调试程序内置规则列表

使用 Amazon SageMaker 调试器提供的调试器内置规则，并分析训练模型时发出的张量。调试器内置规则监控对训练作业至关重要的各种常见情况。您可以使用内置规则调用Amazon SageMaker Python 开发工具包或低级别 SageMaker API 操作。根据您选择的深度学习框架，内置规则有四个有效性范围，如下表所示。

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

调试程序 ProfilerRule

以下规则是调试器内置规则，可以使用ProfilerRule.sagemaker类方法。

调试程序规则

以下规则是调试器内置规则，可以使用Rule.sagemaker类方法。

使用具有默认参数值的内置规则— 采用以下配置格式：

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()),
    Rule.sagemaker(rule_configs.built_in_rule_name_1()),
    Rule.sagemaker(rule_configs.built_in_rule_name_2()),
    ...
    Rule.sagemaker(rule_configs.built_in_rule_name_n())
]

使用内置规则来自定义参数值— 采用以下配置格式：

from sagemaker.debugger import Rule, ProfilerRule, rule_configs

rules = [
    ProfilerRule.sagemaker(
        base_config=rule_configs.BuiltInRuleName(),
        rule_parameters={
                "key": "value"
        }
    )
    Rule.sagemaker(
        base_config=rule_configs.built_in_rule_name(),
        rule_parameters={
                "key": "value"
        }
        collections_to_save=[ 
            CollectionConfig(
                name="tensor_collection_name", 
                parameters={
                    "key": "value"
                } 
            )
        ]
    )
]

查找可用的密钥rule_parameters参数，请参阅参数描述表。

参数描述表下方为每个内置规则提供了示例规则配置代码。

剖析器报告

ProfilerReport 规则调用所有内置规则来执行监控和分析。它会创建一个性能分析报告，并在触发单个规则时进行更新。您可以在训练作业运行期间或培训作业完成后下载全面的分析报告。您可以调整规则参数值以自定义内置监视和分析规则的敏感度。以下示例代码显示了通过 ProfilerREPORT 规则调整内置规则参数的基本格式。

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

如果您在没有任何自定义参数的情况下触发此 ProfilerPORT 规则（如以下示例代码所示），则 ProfilerPORT 规则将触发所有内置规则，以便使用默认参数值进行监视和分析。

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

以下示例代码说明了如何指定和调整 CPUBalyeck 规则。cpu_threshold参数和 IO瓶颈规则threshold参数。

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

BatchSize

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

CPU瓶颈

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

gpumMory 增加

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

IO瓶颈

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

负载均衡

LoadBalancing 规则有助于检测多个 GPU 之间的工作负载均衡中的问题。

GPU 利用率低

LowGPU 利用率规则有助于检测 GPU 利用率是低还是受到波动影响。对于每个工作线程上的每个 GPU，都会检查这个 如果第 95 个分位数低于阈hold_p95 表示利用率不足，则规则返回 True。如果第 95 个分位数高于 tarhold_p95 且第 5 个分位数低于 tarhold_p5，则规则返回 true，这表示波动。

整体系统使用情况

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

最大初始化时间

maxInitialize Time 规则有助于检测训练初始化是否花费了太长的时间。规则一直等到第一步可用。

整体框架指标

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

stepOtLier

stepOutLier 规则有助于检测步长持续时间内的异常值。此规则返回True如果有异常值的步长持续时间大于stddev在一个时间范围内整个步骤持续时间的 sigmas。

CreateexGBoost 报告

CreatexgBoost报告规则收集 xgBoost 训练作业的输出张量，并自动生成全面的训练报告。您可以在训练作业运行期间或培训作业完成后下载全面的概况分析报告，并检查培训进度或培训作业的最终结果。默认情况下，CreatexgBoostReport 规则收集以下输出张量：

rules=[
    Rule.sagemaker(
        rule_configs.create_xgboost_report()
    )  
]

DeadRelu

此规则检测试验中的修正线性单元 (ReLU) 激活函数的百分比是否因它们的激活活动已降至阈值以下而被视为死亡。如果层中非活跃 ReLU 的百分比大于非活跃 ReLU 的 threshold_layer 值，则该规则会返回 True。

