文档

插件接入指引

更新时间:

您可以方便地将已有的api接口包装为plugin,仅需提供以下两个文件:

  • 元信息描述文件:ai-plugin.json

  • API描述文件:openapi.yaml

将上述两个文件编写完成后,通过邮件提交给工作人员(dashscope@alibabacloud.com)进行录入确认。

元信息描述文件:ai-plugin.json

元信息描述文件ai-plugin.json描述了插件的基本信息,以下是一个示例,定义了一个管理待办事项的插件:

{
    "schema_version": "v1",
    "name_for_human": "待办事项插件",
    "name_for_model": "todo",
    "description_for_human": "用于管理待办事项列表的插件。您可以添加、删除和查看您的待办事项。",
    "description_for_model": "用于管理待办事项列表的插件。您可以添加、删除和查看您的待办事项。",
    "auth": {
        "type": "none"
    },
    "api": {
        "type": "openapi",
    },
    "logo_url": "http://localhost:3333/logo.png",
    "contact_email": "support@example.com"
}

插件基本信息

字段

类型

描述

是否必填

是否公开

schema_version

String

插件版本号,用于开发者标记

name_for_model

String

对模型展示的插件名称(仅支持字母、数字、下划线),此字段将作为插件的唯一标识。描述请带有一定的语义,不要超过20个字符。

name_for_human

String

插件对外公开的名字。不超过20个字符。

description_for_model

String

面向模型的插件描述信息。请描述插件的核心能力、使用场景等,以指导模型是否触发调用插件。

description_for_human

String

对用户展示的插件介绍

auth

ManifestAuth

插件鉴权信息,详情见下文插件鉴权配置

api

Object

API规范,目前支持openapi,配置为{"type": "openapi"}

logo_url

String

插件图标的URL。建议大小:512 x 512。支持透明背景。必须是图像,不允许使用GIF。

contact_email

String

安全/审核、支持和停用的电子邮件联系方式

插件鉴权配置(auth字段)

不需要鉴权

默认不需要鉴权,可以填写如下auth信息或者不填。

"auth": {
  "type": "none"
}

服务级别token

服务级别token鉴权,调用插件时默认会在Header里加上(“Authorization”: “Bearer service_token”),所有的用户调用使用同一个token。

"auth": {
  "type": "service_http",
  "authorization_type": "bearer",
  "verification_tokens": {
    "dashscope": "替换token信息"
  }
}

用户级别鉴权

用户级别token鉴权,用来实现第三方插件对dashscope平台的鉴权。外部用户通过sdk或dashscope管控台时需手动添加user token信息,dashscope内部调用插件时候会在请求Header里加上(“Authorization”: “Bearer user_token”)。

"auth": {
  "type": "user_http",
  "authorization_type": "bearer",
}

API描述文件:openapi.yaml

我们依照OpenAPI v3协议来提供对于插件API的描述。关于OpenAPI v3的详细字段,您可以参见: OpenAPI v3.0.3

说明
  • OpenAPI v3协议有丰富的字段描述接口信息,但是过于复杂的接口类型和数据类型可能会影响模型生成插件调用参数的质量。如果您的插件调用不符合预期,可以尝试简化接口类型和数据类型。

  • DashScope依照OpenAPI v3协议,支持的是OpenAPI v3协议的部分内容。具体内容会在后文描述。

您可以通过编辑器来编辑和验证API描述文件的正确性。以下是一个示例。

openapi: 3.0.1
info:
  title: TODO Plugin
  description: A plugin that allows the user to create and manage a TODO list using ChatGPT. If you do not know the user's username, ask them first before making queries to the plugin. Otherwise, use the username "global".
  version: 'v1'
servers:
  - url: http://localhost:5003
