如何创建自定义插件

如果百炼提供的官方插件不能满足业务需求,比如您想要在大模型应用中调用个性化开发的插件、第三方平台的API或云市场中的插件,那么您可以在百炼创建自定义插件,以便集成所需的API并进行在线调试。

自定义插件包括个性化开发的插件、第三方平台的API以及从云市场导入的插件。创建自定义插件的流程如下:

image

创建与调用个性化开发的插件或第三方平台的API

步骤一:创建插件

  1. 登录阿里云百炼大模型服务平台应用组件中选择自定义插件,单击新增自定义插件

    image

  2. 填写插件信息。

    image

    参数

    说明

    插件名称

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

    插件描述

    请输入插件描述,帮助用户更好地理解插件功能和使用场景。

    插件URL

    插件的访问地址。同一个HTTP请求下,不同的路径被拆分成了不同的API(即下方创建工具中的工具路径)。同一插件下的不同工具使用相同的域名,每个工具的工具路径对应一个独立的API。

    例如:xx插件下包含两个API:

    查询:https://xxx.com/query

    删除:https://xxx.com/delete

    在这个示例中,https://xxx.com对应插件URL/query/delete对应下方创建工具中的工具路径。这表明该插件下包含两个工具。

    Header列表

    (可选)需要鉴权时,可以通过自定义Header传递鉴权信息。

    是否鉴权

    (可选)当百炼应用调用您的自定义插件时是否需要鉴权。此处是否需要鉴权主要取决于API提供方的安全策略。

    image:无鉴权。

    image:开启鉴权。

    鉴权类型

    鉴权包括服务级鉴权用户级鉴权两种方式。

    • 如果选择服务级鉴权,那么调用插件时不需要传入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”。

      • appcode:会在Token前增加“APPCODE”。

      两种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”。

      • appcode:会在Token前增加“APPCODE”。

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

    使用DashScope SDKHTTP接口调用应用时,通过参数biz_paramsuser_defined_tokens将插件中的用户级鉴权信息透传给应用,其中user_token传递的值为该插件需要的鉴权信息。具体请参见应用的参数透传

  3. 填写完成后单击确认创建插件 > 创建工具或单击继续添加工具

步骤二:创建工具

  1. 填写工具信息、配置输入/输出参数以及高级配置。

    image

    参数

    说明

    工具名称

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

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

    工具描述

    工具描述能帮助大模型更好的理解工具功能和使用场景。请使用自然语言进行描述,尽量给出使用示例。例如:“此工具用于获取指定时间和指定地点的天气和温度。例如‘查询杭州明天的天气和温度’”。

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

    工具路径

    指向插件URL的相对路径。字段名必须以正斜杠(/)开头。此路径将拼接到插件URL上,以构建完整的URL。

    请求方法

    您可以根据需求选择使用GETPOSTHTTP方法来操作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行末的image图标进行新增。

      image

    • 传参方式要设置准确。

      • 大模型识别:表示该参数的值需要大模型从用户输入中提取。

      • 业务透传:表示该参数的值从外部主动透传,传递过程中不对数据进行处理或修改。使用DashScope SDKHTTP接口调用应用时,通过参数 biz_paramsuser_defined_params将插件中的业务透传参数信息透传给应用。具体请参见应用的参数透传

    配置输出参数

    单击增加出参,配置参数信息,所有参数均为必填项。

    大模型会根据出参的定义,再结合用户的问题,对API返回的结果进行筛选、重新组合,作为最终的答案返回给用户。因此,出参与入参一样,需要尽可能精简和准确描述,嵌套的层级也尽可能少。

    高级配置

    (可选)为大模型增加调用示例,减少漏召回和误召回的情况。通常用于入参比较复杂,模型构造容易出错的场景,通过提供一些样例,提升大模型调用插件的准确性。

    Value表示用户输入当前的Query时,期望大模型构造出的调用入参。

  2. 配置完成后单击保存草稿

  3. 在线调试工具API能否调通。

    单击测试工具,输入鉴权信息(开启鉴权时填写)及入参的值,单击开始运行

    如果运行失败,请根据运行结果中的报错信息对配置进行调整,并重新进行测试,直至成功运行。

    image

    入参的值可以手动输入,也可以通过代码输入。对于入参较为复杂的情况,建议采用代码模式编辑。您可以在代码编辑器中提交完整的JSON格式的入参及其相应的值。

    image

  4. 测试通过后单击发布。只有已发布的工具才能在应用中被调用。

步骤三:调用插件

从云市场导入插件

云市场提供了丰富的API,您可在云市场开通需要的API并将其导入至百炼插件列表中,以便应用进行调用。