built_in_rules = [
    Rule.sagemaker(
        base_config=rule_configs.dead_relu(),
        rule_parameters={
                "tensor_regex": ".*relu_output|.*ReLU_output",
                "threshold_inactivity": "1.0",
                "threshold_layer": "50.0"
        }
        collections_to_save=[ 
            CollectionConfig(
                name="custom_relu_collection", 
                parameters={
                    "include_regex: ".*relu_output|.*ReLU_output",
                    "save_interval": "500"
                } 
            )
        ]
    )
]

有关如何配置和部署内置规则的示例，请参阅配置调试程序内置规则。

ExplodingTensor

此规则检测训练期间发射的张量是否具有非有限值，即无限值或 NaN（不是数字）。如果检测到非有限值，则该规则返回 True。

built_in_rules = [
    Rule.sagemaker(
        base_config=rule_configs.exploding_tensor(),
        rule_parameters={
                "tensor_regex": ".*gradient",
                "only_nan": "False"
        }
        collections_to_save=[ 
            CollectionConfig(
                name="gradients", 
                parameters={
                    "save_interval": "500"
                }
            )
        ]
    )
]

有关如何配置和部署内置规则的示例，请参阅配置调试程序内置规则。

PoorWeightInitialization

此规则检测模型参数是否初始化不当。

良好的初始化会破坏神经网络中权重和梯度的对称性，并在各层之间保持相应的激活方差。否则，神经网络无法有效地学习。诸如 Xavier 之类的初始化程序旨在使激活之间的方差保持恒定，这对于训练非常深的神经网络尤其重要。初始化太小可能会导致梯度消失。初始化过大可能会导致梯度爆炸。此规则检查各层激活输入的方差、梯度分布以及初始步骤的损失收敛性，确定神经网络是否初始化不当。

built_in_rules = [
    Rule.sagemaker(
        base_config=rule_configs.poor_weight_initialization(),
        rule_parameters={
                "activation_inputs_regex": ".*relu_input|.*ReLU_input",
                "threshold": "10.0",
                "distribution_range": "0.001",
                "patience": "5",
                "steps": "10"
        },
        collections_to_save=[ 
            CollectionConfig(
                name="custom_relu_collection", 
                parameters={
                    "include_regex": ".*relu_input|.*ReLU_input",
                    "save_interval": "500"
                } 
            )
        ]
    )
]

有关如何配置和部署内置规则的示例，请参阅配置调试程序内置规则。

SaturatedActivation

此规则检测 tanh 和 sigmoid 激活层是否正在变得饱和。当层的输入接近激活函数的最大或最小值时，激活层将饱和。tanh 和 sigmoid 激活函数的最小和最大值由它们各自的 min_threshold 和 max_thresholds 值定义。如果节点的活动降到 threshold_inactivity 百分比以下，则将其视为饱和。如果超过 threshold_layer 百分比的节点处于饱和状态，则该规则返回 True。

built_in_rules = [
    Rule.sagemaker(
        base_config=rule_configs.saturated_activation(),
        rule_parameters={
                "tensor_regex": ".*tanh_input|.*sigmoid_input",
                "threshold_tanh_min": "-9.4999",
                "threshold_tanh_max": "9.4999",
                "threshold_sigmoid_min": "-23",
                "threshold_sigmoid_max": "16.99999",
                "threshold_inactivity": "1.0",
                "threshold_layer": "50.0"
        },
        collections_to_save=[ 
            CollectionConfig(
                name="custom_activations_collection",
                parameters={
                    "include_regex": ".*tanh_input|.*sigmoid_input"
                    "save_interval": "500"
                } 
            )
        ]
    )
]

有关如何配置和部署内置规则的示例，请参阅配置调试程序内置规则。

VanishingGradient

该规则检测试验中的梯度是否变得非常小或降至零幅度。如果梯度绝对值的平均值低于指定的 threshold，则该规则返回 True。

built_in_rules = [
    Rule.sagemaker(
        base_config=rule_configs.vanishing_gradient(),
        rule_parameters={
                "threshold": "0.0000001"
        },
        collections_to_save=[ 
            CollectionConfig(
                name="gradients", 
                parameters={
                    "save_interval": "500"
                } 
            )
        ]
    )
]

有关如何配置和部署内置规则的示例，请参阅配置调试程序内置规则。

WeightUpdateRatio

此规则跟踪训练期间更新与权重的比率，并检测该比率是过大还是过小。如果更新与权重的比率大于 large_threshold value 或者此比率小于 small_threshold，则该规则返回 True。

