Open WebUI 如何使用 :cuda 镜像与 --gpus all 启动以启用 NVIDIA GPU 支持-平芜编程栈

Open WebUI 如何使用 :cuda 镜像与 --gpus all 启动以启用 NVIDIA GPU 支持

【免费下载链接】open-webuiUser-friendly AI Interface (Supports Ollama, OpenAI API, ...)项目地址: https://gitcode.com/GitHub_Trending/op/open-webui

如果你的目标是让 Open WebUI 在 NVIDIA GPU 机器上获得 CUDA 加速，官方给出的部署方式是：拉取带:cuda标签的镜像，并在docker run命令中加上--gpus all参数。这条路径的前提是宿主机为 Linux 或 WSL 系统，且已安装 Nvidia CUDA container toolkit（NVIDIA 容器运行时组件），这一点在 README.md 的 Docker 快速开始章节中有明确说明。完成启动后，Open WebUI 会运行在http://localhost:3000。

准备条件

在执行 GPU 版命令前，确认以下几点，它们都来自 README.md 的 Docker 安装说明：

宿主机为Linux 或 WSL系统。要启用 CUDA，必须在宿主机上安装Nvidia CUDA container toolkit，这是 README 中列出的硬性前提。
系统已安装 NVIDIA GPU 与对应驱动，Docker 可用。
无论使用哪个镜像标签，Docker 命令中都必须包含-v open-webui:/app/backend/data。README 以 WARNING 的形式强调：这个挂载用于持久化数据库，缺少它会导致数据丢失。

另外，从 Dockerfile 可以看到，官方:cuda镜像是通过USE_CUDA=true构建参数生成的，默认使用USE_CUDA_VER=cu128（注释说明 cu117 对应 CUDA 11、cu121 对应 CUDA 12 均为已测试版本）。USE_CUDA为 true 时，镜像内会安装对应 CUDA 版本的 torch，并且 whisper 与 embedding 模型会在首次使用时下载，所以第一次触发语音或 RAG 相关功能时会有下载动作。

使用 :cuda 镜像启动容器

README 中给出的 GPU 版启动命令如下，可直接复制执行：

docker run -d -p 3000:8080 --gpus all --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:cuda

各参数的用途：

参数	说明
`:cuda`	镜像标签，即启用 CUDA 加速的官方镜像
`--gpus all`	将宿主机上所有 GPU 暴露给容器，这是启用 GPU 的关键参数
`-p 3000:8080`	容器内服务端口为 8080，映射到宿主机 3000
`--add-host=host.docker.internal:host-gateway`	让容器能通过`host.docker.internal`访问宿主机服务（例如本地 Ollama）
`-v open-webui:/app/backend/data`	数据卷挂载，持久化数据库，README 明确要求必须保留
`--name open-webui --restart always`	容器命名与开机自启

这条命令与 README 中默认配置命令的区别只有两处：镜像标签从:main换成:cuda，并追加了--gpus all。如果你只使用 OpenAI API 而不需要 CUDA，不需要切换到:cuda标签。

可选分支：使用 :ollama 镜像并启用 GPU

如果你希望在同一个容器里同时运行 Open WebUI 和内嵌的 Ollama（而不是连接外部 Ollama），README 提供的是:ollama镜像加--gpus=all的组合：

docker run -d -p 3000:8080 --gpus=all -v ollama:/root/.ollama -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:ollama

该变体额外挂载了ollama:/root/.ollama数据卷用于持久化 Ollama 的模型数据；不使用 GPU 时则去掉--gpus=all。两条路径不要混用：要么用:cuda连接外部 Ollama/OpenAI 端点，要么用:ollama依赖内嵌推理。

验证启动结果

启动完成后，按以下顺序核对：

访问入口：浏览器打开http://localhost:3000，应能看到 Open WebUI 页面。
健康检查：后端提供/health端点（见 backend/open_webui/main.py），返回{'status': true}。宿主机上可以用curl http://localhost:3000/health请求该路径。
确认 CUDA 已被镜像启用：容器入口脚本 backend/start.sh 在检测到USE_CUDA_DOCKER=true（:cuda镜像构建时即为此值）时会向日志输出CUDA enabled — extending LD_LIBRARY_PATH for torch/cudnn libraries.，并将 torch 与 cuDNN 的库路径加入LD_LIBRARY_PATH。执行docker logs open-webui可以看到这一行，说明镜像内的 CUDA 分支确实生效。

排查与限制

Ollama 连接失败：如果 WebUI 容器无法访问本机 Ollama（容器内对应127.0.0.1:11434/host.docker.internal:11434），README 的 Troubleshooting 部分给出的解法是改用--network=host网络模式，此时端口映射不再需要，直接访问http://localhost:8080：
```
docker run -d --network=host -v open-webui:/app/backend/data -e OLLAMA_BASE_URL=http://127.0.0.1:11434 --name open-webui --restart always ghcr.io/open-webui/open-webui:main
```
该示例使用的是:main标签，README 未展示:cuda与--network=host组合的完整命令；需要 GPU 时可在该命令基础上自行替换标签并加--gpus all，但请以实际环境验证为准。
CUDA toolkit 缺失：宿主机没有安装 Nvidia CUDA container toolkit 时，--gpus all无法把 GPU 暴露给容器，这是 README 明确列出的前置条件，遇到 GPU 不可用问题应先检查这一项。
首次使用下载模型：如前所述，:cuda镜像的 whisper 与 embedding 模型是首次使用时才下载，离线环境可参考 README 的 Offline Mode 说明设置HF_HUB_OFFLINE=1。