登录
推荐 文章 Go 技术 课程 下载 专题 AI
首页 >  科技周边 >  人工智能

结构化输出怎样约束模型返回 JSON Schema

来源:17golang原创

时间:2026-11-16 20:26:28 328浏览 收藏

当模型输出要直接交给下游代码时,“看起来像 JSON”并不够。调用方真正需要的是一份稳定的返回契约:字段名称明确、额外字段有边界,遇到拒答或不完整响应时也不会把异常对象误当成正常数据。Structured Outputs 的作用,就是把这份契约写成 JSON Schema,并在请求中明确启用严格约束。

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

这篇只围绕三个问题展开:Schema 应该怎么写,strict=true 到底收紧了什么,以及拒答、Schema 不支持和不完整响应为什么必须单独处理。它不承诺模型输出的业务事实一定正确,也不把结构化输出扩展成完整的提示词评测方案。

先把“合法 JSON”和“符合契约”分开

JSON mode 解决的是语法层问题:返回内容可以被 JSON 解析器读取。Structured Outputs 再向前走一步,要求返回对象遵循给定的 JSON Schema。比如工单分类器要交给程序读取 summary、priority 和 tags,仅仅得到一个合法对象还不够;字段拼错、漏掉必填项或突然多出一组未约定的键,都会把后续逻辑推入不确定状态。

因此可以把请求看成三层契约:API 请求选择结构化输出,json_schema 指向命名模式,Schema 再约束字段、类型、必填项和额外属性。strict=true 不是“模型更懂业务”的开关,它表达的是:这次返回应该尽量贴合给定的结构。

Structured Outputs 请求契约结构图,展示 Responses API、text.format、json_schema、strict、JSON Schema 与模型输出的关系
图1:Structured Outputs 请求契约的静态说明图;它解释字段约束之间的关系,不是运行截图或运行证据。

Schema 先写清楚对象边界

一个可维护的 Schema,至少要明确对象类型、属性类型、必填字段和是否允许额外属性。严格模式下,不要只写一组 properties 就期待调用方得到稳定结果;把真正要交付给下游的字段列入 required,并用 additionalProperties: false 把对象边界写出来。

如果某个值业务上可以缺省,可以把它表达成“字段仍然存在,但值允许为 null”,而不是让字段在不同响应中一会儿存在、一会儿消失。下面的 Schema 是一个原创的工单分类示例,JSON 本身保持严格有效,不在其中插入注释。

{
  "type": "object",
  "properties": {
    "summary": { "type": "string" },
    "priority": { "type": "string", "enum": ["low", "normal", "high"] },
    "tags": { "type": "array", "items": { "type": "string" } },
    "owner": { "type": ["string", "null"] }
  },
  "required": ["summary", "priority", "tags", "owner"],
  "additionalProperties": false
}

这里的 owner 不是可有可无的键,而是一个必填键;它的值可以是字符串,也可以是 null。这样下游只需要读取同一组键,不必再用“键不存在”和“键存在但为空”两套分支表达同一个业务状态。

Responses API:把 Schema 放进 text.format

在 Responses API 中,结构化文本输出通过 text.format 描述。关键关系是:type 设为 json_schema,给 Schema 一个稳定的 name,把 strict 放在格式对象中,并把上面的对象定义放入 schema。调用方拿到响应后,仍然要把它当作外部输入处理;结构符合约定,不代表内容自动通过业务审核。

from openai import OpenAI

client = OpenAI()

ticket_schema = {
    "type": "object",
    "properties": {
        "summary": {"type": "string"},
        "priority": {"type": "string", "enum": ["low", "normal", "high"]},
        "tags": {"type": "array", "items": {"type": "string"}},
        "owner": {"type": ["string", "null"]},
    },
    # 严格模式下把所有交付字段列出,避免下游依赖“偶尔缺失”的键。
    "required": ["summary", "priority", "tags", "owner"],
    # 关闭未声明字段,防止调用方悄悄接收新的结构。
    "additionalProperties": False,
}

response = client.responses.create(
    model="gpt-4o-mini",
    input="把这条工单归类:支付回调超时,但用户已经收到扣款通知。",
    text={
        "format": {
            "type": "json_schema",
            "name": "support_ticket",
            "strict": True,
            "schema": ticket_schema,
        }
    },
)

