TRL documentation

Jobsでのトレーニング

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Jobsでのトレーニング

model badge

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
hf jobs uv run \
    --flavor a10g-small \
    --timeout 30m \
    --secrets 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

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
hf jobs uv run \
    --flavor a10g-small \
    --timeout 30m \
    --secrets HF_TOKEN \
    train.py

ヘッダーのないスクリプトの場合、--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
hf jobs uv run \
    --flavor a10g-small \
    --timeout 3h \
    --secrets 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 \
    --output_dir Qwen2-0.5B-SFT \
    --push_to_hub \
    --save_steps 500 \
    --hub_strategy checkpoint

--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
hf jobs uv run \
    --flavor a10g-small \
    --timeout 3h \
    --secrets HF_TOKEN \
    --volume hf://buckets/<your-username>/checkpoints:/checkpoints \
    -- \
    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 \
    --output_dir /checkpoints/Qwen2-0.5B-SFT \
    --save_steps 500

中断された実行を再開するには、--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
hf jobs run \
    --flavor l4x4 \
    --timeout 30m \
    --secrets HF_TOKEN \
    huggingface/trl \
    -- \
    trl sft --nproc_per_node 4 \
    --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

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

ご自身のスクリプト

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

bash
python
hf jobs run \
    --flavor l4x4 \
    --timeout 30m \
    --secrets HF_TOKEN \
    --volume ./my-project:/code \
    huggingface/trl \
    -- \
    torchrun --nproc_per_node 4 /code/train_grpo.py

スクリプトはイメージに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
hf jobs uv run \
    --flavor a100-large \
    --secrets HF_TOKEN \
    --image huggingface/trl \
    train.py

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

bash
python
hf jobs run \
    --flavor a100-large \
    --secrets HF_TOKEN \
    huggingface/trl \
    -- \
    trl sft --model_name_or_path Qwen/Qwen2-0.5B-Instruct --dataset_name trl-lib/Capybara --output_dir Qwen2-0.5B-SFT

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

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

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

bash
python
hf jobs run \
    --flavor a100-large \
    --secrets HF_TOKEN \
    huggingface/trl:dev \
    -- \
    trl sft --model_name_or_path Qwen/Qwen2-0.5B-Instruct --dataset_name trl-lib/Capybara --output_dir Qwen2-0.5B-SFT

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

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

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

bash
python
hf jobs uv run \
    --flavor a100-large \
    --secrets HF_TOKEN \
    --image <docker-image> \
    train.py

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

Update on GitHub