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

# 偵錯工具內建剖析工具規則清單
<a name="debugger-built-in-profiler-rules"></a>

使用 Amazon SageMaker Debugger 提供的偵錯工具內建剖析工具規則，並分析訓練您的模型時收集的指標。偵錯工具內建規則監控對成功執行高效能訓練任務至關重要的各種常見條件。您可以使用 [Amazon SageMaker Python SDK](https://sagemaker.readthedocs.io/en/stable) 或低階 SageMaker API 作業來呼叫內建剖析工具規則。使用內建規則無需額外付費。如需帳單的更多相關資訊，請參閱 [Amazon SageMaker 定價](https://aws.amazon.com/sagemaker/pricing/)頁面。

**注意**  
您可以連接到訓練任務的內建剖析工具規則數量上限為 20。SageMaker Debugger 可完整管理內建規則，並同步分析您的訓練任務。

**重要**  
若要使用新的偵錯工具功能，您必須升級 SageMaker Python SDK 和 SMDebug 用戶端程式庫。在您的 IPython 核心、Jupyter 筆記本或 JupyterLab 環境中，執行下列程式碼以安裝最新版本的程式庫，然後重新啟動核心。  

```
import sys
import IPython
!{sys.executable} -m pip install -U sagemaker smdebug
IPython.Application.instance().kernel.do_shutdown(True)
```

## 剖析工具規則
<a name="debugger-built-in-profiler-rules-ProfilerRule"></a>

下列規則是可使用 `ProfilerRule.sagemaker` 類別方法呼叫的 Debugger 內建規則。

用於產生分析報告的偵錯工具內建規則


| 有效性範圍 | 內建規則 | 
| --- | --- | 
| 任何 SageMaker 訓練任務的分析報告 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/debugger-built-in-profiler-rules.html)  | 

適用於分析硬體系統資源使用率 (系統指標) 的偵錯工具內建規則


| 有效性範圍 | 內建規則 | 
| --- | --- | 
| 任何 SageMaker 訓練任務的一般系統監控規則 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/debugger-built-in-profiler-rules.html)  | 

分析架構指標的偵錯工具內建規則


| 有效性範圍 | 內建規則 | 
| --- | --- | 
| 深度學習架構 (TensorFlow 和 PyTorch) 的分析規則 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/debugger-built-in-profiler-rules.html)  | 

