当前位置:首页 > 文章列表 > 科技周边 > 人工智能 > 结构化输出怎样约束模型返回 JSON Schema

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

来源:17golang原创 2026-11-16 20:26:28 0浏览 收藏

当模型输出要直接交给下游代码时,“看起来像 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删除
Responses API 怎样处理工具调用后的继续响应Responses API 怎样处理工具调用后的继续响应
上一篇
Responses API 怎样处理工具调用后的继续响应
Embedding 批量生成怎样控制输入分片和结果对应
下一篇
Embedding 批量生成怎样控制输入分片和结果对应
查看更多
最新文章
查看更多
课程推荐
  • 前端进阶之JavaScript设计模式
    前端进阶之JavaScript设计模式
    设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
    543次学习
  • GO语言核心编程课程
    GO语言核心编程课程
    本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
    516次学习
  • 简单聊聊mysql8与网络通信
    简单聊聊mysql8与网络通信
    如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
    500次学习
  • JavaScript正则表达式基础与实战
    JavaScript正则表达式基础与实战
    在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
    487次学习
  • 从零制作响应式网站—Grid布局
    从零制作响应式网站—Grid布局
    本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
    485次学习
查看更多
AI推荐
  • PubMedQA数据集详解:生物医学问答基准、功能与应用指南
    PubMedQA
    深入了解PubMedQA生物医学问答数据集,涵盖其核心功能、使用方法及在临床决策、药物研发等场景的应用,助力提升NLP模型性能。
    1054次使用
  • H2O EvalGPT:开源LLM大模型评估与排行榜工具
    H2O EvalGPT
    H2O EvalGPT是H2O.ai推出的开源LLM评估平台,提供详细的大模型性能排行榜、行业特定基准测试及A/B测试功能,助您快速选择最适合项目的高性能大语言模型。
    1054次使用
  • LMArena是什么?伯克利AI模型评估平台使用指南与功能解析
    LMArena
    LMArena是加州大学伯克利分校推出的AI模型匿名评测平台。通过盲测投票机制,用户可对比不同大模型回答并生成实时排行榜,助力开发者优化模型及用户选择最佳AI工具。
    1219次使用
  • 斯坦福HELM:大语言模型Holistic Evaluation整体评估框架详解
    HELM
    深入了解斯坦福推出的HELM(Holistic Evaluation of Language Models)大模型评测体系。本文解析其核心功能、安装配置步骤及应用场景,涵盖准确性、公平性、鲁棒性等多维度指标,助力开发者全面优化语言模型性能。
    1161次使用
  • MMBench详解:多模态大模型基准测试、功能特点与使用指南
    MMBench
    MMBench是由上海人工智能实验室等机构联合推出的多模态基准测试平台,提供细粒度能力评估、大规模数据集及VLMEvalKit工具。本文详细介绍其核心功能、安装使用方法及应用场景,助力开发者全面评估多模态模型性能。
    1004次使用
微信登录更方便
  • 密码登录
  • 注册账号
登录即同意 用户协议 和 隐私政策
返回登录
  • 重置密码