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}

这种方法有时有效，但存在几个致命弱点：

1. 遵从性不稳定：模型，特别是较小或未经专门调优的模型，可能会忽略格式要求，或在 JSON 中插入额外的解释性文字。
2. 格式错误：生成的 JSON 可能缺少引号、有尾随逗号、或键名不一致，导致JSON.parse()直接抛出异常。
3. 内容漂移：即使格式正确，字段的值可能不符合要求，比如duration_minutes输出成了 “三十” 而不是 30。
4. 复杂结构无力：对于嵌套对象、数组的数组、联合类型等复杂结构，纯文本提示的约束力急剧下降。

这些不确定性使得在生产环境中集成大模型变得风险极高。每一次 API 调用都像一次赌博，你需要编写复杂的后处理代码和重试逻辑来兜底。

2.2 结构化输出的核心需求清单

一个理想的结构化输出方案，应该满足以下需求：

• 强约束性：能严格定义输出的数据类型（字符串、数字、布尔值、枚举）、结构（对象、数组）和可选性。
• 高可靠性：保证输出 100% 符合预定格式，可直接被标准解析器（如 JSON 解析器）处理，无需清洗。
• 开发友好：定义模式（Schema）的方式应该直观，最好能与编程语言中的类型定义（如 TypeScript Interface、Python Pydantic Model）无缝衔接。
• 灵活性：在约束框架内，模型仍保有生成内容的创造性。我们约束的是“容器”，而非完全限制“内容”。
• 跨模型兼容：方案应尽可能适用于不同的主流模型，而不是绑定某个特定供应商。

理解了这些需求，我们就能更好地评估接下来要介绍的各种技术方案。

3. 技术方案全景图：三大主流流派详解

目前，实现结构化输出的技术路径主要分为三大流派：基于提示工程的“软约束”、基于模型微调的“硬约束”、以及当前最热门的“函数调用/工具调用与 JSON 模式”。每种方案各有优劣，适用场景也不同。

3.1 流派一：提示工程增强法

这是入门成本最低的方法，不依赖任何特殊 API 或模型微调，核心在于优化你的提示词。

核心技巧：

1. 示例驱动（Few-Shot Learning）：在提示词中提供多个清晰、正确的输入-输出示例。这是最有效的手段之一。示例要覆盖各种边界情况。
2. 格式强化描述：不仅说“输出 JSON”，还要详细描述。例如：“你必须输出一个有效的、可直接被JSON.parse()解析的JSON 对象，不要有任何额外的 markdown 代码块标记或解释文字。”
3. 角色扮演：给模型赋予一个严格遵守规则的角色，如“你是一个严格的 JSON API 终端，只返回纯 JSON，不返回任何其他文本。”
4. 后处理兜底：在代码中，尝试解析后，如果失败，可以提取可能包含 JSON 的代码块（如json ...），或进行简单的字符串修复（如移除首尾空白、匹配第一个{到最后一个}之间的内容）。

实操示例（Python）：

import json import re import openai def get_structured_output_with_retry(prompt, max_retries=3): 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( model="gpt-3.5-turbo", messages=[{"role": "system", "content": system_msg}, {"role": "user", "content": user_msg}], temperature=0.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, indent=2, ensure_ascii=False)) except ValueError as e: print(e)

注意：提示工程法本质上是“概率性合规”，无法保证 100% 成功。它适用于对可靠性要求不是极端高、或调用成本需要严格控制的中低复杂度场景。温度（temperature）参数建议设为较低值（如0.1-0.3），以减少随机性。

3.2 流派二：模型微调法

这是最根本但也最“重”的解决方案。通过在自己的任务数据上对基础模型进行有监督微调（SFT），让模型从底层学会遵循特定的输出格式。

操作流程：

1. 数据准备：收集或生成大量的(输入指令， 符合格式的输出)配对数据。输出必须是严格符合你目标格式（如特定 JSON 结构）的字符串。
2. 模型训练：使用 LoRA、QLoRA 等参数高效微调技术，在基础模型（如 Llama 3、Qwen 2.5）上进行训练。
3. 部署推理：使用微调后的模型进行推理，理论上它会对指定的格式有极强的遵从性。

优劣分析：

• 优势：格式遵从性极高，一旦训好，一劳永逸。可以定制非常复杂和独特的格式。
• 劣势：成本高（数据准备、训练资源）、周期长、不灵活（格式一旦变化可能需要重新训练或数据）。属于“为了格式，训练一个专属模型”，性价比通常不高，除非格式是你应用的核心且极其复杂。

适用场景：输出格式是业务核心且极度稳定不变，同时有海量高质量配对数据可供训练。对于大多数应用来说，这有点“杀鸡用牛刀”。

3.3 流派三：函数调用与JSON模式（当前主流）

这是目前各大厂商主推、也是效果最好的方案。其核心是在 API 调用层面，将输出结构作为“约束条件”直接传递给模型。它又细分为两种实现方式：

3.3.1 函数调用（Function Calling）OpenAI 在 2023 年中期率先引入。你定义一系列“函数”（描述其名称、参数说明和参数 JSON Schema），模型在理解用户请求后，可以选择调用其中一个或多个函数，并以符合该函数参数 Schema 的 JSON 对象作为输出。虽然名为“函数调用”，但其本质是引导模型输出结构化 JSON 的绝佳机制。后来，Anthropic（Claude）的“工具使用”（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 基于函数调用的结构化输出

函数调用的核心思路是：你告诉模型“你有什么函数可用，每个函数需要什么参数”，模型在思考后，会决定是否调用以及调用时传入什么参数。这个“传入的参数”就是一个完美的结构化输出。

步骤拆解：

