vllm-deploy-docker

vLLM Docker 部署

一项 Claude 技能，介绍如何使用官方预构建镜像或从源代码构建镜像，通过 Docker 部署 vLLM，并支持配备 CUDA 的 NVIDIA GPU。说明包括 NVIDIA CUDA 支持、docker run 示例、精简的 docker-compose 片段、推荐标志以及故障排查说明。对于 AMD、Intel 或其他加速器，请参阅 vLLM 文档，了解其他部署方法。

此技能的功能

• 使用预构建镜像（推荐大多数用户采用）部署 vLLM，或从源代码构建以支持自定义配置
• 提供示例命令，用于运行可兼容 OpenAI 的服务、访问 GPU 并挂载 Hugging Face 缓存
• 在需要自定义镜像或可选依赖项时，指向从源代码构建的说明
• 说明常见标志：--ipc=host、共享缓存挂载以及 HF_TOKEN 的处理方式

前提条件

• 已安装 Docker Engine（推荐使用 Docker 20.10+）
• 已安装适当驱动程序和 CUDA 工具包的 NVIDIA GPU
• 可选：用于 API 测试的 curl
• 如果要拉取私有模型或避免速率限制，需要 Hugging Face 令牌：HF_TOKEN

使用预构建镜像快速开始（推荐）

运行可兼容 OpenAI 的 vLLM 服务，启用 GPU 访问、挂载 HF 缓存并转发端口 8000：

docker run --rm --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  --env "HF_TOKEN=$HF_TOKEN" \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen2.5-1.5B-Instruct

• --gpus all 会将所有 GPU 暴露给容器。如需指定 GPU，请相应调整。
• 建议使用 --ipc=host 或足够大的 --shm-size，以便 PyTorch 和 vLLM 共享主机共享内存。
• 挂载 ~/.cache/huggingface 可避免在容器内重复下载模型。

注意： vLLM 和此技能建议使用最新的 Docker 镜像（vllm/vllm-openai:latest）。对于旧版镜像，请参阅 Docker Hub 镜像标签。

从源代码构建 Docker 镜像

你可以使用提供的 docker/Dockerfile 从源代码构建并运行 vLLM。 首先，检查主机的硬件，并确保已安装必要的依赖项（例如 NVIDIA 驱动程序、CUDA 工具包以及支持 BuildKit 的 Docker）。对于 ARM64/aarch64 构建，请参阅“为 ARM64/aarch64 构建”部分。

基本构建命令

DOCKER_BUILDKIT=1 docker build . \
  --target vllm-openai \
  --tag vllm/vllm-openai \
  --file docker/Dockerfile

--target vllm-openai 指定要构建的是可兼容 OpenAI 的服务镜像。DOCKER_BUILDKIT=1 环境变量会启用 BuildKit，从而提供更好的缓存效果并加快构建速度。

构建参数和选项

• --build-arg max_jobs=<N> — 设置构建 CUDA 内核时的并行编译任务数。在多核系统上可用于加快构建速度。
• --build-arg nvcc_threads=<N> — 控制 CUDA 编译器线程数。建议设置为小于 max_jobs 的值，以避免过度占用内存。
• --build-arg torch_cuda_arch_list="" — 如果设为空字符串，vLLM 将检测当前 GPU 的计算能力并仅针对该能力进行构建。默认情况下，vLLM 会针对所有 GPU 类型构建，以便更广泛地分发。

使用预编译 wheel 加快构建

如果你没有修改任何 C++ 或 CUDA 内核代码，可以使用预编译 wheel，大幅缩短 Docker 构建时间：

• 启用预编译 wheel： 在构建命令中添加 --build-arg VLLM_USE_PRECOMPILED="1"。
• 工作原理： 默认情况下，vLLM 会使用与上游 main 分支的合并基点提交，从 Nightly Builds 自动查找正确的预编译 wheel。
• 指定提交： 若要使用特定提交的 wheel，请添加 --build-arg VLLM_PRECOMPILED_WHEEL_COMMIT=<commit_hash>。

使用预编译 wheel 并启用快速编译选项的示例：

DOCKER_BUILDKIT=1 docker build . \
  --target vllm-openai \
  --tag vllm/vllm-openai \
  --file docker/Dockerfile \
  --build-arg max_jobs=8 \
  --build-arg nvcc_threads=2 \
  --build-arg VLLM_USE_PRECOMPILED="1"

使用可选依赖进行构建（可选）

为避免许可问题，vLLM 的预构建镜像不包含可选依赖（例如音频处理依赖）。如果需要可选依赖，请创建一个扩展基础镜像的自定义 Dockerfile：

示例：添加音频可选依赖

# NOTE: MAKE SURE the version of vLLM matches the base image!
FROM vllm/vllm-openai:0.11.0

