Debugger 内置规则列表

使用 Amazon SageMaker Debugger 提供的 Debugger 内置规则，分析在模型训练期间收集的指标和张量。Debugger 内置规则监控对成功运行训练作业至关重要的各种常见条件。您可以使用 Amazon SageMaker Python SDK 或者是低级别的 SageMaker API 操作调用内置规则。使用内置规则不会产生额外费用。有关计费的更多信息，请参阅 Amazon SageMaker 定价页面。

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

Debugger 规则

以下规则是可使用 Rule.sagemaker 类方法调用的 Debugger 内置规则。

使用内置规则及默认参数值 – 使用以下配置格式：

from sagemaker.debugger import Rule, ProfilerRule, rule_configs

rules = [
    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 = [
    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 参数的可用键，请参阅参数描述表。

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

CreateXgboostReport

CreateXgboostReport 规则从 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"
                } 
            )
        ]
    )
]

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

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"
                }
            )
        ]
    )
]

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

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"
                } 
            )
        ]
    )
]

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

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"
                } 
            )
        ]
    )
]

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

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"
                } 
            )
        ]
    )
]

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

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"
                } 
            )
        ]
    )
]

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

AllZero

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

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

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

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 算法。

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

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 参数。如果指定了这两个参数，则规则将检查两个集合内张量的并集。

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

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 算法。

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

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 算法。

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

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 算法。

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

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

StalledTrainingRule

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 参数。如果指定了这两个参数，则规则将检查两个集合内张量的并集。

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

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 参数。如果指定了这两个参数，则规则将检查两个集合内张量的并集。

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

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

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

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

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

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 令牌数量过高，则应执行替代分桶策略。您还可以计算输入序列中未知令牌的百分比。如果未知单词的数量过高，可以使用替代词汇表。

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

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

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 算法。

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

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"
                } 
            )
        ]
    )
]

FeatureImportanceOverweight

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

此规则仅对 XGBoost 算法有效。

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

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 算法有效。

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

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"
                } 
            )
        ]
    )
]