04 人工调查

以下学员课程的讲师配套材料： 04 人工调查的讲师配套材料。

时间安排

总计约 20 分钟。

• 3 分钟 — 筛选负面反馈并核实权威的 Chat 根节点。
• 4 分钟 — 创建三个评分配置，然后创建带固定附件的队列。
• 4 分钟 — 在讨论诊断结论之前，先对可观察行为进行开放式编码。
• 5 分钟 — 检查 trace 证据，并并排运行 policy-v1/policy-v2 SQL。
• 4 分钟 — 录入修正结果、批准、完成，并记录溯源信息。

讲师预检

在学员到场之前，确认模块 03 已生成唯一权威的 chat_turn，其 Boolean 型 user-thumbs=false 且 sql-execution-success=true。对其 trace ID 保密，并确认根输出 包含问题、生成的 SQL、返回的行，以及结果。

如果需要预演，可以在一次性测试项目中创建三个评分配置， 但不要提前为学员创建最终队列。队列所附加的评分配置 ID 集合在创建时即固定，因此全班应先创建好配置，再一次性附加全部 三个：

这项标注练习是纯 UI 操作。运行时脚本可以校验 trace 分数并 在之后推广已审核的导出结果，但脚本不会创建队列、写入人工 判断，也不会完成标注任务。

讲解流程

1. 在 Tracing 中筛选 user-thumbs = false，并匹配 模块 03 工作表中的 trace ID。可以这样说：“反馈决定我们接下来调查什么， 而不是决定我们的结论是什么。”

2. 使用 Settings → Scores → Create 为每个评分配置创建条目。然后使用 Annotations → Queues → Create，将队列命名为 production-investigation-<session>(带唯一的会话后缀)，并附加全部 三个配置。

3. 选中根 chat_turn observation，打开其 Annotate 下拉菜单，并选择 新创建的队列。展示子级 llm_call，但要说明为什么它是错误的目标： 它缺少端到端的结构化执行结果，也不是逻辑上的 反馈事件本体。

4. 提醒学员，模块 03 已经透露了预置场景，请他们先搁置 这一先验知识，练习基于可观察证据的开放式编码。一条好的初始记录示例是：

   The SQL executed and returned a count. The observed count differs from the second
   reference count. The query uses a 90-day customer signup window, and the trace
   metadata reports policy-v1.

5. 只有在全班记录下这条笔记之后，才揭示完整证据：发出的元数据 policyversion=policy-v1、基于注册日期的 SQL/结果，以及那两个分数。 来源字段是 policy_version；OpenTelemetry 适配器发出经过净化的 Langfuse 键 policyversion。

6. 并排运行两个策略定义。policy-v1 参考查询是：

   SELECT count() FROM v_customers
   WHERE signup_date >= today() - INTERVAL 90 DAY

   policy-v2 当前策略参考查询是：

   SELECT uniqExact(customer_id) FROM v_orders
   WHERE order_ts >= now() - INTERVAL 30 DAY
   AND status NOT IN ('cancelled', 'returned')

7. 只有在完成这一对比之后，才应用诊断结论：记录 failure-category=stale-business-policy，将 Corrected Output 切换为 plain-text mode，并粘贴原始的当前查询。Langfuse 不会执行 SQL，因此在设置 approved-for-golden=true 并完成任务之前， 请通过第 6 步中的只读客户端验证这段确切文本。

8. 为模块 05 保留 source_trace_id、failure_category、source_policy_version、 修正内容，以及可选的标注任务 ID。

三种有诱惑力但错误的诊断

• “模型忽略了提示词。” trace 中的 SQL 遵循了明确给出的 policy-v1 上下文。问题在于已过期的部署策略，而不是模型 违背了给定的指令。
• “sql-execution-success 出问题了。” SQL 确实执行成功了，因此 这个操作型评估器正确地返回了 true。它的设计本就不检验受治理的 业务含义。
• “点了 thumbs-down 就证明 SQL 是错的。” 反馈只是指出了一条值得 审查的 trace。它并不能消除用户意图的歧义，也不能提供经过验证的 替代查询；真正做到这些的是并排的策略核对与人工审查。

在学员完成对该 trace 的开放式编码之前，请让这些备选解释保持可见。 讲师本人已经知道预置的答案，但这次调查仍应模拟一次真实的 以证据为先的审查。

