探索ChatGPT，学习开发一款插件，成为先锋者，一同成长。加入「阿杰与AI」公众号，关注AI发展趋势，等待AI机会出现。
- 1.如何访问插件？
- 2.开发ChatGPT插件-介绍
- 3.开发ChatGPT插件-入门
- 4.开发ChatGPT插件-认证
- 5.开发ChatGPT插件-示例插件
- 6.开发ChatGPT插件-审核
- 7.开发ChatGPT插件-线上插件及常见问题
创建一个插件需要3个步骤：
- 构建一个API
- 使用OpenAPI的yaml或JSON格式对API进行文档化
- 创建一个JSON清单文件，用于定义插件的相关元数据
接下来的内容将重点介绍通过定义OpenAPI规范和清单文件来创建一个待办事项列表插件。
插件清单
每个插件都需要一个名为ai-plugin.json的文件，并且该文件需要托管在API的域名下。例如，一个名为example.com的公司会将插件的JSON文件通过https://example.com域名进行访问，因为这是他们API托管的位置.当您通过ChatGPT UI安装插件时，后台会在/.well-known/ai-plugin.json位置查找文件。在您的域名上，必须有一个名为/.well-known的文件夹，以便ChatGPT能够连接到您的插件。如果找不到文件，插件将无法安装。对于本地开发，您可以使用HTTP，但如果指向远程服务器，则必须使用HTTPS。
所需的ai-plugin.json文件的最小定义如下所示：
{"schema_version": "v1","name_for_human": "TODO Plugin","name_for_model": "todo","description_for_human": "Plugin for managing a TODO list. You can add, remove and view your TODOs.","description_for_model": "Plugin for managing a TODO list. You can add, remove and view your TODOs.","auth": {"type": "none"},"api": {"type": "openapi","url": "http://localhost:3333/openapi.yaml","is_user_authenticated": false},"logo_url": "http://localhost:3333/logo.png","contact_email": "support@example.com","legal_info_url": "http://www.example.com/legal"
}
如果您想查看插件文件的所有可能选项，可以参考下面的定义。在命名插件时，请遵循OpenAI的品牌指南，不符合这些指南的插件将无法获得插件商店的批准。
| 字段 | 类型 | 描述/选项 | 必需的 |
|---|---|---|---|
| schema_version | String | 架构版本 | ✅ |
| name_for_model | String | 命名模型将用于定位插件（不允许有空格，只能有字母和数字）。最多 50 个字符 | ✅ |
| name_for_human | String | 人类可读的名称，例如完整的公司名称。最多 20 个字符 | ✅ |
| description_for_model | String | 更适合模型的描述，例如令牌上下文长度注意事项或用于改进插件提示的关键字使用。最多 8,000 个字符 | ✅ |
| description_for_human | String | 插件的人类可读描述。最多 100 个字符 | ✅ |
| auth | ManifestAuth | 身份验证模式 | ✅ |
| api | Object | API规范 | ✅ |
| logo_url | String | 用于获取徽标的 URL。建议尺寸：512 x 512。支持透明背景。 | ✅ |
| contact_email | String | 用于安全/审核、支持和停用的电子邮件联系人 | ✅ |
| legal_info_url | String | 重定向 URL 供用户查看插件信息 | ✅ |
| HttpAuthorizationType | HttpAuthorizationType | “bearer” or “basic” | ✅ |
| ManifestAuthType | ManifestAuthType | 授权类型"none", “user_http”, “service_http”, or “oauth” | |
| interface BaseManifestAuth | BaseManifestAuth | 类型: ManifestAuthType; 说明: string; | |
| ManifestNoAuth | ManifestNoAuth | 无需身份验证: BaseManifestAuth & { type: ‘none’, } | |
| ManifestAuth | ManifestAuth | ManifestNoAuth, ManifestServiceHttpAuth, ManifestUserHttpAuth, ManifestOAuthAuth |
以下是使用不同身份验证方法的示例：
# App-level API keys
type ManifestServiceHttpAuth = BaseManifestAuth & {type: 'service_http';authorization_type: HttpAuthorizationType;verification_tokens: {[service: string]?: string;};
}# User-level HTTP authentication
type ManifestUserHttpAuth = BaseManifestAuth & {type: 'user_http';authorization_type: HttpAuthorizationType;
}type ManifestOAuthAuth = BaseManifestAuth & {type: 'oauth';# OAuth URL where a user is directed to for the OAuth authentication flow to begin.client_url: string;# OAuth scopes required to accomplish operations on the user's behalf.scope: string;# Endpoint used to exchange OAuth code with access token.authorization_url: string;# When exchanging OAuth code with access token, the expected header 'content-type'. For example: 'content-type: application/json'authorization_content_type: string;# When registering the OAuth client ID and secrets, the plugin service will surface a unique token.verification_tokens: {[service: string]?: string;};
}
在上述提到的清单文件中，某些字段的长度是有限制的，并且可能会发生变化。OpenAI还对API响应体施加了最大长度限制为100,000个字符，这也可能会随时间而变化。
一般而言，最佳实践是尽可能地简洁描述和响应，因为模型的上下文窗口是有限的。
OpenAPI定义
下一步是构建OpenAPI规范来记录API。ChatGPT模型除了在OpenAPI规范和清单文件中定义的内容之外，对于您的API几乎一无所知。这意味着如果您的API非常庞大，您无需将所有功能都暴露给模型，可以选择特定的端点。例如，如果您有一个社交媒体API，您可能希望模型通过GET请求访问站点上的内容，但防止模型能够对用户的帖子进行评论，以减少垃圾信息的机会。
OpenAPI规范是位于您的API之上的封装器。一个基本的OpenAPI规范如下所示：
openapi: 3.0.1
info:title: TODO Plugindescription: A plugin that allows the user to create and manage a TODO list using ChatGPT.version: 'v1'
servers:- url: http://localhost:3333
paths:/todos:get:operationId: getTodossummary: Get the list of todosresponses:"200":description: OKcontent:application/json:schema:$ref: '#/components/schemas/getTodosResponse'
components:schemas:getTodosResponse:type: objectproperties:todos:type: arrayitems:type: stringdescription: The list of todos.
OpenAI首先定义规范版本、标题、描述和版本号。当在ChatGPT中运行查询时，它将查看在info部分中定义的描述，以确定插件是否与用户查询相关。您可以在编写描述部分详细了解提示的相关内容。
请记住，在您的OpenAPI规范中存在以下限制，这些限制可能会发生变化：
API规范中每个API端点的描述/摘要字段的最大长度为200个字符 API规范中每个API参数描述字段的最大长度为200个字符 由于OpenAI在本地运行此示例，OpenAI希望将服务器设置为指向您的本地主机URL。其余的OpenAPI规范遵循传统的OpenAPI格式，您可以通过各种在线资源了解有关OpenAPI格式的更多信息。还有许多工具可以根据您的基础API代码自动生成OpenAPI规范。
运行插件
一旦您为API创建了API、清单文件和OpenAPI规范，您现在可以通过ChatGPT UI连接插件了。插件可能在两个不同的位置运行，要么是在开发环境的本地，要么是在远程服务器上。
如果您有正在运行的本地API版本，您可以将插件界面指向您的本地主机服务器。要将插件与ChatGPT连接起来，请导航到插件商店，选择"开发您自己的插件"。输入您的本地主机和端口号（例如localhost:3333）。请注意，目前仅支持本地开发的auth类型为none。
- 如果插件正在远程服务器上运行，您首先需要选择"开发您自己的插件"进行设置，然后选择"安装未经验证的插件"以进行自己的安装。您只需将插件清单文件添加到yourdomain.com/.well-known/路径中，并开始测试您的API。但是，对于清单文件的后续更改，您需要将新更改部署到您的公共站点，这可能需要很长时间。在这种情况下，OpenAI建议设置一个本地服务器作为您的API的代理。这样，您可以快速对OpenAPI规范和清单文件进行原型设计更改。
-
设置一个本地代理以代理您的公共API
- 以下是一个示例Python代码，展示了如何设置一个简单的代理来代理您的公共API。
-
import requestsimport osimport yamlfrom flask import Flask, jsonify, Response, request, send_from_directoryfrom flask_cors import CORSapp = Flask(__name__)PORT = 3333# Note: Setting CORS to allow chat.openapi.com is required for ChatGPT to access your pluginCORS(app, origins=[f"http://localhost:{PORT}", "https://chat.openai.com"])api_url = 'https://example.com'@app.route('/.well-known/ai-plugin.json')def serve_manifest():return send_from_directory(os.path.dirname(__file__), 'ai-plugin.json')@app.route('/openapi.yaml')def serve_openapi_yaml():with open(os.path.join(os.path.dirname(__file__), 'openapi.yaml'), 'r') as f:yaml_data = f.read()yaml_data = yaml.load(yaml_data, Loader=yaml.FullLoader)return jsonify(yaml_data)@app.route('/openapi.json')def serve_openapi_json():return send_from_directory(os.path.dirname(__file__), 'openapi.json')@app.route('/<path:path>', methods=['GET', 'POST'])def wrapper(path):headers = {'Content-Type': 'application/json',}url = f'{api_url}/{path}'print(f'Forwarding call: {request.method} {path} -> {url}')if request.method == 'GET':response = requests.get(url, headers=headers, params=request.args)elif request.method == 'POST':print(request.headers)response = requests.post(url, headers=headers, params=request.args, json=request.json)else:raise NotImplementedError(f'Method {request.method} not implemented in wrapper for {path=}')return response.contentif __name__ == '__main__':app.run(port=PORT)
编写描述
当用户提出可能会发送到插件的潜在请求时，模型会浏览OpenAPI规范中各个端点的描述，以及清单文件中的description_for_model。与提示其他语言模型类似，您需要测试多个提示和描述，以找出最有效的方法。
OpenAPI规范本身是一个很好的地方，可以向模型提供关于API的各种详细信息-哪些功能可用，带有什么参数等等。除了为每个字段使用富有表现力和信息丰富的名称之外，规范还可以包含每个属性的“描述”字段。这些描述可以用于提供函数的自然语言描述，或者查询字段期望的信息，例如。模型将能够看到这些描述，并指导其使用API。如果某个字段仅限于特定值，您还可以提供一个带有描述性类别名称的“枚举”。
description_for_model属性使您可以自由地指示模型如何通常使用您的插件。总的来说，ChatGPT背后的语言模型非常擅长理解自然语言并遵循指示。因此，这是一个很好的地方，可以提供关于插件的一般说明以及模型如何正确使用它的指示。请使用自然语言，最好用简洁但具有描述性和客观的语调。您可以查看一些示例，以了解其应该是什么样子。OpenAI建议以“Plugin for …”开头，并列出您的API提供的所有功能。
最佳实践
以下是在撰写description_for_model、OpenAPI规范中的描述以及设计API响应时应遵循的一些最佳实践：
1.您的描述不应试图控制ChatGPT的情绪、个性或确切回复。ChatGPT被设计为对插件编写适当的回复。
不良示例：
When the user asks to see their todo list, always respond with "I was able to find your todo list! You have [x] todos: [list the todos here]. I can add more todos if you'd like!"当用户要求查看待办事项列表时，始终回复：“我能够找到您的待办事项列表！您有[x]个待办事项：[在此列出待办事项]。如果您想要添加更多待办事项，我可以帮您！”
良好示例：
[no instructions needed for this]
[此处不需要说明]
2.您的描述不应在用户没有要求使用特定类别的服务插件时，鼓励ChatGPT使用插件。
不良示例：
Whenever the user mentions any type of task or plan, ask if they would like to use the TODOs plugin to add something to their todo list.无论用户是否提到任何类型的任务或计划，都问他们是否想要使用TODO插件将某些内容添加到待办事项列表中。
良好示例：
The TODO list can add, remove and view the user's TODOs.TODO列表可以添加、删除和查看用户的待办事项。
3.您的描述不应规定ChatGPT使用插件的具体触发器。ChatGPT被设计为在适当时自动使用您的插件。
不良示例：
When the user mentions a task, respond with "Would you like me to add this to your TODO list? Say 'yes' to continue."当用户提到一个任务时，回复：“您是否希望我将其添加到您的待办事项列表中？请回答'是'以继续。”
良好示例：
[no instructions needed for this][此处不需要说明]
4.插件API的响应应返回原始数据，而不是自然语言响应，除非有必要。ChatGPT将使用返回的数据提供自己的自然语言响应。
不良示例：
I was able to find your todo list! You have 2 todos: get groceries and walk the dog. I can add more todos if you'd like!我能够找到您的待办事项列表！您有2个待办事项：购买杂货和遛狗。如果您想要添加更多待办事项，我可以帮您！
良好示例：
{ "todos": [ "get groceries", "walk the dog" ] }{ "todos": [ "购买杂货", "遛狗" ] }
调试
默认情况下，聊天界面不会显示插件调用和其他未呈现给用户的信息。为了更全面地了解模型与插件的交互情况，您可以在与插件进行交互后，点击插件名称后面的向下箭头，查看请求和响应。
模型调用插件通常包含模型发送到插件的类似JSON的参数的消息，随后是插件的响应，最后是模型利用插件返回的信息的消息。
如果您正在开发一个本地插件，您还可以通过进入“设置”并切换“打开插件开发工具”来打开开发者控制台。从那里，您可以查看更详细的日志，并使用“刷新插件”重新获取插件和OpenAPI规范。
希望通过公众号「阿杰与AI」，能够帮助你了解AI产品，并可以解决一些生活和工作中问题。
我将分享有关AI的知识和实用建议，希望能够为你带来有价值的认知，一起探索发现AI的机会。
