vllm-deploy-k8s

vLLM Kubernetes 部署

一项用于通过 YAML 模板将 vLLM 部署到 Kubernetes 的 Claude 技能。将兼容 OpenAI 的 vLLM 服务部署为 Kubernetes Deployment，并配置 ClusterIP Service、GPU 资源和健康探针。

此技能的功能

• 将 vLLM 部署为支持 NVIDIA GPU 的 Kubernetes Deployment + Service
• 部署前检查 vLLM 是否已部署
• 检查 Hugging Face 令牌密钥是否存在；如果不存在，则向用户索取令牌
• 默认使用 vllm/vllm-openai:latest 镜像（用户可以指定其他版本）
• 提供合理的默认配置，用户可以自定义（模型、副本数、GPU 数量、额外的 vLLM 标志等）

前置条件

• 已配置 kubectl，并可访问 Kubernetes 集群
• 集群节点已安装 NVIDIA GPU Operator 或设备插件
• Hugging Face 令牌（受限模型（如 Llama）必需，公开模型可选）

部署步骤

步骤 1：检查 HF 令牌密钥

部署前，检查目标命名空间中是否存在 hf-token Kubernetes 密钥：

kubectl get secret hf-token -n <namespace>

• 如果密钥存在：继续步骤 2。
• 如果密钥不存在：请用户提供 Hugging Face 令牌，然后创建密钥：

kubectl create secret generic hf-token --from-literal=HF_TOKEN="<user-provided-token>" -n <namespace>

受限模型（例如 meta-llama/Meta-Llama-3.1-8B）需要此密钥。对于公开模型，该密钥是可选的，但建议配置，以避免触发速率限制。

步骤 2：检查 Deployment 是否已存在

应用配置前，检查 vLLM Deployment 是否已存在：

kubectl get deployment vllm -n <namespace>

• 如果已存在：告知用户该 Deployment 已存在。显示当前镜像和状态，并询问用户是否要更新或跳过。
• 如果不存在：继续部署。

步骤 3：部署

应用模板 YAML 文件以部署 vLLM：

kubectl apply -f templates/vllm-service.yaml -n <namespace>
kubectl apply -f templates/vllm-deployment.yaml -n <namespace>

步骤 4：等待并验证

等待 Deployment 完成滚动更新：

kubectl rollout status deployment/vllm -n <namespace> --timeout=600s

验证 Pod 是否正在运行且已就绪：

kubectl get pods -n <namespace> -l app=vllm

确认 Pod 显示 READY 1/1 和 STATUS Running。如果 Pod 尚未就绪，请等待后再次检查。如果状态为 CrashLoopBackOff 或 Error，请使用 kubectl logs -n <namespace> -l app=vllm 检查日志。

步骤 5：打印部署摘要

Pod 就绪后，按以下格式向用户打印摘要消息（将占位符替换为实际值）：

🎉 **vLLM Deployment Successful!**

| Resource | Name | Status |
|----------|------|--------|
| Deployment | <deployment-name> | <ready>/<total> Ready |
| Service | <service-name> | ClusterIP:<port> |
| Pod | <pod-name> | Running |
| Image | <image> | |
| Model | <model> | |

&nbsp;

**To test the API, run these two commands in your terminal:**

**1. Open a port-forward** (this connects your local port <port> to the vLLM service inside the cluster):

kubectl port-forward svc/vllm-svc <port>:<port> -n <namespace>

**2. In a separate terminal**, send a test request to the OpenAI-compatible API:

curl -s http://localhost:<port>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"<model>","messages":[{"role":"user","content":"Hello!"}],"max_tokens":50}' | python3 -m json.tool

If everything is working, you'll get a JSON response with the model's reply.

默认配置

模板使用以下默认值：

参数	默认值
镜像	vllm/vllm-openai:latest
模型	Qwen/Qwen2.5-1.5B-Instruct
端口	8000
副本数	1
GPU 数量	1
GPU 内存利用率	0.85
张量并行大小	1
CPU 请求 / 限制	12 / 128
内存请求 / 限制	100Gi / 400Gi
共享内存（dshm）	80Gi

自定义

当用户请求更改时，先修改模板 YAML 文件，再应用更改。可自定义以下内容：

• 镜像版本：更改 templates/vllm-deployment.yaml 中的 image: vllm/vllm-openai:<version>（默认值：latest）。如果用户提出要求，请使用特定版本标签，例如 v0.17.1。
• 模型：更改 Deployment args 中 vllm serve 命令里的模型名称。
• 额外的 vLLM 标志：在 Deployment args 中的 vllm serve 命令后追加标志（例如 --max-model-len 4096、--kv-cache-dtype fp8、--enforce-eager、--generation-config vllm）。
• 副本数：更改 Deployment 规格中的 replicas:。
• GPU 数量：更改资源配置中 requests 和 limits 下的 nvidia.com/gpu。
• 张量并行大小：更改 --tensor-parallel-size 标志，使其与 GPU 数量相符。
• CPU/内存资源：更改 requests 和 limits 下的 cpu 和 memory 值。
• 端口：更改 Deployment 中的 containerPort、Service 中的 port/targetPort、所有健康探测（存活、就绪、启动）中的 port，并在 args 中的 vllm serve 命令后添加 --port <port>。这四处必须保持一致。
• 命名空间：使用 -n <namespace> 应用到指定命名空间。
• 共享内存大小：更改 dshm emptyDir 卷的 sizeLimit。

使用 Edit 工具编辑模板文件，然后应用修改后的模板。

状态检查

kubectl get deployment,svc,pods -n <namespace> -l app=vllm

清理

当用户要求清理或删除 vLLM Deployment 时，执行以下步骤：

1. 删除 Deployment 和 Service：

kubectl delete -f templates/vllm-deployment.yaml -n <namespace>
kubectl delete -f templates/vllm-service.yaml -n <namespace>

2. 询问用户是否也要删除 HF token secret。如果是：

kubectl delete secret hf-token -n <namespace>

3. 验证是否已清理完毕：

kubectl get deployment,svc,pods -n <namespace> -l app=vllm

4. 向用户打印摘要消息：

vLLM deployment has been cleaned up from namespace <namespace>.
Deleted: Deployment/vllm, Service/vllm-svc
HF token secret: <kept/deleted>

故障排除

• Pod 卡在 Pending 状态：没有可用的 GPU 节点。使用 kubectl describe pod <pod-name> 检查调度错误。确保已安装 NVIDIA GPU Operator 或设备插件。
• Pod 被 OOMKilled：增加 Deployment 中的 memory 限制，或使用更小的模型。
• ImagePullBackOff：检查镜像名称和标签。确认节点可以访问 Docker Hub / 容器注册表。
• 启动探测失败（CrashLoopBackOff）：模型下载可能较慢。使用 kubectl logs <pod-name> 检查日志。对于受限模型，确保 hf-token secret 存在。必要时增大启动探测的 failureThreshold。
• HF_TOKEN 无法使用：验证 secret 是否存在：kubectl get secret hf-token -n <namespace>。检查令牌是否有效。
• 容器中未检测到 GPU：确保请求了 nvidia.com/gpu 资源，并且节点上运行着 NVIDIA 设备插件。

参考资料

• vLLM 文档
• vLLM Docker 镜像
• NVIDIA GPU Operator
• Kubernetes GPU 调度