LoRA

LoRA는 가장 인기 있는 PEFT 방법 중 하나로, PEFT를 처음 접하는 분들에게 좋은 출발점이 됩니다. 처음에는 대규모 언어 모델을 위해 개발되었지만, 효율성과 효과성 덕분에 diffusion 모델의 학습 방법으로도 매우 널리 사용됩니다.

Low-Rank Adaptation(LoRA)는 큰 행렬을 두 개의 더 작은 저랭크 행렬로 분해하는 PEFT 방법입니다. 이를 통해 미세 조정해야 하는 매개변수의 수를 크게 줄일 수 있습니다.

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

자연어 처리의 중요한 패러다임 중 하나는 일반 도메인 데이터에 대한 대규모 사전 학습과 특정 작업 또는 도메인에 대한 적응입니다. 더 큰 모델을 사전 학습할수록 모든 모델 파라미터를 다시 학습하는 전체 fine-tuning은 실현 가능성이 낮아집니다. GPT-3 175B를 예로 들어 보면, 175B 파라미터를 가진 fine-tuned 모델의 독립적인 인스턴스를 배포하는 것은 비용 면에서 감당하기 어렵습니다. 우리는 사전 학습된 모델 가중치를 고정하고 Transformer 아키텍처의 각 레이어에 학습 가능한 랭크 분해 행렬을 주입하여 하위 작업의 학습 가능한 파라미터 수를 크게 줄이는 Low-Rank Adaptation, 즉 LoRA를 제안합니다. Adam으로 fine-tuning된 GPT-3 175B와 비교할 때, LoRA는 학습 가능한 파라미터 수를 10,000배, GPU 메모리 요구량을 3배까지 줄일 수 있습니다. LoRA는 학습 가능한 파라미터 수가 적고, 학습 처리량이 높으며, 어댑터와 달리 추가적인 추론 지연이 없음에도 불구하고 RoBERTa, DeBERTa, GPT-2, GPT-3에서 모델 품질 측면으로 fine-tuning과 동등하거나 더 나은 성능을 보입니다. 또한 언어 모델 적응에서의 랭크 부족 현상에 대한 실증적 조사를 제공하여 LoRA의 유효성에 대한 통찰을 제시합니다. PyTorch 모델과의 LoRA 통합을 용이하게 하는 패키지를 공개하고, 이 https URL에서 RoBERTa, DeBERTa, GPT-2에 대한 구현 및 모델 체크포인트를 제공합니다.

LoRA는 가중치 업데이트를 $\Delta W$ 두 개의 더 작은 행렬(업데이트 행렬이라고 함)을 통해 저랭크 분해로 표현합니다. 이 새로운 행렬은 전체 매개변수 수를 낮게 유지하면서 새로운 데이터에 적응하도록 학습할 수 있습니다. 원래의 가중치 행렬은 동결된 상태로 유지되며 추가적인 업데이트를 받지 않습니다. 최종 결과를 생성하려면 원래의 가중치와 추가된 적응 가중치를 결합합니다. 추론 지연을 제거하기 위해 어댑터 가중치를 베이스 모델에 병합하는 것도 가능합니다.)

이 접근 방식에는 다음과 같은 여러 장점이 있습니다:

• LoRA는 학습 가능한 매개변수의 수를 크게 줄여 파인튜닝을 더 효율적으로 만듭니다.
• …
• LoRA는 다른 매개변수 효율적 방법과 직교하며, 그 중 많은 방법과 결합할 수 있습니다.
• LoRA를 사용하여 파인튜닝한 모델의 성능은 완전한 파인튜닝 모델의 성능과 비슷합니다.

원칙적으로 LoRA는 학습 가능한 매개변수의 수를 줄이기 위해 신경망의 가중치 행렬 부분집합에 적용할 수 있습니다. 그러나 단순성과 추가적인 매개변수 효율성을 위해 LoRA는 일반적으로 Transformer 모델의 attention 블록에만 적용되며, 다른 레이어를 대상으로 하는 것도 고려해 볼 가치가 있습니다. LoRA 모델의 학습 가능한 매개변수 수는 업데이트 행렬의 크기에 따라 달라지며, 이는 주로 랭크 r와 원래 가중치 행렬의 형태에 의해 결정됩니다.

다양한 용도를 염두에 두고 저순위 행렬을 초기화할 수 있습니다. 예를 들어, 작업 인식(CorDA, EVA, Astra), 더 빠른 수렴(PiSSA), 양자화 완화(LoftQ) 등이 있습니다. 다양한 초기화 방식에 대해서는 아래에서 확인하세요. 기본 초기화 방식은 LoRA가 no-op(무작동)이 되도록 설정하여, 기존 모델에 크게 간섭하지 않으면서 점진적으로 새로운 동작을 학습하도록 하는 것입니다.

사용

저항 랭크 업데이트 행렬의 크기는 rank 또는 r에 의해 결정됩니다. 랭크가 높을수록 학습할 매개변수가 많아지지만, 모델의 학습 용량도 커집니다. 다음 예시에서는 어텐션 블록의 query 및 value 행렬을 대상으로 합니다. 설정해야 할 다른 중요한 매개변수로는 lora_alpha(스케일링 팩터), bias(none, all 또는 LoRA bias 매개변수만 학습할지 여부), 그리고 modules_to_save(LoRA 레이어 외에 학습 및 저장할 모듈)가 있습니다. 이 모든 매개변수와 그 외의 항목은 LoraConfig에서 찾을 수 있습니다.

from peft import LoraConfig, get_peft_model

config = LoraConfig(
    r=16,
    lora_alpha=16,
    target_modules=["query", "value"],
    lora_dropout=0.1,
    bias="none",
    modules_to_save=["classifier"],
)
model = get_peft_model(model, config)
model.print_healthcheck()

벤치마크 개요

초기화

LoRA 가중치의 초기화는 LoraConfig의 init_lora_weights 매개변수로 제어됩니다. 기본적으로 PEFT는 가중치 A에 Kaiming-uniform, 가중치 B에 제로를 사용하여 LoRA 가중치를 초기화하며, 이는 항등 변환(참조 구현과 동일)을 생성합니다.

GPT-2의 투영과 같은 transformers.Conv1D 레이어의 경우, 가중치가 nn.Linear 레이아웃이 아닌 (in_features, out_features)로 저장되므로 fan_in_fan_out=True를 사용해야 합니다. 지원되는 가중치 기반 초기화기는 분해 시 Linear 레이아웃을 사용하고, 기본 가중치를 업데이트할 때 저장된 레이아웃을 복원합니다. LoRA-GA의 "stable" 스케일링도 저장 레이아웃과 무관하게 출력 차원을 사용합니다.

init_lora_weights="gaussian"를 전달하는 것도 가능합니다. 이름에서 알 수 있듯이, 이는 가중치 A를 가우시안 분포로, 가중치 B를 0으로 초기화합니다(Diffusers가 LoRA 가중치를 초기화하는 방식입니다).

from peft import LoraConfig

config = LoraConfig(init_lora_weights="gaussian", ...)

디버깅 및 테스트에 유용한 init_lora_weights=False 옵션도 있습니다. 이 옵션은 이 경우에만 사용해야 합니다. 이 옵션을 선택하면 LoRA 가중치가 항등 변환(identity transform)을 생성하지 않도록 초기화됩니다.

from peft import LoraConfig

config = LoraConfig(init_lora_weights=False, ...)

from torch import nn

from peft import LoraConfig, get_peft_model

model = nn.Sequential(
    nn.Linear(32, 32),
    nn.ReLU(),
    nn.Linear(32, 16),
)

config = LoraConfig(
    r=8,
    lora_alpha=8,
    target_modules=["0", "2"],
    init_lora_weights="nora",
    bias="none",
    lora_bias=False,
    use_rslora=False,
)
model = get_peft_model(model, config)
model.print_healthcheck()

from peft import LoraConfig
config = LoraConfig(init_lora_weights="pissa", ...)

lora_config = LoraConfig(init_lora_weights="pissa_niter_[number of iters]", ...)

from peft import LoraConfig
config = LoraConfig(init_lora_weights="mica", r=16, target_modules=["q_proj", "v_proj"], ...)

@torch.no_grad()
def run_model():
    # Assume `model` and `dataset` is in context...
    model.eval()
    for batch in dataset:
        model(**batch)


