Open WebUI文档问答功能依赖的嵌入模型选择：离线环境下载与注册配置

Open WebUI 的文档问答功能会把导入文档切片后向量化，之后查询时再用同一套嵌入模型生成向量做相似度匹配。离线环境下，关键是提前把嵌入模型文件准备好，并在启动 Open WebUI 前指定好模型路径和名称。这个流程可以拆成三件事：选一个适合语料的嵌入模型、让模型文件出现在本机磁盘上、把模型注册到 Open WebUI 可用的配置项里。

离线部署时，嵌入模型通常只能靠手动拷贝或内网分发。建议优先选择通用性强的开源模型，例如 sentence-transformers 系列的 all-MiniLM-L6-v2（英文场景）或 BAAI/bge-m3（中英通用）。下载模型尽量在联网环境完成，再通过内网传输到 Open WebUI 所在主机。配置时注意区分 Docker 安装和本机 pip 安装，模型路径必须对运行进程可读，且环境变量名称需要与当前版本对应。

嵌入模型怎么选

模型选择影响检索效果和资源占用。不需要在线 API 时，优先选本地可加载的开源嵌入模型。以下按常见使用场景给出选择方向，具体尺寸和依赖以模型仓库说明为准。

英文文档为主：可考虑 all-MiniLM-L6-v2，模型文件较小，加载快，适合部署在内存紧张的主机上。
中文文档为主或中英混合：优先考虑 BAAI/bge-m3，在中文语义检索上通常比通用英文模型更合适，但模型文件相对更大。
对检索效果有更高要求：尝试 bge-large 或 gte-large 系，但资源占用也会相应提高。是否可用取决于 Open WebUI 的嵌入后端是否兼容。
已有 Ollama 环境：可以选 Ollama 仓库中支持的嵌入模型，例如 nomic-embed-text，直接把模型拉取到本地，再在 Open WebUI 里填写 Ollama 连接地址和模型名。

没有特殊要求时，先用 all-MiniLM-L6-v2 或 bge-m3 跑通，再根据问答效果决定是否更换。

离线环境下载模型文件

离线机器通常无法直接从 Hugging Face 拉取模型。可行做法是在有网的机器上下载完整目录，通过 U 盘、内网共享或 scp 传到目标机器。使用 Python 的 huggingface_hub 下载模型目录，示例命令如下（示意，按实际环境调整）：

# 在有网环境中执行
pip install huggingface_hub
huggingface-cli download BAAI/bge-m3 `--local-dir` bge-m3

如果目标机器没有公网，也可以从另一台已经下载好的机器上压缩后搬移。注意保留模型目录下的所有文件，尤其是 config.json、tokenizer 相关文件，缺少任何一个都可能无法加载。传到目标机器后，建议确认目录大小和文件数量与源端一致，必要时用 sha256 校验。

在 Open WebUI 中注册配置

Open WebUI 的嵌入模型配置有两层：一是让后端程序知道去哪里找模型文件，二是给文档问答功能指定使用哪个模型名。不同安装方式会有细微差别。

Docker 安装：通常通过环境变量传给容器。可以将模型目录挂载到容器内，再设置嵌入模型变量。以 docker-compose 片段为例，变量名和路径以你当前使用的 Open WebUI 版本实际支持为准：

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - ./models:/app/models
    environment:
      EMBEDDING_MODEL_NAME: "BAAI/bge-m3"
      EMBEDDING_MODEL_PATH: "/app/models/bge-m3"

pip 本机安装：可以在启动进程前设置同名环境变量，或者把变量写入 .env 文件。启动后不要立即绕过验证，先在页面上传一个短文档，用问答提问确认返回结果是否正常。如果查询时报模型不存在或路径错误，需要逐项核对模型目录名、环境变量名、是否缺少依赖组件。

如果 Open WebUI 默认接入的是 Ollama 后端，那么嵌入模型需要先导入到 Ollama。本地已有的二进制模型文件可以通过 Modelfile 方式导入，或直接把模型文件放到 Ollama 的模型存储目录并执行 ollama create 命令。该步骤的操作细节较多，需要先确认你选择的模型是否能被 Ollama 识别。

常见问题

模型文件下载后放在哪里？ 放在 Open WebUI 进程可读的本地目录即可。Docker 安装时必须通过卷挂载让容器内路径可见；pip 安装则要让启动进程的用户对该目录有读权限。不要只放在 /root 或 /home 下而不检查权限。

配置后为什么仍然加载失败？ 可能是环境变量名不匹配，也可能是模型文件缺少分词器或配置文件。先用命令行尝试用 sentence-transformers 直接加载模型目录，如果本机也不能加载，问题在模型文件本身，而不是 Open WebUI 配置。

离线部署的核心是把“下载模型”和“接入系统”分成两件独立的事来处理。先在本机用 Python 加载测试，再完成 Open WebUI 的注册配置，能减少很多环境命名的排查弯路。