BAdam 的八个参数：mode、switch_mode、update_ratio 与 mask_mode

2026-08-09

本文事实以 hiyouga/LlamaFactory 官方仓库 2026-08-09 的内容为准。文中每一个默认值都是从 src/llamafactory/hparams/finetuning_args.py 的 field(default=...) 里读出来的。我们没有安装、训练或部署过任何模型。

在 LlamaFactory 里，BAdam 不是一个训练阶段，也不是一个子命令，而是 finetuning_args.py 里带 badam_ 前缀的八个字段。你打开配置准备开它的时候，真正卡住你的问题往往不是”BAdam 是什么算法”，而是”这八行我一行都不写，跑起来到底是什么状态”。这篇只回答后面这个问题。

先把边界说死：BAdam 这个名字在本文里只当名字用。它的数学原理、收敛特性、跟别的优化器比谁更省资源——我们没有读过它的实现，一个字都不会写。本文能给的只有四件事：这八个字段确切叫什么、默认是什么、摆在哪一层、以及为什么”默认值”跟”推荐值”完全是两码事。

八个字段，一次看全

参数	默认值
`use_badam`	`False`
`badam_mode`	`"layer"`
`badam_start_block`	`None`
`badam_switch_mode`	`"ascending"`
`badam_switch_interval`	`50`
`badam_update_ratio`	`0.05`
`badam_mask_mode`	`"adjacent"`
`badam_verbose`	`0`

标题里说”八个”，就是不多不少这八个。它们有一个很省事的共同点：前缀完全统一，全部是 badam_ 开头，没有例外。这意味着你在自己的配置文件里排查漏项时，一次前缀搜索就能把这一族全部捞出来，不用担心某个字段被起了个不带前缀的名字藏在别处。

它们坐在哪一层

LlamaFactory 把超参按文件切开，src/llamafactory/hparams/ 目录下是这样的结构：

src/llamafactory/hparams/
  __init__.py
  data_args.py
  evaluation_args.py
  finetuning_args.py
  generating_args.py
  megatron_bridge_args.py
  model_args.py
  parser.py
  training_args.py

也就是说，超参被按数据、模型、微调、生成、评测、训练、Megatron 桥接分成了 8 个文件。这八个 badam_ 字段全部住在 finetuning_args.py 里，跟 stage（默认 "sft"）、finetuning_type（默认 "lora"）是同一个文件的邻居，也跟 lora_rank（默认 8）、pref_beta（默认 0.1）这些同属一层。

这个定位有个直接的实用含义：找这几个字段的时候别去翻 model_args.py（那边管的是 trust_remote_code、量化、推理后端这类东西），也别去 generating_args.py（那边是 temperature 默认 0.95、top_p 默认 0.7 那一组）。分层清楚了，翻源码对默认值的速度会快很多。

顺带说明一句：megatron_bridge_args.py、parser.py、training_args.py 这三个文件我们这次没有抽取字段，所以本文不会描述它们里面有什么。

第一个字段决定另外七个有没有意义

use_badam 默认是 False。这一条决定了一件很朴素的事：如果你没有把它显式打开，另外七个字段你写不写、写成什么，从配置的角度看都不产生区别。

这不是 BAdam 独有的排布。同一个文件里，use_galore 默认 False、use_apollo 默认 False；再往下还有一整串同样默认关闭的布尔开关：use_llama_pro、use_adam_mini、use_muon、pure_bf16、use_mca、use_megatron_bridge、use_hyper_parallel、use_dft_loss、use_asft_loss（配 asft_alpha=0.1）、use_eaft_loss（配 eaft_alpha=1.0）。

从默认值这一层能读出来的结论只有一个：这些进阶算法是”接进来了”，不是”默认开着”。你不动配置，它们全都是关的。这句话是从一堆 False 里直接读出来的，不涉及任何对算法本身的评价。

三个字符串旋钮：mode、switch_mode、mask_mode

这三个是标题点名的主角，默认值都是字符串字面量：

badam_mode 默认 "layer"
badam_switch_mode 默认 "ascending"
badam_mask_mode 默认 "adjacent"

到这里我必须停一下，说清楚本文不给什么：这三个字段各自还允许哪些取值，我们这次的抽取只覆盖了默认值，没有覆盖取值范围，所以本文一个候选值都不列。凭印象补全枚举是这类文章最常见的翻车方式——把一个不存在的取值写进正文，读者照抄进 YAML，报错时还以为是自己环境的问题。

想知道确切的可选值，唯一不会过期的办法是问工具本身：

llamafactory-cli train -h

Windows 的 cmd 下可以接一层过滤：

llamafactory-cli train -h | findstr badam

PowerShell 里把 findstr badam 换成 Select-String badam 即可。这两条只是把 -h 的输出筛一遍，属于通用的命令行用法，不是该项目文档里的内容。

两个数字：50 与 0.05

badam_switch_interval 默认 50，badam_update_ratio 默认 0.05。后者是这一族里唯一的浮点数。

