管理模型供应商、API 密钥、模型列表和模型分组

模型供应商管理

模型供应商决定 ZStack Zenova 可以调用哪些 AI 模型。管理员需要先配置模型供应商，确认模型已有可用上游，再通过模型分组授权，普通用户才能在创建智能体或聊天时选择模型。

如果你只是普通使用者，看到“没有可用模型”时，可以把这一页发给管理员处理。

1. 什么是模型供应商

模型供应商就是提供模型 API 的平台，例如：

• OpenAI-compatible 服务。
• DashScope。
• DeepSeek。
• 企业内部模型网关。
• 其他兼容 OpenAI 接口的模型平台。

配置模型供应商时，通常需要准备：

2. 进入管理页面

管理员登录 ZStack Zenova 后，进入管理后台：

/admin/model-providers

如果页面没有权限，说明当前账号不是管理员，需要联系系统管理员授权。

3. 新增模型供应商

在模型供应商页面点击新增或创建，然后填写：

1. 供应商名称，例如“DashScope 生产账号”。
2. Provider 类型，通常选择 OpenAI-compatible 或对应平台。
3. API 地址。
4. API 密钥。
5. 保存。

填写完成后，建议立即测试连接。测试失败时，优先检查 API 密钥、接口地址、服务器网络和代理配置。

接入本地部署或行内自建的推理服务

选择「本地部署」时，地址与路径分开填写：

1. 点击「测试连接」。结果逐步列出每一步实际访问的地址、上游返回的状态码与原文，便于判断是地址、路径还是认证的问题。

网关只按接口能力表中的路径访问上游，不会自动补 /v1 或其他前缀。

4. 添加或同步模型

模型供应商保存后，需要确认模型列表可用。

常见做法：

• 如果系统支持自动同步，点击同步模型。
• 如果需要手动填写，添加模型名称。
• 设置默认模型或主模型。
• 启用需要开放给用户的模型。

模型名称必须和供应商实际支持的名称一致。名称写错时，智能体创建成功后也可能无法正常回复。

编辑供应商时获取可用模型

编辑已有供应商时，点击“获取可用模型”，系统会用当前 API 密钥向供应商查询它支持的模型列表；勾选需要开放的模型后保存。

• 获取失败时，优先检查 API 密钥、接口地址和网络，可参考“测试连接失败”。
• 勾选保存后，模型出现在供应商的模型列表里，并作为对应模型的上游；再按需设置默认模型，并在模型分组中设置可用范围。

5. 确认模型并加入模型分组

模型是普通用户在创建智能体或聊天时看到的选项。供应商下的模型保存后，会作为上游归入同名模型。

1. 进入「模型」页面，确认模型已存在，且至少有一个启用的上游：

/admin/models

1. 进入「组织与权限 › 模型分组」，新建或编辑模型分组：

/admin/model-groups

创建模型分组时，建议填写：

• 模型分组名称，例如“通用问答”。
• 分组包含的模型。
• 在「可用范围与配额」中设置可使用的工作空间、部门或用户，以及额度。
• 启用状态。

保存后，可用范围内的用户就可以在创建智能体时选择分组内的模型。

6. 验证是否配置成功

验证方式：

1. 切换到普通用户或目标工作空间。
2. 打开创建智能体页面。
3. 查看模型下拉框。
4. 选择刚加入模型分组的模型。
5. 创建一个测试智能体。
6. 发送一条测试消息。

如果智能体能正常回复，说明模型供应商、模型和模型分组配置成功。

7. 常见问题

创建智能体时没有模型可选

可能原因：

• 模型没有启用的上游。
• 模型没有加入任何启用的模型分组。
• 模型分组的可用范围不包含当前工作空间或用户。
• 模型供应商的 API 密钥无效。
• 模型列表为空。

测试连接失败

优先检查：

• 测试结果中列出的实际访问地址是否正确；本地部署时核对服务地址与接口能力表中的路径。
• 上游返回 404 时，多半是路径不对；返回 401 或 403 时，核对认证方式、API 密钥或自定义请求头。
• 服务没有模型列表接口时，关闭「模型列表」并手动添加模型。
• 服务器是否能访问模型供应商。
• 是否需要配置代理。
• 模型供应商账号是否欠费或被限流。

智能体创建成功但聊天失败

优先检查：

• 模型名称是否写错。
• 模型供应商是否支持该模型。
• API 密钥是否有调用该模型的权限。
• 是否达到模型供应商限额。
• ZStack Zenova 服务器是否能访问外部模型接口。