OpenAI Structured Outputs 与 JSON mode 有什么区别？

官方资料（2026-10-29 核对）：Structured model outputs · Responses format reference · Chat Completions response_format · 迁移到 Responses API

Structured Outputs 与 JSON mode 核心对比

什么时候选择哪一种？

优先 Structured Outputs

• API 结果要直接写入数据库、表单、队列或类型化后端。
• 字段缺失、类型错误或非法枚举会造成业务事故。
• 需要前端稳定渲染卡片、表格、图表或多步骤 UI。
• 希望用 SDK 的 Zod、Pydantic 等辅助能力减少 Schema 与类型漂移。

JSON mode 仍有价值

• 所用旧模型或集成暂不支持 Structured Outputs。
• 输出结构非常松散，应用本来就需要兼容多种对象。
• 正在从纯文本逐步迁移，短期先取得有效 JSON，再补 Schema。

不要因为 JSON mode 配置更短就默认它更稳定。只要下游依赖具体字段，你仍要把验证、重试和失败隔离写回应用。

Responses API：使用 text.format

Responses 的 Structured Outputs 配置位于 text.format。下面示例把输出限制为一个订单摘要；模型名称应替换为你当前项目实际支持并验证过的模型。

import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "YOUR_MODEL",
  input: "订单 A-102，客户要求周五前送达。",
  text: {
    format: {
      type: "json_schema",
      name: "order_summary",
      strict: true,
      schema: {
        type: "object",
        properties: {
          order_id: { type: "string" },
          deadline: { type: ["string", "null"] }
        },
        required: ["order_id", "deadline"],
        additionalProperties: false
      }
    }
  }
});

const message = response.output.find(item => item.type === "message");
const content = message?.content?.[0];
if (response.status !== "completed" || content?.type !== "output_text") {
  throw new Error("refused or incomplete");
}
const data = JSON.parse(content.text);

如果使用 SDK 的解析辅助方法，可以从代码类型生成 Schema 并取得已解析对象；无论哪种方式，都要先判断响应是否完成、是否出现拒答，再把结果交给业务逻辑。

Chat Completions：使用 response_format

Chat Completions 的 Schema 位于 response_format.json_schema。它与 Responses 的字段层级不同，因此迁移时不能原样复制。

const completion = await client.chat.completions.create({
  model: "YOUR_MODEL",
  messages: [
    { role: "developer", content: "提取订单字段。" },
    { role: "user", content: "订单 A-102，客户要求周五前送达。" }
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "order_summary",
      strict: true,
      schema: {
        type: "object",
        properties: {
          order_id: { type: "string" },
          deadline: { type: ["string", "null"] }
        },
        required: ["order_id", "deadline"],
        additionalProperties: false
      }
    }
  }
});

const message = completion.choices[0].message;
if (message.refusal || !message.content) {
  throw new Error("refused or incomplete");
}
const data = JSON.parse(message.content);

要迁移完整端点、Items、状态和 Streaming，请先看 Responses API 与 Chat Completions 区别；本页只解决输出格式选择和失败处理。

strict Schema 最常见的四个问题

1. 根节点必须是 object：不能把顶层直接定义为数组，也不能在根节点使用 anyOf。
2. 字段都要 required：需要“可选”时，可把字段类型写成包含 null 的联合类型，但字段本身仍列入 required。
3. 关闭额外字段：对象通常需要 additionalProperties: false，避免模型返回 Schema 外的键。
4. 只使用受支持子集：Structured Outputs 支持 JSON Schema 的一个子集；先用官方指南核对类型、嵌套、枚举、anyOf、约束和递归支持，不要把任意 Schema 验证器的全部能力直接搬进请求。

大型 Schema 还要关注名称清晰、字段描述、嵌套深度和首次 Schema 处理延迟。把同一 Schema 版本化，并用固定评测集测试，比频繁动态生成更容易排查。

拒答、截断和“不完整 JSON”怎么处理？

Structured Outputs 并不表示每个请求都能得到业务对象。安全拒答可能以 refusal 出现；达到 max_output_tokens 或内容过滤时，Responses 可能标记为 incomplete。网络错误、超时和服务端错误则属于请求层问题。

1. 先检查 HTTP/SDK 错误，不把网络失败当成 JSON 错误。
2. Responses 先检查 status 与 incomplete_details；Chat Completions 检查结束原因和消息内容。
3. 检查输出内容是否为 refusal；拒答应进入明确 UI 或业务分支，而不是强行 JSON.parse。
4. 只有完整输出才解析；随后再做订单号、金额、权限、数据库约束等业务校验。
5. 按错误类别决定是否重试，并设置次数、退避与幂等保护；不要对固定 Schema 错误无限重试。

遇到 500、503、连接或超时，请看 API 5xx 与超时排查；遇到 429，按 速率限制指南处理。

JSON mode 的正确用法

Responses 使用 text: { format: { type: "json_object" } }；Chat Completions 使用 response_format: { type: "json_object" }。同时必须在 developer、system 或 user 上下文中明确要求生成 JSON。

const response = await client.responses.create({
  model: "YOUR_MODEL",
  instructions: "只返回有效 JSON，包含 summary 和 risk 字段。",
  input: "分析这段订单备注。",
  text: { format: { type: "json_object" } }
});

JSON mode 不知道你的业务 Schema。解析后必须用 Zod、JSON Schema validator、Pydantic 或等价方式验证；失败时保留原始响应、Schema 版本、模型、Request ID 和失败类别，有限重试或进入人工处理。

Structured Outputs 与 function calling 怎么选？

两者都能使用严格 Schema，但意图不同：

• 模型给用户或界面返回结构化结果：使用 text.format 或 response_format。
• 模型决定调用你的工具、数据库或业务动作：使用 function calling，并在函数定义中启用适用的严格参数 Schema。

不要为了取得 JSON 就假装调用一个无副作用函数；也不要把需要执行动作的工具参数当成普通文本返回。工具调用还要校验授权、幂等和副作用。

上线前验收清单

• 确认模型和端点支持所选格式；不要只凭模型家族名称推断。
• Responses 使用 text.format，Chat Completions 使用 response_format。
• 根 Schema 是 object，required 与 properties 一致，额外属性已关闭。
• 正常、空值、长文本、多语言、恶意输入和拒答样本均通过测试。
• 应用区分网络错误、429、5xx、refusal、incomplete、Schema 错误和业务校验失败。
• 有限重试带指数退避、jitter 与幂等保护，不形成重试风暴。
• 日志记录模型、Schema 版本、状态、Request ID、延迟和 usage，但不记录 API Key 或敏感原文。
• 通过 API Usage观察 Token、成本和失败率；批量离线任务可评估 Batch API。

常见问题