agent-insight 0.5.1 → 0.5.2

package/.next/standalone/Evaluation_and_Research/agent_evaluator_research_qna_2.md

@@ -0,0 +1,1312 @@
+# Agent 评估器调研问答 2
+
+调研日期：2026-07-06
+
+这份文档用于继续记录 `agent_evaluator_industry_research.md` 里的细节问题。上一份问答见 `agent_evaluator_research_qna.md`。
+
+## Q5：DeepEval PlanAdherenceMetric 的意义是什么？如果 plan 和 execution steps 都来自 trace，这种“自我评价”奇怪吗？
+
+### 简短回答
+
+确实容易觉得奇怪，但它不是让 agent “自己评价自己”。更准确地说，DeepEval [`PlanAdherenceMetric`](https://deepeval.com/docs/metrics-plan-adherence) 是用一个外部 LLM judge，从同一条 trace 中抽取两类对象：
+
+```text
+1. agent 曾经表达或暗示过的计划 plan
+2. agent 后续实际执行的步骤 execution steps
+```
+
+然后评估：
+
+```text
+实际执行步骤是否遵守了前面那个计划？
+```
+
+所以它评估的不是“计划好不好”，也不是“最终结果好不好”，而是：
+
+```text
+agent 是否能把自己定下的路线稳定执行下去？
+```
+
+### 为什么这不是纯粹的自我评价？
+
+它看起来像自我评价，是因为 plan 和 execution steps 都来自同一条 trace。但真正的评价者不是原 agent，而是外部 evaluator。
+
+可以类比成人类项目复盘：
+
+```text
+会议纪要里写了计划：
+1. 先确认需求
+2. 再修改代码
+3. 最后运行测试
+
+实际工作记录里显示：
+1. 直接修改代码
+2. 没有确认需求
+3. 没有运行测试
+
+复盘者判断：
+没有遵守计划
+```
+
+计划和执行记录都来自同一个项目过程，但复盘判断不是项目执行者自己做的，而是外部观察者做的。
+
+### 这个指标的意义在哪？
+
+Plan Adherence 的意义是把 agent 的失败拆成更细的责任阶段。
+
+很多时候 agent 会先说出一个看起来合理的计划：
+
+```text
+我会先读取相关文件，然后定位问题，再修改代码，最后运行测试。
+```
+
+但实际 trace 里可能是：
+
+```text
+读取了一个文件
+直接修改
+没有运行测试
+直接回复完成
+```
+
+这时如果只看 Plan Quality，计划可能是好的；如果只看 Task Completion，可能只知道结果成败；Plan Adherence 则能指出：
+
+```text
+计划本身没问题，但执行没有跟上。
+```
+
+它尤其能发现这些问题：
+
+- 计划里说要验证，但最后没验证。
+- 计划里说要先收集信息，但直接行动。
+- 计划里说要分阶段处理，但执行时跳步。
+- 计划里说要调用某类工具，但实际用了无关工具。
+- 计划里说要交给某个子 agent，但实际没有派发或派错。
+- 中途遇到错误后，偏离计划但没有解释或重规划。
+
+### 它和 Plan Quality 的区别
+
+| 指标 | 比较对象 | 回答的问题 |
+| --- | --- | --- |
+| Plan Quality | Task vs Plan | 这个计划本身能不能完成任务？ |
+| Plan Adherence | Plan vs Execution Steps | agent 后续有没有按计划执行？ |
+
+典型情况：
+
+| Plan Quality | Plan Adherence | 说明 |
+| --- | --- | --- |
+| 高 | 高 | 计划合理，执行也遵守，理想状态 |
+| 高 | 低 | 计划合理，但执行偏离，问题在执行控制 |
+| 低 | 高 | agent 忠实执行了坏计划，问题在规划能力 |
+| 低 | 低 | 规划和执行都不稳定 |
+
+### `agent's execution steps` 是什么意思？
+
+`agent's execution steps` 指的是 agent 在 trace 中实际发生过的一系列可观察动作。它不是隐藏推理，也不是模型脑子里的 chain-of-thought，而是运行记录里能看到的步骤。
+
+常见 execution steps 包括：
+
+- 用户请求。
+- agent 的可见计划或行动说明。
+- LLM 生成的一次响应。
+- 工具调用，例如 `read_file`、`web_search`、`bash`、`database_query`。
+- 工具返回结果。
+- skill 调用。
+- 子 agent / handoff 调用。
+- 错误、重试、参数修正。
+- 最终回复。
+
+一个简化 trace 可以表示成：
+
+```text
+[#0] user: 修复登录失败问题
+[#1] assistant: 我会先查看日志，再定位代码，再修改并运行测试
+[#2] tool: read_file("auth.log")
+[#3] tool_result: database timeout
+[#4] tool: read_file("src/auth.ts")
+[#5] tool: edit_file("src/auth.ts")
+[#6] assistant: 已修复
+```
+
+这里：
+
+- plan 是 `[#1]` 里的“先查看日志、再定位代码、再修改并运行测试”。
+- execution steps 是 `[#2]` 到 `[#6]` 的实际动作序列。
+- Plan Adherence 会发现：计划里有“运行测试”，execution steps 里没有测试步骤。
+
+### execution steps 怎么提取？
+
+通常从 trace 的 span / event 序列中提取。不同框架字段不同，但核心思路类似。
+
+#### 1. 先把 trace 按时间排序
+
+原始 trace 里可能有很多 span：
+
+```text
+llm.call
+tool.call
+tool.result
+agent.message
+subagent.start
+subagent.end
+```
+
+先按时间线排成一条或一棵执行链。
+
+#### 2. 过滤成 agent 行为相关事件
+
+不是所有 telemetry 都是 execution step。通常保留：
+
+- LLM 输出。
+- tool call。
+- tool result。
+- skill call。
+- subagent / handoff。
+- 错误和 retry。
+- 最终输出。
+
+可以忽略：
+
+- 纯内部网络 span。
+- 日志写入 span。
+- UI 事件。
+- 与任务无关的 telemetry。
+
+#### 3. 归一化为步骤结构
+
+例如统一成：
+
+```json
+{
+  "step_index": 4,
+  "kind": "tool",
+  "name": "read_file",
+  "args_summary": "{\"path\":\"src/auth.ts\"}",
+  "output_summary": "function login(...) ...",
+  "timestamp": "...",
+  "agent": "root"
+}
+```
+
+这一步的目标是让 evaluator 不必理解每个框架的原始日志格式。
+
+#### 4. 抽取 plan
+
+plan 可以来自：
+
+- agent 明确输出的计划。
+- TODO list。
+- “I will first..., then...” 这类行动说明。
+- 子 agent 派发前的任务拆解。
+- 对用户可见的工作步骤承诺。
+
+不建议从隐藏推理里抽 plan，也不应该为了评估要求模型泄露 chain-of-thought。
+
+#### 5. 比较 plan 和 execution steps
+
+外部 judge 会判断：
+
+```text
+计划中的每个步骤是否执行了？
+执行顺序是否大体一致？
+是否跳过关键步骤？
+是否做了计划外但合理的重规划？
+是否偏离计划且没有解释？
+```
+
+输出通常可以是：
+
+```text
+score: 0-1
+reason: 为什么遵守/没遵守
+missed_plan_items: [...]
+deviated_steps: [...]
+evidence_steps: [...]
+```
+
+### 什么时候这个指标有意义？
+
+Plan Adherence 有意义的前提是：trace 里真的有可见计划。
+
+适合场景：
+
+- agent 会先输出任务计划。
+- coding agent 有 todo list。
+- 多 agent 系统有任务拆解和 handoff 计划。
+- 高风险任务要求先说明步骤再执行。
+- skill 明确要求 agent 按流程执行。
+
+例如：
+
+```text
+先分析日志 -> 再定位根因 -> 再修改配置 -> 最后验证
+```
+
+如果 trace 里能看到这个计划，那么评估实际是否遵守就很有价值。
+
+### 什么时候它会变得很弱，甚至误导？
+
+#### 1. trace 里没有可见计划
+
+如果 agent 没有输出计划，或者框架不记录 planning 信息，Plan Adherence 就缺少比较对象。
+
+这时不应该强行给高分或低分，更合理的是：
+
+```text
+N/A: no visible plan
+```
+
+#### 2. plan 是评估器事后从执行步骤“反推”的
+
+这是最危险的情况。
+
+如果 evaluator 不是从 agent 执行前的可见计划抽 plan，而是看完整 trace 后总结出一个“计划”，再拿这个计划和同一条 trace 比较，那么就会产生循环：
+
+```text
+根据实际执行反推出计划
+再评估实际执行是否符合这个计划
+```
+
+这当然会虚高，也就失去意义。
+
+所以 Plan Adherence 的关键约束是：
+
+```text
+plan 必须来自执行前或执行中的可见计划表达，
+不能由 evaluator 看完整执行后倒推出。
+```
+
+#### 3. agent 合理重规划
+
+如果执行过程中出现新证据，agent 偏离原计划不一定是坏事。
+
+例如：
+
+```text
+原计划：读取 A 文件后修改 A
+实际：读取 A 后发现问题在 B，于是改 B 并说明原因
+```
+
+这应该算合理重规划，而不是简单扣分。
+
+所以评估时要区分：
+
+```text
+合理偏离：有新证据、有解释、目标仍一致
+不合理偏离：无理由跳过关键步骤、忘记验证、做无关动作
+```
+
+### 这个指标对 agent 评估改进有什么用？
+
+它主要帮助改 **执行控制能力**，不是直接改最终答案。
+
+如果 Plan Quality 高但 Plan Adherence 低，优化方向通常是：
+
+- 增加 checklist / todo 状态跟踪。
+- 在回复前检查计划项是否完成。
+- 给关键步骤加 hard constraint，例如“修改后必须验证”。
+- 增加中途偏离计划时的重规划说明。
+- 给多 agent handoff 增加父 agent 汇总和验收步骤。
+
+它能避免一种常见问题：
+
+```text
+agent 很会说计划，但执行时不按计划做。
+```
+
+这类 agent 看起来很聪明，但可靠性差。Plan Adherence 正是用来抓这种“计划-执行脱节”的。
+
+### 总结
+
+Plan Adherence 的核心不是“自我评价”，而是：
+
+```text
+外部 evaluator 检查 agent 的可见计划和实际执行是否一致。
+```
+
+`agent's execution steps` 就是 trace 中可观察到的行动序列，包括 LLM 消息、工具调用、工具返回、skill 调用、子 agent 调用、错误重试和最终回复。
+
+这个指标有意义的前提是：
+
+```text
+plan 必须是执行前/执行中可见的真实计划，
+不能是根据完整 trace 事后反推出来的计划。
+```
+
+如果没有可见计划，最好标记为 N/A；如果有可见计划，它就能很好地区分“计划错了”与“执行没跟上”。
+
+### 参考链接
+
+- DeepEval Plan Adherence: https://deepeval.com/docs/metrics-plan-adherence
+
+## Q6：Ragas Context Precision / Context Recall 和 Phoenix Document Relevance 有什么区别？Ragas Context Precision / Recall 的输入、输出和评估过程是什么？
+
+### 简短结论
+
+这三个指标都和 RAG / 检索质量有关，但粒度和回答的问题不一样。
+
+| 指标 | 主要回答的问题 | 评估粒度 | 是否看排序 | 是否需要 reference | 输出 |
+| --- | --- | --- | --- | --- | --- |
+| Ragas [`Context Precision`](https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/context_precision/) | 检索回来的上下文里，相关内容是否排在前面？ | 一次 query 的整组 retrieved contexts | 看排序 | 可用 reference、response、reference_contexts 或 context IDs，取决于变体 | 0-1 连续分 |
+| Ragas [`Context Recall`](https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/context_recall/) | reference 里需要的信息，有多少被检索回来了？ | 一次 query 的整组 retrieved contexts | 不重点看排序 | 需要 reference / reference_contexts / reference IDs | 0-1 连续分 |
+| Phoenix [`Document Relevance`](https://arize.com/docs/phoenix/evaluation/pre-built-metrics/document-relevance) | 单个文档 chunk 对当前 query 是否相关？ | 单个 document / span | 不看排序 | 不需要 reference，只需要 query + document | `relevant` / `unrelated`，1 或 0 |
+
+可以这样记：
+
+```text
+Phoenix Document Relevance:
+  这个单独文档有没有用？
+
+Ragas Context Precision:
+  检索回来的一组文档里，有用的是否排在前面？
+
+Ragas Context Recall:
+  该找回的重要信息有没有找全？
+```
+
+### Phoenix Document Relevance 是什么
+
+Phoenix Document Relevance 是一个 **单文档相关性分类器**。它的输入很简单：
+
+```text
+input: 用户问题
+document_text: 一个被检索出来的文档/chunk
+```
+
+输出是：
+
+```text
+label: relevant | unrelated
+score: 1.0 | 0.0
+explanation: LLM 判断理由
+```
+
+它适合用在 retriever span 上，对每个检索结果单独打标：
+
+```text
+query: COVID-19 有什么症状？
+
+doc1: COVID-19 symptoms include fever, cough...
+=> relevant, 1
+
+doc2: The history of coronaviruses dates back...
+=> unrelated, 0
+```
+
+它不天然回答：
+
+- 相关文档是否排在前面。
+- 所有必要信息是否都找全。
+- 多个文档合起来是否覆盖 reference。
+
+如果要得到类似 precision 的聚合，需要你自己对多个文档结果做统计；如果要 recall，则必须有 reference 或标准相关文档集合，否则没法知道“漏了什么”。
+
+### Ragas Context Precision 的输入是什么？
+
+Ragas Context Precision 有多个变体，输入略有不同。
+
+#### 1. LLM Context Precision with reference
+
+适合有标准答案时。
+
+```text
+user_input: 用户问题
+reference: 标准答案 / 期望答案
+retrieved_contexts: 按检索排序返回的一组 context chunks
+```
+
+例子：
+
+```text
+user_input:
+Where is the Eiffel Tower located?
+
+reference:
+The Eiffel Tower is located in Paris.
+
+retrieved_contexts:
+1. The Eiffel Tower is located in Paris.
+2. The Brandenburg Gate is located in Berlin.
+```
+
+#### 2. LLM Context Precision without reference / Context Utilization
+
+适合没有标准答案，但已有模型生成回答时。
+
+```text
+user_input: 用户问题
+response: 模型生成的回答
+retrieved_contexts: 按检索排序返回的一组 context chunks
+```
+
+它会用 response 作为判断依据，看每个 retrieved context 是否对生成回答有用。
+
+#### 3. Non-LLM Context Precision with reference contexts
+
+适合有标准相关文档集合时。
+
+```text
+retrieved_contexts: 实际检索返回的 contexts
+reference_contexts: 标准相关 contexts
+```
+
+它不用 LLM，而是用字符串相似度等方法判断 retrieved context 是否命中 reference context。
+
+#### 4. ID-based Context Precision
+
+适合文档有稳定 ID 时。
+
+```text
+retrieved_context_ids: 实际检索返回的文档 ID
+reference_context_ids: 标准相关文档 ID
+```
+
+直接按 ID 计算命中。
+
+### Ragas Context Precision 的中间评估过程
+
+Context Precision 重点看的是：**相关 context 是否排在检索结果前面**。
+
+它的核心过程可以拆成：
+
+#### 1. 对每个 retrieved context 判断是否相关
+
+对检索结果列表里的每个 chunk，得到一个相关性标记：
+
+```text
+v_k = 1 表示第 k 个 chunk relevant
+v_k = 0 表示第 k 个 chunk irrelevant
+```
+
+这个判断可以由 LLM 完成，也可以由字符串相似度或 ID 匹配完成。
+
+LLM with reference 时：
+
+```text
+判断 retrieved_context[k] 是否有助于回答 reference
+```
+
+LLM without reference / utilization 时：
+
+```text
+判断 retrieved_context[k] 是否有助于支撑 response
+```
+
+ID-based 时：
+
+```text
+判断 retrieved_context_id[k] 是否在 reference_context_ids 中
+```
+
+#### 2. 计算每个 relevant chunk 位置上的 precision@k
+
+例如检索回来 4 个 chunk：
+
+```text
+rank 1: relevant
+rank 2: irrelevant
+rank 3: relevant
+rank 4: irrelevant
+```
+
+那么：
+
+```text
+precision@1 = 1/1 = 1.0
+precision@3 = 2/3 = 0.67
+```
+
+#### 3. 对 relevant chunk 的 precision@k 求平均
+
+Context Precision 类似 average precision：
+
+```text
+Context Precision =
+  sum(precision@k * v_k) / number_of_relevant_chunks_in_retrieved_contexts
+```
+
+所以它会奖励：
+
+```text
+相关 chunk 排在前面
+```
+
+惩罚：
+
+```text
+无关 chunk 排在前面，把相关 chunk 挤到后面
+```
+
+#### 4. 为什么它关注排序
+
+两个检索结果包含相同文档，但顺序不同：
+
+```text
+结果 A:
+1. Eiffel Tower is located in Paris
+2. Brandenburg Gate is in Berlin
+
+结果 B:
+1. Brandenburg Gate is in Berlin
+2. Eiffel Tower is located in Paris
+```
+
+两个结果都找到了正确 context，但结果 A 的 Context Precision 更高，因为正确 context 排在前面。对 RAG 很重要，因为 LLM 通常更容易使用前面的、靠前的上下文；排序差会导致生成阶段更容易被噪声干扰。
+
+### Ragas Context Precision 的输出是什么？
+
+Ragas 示例里返回的是：
+
+```text
+result.value
+```
+
+取值范围：
+
+```text
+0.0 到 1.0
+```
+
+含义：
+
+```text
+越接近 1，说明相关 context 越靠前，检索排序越好。
+越接近 0，说明相关 context 少或排得很靠后。
+```
+
+如果使用 LLM 版本，内部通常还会有 per-context 的判断理由或中间判断，但标准示例主要展示最终分数。
+
+### Ragas Context Recall 的输入是什么？
+
+Context Recall 衡量的是“有没有漏掉重要信息”。它不像 precision 那样主要看排序，而是看 reference 中需要的信息是否被 retrieved contexts 覆盖。
+
+Ragas 文档明确说：Context Recall 需要 reference 来比较。
+
+#### 1. LLM Context Recall
+
+输入：
+
+```text
+user_input: 用户问题
+reference: 标准答案 / 期望答案
+retrieved_contexts: 检索返回的一组 context chunks
+```
+
+例子：
+
+```text
+user_input:
+Where is the Eiffel Tower located?
+
+reference:
+The Eiffel Tower is located in Paris.
+
+retrieved_contexts:
+Paris is the capital of France.
+```
+
+#### 2. Non-LLM Context Recall
+
+输入：
+
+```text
+retrieved_contexts: 实际检索返回的 contexts
+reference_contexts: 标准相关 contexts
+```
+
+#### 3. ID-based Context Recall
+
+输入：
+
+```text
+retrieved_context_ids: 实际检索返回的文档 ID
+reference_context_ids: 标准相关文档 ID
+```
+
+### Ragas Context Recall 的中间评估过程
+
+Context Recall 的核心是：
+
+```text
+reference 里有多少信息能从 retrieved_contexts 中找到证据？
+```
+
+LLM 版本通常这样做。
+
+#### 1. 把 reference 拆成 claims
+
+例如：
+
+```text
+reference:
+The Eiffel Tower is located in Paris and was completed in 1889.
+```
+
+拆成：
+
+```text
+claim 1: The Eiffel Tower is located in Paris.
+claim 2: The Eiffel Tower was completed in 1889.
+```
+
+#### 2. 对每个 claim 判断是否被 retrieved contexts 支持
+
+假设：
+
+```text
+retrieved_contexts:
+1. Paris is the capital of France.
+2. The Eiffel Tower is located in Paris.
+```
+
+判断：
+
+```text
+claim 1 supported: yes
+claim 2 supported: no
+```
+
+#### 3. 计算支持比例
+
+公式：
+
+```text
+Context Recall =
+  number_of_reference_claims_supported_by_retrieved_contexts
+  / total_number_of_reference_claims
+```
+
+上面的例子：
+
+```text
+Context Recall = 1 / 2 = 0.5
+```
+
+#### 4. Non-LLM / ID-based recall
+
+如果有 `reference_contexts` 或 `reference_context_ids`，可以不拆 claims：
+
+```text
+Context Recall =
+  retrieved 中命中的 reference contexts 数量
+  / reference contexts 总数
+```
+
+ID-based 例子：
+
+```text
+retrieved_context_ids:
+doc_1, doc_2, doc_3
+
+reference_context_ids:
+doc_1, doc_4, doc_5, doc_6
+
+Context Recall = 1 / 4 = 0.25
+```
+
+### Ragas Context Recall 的输出是什么？
+
+输出同样是 0-1 分数：
+
+```text
+result.value
+```
+
+含义：
+
+```text
+越接近 1，说明 reference 需要的信息基本都被检索回来了。
+越接近 0，说明检索漏掉了大量关键证据。
+```
+
+### 三者最关键的区别
+
+#### 1. Phoenix Document Relevance 是单文档判断
+
+它判断：
+
+```text
+这个 doc 对 query 有没有用？
+```
+
+不关心：
+
+```text
+这个 doc 排第几？
+是否漏了其他关键 doc？
+```
+
+#### 2. Ragas Context Precision 是排序质量
+
+它判断：
+
+```text
+检索结果里相关 context 是否排得足够靠前？
+```
+
+所以它适合比较：
+
+- embedding 模型。
+- chunking 策略。
+- reranker。
+- hybrid search。
+- top-k 设置。
+
+#### 3. Ragas Context Recall 是覆盖质量
+
+它判断：
+
+```text
+reference 里需要的信息有没有被找回来？
+```
+
+所以它适合发现：
+
+- top-k 太小。
+- query rewrite 不够好。
+- 索引缺文档。
+- chunk 太碎导致关键信息分散。
+- retriever 找到了相关但不完整的上下文。
+
+### 在 agent 评估里的意义
+
+对于 agent，尤其是会搜索、读文档、查知识库的 agent，这三个指标对应检索链路的三个问题：
+
+```text
+Document Relevance:
+  每个检索结果是不是有用？
+
+Context Precision:
+  有用结果是不是排在前面，噪声有没有挡路？
+
+Context Recall:
+  任务需要的关键信息有没有找全？
+```
+
+如果答案错了：
+
+- Document Relevance 低：检索结果本身大量无关。
+- Context Precision 低：相关信息有，但排得靠后，被噪声干扰。
+- Context Recall 低：关键证据根本没被找回来。
+- 这三项都高但答案仍错：问题更可能在生成、证据忠实度或工具结果处理。
+
+### 附加问题：这三个指标是不是专门用来衡量 RAG 检索质量的？
+
+是的，严格来说它们主要是 **RAG / retrieval 质量指标**，不是通用 agent 指标。
+
+它们评估的是 agent 链路里的“取证/检索阶段”：
+
+```text
+用户问题
+=> 检索器 / 搜索 / 文档读取
+=> retrieved contexts / documents
+=> 后续生成或行动
+```
+
+三者关注的都是 retrieved contexts / documents 的质量：
+
+- `Document Relevance`：单个检索结果是否相关。
+- `Context Precision`：相关检索结果是否排得靠前。
+- `Context Recall`：任务需要的信息是否被检索回来。
+
+所以它们适用于这些 agent：
+
+- RAG 问答 agent。
+- 文档分析 agent。
+- 知识库客服 agent。
+- 需要 web search / file search / database search 的 agent。
+- 需要先读材料再回答或行动的工具型 agent。
+
+但它们不适合直接评价所有 agent。例如：
+
+- 纯代码修改 agent，如果没有检索/读文档阶段，这三个指标可能 N/A。
+- 纯计算或格式转换任务，不需要 context retrieval。
+- 工具调用型业务 agent，如果工具返回的是结构化业务状态，更适合用 Tool Invocation / Tool Response Handling，而不是 Context Precision / Recall。
+
+更准确的定位是：
+
+```text
+它们不是评价 agent 整体好坏，
+而是评价 agent 在 RAG / 检索 / 取证环节做得好不好。
+```
+
+如果把 agent 看成一条链路：
+
+```text
+计划 -> 检索/取证 -> 工具调用 -> 结果处理 -> 最终回答
+```
+
+那么这三个指标主要覆盖：
+
+```text
+检索/取证
+```
+
+如果这三项都很好，最终答案仍然差，说明问题多半不在检索，而在后续的 groundedness、工具结果处理、推理或任务完成度。
+
+### 参考链接
+
+- Ragas Context Precision: https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/context_precision/
+- Ragas Context Recall: https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/context_recall/
+- Phoenix Document Relevance: https://arize.com/docs/phoenix/evaluation/pre-built-metrics/document-relevance
+
+## Q7：稳定性 / 可重复性，业界各方法的逻辑是什么？
+
+### 简短结论
+
+稳定性 / 可重复性评估关注的不是：
+
+```text
+这次 agent 有没有成功？
+```
+
+而是：
+
+```text
+同一个任务、同一类任务、或轻微扰动后的任务，agent 能不能稳定成功？
+```
+
+这类指标要解决一个 agent 评估里的核心问题：
+
+```text
+单次成功不代表可上线。
+```
+
+一个 agent 可能某次完成任务，但换一次随机种子、换一种用户说法、工具慢一点、API 报一次错，就失败。稳定性指标就是用来量化这种不可靠性。
+
+### 方法 1：重复运行成功率 success rate@N
+
+这是最直观的方法。
+
+对同一个 case 重复运行 N 次：
+
+```text
+case_1 run_1: pass
+case_1 run_2: fail
+case_1 run_3: pass
+case_1 run_4: pass
+case_1 run_5: fail
+```
+
+计算：
+
+```text
+success_rate@5 = 成功次数 / 总次数 = 3 / 5 = 0.6
+```
+
+然后对所有 case 求平均：
+
+```text
+mean_success_rate@N =
+  average(success_count(case_i) / N)
+```
+
+#### 它说明什么
+
+它衡量 agent 在相同任务上的平均成功概率。
+
+如果单次 pass rate 是 80%，但 success_rate@5 的分布很散，说明 agent 行为不稳定，有时能成、有时不能成。
+
+#### 优点
+
+- 简单直观。
+- 适合 A/B、版本回归、灰度评测。
+- 容易和任务完成度评估器结合。
+
+#### 缺点
+
+- 只看平均值，可能掩盖“某些 case 非常不稳定”。
+- 如果 N 太小，估计不稳。
+- 不能区分失败原因。
+
+### 方法 2：tau-bench 的 `pass^k`
+
+[`tau-bench`](https://arxiv.org/abs/2406.12045) 提出了一个很适合 agent 的稳定性指标：`pass^k`。
+
+它的直觉是：
+
+```text
+一个 agent 只有连续 k 次都完成同一个任务，才算这个任务稳定通过。
+```
+
+所以它比普通 success rate 更严格。
+
+#### 计算逻辑
+
+对每个任务重复运行 k 次。
+
+```text
+case A:
+run 1: pass
+run 2: pass
+run 3: pass
+=> pass^3 = 1
+
+case B:
+run 1: pass
+run 2: fail
+run 3: pass
+=> pass^3 = 0
+```
+
+然后对所有 case 求平均：
+
+```text
+pass^k =
+  number_of_cases_that_pass_all_k_trials / total_cases
+```
+
+#### 它和 pass@k 不一样
+
+常见 benchmark 里有 `pass@k`：
+
+```text
+k 次里只要有一次成功，就算通过
+```
+
+这适合代码生成或采样多个答案的场景。
+
+但 tau-bench 的 `pass^k` 更严格：
+
+```text
+k 次必须全部成功，才算通过
+```
+
+这更适合 agent 上线质量，因为真实用户通常不会接受“多试几次总有一次能成”。
+
+#### 它说明什么
+
+`pass^k` 衡量的是：
+
+```text
+agent 行为是否可重复、可靠、稳定。
+```
+
+如果：
+
+```text
+pass^1 = 0.70
+pass^8 = 0.25
+```
+
+说明 agent 单次看起来还行，但连续稳定完成任务的能力很差。tau-bench 论文里就观察到：一些函数调用 agent 单次成功率尚可，但多次重复后 `pass^8` 大幅下降。
+
+#### 适用场景
+
+- 业务流程 agent，例如客服、订票、订单修改。
+- 多轮工具调用 agent。
+- 有明确最终状态的任务。
+- 版本发布前的可靠性门槛。
+
+### 方法 3：方差 / 分数波动
+
+如果每次运行不只是 pass/fail，而是有 0-1 分数，可以看方差。
+
+例如同一个 case 跑 5 次任务完成度：
+
+```text
+0.9, 0.8, 0.2, 0.95, 0.3
+```
+
+平均分可能还不低，但波动很大。
+
+常用统计包括：
+
+```text
+mean_score
+stddev_score
+min_score
+max_score
+coefficient_of_variation = stddev / mean
+```
+
+#### 它说明什么
+
+它衡量 agent 的输出质量是否稳定。
+
+两个 agent 平均分一样：
+
+```text
+Agent A: 0.8, 0.8, 0.8, 0.8
+Agent B: 1.0, 0.6, 1.0, 0.6
+```
+
+Agent A 更稳定，Agent B 更随机。
+
+#### 适用场景
+
+- LLM judge 给连续分的任务。
+- 结果质量评估。
+- RAG 回答质量。
+- 多指标综合评分。
+
+### 方法 4：一致性 / 输出等价性
+
+有些任务不是简单 pass/fail，而是多种答案都可以接受。这时可以评估多次运行之间是否语义一致、最终状态等价。
+
+逻辑是：
+
+```text
+同一个任务运行多次
+=> 比较最终输出 / 最终状态 / 工具动作序列
+=> 判断是否等价
+```
+
+例如：
+
+```text
+run 1: 把订单地址改成 A，成功
+run 2: 把订单地址改成 A，成功
+run 3: 把订单地址改成 B，成功
+```
+
+如果用户目标是地址 A，那么 run 3 即使自称成功，也不是等价成功。
+
+#### 常见等价对象
+
+- 最终数据库状态。
+- 文件 diff。
+- API side effect。
+- 关键事实集合。
+- 用户可见最终答案。
+- 工具调用序列是否满足同一目标。
+
+#### 适用场景
+
+- 有多个合理文本表达的任务。
+- 最终状态比最终文本更重要的业务 agent。
+- 工具型 agent。
+
+tau-bench 就是用最终数据库状态与标注 goal state 比较，避免只看文本回复。
+
+### 方法 5：语义扰动鲁棒性
+
+这是更接近生产环境的方法：不是只重复同一句输入，而是生成语义等价或近似等价的变体。
+
+例如：
+
+```text
+原始任务：
+帮我把 8 点的航班改签到明早最早一班。
+
+扰动 1：
+我想把今晚 8 点那趟飞机改成明天早上最早的。
+
+扰动 2：
+能不能帮我改签？目标是明早越早越好，原票是晚上 8 点。
+```
+
+评估：
+
+```text
+agent 是否在这些语义等价输入上都达成同一目标？
+```
+
+#### 它说明什么
+
+它衡量 agent 是否只记住了某种表述，还是理解了用户意图。
+
+#### 适用场景
+
+- 用户自然语言高度多样的客服/业务 agent。
+- 需要抗 prompt wording 变化的生产 agent。
+- 数据集样本太模板化时的补充评估。
+
+[`ReliabilityBench`](https://arxiv.org/abs/2601.06112) 把这种思想系统化，提出在语义扰动强度 `ε` 下评估 agent robustness。
+
+### 方法 6：故障注入 / 压力条件下的可靠性
+
+生产环境里，工具/API 不会总是完美工作。稳定性评估还要看 agent 在工具失败时能否恢复。
+
+常见故障注入：
+
+- timeout。
+- rate limit。
+- partial response。
+- schema drift。
+- 空结果。
+- 权限错误。
+- 临时网络错误。
+
+评估：
+
+```text
+正常条件下是否成功？
+工具故障条件下是否仍能成功或合理失败？
+是否会重复相同错误调用？
+是否能修正参数或换路径？
+```
+
+[`ReliabilityBench`](https://arxiv.org/abs/2601.06112) 把可靠性建模成一个面：
+
+```text
+R(k, ε, λ)
+```
+
+其中：
+
+- `k`：重复执行次数。
+- `ε`：语义扰动强度。
+- `λ`：工具/API 故障强度。
+
+这个框架的意思是：
+
+```text
+真正的可靠性 = 重复执行 + 输入扰动 + 工具故障 三者共同压力下的表现。
+```
+
+### 方法 7：CLEAR 的 Reliability 维度
+
+[`CLEAR`](https://arxiv.org/abs/2511.14136) 是面向企业 agent 的多维评估框架：
+
+```text
+C = Cost
+L = Latency
+E = Efficacy
+A = Assurance
+R = Reliability
+```
+
+其中 Reliability 关注：
+
+```text
+agent 在多次运行、不同条件下是否稳定可靠。
+```
+
+CLEAR 的重要观点是：
+
+```text
+accuracy-only 不够。
+```
+
+一个 agent 可能单次准确率高，但：
+
+- 成本极高。
+- 延迟不可接受。
+- 多次运行不稳定。
+- 合规性不好。
+- 遇到边界条件就失败。
+
+CLEAR 把 reliability 和 cost、latency、assurance 放在一起，是为了判断 agent 是否真的适合生产环境。
+
+#### 它说明什么
+
+CLEAR 的稳定性逻辑不是只算一个成功率，而是把稳定性放入上线决策：
+
+```text
+能不能稳定完成？
+完成成本是否稳定？
+延迟是否稳定？
+风险是否可控？
+```
+
+它特别适合企业 agent，因为企业更关心：
+
+```text
+可预测性 > 偶然高分
+```
+
+### 方法 8：平台化 eval runs，例如 LangSmith / OpenAI
+
+LangSmith、OpenAI Evals 这类平台通常不只定义某一个“稳定性指标”，而是提供可重复的评测运行机制：
+
+```text
+固定 dataset
+固定 evaluator / grader
+固定模型和配置
+重复运行
+比较不同版本
+记录每次 run 的分数、失败样例和趋势
+```
+
+稳定性来自实验设计：
+
+- 同一数据集重复跑。
+- 同一 case 多次采样。
+- 比较 run-to-run score。
+- 记录分布，而不是只看单次平均值。
+- 用 regression report 看新版本是否退化。
+
+#### 它说明什么
+
+这类平台方法关注：
+
+```text
+评估是否可重复、可比较、可回归。
+```
+
+它不一定内置 `pass^k`，但提供了实现 `success_rate@N`、方差、回归检测、版本对比的基础设施。
+
+### 各方法对比
+
+| 方法 | 核心逻辑 | 最适合回答的问题 |
+| --- | --- | --- |
+| success_rate@N | 同一 case 跑 N 次，统计成功比例 | 平均有多大概率成功？ |
+| pass^k | 同一 case 连续 k 次全成功才算过 | 是否稳定到可以依赖？ |
+| 分数方差 | 多次运行的连续分是否波动 | 输出质量是否稳定？ |
+| 输出/状态等价性 | 多次运行最终状态是否等价 | 是否每次都达成同一个目标？ |
+| 语义扰动鲁棒性 | 换说法后是否仍成功 | 是否理解意图，而非记模板？ |
+| 故障注入 | 工具/API 异常时是否恢复 | 是否具备生产容错能力？ |
+| CLEAR Reliability | 把可靠性与成本、延迟、风险一起看 | 是否适合企业上线？ |
+| Eval runs 平台化 | 固定数据集和 evaluator 做重复实验 | 版本是否可比较、可回归？ |
+
+### 对 agent 评估的价值
+
+稳定性 / 可重复性指标能发现单次评测看不出来的问题：
+
+```text
+偶然成功
+随机失败
+对措辞敏感
+对工具错误脆弱
+成本和延迟波动大
+同一任务多次产生不同副作用
+```
+
+它也能帮助做发布决策：
+
+```text
+单次任务完成度高，但 pass^k 低
+=> 不适合上线，只能说明偶尔能成
+
+平均分高，但方差大
+=> 需要增加 guardrail 或降低随机性
+
+正常条件好，故障注入差
+=> 需要优化错误恢复和 fallback
+
+旧版本 pass^5 高，新版本 pass^5 低
+=> 新版本有可靠性回归
+```
+
+### 一个推荐的稳定性指标组合
+
+如果要系统评估 agent 稳定性，可以组合这些指标：
+
+```text
+1. success_rate@N
+2. pass^k
+3. score_mean / score_stddev
+4. semantic_perturbation_success_rate
+5. fault_injection_success_rate
+6. final_state_consistency
+7. cost / latency variance
+```
+
+其中：
+
+- `success_rate@N` 看平均成功概率。
+- `pass^k` 看连续可靠性。
+- `stddev` 看质量波动。
+- `semantic perturbation` 看表达鲁棒性。
+- `fault injection` 看生产容错。
+- `final state consistency` 看副作用是否一致。
+- `cost / latency variance` 看运行是否可预测。
+
+### 参考链接
+
+- tau-bench: https://arxiv.org/abs/2406.12045
+- CLEAR: https://arxiv.org/abs/2511.14136
+- ReliabilityBench: https://arxiv.org/abs/2601.06112
+- LangSmith evaluation concepts: https://docs.langchain.com/langsmith/evaluation-concepts
+- OpenAI agent evals: https://developers.openai.com/api/docs/guides/agent-evals