跳到主要内容

兼容 OpenAI

概述

Open WebUI 可以连接到任何实现了兼容 OpenAI 的 API 的服务器或提供商。本指南介绍了如何为流行的云端提供商和本地服务器设置连接。

对于 OpenAI 本身(或 Azure OpenAI),请参阅专门的 OpenAI 指南


面向协议的设计

Open WebUI 是围绕标准协议构建的。我们没有为每个独立的 AI 提供商构建特定的模块(这会导致行为不一致和配置臃肿),而是专注于像 OpenAI Chat Completions 协议 这样的标准。

这意味着,虽然 Open WebUI 负责界面和工具,但它要求您的后端遵循通用的 Chat Completions 标准。

  • 我们支持协议:任何遵循广泛采用的 API 标准的提供商都会得到原生支持。我们还对 Open Responses 提供了实验性支持。
  • 我们避免专有 API:为了保持通用、可维护的代码库,我们不会在核心中实现特定于提供商的非标准 API。对于不支持的提供商,请使用管道(Pipe)或类似 LiteLLM 或 OpenRouter 的中间件代理来连接它们。

有关此架构决策的详细解释,请参阅我们的 关于协议支持的 FAQ


重要提示:某些提供商的连接验证可能会失败

当您添加连接时,Open WebUI 会通过使用标准的 Bearer Token 调用提供商的 /models 端点来验证连接。一些提供商根本没有实现 /models 端点,或者对其使用了非标准的身份验证。在这些情况下:

  • 连接验证将失败并报错(例如 400、401 或 403)。
  • 这并意味着提供商不兼容——对话补全(Chat completions)仍将正常工作
  • 您只需在连接设置中手动将模型名称添加模型 ID (过滤) 白名单中。

已知存在 /models 问题的提供商:

提供商/models 是否可用?需要采取的行动
Anthropic是 — 内置兼容层自动检测正常工作
GitHub Models否 — 使用了非标准路径手动将模型 ID 添加到白名单中
Perplexity否 — 端点不存在手动将模型 ID 添加到白名单中
MiniMax否 — 端点不存在手动将模型 ID 添加到白名单中
OpenRouter是 — 但会返回数千个模型强烈建议添加过滤白名单
Google Gemini自动检测正常工作
DeepSeek自动检测正常工作
Mistral自动检测正常工作
Groq自动检测正常工作

如何手动添加模型:在连接设置中,找到 模型 ID (过滤),键入模型 ID,点击 + 图标,然后保存。即使连接验证显示错误,这些模型也将出现在您的模型选择器中。


步骤 1:添加您的提供商连接

  1. 在浏览器中打开 Open WebUI。
  2. 转到 ⚙️ 管理员设置外部连接OpenAI
  3. 点击 ➕ 添加连接
  4. 填写您的提供商的 URLAPI Key(参见下方的选项卡)。URL 字段会在您键入时自动推荐常见的提供商端点
  5. 如果您的提供商不支持 /models 自动检测,请将您的模型 ID 添加到 模型 ID (过滤) 白名单中。
  6. 点击 保存
提示

如果是在 Docker 中运行 Open WebUI,且您的模型服务器运行在宿主机上,请将 URL 中的 localhost 替换为 host.docker.internal

启用/禁用连接

每个连接都有一个开关,允许您启用或禁用它而无需删除连接。这对于临时停用某个提供商并保留其配置信息非常有用。

云端提供商

提示

有关完整的逐步操作演练,请参阅专门的 Anthropic (Claude) 指南。

Anthropic (Claude) 提供了一个兼容 OpenAI 的端点。Open WebUI 包含一个内置的兼容层,该兼容层会自动检测 Anthropic 的 URL 并处理模型发现——只需填入您的 API Key,模型就会被自动检测到。请注意,这主要用于测试和对比——如需在生产环境中使用完整的 Claude 功能(PDF 处理、引用、深度思考、Prompt 缓存),Anthropic 建议使用其原生 API。

设置项
URLhttps://api.anthropic.com/v1
API Key您在 console.anthropic.com 获取的 Anthropic API Key
模型 ID自动检测 — 留空或过滤到特定模型

本地服务器

Llama.cpp 在本地运行高效、量化的 GGUF 模型,并提供了一个兼容 OpenAI 的 API 服务器。参见专门的 Llama.cpp 指南 获取完整的设置指南(包括安装、模型下载、服务器启动)。

设置项
URLhttp://localhost:10000/v1 (或您配置的端口)
API Key留空

快速开始:

./llama-server --model /path/to/model.gguf --port 10000 --ctx-size 1024 --n-gpu-layers 40
连接超时配置

如果您的服务器启动缓慢,或者您正在通过高延迟网络进行连接,可以调节模型列表获取的超时时间:

# 调整慢速连接的超时时间(默认是 10 秒)
AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST=5

如果您保存了一个无法访问的 URL 并导致 UI 变得无响应,请参阅 模型列表加载问题 故障排除指南以了解恢复选项。


必需的 API 端点

为了确保与 Open WebUI 的完全兼容,您的服务器应实现以下 OpenAI 标准端点:

端点请求方法是否必需?用途
/v1/modelsGET推荐用于模型发现并在 UI 中选择模型。如果不可用,请手动将模型添加到白名单中。
/v1/chat/completionsPOST聊天对话的核心端点,支持流式传输和 Temperature 等参数。
/v1/embeddingsPOST如果您希望将此提供商用于 RAG (检索增强生成) 则为必需。
/v1/audio/speechPOST文本转语音 (TTS) 功能所需。
/v1/audio/transcriptionsPOST语音转文本 (STT/Whisper) 功能所需。
/v1/images/generationsPOST图像生成 (DALL-E) 功能所需。

支持的参数

Open WebUI 会传递标准的 OpenAI 参数,例如 temperaturetop_pmax_tokens(或 max_completion_tokens)、stopseedlogit_bias。如果您的模型和服务器支持 toolstool_choice 参数,它还支持工具调用 (Tool Use / Function Calling)


步骤 2:开始对话!

在对话菜单中选择您已连接的提供商模型,然后开始对话!

大功告成!无论您选择的是云端提供商还是本地服务器,您都可以在 Open WebUI 中同时管理多个连接。


🚀 祝您构建完美 AI 配置的过程一切顺利!

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.