Windows上利用WSL2与Unsloth微调Qwen模型实战指南

1. 别急着装环境：先搞清楚 Unsloth 在 Windows 上的运行边界

1.1 为什么是 Unsloth + Qwen 这个组合

在 Windows 上用 Unsloth 微调 Qwen，这个需求最近越来越多。很多朋友刚接触大模型微调，手里只有一台 Windows 电脑，又想用上开源最强的中文模型，那 Qwen 基本是绕不开的选择。而 Unsloth 的价值，就是把微调这件事的“门槛”狠狠往下拉：训练速度快很多，显存占用也能少一截。官方给的数据是最高能省 70% 显存、速度快 2 到 5 倍，实际跑下来虽然没这么夸张，但省 30%-50% 是有的。

至于为什么选 Qwen 而不是其他模型？一方面 Qwen 的中文能力在开源模型里确实能打，另一方面它对消费级显卡相对友好，7B、8B 这个量级的模型用 4bit 量化加 LoRA 就能在普通显卡上跑起来。所以组合思路很简单：Qwen 负责“会说话”，Unsloth 负责“跑得动”。

1.2 原生 Windows 与 WSL2 的选择：我的判断标准

先说结论：不要在原生 Windows 上折腾，直接上 WSL2。

Unsloth 官方支持的平台是 Linux，很多核心依赖（比如 Triton、bitsandbytes 的某些编译路径）在原生 Windows 上要么没有预编译包，要么编译环境不完整。第一次尝试的时候，我在原生 Windows 上装了 CUDA 版 PyTorch，也装上了 Unsloth，结果一跑训练就报 Triton 相关错误，折腾两天也没解决。后来切到 WSL2，一小时就全通了。

WSL2 本质是一个轻量虚拟机，但它对 NVIDIA GPU 的支持已经非常完善：Windows 驱动层直接透传 CUDA 能力，你在 WSL 里跑 nvidia-smi 就能看到显卡，不需要在 WSL 里单独装驱动。这相当于既保留了 Windows 的使用习惯，又拿到了 Linux 的兼容性。

显存方面，如果你是想跑 Qwen2.5-7B-Instruct 或 Qwen3-8B 这类模型，用 4bit 量化 + LoRA，显存 8GB 起步可以跑，但很紧张；12GB 以上比较舒服；16GB 基本能正常训练。显存不够的话，即便 Unsloth 再省内存，也可能卡在 batch size 等于 1 的尴尬局面，所以先确认自己的显卡型号和显存大小，再决定用 7B 还是 3B/4B 模型。

注意：检查显存可以用 nvidia-smi 命令，Windows 下直接在 CMD 或 PowerShell 里执行即可。如果命令不存在，说明驱动没装好，先去 NVIDIA 官网更新显卡驱动。

2. WSL2 + CUDA 环境搭建：最稳妥的 Windows 微调底座

2.1 开启 WSL2 并安装 Ubuntu

这一步比想象中简单。以管理员身份打开 PowerShell，执行：

powershell复制wsl --install -d Ubuntu-22.04

执行完之后系统会要求重启，重启后自动进入 Ubuntu 初始化流程，设置用户名和密码。注意，这不是一个“可选项”，而是一个真正的 Linux 环境，后面所有命令都在这套环境里执行。

如果你之前已经装过 WSL 但没有启用 WSL2，需要确认一下版本：

bash复制wsl -l -v

如果显示的是 VERSION 1，建议升级到 WSL2：

bash复制wsl --set-version <发行版名称> 2

WSL2 比 WSL1 的完整内核支持好很多，尤其是 CUDA 转发和内存管理，一定要用 WSL2。

2.2 在 WSL 内安装 Miniconda 和 CUDA 工具链

进入 WSL 终端后，先更新系统基础包：

bash复制sudo apt update && sudo apt upgrade -y

然后安装 Miniconda。我习惯用 Miniconda 管理 Python 环境，比直接用系统 Python 干净得多：

bash复制wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

安装完以后重新打开终端，创建微调专用的 Python 环境。目前 3.10 或者 3.11 都可以，Unsloth 和 PyTorch 都能很好支持：

bash复制conda create -n unsloth-env python=3.10 -y
conda activate unsloth-env

接下来安装 PyTorch。这里有个误区：很多人会先去装系统级 CUDA Toolkit，其实没必要。PyTorch 官方 pip 包自带 CUDA 运行库，只要 Windows 宿主机的显卡驱动面板里显示驱动版本够新，WSL 内部不需要额外装 CUDA Toolkit。我们只需要用 pip 安装对应 CUDA 版本的 PyTorch 即可：

