PEFT documentation
Fully Sharded Data Parallel
Fully Sharded Data Parallel
Fully sharded data parallel(FSDP)은 최대 1T 파라미터 규모의 대규모 사전 학습 모델의 분산 학습을 위해 개발되었습니다. FSDP는 모델 파라미터, 그래디언트, 옵티마이저 상태를 데이터 병렬 프로세스에 걸쳐 샤딩(sharding)하여 이를 달성하며, 샤딩된 모델 파라미터를 CPU로 오프로드(offload)할 수도 있습니다. FSDP가 제공하는 메모리 효율성 덕분에 더 큰 배치 또는 모델 크기로 학습을 확장할 수 있습니다.
PEFT는 FSDP1과 PyTorch FSDP2를 지원합니다. Transformers의 Trainer를 통해 FSDP를 구성하거나 PyTorch 학습 루프에서 직접 사용할 수 있습니다.
Transformers와 FSDP2
PyTorch 2.6 이상과 최신 버전의 Transformers, Accelerate, TRL, PEFT를 사용하세요. SFT 예제는 SFTTrainer를 사용합니다. 일반적인 FSDP2 구성은 다음과 같습니다:
{
"fsdp": true,
"fsdp_config": {
"version": 2,
"reshard_after_forward": true,
"auto_wrap_policy": "TRANSFORMER_BASED_WRAP",
"cpu_ram_efficient_loading": true,
"state_dict_type": "SHARDED_STATE_DICT",
"activation_checkpointing": false
}
}TRANSFORMER_BASED_WRAP은 모델의 transformer 레이어 정의를 사용합니다. reshard_after_forward는 각 forward pass 이후에 수집된 파라미터를 해제합니다. FSDP2는 개별 파라미터를 샤딩하므로 FSDP1의 use_orig_params 설정을 사용하지 않습니다. 추가 구성 옵션은 Transformers FSDP 가이드를 참고하세요.
예제의 fsdp2_config.json에서 모델, 데이터셋, 학습 옵션을 편집합니다. examples/sft에서 GPU당 하나의 프로세스를 시작합니다:
torchrun --standalone --nproc_per_node=2 train.py configs/fsdp2_config.json
BF16을 지원하지 않는 GPU의 경우, JSON 파일에서 "bf16": false와 "fp16": true를 설정하세요.
v0.22 이전의 PEFT 버전을 사용하는 경우, 빈 어댑터 내보내기를 방지하기 위해 activation_checkpointing을 false로 설정해 두세요. PEFT v0.22에는 어댑터 내보내기 수정 사항이 포함되어 있습니다.
저장 및 재개
트레이닝을 재개하려면 동일한 FSDP 구성을 유지하고 JSON 파일에 "resume_from_checkpoint": "path/to/checkpoint-N"을 설정하세요. 트레이닝 체크포인트에는 샤드된 모델 및 옵티마이저 상태가 포함됩니다.
학습이 끝난 후, 예제는 어댑터를 내보내기 전에 전체 상태 사전(state dictionary)을 수집합니다:
if trainer.is_fsdp_enabled:
trainer.accelerator.state.fsdp_plugin.set_state_dict_type("FULL_STATE_DICT")
trainer.save_model()모든 rank가 gather에 참여해야 하며, 어댑터 파일은 메인 프로세스만 작성합니다. 전체 state dictionary를 수집하면 메모리 사용량이 일시적으로 증가합니다.
추론을 위해 내보낸 어댑터를 로드합니다:
import torch
from peft import AutoPeftModelForCausalLM
model = AutoPeftModelForCausalLM.from_pretrained("qwen-sft-lora-fsdp2", dtype=torch.float32)SFT 실행으로 인해 기본 모델의 임베딩이 확장된 토큰이 추가되었다면, 어댑터를 로드하기 전에 학습 시점의 임베딩 크기와 일치시켜야 합니다. SFT 예시에서는 확장된 임베딩을 8의 배수로 패딩합니다:
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftConfig, PeftModel
adapter_path = "qwen-sft-lora-fsdp2"
config = PeftConfig.from_pretrained(adapter_path)
tokenizer = AutoTokenizer.from_pretrained(adapter_path)
base_model = AutoModelForCausalLM.from_pretrained(config.base_model_name_or_path, dtype=torch.float32)
# Match the SFT example: grow the embeddings if needed, but never shrink them.
if len(tokenizer) > base_model.get_input_embeddings().num_embeddings:
base_model.resize_token_embeddings(len(tokenizer), pad_to_multiple_of=8)
model = PeftModel.from_pretrained(base_model, adapter_path)Accelerate를 사용한 FSDP1
이 섹션에서는 SFT 학습 스크립트를 사용하여 단일 머신에서 8xH100 80GB GPU로 Llama-70B를 LoRA와 FSDP1로 파인튜닝하는 방법을 다룹니다. Accelerate 설정을 변경하여 여러 머신으로 확장할 수 있습니다.
구성
🤗 Accelerate를 사용하여 FSDP 구성 파일을 생성하는 다음 명령을 실행하여 시작합니다. --config_file 플래그를 사용하면 구성 파일을 특정 위치에 저장할 수 있으며, 그렇지 않으면 🤗 Accelerate 캐시에 default_config.yaml 파일로 저장됩니다.
설정 파일은 학습 스크립트를 실행할 때 기본 옵션을 설정하는 데 사용됩니다.
accelerate config --config_file fsdp_config.yaml
설정에 대한 몇 가지 질문이 표시됩니다. 아래 이미지에 표시된 대로 설문지를 응답하여 다음 인수를 구성합니다.

