PEFT documentation
Fully Sharded Data Parallel
Fully Sharded Data Parallel
Fully sharded data parallel (FSDP) は、最大 1T パラメータまでの大規模事前学習モデルの分散学習用に開発されました。FSDP は、モデルのパラメータ、勾配、オプティマイザの状態をデータ並列プロセス間でシャーディングすることでこれを達成し、シャーディングされたモデルのパラメータを CPU にオフロードすることもできます。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 は、各フォワードパス後に集約されたパラメータを解放します。FSDP2 は個々のパラメータをシャーディングするため、FSDP1 の use_orig_params 設定は使用しません。その他の設定オプションについては、Transformers FSDP ガイドを参照してください。
例のfsdp2_config.jsonで、モデル、データセット、学習オプションを編集します。examples/sftから、GPUごとに1つのプロセスを起動します:
torchrun --standalone --nproc_per_node=2 train.py configs/fsdp2_config.json
BF16 に対応していない GPU では、JSON ファイルに "bf16": false と "fp16": true を設定してください。
PEFT v0.22 より前のバージョンでは、空のアダプターのエクスポートを回避するために、activation_checkpointingをfalseに設定してください。PEFT v0.22には、アダプターエクスポートの修正が含まれています。
保存と再開
トレーニングを再開するには、同じ FSDP 設定を維持し、JSON ファイルに"resume_from_checkpoint": "path/to/checkpoint-N"を設定します。トレーニングのチェックポイントには、シャーディングされたモデルとオプティマイザーの状態が含まれます。
トレーニングの終了時、この例ではアダプターをエクスポートする前に完全な状態辞書を収集します。
if trainer.is_fsdp_enabled:
trainer.accelerator.state.fsdp_plugin.set_state_dict_type("FULL_STATE_DICT")
trainer.save_model()すべてのランクがgatherに参加する必要があります。アダプターファイルを書き込むのはメインプロセスのみです。完全な状態辞書をgatherすると、メモリ使用量が一時的に増加します。
推論のために、エクスポートされたアダプターを読み込みます:
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でLoRAとFSDP1を用いてLlama-70Bをファインチューニングします。Accelerateの設定を変更することで、複数マシンへのスケーリングが可能です。
設定
🤗 Accelerate を使用して、FSDP 設定ファイルを作成する以下のコマンドを実行することから始めます。--config_file フラグを使用すると、設定ファイルを特定の場所に保存できます。指定しない場合、🤗 Accelerate のキャッシュ内に default_config.yaml として保存されます。
設定ファイルは、学習スクリプトを起動する際のデフォルトオプションを設定するために使用されます。
accelerate config --config_file fsdp_config.yaml
セットアップに関するいくつかの質問が表示されるので、以下の引数を設定します。この例では、下の画像に示されているようにアンケートに回答します。

これらが完了すると、対応する設定は以下のようになります。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でLoRAを使用し、すべての線形層を対象にしている点に注意してください。FSDP設定ファイルを渡し、ultrachatデータセットの部分集合で70BのLlamaモデルをファインチューニングしています。
重要な部分
スクリプトの中身をもう少し詳しく見ていきましょう。何が起きているのか、どのように動作するのかを理解するために。
まず知っておくべきことは、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のstate dict型でモデルを保存するためです。これにより、推論時にfrom_pretrainedメソッドで通常どおり読み込めるアダプター重みをモデルが持つようになります。

FSDP1とQLoRA
このセクションでは、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エコシステムに統合されています。
現在のPEFT、Transformers、TRL、Accelerateはbitsandbytes>=0.43.3と併用してください。この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: falserun_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"新しい引数として渡されるbnb_4bit_quant_storage_dtypeに注目してください。これは、4ビットのパラメータをパックするためのデータ型を指定します。例えば、bfloat16に設定すると、量子化後に16/4 = 4個の4ビットパラメータがパックされます。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オフローディングを使用した場合のGPUメモリ節約は、現時点では未検証です。
- FSDP+QLoRAを使用する場合、
paged_adamw_8bitでは現在、チェックポイントの保存時にエラーが発生します。 - FSDP による DoRA トレーニングは動作するはずです(ただし LoRA より速度は低くなります)。bitsandbytes(QDoRA)と組み合わせる場合、4 ビット量子化も動作するはずですが、8 ビット量子化には既知の問題があり、推奨されていません。
- FSDP2では、
set_adapter()およびset_requires_grad()が、PeftModel内のFSDP2モジュールを再シャーディングします。これにはPeftModel自体も含まれ、requires_gradの変更がシャーディングされたパラメータに反映されるようになります。 disable_adapter()からの復帰は、FSDP2が内部に登録されたパラメータオブジェクトを置き換えた場合(フォワードパスがシャードされたパラメータに対して行う処理と同様)、または再有効化によってrequires_gradが関数呼び出し時の状態から変更される場合のみ行われます。merge_adapter()およびunmerge_adapter()は、FSDP2 モジュールも再シャーディングします。これにより、マージとアンマージがシャーディングされたパラメータに到達します。再シャーディングを行わない場合、マージは forward が登録したアンシャーディングされたパラメータに適用されてしまい、次の再シャーディングで破棄されてしまいます。マージ自体は、シャーディングされたパラメータにインプレースで書き込まれます。- FSDP2 モジュールは、マージ済みアダプタ層のパラメータをシャーディングしていますが、
set_adapter()およびset_requires_grad()によって再シャーディングされません。そのため、これらのメソッドを呼び出す前にアンマージしてください。FSDP2 環境でdisable_adapter()にエントリすると、マージ済み層が自動的にアンマージされ、アンマージがシャーディングされたパラメータに反映されます。したがって、マージはコンテキストを抜けた後に維持されません。 reshard_after_forward=Falseの場合、またはデフォルトのNoneが設定されているルートモジュールの場合、次のforwardで再度all-gatherが行われます。PeftModelをラップするFSDP2モジュールは再シャーディングされません。これらのメソッドを呼び出す前に、それらに対してreshard()を呼び出してください。- プロンプト学習手法と適応プロンプトについては、まだカバーされていません。
- FSDP2/HSDPを使用する場合、
get_peft_model_state_dict()またはsave_pretrained()をすべての参加ランクで呼び出してください。分散アダプターテンソルの集約は集合通信です。save_pretrained()の場合、is_main_process=Trueは書き込みを行うランクでのみ渡してください。集約されるのは選択されたアダプターエントリ(明示的に要求されたembeddingやmodules_to_saveを含む)のみであり、選択されていないベースモデルの重みはシャードされたままです。