基于 Docker 及 Kubernetes 部署 vLLM：开启机器学习模型服务的新篇章

在当今数字化浪潮中，机器学习模型的高效部署与管理成为众多开发者和企业关注的焦点。vLLM 作为一款性能卓越的大型语言模型推理引擎，其在 Docker 及 Kubernetes 上的部署方式如何呢？本文将深入探讨如何在 Docker 及 Kubernetes 集群中部署 vLLM，充分挖掘其潜力，助力机器学习模型服务的高效开展。

本文分两部分，第一部分介绍 Docker 部署；第二部分介绍基于 Kubernetes 部署。

基于 Docker 部署 vLLM

vLLM作为一款优秀的开源语言模型推理引擎，其在Docker容器中的部署方式为我们提供了一种高效、灵活且可扩展的解决方案。第一部分将深入探讨vLLM的Docker部署方法。

vLLM官方Docker镜像：便捷高效的起点

vLLM团队在Docker Hub上提供了官方Docker镜像vllm/vllm-openai，这为我们快速搭建OpenAI兼容服务器提供了极大的便利。其基本使用命令如下：

docker run --runtime nvidia --gpus all \-v ~/.cache/huggingface:/root/.cache/huggingface \--env "HUGGING_FACE_HUB_TOKEN=<secret>" \-p 8000:8000 \--ipc=host \vllm/vllm-openai:latest \--model mistralai/Mistral-7B-v0.1

此命令中，--runtime nvidia和--gpus all参数确保了NVIDIA GPU资源的充分利用；-v参数将本地Hugging Face缓存目录挂载到容器中，便于模型文件的共享与复用；--env参数用于设置环境变量，此处为Hugging Face Hub的认证令牌，保障模型下载的安全性与合法性；-p 8000:8000实现了宿主机与容器的端口映射，使外部能够访问模型服务；--ipc=host标志允许容器访问宿主机的共享内存，这对于vLLM基于PyTorch的进程间通信、尤其是张量并行推理过程至关重要。

值得一提的是，此镜像同样适用于其他容器引擎如Podman。在使用Podman时，命令略有调整：

podman run --gpus all \-v ~/.cache/huggingface:/root/.cache/huggingface \--env "HUGGING_FACE_HUB_TOKEN=$HF_TOKEN" \-p 8000:8000 \--ipc=host \vllm/vllm-openai:latest \--model mistralai/Mistral-7B-v0.1

这里使用$HF_TOKEN变量替代了直接的令牌值，体现了环境变量在不同系统间的适配性与灵活性。

自定义Docker镜像：满足个性化需求的进阶之路

尽管官方镜像功能强大，但在某些场景下，我们可能需要自定义镜像以满足特定需求。例如，当需要添加可选依赖项时，可基于官方镜像构建新的Dockerfile：

FROM vllm/vllm-openai:v0.9.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.9.0

此Dockerfile以vLLM 0.9.0版本镜像为基础，通过uv pip命令安装了音频处理相关的可选依赖。这为在语音识别、语音合成等多模态任务中应用vLLM提供了可能。

若要使用Hugging Face Transformers库的开发版本，亦可通过自定义Dockerfile实现：

FROM vllm/vllm-openai:latestRUN uv pip install --system git+https://github.com/huggingface/transformers.git

该命令从GitHub源代码仓库安装最新的Transformers库，使我们能够第一时间体验到最新的模型架构与算法优化。

从源码构建Docker镜像：深度定制与优化的关键

对于追求极致性能与功能定制的用户，从源码构建Docker镜像是不二之选。vLLM提供了详细的Dockerfile，位于项目根目录的docker文件夹中。构建命令如下：

# 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

这里，--target参数指定了构建目标阶段，--tag为生成的镜像指定标签，便于后续管理和使用。DOCKER_BUILDKIT=1启用Docker的现代化构建工具，提升构建效率与性能。

在构建过程中，可根据实际需求添加构建参数。例如，若仅针对当前机器的GPU类型进行构建，可添加--build-arg torch_cuda_arch_list=""，使vLLM自动检测并优化CUDA架构配置。对于使用Podman的用户，可能需要添加--security-opt label=disable以禁用SELinux标签，解决潜在的权限问题。

Arm64架构支持：拓展应用场景的前沿探索

随着Arm架构在服务器领域的崛起，vLLM也在积极探索其在Arm64平台（如Nvidia Grace-Hopper）上的应用。尽管目前仍处于实验阶段，但已取得显著进展。构建Arm64镜像的命令如下：

# Example of building on Nvidia GH200 server. (Memory usage: ~15GB, Build time: ~1475s / ~25 min, Image size: 6.93GB)
python3 use_existing_torch.py
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 vllm_fa_cmake_gpu_arches="90-real"

