做了两年多大模型应用开发几乎每次技术分享都有人问同一个问题怎么让大模型老实输出 JSON表面上这像是个很小的工程问题实际遇到才知道模型不按套路出牌的时候轻则丢一个字段重则整段返回散文想用程序解析只能干瞪眼。大模型的输出本质是概率采样它天生不知道“类型”为何物。你让它返回一坨 JSON它可能给你在 JSON 前后附赠一段“好的下面是我的回答”之类的废话你让它返回数组它可能在最后一个元素后面留个多余逗号你让它值必须是整数它给你返回“三”。这些不是某一个模型的毛病而是当前 decoder-only 架构的自回归机制决定的通病。所以想稳定拿到 JSON不能靠模型自觉得靠工程手段约束。这篇就把我从提示词、JSON Schema、推理框架、function calling、错误兜底几个层面验证过的方法完整梳理一遍适合正在做大模型应用开发的工程师、做数据标注和微调的朋友以及任何被“非结构化输出”折磨过的人。1. 为什么大模型返回 JSON 这么难先搞懂输出原理1.1 大模型的输出机制决定了它天生不守规矩大模型生成文本的方式大家可能已经知道通过自回归的方式一个 token 一个 token 地预测下一个 token 的概率分布然后按概率采样生成。这个机制跟传统的强类型编程完全不同。编程里你定义一个对象字段和类型是编译期就定死的但大模型的输出只有一个约束——下一个 token 在词表里存在。它不会因为“程序员要求输出合法 JSON”就在概率上强制排除非法字符。这就好比你让一个新来的实习生整理会议记录你口头交代“结尾写个 JSON 格式的总结”他听懂了但他不一定知道 JSON 里不能有注释、字符串必须双引号、布尔值必须是 true/false。模型也一样它只是“见过”很多 JSON知道大概长什么样但真让它每次都精确匹配规范的 JSON 语法靠 prompt 里的几句话很难约束住。这也是为什么“结构化输出”会成为一个专门话题的原因。它要解决的不是让模型“理解 JSON”的问题而是让模型在生成路径上被工具链强制纠正的问题。所谓“稳定返回 JSON”本质上是把“模型自由生成”这件事改造成“模型在合法 JSON token 子集里做选择”。1.2 非结构化输出在真实项目中的翻车表现这里说几个我真实遇到过的情况。第一个是前缀污染。模型回答“好的以下是您需要的 JSON”然后再输出 JSON。程序用 JSON.parse(response) 直接抛异常很多人第一反应是自己代码写错了调试半天才发现是模型多说了几个字。这种情况在开放问答类模型里特别常见因为模型被训练成“乐于助人”喜欢加礼貌用语。第二个是格式破洞。模型输出的 JSON 里混入了 Markdown 代码块标记json ...。如果只做简单的字符串裁剪很容易漏掉末尾的 导致反序列化失败。还有的模型会把 null 写成 None把 true 写成 True或者字符串值里出现未转义的双引号。这些都是小的、但非常折磨人的问题。第三个是结构漂移。比如你要求输出一个包含 10 个字段的数组模型只给你返回 8 个你要求字段名必须是 input_text它返回的是 inputText。这类问题在长输出、复杂嵌套结构上尤其明显等你发现的时候下游流程已经报废了。1.3 结构化输出的实际应用场景与价值边界结构化输出不是炫技它解决的是一类很实际的工程问题。最典型的场景是信息抽取。比如从一段客户投诉文本中提取订单号、问题类型、情绪倾向你需要把这些结果直接写入工单系统或数据库非 JSON 格式根本没法自动化。第二个场景是工具调用。现在很多 Agent 架构让模型决定“要不要调用工具”工具参数必须严格符合 JSON Schema否则后端的 Python/Java 服务会直接拒绝请求。第三个场景是批处理下游比如每天跑几百条数据用模型做分类、提取、改写再把结果落库做统计分析。如果输出不稳定整个数据管线就要频繁中断。但也要清楚它的价值边界。结构化输出解决的是“格式稳定”不解决“内容正确”。模型可能乖乖返回 JSON但字段值是错的这在实测中非常常见。所以任何生产级系统都要在结构化输出之上再做一层业务校验比如枚举值白名单、数值范围检查、关联数据验证。我见过不少团队把精力全部放在 JSON 解析上却忽略了内容校验最后模型返回的 JSON 格式完美里面的数据却全乱了套。2. 四层方案选型从提示词硬控到解码约束这里说明一下我习惯把方案分成四层从最轻量到最重量级实际项目里往往是几层方案叠加使用不是单选。2.1 第一层在提示词里立规矩最基础也最快见效的办法是在提示词里明确要求输出 JSON并且附上格式说明。比如请分析以下客户反馈输出 JSON 格式结果只输出 JSON 本身不要输出任何解释。 字段要求 - order_id: 字符串 - sentiment: 枚举值只能是 positive/neutral/negative - summary: 不超过50字的中文摘要 - items: 数组每个元素包含 name 和 count这个方案的优势是零成本改一行 prompt 就行。但它的稳定性只能算“及格线”对能力强的模型比如 GPT-4 级别的闭源大模型、Qwen 系列的大参数开源模型这种写法已经能保证九成以上的成功率但换了小参数模型或者领域语料差异较大的模型成功率可能掉到六成甚至更低。我实际测试过在这种纯提示词方案下最常见的问题就两类一是模型在 JSON 外面包一层 Markdown 代码块二是字段顺序乱排、多字段漏字段。所以纯提示词方案只适合原型验证和低风险场景生产环境不能只靠它。2.2 第二层用 JSON Schema 定义字段边界如果给模型提供 JSON Schema稳定性会有明显提升。JSON Schema 本身只是一个描述 JSON 结构的说明文件但它给了模型更明确的字段名、类型、必填项和嵌套结构。一个典型 schema 长这样{ type: object, properties: { order_id: { type: string }, sentiment: { type: string, enum: [positive, neutral, negative] }, summary: { type: string, maxLength: 60 }, items: { type: array, items: { type: object, properties: { name: { type: string }, count: { type: integer } }, required: [name, count] } } }, required: [order_id, sentiment, summary, items] }使用时把这段 schema 贴到系统提示词或者用户提示词里告诉模型“严格按照以下 JSON Schema 生成”。很多云厂商的 API 现在也支持在请求参数里直接传 json_schema比如 OpenAI 的 response_format 就支持 json_schema 模式这等于在接口层做了第一道格式约束。有朋友会问JSON Schema 和纯文字描述有什么区别我的体会是schema 能把字段的类型和嵌套关系表达得更精确尤其对数组嵌套、枚举值、整数与字符串的区分比文字描述可靠得多。模型在训练时见过大量 JSON Schema它更“认识”这个结构。不过它也只是软约束并不能强制模型逐字遵循。2.3 第三层依赖推理框架的 JSON 约束解码这层是真正的“硬约束”也是我强烈推荐在生产环境使用的方法。简单讲像 Ollama、vLLM、llama.cpp 这些推理框架现在都支持约束解码。它们会在模型做 token 概率采样时动态屏蔽掉所有非法的 token。什么意思呢模型生成“{”之后下一个 token 如果从“合法字段名列表”之外非法框架就直接把概率置为 0模型根本没有机会输出非法字符。Ollama 里这一步最简单请求参数里加一个“format”: json 即可。vLLM 和 llama.cpp 稍微复杂需要传一个 GBNF 语法文件或 guided_json 的 schema 配置但思路一致把生成空间锁定在合法 JSON 范围内。这种方案的稳定性极高基本能做到“只要生成了就一定是合法 JSON”。代价是灵活度降低且生成速度略有下降因为所有 token 都要过一个合法性过滤器。但对多数应用来说这个代价完全值得。2.4 第四层function calling 让模型走“正门”Function calling 是另一个被我频繁使用的方案也可以说是最“正规”的路线。原理不复杂模型被训练成了“工具使用者”当你给它配置了一批函数并要求它“如果需要调用工具请严格按工具参数格式输出”模型会更倾向于输出结构化的 tool call而不是自由文本。这个“倾向”是训练阶段强化的所以稳定性往往比纯文本格式约束更高。比如你定义一个函数 fetch_order_info(order_id: string, include_details: boolean)模型如果真的需要查询订单它会生成一段符合该函数签名的参数 JSON而不是在回答里随手写一个 JSON。实际项目中我经常用 function calling 来实现“抽取分类”这类任务效果比在 prompt 里要求输出 JSON 好很多。四种方案我做个对比方案稳定性实现成本灵活性推荐场景提示词硬控一般极低高原型验证、低风险任务JSON Schema中等低中有明确字段定义的抽取任务约束解码极高中低生产环境、批量数据处理Function Calling高中中Agent 工具调用、参数严格校验3. 实操落地三种最常用的 JSON 稳定输出方案光讲原理不够下面直接给能复制的代码和配置。我以实际项目中最常见的三个场景为例OpenAI 兼容接口、本地 Ollama 部署、自建清洗层。3.1 OpenAI 兼容接口 response_format 的用法与细节现在很多大规模 API 都提供 OpenAI 兼容的接口最直接方式是使用 Python SDK 里的 response_format 参数。from openai import OpenAI client OpenAI() response client.chat.completions.create( modelgpt-4o-mini, response_format{type: json_object}, messages[ {role: system, content: 你是一个信息抽取助手只输出JSON不要输出任何其他内容。}, {role: user, content: 提取这句话中的订单号和情绪倾向订单A10086的用户表示非常不满意要求退款。} ] ) content response.choices[0].message.content print(content)这里有一个容易忽略的细节不少模型的 json_object 模式要求 prompt 里必须出现“json”这个词否则接口会直接报错或者仍然输出纯文本。我第一次用的时候被这个问题卡了半天。所以写 system prompt 时尽量显式带上“输出 JSON 格式”字样不要只写“输出结果”。另外response_format 里的 json_object 模式只保证“返回的是合法 JSON 对象”不保证返回 JSON 里的字段符合你的预期。比如你想要数组它可能给你对象你要整数它可能给字符串。所以生产环境优先使用 json_schema 模式把字段约束也传进去response client.chat.completions.create( modelgpt-4o-mini, response_format{ type: json_schema, json_schema: { name: feedback_extraction, strict: True, schema: { type: object, properties: { order_id: {type: string}, sentiment: {type: string, enum: [positive, neutral, negative]} }, required: [order_id, sentiment], additionalProperties: False } } }, messages[ {role: user, content: 订单A10086的用户表示非常不满意要求退款。请提取订单号和情绪。} ] )注意 strict 参数和 additionalProperties: False 在很多实现里不能乱加尤其是当你的 schema 中存在嵌套对象时strict 模式要求每个层级都要补齐 required 和 additionalProperties否则可能报错。不同厂商的实现细节不一致最好先查一遍文档再上。3.2 本地模型 Ollama 的 formatjson 配置与实测本地部署大模型是很多团队选择的路线Ollama 因为部署简单是我在本地试验时的首选工具。让 Ollama 返回 JSON只需要在请求参数里加一个 format: json。curl http://localhost:11434/api/chat -d { model: qwen2.5:7b, messages: [ {role: system, content: 你是一个信息抽取助手只输出JSON。}, {role: user, content: 提取这句话中的订单号和情绪订单A10086的用户表示非常不满意。} ], format: json, stream: false }在 Ollama 里format 设为 json 后模型会被强制约束成只生成合法 JSON 对象框架甚至在底层使用了动态 token 过滤来确保语法正确。这个是 Ollama 0.5 以后比较成熟的能力实测下来成功率很高。但有个问题Ollama 的 json 格式只约束“是合法 JSON”不会约束 schema。模型可能生成 {order_id: A10086, sentiment: 非常不满意}sentiment 本应该是枚举值结果它给了个自然语言虽然 JSON 合法业务上却是脏数据。所以配合 Ollama 用的时候我会在 system prompt 里把 schema 贴进去同时在下游增加一层值校验双保险。Python 调用 Ollama 的写法也很简单import requests url http://localhost:11434/api/chat payload { model: qwen2.5:7b, messages: [ {role: system, content: 你是信息抽取助手只输出JSON不含其他内容。}, {role: user, content: 订单A10086的用户表示非常不满意要求退款。提取订单号和情绪。} ], format: json, stream: False } resp requests.post(url, jsonpayload).json() content resp[message][content] print(content)如果你是本地部署并且有一定开发能力我更推荐直接把模型接进 vLLM 这类高性能推理框架使用 guided_json 参数。vLLM 支持传入 JSON Schema生成的输出不仅合法还会在枚举值、字段结构上做严格约束。对稳定性的提升比 Post-processing 清洗要高一整个量级。3.3 兜底方案自己写一个 JSON 清洗与解析层即使有了上面的种种约束真实生产环境里仍然会有输出不合法的情况。我建议在所有接入大模型的项目里都预留一个 JSON 清洗与解析层看作最后的保险丝。下面是我常用的清洗函数逻辑不复杂但覆盖了大部分常见脏数据场景import json import re def extract_json_str(text: str) - str: # 去掉 Markdown 代码块标记 text re.sub(r^(?:json)?\s*|\s*$, , text.strip()) # 找到第一个 { 和最后一个 }截取中间部分 start text.find({) end text.rfind(}) if start -1 or end -1 or end start: raise ValueError(no json object found) return text[start:end1] def clean_json_value(value): if isinstance(value, str): # 处理模型输出的 None/True/False 大小写问题 if value.strip() None: return None if value.strip() True: return True if value.strip() False: return False return value def parse_model_json(text: str, defaultNone): try: cleaned extract_json_str(text) return json.loads(cleaned) except Exception as e: if default is not None: return default raise ValueError(fparse failed: {e}, raw: {text[:200]})这套代码的核心逻辑有两点把模型可能混入 Markdown 标记、解释性文字等隔离开再对最明显的“JSON 方言”None/True/False 首字母大小写做清洗。它解决不了所有问题但能让 90% 以上的脏输出起死回生。注意如果你已经在请求层做了约束解码这个清洗层的命中率会很低但它仍然值得保留——因为你会遇到“JSON 合法但业务字段非法”的情况这层逻辑可以进一步校验字段存在性也可以记录日志方便后续调优。4. 常见问题与排查技巧实录4.1 高频报错与含义速查项目做多了你会发现 JSON 相关的报错就那么几种。这里整理一个速查表基本都是我实际项目里踩过的。报错信息常见原因处理建议Expecting property name enclosed in double quotes字符串用了单引号或裸字段名用清洗层提取最外层 JSON 后重试或开启约束解码Expecting value: line 1 column 1 (char 0)拿到的是空字符串或非 JSON 文本检查是否被模型加了前缀/后缀解释Extra data: line 1 column ...多个 JSON 拼接在一起或尾部有剩余符号用 rfind 找到最后一个 } 截断Failed to deserialize the JSON body into the target type服务端强类型反序列化失败通常是字段类型不匹配在入参前做类型转换和字段校验避免直接传入反序列化层json.loads 报 string indices must be integers结果是 JSON 数组代码却按对象访问先打印样例输出确认结构是数组还是对象其中 Failed to deserialize the JSON body 这类错误经常出现在强类型语言比如 C#、Java里接口层收到的 body 是文本反序列化成目标 DTO 时类型对不上就会报这个错。解决问题的关键不是在反序列化层加异常处理而是确保模型端输出前就符合目标 DTO 的结构定义。最简单做法把目标 DTO 转成 JSON Schema喂给模型。4.2 字段缺失、类型不匹配与兜底策略结构化输出最容易被低估的问题是“字段缺失”。模型返回的 JSON 合法却少了一个必填字段。我用过的一个策略是“默认值兜底 必填校验”双轨并行。在解析层可以使用类似这样的逻辑def safe_extract(data: dict, field: str, defaultNone): value data.get(field, default) return value if value is not None else default必填字段用 if field not in data 或 data.get(field) is None 做显式校验校验失败时记录完整原始输出方便定位是 prompt 问题还是模型能力问题。千万不要在数据缺失时仍然静默通过否则下游会拿到大量空值问题更难排查。类型不匹配也有典型套路。比如要求 integer模型返回字符串 123。可以在清洗层做一次强制类型转换def coerce_int(value): try: return int(value) except (TypeError, ValueError): return 0这类转换逻辑很简单但能避免大量反序列化异常。需要注意的是强制转换时要能区分“空值默认”和“真实 0 值”否则业务统计会出错。4.3 中文转义、null 与数组嵌套的坑中文内容是国内大模型应用里绕不开的一环踩坑也最多。最典型的是 JSON 序列化时中文被转成 \uXXXX 还是直接输出 UTF-8 字符不同模型行为不一致。在 Python 里json.dumps(data, ensure_asciiFalse) 可以避免把中文变成 \u 转义序列Java 里用 Jackson 时如果对象属性名以大写字母开头默认序列化后可能变成小写开头这也是很多人常见的坑。此时最好在字段上用 JsonProperty(orderID) 显式指定或者配置 PropertyNamingStrategy不要依赖默认规则。数组嵌套的坑更隐蔽。模型返回 JSON 合法但内部数组里的某个元素不是对象而是字符串或者空数组变成 null这些都会导致下游遍历时报错。建议在解析后立即做一次结构校验工具函数比如 isinstance(items, list) and all(isinstance(i, dict) for i in items)把问题拦截在入口处。顺带说一句null 与缺失是两个语义。有些模型会把空字符串序列化成 null有些会省略字段两个都不算合规。你要在 schema 里明确写 type: [string, null] 或者设置默认值否则无法统一处理。4.4 输出内容被截断的应对办法还有一个实战里经常遇到但文档很少提的问题输出被截断。当 max_tokens 设置过小或模型生成长文本后 JSON 字段过长生成的 JSON 可能不完整最后连右花括号都没有。应对截断有三个手段。第一max_tokens 要留足余量比如预估 JSON 长度在 800 token 左右就设 1024 或更高给模型留点喘息空间。第二把 JSON 里的长文本字段限制长度比如 summary 长度控制在 50 字以内避免模型把一个字段写成长篇大论。第三解析层遇到“未闭合”的 JSON 时可以尝试用 json.JSONDecoder().raw_decode 或者自动补右括号但这招只能应急因为补出来的字段可能不完整准确度有限。最推荐的还是从源头控制减小 max output 之前先测量真实输出长度调大 max_tokens 之后还要同步调整超时时间和流式读取逻辑。5. 一些只有实操才能总结出的经验这部分没有严格的顺序想到哪写到哪但每一条都是真金白银换来的。5.1 系统提示词的“角色格式双保险”写法很多开发者在 system prompt 里只写“输出 JSON”效果不稳定。我习惯给模型设定一个明确角色再叠加格式约束形成双保险。你是一个严谨的信息抽取与数据格式化引擎。 你的唯一任务是从用户输入中抽取指定字段并严格按照 JSON 对象输出。 输出要求 1. 只输出 JSON 对象本身不要输出任何说明性文字、前后缀或 Markdown 代码块。 2. JSON 必须合法所有 key 使用双引号字符串值使用双引号。 3. 未识别到的字段填 null不要省略字段。 4. 输出格式参考 { order_id: string or null, sentiment: positive | neutral | negative, summary: string }为什么要“角色 格式”一起写因为模型对“系统角色”的遵从度往往高于对“一句话指令”的遵从度。给它一个明确的角色定位相当于把任务从“自由创作”切换成“工具执行”输出稳定性会明显提升。再加上格式示例等于给模型一张“答题卡”它会照着填。5.2 把 temperature 调到最低不一定够很多人一遇到输出不稳定第一反应是把 temperature 调到 0。这有一定效果但不够。temperature 只影响采样的随机性它管不住“模型想多写两句解释”的倾向。我的做法是“temperature 调低 输出长度约束 格式示例”三重配合。temperature 设为 0 或接近 0保证同一输入的输出尽量可复现输出长度约束用 max_tokens 控制防止模型长篇大论格式示例在提示词里放一个完整、合法的 JSON 输出样例让模型有样可依。这种组合拳比单调 temperature 效果稳定得多。另外如果你在 Java/C 这类强类型语言里接收 JSON建议在模型输出后先做 ObjectMapper 或 nlohmann::json 解析不要直接字符串拼接去访问字段。字符串拼接 下标访问遇到嵌套结构非常容易出错而且出错信息不友好。5.3 few-shot 示例远比规则描述有效我做过一个对比实验同一个信息抽取任务A 组 prompt 只写了“输出 JSON字段有 a/b/c”B 组 prompt 附带了一条输入输出的完整示例。结果 B 组的字段准确率高了十几个百分点漏字段的情况也明显减少。原因很好理解大模型本质上是在做“模式匹配和延续”给它的示例越具体它越容易模仿出你想要的结构。所以建议在每个需要稳定 JSON 输出的 prompt 里尽量塞 1~2 个 few-shot 示例而不是只写一堆抽象规则。示例中最好包含一个边界情况比如某个字段缺失时填 null防止模型自己发挥。5.4 跨语言调用时的互操作细节最后一个经验和团队协作有关。结构化输出往往不只是 Python 一个语言的事。模型端是 Python 生成的 JSON接收端可能是 Java、C、Go 或 SQLite。跨语言传输时要注意几个细节字段命名风格要统一Java 里用驼峰、Python 里用下划线如果不统一需要做映射层。日期时间统一用 ISO8601 字符串不要用时间戳否则跨时区会出问题。浮点数精度在 JSON 里没有类型区分传输到强类型语言时可能被转成 double要注意小数位数损失。如果你想在 C 里把 JSON 存进 SQLite建议用 nlohmann/json 库先解析成结构体再用 SQL 参数绑定写入不要直接拼 SQL 字符串也不要把 JSON 文本原样塞进 text 字段那样后续查询会很痛苦。这些细节看似琐碎但往往是线上系统出 bug 的真正源头。最后分享一点点个人体验做结构化输出这个方向我最大的感受是——别指望“一个参数”解决所有问题。那些宣称“加了 formatjson 就万事大吉”的说法多半是没跑过真实的高并发业务。真正稳的方案一定是“约束解码 校验兜底 数据监控”三件套。约束解码负责让模型输出合法 JSON校验兜底负责拦截业务级脏数据数据监控负责持续发现模型行为漂移。把这三层都做扎实你才敢把大模型输出直接喂给下游生产系统。