安装与硬件支持矩阵

Unsloth 的核心优势是手写 Triton kernel 加速，这意味着对 GPU 硬件 / CUDA / PyTorch / Triton 版本要求非常具体。 本章给你一份"哪些 GPU 能用、用哪条命令装"的全套指南。

2.1支持的 GPU 矩阵

Unsloth 通过手写 Triton kernel 提速，不是所有 GPU 都支持。看 unsloth/_gpu_init.py 检测逻辑：

2.2三条安装路线

路线 A：官方 install.sh / install.ps1（推荐）

仓库自带 install.sh（macOS / Linux）和 install.ps1（Windows），是当前 v2026 后的标准入口：

# macOS / Linux / WSL
curl -fsSL https://unsloth.ai/install.sh | sh

# Windows PowerShell
irm https://unsloth.ai/install.ps1 | iex

它会做这些事：

1. 检测 OS / Python / CUDA 版本；
2. 建一个独立的 ~/.unsloth/ 目录；
3. 装 PyTorch（按 CUDA 选 wheel）；
4. 装 Triton（CUDA 上是 triton，Windows 是 triton-windows）；
5. 装 unsloth + unsloth-zoo（依赖库）；
6. 安装 Unsloth Studio（可选 GUI）；
7. 建 unsloth CLI shim。

常用 flag：

--local           # 用当前目录的源码装（开发者用）
--no-torch        # 跳过 PyTorch（仅装 GGUF inference 部分）
--python 3.12     # 强制 Python 版本

路线 B：纯 pip 安装

不想用 install.sh，直接 pip：

# 先装好 PyTorch（按 CUDA 12.x 选）
pip install torch==2.5.1 --index-url https://download.pytorch.org/whl/cu126

# 装 Triton
pip install triton             # Linux / WSL
# 或 Windows:
pip install triton-windows

# 装 Unsloth
pip install unsloth

# 可选：装最新版（commit 级）
pip install --upgrade --force-reinstall --no-cache-dir \
  "unsloth[colab-new] @ git+https://github.com/unslothai/unsloth.git"

路线 C：从本地 repo 装

cd /Users/zjw/Documents/LLM/train/repos/unsloth
pip install -e .

2.3关键依赖版本

2.4验证安装

# 1. import 不报错
python -c "import unsloth; print(unsloth.__version__)"

# 2. CUDA + Triton 都识别
python -c "
import torch, triton
print('PyTorch:', torch.__version__, 'CUDA:', torch.version.cuda)
print('Triton:', triton.__version__)
print('GPU:', torch.cuda.get_device_name(0))
"

# 3. 跑一个最小的 FastLanguageModel
python -c "
from unsloth import FastLanguageModel
model, tokenizer = FastLanguageModel.from_pretrained(
    'unsloth/Llama-3.2-1B',
    max_seq_length=2048,
    load_in_4bit=True,
)
print('Model OK')
"

第 3 条会下载一个 1B 模型（约 800 MB），是验证 Triton kernel 能用的"金标准"。

2.5显存矩阵（典型微调）

对照"4090 24 GB"这条硬件线，QLoRA + Unsloth 让你能训到 70B（极限），常规训 8B-13B 完全宽松。

2.6Colab / Kaggle 免费档

Unsloth 大量营销做在免费 GPU 上微调大模型这件事上。官方维护了 50+ 个 Colab notebook：

Colab notebook 入口

仓库 tests/notebooks/ 下有大量参考 notebook，对应每个模型 + 每种训练算法：

tests/notebooks/
  ├── Llama3_(8B)-Alpaca.ipynb              # 经典 SFT
  ├── Llama3_(8B)-ORPO.ipynb                # 偏好对齐
  ├── Llama3_(8B)-Inference.ipynb           # 推理
  ├── Qwen3_(8B)-GRPO.ipynb                 # GRPO RL
  ├── Gemma-3_(9B)-Vision.ipynb             # 多模态
  ├── ...

Colab 直接打开（仓库 README 列了 URL），运行环境 install + 数据预处理 + 训练全包，不要去自己 pip install。

2.7常见安装错误

2.8装完后第一件事

跑 tests/notebooks/Llama3_(8B)-Alpaca.ipynb 第一个 cell，确认能下模型 + Triton 能 compile：

from unsloth import FastLanguageModel
import torch

max_seq_length = 2048
dtype = None  # 自动选 bf16 / fp16
load_in_4bit = True

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = "unsloth/llama-3-8b-bnb-4bit",
    max_seq_length = max_seq_length,
    dtype = dtype,
    load_in_4bit = load_in_4bit,
)
print("Unsloth setup OK!")

如果这一段能跑 30 秒内打印 "Unsloth setup OK!"，整套环境就 ready 了。

2.9这章带走的

• Unsloth 是NVIDIA-only + 单 GPU（多 GPU 要 Pro 或社区 patch）；
• 消费卡（4090 / 3090）是营销主战场，Ampere+ 都能用；
• 装法首选 curl install.sh；纯 pip 也行但要先装好 PyTorch + Triton；
• 不要手动升级 transformers，跟着 Unsloth pin 走；
• 跑通 FastLanguageModel.from_pretrained = 环境 ready；
• 免费档（Colab T4）能训 Llama-3-8B QLoRA，是 Unsloth 的"看家戏"。