基于 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 進行模型服務部署，推動機器學習技術在各行業的廣泛應用與創新發展。