开发ChatGPT插件-入门

ChatGPT插件1年前 (2023)更新 潮汐
119 0 0

创建一个插件需要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规范。

© 版权声明

相关文章