Trace 可观测

🎯 学习目标

• 为每次请求分配 trace_id 并串联 LLM、检索、工具 span
• 记录 Token、耗时、成本与检索 chunk id
• 用 Trace 复现用户投诉与定位幻觉根因

引言

线上问题无法复现，90% 是因为没存当时发给模型的完整上下文。Trace 是 LLM 应用的「飞行记录仪」。

章节正文

第 1 步：必须记录的字段

字段	用途
trace_id / session_id	端到端关联
prompt_version	对比回归
model, temperature	复现生成
input_messages（脱敏）	看实际 Prompt
retrieval: chunk_ids, scores	判断 RAG 是否命中
tool: name, args, result, latency	Agent 调试
tokens_in/out, cost_usd	成本归因
error_stack	失败分析

第 2 步：LangChain Callback 示例

from langchain_core.tracers import ConsoleCallbackHandler

chain.invoke(
    {"question": "..."},
    config={"callbacks": [ConsoleCallbackHandler()]},
)

# 生产：LangSmith
import os
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "..."
os.environ["LANGCHAIN_PROJECT"] = "prod-rag"

OpenTelemetry：将 span 导出到 Jaeger / Datadog，与现有 APM 统一。

第 3 步：从 Trace 诊断幻觉

流程：

1. 用户反馈「回答错误」→ 查 trace_id
2. 看 retrieval chunks：是否未命中正确文档？
3. 若命中仍错 → 模型问题或 Prompt 未强调「仅依据上下文」
4. 若 tool 参数错 → 工具 schema 或 Agent 循环问题

建立 Weekly Trace Review：抽 10 条低分 Eval + 10 条随机线上请求。

动手练习

1. 为 /api/chat 中间件添加 trace_id 响应头
2. 开启 LangSmith 或打印 ConsoleCallback，完成一次 RAG 请求并找到 retrieval span
3. 写一份「幻觉排查 checklist」3 步

本节小结

Trace 记录 Prompt、检索、工具、Token 全链路；LangSmith/OTel 接入；用 trace_id 复现与归因幻觉。