이 작업이 완료되면 해당 config는 다음과 같이 보이며 fsdp_config.yaml 파일은 config 폴더에서 찾을 수 있습니다:
compute_environment: LOCAL_MACHINE
debug: false
distributed_type: FSDP
downcast_bf16: 'no'
fsdp_config:
fsdp_version: 1
fsdp_auto_wrap_policy: TRANSFORMER_BASED_WRAP
fsdp_backward_prefetch: BACKWARD_PRE
fsdp_cpu_ram_efficient_loading: true
fsdp_forward_prefetch: false
fsdp_offload_params: false
fsdp_sharding_strategy: FULL_SHARD
fsdp_state_dict_type: SHARDED_STATE_DICT
fsdp_sync_module_states: true
fsdp_use_orig_params: false
machine_rank: 0
main_training_function: main
mixed_precision: bf16
num_machines: 1
num_processes: 8
rdzv_backend: static
same_network: true
tpu_env: []
tpu_use_cluster: false
tpu_use_sudo: false
use_cpu: false시작 명령
실행 명령어는 run_peft_fsdp.sh에서 사용할 수 있으며, 아래에도 표시됩니다:
accelerate launch --config_file "configs/fsdp_config.yaml" train.py \
--seed 100 \
--model_name_or_path "meta-llama/Llama-2-70b-hf" \
--dataset_name "smangrul/ultrachat-10k-chatml" \
--chat_template_format "chatml" \
--add_special_tokens False \
--append_concat_token False \
--splits "train,test" \
--max_length 2048 \
--num_train_epochs 1 \
--logging_steps 5 \
--log_level "info" \
--logging_strategy "steps" \
--eval_strategy "epoch" \
--save_strategy "epoch" \
--push_to_hub \
--hub_private_repo True \
--hub_strategy "every_save" \
--bf16 True \
--packing True \
--learning_rate 1e-4 \
--lr_scheduler_type "cosine" \
--weight_decay 1e-4 \
--warmup_steps 0 \
--max_grad_norm 1.0 \
--output_dir "llama-sft-lora-fsdp" \
--per_device_train_batch_size 8 \
--per_device_eval_batch_size 8 \
--gradient_accumulation_steps 4 \
--gradient_checkpointing True \
--use_reentrant False \
--dataset_text_field "content" \
--use_flash_attn True \
--use_peft_lora True \
--lora_r 8 \
--lora_alpha 16 \
--lora_dropout 0.1 \
--lora_target_modules "all-linear" \
--use_4bit_quantization Falserank=8, alpha=16을 사용하고 모든 linear layer를 대상으로 하는 LoRA를 적용하고 있음을 주목하세요. FSDP 설정 파일을 전달하고 ultrachat dataset의 하위 집합으로 70B Llama 모델을 fine-tuning하고 있습니다.
중요한 부분
스크립트를 조금 더 자세히 살펴보겠습니다. 어떻게 동작하는지 이해할 수 있도록 내부 구조를 확인해 보겠습니다.
가장 먼저 알아둘 점은, FSDP 설정이 전달되었으므로 스크립트가 분산 학습에 FSDP를 사용한다는 것입니다. SFTTrainer 클래스는 전달된 peft 설정을 사용하여 PEFT 모델을 생성하는 모든 핵심 작업을 처리합니다. 이후 trainer.train()을 호출하면, Trainer는 내부적으로 🤗 Accelerate를 사용하여 FSDP 설정에 따라 FSDP로 래핑된 모델을 생성하고, 이 모델을 학습하기 위해 모델, 옵티마이저, 트레이너를 준비합니다. 주요 코드 스니펫은 다음과 같습니다:
# trainer
trainer = SFTTrainer(
model=model,
processing_class=tokenizer,
args=training_args,
train_dataset=train_dataset,
eval_dataset=eval_dataset,
peft_config=peft_config,
)
trainer.accelerator.print(f"{trainer.model}")
if hasattr(trainer.model, "print_healthcheck"):
trainer.model.print_healthcheck()
# train
checkpoint = None
if training_args.resume_from_checkpoint is not None:
checkpoint = training_args.resume_from_checkpoint
trainer.train(resume_from_checkpoint=checkpoint)
# saving final model
if trainer.is_fsdp_enabled:
trainer.accelerator.state.fsdp_plugin.set_state_dict_type("FULL_STATE_DICT")
trainer.save_model()FSDP1에서 use_orig_params=False는 학습 가능 파라미터와 고정된 파라미터를 각각 래핑하여 메모리 사용량을 줄입니다. 현재 Transformers Trainer는 이 경우에 PEFT의 fsdp_auto_wrap_policy를 설치하므로, 예제에서는 이를 수동으로 설정할 필요가 없습니다. 사용자 정의 Accelerate FSDP1 학습 루프에서는 모델을 준비하기 전에 해당 정책을 설정해야 합니다. 이 평탄화 파라미터 래핑 요구 사항은 FSDP2에는 적용되지 않습니다.
메모리 사용량
위 예시에서 아래 스크린샷과 같이 GPU당 소비되는 메모리는 72-80 GB(90-98%)입니다. 끝부분에서 GPU 메모리가 약간 증가하는 이유는 SHARDED_STATE_DICT 대신 FULL_STATE_DICT 상태 딕트 유형으로 모델을 저장하기 때문이며, 이를 통해 추론 시 from_pretrained 메서드로 정상적으로 로드할 수 있는 어댑터 가중치를 모델이 갖게 됩니다:

