Open WebUI

Open WebUI 快速入门

给 Ollama 装上 ChatGPT 的界面 —— 自托管、功能全、完全免费。

这是什么？适合谁？

Open WebUI 是一款开源的 AI 对话 Web 界面，让你用自己的电脑当服务器，通过浏览器访问 ChatGPT 式的 AI 对话体验。它支持 Ollama 和 OpenAI 兼容 API 作为后端，自带 RAG（文档问答）、Web 搜索、多模态（图片理解）、多用户管理、语音交互、Python 函数管道等功能。GitHub 146K+ stars（AI 界最受欢迎的 Web UI 之一），MIT 开源，总下载量超 3.61 亿次，社区成员 46 万+。

适合谁？一是注重隐私的团队，需要自托管 AI 聊天服务，数据不出内网；二是个人开发者，想给本地 Ollama 模型配一个漂亮的 Web 界面；三是小型企业，需要多用户 AI 对话平台但不想付费购买 SaaS 服务。不适合：只需要简单对话的个人用户（直接用 ChatGPT 网页），以及需要大规模并发服务的企业（建议用专业部署方案）。

准备工作

• 安装：推荐 Docker：docker run -d -p 3000:8080 --name open-webui ghcr.io/open-webui/open-webui:main；或 pip install open-webui
• 后端：Ollama 或 OpenAI 兼容 API
• 设备：建议 8GB+ 内存（含模型推理则需更多）
• 前置知识：Docker 基础或 Python 基础

3 步快速上手

第 1 步：启动 Ollama

ollama serve  # 启动 Ollama 服务
ollama pull deepseek-v4-flash  # 下载模型

第 2 步：启动 Open WebUI

docker run -d -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  ghcr.io/open-webui/open-webui:main

第 3 步：打开浏览器访问

打开 http://localhost:3000，注册管理员账号，选择模型，开始对话。

常见踩坑

踩坑 1：无法连接 Ollama

• 症状：Open WebUI 显示”无法连接到 Ollama”
• 原因：Docker 容器内无法访问宿主机的 localhost
• 解决：Docker 运行时添加 --add-host=host.docker.internal:host-gateway，并在设置中使用 http://host.docker.internal:11434

踩坑 2：文档上传失败

• 症状：上传 PDF 后 RAG 功能不可用
• 原因：需要额外配置嵌入模型
• 解决：在设置中配置嵌入模型（如 Ollama 的 nomic-embed-text）

踩坑 3：Docker 数据卷丢失导致配置重置

• 症状：重启容器后所有用户、配置、对话历史丢失
• 原因：未挂载持久化数据卷
• 解决：启动时务必挂载数据卷 -v open-webui:/app/backend/data，使用命名卷而非匿名卷

踩坑 4：多用户模式下管理员账号丢失

• 症状：忘记管理员账号密码，无法管理其他用户
• 原因：首次注册的账号自动成为管理员，未保留恢复机制
• 解决：使用 Docker Exec 进入容器修改数据库，或通过 WEBUI_SECRET_KEY 环境变量提前备份

踩坑 5：接入 OpenAI 兼容 API 后模型不显示

• 症状：配置了 OpenAI API 但下拉列表中无模型
• 原因：API 端点的 /v1/models 未正确暴露或鉴权错误
• 解决：在设置中确认 API URL 格式正确（如 https://api.openai.com/v1），检查 API Key 是否正确

踩坑 6：Web 搜索功能不生效

• 症状：开启 Web 搜索后 AI 仍无法联网检索信息
• 原因：默认搜索 API 未配置或服务不可用
• 解决：在管理员设置中配置搜索引擎接口（SeARCh / Google PSE 等），或自建搜索引擎服务

踩坑 7：大模型推理时内存不足

• 症状：加载 30B+ 参数模型时 Open WebUI 崩溃或无响应
• 原因：系统内存/显存不足
• 解决：确保至少 16GB+ 内存（Ollama 运行大模型时），或使用量化版本模型（如 Q4_K_M）

初级用法

