尧图网页设计 
在构建基于大模型的智能应用时你是否遇到过这样的困扰你向模型提问期望得到一个结构化的JSON响应以便程序能直接解析但模型却返回了一段夹杂着解释、换行甚至错误括号的自然语言文本这种输出不稳定、格式不统一的问题严重阻碍了大模型与后端系统的无缝集成。本文将深入探讨大模型稳定输出JSON格式的多种实战方案从基础提示词工程到高级函数调用并提供完整的代码示例和避坑指南帮助开发者构建可靠的生产级AI应用。1. 背景与核心概念为什么JSON输出如此重要在传统软件开发中API接口通常返回结构化的数据格式如JSON或XML以便客户端程序能够稳定、高效地解析和处理数据。当我们将大语言模型LLM集成到自动化流程、智能体或业务系统中时同样需要这种稳定性。1.1 结构化输出的价值想象一下你正在开发一个智能客服系统需要从用户对话中提取“投诉类型”、“紧急程度”和“关键时间点”三个字段。如果模型返回“这是一起关于物流延迟的投诉比较紧急用户希望今天下午5点前得到回复”你的程序将难以自动化处理。而如果模型返回{complaint_type: 物流延迟, urgency: 高, deadline: 今天17:00}你的后端代码就可以轻松地将其映射到数据库字段或触发后续工作流。1.2 大模型输出不稳定的根源大语言模型本质上是基于概率生成文本的序列预测模型。它们的训练数据包含了各种格式的文本包括代码、JSON、自然语言描述等。当模型接收到一个指令时它可能会“理解”指令但“执行”偏差它知道要生成JSON但在生成过程中受到概率采样、温度参数等因素影响可能漏掉引号、逗号或括号。过度解释模型倾向于做一个“好老师”在输出JSON前后加上解释性文字如“好的这是您要的JSON数据”。格式混淆对于复杂嵌套结构模型可能混淆数组和对象或者使用单引号而非双引号JSON标准要求双引号。因此让大模型稳定输出JSON核心是通过技术手段约束其生成空间引导其行为更像一个确定性的JSON序列化器。2. 环境准备与版本说明本文将使用 Python 作为主要演示语言并围绕 OpenAI GPT 系列模型和开源模型进行讲解。其他语言如 JavaScript/Node.js的思路完全一致。2.1 基础环境操作系统Windows 10/11, macOS, 或 Linux (如 Ubuntu 20.04)Python 版本3.8 或更高版本包管理工具pip2.2 核心依赖库我们将使用openai库调用商业API使用litellm或transformers库作为连接多种模型包括本地模型的统一入口。pydantic库用于定义严谨的数据结构。# 创建虚拟环境并安装依赖推荐 python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows pip install openai litellm pydantic # 如果需要本地运行模型可能还需要 # pip install transformers torch2.3 模型访问OpenAI API你需要一个有效的 API Key。本文示例将主要使用gpt-3.5-turbo或gpt-4。其他云端模型如 Anthropic Claude, Google Gemini通过litellm可以统一调用。本地模型如 Llama 3, Qwen, ChatGLM 等通过ollama,vllm或transformers库部署和调用。版本说明大模型生态迭代迅速本文重点在于方法论和核心代码逻辑。示例代码基于openai1.0.0和litellm的常见用法具体参数请根据你使用的模型提供商和库的最新文档进行调整。3. 核心方法拆解从提示词到函数调用实现稳定JSON输出主要有四大类方法难度和可靠性逐级递增。3.1 方法一基础提示词工程Prompt Engineering这是最简单直接的方法通过精心设计的提示词来引导模型。核心思路在系统提示System Prompt或用户消息中明确、强硬地指定输出格式。优点零成本无需更改代码逻辑适用于所有模型。缺点稳定性最低模型可能不遵守指令。import openai import json client openai.OpenAI(api_keyyour-api-key) def get_json_via_prompt(user_input: str): response client.chat.completions.create( modelgpt-3.5-turbo, messages[ { role: system, content: 你是一个专业的JSON数据生成器。你必须且只能输出一个完整的、有效的JSON对象不要有任何额外的解释、标记、前缀或后缀。确保使用双引号并确保JSON语法正确。 }, { role: user, content: f请根据以下描述生成JSON。描述{user_input}\n\n输出格式示例{{\key\: \value\}}。现在只输出JSON } ], temperature0.1, # 降低温度减少随机性 max_tokens500 ) raw_output response.choices[0].message.content.strip() # 尝试解析如果失败说明模型没有遵守指令 try: result json.loads(raw_output) return result except json.JSONDecodeError as e: print(fJSON解析失败原始输出{raw_output}) # 此处可以加入后处理清洗逻辑见3.4节 return None # 测试 user_input 提取信息张三男30岁来自北京是一名软件工程师。 result get_json_via_prompt(user_input) if result: print(成功解析JSON:, result)提示词设计要点系统角色定义明确模型角色如“JSON数据生成器”。强制指令使用“必须且只能”、“不要有任何”等强约束词汇。提供示例在消息中直接给出一个简单的格式示例非常有效。结尾强调在最后再次强调“只输出JSON”。调整参数将temperature设置为较低值如0.1使输出更确定。3.2 方法二使用JSON Schema进行约束许多现代大模型API支持在请求中传入response_format参数直接指定输出为JSON并可选地提供一个JSON Schema来定义结构。核心思路利用API的原生支持让模型在生成之初就锁定JSON格式。优点稳定性高是官方推荐做法。缺点并非所有模型和API都支持。def get_json_via_response_format(user_input: str): response client.chat.completions.create( modelgpt-3.5-turbo-1106, # 或 gpt-4-turbo-preview 等支持此功能的模型 messages[ {role: user, content: f根据描述生成用户信息。描述{user_input}} ], response_format{ type: json_object }, # 关键参数要求返回JSON对象 temperature0.1 ) raw_output response.choices[0].message.content # 由于指定了response_format理论上输出一定是可解析的JSON try: return json.loads(raw_output) except json.JSONDecodeError: # 即使有format也应做防御性处理 print(f意外错误输出非JSON: {raw_output}) return None # 更进一步使用JSON Schema定义具体结构OpenAI部分版本支持 def get_json_via_schema(user_input: str): # 注意截至知识截止日期OpenAI的JSON Schema支持可能处于测试阶段请查阅最新文档。 # 以下代码为概念演示。 response client.chat.completions.create( modelgpt-4-turbo-preview, messages[ {role: user, content: f提取用户信息。描述{user_input}} ], response_format{ type: json_schema, json_schema: { name: user_info, schema: { type: object, properties: { name: {type: string}, age: {type: integer}, city: {type: string}, job: {type: string} }, required: [name, age], additionalProperties: False # 禁止输出schema未定义的字段 } } } ) # ... 解析逻辑同上3.3 方法三函数调用Function Calling/工具调用Tool Calls这是目前最强大、最稳定的方法。你定义好一个“函数”包含名称、描述和参数schema模型会识别用户输入是否需要调用此函数并返回一个严格符合参数schema的JSON对象。核心思路将“生成JSON”转化为“调用一个虚拟函数并填充参数”。优点稳定性极高输出完全结构化且意图识别准确。缺点流程稍复杂需要处理“是否调用函数”的逻辑。def extract_info_via_function_calling(user_input: str): # 1. 定义你希望模型“调用”的函数 tools [ { type: function, function: { name: extract_user_info, description: 从文本中提取用户个人信息, parameters: { type: object, properties: { name: {type: string, description: 用户姓名}, gender: {type: string, enum: [男, 女, 其他], description: 性别}, age: {type: integer, description: 年龄}, city: {type: string, description: 所在城市}, occupation: {type: string, description: 职业} }, required: [name, age], additionalProperties: False } } } ] # 2. 发起对话提供工具定义 response client.chat.completions.create( modelgpt-3.5-turbo, messages[{role: user, content: user_input}], toolstools, tool_choiceauto, # 让模型决定是否调用工具 temperature0 ) # 3. 检查模型的响应 message response.choices[0].message if message.tool_calls: # 模型决定调用工具 tool_call message.tool_calls[0] # 假设只调用一个工具 if tool_call.function.name extract_user_info: # 提取出的参数已经是JSON字符串 arguments_str tool_call.function.arguments try: arguments_dict json.loads(arguments_str) return arguments_dict except json.JSONDecodeError: print(f函数参数解析失败: {arguments_str}) return None else: # 模型认为不需要或无法调用工具返回了普通文本 print(f模型未调用函数返回文本: {message.content}) return None # 测试 user_input 帮我记录一下李四28岁在深圳做设计师。 result extract_info_via_function_calling(user_input) print(result) # 输出: {name: 李四, age: 28, city: 深圳, occupation: 设计师} # 注意gender字段未在输入中提及且不在required中所以输出中不存在该字段。3.4 方法四输出后处理与验证作为最后一道防线无论使用哪种方法都应该对模型的原始输出进行清洗和验证。核心思路使用正则表达式或解析器从可能包含额外文本的输出中提取出JSON部分并用json.loads()或pydantic进行验证。import re import json from pydantic import BaseModel, ValidationError def extract_and_validate_json(raw_text: str, pydantic_modelNone): 从原始文本中提取并验证JSON。 :param raw_text: 模型返回的原始文本 :param pydantic_model: 可选的Pydantic模型用于强验证 :return: 解析后的字典或Pydantic模型实例失败则返回None # 方法A使用正则表达式查找最像JSON的部分 # 这个正则匹配以 { 开头以 } 结尾中间内容相对平衡的字符串简单场景 json_pattern r\{[^{}]*\} # 非常简单的匹配对于嵌套JSON会失败 # 更健壮的做法使用栈或现成的库如 json_repair # 方法B尝试直接解析整个文本如果模型遵守指令这应该成功 # 方法C使用 json_repair 等第三方库修复常见的JSON格式错误 # pip install json_repair # from json_repair import repair_json # 这里演示一个简单的尝试先尝试直接解析失败则尝试查找 text raw_text.strip() # 尝试1直接解析 try: data json.loads(text) return validate_with_pydantic(data, pydantic_model) except json.JSONDecodeError: pass # 尝试2查找被标记的JSON块例如被 json ... 包裹 if json in text: parts text.split(json) if len(parts) 1: json_block parts[1].split()[0].strip() try: data json.loads(json_block) return validate_with_pydantic(data, pydantic_model) except json.JSONDecodeError: pass # 如果还找不到可以尝试更复杂的启发式方法或返回None print(f无法从文本中提取有效JSON: {text[:200]}...) return None def validate_with_pydantic(data: dict, model_class): if model_class is None: return data try: # 使用Pydantic模型进行数据验证和类型转换 instance model_class(**data) return instance except ValidationError as e: print(fPydantic验证失败: {e}) return None # 定义一个Pydantic模型 class UserInfo(BaseModel): name: str age: int city: str | None None # 可选字段 job: str | None None # 使用后处理 raw_output_from_model 用户信息如下\njson\n{\name\: \王五\, \age\: 35, \city\: \上海\}\n processed_data extract_and_validate_json(raw_output_from_model, UserInfo) if processed_data: print(f验证通过的数据: {processed_data}) # 如果是Pydantic模型可以方便地访问属性 if isinstance(processed_data, UserInfo): print(f姓名: {processed_data.name})4. 完整实战案例构建一个稳定的天气查询智能体让我们综合运用以上方法构建一个能稳定返回JSON格式天气信息的智能体。该智能体接收用户关于天气的自然语言查询并返回结构化的天气数据。4.1 项目结构与设计weather_agent/ ├── config.py # 配置文件存放API Key等 ├── schemas.py # Pydantic数据模型定义 ├── llm_client.py # 大模型客户端封装 ├── weather_tool.py # 模拟的天气查询工具 ├── agent.py # 智能体主逻辑 └── main.py # 主程序入口4.2 定义数据结构schemas.py使用Pydantic确保输入输出的数据形状和类型。# schemas.py from pydantic import BaseModel, Field from typing import Optional, List from enum import Enum class TemperatureUnit(str, Enum): celsius celsius fahrenheit fahrenheit class WeatherCondition(str, Enum): sunny sunny cloudy cloudy rainy rainy snowy snowy windy windy class WeatherRequest(BaseModel): 用户查询解析后的结构化请求 location: str Field(description查询的城市或地区名称如‘北京’、‘New York’) date: Optional[str] Field(defaultNone, description查询的日期格式‘YYYY-MM-DD’默认为今天) unit: TemperatureUnit Field(defaultTemperatureUnit.celsius, description温度单位) class WeatherResponse(BaseModel): 返回给用户的标准化天气响应 location: str date: str temperature: float Field(description温度值) unit: TemperatureUnit condition: WeatherCondition humidity: Optional[int] Field(description湿度百分比, ge0, le100) wind_speed: Optional[float] Field(description风速公里/小时, ge0) forecast: Optional[List[WeatherResponse]] Field(defaultNone, description未来几天的预报)4.3 封装LLM客户端与函数调用llm_client.py# llm_client.py import json from openai import OpenAI from typing import Dict, Any from schemas import WeatherRequest import config client OpenAI(api_keyconfig.OPENAI_API_KEY) def create_weather_tool(): 定义天气查询‘工具’函数 # 利用WeatherRequest的schema作为函数参数schema schema_dict WeatherRequest.schema() return { type: function, function: { name: get_weather, description: 根据地点和日期查询天气信息, parameters: schema_dict } } def parse_user_query_with_llm(user_query: str) - Dict[str, Any]: 使用函数调用解析用户自然语言查询。 返回解析后的参数字典。 tools [create_weather_tool()] response client.chat.completions.create( modelgpt-3.5-turbo, messages[ {role: system, content: 你是一个天气查询助手。请从用户的问题中提取查询地点、日期和温度单位。如果用户未指定日期默认为今天未指定单位默认为摄氏度。}, {role: user, content: user_query} ], toolstools, tool_choice{type: function, function: {name: get_weather}}, # 强制调用此工具 temperature0.0, # 设置为0以获得最确定性的输出 max_tokens500 ) message response.choices[0].message if message.tool_calls: tool_call message.tool_calls[0] if tool_call.function.name get_weather: args_json tool_call.function.arguments try: args_dict json.loads(args_json) # 使用Pydantic模型进行验证和类型转换 validated_request WeatherRequest(**args_dict) return validated_request.dict() # 返回字典 except (json.JSONDecodeError, Exception) as e: print(f解析或验证函数参数失败: {e}, 原始参数: {args_json}) return None print(f模型未返回预期的工具调用。响应: {message.content}) return None # 备用方案使用response_format如果模型支持 def parse_user_query_with_json_mode(user_query: str): 使用JSON模式解析查询作为备选方案 response client.chat.completions.create( modelgpt-3.5-turbo-1106, messages[ {role: system, content: 你输出JSON。从用户问题中提取‘location’、‘date’默认今天、‘unit’默认celsius。}, {role: user, content: user_query} ], response_format{type: json_object}, temperature0.0 ) raw_json response.choices[0].message.content try: data json.loads(raw_json) validated_request WeatherRequest(**data) return validated_request.dict() except Exception as e: print(fJSON模式解析失败: {e}) return None4.4 模拟天气查询工具weather_tool.py# weather_tool.py import random from datetime import datetime, timedelta from schemas import WeatherResponse, WeatherCondition, TemperatureUnit from typing import Dict def mock_fetch_weather(location: str, date: str None, unit: TemperatureUnit TemperatureUnit.celsius) - Dict: 模拟一个天气API的调用。 在实际项目中这里会调用真实的天气服务API如OpenWeatherMap。 if date is None: date datetime.now().strftime(%Y-%m-%d) # 模拟一些随机但合理的数据 conditions list(WeatherCondition) condition random.choice(conditions) if unit TemperatureUnit.celsius: temp random.uniform(-5, 35) # 摄氏度范围 else: temp random.uniform(23, 95) # 华氏度范围 humidity random.randint(30, 90) wind_speed random.uniform(0, 30) # 构建单日响应 weather_data { location: location, date: date, temperature: round(temp, 1), unit: unit, condition: condition, humidity: humidity, wind_speed: round(wind_speed, 1) } # 模拟未来三天的预报 forecast [] for i in range(1, 4): future_date (datetime.now() timedelta(daysi)).strftime(%Y-%m-%d) forecast.append({ location: location, date: future_date, temperature: round(temp random.uniform(-3, 3), 1), unit: unit, condition: random.choice(conditions), humidity: random.randint(30, 90), wind_speed: round(wind_speed random.uniform(-5, 5), 1) }) weather_data[forecast] forecast return weather_data def get_weather_structured(request_dict: Dict) - WeatherResponse: 获取天气并返回Pydantic验证后的对象 raw_data mock_fetch_weather(**request_dict) # 将主天气和预报数据都转换为Pydantic模型 main_response WeatherResponse(**raw_data) if raw_data.get(forecast): forecast_objs [WeatherResponse(**item) for item in raw_data[forecast]] main_response.forecast forecast_objs return main_response4.5 智能体主逻辑agent.py# agent.py from llm_client import parse_user_query_with_llm, parse_user_query_with_json_mode from weather_tool import get_weather_structured from schemas import WeatherResponse import json class WeatherAgent: def __init__(self, use_function_callingTrue): self.use_function_calling use_function_calling self.fallback_method parse_user_query_with_json_mode def process_query(self, user_query: str) - str: 处理用户查询的主流程。 返回一个JSON字符串给用户。 # 1. 解析用户意图 if self.use_function_calling: request_data parse_user_query_with_llm(user_query) else: request_data self.fallback_method(user_query) if not request_data: error_response {error: 无法理解您的查询请提供明确的城市和日期信息。} return json.dumps(error_response, ensure_asciiFalse, indent2) # 2. 获取天气数据 try: weather_result: WeatherResponse get_weather_structured(request_data) except Exception as e: error_response {error: f查询天气服务时出错: {str(e)}} return json.dumps(error_response, ensure_asciiFalse, indent2) # 3. 将Pydantic模型转换为字典再序列化为JSON # Pydantic的 .dict() 方法可以很好地处理嵌套模型和枚举 result_dict weather_result.dict() # 4. 返回格式化的JSON字符串 return json.dumps(result_dict, ensure_asciiFalse, indent2)4.6 运行与验证main.py# main.py from agent import WeatherAgent def main(): agent WeatherAgent(use_function_callingTrue) test_queries [ 今天北京天气怎么样, 查询纽约明天华氏度的天气情况。, 下周上海的温度用摄氏度。, 这说的什么乱七八糟的 # 测试错误处理 ] for query in test_queries: print(f\n用户查询: 「{query}」) print(- * 40) json_response agent.process_query(query) print(智能体响应 (JSON):) print(json_response) # 你可以在这里添加代码将json_response传递给其他系统 print(- * 40) if __name__ __main__: main()4.7 预期输出示例运行main.py你可能会看到类似以下的输出数据是随机的用户查询: 「今天北京天气怎么样」 ---------------------------------------- 智能体响应 (JSON): { location: 北京, date: 2023-10-27, temperature: 18.5, unit: celsius, condition: sunny, humidity: 65, wind_speed: 12.3, forecast: [ { location: 北京, date: 2023-10-28, temperature: 16.2, unit: celsius, condition: cloudy, humidity: 70, wind_speed: 10.1 }, ... // 更多预报 ] }5. 常见问题与排查思路在实际应用中你可能会遇到以下问题问题现象可能原因排查与解决思路JSON解析失败json.decoder.JSONDecodeError1. 模型输出包含非JSON文本。2. JSON格式错误如单引号、尾随逗号。3. 编码问题如包含不可见字符。1.检查原始输出打印raw_response查看模型实际返回内容。2.强化提示词在系统提示中更严格地要求“只输出JSON”。3.使用后处理实现extract_and_validate_json函数进行清洗和修复。4.降低温度将temperature设为 0 或 0.1。函数调用未被触发1. 模型认为用户输入与函数描述不匹配。2. 函数描述 (description) 不够清晰。3. 使用了tool_choiceauto模型选择了不调用。1.优化函数描述确保description和parameters的描述清晰、覆盖用户可能问法。2.强制调用在简单场景下使用tool_choice{type: function, function: {name: xxx}}强制模型调用特定函数。3.检查用户输入确认输入是否确实包含提取所需的信息。输出字段缺失或多余1. 用户输入未提供必填字段信息。2. JSON Schema 或 Pydantic 模型中required定义有误。3. 模型“幻觉”出不存在的信息。1.设置默认值在Pydantic模型中将非核心字段设为Optional并提供默认值。2.严格模式在JSON Schema中使用additionalProperties: false禁止多余字段。3.后验检查对解析后的数据做业务逻辑校验丢弃或标记可疑数据。本地模型输出格式不稳定1. 本地模型如Llama对指令遵循能力较弱。2. 未在训练时充分学习JSON格式。1.微调模型使用高质量输入输出JSON数据对进行指令微调。2.使用引导生成在生成时通过代码限制输出token例如遇到}后强制停止。3.采用代理模式让一个强的小模型如GPT-3.5专门负责格式转换本地大模型负责内容生成。处理嵌套或复杂JSON时出错1. 模型难以理解复杂的嵌套结构。2. 输出被截断max_tokens设置过小。1.简化Schema尽可能扁平化数据结构。2.分步查询将复杂查询拆分成多个简单查询分步获取数据再组合。3.增加Token限制合理设置max_tokens确保足够输出完整JSON。API响应慢或超时1. 网络问题。2. 模型负载高。3. 生成内容过长。1.设置超时在客户端配置合理的请求超时时间。2.使用流式响应对于长内容考虑使用流式API以提升感知速度。3.异步调用在Web应用中使用异步客户端避免阻塞。6. 最佳实践与工程建议将大模型集成到生产系统时稳定性、可维护性和安全性至关重要。6.1 设计模式采用“解析器-执行器”模式将智能体的工作流清晰分离解析器专门负责与LLM交互将自然语言转换为结构化请求JSON。本文的llm_client模块就是解析器。执行器接收结构化请求调用具体的工具、API或数据库完成实际任务。本文的weather_tool模块就是执行器。编排器控制流程处理错误组合多个执行器的结果。这种模式解耦了不稳定的LLM调用和稳定的业务逻辑便于测试和替换。6.2 验证与防御性编程始终验证输入即使使用函数调用也要用Pydantic等库验证模型返回的参数防止注入攻击或无效数据。设置超时和重试LLM API可能不稳定必须设置网络超时并对可重试的错误如网络抖动实现指数退避重试机制。实现降级方案当主要方法如函数调用失败时应有备选方案如回退到提示词工程后处理。6.3 提示词工程优化提供少量示例在系统提示中提供1-2个高质量的输入输出示例Few-Shot Learning能极大提升模型格式遵循能力。结构化思考链对于复杂任务可以要求模型“先一步一步思考最后输出JSON”这能提高输出的逻辑性和准确性。迭代优化将生产环境中出错的案例收集起来分析是提示词问题、Schema问题还是模型能力问题并持续优化提示词。6.4 性能与成本考量缓存对于相同或相似的查询可以缓存LLM的解析结果避免重复调用节省成本和延迟。模型选型对于简单的格式转换任务gpt-3.5-turbo通常足够且成本更低。对于复杂逻辑或高精度要求再考虑gpt-4。Token管理精心设计提示词和Schema避免不必要的描述减少输入和输出的Token数量。6.5 监控与可观测性在生产环境中务必记录原始用户查询和模型原始输出用于调试和优化提示词。解析后的结构化数据用于业务审计。API延迟和错误率用于性能监控和容量规划。Token使用量用于成本分析。通过综合运用提示词工程、函数调用、输出后处理以及严谨的工程实践你可以极大地提升大模型输出JSON格式的稳定性和可靠性从而构建出真正强大、可集成的AI驱动应用。从简单的数据提取到复杂的智能体工作流结构化的输出是连接大模型智能与传统软件系统的关键桥梁。 大模型稳定输出JSON实战：从提示词到函数调用的生产级方案
在构建基于大模型的智能应用时你是否遇到过这样的困扰你向模型提问期望得到一个结构化的JSON响应以便程序能直接解析但模型却返回了一段夹杂着解释、换行甚至错误括号的自然语言文本这种输出不稳定、格式不统一的问题严重阻碍了大模型与后端系统的无缝集成。本文将深入探讨大模型稳定输出JSON格式的多种实战方案从基础提示词工程到高级函数调用并提供完整的代码示例和避坑指南帮助开发者构建可靠的生产级AI应用。1. 背景与核心概念为什么JSON输出如此重要在传统软件开发中API接口通常返回结构化的数据格式如JSON或XML以便客户端程序能够稳定、高效地解析和处理数据。当我们将大语言模型LLM集成到自动化流程、智能体或业务系统中时同样需要这种稳定性。1.1 结构化输出的价值想象一下你正在开发一个智能客服系统需要从用户对话中提取“投诉类型”、“紧急程度”和“关键时间点”三个字段。如果模型返回“这是一起关于物流延迟的投诉比较紧急用户希望今天下午5点前得到回复”你的程序将难以自动化处理。而如果模型返回{complaint_type: 物流延迟, urgency: 高, deadline: 今天17:00}你的后端代码就可以轻松地将其映射到数据库字段或触发后续工作流。1.2 大模型输出不稳定的根源大语言模型本质上是基于概率生成文本的序列预测模型。它们的训练数据包含了各种格式的文本包括代码、JSON、自然语言描述等。当模型接收到一个指令时它可能会“理解”指令但“执行”偏差它知道要生成JSON但在生成过程中受到概率采样、温度参数等因素影响可能漏掉引号、逗号或括号。过度解释模型倾向于做一个“好老师”在输出JSON前后加上解释性文字如“好的这是您要的JSON数据”。格式混淆对于复杂嵌套结构模型可能混淆数组和对象或者使用单引号而非双引号JSON标准要求双引号。因此让大模型稳定输出JSON核心是通过技术手段约束其生成空间引导其行为更像一个确定性的JSON序列化器。2. 环境准备与版本说明本文将使用 Python 作为主要演示语言并围绕 OpenAI GPT 系列模型和开源模型进行讲解。其他语言如 JavaScript/Node.js的思路完全一致。2.1 基础环境操作系统Windows 10/11, macOS, 或 Linux (如 Ubuntu 20.04)Python 版本3.8 或更高版本包管理工具pip2.2 核心依赖库我们将使用openai库调用商业API使用litellm或transformers库作为连接多种模型包括本地模型的统一入口。pydantic库用于定义严谨的数据结构。# 创建虚拟环境并安装依赖推荐 python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows pip install openai litellm pydantic # 如果需要本地运行模型可能还需要 # pip install transformers torch2.3 模型访问OpenAI API你需要一个有效的 API Key。本文示例将主要使用gpt-3.5-turbo或gpt-4。其他云端模型如 Anthropic Claude, Google Gemini通过litellm可以统一调用。本地模型如 Llama 3, Qwen, ChatGLM 等通过ollama,vllm或transformers库部署和调用。版本说明大模型生态迭代迅速本文重点在于方法论和核心代码逻辑。示例代码基于openai1.0.0和litellm的常见用法具体参数请根据你使用的模型提供商和库的最新文档进行调整。3. 核心方法拆解从提示词到函数调用实现稳定JSON输出主要有四大类方法难度和可靠性逐级递增。3.1 方法一基础提示词工程Prompt Engineering这是最简单直接的方法通过精心设计的提示词来引导模型。核心思路在系统提示System Prompt或用户消息中明确、强硬地指定输出格式。优点零成本无需更改代码逻辑适用于所有模型。缺点稳定性最低模型可能不遵守指令。import openai import json client openai.OpenAI(api_keyyour-api-key) def get_json_via_prompt(user_input: str): response client.chat.completions.create( modelgpt-3.5-turbo, messages[ { role: system, content: 你是一个专业的JSON数据生成器。你必须且只能输出一个完整的、有效的JSON对象不要有任何额外的解释、标记、前缀或后缀。确保使用双引号并确保JSON语法正确。 }, { role: user, content: f请根据以下描述生成JSON。描述{user_input}\n\n输出格式示例{{\key\: \value\}}。现在只输出JSON } ], temperature0.1, # 降低温度减少随机性 max_tokens500 ) raw_output response.choices[0].message.content.strip() # 尝试解析如果失败说明模型没有遵守指令 try: result json.loads(raw_output) return result except json.JSONDecodeError as e: print(fJSON解析失败原始输出{raw_output}) # 此处可以加入后处理清洗逻辑见3.4节 return None # 测试 user_input 提取信息张三男30岁来自北京是一名软件工程师。 result get_json_via_prompt(user_input) if result: print(成功解析JSON:, result)提示词设计要点系统角色定义明确模型角色如“JSON数据生成器”。强制指令使用“必须且只能”、“不要有任何”等强约束词汇。提供示例在消息中直接给出一个简单的格式示例非常有效。结尾强调在最后再次强调“只输出JSON”。调整参数将temperature设置为较低值如0.1使输出更确定。3.2 方法二使用JSON Schema进行约束许多现代大模型API支持在请求中传入response_format参数直接指定输出为JSON并可选地提供一个JSON Schema来定义结构。核心思路利用API的原生支持让模型在生成之初就锁定JSON格式。优点稳定性高是官方推荐做法。缺点并非所有模型和API都支持。def get_json_via_response_format(user_input: str): response client.chat.completions.create( modelgpt-3.5-turbo-1106, # 或 gpt-4-turbo-preview 等支持此功能的模型 messages[ {role: user, content: f根据描述生成用户信息。描述{user_input}} ], response_format{ type: json_object }, # 关键参数要求返回JSON对象 temperature0.1 ) raw_output response.choices[0].message.content # 由于指定了response_format理论上输出一定是可解析的JSON try: return json.loads(raw_output) except json.JSONDecodeError: # 即使有format也应做防御性处理 print(f意外错误输出非JSON: {raw_output}) return None # 更进一步使用JSON Schema定义具体结构OpenAI部分版本支持 def get_json_via_schema(user_input: str): # 注意截至知识截止日期OpenAI的JSON Schema支持可能处于测试阶段请查阅最新文档。 # 以下代码为概念演示。 response client.chat.completions.create( modelgpt-4-turbo-preview, messages[ {role: user, content: f提取用户信息。描述{user_input}} ], response_format{ type: json_schema, json_schema: { name: user_info, schema: { type: object, properties: { name: {type: string}, age: {type: integer}, city: {type: string}, job: {type: string} }, required: [name, age], additionalProperties: False # 禁止输出schema未定义的字段 } } } ) # ... 解析逻辑同上3.3 方法三函数调用Function Calling/工具调用Tool Calls这是目前最强大、最稳定的方法。你定义好一个“函数”包含名称、描述和参数schema模型会识别用户输入是否需要调用此函数并返回一个严格符合参数schema的JSON对象。核心思路将“生成JSON”转化为“调用一个虚拟函数并填充参数”。优点稳定性极高输出完全结构化且意图识别准确。缺点流程稍复杂需要处理“是否调用函数”的逻辑。def extract_info_via_function_calling(user_input: str): # 1. 定义你希望模型“调用”的函数 tools [ { type: function, function: { name: extract_user_info, description: 从文本中提取用户个人信息, parameters: { type: object, properties: { name: {type: string, description: 用户姓名}, gender: {type: string, enum: [男, 女, 其他], description: 性别}, age: {type: integer, description: 年龄}, city: {type: string, description: 所在城市}, occupation: {type: string, description: 职业} }, required: [name, age], additionalProperties: False } } } ] # 2. 发起对话提供工具定义 response client.chat.completions.create( modelgpt-3.5-turbo, messages[{role: user, content: user_input}], toolstools, tool_choiceauto, # 让模型决定是否调用工具 temperature0 ) # 3. 检查模型的响应 message response.choices[0].message if message.tool_calls: # 模型决定调用工具 tool_call message.tool_calls[0] # 假设只调用一个工具 if tool_call.function.name extract_user_info: # 提取出的参数已经是JSON字符串 arguments_str tool_call.function.arguments try: arguments_dict json.loads(arguments_str) return arguments_dict except json.JSONDecodeError: print(f函数参数解析失败: {arguments_str}) return None else: # 模型认为不需要或无法调用工具返回了普通文本 print(f模型未调用函数返回文本: {message.content}) return None # 测试 user_input 帮我记录一下李四28岁在深圳做设计师。 result extract_info_via_function_calling(user_input) print(result) # 输出: {name: 李四, age: 28, city: 深圳, occupation: 设计师} # 注意gender字段未在输入中提及且不在required中所以输出中不存在该字段。3.4 方法四输出后处理与验证作为最后一道防线无论使用哪种方法都应该对模型的原始输出进行清洗和验证。核心思路使用正则表达式或解析器从可能包含额外文本的输出中提取出JSON部分并用json.loads()或pydantic进行验证。import re import json from pydantic import BaseModel, ValidationError def extract_and_validate_json(raw_text: str, pydantic_modelNone): 从原始文本中提取并验证JSON。 :param raw_text: 模型返回的原始文本 :param pydantic_model: 可选的Pydantic模型用于强验证 :return: 解析后的字典或Pydantic模型实例失败则返回None # 方法A使用正则表达式查找最像JSON的部分 # 这个正则匹配以 { 开头以 } 结尾中间内容相对平衡的字符串简单场景 json_pattern r\{[^{}]*\} # 非常简单的匹配对于嵌套JSON会失败 # 更健壮的做法使用栈或现成的库如 json_repair # 方法B尝试直接解析整个文本如果模型遵守指令这应该成功 # 方法C使用 json_repair 等第三方库修复常见的JSON格式错误 # pip install json_repair # from json_repair import repair_json # 这里演示一个简单的尝试先尝试直接解析失败则尝试查找 text raw_text.strip() # 尝试1直接解析 try: data json.loads(text) return validate_with_pydantic(data, pydantic_model) except json.JSONDecodeError: pass # 尝试2查找被标记的JSON块例如被 json ... 包裹 if json in text: parts text.split(json) if len(parts) 1: json_block parts[1].split()[0].strip() try: data json.loads(json_block) return validate_with_pydantic(data, pydantic_model) except json.JSONDecodeError: pass # 如果还找不到可以尝试更复杂的启发式方法或返回None print(f无法从文本中提取有效JSON: {text[:200]}...) return None def validate_with_pydantic(data: dict, model_class): if model_class is None: return data try: # 使用Pydantic模型进行数据验证和类型转换 instance model_class(**data) return instance except ValidationError as e: print(fPydantic验证失败: {e}) return None # 定义一个Pydantic模型 class UserInfo(BaseModel): name: str age: int city: str | None None # 可选字段 job: str | None None # 使用后处理 raw_output_from_model 用户信息如下\njson\n{\name\: \王五\, \age\: 35, \city\: \上海\}\n processed_data extract_and_validate_json(raw_output_from_model, UserInfo) if processed_data: print(f验证通过的数据: {processed_data}) # 如果是Pydantic模型可以方便地访问属性 if isinstance(processed_data, UserInfo): print(f姓名: {processed_data.name})4. 完整实战案例构建一个稳定的天气查询智能体让我们综合运用以上方法构建一个能稳定返回JSON格式天气信息的智能体。该智能体接收用户关于天气的自然语言查询并返回结构化的天气数据。4.1 项目结构与设计weather_agent/ ├── config.py # 配置文件存放API Key等 ├── schemas.py # Pydantic数据模型定义 ├── llm_client.py # 大模型客户端封装 ├── weather_tool.py # 模拟的天气查询工具 ├── agent.py # 智能体主逻辑 └── main.py # 主程序入口4.2 定义数据结构schemas.py使用Pydantic确保输入输出的数据形状和类型。# schemas.py from pydantic import BaseModel, Field from typing import Optional, List from enum import Enum class TemperatureUnit(str, Enum): celsius celsius fahrenheit fahrenheit class WeatherCondition(str, Enum): sunny sunny cloudy cloudy rainy rainy snowy snowy windy windy class WeatherRequest(BaseModel): 用户查询解析后的结构化请求 location: str Field(description查询的城市或地区名称如‘北京’、‘New York’) date: Optional[str] Field(defaultNone, description查询的日期格式‘YYYY-MM-DD’默认为今天) unit: TemperatureUnit Field(defaultTemperatureUnit.celsius, description温度单位) class WeatherResponse(BaseModel): 返回给用户的标准化天气响应 location: str date: str temperature: float Field(description温度值) unit: TemperatureUnit condition: WeatherCondition humidity: Optional[int] Field(description湿度百分比, ge0, le100) wind_speed: Optional[float] Field(description风速公里/小时, ge0) forecast: Optional[List[WeatherResponse]] Field(defaultNone, description未来几天的预报)4.3 封装LLM客户端与函数调用llm_client.py# llm_client.py import json from openai import OpenAI from typing import Dict, Any from schemas import WeatherRequest import config client OpenAI(api_keyconfig.OPENAI_API_KEY) def create_weather_tool(): 定义天气查询‘工具’函数 # 利用WeatherRequest的schema作为函数参数schema schema_dict WeatherRequest.schema() return { type: function, function: { name: get_weather, description: 根据地点和日期查询天气信息, parameters: schema_dict } } def parse_user_query_with_llm(user_query: str) - Dict[str, Any]: 使用函数调用解析用户自然语言查询。 返回解析后的参数字典。 tools [create_weather_tool()] response client.chat.completions.create( modelgpt-3.5-turbo, messages[ {role: system, content: 你是一个天气查询助手。请从用户的问题中提取查询地点、日期和温度单位。如果用户未指定日期默认为今天未指定单位默认为摄氏度。}, {role: user, content: user_query} ], toolstools, tool_choice{type: function, function: {name: get_weather}}, # 强制调用此工具 temperature0.0, # 设置为0以获得最确定性的输出 max_tokens500 ) message response.choices[0].message if message.tool_calls: tool_call message.tool_calls[0] if tool_call.function.name get_weather: args_json tool_call.function.arguments try: args_dict json.loads(args_json) # 使用Pydantic模型进行验证和类型转换 validated_request WeatherRequest(**args_dict) return validated_request.dict() # 返回字典 except (json.JSONDecodeError, Exception) as e: print(f解析或验证函数参数失败: {e}, 原始参数: {args_json}) return None print(f模型未返回预期的工具调用。响应: {message.content}) return None # 备用方案使用response_format如果模型支持 def parse_user_query_with_json_mode(user_query: str): 使用JSON模式解析查询作为备选方案 response client.chat.completions.create( modelgpt-3.5-turbo-1106, messages[ {role: system, content: 你输出JSON。从用户问题中提取‘location’、‘date’默认今天、‘unit’默认celsius。}, {role: user, content: user_query} ], response_format{type: json_object}, temperature0.0 ) raw_json response.choices[0].message.content try: data json.loads(raw_json) validated_request WeatherRequest(**data) return validated_request.dict() except Exception as e: print(fJSON模式解析失败: {e}) return None4.4 模拟天气查询工具weather_tool.py# weather_tool.py import random from datetime import datetime, timedelta from schemas import WeatherResponse, WeatherCondition, TemperatureUnit from typing import Dict def mock_fetch_weather(location: str, date: str None, unit: TemperatureUnit TemperatureUnit.celsius) - Dict: 模拟一个天气API的调用。 在实际项目中这里会调用真实的天气服务API如OpenWeatherMap。 if date is None: date datetime.now().strftime(%Y-%m-%d) # 模拟一些随机但合理的数据 conditions list(WeatherCondition) condition random.choice(conditions) if unit TemperatureUnit.celsius: temp random.uniform(-5, 35) # 摄氏度范围 else: temp random.uniform(23, 95) # 华氏度范围 humidity random.randint(30, 90) wind_speed random.uniform(0, 30) # 构建单日响应 weather_data { location: location, date: date, temperature: round(temp, 1), unit: unit, condition: condition, humidity: humidity, wind_speed: round(wind_speed, 1) } # 模拟未来三天的预报 forecast [] for i in range(1, 4): future_date (datetime.now() timedelta(daysi)).strftime(%Y-%m-%d) forecast.append({ location: location, date: future_date, temperature: round(temp random.uniform(-3, 3), 1), unit: unit, condition: random.choice(conditions), humidity: random.randint(30, 90), wind_speed: round(wind_speed random.uniform(-5, 5), 1) }) weather_data[forecast] forecast return weather_data def get_weather_structured(request_dict: Dict) - WeatherResponse: 获取天气并返回Pydantic验证后的对象 raw_data mock_fetch_weather(**request_dict) # 将主天气和预报数据都转换为Pydantic模型 main_response WeatherResponse(**raw_data) if raw_data.get(forecast): forecast_objs [WeatherResponse(**item) for item in raw_data[forecast]] main_response.forecast forecast_objs return main_response4.5 智能体主逻辑agent.py# agent.py from llm_client import parse_user_query_with_llm, parse_user_query_with_json_mode from weather_tool import get_weather_structured from schemas import WeatherResponse import json class WeatherAgent: def __init__(self, use_function_callingTrue): self.use_function_calling use_function_calling self.fallback_method parse_user_query_with_json_mode def process_query(self, user_query: str) - str: 处理用户查询的主流程。 返回一个JSON字符串给用户。 # 1. 解析用户意图 if self.use_function_calling: request_data parse_user_query_with_llm(user_query) else: request_data self.fallback_method(user_query) if not request_data: error_response {error: 无法理解您的查询请提供明确的城市和日期信息。} return json.dumps(error_response, ensure_asciiFalse, indent2) # 2. 获取天气数据 try: weather_result: WeatherResponse get_weather_structured(request_data) except Exception as e: error_response {error: f查询天气服务时出错: {str(e)}} return json.dumps(error_response, ensure_asciiFalse, indent2) # 3. 将Pydantic模型转换为字典再序列化为JSON # Pydantic的 .dict() 方法可以很好地处理嵌套模型和枚举 result_dict weather_result.dict() # 4. 返回格式化的JSON字符串 return json.dumps(result_dict, ensure_asciiFalse, indent2)4.6 运行与验证main.py# main.py from agent import WeatherAgent def main(): agent WeatherAgent(use_function_callingTrue) test_queries [ 今天北京天气怎么样, 查询纽约明天华氏度的天气情况。, 下周上海的温度用摄氏度。, 这说的什么乱七八糟的 # 测试错误处理 ] for query in test_queries: print(f\n用户查询: 「{query}」) print(- * 40) json_response agent.process_query(query) print(智能体响应 (JSON):) print(json_response) # 你可以在这里添加代码将json_response传递给其他系统 print(- * 40) if __name__ __main__: main()4.7 预期输出示例运行main.py你可能会看到类似以下的输出数据是随机的用户查询: 「今天北京天气怎么样」 ---------------------------------------- 智能体响应 (JSON): { location: 北京, date: 2023-10-27, temperature: 18.5, unit: celsius, condition: sunny, humidity: 65, wind_speed: 12.3, forecast: [ { location: 北京, date: 2023-10-28, temperature: 16.2, unit: celsius, condition: cloudy, humidity: 70, wind_speed: 10.1 }, ... // 更多预报 ] }5. 常见问题与排查思路在实际应用中你可能会遇到以下问题问题现象可能原因排查与解决思路JSON解析失败json.decoder.JSONDecodeError1. 模型输出包含非JSON文本。2. JSON格式错误如单引号、尾随逗号。3. 编码问题如包含不可见字符。1.检查原始输出打印raw_response查看模型实际返回内容。2.强化提示词在系统提示中更严格地要求“只输出JSON”。3.使用后处理实现extract_and_validate_json函数进行清洗和修复。4.降低温度将temperature设为 0 或 0.1。函数调用未被触发1. 模型认为用户输入与函数描述不匹配。2. 函数描述 (description) 不够清晰。3. 使用了tool_choiceauto模型选择了不调用。1.优化函数描述确保description和parameters的描述清晰、覆盖用户可能问法。2.强制调用在简单场景下使用tool_choice{type: function, function: {name: xxx}}强制模型调用特定函数。3.检查用户输入确认输入是否确实包含提取所需的信息。输出字段缺失或多余1. 用户输入未提供必填字段信息。2. JSON Schema 或 Pydantic 模型中required定义有误。3. 模型“幻觉”出不存在的信息。1.设置默认值在Pydantic模型中将非核心字段设为Optional并提供默认值。2.严格模式在JSON Schema中使用additionalProperties: false禁止多余字段。3.后验检查对解析后的数据做业务逻辑校验丢弃或标记可疑数据。本地模型输出格式不稳定1. 本地模型如Llama对指令遵循能力较弱。2. 未在训练时充分学习JSON格式。1.微调模型使用高质量输入输出JSON数据对进行指令微调。2.使用引导生成在生成时通过代码限制输出token例如遇到}后强制停止。3.采用代理模式让一个强的小模型如GPT-3.5专门负责格式转换本地大模型负责内容生成。处理嵌套或复杂JSON时出错1. 模型难以理解复杂的嵌套结构。2. 输出被截断max_tokens设置过小。1.简化Schema尽可能扁平化数据结构。2.分步查询将复杂查询拆分成多个简单查询分步获取数据再组合。3.增加Token限制合理设置max_tokens确保足够输出完整JSON。API响应慢或超时1. 网络问题。2. 模型负载高。3. 生成内容过长。1.设置超时在客户端配置合理的请求超时时间。2.使用流式响应对于长内容考虑使用流式API以提升感知速度。3.异步调用在Web应用中使用异步客户端避免阻塞。6. 最佳实践与工程建议将大模型集成到生产系统时稳定性、可维护性和安全性至关重要。6.1 设计模式采用“解析器-执行器”模式将智能体的工作流清晰分离解析器专门负责与LLM交互将自然语言转换为结构化请求JSON。本文的llm_client模块就是解析器。执行器接收结构化请求调用具体的工具、API或数据库完成实际任务。本文的weather_tool模块就是执行器。编排器控制流程处理错误组合多个执行器的结果。这种模式解耦了不稳定的LLM调用和稳定的业务逻辑便于测试和替换。6.2 验证与防御性编程始终验证输入即使使用函数调用也要用Pydantic等库验证模型返回的参数防止注入攻击或无效数据。设置超时和重试LLM API可能不稳定必须设置网络超时并对可重试的错误如网络抖动实现指数退避重试机制。实现降级方案当主要方法如函数调用失败时应有备选方案如回退到提示词工程后处理。6.3 提示词工程优化提供少量示例在系统提示中提供1-2个高质量的输入输出示例Few-Shot Learning能极大提升模型格式遵循能力。结构化思考链对于复杂任务可以要求模型“先一步一步思考最后输出JSON”这能提高输出的逻辑性和准确性。迭代优化将生产环境中出错的案例收集起来分析是提示词问题、Schema问题还是模型能力问题并持续优化提示词。6.4 性能与成本考量缓存对于相同或相似的查询可以缓存LLM的解析结果避免重复调用节省成本和延迟。模型选型对于简单的格式转换任务gpt-3.5-turbo通常足够且成本更低。对于复杂逻辑或高精度要求再考虑gpt-4。Token管理精心设计提示词和Schema避免不必要的描述减少输入和输出的Token数量。6.5 监控与可观测性在生产环境中务必记录原始用户查询和模型原始输出用于调试和优化提示词。解析后的结构化数据用于业务审计。API延迟和错误率用于性能监控和容量规划。Token使用量用于成本分析。通过综合运用提示词工程、函数调用、输出后处理以及严谨的工程实践你可以极大地提升大模型输出JSON格式的稳定性和可靠性从而构建出真正强大、可集成的AI驱动应用。从简单的数据提取到复杂的智能体工作流结构化的输出是连接大模型智能与传统软件系统的关键桥梁。