使用 Kubernetes

在 Kubernetes 上部署 vLLM 是一种可扩展且高效的模型服务方式。本指南将引导您完成使用原生 Kubernetes 部署 vLLM 的过程。

• 基于 CPU 的部署
• 基于 GPU 的部署
• 故障排除
  • 启动探针或就绪探针失败，容器日志包含 "KeyboardInterrupt: terminated"
• 结论

或者，您也可以通过以下任一方式将 vLLM 部署到 Kubernetes：

• Helm
• NVIDIA Dynamo
• InftyAI/llmaz
• llm-d
• KAITO
• KServe
• Kthena
• KubeRay
• kubernetes-sigs/lws
• meta-llama/llama-stack
• substratusai/kubeai
• vllm-project/AIBrix
• vllm-project/production-stack

基于 CPU 的部署

注意

此处使用 CPU 仅供演示和测试目的，其性能将无法与 GPU 相媲美。

首先，创建一个 Kubernetes PVC 和 Secret，用于下载和存储 Hugging Face 模型。

配置

cat <<EOF |kubectl apply -f -
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: vllm-models
spec:
  accessModes:
    - ReadWriteOnce
  volumeMode: Filesystem
  resources:
    requests:
      storage: 50Gi
---
apiVersion: v1
kind: Secret
metadata:
  name: hf-token-secret
type: Opaque
stringData:
  token: "REPLACE_WITH_TOKEN"
EOF

在此处，token 字段存储您的 Hugging Face 访问令牌。有关如何生成令牌的详细信息，请参阅 Hugging Face 文档。

接下来，将 vLLM 服务器作为 Kubernetes Deployment 和 Service 启动。

请注意，您需要根据您的处理器架构配置 vLLM 镜像。

配置

VLLM_IMAGE=public.ecr.aws/q9t5s3a7/vllm-cpu-release-repo:latest       # use this for x86_64
VLLM_IMAGE=public.ecr.aws/q9t5s3a7/vllm-arm64-cpu-release-repo:latest # use this for arm64
cat <<EOF |kubectl apply -f -
apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-server
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: vllm
  template:
    metadata:
      labels:
        app.kubernetes.io/name: vllm
    spec:
      containers:
      - name: vllm
        image: $VLLM_IMAGE
        command: ["/bin/sh", "-c"]
        args: [
          "vllm serve meta-llama/Llama-3.2-1B-Instruct"
        ]
        env:
        - name: HF_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-token-secret
              key: token
        ports:
          - containerPort: 8000
        volumeMounts:
          - name: llama-storage
            mountPath: /root/.cache/huggingface
      volumes:
      - name: llama-storage
        persistentVolumeClaim:
          claimName: vllm-models
---
apiVersion: v1
kind: Service
metadata:
  name: vllm-server
spec:
  selector:
    app.kubernetes.io/name: vllm
  ports:
  - protocol: TCP
    port: 8000
    targetPort: 8000
  type: ClusterIP
EOF

我们可以通过日志验证 vLLM 服务器是否已成功启动（下载模型可能需要几分钟时间）。

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 集群。

