跳到主要内容

添加提供商

通过添加提供商,你可以将不同的 LLM 服务接入 Elftia,在聊天中自由切换不同的模型。Elftia 提供了预设模板、自定义配置和导入/导出三种方式来添加提供商。

何时使用​

  • 首次使用 Elftia,需要配置 API Key 来启用默认提供商
  • 需要接入默认列表中没有的 LLM 服务
  • 想要添加同一提供商的多个实例(如不同区域的端点)
  • 从另一台设备迁移配置

方式一:从预设模板添加​

预设模板包含了提供商的 Base URL、默认模型列表和推荐配置,你只需填入 API Key 即可完成设置。

操作步骤​

  1. 打开 设置 → 提供商管理
  2. 点击 添加提供商 按钮
  3. 在提供商列表中选择一个预设模板
  1. 在弹出的配置面板中,填入你的 API Key
    • 直接粘贴 Key 值,如 sk-xxxxxxxxxxxxxxxx
    • 或使用环境变量引用,如 $OPENAI_API_KEY
  1. 点击 测试连接 确认 Key 有效

    • 成功:显示绿色提示「连接成功」
    • 失败:显示错误信息(详见 Troubleshooting)
  2. 开启 启用 开关

  3. 点击 保存

完成后,该提供商的模型将出现在聊天界面的模型选择下拉菜单中。

预设模板一览​

国际提供商​

预设 ID名称API 格式Base URL特点
openaiOpenAIopenaihttps://api.openai.com/v1/chat/completionsGPT-4o/5, o1/o3 系列推理模型,支持视觉
anthropicAnthropicanthropichttps://api.anthropic.com/v1/messagesClaude Sonnet/Opus/Haiku 4.5,原生思维链
geminiGoogle Geminigooglehttps://generativelanguage.googleapis.com/v1beta/models/100 万 token 上下文,视觉+推理
openai-responseOpenAI (Responses API)openai-responsehttps://api.openai.comGPT-5 系列 + o3/o4,新版 API
azure-openaiAzure OpenAIazure-openai(自定义)企业级 SLA,需部署名称作为模型
openrouterOpenRouteropenaihttps://openrouter.ai/api/v1聚合 200+ 模型,统一 Key
groqGroqopenaihttps://api.groq.com/openai/v1极速推理引擎
ollamaOllamaopenaihttp://localhost:11434/v1本地部署,免费使用

中国云平台​

预设 ID名称API 格式Base URL特点
zhipu智谱 GLMopenaihttps://api.z.ai/api/paas/v4GLM-5/4.5/4.6V/4.7, Coding Plan
volcengine火山方舟openaihttps://ark.cn-beijing.volces.com/api/v3豆包 Seed 2.0,智能路由,多模型聚合
kimiKimi (Moonshot)openaihttps://api.moonshot.ai/v1Kimi K2.5, 25.6 万上下文
dashscope阿里云百炼openaihttps://dashscope.aliyuncs.com/compatible-mode/v1Qwen3 系列,100 万 token
tencent腾讯云混元openaihttps://api.lkeap.cloud.tencent.com/v1混元 2.0,多模型聚合
minimaxMiniMaxanthropichttps://api.minimaxi.com/anthropicM2.5/M2.1, Anthropic 格式
baidu百度千帆openaihttps://qianfan.baidubce.com/v2ERNIE 系列, Coding Plan
kuaishou快手 KwaiKATopenaihttps://wanqing.streamlakeapi.com/api/gateway/v1KAT-Coder, 编码专用
mthreads摩尔线程openai(需配置)国产芯片 Coding Plan

方式二:自定义 OpenAI 兼容提供商​

如果你使用的 LLM 服务提供了 OpenAI 兼容的 API(大多数服务都支持),可以通过自定义方式添加。

操作步骤​

  1. 打开 设置 → 提供商管理
  2. 点击 添加提供商 → 选择 自定义提供商
  1. 填写基本信息:
字段必填说明示例
名称是显示名称My Local LLM
API 格式是选择协议格式openai(最常用)
Base URL是API 地址http://localhost:8080/v1/chat/completions
API Key否认证密钥sk-...(本地服务可留空)
  1. 添加模型:
    • 点击 添加模型
    • 输入模型 ID(调用 API 时使用的名称,如 llama-3.1-70b)
    • 输入显示名称
    • 设置模型能力标记(视觉、函数调用、推理等)
  1. (可选)配置 Transformer:

    • 如果目标服务的 API 与标准 OpenAI 格式有差异,可添加适当的 Transformer
    • 常见选择:deepseek(DeepSeek 兼容服务)、groq(Groq 兼容服务)
  2. 点击 测试连接 验证配置

  3. 开启 启用 开关并保存

模型发现​

部分提供商支持通过 /v1/models 端点自动发现可用模型:

  1. 在提供商配置中,填写 模型发现端点(如 https://api.example.com/v1/models)
  2. 点击 发现模型 按钮
  3. Elftia 会调用该端点获取模型列表
  4. 从返回结果中选择要添加的模型

方式三:导入/导出​

导出配置​

  1. 打开 设置 → 提供商管理
  2. 选择要导出的提供商
  3. 点击 导出 按钮
  4. 配置将保存为 JSON 文件

导入配置​

  1. 打开 设置 → 提供商管理
  2. 点击 导入 按钮
  3. 选择之前导出的 JSON 文件
  4. 确认导入的提供商信息
  5. 填入 API Key(出于安全考虑,导出文件中不包含 API Key)
  6. 保存并启用

环境变量 API Key​

使用环境变量来管理 API Key 是推荐的做法,特别适合以下场景:

  • 不希望将 Key 明文存储在应用数据库中
  • 多台设备共享配置文件时,每台设备使用不同的 Key
  • 在 CI/CD 或自动化场景中使用 Elftia

配置方法​

在 API Key 输入框中,以 $ 开头输入环境变量名称:

输入值运行时解析为
$OPENAI_API_KEYprocess.env.OPENAI_API_KEY 的值
$ANTHROPIC_API_KEYprocess.env.ANTHROPIC_API_KEY 的值
$MY_CUSTOM_KEYprocess.env.MY_CUSTOM_KEY 的值

注意:如果对应的环境变量未设置,API 请求将因认证失败而报错。修改环境变量后需要重启 Elftia 才能生效。

可配置项参考​

配置项类型默认值说明
名称字符串(模板名)提供商显示名称
API 格式枚举openaiopenai / anthropic / google / azure-openai / openai-response
Base URLURL(因模板而异)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 后追加后缀以确保唯一性。

添加后的初始状态​

新添加的提供商默认处于 禁用 状态。你需要:

  1. 填入有效的 API Key
  2. 测试连接成功
  3. 手动开启启用开关

才能在聊天中使用该提供商的模型。

Troubleshooting​

问题可能原因解决方案
测试连接返回 401API Key 无效或已过期在提供商官网重新生成 Key
测试连接返回 403Key 权限不足确认 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

相关页面​