# 🤗 PEFT를 활용한 매개변수 효율적 미세 조정

[🤗 PEFT](https://github.com/huggingface/peft)(Parameter-Efficient Fine-Tuning)는 사전 학습된 정책(예: SmolVLA, π₀, ...)과 같은 대규모 사전 학습 모델을 모델의 모든 매개변수를 학습하지 않고도 새로운 작업에 효율적으로 적응시키는 라이브러리입니다. 이 과정에서 기존 모델과 동등한 수준의 성능을 제공합니다.

PEFT 지원을 활성화하려면 `lerobot[peft]` 선택 패키지를 설치하세요.

적응의 모든 가능한 방법에 대해 자세히 알아보려면 [🤗 PEFT 문서](https://huggingface.co/docs/peft/index)를 참고하세요.

## SmolVLA 학습

이 섹션에서는 PEFT를 사용하여 libero 데이터셋에서 사전 학습된 SmolVLA 정책을 학습하는 방법을 보여줍니다. 간결성을 위해 `libero_spatial` 하위 집합에서만 학습합니다. 매개변수 효율적 미세 조정 대상 모델로 `lerobot/smolvla_base`를 사용합니다:

```
lerobot-train \
 --policy.path=lerobot/smolvla_base \
 --policy.repo_id=your_hub_name/my_libero_smolvla \
 --dataset.repo_id=HuggingFaceVLA/libero \
 --policy.output_features=null \
 --policy.input_features=null \
 --policy.optimizer_lr=1e-3 \
 --policy.scheduler_decay_lr=1e-4 \
 --env.type=libero \
 --env.task=libero_spatial \
 --steps=100000 \
 --batch_size=32 \
 --peft.method_type=LORA \
 --peft.r=64 \
 --peft.lora_alpha=64
```

`--peft.method_type` 파라미터를 사용하여 사용할 PEFT 방법을 선택할 수 있습니다. 여기서는 [LoRA](https://huggingface.co/docs/peft/main/en/package_reference/lora)(Low-Rank Adapter)를 사용하는데, 이는 아마도 지금까지 가장 인기 있는 fine-tuning 방법일 것입니다. Low-rank adaption은 전체 weight matrix 대신 상대적으로 낮은 rank를 가진 matrix만 fine-tune하는 것을 의미합니다. 이 rank는 `--peft.r` 파라미터로 지정할 수 있으며, LoRA scaling factor는 `--peft.lora_alpha`로 지정합니다(여기서 `scaling = lora_alpha / r`). rank가 높을수록 full fine-tuning에 더 가까워집니다.

매개변수가 더 많은 더 복잡한 방법론도 있습니다. 이러한 방법론은 아직 지원되지 않으며, 특정 PEFT 방법론의 지원을 원하시면 이슈를 등록해 주세요.

기본적으로 PEFT는 SmolVLA의 LM expert에서 `q_proj` 및 `v_proj` 레이어를 대상으로 합니다. 또한 태도에 따라 달라질 가능성이 가장 높은 상태 및 액션 투영 행렬도 대상으로 합니다. 다른 레이어를 대상으로 해야 하는 경우 `--peft.target_modules`를 사용하여 대상 레이어를 지정할 수 있습니다. 지원되는 입력을 확인하려면 해당 PEFT 메서드의 문서를 참조하십시오(예: [LoRA의 target_modules 문서](https://huggingface.co/docs/peft/main/en/package_reference/lora#peft.LoraConfig.target_modules)). 일반적으로 접미사 목록 또는 정규식이 지원됩니다. 예를 들어, `q` 및 `v` 투영 대신 `lm_expert`의 MLP를 대상으로 하려면 다음을 사용하십시오:

```
--peft.target_modules='(model\.vlm_with_expert\.lm_expert\..*\.(down|gate|up)_proj|.*\.(state_proj|action_in_proj|action_out_proj|action_time_mlp_in|action_time_mlp_out))'
```

레이어를 단순히 적응시키는 대신 완전히 fine-tune해야 하는 경우, `--peft.full_training_modules` 매개변수에 레이어 접미사 목록을 제공할 수 있습니다:

```
--peft.full_training_modules='["state_proj"]'
```

학습률과 스케줄링된 목표 학습률은 일반적으로 전체 파인튜닝에 사용된 학습률(예: 1e-4)에 비해 10배의 계수로 스케일링할 수 있습니다(예: LoRA 사용 시 1e-3).

PEFT는 샤드된 멀티 GPU 학습(FSDP2 및 HSDP)과도 함께 작동하며, [멀티 GPU 학습](./multi_gpu_training#peft)을 참고하세요.

## 기타 정책

동일한 `--peft.*` 플래그은 모든 사전 학습된 정책에 적용됩니다. 일부 정책(예: SmolVLA, π₀, π₀.₅, MolmoAct2)은 내장된 기본 `target_modules`를 제공하므로 `--peft.method_type=LORA`만 지정하면 됩니다. 그렇지 않은 정책은 `--peft.target_modules`를 명시적으로 전달해야 하며, 예를 들어 LingBot-VA의 경우 권장 대상은 [전용 가이드](./lingbot_va#training--fine-tuning)에 문서화되어 있습니다.

`--policy.use_peft=true`만 사용하는 것은 기본 설정으로 `--peft.method_type=LORA`를 사용하는 것과 동일합니다.