06-evaluation-observability-playbook

06. Evaluation 与 Observability Playbook

Agent 工程的核心不是一次性把 demo 做出来，而是持续知道它在哪里失败、为什么失败、如何修复、修复是否有效。

基本闭环

推荐闭环：

1. 线上请求进入 LangSmith trace。
2. 用户反馈或 evaluator 发现失败。
3. 失败 trace 进入人工复盘。
4. 典型失败样例加入 dataset。
5. 修改 prompt / tool / retriever / workflow。
6. 运行 experiment 验证变化。
7. 通过后上线。
8. dashboard 和 alert 继续监控。

Trace 应该记录什么

最少需要：

• user input
• user / tenant / session metadata
• prompt version
• model name
• model input / output
• tool name
• tool input / output
• retrieval query
• retrieved chunks
• final answer
• latency
• token
• cost
• error
• user feedback

注意：不要无脑记录敏感信息。需要配合 PII redaction 和权限策略。

如何读一次失败 trace

按这个顺序看：

1. 用户真实意图是什么？
2. Agent 是否理解成了另一个任务？
3. prompt 是否给了错误或不足的指令？
4. 是否调用了正确工具？
5. tool input 是否正确？
6. tool output 是否足够？
7. 检索内容是否相关？
8. 模型是否被错误上下文误导？
9. final answer 是否违反输出 contract？
10. 失败是否已有 eval 覆盖？

Dataset 设计

Dataset 不应该只放「正常问题」，必须覆盖真实风险。

建议分类：

• happy path
• ambiguous request
• missing context
• retrieval failure
• conflicting context
• tool failure
• permission boundary
• prompt injection
• PII / sensitive data
• destructive action
• no-answer
• long context

每条样例建议包含：

• input
• expected behavior
• reference answer
• category
• risk level
• notes
• source trace link

Eval 类型

Correctness Eval

判断回答是否正确。适合有 reference answer 的任务。

Groundedness Eval

判断回答是否被检索证据支持。适合 RAG。

Citation Eval

判断引用是否真实支持回答中的关键主张。

Tool-use Eval

判断是否调用了正确工具、参数是否正确、是否不该调用工具。

Refusal Eval

判断 Agent 在缺少证据、越权请求或不安全请求时是否拒绝。

Trajectory Eval

判断中间步骤是否合理。适合 multi-step Agent 和 LangGraph workflow。

Latency / Cost Eval

判断质量提升是否以不可接受的成本或延迟为代价。

Failure Taxonomy

建议把失败归类，避免每次只修单点。

常见类别：

• intent_misunderstanding
• bad_prompt_instruction
• wrong_tool_selected
• invalid_tool_arguments
• tool_error_not_handled
• retrieval_miss
• retrieval_noise
• hallucinated_answer
• missing_citation
• unsafe_action
• permission_violation
• poor_user_experience
• excessive_latency
• excessive_cost

Experiment 比较方式

不要只比较平均分。至少看：

• 总体分数
• 分类分数
• 高风险样例分数
• latency p50 / p95
• cost
• regression cases
• new failure cases

推荐输出：

• 哪些样例变好
• 哪些样例变差
• 哪些类别仍然失败
• 是否值得上线
• 上线后需要监控什么

CI Eval Gate

适合进入 CI 的 eval：

• 核心 happy path
• 高风险拒绝
• 关键工具调用
• 关键 RAG 问题
• 历史线上事故样例

不适合每次 CI 都跑的 eval：

• 超大 dataset
• 高成本 LLM-as-judge
• 长时间端到端评估

实践方式：

• PR 上跑小型关键 dataset。
• nightly 跑完整 dataset。
• prompt / retriever / workflow 修改强制跑相关 eval。

参考：LangSmith CI/CD Pipeline Example。

Dashboard 建议

质量

• feedback score
• evaluator score
• failure rate
• no-answer rate
• hallucination risk
• citation correctness

工具

• tool call count
• tool success rate
• tool error rate
• top failing tools
• destructive action approval rate

RAG

• retrieval hit rate
• empty retrieval rate
• average chunks
• citation rate
• groundedness score

性能和成本

• request count
• latency p50 / p95
• token per request
• cost per request
• cost by model
• cost by feature

参考：LangSmith Dashboards。

Alert 建议

可设置 alert：

• error rate 突然上升
• p95 latency 超阈值
• cost per request 超阈值
• feedback negative rate 超阈值
• evaluator score 下降
• tool failure rate 上升
• no-answer rate 异常变化

参考：LangSmith Alerts。

从失败到修复的模板

每次复盘失败时，写清楚：

## Failure
 
- Trace:
- User input:
- Expected behavior:
- Actual behavior:
- Failure category:
- Risk level:
 
## Root Cause
 
- Prompt:
- Tool:
- Retrieval:
- Workflow:
- UI:
- Policy:
 
## Fix
 
- Change:
- Why this should work:
 
## Verification
 
- Dataset cases added:
- Experiment result:
- Regression risk:
- Monitoring after release:

这个模板可以直接变成作品集中的 case study。