当前位置：首页 > news >正文

大模型稳定输出JSON的完整方案：从Prompt工程到Function Calling实战

news 2026/8/4 12:01:39

在开发基于大模型的AI应用，特别是构建Agent或自动化工作流时，我们常常需要大模型严格按照指定的JSON格式输出数据。无论是调用API、处理结构化数据，还是构建复杂的多步推理链，稳定的JSON输出都是确保系统可靠性和下游程序正确解析的关键。然而，开发者们在实际操作中总会遇到各种“翻车”现场：模型输出的JSON格式混乱、缺少引号、多出无关文本，甚至直接返回一段无法解析的自然语言描述。

本文将系统性地拆解大模型稳定输出JSON的完整方案，从核心原理、Prompt工程技巧、到调用时的参数调优和后处理策略，为你提供一套从理论到实战的闭环解决方案。无论你是正在搭建第一个AI Agent的新手，还是被面试官追问“如何保证大模型输出JSON的稳定性”而需要深入理解的进阶开发者，这篇文章都能提供直接的代码示例和可复现的避坑指南。

1. 理解问题：为什么大模型输出JSON不稳定？

在深入解决方案之前，我们首先要理解问题的根源。大语言模型（LLM）本质上是基于概率生成文本的模型，其训练目标是生成“看起来合理”的下一个词元（Token），而非严格遵循编程语法。

1.1 不稳定的常见表现

格式错误：缺少闭合的大括号}、引号"不匹配、键名未加引号。
内容溢出：在JSON对象前后添加了额外的解释性文字，如“好的，这是你要的JSON：”或“解析如下：”。
结构偏离：未遵循指定的Schema，例如要求输出数组却返回了单个对象，或键名与要求不符。
类型错误：数字值被输出为字符串（如"age": "25"），布尔值被输出为单词（如"is_valid": "yes"）。

1.2 根本原因分析

训练数据偏差：模型在训练时接触的JSON数据可能格式不一，且混杂在大量自然语言文本中。
生成策略的随机性：即使使用相同的输入，由于temperature（温度）等参数的影响，模型每次的采样结果也可能不同。
Prompt指令模糊：指令不够清晰、强硬，模型会优先以“人类友好”的方式回应，而非“机器可解析”的方式。
上下文长度限制：在长对话中，模型可能会遗忘最初的格式指令。

理解了这些，我们就可以有针对性地设计稳定输出的策略。

2. 环境准备与核心工具

本文将主要以OpenAI的GPT系列模型和国产深度求索的DeepSeek-V2 API为例进行演示，但其原理和方法通用于大多数支持Function Calling或JSON Mode的大模型。

2.1 基础环境

Python 3.8+：本文示例代码语言。
必要的Python包：openai,requests,json,pydantic（用于Schema验证）。
API密钥：你需要准备对应大模型平台的API Key。

2.2 安装依赖

创建一个新的Python虚拟环境并安装基础包。

# 创建并激活虚拟环境（可选） python -m venv venv source venv/bin/activate # Linux/Mac # venv\Scripts\activate # Windows # 安装核心依赖 pip install openai requests pydantic

2.3 测试用项目结构

json_stable_output/ ├── utils/ │ ├── __init__.py │ └── prompt_templates.py # 存放Prompt模板 ├── schemas/ │ ├── __init__.py │ └── data_models.py # 存放Pydantic数据模型 ├── config.py # 存放API密钥等配置 ├── main_direct.py # 直接调用示例 ├── main_function_calling.py # 函数调用示例 └── main_json_mode.py # JSON Mode示例

3. 核心策略一：精炼Prompt工程

这是最基础也是最关键的一步。清晰、强约束的Prompt能极大提高模型输出格式的稳定性。

3.1 基础指令模板

一个有效的JSON输出Prompt应包含以下要素：

# utils/prompt_templates.py BASIC_JSON_PROMPT_TEMPLATE = """ 请根据以下用户输入，生成一个严格符合JSON格式的响应。 **要求**： 1. 输出必须是**且仅是一个**有效的JSON对象。 2. 不要添加任何JSON之外的文本、解释、Markdown代码块标记（如```json）或前缀。 3. 确保所有字符串都用双引号（"）包裹，所有键名也用双引号包裹。 4. 请确保JSON结构完整，括号正确闭合。 **JSON Schema（结构）**： {json_schema} **用户输入**： {user_input} 请直接输出JSON： """

3.2 使用示例与反向提示

在Prompt中给出正面示例（Few-Shot）和反面示例（Negative Prompt）效果显著。

