Hugging Face's logo

Hub documentation

ジョブでモデルをトレーニング

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

ジョブでモデルをトレーニング

このページでは、Jobs上でライブラリのスクリプトまたは自作のスクリプトを使用してモデルをファインチューニングおよび学習する方法を示します。すべての例は、単一のA10Gで数分で完了する短い実行に制限されており、計算コストは約0.10ドルです。JobはHugging Faceのマシン上で実行されるため、ターミナルやラップトップを閉じても処理は継続されます。Jobをまだ実行したことがない場合は、クイックスタートでCLIのインストール、ログイン、およびJobに必要なクレジットについて説明しています。

初回の実行

このコマンドは、Food-101の2,000枚の画像で画像分類器をファインチューニングし、約3分でHub上のあなたのネームスペースにプッシュします:

hf jobs uv run --flavor a10g-small --timeout 30m -s HF_TOKEN -- \
  https://raw.githubusercontent.com/huggingface/transformers/main/examples/pytorch/image-classification/run_image_classification.py \
  --model_name_or_path google/vit-base-patch16-224-in21k \
  --dataset_name ethz/food101 \
  --do_train --do_eval \
  --remove_unused_columns False \
  --max_train_samples 2000 --max_eval_samples 500 --num_train_epochs 1 \
  --output_dir vit-food101 \
  --push_to_hub

Transformers セクションでは、フルランおよびその他のサンプルスクリプトについて説明しています。

トレーニングJobの構成

上記のコマンドは5つの部分から構成されており、このページのすべてのコマンドも同じ構成です。

  • 実行されるもの。 hf jobs uv run で起動される uv スクリプト、またはライブラリの Docker イメージです。uv スクリプトは、Python スクリプトの上部付近のコメントブロック（# /// script、PEP 723 形式）で依存関係を宣言し、uv が新しい環境にインストールします。TRL セクションにその例があります。一方、Docker イメージは hf jobs run で起動され、イメージにすでにインストールされているライブラリを使用します。ライブラリが pip でインストールできる場合は、uv スクリプトから始めることをお勧めします。コンパイル済みの依存関係を含むイメージが提供されている場合、またはドキュメントでそのように指示されている場合は、イメージを使用してください。トレードオフについては、Docker イメージの使用 を参照してください。
  • トークン。ジョブにはデフォルトで Hugging Face トークンが割り当てられません。-s HF_TOKEN を使用すると、あなたのトークンがシークレットとして転送され、実行時にモデルをプッシュしたり、ゲート付きまたはプライベートな入力を読み取ったりできます。その他のシークレットも同様に転送されます。例えば -s WANDB_API_KEY などです。
  • ハードウェアと時間。 --flavor で GPU を選択します。--timeout で時間制限を設定します。デフォルトは 30 分です。タイムアウトに達した実行は停止されるため、--timeout は予想される実行時間より長く設定してください。Hardware flavor と Timeout を参照してください。
  • A -- between the hf flags and the script. Flags before -- are for hf jobs. After it come the script path and the script’s own arguments. Without it, a script argument that shares a name with an hf flag, such as --timeout or --token, is taken by hf. In the image form, what follows -- is the command to run in the container.
  • 出力先。 以下のすべてのライブラリで、完成したモデルを Hub リポジトリにプッシュでき、各例ではそのオプションを示しています。Transformers と TRL では、リポジトリ名として --output_dir の値が使用されます。実行中にマウントされた バケット へ書き込むこともでき、-v を使用してコンテナにバケットをマウントします。終了後 を参照してください。

ご自身の学習コード。 状況に合った最もシンプルな形式を使用してください：

  • 1つのファイル。スクリプトのヘッダーで依存関係を宣言し、hf jobs uv run train.pyを実行します。TRLのセクションに1つの例が示されています。

  • ローカルインポートとpyproject.tomlまたは設定ファイルを含むプロジェクトフォルダ。hf jobs uv runはスクリプトファイルのみをアップロードするため、代わりにフォルダをマウントしてください。マウントは読み取り専用なので、コマンドはプロジェクトを書き込み可能なディレクトリにコピーして、ローカルで実行するのと同じようにそこで実行します:

    hf jobs run --flavor a10g-small --timeout 30m -s HF_TOKEN \
  -v ./my-project:/code ghcr.io/astral-sh/uv:python3.12-bookworm -- \
  bash -c "cp -r /code /tmp/project && cd /tmp/project && uv run train.py --config configs/run.yaml"

    uv run は pyproject.toml またはスクリプトのヘッダーから依存関係をインストールし、ローカルインポートや相対パスはそのまま動作します。ローカルディレクトリを参照してください。

  • システムパッケージやCUDAツールキットが必要なコード。イメージを一度ビルドして、hf jobs runで実行します。Docker Spaceで独自のイメージをビルドするを参照してください。

