使用 Docker¶

使用 vLLM 的官方 Docker 映象¶

vLLM 提供了一個官方 Docker 映象用於部署。該映象可用於執行相容 OpenAI 的伺服器，並可在 Docker Hub 上找到，地址為 vllm/vllm-openai。

docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=$HF_TOKEN" \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:latest \
    --model Qwen/Qwen3-0.6B

此映象也可與其他容器引擎（如 Podman）配合使用。

podman run --device nvidia.com/gpu=all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  --env "HF_TOKEN=$HF_TOKEN" \
  -p 8000:8000 \
  --ipc=host \
  docker.io/vllm/vllm-openai:latest \
  --model Qwen/Qwen3-0.6B

您可以在映象標籤（vllm/vllm-openai:latest）後新增任何其他所需的 engine-args。

注意

您可以使用 ipc=host 標誌或 --shm-size 標誌來允許容器訪問主機的共享記憶體。vLLM 使用 PyTorch，PyTorch 在底層使用共享記憶體來在程序之間共享資料，特別是對於張量並行推理。

注意

可選依賴項未包含在內，以避免許可問題（例如問題 #8030）。

如果您需要使用這些依賴項（並已接受許可條款），請在基礎映象之上建立一個自定義 Dockerfile，並新增一個額外的層來安裝它們。

FROM vllm/vllm-openai:v0.11.0

# e.g. install the `audio` optional dependencies
# NOTE: Make sure the version of vLLM matches the base image!
RUN uv pip install --system vllm[audio]==0.11.0

提示

一些新模型可能僅在 HF Transformers 的主分支上可用。

要使用 transformers 的開發版本，請在基礎映象之上建立一個自定義 Dockerfile，並新增一個額外的層來從原始碼安裝其程式碼。

FROM vllm/vllm-openai:latest

RUN uv pip install --system git+https://github.com/huggingface/transformers.git

從原始碼構建 vLLM 的 Docker 映象¶

您可以透過提供的 docker/Dockerfile 構建並執行 vLLM。要構建 vLLM：

# optionally specifies: --build-arg max_jobs=8 --build-arg nvcc_threads=2
DOCKER_BUILDKIT=1 docker build . \
    --target vllm-openai \
    --tag vllm/vllm-openai \
    --file docker/Dockerfile

注意

預設情況下，vLLM 將為所有 GPU 型別進行構建，以實現最廣泛的發行。如果您僅為當前執行機器的 GPU 型別進行構建，可以在執行 --build-arg torch_cuda_arch_list="" 引數時新增該引數，以便 vLLM 查詢當前 GPU 型別併為其構建。

如果您使用的是 Podman 而非 Docker，則在執行 podman build 命令時，可能需要透過新增 --security-opt label=disable 來停用 SELinux 標籤，以避免某些現有問題。

為 Arm64/aarch64 構建¶

可以為 aarch64 系統（如 Nvidia Grace-Hopper 和 Grace-Blackwell）構建 Docker 容器。使用 --platform "linux/arm64" 標誌將為 arm64 構建。

注意

需要編譯多個模組，因此此過程可能需要一段時間。建議使用 --build-arg max_jobs= 和 --build-arg nvcc_threads= 標誌來加快構建過程。但是，請確保您的 max_jobs 遠大於 nvcc_threads 以獲得最大效益。請注意並行作業的記憶體使用量，因為記憶體消耗可能很大（請參見下面的示例）。

命令

# Example of building on Nvidia GH200 server. (Memory usage: ~15GB, Build time: ~1475s / ~25 min, Image size: 6.93GB)
DOCKER_BUILDKIT=1 docker build . \
--file docker/Dockerfile \
--target vllm-openai \
--platform "linux/arm64" \
-t vllm/vllm-gh200-openai:latest \
--build-arg max_jobs=66 \
--build-arg nvcc_threads=2 \
--build-arg torch_cuda_arch_list="9.0 10.0+PTX" \
--build-arg RUN_WHEEL_CHECK=false

對於 (G)B300，我們建議使用 CUDA 13，如下面的命令所示。

命令

DOCKER_BUILDKIT=1 docker build \
--build-arg CUDA_VERSION=13.0.1 \
--build-arg BUILD_BASE_IMAGE=nvidia/cuda:13.0.1-devel-ubuntu22.04 \
--build-arg max_jobs=256 \
--build-arg nvcc_threads=2 \
--build-arg RUN_WHEEL_CHECK=false \
--build-arg torch_cuda_arch_list='9.0 10.0+PTX' \
--platform "linux/arm64" \
--tag vllm/vllm-gb300-openai:latest \
--target vllm-openai \
-f docker/Dockerfile \
.

注意

如果您在非 ARM 主機（例如 x86_64 機器）上構建 linux/arm64 映象，則需要確保您的系統已透過 QEMU 設定為交叉編譯。這允許您的主機模擬 ARM64 執行。

在主機上執行以下命令以註冊 QEMU 使用者靜態處理程式：

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

設定 QEMU 後，您可以在 docker build 命令中使用 --platform "linux/arm64" 標誌。

使用自定義構建的 vLLM Docker 映象¶

使用自定義構建的 Docker 映象執行 vLLM：

docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    --env "HF_TOKEN=<secret>" \
    vllm/vllm-openai <args...>

引數 vllm/vllm-openai 指定要執行的映象，應替換為自定義構建映象的名稱（構建命令中的 -t 標籤）。

注意

僅適用於 0.4.1 和 0.4.2 版本 - 這些版本的 vLLM Docker 映象需要以 root 使用者身份執行，因為需要載入 root 使用者主目錄下的一個庫，即 /root/.config/vllm/nccl/cu12/libnccl.so.2.18.1。如果您以其他使用者身份執行容器，則可能需要首先更改該庫（及其所有父目錄）的許可權，以允許該使用者訪問它，然後使用環境變數 VLLM_NCCL_SO_PATH=/root/.config/vllm/nccl/cu12/libnccl.so.2.18.1 執行 vLLM。