Trainer用のユーティリティ

このページでは、Trainerで使用されるすべてのユーティリティ関数を一覧にしています。

これらの多くは、ライブラリのTrainerのコードを研究している場合にのみ有用です。

ユーティリティ

クラス transformers.EvalPrediction

パラメータ

predictions (np.ndarray) — モデルの予測値。
label_ids (np.ndarray) — 照合対象のターゲット。
inputs (np.ndarray、任意) — モデルに渡す入力データ。
losses (np.ndarray, 任意) — 評価中に計算された損失値。

評価の出力（常にラベルを含む）。メトリクスの計算に使用します。

class transformers.IntervalStrategy

< source >

( valuenames = Nonemodule = Nonequalname = Nonetype = Nonestart = 1boundary = None )

transformers.enable_full_determinism

< source >

( seed: intwarn_only: bool = False )

分散学習時の再現可能な動作のためのヘルパー関数です。PyTorch については https://pytorch.org/docs/stable/notes/randomness.html を参照してください。

transformers.set_seed

< source >

( seed: intdeterministic: bool = False )

パラメータ

seed (int) — 設定するシード。
deterministic (bool、省略可、デフォルトは False) — 利用可能な場合に決定論的アルゴリズムを使用するかどうか。トレーニングが低速になる可能性があります。

random、numpy、torch（インストールされている場合）にシードを設定し、再現可能な動作を実現するためのヘルパー関数です。

transformers.torch_distributed_zero_first

< source >

( local_rank: int )

パラメータ

local_rank (int) — ローカルプロセスのランクです。

分散学習におけるすべてのプロセスが、各 local_master が何らかの処理を実行するのを待機するためのデコレーターです。

コールバックの内部構造

クラス transformers.trainer_callback.CallbackHandler

< source >

( callbacksmodelprocessing_classoptimizerlr_scheduler )

コールバックのリストを順番に呼び出すだけの内部クラスです。

Trainer 引数パーサー

クラス transformers.HfArgumentParser

< source >

( dataclass_types: typing.Union[transformers.hf_argparser.DataClassType, collections.abc.Iterable[transformers.hf_argparser.DataClassType], NoneType] = None**kwargs )

パラメータ

dataclass_types (DataClassType または Iterable[DataClassType]、省略可) — 解析された引数でインスタンスを「埋める」対象の dataclass 型、または dataclass 型のリスト。
kwargs (dict[str, Any]、省略可) — 通常どおりargparse.ArgumentParser()に渡されます。

argparse.ArgumentParser のこのサブクラスは、dataclass の型ヒントを使用して引数を生成します。

このクラスは、ネイティブのargparseと良好に連携するように設計されています。特に、初期化後にパーサーに追加の（dataclassベースでない）引数を追加すると、パース後に追加のnamespaceとして出力が返されます。オプション: サブ引数グループを作成するには、dataclass内で_argument_group_name属性を使用します。

parse_args_into_dataclasses

< source >

( args = Nonereturn_remaining_strings = Falselook_for_args_file = Trueargs_filename = Noneargs_file_flag = None ) → Tuple consisting of

パラメータ

args — 解析対象の文字列のリストです。デフォルトでは sys.argv から取得されます。(argparse.ArgumentParser と同じ)
return_remaining_strings — true の場合、残りの引数文字列のリストも返します。
look_for_args_file — true の場合、このプロセスのエントリポイントスクリプトと同じベース名を持つ“.args”ファイルを探し、その内容があればコマンドライン引数に追加します。
args_filename — None 以外の場合、前の引数で指定された“.args”ファイルの代わりに、このファイルを使用します。
args_file_flag — None 以外の場合、このフラグで指定されたコマンドライン引数からファイルを検索します。このフラグは複数回指定でき、優先順位は指定順序によって決定されます（最後に指定されたものが優先されます）。

戻り値

で構成されるタプル

