GPUStack 生产环境部署：NVIDIA 驱动 + CUDA + cuDNN 全流程记录

背景

2026 年 3 月，在完成 information-collection-s 的数据库改造后，同一天对生产环境的 GPU 算力服务器做了全流程环境部署。目标是在一台配备 NVIDIA 显卡的 Linux 服务器上，从裸机状态搭建完整的 AI 推理环境，并通过 GPUStack 平台统一管理和部署大语言模型。

服务器配置：单机单卡（NVIDIA GPU），Ubuntu 22.04 LTS，需要承载 7B~14B 级别的开源模型推理任务。

第一步：NVIDIA 驱动安装

确认显卡型号

lspci | grep -i nvidia

卸载旧驱动

如果服务器之前装过 Nouveau 开源驱动或者其他版本的 NVIDIA 驱动，先做清理：

# 卸载已有 NVIDIA 驱动
sudo apt-get purge nvidia*
sudo apt-get autoremove

# 禁用 Nouveau（如果存在）
echo "blacklist nouveau" | sudo tee /etc/modprobe.d/blacklist-nvidia-nouveau.conf
echo "options nouveau modeset=0" | sudo tee -a /etc/modprobe.d/blacklist-nvidia-nouveau.conf
sudo update-initramfs -u

安装驱动

从 NVIDIA 官网下载对应显卡型号的驱动（推荐使用 runfile 安装，避免包管理器版本过旧）：

# 进入纯文本模式（禁用图形界面）
sudo systemctl set-default multi-user.target
sudo reboot

# 安装驱动
chmod +x NVIDIA-Linux-x86_64-XXX.xx.run
sudo ./NVIDIA-Linux-x86_64-XXX.xx.run

安装完成后用 nvidia-smi 验证，确认驱动版本和 CUDA 版本号。

第二步：CUDA Toolkit 安装

GPUStack 依赖 CUDA 运行时来调用 GPU 算力。推荐使用 runfile 方式安装，与驱动解耦，方便版本管理。

# 下载 CUDA 12.x Toolkit
wget https://developer.download.nvidia.com/compute/cuda/12.x.x/local_installers/cuda_12.x.x_XXX.xx_linux.run
sudo sh cuda_12.x.x_XXX.xx_linux.run --toolkit --silent --override

配置环境变量：

echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

验证 CUDA 安装：

nvcc --version

输出类似 Cuda compilation tools, release 12.x, V12.x.x 即表示成功。

第三步：cuDNN 安装

cuDNN（CUDA Deep Neural Network library）是 NVIDIA 针对深度学习的加速库，vLLM、TensorRT-LLM 等推理引擎都依赖它。

# 下载 cuDNN（需要 NVIDIA Developer 账号，选对应 CUDA 12.x 的版本）
# 下载得到 cudnn-linux-x86_64-9.x.x.x_cuda12-archive.tar.xz

tar -xvf cudnn-linux-x86_64-9.x.x.x_cuda12-archive.tar.xz
sudo cp cudnn-*-archive/include/cudnn*.h /usr/local/cuda/include/
sudo cp -P cudnn-*-archive/lib/libcudnn* /usr/local/cuda/lib64/
sudo chmod a+r /usr/local/cuda/include/cudnn*.h /usr/local/cuda/lib64/libcudnn*

# 验证 cuDNN 版本
cat /usr/local/cuda/include/cudnn_version.h | grep CUDNN_MAJOR -A 2

踩坑：驱动版本与 CUDA 版本的对应关系

第一次安装时没注意 nvidia-smi 输出的 CUDA Version 只是驱动支持的最高 CUDA 版本（与 nvcc --version 是两回事）。实际需要安装的 CUDA Toolkit 版本不能超过驱动支持的版本上限。例如：

• nvidia-smi 显示 CUDA Version: 12.4 → 最高只能装 CUDA Toolkit 12.4
• 强行装 12.6 会导致 nvcc 编译出来的程序无法运行

