SGLang结构化输出揭秘：约束解码从JSON Schema到Token掩码的实战

先说我最近一个真实感受：让大模型输出 JSON，从来都不是靠一句“请你以 JSON 格式返回”就能搞定的。最初我在做信息抽取类的模拟项目时，一直是“自由生成 + 解析失败再重试”的路子，结果是解析通过率大概只有六成，重试一次延迟翻倍，token 也白烧一大半。后来被同事按着头去研究约束解码，才认真把 SGLang 的 Structured Output 机制啃了一遍——这才发现，很多人只把它当推理加速框架用，其实它真正值钱的地方，是那个“生成时就约束你只能吐合法结果”的解码引擎。

这篇文章我会从约束解码的底层原理讲起，拆一下 SGLang 把正则、JSON Schema 变成 token 级掩码的整个链路，再把那些容易踩的坑、以及一个可以直接抄的信息抽取示例一起给你。如果你在搞工具调用、数据入库、批量结构化抽取，或者只是想搞清楚“结构化输出到底是怎么实现的”，这篇应该能帮你省不少时间。

1. 先破个误区：SGLang不只是一个推理加速框架，真正的底牌是约束解码

1.1 我为什么从“事后修复”转向“生成前约束”

先描述一下很多人都在经历的痛：让模型生成结构化内容，最常见的做法是——先自由生成，然后丢给 JSON 解析器，失败了就改 prompt 再重试一次。代码层面看起来很简单，但放到生产环境里就很残酷。

我测试过一个很普通的抽取场景：系统提示词要求模型“必须输出 JSON，不要输出多余内容”，模型表面上听话，但实际输出经常出现三种问题：字段名拼错、数字被写成字符串、嵌套数组残缺。解析器一报错就得重试，每次重试不光花时间，还要重新算一遍 KV Cache。最离谱的一次，一个简单的地址抽取，重试了三轮才跑通，时间直接翻了四倍。

后来我明白了一个道理：自由生成是“先输出再检查”，模型的采样过程根本不在乎你要不要 JSON，它只在乎下一个 token 对自己当前的“对话延续”来说是否自然。事后校验做得再好，也只是在筛掉坏结果，而不是阻止坏结果产生。

1.2 约束解码引擎在 SGLang 中的位置

SGLang 的结构化输出，不是挂在采样器外面的一个“后处理钩子”，而是一个跟采样器、KV Cache 管理深度耦合的模块。通俗讲，它做了三件事：

• 把你给的约束（正则、JSON Schema、EBNF 文法）编译成一个解码器能理解的状态机描述；
• 在生成每一个 token 之前，计算当前状态下“哪些 token 是合法的”，并据此屏蔽掉非法 token 的 logits；
• 把这种约束能力跟调度器、前缀缓存结合在一起，让结构化生成也能享受推理加速。

很多人宣传 SGLang 的时候只提“前缀缓存”“调度器”“并发”，却忽略了 Structured Output 才是它的核心差异化之一。如果你只拿它做自由聊天文本生成，确实也能跑，但那等于只用了它一半的功力。

1.3 这篇文章会怎么讲

先声明一下：我不打算复述官方 README，而是把约束解码这条线单独拎出来讲清楚——从有限状态机到底层怎么算 token 掩码开始，再到我实际踩过的一个正则编译膨胀的坑，最后给一个信息抽取的小例子。这样你不仅能跑通，还能知道跑通背后的原理和边界。

2. 约束解码的核心原理：正则/JSON Schema如何变成token级掩码

2.1 先理解“状态机”：自动售货机的例子

很多人一听到有限状态机（FSM）就头大，其实可以用自动售货机来类比：机器处于不同状态时，你对它投币、按键，它会决定是出饮料、找零还是报警。整个过程里，“当前状态 + 输入符号”共同决定了下一步去哪。

正则表达式天然就能被编译成状态机。比如[0-9]+这个模式，意思很明确：至少读到一个数字字符，之后可以继续读数字，一旦读到非数字字符就拒绝。状态机里至少有“起始状态”“已读数字状态”“终止状态”三档。

