LlamaFactory 的 LoRA 参数：`lora_rank` 8、`lora_target` all，以及默认是 `None` 的 `lora_alpha`

本文所有事实以 hiyouga/LlamaFactory 官方仓库 2026-08-09 的内容为准。我们没有安装、训练或部署过任何模型，文中的默认值都是从源码 field(default=...) 与示例 YAML 里逐行读出来的。

先把三个最常被问到的值钉死：在 src/llamafactory/hparams/finetuning_args.py 里，lora_rank 的默认值是 8，lora_target 的默认值是字符串 "all"，而 lora_alpha 的默认值是 None——不是 16，不是 32，是 None。

第三条是这篇文章存在的理由。前两个默认值在网上到处能查到，第三个每次都被人自动脑补成一个具体数字。它在源码里就是没有数字。

这一圈参数完整长什么样

LoRA 相关的字段集中在 finetuning_args.py。把源码里的默认值抄成一张表：

参数	默认值
lora_rank	8
lora_target	"all"
lora_alpha	None
lora_dropout	0.0
additional_target	None
loraplus_lr_ratio	None
loraplus_lr_embedding	1e-6
use_rslora	False
use_dora	False
pissa_init	False
pissa_iter	16
pissa_convert	False
create_new_adapter	False
module_dropout	0.0

这张表读起来有一个直观的结论：默认状态下，这一圈开关一个都没打开。rsLoRA、DoRA、PiSSA 对应的是三个独立的布尔字段（use_rslora、use_dora、pissa_init），默认全是 False（PiSSA 那组旁边还有 pissa_iter 默认 16、pissa_convert 默认 False）；LoRA+ 对应的两个字段是 loraplus_lr_ratio（默认 None）与 loraplus_lr_embedding（默认 1e-6）；dropout 类的两项都是 0.0。也就是说，你在别处听到过的那些名字，在这个仓库里的存在形式就是一个个默认关着的字段。至于它们各自到底做了什么、跑起来是什么表现，我们没有读过实现，这篇一个字都不描述，只把名字和默认值摆出来。

顺带把它旁边那组也记一下，因为名字太像很容易看混：freeze_trainable_layers 默认 2、freeze_trainable_modules 默认 "all"、freeze_extra_modules 默认 None——那是 freeze-tuning 的参数，跟 LoRA 不是一路。

lora_alpha 为什么是 None

这一条要说得很克制。

源码里它的定义就是默认 None，不是某个整数。这意味着当你不显式写 lora_alpha 时，最终生效的值由代码在别处决定，而不是直接取一个写死的常量。那段决定逻辑我们没有读过，所以这里不会告诉你它等于多少，也不会写”通常是 rank 的几倍”这种话。

对你的实际影响只有一条，而且是可操作的：如果你的实验记录里需要写清 alpha 用了多少，不要凭默认值推断，显式写出来，或者去看你那次运行实际打印/保存的适配器配置。凭”我记得默认是 16”去写实验报告，是这个参数最容易出事的地方。

lora_target: "all" 这个 "all" 在仓库里不止一处

lora_target 默认 "all"，examples/train_lora/qwen3_lora_sft.yaml 里也确实写着 lora_target: all，两处一致。

但 "all" 这个字面量在 finetuning_args.py 里出现了不止一次：freeze_trainable_modules 是 "all"，galore_target 是 "all"，apollo_target 是 "all"，oft_target 也是 "all"。这是一种贯穿全表的命名习惯——每一族算法都有一个自己的 *_target，并且默认都取 "all"。所以当你在某份配置里看到一行 target: all 时，先看清前缀属于哪一族，别把 GaLore 的 target 当成 LoRA 的 target 去改。

同一族里还有个值得对照的数字：OFT 那组的 oft_rank 默认是 0，而不是像 lora_rank 那样默认 8（oft_block_size 默认 32）。两者默认值形态就不一样，这是参数表层面的客观差异，我们不据此评价谁更好。

这些默认值住在哪一层，以及示例 YAML 覆盖了哪些

LlamaFactory 把超参按用途拆成了多个文件放在 src/llamafactory/hparams/ 下：data_args.py、model_args.py、finetuning_args.py、generating_args.py、evaluation_args.py、training_args.py、megatron_bridge_args.py，加上 parser.py 和 __init__.py。LoRA 这一圈全部属于 finetuning_args.py。

而你实际跑训练时给的是一份 YAML。examples/train_lora/qwen3_lora_sft.yaml 被 ### 注释切成了 model / method / dataset / output / train 五块，另有一个整块被注释掉的 ### eval。它的 method 块原样是：

### method
stage: sft
do_train: true
finetuning_type: lora
lora_rank: 8
lora_target: all

去掉 ### method 那行注释，真正生效的是五行，其中四行写的就是源码默认值：stage 源码默认 "sft"，finetuning_type 源码默认 "lora"，lora_rank 源码默认 8，lora_target 源码默认 "all"。剩下的 do_train: true 属于训练参数那一层（training_args.py），我们没有抽取过那个文件的字段，所以不猜它的默认值。示例把这几行显式写出来，是为了让人看得见，不是因为不写就不生效。

知道哪几行是”重复默认值”，价值在于排查时能缩小怀疑范围：当训练行为和你预期不符时，这几行不是变量，因为它们和默认值一样；真正的变量在你改过的那些行上。

同一份文件里还有一处更值得留意的对照：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。代码默认保守、示例配置显式打开，这是两处口径的客观差异，我们只陈述到这里，不推断原因，也不给”你该不该开”的结论。

