API First 再先一步，OpenAPI 定义被 openAI 定为 ChatGPT 插件标准

Plory Joe

2023-03-30

ChatGPT Plugin 介绍

最近，OpenAI 宣布了一个重大的更新： ChatGPT 支持 Plugin 能力。用户在与 ChatGPT 自然语言交互时，可以选择使用插件。通过插件扩展，可以实现让 ChatGPT 实现以下能力：

检索实时信息，例如：体育比分、股票价格、最新消息等。
检索知识库信息，例如：公司文档、个人笔记等。
代表用户执行操作，例如：订机票、订餐等。

举具体例子，用户想要使用 ChatGPT 来查询某个城市的酒店信息，只需要安装并允许使用一个酒店搜索的插件，然后就可以通过简单的对话来获取酒店的名称、价格、评分、位置等信息；如果用户想要使用 ChatGPT 来学习某个编程语言，他们只需要安装并允许使用一个编程教程的插件，然后就可以通过互动式的问答来掌握编程的基础知识和技巧。更多详细的例子可以查看这篇文章：ChatGPT 插件应用场景有哪些？

Openai is offering a web browsing plugin and a code execution plugin, and open-sourcing the code for a retrieval plugin. Plugins are very experimental still but we think there's something great in this direction; it's been a heavily requested feature.

OpenAI正在提供一个网页浏览插件和一个代码执行插件，并开源检索插件的代码。插件仍然非常实验性，但我们认为在这个方向上有很大的潜力；这是一个备受期待的功能。

-Sam Altman，CEO of OpenAI

插件背后的技术原理

插件开发人员通过标准的 manifest 文件和 OpenAPI 规范格式的 API 文档文件，指定一个或多个开放的 API Endpoint（指具体的某个 API）。这些文件定义了插件的功能，允许 ChatGPT 读取这些文件，并调用开发人员定义的 API。一句话描述就是：AI 模型充当了智能 API 的调用方。给定 API 规范和有关何时使用 API 的自然语言描述，模型会主动调用 API 来执行操作。

插件从构建到使用的流程

截止目前时间（2023 年 3 月 30 日），ChatGPT 插件仍然处于有限的 alpha 版本阶段，所以需要加入等待列表以排队获取访问权限。在 alpha 版本期间，openAI 也承诺会充分和用户与开发人员合作迭代插件系统，所以最后上线的插件功能可能也会有一些变化，这也是想要提前体验与成为插件开发者需要去注意的很重要的点。

创建清单（manifest）文件

将该文件托管在 yourdomain.com/.well-known/ai-plugin.json
该文件包含有关插件的元数据（名称、徽标等），身份验证信息（身份验证类型、OAuth URL 等），以及 OpenAPI 规范格式的 API 文档文件。
该模型将看到 OpenAPI 规范描述的字段，可用于为这些字段提供自然语言描述。
建议在开始时仅公开 1-2 个端点，并使用最少数量的参数来最小化文本的长度。插件描述、API 请求和 API 响应都被插入到与 ChatGPT 的对话中。过多的内容会影响模型的上下文长度限制。

在 ChatGPT UI 中注册插件

从顶部下拉列表中选择插件模型，然后选择“Plugins（插件）”、“Plugin Store（插件商店）”，最后选择“Install an unverified plugin（安装未经验证的插件）”或“Develop your own plugin（开发自己的插件）”。
如果需要身份验证，需要提供 OAuth 2 client_id 和 client_secret 或 API Key

用户激活你的插件

用户必须在 ChatGPT UI 中手动激活你的插件(ChatGPT 不会默认使用你的插件)。
在 alpha 测试期间，插件开发人员将能够与 15 个其他用户共享其插件(目前只有其他开发人员可以安装未经验证的插件)。随着时间推移，openAI 将推出一种提交你的插件进行审核以暴露给所有 ChatGPT 用户群体的方式。
如果需要认证，则用户将通过 OAuth 重定向到你的插件；你还可以选择在此处创建新帐户。
未来，openAI 可能会构建功能来帮助用户发现有用和流行的插件。

用户开始对话

OpenAI 将在发送给 ChatGPT 的消息中插入对你的插件的简洁描述，但最终用户是看不到的。这将包括插件描述、Endpoint（指具体的某个 API）和示例。
当用户提出相关问题时，如果看起来相关，模型可能会选择从你的插件调用 API 调用；对于 POST 请求，openAI 要求开发人员构建用户确认流程。
该模型会将 API 结果合并到其对用户的响应中。
该模型的响应中可能包含从 API 调用返回的链接。这些将显示为丰富的预览（使用 OpenGraph 协议，openAI 在其中提取 site_name, title, description, image, url 字段）”

需要了解关于插件的更多详情，可以在 OpenAI 中文文档中进行查看。当然你也可以去官方文档中查看。

插件与 OpenAPI

