Hugging Face Transformers

Try in Colab

Hugging Face Transformers ライブラリは、BERTのような最先端のNLPモデルや、混合精度、勾配チェックポイントなどのトレーニング手法を簡単に使用できるようにします。W&B integrationにより、その使いやすさを損なうことなく、柔軟な実験管理とモデルのバージョン管理をインタラクティブな集中ダッシュボードに追加します。

数行で次世代のロギング

os.environ["WANDB_PROJECT"] = "<my-amazing-project>"  # 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をチェックしてください。

始める： 実験をトラックする

サインアップしてAPIキーを作成する

APIキーは、あなたのマシンをW&Bに認証します。ユーザープロフィールからAPIキーを生成できます。

よりスムーズな方法として、https://wandb.ai/authorizeで直接APIキーを生成することができます。表示されたAPIキーをコピーして、パスワードマネージャーのような安全な場所に保存してください。

1. 右上のユーザーアイコンをクリックします。
2. ユーザー設定を選択し、APIキーセクションまでスクロールします。
3. Revealをクリックします。表示されたAPIキーをコピーします。APIキーを非表示にするには、ページを再読み込みします。

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

wandbライブラリをローカルにインストールし、ログインするには：

Command Line

1. WANDB_API_KEY 環境変数をAPIキーに設定します。

   export WANDB_API_KEY=<your_api_key>
   

2. wandbライブラリをインストールしてログインします。

   pip install wandb
   
   wandb login
   

Python

pip install wandb

import wandb
wandb.login()

Python notebook

!pip install wandb

import wandb
wandb.login()

初めてW&Bを使用する場合、クイックスタートをご覧になることをお勧めします。

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

W&B Projectは、関連するRunsからログされたすべてのチャート、データ、モデルを保存する場所です。プロジェクト名をつけることで、作業を整理し、1つのプロジェクトに関するすべての情報を一ヶ所にまとめることができます。

プロジェクトにrunを追加するには、単にWANDB_PROJECT 環境変数をプロジェクト名に設定するだけです。WandbCallbackは、このプロジェクト名の環境変数を拾い上げ、runを設定する際にそれを使用します。

Command Line

WANDB_PROJECT=amazon_sentiment_analysis

Python

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

Python notebook

%env WANDB_PROJECT=amazon_sentiment_analysis

プロジェクト名はTrainerを初期化する前に設定することを確認してください。

プロジェクト名が指定されていない場合、プロジェクト名はhuggingfaceにデフォルト設定されます。

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

これは、コード内またはコマンドラインからトレーニング引数を定義する際の最も重要なステップです。report_toを"wandb"に設定することで、W&Bログを有効にします。

TrainingArgumentsのlogging_steps引数は、トレーニング中にW&Bにトレーニングメトリクスがプッシュされる頻度を制御します。run_name引数を使用して、W&B内でトレーニングrunに名前を付けることもできます。

これで終了です。トレーニング中は、モデルが損失、評価メトリクス、モデルトポロジー、勾配をW&Bにログします。

Command Line

python run_glue.py \     # Pythonスクリプトを実行
  --report_to wandb \    # W&Bにログを有効化
  --run_name bert-base-high-lr \   # W&B runの名前 (オプション)
  # その他のコマンドライン引数をここに

Python

from transformers import TrainingArguments, Trainer

args = TrainingArguments(
    # 他の引数やキーワード引数をここに
    report_to="wandb",  # W&Bにログを有効化
    run_name="bert-base-high-lr",  # W&B runの名前 (オプション)
    logging_steps=1,  # W&Bにログする頻度
)

trainer = Trainer(
    # 他の引数やキーワード引数をここに
    args=args,  # トレーニング引数
)

trainer.train()  # トレーニングとW&Bへのログを開始

TensorFlowを使用していますか？ PyTorchのTrainerをTensorFlowのTFTrainerに置き換えるだけです。

モデルのチェックポイントをオンにする

Artifactsを使用すると、最大100GBのモデルやデータセットを無料で保存し、その後Weights & BiasesのRegistryを使用できます。Registryを使用して、モデルを登録し、それらを探索・評価したり、ステージングの準備をしたり、プロダクション環境にデプロイできます。

Hugging FaceモデルのチェックポイントをArtifactsにログするには、WANDB_LOG_MODEL 環境変数を以下のいずれかに設定します：

• checkpoint: TrainingArgumentsのargs.save_stepsごとにチェックポイントをアップロードします。
• end: トレーニング終了時にモデルをアップロードします。またload_best_model_at_endが設定されている場合です。
• false: モデルをアップロードしません。

Command Line

WANDB_LOG_MODEL="checkpoint"

Python

import os

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

Python notebook

%env WANDB_LOG_MODEL="checkpoint"

これ以降に初期化するすべてのTransformers Trainerは、モデルをW&Bプロジェクトにアップロードします。ログされたモデルチェックポイントはArtifacts UIを通じて表示可能で、完全なモデルリネージを含みます（UIでのモデルチェックポイントの例はこちらをご覧ください here)。

デフォルトでは、WANDB_LOG_MODELがendに設定されているときはmodel-{run_id}として、WANDB_LOG_MODELがcheckpointに設定されているときはcheckpoint-{run_id}として、モデルがW&B Artifactsに保存されます。しかし、TrainingArgumentsにrun_nameを渡すと、モデルはmodel-{run_name}またはcheckpoint-{run_name}として保存されます。

W&B Registry