改了 lora_rank，下游哪些地方会跟着动

只讲有依据的关联，没依据的一律不编。

训练产物和推理侧是靠路径串起来的。 训练配置的 output_dir: saves/qwen3-4b/lora/sft，正是推理配置 examples/inference/qwen3_lora_sft.yaml 里 adapter_name_or_path 指向的那个目录；两份配置的 template 都是 qwen3_nothink，基座都是 Qwen/Qwen3-4B-Instruct-2507。你改 LoRA 参数不影响这条路径，但你换了输出目录就得同步改推理侧。

推理后端那边另有一个名字很像的参数。 model_args.py 里有 vllm_max_lora_rank，默认 32。它属于推理后端那一组（同组还有 vllm_maxlen 4096、vllm_gpu_util 0.7 等），和训练侧的 lora_rank 不在同一层、不在同一个文件里。两者之间的具体约束关系我们没有追源码，官方也没在参数表里写明，所以这里只提醒你”名字像但不是同一个东西”，不做进一步推断。

合并适配器那一步有一条硬禁令。 examples/merge_lora/qwen3_lora_sft.yaml 的第一行是全大写的注释：

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

原文就是 DO NOT，不是 “not recommended”。合并阶段的其余几行是 export_dir: saves/qwen3_sft_merged、export_size: 5、export_device: cpu # choices: [cpu, auto]、export_legacy_format: false，其中 export_size: 5 与 model_args.py 里的源码默认值一致。

整条链路对应 README Quickstart 的三条命令：

llamafactory-cli train examples/train_lora/qwen3_lora_sft.yaml
llamafactory-cli chat examples/inference/qwen3_lora_sft.yaml
llamafactory-cli export examples/merge_lora/qwen3_lora_sft.yaml

同一组字段在 examples/ 里被复用了多少次

上面那份 qwen3_lora_sft.yaml 只是 examples/train_lora/ 里的一份。这个目录实读有 12 个文件：

mossvl_lora_sft.yaml        qwen3_lora_dpo.yaml       qwen3_lora_kto.yaml
qwen3_lora_pretrain.yaml    qwen3_lora_reward.yaml    qwen3_lora_sft.sh
qwen3_lora_sft.yaml         qwen3_lora_sft_ds3.yaml   qwen3_lora_sft_ray.yaml
qwen3_preprocess.yaml       qwen3vl_lora_dpo.yaml     qwen3vl_lora_sft.yaml

从文件名能读出来的结构事实是：LoRA 并不只跟 stage: sft 绑在一起——预训练（pretrain）、DPO、KTO、奖励建模（reward）各有一份，多模态（qwen3vl）另有 sft 与 dpo 两份，DeepSpeed ZeRO-3（ds3）与 Ray（ray）则是同一件事换了跑法。所以你在这篇里核对过的 finetuning_type / lora_rank / lora_target 这几行，在这十几份配置里是同一组字段，变的是外面那层 stage 和调度方式。

顺着 reward 这条线还有一个默认值值得记：finetuning_args.py 里 reward_model_type 的默认值就是字符串 "lora"，而 reward_model、reward_model_adapters、reward_model_quantization_bit 三个字段默认都是 None。字面上说，这一族参数的默认形态是 LoRA 而不是别的；具体语义我们没有追源码，这里只把默认值摆出来。

多模态那两份 qwen3vl_* 配置对应的则是另外三个开关，同样住在 finetuning_args.py：freeze_vision_tower 默认 True、freeze_multi_modal_projector 默认 True、freeze_language_model 默认 False。视觉塔冻结、投影层冻结、语言模型不冻结——这是从三个默认值直接读出来的，至于多模态该怎么微调、哪一层该不该解冻，我们不据此给任何结论。

Windows 用户多一步

参数本身不分平台，但你在把 LoRA 配置跑起来之前那一步——切模型下载源——写法是分平台的。README 给的环境变量是 USE_MODELSCOPE_HUB=1，两个系统的语法不一样：

# Linux / macOS
export USE_MODELSCOPE_HUB=1

:: Windows
set USE_MODELSCOPE_HUB=1

设完之后要把 model_name_or_path 换成对应 Hub 的 model ID，示例 YAML 里那个 Qwen/Qwen3-4B-Instruct-2507 是 Hugging Face 侧的写法，不要照搬。另外 model_args.py 里有三个 token 字段 hf_hub_token、ms_hub_token、om_hub_token，默认全是 None，分别对应三个 Hub。这类值一律走环境变量或写成 <YOUR_API_KEY> 占位，别提交进版本库。

为什么这篇不告诉你 rank 该设多少

因为没有依据。

仓库里能核实到的只有”默认值是 8”和”示例配置写的也是 8”，没有任何一处文档说”8 适合什么场景""数据量到多少要往上调”。该设多少取决于你的数据规模、基座模型和硬件，官方没有给出通用值，我们也没有做过任何本机训练，编一个推荐值出来对你没有好处。

能给你的只有核对方法：这些默认值随版本变动，以 llamafactory-cli train -h 在你那套环境上的实际输出为准；YAML 里没写的字段就是走源码默认，写了的字段以 YAML 为准。至于 template 为什么必须训练推理两侧对齐、dataset_info.json 的字段怎么填、examples/extras/ 下那 18 个高级算法目录各对应哪个开关，我们另有专门篇目讲，这篇只负责把 LoRA 这几行讲干净。

---

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