第 2/3 节课 · 8 分钟

获取结构化输出

发送一个 JSON Schema,让模型按你的结构返回 JSON,并在使用前先验证它。

随请求发送一个 JSON Schema,模型就会返回该结构的 JSON,而不是自由文本。当你想要拿回数据时使用它,例如从电子邮件中提取的字段。当你想让模型请求你的应用去做某件事时,使用工具调用。

type你得到什么
json_schema遵循你的 schema 的 JSON。默认使用这个。
json_object某个有效的 JSON 对象,不强制结构。
text纯文本(默认值)。

格式在 /v1/chat/completions 上放在 response_format 中,在 /v1/responses 上放在 text.format 中,在 /v1/messages 上放在 output_config.format 中(仅支持 json_schema)。

{
  "model": "openai/gpt-6-astra",
  "messages": [
    { "role": "user", "content": "Return the city and weather for London." }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "weather",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "city": { "type": "string" },
          "weather": { "type": "string" }
        },
        "required": ["city", "weather"],
        "additionalProperties": false
      }
    }
  }
}

JSON 会以字符串形式出现在消息内容中。解析之前,先检查是否有拒绝回答、内容缺失,或 finish_reason 不是 stop 的情况。然后验证解析后的对象,例如使用 Zod。如果验证失败,把错误放进提示词重试一次,然后返回一个安全的失败结果。每次重试都会计费,而且有效的 JSON 也不能证明其中的值是正确的。

Phaseo 从不丢弃 response_format。它只会把 json_schema 请求路由到支持结构化输出的提供商;如果该模型的所有提供商都不支持,请求会以 400 validation_error 失败。模型页面用 structured_outputs 标示是否支持,这是一个能力标记,而不是请求字段。

检验你的理解

你向一个其提供商都不支持结构化输出的模型发送了带 json_schema 的 response_format。会发生什么?

学以致用

你的发票解析器使用 json_schema,偶尔回复会因为缺少 total 而无法通过 Zod 检查。代码应该怎么做?

显示答案

先检查 finish_reason 是否为 stop,因为被截断的回答不可能有效。然后把验证错误放进提示词重试一次,如果仍然失败,就返回一个安全的失败结果,而不是去猜。按模型和 schema 版本跟踪失败情况,这样当其中任何一个变化导致情况变差时你能及时发现。

要点

需要固定结构的数据时使用 json_schema,并且在信任结果之前始终用你自己的代码验证它。

相关链接

进度保存在此浏览器中。

最后核对于 2026年11月17日