当更新与梯度相当时，训练条件是最佳的。过大的更新会使权重远离最佳值，而过小的更新会导致收敛速度非常慢。此规则要求权重可用于两个训练步骤，train.save_interval需要设置等于num_steps.

built_in_rules = [
    Rule.sagemaker(
        base_config=rule_configs.weight_update_ratio(),
        rule_parameters={
                "num_steps": "100",
                "large_threshold": "10.0",
                "small_threshold": "0.00000001",
                "epsilon": "0.000000001"
        },
        collections_to_save=[ 
            CollectionConfig(
                name="weights", 
                parameters={
                    "train.save_interval": "100"
                } 
            )
        ]
    )
]

有关如何配置和部署内置规则的示例，请参阅配置调试程序内置规则。

AllZero

此规则检测张量值的全部或值的指定百分比是否为零。

此规则可应用于受支持的深度学习框架（TensorFlow、MXNet 和 PyTorch）之一，也可以应用于 XGBoost 算法。必须指定 collection_names 或 tensor_regex 参数。如果指定了这两个参数，则规则将检查两个集合内张量的并集。

有关如何配置和部署内置规则的示例，请参阅配置调试程序内置规则。

built_in_rules = [
    Rule.sagemaker(
        base_config=rule_configs.all_zero(),
        rule_parameters={
                "tensor_regex": ".*",
                "threshold": "100"
        },
        collections_to_save=[ 
            CollectionConfig(
                name="all", 
                parameters={
                    "save_interval": "500"
                } 
            )
        ]
    )
]

ClassImbalance

此规则用于衡量分类之间的采样不平衡，如果不平衡状况超过阈值，或者由于不平衡而导致代表性不足的分类发生太多错误预测，则会引发错误。

分类模型需要训练数据集中的分类保持良好平衡，或者在训练期间对分类执行适当的加权/取样。此规则执行以下检查：

此规则可应用于受支持的深度学习框架（TensorFlow、MXNet 和 PyTorch）之一，也可以应用于 XGBoost 算法。

有关如何配置和部署内置规则的示例，请参阅配置调试程序内置规则。

built_in_rules = [
    Rule.sagemaker(
        base_config=rule_configs.class_imbalance(),
        rule_parameters={
                "threshold_imbalance": "10",
                "threshold_misprediction": "0.7",
                "samples": "500",
                "argmax": "False",
                "labels_regex": ".*labels",
                "predictions_regex": ".*predictions"
        },
        collections_to_save=[ 
            CollectionConfig(
                name="custom_output_collection",
                parameters={
                    "include_regex": ".*labels|.*predictions",
                    "save_interval": "500"
                } 
            )
        ]
    )
]

LossNotDecreasing

此规则检测值损失是否以适当的速度减少。这些损失必须是标量。

此规则可应用于受支持的深度学习框架（TensorFlow、MXNet 和 PyTorch）之一，也可以应用于 XGBoost 算法。必须指定 collection_names 或 tensor_regex 参数。如果指定了这两个参数，则规则将检查两个集合内张量的并集。

有关如何配置和部署内置规则的示例，请参阅配置调试程序内置规则。

built_in_rules = [
    Rule.sagemaker(
        base_config=rule_configs.loss_not_decreasing(),
        rule_parameters={
                "tensor_regex": ".*",
                "use_losses_collection": "True",
                "num_steps": "10",
                "diff_percent": "0.1",
                "increase_threshold_percent": "5",
                "mode": "GLOBAL"
        },
        collections_to_save=[ 
            CollectionConfig(
                name="losses", 
                parameters={
                    "save_interval": "500"
                } 
            )
        ]
    )
]

Overfit

此规则通过比较验证和训练损失来检测模型是否与训练数据过度拟合。

此规则可应用于受支持的深度学习框架（TensorFlow、MXNet 和 PyTorch）之一，也可以应用于 XGBoost 算法。

有关如何配置和部署内置规则的示例，请参阅配置调试程序内置规则。

built_in_rules = [
    Rule.sagemaker(
        base_config=rule_configs.overfit(),
        rule_parameters={
                "tensor_regex": ".*",
                "start_step": "0",
                "patience": "1",
                "ratio_threshold": "0.1"
        },
        collections_to_save=[
            CollectionConfig(
                name="losses", 
                parameters={
                    "train.save_interval": "100",
                    "eval.save_interval": "10"
                } 
            )
        ]
    )
]

Overtraining

