03 发布并发现问题

讲师笔记：发布预置的过期策略，并演示一次真实的在线评估漏检。

时间安排

总计约 15 分钟。

3 分钟 — 说明"运营评估"与"用户价值"之间的区别。
4 分钟 — 演示预检流程，并在 policy-v1 上发布现场选定的配置。
4 分钟 — 在 Chat 中提出受策略约束的问题，并对该回答收集 👎。
4 分钟 — 定位该 Chat 轨迹，验证两个分数，并用 curl 复现问题。

前一天的预检

使用你预期现场会选出的确切获胜配置来运行以下命令。已验证的兜底配置是 qwen3.7-flash__P2_fewshot：

cd ClickHouse_Demos/workshops/agent_arena
source .env
export WINNER_CONFIG_ID="${WINNER_CONFIG_ID:-qwen3.7-flash__P2_fewshot}"
.venv/bin/python -m schema.gen_schema_context
.venv/bin/python -m scripts.check_online_eval_scenario \
  --config-id "$WINNER_CONFIG_ID"
.venv/bin/python -m scripts.provision_online_evaluators --operational

只有当某个措辞变体的首次结果为 ok/unknown 时，预检才会执行一次有界重试，并且只重试相同的措辞和配置。其他所有失败均为最终结果，任何措辞变体都不会被重试超过一次。

不要凭记忆推进。请在现场的实际环境中逐项确认以下内容：

stale_count 与 current_count 均存在且两者不同；
三项分类均为 policy-v1；
最后一行提示该事件是可复现的；
评估器 sql-execution-success 存在；且
规则 agent-arena-sql-execution-online 已启用。

对于 Qwen，需要禁用 OpenRouter 的 Settings → Privacy → Data Policies → Zero Data Retention → Non-frontier，才能让 Alibaba 路由具备资格。只有在完成该活动的数据处理要求审查之后，才能进行此项更改。学员需要使用受限额度的运行时密钥，绝不能使用讲师的配置密钥。

讲解要点

从现场在 Module 02 中实际选出的获胜配置开始，把 WINNER_CONFIG_ID 写在所有人都能看到的地方。Agent 核心与所选配置保持不变；唯一被故意设置为落后一个版本的是所部署的业务策略上下文。
在展示结果之前先说明该评估器的边界：sql-execution-success 只能证明 ClickHouse 接受了这条 SQL，不能证明该 SQL 实现了当前对某个受治理指标的含义。
在 Chat 中提问，展示其生成的 SQL、结果以及 policy_version=policy-v1，然后点击 👎 并等待出现 feedback sent。这条 Chat 根轨迹是唯一权威的事件记录。

向听众并排展示当前的定义：

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

明确指出：在提供给模型的过期 policy-v1 之下，生成的基于注册（signup）的 SQL 是有效的。这是一次发布/流程失败以及评估器盲点问题，并不是说模型忽视了明确的指令。
在 Langfuse 中筛选 user-thumbs = false，打开最新匹配的 Chat chat_turn，把 sql-execution-success=true 与 user-thumbs=false 并列展示。该信号只是用于确定调查的优先级；它本身既不提供诊断结论，也不能作为事实依据。
之后运行必做的 curl 复现步骤，作为一次不参与评分的诊断操作。将其标识命名为 CURL_TRACE_ID，只验证 sql-execution-success=true，绝不为它提交 feedback，也不能把它用作 Module 04 的交接材料。
为 Module 04 记录根轨迹的 ID/URL 以及两个计数值。将存活的标识符保留在 Langfuse 项目和工作坊工作表中。

预期的轨迹证据

打开根 chat_turn observation，而不仅是它的子级 llm_call。预期结果如下：

字段	预期值
trace/observation 名称	`chat_turn`
标签（tags）	所选的 `config_id`、模型、提示词、`policy-v1`、`serving`
元数据 `policyversion`	`policy-v1`
输出	生成的 SQL、列/行数据、`outcome_hint`
运营评分（operational score）	`sql-execution-success=true`
反馈评分（feedback score）	布尔值 `user-thumbs=false`

