如果百炼提供的官方插件不能满足业务需求,比如您想要在大模型应用中调用个性化开发的插件或第三方平台的API,可以在百炼创建自定义插件来集成需要使用的API。
操作步骤
步骤一:进入插件创建页面
方式一:登录阿里云百炼大模型服务平台,在应用组件中选择插件管理,单击新建自定义插件。
方式二:如果您已经拥有了一个百炼大模型应用,您可以进入应用管理界面,单击选择插件,在自定义插件栏处,单击创建自定义插件。
步骤二:填写插件信息
参数 | 说明 |
插件名称 | 建议您输入具有语义的名称,中英文不限。 插件名称能够帮助大模型判断当前任务是否需要调用该插件。 |
插件ID | 建议您输入具有语义的英文名称,例如:search、weather等。在您单击创建完成后,百炼将为您生成全局唯一的插件ID。 您可以在Assistant API中使用该插件ID调用您的自定义插件。 |
插件描述 | 请使用自然语言描述插件的功能,尽量给出使用示例。例如:“此插件用于获取指定时间和指定地点的天气和温度。例如‘查询杭州明天的天气和温度’”。 插件描述能够帮助大模型判断当前任务是否需要调用该插件。 |
是否鉴权 | (可选)当百炼应用调用您的自定义插件时是否需要鉴权,支持无鉴权、服务级鉴权和用户级鉴权三种方式。此处是否需要鉴权主要取决于API提供方的安全策略。 |
鉴权类型 |
服务级鉴权
用户级鉴权
用户级鉴权需要在应用管理界面配置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对象 该对象指定使用的openapi版本。 |
| info对象 该对象提供了关于API的元数据,客户端可以根据需要使用这些元数据。
|
| servers对象 该对象指定服务端路径。
|
| paths对象
|
| operation对象 操作接口包含如下的属性:
JSON schema对象
|
小技巧:您可以借助大模型生成符合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协议,示例如下:
服务级鉴权
填写插件信息。
插件名称:行政区域查询
插件ID后缀:administrative_region
插件描述填入:该插件用于行政区域查询,例如“查询杭州地区的行政区域”
是否鉴权:开启鉴权开关
鉴权类型:服务级鉴权
位置:Query
参数名:key
Type:basic
Token:<输入您的API-KEY>
填写接口信息。
返回大模型应用管理界面,单击选择插件,在自定义插件栏勾选上一步创建好的插件,单击添加。
用户级鉴权
填写插件信息:本文以高德开放平台提供的行政区域查询API为例。
插件名称:行政区域查询
插件ID后缀:administrative_region
插件描述填入:该插件用于行政区域查询,例如“查询杭州地区的行政区域。
是否鉴权:开启鉴权开关
鉴权类型:用户级鉴权
位置:Query
参数名:key
Type:basic
填写接口信息。
返回大模型应用管理界面,单击选择插件,在自定义插件栏勾选上一步创建好的插件,单击添加。
单击插件及流程变量配置,填入鉴权token,最后单击确定。
插件添加完成后,您可以在输入框中输入:查询杭州地区的行政区域,大模型应用成功调用自定义的行政区域查询插件,并正确返回结果。
常见问题
自定义插件功能是否支持透传业务参数?
自定义插件功能支持透传业务参数,以行政区域查询API为例,具体操作如下:
进入插件中心,单击编辑插件,配置接口信息,为参数加入业务透传标识
x-source:user
,此处将下级行政区级数设置为业务透传参数:parameters: - in: query name: subdistrict schema: type: integer minimum: 0 maximum: 3 description: 设置显示下级行政区级数,默认1 x-source: user
返回大模型应用管理界面,单击选择插件,在自定义插件栏勾选上一步创建好的插件,单击添加。
单击插件及流程变量配置,配置subdistrict变量值,最后单击确定。
配置完成后,您可以在输入框中输入:查询杭州地区的行政区域。
subdistrict=1
subdistrict=2
大模型应用输出杭州市下一级行政区域
大模型应用输出杭州市下两级行政区域