vLLM 集成 Open WebUI：基于 Docker 搭建自托管 AI 聊天平台的完整实践

本篇指南以 vLLM 官方文档 Open WebUI 部署文档 为主体，完整还原「vLLM 推理服务 + Open WebUI 前端」的自托管 AI 平台搭建流程，并结合 vLLM 源码中的 CLI 参数定义与服务启动链路，说明每一步配置背后的原理与可选项。读完本文，你将能够：使用 vllm serve 启动一个 OpenAI 兼容的推理服务，通过 Docker 一键拉起 Open WebUI 并正确对接后端 API，以及在页面上直接看到并调用所部署的模型。

一、方案概述：vLLM 作为 Open WebUI 的 LLM 后端

Open WebUI 是一个可扩展、功能丰富且用户友好的自托管 AI 平台，设计上可以完全离线运行。它支持多种 LLM 运行器，例如 Ollama 和任何 OpenAI 兼容 API，并内置 RAG 能力，因此是一个强大的 AI 部署方案。

vLLM 恰好就是典型的 OpenAI 兼容 API 提供方：vllm serve 子命令会启动一个本地 OpenAI 兼容的 HTTP API 服务（该描述可直接在 serve 子命令的说明 中看到）。Open WebUI 无需感知 vLLM 的 PagedAttention、连续批处理等内部细节，只通过标准 /v1 接口与之交互，两者以「前端 UI ↔ OpenAI 兼容后端」的方式解耦，这也是该部署模式最核心的价值——前端体验由 Open WebUI 提供，推理吞吐由 vLLM 负责。

整体部署拓扑为：

1. 宿主机上运行 vLLM 服务，监听某个 IP:Port（例如 0.0.0.0:8000）；
2. Docker 中运行 Open WebUI 容器，容器内部端口为 8080，映射到宿主机的 3000 端口；
3. 通过环境变量 OPENAI_API_BASE_URL 告诉 Open WebUI 后端 API 的地址（http://0.0.0.0:8000/v1）；
4. 用户在浏览器访问 Open WebUI，即可选择模型进行对话。

二、前置准备：安装 Docker

官方流程的第一步是安装 Docker（Docker 引擎的标准安装方式）。Open WebUI 以容器方式运行，因此宿主机必须装有可用的 Docker 引擎；而 vLLM 服务本身推荐直接以 Python 进程方式跑在宿主机上，这样便于排查 GPU 显存、CUDA 相关问题。

三、启动 vLLM 服务：vllm serve 与 --host/--port 的含义

按照 部署文档 的步骤 2，用一个支持聊天补全的模型启动 vLLM 服务：

vllm serve Qwen/Qwen3-0.6B-Chat

文档中特别强调（note 提示）：启动 vLLM 服务时，务必使用 --host 和 --port 标志指定监听地址和端口，例如：

vllm serve <model> --host 0.0.0.0 --port 8000

这两行命令在源码层面有明确的对应关系：

• serve 子命令由 ServeSubcommand 实现。它的描述文本还说明了「不指定模型时默认为 Qwen/Qwen3-0.6B」，并支持 --help=<ConfigGroup> 按分组查看参数（如 --help=ModelConfig、--help=all），这对排查参数非常实用。
• --host 与 --port 的默认值定义在 FrontendArgs 中：port: int = 8000，即默认端口就是 8000，与文档示例一致；host 字段本身默认为 None。由于 Open WebUI 跑在另一个 Docker 容器中、必须跨进程网络访问 vLLM，显式指定 --host 0.0.0.0 才能监听所有网卡（默认仅本地回环地址可访问时，容器将无法连通）；--port 8000 则与后续环境变量中的地址保持一致。
• 从 serve 的启动链路 可以看出，单 API server 场景（本教程场景）最终走 uvloop.run(run_server(args))，由 entry 模块 完成服务装配，并对外暴露标准 OpenAI 路由（/v1/chat/completions、/v1/models 等），这正是 Open WebUI 能够直接对接的原因。

