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运行库
pip install torch==2.3.1 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
# cu118 后缀
pip install torch==2.3.1 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

• torch CPU版（无 CUDA ）

pip install torch==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 | grep nvidia-cuda

# 输出
	nvidia-cuda-cupti-cu12    12.1.105
	nvidia-cuda-nvrtc-cu12    12.1.105
	nvidia-cuda-runtime-cu12  12.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 / 你的虚拟环境：

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