Skip to main content

自定义端点

通过自定义端点功能，你可以将本地部署的 LLM 推理服务（如 Ollama、LM Studio）或企业私有化部署的 API 接入 Elftia。大多数本地推理框架都提供了 OpenAI 兼容的 API 接口，配置过程非常简单。

何时使用​

  • 想在本地运行开源模型（Llama、Qwen、Mistral 等），实现完全离线使用
  • 企业内网部署了私有化 LLM 服务
  • 使用 Azure OpenAI Service 而非 OpenAI 官方 API
  • 需要连接自建的推理集群（如 vLLM、TGI）
  • 想使用 LM Studio 的图形化本地推理环境

Ollama​

Ollama 是最流行的本地模型运行工具，支持一键下载和运行各种开源模型。

前置要求​

  • 已安装 Ollama（下载地址）
  • 已下载至少一个模型（如 ollama pull llama3.1）

操作步骤​

  1. 确保 Ollama 正在运行
    • Windows/macOS：Ollama 安装后默认作为后台服务运行
    • Linux：运行 ollama serve 启动服务
    • 默认监听地址：http://localhost:11434

  1. 在 Elftia 中打开 设置 → 提供商管理

  2. 找到默认的 Ollama 提供商（如果不存在，点击 添加提供商 → 选择 Ollama 预设）

  3. 确认配置：

字段值
API 格式openai
Base URLhttp://localhost:11434/v1
API Key(留空，Ollama 默认不需要认证)
  1. 添加已下载的模型：
    • 点击 添加模型
    • 输入 Ollama 中的模型名称（与 ollama list 输出一致）
    • 例如：llama3.1、qwen2.5:14b、codellama:34b

  1. 开启 启用 开关并保存

  2. 在聊天界面的模型选择中，就可以看到 Ollama 的模型了

Ollama 常用模型​

模型名称参数量用途下载命令
llama3.18B通用聊天ollama pull llama3.1
llama3.1:70b70B高质量聊天ollama pull llama3.1:70b
qwen2.5:14b14B中英文聊天ollama pull qwen2.5:14b
codellama:34b34B代码生成ollama pull codellama:34b
deepseek-coder-v216B代码辅助ollama pull deepseek-coder-v2
mistral7B轻量聊天ollama pull mistral
llava7B视觉理解ollama pull llava

远程 Ollama​

如果 Ollama 运行在局域网内的其他机器上：

  1. 在运行 Ollama 的机器上设置环境变量 OLLAMA_HOST=0.0.0.0:11434
  2. 重启 Ollama 服务
  3. 在 Elftia 中将 Base URL 改为 http://<远程IP>:11434/v1

LM Studio​

LM Studio 提供了图形化的本地模型管理和推理界面，内置 OpenAI 兼容的 API 服务器。

前置要求​

  • 已安装 LM Studio（下载地址）
  • 已下载并加载至少一个模型

操作步骤​

  1. 在 LM Studio 中启动本地服务器：
    • 打开 LM Studio
    • 切换到 Local Server 标签页
    • 加载一个模型
    • 点击 Start Server
    • 记下服务器地址（默认 http://localhost:1234）

  1. 在 Elftia 中打开 设置 → 提供商管理

  2. 点击 添加提供商 → 选择 自定义提供商

  3. 填写配置：

字段值
名称LM Studio
API 格式openai
Base URLhttp://localhost:1234/v1/chat/completions
API Keylm-studio（LM Studio 不验证 Key，但字段不能为空时填任意值）

  1. 添加模型：

    • 输入 LM Studio 中加载的模型名称
    • 模型名称需要与 LM Studio 显示的模型标识符一致

  2. 测试连接，启用并保存

vLLM / Text Generation Inference​

vLLM 和 TGI 是高性能的 LLM 推理引擎，广泛用于生产环境部署。两者都提供 OpenAI 兼容的 API。

vLLM 配置​

  1. 启动 vLLM 服务（示例）：

    python -m vllm.entrypoints.openai.api_server \
      --model meta-llama/Llama-3.1-8B-Instruct \
      --port 8000

  2. 在 Elftia 中添加自定义提供商：

字段值
名称vLLM Local
API 格式openai
Base URLhttp://localhost:8000/v1/chat/completions
API Key(留空或填入 vLLM 的 --api-key 值)
  1. 添加模型：使用 vLLM 启动时指定的 --model 名称

TGI 配置​

  1. 启动 TGI 服务后，使用其 OpenAI 兼容端点

  2. 在 Elftia 中添加自定义提供商：

