From 9db9c35cb473afe3d9bf7b54fa5fd44576974f75 Mon Sep 17 00:00:00 2001
From: Cheng Yin <34277382+wadeKeith@users.noreply.github.com>
Date: Wed, 13 May 2026 17:09:19 +0800
Subject: [PATCH] fix(config): add lora_alpha to PeftConfig (#3573)

* fix(config): add lora_alpha to PeftConfig

PeftConfig was missing the lora_alpha field, causing the PEFT library
to default to alpha=8 regardless of the LoRA rank, which dampens the
adaptation signal for high-rank adapters (e.g., r=128).

This adds lora_alpha: int | None = None to PeftConfig, allowing users
to specify --peft.lora_alpha <value> on the CLI.

Closes #3551

* fix(docs): add lora_alpha to peft training example + clarify scaling formula

- Add --peft.lora_alpha=64 to docs/source/peft_training.mdx example to
  prevent new users from hitting the alpha=8 default dampening bug
- Clarify lora_alpha comment in default.py with scaling = lora_alpha / r

* docs: mention both --peft.r and --peft.lora_alpha in LoRA description

---------

Co-authored-by: Cheng Yin <yin@users.noreply.github.com>
---
 docs/source/peft_training.mdx  | 6 ++++--
 src/lerobot/configs/default.py | 6 ++++++
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/docs/source/peft_training.mdx b/docs/source/peft_training.mdx
index dd0b10075..d44a3f081 100644
--- a/docs/source/peft_training.mdx
+++ b/docs/source/peft_training.mdx
@@ -28,13 +28,15 @@ lerobot-train \
  --steps=100000 \
  --batch_size=32 \
  --peft.method_type=LORA \
- --peft.r=64
+ --peft.r=64 \
+ --peft.lora_alpha=64
 ```
 
 Note the `--peft.method_type` parameter that let's you select which PEFT method to use. Here we use
 [LoRA](https://huggingface.co/docs/peft/main/en/package_reference/lora) (Low-Rank Adapter) which is probably the most
 popular fine-tuning method to date. Low-rank adaption means that we only fine-tune a matrix with comparably low rank
-instead of the full weight matrix. This rank can be specified using the `--peft.r` parameter. The higher the rank
+instead of the full weight matrix. This rank can be specified using the `--peft.r` parameter, and the LoRA scaling factor with
+`--peft.lora_alpha` (where `scaling = lora_alpha / r`). The higher the rank
 the closer you get to full fine-tuning
 
 There are more complex methods that have more parameters. These are not yet supported, feel free to raise an issue
diff --git a/src/lerobot/configs/default.py b/src/lerobot/configs/default.py
index be906edbd..b1eebba94 100644
--- a/src/lerobot/configs/default.py
+++ b/src/lerobot/configs/default.py
@@ -117,3 +117,9 @@ class PeftConfig:
     # the rank used for the adapter. In general a higher rank means more trainable parameters and closer to full
     # fine-tuning.
     r: int = 16
+
+    # Alpha parameter for LoRA scaling (scaling = lora_alpha / r).
+    # In general, a higher alpha means stronger adaptation signal.
+    # If None, the PEFT library defaults to alpha=8, which may dampen high-rank adapters.
+    # Common values are r (alpha == rank) or 2*r.
+    lora_alpha: int | None = None