チェックポイントをArtifactsにログしたら、最良のモデルチェックポイントを登録して、**Registry**でチーム全体に中央集約できます。Registryを使用すると、タスクごとに最良のモデルを整理し、モデルライフサイクルを管理し、機械学習ライフサイクル全体を追跡および監査し、オートメーションダウンストリームアクションを自動化できます。

モデルのアーティファクトをリンクするには、Registryを参照してください。

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

トレーニングや評価中にモデル出力を視覚化することは、モデルがどのようにトレーニングされているかを理解するためにしばしば重要です。

Transformers Trainerのコールバックシステムを使用すると、モデルのテキスト生成出力や他の予測などの役立つデータをW&B Tablesにログできます。

トレーニング中にW&B Tableに評価出力をログする方法については、以下の**カスタムログセクション**をご覧ください:

W&B Runを終了させる（ノートブックのみ）

トレーニングがPythonスクリプトでカプセル化されている場合、スクリプトが終了するとW&B runも終了します。

JupyterまたはGoogle Colabノートブックを使用している場合は、トレーニングが終了したことをwandb.finish()を呼び出して知らせる必要があります。

trainer.train()  # トレーニングとW&Bへのログを開始

# トレーニング後の分析、テスト、他のログ済みコード

wandb.finish()

結果を視覚化する

トレーニング結果をログしたら、W&B Dashboardで結果を動的に探索できます。複数のrunを一度に比較したり、興味深い知見にズームインしたり、柔軟でインタラクティブな可視化を用いて複雑なデータから洞察を引き出すのが簡単です。

高度な機能とFAQ

最良のモデルを保存する方法は？

Trainerにload_best_model_at_end=TrueのTrainingArgumentsを渡すと、W&Bは最良のパフォーマンスを示すモデルチェックポイントをアーティファクトに保存します。

モデルチェックポイントをアーティファクトとして保存すれば、それらをRegistryに昇格させることができます。Registryでは以下のことが可能です：

• MLタスクによって最良のモデルバージョンを整理する。
• モデルを集約してチームと共有する。
• モデルをステージングしてプロダクションに展開するか、さらに評価するためにブックマークする。
• 下流のCI/CDプロセスをトリガーする。

保存したモデルをロードするには？

WANDB_LOG_MODELでW&B Artifactsにモデルを保存した場合、追加トレーニングや推論のためにモデルウェイトをダウンロードできます。同じHugging Faceアーキテクチャーにモデルを読み戻すだけです。

# 新しいrunを作成
with wandb.init(project="amazon_sentiment_analysis") as run:
    # アーティファクトの名前とバージョンを指定
    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'を設定していた場合、model_dirをTrainingArgumentsの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に接続
    my_checkpoint_name = f"checkpoint-{last_run_id}:latest"
    my_checkpoint_artifact = run.use_artifact(my_model_name)

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

    # モデルとトレーナーを再初期化
    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クラスから追加のメソッドを利用する追加機能を追加することにより、このコールバックを変更できます。

以下は、HF Trainerにこの新しいコールバックを追加する際の一般的なパターンであり、さらに下にはW&B Tableに評価出力をログするコード完備の例があります：

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

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

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

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

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

以下のセクションでは、WandbCallbackをカスタマイズして、モデルの予測を実行し、トレーニング中にW&B Tableに評価サンプルをログする方法を示します。on_evaluateメソッドを使用してeval_stepsごとにログします。

ここでは、トークナイザーを使用してモデル出力から予測とラベルをデコードするためのdecode_predictions関数を書いています。

その後、予測とラベルからpandas DataFrameを作成し、DataFrameにepoch列を追加します。

最後に、DataFrameからwandb.Tableを作成し、それをwandbにログします。 さらに、freqエポックごとに予測をログすることで、ログの頻度を制御できます。

注意: 通常のWandbCallbackとは異なり、このカスタムコールバックは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.add_callback(progress_callback)

詳細な例については、このcolabを参照してください。

利用可能な追加のW&B設定は？

Trainerでログされる内容のさらなる設定は、環境変数を設定することで可能です。W&B環境変数の完全なリストはこちらにあります。

環境変数	使用法
WANDB_PROJECT	プロジェクト名を付けます（デフォルトはhuggingface）
WANDB_LOG_MODEL	モデルチェックポイントをW&Bアーティファクトとしてログします（デフォルトはfalse） false（デフォルト）：モデルチェックポイントは行われません checkpoint：args.save_stepsごとにチェックポイントがアップロードされます（TrainerのTrainingArgumentsで設定） end：トレーニングの終了時に最終モデルチェックポイントがアップロードされます。
WANDB_WATCH	モデルの勾配、パラメータ、またはそのいずれもログするかどうかを設定します false（デフォルト）：勾配やパラメータのログは行わない gradients：勾配のヒストグラムをログ all：勾配とパラメータのヒストグラムをログ
WANDB_DISABLED	trueに設定すると、ログが完全にオフになります（デフォルトはfalse）
WANDB_SILENT	trueに設定すると、wandbによって印刷される出力が消音されます（デフォルトはfalse）

Command Line

WANDB_WATCH=all
WANDB_SILENT=true

Notebook

%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(
    project="amazon_sentiment_analysis",
    name="bert-base-high-lr",
    tags=["baseline", "high-lr"],
    group="bert",
)

追加のリソース

以下は、6つのTransformersとW&Bに関連する記事で楽しめるかもしれないものです。

ヘルプを受けたり、機能をリクエストする

Hugging Face W&Bインテグレーションに関する問題、質問、または機能のリクエストについては、Hugging Faceフォーラムのこのスレッドに投稿するか、Hugging FaceTransformers GitHubリポジトリで問題を開いてください。