大语言模型API返回JSON解析全攻略：从防御性解析到Prompt工程

1. 项目概述：当AI的“智能”遇上JSON的“固执”

最近在对接各种大语言模型（LLM）的API时，你是不是也经常被返回的“JSON”数据搞得焦头烂额？满怀信心地写下response.json()或者json.loads(response_text)，结果迎头就是一个JSONDecodeError。这感觉就像你满怀期待地打开一个包装精美的礼物，结果发现里面是一团乱麻的毛线。问题不在于你，而在于AI模型——它们有时并不那么“听话”。这个项目，就是一次对AI返回的非标准JSON数据的“排雷”行动。我们将深入那些看似是JSON，实则暗藏玄机的响应体，从原理到实践，手把手教你构建一个健壮的解析流程，让你不再被这些“坑”绊倒。

无论是调用OpenAI的Chat Completions、Claude的Messages，还是国内诸多大厂的模型服务，只要你期望得到一个结构化的JSON输出，就一定会遇到格式问题。模型可能会在JSON对象外包裹多余的文本说明，可能忘记闭合引号或括号，甚至可能因为思维链（Chain-of-Thought）而在JSON中插入自然语言解释。直接使用标准库json.loads就像用一把精密的尺子去丈量一片毛边纸，注定会失败。我们需要的是更灵活、更智能的“剪刀”和“胶水”。

2. 核心问题拆解：AI返回的JSON到底“坑”在哪？

2.1 坑位一：非JSON前缀与后缀（包裹文本）

这是最常见的问题。你要求模型“以JSON格式返回用户信息”，它可能真的会“理解”成：“好的，我将以JSON格式返回。以下是用户信息：{“name”: “张三”}”。看，JSON前面多了一句自然语言。更复杂的情况是，模型会在JSON前后都加上解释性文字，比如“根据您的要求，生成如下JSON数据：”和“以上是查询结果。”。标准json.loads要求字符串必须且只能是一个完整的JSON值，这些多余字符会直接导致解析失败。

为什么会出现这种情况？这源于大语言模型基于概率生成的本质。它的训练数据包含了海量的对话、文档和代码，其中“先说明后给数据”的模式非常普遍。当你的指令（Prompt）不够强硬或清晰时，模型会倾向于模仿这种更“人性化”、更“安全”（避免直接输出裸数据）的回应方式。

2.2 坑位二：JSON内的非法注释与自然语言

你以为进入{}或[]内部就安全了？太天真了。模型有时会在JSON的键值对之间插入类似注释的内容。例如：{“name”: “张三”， /* 这是一个用户名 */ “age”: 25}。标准的JSON规范（RFC 8259）是不支持/* */或//这种注释的。此外，在数组或对象中突然插入一句自然语言描述也时有发生，尤其是在生成列表或复杂对象时，模型可能会“自言自语”地解释它正在做什么。

2.3 坑位三：不标准的字符串引号与编码

JSON标准要求字符串必须使用双引号(””)。但AI模型在生成过程中，可能会“偷懒”或受到训练数据中其他语言（如Python字典）的影响，使用单引号(’’)。例如生成{‘name’: ‘张三’}。虽然这在JavaScript或Python中可能被宽容处理，但严格的json.loads会直接报错。此外，未转义的控制字符、不正确的Unicode编码也可能导致问题。

2.4 坑位四：结构不完整或格式错误

这是最棘手的一类问题。模型可能在生成过程中被token长度限制截断，导致JSON缺少闭合的}或]。也可能在生成嵌套结构时出现括号不匹配。另一种常见错误是键名没有用引号括起来（即生成了JavaScript对象字面量，而非严格JSON），例如{name: “张三”}。这些都属于语法层面的错误，修复起来需要一定的策略。

2.5 坑位五：Markdown代码块包裹

许多开发者会在Prompt中要求“将JSON放在代码块中”，模型通常会照做，返回如下内容：

{ “name”: “张三” }

此时，整个响应文本包含了 ```json 和 ``` 这样的标记。你需要先剥离这些Markdown标记，才能得到纯净的JSON字符串。

3. 防御性解析策略：从正则到AI的层层过滤