约束解码要做的事情，本质上就是：在模型生成序列的每一步，都把人话翻译成“当前状态 + 合法输入字符集合”，然后把词表里那些“不合法”的 token 全部拉黑。

2.2 从语法约束到 token 掩码的完整链路

SGLang 的实际处理链路，可以拆成四步：

1. 解析约束：你传进来一个正则、JSON Schema 或 EBNF 文法，会先被解析成内部表示。JSON Schema 这种带嵌套结构的，还需要转成一个等价的文法描述，因为普通正则表达不了任意深度的嵌套。
2. 构造状态机：基于内部表示，构造出用于引导生成的约束状态机，同时确认哪些状态是“可终止”的。
3. 预计算合法 token：这一步非常关键。引擎会把词表里所有 token 都拿到当前状态下过一遍，看谁能从当前状态走到一个合法状态，从而得到一个“合法 token ID 集合”。
4. 生成时屏蔽：在采样前，把所有非法 token 的 logits 设成负无穷，模型根本不可能选择它们，于是输出天然满足约束。

举个例子：你定义了一个 JSON Schema，规定age字段必须是整数。那当模型生成到age:后方的值时，字母开头的 token、标点 token、空格 token 都会被屏蔽，只剩数字类和可能的负号 token 可选。模型在采样阶段根本碰不到字母，输出自然长成合法的数字。

2.3 JSON Schema不是正则，但同样能被约束

有人会问：JSON 是嵌套递归的，纯有限状态机怎么可能表达任意深度的{}？这确实是把问题想复杂了。

实际上，JSON Schema 会被先翻译成一种上下文无关文法（例如 EBNF），然后约束引擎在生成过程中维护一个“解析栈”或“当前产生式位置”，而不是一个简单的状态编号。本质上，它比“正则状态机”多了一个栈的概念，这样才能跟踪数组、对象、嵌套层级。

SGLang 的约束引擎之所以叫“引擎”，就是因为它不是拿一个正则库去 match 整段文本，而是把这个正则/文法当成“边生成边指导采样”的解析器。这个区别很重要：传统校验是“生成完之后拿正则去验证”，约束解码是“生成过程中拿文法来决定下一步能选谁”。

3. 最难啃的硬骨头：tokenizer与约束状态机的拉扯（含完整排查链路）

3.1 现象：加上了约束，integer字段还是翻车了

先说结论：约束解码不是银弹，它只能保证“语法上合法”，不能保证“语义上合理”。我最早是在给age字段加"type": "integer"约束时发现异常的。

测试样本里出现了一个让我很困惑的情况：模型在整数字段一直在吐数字，一直吐到max_new_tokens被截断。也就是说，约束解码保证了它吐的全是数字字符，但没法阻止它“停不下来”。JSON Schema 里的 integer 只限制“这是一个整数”，并没规定“这个整数不能有一百位”。模型一旦进入数字 token 的惯性里，就可能疯狂输出直到序列被截断，最终产生一个看似合法、实际上完全不合语义的长数字。

这个现象让我意识到：约束引擎的“合法”是形式语言意义上的合法，不是业务意义上的合法。后来我加上了minimum、maximum以及自定义正则才彻底解决。

3.2 排查链路第一步：怀疑 tokenizer，打印合法 token 集合

继续深挖时，我做了个更“底层”的实验。当时换了一个新开源 8B 模型，词表跟之前的模型完全不同，结果同样的日期正则\d{4}-\d{2}-\d{2}，出现了非常明显的“首 token 延迟变高”。

我把引擎的 debug 日志打开，在生成阶段导出了当前约束状态下被允许的 token ID 集合，结果发现两个特征：

• 词表里存在大量“多位数字合并成一个 token”的情况，比如某个 token 就是"123"，另一个 token 是"12"；
• 同一个四位年份2024，可以由20+24两个 token 拼成，也可以由2024一个 token 直接吐出，路径非常多。

