DeepSeek09-open-webui使用

Open WebUI 完全指南：从安装到知识库搭建与异常处理

最后更新：2025年6月7日 | 适用版本：Open WebUI v0.6.x

---

一、安装部署

1.1 系统要求

• **Python 3.12 **（严格版本要求，更高版本3.13不兼容）
• Node.js 20.x+
• 内存 ≥ 4GB（知识库场景建议≥8GB）

1.2 两种安装方式

✅ 方式一：Docker安装（推荐）

# 基础命令（Ollama在本地运行）
docker run -d -p 3000:8080 \\--add-host=host.docker.internal:host-gateway \\-v open-webui:/app/backend/data \\--name open-webui \\--restart always \\ghcr.io/open-webui/open-webui:main# GPU加速版（Nvidia显卡）
docker run -d -p 3000:8080 \\--gpus all \\--add-host=host.docker.internal:host-gateway \\-v open-webui:/app/backend/data \\--name open-webui \\ghcr.io/open-webui/open-webui:cuda# 国内镜像替代（解决拉取失败）
docker run ... ghcr.nju.edu.cn/open-webui/open-webui:main

✅ 方式二：Python pip安装

# 创建虚拟环境（避免依赖冲突）
python -m venv openwebui-env
source openwebui-env/bin/activate  # Linux/macOS
openwebui-env\\Scripts\\activate    # Windows# 安装并启动
pip install open-webui
open-webui serve --port 8080

访问：http://localhost:8080

---

1.3 离线（内网安装）

1.3.1 联网下载所需要的python以及whl包

1. 下载python3.11.9安装包

   • https://mirrors.huaweicloud.com/python/3.11.9/
   • https://www.python.org/downloads/release/python-3119/

2. 下载依赖包：

   Python3.11.9\python.exe -m venv open_webui_env_py3119 
   open_webui_env_py3119\Scripts\activate
   mkdir open_webui_py3119_whls
   python.exe -m pip download -d ./open_webui_py3119_whls  pip==25.1.1
   python.exe -m pip install --upgrade pip
   pip download -d ./open_webui_py3119_whls open-webui 
   pip download -d ./open_webui_py3119_whls huggingface_hub
   pip download -d ./open_webui_py3119_whls setuptools==80.9.0 packaging==25.0 fsspec==2025.5.1 
   pip download -d ./open_webui_py3119_whls setuptools==65.5.0 packaging==23.2 fsspec==2025.3.0
   

   注意：
   Windows 下载 Linux 包需追加 --platform linux_x86_64
   Linux 下载 Windows 包需追加 --platform win_amd64
   确保离网环境的 Python 版本与下载时一致（必须为 3.11）

3. 编译生成whl

   cd open_webui
   pip download -d ./open_webui_py3119_whls build 
   pip install build
   cd compile_whls\docx2txt-0.8
   python -m build --wheel
   cd ..\google_api_python_client-2.171.0
   python -m build --wheel
   cd ..\langdetect-1.0.9
   python -m build --wheel
   cd ..\peewee-3.18.1
   python -m build --wheel
   cd ..\PyPika-0.48.9
   python -m build --wheel
   cd ..\red-black-tree-mod-1.22
   python -m build --wheel
   cd ..\win_unicode_console-0.5
   python -m build --wheel
   

4. 将生成的whl文件拷入open_webui_py3119_whls目录下

1.3.2 联网下载所需要的模型

1. 安装模型下载工具：
   在 Python 环境中执行以下命令安装工具

   pip install huggingface_hub
   HF_ENDPOINT=https://hf-mirror.com huggingface-cli download --resume-download sentence-transformers/all-MiniLM-L6-v2 --local-dir .\used_models
   

2. 下载模型：

• 方式一：默认路径下拷贝出模型：
  压缩拷贝目录:
  C:\Users\%USERNAME%\.cache\huggingface\hub\models--sentence-transformers--all-MiniLM-L6-v2

• 方式二：下载模型

set HF_ENDPOINT=https://hf-mirror.com
huggingface-cli download --force-download sentence-transformers/all-MiniLM-L6-v2 --local-dir .\used_models\sentence-transformers\all-MiniLM-L6-v2

1.3.3 离线安装open-webui

1. 安装python3.11
2. 生成虚拟环境：python -m venv open_webui_env_py3119
3. 安装open-webui

open_webui_env_py3119\Scripts\activate
# 进入依赖目录执行离线安装
pip install --no-index --find-links .\open_webui_py3119_whls .\open_webui_py3119_whls\open_webui-0.6.13-py3-none-any.whl

4. 拷贝模型文件到虚拟环境的目录：

open_webui_env_py3119\models\all-MiniLM-L6-v2

####1.3.4 离线恢复模型：

• 方式一：将模型放到默认路径下：

将all-MiniLM-L6-v2下的内容拷贝到
C:\Users\%USERNAME%\.cache\huggingface\hub\models--sentence-transformers--all-MiniLM-L6-v2
目录下

• 方式二：修改环境变量，指向模型所在目录

set RAG_EMBEDDING_MODEL=path\to\sentence-transformers\all-MiniLM-L6-v2
open-webui serve  # 正常应显示启动日志，无下载请求

附：离网部署流程全景图

二、核心配置

2.1 连接大模型

本地Ollama模型配置

