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 种主流大语言模型的微调训练。当前版本对训练方法与训练范式的支持矩阵如下方法全参数训练部分参数训练LoRAQLoRA指令监督微调 (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_V11时加载 src/llamafactory/v1/launcher.py否则加载 src/llamafactory/launcher.py。两者的命令集合并不完全相同v1 启动器src/llamafactory/v1/launcher.pytrain/sft/dpo/rm四个训练命令sft与train最终都调用run_sft()因此二者等价以及chat、merge命令。默认启动器src/llamafactory/launcher.pytrain、api、chat、webchat、webuiLlamaBoard 图形界面、export合并 LoRA 并导出、env打印环境信息、version、help。可以推断需要 Web UILlamaBoard或export等能力时应使用默认启动器不设USE_V1而官方推荐的 FSDP2 全参数训练示例则运行在 v1 管线下。2. 软件依赖快速开始文档给出的最低与推荐版本如下。必需项依赖至少推荐python3.113.12torch2.7.12.7.1torch-npu (Ascend NPU)2.7.12.7.1torchvision0.22.10.22.1transformers5.0.05.0.0datasets3.2.04.0.0peft0.18.10.18.1可选项依赖至少推荐CUDA (NVIDIA GPU)11.612.2deepspeed0.18.40.18.4flash-attn (NVIDIA GPU)2.5.62.7.2与构建配置交叉核对pyproject.toml 声明requires-python 3.11.0核心依赖的区间约束为torch2.4.0、transformers4.55.0,5.8.0、datasets2.16.0,4.0.0、peft0.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 llamafactory3.3 可选依赖如需要使用特定加速特性按需追加安装# 安装 FlashAttention-2 支持 pip install flash-attn --no-build-isolation # 安装 DeepSpeed 支持 pip install deepspeed # 安装 Unsloth 支持用于加速 LoRA 训练 pip install unsloth3.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_V11 llamafactory-cli sft examples/v1/train_full/train_full_fsdp2.yamlllamafactory-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 张可见 GPUv1 启动器无需你手动写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 训练LlamaBoardllamafactory-cli webui在浏览器中打开http://localhost:7860即可开始使用。需要注意命令路由webui子命令注册在默认legacy启动器中src/llamafactory/launcher.py 调用run_web_ui()而 v1 启动器的命令集不含webui因此运行 Web UI 时不应设置USE_V11。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 qwentemplate需与模型对应的对话模板一致如 Qwen 系列使用qweninfer_backend缺省为 HuggingFace 后端切换到vllm时请确保已安装 vLLM。部署场景含 API 服务可进一步参考 推理部署文档。8. 进阶用法指引快速开始文档指向的进阶主题在当前仓库中文文档中的对应位置如下可按需深入多卡多机分布式训练并行策略DP/TP/EP/SP/CP、DeepSpeed、FSDP、FSDP-Turbo EP/EFSDPLoRA/QLoRA 微调LoRA 指南模型量化AWQ/GPTQ 等量化指南多模态模型微调多模态示例配置、MOS 系列 VL 要求训练超参数详解训练参数、数据参数配套的完整示例 YAML 汇总在 examples/README_zh.md包括 DeepSpeed、Megatron、KTransformers、冻结训练等各场景配置。9. 常见问题FAQ9.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. 获取帮助如果在使用过程中遇到问题建议的排查路径先用llamafactory-cli env默认启动器打印完整环境信息Python、PyTorch、Transformers、DeepSpeed、vLLM 等版本实现见 src/llamafactory/extras/env.py便于定位版本问题查阅项目 GitHub Issues 提交的问题看是否已有相同报错的解决方案加入项目 Discord 社区或在项目微信群中向作者和其他贡献者提问。【免费下载链接】LlamaFactoryUnified Efficient Fine-Tuning of 100 LLMs VLMs (ACL 2024)项目地址: https://gitcode.com/GitHub_Trending/ll/LlamaFactory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考