corda_config = CordaConfig(
    corda_method="kpm",
)
lora_config = LoraConfig(
    init_lora_weights="corda",
    corda_config=corda_config,
)
preprocess_corda(model, lora_config, run_model=run_model)
peft_model = get_peft_model(model, lora_config)

@torch.no_grad()
def run_model():
    # Assume `model` and `dataset` is in context...
    model.eval()
    for batch in dataset:
        model(**batch)


from peft.tuners.lora import AstraConfig, preprocess_astra

astra_config = AstraConfig()
lora_config = LoraConfig(
    init_lora_weights="astra",
    target_modules=["q_proj", "v_proj"],
    astra_config=astra_config,
)
preprocess_astra(model, lora_config, run_model=run_model)
peft_model = get_peft_model(model, lora_config)

from peft import LoraConfig
config = LoraConfig(init_lora_weights="olora", ...)

from peft import LoraConfig, EvaConfig
peft_config = LoraConfig(
    init_lora_weights = "eva",
    eva_config = EvaConfig(rho = 2.0),
    ...
)

peft_model = get_peft_model(model, peft_config, low_cpu_mem_usage=True)

initialize_lora_eva_weights(peft_model, dataloader)

from peft import LoraConfig

config = LoraConfig(use_rslora=True, ...)

from peft.tuners.lora import preprocess_loraga

def train_step():
    """Run forward and backward passes for gradient estimation."""
    dataloader_iter = iter(grad_dataloader)
    for _ in range(N):
        batch = next(dataloader_iter)
        batch = {k: v.to(device) for k, v in batch.items()}
        outputs = model(**batch)
        loss = outputs.loss
        loss.backward()

preprocess_loraga(model, lora_config, train_step)

학습

이 섹션에서는 모델에 저순위 어댑터만 적용하고 데이터를 공급하는 것보다 더 복잡한 학습 시나리오를 처리하는 방법을 보여줍니다.

QLoRA 스타일 학습

PEFT의 기본 LoRA 설정은 각 attention 블록의 query와 value 레이어에 학습 가능한 가중치를 추가합니다. 그러나 트랜스포머 모델의 모든 linear 레이어에 학습 가능한 가중치를 추가하는 QLoRA는 완전한 fine-tuning 모델과 동등한 성능을 제공할 수 있습니다. QLoRA처럼 모든 linear 레이어에 LoRA를 적용하려면 target_modules="all-linear"을 설정합니다(아키텍처에 따라 달라질 수 있는 개별 모듈을 이름으로 지정하는 것보다 간단합니다).

config = LoraConfig(target_modules="all-linear", ...)

PEFT 어댑터에 양자화를 적용하는 방법에 대한 자세한 내용은 양자화 가이드를 참고하세요.

LoRA를 활용한 메모리 효율적인 레이어 복제

모델의 성능을 향상시키기 위한 방법 중 하나는, 주어진 크기의 사전 학습 모델에서 레이어를 복제하여 모델을 확장함으로써 더 큰 모델을 구축하는 것입니다. 예를 들어, SOLAR 논문에서 설명된 바와 같이 7B 모델을 10B 모델로 늘리는 경우입니다. PEFT LoRA는 레이어 복제 후 해당 레이어에 연결된 LoRA 어댑터를 사용하여 추가적인 미세 조정을 지원하는 방식으로, 이러한 확장을 메모리 효율적으로 지원합니다. 복제된 레이어는 기존 가중치를 공유하므로 추가 메모리를 사용하지 않으며, 필요한 추가 메모리는 어댑터 가중치를 위한 메모리뿐입니다. 이 기능을 사용하려면 layer_replication 인수를 사용하여 설정을 생성합니다.

config = LoraConfig(layer_replication=[[0,4], [2,5]], ...)

원본 모델이 5개의 레이어 [0, 1, 2 ,3, 4]를 가졌다고 가정하면, 이는 [0, 1, 2, 3, 2, 3, 4]로 구성된 7개의 레이어를 가진 모델을 생성합니다. 이는 mergekit의 pass through merge 규약을 따르며, 시작 레이어를 포함하고 끝 레이어를 제외하는 튜플로 지정된 레이어 시퀀스를 쌓아 최종 모델을 구성합니다. 최종 모델의 각 레이어에는 고유한 LoRA 어댑터 세트가 할당됩니다.

Fewshot-Metamath-OrcaVicuna-Mistral-10B는 Mistral-7B를 10B로 확장하여 이 방법으로 학습한 모델의 예시입니다. adapter_config.json은 이 방법을 적용하여 파인튜닝을 수행하는 LoRA 어댑터 설정의 샘플을 보여줍니다.

랭크와 알파(스케일링)에 대한 세밀한 제어

기본적으로 LoRA가 적용되는 모든 레이어는 LoraConfig에서 지정된 값에 따라 동일한 랭크 r와 동일한 lora_alpha(LoRA 스케일링을 결정)을 사용합니다. 그러나 일부 경우에는 레이어별로 다른 값을 지정하고 싶을 수 있습니다. LoraConfig에 rank_pattern 및 alpha_pattern 인수를 전달하면 이를 수행할 수 있습니다. 이 인수는 키가 레이어 이름이고 값이 랭크/알파 값인 사전(dictionary)이어야 합니다. 키는 정규 표현식(regex)일 수 있습니다. rank_pattern과 alpha_pattern에 명시적으로 언급되지 않은 모든 LoRA 레이어는 기본 r 및 lora_alpha 값을 사용합니다.

예를 들어, 다음과 같은 구조를 가진 모델이 있다고 가정해 보겠습니다.

>>> print(model)
Outer(
  (foo): Linear(...)
  (module): Middle(
    (foo): Linear(...)
    (foobar): Linear(...)
    (module): Inner(
      (foo): Linear(...)
      (barfoo): Linear(...)
    )
  )
)

• rank_pattern={"foo": 42}은 모든 3개의 foo 레이어와 일치합니다. foobar도 barfoo도 일치하지 않습니다.
• rank_pattern={"^foo": 42}은 모델의 foo 레이어만 일치시키며, module.foo나 module.module.foo는 일치시키지 않습니다. 이는 정규식에서 ^가 “문자열의 시작”을 의미하기 때문이며, foo만 "foo"로 시작하고 다른 레이어 이름은 접두사가 있기 때문입니다.
• rank_pattern={"^module.foo": 42}는 같은 이유로 module.foo만 일치하고 module.module.foo는 일치하지 않습니다.
• rank_pattern={"module.foo": 42}은 module.foo와 module.module.foo 모두에 일치하지만 foo에는 일치하지 않습니다.
• rank_pattern={"^foo": 42, "^module.module.foo": 55}은 각각 foo와 module.module.foo에 일치하지만 module.foo에는 일치하지 않습니다.
• PEFT가 자동으로 추가하므로 매치의 끝을 표시하기 위해 $를 명시할 필요가 없습니다.

alpha_pattern에도 동일한 논리가 적용됩니다. 확실하지 않다면 정규식으로 복잡한 처리를 시도하지 마세요. rank/alpha가 다른 각 모듈에 대해 ^ 접두사가 붙은 전체 이름을 그대로 전달하면 됩니다.

적합한 대상 모듈을 자동으로 감지

peft.helpers.KappaTuneSelector는 KappaTune 논문의 조건수 기반 대상 선택 전략을 구현합니다. 모든 nn.Linear 모듈을 스캔하고, MoE 전문가 가중치가 융합된 3차원 nn.Parameter 텐서로 저장된 모델(예: Llama-4, Qwen3-MoE)의 경우 해당 파라미터도 포함하여 각각의 행렬 조건수 κ = σ_max / σ_min을 계산한 후, 가장 등방적인 레이어(가장 낮은 κ)를 선택합니다. 이러한 등방적인 레이어는 고엔트로피 특성으로 인해 새로운 정보를 더 쉽게 흡수할 수 있어 미세 조정의 이상적인 후보로 작용하며, 전문화된 비등방적인 레이어는 그대로 유지되어 지속 학습过程中的 재앙적 망각을 완화합니다.

LoraConfig에 대한 최적의 target_modules를 한 줄로 가져오려면 peft.helpers.find_kappa_target_modules()를 사용하세요:

from peft import LoraConfig, get_peft_model
from peft.helpers import find_kappa_target_modules

