PEFT documentation
문제 해결
문제 해결
PEFT를 사용하면서 문제가 발생하면, 다음에 나열된 일반적인 문제와 해결 방법을 확인해 보세요.
예제가 작동하지 않습니다
예제는 최신 패키지 버전에 의존하는 경우가 많으므로, 최신 버전으로 업데이트되어 있는지 확인해 주세요. 특히 다음 패키지 버전을 확인해 주세요:
pefttransformersacceleratetorch
일반적으로 Python 환경에서 다음 명령을 실행하여 패키지 버전을 업데이트할 수 있습니다:
python -m pip install -U <package_name>
PEFT를 소스에서 설치하는 것은 최신 개발 동향을 따라가기에 유용합니다:
python -m pip install git+https://github.com/huggingface/peft
Dtype 관련 문제
ValueError: FP16 그래디언트 스케일 해제 시도
이 오류는 모델이 dtype=torch.float16로 로드된 후 자동 혼합 정밀도(AMP) 컨텍스트에서 사용되었기 때문에 발생했을 가능성이 높습니다. 예를 들어, 🤗 Transformers의 Trainer 클래스에서 fp16=True를 설정하는 경우입니다. AMP를 사용할 때 학습 가능한 가중치는 fp16을 사용해서는 안 되기 때문입니다. 전체 모델을 fp32로 로드하지 않고 이 문제를 해결하려면 다음을 코드에 추가하세요:
peft_model = get_peft_model(...)
# add this:
for param in model.parameters():
if param.requires_grad:
param.data = param.data.float()
# proceed as usual
trainer = Trainer(model=peft_model, fp16=True, ...)
trainer.train()대신 cast_mixed_precision_params() 함수를 사용하여 가중치를 올바르게 캐스팅할 수 있습니다:
from peft import cast_mixed_precision_params
peft_model = get_peft_model(...)
cast_mixed_precision_params(peft_model, dtype=torch.float16)
# proceed as usual
trainer = Trainer(model=peft_model, fp16=True, ...)
trainer.train()PEFT v0.12.0 버전부터 PEFT는 적절한 상황에서 어댑터 가중치의 dtype를
torch.float16및torch.bfloat16에서torch.float32로 자동으로 승격합니다. 이 동작을 방지하려면autocast_adapter_dtype=False를 ~get_peft_model(), from_pretrained(), load_adapter()에 전달할 수 있습니다.
어댑터의 dtype 선택
LoRA와 같은 대부분의 PEFT 방법은 학습 가능한 어댑터 가중치를 추가하여 작동합니다. 기본적으로 이러한 가중치는 float32 dtype(fp32), 즉 상대적으로 높은 정밀도로 저장됩니다. 따라서 베이스 모델이 float16(fp16) 또는 bfloat16(bf16)로 로드되더라도 어댑터 가중치는 float32입니다. 포워드 패스 동안 어댑터 결과가 계산될 때, 입력은 일반적으로 베이스 모델의 dtype을 가지므로 필요에 따라 float32로 업캐스트된 후 원래의 dtype으로 다시 캐스트됩니다.
어댑터 가중치를 베이스 모델의 낮은 정밀도, 즉 float16 또는 bfloat16로 유지하려면 모델을 생성할 때(~get_peft_model()) 또는 로드할 때(from_pretrained()) autocast_adapter_dtype=False를 전달할 수 있습니다. 이렇게 하면 다음과 같은 장단점이 있습니다:
반정수형 어댑터의 장점:
- 계산이 약간 더 빠름
- 메모리가 약간 적게
- 체크포인트의 더 작은 파일 크기(크기의 절반)
반정수 정밀도 어댑터의 단점:
- 약간 더 높은 손실
- 오버플로우 또는 언더플로우 발생 위험이 더 높음
대부분의 사용 사례에서 전체 실행 시간과 메모리 비용은 베이스 모델의 크기와 데이터셋에 의해 결정되며, PEFT 어댑터의 dtype은 상대적으로 작은 영향을 미칩니다.
트레이닝은 실행되지만 모델이 개선되지 않습니다
학습이 정상적으로 진행되고 있는 것 같지만(손실이 감소하고, 체크포인트가 오류 없이 저장됨) 결과 모델이 기본 모델보다 성능이 향상되지 않는다면, 학습 중 학습 가능한 매개변수가 실제로 변경되었는지 확인하세요:
# before training
sample_param = next(p for p in model.parameters() if p.requires_grad)
before = sample_param.detach().clone()
# ... train for at least three optimizer steps ...
after = next(p for p in model.parameters() if p.requires_grad)
print("weights updated:", not torch.allclose(before, after.detach().cpu()))forward 또는 backward 훅 누락
가중치가 이동하지 않았다면, 가장 유력한 원인은 파라미터가 대상 디바이스에 물리적으로 생성되기 전에 파라미터 참조가 캡처되었기 때문일 수 있습니다. 이는 대상 디바이스로 이동되기 전의 파라미터를 가진 베이스 모델이 get_peft_model()로 래핑된 후, 서드파티 라이브러리가 forward/backward 훅(예: 차등 프라이버시 프레임워크의 샘플별 그래디언트 훅)을 등록하거나 첫 번째 forward 호출 전에 옵티마이저가 생성되는 경우 발생할 수 있습니다. 이후 파라미터가 물리적으로 생성되면, 해당 훅과 옵티마이저 참조는 오래된 텐서를 가리키게 되어 모든 업데이트가 조용히 무시되는 no-op가 됩니다.
이를 피하려면 다음 순서를 사용하세요:
- 기본 모델을 로드하고 대상 장치로 이동합니다(예:
model.to(device)). - get_peft_model()로 감싸세요.
- 그 후에야 훅을 등록하거나 옵티마이저를 생성할 수 있습니다.
Target modules가 모델과 일치하지 않습니다
학습이 오류 없이 실행되지만 손실이 거의 변하지 않거나, 파인튜닝 후 모델에 개선이 보이지 않는 경우, 설정된 target_modules(사용자가 별도로 지정하지 않은 경우 기본 target_modules)가 모델의 실제 모듈 이름과 일치하지 않을 수 있습니다. 이는 표준 Transformer 모델과 다른 레이어 이름을 사용하는 Mamba, Jamba, NemotronH와 같은 하이브리드 아키텍처에서 흔히 발생하는 문제입니다.
PEFT는 구성된 target_modules 중 어떤 것도 모델의 모듈과 일치하지 않을 때만 오류를 발생시킵니다. 일부가 일치하고 일부가 일치하지 않는 경우, 일치하지 않는 항목은 경고 없이 조용히 건너뜁니다. 모델의 상당 부분이 아무런 표시 없이 동결된 상태로 남을 수 있습니다.
첫 번째 진단은 학습 가능한 매개변수 수를 확인하는 것입니다:
from peft import LoraConfig, get_peft_model
config = LoraConfig(target_modules=["q_proj", "v_proj", "gate_proj"])
model = get_peft_model(base_model, config)
model.print_healthcheck()보고된 숫자가 예상보다 훨씬 낮다면, 모델의 어댑터 레이어를 검사하세요:
print(model.get_layer_status())이것은 각 어댑터 레이어의 이름, 모듈 유형, 활성화 상태 및 활성 어댑터를 보여주는 TunerLayerStatus 항목의 목록을 반환합니다. 또는 모델의 repr을 출력(print(model))하면 전체 모듈 계층 구조의 개요를 확인할 수 있으며, 이는 익숙하지 않은 아키텍처에서 올바른 레이어 이름을 식별하는 데 유용합니다.
모델의 모듈에 해당하지 않는 target_modules 항목은 조용히 건너뜁니다. target_modules를 실제 모듈 이름과 일치하도록 업데이트하세요.
이 문제는 LoRA뿐만 아니라
target_modules를 사용하는 모든 PEFT 방법(LoRA, LoHa, IA³ 등)에 영향을 미칩니다. 사용 방법에 관계없이 진단 단계는 동일합니다. 특정 아키텍처가 어떤 모듈 이름을 사용하는지 확실하지 않다면, 어댑터를 구성하기 전에 모델의 문서를 확인하거나model.named_modules()를 검사해 보세요.
로드된 PEFT 모델에서 결과가 좋지 않은 경우
로드된 PEFT 모델에서 결과가 좋지 않은 이유는 여러 가지가 있으며, 아래에 나열되어 있습니다. 여전히 문제를 해결할 수 없다면 GitHub에서 다른 사람이 비슷한 이슈를 겪었는지 확인해 보시고, 관련 이슈가 없다면 새로운 이슈를 등록하세요.
이슈를 열 때, 해당 문제를 재현하는 최소한의 코드 예시를 제공하면 큰 도움이 됩니다. 또한, 로드된 모델이 파인튜닝 전과 동일한 수준으로 성능을 발휘하는지, 무작위 수준으로 성능을 발휘하는지, 아니면 예상보다 약간만 나쁜지 보고해 주세요. 이 정보는 문제를 더 빠르게 식별하는 데 도움이 됩니다.
무작위 편차
모델의 출력이 이전 실행 결과와 정확히 일치하지 않는다면, 무작위 요소에 문제가 있을 수 있습니다. 예를 들어:
- 모델이 dropout을 사용하는 경우와 같이 중요한 사항이므로,
.eval()모드인지 확인하세요. - 언어 모델에 generate를 사용하면 무작위 샘플링이 발생할 수 있으므로 동일한 결과를 얻으려면 무작위 시드를 설정해야 합니다
- quantization를 사용하고 가중치를 병합한 경우, 반올림 오류로 인해 작은 편차가 발생할 수 있습니다
잘못 로드된 모델
모델을 올바르게 로드했는지 확인하세요. 학습된 모델을 get_peft_model()로 로드하려는 시도는 잘못된 일반적인 오류입니다. 대신 로드 코드는 다음과 같이 작성해야 합니다:
from peft import PeftModel, PeftConfig
base_model = ... # to load the base model, use the same code as when you trained it
config = PeftConfig.from_pretrained(peft_model_id)
peft_model = PeftModel.from_pretrained(base_model, peft_model_id)어댑터를 우회하는 최적화된 실행 경로
일부 최적화된 실행 경로는 모듈의 forward 메서드를 호출하는 대신 모듈 가중치를 직접 읽습니다. 이로 인해 어댑터가 활성화된 상태여도 병합되지 않은 어댑터에 의해 이루어진 변경 사항이 경고 없이 건너뛸 수 있습니다. 이 문제는 다양한 모듈과 PEFT 메서드에 영향을 줄 수 있습니다.
예를 들어, PyTorch의 네이티브 torch.nn.TransformerEncoder는 torch.no_grad() 또는 torch.inference_mode()를 사용하여 평가 시 fused path를 사용할 수 있습니다. 이 path는 TransformerEncoderLayer 서브모듈의 어댑터를 건너뛸 수 있으며, 예를 들어 linear1과 linear2에 있는 LoRA 어댑터가 해당됩니다. 학습은 올바르게 작동할 수 있지만 평가에서는 어댑터 변경 사항이 무시될 수 있습니다. 재현 방법은 issue #3976을 참고하세요.
이 문제가 의심되면 먼저 get_layer_status()를 사용하여 어댑터가 활성화되어 있고 활성 상태인지 확인하세요. 평가 모드에서 동일한 입력에 대해 어댑터가 있는 경우와 없는 경우의 출력을 비교한 후, 최적화가 비활성화된 경우와 비교하세요. 출력을 변경하는 학습된 어댑터를 사용해야 하며, 새로 초기화된 LoRA 어댑터는 일반적으로 효과가 없기 때문입니다. 작은 수치적 차이는 정상입니다.
eager 모드에서 네이티브 인코더의 병합되지 않은 어댑터의 경우, 동일한 텐서 입력 x에 대한 출력을 비교합니다:
import torch
model.eval()
previous = torch.backends.mha.get_fastpath_enabled()
try:
with torch.inference_mode():
torch.backends.mha.set_fastpath_enabled(True)
fast_output = model(x)
torch.backends.mha.set_fastpath_enabled(False)
reference_output = model(x)
finally:
torch.backends.mha.set_fastpath_enabled(previous)
print((fast_output - reference_output).abs().max().item())활성화된 백엔드 플래그만으로는 퓨즈된 경로가 실행된다는 보장이 없으며, 그 사용 여부는 모델, 입력 및 런타임 조건에도 따라 달라집니다. 해당 모듈의 forward 구현을 검사하여 직접적인 가중치 접근이나 퓨즈된 연산자 호출이 있는지 확인하세요. 포워드 훅을 사용하여 디버깅할 때는 주의가 필요합니다. 훅을 등록하는 것 자체가 최적화를 비활성화하고 조사 중인 동작을 변경할 수 있기 때문입니다.
Eager 모드에서 네이티브 인코더의 경우, torch.backends.mha.set_fastpath_enabled(False)는 어댑터가 병합되지 않도록 유지하는 우회 방법입니다. 이 설정은 프로세스 전체에 적용되며 다른 모델 및 성능에 영향을 줄 수 있으므로 동시 요청에 의해 독립적으로 전환되어서는 안 됩니다. 다른 최적화된 경로의 경우, 영향을 받는 최적화를 비활성화하거나 어댑트된 모듈을 호출하는 구현을 사용하십시오. PEFT 방법과 양자화 설정이 허용하는 경우, merge_and_unload()를 사용하여 어댑터를 병합하고 반환된 모델을 추론에 사용할 수도 있습니다. 그러면 어댑터 변경 사항이 기본 가중치에 포함됩니다. 병합은 어댑터 래퍼를 제거하므로, 어댑터를 전환하거나 학습을 재개해야 하는 경우 원래 체크포인트를 유지하십시오.
무작위로 초기화된 레이어
일부 작업에서는 무작위로 초기화된 레이어를 고려하기 위해 설정에서 modules_to_save를 올바르게 구성하는 것이 중요합니다.
예를 들어, LoRA를 사용하여 시퀀스 분류를 위해 언어 모델을 파인튜닝하는 경우 이 작업이 필요합니다. 🤗 Transformers는 모델 위에 무작위로 초기화된 분류 헤드를 추가하기 때문입니다. 이 레이어를 modules_to_save에 추가하지 않으면 분류 헤드가 저장되지 않습니다. 다음에 모델을 로드하면 다른 무작위로 초기화된 분류 헤드가 생성되어 완전히 다른 결과가 나옵니다.
task_type 인수를 설정에 제공하면 PEFT는 modules_to_save를 올바르게 추측하려고 합니다. 이는 표준 네이밍 규칙을 따르는 transformers 모델에서 작동해야 합니다. 모든 모델이 네이밍 규칙을 따르는 것을 보장할 수 없으므로 항상 두 번 확인하는 것이 좋습니다.
transformers 모델에서 무작위로 초기화된 레이어가 있는 경우, 다음과 유사한 경고가 표시됩니다:
Some weights of <MODEL> were not initialized from the model checkpoint at <ID> and are newly initialized: [<LAYER_NAMES>].
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.설명된 문제를 피하려면 해당 레이어를 설정의 modules_to_save에 추가해야 합니다.
healthcheck()는 이 실수의 가장 흔한 형태에 대해 TASK_HEAD_NOT_SAVED 경고를 보고합니다. 이는 베이스 모델을 로드할 때 새로 초기화되었지만 modules_to_save에 포함되지 않은 시퀀스 분류, 토큰 분류 또는 질의응답 헤드입니다. 예를 들어 task_type가 설정되지 않은 경우입니다. 베이스 모델이 config에 아키텍처를 나열하지 않으면 이 체크는 건너뜁니다.
예를 들어, DeBERTa 아키텍처를 사용하는 시퀀스 분류 모델을 로드할 때, 다음 가중치가 새로 초기화되었다는 경고가 표시됩니다:
['classifier.bias', 'classifier.weight', 'pooler.dense.bias', 'pooler.dense.weight']. 이를 통해classifier와pooler레이어를modules_to_save=["classifier", "pooler"]에 추가해야 함을 알 수 있습니다.
어휘 확장
많은 언어 파인튜닝 작업에서는 새로운 토큰이 도입되므로 모델 어휘를 확장해야 합니다. 이를 위해 새로운 토큰을 고려하여 임베딩 레이어를 확장해야 하며, 파인튜닝 방법에 따라 어댑터를 저장할 때 어댑터 가중치 외에도 임베딩 레이어를 저장해야 할 수 있습니다. 이를 달성하는 방법은 파라미터 효율성에 따라 다음과 같이 정렬됩니다:
- trainable tokens, 지정된 토큰만 학습하고, 선택적으로 업데이트된 값만 저장
- 임베딩 행렬에 어댑터를 학습하고, 선택적으로 업데이트된 값만 저장
- 임베딩 레이어의 완전한 파인튜닝
학습 가능한 토큰 사용
학습 가능한 토큰부터 시작해 보겠습니다. 이 경우 LoRA 통합입니다. 새로운 임베딩만 학습하고 나머지는 학습하지 않는 데 관심이 있다면 독립 문서를 참고하세요.
임베딩 레이어의 선택적 토큰 학습을 활성화하려면 trainable_token_indices 파라미터를 통해 새로 추가한 토큰의 토큰 ID를 제공해야 합니다. 임베딩 레이어가 하나 이상인 경우 대상 레이어를 지정할 수도 있습니다. Mistral 모델의 경우 다음과 같이 사용할 수 있습니다:
new_tokens = ['<think>', '</think>']
tokenizer.add_tokens(new_tokens)
base_model.resize_token_embeddings(len(tokenizer))
lora_config = LoraConfig(
...,
trainable_token_indices={'embed_tokens': tokenizer.convert_tokens_to_ids(new_tokens)},
)모델이 tied weights(예: lm_head)를 사용하는 경우, 학습 가능한 토큰은 해당 가중치를 해결하고 함께 업데이트하려고 하므로, 그런 경우에는 modules_to_save=["lm_head"]를 추가할 필요가 없습니다. 이는 모델이 Transformers의 가중치 연결(tying weights) 관례를 사용하는 경우에만 작동합니다.
model.save_pretrained를 사용하여 모델을 저장할 때, 임베딩 행렬이 리사이즈되었기 때문에 차이 부분만 저장하는 대신 전체 임베딩 행렬을 저장할 수 있습니다. 저장 공간을 절약하려면 save_pretrained를 호출할 때 save_embedding_layers=False를 설정하여 이 동작을 비활성화할 수 있습니다. 다른 방식으로 임베딩 행렬을 수정하지 않는 한 이렇게 하는 것이 안전합니다. 이러한 변경 사항은 학습 가능한 토큰에 의해 추적되지 않기 때문입니다.
LoRA와 같은 어댑터 사용
target_modules에 embedding 레이어를 추가하여 embedding 레이어를 준비합니다. 예를 들어, Mistral 설정은 다음과 같이 구성할 수 있습니다:
config = LoraConfig(..., target_modules=["embed_tokens", "lm_head", "q_proj", "v_proj"])target_modules에 추가된 후, PEFT는 모델에 get_input_embeddings와 get_output_embeddings가 있는 경우 어댑터를 저장할 때 임베딩 레이어를 자동으로 저장합니다. 이는 일반적으로 Transformers 모델의 경우 해당됩니다.
모델의 임베딩 레이어가 Transformer의 네이밍 스키마를 따르지 않더라도 get_input_embeddings를 구현하고 있다면, 어댑터를 저장할 때 save_embedding_layers=True를 수동으로 전달하여 저장할 수 있습니다:
model = get_peft_model(...)
# train the model
model.save_pretrained("my_adapter", save_embedding_layers=True)추론을 위해 먼저 베이스 모델을 로드한 후, 모델을 학습하기 전에 했던 것과 동일한 방식으로 크기를 조정합니다. 베이스 모델의 크기를 조정하면 PEFT 체크포인트를 로드할 수 있습니다.
완전한 예제는 이 노트북을 확인해 보세요.
전체 파인튜닝
Full fine-tuning은 VRAM이나 저장 공간 측면에서 더 비용이 많이 들지만, 다른 방법이 모두 실패할 경우 이 방법으로 전환하여 작동하는지 확인할 수 있습니다. modules_to_save에 임베딩 레이어 이름을 추가하여 이를 수행합니다. 연결된 레이어, 예: lm_head도 추가해야 한다는 점에 유의하세요. LoRA를 사용하는 Mistral 모델의 예시:
config = LoraConfig(..., modules_to_save=["embed_tokens", "lm_head"], target_modules=["q_proj", "v_proj"])모델 체크포인트에서 가중치가 초기화되지 않았다는 경고가 표시되는 경우
작업(예: 분류)으로 학습된 PEFT 모델을 로드할 때 다음과 같은 경고가 표시될 수 있습니다:
LlamaForSequenceClassification의 일부 가중치가 meta-llama/Llama-3.2-1B 모델 체크포인트에서 초기화되지 않고 새로 초기화되었습니다: [‘score.weight’]. 예측 및 추론에 이 모델을 사용하려면 다운스트림 작업으로 이 모델을 학습해야 합니다.
이 경고가 무섭게 보일 수 있지만, 대부분 걱정할 필요가 없습니다. 이 경고는 Transformers에서 발생하며 PEFT에 특화된 경고가 아닙니다. 무작위로 초기화된 분류 헤드(score)가 기본 모델에 연결되어 있으며, 이 헤드가 합리적인 예측을 생성하도록 학습되어야 한다는 사실을 알려 줍니다.
모델을 학습하기 전에 이 경고가 표시되면, PEFT config에 task_type 인수를 올바르게 전달한 경우 PEFT가 분류 헤드를 학습 가능하도록 자동으로 처리합니다.
from peft import LoraConfig, TaskType
lora_config = LoraConfig(..., task_type=TaskType.SEQ_CLS)분류 헤드가 Transformers의 일반적인 네이밍 컨벤션을 따르지 않는 경우(드물지만)에는 modules_to_save에서 해당 헤드의 이름을 명시적으로 PEFT에 전달해야 합니다.
lora_config = LoraConfig(..., modules_to_save=["name-of-classification-head"])classification head의 이름을 확인하려면 모델을 출력하면 마지막 모듈로 표시됩니다.
추론 코드, 즉 모델 학습 이후 PEFT 모델을 로드할 때 이 경고가 표시되면, 항상 먼저 Transformers 모델을 로드해야 합니다. Transformers는 나중에 PEFT 가중치가 로드될 것을 알지 못하므로 여전히 경고를 표시합니다.
항상 그렇듯, 모델이 추론을 올바르게 수행하는지 확인하기 위해 일부 검증을 실행하는 것이 최선의 관행입니다.
학습 헬스체크 실행
학습 전에 print_healthcheck()를 사용하여 PEFT 모델의 상태를 나타내는 간결하고 사람이 읽기 쉬운 요약을 가져오세요. 이는 모델 및 레이어 상태 API(다음 섹션 참조)에서 파생되며, 일관되지 않은 어댑터, 병합된 어댑터, 의심스러운 학습 가능 매개변수 수와 같은 의심스러운 상태를 표시합니다.
peft_model.print_healthcheck()
보고서 말미에 “Findings” 섹션이 포함되어 있는지 특별히 주의하세요. 이상 사항이 발견된 경우에만 이 섹션이 포함됩니다.
JSON 직렬화가 가능한 딕셔너리 출력을 선호하는 경우, 대신 healthcheck()를 사용하세요:
healthcheck = peft_model.healthcheck()
print(healthcheck.get("findings", "all good")이 체크는 모델과 어댑터만 검사합니다. 학습 루프, 옵티마이저, 데이터셋은 검증하지 않습니다. 프롬프트 학습 및 어댑션 프롬프트의 경우, 보고서는 모델 정보와 매개변수 수를 표시하지만, 이러한 방법이 지원하지 않으므로 레이어 상태는 생략됩니다.
레이어 및 모델 상태 확인
PEFT 모델은 특히 여러 어댑터를 다룰 때 잘못된 상태로 전환될 수 있습니다. 어떤 어댑터가 존재하는지, 어떤 어댑터가 활성화되어 있는지, 어떤 어댑터가 병합되었는지 등에 대해 혼란이 생길 수 있습니다. 이 문제를 조사하기 위해 get_layer_status() 및 get_model_status() 메서드를 호출하세요.
get_layer_status() 메서드는 각 대상 레이어의 활성, 병합, 사용 가능한 어댑터에 대한 상세한 개요를 제공합니다.
>>> from transformers import AutoModel
>>> from peft import get_peft_model, LoraConfig
>>> model_id = "google/flan-t5-small"
>>> model = AutoModel.from_pretrained(model_id)
>>> model = get_peft_model(model, LoraConfig())
>>> model.get_layer_status()
[TunerLayerStatus(name='model.encoder.block.0.layer.0.SelfAttention.q',
module_type='lora.Linear',
enabled=True,
active_adapters=['default'],
merged_adapters=[],
requires_grad={'default': True},
available_adapters=['default']),
TunerLayerStatus(name='model.encoder.block.0.layer.0.SelfAttention.v',
module_type='lora.Linear',
enabled=True,
active_adapters=['default'],
merged_adapters=[],
requires_grad={'default': True},
available_adapters=['default']),
...]
>>> model.get_model_status()
TunerModelStatus(
base_model_type='T5Model',
adapter_model_type='LoraModel',
peft_types={'default': 'LORA'},
trainable_params=344064,
total_params=60855680,
num_adapter_layers=48,
enabled=True,
active_adapters=['default'],
merged_adapters=[],
requires_grad={'default': True},
available_adapters=['default'],
)모델 상태 출력에서 "irregular"라고 표시된 항목을 확인해야 합니다. 이는 PEFT가 모델에서 일관되지 않은 상태를 감지했음을 의미합니다. 예를 들어, merged_adapters="irregular"인 경우, 적어도 하나의 어댑터가 일부 대상 모듈에는 병합되었지만 다른 모듈에는 병합되지 않았음을 의미합니다. 이로 인해 추론 결과가 대부분 정확하지 않을 것입니다.
이 문제를 해결하는 가장 좋은 방법은 모델 전체와 어댑터 체크포인트를 다시 로드하는 것입니다. 일부 모듈에만 어댑터를 수동으로 병합하는 등 모델에 대해 잘못된 작업을 수행하지 않도록 주의하세요.
DataFrame으로 레이어 상태를 변환하여 시각적 검사를 쉽게 수행합니다.
from dataclasses import asdict
import pandas as pd
df = pd.DataFrame(asdict(layer) for layer in model.get_layer_status())PEFT 모델을 사용하지 않지만 내부적으로 PEFT 레이어를 사용하는 모델의 경우에도 이 정보를 가져올 수 있지만, base_model_type 또는 peft_types와 같은 일부 정보는 해당 경우 결정할 수 없습니다. 예를 들어, diffusers 모델에 대해 다음과 같이 호출할 수 있습니다:
>>> import torch
>>> from diffusers import StableDiffusionPipeline
>>> from peft import get_model_status, get_layer_status
>>> path = "runwayml/stable-diffusion-v1-5"
>>> lora_id = "takuma104/lora-test-text-encoder-lora-target"
>>> pipe = StableDiffusionPipeline.from_pretrained(path, dtype=torch.float16)
>>> pipe.load_lora_weights(lora_id, adapter_name="adapter-1")
>>> pipe.load_lora_weights(lora_id, adapter_name="adapter-2")
>>> pipe.set_lora_device(["adapter-2"], "cuda")
>>> get_layer_status(pipe.text_encoder)
[TunerLayerStatus(name='text_model.encoder.layers.0.self_attn.k_proj',
module_type='lora.Linear',
enabled=True,
active_adapters=['adapter-2'],
merged_adapters=[],
requires_grad={'adapter-1': False, 'adapter-2': True},
available_adapters=['adapter-1', 'adapter-2'],
devices={'adapter-1': ['cpu'], 'adapter-2': ['cuda']}),
TunerLayerStatus(name='text_model.encoder.layers.0.self_attn.v_proj',
module_type='lora.Linear',
enabled=True,
active_adapters=['adapter-2'],
merged_adapters=[],
requires_grad={'adapter-1': False, 'adapter-2': True},
devices={'adapter-1': ['cpu'], 'adapter-2': ['cuda']}),
...]
>>> get_model_status(pipe.unet)
TunerModelStatus(
base_model_type='other',
adapter_model_type='None',
peft_types={},
trainable_params=797184,
total_params=861115332,
num_adapter_layers=128,
enabled=True,
active_adapters=['adapter-2'],
merged_adapters=[],
requires_grad={'adapter-1': False, 'adapter-2': True},
available_adapters=['adapter-1', 'adapter-2'],
devices={'adapter-1': ['cpu'], 'adapter-2': ['cuda']},
)속도
어댑터 가중치 로딩이 느립니다
LoRA 가중치와 같은 어댑터를 로드하는 것은 일반적으로 베이스 모델을 로드하는 것보다 빠릅니다. 그러나 어댑터 가중치가 상당히 크거나, 사용자가 대량의 어댑터를 로드해야 하는 경우가 있을 수 있으며, 이 경우 로드 시간이 누적될 수 있습니다. 그 이유는 어댑터 가중치가 먼저 초기화된 후 로드된 가중치로 덮어쓰이기 때문에 비효율적이기 때문입니다. 로드 시간을 단축하려면 low_cpu_mem_usage=True 인수를 from_pretrained() 및 load_adapter()에 전달할 수 있습니다.
이 옵션이 다양한 사용 사례에서 잘 작동한다면, 향후 어댑터 로딩의 기본값이 될 수 있습니다.
재현성
배치 정규화를 사용하는 모델
기본 모델에 batch norm(예: torch.nn.BatchNorm1d 또는 torch.nn.BatchNorm2d)이 사용되는 학습된 PEFT 모델을 로드할 때, 동일한 출력을 재현하지 못할 수 있습니다. 이는 batch norm 레이어가 학습 중에 running stats를 추적하지만, 이러한 stats가 PEFT 체크포인트의 일부가 아니기 때문입니다. 따라서 PEFT 모델을 로드할 때 기본 모델의 running stats(즉, PEFT로 학습하기 전의 값)가 사용됩니다.
사용 사례에 따라 이것이 큰 문제가 아닐 수 있습니다. 그러나 출력이 100% 재현 가능해야 하는 경우, modules_to_save에 batch norm 레이어를 추가하여 이를 달성할 수 있습니다. 아래는 resnet과 LoRA를 사용하여 이를 구현한 예시입니다. modules_to_save=["classifier", "normalization"]로 설정하는 것에 주목하세요. 작업이 이미지 분류이므로 "classifier" 인수가 필요하며, batch norm 레이어가 PEFT 체크포인트에 저장되도록 "normalization" 인수를 추가합니다.
from transformers import AutoModelForImageClassification
from peft import LoraConfig, get_peft_model
model_id = "microsoft/resnet-18"
base_model = AutoModelForImageClassification.from_pretrained(self.model_id)
config = LoraConfig(
target_modules=["convolution"],
modules_to_save=["classifier", "normalization"],
),사용하는 모델의 유형에 따라 batch norm 레이어의 이름이 "normalization"과 다를 수 있으므로, 모델 아키텍처와 이름이 일치하는지 확인하세요.
버전 불일치
예기치 않은 키워드 인수로 인해 config를 로드하는 동안 오류가 발생했습니다
아래와 같은 오류를 만나면, 로드하려는 어댑터가 시스템에 설치된 PEFT 버전보다 더 최신 버전의 PEFT로 학습되었음을 의미합니다.
TypeError: LoraConfig.__init__() got an unexpected keyword argument <argument-name>이 문제를 해결하는 가장 좋은 방법은 최신 PEFT 버전을 설치하는 것입니다:
python -m pip install -U PEFT
어댑터가 PEFT의 소스 설치(미발행 버전의 PEFT)에서 학습된 경우, PEFT를 소스에서 설치해야 합니다.
python -m pip install -U git+https://github.com/huggingface/peft.git
PEFT를 업그레이드할 수 없는 경우, 시도해 볼 수 있는 우회 방법이 있습니다.
오류 메시지에 알려지지 않은 키워드 인수의 이름이 foobar라고 한다고 가정해 보겠습니다. 이 PEFT 어댑터의 adapter_config.json 파일에서 foobar 항목을 찾아 파일에서 삭제하세요. 그런 다음 파일을 저장하고 모델을 다시 로드해 보세요.
이 솔루션은 대부분의 경우 작동합니다. foobar의 기본값인 한 무시할 수 있습니다. 그러나 다른 값으로 설정된 경우 잘못된 결과를 얻게 됩니다. PEFT 업그레이드가 권장되는 해결책입니다.
Adapter 처리
여러 어댑터를 동시에 사용
PEFT를 사용하면 동일한 모델에 여러 개의 어댑터를 생성할 수 있습니다. 이는 다양한 상황에서 유용합니다. 예를 들어 추론 시, 각 파인튜닝된 모델마다 베이스 모델을 한 번씩 로드하여 메모리 비용이 증가하는 대신, 동일한 베이스 모델에서 두 개의 파인튜닝된 모델을 서빙하고 싶을 수 있습니다. 또한, 여러 개의 어댑터를 동시에 활성화할 수 있습니다. 이렇게 하면 모델이 모든 어댑터에서 학습된 내용을 동시에 활용할 수 있습니다. 예를 들어, 확산 모델(diffusion model)을 사용하는 경우, 하나의 LoRA 어댑터로 스타일을 변경하고 다른 어댑터로 주제를 변경하고 싶을 수 있습니다.
PEFT 방법(LoRA, LoHa, IA³ 등)은 프롬프트 학습 방법(p-tuning, prefix tuning 등)을 제외하고 일반적으로 여러 어댑터를 동시에 활성화할 수 있습니다. 다음 예제는 이를 수행하는 방법을 보여줍니다:
from transformers import AutoModelForCausalLM
from peft import PeftModel
model_id = ...
base_model = AutoModelForCausalLM.from_pretrained(model_id)
model = PeftModel.from_pretrained(base_model, lora_path_0) # default adapter_name is 'default'
model.load_adapter(lora_path_1, adapter_name="other")
# the 'other' adapter was loaded but it's not active yet, so to activate both adapters:
model.base_model.set_adapter(["default", "other"])위의 예시에서
model.base_model.set_adapter(["default", "other"])를 호출해야 하는 것을 볼 수 있습니다. 왜model.set_adapter(["default", "other"])를 호출할 수 없을까요? 앞서 설명했듯이 일부 PEFT 메서드는 한 번에 두 개 이상의 어댑터를 활성화하는 것을 지원하지 않기 때문에, 안타깝게도 이는 불가능합니다.
두 개의 어댑터를 동시에 학습하는 것도 가능하지만, 두 어댑터의 가중치가 모두 옵티마이저에 의해 인식되도록 주의해야 합니다. 그렇지 않으면 하나의 어댑터만 업데이트를 받게 됩니다.
from transformers import AutoModelForCausalLM
from peft import LoraConfig, get_peft_model
model_id = ...
base_model = AutoModelForCausalLM.from_pretrained(model_id)
lora_config_0 = LoraConfig(...)
lora_config_1 = LoraConfig(...)
model = get_peft_model(base_model, lora_config_0)
model.add_adapter(adapter_name="other", peft_config=lora_config_1)이제 다음을 호출하면
from transformers import Trainer
trainer = Trainer(model=model, ...)
trainer.train()또는
optimizer = torch.optim.AdamW([param for param in model.parameters() if param.requires_grad], ...)그렇다면 두 번째 LoRA 어댑터("other")는 학습되지 않습니다. 이는 해당 어댑터가 현재 비활성 상태이므로, 그 파라미터의 requires_grad 속성이 False로 설정되어 있고 옵티마이저가 이를 무시하기 때문입니다. 따라서 학습할 모든 어댑터를 옵티마이저를 초기화하기 전에 활성화해야 합니다:
# activate all adapters
model.base_model.set_adapter(["default", "other"])
trainer = Trainer(model=model, ...)
trainer.train()이 섹션은 동일한 모델에 동일한 유형의 여러 어댑터를 사용하는 방법, 예를 들어 여러 LoRA 어댑터를 동시에 사용하는 방법에 대해 다룹니다. 이는 동일한 모델에 서로 다른 유형의 어댑터를 사용하는 경우, 예를 들어 LoRA 어댑터 하나와 LoHa 어댑터 하나를 함께 사용하는 경우에는 적용되지 않습니다. 이 경우
PeftMixedModel을 확인해 주세요.
활성 어댑터 중 일부만 병합
어댑터 가중치가 베이스 가중치에 병합되면, 해당 레이어는 포워드 패스 동안 더 이상 어댑터를 적용하지 않고 병합된 베이스 가중치만 사용합니다. 따라서 여러 어댑터가 활성화되어 있지만 일부만 병합된 경우, 여전히 활성화되어 있지만 병합되지 않은 어댑터는 조용히 적용되지 않습니다:
model = get_peft_model(base_model, lora_config_0, adapter_name="default")
model.add_adapter("other", lora_config_1)
model.base_model.set_adapter(["default", "other"])
output_both = model(**inputs)
model.merge_adapter(adapter_names=["default"])
output_merged = model(**inputs) # this is *not* the same as output_both여기서 output_merged는 "other"가 여전히 활성으로 나열되어 있음에도 불구하고 "default" 어댑터 단독의 출력입니다:
>>> model.get_layer_status()[0].active_adapters
['default', 'other']
>>> model.get_layer_status()[0].merged_adapters
['default']활성화되지 않은 어댑터가 병합되는 경우에도 동일한 규칙이 적용됩니다. 병합 이후에는 모델이 병합된 어댑터의 출력을 반환하며, 활성화된 어댑터는 무시됩니다. 두 경우 모두 오류나 경고가 발생하지 않습니다. 어댑터 가중치 자체에는 영향이 없으므로 unmerge_adapter()를 호출하면 결합된 출력이 복원됩니다.
이를 방지하려면 모든 활성 어댑터를 병합하거나, 즉 adapter_names 없이 model.merge_adapter()를 호출하거나, 활성 상태인 어댑터를 변경하기 전에 병합을 해제하세요.
이 동작은 병합을 지원하는 모든 PEFT 방법(LoRA, LoHa, LoKr, IA³, OFT 등)에서 일관되게 나타납니다. 이는 모든 방법이 forward pass에서 동일한 로직을 공유하기 때문입니다.
Update on GitHub이 동작은 혼란스럽고 PEFT v1.0 릴리스에서 변경될 예정입니다.