面对这些坑，我们不能指望模型100%合规，必须建立自己的防御工事。一个健壮的解析器应该是多层的，从简单到复杂，逐步尝试和清理。

3.1 第一层：文本预处理与清洗

在尝试解析之前，先对原始文本进行清理。这能解决大部分“包裹文本”和“Markdown代码块”问题。

核心策略：使用正则表达式提取最像JSON的部分。我们不是简单地匹配第一个{和最后一个}，因为JSON可能是一个数组[]，也可能嵌套很深。一个更稳健的思路是：寻找一个可能JSON片段的起始（{或[），然后尝试找到与之匹配的结束符。

import re import json def extract_json_string(text): """ 尝试从可能包含额外文本的字符串中提取JSON部分。 策略：找到第一个‘{’或‘[’，然后逐步向右扫描，找到匹配的结束符。 """ text = text.strip() # 模式1：尝试匹配被 ```json ... ``` 包裹的代码块 code_block_pattern = r'```(?:json)?\s*([\s\S]*?)\s*```' match = re.search(code_block_pattern, text, re.IGNORECASE) if match: candidate = match.group(1).strip() # 如果代码块内成功提取，则以此为准 if candidate.startswith(('{', '[')): return candidate # 模式2：没有代码块，或代码块内不是JSON，则在整个文本中寻找JSON-like结构 # 这是一个简化的、非完全严谨的栈匹配方法，用于演示 # 在实际生产中，可以结合多次json.loads尝试 for start_char, end_char in [('{', '}'), ('[', ']')]: start_pos = text.find(start_char) if start_pos != -1: # 简易栈，用于匹配括号 stack = [] for i in range(start_pos, len(text)): char = text[i] if char == start_char: stack.append(char) elif char == end_char: if stack: stack.pop() if not stack: # 栈空，意味着找到了匹配的结束位置 candidate = text[start_pos:i+1] # 快速验证：能否被json.loads解析（允许前后有空白） try: json.loads(candidate) return candidate except json.JSONDecodeError: # 如果失败，继续寻找下一个可能的开始 continue # 如果循环结束栈不为空，说明不完整，这个开始位置无效，继续外层循环找下一个开始 # 如果以上都没找到，返回None或原始文本（根据策略） return None

注意：上述栈匹配方法是一个简化示例，对于极其复杂或严重损坏的JSON可能不准。在实际应用中，可以结合“多次尝试+容错解析库”的策略。

3.2 第二层：容错解析与语法修复

当预处理提取出疑似JSON的字符串后，如果标准解析仍然失败，我们需要进行语法修复。

3.2.1 处理单引号将字符串外部的单引号替换为双引号，同时注意不要替换字符串内部转义的单引号（这很复杂）。一个相对安全的启发式方法是：使用正则表达式只匹配键名和字符串值位置的单引号。

import re def fix_single_quotes(json_str): """ 尝试将JSON字符串外部的单引号替换为双引号。 这是一个启发式方法，并非100%可靠，但对于简单情况有效。 """ # 匹配不在转义字符后的单引号（简易版） # 这个正则并不完美，但对于模型生成的、格式相对规整的JSON通常够用 pattern = r"(?<!\\)'" # 更安全的做法是写一个简单的状态机来遍历字符串，区分在字符串内还是外。 # 这里提供一个更稳健版本的思路： fixed = [] in_string = False escaped = False for char in json_str: if not in_string: if char == "'": # 在字符串外部遇到单引号，视为字符串开始，改为双引号 fixed.append('"') in_string = True else: fixed.append(char) if char == '"': # 遇到标准双引号，进入字符串状态 in_string = True else: # 在字符串内部 if escaped: # 当前字符是转义后的，原样输出，重置escaped状态 fixed.append(char) escaped = False else: if char == '\\': escaped = True fixed.append(char) elif char == '"' or char == "'": # 字符串结束（遇到匹配的引号） fixed.append(char) in_string = False else: fixed.append(char) return ''.join(fixed)

3.2.2 处理未转义控制字符与尾随逗号模型有时会在字符串值里插入换行符\n或制表符\t而未转义。我们可以尝试转义它们。另外，JSON不允许在对象或数组最后一个元素后出现逗号，但模型常会加上。

def fix_trailing_commas(json_str): """移除对象和数组末尾的尾随逗号。""" # 移除对象 { ... , } 中的尾随逗号 json_str = re.sub(r',\s*}', '}', json_str) # 移除数组 [ ... , ] 中的尾随逗号 json_str = re.sub(r',\s*]', ']', json_str) return json_str def escape_control_chars_in_strings(json_str): """ 尝试转义字符串内部未转义的控制字符（如换行、制表符）。 注意：此操作风险较高，可能误伤。最好在明确知道模型可能生成此类错误时使用。 """ # 这是一个非常激进且可能破坏数据的修复，慎用！ # 理想情况下，应该在解析失败后，定位到出错位置再进行针对性修复。 # 这里仅作示例，将未转义的 \n, \t, \r 替换为转义形式。 # 但如何精准定位“字符串内部”是一个复杂问题。 # 更推荐使用如 `demjson3` 或 `json5` 这类容错解析器。 pass

3.3 第三层：使用容错JSON解析库

当自己的修复逻辑不够用时，可以借助更强大的第三方库。这些库实现了对JSON超集或常见错误的宽容解析。

• json5: 支持JSON5规范，允许注释、尾随逗号、单引号等。对于模型生成的类JSON数据非常友好。

  pip install json5

  import json5 try: data = json5.loads(dirty_json_str) except Exception as e: # 即使json5也可能失败 pass

• demjson3(或demjson): 一个历史悠久的容错JSON解析器，能处理许多不严格的格式。

  pip install demjson3

  import demjson3 # demjson.decode 会尝试修复错误 data = demjson3.decode(dirty_json_str, strict=False)

实操心得：优先考虑json5，因为它遵循一个明确的规范（JSON5），社区支持较好，且通常能解决注释、尾随逗号、单引号等大部分“软错误”。demjson3的修复能力更强，但可能更激进，在极端情况下可能导致意想不到的解析结果。建议将标准库json.loads作为第一选择，失败后降级到json5.loads，最后再尝试demjson3.decode。

3.4 第四层：终极武器——请AI自己修复

如果以上所有自动方法都失败了，我们还有一个“降维打击”的手段：把解析失败的字符串和错误信息，再塞回给另一个AI调用（或者同一个模型，但使用更明确的指令），让它自己修复成合法的JSON。这听起来像递归，但在实践中非常有效。

核心思路：构造一个系统Prompt，要求模型扮演一个“JSON修复专家”。

import openai # 或其他LLM SDK def ai_repair_json(broken_json_str, original_error, model="gpt-3.5-turbo"): """ 使用LLM修复损坏的JSON字符串。 """ repair_prompt = f""" 你是一个JSON格式修复专家。以下是一个尝试解析时出错的JSON字符串，以及解析错误信息。 你的任务是将它修复成一个完全符合标准RFC 8259 JSON规范的、可被`json.loads`解析的字符串。 只输出修复后的JSON字符串，不要有任何额外的解释、注释或Markdown包装。 损坏的JSON字符串： ``` {broken_json_str} ``` 解析错误： ``` {original_error} ``` 修复后的标准JSON： """ # 调用LLM API response = openai.ChatCompletion.create( model=model, messages=[ {"role": "system", "content": "你是一个只输出标准JSON的修复工具。"}, {"role": "user", "content": repair_prompt} ], temperature=0.1, # 低温度，确保输出稳定 max_tokens=2000 ) repaired = response.choices[0].message.content.strip() # 清理可能的Markdown代码块包装（再次） repaired = re.sub(r'^```(?:json)?\s*|\s*```$', '', repaired, flags=re.MULTILINE) return repaired

注意事项：这个方法会产生额外的API调用成本和延迟，应作为最后的手段。同时，要小心避免无限递归（修复后的JSON可能仍然错误）。可以设置最大重试次数（例如2次）。

4. 构建健壮的AI JSON解析管道

将上述策略组合起来，形成一个完整的、有弹性的解析管道。这个管道应该从最廉价、最快的方法开始尝试，逐步升级到成本更高、更复杂的方法。

4.1 管道设计流程图（文字描述）

1. 输入：原始API响应文本。
2. 步骤1：预处理与提取：使用extract_json_string函数，尝试剥离Markdown代码块和周围文本，提取核心JSON候选字符串。如果提取物为None，跳至步骤5（终极修复）。
3. 步骤2：标准解析尝试：对候选字符串直接使用json.loads。成功则返回数据，流程结束。
4. 步骤3：轻度修复后重试：如果标准解析失败，记录错误信息e1。依次进行：
   • a. 应用fix_single_quotes。
   • b. 应用fix_trailing_commas。
   • 对修复后的字符串再次尝试json.loads。成功则返回。
5. 步骤4：容错库解析：如果轻度修复后仍失败，记录错误信息e2。依次尝试：
   • a. 使用json5.loads。
   • b. 如果失败，使用demjson3.decode(strict=False)。
   • 成功则返回。
6. 步骤5：AI辅助修复：如果以上所有方法均失败，将原始响应文本或最后修复的候选字符串与最后的错误信息e2一起，传递给ai_repair_json函数。对修复后的结果，从步骤2开始重新执行整个管道（因为AI修复后可能仍不完美，需要标准流程验证）。为避免死循环，设置最大AI修复次数（如1-2次）。
7. 步骤6：最终失败处理：如果所有尝试都失败，抛出包含所有阶段错误信息的自定义异常，或返回一个包含原始文本的错误结果，供人工检查。

4.2 代码实现示例

import json import json5 import demjson3 import re import logging from typing import Any, Optional, Tuple logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) class RobustAIJSONParser: def __init__(self, max_ai_repair_attempts: int = 1): self.max_ai_repair_attempts = max_ai_repair_attempts self.ai_repair_attempts = 0 def parse(self, raw_text: str) -> Tuple[bool, Any, Optional[str]]: """ 核心解析方法。 返回: (success, data_or_error, final_used_method) """ # 步骤1: 预处理提取 candidate = self._extract_json_candidate(raw_text) if candidate is None: candidate = raw_text # 如果没有提取到，使用原始文本 logger.warning("无法提取出明确的JSON候选片段，将使用原始文本尝试解析。") # 首先尝试标准解析（可能已经是干净的JSON） success, data = self._try_standard_json(candidate) if success: return True, data, "standard_json" # 步骤3 & 4: 渐进式修复与容错解析 repair_functions = [ ("fix_single_quotes", self._fix_single_quotes), ("fix_trailing_commas", self._fix_trailing_commas), ] for fix_name, fix_func in repair_functions: repaired = fix_func(candidate) success, data = self._try_standard_json(repaired) if success: logger.info(f"通过 {fix_name} 修复后解析成功。") return True, data, f"standard_json after {fix_name}" # 尝试容错库 success, data, lib_name = self._try_tolerant_libs(candidate) if success: return True, data, lib_name # 步骤5: AI修复 (如果配置了且未超限) if self.max_ai_repair_attempts > 0 and self.ai_repair_attempts < self.max_ai_repair_attempts: logger.warning("所有自动方法失败，尝试AI修复...") # 这里需要接入LLM API，我们模拟一个接口 # repaired_text = self._call_ai_repair(candidate, last_error) # self.ai_repair_attempts += 1 # 递归调用parse，但传入修复后的文本，并避免无限递归 # 在实际实现中，需要小心设计递归终止条件。 # 为简化示例，我们跳过具体AI调用，仅示意流程。 # success, data, method = self.parse(repaired_text) # if success: # return True, data, f"ai_repaired_then_{method}" pass # 步骤6: 最终失败 error_msg = f"所有解析尝试均失败。最后处理的文本片段：{candidate[:200]}..." logger.error(error_msg) return False, error_msg, None def _extract_json_candidate(self, text: str) -> Optional[str]: """实现之前的extract_json_string逻辑""" # ... (省略具体实现，见前文) pass def _try_standard_json(self, s: str) -> Tuple[bool, Any]: try: data = json.loads(s) return True, data except json.JSONDecodeError as e: return False, str(e) def _fix_single_quotes(self, s: str) -> str: """实现之前的fix_single_quotes逻辑（建议使用更稳健的状态机版本）""" # ... (省略具体实现) return s def _fix_trailing_commas(self, s: str) -> str: """实现之前的fix_trailing_commas逻辑""" # ... (省略具体实现) return s def _try_tolerant_libs(self, s: str) -> Tuple[bool, Any, str]: """尝试json5和demjson3""" # 尝试 json5 try: data = json5.loads(s) return True, data, "json5" except Exception as e1: logger.debug(f"json5 解析失败: {e1}") # 尝试 demjson3 try: data = demjson3.decode(s, strict=False) return True, data, "demjson3" except Exception as e2: logger.debug(f"demjson3 解析失败: {e2}") return False, None, "" # 使用示例 parser = RobustAIJSONParser(max_ai_repair_attempts=0) # 暂时关闭AI修复 raw_text_from_ai = """ 用户您好，这是您请求的数据： ```json { 'name': '李四', 'age': 30, 'hobbies': ['阅读', '游泳', '音乐'], }

希望这对您有帮助！ """

success, data, method = parser.parse(raw_text_from_ai) if success: print(f"解析成功！方法：{method}, 数据：{data}") else: print(f"解析失败。错误：{data}")

## 5. 预防优于治疗：在Prompt工程中规避问题 虽然有了强大的解析器，但最好的错误是那些从不发生的错误。通过精心设计Prompt，可以极大减少模型返回非标准JSON的概率。 ### 5.1 明确输出格式指令 * **强约束**：在系统指令或用户消息中明确要求输出格式。 * **好**：“请严格输出一个JSON对象，不要有任何额外的解释、前缀或后缀。JSON必须符合RFC 8259标准，使用双引号，无注释。” * **更好**：提供JSON Schema。 ``` 请根据以下JSON Schema定义输出数据： { "type": "object", "properties": { "name": {"type": "string"}, "age": {"type": "integer"} }, "required": ["name", "age"] } 只输出JSON，不要输出其他任何内容。 ``` * **使用分隔符**：要求模型将JSON放在特定的标记之间，便于后续提取。 * “将你的回答用三个反引号包裹起来，例如：```json {...}```” ### 5.2 提供少样本示例（Few-Shot Prompting） 在Prompt中给出1-2个清晰的输入输出示例，让模型模仿。

示例： 用户：请以JSON格式提供北京和上海的天气信息。 助手：```json { "cities": [ {"name": "北京", "weather": "晴", "temperature": 22}, {"name": "上海", "weather": "多云", "temperature": 25} ] }

现在请回答： 用户：请以JSON格式提供深圳和广州的天气信息。

5.3 利用模型的功能参数

许多LLM API提供了直接控制输出格式的参数。

• OpenAI GPT-4o/4-turbo等：可以使用response_format参数强制输出JSON。

  response = client.chat.completions.create( model="gpt-4-turbo", messages=[...], response_format={ "type": "json_object" }, # 关键参数 temperature=0, )

  注意：当使用response_format={ "type": "json_object" }时，系统消息中必须提示模型输出JSON，否则API可能报错。

• Anthropic Claude：在消息中可以使用XML标签等工具来结构化输出。

5.4 后处理作为安全网

即使使用了上述所有预防措施，仍然建议在你的代码中，将解析逻辑包裹在try...except中，并调用我们上面构建的健壮解析器作为最后的安全网。因为网络抖动、模型版本差异、极端输入都可能导致意外输出。

def get_structured_data_from_ai(prompt): # 1. 精心构造的Prompt full_prompt = f""" {system_prompt_requiring_json} User: {prompt} Assistant: """ # 2. 调用API，可能使用response_format参数 raw_response = call_ai_api(full_prompt, response_format="json_object") # 3. 尝试解析，使用我们的安全网 success, data, _ = robust_parser.parse(raw_response) if not success: # 记录告警，可能触发人工检查或重试逻辑 logger.error(f"AI返回数据解析失败，原始响应: {raw_response[:500]}") # 返回一个安全的默认值或抛出业务异常 return {"error": "failed_to_parse_ai_response"} return data

6. 常见问题与排查技巧实录

在实际集成中，你可能会遇到一些典型场景和错误。以下是一些实录和解决方案。

6.1 错误：“Expecting property name enclosed in double quotes”

• 现象：json.decoder.JSONDecodeError: Expecting property name enclosed in double quotes: line 1 column 2 (char 1)
• 原因：键名使用了单引号或没有引号。例如{‘key’: ‘value’}或{key: “value”}。
• 排查：检查提取后的字符串前几个字符。使用print(repr(candidate[:50]))查看原始字符。
• 解决：启用_fix_single_quotes修复函数。如果是因为没有引号，正则匹配会更复杂，可以考虑使用demjson3或AI修复。

6.2 错误：“Extra data” 或 “Trailing characters”

• 现象：json.decoder.JSONDecodeError: Extra data: line 1 column X (char Y)
• 原因：JSON对象或数组后面有多余的字符。通常是模型在JSON后添加了说明文字。
• 排查：确认_extract_json_candidate函数是否正常工作。检查提取的字符串末尾是否干净。
• 解决：优化提取逻辑，确保只截取到第一个完整JSON结构的末尾。可以尝试用json.loads()的strict模式？不，标准库没有这个参数。所以必须靠预处理截取。

6.3 错误：“Unterminated string starting at”

• 现象：字符串引号没有闭合。
• 原因：模型生成被截断，或者在字符串中包含了未转义的引号。
• 排查：找到出错位置附近的文本。可能是值里包含了换行符。
• 解决：对于截断，可能无解，需要调整API的max_tokens参数。对于字符串内的复杂内容，确保在Prompt中要求模型对字符串内容进行JSON转义。修复已损坏的字符串非常困难，通常需要AI修复。

6.4 错误：解析成功，但结构不对

• 现象：没有抛出异常，但解析出来的Python字典或列表与预期结构不符。
• 原因：模型没有遵循你期望的Schema。例如，你期望一个对象列表，它却返回了一个嵌套对象。
• 排查：在解析后立即进行数据验证。使用jsonschema库。

  from jsonschema import validate, ValidationError schema = { "type": "object", "properties": {"name": {"type": "string"}, "age": {"type": "number"}}, "required": ["name"] } try: validate(instance=parsed_data, schema=schema) except ValidationError as e: logger.warning(f"数据Schema验证失败: {e}") # 执行降级处理或请求重试

• 解决：强化Prompt中的格式描述，使用JSON Schema，并考虑在验证失败时进行重试。

6.5 性能与可靠性权衡

• 问题：容错解析库（如demjson3）可能比标准json库慢得多。AI修复的延迟和成本更高。
• 建议：
  1. 监控：记录每种解析方法的使用频率和成功率。如果99%的响应都能被标准库解析，那么容错路径很少被触发，性能影响可忽略。
  2. 分级处理：对于实时性要求高的场景，可以先尝试标准解析和简单修复（毫秒级）。失败后，将错误响应放入队列，异步进行更耗时的AI修复，并缓存结果（如果相同错误可能重复出现）。
  3. 超时设置：对解析过程设置超时，防止个别畸形数据导致整个服务线程阻塞。

6.6 一个真实的排查案例

场景：从AI返回的文本中解析一个用户偏好列表。原始响应如下：

好的，这是根据您的对话总结的用户偏好： - 颜色：蓝色和绿色 - 食物：披萨和寿司 - 电影类型：科幻片 我将它格式化为JSON： ['蓝色', '绿色', '披萨', '寿司', '科幻片']

问题：直接json.loads失败，因为开头有大量文本。提取函数_extract_json_candidate通过寻找第一个[和匹配的]，成功提取出['蓝色', '绿色', '披萨', '寿司', '科幻片']。但标准库解析仍然失败，因为数组中的字符串使用了单引号。

解决流程：

1. 标准解析失败，捕获错误Expecting value: line 1 column 2 (char 1)。
2. 触发_fix_single_quotes函数，将字符串转换为["蓝色", "绿色", "披萨", "寿司", "科幻片"]。
3. 再次尝试json.loads，成功解析为Python列表。
4. 解析方法记录为"standard_json after fix_single_quotes"。

这个案例展示了多层防御如何协同工作：预处理提取解决了“包裹文本”问题，轻度修复解决了“单引号”问题，最终无需动用重量级的容错库或AI。