model = AutoModelForCausalLM.from_pretrained("mistralai/Mixtral-8x7B-Instruct-v0.1")

targets = find_kappa_target_modules(model, top_p=0.2)
config = LoraConfig(
    target_modules=targets["target_modules"],
    target_parameters=targets["target_parameters"] if stable_modules_dic["target_parameters"] else None,
    r=64,
    lora_alpha=32,
    task_type="CAUSAL_LM",
)
peft_model = get_peft_model(model, config)

완전한 예제는 여기에서 확인하세요.

nn.Parameter를 직접 대상으로 지정

일반적으로 모듈(예: nn.Linear)을 대상으로 지정하려면 target_modules를 사용해야 합니다. 그러나 일부 상황에서는 이것이 불가능합니다. 예를 들어, HF Transformers의 많은 mixture of expert (MoE) 레이어에서는 nn.Linear 대신 nn.Parameter를 사용합니다. PEFT는 LoRA의 경우 forward 메서드를 기본적으로 오버라이드하지만, nn.Parameter에는 해당 메서드가 없습니다. 따라서 해당 파라미터에 LoRA를 적용하려면 target_parameters로 대상 지정을 해야 합니다. 예를 들어, Llama4의 경우 다음을 전달할 수 있습니다: target_parameters=['feed_forward.experts.gate_up_proj', 'feed_forward.experts.down_proj].

expert 파라미터를 대상으로 할 때 PEFT는 상당한 런타임 오버헤드를 추가할 수 있습니다. 그 이유는 필요한 expert의 수가 적더라도 PEFT가 각 expert에 대해 LoRA 기여분을 항상 materialize하기 때문입니다. 학습 중에는 시퀀스 진행 과정에서 일반적으로 expert의 상당 부분이 최소 한 번 이상 활성화되므로 이 영향이 덜합니다. 그러나 추론 시에는 일반적으로 KV cache가 사용되어 마지막 토큰만 계산하면 되므로, 활성화되는 expert의 수가 적습니다. 따라서 MoE 레이어에 LoRA를 사용하면 추론 시 상당한 지연이 발생할 수 있습니다. 이에 대한 권장 사항은 가중치를 병합하는 것입니다(model.merge_adapter() 또는 model = model.merge_and_unload()). 이렇게 하면 PEFT 오버헤드가 제거됩니다.

이 문제에 대한 보다 자세한 조사는 이 MoE 최적화 pull request에서 확인할 수 있습니다.

주의 사항

• 현재 이 인수는 2차원 또는 3차원 nn.Parameter를 대상으로 할 수 있습니다. 3차원 매개변수의 경우, 0번째 차원이 전문가(expert) 차원으로 가정됩니다.
• target_parameters를 사용하는 여러 LoRA 어댑터(model.add_adapter 또는 model.load_adapter를 통해 추가)가 지원되지만, 모든 어댑터는 동일한 매개변수 집합을 대상으로 해야 합니다.

MoE 전문가 파라미터와 vLLM

Transformers의 일부 MoE 모델은 전문가 가중치를 nn.Linear 모듈이 아닌 nn.Parameter 텐서(종종 3차원)로 저장합니다. 해당 전문가에 LoRA를 적용하려면 target_parameters를 사용하고 rank_pattern으로 레이어별 랭크를 설정하세요:

num_experts = getattr(model.config, "num_local_experts", None) or model.config.num_experts
effective_r = max(1, r // num_experts)
config = LoraConfig(
    r=r,
    lora_alpha=32,
    target_modules=["q_proj", "v_proj"],
    target_parameters=[
        # Mixtral / Qwen3-MoE / GPT-OSS
        "mlp.experts.gate_up_proj",
        "mlp.experts.down_proj",
        # Llama4
        # "feed_forward.experts.gate_up_proj",
        # "feed_forward.experts.down_proj",
    ],
    rank_pattern={
        "experts.gate_up_proj": effective_r,
        "experts.down_proj": effective_r,
    },
)

이로 인해 LoRA 파라미터의 총 예산이 dense layer와 유사하게 유지됩니다(Schulman 외의 LoRA Without Regret 참고). Non-expert 모듈은 기본 rank r를 사용합니다.

예를 들어, v0.11.2부터 fused MoE expert layers를 지원하는 vLLM을 사용하면 fine-tuned 모델로 가속화된 추론이 가능합니다.

LoRA와 함께 토큰을 효율적으로 학습

PEFT LoRA 어댑터는 trainable_token_indices 파라미터를 통해 새 토큰을 추가하는 것을 지원합니다. 이를 통해 특정 레이어의 파인튜닝과 함께 다른 토큰도 튜닝할 수 있습니다. 지정된 토큰만 학습되며 모든 다른 토큰은 변경되지 않습니다. 이는 메모리를 절약하고, 전체 임베딩 행렬을 학습하는 경우와 달리 기존 토큰 임베딩에서 학습된 컨텍스트를 유지합니다. 내부적으로 이 방법은 TrainableTokensModel의 레이어를 사용합니다.

# for layer 'embed_tokens'
config = LoraConfig(trainable_token_indices=[idx_1, idx_2, ...], ...)

# specific embedding layer
config = LoraConfig(trainable_token_indices={'emb_tokens': [idx_1, idx_2, ...]}, ...)

아래 코드 조각에서는 모델에 새로운 토큰을 추가하는 방법과 모델의 다른 레이어와 함께 이를 학습하는 방법을 보여줍니다.

from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import get_peft_model, LoraConfig

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-v0.1")

# we define our new tokens and add them to the tokenizer as special tokens
special_tokens = ['<|start_think|>', '<|stop_think|>']
tokenizer.add_special_tokens({'additional_special_tokens': special_tokens})

# make room for new tokens in the embedding matrix if it isn't big enough already
base_model.resize_token_embeddings(max(len(tokenizer), base_model.model.embed_tokens.num_embeddings))

# typical LoRA config with `trainable_token_indices` targeting embedding layer `embed_tokens`
# and specifically our new tokens we just added
lora_config = LoraConfig(
    target_modules='all-linear',
    trainable_token_indices={'embed_tokens': tokenizer.convert_tokens_to_ids(special_tokens)},
)
peft_model = get_peft_model(base_model, lora_config)

# proceed to train the model like normal
[...]

토큰 가중치는 LoRA 가중치와 함께 어댑터 상태 딕셔너리의 일부로 저장됩니다. 전체 파인튜닝 및 임베딩 행렬을 저장했다면 훨씬 더 큰 파일이 저장되었을 것입니다.

VRAM을 얼마나 절약할 수 있는지 대략적인 참고를 위해, 위 예시를 기준으로 임베딩 행렬을 완전히 학습하는 경우(modules_to_save=["embed_tokens"]), 임베딩 행렬에 LoRA를 사용하는 경우(target_modules=[..., "embed_tokens"], 랭크 32), 학습 가능한 토큰을 사용하는 경우(trainable_token_indices=[...], 6개 토큰)를 비교했습니다:

Weight tying

많은 causal LM은 weight tying를 사용합니다. 이는 두 개 이상의 가중치가 동일한 기본 매개변수를 공유하는 기법입니다. 가장 일반적인 경우, 입력 임베딩 가중치(embed_tokens)와 출력 투영 가중치(lm_head)가 동일한 텐서를 공유합니다. 이는 매개변수 수를 줄이면서도 일반적으로 모델 품질을 유지하기 때문입니다.

PEFT가 파인튜닝 대상으로 지정된 이러한 tied weights를 어떻게 처리하는지는 항상 명확하지 않습니다. LoRA의 경우, LoraConfig의 ensure_weight_tying가 해당 레이어에 대해 PEFT가 어댑터 측 업데이트를 명시적으로 tied 상태로 유지할지 여부를 제어합니다. 실제로 이는 modules_to_save, target_modules, trainable_token_indices에 영향을 줄 수 있습니다. 레이어 이름 지정("embed_tokens", "lm_head")에 있어 이 로직은 부분적으로 관례에 의존하며, 이러한 관례가 사용되지 않으면 정상적인 동작을 보장할 수 없습니다.

아래 표는 예상 동작을 요약합니다.

modules_to_save

target_modules

trainable_token_indices

학습 가능한 토큰의 경우, LM head와 embeddings가 연결되어 있더라도 사용자가 이 둘에 대해 다른 토큰을 미세 조정하고 싶어 할 수 있다는 추가적인 복잡성이 있습니다. 따라서 아래 예시 표에서는 동일한 토큰을 미세 조정하는 경우와 다른 토큰을 미세 조정하는 경우를 구분합니다.

사용자에게는 다음과 같은 의미를 갖습니다:

• 일반적으로, 연결된 가중치를 미세 조정하되 연결 상태를 유지하려면 ensure_weight_tying=True를 전달하세요.
• 기본 모델의 가중치가 untied 상태인 경우, ensure_weight_tying=True는 tying을 강제할 수 없으며 경고만 출력합니다.
• trainable_token_indices의 경우, ensure_weight_tying=True일 때 묶인 레이어는 동일한 토큰 인덱스를 사용해야 합니다.

옵티마이저

LoRA 학습에는 선택적으로 특수 목적의 옵티마이저를 포함할 수 있습니다. 현재 PEFT는 LoRA-FA, LoRA+, Riemannian-preconditioned LoRA를 지원합니다.

LoRA-FA 옵티마이저

LoRA-FA에 설명된 바와 같이, LoRA-FA를 사용하면 LoRA 학습이 더 효과적이고 효율적일 수 있습니다. LoRA-FA는 행렬 A를 고정하고 행렬 B만 조정함으로써 활성화 메모리 사용량을 줄입니다. 학습 중에 B의 기울기는 전체 파라미터 미세 조정 기울기를 근사하도록 최적화됩니다. 또한 LoRA-FA의 메모리 사용량은 랭크에 민감하지 않으므로($A$의 활성화를 제거하기 때문), 메모리 사용량 증가 없이 lora 랭크를 늘려 성능을 향상시킬 수 있습니다.

from peft import LoraConfig, get_peft_model
from peft.optimizers import create_lorafa_optimizer
from transformers import Trainer, get_cosine_schedule_with_warmup

base_model = AutoModelForCausalLM.from_pretrained("meta-llama/Meta-Llama-3-8B-Instruct")

config = LoraConfig(...)
model = get_peft_model(base_model, config)

optimizer = create_lorafa_optimizer(
    model=model,
    r=128,
    lora_alpha=32,
    lr=7e-5,
)

scheduler = get_cosine_schedule_with_warmup(
    optimizer,
    num_warmup_steps=100,
    num_training_steps=1000,
)

trainer = Trainer(
    ...,
    optimizers=(optimizer, scheduler),
)

LoRA+ 최적화 LoRA

LoRA 학습은 LoRA+를 사용하여 최적화할 수 있으며, 이는 어댑터 행렬 A와 B에 서로 다른 학습률을 적용하여 파인튜닝 속도를 최대 2배, 성능을 1~2%까지 향상시키는 것으로 입증되었습니다.

from peft import LoraConfig, get_peft_model
from peft.optimizers import create_loraplus_optimizer
from transformers import Trainer
import bitsandbytes as bnb

base_model = ...
config = LoraConfig(...)
model = get_peft_model(base_model, config)

optimizer = create_loraplus_optimizer(
    model=model,
    optimizer_cls=bnb.optim.Adam8bit,
    lr=5e-5,
    loraplus_lr_ratio=16,
)
scheduler = None

...
trainer = Trainer(
    ...,
    optimizers=(optimizer, scheduler),
)

Riemannian-preconditioned LoRA

LoRA 학습은 Riemannian preconditioner를 사용하여 개선할 수 있으며, 이는 Riemannian Preconditioned LoRA. 모든 optimizer step에서 LoRA 행렬 $A$ 과 $B$ 의 그래디언트는 $r \times r$ preconditioner에 의해 곱해집니다. 이 preconditioner는 저순위 행렬 다양체 위에서 유클리드 그래디언트를 Riemannian(scaled-gradient) 방향으로 재조정하여 업데이트의 조건을 더 좋게 만들고 수렴을 개선할 수 있습니다. preconditioner가 $r \times r$ 크기이므로, LoRA rank에 비해 메모리와 런타임 오버헤드는 작습니다. create_riemannian_optimizer 는 모든 기본 optimizer 클래스(예: torch.optim.AdamW 또는 torch.optim.SGD): 를 래핑합니다. LoRA가 아닌 파라미터는 기본 optimizer에 의해 변경 없이 업데이트되고, 오직 nn.Linear-형태의 LoRA 레이어(lora_A / lora_B) 에 대해 preconditioning이 적용됩니다.

from peft import LoraConfig, get_peft_model
from peft.optimizers import create_riemannian_optimizer
from transformers import Trainer, get_cosine_schedule_with_warmup
import torch

base_model = AutoModelForCausalLM.from_pretrained("meta-llama/Meta-Llama-3-8B-Instruct")

config = LoraConfig(...)
model = get_peft_model(base_model, config)

optimizer = create_riemannian_optimizer(
    model=model,
    optimizer_cls=torch.optim.AdamW,
    lr=5e-5,
    reg=1e-2,
)

scheduler = get_cosine_schedule_with_warmup(
    optimizer,
    num_warmup_steps=100,
    num_training_steps=1000,
)

trainer = Trainer(
    ...,
    optimizers=(optimizer, scheduler),
)

reg 는 역전환 전에 $r \times r$ 행렬 대각선에 추가되는 감쇠 항입니다. LoRA 인자가 (거의) 랭크 부족 상태일 때 사전 조건자를 안정화합니다.

Post-Training

이 섹션에서는 학습된 어댑터에 적용할 수 있는 후처리 방법을 보여 줍니다.

LoRA 가중치를 기본 모델에 병합

While LoRA is significantly smaller and faster to train, you may encounter latency issues during inference due to separately loading the base model and the LoRA adapter. To eliminate latency, use the merge_and_unload() function to merge the adapter weights with the base model. This allows you to use the newly merged model as a standalone model. The merge_and_unload() function doesn’t keep the adapter weights in memory.

아래는 LoRA 어댑터 병합의 직관을 설명하는 다이어그램입니다:

아래 스니펫에서 PEFT를 사용하여 이를 실행하는 방법을 보여줍니다.

from transformers import AutoModelForCausalLM
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id)
model = model.merge_and_unload()

반환된 모델을 변수에 할당하고 사용하는 것이 중요합니다. merge_and_unload()는 in-place 연산이 아니기 때문입니다. 나중에 어댑터를 unmerge하거나 삭제하고 다른 어댑터를 로드하기 위해 가중치 사본을 유지해야 하는 경우, 대신 merge_adapter() 함수를 사용해야 합니다. 이제 unmerge_adapter()를 사용하여 베이스 모델로 되돌릴 수 있습니다.

from transformers import AutoModelForCausalLM
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id)
model.merge_adapter()

