12.3 可观测性与调试

12.3.1 可观测性的三大支柱

日志（Logs） 记录系统运行的详细事件

指标（Metrics） 量化的系统状态数据

追踪（Traces） 请求在系统中的完整路径

12.3.2 上下文相关的关键指标

指标	说明	告警阈值（示意）
上下文 Token 数	每次请求的上下文大小	接近窗口上限
检索延迟	检索操作耗时	以 SLO 与基线为准
检索命中率	检索到相关结果的比例	以基线与业务验收为准
压缩率	压缩后/压缩前	异常波动
成本/请求	单次请求的成本	超出预算

12.3.3 日志设计

结构化日志

{
  "timestamp": "2024-03-01T10:00:00Z",
  "request_id": "req_123",
  "stage": "context_build",
  "input_tokens": 500,
  "retrieved_chunks": 5,
  "context_tokens": 2000,
  "duration_ms": 150
}

日志级别

• ERROR：失败的操作

• WARN：接近限制、降级处理

• INFO：关键流程节点

• DEBUG：详细调试信息

12.3.4 请求追踪

完整追踪请求处理流程：

request_123
├── 接收请求 [0ms]
├── 查询处理 [10ms]
├── 知识检索 [120ms]
│   ├── 嵌入计算 [30ms]
│   └── 向量搜索 [90ms]
├── 重排序 [50ms]
├── 上下文构建 [20ms]
├── 模型调用 [800ms]
└── 响应返回 [1000ms]

12.3.5 上下文快照

保存关键请求的完整上下文：

if should_snapshot(request):
    save_snapshot({
        "request_id": request.id,
        "full_context": context,
        "retrieved_docs": docs,
        "model_response": response,
        "metadata": {...}
    })

用于：调试问题、效果分析、回放测试

12.3.6 调试技巧

问题定位流程

常见问题诊断

症状	可能原因	检查点
答案不相关	检索问题	检索结果、嵌入质量
答案不完整	上下文不足	上下文内容、压缩程度
幻觉	缺乏依据	是否有相关知识
响应慢	瓶颈	各阶段耗时

12.3.7 监控仪表盘

建立可视化监控：

• 实时请求量和延迟

• Token 使用分布

• 错误率趋势

• 成本累计

12.3.8 告警设置

配置关键告警：

• 错误率超过阈值

• 延迟异常升高

• 成本超出预算

• Token 接近上限

12.3.9 常用可观测性工具（示例）

以下列举若干在业界较常见的工具/产品方向（以各工具最新能力与版本为准）：

LangSmith (LangChain)

• 特点：全链路追踪，Prompt 编排，数据集评估。与 LangChain 生态集成度高。

• 适用：LangChain 用户，需要完整 DevOps 流程的团队。

LangFuse

• 特点：开源，支持自托管，详细的 Trace 和 Score 功能。

• 适用：注重数据隐私，需要开源解决方案的团队。

Arize Phoenix

• 特点：专注于 LLM Tracing 和 Evaluation，提供 Notebook 环境下的可视化。

• 适用：数据科学家，需要深入分析 Trace 的场景。

Weights & Biases (W&B)

• 特点：传统的 ML 实验追踪工具，增加了 Prompts 和 LLM 监控功能。

• 适用：已有 W&B 工作流的 ML 团队。