LLaMA Factory 快速开始：从环境安装到 FSDP2 全参数微调的完整上手指南

本文基于 LLaMA Factory 仓库的官方快速开始文档（docs/zh/getting-started.md）编写，覆盖软件依赖要求、两种安装方式、内置/自定义数据准备，以及命令行训练、Web UI 训练与推理部署的完整流程。读完后你可以独立搭好训练环境，使用 FSDP2 对 Qwen3-0.6B 跑通一次全参数 SFT，并掌握从源码层面理解 llamafactory-cli 各子命令路由的方法。

1. 支持哪些训练方法与训练范式

LLaMA Factory 支持 100+ 种主流大语言模型的微调训练。当前版本对训练方法与训练范式的支持矩阵如下：

方法	全参数训练	部分参数训练	LoRA	QLoRA
指令监督微调 (SFT)	支持	支持	支持	支持
DPO 训练	支持	支持	支持	支持

提示：v1 训练管线目前支持 SFT 和 DPO 两种训练方法，两者均可搭配 DeepSpeed、FSDP、FlashAttention-2 等加速特性。

v1 与默认（legacy）启动器的路由关系

仓库中存在两套训练入口，由环境变量 USE_V1 切换。从 src/llamafactory/cli.py 可以看到这一路由逻辑：

def main():
    from .extras.misc import is_env_enabled

    if is_env_enabled("USE_V1"):
        from .v1 import launcher
    else:
        from . import launcher

    launcher.launch()

即 pip install 后统一的 llamafactory-cli 入口，在检测到 USE_V1=1 时加载 src/llamafactory/v1/launcher.py，否则加载 src/llamafactory/launcher.py。两者的命令集合并不完全相同：

• v1 启动器（src/llamafactory/v1/launcher.py）：train / sft / dpo / rm 四个训练命令（sft 与 train 最终都调用 run_sft()，因此二者等价），以及 chat、merge 命令。
• 默认启动器（src/llamafactory/launcher.py）：train、api、chat、webchat、webui（LlamaBoard 图形界面）、export（合并 LoRA 并导出）、env（打印环境信息）、version、help。

可以推断：需要 Web UI（LlamaBoard）或 export 等能力时应使用默认启动器（不设 USE_V1），而官方推荐的 FSDP2 全参数训练示例则运行在 v1 管线下。

2. 软件依赖

快速开始文档给出的最低与推荐版本如下。

必需项：

依赖	至少	推荐
python	3.11	3.12
torch	2.7.1	2.7.1
torch-npu (Ascend NPU)	2.7.1	2.7.1
torchvision	0.22.1	0.22.1
transformers	5.0.0	5.0.0
datasets	3.2.0	4.0.0
peft	0.18.1	0.18.1

可选项：

依赖	至少	推荐
CUDA (NVIDIA GPU)	11.6	12.2
deepspeed	0.18.4	0.18.4
flash-attn (NVIDIA GPU)	2.5.6	2.7.2

与构建配置交叉核对：pyproject.toml 声明 requires-python = ">=3.11.0"，核心依赖的区间约束为 torch>=2.4.0、transformers>=4.55.0,<=5.8.0、datasets>=2.16.0,<=4.0.0、peft>=0.18.0,<=0.18.1（见 pyproject.toml）。也就是说，pip install 实际接受的版本下限比文档表格更宽，而文档表格中的推荐版本（torch 2.7.1、transformers 5.0.0 等）可作为新环境的一键对齐基线。当前开发版本号为 0.9.6.dev0，定义于 src/llamafactory/extras/env.py。

3. 安装 LLaMA Factory

注意：此步骤为必需，请确保环境满足上一节的依赖要求。

3.1 从源码安装（推荐）

git clone --depth 1 https://gitcode.com/GitHub_Trending/ll/LlamaFactory.git
cd LlamaFactory
pip install -e .

3.2 使用 pip 安装

pip install llamafactory

