Snail AI

Appearance

模型提供商 ​

模型提供商（Provider）是 Snail AI 模型管理的第一层抽象，代表一个 AI 模型厂商或服务端点。每个具体的模型配置都必须归属于某个提供商。

内置提供商 ​

Snail AI 内置了以下主流 AI 模型提供商：

提供商标识（providerKey）支持的模型类型说明
OpenAIopenaiCHAT, EMBEDDING, IMAGE, SPEECHGPT 系列、DALL-E、Whisper、TTS 等
Anthropic (Claude)claudeCHATClaude 3.5 Sonnet、Claude 3 Opus 等
OllamaollamaCHAT, EMBEDDING本地部署开源模型（Llama、Qwen、Mistral 等）
Google GeminigoogleCHAT, EMBEDDINGGemini Pro、Gemini Flash 等
火山引擎volcengineCHAT, EMBEDDING字节跳动豆包（Doubao）系列模型

OpenAI 兼容接口

除了官方 OpenAI 之外，市面上大量第三方服务（如 DeepSeek、零一万物、Moonshot 等）兼容 OpenAI API 格式。你可以直接使用 openai 提供商，只需在模型配置中修改 apiEndpoint 指向对应服务即可，无需额外添加提供商。

例如接入 DeepSeek：

  • 提供商选择：OpenAI
  • apiEndpoint：https://api.deepseek.com
  • modelKey：deepseek-chat

提供商数据结构 ​

每个提供商包含以下核心字段：

字段类型说明
idnumber提供商唯一标识
providerNamestring显示名称，如 "OpenAI"
providerKeystring唯一标识键，如 "openai"，创建后不可修改
descriptionstring提供商描述信息
iconUrlstring图标地址，用于界面展示
isEnabledboolean是否启用，禁用后该提供商下的模型不可选

管理提供商 ​

查看提供商列表 ​

在管理后台进入「模型管理」页面，顶部展示所有已注册的模型提供商卡片，包括名称、图标和启用状态。

API 调用示例：

bash
# 获取已启用的提供商列表
curl -X GET /api/ai-model/providers

# 获取全部提供商（包括已禁用的）
curl -X GET /api/ai-model/all-providers

新增提供商 ​

当内置提供商无法满足需求时，可以手动添加新的提供商。

操作步骤：

  1. 进入「模型管理」页面，点击「新增提供商」按钮
  2. 填写提供商信息：
字段是否必填说明
提供商名称是显示名称，如 "智谱 AI"
提供商标识是唯一 key，建议使用小写英文，如 "zhipu"，创建后不可修改
描述否备注信息
图标 URL否提供商图标地址
  1. 点击「确定」完成创建

API 请求示例：

json
POST /api/ai-model/provider

{
  "providerName": "智谱 AI",
  "providerKey": "zhipu",
  "description": "智谱 AI 大模型平台，提供 GLM 系列模型",
  "iconUrl": "https://example.com/zhipu-icon.png"
}

重要提示

providerKey 是全局唯一的，创建后不可修改。请使用简洁、有意义的小写英文标识。如果提交重复的 providerKey，系统将返回 DUPLICATE_PROVIDER_KEY 错误。

编辑提供商 ​

点击提供商卡片上的「编辑」按钮，可以修改名称、描述和图标。providerKey 不可修改。

json
PUT /api/ai-model/provider/{id}

{
  "providerName": "智谱 AI（GLM）",
  "description": "更新后的描述信息",
  "iconUrl": "https://example.com/zhipu-icon-v2.png"
}

启用 / 禁用提供商 ​

通过提供商卡片上的开关，可以快速启用或禁用提供商：

bash
# 启用
PUT /api/ai-model/provider/{id}/enable

# 禁用
PUT /api/ai-model/provider/{id}/disable

禁用影响

禁用提供商后，该提供商下的所有模型配置将不再出现在智能体、知识库等模块的模型选择列表中。已经绑定的模型仍会保留配置，但新的调用可能失败。请在禁用前确认无活跃使用。

删除提供商 ​

bash
DELETE /api/ai-model/provider/{id}

删除须知

删除提供商前，请先删除或迁移该提供商下的所有模型配置。如果提供商下仍存在模型配置，删除操作可能会被拒绝。

图标管理 ​

每个提供商支持配置一个图标 URL，用于在界面中展示。推荐使用：

  • 尺寸：建议 64x64 像素或以上的正方形图片
  • 格式：PNG（透明背景）或 SVG
  • 来源：可使用平台资源管理上传的图片，或直接填写外部 URL

如果未配置图标，系统会使用默认占位图标。

添加新提供商的完整流程 ​

以接入**智谱 AI（GLM-4）**为例，展示添加新提供商并配置模型的完整流程：

第一步：创建提供商 ​

在「模型管理」页面点击「新增提供商」：

  • 名称：智谱 AI
  • 标识：zhipu
  • 描述：智谱 AI 大模型服务，提供 GLM-4 系列模型

第二步：添加模型配置 ​

创建提供商后，进入「模型配置」页面，为该提供商添加具体模型：

  • 提供商：选择 智谱 AI
  • 模型名称：GLM-4
  • 模型标识：glm-4
  • 模型类型：CHAT
  • API Key：填写智谱平台获取的 API Key
  • API Endpoint：https://open.bigmodel.cn/api/paas/v4

详细的模型配置说明参见 模型配置。

第三步：验证可用性 ​

配置完成后，在创建智能体时选择该模型进行对话测试，验证配置是否正确。

常见问题 ​

Q: OpenAI 兼容接口需要创建新提供商吗？ ​

不需要。 大多数兼容 OpenAI API 的服务（如 DeepSeek、零一万物等）可以直接使用内置的 openai 提供商，只需在模型配置中修改 apiEndpoint 和 apiKey 即可。

Q: 禁用提供商后，已创建的智能体会受影响吗？ ​

已创建的智能体仍保留模型配置信息，但如果尝试发起新对话，由于模型不可用，调用将会失败。建议在禁用前将相关智能体切换到其他可用模型。

Q: 提供商标识（providerKey）的命名规范是什么？ ​

建议使用全小写英文字母、数字和连字符，如 openai、zhipu、volcano-engine。避免使用中文、空格或特殊字符。

Apache 2.0 Licensed

Copyright © 2024-present OpenSnail