如何创建自定义插件 - 大模型服务平台百炼

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

操作步骤

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

方式一：登录阿里云百炼大模型服务平台，在应用组件中选择插件管理，单击新建自定义插件。
方式二：如果您已经拥有了一个百炼大模型应用，您可以进入应用管理界面，单击选择插件，在自定义插件栏处，单击创建自定义插件。

步骤二：填写插件信息

参数	说明
插件名称	建议您输入具有语义的名称，中英文不限。插件名称能够帮助大模型判断当前任务是否需要调用该插件。
插件ID	建议您输入具有语义的英文名称，例如：search、weather等。在您单击创建完成后，百炼将为您生成全局唯一的插件ID。您可以在Assistant API中使用该插件ID调用您的自定义插件。
插件描述	请使用自然语言描述插件的功能，尽量给出使用示例。例如：“此插件用于获取指定时间和指定地点的天气和温度。例如‘查询杭州明天的天气和温度’”。插件描述能够帮助大模型判断当前任务是否需要调用该插件。
是否鉴权	（可选）当百炼应用调用您的自定义插件时是否需要鉴权，支持无鉴权、服务级鉴权和用户级鉴权三种方式。此处是否需要鉴权主要取决于API提供方的安全策略。
鉴权类型	如果选择服务级鉴权，那么调用插件时不需要传入Token，统一使用配置插件时填写的Token。如果选择用户级鉴权，那么每次调用插件时都需要传入Token。服务级鉴权位置：支持将鉴权信息放在Header或Query中。 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。用户级鉴权位置：支持将鉴权信息放在Header或Query中。 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、POST或DELETE等HTTP方法来操作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规范是否符合规范要求，确保没有语法错误或不一致的地方。

参考示例

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

无需鉴权时

填写插件及接口信息，本文以百炼提供的寝室公约查询工具作为示例。
- 插件名称：寝室公约查询工具
- 插件ID后缀：test
- 插件描述填入：寝室公约查询工具，可以根据序号查询特定条目。
- 其它保持默认选项，单击创建完成。
返回大模型应用管理界面，单击选择插件，在自定义插件栏勾选上一步创建好的插件，单击添加。
添加完成后，您可以在输入框中输入：寝室公约第二条是什么？大模型应用会返回以下结果：

需要鉴权时

本文以高德开放平台提供的行政区域查询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: 下级行政区列表

服务级鉴权

填写插件信息。
- 插件名称：行政区域查询
- 插件ID后缀：administrative_region
- 插件描述填入：该插件用于行政区域查询，例如“查询杭州地区的行政区域”
- 是否鉴权：开启鉴权开关
- 鉴权类型：服务级鉴权
- 位置：Query
- 参数名：key
- Type：basic
- Token：<输入您的API-KEY>
填写接口信息。
返回大模型应用管理界面，单击选择插件，在自定义插件栏勾选上一步创建好的插件，单击添加。

用户级鉴权

填写插件信息：本文以高德开放平台提供的行政区域查询API为例。
- 插件名称：行政区域查询
- 插件ID后缀：administrative_region
- 插件描述填入：该插件用于行政区域查询，例如“查询杭州地区的行政区域。
- 是否鉴权：开启鉴权开关
- 鉴权类型：用户级鉴权
- 位置：Query
- 参数名：key
- Type：basic
填写接口信息。
返回大模型应用管理界面，单击选择插件，在自定义插件栏勾选上一步创建好的插件，单击添加。
单击插件及流程变量配置，填入鉴权token，最后单击确定。

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

常见问题

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

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

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

parameters:
  - in: query
    name: subdistrict
    schema:
      type: integer
      minimum: 0
      maximum: 3
    description: 设置显示下级行政区级数，默认1
    x-source: user

返回大模型应用管理界面，单击选择插件，在自定义插件栏勾选上一步创建好的插件，单击添加。
单击插件及流程变量配置，配置subdistrict变量值，最后单击确定。
配置完成后，您可以在输入框中输入：查询杭州地区的行政区域。