跳转至

评测架构

评测系统是运行时旁路，但不是和业务主链路彻底分离的另一套世界。它本质上是在“复用真实 runtime 的前提下，增加数据集、批量执行、裁判、gate 和结果归档”。

顶层结构

flowchart LR
  Dataset[Evaluation Dataset] --> Runner[Evaluation Runner]
  Runner --> Runtime[Chat Runtime / Fusion Runtime]
  Runtime --> Result[Raw Prediction]
  Result --> Metrics[Rule-based Metrics]
  Result --> Judge[LLM Judge]
  Metrics --> Gate[Gate Evaluation]
  Judge --> Gate
  Gate --> Store[(PostgreSQL + MinIO)]
  Store --> Report[Studio Results / Export]

当前组件

组件 关键实现 作用
Dataset Manager evaluation_dataset_importer.py + routers/evaluation.py 导入、冻结、替换 dataset items
Evaluation Runner evaluation_runner.py claim run、worker heartbeat、resume stale run、逐 item 执行
Runtime Adapter build_chat_orchestrator() 等 复用真实 chat runtime 执行评测
Metrics evaluation_metrics.py exact match、token f1 等规则指标
Judge evaluation_judge.py LLM judge prompt 快照与裁判
Gate evaluation_gate.py pass / fail / not evaluated 判定
Result Store evaluations.py dataset、run、result、gate 结果持久化

当前最关键的架构现实

1. 评测复用真实 runtime

当前 runner 不是写死一套 mock 推理逻辑，而是会构建真正的 chat orchestrator runtime。

这意味着：

  • 编排器改动会直接影响评测结果
  • 模型路由、MCP runtime config、response behavior 都会进入评测真实面

2. run 是异步、可恢复对象

AgentEvaluationRun 当前已经不是简单任务表，而是带这些运行状态：

  • lease_token
  • attempt_count
  • worker_heartbeat_at
  • stale run recovery

所以评测执行器是有“任务恢复”和“租约竞争”设计的。

3. gate 不是结果页上的附加标签

evaluation_gate.py 当前会根据：

  • minimum_items
  • score_pass_rate_min
  • score_f1_min
  • max_failed_item_ratio
  • llm_judge_min

去产出结构化 gate decision。

这意味着 gate 已经是 release-readiness 逻辑的一部分。

4. source CSV 与结果状态分层存储

  • dataset 源 CSV 在 MinIO
  • dataset item、run、result、judge snapshot、gate 结果在 PostgreSQL

这保证了导入资产和运行真相源可以分别治理。

当前核心原则

Agent 解耦

同一个评测体系可以评测不同 Agent，而不强依赖某一种业务实现。

Runtime 解耦

评测面向 runtime 输出，不和单一页面或单一产品流程耦死。

数据解耦

dataset、run、result 分层持久化，允许快照与重复执行。

线上离线闭环

评测不是纯离线实验，因为它复用了线上 runtime；但它也不是线上请求旁路复制，因为 run、judge、gate、export 都是独立控制面。

当前最值得关注的架构连接点

连接点 作用
编排器 决定真实输出路径
Agent version snapshot 保证 run 可复现
model routing config snapshot 解释结果为什么变化
judge prompt snapshot 解释裁判标准
gate policy snapshot 解释通过 / 不通过依据

读代码建议

想理解 run 为什么卡住

  1. ai_service/services/evaluation_runner.py
  2. claim_agent_evaluation_run
  3. heartbeat / stale recovery 相关逻辑

想理解 gate 为什么失败

  1. ai_service/services/evaluation_gate.py
  2. run 上的 score / failed item count

想理解 judge 为什么和规则指标冲突

  1. ai_service/services/evaluation_judge.py
  2. ai_service/services/evaluation_metrics.py

相关页面