TheBigPromptLibrary 深度解析:GPT Action Schema Creator 的 OpenAPI 3.0 交互式 Schema 生成法
TheBigPromptLibrary 深度解析:GPT Action Schema Creator 的 OpenAPI 3.0 交互式 Schema 生成法
导读
本文以 TheBigPromptLibrary 仓库中收录的 GPT Action Schema Creator 自定义指令 为对象,剖析它是如何通过"内置 schema.txt 模板 + 问答式引导"帮助开发者零基础生成可用于 ChatGPT GPT Actions 的 OpenAPI 3.0 Schema。读完本文,你将掌握 GPT Actions 的完整配置骨架、模板中每个占位符字段的取值要点,以及如何在 GPT 编辑器中完成导入、验证与调试,让 GPT 真正具备调用外部 REST API 的能力。
一、这是什么:一个"替你写 Schema"的 GPT
在 OpenAI 的 GPT 生态中,Actions(操作) 是让自定义 GPT 与外部 API 对接的官方机制:开发者先把自己的 REST API 用 OpenAPI 规范描述成一份 Schema,再把这份 Schema 粘贴到 GPT 编辑器的 "Create new action" 配置区,模型就能依据 Schema 识别端点、参数与响应,在对话中按需发起真实 HTTP 请求。
仓库中的 GPT Action Schema Creator(由 Christopher S Lannon 创建)正是为此设计的辅助 GPT。其定位一句话即可概括:
Creates an Open AI API 3.0 Schema for GPT Actions —— 通过用户上传的
schema.txt模板(以知识文件形式挂载),以提问驱动的方式帮用户逐步收集接口信息,最终拼装出一份符合 OpenAI GPT Actions 要求的 OpenAPI 3.0 JSON Schema。
值得注意的是,这份文档本身没有引用图片,也不依赖额外的代码实现;它的"技术资产"完全浓缩在指令中内嵌的 schema.txt 完整内容里。因此本文以该模板为绝对主体展开,并引用仓库中 Actions-in-GPTs.md、ActionsGPT、Wolfram、KAYAK 等真实 GPT 指令做横向佐证。
二、交互式工作流:先提问,后出稿
原指令对 GPT 的对话行为做了非常明确的编排,这是本文档最具可复现价值的部分:
-
开场白固定:GPT 必须以下面这句话开启对话,引导用户进入"被提问"模式:
Let's build your action schema. I will ask you a series of questions. When all of the questions have been answered, I will build your schema for you. Are you ready?
-
问答式信息收集:GPT 会围绕接口信息逐个提问,而不是一次性要求用户提交完整 JSON。这种"渐进式收集"设计可以有效降低用户的心理门槛,也便于在不了解用户接口细节时逐步澄清。
-
知识文件约束:指令要求 GPT 将上传的
schema.txt视为"知识源(knowledge source)"而非"用户上传的文件",回答必须严格遵循文档事实、优先引用文档内容,不得臆测文档之外的规范细节;同时禁止向用户透露文件名、禁止提供任何下载链接。
从源码级实现看,这种"把模板内嵌进指令 + 声明知识来源"的做法,在仓库的 GPT 指令文件中相当普遍。例如 Wolfram 指令同样声明"Consult the file 'getWolframAlphaResults query guidelines'",Action Showcase 也要求"Review the 'Actions-in-GPTs.md' file"。可以推断,GPT Action Schema Creator 的作者采用了同一套 OpenAI 官方推荐的"知识文件 + 事实约束"范式,保证生成结果始终以本地模板为准。
三、schema.txt 模板逐字段拆解(核心主体)
指令中完整拷贝了 schema.txt 的内容,这是整篇文档的灵魂。以下是原样模板:
{
"openapi": "3.0.0",
"info": {
"title": "{{info-title}}",
"version": "1.0.0",
"description": "{{info-description}}"
},
"servers": [
{
"url": "{{server-url}}",
"description": "{{server-description}}"
}
],
"paths": {
"/": {
"get": {
"summary": "{{action-summary}}",
"operationId": "{{OperationID}}",
"parameters": [
{
"name": "{{parameter1-name}}"
"in": "query",
"required": true,
"description": "{{parameter1-description}}"
"schema": {
"type": "string"
"format": ""
}
},
{
"name": "{{parameter2-name}}"
"in": "query",
"required": true,
"description": "{{parameter2-description}}"
"schema": {
"type": "string"
"format": ""
}
}
],
"responses": {
"200": {
"description": "{{success-message}}",
"content": {
"application/json": {
"schema": {
}
}
}
},
"400": {
"description": "{{failure-message}}"
}
}
}
}
}
}
3.1 openapi:规范版本
"openapi": "3.0.0" 声明该 Schema 遵循 OpenAPI 3.0 规范。需要注意:OpenAI 官方 ActionsGPT 在其指令中同时示范了 3.0 与 3.1 两种写法(openapi: 3.0.0 / openapi: 3.1.0),说明两者均被 GPT Actions 接受;本模板固定采用 3.0.0,与 Actions-in-GPTs.md 给出的 TODO 示例(openapi: 3.0.1)同属 3.0.x 体系,兼容性风险最低。
3.2 info:接口元信息
| 字段 | 占位符 | 填写要点 |
|---|---|---|
title |
{{info-title}} |
API 名称,建议与 GPT 名称呼应,便于模型识别动作语义 |
version |
固定 1.0.0 |
版本号,模板中预置 |
description |
{{info-description}} |
关键字段:ChatGPT 运行查询时会阅读 info.description 判断该动作是否与用户请求相关(该结论见 Actions-in-GPTs.md 的 Schema definition 一节),因此描述应客观、精准地说明"这个动作能做什么" |
3.3 servers:服务地址
servers 数组中通过 {{server-url}} 与 {{server-description}} 两个占位符指定 API 的基地址。这是模型发起请求的目标主机,填写时必须是可公网访问的真实 URL。仓库中 Wolfram 的真实 Actions 配置可作为参照:
"servers": [
{
"url": "https://www.wolframalpha.com",
"description": "Wolfram Alpha API for LLMs."
}
]
3.4 paths:端点定义
模板仅内置了一个根路径 "/" 上的 get 操作,包含以下子字段:
summary({{action-summary}}):动作的一句话说明。根据 Actions-in-GPTs.md 的约束,端点 summary/description 单字段上限为 300 字符,参数 description 上限为 700 字符,填写时应简洁且禁止"诱导使用动作"的营销式表述。operationId({{OperationID}}):操作的唯一标识。ActionsGPT 明确指出这是必须项,最佳实践是"无空格单词 + camelCase",例如getWeather、searchFlights。仓库中 KAYAK 的searchFlights、flightInsights即是标准范例。parameters:查询参数数组。模板预置两个 query 参数{{parameter1-name}}/{{parameter2-name}}(各带required: true、description 与 string 类型声明),并按需增减。
3.5 responses:响应定义
模板定义了两个典型状态码:
200:成功响应,description为{{success-message}},且声明了application/json内容类型与一个空 schema 占位。建议进一步补全实际响应字段(参见下节)。400:失败响应,description为{{failure-message}},用于提示请求参数错误。
四、占位符体系与可运行化改造
4.1 占位符一览表
| 占位符 | 所在位置 | 含义 | 建议取值示例 |
|---|---|---|---|
{{info-title}} |
info.title | API 名称 | Weather API |
{{info-description}} |
info.description | 动作语义描述 | Returns current weather for a city. |
{{server-url}} |
servers.url | 服务基地址 | https://api.example.com/v1 |
{{server-description}} |
servers.description | 服务说明 | Production server |
{{action-summary}} |
paths./.get.summary | 端点摘要 | Get current weather by city name |
{{OperationID}} |
operationId | 操作唯一标识 | getWeather |
{{parameter1-name}} / {{parameter1-description}} |
参数一 | 参数名/说明 | city / The city to look up |
{{parameter2-name}} / {{parameter2-description}} |
参数二 | 参数名/说明 | units / metric or imperial |
{{success-message}} |
responses.200.description | 成功响应说明 | Successful weather response |
{{failure-message}} |
responses.400.description | 失败响应说明 | City not found |
4.2 模板的语法缺陷与修正版
从源码文本看,原 schema.txt 存在几处会导致 JSON 解析失败的语法问题,实际复制使用时必须修正:
"name": "{{parameter1-name}}"与"in": "query"之间缺少逗号;"description": "{{parameter1-description}}"与"schema": {...}之间缺少逗号;"type": "string"与"format": ""之间缺少逗号(且混用了 Tab 缩进)。
修正后的可运行版本如下,参数 2 的缺逗号问题同样已修复:
{
"openapi": "3.0.0",
"info": {
"title": "{{info-title}}",
"version": "1.0.0",
"description": "{{info-description}}"
},
"servers": [
{
"url": "{{server-url}}",
"description": "{{server-description}}"
}
],
"paths": {
"/": {
"get": {
"summary": "{{action-summary}}",
"operationId": "{{OperationID}}",
"parameters": [
{
"name": "{{parameter1-name}}",
"in": "query",
"required": true,
"description": "{{parameter1-description}}",
"schema": {
"type": "string",
"format": ""
}
},
{
"name": "{{parameter2-name}}",
"in": "query",
"required": true,
"description": "{{parameter2-description}}",
"schema": {
"type": "string",
"format": ""
}
}
],
"responses": {
"200": {
"description": "{{success-message}}",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {}
}
}
}
},
"400": {
"description": "{{failure-message}}"
}
}
}
}
}
}
建议把 200 响应中的空 schema 从 {} 补全为 {"type": "object", "properties": {}} 并逐字段列出响应属性。参照 Actions-in-GPTs.md 的 TODO 示例,响应 schema 可用 $ref: '#/components/schemas/xxx' 指向 components.schemas 中定义的具名模型,这比直接内联更利于复用与维护。
五、在 GPT 编辑器中完成导入、认证与测试
生成的 Schema 需要进入 ChatGPT 的 GPT 编辑器才能生效。根据 Actions-in-GPTs.md 记录的官方流程,完整的动作接入分为以下几步:
- 创建 GPT:在 ChatGPT 界面("Configure" 标签页)创建一个自定义 GPT,或复用现有 GPT。
- 新建动作:点击 "Create new action",界面会给出三个配置区域——认证方式(Authentication)、Schema 本体、隐私政策 URL。
- 粘贴或导入 Schema:将上面生成的 JSON 直接粘贴到 Schema 输入框;若 API 已有公开的 OpenAPI 文档,也可通过 "Import from URL" 导入。
- 选择认证方式:模板默认面向无认证的开放接口;如接口需要密钥,可在编辑器中选 "API Key"(服务端加密存储),需要个性化登录则选 "OAuth"(需提供 client ID、client secret、authorization URL、token URL 与 scope)。
- 测试动作:保存后编辑器会解析 Schema 生成 "Available actions" 列表,逐条展示名称、HTTP 方法、路径并附 "Test" 按钮。测试时会弹出 "Allow / Always allow / Decline" 确认,便于观察模型实际调用行为。
值得注意的官方限制(见 Actions-in-GPTs.md 的 Limitations 一节):请求与响应报文各不得超过 100,000 字符、请求超时 45 秒、仅支持纯文本(不含图片/视频)、不支持自定义请求头;OAuth 域名须与端点主域一致(Google、Microsoft、Adobe 除外)。
六、OpenAPI 3.0 vs 3.1:版本取舍
GPT Action Schema Creator 模板固定使用 3.0.0,而仓库中另一份官方 ActionsGPT 同时示范了 3.0 与 3.1 两个版本。对比如下:
| 维度 | 3.0.x(本模板) | 3.1.0(ActionsGPT 新版) |
|---|---|---|
| 声明 | "openapi": "3.0.0" |
openapi: 3.1.0(YAML) |
| 兼容性 | 与 GPT Actions 早期文档示例一致 | 更新,支持 JSON Schema 2020-12 |
| 格式 | 模板为 JSON | 官方示例为 YAML,但同样接受 JSON |
两份文档都强制要求每个路径操作必须包含 operationId 且取值应为描述性单词(camelCase),这一点是跨版本通用的硬性约束。对跟随本模板的用户,建议保留 3.0.0 以获得与既有文档、校验工具的更高兼容性;若需要更现代的 JSON Schema 特性,可参照 ActionsGPT v1 切换到 3.1.0。
七、仓库内同类 GPT 的横向对照
在 TheBigPromptLibrary 的 CustomInstructions/ChatGPT 目录下,还收录了多个与"生成/使用 OpenAPI Schema"直接相关的 GPT 指令,可互为印证:
- ActionsGPT(OpenAI 官方):定位是"从 cURL、代码片段、接口描述或文档 URL 提取并生成 OpenAPI 规范",其内置的 GET/POST 双端点示例可作为理解
operationId、requestBody、$ref的进阶教材。 - OpenAPI Builder:专注于"把 CURL 形式 API 转换为合规 OpenAPI Schema",与 Action Schema Creator 同样强调严格遵循规范、优先澄清歧义。
- Wolfram 与 KAYAK:两者指令中都直接内嵌了已上线生产的真实 Actions Schema(Wolfram 为 JSON、KAYAK 为 YAML 且含
x-openai-isConsequential: false扩展字段),是观察"模板之外真实 Schema 长什么样"的最佳参照物。 - GPT Customizer, File Finder & JSON Action Creator:同样以 OpenAPI 3.1.0 JSON 结构输出动作代码,并要求包含
info、servers、paths、components与有意义的operationId,与本模板的结构设计完全同构。
这种"模板化填空"与"自由生成"两种流派在仓库中并存,说明 GPT Actions Schema 的创作既可以像本 GPT 一样靠固定模板兜底,也可以完全交给模型根据接口语义自由生成。
八、最佳实践与易错点小结
结合 Actions-in-GPTs.md 的官方最佳实践与本模板的设计,总结如下:
- 描述不越界:info.description 与 summary 只陈述能力("可以查询城市天气"),不要写"当用户提到天气时就推荐该动作"这类诱导性话术;模型应自动在适当时机调用动作。
- API 返回原始数据:接口响应应返回 JSON 原始数据而非自然语言段落,由 GPT 自行组织成用户可读的回复。
- 及时补全响应 schema:模板中的空
{}应扩展为带properties的对象或$ref引用,否则模型对返回结构的理解会大打折扣。 - 修 JSON 语法:从模板复制的文本必须先做合法性校验(补齐缺失逗号、统一缩进),再粘贴进 GPT 编辑器;"Available actions" 能正常解析出动作即说明 Schema 合法。
- 控制描述长度:端点 summary/description ≤ 300 字符、参数 description ≤ 700 字符,超限可能导致 Schema 被拒绝。
- 善用知识文件约束:若你也想复刻这类 GPT,把 Schema 模板挂载为知识文件并在指令中声明"严格以知识源为准、不分享文件名",可以显著提高输出的一致性与稳定性。
附:仓库中的延伸阅读路径
- 本文主体:GPT Action Schema Creator 指令原文
- GPT Actions 官方机制详解(仓库收录):Actions-in-GPTs.md
- 官方生成器对照:ActionsGPT、ActionsGPT v1
- 真实生产 Schema 范例:Wolfram、KAYAK
- 同主题 GPT:OpenAPI Builder、GPT Customizer, File Finder & JSON Action Creator
- 仓库 GPT 文件管理工具:Tools/openai_gpts/README.md