Skip to main content
Hugging Face Transformers ライブラリは、BERT のような NLP モデルや、混合精度や勾配チェックポイントなどのトレーニング手法を簡単に使用できるようにします。W&B インテグレーション は、集中型ダッシュボードに実験管理とモデルバージョン管理を追加します。 このガイドでは、Hugging Face の Trainer を W&B に接続する方法を説明します。これにより、トレーニング run はメトリクス、モデル チェックポイント、評価出力を集中型ダッシュボードに自動的にログします。最終的に、run を比較したり、W&B Artifacts からモデル チェックポイントを保存および再読み込みしたり、独自のワークフロー用にログをカスタマイズしたりできるようになります。このガイドは、Hugging Face Transformers の Trainer を使用したモデルのトレーニングにすでに慣れていることを前提としています。

クイックスタート

Hugging Face ダッシュボード
すぐに動作するコードを試したい場合は、こちらの Google Colab をご覧ください。

はじめに: 実験をトラッキングする

このセクションでは、W&B で認証し、クライアントライブラリをインストールし、プロジェクト名を設定し、Trainer でログする機能を有効にして、最初のトレーニング run を W&B ダッシュボードに表示する方法を説明します。

登録してAPIキーを作成する

APIキーは、マシンを W&B に対して認証します。ユーザープロフィールからAPIキーを発行できます。
より簡単な方法として、User Settings に移動して APIキーを作成することもできます。作成した APIキーはすぐにコピーし、パスワードマネージャーなどの安全な場所に保存してください。
  1. 右上のユーザープロフィールアイコンをクリックします。
  2. User Settings を選択し、APIキーセクションまでスクロールします。

wandb ライブラリのインストールとログイン

wandb ライブラリをローカルにインストールしてログインするには、次の手順に従います。
  1. WANDB_API_KEY 環境変数に APIキーを設定します。<> で囲まれた値を自分の値に置き換えてください。
  2. wandb ライブラリをインストールしてログインします。
W&B を初めて使用する場合は、クイックスタートをご覧ください。

プロジェクト名を設定する

W&B プロジェクトには、関連する run からログされたすべてのチャート、データ、モデルが保存されます。プロジェクト名を設定すると、作業を整理し、1 つの project に関するすべての情報を一か所にまとめられます。 project に run を追加するには、WANDB_PROJECT 環境変数にプロジェクト名を設定します。WandbCallback は、この環境変数からプロジェクト名を取得し、run の設定時に使用します。
必ず Trainer を初期化する_前に_プロジェクト名を設定してください。
プロジェクト名を指定しない場合、デフォルトのプロジェクト名は huggingface になります。

トレーニング run を W&B にログする

コード内またはコマンドラインから Trainer のトレーニング引数を定義する際に、report_to を "wandb" に設定して、W&B へのログを有効にします。この設定がない場合、Trainer は W&B にデータを送信しません。 TrainingArguments の logging_steps 引数は、トレーニング中にトレーニングメトリクスを W&B に送信する頻度を制御します。run_name 引数を使用して、W&B のトレーニング run に名を付けることもできます。 これで完了です。モデルはトレーニング中に、損失、評価メトリクス、モデルのトポロジ、勾配を W&B にログするようになります。
TensorFlow を使用していますか?PyTorch の Trainer を TensorFlow の TFTrainer に置き換えてください。

モデル チェックポイントの保存を有効にする

メトリクスをログするだけでなく、トレーニング済みモデルの重み自体を W&B に保存して、バージョン管理、ダウンロード、チーム内での共有ができます。 Artifacts を使用すると、モデルとデータセットを最大 100 GB まで無料で保存し、W&B Registry で使用できます。Registry では、モデルを登録して調査や評価を行い、ステージングの準備をしたり、本番環境にデプロイしたりできます。 Hugging Face のモデル チェックポイントを Artifacts にログするには、WANDB_LOG_MODEL 環境変数を次のいずれか 1 つ に設定します。
  • checkpoint: TrainingArguments の args.save_steps ごとにチェックポイントをアップロードします。
  • end: load_best_model_at_end も設定されている場合、トレーニングの終了時にモデルをアップロードします。
  • false: モデルをアップロードしません。
以降に初期化するすべての Transformers Trainer は、モデルを W&B プロジェクトにアップロードします。ログしたモデル チェックポイントは Artifacts UI で確認でき、モデルの完全なリネージも含まれます。Artifacts UI のモデル チェックポイントの例をご覧ください。
デフォルトでは、WANDB_LOG_MODEL が end に設定されている場合、モデルは W&B Artifacts に model-{run_id} として保存され、WANDB_LOG_MODEL が checkpoint に設定されている場合は checkpoint-{run_id} として保存されます。 ただし、TrainingArguments に run_name を渡すと、モデルは model-{run_name} または checkpoint-{run_name} として保存されます。

Registry

チェックポイントを Artifacts にログしたら、Registry を使用して、ベストなモデル チェックポイントを登録し、チーム全体で一元管理できます。Registry では、タスクごとにベストなモデルを整理したり、モデルのライフサイクルを管理したり、ML ライフサイクル全体をトラッキングして監査したり、ダウンストリームの action をオートメーションしたりできます。 モデル アーティファクトを link するには、Registry を参照してください。

トレーニング中の評価出力を可視化する

