PEFT documentation
AdaMSS
AdaMSS
AdaMSS(AdaMSS: Adaptive Multi-Subspace Approach for Parameter-Efficient Fine-Tuning)는 SVD를 사용하여 가중치 행렬을 분해하고 분해된 공간을 여러 학습 가능한 부분 공간으로 클러스터링하는 파라미터 효율적 파인튜닝 방법입니다. 각 부분 공간은 독립적인 저랭크 업데이트를 학습하는 동안 원래의 가중치는 고정된 상태로 유지됩니다. AdaMSS는 또한 훈련 중에 그라디언트 정보에 기반하여 덜 중요한 부분 공간을 동적으로 제거하는 Adaptive Subspace Allocation(ASA)을 지원합니다.
해당 논문의 초록은 다음과 같습니다:
대형 모델의 매개변수 효율적 파인튜닝을 위한 적응형 다중 부분공간 접근 방식인 AdaMSS를 제안합니다. 네트워크 가중치 내에서 하나의 큰 단일 부분공간에서 작동하는 기존 매개변수 효율적 파인튜닝 방법과 달리, AdaMSS는 부분공간 분할을 활용하여 여러 개의 더 작은 부분공간을 얻고, 학습 중에 학습 가능한 매개변수의 수를 적응적으로 줄입니다. 궁극적으로 목표 다운스트림 작업과 가장 관련이 있는 소수의 부분공간에 연관된 매개변수만 업데이트합니다. 가장 낮은 랭크 표현을 사용함으로써, AdaMSS는 더 컴팩트한 표현력과 모델 매개변수의 더 정밀한 튜닝을 달성합니다. 이론적 분석을 통해 AdaMSS가 LoRA, PiSSA 및 기타 단일 부분공간 기반 저랭크 방법보다 더 나은 일반화 보장을 가짐을 입증했습니다. 이미지 분류, 자연어 이해, 자연어 생성 작업에 걸친 광범위한 실험 결과, AdaMSS는 전체 파인튜닝과 동등한 성능을 달성하는 동시에 대부분의 경우 다른 매개변수 효율적 파인튜닝 방법보다 우수한 성능을 보이며, 학습 가능한 매개변수의 수가 더 적습니다. 특히, ViT-Large 모델에서 AdaMSS는 학습 가능한 매개변수만 15.4%를 사용하여 7개 작업에서 LoRA보다 평균 정확도가 4.7% 높았습니다. RoBERTa-Large에서는 6개 작업에서 평균 정확도가 PiSSA보다 7% 높았으며, 학습 가능한 매개변수의 수를 약 94.4% 줄였습니다. 이러한 결과는 AdaMSS의 매개변수 효율적 파인튜닝에서의 효과성을 보여줍니다. AdaMSS의 코드는 https: //github.com/jzheng20/AdaMSS에서 사용할 수 있습니다.
AdaMSS에는 현재 다음과 같은 제약 사항이 있습니다:
nn.Linear레이어만 지원됩니다.- KMeans 클러스터링 단계에 scikit-learn이 필요합니다.
이러한 제약 조건이 사용 사례에 적합하지 않다면, 다른 방법을 고려해 보세요.
벤치마크 개요
API
AdamssConfig
클래스 peft.AdamssConfig
< source >( task_type: Optional[Union[str, TaskType]] = Nonepeft_type: Optional[Union[str, PeftType]] = Noneauto_mapping: Optional[dict] = Nonepeft_version: Optional[str] = Nonebase_model_name_or_path: Optional[str] = Nonerevision: Optional[str] = Noneinference_mode: bool = Falser: int = 100num_subspaces: int = 5subspace_rank: int = 1target_modules: Optional[Union[list[str], str]] = Noneinit_weights: Optional[Literal['orthogonal']] = 'orthogonal'modules_to_save: Optional[list[str]] = Nonelayers_to_transform: Optional[Union[list[int], int]] = Nonelayers_pattern: Optional[Union[list[str], str]] = Noneuse_asa: bool = Falseasa_target_subspaces: int = 50init_warmup: int = 50final_warmup: int = 1000mask_interval: int = 100asa_importance_beta: float = 0.85asa_uncertainty_beta: float = 0.85asa_schedule_exponent: float = 3.0use_dynamic_rank: bool = Falsesvd_threshold: float = 0.1random_seed: int = 0 )
매개변수
- r (
int) — SVD 분해의 총 랭크(논문에서 R로 표기). 이는 클러스터링 전에 가중치 행렬을 표현하는 데 사용되는 특이 벡터의 수를 결정합니다. 값이 높을수록 원래 가중치에서 더 많은 정보를 포착하지만, 더 많은 계산 및 메모리가 필요합니다. 값이 낮을수록 더 강한 정규화를 제공합니다. 일반적인 값은 50에서 500 사이이며, 기본값은 100입니다. - num_subspaces (
int) — SVD 분해된 공간을 클러스터링할 부분 공간(K)의 수입니다. 각 부분 공간은 독립적인 저랭크 업데이트를 학습합니다. 이 값을 증가시키면 더 세밀한 적응이 가능하지만, 학습 가능한 매개변수의 수가 비례하여 증가합니다. ASA(Adaptive Subspace Allocation)를 사용하는 경우, 이는 프루닝 이전의 초기 부분 공간 수를 결정합니다. 일반적인 값은 3에서 10 사이이며, 기본값은 5입니다. - subspace_rank (
int) — 학습 가능한 각 부분 공간의 랭크(r_i)입니다. 이는 각 부분 공간이 적응을 학습할 수 있는 용량을 제어합니다. 값이 높을수록 표현력이 증가하지만 학습 가능한 매개변수도 함께 증가합니다. 총 학습 가능한 매개변수는 O(num_subspaces subspace_rank (in_dim + out_dim) / num_subspaces)에 비례합니다. 대부분의 작업에서는 1~4의 값이 잘 작동합니다. 기본값은 1입니다. - target_modules (
Optional[Union[list[str], str]]) — AdaMSS를 적용할 모듈의 이름입니다. 지정된 경우, 해당 모듈만 적응됩니다. 정확한 모듈 이름의 목록 또는 정규식 표현식을 사용할 수 있습니다. 예를 들어, 어텐션 레이어의 경우['q_proj', 'v_proj'], 정규식 매칭의 경우'.*decoder.*(SelfAttention|EncDecAttention).*(q|v)$'를 사용할 수 있습니다. - modules_to_save (
Optional[list[str]]) — AdaMSS 레이어를 제외한 최종 체크포인트에 저장할 학습 가능 모듈 목록입니다. 이 모듈들은 저랭크 방식이 아닌 완전한 파인튜닝을 수행합니다. 분류 작업에서classifier나score와 같이 무작위로 초기화된 헤드를 사용할 때 필수입니다. - init_weights (
Literal["orthogonal"]) — AdaMSS 학습 가능 가중치의 초기화 방법입니다. 현재는 B 행렬(출력 투영)에 직교 초기화를 사용하는 “orthogonal”만 지원됩니다. A 행렬은 모델이 사전 학습된 가중치에서 시작하도록 0으로 초기화됩니다. 체크포인트에서 로드할 때 초기화를 건너뛰려면 None으로 설정합니다. 기본값은 “orthogonal”입니다. - layers_to_transform (
Optional[Union[list[int], int]]) — AdaMSS를 적용할 특정 레이어 인덱스입니다. 지정된 경우, 해당 레이어만 적응되며, 적응에서 가장 큰 이점을 얻는 레이어를 실험하는 데 유용합니다. 단일 정수 또는 정수 목록일 수 있습니다. - layers_pattern (
Optional[Union[list[str], str]]) —layers_to_transform가 지정된 경우 레이어 이름을 일치시키기 위한 패턴입니다. 일반적인 패턴을 따르지 않는 모듈 이름에서 레이어 인덱스를 추출하는 데 사용됩니다. - use_asa (
bool) — Adaptive Subspace Allocation(ASA)를 활성화할지 여부입니다. 활성화되면 ASA는 학습 중에 기울기 정보에 기반하여 중요도가 낮은 부분공간을 동적으로 제거하여, 성능을 유지하면서 유효한 매개변수 수를 줄입니다. 학습 콜백과의 통합이 필요합니다. 기본값은 False입니다. - asa_target_subspaces (
int) — ASA가 활성화된 경우 모든 레이어에 걸친 활성 서브스페이스의 총 목표 개수입니다. ASA는 이 목표에 도달할 때까지 서브스페이스를 점진적으로 제거합니다. 값이 낮을수록 더 공격적인 제거가 이루어져 학습 가능한 파라미터가 줄어듭니다.num_subspaces * num_target_modules보다 작아야 합니다. 모델 크기에 따라 일반적인 값은 20에서 100 사이입니다. 기본값은 50입니다.use_asa=True인 경우 양의 정수여야 합니다. - init_warmup (
int) — ASA pruning을 시작하기 전에 대기할 학습 단계 수입니다. warmup 동안에는 중요도 점수가 안정화될 수 있도록 모든 부분 공간이 활성화된 상태로 유지됩니다. 값이 높을수록 정확한 중요도 추정에 더 많은 시간이 주어지지만, pruning이 지연됩니다. 일반적인 값은 50에서 200 사이입니다. 기본값은 50입니다.use_asa=True인 경우final_warmup보다 작아야 합니다. - final_warmup (
int) — ASA가 프루닝을 완료하고asa_target_subspaces개의 활성 서브스페이스에 도달하는 학습 단계입니다. 프루닝은init_warmup과final_warmup사이에 분배됩니다. 전체 학습 단계 수를 기준으로 설정해야 하며, 일반적으로 전체 학습 단계의 1/3에서 1/2 사이입니다. 기본값은 1000입니다.use_asa=True인 경우init_warmup보다 커야 합니다. - mask_interval (
int) — ASA 마스크 업데이트 사이의 학습 스텝 수입니다. 값이 낮을수록 적응이 더 자주 일어나지만 오버헤드가 증가합니다. 값이 높을수록 업데이트 사이에 중요도 추정치가 더 안정적으로 유지됩니다. 일반적인 값은 50에서 200 사이이며 기본값은 100입니다.use_asa=True인 경우 양의 정수여야 합니다. - asa_importance_beta (
float) — 서브스페이스 중요도 점수를 부드럽게 만들기 위한 지수 이동 평균(EMA) 계수입니다. 값이 높을수록(1.0에 가까울수록) 과거 중요도에 더 큰 가중치를 부여하여 안정성을 제공합니다. 값이 낮을수록 최근 그래디언트에 중요도가 더 민감하게 반응합니다. 일반적인 값의 범위는 0.8에서 0.95입니다. 기본값은 0.85입니다. - asa_uncertainty_beta (
float) — 중요도 불확실성 추정치를 부드럽게 만들기 위한 EMA 계수입니다. 불확실성이 그라디언트 분산에 얼마나 빠르게 적응하는지를 제어합니다. asa_importance_beta와 유사하게, 값이 높을수록 더 안정적인 추정치를 제공합니다. 일반적인 값은 0.8에서 0.95 범위입니다. 기본값은 0.85입니다. - asa_schedule_exponent (
float) — ASA warmup 동안asa_target_subspaces까지 total subspaces에서 감쇠하는 속도를 제어하는 schedule 지수입니다. 값이 높을수록 초기 pruning이 더 빠르게 진행되며(더 공격적인 초기 감소), 값이 낮을수록 더 점진적이고 선형에 가까운 감쇠를 제공합니다. 공식은 다음과 같습니다: current_active_subspaces = asa_target_subspaces + (asa_total_subspaces - asa_target_subspaces) * (progress ** exponent). 일반적인 값의 범위는 1.0(선형)에서 5.0(공격적)까지입니다. 기본값은 3.0입니다.use_asa=True인 경우 양수여야 합니다(지수가 0 또는 음수이면 schedule이 영구적인 no-op으로 퇴화하거나,progress가 정확히 0.0에 도달하면ZeroDivisionError가 발생합니다). - use_dynamic_rank (
bool) — 특이값의 크기에 기반하여 부분공간 랭크를 동적으로 결정할지 여부입니다. True인 경우, 각 부분공간의 랭크는 임계값을 초과하는 특이값의 개수를 세어 결정되며, 이를 통해 서로 다른 부분공간이 서로 다른 유효 랭크를 가질 수 있습니다. False인 경우, 모든 부분공간이 고정된subspace_rank를 사용합니다. 기본값은 False입니다. - svd_threshold (
float) — 동적 랭크 선택을 위한 임계 비율로,use_dynamic_rank=True일 때만 사용됩니다. 특이값이threshold * max_singular_value를 초과하는 경우 유의미한 것으로 간주됩니다. 값이 높을수록 유효 랭크가 낮아지며(더 공격적인 절단) 더 많은 특이값이 제거됩니다. 일반적인 값의 범위는 0.05에서 0.2입니다. 기본값은 0.1(최대값의 10%)입니다.
Adamss(Adaptive Multi-Subspaces) 방법의 구성 클래스입니다.
AdaMSS는 SVD를 사용하여 가중치 행렬을 분해하고 분해된 공간을 여러 학습 가능한 부분 공간으로 클러스터링하는 매개변수 효율적 파인튜닝 방법입니다. 원래 가중치는 고정된 상태로 유지하면서 이러한 부분 공간 내에서 저랭크 업데이트를 학습합니다.
AdamssModel
class peft.AdamssModel
< source >( modelconfigadapter_namelow_cpu_mem_usage: bool = Falsestate_dict: Optional[dict] = None ) → torch.nn.Module
Adamss(Adaptive Multi-Subspaces) 모델을 사전 학습된 모델로부터 생성합니다.
이 메서드는 SVD를 사용하여 가중치 행렬을 분해하고, 분해된 공간을 여러 학습 가능한 부분 공간으로 클러스터링하여 매개변수 효율적인 미세 조정을 수행합니다.
예:
>>> from transformers import AutoModelForImageClassification
>>> from peft import AdamssConfig, get_peft_model
>>> config = AdamssConfig(
... r=500,
... num_subspaces=5,
... target_modules=["query", "value"],
... )
>>> model = AutoModelForImageClassification.from_pretrained("google/vit-base-patch16-224")
>>> adamss_model = get_peft_model(model, config)속성:
- model (
~torch.nn.Module) — 적응할 모델. - peft_config (AdamssConfig): Adamss 모델의 구성입니다.
중요도 점수를 업데이트하고 ASA 마스킹을 적용합니다(활성화된 경우).
ASA가 활성화된 경우, 이 메서드는 loss.backward() 이후, optimizer.zero_grad() 이전의 모든 학습 단계에서 호출되어야 합니다. 내부적으로:
- 워밍업 기간 동안 각 단계마다 EMA를 통해 중요도 점수를 누적합니다.
- 마스크 간격에서 전역 top-K 마스킹을 적용하고 중요도를 초기화합니다.
ASA의 단일 진입점입니다. HuggingFace Trainer와 함께 AdamssAsaCallback을 사용하면 단순히 이 메서드에 위임됩니다. 커스텀 학습 루프의 경우, 콜백 대신 이 메서드를 직접 호출하세요.