本文记录一次 Windows 环境下启动 Open WebUI 时遇到的真实问题：服务启动过程中访问 Hugging Face 下载默认 Embedding 模型失败，最终导致 ValueError: No embedding model is loaded。文章会从现象、日志分析、根因定位、临时修复、长期修复和常见扩展问题几个角度完整说明。
一、问题背景
在 Windows 11 环境中，通过 Python / Conda 环境安装并启动 Open WebUI：
open-webui serve
当前环境中 Open WebUI 已安装：
open-webui 0.9.6
启动命令本身可以被识别，说明 Open WebUI 的 CLI 安装没有问题：
open-webui —help
可以看到类似输出：
Usage: open-webui [OPTIONS] COMMAND [ARGS]…
Commands:
main
serve
dev
但是直接执行：
open-webui serve
服务并没有成功启动，而是在启动过程中退出。
二、故障现象
启动日志中首先可以看到 Open WebUI 正常进入初始化阶段：
Loading WEBUI_SECRET_KEY from file, not provided as an environment variable.
Loading WEBUI_SECRET_KEY from C:\\Users\\zh401\\.webui_secret_key
INFO [alembic.runtime.migration] Context impl SQLiteImpl.
INFO [alembic.runtime.migration] Will assume non-transactional DDL.
这说明数据库迁移、密钥读取等基础步骤并不是主要问题。
随后日志出现网络相关错误：
ERROR [open_webui.retrieval.utils] Cannot determine model snapshot path: Got: ConnectError: [WinError 10054]
An error happened while trying to locate the files on the Hub, and we cannot find the appropriate snapshot folder for the specified revision on the local disk.
Please check your internet connection and try again.
进一步可以看到 Hugging Face Hub 请求失败：
'[WinError 10054]' thrown while requesting HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/./modules.json
以及：
'[WinError 10051]' thrown while requesting HEAD https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/adapter_config.json
最终 Open WebUI 抛出致命错误：
ValueError: No embedding model is loaded. Set RAG_EMBEDDING_MODEL to a valid SentenceTransformer model name, or configure an external RAG_EMBEDDING_ENGINE (ollama, openai, azure_openai).
三、核心报错解读
这次问题的关键报错是：
No embedding model is loaded
不要只看最后这一行。它并不是说 Open WebUI 配置文件一定写错了，也不是说 Python 包一定损坏了。
结合前面的日志，完整链路是：
Open WebUI 启动。
初始化 RAG / Retrieval 相关模块。
尝试加载默认 Embedding 模型。
默认模型是：
sentence-transformers/all-MiniLM-L6-v2
本地 Hugging Face 缓存中没有完整模型。
程序尝试访问 Hugging Face 官方站点下载模型。
网络连接失败。
模型无法加载。
Open WebUI 启动失败。
也就是说，真正的根因不是 ValueError 本身，而是前面的 Hugging Face 网络访问失败。
四、根因定位
Open WebUI 默认会使用 SentenceTransformer 模型作为本地 RAG Embedding 模型。常见默认模型之一是：
sentence-transformers/all-MiniLM-L6-v2
启动时，如果本地没有缓存，huggingface_hub 会尝试从：
https://huggingface.co
下载模型文件。
但在某些网络环境下，访问 Hugging Face 可能会失败，例如：
- 网络无法直连 Hugging Face；
- HTTPS 连接被重置；
- 公司 / 校园网络限制；
- 代理未配置；
- DNS 或防火墙导致连接异常；
- 本地没有提前缓存模型。
本次日志中的典型错误包括：
WinError 10054
含义大致是：远程主机强制关闭了一个现有连接。
以及：
WinError 10051
含义大致是：网络不可达或当前网络路径无法建立连接。
所以最终结论是：
Open WebUI 启动失败的根因，是启动阶段需要下载默认 Embedding 模型，但当前环境无法稳定访问 Hugging Face 官方站点，导致模型加载失败。
五、临时解决方案：使用 Hugging Face 镜像
在 Windows PowerShell 中，可以临时设置 HF_ENDPOINT 环境变量，让 Hugging Face Hub 请求走镜像站点。
执行：
$env:HF_ENDPOINT='https://hf-mirror.com'
open-webui serve
设置后，Open WebUI 启动时会从镜像下载模型。
日志中可以看到开始下载模型文件：
Fetching 30 files: 0%| | 0/30 [00:00<?, ?it/s]
Fetching 30 files: 3%| | 1/30 […]
Fetching 30 files: 7%| | 2/30 […]
等待下载完成后，服务可以正常启动。
验证端口：
Get-NetTCPConnection –LocalPort 8080
可以看到端口处于监听状态：
LocalAddress LocalPort State OwningProcess
———— ——— —– ————-
0.0.0.0 8080 Listen 13012
访问页面：
Invoke-WebRequest –Uri "http://127.0.0.1:8080" –UseBasicParsing
返回状态码：
200
页面标题为：
Open WebUI
浏览器访问：
http://127.0.0.1:8080
即可打开 Open WebUI。
六、推荐的长期解决方案
方案 1：永久配置 HF_ENDPOINT
如果你的网络环境长期无法直接访问 Hugging Face，可以把 HF_ENDPOINT 配置为系统环境变量。
当前 PowerShell 会话临时生效
$env:HF_ENDPOINT='https://hf-mirror.com'
open-webui serve
这种方式只对当前 PowerShell 窗口有效，关闭终端后失效。
用户级环境变量长期生效
可以执行：
[Environment]::SetEnvironmentVariable('HF_ENDPOINT', 'https://hf-mirror.com', 'User')
然后重新打开 PowerShell，再启动：
open-webui serve
检查是否生效：
$env:HF_ENDPOINT
应该输出：
https://hf-mirror.com
方案 2：提前下载模型到本地缓存
如果你希望服务启动时不依赖临时网络，可以提前把模型下载到本地 Hugging Face 缓存中。
在网络可用或已配置镜像的情况下执行一次启动，让模型下载完成。之后再启动时，Open WebUI 会优先使用本地缓存。
也可以使用 Python / huggingface-cli 等方式提前下载模型，但对普通用户来说，直接通过 Open WebUI 首次启动自动下载更简单。
方案 3：配置外部 Embedding 引擎
Open WebUI 报错中也提示了另一类解决方案：
configure an external RAG_EMBEDDING_ENGINE (ollama, openai, azure_openai)
也就是说，你可以不使用本地 SentenceTransformer 模型，而是配置外部 Embedding 服务，例如：
- Ollama；
- OpenAI；
- Azure OpenAI。
这种方式适合已经有统一模型服务或不希望本地下载 embedding 模型的场景。
不过如果只是想让 Open WebUI 先跑起来，最简单的方式仍然是配置 HF_ENDPOINT 或提前缓存模型。
七、关于 Windows 上的 symlink 警告
启动过程中还可能看到如下警告：
huggingface_hub cache-system uses symlinks by default to efficiently store duplicated files but your machine does not support them
这不是导致 Open WebUI 启动失败的主要原因。
它的意思是：Hugging Face Hub 默认希望用符号链接优化缓存空间，但当前 Windows 环境不支持或没有权限创建 symlink。
影响是：
- 缓存仍然可用；
- 只是可能占用更多磁盘空间；
- 一般不会导致启动失败。
如果想消除这个警告，可以考虑：
$env:HF_HUB_DISABLE_SYMLINKS_WARNING='1'
如果要永久关闭：
[Environment]::SetEnvironmentVariable('HF_HUB_DISABLE_SYMLINKS_WARNING', '1', 'User')
八、完整排查命令汇总
1. 检查 Open WebUI 是否安装
open-webui —help
或：
python –m pip show open-webui
2. 直接启动
open-webui serve
如果出现 Hugging Face 连接错误，继续下一步。
3. 使用 Hugging Face 镜像启动
$env:HF_ENDPOINT='https://hf-mirror.com'
open-webui serve
4. 检查 8080 端口
Get-NetTCPConnection –LocalPort 8080
5. 检查 Web 服务是否可访问
Invoke-WebRequest –Uri "http://127.0.0.1:8080" –UseBasicParsing
如果返回 HTTP 200，说明服务已经正常启动。
九、最终结论
本次 Open WebUI 启动失败并不是因为 Open WebUI 本身损坏，也不是因为命令写错，而是因为：
Open WebUI 在启动时需要加载默认 Embedding 模型 sentence-transformers/all-MiniLM-L6-v2，但当前环境无法访问 Hugging Face 官方站点，导致模型下载失败，最终触发 No embedding model is loaded。
最直接的修复方式是：
$env:HF_ENDPOINT='https://hf-mirror.com'
open-webui serve
如果希望长期生效，可以设置用户级环境变量：
[Environment]::SetEnvironmentVariable('HF_ENDPOINT', 'https://hf-mirror.com', 'User')
之后重新打开终端，再执行：
open-webui serve
服务启动成功后，浏览器访问：
http://127.0.0.1:8080
即可进入 Open WebUI。
十、附：一键启动脚本示例
如果不想每次手动输入环境变量，可以创建一个 start-openwebui.ps1 文件：
$env:HF_ENDPOINT='https://hf-mirror.com'
$env:HF_HUB_DISABLE_SYMLINKS_WARNING='1'
open-webui serve
以后只需要执行：
.\\start-openwebui.ps1
即可启动 Open WebUI。
如果 PowerShell 提示脚本执行策略限制，可以使用：
powershell –ExecutionPolicy Bypass –File .\\start-openwebui.ps1
总结
遇到 Open WebUI 启动失败时，不要只盯着最后的 ValueError。很多时候，真正的原因藏在前面的下载日志里。
这类问题的排查思路可以概括为：
对于本案例，HF_ENDPOINT=https://hf-mirror.com 是最简单、最快速、最有效的解决方案。
