`examples/` 的配方矩阵：18 个 extras 目录与算法开关一一对应

2026-08-09

本文事实以 hiyouga/LlamaFactory 官方仓库 2026-08-09 的内容为准。我们没有安装、训练或部署过任何模型，文中目录与参数均为仓库实读值。

很多人打开 LlamaFactory 的 examples/，第一反应是「配置怎么这么多」，然后随手挑一个最像的复制走。这其实是把一张有结构的矩阵当成了杂物箱。这个目录不是按主题堆的，它是按四条互不相同的轴切开的，认清轴之后，找配置就变成了「先定位轴，再定位格子」。

这篇不讲某一份 YAML 该怎么改，只讲这张矩阵怎么读——尤其是 extras/ 那 18 个子目录，它们和源码里的算法开关是能一格一格对上号的。

先把一级目录树摆出来

我们实读 examples/ 目录，一级内容是两份 README 加 13 个目录：

examples/
  README.md  README_zh.md
  accelerate/  ascend/  deepspeed/  extras/  inference/  ktransformers/
  megatron/  megatron_bridge/  merge_lora/  train_full/  train_lora/  train_qlora/  v1/

这 13 个目录如果按字母序读，会显得毫无逻辑：ascend 和 extras 挨着，但它们根本不是一个维度的东西。按下面四条轴重排一遍，结构立刻就出来了：

轴	目录	这条轴回答的问题
微调方式	`train_lora/`、`train_qlora/`、`train_full/`	你打算用哪种方式改权重
生命周期阶段	`inference/`、`merge_lora/`	训完之后这个产物怎么用
运行后端	`accelerate/`、`ascend/`、`deepspeed/`、`ktransformers/`、`megatron/`、`megatron_bridge/`、`v1/`	它跑在什么硬件与什么并行栈上
高级算法	`extras/`	你要额外打开哪个算法开关

四条轴是正交的：train_lora/ 和 deepspeed/ 不是二选一的关系，而是分别回答了两个不同的问题——这也是为什么 train_lora/ 里会有一份 qwen3_lora_sft_ds3.yaml，它是「LoRA」这个格子和「DeepSpeed ZeRO-3」这个格子的交叉。理解了这一点，你就不会再纠结「我该进 train_lora 还是进 deepspeed」这种问错方向的问题。

有一条边界必须先讲清楚：后端那一列的七个目录，里面具体的 YAML 我们没有读过。本文只写「仓库为 accelerate / Ascend / DeepSpeed / KTransformers / Megatron / Megatron-Bridge / v1 各准备了独立的示例目录」这一层目录事实，不描述任何一份我们没读过的配置写了什么。

`extras/` 的 18 个子目录，是本篇的重点

实读 examples/extras/，下面有 18 个子目录：

adam_mini  apollo  asft  badam  dft  eaft  fp8  fsdp_qlora  galore
llama_pro  loraplus  mod  multi_tokens  muon  nlg_eval  oft  pissa  qoft

把这份清单和 src/llamafactory/hparams/finetuning_args.py 里的字段名并排看，对应关系相当直接。下面这张表是从两处文件名与字段名交叉读出来的，右列的默认值全部来自源码 field(default=...)：

`extras/` 子目录	对应的参数	源码默认值
`galore`	`use_galore`	`False`（配 `galore_rank=16`、`galore_update_interval=200`、`galore_scale=2.0`、`galore_proj_type="std"`、`galore_layerwise=False`）
`apollo`	`use_apollo`	`False`（配 `apollo_rank=16`、`apollo_update_interval=200`、`apollo_scale=32.0`、`apollo_proj="random"`）
`badam`	`use_badam`	`False`（配 `badam_mode="layer"`、`badam_switch_interval=50`、`badam_update_ratio=0.05`）
`adam_mini`	`use_adam_mini`	`False`
`muon`	`use_muon`	`False`
`llama_pro`	`use_llama_pro`	`False`
`dft`	`use_dft_loss`	`False`
`asft`	`use_asft_loss`	`False`（配 `asft_alpha=0.1`）
`eaft`	`use_eaft_loss`	`False`（配 `eaft_alpha=1.0`）
`loraplus`	`loraplus_lr_ratio`	`None`（配 `loraplus_lr_embedding=1e-6`）
`pissa`	`pissa_init`	`False`（配 `pissa_iter=16`、`pissa_convert=False`）
`oft`	`oft_rank`	`0`（配 `oft_block_size=32`、`oft_target="all"`）
`mod`	`mixture_of_depths`	`None`

读这张表要注意三件事。

第一，这些算法名在本文里只是名字。 GaLore、APOLLO、BAdam、OFT、PiSSA 这些词，我们只核对了它们在参数表和目录名里的写法，没有读过任何一个的实现，因此本文不描述它们的数学原理、收敛特性或效果差别，也不会告诉你哪个更适合你。

第二，几乎所有算法开关的默认值都是「关」。 布尔类的一水儿 False，loraplus_lr_ratio 与 mixture_of_depths 默认 None，oft_rank 默认 0。也就是说，examples/README.md 的 Extras 一节里列出的那一长串高级算法（GaLore、APOLLO、BAdam、Adam-mini、Muon、LoRA+、PiSSA、Mixture-of-Depths、LLaMA-Pro、FSDP+QLoRA、OFT、QOFT），性质是「接进来了」而不是「默认开着」——你不去 extras/ 里找对应的示例配置，它们就一直躺着。这一层「目录 ↔ 开关」的对应，本质上就是仓库在说：每个接进来的算法，都配了一份可以直接跑的示例配置。