# utils/prompt_templates.py FEW_SHOT_JSON_PROMPT_TEMPLATE = """ 你是一个JSON格式输出专家。请始终只返回JSON。 示例任务：提取人物信息。 输入：“我叫张三，今年30岁，是一名来自北京的工程师。” 正确输出：{{"name": "张三", "age": 30, "job": "工程师", "location": "北京"}} 错误输出1（包含额外文本）：好的，这是提取的信息：{{"name": "张三", ...}} 错误输出2（格式错误）：name: 张三, age: 30, ... 现在，请处理新任务。 任务要求：{task_description} JSON结构必须如下： {schema} 输入内容： {user_input} 请直接输出符合上述结构的JSON： """

3.3 结构化思维链（Chain-of-Thought for Structure）

对于复杂嵌套的JSON，可以引导模型先“思考”结构，再输出。这能提升复杂结构的准确性。

# utils/prompt_templates.py COT_JSON_PROMPT_TEMPLATE = """ 你将要生成一个JSON。请按以下两步执行： 第一步（思考）：分析下面的输入，并规划出符合输出Schema的JSON结构。将思考过程放在<thinking>标签内。 第二步（输出）：在<json>标签内，输出最终且唯一的JSON对象。不要有任何其他内容。 输出Schema： {schema} 输入： {user_input} 现在开始： """

调用后，你需要从响应中提取<json>标签内的内容。

4. 核心策略二：利用平台原生功能（JSON Mode & Function Calling）

许多主流大模型平台提供了官方解决方案来强制输出JSON，这比纯Prompt工程更可靠。

4.1 OpenAI的JSON Mode

OpenAI在gpt-4-turbo和gpt-3.5-turbo等模型中引入了response_format参数。

# main_json_mode.py import openai from config import OPENAI_API_KEY import json client = openai.OpenAI(api_key=OPENAI_API_KEY) def get_json_via_json_mode(user_input: str, schema_description: str): """ 使用OpenAI的JSON Mode获取结构化输出。 注意：JSON Mode要求模型输出符合给定的JSON Schema，但Schema本身是通过Prompt描述的。 """ prompt = f""" 请根据以下描述，将用户输入解析为JSON。 JSON结构描述：{schema_description} 用户输入：{user_input} 请输出符合上述描述的JSON对象。 """ try: response = client.chat.completions.create( model="gpt-3.5-turbo-0125", # 或 gpt-4-turbo-preview messages=[{"role": "user", "content": prompt}], response_format={"type": "json_object"}, # 关键参数：启用JSON Mode temperature=0.1, # 低温度提高稳定性 max_tokens=1000 ) json_str = response.choices[0].message.content # 尝试解析，验证有效性 parsed_json = json.loads(json_str) print("成功解析JSON:") print(json.dumps(parsed_json, indent=2, ensure_ascii=False)) return parsed_json except json.JSONDecodeError as e: print(f"JSON解析失败！原始输出：{json_str}") print(f"错误信息：{e}") return None except Exception as e: print(f"API调用异常：{e}") return None if __name__ == "__main__": schema_desc = """ 一个代表“书评”的对象，包含以下字段： - book_title (字符串): 书名 - author (字符串): 作者 - rating (整数，1-5): 评分 - summary (字符串): 简要总结 - tags (字符串数组): 标签列表 """ user_input = "我刚刚读完了《三体》，刘慈欣写的。太震撼了，宏大的宇宙观和深刻的人性思考，我给5星。标签可以打上科幻、硬科幻、雨果奖。" result = get_json_via_json_mode(user_input, schema_desc)

关键点：

response_format={"type": "json_object"}强制模型以合法JSON对象开始和结束生成。
当使用此模式时，系统提示（System Message）或用户第一条消息必须明确指示模型输出JSON，否则可能报错。
它保证了输出是合法的JSON，但内容是否符合你的具体Schema，仍需靠Prompt描述。

4.2 Function Calling（工具调用）

Function Calling本质是让模型返回一个调用特定“函数”的请求，其参数是结构化的JSON。我们可以利用它来“骗取”一个格式稳定的JSON输出。

首先，用Pydantic定义我们期望的数据结构：

# schemas/data_models.py from pydantic import BaseModel, Field from typing import List class BookReview(BaseModel): book_title: str = Field(description="书名") author: str = Field(description="作者") rating: int = Field(ge=1, le=5, description="评分，1-5分") summary: str = Field(description="简要总结") tags: List[str] = Field(description="标签列表")

然后，在调用时，我们将这个Pydantic模型“伪装”成一个函数工具：

