Hugging Face Transformers - Weights & Biases Documentation

Hugging Face Transformers ライブラリを使用すると、BERT のような NLP モデルや、混合精度、gradient checkpointing などのトレーニング手法を簡単に利用できます。W&B インテグレーションを使うと、一元管理ダッシュボードで実験管理とモデルのバージョン管理を行えます。このガイドでは、Hugging Face の Trainer を W&B に接続する方法を説明します。これにより、トレーニング Runs のメトリクス、モデルチェックポイント、評価出力が一元管理ダッシュボードに自動的にログされます。最後には、Runs を比較し、モデルチェックポイントを W&B Artifacts に保存してそこから再読み込みし、独自のワークフローに合わせてログをカスタマイズできるようになります。このガイドでは、Hugging Face Transformers の Trainer を使用したモデルのトレーニングにすでに慣れていることを前提としています。

クイックスタート

os.environ["WANDB_PROJECT"] = "<my-project-name>"  # W&B のプロジェクト に名前を付ける
os.environ["WANDB_LOG_MODEL"] = "checkpoint"  # すべてのモデル チェックポイントをログする

from transformers import TrainingArguments, Trainer

args = TrainingArguments(..., report_to="wandb")  # W&B ログを有効にする
trainer = Trainer(..., args=args)

すぐに使えるコードを見たい場合は、こちらのGoogle Colabをご覧ください。

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

このセクションでは、W&B への認証、クライアントライブラリのインストール、project 名の設定、および Trainer でのログの有効化について説明します。これにより、最初のトレーニング run が W&B Dashboard に表示されるようになります。 APIキーは、お使いのマシンをW&Bに認証するために使用します。APIキーはユーザープロフィールから発行できます。

より手早く行うには、User Settings にアクセスしてAPIキーを作成してください。APIキーはすぐにコピーし、パスワードマネージャーなどの安全な場所に保存してください。

右上にあるユーザープロフィールアイコンをクリックします。
User Settings を選択し、API Keys セクションまでスクロールします。

`wandb` ライブラリをインストールしてログインする

wandb ライブラリをローカルにインストールしてログインするには、以下の手順に従います。

コマンドライン
Python
Python ノートブック

WANDB_API_KEY 環境変数に APIキーを設定します。<> で囲まれた値は、ご自身の値に置き換えてください。
export WANDB_API_KEY=<your_api_key>
wandb ライブラリをインストールし、ログインします。
pip install wandb wandb login

pip install wandb

import wandb
wandb.login()

!pip install wandb

import wandb
wandb.login()

W&B を初めて使用する場合は、クイックスタートを確認してください。

プロジェクトに名前を付ける

W&B のプロジェクトは、関連する run からログされたすべてのチャート、データ、モデルを保存する場所です。プロジェクトに名前を付けることで、作業を整理しやすくなり、1 つのプロジェクトに関するすべての情報を 1 か所にまとめられます。 run をプロジェクトに追加するには、WANDB_PROJECT 環境変数にプロジェクト名を設定します。WandbCallback はこの環境変数からプロジェクト名を取得し、run の設定時に使用します。

コマンドライン
Python
Python ノートブック

WANDB_PROJECT=amazon_sentiment_analysis

import os
os.environ["WANDB_PROJECT"]="amazon_sentiment_analysis"

%env WANDB_PROJECT=amazon_sentiment_analysis

Trainer を初期化する_前に_、必ずプロジェクト名を設定してください。

プロジェクト名を指定しない場合、デフォルトのプロジェクト名は huggingface になります。

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

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

コマンドライン
Python

python run_glue.py \     # Python スクリプトを実行
  --report_to wandb \    # W&B へログすることを有効化
  --run_name bert-base-high-lr \   # W&B の run 名（任意）
  # ここに他のコマンドライン引数を指定

from transformers import TrainingArguments, Trainer

