添加与配置模型

什么时候用

当你已经接入了模型供应商（Provider），需要添加具体的模型供智能体或用户使用时。每个 ModelItem 代表一个可调用的具体模型，你可以手动添加单个模型，也可以使用自动获取功能批量导入（适用于支持该功能的 Provider）。

你需要准备

• 已配置好至少一个 Provider（参见「接入模型供应商」）
• 知道该 Provider 支持的具体模型名称（如 gpt-4o、claude-3-sonnet）

操作步骤

第 1 步：展开供应商

在模型管理页面，找到要添加模型的 Provider，点击「模型管理」展开该 Provider。

展开后你会看到该 Provider 下已配置的模型列表，以及「添加模型」和「自动获取模型」（如支持）按钮。

第 2 步：添加单个模型

点击「添加模型」按钮，填写表单：

重要提醒： 显示名称 是你在 API 调用和控制台中使用的名称，必须唯一且不能以 group- 开头。

填完点击「确认」保存。

第 3 步：自动获取模型（可选）

对于支持该功能的 Provider（非 Azure、Anthropic、火山方舟），你可以点击「自动获取模型」按钮：

1. 系统会探测上游可调用模型列表
2. 展示预览供你选择要导入的模型
3. 你可以为每个模型设置自定义显示名称
4. 确认后批量导入

注意： 使用此功能需要 Provider 已配置有效的 API Key。

第 4 步：编辑或删除模型

在模型列表中，你可以：

• 点击「编辑」修改已有模型的配置
• 点击「删除」移除该模型
• 点击显示名称旁的复制按钮快速复制名称

怎么验证成功了

1. 在展开的 Provider 下能看到刚添加的模型
2. 模型状态为「启用」
3. 可以在智能体创建或设置中选择该模型
4. 通过 API 调用时使用该模型的 显示名称 能正常响应

常见问题

创建模型返回 422

可能是以下原因：

• 显示名称 与同下已有模型或模型组冲突
• 显示名称 以 group- 开头（该前缀仅用于模型组）
• 必填字段未填写

自动获取模型按钮是灰色的

说明该 Provider 不支持此功能（如 Azure、Anthropic、火山方舟），或者未配置有效的 API Key。

模型添加后不能用

请检查：

• 模型状态是否为「启用」
• 是否已将模型添加到用户白名单（非 Agent 路径调用需要）
• Provider 的 API Key 是否有效

显示名称 有什么用

显示名称 是：

• 控制台展示的名称
• OpenAI API 调用时 model 参数使用的名称
• 智能体绑定时选择的名称

深入

核心概念

ModelItem（模型项）

一个 Provider 下可以创建多个 ModelItem，每个代表一个可调用的具体模型。

关键字段：

字段含义速查表

ModelItem

权限边界

常见坑

1. 显示名称不要冲突

   两个 ModelItem 不能有相同的显示名称。如果看到「显示名称已存在」，说明同租户已有同名模型。

2. 显示名称不要以 group- 开头

   如果你试图以 group- 开头创建 ModelItem，系统会拒绝。模型组自身的名称也不能以 group- 开头；group- 仅是 OpenAI API 调用模型组时的前缀。

排错速查

• 接入模型供应商：参见「接入模型供应商」
• 模型组与多模型路由：参见「模型组：多模型路由」