此命令中，--platform "linux/arm64"明确指定了目标平台，--build-arg参数用于优化构建过程中的各项配置。然而，由于Arm64构建涉及多个模块的编译，整个过程可能较为耗时且占用大量内存资源。建议在构建前合理设置max_jobs和nvcc_threads参数，以平衡构建速度与系统资源占用。

对于在非Arm主机上进行交叉编译的需求，可通过QEMU实现。首先运行以下命令注册QEMU用户静态处理器：

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

完成QEMU配置后，即可在x86_64等非Arm主机上使用--platform "linux/arm64"标志构建Arm64镜像，为跨平台部署vLLM提供了可能。

使用自定义镜像：从构建到应用的闭环

构建完成自定义镜像后，使用方法与官方镜像类似：

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

其中，vllm/vllm-openai应替换为自定义镜像的标签名称。这一步骤标志着从镜像构建到实际应用的闭环形成，使我们能够将定制化的vLLM部署到生产环境中，为各类人工智能应用提供强大的语言模型支持。

在特定版本（0.4.1和0.4.2）中，由于库文件权限问题，可能需要调整环境变量VLLM_NCCL_SO_PATH以确保正常运行。

上面是基于 Docker 的部署，那在 Kubernetes 中如何部署 vllm 呢？

基于 Kubernetes 部署 vLLM

vLLM 在 Kubernetes 上的部署方式更适合云上或分布式运行。这部分将介绍如何在 Kubernetes 集群中部署 vLLM。

部署方式概览

部署 vLLM 于 Kubernetes 上，主要有两种方式：CPU 部署和 GPU 部署。CPU 部署虽性能较 GPU 稍逊，但能满足日常演示与测试需求；而 GPU 部署则凭借强劲的并行计算能力，为模型推理提供强大动力，保障模型高效、快速响应。

除基础部署外，vLLM 还支持通过多种工具在 Kubernetes 上进行部署，如 Helm、InftyAI/llmaz、KServe、kubernetes-sigs/lws、meta-llama/llama-stack、substratusai/kubeai、vllm-project/aibrix 以及 vllm-project/production-stack 等。这些工具的引入，进一步丰富了部署手段，满足不同用户在实际应用场景下的多样化需求。

CPU 部署实践

进行 CPU 部署时，首先需创建 Kubernetes PVC（PersistentVolumeClaim）和 Secret，用于下载及存储 Hugging Face 模型。具体操作如下：

cat <<EOF |kubectl apply -f -
apiVersion: v1
kind: PersistentVolumeClaim
metadata:name: vllm-models
spec:accessModes:- ReadWriteOncevolumeMode: Filesystemresources:requests:storage: 50Gi
---
apiVersion: v1
kind: Secret
metadata:name: hf-token-secret
type: Opaque
data:token: $(HF_TOKEN)
EOF

完成上述配置后，启动 vLLM 服务器，创建 Kubernetes Deployment 和 Service ：

cat <<EOF |kubectl apply -f -
apiVersion: apps/v1
kind: Deployment
metadata:name: vllm-server
spec:replicas: 1selector:matchLabels:app.kubernetes.io/name: vllmtemplate:metadata:labels:app.kubernetes.io/name: vllmspec:containers:- name: vllmimage: vllm/vllm-openai:latestcommand: ["/bin/sh", "-c"]args: ["vllm serve meta-llama/Llama-3.2-1B-Instruct"]env:- name: HUGGING_FACE_HUB_TOKENvalueFrom:secretKeyRef:name: hf-token-secretkey: tokenports:- containerPort: 8000volumeMounts:- name: llama-storagemountPath: /root/.cache/huggingfacevolumes:- name: llama-storagepersistentVolumeClaim:claimName: vllm-models
---
apiVersion: v1
kind: Service
metadata:name: vllm-server
spec:selector:app.kubernetes.io/name: vllmports:- protocol: TCPport: 8000targetPort: 8000type: ClusterIP
EOF

部署完成后，可通过查看服务器日志验证其是否成功启动。执行命令 kubectl logs -l app.kubernetes.io/name=vllm，若日志显示类似以下内容，则表明服务器已正常运行：

INFO:     Started server process [1]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

GPU 部署实践

GPU 部署能显著提升模型推理效率，在开始之前，需确保 Kubernetes 集群已配备 GPU。以下是具体部署步骤：

（一）创建 PVC、Secret 及 Deployment

PVC 用于存储模型缓存，可按需选择存储方式，如 hostPath 等。Secret 仅在访问受限模型时才需配置，若无需使用受限模型，此步骤可跳过。以 NVIDIA GPU 为例，Deployment 配置如下：