这里有个特别容易串台的地方，值得单独点出来：同一个文件里，GaLore 和 APOLLO 各有一个 update_interval，两边的默认值都是 200。而 BAdam 这个叫 switch_interval，默认 50。名字不一样，别把 50 和 200 当成同一件事的两个取值——它们分属不同算法各自的参数，我们没有读过任何一方的实现，不知道这两个”间隔”在语义上是不是可比的，所以这里只做名称与数值的并列陈述，不做换算，也不做类比。

再看参数的形状差异，也是纯粹从字段名读出来的：GaLore 与 APOLLO 那一组有 rank、scale、proj_type 这类字段（两者 rank 同为 16、update_interval 同为 200，而 scale 一个是 2.0、一个是 32.0），BAdam 这一组里既没有 rank 也没有 scale，取而代之的是 mode / switch_mode / switch_interval / mask_mode 这一串。GaLore 与 APOLLO 的完整参数对照我们另有一篇专门讲，这里只借它们的字段名做个形状上的参照，不展开。

两个最容易被忽略的：start_block 与 verbose

badam_start_block 默认是 None。请注意：None 不是 0。这一族里 badam_verbose 的默认值确实是数字 0，而 badam_start_block 是 None，两者在配置语义上不是一回事。

同一个文件里还有一个更知名的 None 默认值可以对照：lora_alpha 的默认值也是 None，而不是某个具体数字。它的含义是”不显式设置时由代码另行决定”——那段决定逻辑我们没有读过，所以不推断它最终等于多少。badam_start_block 同理，我们只报告它默认是 None，不猜代码会拿它做什么。

badam_verbose 的默认值写的是数字 0，而不是 False——这一点我们只报告字面值，不去推断它背后声明成了什么类型。它默认是 0 这件事可以写，0 之外还允许哪些取值、各自会打印什么，我们没有核对，不写。

另外别把它和实验跟踪混为一谈。训练过程往外报的那一套在同一个文件里是另外九个字段：use_swanlab 默认 False、swanlab_project 默认 "llamafactory"、swanlab_mode 默认 "cloud"，其余如 swanlab_workspace、swanlab_run_name、swanlab_logdir 默认都是 None。其中 swanlab_api_key 默认 None，这是密钥类字段——写进配置文件时请用 <YOUR_API_KEY> 这样的占位符或改走环境变量，别把真实 key 提交进仓库。

“那我到底该设成多少”

这是本文唯一必须正面拒绝的问题：取决于你的数据和硬件，官方没有给通用值，我们也不会替它给。

理由不是谦虚，是我们确实没有依据。上面每一个数字的性质都只有一种——它是你不写这一行时代码会拿到的值。0.05 不是经验值，50 不是推荐值，"adjacent" 也不是”官方建议先这么试”。仓库文档口径里的默认值和”应该配多少”之间没有等号，这一点跟 README 里那张显存表标着 * estimated 是同一类问题：写在那里的数字有它自己的语境，脱离语境就会被读成承诺。

能给的只有三条纪律，都不涉及具体取值：

默认值 ≠ 推荐值。 看到一个数字先问它是”缺省落点”还是”作者建议”，这两者在源码里长得一模一样。
以 llamafactory-cli train -h 的实际输出为准。 参数和默认值会随版本变动，本文核对的是 2026-08-09 这一天的仓库状态。
抄别人的 YAML 之前先核字段是否还在。 网上的配置片段常常跨了好几个版本，字段被改名或移除时，多数情况下你只会看到一个不太好懂的报错。

把默认值抄成配置长什么样

纯粹为了看清形状，把上面的值原样落成 YAML 是这样（badam_start_block 因为默认是 None 而没有列进来）：

use_badam: true
badam_mode: layer
badam_switch_mode: ascending
badam_switch_interval: 50
badam_update_ratio: 0.05
badam_mask_mode: adjacent
badam_verbose: 0

这七行里只有第一行真正改变了什么，后面六行写的都是不写也一样的值。把它们显式写出来的好处是配置自解释——半年后回头看能一眼知道当时用的是哪一档；坏处是版本升级后默认值若有变动，你会被这份配置钉在旧值上而不自知。这两条都是配置管理的常识，不是该项目的官方建议。

以上为按官方参数语义组合的示例，未逐项实测，以官方文档与 --help 的实际输出为准。另外提醒一句：我们这次抽取的是参数定义文件本身，没有核对 examples/ 目录下是否有对应的 BAdam 示例配置，所以别把上面这段当成官方示例来引用；要照抄示例，请自己去仓库的 examples/ 下确认。

什么情况下你根本不用纠结这八个字段

最后收一句边界。如果你的配置里 use_badam 仍然是 False，那另外七个字段完全不必出现在你的 YAML 里——它们既不会生效，也不会因为缺席而报错。而如果你只是想先把第一次 SFT 跑通，finetuning_args.py 的默认姿态已经是一条完整路径：stage 默认 "sft"、finetuning_type 默认 "lora"、lora_rank 默认 8、lora_target 默认 "all"，这条路上一个 badam_ 字段都不需要写。

进阶优化器这一层的价值在于”需要的时候它在那儿”，而不是”每个人第一天都得先决定用哪个”。

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