这次我们来看一个非常实际的问题大模型生成 JSON 格式内容时经常出现格式错误、解析失败甚至直接返回非 JSON 文本。这几乎是每个开发者调用大模型 API 时都会遇到的“拦路虎”。本文要介绍的就是一套能有效解决这个问题的核心思路与实用技巧。这个问题的核心在于大模型无论是 OpenAI GPT、Claude还是各类开源模型本质上是文本生成器它们并不“理解”JSON语法。当你的提示词Prompt要求它返回JSON时它只是在模仿JSON的格式。一旦遇到复杂结构、嵌套、或者模型“自由发挥”一下返回的内容就可能包含多余的解释、Markdown代码块标记、甚至格式错乱的文本导致下游程序无法直接解析。本文将重点拆解导致JSON格式错误的常见原因并提供从提示词工程、到后处理、再到使用专用工具库的一整套解决方案。无论你是进行本地大模型部署调试还是调用云端API进行应用开发这些方法都能帮你显著提升JSON输出的稳定性和可靠性。1. 核心能力速览解决JSON格式问题的工具箱在深入细节之前我们先快速浏览一下解决此问题的几种核心路径及其适用场景。能力项说明与工具适用阶段核心优势结构化提示词 (Prompt Engineering)在系统提示词中严格定义JSON Schema使用分隔符示例少样本Few-Shot请求前从源头引导模型成本最低适合简单结构输出格式强制 (Output Formatting)使用模型提供的特定参数如OpenAI的response_format或函数调用Function Calling请求时平台原生支持格式最规范但依赖模型能力后处理与修复 (Post-Processing)使用json5、demjson3等容错解析库或编写正则表达式提取JSON片段收到响应后兼容性最强可处理“脏”数据是最后的安全网专用解析库/工具使用instructor、marvin、pydantic-ai等库或自建校验层开发框架层开发体验好将格式问题抽象化适合生产环境大模型自愈 (Self-Correction)将格式错误的响应再次发给模型要求其修正错误发生后利用模型自身能力修正适合复杂错误对于本地部署的大模型如使用ollama、vLLM、text-generation-webui通常更依赖提示词工程和后处理。对于OpenAI等商用API则可以优先尝试输出格式强制和专用工具库。2. 问题根源与典型错误场景要解决问题先要理解问题是如何产生的。大模型返回JSON格式不正确通常源于以下几个场景附加解释文本模型在JSON对象前后添加了自然语言描述。好的这是您要的JSON数据 json {name: Alice, age: 30}希望这对您有帮助Markdown 代码块模型将JSON包裹在 json ... 标记中。格式错误缺少引号、括号不匹配、尾随逗号、使用了单引号而非双引号。{name: Alice, age: 30} // JSON标准要求双引号 {name: Alice, age: 30,} // 尾随逗号在某些解析器中会报错结构偏差返回的字段名或结构与预设的Schema不符例如多了字段、少了字段、或嵌套层级错误。完全非JSON响应当请求过于复杂或模型困惑时可能返回纯文本解释或完全无关的内容。理解这些场景有助于我们选择合适的工具进行针对性处理。3. 环境准备与前置条件本文的解决方案不依赖特定的大模型服务因此环境准备主要集中在Python开发环境上。你需要准备以下基础环境Python 环境推荐 Python 3.8 及以上版本。这是绝大多数相关库的支持基线。包管理工具pip或conda。网络访问如果你需要调用云端大模型API如OpenAI、Anthropic则需要确保能访问对应服务。本文所有操作均不涉及任何违规网络访问行为。文本编辑器或IDE如 VS Code, PyCharm 等。可选本地大模型环境如果你测试的是本地模型如通过ollama、LM Studio部署则需要确保模型服务已正常启动并能通过HTTP接口通常是http://localhost:11434等进行调用。我们将主要使用Python进行示例演示。首先创建一个干净的虚拟环境并安装核心库# 创建并激活虚拟环境 (可选但推荐) python -m venv venv # Windows: venv\Scripts\activate # Linux/Mac: source venv/bin/activate # 安装基础请求和JSON处理库 pip install requests json5 demjson3 # 如果你打算使用 instructor 等高级库 pip install instructor # 或者使用 pydantic-ai # pip install pydantic-ai4. 解决方案一强化提示词工程这是最直接、成本最低的方法旨在从请求源头减少错误。4.1 使用明确的指令和分隔符在你的系统提示词System Prompt或用户消息中清晰、强硬地指定输出格式。import openai # 或其他客户端 system_prompt 你是一个严格的JSON数据生成器。你必须只返回一个有效的JSON对象不要有任何额外的解释、注释、Markdown代码块标记或前言后语。 用户会描述他们需要的数据结构你直接生成对应的JSON。 输出示例 {users: [{name: John, id: 1}]} user_prompt 请生成一个包含3个用户信息的列表每个用户有name和id字段。 # 假设使用OpenAI客户端 response openai.chat.completions.create( modelgpt-3.5-turbo, messages[ {role: system, content: system_prompt}, {role: user, content: user_prompt} ], temperature0.1 # 降低随机性使输出更稳定 ) raw_output response.choices[0].message.content print(原始输出:, raw_output)关键点“只返回一个有效的JSON对象”明确指令。“不要有任何额外的...”排除常见干扰项。提供输出示例让模型直观看到你期望的格式。降低temperature减少模型的随机性使其更倾向于遵循指令。4.2 提供JSON Schema作为少样本Few-Shot对于复杂结构在提示词中直接给出一个完整的、符合你要求的JSON例子效果极佳。user_prompt_with_example 请根据以下示例的格式生成一份新的书店库存数据。 示例JSON格式 { store: { name: 经典书店, books: [ { title: 深入浅出Python, author: 某作者, price: 59.9, in_stock: true } ] } } 请生成一个包含2本书的新数据书店名改为“未来科技书店”。 这种方法相当于给模型一个“模板”它模仿的准确率会大大提高。5. 解决方案二利用平台原生格式强制功能部分大模型API提供了原生支持能强制输出JSON格式。5.1 OpenAI API 的response_formatOpenAI在部分模型如gpt-4-turbo-preview,gpt-3.5-turbo-1106及更新版本中支持response_format参数。import openai from openai import OpenAI client OpenAI(api_keyyour-api-key) response client.chat.completions.create( modelgpt-3.5-turbo-1106, messages[ {role: user, content: 列出太阳系的三颗行星包含名称和直径。} ], response_format{type: json_object}, # 关键参数 temperature0, ) json_output response.choices[0].message.content print(json_output) # 预期输出将是一个纯粹的JSON对象例如{planets: [{name: 地球, diameter_km: 12742}, ...]}注意当使用response_format: { “type”: “json_object” }时OpenAI官方建议系统或用户消息中必须明确提示模型输出JSON否则模型可能会报错。这是目前最可靠的官方方案。5.2 函数调用Function Calling函数调用本意是让模型选择工具但其返回结果本身就是严格符合预定JSON Schema的arguments。我们可以“借用”这个机制来获取结构化数据。import json import openai from openai import OpenAI client OpenAI(api_keyyour-api-key) response client.chat.completions.create( modelgpt-3.5-turbo, messages[ {role: user, content: 上海和北京今天的天气怎么样} ], tools[{ type: function, function: { name: get_weather, description: 获取城市天气信息, parameters: { type: object, properties: { city: { type: string, description: 城市名称 }, temperature: { type: integer, description: 温度单位摄氏度 }, condition: { type: string, description: 天气状况如晴朗、多云、雨 } }, required: [city, temperature, condition] } } }], tool_choiceauto, ) # 解析返回的工具调用 tool_calls response.choices[0].message.tool_calls if tool_calls: for tool_call in tool_calls: if tool_call.function.name get_weather: arguments json.loads(tool_call.function.arguments) print(解析成功的JSON:, arguments)这种方式获得的JSON质量极高但逻辑上绕了个弯且消耗的Token可能更多。6. 解决方案三后处理与容错解析当模型返回的文本“不太干净”时一个健壮的后处理流程是必不可少的。这是本地部署模型场景下的主要手段。6.1 使用json5或demjson3库标准库json.loads()非常严格。json5和demjson3则能解析更“宽松”的JSON例如允许尾随逗号、注释、单引号等。import json import json5 import demjson3 dirty_json_string // 这是一个用户列表 { users: [ {name: Alice, age: 30, }, {name: Bob, age: 25}, // 注意这里的尾随逗号 ] } # 1. 使用标准库 - 会失败 try: data json.loads(dirty_json_string) print(标准库解析成功:, data) except json.JSONDecodeError as e: print(f标准库解析失败: {e}) # 2. 使用 json5 - 可能成功 try: data json5.loads(dirty_json_string) print(json5 解析成功:, data) except Exception as e: print(fjson5 解析失败: {e}) # 3. 使用 demjson3 - 可能成功 try: data demjson3.decode(dirty_json_string) print(demjson3 解析成功:, data) except demjson3.JSONDecodeError as e: print(fdemjson3 解析失败: {e})6.2 使用正则表达式提取JSON片段当响应文本中混杂着自然语言和JSON时可以用正则表达式尝试“挖出”JSON部分。import re import json raw_response 好的根据您的查询数据如下 json { status: success, data: [{id: 1, value: foo}] }您还可以进一步查询。 尝试匹配被json ...包裹的内容pattern r(?:json)?\s*([\s\S]*?)\s* matches re.findall(pattern, raw_response, re.IGNORECASE)extracted_json None for match in matches: cleaned match.strip() if cleaned.startswith({) or cleaned.startswith([): try: extracted_json json.loads(cleaned) print(从代码块中提取并解析成功:, extracted_json) break except json.JSONDecodeError: continue如果没有代码块尝试直接找最长的 {...} 或 [...]if not extracted_json: pattern_direct r({[\s\S]?}|[[\s\S]?]) matches re.findall(pattern_direct, raw_response) for match in matches: try: extracted_json json.loads(match) print(直接提取JSON对象成功:, extracted_json) break except json.JSONDecodeError: continueif not extracted_json: print(未能从响应中提取有效JSON。)**后处理流程建议** 1. 首先尝试标准 json.loads() 解析原始响应。 2. 如果失败尝试用正则提取可能的JSON片段再交给 json.loads()。 3. 如果还失败尝试使用 json5 或 demjson3 解析原始响应或提取后的片段。 4. 作为最后手段可以将错误响应和解析错误信息记录下来用于后续分析或重试。 ## 7. 解决方案四使用专用库如 instructor instructor 库通过“修补”OpenAI客户端将输出结构化到Pydantic模型中内部自动处理了提示词构造、响应解析和重试极大简化了开发。 python import instructor from openai import OpenAI from pydantic import BaseModel from typing import List # 修补客户端 client instructor.patch(OpenAI(api_keyyour-api-key)) # 定义你期望的数据结构 class User(BaseModel): name: str age: int email: str class UserList(BaseModel): users: List[User] # 直接调用获取结构化对象 user_list: UserList client.chat.completions.create( modelgpt-3.5-turbo, response_modelUserList, # 指定响应模型 messages[ {role: user, content: 生成三个虚拟用户信息包含姓名、年龄和邮箱。} ], ) print(user_list.model_dump_json(indent2)) # 输出将是完美的JSON字符串并且user_list是一个可操作的Pydantic对象 for user in user_list.users: print(fName: {user.name}, Age: {user.age}) # instructor 也支持异步和重试 # user_list await client.chat.completions.create(...)instructor在后台做了大量工作它修改了提示词以要求JSON解析响应如果解析失败还会自动尝试重试可配置次数。对于生产环境这是非常推荐的方式。8. 解决方案五大模型自愈Self-Correction如果上述方法都失效或者你拿到了一段格式错误但又包含所需信息的文本可以尝试让大模型自己修复它。def self_correct_json(bad_json_string: str, model_client) - str: 请求大模型修正格式错误的JSON字符串。 correction_prompt f 以下是一段意图是JSON但格式不正确的文本。请只返回修正后的、有效的、标准的JSON字符串不要有任何其他内容。 错误文本 {bad_json_string} # 这里需要你根据使用的客户端openai, ollama等发送请求 # 伪代码 # corrected_response model_client.chat(... messages[{role: user, content: correction_prompt}], temperature0) # return corrected_response.choices[0].message.content return corrected_json_string # 使用示例 bad_text { name: Alice, age: thirty } # corrected self_correct_json(bad_text, openai_client) # print(corrected) # 期望输出: {name: Alice, age: 30}这种方法会额外消耗一次API调用成本较高但作为错误处理流程中的一环有时是值得的。9. 资源占用与性能观察处理JSON格式问题本身计算开销极低主要资源消耗在于大模型推理。Token消耗使用详细的提示词如包含完整Schema示例会增加输入Token从而增加成本和延迟。需要在格式准确性和效率间权衡。延迟后处理正则、容错解析的耗时通常可忽略不计。但“自愈”方案会引入额外的一轮模型调用延迟翻倍。内存/CPUjson,json5,re等库的处理开销对于常规应用微乎其微。最佳实践在本地测试时先用简单的请求和小模型如Qwen2.5-1.5B验证你的提示词和后处理管道是否工作再切换到更大的生产模型可以节省成本。10. 常见问题与排查方法问题现象可能原因排查方式解决方案json.decoder.JSONDecodeError响应包含非JSON文本、格式错误。1. 打印原始响应response.choices[0].message.content。2. 检查是否有Markdown标记、额外说明。1. 强化提示词。2. 使用后处理提取JSON片段。3. 使用json5容错解析。字段缺失或多余模型未遵循Schema。比较返回的JSON与期望的Schema结构。1. 在提示词中提供更清晰的示例。2. 使用instructor等库其内置重试机制。3. 在后处理中设置默认值或过滤未知字段。返回纯文本无JSON提示词指令不够强或任务过于复杂模型无法结构化。检查系统提示词和用户消息。1. 在系统提示词中强调“只输出JSON”。2. 使用OpenAI的response_format参数。3. 改用函数调用Function Calling方式。嵌套结构混乱复杂嵌套导致模型混淆。简化数据结构或提供更详细的少样本示例。1. 将复杂对象拆分为多个简单请求。2. 使用instructor分步提取Multi-Task。本地模型效果差小模型遵循指令和格式能力较弱。尝试不同的提示词模板如Alpaca,ChatML格式。1. 考虑使用专门微调过格式遵循的模型。2. 加强后处理逻辑。API返回非200状态码网络、鉴权、模型不存在等问题。检查API密钥、端点URL、模型名称是否正确。根据错误信息排查与JSON格式无关。11. 最佳实践与使用建议分层防御不要只依赖一种方法。采用“提示词引导 平台强制如有 健壮后处理”的组合策略。设置重试与降级在代码中如果JSON解析失败可以自动重试请求可能附带更严格的提示词或者降级为使用正则提取关键信息。日志记录始终记录模型返回的原始响应和解析错误。这些日志是优化提示词和排查问题的宝贵资料。测试驱动为你的大模型调用函数编写单元测试模拟各种格式错误的返回确保你的后处理管道能正确处理它们。合规与授权确保你请求模型生成的数据内容不涉及侵权、隐私泄露或生成非法信息。对于生成模拟数据这是安全的对于处理真实数据需注意合规性。成本意识复杂的提示词和“自愈”重试都会增加Token消耗。在批处理任务中需评估其对总体成本和速度的影响。12. 总结与下一步解决大模型返回JSON格式不正确的问题核心思路是“引导 强制 清洗”。对于绝大多数应用场景结合强提示词与后处理容错解析json5/正则已经能解决90%的问题。如果使用OpenAI等高级API原生response_format参数和instructor这类库能提供近乎完美的体验。建议你按以下步骤实践首先检查你使用的API是否支持response_format如OpenAI这是最省力的方案。其次优化你的系统提示词加入严格的输出格式指令和少样本示例。然后在你的代码中用try-except包裹json.loads()并在except块中实现后处理逻辑正则提取 -json5解析。对于生产项目强烈考虑采用instructor或类似框架将格式问题从业务逻辑中完全抽象出去。把这个流程固化下来以后无论调用哪个模型、进行何种复杂的数据抽取你都能获得稳定可解析的结构化输出从而让大模型真正成为你应用中可靠的数据生成组件。