开发ChatGPT插件-入门

探索ChatGPT，学习开发一款插件，成为先锋者，一同成长。加入「阿杰与AI」公众号，关注AI发展趋势，等待AI机会出现。

• 1.如何访问插件？
• 2.开发ChatGPT插件-介绍
• 3.开发ChatGPT插件-入门
• 4.开发ChatGPT插件-认证
• 5.开发ChatGPT插件-示例插件
• 6.开发ChatGPT插件-审核
• 7.开发ChatGPT插件-线上插件及常见问题

创建一个插件需要3个步骤：

1. 构建一个API
2. 使用OpenAPI的yaml或JSON格式对API进行文档化
3. 创建一个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 Plugin
  description: 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: getTodos
      summary: Get the list of todos
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getTodosResponse'
components:
  schemas:
    getTodosResponse:
      type: object
      properties:
        todos:
          type: array
          items:
            type: string
          description: 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 requests
    import os
  
    import yaml
    from flask import Flask, jsonify, Response, request, send_from_directory
    from flask_cors import CORS
  
    app = Flask(__name__)
  
    PORT = 3333
  
    # Note: Setting CORS to allow chat.openapi.com is required for ChatGPT to access your plugin
    CORS(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.content
  
  
    if __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的机会。