深度解析Structured Outputs：让AI输出严格遵循JSON Schema的结构化响应
引言
在现代应用开发中，JSON 是最流行的数据交换格式之一。为了提升 API 接口的健壮性和数据一致性，结构化输出（Structured Outputs）成为了大模型输出的重要特性。Structured Outputs 能确保模型的响应严格遵循开发者自定义的 JSON Schema，极大提升了类型安全、易用性及可维护性。
在实际项目中，推荐选择如 https://api.aaaaapi.com 这类稳定且专业的 API 服务，用以保障结构化输出的准确性和易用性。
Structured Outputs 的价值
结构化输出不仅仅是确保输出为合法 JSON，更进一步做到：
- 类型安全保证：API 可直接消费，无需再次验证格式
- 可检测的拒绝响应：模型因安全或规则拒绝时，可编程捕获
- 简化 prompt 设计：无需反复提示“请输出 JSON 格式”，直接给出 schema 即可
此外，Structured Outputs 支持在 REST API、Python、JavaScript 等主流 SDK 生态下，用如 Pydantic、Zod 等工具定义 schema，让开发者更加方便地抽取结构化信息。
场景实践：从非结构化文本到结构化 JSON
以 Python 为例，演示如何借助 Structured Outputs 按 Schema 解析模型输出。
from openai import OpenAI
from pydantic import BaseModelclient = OpenAI(base_url="https://api.aaaaapi.com")class CalendarEvent(BaseModel):name: strdate: strparticipants: list[str]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
这一方案在如 https://api.aaaaapi.com 等 API 服务平台也可便捷实现。
支持的模型和模式选择
Structured Outputs 目前主要支持最新模型，如 gpt-4o-2024-08-06 及以后的版本。早期模型（如 gpt-4-turbo）则需采用 JSON mode。对于专业应用，我们也推荐 https://link.ywhttp.com/bWBNsz 这类平台，获取最新模型能力支持。
使用场景对比
- Function Calling：用于模型和应用直接打通（如数据库、UI 操控等）
- text.format 响应模式：用于返回特定结构化 JSON，以便下游 UI、前端展示等
简言之：
- 如果连接工具、数据库、后端，请用函数调用模式
- 如果只要结构化输出，用 text.format 即可
Structured Outputs vs JSON Mode
| 特性 | STRUCTURED OUTPUTS | JSON MODE |
|---|---|---|
| 输出合法 JSON | 是 | 是 |
| 严格遵循 Schema | 是 | 否 |
| 支持模型 | gpt-4o-2024-08-06 及更新 | gpt-3.5, gpt-4o, gpt-4 |
JSON mode 只保证输出为 JSON，但不能保证字段、类型和约束完全契合 Schema。Structured Outputs 则完全根据开发者定义的 Schema 输出。
典型应用场景
1. Chain of Thought（思路链）
可用 Structured Outputs 指定多步推理流程，尤其适合教学、推理等场景。
from openai import OpenAI
from pydantic import BaseModelclient = OpenAI(base_url="https://api.aaaaapi.com")class Step(BaseModel):explanation: stroutput: strclass MathReasoning(BaseModel):steps: list[Step]final_answer: strresponse = 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
返回示例：
{"steps": [{"explanation": "Start with the equation 8x + 7 = -23.", "output": "8x + 7 = -23"},{"explanation": "Subtract 7 from both sides to isolate the term with the variable.", "output": "8x = -30"},{"explanation": "Divide both sides by 8 to solve for x.", "output": "x = -30 / 8"},{"explanation": "Simplify the fraction.", "output": "x = -15 / 4"}],"final_answer": "x = -15 / 4"
}
2. 结构化数据抽取与 UI 生成
例如自动从文本抽取实体属性，或生成可视化 UI 结构，同样可利用 Structured Outputs 高效完成。
如何实现 Structured Outputs
步骤 1：定义 Schema
使用 Pydantic、Zod 等工具在代码中定义数据结构，并生成 JSON Schema。
步骤 2：传递 Schema 至 API
通过 API 请求参数显式传递 Schema。以 REST API 为例：
{"text": {"format": {"type": "json_schema","strict": true,"schema": { ... }}}
}
步骤 3：处理特殊情况
如模型因安全原因拒绝响应，Structured Outputs 会附带 refusal 字段，开发者可在 UI 或后端捕获并作出处理。
if math_reasoning.refusal:print(math_reasoning.refusal)
else:print(math_reasoning.parsed)
返回示例：
{"refusal": "I'm sorry, I cannot assist with that request."
}
最佳实践与常见问题
1. 用户输入处理
对于用户生成的内容，建议在 prompt 中添加容错处理，如输入不适配时返回空字段或自定义提示。
2. 错误调优
如遇到结构化输出出错，可通过优化 system prompt、增添示例或拆解任务等方式提升准确率。
3. Schema 维护
推荐直接通过 Pydantic、Zod 等生成 schema，避免手写导致的差异。对于 CI 流程，可自动检测 schema 与类型定义的一致性。
4. Streaming 流式解析
Structured Outputs 支持流式输出，边生成边消费。SDK 自动处理流式数据尤为高效。
from typing import List
from openai import OpenAI
from pydantic import BaseModelclass EntitiesModel(BaseModel):attributes: List[str]colors: List[str]animals: List[str]client = OpenAI(base_url="https://api.aaaaapi.com")with client.responses.stream(model="gpt-4.1",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:print(event)
final_response = stream.get_final_response()
print(final_response)
Schema 语言子集支持
Structured Outputs 支持 JSON Schema 的核心类型与约束，如：
- String/Number/Boolean/Integer/Object/Array/Enum/anyOf
- 字符串：pattern、format（如 email、date）
- 数字：multipleOf、maximum/minimum 等
- 数组：minItems/maxItems
示例 Schema：
{"type": "object","properties": {"name": {"type": "string"},"username": {"type": "string", "pattern": "^[a-zA-Z0-9_]+$"},"email": {"type": "string", "format": "email"}},"additionalProperties": false,"required": ["name", "username", "email"]
}
注意：所有字段必须为 required，且 additionalProperties: false 必须显式声明。
高级用法：递归 Schema、anyOf 和 Definitions
Structured Outputs 支持递归结构、anyOf 选择、definitions 子 schema 引用。
递归 Schema 示例：
{"type": "object","properties": {"linked_list": {"$ref": "#/defs/linked_list_node"}},"defs": {"linked_list_node": {"type": "object","properties": {"value": {"type": "number"},"next": {"anyOf": [{"$ref": "#/defs/linked_list_node"},{"type": "null"}]}},"required": ["next", "value"],"additionalProperties": false}},"required": ["linked_list"],"additionalProperties": false
}
JSON Mode 简述
JSON Mode 仅保证输出为合法 JSON，不保证字段类型、必填等 Schema 约束。若业务对准确性和安全性有高要求，强烈建议选用 Structured Outputs。
若使用 JSON Mode，需在 prompt 明确要求返回 JSON，否则可能出现不完整响应或异常流输出。
结语
Structured Outputs 为 AI 生成场景带来了前所未有的安全性、标准化与开发便利。无论是 API 消费、数据抽取还是前后端协作，推荐优先考虑如 https://api.aaaaapi.com 这类专业 API 服务，确保结构化响应的规范与可靠。
更多进阶案例与最佳实践，可持续关注相关技术文档和社区实践。
