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

逃离我推掉我的手 2024-03-24 15:56 100阅读 0赞

### ChatGPT Plugin 介绍 ###

最近，OpenAI 宣布了一个重大的更新： ChatGPT 支持 Plugin 能力。用户在与 ChatGPT 自然语言交互时，可以选择使用插件。通过插件扩展，可以实现让 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 规范格式][OpenAPI] 的 API 文档文件，指定一个或多个开放的 API Endpoint（指具体的某个 API）。这些文件定义了插件的功能，允许 ChatGPT 读取这些文件，并调用开发人员定义的 API。一句话描述就是：**AI 模型充当了智能 API 的调用方**。给定 API 规范和有关何时使用 API 的自然语言描述，模型会主动调用 API 来执行操作。

### 插件从构建到使用的流程 ###

截止目前时间（2023 年 3 月 30 日），ChatGPT 插件仍然处于有限的 alpha 版本阶段，所以需要加入[等待列表][Link 1]以排队获取访问权限。在 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 协议][OpenGraph]，openAI 在其中提取 site\_name, title, description, image, url 字段）”

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

### 插件与 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 规范的来源 ####

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

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

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

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

1.  优先进行 API 与业务代码的开发，开发完成并通过单元测试后，由技术人员根据实际开发的代码编写出 OpenAPI 规范文档。这种工作方式我们称之为：**Code First**；
2.  优先进行 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 插件。

[ChatGPT]: https://apifox.com/apiskills/chatgpt-plugin-application-scenario/
[OpenAPI]: https://openapi.xiniushu.com/
[Link 1]: https://openai.com/waitlist/plugins
[ChatGPT UI]: https://chat.openai.com/
[OpenGraph]: https://ogp.me/
[OpenAI]: https://openai.xiniushu.com/docs/plugins/introduction
[Link 2]: https://platform.openai.com/docs/plugins/introduction
[GitHub]: https://github.com/OAI/OpenAPI-Specification