1. 为 vLLM 创建 PVC、Secret 和 Deployment。

   PVC 用于存储模型缓存，这是可选的，您可以使用 hostPath 或其他存储选项。

   Yaml

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: mistral-7b
     namespace: default
   spec:
     accessModes:
     - ReadWriteOnce
     resources:
       requests:
         storage: 50Gi
     storageClassName: default
     volumeMode: Filesystem
   

   Secret 是可选的，仅在访问受限模型（gated models）时才需要，如果您不使用受限模型，可以跳过此步骤。

   apiVersion: v1
   kind: Secret
   metadata:
     name: hf-token-secret
     namespace: default
   type: Opaque
   stringData:
     token: "REPLACE_WITH_TOKEN"
   

   接下来创建 vLLM 的部署文件以运行模型服务器。以下示例部署了 Mistral-7B-Instruct-v0.3 模型。

   以下是使用 NVIDIA GPU 和 AMD GPU 的两个示例。

   NVIDIA GPU

   Yaml

   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-7b
       spec:
         volumes:
         - name: cache-volume
           persistentVolumeClaim:
             claimName: mistral-7b
         # vLLM needs to access the host's shared memory for tensor parallel inference.
         - name: shm
           emptyDir:
             medium: Memory
             sizeLimit: "2Gi"
         containers:
         - name: mistral-7b
           image: vllm/vllm-openai:latest
           command: ["/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: HF_TOKEN
             valueFrom:
               secretKeyRef:
                 name: hf-token-secret
                 key: token
           ports:
           - containerPort: 8000
           resources:
             limits:
               cpu: "10"
               memory: 20G
               nvidia.com/gpu: "1"
             requests:
               cpu: "2"
               memory: 6G
               nvidia.com/gpu: "1"
           volumeMounts:
           - mountPath: /root/.cache/huggingface
             name: cache-volume
           - name: shm
             mountPath: /dev/shm
           livenessProbe:
             httpGet:
               path: /health
               port: 8000
             initialDelaySeconds: 60
             periodSeconds: 10
           readinessProbe:
             httpGet:
               path: /health
               port: 8000
             initialDelaySeconds: 60
             periodSeconds: 5
   

   AMD GPU

   如果您使用 MI300X 等 AMD ROCm GPU，可以参考下方的 deployment.yaml。

   Yaml

   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-7b
       spec:
         volumes:
         # PVC
         - name: cache-volume
           persistentVolumeClaim:
             claimName: mistral-7b
         # vLLM needs to access the host's shared memory for tensor parallel inference.
         - name: shm
           emptyDir:
             medium: Memory
             sizeLimit: "8Gi"
         hostNetwork: true
         hostIPC: true
         containers:
         - name: mistral-7b
           image: rocm/vllm:rocm6.2_mi300_ubuntu20.04_py3.9_vllm_0.6.4
           securityContext:
             seccompProfile:
               type: Unconfined
             runAsGroup: 44
             capabilities:
               add:
               - SYS_PTRACE
           command: ["/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: HF_TOKEN
             valueFrom:
               secretKeyRef:
                 name: hf-token-secret
                 key: token
           ports:
           - containerPort: 8000
           resources:
             limits:
               cpu: "10"
               memory: 20G
               amd.com/gpu: "1"
             requests:
               cpu: "6"
               memory: 6G
               amd.com/gpu: "1"
           volumeMounts:
           - name: cache-volume
             mountPath: /root/.cache/huggingface
           - name: shm
             mountPath: /dev/shm
   

   您可以从 https://github.com/ROCm/k8s-device-plugin/tree/master/example/vllm-serve 获取包含步骤和示例 yaml 文件的完整指南。

2. 为 vLLM 创建 Kubernetes Service

   接下来，创建一个 Kubernetes Service 文件以公开 mistral-7b 部署。

   Yaml

   apiVersion: v1
   kind: Service
   metadata:
     name: mistral-7b
     namespace: default
   spec:
     ports:
     - name: http-mistral-7b
       port: 80
       protocol: TCP
       targetPort: 8000
     # The label selector should match the deployment labels & it is useful for prefix caching feature
     selector:
       app: mistral-7b
     sessionAffinity: None
     type: ClusterIP
   

3. 部署与测试

   使用 kubectl apply -f <filename> 应用部署和 Service 配置。

   kubectl apply -f deployment.yaml
   kubectl apply -f service.yaml
   

   要测试部署，请运行以下 curl 命令。

   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 模型的响应。

故障排除

启动探针或就绪探针失败，容器日志包含 "KeyboardInterrupt: terminated"

如果启动探针或就绪探针的 failureThreshold 设置过低，不足以覆盖服务器启动所需的时间，Kubernetes 调度器将终止该容器。以下是这种情况的几种表现：

1. 容器日志包含 "KeyboardInterrupt: terminated"
2. kubectl get events 显示消息 Container $NAME failed startup probe, will be restarted

为缓解此问题，请增加 failureThreshold 以留出更多时间让模型服务器准备就绪。您可以通过从清单中移除探针并测量模型服务器显示已准备就绪所需的时间，来确定理想的 failureThreshold 值。

结论

利用 Kubernetes 部署 vLLM 可以实现机器学习模型的高效扩展和管理，并充分利用 GPU 资源。按照上述步骤，您应该能够在 Kubernetes 集群中设置并测试 vLLM 部署。如果您遇到任何问题或有改进建议，欢迎为文档做出贡献。