日常使用 LLaMA Factory九成时间只需要动两个地方examples 里的 yaml 配置和 data 里的数据集。核心代码在 src/llamafactory出问题再往里查。一条 train 命令的背后是读配置、读数据、加载模型、进入训练、保存结果。搞清这条链就不会在项目里迷路。一、先认地图不必先啃源码 打开 LLaMA Factory 项目根目录最先值得认识的文件夹只有几个。examples 存放各种 yaml 配置是「抄作业」的首选。data 放数据集和 dataset_info.json 注册表。src/llamafactory 是核心代码。docs 是官方文档源文件。scripts 是一些辅助脚本。 对初学者来说日常工作的重心在 examples 和 data。只有当你要深度定制、排查底层行为才需要进入 src/llamafactory。这个顺序很重要不要一上来就扎进 Python 文件先把 yaml 玩熟效率更高。二、核心代码各自管什么 src/llamafactory 里launcher.py 是 llamafactory-cli 的入口。hparams 定义并校验所有训练参数。data 负责读数据、拼对话、做 tokenize。model 负责加载基座模型、挂 LoRA、做量化。train 按阶段组织训练流程比如 sft、dpo、ppo。webui 是 LlamaBoard 网页界面。api 提供 OpenAI 风格的 HTTP 服务。chat 负责命令行推理和 vLLM 等后端。 另外还有一个较新的 v1 子目录代表下一代训练框架。日常上手仍然以经典路径为主也就是 train 目录加 yaml 配置。等主路走通再了解 v1 不迟。三、一条 train 命令背后发生了什么 以 llamafactory-cli train examples/train_lora/qwen3_lora_sft.yaml 为例简化后的流程是这样的 launcher 收到 train 子命令读取 yaml把字段转成内部参数对象。接着加载 tokenizer按 template 修正特殊 token。然后从 data 目录读取数据集预处理成模型能吃的输入。再加载基座模型如果配置了 LoRA就挂上 adapter。最后进入 SFT 训练循环按步数保存 checkpoint可选地绘制 loss 曲线。 如果以后要排查问题可以按这个顺序想是配置错了是数据错了是模型加载错了还是训练本身的问题。对应代码大致在 train/tuner.py、train/sft/workflow.py、data/loader.py、data/template.py、model/loader.py、model/adapter.py。现在不必逐文件阅读知道「训练逻辑在这几块」就够了。四、yaml 配置文件怎么读 yaml 是按块组织的读的时候按块理解比记零散参数轻松得多。 model 块决定用哪个基座比如 model_name_or_path: Qwen/Qwen3-4B-Instruct。 method 块决定怎么训stage: sft 表示监督微调finetuning_type: lora 表示用 LoRA。 dataset 块决定用什么数据、多长序列、什么对话格式比如 dataset: identity,alpaca_en_demotemplate: qwen3_nothinkcutoff_len: 2048。 output 块决定结果存哪、多久存一次、是否画 loss 图。 train 块是学习率、batch、epoch 这些训练超参。 改实验最省事的做法是复制一份最接近你需求的 yaml改几行另存为新文件。这比每次拼一长串命令行参数可靠得多。五、examples 目录怎么逛 train_lora 里是 LoRA 微调最常用。train_qlora 是四 bit 量化加 LoRA显存紧张时用。train_full 是全量微调资源充足且确实需要时再考虑。inference 是推理和聊天配置。merge_lora 是合并 LoRA 导出完整模型。extras 里是 GaLore、LongLoRA 等特殊玩法。 不要从零写配置。找到最接近你场景的 yaml复制、改名、微调这是老手也在用的方法。六、CLI 还有哪些常用能力 除了 trainllamafactory-cli chat 用于命令行聊天export 用于合并和导出模型webui 打开 LlamaBoard 网页api 启动 API 服务webchat 打开纯聊天网页env 查看环境信息。 机器上有多张 GPU 时train 通常会自动走分布式一般不需要手写 torchrun。这对新手是友好的硬件到位了软件侧少一道门槛。七、训练完成后output_dir 里有什么 以 saves/qwen3-4b/lora/sft/ 为例常见内容有 adapter_config.json、adapter_model.safetensors、trainer_state.json如果开了 plot_loss 还有 training_loss.png以及 checkpoint-500 这类中间存档。 这里要建立一个关键认知LoRA 训完产物主要是 adapter 小文件基座模型并没有被改掉仍然在 Hugging Face 或你的本地路径里。部署时要么「基座加 adapter 一起加载」要么先 merge 成完整模型。八、用一张心智图收束 yaml 配置进入 llamafactory-cli train兵分两路一路读 data一路加载 model两路汇合后进入 train 下的具体阶段比如 SFT最终输出到 saves 目录。 想改训练参数去 examples 里的 yaml。想准备数据去 data 和 dataset_info.json。想查参数含义看官方文档和 yaml 注释。想查训练逻辑去 src/llamafactory/train。想用网页操作运行 llamafactory-cli webui。 结构清楚了第四篇就可以专心讲数据怎么准备。