bash复制pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

CUDA 版本选择上，统一用 cu121（CUDA 12.1）最省心，Unsloth 和 bitsandbytes 的预编译包大多也是基于这个版本测试的。安装后验证一下：

bash复制python -c "import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))"

如果输出 True 和显卡型号，说明 GPU 环境已经通了。这一步是最关键的分水岭，很多人后面报错，都是因为这里输出了 False 还在硬往下走。

2.3 安装基础编译工具：gcc 与 ninja

这是一步很容易被忽略的环境准备。Unsloth 在安装时会尝试编译一些扩展，如果系统里没有 C/C++ 编译器和 ninja，你会在安装阶段就看到一长串报错。

bash复制sudo apt install -y gcc g++ make ninja-build

装完后顺手把 packaging 库也装上，Unsloth 的某些依赖会用到：

bash复制pip install packaging

3. 安装 Unsloth 并下载 Qwen 模型：版本匹配是关键

3.1 Unsloth 的安装方式与坑点

安装 Unsloth 现在有两种主流方式。一种是直接 pip 安装稳定版：

bash复制pip install unsloth

另一种是用官方 GitHub 上的最新代码：

bash复制pip install "unsloth[colab-new] @ git+https://github.com/unslothai/unsloth.git"

我个人的经验是：如果只是常规微调，直接用 pip 稳定版就够。Unsloth 更新速度极快，但稳定版反而更可靠，因为热门教程和社区踩坑经验都是基于稳定版累积的。那些追新版本遇到的坑，很多时候是依赖冲突，不值得新手去踩。

安装完成后，建议把依赖库也装齐，后面训练时不会因为缺东西突然中断：

bash复制pip install accelerate peft trl bitsandbytes datasets

版本方面有一点要特别注意：bitsandbytes 的版本不能太旧，也不能太新。如果你在加载 4bit 模型时报错如 CUDA setup failed despite GPU being available，基本都是 bitsandbytes 跟你当前 PyTorch/CUDA 版本不匹配。我这边测试过的组合是 bitsandbytes==0.43.3 + torch 2.4.0 + CUDA 12.1，能稳定运行。你可以用 pip show bitsandbytes 看当前版本，必要时单独指定版本：

bash复制pip install bitsandbytes==0.43.3

3.2 下载 Qwen 模型到本地

模型推荐用 Qwen2.5-7B-Instruct 或者 Qwen3-8B。如果你显存只有 8GB，建议用 Qwen2.5-3B-Instruct 或 Qwen3-4B，否则后面 batch size 太小会影响效果。

最简单的方式是用 huggingface_hub 下载。如果网络环境访问 Hugging Face 不稳定，建议直接配置国内镜像环境变量：

bash复制export HF_ENDPOINT=https://hf-mirror.com

然后执行下载。比如下载 Qwen2.5-7B-Instruct：

bash复制pip install -U huggingface_hub
huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./qwen2.5-7b-instruct

如果你更喜欢 ModelScope，也可以：

bash复制pip install modelscope
modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir ./qwen2.5-7b-instruct

下载完成后，记得确认目录里有 config.json、model.safetensors 文件。缺文件会导致加载失败。

3.3 用 FastLanguageModel 验证加载

Unsloth 的核心 API 是 FastLanguageModel，加载模型之前先写个小脚本验证一下路径没问题：

python复制from unsloth import FastLanguageModel

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="./qwen2.5-7b-instruct",
    max_seq_length=2048,
    load_in_4bit=True,
)

print(model)
print("加载成功")

这里 load_in_4bit=True 表示用 4bit 量化加载，能大幅降低显存占用。只要这一步顺利跑通，整个微调工程就完成一半了。

4. 把业务语料构造成 Alpaca 格式：微调效果分水岭

4.1 为什么指令微调需要 Alpaca 格式

很多新手第一次微调，拿来的数据是几十个问答对，格式五花八门：有的是 CSV，有的是 Excel，有的直接是一段纯文本。这样的数据塞进训练脚本，基本等于白训练。

Unsloth 在微调指令模型时，标准做法是把数据组织成 Alpaca 格式的 JSON 或 JSONL，每一行长这样：

