本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# Debugger 内置探查器规则列表
<a name="debugger-built-in-profiler-rules"></a>

使用 Amazon Debugger 提供的 SageMaker 调试器内置分析器规则，分析在训练模型时收集的指标。Debugger 内置规则监控对成功运行高性能的训练作业至关重要的各种常见条件。您可以使用 [Amaz SageMaker on Python 软件开发工具包](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 内置规则。

用于生成分析报告的 Debugger 内置规则


| 有效性范围 | 内置规则 | 
| --- | --- | 
| 任何 SageMaker 训练作业的分析报告 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/debugger-built-in-profiler-rules.html)  | 

Debugger 内置规则，用于分析硬件系统资源利用率（系统指标）


| 有效性范围 | 内置规则 | 
| --- | --- | 
| 适用于任何 SageMaker 训练作业的通用系统监控规则 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/debugger-built-in-profiler-rules.html)  | 

用于分析框架指标的 Debugger 内置规则


| 有效性范围 | 内置规则 | 
| --- | --- | 
| 深度学习框架的分析规则（TensorFlow 和 PyTorch） |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sagemaker/latest/dg/debugger-built-in-profiler-rules.html)  | 

**警告**  
为了支持 [Amazon SageMaker Profiler](train-use-sagemaker-profiler.md)， SageMaker AI Debugger 从 TensorFlow 2.11 和 2.0 开始弃用框架分析功能。 PyTorch 您仍然可以在先前版本的框架中使用该功能， SDKs 如下所示。  
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 内置规则的完整说明和示例，请参阅 [Debugger 内置规则示例代码](debugger-built-in-rules-example.md#debugger-deploy-built-in-rules)。
+ 有关在低级 SageMaker API 操作中使用内置规则的完整说明，请参阅[使用 SageMaker API 配置调试器](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`参数和 IOBottleneck 规则的`threshold`参数。

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

要浏览概要分析器报告中的内容，请参阅[SageMaker 调试器分析](https://docs.aws.amazon.com/sagemaker/latest/dg/debugger-profiling-report.html)报告。此外，由于此规则会激活所有分析规则，因此您还可以使用 [ SageMaker Studio Experiments 中的SageMaker 调试器用户界面](https://docs.aws.amazon.com/sagemaker/latest/dg/debugger-on-studio.html)来检查规则分析状态。

 OverallSystemUsage 规则的参数描述


| 参数名称 | 说明 | 
| --- | --- | 
| base\$1trial | 基本试验训练作业名称。Amazon D SageMaker ebugger 会自动将此参数设置为当前的训练作业。 **必填** 有效值：字符串  | 
| <BuiltInRuleName>\$1<parameter\$1name> |  可自定义的参数，用于调整其他内置监控和分析规则的阈值。 **可选** 默认值：`None`  | 

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

该 BatchSize 规则有助于检测 GPU 是否由于批量较小而未得到充分利用。为检测此问题，此规则监控平均 CPU 利用率、GPU 利用率和 GPU 内存利用率。如果 CPU、GPU 和 GPU 内存的利用率平均值偏低，则可能表明训练作业可运行在较小的实例类型上，或者可以使用更大的批次运行。此分析不适用于内存分配严重过量的框架。但是，增加批次大小可能会导致处理或数据加载瓶颈，因为每次迭代都需要更长的数据预处理时间。

 BatchSize 规则的参数描述


| 参数名称 | 说明 | 
| --- | --- | 
| base\$1trial | 基本试验训练作业名称。Amazon D SageMaker ebugger 会自动将此参数设置为当前的训练作业。 **必填** 有效值：字符串  | 
| 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 瓶颈而未得到充分利用。如果 CPU 瓶颈数超过预定义的阈值，则规则返回 True。

 CPUBottleneck 规则的参数描述


| 参数名称 | 说明 | 
| --- | --- | 
| base\$1trial | 基本试验训练作业名称。Amazon D SageMaker ebugger 会自动将此参数设置为当前的训练作业。 **必填** 有效值：字符串  | 
| threshold |  定义瓶颈时间与总训练时间比例的阈值。如果该比例超过为阈值参数指定的百分比，则规则会将规则状态切换为 True。 **可选** 有效值：整数 默认值：`50`（百分比）  | 
| gpu\$1threshold |  定义低 GPU 利用率的阈值。 **可选** 有效值：整数 默认值：`10`（百分比）  | 
| cpu\$1threshold | 定义高 CPU 利用率的阈值。 **可选** 有效值：整数 默认值：`90`（百分比）  | 
| patience | 定义在规则开始评估之前要跳过的数据点数。训练作业的前几个步骤通常会显示大量的数据处理，因此请慎重保留该规则，防止使用您对此参数指定的给定数量的分析数据过早调用该规则。 **可选** 有效值：整数 默认值：`100`  | 
| scan\$1interval\$1us | 扫描时间轴文件的时间间隔。 **可选** 有效值：整数 默认值：`60000000`（微秒）  | 

## GPUMemory增加
<a name="gpu-memory-increase"></a>

 GPUMemory增加规则有助于检测上内存使用量的大幅增加 GPUs。

 GPUMemory增加规则的参数描述


| 参数名称 | 说明 | 
| --- | --- | 
| base\$1trial | 基本试验训练作业名称。Amazon D SageMaker ebugger 会自动将此参数设置为当前的训练作业。 **必填** 有效值：字符串  | 
| increase |  定义绝对内存增加的阈值。 **可选** 有效值：整数 默认值：`10`（百分比）  | 
| patience |  定义在规则开始评估之前要跳过的数据点数。训练作业的前几个步骤通常会显示大量的数据处理，因此请慎重保留该规则，防止使用您对此参数指定的给定数量的分析数据过早调用该规则。 **可选** 有效值：整数 默认值：`100`  | 
| window |  用于计算分位数的时间长度。 **可选** 有效值：整数 默认值：`500`  | 
| scan\$1interval\$1us |  扫描时间轴文件的时间间隔。 **可选** 有效值：整数 默认值：`60000000`（微秒）  | 

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

此规则有助于检测 GPU 是否由于数据 IO 瓶颈而未充分利用。如果 IO 瓶颈数超过预定义的阈值，则规则返回 True。

 IOBottleneck 规则的参数描述


| 参数名称 | 说明 | 
| --- | --- | 
| base\$1trial | 基本试验训练作业名称。Amazon D SageMaker ebugger 会自动将此参数设置为当前的训练作业。 **必填** 有效值：字符串  | 
| threshold | 定义规则返回 True 时的阈值。**可选**有效值：整数默认值：`50`（百分比） | 
| gpu\$1threshold |  定义 GPU 何时被认为未充分利用的阈值。 **可选** 有效值：整数 默认值：`70`（百分比）  | 
| io\$1threshold | 定义高 IO 等待时间的阈值。**可选**有效值：整数默认值：`50`（百分比） | 
| patience | 定义在规则开始评估之前要跳过的数据点数。训练作业的前几个步骤通常会显示大量的数据处理，因此请慎重保留该规则，防止使用您对此参数指定的给定数量的分析数据过早调用该规则。**可选**有效值：整数默认值：`1000` | 
| scan\$1interval\$1us |  扫描时间轴文件的时间间隔。 **可选** 有效值：整数 默认值：`60000000`（微秒）  | 

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

该 LoadBalancing 规则有助于检测多个工作负载平衡中的问题 GPUs。

 LoadBalancing 规则的参数描述


| 参数名称 | 说明 | 
| --- | --- | 
| base\$1trial | 基本试验训练作业名称。Amazon D SageMaker ebugger 会自动将此参数设置为当前的训练作业。 **必填** 有效值：字符串  | 
| threshold |  定义工作负载百分比。 **可选** 有效值：整数 默认值：`0.5`（无单位比例值）  | 
| patience |  定义在规则开始评估之前要跳过的数据点数。训练作业的前几个步骤通常会显示大量的数据处理，因此请慎重保留该规则，防止使用您对此参数指定的给定数量的分析数据过早调用该规则。 **可选** 有效值：整数 默认值：`10`  | 
| scan\$1interval\$1us |  扫描时间轴文件的时间间隔。 **可选** 有效值：整数 默认值：`60000000`（微秒）  | 

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

“低” GPUUtilization 规则有助于检测 GPU 利用率是低还是存在波动。这会检查每个工作线程上的每个 GPU。如果第 95 个分位数低于 threshold\$1p95，则规则返回 True，表明利用率不足。如果第 95 个分位数高于 threshold\$1p95 且第 5 个分位数低于 threshold\$1p5，则规则返回 True，表示此时的情况为波动。

低限GPUUtilization 规则的参数描述


| 参数名称 | 说明 | 
| --- | --- | 
| base\$1trial | 基本试验训练作业名称。Amazon D SageMaker ebugger 会自动将此参数设置为当前的训练作业。 **必填** 有效值：字符串  | 
| threshold\$1p95 |  第 95 个分位数的阈值，低于此阈值即将 GPU 视为未充分利用。 **可选** 有效值：整数 默认值：`70`（百分比）  | 
| threshold\$1p5 | 第 5 个分位数的阈值。默认值为 10%。**可选**有效值：整数默认值：`10`（百分比） | 
| patience |  定义在规则开始评估之前要跳过的数据点数。训练作业的前几个步骤通常会显示大量的数据处理，因此请慎重保留该规则，防止使用您对此参数指定的给定数量的分析数据过早调用该规则。 **可选** 有效值：整数 默认值：`1000`  | 
| window |  用于计算分位数的时间长度。 **可选** 有效值：整数 默认值：`500`  | 
| scan\$1interval\$1us |  扫描时间轴文件的时间间隔。 **可选** 有效值：整数 默认值：`60000000`（微秒）  | 

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

该 OverallSystemUsage 规则衡量每个工作节点的总体系统使用率。该规则目前仅聚合每个节点的值并计算其百分位数。

 OverallSystemUsage 规则的参数描述


| 参数名称 | 说明 | 
| --- | --- | 
| base\$1trial | 基本试验训练作业名称。Amazon D SageMaker ebugger 会自动将此参数设置为当前的训练作业。 **必填** 有效值：字符串  | 
| scan\$1interval\$1us |  扫描时间轴文件的时间间隔。 **可选** 有效值：整数 默认值：`60000000`（微秒）  | 

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

该 MaxInitializationTime 规则有助于检测训练初始化是否花费了太多时间。规则会等待直至第一个步骤可用。

 MaxInitializationTime 规则的参数描述


| 参数名称 | 说明 | 
| --- | --- | 
| base\$1trial | 基本试验训练作业名称。Amazon D SageMaker ebugger 会自动将此参数设置为当前的训练作业。 **必填** 有效值：字符串  | 
| threshold |  定义等待第一个步骤可用的阈值（以分钟为单位）。 **可选** 有效值：整数 默认值：`20`（分钟）  | 
| scan\$1interval\$1us |  扫描时间轴文件的时间间隔。 **可选** 有效值：整数 默认值：`60000000`（微秒）  | 

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

该 OverallFrameworkMetrics 规则汇总了在框架指标上花费的时间，例如向前和向后传递以及数据加载。

 OverallFrameworkMetrics 规则的参数描述


| 参数名称 | 说明 | 
| --- | --- | 
| base\$1trial | 基本试验训练作业名称。Amazon D SageMaker ebugger 会自动将此参数设置为当前的训练作业。 **必填** 有效值：字符串  | 
| scan\$1interval\$1us |  扫描时间轴文件的时间间隔。 **可选** 有效值：整数 默认值：`60000000`（微秒）  | 

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

该 StepOutlier 规则有助于检测步进持续时间内的异常值。如果在某个时间范围内，步骤持续时间的异常值大于整个步骤持续时间的 `stddev` sigma，则此规则返回 `True`。

 StepOutlier 规则的参数描述


| 参数名称 | 说明 | 
| --- | --- | 
| base\$1trial | 基本试验训练作业名称。Amazon D SageMaker ebugger 会自动将此参数设置为当前的训练作业。 **必填** 有效值：字符串  | 
| stddev |  定义与标准差相乘的因子。例如，当步骤持续时间大于或小于标准差的 5 倍时，默认情况下会调用该规则。 **可选** 有效值：整数 默认值：`5`（分钟）  | 
| mode | 应保存步骤并在其上运行规则的模式。根据默认设置，规则将在从 EVAL 到 TRAIN 阶段的步骤上运行。**可选**有效值：整数默认值：`5`（分钟） | 
| n\$1outliers | 可以忽略的异常值数量，超过该数量后规则返回 True**可选**有效值：整数默认值：`10` | 
| scan\$1interval\$1us |  扫描时间轴文件的时间间隔。 **可选** 有效值：整数 默认值：`60000000`（微秒）  |