跳转至

评测运行生命周期

本页回答“一个 evaluation run 从排队到完成，中间到底经历了什么”，重点是 lease、heartbeat、stale recovery、judge 和 gate 如何串起来。

生命周期

  1. 选择数据集版本
  2. 选择 Agent / runtime / policy 组合
  3. 创建 queued run
  4. worker claim lease 并进入 RUNNING
  5. 分批执行 dataset items，持续写 heartbeat
  6. 持久化 item result、judge、指标和 gate
  7. 汇总 run 级结果并结束
  8. 若 worker 掉线，supervisor 负责 stale recovery

当前状态机

QUEUED

表示 run 已创建但尚未被 worker 领取。此时可以是：

  • 首次等待执行
  • 失败恢复后重新入队

如果 attempt_count > 0 但仍是 QUEUED，前端应把它理解为 recovering，而不是纯新任务。

RUNNING

表示某个 worker 已 claim 当前 run，并持有 lease token。

运行中会持续更新：

  • worker_heartbeat_at
  • started_at / last_attempt_started_at
  • progress counters

COMPLETED

表示 item 执行、judge、指标和 gate 都已经落盘，run 级聚合也完成。

FAILED

表示 run 本轮执行终止，且没有被自动恢复为 QUEUED。

关键运行机制

1. Claim lease

worker 不会无锁抢任务，而是通过 claim_agent_evaluation_run() 获取 lease。

这意味着排查“同一个 run 被重复跑”时，先查 lease 语义，而不是怀疑 API 重复触发。

2. Heartbeat

worker 在处理 item 过程中会周期性调用 touch_agent_evaluation_run_heartbeat()。

heartbeat 是当前系统区分“还在跑”和“已经失联”的核心信号。

3. Stale recovery

supervisor 会按固定周期调用 requeue_stale_agent_evaluation_runs()，把长时间没有 heartbeat 的 RUNNING 任务重新放回 QUEUED。

这也是为什么 evaluation run 可能出现：

  • 状态从 RUNNING 回到 QUEUED
  • attempt_count 增长
  • 前端表现为 recovering

4. Item 结果持久化

每个 dataset item 的执行结果会单独通过 create_agent_evaluation_result_record() 落盘。

所以 run 中途失败时，通常不是“完全没有结果”，而是可能已经有部分 item result。

5. Judge 与 Gate

run 完成 generation 后，还会额外写入：

  • judge prompt / model snapshot
  • judge score
  • gate policy snapshot
  • gate status

这保证结果可解释，而不是只剩一个 pass/fail。

为什么它和编排器有关

离线评测会复用真实聊天运行时或其他执行内核，因此这些差异都会影响 run 解释：

  • orchestrator key
  • model routing
  • MCP runtime config
  • response behavior
  • grounding 策略

如果这些配置不进入 run 快照，评测结果无法对比。

常见症状与动作

Run 一直停在 QUEUED

先看：

  1. worker / supervisor 是否在运行
  2. 是否能成功 claim lease
  3. 数据集 item 数量是否为空

Run 显示 RUNNING 但前端像卡住

先看：

  1. worker_heartbeat_at 是否持续更新
  2. 是否已经进入 heartbeat expired
  3. 当前 item 是否卡在 generation / judge 阶段

Run 反复从 RUNNING 回到 QUEUED

优先怀疑：

  1. worker 进程不稳定
  2. heartbeat 没有按周期写入
  3. stale seconds 过短

Run 完成了，但 gate 为空

先看：

  1. 是否执行了 update_agent_evaluation_run_gate()
  2. gate policy 是否为空
  3. judge 或 rule-based score 是否缺失导致 gate 无法判定

代码入口

路径 作用
ai_service/services/evaluation_runner.py run worker、heartbeat、stale recovery、聚合主逻辑
ai_service/services/evaluation_judge.py judge prompt 与裁判执行
ai_service/services/evaluation_gate.py gate 判定逻辑
ai_service/storage/model_domains/evaluations.py lease、状态更新、结果落盘
ai_service/api/routers/evaluation.py run 创建、列表、导出、详情

运维上最重要的三个字段

  • status
  • worker_heartbeat_at
  • lease_token

如果这三个字段读不明白，基本就解释不了 run 为什么卡住、为什么恢复、为什么看起来被重复执行。