**警告**  
為了使用 [Amazon SageMaker Profiler](train-use-sagemaker-profiler.md)，SageMaker AI Debugger 會從 TensorFlow 2.11 和 PyTorch 2.0 開始棄用架構分析功能。您仍然可以在舊版本的架構和開發套件中使用該功能，如下所示。  
SageMaker Python SDK <= v2.130.0
PyTorch >= v1.6.0, < v2.0
TensorFlow >= v2.3.1, < v2.11
另請參閱[2023 年 3 月 16 日](debugger-release-notes.md#debugger-release-notes-20230315)。

**若要將內建規則與預設參數值搭配使用**，請使用下列組態格式：

```
from sagemaker.debugger import Rule, ProfilerRule, rule_configs

rules = [
    ProfilerRule.sagemaker(rule_configs.BuiltInRuleName_1()),
    ProfilerRule.sagemaker(rule_configs.BuiltInRuleName_2()),
    ...
    ProfilerRule.sagemaker(rule_configs.BuiltInRuleName_n())
]
```

**若要使用內建規則來自訂參數值**，請使用下列組態格式：

```
from sagemaker.debugger import Rule, ProfilerRule, rule_configs

rules = [
    ProfilerRule.sagemaker(
        base_config=rule_configs.BuiltInRuleName(),
        rule_parameters={
                "key": "value"
        }
    )
]
```

若要尋找 `rule_parameters` 參數的可用金鑰，請參閱參數描述資料表。

為參數描述資料表下方的每個內建規則提供範例規則組態程式碼。
+ 如需使用偵錯工具內建規則的完整指示和範例，請參閱[偵錯工具內建規則範例程式碼](debugger-built-in-rules-example.md#debugger-deploy-built-in-rules)。
+ 如需關於將內建規則與低階 SageMaker API 作業搭配使用的完整指示，請參閱[使用 SageMaker API 設定 Debugger](debugger-createtrainingjob-api.md)。

## ProfilerReport
<a name="profiler-report"></a>

ProfilerReport 規則會調用適用於監控和分析的所有內建規則。它建立一個分析報告，並在觸發個別規則時更新。您可以在訓練任務執行期間或訓練任務完成後下載全方位的分析報告。您可以調整規則參數值，以自訂內建監控和分析規則的敏感度。下列範例程式碼顯示透過 ProfilerReport 規則調整內建規則參數的基本格式。

```
rules=[
    ProfilerRule.sagemaker(
        rule_configs.ProfilerReport(
            <BuiltInRuleName>_<parameter_name> = value
        )
    )  
]
```

如果您在沒有任何自訂參數 (如下列範例程式碼所示) 的情況下觸發此 ProfilerReport 規則，則 ProfilerReport 規則會觸發具有預設參數值之監控和分析的所有內建規則。

```
rules=[ProfilerRule.sagemaker(rule_configs.ProfilerReport())]
```

下列範例程式碼會示範如何指定和調整 CPUBottleneck 規則的 `cpu_threshold` 參數和 CPUBottleneck 規則的 `threshold` 參數。

```
rules=[
    ProfilerRule.sagemaker(
        rule_configs.ProfilerReport(
            CPUBottleneck_cpu_threshold = 90,
            IOBottleneck_threshold = 90
        )
    )  
]
```

若要探索剖析工具報告中的內容，請參閱 [SageMaker Debugger 分析報告](https://docs.aws.amazon.com/sagemaker/latest/dg/debugger-profiling-report.html)。此外，由於此規則會啟動所有分析規則，因此您還可以使用 [SageMaker Studio 實驗中的 SageMaker Debugger 使用者介面](https://docs.aws.amazon.com/sagemaker/latest/dg/debugger-on-studio.html)來檢查規則分析狀態。

OverallSystemUsage 規則的參數描述


| 參數名稱 | Description | 
| --- | --- | 
| base\$1trial | 基礎試驗訓練任務名稱。此參數會由 Amazon SageMaker Debugger 自動設定為目前的訓練任務。 **必要** 有效值：字串  | 
| <BuiltInRuleName>\$1<parameter\$1name> |  可自訂的參數，可調整其他內建監控和分析規則的閾值。 **選用** 預設值：`None`  | 

## BatchSize
<a name="batch-size-rule"></a>

BatchSize 規則有助於偵測 GPU 是否因為批次大小較小而讓 GPU 的使用量過低。為了偵測此問題，此規則會監控平均 CPU 利用率、GPU 使用率和 GPU 記憶體使用率。如果 CPU、GPU 和 GPU 記憶體的平均使用率較低，則可能表示訓練任務可以在較小的執行個體類型上執行，或是以較大的批次大小執行。這種分析不適用於大量過度配置記憶體的架構。但是，增加批次大小可能會導致處理或資料載入瓶頸，因為每次反覆運算都需要更多資料預先處理的時間。

BatchSize 規則的參數描述


| 參數名稱 | Description | 
| --- | --- | 
| base\$1trial | 基礎試驗訓練任務名稱。此參數會由 Amazon SageMaker Debugger 自動設定為目前的訓練任務。 **必要** 有效值：字串  | 
| cpu\$1threshold\$1p95 |  定義 CPU 利用率第 95 分位數的閾值 (以百分比表示)。 **選用** 有效值：整數 預設值：`70` (以百分比表示)  | 
| gpu\$1threshold\$1p95 |  定義 GPU 使用率第 95 分位數的閾值 (以百分比表示)。 **選用** 有效值：整數 預設值：`70` (以百分比表示)  | 
| gpu\$1memory\$1threshold\$1p95 | 定義 GPU 記憶體使用率第 95 分位數的閾值 (以百分比表示)。 **選用** 有效值：整數 預設值：`70` (以百分比表示)  | 
| patience | 定義規則開始評估前要略過的資料點數量。訓練任務的前幾個步驟通常會顯示大量的資料程序，因此請讓規則保持耐心，並防止過早以您使用此參數指定的特定分析資料數量來調用規則。 **選用** 有效值：整數 預設值：`100`  | 
| window |  運算分位數的視窗大小。 **選用** 有效值：整數 預設值：`500`  | 
| scan\$1interval\$1us |  掃描時間軸檔案的時間間隔。 **選用** 有效值：整數 預設值：`60000000` (以微秒為單位)  | 

## CPUBottleneck
<a name="cpu-bottleneck"></a>

CPUBottleneck 規則可協助偵測 GPU 是否因 CPU 瓶頸而讓 GPU 的使用量過低。如果 CPU 瓶頸數量超過預先定義的閾值，則規則會傳回 True。

CPUBottleneck 規則的參數描述


| 參數名稱 | Description | 
| --- | --- | 
| base\$1trial | 基礎試驗訓練任務名稱。此參數會由 Amazon SageMaker Debugger 自動設定為目前的訓練任務。 **必要** 有效值：字串  | 
| threshold |  定義瓶頸時間與總訓練時間比例的閾值。如果比例超過為閾值參數指定的百分比，則規則會將規則狀態切換為 True。 **選用** 有效值：整數 預設值：`50` (以百分比表示)  | 
| gpu\$1threshold |  定義低 GPU 使用率的閾值。 **選用** 有效值：整數 預設值：`10` (以百分比表示)  | 
| cpu\$1threshold | 定義高 CPU 利用率的閾值。 **選用** 有效值：整數 預設值：`90` (以百分比表示)  | 
| patience | 定義規則開始評估前要略過的資料點數量。訓練任務的前幾個步驟通常會顯示大量的資料程序，因此請讓規則保持耐心，並防止過早以您使用此參數指定的特定分析資料數量來調用規則。 **選用** 有效值：整數 預設值：`100`  | 
| scan\$1interval\$1us | 掃描時間軸檔案的時間間隔。 **選用** 有效值：整數 預設值：`60000000` (以微秒為單位)  | 

## GPUMemoryIncrease
<a name="gpu-memory-increase"></a>

GPUMemoryIncrease 規則有助於偵測 GPU 上記憶體使用量大幅增加的情況。

GPUMemoryIncrease 規則的參數描述


| 參數名稱 | Description | 
| --- | --- | 
| base\$1trial | 基礎試驗訓練任務名稱。此參數會由 Amazon SageMaker Debugger 自動設定為目前的訓練任務。 **必要** 有效值：字串  | 
| increase |  定義絕對記憶體增加的閾值。 **選用** 有效值：整數 預設值：`10` (以百分比表示)  | 
| patience |  定義規則開始評估前要略過的資料點數量。訓練任務的前幾個步驟通常會顯示大量的資料程序，因此請讓規則保持耐心，並防止過早以您使用此參數指定的特定分析資料數量來調用規則。 **選用** 有效值：整數 預設值：`100`  | 
| window |  運算分位數的視窗大小。 **選用** 有效值：整數 預設值：`500`  | 
| scan\$1interval\$1us |  掃描時間軸檔案的時間間隔。 **選用** 有效值：整數 預設值：`60000000` (以微秒為單位)  | 

## IOBottleneck
<a name="io-bottleneck"></a>

此規則有助於偵測 GPU 是否因為資料 IO 瓶頸而讓 GPU 的使用量過低。如果 IO 瓶頸數量超過預先定義的閾值，則規則會傳回 True。

IOBottleneck 規則的參數描述


| 參數名稱 | Description | 
| --- | --- | 
| base\$1trial | 基礎試驗訓練任務名稱。此參數會由 Amazon SageMaker Debugger 自動設定為目前的訓練任務。 **必要** 有效值：字串  | 
| threshold | 定義規則傳回 True 時的閾值。**選用**有效值：整數預設值：`50` (以百分比表示) | 
| gpu\$1threshold |  定義何時將 GPU 視為使用量過低的閾值。 **選用** 有效值：整數 預設值：`70` (以百分比表示)  | 
| io\$1threshold | 定義高 IO 等待時間的閾值。**選用**有效值：整數預設值：`50` (以百分比表示) | 
| patience | 定義規則開始評估前要略過的資料點數量。訓練任務的前幾個步驟通常會顯示大量的資料程序，因此請讓規則保持耐心，並防止過早以您使用此參數指定的特定分析資料數量來調用規則。**選用**有效值：整數預設值：`1000` | 
| scan\$1interval\$1us |  掃描時間軸檔案的時間間隔。 **選用** 有效值：整數 預設值：`60000000` (以微秒為單位)  | 

## LoadBalancers
<a name="load-balancing"></a>

LoadBalancer 規則有助於偵測多個 GPU 之間的工作負載平衡問題。

LoadBalancer 規則的參數描述


| 參數名稱 | Description | 
| --- | --- | 
| base\$1trial | 基礎試驗訓練任務名稱。此參數會由 Amazon SageMaker Debugger 自動設定為目前的訓練任務。 **必要** 有效值：字串  | 
| threshold |  定義工作負載百分比。 **選用** 有效值：整數 預設值：`0.5` (無單位比例)  | 
| patience |  定義規則開始評估前要略過的資料點數量。訓練任務的前幾個步驟通常會顯示大量的資料程序，因此請讓規則保持耐心，並防止過早以您使用此參數指定的特定分析資料數量來調用規則。 **選用** 有效值：整數 預設值：`10`  | 
| scan\$1interval\$1us |  掃描時間軸檔案的時間間隔。 **選用** 有效值：整數 預設值：`60000000` (以微秒為單位)  | 

## LowGPUUtilization
<a name="low-gpu-utilization"></a>

LowGPUUtilization 規則可協助偵測 GPU 使用率是否較低或受到波動的影響。這是針對每個工作者上的每個 GPU 進行檢查。如果第 95 個分位數低於 threshold\$1p95 (這表示使用量過低)，則規則會傳回 True。如果第 95 個分位數高於 threshold\$1p95 和第五分位數低於 threshold\$1p5 (這表示波動)，則規則會傳回 True。

LowGPUUtilization 規則的參數描述


| 參數名稱 | Description | 
| --- | --- | 
| base\$1trial | 基礎試驗訓練任務名稱。此參數會由 Amazon SageMaker Debugger 自動設定為目前的訓練任務。 **必要** 有效值：字串  | 
| threshold\$1p95 |  第 95 個分位數的閾值，低於此閾值，會將 GPU 視為使用量過低。 **選用** 有效值：整數 預設值：`70` (以百分比表示)  | 
| threshold\$1p5 | 第五分位數的閾值。預設為 10%。**選用**有效值：整數預設值：`10` (以百分比表示) | 
| patience |  定義規則開始評估前要略過的資料點數量。訓練任務的前幾個步驟通常會顯示大量的資料程序，因此請讓規則保持耐心，並防止過早以您使用此參數指定的特定分析資料數量來調用規則。 **選用** 有效值：整數 預設值：`1000`  | 
| window |  運算分位數的視窗大小。 **選用** 有效值：整數 預設值：`500`  | 
| scan\$1interval\$1us |  掃描時間軸檔案的時間間隔。 **選用** 有效值：整數 預設值：`60000000` (以微秒為單位)  | 

## OverallSystemUsage
<a name="overall-system-usage"></a>

OverallSystemUsage 規則會衡量每個背景工作者節點的整體系統使用量。規則目前只會彙總每個節點的值，並運算其百分位數。

OverallSystemUsage 規則的參數描述


| 參數名稱 | Description | 
| --- | --- | 
| base\$1trial | 基礎試驗訓練任務名稱。此參數會由 Amazon SageMaker Debugger 自動設定為目前的訓練任務。 **必要** 有效值：字串  | 
| scan\$1interval\$1us |  掃描時間軸檔案的時間間隔。 **選用** 有效值：整數 預設值：`60000000` (以微秒為單位)  | 

## MaxInitializationTime
<a name="max-initialization-time"></a>

MaxInitializationTime 規則有助於偵測訓練初始化是否花費太多時間。規則會等到第一個步驟可用為止。

MaxInitializationTime 規則的參數描述


| 參數名稱 | Description | 
| --- | --- | 
| base\$1trial | 基礎試驗訓練任務名稱。此參數會由 Amazon SageMaker Debugger 自動設定為目前的訓練任務。 **必要** 有效值：字串  | 
| threshold |  定義等待第一個步驟變成可用的閾值 (以分鐘為單位)。 **選用** 有效值：整數 預設值：`20` (以分鐘為單位)  | 
| scan\$1interval\$1us |  掃描時間軸檔案的時間間隔。 **選用** 有效值：整數 預設值：`60000000` (以微秒為單位)  | 

## OverallFrameworkMetrics
<a name="overall-framework-metrics"></a>

OverallFrameworkMetrics 規則總結了在架構指標上使用的時間，例如轉送和向後傳遞以及資料載入。

OverallFrameworkMetrics 規則的參數描述


| 參數名稱 | Description | 
| --- | --- | 
| base\$1trial | 基礎試驗訓練任務名稱。此參數會由 Amazon SageMaker Debugger 自動設定為目前的訓練任務。 **必要** 有效值：字串  | 
| scan\$1interval\$1us |  掃描時間軸檔案的時間間隔。 **選用** 有效值：整數 預設值：`60000000` (以微秒為單位)  | 

## StepOutlier
<a name="step-outlier"></a>

StepOutlier 規則有助於偵測步驟持續時間中的極端值。如果有步驟持續時間大於某個時間範圍內整個步驟持續時間之 `stddev` sigmas 的極端值，則此規則會傳回 `True`。

StepOutlier 規則的參數描述


| 參數名稱 | Description | 
| --- | --- | 
| base\$1trial | 基礎試驗訓練任務名稱。此參數會由 Amazon SageMaker Debugger 自動設定為目前的訓練任務。 **必要** 有效值：字串  | 
| stddev |  定義與標準偏差相乘的係數。例如，當步驟持續時間大於或小於標準偏差的 5 倍時，則會依預設調用規則。 **選用** 有效值：整數 預設值：`5` (以分鐘為單位)  | 
| mode | 已在其下儲存步驟的模式，以及應在其上執行規則的模式。每個預設規則將在 EVAL 和 TRAIN 階段的步驟上執行**選用**有效值：整數預設值：`5` (以分鐘為單位) | 
| n\$1outliers | 規則傳回 True 之前要忽略多少個極端值**選用**有效值：整數預設值：`10` | 
| scan\$1interval\$1us |  掃描時間軸檔案的時間間隔。 **選用** 有效值：整數 預設值：`60000000` (以微秒為單位)  |