Responses API 怎样保存结构化输出

Responses API 保存结构化输出时，建议把“模型响应对象”和“业务 JSON 文件”分开处理：先让接口按 Schema 生成结果，再从 SDK 的解析字段取出对象，最后写入自己的文件或数据库。这样既保留了响应状态，也不会把整份 SDK 响应对象直接当成业务数据。

官方文档：https://platform.openai.com/docs/guides/structured-outputs

本文使用 Python 说明一个小实验：把一条工单摘要保存为固定字段的 JSON。代码只是接口用法示例，图片是静态结构说明图，不是运行截图或真实请求结果。

先确定结构化输出与保存对象

先画清楚三层对象：输入提示决定任务，结构化 Schema 约束字段，Responses API 返回响应对象。真正要写入业务文件的，通常是解析后的字段；响应状态、响应 ID 和错误信息则作为旁路元数据保存，方便之后追踪。

如果只把 output_text 当成普通字符串保存，后续还要自己解析 JSON；如果直接保存整个响应，又会把接口元数据、输出项层级和业务字段混在一起。先确定落盘边界，后面代码会更简单。

用 Responses API 直接得到可解析对象

如果使用官方 Python SDK，最省事的方式是用 Pydantic 定义结果模型，再调用 client.responses.parse。成功后从 response.output_parsed 取得已经映射好的对象，再转换成普通字典写入文件。

from pathlib import Path
import json

from openai import OpenAI
from pydantic import BaseModel


class TicketSummary(BaseModel):
    # 这些字段就是下游文件的固定结构
    summary: str
    priority: str
    next_action: str


client = OpenAI()

# 让 Responses API 按模型约束返回结构化结果
response = client.responses.parse(
    model="gpt-6-astra",
    input=[
        {"role": "system", "content": "把工单整理成结构化摘要。"},
        {"role": "user", "content": "接口超时，已确认服务仍在运行，请给出下一步。"},
    ],
    text_format=TicketSummary,
)

# 响应未完成或没有解析对象时，不要写入业务文件
if response.status != "completed" or response.output_parsed is None:
    raise RuntimeError(f"响应未完成，状态为：{response.status}")

# 只保存业务字段，同时保留响应 ID 方便追踪
payload = {
    "response_id": response.id,
    "result": response.output_parsed.model_dump(),
}
Path("ticket-summary.json").write_text(
    json.dumps(payload, ensure_ascii=False, indent=2),
    encoding="utf-8",
)

这里的关键不是文件名，而是保存边界：response.output_parsed 是业务对象，response.id 是追踪元数据。两者一起落盘时，下游可以直接读取 result，排查请求时仍能定位原始响应。

需要原始 JSON 时显式声明 Schema

不想绑定 Pydantic 时，可以直接在 Responses API 的 text.format 中声明 JSON Schema。Structured Outputs 会按支持的 Schema 约束输出；相比旧式 JSON mode，Schema 方案还能明确字段和类型。严格模式下，示例 Schema 将三个字段列入 required，并禁止额外字段。

import json
from pathlib import Path
from openai import OpenAI


schema = {
    "type": "object",
    "properties": {
        "summary": {"type": "string"},
        "priority": {"type": "string"},
        "next_action": {"type": "string"},
    },
    "required": ["summary", "priority", "next_action"],
    "additionalProperties": False,
}

client = OpenAI()

# json_schema 让接口返回可被 json.loads 读取的固定对象
response = client.responses.create(
    model="gpt-6-astra",
    input="把这条工单整理成摘要：接口超时，但服务进程仍在运行。",
    text={
        "format": {
            "type": "json_schema",
            "name": "ticket_summary",
            "strict": True,
            "schema": schema,
        }
    },
)

# 先判断响应状态，再把文本解码成业务 JSON
if response.status != "completed":
    raise RuntimeError(f"响应未完成，状态为：{response.status}")
result = json.loads(response.output_text)
Path("ticket-summary.json").write_text(
    json.dumps(result, ensure_ascii=False, indent=2),
    encoding="utf-8",
)

严格 Schema 不是“任何 JSON 都能通过”的开关。字段是否必填、是否允许额外字段、类型如何定义，都要写在 Schema 中。若业务还要求日期格式、枚举值或跨字段关系，也要在应用层补充对应的规则。

保存前记录状态与失败原因

保存动作最好放在两个条件之后：响应状态为 completed，并且结构化对象已经成功取得。网络错误、响应不完整、模型拒答或解析字段为空时，应保留错误记录，不要生成一份看似完整的业务 JSON。

建议把成功文件和运行记录分开。成功文件只放下游真正需要的字段；运行记录可以包含 response_id、状态、模型名和错误信息。这样重试时不会覆盖上一次失败的上下文，也不会把内部响应层级暴露给业务消费者。

如果你的业务允许降级，可以单独写入 fallback.json，但要在字段中标记来源和降级原因。不要把降级字符串混进原本要求结构化的字段，否则下游很难判断这条数据是否可用。

按场景选择保存策略

只需要业务字段时，优先使用 responses.parse 与类型模型；需要跨语言或服务间共享契约时，使用显式 JSON Schema；需要追溯请求时，再把响应 ID 和状态写入旁路日志。三种做法都围绕同一个原则：业务文件保存稳定结构，运行记录保存接口上下文。

常见问题是把 JSON mode 和 Structured Outputs 混为一谈。前者主要保证输出是合法 JSON，不替你定义字段契约；后者通过 json_schema 约束结构，但仍需要应用层处理响应状态、业务语义和权限边界。

为什么不直接保存整个 response？

整个响应包含接口层级和元数据，不适合作为稳定业务格式。可以保存必要的 id、status，把解析后的字段单独放入 result。

output_text 能不能直接写文件？

可以，但它是文本。若下游需要对象，应先确认响应完成，再用 json.loads 解码；使用 responses.parse 时则直接读取 output_parsed。

官方接口地址在哪里？

API 请求入口是 https://api.openai.com/v1/responses，结构化输出说明见 https://platform.openai.com/docs/guides/structured-outputs。具体模型和 SDK 版本以当前官方文档为准。