根 observation 的选取

trace 中有两个相关的 observation:

如果学员误将子级添加进去，不要把它当作生产调查来完成。 应将根 chat_turn 添加到正确的队列，并按项目的保留策略 保留/删除那个误建的任务。保留的应是 trace ID，而不是子级 observation ID，记作 source_trace_id。

固定的队列附件与可安全重置的命名

Langfuse 会在队列创建时就固定其所附加的评分配置 ID 集合。 队列之后无法附加遗漏的配置，因此最安全的做法是先创建好全部配置。 评分配置本身是可变的：受支持的名称、schema 或分类值编辑 需要经过审计的评分配置更新，而该更新不会改写已有的分数。

使用可安全重置的后缀，例如：

production-investigation-<session>-retry-1

如果队列遗漏了某个配置或附加了错误的配置 ID，请创建一个带新后缀的 队列，附上全部三个正确的 ID，再次添加权威根节点，并明确将 旧队列标记为已废弃(仅在项目策略允许的情况下才可移除)。对于已附加 配置的受支持编辑，应使用经过审计的评分配置更新，而不是重新创建队列。 切勿以掩盖决策来源的方式重复使用一个已完成的队列名称。

修正结果的可靠性

这项修正将成为未来的黄金标准真值，因此语法与策略都很重要。 在粘贴原始 SQL 之前，先将 Corrected Output 切换为 plain-text mode。 Langfuse 会存储这段文本但不会执行它；在批准之前，必须通过 第 6 步中的只读 ClickHouse 客户端执行这段确切的文本。任何看起来正确、 但实际格式有误、引用了原始表、包含多条语句，或在 ClickHouse 中执行失败的 查询，都必须保持未批准状态。

对于格式有误的 SQL:

1. 将 approved-for-golden 设为或保持 false；
2. 不要将任务标记为已批准并完成；
3. 针对被允许的 v_* 视图修正该查询；
4. 重新运行并检查结果；并且
5. 只有在验证通过之后才批准并完成。

如果有人已经完成了一个格式有误的修正，请创建一个新的队列/任务后缀 重新进行审查，而不要悄悄编辑掉审计痕迹。模块 05 的 推广命令也会校验并执行只读 SQL，但那道防线不能替代人工审查。

常见问题

• 筛选后没有 trace — 确认分数类型为 Boolean，且筛选条件为 user-thumbs=false；不要去搜索一个旧的分数名称。应匹配工作表中的 trace ID，而不是选中那条未评分的 curl 诊断记录。
• 目标选错 — 任务里只显示了对话记录/SQL，原因是添加了 llm_call。 返回该 trace，改为添加根 chat_turn。
• 队列维度缺失 — 队列创建时缺少了某个必需的附加配置 ID。请创建一个 带新后缀的队列；不要在一个不完整的审查表单上继续操作。对于已附加 配置的受支持编辑，应使用经过审计的配置更新，而不是重新创建队列。
• 策略元数据看起来不存在 — 应查找发出的 policyversion，而不是 来源字段 policy_version，然后确认根节点上的 policy-v1 标签。
• 计数意外相符 — 停止诊断。重新运行模块 03 的场景预检， 不要在没有对照的情况下凭数据快照捏造证据。
• 修正内容是格式化文本而非原始 SQL — 将 Corrected Output 切换为 plain-text mode，并只粘贴查询本身。
• 修正内容无法执行 — Langfuse 不会捕获这个问题。保持批准状态为 false, 修正它，并在完成任务之前通过第 6 步的客户端重新运行这段确切的文本。

完成与交接

在进入模块 05 之前，请核实已完成的任务对应的是权威的 chat_turn，观察记录是在诊断之前录入的，修正内容是准确的 当前策略 SQL，并且该任务已被批准。学员工作表必须包含：

source=production-feedback
source_trace_id=<authoritative Chat trace ID>
failure_category=stale-business-policy
source_policy_version=policy-v1
annotation_id=<task ID when available>

那个负面用户评分会一直保留在生产 trace 上，作为分拣信号。 人工标注则提供了经过审查的真值。模块 05 在推广该修正并 构建预防性评估器时，会同时保留这两个来源。