args = TrainingArguments(
    # ここに他の引数と kwargs を指定
    report_to="wandb",  # W&B へログすることを有効化
    run_name="bert-base-high-lr",  # W&B の run 名（任意）
    logging_steps=1,  # W&B にログする頻度
)

trainer = Trainer(
    # ここに他の引数と kwargs を指定
    args=args,  # トレーニング引数
)

trainer.train()  # トレーニングを開始し、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: モデルをアップロードしません。

コマンドライン
Python
Python ノートブック

WANDB_LOG_MODEL="checkpoint"

import os

os.environ["WANDB_LOG_MODEL"] = "checkpoint"

%env WANDB_LOG_MODEL="checkpoint"

これ以降に初期化するすべての 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} として保存されます。

W&B Registry

チェックポイントをArtifactsにログしたら、Registry を使って最良のモデルチェックポイントを登録し、チーム全体で一元管理できます。Registry を使うと、最良のモデルをタスクごとに整理し、モデルのライフサイクルを管理し、ML ライフサイクル全体をトラッキングおよび監査し、後続のアクションを自動化できます。モデル Artifact をリンクする方法については、Registry を参照してください。

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

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

W&B run を終了する (notebook のみ)

トレーニングを Python スクリプト内で実行している場合、W&B run はスクリプトの終了とともに終了します。 Jupyter または Google Colab のノートブックを使用している場合は、run.finish() を呼び出して、トレーニングが完了したことを W&B に伝えます。

run = wandb.init()
trainer.train()  # トレーニングを開始し、W&B にログする

# トレーニング後の分析、テスト、その他のログ対象コード

run.finish()

結果を可視化する

トレーニング結果をログしたら、W&B Dashboard で確認できます。run を比較したり、結果の詳細を拡大して確認したり、インタラクティブな可視化でデータを探索したりできます。ここまでで、インテグレーションは動作する状態になっています。Trainer はメトリクスを名前付きの project にログし、必要に応じてチェックポイントを Artifacts に保存し、評価の出力を W&B Dashboard で確認できるようにします。

高度な機能と FAQ

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

最良のモデルを保存する

Trainer に load_best_model_at_end=True を含む TrainingArguments を渡すと、W&B は最も性能の高いモデルチェックポイントを Artifacts に保存します。モデルチェックポイントを Artifacts として保存した場合は、Registry に昇格できます。Registry では、次のことができます。

ML タスクごとに最良のモデルバージョンを整理する。
モデルを一元管理し、チームと共有する。
モデルを本番向けにステージングしたり、追加の評価のためにブックマークしたりする。
後続の CI/CD プロセスをトリガーする。

保存したモデルを読み込む

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

# 新しい run を作成する
with wandb.init(project="amazon_sentiment_analysis") as run:
    # Artifact の名前とバージョンを渡す
    my_model_name = "model-bert-base-high-lr:latest"
    my_model_artifact = run.use_artifact(my_model_name)

    # モデルの重みをフォルダにダウンロードしてパスを返す
    model_dir = my_model_artifact.download()

    # 同じモデルクラスを使って、そのフォルダから
    #  Hugging Face モデルを読み込む
    model = AutoModelForSequenceClassification.from_pretrained(
        model_dir, num_labels=num_labels
    )

    # 追加のトレーニングを行うか、推論を実行する

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

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

last_run_id = "xxxxxxxx"  # fetch the run_id from your wandb workspace

# resume the wandb run from the run_id
with wandb.init(
    project=os.environ["WANDB_PROJECT"],
    id=last_run_id,
    resume="must",
) as run:
    # Connect an Artifact to the run
    my_checkpoint_name = f"checkpoint-{last_run_id}:latest"
    my_checkpoint_artifact = run.use_artifact(my_checkpoint_name)

    # Download checkpoint to a folder and return the path
    checkpoint_dir = my_checkpoint_artifact.download()

    # reinitialize your model and trainer
    model = AutoModelForSequenceClassification.from_pretrained(
        "<model-name>", num_labels=num_labels
    )
    # your training arguments here.
    training_args = TrainingArguments()

    trainer = Trainer(model=model, args=training_args)

    # make sure use the checkpoint dir to resume training from the checkpoint
    trainer.train(resume_from_checkpoint=checkpoint_dir)

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

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