モデルがどのようにトレーニングされているかを理解するには、トレーニング中や評価中にモデル出力を可視化することが欠かせない場合が多くあります。損失曲線と併せて具体的な予測を確認することで、集計メトリクスだけでは見落としがちな品質の問題を発見しやすくなります。 Transformers Trainer のコールバックシステムを使用すると、より有用なデータを W&B 表にログできます。たとえば、モデルのテキスト生成出力やその他の予測などです。 次のような W&B 表に、トレーニング中の評価出力をログする方法の詳しいガイドについては、トレーニング中に評価サンプルをログして表示するを参照してください。
W&B 表に評価出力が表示されている様子

W&B run を終了する (ノートブックのみ)

トレーニングが Python スクリプトにカプセル化されている場合、W&B run はスクリプトが終了したときに終了します。 Jupyter または Google Colab ノートブックを使用している場合は、run.finish() を呼び出してトレーニングが完了したことを通知します。

結果を可視化する

トレーニング結果をログしたら、W&B ダッシュボード で探索できます。run を比較したり、検出結果をズームインしたり、インタラクティブな可視化でデータを探索できます。 この時点で、動作するインテグレーションが完成しています。Trainer はメトリクスを指定した project にログし、オプションでチェックポイントを Artifacts に保存し、評価出力を W&B ダッシュボードに表示します。

高度な機能とよくある質問

以下のセクションでは、最良のモデルの保存、チェックポイントからのトレーニングの再開、ログするためのコールバックのカスタマイズ、環境変数による W&B の動作の設定など、一般的な追加タスクについて説明します。

最良のモデルを保存する

load_best_model_at_end=True を指定した TrainingArguments を Trainer に渡すと、W&B は最も性能の高いモデル チェックポイントを Artifacts に保存します。 モデル チェックポイントをアーティファクトとして保存すると、Registry にプロモートできます。Registry では、次の操作ができます。
  • 最良のモデルのバージョンを ML タスク別に整理します。
  • モデルを一元管理し、チームと共有します。
  • モデルを本番向けにステージングするか、追加の評価に備えてブックマークします。
  • 後続の CI/CD プロセスをトリガーします。

保存済みのモデルをロードする

WANDB_LOG_MODEL を使用してモデルを W&B Artifacts に保存した場合は、モデルの重みをダウンロードして、追加のトレーニングや推論に使用できます。ダウンロードした重みは、以前使用したものと同じ Hugging Face アーキテクチャにロードしてください。

チェックポイントからトレーニングを再開する

WANDB_LOG_MODEL='checkpoint' を設定している場合は、TrainingArguments の model_name_or_path 引数に model_dir を指定し、Trainer に resume_from_checkpoint=True を渡すことで、トレーニングを再開できます。

トレーニング中に評価サンプルをログして表示する

Transformers ライブラリの WandbCallback は、Transformers の Trainer を通じて W&B にログする処理を担います。このコールバックをカスタマイズして、モデルの予測、混同行列、その他のカスタムデータをログできます。そのためには、WandbCallback をサブクラス化し、Trainer クラスの追加メソッドを使用する機能を追加します。 以下では、この新しいコールバックを Hugging Face Trainer に追加するための一般的なパターンを示し、その後に評価出力を W&B 表にログするための完全なコード例を示します。

トレーニング中に評価サンプルを表示する

次のセクションでは、WandbCallback をカスタマイズして、トレーニング中にモデルの予測を実行し、評価サンプルを W&B 表にログする方法を説明します。これは、Trainer コールバックの on_evaluate メソッドを使用して、eval_steps ごとに実行されます。 decode_predictions 関数は、トークナイザーを使用してモデル出力から予測とラベルをデコードします。 次に、コードは予測とラベルから pandas データフレームを作成し、データフレームに epoch 列を追加します。 最後に、コードはデータフレームから wandb.Table を作成し、W&B にログします。freq エポックごとに予測をログすることで、ログする頻度を制御できます。
通常の WandbCallback とは異なり、このカスタムコールバックは、Trainer の初期化中ではなく、Trainer がインスタンス化された後にトレーナーに追加する必要があります。これは、初期化中に Trainer インスタンスがコールバックに渡されるためです。
より詳しい例については、こちらの Colab を参照してください。

その他の W&B 設定

環境変数を設定すると、Trainer でログする内容をさらに細かく設定できます。W&B の環境変数の一覧については、環境変数リファレンスを参照してください。

wandb.init() をカスタマイズする

Trainer が使用する WandbCallback は、Trainer の初期化時に wandb.init() を内部で呼び出します。あるいは、Trainer が初期化される前に wandb.init() を呼び出すことで、run を手動で設定することもできます。これにより、W&B run 設定に対してフルコントロールが得られます。 以下は、init に渡すことができる例です。wandb.init() の詳細については、wandb.init() リファレンス を参照してください。

追加リソース

TransformersとW&Bに関連する記事を6つ紹介します。さらに詳しく知りたい方は、以下をご覧ください。

ヘルプを得る、または機能をリクエストする

Hugging Face の W&B インテグレーションに関する問題、質問、機能のリクエストがある場合は、Hugging Face フォーラムのこちらのスレッドに投稿するか、Hugging Face の Transformers GitHub repoで issue を作成してください。
最終更新日 2026年9月30日