Llama-Factory与PyTorch版本兼容性问题排查手册
在大模型微调日益普及的今天，越来越多开发者和企业选择使用高效、易用的一站式框架来加速定制化进程。Llama-Factory 正是在这一背景下迅速崛起的开源利器——它集成了数据预处理、模型加载、LoRA/QLoRA适配、分布式训练乃至可视化界面，几乎让'一键微调'成为现实。
但理想很丰满，现实却常因一个看似不起眼的问题而崩塌：PyTorch 版本不兼容。
你是否遇到过这样的场景？ 刚配置好环境，满怀期待地启动 QLoRA 训练脚本，结果报错：
ImportError: cannot import name 'libbitsandbytes_cuda11x' from 'bitsandbytes.cuda_setup'
或者更令人困惑的：
RuntimeError: Input type (torch.cuda.HalfTensor) and weight type (torch.cuda.BFloat16Tensor) should be the same
这些错误背后，往往不是代码写错了，也不是硬件不行，而是 底层依赖链中某个环节脱节了——尤其是 PyTorch 与其生态库（如 bitsandbytes）之间的版本协同出了问题。
Llama-Factory 虽然封装了复杂的训练流程，但它本质上是一个构建在 Hugging Face 生态之上的聚合体：底层靠 PyTorch 驱动张量计算，中间层通过 Transformers 加载模型结构，再往上由 PEFT 注入 LoRA 层，最后由 Accelerate 管理设备分布与精度策略。整个链条环环相扣，而 PyTorch 就是那个承上启下的核心枢纽。
一旦这个枢纽出现版本错配，轻则训练失败，重则显存泄漏、梯度异常甚至 GPU 崩溃。尤其当启用 QLoRA 这类依赖二进制扩展的量化技术时，对 PyTorch 的 ABI（应用二进制接口）、CUDA 编译版本和 Python 解释器都有严格要求。
那么，我们该如何系统性地规避这些问题？
从一次典型崩溃说起
设想你在本地机器上执行如下命令安装依赖：
pip install torch torchvision torchaudio --upgrade
这条命令看起来毫无问题，但它可能悄悄将你的 PyTorch 升级到了 2.4.0 或更高版本。紧接着你运行 Llama-Factory 的 QLoRA 示例脚本，却在模型加载阶段直接抛出异常：
ImportError: No module named 'bitsandbytes.cextension'
为什么会这样？
因为 bitsandbytes 是一个 C++/CUDA 编写的原生扩展库，其 .so 文件必须与 PyTorch 编译时所用的 CUDA 工具链、Python ABI 完全匹配。官方发布的 wheel 包通常只支持特定版本的 PyTorch（例如截至 2024 年中，bitsandbytes==0.43.1 仅正式支持到 torch==2.3.1），并不向后兼容最新版 PyTorch。
