LLaMA-Factory 分布式训练实践指南

最后验证安装状态：

llama_factory-cli version

如果能正常输出版本号，则说明框架已就绪。

检查分布式训练依赖

在启动前务必确认以下三项是否全部满足：

# 检查 PyTorch 分布式支持
python -c "import torch; print(f'Distributed available: {torch.distributed.is_available()}')"
# 检查 DeepSpeed 是否可用
deespeed --version || echo "DeepSpeed not installed"
# 检查 FSDP 支持（需 PyTorch >= 2.0）
python -c "try:
    from torch.distributed.fsdp import FullyShardedDataParallel as FSDP
    print('FSDP supported')
except ImportError:
    print('FSDP not supported')"

任一检查失败都可能导致训练中途崩溃，尤其是 FSDP 在旧版 PyTorch 中不可用。

三种分布式引擎怎么选？一场关于'显存 vs 性能'的权衡

LLaMA-Factory 支持三种主流并行策略，每种都有其适用边界。理解它们的本质差异，才能做出合理选择。

我的经验是：

• 快速验证想法 → 用 DDP
• 显存不够 → 上 DeepSpeed
• 想省心长期维护 → 优先考虑 FSDP

特别是当你计划在未来迁移到生产集群时，FSDP 的原生集成优势会越来越明显。

单机多卡实战：从小试牛刀到稳定压测

大多数用户的第一个分布式任务都在单机上完成。我们分别演示三种引擎的实际操作流程。

使用 DDP 启动 Qwen-7B 的 LoRA 微调

DDP 是最简单的选项，无需额外配置文件，只需通过 torchrun 指定 GPU 数量即可：

torchrun --nproc_per_node=4 \
src/train_bash.py \
--stage sft \
--do_train \
--model_name_or_path /models/Qwen-7B \
--dataset alpaca_en \
--finetuning_type lora \
--output_dir ./output/qwen-7b-lora-ddp \
--per_device_train_batch_size 2 \
--gradient_accumulation_steps 8 \
--learning_rate 2e-4 \
--num_train_epochs 3 \
--lr_scheduler_type cosine \
--max_grad_norm 1.0 \
--logging_steps 10 \
--save_steps 500 \
--fp16 \
--ddp_find_unused_parameters false \
--plot_loss

关键点说明：

• --ddp_find_unused_parameters false 可显著减少通信开销；
• 若模型中有未参与梯度更新的模块（如冻结层），必须关闭此选项；
• 开启 --fp16 可节省约 40% 显存，且对精度影响极小。

该配置下，Qwen-7B 在 4×A10 上每卡显存占用约为 18GB，训练速度可达 ~920 tokens/s。

DeepSpeed + ZeRO-2 Offload：让 Baichuan2-13B 在消费级显卡上跑起来

对于 13B 级别以上的模型，显存成为瓶颈。此时 DeepSpeed 的 ZeRO 技术可以大幅降低内存压力。

第一步：编写配置文件 ds_z2_offload.json

{
  "train_batch_size": 64,
  "train_micro_batch_size_per_gpu": 4,
  "gradient_accumulation_steps": 4,
  "fp16": {
    "enabled": true
  },
  "zero_optimization": {
    "stage": 2,
    "offload_optimizer": {
      "device": "cpu",
      "pin_memory": true
    },
    "allgather_partitions": true,
    "allgather_bucket_size": 5e8,
    "overlap_comm": true,
    "reduce_scatter": true,
    "reduce_bucket_size": 5e8,
    "contiguous_gradients": true
  },
  "optimizer": {
    "type": "AdamW",
    "params": {
      "lr": 2e-4,
      "betas": [0.9, 0.999],
      "eps": 1e-8,
      "weight_decay": 0.01
    }
  },
  "scheduler": {
    "type": "WarmupCosineLR",
    "params": {
      "warmup_min_lr": 0,
      "warmup_max_lr": 2e-4,
      "warmup_num_steps": 100,
      "total_num_steps": 10000
    }
  },
  "gradient_clipping": 1.0,
  "wall_clock_breakdown": false,
  "zero_allow_untested_optimizer": true
}

其中 "offload_optimizer" 将优化器状态卸载到 CPU，配合 pinned memory 提升数据传输效率。

第二步：启动训练