# unmerge the LoRA layers from the base model
model.unmerge_adapter()

양자화된 모델에서는 unmerge가 정확하지 않습니다. merge는 base weight를 다시 양자화하며, merge와 unmerge 사이클이 반복되면 반올림 오차가 누적될 수 있습니다. 양자화된 가중치에 어댑터 병합을 참조하세요.

여러 개의 어댑터가 활성화되어 있고 그중 일부만 병합된 경우, 병합되지 않은 어댑터는 조용히 적용되지 않습니다. 이 동작은 PEFT v1.0에서 변경됩니다. 활성화된 어댑터 중 일부만 병합하기를 참조하세요.

weights 매개변수에 사용자가 지정한 가중치 스킴을 기반으로 여러 LoRA를 새로운 어댑터로 병합하는 데 add_weighted_adapter() 함수가 유용합니다. 아래는 끝에서 끝까지(end-to-end) 진행되는 예시입니다.

먼저 기본 모델을 로드합니다:

from transformers import AutoModelForCausalLM
from peft import PeftModel
import torch

base_model = AutoModelForCausalLM.from_pretrained(
    "mistralai/Mistral-7B-v0.1", dtype=torch.float16, device_map="auto"
)

그런 다음 첫 번째 어댑터를 로드합니다:

peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id, adapter_name="sft")

그 다음 다른 어댑터를 로드하고 첫 번째 어댑터와 병합합니다:

weighted_adapter_name = "sft-dpo"
model.load_adapter("alignment-handbook/zephyr-7b-dpo-lora", adapter_name="dpo")
model.add_weighted_adapter(
    adapters=["sft", "dpo"],
    weights=[0.7, 0.3],
    adapter_name=weighted_adapter_name,
    combination_type="linear"
)
model.set_adapter(weighted_adapter_name)