此规则检测模型是否过度训练。在对行为良好的模型进行了多次训练迭代（训练和验证损失减少）之后，该模型接近损失函数的最低限度，并且不再改善。如果模型继续训练，则可能会发生验证损失开始增加，因为模型开始过度拟合。该规则设置阈值和条件，以确定模型是否没有改进，并防止由于过度训练而导致的过度拟合问题。

此规则可应用于受支持的深度学习框架（TensorFlow、MXNet 和 PyTorch）之一，也可以应用于 XGBoost 算法。

有关如何配置和部署内置规则的示例，请参阅配置调试程序内置规则。

built_in_rules = [
    Rule.sagemaker(
        base_config=rule_configs.overtraining(),
        rule_parameters={
                "patience_train": "5",
                "patience_validation": "10",
                "delta": "0.01"
        },
        collections_to_save=[ 
            CollectionConfig(
                name="losses", 
                parameters={
                    "save_interval": "500"
                } 
            )
        ]
    )
]

SimilarAcrossRuns

此规则将从基本试验中收集的张量与从另一试验中收集的张量进行比较。

此规则可应用于受支持的深度学习框架（TensorFlow、MXNet 和 PyTorch）之一，也可以应用于 XGBoost 算法。

有关如何配置和部署内置规则的示例，请参阅配置调试程序内置规则。

built_in_rules = [
    Rule.sagemaker(
        base_config=rule_configs.similar_across_runs(),
        rule_parameters={
                "other_trial": "<specify-another-job-name>",
                "collection_names": "losses",
                "tensor_regex": ".*"
        },
        collections_to_save=[ 
            CollectionConfig(
                name="losses", 
                parameters={
                    "save_interval": "500"
                } 
            )
        ]
    )
]

已停止的训练规则

stalledTraininGrule 检测训练作业是否没有进展，如果规则触发，则停止训练作业。该规则要求张量在其定义的时间间隔内定期保存张量threshold参数。该规则会继续监控新张量，如果没有发出新的张量，阈值间隔规则将被触发。

built_in_rules = [
    Rule.sagemaker(
        base_config=rule_configs.stalled_training_rule(),
        rule_parameters={
                "threshold": "1800",
                "stop_training_on_fire": "True",
                "training_job_name_prefix": "<specify-training-base-job-name>"
        },
        collections_to_save=[ 
            CollectionConfig(
                name="losses", 
                parameters={
                    "save_interval": "500"
                } 
            )
        ]
    )
]

TensorVariance

该规则检测您是否具有方差非常高或非常低的张量。张量中的非常高或非常低的方差可能会导致神经元饱和，从而降低神经网络的学习能力。张量非常高的方差最终还会产生张量爆炸问题。使用此规则可以提前检测出此类问题。

此规则可应用于受支持的深度学习框架（TensorFlow、MXNet 和 PyTorch）之一，也可以应用于 XGBoost 算法。必须指定 collection_names 或 tensor_regex 参数。如果指定了这两个参数，则规则将检查两个集合内张量的并集。

有关如何配置和部署内置规则的示例，请参阅配置调试程序内置规则。

built_in_rules = [
    Rule.sagemaker(
        base_config=rule_configs.tensor_variance(),
        rule_parameters={
                "collection_names": "weights",
                "max_threshold": "10",
                "min_threshold": "0.00001",
        },
        collections_to_save=[ 
            CollectionConfig(
                name="weights", 
                parameters={
                    "save_interval": "500"
                } 
            )
        ]
    )
]

UnchangedTensor

此规则检测张量是否不再随步骤而发生更改。

此规则运行numpy.allclose检查张量是否未发生更改的方法。

此规则可应用于受支持的深度学习框架（TensorFlow、MXNet 和 PyTorch）之一，也可以应用于 XGBoost 算法。必须指定 collection_names 或 tensor_regex 参数。如果指定了这两个参数，则规则将检查两个集合内张量的并集。

有关如何配置和部署内置规则的示例，请参阅配置调试程序内置规则。

built_in_rules = [
    Rule.sagemaker(
        base_config=rule_configs.unchanged_tensor(),
        rule_parameters={
                "collection_names": "losses",
                "tensor_regex": "",
                "num_steps": "3",
                "rtol": "1e-05",
                "atol": "1e-08",
                "equal_nan": "False"
        },
        collections_to_save=[ 
            CollectionConfig(
                name="losses", 
                parameters={
                    "save_interval": "500"
                } 
            )
        ]
    )
]

