JSON-validity sweep

阶段: B2 · attention/decoder/KV + judge 校准（Day 11-20） 标签: #structured-output #temperature #json-validity #constrained-decoding

今日导引（由浅入深）

昨天（Day 15）我们把采样策略的「机理」过了一遍——greedy / temperature / top-p / top-k 各自怎么改写概率分布，以及为什么 structured output 要在解码阶段就用 grammar 约束。

今天把那个论点从「定性」推到「定量」：搭一个温度扫描实验，实测 JSON.parse 合法率随 temperature 怎么单调下滑。

这是 B1→B18 能力曲线里「从会调参数 → 会用数据论证参数选择」的转折点。B1（Day 1-10）我们建了 eval harness 与 token 计量；B2（Day 11-20）前半段（Day 11-15）打 attention/decoder/KV 的内核地基，后半段（Day 16-20）转入「评测可信度」——而今天是这条线的第一炮：先用一个对照实验把「严格结构任务为何该低温/约束解码」钉死，再为后面 AML 实体抽取任务的解码配置提供实验依据。

今日最小可判定产出：一张 validity-vs-temperature 折线图 + 一张数值表（管道能离线跑通，真实数字待 key）。

1. 机理精读

采样温度 T 的作用是对 logits 做缩放：

p_i ∝ exp(logit_i / T)

T<1 让分布变尖（更接近 argmax），T>1 让分布变平（尾部 token 概率被抬高）。多样性上升的代价是：对严格语法任务，那些本该概率极低的「错误延续」token 被采到的几率上升。

具体到 JSON：一个多余的逗号、一个漏掉的引号、一个提前出现的 }、或者在 token 预算耗尽前没闭合括号，都会让整个输出无法被 JSON.parse 解析。

关键在于「合法 JSON」是一个语法约束（context-free grammar）下的离散全或无判定：差一个字符就整体失败。这与「文本质量」这种连续可降级的指标不同——质量可以是 7 分、6 分、5 分，而合法性只有 0 和 1。

所以随着 T 上升，validity 不是缓慢退化，而往往在某个阈值后陡降。这正是把「为什么严格结构任务该用低温或 constrained decoding」从口号变成可观测曲线的实验。曲线的形状本身就是论据：低温平台期接近 100%，越过某个 T 后断崖。

设计权衡：纯靠 prompt 写「请只输出 JSON」不保证合法。模型仍可能加 markdown 围栏、解释性前言、或在高温下崩坏格式。prompt 只是「软约束」，模型可以无视。

真正把合法率钉到 100% 的手段是在解码层用 JSON-Schema / grammar 约束 token 采样空间（constrained / structured decoding），让非法 token 在每一步直接被 mask 掉——这是「硬约束」，从根上排除非法路径。本 sweep 的价值正是作为「裸采样 vs 约束解码」的对照实验：它量化了不上约束解码会损失多少合法率，从而论证约束解码的必要性。

与相邻概念的边界：Day 15 讲的是采样策略本身（温度怎么改分布），今天讲的是采样策略对下游格式约束的副作用（合法率掉多少）。明天（Day 17）则转向另一条线——LLM-as-a-Judge 的系统性偏差与 κ 校准。本日延续 OpenAI Structured Outputs (2024-08) 的论点：与其事后修 JSON，不如在解码时就约束。

2. 推导 / 手算 / 代码走读

本日为实验/数据日。脚本 scripts/json-validity-sweep.ts 在仓库中尚未建立（seed 标注「待建」，实测确认该文件缺失）。因此这里给出实验逻辑的最小化伪推导，而非真实函数走读。

实验骨架：

• 固定一个 JSON-schema 任务（如 AML 实体抽取：抽出 {entities:[{name, type, amount}]}）。
• 对 T ∈ {0, 0.3, 0.7, 1.0, 1.2, 1.5} 各采样 N 条 completion。
• 每条做 JSON.parse，捕获异常即记为非法；validity(T) = pass_count / N。
• 输出两件东西：数值表（每个 T 一行 validity%）+ 折线图（x=temperature, y=validity%）。

合法率的离散性可手算示意。设某 token 步在温度 T 下「采到非法延续」的概率为 q，一条输出有 m 个「关键语法点」（每个引号、逗号、括号都是一个），则该条整体合法的概率约为：

P(valid | T) ≈ (1 − q(T))^m

m 越大、q 越大，合法率指数下滑。举例：若 m=20，q 从 0.005（低温）升到 0.05（高温），则合法率从 0.995^20≈0.90 跌到 0.95^20≈0.36。这解释了为什么高温下长结构输出几乎必崩——非法概率被指数放大。

