JSON schema 怎样约束模型返回结构

JSON Schema 要真正约束模型返回结构，需要把它交给支持结构化输出的接口，而不只是写进提示词。以 OpenAI Responses API 为例，在 text.format 中设置 type 为 json_schema、提供 schema 并启用 strict，正常完成的结构化输出便按受支持的 Schema 生成。拒绝或未完成响应仍需单独处理。

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

先确定要约束的业务对象

假设应用需要把一段用户反馈整理成工单草稿：category 表示分类，summary 是简短概括，ticket_id 是已有编号，没有编号就返回 null。先定义这些字段的含义，再决定类型与可用值，能减少接口接入后不断改字段的返工。

完整接入可以拆成约定对象、提交结构、接收状态、交给业务处理四个阶段。本文只讨论模型面向应用的文本输出，不展开工具调用。代码为未执行的教学示例，不会实际请求 API；读者需自行准备 SDK、环境变量及具备该能力的模型。

把字段约定写成最小 Schema

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "bug",
        "feature",
        "question"
      ]
    },
    "summary": {
      "type": "string"
    },
    "ticket_id": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "category",
    "summary",
    "ticket_id"
  ],
  "additionalProperties": false
}

根对象使用 object。properties 定义字段，required 列出三个字段；ticket_id 允许 string 或 null，以“字段存在但值为空”表达未提供编号。additionalProperties 为 false，限制未声明字段；category 的 enum 将分类收敛为三个机器可识别值。JSON 本身不支持注释，因此字段说明放在代码旁边。

图中的 properties、required、additionalProperties、category、summary、ticket_id 对应正文的六个节点。三个字段归入业务字段边界，其余节点归入结构规则边界；连线说明规则的归属与约束对象。遇到嵌套 object 时，也需要为该对象配置不允许额外属性的规则。

在 Responses API 中绑定结构

把上一节 JSON 读入 Python 字典并命名为 ticket_schema；如果直接写成 Python 字面量，应把 false 改为 False。再配置 OPENAI_API_KEY 和 OPENAI_MODEL，模型名应取自账号当前可用且支持 Structured Outputs 的选项。下面不固定某个模型，以免把账号可用性误写成通用保证。

import os
from openai import OpenAI

# 提前在环境变量中配置密钥与支持结构化输出的模型；不要把密钥写进源码
client = OpenAI()
model_name = os.environ["OPENAI_MODEL"]

# ticket_schema 使用上一节的 Schema 对象
response = client.responses.create(
    model=model_name,
    input=[
        {"role": "system", "content": "将反馈归类并概括。没有工单号时返回 null，不要编造编号。"},
        {"role": "user", "content": "导出按钮点击后没反应，请协助处理。"},
    ],
    text={"format": {
        "type": "json_schema",
        "name": "feedback_ticket",
        "strict": True,  # 启用支持范围内的严格结构约束
        "schema": ticket_schema,
    }},
)

name 是这份输出格式的名称，schema 才是业务字段约定；strict 是格式配置的一部分，不放在业务 properties 里面。Responses 的配置位置是 text.format，不能直接把其他接口的 response_format 外层结构原样搬过来。

提示词仍要说明任务和缺失信息处理方式。例如“没有编号返回 null”是在约束业务语义；Schema 只说明编号的类型允许空值，不能替应用决定来源可信不可信。

接收端区分完成、拒绝与未完成

import json

# 示例只展示非流式 Responses 返回后的处理；请求异常由调用方单独处理
if response.status != "completed":
    raise RuntimeError(f"响应未完成，状态为 {response.status}")

for item in response.output:
    if item.type != "message":
        continue
    for part in item.content:
        if part.type == "refusal":
            raise RuntimeError("模型拒绝了请求，应向用户展示相应状态")

if not response.output_text:
    raise RuntimeError("响应没有可解析的文本")

# 这里只解析最终文本，不从整份响应信封中猜测业务字段
ticket = json.loads(response.output_text)
# 进入业务系统前核对编号来源、分类含义与用户权限
print(ticket["category"], ticket["summary"])

response 包含 status 和 output；output 中可能包含 message，message 的内容可包括 refusal。output_text 是 SDK 提供的文本汇总便利属性，不能据此忽略响应状态。图中的 response、status、output、message、refusal、output_text 六个节点分别归入响应信封、消息内容与文本便利属性三个边界。

接收代码先要求 completed，再检查拒绝内容，最后解析文本。网络失败、认证错误和 Schema 不受支持属于请求层异常，应在调用处记录并处理，不能编造一个“成功的空工单”掩盖失败。正式产品可将这些状态转为明确的用户提示。

避免把结构正确当成事实正确

category 只能取三个值，不代表模型分类必然符合团队标准；ticket_id 是字符串，也不代表编号真实存在。业务系统仍应确认编号来源与权限，并在需要时回查记录。不要让格式符合成为执行敏感写入的唯一依据。

Structured Outputs 使用的是 JSON Schema 的受支持子集。Schema 越复杂，越需要核实所用关键字与模型支持情况；strict 模式不支持的定义可能直接导致请求报错。可先用小对象接通流程，再逐步增加确实需要的字段。

接入速查与常见疑问

只要求“返回 JSON”够吗？不能替代接口结构约束。JSON mode 主要保证 JSON 格式，不能保证字段、类型和枚举与这份 Schema 一致。

可选字段能从 required 中省掉吗？这里的严格结构化输出要求字段必填。需要表达可选业务信息时，可以让字段接收 null，而不是直接删除它。

解析成功就能写数据库吗？应先完成与业务有关的检查。解析解决的是数据形态问题，授权、记录真实性和业务规则仍由应用负责。

官方结构化输出指南：https://developers.openai.com/api/docs/guides/structured-outputs