スクリプトは、スクリプトヘッダーの[tool.hf-jobs]テーブルに独自の起動設定を含めることもできます。TRLのセクションに示されているようにです。スクリプトで起動設定を定義するを参照してください。Pythonからは、設定で説明されているrun_uv_job()およびrun_job()として、同じコマンドが利用できます。

長時間実行前のチェック

キャップを解除する前に、いくつかのチェックを行うことで、無駄な実行を避けることができます。

  • まずスモークテストを実行します。 このページの例と同様に、小さなバリエーションでステップ上限を指定してコマンドを実行します。これにより、依存関係のインストール、データの読み込み、モデルの学習、プッシュの動作が確認できます。その後、上限を解除してフルランを開始します。
  • データが収まるか確認します。 各フレーバーには固定のディスクがあり、料金と請求の Ephemeral Storage 列に記載されています。重み、データセット、保存されたチェックポイントはこれらを共有します。ディスクに収まらない大きなデータセットは、ダウンロードする代わりにストリーミングまたはマウントできます。大規模データセットの処理を参照してください。
  • 実行時間の見積もり。 スモークテストの最終的なtrain_*メトリクスにはtrain_steps_per_secondが含まれており、Trainer は開始時に総ステップ数を出力します。これらを組み合わせることで、フルランのトレーニング時間を算出できます。Job は依存関係のインストールやモデルのダウンロードにも時間がかかるため、--timeoutはこれより十分に余裕を持たせて設定してください。各フレーバーの料率は料金と請求を参照してください。
  • マルチGPUのフレーバーでは、GPUごとに1つのプロセスを起動します。 x2、x4、またはx8で終わるフレーバーは、1台のマシンに複数のGPUを提供します。起動方法がそれらを使用していることを確認してください。TransformersとTRLは、TRLのセクションに示されているようにaccelerate launchが必要です。Axolotlはそれ自体で処理します。単純なpython train.pyは1つのGPUしか使用せず、TrainerはDataParallelにフォールバックしますが、これはGPUごとに1プロセスの方式よりも遅くなります。
  • 再実行する場合はピン留めしてください。 スクリプトの URL は main ではなく特定のコミットに、イメージは latest ではなく特定のタグにピン留めしてください。これにより、再実行時に同じソフトウェアが使用されます。以下のスクリプト URL は main を追跡しているため、再実行する前にコミットをピン留めしてください。
  • マウントされたバケットに長時間の実行をチェックポイントすることで、タイムアウトやクラッシュが発生しても実行結果を失わないようにします。終了後を参照してください。

実行中

hf jobs run と hf jobs uv run はどちらもログをストリーミング表示し、実行が終了するまでターミナルを保持します。Ctrl+C はログのストリーミングのみを停止します。ジョブは、完了するか、hf jobs cancel <job_id> で停止するまで実行を続けます。

長時間の実行では、-d（detach）を渡して Job ID を即座に取得し、その後 hf jobs logs -f <job_id> で実行を追跡し、hf jobs stats <job_id> で GPU が使用中であることを確認します。detach された実行の後、hf jobs wait <job_id> は Job が終了するまでブロックし、失敗した場合は非ゼロで終了します。これはスクリプトやエージェントループに必要な動作です。非 detach の実行はすでにこの動作を行います。Jobs の管理を参照してください。

ジョブログは損失値をテキストとして出力します。曲線を表示するには、trackioなどの実験トラッカーをトレーナーに指定し、Weights & Biasesなどのホスト型トラッカーを使用する場合は、そのキーを2番目のシークレットとして渡します。

終了後

Jobが終了した場合（正常終了、失敗、タイムアウトのいずれかであっても）、そのJobのディスクは破棄されます。保持したいデータは、その前にコンテナの外へ退避する必要があります。

モデルを Hub リポジトリにプッシュします。 このページのすべてのライブラリにそのオプションがあります: Transformers、TRL、Diffusers では --push_to_hub、Unsloth スクリプトでは --output-repo、Axolotl YAML では hub_model_id です。実行の最後に、ライブラリは重み、トークナイザー、およびベースモデルと学習引数を記録した生成されたモデルカードをアップロードします。リポジトリが存在しない場合は作成されます。プライベートにするには、まず hf repos create <name> --private で作成してください。細粒度トークンは、モデルリポジトリへの書き込みと作成アクセスが必要です。これがない場合、実行は最後まで学習しますが、アップロードで失敗します。

