Skip to main content

自定义插件

当阿里云百炼的官方插件无法满足您的业务需求时，您可以通过创建自定义插件来扩展大模型的能力。本文档将引导您完成从创建、调试到使用的全过程，轻松集成所需 API。

工作流程

  1. 创建/导入插件： 定义插件的基础信息，或直接从云市场导入。
  2. 添加工具（导入插件无需此步）： 为插件配置具体的 API 路径、请求参数和返回数据。
  3. 调试与发布： 在线测试 API 的连通性，确保功能正常后发布。
  4. 在应用中使用： 将插件关联到智能体，通过对话测试或 API 集成来调用。

创建自定义插件

请参见下方"步骤一：创建插件"和"步骤二：创建工具"。

步骤一：创建插件

1

访问插件页面

访问插件管理页面，单击创建插件。
2

填写插件信息

  • 插件名称：输入具有语义的名称，支持中英文。
    示例：寝室公约查询工具test
  • 插件描述：对插件功能和使用场景的简要说明。能帮助大模型判断当前任务是否需要调用当前插件，请使用自然语言进行描述。
    示例：根据输入的数字索引查询特定条目的寝室公约内容。
  • 插件 URL：插件的访问地址。同一个域名下，不同的路径被拆分成不同的 API（即工具路径）。
    示例：https://domitorgreement-plugin-example-icohrkdjxy.cn-beijing.fcapp.run
如需要鉴权请打开是否鉴权开关，填写鉴权配置信息。鉴权参数说明：
参数说明
Header列表（可选）需要鉴权时，可以通过自定义 Header 传递鉴权信息。
是否鉴权（可选）当阿里云百炼应用调用您的自定义插件时是否需要鉴权。此处是否需要鉴权主要取决于 API 提供方的安全策略。
鉴权类型鉴权包括服务级鉴权和用户级鉴权两种方式。位置支持 Header 或 Query；Type 支持 basic、bearer、appcode 三种模式。
3

确认创建

填写完成后单击确认创建并创建工具或单击继续添加工具。

步骤二：创建工具

1

填写工具信息并配置参数

工具信息：
参数说明
工具名称输入具有语义的名称，支持中英文。
工具描述对工具功能和使用场景的简要说明。帮助大模型判断当前任务是否需要调用该工具。
工具路径指向插件 URL 的相对路径，必须以正斜杠（/）开头。
请求方法根据实际需求选择 GET 或 POST 请求方法。
提交方式application/json 或 application/x-www-form-urlencoded。
配置输入参数：单击添加输入参数，配置参数信息。
  • 参数名称：尽可能带有含义，帮助大模型理解当前需要识别的参数信息。例如 city。
  • 参数描述：对该入参的功能描述，要简练且准确。例如 date，描述为日期，形式为 yyyy-MM-dd。
  • 类型：指参数类型。
  • 传参方式：
    • 大模型识别：表示该参数的值需要大模型从用户输入中提取。
    • 业务透传：表示该参数的值从外部主动透传，传递过程中不对数据进行处理或修改。
Object 类型下的子属性不能为空。请单击该对象行末的图标新增子属性。
配置输出参数：单击添加参数，配置参数信息，所有参数均为必填项。大模型会根据出参的定义，结合用户的问题，对 API 返回的结果进行筛选和重新组合。高级配置（可选）：为大模型增加调用示例，减少漏召回和误召回的情况。通常用于入参比较复杂、模型构造容易出错的场景。
2

保存草稿

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

在线调试

单击测试工具，输入鉴权信息（开启鉴权时填写）及入参的值，单击开始运行。
如果运行失败，请根据运行结果中的报错信息对配置进行调整，并重新进行测试，直至成功运行。
4

发布工具

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

从云市场导入插件

云市场提供了丰富的 API，您可在云市场开通需要的 API 并将其导入至阿里云百炼插件列表中。
1

进入导入页面

访问插件管理页面，单击从云市场导入。首次导入需要进行服务关联角色授权。
2

开通云市场 API

在导入云市场插件弹窗中，单击点击查看进入云市场开通需要的 API。等待商品状态为已开通。
3

导入插件

开通成功后，返回阿里云百炼控制台，单击从云市场导入，选择已开通的 API，单击确定。
4

测试并发布

从云市场导入的插件为草稿状态，需要测试、发布后再使用：
  1. 单击工具所在行的调试，进入工具测试页面。
  2. 输入参数后，单击开始运行。
  3. 运行成功后返回编辑工具页面，单击发布。
从云市场导入插件时，系统将自动填充出参和入参信息，但可能会存在信息缺失的情况。在发布工具时，请关注错误信息并根据提示解决问题。

使用插件

方式一：将插件发布为 MCP 服务，然后在智能体应用中添加该 MCP 服务。

步骤一：将插件发布为 MCP 服务
1. 在插件列表中，将鼠标悬浮在目标插件卡片上，单击**发布为 MCP 服务**。
2. 发布成功后，可在 MCP 管理页面查看该 MCP 服务的详细信息。

步骤二：在智能体应用中添加 MCP 服务
1. 进入智能体应用的编排页面，在 MCP 区块中单击 +。
2. 在选择 MCP 服务面板中，切换到自定义 MCP 页签，找到从插件转换的 MCP 服务，单击添加。
3. 测试插件的使用效果是否符合预期。
4. 测试完成后，发布应用。

方式二：在应用管理页面中，进入智能体应用的编排页面，在 MCP 区块中添加 MCP 服务，测试插件使用效果，并发布应用。

管理自定义插件与工具

删除插件

删除插件会删除插件下的所有工具，并且调用了插件的应用会失效，此操作不可撤回，请谨慎操作。
在插件列表中，找到目标插件，单击更多图标（...），然后选择删除。

编辑插件

  1. 在插件列表中，找到目标插件，单击查看详情。
  2. 单击右上角的编辑插件，修改插件信息并保存。
插件信息保存后立即生效。如果修改了插件的 URL、Header、鉴权信息，可能会影响工具调用，请重新测试并发布工具。

编辑工具

工具信息修改完成后，需要重新测试并发布，才能生效。
  1. 在插件列表中，找到工具所属插件，单击查看详情。
  2. 单击工具所在行的编辑，修改工具信息并单击保存草稿。
  3. 单击测试工具，在线调试工具。
  4. 运行成功后单击发布。

删除工具

删除工具后，调用了此工具的应用会失效，此操作不可撤回，请谨慎操作。
  1. 在插件列表中，找到工具所属插件，单击查看详情。
  2. 单击工具所在行的删除。

错误码

发布工具时的常见错误信息如下表所示：
错误码错误信息说明
130040xx缺少参数描述信息原因：xx 参数的参数描述缺失。解决方案：请您补充参数描述后重新发布工具。
130022保存工具信息异常/请检查示例参数是否正确可能原因一：输入参数或输出参数中的 Object 类型参数子属性为空。解决方案：请点击该对象行末的图标新增子属性。可能原因二：请求方法选择了 GET，但输入参数配置时存在 Object 类型参数。解决方案：GET 请求方法下的输入参数不支持 Object 类型，请选择其他类型。