vLLM Docker：架构、性能与云端部署指南

vLLM Docker：架构、性能与云端部署指南

Docker 是在您可控的 GPU 上，通过兼容 OpenAI 的端点部署 vLLM 的最直接方式。不过，良好的 vLLM Docker 部署不仅仅是一条 docker run 命令：它需要兼容的 GPU 运行时、受控的内存与并发计划、边缘认证，以及在流量到来前可重复执行的性能测试方法。

本指南将介绍其架构、安全的首次部署、真正影响容量的调优项，以及从单个 GPU 扩展到云端 GPU 集群的路径。

适合使用 vLLM Docker 的场景：您需要控制模型权重、部署位置、运行时设置，或需要承载稳定的自托管工作负载。如果运维成本超过了这种控制带来的价值，托管模型 API 或统一网关通常是更合适的边界。

vLLM Docker 为您提供什么

vLLM 发布了官方 vllm/vllm-openai Docker 镜像，可启动兼容 OpenAI 的服务器。这使得 vLLM Docker 成为模型仓库与已采用 OpenAI 客户端接口形式的应用之间的实用桥梁：模型列表、聊天补全、补全、嵌入及相关兼容端点取决于您部署的模型和服务器版本。vLLM 的 Docker 文档提供了当前镜像和运行时示例。

实际含义很简单：仅仅因为将工作负载迁移到自己的 GPU，您的应用不应就需要专门的模型服务器客户端。但它仍然需要显式指定模型名称、API 密钥、超时时间，以及符合您自身可用性目标的重试行为。

vLLM Docker 架构如何工作

从高层来看，vLLM Docker 包含五个层级：

1. 您的客户端向兼容 OpenAI 的端点发送经认证的请求。
2. API 服务器验证并分词请求，然后将其交给 vLLM 引擎。
3. 调度器对兼容的工作进行批处理，并将其分派给一个或多个 GPU 工作进程。
4. GPU 工作进程在生成令牌时持有模型权重和键值（KV）缓存。
5. 响应通过 API 服务器流式返回给客户端。

核心的性能理念是 PagedAttention。vLLM 不会为请求可能达到的最大长度预留一大片连续的 KV 缓存区域，而是以块的形式管理 KV 状态。这使得可变长度工作负载更容易装入可用内存，并让已完成的请求释放块以供后续工作使用。原始的 PagedAttention 论文描述了调度器、GPU 工作进程、逻辑到物理 KV 块，以及缓存利用率与批处理之间的权衡。

该架构有一个重要的运维影响：显存不仅仅是“模型大小”。它由模型权重、运行时开销、激活值和 KV 缓存共同占用，而 KV 缓存的需求会随上下文长度和并发请求数增长。应将上下文、并发性和内存利用率视为一个决策，而不是三项彼此独立的调优任务。

在云端 GPU 上运行 vLLM Docker 之前

首先进行四项检查：

1. 选择经过测试的镜像标签。在生产环境中固定 vLLM 发布标签，而不是盲目跟随 latest。在依赖某个标志或默认值前，请阅读与该标签匹配的文档。
2. 使用您获准下载和提供服务的模型。某些仓库需要 Hugging Face 令牌或接受模型许可证。在验证模型后固定其修订版本。
3. 在模型容器之外验证 GPU 访问。安装主机 NVIDIA 驱动程序和 NVIDIA Container Toolkit，然后使用 nvidia-smi 验证启用 GPU 的容器。NVIDIA 的安装指南介绍了主机端前置条件和运行时配置。
4. 起初应保持端口私有。对于单主机概念验证，请绑定到回环地址；或者将服务置于私有子网中，并在 TLS、认证和反向代理/负载均衡器之后运行。不要将裸露的模型服务器视为面向互联网的安全边界。

在调试 vLLM 本身之前，先使用 NVIDIA 的示例命令：

docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

如果该命令无法看到预期的 GPU，请先停在那里。模型服务器日志无法修复缺失的驱动程序、未配置的容器运行时，或从未分配给云端 VM 的 GPU。

