05 闭合改进循环

配套学习者文档： 05 闭合改进循环。

时间安排

总计约 25 分钟。

• 5 分钟——构建并推广三条源自生产环境的记录。
• 5 分钟——启动配对的 policy-v1 与 policy-v2 实验。
• 5 分钟——比较正确率并校准 business-policy-adherence。
• 5 分钟——启用受保护的观测规则并回放四类指标。
• 5 分钟——检查证据，讨论回滚、成本以及下一轮反馈循环。

这两个实验和异步评审器的运行时间可能超出这些环节的时长。请尽早启动运行，在等待期间讲解概念性内容，并提前一天演练提供商延迟情况。

讲师预检

在实验室根目录运行以下非变更性命令检查，并在会前确认所选配置存在：

cd ClickHouse_Demos/workshops/agent_arena
.venv/bin/python -m scripts.promote_to_golden --help
.venv/bin/python -m scripts.provision_online_evaluators --help
.venv/bin/python -m eval.harness --help
.venv/bin/python -m scripts.verify_online_scores --help

然后确认：

• 模块 03 存在一条权威的根 chat_turn，其 sql-execution-success=true，且布尔值 user-thumbs=false；
• 模块 04 中仅在 UI 中操作的 production-investigation-<session> 任务已完成，其 修正后的 SQL 已执行，其真实 trace ID 已私下留存，且当 Langfuse 暴露其标注任务 ID 时该 ID 已记录；
• reviewed.json 将由该真实审核生成，而不是那份已纳入版本控制的合成 fixture；
• WINNER_MODEL、WINNER_PROMPT 与 WINNER_CONFIG_ID 描述的都是同一个房间的获胜者；
• Langfuse LLM 连接 agent-arena-openrouter 能够访问其配置的评审模型，且凭证有效；
• 评审模型的结构化分类输出只接受 PASS、FAIL 与 NOT_APPLICABLE，并附带理由；以及
• 评审调度器状态正常，房间能够接收异步评分。

每次演练都要生成一个唯一后缀，并让基线/候选一对保持关联：

export LOOP_RUN_SUFFIX="$(date +%Y%m%d-%H%M%S)"
export BASELINE_RUN_ID="online-loop-baseline-${LOOP_RUN_SUFFIX}"
export CANDIDATE_RUN_ID="online-loop-candidate-${LOOP_RUN_SUFFIX}"

不要重复使用之前会话的运行 ID。harness 会追加策略版本与配置信息，唯一的基础 ID 能防止学习者比较到无关或部分被覆盖的证据。

人工标注的边界

模块 04 中的人工标注刻意不做自动化处理。运行脚本不会创建队列、填写人工判断、录入修正结果、批准该条目，或代为完成任务。当没有真实审核结果时，一份已纳入版本控制的合成 fixture 有助于讲师演练，但它始终标记为 source=synthetic-reviewed-fixture，并不能证明已完成一轮真实的人工标注流程。

在学习者路径中，使用真实的（未纳入版本控制的）reviewed.json。原始措辞来自一条真实的用户反馈问题。另外两条输入是审核者基于该已审核事件撰写的同义改写：

How many active customers do we have?
What is our active customer count right now?
How many customers qualify as active under our business definition?

这三条问题共享同一条真实来源 trace 和相同的标注溯源信息。请当面向学习者说明这一点，以免他们误以为这是三条独立的反馈 trace，而实际上只是一次生产事件。

推广的可靠性与溯源

在房间运行推广之前，先直接检查 reviewed.json，不要对其做任何投影处理。它必须包含精确的、修正后的只读 SQL，必需的生产环境溯源信息，以及三个唯一的安全 ID。推广流程会先校验完整的本地批次，再在执行 ClickHouse 查询或写入数据集之前，进行一次带身份验证的元数据读取。当元数据无法读取时它会采取失败关闭（fail closed）策略，并会拒绝一个 ID 冲突且真实生产溯源信息不同的条目。

一次完全相同的真实推广操作是幂等的。合成 fixture 需要显式传入 --synthetic-fixture 参数；它不能作为直接路径提供，也不能与 reviewed.json 组合使用。真实推广之后绝不要再运行它。如果报告了冲突，请保留两个来源，调查现有的数据集条目，只有当这些条目确实代表不同的已审核案例时才选用新的、经审计的 ID。

实验规则与观测规则

将下面这两种上下文清楚地展示在幻灯片或白板上：

配置脚本安装的是一个由目录驱动的通用评审器，而不是一个只针对活跃客户数的评审器。其 policy-v2 目录覆盖活跃客户、营收、浏览到购买转化率与毛利率；与这些无关的问题应判为 NOT_APPLICABLE。

--business-policy-experiments 阶段必须报告 online rule enabled=False。请以 Langfuse 规则界面作为第二重检查手段。随后的启用命令只能证明至少存在一条数据集范围内的 business-policy-adherence 评分，但它无法替代讲师的完整校准审查。

校准门槛

在相同的条目 ID、模型与提示词下比较基线与候选。仓库有 20 个 YAML 问题， 其中 q019 与 q020 是 few-shot 保留样例，因此干净项目从 18 个 Experiment 条目开始，提升三条后应有 21 个条目。经审核时复用的共享项目显示 22 个条目， 因为其中已有一条与本次事件无关的已批准旧条目；该快照从 16/22 提升到 19/22。 请把这组数字仅视为复用项目的验证证据，而不是要求学员复现的固定基数或结果。

除非以下所有门槛都通过，否则不要启用：

