模型配置

模型配置（Model Config）是模型管理的核心，定义了访问某个具体 AI 模型所需的全部参数，包括密钥、端点、模型标识和高级参数等。

配置数据结构

每条模型配置包含以下字段：

字段	类型	必填	说明
`providerId`	`number`	是	所属提供商 ID
`modelName`	`string`	是	模型显示名称，如 "GPT-4o"
`modelKey`	`string`	是	模型标识，即 API 调用时使用的 model 参数，如 `gpt-4o`
`modelType`	`ModelType`	是	模型类型：`CHAT` / `EMBEDDING` / `RERANKER` / `IMAGE` / `SPEECH`
`apiKey`	`string`	是	API 密钥（存储时加密）
`apiEndpoint`	`string`	否	API 端点地址，不填则使用提供商默认端点
`configJson`	`object`	否	高级参数配置，JSON 格式
`scope`	`ModelScope`	否	作用域：`GLOBAL`（默认）或 `PERSONAL`
`isDefault`	`boolean`	否	是否为该类型的默认模型
`isEnabled`	`boolean`	否	是否启用，默认 `true`
`description`	`string`	否	模型描述信息

创建模型配置

操作步骤

进入「模型管理」页面，点击「新增模型」按钮
选择模型提供商
填写模型基本信息和 API 参数
按需配置高级参数
点击「确定」保存

API 请求示例

json

POST /api/ai-model/config

{
  "providerId": 1,
  "modelName": "GPT-4o",
  "modelKey": "gpt-4o",
  "modelType": "CHAT",
  "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxx",
  "apiEndpoint": "https://api.openai.com",
  "description": "OpenAI 旗舰多模态模型",
  "configJson": {
    "temperature": 0.7,
    "topP": 1.0,
    "maxTokens": 4096
  }
}

各提供商配置示例

OpenAI

json

{
  "providerId": 1,
  "modelName": "GPT-4o",
  "modelKey": "gpt-4o",
  "modelType": "CHAT",
  "apiKey": "sk-proj-xxxxxxxxxxxx",
  "apiEndpoint": "https://api.openai.com"
}

Anthropic (Claude)

json

{
  "providerId": 2,
  "modelName": "Claude 3.5 Sonnet",
  "modelKey": "claude-3-5-sonnet-20241022",
  "modelType": "CHAT",
  "apiKey": "sk-ant-xxxxxxxxxxxx",
  "apiEndpoint": "https://api.anthropic.com"
}

Ollama（本地部署）

json

{
  "providerId": 3,
  "modelName": "Qwen2.5 72B",
  "modelKey": "qwen2.5:72b",
  "modelType": "CHAT",
  "apiKey": "",
  "apiEndpoint": "http://localhost:11434"
}

Ollama 特殊说明

Ollama 部署的本地模型通常不需要 API Key，apiKey 填空字符串即可。apiEndpoint 填写 Ollama 服务的地址，默认为 http://localhost:11434。

Google Gemini

json

{
  "providerId": 4,
  "modelName": "Gemini 2.0 Flash",
  "modelKey": "gemini-2.0-flash",
  "modelType": "CHAT",
  "apiKey": "AIzaSyxxxxxxxxxxxx",
  "apiEndpoint": "https://generativelanguage.googleapis.com"
}

火山引擎（豆包）

json

{
  "providerId": 5,
  "modelName": "豆包 Pro",
  "modelKey": "doubao-pro-32k",
  "modelType": "CHAT",
  "apiKey": "xxxxxxxxxxxxxxxx",
  "apiEndpoint": "https://ark.cn-beijing.volces.com/api/v3"
}

OpenAI 兼容服务（以 DeepSeek 为例）

json

{
  "providerId": 1,
  "modelName": "DeepSeek V3",
  "modelKey": "deepseek-chat",
  "modelType": "CHAT",
  "apiKey": "sk-xxxxxxxxxxxx",
  "apiEndpoint": "https://api.deepseek.com"
}

configJson 高级参数

configJson 字段允许传入 JSON 格式的高级参数，不同模型类型支持的参数不同：

CHAT 模型参数

参数	类型	默认值	说明
`temperature`	`number`	`0.7`	生成随机性，范围 0-2，越高越随机
`topP`	`number`	`1.0`	核采样概率，范围 0-1
`maxTokens`	`number`	`2048`	最大生成 Token 数
`frequencyPenalty`	`number`	`0`	频率惩罚，范围 -2 到 2
`presencePenalty`	`number`	`0`	存在惩罚，范围 -2 到 2
`timeoutMs`	`number`	`30000`	请求超时时间（毫秒）

示例：

json

{
  "temperature": 0.3,
  "topP": 0.9,
  "maxTokens": 8192,
  "frequencyPenalty": 0.5,
  "presencePenalty": 0.3,
  "timeoutMs": 60000
}

EMBEDDING 模型参数

参数	类型	说明
`dimensions`	`number`	向量维度，如 1536、1024
`batchSize`	`number`	批量处理大小

IMAGE 模型参数

参数	类型	说明
`size`	`string`	图片尺寸，如 "1024x1024"
`quality`	`string`	图片质量，如 "standard"、"hd"
`style`	`string`	风格，如 "natural"、"vivid"

默认模型管理

系统允许为每种模型类型设置一个默认模型。默认模型在以下场景中使用：

创建智能体时未手动指定对话模型
创建知识库时未手动指定向量模型
其他需要模型但未显式指定的场景

设置默认模型

