QLoRA 版本兼容问题

三方库 的 兼容版本

中等偏稳定、日常 QLoRA SFT 微调完全能用的折中组合：

pyhton 3.10 torch==2.3.1 transformers==4.41.2 bitsandbytes==0.43.1 trl==0.9.6 peft==0.11.1

• 依赖关系
  peft 依赖 transformers、torch
  trl 依赖 transformers、peft、torch、datasets
  bitsandbytes 依赖 torch
  这是代码里 import、底层调用的强制要求，没有对应库直接无法安装 / 导入。

CUDA 兼容说明

CUDA ( CUDA Toolkit ) 是 NVIDIA 写的完整 GPU 开发工具全家桶，包含 CUDA 运行时内核、编译器、调试工具，所有 GPU 底层计算逻辑都在这里，纯 C/C++。

CUDA 是 NVIDIA 给 显卡 做并行计算的 底层驱动平台；torch是唯一直接对接 CUDA 的库。

通俗的说：

CUDA ——连接着—— GPU（硬件）
Torch ——连接着—— CUDA（C++代码）
其他 py库 ——连接着——Torch（python 代码）

不同 CUDA 版本底层算子、内存接口、硬件指令不一样，所以所有包都要和 CUDA 配对，否则 GPU 无法运算、量化报错、训练直接崩溃。

版本对应

torch（和 CUDA 强绑定，根源）

1. PyTorch 分多个安装包：cu118/cu121/cu124，每个包内部内置了对应版本的 CUDA 运行时库；
2. torch 所有 GPU 操作（张量运算、模型前向/反向传播）都调用 CUDA API；
3. 硬性规则：
   • 你装的torch==2.3.1+cu121= 这个 torch 是基于 CUDA 12.1 编译；
   • 电脑显卡驱动版本必须 ≥ CUDA 12.1 最低驱动要求，否则识别不了GPU；
4. 其他库不自带CUDA，全部复用 torch 内置的 CUDA 环境。

版本安装

• torch 显卡版本 （带 CUDA ）

# cu121 后缀，代表内置CUDA12.1运行库pipinstalltorch==2.3.1 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121# cu118 后缀pipinstalltorch==2.3.1 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

• torch CPU版（无 CUDA ）

pipinstalltorch==2.3.1

版本查看

执行命令：

pip show torch

看Location上方的Version字段：

• GPU包：Version: 2.3.1+cu121（带+cu121后缀）
• CPU包：Version: 2.3.1（干净无后缀）

包名里的cu12代表大版本 12，对应 CUDA Toolkit 12.1。

只要 torch 版本带+cuXX后缀，执行下面命令一定能查到三个 cuda 运行库：

pip list|grepnvidia-cuda# 输出nvidia-cuda-cupti-cu1212.1.105 nvidia-cuda-nvrtc-cu1212.1.105 nvidia-cuda-runtime-cu1212.1.105

–index-url 讲解

• 拆开两部分理解
  --index-url是 pip 的参数，意思：指定包下载仓库地址
  后面https://download.pytorch.org/whl/cu121是 PyTorch 官方专属仓库路径

• 核心作用
  PyTorch 分很多版本：CPU、cu118、cu121、cu124，体积巨大，不放在默认pypi仓库，单独存在自己的服务器。
  所以 PyPI 上只上架了纯 CPU 版本 torch。
  pip 默认去公共仓库 PyPI（pypi.org）拉取包，所以 默认 就是拉取 CPU 版本的。
  加这一行的目的：告诉 pip：去这个CUDA12.1专属仓库下载适配CUDA12.1的GPU版torch，而不是下载纯CPU版本。

版本查看

一、查看系统安装的 CUDA Toolkit 版本（nvcc）

打开终端执行：

nvcc-V# 或者nvcc--version

输出示例：

nvcc: NVIDIA (R) Cuda compiler driver Copyright (c) 2005-2024 NVIDIA Corporation Built on Wed_Apr_17_19:19:09_PDT_2024 Cuda compilation tools, release 12.4, V12.4.131 Build cuda_12.4.r12.4/compiler.33887368_0

这里release 12.4就是 CUDA Toolkit 版本。

二、查看 显卡驱动 支持的最高 CUDA 版本（nvidia-smi）

nvidia-smi

右上角会显示CUDA Version: 12.5

重点：这里只是驱动支持的最大CUDA，不是你安装的CUDA Toolkit版本，二者可以不一致。

三、Python 代码查看当前 PyTorch 绑定的 CUDA

进入 python / 你的虚拟环境：

importtorch# 查看pytorch编译时用的cuda版本print(torch.version.cuda)# 查看是否可用cudaprint(torch.cuda.is_available())