AI Agent 全链路评测体系方案与实测开发调研报告

摘要摘要与核心结论

本方案面向当前 Agent 业务在 链路可观测、耗时归因、效果评测、BadCase 沉淀与迭代验证 上的缺失，以 LangFuse 全链路埋点 + 分层数据存储 + Java 后端与网关 + 前端可视化 为底座，构建一套能自动采集、自动评测、自动出报告、异常自动派单复检的 AI 评测平台。

一整体架构与采集链路

评测数据统一来自 LangFuse 链路埋点：Agent 任务执行完成后，通过 Webhook 推送 Trace / Span 数据，清洗后按类型分层入库，后端与网关承接业务，前端可视化大盘与人工复检闭环兜底。

二数据特性与选型决策

2.1LangFuse 输出数据的特性

• 类型混合：既含结构化字段（TraceID、耗时、token、状态码、AB 分组），也含半结构化大文本（Prompt、模型回复、工具入参、RAG 召回片段），还有任务回放所需的分步状态快照。
• 写入追加为主：一条 Trace 生成后基本只增不改，批量评测时有写入峰值。
• 查询两极化：高频按 TraceID 单点查询（任务回放、BadCase 详情），低频做聚合统计（均耗时、失败率、各环节占比、Token 成本）。

2.2数据库选型：分层存储，不单库硬扛

2.3后端与网关选型

评测平台面向评测人员多人并发使用，正式生产主后端选择 Java SpringBoot（高并发、生态成熟、分布式与网关体系完善）；LangFuse 数据拉取与清洗用 Python 脚本 单独承担，两者共存不二选一。需引入 网关（Spring Cloud Gateway / Kong）做限流、鉴权 RBAC、路由转发、熔断降级，防止批量回归任务打崩数据库，并统一透传 TraceID。

2.4系统边界与数据共享（与通用知识库底座协同）

评测平台不单独生产知识库能力，与现有「通用知识库底座」形成「生产 + 观测」双层架构：底座负责知识库管理与业务运行，评测平台负责跨业务线的链路观测与质量治理。两者 JWT 鉴权体系对齐，共享同一批基础数据表。

2.4.1 客户分层与交付形态

2.4.2 两套系统与 JWT 对齐

• 通用知识库底座：负责文档解析、知识库管理、问答应用、内置实时 RAG 自校验任务链；运行产生 Trace，写共享库。
• AI Agent 评测平台（本 PRD）：消费共享库 Trace 数据，完成五维评测、RAG 评测、Token 监控、任务回放、工单闭环、AB 实验。
• JWT 对齐：两系统使用同一套账号体系与 JWT 签发密钥，跨系统免登录切换；权限模型（RBAC）各自维护。

2.4.3 共享表与专属表划分

2.4.4 多业务线接入（任务链场景）

评测平台按 Trace 维度通用接入，不绑定单一业务。凡业务侧输出标准 Trace（LangFuse 协议），均可接入评测：

2.4.5 数据流转链路（总览）

两套系统通过共享库完成数据流转：底座运行期写入 Trace，评测平台只读消费并回写自身评测结果，JWT 对齐保障跨系统免登录。

底座（Agent/RAG 应用运行）
    │
    │ 写入
    ▼
共享库 trace_main（Trace 埋点落库）
    │
    │ JWT 对齐（同一套账号体系，免登录）
    │ trace_id 关联
    ▼
评测平台
    │
    │ 直接 SELECT 共享表
    ▼
拿到 Trace 数据 → 跑评测 → 评测结果写自己的表

三AI 端到端评测（实测）

评估"Agent 任务链路本身是否合理"，含 五维质量指标 + 反思次数 + 延迟。五维中仅"回答忠实度"走 RAGAS LLM 打分，其余四维从链路埋点直接统计。

3.1关键结论

• 任务完成度是短板：平均 3.42、通过率仅 42%，明显低于其余四维（83%~92%），说明链路经常未跑完目标，优先排查 Agent Loop 与子任务编排。
• 回答忠实度存在天花板：逐条明细中 12 用例恒为 4 分，评分区分度有限，需放宽档位或改用更细的 RAGAS faithfulness 子项。
• 反思次数只出现在异常场景：仅越权检测用例（error Agent）触发 1 次反思，其余均为 0，可作为链路行为与安全边界评测信号。

四RAG 检索与生成评测（实测）

评估检索召回质量与回答内容质量，分为 检索层指标（纯统计）与 生成层指标（RAGAS LLM 打分）。

4.1关键结论