方式一： 在模型配置列表中，点击目标模型的「设为默认」按钮。

方式二： 调用 API：

bash

PUT /api/ai-model/switch-default/{modelId}

查询默认模型

bash

# 查询全局默认模型
GET /api/ai-model/default

# 查询指定类型的默认模型
GET /api/ai-model/default/CHAT
GET /api/ai-model/default/EMBEDDING

注意

同一模型类型下只能有一个默认模型。设置新的默认模型时，原默认模型会自动取消默认状态。

启用 / 禁用模型

通过列表中的开关或 API 可以控制单个模型的启用状态：

bash

# 启用模型
PUT /api/ai-model/config/{id}/enable

# 禁用模型
PUT /api/ai-model/config/{id}/disable

禁用的模型：

不会出现在智能体、知识库等模块的模型选择下拉列表中
已绑定该模型的智能体仍保留配置，但新的调用会失败
使用统计数据不受影响，仍可查看历史记录

API Key 加密

Snail AI 对存储的 API Key 进行加密处理，确保密钥安全：

环节	处理方式
传输	通过 HTTPS 加密传输
存储	API Key 在写入数据库前进行加密，不以明文存储
展示	前端列表中 API Key 以脱敏方式显示（如 `sk-****xxxx`）
使用	模型调用时由后端解密后直接传递给对应厂商 API

安全提醒

请勿在 description 或 configJson 等非加密字段中存放密钥信息
定期轮换 API Key，可在模型配置中直接更新
PERSONAL 作用域的模型配置，其 API Key 仅对配置者本人可见

编辑模型配置

json

PUT /api/ai-model/config/{id}

{
  "providerId": 1,
  "modelName": "GPT-4o (Updated)",
  "modelKey": "gpt-4o",
  "modelType": "CHAT",
  "apiKey": "sk-new-key-xxxxxxxxxxxx",
  "apiEndpoint": "https://api.openai.com",
  "configJson": {
    "temperature": 0.5,
    "maxTokens": 8192
  }
}

删除模型配置

bash

DELETE /api/ai-model/config/{id}

删除须知

删除模型配置前，请确认没有智能体、知识库或记忆库正在使用该模型。建议先禁用模型，观察一段时间后再执行删除操作。

筛选与查询

模型配置列表支持多维度筛选：

筛选条件	参数	说明
提供商	`providerKey`	按提供商标识过滤
模型类型	`modelType`	按类型过滤：CHAT / EMBEDDING / RERANKER / IMAGE / SPEECH
作用域	`scope`	按作用域过滤：GLOBAL / PERSONAL
分页	`pageNum` / `pageSize`	分页参数，默认第 1 页、每页 10 条

查询示例：

bash

# 获取所有 CHAT 类型的全局模型
GET /api/ai-model/configs?modelType=CHAT&scope=GLOBAL&pageNum=1&pageSize=10

# 获取 OpenAI 提供商下的所有模型
GET /api/ai-model/configs?providerKey=openai

# 按提供商和类型联合查询
GET /api/ai-model/by-provider-type?providerKey=openai&modelType=EMBEDDING

常见问题

Q: apiEndpoint 应该填什么？

apiEndpoint 是 AI 服务的 API 根地址，不需要包含具体的路径。例如：

OpenAI：https://api.openai.com
Ollama：http://localhost:11434
DeepSeek：https://api.deepseek.com

系统会根据提供商类型自动拼接完整的请求路径。

Q: modelKey 和 modelName 有什么区别？

modelKey 是发送给 AI 服务的实际模型标识，如 gpt-4o，必须与服务端一致
modelName 是在 Snail AI 界面上显示的名称，可以自定义，如 "GPT-4o 旗舰版"

Q: configJson 中的参数不生效怎么办？

不同提供商和模型支持的参数不同，请参考对应厂商的 API 文档确认参数名称和取值范围。如果某个参数对目标模型无效，系统会忽略该参数而不会报错。

模型配置 ​

配置数据结构 ​

创建模型配置 ​

操作步骤 ​

API 请求示例 ​

各提供商配置示例 ​

OpenAI ​

Anthropic (Claude) ​

Ollama（本地部署） ​

Google Gemini ​

火山引擎（豆包） ​

OpenAI 兼容服务（以 DeepSeek 为例） ​

configJson 高级参数 ​

CHAT 模型参数 ​

EMBEDDING 模型参数 ​

IMAGE 模型参数 ​

默认模型管理 ​

设置默认模型 ​

查询默认模型 ​

启用 / 禁用模型 ​

API Key 加密 ​

编辑模型配置 ​

删除模型配置 ​

筛选与查询 ​

常见问题 ​

Q: apiEndpoint 应该填什么？ ​

Q: modelKey 和 modelName 有什么区别？ ​

Q: configJson 中的参数不生效怎么办？ ​

模型配置

配置数据结构

创建模型配置

操作步骤

API 请求示例

各提供商配置示例

OpenAI

Anthropic (Claude)

Ollama（本地部署）

Google Gemini

火山引擎（豆包）

OpenAI 兼容服务（以 DeepSeek 为例）

configJson 高级参数

CHAT 模型参数

EMBEDDING 模型参数

IMAGE 模型参数

默认模型管理

设置默认模型

查询默认模型

启用 / 禁用模型

API Key 加密

编辑模型配置

删除模型配置

筛选与查询

常见问题

Q: apiEndpoint 应该填什么？

Q: modelKey 和 modelName 有什么区别？

Q: configJson 中的参数不生效怎么办？