1. 项目概述为什么我们需要“结构化输出”如果你最近在折腾大语言模型不管是调用 OpenAI 的 API还是玩转开源的 Llama、Qwen大概率都遇到过这种场景你满怀期待地向模型抛出一个问题比如“给我列出接下来一周的健身计划包含日期、项目、时长”结果模型确实给了你一段文字但格式五花八门。有时候是 Markdown 列表有时候是纯文本段落有时候甚至把日期和项目混在一起。当你试图写个程序自动解析这段回复提取出结构化的数据比如一个 JSON 数组时崩溃就开始了——正则表达式写到头秃边界情况多到怀疑人生模型稍微“自由发挥”一下你的解析逻辑就全盘失效。这就是“解析崩溃”Parse Hell的典型困境。我们利用大模型的强大生成能力却卡在了最后一步把非结构化的自然语言可靠地转换回程序可用的结构化数据。这就像雇了一个天才设计师但他交稿时把设计图、素材、说明全混在一张纸上你需要手动裁剪拼接效率低下且极易出错。“结构化输出”Structured Outputs技术就是为了彻底解决这个问题而生。它不是一个单一的工具而是一套让大模型“听话”地按照预定格式如 JSON、YAML、XML 甚至是一个遵循特定范式的类来生成内容的技术方案。其核心思想是在给模型的指令Prompt中就明确约定好输出的“数据结构”引导甚至强制模型在这个框架内进行创作。这不仅仅是让输出“好看”更是为了实现人机交互与机机交互的可靠桥梁。对于构建基于大模型的自动化流程、Agent智能体、复杂工具调用等场景结构化输出是必不可少的基础设施。简单来说它让模型的输出从“散文”变成了“填空题”或“选择题”极大地提升了后续处理的确定性和自动化程度。接下来我将拆解这项技术的核心原理、主流实现方案、实操细节以及我趟过的那些坑。2. 核心需求解析从“自由发挥”到“按图施工”在深入技术细节前我们得先搞清楚为什么简单的文本提示Prompt做不到可靠的结构化输出以及我们对结构化输出的真实需求到底是什么2.1 传统提示工程的局限性过去我们依赖精巧的提示词来约束模型。例如请以 JSON 格式输出包含以下字段date (字符串格式 YYYY-MM-DD), workout (字符串), duration_minutes (整数)。示例{date: 2023-10-27, workout: 慢跑, duration_minutes: 30}这种方法有时有效但存在几个致命弱点遵从性不稳定模型特别是较小或未经专门调优的模型可能会忽略格式要求或在 JSON 中插入额外的解释性文字。格式错误生成的 JSON 可能缺少引号、有尾随逗号、或键名不一致导致JSON.parse()直接抛出异常。内容漂移即使格式正确字段的值可能不符合要求比如duration_minutes输出成了 “三十” 而不是 30。复杂结构无力对于嵌套对象、数组的数组、联合类型等复杂结构纯文本提示的约束力急剧下降。这些不确定性使得在生产环境中集成大模型变得风险极高。每一次 API 调用都像一次赌博你需要编写复杂的后处理代码和重试逻辑来兜底。2.2 结构化输出的核心需求清单一个理想的结构化输出方案应该满足以下需求强约束性能严格定义输出的数据类型字符串、数字、布尔值、枚举、结构对象、数组和可选性。高可靠性保证输出 100% 符合预定格式可直接被标准解析器如 JSON 解析器处理无需清洗。开发友好定义模式Schema的方式应该直观最好能与编程语言中的类型定义如 TypeScript Interface、Python Pydantic Model无缝衔接。灵活性在约束框架内模型仍保有生成内容的创造性。我们约束的是“容器”而非完全限制“内容”。跨模型兼容方案应尽可能适用于不同的主流模型而不是绑定某个特定供应商。理解了这些需求我们就能更好地评估接下来要介绍的各种技术方案。3. 技术方案全景图三大主流流派详解目前实现结构化输出的技术路径主要分为三大流派基于提示工程的“软约束”、基于模型微调的“硬约束”、以及当前最热门的“函数调用/工具调用与 JSON 模式”。每种方案各有优劣适用场景也不同。3.1 流派一提示工程增强法这是入门成本最低的方法不依赖任何特殊 API 或模型微调核心在于优化你的提示词。核心技巧示例驱动Few-Shot Learning在提示词中提供多个清晰、正确的输入-输出示例。这是最有效的手段之一。示例要覆盖各种边界情况。格式强化描述不仅说“输出 JSON”还要详细描述。例如“你必须输出一个有效的、可直接被JSON.parse()解析的JSON 对象不要有任何额外的 markdown 代码块标记或解释文字。”角色扮演给模型赋予一个严格遵守规则的角色如“你是一个严格的 JSON API 终端只返回纯 JSON不返回任何其他文本。”后处理兜底在代码中尝试解析后如果失败可以提取可能包含 JSON 的代码块如json ...或进行简单的字符串修复如移除首尾空白、匹配第一个{到最后一个}之间的内容。实操示例Pythonimport json import re import openai def get_structured_output_with_retry(prompt, max_retries3): system_msg 你是一个数据格式化助手。用户会提出需求你必须返回一个严格符合给定JSON Schema的对象且不要包含任何其他解释文字。 user_msg f 需求{prompt} 请严格按照以下JSON Schema输出 {{ type: object, properties: {{ plan: {{ type: array, items: {{ type: object, properties: {{ date: {{ type: string, format: date }}, workout: {{ type: string }}, duration_minutes: {{ type: integer }} }}, required: [date, workout, duration_minutes] }} }} }}, required: [plan] }} 示例正确输出{{plan: [{{date: 2023-10-27, workout: 慢跑, duration_minutes: 30}}]}} for _ in range(max_retries): response openai.ChatCompletion.create( modelgpt-3.5-turbo, messages[{role: system, content: system_msg}, {role: user, content: user_msg}], temperature0.1 # 降低随机性 ) raw_output response.choices[0].message.content # 尝试提取JSON json_match re.search(r\{.*\}, raw_output, re.DOTALL) if json_match: try: return json.loads(json_match.group()) except json.JSONDecodeError: continue # 解析失败重试 raise ValueError(Failed to get valid JSON after retries.) # 使用 try: result get_structured_output_with_retry(制定一个为期三天的健身计划) print(json.dumps(result, indent2, ensure_asciiFalse)) except ValueError as e: print(e)注意提示工程法本质上是“概率性合规”无法保证 100% 成功。它适用于对可靠性要求不是极端高、或调用成本需要严格控制的中低复杂度场景。温度temperature参数建议设为较低值如0.1-0.3以减少随机性。3.2 流派二模型微调法这是最根本但也最“重”的解决方案。通过在自己的任务数据上对基础模型进行有监督微调SFT让模型从底层学会遵循特定的输出格式。操作流程数据准备收集或生成大量的(输入指令 符合格式的输出)配对数据。输出必须是严格符合你目标格式如特定 JSON 结构的字符串。模型训练使用 LoRA、QLoRA 等参数高效微调技术在基础模型如 Llama 3、Qwen 2.5上进行训练。部署推理使用微调后的模型进行推理理论上它会对指定的格式有极强的遵从性。优劣分析优势格式遵从性极高一旦训好一劳永逸。可以定制非常复杂和独特的格式。劣势成本高数据准备、训练资源、周期长、不灵活格式一旦变化可能需要重新训练或数据。属于“为了格式训练一个专属模型”性价比通常不高除非格式是你应用的核心且极其复杂。适用场景输出格式是业务核心且极度稳定不变同时有海量高质量配对数据可供训练。对于大多数应用来说这有点“杀鸡用牛刀”。3.3 流派三函数调用与JSON模式当前主流这是目前各大厂商主推、也是效果最好的方案。其核心是在 API 调用层面将输出结构作为“约束条件”直接传递给模型。它又细分为两种实现方式3.3.1 函数调用Function CallingOpenAI 在 2023 年中期率先引入。你定义一系列“函数”描述其名称、参数说明和参数 JSON Schema模型在理解用户请求后可以选择调用其中一个或多个函数并以符合该函数参数 Schema 的 JSON 对象作为输出。虽然名为“函数调用”但其本质是引导模型输出结构化 JSON 的绝佳机制。后来AnthropicClaude的“工具使用”Tool Use、Google Gemini 的“函数调用”都采用了类似理念。3.3.2 JSON 模式JSON Mode这是对函数调用的简化与补充。OpenAI 在gpt-3.5-turbo-1106及更新版本中引入了response_format参数。当你设置{ type: json_object }时模型会强制以 JSON 对象格式输出。但这只保证了输出是 JSON不保证内部结构。为了进一步约束内部结构你需要结合详细的提示词描述 JSON Schema。而像 Anthropic 的 Claude 3 系列则支持更强大的response_schema参数允许你直接传入一个 JSON Schema 对象来定义输出结构约束力更强。这是当前的重点和推荐方案因为它平衡了可靠性、灵活性和开发便利性。接下来我们将深入其实操细节。4. 实战使用OpenAI API实现可靠结构化输出让我们以最普及的 OpenAI API 为例展示如何在实际项目中运用函数调用和 JSON 模式。4.1 基于函数调用的结构化输出函数调用的核心思路是你告诉模型“你有什么函数可用每个函数需要什么参数”模型在思考后会决定是否调用以及调用时传入什么参数。这个“传入的参数”就是一个完美的结构化输出。步骤拆解定义工具函数列表这是一个数组每个元素描述一个函数。关键部分是parameters它遵循 JSON Schema 标准。发起聊天补全请求在tools参数中传入上述列表。将tool_choice设置为auto让模型决定或指定某个函数如{type: function, function: {name: your_function_name}}来强制调用。解析模型响应模型的响应会包含一个tool_calls字段其中就有它“决定调用”的函数名和参数一个 JSON 对象。完整代码示例import openai import json from typing import List, Optional client openai.OpenAI(api_keyyour-api-key) # 1. 定义我们期望的输出结构以“函数参数”的形式描述 tools [ { type: function, function: { name: output_fitness_plan, description: 输出一份健身计划, parameters: { type: object, properties: { plan: { type: array, description: 健身计划列表, items: { type: object, properties: { date: { type: string, description: 训练日期YYYY-MM-DD格式 }, workout_type: { type: string, description: 训练类型, enum: [有氧, 力量, 柔韧, 休息] # 甚至可以定义枚举 }, workout_name: {type: string}, duration_minutes: {type: integer, minimum: 10}, intensity: { type: string, enum: [低, 中, 高], default: 中 # 提供默认值 } }, required: [date, workout_type, workout_name, duration_minutes] # 必填字段 } }, summary: { type: object, properties: { total_days: {type: integer}, total_minutes: {type: integer}, focus_area: {type: string} } } }, required: [plan] } } } ] # 2. 发起请求强制模型使用我们定义的这个工具 response client.chat.completions.create( modelgpt-3.5-turbo, # 或 gpt-4-turbo messages[ {role: user, content: 为我制定一个为期5天的综合健身计划包含有氧和力量训练。} ], toolstools, tool_choice{type: function, function: {name: output_fitness_plan}}, # 强制调用指定函数 temperature0.1 ) # 3. 解析响应 message response.choices[0].message if message.tool_calls: tool_call message.tool_calls[0] # 假设只调用一个函数 if tool_call.function.name output_fitness_plan: # 这里得到的 arguments 已经是符合我们 Schema 的 JSON 字符串了 structured_output json.loads(tool_call.function.arguments) print(json.dumps(structured_output, indent2, ensure_asciiFalse)) else: print(模型没有调用工具。)关键优势100% 格式合规输出的arguments一定是一个能被json.loads解析的字符串并且其结构完全符合你定义的parametersSchema。OpenAI 的 API 层会对此进行保证。类型安全你可以定义字段类型、枚举值、默认值、必填项甚至嵌套结构。意图明确模型通过“选择调用哪个函数”来表达它对用户请求的理解这本身也是一种结构化信息。实操心得即使你当前不需要“函数调用”这个语义也可以只定义一个函数比如叫format_output把它当作一个纯粹的“结构化输出模板”来用。tool_choice参数强制模型使用它这样就变相实现了强约束的结构化输出。4.2 基于JSON模式response_format的简化方案如果你觉得定义函数有点重且使用的是较新的模型如gpt-3.5-turbo-1106,gpt-4-turbo-preview,gpt-4o可以使用更直接的 JSON 模式。response client.chat.completions.create( modelgpt-3.5-turbo-1106, # 注意必须是指定版本及之后的模型 messages[ {role: system, content: 你总是以有效的 JSON 对象回应。}, {role: user, content: 为我制定一个为期5天的综合健身计划以JSON格式输出包含一个plan数组每个元素有date、workout、duration_minutes字段。} ], response_format{type: json_object}, # 关键参数 temperature0.1 ) output_text response.choices[0].message.content # 此时 output_text 应该是一个纯 JSON 字符串可以直接解析 try: plan json.loads(output_text) print(json.dumps(plan, indent2)) except json.JSONDecodeError as e: print(fJSON解析失败但概率极低: {e}) print(f原始输出: {output_text})注意response_format{type: json_object}只保证输出是合法的 JSON 对象不保证内部字段结构。因此系统提示System Message和用户提示User Message中对 JSON 结构的描述至关重要需要与函数调用中的parameters一样详细。两者结合使用效果最佳。5. 开源模型与本地部署的结构化输出方案如果你在使用开源模型如 Llama 3、Qwen、Mixtral进行本地部署或通过兼容 API如 vLLM、Ollama调用同样可以实现结构化输出。主流方案有以下几种5.1 使用支持“工具调用”的推理框架许多推理服务器和库已经集成了类似 OpenAI 函数调用的功能。vLLM通过其 OpenAI 兼容的 API 服务器可以接收tools和tool_choice参数。前提是你使用的模型本身支持工具调用例如一些经过微调以支持工具调用的 Llama 版本。Llama.cpp其server模式也提供了与 OpenAI 兼容的 API但工具调用的支持程度取决于模型本身和编译选项。第三方 API 服务如 Together AI、Fireworks AI 等它们提供了多种开源模型的托管服务其中许多模型已支持工具调用其 API 与 OpenAI 高度兼容。操作流程与第4节中的OpenAI示例几乎完全相同只需更换 API Base URL 和 API Key。你需要查阅你所使用模型和推理框架的文档确认其对工具调用的支持情况。5.2 使用指导生成Guidance或约束解码Constrained Decoding库这是更底层、更强大的方法尤其适用于模型本身没有内置工具调用能力的情况。它通过在生成文本的每个步骤施加规则来确保输出符合特定格式如 JSON、正则表达式。Guidance一个微软推出的库允许你使用混合提示词和生成语法来引导模型。你可以定义一个 JSON 模板让模型在特定位置生成内容。Outlines/jsonformer这类库使用“约束解码”技术。它们在模型生成 token 时实时检查并过滤掉那些会导致最终结果不符合预定格式如 JSON Schema的 token。这能从根源上保证输出的语法正确性。以 Outlines 为例# 示例概念非可运行代码 import outlines from pydantic import BaseModel from typing import List # 1. 用 Pydantic 定义你想要的结构 class WorkoutItem(BaseModel): date: str workout: str duration_minutes: int class FitnessPlan(BaseModel): plan: List[WorkoutItem] # 2. 创建模型并约束其生成符合 FitnessPlan Schema 的 JSON model outlines.models.transformers(meta-llama/Llama-3-8B-Instruct) generator outlines.generate.json(model, FitnessPlan) # 关键绑定Schema # 3. 生成 prompt 制定一个3天的健身计划。 result generator(prompt) # result 直接是一个 FitnessPlan 实例 print(result.plan[0].date) # 直接访问属性类型安全这种方法优势巨大绝对可靠输出 100% 符合 Pydantic 模型直接就是 Python 对象无需解析和验证。开发体验极佳使用熟悉的 Pydantic 定义 Schema类型提示和自动补全全都有。适用性广不依赖模型本身的特殊能力只要是一个文本生成模型理论上都可以施加约束。主要挑战性能开销约束解码需要在生成时进行额外的计算和检查可能会降低推理速度。集成复杂度需要将推理管道与这些库集成相比直接调用 API 更复杂。6. 避坑指南与最佳实践在实际项目中大规模应用结构化输出我积累了一些血泪教训和有效实践。6.1 常见问题与排查技巧模型返回了tool_calls但arguments不是合法 JSON原因极其罕见但可能发生在早期模型或提示词冲突时。OpenAI 的最新模型基本杜绝了此问题。排查首先检查tool_call.function.arguments字符串。用json.loads捕获异常。如果失败可以尝试用ast.literal_eval安全或简单正则修复如补全缺失引号但更建议记录日志并触发重试或降级流程。模型不调用我期望的函数tool_calls为空原因模型认为用户请求与任何已定义函数的功能不匹配。解决检查函数描述function.description是否清晰准确地描述了该函数的用途确保它能被模型理解。优化用户查询用户的问题是否足够明确有时需要引导用户提问或在系统提示中说明“请根据以下可用功能来回答”。使用tool_choice参数如果你确定应该调用某个函数直接使用tool_choice强制指定而不是设为auto。生成的 JSON 值类型不对比如应该是数字却成了字符串原因JSON Schema 中定义了type: integer但模型生成时可能还是写了带引号的数字。这在复杂提示或温度较高时可能出现。解决降低温度将temperature设为 0.1 或 0。强化示例在function.parameters的description中强调类型或在系统/用户消息中提供更明确的示例。后处理转换在解析 JSON 后增加一层数据清洗和类型转换的代码作为最终防线。处理可选字段和空值null问题如果 Schema 中某个字段不是required模型有时会直接省略该字段有时会生成field: null。实践在代码中处理时使用.get()方法安全地访问可选字段并做好默认值处理。明确在 Schema 描述中说明“如果无关请省略此字段”或“如果无请设为 null”。6.2 架构设计与最佳实践Schema 设计要严谨且可扩展使用 JSON Schema 或 Pydantic 等工具正确定义 Schema。字段描述description要尽可能详细这是模型理解字段含义的主要依据。为未来留出扩展空间比如在根对象中加入_version字段或使用additionalProperties: false来严格限制字段防止模型“自由发挥”添加未定义的字段。实现健壮的客户端封装不要在每个业务代码里都写一遍 API 调用和错误处理。封装一个统一的get_structured_response函数内部处理重试、降级如结构化失败后回退到文本提取、日志记录和监控。考虑使用指数退避策略进行重试特别是对于偶发的格式错误。监控与评估记录每次 API 调用的输入、输出、token 用量和耗时。定义并监控关键指标结构化输出成功率JSON 解析成功且符合 Schema 的比例。这是衡量你提示词和 Schema 设计质量的核心指标。对失败案例进行抽样分析持续优化你的提示词和 Schema 描述。成本与延迟权衡函数调用/JSON 模式通常会消耗更多 token因为 Schema 描述本身也计入输入 token并可能带来轻微延迟。对于极其简单、固定的结构如“返回是或否”有时一个严格的提示词如“只回答‘是’或‘否’”可能更经济。但对于复杂结构为可靠性付出的 token 成本是值得的。组合使用多种技术主方案使用函数调用或 JSON 模式获得高可靠性输出。降级方案当主方案失败如模型不配合时回退到增强提示词后处理提取的方案。验证层无论哪种方案最终得到数据后都应用 Pydantic 模型进行二次验证和类型转换确保进入业务逻辑的数据是绝对干净的。从我自己的项目经验来看一旦将核心流程切换到结构化输出代码中那些丑陋的正则表达式和脆弱的文本解析逻辑可以删除大半整个系统的稳定性和可维护性会有质的提升。它让大模型从“一个聪明的聊天伙伴”真正变成了“一个可靠的软件组件”。
1. 项目概述为什么我们需要“结构化输出”如果你最近在折腾大语言模型不管是调用 OpenAI 的 API还是玩转开源的 Llama、Qwen大概率都遇到过这种场景你满怀期待地向模型抛出一个问题比如“给我列出接下来一周的健身计划包含日期、项目、时长”结果模型确实给了你一段文字但格式五花八门。有时候是 Markdown 列表有时候是纯文本段落有时候甚至把日期和项目混在一起。当你试图写个程序自动解析这段回复提取出结构化的数据比如一个 JSON 数组时崩溃就开始了——正则表达式写到头秃边界情况多到怀疑人生模型稍微“自由发挥”一下你的解析逻辑就全盘失效。这就是“解析崩溃”Parse Hell的典型困境。我们利用大模型的强大生成能力却卡在了最后一步把非结构化的自然语言可靠地转换回程序可用的结构化数据。这就像雇了一个天才设计师但他交稿时把设计图、素材、说明全混在一张纸上你需要手动裁剪拼接效率低下且极易出错。“结构化输出”Structured Outputs技术就是为了彻底解决这个问题而生。它不是一个单一的工具而是一套让大模型“听话”地按照预定格式如 JSON、YAML、XML 甚至是一个遵循特定范式的类来生成内容的技术方案。其核心思想是在给模型的指令Prompt中就明确约定好输出的“数据结构”引导甚至强制模型在这个框架内进行创作。这不仅仅是让输出“好看”更是为了实现人机交互与机机交互的可靠桥梁。对于构建基于大模型的自动化流程、Agent智能体、复杂工具调用等场景结构化输出是必不可少的基础设施。简单来说它让模型的输出从“散文”变成了“填空题”或“选择题”极大地提升了后续处理的确定性和自动化程度。接下来我将拆解这项技术的核心原理、主流实现方案、实操细节以及我趟过的那些坑。2. 核心需求解析从“自由发挥”到“按图施工”在深入技术细节前我们得先搞清楚为什么简单的文本提示Prompt做不到可靠的结构化输出以及我们对结构化输出的真实需求到底是什么2.1 传统提示工程的局限性过去我们依赖精巧的提示词来约束模型。例如请以 JSON 格式输出包含以下字段date (字符串格式 YYYY-MM-DD), workout (字符串), duration_minutes (整数)。示例{date: 2023-10-27, workout: 慢跑, duration_minutes: 30}这种方法有时有效但存在几个致命弱点遵从性不稳定模型特别是较小或未经专门调优的模型可能会忽略格式要求或在 JSON 中插入额外的解释性文字。格式错误生成的 JSON 可能缺少引号、有尾随逗号、或键名不一致导致JSON.parse()直接抛出异常。内容漂移即使格式正确字段的值可能不符合要求比如duration_minutes输出成了 “三十” 而不是 30。复杂结构无力对于嵌套对象、数组的数组、联合类型等复杂结构纯文本提示的约束力急剧下降。这些不确定性使得在生产环境中集成大模型变得风险极高。每一次 API 调用都像一次赌博你需要编写复杂的后处理代码和重试逻辑来兜底。2.2 结构化输出的核心需求清单一个理想的结构化输出方案应该满足以下需求强约束性能严格定义输出的数据类型字符串、数字、布尔值、枚举、结构对象、数组和可选性。高可靠性保证输出 100% 符合预定格式可直接被标准解析器如 JSON 解析器处理无需清洗。开发友好定义模式Schema的方式应该直观最好能与编程语言中的类型定义如 TypeScript Interface、Python Pydantic Model无缝衔接。灵活性在约束框架内模型仍保有生成内容的创造性。我们约束的是“容器”而非完全限制“内容”。跨模型兼容方案应尽可能适用于不同的主流模型而不是绑定某个特定供应商。理解了这些需求我们就能更好地评估接下来要介绍的各种技术方案。3. 技术方案全景图三大主流流派详解目前实现结构化输出的技术路径主要分为三大流派基于提示工程的“软约束”、基于模型微调的“硬约束”、以及当前最热门的“函数调用/工具调用与 JSON 模式”。每种方案各有优劣适用场景也不同。3.1 流派一提示工程增强法这是入门成本最低的方法不依赖任何特殊 API 或模型微调核心在于优化你的提示词。核心技巧示例驱动Few-Shot Learning在提示词中提供多个清晰、正确的输入-输出示例。这是最有效的手段之一。示例要覆盖各种边界情况。格式强化描述不仅说“输出 JSON”还要详细描述。例如“你必须输出一个有效的、可直接被JSON.parse()解析的JSON 对象不要有任何额外的 markdown 代码块标记或解释文字。”角色扮演给模型赋予一个严格遵守规则的角色如“你是一个严格的 JSON API 终端只返回纯 JSON不返回任何其他文本。”后处理兜底在代码中尝试解析后如果失败可以提取可能包含 JSON 的代码块如json ...或进行简单的字符串修复如移除首尾空白、匹配第一个{到最后一个}之间的内容。实操示例Pythonimport json import re import openai def get_structured_output_with_retry(prompt, max_retries3): system_msg 你是一个数据格式化助手。用户会提出需求你必须返回一个严格符合给定JSON Schema的对象且不要包含任何其他解释文字。 user_msg f 需求{prompt} 请严格按照以下JSON Schema输出 {{ type: object, properties: {{ plan: {{ type: array, items: {{ type: object, properties: {{ date: {{ type: string, format: date }}, workout: {{ type: string }}, duration_minutes: {{ type: integer }} }}, required: [date, workout, duration_minutes] }} }} }}, required: [plan] }} 示例正确输出{{plan: [{{date: 2023-10-27, workout: 慢跑, duration_minutes: 30}}]}} for _ in range(max_retries): response openai.ChatCompletion.create( modelgpt-3.5-turbo, messages[{role: system, content: system_msg}, {role: user, content: user_msg}], temperature0.1 # 降低随机性 ) raw_output response.choices[0].message.content # 尝试提取JSON json_match re.search(r\{.*\}, raw_output, re.DOTALL) if json_match: try: return json.loads(json_match.group()) except json.JSONDecodeError: continue # 解析失败重试 raise ValueError(Failed to get valid JSON after retries.) # 使用 try: result get_structured_output_with_retry(制定一个为期三天的健身计划) print(json.dumps(result, indent2, ensure_asciiFalse)) except ValueError as e: print(e)注意提示工程法本质上是“概率性合规”无法保证 100% 成功。它适用于对可靠性要求不是极端高、或调用成本需要严格控制的中低复杂度场景。温度temperature参数建议设为较低值如0.1-0.3以减少随机性。3.2 流派二模型微调法这是最根本但也最“重”的解决方案。通过在自己的任务数据上对基础模型进行有监督微调SFT让模型从底层学会遵循特定的输出格式。操作流程数据准备收集或生成大量的(输入指令 符合格式的输出)配对数据。输出必须是严格符合你目标格式如特定 JSON 结构的字符串。模型训练使用 LoRA、QLoRA 等参数高效微调技术在基础模型如 Llama 3、Qwen 2.5上进行训练。部署推理使用微调后的模型进行推理理论上它会对指定的格式有极强的遵从性。优劣分析优势格式遵从性极高一旦训好一劳永逸。可以定制非常复杂和独特的格式。劣势成本高数据准备、训练资源、周期长、不灵活格式一旦变化可能需要重新训练或数据。属于“为了格式训练一个专属模型”性价比通常不高除非格式是你应用的核心且极其复杂。适用场景输出格式是业务核心且极度稳定不变同时有海量高质量配对数据可供训练。对于大多数应用来说这有点“杀鸡用牛刀”。3.3 流派三函数调用与JSON模式当前主流这是目前各大厂商主推、也是效果最好的方案。其核心是在 API 调用层面将输出结构作为“约束条件”直接传递给模型。它又细分为两种实现方式3.3.1 函数调用Function CallingOpenAI 在 2023 年中期率先引入。你定义一系列“函数”描述其名称、参数说明和参数 JSON Schema模型在理解用户请求后可以选择调用其中一个或多个函数并以符合该函数参数 Schema 的 JSON 对象作为输出。虽然名为“函数调用”但其本质是引导模型输出结构化 JSON 的绝佳机制。后来AnthropicClaude的“工具使用”Tool Use、Google Gemini 的“函数调用”都采用了类似理念。3.3.2 JSON 模式JSON Mode这是对函数调用的简化与补充。OpenAI 在gpt-3.5-turbo-1106及更新版本中引入了response_format参数。当你设置{ type: json_object }时模型会强制以 JSON 对象格式输出。但这只保证了输出是 JSON不保证内部结构。为了进一步约束内部结构你需要结合详细的提示词描述 JSON Schema。而像 Anthropic 的 Claude 3 系列则支持更强大的response_schema参数允许你直接传入一个 JSON Schema 对象来定义输出结构约束力更强。这是当前的重点和推荐方案因为它平衡了可靠性、灵活性和开发便利性。接下来我们将深入其实操细节。4. 实战使用OpenAI API实现可靠结构化输出让我们以最普及的 OpenAI API 为例展示如何在实际项目中运用函数调用和 JSON 模式。4.1 基于函数调用的结构化输出函数调用的核心思路是你告诉模型“你有什么函数可用每个函数需要什么参数”模型在思考后会决定是否调用以及调用时传入什么参数。这个“传入的参数”就是一个完美的结构化输出。步骤拆解定义工具函数列表这是一个数组每个元素描述一个函数。关键部分是parameters它遵循 JSON Schema 标准。发起聊天补全请求在tools参数中传入上述列表。将tool_choice设置为auto让模型决定或指定某个函数如{type: function, function: {name: your_function_name}}来强制调用。解析模型响应模型的响应会包含一个tool_calls字段其中就有它“决定调用”的函数名和参数一个 JSON 对象。完整代码示例import openai import json from typing import List, Optional client openai.OpenAI(api_keyyour-api-key) # 1. 定义我们期望的输出结构以“函数参数”的形式描述 tools [ { type: function, function: { name: output_fitness_plan, description: 输出一份健身计划, parameters: { type: object, properties: { plan: { type: array, description: 健身计划列表, items: { type: object, properties: { date: { type: string, description: 训练日期YYYY-MM-DD格式 }, workout_type: { type: string, description: 训练类型, enum: [有氧, 力量, 柔韧, 休息] # 甚至可以定义枚举 }, workout_name: {type: string}, duration_minutes: {type: integer, minimum: 10}, intensity: { type: string, enum: [低, 中, 高], default: 中 # 提供默认值 } }, required: [date, workout_type, workout_name, duration_minutes] # 必填字段 } }, summary: { type: object, properties: { total_days: {type: integer}, total_minutes: {type: integer}, focus_area: {type: string} } } }, required: [plan] } } } ] # 2. 发起请求强制模型使用我们定义的这个工具 response client.chat.completions.create( modelgpt-3.5-turbo, # 或 gpt-4-turbo messages[ {role: user, content: 为我制定一个为期5天的综合健身计划包含有氧和力量训练。} ], toolstools, tool_choice{type: function, function: {name: output_fitness_plan}}, # 强制调用指定函数 temperature0.1 ) # 3. 解析响应 message response.choices[0].message if message.tool_calls: tool_call message.tool_calls[0] # 假设只调用一个函数 if tool_call.function.name output_fitness_plan: # 这里得到的 arguments 已经是符合我们 Schema 的 JSON 字符串了 structured_output json.loads(tool_call.function.arguments) print(json.dumps(structured_output, indent2, ensure_asciiFalse)) else: print(模型没有调用工具。)关键优势100% 格式合规输出的arguments一定是一个能被json.loads解析的字符串并且其结构完全符合你定义的parametersSchema。OpenAI 的 API 层会对此进行保证。类型安全你可以定义字段类型、枚举值、默认值、必填项甚至嵌套结构。意图明确模型通过“选择调用哪个函数”来表达它对用户请求的理解这本身也是一种结构化信息。实操心得即使你当前不需要“函数调用”这个语义也可以只定义一个函数比如叫format_output把它当作一个纯粹的“结构化输出模板”来用。tool_choice参数强制模型使用它这样就变相实现了强约束的结构化输出。4.2 基于JSON模式response_format的简化方案如果你觉得定义函数有点重且使用的是较新的模型如gpt-3.5-turbo-1106,gpt-4-turbo-preview,gpt-4o可以使用更直接的 JSON 模式。response client.chat.completions.create( modelgpt-3.5-turbo-1106, # 注意必须是指定版本及之后的模型 messages[ {role: system, content: 你总是以有效的 JSON 对象回应。}, {role: user, content: 为我制定一个为期5天的综合健身计划以JSON格式输出包含一个plan数组每个元素有date、workout、duration_minutes字段。} ], response_format{type: json_object}, # 关键参数 temperature0.1 ) output_text response.choices[0].message.content # 此时 output_text 应该是一个纯 JSON 字符串可以直接解析 try: plan json.loads(output_text) print(json.dumps(plan, indent2)) except json.JSONDecodeError as e: print(fJSON解析失败但概率极低: {e}) print(f原始输出: {output_text})注意response_format{type: json_object}只保证输出是合法的 JSON 对象不保证内部字段结构。因此系统提示System Message和用户提示User Message中对 JSON 结构的描述至关重要需要与函数调用中的parameters一样详细。两者结合使用效果最佳。5. 开源模型与本地部署的结构化输出方案如果你在使用开源模型如 Llama 3、Qwen、Mixtral进行本地部署或通过兼容 API如 vLLM、Ollama调用同样可以实现结构化输出。主流方案有以下几种5.1 使用支持“工具调用”的推理框架许多推理服务器和库已经集成了类似 OpenAI 函数调用的功能。vLLM通过其 OpenAI 兼容的 API 服务器可以接收tools和tool_choice参数。前提是你使用的模型本身支持工具调用例如一些经过微调以支持工具调用的 Llama 版本。Llama.cpp其server模式也提供了与 OpenAI 兼容的 API但工具调用的支持程度取决于模型本身和编译选项。第三方 API 服务如 Together AI、Fireworks AI 等它们提供了多种开源模型的托管服务其中许多模型已支持工具调用其 API 与 OpenAI 高度兼容。操作流程与第4节中的OpenAI示例几乎完全相同只需更换 API Base URL 和 API Key。你需要查阅你所使用模型和推理框架的文档确认其对工具调用的支持情况。5.2 使用指导生成Guidance或约束解码Constrained Decoding库这是更底层、更强大的方法尤其适用于模型本身没有内置工具调用能力的情况。它通过在生成文本的每个步骤施加规则来确保输出符合特定格式如 JSON、正则表达式。Guidance一个微软推出的库允许你使用混合提示词和生成语法来引导模型。你可以定义一个 JSON 模板让模型在特定位置生成内容。Outlines/jsonformer这类库使用“约束解码”技术。它们在模型生成 token 时实时检查并过滤掉那些会导致最终结果不符合预定格式如 JSON Schema的 token。这能从根源上保证输出的语法正确性。以 Outlines 为例# 示例概念非可运行代码 import outlines from pydantic import BaseModel from typing import List # 1. 用 Pydantic 定义你想要的结构 class WorkoutItem(BaseModel): date: str workout: str duration_minutes: int class FitnessPlan(BaseModel): plan: List[WorkoutItem] # 2. 创建模型并约束其生成符合 FitnessPlan Schema 的 JSON model outlines.models.transformers(meta-llama/Llama-3-8B-Instruct) generator outlines.generate.json(model, FitnessPlan) # 关键绑定Schema # 3. 生成 prompt 制定一个3天的健身计划。 result generator(prompt) # result 直接是一个 FitnessPlan 实例 print(result.plan[0].date) # 直接访问属性类型安全这种方法优势巨大绝对可靠输出 100% 符合 Pydantic 模型直接就是 Python 对象无需解析和验证。开发体验极佳使用熟悉的 Pydantic 定义 Schema类型提示和自动补全全都有。适用性广不依赖模型本身的特殊能力只要是一个文本生成模型理论上都可以施加约束。主要挑战性能开销约束解码需要在生成时进行额外的计算和检查可能会降低推理速度。集成复杂度需要将推理管道与这些库集成相比直接调用 API 更复杂。6. 避坑指南与最佳实践在实际项目中大规模应用结构化输出我积累了一些血泪教训和有效实践。6.1 常见问题与排查技巧模型返回了tool_calls但arguments不是合法 JSON原因极其罕见但可能发生在早期模型或提示词冲突时。OpenAI 的最新模型基本杜绝了此问题。排查首先检查tool_call.function.arguments字符串。用json.loads捕获异常。如果失败可以尝试用ast.literal_eval安全或简单正则修复如补全缺失引号但更建议记录日志并触发重试或降级流程。模型不调用我期望的函数tool_calls为空原因模型认为用户请求与任何已定义函数的功能不匹配。解决检查函数描述function.description是否清晰准确地描述了该函数的用途确保它能被模型理解。优化用户查询用户的问题是否足够明确有时需要引导用户提问或在系统提示中说明“请根据以下可用功能来回答”。使用tool_choice参数如果你确定应该调用某个函数直接使用tool_choice强制指定而不是设为auto。生成的 JSON 值类型不对比如应该是数字却成了字符串原因JSON Schema 中定义了type: integer但模型生成时可能还是写了带引号的数字。这在复杂提示或温度较高时可能出现。解决降低温度将temperature设为 0.1 或 0。强化示例在function.parameters的description中强调类型或在系统/用户消息中提供更明确的示例。后处理转换在解析 JSON 后增加一层数据清洗和类型转换的代码作为最终防线。处理可选字段和空值null问题如果 Schema 中某个字段不是required模型有时会直接省略该字段有时会生成field: null。实践在代码中处理时使用.get()方法安全地访问可选字段并做好默认值处理。明确在 Schema 描述中说明“如果无关请省略此字段”或“如果无请设为 null”。6.2 架构设计与最佳实践Schema 设计要严谨且可扩展使用 JSON Schema 或 Pydantic 等工具正确定义 Schema。字段描述description要尽可能详细这是模型理解字段含义的主要依据。为未来留出扩展空间比如在根对象中加入_version字段或使用additionalProperties: false来严格限制字段防止模型“自由发挥”添加未定义的字段。实现健壮的客户端封装不要在每个业务代码里都写一遍 API 调用和错误处理。封装一个统一的get_structured_response函数内部处理重试、降级如结构化失败后回退到文本提取、日志记录和监控。考虑使用指数退避策略进行重试特别是对于偶发的格式错误。监控与评估记录每次 API 调用的输入、输出、token 用量和耗时。定义并监控关键指标结构化输出成功率JSON 解析成功且符合 Schema 的比例。这是衡量你提示词和 Schema 设计质量的核心指标。对失败案例进行抽样分析持续优化你的提示词和 Schema 描述。成本与延迟权衡函数调用/JSON 模式通常会消耗更多 token因为 Schema 描述本身也计入输入 token并可能带来轻微延迟。对于极其简单、固定的结构如“返回是或否”有时一个严格的提示词如“只回答‘是’或‘否’”可能更经济。但对于复杂结构为可靠性付出的 token 成本是值得的。组合使用多种技术主方案使用函数调用或 JSON 模式获得高可靠性输出。降级方案当主方案失败如模型不配合时回退到增强提示词后处理提取的方案。验证层无论哪种方案最终得到数据后都应用 Pydantic 模型进行二次验证和类型转换确保进入业务逻辑的数据是绝对干净的。从我自己的项目经验来看一旦将核心流程切换到结构化输出代码中那些丑陋的正则表达式和脆弱的文本解析逻辑可以删除大半整个系统的稳定性和可维护性会有质的提升。它让大模型从“一个聪明的聊天伙伴”真正变成了“一个可靠的软件组件”。
)