• Recall@3 是唯一短板（0.60）：top3 中约 40% 相关文档未召回，且逐条明细 12 用例恒为 0.6，属系统性召回覆盖不足，而非排序错误（Hit@1=1.0）。优化方向：调大召回数量、加重排、优化 chunk 切分粒度。
• Answer Relevancy 有区分度（0.8793 且逐条波动 0.636~0.98）：是未到天花板的 LLM 打分指标，适合作为 RAGAS 优化抓手。
• 耗时异常点：pre_01 用例耗时 1485.5ms，其余均 43~65ms，慢约 20 倍，疑似首次冷启动 / 缓存未命中，需单独复检。

五自动评测报告与人工复检闭环

对标工业巡检机器人"自动识别异常上报、人工复核"模式：系统自动识别异常链路，自动生成复检工单，评测人员经任务回放复核确认后沉淀 BadCase。

1. 自动判定：按规则识别超时、工具调用失败、输出格式错误、RAGAS 分数低于阈值、Token 突增。
2. 自动动作：命中规则即生成复检工单（绑定 TraceID，一键跳转任务回放），并按项目/版本/AB 分组自动产出评测报告（支持定时或手动）。
3. 人工复核：评测人员打开任务回放复现全流程，标注真实 BadCase、填写根因与优化建议，工单闭环。
4. 沉淀联动：BadCase 自动纳入回归测试用例库，结合 AB 测试完成版本迭代验证。

六待优化项与下一步

七前端技术选型

平台面向评测人员多人在线使用，核心是 实时数据看板、链路查询、任务回放与工单管理。前端选型需同时考虑框架与实时数据推送通道两层。

7.1选型结论：Vue3，不做 Flutter

7.2实时性方案：SSE + WebSocket，而非框架决定

实时性关键在数据推送通道，不在框架。数据由 LangFuse Webhook 进后端，再由后端实时推给前端：

• SSE（服务端单向推送）：用于指标看板实时刷新，成本低、自动断线重连，适合监控大盘、告警计数、评测进度这类单向指标。
• WebSocket（双向）：用于任务回放、实时链路展示等需要前后端交互、主动请求后续数据的场景。
• 性能兜底：看板实时性的瓶颈在数据预聚合，不在框架。TDengine 预聚合指标，前端只读聚合结果，配合 SSE 推送，多人同时看大盘无压力。

八PRD 开发缺口与立项清单

本方案可作为 PRD 起点进入开发，但需补齐以下缺口后方可正式立项交付研发。

九功能需求明细

按模块拆解为可直接开发的用户行为规则，覆盖评测平台全部核心链路。

9.1数据采集与接入

• LangFuse 接入：Agent 执行完成后，通过 Webhook 接收 Trace / Span 数据。
• 清洗分流：Python 脚本消费 Webhook，拆分为结构化字段、大文本快照、聚合指标三类，分别写入 MySQL / MongoDB / TDengine。
• TraceID 贯穿：所有环节以 TraceID 关联，支持一键溯源完整链路。

9.2评测看板（大盘）

• 实时指标：成功率、平均耗时、各环节耗时占比、Token 消耗、慢请求 TOP，SSE 实时推送刷新。
• 维度筛选：按项目、版本、AB 分组、时间范围、Agent / 场景筛选。
• 告警展示：超时、失败率、Token 突增等阈值告警实时计数与列表。

9.3链路查询与任务回放

• 链路查询：按 TraceID 或条件检索，查看每一步 Span 的耗时、输入输出、状态、错误原因。
• 任务回放：WebSocket 实时推送，按时间序回放 Agent 全流程，复现 BadCase。

9.4人工复检工单

• 自动派单：命中异常规则（超时、失败、RAGAS 低分等）自动生成工单，绑定 TraceID。
• 人工复核：评测人员打开任务回放复现，标注真实 BadCase、填写根因与优化建议，工单闭环。

9.5BadCase 与回归

• BadCase 库：沉淀真实 BadCase，支持打标、关联 Prompt / 模型版本。
• 回归验证：BadCase + 基准用例组成测试集，版本迭代自动批量评测并对比指标。

9.6AB 测试

• 分流：同一用户请求按分组分流至不同 Prompt / 检索 / 模型版本。
• 对比：统计两组的耗时、失败率、RAGAS 分数、BadCase 数，自动对比报表。

9.7报告与权限

• 自动报告：按项目 / 版本 / AB 分组自动产出评测报告（支持定时与手动），可导出。
• 权限 RBAC：不同评测人员按角色访问对应项目与数据，网关统一鉴权。

