- LLaMA-Factory 使用指南
- 结束
LLaMA-Factory 使用指南
北航博士生郑耀威，开发的大模型训练框架
- 2022年开始北航博士学业
- github hiyouga
- 【2024-3-20】ACL 2024 论文 LlamaFactory: Unified Efficient Fine-Tuning of 100+ Language Models
- 【2024-7-18】LLaMA-Factory QuickStart
- 官方文档
LLaMA-Factory
- 定位：工业级微调平台
- 核心能力：
- 企业背书：被Amazon/NVIDIA等公司采用，提供生产级工具链（含Colab集成）
- 生态整合：支持HuggingFace模型库，内置warp等辅助工具
- 社区活跃：GitHub高星项目，持续更新
- 推荐场景：
- 企业需要稳定、可扩展的微调框架
- 希望快速复现论文方案的团队
LLaMA-Factory 介绍
LLaMA Factory 支持多种LLM微调方式，北航博士生推出，包括: 预训练、指令监督微调和奖励模型训练等。
- 支持
LoRA和QLoRA微调策略，广泛集成了业界前沿的微调方法。 - 特点: 支持多种LLM模型，提供了WebUI页面，使非开发人员也能微调。
- 体验地址：LLaMA-Board
- 可视化界面 LLaMA-Board
- github: LLaMA-Factory，附各阶段训练数据集
资源
功能
功能
- 支持多种模型：LLaMA、LLaVA、Mistral、Mixtral-MoE、Qwen、Qwen2-VL、Yi、Gemma、Baichuan、ChatGLM、Phi 等等。
- 集成方法：（增量）预训练、（多模态）指令监督微调、奖励模型训练、PPO 训练、DPO 训练、KTO 训练、ORPO 训练等等。
- 多种精度：16 比特全参数微调、冻结微调、LoRA 微调和基于 AQLM/AWQ/GPTQ/LLM.int8/HQQ/EETQ 的 2/3/4/5/6/8 比特 QLoRA 微调。
- 先进算法：GaLore、BAdam、Adam-mini、DoRA、LongLoRA、LLaMA Pro、Mixture-of-Depths、LoRA+、LoftQ、PiSSA 和 Agent 微调。
- 实用技巧：FlashAttention-2、Unsloth、Liger Kernel、RoPE scaling、NEFTune 和 rsLoRA。
- 实验监控：LlamaBoard、TensorBoard、Wandb、MLflow、SwanLab 等等。
- 极速推理：基于 vLLM 的 OpenAI 风格 API、浏览器界面和命令行接口。
性能指标
- 与 ChatGLM 官方的 P-Tuning 微调相比，LLaMA Factory 的 LoRA 微调提供了 3.7 倍的加速比，同时在广告文案生成任务上取得了更高的 Rouge 分数。
- 结合 4 比特量化技术，LLaMA Factory 的 QLoRA 微调进一步降低了 GPU 显存消耗。
详情参考
依赖
模型训练生态系统
框架
【2025-11-13】【开源框架】ms-swift为什么比llama-factory好？
llama-factory 专注于“模型训练”的框架，核心是三大模块和工具能力
- 三大核心模块：Model Loader、Data Worker、Trainer
- 工具能力：llamaboard、model_inference、model_evaluation
模块
- Model Loader：负责模型的加载、适配与优化，支持LLM和VLM两类模型。目录
src/llamafactory/model- Initialization：使用Transformers库中的AutoClasses，加载model和tokenizer
- Patches：支持Flash attention等优化，提供GPTQ等量化微调
- Adapters：使用PEFT库挂载lora等adapter，自动识别模型架构
- Data Worker: 目录
src/llamafactory/data- Loading：使用Datasets库加载hugging face hub数据集
- Aligning：将Alpaca、ShareGPT等格式数据统一为标准结构
- Preprocess：提供模型的chat_template
- Trainer：目录
src/llamafactory/train- Efficient Training：使用Transformers/TRL库的Trainer，支持PT、SFT、DPO等任务，集成LoRA+、GaLore 等
- Distributed Training：使用Deepspeed库实现数据并行
LLaMA-Factory 安装
安装
依赖
- 必备依赖: torch/transformers/datasets/trl/accelerate/peft
- 可选依赖: CUDA/deepspeed/bitsandbytes/vllm/flash-attn
# ----------------------
git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory
pip install -e ".[torch,metrics]"
# ---------------------
# Clone the repository
git clone https://github.com/hiyouga/LLaMA-Factory.git
# Create a virtual environment
conda create -n llama_factory python=3.10
# Activate the virtual environment
conda activate llama_factory
# Install dependencies
cd LLaMA-Factory
pip install -r requirements.txt
【2025-1-11】 win 10 上实践
pip install llamafactory # 一步安装
模型
模型下载
项目支持通过模型名称直接从 huggingface 和 modelscope 下载模型，但不容易对模型文件统一管理，所以建议使用手动下载，然后使用绝对路径控制哪个模型。
以 Meta-Llama-3-8B-Instruct为例
# huggingface 下载（可能要先提交申请通过）
git clone https://huggingface.co/meta-llama/Meta-Llama-3-8B-Instruct
# modelscope 下载（适合中国大陆网络环境）
git clone https://www.modelscope.cn/LLM-Research/Meta-Llama-3-8B-Instruct.git
# 或者 模型下载
from modelscope import snapshot_download
model_dir = snapshot_download('LLM-Research/Meta-Llama-3-8B-Instruct')
注意
# Hugging Face 模型和数据集下载中遇到问题，可使用魔搭/魔乐社区。
export USE_MODELSCOPE_HUB=1 # Windows 使用 `set USE_MODELSCOPE_HUB=1`
export USE_OPENMIND_HUB=1 # Windows 使用 `set USE_OPENMIND_HUB=1`
训练模式
支持多种训练方法
- OFT正交微调
| Approach | Full-tuning | Freeze-tuning | LoRA | QLoRA | OFT | QOFT |
|---|---|---|---|---|---|---|
| Pre-Training | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Supervised Fine-Tuning | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Reward Modeling | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| PPO Training | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| DPO Training | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| KTO Training | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| ORPO Training | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| SimPO Training | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
Web UI
UI 点选操作转化为命令行
浏览器打开图形界面测试模型，可选择 --share 开公网链接
# Web UI 使用
llamafactory-cli webui # 启动网页端
GRADIO_SERVER_PORT=7862 lmf webui
GRADIO_SERVER_PORT=7862 llamafactory-cli webui # 制定端口，不是默认 7860
GRADIO_SERVER_PORT=8080 CACHE_DIR=$cache_dir lmf webui # 【2026-2-2】制定 cache 目录，huggingface 下载模型不放默认目录 ~/.cache/huggingface
CUDA_VISIBLE_DEVICES=4 llamafactory-cli webui # 指定第4张显卡使用
CUDA_DEVICE_ORDER='cpu' && llamafactory-cli webui # cpu 上启动web ui
set CUDA_DEVICE_ORDER='cpu';llamafactory-cli webui # windows terminal 命令
llamafactory-cli web --model_name_or_path path_to_model --share
其中
- 模型候选集合在源码 LlamaFactory/src/llamafactory/extras/constants.py 中
CLI 模式
几种使用方法
- ① 命令行直接指定
- ② 在 YAML 配置文件中设置
① 命令行直接指定
CUDA_VISIBLE_DEVICES=0 python src/train_bash.py \
--stage sft \
--do_train \
--model_name_or_path path_to_llama_model \
--dataset alpaca_gpt4_zh \
--cache_dir /mnt/fast_cache \
--output_dir path_to_sft_checkpoint
这样会将模型文件和数据集缓存到 /mnt/fast_cache，而不是默认的 ~/.cache/huggingface。
② 在 YAML 配置文件中设置
model_args:
model_name_or_path: path_to_llama_model
cache_dir: /mnt/fast_cache
然后运行：
python src/train_bash.py config.yaml
CACHE_DIR 是共享存储路径
# 三个环境变量指定到共享存储路径。
-e HF_DATASETS_CACHE=${CACHE_DIR}/HF_DATASETS_CACHE \
-e HUGGINGFACE_HUB_CACHE=${CACHE_DIR}/HUGGINGFACE_HUB_CACHE \
-e TRANSFORMERS_CACHE=${CACHE_DIR}/TRANSFORMERS_CACHE \
# 2个训练参数指定到共享存储路径。
--cache_dir ${CACHE_DIR}/cache_dir \
--tokenized_path ${CACHE_DIR}/tokenized_cache \
# 1个训练参数指定共享存储
--data_shared_file_system true \
【2026-2-2】实践
- lmf train *** 命令转化为 pytorch 的 torchrun 命令
# 单机两卡
torchrun --nnodes 1 --node_rank 0 --nproc_per_node 2 --master_addr 127.0.0.1 --master_port 54547 /ofs/ese-llm-ssd/users/wangqiwen/envs/py312/lib/python3.12/site-packages/llamafactory/launcher.py saves/Qwen3-4B-Instruct-2507/lora/train_2026-02-02-20-26-27/training_args.yaml
【2026-3-13】官方示例执行报错，以上torchrun命令同样报错
# 命令
llamafactory-cli train examples/train_lora/qwen3_lora_sft.yaml
# 错误信息
socket.cpp:764] [c10d] The client socket cannot be initialized to connect to [localhost]:54943 (errno: 97 - Address family not supported by protocol)
subprocess.CalledProcessError: Command '['torchrun', '--nnodes', '1', '--node_rank', '0', '--nproc_per_node', '2', '--master_addr', '127.0.0.1', '--master_port', '51789', '/ofs/ese-llm-ssd/users/wangqiwen/code/LlamaFactory/src/llamafactory/launcher.py', 'examples/train_lora/qwen3_lora_sft.yaml']' returned non-zero exit status 1.
# 更正后的命令
CUDA_VISIBLE_DEVICES=0 lmf train examples/train_lora/qwen3_lora_sft.yaml # 改成单机单卡
CUDA_VISIBLE_DEVICES=0,1 lmf train examples/train_lora/qwen3_lora_sft.yaml # 【2026-3-13】注明可用GPU即可
原因：
- 当前机器有多张GPU，默认都启用，训练时按照分布式模式启动，而 llamafactory-cli 训练命令里默认单机单卡，导致失败
# 启动日志显示未开启分布式
[INFO|2026-03-13 16:20:27] llamafactory.hparams.parser:508 >> Process rank: 0, world size: 1, device: cuda:0, distributed training: False, compute dtype: torch.bfloat16
解法
- 使用单机单卡模式：指定 CUDA_VISIBLE_DEVICES=0
- 更改命令为单机多卡模式：指定 CUDA_VISIBLE_DEVICES=0,1
注意
- 尽量使用2的次方的卡数，如 2，4，8，否则不符合操作系统的规律，可能问题，如算力分配不均衡，2**n的张量无法拆分进行运算
- 系统盘如果不够的话可以直接清空.cache文件
LLaMA-Factory 命令
llamafactory-cli 命令行工具接口是 LLaMA-Factory v3 版本引入的新特性，用于简化常用操作（训练、推理、导出等），简称 lmf
命令 说明
- env 显示环境信息（PyTorch、CUDA、transformers 等）
- train 启动模型训练（封装了 src/train_bash.py）
- merge 合并 LoRA 模型权重为 HuggingFace 模型
- cli 启动命令行交互测试
- webui 启动 Web UI 推理界面
- export 导出模型为 GGUF 或 Safetensors
- convert 转换数据格式为标准训练集
- validate 验证数据集格式是否正确
- chat 在命令行中与模型多轮对话
- clean 清理缓存、训练中间结果
- build 构建 tokenizer/config 结构
常用命令
主要命令
- llamafactory-cli 可简化为 lmf
llamafactory-cli version # 显示版本 lmf version
llamafactory-cli help # 帮助信息
llamafactory-cli train --help # 某个命令的详细参数说明 lmf train
llamafactory-cli env # 查看环境
llamafactory-cli build --model_type llama --output_dir ./model # 构建 tokenizer 和 config（高级用法）
llamafactory-cli train --config xxx.yaml # 训练模型
llamafactory-cli train --config ./configs/sft.yaml
llamafactory-cli cli/web/chat # 推理测试
llamafactory-cli cli --model_name_or_path path_to_model # 命令行对话
llamafactory-cli merge # 合并模型
# 合并 LoRA 模型
llamafactory-cli merge \
--base_model base_model_path \
--lora_model lora_adapter_path \
--output_dir merged_model_path
llamafactory-cli export --format gguf # 导出模型
# 导出为 GGUF（用于 llama.cpp）
llamafactory-cli export \
--model_name_or_path merged_model_path \
--format gguf \
--quantization q4_0 \
--output_dir ./gguf_model
llamafactory-cli chat --model_name_or_path path_to_model # 多轮对话测试（Chat 模式）
# convert, validate # 数据工具
llamafactory-cli validate --input_file ./data/converted.json # 验证数据格式是否正确
# 数据集格式转换：数据集转换为 Alpaca / ChatML 等格式
llamafactory-cli convert \
--input_file ./data/raw.json \
--output_file ./data/converted.json \
--format alpaca
llamafactory-cli clean # 清理缓存
对 Llama3-8B-Instruct 模型进行 LoRA 微调、推理和合并。
# 训练
llamafactory-cli train -h # 查看训练参数
# lora 微调
llamafactory-cli train examples/train_lora/llama3_lora_sft.yaml
# 推理
llamafactory-cli chat examples/inference/llama3_lora_sft.yaml
# 合并
llamafactory-cli export examples/merge_lora/llama3_lora_sft.yaml
# 用 vLLM 部署 OpenAI API
API_PORT=8000 llamafactory-cli api examples/inference/llama3_vllm.yaml
参数
参数解释
| 动作参数枚举 | 参数说明 |
|---|---|
version |
显示版本信息 |
train |
命令行版本训练 |
chat |
命令行版本推理chat |
export |
模型合并和导出 |
api |
启动API server，供接口调用 |
eval |
使用mmmlu等标准数据集做评测 |
webchat |
前端版本纯推理的chat页面 |
webui |
启动LlamaBoard前端页面，包含可视化训练，预测，chat，模型合并多个子页面 |
关键参数
model_name_or_path参数名称- huggingface 或 modelscope 标准定义，如“meta-llama/Meta-Llama-3-8B-Instruct”）
- 或者是本地下载的绝对路径，如 /media/codingma/LLM/llama3/Meta-Llama-3-8B-Instruct
template模型问答时prompt模板，不同模型不同，请参考 获取不同模型的模板定义，否则会回答结果会很奇怪或导致重复生成等现象的出现。- chat 版本模型基本都需要指定，比如 Meta-Llama-3-8B-Instruct 的 template 就是 llama3
也可提前把相关参数存在 yaml文件里，比如: LLaMA-Factory/examples/inference/llama3.yaml at main · hiyouga/LLaMA-Factory， 本地位置是 examples/inference/llama3.yaml
内容如下
model_name_or_path: /media/codingma/LLM/llama3/Meta-Llama-3-8B-Instruct
template: llama3
通过如下命令启动，效果跟上面一样，但是更方便管理
llamafactory-cli webchat examples/inference/llama3.yaml
效果如图，可通过 http://localhost:7860/ 进行访问
推理
transformers
huggingface transformers 库直接推理
import transformers
import torch
# 切换为你下载的模型文件目录, 这里的demo是Llama-3-8B-Instruct
# 如果是其他模型，比如qwen，chatglm，请使用其对应的官方demo
model_id = "/media/codingma/LLM/llama3/Meta-Llama-3-8B-Instruct"
pipeline = transformers.pipeline(
"text-generation",
model=model_id,
model_kwargs={"torch_dtype": torch.bfloat16},
device_map="auto",
)
messages = [
{"role": "system", "content": "You are a pirate chatbot who always responds in pirate speak!"},
{"role": "user", "content": "Who are you?"},
]
prompt = pipeline.tokenizer.apply_chat_template(
messages,
tokenize=False,
add_generation_prompt=True
)
terminators = [
pipeline.tokenizer.eos_token_id,
pipeline.tokenizer.convert_tokens_to_ids("<|eot_id|>")
]
outputs = pipeline(
prompt,
max_new_tokens=256,
eos_token_id=terminators,
do_sample=True,
temperature=0.6,
top_p=0.9,
)
print(outputs[0]["generated_text"][len(prompt):])
API
API 实现标准参考 OpenAI的相关接口协议，基于uvicorn服务框架进行开发， 使用如下的方式启动
本脚本改编自 llama3_lora_sft.yaml
CUDA_VISIBLE_DEVICES=0 API_PORT=8000 llamafactory-cli api \
--model_name_or_path /media/codingma/LLM/llama3/Meta-Llama-3-8B-Instruct \
--adapter_name_or_path ./saves/LLaMA3-8B/lora/sft \
--template llama3 \
--finetuning_type lora
项目也支持了基于vllm 的推理后端，但是这里由于一些限制，需要提前将LoRA 模型进行merge，使用merge后的完整版模型目录或者训练前的模型原始目录都可。
CUDA_VISIBLE_DEVICES=0 API_PORT=8000 llamafactory-cli api \
--model_name_or_path megred-model-path \
--template llama3 \
--infer_backend vllm \
--vllm_enforce_eager
服务启动后，即可按照openai 的API 进行远程访问，主要的区别就是替换 其中的base_url，指向所部署的机器url和端口号即可。
import os
from openai import OpenAI
from transformers.utils.versions import require_version
require_version("openai>=1.5.0", "To fix: pip install openai>=1.5.0")
if __name__ == '__main__':
# change to your custom port
port = 8000
client = OpenAI(
api_key="0",
base_url="http://localhost:{}/v1".format(os.environ.get("API_PORT", 8000)),
)
messages = []
messages.append({"role": "user", "content": "hello, where is USA"})
result = client.chat.completions.create(messages=messages, model="test")
print(result.choices[0].message)
Ollama
导出GGUF，部署Ollama
GGUF 是 lllama.cpp 设计的大模型存储格式，可以对模型进行高效的压缩，减少模型的大小与内存占用，从而提升模型的推理速度和效率。
Ollama框架可以帮助用户快速使用本地的大型语言模型，那将LLaMA-Factory项目的训练结果导出到Ollama中部署呢？
- 将lora模型合并
- 安装gguf库
- 使用llama.cpp的转换脚本将训练后的完整模型转换为gguf格式
- 安装Ollama软件
- 注册要部署的模型文件
- 启动Ollama
1-3 步是准备好 gguf 格式的文件这也是Ollama所需要的标准格式。
4-6 步就是如何在Ollama环境中启动训练后的模型。
分布式
【2025-12-15】LLaMA-Factory分布式训练实战指南
LLaMA-Factory 支持 DDP、DeepSpeed、FSDP 三种模式，各有侧重，具体看硬件条件和训练目标。
详见站内专题：分布式训练框架-底层框架选型
依赖检查
# 检查 PyTorch 分布式能力
python -c "import torch; print('Distributed available:', torch.distributed.is_available())"
# 检查 DeepSpeed
deepspeed --version
# 检查 FSDP 支持
python -c "try: import torch.distributed.fsdp; print('FSDP supported') except: print('FSDP not available')"
DDP 最简单
DDP：最简单，无需额外配置文件，直接用 torchrun 启动
示例
- –
nproc_per_node=4: 单机4卡 - –
fp16: 开启混合精度，显存节省约 40% - –
ddp_find_unused_parameters=false可提升约 5%~10% 训练速度，适用于 LoRA 微调方式
# torchrun --standalone --nnodes=1 --nproc-per-node=8 src/train.py \
torchrun --nproc_per_node=4 \
src/train_bash.py \
--stage sft \
--do_train \
--model_name_or_path /models/Qwen-7B-Chat \
--dataset medical_zh \
--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 \
--fp16 \
--ddp_find_unused_parameters false \
--plot_loss
# llama-factory 启动，CUDA_VISIBLE_DEVICES 没有指定，则默认使用所有GPU
FORCE_TORCHRUN=1 llamafactory-cli train examples/train_full/llama3_full_sft_ds3.yaml
FORCE_TORCHRUN=1 CUDA_VISIBLE_DEVICES=0,1 llamafactory-cli train config/config1.yaml
DeepSpeed：显存压缩之王
当模型变大（如 13B 级别），DDP 很容易 OOM。这时就得靠 DeepSpeed 的 ZeRO 技术来“瘦身”。
实测：
- 2×A100（40GB）上成功运行 Baichuan2-13B 的 LoRA 微调，显存峰值控制在 32GB 以内
先写配置文件：ds_z3_offload.json
三重减负：
- ZeRO-3：分片优化器状态、梯度、权重；
- CPU Offload：将部分状态卸载到内存；
- bf16：比 fp16 更稳定，适合大模型。
{
"train_batch_size": 64,
"train_micro_batch_size_per_gpu": 2,
"gradient_accumulation_steps": 8,
"bf16": { "enabled": true },
"fp16": { "enabled": false },
"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": 12000
}
},
"zero_optimization": {
"stage": 3,
"offload_optimizer": { "device": "cpu", "pin_memory": true },
"offload_param": { "device": "cpu", "pin_memory": true },
"overlap_comm": true,
"contiguous_gradients": true,
"reduce_bucket_size": 1e8,
"allgather_bucket_size": 5e8
},
"gradient_clipping": 1.0
}
启动训练
deepspeed --num_gpus=4 \
src/train_bash.py \
--model_name_or_path /models/Baichuan2-13B-Chat \
--dataset finance_en \
--finetuning_type lora \
--output_dir ./output/baichuan2-13b-lora-deepspeed \
--per_device_train_batch_size 2 \
--gradient_accumulation_steps 8 \
--deepspeed ./ds_z3_offload.json \
--fp16
FSDP：轻量级多机友好方案
FSDP 是 PyTorch 2.0 原生分片方案，不用引入 DeepSpeed 第三方依赖，更适合长期维护的生产系统
PyTorch 全切片数据并行技术 FSDP （Fully Sharded Data Parallel）能处理更多更大的模型。LLaMA-Factory支持使用 FSDP 引擎进行分布式训练。
FSDP 参数 ShardingStrategy 的不同取值决定了模型的划分方式：
- FULL_SHARD: 将模型参数、梯度和优化器状态都切分到不同的GPU上，类似ZeRO-3。
- SHARD_GRAD_OP: 将梯度、优化器状态切分到不同的GPU上，每个GPU仍各自保留一份完整的模型参数。类似ZeRO-2。
- NO_SHARD: 不切分任何参数。类似ZeRO-0。
注意
- PyTorch 版本需 ≥ 2.0，否则 torch.distributed.fsdp 模块将不可用
关键参数说明：
- full_shard：对模型状态全面分片；
- auto_wrap：自动包装 Transformer 层；
- offload：将部分张量卸载至 CPU；
- GLMBlock：ChatGLM 的基本模块名，必须准确指定，否则分片无效。
🔥 注意：
- LoRA 微调必须加上 –fsdp_use_orig_params true，否则会出现参数未绑定的问题。
torchrun --nproc_per_node=4 \
src/train_bash.py \
--stage sft \
--do_train \
--model_name_or_path /models/ChatGLM3-6B \
--dataset law_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 \
--fp16 \
--fsdp "full_shard auto_wrap offload" \
--fsdp_transformer_layer_cls_to_wrap "GLMBlock" \
--fsdp_use_orig_params true \
--plot_loss
原文链接：https://blog.csdn.net/weixin_35516624/article/details/155976841
多机训练：跨节点协同的那些坑
当训练更大模型或处理海量数据时，单机已无法满足需求。多机训练的关键在于 网络通信稳定性和路径一致性。
前提条件
- 所有机器在同一内网，可通过 IP 直接访问；
- 统一安装相同版本的 CUDA、PyTorch、LLaMA-Factory；
- 模型和数据集挂载在共享路径（推荐 NFS）；
- 主节点 SSH 免密登录所有从节点；
- 防火墙开放端口（默认 29500）；
- 所有节点时间同步（建议启用 NTP）。
llama-factory 多机多卡
参数
- NNODES 节点数，如 两台机器
- RANK 各个节点的rank，编号
- MASTER_ADDR 主节点地址
- MASTER_PORT 主节点端口
FORCE_TORCHRUN=1 NNODES=2 RANK=0 MASTER_ADDR=192.168.0.1 MASTER_PORT=29500 \ llamafactory-cli train examples/train_lora/llama3_lora_sft.yaml FORCE_TORCHRUN=1 NNODES=2 RANK=1 MASTER_ADDR=192.168.0.1 MASTER_PORT=29500 \ llamafactory-cli train examples/train_lora/llama3_lora_sft.yaml
(1) DDP 多机训练：手动协调节点
创建 hostfile 文件：
192.168.1.10 master_addr=192.168.1.10 slots=4
192.168.1.11 slots=4
主节点执行
torchrun \
--nnodes=2 \
--node_rank=0 \
--master_addr=192.168.1.10 \
--master_port=29500 \
--nproc_per_node=4 \
src/train_bash.py \
--model_name_or_path /shared/models/Qwen-7B-Chat \
--dataset alpaca_gpt4_en \
--finetuning_type lora \
--output_dir /shared/output/qwen-7b-ddp-multi \
--per_device_train_batch_size 2 \
--gradient_accumulation_steps 8 \
--fp16 \
--ddp_find_unused_parameters false
# 或
torchrun --master_port 29500 --nproc_per_node=8 --nnodes=2 --node_rank=0 \
--master_addr=192.168.0.1 train.py torchrun --master_port 29500 --nproc_per_node=8 --nnodes=2 --node_rank=1 \
--master_addr=192.168.0.1 train.py
从节点执行相同命令，仅修改 –node_rank=1。
⚠️ 常见错误：
- “Connection refused” —— 检查 master_addr 是否为真实 IP，不能是 localhost 或 127.0.0.1。
(2) DeepSpeed 多机：一键启动
每个节点运行相同命令，–node_rank 按顺序设置为 0, 1, … 即可。
💡 提醒：
- 所有节点必须能访问相同的模型路径（如 NFS），否则会报 “Model file not found”。
DeepSpeed 自动管理多节点，只需加 –num_nodes 参数：
deepspeed \
--num_nodes=2 \
--num_gpus=4 \
--master_addr=192.168.1.10 \
--master_port=29500 \
--node_rank=0 \
src/train_bash.py \
--model_name_or_path /shared/models/Llama-2-13B-chat-hf \
--dataset medical_zh \
--finetuning_type lora \
--deepspeed ./ds_z3_offload.json \
--fp16
(3) FSDP 多机：配置与 DDP 完全一致
FSDP 多机启动方式与 DDP 几乎一样，只是保留了 FSDP 参数
不同模型对应的 layer class 名称：
- Qwen / LLaMA → QWenBlock / LlamaDecoderLayer
- ChatGLM → GLMBlock
- Baichuan → BaichuanLayer
务必根据实际模型结构填写，否则分片不会生效。
torchrun \
--nnodes=2 \
--node_rank=0 \
--master_addr=192.168.1.10 \
--master_port=29500 \
--nproc_per_node=4 \
src/train_bash.py \
--model_name_or_path /shared/models/Qwen-7B-Chat \
--dataset finance_en \
--finetuning_type lora \
--output_dir /shared/output/qwen-7b-lora-fsdp-multi \
--per_device_train_batch_size 4 \
--gradient_accumulation_steps 4 \
--fp16 \
--fsdp "full_shard auto_wrap offload" \
--fsdp_transformer_layer_cls_to_wrap "QWenBlock" \
--fsdp_use_orig_params true
常见问题
常见问题与解决方案（亲测有效）
1. 显存不足（OOM）
✅ 应对策略：
- 降低 per_device_train_batch_size
- 增加 gradient_accumulation_steps 保持总 batch size
- 启用 fp16 或 bf16
- DeepSpeed 使用 ZeRO-3 + CPU Offload
- FSDP 添加 –fsdp_offload_params_to_cpu true
小技巧：QLoRA 比 LoRA 更省显存，可进一步压缩 30%，但需转换模型为 bitsandbytes 格式。
2. 多机通信失败
常见报错：Connection refused, Address already in use
✅ 检查清单：
- master_addr 是否为真实内网 IP
- master_port 是否被占用（lsof -i :29500）
- 防火墙是否放行
- SSH 免密登录是否配置正确
- 所有节点时间是否同步（timedatectl status）
3. DeepSpeed 报错 “ZeRO stage 3 not supported”
可能原因：
- DeepSpeed 版本 < v0.9.0 → 升级
- 使用了不兼容优化器 → 加 “zero_allow_untested_optimizer”: true
- LoRA 与 ZeRO-3 冲突 → 改用 ZeRO-2 或切换为 FSDP
4. FSDP 报错 “Did not instantiate model with FSDP”
解决方法：
- 确保 –fsdp 参数格式正确（空格分隔）
- 检查 –fsdp_transformer_layer_cls_to_wrap 拼写
- 必须添加 –fsdp_use_orig_params true（LoRA 必须）
- PyTorch ≥ 2.0
LLaMA-Factory 可视化
LLaMA Board
Web UI 使用
- LLaMA Board 可视化微调（由 Gradio 驱动）
- Web UI 目前只支持单卡训练/推理，当机器有多张显卡时请使用
CUDA_VISIBLE_DEVICES指定一张显卡启动程序。 - 启动网页UI，系统上必须有 GPU ！
目前webui版本只支持单机单卡和单机多卡，如果是多机多卡请使用命令行版本
# Web UI 使用
llamafactory-cli webui # 启动网页端
CUDA_VISIBLE_DEVICES=0 llamafactory-cli webui
CUDA_VISIBLE_DEVICES=4 llamafactory-cli webui # 指定第4张显卡使用
# 如果开启 gradio share功能，或者修改端口号
CUDA_VISIBLE_DEVICES=0 GRADIO_SHARE=1 GRADIO_SERVER_PORT=7860 llamafactory-cli webui
上述的多个不同的大功能模块都通过不同的tab进行了整合，提供了一站式操作体验。
- 训练 → 批量评估 → 交互测试 → 模型导出
- train页面，可通过预览命令功能，将训练脚本导出，用于支持多gpu训练
点击开始按钮, 即可开始训练，网页端和服务器端会同步输出相关的日志结果
训练完毕后, 点击“刷新适配器”，可找到该模型历史上使用webui训练的LoRA模型文件，后续再训练或者执行chat的时候，即会将此LoRA一起加载。
W&B
Weights & Biases 记录实验数据，请在 yaml 文件中添加下面的参数。
report_to: wandb
run_name: test_run # 可选
启动训练任务时，将 WANDB_API_KEY 设置为密钥来登录 W&B 账户。
SwanLab
用 SwanLab 记录实验数据，请在 yaml 文件中添加下面的参数。
use_swanlab: true
swanlab_run_name: test_run # 可选
启动训练任务时，登录 SwanLab账户 有三种方式：
- 方式一：在 yaml 文件中添加
swanlab_api_key=<your_api_key>，并设置 API 密钥。 - 方式二：将环境变量
SWANLAB_API_KEY设置为你的 API 密钥。 - 方式三：启动前使用
swanlab login命令完成登录。
数据集
目前支持 alpaca 和 sharegpt 两种数据格式
以alpaca为例，整个数据集是一个json对象的list，具体数据格式为
[
{
"instruction": "用户指令（必填）",
"input": "用户输入（选填）",
"output": "模型回答（必填）",
"system": "系统提示词（选填）",
"history": [
["第一轮指令（选填）", "第一轮回答（选填）"],
["第二轮指令（选填）", "第二轮回答（选填）"]
]
}
]
例子比如单轮（alpaca_data_zh_51k.json 中的例子, 数据集在data/dataset_info.json中注册为alpaca_zh）
{
"instruction": "写一个有效的比较语句",
"input": "篮球和足球",
"output": "篮球和足球都是受欢迎的运动。"
}
和多轮 （oaast_sft_zh.json 中的例子, 数据集在data/dataset_info.json中注册为oaast_sft_zh）
{
"instruction": "谢谢",
"input": "",
"output": "不用谢! 很高兴我提供的信息能够帮助到你! 如果还有什么其他问题也可以向我提问。",
"history": [
[
"请你给我写一个面试准备计划，我想要去面试微软的程序员岗位",
"首先，你可以去微软官网寻找招聘信息并申请面试。\n其次，您可以在社交媒体平台寻找微软公司对程序员的面试问题，并做好准备。\n最后，您可以自己对面试过程进行模拟，熟悉话题并减少紧张感。\n我希望你能面试成功。"
]
]
}
应用案例
多GPU分布式训练, 多种工具
- huggingface Accelerate
- DeepSpeed
微调类型: full, freeze, lora
指令监督微调
sft lora
CUDA_VISIBLE_DEVICES=0 llamafactory-cli train \
# CUDA_VISIBLE_DEVICES=0 nohup python src/train_bash.py # 另一个启动选项
--stage sft \ # 训练阶段 “sft”,"pt","rm","ppo"
--do_train \ # 是否训练模式
--model_name_or_path /media/codingma/LLM/llama3/Meta-Llama-3-8B-Instruct \
--dataset alpaca_gpt4_zh,identity,adgen_local \ # 数据集列表, 多个数据集逗号分隔
--dataset_dir ./data \ # 数据集目录，自带的data
--template llama3 \ # 可以是 qwen
--finetuning_type lora \ # 微调类型: full, freeze, lora
--output_dir ./saves/LLaMA3-8B/lora/sft \ # 模型保存目录
--overwrite_cache \
--overwrite_output_dir \
--cutoff_len 1024 \ # 长度截断
--preprocessing_num_workers 16 \ #
--per_device_train_batch_size 2 \ # 训练时，各节点最小 batch_size
--per_device_eval_batch_size 1 \ # 训练时，各节点最小 batch_size
--gradient_accumulation_steps 8 \ # 梯度累积步数
--lr_scheduler_type cosine \ # 学习率衰减策略
--logging_steps 50 \ # 打日志步数
--warmup_steps 20 \ # warmup
--save_steps 100 \ # 模型保存间隔步数
--eval_steps 50 \
--evaluation_strategy steps \ #
--load_best_model_at_end \
--learning_rate 5e-5 \
--num_train_epochs 5.0 \
--max_samples 1000 \ # 采样数
--val_size 0.1 \
--plot_loss \
--fp16 # 半精度, v100不支持 bf16
训练结果
output_dir 下主要包含3部分
- adapter 开头: LoRA保存的结果了，后续用于模型推理融合
- training_loss 和 trainer_log 等记录训练的过程指标
- 其他是训练当时各种参数的备份
loss在 正常情况下会随着训练的时间慢慢变小，最后需要下降到1以下的位置才会有一个比较好的效果，可以作为训练效果的一个中间指标。
lora 效果验证
- webui
- terminal
lora 模型推理: webchat
- 指定原模型+lora模型
CUDA_VISIBLE_DEVICES=0 llamafactory-cli webchat \
--model_name_or_path /media/codingma/LLM/llama3/Meta-Llama-3-8B-Instruct \
--adapter_name_or_path ./saves/LLaMA3-8B/lora/sft \
--template llama3 \
--finetuning_type lora
terminal 终端验证
CUDA_VISIBLE_DEVICES=0 llamafactory-cli chat \
--model_name_or_path /media/codingma/LLM/llama3/Meta-Llama-3-8B-Instruct \
--adapter_name_or_path ./saves/LLaMA3-8B/lora/sft \
--template llama3 \
--finetuning_type lora
批量自动化评估
pip install jieba
pip install rouge-chinese
pip install nltk
本脚参考文件参数
CUDA_VISIBLE_DEVICES=0 llamafactory-cli train \
--stage sft \
--do_predict \ # 预测模式
--model_name_or_path /media/codingma/LLM/llama3/Meta-Llama-3-8B-Instruct \
--adapter_name_or_path ./saves/LLaMA3-8B/lora/sft \
--eval_dataset alpaca_gpt4_zh,identity,adgen_local \
--dataset_dir ./data \
--template llama3 \
--finetuning_type lora \
--output_dir ./saves/LLaMA3-8B/lora/predict \
--overwrite_cache \
--overwrite_output_dir \
--cutoff_len 1024 \
--preprocessing_num_workers 16 \
--per_device_eval_batch_size 1 \
--max_samples 20 \ # 预测阶段采样数目
--predict_with_generate # 生成阶段
评估预测脚本 vs 训练脚本
区别如下两个
do_predict预测模式predict_with_generate生成文本max_samples每个数据集采样多少用于预测对比
训练的LoRA和原始大模型进行融合，输出一个完整的模型文件
CUDA_VISIBLE_DEVICES=0 llamafactory-cli export \
--model_name_or_path /media/codingma/LLM/llama3/Meta-Llama-3-8B-Instruct \
--adapter_name_or_path ./saves/LLaMA3-8B/lora/sft \
--template llama3 \
--finetuning_type lora \
--export_dir megred-model-path \
--export_size 2 \
--export_device cpu \
--export_legacy_format False
Accelerate
accelerate launch src/train.py \
--ddp_timeout 18000000 \
--stage sft \
--do_train \
--model_name_or_path /gemini/pretrain/Qwen1.5-4B/ \
--dataset alpaca_gpt4_data_zh,alpaca_gpt4_data_en,glaive_toolcall_zh_demo,adgen_local \
--template qwen \
--finetuning_type lora \
--lora_target q_proj,v_proj \
--output_dir path_to_sft_checkpoint \
--overwrite_cache \
--overwrite_output_dir
--per_device_train_batch_size 2 \
--gradient_accumulation_steps 4 \
--lr_scheduler_type cosine \
--logging_steps 10 \
--save_steps 1000 \
--learning_rate 5e-5 \
--num_train_epochs 3.0 \
--plot_loss \
--fp16
使用 DeepSpeed
deepspeed --num_gpus 2 src/train.py \
--deepspeed ds_config.json \
--ddp_timeout 18000000 \
--stage sft \
--do_train \
--model_name_or_path /gemini/pretrain/Qwen1.5-4B/ \
--dataset alpaca_zh_demo \
--template qwen \
--finetuning_type lora \
--lora_target q_proj,v_proj \
--output_dir path_to_sft_checkpoint \
--overwrite_cache \
--overwrite_output_dir
--per_device_train_batch_size 4 \
--gradient_accumulation_steps 4 \
--lr_scheduler_type cosine \
--logging_steps 10 \
--save_steps 1000 \
--learning_rate 5e-5 \
--num_train_epochs 3.0 \
--plot_loss \
--fp16
奖励模型训练
示例
- finetune_type = lora
CUDA_VISIBLE_DEVICES=0 python src/train_bash.py \
--stage rm \
--do_train \
--model_name_or_path /data/models/sft_qwen/
--create_new_adapter \
--dataset comparison_gpt4_zh \
--template qwen \
--finetuning_type lora \
--lora_target c_attn \
--output_dir /data/models/rm_qwen \
--per_device_train_batch_size 2 \
--gradient_accumulation_steps 4 \
--lr_scheduler_type cosine \
--logging_steps 10 \
--save_steps 1000 \
--learning_rate 1e-6 \
--num_train_epochs 1.0 \
--plot_loss \
--fp16
lora 合并
合并：
python src/export_model.py
--model_name_or_path /data/models/Qwen-1_8B-Chat
--adapter_name_or_path /data/models/sft_qwen
--template qwen
--finetuning_type lora
--export_dir /data/models/export_qwen/
Accelerate
accelerate launch src/train.py \
--stage rm \
--do_train \
--model_name_or_path /gemini/pretrain/Qwen1.5-4B/ \
--adapter_name_or_path path_to_sft_checkpoint \
--create_new_adapter \
--dataset dpo_zh_demo \
--template qwen \
--finetuning_type lora \
--lora_target q_proj,v_proj \
--output_dir path_to_ac_rm_checkpoint \
--per_device_train_batch_size 2 \
--gradient_accumulation_steps 4 \
--lr_scheduler_type cosine \
--logging_steps 10 \
--save_steps 1000 \
--learning_rate 1e-5 \
--num_train_epochs 1.0 \
--plot_loss \
--fp16
使用 DeepSpeed
deepspeed --num_gpus 2 src/train.py \
--deepspeed ds_config.json \
--stage rm \
--do_train \
--model_name_or_path /gemini/pretrain/Qwen1.5-4B/ \
--adapter_name_or_path path_to_sft_checkpoint \
--create_new_adapter \
--dataset dpo_zh_demo \
--template qwen \
--finetuning_type lora \
--lora_target q_proj,v_proj \
--output_dir path_to_deep_rm_checkpoint \
--per_device_train_batch_size 2 \
--gradient_accumulation_steps 4 \
--lr_scheduler_type cosine \
--logging_steps 10 \
--save_steps 1000 \
--learning_rate 1e-5 \
--num_train_epochs 1.0 \
--plot_loss \
--fp16
ppo 训练
示例
CUDA_VISIBLE_DEVICES=0 nohup python src/train_bash.py
--stage ppo
--do_train
--model_name_or_path /data/models/export_qwen
--create_new_adapter
--dataset alpaca_gpt4_zh
--template qwen
--finetuning_type lora
--lora_target c_attn
--reward_model /data/models/rm_qwen
--output_dir /data/models/ppo_qwen
--per_device_train_batch_size 2
--gradient_accumulation_steps 4
--lr_scheduler_type cosine
--top_k 0
--top_p 0.9
--logging_steps 10
--save_steps 1000
--learning_rate 1e-5
--num_train_epochs 1.0
--plot_loss
--overwrite_output_dir
--fp16 >>log &
Accelerate
accelerate launch src/train.py \
--stage ppo \
--do_train \
--model_name_or_path /gemini/pretrain/Qwen1.5-4B/ \
--adapter_name_or_path path_to_sft_checkpoint \
--create_new_adapter \
--dataset alpaca_zh_demo \
--template qwen \
--finetuning_type lora \
--lora_target q_proj,v_proj \
--reward_model path_to_ac_rm_checkpoint \
--output_dir path_to_ac_ppo_checkpoint \
--per_device_train_batch_size 2 \
--gradient_accumulation_steps 4 \
--lr_scheduler_type cosine \
--top_k 0 \
--top_p 0.9 \
--logging_steps 10 \
--save_steps 1000 \
--learning_rate 1e-5 \
--num_train_epochs 1.0 \
--plot_loss \
--fp16
deepspeed
deepspeed --num_gpus 2 src/train.py \
--deepspeed ds_config.json \
--stage ppo \
--do_train \
--model_name_or_path /gemini/pretrain/Qwen1.5-4B/ \
--adapter_name_or_path path_to_sft_checkpoint \
--create_new_adapter \
--dataset alpaca_zh_demo \
--template qwen \
--finetuning_type lora \
--lora_target q_proj,v_proj \
--reward_model path_to_deep_rm_checkpoint \
--output_dir path_to_deep_ppo_checkpoint \
--per_device_train_batch_size 4 \
--gradient_accumulation_steps 4 \
--lr_scheduler_type cosine \
--top_k 0 \
--top_p 0.9 \
--logging_steps 10 \
--save_steps 1000 \
--learning_rate 1e-5 \
--num_train_epochs 1.0 \
--plot_loss \
--fp16
dpo 训练
DPO算法不依赖RM阶段，不需要RM模型。
nohup deepspeed --include="localhost:1,2,3,4,5,6,7" --master_port=9901 src/train_bash.py
--deepspeed ds_config.json
--stage dpo
--do_train
--model_name_or_path /data/models/chatglm3-6b/
--adapter_name_or_path /data/models/lora_chatglm
--create_new_adapter
--dataset comparison_gpt4_zh
--template chatglm3
--finetuning_type lora
--lora_target query_key_value
--output_dir /data/models/chatglm3_dpo
--per_device_train_batch_size 1
--gradient_accumulation_steps 4
--lr_scheduler_type cosine
--logging_steps 10
--save_steps 2000
--learning_rate 1e-5
--num_train_epochs 1.0
--plot_loss
--fp16 >> log&
Accelerate
accelerate launch src/train.py \
--stage dpo \
--do_train \
--model_name_or_path /gemini/pretrain/Qwen1.5-4B/ \
--adapter_name_or_path path_to_sft_checkpoint \
--create_new_adapter \
--dataset dpo_zh_demo \
--template qwen \
--finetuning_type lora \
--lora_target q_proj,v_proj \
--output_dir path_to_ac_dpo_checkpoint \
--per_device_train_batch_size 2 \
--gradient_accumulation_steps 4 \
--lr_scheduler_type cosine \
--logging_steps 10 \
--save_steps 1000 \
--learning_rate 1e-5 \
--num_train_epochs 1.0 \
--plot_loss \
--fp16
deepspeed
deepspeed --num_gpus 2 src/train.py \
--deepspeed ds_config.json \
--stage dpo \
--do_train \
--model_name_or_path /gemini/pretrain/Qwen1.5-4B/ \
--adapter_name_or_path path_to_sft_checkpoint \
--create_new_adapter \
--dataset dpo_zh_demo \
--template qwen \
--finetuning_type lora \
--lora_target q_proj,v_proj \
--output_dir path_to_deep_dpo_checkpoint \
--per_device_train_batch_size 2 \
--gradient_accumulation_steps 4 \
--lr_scheduler_type cosine \
--logging_steps 10 \
--save_steps 1000 \
--learning_rate 1e-5 \
--num_train_epochs 1.0 \
--plot_loss \
--fp16
支付宝打赏 
微信打赏 
