OpenAI结构化输出实战：用JSON Schema稳定生成接口文档

做接口联调的人应该都有过这种手忙脚乱的时刻对方扔过来一份接口文档字段名含糊类型和真实返回对不上要么缺嵌套层级要么把 string 写成 number。我最近在整理内部系统接口清单重点研究了一下 OpenAI 格式化输出 JSON 的能力把模型返回结果直接当成接口文档的数据源来用。这套做法不算复杂但真正跑起来会发现网上很多帖子只贴一个 response_format 参数完全不够。这篇文章把我在实践里验证过的配置方式、JSON Schema 约束、文档生成流程和踩过的坑都写出来给正在做同类事情的人一个可抄的作业。如果你现在做的事是“让 ChatGPT 帮我生成一段 JSON”那只看 JSON Mode 就够了但如果你和我一样是想让模型稳定产出结构一致的接口文档字段那必须花时间把“格式化输出”当成一个工程问题来处理而不是一句话的事。下面从原理讲到实操再讲排障。1. 格式化输出不止是“把结果整理成 JSON”而是接口契约很多人误以为模型能返回 JSON就等于能稳定返回“正确结构的 JSON”。这两者差距非常大。普通对话里让模型“给我一个 JSON”它能给你但字段名和嵌套结构可能每次都变。接口文档恰恰最怕字段不稳定文档里的 endpoint、method、request_params 一旦换了名字下游代码就废了。1.1 三种常见做法提示词、JSON Mode、Structured Outputs我在实际项目里把 OpenAI 的结构化返回分成三个层级提示词约束在 system prompt 里写“请以 JSON 格式返回”。优点是零成本缺点是模型心情好就遵守心情不好就给你塞几句 Markdown 说明。JSON Mode通过 response_format{type: json_object} 强制模型输出合法 JSON。这个模式能保证输出是 JSON但不保证 JSON 的字段跟你想要的一致。Structured Outputs在请求里直接传 JSON Schema模型按 schema 返回字段缺失或多余时会被拦下来。这才是接口文档真正需要的约束。要不要上 Structured Outputs取决于你后续拿 JSON 干什么。如果只是给人看一眼JSON Mode 足够如果 JSON 要进程序、要落库、要生成接口文档那最好直接上 schema。1.2 为什么接口文档需要严格的 JSON 输出接口文档本质上是一份契约。调用方根据文档去写请求参数服务方根据文档去实现接口中间任何字段表达不一致都会变成 bug。OpenAI 这类大模型的输出天然带有随机性如果不做结构化约束你让它描述同一个“用户列表接口”一次可能返回 users另一次返回 user_list第三次直接给中文的“用户列表”。字段名对不上后面所有逻辑都会跟着断。我自己踩过最明显的一次是让模型直接描述一个登录接口它第一次返回{url: /login, method: POST, args: {user: root}}第二次返回{endpoint: /login, request_type: POST, params: {username: root}}两个结果单独看都对但放到同一个接口文档模板里就没法合并。这就是没有 JSON Schema 约束时的典型问题。后来我把字段名和类型全部写进 schema模型就算想发挥也只能在我给的框里发挥。2. 从零配置一个能稳定输出 JSON 的 OpenAI 调用写代码之前先想清楚一件事OpenAI 的 API 参数在不同接口版本里长得不一样但你只要认准最常用的 Chat Completions 接口按下面这套写基本能覆盖大多数场景。2.1 最基础的那步response_format 参数怎么传一个最简单的 Python 调用长这样from openai import OpenAI client OpenAI() resp client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 请把用户描述整理成 JSON。}, {role: user, content: 这是一个支付回调接口请求方式是 POST路径是 /api/pay/callback返回 code 和 message。} ], response_format{type: json_object}, temperature0, ) print(resp.choices[0].message.content)这里有两个细节值得注意。第一JSON Mode 要求 messages 里至少出现一次“JSON”这个单词否则请求会直接报参数错误。所以我在 system prompt 里一定会把“JSON”写在文案里而不是只靠 response_format 参数。第二temperature 我直接给 0。虽然 temperature0 不代表完全确定性但对接接口文档这种任务我就要尽量少的变化。现在很多工具比如 Cline 这类编码助手配置页面里也有 OpenAI compatible 的选项底层走的就是这套协议。你只要按上面的方式写好了换成兼容端点时 response_format 一般也能透传省很多麻烦。2.2 JSON Schema 版本把约束写在请求里如果你需要的不只是合法 JSON而是字段全对的 JSON就得用 Structured Outputs。Chat Completions 里的写法是api_doc_schema { name: api_doc, strict: True, schema: { type: object, properties: { endpoint: {type: string}, method: {type: string, enum: [GET, POST, PUT, DELETE]}, summary: {type: string} }, required: [endpoint, method, summary], additionalProperties: False } } resp client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 根据用户描述生成接口 JSON严格遵守 schema。}, {role: user, content: 用户登录接口POST 到 /api/login作用是校验用户名密码并返回 token。} ], response_format{type: json_schema, json_schema: api_doc_schema}, temperature0, )这里有个很重要的限制strict 为 true 时schema 中声明的 properties 必须全部出现在 required 里并且 additionalProperties 必须为 false。OpenAI 的结构化输出要求严格 JSON Schema 的子集想把某些字段设为“可选”不能只是少写在 required 里得更明确地用 nullable 或 anyOf 来表达。刚开始我用 strict schema 时也很不习惯觉得所有字段必填太死板。但做接口文档这件事“必填”本来就是常态一个字段如果可填可不填在文档里也应该明确标注。所以严格模式反而能逼着我把文档定义得更清楚。2.3 不传 schema 时的注意事项与提示词怎么写如果你暂时不想维护复杂 schema只用 JSON Mode也有办法尽量提升稳定性。我的经验是在 user 消息里直接给一个输出示例比在 system prompt 里写一堆“请务必准确”管用得多。比如这样写请根据下面这段描述输出一个 JSON 对象字段必须包含 { endpoint: 接口路径, method: 请求方法, params: {}, response: {} } 待整理描述获取用户列表的接口GET /api/users参数有 page 和 size返回用户数组。模型见过具体结构之后照抄概率会比空泛要求高很多。不过这仍是“尽量稳定”不是“保证稳定”。字段一旦多起来漏字段、改命名还是会出现。所以只要项目稍微正式一点我建议直接上 2.2 里的 schema 方式。3. 拿返回的 JSON 当中间产物再生成接口文档格式化输出的最终目标不是“输出 JSON”而是让 JSON 能被后续流程使用。我在实际项目里的做法是把模型输出的 JSON 当中间产物再用脚本渲染成 Markdown 或 OpenAPI 文档而不是让模型直接给你一份完整接口文档。3.1 先定义一套描述接口的 JSON Schema在调用模型之前我会先定义一套描述单个接口的最小 schema。以我自己常用的为例{ type: object, properties: { endpoint: {type: string}, method: {type: string, enum: [GET, POST, PUT, DELETE]}, summary: {type: string}, auth: {type: [string, null]}, request_body: {type: [object, null]}, response_body: {type: object}, errors: { type: array, items: { type: object, properties: { code: {type: integer}, message: {type: string} }, required: [code, message], additionalProperties: false } } }, required: [endpoint, method, summary, auth, request_body, response_body, errors], additionalProperties: false }这个 schema 有两个用意。第一约束模型的输出范围保证每个接口 JSON 都有一致的骨架第二给后面的校验脚本用任何一次生成结果不符合规范我都能第一时间发现。定义 schema 时不要一口气定义得太细。我一开始试图把 headers、query、path params 全拆到 properties 里结果模型频繁漏字段。后来改成以“接口文档需要的最小信息量”来定义反而稳定很多。太细的字段等生成之后再用人工或规则去补比逼模型一次到位更省事。3.2 让模型按 schema 返回接口信息有了 schema就把原始资料喂给模型。这里说的原始资料可以是代码注释、抓包记录、老接口文档甚至是一段接口定义代码。我的调用逻辑大概是这样import json from openai import OpenAI from jsonschema import validate client OpenAI() source_text 订单列表接口GET /api/orders 需要登录支持分页参数 page 和 size 返回订单数组每条订单包含 id、amount、status 错误情况token 失效时返回 401参数错误时返回 400 resp client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 把用户提供的接口说明整理成 JSON字段必须匹配给定 schema。}, {role: user, content: f接口说明如下\n{source_text}} ], response_format{type: json_schema, json_schema: api_doc_schema}, temperature0, ) doc_json json.loads(resp.choices[0].message.content) validate(instancedoc_json, schemaapi_doc_schema[schema])注意最后的 validate 调用我用的是 jsonschema 库不是只靠 OpenAI 的 strict 模式。OpenAI 的 strict 能保证输出基本符合 schema但传参传错、模型版本不同、兼容端点实现不全时可能还是会有偏差。加一道本地校验等于给流程上了双保险。到最后你会发现代码里真正调用 OpenAI 的部分反而不是最复杂的复杂的是怎么把 schema 和后面生成文档的逻辑对齐。3.3 把 JSON 转成 Markdown/OpenAPI 文档模型输出的 JSON 只是原料。下一步我通常会写一个非常简单的模板把 JSON 渲染成 Markdown 表格。比如md f ## {doc_json[summary]} - 请求方式{doc_json[method]} - 请求路径{doc_json[endpoint]} - 鉴权方式{doc_json[auth] or 无} ### 请求体 json {json.dumps(doc_json[request_body], ensure_asciiFalse, indent2)}响应体{json.dumps(doc_json[response_body], ensure_asciiFalse, indent2)}错误码codemessagefor err in doc_json.get(errors, []):md f| {err[code]} | {err[message]} |\n这样渲染出来的文档格式统一方便放进 Git 管理。如果团队已经使用 OpenAPI 规范也可以写一段转换逻辑把 doc_json 包成 paths 节点 python openapi_piece { /api/orders: { get: { summary: doc_json[summary], responses: { 200: { description: OK, content: { application/json: { schema: doc_json[response_body] } } } } } } }我不太建议让模型直接输出一整份 OpenAPI 文件因为 OpenAPI 要求很多顶层字段比如 openapi 版本、info、components模型一次生成很容易超过 token 限制或者生成不完整的结构。比较稳的做法是让模型只输出接口级别的 JSON再由本地脚本拼装完整 OpenAPI 文件。4. 我在实际接入中踩过的坑格式校验、返回变体和温度参数这一节写的都是真实排障过程不是标准文档里会告诉你的内容。希望对你有参考价值。4.1 开着 JSON 模式但返回了空对象有一次我明明设置了 response_format{type: json_object}模型却返回了一段空 JSON或者外面套了一层 Markdown 代码块。我先检查 messages 里有没有出现“JSON”这个单词果然没有。OpenAI 的 JSON Mode 对这个要求很严格提示词里没有 JSON 字样时请求直接报错或者结果不符合预期。补齐之后问题解决。还有一次更隐蔽是因为 max_tokens 给得太小。模型生成 JSON 到一半被截断返回内容是半截字符串json.loads 自然就失败了。遇到这种问题先看 messages 里有没有“JSON”再看返回内容长度是不是接近上限不要一上来就怀疑模型不会格式化。4.2 temperature 对 JSON 输出的影响到底有多大我一开始用 temperature0.7 去生成接口文档字段经常“换说法”。比如同样表示“用户ID”有些接口返回 user_id有些返回 uid有些返回 userId。后来全部改成 temperature0情况好了很多。但这里要说句实话temperature0 也不是银弹。大模型在解码时仍然存在低概率的采样波动尤其模型版本更新后同一段 prompt 可能产生不同结果。所以我不会只依赖 temperature还会在请求后做 schema 校验并且把校验结果写进日志。如果项目允许可以在 system prompt 里写明“不要解释不要输出除 JSON 以外的内容”但这最好和 response_format 一起用单独靠提示词还是不够稳。4.3 function calling 与 JSON mode 不能随便叠我在做一个自动收集接口的任务时本来已经用 tools 传了 function 定义又在同一个请求里加了 response_format。实际跑下来发现模型返回的 tool_calls 参数本身就已经是 JSON 字符串了再套一层 JSON Mode 反而让排查变得混乱。简单归纳一下我的使用经验如果只是想拿到一个 JSON 文本用 response_format。如果模型内部要决定调用哪个函数并且你希望返回结果严格匹配某个参数结构直接用 tools strict function calling。两个机制尽量分开用不要叠在一起。现在 OpenAI 的 Agents API / Responses API 也在强调 tools 和 text.format.json_schema 的分工本质上和 Chat Completions 里的取舍一致。理解这一点后面切到新接口也不会太痛苦。4.4 一个简单的排查表为了省得每次重复排障我把遇到的现象和处理方式整理成了一个小表贴在这里现象最常见原因处理方式返回的 JSON 字段名和期望不一致用了 json_object 但没传 schema改用 json_schema并加本地校验提示词包含 JSON 仍报参数错误某些兼容端点对 response_format 支持不完整降级为提示词约束或升级模型版本返回内容被截断max_tokens 太小调大 max_tokens或拆分接口文档生成任务内容带 Markdown 代码块模型受旧对话影响没按 response_format 走提示词中明确“只输出 JSON不要代码块”字段类型不符比如 string 返回了 numberschema 对类型没卡住严格模式 additionalPropertiesfalse并把类型写明确5. 从一次性生成到规范化接口文档团队协作视角单次调用生成一份接口文档很简单但放到团队里这件事要可持续就得考虑 schema 怎么维护、文档怎么版本化、生成结果怎么审查。5.1 让文档跟着 Schema 走我的核心习惯是schema 是主文档是次。先有 schema再有模型输出最后才有渲染出来的文档。不要反过来先让模型输出再手工改文档。具体到仓库里我会把 schema 单独放一个 JSON 文件比如 api_doc.schema.json。所有生成流程都读这个文件不在代码里复制一份。这样改字段时只需要改一处后面模型调用和校验脚本都能同步更新。生成的 Markdown 或 OpenAPI 文件也放进 Git每次变更都有 diff。人工审查时重点看 diff 里哪些字段变了而不是重新通读全文。这比让模型重新生成一遍文档要可控得多。5.2 版本管理与字段变更通知接口文档最怕字段消失。所以我给 schema 加了一个 version 字段并在生成文件时带上版本号。如果一次生成的任务涉及多个接口我会把所有接口的 JSON 放在一个数组里统一加序号和版本。当上游接口发生 breaking change 时正确的顺序是先改 schema再重新生成文档再更新下游依赖代码。如果你先改了代码再让模型猜文档就很容易出现文档和实际请求对不上的情况。这也是我自己一开始没有做好的地方。5.3 自动生成 OpenAPI 的取舍如果你的团队已经用 OpenAPI/Swagger我的建议仍然是“模型只生成局部脚本拼装全局”。原因很简单OpenAPI 对格式和引用关系要求高模型生成大文件时容易“自创”一些字段校验起来特别费劲。我实践过的路径是定义接口级 JSON Schema。调用模型为每个接口生成 doc_json。本地脚本把一组 doc_json 拼成完整 OpenAPI 文件。将 OpenAPI 文件导入到 Apifox、Cool Request 这类接口工具里继续做在线调试和分享。这样既用到了 OpenAI 的格式化输出能力又没有把最关键的数据结构交给模型自由发挥。所有可能出错的地方都被脚本和 schema 限制住了。6. 最后留一个建议把“格式化”当成接口文档项目的第一个验收用例如果你现在刚开始做类似的项目我建议不要一上来就追求“让模型自动生成全套接口文档”。先挑一个最简单的接口定义好 schema让它输出一次 JSON然后本地校验、渲染、人工检查。这一步跑通了后面再批量处理其他接口就只是复制流程的问题。我在实际使用中的一个体会是这套玩法真正的门槛不在 OpenAI 参数而在“你有多清楚自己想要的字段是什么”。字段定义得越清楚模型返回的结果就越接近可用状态。如果连你都不知道文档里该放哪些字段那模型只会帮你生成一份看起来很像、实际没法用的文档。最后分享一个小技巧批量生成完接口文档后我会随机抽两三条结果人工看一遍重点看字段命名是否和旧文档一致。模型很容易把 order_id 换成 orderId把 status 换成 state。这类问题靠 schema 很难完全杜绝只能靠定期抽检兜底。接口文档这种要给别人用的东西多一道人工审视力永远不吃亏。