OpenAI Structured Outputs 怎么约束嵌套 JSON 结构

我第一次把模型返回的订单信息接到业务代码时，最容易误判的是“JSON 能解析”就等于“结构可靠”。实际上，解析成功只说明文本像 JSON；如果还要稳定读取 items[].product 或 shipping_address.city，就需要让 Structured Outputs 约束完整的嵌套 schema。

官方地址：https://platform.openai.com/docs/guides/structured-outputs

嵌套 JSON 的关键不是只在根节点写一个 schema，而是把每一层 object 都写完整：properties、required、additionalProperties=false 同时出现；业务上“可选”的字段仍可 required，只把类型写成允许 null。

先把目标 JSON 拆成一棵对象树

假设结果需要表达订单、商品列表和收货地址，可以先确定边界，而不是马上拼请求参数：

{
  "order_id": "A1001",
  "items": [
    {
      "product": {"sku": "KB-01", "quantity": 2},
      "shipping_address": {"city": "杭州", "detail": null}
    }
  ]
}

这里至少有三个对象层级：根对象、items 的数组元素、数组元素里的 product 和 shipping_address。每个对象都要独立声明字段边界。

每个嵌套对象都补齐 required

下面是 Chat Completions 风格的核心 schema。注意 required 不是只写根层；数组元素中的对象和两个子对象也要写。

from openai import OpenAI

client = OpenAI()

# 根对象、数组元素和子对象都显式声明字段，避免返回结构漂移
order_schema = {
    "type": "object",
    "properties": {
        "order_id": {"type": "string"},
        "items": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "product": {
                        "type": "object",
                        "properties": {
                            "sku": {"type": "string"},
                            "quantity": {"type": "integer"}
                        },
                        "required": ["sku", "quantity"],
                        "additionalProperties": False
                    },
                    "shipping_address": {
                        "type": "object",
                        "properties": {
                            "city": {"type": "string"},
                            "detail": {"type": ["string", "null"]}
                        },
                        "required": ["city", "detail"],
                        "additionalProperties": False
                    }
                },
                "required": ["product", "shipping_address"],
                "additionalProperties": False
            }
        }
    },
    "required": ["order_id", "items"],
    "additionalProperties": False
}

这一段最值得记住的是缩进对应的约束边界：进入一个新的 type=object，就重新检查三件事。遗漏深层对象的 required，常常会让“根结构看起来正确，但业务字段不稳定”的问题重新出现。

required 和 nullable 解决的是两件事

收货地址的 detail 可能没有具体内容，但这不代表字段应该消失。用 ["string", "null"] 表示“字段必须出现，值可以是字符串或 null”。如果把它从 required 中删除，调用方就还要处理“字段不存在”和“字段为 null”两种分支。

additionalProperties: false 则是第三条边界：它限制对象不能带 schema 之外的字段。这个设置要沿着嵌套对象逐层放置，不是根层写一次就能覆盖所有子对象。

选对 API 入口并保留拒答分支

使用 Chat Completions 时，把 schema 放到 response_format 的 json_schema 中；使用 Responses API 时，对应位置是 text.format。入口不同，读取返回结果的代码也要跟着 SDK 版本保持一致。

from openai import OpenAI

client = OpenAI()

# strict=true 让模型按给定 schema 输出，业务仍要处理拒答或请求失败
response = client.chat.completions.create(
    model="gpt-4o-2024-08-06",
    messages=[
        {"role": "system", "content": "把订单文本整理成结构化订单。"},
        {"role": "user", "content": "订单 A1001：KB-01 两件，寄到杭州。"}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "order_result",
            "strict": True,
            "schema": order_schema
        }
    }
)

# 先判断是否被拒答，再读取 JSON 文本；不要把拒答当成正常订单
message = response.choices[0].message
if getattr(message, "refusal", None):
    raise RuntimeError("模型拒绝生成结构化订单")
print(message.content)

Structured Outputs 解决的是结构遵循，不会替你判断商品是否真实存在、数量是否符合库存，也不会替代业务层的权限和数据校验。结构稳定后，仍要在入库前做领域校验。

上线前用这张清单复查

• 根对象、数组元素对象和每个子对象是否都有 properties、required、additionalProperties=false。
• required 中的字段是否都在同层 properties 出现，拼写和大小写是否一致。
• 业务上的可选值是否用 nullable 表达，而不是依赖模型偶尔省略字段。
• 是否区分了 JSON mode 的“能解析”和 Structured Outputs 的“按 schema 组织”。
• 拒答、请求错误、业务枚举不合法和数据库写入失败是否分别处理。

按这套顺序整理后，嵌套 JSON 的问题会从“返回偶尔少字段”变成可定位的 schema 配置问题：先找漏掉的对象层，再查 required，最后检查 nullable 与未知字段边界。

相关问题

只写 json_object 可以吗？ 可以得到合法 JSON，但它不等于严格遵循你的嵌套字段约束；支持的模型优先使用 json_schema。

字段可选时一定要删除 required 吗？ 不一定。若调用方希望字段始终存在，应保留 required，并把类型设为允许 null。