第三，mod 这一格的开关不在 finetuning_args.py 里。 上面 12 个对应项都落在微调参数那一层，唯独 mixture_of_depths 是 model_args.py 的字段（默认 None）。这就是配置类问题最容易踩空的地方：同一个功能，示例目录名、参数名、参数所在的文件三者未必在同一层。你在 finetuning_args.py 里搜 mod 搜不到东西时，不是它不存在，是找错了文件。

剩下那五个目录，我们只陈述现状

18 个子目录里，上表覆盖了 13 个。剩下的五个是 fp8、fsdp_qlora、multi_tokens、nlg_eval、qoft。

在本文依据的参数抽取范围内（finetuning_args.py / model_args.py / generating_args.py / evaluation_args.py 的字段清单），这五个目录名没有找到与之同名的独立开关。其中 qoft 从命名上看与 OFT 那一族（oft_rank / oft_block_size / oft_target）同源，但我们抽取到的字段里没有出现一个叫 use_qoft 的项。

这里我只把现状说到这儿。这几个目录对应的参数是否写在我们没有抽取字段的那几个文件里（hparams/ 下还有 megatron_bridge_args.py、parser.py、training_args.py 三个文件我们没有抽取）、还是走了别的机制，我们没有核实，因此不做任何推断，也不拿这个差异去评价什么。你要用这几个目录时，直接去看目录里的 YAML 写了哪些字段，比猜要快。

README 的配方清单里，只有一条带了 (Recommended)

examples/README.md 用章节标题把配方列成了一份清单：LoRA Fine-Tuning 一节里有（持续）预训练、监督微调、多模态监督微调、DPO/ORPO/SimPO 训练、奖励建模、KTO 训练、预处理数据集、多节点监督微调、带 DeepSpeed ZeRO-3 的监督微调、在 4 张 GPU 上用 Ray 做监督微调；QLoRA 一节列了 4/8-bit Bitsandbytes/HQQ/EETQ、Ascend NPU 上的 4-bit Bitsandbytes、4/8-bit GPTQ、4-bit AWQ、2-bit AQLM 五条量化路径；Full-Parameter 一节除了单节点与多节点，还单独列了一条多节点弹性容错监督微调；后面依次是合并 LoRA 与量化、保存 Ollama modelfile、推理 LoRA 微调后的模型，最后才是 Extras。

这份清单里有一处标注值得单独拎出来：五条量化路径中，README 只在「4/8-bit Bitsandbytes/HQQ/EETQ 量化」那一条上标了 (Recommended)，GPTQ、AWQ、AQLM 三条没有这个标注。这是 README 自己的标注，我如实转述——它标了什么就是什么，至于为什么这样标、其它路径是不是不能用，README 没说，我也不替它说。你如果没有特别的理由必须走某条量化路径，从带标注的那条开始找示例，至少省一轮排除法。

另一个结构性的点是「弹性容错」被抬成了独立一节，而不是塞在多节点那条里。这与仓库环境变量那一组「elastic launch support」的变量（MAX_RESTARTS、RDZV_ID、MIN_NNODES、MAX_NNODES）是对应的——分布式与容错这块我们另有一篇专门讲，这里只指出示例目录和环境变量两侧都给它留了独立位置。

顺带一提，ORPO 和 SimPO 在 README 清单里是和 DPO 并列在同一条标题下的，代码侧的 src/llamafactory/train/ 下并没有它们各自的目录，对应的是 pref_loss（默认 "sigmoid"）和 simpo_gamma（默认 0.5）这类偏好损失参数。这件事我们也另有一篇专门讲。

实际找配置时的顺序

把四条轴反过来用，就是一条可执行的定位路径：

先定微调方式：全参、LoRA 还是 QLoRA，决定你进 train_full/、train_lora/ 还是 train_qlora/。这一步定不下来，后面都是空转。
再定阶段：只是训练，就停在上一步；要把产物用起来，inference/ 和 merge_lora/ 分别对应「挂着适配器跑」和「把适配器并回权重」。
看要不要换后端：默认路径不需要动后端目录；确定要上 DeepSpeed、Ascend、Megatron 这类栈时，再去对应目录找。
最后才看 extras/：只有当你明确要开某一个算法开关时，才进这个目录，按上面那张表按图索骥。

这个顺序的意义在于：extras/ 是最后一步，不是第一步。 那 18 个目录名看起来很有吸引力，但上表核对过的那 13 个开关全都默认关着（剩下五个我们连同名开关都没抽到，更谈不上「默认开着」），且我们没有任何依据告诉你哪个该开、开到多少。这些值该怎么设，取决于你的数据、模型和硬件，官方也没有给出通用值。

至于三份 Quickstart 配置（训练、推理、合并）字段是怎么严格对齐的、LoRA 那份 YAML 逐块怎么读、trust_remote_code 在源码默认值与示例 YAML 之间的那处差异，我们各有专门篇目讲。这篇只负责把 examples/ 这张矩阵的坐标系交代清楚——认清坐标系之后，剩下的就是在格子里找文件了。

本文依据 LlamaFactory 官方仓库（github.com/hiyouga/LlamaFactory）的 README、data/README.md、examples/ 下的配置与 src/llamafactory/hparams/ 的参数定义整理，核对日 2026-08-09。本文内容为仓库源码与文档口径，我们没有安装、训练或部署过任何模型，文中显存数字均为官方标注的估算值（README 原文标 * estimated）而非实测占用。参数与默认值随版本变动，请以 llamafactory-cli train -h 的实际输出为准。