这次我们来看一个非常实际的问题：大模型生成 JSON 格式内容时，经常出现格式错误、解析失败，甚至直接返回非 JSON 文本。这几乎是每个开发者调用大模型 API 时都会遇到的“拦路虎”。本文要介绍的，就是一套能有效解决这个问题的核心思路与实用技巧。

这个问题的核心在于，大模型（无论是 OpenAI GPT、Claude，还是各类开源模型）本质上是文本生成器，它们并不“理解”JSON语法。当你的提示词（Prompt）要求它返回JSON时，它只是在模仿JSON的格式。一旦遇到复杂结构、嵌套、或者模型“自由发挥”一下，返回的内容就可能包含多余的解释、Markdown代码块标记、甚至格式错乱的文本，导致下游程序无法直接解析。

本文将重点拆解导致JSON格式错误的常见原因，并提供从提示词工程、到后处理、再到使用专用工具库的一整套解决方案。无论你是进行本地大模型部署调试，还是调用云端API进行应用开发，这些方法都能帮你显著提升JSON输出的稳定性和可靠性。

1. 核心能力速览：解决JSON格式问题的工具箱

在深入细节之前，我们先快速浏览一下解决此问题的几种核心路径及其适用场景。

对于本地部署的大模型（如使用ollama、vLLM、text-generation-webui），通常更依赖提示词工程和后处理。对于OpenAI等商用API，则可以优先尝试输出格式强制和专用工具库。

2. 问题根源与典型错误场景

要解决问题，先要理解问题是如何产生的。大模型返回JSON格式不正确，通常源于以下几个场景：

1. 附加解释文本：模型在JSON对象前后添加了自然语言描述。

   好的，这是您要的JSON数据： ```json {"name": "Alice", "age": 30}

   希望这对您有帮助！

2. Markdown 代码块：模型将JSON包裹在 ```json ... ``` 标记中。
3. 格式错误：缺少引号、括号不匹配、尾随逗号、使用了单引号而非双引号。

   {'name': 'Alice', 'age': 30} // JSON标准要求双引号 {"name": "Alice", "age": 30,} // 尾随逗号在某些解析器中会报错

4. 结构偏差：返回的字段名或结构与预设的Schema不符，例如多了字段、少了字段、或嵌套层级错误。
5. 完全非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-ai

4. 解决方案一：强化提示词工程

这是最直接、成本最低的方法，旨在从请求源头减少错误。

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( model="gpt-3.5-turbo", messages=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt} ], temperature=0.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_format

OpenAI在部分模型（如gpt-4-turbo-preview,gpt-3.5-turbo-1106及更新版本）中支持response_format参数。

import openai from openai import OpenAI client = OpenAI(api_key="your-api-key") response = client.chat.completions.create( model="gpt-3.5-turbo-1106", messages=[ {"role": "user", "content": "列出太阳系的三颗行星，包含名称和直径。"} ], response_format={"type": "json_object"}, # 关键参数 temperature=0, ) 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_key="your-api-key") response = client.chat.completions.create( model="gpt-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_choice="auto", ) # 解析返回的工具调用 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(f"json5 解析失败: {e}") # 3. 使用 demjson3 - 可能成功 try: data = demjson3.decode(dirty_json_string) print("demjson3 解析成功:", data) except demjson3.JSONDecodeError as e: print(f"demjson3 解析失败: {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: continue

if 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_key="your-api-key")) # 定义你期望的数据结构 class User(BaseModel): name: str age: int email: str class UserList(BaseModel): users: List[User] # 直接调用，获取结构化对象 user_list: UserList = client.chat.completions.create( model="gpt-3.5-turbo", response_model=UserList, # 指定响应模型 messages=[ {"role": "user", "content": "生成三个虚拟用户信息，包含姓名、年龄和邮箱。"} ], ) print(user_list.model_dump_json(indent=2)) # 输出将是完美的JSON字符串，并且user_list是一个可操作的Pydantic对象 for user in user_list.users: print(f"Name: {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}], temperature=0) # 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，从而增加成本和延迟。需要在格式准确性和效率间权衡。
• 延迟：后处理（正则、容错解析）的耗时通常可忽略不计。但“自愈”方案会引入额外的一轮模型调用，延迟翻倍。
• 内存/CPU：json,json5,re等库的处理开销对于常规应用微乎其微。
• 最佳实践：在本地测试时，先用简单的请求和小模型（如Qwen2.5-1.5B）验证你的提示词和后处理管道是否工作，再切换到更大的生产模型，可以节省成本。

10. 常见问题与排查方法

11. 最佳实践与使用建议

1. 分层防御：不要只依赖一种方法。采用“提示词引导 + 平台强制（如有）+ 健壮后处理”的组合策略。
2. 设置重试与降级：在代码中，如果JSON解析失败，可以自动重试请求（可能附带更严格的提示词），或者降级为使用正则提取关键信息。
3. 日志记录：始终记录模型返回的原始响应和解析错误。这些日志是优化提示词和排查问题的宝贵资料。
4. 测试驱动：为你的大模型调用函数编写单元测试，模拟各种格式错误的返回，确保你的后处理管道能正确处理它们。
5. 合规与授权：确保你请求模型生成的数据内容不涉及侵权、隐私泄露或生成非法信息。对于生成模拟数据，这是安全的；对于处理真实数据，需注意合规性。
6. 成本意识：复杂的提示词和“自愈”重试都会增加Token消耗。在批处理任务中，需评估其对总体成本和速度的影响。

12. 总结与下一步

解决大模型返回JSON格式不正确的问题，核心思路是“引导 + 强制 + 清洗”。对于绝大多数应用场景，结合强提示词与后处理容错解析（json5/正则）已经能解决90%的问题。如果使用OpenAI等高级API，原生response_format参数和instructor这类库能提供近乎完美的体验。

建议你按以下步骤实践：

1. 首先，检查你使用的API是否支持response_format（如OpenAI），这是最省力的方案。
2. 其次，优化你的系统提示词，加入严格的输出格式指令和少样本示例。
3. 然后，在你的代码中，用try-except包裹json.loads()，并在except块中实现后处理逻辑（正则提取 ->json5解析）。
4. 对于生产项目，强烈考虑采用instructor或类似框架，将格式问题从业务逻辑中完全抽象出去。

把这个流程固化下来，以后无论调用哪个模型、进行何种复杂的数据抽取，你都能获得稳定可解析的结构化输出，从而让大模型真正成为你应用中可靠的数据生成组件。