本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 SageMaker Python SDK 搭配 Debugger 啟動訓練任務
<a name="debugger-configuration-for-debugging"></a>

若要使用 SageMaker Debugger 設定 SageMaker AI 估算器，請使用 [Amazon SageMaker Python SDK](https://sagemaker.readthedocs.io/en/stable) 並指定特定 Debugger 的參數。若要充分利用除錯功能，您需要設定三個參數：`debugger_hook_config`、`tensorboard_output_config` 和 `rules`。

**重要**  
建構並執行估計器擬合方法以啟動訓練任務之前，請確定您已依照[調整您的訓練指令碼以註冊勾點](debugger-modify-script.md)中的指示調整訓練指令碼。

## 使用特定 Debugger 參數建構 SageMaker AI 估算器
<a name="debugger-configuration-structure"></a>

本節中的程式碼範例說明如何使用特定 Debugger 參數建構 SageMaker AI 估算器。

**注意**  
下列程式碼範例是建構 SageMaker AI 架構估算器的範本，不可直接執行。您必須繼續後續幾節，設定特定 Debugger 參數。

------
#### [ PyTorch ]

```
# An example of constructing a SageMaker AI PyTorch estimator
import boto3
import sagemaker
from sagemaker.pytorch import PyTorch
from sagemaker.debugger import CollectionConfig, DebuggerHookConfig, Rule, rule_configs

session=boto3.session.Session()
region=session.region_name

debugger_hook_config=DebuggerHookConfig(...)
rules=[
    Rule.sagemaker(rule_configs.built_in_rule())
]

estimator=PyTorch(
    entry_point="directory/to/your_training_script.py",
    role=sagemaker.get_execution_role(),
    base_job_name="debugger-demo",
    instance_count=1,
    instance_type="ml.p3.2xlarge",
    framework_version="1.12.0",
    py_version="py37",
    
    # Debugger-specific parameters
    debugger_hook_config=debugger_hook_config,
    rules=rules
)

estimator.fit(wait=False)
```

------
#### [ TensorFlow ]

```
# An example of constructing a SageMaker AI TensorFlow estimator
import boto3
import sagemaker
from sagemaker.tensorflow import TensorFlow
from sagemaker.debugger import CollectionConfig, DebuggerHookConfig, Rule, rule_configs

session=boto3.session.Session()
region=session.region_name

debugger_hook_config=DebuggerHookConfig(...)
rules=[
    Rule.sagemaker(rule_configs.built_in_rule()),
    ProfilerRule.sagemaker(rule_configs.BuiltInRule())
]

estimator=TensorFlow(
    entry_point="directory/to/your_training_script.py",
    role=sagemaker.get_execution_role(),
    base_job_name="debugger-demo",
    instance_count=1,
    instance_type="ml.p3.2xlarge",
    framework_version="2.9.0",
    py_version="py39",
    
    # Debugger-specific parameters
    debugger_hook_config=debugger_hook_config,
    rules=rules
)

estimator.fit(wait=False)
```

------
#### [ MXNet ]

```
# An example of constructing a SageMaker AI MXNet estimator
import sagemaker
from sagemaker.mxnet import MXNet
from sagemaker.debugger import CollectionConfig, DebuggerHookConfig, Rule, rule_configs

debugger_hook_config=DebuggerHookConfig(...)
rules=[
    Rule.sagemaker(rule_configs.built_in_rule())
]

estimator=MXNet(
    entry_point="directory/to/your_training_script.py",
    role=sagemaker.get_execution_role(),
    base_job_name="debugger-demo",
    instance_count=1,
    instance_type="ml.p3.2xlarge",
    framework_version="1.7.0",
    py_version="py37",
    
    # Debugger-specific parameters
    debugger_hook_config=debugger_hook_config,
    rules=rules
)

estimator.fit(wait=False)
```

------
#### [ XGBoost ]

```
# An example of constructing a SageMaker AI XGBoost estimator
import sagemaker
from sagemaker.xgboost.estimator import XGBoost
from sagemaker.debugger import CollectionConfig, DebuggerHookConfig, Rule, rule_configs

debugger_hook_config=DebuggerHookConfig(...)
rules=[
    Rule.sagemaker(rule_configs.built_in_rule())
]

estimator=XGBoost(
    entry_point="directory/to/your_training_script.py",
    role=sagemaker.get_execution_role(),
    base_job_name="debugger-demo",
    instance_count=1,
    instance_type="ml.p3.2xlarge",
    framework_version="1.5-1",

    # Debugger-specific parameters
    debugger_hook_config=debugger_hook_config,
    rules=rules
)

estimator.fit(wait=False)
```

------
#### [ Generic estimator ]

```
# An example of constructing a SageMaker AI generic estimator using the XGBoost algorithm base image
import boto3
import sagemaker
from sagemaker.estimator import Estimator
from sagemaker import image_uris
from sagemaker.debugger import CollectionConfig, DebuggerHookConfig, Rule, rule_configs

debugger_hook_config=DebuggerHookConfig(...)
rules=[
    Rule.sagemaker(rule_configs.built_in_rule())
]

region=boto3.Session().region_name
xgboost_container=sagemaker.image_uris.retrieve("xgboost", region, "1.5-1")

estimator=Estimator(
    role=sagemaker.get_execution_role()
    image_uri=xgboost_container,
    base_job_name="debugger-demo",
    instance_count=1,
    instance_type="ml.m5.2xlarge",
    
    # Debugger-specific parameters
    debugger_hook_config=debugger_hook_config,
    rules=rules
)

estimator.fit(wait=False)
```

------

設定下列參數，啟動 SageMaker Debugger：
+ `debugger_hook_config` ([https://sagemaker.readthedocs.io/en/stable/api/training/debugger.html#sagemaker.debugger.DebuggerHookConfig](https://sagemaker.readthedocs.io/en/stable/api/training/debugger.html#sagemaker.debugger.DebuggerHookConfig) 的物件) — 必須在 [調整您的訓練指令碼以註冊勾點](debugger-modify-script.md) 期間啟動調整後訓練指令碼中的勾點，將 SageMaker 訓練啟動器 (估算器) 設定為從訓練任務收集輸出張量，並將張量儲存到安全的 S3 儲存貯體或本機機器。若要了解如何設定 `debugger_hook_config`，請參閱[設定 SageMaker Debugger 以儲存張量](debugger-configure-hook.md)。
+ `rules` ([https://sagemaker.readthedocs.io/en/stable/api/training/debugger.html#sagemaker.debugger.Rule](https://sagemaker.readthedocs.io/en/stable/api/training/debugger.html#sagemaker.debugger.Rule) 物件清單) — 設定此參數以啟動您要即時執行的 SageMaker Debugger 內建規則。內建規則這種邏輯可自動偵錯模型的訓練進度，並透過分析安全 S3 儲存貯體中儲存的輸出張量找出訓練問題。若要了解如何設定 `rules`，請參閱[如何設定偵錯工具內建規則](use-debugger-built-in-rules.md)。若要尋找偵錯輸出張量之內建規則的完整清單，請參閱[偵錯工具規則](debugger-built-in-rules.md#debugger-built-in-rules-Rule)。如果您想要建立自己的邏輯偵測任何訓練問題，請參閱[使用偵錯工具用戶端程式庫建立自訂規則](debugger-custom-rules.md)。
**注意**  
唯有利用 SageMaker 訓練執行個體才能使用內建規則。您無法在本機模式使用這些規則。
+ `tensorboard_output_config` ([https://sagemaker.readthedocs.io/en/stable/api/training/debugger.html#sagemaker.debugger.TensorBoardOutputConfig](https://sagemaker.readthedocs.io/en/stable/api/training/debugger.html#sagemaker.debugger.TensorBoardOutputConfig) 的物件) — 設定 SageMaker Debugger 以 Tensorboard 相容格式收集輸出張量，並儲存至 `TensorBoardOutputConfig` 物件中指定的 S3 輸出路徑。如需詳細資訊，請參閱 [在 TensorBoard 中視覺化 Amazon SageMaker Debugger 輸出張量](debugger-enable-tensorboard-summaries.md)。
**注意**  
`tensorboard_output_config` 必須使用 `debugger_hook_config` 參數進行設定，過程中您必須新增 `sagemaker-debugger` 勾點，調整訓練指令碼。

**注意**  
SageMaker Debugger 將輸出張量安全儲存於 S3 儲存貯體的子資料夾。例如，帳戶中預設 S3 儲存貯體 URI 的格式為 `s3://amzn-s3-demo-bucket-sagemaker-<region>-<12digit_account_id>/<base-job-name>/<debugger-subfolders>/`。SageMaker Debugger 建立的子資料夾有兩個：`debug-output` 和 `rule-output`。如果新增 `tensorboard_output_config` 參數，您也會找到 `tensorboard-output` 資料夾。

請參閱下列主題，尋找關於如何設定特定 Debugger 參數的更多詳細範例。

**Topics**
+ [使用特定 Debugger 參數建構 SageMaker AI 估算器](#debugger-configuration-structure)
+ [設定 SageMaker Debugger 以儲存張量](debugger-configure-hook.md)
+ [如何設定偵錯工具內建規則](use-debugger-built-in-rules.md)
+ [關閉偵錯工具](debugger-turn-off.md)
+ [Debugger 的實用 SageMaker AI 估算器類別方法](debugger-estimator-classmethods.md)