3.3 可选依赖

如需要使用特定加速特性，按需追加安装：

# 安装 FlashAttention-2 支持
pip install flash-attn --no-build-isolation

# 安装 DeepSpeed 支持
pip install deepspeed

# 安装 Unsloth 支持（用于加速 LoRA 训练）
pip install unsloth

3.4 入口命令说明

安装后 pyproject.toml 注册了两个命令行入口：

[project.scripts]
llamafactory-cli = "llamafactory.cli:main"
lmf = "llamafactory.cli:main"

两者指向同一个 main() 函数，因此 lmf 是 llamafactory-cli 的等价短别名，后文命令可互换使用。

4. 数据准备

LLaMA Factory 支持 JSON、JSONL、CSV 等多种数据格式，字段级详细说明见 数据准备指南。

4.1 使用内置数据集

仓库自带若干用于快速验证的数据集，全部登记在 data/dataset_info.json 中。v1 训练示例直接引用 data/v1_sft_demo.yaml 描述的 SFT 演示数据，可直接跑通无需额外下载。

4.2 使用自定义数据集

你可以使用 HuggingFace / ModelScope 上的数据集，或加载本地数据集。

使用自定义数据集或自定义数据集格式时，请参照 数据准备指南 进行配置。如有必要，请重新实现自定义数据集的数据处理逻辑，包括对应的 converter。

4.3 数据构建工具

也可以借助社区工具构建用于微调的合成数据（文档中推荐的项目）：

• Easy Dataset —— 易于使用的数据集构建工具；
• DataFlow —— 高质量数据准备管道；
• GraphGen —— 基于图的数据生成工具。

5. 命令行训练：FSDP2 全参数微调示例

官方快速开始的默认示例是对 Qwen3-0.6B 使用 FSDP2 进行全参数微调：

export USE_V1=1
llamafactory-cli sft examples/v1/train_full/train_full_fsdp2.yaml

llamafactory-cli sft 与 llamafactory-cli train 等价（见第 1 节的路由分析）。下面把示例配置文件 examples/v1/train_full/train_full_fsdp2.yaml 的关键字段展开注释，方便按需修改：

model: Qwen/Qwen3-0.6B      # 基座模型，HF 仓库名或本地路径
model_class: llm            # 模型类别：llm（此处为纯文本语言模型）

kernel_config:
  name: auto                # 算子插件自动选择（如 FlashAttention 等内核）

quant_config: null          # 量化配置；QLoRA 场景下在此启用

dist_config:
  name: fsdp2               # 分布式后端：FSDP2
  dcp_path: null            # 可选的 DCP 预训练检查点目录

### data
train_dataset: data/v1_sft_demo.yaml   # 引用仓库内置演示数据集

### training
output_dir: outputs/test_fsdp2   # 检查点与日志输出目录
micro_batch_size: 1              # 微批次大小
cutoff_len: 2048                 # 单条样本最大 token 长度
learning_rate: 1.0e-4            # 学习率
max_steps: 10                    # 演示用步数上限，正式训练建议改为按 epoch

### sample
sample_backend: hf               # 采样/生成后端
max_new_tokens: 128              # 采样时最大生成 token 数

5.1 多卡环境会自动进入 torchrun 分布式

如果你直接执行 llamafactory-cli sft 而机器上有超过 1 张可见 GPU，v1 启动器无需你手动写 torchrun。从 src/llamafactory/v1/launcher.py 的源码结构看，当命令属于 _DIST_TRAIN_COMMANDS = ("train", "sft", "dpo", "rm") 且 get_device_count() > 1（或未显式使用 Ray / KTransformers）时，会自动以子进程方式调用 torchrun 拉起分布式任务，并支持通过 NNODES、NODE_RANK、NPROC_PER_NODE、MASTER_ADDR、MASTER_PORT 等环境变量扩展多机与弹性（RDZV）启动。单卡则直接进入单进程训练路径（src/llamafactory/v1/launcher.py）。

