大模型K8s部署教程：从零搭建推理服务

在Kubernetes上部署大模型，本质是把推理服务封装成容器，通过Deployment调度到带GPU的节点，再用Service和Ingress对外提供接口。
下面以vLLM运行开源模型为例，给出从零到可调用的完整路径，适用于已有K8s集群、节点带NVIDIA GPU的环境。

环境准备与前提检查

开始前确认三件事：集群版本建议1.24以上、至少一个节点装有NVIDIA GPU、节点能访问镜像仓库。
在控制节点执行：

kubectl get nodes -o wide
kubectl get pods -n kube-system

接着检查GPU节点是否已安装驱动：

nvidia-smi

如果命令不存在或报错，需要先在节点安装NVIDIA驱动和nvidia-container-toolkit。
驱动版本要与后续CUDA镜像兼容，不确定时选择驱动较新的稳定版。

安装GPU调度组件

K8s默认不认识GPU资源，需要部署NVIDIA device plugin。
用Helm安装：

helm repo add nvidia https://helm.ngc.nvidia.com/nvidia
helm repo update
helm install --generate-name nvidia/device-plugin \
  --namespace kube-system

安装后查看节点可分配GPU数量：

kubectl describe node  | grep nvidia.com/gpu

输出中应出现类似 nvidia.com/gpu: 1 的容量信息。
若显示0，先检查device plugin Pod日志：

kubectl logs -n kube-system -l name=nvidia-device-plugin-ds

部署vLLM推理服务

创建一个Deployment，把模型挂载到容器内。
下面示例使用Qwen2.5-7B-Instruct，模型文件提前放在节点目录 /data/models/Qwen2.5-7B-Instruct，通过hostPath挂载。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-qwen
spec:
  replicas: 1
  selector:
    matchLabels:
      app: vllm-qwen
  template:
    metadata:
      labels:
        app: vllm-qwen
    spec:
      containers:
      - name: vllm
        image: vllm/vllm-openai:latest
        args: ["--model", "/models/Qwen2.5-7B-Instruct", "--served-model-name", "qwen", "--port", "8000"]
        ports:
        - containerPort: 8000
        resources:
          limits:
            nvidia.com/gpu: 1
        volumeMounts:
        - name: model-data
          mountPath: /models
      volumes:
      - name: model-data
        hostPath:
          path: /data/models
          type: Directory

保存为 vllm-deploy.yaml 后执行：

kubectl apply -f vllm-deploy.yaml
kubectl get pods -w

Pod进入Running且日志出现 Uvicorn running on 即表示服务启动成功。
首次加载模型可能耗时几分钟，用 kubectl logs -f 观察进度。

暴露服务并验证调用

先创建ClusterIP Service：

apiVersion: v1
kind: Service
metadata:
  name: vllm-qwen-svc
spec:
  selector:
    app: vllm-qwen
  ports:
  - port: 80
    targetPort: 8000

集群内测试：

kubectl run curl-test --image=curlimages/curl -it --rm -- sh
curl http://vllm-qwen-svc/v1/models

返回模型列表即表示推理服务正常。
若需外部访问，再配置Ingress或NodePort，注意安全组和防火墙放行对应端口。

常见报错与避坑提示

Pod一直Pending：多半是GPU资源不足或节点未打标签。
用 kubectl describe pod 查看事件，确认 nvidia.com/gpu 可分配。

容器启动后OOM退出：模型显存需求超过单卡容量。
7B模型建议至少16GB显存，可调整 --gpu-memory-utilization 参数控制占用比例。

模型下载慢：优先提前把模型文件放到节点本地，避免容器内下载。
hostPath方式简单但耦合节点，生产环境建议用PVC或对象存储。

镜像拉取失败：检查节点是否能访问镜像仓库，必要时配置私有仓库或镜像加速。

验证部署效果

完成上述步骤后，从三个方面确认：

• kubectl get pods 显示vLLM Pod为Running且重启次数为0。
• 集群内 curl /v1/models 返回模型名称。
• 发起一次对话请求：

curl http://vllm-qwen-svc/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen","messages":[{"role":"user","content":"你好"}]}'

能返回JSON格式的回复内容，说明大模型K8s部署已跑通。
后续可根据并发量调整副本数、资源限制和Ingress超时时间。
遇到异常时，优先回看Pod事件和容器日志，多数问题能在日志中找到直接原因。