json复制{
  "instruction": "请根据给定的产品名称写一句宣传语。",
  "input": "无线降噪耳机",
  "output": "沉浸纯净声音，远离世界喧嚣。"
}

其中 input 可以留空，表示这是一个不需要额外输入的指令。模型训练时，会专门把 output 部分的 loss 计算出来，instruction 和 input 只作为上下文，不惩罚预测错误。这样模型才能学到“你问什么、我答什么”的映射关系，而不是把整段话当作文本生成。 格式一旦错了，模型很可能学会复读问题而不是回答问题。

4.2 一个转换脚本示例

假设你有一份 Excel 表格，里面是 问题、答案 两列。先用 pandas 读出来，转成 Alpaca JSONL：

python复制import pandas as pd
import json

df = pd.read_excel("qa_data.xlsx")

with open("train.jsonl", "w", encoding="utf-8") as f:
    for _, row in df.iterrows():
        item = {
            "instruction": row["问题"],
            "input": "",
            "output": row["答案"]
        }
        f.write(json.dumps(item, ensure_ascii=False) + "\n")

再按 9:1 随机切分成训练集和验证集，验证集不用太大，500 条里留 50 条就够：

python复制from datasets import load_dataset

dataset = load_dataset("json", data_files={"train": "train.jsonl"}, split="train")
dataset = dataset.train_test_split(test_size=0.1, seed=42)

print(dataset)

用 datasets 库的好处是后面可以直接传给 SFTTrainer，不需要自己写数据加载逻辑。

4.3 数据数量与质量的平衡

数据量这块，我测下来的感受是：500 条高质量的问答对就能看到明显效果，1000 到 3000 条效果比较理想，超过 5000 条后边际收益递减。 关键是质量比数量重要得多。

什么叫高质量数据？第一，问题和答案的口径要一致，别一会儿用客服回复的口气，一会儿用技术文档的口气；第二，答案长度要适中，如果训练集里都是几百字的长答案，模型之后回答问题也会啰嗦；第三，要去重，很多真实业务数据里大量重复问题，不去重反而会让模型对这些内容过拟合。

如果你手里的原始数据比较脏，建议先做一轮清洗：去掉空行、HTML 标签、特殊符号，再手动随机抽 50 条看一眼质量。

5. 训练脚本参数详解与 LoRA 配置：决定显存占用和效果的核心

5.1 一份可直接运行的微调脚本

下面这份脚本是我在 Windows + WSL2 上验证过的精简版本，可以保存为 train.py 直接运行：

python复制from unsloth import FastLanguageModel
import torch
from datasets import load_dataset
from trl import SFTTrainer
from transformers import TrainingArguments
from unsloth import is_bfloat16_supported

# 1. 加载模型
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="./qwen2.5-7b-instruct",
    max_seq_length=1024,
    load_in_4bit=True,
)

# 2. 配置 LoRA
model = FastLanguageModel.get_peft_model(
    model,
    r=16,
    target_modules=["q_proj","k_proj","v_proj","o_proj",
                    "gate_proj","up_proj","down_proj"],
    lora_alpha=16,
    lora_dropout=0,
    bias="none",
    use_gradient_checkpointing=True,
)

# 3. 准备数据集
dataset = load_dataset("json", data_files={"train": "train.jsonl"}, split="train")
dataset = dataset.train_test_split(test_size=0.1, seed=42)

# 4. 训练参数
training_args = TrainingArguments(
    output_dir="./qwen-finetuned",
    per_device_train_batch_size=2,
    per_device_eval_batch_size=2,
    gradient_accumulation_steps=4,
    num_train_epochs=3,
    learning_rate=2e-4,
    warmup_steps=50,
    logging_steps=10,
    eval_strategy="steps",
    save_strategy="epoch",
    save_total_limit=2,
    fp16=not is_bfloat16_supported(),
    bf16=is_bfloat16_supported(),
    optim="adamw_8bit",
    report_to="none",
)

# 5. 启动训练
trainer = SFTTrainer(
    model=model,
    tokenizer=tokenizer,
    train_dataset=dataset["train"],
    eval_dataset=dataset["test"],
    args=training_args,
    dataset_text_field="output",
    max_seq_length=1024,
)

trainer.train()

5.2 参数含义与显存估算

脚本里的每个参数都值得认真调一下，我整理成一张表：