serving 端将该字段命名为 policy_version；OpenTelemetry 适配器会将元数据键清洗为仅含字母数字字符，因此 Langfuse 显示出来的键名是 policyversion。

该运营评估器是异步执行的。请使用验证脚本，而不要把尚未出现的分数直接当作失败：

.venv/bin/python -m scripts.verify_online_scores "$CHAT_TRACE_ID" \
  sql-execution-success=true user-thumbs=false

常见故障

提供商被 ZDR 阻断 — 当 OpenRouter 的 non-frontier Zero Data Retention 要求被启用、导致符合条件的 Alibaba 路由不可用时，Qwen 会在生成 SQL 之前就失败。请针对本工作坊禁用该 ZDR 限制，或在审查隐私要求后使用已公开说明的兜底配置。
评估器调度器未运行 — 轨迹已到达，但 sql-execution-success 始终没有出现。请确认 Langfuse 的评估器执行服务/调度器状态正常，且 agent-arena-sql-execution-online 规则已启用；仅仅配置好规则并不会处理分数，如果评估工作进程本身不可用也无法生效。
缺少 OpenTelemetry 依赖 — 即使 /ask 返回了结果，也没有出现轨迹。请使用 .venv/bin/python -m pip install -r requirements.txt 重新安装锁定版本的实验依赖；运行时使用的是 Langfuse v4 的 OpenTelemetry 路径，需要与之兼容的 OTel 相关包。
服务器进程仍是旧的 — 响应报告的是 policy-v2，即使 shell 命令写的是 policy-v1。这是因为有一个更早的进程仍占用着端口 8100；请在启动预置发布之前彻底停止该进程。
端口不对 — Chat UI 默认使用 http://localhost:8100。如果 serving 使用了不同的端口，请将 VITE_SERVING_BASE 设置为同一地址，或直接对实际端口使用原始 curl 请求。
重复提交反馈 — 反馈使用的是确定性的分数 ID user-thumbs-<trace_id>。每条轨迹只能提交一次评分。对同一条轨迹重复提交相互矛盾的评分，可能返回反馈服务错误，或使演示结果变得含糊不清；请改用一条全新的会话/轨迹。
分数仍在等待中 — 评估是异步进行的。在更改配置之前，先让 scripts.verify_online_scores 轮询等待该分数出现。
参考计数一致 — 说明本次数据快照中并不存在预置的对照差异。不要人为编造一次失败；应在开课前重新播种数据或排查数据问题。

重置步骤

先停止所有已在运行的服务器，然后启动一个干净的 policy-v1 进程：

scripts/arena.sh stop
scripts/arena.sh serve
source .env
.venv/bin/python -m schema.gen_schema_context
AGENT_ARENA_POLICY_VERSION=policy-v1 \
  .venv/bin/uvicorn serving.api:app --port 8100

scripts/arena.sh serve 会在 serving API 占用终端之前，先在后台恢复 dashboard 和 web UI。刷新 Chat 页面即可创建一个全新的会话。如果你使用的是原始 API，请传入一个新的会话 ID，或者不传，让 /ask 自动创建一个。可以在第二个终端中重新运行预检脚本和 provisioner；两者都可以安全地重复执行。

兜底策略

只有当现场选出的获胜配置在三项预检问题中不再遵循明确的过期策略时，才使用讲师已验证可用的 qwen3.7-flash__P2_fewshot 配置。要口头明确说明这次替换：该兜底配置是为了保留一个确定性的教学事件，而排行榜上的获胜者仍然是现场实测出的结果。不要悄悄替换模型，也不要用这个兜底配置去掩盖计数相同、凭证问题、提供商路由问题，或评估器基础设施故障。

交接给 Module 04

在继续之前，请确认工作表中已经包含权威的 Chat 根轨迹 ID/URL、过期计数（stale count）、当前计数（current count）、sql-execution-success=true，以及布尔值 user-thumbs=false。Module 04 将从这一确切的分歧点出发，加入人工判断；它绝不能以一份脱离生产轨迹、提前写好的诊断结论作为开头。

本页内容