问题来了：路径多意味着状态机的分支多。尤其像\d{4}这种“恰好四位数字”的模式，FSM 必须区分当前已经读到了第几位数字，而多字符 token 的存在，会让“读了几位”这件事变得需要大量中间状态来跟踪。

我当时第一反应是“词表太大了”，但真正找原因时发现，问题不完全在词表，而在我写的正则本身。

3.3 根因真正所在：正则导致约束状态快速膨胀

继续排查时，我把日期正则改成\d{4}-\d{2}-\d{2}，后来又加了(19|20)\d{2}这样的前缀限定。实验结果是：约束引擎的初始化耗时和单 token 解码的额外开销都明显上涨。

原因梳理下来有三点：

• \d{4}这种“恰好长度”的模式，需要状态机区分 1 位、2 位、3 位、4 位数字，这是线性增加的状态；
• 词表里每个 token 可能是 1 到多个字符的组合，状态机需要对“一个 token 内的每个字符”做转移，路径数会乘以词表中数字 token 的数量；
• 正则里一旦出现多个连续的\d重复块，前面说到的乘法效应就会被放大，状态数涨得比直觉快很多。

后来我做了个很笨但有效的验证：把词表里所有纯数字 token 抽出来，按长度统计了一下数量，再拿同一个正则分别在“完整词表”和“精简数字词表”上做约束初始化，前者耗时的增长肉眼可见。

修复方案也不复杂。我做了三件事：

• 对日期这类强结构字段，不再写宽泛的\d正则，而是尽量把年份、月份的取值范围写清楚；
• 对数值字段，把minimum、maximum写进 JSON Schema，而不是让引擎自由放飞；
• 正则里省的连续重复块，尽量拆成多个状态更容易跟踪的写法。

改完之后，同一个模型不再出现“首 token 延迟暴涨”，连续跑了 200 条样本，全部通过 schema 校验。

3.4 验证：修正后的小规模回归

验证环节我做得比较朴素：把 200 条文本全部跑了一遍，记录每条输出是否通过jsonschema库校验、首 token 延迟和总耗时。修复前，“恰好长度”正则的那组样本里，首 token 延迟高到能被明显感知；修复后，约束引擎的额外开销基本回到正常水平，200 条样本的 schema 通过率是 100%。

这里也提醒一下读者：约束解码虽然让输出“合法”，但它不是零成本的。正则越复杂、词表越大，编译和逐 token 掩码计算的耗时就越高。上线前最好先用目标模型和正式约束做一次小样本压测，别等上了生产环境才发现首 token 延迟超标。

4. 结构化输出与Radix Cache：为什么这两件事必须放在一起看

4.1 结构化生成场景的“高前缀复用”特性

SGLang 的加速体系中，最顺手的就是 Radix Cache（基数树前缀缓存）。它做的事情可以理解成：把之前计算过的 KV Cache 按 token 前缀组织成一棵树，新请求来了，先从树里找最长公共前缀，丢掉重复计算的那部分 prefill。

有意思的是，结构化输出场景天然就让这个机制效果拉满。原因很简单：当所有请求都要求输出 JSON 时，大概率共享以下几段前缀——