deepeed --num_gpus=4 \
src/train_bash.py \
--stage sft \
--do_train \
--model_name_or_path /models/Baichuan2-13B-Base \
--dataset medical_qa_zh \
--finetuning_type lora \
--output_dir ./output/baichuan2-13b-lora-deepspeed \
--per_device_train_batch_size 1 \
--gradient_accumulation_steps 16 \
--learning_rate 2e-4 \
--num_train_epochs 3 \
--deepspeed ./ds_z2_offload.json \
--fp16 \
--plot_loss

效果惊人：原本每卡需 ~26GB 显存才能加载的模型，现在仅需 ~14GB，使得 13B 模型可在 4×A10（24GB）上顺利训练。

FSDP + torch.compile：面向未来的高性能组合

FSDP 是 PyTorch 2.0 推出的官方分片方案，天然支持 torch.compile 加速，在多机场景中表现尤为出色。

torchrun --nproc_per_node=4 \
src/train_bash.py \
--stage sft \
--do_train \
--model_name_or_path /models/ChatGLM3-6B \
--dataset finance_qa_zh \
--finetuning_type lora \
--output_dir ./output/chatglm3-6b-lora-fsdp \
--per_device_train_batch_size 4 \
--gradient_accumulation_steps 4 \
--learning_rate 5e-5 \
--num_train_epochs 3 \
--lr_scheduler_type cosine \
--fp16 \
--fsdp "full_shard auto_wrap" \
--fsdp_transformer_layer_cls_to_wrap "GLMBlock" \
--fsdp_use_orig_params true \
--compile \
--plot_loss

几个关键参数解读：

• full_shard：权重、梯度、优化器状态全部分片；
• auto_wrap：自动识别 Transformer 层进行包装；
• fsdp_use_orig_params=true：这是使用 LoRA 的必要条件，否则会因参数注册失败报错；
• --compile：启用 torch.compile，实测可带来 15%-25% 的前向加速。

在双机共 8×RTX3090 的环境下，该配置达到 ~810 tokens/s，显存仅占 ~10GB/卡，性价比极高。

多机协同：突破单机天花板

当模型规模超过 30B，单台服务器已无法承载。这时需要借助多机分布式训练。

准备工作清单

1. 所有机器处于同一内网，可通过主机名或 IP 直接访问；
2. 统一 CUDA、PyTorch、LLaMA-Factory 版本；
3. 模型路径和数据集路径一致（推荐 NFS/SMB 共享存储）；
4. 主节点能免密 SSH 登录所有从节点；
5. 防火墙开放主控端口（默认 29500）；
6. 各节点时间同步（NTP 服务）。

任意一项缺失都会导致连接失败或训练中断。

DDP 多机训练：两步走策略

主节点启动命令（node_rank=0）

torchrun \
--nnodes=2 \
--node_rank=0 \
--master_addr=worker01 \
--master_port=29500 \
--nproc_per_node=4 \
src/train_bash.py \
--stage sft \
--do_train \
--model_name_or_path /shared/models/Qwen-14B \
--dataset law_qa_zh \
--finetuning_type lora \
--output_dir /shared/output/qwen-14b-lora-ddp-multi \
--per_device_train_batch_size 2 \
--gradient_accumulation_steps 8 \
--learning_rate 2e-4 \
--num_train_epochs 3 \
--fp16 \
--ddp_find_unused_parameters false \
--save_steps 1000 \
--logging_steps 50 \
--plot_loss

从节点执行相同命令（node_rank=1）

torchrun \
--nnodes=2 \
--node_rank=1 \
--master_addr=worker01 \
--master_port=29500 \
--nproc_per_node=4 \
src/train_bash.py \
# 参数完全相同...

注意：所有节点必须保证代码、依赖、路径完全一致，否则会因模型加载失败而中断。

DeepSpeed 多机训练：一键扩展

DeepSpeed 对多机支持非常成熟，只需指定节点数量和主地址即可：

deepeed \
--num_nodes=2 \
--num_gpus=4 \
--master_addr=worker01 \
--master_port=29500 \
--node_rank=0 \
src/train_bash.py \
--stage sft \
--do_train \
--model_name_or_path /shared/models/Llama-2-70B-Chat \
--dataset alpaca_gpt4_en \
--finetuning_type lora \
--output_dir /shared/output/llama2-70b-lora-deepspeed \
--per_device_train_batch_size 1 \
--gradient_accumulation_steps 16 \
--learning_rate 2e-5 \
--num_train_epochs 2 \
--deepspeed ./ds_z3_offload.json \
--fp16 \
--plot_loss