combination_type에 대해 여러 가지 지원되는 방법이 있습니다. 자세한 내용은 문서를 참조하세요. 데이터 타입으로 torch.float16 또는 torch.bfloat16를 사용하는 경우, combination_type으로 “svd”는 지원되지 않습니다.

이제 추론을 수행합니다:

device = torch.accelerator.current_accelerator().type if hasattr(torch, "accelerator") else "cuda"

tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-v0.1")

prompt = "Hey, are you conscious? Can you talk to me?"
inputs = tokenizer(prompt, return_tensors="pt")
inputs = {k: v.to(device) for k, v in inputs.items()}

with torch.no_grad():
    generate_ids = model.generate(**inputs, max_length=30)
outputs = tokenizer.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)[0]
print(outputs)

침입자 차원 축소로 베이스 모델 성능 복구

LoRA vs Full Fine-tuning: An Illusion of Equivalence 논문은 LoRA 학습이 이미 학습된 가중치와 거의 공통점이 없는 추가 차원을 가중치에 도입하여 이미 학습된 정보를 망각하게 만든다고 주장합니다. PEFT는 peft.tuners.lora.intruders.reduce_intruder_dimension()에서 제안된 완화 조치를 구현합니다.

완화 방법은 로드된 LoRA가 포함된 PEFT 모델을 가져와서, 기존 어댑터와 함께 로드되며 이제 활성 어댑터가 되는 새로운 수정된 어댑터를 생성합니다.

사용 예시:

from peft.tuners.lora.intruders import reduce_intruder_dimension

peft_model = AutoPeftModelForCausalLM.from_pretrained('hubnemo/llama-3.2b-metamathqa-lora64')

reduce_intruder_dimension(
    peft_model,
    mitigation_lambda=0.75,
)

peft_model.generate(...)

완화 효과의 효율성을 조정하는 데 사용할 수 있는 하이퍼파라미터가 몇 가지 있지만, 해당 논문의 Figure 8에서 입증된 바와 같이 어댑터가 학습한 작업 정확도와 베이스 모델의 지식 망각 사이에는 항상 트레이드오프가 존재합니다. 완화는 이전 지식의 망각에 미치는 영향을 줄이기 위해 어댑터에서 정보를 제거하지만, 이는 어댑터가 학습한 작업에 대한 일부 정보도 함께 손실된다는 것을 의미합니다.

기본값은 두 요인 간의 좋은 균형점을 제공하도록 설정되어 있지만, 해당 기본값이 사용자의 어댑터, 모델 및 데이터에 항상 적용된다는 보장은 없으므로, 그 효과를 측정할 수 있는 벤치마크를 미리 준비해 두는 것이 현명합니다.

어댑터 로드

Adapters는 load_adapter()를 통해 사전 학습된 모델에 로드할 수 있으며, 가중치가 병합되지 않은 다양한 어댑터를 테스트하는 데 유용합니다. 활성 어댑터 가중치는 set_adapter() 함수로 설정합니다.

from transformers import AutoModelForCausalLM
from peft import PeftModel

base_model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
peft_model_id = "alignment-handbook/zephyr-7b-sft-lora"
model = PeftModel.from_pretrained(base_model, peft_model_id)

# load different adapter
model.load_adapter("alignment-handbook/zephyr-7b-dpo-lora", adapter_name="dpo")

# set adapter as active
model.set_adapter("dpo")

기본 모델을 반환하려면 unload()를 사용하여 모든 LoRA 모듈을 언로드하거나 delete_adapter()를 사용하여 어댑터를 완전히 삭제할 수 있습니다. unload()는 in-place 연산이 아니므로, 반환된 모델을 변수에 할당하여 사용해야 합니다.

# unload adapter
model = model.unload()

# delete adapter
model.delete_adapter("dpo")

Tensor 병렬

LoRA는 Transformers에서 제공하는 Tensor Parallelism (TP)를 지원합니다. 기본 모델이 tp_plan과 함께 로드되면, PEFT는 각 대상 모듈의 TP 구성을 자동으로 감지하고 LoRA 어댑터 가중치에 적절한 훅을 추가하여 텐서 병렬 계산에 올바르게 참여하도록 합니다.

LoRA에 대한 Tensor Parallelism 지원에는 transformers >= 5.4.0이 필요합니다. DTensor 기반 Tensor Parallelism API에는 peft >= 0.21.1과 transformers >= 5.17.0이 필요합니다.

사용법은 표준 LoRA 워크플로우와 동일합니다. PEFT로 래핑하기 전에 tp_plan을 사용하여 기본 모델을 로드하면 됩니다:

from transformers import AutoModelForCausalLM
from peft import get_peft_model, LoraConfig

model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.1-8B", tp_plan="auto")
lora_config = LoraConfig(r=16, target_modules=["q_proj", "v_proj"])
model = get_peft_model(model, lora_config)

save_pretrained / from_pretrained를 통해 저장 및 로딩은 평소와 동일하게 작동합니다. PEFT는 저장 전에 샤드된 어댑터 가중치를 전체 텐서로 다시 모으므로, 체크포인트는 이동 가능하며 학습에 사용된 장치 수와 무관합니다.

TP 플랜 없이 텐서 병렬성을 적용하는 경우, 예를 들어 PyTorch의 parallelize_module를 사용하는 경우, PEFT는 가중치의 디바이스 메시에 "tp"라는 이름의 차원이 있으면 샤딩된 nn.Linear의 LoRA 가중치를 해당 로컬 샤드 크기로 설정하고, 그렇지 않으면 전체 레이어 형상으로 설정합니다(FSDP2와 동일). PEFT는 이러한 LoRA 가중치에 TP 훅을 추가하지 않으며, 저장 시에도 이를 수집하지 않습니다. TP 메시 차원의 이름이 다른 경우, PEFT 모델을 생성하기 전에 해당 이름을 추가하세요:

from peft.utils.integrations import TpMeshDimRegistry

TpMeshDimRegistry.register("tp_dim")

추론

이 섹션에서는 LoRA를 사용하여 추론 시기에 수행할 수 있는 작업, 예를 들어 어댑터 분리(uncoupling) 등을 소개합니다.

활성화 LoRA(aLoRA)

Activated LoRA(aLoRA)는 인과적 LM을 위한 저랭크 어댑터 아키텍처로, 기존 베이스 모델의 KV 캐시를 재사용하여 보다 효율적인 추론을 수행합니다. 이 방식은 대부분의 작업/생성에서 베이스 모델에 의존하지만, 체인 내에서 전문화된 작업을 수행하기 위해 aLoRA 어댑터를 사용하는 추론 파이프라인에 가장 적합합니다. 예를 들어, 베이스 모델의 생성된 출력을 확인하거나 수정하는 경우입니다. 이러한 설정에서는 추론 시간을 10배 이상 단축할 수 있습니다. aLoRA에 대한 추가 정보와 다양한 사용 사례는 aLoRA 논문을 참고하세요.

이 기법은 각 입력에서 호출 시퀀스(alora_invocation_tokens)의 마지막 발생 위치를 스캔합니다(이것은 1개의 토큰만으로도 가능합니다). 호출 시퀀스의 시작 부분부터 시작하는 토큰에 대해 어댑터 가중치를 활성화합니다. 호출 시퀀스 이후의 모든 입력도 적응되며, 생성되는 모든 토큰은 적응된 가중치를 사용합니다. 이전 토큰의 가중치는 적응되지 않은 상태로 유지되며, 이는 인과적 LM의 인과적 어텐션 마스크로 인해 해당 토큰의 캐시가 베이스 모델 캐시와 상호 교환 가능하게 만듭니다. 사용법은 표준 LoRA와 매우 유사합니다. 주요 차이점은 어댑터 생성 시 호출 시퀀스를 지정해야 한다는 것입니다:

from peft import LoraConfig

config = LoraConfig(alora_invocation_tokens=alora_invocation_tokens, task_type="CAUSAL_LM", ...)

alora_invocation_tokens는 정수 토큰 ID의 목록입니다. 원하는 호출 문자열이 주어지면, 다음과 같이 이를 얻을 수 있습니다:

invocation_string = "placeholder"
alora_invocation_tokens = tokenizer.encode(invocation_string, add_special_tokens=False).