运行单 GPU vLLM Docker 服务器

以下是一个刻意保持精简的起点。它遵循官方镜像模式，但添加了 API 密钥，并将发布端口绑定到回环地址。请将占位符替换为您已测试过的模型和镜像标签。

export HF_TOKEN="your_hugging_face_token"
export VLLM_API_KEY="replace-with-a-long-random-secret"
export VLLM_IMAGE="vllm/vllm-openai:<tested-version>"
export MODEL="Qwen/Qwen3-0.6B"

docker run -d \
  --name vllm-api \
  --restart unless-stopped \
  --runtime=nvidia \
  --gpus all \
  --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN \
  -e VLLM_API_KEY \
  "$VLLM_IMAGE" \
  --model "$MODEL" \
  --dtype auto \
  --api-key "$VLLM_API_KEY"

共享内存设置和 Hugging Face 缓存挂载遵循官方 vLLM Docker 示例。缓存挂载可避免在重新创建容器时再次下载相同的模型权重。API 密钥是一种应用层控制措施，不能替代网络隔离、TLS、速率限制或密钥管理器。

在连接应用程序之前，请验证服务器是否正在提供预期的模型：

curl --fail --silent --show-error \
  http://127.0.0.1:8000/v1/models \
  -H "Authorization: Bearer $VLLM_API_KEY"

然后使用 /v1/models 返回的相同模型标识符发送一个小型请求：

curl --fail --silent --show-error \
  http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer $VLLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-0.6B",
    "messages": [{"role": "user", "content": "Reply with the word ready."}],
    "max_tokens": 16
  }'

如果您的模型不包含可用的聊天模板，即使容器已经启动，聊天补全请求也可能失败。vLLM 说明了如何为 tokenizer 配置缺少聊天模板的模型提供 --chat-template；请在应用程序上线前对此进行测试。请参阅聊天模板指南。

更改标志前先确定性能边界

不存在普遍正确的 vLLM Docker 命令。正确的配置取决于模型架构、GPU 类型和内存、输入/输出长度分布、并发量以及延迟目标。请使用具有代表性的工作负载建立基线，然后每次只更改一个变量。

至少应采集以下指标：

• 请求成功率/错误率，以及重启和 OOM 事件。
• 首个 token 时间（TTFT）和每输出 token 时间（TPOT），并按提示词长度分段。
• 在预期并发量下的 p50 和 p95/p99 端到端延迟。
• 输入 token、输出 token、排队时间、活跃请求数和 GPU 内存使用量。
• 吞吐量只能结合其所满足的延迟和质量目标来评估。

会实质影响容量的 vLLM Docker 标志

确切的选项默认值和行为会随版本而变化。vLLM 当前的引擎参数参考定义了调度器、缓存、并行和队列控制；其缓存配置参考说明了内存利用率和前缀缓存设置。

实用的调优顺序

1. 根据应用限制设置合理的 --max-model-len。
2. 从保守的内存利用率开始，并为驱动程序/运行时开销预留空间。
3. 使用真实的提示词和补全长度，对 --max-num-seqs 和 --max-num-batched-tokens 进行负载测试。
4. 仅当单个 GPU 无法容纳模型或无法满足模型目标时，才添加张量并行。
5. 当可用性或总体流量需求要求独立故障域时，在负载均衡器后添加副本。

这一顺序可避免一个常见错误：在尚未确定工作负载实际受上下文、队列、内存还是计算限制之前，就增加 GPU 或提高并发度。

跨多个 GPU 扩展 vLLM Docker

对于需要多个 GPU 的单个模型，vLLM 支持张量并行和流水线并行服务。在单台主机上，将 GPU 暴露给容器，并将张量并行大小设置为你有意分配给该模型服务器的 GPU 数量：

