评测架构蓝图 v1
本文档定义 AI Agent 平台评测体系的长期架构，目标是同时解决两个核心问题：
- 看不见过程：无法系统追踪 RAG 抓取内容、重排序结果、最终上下文与生成行为。
- 无法比较效果：缺少统一基准，无法在相同数据集上比较不同 Agent 或不同版本。
本文档聚焦统一评测底座设计，支持对话型 Agent 与非对话型 Agent。首期优先覆盖知识问答与 OCR 提取任务。
在当前实现中，聊天 Agent 已支持 orchestrator_key 运行时切换，并支持可选 model_routing_config 角色化模型路由。因此评测体系除了比较 Agent 自身，也需要比较同一 Agent 在不同聊天运行时、不同路由策略下的表现。实验运行时必须通过评测门禁后才能考虑晋升为默认值。
1. 代码资产盘点
1.1 入口与运行
- 主入口：
main.py - AI 服务入口：
ai_service/main.py - API 启动入口：
ai_service/api/entrypoint.py - 文档构建入口：
mkdocs.yml
1.2 核心逻辑
- 编排图：
ai_service/orchestrator/graph.py - 编排状态：
ai_service/orchestrator/state.py - RAG 检索：
ai_service/services/rag_retrieval.py - 重排序：
ai_service/services/rerank.py
1.3 数据层
- 存储模型：
ai_service/storage/models.py - 数据迁移：
ai_service/migrations/versions/ - 向量检索：
ai_service/storage/qdrant_client.py
1.4 配置与环境
- 依赖声明：
pyproject.toml - 运行配置：
config.toml与.env.example - 工程命令：
justfile
2. 架构目标
2.1 业务目标
- 统一记录 Agent 执行轨迹，完整还原每次任务过程。
- 统一离线评测基准，在同一数据集上对比 Agent 效果。
- 统一线上质量观察，支持持续优化与回归预警。
2.2 设计原则
- Agent 解耦：评测不依赖具体 Agent 实现。
- 任务解耦：评测指标按任务类型插件化扩展。
- 数据解耦：评测运行与业务数据写入分离。
- 线上离线闭环：离线做对比，线上做监控，统一指标口径。
3. 总体架构
flowchart LR
A[Agent Runtime LangGraph] --> B[Trace Collector]
A --> C[Artifact Collector]
D[Dataset Manager] --> E[Evaluation Runner]
B --> E
C --> E
E --> F[Evaluator Plugins]
F --> G[Metrics Store]
G --> H[Report Service]
H --> I[Leaderboard Dashboard]3.1 核心组件
- Trace Collector：采集节点级过程事件与耗时成本信息。
- Artifact Collector：采集检索候选、重排列表、最终上下文、模型输出。
- Dataset Manager：维护 Bronze Silver Gold 分层数据集。
- Evaluation Runner：按数据集批量执行多个 Agent 版本。
- Evaluator Plugins：任务类型与环节指标插件。
- Report Service：输出可读报告与对比榜单。
4. 统一数据模型
4.1 标准对象
TaskDefinition：任务定义与成功规则。DatasetItem：单条评测样本，包含输入、期望输出与标注。AgentSpec：Agent 标识、版本、参数、能力描述。EvaluationRun：一次批量评测运行。StepTrace：一次运行中的步骤轨迹。Artifact：步骤产物，如候选文档与中间结果。MetricRecord：指标结果，支持 run 级和 item 级。
4.2 最小字段建议
| 对象 | 关键字段 | 说明 |
|---|---|---|
| TaskDefinition | task_type, success_policy, weights | 支持任务差异化成功定义 |
| DatasetItem | item_id, input_payload, expected_output, gold_evidence | 支持 QA 与 OCR 统一 |
| AgentSpec | agent_name, agent_version, runtime_kind, orchestrator_key, model_routing_config, config_hash | 支持横向对比与回溯 |
| EvaluationRun | run_id, dataset_version, triggered_by, started_at | 支持可复现 |
| StepTrace | step_name, step_type, latency_ms, status, error_code | 支持过程诊断 |
| Artifact | artifact_type, content_uri, digest, metadata | 支持过程可视化 |
| MetricRecord | metric_name, metric_value, level, aggregation | 支持多维聚合 |
5. Trace Schema v1
5.1 Run 级字段
run_idtrace_idtask_typeagent_nameagent_versiondataset_namedataset_versionrequest_timetotal_latency_mstotal_token_inputtotal_token_outputtotal_cost_usdroute_modemodel_routing_policy_version
5.2 Step 级字段
step_idparent_step_idstep_namestep_typeinput_summaryoutput_summarystatuslatency_mstoken_inputtoken_outputmodel_namemodel_providermodel_roletool_nameerror_typeerror_message
5.3 关键步骤类型
retrieval_queryretrieval_candidatererank_inputrerank_outputprompt_assemblyllm_generationtool_calltool_resultpostprocess
6. RAG 评测体系
6.1 检索层
- 指标：
Recall@K、Precision@K、MRR、NDCG。 - 过程产物：原始召回候选列表与分数。
6.2 重排层
- 指标：重排前后
NDCG提升、TopK 命中变化、候选位次变化。 - 过程产物：重排输入与重排输出全量保留。
6.3 生成层
- 指标：答案正确性、忠实性、证据一致性、幻觉率。
- 过程产物：最终上下文快照、最终回答、引用证据映射。
6.4 当前代码基线说明
- 检索已具备：
ai_service/services/rag_retrieval.py - 重排已具备接口：
ai_service/services/rerank.py - 当前重排实现以确定性排序兜底，需在评测中与后续真实重排能力对比验证。
7. Agent 横向评测体系
7.1 通用指标
- 任务成功率
- 平均时延与 P95
- 单请求成本
- 工具调用成功率
- 错误率与错误类型分布
- 重试率
7.2 任务专项指标
- 知识问答：答案质量、证据覆盖、引用一致性。
- OCR 提取：字段级 F1、字段级 EM、编辑距离、漏提率、误提率。
7.3 排行与对比
- 同数据集同任务类型跨 Agent 对比。
- 同 Agent 跨版本回归对比。
- 同 Agent 不同配置对比。
- 同 Agent / 同数据集下跨
orchestrator_key运行时对比。 - 同 Agent / 同数据集下跨
model_routing_config.policy_version或不同角色模型组合对比。
7.4 运行时切片与发布门禁
chameleon_chat_v1应被视为当前默认基线。langgraph_react_agent_v1等实验运行时应单独形成 runtime slice，而不是与默认运行时混在一起。- 建议最小切片字段：
orchestrator_keyroute_modemodel_routing_policy_versiondataset_idgating_statusexact_match_avgpass_rate_avg- 当前代码已提供
summarize_runtime_evaluation_slices(...)辅助函数，可将 runtime slice 聚合为： - 运行次数
- 门禁通过次数 / 失败次数
- 平均 EM
- 平均 pass rate
- 推荐发布规则：
- 非默认运行时连续通过 Gold 数据集门禁
- 不低于默认运行时的核心质量指标
- 无新增 blocking 错误类型
7.5 当前实现补充
agent_evaluation_runs现已持久化model_routing_config_json，用于快照一次运行采用的角色化模型路由策略。- 若
POST /agents/{agent_id}/evaluation-runs显式提供model_name/model_provider/model_temperature，则本次评测会折叠为单模型路径，model_routing_config_json保持为空。 - Turn 级观测负载中的
model_routing.stage_decisions[]可作为后续评测 trace collector 的直接输入，无需再从最终ConversationTurn.model_*反推中间阶段模型。
8. 数据集建设策略
8.1 分层策略
- Bronze：自动构造样本，用于快速扩量。
- Silver：人工抽检样本，用于稳定迭代。
- Gold：严格标注样本，用于发布门禁。
8.2 首批建议规模
- QA Gold：200 条
- OCR Gold：100 条
- 每周新增 Silver：50 条
8.3 样本字段建议
| 字段 | 说明 |
|---|---|
| item_id | 样本唯一标识 |
| task_type | qa 或 ocr |
| input_payload | 原始输入，如问题文本或图像路径 |
| expected_output | 期望结果 |
| gold_evidence | QA 证据段或 OCR 标准字段 |
| metadata | 业务域、难度、来源等 |
9. 离线与线上闭环
flowchart TB
A[Dataset Gold] --> B[Offline Evaluation]
B --> C[Agent Leaderboard]
C --> D[Release Gate]
E[Online Traffic Sample] --> F[Online Evaluation]
F --> G[Quality Monitor]
G --> H[Issue Queue]
H --> A- 离线评测：用于版本对比与发版门禁。
- 线上评测：用于真实流量质量监控与异常告警。
- 统一口径：线上离线共用同一指标定义与聚合逻辑。
10. LangGraph 接入方案
10.1 接入位置
- Run 开始：进入
ChameleonOrchestrator执行前创建run_id。 - Node 执行前后：记录
StepTrace与Artifact。 - 结束时：汇总 run 级指标并写入评测存储。
- 当前代码基线已增加一个外部观测桥接：
ai_service会在保留内部trace_id/SQL 观测的同时，可选地把同一 trace 导出到 Langfuse，用于线上排障与链路回放。
10.2 接口建议
class TraceCollector:
def start_run(self, run_context: dict) -> str: ...
def start_step(self, run_id: str, step_context: dict) -> str: ...
def end_step(self, run_id: str, step_id: str, step_result: dict) -> None: ...
def emit_artifact(self, run_id: str, artifact_payload: dict) -> None: ...
def end_run(self, run_id: str, run_result: dict) -> None: ...
11. 模块落地建议
建议新增目录：
ai_service/eval/
├── adapters/
├── collectors/
├── datasets/
├── evaluators/
│ ├── rag/
│ ├── qa/
│ └── ocr/
├── runner/
├── reports/
└── schemas/
12. 实施路线图
12.1 Day 1 可交付
- 评测架构蓝图文档与字段规范。
Trace Schema v1与Dataset Schema v1。- MVP backlog 与优先级标注。
12.2 四周落地节奏
- 第 1 周：LangGraph 全链路打点，完成 Run 与 Step 基础落库。
- 第 2 周：RAG 评测插件，落地检索与重排评测。
- 第 3 周：QA 与 OCR 任务评测插件，支持多 Agent 横向对比。
- 第 4 周：线上抽样评测与回归门禁，输出周报与告警机制。
13. 验收标准
13.1 可观测性
- 任意一次请求可回放完整 RAG 过程。
- 可查询召回候选、重排结果、最终上下文。
13.2 可比较性
- 可在同一数据集上生成多 Agent 排行榜。
- 可追踪同 Agent 不同版本性能变化。
13.3 可扩展性
- 新增任务类型仅需新增
TaskDefinition与对应Evaluator。 - 不修改核心 Runner 即可挂载新 Agent。
14. 风险与缓解
| 风险 | 影响 | 缓解策略 |
|---|---|---|
| 标注成本高 | Gold 集增长慢 | Bronze Silver Gold 分层推进 |
| 评测口径漂移 | 横向对比失真 | 指标定义集中管理与版本化 |
| 线上数据噪声 | 监控误报 | 采样策略与阈值分层 |
| 轨迹数据膨胀 | 存储与查询压力 | 分级留存与摘要归档 |
15. 下一步建议
- 优先实现
TraceCollector与EvaluationRunner骨架。 - 优先构建 QA 与 OCR 的 Gold 数据样本导入流程。
- 以离线评测先打通可比较能力，再补齐线上抽样评测闭环。