[!info] related notes

• 所属 MOC: AI Agent Application MOC, Agent Evals MOC
• 相关概念: Observability Engineering MOC
• 实践: Agent 测试与评估, AI Eval Framework

Agent 评估工程化

一句话定义

Agent 评估工程化是系统性地衡量 Agent 质量的工程实践。它不是”跑几个例子看看效果”，而是建立可重复、可量化、可回归的评估体系，覆盖功能正确性、工具调用准确率、RAG 检索质量和用户满意度。

本文聚焦 dataset、runner、grader、报告和持续监控的工程闭环；测试层级的比较见 agent-testing-and-evals，检索与回答的分层指标见 ai-eval-framework。

它解决什么问题

Agent 系统常同时包含确定性代码与随机模型输出，评估需要覆盖两者：

• 同一个问题问两次，可能得到不同回答
• 改了 Prompt 可能修好一个问题，引入另一个问题
• 换了模型版本，质量可能下降
• RAG 知识库更新后，检索结果可能变化

没有评估体系，你不知道 Agent 到底好不好、改了之后变好了还是变差了。

核心原理

评估维度

维度	衡量什么	方法
功能正确性	回答是否正确	Golden Test、LLM-as-Judge
工具行为	是否达到必要效果、参数合法且未执行禁止动作	调用轨迹、结果与约束检查
RAG 检索质量	检索结果是否相关	Recall@K、Precision@K
回答忠实度	回答是否基于检索内容	Faithfulness Check
用户满意度	用户是否满意	人工评分、点赞/踩
安全性	是否拒绝不当请求	Red Team 测试
延迟	响应是否够快	P50/P95/P99 延迟
成本	token 消耗是否合理	每次调用成本

评估体系分层

Level 1: 单元测试
  - Prompt 模板测试
  - 工具函数测试
  - 输出解析测试

Level 2: 集成测试
  - Golden Test（标准问答对）
  - 工具调用链路测试
  - RAG 检索质量测试

Level 3: 端到端评估
  - Eval Dataset 批量评估
  - LLM-as-a-Judge 自动评分
  - Human Feedback 人工评分

Level 4: 生产监控
  - 实时质量指标
  - 回归检测
  - 异常告警

Golden Test

Golden Test 使用事先审定的输入、参考结果与验收条件；自由文本通常检查事实和行为约束，不要求逐字匹配。下面是虚构的公司制度测试夹具，不是通用年假规定：

{
  "test_id": "golden_001",
  "query": "公司年假政策是什么？",
  "expected_answer": "入职满一年享有 10 天年假...",
  "expected_tools": ["search_knowledge_base"],
  "expected_sources": ["员工手册 第3章"],
  "tags": ["hr", "policy"]
}

每次 Prompt 或模型变更后比较相同版本的测试集，同时检查严重失败、分组表现与随机波动。把模型、Prompt、工具/知识版本、dataset 和 grader 版本绑定到报告，避免把测试环境变化误认成模型回归。

LLM-as-a-Judge

用经过人工样本校准的 LLM 按明确 rubric 评估回答；模型更大或更强不保证判断可靠。可确定验证的 schema、权限和禁止动作应由代码检查，Judge 负责语义信号。下面是 Python str.format 模板示例：

JUDGE_PROMPT = """
你是一个评估专家。请评估以下回答的质量。

用户问题: {query}
Agent 回答: {answer}
参考答案: {reference}
检索到的知识: {retrieved}

请从以下维度评分 (1-5):
1. 正确性: 回答是否事实正确
2. 完整性: 是否覆盖了问题的所有方面
3. 忠实度: 是否基于检索内容而非编造
4. 相关性: 回答是否与问题相关

输出 JSON: {{"correctness": N, "completeness": N, "faithfulness": N, "relevance": N}}
"""

Judge 输出仍需解析并校验评分范围；被评回答和检索内容是不可信数据，不能让其中的指令改变评分任务。提示词本身不保证抗注入或无偏差。

