02 衡量质量

学员课程 02 衡量质量 的讲师配套材料。

时间安排

总计约 15 分钟。

• 5 分钟：在最佳配置的排行榜详情中查看各难度等级的准确率和结果类型 分布。
• 4 分钟：介绍 agent-arena-llm-judge 辅助分数，并找出它与 correctness 结论不一致的情况。
• 6 分钟：针对错误或低分答案，深入查看两到三条 Langfuse trace。

讲解脚本

• 重新框定目标：赢下 Arena 只说明某个配置在总量上胜过了其他配置； 本模块讲的是它怎么赢的、它最弱在哪，就像不只要知道 一个候选人通过了面试，还要知道哪些题他答得漂亮。
• 明确说本模块不产生新数据，这里的一切在模块 01 里就已经被 correctness 和 agent-arena-llm-judge 分数记录下来了。这是一次 阅读练习，不是重跑。
• 提醒学员：仓库的 20 个 YAML 问题中，q019 和 q020 是 few-shot 保留样例， 所以干净的 Experiment 数据集有 18 个条目。
• 关于逐档位准确率：指出一个配置可以整体看起来很强，却在最难的档位上 不稳，而这正是聚合的 leaderboard 数字所 掩盖的。
• 关于 outcome 分布：把这些类别念一遍，被沙箱拒绝的 SQL、ClickHouse 报错、空结果、错误的结果集，并说明每一种都是 不同的问题、有不同的修法，而不是一团笼统的"失败"。
• 关于这个 judge 分数：它是二元 correctness 的细粒度兄弟。Langfuse 中的 evaluator 定义名为 llm_judge，但学习者在 Experiment 中看到并由 harness 等待的是 agent-arena-llm-judge。一个配置可以在 执行准确率上正确，同时写出的 SQL 仍然会被审阅者挑出来（ 多余的子查询、脆弱的日期比较）。如果能找到一处 correctness 和 agent-arena-llm-judge 现场不一致的例子，那是让这个区别落地的最清楚 方式。
• 结尾时挑两三个答错/得分低的问题，现场把它们的完整 trace 从头读到尾，发出去的 prompt、生成的 SQL、错误或结果，边读边出声 寻找规律（某种表述、某个 join、某个模型总处理不好的日期过滤）。 这就是模块 04 在生产流量上会复用的同一种读 trace 技能。

常见故障

• Langfuse evaluators 没配好：就没有 agent-arena-llm-judge 或 correctness score 来支撑本模块。回到模块 01，修好 evaluator 的 target/filter， 再跑一个小的新网格，然后继续。
• 没有答错的答案可以下钻：如果获胜配置在演示网格上拿了 100%， 就改用一个非获胜配置的失败；重点是读 trace 的技能， 而不是非要在冠军身上找出瑕疵。
• ClickHouse 没初始化 / harness 从未运行：Leaderboard 详情视图（逐档位 准确率、outcome 分布）是空的。这说明模块 01 没跑完；回去 重跑一遍再继续。
• 点进 trace 时 404 或加载了错误的项目：通常意味着 浏览器指向的 Langfuse 项目和 .env 里的不是同一个，或者 LANGFUSE_BASE_URL/密钥与跑过模块 01 harness 的那个账号不匹配。

重置步骤

• 如果 Leaderboard 详情视图是空的，重新初始化并重跑那个便宜的子集： scripts/arena.sh up，然后 python -m eval.harness --run-id demo2 --models qwen3.7-flash,gpt-5.6-luna --prompts P1_zeroshot,P3_dialect。
• 重跑时用一个新的 --run-id，这样现场就能明确你在读哪些 Leaderboard 行、 哪个 Langfuse Experiment。
• 如果只是 dashboard 渲染卡住了（Langfuse 里 Experiments 是存在的）， 不重新初始化，只重启本地服务：scripts/arena.sh stop && scripts/arena.sh serve。
• 如果缺的是 evaluators，那本模块的深度就取决于在 下一场之前把它修好，Langfuse 侧的那些 score 在课上没有替代品。