添加提供商
通过添加提供商，你可以将不同的 LLM 服务接入 Elftia，在聊天中自由切换不同的模型。Elftia 提供了预设模板、自定义配置和导入/导出三种方式来添加提供商。
何时使用
- 首次使用 Elftia，需要配置 API Key 来启用默认提供商
- 需要接入默认列表中没有的 LLM 服务
- 想要添加同一提供商的多个实例（如不同区域的端点）
- 从另一台设备迁移配置
方式一：从预设模板添加
预设模板包含了提供商的 Base URL、默认模型列表和推荐配置，你只需填入 API Key 即可完成设置。
操作步骤
- 打开 设置 → 提供商管理
- 点击 添加提供商 按钮
- 在提供商列表中选择一个预设模板
- 在弹出的配置面板中，填入你的 API Key
- 直接粘贴 Key 值，如
sk-xxxxxxxxxxxxxxxx - 或使用环境变量引用，如
$OPENAI_API_KEY
- 直接粘贴 Key 值，如
-
点击 测试连接 确认 Key 有效
- 成功：显示绿色提示「连接成功」
- 失败：显示错误信息（详见 Troubleshooting）
-
开启 启用 开关
-
点击 保存
完成后，该提供商的模型将出现在聊天界面的模型选择下拉菜单中。
预设模板一览
国际提供商
| 预设 ID | 名称 | API 格式 | Base URL | 特点 |
|---|---|---|---|---|
openai | OpenAI | openai | https://api.openai.com/v1/chat/completions | GPT-4o/5, o1/o3 系列推理模型，支持视觉 |
anthropic | Anthropic | anthropic | https://api.anthropic.com/v1/messages | Claude Sonnet/Opus/Haiku 4.5，原生思维链 |
gemini | Google Gemini | https://generativelanguage.googleapis.com/v1beta/models/ | 100 万 token 上下文，视觉+推理 | |
openai-response | OpenAI (Responses API) | openai-response | https://api.openai.com | GPT-5 系列 + o3/o4，新版 API |
azure-openai | Azure OpenAI | azure-openai | (自定义) | 企业级 SLA，需部署名称作为模型 |
openrouter | OpenRouter | openai | https://openrouter.ai/api/v1 | 聚合 200+ 模型，统一 Key |
groq | Groq | openai | https://api.groq.com/openai/v1 | 极速推理引擎 |
ollama | Ollama | openai | http://localhost:11434/v1 | 本地部署，免费使用 |
中国云平台
| 预设 ID | 名称 | API 格式 | Base URL | 特点 |
|---|---|---|---|---|
zhipu | 智谱 GLM | openai | https://api.z.ai/api/paas/v4 | GLM-5/4.5/4.6V/4.7, Coding Plan |
volcengine | 火山方舟 | openai | https://ark.cn-beijing.volces.com/api/v3 | 豆包 Seed 2.0，智能路由，多模型聚合 |
kimi | Kimi (Moonshot) | openai | https://api.moonshot.ai/v1 | Kimi K2.5, 25.6 万上下文 |
dashscope | 阿里云百炼 | openai | https://dashscope.aliyuncs.com/compatible-mode/v1 | Qwen3 系列，100 万 token |
tencent | 腾讯云混元 | openai | https://api.lkeap.cloud.tencent.com/v1 | 混元 2.0，多模型聚合 |
minimax | MiniMax | anthropic | https://api.minimaxi.com/anthropic | M2.5/M2.1, Anthropic 格式 |
baidu | 百度千帆 | openai | https://qianfan.baidubce.com/v2 | ERNIE 系列, Coding Plan |
kuaishou | 快手 KwaiKAT | openai | https://wanqing.streamlakeapi.com/api/gateway/v1 | KAT-Coder, 编码专用 |
mthreads | 摩尔线程 | openai | (需配置) | 国产芯片 Coding Plan |
方式二：自定义 OpenAI 兼容提供商
如果你使用的 LLM 服务提供了 OpenAI 兼容的 API（大多数服务都支持），可以通过自定义方式添加。
操作步骤
- 打开 设置 → 提供商管理
- 点击 添加提供商 → 选择 自定义提供商
- 填写基本信息：
| 字段 | 必填 | 说明 | 示例 |
|---|---|---|---|
| 名称 | 是 | 显示名称 | My Local LLM |
| API 格式 | 是 | 选择协议格式 | openai（最常用） |
| Base URL | 是 | API 地址 | http://localhost:8080/v1/chat/completions |
| API Key | 否 | 认证密钥 | sk-...（本地服务可留空） |
- 添加模型：
- 点击 添加模型
- 输入模型 ID（调用 API 时使用的名称，如
llama-3.1-70b） - 输入显示名称
- 设置模型能力标记（视觉、函数调用、推理等）
-
（可选）配置 Transformer：
- 如果目标服务的 API 与标准 OpenAI 格式有差异，可添加适当的 Transformer
- 常见选择：
deepseek（DeepSeek 兼容服务）、groq（Groq 兼容服务）
-
点击 测试连接 验证配置
-
开启 启用 开关并保存
模型发现
部分提供商支持通过 /v1/models 端点自动发现可用模型：
- 在提供商配置中，填写 模型发现端点（如
https://api.example.com/v1/models） - 点击 发现模型 按钮
- Elftia 会调用该端点获取模型列表
- 从返回结果中选择要添加的模型
方式三：导入/导出
导出配置
- 打开 设置 → 提供商管理
- 选择要导出的提供商
- 点击 导出 按钮
- 配置将保存为 JSON 文件
导入配置
- 打开 设置 → 提供商管理
- 点击 导入 按钮
- 选择之前导出的 JSON 文件
- 确认导入的提供商信息
- 填入 API Key（出于安全考虑，导出文件中不包含 API Key）
- 保存并启用
环境变量 API Key
使用环境变量来管理 API Key 是推荐的做法，特别适合以下场景：
- 不希望将 Key 明文存储在应用数据库中
- 多台设备共享配置文件时，每台设备使用不同的 Key
- 在 CI/CD 或自动化场景中使用 Elftia
配置方法
在 API Key 输入框中，以 $ 开头输入环境变量名称：
| 输入值 | 运行时解析为 |
|---|---|
$OPENAI_API_KEY | process.env.OPENAI_API_KEY 的值 |
$ANTHROPIC_API_KEY | process.env.ANTHROPIC_API_KEY 的值 |
$MY_CUSTOM_KEY | process.env.MY_CUSTOM_KEY 的值 |
注意：如果对应的环境变量未设置，API 请求将因认证失败而报错。修改环境变量后需要重启 Elftia 才能生效。
可配置项参考
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| 名称 | 字符串 | (模板名) | 提供商显示名称 |
| API 格式 | 枚举 | openai | openai / anthropic / google / azure-openai / openai-response |
| Base URL | URL | (因模板而异) | API 请求地址，必须以 http:// 或 https:// 开头 |
| API Key | 字符串 | (空) | 支持 $ 前缀引用环境变量 |
| 模型列表 | 数组 | (因模板而异) | 可手动添加、删除或通过模型发现获取 |
| 模型发现端点 | URL | (可选) | 调用 /v1/models 等端点自动获取模型列表 |
| 启用状态 | 布尔 | false | 新添加的提供商默认禁用 |
| Transformer | 数组 | (因格式而异) | 请求/响应格式转换链 |
| 图标 | 字符串 | (因模板而异) | 提供商图标标识 |
| 官网链接 | URL | (可选) | 提供商官网，用于帮助文档跳转 |
| 备注 | 字符串 | (空) | 自由备注信息 |
| API 版本 | 字符串 | (仅 Azure) | Azure OpenAI 的 API 版本号 |
| 并发限制 | 数字 | (因提供商而异) | Agent 代理的最大并发请求数 |
| 是否官方 | 布尔 | false | 标记为官方 Anthropic 提供商（影响思维链签名处理） |
行为说明
预设模板与自定义的区别
| 特性 | 预设模板 | 自定义提供商 |
|---|---|---|
| Base URL | 自动填充 | 需手动输入 |
| 模型列表 | 预配置 | 需手动添加 |
| Transformer | 自动配置 | 可选配置 |
| 模型发现 | 部分支持 | 需手动设置端点 |
| Coding Plan | 部分支持 | 不支持 |
| 搜索集成 | 预配置 | 需手动配置 |
提供商 ID 的唯一性
每个提供商有一个唯一 ID。从同一预设模板添加多个实例时，Elftia 会自动在 ID 后追加后缀以确保唯一性。
添加后的初始状态
新添加的提供商默认处于 禁用 状态。你需要：
- 填入有效的 API Key
- 测试连接成功
- 手动开启启用开关
才能在聊天中使用该提供商的模型。
Troubleshooting
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| 测试连接返回 401 | API Key 无效或已过期 | 在提供商官网重新生成 Key |
| 测试连接返回 403 | Key 权限不足 | 确认 Key 有权限访问目标模型 |
| 测试连接超时 | 网络不通或 Base URL 错误 | 检查网络连接和 URL 拼写 |
$ENV_VAR Key 无效 | 环境变量未设置 | 在系统中设置环境变量并重启 Elftia |
| 模型发现返回空列表 | 端点不正确或 Key 无权限 | 检查模型发现端点 URL，确认 Key 有 list models 权限 |
| 保存时提示 URL 无效 | Base URL 格式不正确 | 确保以 http:// 或 https:// 开头 |
| 自定义提供商请求失败 | Transformer 配置不匹配 | 确认 API 格式选择正确，或尝试添加对应的 Transformer |
| Azure OpenAI 连接失败 | API 版本或部署名称错误 | 确认 API Version 字段已填写（如 2024-08-01-preview），模型名使用部署名称 |
| MiniMax 请求格式错误 | 未使用 anthropic 格式 | MiniMax 使用 Anthropic API 格式，需选择 anthropic 并配置 anthropic Transformer |
相关页面
- LLM 提供商概览 - 提供商系统的整体架构
- API Key 池化 - 为单个提供商配置多个 API Key
- 自定义端点 - 连接 Ollama、LM Studio 等本地服务的详细指南
- 模型参数 - 配置 temperature、max_tokens 等生成参数