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

优质文章学习记录

— 11 min read

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

在大模型时代，微调不再是少数人的专利。随着开源生态的爆发式增长，越来越多开发者希望基于 Qwen、Llama 或 ChatGLM 等主流架构定制自己的领域专家模型。然而，当模型参数从 7B 跨越到 13B 甚至 70B 时，显存墙和训练效率问题接踵而至。

LLaMA-Factory 正是在这一背景下崛起的明星项目——它不仅支持超过百种主流模型架构的全参数与高效微调（如 LoRA/QLoRA），更关键的是，提供了开箱即用的分布式训练能力。无论是单机多卡还是跨节点集群，你都可以通过统一接口快速启动训练任务。

本文将带你深入实战，从环境搭建到多机部署，覆盖 DDP、DeepSpeed 和 FSDP 三大主流分布式方案，并结合真实场景给出选型建议与避坑指南。

环境准备：让系统“准备好跑大模型”

任何高效的训练都始于一个干净、稳定的运行环境。尤其是在使用 A10/A100/H100 等高端 GPU 时，CUDA 版本、驱动兼容性和依赖库的选择直接影响能否成功加载模型。

安装基础工具链

首先确保系统具备编译和运行所需的基础组件：

sudo apt update && sudo apt install -y \ python3-pip python3-dev git gcc g++ make cmake libssl-dev libffi-dev

这一步看似简单，但若缺少 libffi-dev 或 cmake，后续安装 PyTorch 扩展或 FlashAttention 时可能报错无法编译 C++ 源码。

配置 CUDA 与 GPU 支持

推荐使用 CUDA 11.8 或 12.1，具体选择取决于硬件：

# 示例：Ubuntu 22.04 上安装 CUDA 11.8 wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb sudo dpkg -i cuda-keyring_1.1-1_all.deb sudo apt update && sudo apt install -y cuda-11-8 # 设置环境变量 echo 'export PATH=/usr/local/cuda-11.8/bin:$PATH' >> ~/.bashrc echo 'export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc source ~/.bashrc

验证安装是否成功：

nvcc -V # 应输出 CUDA 编译器版本 nvidia-smi # 查看 GPU 状态及驱动加载情况
💡 若使用 Hopper 架构（如 H100），强烈建议升级至 CUDA 12.x 并搭配 PyTorch 2.0+，以启用 torch.compile 和 BF16 计算，这对提升吞吐至关重要。

安装 LLaMA-Factory 与核心依赖

推荐采用源码安装方式，以便获取最新功能和分布式优化补丁：

git clone https://github.com/hiyouga/LLaMA-Factory.git cd LLaMA-Factory # 创建独立虚拟环境（conda 更便于管理） conda create -n llafactory python=3.10 -y conda activate llafactory # 安装主包及可选组件（含 DeepSpeed、FlashAttention） pip install -e .[deepspeed,torch] # 安装匹配版本的 PyTorch（以 CUDA 11.8 为例） pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

最后验证安装状态：

llama_factory-cli version

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

检查分布式训练依赖

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

# 检查 PyTorch 分布式支持 python -c "import torch; print(f'Distributed available: {torch.distributed.is_available()}')" # 检查 DeepSpeed 是否可用 deepspeed --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 支持三种主流并行策略，每种都有其适用边界。理解它们的本质差异，才能做出合理选择。

引擎核心特点适用场景
DDPPyTorch 原生实现，调试方便，通信开销低单机多卡（≤8卡），中小模型（<13B）
DeepSpeedZeRO 显存优化强大，支持 CPU offload，适合超大模型大模型（≥13B）、显存受限、追求极致吞吐
FSDPPyTorch 官方内置，兼容性强，支持 torch.compile 加速多机扩展、标准化部署、长期维护项目

我的经验是：
- 快速验证想法 → 用 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 提升数据传输效率。

第二步：启动训练
deepspeed --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 对多机支持非常成熟，只需指定节点数量和主地址即可：

deepspeed \ --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）

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

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

引擎模型设备显存/卡速度 (tokens/s)适用性
DDPQwen-7B单机4×A10~18GB~920快速迭代首选
DeepSpeed-ZeRO2Baichuan2-13B单机8×A10~14GB~760显存敏感场景最佳
FSDPChatGLM3-6B双机8×RTX3090~10GB~810多机标准化部署优选
DeepSpeed-ZeRO3+OffloadLlama2-70B4节点×8GPU~16GB~320超大模型唯一选择

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

写在最后：为什么你应该关注 LLaMA-Factory？

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

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

更重要的是，它的设计理念是“让用户专注于模型本身，而不是工程细节”。无论你是高校研究员、初创公司工程师，还是个人开发者，都能从中受益。

不同场景下的推荐策略