処理を進めるにつれてバケットに書き込みます。 数時間かかる実行の場合、既存のStorage Bucketを読み書き可能にマウントし（hf buckets createでバケットを作成できます）、ライブラリの出力ディレクトリをそこに指定します。チェックポイントは保存されるたびにバケットに格納されるため、タイムアウトやクラッシュが発生しても実行が失われることはなく、次のJobはそれらから再開できます。モデル以外の評価出力、ログ、その他のデータについても、同じ方法が適用できます。

hf jobs uv run --flavor a10g-large --timeout 8h -s HF_TOKEN \
  -v hf://buckets/your-username/checkpoints:/ckpt -- \
  train.py --output_dir /ckpt/run-01

Transformers、TRL、Diffusers のスクリプトは --output_dir を受け取ります。Axolotl は YAML で output_dir を指定します。--push_to_hub も渡す場合は、--hub_model_id も設定してください。設定しないと、リポジトリ名は出力パスの最後の部分（run-01）になります。中断された実行を再開するには、同じバケットを再度マウントし、ライブラリの再開オプション（Transformers の Trainer なら --resume_from_checkpoint など）を渡します。マウントオプションについては ボリューム を参照してください。

失敗した実行の読み取り。 失敗した Job はログを保持します: hf jobs logs <job_id> は終了後も動作し、hf jobs inspect <job_id> は最終ステータスとエラーメッセージを返します。 hf jobs logs -f は実行が成功したかどうかに関わらず、ログストリームが終了すると返ってくるため、正常に動作したと判断する前に inspect を確認してください。

Transformers

Transformers リポジトリのサンプルスクリプトは、スクリプトのヘッダーに依存関係を宣言しているため、GitHub の URL からそのまま Jobs で実行できます。URL の後ろの引数はスクリプトに渡されます。初回実行では、image-classification スクリプトを使用します。

フルランでは、そのコマンドから--max_train_samples 2000 --max_eval_samples 500 --num_train_epochs 1を削除してください。Food-101の75,000枚のトレーニング画像で3エポックの実行は、a10g-smallで約1時間かかり、そのフレーバーのレートでは約1ドルで、90%の精度に達します。起動する前に--timeoutを2hに上げてください。--push_to_hubは、出力ディレクトリ名を使用して、あなたのネームスペース配下にモデルをアップロードします。テキスト分類、要約、翻訳、トークン分類、音声認識など、スクリプトが用意されています。

TRL

TRLには、各トレーナー（SFT、DPO、GRPO など）ごとに実行可能なスクリプトが用意されており、それぞれが独自の依存関係を宣言しているため、Transformersのスクリプトと同様に、URLからそのままJobs上で実行できます。このコマンドは、チャットデータセットで小型モデルをファインチューニングします。

hf jobs uv run --flavor a10g-small --timeout 30m -s HF_TOKEN -- \
  https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py \
  --model_name_or_path Qwen/Qwen2-0.5B-Instruct \
  --dataset_name trl-lib/Capybara \
  --max_steps 100 \
  --output_dir Qwen2-0.5B-SFT \
  --push_to_hub

この処理は約6分で完了します。フルランを実行するには--max_stepsを削除してください。Capybaraの3エポック（スクリプトのデフォルト）はa10g-smallで約2時間20分かかりますので、--timeoutをそれに応じて引き上げてください。TRLの公式ドキュメントでは、より高速なa100-largeが使用されています。

スクリプトの作成やhuggingface/trlイメージの実行を含む完全なガイドは、TRLドキュメントのJobsでの学習を参照してください。

複数のGPUを使用する場合は、accelerateが同梱されているTRLイメージに切り替え、GPUごとに1つのプロセスを起動するように設定します。

hf jobs run --flavor a10g-largex2 --timeout 30m -s HF_TOKEN huggingface/trl -- \
  accelerate launch --num_processes 2 -m trl.scripts.sft \
  --model_name_or_path Qwen/Qwen2-0.5B-Instruct \
  --dataset_name trl-lib/Capybara \
  --max_steps 100 \
  --output_dir Qwen2-0.5B-SFT \
  --push_to_hub

--max_stepsを指定しない場合、フルラン（Capybaraの3エポック、スクリプトのデフォルト）は2つのA10Gで約1時間35分かかります。

独自のTRLスクリプトを作成する際、起動設定をスクリプトに含めることができます。ヘッダーの[tool.hf-jobs]テーブルで、flavor、タイムアウト、シークレットを設定します。

# /// script
# dependencies = ["trl"]
#
# [tool.hf-jobs]
# flavor  = "a10g-small"
# timeout = "1h"
# secrets = ["HF_TOKEN"]
# ///
from trl import SFTConfig, SFTTrainer
...

hf jobs uv run train.py を使用する場合、フラグは不要です。また、フラグを指定した場合は、その指定が優先されます。スクリプト内で起動設定を定義するを参照してください。