• 全部三个 prod-active-* 案例在 policy-v1 下都是 FAIL 且结果不正确，在 policy-v2 下都变为 PASS 且结果正确；
• 候选侧的营收 (q005) 与转化率 (q018) 均为 PASS；
• 一个普通计数问题 (q001) 为 NOT_APPLICABLE；
• 逐条比较所有已存在条目的 correctness，且不存在任何 1→0 的回退；
• 聚合正确率没有回退；以及
• 每个 Experiment 条目都具有 correctness、agent-arena-llm-judge，以及带有有效结构化输出的精确 business-policy-adherence 评分。

一个把每一次计数都判为 PASS 的评审模型即使候选表现看起来不错，其校准也是失败的。用 NOT_APPLICABLE 探针来证明策略适用性判断确实是一个真实存在的分类步骤。

异步评分与无评分排查

实验评估和观测评估都是异步的。harness 会等待所需的实验评分，而 scripts.verify_online_scores 默认会轮询线上 trace 评分长达 180 秒。不要因为评分暂未出现就频繁刷新、重建规则，或提前启用。

如果评分没有出现：

1. 确认预期的确切名称。实验使用 business-policy-adherence；线上服务观测使用 agent-arena-business-policy-online。
2. 确认评审调度器/执行工作进程状态正常。
3. 检查 agent-arena-openrouter 连接与评审模型的可用性。提供商延迟、速率限制或路由限制都可能导致评估处于挂起或失败状态，即便 agent 的响应本身是成功的。
4. 确认实验规则的目标是 arena-golden 数据集，且观测规则的目标是根 chat_turn 观测。映射必须暴露 $.question 和 $.sql。
5. 检查结构化输出。缺失分类、分类超出三个允许值范围，或缺少理由，都属于校准失败。
6. 如果配置脚本报告规则名称存在歧义，请停下来，先在 Langfuse 中解决重复的完全同名规则，再重试；不要去猜测哪个重复项被更新了。

保留失败的 trace 与评审证据。不要把一次提供商中断变成一个伪造的 PASS，也不要跳过缺失评分这道门槛。

回放指引

启用之后，明确以 policy-v2 重新启动服务，并使用学习者的这四个确切问题：

How many active customers do we have?
What was revenue in the last 30 days?
What is our view-to-purchase conversion rate for the last 7 days?
How many products are there?

要求每条 trace 都具备运行成功的结果。活跃客户、营收与转化率必须 agent-arena-business-policy-online=PASS；产品数量的结果必须为 NOT_APPLICABLE。

转化率这条请求存在一个已验证的随机性边界情况。最多允许在相同配置下重试一次，保留两次尝试的 trace ID 与结果，若两次尝试都未通过则停止。反复失败是需要调查的新生产证据，不是让你一直循环直到出现绿色结果的理由。

采样、成本与可靠性

工作坊规则使用采样率 1，以便每条符合条件的 trace 都能产出可见的证据。在生产流量下，对每一次请求都运行 LLM 评审模型会增加提供商成本、消耗速率限制配额，而且评分可能在用户收到响应之后才产生。应基于流量、事件风险、评审器成本/延迟以及所需覆盖率来选择采样率。让确定性的运行检查覆盖面保持宽泛；把昂贵的语义判断保留给真正值得为其付出成本的流量与指标。

评审器属于监控性质，不是请求路径上的授权环节。一个延迟出现的评审结果不应悄无声息地阻塞服务响应。应根据系统的服务级别目标(SLO)，把缺失的评分、分类偏移与信号不一致导向运维告警或审核积压队列。

回滚与重置

如果启用之后，观测评审模型产生了假通过、假失败、格式错误的输出，或成本/延迟不可接受：

1. 打开 Langfuse Evaluations，找到确切的观测规则 agent-arena-business-policy-online，将其切换为禁用(disabled)。
2. 确认新产生的 chat_turn 观测不再收到该线上规则的评分。
3. 保持 policy-v2、sql-execution-success 以及 👍/👎 继续运行，除非有各自的证据表明应停止；禁用一个有问题的评审模型不应重新引入已知的过期策略。
4. 将受影响的 trace 加入一个带后缀的人工标注队列，改进评审器目录/提示词以及黄金数据，然后重新执行一轮配对实验校准，之后才能重新启用。

要在不删除远端证据的情况下停止本地服务：

scripts/arena.sh stop

scripts/arena.sh down 还会移除工作坊使用的 ClickHouse 数据库与只读用户，但它不会删除 Langfuse 的数据集、Experiment 运行记录、标注队列或评分。不要把它当作评审器的回滚手段。

讲解要点：循环保持开放

• 最初的评审器之所以通过，是因为它的契约仅是“SQL 已执行”。用户的 👎 暴露了这一契约之外的价值判断失败。
• 人工审核把一个不确定的信号转变成了一个经过验证的诊断与修正。
• 生产环境溯源信息使该事件在进入黄金数据集时具备可审计性；同义改写在不虚构额外用户 trace 的前提下扩展了措辞覆盖面。
• 配对实验把策略变更与模型/提示词变更区分开来，并在上线前测试了这个通用评审模型。
• 线上出现 PASS 并不意味着用户反馈就此过时。未来若出现 agent-arena-business-policy-online=PASS 同时伴随 user-thumbs=false，恰恰正是应该重新启动调查的那种矛盾信号。

完成门槛

在房间能够展示以下全部六项证据之前，不要结束本模块：

1. 具备运行通过结果且带有负面用户信号的生产环境 trace；
2. 已完成的人工标注，以及经过验证的修正后 SQL；
3. 三条具有真实生产环境溯源信息的黄金数据条目；
4. 同一数据集上的基线/候选证据，且未出现现有正确率的回退；
5. 经过校准的 FAIL、PASS 与 NOT_APPLICABLE Experiment 证据；以及
6. 已在活跃客户、营收、转化率与一个普通计数问题上启用线上评分，同时持续的 👍/👎 依旧可用于下一轮循环。