在离线模式下运行 Open WebUI 🔌

注意

本教程由社区贡献，不属于 Open WebUI 团队官方支持范围。内容仅用于演示如何根据你的特定场景自定义 Open WebUI。想参与贡献？请查看贡献教程。

如果你希望以离线模式运行 Open WebUI，需要结合你的安装方式，按需调整可用功能。本指南会介绍几种实现方式，以尽量获得接近在线版本的使用体验。

“离线模式” 是什么意思？

Open WebUI 的离线模式允许应用在无互联网连接时运行。这有助于为你的 LLM 和工具构建“气隙（air-gapped）”环境（完全气隙需将实例与互联网彻底隔离）。

信息

启用离线模式后将禁用的功能：

• 自动版本更新检查（由 ENABLE_VERSION_UPDATE_CHECK 控制）
• 从 Hugging Face Hub 下载嵌入模型（由 HF_HUB_OFFLINE 控制）
  • 若在启用离线模式前未预先下载嵌入模型，RAG、网页搜索和文档分析功能将无法正常工作
• 嵌入模型、重排模型和 Whisper 模型的自动更新
• UI 中的更新通知

仍可用：

• 外部 LLM API 连接（OpenAI 等）
• OAuth 认证提供商
• 基于外部 API 的网页搜索与 RAG

如何启用离线模式？

离线模式需要设置多个环境变量，以尽可能切断 Open WebUI 对外部网络的依赖。核心变量如下：

必需环境变量：

• OFFLINE_MODE=true - 禁用版本检查并阻止自动下载模型
• HF_HUB_OFFLINE=1 - 告知 Hugging Face Hub 以离线模式运行，阻止所有自动下载

可选但推荐：

• RAG_EMBEDDING_MODEL_AUTO_UPDATE=false - 阻止嵌入模型自动更新
• RAG_RERANKING_MODEL_AUTO_UPDATE=false - 阻止重排模型自动更新
• WHISPER_MODEL_AUTO_UPDATE=false - 阻止 Whisper 模型自动更新

请根据你的部署方式应用这些环境变量。

关键说明：HF_HUB_OFFLINE 的行为

当设置 HF_HUB_OFFLINE=1 后：

• 模型、sentence-transformers 及其他 Hugging Face 内容将无法下载
• 若未提前下载模型就启用该项，默认安装下的 RAG 将无法工作
• 仅能访问正确缓存目录中预先下载的模型

该变量提供最严格的离线约束，但也要求提前做好充分准备。

提示

请先评估你是否需要在部署初期就完全离线运行。如果你的场景不要求立即离线，建议采用方案 II，配置更简单。

方案 I

I: Speech-To-Text

本地 whisper 安装默认不包含模型。若你希望使用外部模型/提供商，可部分参考此指南。若要使用本地 whisper，需先下载你选择的模型（例如 Hugging Face - Systran）。

from faster_whisper import WhisperModel

faster_whisper_kwargs = {
    "model_size_or_path": "Systran/faster-whisper-large-v3",
    "device": "cuda", # set this to download the cuda adjusted model
    "compute_type": "int8",
    "download_root": "/path/of/your/choice"
}

WhisperModel(**faster_whisper_kwargs)

下载目录中的内容必须复制到 Open WebUI 部署内的 /app/backend/data/cache/whisper/models/。建议通过环境变量直接声明 whisper 模型，例如：WHISPER_MODEL=Systran/faster-whisper-large-v3。

I: Text-To-Speech

默认本地 transformer 已可满足文本转语音功能。若你偏好其他方案，可参考这些指南。

I: Embedding Model

在多种场景下你都需要嵌入模型（例如 RAG）。你需要先下载所选模型（例如 Hugging Face - sentence-transformers）。

from huggingface_hub import snapshot_download

snapshot_download(repo_id="sentence-transformers/all-MiniLM-L6-v2", cache_dir="/path/of/your/choice")

下载目录中的内容必须复制到 Open WebUI 部署内的 /app/backend/data/cache/embedding/models/。建议通过环境变量直接声明嵌入模型，例如：RAG_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2。

方案 II

在安装阶段保留网络连接运行 Open WebUI

这是最容易实现离线部署的方式，并可保留接近在线版本的大多数功能。请仅启用你部署场景真正需要的功能。

II: Embedding Model

在 Open WebUI 中进入 Admin Settings > Settings > Documents，选择你要使用的嵌入模型（例如 sentence-transformer/all-MiniLM-L6-v2）。选择后点击其右侧下载按钮。

---

安装完所需功能后，根据你的 Open WebUI 部署类型设置环境变量 OFFLINE_MODE=True。

补充说明

如前所述，要实现真正完全离线的 Open WebUI 体验，你还必须将实例与互联网断开。离线模式本身主要用于避免在无网时 Open WebUI 内部出现报错。

如何断开实例网络由你自行决定。下面给出一个 docker-compose 示例：

services:
  # requires a reverse-proxy
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    restart: unless-stopped
    environment:
      # Core offline mode settings
      - OFFLINE_MODE=true
      - HF_HUB_OFFLINE=1
      
      # Disable automatic model updates
      - RAG_EMBEDDING_MODEL_AUTO_UPDATE=false
      - RAG_RERANKING_MODEL_AUTO_UPDATE=false
      - WHISPER_MODEL_AUTO_UPDATE=false
      
      # Specify pre-downloaded models
      - RAG_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
      - WHISPER_MODEL=Systran/faster-whisper-large-v3
    volumes:
      - ./open-webui-data:/app/backend/data
      - ./models/sentence-transformers/all-MiniLM-L6-v2:/app/backend/data/cache/embedding/models/
      - ./models/Systran/faster-whisper-large-v3:/app/backend/data/cache/whisper/models/
    networks:
      - open-webui-internal

networks:
  open-webui-internal:
    name: open-webui-internal-network
    driver: bridge
    internal: true