# main_function_calling.py import openai import json from config import OPENAI_API_KEY from schemas.data_models import BookReview from pydantic import ValidationError client = openai.OpenAI(api_key=OPENAI_API_KEY) def get_json_via_function_calling(user_input: str, response_model: BaseModel): """ 使用Function Calling来获取结构化输出。 将期望的JSON Schema包装成一个“虚拟函数”，让模型来调用它。 """ # 1. 将Pydantic模型转换为OpenAI函数调用格式 function_json_schema = response_model.model_json_schema() tools = [{ "type": "function", "function": { "name": "extract_information", # 函数名可以任意，不与实际执行挂钩 "description": "提取信息并格式化为结构化数据", "parameters": function_json_schema } }] # 2. 构造用户消息 messages = [ {"role": "system", "content": "你是一个信息提取助手。请根据用户输入，调用提供的函数来输出结构化数据。"}, {"role": "user", "content": user_input} ] try: response = client.chat.completions.create( model="gpt-3.5-turbo-0125", messages=messages, tools=tools, tool_choice={"type": "function", "function": {"name": "extract_information"}}, # 强制调用特定函数 temperature=0.1 ) # 3. 提取模型返回的函数调用参数 tool_call = response.choices[0].message.tool_calls[0] arguments_str = tool_call.function.arguments arguments_dict = json.loads(arguments_str) # 4. 用Pydantic模型验证和解析 validated_data = response_model(**arguments_dict) print("通过Function Calling成功获取并验证JSON:") print(validated_data.model_dump_json(indent=2, ensure_ascii=False)) return validated_data except (IndexError, KeyError, json.JSONDecodeError) as e: print(f"解析Function Calling响应失败：{e}") print(f"原始响应：{response}") return None except ValidationError as e: print(f"数据验证失败：{e}") print(f"原始参数：{arguments_str}") return None if __name__ == "__main__": user_input = "《活着》是余华的作品，读起来非常沉重但感人至深，讲述了福贵一生的苦难。我打4分。标签是小说、悲剧、当代文学。" result = get_json_via_function_calling(user_input, BookReview) if result: print(f"书名：{result.book_title}")

优势：

格式极度稳定：平台层面保证返回的是指定Schema的JSON。
类型校验：可以利用Pydantic在解析时进行类型、范围校验。
结构化输出：直接得到Python对象，无需手动解析键值。

5. 核心策略三：调用参数调优与后处理

即使使用了上述方法，仍需要通过参数微调和后处理来确保万无一失。

5.1 关键API参数设置

temperature（温度）: 设置为较低值（如0.1-0.3），降低随机性，使输出更确定。
top_p（核采样）: 通常设置为较低值（如0.1）或与temperature配合使用。
max_tokens（最大生成长度）: 设置足够大的值以容纳完整JSON，但不要过大以免产生冗余。
stop（停止序列）: 可以设置如\n}、}等序列，但需谨慎，可能截断有效内容。