• 同一个系统提示词；
• “请输出 JSON”这类固定指令；
• JSON 模板里固定不变的键名顺序，比如{"name":、"age":；
• Schema 中固定写的枚举项、固定格式说明。

自由对话场景里，用户输入千奇百怪，前缀匹配率可能很低；但在结构化抽取场景里，请求和请求之间的公共前缀往往长得可怕。我在实际测试里甚至遇到过 80 个并发请求共享同一个约 300 token 的公共前缀的情况，这部分如果不缓存，每个请求都得重新算一遍注意力，纯属浪费。

4.2 Radix Cache为什么跟约束解码配合得很好

有人可能会担心：加了约束解码之后，模型在每个 token 的选择范围被限制了，那前缀缓存还有用吗？答案是当然有用。

约束解码虽然限制了“合法 token 集合”，但它并没有决定唯一 token。同一个 schema 下，模型仍然会基于输入内容采样出不同的字段值。因此，前文已经生成的 token 序列依然是“生成”出来的，不是固定的模板常量，KV 缓存依然有很高的重复利用价值。

更微妙的一点是，约束解码让字段出现的先后顺序更可预测了。比如 Schema 固定先 name 后 age 后 hobbies，那么所有请求都会先在"name":之后生成人名，再进入"age":字段。自由生成时模型可能会调皮地先写 age 再写 name，而约束解码逼着它按模板顺序走，反而让多个请求之间的前缀更加整齐划一。这对 Radix Cache 来说简直是最友好的场景。

4.3 一个手头小实验：结构化抽取下的缓存收益

我在一个自建的小规模测试集上做过一组对照实验，100 条文本，同一个 8B 开源指令模型，跑的同样的信息抽取任务：

说明一下：这不是严谨基准测试，样本小、模型单一，数字只能给个直觉。但它反映的趋势是稳定的——约束解码提升了通过率，而前缀缓存把重复计算的成本砍掉了一大截，两者叠加，效果非常明显。

当时让我印象最深的是，prefix cache 不只是在单请求维度变速，而是在高并发下体现得淋漓尽致：同样一批并发请求，开了缓存之后排队时间明显下降，因为每个请求真正需要计算的 prefill 部分变短了。

5. 上手实操：从安装到编写一个严格的信息抽取小工具

5.1 安装和环境检查

SGLang 的安装不算复杂，但要注意环境里的 PyTorch 和 CUDA 版本别冲突：

pip install sglang[all]

装完之后先跑一个极小的推理验证一下环境是否可用。我个人的习惯是先用Engine直接跑一个文本生成的冒烟测试，确认模型能加载、采样不报错，再开始写约束相关代码。

这里提醒一句：SGLang 迭代比较快，API 在不同小版本之间可能有差异，下面的代码基于我当前在用的稳定版风格，具体以最新官方文档为准。

5.2 用Engine直接在脚本里跑

如果你是做离线批量抽取，我建议直接用Engine，省去起服务的开销。下面是一个信息抽取函数，用json_schema约束输出：

import sglang as sgl from sglang import Engine, function, gen, system, user, assistant @function def info_extract(paragraph: str): system("你是一个信息抽取助手，只输出合法 JSON，不要输出任何解释。") user( "请从下面的文本中抽取人物信息，严格按照给定的 JSON Schema 输出：\n" + paragraph ) assistant( gen( "output", json_schema={ "type": "object", "properties": { "name": {"type": "string"}, "age": {"type": "integer", "minimum": 0, "maximum": 200}, "hobbies": { "type": "array", "items": {"type": "string"}, }, }, "required": ["name", "age", "hobbies"], "additionalProperties": False, }, ) ) engine = Engine(model_path="<你的8B级别开源模型路径>", mem_fraction_static=0.6) state = info_extract.run( engine, paragraph="张三是一名软件工程师，今年28岁，平时喜欢编程、摄影和爬山。", ) print(state["output"].text()) engine.shutdown()

要点有两个：一是additionalProperties: False一定要写，否则模型可能自由发挥加字段；二是给数值字段加minimum、maximum，这正好对应我在第 3 章讲的语义约束问题，避免出现“合法但离谱”的数字。

5.3 用Server模式集成到HTTP服务

如果想把约束能力暴露成 API，可以用服务模式启动：

python -m sglang.launch_server --model-path <你的模型路径> --port 30000

然后在业务代码里用 HTTP 调用。服务端提供的是主流兼容接口，里面可以直接带约束信息：

import requests resp = requests.post( "http://localhost:30000/v1/chat/completions", json={ "model": "<your-model>", "messages": [ {"role": "system", "content": "你是一个信息抽取助手，只输出合法 JSON。"}, {"role": "user", "content": "请从下面内容中抽取实体并输出 JSON：\n..."}, ], "temperature": 0.0, "max_tokens": 512, }, timeout=60, )

具体请求体参数在不同版本会有一点变化，建议拿自己环境的 API 文档试一下。但思路是不变的：约束是服务端帮你保证的，客户端只需要把 schema 或正则丢过去。

5.4 我在实测中遇到的三个隐蔽问题

第一个是数组元素之间的分隔符。schema 里如果有数组，数组里的每个对象之间该不该有逗号、换行，有时候约束引擎能处理，但 prompt 里如果给了太多“可以换行”的自由，模型可能产出很长但完全合法的空字段对象，白白浪费 token。

第二个问题是max_new_tokens太短导致截断。约束解码只能保证每个 token 都是“合法前缀”的一部分，但不能保证最终截断点正好在完整 JSON 的结尾。我踩过一次：schema 完全没问题，但max_tokens=128太短，输出被切在了一个数组中间。从“前缀合法性”角度它没错，但从“完整 JSON”角度它就是个残缺结果。解决办法是把 max tokens 放宽，或者后端做一次最终校验。

第三个问题是字符串字段里的转义字符。JSON Schema 只约束“这是个字符串”，但模型很可能在一个 string 字段里输出换行符、单引号、未转义的双引号。这不会违反“字符串”这个类型约束，但在 JSON 解析层面会让结果仍然是合法 JSON（因为引擎会自动做转义）。如果你下游要拿原始文本而不是解析后的值，这个细节会让你很迷惑。我的处理是：在抽取字段的 schema 里加pattern限制字符类别，或者在后处理时统一 strip 换行。

6. 生产选型：硬约束解码、软约束提示词、事后修复怎么选

6.1 三条路线的本质差别

把市面上常见的做法归成三类，能帮你快速判断该用哪种：

我个人的体会是：如果下游是程序自动解析、入库、或者作为工具参数传入函数，那就不要犹豫，直接上硬约束。如果只是生成一段供人阅读的要点列表，软约束完全够用，没必要为了“结构化”而牺牲生成自由度。

6.2 什么时候不必用硬约束解码

有一种情况我不会推荐硬约束解码：输出本身很开放，或者约束会导致模型“憋”出一个形式上合法但内容退化的结果。比如让模型写一篇商品评论摘要，你用正则约束它必须输出{"summary": "..."}，这时候模型往往为了满足“首字段必须是 summary”，从第一个 token 起就被锁死在一个固定模板里，生成内容变得机械。

还有一种情况是 schema 极度复杂、深层递归嵌套。约束引擎能处理，但状态维护和掩码计算的开销会变大。我的建议是：能简化 schema 就先简化，把复杂的嵌套压成扁平结构；如果业务确实需要，再上硬约束解码。

6.3 选型时我的三个判断标准

第一个判断标准是“错误成本”。错误结果进入程序后会不会导致下游故障？会，就必须硬约束。

第二个标准是“频率和延迟敏感度”。高频调用且延迟敏感，优先考虑约束解码加前缀缓存的组合，而不是反复重试。重试的代价是线性增加的，硬约束的代价大多是线性的、一次性的。

第三个标准是“schema 的稳定性”。如果字段结构天天变，约束编译缓存带来的收益会被频繁失效抵消，这时候可以考虑把 schema 做一层封装，只对稳定字段做强约束，其余字段用宽松字符串。

最后再分享一个小技巧：把固定模板部分的 token 尽量前置。比如 system 里固定放“只输出 JSON”，schema 的描述放中间，正文内容放最后。这样多个请求的公共前缀尽量长，Radix Cache 命中率会高很多。我在前面的小实验里，只做了这个顺序调整，单请求延迟就肉眼可见地降了一截。

结构约束带来的稳定感，只有真正在数据抽取和工具调用场景里跑过，才会有体会。它解决的也不是“能不能生成合法 JSON”，而是“每次都能生成合法 JSON”，这两件事在生产环境里差了十万八千里。