场景推荐方案
快速验证想法DDP + LoRA + 单机4卡
显存有限训练大模型DeepSpeed ZeRO-2 + CPU Offload
多机集群标准化训练FSDP + torch.compile
超大规模模型（>70B）DeepSpeed ZeRO-3 + Offload + 多节点

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

立即动手，打造属于你的垂直领域大模型吧！

Read more

SpringBoot+Vue+Netty+WebSocket+WebRTC 视频聊天实现

一、关于WebRTC（Web Real-Time Communication） WebRTC 是什么:是浏览器内置的实时通信技术，能让网页直接实现音视频通话、数据传输，无需安装插件。 ICE 是什么：ICE（Interactive Connectivity Establishment）是 WebRTC 中用于解决 NAT 穿透（简单说就是让不同网络下的设备能找到彼此）的框架，而 iceServers 就是给 ICE 提供 “辅助服务器” 的配置。 STUN 服务器：STUN（Session Traversal Utilities for NAT），直译是 “NAT 会话穿透工具”，它是一种轻量级的网络服务器，核心作用是：帮助处于 NAT（网络地址转换）后的设备（比如你的电脑 / 手机）
【Vue2+SpringBoot在线商城】02-连接前端登录功能与后端接口

【Vue2+SpringBoot在线商城】02-连接前端登录功能与后端接口

本项目是基于Vue2+SpringBoot+Mysql制作的在线商城项目。 之前已经实现了后端Result，也实现了前后端的连通测试。接下来先逐步实现登录功能。不过目前先不连接数据库，先把登录的相关接口和MD5加密以及其他必备的功能先写好，然后后续再对接数据库。 一、后端实现 1.1 添加必要依赖 在pom.xml中，添加这两个依赖。 jjwt这个依赖用于生成/校验 Token。后续在JwtUtil会用到。hutool-all是用于做md5加密 <dependency> <groupId>io.jsonwebtoken</groupId> <artifactId>jjwt</artifactId> <version>0.9.1</version> <

DAMO-YOLO-S WebUI无障碍适配：屏幕阅读器支持与键盘导航优化

DAMO-YOLO-S WebUI无障碍适配：屏幕阅读器支持与键盘导航优化 1. 项目背景与意义 在现代Web应用开发中，无障碍访问（Accessibility）已经成为一个不可忽视的重要议题。DAMO-YOLO-S作为一个基于先进目标检测技术的手机检测系统，其Web界面的无障碍适配对于确保所有用户都能平等使用这一技术具有重要意义。 传统的计算机视觉应用往往忽视了视障用户和行动不便用户的需求。通过为DAMO-YOLO-S WebUI添加屏幕阅读器支持和键盘导航优化，我们不仅提升了产品的包容性，也为更多用户群体打开了使用先进AI技术的大门。 这项改进工作的核心价值在于： * 平等访问：确保视障用户能够通过屏幕阅读器理解界面内容和操作流程 * 操作便利：为无法使用鼠标的用户提供完整的键盘操作支持 * 合规性：符合Web内容无障碍指南（WCAG）标准要求 * 用户体验：为所有用户提供更加友好和高效的操作体验 2. 屏幕阅读器支持实现 2.1 ARIA标签优化 为DAMO-YOLO-S WebUI中的关键元素添加适当的ARIA（Accessible Rich Int
前端八股文面经大全：MetaAPP前端一面（2026-03-03）·面经深度解析

前端八股文面经大全：MetaAPP前端一面（2026-03-03）·面经深度解析

前言 大家好，我是木斯佳。 在这个春节假期，当大家都在谈论返乡、团圆与休息时，作为一名技术人，我的思考却不由自主地转向了行业的「冬」与「春」。 相信很多人都感受到了，在AI浪潮的席卷之下，前端领域的门槛在变高，纯粹的“增删改查”岗位正在肉眼可见地减少。曾经热闹非凡的面经分享，如今也沉寂了许多。但我们都知道，市场的潮水退去，留下的才是真正在踏实准备、努力沉淀的人。学习的需求，从未消失，只是变得更加务实和深入。 这个专栏的初衷很简单：拒绝过时的、流水线式的PDF引流贴，专注于收集和整理当下最新、最真实的前端面试资料。我会在每一份面经和八股文的基础上，尝试从面试官的角度去拆解问题背后的逻辑，而不仅仅是提供一份静态的背诵答案。无论你是校招还是社招，目标是中大厂还是新兴团队，只要是真实发生、有价值的面试经历，我都会在这个专栏里为你沉淀下来。 温馨提示：市面上的面经鱼龙混杂，甄别真伪、把握时效，是我们对抗内卷最有效的武器。 在这个假期，让我们一起充电，为下一个技术春天做好准备。 面经原文内容 📍面试公司：MetaAPP