Ubuntu 上的 NVIDIA 驱动、CUDA 与 Fabric Manager

检查当前安装情况

确认是否已经安装了驱动，以及它来自哪里：

lspci -d 10de: | grep -Ei '3d controller|vga compatible'   # PCI 总线上的 GPU
nvidia-smi                                  # 如果没有加载驱动则会失败
cat /proc/driver/nvidia/version             # 已加载内核模块的版本
dpkg -l | grep -Ei 'nvidia|cuda' | awk '{print $2, $3}'   # 已安装的软件包
mokutil --sb-state                          # 是否已启用 Secure Boot？

nvidia-smi 的输出顶部会显示驱动版本和 CUDA Version。这第二个数字表示该驱动所能支持的最新 CUDA 版本，并不代表已经安装了对应的工具包。

如果已经有一个可正常工作、且适合您的技术栈的驱动，就保留它。如果要更换驱动，请先卸载旧的软件包，然后只从一个来源安装：混用 Ubuntu 自带的软件包、NVIDIA 的软件仓库和 .run 安装程序，是导致 GPU 环境损坏的常见原因。

安装驱动

NVIDIA 的 CUDA 软件仓库同时提供数据中心显卡和 GeForce 显卡的驱动。请使用开源内核模块（nvidia-open）进行安装：在 Blackwell 系列（B300、B200、RTX PRO 6000、RTX 5090、RTX 5080）上，NVIDIA 只支持开源模块，并在 Hopper 和 Ada Lovelace 系列上也推荐使用它。

sudo apt update
sudo apt install -y linux-headers-$(uname -r)

# 添加 NVIDIA 的 CUDA 软件仓库（x86_64；Arm64 服务器使用 sbsa）
distro=$(. /etc/os-release; echo "ubuntu${VERSION_ID//./}")   # ubuntu2204 或 ubuntu2404
wget https://developer.download.nvidia.com/compute/cuda/repos/$distro/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update

# 可选，推荐：安装前锁定驱动分支版本
sudo apt install -V nvidia-driver-pinning-<branch>

sudo apt install -V nvidia-open
sudo reboot

<branch> 是 NVIDIA 版本锁定页面上列出的驱动分支号。锁定分支可以避免 apt upgrade 在项目进行过程中把您切换到新的分支。从分支 590 开始，Ubuntu 的软件包名称中不再包含分支号，因此要锁定在某个分支上，就需要依靠这个锁定软件包。重启后，nvidia-smi 应该能列出所有 GPU。

另一种方式：Ubuntu 自带的软件包

Ubuntu 将相同的驱动打包为预编译、已签名的内核模块。启用 Secure Boot 时，建议优先选择这种方式：DKMS 在本地构建的模块不会用固件信任的密钥签名，注册这样的密钥还需要访问启动控制台。

sudo ubuntu-drivers list --gpgpu                 # 列出与这些 GPU 匹配的驱动
sudo ubuntu-drivers install --gpgpu              # 安装推荐的驱动
sudo apt install nvidia-utils-<branch>-server    # 该分支对应的 nvidia-smi
sudo reboot

在 Blackwell 系列 GPU 上，请确保选用的驱动是 -open 变体。只能使用其中一种来源，切勿两者混用。详情参见 Ubuntu Server 文档和 NVIDIA 的驱动安装指南。

需要自行编译代码时添加 CUDA 工具包

PyTorch wheel 包、vLLM 和 NGC 容器都自带 CUDA 库；宿主机只需要一个版本足够新、能兼容它们的驱动即可。只有在您自己编译 CUDA 代码时才需要安装工具包：例如使用 nvcc、编写自定义内核、运行 nccl-tests，或使用需要构建 CUDA 扩展的 Python 软件包。

sudo apt install -V cuda-toolkit                # 仓库中最新的 CUDA 版本
# 或安装固定版本：sudo apt install -V cuda-toolkit-<major>-<minor>
echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
nvcc --version

每个 CUDA 版本都要求一个最低驱动版本；例如 CUDA 13.x 就需要 580 系列或更新的驱动。CUDA 发行说明列出了每个版本对应的具体要求。

持久性模式

如果不启用持久性模式，驱动会在最后一个进程退出时清空 GPU 状态，并在下一个进程启动时重新构建，这会拖慢每个短任务的启动速度。在服务器上应始终保持开启：

nvidia-smi --query-gpu=index,persistence_mode --format=csv
sudo systemctl enable --now nvidia-persistenced
sudo nvidia-smi -pm 1

相比旧式的驱动内置设置，NVIDIA 更推荐使用持久化守护进程（nvidia-persistenced）；该进程运行时，nvidia-smi -pm 1 也会通过它来执行。如果重启后查询结果仍显示 Disabled，请运行 systemctl cat nvidia-persistenced：某些软件包会用 --no-persistence-mode 参数启动该守护进程。可以通过 sudo systemctl edit nvidia-persistenced 覆盖这一设置（添加一个空的 ExecStart= 行，再写入去掉该参数的原始命令），然后重启服务。

HGX 服务器：Fabric Manager 与 NVLink

在 8 块 GPU 的 HGX 主板（H100、H200、B200、B300）上，各个 GPU 之间通过 NVSwitch 芯片互连，这些芯片由 NVIDIA Fabric Manager 负责配置。如果没有它，nvidia-smi 仍能列出所有 GPU，但 CUDA 程序会在启动时报错误 802，“system not yet initialized”（系统尚未初始化，即 cudaErrorSystemNotReady）。