十里程碑与排期

分三阶段交付，每阶段可独立上线验证。

十一接口定义

核心 API 清单与字段约定，供后端与前端联调。

11.1鉴权与安全

• 所有 API 经网关统一鉴权，基于 OAuth2 / JWT，按 RBAC 控制访问。
• 内部接口（Webhook、SSE）与外部接口（看板、工单）路由分离，内网白名单。

十二非功能需求

十三数据库表结构与评测接口设计

本章为 AI 端到端评测与 RAG 评测补齐 具体数据表结构 与 评测专用接口，供后端建表与前端联调直接使用。所有评测结果均以 TraceID 关联 LangFuse 主链路。

13.1三大评测体系总览

本平台的评测能力由三大并列的评测对象构成，各自独立存储、独立评测、前端分模块展示，均以 TraceID 关联 LangFuse 主链路。

13.2AI 端到端评测（agent_evaluation）

13.2.1 表结构

一条 Trace 对应一条 AI 端到端评测记录，存储五维质量指标 + 延迟 + 反思次数。

13.2.2 专用接口

13.3RAGAS / RAG 评测（rag_evaluation）

13.3.1 表结构

一条 Trace 对应一条 RAG 评测记录，存检索层指标与 RAGAS 生成层指标。

13.3.2 专用接口

13.4Token 成本监控

Token 消耗是 成本 / 资源维度，与五维质量指标、RAG 指标（质量维度）分开管理。Token 数据归属主表 trace_main，一次 Trace 对应一条总量记录，评测表通过 trace_id 关联查询，不冗余存储。

13.4.1 主表字段设计（trace_main 新增）

13.4.2 TDengine 聚合指标

定时任务按 project / version / ab_group 聚合 Token 指标，供大盘与 AB 对比：

• Token 总量：按时间段聚合 input / output / total 总量与趋势。
• Token 成本：聚合估算成本，监控成本随版本、流量变化的曲线。
• 单次均值：平均每次对话消耗 token / 成本，对比版本间资源消耗差异。
• P50 / P99：token 消耗分位数，识别资源消耗异常的长对话。

13.4.3 前端展示

• 大盘看板：Token 总量、成本趋势折线图，按项目 / 版本 / AB 分组筛选。
• 单条详情：链路详情页展示本次 Trace 的 input / output / total token 与估算成本。
• AB 对比：两组平均 token 与成本并列对比，判断新版本是否更省资源。

13.4.4 价值与用途

• 成本控制：量化每次对话、每个版本、每个项目的 token 成本，防止成本失控。
• 版本对比：AB / 回归测试时，对比新旧版本的 token 消耗，新版本质量提升但成本翻倍则需权衡。
• 异常识别：token 消耗突增的 Trace 自动告警，定位是否存在死循环、无限制重试、超长上下文等异常链路。
• 归因分析：结合耗时，判断"慢"与"贵"的关联，找出既慢又耗资源的瓶颈链路。
• 定价与预算：为平台向业务方核算资源成本、预估预算提供数据支撑。

13.4.5 专用接口

13.4.6 数据归属与表结构

Token 成本数据归属主表 trace_main，一次 Trace 对应一条总量记录；评测表通过 trace_id 关联查询，不冗余存储。

13.5表关联关系

trace_main（主链路表）为父表，承载一条 Trace 的总链路信息；agent_evaluation 与 rag_evaluation 为子表，一条 Trace 同时存在两类评测记录，分别存储、互不覆盖。

13.6聚合指标与明细（供前端看板）

• TDengine 聚合：定时聚合各项目/版本/AB 分组的五维平均分、通过率、RAG 指标均值、P50/P99 延迟、Token 成本，供大盘实时展示。
• MongoDB 明细：存放评测 prompt、LLM 打分理由、召回原文，详情页展开查看，不占 MySQL。
• Redis 缓存：热门 TraceID 明细与看板聚合结果缓存，加速查询。

13.7触发逻辑

• 自动评测（默认）：Agent Trace 链路完成后，Webhook 消费完成即调用评测模型，分别写入 agent_evaluation 与 rag_evaluation，并同步记录 token 成本。
• 批量回归：批量接口提交测试集，异步执行，结果按 project / version 聚合到 TDengine。
• 低分联动：五维或 RAGAS 低于阈值，自动生成复检工单并关联 TraceID。
• 成本联动：token 消耗突增的 Trace 自动告警，纳入成本异常复检。