显存估算大概是这样：Qwen2.5-7B-Instruct 用 4bit 量化后，模型本身约 5GB 左右。max_seq_length=1024、batch_size=2 时，训练峰值显存大约在 11-13GB。如果你的显卡是 8GB，需要把 max_seq_length 降到 512，batch_size 降到 1，同时把 gradient_accumulation_steps 调到 8，保存时关闭一些中间状态。

5.3 LoRA 参数选择经验

LoRA 的 r 值不是越大越好。我试过 r=64，训练慢一圈，效果提升并不明显。对绝大多数指令微调场景，r=16 是甜点值。 如果你数据集比较小（500 条以内），r=8 能减少过拟合。lora_alpha 我喜欢设成跟 r 相同，或者它的两倍，效果稳定。

另外，target_modules 最好把 Qwen 的注意力层和 MLP 层都选上，也就是脚本里那一串 _proj 模块。只训练部分层是可以省显存，但效果通常偏差，不推荐新手这样省。

6. 跑通训练：日志解读、Loss 曲线与常见崩溃处理

6.1 启动训练并观察日志

一切就绪后，运行：

bash复制python train.py

正常会看到类似这样的输出：

code复制{'loss': 1.2345, 'learning_rate': 1.8e-4, 'epoch': 0.01}

关注的指标就一个：loss。微调时 loss 不一定非要降到很低，重点是平稳下降然后收敛。如果数据比较小，loss 从 1.5 左右降到 0.8 就已经不错。如果发现 loss 在震荡、不下降，先检查是不是学习率太大，或者数据集里有太多脏数据。

训练日志里每个 step 会显示耗时，比如 0.85s/it。7B 模型在 4070Ti 上大概每步 0.8 到 1.5 秒，一个 epoch 500 条数据，大约 250 步（batch=2），跑 3 轮也就十几分钟到半小时，速度还是可以接受的。

6.2 常见报错和应对

我在 WSL 里踩过的坑，集中在下面几个：

CUDA out of memory
这是最常见的一个。报错提示里有 RuntimeError: CUDA out of memory。处理优先级：先降 per_device_train_batch_size 到 1，再降 max_seq_length，如果还不行就开 gradient_checkpointing（脚本里已经默认开了）。注意，即使 batch=1 还 OOM，多半是模型加载时没有真正 4bit，检查 load_in_4bit 是否生效。

bitsandbytes 报错
如果报错里有 Detected that PyTorch and LibTorch have different versions 或者 CUDA Setup failed，先重新安装匹配版本的 bitsandbytes，再不行就把 PyTorch 换成 cu121 版本。

Triton 编译报错
常见信息是 error: 'c10/cuda/CUDAStream.h' file not found 或者 No such file or directory。这基本是因为 WSL 里没有装 gcc / g++，退回第 2.3 节把编译工具装上。如果已经装了还报错，检查自己是不是在原生 Windows 里跑，而不是 WSL2。

数据集字段错误
ValueError: The instruction column... 这种报错说明数据集字段名跟脚本不一致。检查 JSONL 里字段是否叫 instruction/input/output，别用 question/answer 这种名字，除非你修改脚本里的映射。

6.3 推理测试与导出：验证效果并保存为 GGUF 或标准模型

训练完成后，先不要着急导出，加载一下 adapter 做推理测试：

python复制from unsloth import FastLanguageModel

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="./qwen2.5-7b-instruct",
    max_seq_length=1024,
    load_in_4bit=True,
)

model = FastLanguageModel.from_pretrained(
    model_name="./qwen-finetuned/checkpoint-xxx",  # 换成实际 checkpoint 路径
)

FastLanguageModel.for_inference(model)

inputs = tokenizer(["""请根据产品名写一句宣传语：无线降噪耳机"""], return_tensors="pt").to("cuda")
outputs = model.generate(**inputs, max_new_tokens=128)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

如果效果满意，再把 LoRA adapter 合并成完整模型并保存，方便后续用 vLLM 或 Ollama 部署：

python复制model.save_pretrained_merged("qwen-merged", tokenizer, save_method="merged_16bit")

这样会得到一个 16bit 精度的完整模型目录，可以用 transformers 直接加载。

最后分享一点个人感受：微调这件事，跑通环境不难，难的是数据。环境问题是“时间问题”，数据问题是“效果问题”。你花在清洗数据、整理格式上的每一分钟，最后都会在模型回答质量上体现出来。 如果微调后效果不好，先别急着改参数，回头看看训练集——多半是数据不够好。先用 100 条精挑细选的样本试跑通全流程，再逐步加数据，这样既省时间，也不会被错误参数带偏。