イニシャライザーに渡されたのと同じ順序で、dataclass のインスタンスを返します。
該当する場合、初期化後にパーサーに追加される追加の引数（dataclass によるバックエンドを持たないもの）のための追加のネームスペース
残りの引数文字列の可能性があるリストです(argparse.ArgumentParser.parse_known_argsと同じ)。

指定された dataclass 型のインスタンスに、コマンドライン引数を解析します。

これは ArgumentParser.parse_known_args に依存しています。ドキュメントは以下を参照してください: docs.python.org/3/library/argparse.html#argparse.ArgumentParser.parse_args

parse_dict

< source >

( args: dict[str, typing.Any]allow_extra_keys: bool = False ) → Tuple consisting of

パラメータ

args (dict) — 設定値を含む dict
allow_extra_keys (bool、任意、デフォルトは False) — デフォルトは False です。False の場合、dict に解析されないキーが含まれていると例外を発生させます。

戻り値

で構成されるタプル

イニシャライザーに渡されたのと同じ順序で、dataclass のインスタンスを返します。

argparseを一切使用せず、代わりにdictを用いてdataclassの型にデータを設定する、別のヘルパーメソッドです。

parse_json_file

< source >

( json_file: str | os.PathLikeallow_extra_keys: bool = False ) → Tuple consisting of

パラメータ

json_file (str または os.PathLike) — 解析対象の JSON ファイルのファイル名
allow_extra_keys (bool、任意、デフォルトは False) — デフォルトは False です。False の場合、json ファイルに解析されないキーが含まれていると例外が発生します。

戻り値

で構成されるタプル

イニシャライザーに渡されたのと同じ順序で、dataclass のインスタンスを返します。

argparse を一切使用せず、代わりに JSON ファイルを読み込んで dataclass 型にデータを設定する、別のヘルパーメソッドです。

parse_yaml_file

< source >

( yaml_file: str | os.PathLikeallow_extra_keys: bool = False ) → Tuple consisting of

パラメータ

yaml_file (str または os.PathLike) — 解析対象の yaml ファイルのファイル名
allow_extra_keys (bool、任意、デフォルトは False) — デフォルトは False です。False の場合、json ファイルに解析されないキーが含まれていると例外が発生します。

戻り値

で構成されるタプル

イニシャライザーに渡されたのと同じ順序で、dataclass のインスタンスを返します。

argparseを一切使用せず、代わりにyamlファイルを読み込んでdataclass型に値を設定する、別のヘルパーメソッドです。

デバッグユーティリティ

class transformers.debug_utils.DebugUnderflowOverflow

< source >

( modelmax_frames_to_save = 21trace_batch_nums = Noneabort_after_batch_num = None )

パラメータ

