Skip to content

fix(lora): honor fallback RS-LoRA scaling - #170

Merged
isLinXu merged 5 commits into
Tencent:mainfrom
SidKC:fix/lora-fallback-effective-config
Jul 27, 2026
Merged

fix(lora): honor fallback RS-LoRA scaling#170
isLinXu merged 5 commits into
Tencent:mainfrom
SidKC:fix/lora-fallback-effective-config

Conversation

@SidKC

@SidKC SidKC commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

背景

fallback LoRA 路径目前没有真正应用 LoRAConfig.use_rsloraManualLoRAConvFewShotLoRAConv 始终使用 alpha / r。这会导致配置记录为 RS-LoRA,但实际 scaling 仍是普通 LoRA。

此外,fallback adapter 的保存格式没有记录实际 scaling 模式,加载时也无法区分 RS-LoRA 与普通 LoRA。

修改

  • use_rslora 显式传入 fallback wrapper:
    • RS-LoRA 使用 alpha / sqrt(r)
    • 普通 LoRA 保持 alpha / r
  • 在 runtime metadata 和 fallback adapter 的逐模块配置中记录实际 scaling 模式。
  • 保存、加载和 merge 前后保持相同的有效 scaling。
  • 加载旧 adapter 时,如果不存在 use_rslora 字段,继续按历史的 alpha / r 处理,避免旧 checkpoint 的行为发生静默变化。

测试

  • 收窄后的聚焦测试:3 passed
  • LoRA、adapter、MoLoRA、VPEFT 相关回归:150 passed, 29 skipped
  • 聚焦测试和相关回归均生成了 JUnit XML 回执。
  • py_compile、新增测试的 Ruff 检查及 git diff --check 通过。

重点覆盖:

  • RS-LoRA 与普通 LoRA 的 scaling;
  • RS-LoRA adapter 保存、加载和 merge 前向一致性;
  • 旧格式缺少 scaling 字段时的兼容加载。

范围说明

独立复核发现,fallback alpha warmup 还涉及 online model 与 EMA model 的 scaling 同步,以及 validation、checkpoint 和 resume 的完整生命周期。仅增加 bare-Parameter coverage 不能闭合这条链路,因此本 PR 不再包含 alpha warmup 改动。

Alpha warmup 将作为后续独立的 test-first 修复处理,避免把两个不同风险边界混在同一个 PR 中。

@SidKC SidKC changed the title Fix fallback RS-LoRA scaling and alpha warmup fix(lora): honor fallback RS-LoRA scaling and alpha warmup Jul 24, 2026
@isLinXu
isLinXu marked this pull request as ready for review July 24, 2026 13:14
@SidKC

SidKC commented Jul 24, 2026

Copy link
Copy Markdown
Contributor Author

补充说明一下当前 CI 的失败情况:

我对比了本 PR 的 CI run 30095230566 和基线 main@4dbed323 的 CI run 30039398541。目前各平台失败的是同一组 5 个测试:

  • test_ddp_lifecycle_ema_nan.py 中 3 个 DDP / trainer lifecycle 测试;
  • test_ddp_checkpoint_coordination.py 中 2 个 mixture buffer 测试。

这些失败在本 PR 创建前已经存在,并且可以追溯到 #165 合入后的 main CI run 29996840129。本 PR 只修改 fallback LoRA scaling、alpha warmup coverage 及相应测试,没有改动上述 DDP、trainer 或 mixture 代码;新增的 fallback LoRA 测试也没有出现在失败列表中。

@isLinXu 这组回归看起来与 #165 合入的 optimization delivery 改动有关,麻烦您有空时帮忙确认一下。

为了保持当前 PR 的修改范围单一,我暂时不把这组 main 回归的修复混入本 PR;待 main 修复后再同步最新基线。

@SidKC
SidKC marked this pull request as draft July 24, 2026 13:55
@SidKC SidKC changed the title fix(lora): honor fallback RS-LoRA scaling and alpha warmup fix(lora): honor fallback RS-LoRA scaling Jul 24, 2026
@SidKC

SidKC commented Jul 24, 2026

Copy link
Copy Markdown
Contributor Author

补充说明:独立复核发现,当前 fallback alpha warmup 虽然可以更新 online model 的 scaling,但该属性不在 state_dict() 中,trainer 使用的 EMA model 不会自动同步这一变化;而 validation 和 checkpoint 默认使用 EMA。因此,把 bare-Parameter warmup coverage 单独合入,仍不能构成完整的端到端修复。

为避免把尚未闭合的 warmup/EMA 生命周期行为带入 main,我已将本 PR 重新转为 Draft,并把范围收窄为 fallback RS-LoRA scaling、有效模式记录和 legacy adapter 兼容。

