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

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

【免费下载链接】LlamaFactoryUnified Efficient Fine-Tuning of 100+ LLMs & VLMs (ACL 2024)项目地址: https://gitcode.com/GitHub_Trending/ll/LlamaFactory

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

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

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

提示：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. 软件依赖

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

必需项：

可选项：

与构建配置交叉核对：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 社区或在项目微信群中向作者和其他贡献者提问。

【免费下载链接】LlamaFactoryUnified Efficient Fine-Tuning of 100+ LLMs & VLMs (ACL 2024)项目地址: https://gitcode.com/GitHub_Trending/ll/LlamaFactory