Diffusers documentation
Hugging Face Jobs
Hugging Face Jobs
Hugging Face Jobs は Hugging Face の GPU で実行されるため、マシンのセットアップは不要です。また、ターミナルを閉じても実行は継続されます。Diffusers の学習スクリプトは、リポジトリをクローンしたりローカルに何かをインストールしたりすることなく、GitHub の URL からそのまま Jobs で実行できます。
開始する前に、Jobs クイックスタートに従って、hf CLI をインストールし、ログインして、アカウントにクレジットを追加してください。
JobsでLoRAを学習
以下のコマンドは、diffusers/dog-example にある5枚の犬の写真で FLUX.2-klein-4B の LoRA を学習します。単一の A10G で実行でき、学習した LoRA を Hub 上のあなたのネームスペースにプッシュします。
# 20 steps is a test run. For a real run, raise --max_train_steps
# (the FLUX.2 README uses 500) and --timeout to match.
hf jobs uv run --flavor a10g-small --timeout 30m -s HF_TOKEN -- \
https://raw.githubusercontent.com/huggingface/diffusers/main/examples/dreambooth/train_dreambooth_lora_flux2_klein.py \
--pretrained_model_name_or_path black-forest-labs/FLUX.2-klein-4B \
--dataset_name diffusers/dog-example \
--instance_prompt "a photo of sks dog" \
--resolution 512 --mixed_precision bf16 --guidance_scale 1 \
--gradient_checkpointing --cache_latents \
--optimizer adamW --use_8bit_adam --learning_rate 1e-4 \
--max_train_steps 20 --seed 0 \
--output_dir /tmp/out \
--push_to_hub --hub_model_id your-username/klein-dog-lorauv は、スクリプトの # /// script ヘッダーに列挙された依存関係をインストールします。これには main からの Diffusers も含まれます。ジョブにはデフォルトで Hugging Face トークンが与えられないため、-s HF_TOKEN を使用してトークンをスクリプトに渡し、LoRA をプッシュできるようにします。ジョブのディスクはジョブ終了時に破棄されるため、プッシュしなかったデータは失われます。DreamBooth と LoRA のガイドでは、トレーニング引数について説明しています。
ジョブの管理
Jobの実行中、トレーニングログはターミナルに出力されます。ターミナルを閉じたりCtrl+Cを押したりしても、JobはHugging Faceのマシン上で実行されるため、トレーニングは停止しません。ターミナルを占有せずに長時間の実行を開始するには、--の前に-dを追加します。すると、コマンドはJob IDを出力して返ります。
Job ID を使用して、ログに再接続したり、モデルの学習中に GPU メモリと使用率を確認したり、実行を停止したりできます。
hf jobs logs -f <job_id>
hf jobs stats <job_id>
hf jobs cancel <job_id>実行が失敗した場合、hf jobs inspect <job_id> でエラーメッセージが表示されます。その他のコマンドについては、ジョブの管理を参照してください。
自分の画像で学習
画像で学習するには、-v を使用してそのフォルダを Job にマウントし、--dataset_name の代わりにマウントパスを --instance_data_dir に渡します。Jobs は Job の開始前にフォルダをプライベートバケットにアップロードし、読み取り専用でマウントします。同じフォルダを再度アップロードしても、新規または変更されたファイルのみが送信されます。
hf jobs uv run --flavor a10g-small --timeout 30m -s HF_TOKEN \
-v ./my-dog:/data -- \
https://raw.githubusercontent.com/huggingface/diffusers/main/examples/dreambooth/train_dreambooth_lora_flux2_klein.py \
--pretrained_model_name_or_path black-forest-labs/FLUX.2-klein-4B \
--instance_data_dir /data \
--instance_prompt "a photo of sks dog" \
--resolution 512 --mixed_precision bf16 --guidance_scale 1 \
--gradient_checkpointing --cache_latents \
--optimizer adamW --use_8bit_adam --learning_rate 1e-4 \
--max_train_steps 20 --seed 0 \
--output_dir /tmp/out \
--push_to_hub --hub_model_id your-username/klein-dog-loraスクリプトは--instance_data_dir内のすべてのファイルを画像として開くため、フォルダには画像のみを保存してください。.DS_Storeのような隠しファイルがあると実行が失敗します。フォルダのマウントに関する詳細は、ローカルディレクトリを参照してください。
--with_prior_preservation を使用すると、スクリプトは学習開始前にクラス画像を --class_data_dir に生成します。Job が書き込み可能なパスを指定してください。後続の実行でクラス画像を再利用するには、長時間実行用のチェックポイントの保存 に記載されているような読み書き可能なバケットマウントに配置してください。
FP8で学習
FLUX.2、Z-Image、Ideogram 4、および Krea 2 の DreamBooth LoRA スクリプトは、--do_fp8_training を指定することで torchao を使用して FP8 で学習し、メモリ使用量を削減できます。スクリプトのヘッダーには torchao が含まれていないため、-- の前に --with torchao を追加してください。また、FP8 には L4 (l4x1) や L40S (l40sx1) のような、コンピュート能力 8.9 以上の GPU が必要です。A10G (8.6) と A100 (8.0) はサポートされていません。
依存関係ヘッダーなしでスクリプトを実行する
examples/dreambooth と examples/advanced_diffusion_training にあるスクリプトのみ、ファイルの先頭に # /// script ブロックを宣言しています。これらのフォルダ内の train_dreambooth_lora_sdxl.py などのスクリプトには、このブロックが含まれていません。
ヘッダーのないスクリプトでは、各依存関係を--withで渡します。学習スクリプトは開発版を必要とするため、Diffusersはソースからインストールしてください。その他の依存関係は、スクリプトのrequirements.txtファイルとそのインポートから取得されます。
hf jobs uv run --flavor a10g-small --timeout 30m -s HF_TOKEN \
--with "diffusers @ git+https://github.com/huggingface/diffusers.git" \
--with torch --with torchvision --with accelerate --with transformers \
--with peft --with datasets --with bitsandbytes \
--with ftfy --with tensorboard --with Jinja2 -- \
https://raw.githubusercontent.com/huggingface/diffusers/main/examples/dreambooth/train_dreambooth_lora_sdxl.py \
--pretrained_model_name_or_path stabilityai/stable-diffusion-xl-base-1.0 \
--pretrained_vae_model_name_or_path madebyollin/sdxl-vae-fp16-fix \
--dataset_name diffusers/dog-example \
--instance_prompt "a photo of sks dog" \
--resolution 1024 --mixed_precision fp16 \
--gradient_checkpointing --use_8bit_adam --learning_rate 1e-4 \
--max_train_steps 20 --seed 0 \
--output_dir /tmp/out \
--push_to_hub --hub_model_id your-username/sdxl-dog-lora長時間の実行用にチェックポイントを保存する
数時間かかる実行は、完了前にタイムアウトやクラッシュが発生する可能性があります。進捗を保持するには、-v を使用してジョブに Storage Bucket をマウントし、--output_dir をそのバケットに向けます。まず、hf buckets create でバケットを作成してください。
スクリプトは、--checkpointing_steps ステップ（デフォルトは 500）ごとに checkpoint-<step> フォルダを --output_dir に保存するため、学習が進むにつれてチェックポイントがバケットに格納されます。--checkpoints_total_limit で保持するチェックポイントの最大数を制限できます。--resume_from_checkpoint latest を使用すると、--output_dir 内の最新のチェックポイントから学習を再開し、チェックポイントが存在しない場合は最初から学習を開始します。そのため、初回実行と各回の再起動の両方で同じコマンドを使用できます。
hf jobs uv run --flavor a10g-small --timeout 8h -s HF_TOKEN \
-v hf://buckets/your-username/checkpoints:/ckpt -- \
https://raw.githubusercontent.com/huggingface/diffusers/main/examples/dreambooth/train_dreambooth_lora_flux2_klein.py \
--pretrained_model_name_or_path black-forest-labs/FLUX.2-klein-4B \
--dataset_name diffusers/dog-example \
--instance_prompt "a photo of sks dog" \
--resolution 1024 --mixed_precision bf16 --guidance_scale 1 \
--gradient_checkpointing --cache_latents \
--optimizer adamW --use_8bit_adam --learning_rate 1e-4 \
--max_train_steps 5000 --seed 0 \
--checkpointing_steps 500 --checkpoints_total_limit 3 \
--resume_from_checkpoint latest \
--output_dir /ckpt/klein-dogトレーニングが終了すると、LoRA はバケットに pytorch_lora_weights.safetensors として保存されます。マウントオプションについては、ボリュームを参照してください。
--output_dirにチェックポイントが含まれている場合、--push_to_hubを追加しないでください。アップロードはstep_*とepoch_*フォルダーのみをスキップするため、checkpoint-<step>フォルダーは LoRA と一緒にモデルリポジトリにプッシュされてしまいます。代わりに、pytorch_lora_weights.safetensorsを自分でモデルリポジトリにアップロードしてください。
次のステップ
- Hub のドキュメントにある Train Models on Jobs を参照し、長時間のジョブ実行前に実施すべきチェック項目や、失敗したジョブの読み取り方法を確認してください。
- LoRAガイドに従って、学習済みのLoRAを読み込んで推論を実行してください。
- モデル固有のコマンドやメモリオプションについては、DreamBoothのREADMEファイルを参照してください。