토크나이저는 베이스 모델의 토크나이저입니다. 검색 문자열에 SOS/EOS 토큰이 추가되지 않도록 add_special_tokens=False를 사용하세요(추가되면 검색이 실패할 가능성이 높습니다).

참고

• aLoRA는 캐시 재사용에 초점을 맞추고 있어 task_type=CAUSAL_LM 작업만 지원합니다.
• 가중치가 더 적은 토큰에 대해 적응되므로, aLoRA는 LoRA보다 더 높은 랭크(r)가 필요한 경우가 많습니다(항상 그런 것은 아닙니다). r=32를 좋은 시작점으로 사용할 수 있습니다.
• aLoRA 가중치는 어댑터 가중치가 토큰의 부분 집합에 선택적으로 적용되기 때문에 정의상 베이스 모델에 병합할 수 없습니다. 병합을 시도하면 오류가 발생합니다.
• Beam search은 아직 지원되지 않습니다.
• 기본 모델에 없는 토큰을 토크나이저에 추가하는 것은 일반적으로 권장되지 않습니다. 이는 기본 모델과 어댑터 모델이 겹치는 컨텍스트에서 작동하는 대상 사용 사례를 복잡하게 만들 수 있습니다. 이를 우회하려면 어댑터 학습 전에 기본 모델에 학습 가능한 토큰을 추가할 수 있습니다.

호출 시퀀스 선택 및 SFT 설계

alora_invocation_tokens 시퀀스는 자동으로 추가되지 않으므로 반드시 추가해야 합니다. 캐시 재사용을 해치지 않으면서 모델 성능을 극대화하기 위해, 어댑터 가중치를 가능한 한 초기(어댑터 전용 프롬프팅의 시작 부분)에 활성화하되, 긴 입력 이후에 활성화하는 것을 권장합니다. 모든 모델과 마찬가지로, 학습과 테스트 간에 포맷이 일관되어야 합니다.

다음 예시를 살펴보세요. 베이스 모델에 채팅 템플릿이 있고, 어댑터가 원하는 출력을 생성하도록 학습하는 것이 목표입니다.

• 옵션 1: 작업별 프롬프트가 없으면, 즉 입력이 assistant 프롬프트를 가진 채팅 히스토리인 경우, 채팅 템플릿의 assistant 프롬프트(예: <|start_of_role|>assistant<|end_of_role|>)를 호출 문자열로 사용하는 것이 자연스러운 선택입니다. 모델의 채팅 템플릿을 확인하여 해당 모델의 프롬프트를 찾아보세요.
• 옵션 2: 어댑터가 학습하는 작업을 설명하는 작업별 프롬프트가 있고, 해당 프롬프트가 생성 직전의 user 턴으로 배치된다면, 채팅 템플릿의 user 프롬프트(예: <|start_of_role|>user<|end_of_role|>)가 호출 문자열로 자연스러운 선택입니다.

호출 문자열을 결정하면, 모델의 토크나이저를 가져와 alora_invocation_tokens를 다음과 같이 얻습니다

alora_invocation_tokens = tokenizer.encode(invocation_string, add_special_tokens=False).

추론 설정의 예시는 alora finetuning에 있습니다.

invocation string에 사용자 정의 문자열을 사용하는 경우, 경계에서의 토큰화 문제를 방지하기 위해 문자열의 시작과 끝이 특수 토큰인지 확인하세요.

그 이유를 이해하려면, 토크나이저에서 ‘a’, ‘b’, ‘c’, ‘ab’가 각각 토큰(번호 1, 2, 3, 4)이라고 가정해 보세요. alora_invocation_tokens = [2, 3]이라고 가정합니다. 이제 입력 문자열이 “abc”라고 생각해 보세요. “ab”가 토큰이므로, 이는 [4,3]으로 토큰화됩니다. 따라서 문자열에 “bc”가 포함되어 있음에도 불구하고 alora_invocation_tokens는 발견되지 않습니다. 그러나 호출 문자열의 시작과 끝이 특수 토큰이라면, 특수 토큰은 다른 문자와 동일한 토큰으로 토큰화되지 않으므로 이러한 실패 사례는 절대 발생하지 않습니다.

생성을 위한 캐시 사용(및 재사용)

aLoRA의 주요 목적은 기본 모델과 aLoRA 어댑터 모델 간의 KV 캐시를 호출 시퀀스 이전에 교환 가능하게 만드는 것입니다. 기본 모델과 어댑터 모델의 KV 값은 호환되지 않기 때문입니다. 구체적으로, 한 번의 모델 생성 동안 저장된 키와 값은 컨텍스트 토큰에 대한 비용이 높은 prefill 작업을 피하기 위해 후속 생성에 사용할 수 있습니다. 기본 모델과 aLoRA 어댑터 간에 캐시를 공유할 때, 두 가지 주요 패턴이 있습니다:

1. 기본 모델이 무언가를 생성한 후, aLoRA 어댑터가 호출되어 후속 생성을 수행합니다. 예를 들어, 기본 모델이 질문에 답하고, 환각(hallucination) 감지를 위해 학습된 aLoRA가 기본 모델의 응답을 검사하는 경우입니다.
2. aLoRA 어댑터가 어떤 것을 생성한 후, 베이스 모델 또는 다른 aLoRA 어댑터가 원래 aLoRA와 부분적으로 컨텍스트가 겹치는 후속 생성을 수행하도록 호출되는 경우입니다. 예를 들어, 사용자가 쿼리를 제공하고 aLoRA가 RAG 시스템에서 검색을 개선하기 위해 쿼리를 더 자기 완결적으로 재작성합니다. 그런 다음 문서가 검색되어 컨텍스트에 로드되고, aLoRA가 이 문서들이 질문에 관련되는지 확인한 후, 베이스 모델이 답변을 생성합니다.

캐싱을 사용할 때 위 동작을 시연하기 위해 transformers의 DynamicCache를 사용합니다. 적응된 캐시 값이 기본 캐시 값과 섞이지 않도록 주의하세요. 특히 부분적인 컨텍스트 중복이 있는 경우(패턴 2)에는 캐시를 공유하려면 추가 단계가 필요합니다.

패턴 1: 베이스 모델 후 aLoRA 여기서 베이스 모델의 전체 입력과 생성 결과가 호출 시퀀스와 함께 aLoRA 어댑터에 입력됩니다:

from transformers import DynamicCache
...
cache = DynamicCache()
inputs_base = tokenizer(prompt_base, return_tensors="pt")
# Generate from base model and save cache
with model_alora.disable_adapter():
    output = model_alora.generate(inputs_base["input_ids"].to(device),attention_mask=inputs_base["attention_mask"].to(device),past_key_values = cache,return_dict_in_generate=True)
output_text_base = tokenizer.decode(output.sequences[0])
cache = output.past_key_values

# Generate with aLoRA adapter from cache
prompt_alora = output_text + INVOCATION_STRING
inputs_alora = tokenizer(prompt_alora, return_tensors="pt").to(device)
output = model_alora.generate(**inputs_alora, past_key_values=cache)
output_text_alora = tokenizer.decode(output[0])

# Note: cache is now tainted with adapter values and cannot be used in base model from here on!

패턴 2: aLoRA 생성 후 부분적인 컨텍스트가 겹치는 베이스 모델(또는 다른 aLoRA) 사용 여기서는 베이스 모델을 사용하여 공유 컨텍스트를 사전 입력(prefill)한 다음 생성을 수행합니다.

from transformers import DynamicCache
import copy
...
cache = DynamicCache()
inputs_shared = tokenizer(prompt_shared, return_tensors="pt").to(device)

# Prefill from base model and save cache
with model_alora.disable_adapter():
    with torch.no_grad():
        model_alora(**inputs_shared, past_key_values=cache)
cache_copy = copy.deepcopy(cache)

# Generate from aLoRA using prefilled cache
prompt_alora = prompt_shared + INVOCATION_STRING
inputs_alora = tokenizer(prompt_alora, return_tensors="pt").to(device)
output = model_alora.generate(**inputs_alora, past_key_values=cache)
output_text_alora = tokenizer.decode(output[0])

# Generate from base model using saved cache not tainted by aLoRA KV values
prompt_base = prompt_shared
inputs_base = tokenizer(prompt_base, return_tensors="pt").to(device)
with model_alora.disable_adapter():
    output = model_alora.generate(**inputs_base, past_key_values=cache_copy)
