[English](../en/evaluation-and-ledger.md) | 简体中文 # 回归评测与口径账本 这篇讲两件事：回归评测（换模型、改提示词、改目录之后，问数据还答得对不对）和口径账本（问数据答案里的数和已发布的口径对不对得上）。给搭建者和管理员看。 ## 回归评测 评测在导航的「评测」里，搭建者以上可见（快捷键 ⌥0）。 ### 题集 每道题是一个问题加期望答案。期望可以是： - 一条 SQL：选格或列，每次评测重算，不冻结数值；查到遮罩列的拒收。 - 一份已发布口径的指标。 - 从某次问数据运行里认定的查询。 - 「没有数据」，或者期望反问。 - 一个变化的主要来源（贡献）：期望 SQL 加变化拆解的参数，用和作答同一套分析算出主要来源（一段或前几段）和方向。 - 一个判定：期望 SQL 加波动基线、趋势判断、差异检验或可比性检查的参数，用同一套分析算出判定的类——常规波动还是异常，上升、下降还是没有明显趋势，差异站得住还是不足以下结论，可比还是不可比（见[分析能力](analysis.md#五种分析)）。 规则： - 数值不许人填；贡献和判定两种期望里的段、方向、判定同样不许人填，由期望 SQL 和同一套分析算出，作答前后各算一次。 - 文字要点由裁判判，单列，不计入准确率。 - 口径升版后，用到它的题在顶部提示。每道题三选一：改为固定新版本、新旧两版各算一份期望、旧题归档另建新题。处置之前，评测时跳过这道题。 - 题集能导入导出。 ### 发起评测 1. 选变体：助手模型、写作模型、裁判开关、目录（当前 / 快照 / 只用已核实的 / 关）、重复几次。 2. 看预估花费，确认发起。「目录贡献」预设一次跑「当前 vs 关」。 - 评测在后台跑，每题怎么走和用户在问数据里拿到的一样（建图、运行、复核）。停在审批上的不代批，照实记。 - 助手只给了思考、一个操作都没给时，自动重来一次。 - 并发、每题时限、单次和每日金额都有上限，在「设置 → 偏好设置 → 评测」里改。评测的花费单独记账。 - 每题的时限不算排队的时间。满载时评测会排在问数据后面（见[运行并发](postgresql-and-scaling.md#运行并发)）。 - 能停，能只重试没做完的题。服务重启时标成中断，不会自己续跑。 ### 看结果 - **总览**：准确率与可追溯准确率（带 Wilson 区间）、路径和出具档位的分布、按角色的用量与成本、耗时分位。 - **逐题表**：结论、期望和答案里的数、SQL 差在哪、看了几次表、花费；点开去看运行。 - **对比**：和上一次或基线比，看逐题转移与归因。 - **A/B 配对表**：精确 McNemar 检验，只展示，不卡门。 贡献和判定两种期望这样评：答案引用了判定对得上的分析结论，算对且可追溯；正文照说法表写对了、但没有引用，算对但没引用；来源、判定对不上或答成相反，算错；期望本身算不了（比如期望 SQL 查出来的历史不够），不能评分。分析结论的输入查询也算答案引用过的查询。 评测运行不进使用统计。评分规则现在是第 3 版（加了贡献、判定两种期望）；老评测可以在评测详情里按新规则重评（只读封存，不调模型）。 ### 定时评测 定时任务的目标可以选题集。有一道题从通过变成不通过，就推「定时评测有退步」；消息里只有题集名、通过数、退步题数和链接。以题集为目标的定时任务不收 Webhook（回 422）。 ## 口径账本 口径账本把问数据答案里的数，和已发布的口径对上。口径是一个指标怎么取数、怎么算的约定，固定在口径卡里。 ### 逐个数标口径 探索运行封存后，系统在后台把答案和已发布的口径比对，给每个数标一种口径： | 标签 | 含义 | |---|---| | 「等价已证明」 | SQL 被证明和口径等价 | | 「助手选用」 | 助手选用口径拼出来的 | | 「相关口径」 | 用到同一张表却不等价，写明差在哪 | | 「这次的推理」 | 和哪份口径都不沾边 | - 证据面板的出处链最上面多一步「口径」；问数据每一轮底下有一行摘要。比对还没出结果时，写「正在比对口径」并按退避重取。 - 比对结果是一条封存后追加的事件 `ledger.matched`，出现在时间线和可验证报告的「封存后追加」里，不在封存范围内。启动时会补比最近 7 天的运行（跟着 `AGENTLAB_SCHEDULER` 开关）。 - 逐个数判：报告引用了一条查询的几列（例如销售额、订单数、首末日）时，每个数按它那一列单独和口径的指标列比，多查的列不影响这个数。只在去掉别的列不会改变这个数时才这样比；有 DISTINCT、按别的列排序后截断、多出来分组列的，照旧整条比。 - 多行查询没有 `ORDER BY` 时，引用其中一格不算「来自口径」，召回和对账里照实标「行序不定」。 - 整题要每个来自数据的数都被证明来自同一份口径，才自动出具。 - 分析结论里的数（占比、变化、波动范围）是从查询结果派生的，不比对、不标口径，摘要行也不计它们。 写口径的取数 SQL 时，最好不要取整（`ROUND(SUM(x), 2)`），也不要套 `COALESCE(…, 0)`。取整和缺省值交给口径卡的小数位和展示；否则问数据里没取整的写法永远认不成等价（差在哪会照实写出来）。 ### 按口径正式出具 整题等价于一份已发布的受管口径时（SQL 被证明等价、版本受管、图里没有人工节点和写入），系统按口径自动发起一次正式运行，来源记为「按口径正式出具」。 - 「设置」里的 `ledger` 一组可以关掉自动出具（`auto_issue`）。 - 自动和一键出具合计每天最多 20 次。 - 标「助手选用」的答案给一键出具。 - 画布试跑、个人应用刷新这类不是问数据答案的运行，不自动出具。 - 使用者按口径正式出具，只限他有权使用的应用固定着的口径版本。 ### 对账 对标「相关口径」的数，点「看差多少」发起一次只读的对账运行：这次的数、口径的数和差值，各自点得开出处。 - 对账的说明有没有用，可以反馈。 - 使用者也能对账。 - 要人选对照指标时，按逐个数核对过的那几列预选。 ### 沉淀 同一类问题反复出现时，它会进工作流选择里的「可沉淀的问题」。判断标准：同一形状的查询 ≥3 次、来自 ≥2 段对话；或者问题聚成一类；或者答案被反复导出、做成应用。 可沉淀的问题可以固化成口径草稿：引用的查询变成取数节点，跨轮变化的字面量自动成为参数。审过再发布。 ### 召回 受管口径发布新版本后，系统在后台反查用过旧版的问数据回答、正式运行、固定它的应用和导出，按参数分组，在同一份数据上重算两版之差（来源为「口径召回」的探索运行，差值在召回卡里算）。 - 只有数真变了，才给答案的主人开「召回」待办，并推 `ledger.recall`。待办里旧值、新值、差值和原答案当时的值都点得开，可以按新版重新出具。 - 没变的只记账，在原答案上记「已按 vN 核对，不影响」。 - 全部指标都行序不定的，结论写「核对不了」并开待办。 - 每次发布最多重算 `ledger.recall_limit` 组（缺省 50；0 表示只列不算），超出的在版本历史里点「接着算」。发布弹窗先预告规模。 - 发布后自动的那一批，以及启动时接着做，都跟着 `AGENTLAB_SCHEDULER` 开关。 - 数变了时可以推通知「口径升版，答案的数变了」（全局渠道、答案主人的个人渠道），消息里不放数字。 - 目录或表结构的变化也会让答案标「依据有变」（见[数据目录](data-catalog.md#版本与提醒)）；只有按新目录新出现错误级问题的答案才开待办。 ### 统计 四项统计由 `GET /api/ledger/stats` 现算：等价命中、对账、问题重复度、召回（E1–E4）。评测页的「口径命中与重复度」页签画趋势。 评测、口径对账、口径召回是系统代为发起的运行，不进使用统计，记录页默认不列。