LLaMA-Factory 微调实战：从 GitHub 下载到跑通第一条训练命令

简介：本资源为从 GitHub 下载的 LLama-factory 完整源码包，面向大模型微调初学者与工程实践者，可用于本地搭建 LLaMA 系列模型的训练、微调与推理环境。压缩包共 408 个文件，约 231.59MB，以 146 个 Python 源码、108 个 pyc 编译文件、48 个 YAML 配置、23 个 JSON 参数文件为主，另含 txt 说明、md 文档、Dockerfile、Makefile 及少量图片与压缩子包，覆盖配置、脚本、容器化部署等模块，目录结构完整，便于按需检索与二次开发。目前已有 1728 人学习下载，适合希望快速上手 LLama-factory 微调流程、研究其配置体系与工程组织的读者参考使用。

1. 从 GitHub 拉下 LLama-factory 之后，先别急着 pip install

很多人第一次接触大模型微调，都是冲着 LLaMA-Factory 来的。它把数据准备、模型加载、LoRA/QLoRA、全参微调、DPO、推理评测这一整套流程收进了一个仓库，命令行和 WebUI 两条路都能走。你从 GitHub 上把包拉下来，解压或 clone 到本地，这一步其实只是拿到了“施工图纸”，离真正跑起来还差环境、数据格式、显存估算和参数配置四道关。我见过太多人卡在pip install -e .之后的第一个报错上，然后开始怀疑是不是包有问题。实际上，LLaMA-Factory 的坑大多不在代码本身，而在你对“微调一个模型到底需要什么”这件事的预期上。这篇笔记就按我自己的落地顺序，把从 GitHub 下载到跑通第一条训练命令的路径拆开讲，适合手里已经有一份代码、但还没让它动起来的人。

2. 环境与依赖：把“能跑”和“跑得动”分开处理

2.1 先确认你的 CUDA 和 PyTorch 是不是一对

从 GitHub 拉下来的 LLaMA-Factory，根目录下通常有requirements.txt和setup.py。很多人上来就pip install -r requirements.txt，结果 torch 版本被覆盖，和本机 CUDA 驱动对不上，训练时直接报CUDA error: no kernel image is available for execution on the device。我的习惯是先锁死 PyTorch，再装项目依赖。

# 先看驱动支持的 CUDA 上限，不要只看 nvcc nvidia-smi # 假设驱动支持 CUDA 12.1，装对应 torch，不要用默认最新版 pip install torch==2.1.2 torchvision==0.16.2 torchaudio==2.1.2 \ --index-url https://download.pytorch.org/whl/cu121 # 再进项目目录装其余依赖，让 pip 不要动 torch pip install -r requirements.txt --no-deps pip install -e . --no-deps

这里--no-deps是关键，它阻止 pip 在装其他包时顺带升级 torch。装完用下面这段验证，输出为 True 才算环境对齐。

import torch print(torch.__version__) print(torch.cuda.is_available()) print(torch.cuda.get_device_capability(0)) # 例如 (8, 6) 表示 30 系

参数说明：get_device_capability返回的是算力版本，后面选bf16还是fp16要看它。算力低于 8.0 的卡，bf16 支持不完整，硬开会在训练中途 loss 变 NaN。

2.2 用 conda 隔离，别在 base 里折腾

我一般会建一个独立环境，Python 版本选 3.10 或 3.11。3.12 在部分 flash-attn 预编译轮子上会翻车，这是血泪经验。

conda create -n llama_factory python=3.10 -y conda activate llama_factory # 后续所有 pip 操作都在这个环境里

如果你要用 WebUI，还需要额外装gradio和streamlit，但训练本身不依赖它们。先把训练跑通，再装界面，能少一半报错。

2.3 显存不够时，先算账再选方案

LLaMA-Factory 支持 LoRA、QLoRA、全参。很多人一上来就想全参微调 7B，结果 24G 卡直接 OOM。一个粗略的显存估算表：

这张表是经验值，实际还受 batch size、序列长度影响。如果你只有一张 12G 的卡，QLoRA 是唯一现实选择，别硬试全参。

3. 数据格式：LLaMA-Factory 认什么，你怎么喂

