自定义插件

步骤一：创建插件

1. 访问插件页面，单击创建插件。

2. 填写插件信息。

   插件名称：输入具有语义的名称，支持中英文。 示例：寝室公约查询工具test

   插件描述：对插件功能和使用场景的简要说明。能帮助大模型判断当前任务是否需要调用当前插件，请使用自然语言进行描述。 示例：根据输入的数字索引查询特定条目的寝室公约内容。

   插件URL：插件的访问地址。 示例：https://domitorgreement-plugin-example-icohrkdjxy.cn-beijing.fcapp.run 同一个域名下，不同的路径被拆分成了不同的API（即下方创建工具中的工具路径） 同一插件下的不同工具使用相同的域名，每个工具的工具路径对应一个独立的API 例如：xx插件下包含两个API： 查询：https://xxx.com/query 删除：https://xxx.com/delete 在这个示例中，https://xxx.com对应插件URL，/query和/delete对应下方创建工具中的工具路径。这表明该插件下包含两个工具。

   如需要鉴权请打开是否鉴权开关，填写鉴权配置信息。

   鉴权参数说明

   Header列表（可选）	需要鉴权时，可以通过自定义Header传递鉴权信息。
   是否鉴权（可选）	当阿里云百炼应用调用您的自定义插件时是否需要鉴权。此处是否需要鉴权主要取决于API提供方的安全策略。
   鉴权类型	鉴权包括服务级鉴权和用户级鉴权两种方式。 位置：支持将鉴权信息放在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。

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

步骤二：创建工具

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

   本示例中，工具名称填写"寝室公约查询工具"，工具描述填写"根据输入的数字索引查询特定条目的寝室公约内容"，工具路径填写/article，请求方法选择POST，提交方式选择application/json。输入参数：参数名称article_index，参数描述为"索引"，类型为Number，传入方法为Body，必填，传参方式为大模型识别。输出参数：参数名称article，参数描述为"寝室公约内容"，类型为String。高级配置中，用户输入Query为"请根据输入的索引值，查询对应条目的寝室公约内容"，输入参数article_index的Value为5。

   工具参数说明

   工具信息

   工具名称	输入具有语义的名称，支持中英文。
   工具描述	对工具功能和使用场景的简要说明。 帮助大模型判断当前任务是否需要调用该工具，请使用自然语言进行描述，尽量给出使用示例。
   工具路径	指向插件URL的相对路径。 字段名必须以正斜杠（/）开头。 此路径将拼接到插件URL上，以构建完整的URL。
   请求方法	根据实际需求选择GET或POST请求方法来调用API接口。
   提交方式	请求或响应的编码类型。 application/json：主体内容是JSON格式的数据。 application/x-www-form-urlencoded：将表单数据编码为键值对。 这种编码方式用于 POST 请求，表单数据编码为键值对，并通过 URL 编码传输。多个键值对之间用 & 分隔，每个键和值之间用 = 分隔。URL 编码会将特殊字符转换为 % 后跟两位十六进制数的形式。例如，空格会被编码为 %20，& 会被编码为 %26，= 会被编码为 %3D 示例：name=John Doe&age=25 被编码为 name=John%20Doe&age=25

   配置输入参数与输出参数

   配置输入参数	单击增加入参，配置参数信息。
   	参数名称：尽可能带有含义，帮助大模型理解当前需要识别的参数信息是什么。例如city。
   	参数描述：对该入参的功能描述，要简练且准确，帮助大模型进一步理解取参的方式。例如，date，描述为日期的同时，可以再进一步描述date的形式，比如yyyy-MM-dd。
   	类型：指参数类型。 重要 Object类型下的子属性不能为空。请单击该对象行末的图标新增子属性。
   	传参方式：要设置准确。 大模型识别：表示该参数的值需要大模型从用户输入中提取。 业务透传：表示该参数的值从外部主动透传，传递过程中不对数据进行处理或修改。 使用DashScope SDK或HTTP接口调用应用时，插件中的业务透传类型的输入参数信息通过 biz_params和user_defined_params传递给应用。具体请参见应用的参数传递。
   配置输出参数	单击增加出参，配置参数信息，所有参数均为必填项。 大模型会根据出参的定义，结合用户的问题，对API返回的结果进行筛选、重新组合，作为最终的答案返回给用户。 出参与入参一样，需要尽可能精简和准确描述，嵌套的层级也尽可能少。 重要 无论请求方式是GET还是POST，参数都支持Object类型。但Object类型下的子属性不能为空。请单击该对象行末的图标新增子属性。

   高级配置（可选）

   高级配置	为大模型增加调用示例，减少漏召回和误召回的情况。 通常用于入参比较复杂，模型构造容易出错的场景，通过提供一些样例，提升大模型调用插件的准确性。
   	Value：表示用户输入当前的Query时，期望大模型构造出的调用入参。示例：用户输入：“查询杭州明天的天气”，期望构造入参为：{"city": "杭州", "date": "2025-04-25"}。

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

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

   单击测试工具，输入鉴权信息（开启鉴权时填写）及入参的值，单击开始运行。 如果运行失败，请根据运行结果中的报错信息对配置进行调整，并重新进行测试，直至成功运行。 入参的值可以手动输入，也可以通过代码输入。对于入参较为复杂的情况，建议采用代码模式编辑。您可以在代码编辑器中提交完整的JSON格式的入参及其相应的值。

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

1. 访问插件页面，单击从云市场导入。

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

   主账号

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

   该弹窗显示角色名称为 AliyunServiceRoleForSFMAccessCloudAPI，角色权限策略为 AliyunServiceRolePolicyForSFMAccessCloudAPI，授权百炼大模型平台访问阿里云云市场商品清单并根据插件配置进行API调用。

   RAM用户（子账号）

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

   页面弹出授权失败弹窗，提示当前用户没有创建服务关联角色的权限，服务关联角色名称为 AliyunServiceRoleForSFMAccessCloudAPI。

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

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

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

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

      3. 单击创建权限策略。

      4. 在脚本编辑的Effect、Action、Resource、Condition中分别输入以下脚本中的对应内容。

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

      5. 单击确定。

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

         此处名称设置为服务关联角色。

      7. 在左侧导航栏，选择。

      8. 找到待授权的RAM用户（子账号），单击RAM用户（子账号）操作列的添加权限。

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

         至此，RAM用户（子账号）拥有了创建服务关联角色的权限。

         在资源范围中选择账号级别，在权限策略筛选下拉框中选择自定义策略类型，即可找到并勾选目标策略。

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

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

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

4. 您可以查看云市场页面，等待商品状态为已开通。

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

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

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

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

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

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

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

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

      例如，当工具名称超出20字符限制时，输入框右侧的字符计数将以红色显示（如22/20），您需要将名称缩短至限制范围内后再发布。

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

      同时确保工具的调试状态为成功。

获取工具 ID

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

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

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

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