如何创建自定义插件

如果百炼提供的官方插件不能满足业务需求,比如您想要在大模型应用中调用个性化开发的插件或第三方平台的API,可以在百炼创建自定义插件来集成需要使用的API。

操作步骤

步骤一:进入插件创建页面

  • 方式一:登录阿里云百炼大模型服务平台应用组件中选择插件管理,单击新建自定义插件image

  • 方式二:如果您已经拥有了一个百炼大模型应用您可以进入应用管理界面,单击选择插件,在自定义插件栏处,单击创建自定义插件image

步骤二:填写插件信息

参数

说明

插件名称

建议您输入具有语义的名称,中英文不限。

插件名称能够帮助大模型判断当前任务是否需要调用该插件。

插件ID

建议您输入具有语义的英文名称,例如:search、weather等。在您单击创建完成后,百炼将为您生成全局唯一的插件ID。

您可以在Assistant API中使用该插件ID调用您的自定义插件。

插件描述

请使用自然语言描述插件的功能,尽量给出使用示例。例如:“此插件用于获取指定时间和指定地点的天气和温度。例如‘查询杭州明天的天气和温度’”。

插件描述能够帮助大模型判断当前任务是否需要调用该插件。

是否鉴权

(可选)当百炼应用调用您的自定义插件时是否需要鉴权,支持无鉴权服务级鉴权用户级鉴权三种方式。此处是否需要鉴权主要取决于API提供方的安全策略。

鉴权类型

  • 如果选择服务级鉴权,那么调用插件时不需要传入Token,统一使用配置插件时填写的Token。

  • 如果选择用户级鉴权,那么每次调用插件时都需要传入Token。

服务级鉴权

  • 位置:支持将鉴权信息放在HeaderQuery中。

    • Header:将鉴权信息放在HTTP请求头的Authorization字段中,这些信息在URL中不可见。

    • Query:将鉴权信息放在URL中,例如https://example.com?api_key=123456。

  • 参数名:如果将鉴权信息放在Query中需填写鉴权时使用的参数,如“api_key”。如果将鉴权信息放在Header中将默认此参数为“Authorization”。

  • Type

    • basic:不会在您提供的Token前加任何内容。

    • bearer:会在Token前增加“Bearer”。

    两种type都会放在鉴权参数字段中。例如:选择bearer,则调用插件时会变成(“Authorization”: “Bearer <YOUR_TOKEN>”)。

  • Token:从API提供方获取的鉴权Token,如API Key。

用户级鉴权

  • 位置:支持将鉴权信息放在HeaderQuery中。

    • Header:将鉴权信息放在HTTP请求头的Authorization字段中,这些信息在URL中不可见。

    • Query:将鉴权信息放在URL中,例如https://example.com?api_key=123456。

  • 参数名:如果将鉴权信息放在Query中需填写鉴权时使用的参数,如“api_key”。如果将鉴权信息放在Header中将默认此参数为“Authorization”。

  • Type

    • basic:不会在您提供的Token前加任何内容。

    • bearer:会在Token前增加“Bearer”。

    两种type都会放在鉴权参数字段中。例如:选择bearer,则调用插件时会变成(“Authorization”: “Bearer <YOUR_TOKEN>”)。

用户级鉴权需要在应用管理界面配置Token,具体操作请参见用户级鉴权

步骤三:填写接口信息

在代码框中定义您的API接口信息,请使用符合OpenAPI v3规范的格式。OpenAPI 规范(原名 Swagger 规范)是定义 RESTful 接口的全球标准,关于OpenAPI v3的详细字段,请参见OpenAPI v3.0.3。以下是一个示例:

openapi: 3.0.1
info:
    title: 寝室公约查询工具
    description: 寝室公约查询工具,可以根据序号查询特定条目。
    version: "v2"
servers:
    - url: https://domitorgreement-plugin-example-icohrkdjxy.cn-beijing.fcapp.run
paths:
    /article:
        post:
            operationId: get_article
            summary: 查询寝室公约第几条,用整数数字
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [article_index]
                            properties:
                                article_index:
                                    type: integer
                                    description: 寝室公约第几条,用整数数字
            responses:
                "200":
                    description: 查询成功
                    content:
                        application/json:
                            schema:
                                type: object
                                required: [article]
                                properties:
                                    article:
                                        type: string
                                        description: 寝室公约条款

