ThearchyHelios
10 KiB
English | 简体中文
回归评测与口径账本
这篇讲两件事：回归评测（换模型、改提示词、改目录之后，问数据还答得对不对）和口径账本（问数据答案里的数和已发布的口径对不对得上）。给搭建者和管理员看。
回归评测
评测在导航的「评测」里，搭建者以上可见（快捷键 ⌥0）。
题集
每道题是一个问题加期望答案。期望可以是：
- 一条 SQL：选格或列，每次评测重算，不冻结数值；查到遮罩列的拒收。
- 一份已发布口径的指标。
- 从某次问数据运行里认定的查询。
- 「没有数据」，或者期望反问。
- 一个变化的主要来源（贡献）：期望 SQL 加一次变化拆解的参数。模式选可加、比率或乘积，参数名和分析工具的一样，另写点名前几段（1–10，缺省 1）；期望是算出的主要来源和方向。
- 一个判定：期望 SQL 加波动基线、趋势判断、差异检验（要写模式）或可比性检查的参数；期望是算出的判定类——常规波动还是超出，上升、下降还是没有明显趋势，差异站得住还是不足以下结论，可比还是不可比（见五种分析）。
规则：
- 数值不许人填。贡献、判定两种期望里的段、方向、判定同样不许人填：在期望 SQL 的快照上，用和作答同一套分析算出来，作答前后各算一次。
- 贡献、判定的参数里不写输入（就是期望 SQL 的结果）、总数、下钻和阈值；文字参数可以带定时变量
{{ schedule.* }}。期望 SQL 只返回两期时可以不写基期、本期：先的一期是基期。口径题、期望反问的题配不了这两种。 - 阈值用这次评测开评时拍下的分析设置：算期望、各臂作答都按这一份，记进评测的指纹（「分析设置」）。期望算不了（历史不够、本期不完整……）的这一项不能评分，写明原因。
- 文字要点由裁判判，单列，不计入准确率。
- 口径升版后，用到它的题在顶部提示。每道题三选一：改为固定新版本、新旧两版各算一份期望、旧题归档另建新题。处置之前，评测时跳过这道题。
- 题集能导入导出。
- 仓库带一份分析题用的虚构零售库和题集：在
backend目录下运行python -m tests.fixtures.acceptance.retail_trends <库文件> [--today YYYY-MM-DD]，生成截止昨天的 26 周订单（随机数种子固定），登记成名为retail_trends的只读数据源，再导入tests/fixtures/eval/analysis_suite.json（八题，每个埋下的效应一题）。
发起评测
- 选变体：助手模型、写作模型、裁判开关、目录（当前 / 快照 / 只用已核实的 / 关）、重复几次。
- 看预估花费，确认发起。「目录贡献」预设一次跑「当前 vs 关」。
- 评测在后台跑，每题怎么走和用户在问数据里拿到的一样（建图、运行、复核）。停在审批上的不代批，照实记。
- 助手只给了思考、一个操作都没给时，自动重来一次。
- 并发、每题时限、单次和每日金额都有上限，在「设置 → 偏好设置 → 评测」里改。评测的花费单独记账。
- 每题的时限不算排队的时间。满载时评测会排在问数据后面（见运行并发）。
- 能停，能只重试没做完的题。服务重启时标成中断，不会自己续跑。
看结果
- 总览：准确率与可追溯准确率（带 Wilson 区间）、路径和出具档位的分布、按角色的用量与成本、耗时分位。
- 逐题表：结论、期望和答案里的数、SQL 差在哪、看了几次表、花费；点开去看运行。
- 对比：和上一次或基线比，看逐题转移与归因。
- A/B 配对表：精确 McNemar 检验，只展示，不卡门。
贡献、判定两种期望这样评：
- 对且可追溯：答案引用了判定对得上的分析结论（同一种分析，主要来源点名的是期望的那几段、方向一致）；引用它的那句话却写反了的算错。
- 对但没引用：没引用对得上的结论，但正文按说法表写对了（同一套判断词和绑定规则，见分析说法核对）。可比性没有对应的判断词，只能靠引用。
- 错：引用的结论判定对不上、正文写反了（把常规波动说成异常、把上升说成下降、主要来源说成别的段）、做了分析没说，或者根本没做。
- 不能评分：期望算不了。
系统写的「分析范围」不算答案的引用。答案引用分析结论时，逐题 E1 按它的输入查询比。
评测运行不进使用统计。评分规则现在是第 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开关。 - 数变了时可以推通知「口径升版，答案的数变了」（全局渠道、答案主人的个人渠道），消息里不放数字。
- 目录或表结构的变化也会让答案标「依据有变」（见数据目录）；只有按新目录新出现错误级问题的答案才开待办。
统计
四项统计由 GET /api/ledger/stats 现算：等价命中、对账、问题重复度、召回（E1–E4）。评测页的「口径命中与重复度」页签画趋势。
评测、口径对账、口径召回是系统代为发起的运行，不进使用统计，记录页默认不列。