Trace 驱动的复杂问题排查

先描述现象，再讨论根因

AI 系统的“结果不对”可能来自多个阶段。排障第一步不是修改 Prompt，而是把用户看到的现象写成可验证的问题：

• 是没有候选，还是候选被过滤？
• 是页面没有展示，还是后端没有生成？
• 是新任务复现，还是页面读取了历史 Trace？
• 是一个节点错误，还是多个节点合并时发生了丢失？

我的五步方法

1. 锁定任务和时间窗口

通过任务 ID、消息 ID、页面链接和发生时间找到唯一执行。先确认页面读取的是新 Trace 还是历史 Trace，避免把部署后的代码与旧数据混在一起。

2. 找首个异常节点

沿 DAG 顺序查看每个 observation 的状态和输入输出。首个异常节点通常比最后一个空结果更接近根因；后续节点只是被上游空值连带影响。

3. 对比原始 payload 与派生字段

重点检查模型候选、查询候选、过滤集合、过滤原因、后置动作和来源分类等字段。要区分：

• 模型有没有提取出候选对象。
• 查询阶段有没有查到候选。
• 过滤阶段把哪些对象移入了哪个集合。
• 结果整理阶段是否保留了候选，是否因为没有候选而返回空动作。

4. 划清责任边界

把问题归类为 AI 输出、后端规则、DAG 路由、消息重试、前端展示或历史脏数据。比如模型已经返回空的噪声结果，但页面仍展示旧内容，问题在展示聚合；又比如部署了新的数据填充逻辑，但页面仍读取旧 Trace，重新部署不会改变历史结果。

5. 固化回归证据

将复现输入、关键 payload、预期集合变化和验证结果写进测试或案例文档。下一次再遇到类似问题，可以直接比较节点输出，而不是重新凭感觉排查。

一个典型分析框架

用户现象：页面没有显示候选结果
        │
        ├─ Trace 中模型有候选结果？
        │       ├─ 否：检查 Prompt / 输入 / 模型输出
        │       └─ 是：继续检查搜索与过滤
        │
        ├─ 查询阶段是否存在候选？
        │       ├─ 否：检查查询构造和 API
        │       └─ 是：检查 filter_reason 和最终 tokens
        │
        └─ 结果有值但页面为空？
                └─ 检查回调、接口映射、前端读取的 Trace 版本

沟通方式

排障结论要同时给出证据和边界：先说确认了什么，再说尚未验证什么；明确受影响的是候选集合、排序结果、展示卡片还是消息状态。与产品、前端和 QA 沟通时，我尽量用“阶段 + 字段 + 现象”表达，而不是只说“AI 有问题”。

小结

Trace 驱动排障的核心是建立证据链：现象 → 首个异常阶段 → 原始输入输出 → 集合变化 → 根因 → 回归验证。它不仅适用于公司项目，也适用于任何包含 LLM、异步任务和多阶段数据处理的系统。