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:i1] # 快速验证能否被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 这类容错解析器。 pass3.3 第三层使用容错JSON解析库当自己的修复逻辑不够用时可以借助更强大的第三方库。这些库实现了对JSON超集或常见错误的宽容解析。json5: 支持JSON5规范允许注释、尾随逗号、单引号等。对于模型生成的类JSON数据非常友好。pip install json5import json5 try: data json5.loads(dirty_json_str) except Exception as e: # 即使json5也可能失败 passdemjson3(或demjson): 一个历史悠久的容错JSON解析器能处理许多不严格的格式。pip install demjson3import demjson3 # demjson.decode 会尝试修复错误 data demjson3.decode(dirty_json_str, strictFalse)实操心得优先考虑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, modelgpt-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( modelmodel, messages[ {role: system, content: 你是一个只输出标准JSON的修复工具。}, {role: user, content: repair_prompt} ], temperature0.1, # 低温度确保输出稳定 max_tokens2000 ) repaired response.choices[0].message.content.strip() # 清理可能的Markdown代码块包装再次 repaired re.sub(r^(?:json)?\s*|\s*$, , repaired, flagsre.MULTILINE) return repaired注意事项这个方法会产生额外的API调用成本和延迟应作为最后的手段。同时要小心避免无限递归修复后的JSON可能仍然错误。可以设置最大重试次数例如2次。4. 构建健壮的AI JSON解析管道将上述策略组合起来形成一个完整的、有弹性的解析管道。这个管道应该从最廉价、最快的方法开始尝试逐步升级到成本更高、更复杂的方法。4.1 管道设计流程图文字描述输入原始API响应文本。步骤1预处理与提取使用extract_json_string函数尝试剥离Markdown代码块和周围文本提取核心JSON候选字符串。如果提取物为None跳至步骤5终极修复。步骤2标准解析尝试对候选字符串直接使用json.loads。成功则返回数据流程结束。步骤3轻度修复后重试如果标准解析失败记录错误信息e1。依次进行a. 应用fix_single_quotes。b. 应用fix_trailing_commas。对修复后的字符串再次尝试json.loads。成功则返回。步骤4容错库解析如果轻度修复后仍失败记录错误信息e2。依次尝试a. 使用json5.loads。b. 如果失败使用demjson3.decode(strictFalse)。成功则返回。步骤5AI辅助修复如果以上所有方法均失败将原始响应文本或最后修复的候选字符串与最后的错误信息e2一起传递给ai_repair_json函数。对修复后的结果从步骤2开始重新执行整个管道因为AI修复后可能仍不完美需要标准流程验证。为避免死循环设置最大AI修复次数如1-2次。步骤6最终失败处理如果所有尝试都失败抛出包含所有阶段错误信息的自定义异常或返回一个包含原始文本的错误结果供人工检查。4.2 代码实现示例import json import json5 import demjson3 import re import logging from typing import Any, Optional, Tuple logging.basicConfig(levellogging.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, fstandard_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, fai_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(fjson5 解析失败: {e1}) # 尝试 demjson3 try: data demjson3.decode(s, strictFalse) return True, data, demjson3 except Exception as e2: logger.debug(fdemjson3 解析失败: {e2}) return False, None, # 使用示例 parser RobustAIJSONParser(max_ai_repair_attempts0) # 暂时关闭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( modelgpt-4-turbo, messages[...], response_format{ type: json_object }, # 关键参数 temperature0, )注意当使用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_formatjson_object) # 3. 尝试解析使用我们的安全网 success, data, _ robust_parser.parse(raw_response) if not success: # 记录告警可能触发人工检查或重试逻辑 logger.error(fAI返回数据解析失败原始响应: {raw_response[:500]}) # 返回一个安全的默认值或抛出业务异常 return {error: failed_to_parse_ai_response} return data6. 常见问题与排查技巧实录在实际集成中你可能会遇到一些典型场景和错误。以下是一些实录和解决方案。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(instanceparsed_data, schemaschema) except ValidationError as e: logger.warning(f数据Schema验证失败: {e}) # 执行降级处理或请求重试解决强化Prompt中的格式描述使用JSON Schema并考虑在验证失败时进行重试。6.5 性能与可靠性权衡问题容错解析库如demjson3可能比标准json库慢得多。AI修复的延迟和成本更高。建议监控记录每种解析方法的使用频率和成功率。如果99%的响应都能被标准库解析那么容错路径很少被触发性能影响可忽略。分级处理对于实时性要求高的场景可以先尝试标准解析和简单修复毫秒级。失败后将错误响应放入队列异步进行更耗时的AI修复并缓存结果如果相同错误可能重复出现。超时设置对解析过程设置超时防止个别畸形数据导致整个服务线程阻塞。6.6 一个真实的排查案例场景从AI返回的文本中解析一个用户偏好列表。原始响应如下好的这是根据您的对话总结的用户偏好 - 颜色蓝色和绿色 - 食物披萨和寿司 - 电影类型科幻片 我将它格式化为JSON [蓝色, 绿色, 披萨, 寿司, 科幻片]问题直接json.loads失败因为开头有大量文本。提取函数_extract_json_candidate通过寻找第一个[和匹配的]成功提取出[蓝色, 绿色, 披萨, 寿司, 科幻片]。但标准库解析仍然失败因为数组中的字符串使用了单引号。解决流程标准解析失败捕获错误Expecting value: line 1 column 2 (char 1)。触发_fix_single_quotes函数将字符串转换为[蓝色, 绿色, 披萨, 寿司, 科幻片]。再次尝试json.loads成功解析为Python列表。解析方法记录为standard_json after fix_single_quotes。这个案例展示了多层防御如何协同工作预处理提取解决了“包裹文本”问题轻度修复解决了“单引号”问题最终无需动用重量级的容错库或AI。 大语言模型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:i1] # 快速验证能否被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 这类容错解析器。 pass3.3 第三层使用容错JSON解析库当自己的修复逻辑不够用时可以借助更强大的第三方库。这些库实现了对JSON超集或常见错误的宽容解析。json5: 支持JSON5规范允许注释、尾随逗号、单引号等。对于模型生成的类JSON数据非常友好。pip install json5import json5 try: data json5.loads(dirty_json_str) except Exception as e: # 即使json5也可能失败 passdemjson3(或demjson): 一个历史悠久的容错JSON解析器能处理许多不严格的格式。pip install demjson3import demjson3 # demjson.decode 会尝试修复错误 data demjson3.decode(dirty_json_str, strictFalse)实操心得优先考虑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, modelgpt-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( modelmodel, messages[ {role: system, content: 你是一个只输出标准JSON的修复工具。}, {role: user, content: repair_prompt} ], temperature0.1, # 低温度确保输出稳定 max_tokens2000 ) repaired response.choices[0].message.content.strip() # 清理可能的Markdown代码块包装再次 repaired re.sub(r^(?:json)?\s*|\s*$, , repaired, flagsre.MULTILINE) return repaired注意事项这个方法会产生额外的API调用成本和延迟应作为最后的手段。同时要小心避免无限递归修复后的JSON可能仍然错误。可以设置最大重试次数例如2次。4. 构建健壮的AI JSON解析管道将上述策略组合起来形成一个完整的、有弹性的解析管道。这个管道应该从最廉价、最快的方法开始尝试逐步升级到成本更高、更复杂的方法。4.1 管道设计流程图文字描述输入原始API响应文本。步骤1预处理与提取使用extract_json_string函数尝试剥离Markdown代码块和周围文本提取核心JSON候选字符串。如果提取物为None跳至步骤5终极修复。步骤2标准解析尝试对候选字符串直接使用json.loads。成功则返回数据流程结束。步骤3轻度修复后重试如果标准解析失败记录错误信息e1。依次进行a. 应用fix_single_quotes。b. 应用fix_trailing_commas。对修复后的字符串再次尝试json.loads。成功则返回。步骤4容错库解析如果轻度修复后仍失败记录错误信息e2。依次尝试a. 使用json5.loads。b. 如果失败使用demjson3.decode(strictFalse)。成功则返回。步骤5AI辅助修复如果以上所有方法均失败将原始响应文本或最后修复的候选字符串与最后的错误信息e2一起传递给ai_repair_json函数。对修复后的结果从步骤2开始重新执行整个管道因为AI修复后可能仍不完美需要标准流程验证。为避免死循环设置最大AI修复次数如1-2次。步骤6最终失败处理如果所有尝试都失败抛出包含所有阶段错误信息的自定义异常或返回一个包含原始文本的错误结果供人工检查。4.2 代码实现示例import json import json5 import demjson3 import re import logging from typing import Any, Optional, Tuple logging.basicConfig(levellogging.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, fstandard_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, fai_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(fjson5 解析失败: {e1}) # 尝试 demjson3 try: data demjson3.decode(s, strictFalse) return True, data, demjson3 except Exception as e2: logger.debug(fdemjson3 解析失败: {e2}) return False, None, # 使用示例 parser RobustAIJSONParser(max_ai_repair_attempts0) # 暂时关闭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( modelgpt-4-turbo, messages[...], response_format{ type: json_object }, # 关键参数 temperature0, )注意当使用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_formatjson_object) # 3. 尝试解析使用我们的安全网 success, data, _ robust_parser.parse(raw_response) if not success: # 记录告警可能触发人工检查或重试逻辑 logger.error(fAI返回数据解析失败原始响应: {raw_response[:500]}) # 返回一个安全的默认值或抛出业务异常 return {error: failed_to_parse_ai_response} return data6. 常见问题与排查技巧实录在实际集成中你可能会遇到一些典型场景和错误。以下是一些实录和解决方案。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(instanceparsed_data, schemaschema) except ValidationError as e: logger.warning(f数据Schema验证失败: {e}) # 执行降级处理或请求重试解决强化Prompt中的格式描述使用JSON Schema并考虑在验证失败时进行重试。6.5 性能与可靠性权衡问题容错解析库如demjson3可能比标准json库慢得多。AI修复的延迟和成本更高。建议监控记录每种解析方法的使用频率和成功率。如果99%的响应都能被标准库解析那么容错路径很少被触发性能影响可忽略。分级处理对于实时性要求高的场景可以先尝试标准解析和简单修复毫秒级。失败后将错误响应放入队列异步进行更耗时的AI修复并缓存结果如果相同错误可能重复出现。超时设置对解析过程设置超时防止个别畸形数据导致整个服务线程阻塞。6.6 一个真实的排查案例场景从AI返回的文本中解析一个用户偏好列表。原始响应如下好的这是根据您的对话总结的用户偏好 - 颜色蓝色和绿色 - 食物披萨和寿司 - 电影类型科幻片 我将它格式化为JSON [蓝色, 绿色, 披萨, 寿司, 科幻片]问题直接json.loads失败因为开头有大量文本。提取函数_extract_json_candidate通过寻找第一个[和匹配的]成功提取出[蓝色, 绿色, 披萨, 寿司, 科幻片]。但标准库解析仍然失败因为数组中的字符串使用了单引号。解决流程标准解析失败捕获错误Expecting value: line 1 column 2 (char 1)。触发_fix_single_quotes函数将字符串转换为[蓝色, 绿色, 披萨, 寿司, 科幻片]。再次尝试json.loads成功解析为Python列表。解析方法记录为standard_json after fix_single_quotes。这个案例展示了多层防御如何协同工作预处理提取解决了“包裹文本”问题轻度修复解决了“单引号”问题最终无需动用重量级的容错库或AI。