output_text_base = tokenizer.decode(output[0])

같은 배치에서 서로 다른 LoRA 어댑터로 추론

일반적으로 PEFT에서는 각 추론 배치에 동일한 어댑터를 사용해야 합니다. 이는 때때로 번거로울 수 있습니다. 서로 다른 LoRA 어댑터와 함께 사용하도록 의도된 샘플이 포함된 배치가 있을 수 있기 때문입니다. 예를 들어, 영어에서 잘 작동하는 베이스 모델과 프랑스어용, 독일어용 LoRA 어댑터 두 개가 있을 수 있습니다. 일반적으로 각 배치에 하나의 언어 샘플만 포함되도록 배치를 분리해야 하며, 서로 다른 언어를 동일한 배치에 결합할 수 없습니다.

다행히도 adapter_name 인수를 사용하여 동일한 배치에 서로 다른 LoRA 어댑터를 혼합할 수 있습니다. 아래에서는 이를 실제로 적용하는 예시를 보여줍니다. 먼저, 기본 모델, 영어, 그리고 두 개의 어댑터인 프랑스어와 독일어를 다음과 같이 로드합니다:

from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import PeftModel

model_id = ...
tokenizer = AutoTokenizer.from_pretrained(model_id)

model = AutoModelForCausalLM.from_pretrained(model_id)
# load the LoRA adapter for French
peft_model = PeftModel.from_pretrained(model, <path>, adapter_name="adapter_fr")
# next, load the LoRA adapter for German
peft_model.load_adapter(<path>, adapter_name="adapter_de")

이제 세 가지 언어가 모두 포함된 샘플에서 텍스트를 생성하려고 합니다. 첫 번째 샘플 3개는 영어, 다음 3개는 프랑스어, 마지막 3개는 독일어입니다. 각 샘플에 사용할 어댑터를 지정하려면 adapter_names 인수를 사용할 수 있습니다. 기본 모델이 영어에 사용되므로, 해당 샘플에는 특수 문자열 "__base__"을 사용합니다. 다음 3개 샘플에는 프랑스어 LoRA 파인튜닝의 어댑터 이름, 이 경우 "adapter_fr"을 지정합니다. 마지막 3개 샘플에는 독일어 LoRA 파인튜닝의 어댑터 이름, 이 경우 "adapter_de"를 지정합니다. 이렇게 하면 기본 모델과 두 개의 어댑터를 단일 배치에서 사용할 수 있습니다.

inputs = tokenizer(
    [
        "Hello, my dog is cute",
        "Hello, my cat is awesome",
        "Hello, my fish is great",
        "Salut, mon chien est mignon",
        "Salut, mon chat est génial",
        "Salut, mon poisson est super",
        "Hallo, mein Hund ist süß",
        "Hallo, meine Katze ist toll",
        "Hallo, mein Fisch ist großartig",
    ],
    return_tensors="pt",
    padding=True,
)

adapter_names = [
    "__base__", "__base__", "__base__",
    "adapter_fr", "adapter_fr", "adapter_fr",
    "adapter_de", "adapter_de", "adapter_de",
]
output = peft_model.generate(**inputs, adapter_names=adapter_names, max_new_tokens=20)

여기서는 순서가 중요하지 않으며, 즉 위의 예시처럼 배치 내 샘플을 어댑터별로 그룹화할 필요가 없습니다. adapter_names 인수가 샘플과 올바르게 정렬되어 있는지 확인하면 됩니다.

또한, 동일한 접근 방식은 modules_to_save 기능과도 함께 작동합니다. 이 기능은 분류 작업용 커스텀 헤드와 같은 특정 신경망 레이어를 저장하고 다른 LoRA 어댑터 간에 재사용할 수 있도록 합니다.

주의 사항

이 기능을 사용하면 다음과 같은 단점이 있습니다:

• 추론에만 작동하며, 학습에는 작동하지 않습니다.
• with model.disable_adapter() 컨텍스트를 사용하여 어댑터를 비활성화하는 것이 adapter_names보다 우선합니다.
• 일부 어댑터 가중치가 merge_adapter 메서드를 사용하여 기본 가중치와 병합된 경우 adapter_names를 전달할 수 없습니다. 먼저 model.unmerge_adapter()를 호출하여 모든 어댑터를 병합 해제하십시오. adapter_names 외부에서도 활성 어댑터 중 일부만 병합하는 경우 유사한 주의 사항이 있습니다.
• 명백한 이유로, 이 방법은 merge_and_unload() 호출 이후에는 사용할 수 없습니다. 이 경우 모든 LoRA 어댑터가 기본 가중치에 병합되기 때문입니다.
• 이 기능은 현재 DoRA와 함께 작동하지 않으므로, 이 기능을 사용하려면 LoraConfig에서 use_dora=False로 설정하세요.
• modules_to_save 기능은 현재 Linear, Embedding, Conv2d, Conv1d 유형의 레이어만 지원합니다.
• 추론 시 adapter_names, 에 대한 예상 오버헤드가 있습니다. 특히 배치 내 서로 다른 어댑터의 수가 많을 경우 더욱 그렇습니다. 이는 배치 크기가 실제로는 어댑터당 샘플 수로 줄어듦을 의미하기 때문입니다. 런타임 성능이 최우선이라면 다음을 시도해 보세요: 배치 크기를 늘리세요. 같은 배치에 서로 다른 어댑터가 너무 많이 포함되지 않도록 하세요. 동질적인 배치를 선호하는 것이 좋습니다. 이는 동일한 어댑터를 가진 샘플을 버퍼링하고, 소수의 서로 다른 어댑터만 사용하여 추론을 수행함으로써 달성할 수 있습니다. LoRAX, punica, S-LoRA와 같이 서로 다른 어댑터가 많이 있는 환경에 특화된 대안 구현을 살펴보세요.
  • 배치 크기를 증가시킵니다.
  • batch 내에 서로 다른 adapter가 너무 많도록 하는 것은 피하고, 동질적인 batch를 사용하는 것이 좋습니다. 이를 위해 동일한 adapter를 가진 샘플을 버퍼링하고, 소수의 서로 다른 adapter만 사용하여 추론을 수행하면 됩니다.
  • 다양한 어댑터와 함께 작동하도록 특화된 LoRAX, punica, S-LoRA와 같은 대안 구현을 살펴보세요.

LoRA 어댑터 구성 및 재사용

Arrow

Arrow은 여러 사전 학습된 작업별 LoRA 어댑터를 결합하여 주어진 작업을 해결하도록 설계된 모듈형 라우팅 알고리즘으로, Polytropon과 유사하지만 미세 조정 없이 작동합니다. 모든 어댑터를 단순히 병합하는 대신, Arrow는 그라디언트 없이 토큰 단위로 동작하는 mixture-of-experts(MoE) 라우팅 메커니즘을 도입합니다. 추론 시, 각 LoRA의 SVD 분해에서 상위 우측 특이 벡터를 추출하여 프로토타입을 계산합니다. 이후 각 토큰 표현을 이러한 프로토타입과 코사인 유사도를 통해 비교하여 라우팅 계수를 구합니다. 토큰은 상위 k개의 가장 관련성 높은 LoRA 어댑터에 할당되며, 계수는 softmax를 통해 정규화되고, 그 출력은 선형 결합됩니다. 이를 통해 기존 LoRA 모듈을 새로운 작업에 효과적으로 재사용할 수 있으며, 더 강력한 제로샷 일반화 성능을 달성합니다.

