LLM 提供商概览
Elftia 的 LLM 提供商系统让你可以连接多个大语言模型服务，通过统一的 API 抽象在不同提供商之间无缝切换，无需关心底层 API 格式差异。
何时使用
- 需要接入新的 LLM 服务（如 OpenAI、Anthropic、DeepSeek 等）
- 想在同一个应用中使用多个提供商的模型
- 需要连接本地部署的模型（如 Ollama、LM Studio）
- 想通过 API Key 池化实现高可用和负载均衡
核心概念
提供商 (Provider)
提供商是一个 LLM API 服务的配置单元。每个提供商包含以下关键信息：
| 概念 | 说明 | 示例 |
|---|---|---|
| 名称 | 提供商的显示名称 | OpenAI、DeepSeek、智谱 GLM |
| API 格式 | 提供商使用的 API 协议格式 | openai、anthropic、google |
| Base URL | API 请求的基础地址 | https://api.openai.com/v1/chat/completions |
| API Key | 身份验证密钥 | sk-... 或环境变量引用 $OPENAI_API_KEY |
| 模型列表 | 该提供商可用的模型 | gpt-4o、claude-sonnet-4-5、gemini-3-pro |
API 格式 (API Format)
Elftia 支持 5 种 API 格式，通过内置的格式转换器 (Transformer) 自动处理请求和响应的格式差异：
| API 格式 | 说明 | 使用者 |
|---|---|---|
openai | OpenAI Chat Completions 格式 (/v1/chat/completions) | OpenAI、DeepSeek、智谱、Ollama、Groq 等大多数提供商 |
anthropic | Anthropic Messages 格式 (/v1/messages) | Anthropic 官方、MiniMax |
google | Google Gemini 格式 | Google Gemini |
azure-openai | Azure OpenAI 格式（与 OpenAI 相同，认证方式不同） | Azure OpenAI Service |
openai-response | OpenAI Responses API 格式 (/v1/responses) | OpenAI 新版 Responses API |
模型 (Model)
每个提供商下可以配置多个模型。模型配置包含：
- 模型 ID：调用 API 时使用的标识符（如
gpt-4o） - 显示名称：在界面上展示的名称（如
GPT-4o） - 类别：chat（聊天）、reasoning（推理）、code（编码）、image（图像）等
- 能力标记：是否支持视觉 (vision)、函数调用 (function call)、推理模式 (reasoning)、网络搜索 (web search)
- 上下文长度：模型支持的最大输入 token 数
- 最大输出：模型单次生成的最大 token 数
API Key
API Key 是访问提供商服务的身份凭证。Elftia 支持两种方式配置 API Key：
- 直接输入：在设置界面直接粘贴 API Key
- 环境变量引用：以
$开头引用系统环境变量（如$OPENAI_API_KEY），适用于不希望将密钥存储在应用配置中的场景
请求处理流程
用户发送消息后，Elftia 按以下流程处理请求：
用户发送消息
|
v
选择提供商和模型
|
v
解析 API Key（直接值 / 环境变量 / Key 池）
|
v
格式转换器：将统一请求转为目标 API 格式
| (openai / anthropic / google / ...)
v
发送请求到提供商 API
|
v
格式转换器：将提供商响应转为统一格式
|
v
渲染响应到聊天界面
默认提供商列表
Elftia 预装了以下提供商模板，首次启动时会自动创建（默认未启用，需填入 API Key 后启用）：
| 提供商 | API 格式 | Base URL | 特点 |
|---|---|---|---|
| DeepSeek | openai | https://api.deepseek.com/v1 | 高性价比，支持推理模式 |
| OpenRouter | openai | https://openrouter.ai/api/v1 | 聚合 200+ 模型，统一计费 |
| SiliconFlow | openai | https://api.siliconflow.cn/v1 | 国内加速，开源模型托管 |
| OpenAI | openai | https://api.openai.com/v1/chat/completions | GPT 系列、o 系列推理模型 |
| Anthropic | anthropic | https://api.anthropic.com/v1/messages | Claude 系列，原生思维链 |
| Google Gemini | https://generativelanguage.googleapis.com/v1beta/models/ | 超长上下文（100 万 token） | |
| 智谱 GLM | openai | https://api.z.ai/api/paas/v4 | GLM 系列，支持 Coding Plan |
| Moonshot (Kimi) | openai | https://api.moonshot.ai/v1 | Kimi K2.5，超长上下文 |
| 阿里云百炼 | openai | https://dashscope.aliyuncs.com/compatible-mode/v1 | Qwen 系列，100 万 token |
| Ollama | openai | http://localhost:11434/v1 | 本地部署，完全离线 |
| Groq | openai | https://api.groq.com/openai/v1 | 极速推理，低延迟 |
| Claude Code | anthropic | https://api.anthropic.com/v1/messages | Claude Agent SDK 集成 |
除以上默认提供商外，Elftia 还提供更多中国云平台的预设模板（火山方舟、腾讯云混元、百度千帆、MiniMax、快手 KwaiKAT、摩尔线程等），可在「添加提供商」界面中选择。
可配置项参考
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| 提供商名称 | 字符串 | (模板名称) | 显示名称，可自定义 |
| API 格式 | 枚举 | openai | openai / anthropic / google / azure-openai / openai-response |
| Base URL | URL | (因模板而异) | API 请求地址 |
| API Key | 字符串 | (空) | 支持 $ 前缀引用环境变量 |
| 模型列表 | 数组 | (因模板而异) | 可手动添加或通过模型发现自动获取 |
| 启用状态 | 布尔 | false | 是否在模型选择列表中显示 |
| Transformer | 对象 | (因格式而异) | 请求/响应格式转换器配置 |
| 默认参数 | 对象 | temperature: 0.7 | 提供商级别的默认生成参数 |
| API 超时 | 毫秒 | (全局设置) | 单次请求超时时间 |
| 并发限制 | 数字 | (因提供商而异) | Agent 代理的最大并发请求数 |
行为说明
提供商启用与禁用
- 禁用的提供商不会出现在模型选择下拉列表中
- 禁用提供商不会删除其配置，重新启用后所有设置保持不变
- 如果当前会话正在使用某个提供商的模型，禁用该提供商后，已有会话不受影响，但新的消息将无法使用该模型
模型发现
部分提供商支持模型发现 (Model Discovery) 功能：Elftia 会调用提供商的模型列表 API（如 /v1/models）自动获取可用模型。支持模型发现的提供商包括 OpenAI、Anthropic、Gemini、智谱等。
环境变量 API Key
当 API Key 以 $ 开头时，Elftia 会在运行时从系统环境变量中读取实际值。例如：
- 配置
$OPENAI_API_KEY→ 运行时读取process.env.OPENAI_API_KEY - 如果环境变量不存在，请求将因认证失败而报错
格式转换器
格式转换器 (Transformer) 是 Elftia 实现多 API 格式支持的核心机制。每个非 OpenAI 格式的提供商都会配置对应的转换器：
| 提供商类型 | 转换器 | 作用 |
|---|---|---|
| Anthropic 官方 | anthropic | 保持 Anthropic Messages 格式，处理思维链 |
| Google Gemini | gemini | 将请求转换为 Gemini 格式 |
| OpenAI Responses | openai-response | 适配 /v1/responses 端点 |
| OpenRouter | openrouter | 处理提供商路由配置 |
| DeepSeek | deepseek | 处理 DeepSeek 特有的推理字段 |
| Groq | groq | 适配 Groq 的参数限制 |
Troubleshooting
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| 提供商不在模型选择列表中 | 提供商未启用 | 进入提供商设置，开启启用开关 |
| 请求返回 401 错误 | API Key 无效或过期 | 检查并更新 API Key，确认 Key 有足够额度 |
| 请求返回 403 错误 | API Key 权限不足 | 检查 API Key 是否有权限访问所选模型 |
| 环境变量 Key 无效 | 环境变量名称错误或未设置 | 在系统中确认环境变量已设置并重启 Elftia |
| 请求超时 | 网络不通或提供商服务故障 | 检查网络连接，确认 Base URL 正确，尝试使用代理 |
| 模型列表为空 | 提供商不支持模型发现或 Key 无效 | 手动添加模型，或检查 API Key 是否正确 |
| 响应格式异常 | Transformer 配置不匹配 | 确认 API 格式选择正确，检查是否需要特定 Transformer |
| 中文提供商连接慢 | 网络延迟 | 确认使用正确的国内 Base URL，检查代理设置 |
相关页面
- 添加提供商 - 从预设模板或自定义配置添加新提供商
- API Key 池化 - 多 Key 负载均衡与自动故障转移
- 自定义端点 - 连接 Ollama、LM Studio 等本地服务
- 模型参数 - temperature、max_tokens 等生成参数配置