对应的 ds_z3_offload.json 需启用 ZeRO-3 并开启参数卸载：

"zero_optimization": {
  "stage": 3,
  "offload_optimizer": {
    "device": "cpu"
  },
  "offload_param": {
    "device": "cpu"
  },
  "stage3_max_live_parameters": 1e9,
  "stage3_max_reuse_distance": 1e9,
  "stage3_gather_16bit_weights_on_model_save": true
}

这套组合几乎是目前唯一能在普通集群上训练 70B 模型的方式。

FSDP 多机训练：简洁而强大

FSDP 的多机启动方式与 DDP 完全一致，仅需保留原有 FSDP 参数：

torchrun \
--nnodes=2 \
--node_rank=0 \
--master_addr=worker01 \
--master_port=29500 \
--nproc_per_node=4 \
src/train_bash.py \
--stage sft \
--do_train \
--model_name_or_path /shared/models/Yi-34B \
--dataset instruction_zh \
--finetuning_type lora \
--output_dir /shared/output/yi-34b-lora-fsdp-multi \
--per_device_train_batch_size 1 \
--gradient_accumulation_steps 16 \
--learning_rate 1e-4 \
--num_train_epochs 3 \
--fp16 \
--fsdp "full_shard auto_wrap" \
--fsdp_transformer_layer_cls_to_wrap "YiDecoderLayer" \
--fsdp_use_orig_params true \
--plot_loss

由于 FSDP 是 PyTorch 原生机制，无需外部依赖，非常适合构建标准化训练流水线。

常见问题与解决方案

显存溢出（OOM）

典型现象：训练刚开始就报 CUDA out of memory。

✅ 解决方案：

• 减小 per_device_train_batch_size
• 增加 gradient_accumulation_steps
• 启用 fp16 或 bf16
• 使用 DeepSpeed ZeRO-2/3 + CPU offload
• 添加 --low_cpu_mem_usage 加载模型，避免瞬时内存暴涨

实践建议：先用最小 batch size 跑通一轮 forward，再逐步放大。

多机连接失败

错误日志常见 ConnectionRefusedError 或 timeout。

✅ 排查步骤：

• 确保 master_addr 是内网 IP，而非 localhost 或 127.0.0.1；
• 测试 ping worker01 和 ssh worker01 是否通畅；
• 检查防火墙是否放行 master_port（如 29500）；
• 使用 ntpdate 同步各节点时间。

一个小技巧：可以在主节点监听端口 netstat -tulnp | grep 29500，确认服务是否真正启动。

DeepSpeed 报错 'Unsupported optimizer'

错误信息类似：ZeRO does not support AdamW with custom parameters

✅ 解决方法：

• 在配置中添加 "zero_allow_untested_optimizer": true
• 或尝试降级 DeepSpeed 至 v0.9.x（部分新版存在兼容性回归）

这个问题常出现在自定义学习率调度或 weight decay 设置时。

FSDP 报错 'Did not infer parameter location'

根本原因是 LoRA 适配器未能被正确识别。

✅ 解决方案：

• 必须设置 --fsdp_use_orig_params true
• 确认 fsdp_transformer_layer_cls_to_wrap 与模型实际结构匹配（如 GLMBlock、YiDecoderLayer）
• 避免在 target_modules 中包含非 Linear 层（如 LayerNorm）

这类错误往往不会立即暴露，而是在保存模型时才触发，因此建议早期就加入测试环节。

性能对比与选型建议（基于实测数据）

总结趋势：

• DDP 性能最强但吃显存，适合资源充足的快速实验；
• DeepSpeed 显存控制最优，是大模型训练的事实标准；
• FSDP 平衡性好，易于维护，特别适合构建长期演进的训练平台。

总结

在这个人人都想微调大模型的时代，LLaMA-Factory 提供了一个真正意义上的'一站式'解决方案：

• ✅ 统一接口支持 LLAMA、Qwen、Baichuan、ChatGLM 等数十种架构；
• ✅ 支持全参、LoRA、QLoRA 自由切换；
• ✅ 数据处理 → 训练 → 评估 → 部署一体化；
• ✅ 提供 WebUI，零代码也能完成模型定制；
• ✅ 完整覆盖 DDP、DeepSpeed、FSDP 三大分布式范式。

更重要的是，它的设计理念是'让用户专注于模型本身，而不是工程细节'。

不同场景下的推荐策略

不必纠结于'哪个最好'，而是根据你的资源、目标和团队技术栈选择最合适的一条路径。