1. 定义工具（函数）列表：这是一个数组，每个元素描述一个函数。关键部分是parameters，它遵循 JSON Schema 标准。
2. 发起聊天补全请求：在tools参数中传入上述列表。将tool_choice设置为"auto"（让模型决定）或指定某个函数（如{"type": "function", "function": {"name": "your_function_name"}}）来强制调用。
3. 解析模型响应：模型的响应会包含一个tool_calls字段，其中就有它“决定调用”的函数名和参数（一个 JSON 对象）。

完整代码示例：

import openai import json from typing import List, Optional client = openai.OpenAI(api_key="your-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( model="gpt-3.5-turbo", # 或 gpt-4-turbo messages=[ {"role": "user", "content": "为我制定一个为期5天的综合健身计划，包含有氧和力量训练。"} ], tools=tools, tool_choice={"type": "function", "function": {"name": "output_fitness_plan"}}, # 强制调用指定函数 temperature=0.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, indent=2, ensure_ascii=False)) 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( model="gpt-3.5-turbo-1106", # 注意：必须是指定版本及之后的模型 messages=[ {"role": "system", "content": "你总是以有效的 JSON 对象回应。"}, {"role": "user", "content": "为我制定一个为期5天的综合健身计划，以JSON格式输出，包含一个'plan'数组，每个元素有'date'、'workout'、'duration_minutes'字段。"} ], response_format={"type": "json_object"}, # 关键参数 temperature=0.1 ) output_text = response.choices[0].message.content # 此时 output_text 应该是一个纯 JSON 字符串，可以直接解析 try: plan = json.loads(output_text) print(json.dumps(plan, indent=2)) except json.JSONDecodeError as e: print(f"JSON解析失败，但概率极低: {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 常见问题与排查技巧

1. 模型返回了tool_calls，但arguments不是合法 JSON？

   • 原因：极其罕见，但可能发生在早期模型或提示词冲突时。OpenAI 的最新模型基本杜绝了此问题。
   • 排查：首先检查tool_call.function.arguments字符串。用json.loads捕获异常。如果失败，可以尝试用ast.literal_eval（安全）或简单正则修复（如补全缺失引号），但更建议记录日志并触发重试或降级流程。

2. 模型不调用我期望的函数（tool_calls为空）？

   • 原因：模型认为用户请求与任何已定义函数的功能不匹配。
   • 解决：
     • 检查函数描述：function.description是否清晰准确地描述了该函数的用途？确保它能被模型理解。
     • 优化用户查询：用户的问题是否足够明确？有时需要引导用户提问，或在系统提示中说明“请根据以下可用功能来回答”。
     • 使用tool_choice参数：如果你确定应该调用某个函数，直接使用tool_choice强制指定，而不是设为"auto"。

3. 生成的 JSON 值类型不对，比如应该是数字却成了字符串？

   • 原因：JSON Schema 中定义了"type": "integer"，但模型生成时可能还是写了带引号的数字。这在复杂提示或温度较高时可能出现。
   • 解决：
     • 降低温度：将temperature设为 0.1 或 0。
     • 强化示例：在function.parameters的description中强调类型，或在系统/用户消息中提供更明确的示例。
     • 后处理转换：在解析 JSON 后，增加一层数据清洗和类型转换的代码，作为最终防线。

4. 处理可选字段和空值（null）

   • 问题：如果 Schema 中某个字段不是required，模型有时会直接省略该字段，有时会生成"field": null。
   • 实践：在代码中处理时，使用.get()方法安全地访问可选字段，并做好默认值处理。明确在 Schema 描述中说明“如果无关，请省略此字段”或“如果无，请设为 null”。

6.2 架构设计与最佳实践

1. Schema 设计要严谨且可扩展

   • 使用 JSON Schema 或 Pydantic 等工具正确定义 Schema。字段描述（description）要尽可能详细，这是模型理解字段含义的主要依据。
   • 为未来留出扩展空间，比如在根对象中加入_version字段，或使用additionalProperties: false来严格限制字段，防止模型“自由发挥”添加未定义的字段。

2. 实现健壮的客户端封装

   • 不要在每个业务代码里都写一遍 API 调用和错误处理。封装一个统一的get_structured_response函数，内部处理重试、降级（如结构化失败后回退到文本提取）、日志记录和监控。
   • 考虑使用指数退避策略进行重试，特别是对于偶发的格式错误。

3. 监控与评估

   • 记录每次 API 调用的输入、输出、token 用量和耗时。
   • 定义并监控关键指标：结构化输出成功率（JSON 解析成功且符合 Schema 的比例）。这是衡量你提示词和 Schema 设计质量的核心指标。
   • 对失败案例进行抽样分析，持续优化你的提示词和 Schema 描述。

4. 成本与延迟权衡

   • 函数调用/JSON 模式通常会消耗更多 token（因为 Schema 描述本身也计入输入 token），并可能带来轻微延迟。
   • 对于极其简单、固定的结构（如“返回是或否”），有时一个严格的提示词（如“只回答‘是’或‘否’”）可能更经济。但对于复杂结构，为可靠性付出的 token 成本是值得的。

5. 组合使用多种技术

   • 主方案：使用函数调用或 JSON 模式获得高可靠性输出。
   • 降级方案：当主方案失败（如模型不配合）时，回退到增强提示词+后处理提取的方案。
   • 验证层：无论哪种方案，最终得到数据后，都应用 Pydantic 模型进行二次验证和类型转换，确保进入业务逻辑的数据是绝对干净的。

从我自己的项目经验来看，一旦将核心流程切换到结构化输出，代码中那些丑陋的正则表达式和脆弱的文本解析逻辑可以删除大半，整个系统的稳定性和可维护性会有质的提升。它让大模型从“一个聪明的聊天伙伴”真正变成了“一个可靠的软件组件”。