# 先判断是否有可消费的文本,再交给 JSON 解析或 SDK 的解析层。
if not response.output_text:
    raise RuntimeError("没有可消费的结构化文本")
print(response.output_text)

这个示例刻意没有把“输出一定正确”写进结论。strict=true 负责的是形状约束;例如 priority 的值只能来自枚举,但“支付回调超时”是否真的应该判为 high,仍然需要业务规则、人工复核或独立评测。

Chat Completions:正常对象与 refusal 要分支

如果项目仍然使用 Chat Completions API,结构化输出的入口是 response_format。读取消息时不要直接假设 content 就是可解析对象,先检查 SDK 暴露的拒答字段,再决定是否进入正常解析分支。拒答不是“Schema 失败后的一份半结构化 JSON”,而是需要调用方单独呈现或记录的响应状态。

import json
from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "只返回工单分类对象。"},
        {"role": "user", "content": "支付回调超时,但用户已经收到扣款通知。"},
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "support_ticket",
            "strict": True,
            "schema": ticket_schema,
        },
    },
)

message = response.choices[0].message

# 拒答先走独立分支,不把拒答文本当成业务对象解析。
if message.refusal:
    print({"status": "refused", "reason": message.refusal})
else:
    # 只有在没有拒答时,才把内容交给 JSON 解析器。
    parsed = json.loads(message.content)
    print(parsed["priority"])

真实项目还应该把截断或不完整响应单独记录。比如响应因为长度达到上限而提前结束时,解析器报错并不等于模型违反了 Schema;它更接近“这次没有拿到完整对象”。把这几类状态分开,重试、降级和人工处理才不会混成一个 catch-all 分支。

结构化输出拒答边界关系图,展示模型响应到 parsed、refusal、Schema 错误和不完整响应的分支
图2:拒答与不完整响应的边界说明图;它用于理解调用方分支,不是实际 API 返回截图。

strict 能约束什么,不能替你决定什么

把 strict=true 当作模式开关时,最容易忽略它的适用力。它适合收紧“返回对象长什么样”,不适合承担以下三件事:

  • 事实核验:字符串符合类型,不代表字符串里的结论真实。
  • 业务授权:枚举值合法,不代表当前用户真的有权执行对应动作。
  • 异常消除:拒答、截断和不支持的 Schema 仍然需要调用方分支。

另一个边界是 Schema 支持范围。严格模式并不意味着任意 JSON Schema 关键字都能使用;如果 Schema 包含当前接口不支持的能力,请求可能在模型生成前就失败。生产代码应把这类错误当作配置或契约发布错误处理,而不是把请求重发给模型。

什么时候值得把输出收紧成契约

如果输出只是展示给人看的段落,结构化约束的收益通常有限;如果输出要进入数据库、队列、表单或后续函数参数,Schema 的价值就很直接。可以用下面的清单做判断:

场景建议原因
下游按固定字段分流使用 JSON Schema + strict先把键和类型固定下来
只需要可解析 JSON评估是否真的需要严格模式减少不必要的 Schema 维护
内容可能触发拒答保留 refusal 分支拒答不是业务对象
Schema 复杂且频繁变化先确认官方支持范围避免把不支持的关键字带到线上

结语:把模型当成契约的一端,而不是契约本身

结构化输出最有用的地方,是让模型返回和下游代码之间多了一层可以讨论、版本化和审查的契约。写好 properties、required 与 additionalProperties,再用 strict=true 表达约束强度;与此同时,把 refusal、Schema 不支持和不完整响应留在正常对象之外。这样做的结果不是让模型变成数据库,而是让调用方更清楚地知道:什么可以解析,什么必须拒绝,什么需要重新设计契约。

相关问题

  • JSON mode 和 Structured Outputs 的核心区别是什么?前者保证 JSON 语法,后者进一步约束 Schema 遵循。
  • additionalProperties: false 为什么重要?它能把未声明字段挡在契约之外,减少下游静默接收新字段的风险。
  • 出现 refusal 后要不要继续 json.loads?不要;先走拒答分支,只有拿到正常内容时才进入解析。
声明:本文转载于:17golang原创 如有侵犯,请联系study_golang@163.com删除
相关阅读
更多>
最新阅读
更多>
课程推荐
更多>