3.1 两种数据格式，选一种就别混

LLaMA-Factory 的data/目录下有一份dataset_info.json，里面注册了所有可用数据集。你自定义的数据要么走alpaca格式，要么走sharegpt格式。alpaca 适合单轮指令，sharegpt 适合多轮对话。

alpaca 格式长这样：

[ { "instruction": "把下面这句话翻译成英文", "input": "今天天气不错", "output": "The weather is nice today." } ]

sharegpt 格式长这样：

[ { "conversations": [ {"from": "human", "value": "你好，帮我写个快排"}, {"from": "gpt", "value": "好的，以下是 Python 实现..."} ] } ]

注意：from字段的值必须和dataset_info.json里配置的role_tag对应，默认是human和gpt。如果你写成user和assistant，训练时对话模板会匹配不上，loss 直接不降。

3.2 注册数据集：改 JSON 不是改代码

把数据文件放到data/下，然后在dataset_info.json里加一段：

{ "my_dataset": { "file_name": "my_data.json", "formatting": "alpaca", "columns": { "prompt": "instruction", "query": "input", "response": "output" } } }

参数说明：formatting决定用哪套模板，columns把你的字段名映射到框架内部字段。如果你的数据里没有input列，query可以留空字符串，但键要保留。改完不用重启，训练命令里dataset参数写my_dataset即可。

3.3 数据量少的时候，先做一遍 dry run

我一般会先用 100 条数据跑 10 步，确认 loss 在动、显存没爆、保存路径可写，再换全量数据。命令里加--max_samples 100和--max_steps 10，几分钟就能验证链路。

llamafactory-cli train \ --stage sft \ --do_train \ --model_name_or_path /path/to/base_model \ --dataset my_dataset \ --max_samples 100 \ --max_steps 10 \ --output_dir ./sft_dryrun \ --per_device_train_batch_size 1 \ --learning_rate 1e-4 \ --template default

--template要和基座模型匹配，Qwen 用qwen，Llama 用llama3，ChatGLM 用chatglm3。模板错了，模型学到的对话格式就是乱的。

4. 训练参数：LoRA 的 rank、alpha 和 target 怎么定

4.1 LoRA rank 不是越大越好

LoRA 的lora_rank默认 8，lora_alpha默认 16。rank 越大，可训练参数越多，显存和过拟合风险都上升。我的经验是：数据量小于 1 万条，rank 8 到 16 足够；数据量几万条以上，可以试 32 或 64。alpha 一般设成 rank 的两倍，或者等于 rank，两者比例影响更新幅度。

--lora_rank 16 \ --lora_alpha 32 \ --lora_dropout 0.05 \ --lora_target all

lora_target all表示对所有线性层加 LoRA。如果显存紧张，可以只加q_proj,v_proj，但效果会打折扣。lora_dropout在数据少时设 0.1，数据多时设 0.05 或 0。

4.2 学习率和 batch size 的联动

LLaMA-Factory 默认学习率 5e-5，这是全参微调的常用值。LoRA 通常需要更大学习率，1e-4 到 3e-4 比较常见。batch size 受显存限制，但可以用梯度累积模拟大 batch。

--per_device_train_batch_size 2 \ --gradient_accumulation_steps 8 \ --learning_rate 2e-4 \ --lr_scheduler_type cosine \ --warmup_ratio 0.1

等效 batch size = 2 × 8 × GPU 数。warmup_ratio 0.1 表示前 10% 步数线性升温，避免一开始就大步长震荡。cosine 调度在微调里比 linear 更稳。

4.3 精度选择：bf16、fp16 还是 fp32

--bf16 true # 算力 >= 8.0 且驱动支持时用 --fp16 true # 算力 < 8.0 时用，但需要 loss scaling

两者不能同时为 true。bf16 动态范围大，不容易溢出，优先选。如果卡不支持 bf16，用 fp16 时要留意 loss 是否出现 NaN，必要时加--fp16_full_eval或调小学习率。

5. 避坑与排查：那些让你怀疑人生的报错

5.1 现象：训练启动就报 KeyError: 'instruction'

