本地模型 JSON 输出怎么约束:三档实测,开思考全废

结论先说:同一套订单抽取任务,三种约束写法的字段准确率完全一样,都是 88.1%。真正决定成败的是思考模式和输出预算。开思考又不给足 token,6 份多单文档 6 份截断,一条可用的 JSON 都拿不到。

测试机是 M4 16GB,推理框架 llama.cpp 0.9.0(build 12110),模型用 Qwen3-4B Q4_K_M(2.4GB)与 Qwen3-1.7B Q8_0(1.8GB)。温度 0,固定种子 42,单槽位串行请求。任务集分两组,30 条单订单中文消息,6 份多订单文档(每份 4 到 6 单,每单 2 到 3 条明细)。金标由脚本生成,逐字段硬比对,不做人工判分。

三种约束写法的成绩单

单条抽取这组,每条消息要吐出 7 个字段,输出预算 512 token。七种配置各跑 30 条,合计 210 次请求,全部本地回环,没有网络抖动。

写法 可解析 字段命中 平均耗时 完成 token
只写提示词,关思考 30/30 185/210(88.1%) 2.47 秒 2313
只写提示词,开思考 25/30 164/210(78.1%) 11.73 秒 12328
json_object,开思考 25/30 164/210(78.1%) 11.72 秒 12328
json_schema,开思考 25/30 164/210(78.1%) 11.67 秒 12328
json_schema,关思考 30/30 185/210(88.1%) 2.32 秒 2313
GBNF 文法,关思考 30/30 185/210(88.1%) 2.22 秒 2304
GBNF 文法,开思考 30/30 186/210(88.6%) 2.32 秒 2422

最扎眼的是思考模式那三行。同一个提示词,关掉思考 30 条全部可解析,准确率 88.1%,平均 2.47 秒。打开思考 5 条被截断,准确率掉到 78.1%,平均 11.73 秒。完成 token 从 2313 涨到 12328,五倍多,换回来的是更差的成绩。

json_schema 和 GBNF 在这组任务上没有带来任何准确率提升。原因不难理解:七个字段里五个能直接从原文抄,类别是五选一,Qwen3 这个量级本来就不会写错格式。约束的价值不在提分。

真正没救住的是标签字段。要求只填「专票、分期、老客户、转介绍」里出现过的词,最好的一次 16/30,最差 7/30。模型会把「设备采购」「HT-9000」这种原文里的词塞进去。约束能限制取值范围,限制不了该不该填。

服务和请求怎么发

三个片段都能直接粘。启动命令里模型路径换成自己的,–jinja 默认开启,别手动关掉。

llama-server -m Qwen3-4B-Q4_K_M.gguf --port 8137 --host 127.0.0.1 \
  -c 8192 -np 1 --jinja --temp 0 --seed 42

写法一,只靠提示词,把字段清单塞进 system。

{"messages": [
  {"role": "system", "content": "只输出 JSON 对象,字段 order_id、customer、amount_yuan、deadline、category、urgent、tags"},
  {"role": "user", "content": "单号 SO-004700,客户 杭州瑞谱仪器,金额 80800 元"}],
 "max_tokens": 512, "temperature": 0}

写法二,用 json_schema。这里有个位置坑,schema 必须嵌在 response_format.json_schema.schema 里。

"response_format": {
  "type": "json_schema",
  "json_schema": {"name": "order", "schema": {"type": "object", "...": "..."}}}

写成 response_format.schema 会怎样?实测被静默忽略,服务端连报错都不给。用一个反例最能说明:schema 要求 x 是整数、y 是字符串,请求里故意让模型反着写。正确写法输出 {“x”: 123, “y”: “hello”},类型被强制纠正;写成 response_format.schema 时输出 {“x”: “hello”, “y”: 123},约束完全没进模型。顶层直接给一个 json_schema 键也能生效,两种都行,就是别用 response_format.schema。

写法三,手写 GBNF。键序和空白都由文法决定,输出最紧凑。

root ::= "{" ws "\"order_id\"" ws ":" ws oid ws "," ws "\"customer\"" ws ":" ws str ws "}" ws
ws   ::= [ \t\n]*
str  ::= "\"" ch* "\""
ch   ::= [^"\\\x00-\x1F] | "\\" (["\\/bfnrt] | "u" hex hex hex hex)