实践建议：模型名称请替换为你实际拥有权重、且支持聊天补全的模型；Qwen/Qwen3-0.6B-Chat 是文档选定的轻量示例，便于在普通硬件上快速验证链路。

四、启动 Open WebUI 容器：逐项解读 docker run 参数

文档步骤 3 给出了完整的启动命令，这里完整保留并对每个参数做说明：

docker run -d \
    --name open-webui \
    -p 3000:8080 \
    -v open-webui:/app/backend/data \
    -e OPENAI_API_BASE_URL=http://0.0.0.0:8000/v1 \
    --restart always \
    ghcr.io/open-webui/open-webui:main

参数	作用	说明
-d	后台运行容器	终端不会被占用
--name open-webui	容器命名	便于后续 docker stop/logs open-webui 管理
-p 3000:8080	端口映射	容器内 Open WebUI 监听 8080，对外暴露宿主机的 3000
-v open-webui:/app/backend/data	命名卷持久化	用户账号、聊天历史、上传文档等数据保存在 Docker volume 中，容器重建不丢失
-e OPENAI_API_BASE_URL=http://0.0.0.0:8000/v1	指向 vLLM 后端	Open WebUI 以此地址作为 OpenAI 兼容 API base URL，/v1 后缀对应 vLLM 的 OpenAI 路由前缀
--restart always	自动重启策略	宿主机重启后容器自动拉起，适合长期自托管
ghcr.io/open-webui/open-webui:main	镜像	Open WebUI 官方镜像

几个容易踩坑的点：

1. OPENAI_API_BASE_URL 中的 host 必须是 vLLM 可被容器访问到的地址。在「vLLM 与容器同宿主机」的常见拓扑下，0.0.0.0:8000 可指向宿主机监听地址（文档即采用此写法）；若 vLLM 部署在另一台机器，则替换为对应 IP。
2. 端口必须两端一致：vLLM 侧 --port 8000 与环境变量中的 :8000 一致，容器侧 8080 与映射 3000:8080 一致，浏览器访问的则是 3000。三处对应关系不要混淆。
3. 若 vLLM 服务启用了 API key（--api-key），需要在 Open WebUI 中填入对应 key；默认本地部署不启用 key 时则无需额外配置。

五、验证结果：在浏览器中看到模型

按文档步骤 4，在浏览器打开：

http://open-webui-host:3000/

页面顶部的模型选择器中应当看到 Qwen/Qwen3-0.6B-Chat，选中后即可开始对话。这是判断「vLLM ↔ Open WebUI 链路」完全打通的最直接信号——模型名能被列出，说明 Open WebUI 成功调用了 vLLM 的模型列表接口。

Open WebUI 部署成功后的页面效果（来源：官方部署文档配图）：

若模型未出现，可沿以下链路排查：vLLM 是否完成模型加载（服务日志中需出现 listening 信息）→ 容器内能否访问 http://0.0.0.0:8000/v1 → docker logs open-webui 中是否有连接后端的报错。

六、小结与扩展方向

• 链路核心：vllm serve <model> --host 0.0.0.0 --port 8000 提供 OpenAI 兼容 API；Open WebUI 容器经 OPENAI_API_BASE_URL=http://0.0.0.0:8000/v1 对接；浏览器访问 http://open-webui-host:3000/。
• 源码依据：serve 子命令参数默认值见 cli_args.py，服务启动分发逻辑见 serve.py。
• 可扩展方向：
  • 使用 --help=all 查看全部 serve 参数，例如通过 --max-model-len、--tensor-parallel-size 等按实际模型与 GPU 资源调整（具体取值以 vllm serve --help 输出为准）；
  • 更换为更大的聊天模型或多模态模型时，只需替换 vllm serve 后的模型名，Open WebUI 侧无需改动；
  • 其他前端框架（如 OpenAI UI、LobeChat 等）的部署方式，可参考仓库 deployment/frameworks 目录下的其他文档；
  • 若需要更完整的在线服务参数说明，可继续阅读 在线服务指南。

参考文件：open-webui 部署文档、serve 子命令实现、前端参数定义、API server 启动入口。