rsLoRA、DoRA、PiSSA、LoRA+：四个开关分别控制什么

2026-08-09

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

这四个名字经常被并排提起，容易让人以为它们是「LoRA 的四种流派」，得挑一个。但在 LlamaFactory 的参数层面，它们是四组彼此独立、默认全部关闭的开关，写在同一个文件 src/llamafactory/hparams/finetuning_args.py 里。真正值得先搞清楚的不是「哪个更好」，而是「它们各自长什么样、怎么才知道自己有没有开着」——因为这四组的开关形态并不统一，其中一组你 grep use_ 根本找不到。

先把这几行原样摆出来

finetuning_args.py 里 LoRA 那一段的参数不少，这篇只取跟这四个变体直接相关的行——lora_rank（默认 8）、lora_target（默认 "all"）、lora_alpha（默认 None）那几项另有一篇专门讲，这里不重复搬表。

参数	默认值	属于哪一组
`use_rslora`	`False`	rsLoRA
`use_dora`	`False`	DoRA
`pissa_init`	`False`	PiSSA
`pissa_iter`	`16`	PiSSA
`pissa_convert`	`False`	PiSSA
`loraplus_lr_ratio`	`None`	LoRA+
`loraplus_lr_embedding`	`1e-6`	LoRA+

只看这张表就能读出一件事：四组开关的”关闭态”写法有三种。

三种开关形态，对应三种排查动作

第一种，纯布尔单开关：use_rslora 和 use_dora，各自只有一个字段，默认都是 False，没有任何配套的数值参数。这两个在配置里的存在感是最直白的——YAML 里有这一行且为 true，就是开了；没这一行，就是没开。

第二种，布尔加配套数值：PiSSA 一组三个字段，pissa_init（False）、pissa_iter（16）、pissa_convert（False）。这里有个容易看走眼的地方：pissa_iter 默认值是 16，是这一组里唯一一个非布尔、非零的数字。也就是说，即使 pissa_init 是 False，pissa_iter 也已经带着一个具体值待在那儿。所以只凭”我在参数列表里看到 pissa_iter=16”来判断 PiSSA 开没开，是判断错的——要看的是 pissa_init。至于 pissa_convert 具体在做什么、和 pissa_init 是什么先后关系，我们只读了参数定义、没读实现，这里不推断。

第三种，没有 use_ 开关：LoRA+ 这一组只有两个字段，loraplus_lr_ratio（默认 None）和 loraplus_lr_embedding（默认 1e-6）。我们从 finetuning_args.py 抽出的这一组字段里没有 use_loraplus 这样的布尔量，“未启用”是靠 loraplus_lr_ratio 默认为 None 来表达的。这一点的实际影响很具体：如果你习惯了用「搜 use_ 前缀」的办法快速盘一遍自己开了哪些特性，LoRA+ 会整个从你的清单里漏掉。而另一个字段 loraplus_lr_embedding 默认就已经是 1e-6 这个具体数值，它同样不代表 LoRA+ 处于启用状态。

顺带说一句同组里另外两个容易和这四个混在一起的字段：create_new_adapter（默认 False）和 module_dropout（默认 0.0）。它们也在这一段里，但不属于上面四组中的任何一组，看配置时别顺手归错类。

它们在哪一层，以及这一层管到哪儿

LlamaFactory 把超参按数据、模型、微调、生成、评测、训练、Megatron 桥接拆成了 8 个文件放在 src/llamafactory/hparams/ 下。这四组开关全部落在 finetuning_args.py，和它们同文件的还有 stage（默认 "sft"）与 finetuning_type（默认 "lora"）。

分层这件事在实操里是有意义的：同一个概念在不同文件里可能有不同的取值口径。仓库里现成的一个例子是 trust_remote_code——它属于 model_args.py，源码默认值是 False，而 examples/ 下的示例 YAML（train_lora/qwen3_lora_sft.yaml、inference/qwen3_lora_sft.yaml、merge_lora/qwen3_lora_sft.yaml）里都显式写了 trust_remote_code: true。代码默认保守、示例配置显式打开，这两处口径不一致是可以直接核实的客观差异。为什么会这样、哪一处”才对”，我们不推断；该不该开也不给建议，这是要你结合自己的环境去判断的事。

回到这四组开关本身：它们和 finetuning_type 在同一个文件里，但把 finetuning_type 换成非 lora 的值之后这些开关是否还生效，取决于源码里那段解析逻辑——我们没读，不下结论。

默认全关意味着什么