# Trainer を通常通りインスタンス化する
trainer = Trainer()

# 新しいログコールバックをインスタンス化し、Trainer オブジェクトを渡す
evals_callback = WandbEvalsCallback(trainer, tokenizer, ...)

# コールバックを Trainer に追加する
trainer.add_callback(evals_callback)

# Trainer のトレーニングを通常通り開始する
trainer.train()

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

次のセクションでは、WandbCallback をカスタマイズして、トレーニング中にモデルの予測を実行し、評価サンプルを W&B 表にログする方法を示します。これは、Trainer のコールバックの on_evaluate メソッドを使って、eval_steps ごとに実行されます。 decode_predictions function は、トークナイザーを使用してモデル出力から予測とラベルをデコードします。次に、コードは予測とラベルから pandas DataFrame を作成し、DataFrame に epoch 列を追加します。最後に、コードは DataFrame から wandb.Table を作成し、それを W&B にログします。freq エポックごとに予測をログすることで、ログする頻度を制御できます。

通常の WandbCallback とは異なり、このカスタムコールバックは、Trainer の初期化時ではなく、Trainer をインスタンス化した後に trainer に追加する必要があります。これは、初期化時に Trainer インスタンスがコールバックに渡されるためです。

from transformers.integrations import WandbCallback
import pandas as pd


def decode_predictions(tokenizer, predictions):
    labels = tokenizer.batch_decode(predictions.label_ids)
    logits = predictions.predictions.argmax(axis=-1)
    prediction_text = tokenizer.batch_decode(logits)
    return {"labels": labels, "predictions": prediction_text}


class WandbPredictionProgressCallback(WandbCallback):
    """トレーニング中にモデルの予測をログするカスタム WandbCallback。

    このコールバックは、トレーニング中の各ログステップで、モデルの予測とラベルを
    wandb.Table にログします。トレーニングの進行に伴い、モデルの予測を
    可視化することができます。

    Attributes:
        trainer (Trainer): Hugging Face の Trainer インスタンス。
        tokenizer (AutoTokenizer): モデルに関連付けられたトークナイザー。
        sample_dataset (Dataset): 予測生成に使用する検証データセットのサブセット。
        num_samples (int, optional): 予測生成のために検証データセットから
          選択するサンプル数。デフォルトは 100。
        freq (int, optional): ログの頻度。デフォルトは 2。
    """

    def __init__(self, trainer, tokenizer, val_dataset, num_samples=100, freq=2):
        """WandbPredictionProgressCallback インスタンスを初期化します。

        Args:
            trainer (Trainer): Hugging Face の Trainer インスタンス。
            tokenizer (AutoTokenizer): モデルに関連付けられた
              トークナイザー。
            val_dataset (Dataset): 検証データセット。
            num_samples (int, optional): 予測生成のために検証データセットから
              選択するサンプル数。
              デフォルトは 100。
            freq (int, optional): ログの頻度。デフォルトは 2。
        """
        super().__init__()
        self.trainer = trainer
        self.tokenizer = tokenizer
        self.sample_dataset = val_dataset.select(range(num_samples))
        self.freq = freq

    def on_evaluate(self, args, state, control, **kwargs):
        super().on_evaluate(args, state, control, **kwargs)
        # `freq` エポックごとに予測をログすることで、ログの頻度を制御する
        if state.epoch % self.freq == 0:
            # 予測を生成する
            predictions = self.trainer.predict(self.sample_dataset)
            # 予測とラベルをデコードする
            predictions = decode_predictions(self.tokenizer, predictions)
            # 予測を wandb.Table に追加する
            predictions_df = pd.DataFrame(predictions)
            predictions_df["epoch"] = state.epoch
            records_table = self._wandb.Table(dataframe=predictions_df)
            # テーブルを wandb にログする
            self._wandb.log({"sample_predictions": records_table})


