# PVeRA: 확률적 벡터 기반 랜덤 행렬 적응

[PVeRA](https://huggingface.co/papers/2512.07703)는 LoRA 기반 어댑터 계열의 VeRA를 기반으로 한 매개변수 효율적 파인튜닝 기법입니다. VeRA의 매우 낮은 매개변수 예산을 유지하면서, 잠재적 적응 분포를 학습함으로써 성능을 향상시킵니다. 이를 통해 PVeRA로 적응된 모델은 추론 시 학습된 분포에서 샘플링하여 몬테카를로 신뢰 구간 추정치를 생성할 수 있습니다.

어댑터 파라미터를 저장할 때 `PveraConfig`의 `save_projection=False`를 설정하여 저랭크 행렬을 저장하지 않을 수 있습니다. 이 경우, `projection_prng_key` 인자의 고정된 랜덤 시드를 기반으로 해당 행렬이 복원됩니다. 이를 통해 체크포인트의 크기를 줄일 수 있지만, 모든 디바이스와 PyTorch의 모든 향후 버전에서 재현성을 보장할 수 없습니다. 재현성을 보장하려면 `save_projection=True`를 설정하세요(기본값).

적응된 레이어의 다양한 형태를 처리하기 위해 PVeRA는 각 차원에 대해 필요한 최대 크기로 공유 A 및 B 행렬을 초기화합니다. 순전파 과정에서, 주어진 레이어에 대한 부분 행렬 A와 B는 이러한 공유 행렬에서 슬라이싱되어 추출되며, 논문에서 설명된 대로 사용됩니다. 예를 들어, 형태가 (100, 20)과 (80, 50)인 두 개의 선형 레이어를 적응하면, 각각 (rank, 50)과 (100, rank) 형태의 A 및 B 행렬이 생성됩니다. 그런 다음, 형태가 (100, 20)인 레이어를 적응하려면 (rank, 20)과 (100, rank) 형태의 부분 행렬 A와 B가 추출됩니다.

PVeRA에는 현재 다음과 같은 제약 조건이 있습니다:

- `nn.Linear` 레이어만 지원됩니다.
- KL 다이버전스를 사용하여 학습하는 데에는 잠재 표현에 쉽게 접근할 수 없습니다.

해당 논문의 초록은 다음과 같습니다:

> 최근 몇 년간 대규모 파운데이션 모델이 등장하여 다양한 작업의 성능 한계를 확장하고 있습니다. 이러한 모델을 학습하거나 심지어 파인튜닝하는 데는 방대한 데이터셋과 계산 자원이 필요하며, 이는 종종 희소하고 비용이 높습니다. 적응 방법은 이러한 모델이 소량의 데이터와 계산 자원으로 파인튜닝될 수 있도록 하여 이러한 한계를 해결하는 계산 효율적인 솔루션을 제공합니다. 이는 학습 가능한 매개변수의 일부만 가진 동결된 백본에 새로운 학습 가능한 모듈을 추가하고, 새로운 작업에 대해 이 모듈만 적합(fitting)하도록 함으로써 달성됩니다. 최근 VeRA 어댑터는 모든 레이어에 걸쳐 공유되는 동결된 무작위 저랭크 행렬 쌍을 활용하여 매개변수 효율적 적응에서 뛰어난 성능을 보인 것으로 입증되었습니다. 본 논문에서는 VeRA 어댑터의 확률적 버전인 PVeRA를 제안하며, 이는 VeRA의 저랭크 행렬을 확률적 방식으로 수정합니다. 이러한 수정은 입력의 내재적 모호성을 처리할 수 있게 하고, 학습 및 테스트 중에 다른 샘플링 구성을 허용합니다. VTAB-1k 벤치마크와 7개의 어댑터를 대상으로 포괄적인 평가가 수행되었으며, PVeRA는 VeRA 및 다른 어댑터보다 우수한 성능을 보였습니다.

## 벤치마크 개요

<iframe src="https://peft-internal-testing-peft-method-comparison-embed.hf.space/?highlight[type]=PVERA" frameborder="0" width="850" height="1000"
>

# API

## PveraConfig[[peft.PveraConfig]]

#### peft.PveraConfig[[peft.PveraConfig]]

```python
peft.PveraConfig(task_type: Optional[Union[str, TaskType]] = None, peft_type: Optional[Union[str, PeftType]] = None, auto_mapping: Optional[dict] = None, peft_version: Optional[str] = None, base_model_name_or_path: Optional[str] = None, revision: Optional[str] = None, inference_mode: bool = False, r: int = 256, target_modules: Optional[Union[list[str], str]] = None, projection_prng_key: int = 0, save_projection: bool = True, pvera_dropout: float = 0.0, d_initial: float = 0.1, fan_in_fan_out: bool = False, bias: str = 'none', modules_to_save: Optional[list[str]] = None, init_weights: bool = True, layers_to_transform: Optional[Union[list[int], int]] = None, layers_pattern: Optional[Union[list[str], str]] = None, sample_at_inference: bool = False, generator_seed: Optional[int] = None)
```

[소스](https://github.com/huggingface/peft/blob/main/src/peft/tuners/pvera/config.py#L25)

**매개변수:**

r (`int`, *선택 사항*, 기본값 `256`) : PVeRA 파라미터 차원("rank"). PVeRA는 레이어 간에 파라미터를 공유하므로 LoRA보다 훨씬 적은 파라미터를 사용합니다. 따라서 LoRA rank보다 높은 값을 선택하세요.

target_modules (`Union[List[str], str]`) : PVeRA를 적용할 모듈의 이름입니다. 선형 레이어만 지원됩니다. 문자열을 전달하는 경우 정규식 매칭이 수행됩니다. 'all-linear'로 지정하면 모든 선형/Conv1D 모듈이 선택됩니다. 지정하지 않으면 모델 아키텍처에 따라 모듈이 선택됩니다. 아키텍처가 알려지지 않은 경우 오류가 발생합니다.

projection_prng_key (`int`) : PVeRA PRNG 초기화 키. 새로운 모델에서 pvera_A와 pvera_B를 초기화하거나, 이러한 투영이 포함되지 않은 체크포인트를 로드할 때 사용됩니다. 기본값은 `0`입니다.

save_projection (`bool`) : state dict에 레이어별 lambda_b / lambda_d 가중치와 함께 pvera_A / pvera_B 투영을 저장할지 여부입니다. 이는 체크포인트 크기를 증가시키지만, 모든 시스템 구성에서 체크포인트를 다시 로드할 수 있음을 보장합니다. 기본값은 `True`입니다.

pvera_dropout (`float`) : PVeRA 레이어의 dropout 확률입니다.

d_initial (`float`, *선택 사항*, 기본값 `0.1`) : PVeRA 매개변수를 초기화할 때 사용되는 `pvera_lambda_d` 벡터의 초기 값입니다. 작은 값(<=0.1)을 권장합니다.

fan_in_fan_out (`bool`) : 대체할 레이어가 가중치를 (fan_in, fan_out) 형태로 저장하는 경우 True로 설정합니다. 예를 들어, gpt-2는 가중치를 (fan_in, fan_out) 형태로 저장하는 `Conv1D`를 사용하므로 이 값을 `True`로 설정해야 합니다.

bias (`str`) : PVeRA의 bias 유형입니다. 'none', 'all', 'pvera_only' 중 하나를 지정할 수 있습니다. 'all' 또는 'pvera_only'로 설정하면 해당 bias가 학습 중에 업데이트됩니다. 어댑터를 비활성화하더라도, 어댑팅이 없는 기본 모델과 동일한 출력을 생성하지 않는다는 점에 유의하세요.

modules_to_save (`List[str]`) : PVeRA 레이어를 제외한 최종 체크포인트에 저장할 학습 가능 모듈 목록.

init_weights (`bool`) : PVeRA 레이어의 가중치를 기본 초기화로 초기화할지 여부입니다. 정확히 무엇을 하는지 알고 있는 경우를 제외하고는 이 설정을 변경하지 마세요.

layers_to_transform (`Union[List[int],int]`) : 변환할 레이어 인덱스입니다. 이 인수가 지정되면, 이 리스트에 지정된 레이어 인덱스에 PVeRA 변환을 적용합니다. 단일 정수가 전달되면, 해당 인덱스의 레이어에 PVeRA 변환을 적용합니다.

layers_pattern (`Optional[Union[List[str], str]]`) : `layers_to_transform`가 `None`과 다르면만 사용되는 레이어 패턴 이름입니다. 이는 모델의 `nn.ModuleList`를 대상으로 해야 하며, 보통 `'layers'` 또는 `'h'`라고 불립니다.

sample_at_inference (`bool`, 기본값 `False`) : 추론 시 학습된 PVeRA 분포에서 샘플링할지 여부입니다. False인 경우 학습된 평균이 사용됩니다.

generator_seed (`int`, 기본값 None) : 학습된 분포에서 샘플링하는 데 사용되는 생성기의 랜덤 시드입니다.

이것은 [PveraModel](/docs/peft/main/ko/package_reference/pvera#peft.PveraModel)의 구성을 저장하기 위한 구성 클래스입니다.

논문: https://www.arxiv.org/abs/2512.07703.

## PveraModel[[peft.PveraModel]]

#### peft.PveraModel[[peft.PveraModel]]

```python
peft.PveraModel(model, peft_config: Union[PeftConfig, dict[str, PeftConfig]], adapter_name: str, low_cpu_mem_usage: bool = False, state_dict: Optional[dict[str, torch.Tensor]] = None)
```

[소스](https://github.com/huggingface/peft/blob/main/src/peft/tuners/pvera/model.py#L35)

**매개변수:**

model ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) : 적응할 모델.

config ([PveraConfig](/docs/peft/main/ko/package_reference/pvera#peft.PveraConfig)) : PVeRA 모델의 구성입니다.

adapter_name (`str`) : 어댑터의 이름이며, 기본값은 `"default"`입니다.

low_cpu_mem_usage (`bool`, `optional`, 기본값 `False`) : meta device에 빈 어댑터 가중치를 생성합니다. 로딩 프로세스를 가속하는 데 유용합니다.

**반환값:** `torch.nn.Module`

PVeRA 모델.

pretrained transformers model에서 Probabilistic Vector-based Random Matrix Adaptation (PVeRA) 모델을 생성합니다.

예:

```py
>>> from transformers import AutoModel
>>> from peft import PveraConfig, get_peft_model

>>> base_model = AutoModel.from_pretrained("facebook/dinov2-base")
>>> config = PveraConfig(r=128, sample_at_inference=False)
>>> model = get_peft_model(base_model, config)
```

**속성**:
- **model** ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) -- 적응할 모델.
- **peft_config** ([PveraConfig](/docs/peft/main/ko/package_reference/pvera#peft.PveraConfig)): PVeRA 모델의 구성입니다.