12.4 结构化输出:让模型按格式说话

本页范围:第 12 章第 4 节 | 整理时间:2026-10-09

快速浏览

核心问题前三节解决了「挑哪个词、何时刹车」,但下游程序要的不只是通顺的文字,还要严格的格式——JSON 里错一个逗号,整条解析流水线就全盘崩溃。怎么让模型输出从「大概率合法」升级为「不可能非法」?
本节主张把目标格式编译成状态机(FSM)或文法(CFG),解码每一步先算出语法合法的 token 集合,其余位置的 logit 一律置 −∞。约束解码用与 top-p 相同的「置 −∞」手法,把「请求模型守格式」的软约束变成「模型无法越界」的硬约束。
一句话结论结构化输出 = 格式编译(JSON Schema → FSM / CFG)+ 逐步词表掩码;它保证格式必对,但不保证内容正确,过死的格式还会挤压模型的推理表达空间。
关键词
结构化输出约束解码FSMCFGJSON SchemaOutlinesGBNFtoken 掩码

  本章前三节把解码的单步拆了个遍:12.1 的主循环负责把 logits 变成 token,12.2 的三件套决定从分布里怎么挑,12.3 的停止条件决定说到哪停。还剩一维没管:说出来的形状。自由聊天时形状无所谓,可一旦输出的读者从人换成程序——API 要返回 JSON、函数调用要填参数表、报告要套固定模板——形状就成了生死线。本节回答的问题就是:怎么让模型按格式说话,而且是机制级地保证,不靠它自觉。

  本节按「为什么 → 什么原理 → 用什么工具 → 付什么代价」的顺序展开,路线图如下:

  1. 为什么需要约束:JSON 错一个逗号就全盘崩(12.4.1):哪些场景必须把输出交给程序消费,prompt 里的格式请求为什么只是软约束;
  2. 约束解码原理:每步给词表加掩码(12.4.2):格式怎么编译成状态机,置 −∞ 与 12.2 节 top-p 的同一招;
  3. 工程方案:Outlines、GBNF 与 Structured Outputs(12.4.3):三套主流方案逐一对照,token 对齐这个共同难点;
  4. 代价与边界:约束会不会让模型变笨(12.4.4):约束改了什么、没改什么,实践中该约束什么、放开什么。

  读完本节,应该能讲清约束解码的一步是怎么走的,能为手里的场景选对工具,也知道格式保证的边界画在哪里。

  图 1 展示约束解码如何把词表划分为合法与非法 token,后续各节逐步说明前缀、格式约定与掩码的计算。

  图 1 里这个紫框的「结构化输出」放大之后长什么样?一条已生成的前缀和一份格式约定,是怎么汇合起来、把词表劈成合法与非法两堆的?把约束解码的一步单独拆开看(图 1):