上述示例代码中各项内容的描述如下。

代码片段

描述

openapi: 3.0.1

openapi对象

该对象指定使用的openapi版本。

info:
    title: 寝室公约查询工具
    description: 寝室公约查询工具,可以根据序号查询特定条目。
    version: "v2"

info对象

该对象提供了关于API的元数据,客户端可以根据需要使用这些元数据。

  • title:插件标题。

  • description:插件描述。

  • version:OpenAPI接口协议版本号。

servers:
    - url: https://domitorgreement-plugin-example-icohrkdjxy.cn-beijing.fcapp.run

servers对象

该对象指定服务端路径。

  • url:访问服务端的基础路径。

paths:
    /article:
        post:

paths对象

  • paths:一个指向单个endpoint的相对路径。字段名必须以正斜杠(/)开头。此路径将附加到servers对象中的URL上,以构建完整的URL。

  • /article中包含一个POST操作接口。

    您可以根据需求选择使用GET、POSTDELETEHTTP方法来操作API接口。
operationId: get_article
summary: 查询寝室公约第几条,用整数数字
requestBody:
    required: true
    content:
        application/json:
            schema:
                type: object
                required: [article_index]
                properties:
                    article_index:
                        type: integer
                        description: 寝室公约第几条,用整数数字
responses:
    "200":
        description: 查询成功
        content:
            application/json:
                schema:
                   type: object
                   required: [article]
                   properties:
                      article:
                         type: string
                         description: 寝室公约条款

operation对象

操作接口包含如下的属性:

  • operationId:操作对象的唯一ID。

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

  • requestBody:请求体的描述。

    • required:是否为必填项。

    • content:请求体内容。application/json表示请求或响应的主体内容是以JSON格式编码的数据。

  • responses:响应体的描述,直接使用常见的httpcode作为key

    • description:关于响应内容的简短描述。

    • content:响应体内容。

JSON schema对象

  • type:数据的类型,如string、number、object、array等。

  • required:指定必须存在的参数。

  • properties:对象中每个属性的定义,包括它们的数据类型和描述。

小技巧:您可以借助大模型生成符合OpenAPI v3规范的接口信息,Prompt示例如下:

请根据以下参数帮助我生成符合OpenAPI v3规范的接口信息:
URL: https://domitorgreement-plugin-example-icohrkdjxy.cn-beijing.fcapp.run/article
请求方式:post
请求参数:名称:article_index;含义:寝室公约第几条,用整数数字;是否必须:是。
返回参数:名称:article;含义:寝室公约条款。
说明

完成接口信息编写后,请使用OpenAPI校验工具(如Swagger Editor在线工具)验证您的OpenAPI规范是否符合规范要求,确保没有语法错误或不一致的地方。

参考示例

百炼应用调用插件时支持无鉴权服务级鉴权用户级鉴权三种方式。

无需鉴权时

  1. 填写插件及接口信息,本文以百炼提供的寝室公约查询工具作为示例。

    • 插件名称:寝室公约查询工具

    • 插件ID后缀:test

    • 插件描述填入:寝室公约查询工具,可以根据序号查询特定条目。

    • 其它保持默认选项,单击创建完成image

  2. 返回大模型应用管理界面,单击选择插件,在自定义插件栏勾选上一步创建好的插件,单击添加image

  3. 添加完成后,您可以在输入框中输入:寝室公约第二条是什么?大模型应用会返回以下结果:image

需要鉴权时

本文以高德开放平台提供的行政区域查询API为例。API文档请参见行政区域查询,接口需支持OpenAPI v3协议,示例如下:

单击下拉框可查看接口信息

openapi: 3.0.2
info:
  title: 高德地图行政区查询API
  version: 1.0.0
  description: 查询中国行政区划信息的API接口

servers:
  - url: https://restapi.amap.com

