跳到主要内容

在离线模式下运行 Open WebUI 🔌

注意

本教程为社区贡献，Open WebUI 团队不提供官方支持。它仅作为如何针对特定用例自定义 Open WebUI 的演示。想要贡献？请查看 贡献教程。

如果您想在离线模式下运行 Open WebUI，您必须考虑您的安装方法并相应地调整您所需的功能。在本指南中，我们将介绍实现与在线版本基本相似设置的不同方法。

什么是离线模式？​

Open WebUI 的离线模式允许您在不需要活动互联网连接的情况下运行应用程序。这使您能够为您的 LLM 和工具创建一个“物理隔离（air-gapped）”环境（一个完全“物理隔离”的环境需要将实例与互联网彻底隔离）。

信息

启用离线模式时禁用的功能：

  • 自动版本更新检查（由 ENABLE_VERSION_UPDATE_CHECK 控制）
  • 从 Hugging Face Hub 下载 Embedding 模型（由 HF_HUB_OFFLINE 控制）
    • 如果在激活离线模式之前没有下载 Embedding 模型，RAG、网页搜索和文档分析功能将无法正常工作
  • Embedding、Reranking 重排序模型和 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 - 防止 Embedding 模型自动更新
  • RAG_RERANKING_MODEL_AUTO_UPDATE=false - 防止 Reranking 重排序模型自动更新
  • 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 应用程序，您必须首先下载您选择的模型（例如：Huggingface - Systran）。

from faster_whisper import WhisperModel

faster_whisper_kwargs = {
    "model_size_or_path": "Systran/faster-whisper-large-v3",
    "device": "cuda", # 设置此项以下载适配 cuda 的模型
    "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 已经可以处理 Text-To-Speech 功能。如果您更倾向于其他方法，请参考 相关指南。

I：Embedding Model 向量模型​

出于各种目的，您需要一个 Embedding 模型（例如 RAG）。您需要首先下载一个您选择的此类模型（例如 Huggingface - 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/。直接通过 环境变量 声明您的 Embedding 模型是合理的，例如：RAG_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2。

方案 II​

在设置期间连接互联网运行 Open WebUI​

这是实现离线设置最简单的方法，几乎可以使用在线版本中的所有功能。只需应用您在部署中想要使用的功能即可。

II：Embedding Model 向量模型​

在您的 Open WebUI 安装中，导航至 Admin Settings > Settings > Documents（管理员设置 > 设置 > 文档）并选择您想要使用的 Embedding 模型（例如 sentence-transformer/all-MiniLM-L6-v2）。选择完毕后，点击其旁边的下载按钮。

在您安装了所有您期望的功能后，根据您的 Open WebUI 部署类型设置环境变量 OFFLINE_MODE=True。

补充说明​

如前所述，要在 Open WebUI 中实现完全的离线体验，您必须断开您的实例与互联网的连接。离线模式只是在没有互联网连接时防止 Open WebUI 内部发生错误。

如何断开您的实例连接由您决定。以下是一个通过 docker-compose 实现的示例：

services:
  # 需要一个反向代理（reverse-proxy）
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    restart: unless-stopped
    environment:
      # 核心离线模式设置
      - OFFLINE_MODE=true
      - HF_HUB_OFFLINE=1
      
      # 禁用自动模型更新
      - RAG_EMBEDDING_MODEL_AUTO_UPDATE=false
      - RAG_RERANKING_MODEL_AUTO_UPDATE=false
      - WHISPER_MODEL_AUTO_UPDATE=false
      
      # 指定预下载的模型
      - 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
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.