这是《LLM 应用开发 零基础实战指南》的独立章节版。本章从概念、实操和生产排查三个视角展开，代码块保留了原书可直接运行的版本。 LLM 应用的行为不确定，更需要完整记录每次请求的输入、配置、检索、工具、模型输出、校验结果和用户反馈。可观测性用于排障、归因、评测、成本和审计。
27.1 三支柱
| 支柱 | 内容 |
|---|---|
| Logs | 事件和错误 |
| Metrics | 聚合指标 |
| Traces | 跨模块调用链 |
推荐额外增加：
- Prompt 版本；
- 模型版本；
- 检索版本；
- 工具版本；
- 原始输出；
- 评分结果；
- 用户反馈。
27.2 Trace 结构
trace_id
|-- auth
|-- query_rewrite
|-- embedding
|-- dense_search
|-- keyword_search
|-- rerank
|-- llm_call
|-- guardrail
+-- response
Span 示例：
{
"trace_id": "t-1001",
"span_id": "llm-1",
"parent_id": "pipeline-1",
"name": "llm_call",
"status": "success",
"duration_ms": 2300,
"attributes": {
"model": "chat-mini",
"prompt_version": "v3",
"input_tokens": 1800,
"output_tokens": 220
}
}
27.3 日志字段
基础字段：
| 类别 | 字段 |
|---|---|
| 请求 | trace_id、user_id、tenant_id、session_id |
| 配置 | app、prompt、model、index、policy 版本 |
| 检索 | query、candidate_ids、selected_ids、scores |
| 模型 | tokens、finish_reason、latency |
| 工具 | name、args_digest、status、duration |
| 输出 | answer_digest、parse_ok、citation_ok |
| 业务 | scene、risk、feedback |
敏感数据要脱敏，正文可加密并按需采样。
27.4 指标
质量：
- 解析成功率；
- schema 通过率；
- 引用通过率；
- 自动解决率；
- 转人工率；
- 用户点赞率；
- 幻觉抽检率。
技术：
- QPS；
- 错误率；
- p95/p99 延迟；
- 模型 429/5xx；
- 工具失败率；
- 队列长度；
- 缓存命中率；
- token 和成本。
27.5 回放
回放需要的最小数据：
原始用户输入
权限主体标识
Prompt 渲染参数
检索候选 ID 和分数
工具输入输出摘要
模型配置
最终输出
校验结果
回放模式：
| 模式 | 用途 |
|---|---|
| 原配置重放 | 复现问题 |
| 新配置重放 | 对比修复 |
| 脱敏重放 | 团队协作 |
| 离线评估 | 回归测试 |
27.6 告警
| 告警 | 条件示例 |
|---|---|
| 错误率 | 5 分钟 > 2% |
| 限流 | 429 快速上升 |
| 延迟 | p95 超过 SLO |
| 成本 | 每小时超预算 |
| 护栏拦截 | 异常突增 |
| 引用失败 | > 1% |
| 转人工 | 同比突增 |
| 模型输出为空 | 连续出现 |
告警应带 trace 示例和看板链接。
27.7 隐私
日志治理：
- 明确数据分级；
- 最小化记录；
- 身份和数据加密；
- 访问权限控制；
- 保留周期；
- 审计访问；
- 用户删除流程；
- 外部传输限制。
开发环境不应直接复用生产明文日志。
27.8 排障流程
用户反馈
-> 找 trace
-> 检查版本组合
-> 检查输入和上下文
-> 检查检索结果
-> 检查工具轨迹
-> 检查输出校验
-> 复现和修复
归因示例：
| 现象 | 可能层 |
|---|---|
| 答非所问 | 查询改写或检索 |
| 引用错 | 映射或模型 |
| 数值错 | 未走程序计算 |
| 权限错 | 过滤和缓存 |
| 格式错 | Prompt 和解析 |
| 超时 | 模型、工具或队列 |
27.9 实验观测
实验必须记录：
- 实验 ID；
- 分流规则；
- 用户和请求样本；
- 版本组合；
- 质量指标；
- 成本指标；
- 护栏指标；
- 结束时间。
避免只看请求成功率，不看答案质量和风险。
本章小结
可观测性把不确定的模型行为变成可排查的数据。要记录版本化 trace、组件指标、用户反馈和可回放上下文，同时做好脱敏和权限治理。没有 trace 的 LLM 系统很难持续迭代。
思考题
- 为什么版本信息是 trace 的关键字段？
- 回放需要保存哪些最小数据？
- 日志脱敏和质量排查如何平衡？
- 转人工率突增应如何归因？
- 哪些告警适合配置成发布阻断？