Jobsでのトレーニング

Hugging Face Jobsは、Hugging FaceのGPU上でトレーニングを実行します。各実行ごとにハードウェアを選択し、実行された秒数分のみ課金されます。--push_to_hubを使用すると、トレーニングが完了した時点でモデルがHubにアップロードされます。

このガイドでは、次のことを学びます。

1つのコマンドでTRLの学習スクリプトを起動します
ランを追跡して、その損失曲線を確認します
…のファイルにハードウェア設定を指定して、独自のスクリプトを実行します
チェックポイントを保存し、中断された実行を再開する
複数のGPUで学習

Jobsの一般的な仕組み（ハードウェアや料金体系を含む）については、Jobsのドキュメントを参照してください。

要件

正のクレジット残高を持つ Hugging Face アカウント。ジョブは従量課金制です。使用した秒数分のみ課金されます。
Hugging Face Hub にログイン済み(hf auth login)

初回の実行

このコマンドは、TRL SFTスクリプトを使用してCapybaraチャットデータセットでQwen2-0.5B-Instructをファインチューニングし、その後モデルをあなたのアカウントにプッシュします:

bash

python

It takes a few minutes and costs well under $1 on a10g-small. The options before -- are for Jobs: the hardware, a time limit and the token used to push the model. --secrets HF_TOKEN sends the token you logged in with. In Python, pass the token itself. The arguments after the script URL go to the script. hf jobs uv run runs a Python script with uv. sft.py lists its dependencies in a header at the top of the file, so Jobs installs TRL before the script starts. The Job stops when the script exits, and billing stops with it.

--max_steps 100 はこの最初のランを短く保ちます。フルランではこれを削除してください。3エポック（スクリプトのデフォルト）は a10g-small で数時間かかるため、--timeout をそれに合わせて引き上げてください。例えば --timeout 3h のようにします。Jobs はタイムアウトに達するとランを停止します。デフォルトは30分です。a100-large のようなより大きな GPU では、より早く完了します。フレーバーとその価格については Hardware を参照してください。

実行を追跡する

hf jobs uv run はログをストリーミング表示し、実行が終了するまでターミナルを保持します。Ctrl+C はログストリームのみを停止し、Job 自体は実行を続けます。--detach を追加すると、すぐに Job ID が返され、その後:

hf jobs logs -f <job_id>   # stream the logs
hf jobs ps                 # list your running Jobs
hf jobs inspect <job_id>   # status, and the error message if it failed
hf jobs cancel <job_id>    # stop it

詳細は、ジョブの管理を参照してください。

ロスカーブについては、TRLはTrackioにログを出力します。ダッシュボード用のSpaceに名前を付けるには、--の前に--env TRACKIO_SPACE_ID=<your-username>/trackioを追加し、スクリプトURLの後に--report_to trackioを追加します。Spaceとメトリクスのバケットが存在しない場合、Trackioがそれらを作成します。どちらもデフォルトで公開されています。Transformersがサポートする他のトラッカーも使用できます。Weights & Biasesを使用するには、--の前に--with wandb --secrets WANDB_API_KEYを追加し、スクリプトURLの後に--report_to wandbを追加します。--secrets WANDB_API_KEYは、ローカル環境のWANDB_API_KEYから値を読み取ります。他の渡し方については、環境変数とシークレットを参照してください。

独自のスクリプトを実行する

トレーニングコードをPythonファイル（例: train.py）に記述します。ファイルの先頭に、TRLのスクリプトと同様にスクリプトヘッダーとして依存関係を列挙します。ジョブはスクリプトの開始前にこれらをインストールします:

# /// script
# dependencies = [
#     "trl",
#     "peft",
# ]
# ///

from datasets import load_dataset
from peft import LoraConfig
from trl import SFTConfig, SFTTrainer

dataset = load_dataset("trl-lib/Capybara", split="train")

