跳到主要内容

兼容 OpenAI

概览

Open WebUI 可以连接任何实现兼容 OpenAI API 的服务端或提供商。本指南介绍如何为常见的云端提供商与本地服务器配置连接。

如果你要连接的是 OpenAI 本身(或 Azure OpenAI),请参见专门的 OpenAI 指南


面向协议的设计

Open WebUI 建立在标准协议之上。与其为每个单独的 AI 提供商都开发专用模块(这通常会带来行为不一致和配置膨胀),Open WebUI 更专注于像 OpenAI 聊天补全协议 这样的协议标准。

这意味着,Open WebUI 负责界面与工具层,而你的后端应遵循通用的聊天补全标准。

  • 我们支持协议: 只要提供商遵循广泛采用的 API 标准,就能获得原生支持。我们也对 Open Responses 提供实验性支持。
  • 我们避免支持私有 API: 为了保持代码库通用且可维护,我们不会在核心中为每个厂商的非标准私有 API 单独实现适配。对于未原生支持的提供商,请使用 pipe 或 LiteLLM、OpenRouter 等中间代理进行桥接。

关于这一架构决策的完整解释,请参见 协议支持 FAQ


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

添加连接时,Open WebUI 会通过标准 Bearer token 调用提供商的 /models 端点进行验证。有些提供商根本不实现 /models 端点,或者对该端点使用了非标准认证方式。在这类情况下:

  • 连接验证会报错失败(例如 400、401 或 403)。
  • 并不意味着提供商不兼容——聊天补全依然可以正常工作
  • 你只需要在连接设置中的 Model IDs (Filter) 白名单里手动添加模型名即可。

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

提供商/models 可用吗?需要采取的操作
Anthropic可以——有内置兼容层自动发现可用
GitHub Models不可用——使用非标准路径手动把模型 ID 加入白名单
Perplexity不可用——没有该端点手动把模型 ID 加入白名单
MiniMax不可用——没有该端点手动把模型 ID 加入白名单
OpenRouter可以——但会返回海量模型强烈建议使用筛选白名单
Google Gemini可以自动发现可用
DeepSeek可以自动发现可用
Mistral可以自动发现可用
Groq可以自动发现可用

如何手动添加模型: 在连接设置中找到 Model IDs (Filter),输入模型 ID,点击 + 图标后保存。即使连接验证显示错误,这些模型依然会出现在模型选择器中。


第 1 步:添加提供商连接

  1. 在浏览器中打开 Open WebUI。
  2. 进入 ⚙️ Admin SettingsConnectionsOpenAI
  3. 点击 ➕ Add Connection
  4. 填写提供商的 URLAPI Key(见下方标签页)。输入 URL 时,字段会自动提示常见提供商端点
  5. 如果你的提供商不支持 /models 自动发现,请把模型 ID 加入 Model IDs (Filter) 白名单。
  6. 点击 Save
提示

如果 Open WebUI 运行在 Docker 中,而模型服务在宿主机上,请把 URL 里的 localhost 替换成 host.docker.internal

启用 / 禁用连接

每个连接都带有一个开关,你可以在不删除配置的情况下启用或禁用它。适合临时停用某个提供商。

云端提供商

提示

完整分步说明请查看专门的 Anthropic(Claude) 指南。

Anthropic(Claude)提供兼容 OpenAI 的端点。Open WebUI 内置兼容层,可自动识别 Anthropic URL 并完成模型发现——只要填入 API key,模型就会被自动识别。需要注意的是,这个兼容端点主要面向测试与对比;如果你要在生产环境中使用 Claude 的完整原生能力(PDF 处理、引用、extended thinking、prompt caching),Anthropic 建议使用其原生 API。

设置项
URLhttps://api.anthropic.com/v1
API Key你在 console.anthropic.com 获取的 Anthropic API key
Model IDs自动发现——可留空,或筛选到特定模型

本地服务器

Llama.cpp 可在本地通过兼容 OpenAI 的 API 服务运行高效量化的 GGUF 模型。完整安装、模型下载与服务启动步骤,请查看专门的 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,导致界面卡住,请查看 模型列表加载问题 故障排查页面以获取恢复方法。


必需的 API 端点

要与 Open WebUI 保持完整兼容,你的服务最好实现以下 OpenAI 标准端点:

端点方法是否必需用途
/v1/modelsGET推荐用于模型发现和 UI 中的模型选择。如果没有,可手动将模型加入白名单。
/v1/chat/completionsPOST必须聊天核心端点,支持流式输出和 temperature 等参数。
/v1/embeddingsPOST若要让该提供商用于 RAG(Retrieval Augmented Generation),则需要此端点。
/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 参数,它也支持工具使用(Function Calling)。


第 2 步:开始聊天!

在聊天界面中选择已连接提供商的模型,然后开始使用即可。

就是这么简单!无论你选择云端提供商还是本地服务器,都可以在 Open WebUI 中统一管理多个连接。


🚀 祝你构建出最适合自己的 AI 工作流!

本内容仅供参考,不构成任何保证、担保或合同承诺。Open WebUI 按“现状”提供。请参阅您的许可协议 以了解适用条款。