# Install audio optional dependencies
RUN uv pip install --system vllm[audio]==0.11.0

示例：使用 transformers 的开发版本：

FROM vllm/vllm-openai:latest

# Install development version of Transformers from source
RUN uv pip install --system git+https://github.com/huggingface/transformers.git

使用以下命令构建此自定义 Dockerfile：

docker build -t my-vllm-custom:latest -f Dockerfile .

然后像使用其他 vLLM 镜像一样使用它：

docker run --rm --gpus all \
  -p 8000:8000 \
  --ipc=host \
  my-vllm-custom:latest \
  --model Qwen/Qwen2.5-1.5B-Instruct

为 ARM64/aarch64 构建

可以为 ARM64 系统（例如 NVIDIA Grace-Hopper 和 Grace-Blackwell）构建 Docker 容器。使用标志 --platform "linux/arm64"：

DOCKER_BUILDKIT=1 docker build . \
  --target vllm-openai \
  --tag vllm/vllm-openai \
  --file docker/Dockerfile \
  --platform "linux/arm64"

注意： 需要编译多个模块，因此此过程可能耗时更长。使用 --build-arg max_jobs=8 --build-arg nvcc_threads=2 等构建参数可加快此过程（请确保 max_jobs 明显大于 nvcc_threads）。请监控内存使用情况，因为并行作业可能需要大量 RAM。

交叉编译（在 x86_64 主机上构建 ARM64）时，请先注册 QEMU user-static 处理程序：

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

然后在构建命令中使用 --platform "linux/arm64" 标志。

运行自定义构建的镜像

构建完成后，像运行预构建镜像一样运行你的镜像：

docker run --rm --runtime nvidia --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  --env "HF_TOKEN=$HF_TOKEN" \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai \
  --model Qwen/Qwen2.5-1.5B-Instruct

将 vllm/vllm-openai 替换为你在构建时指定的标签（例如 my-vllm-custom:latest）。

注意： --runtime nvidia 在大多数环境中已弃用。建议使用 NVIDIA Container Toolkit 提供的 --gpus ...。仅在旧版 Docker 配置中使用 --runtime nvidia。

常用服务端标志

• --model <MODEL_ID> — 要加载的模型（HF ID 或本地路径）
• --port <PORT> — 服务端端口（OpenAI 兼容服务端的默认值为 8000）
• --log-level — 调整详细程度
• 你可以在镜像标签后传递其他 engine_args；请参阅 vLLM 文档了解调优选项。

测试 API

容器启动后，向 OpenAI 兼容端点发送一个快速测试请求：

curl -s http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen2.5-1.5B-Instruct","messages":[{"role":"user","content":"Who are you?"}],"max_tokens":128}'

安全与运维说明

• 请对 HF_TOKEN 保密；建议通过环境变量或密钥管理器传递。
• 在生产环境中，请通过带 TLS 和身份验证的反向代理（Nginx）运行。
• 只将必要的主机路径挂载到容器中。

故障排除

• 容器无法访问 GPU：请确保已安装 nvidia-container-toolkit，并重启 Docker。
• 模型下载失败：请检查 HF_TOKEN 和网络；挂载缓存目录以保留下载内容。
• 内存 / OOM 错误：尝试使用更小的模型或增加 GPU 内存；检查 --shm-size。
• 如果容器因 NCCL 库路径问题而失败（少见）：请按照上游指南设置 VLLM_NCCL_SO_PATH。
• 当前用户的 Docker 权限问题：请确保你的用户属于 docker 组，或建议用户按照以下步骤手动将当前用户添加到 docker 组：

# 1. Create docker group if it doesn't exist (may already exist on some systems)
sudo groupadd docker

# 2. Add current user to the docker group (replace $USER with your username if needed)
sudo usermod -aG docker $USER

# 3. Apply the new group membership (you may need to log out and log back in for this to take effect)
newgrp docker

# 4. Verify that the user is in the docker group (output should include docker)
groups $USER

• Docker pull 因连接 Docker Hub 时网络超时而失败：请检查网络连接并重试。如果问题仍然存在，请建议用户使用 Docker Hub 镜像，并向用户展示具体用法。
• 从 Hugging Face 下载模型时出错：请检查是否已将 HF_TOKEN 传递给容器且令牌有效。如果主机位于代理后方，请检查是否已将 HTTP_PROXY 和 HTTPS_PROXY 传递给容器。此外，请确认模型 ID 正确，且该模型是公开的，或可通过提供的令牌访问。

参考资料

• vLLM 仓库（docker/Dockerfile）：https://github.com/vllm-project/vllm/tree/main/docker
• NVIDIA Container Toolkit：https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
• 最新部署说明和故障排除：https://docs.vllm.ai/en/latest/deployment/docker/