def call_model_with_stable_params(prompt): response = client.chat.completions.create( model="gpt-3.5-turbo", messages=[{"role": "user", "content": prompt}], temperature=0.1, # 低温度，高确定性 top_p=0.1, # 限制采样池 max_tokens=500, # 根据JSON复杂度调整 # stop=["```"] # 如果Prompt要求用代码块包裹，可设置停止符 ) return response.choices[0].message.content

5.2 鲁棒的后处理管道

编写一个健壮的后处理函数，用于清理和修复常见的非致命格式问题。

# utils/json_post_processor.py import json import re def robust_json_parse(raw_text: str): """ 尝试从可能被污染的文本中提取并解析JSON。 1. 尝试直接解析。 2. 尝试查找JSON对象或数组。 3. 尝试修复常见格式错误。 """ # 清理1：去除可能的Markdown代码块标记 cleaned_text = re.sub(r'^```json\s*|\s*```$', '', raw_text.strip(), flags=re.IGNORECASE) cleaned_text = cleaned_text.strip() # 尝试1：直接解析 try: return json.loads(cleaned_text) except json.JSONDecodeError as e1: pass # 尝试2：查找最外层的大括号或中括号 json_match = re.search(r'(\{.*\}|\[.*\])', cleaned_text, re.DOTALL) if json_match: try: return json.loads(json_match.group(1)) except json.JSONDecodeError as e2: # 尝试3：修复常见错误 potential_json = json_match.group(1) # 修复单引号（不推荐，但可作为最后手段） potential_json = potential_json.replace("'", '"') # 修复未加引号的键（简单情况）：确保模式 { key: value } -> { "key": value } # 注意：此修复非常激进，可能破坏字符串内容，仅作为示例 def quote_keys(match): key = match.group(1).strip() return f'"{key}":' # 仅匹配不在引号内的键（这是一个简化版，复杂情况需更严谨解析器） potential_json = re.sub(r'(\s*)(\w+)(\s*):', r'\1"\2"\3:', potential_json) try: return json.loads(potential_json) except: pass # 如果所有尝试都失败，记录日志并返回None或抛出异常 print(f"无法从文本中解析JSON。原始文本前200字符：{raw_text[:200]}...") raise ValueError("Failed to parse JSON from model output.") # 使用示例 raw_output = model_response_content try: parsed_data = robust_json_parse(raw_output) except ValueError: # 触发重试或降级逻辑 parsed_data = {"error": "parse_failed", "raw_text": raw_output}

6. 完整实战案例：构建一个稳定的图书信息提取Agent

让我们综合运用以上所有策略，构建一个从自由文本中稳定提取图书信息并输出JSON的AI Agent。

6.1 定义数据模型和工具

# schemas/data_models.py from pydantic import BaseModel, Field from typing import Optional, List from enum import Enum class BookGenre(str, Enum): FICTION = "fiction" NON_FICTION = "non_fiction" SCI_FI = "science_fiction" FANTASY = "fantasy" MYSTERY = "mystery" BIOGRAPHY = "biography" OTHER = "other" class BookInfo(BaseModel): title: str = Field(description="书籍标题") author: str = Field(description="作者") publication_year: Optional[int] = Field(None, description="出版年份") genre: BookGenre = Field(description="书籍体裁") isbn: Optional[str] = Field(None, description="ISBN号", pattern=r'^(\d{10}|\d{13})$') keywords: List[str] = Field(default_factory=list, description="关键词列表")

6.2 实现多策略调用器

# agents/book_extractor_agent.py import openai from typing import Dict, Any, Optional from schemas.data_models import BookInfo import json from utils.json_post_processor import robust_json_parse from config import OPENAI_API_KEY class BookExtractorAgent: def __init__(self, model: str = "gpt-3.5-turbo"): self.client = openai.OpenAI(api_key=OPENAI_API_KEY) self.model = model self.prompt_template = """ 你是一个专业的图书信息提取器。请从用户输入中提取关于书籍的结构化信息。 输出要求： 1. 必须是一个有效的JSON对象。 2. 必须严格遵循下面的JSON Schema。 3. 如果某个字段无法从输入中确定，请将其设置为null。 4. 体裁(genre)必须是以下之一：fiction, non_fiction, science_fiction, fantasy, mystery, biography, other。 JSON Schema: {schema} 用户输入： {input} 请直接输出JSON： """ def extract_via_prompt(self, user_input: str) -> Optional[Dict[str, Any]]: """策略1：纯Prompt工程""" from schemas.data_models import BookInfo schema_str = json.dumps(BookInfo.model_json_schema(), indent=2, ensure_ascii=False) prompt = self.prompt_template.format(schema=schema_str, input=user_input) response = self.client.chat.completions.create( model=self.model, messages=[{"role": "user", "content": prompt}], temperature=0.1, max_tokens=500 ) raw_text = response.choices[0].message.content return robust_json_parse(raw_text) def extract_via_json_mode(self, user_input: str) -> Optional[Dict[str, Any]]: """策略2：JSON Mode""" from schemas.data_models import BookInfo schema_desc = BookInfo.schema_json(indent=2) prompt = f"请将以下文本中的图书信息提取为JSON。JSON结构描述如下：\n{schema_desc}\n\n文本：{user_input}" response = self.client.chat.completions.create( model=self.model, messages=[{"role": "user", "content": prompt}], response_format={"type": "json_object"}, temperature=0.1 ) raw_text = response.choices[0].message.content return json.loads(raw_text) # JSON Mode下直接解析通常更安全 def extract_via_function_calling(self, user_input: str) -> Optional[BookInfo]: """策略3：Function Calling（最稳定）""" tools = [{ "type": "function", "function": { "name": "record_book_info", "description": "记录提取到的图书信息", "parameters": BookInfo.model_json_schema() } }] response = self.client.chat.completions.create( model=self.model, messages=[{"role": "user", "content": user_input}], tools=tools, tool_choice={"type": "function", "function": {"name": "record_book_info"}} ) if response.choices[0].message.tool_calls: args = response.choices[0].message.tool_calls[0].function.arguments return BookInfo(**json.loads(args)) return None def extract_with_fallback(self, user_input: str, primary_method: str = "function_calling") -> Dict[str, Any]: """ 带降级策略的提取方法。 优先使用指定方法，失败后尝试其他方法。 """ result = None methods = ["function_calling", "json_mode", "prompt"] # 按优先级排序 if primary_method not in methods: primary_method = "function_calling" ordered_methods = [primary_method] + [m for m in methods if m != primary_method] for method in ordered_methods: try: if method == "function_calling": result_obj = self.extract_via_function_calling(user_input) result = result_obj.model_dump() if result_obj else None elif method == "json_mode": result = self.extract_via_json_mode(user_input) elif method == "prompt": result = self.extract_via_prompt(user_input) if result: print(f"使用方法 [{method}] 提取成功。") # 可选：用Pydantic模型进行最终验证 validated = BookInfo(**result) return validated.model_dump() except Exception as e: print(f"方法 [{method}] 失败：{e}") continue # 所有方法都失败 raise ValueError("所有提取方法均失败，无法从输入中解析图书信息。")

6.3 运行与测试

# main.py from agents.book_extractor_agent import BookExtractorAgent def main(): agent = BookExtractorAgent() test_cases = [ "我最近读了《百年孤独》，加西亚·马尔克斯的杰作，魔幻现实主义题材，发表于1967年。ISBN是978-7-02-000000-0。关键词有孤独、家族、马孔多。", "这是一本关于Python编程的书，作者是John Smith，2019年出版的，属于非虚构类。", "《三体》刘慈欣，科幻小说，非常棒。" ] for i, text in enumerate(test_cases): print(f"\n{'='*50}") print(f"测试用例 {i+1}: {text[:50]}...") try: # 使用最稳定的Function Calling作为首选 result = agent.extract_with_fallback(text, primary_method="function_calling") print("提取结果：") print(json.dumps(result, indent=2, ensure_ascii=False)) except Exception as e: print(f"提取失败：{e}") if __name__ == "__main__": import json main()

7. 常见问题与排查清单

在实际开发中，你可能会遇到以下典型问题。

7.1 问题：模型返回了JSON，但前后有额外文本

现象：好的，这是你要的JSON：{"name": "Alice"} 希望对你有所帮助。原因：Prompt指令不够强硬，模型倾向于生成对人类友好的回复。解决：

在System Message或Prompt开头强调“只输出JSON，不要任何其他文本”。
使用response_format={"type": "json_object"}（OpenAI）。
使用后处理函数（如robust_json_parse）提取JSON部分。

7.2 问题：JSON格式错误，无法解析

现象：JSONDecodeError: Expecting property name enclosed in double quotes原因：键名未用双引号、单引号、尾随逗号、括号不匹配。解决：

在Prompt中明确要求“所有键名必须用双引号包裹”。
使用json.dumps()生成Schema示例时，确保是标准JSON。
启用JSON Mode。
使用Function Calling，由平台保证格式。

7.3 问题：字段值类型不符合预期

现象：期望是整数25，但返回了字符串"25"。原因：模型从文本中推断类型存在歧义。解决：

在Schema描述中明确类型，如“rating (整数，1-5)”。
使用Pydantic等工具在解析后做强制类型转换和验证。
在Few-Shot示例中给出明确的类型示范。

7.4 问题：复杂嵌套结构下模型“遗忘”Schema

现象：对于深层嵌套的JSON，模型可能只生成部分结构。原因：Schema过于复杂，超出模型的单次处理能力或注意力范围。解决：

简化Schema，必要时拆分成多个步骤或多次调用。
使用结构化思维链（Chain-of-Thought），让模型先规划再输出。
增加max_tokens，确保有足够生成长度。

7.5 问题：不同模型表现差异巨大

现象：在GPT-3.5上工作良好，换到其他国产模型或开源模型后格式混乱。原因：不同模型对指令的遵循能力、JSON Mode和Function Calling支持度不同。解决：

查阅目标模型官方文档，确认其是否有强制结构化输出的功能。
强化Prompt工程：对于能力较弱的模型，需要更详细、更严格的Prompt，并多用Few-Shot。
实施更严格的后处理：准备多套后处理正则表达式或使用json5等更宽松的解析库作为备选。

8. 最佳实践与工程建议

8.1 设计阶段

Schema先行：使用Pydantic、TypeScript等工具严格定义你期望的数据结构。这不仅是验证工具，也是生成Prompt和Function描述的基础。
评估模型能力：在项目初期，用小批量测试数据评估目标模型输出JSON的稳定性，选择合适的策略（Prompt/JSON Mode/Function Calling）。
设计降级方案：永远不要假设一次调用100%成功。设计重试机制（如指数退避）和降级逻辑（如换用更稳定的方法或返回错误标识）。