Unsloth

Unslothは、unsloth/jobsデータセットに、モデルファミリーごとに1つずつ、すぐに実行できるスクリプトを提供しています。これらのスクリプトは、スクリプトのヘッダーからUnslothをインストールし、データセットと出力リポジトリを引数として受け取ります。

hf jobs uv run --flavor a10g-small --timeout 30m -s HF_TOKEN -- \
  https://huggingface.co/datasets/unsloth/jobs/resolve/main/sft-lfm2.5.py \
  --dataset mlabonne/FineTome-100k \
  --max-steps 50 \
  --output-repo your-username/lfm-finetuned

この処理は約5分で完了し、LoRAアダプターをプッシュします。1エポック分を処理するには、--max-steps 50を--num-epochs 1に置き換え、--timeoutの値を上げてください。詳細な手順は、Hugging FaceブログのFine-tune with Unsloth on Jobsを参照してください。

Axolotl

Axolotl は YAML 設定を受け取り、独自の Docker イメージから実行されるため、このセクションでは固定タグ付きの hf jobs run を使用し、-v でローカルディレクトリから設定を同期します。Axolotl examples から設定を ./configs/lora.yml として保存し、コマンドの後に示すキーを追加してください。この例では、Phi-3.5-mini の LoRA ファインチューニングを行う examples/phi/lora-3.5.yaml を使用しており、それ以外は変更していません。イメージにはすでに axolotl コマンドが含まれています。

hf jobs run --flavor a10g-small --timeout 30m -s HF_TOKEN \
  -v ./configs:/configs \
  axolotlai/axolotl:0.19.0-py3.12-cu130-2.13.0 -- \
  axolotl train /configs/lora.yml

-v ./configs:/configs は、ローカルの configs ディレクトリを、初回使用時に作成されるプライベートな jobs-artifacts バケットにアップロードし、コンテナ内に読み取り専用でマウントします。これにより、ディスク上の YAML がそのまま実行で使用する YAML となります。出力は YAML で設定します。以下のキーは実行終了時にモデルをプッシュし、max_steps はこの試行実行の上限を指定します。

hub_model_id: your-username/my-adapter
hub_strategy: end
max_steps: 20

この処理は約7分で完了し、アダプターをhub_model_idにプライベートリポジトリとしてプッシュします。フルランを実行するにはmax_stepsを削除してください。イメージタグの形式については、AxolotlのDockerガイドを参照してください。

GPU を増やす場合は、フレーバーを変更するだけで、それ以外は変更しません。a10g-largex4 の場合、axolotl train は自動的に GPU ごとに 1 つのプロセスを開始します。DeepSpeed と FSDP は YAML のキーで設定でき、Axolotl のマルチ GPU ガイド で説明しています。

詳細については、AxolotlのドキュメントにあるHugging Face Jobsガイドを参照してください。

Diffusers

DiffusersリポジトリのDreamBooth LoRAスクリプトの多くは、スクリプトのヘッダーに依存関係を宣言しているため、Transformersのスクリプトと同様に、GitHub URLからそのままJobsで実行できます。このコマンドは、犬の5枚の写真でFLUX.2 [klein] 4BのLoRAを学習します。

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-lora

この処理は約5分で完了し、LoRAをプッシュします。本番実行では--max_train_stepsを大きくしてください。FLUX.2 READMEでは500が使用されています。そのフォルダ内の他のREADMEには、残りのモデルとそのメモリオプションについて記載されています。スクリプトの先頭にある# /// scriptブロックを確認してください。SDXLスクリプトのようにこのブロックがないスクリプトは、--withで依存関係を渡す必要があります。

さらに深く

  • Serve Models を使用すると、学習したモデルを一時的なエンドポイントの背後に配置して、評価実行やデモを行うことができます。Inference Endpoints は、常時稼働するエンドポイントを実行します。
  • シークレット、環境変数、ボリューム、およびスクリプトに独自のフラバーとタイムアウトを持たせるための[tool.hf-jobs]テーブルの設定。
  • ジョブの一覧表示、詳細確認、デバッグ、キャンセルを行うためのManage Jobs。
  • ディスクに収まらないデータのストリーミングとマウントには、大規模データセットの処理を使用します。
  • タイマーでトレーニングコマンドを実行するには、Schedule Jobsを使用します。
  • コミュニティによる記事を含むExamples & Tutorials。ビジョン言語モデルのファインチューニングや、トレーニング実行への大規模データセットのストリーミング処理などが含まれます。
  • コーディングエージェントからJobsを使用する: hf CLIスキルにより、Claude Code、Codex、Cursorがこれらの実行を起動して監視してくれます。
Update on GitHub

←モデルのサービング 例とチュートリアル→