第2章：环境准备——K8s集群搭建与GPU节点配置

说实话，很多人在vLLM部署上栽跟头，不是因为模型本身多复杂，而是环境没搭好。我见过太多人花了两天调驱动，结果发现是K8s版本不兼容。这一章，咱们就把地基打牢。

2.1 选择你的K8s集群方案

我个人习惯把K8s集群分成两类：本地实验型和生产型。做vLLM负载均衡实验，我建议先从本地开始。

你想想看，Minikube和K3s最大的区别在哪？Minikube会帮你管理好虚拟机，而K3s直接跑在宿主机上。我在项目中遇到过，用Minikube做GPU透传时，需要额外装一个nvidia-mounter插件，而K3s直接挂载/dev/nvidia*就行。

2.2 搭建Minikube集群（带GPU支持）

嗯，这里要注意：Minikube默认不开启GPU。你得手动指定驱动。

# 安装Minikube（Linux环境）
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

# 启动集群，指定GPU驱动
minikube start \
  --driver=docker \
  --gpus=all \
  --cpus=4 \
  --memory=8g \
  --kubernetes-version=v1.28.3

我曾经踩过一个坑：--gpus=all这个参数在Minikube 1.30版本之前是不支持的。如果你用的是老版本，得手动装nvidia-container-toolkit。说白了，就是让Docker能识别到NVIDIA显卡。

2.3 K3s集群搭建（更轻量）

如果你机器配置不高，或者想模拟边缘部署场景，K3s是更好的选择。我个人习惯在生产边缘节点上用K3s，因为它启动快、内存占用低。

# 一键安装K3s
curl -sfL https://get.k3s.io | sh -s - \
  --docker \
  --disable=traefik \
  --write-kubeconfig-mode=644

# 验证集群
sudo k3s kubectl get nodes

为什么我要加--disable=traefik？因为vLLM负载均衡我们后面会用Nginx或者K8s Service来做，Traefik在这里反而多余。你想想看，少一个组件就少一个故障点。

2.4 GPU节点配置——NVIDIA驱动与CUDA

这是整个环境准备里最容易出问题的一环。我见过有人驱动装了三遍，结果发现是Secure Boot没关。

2.4.1 检查硬件

# 查看显卡型号
lspci | grep -i nvidia

# 查看驱动是否已装
nvidia-smi

如果nvidia-smi报错，别慌。先看看是不是驱动没装，或者内核模块没加载。

2.4.2 安装NVIDIA驱动

我个人推荐用runfile方式安装，虽然麻烦点，但可控性高。当然，如果你用的是Ubuntu，用apt也行。

# 方法一：apt安装（推荐Ubuntu用户）
sudo apt update
sudo apt install nvidia-driver-535

# 方法二：runfile安装（通用）
wget https://us.download.nvidia.com/XFree86/Linux-x86_64/535.154.05/NVIDIA-Linux-x86_64-535.154.05.run
chmod +x NVIDIA-Linux-x86_64-535.154.05.run
sudo ./NVIDIA-Linux-x86_64-535.154.05.run

2.4.3 安装CUDA Toolkit

vLLM需要CUDA 11.8以上。我建议装12.1，兼容性最好。

# 下载CUDA 12.1
wget https://developer.download.nvidia.com/compute/cuda/12.1.0/local_installers/cuda_12.1.0_530.30.02_linux.run
sudo sh cuda_12.1.0_530.30.02_linux.run

# 配置环境变量
echo 'export PATH=/usr/local/cuda-12.1/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

# 验证
nvcc --version

嗯，这里有个细节：CUDA Toolkit和驱动的版本要匹配。我曾经因为驱动是535版，CUDA装了12.0，结果编译vLLM时一直报cudaErrorInsufficientDriver。后来查了兼容性表才发现，535驱动对应CUDA 12.1以上。

2.5 安装NVIDIA Container Toolkit

这一步是为了让容器能访问GPU。说白了，就是让Docker/K8s知道「哦，这个容器需要显卡」。

# 添加仓库
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

# 安装
sudo apt update
sudo apt install nvidia-container-toolkit

# 重启Docker
sudo systemctl restart docker

docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

2.6 vLLM镜像准备

vLLM官方提供了Docker镜像，但我建议自己构建。为什么？因为官方镜像里有些依赖版本可能跟你环境不匹配。我在项目中遇到过，官方镜像用的PyTorch 2.1，而我CUDA是12.1，结果跑起来性能差了一截。

2.6.1 拉取官方镜像（快速验证）

docker pull vllm/vllm-openai:latest

2.6.2 自己构建镜像（推荐）

# 克隆vLLM仓库
git clone https://github.com/vllm-project/vllm.git
cd vllm

# 修改Dockerfile，指定CUDA版本
# 在Dockerfile中找到 FROM nvidia/cuda:12.1.0-base-ubuntu22.04

# 构建
docker build -t vllm-custom:12.1 .

你想想看，自己构建的好处是什么？你可以控制每个依赖的版本。比如我习惯把transformers固定到4.36.0，因为新版有些API变了，vLLM可能还没适配。

2.7 验证整个链路

最后，咱们跑一个简单的测试，确保K8s能调度GPU给vLLM。

# 部署一个测试Pod
cat <