Hugging Face Transformers - Weights & Biases Documentation

Hugging Face Transformers ライブラリを使用すると、BERT のような最先端の NLP モデルや、混合精度、gradient checkpointing などのトレーニング手法を簡単に利用できます。W&B インテグレーションを使うと、その使いやすさはそのままに、インタラクティブな一元管理ダッシュボードで、充実した柔軟な実験管理とモデルのバージョン管理を行えます。

数行でできるワンランク上のログする

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

from transformers import TrainingArguments, Trainer

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

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

はじめに: 実験を管理する

APIキーは、お使いのマシンをW&Bに認証するために使用します。APIキーはユーザープロフィールから発行できます。

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

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

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

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

コマンドライン
Python
Python notebook

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 notebook

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" に設定することです。 TrainingArguments の logging_steps 引数では、トレーニング中のメトリクスをどのくらいの頻度で W&B に送信するかを制御します。また、run_name 引数を使って、W&B 上のトレーニング run に名前を付けることもできます。以上です。これで、モデルはトレーニング中に損失、評価メトリクス、モデルのトポロジー、勾配を W&B にログするようになります。

コマンドライン
Python

python run_glue.py \     # Python スクリプトを実行
  --report_to wandb \    # W&amp;B へログすることを有効化
  --run_name bert-base-high-lr \   # W&amp;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 に置き換えるだけです。

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

Artifacts を使用すると、最大 100GB までのモデルとデータセットを無料で保存でき、さらに 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 で確認でき、完全なモデルリネージが含まれます (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 表にログできます。トレーニング中に評価出力をログし、このような 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 ダッシュボードで結果をインタラクティブに確認できます。数十件のrunを一度に簡単に比較し、興味深い発見を拡大して詳しく見たり、柔軟でインタラクティブな可視化によって複雑なデータからインサイトを引き出したりできます。

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

最良のモデルを保存するにはどうすればよいですか

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"  # wandb workspace から run_id を取得する

# run_id から wandb の run を再開する
with wandb.init(
    project=os.environ["WANDB_PROJECT"],
    id=last_run_id,
    resume="must",
) as run:
    # run に Artifact を接続する
    my_checkpoint_name = f"checkpoint-{last_run_id}:latest"
    my_checkpoint_artifact = run.use_artifact(my_model_name)

    # チェックポイントをフォルダにダウンロードしてパスを返す
    checkpoint_dir = my_checkpoint_artifact.download()

    # モデルと trainer を再初期化する
    model = AutoModelForSequenceClassification.from_pretrained(
        "<model_name>", num_labels=num_labels
    )
    # トレーニング引数をここに記述する
    training_args = TrainingArguments()

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

    # チェックポイントからトレーニングを再開するために、チェックポイントディレクトリを使用すること
    trainer.train(resume_from_checkpoint=checkpoint_dir)

トレーニング中に評価サンプルをログして表示するにはどうすればよいですか

Transformers の Trainer 経由で W&B にログする処理は、Transformers ライブラリの WandbCallback が担います。Hugging Face のログすることをカスタマイズする必要がある場合は、WandbCallback をサブクラス化し、Trainer クラスの追加の method を活用する機能を加えることで、このコールバックを拡張できます。以下に、この新しいコールバックを HF 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 method を使って、eval_steps ごとに実行します。ここでは、トークナイザーを使用してモデル出力から予測とラベルをデコードする decode_predictions function を作成しています。次に、予測とラベルから pandas DataFrame を作成し、DataFrame に epoch 列を追加します。最後に、DataFrame から wandb.Table を作成し、それを wandb にログします。また、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 を登録してください。

​数行でできるワンランク上のログする

​はじめに: 実験を管理する

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

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

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

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

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

​W&B Registry

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

​W&B Run を終了する (Notebook のみ)

​結果を可視化する

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

​最良のモデルを保存するにはどうすればよいですか

​保存したモデルを読み込むにはどうすればよいですか？

​チェックポイントからトレーニングを再開するにはどうすればよいですか？

​トレーニング中に評価サンプルをログして表示するにはどうすればよいですか

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

​利用可能な追加の W&B 設定は何ですか？

​wandb.init() をカスタマイズするにはどうすればよいですか？

​追加リソース

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

数行でできるワンランク上のログする

はじめに: 実験を管理する

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

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

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

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

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

W&B Registry

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

W&B Run を終了する (Notebook のみ)

結果を可視化する

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

最良のモデルを保存するにはどうすればよいですか

保存したモデルを読み込むにはどうすればよいですか？

チェックポイントからトレーニングを再開するにはどうすればよいですか？

トレーニング中に評価サンプルをログして表示するにはどうすればよいですか

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

利用可能な追加の W&B 設定は何ですか？

`wandb.init()` をカスタマイズするにはどうすればよいですか？

追加リソース

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