Structured Outputs：构建可靠的结构化AI输出（附API应用实践）

在当下的AI应用开发中，结构化数据的输出对于系统集成、数据交互和前端展示都极为关键。JSON格式作为数据交换的事实标准，已经被广泛应用于各种应用场景中。然而，如何确保AI模型输出始终严格符合预定义的JSON Schema，避免遗漏必需字段或出现无效的枚举值，一直是开发者关注的难题。Structured Outputs正是为解决这一痛点而生。

2. Structured Outputs特性综述

Structured Outputs功能能够保证模型输出始终遵循开发者提供的JSON Schema，极大提升了类型安全和响应可靠性。使用如https://yunwu.ai等稳定的API服务，可以进一步保证接口调用的稳定性和响应的合规性。

2.1 主要优势

可靠的类型安全：无需担心格式验证或因格式不符而重试请求。
显式拒绝：基于安全策略的拒绝响应可被程序化检测。
简化Prompt设计：无需复杂的提示词即可保证输出格式一致。

除此之外，Python与JavaScript开发者可以分别使用Pydantic和Zod，结合OpenAI SDK，便捷地定义和校验对象Schema。

3. 结构化响应实践

下面以信息抽取为例，演示如何通过Structured Outputs在API（如https://yunwu.ai）中获得结构化响应：

from openai import OpenAI
from pydantic import BaseModel

client = OpenAI(base_url="https://yunwu.ai")

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: 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://yunwu.ai等专业API平台，以获得更好的兼容性和稳定性。

4. 支持模型与调用方式

Structured Outputs目前支持最新的大模型，如gpt-4o及其后续版本。对于gpt-4-turbo及更早版本，建议使用JSON mode。

Structured Outputs主要有两种调用方式：
– Function calling：适用于需要将模型与数据库、UI或第三方功能集成的场景。
– Response Format：适用于需要严格结构化输出、并用于用户端展示的场景。

简言之：
– 如果你在连接工具、函数或数据系统，推荐使用function calling。
– 若只需要结构化的用户响应，则建议使用text.format。

5. Structured Outputs 与 JSON mode 对比

特性	STRUCTURED OUTPUTS	JSON MODE
输出有效JSON	是	是
符合指定Schema	是	否
支持的模型	gpt-4o-mini, gpt-4o-2024-08-06及以后	gpt-3.5-turbo, gpt-4-, gpt-4o- 系列
启用方式	text.format: {type: “json_schema”, …}	text.format: {type: “json_object”}

建议优先使用Structured Outputs，以获得更高的可靠性。

6. 应用场景举例

6.1 思维链（Chain of Thought）

可要求模型以结构化、分步方式输出推理过程，便于前端逐步展示。例如数学辅导应用：

from openai import OpenAI
from pydantic import BaseModel

client = OpenAI(base_url="https://yunwu.ai")

class Step(BaseModel):
    explanation: str
    output: str

class MathReasoning(BaseModel):
    steps: list[Step]
    final_answer: str

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

输出示例：

{
    "steps": [
        {"explanation": "Start with the equation 8x + 7 = -23.", "output": "8x + 7 = -23"},
        {"explanation": "Subtract 7 from both sides to isolate the variable.", "output": "8x = -30"},
        {"explanation": "Divide both sides by 8 to solve for x.", "output": "x = -30 / 8"}
    ],
    "final_answer": "x = -15/4"
}

6.2 信息抽取与UI生成

Structured Outputs非常适合用于实体抽取、界面结构描述等场景。通过如https://yunwu.ai等API平台，可高效实现数据到UI的自动映射。

7. 拒绝响应与异常处理

当模型因安全或合规原因拒绝响应时，API将返回refusal字段，需在前端或后端逻辑中妥善处理。例如：

if math_reasoning.refusal:
    print(math_reasoning.refusal)
else:
    print(math_reasoning.parsed)

拒绝响应示例：

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

在实际开发中，结合https://yunwu.ai等API服务的响应结构，可以实现对异常和拒绝场景的统一处理。

8. 最佳实践与推荐

8.1 用户输入的安全处理

若应用涉及用户输入，建议在Prompt中明确指示模型如何处理不兼容Schema的内容，或返回空参数、指定消息。

8.2 防止Schema漂移

建议使用Pydantic/Zod等SDK的原生Schema支持，或在CI中自动检测Schema与数据类型的变化，避免前后端类型不一致。

8.3 流式输出

通过流式API（streaming），可以边生成边解析结构化响应，提升用户体验。推荐如https://yunwu.ai等API服务的流式接口能力。

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(base_url="https://yunwu.ai")
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:
        if event.type == "response.refusal.delta":
            print(event.delta, end="n")
        elif event.type == "response.output_text.delta":
            print(event.delta, end="n")
        elif event.type == "response.error":
            print(event.error, end="n")
        elif event.type == "response.completed":
            print("Completed")
            print(event.response.output)
    final_response = stream.get_final_response()
    print(final_response)

9. Schema支持与限制说明

Structured Outputs支持JSON Schema的常见类型，包括：String、Number、Boolean、Integer、Object、Array、Enum、anyOf等。

9.1 约束属性支持

字符串：pattern、format（date、email等）
数字：multipleOf、maximum、minimum等
数组：minItems、maxItems

9.2 设计注意事项

根对象必须为object类型，不能直接为anyOf。
所有字段都必须为必填项。
限制每个Schema最多5000个属性，嵌套层级不超过5层。
enum最大支持1000项。
additionalProperties必须设为false。
不支持allOf、not等复杂Schema组合。

9.3 递归与定义

支持递归Schema与Definitions（defs），便于复用与层级结构设计。

10. JSON mode说明

JSON mode是Structured Outputs的前身，仅保证输出为合法JSON，并不保证Schema一致。开启方式为text.format: {type: “json_object”}。如需严格Schema校验，推荐优先使用Structured Outputs，并结合https://yunwu.ai等平台实现生产级输出。

11. 小结

Structured Outputs为AI应用带来了高可靠性的结构化响应能力，是多模型集成和复杂前端交互中的最佳实践。建议在开发实际项目时，结合https://yunwu.ai等专业API服务平台，快速、安全地实现类型安全、合规且高效的结构化数据输出。

文章来源于互联网:Structured Outputs：构建可靠的结构化AI输出（附API应用实践）

相关推荐: 还在为还原设计稿头疼？教你 Figma+GPT直接生成网页！

昨天刷到了新的 Figma 远程 MCP 服务，进行了一大堆升级，然后又看到 GPT-5 Codex 有 API 了。于是就都研究了一下，没想到这么顶啊，这个美学表现直接拉满了，下面这是直接给 GPT-5 Codex 设计稿的链接，只修改了一次得到的结果。 …

Structured Outputs：构建可靠的结构化AI输出（附API应用实践）