字段值
名称TGI
API 格式openai
Base URLhttp://localhost:8080/v1/chat/completions
API Key(留空或填入对应值)

Azure OpenAI​

Azure OpenAI Service 使用与 OpenAI 相同的模型，但通过 Azure 平台托管，具有企业级 SLA 和数据合规保障。

前置要求​

  • Azure 订阅和 Azure OpenAI Service 访问权限
  • 已在 Azure Portal 中创建了 Azure OpenAI 资源
  • 已部署至少一个模型（得到部署名称）

操作步骤​

  1. 在 Azure Portal 中获取以下信息：
    • 终结点 (Endpoint)：格式为 https://<resource-name>.openai.azure.com
    • API 密钥：在「密钥和终结点」页面获取
    • 部署名称：在「模型部署」页面获取
    • API 版本：推荐使用 2024-08-01-preview

  1. 在 Elftia 中打开 设置 → 提供商管理

  2. 点击 添加提供商 → 选择 Azure OpenAI 预设

  3. 填写配置：

字段值示例
API 格式azure-openai--
Base URLAzure 终结点https://my-resource.openai.azure.com
API KeyAzure API 密钥xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
API VersionAPI 版本号2024-08-01-preview

  1. 添加模型：

    • 模型 ID 使用 Azure 中的 部署名称（不是模型名称）
    • 例如你把 gpt-4o 部署为 my-gpt4o，则模型 ID 填 my-gpt4o

  2. 测试连接，启用并保存

Azure 与标准 OpenAI 的区别​

特性OpenAIAzure OpenAI
Base URLhttps://api.openai.com/v1/...https://<resource>.openai.azure.com
认证Authorization: Bearer sk-...api-key: ...
模型指定使用模型名称（如 gpt-4o）使用部署名称
API 版本不需要必须指定（URL 参数）
API 格式openaiazure-openai

可配置项参考​

以下为自定义端点场景的配置项：

配置项类型默认值说明
名称字符串--自定义显示名称
API 格式枚举openai本地服务通常选 openai，Azure 选 azure-openai
Base URLURL--推理服务的 API 地址
API Key字符串(空)本地服务通常不需要，Azure 必填
API Version字符串(空)仅 Azure OpenAI 需要，如 2024-08-01-preview
模型列表数组(空)手动输入服务中可用的模型名称
Transformer数组(空)自定义端点通常不需要额外 Transformer

行为说明​

本地服务的特殊注意事项​

  • 无 API Key 验证：大多数本地服务（Ollama、LM Studio）不需要 API Key。如果 Elftia 的 API Key 字段要求必填，可以填入任意值
  • 模型热加载：部分服务支持动态加载模型。添加新模型到服务后，只需在 Elftia 中手动添加对应的模型名称即可
  • 并发限制：本地服务通常只能处理一个请求，建议将并发限制设为 1
  • 首次响应延迟：本地模型可能需要几秒钟加载到 GPU 显存，首次请求会有明显延迟

代理与网络​

  • 本地服务（localhost / 127.0.0.1）不会经过全局代理
  • 局域网服务根据代理配置可能需要添加到代理排除列表

模型能力​

本地模型的能力标记（视觉、函数调用等）需要在 Elftia 中手动设置。如果模型支持视觉但未标记，Elftia 不会向该模型发送图片。

Troubleshooting​

问题可能原因解决方案
连接被拒绝 (Connection refused)本地服务未启动确认 Ollama/LM Studio/vLLM 正在运行
连接超时端口不正确或防火墙阻止检查端口号，确认防火墙允许连接
模型不存在 (Model not found)模型名称与服务端不匹配使用 ollama list 或服务端的模型列表确认名称
Ollama 远程连接失败Ollama 默认只监听 localhost设置 OLLAMA_HOST=0.0.0.0:11434 并重启
LM Studio 返回空响应模型未加载到内存在 LM Studio 中确认模型已加载并显示 Ready
Azure 返回 404部署名称错误确认使用部署名称而非模型名称作为模型 ID
Azure 返回 401API 版本或密钥错误检查 API Version 字段和 API Key
响应中文乱码模型不支持中文切换到支持中文的模型（如 Qwen、ChatGLM）
GPU 内存不足模型太大选择更小的量化版本（如 llama3.1:8b-q4_0）
请求卡住无响应本地服务正在加载模型等待模型加载完成，首次请求可能需要 10-30 秒

相关页面​