docker run -d \
  --name vllm-tp \
  --restart unless-stopped \
  --runtime=nvidia \
  --gpus all \
  --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN \
  -e VLLM_API_KEY \
  "$VLLM_IMAGE" \
  --model "$MODEL" \
  --tensor-parallel-size 4 \
  --api-key "$VLLM_API_KEY"

vLLM 的并行化与扩展指南介绍了张量并行、流水线并行，以及单节点与多节点执行的选择。不要将示例中的 4 原样复制到双 GPU 节点：应使该参数与分配给此服务器的 GPU 相匹配，并验证通信拓扑、内存均衡和故障行为。

有关实现细节、拓扑检查，以及如何在张量并行和流水线并行之间做出决策，请参阅 Flatkey 的vLLM 多 GPU 推理指南。若需要的是服务运行时决策而非 Docker 部署决策，请参阅vLLM 与 SGLang 对比。

生产环境云部署架构

生产环境中的 vLLM Docker 部署通常会将公共边缘与 GPU 执行分离：

将 Hugging Face 缓存放在持久存储或经过有意预热的存储上，以免一次普通重启意外触发模型下载。在部署记录中保留模型的许可证和访问控制信息。如果模型仓库指向会持续变动的分支，仅固定镜像标签是不够的。

有关 GPU 选择、由上下文驱动的内存规划，以及何时应采用云基础设施的背景信息，请将此运行手册链接到 Flatkey 的LLM GPU 内存需求指南、GPU 云指南和GPU 云与模型 API 框架对比。

无需猜测地排查 vLLM Docker 故障

当服务器已运行但应用行为仍与托管 API 不同时，请明确确认端点和参数兼容性。Flatkey 的OpenAI 兼容推理服务器指南涵盖了客户端迁移和兼容性测试范围。

何时不应自行运维 vLLM Docker

自托管是一项基础设施承诺。您需要负责镜像更新、模型来源、GPU 容量、节点故障、访问控制、延迟验证以及值班响应流程。当运行时控制是核心要求时，这可能是正确的权衡。

对于模型选择、提供商可用性或运维简便性比直接控制 GPU 更重要的工作负载，请在架构中保留托管 API 路径。Flatkey 专为互补工作流而设计：通过单一 OpenAI 兼容集成访问跨提供商的模型，并实现集中计费；同时，对于确实需要的工作负载，自托管 vLLM 端点仍然是一种选择。

正确的下一步并不是孤立地最大化某项基准测试。在将 vLLM Docker 置于生产流量之后前，请固定镜像和模型版本，验证 GPU 运行时，设定明确的上下文和队列策略，使用符合生产特征的请求进行测试，并记录故障处理路径。

常见问题

vLLM Docker 与托管 LLM API 相同吗？

不相同。vLLM Docker 为您自行运维的 GPU 提供模型服务运行时。托管 API 则抽象了模型托管和 GPU 运维。两者都可以公开 OpenAI 兼容的客户端接口，但运维责任不同。

vLLM Docker 是否需要 NVIDIA Container Toolkit？

对于 NVIDIA GPU 容器，主机需要兼容的 NVIDIA 驱动程序和已配置的 GPU 容器运行时。NVIDIA Container Toolkit 是 NVIDIA 所记录的、用于让 Docker 容器能够使用 GPU 的标准方案。

我应首先调整哪个 vLLM Docker 标志？

首先设置现实可行的最大上下文长度，然后使用具有代表性的请求组合测试内存利用率、并发度和批处理令牌限制。在没有工作负载基准的情况下更改标志，通常只会产生不可复现的结果。

vLLM Docker 能否让一个模型跨多张 GPU 运行？

可以。vLLM 支持张量并行和流水线并行服务。请先从单台主机开始，并在扩展设计之前验证确切的 GPU 数量、拓扑结构和通信行为。

来源与延伸阅读

• vLLM：使用 Docker
• vLLM：并行化与扩展
• vLLM：引擎参数
• NVIDIA Container Toolkit 安装指南
• 使用 PagedAttention 实现大语言模型服务的高效内存管理