如果百炼提供的官方插件不能满足业务需求,比如您想要在大模型应用中调用个性化开发的插件、第三方平台的API或云市场中的插件,那么您可以在百炼创建自定义插件,以便集成所需的API并进行在线调试。
自定义插件包括个性化开发的插件、第三方平台的API以及从云市场导入的插件。创建自定义插件的流程如下:
创建与调用个性化开发的插件或第三方平台的API
步骤一:创建插件
登录阿里云百炼大模型服务平台,在应用组件中选择自定义插件,单击新增自定义插件。
填写插件信息。
参数
说明
插件名称
建议您输入具有语义的名称,中英文不限。
插件描述
请输入插件描述,帮助用户更好地理解插件功能和使用场景。
插件URL
插件的访问地址。同一个HTTP请求下,不同的路径被拆分成了不同的API(即下方创建工具中的工具路径)。同一插件下的不同工具使用相同的域名,每个工具的工具路径对应一个独立的API。
例如:xx插件下包含两个API:
查询:https://xxx.com/query
删除:https://xxx.com/delete
在这个示例中,
https://xxx.com
对应插件URL,/query
和/delete
对应下方创建工具中的工具路径。这表明该插件下包含两个工具。Header列表
(可选)需要鉴权时,可以通过自定义Header传递鉴权信息。
是否鉴权
(可选)当百炼应用调用您的自定义插件时是否需要鉴权。此处是否需要鉴权主要取决于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”。
appcode:会在Token前增加“APPCODE”。
两种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”。
appcode:会在Token前增加“APPCODE”。
两种type都会放在鉴权参数字段中。例如:选择bearer,则调用插件时会变成(“Authorization”: “Bearer <YOUR_TOKEN>”)。
使用DashScope SDK或HTTP接口调用应用时,通过参数
biz_params
和user_defined_tokens
将插件中的用户级鉴权信息透传给应用,其中user_token
传递的值为该插件需要的鉴权信息。具体请参见应用的参数透传。填写完成后单击
或单击继续添加工具。
步骤二:创建工具
填写工具信息、配置输入/输出参数以及高级配置。
参数
说明
工具名称
建议您输入具有语义的名称,中英文不限。
工具名称能够帮助大模型判断当前任务是否需要调用该工具。
工具描述
工具描述能帮助大模型更好的理解工具功能和使用场景。请使用自然语言进行描述,尽量给出使用示例。例如:“此工具用于获取指定时间和指定地点的天气和温度。例如‘查询杭州明天的天气和温度’”。
工具描述能够帮助大模型判断当前任务是否需要调用该工具。
工具路径
指向插件URL的相对路径。字段名必须以正斜杠(/)开头。此路径将拼接到插件URL上,以构建完整的URL。
请求方法
您可以根据需求选择使用GET或POST等HTTP方法来操作API接口。
提交方式
请求或响应的编码类型。
application/json:表示请求或响应的主体内容是以JSON格式编码的数据。
application/x-www-form-urlencoded:用于在 HTTP 请求中编码表单数据。这种编码方式主要用于 POST 请求,将表单数据编码为键值对,并通过 URL 编码传输。多个键值对之间用 & 分隔,每个键和值之间用 = 分隔。URL 编码会将特殊字符转换为 % 后跟两位十六进制数的形式。例如,空格会被编码为 %20,& 会被编码为 %26,= 会被编码为 %3D,表单数据 name=John Doe&age=25 会被编码为 name=John%20Doe&age=25。
配置输入参数
单击增加入参,配置参数信息,所有参数均为必填项。
参数名称尽可能带有含义,可以帮助大模型理解当前需要识别的参数信息是什么。例如
city
这种有含义的词。参数描述是对该入参的功能描述,要简练且准确,帮助大模型进一步理解取参的方式。例如,date,描述为日期的同时,可以再进一步描述date的形式,比如yyyy-MM-dd。
类型指参数类型。如需在Object类型下新增参数,请单击Object行末的
图标进行新增。
传参方式要设置准确。
大模型识别:表示该参数的值需要大模型从用户输入中提取。
业务透传:表示该参数的值从外部主动透传,传递过程中不对数据进行处理或修改。使用DashScope SDK或HTTP接口调用应用时,通过参数
biz_params
和user_defined_params
将插件中的业务透传参数信息透传给应用。具体请参见应用的参数透传。
配置输出参数
单击增加出参,配置参数信息,所有参数均为必填项。
大模型会根据出参的定义,再结合用户的问题,对API返回的结果进行筛选、重新组合,作为最终的答案返回给用户。因此,出参与入参一样,需要尽可能精简和准确描述,嵌套的层级也尽可能少。
高级配置
(可选)为大模型增加调用示例,减少漏召回和误召回的情况。通常用于入参比较复杂,模型构造容易出错的场景,通过提供一些样例,提升大模型调用插件的准确性。
Value表示用户输入当前的Query时,期望大模型构造出的调用入参。
配置完成后单击保存草稿。
在线调试工具API能否调通。
单击测试工具,输入鉴权信息(开启鉴权时填写)及入参的值,单击开始运行。
如果运行失败,请根据运行结果中的报错信息对配置进行调整,并重新进行测试,直至成功运行。
入参的值可以手动输入,也可以通过代码输入。对于入参较为复杂的情况,建议采用代码模式编辑。您可以在代码编辑器中提交完整的JSON格式的入参及其相应的值。
测试通过后单击发布。只有已发布的工具才能在应用中被调用。
步骤三:调用插件
从云市场导入插件
云市场提供了丰富的API,您可在云市场开通需要的API并将其导入至百炼插件列表中,以便应用进行调用。
步骤一:导入插件
在应用组件中选择自定义插件,单击从云市场导入。
首次在阿里云百炼平台上导入云市场API作为插件,需要先进行服务关联角色授权。
主账号
如果您使用主账号登录百炼,请在SLR授权弹窗中,勾选同意上述条款,单击确认授权。
RAM用户(子账号)
如果您使用RAM用户(子账号)登录百炼,在SLR授权弹窗中,勾选同意上述条款,单击确认授权时,会有如下提示:
这是因为该RAM用户(子账号)不具备创建服务关联角色的权限。请按照下述操作先授予RAM用户(子账号)创建服务关联角色的权限。获得授权后,RAM用户(子账号)即可自行从云市场导入插件至百炼或使用主账号已经导入的插件。
授权RAM用户(子账号)创建服务关联角色的权限。
使用主账号登录RAM控制台。
在左侧导航栏,选择
。单击创建权限策略。
在脚本编辑的
Effect
、Action
、Resource
、Condition
中分别输入以下脚本中的对应内容。{ "Action": [ "ram:CreateServiceLinkedRole" ], "Resource": "*", "Effect": "Allow", "Condition": { "StringEquals": { "ram:ServiceName": "cloundapi-access.sfm.aliyuncs.com" } } }
单击确定。
设置权限策略名称,单击确定。
在左侧导航栏,选择
。找到待授权的RAM用户(子账号),单击RAM用户(子账号)操作列的添加权限。
在权限策略中选择刚才创建的权限策略,单击确认新增授权。
至此,RAM用户(子账号)拥有了创建服务关联角色的权限。
RAM用户(子账号)自行从云市场导入插件至百炼或使用主账号已经导入的插件。
返回百炼控制台,单击从云市场导入,在SLR授权弹窗中,勾选同意上述条款,单击确认授权
在导入云市场插件弹窗中,单击点击查看进入云市场开通需要的API。
您可以刷新
页面,等待商品状态为已开通。当前页面还提供了API的AppKey、AppSecret、AppCode,如果插件需要鉴权,您可以在此处获取鉴权信息。
开通成功后,返回百炼控制台,单击从云市场导入,重新打开导入云市场插件弹窗。选择已开通的API,再单击确定,进入工具列表页面。
从云市场导入的插件为草稿状态,需要测试、发布后再使用。
单击工具所在行的调试,进入工具测试页面。
输入参数后,单击开始运行。
若运行成功,则说明接口正常。否则,请参考界面提示信息修改配置。
返回编辑工具页面,单击发布,发布工具。
从云市场导入插件时,系统将自动填充出参和入参信息,但可能会存在信息缺失的情况。在发布工具时,您需要关注无法发布的错误信息,以便根据错误提示有效地解决问题。
已发布且启用状态的工具才能用于后续调用。
步骤二:调用插件
调用插件
方式一:在工具列表中,将已发布的工具添加到智能体应用中。
工具只能与位于相同的业务空间里的智能体应用关联。
在工具所在行,单击添加至应用,按照界面提示将插件添加到智能体应用中。
在应用详情页面,您可以看到工具已经自动添加。
您也可以单击选择插件,继续添加其他工具。最多支持添加10个工具。智能体应用会根据输入选择调用一个或多个工具。
测试插件的使用效果是否符合预期。
无鉴权:您可以在输入框中与大模型进行对话,测试插件使用效果。
用户级鉴权、服务级鉴权:您需要在开启对话前,单击
配置需要传入的鉴权Token。如果不离开当前页面,可以只配置一次。
从云市场导入的插件,不需要在当前页面输入鉴权Token。
工具入参的传参方式选择了业务透传:您需要在开启对话前,单击
配置需要传入的变量值。如果不离开当前页面,可以只输入一次。
测试完成后,发布应用。
方式二:在插件列表中,将插件下的工具添加到智能体应用中。
找到目标插件,单击添加到智能体,按照界面提示将插件添加到智能体应用中。
工具只能与位于相同的业务空间里的智能体应用关联。
默认仅添加已发布的工具,最多可选则10个已发布的工具添加至智能体应用中。
参考方式一的操作,在应用详情页面,测试插件使用效果,并发布应用。
方式三:在我的应用中将工具添加至智能体应用或工作流应用,测试插件使用效果,并发布应用。具体操作请参见通过插件扩展智能体应用能力、工作流应用。
方式四:通过应用调用API使用插件。当通过API调用应用时,如果应用中关联的插件存在业务透传参数或开启了用户级鉴权,则需要通过参数
biz_params
传递鉴权信息或透传参数信息。具体操作请参见应用调用API参考。方式五:通过Assistant API调用工具。请在Assistant API文档中搜索
tools
关键字,查看如何使用Assistant API调用工具。
获取工具ID
工具ID用于标识具体的工具。通过API调用工具时,需要正确传递工具ID,以确保请求能够被正确识别。
在插件列表中,找到工具所属的插件,单击查看详情。
将鼠标悬浮于工具名称旁边的
图标上。
单击
图标,复制工具ID。
管理自定义插件与工具
常见问题
发布工具时的报错信息
错误码 | 错误信息 | 说明 |
130040 | xx缺少参数描述信息 | xx参数的参数描述缺失。请您补充参数描述后重新发布工具。 |