5.2 回归验证

v1 训练器配有端到端测试 tests_v1/trainers/test_fsdp2_sft_trainer.py 与 tests_v1/trainers/test_fsdp2_dpo_trainer.py，可在具备 GPU 的环境执行，用于验证 FSDP2 下 SFT/DPO 训练链路是否正常。

6. Web UI 训练（LlamaBoard）

llamafactory-cli webui

在浏览器中打开 http://localhost:7860 即可开始使用。需要注意命令路由：webui 子命令注册在默认（legacy）启动器中（src/llamafactory/launcher.py 调用 run_web_ui()），而 v1 启动器的命令集不含 webui，因此运行 Web UI 时不应设置 USE_V1=1。Web 界面的完整功能说明见 LlamaBoard 文档。

7. 推理部署

训练完成后，可将模型用于本地对话推理：

# 使用 vLLM 后端进行高性能推理
llamafactory-cli chat --model_name_or_path path/to/your/model --template qwen --infer_backend vllm

# 使用 HuggingFace 后端进行推理
llamafactory-cli chat --model_name_or_path path/to/your/model --template qwen

template 需与模型对应的对话模板一致（如 Qwen 系列使用 qwen）；infer_backend 缺省为 HuggingFace 后端，切换到 vllm 时请确保已安装 vLLM。部署场景（含 API 服务）可进一步参考 推理部署文档。

8. 进阶用法指引

快速开始文档指向的进阶主题，在当前仓库中文文档中的对应位置如下，可按需深入：

• 多卡多机分布式训练：并行策略（DP/TP/EP/SP/CP）、DeepSpeed、FSDP、FSDP-Turbo EP/EFSDP
• LoRA/QLoRA 微调：LoRA 指南
• 模型量化（AWQ/GPTQ 等）：量化指南
• 多模态模型微调：多模态示例配置、MOS 系列 VL 要求
• 训练超参数详解：训练参数、数据参数

配套的完整示例 YAML 汇总在 examples/README_zh.md，包括 DeepSpeed、Megatron、KTransformers、冻结训练等各场景配置。

9. 常见问题（FAQ）

9.1 内存不足怎么办？

• 使用 LoRA 或 QLoRA 代替全参数训练；
• 减小 batch_size 和 cutoff_len；
• 启用 gradient_checkpointing；
• 使用 DeepSpeed ZeRO-2 或 ZeRO-3（配置模板见 examples/deepspeed/ds_z3_config.json）。

9.2 如何选择合适的训练方法？

• SFT（指令微调）：最常用的方法，适用于大多数场景，通过监督数据训练模型，教程见 SFT 训练文档；
• DPO（直接偏好优化）：用于对齐人类偏好、提升模型输出质量，无需训练奖励模型，教程见 DPO 训练文档。

9.3 训练完成后如何评估模型？

文档给出的评估命令为：

llamafactory-cli eval --model_name_or_path path/to/your/model --template qwen --dataset mmlu

需要结合当前仓库状态注意一点：在 src/llamafactory/launcher.py 中，eval 子命令当前抛出 NotImplementedError，注释标明"评估功能将在未来被弃用（deprecated）"；评估器的实现仍保留在 src/llamafactory/eval/ 模块中。可以推断：在依赖当前仓库构建的环境里，评估能力的可用性取决于具体版本与入口，实际使用请先确认 llamafactory-cli 是否支持 eval 子命令。

10. 获取帮助

如果在使用过程中遇到问题，建议的排查路径：

1. 先用 llamafactory-cli env（默认启动器）打印完整环境信息（Python、PyTorch、Transformers、DeepSpeed、vLLM 等版本，实现见 src/llamafactory/extras/env.py），便于定位版本问题；
2. 查阅项目 GitHub Issues 提交的问题，看是否已有相同报错的解决方案；
3. 加入项目 Discord 社区或在项目微信群中向作者和其他贡献者提问。