原创示意图 · 非论文原图 局部放大:约束解码的一步(词表 6400 为 minimind 配置)——状态机卡住格式,softmax 只在合法堆里做 输入 ①:已生成前缀 {"name": "小明", prompt 与已生成 token 的拼接(12.1 主循环) 输入 ②:格式约定(如 JSON Schema) 离线编译成状态机 FSM(12.4.2) 键名、类型、括号全部写成转移规则 模型前向(每步只算新 token) 输出 logits z:6400 维 词表每个 token 一个分量 FSM 推进:当前状态 = 等待键名字符串 合法 token:以 " 开头、能推进状态的那些 算出掩码 m:合法位 0,非法位 −∞ z 与 m 逐位相加,对齐到同一张词表上(绿 = 合法,红 = 非法、logit 置 −∞): 绿块举例:以引号开头的 token,如 "、"nam、"age" ……(键名可逐个 token 拼出) token 0 …… token 6399,共 6400 个;绿块大小仅为示意 z + m 后做 softmax:非法位概率归零,合法堆内重归一化 合法 token 之间的相对比值原样保留(12.4.2 公式 (1)) 温度 / top-k / top-p 与采样照常叠加(12.2 节) 输出:1 个合法 token(如 "age") 拼回前缀,状态机前进到「键名之后,等待冒号」 自回归回路(12.1 节)
图 1:约束解码一步的局部放大(词表 6400 为 minimind 真实配置,绿块比例仅为示意)。输入有二:已生成的前缀({"name": "小明",)与离线编译好的格式状态机。前缀兵分两路——进模型前向得到 6400 维 logits z,进状态机推进到「等待键名字符串」状态、算出同样 6400 维的掩码 m(合法位 0、非法位 −∞);z + m 之后 softmax 只在绿色合法堆里归一化,温度与 top-k/top-p 照常叠加,采样出 1 个合法 token(如 "age"),经红色自回归回路拼回前缀进入下一步。12.4.2 会逐格讲清这张图。

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\)。

约束解码 Constrained Decoding constrained = 被约束的;decoding = 解码,即从 logits 到 token 的那一步

在自回归解码的每一步,用一个外部来源(语法、状态机、词表白名单)算出当前允许出现的 token 集合,把集合外 token 的 logit 置为 \(-\infty\),再做 softmax 与采样。它与 12.2 节的 top-k、top-p 是同一种手法——都是给 logits 加掩码,区别只在掩码的来源:top-p 的掩码来自概率排名,约束解码的掩码来自语法合法性,两者可以叠加使用。

像注塑生产:塑料熔液(模型的概率分布)在模具里怎么流动都行,但最终能成型的只有模具(格式状态机)允许的形状——模具不改塑料的性质,只改它可能的去处。

  这台「判卷机」最常见的形态是有限状态机。

有限状态机 FSM finite-state machine = 有限状态机;任意时刻只处于一个状态,每读入一个符号就按规则跳到下一个状态

一台抽象的小机器:内部有有限个状态,从起始状态出发,每读入一个字符(或 token)就查表「当前状态 + 这个符号 → 下一个状态」,没有查到的转移一律不允许。正则表达式和 JSON 这类格式都能编译成状态机。它的价值在于把「这段文本合不合法」变成「沿着状态走,每一步有没有路可走」——判定从全局问题变成逐步的局部问题,恰好契合逐 token 生成。比 FSM 更强的格式(如带任意层嵌套的括号)需要上下文无关文法(CFG)与下推自动机,思想相同,只是状态机多了一条栈。

像地铁闸机的通行逻辑:闸机在任何时刻只处于「等待刷卡 / 等待通行 / 已关闭」等少数几个状态,每个状态只认少数几种动作——刷票能过闸,翻越栏杆(非法符号)根本不在转移表里。

  以生成一个 JSON 对象为例,看状态机怎么一步步卡住格式。目标输出是 {"name":"小明","age":8} 这样的文本,状态机把它拆成「开始 → 对象内 → 键名串内 → 键名之后 → 值位置 → 值之后 → 结束」几个状态,每个状态只放行少数几种字符:

原创示意图 · 非论文原图 JSON 对象的简化状态机:每个状态只放行少数几种字符,其余 token 在该状态下全部被掩码 开始 只准 { 对象内 只准 "(键名开始) 键名串内 任意字符 / 结束 " 键名之后 只准 : 值位置 值的首字符 值之后 只准 , 或 } { " 结束 " : 值的 token 普通字符 ,(还有下一个键,回到「对象内」) 结束 输出完整合法 }
图 2:JSON 对象格式的简化状态机(原创示意,真实实现的状态划分更细)。沿主链从左到右正好走出 {"name":"小明","age":8}:开始只准 {;键名串内靠自环逐字符推进,直到结束引号;值之后遇 , 沿上方回环回到「对象内」开始下一个键,遇 } 走向结束。每个状态的「只准什么」翻译成词表语言,就是该状态下合法 token 的集合——本节开头图 1 里那两堆绿红 token,正是从这张转移表里查出来的。

  状态机给出「当前合法字符」,模型给出「当前 logits」,两者在词表上汇合。把第 \(t\) 步的合法判定写成一个掩码向量,约束解码的完整一步就是:

\[ \tilde{p}_t(v) \;=\; \mathrm{softmax}\bigl(z_t + m_t\bigr)(v), \qquad m_t(v) = \begin{cases} 0, & v \in \mathcal{A}(s_t) \\ -\infty, & v \notin \mathcal{A}(s_t) \end{cases} \tag{1} \]
公式 (1):约束解码的掩码操作——把模型 logits 与语法掩码逐位相加后再做 softmax,非法 token 的概率被精确压成 0,合法 token 之间重新归一化。符号说明:\(v\) 遍历词表中的 token(minimind 词表共 6400 个);\(z_t\) 是第 \(t\) 步模型前向输出的 logits 向量,每个 token 一个分量;\(s_t\) 是格式状态机吃掉已生成前缀 \(x_{<t}\) 后停下的状态;\(\mathcal{A}(s_t)\) 是该状态下合法的 token 集合——token 的全部字符都能被状态机吸收且不落入死路;\(m_t\) 是掩码向量,合法位取 0(不改变原分数)、非法位取 \(-\infty\)(经 softmax 后概率为 0);\(\tilde{p}_t\) 是掩码后的分布,之后的温度、top-k、top-p 与采样照常叠加。

  公式 (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 GBNFGBNF 语法文件(BNF 的正则化扩展),也支持把 JSON Schema 子集自动转成 GBNF按文法做 CFG 级约束,采样时只放行合法 token;文法可直接按 token ID 或 token 文本书写llama.cpp 官方功能(项目文档,非论文),本地量化推理场景
OpenAI Structured OutputsJSON 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 章。

🧭本节要点回顾
软约束和硬约束差在哪?
软约束是 prompt 里的格式请求,本质是向模型提要求,合规是概率性的——温度高、输出长、指令多时都可能破戒,而 JSON 错一个字符解析器就全盘崩。硬约束(约束解码)在解码每一步把非法 token 的 logit 置 −∞,概率恒为零,违规在机制上不可能发生。选择标准看输出的第一消费者:是人还是程序。
约束解码的一步具体怎么走?
编译期把格式(JSON Schema / 正则 / 文法)翻译成状态机,运行期每步由状态机按已生成前缀算出合法 token 集合,词表其余位置置 −∞,softmax 只在合法堆里归一化,温度与 top-k/top-p 照常叠加。与 top-p 同是置 −∞,只是掩码来源从概率排名换成语法合法性;合法集合内的概率比值保持不变。
约束会让模型变笨吗?
机制上不动参数、不动合法集合内的相对形状,但实证(Tam et al., arXiv:2408.02442)发现严格格式限制显著拉低推理表现、约束越严退化越重。且约束只保格式不保内容,拒答与截断还能绕过约束。实践结论:约束骨架(键名、类型、括号),放开内容(自由文本与思考过程)。

参考来源

  • 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 的词表规模即取自于此。