UnslothAI项目Blackwell架构兼容性指南

概述

本文主要介绍如何在NVIDIA Blackwell架构（sm100+）GPU上正确配置UnslothAI项目运行环境。Blackwell架构需要所有依赖库都使用CUDA 12.8进行编译，这对环境配置提出了特定要求。

核心依赖说明

在Blackwell架构上运行UnslothAI项目，需要特别注意以下几个核心库的版本和编译要求：

1. bitsandbytes：已提供CUDA 12.8预编译版本，可直接安装
2. triton：需要3.3.1及以上版本
3. PyTorch：必须从特定源安装CUDA 12.8版本
4. vllm：建议使用nightly版本
5. xformers：目前需要从源码编译

环境配置方法

使用uv工具安装（推荐）

uv是新一代Python包管理工具，比pip更快且能更好地处理依赖关系。

1. 安装uv并创建虚拟环境

curl -LsSf https://astral.sh/uv/install.sh | sh && source $HOME/.local/bin/env
mkdir unsloth-blackwell && cd unsloth-blackwell
uv venv .venv --python=3.12 --seed
source .venv/bin/activate

2. 安装vllm

uv pip install -U vllm --torch-backend=cu128 --extra-index-url https://wheels.vllm.ai/nightly

3. 安装Unsloth核心依赖

uv pip install unsloth unsloth_zoo bitsandbytes

4. 编译安装xformers

uv pip uninstall xformers
git clone --depth=1 https://github.com/facebookresearch/xformers --recursive
cd xformers
export TORCH_CUDA_ARCH_LIST="12.0"
python setup.py install

5. 更新triton

uv pip install -U triton>=3.3.1

6. 安装特定版本transformers

uv pip install -U transformers==4.52.4

使用conda/mamba安装

1. 安装conda/mamba并创建环境

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh
conda create --name unsloth-blackwell python==3.12 -y
conda activate unsloth-blackwell

后续步骤与uv安装类似，只需将uv pip替换为pip即可。

注意事项

1. transformers版本问题：4.53.0及以上版本会与Unsloth的推理功能产生兼容性问题，建议使用4.52.4版本

2. xformers编译：必须设置TORCH_CUDA_ARCH_LIST="12.0"环境变量

3. numpy版本：安装完成后可能需要降级numpy到2.2及以下版本

4. 环境验证：安装完成后，建议运行test_llama32_sft.py和test_qwen3_grpo.py测试脚本验证环境配置是否正确

常见问题解决方案

1. 推理输出不匹配：如果遇到推理输出与预期不符的情况，尝试在生成前禁用梯度检查点：

   model.disable_gradient_checkpointing()
   

2. CUDA版本冲突：确保所有库都使用CUDA 12.8版本，特别是PyTorch和vllm

3. 性能问题：如果遇到性能下降，检查是否所有库都正确编译支持sm100+架构

通过以上步骤，您应该能够在Blackwell架构GPU上成功配置UnslothAI项目的运行环境。如果在安装过程中遇到问题，建议对照官方提供的blackwell.requirements.txt检查各依赖版本是否匹配。