apiVersion: apps/v1
kind: Deployment
metadata:
name: mistral-7b
namespace: default
labels:app: mistral-7b
spec:
replicas: 1
selector:matchLabels:app: mistral-7b
template:metadata:labels:app: mistral-7bspec:volumes:- name: cache-volumepersistentVolumeClaim:claimName: mistral-7b- name: shmemptyDir:medium: MemorysizeLimit: "2Gi"containers:- name: mistral-7bimage: vllm/vllm-openai:latestcommand: ["/bin/sh", "-c"]args: ["vllm serve mistralai/Mistral-7B-Instruct-v0.3 --trust-remote-code --enable-chunked-prefill --max_num_batched_tokens 1024"]env:- name: HUGGING_FACE_HUB_TOKENvalueFrom:secretKeyRef:name: hf-token-secretkey: tokenports:- containerPort: 8000resources:limits:cpu: "10"memory: 20Gnvidia.com/gpu: "1"requests:cpu: "2"memory: 6Gnvidia.com/gpu: "1"volumeMounts:- mountPath: /root/.cache/huggingfacename: cache-volume- name: shmmountPath: /dev/shmlivenessProbe:httpGet:path: /healthport: 8000initialDelaySeconds: 60periodSeconds: 10readinessProbe:httpGet:path: /healthport: 8000initialDelaySeconds: 60periodSeconds: 5

对于 AMD GPU，如 MI300X，其 Deployment 配置略有不同，以下是示例：

apiVersion: apps/v1
kind: Deployment
metadata:
name: mistral-7b
namespace: default
labels:app: mistral-7b
spec:
replicas: 1
selector:matchLabels:app: mistral-7b
template:metadata:labels:app: mistral-7bspec:volumes:- name: cache-volumepersistentVolumeClaim:claimName: mistral-7b- name: shmemptyDir:medium: MemorysizeLimit: "8Gi"hostNetwork: truehostIPC: truecontainers:- name: mistral-7bimage: rocm/vllm:rocm6.2_mi300_ubuntu20.04_py3.9_vllm_0.6.4securityContext:seccompProfile:type: UnconfinedrunAsGroup: 44capabilities:add:- SYS_PTRACEcommand: ["/bin/sh", "-c"]args: ["vllm serve mistralai/Mistral-7B-v0.3 --port 8000 --trust-remote-code --enable-chunked-prefill --max_num_batched_tokens 1024"]env:- name: HUGGING_FACE_HUB_TOKENvalueFrom:secretKeyRef:name: hf-token-secretkey: tokenports:- containerPort: 8000resources:limits:cpu: "10"memory: 20Gamd.com/gpu: "1"requests:cpu: "6"memory: 6Gamd.com/gpu: "1"volumeMounts:- name: cache-volumemountPath: /root/.cache/huggingface- name: shmmountPath: /dev/shm

更全面的示例及相关步骤、yaml 文件可从 https://github.com/ROCm/k8s-device-plugin/tree/master/example/vllm-serve 获取。

（二）创建 Service

为了使外部能访问部署的 vLLM 服务，需创建 Kubernetes Service 。以下是 Service 配置示例：

apiVersion: v1
kind: Service
metadata:name: mistral-7bnamespace: default
spec:ports:- name: http-mistral-7bport: 80protocol: TCPtargetPort: 8000
selector:app: mistral-7b
sessionAffinity: None
type: ClusterIP

（三）部署与测试

完成配置后，使用 kubectl apply -f <filename> 命令应用部署和 Service 配置。执行以下命令进行测试：

curl http://mistral-7b.default.svc.cluster.local/v1/completions \-H "Content-Type: application/json" \-d '{"model": "mistralai/Mistral-7B-Instruct-v0.3","prompt": "San Francisco is a","max_tokens": 7,"temperature": 0}'

若服务部署成功，将收到 vLLM 模型返回的响应。

总结

vLLM的Docker部署方法丰富多样，从官方镜像的快速应用到自定义镜像的深度定制，再到Arm64架构的前沿探索，为我们提供了全方位的技术解决方案。在科研与实际应用中，合理选择与优化部署策略，将有助于充分发挥vLLM的性能优势，比如单机、简单、高效等。

基于 Kubernetes 部署 vLLM，能充分利用 GPU 资源，实现机器学习模型服务的高效扩展与管理。无论是科研探索还是企业生产场景，这一部署方案都展现出巨大潜力和应用价值。希望本文的介绍能为您提供有益参考，助力大家在实际项目中更好地利用 vLLM 进行模型服务部署，推动机器学习技术在各行业的广泛应用与创新发展。