数值表的目标形态（每行一档温度，数字待 key 实测）：

temperature | samples N | parse_ok | validity%
------------+-----------+----------+----------
0.0         |     N     |    ?     |   ~100%   (预期，待实测)
0.3         |     N     |    ?     |    ?
0.7         |     N     |    ?     |    ?
1.0         |     N     |    ?     |    ?
1.2         |     N     |    ?     |   明显下滑 (预期)
1.5         |     N     |    ?     |    ?

表中 ? 一律待 key 跑出，禁止填臆造数字——这是本套笔记的诚信约束。

离线管道验证：在没有 key 时，可以用一组预存的离线 fixture completion（混合合法/非法样本）喂进「解析 → 统计 → 画图」管道，验证以下环节全部跑通：

• JSON.parse 的 try/catch 异常捕获正确区分合法/非法；
• 结果按 temperature 分桶聚合；
• 每桶 validity = parse_ok / N 百分比计算正确；
• CSV / 折线图导出正常。

只是这些数字是 fixture 的、不是真实模型采样的，必须显式标注「fixture，非实测」。

3. 今日实战

1. 新建 scripts/json-validity-sweep.ts（当前缺失，需创建）。
2. 复用 B1 已有的 OpenRouter 调用封装，对固定 schema 任务在 6 档温度各采样 N 条。
3. 对每条 completion 跑 JSON.parse，统计每档通过率，落数值表。
4. 用任意纯 TS 绘图/导出 CSV 出折线图（validity vs temperature）。
5. 离线 fixture 先行：无 OPENROUTER_API_KEY 时，用预存的离线 completion fixture 跑通「解析 → 统计 → 画图」管道，确保管道正确，真实数字待 key 补。

4. 今日实测 / 产出

• 状态：待跑（需 OPENROUTER_API_KEY）；离线 fixture 可先跑通统计与画图管道。
• 产出：validity-vs-temperature 折线图 + 数值表。
• 预期（非实测）：T=0 接近 100%、T≥1.2 明显下滑。具体数字待跑——不臆造任何合法率百分比。
• 脚本 scripts/json-validity-sweep.ts 当前仓库中不存在，属本日待建产出。

5. 常见误区 / 陷阱

1. 把「prompt 里写请输出 JSON」当成合法率保证——不保证，高温下照样崩，本 sweep 就是反证它。
2. 在 schema 强约束任务上用高温自由采样——合法率换不来有用的多样性，纯亏。
3. N 太小导致 validity% 抖动——每档至少几十条才稳，否则曲线噪声盖过趋势。
4. 把离线 fixture 跑出的占位数字当真实测量上报——必须标注「待跑」，这是本套笔记的诚信底线。

6. 学习资源（每条带 YYYY-MM）

• OpenAI, Introducing Structured Outputs in the API (2024-08) — 本日论点直接来源：解码层约束 > 事后修 JSON。
• OpenAI, JSON mode / function calling docs (2024, 持续更新) — structured output 的工程接口。
• Willard & Louf, Efficient Guided Generation for LLMs（Outlines, arXiv:2307.09702, 2023-07）— grammar-constrained decoding 的理论与实现基础。
• Anthropic, Tool use & structured responses docs (2024-2025) — MCP/tool 结构化返回作为约束解码的产品化形态。

SOTA检查 (2026-06 更新)

• 结论恒成立：validity 随 temperature 单调下滑是语法约束的固有性质，不过时。
• 当前主流方案：2026 生产环境已基本用 constrained / structured decoding（JSON-Schema 约束 token 空间）把合法率钉到 100%；本 sweep 的定位是论证「为何需要它」的对照实验，而非生产方案本身。
• 过时黑名单：避免把「高温自由采样 + 事后正则修复 JSON」用于 schema 强约束任务——脆弱且不可靠；避免只靠 prompt 文案保证格式。
• 下次复查点：2026-Q3 复核各家 structured output / grammar decoding 的 GA 状态与 schema 覆盖度（OpenAI / Anthropic / OpenRouter 约束解码支持矩阵随版本变）。

衔接

• 昨天：Day 15 — 采样策略（greedy/temperature/top-p/top-k + structured output 机理）
• 今天：用温度扫描把「严格结构任务该低温/约束解码」从口号变成可观测的合法率曲线。
• 明天：Day 17 — LLM-as-a-Judge 偏差（position/verbosity/self-preference + κ 校准入门）