Fabric Manager 的版本必须与驱动版本完全一致。请从同一个软件仓库安装，让两者保持在同一个分支，并同时升级。

cat /proc/driver/nvidia/version                               # 驱动版本
apt-cache search --names-only 'fabricmanager|nvlsm|nvlink5'   # 您的软件仓库中提供的相关软件包

• NVIDIA 软件仓库，分支 590 及以后版本（包名不再带分支号，由锁定软件包固定在您所选的分支上）：sudo apt install -V nvidia-fabricmanager
• NVIDIA 软件仓库，更早的分支：sudo apt install -V cuda-drivers-fabricmanager-<branch>
• Ubuntu 自带的软件包：sudo apt install nvidia-fabricmanager-<branch> libnvidia-nscq-<branch>

HGX B200 和 B300 使用第四代 NVSwitch，还需要 NVLink 子网管理器（nvlsm）、libibumad3、infiniband-diags 以及 ib_umad 内核模块；在使用带分支号的软件包时，nvlink5-<branch> 会同时安装 Fabric Manager 和 NVLSM。Fabric Manager 指南列出了每一代对应的具体软件包。

# 仅适用于 HGX B200 / B300
sudo apt install -V nvlsm libibumad3 infiniband-diags
sudo modprobe ib_umad
echo ib_umad | sudo tee /etc/modules-load.d/ib_umad.conf

# 适用于所有 HGX 主板
sudo systemctl enable --now nvidia-fabricmanager
systemctl status nvidia-fabricmanager --no-pager
dpkg -l | grep -i fabricmanager                  # 是否与驱动版本一致？
nvidia-smi -q -i 0 | grep -i -A 2 fabric         # 应显示 State: Completed, Status: Success

检查 NVLink

nvidia-smi topo -m     # 在 HGX 主板上，每一对 GPU 都会显示 NV#（HGX H100 上为 NV18）
nvidia-smi nvlink -s   # 每条链路的状态和速度
nvidia-smi nvlink -e   # 每条链路的错误计数

如果 HGX 主板上两块 GPU 之间显示的是 PIX、PXB、NODE 或 SYS 之类的条目，说明这一对 GPU 没有使用 NVLink。要测量带宽，请按照多 GPU 一文所述运行 nccl-tests。

MIG：将一块 GPU 拆分为多个实例

Multi-Instance GPU（多实例 GPU）可以将一块 GPU 拆分成多个相互隔离的实例，每个实例都有自己独立的显存和计算资源，例如可以用来并行提供多个小模型的推理服务。在 CryptGPU 提供的产品线中：

sudo nvidia-smi -i 0 -mig 1                  # 在 GPU 0 上启用 MIG 模式（请先停止其上运行的任务）
nvidia-smi mig -i 0 -lgip                    # 列出该 GPU 提供的实例配置及其 ID
sudo nvidia-smi mig -i 0 -cgi <id>,<id> -C   # 创建 GPU 实例及其计算实例
nvidia-smi -L                                # 列出 MIG 设备及其 UUID

sudo nvidia-smi mig -i 0 -dci && sudo nvidia-smi mig -i 0 -dgi   # 删除这些实例
sudo nvidia-smi -i 0 -mig 0                  # 恢复为一整块 GPU

使用 CUDA_VISIBLE_DEVICES=MIG-<uuid> 可以让某个进程指向特定实例。在 Hopper 和 Blackwell 上，MIG 模式及其实例在重启后不会保留；需要在每次启动时重新创建，例如使用 NVIDIA 的 mig-parted。MIG 用户指南列出了所有配置文件。

常见错误及修复方法

“NVIDIA-SMI has failed because it couldn’t communicate with the NVIDIA driver”（NVIDIA-SMI 无法与驱动通信）

这说明内核模块没有被加载。常见原因是内核版本较新但缺少匹配的头文件，导致 DKMS 无法构建模块；或者是 Secure Boot 拒绝了未签名的模块。

lsmod | grep nvidia
dkms status
sudo dmesg | grep -iE 'nvidia|nvrm' | tail -n 20
mokutil --sb-state
sudo apt install -y linux-headers-$(uname -r) && sudo dkms autoinstall && sudo reboot

“Failed to initialize NVML: Driver/library version mismatch”（驱动与库版本不匹配）

这通常是因为驱动软件包已经升级，但旧的内核模块仍在加载中。重启即可解决。为避免在任务运行期间发生这种情况，请锁定驱动分支，只在任务之间进行升级。

“CUDA driver version is insufficient for CUDA runtime version”（驱动版本低于运行时要求）

说明该程序或容器所构建使用的 CUDA 版本，比您当前驱动所支持的版本更新（可以对比 nvidia-smi 显示的 CUDA Version）。请升级驱动，或改用针对更旧 CUDA 版本构建的版本。

HGX 服务器上的错误 802

说明 Fabric Manager 没有运行、启动失败，或者版本与驱动不匹配。请检查 systemctl status nvidia-fabricmanager 和 sudo journalctl -u nvidia-fabricmanager 的输出。

Xid 错误

驱动会在内核日志中以 NVRM: Xid 形式的行报告 GPU 故障：

sudo dmesg -T | grep -i xid

如果硬件类 Xid（48、64、74、79 或 95）在重启后仍反复出现，请运行 sudo nvidia-bug-report.sh，并通过联系表单发送相关 Xid 日志。NVIDIA 的 Xid 目录解释了每个错误代码的含义。