trainer = SFTTrainer(
    model="Qwen/Qwen2.5-0.5B",
    train_dataset=dataset,
    peft_config=LoraConfig(),
    args=SFTConfig(output_dir="Qwen2.5-0.5B-SFT", max_steps=100),
)
trainer.train()
trainer.push_to_hub()

次に、hf jobs CLIまたはPython APIで起動します:

bash

python

ヘッダーのないスクリプトの場合、--with をパッケージごとに1回ずつ指定して、起動時に依存関係を列挙します: --with trl --with peft (Python では dependencies=["trl", "peft"])。スクリプトは URL でもよく、GitHub raw リンク、Gist、またはパブリックな Hub リポジトリ内のファイルなどが該当します。

起動設定はスクリプト内に記述することもできます。ヘッダーの[tool.hf-jobs]テーブルで、ハードウェア、タイムアウト、シークレットを設定します:

# /// script
# dependencies = [
#     "trl",
#     "peft",
# ]
#
# [tool.hf-jobs]
# flavor = "a10g-small"
# timeout = "30m"
# secrets = ["HF_TOKEN"]
# ///

hf jobs uv run train.py はオプションを必要としません。また、渡したオプションはスクリプトの内容を上書きします。スクリプトには実行に必要な情報がすべて含まれているため、GPU やタイムアウトを覚えておくことなく、スクリプトを共有したり、後で実行したりできます。hf jobs uv run --dry-run train.py は解決された設定を表示し、スクリプト由来の値にマークを付けます。このテーブルは hf CLI によってのみ読み取られ、run_uv_job() では無視されます。スクリプト内で起動設定を定義するを参照してください。

任意のTRLスクリプトを実行する

同じパターンは、すべてのTRLトレーナーのスクリプト（SFT、DPO、GRPO、報酬モデリングなど）およびExamples Indexのスタンドアロンな.py例に適用されます。各スクリプトは、スクリプトのヘッダーに依存関係を宣言しています。隣接する他のファイルを読み込む例では、そのフォルダをJobにマウントする必要があります。Local directoriesを参照してください。ノートブック専用の例は、この方法では提出できません。スクリプトの引数は、ローカルでスクリプトを実行する場合と同じです。

チェックポイントの保持

Jobが終了すると、タイムアウトに達した場合や失敗した場合を含む、そのJobのディスクは削除されます。長時間の実行では、チェックポイントをJobの外に保存し、Jobの終了後も保持されるようにしてください。

最もシンプルな方法は、チェックポイントが保存されるたびに、そのまま出力モデルのリポジトリにプッシュすることです：

bash

python

--hub_strategy checkpoint を使用すると、オプティマイザーの状態を含む最新のチェックポイントが、リポジトリの last-checkpoint フォルダに保存されます。中断された実行を再開するには、リポジトリを新しい Job にマウントし、そのフォルダから再開します。スクリプトの URL の前に --volume hf://<your-username>/Qwen2-0.5B-SFT:/previous を、-- の後に --resume_from_checkpoint /previous/last-checkpoint を追加して、同じコマンドを起動します。

モデルリポジトリの外に複数のチェックポイントを保持するには、代わりにStorage Bucketに書き出します。hf buckets create <your-username>/checkpoints --privateでバケットを作成し、Jobにマウントして--output_dirをそこに指定します:

bash

python

中断された実行を再開するには、--resume_from_checkpoint /checkpoints/Qwen2-0.5B-SFT/checkpoint-<step> を付けて同じコマンドを再度実行してください。詳細については、処理しながらバケットに書き込むおよびマウントオプションについては Volumes を参照してください。

各チェックポイントは、モデルとオプティマイザーの状態を保持しており、そのサイズはモデルのサイズの何倍にもなります。最新のもののみを保持するには、--save_total_limit 2を追加してください。--push_to_hubも渡す場合は、--hub_model_idを設定するか、リポジトリ名を出力パスの最後の部分に設定してください。

複数のGPU

