API First 再先一步，OpenAPI 定義被 openAI 定為 ChatGPT 插件標(biāo)準(zhǔn)
ChatGPT Plugin 介紹
最近，OpenAI 宣布了一個重大的更新： ChatGPT 支持 Plugin 能力。用戶在與 ChatGPT 自然語言交互時，可以選擇使用插件。通過插件擴(kuò)展，可以實現(xiàn)讓 ChatGPT 實現(xiàn)以下能力：
檢索實時信息，例如：體育比分、股票價格、最新消息等。
檢索知識庫信息，例如：公司文檔、個人筆記等。
代表用戶執(zhí)行操作，例如：訂機(jī)票、訂餐等。
舉具體例子，用戶想要使用 ChatGPT 來查詢某個城市的酒店信息，只需要安裝并允許使用一個酒店搜索的插件，然后就可以通過簡單的對話來獲取酒店的名稱、價格、評分、位置等信息；如果用戶想要使用 ChatGPT 來學(xué)習(xí)某個編程語言，他們只需要安裝并允許使用一個編程教程的插件，然后就可以通過互動式的問答來掌握編程的基礎(chǔ)知識和技巧。更多詳細(xì)的例子可以查看這篇文章：ChatGPT 插件應(yīng)用場景有哪些？（https://apifox.com/apiskills/chatgpt-plugin-application-scenario/）
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正在提供一個網(wǎng)頁瀏覽插件和一個代碼執(zhí)行插件，并開源檢索插件的代碼。 插件仍然非常實驗性，但我們認(rèn)為在這個方向上有很大的潛力；這是一個備受期待的功能。-Sam Altman，CEO of OpenAI
插件背后的技術(shù)原理
插件開發(fā)人員通過標(biāo)準(zhǔn)的 manifest 文件和?OpenAPI 規(guī)范格式?的 API 文檔文件，指定一個或多個開放的 API Endpoint（指具體的某個 API）。這些文件定義了插件的功能，允許 ChatGPT 讀取這些文件，并調(diào)用開發(fā)人員定義的 API。一句話描述就是：AI 模型充當(dāng)了智能 API 的調(diào)用方。給定 API 規(guī)范和有關(guān)何時使用 API 的自然語言描述，模型會主動調(diào)用 API 來執(zhí)行操作。
插件從構(gòu)建到使用的流程
截止目前時間（2023 年 3 月 30 日），ChatGPT 插件仍然處于有限的 alpha 版本階段，所以需要加入等待列表以排隊獲取訪問權(quán)限。在 alpha 版本期間，openAI 也承諾會充分和用戶與開發(fā)人員合作迭代插件系統(tǒng)，所以最后上線的插件功能可能也會有一些變化，這也是想要提前體驗與成為插件開發(fā)者需要去注意的很重要的點。
創(chuàng)建清單（manifest）文件
將該文件托管在?
yourdomain.com/.well-known/ai-plugin.json該文件包含有關(guān)插件的元數(shù)據(jù)（名稱、徽標(biāo)等），身份驗證信息（身份驗證類型、OAuth URL 等），以及 OpenAPI 規(guī)范格式的 API 文檔文件。
該模型將看到 OpenAPI 規(guī)范描述的字段，可用于為這些字段提供自然語言描述。
建議在開始時僅公開 1-2 個端點，并使用最少數(shù)量的參數(shù)來最小化文本的長度。插件描述、API 請求和 API 響應(yīng)都被插入到與 ChatGPT 的對話中。過多的內(nèi)容會影響模型的上下文長度限制。
在?ChatGPT UI?中注冊插件
從頂部下拉列表中選擇插件模型，然后選擇“Plugins（插件）”、“Plugin Store（插件商店）”，最后選擇“Install an unverified plugin（安裝未經(jīng)驗證的插件）”或“Develop your own plugin（開發(fā)自己的插件）”。
如果需要身份驗證，需要提供 OAuth 2 client_id 和 client_secret 或 API Key
用戶激活你的插件
用戶必須在 ChatGPT UI 中手動激活你的插件(ChatGPT 不會默認(rèn)使用你的插件)。
在 alpha 測試期間，插件開發(fā)人員將能夠與 15 個其他用戶共享其插件(目前只有其他開發(fā)人員可以安裝未經(jīng)驗證的插件)。隨著時間推移，openAI 將推出一種提交你的插件進(jìn)行審核以暴露給所有 ChatGPT 用戶群體的方式。
如果需要認(rèn)證，則用戶將通過 OAuth 重定向到你的插件；你還可以選擇在此處創(chuàng)建新帳戶。
未來，openAI 可能會構(gòu)建功能來幫助用戶發(fā)現(xiàn)有用和流行的插件。
用戶開始對話
OpenAI 將在發(fā)送給 ChatGPT 的消息中插入對你的插件的簡潔描述，但最終用戶是看不到的。這將包括插件描述、Endpoint（指具體的某個 API）和示例。
當(dāng)用戶提出相關(guān)問題時，如果看起來相關(guān)，模型可能會選擇從你的插件調(diào)用 API 調(diào)用；對于 POST 請求，openAI 要求開發(fā)人員構(gòu)建用戶確認(rèn)流程。
該模型會將 API 結(jié)果合并到其對用戶的響應(yīng)中。
該模型的響應(yīng)中可能包含從 API 調(diào)用返回的鏈接。這些將顯示為豐富的預(yù)覽（使用?OpenGraph 協(xié)議，openAI 在其中提取 site_name, title, description, image, url 字段）”
需要了解關(guān)于插件的更多詳情，可以在?OpenAI 中文文檔?中進(jìn)行查看。當(dāng)然你也可以去官方文檔中查看。
插件與 OpenAPI
在上面的文章內(nèi)容中，我們介紹了插件的核心能力與基本的技術(shù)實現(xiàn)原理。其中提到很重要的一點：如果想要做到讓 AI 模型通過插件作為你 API 的智能調(diào)用方，則你必須將你的 API 以 OpenAPI 規(guī)范格式的文檔放在清單文件中。因為只有當(dāng)你的 API 文檔符合這個規(guī)范，才能被 AI 模型理解并真正執(zhí)行成功調(diào)用你的 API。
為什么 OpenAPI 規(guī)范會被 OpenAI 采納作為自己插件能力調(diào)用 API 的標(biāo)準(zhǔn)格式呢？這就要理解 OpenAPI 規(guī)范到底是什么，以及它是怎么形成的。了解了這些內(nèi)容之后，就可以知道 openAI 公司為何把 OpenAPI 規(guī)范作為自己旗下最火產(chǎn)品 ChatGPT 的插件能力標(biāo)準(zhǔn)了。
OpenAPI 規(guī)范是什么
OpenAPI 規(guī)范（OpenAPI Specification）是一種開放的、標(biāo)準(zhǔn)化的、機(jī)器可讀的 API 描述格式，它可以幫助開發(fā)者快速地創(chuàng)建、測試、發(fā)布和維護(hù) API。OpenAPI 也可以用來生成 API 的文檔、客戶端代碼、服務(wù)器代碼等。
OpenAPI 的規(guī)范由 OpenAPI Initiative（OAI）組織制定和維護(hù)，目前最新的版本是 3.1.0。OpenAPI 規(guī)范使用 JSON 或 YAML 語言來定義 API 的元數(shù)據(jù)、路徑、參數(shù)、響應(yīng)、安全等信息。OpenAPI 規(guī)范是一種通用的和語言無關(guān)的接口，它可以讓人類和計算機(jī)都能夠發(fā)現(xiàn)和理解 API 的能力，而不需要訪問源代碼、額外的文檔或網(wǎng)絡(luò)流量檢查。
深入了解：OpenAPI 規(guī)范 (中文版)（https://openapi.xiniushu.com/）
OpenAPI 規(guī)范的來源
OpenAPI 規(guī)范是由 Tony Tam 在 2009 年創(chuàng)立的，當(dāng)時他是 Wordnik 公司的一名工程師，他想要描述 Wordnik 的在線詞典 JSON API，于是創(chuàng)建了一個規(guī)范，叫做 Swagger。Swagger 在接下來的幾年里經(jīng)過了多次迭代和改進(jìn)。在 2015 年，SmartBear Software 公司收購了 Swagger 規(guī)范，并在同年將其捐贈給了 Linux Foundation 下的一個新組織，叫做 OpenAPI Initiative（OAI），該組織由多家公司共同組成，旨在推動和維護(hù) OpenAPI 規(guī)范的發(fā)展。
從 2016 年開始，Swagger 規(guī)范正式更名為 OpenAPI 規(guī)范，并遷移到了一個新的?GitHub 倉庫。從那時起，OpenAPI 規(guī)范就不斷地更新和完善。
通過 API First 工作方式來提升你的插件開發(fā)效率
我們現(xiàn)在可以理解，一個符合規(guī)范的 API 文檔是有多么的重要。有了這份文檔，人類、機(jī)器就能夠更好的理解你的 API。在 API 開發(fā)過程中，一般來說，常見的產(chǎn)生符合 OpenAPI 規(guī)范文檔的方式有兩種：
優(yōu)先進(jìn)行 API 與業(yè)務(wù)代碼的開發(fā)，開發(fā)完成并通過單元測試后，由技術(shù)人員根據(jù)實際開發(fā)的代碼編寫出 OpenAPI 規(guī)范文檔。這種工作方式我們稱之為：Code First；
優(yōu)先進(jìn)行 API 的定義并基于 OpenAPI 規(guī)范編寫文檔，根據(jù)這份規(guī)范的 API 文檔來進(jìn)行實際的代碼開發(fā)工作。這種工作方式我們稱之為：API First。
Code First 與 API First，兩者都可以寫出符合 OpenAPI 規(guī)范的文檔，但是它們有著不同的應(yīng)用場景與優(yōu)缺點。
對于 API First 來說：
強(qiáng)調(diào) API 的重要性，把 API 作為業(yè)務(wù)的核心資產(chǎn)；
更能保證 API 的質(zhì)量與一致性；
整體開發(fā)效率更高，可以基于 OpenAPI 規(guī)范的定義來模擬 API ，無需等待 API 代碼部署，來更好的進(jìn)行前后端協(xié)同、測試工作。
對于 Code First 來說：
更靈活、直觀；
無需額外的設(shè)計工作，更適合簡單、臨時的 API ，或者一些已經(jīng)存在的代碼庫。
總之，API First 是一個可以提升效率的工作流程，它的底層思想跟 OKR 工作方式也挺類似，優(yōu)先定義工作目標(biāo)、實現(xiàn)規(guī)范，從而讓所有人的工作協(xié)同更好效率更高。
如果你最近想要開發(fā)一個 ChatGPT 的插件，一般情況下來說，必然已經(jīng)對這個插件在什么場景想要做到什么效果，有一個清晰、明確的結(jié)論。所以，如果你采用 API First 工作流程，在開發(fā)工作開始之前事先將這個能力抽象定義出來并且制作出一個 OpenAPI 規(guī)范文檔，就有以下明顯的好處了：
如果你是一個團(tuán)隊來對這個插件進(jìn)行開發(fā)，你們團(tuán)隊的所有成員都會因為這個優(yōu)先制作好的 OpenAPI 規(guī)范文檔達(dá)成共識，每個人都明確的知道自己需要開發(fā)的目標(biāo)是什么，避免出現(xiàn)實際開發(fā)代碼與目標(biāo)偏離的悲??；
可以通過搭建一個該接口的模擬服務(wù)器，來模擬 ChatGPT 在調(diào)用之后的結(jié)果，進(jìn)行調(diào)試，了解實際效果。而非等萬事具備之后再來看開發(fā)效果是否符合預(yù)期；
Q&A 工作可以與代碼開發(fā)工作同步開始，邊進(jìn)行代碼開發(fā)邊編寫測試用例，加快你的插件發(fā)布與迭代節(jié)奏。
以上就是對于 ChatGPT 插件、OpenAPI、API First 的簡單介紹，希望這篇文章能夠幫助到你更加高效的開發(fā)出你的 ChatGPT 插件。