一个直接的推论是：如果你拿官方 examples/train_lora/ 下的示例 YAML 起步，而没有额外加这些行，你跑的就是不带这四个变体的配置。use_rslora、use_dora、pissa_init 三个布尔默认是 False，loraplus_lr_ratio 默认是 None。

这一点值得单独点出来，是因为 README 的 Features 那节会把这些名字都列出来：DoRA、LoRA+、PiSSA 出现在 Advanced algorithms 这一条里（同一条里还有 GaLore、BAdam、APOLLO、Adam-mini、Muon、OFT、LongLoRA、LLaMA Pro、Mixture-of-Depths、LoftQ），rsLoRA 则被归在另一条 Practical tricks 下（与 FlashAttention-2、Unsloth、Liger Kernel、KTransformers、RoPE scaling、NEFTune 并列）。这是 README 自称的分组，我们没有核实过分组依据。要注意的是：名字出现在特性列表里，说明的是”这个开关接进来了”，不是”它默认开着”。这两件事在读文档时最容易混。

那到底该开哪个、`pissa_iter` 该设多少

不给。这不是卖关子，是我们确实没有依据。

我们手上能核实的只有 field(default=...) 里的字面值，既没有官方给出的通用推荐值，也没有任何本机训练数据——这一批文章从头到尾没有 pip install 过 LlamaFactory，更没有训练过模型。开哪个、pissa_iter 设多少、loraplus_lr_ratio 填什么，取决于你的数据、你的基座模型和你的硬件，官方没有给出一个通用值，我们也不打算凭印象编一个。

同理，这四个算法各自的数学含义、彼此的取舍关系，这篇一句都不写——我们只读了参数定义，没读实现，写了就是编。要看原理请去各自的论文与 PEFT 侧文档。

往下游看：三个会被牵动的点

在事实有依据的范围内，有三处跟这几个开关相邻、值得顺手看一眼：

一是名字里带 rank 的字段不止一个。lora_rank 在 finetuning_args.py 里默认 8；而 model_args.py 的推理后端参数里另有一个 vllm_max_lora_rank，默认 32。这是两个文件里的两个独立默认值，名字相近但分属不同的参数层。它们之间有没有约束关系、要不要保持某种对应，源码里那段逻辑我们没读，不下结论——以官方文档和 --help 输出为准。

二是合并阶段有一条明确禁令。examples/merge_lora/qwen3_lora_sft.yaml 顶部有一行原文注释：

### Note: DO NOT use quantized model or quantization_bit when merging lora adapters

全大写的 DO NOT，意思是合并 LoRA 适配器时不要使用量化模型或 quantization_bit。如果你训完打算把适配器合回基座，这一行要先看。同一个示例文件里的其它值：export_size: 5、export_device: cpu（注释标了 choices: [cpu, auto]）、export_legacy_format: false，与 model_args.py 的源码默认一致。

三是量化那一侧的默认是开着的。double_quantization 源码默认 True，README 在 Ascend NPU 那节要求用户显式设成 false——默认开着，所以那个场景才需要一条专门的提示。这跟上面四个开关不是一回事，但它们经常出现在同一份 YAML 里。

Windows 侧的一句提醒

这四组开关都写在 YAML 配置里，跟操作系统无关，两个平台的写法完全一样。真正分平台的是环境变量。比如需要切换模型下载源时：

# Linux / macOS
export USE_MODELSCOPE_HUB=1

:: Windows
set USE_MODELSCOPE_HUB=1

Windows 用 set、Linux/macOS 用 export，别把两种写法混在一起用。同一份 YAML 换台机器就对不上时，除了 YAML 本身，这类进程外的环境变量也值得比一比——它不写在配置文件里，diff 两份 YAML 是看不出来的。

怎么自己核一遍

上面每个值都可以在两分钟内自己验一遍，不用相信我：

打开 src/llamafactory/hparams/finetuning_args.py，搜参数名，看紧跟着的 field(default=...)；
LoRA+ 直接搜 loraplus，你会确认这一组确实没有 use_ 前缀的布尔；
想看你这次实际跑的是什么，以 llamafactory-cli train -h 的实际输出为准——参数与默认值会随版本变动，这篇写的是 2026-08-09 这一天的仓库状态。

至于 lora_rank / lora_target / lora_alpha 这三个基础参数怎么读、OFT 那一组三个参数是什么、GaLore 与 APOLLO 的参数表怎么对照，我们另有专门篇目讲，这篇只负责把这四组变体开关的形态和边界交代干净。

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