QLoRA를 사용한 FSDP1
이 섹션에서는 2X24GB GPU에서 70B llama 모델을 파인튜닝하기 위해 QLoRA와 FSDP를 사용하는 방법을 살펴봅니다. Answer.AI는 bitsandbytes 및 Hugging Face 🤗와 협력하여 FSDP+QLoRA 사용을 가능하게 하는 코드를 오픈소스로 공개했으며, 통찰력 있는 블로그 포스트 You can now train a 70b language model at home에서 전체 과정을 설명했습니다. 이 기능은 이제 Hugging Face 생태계에 통합되었습니다.
bitsandbytes>=0.43.3와 함께 현재 PEFT, Transformers, TRL 및 Accelerate를 사용하세요. 이 FSDP1 구성의 경우 fsdp_cpu_ram_efficient_loading=true, fsdp_use_orig_params=false, fsdp_offload_params=true(CPU 오프로딩)를 설정하세요. 구성은 fsdp_config_qlora.yaml에서 확인할 수 있습니다:
compute_environment: LOCAL_MACHINE
debug: false
distributed_type: FSDP
downcast_bf16: 'no'
fsdp_config:
fsdp_version: 1
fsdp_auto_wrap_policy: TRANSFORMER_BASED_WRAP
fsdp_backward_prefetch: BACKWARD_PRE
fsdp_cpu_ram_efficient_loading: true
fsdp_forward_prefetch: false
fsdp_offload_params: true
fsdp_sharding_strategy: FULL_SHARD
fsdp_state_dict_type: SHARDED_STATE_DICT
fsdp_sync_module_states: true
fsdp_use_orig_params: false
machine_rank: 0
main_training_function: main
mixed_precision: 'no'
num_machines: 1
num_processes: 2
rdzv_backend: static
same_network: true
tpu_env: []
tpu_use_cluster: false
tpu_use_sudo: false
use_cpu: false아래는 run_peft_qlora_fsdp.sh에서 사용할 수 있는 실행 명령입니다:
accelerate launch --config_file "configs/fsdp_config_qlora.yaml" train.py \
--seed 100 \
--model_name_or_path "meta-llama/Llama-2-70b-hf" \
--dataset_name "smangrul/ultrachat-10k-chatml" \
--chat_template_format "chatml" \
--add_special_tokens False \
--append_concat_token False \
--splits "train,test" \
--max_length 2048 \
--num_train_epochs 1 \
--logging_steps 5 \
--log_level "info" \
--logging_strategy "steps" \
--eval_strategy "epoch" \
--save_strategy "epoch" \
--push_to_hub \
--hub_private_repo True \
--hub_strategy "every_save" \
--bf16 True \
--packing True \
--learning_rate 1e-4 \
--lr_scheduler_type "cosine" \
--weight_decay 1e-4 \
--warmup_steps 0 \
--max_grad_norm 1.0 \
--output_dir "llama-sft-qlora-fsdp" \
--per_device_train_batch_size 2 \
--per_device_eval_batch_size 2 \
--gradient_accumulation_steps 2 \
--gradient_checkpointing True \
--use_reentrant True \
--dataset_text_field "content" \
--use_flash_attn True \
--use_peft_lora True \
--lora_r 8 \
--lora_alpha 16 \
--lora_dropout 0.1 \
--lora_target_modules "all-linear" \
--use_4bit_quantization True \
--use_nested_quant True \
--bnb_4bit_compute_dtype "bfloat16" \
--bnb_4bit_quant_storage_dtype "bfloat16"4-bit 파라미터를 패킹하는 데 사용되는 데이터 타입을 나타내는 새로운 인자 bnb_4bit_quant_storage_dtype가 전달되는 것을 확인하세요. 예를 들어, bfloat16으로 설정하면 양자화 후 16/4 = 4개의 4-bit 파라미터가 함께 패킹됩니다. bfloat16로 혼합 정밀도 훈련을 사용할 때, bnb_4bit_quant_storage_dtype는 순수한 bfloat16 파인튜닝을 위해 bfloat16로, 또는 자동 혼합 정밀도를 위해 float32로 설정할 수 있습니다(이 경우 GPU 메모리 사용량이 더 증가합니다). float16로 혼합 정밀도 훈련을 사용할 때, 안정적인 자동 혼합 정밀도 훈련을 위해 bnb_4bit_quant_storage_dtype은 float32로 설정해야 합니다.
학습 코드 측면에서 중요한 코드 변경 사항은 다음과 같습니다:
...
bnb_config = BitsAndBytesConfig(
load_in_4bit=args.use_4bit_quantization,
bnb_4bit_quant_type=args.bnb_4bit_quant_type,
bnb_4bit_compute_dtype=compute_dtype,
bnb_4bit_use_double_quant=args.use_nested_quant,
+ bnb_4bit_quant_storage=quant_storage_dtype,
)
...
model = AutoModelForCausalLM.from_pretrained(
args.model_name_or_path,
quantization_config=bnb_config,
trust_remote_code=True,
attn_implementation="flash_attention_2" if args.use_flash_attn else "eager",
+ dtype=quant_storage_dtype or torch.float32,
)AutoModelForCausalLM의 dtype이 bnb_4bit_quant_storage 데이터 타입과 동일하다는 점에 유의하세요. 이 정도면 충분합니다. 나머지는 Trainer와 TRL이 처리합니다.
메모리 사용량
위 예시에서 GPU당 소비되는 메모리는 19.6 GB이고, CPU RAM 사용량은 약 107 GB입니다. CPU 오프로딩을 비활성화하면 GPU 메모리 사용량은 35.6 GB/ GPU가 됩니다. 따라서 전체 파인튜닝에는 16X80GB GPU, FSDP+LoRA에는 8X80GB GPU, DDP+QLoRA에는 80GB GPU 몇 개가 필요했던 작업이 이제는 2X24GB GPU로 가능합니다. 이를 통해 대규모 모델의 파인튜닝이 더 쉽게 접근할 수 있게 되었습니다.
추가 리소스
FSDP와 PEFT를 사용하여 파인튜닝하는 방법에 대해서는 llama-recipes 저장소와 Getting started with Llama 가이드를 참고할 수 있습니다.
주의 사항
- FSDP1(위에서 사용한 Accelerate의 FSDP 통합)에서는 병합이 지원되지 않으며 오류가 발생합니다. FSDP2(
fully_shard)의 경우merge_adapter()와unmerge_adapter()가 샤드된 파라미터에 도달합니다.Linear,Embedding및 컨볼루션 기반 레이어에 대한 일반 LoRA(safe_merge포함) 병합이 작동하며,Linear에 대한 DoRA와 (IA)^3도 작동합니다. 다른 어댑터 또는 레이어 조합은 이러한 메서드로 처리되지 않으며, 오류가 발생하거나 병합이 조용히 실패할 수 있으므로 신뢰하기 전에 결과를 확인하십시오. 알려진 예시 중 하나는base_layer가 자체 FSDP2 모듈로 래핑된 DoRA 레이어로, 이는 오류를 발생시킵니다. modules_to_save구성 매개변수를 전달하는 기능은 현재 테스트되지 않았습니다.- CPU Offloading을 사용할 때의 GPU Memory 절감 효과는 현재까지 테스트되지 않았습니다.
- FSDP+QLoRA를 사용할 때
paged_adamw_8bit는 현재 체크포인트를 저장할 때 오류가 발생합니다. - FSDP를 사용한 DoRA 학습은 작동해야 합니다(LoRA보다 속도는 느릴 수 있음). bitsandbytes(QDoRA)와 결합할 경우 4-bit 양자화도 작동해야 하지만, 8-bit 양자화는 알려진 문제가 있어 권장되지 않습니다.
- FSDP2에서
set_adapter()와set_requires_grad()는requires_grad변경 사항이 샤드된 매개변수에 도달하도록 PeftModel 내부의 FSDP2 모듈,PeftModel자체를 포함하여 리샤드합니다. disable_adapter()를 종료하는 경우, FSDP2가 내부에 등록된 파라미터 객체를 샤드된 파라미터를 사용하는 포워드처럼 교체했거나, 재활성화 시requires_grad가 진입 시점의 값과 달라지는 경우에만 수행됩니다.merge_adapter()와unmerge_adapter()는 FSDP2 모듈도 다시 샤딩(reshard)하여, 병합(merge)과 역병합(unmerge)이 샤드된 파라미터에 도달하도록 합니다. 다시 샤딩하지 않으면 병합은 forward가 등록해 둔 언샤드된(unsharded) 파라미터에 적용되고, 다음 다시 샤딩 시 해당 변경 사항이 제거됩니다. 병합 자체는 샤드된 파라미터에 인플레이스(in place)로 기록됩니다.- FSDP2 모듈에서 병합된 어댑터 레이어의 파라미터를 샤딩하는 경우,
set_adapter()와set_requires_grad()에 의해 리샤딩되지 않으므로, 이러한 메서드를 호출하기 전에 언머지를 수행해야 합니다. FSDP2 환경에서disable_adapter()에 진입하면 병합된 레이어가 자동으로 언머지되어 샤딩된 파라미터까지 언머지가 적용되므로, 병합 상태는 컨텍스트를 통과하지 못합니다. reshard_after_forward=False인 경우 또는 기본값인None인 루트 모듈의 경우, 다음 forward에서 다시 all-gather가 수행됩니다.PeftModel을 래핑하는 FSDP2 모듈은 리샤드되지 않으므로, 이러한 메서드를 호출하기 전에 해당 모듈에reshard()를 호출해야 합니다.- Prompt learning 방법과 adaption prompt는 아직 다루지 않았습니다.
- FSDP2/HSDP를 사용하는 경우, 모든 참여 랭크에서
get_peft_model_state_dict()또는save_pretrained()를 호출해야 합니다. 분산 어댑터 텐서를 수집하는 작업은 집합 연산(collective)이기 때문입니다.save_pretrained()의 경우,is_main_process=True는 쓰기 담당 랭크에서만 전달하세요. 선택된 어댑터 항목(명시적으로 요청된 임베딩 또는modules_to_save포함)만 수집되며, 선택되지 않은 베이스 모델 가중치는 샤드된 상태로 유지됩니다.