CheckInputImages

此规则检查输入图像是否已正确归一化。具体而言，规则会检测样本数据的平均值与零之间的差异是否超过阈值。许多计算机视觉模型要求输入数据的平均值和单位方差为零。

此规则适用于深度学习应用程序。

有关如何配置和部署内置规则的示例，请参阅配置调试程序内置规则。

built_in_rules = [
    Rule.sagemaker(
        base_config=rule_configs.check_input_images(),
        rule_parameters={
                "threshold_mean": "0.2",
                "threshold_samples": "500",
                "regex": ".*hybridsequential0_input_0",
                "channel": "1"
        },
        collections_to_save=[ 
            CollectionConfig(
                name="custom_inputs_collection", 
                parameters={
                    "include_regex": ".*hybridsequential0_input_0"
                    "save_interval": "500"
                } 
            )
        ]
    )
]

NLPSequenceRatio

给定其余输入序列（对于优化性能很有用）的情况下，此规则将计算特定令牌的比率。例如，您可以计算输入序列中填充句尾 (EOS) 令牌的百分比。如果 EOS 令牌数量过高，则应执行替代分桶策略。您还可以计算输入序列中未知令牌的百分比。如果未知单词的数量过高，可以使用替代词汇表。

此规则适用于深度学习应用程序。

有关如何配置和部署内置规则的示例，请参阅配置调试程序内置规则。

built_in_rules = [
    Rule.sagemaker(
        base_config=rule_configs.nlp_sequence_ratio(),
        rule_parameters={
                "tensor_regex": ".*embedding0_input_0",
                "token_values": "0",
                "token_thresholds_percent": "50"
        },
        collections_to_save=[ 
            CollectionConfig(
                name="custom_inputs_collection", 
                parameters={
                    "include_regex": ".*embedding0_input_0"
                } 
            )
        ]
    )
]

Confusion

此规则评估分类问题的混淆矩阵的优点。

它创建一个大小为 category_no*category_no 的矩阵，并使用来自 (labels, predictions) 对的数据填充该矩阵。对于每个 (labels, predictions) 对，confusion[labels][predictions] 中的计数增加 1。当完全填充矩阵后，按以下所示计算数据对角线值和非对角线值的比率：

此规则可应用于 XGBoost 算法。

有关如何配置和部署内置规则的示例，请参阅配置调试程序内置规则。

built_in_rules = [
    Rule.sagemaker(
        base_config=rule_configs.confusion(),
        rule_parameters={
                "category_no": "10",
                "labels": "labels",
                "predictions": "predictions",
                "labels_collection": "labels",
                "predictions_collection": "predictions",
                "min_diag": "0.9",
                "max_off_diag": "0.1"
        },
        collections_to_save=[ 
            CollectionConfig(
                name="labels",
                parameters={
                    "save_interval": "500"
                } 
            ),
            CollectionConfig(
                name="predictions",
                parameters={
                    "include_regex": "500"
                } 
            )
        ]
    )
]

功能重要性超重

此规则累积每个步骤 n 个最大要素重要性值的权重，并确保它们不会超过阈值。例如，您可以将前 3 个要素的阈值设置为不超过模型总权重的 80%。

此规则仅对 XGBoost 算法有效。

有关如何配置和部署内置规则的示例，请参阅配置调试程序内置规则。

built_in_rules = [
    Rule.sagemaker(
        base_config=rule_configs.feature_importance_overweight(),
        rule_parameters={
                "threshold": "0.8",
                "nfeatures": "3",
                "tensor_regex": ".*feature_importance/weight"
        },
        collections_to_save=[ 
            CollectionConfig(
                name="feature_importance", 
                parameters={
                    "save_interval": "500"
                } 
            )
        ]
    )
]

TreeDepth

此规则测量 XGBoost 模型中树的深度。XGBoost 会拒绝拆分，如果拆分不能改进损失。这会将训练规范化。因此，树的深度可能无法达到由depth参数。

此规则仅对 XGBoost 算法有效。

有关如何配置和部署内置规则的示例，请参阅配置调试程序内置规则。

built_in_rules = [
    Rule.sagemaker(
        base_config=rule_configs.tree_depth(),
        rule_parameters={
                "depth": "4"
        },
        collections_to_save=[ 
            CollectionConfig(
                name="tree", 
                parameters={
                    "save_interval": "500"
                } 
            )
        ]
    )
]