日常使用 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_demo，template: qwen3_nothink，cutoff_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 还有哪些常用能力 除了 train，llamafactory-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。 结构清楚了，第四篇就可以专心讲数据怎么准备。