paths:
  /v3/config/district:
    get:
      summary: 查询行政区划信息
      operationId: searchDistrict
      parameters:
        - in: query
          name: key
          schema:
            type: string
          required: true
          description: 请求服务权限标识,需在高德地图官网申请
        - in: query
          name: keywords
          schema:
            type: string
          description: 查询关键字,如行政区名称、citycode、adcode
        - in: query
          name: subdistrict
          schema:
            type: integer
            minimum: 0
            maximum: 3
          description: 设置显示下级行政区级数,默认1
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
            default: 1
          description: 需要第几页数据
        - in: query
          name: offset
          schema:
            type: integer
            minimum: 1
            maximum: 20
            default: 20
          description: 每页返回的最大数据量
        - in: query
          name: extensions
          schema:
            type: string
            enum: [base, all]
            default: base
          description: 控制返回结果中是否包含行政区边界坐标点
        - in: query
          name: filter
          schema:
            type: string
          description: 根据区划过滤,填入adcode
        - in: query
          name: callback
          schema:
            type: string
          description: JSONP回调函数名
        - in: query
          name: output
          schema:
            type: string
            enum: [JSON, XML]
            default: JSON
          description: 返回数据格式类型

      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: 返回结果状态值,0表示失败,1表示成功
                  info:
                    type: string
                    description: 返回状态说明
                  infocode:
                    type: string
                    description: 状态码
                  suggestion:
                    $ref: '#/components/schemas/Suggestion'
                  districts:
                    type: array
                    items:
                      $ref: '#/components/schemas/District'

components:
  schemas:
    Suggestion:
      type: object
      properties:
        keywords:
          type: array
          items:
            type: string
          description: 建议关键字列表
        cities:
          type: array
          items:
            type: string
          description: 建议城市列表
    District:
      type: object
      properties:
        citycode:
          type: string
          description: 城市编码
        adcode:
          type: string
          description: 区域编码
        name:
          type: string
          description: 行政区名称
        polyline:
          type: string
          description: 行政区边界坐标点
        center:
          type: array
          items:
            type: number
            format: float
          description: 区域中心点坐标
        level:
          type: string
          enum: [country, province, city, district, street]
          description: 行政区划级别
        districts:
          type: array
          items:
            $ref: '#/components/schemas/District'
          description: 下级行政区列表

服务级鉴权

  1. 填写插件信息。

    • 插件名称行政区域查询

    • 插件ID后缀:administrative_region

    • 插件描述填入:该插件用于行政区域查询,例如“查询杭州地区的行政区域”

    • 是否鉴权:开启鉴权开关

    • 鉴权类型:服务级鉴权

    • 位置:Query

    • 参数名:key

    • Type:basic

    • Token:<输入您的API-KEY>

    image

  2. 填写接口信息。

  3. 返回大模型应用管理界面,单击选择插件,在自定义插件栏勾选上一步创建好的插件,单击添加

用户级鉴权

  1. 填写插件信息:本文以高德开放平台提供的行政区域查询API为例。

    • 插件名称行政区域查询

    • 插件ID后缀:administrative_region

    • 插件描述填入:该插件用于行政区域查询,例如“查询杭州地区的行政区域。

    • 是否鉴权:开启鉴权开关

    • 鉴权类型:用户级鉴权

    • 位置:Query

    • 参数名:key

    • Type:basic

    image

  2. 填写接口信息。

  3. 返回大模型应用管理界面,单击选择插件,在自定义插件栏勾选上一步创建好的插件,单击添加

  4. 单击插件及流程变量配置,填入鉴权token,最后单击确定

    用户级.png

插件添加完成后,您可以在输入框中输入查询杭州地区的行政区域,大模型应用成功调用自定义的行政区域查询插件,并正确返回结果执行插件.png

常见问题

自定义插件功能是否支持透传业务参数?

自定义插件功能支持透传业务参数,以行政区域查询API为例,具体操作如下:

  1. 进入插件中心,单击编辑插件,配置接口信息,为参数加入业务透传标识x-source:user,此处将下级行政区级数设置为业务透传参数:

    parameters:
      - in: query
        name: subdistrict
        schema:
          type: integer
          minimum: 0
          maximum: 3
        description: 设置显示下级行政区级数,默认1
        x-source: user
  2. 返回大模型应用管理界面,单击选择插件,在自定义插件栏勾选上一步创建好的插件,单击添加

  3. 单击插件及流程变量配置,配置subdistrict变量值,最后单击确定

    配置变量.png

  4. 配置完成后,您可以在输入框中输入查询杭州地区的行政区域。

    subdistrict=1

    subdistrict=2

    大模型应用输出杭州市下一级行政区域

    大模型应用输出杭州市下两级行政区域

    下一级.png

    下两级.png