1. 多模型监听 — 在 Open WebUI 设置中切换不同的 Ollama 模型，同一个界面对话不同模型，对比输出质量
2. 对话历史管理与搜索 — 所有对话自动保存，可在侧边栏搜索历史对话、标注标签，便于回顾和整理
3. 上传文档做 RAG 问答 — 点击上传按钮选择 PDF / Word / TXT 文件，Open WebUI 自动解析并建立检索索引，然后针对文档内容提问
4. 内置图片理解 — 直接上传图片到对话中，支持多模态模型（如 LLaVA、GPT-4o）理解图片内容，截图问问题和分析图表

高级玩法

1. 多用户与权限管理 — Open WebUI 原生支持多用户注册，管理员可为不同用户分配不同模型访问权限和每日额度限制，适合团队部署
2. 自定义 Python 函数管道 — 在「Functions」面板编写 Python 函数，作为管线连接在 LLM 前后，实现内容过滤、格式转换、数据增强等自定义逻辑
3. 语音交互 — 配置语音输入（Whisper）和语音输出（TTS），实现真正的语音对话体验，适合无障碍场景或免手持操作
4. 外部工具集成 — 通过「Tools」面板配置外部工具（如网络搜索、代码执行、数据库查询），让 AI Agent 具备执行能力，不再局限于文本生成
5. Sovereign AI 企业部署 — 使用 Open WebUI 的 Enterprise 方案实现 SSO、RBAC、审计日志和数据驻留，配合 air-gapped 部署满足合规要求

小技巧

1. pip 安装更灵活 — pip install open-webui 一行安装，省去 Docker 学习成本，适合 Python 开发者和服务器端部署
2. 自定义 Prompt 库 — 在 Community 面板浏览 openwebui.com 上 46 万+ 社区成员分享的 Prompt，一键导入即用
3. 模型参数调节 — 每次对话可在右上角调节 Temperature、Top P、Max Tokens 等参数，针对不同任务调优
4. 多模态快捷键 — 拖拽图片直接到输入框即可发送，无需点击上传按钮
5. API 兼容性 — Open WebUI 完全兼容 OpenAI API 格式，ChatGPT 客户端的代码可直接复用，无需修改端点地址

进阶学习建议

• 自定义 Function 管线：深入 Open WebUI 的 Functions（Pipelines）子系统，Python 函数管线的设计非常灵活，可以构建内容审查、多步推理、数据预处理等自定义流程
• 探究 Community 生态：openwebui.com 社区已积累大量 Prompt、Model 配置、Tools 和 Functions，研究高赞项目可以快速理解社区最佳实践
• 结合 Ollama 构建私有 AI 知识库：将公司文档、技术手册等非公开资料通过 RAG 索引，配合本地的嵌入模型和 LLM，构建 100% 数据自控的企业知识库
• Enterprise 部署实践：Open WebUI 的 Enterprise 方案支持 SSO（OIDC/SAML）、RBAC 和审计日志，对于有合规需求的组织，部署 Open WebUI 是成本最低的私有 AI 平台方案之一

FAQ 常见问题

Q: Open WebUI 收费吗？

A: 完全免费。MIT 协议开源。Enterprise 方案（SSO/RBAC/审计日志/数据驻留）按企业合同收费。社区版功能已足够大多数用户使用。

Q: 必须搭配 Ollama 使用吗？

A: 不是。Open WebUI 支持 Ollama 和任何 OpenAI 兼容 API（包括 OpenAI、Anthropic、Google、OpenRouter、本地 vLLM 等）。你可以混合使用本地模型和云端 API。

Q: 支持移动端访问吗？

A: 支持。通过浏览器访问部署好的 Open WebUI 地址即可在手机和平板上使用。PWA 支持将应用添加到桌面。

Q: 数据安全吗？

A: 数据完全在你的服务器上，不会发送到第三方。对话记录、上传的文档均存储在本地 Docker 数据卷或指定路径中。Enterprise 版支持数据驻留和 air-gapped 部署。

Q: 社区多大？

A: GitHub 146K+ stars，总下载量 3.61 亿+，460K+ 社区成员，293 个活跃 Issue，247 个开放 PR。是 AI 自托管领域最活跃的开源项目之一。

参考链接

• Open WebUI 官网
• Open WebUI GitHub
• Open WebUI 文档
• Open WebUI 社区
• Ollama 官网

免责声明

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测