把 AgentScope Harness 装进 RuoYi-Vue-Plus这句描述乍一听挺拧巴AgentScope 生态里的 Harness 是 Python 那套多智能体评测组件RuoYi-Vue-Plus 又是 Java 系后台管理界的常青树两者语言不通、定位也不一样。但正是这种“拧巴”才值得写一篇文章——它代表了一类很真实的需求公司已经有了成熟的管理后台、账号体系、权限框架现在想在上面长出 AI Agent 的评测、管理和审计能力又不想推翻现有 Java 工程去重建一个 Python 平台。所谓“纯 Java AI 平台”指的不是让 Java 去执行大模型推理而是让 Java 后端负责调度、存储、权限与审计让 Python 侧的 AgentScope Harness 专心干评测的活。这篇文章就是我自己实操这条路的完整记录适合正在用 RuoYi-Vue-Plus 做支撑系统、手里握着一堆 Agent 场景却苦于没有评测管理界面的团队参考。1. 兼容层思维AgentScope Harness 和 RuoYi 各自该干什么1.1 Harness 带来的不是“评分”而是“场景编排”很多人一听到 Harness 就以为是套测试框架无非跑几个用例然后算通过率。实际用过之后你会发现它真正的价值是把多智能体评测里的脏活累活标准化了一个评测场景包含用户角色定义、交互轮次上限、环境工具的模拟、终止条件、指标采集点等等。你自己用脚本写写到后面往往变成“为了这套场景的代码快比被测 Agent 本身还复杂”。Harness 帮你把这些编排逻辑收敛成场景配置和数据记录然后替你产出结构化结果任务是否完成、工具调用是否正确、对话轮次、耗时、失败时卡在哪一步。这是团队在做 Agent 质检时最缺的东西。但问题也在这里——Harness 的默认使用方式偏向命令行和 Python 脚本是个“实验室工具”不是“管理平台”。相当于引擎很好却没有仪表盘和方向盘。1.2 RuoYi-Vue-Plus 在这个平台里扮演的角色RuoYi-Vue-Plus 这套框架强在工程底座用户与角色权限、菜单管理、操作日志、定时任务、代码生成开箱即用。公司里很多内部系统都是基于它二次开发的运营、算法、测试同学的账号和权限早就沉淀在里面。如果为了 AI 评测再单独搭一个前端加一套登录体系等于把已经有的地基推倒重来。所以我的判断是RuoYi 侧只做三件事——把评测任务当作业务数据进行管理、把 Python 服务当作一个不可见的执行引擎来调度、把评测结果转成报表和明细给业务方看。AgentScope Harness 的命令行能力全部封装在 Python 服务进程里对 Java 侧暴露的只是一组 REST 接口。两边各管各的Java 不需要 import 任何 Python 库Python 也不需要知道 RuoYi 的权限模型。1.3 一个典型的使用闭环我们当时的闭环是这样算法同学写好 Agent 配置后在 RuoYi 的管理页面里发起一次评测任务选择目标场景集和 Agent 版本提交后 Java 后端落库并调用 Python 服务。Python 侧把评测任务丢进线程池异步跑跑完后把 JSON 结果返回Java 轮询到结果后写入业务表前端展示通过率、工具准确率、失败样例。整个过程中测试人员只跟 Vue 页面打交道完全感觉不到背后还有个 Python 引擎。这就是“纯 Java 平台”对使用者的意义——技术栈边界藏在内部体验是统一的。2. 技术选型与架构边界为什么用 HTTP 而不是 MQ 或 gRPC2.1 服务拆分与部署拓扑先明确部署形态。Python 评测服务作为独立进程跑在一台内网机器或容器上和 RuoYi 后端服务通过网络互通两边都不需要暴露公网端口。数据库仍然只有 RuoYi 在写Python 服务不直接碰 MySQL评测中间状态先落在自己的内存和临时文件里最终结构化结果通过接口返回给 Java 侧落库。Redis 两边共用但用途很克制Java 侧用 Redisson 做并发控制和分布式锁Python 侧可以用来做任务去重和简单的状态缓存。这样的拓扑有一个好处Python 服务挂掉不影响 RuoYi 主流程任务状态停在“执行中”重试或重启后可以重新提交反过来 RuoYi 重启也不影响正在跑的评测评测完的结果在 Python 侧临时文件里等着被再次拉取。2.2 三种通信方案的取舍做方案评审的时候组里有人提议上 RabbitMQ也有人提出 gRPC 性能更好。我把三种方案放在一起对比过最终选了最朴素的 REST。选择逻辑是这样的方案优势成本与问题REST over HTTP两边都自然支持JSON 调试直观curl 就能验证长任务需要轮询或回调语义朴素消息队列天然异步、削峰任务提交即忘需要多维护一套中间件结果回传仍要接口配合排查链路多一跳gRPC强类型契约、性能好、流式支持强proto 维护和跨语言生成代码麻烦联调时抓包不像 HTTP 那么直观关键是看调用模式Java 侧每次提交评测任务时需要立刻知道“这个请求有没有被接受”这本质上是请求/响应语义不需要事件总线。评测任务虽然耗时长但并发量不大峰值也就几十个任务队列带来的削峰价值发挥不出来。gRPC 的性能优势在这种低频任务下根本体现不出来反而让 Java 和 Python 两边的依赖管理变复杂。REST 虽然“无聊”但足够稳出了故障也容易定位这就是我当时选它的理由。2.3 调用链路的完整时序整个调用流程固定成四个阶段提交、查询、拉取、落库。提交阶段Java 生成业务任务编号插入一条状态为“等待中”的记录再调用 Python 的创建任务接口。Python 接口只做两件事校验 API Key、把任务放进线程池然后立刻返回一个任务 ID。这个接口必须快我给它设的 Java 侧超时是 5 秒。查询阶段Java 用一个异步线程或者 Spring 的 Async每隔 2 秒轮询一次 Python 的任务状态接口最多轮询到任务变为 SUCCESS 或 FAILED。轮询的好处是 Python 侧不需要实现回调Java 侧也不怕回调地址配错。拉取阶段状态成功后 Java 调用结果接口拿到完整的评测 JSON解析后拆成指标表和明细记录入 MySQL。最后把任务状态改成成功前端看到的就是一份可查询的评测报告。3. Python 侧改造把 Harness 包装成可被 Java 调用的服务3.1 环境准备与依赖Python 侧我建议用 3.10 或以上版本创建独立虚拟环境避免污染机器上其他 Python 环境。依赖就三类AgentScope 本体、AgentScope Harness、FastAPI 和 Uvicorn。安装命令没什么特别的唯一要注意的是版本锁定——Python 这边依赖升级很频繁评测结果格式可能随版本变化所以我把核心依赖写死在小版本范围防止某天升级后 Java 侧解析 JSON 出问题。评测场景的配置放在独立目录里每个场景一个 JSON 文件里面包含场景名称、用户模拟器配置、最大轮次、可用工具列表和终止条件。Java 侧提交任务时只需要传场景 IDPython 侧自己去目录加载配置这样双方约定的数据结构尽量小依赖面就窄。3.2 接口协议设计我给 Python 服务设计的接口一共五个全部带 x-api-key 请求头校验方法路径说明GET/api/v1/scenarios返回可用场景列表供 RuoYi 页面下拉选择POST/api/v1/tasks创建评测任务立即返回 task_idGET/api/v1/tasks/{task_id}查询任务状态与进度GET/api/v1/tasks/{task_id}/result拉取评测结果 JSONPOST/api/v1/tasks/{task_id}/cancel取消正在等待或运行中的任务任务状态统一用字符串枚举PENDING、RUNNING、SUCCESS、FAILED、CANCELED。这里有个细节Python 返回的状态枚举最好和 Java 侧的字典表对齐别各写各的缩写否则联调时光翻译状态就够折腾。3.3 异步执行与状态保持Harness 本身的评测过程是同步阻塞的给一个场景配置跑若干轮对话收集指标输出结果。所以服务化改造的核心就一句话把同步调用包进线程池让 HTTP 接口立刻返回。我用的 ThreadPoolExecutor线程数按机器核数和模型 API 的限流情况配置一般 4 到 8 个。每个任务在提交时拿到一个 UUIDPython 侧维护一个任务状态字典key 是 task_idvalue 是状态和关联的临时文件路径。评测线程跑完后把结果写进临时 JSON 文件把状态改成 SUCCESS。这个设计很朴素但够用。需要注意一个致命点进程重启后内存里的任务状态全没了。所以生产上我在 Python 侧把任务状态定期同步到 Redis启动时如果发现 Redis 里有未完成任务就标记为 FAILED 并记录原因“服务重启导致中断”让 Java 侧可以感知并提示用户重跑。3.4 关键代码骨架from fastapi import FastAPI, Header, HTTPException from pydantic import BaseModel from concurrent.futures import ThreadPoolExecutor import uuid, json, pathlib app FastAPI() executor ThreadPoolExecutor(max_workers4) API_KEY 在这里配置和Java侧一致的密钥 class TaskRequest(BaseModel): scenario_id: str agent_config: dict user_proxy_config: dict | None None def run_eval(task_id: str, req: TaskRequest): # 这里调用 agentscope_harness 的评测入口 # 将结果写入 /tmp/eval_results/{task_id}.json # 完成后更新 task_states[task_id] SUCCESS pass app.post(/api/v1/tasks) async def create_task(req: TaskRequest, x_api_key: str Header(...)): if x_api_key ! API_KEY: raise HTTPException(status_code401) task_id str(uuid.uuid4()) task_states[task_id] PENDING executor.submit(run_eval, task_id, req) return {task_id: task_id, status: PENDING} app.get(/api/v1/tasks/{task_id}) async def get_task(task_id: str, x_api_key: str Header(...)): state task_states.get(task_id) if state is None: raise HTTPException(status_code404, detailtask not found) return {task_id: task_id, status: state}实际跑评测的函数里记得把 Harness 的日志级别调低否则每个任务动辄打几百行日志排查问题的时候有用的信息全被淹没了。4. RuoYi-Vue-Plus 侧落地表结构、服务封装与权限控制4.1 后端表设计与 MyBatis-Plus 实体RuoYi-Vue-Plus 的特点是 MyBatis-Plus 加代码生成所以我先建了两张表然后用代码生成器生成实体和 Mapper省掉大量手写 CRUD。create table ai_eval_task ( id bigint primary key, task_no varchar(32) not null comment 业务任务编号, scenario_id varchar(64) not null comment 场景ID, agent_version varchar(64) comment Agent版本标识, status varchar(16) not null comment PENDING/RUNNING/SUCCESS/FAILED, progress int default 0 comment 进度0-100, create_by varchar(64), create_time datetime, finish_time datetime, unique key uk_task_no (task_no) ) engineInnoDB default charsetutf8mb4 comment 评测任务表; create table ai_eval_result ( id bigint primary key, task_id bigint not null, task_no varchar(32) not null, metrics_json json comment 指标汇总JSON, detail_json json comment 逐轮对话与工具调用明细, raw_report_path varchar(255) comment Python侧原始报告路径, create_time datetime ) engineInnoDB default charsetutf8mb4 comment 评测结果表;表设计上要克制不要试图把所有指标都拆成独立字段因为不同场景的指标集差异很大。把指标汇总放进 JSON 字段用 MyBatis-Plus 的 JacksonTypeHandler 做自动序列化查询展示时再按前端需要解析比维护一张属性松散的宽表靠谱得多。4.2 调用 Harness 的服务层封装Java 侧我直接用 Hutool 的 HttpRequest 封装 HTTP 调用理由很简单项目里本来就用 Hutool不需要再引一个 HTTP 客户端依赖。创建任务的代码大概长这样public AiEvalTask createAiEvalTask(AiEvalTaskDTO dto) { String taskNo IdUtil.getSnowflakeNextIdStr(); AiEvalTask task new AiEvalTask(); task.setTaskNo(taskNo); task.setScenarioId(dto.getScenarioId()); task.setStatus(PENDING); // 先落库保证业务上有据可查 aiEvalTaskMapper.insert(task); MapString, Object body new HashMap(); body.put(scenario_id, dto.getScenarioId()); body.put(agent_config, dto.getAgentConfig()); String resp HttpRequest.post(agentScopeUrl /api/v1/tasks) .header(x-api-key, agentScopeApiKey) .body(JSONUtil.toJsonStr(body)) .timeout(5000) .execute().body(); String pyTaskId JSONUtil.parseObj(resp).getStr(task_id); // 更新本表保存python侧任务ID后续轮询用它 task.setPyTaskId(pyTaskId); aiEvalTaskMapper.updateById(task); return task; }轮询逻辑放在独立的异步方法里用 Async 注解提交任务后立即触发。Java 侧轮询要设置上限我设的 30 分钟超过后把任务标记 FAILED原因写“评测超时”。这个兜底非常重要否则 Python 侧线程卡死时 Java 侧会永远挂着一个“运行中”的任务。4.3 鉴权与安全边界处理既然叫平台权限就不能漏。RuoYi-Vue-Plus 的控制器上加 SaCheckPermission 注解只有拥有对应权限的账号才能创建评测任务、查看结果、取消任务。同时Python 服务的 URL 和 API Key 只配置在 Java 后端的配置中心/配置文件里前端永远不可能直接拿到。这样即便有人抓到了整条接口链路也只能看到 RuoYi 的受控接口而 Python 服务不监听对外网卡内网也要求来源 IP 在白名单内。还有一个容易被忽略的点操作日志。RuoYi 自带的日志注解 Log 可以直接记录谁在什么时间发起了哪个评测场景这是合规审计需要的。AI 平台的评测会涉及模型输出内容必须有“谁跑过什么”的痕迹别等出了问题再补。5. 联调阶段最值得记录的四个坑5.1 JSON 类型差异Python 的 None、NaN 与 Java 的严格解析第一次联调就翻车在数据类型上。Python 里 float(nan) 在 json.dumps 时默认会输出 NaNFastAPI 序列化响应时也可能带出这种值而 Jackson 在解析 JSON 里的 NaN 时直接抛异常。评测指标里恰好就有这类数据——某个工具调用的耗时异常时Python 侧代码写的是 float(nan) 占位。解决办法是两件事同时做Python 侧在写入 JSON 前把 NaN 统一替换成 nullJava 侧给 ObjectMapper 开启允许 NaN 的配置作为最后一道防线。另一个高频问题时间格式。Python 的 datetime 序列化默认是 ISO 8601 字符串带 T 和时区后缀Java 的 LocalDateTime 默认解析需要指定格式。与其在两边反复调格式不如在 Python 侧统一转成 yyyy-MM-dd HH:mm:ss 这种字符串Java 侧按同一个格式解析谁都不占谁便宜。5.2 长耗时任务的超时、轮询与幂等控制创建任务接口可以快但评测本身经常要跑几分钟。刚开始我把 Java 侧 HTTP 超时设置成 30 秒于是每次跑超过 30 秒的任务Java 这边就报 SocketTimeoutException可 Python 那边任务其实还在跑。后来我定了两条规矩所有“提交”类接口 Java 侧超时控制在 5 秒以内因为提交动作本身不该慢所有“查询、拉取”类接口超时放宽到 30 秒因为涉及文件读取和状态检查。评测执行一律异步绝不让 HTTP 请求长时间占着连接等待评测完成。幂等控制同样重要。用户手滑点了两次提交产生两个重复评测任务白费算力不说结果还会打架。我在 Java 侧用任务编号的唯一索引加 Redisson 的分布式锁做防重同一个业务单号在 Redis 锁未释放前第二次提交直接提示“任务已存在”。Python 侧也做了对账逻辑同一个 agent_version 加 scenario_id 在短时间窗口内重复提交时直接复用已有结果。5.3 并发评测的资源争抢问题线程池的 max_workers 不是越大越好。我们压测发现8 个并发评测同时跑时如果每个评测都再调用同一个外部模型 API很快会触发限流表现为大量任务失败。后来把线程数降到 4并且加了一个简单的令牌桶每秒最多允许两个评测任务真正进入 Harness 执行其余在队列里等待。模型 API 的限流策略各家不一样务必提前问清楚你的模型供应商每秒允许多少请求然后据此设置评测并发别等到一堆 FAILED 再排查。机器资源也要观察。Harness 评测过程不算太吃显存因为推理都在模型服务那边但 CPU 内存占用还是有的。每个评测任务至少预留 1GB 内存多轮对话的上下文一旦拉长内存会涨得很快。建议给 Python 服务加一个简单的内存监控接口超过阈值时停止接收新任务返回 503 让 Java 侧提示用户稍后再试。5.4 Vue 前端的“假实时”刷新RuoYi-Vue-Plus 的前端是 Vue 3任务列表页需要展示运行状态。最开始后端同学说“你刷新一下页面就有了”但测试同学用起来非常痛苦。我的做法是在任务详情页加一个轮询定时器每 3 秒调一次查询接口组件卸载时记得清掉定时器。这个方案成熟简单比上 WebSocket 省事得多评测任务本来就不是高实时场景3 秒的延迟完全无感。6. 实测效果与还能怎么往深做6.1 一次内部评测的实测数据整套链路跑通后我们拿一个内部的知识库问答 Agent 做了一次完整评测48 个场景12 种 Agent 配置总计 576 个任务分批串行执行约 40 分钟全部跑完。结果是任务完成率 86%工具调用准确率 79%平均单轮响应耗时 2.8 秒。最有价值的不是这三个数字而是 Harness 输出的失败明细帮我们定位到了三个共性问题有两个场景的终止条件设置太苛刻、一个工具的参数校验逻辑在 Agent 传错格式时不给第二次机会、一个 Prompt 模板在长上下文时出现重复追认现象。这些问题之前靠人工测试根本没发现。6.2 值得继续做的方向第一个方向是流式化。现在评测过程是“跑完才能看结果”如果改用 SSE 把对话过程实时推给前端测试同学能边跑边看 Agent 的表现对问题场景的理解会深很多。第二个方向是定时评测。RuoYi 自带 Quartz 定时任务完全可以配置成每晚自动跑一遍核心场景集第二天上班直接看通过率变化趋势相当于给 Agent 上了“夜间自动质检”。第三是把评测结果回传 Agent 的开发流程让算法同学每次改完 Prompt 都能先跑一轮回归减少“改一处坏一片”的回归事故。最后说一句我自己的体会这套集成里最难的从来不是技术而是忍住不要把事情做复杂。Python 和 Java 之间不需要追求“深度集成”一条 REST 接口加上明确的数据结构已经足够让两个生态各司其职、和平共处。等哪天评测场景真多到撑不住 HTTP 轮询了再考虑换更重的方案也不迟。