在上面的文章内容中，我们介绍了插件的核心能力与基本的技术实现原理。其中提到很重要的一点：如果想要做到让 AI 模型通过插件作为你 API 的智能调用方，则你必须将你的 API 以 OpenAPI 规范格式的文档放在清单文件中。因为只有当你的 API 文档符合这个规范，才能被 AI 模型理解并真正执行成功调用你的 API。

为什么 OpenAPI 规范会被 OpenAI 采纳作为自己插件能力调用 API 的标准格式呢？这就要理解 OpenAPI 规范到底是什么，以及它是怎么形成的。了解了这些内容之后，就可以知道 openAI 公司为何把 OpenAPI 规范作为自己旗下最火产品 ChatGPT 的插件能力标准了。

OpenAPI 规范是什么

OpenAPI 规范（OpenAPI Specification）是一种开放的、标准化的、机器可读的 API 描述格式，它可以帮助开发者快速地创建、测试、发布和维护 API。OpenAPI 也可以用来生成 API 的文档、客户端代码、服务器代码等。

OpenAPI 的规范由 OpenAPI Initiative（OAI）组织制定和维护，目前最新的版本是 3.1.0。OpenAPI 规范使用 JSON 或 YAML 语言来定义 API 的元数据、路径、参数、响应、安全等信息。OpenAPI 规范是一种通用的和语言无关的接口，它可以让人类和计算机都能够发现和理解 API 的能力，而不需要访问源代码、额外的文档或网络流量检查。

深入了解：OpenAPI 规范 (中文版)

OpenAPI 规范的来源

OpenAPI 规范是由 Tony Tam 在 2009 年创立的，当时他是 Wordnik 公司的一名工程师，他想要描述 Wordnik 的在线词典 JSON API，于是创建了一个规范，叫做 Swagger。Swagger 在接下来的几年里经过了多次迭代和改进。在 2015 年，SmartBear Software 公司收购了 Swagger 规范，并在同年将其捐赠给了 Linux Foundation 下的一个新组织，叫做 OpenAPI Initiative（OAI），该组织由多家公司共同组成，旨在推动和维护 OpenAPI 规范的发展。

从 2016 年开始，Swagger 规范正式更名为 OpenAPI 规范，并迁移到了一个新的 GitHub 仓库。从那时起，OpenAPI 规范就不断地更新和完善。

通过 API First 工作方式来提升你的插件开发效率

我们现在可以理解，一个符合规范的 API 文档是有多么的重要。有了这份文档，人类、机器就能够更好的理解你的 API。在 API 开发过程中，一般来说，常见的产生符合 OpenAPI 规范文档的方式有两种：

优先进行 API 与业务代码的开发，开发完成并通过单元测试后，由技术人员根据实际开发的代码编写出 OpenAPI 规范文档。这种工作方式我们称之为：Code First；
优先进行 API 的定义并基于 OpenAPI 规范编写文档，根据这份规范的 API 文档来进行实际的代码开发工作。这种工作方式我们称之为：API First。

Code First 与 API First，两者都可以写出符合 OpenAPI 规范的文档，但是它们有着不同的应用场景与优缺点。

对于 API First 来说：

强调 API 的重要性，把 API 作为业务的核心资产；
更能保证 API 的质量与一致性；
整体开发效率更高，可以基于 OpenAPI 规范的定义来模拟 API ，无需等待 API 代码部署，来更好的进行前后端协同、测试工作。

对于 Code First 来说：

更灵活、直观；
无需额外的设计工作，更适合简单、临时的 API ，或者一些已经存在的代码库。

总之，API First 是一个可以提升效率的工作流程，它的底层思想跟 OKR 工作方式也挺类似，优先定义工作目标、实现规范，从而让所有人的工作协同更好效率更高。

如果你最近想要开发一个 ChatGPT 的插件，一般情况下来说，必然已经对这个插件在什么场景想要做到什么效果，有一个清晰、明确的结论。所以，如果你采用 API First 工作流程，在开发工作开始之前事先将这个能力抽象定义出来并且制作出一个 OpenAPI 规范文档，就有以下明显的好处了：

如果你是一个团队来对这个插件进行开发，你们团队的所有成员都会因为这个优先制作好的 OpenAPI 规范文档达成共识，每个人都明确的知道自己需要开发的目标是什么，避免出现实际开发代码与目标偏离的悲剧；
可以通过搭建一个该接口的模拟服务器，来模拟 ChatGPT 在调用之后的结果，进行调试，了解实际效果。而非等万事具备之后再来看开发效果是否符合预期；
Q&A 工作可以与代码开发工作同步开始，边进行代码开发边编写测试用例，加快你的插件发布与迭代节奏。

以上就是对于 ChatGPT 插件、OpenAPI、API First 的简单介绍，希望这篇文章能够帮助到你更加高效的开发出你的 ChatGPT 插件。