AI 服务可观测性：Trace 里要看见一次 Prompt 的旅程

传统微服务 Trace 关注 HTTP 调用、数据库查询和消息队列。AI 服务多了 Prompt、检索、重排、模型调用、输出校验和安全策略。如果 Trace 里看不到这些节点，排查问题时只能知道“请求慢了”，却不知道慢在检索、模型还是格式修复。AI 服务可观测性要让一次 Prompt 的旅程变得可见。

可观测不是为了做漂亮看板，而是为了在事故里快速回答：发生了什么，影响谁，为什么。

一、Trace 要覆盖 AI 节点

sequenceDiagram
  participant U as User
  participant A as API
  participant R as Retriever
  participant M as Model
  participant V as Validator
  U->>A: request
  A->>R: retrieve docs
  A->>M: generate
  A->>V: validate output

一次 AI 请求至少要拆出输入预处理、检索、重排、Prompt 构造、模型调用、输出解析、校验和持久化。每个节点记录耗时、状态和关键元数据。这样 TP99 上升时，才能定位到具体阶段。

注意不要把完整 Prompt 和用户数据直接写进 Trace。可以记录 prompt_template_id、输入长度、检索文档数量、模型名、token 数、校验结果。可观测性不能成为隐私泄露的新入口。

二、模型指标要结构化

{
  "model": "answer-v3",
  "input_tokens": 1820,
  "output_tokens": 430,
  "ttft_ms": 620,
  "total_ms": 4800
}

模型调用不能只记录总耗时。输入 token、输出 token、首 token 延迟、总耗时、流式中断、重试次数、供应商错误码都很重要。成本、性能和质量都依赖这些指标。

如果有模型路由，还要记录路由原因。为什么这次用了小模型，为什么回退到大模型，为什么跳过重排。否则后续质量问题很难解释。

三、检索证据要可追踪

retrieval:
  query_id: q_1024
  top_k: 8
  hit_count: 8
  source_collections:
    - docs_v2

RAG 问题经常来自检索。回答错了，不一定是模型幻觉，也可能是检索没命中、命中了旧文档、权限过滤过严或重排把关键文档排后面。Trace 里要记录检索集合、top_k、命中数量、过滤数量和文档版本。

证据追踪还要支持离线复现。给定 trace_id，能找到当时使用的模板、模型版本、检索配置和文档版本。没有复现能力，可观测只能停留在“看起来知道发生了什么”。

四、告警要结合质量信号

alerts:
  model_error_rate
  validation_failure_rate
  retrieval_empty_rate
  prompt_template_regression

AI 服务的告警不能只有 5xx 和延迟。输出 JSON 校验失败率、检索为空比例、安全拦截率、模型回退率、用户重试率，都可能预示质量问题。质量退化有时不会变成错误码，但用户已经感受到不好用。

告警要能指向动作。检索为空升高，检查数据同步；校验失败升高，检查 Prompt 或模型版本；回退率升高，检查供应商或路由策略。没有动作路径的告警，最后会被忽略。

五、总结

AI 服务可观测性要让一次 Prompt 的旅程可见：检索、Prompt 构造、模型调用、输出校验、成本和质量信号都要进入 Trace。

看得见链路，才托得住系统。AI 应用越复杂，越需要把那些“模型里面发生了什么”的黑箱边界往外照亮一点。