In PEFT, Arrow is enabled through [`ArrowConfig]andcreate_arrow_model. You can also configure parameters such astop_k(the number of LoRA adapters combined per token),router_temperature(the softmax temperature applied to the routing coefficients), andrng_seed` (for reproducibility).

from peft import create_arrow_model, ArrowConfig
from transformers import AutoModelForCausalLM

# Loading the model
base_model = AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct")

# Creating the Arrow config
arrow_config = ArrowConfig(
    top_k=3,
    router_temperature=1.0,
    rng_seed=42,
)

# The LoRA adapters below were trained on a clustered FLAN dataset.
# Task clustering was performed using the Model-Based Clustering (MBC) method,
# as described in the Arrow paper.
# While one could train a separate LoRA for each task and let Arrow route tokens among them,
# training LoRAs on clusters of tasks instead provides an indirect optimization for
# transfer across the multi-task dataset.
task_specific_adapter_paths = [
        f"TahaBa/phi3-mini-clustered-flan/ts_expert_{i}" for i in range(10)
    ]

# Creating the Arrow model
model = create_arrow_model(
        base_model=base_model,
        task_specific_adapter_paths=task_specific_adapter_paths,
        arrow_config=arrow_config,
    )

# Now the forward path could be called on this model, like a normal PeftModel.

또한 create_arrow_model 호출 후 어댑터를 추가하거나 제거할 수 있습니다. 예를 들어, 새로운 어댑터를 파인튜닝하거나 불필요한 어댑터를 삭제하는 경우입니다. 어댑터가 설정된 후에는 추론 시 Arrow를 사용하도록 "arrow_router"를 활성화할 수 있습니다. create_arrow_model 호출 후 새로운 LoRA 어댑터를 추가하여 파인튜닝하려는 경우, create_arrow_model에서 기본적으로 "arrow_router"가 활성화되어 있으므로 새로운 어댑터를 명시적으로 활성 상태로 설정해야 합니다.

from trl import SFTTrainer, SFTConfig

# Adding a new adapter and activating it
model.add_adapter(adapter_name='new_adapter')
model.set_adapter('new_adapter')

# Now the model could be trained along the `new_adapter`.
trainer = SFTTrainer(
        model=model,
        args=SFTConfig(...),
        ...
    )

# Once the training is done, you can activate `arrow_router` and use it in inference
model.set_adapter('arrow_router')    # Model is ready to be used at inference time now

GenKnowSub

GenKnowSub는 라우팅 전에 작업별 LoRA 어댑터를 정제하여 Arrow를 강화합니다. 핵심 아이디어는 부정을 통한 망각(forgetting-via-negation) 원리에 기반하여 LoRA 공간에 인코딩된 일반 지식을 차감하는 것입니다. 이를 통해 작업 어댑터가 더 격리되고 작업 관련 신호에 집중되도록 합니다. 구체적으로, GenKnowSub는 일반(작업 비특정) LoRA 어댑터 집합에서 저차원 “일반” 부분공간을 추정하고, Arrow의 토큰 단위 라우팅 전에 각 작업 어댑터의 LoRA 업데이트에서 이 구성 요소를 제거합니다. 이는 여러 작업 어댑터를 결합할 때 조합성을 향상시키고 간섭을 줄이는 데 일반적으로 도움이 됩니다.

PEFT에서 use_gks=True를 ArrowConfig에 설정하고 create_arrow_model에 general_adapter_paths를 제공하여 GenKnowSub를 활성화합니다:

from peft import create_arrow_model, ArrowConfig
from transformers import AutoModelForCausalLM

# Loading the model
base_model = AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct")

# Creating the Arrow config
arrow_config = ArrowConfig(
    top_k=3,
    router_temperature=1.0,
    use_gks=True,
    rng_seed=42,
)

# Path to task-specific, trained on flan clustered dataset (as we explained before.)
task_specific_adapter_paths = [
        f"TahaBa/phi3-mini-clustered-flan/ts_expert_{i}" for i in range(10)
    ]
# These general adapters are trained on English, German, and French Wikipedia dataset,
# with causal language modelling objective, each pair like: (507 token tsentence, 5 token completion), and the loss computed on the completion
general_adapter_paths = [
        "TahaBa/phi3-mini-general-adapters/cluster0_batch16_prop1.0_langen/checkpoint-17",
        "TahaBa/phi3-mini-general-adapters/cluster0_batch16_prop1.0_langfr/checkpoint-35",
        "TahaBa/phi3-mini-general-adapters/cluster0_batch16_prop1.0_langger/checkpoint-17"
    ]

# Creating the Arrow model
model = create_arrow_model(
        base_model=base_model,
        task_specific_adapter_paths=task_specific_adapter_paths,
        general_adapter_paths=general_adapter_paths,
        arrow_config=arrow_config,
    )

# Now the forward path could be called on this model, like a normal PeftModel.

일반 지식을 인코딩하기 위해 GenKnowSub는 라우팅이 시작되기 전에 제공된 일반 어댑터의 평균을 각 작업별 어댑터에서 한 번 뺍니다. 또한, create_arrow_model을 호출한 후(Arrow 섹션에 설명된 대로) 어댑터를 추가하거나 제거하는 기능도 이 경우 여전히 지원됩니다.

Arrow + GenKnowSub를 사용할 때 알아두어야 할 사항:

• 모든 LoRA 어댑터(작업별 및 일반)는 동일한 rank와 target_modules를 공유해야 합니다.

• 이러한 설정에 일관성이 없으면 create_arrow_model에서 오류가 발생합니다.

• 작업 어댑터마다 다른 스케일링 팩터(lora_alpha)를 사용하는 것이 지원되며, Arrow가 이를 자동으로 처리합니다.

• 동적 라우팅 동작으로 인해 "arrow_router" 병합은 지원되지 않습니다.

• create_arrow_model에서 태스크 어댑터는 task_i로, 일반 어댑터는 gks_j로 로드됩니다(여기서 i와 j는 인덱스입니다). 이 함수는 target_modules, rank, 그리고 어댑터가 Linear 레이어인지 Linear4bit 레이어인지에 적용되는지의 일관성을 보장합니다. 그런 다음 "arrow_router" 모듈을 추가하고 활성화합니다. 이 프로세스의 커스터마이징은 create_arrow_model을 오버라이드해야 합니다.

• 이 구현은 4-bit 양자화(bitsandbytes를 통해)와 호환됩니다:

  복사됨

  from transformers import AutoModelForCausalLM, BitsAndBytesConfig
  import torch
  
  # Quantisation config
  bnb_config = BitsAndBytesConfig(
          load_in_4bit=True,
          bnb_4bit_quant_type="nf4",
          bnb_4bit_compute_dtype=torch.bfloat16,
          bnb_4bit_use_double_quant=False,
      )
  
  # Loading the model
  base_model = AutoModelForCausalLM.from_pretrained(
      "microsoft/Phi-3-mini-4k-instruct",
      dtype=torch.bfloat16,
      device_map="auto",
      quantization_config=bnb_config,
  )
  
  # Now call create_arrow_model() as we explained before.

API

LoraConfig

LoraModel

>>> from transformers import AutoModelForSeq2SeqLM
>>> from peft import LoraConfig, get_peft_model

>>> config = LoraConfig(
...     task_type="SEQ_2_SEQ_LM",
...     r=8,
...     lora_alpha=32,
...     target_modules=["q", "v"],
...     lora_dropout=0.01,
... )

>>> model = AutoModelForSeq2SeqLM.from_pretrained("t5-base")
>>> lora_model = get_peft_model(model, config)

>>> import torch
>>> import transformers
>>> from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training

>>> rank = ...
>>> target_modules = ["q_proj", "k_proj", "v_proj", "out_proj", "fc_in", "fc_out", "wte"]
>>> config = LoraConfig(
...     r=4, lora_alpha=16, target_modules=target_modules, lora_dropout=0.1, bias="none", task_type="CAUSAL_LM"
... )
>>> quantization_config = transformers.BitsAndBytesConfig(load_in_8bit=True)

>>> tokenizer = transformers.AutoTokenizer.from_pretrained(
...     "kakaobrain/kogpt",
...     revision="KoGPT6B-ryan1.5b-float16",  # or float32 version: revision=KoGPT6B-ryan1.5b
...     bos_token="[BOS]",
...     eos_token="[EOS]",
...     unk_token="[UNK]",
...     pad_token="[PAD]",
...     mask_token="[MASK]",
... )
>>> model = transformers.GPTJForCausalLM.from_pretrained(
...     "kakaobrain/kogpt",
...     revision="KoGPT6B-ryan1.5b-float16",  # or float32 version: revision=KoGPT6B-ryan1.5b
...     pad_token_id=tokenizer.eos_token_id,
...     use_cache=False,
...     device_map={"": rank},
...     torch_dtype=torch.float16,
...     quantization_config=quantization_config,
... )
>>> model = prepare_model_for_kbit_training(model)
>>> lora_model = get_peft_model(model, config)

유틸리티

ArrowConfig

LoftQ

replace_lora_weights_loftq

LoftQConfig

Eva

EvaConfig

initialize_lora_eva_weights

get_eva_state_dict

LoraGAConfig

유틸리티

침입자 차원 축소