结构化输出怎样约束模型返回 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 不是“模型更懂业务”的开关,它表达的是:这次返回应该尽量贴合给定的结构。

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 分支。

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?不要;先走拒答分支,只有拿到正常内容时才进入解析。
-
284 收藏
-
387 收藏
-
328 收藏
-
426 收藏
-
147 收藏
-
164 收藏
-
416 收藏
-
267 收藏
-
185 收藏
-
156 收藏
-
科技周边 · 人工智能 | 27分钟前 | 人工智能 · openai · 多轮对话 Responses API conversation state OpenAI API previous_response_id121 收藏
-
470 收藏
-
417 收藏
-
493 收藏
-
414 收藏
-
122 收藏
-
275 收藏
-
- 前端进阶之JavaScript设计模式
- 设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
- 立即学习 543次学习
-
- GO语言核心编程课程
- 本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
- 立即学习 516次学习
-
- 简单聊聊mysql8与网络通信
- 如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
- 立即学习 500次学习
-
- JavaScript正则表达式基础与实战
- 在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
- 立即学习 487次学习
-
- 从零制作响应式网站—Grid布局
- 本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
- 立即学习 485次学习