json_object 只保证一个空对象

这是最容易被误解的开关。拿一句散文去请求,内容是「用一句中文说说今天天气不错」,带上 json_object,返回的是 {},23 个 token 就结束。它确实起了作用,作用仅止于把输出塞进一对花括号。

在 30 条抽取任务上更直接。json_object 组的输出与纯提示词组逐字相同的有 29 条,完成 token 总数两边都是 12328,一个不差。这个开关对结构化抽取等于没设。

思考模式吃预算

换成多订单文档,思考模式的问题被放大。6 份文档,每份 4 到 6 单,每单 2 到 3 条明细,输出预算 1024 token。

模型与写法 全对文档 截断份数 平均耗时
4B,只写提示词 6/6 0 16.3 秒
4B,json_schema 6/6 0 15.4 秒
4B,GBNF 6/6 0 15.4 秒
4B,json_schema 加思考 0/6 6 30.3 秒
1.7B,只写提示词 6/6 0 11.7 秒
1.7B,json_schema 6/6 0 11.2 秒
1.7B,GBNF 6/6 0 11.3 秒
1.7B,GBNF 加思考 6/6 0 13.9 秒
1.7B,json_schema 加思考 2/6 4 21.9 秒

4B 上,schema 加思考 6 份全截断,finish_reason 都是 length,content 停在 {“orders”: [{“order_id”: “SO-007 这种半截状态。30.3 秒换回 6 个空结果。1.7B 好一点,也只剩 2 份能用。

把预算加到 4096 就恢复了。同样两份文档,4/4 与 5/5 全对,思考链分别是 1093 和 1250 字符,耗时 25.6 秒与 26.4 秒,完成 token 1192 与 1233。同一件事,不开思考 11.2 秒 500 多 token 就够。要不要这 2.3 倍时间和 2.2 倍 token 取决于任务难度,但至少别拿 1024 的预算去开思考。

判断方法只有一个字段,finish_reason 是不是 length。被截断的 JSON 前半段完全合法,json.loads 会报 Expecting delimiter 或者 Unexpected end,看起来像模型不会写格式,实际是没写完。这条在别的推理服务上也成立,Xinference 那篇里 context_length 按槽位分配的坑属于同一类预算问题。

GBNF 会把思考掐掉

手写文法有个副作用,reasoning_content 一个字符都没有。因为 grammar 从第一个 token 就开始限制,思考标签根本挤不进输出。4B 上 GBNF 加思考的配置平均 2.32 秒,和不加思考的 2.32 秒完全一样,准确率 88.6% 还高了一点点,多对一个标签,属于噪声。

这条可以直接用。想让本地模型先想再答,就别上 GBNF;上了 GBNF 等于关掉思考,换来绝对可解析和最低延迟。想让模型自己选,就把思考留给模板层,约束只加在 JSON 段,llama.cpp 的 json_schema 正是这么做的。

schema 里哪些关键字真生效

llama.cpp 把 JSON schema 翻译成 GBNF 再解码,支持面比想象宽。用 13 个关键字逐个做反例测试,提示词明确要求模型写出违反约束的值,看它能不能写出来。

schema 关键字 结果 实测表现
pattern 生效 要求 6 位大写加连字符,输出 HEL-01
enum 生效 诱导写丙,输出乙
minimum / maximum 生效 诱导写 250,输出 2
maxLength 生效 诱导写长句,截到 4 个字
minItems 生效 诱导只给 2 个数,补到 10 个
maxItems 生效 诱导给 6 个数,砍到 2 个
additionalProperties 生效 要求多加字段,一个不加
const 生效 诱导写 other,仍输出 FIXED
anyOf 生效 诱导写字符串,输出整数 1
oneOf 生效但误导 诱导写数组,输出字符串 [1, 2]
$ref 生效 引用 $defs 里的对象,输出嵌套对象
format=date 生效但编造 输出 2023-10-05,与原文无关
minLength 崩 字符串不闭合,漏出思考标签,3 次全崩

12 个生效。模型被逼着改值,要它写 250 就输出 2,要它给六个数就只给两个,要它多加一个字段直接不加。这类约束在真实业务里很有用,尤其是金额范围、日期格式、状态枚举。

崩的是 minLength。schema 要求字符串至少 20 字,用户只给一个「好」字,输出变成 {“t”: “好’} 后面接思考结束标签和一大段解释,整段 JSON 没有闭合,重跑三次三次一样。把 minLength 降到 5 也一样,模型会拿单引号和漏出来的标签凑长度,JSON 恰好能解析,值是垃圾。这是本轮唯一一个能把输出彻底搞坏的写法。

oneOf 属于合规但不对。要它写数组 [1,2],约束允许整数或字符串,模型输出的是字符串 “[1, 2]”。format 为 date 时它会凭空编一个 2023-10-05 交差,看着像日期,和原文毫无关系。anyOf 在同样场景下选择了整数 1,没有编造,差别在于两个分支都会被尝试。

踩坑:反斜杠路径与制表符

这组专门放难转义的字符,值里有 ASCII 双引号、Windows 共享路径、制表符、换行、emoji。8 条任务,输出预算 300 token。

写法 可解析 值与原文一致 坏在哪
只写提示词 6/8 2/8 \order 报 Invalid \escape,制表符报 Invalid control character
json_schema 8/8 2/8 \order 静默变成 0x0C 换页符,制表符变空格
GBNF 8/8 2/8 与 schema 完全相同

只写提示词时 6 条可解析,坏的 2 条恰好都是转义问题。共享目录 \\192.168.1.8\order 里的 \o 不是合法转义,json.loads 直接 Invalid escape;制表符被原样塞进字符串,报 Invalid control character。这两条理解全对,就是格式坏了。

加上 schema 或 GBNF,8 条全部可解析,但值被悄悄改了。\order 变成 0x0C 换页符加 older,因为 \f 是合法转义,模型选了它;制表符变成空格。解析率从 75% 到 100%,数据保真度一点没改善。这类问题在日志里看不出来,只能靠比对。

判断方法很土但有效。把黄金值的关键片段(这里是 \\192.168.1.8 和 A区)拿出来在输出里 grep,命中率比长度校验灵敏得多。长度会被空格替换掩盖,片段不会。

可以直接抄的配置

按这轮数据,本地做结构化抽取的默认组合是:enable_thinking 关掉,response_format 用 json_schema,max_tokens 按期望输出字数的 1.5 倍给,服务端保持 –jinja 开启。这一套在 4B 和 1.7B 上都拿到了 6/6 全对。

什么时候换成 GBNF:需要固定键序给下游做流式截取,或者延迟卡得极死。什么时候必须开思考:字段要从长文里推理出来,比如跨段落对账、金额求和、日期换算。这时候预算至少给到不开思考的三倍,否则前面那 6 份全截断就是结局。

无论哪种写法,值保真都得在代码里再校验一次。schema 管得住类型和取值范围,管不住反斜杠和制表符,也管不住标签该不该填。同一条链路上的相邻问题可以对照站内两篇实测:量化档位怎么选里 1.7B 七档的精度差异,和llama.cpp 投机解码里解码参数对速度的影响。如果你用的是 Ollama,模板层还有一套自己的坑,可以看Ollama 函数调用怎么配;换到 Xinference 这种带鉴权的服务,先读Xinference 部署实测里关于 context_length 的部分。

常见问题

加了 json_schema 还是解析失败,先查哪里?
先看 finish_reason 是不是 length,是就是预算不够,常见于开了思考模式的模型。再看 content 第一个字符是不是空格或代码块标记,有些模板会把 JSON 包进三反引号。最后才查 schema 写法,response_format.schema 这种位置会被静默忽略。

中文会被转成 \uXXXX 吗?
三种写法下 210 次请求都没出现 \uXXXX 转义,中文原样输出。原因是 GBNF 的字符类按 Unicode 码点匹配,不按字节。万一遇到转义,json.loads 会自动还原,比对时比解析后的值,别比原始字节。

生产上该用 schema 还是手写 GBNF?
优先 schema,可读、好维护,改字段不用重写文法,llama.cpp 13 个关键字里 12 个都生效。GBNF 只在两个场景值得上,需要固定键序做流式截取,或者延迟极敏感。两者共用的坑是转义字符和该不该填,这两件事只能靠代码二次校验。

全部文章归档与模型专题