这个坑在装 cuDNN 时也会暴露——cuDNN 版本必须和 CUDA Toolkit 版本精确匹配。

第四步：Docker + NVIDIA Container Toolkit

GPUStack 推荐通过 Docker 部署，需要容器能访问宿主机的 GPU。

# 安装 Docker
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

# 安装 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
sudo systemctl restart docker

验证 GPU 能在容器中使用：

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

第五步：GPUStack 部署

安装 GPUStack

# 使用官方一键安装脚本
curl -sfL https://get.gpustack.ai | sudo sh -

安装完成后默认启动在 http://<server-ip>:9090。

初始化配置

首次访问需要创建管理员账号，确认 GPU 节点自动注册到集群中。在 Dashboard 中可以看到：

• GPU 型号和显存容量
• 在线状态和负载
• 已注册的推理引擎

部署模型

通过 GPUStack UI 或 API 部署模型：

# 通过 API 部署 Qwen2.5-7B-Instruct
curl -X POST http://localhost:9090/v1/models \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "model": "Qwen/Qwen2.5-7B-Instruct",
    "replicas": 1,
    "engine": "vllm",
    "config": {
      "max_model_len": 8192,
      "gpu_memory_utilization": 0.9
    }
  }'

验证推理

通过兼容 OpenAI API 的接口验证模型是否正常响应：

curl http://localhost:9090/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen2.5-7B-Instruct",
    "messages": [{"role": "user", "content": "你好，请简单介绍一下自己"}]
  }'

多模型管理

GPUStack 支持同时部署多个模型，按需分配 GPU 显存。同一张 GPU 上可以部署多个小模型，每个模型独立管理副本数和引擎配置。

部署 Checklist

步骤	验证命令	通过条件
NVIDIA 驱动	nvidia-smi	显示 GPU 型号和驱动版本
CUDA Toolkit	nvcc --version	显示正确版本号
cuDNN	cat /usr/local/cuda/include/cudnn_version.h	显示 Major/Minor/Patch 版本
Docker GPU	docker run --rm --gpus all nvidia/cuda nvidia-smi	容器内可识别 GPU
GPUStack	curl http://localhost:9090/v1/models	返回模型列表
模型推理	OpenAI API 调用	正常返回 ChatCompletion 响应

踩坑汇总

1. 驱动 CUDA Version ≠ 已安装的 CUDA Toolkit：nvidia-smi 显示的 CUDA Version 是驱动支持的上限，不代表已安装 CUDA Toolkit，需要区分对待。

2. cuDNN 版本必须与 CUDA Toolkit 精确匹配：cuDNN 9.x for CUDA 12.x 不能混用。安装前确认 nvcc --version 输出的版本号，下载对应变体。

3. 重启后驱动失效：部分服务器内核更新后 NVIDIA 驱动会被覆盖。建议锁定内核版本或使用 DKMS 模式安装驱动：

sudo ./NVIDIA-Linux-*.run --dkms

4. GPUStack 显存不够：部署 14B 模型需要至少 32GB 显存。如果只有 24GB 单卡，建议使用 4bit 量化（AWQ/GPTQ）或选择 7B 级别模型。

最终环境

组件	版本
操作系统	Ubuntu 22.04 LTS
NVIDIA Driver	550.x
CUDA Toolkit	12.4
cuDNN	9.x for CUDA 12
Docker	最新社区版
NVIDIA Container Toolkit	最新
GPUStack	最新稳定版
推理引擎	vLLM
部署模型	Qwen2.5-7B-Instruct / Qwen2.5-14B-Instruct

总结

生产环境的 GPU 算力搭建最核心的一点是：版本对齐。驱动、CUDA Toolkit、cuDNN 三者之间有严格的版本依赖关系，任何一个不匹配都会导致推理引擎启动失败。GPUStack 的优势在于把模型部署和推理管理抽象成统一 API，让开发者不需要关心底层的引擎切换和显存调度——装好环境后剩下的就是 curl 调用了。