複数のGPUを使用するフレーバーにより、実行時間を短縮できます。これには、hf jobs runを使用します。これはスクリプトではなくDockerイメージ内でコマンドを実行するもので、TRLとAccelerateがインストール済みのhuggingface/trlイメージを使用します。その後、GPUごとに1つのプロセスを開始します。この方法は、TRLのスクリプトにも、ご自身の学習コードにも適用できます。

TRLスクリプトの高速化

このガイドの冒頭で実行したSFTを、4つのGPUで:

bash

python

trl CLI は --num_processes を accelerate launch に渡します。この値は、flavor の GPU 数、ここでは 4 つの L4 に設定します。各プロセスが独自のバッチを処理するため、実効バッチサイズはシングル GPU 実行時の 4 倍になります。この実行には数分かかります。--max_steps を指定しないと、3 エポック全体で約 1 時間かかるため、--timeout を例えば 2h に引き上げてください。

ご自身のスクリプト

TRLのスクリプトに限定されるわけではありません。accelerate launchでローカルで実行できる学習コードは、イメージに必要なパッケージが含まれている限り、Jobsでも同じように実行できます。例えば、独自の報酬関数を含むGRPOスクリプトをtrain_grpo.pyとしてフォルダに保存し、そのフォルダをJobにマウントします。Jobsはフォルダをプライベートバケットにアップロードし、読み取り専用でマウントします：

bash

python

スクリプトはイメージにTRLがインストールされた状態で実行されるため、スクリプトヘッダーは不要です。GRPOTrainerはデフォルトでtransformersを使用して補完を生成するため、vLLMサーバーなしで単一のJobで実行されます。より高速な生成については、vLLM Integrationを参照してください。次のセクションでは、hf jobs runがイメージを使用する方法を説明します。

Dockerイメージ

Jobs は uv を使用してスクリプトを実行します。これにより、スクリプトの # /// script ヘッダーに宣言された依存関係が新しい環境にインストールされます。したがって、スクリプトがインポートする TRL はイメージではなくそのヘッダーから取得され、上記の hf jobs uv run の例には --image は一切不要です。

TRLがプリインストールされたDockerイメージはhuggingface/trlで利用できます。hf jobs uv runにこれを渡すことで、ジョブはイメージのシステムレイヤー（CUDAツールチェーンなど）を取得します。これは、そのツールチェーンに対してコンパイルされる依存関係において重要です。

bash

python

イメージにインストールされているTRLを実行するには、代わりにhf jobs runを使用してください。このコマンドはスクリプトヘッダーの解決なしにイメージ内でコマンドを直接実行するため、イメージ自身に搭載されたTRLが実行されます。--はコマンドとJobsのオプションを区切るために使用され、コマンド自体がオプションを受け取る場合は常に必要です。

bash

python

イメージは3種類のタグで公開されます:

タグ	目次
`X.Y.Z`	そのバージョンのリリース時にビルドされた、そのバージョンのTRLリリース
`latest`	最新のリリース
`dev`	すべてのマージ時に再構築される`main`ブランチ

開発版を実行するにはdevを使用します。mainにマージされたがまだリリースされていない修正を試す際に便利です。

bash

python

タグはイメージにインストールされる内容のみを選択するため、hf jobs run には影響します。一方、hf jobs uv run ではバージョンはスクリプトのヘッダーから取得されるため、どの TRL がインポートされるかはタグによって変わりません。

両方を組み合わせ、uvがスクリプトヘッダーを解決する一方で一部のインポートがイメージから提供されるようにするには、追加のフラグが必要です。その形式と必要なパスについては、イメージのパッケージを再利用し、UVで依存関係を追加するを参照してください。

Jobs は Hugging Face Spaces または Docker Hub の Docker イメージで実行されるため、カスタムイメージを指定することもできます:

bash

python

TRL Jobsラッパーは、一部のモデルにプリセットされた設定でJobs上でTRLスクリプトを起動します。例えば、trl-jobs sft --model_name Qwen/Qwen3-0.6B --dataset_name trl-lib/Capybaraのように使用できます。

Update on GitHub