LLM 应用的可观测性
在传统软件中，可观测性通过采集日志、指标和追踪信息帮助开发者掌握系统内部状态。而在 LLM 应用中，可观测性还需要覆盖模型的输入、输出及中间执行步骤。由于 LLM 具有不确定性，相同输入可能产生不同甚至超出预期的结果，排障难度高于传统确定性应用。通过持续记录模型交互细节与性能数据，可观测性能够帮助开发者看清“黑箱”模型的实际运行行为。
有效的可观测性为何重要
- 可靠性与调试：当应用返回错误回答、异常结果或运行报错时，结构化日志与链路追踪可以还原请求流经各组件的完整过程，辅助定位根本原因——例如区分某次错误回答究竟源于提示词设计不当、检索失败，还是模型自身的幻觉。
- 优化与性能：用户希望 LLM 应用快速、高效，但模型可能响应缓慢或消耗大量资源。可观测性可以记录延迟、吞吐量等关键指标，定位性能瓶颈。监测请求延迟、token 使用量和系统资源，可以识别需要优化的环节。使用量数据也有助于发现提示词或模型选择中的低效之处，从而优化成本。
- 注意：多数现代 LLM 可观测性平台尚未直接提供系统级硬件资源指标的原生追踪能力。
- 质量保障：开发阶段的测试集难以穷尽真实生产环境中的全部交互方式与边界情况。通过在线记录模型输出与用户反馈，可以持续统计低质量回答或幻觉的出现频率，及时发现实际表现与预期目标之间的差距。
简言之，LLM 应用的可观测性通过收集和分析运行产生的日志、指标与追踪数据，帮助开发者理解、调试和持续改进不确定性系统。
可观测性的三项基础
现代可观测性体系通常由日志（Logs）、指标（Metrics）和追踪（Traces）三部分构成。
1. 日志（Logs）
日志记录应用运行过程中的具体事件与数据。对于 LLM 应用，建议采用结构化日志记录提示词、响应与异常：
- 用户输入和提示词：记录发送给 LLM 的完整输入（含系统提示词）及所用提示词模板的版本号，便于在输出异常时追溯触发问题的具体提示词版本。
- LLM 输出：记录模型的原始返回文本；若下游还包含解析或格式转换步骤，可同时保存原始输出与解析后的结果，以便排查解析失败原因。
- 错误与异常：统一记录 LLM API 返回的限流、超时等接口错误以及应用自身的代码异常，用于统计失败率并区分问题来自应用逻辑还是外部 API。
- 元数据：为每条日志附带时间戳、请求 ID 或会话 ID、模型名称与版本等字段，支持按条件筛选（如检索特定模型版本的全部输出）或按时间线回溯问题。
LLM 应用的日志记录范围通常比传统应用更广。保留完整的请求与响应记录，便于事后按内容检索特定交互（例如排查模型多次复述同一错误事实的历史记录）并审查系统行为。
指标
指标用于按时间序列量化追踪 LLM 应用的性能与资源消耗。常见核心监测指标包括：
- 延迟：处理单次请求的耗时，既可统计从用户发起请求到收到回答的端到端延迟，也可按 LLM API 调用、向量检索等子步骤分别统计，用于及时感知性能退化。
- 吞吐量与请求速率：每秒或每分钟处理的请求数，用于确认系统扩展能力、控制预算成本，并观察流量突增或日内波动规律。
- token 使用量：分别统计每次请求的输入与输出 token 数量。若提示词过长或模型生成了不必要的冗长回答，均可从该指标中反映出来；同时监测单次请求与累计 token 消耗，有助于及时发现意外的成本增长。
- 提示词长度：按 token 数或字符数记录提示词长度，防止提示词模板或拼接的检索上下文过长而拖慢响应乃至超出模型上下文窗口限制。
- 错误率：统计报错或失败请求所占比例（可按错误类型细分）。错误率上升直接反映系统可靠性受损，例如当 5% 的请求出现超时时，需及时排查原因。
- 资源使用量：在自托管模型推理服务或向量数据库时，还应追踪 CPU、GPU 利用率与内存占用等系统级指标。
- 评估分数：在预算允许的范围内，对生产环境流量执行在线 LLM 评估，及早发现在开发阶段未覆盖的边界情况，为后续迭代提供依据。
采集上述指标后，可通过监控仪表板持续跟踪变化趋势，例如分别配置“每小时平均延迟与吞吐量面板”和“每日 token 总消耗与费用面板”。
追踪
追踪用于还原单次请求流经 LLM 应用各组件的完整执行路径。一次 Trace 代表一次用户交互从开始到结束的端到端过程，由一个或多个 Span 组成；每个 Span 对应工作流中的一个具体步骤或子操作。
下图展示了一个朴素检索增强生成（RAG）工作流的追踪结构：
整条 Trace 覆盖从用户提交查询到收到最终答案的端到端数据流，包含三个主 Span 及各自的子 Span：
这一流程包含三个主要 span：
A．查询改写与增强
包含一个子 span：
1 改写用户的原始查询。
B．检索
包含两个子 span：
2 为查询生成嵌入向量。
3 从向量数据库中检索与查询嵌入最接近的前 kkk 个元素。
C．生成
同样包含两个子 span：
4 将用户查询和检索上下文填入提示词模板，拼装完整提示词。
5 将完整提示词提交给 LLM，并将生成的答案返回给用户。
对于包含多步调用链或智能体的复杂 LLM 应用，追踪尤为关键。例如，当 Trace 显示向量搜索耗时 500 毫秒而 LLM 调用耗时 2 秒时，开发者即可直观定位耗时瓶颈。追踪在 LLM 应用中的核心作用包括：
追踪在 LLM 应用中的主要价值包括：
- 端到端可见性：完整展示每次用户查询依次经过的数据检索、工具调用、模型生成与后处理步骤。面对执行顺序动态变化的智能体或多步骤系统，按时间轴排列的 Trace 有助于准确还原真实执行路径。
- 各步骤延迟拆解：记录每个 Span 的独立耗时。当用户反馈响应慢时，可快速判断是 90% 的时间花在 LLM 推理上，还是某次外部搜索 API 工具调用拖慢了整体响应。
- 逻辑与错误调试：记录每个 Span 的输入与输出。报错时可直接定位故障 Span；最终答案有误时，则可逐级回查中间步骤（例如排查检索阶段是否漏掉了关键上下文，或召回了无关内容）。
- 理解智能体决策：对于动态决定是否调用工具的智能体，逐步查看 Trace 记录有助于还原其决策链路，分析智能体为何触发某个动作或为何陷入重复循环。
对 LLM 应用的日常观测需兼顾系统性能（延迟、吞吐量、错误率、成本）与模型行为（回答质量、出错频率、输入处理方式），并配套仪表板与异常告警，支持工程师及时发现问题并持续优化。
追踪知识查询的阶段
在实际知识查询链路中，将 source-read、chunk、embedding、retrieve、acl-check 和 generation 作为独立阶段分别记录。自托管的 Langfuse 仅接收经过脱敏处理的请求 ID、版本号、token 用量与错误信息，日志中严禁保存密钥。通过对比资料读取延迟与模型推理延迟，并确认权限校验失败能够准确定位到具体阶段，保障链路可查。
练习：记录本课所用配置、输入、预期结果与失败分支，并用脱敏数据复现。