结构化输出

是什么

强制模型返回可被程序直接解析的结构（JSON / 限定枚举 / 嵌套对象），而不是自由文本。

为什么需要

Agent 的下一步动作通常依赖模型产出的字段：分类标签、抽取实体、决策 JSON、工具参数。自由文本无法可靠驱动逻辑，必须结构化。

核心概念

• JSON Mode：response_format={"type": "json_object"}，模型只回 JSON（不保证严格符合你的 schema）。
• Structured Outputs：提供 JSON Schema，模型输出保证符合该 schema（字段、类型、必填）。
• 抽取（Extraction）：从非结构化文本中按 schema 提字段。
• 校验 + 重试：即便有 schema，也要用代码（pydantic / zod）再校验一次，失败则重试或降级。

最小代码范式

from pydantic import BaseModel

class Ticket(BaseModel):
    severity: str          # "P0" | "P1" | "P2"
    component: str
    summary: str
    need_human: bool

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "报警：prod 的 API 网关 5xx 突增"}],
    response_format={
        "type": "json_schema",
        "json_schema": {"name": "ticket", "schema": Ticket.model_json_schema()},
    },
)
import json
data = json.loads(resp.choices[0].message.content)
ticket = Ticket(**data)   # 二次校验，类型不符会抛错

常见陷阱

• 过度信任模型格式：即便开了 JSON Mode，仍可能返回解释性文字。务必代码层校验。
• schema 过严：枚举/嵌套太复杂，模型易失败；用 anyOf、允许 null、拆分步骤。
• 深层嵌套：超过 3 层嵌套的抽取准确率骤降，建议先粗抽再细抽。
• 无重试预算：校验失败应有限次重试（带错误反馈），而不是无限循环。

实践建议

• 简单分类用"限定枚举 + 温度 0"；复杂抽取用 Structured Outputs + pydantic 校验。
• 把"校验失败的原因"作为新一条消息回灌给模型，一次重试即可显著改善。

参考

• OpenAI Structured Outputs 文档
• JSON Schema 规范
• pydantic / zod 校验库文档