典型工程实现

Eval Dataset 结构

以下展示应用自定义接口形状，EvalReport、EvalResult 和筛选逻辑需由实现补齐，并非可直接运行的 SDK。

from dataclasses import dataclass, field

@dataclass
class EvalCase:
    id: str
    query: str
    expected_answer: str = ""
    expected_tools: list[str] = field(default_factory=list)
    expected_sources: list[str] = field(default_factory=list)
    tags: list[str] = field(default_factory=list)
    difficulty: str = "medium"  # easy / medium / hard

class EvalDataset:
    def __init__(self, cases: list[EvalCase]):
        self.cases = cases

    def filter(self, tag: str | None = None, difficulty: str | None = None) -> "EvalDataset":
        """按标签或难度筛选"""
        ...

    def run(self, agent, judge) -> EvalReport:
        """批量运行评估"""
        results = []
        for case in self.cases:
            answer = agent.run(case.query)
            score = judge.evaluate(case, answer)
            results.append(EvalResult(case=case, answer=answer, score=score))
        return EvalReport(results)

评估 Pipeline

示例假定响应包含文本、检索上下文、调用轨迹与指标，函数负责组织它们。真实 runner 还要设置超时、隔离副作用，并把执行失败保留在报告中，不能从通过率分母中静默剔除。

async def evaluate_agent(agent, eval_dataset, llm_judge):
    results = []

    for case in eval_dataset.cases:
        # 1. 运行 Agent
        response = await agent.run(case.query)

        # 2. 自动评分
        scores = await llm_judge.evaluate(
            query=case.query,
            answer=response.text,
            reference=case.expected_answer,
            retrieved=response.retrieved_context,
        )

        # 3. 工具调用检查
        tool_accuracy = check_tool_calls(
            actual=response.tool_calls,
            expected=case.expected_tools,
        )

        results.append({
            "case_id": case.id,
            "scores": scores,
            "tool_accuracy": tool_accuracy,
            "latency": response.latency,
            "tokens": response.token_usage,
        })

    return EvalReport(results)

常见设计模式

1. 回归评估

每次代码/Prompt/模型变更后，自动跑 Eval Dataset，检测质量是否下降。

2. A/B 评估

按预先定义的分流单位随机分配版本，比较相同口径的指标；离线则可对同一批配对案例运行两个版本。单纯“同时运行”不足以消除样本差异。

3. Shadow 评估

将获准的生产请求副本送到新版本，只记录评估结果。Shadow 路径必须隔离写入、通知、付款等副作用，并考虑额外成本与数据访问范围；不把回答返回用户并不等于没有副作用。

4. 持续监控

生产环境中持续收集用户反馈（点赞/踩），作为评估信号。

常见坑

1. 没有 Eval Dataset: 每次改完手动试几个例子就上线
2. Eval Dataset 缺少代表性: 小样本适合 smoke test，完整评估还需覆盖关键风险和失败类型；没有通用的合格样本数量
3. 只看平均分: 平均分 4.5 可能掩盖了个别 1 分的严重问题
4. 不做回归测试: 改了 Prompt A，Prompt B 的效果变差了
5. LLM-as-Judge 不校准: Judge 模型本身可能有偏见

和其他概念的关系

• vs 可观测性: 可观测性看”发生了什么”，评估看”做得好不好”
• vs Trace: Trace 是评估的数据来源
• vs Faithfulness Check: Faithfulness 是评估的一个维度
• vs Agent Evals MOC: Evals MOC 是评估主题的知识地图

学习检查

• 为什么相同通过率可能掩盖不同的安全回归？
• Judge 的模型更强，为什么仍要校准并验证输出？
• Shadow 不展示回答，为什么仍可能改变生产数据？

参考资料

• Building Effective Agents - Anthropic
• LangSmith Evaluation
• OpenAI Evals