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

vLLM 集成 Open WebUI基于 Docker 搭建自托管 AI 聊天平台的完整实践【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm本篇指南以 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 负责。整体部署拓扑为宿主机上运行 vLLM 服务监听某个 IP:Port例如0.0.0.0:8000Docker 中运行 Open WebUI 容器容器内部端口为8080映射到宿主机的3000端口通过环境变量OPENAI_API_BASE_URL告诉 Open WebUI 后端 API 的地址http://0.0.0.0:8000/v1用户在浏览器访问 Open WebUI即可选择模型进行对话。二、前置准备安装 Docker官方流程的第一步是安装 DockerDocker 引擎的标准安装方式。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」并支持--helpConfigGroup按分组查看参数如--helpModelConfig、--helpall这对排查参数非常实用。--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_URLhttp://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_URLhttp://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 官方镜像几个容易踩坑的点OPENAI_API_BASE_URL中的 host 必须是 vLLM 可被容器访问到的地址。在「vLLM 与容器同宿主机」的常见拓扑下0.0.0.0:8000可指向宿主机监听地址文档即采用此写法若 vLLM 部署在另一台机器则替换为对应 IP。端口必须两端一致vLLM 侧--port 8000与环境变量中的:8000一致容器侧8080与映射3000:8080一致浏览器访问的则是3000。三处对应关系不要混淆。若 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 兼容 APIOpen WebUI 容器经OPENAI_API_BASE_URLhttp://0.0.0.0:8000/v1对接浏览器访问http://open-webui-host:3000/。源码依据serve子命令参数默认值见 cli_args.py服务启动分发逻辑见 serve.py。可扩展方向使用--helpall查看全部 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 启动入口。【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考