原因：数据文件里字段名和dataset_info.json里columns映射不一致，或者 JSON 文件本身有语法错误，比如末尾多了逗号。解决：用python -m json.tool my_data.json先验证 JSON 合法性，再核对字段名。别用记事本改 JSON，用编辑器看括号配对。

5.2 现象：loss 一直是 0 或者不下降

原因：对话模板和基座模型不匹配，或者数据里 output 为空。解决：检查--template参数，Qwen 系列用qwen，Llama3 用llama3。再抽一条数据打印出来，确认 response 字段非空。如果用的是 sharegpt 格式，检查from字段值是否和dataset_info.json里的role_tag一致。

5.3 现象：CUDA out of memory，但显存看着还有余量

原因：PyTorch 缓存分配器碎片化，或者序列长度设太大。解决：加--per_device_train_batch_size 1和--gradient_checkpointing true，后者用时间换显存。还可以设--cutoff_len 512截断长序列。如果还不行，换 QLoRA，加--quantization_bit 4。

5.4 现象：保存的 LoRA 权重加载后推理没效果

原因：推理时没有合并 LoRA，或者 template 和训练时不一致。解决：推理命令里加--adapter_name_or_path ./sft_output，并保持--template和训练时相同。如果要用 vLLM 部署，需要先合并权重，LLaMA-Factory 提供了export命令。

5.5 现象：多卡训练时只有一张卡在跑

原因：没有用torchrun或accelerate launch启动，直接python跑只认单卡。解决：用accelerate config配好多卡，然后用accelerate launch启动训练脚本。或者用FORCE_TORCHRUN=1 llamafactory-cli train ...让框架自己拉起分布式。

6. 进阶技巧：用 WebUI 快速试参，用 CLI 固化流程

6.1 WebUI 适合找感觉，不适合复现

LLaMA-Factory 的 WebUI 启动命令是llamafactory-cli webui，打开后可以点选模型、数据集、LoRA 参数，点开始训练。它的价值在于快速试不同 rank 和 learning rate 的组合，但每次点选生成的参数不会自动保存成可复现的脚本。我的做法是：在 WebUI 里试出大致范围，然后把对应的 YAML 配置导出，用 CLI 跑最终训练。

# 导出 WebUI 里的配置为 yaml # 在 WebUI 界面点“导出配置”，保存为 train_config.yaml # 然后用 CLI 加载 llamafactory-cli train train_config.yaml

YAML 里可以写注释，比一长串命令行参数好维护。团队协作时，把 YAML 提交到 git，谁跑都用同一份配置。

6.2 用--plot_loss和日志判断是否过拟合

训练时加--plot_loss true，结束后会在输出目录生成training_loss.png。如果训练 loss 持续下降但验证 loss 开始上升，就是过拟合。这时候要么减 rank，要么加 dropout，要么早停。LLaMA-Factory 支持--eval_dataset和--eval_steps，别省这一步，否则你拿到的模型可能只是背下了训练集。

6.3 合并权重与量化导出

训练完的 LoRA 权重是分离的，部署前要合并：

llamafactory-cli export \ --model_name_or_path /path/to/base_model \ --adapter_name_or_path ./sft_output \ --template qwen \ --finetuning_type lora \ --export_dir ./merged_model \ --export_size 2 \ --export_legacy_format false

export_size是分片大小，2 表示 2GB 一片。合并后的模型可以直接用 transformers 加载，也可以用 vLLM 加速推理。如果显存不够，导出时加--export_quantization_bit 4生成 4bit 量化模型，但精度会掉一点，自己权衡。

6.4 一个我常犯的错：忘了清空输出目录

LLaMA-Factory 在output_dir已存在且非空时，默认会报错或覆盖。我习惯在训练脚本开头加一行rm -rf ./sft_output，但有一次手滑写成了rm -rf ./sft_output/，结果把上一轮最好的 checkpoint 删了。后来改成用时间戳命名输出目录，比如output_dir ./sft_$(date +%m%d_%H%M)，既不会覆盖，也能追溯。这个习惯帮我省了至少两次后悔药。希望帮到你。

本文还有配套的精品资源，点击获取