模型厂商接入
适用角色：管理员
前置条件：已准备好厂商的 API Key
⚠️ 本篇是第一优先级。平台没有默认语言模型时，所有用户都无法发起对话，界面会提示「系统尚未配置语言模型，无法开始对话」。
一、概念
| 概念 | 说明 |
|---|---|
| 厂商（Provider） | 一个大模型服务的接入条目，含地址、密钥、可用模型列表 |
| 内置厂商 | 平台预置的厂商模板，填入 API Key 即可用 |
| 自定义厂商 | 完全自行填写的地址与模型列表 |
| 默认语言模型 | 所有用户默认使用的那一个模型。必配 |
| 默认生图模型 | 出图任务的默认模型。可选 |
| 可选模型白名单 | 限定用户能在下拉里看到的模型；不在名单内的模型对用户不可见 |
模型分两类：
| 类型 | 用途 | 是否必配 |
|---|---|---|
| 对话类 | 文本对话、代码生成、文档处理 | ✅ 必配 |
| 生图类 | 文生图、图生图、局部重绘 | ❌ 可选 |
接入协议分两种：
| 协议 | 适用 | 说明 |
|---|---|---|
| OpenAI 兼容 | 绝大多数第三方服务 | 标准 /v1/chat/completions 风格 |
| 阿里百炼 DashScope | 阿里云百炼 | 原生协议，支持通义、万相等系列 |
二、厂商列表
| 列 | 说明 |
|---|---|
| 厂商 | 厂商名称与 ID |
| 类型 | 内置／自定义 |
| 模型类型 | 对话／生图 |
| 协议 | OpenAI 兼容／DashScope |
| 认证类型 | API Key |
| API Key | 脱敏显示（前几位＋后 4 位），可点击查看完整 |
| 状态 | 启用／停用 |
| 更新时间 | 最后一次修改时间 |
列表上方有两块：
| 区域 | 作用 |
|---|---|
| 当前可选模型 | 已加入白名单的模型标签 |
| 厂商列表 | 全部已接入的厂商 |
三、接入新厂商
点击「接入新厂商」，先选择模型类型。
3.1 对话类 · 内置厂商
内置厂商只需填 API Key，地址与模型列表由平台预置。
| 字段 | 是否必填 | 说明 |
|---|---|---|
| 厂商 ID | ✅ | 平台预置，不可改 |
| API Key | ✅ | 厂商后台申请 |
| 状态 | — | 启用／停用 |
3.2 对话类 · 自定义厂商
自定义厂商需自行填写全部信息。
| 字段 | 是否必填 | 说明 |
|---|---|---|
| 厂商 ID | ✅ | 英文／数字／下划线，须以英文开头 |
| 厂商名称 | ✅ | 显示用 |
| API 协议 | ✅ | OpenAI 兼容／DashScope |
| API Key | ✅ | 加密存储 |
| Base URL | ✅ | 服务地址，如 https://dashscope.aliyuncs.com/compatible-mode/v1 |
| 模型列表（JSON） | ✅ | 可用模型清单 |
| 请求头（JSON） | ❌ | 需要额外鉴权头时填写 |
| NPM 包名 | ❌ | 仅部分协议需要 |
模型列表 JSON 格式：
json
[
{ "id": "gpt-4o", "name": "GPT-4o" },
{ "id": "deepseek-chat", "name": "DeepSeek V3" }
]3.3 生图类模型
生图类厂商配置方式与对话类相同，部分厂商的模型列表需按厂商文档的格式填写。
3.4 测试连接
| 结果 | 处理 |
|---|---|
| 连接成功 | 可保存并启用 |
| 连接失败 | 检查 Base URL、API Key、模型 ID 是否与厂商文档一致 |
提示 · 列表中已有厂商也可随时点「测试」复检。
3.5 编辑与删除
注意 · 删除厂商与部分改动需要重启后端才完全生效，界面会给出提示。停用（状态改为停用）则即时生效且可随时启用。
四、配置默认模型
4.1 默认语言模型
在「默认模型」卡片中选择一个对话类模型并保存。
| 项 | 说明 |
|---|---|
| 生效范围 | 所有用户、所有新建会话的初始模型 |
| 是否必配 | ✅ 必配 |
| 生效时间 | 即时 |
注意 · 只有一个默认语言模型。用户可以在输入区自行切换到白名单内的其他模型。
4.2 默认生图模型
在「默认生图模型」卡片中选择一个生图类模型并保存。未配置时，框选精修等出图入口不可用。
五、配置可选模型白名单
在「当前可选模型」卡片中勾选允许用户使用的模型，保存后生效。
| 场景 | 建议 |
|---|---|
| 控制成本 | 只放开经过压测的模型，把高价位模型留给特定部门 |
| 统一体验 | 只放开一个模型，避免用户选到不熟悉的模型 |
| 分阶段灰度 | 先放开 1–2 个新模型，观察后再扩大范围 |
| 现象 | 原因 |
|---|---|
| 用户下拉里看不到某个模型 | 不在白名单内 |
| 用户下拉为空 | 白名单未配置，或所有模型都被停用 |
六、常见问题
| 现象 | 原因 | 处理 |
|---|---|---|
| 用户提示「系统尚未配置语言模型」 | 未设默认语言模型 | 配置默认语言模型 |
| 测试连接失败 | Base URL / API Key / 模型 ID 不匹配 | 核对厂商文档后重测 |
| 删不掉厂商 | 可能正被默认模型引用 | 先切换默认模型 |
| 改了配置但没生效 | 该项改动需要重启后端 | 按界面提示重启 |
| 生图入口不可用 | 未配置生图模型 | 配置默认生图模型 |
七、相关页面
| 页面 | 内容 |
|---|---|
| 能力配置 | 智能体、场景、插件、MCP |
| 基础配置 | 机构、系统参数、数据字典 |