Alauda Container Platform
简体中文

CUDA 驱动与运行时兼容性

目录

分层架构与核心概念

cuda rt

1. CUDA Runtime API 层

技术定位

  1. 功能范围：为开发者提供高层抽象接口，封装核心 GPU 操作（内存分配、流管理、内核启动等）
  2. 版本绑定：由构建时使用的 CUDA Toolkit 版本决定（例如 CUDA 12.0.1）

版本检测方法

# Python 环境检测（推荐优先方法）
pip list | grep cuda
conda list |grep cuda 
# 示例输出：cu121  # cu121 表示 CUDA 12.1 环境

# 系统级运行时库检测
find / -name "libcudart*"
# cudart 表示 cuda runtime
# 示例输出:
/usr/local/cuda-12.4/targets/x86_64-linux/lib/libcudart.so.12
/usr/local/cuda-12.4/targets/x86_64-linux/lib/libcudart.so.12.4.127
表示 CUDA 12.4

如果发现多个库版本，应检查程序实际使用的版本，如 PATH、LD_LIBRARY_PATH 或其他程序设置

env |grep PATH
# 示例输出：
LIBRARY_PATH=/usr/local/cuda/lib64/stubs
LD_LIBRARY_PATH=/usr/local/nvidia/lib:/usr/local/nvidia/lib64
PATH=/go/bin:/usr/local/go/bin:/usr/local/nvidia/bin:/usr/local/cuda/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
# 表示你的 cuda 程序使用的是 lib 路径顺序中的第一个库

2. CUDA Driver API 层

技术定位

  1. 功能范围：低层接口，直接与 GPU 硬件交互，负责指令翻译和硬件资源调度
  2. 版本绑定：由 NVIDIA 驱动版本决定，遵循 SemVer 规范

版本检测方法

nvidia-smi
# 示例输出：
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 550.144.03             Driver Version: 550.144.03     CUDA Version: 12.4     |
|-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA A30                     Off |   00000000:00:0B.0 Off |                    0 |
| N/A   31C    P0             28W /  165W |   10195MiB /  24576MiB |      0%      Default |
|                                         |                        |             Disabled |
+-----------------------------------------+------------------------+----------------------+

版本兼容矩阵与约束

物理 GPU 部署 - 核心兼容原则

首先参考 NVIDIA 官方声明，基本约束为

  1. 驱动版本必须始终 ≥ 运行时版本
  2. NVIDIA 官方保证 向后兼容 1 个主版本（例如 CUDA Driver 12.x 支持 Runtime 11.x）
  3. 跨两个主版本兼容（例如 Driver 12.x 与 Runtime 10.x）既不官方支持也不推荐

部署 cuda 程序时，请遵守基本约束

正式规则

+ 强制：驱动版本 ≥ 运行时版本
+ 推荐：驱动主版本 - 运行时主版本 ≤ 1
- 阻断：驱动版本 < 运行时版本 → 可能触发 CUDA_ERROR_UNKNOWN(999)
- 不稳定：驱动主版本 - 运行时主版本 > 1 → 应用可能异常

虚拟化场景增强（HAMI/GPU-Manager）

使用 GPU-Manager 或 HAMI 等虚拟 GPU 方案时，除遵守上述基本约束外，还必须满足以下额外约束：

版本要求

1. 虚拟 GPU 方案基线版本 ≥ 运行时版本
2. 运行时主版本 = 驱动主版本 = 基线主版本

GPU-Manager 特别说明： 我们实现了部分跨 1 主版本兼容（例如基线 12.4 支持 vLLM 11.8），但这需要针对每个应用进行 hook 调整，需逐案分析。

部署最佳实践

推荐策略

• 新 GPU 集群规划时，建议采用较新 CUDA 版本（如 CUDA 12.x）作为驱动和运行时版本

旧系统替代方案

1. 物理 GPU 调度或 GPU-Manager 整卡分配

整卡调度提供与物理 GPU 访问等效的原生兼容性
GPU-Manager 可通过设置 tencent.com/vcuda-core 为 100 的正整数倍（如 100、200、300）启用整卡模式

resources:
  limits:
    tencent.com/vcuda-core: "100"

2. 节点标签策略

根据支持的驱动 CUDA 版本为节点打标签：

node_labels:
  cuda-major-version: "12"
  cuda-minor-version: "4"

表示该节点为 cuda 12.4

在部署时配置调度亲和性：
可根据程序所需的 cuda 运行时版本设置 cuda-major-version 和 cuda-minor-version

apiVersion: apps/v1
kind: Deployment
metadata:
  name: cuda-app
spec:
  template:
    spec:
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
            - matchExpressions:
              - key: cuda-major-version
                operator: In
                values: ["12"]
              - key: cuda-minor-version
                operator: Gt
                values: ["2"]

3. 运行时版本升级

旧版 CUDA Runtime 可能存在安全漏洞（CVE）且不支持新 GPU 特性，优先升级至 CUDA 12.x。

NVIDIA 推荐同时升级驱动和运行时
upgrade both

故障排查手册

常见错误代码

错误代码描述推荐操作
CUDA_ERROR_INVALID_IMAGE驱动与运行时不兼容使驱动版本与容器 CUDA 版本保持一致
CUDA_ERROR_ILLEGAL_ADDRESS虚拟内存违规（版本不匹配常见）核实运行时与基线约束是否符合
CUDA_ERROR_UNSUPPORTED_PTX_VERSIONPTX 指令集不匹配使用显式 -arch=sm_xx 重新编译