正文
凌晨两点,推理集群的内存告警又响了。
这次不是 OOM,而是一条更让人不安的曲线:某台实例的 RSS 持续上涨,重启后恢复,几天后再次逼近上限。堆栈翻遍了,没有泄漏;请求量没变,模型没换,最后定位到的”凶手”是一行看起来人畜无害的 JSON Schema:
1 | { "type": "string", "maxLength": 128 } |
约束解码引擎 xgrammar 每遇到一个不同的 maxLength 值,就把它编译成一个全新的文法并永久缓存——而业务的 maxLength 是按请求动态计算的。于是缓存里躺着成千上万个”只差一个数字”的编译产物,内存就这么被一行约束吃完了。
这个事故值得写一篇,但不想只写它的复盘。因为它暴露的是一个更根本的工程问题:把确定性内容交给概率模型生成,再用语法约束去”矫正”,是在错误的层面上解决问题——护栏能挡住格式错误,挡不住幻觉、算错和编造,却要付出真实的编译、缓存和延迟代价。
这篇文章就聊聊这件事:约束解码到底保证了什么、xgrammar 在生产里会踩哪些坑、以及为什么”让模型输出 JSON”这件事,大多数场景下就不该做。
一、”100% 合法”到底保证了什么
xgrammar 的宣传语是”100% 结构正确”,这句话没有撒谎,但很容易被误读。
约束解码在每一个 token 的采样环节,把违反目标文法的 logits 置为 $-\infty$,让非法 token 在数学上不可能被选中。它保证的是语法层正确:括号配平、引号闭合、类型匹配、必填字段存在。
它不保证的东西要长得多:
| 保证了 | 没保证 |
|---|---|
| JSON 能被解析 | 字段值是对的 |
| 类型符合 schema | 数值经过了计算 |
| 必填项存在 | 引用/ID/时间戳是真的 |
| 字符串长度合规 | 内容是模型编的还是抄的 |
| 枚举值在集合内 | 选中的枚举语义正确 |
举个具体的例子。让模型从简历里抽取:
1 | {"name": "张三", "age": 28, "birthday": "1998-03-01", "graduate_year": 2021} |
这份数据 100% 符合 schema,JSON 解析器挑不出任何毛病。但 age 和 birthday 可能对不上,graduate_year 可能是编的。语法约束把”格式校验”这道防线做到了极致,却让下游误以为整条数据都是可信的——这比格式错误更危险,因为它让错误穿上了合法的外衣。
JSON Schema 本身也不是业务规则的执行器。”总价 = 单价 × 数量”、”结束时间晚于开始时间”、”身份证号校验位”——这些语义约束根本表达不进 CFG,约束解码帮不上任何忙。
所以第一个结论很直接:如果你需要的是”正确”,那约束解码给不了;如果你需要的是”能解析”,那说明你真正的问题是下游解析器不够宽容,而不是模型不够听话。
二、确定性内容,就不该让模型来生成
把”让模型输出 JSON”拆开看,里面其实混着两类完全不同的任务:
第一类:模型必须做的判断。 这段文本属于哪个类别、该调用哪个工具、这个字段是正面还是负面、从用户的话里抽取哪几个实体——这些没有唯一答案,本质是概率上的选择,模型是合适的。
第二类:代码能算出来的东西。 ID、时间戳、自增序号、金额合计、分页参数、排序结果、格式化的日期、状态机的下一个合法状态——这些有唯一正确答案,而且必须和系统其它部分严格一致。
问题在于,大量”结构化输出”的需求里,第二类占了大头。让模型逐字生成这些内容,等于让它掷骰子来决定一个本应由 str(uuid4()) 或 sum(items) 决定的值。约束解码只能保证这个骰子掷出来的格式是对的,不能保证它掷出了正确答案。
一个直观的判据:
1 | 这个字段的值,能不能用一行代码算出来? |
再补一刀:token 级的约束是”术”,数据契约是”道”。 当契约里的字段值本来就该由代码确定时,正确的做法是把这些字段从模型的输出里拿掉,由代码填充——而不是给模型一个更强的文法,要求它”正确地”生成。
三、语法约束的账单
即使模型输出确实是它该决定的,约束解码也不是免费的。一次结构化请求的真实成本链条是这样的:
1 | 请求到达 |
第一笔:编译。 rtp-llm 在 GenerateStream 构造时同步编译,schema 首次出现会直接占用请求接入路径;vLLM 用后台线程池异步编译,但请求要挂在 WAITING_FOR_STRUCTURED_OUTPUT_GRAMMAR 状态等编译完成,TTFT 照样受影响。
第二笔:缓存。 xgrammar 的编译缓存 key 是原始 schema 字符串:
1 | return grammar_level_cache_.Get(SchemaKey{ |
字符串有任何差异——字段顺序、空白、甚至只是 maxLength 的值变了——就是一次完整的缓存未命中。
第三笔:每一步的掩码。 即便命中缓存,每一步仍要填掩码、上传 GPU、跑掩码 kernel。xgrammar 做得很好(单次掩码生成低于 40 微秒,Llama 3.1 的 128k 词表里上下文相关的 token 不到 1%),但这仍是一笔持续开销。
第四笔:投机解码的回滚。 有约束的请求还要支持草稿 token 的逐位模拟与回滚,max_rollback_tokens 这类参数意味着额外的状态内存。
这些成本单看都能接受,问题在于它们会随 schema 的多样性线性放大。
四、一场完整的归因:动态长度值如何吃光内存
回到开头的事故。链条是这样的:
1 | 每请求不同的 maxLength: |
四步全部成立,事故才会发生:
- 缓存 key 是原始字符串,无语义归一化;
minLength/maxLength的值被烧进文法结构,xgrammar 把它编译成Repeat(char, min, max),maxLength=100和101在文法上是两个不同对象,不可能共享编译产物;- rtp-llm 的 C++ 层缓存默认无上限(
compiler_cache_bytes = -1,CLI 才覆盖为 512MB); - 业务把
maxLength做成了动态值——而它恰恰是业务上最容易被参数化的约束:剩余上下文预算、租户限长、字段截断长度。
四个条件凑齐,就是”每请求重编译 + 编译产物永不淘汰 + RSS 单调上涨”。
值得注意的是 vLLM 在同样的输入下的表现:它的默认缓存是 512MB 上限(官方注释说约能装 1000 个 schema),LRU 会淘汰。所以同样的重复编译也会发生,但内存有天花板——代价转化为 CPU 抖动:淘汰后再遇到相同 schema 又要重编一次,形成缓存抖动。rtp-llm 默认无上限,则把性能问题转化成了内存问题。两者是同一枚硬币的两面。
五、xgrammar 的坑,不止缓存
把这个案例当成孤例就浪费了。继续翻代码,同类问题还有一批:
坑一:pattern 和长度约束同时出现,长度约束被静默丢弃。 xgrammar 的字符串生成逻辑里,pattern 分支会直接返回,minLength/maxLength 根本不会被应用。vLLM 在入口做了拦截,auto 模式下这类 schema 会降级到 guidance 后端;rtp-llm 则原样透传——约束悄悄消失,输出可能超长而不报错。静默失效是生产系统里最坏的失效方式。
坑二:字符预算的边界 bug。 rtp-llm 固定的 xgrammar 提交(2026 年 7 月)修复了这样一个问题:在字符预算边界处,EOS 等词表外的 token id 会意外出现在掩码里,变得可采样。修复提交的说明写得很直白——跨 12.8 万词表逐 token 校验才发现掩码和实际接受逻辑不一致。**”100% 正确”是需要逐 token 验证才能相信的,不是看文档就能相信的。**
坑三:框架默认值各不相同。 缓存上限(512MB vs 无限)、回滚预算(vLLM 按草稿步数 vs rtp-llm 固定 200)、编译时机(异步 vs 同步)、失败语义(拒绝请求 vs 强制 EOS 收尾)。同一份 schema 在不同引擎上行为可能完全不同,可移植性比想象中差。
坑四:编译本身是攻击面。 恶意构造的复杂正则可以让 DFA 状态数指数爆炸,vLLM 为此加了 5 秒编译超时。如果 schema 部分来自用户输入,编译路径就是一条新的 DoS 入口。
坑五:约束会改变模型分布。 掩码不仅删掉了非法 token,还改变了剩余 token 的相对概率——被强约束的生成质量可能下降,与模型的自然语言能力产生对抗。对需要”判断力”的任务,这可能得不偿失。
一句话概括这一节:约束解码是一个活跃演进中的 C++ 编译器 + 运行时系统,不是一个可以无脑打开的开关。 它的边界情形足够多,值得用对待编译器 bug 的警惕去对待。
六、什么时候该用,什么时候该换设计
那约束解码还有没有价值?有,而且不可替代——但适用范围比多数人以为的窄得多。
适合用的:
- 工具调用:模型选工具名、给参数,结构固定、schema 静态
- 枚举/分类:
choice约束成本极低,一次编译长期复用 - 少量固定字段的抽取:字段集不变、无动态约束
- 必须保证语法可解析的对外接口
不适合用的:
- 动态 schema:每请求字段集/约束值不同,缓存天然失效
- 长文本 + 长度约束:
maxLength一参数化,就是本文那个事故 - 可计算的字段:ID、时间、合计、排序——模型不该碰
- 复杂语义校验:文法表达不了,约束只会给人虚假的安全感
flowchart TD
A["需要模型输出结构化数据?"] --> B{"值能由代码算出来吗?"}
B -->|能| C["代码生成\n模型不参与"]
B -->|不能| D{"结构会随请求变化吗?"}
D -->|会| E["重新设计契约\n固定 schema"]
D -->|不会| F{"字段值需要模型判断吗?"}
F -->|需要| G["小 schema + 约束解码"]
F -->|不需要| C
style C fill:#e8f5e9
style G fill:#e8f5e9
style E fill:#fff3e0
七、更工程的做法
如果不让模型输出完整的确定性 JSON,那该怎么写系统?四个模式,按推荐程度排序。
模式一:模型输出”选择”,代码完成”组装”。
1 | # 模型只输出一个枚举值 |
这一步就能消灭大量”让模型生成 ID 和时间戳”的荒唐场景。
模式二:抽取语义字段,序列化交给代码。
需要结构化数据时,让模型输出的应该是”它真正知道的字段”,而不是整个响应体。格式、嵌套、包装、默认值全部由代码补全:
1 | extracted = llm.extract(text, fields=["name", "city"]) # 只抽取 |
模式三:长度和格式这类确定性约束,移到代码层。
maxLength 的诉求通常是”别撑爆下游字段”,那就在代码里截断,而不是让模型在生成时就盯着字符数:
1 | title = llm.summarize(text)[:128] # 约束在代码层,简单且确定 |
顺带说明:这样反而绕开了本文开头的事故——没有动态长度值,就没有无限增长的文法缓存。
模式四:如果确实需要动态 schema,做归一化与分桶。
1 | import json |
再加两道运维防线:显式设置编译缓存上限(vLLM 是 VLLM_XGRAMMAR_CACHE_MB,rtp-llm 是 GRAMMAR_COMPILER_CACHE_BYTES),并在监控里盯住编译耗时与缓存命中率——缓存的命中率就是 schema 多样性的体温计。
八、上线前的检查清单
如果最终评估下来仍然要用约束解码,至少逐条过一遍:
- schema 字符串是否稳定?有没有在入口做归一化?
- 有没有随请求变化的字段:动态长度、动态枚举、动态字段集?
- 编译缓存上限是否显式配置,还是吃了框架默认值?
pattern/format与长度约束是否同时出现?当前引擎是拦截还是静默丢弃?- 编译耗时、缓存大小、命中率有没有监控和告警?
- 约束请求与 beam search、
n > 1、思考模式的兼容性是否验证过? - 编译失败、预算耗尽、EOS 边界这些失败语义,是否符合预期?
- 升级 xgrammar 版本后,有没有逐 token 的回归验证?
九、结语:确定性属于代码,概率属于模型
回到那行 maxLength: 128。它的初衷是”让模型别写太长”,但它把一个本该由代码层承担的确定性职责,塞给了概率模型和最复杂的运行时系统,最终以内存泄漏的形式收场。
模型擅长的是在不确定中做选择:判断、抽取、归纳、生成。代码擅长的是在确定中做执行:计算、格式化、组装、校验。约束解码的价值,是给前者的输出加一道语法护栏;它从来不是把后者也交给模型生成的理由。
真正可靠的系统是分层设计的:让模型做只有模型能做的事,其余的一切交给代码。 语法约束可以是最后一道防线,但不该是第一块砖。