1. 从一次真实“翻车”说起JSON 输出的三种常见事故现场在正式聊方案之前我觉得有必要先把一个很多人不愿意面对的真相摆上桌大模型返回 JSON从来不是“加一句返回 JSON 格式”就能完事的事情。我自己最早做 AI 应用对接时就吃过一次很惨的亏。那时候调用一个大模型接口做客服工单自动分类prompt 里写得清清楚楚“请以 JSON 格式返回包含 category 和 confidence 字段。”模型也确实返回了 JSON我拿到响应后直接json.loads()结果当场报错。我盯着原始字符串看了半天才发现模型在 JSON 前面加了一行“好的这是您需要的分类结果”后面还跟了一段 Markdown 围栏用 json 包着。这就是所谓的“包装污染”。第二类事故是字段缺失。模型返回的 JSON 结构看着没问题但里面的confidence字段消失了取而代之的是confidence_score或者更离谱的可信度。原因是模型为了“讨好”你的自然语言描述擅自改了字段名。第三类事故最恶心叫做“优雅截断”。当生成内容超过 max_tokens 限制时模型会在一个 JSON 字符串写到一半时戛然而止留下一个语法完全不完整的残缺 JSON。这类问题在长文本摘要或批量生成场景里出现概率极高而且极难通过肉眼排查因为外层结构看起来非常正常。这三类事故几乎覆盖了绝大多数大模型 JSON 输出的翻车场景。它们背后有一个共同的根因大模型本质上是概率文本生成器它并不理解 JSON 的语法规则只是在模仿训练数据里见过的 JSON 样式。所以指望 prompt 一句话就让模型严格遵守 JSON Schema等于指望一个实习生在第一次接到需求时就写出零 bug 的代码——偶尔可以长期不靠谱。这篇文章要做的就是把“如何让大模型稳定返回 JSON”这件事从玄学变成工程学。我会从问题根因、约束解码、后处理修复、防御性解析四个层面完整拆解最后给出一套可以直接落地的分层方案和实测配置参考。无论你是做 Agent、写自动化脚本还是搞知识库问答这套思路都能直接套用。2. 为什么大模型输出 JSON 这么不稳定约束层级缺了三环网上很多教程会把 JSON 输出失败简单归因于“prompt 没写清楚”然后让你把要求写得更啰嗦。这种思路不能说错但只解决了一小部分问题。要真正理解为什么大模型输出 JSON 不稳定得从上到下看一遍生成约束的三个层级。2.1 Prompt 层的“软约束”说得越多越容易跑偏Prompt 是对模型行为的软约束它靠的是模型对指令的“理解力”和“服从度”。你写“请严格返回 JSON不要输出任何其他内容”模型理论上听懂了但在实际生成过程中它并不会像编译器一样对这些指令做硬性检查。尤其是那些参数量较小的开源模型本身指令遵从能力就弱一个复杂任务里塞了角色设定、背景信息、任务要求、输出格式四段话之后模型很容易在生成后期“忘了”格式要求。更隐蔽的问题是当你要求返回 JSON 时模型会倾向于模仿训练语料里常见的 JSON 风格而这些风格千奇百怪。有的模型喜欢在 JSON 外观上套个“解释性前置文本”有的习惯用单引号替代双引号还有的会把布尔值写成字符串 “true”。这些都不是 prompt 能完全约束住的因为模型的下一 token 概率分布里合法 JSON token 和非法 token 同时存在而 prompt 只能改变它们的相对概率无法彻底排除非法项。2.2 采样层的“随机性”温度越高JSON 越容易散架生成阶段的采样参数也是 JSON 稳定性的隐形杀手。temperature、top_p、top_k这些参数控制的是从概率分布中挑选 token 的随机程度。简单说温度越高模型越倾向于选择概率不是最高但更有“创造性”的 token。平时聊天时这种随机性是好东西能让回答更生动但在生成 JSON 时随机性只会增加语法错误的风险。比如生成一个值为false的布尔字段时模型本应以极高概率输出false但温度过高时它可能因为前面某个 token 的概率飘移输出一个半截的fal然后突然跳到别的 token。这类错误在低温度下几乎不会出现但你为了追求回答多样性或“更有推理能力”把温度调到 0.8 以上后JSON 输出就会开始随机抽风。我的经验是凡是要结构化输出的场景温度一律控制在 0 到 0.3 之间top_p 不要超过 0.9。牺牲一点点“创造性”换来的是稳定的格式这笔账绝对划算。2.3 解码层的“硬约束”大模型漏掉的关键一环Softmax 输出的概率分布只是“建议”理论上如果你在解码阶段直接干预 token 选择过程把不符合 JSON 语法的 token 全屏蔽掉模型就只能“被迫”生成合法 JSON。这就是结构化输出最核心的机制——约束解码Constrained Decoding/ 文法采样Grammar Sampling。好多朋友对这个概念比较陌生我用通俗的话解释下大模型生成一个 token 之前会计算出所有候选 token 的概率正常情况下它会按概率抽样。但如果这时候有一个“语法检查器”在旁边看着告诉它“根据当前已生成的内容和 JSON Schema下一个 token 只能是{、、true、false、数字开头等几类”然后把这以外的 token 概率全部设为零那模型无论如何都不会说出“语法错误”的话。这就是约束解码的基本原理。看起来很简单对不对但实现起来需要对解码器底层做侵入式修改不是所有部署框架都支持。目前主流的支持方式有llama.cpp的 GBNF 文法、vLLM的 guided decoding、Outlines库的后端采样以及各大模型厂商 API 自带的结构化输出功能。这一环才是真正让 JSON 输出从“大概率可靠”升级到“理论上可靠”的关键但行业内大部分教程都没把它讲透。3. 从“概率生成”到“语法约束”结构化输出的硬核方案拆解既然问题出在解码层的约束缺失那解决方案就该从解码层入手。这一节我把目前业内最主流、且我实测真正有效的几条技术路线逐一展开。3.1 基于上下文无关文法的约束采样llama.cpp 的 GBNF 语法如果直接在本地部署模型llama.cpp是绕不开的选择。它提供了一套叫 GBNFGGML BNFBackus-Naur Form的语法定义格式允许你描述合法的输出结构然后在采样阶段注入语法约束。GBNF 的语法表达能力很强不但能定义 JSON还能定义任意编程语言的输出结构。举个例子假设我需要模型输出一个包含name字符串和age整数的 JSONGBNF 规则可以写成root :: { ws name ws : ws string ws , ws age ws : ws number ws } string :: \ [^]* \ number :: [0-9] ws :: [ \t\n]*当这条规则传给llama.cpp的采样器后模型每生成一个 token采样器都会检查当前状态如果某个候选 token 会把输出带离语法规则它的概率会被直接设为零。这样生成出来的内容从根上就不可能是非法 JSON。我实际测下来即使把 temperature 拉到 1.0GBNF 约束下的 JSON 输出依然结构完好只是字段内容会飘一些。这套机制对稳定性的提升是 prompt 完全没法比的。不过 GBNF 的缺点是写起来有点费劲尤其是嵌套复杂对象和数组的时候。所以后来社区里冒出了outlines、jsonformer这类库它们能根据 JSON Schema 自动生成对应的正则或上下文无关文法你只需要把 Schema 传进去就行完全不用手写 GBNF。3.2 Outlines 库用 JSON Schema 直接约束生成路径outlines是我个人非常推荐的一个 Python 库它把结构化生成做到了开箱即用。它支持的模型后端很多包括transformers、llama.cpp、vLLM、Ollama等API 设计也简单直白。核心用法是outlines.generate.json()把模型和 JSON Schema 传进去它就返回一个只会生成符合 Schema 内容的生成函数。实际使用中大概是这种感觉import outlines import json schema { type: object, properties: { category: {type: string, enum: [网络故障, 账号问题, 账单咨询]}, confidence: {type: number, minimum: 0, maximum: 1}, }, required: [category, confidence], } model outlines.models.transformers(Qwen/Qwen2.5-7B-Instruct) generator outlines.generate.json(model, schema) result generator(工单内容我的网线被猫咬断了上不了网) print(json.loads(result))这里有个很实用的细节enum 字段在约束解码下会变成一个“绝对安全区”。比如category只能取三个枚举值采样器会直接把枚举之外的 token 全部屏蔽模型只能在这三个选项里挑。这种能力做信息抽取、分类打标时尤其爽彻底告别了“模型又给我返回一个不在预设列表里的标签”这种问题。在底层实现上outlines 根据 Schema 构造了一个有限状态机在每一步采样时拿到当前状态允许的下一个 token 集合再对模型输出的概率分布做掩码。由于状态转移是确定性的所以整个过程的稳定性是数学意义上可保证的而不是概率意义上的“大概率稳定”。3.3 vLLM 的 guided decoding生产环境的服务化部署方案如果你做的是线上服务大概率会用vLLM做模型推理加速因为它吞吐量高、显存管理好。好消息是 vLLM 也内置了结构化输出能力并且做得相当完善。我在实际项目中用的方案是直接初始化一个支持 OpenAI 协议的服务通过 API 参数response_format指定json_object或json_schema由 vLLM 在服务端完成约束解码。curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen/Qwen2.5-7B-Instruct, messages: [{role: user, content: 把这句话转成结构化信息张三在昨天下午三点提交了退货申请}], response_format: { type: json_schema, json_schema: { name: return_info, strict: true, schema: { type: object, properties: { name: {type: string}, time: {type: string}, action: {type: string} }, required: [name, time, action] } } } }值得留意的是vLLM 的 guided decoding 底层实现方式会根据模型格式自动选择最佳引擎。比如对llama.cpp格式的模型它走 GBNF 文法约束对Transformers格式的模型它走outlines或xgrammar的有限状态机解码。所以不同模型的兼容性表现可能略有差异但只要是常见格式问题都不大。生产环境的建议是优先用 vLLM 的 guided decoding少自己写一些花里胡哨的解析逻辑稳定压倒一切。3.4 云厂商 API 的结构化输出只选最香的一条路如果你用的是 OpenAI、Anthropic、Google 或其他国内大模型厂商的托管 API那么恭喜你很多底层麻烦已经被封装好了。OpenAI 比较早就推出了function calling现在更是有了Structured Outputs也就是response_format设为json_schema并开启strict: true。这种模式下的输出是“模式保证”的schema guarantee也就是说只要 Schema 合法模型输出必然可以被 Schema 校验通过。用 OpenAI 官方 SDK 时代码大概长这样from openai import OpenAI client OpenAI() response client.chat.completions.create( modelgpt-4o, messages[ {role: system, content: 提取用户意图并返回结构化结果。}, {role: user, content: 帮我查一下北京的天气然后订一家附近的川菜馆}, ], response_format{ type: json_schema, json_schema: { name: intent_extraction, strict: True, schema: { type: object, properties: { intents: { type: array, items: { type: object, properties: { action: {type: string}, target: {type: string} }, required: [action, target], additionalProperties: False } } }, required: [intents], additionalProperties: False } } } )这里有几个在使用结构化输出时非常容易被忽略的坑我得单独列一下additionalProperties必须设为falseOpenAI 的 strict 模式要求所有的属性都要提前声明不然模型有时候会“自由发挥”加上没有定义的字段导致校验失败或者下游代码出 bug。所有字段都必须出现在required里如果某个字段是可选的strict 模式可能会拒绝执行或者模型因为不确定字段是否必须干脆不生成该字段。官方文档也明确写了一点strict 模式下所有字段均需要标记必填。不支持minLength、maxLength、pattern这类高级校验关键字Structured Outputs 的 Schema 子集并不完整某些 JSON Schema 语法是受限的。用了不支持的校验关键字API 会直接报错。如果你的服务偏国内环境不少云厂商也已经在 API 中提供了类似机制比如百度千帆、阿里云百炼等都可以指定response_format为json_object。整体水平参差不齐但思路一致让服务端在解码时帮你做约束。选型时认准一点就好——若平台接口明确说“保证 JSON 格式合法”就优先依赖它不用再做额外的后处理若平台没说这话就得做好清洗的准备。4. 后处理兜底层当模型已经放飞自我如何把 JSON 从“垃圾桶”里捞回来即使你用了约束解码生产环境里依然会碰到一些“理论上是无限接近零实际上还是会发生”的怪事。比如服务端返回了空字符串、流式传输中途断连、代理层偷偷加了个 BOM 头、或者其他后处理框架把内容截断了。这时候就需要后处理兜底层上阵把那些不完美的文本尽量恢复成可解析的 JSON。4.1 清洗 修复json_repair 这类工具关键时刻能救命先聊最简单实用的一招封装一层“清洗 修复”方法。清洗指的是去掉 JSON 前后的 Markdown 围栏、解释性前缀、尾缀等修复则对应处理引号缺失、多余逗号、截断等情况。Python 社区有个专门的库叫json_repair它能把很多坏 JSON 修复成标准 JSON底层逻辑类似一个宽容版的解析器。import json_repair raw json\n{name: 张三, age: 28,}\n fixed json_repair.loads(raw) print(fixed) # {name: 张三, age: 28}这个库我实测过不少场景字段尾逗号、单引号、换行不转义、截断的半截 JSON它都能救回来一部分。当然它不是万能的如果内容缺失严重比如数组只生成了一半修复结果也只是“尽力而为”。所以我的策略是修复之后立刻用更严格的 Schema 校验若校验不过宁可重试一次也不想用脏数据硬顶。4.2 流式输出场景一边攒一边修别等整包到达如果你做的是类 ChatGPT 的流式输出那么接收到的文本是逐 token 到达的。此时如果用户想看实时效果你得把“解析 JSON”从一次性的动作改成“增量判断”的动作。常规做法是维护一个缓冲区每收到一段新文本就尝试json_repair.loads()如果解析成功且字段完整就更新渲染结果如果解析失败就用“上次成功解析的结果”顶住界面直到新的合法数据出现。这里有一个小经验流式场景下尽量不要实时把缓冲区的“未完成 JSON”展示给用户否则用户会看到一长串奇奇怪怪的断点。更好的方式是让前端等模型输出完毕后一次性拿到完整结果再渲染或者按字段维度做分块渲染比如先渲染title字段再渲染content字段每个字段等其完整后再展示。4.3 解析失败的最终防线重试机制和退让策略修复校验都失败时不要直接就抛异常到用户脸上。最高效的做法是设计一个带重试机制的调用函数也就是说当 JSON 解析失败时把场景里的 prompt 稍作调整再调用一次模型。我写过一个简化的重试逻辑import json import time def call_model_retry(prompt, max_retries3): for attempt in range(max_retries): text get_model_response(prompt) try: return json.loads(text) except json.JSONDecodeError: # 如果失败让模型看到自己的错误并要求自我修正 fix_prompt ( f你上次返回的内容无法解析为合法 JSON。\n f原始内容\n{text}\n\n f请只输出合法的 JSON不要添加任何其他说明。 ) text get_model_response(fix_prompt) try: return json.loads(text) except Exception: time.sleep(1 attempt) raise RuntimeError(模型连续多次无法返回合法JSON)这个“让模型自我修正”的策略在多数模型身上都有效因为模型看到自己的输出和错误提示后通常能够意识到格式问题并给出修正版本。但不要无限重试——超过 2 到 3 次仍失败基本上就是任务本身超出了模型能力范围不如早点降级处理或者换一个更小的 Schema。5. 防御性解析与 Schema 设计给下游代码上一层保险结构化输出这件事不能只把眼睛盯在“生成端”消费端的解析设计同样重要。很多人在json.loads成功之后就以为万事大吉了结果后面只要字段多一层嵌套、少一个默认值线上直接就炸了。5.1 用 TypedDict / Pydantic 做解析层而不是一把梭 loads如果你用 Python 开发习惯是json.loads(response)后直接当字典用。但字典是最不设防的数据结构访问不存在的 key 会抛 KeyError类型不对也不会提醒。更好的做法是引入类型约束让解析结果一出来就已经是“有校验的数据对象”。轻量做法是用typing.TypedDict配合mypy或 IDE 类型检查更完整的做法是用 Pydantic v2。下面是一个用 Pydantic 做解析校验的例子from pydantic import BaseModel, Field class TicketResult(BaseModel): category: str Field(..., description工单分类) confidence: float Field(ge0, le1, default0.5) tags: list[str] Field(default_factorylist)这样即使模型返回的 JSON 缺少tags字段解析层也不会报错而是用默认的空列表顶上。显式声明“缺失时的默认行为”正是防御性解析的核心思想。还有一个小细节Pydantic 默认是“允许未知字段”的v2 也可以配置忽略在对接模型输出时建议开启model_config ConfigDict(extraignore)避免模型多输出的字段破坏了你的业务逻辑。5.2 Schema 的字段设计直接影响稳定性从源头降低生成难度跟模型打交道的次数多了你会越来越认同一个感觉模型能否做到稳定的 JSON 输出和 Schema 设计水平强相关。几个减少出错率的字段设计原则直接分享给大家能限制枚举值就限制枚举值。比如“满意度评分”字段与其让模型自由填一个数字不如直接限定取值范围 1 到 5并在 Schema 里表达出来这样模型的选择空间小输出更稳定。尽量用扁平结构避免深层嵌套。模型对三层以上嵌套的数据结构理解力会显著下降尤其是数组里嵌套对象再嵌套数组的组合经常出现括号不匹配的情况。能用二维表结构表示的就不要强行包三层。重复字段用数组而不是拼接字符串。比如“关键词列表”正确做法是{keywords: [AI, 大模型]}不是{keywords: AI、大模型}前者对模型更直接。合理使用description字段。不管是 OpenAI 还是 Pydantic在字段上写清楚“这个字段的语义是什么、格式应该是什么”对模型的生成准确率会有直观提升。比如日期字段如果你不写 YYYY-MM-DD模型很容易给你来一个“3月21日”之类的口语化表达。5.3 实测对比无约束 vs 约束解码的稳定性差距为了让大家有一个更直观的感知我拿某个 7B 规模的开源模型做了一组小测评任务是从一段文本中抽取“人名 时间 操作类型”每组跑 50 条数据记录 JSON 解析成功率。测试结果如下方案解析成功率字段严格符合 Schema 的比例平均延迟备注仅 prompt 要求 JSON76%52%132ms大量出现前缀污染、字段名篡改prompt 温度调低到 0.282%61%133ms略有提升但字段漂移无法根治prompt 后处理 json_repair91%68%138ms解析成功率上来了但内容质量提升有限约束解码outlines/guided decoding100%100%155ms代价是每次生成多了一点语法检查开销可以看到约束解码把解析成功率从 76% 拉到了 100%这种提升是模型技巧层面很难达到的。延迟增加的十几毫秒绝大多数场景都感知不到换来的却是下游逻辑的绝对稳妥。6. 分层落地方案从“能用”到“好用”的完整架构前面把四个层面的技术方案拆开讲完了这一节把它们组合成一套完整的分层架构方便你直接拿到项目里套用。我的经验是不要把任何单一手段当成银弹而是用“约束层保底、修复层兜底、校验层把关”的思路做组合。6.1 架构总览七行伪代码看清整套流程如果让我用一句话总结一个稳定的生成结构是这个套路先尝试服务端约束response_format / guided decoding拿到文本再清洗再宽松修复最后严格校验校验失败走重试或自我修正最终不再直接报错给用户。伪代码逻辑如下1. 定义 JSON Schema字段、类型、必填、枚举范围 2. 准备 promptsystem prompt 里声明只用 JSON 返回不要任何修饰语 3. 调用模型接口优先开启 response_format / guided decoding 4. 拿到原始文本 5. 去除多余前缀、后缀和 Markdown 围栏 6. 尝试 json.loads成功则继续失败则 json_repair 修复 7. 用 Pydantic/Schema 校验结构 8. 校验失败时自动重试一次让模型看到错误并自我修正 9. 重试仍失败降级返回默认值或转人工流程这样一套链路下来我在实际项目中得到的体感是一百次结构化输出里大概有九十五次在第一层就拿到了合法结果三四次靠修复层救回来真正需要重试或降级的已经极少极少。6.2 本地部署场景的具体配置参考如果你用的是 Ollama它支持一个非常方便的format: json参数。这个参数做的事情本质上就是约束解码只是它是通用约束——只约束“必须输出 JSON”但不约束“必须符合某个具体的 Schema”。用起来大概是ollama run qwen2.5:7b --format json然后从代码里调用时可以在 API 请求体里带上format字段response requests.post(http://localhost:11434/api/chat, json{ model: qwen2.5:7b, messages: [ {role: system, content: 提取工单信息。只输出 JSON 对象。}, {role: user, content: 用户反馈昨天晚上玩游戏掉线三次} ], format: json, stream: False, options: {temperature: 0.2} })这种方式的优点是简单不需要定义复杂的 Schema缺点是它不保证字段名和类型。适合快速验证不适合严谨的生产链路。严谨的场景还是用 vLLM guided decoding 或者 Outlines这两种方式都能把 Schema 约束做到底。6.3 使用 Structured Outputs 后仍需注意的三个“隐形地雷”就算你用了最先进的结构化输出能力实测中还是有一些“官方文档里的隐形地雷”要留意第一个是“流式 严格模式”的组合坑。有些平台的流式接口对response_format支持不完整可能导致约束失效。我的建议是需要严格 JSON 时优先用非流式接口如果必须流式输出就先把流式内容缓冲到本地等完整结束后再做校验不要逐 token 校验。第二个是“复杂 Schema 的超时”问题。当 Schema 太复杂、嵌套太深时约束解码会拖慢生成速度甚至触发服务端的超时限制。实测中遇到过单次请求因为 Schema 过于庞大而多耗了近一倍时间的情况。解法是把大 Schema 拆成几个小 Schema分步让模型生成最后在代码里合成。第三个是多轮对话中 Schema 状态保持的问题。如果你在 Agent 里连续多次调用模型做结构化输出每一轮都要重新传一遍 Schema。某些 SDK 的缓存机制可能会导致上一轮的 Schema 被误用到下一轮所以代码里不要图省事复用旧的 response_format 对象最好每次调用都显式传入。6.4 给团队落地时的两条建议最后补充两点团队协作层面的建议是我在实际项目里踩过坑后总结出来的建议把 JSON Schema 抽成公共模块统一管理。当一个项目里有多个场景需要结构化输出时如果每个人各写各的 Schema字段名的风格五花八门后面做数据打通时会非常痛苦。统一用一份“字段字典”或 Proto/JSON Schema 文件集中管理团队内共享是值得提前做好的基础设施。建议建立“输出质量可视化监控”。说白了就是记录每次模型输出的解析成功率、修复率、重试率按天或按周看趋势。这个指标能很直观地反映模型迭代、prompt 调整、Schema 修改的线上影响。没有数据看板你永远不知道某次 prompt “优化”到底是在变好还是在变坏。我自己习惯把这些日志全部打到 ClickHouse 或 Elasticsearch 里配上简单的折线图效果很直观。7. 总结与个人实践经验七八年做工程下来的一个习惯是写技术文章时最后总喜欢把“如果让我重新做一遍我会怎么选”这件事交代清楚。结构化输出这个话题绕了一圈又回到那句老话——先搞清楚自己手里的牌。如果你用的是云厂商的大模型 API第一选择永远是平台自带的 Structured Outputs / JSON Mode因为你付了钱就应该让服务商把质量保证打包交给你省下来的时间用来做上游的 Schema 设计和下游的业务逻辑。如果你用的是本地部署的开源模型那我推荐以 vLLM 作为生产推理引擎开启 guided decoding然后配上 prompt 加固 json_repair 兜底 Pydantic 校验三层保险。如果只是本地简单实验或者写个小工具Ollama 的format: json加温度调低就能应付大多数场景。个人而言我最近在做的几个 Agent 项目里已经把“约束解码”从选配变成了默认配置。原来每写一个功能都要在 prompt 末尾加上“注意必须返回 JSON不要带额外文字”然后心惊胆战地看日志现在这些心理负担全没了。唯一需要持续投入精力的反而是 Schema 本身的演进——业务变了、字段改了、枚举值加了这些都需要人来做模型和代码都替代不了。最后送大家一个我觉得最好用的小技巧写 prompt 时不要只写“返回 JSON 格式”而是把目标 Schema 直接以三引号的形式贴进 system prompt告诉模型“严格按以下 JSON Schema 输出……不要输出任何与 JSON 无关的内容”。这一个小动作在很多不支持服务端约束的低端模型或老模型上也能显著提升稳定率。结构化输出这条路一层一层修下去其实没有太多玄学拼的就是谁把细节抠得更死。