paths:
  /todos/{username}:
    get:
      operationId: getTodos
      summary: Get the list of todos
      parameters:
      - in: path
        name: username
        schema:
            type: string
        required: true
        description: The name of the user.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getTodosResponse'
    post:
      operationId: addTodo
      summary: Add a todo to the list
      parameters:
      - in: path
        name: username
        schema:
            type: string
        required: true
        description: The name of the user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/addTodoRequest'
      responses:
        "200":
          description: OK
    delete:
      operationId: deleteTodo
      summary: Delete a todo from the list
      parameters:
      - in: path
        name: username
        schema:
            type: string
        required: true
        description: The name of the user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deleteTodoRequest'
      responses:
        "200":
          description: OK

components:
  schemas:
    getTodosResponse:
      type: object
      properties:
        todos:
          type: string
          description: The content of todos.
    addTodoRequest:
      type: object
      required:
      - todo
      properties:
        todo:
          type: string
          description: The todo to add to the list.
    deleteTodoRequest:
      type: object
      required:
      - todo_idx
      properties:
        todo_idx:
          type: integer
          description: The index of the todo to delete.

以下将分别描述schema对应的信息。

openapi对象

指定使用的openapi版本

openapi: 3.0.1

info对象

info:
  title: TODO Plugin
  description: A plugin that allows the user to create and manage a TODO list using ChatGPT. If you do not know the user's username, ask them first before making queries to the plugin. Otherwise, use the username "global".
  version: 'v1'
  • title: 标题

  • description: API 描述

  • version:版本号

servers对象

servers:
  - url: http://localhost:5003
  • URL表示访问服务端的基础路径,即在访问接口前都会带上该参数。

paths 对象

paths:
  /todos/{username}:
    get:

paths表示对象包含真正的 API 信息内容,它的每个项都包含一个可操作的endpoint。

例如上述/todo/{username}包含GET/POST/DELETE三个操作接口,每个操作的接口包含如下的属性:

  • tags:用于对 endpoint 进行分组的组名

  • summary:操作对象的摘要信息,最好限制在 5-10字以内,主要作为概览展示

  • description:操作对象的描述信息,尽可能的详细,展示细节信息

  • operationId:操作对象的唯一ID

  • parameters:该端点的请求参数对象,描述如下

    • name:参数名称

    • in:参数出现的位置,通常是 header,path,query,cookie

    • description:参数的描述

    • required:是否是必填的参数

    • schema:参数的类型

    • example:参数的示例

  • requestBody:请求主体的描述,还可以包含一个指向 components 的 $ref 指针

  • response:响应主体的描述,通常使用标准的 HTTP 状态码,可以包含指向 components的$ref指针

说明

这里将parameters中的请求参数和requestBody中的请求参数统称为参数。

  • 参数的"description"字段不建议省略。这个字段会极大地影响模型生成效果。

  • parameters参数中的"schema.type"字段不可省略,requestBody参数中每个键值的"type"字段也不可省略。不建议在GET请求中使用object和array这两种类型,不建议在POST请求中使用array这种类型。需要有明确且唯一的类型值,不支持oneOf、anyOf和allOf等复杂的类型描述。

  • parameters参数中的required字段如果省略,会按照True被处理;当前,requestBody中的请求参数均会按照required=True被处理。

一个简单的parameters示例

parameters:
  - name: user_name
    in: path
    description: The name of the user.
    required: false
    schema:
      type: string

一个包含多级json的requestBody示例

requestBody:
  content:
    application/json:
      schema:
        required:
          - data
        type: object
        properties:
          data:
            required:
              - input
            type: object
            properties:
              input:
                type: string
                description: XXXX

responses 对象

responses:
  "200":
    description: OK
    content:
    	application/json:
        schema:
          $ref: '#/components/schemas/getTodosResponse'

responses 用于描述接口的响应对象,直接使用常见的httpcode作为key值。

components 对象

在components中定义可重复使用的对象,以便其他对象使用 $ref 关键字直接引用和声明。

components:
  schemas:
    getTodosResponse:
      type: object
      properties:
        todos:
          type: string
          description: The content of todos.