结构化输出：确保AI响应符合JSON Schema的技术原理与实现

结构化输出（Structured Outputs）是一项关键能力，确保大语言模型（LLM）生成的响应严格遵循开发者所指定的JSON Schema。这极大提升了系统集成的可靠性，尤其适用于数据抽取、任务分解、UI生成等场景。本文将系统阐述结构化输出的技术原理、关键参数配置，以及在Python环境下的应用示例。

1. 技术背景与实现原理

JSON作为主流的数据交换格式，被广泛应用于各类系统的数据通信。结构化输出功能要求模型生成的结果不仅是合法的JSON，还必须符合开发者提供的Schema约束。这避免了模型遗漏关键字段或产生非法枚举值的问题。

主要优势包括：
- 类型安全：免除后续数据格式校验或重试的开销。
- 显式拒绝检测：模型因安全等原因拒绝响应时可被程序化检测。
- 简化提示词设计：无需强制性提示即可稳定获得指定格式。

结构化输出目前支持于最新的大语言模型（如gpt-4o及更高版本），并可通过REST API或OpenAI Python SDK实现。Schema定义推荐使用Pydantic（Python）或Zod（JavaScript）。

2. 基础用法与代码示例

以下代码演示了如何从非结构化文本中抽取事件信息并解析为指定的数据结构。

from openai import OpenAI
from pydantic import BaseModel

# 定义事件数据结构
class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

client = OpenAI()

# 解析响应，确保符合CalendarEvent结构
response = client.responses.parse(
    model="gpt-4o-2024-08-06",
    input=[
        {"role": "system", "content": "Extract the event information."},
        {"role": "user", "content": "Alice and Bob are going to a science fair on Friday."},
    ],
    text_format=CalendarEvent,
)

# 得到结构化输出
event = response.output_parsed

关键参数说明

• model：指定所用AI模型版本；结构化输出仅支持gpt-4o及更新版本。
• text_format：绑定Pydantic模型，实现类型约束。

3. 结构化输出方式选择

结构化输出在API层面有两种实现方式：
- 函数调用模式：适用于模型连接数据库或调用业务函数场景。
- 响应格式模式（response_format）：适用于需要明确约定模型响应结构的场景（如前端UI或数据抽取）。

开发者可根据业务场景选择适合的方式。

4. 结构化输出与JSON模式比较

特性	结构化输出	JSON模式
输出有效JSON	✓	✓
严格匹配Schema	✓	✗
支持模型	gpt-4o系列及更高	gpt-3.5、gpt-4等

结构化输出推荐设置如下：

{
  "text": {
    "format": {
      "type": "json_schema",
      "strict": true,
      "schema": { ... }
    }
  }
}

5. 典型应用场景实例

5.1 数学推理分步输出

要求模型输出解题步骤及最终答案。

from openai import OpenAI
from pydantic import BaseModel

# 步骤结构
class Step(BaseModel):
    explanation: str
    output: str

# 推理整体结构
class MathReasoning(BaseModel):
    steps: list[Step]
    final_answer: str

client = OpenAI()
response = client.responses.parse(
    model="gpt-4o-2024-08-06",
    input=[
        {"role": "system", "content": "You are a helpful math tutor. Guide the user through the solution step by step."},
        {"role": "user", "content": "how can I solve 8x + 7 = -23"},
    ],
    text_format=MathReasoning,
)
math_reasoning = response.output_parsed

5.2 安全拒绝处理

模型因安全等原因拒绝响应时，可在结构化输出中检测refusal字段。

if hasattr(math_reasoning, "refusal"):
    print(math_reasoning.refusal)
else:
    print(math_reasoning)

拒绝响应示例：

{
  "output": [
    {
      "type": "refusal",
      "refusal": "I'm sorry, I cannot assist with that request."
    }
  ]
}

6. JSON Schema约束与限制

结构化输出支持JSON Schema的以下类型：
- 字符串（string）
- 数字（number）、整数（integer）
- 布尔值（boolean）
- 对象（object）
- 数组（array）
- 枚举（enum）
- 联合类型（anyOf）

此外，支持如下属性约束：
- 字符串属性：pattern（正则）、format（如email、date）
- 数值属性：minimum, maximum, multipleOf
- 数组属性：minItems, maxItems

示例：

{
  "type": "object",
  "properties": {
    "username": {"type": "string", "pattern": "^[a-zA-Z0-9_]$"},
    "email": {"type": "string", "format": "email"}
  },
  "required": ["username", "email"],
  "additionalProperties": false
}

重要限制

• 根对象必须为object，不可直接为anyOf。
• 所有字段必须为必填项，可通过type: [string, null]实现可选字段。
• 对象嵌套深度上限为5层，总属性数量不超过5000。
• 枚举项总数不超过1000。
• 必须设置additionalProperties: false。

7. 流式结构化输出实践

结构化输出支持流式解析，适合实时处理模型生成结果。

from typing import List
from openai import OpenAI
from pydantic import BaseModel

class EntitiesModel(BaseModel):
    attributes: List[str]
    colors: List[str]
    animals: List[str]

client = OpenAI()
with client.responses.stream(
    model="gpt-4o-2024-08-06",
    input=[
        {"role": "system", "content": "Extract entities from the input text"},
        {"role": "user", "content": "The quick brown fox jumps over the lazy dog with piercing blue eyes"}
    ],
    text_format=EntitiesModel,
) as stream:
    for event in stream:
        # 处理不同类型事件
        pass
    final_response = stream.get_final_response()
    print(final_response)

8. JSON模式说明

JSON模式仅保证输出为合法JSON，但不保证Schema一致。使用结构化输出可免除格式校验与重试环节。

JSON模式开启示例：

{
  "text": {
    "format": {"type": "json_object"}
  }
}

9. 实践经验与注意事项

• 针对用户输入需在提示中预设异常处理方式，避免模型因输入无关任务而生成虚假数据。
• 若输出不符合预期，可调整提示内容或拆分任务。
• 建议使用Pydantic等工具自动同步Schema与数据结构，避免类型漂移。

10. 总结

结构化输出显著提升了AI应用的数据可靠性和系统集成能力。在业务场景适配、异常处理、Schema设计等方面，开发者需充分理解其技术限制与约束，合理利用SDK与流式解析，实现高质量的自动化数据处理。