步骤一:导入插件

  1. 应用组件中选择自定义插件,单击从云市场导入

  2. 首次在阿里云百炼平台上导入云市场API作为插件,需要先进行服务关联角色授权。

    主账号

    如果您使用主账号登录百炼,请在SLR授权弹窗中,勾选同意上述条款,单击确认授权

    image

    RAM用户(子账号)

    如果您使用RAM用户(子账号)登录百炼,在SLR授权弹窗中,勾选同意上述条款,单击确认授权时,会有如下提示:

    image

    这是因为该RAM用户(子账号)不具备创建服务关联角色的权限。请按照下述操作先授予RAM用户(子账号)创建服务关联角色的权限。获得授权后,RAM用户(子账号)即可自行从云市场导入插件至百炼或使用主账号已经导入的插件。

    1. 授权RAM用户(子账号)创建服务关联角色的权限。

      1. 使用主账号登录RAM控制台

      2. 在左侧导航栏,选择权限管理 > 权限策略

      3. 单击创建权限策略

      4. 脚本编辑EffectActionResourceCondition中分别输入以下脚本中的对应内容。

        {
            "Action": [
                "ram:CreateServiceLinkedRole"
            ],
            "Resource": "*",
            "Effect": "Allow",
            "Condition": {
                "StringEquals": {
                    "ram:ServiceName": "cloundapi-access.sfm.aliyuncs.com"
                }
            }
        }

        image

      5. 单击确定

      6. 设置权限策略名称,单击确定

        image

      7. 在左侧导航栏,选择身份管理 > 用户

      8. 找到待授权的RAM用户(子账号),单击RAM用户(子账号)操作列的添加权限

      9. 在权限策略中选择刚才创建的权限策略,单击确认新增授权

        至此,RAM用户(子账号)拥有了创建服务关联角色的权限。

        image

    2. RAM用户(子账号)自行从云市场导入插件至百炼或使用主账号已经导入的插件。

      返回百炼控制台,单击从云市场导入,在SLR授权弹窗中,勾选同意上述条款,单击确认授权

  3. 导入云市场插件弹窗中,单击点击查看进入云市场开通需要的API。

    image

  4. 您可以刷新云市场 > 已购买的服务页面,等待商品状态已开通

    当前页面还提供了APIAppKey、AppSecret、AppCode,如果插件需要鉴权,您可以在此处获取鉴权信息。

    image

  5. 开通成功后,返回百炼控制台,单击从云市场导入,重新打开导入云市场插件弹窗。选择已开通的API,再单击确定,进入工具列表页面。

    image

  6. 从云市场导入的插件为草稿状态,需要测试、发布后再使用。

    1. 单击工具所在行的调试,进入工具测试页面。

      image

    2. 输入参数后,单击开始运行

      运行成功,则说明接口正常。否则,请参考界面提示信息修改配置。

      image

    3. 返回编辑工具页面,单击发布,发布工具。

      从云市场导入插件时,系统将自动填充出参和入参信息,但可能会存在信息缺失的情况。在发布工具时,您需要关注无法发布的错误信息,以便根据错误提示有效地解决问题。

      image

    4. 已发布启用状态的工具才能用于后续调用。

      image

步骤二:调用插件

调用插件

  • 方式一:在工具列表中,将已发布的工具添加到智能体应用中。

    工具只能与位于相同的业务空间里的智能体应用关联。
    1. 在工具所在行,单击添加至应用,按照界面提示将插件添加到智能体应用中。

      image

    2. 在应用详情页面,您可以看到工具已经自动添加。

      您也可以单击选择插件,继续添加其他工具。最多支持添加10个工具。智能体应用会根据输入选择调用一个或多个工具。

      image

    3. 测试插件的使用效果是否符合预期。

      • 无鉴权:您可以在输入框中与大模型进行对话,测试插件使用效果。

      • 用户级鉴权、服务级鉴权:您需要在开启对话前,单击image配置需要传入的鉴权Token。如果不离开当前页面,可以只配置一次。

        从云市场导入的插件,不需要在当前页面输入鉴权Token。

        image

      • 工具入参的传参方式选择了业务透传:您需要在开启对话前,单击image配置需要传入的变量值。如果不离开当前页面,可以只输入一次。

        image

    4. 测试完成后,发布应用。

  • 方式二:在插件列表中,将插件下的工具添加到智能体应用中。

    1. 找到目标插件,单击添加到智能体,按照界面提示将插件添加到智能体应用中。

      工具只能与位于相同的业务空间里的智能体应用关联。
      默认仅添加已发布的工具,最多可选则10个已发布的工具添加至智能体应用中。

      image

    2. 参考方式一的操作,在应用详情页面,测试插件使用效果,并发布应用。

  • 方式三:在我的应用中将工具添加至智能体应用或工作流应用,测试插件使用效果,并发布应用。具体操作请参见通过插件扩展智能体应用能力工作流应用

  • 方式四:通过应用调用API使用插件。当通过API调用应用时,如果应用中关联的插件存在业务透传参数或开启了用户级鉴权,则需要通过参数biz_params传递鉴权信息或透传参数信息。具体操作请参见应用调用API参考

  • 方式五:通过Assistant API调用工具。请在Assistant API文档中搜索tools关键字,查看如何使用Assistant API调用工具。

获取工具ID

工具ID用于标识具体的工具。通过API调用工具时,需要正确传递工具ID,以确保请求能够被正确识别。

  1. 插件列表中,找到工具所属的插件,单击查看详情

  2. 将鼠标悬浮于工具名称旁边的image图标上。

  3. 单击image图标,复制工具ID。

    image

管理自定义插件与工具

删除插件

重要

删除插件会删除插件下的所有工具,并且调用了插件的应用会失效,此操作布科撤回,请谨慎操作。

插件列表中,找到目标插件,单击更多 > 删除

image

编辑插件

  1. 插件列表中,找到目标插件,单击查看详情

  2. 单击右上角的编辑插件,修改插件信息并保存。

    插件信息保存后立即生效。如果修改了插件的URL、Header、鉴权信息,可能会影响工具调用。因此,需要重新测试并发布工具。

编辑工具

工具信息修改完成后,需要重新测试并发布,才能生效。

  1. 插件列表中,找到工具所属插件,单击查看详情

  2. 单击工具所在行的编辑,修改工具信息并单击保存草稿

  3. 单击测试工具,在线调试工具。

  4. 运行成功后单击发布

删除工具

重要

删除工具后,调用了此工具的应用会失效,此操作不可撤回,请谨慎操作。

  1. 插件列表中,找到工具所属插件,单击查看详情

  2. 单击工具所在行的删除

常见问题

发布工具时的报错信息

错误码

错误信息

说明

130040

xx缺少参数描述信息

xx参数的参数描述缺失。请您补充参数描述后重新发布工具。