1. 登录后进入 管理员面板 > 设置 > 外部连接
2. 添加Ollama API：
   • URL：http://host.docker.internal:11434（Docker）
   • URL：http://localhost:11434（本地安装）
3. 在聊天界面选择本地模型（如Llama3）

外部API配置（DeepSeek/OpenAI等）

服务商	API地址	Key获取地址
DeepSeek	https://api.deepseek.com	https://platform.deepseek.com
硅基流动	https://api.siliconflow.cn/v1	https://cloud.siliconflow.cn
OpenAI	https://api.openai.com/v1	https://platform.openai.com

# Docker环境配置示例
docker run -d -p 3000:8080 \\-e OPENAI_API_KEY=sk-xxx \\-v open-webui:/app/backend/data \\--name open-webui \\ghcr.io/open-webui/open-webui:main

2.2 中文界面设置

1. 右上角用户菜单 → Settings
2. General → Language → 简体中文

---

三、知识库创建与管理

3.1 通过Web界面创建

1. 进入 工作区 → 知识库
2. 点击 + 新建知识库，输入名称和描述
3. 上传文档：
   • 支持格式：PDF、DOCX、TXT、Markdown
   • 单个文件 ≤100MB
4. 绑定模型：
   • 创建新聊天 → 点击 # 选择知识库
   • 或创建专用模型：工作区 → 模型 → 新建

3.2 通过API创建（自动化）

import requests# 1. 创建知识库
create_url = "http://localhost:8080/api/v1/knowledge/create"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
data = {"name": "技术文档库", "description": "API创建示例"}
response = requests.post(create_url, headers=headers, json=data)
knowledge_id = response.json()["id"]# 2. 上传文件
file_url = "http://localhost:8080/api/v1/files/"
files = {"file": open("manual.pdf", "rb")}
file_res = requests.post(file_url, headers=headers, files=files)
file_id = file_res.json()["id"]# 3. 绑定到知识库
bind_url = f"http://localhost:8080/api/v1/knowledge/{knowledge_id}/file/add"
requests.post(bind_url, headers=headers, json={"file_id": file_id})

---

四、异常处理大全

4.1 安装类问题

❌ pip install open-webui 失败

解决方案：

1. 确认Python版本为3.11：python -V
2. 使用虚拟环境安装:：

   python -m venv openwebui
   openwebui\\Scripts\\activate
   pip install open-webui
   

❌ Docker容器无法连接Ollama

解决方案：

   # 添加网络参数
docker run -d --network=host \\-e OLLAMA_BASE_URL=http://127.0.0.1:11434 \\-v open-webui:/app/backend/data \\--name open-webui \\ghcr.io/open-webui/open-webui:main

4.2 知识库相关故障

❌ RAG功能失效（本地模型）

现象：：Ollama ≥0.2.2 时知识库检索失败
修复方案：

1. 进入 管理员面板 > 设置 > 文档

2. 修改以下参数：

   • Top K 设为 1
   • 上下文长度 设为 8192

3. 或降级Ollama：ollama install version 0.2.1

❌ PDF文件解析失败

解决方案：

1. 管理员面板 → 设置 → 文档：

   • 开启 PDF图像处理
   • 内容提取引擎选 Unstructured

2. 安装依赖：

# 在Open WebUI后台目录执行
pip install pdf2image unstructured

4.3 性能优化问题

❌ 首屏加载缓慢

解决方案：

1. 管理员面板 → 设置 → 外部连接

2. 删除无效的API预设（如默认的OpenAI/ChatGPT链接）10

❌ Nginx反向代理404

配置示例：

location / {proxy_pass http://localhost:3000;proxy_set_header Host $host;
}# WebSocket支持（必需！）
location /ws {proxy_pass http://localhost:3000;proxy_http_version 1.1;proxy_set_header Upgrade $http_upgrade;proxy_set_header Connection "Upgrade";
} 

五、高级技巧

5.1 知识库优化配置

1. 向量模型选择：

ollama pull nomic-embed-text  # 下载高效向量模型

2. 管理员面板 → 设置 → 模型：
   • 语义向量模型引擎：Ollama
   • 语义向量模型：nomic-embed-text 8

5.2 安全加固

# 启用HTTPS和访问控制
docker run -d -p 443:8080 \\-e ENABLE_AUTH=true \\-e WEBUI_SECRET_KEY=your_strong_key \\-v ssl_certs:/certs \\--name open-webui \\ghcr.io/open-webui/open-webui:main

5.3 性能监控

内置Prometheus指标端点：
http://localhost:8080/metrics

六、架构示意图

通过以上配置，可实现：本地模型对话 + 云API增强 + 私有知识库检索 三位一体能力

附录：常见问题速查表

| 问题现象 | 解决方案 | 引用 |
| 安装时pip报版本不匹配 | 使用Python 3.11虚拟环境 | 链接 |
| RAG返回结果不相关 | 设置Top K=1，上下文长度=8192 | |
| 知识库上传PDF失败 | 开启PDF图像处理 + 安装pdf2image | 链接 |
| 反向代理后WebSocket中断 | 配置Nginx的/ws路径代理 | 链接 |
| 中文显示乱码 | 后台设置 → 语言 → 简体中文 | |

提示：获取最新文档请访问 Open WebUI 官方GitHub
如遇复杂问题，建议通过 docker logs open-webui 查看实时日志

© 著作权归作者所有