Zer0e's Blog

AI其十:别让大模型输出JSON——xgrammar 的确定性幻觉

字数统计: 3.7k阅读时长: 13 min
2026/10/31 Share

正文

凌晨两点,推理集群的内存告警又响了。

这次不是 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
2
3
这个字段的值,能不能用一行代码算出来?
能 → 交给代码
不能 → 才轮到模型

再补一刀:token 级的约束是”术”,数据契约是”道”。 当契约里的字段值本来就该由代码确定时,正确的做法是把这些字段从模型的输出里拿掉,由代码填充——而不是给模型一个更强的文法,要求它”正确地”生成。

三、语法约束的账单

即使模型输出确实是它该决定的,约束解码也不是免费的。一次结构化请求的真实成本链条是这样的:

1
2
3
4
5
6
7
8
9
10
11
请求到达
│
▼
[编译 schema] ─── miss ──► 新 CompiledGrammar 常驻缓存
│ (容量上限取决于框架配置)
│ hit
▼
[每步填 bitmask] ──► [H2D 传输] ──► [GPU 掩码 kernel]
│
▼
[采样] ──► [投机解码时逐位模拟 + 回滚]

第一笔:编译。 rtp-llm 在 GenerateStream 构造时同步编译,schema 首次出现会直接占用请求接入路径;vLLM 用后台线程池异步编译,但请求要挂在 WAITING_FOR_STRUCTURED_OUTPUT_GRAMMAR 状态等编译完成,TTFT 照样受影响。

第二笔:缓存。 xgrammar 的编译缓存 key 是原始 schema 字符串:

1
2
3
return grammar_level_cache_.Get(SchemaKey{
schema, any_whitespace, indent, separators, strict_mode, ...
});

字符串有任何差异——字段顺序、空白、甚至只是 maxLength 的值变了——就是一次完整的缓存未命中。

第三笔:每一步的掩码。 即便命中缓存,每一步仍要填掩码、上传 GPU、跑掩码 kernel。xgrammar 做得很好(单次掩码生成低于 40 微秒,Llama 3.1 的 128k 词表里上下文相关的 token 不到 1%),但这仍是一笔持续开销。

第四笔:投机解码的回滚。 有约束的请求还要支持草稿 token 的逐位模拟与回滚,max_rollback_tokens 这类参数意味着额外的状态内存。

这些成本单看都能接受,问题在于它们会随 schema 的多样性线性放大。

四、一场完整的归因:动态长度值如何吃光内存

回到开头的事故。链条是这样的:

1
2
3
4
5
6
每请求不同的 maxLength:
schema (maxLength=100) ──► key A ──► 编译 ──► 缓存 A(不释放)
schema (maxLength=101) ──► key B ──► 编译 ──► 缓存 B
schema (maxLength=102) ──► key C ──► 编译 ──► 缓存 C
...
缓存占用 ∝ 历史出现过的不同长度值数量

四步全部成立,事故才会发生:

  1. 缓存 key 是原始字符串,无语义归一化;
  2. minLength/maxLength 的值被烧进文法结构,xgrammar 把它编译成 Repeat(char, min, max),maxLength=100 和 101 在文法上是两个不同对象,不可能共享编译产物;
  3. rtp-llm 的 C++ 层缓存默认无上限(compiler_cache_bytes = -1,CLI 才覆盖为 512MB);
  4. 业务把 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
2
3
4
5
6
7
8
9
10
# 模型只输出一个枚举值
category = llm.classify(text, choices=["退款", "换货", "咨询"])

# 代码负责确定性部分
response = {
"category": category,
"ticket_id": str(uuid4()),
"created_at": now().isoformat(),
"priority": PRIORITY_MAP[category],
}

这一步就能消灭大量”让模型生成 ID 和时间戳”的荒唐场景。

模式二:抽取语义字段,序列化交给代码。

需要结构化数据时,让模型输出的应该是”它真正知道的字段”,而不是整个响应体。格式、嵌套、包装、默认值全部由代码补全:

1
2
extracted = llm.extract(text, fields=["name", "city"])  # 只抽取
payload = build_payload(extracted, schema=API_SCHEMA) # 代码组装

模式三:长度和格式这类确定性约束,移到代码层。

maxLength 的诉求通常是”别撑爆下游字段”,那就在代码里截断,而不是让模型在生成时就盯着字符数:

1
title = llm.summarize(text)[:128]   # 约束在代码层,简单且确定

顺带说明:这样反而绕开了本文开头的事故——没有动态长度值,就没有无限增长的文法缓存。

模式四:如果确实需要动态 schema,做归一化与分桶。

1
2
3
4
5
6
7
8
9
import json

def canonical(schema: dict) -> str:
# 固定 key 顺序与分隔符,消灭伪缓存未命中
return json.dumps(schema, sort_keys=True, separators=(",", ":"))

def bucket_length(n: int, step: int = 256) -> int:
# 长度值分桶,把无限基数压到有限档位
return ((n + step - 1) // step) * step

再加两道运维防线:显式设置编译缓存上限(vLLM 是 VLLM_XGRAMMAR_CACHE_MB,rtp-llm 是 GRAMMAR_COMPILER_CACHE_BYTES),并在监控里盯住编译耗时与缓存命中率——缓存的命中率就是 schema 多样性的体温计。

八、上线前的检查清单

如果最终评估下来仍然要用约束解码,至少逐条过一遍:

  • schema 字符串是否稳定?有没有在入口做归一化?
  • 有没有随请求变化的字段:动态长度、动态枚举、动态字段集?
  • 编译缓存上限是否显式配置,还是吃了框架默认值?
  • pattern/format 与长度约束是否同时出现?当前引擎是拦截还是静默丢弃?
  • 编译耗时、缓存大小、命中率有没有监控和告警?
  • 约束请求与 beam search、n > 1、思考模式的兼容性是否验证过?
  • 编译失败、预算耗尽、EOS 边界这些失败语义,是否符合预期?
  • 升级 xgrammar 版本后,有没有逐 token 的回归验证?

九、结语:确定性属于代码,概率属于模型

回到那行 maxLength: 128。它的初衷是”让模型别写太长”,但它把一个本该由代码层承担的确定性职责,塞给了概率模型和最复杂的运行时系统,最终以内存泄漏的形式收场。

模型擅长的是在不确定中做选择:判断、抽取、归纳、生成。代码擅长的是在确定中做执行:计算、格式化、组装、校验。约束解码的价值,是给前者的输出加一道语法护栏;它从来不是把后者也交给模型生成的理由。

真正可靠的系统是分层设计的:让模型做只有模型能做的事,其余的一切交给代码。 语法约束可以是最后一道防线,但不该是第一块砖。

CATALOG
  1. 1. 正文
    1. 1.1. 一、”100% 合法”到底保证了什么
    2. 1.2. 二、确定性内容,就不该让模型来生成
    3. 1.3. 三、语法约束的账单
    4. 1.4. 四、一场完整的归因:动态长度值如何吃光内存
    5. 1.5. 五、xgrammar 的坑,不止缓存
    6. 1.6. 六、什么时候该用,什么时候该换设计
    7. 1.7. 七、更工程的做法
    8. 1.8. 八、上线前的检查清单
    9. 1.9. 九、结语:确定性属于代码,概率属于模型