# まず、Trainer をインスタンス化する
trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=lm_datasets["train"],
    eval_dataset=lm_datasets["validation"],
)

# WandbPredictionProgressCallback をインスタンス化する
progress_callback = WandbPredictionProgressCallback(
    trainer=trainer,
    tokenizer=tokenizer,
    val_dataset=lm_dataset["validation"],
    num_samples=10,
    freq=2,
)

# コールバックを trainer に追加する
trainer.add_callback(progress_callback)

より詳しい例については、この Colab を参照してください。

追加の W&B 設定

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

環境変数	用途
`WANDB_PROJECT`	プロジェクトに名前を付けます (デフォルトは `huggingface`)
`WANDB_LOG_MODEL`	モデルチェックポイントを W&B Artifact としてログします (デフォルトは `false`) `false` (デフォルト) : モデルチェックポイントは保存しません `checkpoint`: args.save_steps ごとにチェックポイントがアップロードされます (Trainer の `TrainingArguments` で設定)。 `end`: トレーニングの終了時に最終モデルチェックポイントがアップロードされます。
`WANDB_WATCH`	モデルの gradient、parameter、またはそのどちらもログしないかを設定します。 `false` (デフォルト) : gradient や parameter はログしません `gradients`: gradient のヒストグラムをログします `all`: gradient と parameter のヒストグラムをログします
`WANDB_DISABLED`	`true` に設定すると、ログを完全に無効にします (デフォルトは `false`)
`WANDB_QUIET`	`true` に設定すると、標準出力にログされるメッセージを重大なもののみに制限します (デフォルトは `false`)
`WANDB_SILENT`	`true` に設定すると、`wandb` が出力する内容を表示しないようにします (デフォルトは `false`)

コマンドライン
ノートブック

WANDB_WATCH=all
WANDB_SILENT=true

%env WANDB_WATCH=all
%env WANDB_SILENT=true

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

Trainer が使用する WandbCallback は、Trainer の初期化時に内部で wandb.init() を呼び出します。代わりに、Trainer が初期化される前に wandb.init() を呼び出して、run を手動で設定することもできます。これにより、W&B の run 設定を完全に制御できます。以下に、init に渡す内容の例を示します。wandb.init() の詳細については、wandb.init() referenceを参照してください。

wandb.init(
    project="amazon_sentiment_analysis",
    name="bert-base-high-lr",
    tags=["baseline", "high-lr"],
    group="bert",
)

追加リソース

以下は、Transformers と W&B に関連する記事 6 本です。さらに詳しく学ぶための参考としてご覧ください。

サポートを受ける、または機能を要望する

Hugging Face W&B インテグレーションに関する問題、質問、または機能要望がある場合は、Hugging Face フォーラムのこのスレッドに投稿するか、Hugging Face のTransformers GitHub リポジトリで issue を登録してください。

​クイックスタート

​はじめに: Experiments をトラッキングする

​サインアップしてAPIキーを発行する

​wandb ライブラリをインストールしてログインする

​プロジェクトに名前を付ける

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

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

​W&B Registry

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

​W&B run を終了する (notebook のみ)

​結果を可視化する

​高度な機能と FAQ

​最良のモデルを保存する

​保存したモデルを読み込む

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

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

​トレーニング中に評価サンプルを確認する

​追加の W&B 設定

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

​追加リソース

​サポートを受ける、または機能を要望する

クイックスタート

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

サインアップしてAPIキーを発行する

`wandb` ライブラリをインストールしてログインする

プロジェクトに名前を付ける

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

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

W&B Registry

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

W&B run を終了する (notebook のみ)

結果を可視化する

高度な機能と FAQ

最良のモデルを保存する

保存したモデルを読み込む

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

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

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

追加の W&B 設定

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

追加リソース

サポートを受ける、または機能を要望する