model (nn.Module) — デバッグ対象のモデル。
max_frames_to_save (int、省略可、デフォルトは 21)— 記録するフレームの数を指定します。
trace_batch_nums(list[int], 任意、デフォルトは []) — トレースするバッチ番号を指定します（ターン検出を無効にします）。
abort_after_batch_num (`int“, optional) — 特定のバッチ番号の処理が完了した後に中断するかどうか

このデバッグクラスは、モデルのどこから非常に大きな値や非常に小さな値、さらに重要なのはnanやinfの重みおよび活性化要素が発生し始めるかを検出し、理解するのに役立ちます。

動作モードは2つあります:

アンダーフロー/オーバーフローの検出（デフォルト）
検出なしの特定バッチ絶対最小値/最大値トレース

モード1: アンダーフロー/オーバーフローの検出

アンダーフロー/オーバーフローの検出を有効にするには、モデルでオブジェクトを初期化します:

debug_overflow = DebugUnderflowOverflow(model)

その後、通常どおりトレーニングを実行します。nan または inf が重み、入力、出力のいずれかの要素で検出された場合、このモジュールは例外をスローし、max_frames_to_save フレームを出力します。各フレームは、このイベントに至るまでの

forward が実行されたクラスの、完全修飾モジュール名とクラス名
各モジュールの重み、入力、および出力の全要素の絶対的な最小値と最大値

例えば、google/mt5-small を fp16 で実行した場合の検出レポートのヘッダーと最後の数フレームが次のとおりです。

混合精度:

Detected inf/nan during batch_number=0
Last 21 forward frames:
abs min  abs max  metadata
[...]
                  encoder.block.2.layer.1.DenseReluDense.wi_0 Linear
2.17e-07 4.50e+00 weight
1.79e-06 4.65e+00 input[0]
2.68e-06 3.70e+01 output
                  encoder.block.2.layer.1.DenseReluDense.wi_1 Linear
8.08e-07 2.66e+01 weight
1.79e-06 4.65e+00 input[0]
1.27e-04 2.37e+02 output
                  encoder.block.2.layer.1.DenseReluDense.wo Linear
1.01e-06 6.44e+00 weight
0.00e+00 9.74e+03 input[0]
3.18e-04 6.27e+04 output
                  encoder.block.2.layer.1.DenseReluDense T5DenseGatedGeluDense
1.79e-06 4.65e+00 input[0]
3.18e-04 6.27e+04 output
                  encoder.block.2.layer.1.dropout Dropout
3.18e-04 6.27e+04 input[0]
0.00e+00      inf output

ここから、T5DenseGatedGeluDense.forward の出力活性化の絶対値の最大値が約 62.7K であることがわかります。これは fp16 の上限である 64K に非常に近い値です。次のフレームでは、Dropout が一部の要素をゼロにした後に重みを再正規化するため、絶対値の最大値が 64K を超え、オーバーフローが発生します。

の数値が非常に大きくなり始める場合、確認すべきは直前のフレームであることがわかります。

トラッキングはフォワードフックによって行われ、forwardの完了直後に呼び出されます。

デフォルトでは、最後の21フレームが出力されます。必要に応じて、デフォルト値を変更できます。例:

debug_overflow = DebugUnderflowOverflow(model, max_frames_to_save=100)

このデバッグ機能が正しく設定されていることを確認し、数時間かかる可能性のあるトレーニングで使用することを意図している場合、次のセクションで説明するように、まず通常トレースを有効にして数バッチ分だけ実行してください。

モード 2。検出なしの特定バッチ絶対最小値/最大値トレース

2番目のワークモードは、アンダーフロー/オーバーフロー検出機能をオフにしたバッチ単位のトレースです。

forward 呼び出しの各回における、すべての成分の絶対的な最小値と最大値を監視したいとします。

与えられたバッチに対してのみ、バッチ1と3のときにのみその処理を行います。その後、このクラスを以下のようにインスタンス化します。

debug_overflow = DebugUnderflowOverflow(model, trace_batch_nums=[1, 3])

次に、上記で説明したのと同じ形式で、フルバッチの1と3がトレースされます。バッチは0始まりのインデックスです。

プログラムが特定のバッチ番号以降に異常をきたすことがわかっている場合に有用です。その場合、該当する領域まで素早くスキップできます。

早期停止:

max_steps パラメータを指定して、トレーニングを停止するバッチ数も設定できます。

debug_overflow = DebugUnderflowOverflow(model, trace_batch_nums=[1, 3], abort_after_batch_num=3)

この機能は主にトレースモードで有用ですが、他のモードでも使用できます。

パフォーマンス:

このモジュールは、モデルの各重みの絶対的なmin/`max`を、すべてのフォワードパスで測定するため、トレーニングが低速化します。したがって、デバッグの目的が達成されたら、これをオフにすることを忘れないでください。

Update on GitHub

Transformers

Trainer用のユーティリティ

ユーティリティ

クラス transformers.EvalPrediction

class transformers.IntervalStrategy

transformers.enable_full_determinism

transformers.set_seed

transformers.torch_distributed_zero_first

コールバックの内部構造

クラス transformers.trainer_callback.CallbackHandler

Trainer 引数パーサー

クラス transformers.HfArgumentParser

parse_args_into_dataclasses

parse_dict

parse_json_file

parse_yaml_file

デバッグユーティリティ

class transformers.debug_utils.DebugUnderflowOverflow