保姆级避坑指南：在Ubuntu 22.04上用LLaMA-Factory训Qwen2.5，从环境配置到解决多卡OOM

最近在折腾Qwen2.5大模型训练的朋友们，想必都遇到过那个令人头疼的OOM（Out of Memory）问题。特别是当你手握8张RTX 4090这样的顶级显卡，却连14B参数的模型都跑不起来时，那种挫败感简直难以言表。今天我就来分享一套完整的解决方案，从零开始带你搞定Ubuntu 22.04下的LLaMA-Factory环境配置，直到成功解决多卡训练时的显存不足问题。

1. 环境准备：打造稳定的大模型训练基地

1.1 系统与硬件检查

首先确认你的Ubuntu 22.04系统已经正确识别所有GPU设备：

nvidia-smi

理想情况下，你应该能看到类似这样的输出：

+---------------------------------------------------------------------------------------+
| NVIDIA-SMI 535.104.05             Driver Version: 535.104.05   CUDA Version: 12.2     |
|-----------------------------------------+----------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |         Memory-Usage | GPU-Util  Compute M. |
|                                         |                      |               MIG M. |
|=========================================+======================+======================|
|   0  NVIDIA GeForce RTX 4090        On  | 00000000:01:00.0 Off |                  Off |
|  0%   38C    P8              25W / 450W |      0MiB / 24564MiB |      0%      Default |
|                                         |                      |                  N/A |
+-----------------------------------------+----------------------+----------------------+

表：关键硬件参数检查清单

检查项	预期值	备注
GPU数量	8	根据实际卡数调整
单卡显存	≥24GB	RTX 4090标准配置
系统内存	≥512GB	建议配置
CUDA版本	12.x	与PyTorch版本匹配

1.2 Python环境配置

推荐使用conda创建隔离的Python环境：

conda create -n qwen_train python=3.10 -y
conda activate qwen_train

安装基础依赖时最容易踩坑的就是PyTorch版本。经过多次测试，我推荐以下组合：

pip install torch==2.1.0 torchvision==0.16.0 torchaudio==2.1.0 --index-url https://download.pytorch.org/whl/cu121

注意：不要直接pip install torch，这可能会安装不兼容的版本导致后续问题

2. LLaMA-Factory的"正确打开方式"

2.1 源码获取与依赖安装

直接从GitHub克隆最新代码：

git clone https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory
pip install -e .

这里有几个常见陷阱：

• 不要使用pip install llamafactory，必须从源码安装
• 安装后务必检查accelerate版本（建议0.27.2）
• 确保deepspeed已正确安装：pip install deepspeed

2.2 模型下载与准备

以Qwen2.5-14B为例，建议使用官方提供的模型权重：

git lfs install
git clone https://huggingface.co/Qwen/Qwen2.5-14B-Instruct

下载完成后检查模型文件结构：

Qwen2.5-14B-Instruct/
├── config.json
├── generation_config.json
├── model-00001-of-00007.safetensors
├── ...
└── tokenizer.json

3. 多卡训练的核心配置技巧

3.1 为什么WebUI/CLI方式会OOM？

很多同学喜欢用LLaMA-Factory提供的Web界面或命令行工具启动训练，但在多卡场景下这会导致显存分配不均。根本原因在于：

• WebUI/CLI无法精细控制各GPU的显存使用
• 默认配置可能将所有模型参数复制到每张卡上
• 缺乏有效的显存优化策略（如ZeRO-3）

3.2 正确的启动脚本配置

创建run_train.sh文件，内容如下：

#!/bin/bash

CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 accelerate launch \
    --config_file configs/accelerate/zero3.yaml \
    src/train.py \
    --deepspeed ds_config_zero3.json \
    --stage sft \
    --do_train \
    --model_name_or_path ./Qwen2.5-14B-Instruct \
    --finetuning_type lora \
    --template qwen \
    --dataset_dir data \
    --dataset alpaca_zh_demo \
    --cutoff_len 1024 \
    --learning_rate 5e-05 \
    --num_train_epochs 1 \
    --per_device_train_batch_size 1 \
    --gradient_accumulation_steps 4 \
    --lr_scheduler_type cosine \
    --max_grad_norm 1.0 \
    --logging_steps 10 \
    --save_steps 100 \
    --output_dir ./output \
    --fp16 \
    --plot_loss

关键参数解析：

• gradient_accumulation_steps: 通过梯度累积模拟更大batch size
• per_device_train_batch_size: 单卡batch size建议从1开始
• fp16: 混合精度训练节省显存

3.3 ZeRO-3配置的黄金法则

创建ds_config_zero3.json文件：

{
    "fp16": {
        "enabled": true,
        "loss_scale_window": 100
    },
    "optimizer": {
        "type": "AdamW",
        "params": {
            "lr": "auto",
            "betas": "auto",
            "eps": "auto"
        }
    },
    "zero_optimization": {
        "stage": 3,
        "offload_optimizer": {
            "device": "cpu",
            "pin_memory": true
        },
        "offload_param": {
            "device": "cpu",
            "pin_memory": true
        },
        "overlap_comm": true,
        "contiguous_gradients": true,
        "stage3_max_live_parameters": 1e9,
        "stage3_param_persistence_threshold": 1e5
    },
    "train_batch_size": "auto",
    "train_micro_batch_size_per_gpu": "auto"
}

重点调整项：

• stage3_max_live_parameters: 控制同时驻留GPU的参数数量
• stage3_param_persistence_threshold: 参数持久化阈值
• pin_memory: 启用可以提升CPU-GPU传输效率

4. 实战排错与性能优化

4.1 常见错误排查清单

遇到OOM时，按照以下步骤检查：

1. 确认nvidia-smi显示所有GPU都被利用
2. 检查deepspeed日志中的显存分配情况
3. 逐步尝试以下调整：
   • 减小per_device_train_batch_size
   • 增加gradient_accumulation_steps
   • 尝试bf16代替fp16（需要硬件支持）
   • 调整stage3_param_persistence_threshold

4.2 性能优化技巧

经过多次实验，我总结出这些有效策略：

• 梯度检查点：在训练脚本中添加--gradient_checkpointing可节省约30%显存
• 激活值压缩：在ds_config_zero3.json中添加：

  "activation_checkpointing": {
      "partition_activations": true,
      "contiguous_memory_optimization": true
  }
  

• 数据加载优化：使用--dataloader_num_workers 4加速数据加载

4.3 监控与调优工具

推荐使用这些工具实时监控训练过程：

1. GPU监控：

   watch -n 1 nvidia-smi
   

2. 系统资源监控：

   htop
   

3. 训练过程可视化：

   tensorboard --logdir ./output/runs
   

在实际项目中，我发现最有效的显存优化组合是：ZeRO-3 + 梯度检查点 + fp16混合精度。这套配置能让8张4090顺利训练14B模型，batch size还能保持在2左右。