简介本资源为从 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 torch2.1.2 torchvision0.16.2 torchaudio2.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 python3.10 -y conda activate llama_factory # 后续所有 pip 操作都在这个环境里如果你要用 WebUI还需要额外装gradio和streamlit但训练本身不依赖它们。先把训练跑通再装界面能少一半报错。2.3 显存不够时先算账再选方案LLaMA-Factory 支持 LoRA、QLoRA、全参。很多人一上来就想全参微调 7B结果 24G 卡直接 OOM。一个粗略的显存估算表微调方式7B 模型显存需求说明全参 fp16约 80G 以上需要多卡或 A100LoRA fp16约 18-22G单张 3090/4090 可跑QLoRA 4bit约 10-14G单张 3080 10G 勉强推理 only约 14G不训练只对话这张表是经验值实际还受 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 用qwenLlama 用llama3ChatGLM 用chatglm3。模板错了模型学到的对话格式就是乱的。4. 训练参数LoRA 的 rank、alpha 和 target 怎么定4.1 LoRA rank 不是越大越好LoRA 的lora_rank默认 8lora_alpha默认 16。rank 越大可训练参数越多显存和过拟合风险都上升。我的经验是数据量小于 1 万条rank 8 到 16 足够数据量几万条以上可以试 32 或 64。alpha 一般设成 rank 的两倍或者等于 rank两者比例影响更新幅度。--lora_rank 16 \ --lora_alpha 32 \ --lora_dropout 0.05 \ --lora_target alllora_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 系列用qwenLlama3 用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_TORCHRUN1 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.yamlYAML 里可以写注释比一长串命令行参数好维护。团队协作时把 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 falseexport_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)既不会覆盖也能追溯。这个习惯帮我省了至少两次后悔药。希望帮到你。本文还有配套的精品资源点击获取
