第2章环境准备

2、环境准备：Docker与Kubernetes集群搭建、GPU驱动与CUDA环境验证、NVIDIA Container Toolkit安装

说实话，很多人在部署vLLM时翻车，不是模型本身的问题，而是环境没配好。我见过太多人花了两天调模型，最后发现是CUDA版本不对——这种坑，踩一次就够了。

这一章，咱们把地基打牢。Docker、Kubernetes集群、GPU驱动、CUDA、NVIDIA Container Toolkit，一个都不能少。我会把我在生产环境中踩过的坑、总结的经验，全都摊开来讲。

核心要点：本章所有操作的目标，是让vLLM能在Kubernetes里正常调用GPU。说白了，就是让容器里的Python代码能顺利跑在NVIDIA显卡上。

2.1 Docker安装与配置

Docker是容器化的基石。我个人习惯用官方脚本安装，干净利落。

# 卸载旧版本（如果有）
sudo apt-get remove docker docker-engine docker.io containerd runc

# 安装依赖
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release

# 添加Docker官方GPG密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 设置稳定版仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io

# 启动并设置开机自启
sudo systemctl start docker
sudo systemctl enable docker

# 验证安装
sudo docker run hello-world

小技巧：安装完成后，记得把当前用户加入docker组，避免每次都要sudo。命令：sudo usermod -aG docker $USER。然后退出重新登录。

我曾经遇到过一个问题：docker run hello-world能跑，但拉取大镜像时总是超时。后来发现是DNS配置问题。建议在/etc/docker/daemon.json里加上国内镜像源：

{
  "registry-mirrors": ["https://docker.mirrors.ustc.edu.cn"]
}

改完记得重启Docker：sudo systemctl restart docker。

2.2 Kubernetes集群搭建（Minikube vs K3s）

本地开发环境，我推荐Minikube。生产环境模拟，K3s更轻量。你想想看，vLLM推理服务对GPU要求高，集群规模不会太大，K3s其实挺合适的。

方案一：Minikube（适合单机学习）

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

# 启动集群（指定驱动为docker）
minikube start --driver=docker --cpus=4 --memory=8192

# 验证集群状态
minikube status
kubectl get nodes

方案二：K3s（更接近生产环境）

# 一键安装K3s
curl -sfL https://get.k3s.io | sh -

# 查看节点状态
sudo k3s kubectl get nodes

# 为了方便，配置kubectl别名
echo "alias kubectl='sudo k3s kubectl'" >> ~/.bashrc
source ~/.bashrc

注意：K3s默认使用containerd而非Docker。如果你后续要用Docker构建镜像，需要额外配置。我个人习惯在K3s上直接使用containerd，少一层抽象，性能更好。

2.3 GPU驱动与CUDA环境验证

这一步是重中之重。vLLM依赖CUDA来加速推理，驱动不对，后面全白搭。

检查GPU驱动

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

# 查看驱动版本
nvidia-smi

# 如果没有输出，说明驱动没装
# 安装驱动（以Ubuntu 22.04为例）
sudo apt-get install -y nvidia-driver-535

我记得有一次，nvidia-smi能正常显示，但CUDA程序就是跑不起来。后来发现是驱动版本和CUDA Toolkit版本不匹配。这里有个经验：驱动版本 >= CUDA Toolkit版本，一般没问题。

验证CUDA环境

# 查看CUDA版本
nvcc --version

# 如果没装CUDA Toolkit，可以这样装
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

验证CUDA是否可用：运行nvidia-smi看到GPU信息，再运行nvcc --version看到CUDA版本，两者都正常，基本就稳了。

2.4 NVIDIA Container Toolkit安装

这是让Docker容器能调用GPU的关键。说白了，它就是个桥梁，把宿主机的GPU设备映射到容器里。

# 添加NVIDIA Container Toolkit仓库
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-get update
sudo apt-get install -y nvidia-container-toolkit

# 配置Docker运行时
sudo nvidia-ctk runtime configure --runtime=docker

# 重启Docker
sudo systemctl restart docker

# 验证：运行一个带GPU的容器
sudo docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

验证技巧：如果上面的命令能正常输出GPU信息，说明NVIDIA Container Toolkit安装成功。我曾经遇到一个问题：容器里nvidia-smi能跑，但vLLM就是报错。后来发现是容器里CUDA版本和宿主机不一致。建议容器镜像的CUDA版本和宿主机保持一致。

2.5 在Kubernetes中验证GPU可用性

集群搭好了，驱动也装了，接下来要在K8s里验证GPU是否能被Pod使用。

# 创建一个测试Pod
cat <




  常见问题：如果Pod一直处于Pending状态，检查一下集群是否安装了NVIDIA Device Plugin。安装命令：kubectl apply -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/v0.14.0/nvidia-device-plugin.yml。我遇到过好几次，都是因为忘了装这个插件。


2.6 本章知识体系

下面这张图，把本章的核心逻辑串起来了。你可以把它当作一个检查清单：



这张图的核心逻辑是：Docker和K8s是容器化基础，GPU驱动和CUDA是硬件基础，NVIDIA Container Toolkit是连接两者的桥梁。缺了任何一环，vLLM都跑不起来。

2.7 避坑指南

最后，分享几个我踩过的坑：


  驱动版本问题：我曾经在Ubuntu 20.04上装了nvidia-driver-470，结果CUDA 12.1不兼容。建议用nvidia-driver-535或更高版本。
  容器内CUDA版本：vLLM官方镜像用的是CUDA 12.1，如果你宿主机CUDA版本太低，容器里会报错。保持版本一致最省心。
  K3s GPU支持：K3s默认不启用GPU，需要手动安装NVIDIA Device Plugin。我一开始没注意，Pod一直Pending，查了半天才发现。
  Docker存储驱动：overlay2是推荐方案，别用devicemapper。性能差很多。



  快速验证清单：
  
    nvidia-smi → 显示GPU信息
    nvcc --version → 显示CUDA版本
    docker run --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi → 容器内能调用GPU
    kubectl run gpu-test --image=nvidia/cuda:12.1.0-base-ubuntu22.04 --restart=Never -- nvidia-smi → K8s Pod能调用GPU
  
  四条命令都通过，环境就准备好了。


嗯，环境准备这块，说难不难，说简单也不简单。关键是把每一步都验证到位。下一章咱们就开始搭建vLLM推理服务了，到时候你会发现，今天花的时间都是值得的。



公众号:蓝海资料掘金营，微信deep3321
        
            ← 上一章
            📖 返回目录
            下一章 →
        
        专注资料整理

📚 课程目录

2、环境准备：Docker与Kubernetes集群搭建、GPU驱动与CUDA环境验证、NVIDIA Container Toolkit安装

2.1 Docker安装与配置

2.2 Kubernetes集群搭建（Minikube vs K3s）

方案一：Minikube（适合单机学习）

方案二：K3s（更接近生产环境）

2.3 GPU驱动与CUDA环境验证

检查GPU驱动

验证CUDA环境

2.4 NVIDIA Container Toolkit安装

2.5 在Kubernetes中验证GPU可用性

2.6 本章知识体系

2.7 避坑指南