12.4 结构化输出:让模型按格式说话
本页范围:第 12 章第 4 节 | 整理时间:2026-10-09
本章前三节把解码的单步拆了个遍:12.1 的主循环负责把 logits 变成 token,12.2 的三件套决定从分布里怎么挑,12.3 的停止条件决定说到哪停。还剩一维没管:说出来的形状。自由聊天时形状无所谓,可一旦输出的读者从人换成程序——API 要返回 JSON、函数调用要填参数表、报告要套固定模板——形状就成了生死线。本节回答的问题就是:怎么让模型按格式说话,而且是机制级地保证,不靠它自觉。
本节按「为什么 → 什么原理 → 用什么工具 → 付什么代价」的顺序展开,路线图如下:
- 为什么需要约束:JSON 错一个逗号就全盘崩(12.4.1):哪些场景必须把输出交给程序消费,prompt 里的格式请求为什么只是软约束;
- 约束解码原理:每步给词表加掩码(12.4.2):格式怎么编译成状态机,置 −∞ 与 12.2 节 top-p 的同一招;
- 工程方案:Outlines、GBNF 与 Structured Outputs(12.4.3):三套主流方案逐一对照,token 对齐这个共同难点;
- 代价与边界:约束会不会让模型变笨(12.4.4):约束改了什么、没改什么,实践中该约束什么、放开什么。
读完本节,应该能讲清约束解码的一步是怎么走的,能为手里的场景选对工具,也知道格式保证的边界画在哪里。
图 1 展示约束解码如何把词表划分为合法与非法 token,后续各节逐步说明前缀、格式约定与掩码的计算。
图 1 里这个紫框的「结构化输出」放大之后长什么样?一条已生成的前缀和一份格式约定,是怎么汇合起来、把词表劈成合法与非法两堆的?把约束解码的一步单独拆开看(图 1):
12.4.1 为什么需要约束:JSON 错一个逗号就全盘崩
先看清需求从哪里来。模型输出的读者有两种:人和程序。给人看的输出,形状差一点无伤大雅——多一句客套、少一个标点,人眼自动忽略。给程序看的输出则完全不同:API 接口要返回 JSON 供前端渲染,函数调用(Function Calling,第 14 章细讲)要填出一份严格的参数表交给代码执行,数据抽取任务要套固定模板入库。这些场景里,输出的第一消费者是解析器。
解析器是一台不讲情面的状态机。以 Python 的 json.loads 为例,下游想要的是 {"name": "小明", "age": 8},而模型自由发挥时可能交出:末尾多一个尾随逗号、字符串用单引号、整段包在 ```json 代码围栏里、开头先来一句「好的,这是你要的结果」。这四种「差一点」中的任何一种,都让 json.loads 直接抛异常——没有「差不多对」,要么解析通过,要么整条流水线崩在这一步。12.3 节讲的截断风险在这里同样致命:撞上 max_new_tokens 上限被砍断的 JSON 少一个右括号,一样无法解析。
最直白的对策是在 prompt 里写「请只输出 JSON,不要任何解释」。这确实能大幅提高合规率,但它的本质是请求:模型大概率照办,却没有任何机制兜底。温度调高、输出变长、prompt 里指令变多,破戒的概率都会上升。于是有了两条路线的分野:
软约束:prompt 里请求格式
在指令里声明「只输出 JSON」「按这个模板填」。优点是零成本、随时改;缺点是本质是向模型提要求,它可以选择不听——合规是概率性的,且格式指令与任务指令会互相挤占模型的注意力。
硬约束:解码时屏蔽非法 token
在解码每一步从机制上把不合格式的 token 概率归零,模型想违规也违规不了。优点是格式有严格保证;缺点是需要额外的编译与运行时设施,这是本节讨论的路线。
判断用哪条路线,看输出的第一消费者是谁:交给人看,软约束通常够用;交给程序看,「错一个字符就全盘崩」决定了需要硬约束把概率性合规换成机制性合规。结构化输出通过解码机制阻止违规 token 生成,使非法格式无法出现。
12.4.2 约束解码原理:每步给词表加掩码
硬约束怎么造?核心思路一句话:解码每一步,先问格式允许哪些 token,把不允许的全部屏蔽。这套做法叫约束解码(constrained decoding),分两步落地。编译期:把目标格式(JSON Schema、正则表达式、文法)翻译成一台自动判卷机,它能回答「给定已生成的前缀,下一个位置合法的是什么」。运行期:每生成一个 token 之前,向判卷机查询当前的合法集合,其余 token 的 logit 一律置 \(-\infty\)。
在自回归解码的每一步,用一个外部来源(语法、状态机、词表白名单)算出当前允许出现的 token 集合,把集合外 token 的 logit 置为 \(-\infty\),再做 softmax 与采样。它与 12.2 节的 top-k、top-p 是同一种手法——都是给 logits 加掩码,区别只在掩码的来源:top-p 的掩码来自概率排名,约束解码的掩码来自语法合法性,两者可以叠加使用。
这台「判卷机」最常见的形态是有限状态机。
一台抽象的小机器:内部有有限个状态,从起始状态出发,每读入一个字符(或 token)就查表「当前状态 + 这个符号 → 下一个状态」,没有查到的转移一律不允许。正则表达式和 JSON 这类格式都能编译成状态机。它的价值在于把「这段文本合不合法」变成「沿着状态走,每一步有没有路可走」——判定从全局问题变成逐步的局部问题,恰好契合逐 token 生成。比 FSM 更强的格式(如带任意层嵌套的括号)需要上下文无关文法(CFG)与下推自动机,思想相同,只是状态机多了一条栈。
以生成一个 JSON 对象为例,看状态机怎么一步步卡住格式。目标输出是 {"name":"小明","age":8} 这样的文本,状态机把它拆成「开始 → 对象内 → 键名串内 → 键名之后 → 值位置 → 值之后 → 结束」几个状态,每个状态只放行少数几种字符:
状态机给出「当前合法字符」,模型给出「当前 logits」,两者在词表上汇合。把第 \(t\) 步的合法判定写成一个掩码向量,约束解码的完整一步就是:
公式 (1) 保留了合法 token 之间的相对概率:对合法集合内的任意两个 token \(u\) 与 \(v\),掩码前后它们的概率比值不变,即 \(\tilde{p}_t(u)/\tilde{p}_t(v) = p_t(u)/p_t(v)\)。原因是 \(e^{-\infty}\) 项全部消失后,softmax 只是在合法子集上重新归一化,分子分母同乘一个数,比值原样保留。约束只决定哪些 token 可以生成,不改变合法 token 之间的相对概率。12.4.4 讨论「约束会不会让模型变笨」时还会用到这个性质。
从实现侧看,这套手法一点也不新。minimind 的 generate 里,top-k 把低于第 k 名的 logit 置 −∞、top-p 把累计概率越线的置 −∞(model_minimind.py:276–282),用的正是同一个「置 −∞」动作;约束解码只是把掩码的来源从「概率排名」换成了「语法合法性」。理解了 12.2 节的修正链,就理解了约束解码的一半——它不过是给这条链再添一个修正站。
约束解码 = 编译期建表(格式 → 状态机 / 文法 → 各状态的合法 token 集合)+ 解码期查表(每步给词表加掩码)。它把「请求模型守规矩」变成「模型没法不守规矩」,且不改合法集合内的相对概率形状——模型对内容的偏好被完整保留。
12.4.3 工程方案:Outlines、GBNF 与 Structured Outputs
原理一句话说完,工程实现各有一家之言。三套主流方案的分工对照如下:
| 方案 | 格式怎么描述 | 约束怎么落地 | 出处与场景 |
|---|---|---|---|
| Outlines(开源库) | 正则表达式、JSON Schema | 编译成 FSM,离线遍历「状态 × 词表」建合法 token 索引,运行时查表掩码;模型无关,可配任意本地模型 | Willard & Louf 论文(arXiv:2307.09702)配套实现,本地部署、自托管场景 |
| llama.cpp GBNF | GBNF 语法文件(BNF 的正则化扩展),也支持把 JSON Schema 子集自动转成 GBNF | 按文法做 CFG 级约束,采样时只放行合法 token;文法可直接按 token ID 或 token 文本书写 | llama.cpp 官方功能(项目文档,非论文),本地量化推理场景 |
| OpenAI Structured Outputs | JSON Schema(strict 模式,只支持一个子集) | 服务端完成约束解码;调用方在 response_format 或 function calling 里传 schema 与 strict: true | 官方 API 特性(2024-08-06 随 gpt-4o-2024-08-06 上线,官方公告与文档,非论文) |
三家各有一处值得细看。Outlines 的贡献在于把效率问题讲透了:论文把文本生成重新表述为状态机上的状态转移,并预先离线遍历「状态机状态 × 整个词表」,建好一张「每个状态下哪些 token 合法」的索引;运行时每一步只查一次表,作者报告这种做法给生成过程增加的额外开销很小,且与具体模型无关(arXiv:2307.09702 摘要)。GBNF 的特色是格式直接写给开发者看:一个让模型只输出列表的完整语法可以短到两行——
root ::= ("- " item)+
item ::= [^\n]+ "\n"
这是 llama.cpp 官方 GBNF 文档里的真实示例:root 规则规定输出整体必须是一行或多行「- 项目」,item 规则规定每行是不含换行的任意字符加换行收尾。不想手写语法时,llama.cpp 也能把 JSON Schema 的一个子集自动转成 GBNF。官方文档还特意提醒:schema 只用于约束输出,不会注入 prompt——模型自己看不见这份格式约定,想让它理解结构,还得在 prompt 里照常说明(工具调用场景除外)。OpenAI 的 Structured Outputs 则把整套机制收进服务端:开发者只传 JSON Schema 与 strict: true,约束解码在服务端完成;官方公告(2024-08-06)给出的口径是,复杂 schema 场景下的格式可靠性从旧模型的不足四成提升到百分之百。代价是 schema 只能用一个子集——所有字段必须列入 required、对象必须声明 additionalProperties: false、嵌套不超过 10 层等(官方文档的 supported schemas 清单),超出就直接报错。
注意:三套方案共享同一个工程难点:token 对齐。语法是字符级的,模型是 token 级的,两者粒度天然错位——一个 token 可能横跨语法边界(比如 "age": 恰好被切成一个 token,一口气走完「键名串内 → 键名之后 → 值位置」三个状态),一个语法符号也可能要多个 token 拼出来。掩码判定必须逐个 token 模拟「它喂进状态机后走到哪里、会不会走进死路」,这是约束解码实现的主要复杂度,也是各家方案性能差异的来源。
对照 minimind 可以看清这条光谱的位置:它的 generate(model_minimind.py:261–293)只实现了概率侧的修正——温度、重复惩罚、top-k、top-p,没有内置任何语法约束。这不奇怪:约束解码的全部增量只是「再往修正链上加一个来自语法的掩码站」,理解了现有那几站的置 −∞,加上去只是工程量的差别。
12.4.4 代价与边界:约束会不会让模型变笨
先回答机制层面的问题:约束到底改了什么、没改什么。改了的只有两处:一是每步的可选集合,从整个词表缩到语法合法的子集;二是每步多一次掩码计算——Outlines 用离线预编译的索引把这次查询摊薄,论文报告额外开销很小;OpenAI 的服务端方案则是首个带新 schema 的请求有一次编译延迟,之后同 schema 的请求不再重复付出(官方文档)。没改的更多:模型参数原样、模型的知识原样、合法集合内的相对概率形状原样(12.4.2 的比值不变性质)。从这个意义上说,约束本身并没有动模型的「脑子」。
但实证研究给出了更复杂的图景。Tam 等人 2024 年的研究(Let Me Speak Freely?,arXiv:2408.02442)系统比较了同一批模型在自由生成与结构化格式下的表现,发现格式限制下推理能力显著下降,且约束越严格、推理任务的退化越严重。直觉解释并不矛盾:推理能力依赖自由展开的中间步骤,把思考硬塞进 JSON 骨架,等于要求模型一边解题一边注意卷面,表达空间被格式挤占。这与「约束不改分布形状」并不冲突——形状没变,但被强制保留的骨架本身改变了模型分配注意力的方式。
第二重边界更要记牢:约束管格式,不管内容。schema 能保证 age 字段一定是整数,保证不了这个整数填得对;输入与 schema 不匹配时,模型照样会在完全合法的格式里编造内容——OpenAI 官方文档自己就提示了这一点。还有两个机制外的破口:模型因安全原因拒答时输出不再遵循 schema(文档要求调用方检查 refusal 字段),以及撞上 max_tokens 上限时 JSON 被拦腰截断(12.3 节的截断风险在这里兑现)。所以工程上仍要兜底:校验、重试、截断检测一个都不能省。
易错点:格式必对 ≠ 内容必对。约束解码消灭的是「解析失败」这一类错误,对「填得不对」「合法地胡说」无能为力;拒答与截断两种情形还会绕过约束本身。拿到结构化输出的正确姿势是:信任它的形状,核验它的内容。
把机制与实证合起来,实践建议就清楚了:约束骨架,放开内容。键名、类型、括号、枚举这类骨架交给硬约束,它们没有发挥余地,约束只有收益;字符串字段里的自由文本、推理过程则尽量留在宽松的位置,不要用格式卡死。推理比重大的任务,更好的安排是让模型先自由生成、再二次结构化抽取;若必须一次输出结构化推理,可以学 OpenAI 官方文档的链式思考示例——把 steps 字段放在 final_answer 之前(Structured Outputs 按 schema 声明的键顺序输出),让模型先在宽松字段里想完,再填结论。格式之外的事——prompt 里怎么写格式指令、与 CoT 和 RAG 怎么组合——属于第 14 章的应用层话题;掩码计算与 KV Cache、量化、投机采样的开销账,则一并留给第 13 章。
参考来源
- Willard & Louf, 2023. Efficient Guided Generation for Large Language Models(Outlines 配套论文,arXiv:2307.09702):把文本生成重构为状态机状态转移、用正则与上下文无关文法引导生成、离线遍历「状态 × 词表」构建索引、模型无关且额外开销小。已核对 arXiv 摘要页(注:本章规划稿原写 arXiv:2307.09709,经核对为一篇太阳物理论文,正确编号为 2307.09702)。
- OpenAI 官方文档 Structured Outputs 指南(platform.openai.com/docs/guides/structured-outputs):strict json_schema 用法、与 JSON mode 的区别(后者只保 JSON 合法不保 schema 符合)、schema 子集限制(全部字段 required、additionalProperties: false、嵌套不超过 10 层等)、首个带新 schema 请求有额外编译延迟、拒答(refusal)与 max_tokens 截断仍会产出不合规输出、按 schema 键顺序输出、输入与 schema 不匹配时模型可能在合法格式内编造。已核对官方文档页。
- OpenAI 官方公告 Introducing Structured Outputs in the API(2024-08-06,openai.com):上线时间(随 gpt-4o-2024-08-06)与「复杂 schema 场景格式可靠性从旧模型不足四成提升至百分之百」为官方公告口径,属官方博客而非论文;公告页直接抓取受反爬限制,内容与日期经多个独立二手报道交叉印证。
- llama.cpp 官方 GBNF 文档(github.com/ggml-org/llama.cpp,grammars/README.md):GBNF 语法(root 规则、产生式、字符范围、重复记号、按 token ID 或文本匹配)、JSON Schema 子集自动转 GBNF、「schema 只约束输出、不注入 prompt」的官方提醒、列表语法示例(root ::= ("- " item)+ 等两行)。已核对官方文档原文。该来源为项目文档,无对应论文。
- Tam et al., 2024. Let Me Speak Freely? A Study on the Impact of Format Restrictions on Performance of Large Language Models(arXiv:2408.02442):格式限制下 LLM 推理能力显著下降、约束越严格退化越严重。已核对 arXiv 摘要页。
- minimind(Apache 2.0),model/model_minimind.py:261–293:generate 只实现概率侧修正(温度 272 行、重复惩罚 273–275 行、top-k 276–277 行、top-p 278–282 行置 −∞、multinomial / argmax 283 行),无内置语法约束;词表 6400(分词器配置)。本节图 2 的词表规模即取自于此。