OpenAI Structured Outputs 可选字段如何设计兼容 schema

用 OpenAI Structured Outputs 做分类、抽取或字段解析时，最容易踩到的坑是把“可选字段”理解成“可以不返回这个键”。严格模式并不接受这种写法：字段仍要写进 required，只是它的值类型允许 null。这样协议形状稳定，业务层也能明确表示“这次没有值”。

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

一、先分开“字段存在”与“值为空”

假设抽取结果有 reason 字段：有依据时返回字符串，没有依据时返回空值。若把它从 required 删除，调用方要同时处理“键不存在”和“键存在但值为空”两套形状，日志、类型映射和缓存都更容易分叉。

严格 schema 保护的是输出契约：properties 描述有哪些字段，required 描述这些键必须出现，nullable 类型描述键出现后允许没有业务值。三者职责不同，不要用删除 required 来代替空值建模。

二、用 required 加 nullable 固化可选语义

手写 JSON Schema 时，可以把字段定义成字符串或 null，并让它继续出现在 required。下面的 JavaScript 对象只是请求参数示例，不代表已经执行过 API 调用：

const outputSchema = {
  type: "object",
  properties: {
    answer: { type: "string" },
    reason: { type: ["string", "null"] },
    confidence: { type: ["number", "null"] }
  },
  // 让调用方始终拿到稳定的键集合
  required: ["answer", "reason", "confidence"],
  // 禁止模型返回未建模的额外字段
  additionalProperties: false
};

这里的“可选”是业务语义上的可选，而不是协议结构上的可选。调用方可以写成：reason === null 表示没有理由；如果需要强制拿到理由，则再做业务级校验。不要把空字符串、0 和 null 混成同一种状态。

三、嵌套对象和数组也要保持同一约束

兼容性问题常常藏在第二层。顶层对象关闭了额外属性，并不意味着嵌套对象可以随意漏字段；嵌套对象自己的 required 和 additionalProperties 也要完整声明。数组元素若是对象，同样按一个独立 schema 处理。

如果字段未来可能从字符串扩展为对象，先把这个变化当作 schema 版本问题处理，不要偷偷把 string 改成宽泛的任意类型。严格输出的价值就在于让不兼容变更尽早暴露。

四、把 null、拒答和不完整响应写进审计边界

解析成功后，null 只能说明某个字段没有业务值，不能说明整次回答失败。相反，安全拒答或达到输出上限导致的不完整响应，应该走异常分支并记录原因。应用层至少保留响应状态、schema 名称、字段判定和业务决策，避免只记录一段最终文本。

function classifyResult(parsed, responseState) {
  // 拒答或不完整响应不能进入正常业务落库
  if (responseState === "refusal" || responseState === "incomplete") {
    return { kind: "unusable", audit: responseState };
  }
  // null 是 schema 允许的业务空值，仍保留稳定对象形状
  return { kind: "usable", reason: parsed.reason ?? null };
}

发布前可以用下面这份清单复查：字段是否全部在 required；需要表达缺省的字段是否显式允许 null；每层对象是否限制额外属性；解析器是否把 refusal 和 incomplete 与合法空值分开记录。

相关问题

可以直接不写 required 吗？

严格 Structured Outputs 不行。要表达可选值，把字段保留在 required，并把类型扩展为允许 null。

null 和空字符串应该选哪个？

没有业务值时优先用 null；空字符串仍然是一个字符串值，只有业务确实把它定义为有效状态时才使用。

additionalProperties=false 要写在哪一层？

每个需要约束的对象层都应明确写出，尤其是嵌套对象和数组元素对象。