在构建基于大模型的智能应用时你是否遇到过这样的困扰你向模型提问“列出三个用户信息包含姓名、年龄和邮箱”期望得到一个结构化的JSON数组但模型却返回了一段自由文本甚至夹杂着解释说明或者模型虽然返回了JSON但格式时常出错比如缺少引号、括号不匹配导致你的下游解析代码频繁崩溃。尤其是在开发AI Agent或自动化工作流时JSON作为标准的数据交换格式其输出的稳定性直接决定了整个系统的可靠性。本文将深入探讨如何让大模型稳定、可靠地输出符合预期的JSON格式涵盖从提示词工程、API参数调优到后处理校验的全链路方案并提供可直接复现的代码示例。无论你是正在搭建第一个AI应用的开发者还是准备应对大模型相关技术面试的求职者这篇文章都将为你提供一套实用的“避坑”指南和工程化解决方案。1. 背景与核心概念为什么JSON输出如此重要在AI应用开发特别是AI Agent的构建中大语言模型LLM的核心价值在于理解自然语言指令并生成结构化的信息或执行动作。JSONJavaScript Object Notation因其轻量级、易读、易解析以及与几乎所有编程语言的良好兼容性成为了连接LLM与下游业务逻辑的“桥梁”。1.1 JSON在AI应用中的核心作用结构化数据交换Agent需要将LLM的文本输出转化为程序可操作的数据对象。例如一个订餐Agent需要解析出“菜品”、“数量”、“送达时间”等字段。函数调用Function Calling许多LLM API如OpenAI、DeepSeek支持将工具/函数描述以JSON Schema形式传递给模型模型则需返回一个包含调用参数的JSON对象来触发函数执行。这是构建复杂Agent的基石。标准化接口统一的JSON输出格式便于构建前后端分离的架构前端只需关心如何渲染固定的数据结构后端则负责保证LLM输出结构的稳定性。1.2 “不稳定”输出的常见表现与根源不稳定并非指模型“发疯”而是指其输出在严格遵循JSON语法和预定Schema方面存在波动。根源在于模型的训练数据与概率本质LLM是基于海量文本训练的概率模型其下一个词的生成具有随机性。虽然经过指令微调但在生成严格语法结构时仍可能产生偏差。提示词Prompt的模糊性如果指令不够清晰、具体模型可能会以它认为更“自然”的方式如附带解释的文本来回应。上下文Context的干扰对话历史中如果存在非JSON格式的内容可能会影响模型后续输出的格式选择。因此追求“稳定输出JSON”的目标实质上是通过一系列工程化手段约束模型的生成空间使其行为高度可预测。2. 环境准备与版本说明本文将使用Python语言并主要以OpenAI GPT系列模型的API为例进行演示。这些方法同样适用于其他提供类似功能的模型API如Anthropic Claude、DeepSeek、国内各大模型平台等。基础环境要求操作系统Windows 10/11, macOS, 或 Linux (如Ubuntu 20.04)Python版本 3.8关键库openai用于调用OpenAI API。本文示例基于openai1.0.0的新版SDK。pydantic用于定义和验证数据模型Schema这是保证JSON结构稳定的强力工具。jsonPython标准库用于解析和校验。tenacity或backoff用于实现API调用的重试机制增强鲁棒性可选但推荐。安装依赖在项目根目录下创建requirements.txt文件并添加以下内容openai1.6.0 pydantic2.0.0 tenacity8.2.0通过pip安装pip install -r requirements.txt获取API密钥你需要一个OpenAI的API密钥。请妥善保管不要将其硬编码在代码中或提交到版本控制系统。# 示例在代码中设置环境变量实际项目中推荐使用.env文件 import os os.environ[“OPENAI_API_KEY”] “your-api-key-here” # 请替换为你的真实密钥3. 核心方法从提示词到后处理的完整链条让大模型稳定输出JSON是一个系统工程通常需要多层保障。我们将从最直接到最稳健的方法逐一讲解。3.1 基础方法强化提示词Prompt Engineering这是成本最低、最先应该尝试的方法。核心原则是明确、具体、结构化地提出你的要求。3.1.1 简单指令在提示词中直接要求返回JSON。import openai from openai import OpenAI client OpenAI() prompt “”” 请提供三个虚构的用户信息。 要求以JSON数组格式返回每个对象包含以下字段 - name (字符串) - age (整数) - email (字符串) 请确保输出是**纯JSON**不要有任何额外的解释、标记或文本。 “”” response client.chat.completions.create( model“gpt-3.5-turbo”, messages[{“role”: “user”, “content”: prompt}], temperature0.1, # 降低随机性 ) print(response.choices[0].message.content)关键点详细描述Schema明确列出字段名、类型字符串、整数等。强调输出格式使用“纯JSON”、“仅JSON”、“不要有任何额外文本”等强约束语句。降低temperature将该参数设为较低值如0.1或0减少生成的随机性使输出更确定。3.1.2 提供示例Few-Shot Learning在提示词中给出一个输入输出的例子能极大地引导模型。prompt_with_example “”” 你是一个信息提取助手始终以指定的JSON格式回复。 示例 用户输入“介绍一下苹果公司创始人是谁成立于哪年” 助手输出{“company”: “Apple Inc.”, “founder”: “Steve Jobs”, “founded_year”: 1976} 现在请处理以下请求 用户输入“特斯拉汽车公司的CEO是谁总部在哪里” 请根据示例格式输出JSON。 “”” response client.chat.completions.create( model“gpt-3.5-turbo”, messages[{“role”: “user”, “content”: prompt_with_example}], temperature0.1, ) print(response.choices[0].message.content)这种方法通过模式匹配让模型快速理解你的精确期望。3.2 进阶方法利用API原生功能JSON Mode 与 Function CallingOpenAI等平台提供了官方的解决方案来强制JSON输出。3.2.1 JSON Mode在API调用参数中设置response_format{“type”: “json_object”}。这是最直接、最有效的强制手段。response client.chat.completions.create( model“gpt-3.5-turbo-1106”, # 注意部分旧模型不支持此参数 messages[ {“role”: “system”, “content”: “你只输出JSON。”}, {“role”: “user”, “content”: “列出两个城市和其所在国家。”} ], response_format{“type”: “json_object”}, # 关键参数 temperature0.1, ) content response.choices[0].message.content print(content) print(“Is valid JSON?”, isinstance(eval(content), dict)) # 简单验证重要限制当使用response_format: { “type”: “json_object” }时系统消息system message或用户消息user message中必须明确指示模型输出JSON。否则API可能报错。此模式保证输出是有效的JSON对象以{开头但不保证其内部结构符合你的自定义Schema。3.2.2 Function Calling (Tool Calls)这是更强大、更结构化的方式。你定义一个或多个“函数”工具并以其参数的形式指定严格的JSON Schema。模型会返回一个包含调用哪个函数及其参数的JSON对象。from pydantic import BaseModel, Field from typing import List # 1. 使用Pydantic定义数据结构 class User(BaseModel): name: str Field(description“用户姓名”) age: int Field(description“用户年龄”, ge0, le150) # 添加范围校验 email: str Field(description“用户邮箱”) class UserList(BaseModel): users: List[User] Field(description“用户列表”) # 2. 将Pydantic模型转换为OpenAI可识别的工具定义 tools [{ “type”: “function”, “function”: { “name”: “extract_user_info”, “description”: “从文本中提取用户信息”, “parameters”: UserList.model_json_schema(), # 关键自动生成JSON Schema } }] # 3. API调用 response client.chat.completions.create( model“gpt-3.5-turbo”, messages[{“role”: “user”, “content”: “小明20岁邮箱是xiaomingexample.com小红25岁邮箱是xiaohongexample.com。请提取他们的信息。”}], toolstools, tool_choice{“type”: “function”, “function”: {“name”: “extract_user_info”}}, # 强制使用特定工具 temperature0, ) # 4. 解析结果 if response.choices[0].message.tool_calls: tool_call response.choices[0].message.tool_calls[0] if tool_call.function.name “extract_user_info”: import json arguments json.loads(tool_call.function.arguments) print(json.dumps(arguments, indent2, ensure_asciiFalse)) # 可以用Pydantic模型再次验证和解析 user_list UserList(**arguments) print(f“成功提取了 {len(user_list.users)} 个用户信息。”)优势结构绝对稳定输出完全符合你定义的Pydantic Schema。类型安全结合Pydantic可以在解析时进行强大的数据验证类型、范围、正则等。意图明确模型不仅输出数据还通过选择“函数”表明了其意图是构建Agent的核心机制。3.3 保底方法输出后处理与校验无论前两种方法多么有效在生产环境中对LLM的输出进行后处理与校验都是必不可少的防御性编程策略。3.3.1 健壮的JSON解析与修复import json import re def safe_json_parse(llm_output: str, max_retries3): “”” 安全地解析LLM输出的JSON。 1. 首先尝试直接解析。 2. 如果失败尝试提取字符串中的JSON部分。 3. 如果仍失败可记录日志并返回默认值或抛出异常。 “”” # 尝试1 直接解析 try: return json.loads(llm_output) except json.JSONDecodeError as e: print(f“直接解析失败: {e}”) # 尝试2 使用正则表达式提取可能的JSON对象或数组 # 匹配以 { 开始以 } 结束或 [ 开始以 ] 结束的内容 json_pattern r(\{.*\}|\[.*\]) matches re.findall(json_pattern, llm_output, re.DOTALL) # re.DOTALL 使 . 匹配换行符 for match in matches: try: # 尝试清理常见的格式问题如末尾多余的逗号 cleaned re.sub(r‘,\s*}’, ‘}’, match) # 删除对象末尾多余的逗号 cleaned re.sub(r‘,\s*\]’, ‘]’, cleaned) # 删除数组末尾多余的逗号 return json.loads(cleaned) except json.JSONDecodeError: continue # 尝试下一个匹配项 # 尝试3 如果以上都失败可以返回一个优雅的默认值或抛出业务异常 print(“无法从输出中提取有效JSON。”) return {“error”: “Failed to parse LLM output as JSON”, “raw_output”: llm_output[:200]} # 返回部分原始输出供调试 # 使用示例 llm_output_with_text “”” 好的根据您的要求以下是用户信息的JSON格式 [ {“name”: “张三”, “age”: 30, “email”: “zhangsanexample.com”}, {“name”: “李四”, “age”: 25, “email”: “lisiexample.com”} ] 希望这能帮到您 “”” parsed_data safe_json_parse(llm_output_with_text) print(“解析后的数据:”, parsed_data)3.3.2 使用Pydantic进行模式验证即使成功解析为JSON字典其内容也可能不符合预期如字段缺失、类型错误。Pydantic可以在解析时进行强制验证。from pydantic import ValidationError # 接上文的 UserList 模型 try: validated_data UserList(**parsed_data) print(“数据验证成功:”, validated_data.model_dump()) except ValidationError as e: print(“数据验证失败:”, e.errors()) # 处理验证错误例如使用默认值、请求重试或记录告警4. 完整实战案例构建一个稳定的用户信息提取Agent让我们综合运用以上所有技术构建一个从自由文本中稳定提取用户信息并输出JSON的微型Agent。项目结构user_info_agent/ ├── requirements.txt ├── config.py # 配置文件 ├── schemas.py # Pydantic数据模型 ├── llm_client.py # LLM客户端与提示词模板 ├── parser.py # 后处理解析器 └── main.py # 主程序4.1 定义数据模型 (schemas.py)from pydantic import BaseModel, Field, EmailStr from typing import List, Optional class UserInfo(BaseModel): “””单个用户信息模型“”” name: str Field(description“用户全名”) age: Optional[int] Field(None, description“用户年龄可能未知”, ge0, le120) email: Optional[EmailStr] Field(None, description“用户邮箱地址”) # EmailStr提供基础邮箱格式校验 city: Optional[str] Field(None, description“所在城市”) class ExtractionResult(BaseModel): “””提取结果模型“”” users: List[UserInfo] Field(description“提取出的用户列表”) source_text: str Field(description“原始输入文本”) success: bool Field(True, description“提取是否成功”) error_message: Optional[str] Field(None, description“若失败错误信息”)4.2 构建LLM客户端与提示词 (llm_client.py)import openai from openai import OpenAI import os from tenacity import retry, stop_after_attempt, wait_exponential from schemas import ExtractionResult from config import OPENAI_API_KEY, OPENAI_BASE_URL, MODEL_NAME client OpenAI(api_keyOPENAI_API_KEY, base_urlOPENAI_BASE_URL) # 定义工具基于Pydantic Schema EXTRACTION_TOOLS [{ “type”: “function”, “function”: { “name”: “extract_users”, “description”: “从文本中提取所有提到的用户信息”, “parameters”: ExtractionResult.model_json_schema(), } }] SYSTEM_PROMPT “”” 你是一个精准的信息提取助手。你的任务是从用户提供的文本中识别并提取所有出现的用户信息。 请仔细阅读文本确保不遗漏任何用户。如果文本中没有明确提及用户信息请返回空列表。 你**必须**使用为你提供的 extract_users 工具来回复。 “”” retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min4, max10)) def extract_users_with_llm(text: str) - dict: “”” 调用LLM进行信息提取使用Function Calling确保结构化输出。 包含重试机制以应对网络或API瞬时故障。 “”” try: response client.chat.completions.create( modelMODEL_NAME, messages[ {“role”: “system”, “content”: SYSTEM_PROMPT}, {“role”: “user”, “content”: f“请从以下文本中提取用户信息\n\n{text}”} ], toolsEXTRACTION_TOOLS, tool_choice{“type”: “function”, “function”: {“name”: “extract_users”}}, # 强制调用 temperature0.1, # 低随机性 max_tokens1000, ) message response.choices[0].message if message.tool_calls: tool_call message.tool_calls[0] if tool_call.function.name “extract_users”: import json return json.loads(tool_call.function.arguments) # 如果没有调用工具理论上不应该发生返回错误结构 return {“users”: [], “source_text”: text, “success”: False, “error_message”: “LLM did not call the extraction tool.”} except Exception as e: # 记录日志 print(f“LLM API调用异常: {e}”) raise # 让tenacity重试4.3 实现后处理解析器 (parser.py)import json import re from typing import Any, Dict from pydantic import ValidationError from schemas import ExtractionResult def robust_json_parser(llm_raw_output: str) - Dict[str, Any]: “””健壮的JSON解析器应对不规范的输出。“”” # 1. 尝试直接解析 try: return json.loads(llm_raw_output) except json.JSONDecodeError: pass # 2. 尝试提取JSON部分 json_pattern r(\{(?:[^{}]|(?R))*\}|\[(?:[^\[\]]|(?R))*\])’ matches re.findall(json_pattern, llm_raw_output, re.DOTALL) for match in matches: try: # 简单修复移除JSON对象/数组末尾可能存在的逗号 repaired re.sub(r‘,\s*([}\]])’, r‘\1’, match) return json.loads(repaired) except json.JSONDecodeError: continue # 3. 提取失败 raise ValueError(f“无法从文本中解析出有效JSON: {llm_raw_output[:500]}…”) def validate_and_parse(extracted_dict: Dict[str, Any], source_text: str) - ExtractionResult: “””使用Pydantic验证并解析数据。“”” # 确保字典中包含原始文本 extracted_dict[“source_text”] source_text try: result ExtractionResult(**extracted_dict) return result except ValidationError as e: # 处理验证错误例如年龄为字符串时尝试转换 errors e.errors() for error in errors: if error[‘type’] ‘int_parsing’ and error[‘loc’] (‘users’, … , ‘age’): # 尝试找到有问题的用户并修复年龄字段 user_idx error[‘loc’][1] ctx error.get(‘ctx’, {}) if ‘input_string’ in ctx: try: extracted_dict[‘users’][user_idx][‘age’] int(ctx[‘input_string’]) except (ValueError, TypeError, IndexError): pass # 重试验证 try: return ExtractionResult(**extracted_dict) except ValidationError: # 如果仍然失败返回一个标记为失败的结果 return ExtractionResult( users[], source_textsource_text, successFalse, error_messagef“Data validation failed: {errors}” )4.4 主程序集成 (main.py)from llm_client import extract_users_with_llm from parser import robust_json_parser, validate_and_parse import json def extract_users_from_text(text: str) - dict: “”” 主流程提取 - 解析 - 验证 - 返回 “”” print(f“ 处理文本 \n{text}\n”) # 步骤1: 调用LLM使用Function Calling try: llm_raw_dict extract_users_with_llm(text) print(“1. LLM返回原始数据:”, json.dumps(llm_raw_dict, indent2, ensure_asciiFalse)) except Exception as e: print(f“1. LLM调用失败: {e}”) return { “users”: [], “source_text”: text, “success”: False, “error_message”: f“LLM API call failed: {e}” } # 步骤2 3: 验证与解析 (在parser.validate_and_parse中已集成) final_result validate_and_parse(llm_raw_dict, text) print(f“2. 最终验证结果 (成功: {final_result.success}):”) print(json.dumps(final_result.model_dump(), indent2, ensure_asciiFalse)) print(“\n” “”*50 “\n”) return final_result.model_dump() if __name__ “__main__”: # 测试用例 test_cases [ “我们的团队成员有张三30岁邮箱zhangsancompany.com来自北京李四邮箱 lisitest.org今年25岁。”, “这里没有提到任何人。”, “王五的邮箱是 wangwuexample.com 他住在上海。另外赵六今年35岁了。”, “这是一个格式混乱的文本姓名: 孙七 年龄: 二十八 联系邮箱: sunqimail.com。”, ] for test_text in test_cases: result extract_users_from_text(test_text)4.5 运行与验证运行python main.py你将看到针对不同测试文本Agent都能稳定地输出结构化的ExtractionResultJSON对象。即使面对格式混乱的输入如“二十八”后处理逻辑也能在一定程度上进行容错。5. 常见问题与排查思路问题现象可能原因排查与解决方案API返回错误‘message’ must contain ‘content’ or ‘function_call’使用了response_format: { “type”: “json_object” }但系统或用户消息中没有明确要求输出JSON。1. 在系统提示词中加入“你总是以JSON格式回复”。2. 或在用户消息末尾强调“请输出JSON”。输出是JSON字符串但被包裹在markdown代码块中模型遵循了某些训练数据中“用代码块展示JSON”的模式。后处理使用正则表达式如json\n(.*?)\n提取代码块内的内容。或在提示词中强调“输出纯JSON不要使用任何markdown格式”。JSON格式正确但字段值类型错误如年龄是字符串“30”模型对类型不敏感或提示词未明确指定类型。1. 在提示词中明确指定类型“age (整数)”。2. 使用Function Calling Pydantic在Schema中定义严格类型。3. 在后处理中进行类型转换和验证。模型忽略了部分字段或返回了额外字段提示词中对Schema的描述不够清晰或者模型“自由发挥”。1. 使用Function Calling这是最严格的约束。2. 在Few-Shot示例中展示包含所有必需字段和可选字段的完整例子。3. 在系统提示词中强调“仅输出指定的字段不要添加任何其他字段”。输出不稳定时而JSON时而文本temperature参数过高或提示词约束力不够。1. 将temperature设为0或接近0的值如0.1。2. 结合使用JSON Mode和强约束提示词。3. 采用Function Calling从根本上限制输出格式。处理长文本时JSON输出被截断或不完整超过了模型的上下文窗口或生成令牌限制(max_tokens)。1. 增加max_tokens参数确保其大于预期JSON字符串的长度。2. 对于超长文本考虑先进行文本分割或摘要再分别提取信息。API调用超时或失败网络问题或服务端不稳定。1. 实现重试机制如使用tenacity库。2. 设置合理的超时时间。3. 在代码中添加降级逻辑如返回缓存或默认值。6. 最佳实践与工程建议优先使用Function Calling对于生产环境尤其是Agent应用Function Calling工具调用是保证输出结构化的首选方案。它提供了机器可读的强契约。始终进行后处理验证永远不要信任LLM的原始输出。必须有一层后处理逻辑来解析、清洗、验证数据这是保证系统鲁棒性的最后防线。定义清晰的数据契约使用像Pydantic这样的库来定义你的数据模型。它不仅是验证工具更是团队沟通和API设计的清晰契约。实施完善的错误处理与降级重试对瞬时的API失败进行指数退避重试。降级如果结构化提取失败可以降级到使用简单正则或关键词匹配或者返回一个友好的错误信息给用户。监控与告警记录JSON解析失败、验证失败的频率和具体案例用于持续优化提示词和模型选择。编写全面的测试用例为你的提取逻辑编写单元测试和集成测试覆盖正常用例格式规整的文本。边界用例缺失信息、模糊表述。错误用例无相关信息、完全无关文本。压力用例超长文本、特殊字符。提示词优化是持续过程将你的提示词视为需要不断迭代的“代码”。根据后处理环节发现的常见错误反向优化你的系统提示词和Few-Shot示例。考虑使用更擅长格式化的模型某些模型在遵循指令和输出格式方面可能表现更佳。可以针对你的任务进行简单的模型评估如对比GPT-3.5-Turbo, GPT-4, Claude等。为面试准备如果是为了应对大模型相关面试你需要理解这些方法背后的原理提示词工程如何通过Few-Shot、Chain-of-Thought等技术引导模型。Function Calling原理本质上是让模型在特定语法空间JSON Schema定义的空间内进行生成。温度Temperature与Top-p如何影响输出的确定性与多样性。大模型的局限性知其不可为而为之了解它在结构化输出上的固有弱点并知道如何用工程手段弥补。通过将清晰的提示词、强大的API功能、严谨的后处理验证三者结合你可以极大地提升大模型输出JSON的稳定性从而构建出可靠、高效的AI应用。这套方法论不仅适用于用户信息提取同样可以推广到任何需要从非结构化文本中抽取结构化数据的场景。