当阿里云百炼的官方插件无法满足您的业务需求时，您可以通过创建自定义插件来扩展大模型的能力。本文档将引导您完成从创建、调试到使用的全过程，轻松集成所需 API。
工作流程
- 创建/导入插件： 定义插件的基础信息，或直接从云市场导入。
- 添加工具（导入插件无需此步）： 为插件配置具体的 API 路径、请求参数和返回数据。
- 调试与发布： 在线测试 API 的连通性，确保功能正常后发布。
- 在应用中使用： 将插件关联到智能体，通过对话测试或 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。 - 类型：指参数类型。
- 传参方式：
- 大模型识别：表示该参数的值需要大模型从用户输入中提取。
- 业务透传：表示该参数的值从外部主动透传，传递过程中不对数据进行处理或修改。
2
保存草稿
配置完成后单击保存草稿。
3
在线调试
单击测试工具，输入鉴权信息（开启鉴权时填写）及入参的值，单击开始运行。
如果运行失败，请根据运行结果中的报错信息对配置进行调整，并重新进行测试，直至成功运行。
4
发布工具
测试通过后单击发布。只有已发布的工具才能在应用中被调用。
从云市场导入插件
云市场提供了丰富的 API，您可在云市场开通需要的 API 并将其导入至阿里云百炼插件列表中。
1
进入导入页面
访问插件页面，单击从云市场导入。首次导入需要进行服务关联角色授权。
2
开通云市场 API
在导入云市场插件弹窗中，单击点击查看进入云市场开通需要的 API。等待商品状态为已开通。
3
导入插件
开通成功后，返回阿里云百炼控制台，单击从云市场导入，选择已开通的 API，单击确定。
4
测试并发布
从云市场导入的插件为草稿状态，需要测试、发布后再使用：
- 单击工具所在行的调试，进入工具测试页面。
- 输入参数后，单击开始运行。
- 运行成功后返回编辑工具页面，单击发布。
从云市场导入插件时，系统将自动填充出参和入参信息，但可能会存在信息缺失的情况。在发布工具时，请关注错误信息并根据提示解决问题。
使用插件
管理自定义插件与工具
删除插件
在插件列表中，找到目标插件，单击 ... > 删除。
编辑插件
- 在插件列表中，找到目标插件，单击查看详情。
- 单击右上角的编辑插件，修改插件信息并保存。
编辑工具
工具信息修改完成后，需要重新测试并发布，才能生效。
- 在插件列表中，找到工具所属插件，单击查看详情。
- 单击工具所在行的编辑，修改工具信息并单击保存草稿。
- 单击测试工具，在线调试工具。
- 运行成功后单击发布。
删除工具
- 在插件列表中，找到工具所属插件，单击查看详情。
- 单击工具所在行的删除。
错误码
发布工具时的常见错误信息如下表所示：
| 错误码 | 错误信息 | 说明 |
|---|---|---|
| 130040 | xx缺少参数描述信息 | 原因：xx 参数的参数描述缺失。解决方案：请您补充参数描述后重新发布工具。 |
| 130022 | 保存工具信息异常/请检查示例参数是否正确 | 可能原因一：输入参数或输出参数中的 Object 类型参数子属性为空。解决方案：请点击该对象行末的图标新增子属性。可能原因二：请求方法选择了 GET，但输入参数配置时存在 Object 类型参数。解决方案：GET 请求方法下的输入参数不支持 Object 类型，请选择其他类型。 |