Alpha warmup coverage、online/EMA scaling 同步、checkpoint/validation 和 resume 行为将放到后续独立的 test-first PR 中处理。本 PR 收窄并重新验证后再转回 Ready。

@SidKC

SidKC commented Jul 25, 2026

Copy link
Copy Markdown
Contributor Author

补充说明:现已将分支同步到最新 main@a510883。本次同步没有扩大 PR 的修改范围;当前相对 main 仍只包含 fallback RS-LoRA effective scaling 及对应回归测试。测试已覆盖 adapter save/load、旧格式兼容,以及 merge 前后的 forward 一致性。同步后定向测试为 3 passed,相关 LoRA/MoLoRA/VPEFT 回归为 150 passed, 29 skipped

@SidKC
SidKC marked this pull request as ready for review July 25, 2026 00:18
Copilot AI review requested due to automatic review settings July 25, 2026 00:18

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR fixes the fallback LoRA backend so it actually honors LoRAConfig.use_rslora (RS-LoRA vs standard LoRA scaling), and makes the chosen scaling mode persist across fallback adapter save/load/merge to keep behavior consistent.

Changes:

  • Add _fallback_lora_scaling() and thread use_rslora through ManualLoRAConv / FewShotLoRAConv to apply alpha / sqrt(r) when RS-LoRA is enabled.
  • Record use_rslora in fallback runtime metadata and per-module adapter configs, and recompute scaling on load for forward/merge consistency.
  • Add tests covering RS-LoRA vs standard scaling, adapter round-trip behavior, and legacy adapter compatibility when use_rslora is missing.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File Description
ultralytics/utils/lora/fallback.py Apply and persist effective RS-LoRA scaling in the fallback backend (wrappers, runtime metadata, adapter save/load).
tests/test_lora_fallback_effective_config.py Add regression tests for fallback RS-LoRA scaling, round-trip persistence, and legacy-compat loading.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread ultralytics/utils/lora/fallback.py
@SidKC

SidKC commented Jul 25, 2026

Copy link
Copy Markdown
Contributor Author

补充一组下游受控验证,主要确认这个修复改变的是实际训练行为,而不只是配置记录。

在固定 released YOLOE、VisDrone、seed 和 7-epoch 预算下,我做了 fresh、Unmerged-Only 的四条件对照。四组使用相同初始化、数据顺序、训练配置和 final-only evaluator:

  • RS-LoRA vs ordinary LoRA,无 alpha warmup:+0.949 AP
  • RS-LoRA vs ordinary LoRA,有 alpha warmup:+0.721 AP

两个背景下 RS-LoRA 的方向一致,说明 fallback use_rslora 的 effective scaling 在真实训练路径中产生了可测量差异。该实验同时验证了 unmerged adapter 的保存/加载路径;merge 语义仍以本 PR 的单元测试为准。

这只是单 seed、固定 7 epochs 的 exploratory observation,不代表跨 seed 稳定提升。Alpha warmup 与 EMA 生命周期修复仍保持为后续独立改动,不混入本 PR。

…ffective-config

# Conflicts:
#	ultralytics/utils/lora/fallback.py
@SidKC

SidKC commented Jul 25, 2026

Copy link
Copy Markdown
Contributor Author

已同步最新 main@296a29c,当前合并冲突已解决。

冲突来自 #175ultralytics/utils/lora/fallback.py 的并行修改。处理时保留了 main 新增的 rank_pattern、placement metadata 和相关整理,同时保留本 PR 的 fallback RS-LoRA scaling、配置持久化及旧适配器兼容逻辑;PR 相对最新 main 仍只改动 fallback.py 和对应回归测试,没有扩大范围。

同步后验证:

  • 本 PR 聚焦测试:4 passed
  • 相关 LoRA / V-PEFT 测试:156 passed, 30 skipped, 2 failed
  • 其中 2 个失败在纯 main@296a29c 上可独立复现,均为 V-PEFT planner 报 name differentiable is not defined 后缺少 lora_placement_plan,与本 PR 的 RS-LoRA 改动无关
  • py_compile、PR 相对 main 的 git diff --check 以及公开内容检查均通过

GitHub 当前已重新显示为可合并,新一轮 CI 正在运行。

@isLinXu

isLinXu commented Jul 27, 2026

Copy link
Copy Markdown
Collaborator

LGTM

@isLinXu
isLinXu merged commit eef14f5 into Tencent:main Jul 27, 2026
12 of 18 checks passed
@SidKC
SidKC deleted the fix/lora-fallback-effective-config branch July 27, 2026 03:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants