翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# フックを登録するためにトレーニングスクリプトを適応させる
<a name="debugger-modify-script"></a>

Amazon SageMaker Debugger には [`sagemaker-debugger` Python SDK](https://sagemaker-debugger.readthedocs.io/en/website) と呼ばれるクライアントライブラリが付属しています。`sagemaker-debugger` Python SDK には、トレーニング前にトレーニングスクリプトを調整するためのツールと、トレーニング後に分析ツールを提供します。このページでは、クライアントライブラリを使用してトレーニングスクリプトを適合させる方法について説明します。

`sagemaker-debugger` Python SDK には、トレーニングスクリプトの変更することなく、モデルテンソルを抽出するフックの登録に役立つラッパー関数が用意されています。モデル出力テンソルを収集を開始し、デバッグしてトレーニングの問題を見つけるには、トレーニングスクリプトに次の変更を加えます。

**ヒント**  
このページでは、API リファレンス用の「[`sagemaker-debugger` open source SDK documentation](https://sagemaker-debugger.readthedocs.io/en/website/index.html)」を使用してください。

**Topics**
+ [PyTorch トレーニングスクリプトを適合させる](debugger-modify-script-pytorch.md)
+ [TensorFlow トレーニングスクリプトを適応させる](debugger-modify-script-tensorflow.md)

# PyTorch トレーニングスクリプトを適合させる
<a name="debugger-modify-script-pytorch"></a>

モデル出力テンソルを収集を開始し、トレーニングの問題をデバッグするには、PyTorch トレーニングスクリプトに次の変更を加えます。

**注記**  
SageMaker Debugger は、[https://pytorch.org/docs/stable/nn.functional.html](https://pytorch.org/docs/stable/nn.functional.html) API オペレーションからモデル出力テンソルを収集できません。PyTorch トレーニングスクリプトを記述する場合は、代わりに [https://pytorch.org/docs/stable/generated/torch.nn.NLLLoss.html](https://pytorch.org/docs/stable/generated/torch.nn.NLLLoss.html) モジュールを使用することをお勧めします。

## PyTorch 1.12.0 の場合
<a name="debugger-modify-script-pytorch-1-12-0"></a>

PyTorch トレーニングスクリプトを持ち込んだ場合、トレーニングスクリプトに数行のコードを追加するだけで、トレーニングジョブを実行し、モデル出力テンソルを抽出できます。`sagemaker-debugger` クライアントライブラリの「[ フック API](https://sagemaker-debugger.readthedocs.io/en/website/hook-api.html)」を使用する必要があります。以下の説明では、コード例を使って各ステップごとに説明します。

1. フックを作成します。

   **(推奨) SageMaker AI 内でのトレーニングジョブの場合**

   ```
   import smdebug.pytorch as smd
   hook=smd.get_hook(create_if_not_exists=True)
   ```

   [SageMaker Python SDK を使用して Debugger でトレーニングジョブを開始する](debugger-configuration-for-debugging.md) で DebuggerHookConfig、TensorBoardConfig、またはルールのいずれかを推定器に組み込んでトレーニングジョブを起動すると、SageMaker AI は `get_hook` 関数によって取得される JSON 設定ファイルをトレーニングインスタンスに追加します。推定器に設定 API が含まれていない場合、フックで検索できる設定ファイルは存在せず、関数は `None` を返すことに注意してください。

   **(オプション) SageMaker AI 以外のトレーニングジョブの場合**

   ローカルモードでトレーニングジョブを実行する際に、SageMaker Notebook インスタンス、Amazon EC2 インスタンス、または独自のローカルデバイス上で直接実行する場合は、`smd.Hook` クラスを使用してフックを作成します。ただし、この方法ではテンソルコレクションの保存のみ可能で、TensorBoard の可視化に使用できます。SageMaker デバッガーのビルトインルールはローカルモードでは動作しません。ルールには SageMaker AI ML トレーニングインスタンスとリモートインスタンスからの出力をリアルタイムで保存する S3 が必要だからです。この場合 `smd.get_hook` API は `None` を返します。

   ローカルモードでテンソルを保存する手動フックを作成する場合は、以下のコードスニペットとロジックを使用して `smd.get_hook` API が `None` を戻すかどうかを確認し、`smd.Hook` クラスを使用して手動フックを作成します。ローカルマシンの任意の出力ディレクトリを指定できることに注意してください。

   ```
   import smdebug.pytorch as smd
   hook=smd.get_hook(create_if_not_exists=True)
   
   if hook is None:
       hook=smd.Hook(
           out_dir='/path/to/your/local/output/',
           export_tensorboard=True
       )
   ```

1. フックのクラスメソッドでモデルをラップします。

   この `hook.register_module()` メソッドはモデルを取得して各レイヤーを繰り返し処理し、[SageMaker Python SDK を使用して Debugger でトレーニングジョブを開始する](debugger-configuration-for-debugging.md) の設定で指定した正規表現と一致するテンソルを検索します。このフックメソッドで収集できるテンソルは、重み、バイアス、アクティベーション、グラデーション、入力、出力です。

   ```
   hook.register_module(model)
   ```
**ヒント**  
大規模なディープラーニングモデルから出力テンソル全体を収集すると、それらのコレクションの合計サイズが指数関数的に大きくなり、ボトルネックの原因になる可能性があります。特定のテンソルを保存したい場合は、`hook.save_tensor()` メソッドを使用することもできます。このメソッドは、特定のテンソルの変数を選択し、必要な名前を付けたカスタムコレクションに保存するのに役立ちます。詳細については、この手順の「[ステップ 7](#debugger-modify-script-pytorch-save-custom-tensor)」を参照してください。

1. 損失関数をフックのクラスメソッドでワープします。

   `hook.register_loss` メソッドは損失関数をラップします。[SageMaker Python SDK を使用して Debugger でトレーニングジョブを開始する](debugger-configuration-for-debugging.md) で設定する `save_interval` ごとに損失値を抽出し、`"losses"` コレクションに保存します。

   ```
   hook.register_loss(loss_function)
   ```

1. トレインブロックに `hook.set_mode(ModeKeys.TRAIN)` を追加します。これは、テンソルコレクションがトレーニングフェーズ中に抽出されることを示しています。

   ```
   def train():
       ...
       hook.set_mode(ModeKeys.TRAIN)
   ```

1. 検証ブロックを `hook.set_mode(ModeKeys.EVAL)` に追加します。これは、テンソルコレクションがト検証フェーズ中に抽出されることを示しています。

   ```
   def validation():
       ...
       hook.set_mode(ModeKeys.EVAL)
   ```

1. カスタムスカラーを保存するには [https://sagemaker-debugger.readthedocs.io/en/website/hook-constructor.html#smdebug.core.hook.BaseHook.save_scalar](https://sagemaker-debugger.readthedocs.io/en/website/hook-constructor.html#smdebug.core.hook.BaseHook.save_scalar) を使用します。モデルにないスカラー値を保存できます。例えば、評価中に計算された精度の値を記録したい場合は、精度を計算する行の下に次のコード行を追加します。

   ```
   hook.save_scalar("accuracy", accuracy)
   ```

   カスタムスカラーコレクションに名前を付けるには、最初の引数に文字列を指定する必要があります。これは TensorBoard のスカラー値を視覚化するために使用される名前で、任意の文字列を指定することができます。

1. <a name="debugger-modify-script-pytorch-save-custom-tensor"></a>カスタムテンソルを保存するには [https://sagemaker-debugger.readthedocs.io/en/website/hook-constructor.html#smdebug.core.hook.BaseHook.save_tensor](https://sagemaker-debugger.readthedocs.io/en/website/hook-constructor.html#smdebug.core.hook.BaseHook.save_tensor) を使用します。[https://sagemaker-debugger.readthedocs.io/en/website/hook-constructor.html#smdebug.core.hook.BaseHook.save_scalar](https://sagemaker-debugger.readthedocs.io/en/website/hook-constructor.html#smdebug.core.hook.BaseHook.save_scalar) と同様に、独自のテンソルコレクションを定義して、追加のテンソルを保存できます。例えば、モデルに渡された入力画像データを抽出し、カスタムテンソルとして保存するには、次のコード行 (`"images"` はカスタムテンソルの名前の例、`image_inputs` は入力画像データの変数の例) を追加します。

   ```
   hook.save_tensor("images", image_inputs)
   ```

   カスタムテンソルの名前を付けるには、最初の引数に文字列を指定する必要があることに注意してください。`hook.save_tensor()` には、カスタムテンソルを保存するテンソルコレクションを指定するための 3 番目の引数 `collections_to_write` があります。デフォルトは `collections_to_write="default"` です。3 番目の引数を明示的に指定しない場合、カスタムテンソルは `"default"` テンソルコレクションに保存されます。

トレーニングスクリプトの調整が完了したら、[SageMaker Python SDK を使用して Debugger でトレーニングジョブを開始する](debugger-configuration-for-debugging.md) に進みます。

# TensorFlow トレーニングスクリプトを適応させる
<a name="debugger-modify-script-tensorflow"></a>

モデル出力テンソルを収集を開始し、トレーニングの問題をデバッグするには、TensorFlow トレーニングスクリプトに次の変更を加えます。

**SageMaker AI 内でジョブをトレーニングするためのフックを作成する**

```
import smdebug.tensorflow as smd

hook=smd.get_hook(hook_type="keras", create_if_not_exists=True)
```

これにより、SageMaker トレーニングジョブを開始するときにフックが作成されます。[SageMaker Python SDK を使用して Debugger でトレーニングジョブを開始する](debugger-configuration-for-debugging.md) で任意の `DebuggerHookConfig`、`TensorBoardConfig`、または `Rules` のいずれかを推定器に組み込んでトレーニングジョブを起動すると、SageMaker AI は `smd.get_hook` メソッドよって取得される JSON 設定ファイルをトレーニングインスタンスに追加します。推定器に設定 API が含まれていない場合、フックで検索できる設定ファイルは存在せず、関数は `None` を返すことに注意してください。

**(オプション) SageMaker AI 以外のジョブをトレーニングするためのフックを作成する**

ローカルモードでトレーニングジョブを実行する際に、SageMaker Notebook インスタンス、Amazon EC2 インスタンス、または独自のローカルデバイス上で直接実行する場合は、`smd.Hook` クラスを使用してフックを作成します。ただし、この方法ではテンソルコレクションの保存のみ可能で、TensorBoard の可視化に使用できます。SageMaker デバッガのビルトインルールはローカルモードでは動作しません。この場合も `smd.get_hook` メソッドは `None` を返します。

手動フックを作成する場合は、以下のコードスニペットとロジックを使用してフックが `None` を返すかどうかを確認し、`smd.Hook` クラスを使用して手動フックを作成します。

```
import smdebug.tensorflow as smd

hook=smd.get_hook(hook_type="keras", create_if_not_exists=True) 

if hook is None:
    hook=smd.KerasHook(
        out_dir='/path/to/your/local/output/',
        export_tensorboard=True
    )
```

フック作成コードを追加したら、次の TensorFlow Keras のトピックに進みます。

**注記**  
SageMaker デバッガーは現在、TensorFlow Keras のみをサポートしています。

## TensorFlow Keras トレーニングスクリプトにフックを登録する
<a name="debugger-modify-script-tensorflow-keras"></a>

以下の手順では、フックとそのメソッドを使用して、モデルとオプティマイザから出力スカラーとテンソルを収集する方法を説明します。

1. フックのクラスメソッドで Keras モデルとオプティマイザをラップします。

   `hook.register_model()` メソッドはモデルを取得して各レイヤーを繰り返し処理し、「[SageMaker Python SDK を使用して Debugger でトレーニングジョブを開始する](debugger-configuration-for-debugging.md)」の設定で指定した正規表現と一致するテンソルを検索します。このフックメソッドで収集できるテンソルは、重み、バイアス、アクティベーションです。

   ```
   model=tf.keras.Model(...)
   hook.register_model(model)
   ```

1. オプティマイザを `hook.wrap_optimizer()` メソッドでラップします。

   ```
   optimizer=tf.keras.optimizers.Adam(...)
   optimizer=hook.wrap_optimizer(optimizer)
   ```

1. TensorFlow の eager モードでモデルをコンパイルします。

   各レイヤーの入出力テンソルなどのテンソルをモデルから収集するには、eager モードでトレーニングを実行する必要があります。そうでない場合は、SageMaker AI Debugger はテンソルを収集できなくなります。ただし、モデルの重み、バイアス、損失などの他のテンソルは、明示的に eager モードで実行しなくても収集できます。

   ```
   model.compile(
       loss="categorical_crossentropy", 
       optimizer=optimizer, 
       metrics=["accuracy"],
       # Required for collecting tensors of each layer
       run_eagerly=True
   )
   ```

1. フックを [https://www.tensorflow.org/api_docs/python/tf/keras/Model#fit](https://www.tensorflow.org/api_docs/python/tf/keras/Model#fit) メソッドに登録します。

   登録したフックからテンソルを収集するには、Keras `model.fit()` クラスメソッドに `callbacks=[hook]` を追加します。これにより、`sagemaker-debugger` フックが Keras コールバックとして渡されます。

   ```
   model.fit(
       X_train, Y_train,
       batch_size=batch_size,
       epochs=epoch,
       validation_data=(X_valid, Y_valid),
       shuffle=True, 
       callbacks=[hook]
   )
   ```

1. TensorFlow 2.x は、シンボリックな勾配変数しか提供されておらず、その値にアクセスすることはできません。勾配を収集するには、[https://sagemaker-debugger.readthedocs.io/en/website/hook-methods.html#tensorflow-specific-hook-api](https://sagemaker-debugger.readthedocs.io/en/website/hook-methods.html#tensorflow-specific-hook-api) メソッドで `tf.GradientTape` をラップします。そのためには、次のように独自のトレーニングステップを記述する必要があります。

   ```
   def training_step(model, dataset):
       with hook.wrap_tape(tf.GradientTape()) as tape:
           pred=model(data)
           loss_value=loss_fn(labels, pred)
       grads=tape.gradient(loss_value, model.trainable_variables)
       optimizer.apply_gradients(zip(grads, model.trainable_variables))
   ```

   テープをラップすることで、`sagemaker-debugger` フックは勾配、パラメータ、損失などの出力テンソルを識別できます。テープをラップすると `push_tape()`、`pop_tape()`、`gradient()` などのテープオブジェクトの関数を中心とした `hook.wrap_tape()` メソッドが SageMaker Debugger のライターを設定し、`gradient()` の入力 (トレーニング可能な変数と損失) および `gradient()` の出力 (勾配) として提供されるテンソルを保存するようになります。
**注記**  
カスタムトレーニングループで収集するには、必ず Eager モードを使用してください。そうでない場合は、SageMaker Debugger はテンソルを収集できなくなります。

`sagemaker-debugger` フック API が提供する、フックの構築やテンソルを保存するためのアクションの完全なリストについては、「`sagemaker-debugger` Python SDK ドキュメント」の「[Hook Methods](https://sagemaker-debugger.readthedocs.io/en/website/hook-methods.html)」を参照してください。

トレーニングスクリプトの調整が完了したら、[SageMaker Python SDK を使用して Debugger でトレーニングジョブを開始する](debugger-configuration-for-debugging.md) に進みます。