diff --git a/docs/api/api_python/mindarmour.adv_robustness.attacks.rst b/docs/api/api_python/mindarmour.adv_robustness.attacks.rst index aa1f127..229a596 100644 --- a/docs/api/api_python/mindarmour.adv_robustness.attacks.rst +++ b/docs/api/api_python/mindarmour.adv_robustness.attacks.rst @@ -3,32 +3,112 @@ mindarmour.adv_robustness.attacks 本模块包括经典的黑盒和白盒攻击算法，以制作对抗性示例。 -.. py:class:: mindarmour.adv_robustness.attacks.SaltAndPepperNoiseAttack(model, bounds=(0.0, 1.0), max_iter=100, is_targeted=False, sparse=True) +.. py:class:: mindarmour.adv_robustness.attacks.FastGradientMethod(network, eps=0.07, alpha=None, bounds=(0.0, 1.0), norm_level=2, is_targeted=False, loss_fn=None) - 增加椒盐噪声的量以生成对抗样本。 + 这种攻击是基于梯度计算的单步攻击，扰动的范数包括 'L1'、'L2'和'Linf'。 + + 参考文献：`I. J. Goodfellow, J. Shlens, and C. Szegedy, "Explaining and harnessing adversarial examples," in ICLR, 2015. `_。 **参数：** - - **model** (BlackModel) - 目标模型。 - - **bounds** (tuple) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 - - **max_iter** (int) - 生成对抗样本的最大迭代。默认值：100。 + - **network** (Cell) - 目标模型。 + - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 + - **alpha** (float) - 单步随机扰动与数据范围的比例。默认值：None。 + - **bounds** (tuple) - 数据的上下界，表示数据范围。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 + - **norm_level** (Union[int, numpy.inf]) - 范数的顺序。可取值：np.inf、1或2。默认值：2。 - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为onehot编码。默认值：True。 + - **loss_fn** (Loss) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 - .. py:method:: generate(inputs, labels) +.. py:class:: mindarmour.adv_robustness.attacks.RandomFastGradientMethod(network, eps=0.07, alpha=0.035, bounds=(0.0, 1.0), norm_level=2, is_targeted=False, loss_fn=None) - 根据输入数据和目标标签生成对抗样本。 - - **参数：** + 快速梯度法（Fast Gradient Method）使用随机扰动。 + 基于梯度计算的单步攻击。对抗性噪声是根据输入的梯度生成的，然后随机扰动。 - - **inputs** (numpy.ndarray) - 原始的、未受扰动的输入。 - - **labels** (numpy.ndarray) - 目标标签。 + 参考文献：`Florian Tramer, Alexey Kurakin, Nicolas Papernot, "Ensemble adversarial training: Attacks and defenses" in ICLR, 2018 `_。 - **返回：** + **参数：** - - **numpy.ndarray** - 每个攻击结果的布尔值。 - - **numpy.ndarray** - 生成的对抗样本。 - - **numpy.ndarray** - 每个样本的查询次数。 + - **network** (Cell) - 目标模型。 + - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 + - **alpha** (float) - 单步随机扰动与数据范围的比例。默认值：0.035。 + - **bounds** (tuple) - 数据的上下界，表示数据范围。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 + - **norm_level** (Union[int, numpy.inf]) - 范数的顺序。可取值：np.inf、1或2。默认值：2。 + - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 + - **loss_fn** (Loss) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + + **异常：** + + - **ValueError** - `eps` 小于 `alpha` 。 + +.. py:class:: mindarmour.adv_robustness.attacks.FastGradientSignMethod(network, eps=0.07, alpha=None, bounds=(0.0, 1.0), is_targeted=False, loss_fn=None) + + 快速梯度符号法（Fast Gradient Sign Method）攻击计算输入数据的梯度，然后使用梯度的符号创建对抗性噪声。 + + 参考文献：`Ian J. Goodfellow, J. Shlens, and C. Szegedy, "Explaining and harnessing adversarial examples," in ICLR, 2015 `_。 + + **参数：** + + - **network** (Cell) - 目标模型。 + - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 + - **alpha** (float) - 单步随机扰动与数据范围的比例。默认值：None。 + - **bounds** (tuple) - 数据的上下界，表示数据范围。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 + - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 + - **loss_fn** (Loss) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + +.. py:class:: mindarmour.adv_robustness.attacks.RandomFastGradientSignMethod(network, eps=0.07, alpha=0.035, bounds=(0.0, 1.0), is_targeted=False, loss_fn=None) + + 快速梯度符号法（Fast Gradient Sign Method）使用随机扰动。 + 随机快速梯度符号法（Random Fast Gradient Sign Method）攻击计算输入数据的梯度，然后使用带有随机扰动的梯度符号来创建对抗性噪声。 + + 参考文献：`F. Tramer, et al., "Ensemble adversarial training: Attacks and defenses," in ICLR, 2018 `_。 + + **参数：** + + - **network** (Cell) - 目标模型。 + - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 + - **alpha** (float) - 单步随机扰动与数据范围的比例。默认值：0.005。 + - **bounds** (tuple) - 数据的上下界，表示数据范围。 + 以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 + - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 + - **loss_fn** (Loss) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + + **异常：** + + - **ValueError** - `eps` 小于 `alpha` 。 + +.. py:class:: mindarmour.adv_robustness.attacks.LeastLikelyClassMethod(network, eps=0.07, alpha=None, bounds=(0.0, 1.0), loss_fn=None) + + 单步最不可能类方法（Single Step Least-Likely Class Method）是FGSM的变体，它以最不可能类为目标，以生成对抗样本。 + + 参考文献：`F. Tramer, et al., "Ensemble adversarial training: Attacks and defenses," in ICLR, 2018 `_。 + + **参数：** + + - **network** (Cell) - 目标模型。 + - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 + - **alpha** (float) - 单步随机扰动与数据范围的比例。默认值：None。 + - **bounds** (tuple) - 数据的上下界，表示数据范围。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 + - **loss_fn** (Loss) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + +.. py:class:: mindarmour.adv_robustness.attacks.RandomLeastLikelyClassMethod(network, eps=0.07, alpha=0.035, bounds=(0.0, 1.0), loss_fn=None) + + 随机最不可能类攻击方法：以置信度最小类别对应的梯度加一个随机扰动为攻击方向。 + + 具有随机扰动的单步最不可能类方法（Single Step Least-Likely Class Method）是随机FGSM的变体，它以最不可能类为目标，以生成对抗样本。 + + 参考文献：`F. Tramer, et al., "Ensemble adversarial training: Attacks and defenses," in ICLR, 2018 `_。 + + **参数：** + + - **network** (Cell) - 目标模型。 + - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 + - **alpha** (float) - 单步随机扰动与数据范围的比例。默认值：0.005。 + - **bounds** (tuple) - 数据的上下界，表示数据范围。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 + - **loss_fn** (Loss) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + + **异常：** + + - **ValueError** - `eps` 小于 `alpha` 。 .. py:class:: mindarmour.adv_robustness.attacks.IterativeGradientMethod(network, eps=0.3, eps_iter=0.1, bounds=(0.0, 1.0), nb_iter=5, loss_fn=None) @@ -56,160 +136,110 @@ mindarmour.adv_robustness.attacks - **NotImplementedError** - 此函数在迭代梯度方法中不可用。 -.. py:class:: mindarmour.adv_robustness.attacks.DiverseInputIterativeMethod(network, eps=0.3, bounds=(0.0, 1.0), is_targeted=False, prob=0.5, loss_fn=None) - - 多样性输入迭代法（Diverse Input Iterative Method）攻击遵循基本迭代法，并在每次迭代时对输入数据应用随机转换。对输入数据的这种转换可以提高对抗样本的可转移性。 +.. py:class:: mindarmour.adv_robustness.attacks.BasicIterativeMethod(network, eps=0.3, eps_iter=0.1, bounds=(0.0, 1.0), is_targeted=False, nb_iter=5, loss_fn=None) - 参考文献：`Xie, Cihang and Zhang, et al., "Improving Transferability of Adversarial Examples With Input Diversity," in CVPR, 2019 `_。 + 参考文献：`A. Kurakin, I. Goodfellow, and S. Bengio, "Adversarial examples in the physical world," in ICLR, 2017 `_。 **参数：** - **network** (Cell) - 目标模型。 - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。 + - **eps_iter** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.1。 - **bounds** (tuple) - 数据的上下界，表示数据范围。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **prob** (float) - 转换概率。默认值：0.5。 + - **nb_iter** (int) - 迭代次数。默认值：5。 - **loss_fn** (Loss) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 - -.. py:class:: mindarmour.adv_robustness.attacks.CarliniWagnerL2Attack(network, num_classes, box_min=0.0, box_max=1.0, bin_search_steps=5, max_iterations=1000, confidence=0, learning_rate=0.005, initial_const=0.01, abort_early_check_ratio=0.05, targeted=False, fast=True, abort_early=True, sparse=True) - - 使用L2范数的Carlini & Wagner攻击通过分别利用两个损失生成对抗样本：“对抗损失”可使生成的示例实际上是对抗性的，“距离损失”可以限制对抗样本的质量。 - - 参考文献：`Nicholas Carlini, David Wagner: "Towards Evaluating the Robustness of Neural Networks" `_。 - - **参数：** - - - **network** (Cell) - 目标模型。 - - **num_classes** (int) - 模型输出的标签数，应大于零。 - - **box_min** (float) - 目标模型输入的下界。默认值：0。 - - **box_max** (float) - 目标模型输入的上界。默认值：1.0。 - - **bin_search_steps** (int) - 用于查找距离和置信度之间的最优代价常数的二进制搜索的步数。默认值：5。 - - **max_itrations** (int) - 最大迭代次数，应大于零。默认值：1000。 - - **confidence** (float) - 对抗样本输出的置信度。默认值：0。 - - **learning_rate** (float) - 攻击算法的学习率。默认值：5e-3。 - - **initial_const** (float) - 用于平衡扰动范数和置信度差异的相对重要性的初始折衷常数。默认值：1e-2。 - - **abort_early_check_ratio** (float) - 检查所有迭代的每个比率的损失进度。默认值：5e-2。 - - **targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **fast** (bool) - 如果为True，则返回第一个找到的对抗样本。 - 如果为False，则返回扰动较小的对抗样本。默认值：True。 - - **abort_early** (bool) - 如果为True，则如果损失在一段时间内没有减少，Adam将被中止。如果为False，Adam将继续工作，直到到达最大迭代。默认值：True。 - - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为onehot编码。默认值：True。 - - .. py:method:: generate(inputs, labels) + .. py:method:: generate(inputs, labels) - 根据输入数据和目标标签生成对抗样本。 + 简单的迭代FGSM方法生成对抗样本。 **参数：** - - **inputs** (numpy.ndarray) - 输入样本。 - - **labels** (numpy.ndarray) - 输入样本或目标标签的基础真值标签。 + - **inputs** (Union[numpy.ndarray, tuple]) - 用作创建对抗样本的引用的良性输入样本。 + - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。 **返回：** - **numpy.ndarray** - 生成的对抗样本。 -.. py:class:: mindarmour.adv_robustness.attacks.GeneticAttack(model, model_type='classification', targeted=True, reserve_ratio=0.3, sparse=True, pop_size=6, mutation_rate=0.005, per_bounds=0.15, max_steps=1000, step_size=0.2, temp=0.3, bounds=(0, 1.0), adaptive=False, c=0.1) - - 遗传攻击（Genetic Attack）表示基于遗传算法的黑盒攻击，属于差分进化算法。 +.. py:class:: mindarmour.adv_robustness.attacks.MomentumIterativeMethod(network, eps=0.3, eps_iter=0.1, bounds=(0.0, 1.0), is_targeted=False, nb_iter=5, decay_factor=1.0, norm_level='inf', loss_fn=None) - 此攻击是由Moustafa Alzantot等人（2018）提出的。 + 动量迭代法（Momentum Iterative Method）攻击通过在迭代中积累损失函数梯度方向上的速度矢量，加速梯度下降算法，如FGSM、FGM和LLCM，从而生成对抗样本。 - 参考文献： `Moustafa Alzantot, Yash Sharma, Supriyo Chakraborty, "GeneticAttack: Practical Black-box Attacks with Gradient-FreeOptimization" `_。 + 参考文献：`Y. Dong, et al., "Boosting adversarial attacks with momentum," arXiv:1710.06081, 2017 `_。 **参数：** - - **model** (BlackModel) - 目标模型。 - - **model_type** (str) - 目标模型的类型。现在支持'classification'和'detection'。默认值：'classification'。 - - **targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。需要注意的是，model_type='detection'仅支持无目标攻击，默认值：True。 - -**reserve_ratio** (Union[int, float]) - 攻击后可检测到的对象百分比，特别是当model_type='detection'。保留比率应在(0, 1)的范围内。默认值：0.3。 - - **pop_size** (int) - 粒子的数量，应大于零。默认值：6。 - - **mutation_rate** (Union[int, float]) - 突变的概率，应在（0,1）的范围内。默认值：0.005。 - - **per_bounds** (Union[int, float]) - 扰动允许的最大无穷范数距离。 - - **max_steps** (int) - 每个对抗样本的最大迭代轮次。默认值：1000。 - - **step_size** (Union[int, float]) - 攻击步长。默认值：0.2。 - - **temp** (Union[int, float]) - 用于选择的采样温度。默认值：0.3。 - 温度越大，个体选择概率之间的差异就越大。 - - **bounds** (Union[tuple, list, None]) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0, 1.0)。 - - **adaptive** (bool) - 为True，则打开突变参数的动态缩放。如果为false，则打开静态突变参数。默认值：False。 - - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为onehot编码。默认值：True。 - - **c** (Union[int, float]) - 扰动损失的权重。默认值：0.1。 + - **network** (Cell) - 目标模型。 + - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。 + - **eps_iter** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.1。 + - **bounds** (tuple) - 数据的上下界，表示数据范围。 + 以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 + - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 + - **nb_iter** (int) - 迭代次数。默认值：5。 + - **decay_factor** (float) - 迭代中的衰变因子。默认值：1.0。 + - **norm_level** (Union[int, numpy.inf]) - 范数的顺序。可取值：np.inf、1或2。默认值：'inf'。 + - **loss_fn** (Loss) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 .. py:method:: generate(inputs, labels) - - 根据输入数据和目标标签（或ground_truth标签）生成对抗样本。 + + 根据输入数据和原始/目标标签生成对抗样本。 **参数：** - -**inputs** (Union[numpy.ndarray, tuple]) - 输入样本。如果model_type='classification'，则输入的格式应为numpy.ndarray。输入的格式可以是(input1, input2, ...)，或者如果model_type='detection'，则只能是一个数组。 - -**labels** (Union[numpy.ndarray, tuple]) - 目标标签或ground-truth标签。如果model_type='classification'，标签的格式应为numpy.ndarray。如果model_type='detection'，标签的格式应为(gt_boxes, gt_labels)。 + - **inputs** (Union[numpy.ndarray, tuple]) - 用作创建对抗样本的引用的良性输入样本。 + - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。 **返回：** - - **numpy.ndarray** - 每个攻击结果的布尔值。 - **numpy.ndarray** - 生成的对抗样本。 - - **numpy.ndarray** - 每个样本的查询次数。 -.. py:class:: mindarmour.adv_robustness.attacks.RandomLeastLikelyClassMethod(network, eps=0.07, alpha=0.035, bounds=(0.0, 1.0), loss_fn=None) - - 随机最不可能类攻击方法：以置信度最小类别对应的梯度加一个随机扰动为攻击方向。 +.. py:class:: mindarmour.adv_robustness.attacks.ProjectedGradientDescent(network, eps=0.3, eps_iter=0.1, bounds=(0.0, 1.0), is_targeted=False, nb_iter=5, norm_level='inf', loss_fn=None) - 具有随机扰动的单步最不可能类方法（Single Step Least-Likely Class Method）是随机FGSM的变体，它以最不可能类为目标，以生成对抗样本。 + 投影梯度下降（Projected Gradient Descent）攻击是基本迭代法的变体，在这种方法中，在每次迭代之后，扰动被投影在指定半径的p范数球上（除了剪切对抗样本的值，使其位于允许的数据范围内）。这是Madry等人提出的用于对抗性训练的攻击。 - 参考文献：`F. Tramer, et al., "Ensemble adversarial training: Attacks and defenses," in ICLR, 2018 `_。 + 参考文献：`A. Madry, et al., "Towards deep learning models resistant to adversarial attacks," in ICLR, 2018 `_。 **参数：** - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 - - **alpha** (float) - 单步随机扰动与数据范围的比例。默认值：0.005。 + - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。 + - **eps_iter** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.1。 - **bounds** (tuple) - 数据的上下界，表示数据范围。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 + - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 + - **nb_iter** (int) - 迭代次数。默认值：5。 + - **norm_level** (Union[int, numpy.inf]) - 范数的顺序。可取值：np.inf、1或2。默认值：'inf'。 - **loss_fn** (Loss) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 - **异常：** - - - **ValueError** - `eps` 小于 `alpha` 。 - - -.. py:class:: mindarmour.adv_robustness.attacks.RandomFastGradientSignMethod(network, eps=0.07, alpha=0.035, bounds=(0.0, 1.0), is_targeted=False, loss_fn=None) - - 快速梯度符号法（Fast Gradient Sign Method）使用随机扰动。 - 随机快速梯度符号法（Random Fast Gradient Sign Method）攻击计算输入数据的梯度，然后使用带有随机扰动的梯度符号来创建对抗性噪声。 + .. py:method:: generate(inputs, labels) - 参考文献：`F. Tramer, et al., "Ensemble adversarial training: Attacks and defenses," in ICLR, 2018 `_。 + 基于BIM方法迭代生成对抗样本。通过带有参数norm_level的投影方法归一化扰动。 - **参数：** + **参数：** - - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 - - **alpha** (float) - 单步随机扰动与数据范围的比例。默认值：0.005。 - - **bounds** (tuple) - 数据的上下界，表示数据范围。 - 以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 - - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **loss_fn** (Loss) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + - **inputs** (Union[numpy.ndarray, tuple]) - 用作创建对抗样本的引用的良性输入样本。 + - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。 - **异常：** + **返回：** - - **ValueError** - `eps` 小于 `alpha` 。 + - **numpy.ndarray** - 生成的对抗样本。 - -.. py:class:: mindarmour.adv_robustness.attacks.FastGradientMethod(network, eps=0.07, alpha=None, bounds=(0.0, 1.0), norm_level=2, is_targeted=False, loss_fn=None) +.. py:class:: mindarmour.adv_robustness.attacks.DiverseInputIterativeMethod(network, eps=0.3, bounds=(0.0, 1.0), is_targeted=False, prob=0.5, loss_fn=None) - 这种攻击是基于梯度计算的单步攻击，扰动的范数包括 'L1'、'L2'和'Linf'。 + 多样性输入迭代法（Diverse Input Iterative Method）攻击遵循基本迭代法，并在每次迭代时对输入数据应用随机转换。对输入数据的这种转换可以提高对抗样本的可转移性。 - 参考文献：`I. J. Goodfellow, J. Shlens, and C. Szegedy, "Explaining and harnessing adversarial examples," in ICLR, 2015. `_。 + 参考文献：`Xie, Cihang and Zhang, et al., "Improving Transferability of Adversarial Examples With Input Diversity," in CVPR, 2019 `_。 **参数：** - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 - - **alpha** (float) - 单步随机扰动与数据范围的比例。默认值：None。 + - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。 - **bounds** (tuple) - 数据的上下界，表示数据范围。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 - - **norm_level** (Union[int, numpy.inf]) - 范数的顺序。可取值：np.inf、1或2。默认值：2。 - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 + - **prob** (float) - 转换概率。默认值：0.5。 - **loss_fn** (Loss) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 - .. py:class:: mindarmour.adv_robustness.attacks.MomentumDiverseInputIterativeMethod(network, eps=0.3, bounds=(0.0, 1.0), is_targeted=False, norm_level='l1', prob=0.5, loss_fn=None) 动量多样性输入迭代法（Momentum Diverse Input Iterative Method）攻击是一种动量迭代法，在每次迭代时对输入数据应用随机变换。对输入数据的这种转换可以提高对抗样本的可转移性。 @@ -226,132 +256,166 @@ mindarmour.adv_robustness.attacks - **prob** (float) - 转换概率。默认值：0.5。 - **loss_fn** (Loss) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 +.. py:class:: mindarmour.adv_robustness.attacks.DeepFool(network, num_classes, model_type='classification', reserve_ratio=0.3, max_iters=50, overshoot=0.02, norm_level=2, bounds=None, sparse=True) -.. py:class:: mindarmour.adv_robustness.attacks.JSMAAttack(network, num_classes, box_min=0.0, box_max=1.0, theta=1.0, max_iteration=1000, max_count=3, increase=True, sparse=True) - - 基于Jacobian的显著图攻击（Jacobian-based Saliency Map Attack）是一种基于输入特征显著图的有目标的迭代攻击。它使用每个类标签相对于输入的每个组件的损失梯度。然后，使用显著图来选择产生最大误差的维度。 + DeepFool是一种无目标的迭代攻击，通过将良性样本移动到最近的分类边界并跨越边界来实现。 - 参考文献：`The limitations of deep learning in adversarial settings `_。 + 参考文献：`DeepFool: a simple and accurate method to fool deep neural networks `_。 **参数：** - **network** (Cell) - 目标模型。 - **num_classes** (int) - 模型输出的标签数，应大于零。 - - **box_min** (float) - 目标模型输入的下界。默认值：0。 - - **box_max** (float) - 目标模型输入的上界。默认值：1.0。 - - **theta** (float) - 一个像素的变化率（相对于输入数据范围）。默认值：1.0。 - - **max_iteration** (int) - 迭代的最大轮次。默认值：1000。 - - **max_count** (int) - 每个像素的最大更改次数。默认值：3。 - - **increase** (bool) - 为True，则增加扰动。如果为False，则减少扰动。默认值：True。 + - **model_type** (str) - 目标模型的类型。现在支持'classification'和'detection'。默认值：'classification'。 + - **reserve_ratio** (Union[int, float]) - 攻击后可检测到的对象百分比，特别是当model_type='detection'。保留比率应在(0, 1)的范围内。默认值：0.3。 + - **max_iters** (int) - 最大迭代次数，应大于零。默认值：50。 + - **overshoot** (float) - 过冲参数。默认值：0.02。 + - **norm_level** (Union[int, str]) - 矢量范数的顺序。可取值：np.inf或2。默认值：2。 + - **bounds** (Union[tuple, list]) - 数据范围的上下界。以(clip_min, clip_max)的形式出现。默认值：None。 - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为onehot编码。默认值：True。 - .. py:method:: generate(inputs, labels) + .. py:method:: generate(inputs, labels) - 批量生成对抗样本。 + 根据输入样本和原始标签生成对抗样本。 **参数：** - - **inputs** (numpy.ndarray) - 输入样本。 - - **labels** (numpy.ndarray) - 目标标签。 + - **inputs** (Union[numpy.ndarray, tuple]) - 输入样本。如果model_type='classification'，则输入的格式应为numpy.ndarray。输入的格式可以是(input1, input2, ...)，或者如果model_type='detection'，则只能是一个数组。 + - **labels** (Union[numpy.ndarray, tuple]) - 目标标签或ground-truth标签。如果model_type='classification'，标签的格式应为numpy.ndarray。如果model_type='detection'，标签的格式应为(gt_boxes, gt_labels)。 **返回：** - **numpy.ndarray** - 对抗样本。 -.. py:class:: mindarmour.adv_robustness.attacks.ProjectedGradientDescent(network, eps=0.3, eps_iter=0.1, bounds=(0.0, 1.0), is_targeted=False, nb_iter=5, norm_level='inf', loss_fn=None) + **异常：** - 投影梯度下降（Projected Gradient Descent）攻击是基本迭代法的变体，在这种方法中，在每次迭代之后，扰动被投影在指定半径的p范数球上（除了剪切对抗样本的值，使其位于允许的数据范围内）。这是Madry等人提出的用于对抗性训练的攻击。 + - **NotImplementedError** - norm_level不在[2, np.inf, '2', 'inf']中。 - 参考文献：`A. Madry, et al., "Towards deep learning models resistant to adversarial attacks," in ICLR, 2018 `_。 +.. py:class:: mindarmour.adv_robustness.attacks.CarliniWagnerL2Attack(network, num_classes, box_min=0.0, box_max=1.0, bin_search_steps=5, max_iterations=1000, confidence=0, learning_rate=0.005, initial_const=0.01, abort_early_check_ratio=0.05, targeted=False, fast=True, abort_early=True, sparse=True) + + 使用L2范数的Carlini & Wagner攻击通过分别利用两个损失生成对抗样本：“对抗损失”可使生成的示例实际上是对抗性的，“距离损失”可以限制对抗样本的质量。 + + 参考文献：`Nicholas Carlini, David Wagner: "Towards Evaluating the Robustness of Neural Networks" `_。 **参数：** - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。 - - **eps_iter** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.1。 - - **bounds** (tuple) - 数据的上下界，表示数据范围。 - 以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 - - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **nb_iter(int) - 迭代次数。默认值：5。 - - **norm_level** (Union[int, numpy.inf]) - 范数的顺序。可取值：np.inf、1或2。默认值：'inf'。 - - **loss_fn** (Loss) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + - **num_classes** (int) - 模型输出的标签数，应大于零。 + - **box_min** (float) - 目标模型输入的下界。默认值：0。 + - **box_max** (float) - 目标模型输入的上界。默认值：1.0。 + - **bin_search_steps** (int) - 用于查找距离和置信度之间的最优代价常数的二进制搜索的步数。默认值：5。 + - **max_itrations** (int) - 最大迭代次数，应大于零。默认值：1000。 + - **confidence** (float) - 对抗样本输出的置信度。默认值：0。 + - **learning_rate** (float) - 攻击算法的学习率。默认值：5e-3。 + - **initial_const** (float) - 用于平衡扰动范数和置信度差异的相对重要性的初始折衷常数。默认值：1e-2。 + - **abort_early_check_ratio** (float) - 检查所有迭代的每个比率的损失进度。默认值：5e-2。 + - **targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 + - **fast** (bool) - 如果为True，则返回第一个找到的对抗样本。 + 如果为False，则返回扰动较小的对抗样本。默认值：True。 + - **abort_early** (bool) - 如果为True，则如果损失在一段时间内没有减少，Adam将被中止。如果为False，Adam将继续工作，直到到达最大迭代。默认值：True。 + - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为onehot编码。默认值：True。 - - .. py:method:: generate(inputs, labels) - - 基于BIM方法迭代生成对抗样本。通过带有参数norm_level的投影方法归一化扰动。 + .. py:method:: generate(inputs, labels) + + 根据输入数据和目标标签生成对抗样本。 **参数：** - - **inputs** (Union[numpy.ndarray, tuple]) - 用作创建对抗样本的引用的良性输入样本。 - - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。 + - **inputs** (numpy.ndarray) - 输入样本。 + - **labels** (numpy.ndarray) - 输入样本或目标标签的基础真值标签。 **返回：** - **numpy.ndarray** - 生成的对抗样本。 -.. py:class:: mindarmour.adv_robustness.attacks.DeepFool(network, num_classes, model_type='classification', reserve_ratio=0.3, max_iters=50, overshoot=0.02, norm_level=2, bounds=None, sparse=True) +.. py:class:: mindarmour.adv_robustness.attacks.JSMAAttack(network, num_classes, box_min=0.0, box_max=1.0, theta=1.0, max_iteration=1000, max_count=3, increase=True, sparse=True) - DeepFool是一种无目标的迭代攻击，通过将良性样本移动到最近的分类边界并跨越边界来实现。 + 基于Jacobian的显著图攻击（Jacobian-based Saliency Map Attack）是一种基于输入特征显著图的有目标的迭代攻击。它使用每个类标签相对于输入的每个组件的损失梯度。然后，使用显著图来选择产生最大误差的维度。 - 参考文献：`DeepFool: a simple and accurate method to fool deep neural networks `_。 + 参考文献：`The limitations of deep learning in adversarial settings `_。 **参数：** - **network** (Cell) - 目标模型。 - **num_classes** (int) - 模型输出的标签数，应大于零。 - - **model_type** (str) - 目标模型的类型。现在支持'classification'和'detection'。默认值：'classification'。 - - **reserve_ratio** (Union[int, float]) - 攻击后可检测到的对象百分比，特别是当model_type='detection'。保留比率应在(0, 1)的范围内。默认值：0.3。 - - **max_iters** (int) - 最大迭代次数，应大于零。默认值：50。 - - **overshoot** (float) - 过冲参数。默认值：0.02。 - - **norm_level** (Union[int, str]) - 矢量范数的顺序。可取值：np.inf或2。默认值：2。 - - **bounds** (Union[tuple, list]) - 数据范围的上下界。以(clip_min, clip_max)的形式出现。默认值：None。 + - **box_min** (float) - 目标模型输入的下界。默认值：0。 + - **box_max** (float) - 目标模型输入的上界。默认值：1.0。 + - **theta** (float) - 一个像素的变化率（相对于输入数据范围）。默认值：1.0。 + - **max_iteration** (int) - 迭代的最大轮次。默认值：1000。 + - **max_count** (int) - 每个像素的最大更改次数。默认值：3。 + - **increase** (bool) - 为True，则增加扰动。如果为False，则减少扰动。默认值：True。 - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为onehot编码。默认值：True。 + .. py:method:: generate(inputs, labels) + + 批量生成对抗样本。 + + **参数：** + + - **inputs** (numpy.ndarray) - 输入样本。 + - **labels** (numpy.ndarray) - 目标标签。 + + **返回：** + + - **numpy.ndarray** - 对抗样本。 + +.. py:class:: mindarmour.adv_robustness.attacks.LBFGS(network, eps=1e-05, bounds=(0.0, 1.0), is_targeted=True, nb_iter=150, search_iters=30, loss_fn=None, sparse=False) + + 在L-BFGS-B攻击中，使用有限内存BFGS优化算法来最小化输入与对抗样本之间的距离。 + + 参考文献：`Pedro Tabacof, Eduardo Valle. "Exploring the Space of Adversarial Images" `_。 + + **参数：** + + - **network** (Cell) - 被攻击模型的网络。 + - **eps** (float) - 攻击步长。默认值：1e-5。 + - **bounds** (tuple) - 数据的上下界。默认值：(0.0, 1.0) + - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：True。 + - **nb_iter** (int) - lbfgs-Optimizer的迭代次数，应大于零。默认值：150。 + - **search_iters** (int) - 步长的变更数，应大于零。默认值：30。 + - **loss_fn** (Functions) - 替代模型的损失函数。默认值：None。 + - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为onehot编码。默认值：False。 + .. py:method:: generate(inputs, labels) - 根据输入样本和原始标签生成对抗样本。 + 根据输入数据和目标标签生成对抗样本。 **参数：** - - **inputs** (Union[numpy.ndarray, tuple]) - 输入样本。如果model_type='classification'，则输入的格式应为numpy.ndarray。输入的格式可以是(input1, input2, ...)，或者如果model_type='detection'，则只能是一个数组。 - - **labels** (Union[numpy.ndarray, tuple]) - 目标标签或ground-truth标签。如果model_type='classification'，标签的格式应为numpy.ndarray。如果model_type='detection'，标签的格式应为(gt_boxes, gt_labels)。 + - **inputs** (numpy.ndarray) - 用作创建对抗样本的引用的良性输入样本。 + - **labels** (numpy.ndarray) - 原始/目标标签。 **返回：** - - **numpy.ndarray** - 对抗样本。 + - **numpy.ndarray** - 生成的对抗样本。 - **异常：** +.. py:class:: mindarmour.adv_robustness.attacks.GeneticAttack(model, model_type='classification', targeted=True, reserve_ratio=0.3, sparse=True, pop_size=6, mutation_rate=0.005, per_bounds=0.15, max_steps=1000, step_size=0.2, temp=0.3, bounds=(0, 1.0), adaptive=False, c=0.1) - - **NotImplementedError** - norm_level不在[2, np.inf, '2', 'inf']中。 - -.. py:class:: mindarmour.adv_robustness.attacks.PSOAttack(model, model_type='classification', targeted=False, reserve_ratio=0.3, sparse=True, step_size=0.5, per_bounds=0.6, c1=2.0, c2=2.0, c=2.0, pop_size=6, t_max=1000, pm=0.5, bounds=None) + 遗传攻击（Genetic Attack）表示基于遗传算法的黑盒攻击，属于差分进化算法。 - PSO攻击表示基于粒子群优化（Particle Swarm Optimization）算法的黑盒攻击，属于差分进化算法。 - 此攻击是由Rayan Mosli等人（2019）提出的。 + 此攻击是由Moustafa Alzantot等人（2018）提出的。 - 参考文献：`Rayan Mosli, Matthew Wright, Bo Yuan, Yin Pan, "They Might NOT Be Giants: Crafting Black-Box Adversarial Examples with Fewer Queries Using Particle Swarm Optimization", arxiv: 1909.07490, 2019. `_。 + 参考文献： `Moustafa Alzantot, Yash Sharma, Supriyo Chakraborty, "GeneticAttack: Practical Black-box Attacks with Gradient-FreeOptimization" `_。 **参数：** - **model** (BlackModel) - 目标模型。 - - **step_size** (Union[int, float]) - 攻击步长。默认值：0.5。 - - **per_bounds** (Union[int, float]) - 扰动的相对变化范围。默认值：0.6。 - - **c1** (Union[int, float]) - 权重系数。默认值：2。 - - **c2** (Union[int, float]) - 权重系数。默认值：2。 - - **c** (Union[int, float]) - 扰动损失的权重。默认值：2。 - - **pop_size** (int) - 粒子的数量，应大于零。默认值：6。 - - **t_max** (int) - 每个对抗样本的最大迭代轮数，应大于零。默认值：1000。 - - **pm** (Union[int, float]) - 突变的概率，应在（0,1）的范围内。默认值：0.5。 - - **bounds** (Union[list, tuple, None]) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：None。 - - **targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。需要注意的是，model_type='detection'仅支持无目标攻击，默认值：False。 - - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为onehot编码。默认值：True。 - **model_type** (str) - 目标模型的类型。现在支持'classification'和'detection'。默认值：'classification'。 + - **targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。需要注意的是，model_type='detection'仅支持无目标攻击，默认值：True。 - **reserve_ratio** (Union[int, float]) - 攻击后可检测到的对象百分比，特别是当model_type='detection'。保留比率应在(0, 1)的范围内。默认值：0.3。 - + - **pop_size** (int) - 粒子的数量，应大于零。默认值：6。 + - **mutation_rate** (Union[int, float]) - 突变的概率，应在（0,1）的范围内。默认值：0.005。 + - **per_bounds** (Union[int, float]) - 扰动允许的最大无穷范数距离。 + - **max_steps** (int) - 每个对抗样本的最大迭代轮次。默认值：1000。 + - **step_size** (Union[int, float]) - 攻击步长。默认值：0.2。 + - **temp** (Union[int, float]) - 用于选择的采样温度。默认值：0.3。温度越大，个体选择概率之间的差异就越大。 + - **bounds** (Union[tuple, list, None]) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0, 1.0)。 + - **adaptive** (bool) - 为True，则打开突变参数的动态缩放。如果为false，则打开静态突变参数。默认值：False。 + - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为onehot编码。默认值：True。 + - **c** (Union[int, float]) - 扰动损失的权重。默认值：0.1。 .. py:method:: generate(inputs, labels) - + 根据输入数据和目标标签（或ground_truth标签）生成对抗样本。 **参数：** @@ -365,56 +429,61 @@ mindarmour.adv_robustness.attacks - **numpy.ndarray** - 生成的对抗样本。 - **numpy.ndarray** - 每个样本的查询次数。 -.. py:class:: mindarmour.adv_robustness.attacks.BasicIterativeMethod(network, eps=0.3, eps_iter=0.1, bounds=(0.0, 1.0), is_targeted=False, nb_iter=5, loss_fn=None) +.. py:class:: mindarmour.adv_robustness.attacks.HopSkipJumpAttack(model, init_num_evals=100, max_num_evals=1000, stepsize_search='geometric_progression', num_iterations=20, gamma=1.0, constraint='l2', batch_size=32, clip_min=0.0, clip_max=1.0, sparse=True) - 参考文献：`A. Kurakin, I. Goodfellow, and S. Bengio, "Adversarial examples in the physical world," in ICLR, 2017 `_。 + Chen、Jordan和Wainwright提出的HopSkipJumpAttack是一种基于决策的攻击。此攻击需要访问目标模型的输出标签。 + + 参考文献：`Chen J, Michael I. Jordan, Martin J. Wainwright. HopSkipJumpAttack: A Query-Efficient Decision-Based Attack. 2019. arXiv:1904.02144 `_。 **参数：** - - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。 - - **eps_iter** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.1。 - - **bounds** (tuple) - 数据的上下界，表示数据范围。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 - - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **nb_iter(int) - 迭代次数。默认值：5。 - - **loss_fn** (Loss) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + - **model** (BlackModel) - 目标模型。 + - **init_num_evals** (int) - 梯度估计的初始评估数。默认值：100。 + - **max_num_evals** (int) - 梯度估计的最大求值数。默认值：1000。 + - **stepsize_search** (str) - 表示要如何搜索步长；可取值为'geometric_progression'、'grid_search'、'geometric_progression'。默认值：'geometric_progression'。 + - **num_iterations** (int) - 迭代次数。默认值：20。 + - **gamma** (float) - 用于设置二进制搜索阈值theta。默认值：1.0。 + 对于l2攻击，二进制搜索阈值 `theta` 为 :math:`gamma / d^{3/2}` 。对于linf攻击是 :math:`gamma/d^2` 。默认值：1.0。 + - **constraint** (str) - 要优化的范数距离。可取值为'l2'或'linf'。默认值：'l2'。 + - **batch_size** (int) - 批次大小。默认值：32。 + - **clip_min** (float, optional) - 最小图像组件值。默认值：0。 + - **clip_max** (float, optional) - 最大图像组件值。默认值：1。 + - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为onehot编码。默认值：True。 + + **异常：** + + - **ValueError** - stepsize_search不在['geometric_progression','grid_search']中。 + - **ValueError** - 约束不在['l2', 'linf']中 .. py:method:: generate(inputs, labels) - 简单的迭代FGSM方法生成对抗样本。 + 在for循环中生成对抗图像。 **参数：** - - **inputs** (Union[numpy.ndarray, tuple]) - 用作创建对抗样本的引用的良性输入样本。 - - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。 - - **返回：** - - - **numpy.ndarray，生成的对抗样本。 + - **inputs** (numpy.ndarray) - 原始图像。 + - **labels** (numpy.ndarray) - 目标标签。 -.. py:class:: mindarmour.adv_robustness.attacks.FastGradientSignMethod(network, eps=0.07, alpha=None, bounds=(0.0, 1.0), is_targeted=False, loss_fn=None) + **返回：** - 快速梯度符号法（Fast Gradient Sign Method）攻击计算输入数据的梯度，然后使用梯度的符号创建对抗性噪声。 + - **numpy.ndarray** - 每个攻击结果的布尔值。 + - **numpy.ndarray** - 生成的对抗样本。 + - **numpy.ndarray** - 每个样本的查询次数。 - 参考文献：`Ian J. Goodfellow, J. Shlens, and C. Szegedy, "Explaining and harnessing adversarial examples," in ICLR, 2015 `_。 + .. py:method:: set_target_images(target_images) - **参数：** + 设置目标图像进行目标攻击。 - - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 - - **alpha** (float) - 单步随机扰动与数据范围的比例。默认值：None。 - - **bounds** (tuple) - 数据的上下界，表示数据范围。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 - - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **loss_fn** (Loss) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + **参数：** + - **target_images** (numpy.ndarray) - 目标图像。 .. py:class:: mindarmour.adv_robustness.attacks.NES(model, scene, max_queries=10000, top_k=-1, num_class=10, batch_size=128, epsilon=0.3, samples_per_draw=128, momentum=0.9, learning_rate=0.001, max_lr=0.05, min_lr=0.0005, sigma=0.001, plateau_length=20, plateau_drop=2.0, adv_thresh=0.25, zero_iters=10, starting_eps=1.0, starting_delta_eps=0.5, label_only_sigma=0.001, conservative=2, sparse=True) 该类是自然进化策略（Natural Evolutionary Strategies，NES）攻击法的实现。NES使用自然进化策略来估计梯度，以提高查询效率。NES包括三个设置：Query-Limited设置、Partial-Information置和Label-Only设置。在query-limit设置中，攻击对目标模型的查询数量有限，但可以访问所有类的概率。在partial-info设置中，攻击仅有权访问top-k类的概率。 在label-only设置中，攻击只能访问按其预测概率排序的k个推断标签列表。在Partial-Information设置和Label-Only设置中，NES会进行目标攻击，因此用户需要使用set_target_images方法来设置目标类的目标图像。 - 参考文献：`Andrew Ilyas, Logan Engstrom, Anish Athalye, and Jessy Lin. - Black-box adversarial attacks with limited queries and information. In ICML, July 2018 `_。 + 参考文献：`Andrew Ilyas, Logan Engstrom, Anish Athalye, and Jessy Lin. Black-box adversarial attacks with limited queries and information. In ICML, July 2018 `_。 **参数：** @@ -425,7 +494,7 @@ mindarmour.adv_robustness.attacks - **num_class** (int) - 数据集中的类数。默认值：10。 - **batch_size** (int) - 批次大小。默认值：128。 - **epsilon** (float) - 攻击中允许的最大扰动。默认值：0.3。 - - **samples_per_draw(int) - 对偶采样中绘制的样本数。默认值：128。 + - **samples_per_draw** (int) - 对偶采样中绘制的样本数。默认值：128。 - **momentum** (float) - 动量。默认值：0.9。 - **learning_rate** (float) - 学习率。默认值：1e-3。 - **max_lr** (float) - 最大学习率。默认值：5e-2。 @@ -441,16 +510,8 @@ mindarmour.adv_robustness.attacks - **conservative** (int) - 用于epsilon衰变的守恒，如果没有收敛，它将增加。默认值：2。 - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为onehot编码。默认值：True。 - .. py:method:: set_target_images(target_images) - - 在Partial-Info或Label-Only设置中设置目标攻击的目标样本。 - - **参数：** - - - **target_images** (numpy.ndarray) - 目标攻击的目标样本。 - .. py:method:: generate(inputs, labels) - + 根据输入数据和目标标签生成对抗样本。 **参数：** @@ -470,21 +531,15 @@ mindarmour.adv_robustness.attacks - **ValueError** - 在Label-Only或Partial-Info设置中target_imgs为None。 - **ValueError** - 场景不在['Label_Only', 'Partial_Info', 'Query_Limit']中 -.. py:class:: mindarmour.adv_robustness.attacks.LeastLikelyClassMethod(network, eps=0.07, alpha=None, bounds=(0.0, 1.0), loss_fn=None) + .. py:method:: set_target_images(target_images) - 单步最不可能类方法（Single Step Least-Likely Class Method）是FGSM的变体，它以最不可能类为目标，以生成对抗样本。 + 在Partial-Info或Label-Only设置中设置目标攻击的目标样本。 - 参考文献：`F. Tramer, et al., "Ensemble adversarial training: Attacks and defenses," in ICLR, 2018 `_。 + **参数：** - **参数：** + - **target_images** (numpy.ndarray) - 目标攻击的目标样本。 - - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 - - **alpha** (float) - 单步随机扰动与数据范围的比例。默认值：None。 - - **bounds** (tuple) - 数据的上下界，表示数据范围。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 - - **loss_fn** (Loss) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 - .. py:class:: mindarmour.adv_robustness.attacks.PointWiseAttack(model, max_iter=1000, search_iter=10, is_targeted=False, init_attack=None, sparse=True) 点式攻击（Pointwise Attack）确保使用最小数量的更改像素为每个原始样本生成对抗样本。那些更改的像素将使用二进制搜索，以确保对抗样本和原始样本之间的距离尽可能接近。 @@ -515,103 +570,39 @@ mindarmour.adv_robustness.attacks - **numpy.ndarray** - 每个攻击结果的布尔值。 - **numpy.ndarray** - 生成的对抗样本。 - **numpy.ndarray** - 每个样本的查询次数。 - -.. py:class:: mindarmour.adv_robustness.attacks.RandomFastGradientMethod(network, eps=0.07, alpha=0.035, bounds=(0.0, 1.0), norm_level=2, is_targeted=False, loss_fn=None) - - 快速梯度法（Fast Gradient Method）使用随机扰动。 - 基于梯度计算的单步攻击。对抗性噪声是根据输入的梯度生成的，然后随机扰动。 - - 参考文献：`Florian Tramer, Alexey Kurakin, Nicolas Papernot, "Ensemble adversarial training: Attacks and defenses" in ICLR, 2018 `_。 - - **参数：** - - - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 - - **alpha** (float) - 单步随机扰动与数据范围的比例。默认值：0.035。 - - **bounds** (tuple) - 数据的上下界，表示数据范围。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 - - **norm_level** (Union[int, numpy.inf]) - 范数的顺序。可取值：np.inf、1或2。默认值：2。 - - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **loss_fn** (Loss) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 - - **异常：** - - - **ValueError** - `eps` 小于 `alpha` 。 - - -.. py:class:: mindarmour.adv_robustness.attacks.LBFGS(network, eps=1e-05, bounds=(0.0, 1.0), is_targeted=True, nb_iter=150, search_iters=30, loss_fn=None, sparse=False) - - 在L-BFGS-B攻击中，使用有限内存BFGS优化算法来最小化输入与对抗样本之间的距离。 - - 参考文献：`Pedro Tabacof, Eduardo Valle. "Exploring the Space of Adversarial Images" `_。 - - **参数：** - - - **network** (Cell) - 被攻击模型的网络。 - - **eps** (float) - 攻击步长。默认值：1e-5。 - - **bounds** (tuple) - 数据的上下界。默认值：(0.0, 1.0) - - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：True。 - - **nb_iter** (int) - lbfgs-Optimizer的迭代次数，应大于零。默认值：150。 - - **search_iters** (int) - 步长的变更数，应大于零。默认值：30。 - - **loss_fn** (Functions) - 替代模型的损失函数。默认值：None。 - - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为onehot编码。默认值：False。 - - .. py:method:: generate(inputs, labels) - - 根据输入数据和目标标签生成对抗样本。 - - **参数：** - - - **inputs** (numpy.ndarray) - 用作创建对抗样本的引用的良性输入样本。 - - **labels** (numpy.ndarray) - 原始/目标标签。 - - **返回：** - - **numpy.ndarray** - 生成的对抗样本。 - -.. py:class:: mindarmour.adv_robustness.attacks.HopSkipJumpAttack(model, init_num_evals=100, max_num_evals=1000, stepsize_search='geometric_progression', num_iterations=20, gamma=1.0, constraint='l2', batch_size=32, clip_min=0.0, clip_max=1.0, sparse=True) +.. py:class:: mindarmour.adv_robustness.attacks.PSOAttack(model, model_type='classification', targeted=False, reserve_ratio=0.3, sparse=True, step_size=0.5, per_bounds=0.6, c1=2.0, c2=2.0, c=2.0, pop_size=6, t_max=1000, pm=0.5, bounds=None) - Chen、Jordan和Wainwright提出的HopSkipJumpAttack是一种基于决策的攻击。此攻击需要访问目标模型的输出标签。 + PSO攻击表示基于粒子群优化（Particle Swarm Optimization）算法的黑盒攻击，属于差分进化算法。 + 此攻击是由Rayan Mosli等人（2019）提出的。 - 参考文献：`Chen J, Michael I. Jordan, Martin J. Wainwright. - HopSkipJumpAttack: A Query-Efficient Decision-Based Attack. 2019. - arXiv:1904.02144 `_。 + 参考文献：`Rayan Mosli, Matthew Wright, Bo Yuan, Yin Pan, "They Might NOT Be Giants: Crafting Black-Box Adversarial Examples with Fewer Queries Using Particle Swarm Optimization", arxiv: 1909.07490, 2019. `_。 **参数：** - **model** (BlackModel) - 目标模型。 - - **init_num_evals** (int) - 梯度估计的初始评估数。默认值：100。 - - **max_num_evals** (int) - 梯度估计的最大求值数。默认值：1000。 - - **stepsize_search** (str) - 表示要如何搜索步长；可取值为'geometric_progression'、'grid_search'、'geometric_progression'。默认值：'geometric_progression'。 - - **num_iterations** (int) - 迭代次数。默认值：20。 - - **gamma** (float) - 用于设置二进制搜索阈值theta。默认值：1.0。 - 对于l2攻击，二进制搜索阈值 `theta` 为 :math:`gamma / d^{3/2}` 。对于linf攻击是 :math:`gamma/d^2` 。默认值：1.0。 - - **constraint** (str) - 要优化的范数距离。可取值为'l2'或'linf'。默认值：'l2'。 - - **batch_size** (int) - 批次大小。默认值：32。 - - **clip_min** (float, optional) - 最小图像组件值。默认值：0。 - - **clip_max** (float, optional) - 最大图像组件值。默认值：1。 + - **step_size** (Union[int, float]) - 攻击步长。默认值：0.5。 + - **per_bounds** (Union[int, float]) - 扰动的相对变化范围。默认值：0.6。 + - **c1** (Union[int, float]) - 权重系数。默认值：2。 + - **c2** (Union[int, float]) - 权重系数。默认值：2。 + - **c** (Union[int, float]) - 扰动损失的权重。默认值：2。 + - **pop_size** (int) - 粒子的数量，应大于零。默认值：6。 + - **t_max** (int) - 每个对抗样本的最大迭代轮数，应大于零。默认值：1000。 + - **pm** (Union[int, float]) - 突变的概率，应在（0,1）的范围内。默认值：0.5。 + - **bounds** (Union[list, tuple, None]) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：None。 + - **targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。需要注意的是，model_type='detection'仅支持无目标攻击，默认值：False。 - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为onehot编码。默认值：True。 + - **model_type** (str) - 目标模型的类型。现在支持'classification'和'detection'。默认值：'classification'。 + - **reserve_ratio** (Union[int, float]) - 攻击后可检测到的对象百分比，特别是当model_type='detection'。保留比率应在(0, 1)的范围内。默认值：0.3。 - **异常：** - - - **ValueError** - stepsize_search不在['geometric_progression','grid_search']中。 - - **ValueError** - 约束不在['l2', 'linf']中 - - .. py:method:: set_target_images(target_images) - - 设置目标图像进行目标攻击。 - - **参数：** - - - **target_images** (numpy.ndarray) - 目标图像。 - - .. py:method:: generate(inputs, labels) + .. py:method:: generate(inputs, labels) - 在for循环中生成对抗图像。 + 根据输入数据和目标标签（或ground_truth标签）生成对抗样本。 **参数：** - - **inputs** (numpy.ndarray) - 原始图像。 - - **labels** (numpy.ndarray) - 目标标签。 + - **inputs** (Union[numpy.ndarray, tuple]) - 输入样本。如果model_type='classification'，则输入的格式应为numpy.ndarray。输入的格式可以是(input1, input2, ...)，或者如果model_type='detection'，则只能是一个数组。 + - **labels** (Union[numpy.ndarray, tuple]) - 目标标签或ground-truth标签。如果model_type='classification'，标签的格式应为numpy.ndarray。如果model_type='detection'，标签的格式应为(gt_boxes, gt_labels)。 **返回：** @@ -619,34 +610,29 @@ mindarmour.adv_robustness.attacks - **numpy.ndarray** - 生成的对抗样本。 - **numpy.ndarray** - 每个样本的查询次数。 -.. py:class:: mindarmour.adv_robustness.attacks.MomentumIterativeMethod(network, eps=0.3, eps_iter=0.1, bounds=(0.0, 1.0), is_targeted=False, nb_iter=5, decay_factor=1.0, norm_level='inf', loss_fn=None) - - 动量迭代法（Momentum Iterative Method）攻击通过在迭代中积累损失函数梯度方向上的速度矢量，加速梯度下降算法，如FGSM、FGM和LLCM，从而生成对抗样本。 +.. py:class:: mindarmour.adv_robustness.attacks.SaltAndPepperNoiseAttack(model, bounds=(0.0, 1.0), max_iter=100, is_targeted=False, sparse=True) - 参考文献：'Y. Dong, et al., "Boosting adversarial attacks with momentum," arXiv:1710.06081, 2017 `_。 + 增加椒盐噪声的量以生成对抗样本。 **参数：** - - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。 - - **eps_iter** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.1。 - - **bounds** (tuple) - 数据的上下界，表示数据范围。 - 以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 + - **model** (BlackModel) - 目标模型。 + - **bounds** (tuple) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 + - **max_iter** (int) - 生成对抗样本的最大迭代。默认值：100。 - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **nb_iter(int) - 迭代次数。默认值：5。 - - **decay_factor** (float) - 迭代中的衰变因子。默认值：1.0。 - - **norm_level** (Union[int, numpy.inf]) - 范数的顺序。可取值：np.inf、1或2。默认值：'inf'。 - - **loss_fn** (Loss) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为onehot编码。默认值：True。 - .. py:method:: generate(inputs, labels) + .. py:method:: generate(inputs, labels) - 根据输入数据和原始/目标标签生成对抗样本。 + 根据输入数据和目标标签生成对抗样本。 **参数：** - - **inputs** (Union[numpy.ndarray, tuple]) - 用作创建对抗样本的引用的良性输入样本。 - - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。 + - **inputs** (numpy.ndarray) - 原始的、未受扰动的输入。 + - **labels** (numpy.ndarray) - 目标标签。 **返回：** + - **numpy.ndarray** - 每个攻击结果的布尔值。 - **numpy.ndarray** - 生成的对抗样本。 + - **numpy.ndarray** - 每个样本的查询次数。 diff --git a/docs/api/api_python/mindarmour.adv_robustness.defenses.rst b/docs/api/api_python/mindarmour.adv_robustness.defenses.rst index fc56676..c78a0b8 100644 --- a/docs/api/api_python/mindarmour.adv_robustness.defenses.rst +++ b/docs/api/api_python/mindarmour.adv_robustness.defenses.rst @@ -3,37 +3,28 @@ mindarmour.adv_robustness.defenses 该模块包括经典的防御算法，用于防御对抗样本，增强模型的安全性和可信性。 -.. py:class:: mindarmour.adv_robustness.defenses.NaturalAdversarialDefense(network, loss_fn=None, optimizer=None, bounds=(0.0, 1.0), replace_ratio=0.5, eps=0.1) - - 基于FGSM的对抗性训练。 +.. py:class:: mindarmour.adv_robustness.defenses.AdversarialDefense(network, loss_fn=None, optimizer=None) - 参考文献：`A. Kurakin, et al., "Adversarial machine learning at scale," in ICLR, 2017. `_ 。 + 使用给定的对抗样本进行对抗训练。 **参数：** - **network** (Cell) - 要防御的MindSpore网络。 - **loss_fn** (Functions) - 损失函数。默认值：None。 - - **optimizer** (Cell)：用于训练网络的优化器。默认值：None。 - - **bounds** (tuple) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 - - **replace_ratio** (float) - 用对抗样本替换原始样本的比率。默认值：0.5。 - - **eps** (float) - 攻击方法（FGSM）的步长。默认值：0.1。 + - **optimizer** (Cell) - 用于训练网络的优化器。默认值：None。 -.. py:class:: mindarmour.adv_robustness.defenses.EnsembleAdversarialDefense(network, attacks, loss_fn=None, optimizer=None, bounds=(0.0, 1.0), replace_ratio=0.5) + .. py:method:: defense(inputs, labels) - 使用特定攻击方法列表和给定的对抗样本进行对抗训练，以增强模型的鲁棒性。 + 通过使用输入样本进行训练来增强模型。 - **参数：** + **参数：** - - **network** (Cell) - 要防御的MindSpore网络。 - - **attacks** (list[Attack]) - 攻击方法列表。 - - **loss_fn** (Functions) - 损失函数。默认值：None。 - - **optimizer** (Cell) - 用于训练网络的优化器。默认值：None。 - - **bounds** (tuple) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 - - **replace_ratio** (float) - 用对抗性替换原始样本的比率，必须在0到1之间。默认值：0.5。 + - **inputs** (numpy.ndarray) - 输入样本。 + - **labels** (numpy.ndarray) - 输入样本的标签。 - **异常：** + **返回：** - - **ValueError** - `bounds` 不在0和1之间。 + - **numpy.ndarray** - 防御操作的损失。 .. py:class:: mindarmour.adv_robustness.defenses.AdversarialDefenseWithAttacks(network, attacks, loss_fn=None, optimizer=None, bounds=(0.0, 1.0), replace_ratio=0.5) @@ -52,7 +43,7 @@ mindarmour.adv_robustness.defenses - **ValueError** - 替换比率不在0和1之间。 - .. py::method:: defense(inputs, labels) + .. py:method:: defense(inputs, labels) 通过使用从输入样本生成的对抗样本进行训练来增强模型。 @@ -64,29 +55,21 @@ mindarmour.adv_robustness.defenses **返回：** - **numpy.ndarray** - 对抗性防御操作的损失。 - -.. py:class:: mindarmour.adv_robustness.defenses.AdversarialDefense(network, loss_fn=None, optimizer=None) - 使用给定的对抗样本进行对抗训练。 +.. py:class:: mindarmour.adv_robustness.defenses.NaturalAdversarialDefense(network, loss_fn=None, optimizer=None, bounds=(0.0, 1.0), replace_ratio=0.5, eps=0.1) + + 基于FGSM的对抗性训练。 + + 参考文献：`A. Kurakin, et al., "Adversarial machine learning at scale," in ICLR, 2017. `_ 。 **参数：** - **network** (Cell) - 要防御的MindSpore网络。 - **loss_fn** (Functions) - 损失函数。默认值：None。 - - **optimizer** (Cell) - 用于训练网络的优化器。默认值：None。 - - .. py::method:: defense(inputs, labels) - - 通过使用输入样本进行训练来增强模型。 - - **参数：** - - - **inputs** (numpy.ndarray) - 输入样本。 - - **labels** (numpy.ndarray) - 输入样本的标签。 - - **返回：** - - - **numpy.ndarray** - 防御操作的损失。 + - **optimizer** (Cell)：用于训练网络的优化器。默认值：None。 + - **bounds** (tuple) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 + - **replace_ratio** (float) - 用对抗样本替换原始样本的比率。默认值：0.5。 + - **eps** (float) - 攻击方法（FGSM）的步长。默认值：0.1。 .. py:class:: mindarmour.adv_robustness.defenses.ProjectedAdversarialDefense(network, loss_fn=None, optimizer=None, bounds=(0.0, 1.0), replace_ratio=0.5, eps=0.3, eps_iter=0.1, nb_iter=5, norm_level='inf') @@ -105,3 +88,20 @@ mindarmour.adv_robustness.defenses - **eps_iter** (int) - PGD攻击参数，内环epsilon。默认值：0.1。 - **nb_iter** (int) - PGD攻击参数，迭代次数。默认值：5。 - **norm_level** (Union[int, char, numpy.inf]) - 范数类型。可选值：1、2、np.inf、'l1'、'l2'、'np.inf' 或 'inf'。默认值：'inf'。 + +.. py:class:: mindarmour.adv_robustness.defenses.EnsembleAdversarialDefense(network, attacks, loss_fn=None, optimizer=None, bounds=(0.0, 1.0), replace_ratio=0.5) + + 使用特定攻击方法列表和给定的对抗样本进行对抗训练，以增强模型的鲁棒性。 + + **参数：** + + - **network** (Cell) - 要防御的MindSpore网络。 + - **attacks** (list[Attack]) - 攻击方法列表。 + - **loss_fn** (Functions) - 损失函数。默认值：None。 + - **optimizer** (Cell) - 用于训练网络的优化器。默认值：None。 + - **bounds** (tuple) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 + - **replace_ratio** (float) - 用对抗性替换原始样本的比率，必须在0到1之间。默认值：0.5。 + + **异常：** + + - **ValueError** - `bounds` 不在0和1之间。 diff --git a/docs/api/api_python/mindarmour.adv_robustness.detectors.rst b/docs/api/api_python/mindarmour.adv_robustness.detectors.rst index 53f7099..1eb53d3 100644 --- a/docs/api/api_python/mindarmour.adv_robustness.detectors.rst +++ b/docs/api/api_python/mindarmour.adv_robustness.detectors.rst @@ -3,25 +3,33 @@ mindarmour.adv_robustness.detectors 此模块包括用于区分对抗样本和良性样本的检测器方法。 -.. py:class:: mindarmour.adv_robustness.detectors.DivergenceBasedDetector(auto_encoder, model, option='jsd', t=1, bounds=(0.0, 1.0)) +.. py:class:: mindarmour.adv_robustness.detectors.ErrorBasedDetector(auto_encoder, false_positive_rate=0.01, bounds=(0.0, 1.0)) - 基于发散的检测器学习通过js发散来区分正常样本和对抗样本。 + 检测器重建输入样本，测量重建误差，并拒绝重建误差大的样本。 - 参考文献：`MagNet: a Two-Pronged Defense against Adversarial Examples, by Dongyu Meng and Hao Chen, at CCS 2017. `_。 + 参考文献： `MagNet: a Two-Pronged Defense against Adversarial Examples, by Dongyu Meng and Hao Chen, at CCS 2017. `_。 **参数：** - - **auto_encoder** (Model) - 编码器模型。 - - **model** (Model) - 目标模型。 - - **option** (str) - 用于计算发散的方法。默认值：'jsd'。 - - **t** (int) - 用于克服数值问题的温度。默认值：1。 - - **bounds** (tuple) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 + - **auto_encoder** (Model) - 一个（训练过的）自动编码器，通过减少编码表示输入。 + - **false_positive_rate** (float) - 检测器的误报率。默认值：0.01。 + - **bounds** (tuple) - (clip_min, clip_max)。默认值：(0.0, 1.0)。 + + .. py:method:: detect(inputs) + + 检测输入样本是否具有对抗性。 + + **参数：** + + - **inputs** (numpy.ndarray) - 待判断的可疑样本。 + + **返回：** + + - **list[int]** - 样本是否具有对抗性。如果res[i]=1，则索引为i的输入样本是对抗性的。 .. py:method:: detect_diff(inputs) - - 检测原始样本和重建样本之间的距离。 - 距离由JSD计算。 + 检测原始样本和重建样本之间的距离。 **参数：** @@ -29,35 +37,32 @@ mindarmour.adv_robustness.detectors **返回：** - - **float** - 距离。 + - **float** - 重建样本和原始样本之间的距离。 - **异常：** + .. py:method:: fit(inputs, labels=None) - - **NotImplementedError** - 不支持参数 `option` 。 - -.. py:class:: mindarmour.adv_robustness.detectors.EnsembleDetector(detectors, policy='vote') + 查找给定数据集的阈值，以区分对抗样本。 + **参数：** - **参数：** + - **inputs** (numpy.ndarray) - 输入样本。 + - **labels** (numpy.ndarray) - 输入样本的标签。默认值：None。 - - **detectors** (Union[tuple, list]) - 检测器方法列表。 - - **policy** (str) - 决策策略，取值可为'vote'、'all'、'any'。默认值：'vote' + **返回：** - .. py:method:: detect_diff(inputs) - - 此方法在此类中不可用。 + - **float** - 区分对抗样本和良性样本的阈值。 + + .. py:method:: set_threshold(threshold) + + 设置参数阈值。 **参数：** - - **inputs** (Union[numpy.ndarray, list, tuple]) - 数据被用作创建对抗样本的引用。 + - **threshold** (float) - 检测阈值。 - **异常：** + .. py:method:: transform(inputs) - - **NotImplementedError** - 此函数在集成中不可用。 - - .. py:method:: detect(inputs) - - 从输入样本中检测对抗性示例。 + 重建输入样本。 **参数：** @@ -65,42 +70,43 @@ mindarmour.adv_robustness.detectors **返回：** - - **list[int]** - 样本是否具有对抗性。如果res[i]=1，则索引为i的输入样本是对抗性的。 + - **numpy.ndarray** - 重建图像。 - **异常：** +.. py:class:: mindarmour.adv_robustness.detectors.DivergenceBasedDetector(auto_encoder, model, option='jsd', t=1, bounds=(0.0, 1.0)) - - **ValueError** - 不支持策略。 - - .. py:method:: fit(inputs, labels=None) - - 像机器学习模型一样拟合检测器。此方法在此类中不可用。 + 基于发散的检测器学习通过js发散来区分正常样本和对抗样本。 - **参数：** + 参考文献： `MagNet: a Two-Pronged Defense against Adversarial Examples, by Dongyu Meng and Hao Chen, at CCS 2017. `_。 - - **inputs** (numpy.ndarray) - 计算阈值的数据。 - - **labels** (numpy.ndarray) - 数据的标签。默认值：None。 + **参数：** - **异常：** + - **auto_encoder** (Model) - 编码器模型。 + - **model** (Model) - 目标模型。 + - **option** (str) - 用于计算发散的方法。默认值：'jsd'。 + - **t** (int) - 用于克服数值问题的温度。默认值：1。 + - **bounds** (tuple) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 - - **NotImplementedError** - 此函数在集成中不可用。 - - .. py:method:: transform(inputs) - - 过滤输入样本中的对抗性噪声。 - 此方法在此类中不可用。 + .. py:method:: detect_diff(inputs) + + 检测原始样本和重建样本之间的距离。 + + 距离由JSD计算。 **参数：** - - **inputs** (Union[numpy.ndarray, list, tuple]) - 数据被用作创建对抗样本的引用。 + - **inputs** (numpy.ndarray) - 输入样本。 + + **返回：** + + - **float** - 距离。 **异常：** - - **NotImplementedError** - 此函数在集成中不可用。 - -.. py:class:: mindarmour.adv_robustness.detectors.RegionBasedDetector(model, number_points=10, initial_radius=0.0, max_radius=1.0, search_step=0.01, degrade_limit=0.0, sparse=False) + - **NotImplementedError** - 不支持参数 `option` 。 +.. py:class:: mindarmour.adv_robustness.detectors.RegionBasedDetector(model, number_points=10, initial_radius=0.0, max_radius=1.0, search_step=0.01, degrade_limit=0.0, sparse=False) - 参考文献：`Mitigating evasion attacks to deep neural networks via region-based classification `_。 + 参考文献： `Mitigating evasion attacks to deep neural networks via region-based classification `_。 **参数：** @@ -112,33 +118,32 @@ mindarmour.adv_robustness.detectors - **degrade_limit** (float) - 分类精度的可接受下降。默认值：0.0。 - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为onehot编码。默认值：False。 - - .. py:method:: detect_diff(inputs) - - 返回原始预测结果和基于区域的预测结果。 + .. py:method:: detect(inputs) + + 判断输入样本是否具有对抗性。 **参数：** - - **inputs** (numpy.ndarray) - 输入样本。 + - **inputs** (numpy.ndarray) - 待判断的可疑样本。 **返回：** - - **numpy.ndarray** - 输入样本的原始预测结果和基于区域的预测结果。 - - .. py:method:: detect(inputs) - - 判断输入样本是否具有对抗性。 + - **list[int]** - 样本是否具有对抗性。如果res[i]=1，则索引为i的输入样本是对抗性的。 + + .. py:method:: detect_diff(inputs) + + 返回原始预测结果和基于区域的预测结果。 **参数：** - - **inputs** (numpy.ndarray) - 待判断的可疑样本。 + - **inputs** (numpy.ndarray) - 输入样本。 **返回：** - - **list[int]** - 样本是否具有对抗性。如果res[i]=1，则索引为i的输入样本是对抗性的。 + - **numpy.ndarray** - 输入样本的原始预测结果和基于区域的预测结果。 .. py:method:: fit(inputs, labels=None) - + 训练检测器来决定最佳半径。 **参数：** @@ -149,9 +154,17 @@ mindarmour.adv_robustness.detectors **返回：** - **float** - 最佳半径。 - + + .. py:method:: set_radius(radius) + + 设置半径。 + + **参数：** + + - **radius** (float) - 区域的半径。 + .. py:method:: transform(inputs) - + 为输入样本生成超级立方体。 **参数：** @@ -161,42 +174,35 @@ mindarmour.adv_robustness.detectors **返回：** - **numpy.ndarray** - 超立方体对应于每个样本。 - - .. py:method:: set_radius(radius) - - 设置半径。 - - **参数：** - - - **radius** (float) - 区域的半径。 - -.. py:class:: mindarmour.adv_robustness.detectors.ErrorBasedDetector(auto_encoder, false_positive_rate=0.01, bounds=(0.0, 1.0)) - 检测器重建输入样本，测量重建误差，并拒绝重建误差大的样本。 +.. py:class:: mindarmour.adv_robustness.detectors.SpatialSmoothing(model, ksize=3, is_local_smooth=True, metric='l1', false_positive_ratio=0.05) - 参考文献：`MagNet: a Two-Pronged Defense against Adversarial Examples, by Dongyu Meng and Hao Chen, at CCS 2017. `_。 + 基于空间平滑的检测方法。 + 使用高斯滤波、中值滤波和均值滤波，模糊原始图像。当模型在样本模糊前后的预测值之间有很大的阈值差异时，将其判断为对抗样本。 **参数：** - - **auto_encoder** (Model) - 一个（训练过的）自动编码器，通过减少编码表示输入。 - - **false_positive_rate** (float) - 检测器的误报率。默认值：0.01。 - - **bounds** (tuple) - (clip_min, clip_max)。默认值：(0.0, 1.0)。 + - **model** (Model) - 目标模型。 + - **ksize** (int) - 平滑窗口大小。默认值：3。 + - **is_local_smooth** (bool) - 如果为True，则触发局部平滑。如果为False，则无局部平滑。默认值：True。 + - **metric** (str) - 距离方法。默认值：'l1'。 + - **false_positive_ratio** (float) - 良性样本上的假正率。默认值：0.05。 - .. py:method:: detect_diff(inputs) + .. py:method:: detect(inputs) - 检测原始样本和重建样本之间的距离。 + 检测输入样本是否为对抗样本。 **参数：** - - **inputs** (numpy.ndarray) - 输入样本。 + - **inputs** (numpy.ndarray) - 待判断的可疑样本。 **返回：** - - **float** - 重建样本和原始样本之间的距离。 + - **list[int]** - 样本是否具有对抗性。如果res[i]=1，则索引为i的输入样本是对抗性的。 - .. py:method:: detect(inputs) - - 检测输入样本是否具有对抗性。 + .. py:method:: detect_diff(inputs) + + 返回输入样本与其平滑对应样本之间的原始距离值（在应用阈值之前）。 **参数：** @@ -204,24 +210,39 @@ mindarmour.adv_robustness.detectors **返回：** - - **list[int]** - 样本是否具有对抗性。如果res[i]=1，则索引为i的输入样本是对抗性的。 - + - **float** - 距离。 + .. py:method:: fit(inputs, labels=None) - - 查找给定数据集的阈值，以区分对抗样本。 + + 训练检测器来决定阈值。适当的阈值能够确保良性样本上的实际假正率小于给定值。 **参数：** - - **inputs** (numpy.ndarray) - 输入样本。 - - **labels** (numpy.ndarray) - 输入样本的标签。默认值：None。 + - **inputs** (numpy.ndarray) - 良性样本。 + - **labels** (numpy.ndarray) - 默认None。 **返回：** - - **float** - 区分对抗样本和良性样本的阈值。 - - .. py:method:: transform(inputs) - - 重建输入样本。 + - **float** - 阈值，大于该距离的距离报告为正，即对抗性。 + + .. py:method:: set_threshold(threshold) + + 设置参数阈值。 + + **参数：** + + - **threshold** (float) - 检测阈值。 + +.. py:class:: mindarmour.adv_robustness.detectors.EnsembleDetector(detectors, policy='vote') + + **参数：** + + - **detectors** (Union[tuple, list]) - 检测器方法列表。 + - **policy** (str) - 决策策略，取值可为'vote'、'all'、'any'。默认值：'vote' + + .. py:method:: detect(inputs) + + 从输入样本中检测对抗性示例。 **参数：** @@ -229,21 +250,55 @@ mindarmour.adv_robustness.detectors **返回：** - - **numpy.ndarray** - 重建图像。 - - .. py:method:: set_threshold(threshold) - - 设置参数阈值。 + - **list[int]** - 样本是否具有对抗性。如果res[i]=1，则索引为i的输入样本是对抗性的。 + + **异常：** + + - **ValueError** - 不支持策略。 + + .. py:method:: detect_diff(inputs) + + 此方法在此类中不可用。 **参数：** - - **threshold** (float) - 检测阈值。 - + - **inputs** (Union[numpy.ndarray, list, tuple]) - 数据被用作创建对抗样本的引用。 + + **异常：** + + - **NotImplementedError** - 此函数在集成中不可用。 + + .. py:method:: fit(inputs, labels=None) + + 像机器学习模型一样拟合检测器。此方法在此类中不可用。 + + **参数：** + + - **inputs** (numpy.ndarray) - 计算阈值的数据。 + - **labels** (numpy.ndarray) - 数据的标签。默认值：None。 + + **异常：** + + - **NotImplementedError** - 此函数在集成中不可用。 + + .. py:method:: transform(inputs) + + 过滤输入样本中的对抗性噪声。 + 此方法在此类中不可用。 + + **参数：** + + - **inputs** (Union[numpy.ndarray, list, tuple]) - 数据被用作创建对抗样本的引用。 + + **异常：** + + - **NotImplementedError** - 此函数在集成中不可用。 + .. py:class:: mindarmour.adv_robustness.detectors.SimilarityDetector(trans_model, max_k_neighbor=1000, chunk_size=1000, max_buffer_size=10000, tuning=False, fpr=0.001) 检测器测量相邻查询之间的相似性，并拒绝与以前的查询非常相似的查询。 - 参考文献：`Stateful Detection of Black-Box Adversarial Attacks by Steven Chen, Nicholas Carlini, and David Wagner. at arxiv 2019 `_。 + 参考文献： `Stateful Detection of Black-Box Adversarial Attacks by Steven Chen, Nicholas Carlini, and David Wagner. at arxiv 2019 `_。 **参数：** @@ -253,21 +308,12 @@ mindarmour.adv_robustness.detectors - **max_buffer_size** (int) - 最大缓冲区大小。默认值：10000。默认值：False。 - **fpr** (float) - 合法查询序列上的误报率。默认值：0.001 - - .. py:method:: detect_diff(inputs) - - 从输入样本中检测对抗样本，如常见机器学习模型中的predict_proba函数。 - - **参数：** - - - **inputs** (Union[numpy.ndarray, list, tuple]) - 数据被用作创建对抗样本的引用。 + .. py:method:: clear_buffer() - **异常：** + 清除缓冲区内存。 - - **NotImplementedError** - 此函数在类 `SimilarityDetector` 中不可用。 - .. py:method:: detect(inputs) - + 处理查询以检测黑盒攻击。 **参数：** @@ -277,9 +323,21 @@ mindarmour.adv_robustness.detectors **异常：** - **ValueError** - 阈值或num_of_neighbors的参数不可用。 - + + .. py:method:: detect_diff(inputs) + + 从输入样本中检测对抗样本，如常见机器学习模型中的predict_proba函数。 + + **参数：** + + - **inputs** (Union[numpy.ndarray, list, tuple]) - 数据被用作创建对抗样本的引用。 + + **异常：** + + - **NotImplementedError** - 此函数在类 `SimilarityDetector` 中不可用。 + .. py:method:: fit(inputs, labels=None) - + 处理输入训练数据以计算阈值。 适当的阈值应确保假正率低于给定值。 @@ -297,104 +355,40 @@ mindarmour.adv_robustness.detectors **异常：** - **ValueError** - 训练数据个数小于max_k_neighbor! - - .. py:method:: transform(inputs) - - 过滤输入样本中的对抗性噪声。 - **参数：** - - - **inputs** (Union[numpy.ndarray, list, tuple]) - 数据被用作创建对抗样本的引用。 - - **异常：** - - - **NotImplementedError* - 此函数在类 `SimilarityDetector` 中不可用。 - - .. py:method:: set_threshold(threshold) - - 设置参数num_of_neighbors和threshold。 - - **参数：** - - - **num_of_neighbors** (int) - 最近邻的数量。 - - **threshold** (float) - 检测阈值。 - - .. py:method:: clear_buffer() - - 清除缓冲区内存。 - .. py:method:: get_detected_queries() - + 获取检测到的查询的索引。 **返回：** - **list[int]** - 检测到的恶意查询的序列号。 - + .. py:method:: get_detection_interval() - + 获取相邻检测之间的间隔。 **返回：** - **list[int]** - 相邻检测之间的查询数。 - -.. py:class:: mindarmour.adv_robustness.detectors.SpatialSmoothing(model, ksize=3, is_local_smooth=True, metric='l1', false_positive_ratio=0.05) - - 基于空间平滑的检测方法。 - 使用高斯滤波、中值滤波和均值滤波，模糊原始图像。当模型在样本模糊前后的预测值之间有很大的阈值差异时，将其判断为对抗样本。 - **参数：** - - - **model** (Model) - 目标模型。 - - **ksize** (int) - 平滑窗口大小。默认值：3。 - - **is_local_smooth** (bool) - 如果为True，则触发局部平滑。如果为False，则无局部平滑。默认值：True。 - - **metric** (str) - 距离方法。默认值：'l1'。 - - **false_positive_ratio** (float) - 良性样本上的假正率。默认值：0.05。 - - - .. py:method:: detect_diff(inputs) - - 返回输入样本与其平滑对应样本之间的原始距离值（在应用阈值之前）。 - - **参数：** - - - **inputs** (numpy.ndarray) - 待判断的可疑样本。 - - **返回：** + .. py:method:: set_threshold(threshold) - - **float** - 距离。 - - .. py:method:: detect(inputs) - - 检测输入样本是否为对抗样本。 + 设置参数num_of_neighbors和threshold。 **参数：** - - **inputs** (numpy.ndarray) - 待判断的可疑样本。 + - **num_of_neighbors** (int) - 最近邻的数量。 + - **threshold** (float) - 检测阈值。 - **返回：** + .. py:method:: transform(inputs) - - **list[int]** - 样本是否具有对抗性。如果res[i]=1，则索引为i的输入样本是对抗性的。 - - .. py:method:: fit(inputs, labels=None) - - 训练检测器来决定阈值。适当的阈值能够确保良性样本上的实际假正率小于给定值。 + 过滤输入样本中的对抗性噪声。 **参数：** - - **inputs** (numpy.ndarray) - 良性样本。 - - **labels** (numpy.ndarray) - 默认None。 - - **返回：** - - - **float** - 阈值，大于该距离的距离报告为正，即对抗性。 - - .. py:method:: set_threshold(threshold) - - 设置参数阈值。 + - **inputs** (Union[numpy.ndarray, list, tuple]) - 数据被用作创建对抗样本的引用。 - **参数：** + **异常：** - - **threshold** (float) - 检测阈值。 - + - **NotImplementedError** - 此函数在类 `SimilarityDetector` 中不可用。 diff --git a/docs/api/api_python/mindarmour.adv_robustness.evaluations.rst b/docs/api/api_python/mindarmour.adv_robustness.evaluations.rst index c74a23c..7628ed9 100644 --- a/docs/api/api_python/mindarmour.adv_robustness.evaluations.rst +++ b/docs/api/api_python/mindarmour.adv_robustness.evaluations.rst @@ -3,72 +3,66 @@ mindarmour.adv_robustness.evaluations 此模块包括各种指标，用于评估攻击或防御的结果。 -.. py:class:: mindarmour.adv_robustness.evaluations.DefenseEvaluate(raw_preds, def_preds, true_labels) +.. py:class:: mindarmour.adv_robustness.evaluations.AttackEvaluate(inputs, labels, adv_inputs, adv_preds, targeted=False, target_label=None) - 防御方法的评估指标。 + 攻击方法的评估指标。 **参数：** - - **raw_preds** (numpy.ndarray) - 原始模型上某些样本的预测结果。 - - **def_preds** (numpy.ndarray) - 防御模型上某些样本的预测结果。 - - **true_labels** (numpy.ndarray) - 样本的ground-truth标签，一个大小为ground-truth的一维数组。 - - .. py:method:: ccv() - - 计算分类置信度方差（CCV）。 + - **inputs** (numpy.ndarray) - 原始样本。 + - **labels** (numpy.ndarray) - 原始样本的one-hot格式标签。 + - **adv_inputs** (numpy.ndarray) - 从原始样本生成的对抗样本。 + - **adv_preds** (numpy.ndarray) - 对抗样本的所有输出类的概率。 + - **targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 + - **target_label** (numpy.ndarray) - 对抗样本的目标类，是大小为adv_inputs.shape[0]的一维。默认值：None。 - **返回：** + **异常：** - - **float** - 值越低，防守就越成功。如果返回值== -1，则说明样本数量为0。 + - **ValueError** - 如果targeted为True时，target_label为None。 - .. py:method:: cos() + .. py:method:: avg_conf_adv_class() - 参考文献：`Calculate classification output stability (COS) `_。 + 计算对抗类的平均置信度（ACAC）。 **返回：** - - **float** - 如果返回值>=0，则是有效的防御。值越低，防守越成功。如果返回值== -1, 则说明样本数量为0。 + - **float** - 范围在（0,1）之间。值越高，攻击就越成功。 - .. py:method:: csr() + .. py:method:: avg_conf_true_class() - 计算分类牺牲比（CSR），越低越好。 + 计算真类的平均置信度（ACTC）。 **返回：** - - **float** - 值越低，防守就越成功。 - - .. py:method:: crr() + - **float** - 范围在（0,1）之间。值越低，攻击就越成功。 - 计算分类校正率（CRR）。 + .. py:method:: avg_lp_distance() + + 计算平均lp距离（lp-dist）。 **返回：** - - **float** - 值越高，防守就越成功。 - - .. py:method:: cav() + - **float** - 返回所有成功对抗样本的平均'l0'、'l2'或'linf'距离，返回值包括以下情况。 + 如果返回值 :math:`>=` 0，则为平均lp距离。值越低，攻击就越成功。 + 如果返回值为-1，则没有成功的对抗样本。 - 计算分类精度方差（CAV）。 + .. py:method:: avg_ssim() - **返回：** + 计算平均结构相似性（ASS）。 - - **float** - 值越高，防守就越成功。 - -.. py:class:: mindarmour.adv_robustness.evaluations.AttackEvaluate(inputs, labels, adv_inputs, adv_preds, targeted=False, target_label=None) + **返回：** - 攻击方法的评估指标。 + - **float** - 平均结构相似性。 + 如果返回值在（0,1）之间，则值越高，攻击越成功。 + 如果返回值为-1，则没有成功的对抗样本。 - **参数：** + .. py:method:: mis_classification_rate() - - **inputs** (numpy.ndarray) - 原始样本。 - - **labels** (numpy.ndarray) - 原始样本的one-hot格式标签。 - - **adv_inputs** (numpy.ndarray) - 从原始样本生成的对抗样本。 - - **adv_preds** (numpy.ndarray) - 对抗样本的所有输出类的概率。 - - **targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **target_label** (numpy.ndarray) - 对抗样本的目标类，是大小为adv_inputs.shape[0]的一维。默认值：None。 + 计算错误分类率（MR）。 - **异常：** + **返回：** - - **ValueError** - 如果targeted为True时，target_label为None。 + - **float** - 范围在（0,1）之间。值越高，攻击就越成功。 .. py:method:: nte() @@ -79,115 +73,120 @@ mindarmour.adv_robustness.evaluations **返回：** - **float** - 范围在（0,1）之间。值越高，攻击就越成功。 - - .. py:method:: avg_lp_distance() - 计算平均lp距离（lp-dist）。 +.. py:class:: mindarmour.adv_robustness.evaluations.BlackDefenseEvaluate(raw_preds, def_preds, raw_query_counts, def_query_counts, raw_query_time, def_query_time, def_detection_counts, true_labels, max_queries) - **返回：** + 反黑盒防御方法的评估指标。 - - **float** - 返回所有成功对抗样本的平均'l0'、'l2'或'linf'距离，返回值包括以下情况。 - 如果返回值 :math:`>=` 0，则为平均lp距离。值越低，攻击就越成功。 - 如果返回值为-1，则没有成功的对抗样本。 + **参数：** - .. py:method:: mis_classification_rate() + - **raw_preds** (numpy.ndarray) - 预测原始模型上某些样本的结果。 + - **def_preds** (numpy.ndarray) - 预测防御模型上某些样本的结果。 + - **raw_query_counts** (numpy.ndarray) - 在原始模型上生成对抗样本的查询数，原始模型是大小为raw_preds.shape[0]的一维。对于良性样本，查询计数必须设置为0。 + - **def_query_counts** (numpy.ndarray) - 在防御模型上生成对抗样本的查询数，原始模型是大小为raw_preds.shape[0]的一维。对于良性样本，查询计数必须设置为0。 + - **raw_query_time** (numpy.ndarray) - 在原始模型上生成对抗样本的总持续时间，该样本是大小为raw_preds.shape[0]的一维。 + - **def_query_time** (numpy.ndarray) - 在防御模型上生成对抗样本的总持续时间，该样本是大小为raw_preds.shape[0]的一维。 + - **def_detection_counts** (numpy.ndarray) - 每次对抗样本生成期间检测到的查询总数，大小为raw_preds.shape[0]的一维。对于良性样本，如果查询被识别为可疑，则将def_detection_counts设置为1，否则将其设置为0。 + - **true_labels** (numpy.ndarray) - 大小为raw_preds.shape[0]的一维真标签。 + - **max_queries** (int) - 攻击预算，最大查询数。 - 计算错误分类率（MR）。 + .. py:method:: asv() + + 计算攻击成功率方差（ASV）。 **返回：** - - **float** - 范围在（0,1）之间。值越高，攻击就越成功。 - - .. py:method:: avg_ssim() + - **float** - 值越低，防守就越强。如果num_adv_samples=0，则返回-1。 - 计算平均结构相似性（ASS）。 + .. py:method:: fpr() + + 计算基于查询的检测器的假正率（FPR）。 **返回：** - - **float** - 平均结构相似性。 - 如果返回值在（0,1）之间，则值越高，攻击越成功。 - 如果返回值为-1，则没有成功的对抗样本。 + - **float** - 值越低，防御的可用性越高。如果num_adv_samples=0，则返回-1。 - .. py:method:: avg_conf_adv_class() + .. py:method:: qcv() - 计算对抗类的平均置信度（ACAC）。 + 计算查询计数方差（QCV）。 **返回：** - - **float** - 范围在（0,1）之间。值越高，攻击就越成功。 - - .. py:method:: avg_conf_true_class() + - **float** - 值越高，防守就越强。如果num_adv_samples=0，则返回-1。 - 计算真类的平均置信度（ACTC）。 + .. py:method:: qrv() + + 计算良性查询响应时间方差（QRV）。 **返回：** - - **float** - 范围在（0,1）之间。值越低，攻击就越成功。 - -.. py:class:: mindarmour.adv_robustness.evaluations.RadarMetric(metrics_name, metrics_data, labels, title, scale='hide') + - **float** - 值越低，防御的可用性越高。如果num_adv_samples=0，则返回-1。 - 雷达图，通过多个指标显示模型的鲁棒性。 +.. py:class:: mindarmour.adv_robustness.evaluations.DefenseEvaluate(raw_preds, def_preds, true_labels) - **参数：** + 防御方法的评估指标。 - - **metrics_name** (Union[tuple, list]) - 要显示的度量名称数组。每组值对应一条雷达曲线。 - - **labels** (Union[tuple, list]) - 所有雷达曲线的图例。 - - **title** (str) - 图表的标题。 - - **scale** (str) - 用于调整轴刻度的标量，如'hide'、'norm'、'sparse'、'dense'。默认值：'hide'。 + **参数：** - **异常：** + - **raw_preds** (numpy.ndarray) - 原始模型上某些样本的预测结果。 + - **def_preds** (numpy.ndarray) - 防御模型上某些样本的预测结果。 + - **true_labels** (numpy.ndarray) - 样本的ground-truth标签，一个大小为ground-truth的一维数组。 - - **ValueError** - scale值不在['hide', 'norm', 'sparse', 'dense']中。 + .. py:method:: cav() - .. py:method:: show() + 计算分类精度方差（CAV）。 - 显示雷达图。 + **返回：** -.. py:class:: mindarmour.adv_robustness.evaluations.BlackDefenseEvaluate(raw_preds, def_preds, raw_query_counts, def_query_counts, raw_query_time, def_query_time, def_detection_counts, true_labels, max_queries) + - **float** - 值越高，防守就越成功。 - 反黑盒防御方法的评估指标。 + .. py:method:: ccv() - **参数：** + 计算分类置信度方差（CCV）。 - - **raw_preds** (numpy.ndarray) - 预测原始模型上某些样本的结果。 - - **def_preds** (numpy.ndarray) - 预测防御模型上某些样本的结果。 - - **raw_query_counts** (numpy.ndarray) - 在原始模型上生成对抗样本的查询数，原始模型是大小为raw_preds.shape[0]的一维。对于良性样本，查询计数必须设置为0。 - - **def_query_counts** (numpy.ndarray) - 在防御模型上生成对抗样本的查询数，原始模型是大小为raw_preds.shape[0]的一维。对于良性样本，查询计数必须设置为0。 - - **raw_query_time** (numpy.ndarray) - 在原始模型上生成对抗样本的总持续时间，该样本是大小为raw_preds.shape[0]的一维。 - - **def_query_time** (numpy.ndarray) - 在防御模型上生成对抗样本的总持续时间，该样本是大小为raw_preds.shape[0]的一维。 - - **def_detection_counts** (numpy.ndarray) - 每次对抗样本生成期间检测到的查询总数，大小为raw_preds.shape[0]的一维。对于良性样本，如果查询被识别为可疑，则将def_detection_counts设置为1，否则将其设置为0。 - - **true_labels** (numpy.ndarray) - 大小为raw_preds.shape[0]的一维真标签。 - - **max_queries** (int) - 攻击预算，最大查询数。 + **返回：** + - **float** - 值越低，防守就越成功。如果返回值== -1，则说明样本数量为0。 - .. py:method:: qcv() + .. py:method:: cos() - 计算查询计数方差（QCV）。 + 参考文献：`Calculate classification output stability (COS) `_。 **返回：** - - **float** - 值越高，防守就越强。如果num_adv_samples=0，则返回-1。 - - .. py:method:: asv() + - **float** - 如果返回值>=0，则是有效的防御。值越低，防守越成功。如果返回值== -1, 则说明样本数量为0。 - 计算攻击成功率方差（ASV）。 + .. py:method:: crr() + + 计算分类校正率（CRR）。 **返回：** - - **float** - 值越低，防守就越强。如果num_adv_samples=0，则返回-1。 - - .. py:method:: fpr() + - **float** - 值越高，防守就越成功。 - 计算基于查询的检测器的假正率（FPR）。 + .. py:method:: csr() + + 计算分类牺牲比（CSR），越低越好。 **返回：** - - **float** - 值越低，防御的可用性越高。如果num_adv_samples=0，则返回-1。 - - .. py:method:: qrv() + - **float** - 值越低，防守就越成功。 - 计算良性查询响应时间方差（QRV）。 +.. py:class:: mindarmour.adv_robustness.evaluations.RadarMetric(metrics_name, metrics_data, labels, title, scale='hide') - **返回：** + 雷达图，通过多个指标显示模型的鲁棒性。 + + **参数：** + + - **metrics_name** (Union[tuple, list]) - 要显示的度量名称数组。每组值对应一条雷达曲线。 + - **labels** (Union[tuple, list]) - 所有雷达曲线的图例。 + - **title** (str) - 图表的标题。 + - **scale** (str) - 用于调整轴刻度的标量，如'hide'、'norm'、'sparse'、'dense'。默认值：'hide'。 + + **异常：** - - **float** - 值越低，防御的可用性越高。如果num_adv_samples=0，则返回-1。 \ No newline at end of file + - **ValueError** - scale值不在['hide', 'norm', 'sparse', 'dense']中。 + + .. py:method:: show() + + 显示雷达图。 diff --git a/docs/api/api_python/mindarmour.fuzz_testing.rst b/docs/api/api_python/mindarmour.fuzz_testing.rst index cd68c42..5f8eea7 100644 --- a/docs/api/api_python/mindarmour.fuzz_testing.rst +++ b/docs/api/api_python/mindarmour.fuzz_testing.rst @@ -3,78 +3,6 @@ mindarmour.fuzz_testing 该模块提供了一种基于神经元覆盖率增益的模糊测试方法来评估给定模型的鲁棒性。 -.. py:class:: mindarmour.fuzz_testing.TopKNeuronCoverage(model, top_k=3, incremental=False, batch_size=32) - - 计算前k个激活神经元的覆盖率。当隐藏层神经元的输出值在最大的'Top-k'范围内，神经元就会被激活。'Top k'神经元覆盖率等于网络中激活神经元占总神经元的比例。 - - **参数：** - - - **model** (Model) - 被测模型。 - - **top_k** (int) - 当隐藏层神经元的输出值在最大的'Top-k'范围内，神经元就会被激活。默认值：3。 - - **incremental** (bool) - 指标将以增量方式计算。默认值：False。 - - **batch_size** (int) - 模糊测试批次中的样本数。默认值：32。 - - .. py:method:: get_metrics(dataset) - - 获取Top K激活神经元覆盖率的指标。 - - **参数：** - - - **dataset** (numpy.ndarray) - 用于计算覆盖率指标的数据集。 - - **返回：** - - - **float** - 'top k neuron coverage'的指标。 - - -.. py:class:: mindarmour.fuzz_testing.SuperNeuronActivateCoverage(model, train_dataset, incremental=False, batch_size=32) - - 获取超激活神经元覆盖率（'super neuron activation coverage'）的指标。 :math:`SNAC = |UpperCornerNeuron|/|N|` 。SNAC是指测试集中神经元输出值超过训练集中相应神经元输出值上限的神经元比例。 - - **参数：** - - - **model** (Model) - 等待测试的预训练模型。 - - **train_dataset** (numpy.ndarray) - 用于确定神经元输出边界的训练数据集。 - - **incremental** (bool) - 指标将以增量方式计算。默认值：False。 - - **batch_size** (int) - 模糊测试批次中的样本数。默认值：32。 - - .. py:method:: get_metrics(dataset) - - 获取超激活神经元覆盖率（'super neuron activation coverage'）的指标。 - - **参数：** - - - **dataset** (numpy.ndarray) - 用于计算覆盖指标的数据集。 - - **返回：** - - - **float** - 超激活神经元覆盖率（'super neuron activation coverage'）的指标 - -.. py:class:: mindarmour.fuzz_testing.KMultisectionNeuronCoverage(model, train_dataset, segmented_num=100, incremental=False, batch_size=32) - - 获取K分神经元覆盖率的指标。KMNC度量测试集神经元输出落在训练集输出范围k等分间隔上的比例。 - - **参数：** - - - **model** (Model) - 等待测试的预训练模型。 - - **train_dataset** (numpy.ndarray) - 用于确定神经元输出边界的训练数据集。 - - **segmented_num** (int) - 神经元输出间隔的分段部分数量。默认值：100。 - - **incremental** (bool) - 指标将以增量方式计算。默认值：False。 - - **batch_size** (int) - 模糊测试批次中的样本数。默认值：32。 - - .. py:method:: get_metrics(dataset) - - 获取'k-multisection neuron coverage'的指标。 - - **参数：** - - - **dataset** (numpy.ndarray) - 用于计算覆盖指标的数据集。 - - **返回：** - - - **float** - 'k-multisection neuron coverage'的指标。 - - .. py:class:: mindarmour.fuzz_testing.Fuzzer(target_model) 深度神经网络的模糊测试框架。 @@ -90,27 +18,29 @@ mindarmour.fuzz_testing 深度神经网络的模糊测试。 **参数：** + - **mutate_config** (list) - 变异方法配置。格式为: - .. code-block:: python - mutate_config = - {'method': 'GaussianBlur', - 'params': {'ksize': [1, 2, 3, 5], 'auto_param': [True, False]}}, - {'method': 'UniformNoise', - 'params': {'factor': [0.1, 0.2, 0.3], 'auto_param': [False, True]}}, - {'method': 'GaussianNoise', - 'params': {'factor': [0.1, 0.2, 0.3], 'auto_param': [False, True]}}, - {'method': 'Contrast', - 'params': {'alpha': [0.5, 1, 1.5], 'beta': [-10, 0, 10], 'auto_param': [False, True]}}, - {'method': 'Rotate', - 'params': {'angle': [20, 90], 'auto_param': [False, True]}}, - {'method': 'FGSM', - 'params': {'eps': [0.3, 0.2, 0.4], 'alpha': [0.1], 'bounds': [(0, 1)]}}] - ...] + .. code-block:: python + + mutate_config = + {'method': 'GaussianBlur', + 'params': {'ksize': [1, 2, 3, 5], 'auto_param': [True, False]}}, + {'method': 'UniformNoise', + 'params': {'factor': [0.1, 0.2, 0.3], 'auto_param': [False, True]}}, + {'method': 'GaussianNoise', + 'params': {'factor': [0.1, 0.2, 0.3], 'auto_param': [False, True]}}, + {'method': 'Contrast', + 'params': {'alpha': [0.5, 1, 1.5], 'beta': [-10, 0, 10], 'auto_param': [False, True]}}, + {'method': 'Rotate', + 'params': {'angle': [20, 90], 'auto_param': [False, True]}}, + {'method': 'FGSM', + 'params': {'eps': [0.3, 0.2, 0.4], 'alpha': [0.1], 'bounds': [(0, 1)]}}] + ...] - 支持的方法在列表 `self._strategies` 中，每个方法的参数必须在可选参数的范围内。支持的方法分为两种类型： - 首先，自然鲁棒性方法包括：'Translate', 'Scale'、'Shear'、'Rotate'、'Perspective'、'Curve'、'GaussianBlur'、'MotionBlur'、'GradientBlur'、'Contrast'、'GradientLuminance'、'UniformNoise'、'GaussianNoise'、'SaltAndPepperNoise'、'NaturalNoise'。 - 其次，对抗样本攻击方式包括：'FGSM'、'PGD'和'MDIM'。'FGSM'、'PGD'和'MDIM'分别是 FastGradientSignMethod、ProjectedGradientDent和MomentumDiverseInputIterativeMethod的缩写。 `mutate_config` 必须包含在['Contrast', 'GradientLuminance', 'GaussianBlur', 'MotionBlur', 'GradientBlur', 'UniformNoise', 'GaussianNoise', 'SaltAndPepperNoise', 'NaturalNoise']中的方法。 - + - 第一类方法的参数设置方式可以在'mindarmour/natural_robustness/transform/image'中看到。第二类方法参数配置参考 `self._attack_param_checklists` 。 - **initial_seeds** (list[list]) - 用于生成变异样本的初始种子队列。初始种子队列的格式为[[image_data, label], [...], ...]，且标签必须为one-hot。 - **coverage** (CoverageMetrics) - 神经元覆盖率指标类。 @@ -157,7 +87,54 @@ mindarmour.fuzz_testing **异常：** - **NotImplementedError** - 抽象方法。 - + +.. py:class:: mindarmour.fuzz_testing.NeuronCoverage(model, threshold=0.1, incremental=False, batch_size=32) + + 计算神经元激活的覆盖率。当神经元的输出大于阈值时，神经元被激活。 + + 神经元覆盖率等于网络中激活的神经元占总神经元的比例。 + + **参数：** + + - **model** (Model) - 被测模型。 + - **threshold** (float) - 用于确定神经元是否激活的阈值。默认值：0.1。 + - **incremental** (bool) - 指标将以增量方式计算。默认值：False。 + - **batch_size** (int) - 模糊测试批次中的样本数。默认值：32。 + + .. py:method:: get_metrics(dataset) + 获取神经元覆盖率的指标：激活的神经元占网络中神经元总数的比例。 + + **参数：** + + - **dataset** (numpy.ndarray) - 用于计算覆盖率指标的数据集。 + + **返回：** + + - **float** - 'neuron coverage'的指标。 + +.. py:class:: mindarmour.fuzz_testing.TopKNeuronCoverage(model, top_k=3, incremental=False, batch_size=32) + + 计算前k个激活神经元的覆盖率。当隐藏层神经元的输出值在最大的'Top-k'范围内，神经元就会被激活。'Top k'神经元覆盖率等于网络中激活神经元占总神经元的比例。 + + **参数：** + + - **model** (Model) - 被测模型。 + - **top_k** (int) - 当隐藏层神经元的输出值在最大的'Top-k'范围内，神经元就会被激活。默认值：3。 + - **incremental** (bool) - 指标将以增量方式计算。默认值：False。 + - **batch_size** (int) - 模糊测试批次中的样本数。默认值：32。 + + .. py:method:: get_metrics(dataset) + + 获取Top K激活神经元覆盖率的指标。 + + **参数：** + + - **dataset** (numpy.ndarray) - 用于计算覆盖率指标的数据集。 + + **返回：** + + - **float** - 'top k neuron coverage'的指标。 + .. py:class:: mindarmour.fuzz_testing.NeuronBoundsCoverage(model, train_dataset, incremental=False, batch_size=32) 获取'neuron boundary coverage'的指标 :math:`NBC = (|UpperCornerNeuron| + |LowerCornerNeuron|)/(2*|N|)` ，其中 :math:`|N|` 是神经元的数量，NBC是指测试数据集中神经元输出值超过训练数据集中相应神经元输出值的上下界的神经元比例。 @@ -168,7 +145,7 @@ mindarmour.fuzz_testing - **train_dataset** (numpy.ndarray) - 用于确定神经元输出边界的训练数据集。 - **incremental** (bool) - 指标将以增量方式计算。默认值：False。 - **batch_size** (int) - 模糊测试批次中的样本数。默认值：32。 - + .. py:method:: get_metrics(dataset) 获取'neuron boundary coverage'的指标。 @@ -181,29 +158,49 @@ mindarmour.fuzz_testing - **float** - 'neuron boundary coverage'的指标。 - -.. py:class:: mindarmour.fuzz_testing.NeuronCoverage(model, threshold=0.1, incremental=False, batch_size=32) +.. py:class:: mindarmour.fuzz_testing.SuperNeuronActivateCoverage(model, train_dataset, incremental=False, batch_size=32) - 计算神经元激活的覆盖率。当神经元的输出大于阈值时，神经元被激活。 - - 神经元覆盖率等于网络中激活的神经元占总神经元的比例。 + 获取超激活神经元覆盖率（'super neuron activation coverage'）的指标。 :math:`SNAC = |UpperCornerNeuron|/|N|` 。SNAC是指测试集中神经元输出值超过训练集中相应神经元输出值上限的神经元比例。 **参数：** - - **model** (Model) - 被测模型。 - - **threshold** (float) - 用于确定神经元是否激活的阈值。默认值：0.1。 + - **model** (Model) - 等待测试的预训练模型。 + - **train_dataset** (numpy.ndarray) - 用于确定神经元输出边界的训练数据集。 - **incremental** (bool) - 指标将以增量方式计算。默认值：False。 - **batch_size** (int) - 模糊测试批次中的样本数。默认值：32。 .. py:method:: get_metrics(dataset) - 获取神经元覆盖率的指标：激活的神经元占网络中神经元总数的比例。 + + 获取超激活神经元覆盖率（'super neuron activation coverage'）的指标。 **参数：** - - **dataset** (numpy.ndarray) - 用于计算覆盖率指标的数据集。 + - **dataset** (numpy.ndarray) - 用于计算覆盖指标的数据集。 **返回：** - - **float** - 'neuron coverage'的指标。 + - **float** - 超激活神经元覆盖率（'super neuron activation coverage'）的指标 + +.. py:class:: mindarmour.fuzz_testing.KMultisectionNeuronCoverage(model, train_dataset, segmented_num=100, incremental=False, batch_size=32) + + 获取K分神经元覆盖率的指标。KMNC度量测试集神经元输出落在训练集输出范围k等分间隔上的比例。 + + **参数：** + + - **model** (Model) - 等待测试的预训练模型。 + - **train_dataset** (numpy.ndarray) - 用于确定神经元输出边界的训练数据集。 + - **segmented_num** (int) - 神经元输出间隔的分段部分数量。默认值：100。 + - **incremental** (bool) - 指标将以增量方式计算。默认值：False。 + - **batch_size** (int) - 模糊测试批次中的样本数。默认值：32。 + + .. py:method:: get_metrics(dataset) + + 获取'k-multisection neuron coverage'的指标。 + + **参数：** - + - **dataset** (numpy.ndarray) - 用于计算覆盖指标的数据集。 + + **返回：** + + - **float** - 'k-multisection neuron coverage'的指标。 diff --git a/docs/api/api_python/mindarmour.privacy.diff_privacy.rst b/docs/api/api_python/mindarmour.privacy.diff_privacy.rst index ccde27f..3adc397 100644 --- a/docs/api/api_python/mindarmour.privacy.diff_privacy.rst +++ b/docs/api/api_python/mindarmour.privacy.diff_privacy.rst @@ -3,22 +3,20 @@ mindarmour.privacy.diff_privacy 本模块提供差分隐私功能，以保护用户隐私。 -.. py::class:: mindarmour.privacy.diff_privacy.NoiseAdaGaussianRandom(norm_bound=1.0, initial_noise_multiplier=1.0, seed=0, noise_decay_rate=6e-06, decay_policy='Exp') +.. py:class:: mindarmour.privacy.diff_privacy.NoiseGaussianRandom(norm_bound=1.0, initial_noise_multiplier=1.0, seed=0, decay_policy=None) - 自适应高斯噪声产生机制。噪音会随着训练而衰减。衰减模式可以是'Time'、'Step'、'Exp'。 - 在模型训练过程中，将更新 `self._noise_multiplier` 。 + 基于高斯机制产生噪声，方法是 :math:`mean=0` 以及 :math:`standard\_deviation = norm\_bound * initial\_noise\_multiplier` 。 **参数：** - - **norm_bound** (float) - 梯度的l2范数的裁剪范围。默认值：1.0。 - - **initial_noise_multiplier** (float) - 高斯噪声标准偏差除以norm_bound的比率，将用于计算隐私预算。默认值：1.0。 - - **seed** (int) - 原始随机种子，如果seed=0随机正态将使用安全随机数。如果seed!=0随机正态将使用给定的种子生成值。默认值：0。 - - **noise_decay_rate** (float) - 控制噪声衰减的超参数。默认值：6e-6。 - - **decay_policy** (str) - 噪声衰减策略包括'Step'、'Time'、'Exp'。默认值：'Exp'。 + - **norm_bound** (float)- 梯度的l2范数的裁剪范围。默认值：1.0。 + - **initial_noise_multiplier** (float)- 高斯噪声标准偏差除以norm_bound的比率，将用于计算隐私预算。默认值：1.0。 + - **seed** (int)- 原始随机种子，如果seed=0随机正态将使用安全随机数。如果seed!=0随机正态将使用给定的种子生成值。默认值：0。 + - **decay_policy** (str)- 衰减策略。默认值：None。 .. py:method:: construct(gradients) - 生成的自适应高斯噪声。 + 产生的高斯噪声。 **参数：** @@ -27,65 +25,67 @@ mindarmour.privacy.diff_privacy **返回：** - **Tensor** - 生成的shape与给定梯度相同的噪声。 - -.. py::class:: mindarmour.privacy.diff_privacy.DPOptimizerClassFactory(micro_batches=2) - 优化器的工厂类。 - - **参数：** +.. py:class:: mindarmour.privacy.diff_privacy.NoiseAdaGaussianRandom(norm_bound=1.0, initial_noise_multiplier=1.0, seed=0, noise_decay_rate=6e-06, decay_policy='Exp') - - **micro_batches** (int) - 从原始批次拆分的小批次中的样本数量。默认值：2。 + 自适应高斯噪声产生机制。噪音会随着训练而衰减。衰减模式可以是'Time'、'Step'、'Exp'。 + 在模型训练过程中，将更新 `self._noise_multiplier` 。 - **返回：** + **参数：** - - **Optimizer** - 优化器类。 + - **norm_bound** (float) - 梯度的l2范数的裁剪范围。默认值：1.0。 + - **initial_noise_multiplier** (float) - 高斯噪声标准偏差除以norm_bound的比率，将用于计算隐私预算。默认值：1.0。 + - **seed** (int) - 原始随机种子，如果seed=0随机正态将使用安全随机数。如果seed!=0随机正态将使用给定的种子生成值。默认值：0。 + - **noise_decay_rate** (float) - 控制噪声衰减的超参数。默认值：6e-6。 + - **decay_policy** (str) - 噪声衰减策略包括'Step'、'Time'、'Exp'。默认值：'Exp'。 - .. py:method:: create(policy) + .. py:method:: construct(gradients) - 创建DP优化器。策略可以是'sgd'、'momentum'、'adam'。 + 生成的自适应高斯噪声。 **参数：** - - **policy** (str) - 选择原始优化器类型。 + - **gradients** (Tensor) - 梯度。 **返回：** - - **Optimizer** - 一个带有差分加噪的优化器。 + - **Tensor** - 生成的shape与给定梯度相同的噪声。 - .. py:method:: set_mechanisms(policy, *args, **kwargs) +.. py:class:: mindarmour.privacy.diff_privacy.AdaClippingWithGaussianRandom(decay_policy='Linear', learning_rate=0.001, target_unclipped_quantile=0.9, fraction_stddev=0.01, seed=0) - 获取噪音机制对象。策略可以是'Gaussian'或'AdaGaussian'。候选的args和kwargs可以在mechanisms.py的NoiseMechanismsFactory类中看到。 + 自适应剪裁。如果 `deay_policy` 是'Linear'，则更新公式 :math:`norm\_bound = norm\_bound - learning\_rate*(beta - target\_unclipped\_quantile)` 。 - **参数：** + 如果 `deay_policy` 是'Geometric'，则更新公式为 :math:`norm\_bound = norm\_bound*exp(-learning\_rate*(empirical\_fraction - target\_unclipped\_quantile))` 。 - - **policy** (str) - 选择机制类型。 + 其中，beta是值最多为 `target_unclipped_quantile` 的样本的经验分数。 - -.. py::class:: mindarmour.privacy.diff_privacy.NoiseGaussianRandom(norm_bound=1.0, initial_noise_multiplier=1.0, seed=0, decay_policy=None) + **参数：** - 基于高斯机制产生噪声，方法是 :math:`mean=0` 以及 :math:`standard\_deviation = norm\_bound * initial\_noise\_multiplier` 。 + - **decay_policy** (str) - 自适应剪裁的衰变策略， `decay_policy` 必须在['Linear', 'Geometric']中。默认值：'Linear'。 + - **learning_rate** (float) - 更新范数裁剪的学习率。默认值：0.001。 + - **target_unclipped_quantile** (float) - 范数裁剪的目标分位数。默认值：0.9。 + - **fraction_stddev** (float) - 高斯正态的stddev，用于 `empirical_fraction` ，公式为empirical_fraction + N(0, fraction_stddev)。默认值：0.01。 + - **seed** (int) - 原始随机种子，如果seed=0随机正态将使用安全随机数。如果seed!=0随机正态将使用给定的种子生成值。默认值：0。 - **参数：** + **返回：** - - **norm_bound** (float)- 梯度的l2范数的裁剪范围。默认值：1.0。 - - **initial_noise_multiplier** (float)- 高斯噪声标准偏差除以norm_bound的比率，将用于计算隐私预算。默认值：1.0。 - - **seed** (int)- 原始随机种子，如果seed=0随机正态将使用安全随机数。如果seed!=0随机正态将使用给定的种子生成值。默认值：0。 - - **decay_policy** (str)- 衰减策略。默认值：None。 + - **Tensor** - 更新后的梯度裁剪阈值。 - .. py:method:: construct(gradients) + .. py:method:: AdaClippingWithGaussianRandom.construct(empirical_fraction, norm_bound) - 产生的高斯噪声。 + 更新norm_bound的值。 **参数：** - - **gradients** (Tensor) - 梯度。 + - **empirical_fraction** (Tensor) - 梯度裁剪的经验分位数。 + - **norm_bound** (Tensor) - 梯度的l2范数的裁剪范围。 **返回：** - **Tensor** - 生成的shape与给定梯度相同的噪声。 - -.. py::class:: mindarmour.privacy.diff_privacy.NoiseMechanismsFactory - + +.. py:class:: mindarmour.privacy.diff_privacy.NoiseMechanismsFactory + 噪声机制的工厂类 噪声产生机制的包装器。它目前支持高斯随机噪声（Gaussian Random Noise）和自适应高斯随机噪声（Adaptive Gaussian Random Noise）。 @@ -111,9 +111,7 @@ mindarmour.privacy.diff_privacy - **Mechanisms** - 产生的噪声类别机制。 - - -.. py::class:: mindarmour.privacy.diff_privacy.ClipMechanismsFactory +.. py:class:: mindarmour.privacy.diff_privacy.ClipMechanismsFactory 剪裁机制的工厂类 噪声生成机制的裁剪包装器。它目前支持高斯随机噪声（Gaussian Random Noise）的自适应剪裁（Adaptive Clipping）。 @@ -139,8 +137,29 @@ mindarmour.privacy.diff_privacy - **Mechanisms** - 产生的噪声类别机制。 - -.. py::class:: mindarmour.privacy.diff_privacy.RDPMonitor(num_samples, batch_size, initial_noise_multiplier=1.5, max_eps=10.0, target_delta=0.001, max_delta=None, target_eps=None, orders=None, noise_decay_mode='Time', noise_decay_rate=0.0006, per_print_times=50, dataset_sink_mode=False) +.. py:class:: mindarmour.privacy.diff_privacy.PrivacyMonitorFactory + + DP训练隐私监视器的工厂类。 + + 详情请查看： `教程 `_。 + + .. py:method:: PrivacyMonitorFactory.create(policy, *args, **kwargs) + + 创建隐私预算监测类。 + + **参数：** + + - **policy** (str) - 监控策略，现支持'rdp'和'zcdp'。 + - 如果策略为'rdp'，监控器将根据Renyi差分隐私（Renyi differential privacy，RDP）理论计算DP训练的隐私预算； + - 如果策略为'zcdp'，监控器将根据零集中差分隐私（zero-concentrated differential privacy，zCDP）理论计算DP训练的隐私预算。注意，'zcdp'不适合子采样噪声机制。 + - **args** (Union[int, float, numpy.ndarray, list, str]) - 用于创建隐私监视器的参数。 + - **kwargs** (Union[int, float, numpy.ndarray, list, str]) - 用于创建隐私监视器的关键字参数。 + + **返回：** + + - **Callback** - 隐私监视器。 + +.. py:class:: mindarmour.privacy.diff_privacy.RDPMonitor(num_samples, batch_size, initial_noise_multiplier=1.5, max_eps=10.0, target_delta=0.001, max_delta=None, target_eps=None, orders=None, noise_decay_mode='Time', noise_decay_rate=0.0006, per_print_times=50, dataset_sink_mode=False) 基于Renyi差分隐私（RDP）理论，计算DP训练的隐私预算。根据下面的参考文献，如果随机化机制被认为具有α阶的ε'-Renyi差分隐私，它也满足常规差分隐私(ε, δ)，如下所示： @@ -149,13 +168,13 @@ mindarmour.privacy.diff_privacy 详情请查看： `教程 `_。 - 参考文献：`Rényi Differential Privacy of the Sampled Gaussian Mechanism `_。 + 参考文献： `Rényi Differential Privacy of the Sampled Gaussian Mechanism `_。 **参数：** - **num_samples** (int) - 训练数据集中的样本总数。 - **batch_size** (int) - 训练时批处理中的样本数。 - - **initial_noise_multiplier(Union[float, int]) - 高斯噪声标准偏差除以norm_bound的比率，将用于计算隐私预算。默认值：1.5。 + - **initial_noise_multiplier** (Union[float, int]) - 高斯噪声标准偏差除以norm_bound的比率，将用于计算隐私预算。默认值：1.5。 - **max_eps** (Union[float, int, None]) - DP训练的最大可接受epsilon预算，用于估计最大训练epoch。'None'表示epsilon预算没有限制。默认值：10.0。 - **target_delta** (Union[float, int, None]) - DP训练的目标delta预算。如果target_delta设置为δ，则隐私预算δ将在整个训练过程中是固定的。默认值：1e-3。 - **max_delta** (Union[float, int, None]) - DP训练的最大可接受delta预算，用于估计最大训练epoch。max_delta必须小于1，建议小于1e-3，否则会溢出。'None'表示delta预算没有限制。默认值：None。 @@ -166,79 +185,25 @@ mindarmour.privacy.diff_privacy - **per_print_times** (int) - 计算和打印隐私预算的间隔步数。默认值：50。 - **dataset_sink_mode** (bool) - 如果为True，所有训练数据都将一次性传递到设备（Ascend）。如果为False，则训练数据将在每步训练后传递到设备。默认值：False。 - .. py:method:: step_end(run_context) - - 在每个训练步骤后计算隐私预算。 - - **参数：** - - - **run_context** (RunContext) - 包含模型的一些信息。 - - .. py:method:: max_epoch_suggest() - - 估计最大训练epoch，以满足预定义的隐私预算。 - - **返回：** - - - **int** - 建议的最大训练epoch。 - - -.. py::class:: mindarmour.privacy.diff_privacy.AdaClippingWithGaussianRandom(decay_policy='Linear', learning_rate=0.001, target_unclipped_quantile=0.9, fraction_stddev=0.01, seed=0) - - 自适应剪裁。如果 `deay_policy` 是'Linear'，则更新公式 :math:`norm\_bound = norm\_bound - learning\_rate*(beta - target\_unclipped\_quantile)` 。 - - 如果 `deay_policy` 是'Geometric'，则更新公式为 :math:`norm\_bound = norm\_bound*exp(-learning\_rate*(empirical\_fraction - target\_unclipped\_quantile))` 。 - - 其中，beta是值最多为 `target_unclipped_quantile` 的样本的经验分数。 + .. py:method:: max_epoch_suggest() - **参数：** - - - **decay_policy** (str) - 自适应剪裁的衰变策略， `decay_policy` 必须在['Linear', 'Geometric']中。默认值：'Linear'。 - - **learning_rate** (float) - 更新范数裁剪的学习率。默认值：0.001。 - - **target_unclipped_quantile** (float) - 范数裁剪的目标分位数。默认值：0.9。 - - **fraction_stddev** (float) - 高斯正态的stddev，用于 `empirical_fraction` ，公式为empirical_fraction + N(0, fraction_stddev)。默认值：0.01。 - - **seed** (int) - 原始随机种子，如果seed=0随机正态将使用安全随机数。如果seed!=0随机正态将使用给定的种子生成值。默认值：0。 + 估计最大训练epoch，以满足预定义的隐私预算。 **返回：** - - **Tensor** - 更新后的梯度裁剪阈值。 - - .. py:method:: AdaClippingWithGaussianRandom.construct(empirical_fraction, norm_bound) - - 更新norm_bound的值。 - - **参数：** - - - **empirical_fraction** (Tensor) - 梯度裁剪的经验分位数。 - - **norm_bound** (Tensor) - 梯度的l2范数的裁剪范围。 + - **int** - 建议的最大训练epoch。 - **返回：** - - - **Tensor** - 生成的shape与给定梯度相同的噪声。 - -.. py::class:: mindarmour.privacy.diff_privacy.PrivacyMonitorFactory - - DP训练隐私监视器的工厂类。 - - 详情请查看： `教程 `_。 - - .. py:method:: PrivacyMonitorFactory.create(policy, *args, **kwargs) + .. py:method:: step_end(run_context) - 创建隐私预算监测类。 + 在每个训练步骤后计算隐私预算。 - **参数：** + **参数：** - - **policy** (str) - 监控策略，现支持'rdp'和'zcdp'。 - - 如果策略为'rdp'，监控器将根据Renyi差分隐私（Renyi differential privacy，RDP）理论计算DP训练的隐私预算； - - 如果策略为'zcdp'，监控器将根据零集中差分隐私（zero-concentrated differential privacy，zCDP）理论计算DP训练的隐私预算。注意，'zcdp'不适合子采样噪声机制。 - - **args** (Union[int, float, numpy.ndarray, list, str]) - 用于创建隐私监视器的参数。 - - **kwargs** (Union[int, float, numpy.ndarray, list, str]) - 用于创建隐私监视器的关键字参数。 + - **run_context** (RunContext) - 包含模型的一些信息。 - **返回：** - - **Callback** - 隐私监视器。 -.. py::class:: mindarmour.privacy.diff_privacy.ZCDPMonitor(num_samples, batch_size, initial_noise_multiplier=1.5, max_eps=10.0, target_delta=0.001, noise_decay_mode='Time', noise_decay_rate=0.0006, per_print_times=50, dataset_sink_mode=False) +.. py:class:: mindarmour.privacy.diff_privacy.ZCDPMonitor(num_samples, batch_size, initial_noise_multiplier=1.5, max_eps=10.0, target_delta=0.001, noise_decay_mode='Time', noise_decay_rate=0.0006, per_print_times=50, dataset_sink_mode=False) 基于零集中差分隐私（zCDP）理论，计算DP训练的隐私预算。根据下面的参考文献，如果随机化机制满足ρ-zCDP机制，它也满足传统的差分隐私（ε, δ），如下所示： @@ -263,6 +228,13 @@ mindarmour.privacy.diff_privacy - **per_print_times** (int) - 计算和打印隐私预算的间隔步数。默认值：50。 - **dataset_sink_mode** (bool) - 如果为True，所有训练数据都将一次性传递到设备（Ascend）。如果为False，则训练数据将在每步训练后传递到设备。默认值：False。 + .. py:method:: max_epoch_suggest() + + 估计最大训练epoch，以满足预定义的隐私预算。 + + **返回：** + + - **int** - 建议的最大训练epoch。 .. py:method:: step_end(run_context) @@ -272,16 +244,39 @@ mindarmour.privacy.diff_privacy - **run_context** (RunContext) - 包含模型的一些信息。 - .. py:method:: max_epoch_suggest() +.. py:class:: mindarmour.privacy.diff_privacy.DPOptimizerClassFactory(micro_batches=2) - 估计最大训练epoch，以满足预定义的隐私预算。 + 优化器的工厂类。 + + **参数：** + + - **micro_batches** (int) - 从原始批次拆分的小批次中的样本数量。默认值：2。 + + **返回：** + + - **Optimizer** - 优化器类。 + + .. py:method:: create(policy) + + 创建DP优化器。策略可以是'sgd'、'momentum'、'adam'。 + + **参数：** + + - **policy** (str) - 选择原始优化器类型。 **返回：** - - **int** - 建议的最大训练epoch。 + - **Optimizer** - 一个带有差分加噪的优化器。 + + .. py:method:: set_mechanisms(policy, *args, **kwargs) - -.. py::class:: mindarmour.privacy.diff_privacy.DPModel(micro_batches=2, norm_bound=1.0, noise_mech=None, clip_mech=None, **kwargs) + 获取噪音机制对象。策略可以是'Gaussian'或'AdaGaussian'。候选的args和kwargs可以在mechanisms.py的NoiseMechanismsFactory类中看到。 + + **参数：** + + - **policy** (str) - 选择机制类型。 + +.. py:class:: mindarmour.privacy.diff_privacy.DPModel(micro_batches=2, norm_bound=1.0, noise_mech=None, clip_mech=None, **kwargs) DPModel用于构建差分隐私训练的模型。 @@ -300,5 +295,3 @@ mindarmour.privacy.diff_privacy - **ValueError** - DPOptimizer和noise_mech都为None或非None。 - **ValueError** - noise_mech或DPOtimizer的mech方法是自适应的，而clip_mech不是None。 - - diff --git a/docs/api/api_python/mindarmour.privacy.evaluation.rst b/docs/api/api_python/mindarmour.privacy.evaluation.rst index c92f1dd..52152c5 100644 --- a/docs/api/api_python/mindarmour.privacy.evaluation.rst +++ b/docs/api/api_python/mindarmour.privacy.evaluation.rst @@ -3,60 +3,6 @@ mindarmour.privacy.evaluation 本模块提供了一些评估给定模型隐私泄露风险的方法。 -.. py:class:: mindarmour.privacy.evaluation.ImageInversionAttack(network, input_shape, input_bound, loss_weights=(1, 0.2, 5)) - - 一种用于通过还原图像的深层表达来重建图像的攻击方法。 - - 参考文献：`Aravindh Mahendran, Andrea Vedaldi. Understanding Deep Image Representations by Inverting Them. 2014. `_。 - - **参数：** - - - **network** (Cell) - 网络，用于推断图像的深层特征。 - - **input_shape** (tuple) - 单个网络输入的数据形状，应与给定网络一致。形状的格式应为(channel, image_width, image_height)。 - - **input_bound** (Union[tuple, list]) - 原始图像的像素范围，应该像[minimum_pixel, maximum_pixel]或(minimum_pixel, maximum_pixel)。 - - **loss_weights** (Union[list, tuple]) - InversionLoss中三个子损失的权重，可以调整以获得更好的结果。默认值：(1, 0.2, 5)。 - - **异常：** - - - **TypeError** - 网络类型不是Cell。 - - **ValueError** - input_shape的值都不是正int。 - - **ValueError** - loss_weights的值都不是正值。 - - .. py:method:: generate(target_features, iters=100) - - 根据target_features重建图像。 - - **参数：** - - **target_features** (numpy.ndarray) - 原始图像的深度表示。 `target_features` 的第一个维度应该是img_num。需要注意的是，如果img_num等于1，则 `target_features` 的形状应该是(1, dim2, dim3, ...)。 - - **iters** (int) - 逆向攻击的迭代次数，应为正整数。默认值：100。 - - **返回：** - - - **numpy.ndarray** - 重建图像，预计与原始图像相似。 - - **异常：** - - - **TypeError** - target_features的类型不是numpy.ndarray。 - - **ValueError** - iters的值都不是正int.Z - - .. py:method:: evaluate(original_images, inversion_images, labels=None, new_network=None) - - 通过三个指标评估还原图像的质量：原始图像和还原图像之间的平均L2距离和SSIM值，以及新模型对还原图像的推理结果在真实标签上的置信度平均值。 - - **参数：** - - - **original_images** (numpy.ndarray) - 原始图像，其形状应为(img_num, channels, img_width, img_height)。 - - **inversion_images** (numpy.ndarray) - 还原图像，其形状应为(img_num, channels, img_width, img_height)。 - - **labels** (numpy.ndarray) - 原始图像的ground truth标签。默认值：None。 - - **new_network** (Cell) - 其结构包含self._network所有部分的网络。_network，但加载了不同的模型文件。默认值：None。 - - **返回：** - - - **float** - l2距离。 - - **float** - 平均ssim值。 - - **Union[float, None]** - 平均置信度。如果labels或new_network为 None，则该值为None。 - - .. py:class:: mindarmour.privacy.evaluation.MembershipInference(model, n_jobs=-1) 成员推理是由Shokri、Stronati、Song和Shmatikov提出的一种用于推断用户隐私数据的灰盒攻击。它需要训练样本的loss或logits结果。 @@ -64,16 +10,15 @@ mindarmour.privacy.evaluation 有关详细信息，请参见： `教程 `_。 - 参考文献：`Reza Shokri, Marco Stronati, Congzheng Song, Vitaly Shmatikov. - Membership Inference Attacks against Machine Learning Models. 2017. `_。 + 参考文献：`Reza Shokri, Marco Stronati, Congzheng Song, Vitaly Shmatikov. Membership Inference Attacks against Machine Learning Models. 2017. `_。 **参数：** - + - **model** (Model) - 目标模型。 - **n_jobs** (int) - 并行运行的任务数量。-1表示使用所有处理器，否则n_jobs的值必须为正整数。 **异常：** - + - **TypeError** - 模型的类型不是Mindpore.train.Model。 - **TypeError** - n_jobs的类型不是int。 - **ValueError** - n_jobs的值既不是-1，也不是正整数。 @@ -85,15 +30,15 @@ mindarmour.privacy.evaluation 评估指标应由metrics规定。 **参数：** - + - **dataset_train** (minspore.dataset) - 目标模型的训练数据集。 - **dataset_test** (minspore.dataset) - 目标模型的测试数据集。 - **metrics** (Union[list, tuple]) - 评估指标。指标的值必须在["precision", "accuracy", "recall"]中。默认值：["precision"]。 **返回：** - + - **list** - 每个元素都包含攻击模型的评估指标。 - + .. py:method:: train(dataset_train, dataset_test, attack_config) 根据配置，使用输入数据集训练攻击模型。 @@ -101,14 +46,15 @@ mindarmour.privacy.evaluation 将攻击模型保存至self._attack_list。 **参数：** - + - **dataset_train** (minspore.dataset) - 目标模型的训练数据集。 - **dataset_test** (minspore.dataset) - 目标模型的测试集。 - **attack_config** (Union[list, tuple]) - 攻击模型的参数设置。格式为 .. code-block:: python - attack_config = - [{"method": "knn", "params": {"n_neighbors": [3, 5, 7]}}, - {"method": "lr", "params": {"C": np.logspace(-4, 2, 10)}}] + + attack_config = + [{"method": "knn", "params": {"n_neighbors": [3, 5, 7]}}, + {"method": "lr", "params": {"C": np.logspace(-4, 2, 10)}}] - 支持的方法有knn、lr、mlp和rf，每个方法的参数必须在可变参数的范围内。参数实现的提示可在下面找到： - `KNN `_, @@ -117,7 +63,60 @@ mindarmour.privacy.evaluation - `MLP `_. **异常：** - + - **KeyError** - attack_config中的配置没有键{"method", "params"}。 - **NameError** - attack_config中的方法（不区分大小写）不在["lr", "knn", "rf", "mlp"]中。 - + +.. py:class:: mindarmour.privacy.evaluation.ImageInversionAttack(network, input_shape, input_bound, loss_weights=(1, 0.2, 5)) + + 一种用于通过还原图像的深层表达来重建图像的攻击方法。 + + 参考文献：`Aravindh Mahendran, Andrea Vedaldi. Understanding Deep Image Representations by Inverting Them. 2014. `_。 + + **参数：** + + - **network** (Cell) - 网络，用于推断图像的深层特征。 + - **input_shape** (tuple) - 单个网络输入的数据形状，应与给定网络一致。形状的格式应为(channel, image_width, image_height)。 + - **input_bound** (Union[tuple, list]) - 原始图像的像素范围，应该像[minimum_pixel, maximum_pixel]或(minimum_pixel, maximum_pixel)。 + - **loss_weights** (Union[list, tuple]) - InversionLoss中三个子损失的权重，可以调整以获得更好的结果。默认值：(1, 0.2, 5)。 + + **异常：** + + - **TypeError** - 网络类型不是Cell。 + - **ValueError** - input_shape的值都不是正int。 + - **ValueError** - loss_weights的值都不是正值。 + + .. py:method:: evaluate(original_images, inversion_images, labels=None, new_network=None) + + 通过三个指标评估还原图像的质量：原始图像和还原图像之间的平均L2距离和SSIM值，以及新模型对还原图像的推理结果在真实标签上的置信度平均值。 + + **参数：** + + - **original_images** (numpy.ndarray) - 原始图像，其形状应为(img_num, channels, img_width, img_height)。 + - **inversion_images** (numpy.ndarray) - 还原图像，其形状应为(img_num, channels, img_width, img_height)。 + - **labels** (numpy.ndarray) - 原始图像的ground truth标签。默认值：None。 + - **new_network** (Cell) - 其结构包含self._network所有部分的网络。_network，但加载了不同的模型文件。默认值：None。 + + **返回：** + + - **float** - l2距离。 + - **float** - 平均ssim值。 + - **Union[float, None]** - 平均置信度。如果labels或new_network为 None，则该值为None。 + + .. py:method:: generate(target_features, iters=100) + + 根据target_features重建图像。 + + **参数：** + - **target_features** (numpy.ndarray) - 原始图像的深度表示。 `target_features` 的第一个维度应该是img_num。需要注意的是，如果img_num等于1，则 `target_features` 的形状应该是(1, dim2, dim3, ...)。 + - **iters** (int) - 逆向攻击的迭代次数，应为正整数。默认值：100。 + + **返回：** + + - **numpy.ndarray** - 重建图像，预计与原始图像相似。 + + **异常：** + + - **TypeError** - target_features的类型不是numpy.ndarray。 + - **ValueError** - iters的值都不是正int.Z + diff --git a/docs/api/api_python/mindarmour.privacy.sup_privacy.rst b/docs/api/api_python/mindarmour.privacy.sup_privacy.rst index 18a303a..eacab67 100644 --- a/docs/api/api_python/mindarmour.privacy.sup_privacy.rst +++ b/docs/api/api_python/mindarmour.privacy.sup_privacy.rst @@ -3,51 +3,24 @@ mindarmour.privacy.sup_privacy 本模块提供抑制隐私功能，以保护用户隐私。 -.. py:class:: mindarmour.privacy.sup_privacy.MaskLayerDes(layer_name, grad_idx, is_add_noise, is_lower_clip, min_num, upper_bound=1.2) - - 描述需要抑制的层。 - - **参数：** - - - **layer_name** (str) - 层名称，如下获取一个层的名称： - - .. code-block:: - for layer in networks.get_parameters(expand=True): +.. py:class:: mindarmour.privacy.sup_privacy.SuppressMasker(model, suppress_ctrl) - - **grad_idx** (int) - Grad层索引，在grad元组中获取掩码层的索引。您可以参考mindarmour/privacy/sup_privacy/train/model.py中TrainOneStepCell的构造函数，获取某些指定的grad层的索引（在PYNATIVE_MODE中打印）。 - - **is_add_noise** (bool) - 如果为True，则此层的权重可以添加噪声。如果为False，则此层的权重不能添加噪声。如果参数num大于100000，则is_add_noise无效。 - - **is_lower_clip** (bool) - 如果为True，则此层的权重将被剪裁到大于下限值。如果为False，此层的权重不会被要求大于下限制。如果参数num大于100000，则is_lower_clip无效。 - - **min_num** (int) - 未抑制的剩余权重数。如果min_num小于（参数num*SupperssCtrl.sparse_end），则min_num无效。 - - **upper_bound** (Union[float, int]) - 此层权重的最大abs值，默认值：1.20。如果参数num大于100000，则upper_bound无效。 + 周期性检查抑制隐私功能状态和切换（启动/关闭）抑制操作。 + 详情请查看： `教程 `_。 + **参数：** -.. py:class:: mindarmour.privacy.sup_privacy.SuppressPrivacyFactory + - **model** (SuppressModel) - SuppressModel 实例。 + - **suppress_ctrl** (SuppressCtrl) - SuppressCtrl实例。 - SuppressCtrl机制的工厂类。 + .. py:method:: step_end(run_context) - 详情请查看： `教程 `_。 - - .. py:method:: create(networks, mask_layers, policy='local_train', end_epoch=10, batch_num=20, start_epoch=3, mask_times=1000, lr=0.05, sparse_end=0.9, sparse_start=0.0) + 更新用于抑制模型实例的掩码矩阵张量。 **参数：** - - **networks** (Cell) - 要训练的神经网络模型。此网络参数应与SuppressModel()的'network'参数相同。 - - **mask_layers** (list) - 需要抑制的训练网络层的描述。 - - **policy** (str) - 抑制隐私训练的训练策略。默认值："local_train"，表示本地训练。 - - **end_epoch** (int) - 最后一次抑制操作对应的epoch序号，0`_。 - **参数：** + .. py:method:: create(networks, mask_layers, policy='local_train', end_epoch=10, batch_num=20, start_epoch=3, mask_times=1000, lr=0.05, sparse_end=0.9, sparse_start=0.0) - - **model** (SuppressModel) - SuppressModel 实例。 - - **suppress_ctrl** (SuppressCtrl) - SuppressCtrl实例。 + **参数：** - .. py:method:: step_end(run_context) + - **networks** (Cell) - 要训练的神经网络模型。此网络参数应与SuppressModel()的'network'参数相同。 + - **mask_layers** (list) - 需要抑制的训练网络层的描述。 + - **policy** (str) - 抑制隐私训练的训练策略。默认值："local_train"，表示本地训练。 + - **end_epoch** (int) - 最后一次抑制操作对应的epoch序号，0`_。 + 详情请查看 `教程 `_。 **参数：** - **model** (Model) - 需要评估模型。 - - **fi_type** (list) - 故障注入的类型，包括bitflips_random（随机翻转）、bitflips_designated（翻转关键位）、random、zeros、na- **n、inf、anti_activation precision_loss等。 + - **fi_type** (list) - 故障注入的类型，包括bitflips_random（随机翻转）、bitflips_designated（翻转关键位）、random、zeros、nan、inf、anti_activation precision_loss等。 - **fi_mode** (list) - 故障注入的模式。仅在单层或所有层上注入故障。 - **fi_size** (list) - 故障注入的次数，表示需要注入多少值。 - .. py:method:: kick_off(ds_data, ds_label, iter_times=100) 故障注入后启动并返回最终结果。 @@ -30,7 +29,7 @@ MindArmour的可靠性方法。 **返回：** - **list** - 故障注入的结果。 - + .. py:method:: metrics() 最终结果的指标。 @@ -39,7 +38,36 @@ MindArmour的可靠性方法。 - **list** - 结果总结。 -..py:class:: mindarmour.reliability.OodDetector(model, ds_train) +.. py:class:: mindarmour.reliability.ConceptDriftCheckTimeSeries(window_size=100, rolling_window=10, step=10, threshold_index=1.5, need_label=False) + + 概念漂移检查时间序列（ConceptDriftCheckTimeSeries）用于样本序列分布变化检测。 + 有关详细信息，请查看 `教程 `_。 + + **参数：** + + - **window_size** (int) - 概念窗口的大小，不小于10。如果给定输入数据，window_size在[10, 1/3*len(input_data)]中。 + 如果数据是周期性的，通常window_size等于2-5个周期。例如，对于月/周数据，30/7天的数据量是一个周期。默认值：100。 + - **rolling_window** (int) - 平滑窗口大小，在[1, window_size]中。默认值：10。 + - **step** (int) - 滑动窗口的跳跃长度，在[1, window_size]中。默认值：10。 + - **threshold_index** (float) - 阈值索引，:math:`(-\infty, +\infty)` 。默认值：1.5。 + - **need_label** (bool) - False或True。如果need_label=True，则需要概念漂移标签。默认值：False。 + + .. py:method:: concept_check(data) + + 在数据系列中查找概念漂移位置。 + + **参数：** + + - **data** (numpy.ndarray) - 输入数据。数据的shape可以是(n,1)或(n,m)。 + 请注意，每列（m列）是一个数据序列。 + + **返回：** + + - **numpy.ndarray** - 样本序列的概念漂移分数。 + - **float** - 判断概念漂移的阈值。 + - **list** - 概念漂移的位置。 + +.. py:class:: mindarmour.reliability.OodDetector(model, ds_train) 分布外检测器的抽象类。 @@ -73,75 +101,42 @@ MindArmour的可靠性方法。 **返回：** - **numpy.ndarray** - 检测结果。0表示数据不是ood，1表示数据是ood。 - - -..py:class:: mindarmour.reliability.ConceptDriftCheckTimeSeries(window_size=100, rolling_window=10, step=10, threshold_index=1.5, need_label=False) - 概念漂移检查时间序列（ConceptDriftCheckTimeSeries）用于样本序列分布变化检测。 - 有关详细信息，请查看`教程`_。 - - **参数：** - - - **window_size** (int) - 概念窗口的大小，不小于10。如果给定输入数据，window_size在[10, 1/3*len(input_data)]中。 - 如果数据是周期性的，通常window_size等于2-5个周期。例如，对于月/周数据，30/7天的数据量是一个周期。默认值：100。 - - **rolling_window** (int) - 平滑窗口大小，在[1, window_size]中。默认值：10。 - - **step** (int) - 滑动窗口的跳跃长度，在[1, window_size]中。默认值：10。 - - **threshold_index** (float) - 阈值索引，:math:`(-\infty, +\infty)` 。默认值：1.5。 - - **need_label** (bool) - False或True。如果need_label=True，则需要概念漂移标签。默认值：False。 - - .. py:method:: concept_check(data) - - 在数据系列中查找概念漂移位置。 - - **参数：** - - - **data** (numpy.ndarray) - 输入数据。数据的shape可以是(n,1)或(n,m)。 - 请注意，每列（m列）是一个数据序列。 - - **返回：** - - - **numpy.ndarray** - 样本序列的概念漂移分数。 - - **float** - 判断概念漂移的阈值。 - - **list** - 概念漂移的位置。 - - -..py:class:: mindarmour.reliability.OodDetectorFeatureCluster(model, ds_train, n_cluster, layer) +.. py:class:: mindarmour.reliability.OodDetectorFeatureCluster(model, ds_train, n_cluster, layer) 训练OOD检测器。提取训练数据特征，得到聚类中心。测试数据特征与聚类中心之间的距离确定图像是否为分布外（OOD）图像。 - 有关详细信息，请查看`教程`_。 + 有关详细信息，请查看 `教程 `_。 **参数：** - **model** (Model) - 训练模型。 - **ds_train** (numpy.ndarray) - 训练数据集。 - **n_cluster** (int) - 聚类编号。取值属于[2,100]。 - 通常，n_cluster等于训练数据集的类号。如果OOD检测器在测试数据集中性能较差，我们可以适当增加n_cluster的值。 + 通常，n_cluster等于训练数据集的类号。如果OOD检测器在测试数据集中性能较差，我们可以适当增加n_cluster的值。 - **layer** (str) - 特征层的名称。layer (str)由'name[:Tensor]'表示，其中'name'由用户在训练模型时给出。 - 请查看有关如何在'README.md'中命名模型层的更多详细信息。 - - .. py:method:: ood_predict(threshold, ds_test) + 请查看有关如何在'README.md'中命名模型层的更多详细信息。 - 分布外（out-of-distribution，OOD）检测。此函数的目的是检测被视为 `ds_test` 的图像是否为OOD样本。如果一张图像的预测分数大于 `threshold` ，则该图像为分布外。 + .. py:method:: get_optimal_threshold(label, ds_eval) **参数：** - - **threshold** (float) - 判断ood数据的阈值。可以根据经验设置值，也可以使用函数get_optimal_threshold。 - - **ds_test** (numpy.ndarray) - 测试数据集。 + - **label** (numpy.ndarray) - 区分图像是否为分布内或分布外的标签。 + - **ds_eval** (numpy.ndarray) - 帮助查找阈值的测试数据集。 **返回：** - - **numpy.ndarray** - 检测结果。0表示数据不是ood，1表示数据是ood。 + - **float** - 最佳阈值。 - .. py:method:: get_optimal_threshold(label, ds_eval) + .. py:method:: ood_predict(threshold, ds_test) + 分布外（out-of-distribution，OOD）检测。此函数的目的是检测被视为 `ds_test` 的图像是否为OOD样本。如果一张图像的预测分数大于 `threshold` ，则该图像为分布外。 **参数：** - - **label** (numpy.ndarray) - 区分图像是否为分布内或分布外的标签。 - - **ds_eval** (numpy.ndarray) - 帮助查找阈值的测试数据集。 + - **threshold** (float) - 判断ood数据的阈值。可以根据经验设置值，也可以使用函数get_optimal_threshold。 + - **ds_test** (numpy.ndarray) - 测试数据集。 **返回：** - - **float** - 最佳阈值。 - + - **numpy.ndarray** - 检测结果。0表示数据不是ood，1表示数据是ood。 diff --git a/docs/api/api_python/mindarmour.rst b/docs/api/api_python/mindarmour.rst index 05a6f99..9f301db 100644 --- a/docs/api/api_python/mindarmour.rst +++ b/docs/api/api_python/mindarmour.rst @@ -6,7 +6,7 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 .. py:class:: mindarmour.Attack 所有通过创建对抗样本的攻击类的抽象基类。 - + 对抗样本是通过向原始样本添加对抗噪声来生成的。 .. py:method:: batch_generate(inputs, labels, batch_size=64) @@ -22,7 +22,7 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 **返回：** - **numpy.ndarray** - 生成的对抗样本。 - + .. py:method:: generate(inputs, labels) 根据正常样本及其标签生成对抗样本。 @@ -35,144 +35,6 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 **异常：** - **NotImplementedError** - 此为抽象方法。 - -.. py:class:: mindarmour.MembershipInference(model, n_jobs=-1) - - 成员推理是由Shokri、Stronati、Song和Shmatikov提出的一种用于推测用户隐私数据的灰盒攻击。它需要训练样本的loss或logits结果。（隐私是指单个用户的一些敏感属性）。 - - 有关详细信息，请参见 ：`教程 `_。 - - 参考文献：`Reza Shokri, Marco Stronati, Congzheng Song, Vitaly Shmatikov. Membership Inference Attacks against Machine Learning Models. 2017. `_。 - - **参数：** - - - **model** (Model) - 目标模型。 - - **n_jobs** (int) - 并行运行的任务数量。-1表示使用所有处理器，否则n_jobs的值必须为正整数。 - - **异常：** - - - **TypeError** - 模型的类型不是Mindspore.Model。 - - **TypeError** - n_jobs的类型不是int。 - - **ValueError** - n_jobs的值既不是-1，也不是正整数。 - - .. py:method:: train(dataset_train, dataset_test, attack_config) - - 根据配置，使用输入数据集训练攻击模型。 - - 将攻击模型保存至self._attack_list。 - - **参数：** - - - **dataset_train** (minspore.dataset) - 目标模型的训练数据集。 - - **dataset_test** (minspore.dataset) - 目标模型的测试集。 - - **attack_config** (Union[list, tuple]) - 攻击模型的参数设置。格式为 - .. code_block:: - attack_config = - [{"method": "knn", "params": {"n_neighbors": [3, 5, 7]}}, - {"method": "lr", "params": {"C": np.logspace(-4, 2, 10)}}] - - - 支持的方法有knn、lr、mlp和rf，每个方法的参数必须在可变参数的范围内。参数实现的提示可在下面找到： - - `KNN `_ ， - - `LR `_ ， - - `RF `_ ， - - `MLP `_ 。 - - **异常：** - - - **KeyError** - attack_config中的配置没有键{"method", "params"}。 - - **NameError** - attack_config中的方法（不区分大小写）不在["lr", "knn", "rf", "mlp"]中。 - - .. py:method:: eval(dataset_train, dataset_test, metrics) - - 评估目标模型的不同隐私。 - 评估指标应由metrics规定。 - - **参数：** - - - **dataset_train** (minspore.dataset) - 目标模型的训练数据集。 - - **dataset_test** (minspore.dataset) - 目标模型的测试数据集。 - - **metrics** (Union[list, tuple]) - 评估指标。指标的值必须在["precision", "accuracy", "recall"]中。默认值：["precision"]。 - - **返回：** - - - **list** - 每个元素都包含攻击模型的评估指标。 - - -.. py:class:: mindarmour.ImageInversionAttack(network, input_shape, input_bound, loss_weights=(1, 0.2, 5)) - - 一种用于通过还原图像的深层表达来重建图像的攻击方法。 - - 参考文献：`Aravindh Mahendran, Andrea Vedaldi. Understanding Deep Image Representations by Inverting Them. 2014. `_。 - - **参数：** - - - **network** (Cell) - 网络，用于推断图像的深层特征。 - - **input_shape** (tuple) - 单个网络输入的数据形状，应与给定网络一致。形状的格式应为(channel, image_width, image_height)。 - - **input_bound** (Union[tuple, list]) - 原始图像的像素范围，应该像[minimum_pixel, maximum_pixel]或(minimum_pixel, maximum_pixel)。 - - **loss_weights** (Union[list, tuple]) - InversionLoss中三个子损失的权重，可以调整以获得更好的结果。默认值：(1, 0.2, 5)。 - - **异常：** - - - **TypeError** - 网络类型不是Cell。 - - **ValueError** - input_shape的值都不是正int。 - - **ValueError** - loss_weights的值都不是正值。 - - - .. py:method:: generate(target_features, iters=100) - - 根据target_features重建图像。 - - **参数：** - - - **iters** (int) - 逆向攻击的迭代次数，应为正整数。默认值：100。 - - **返回：** - - - **numpy.ndarray** - 重建图像，预计与原始图像相似。 - - **异常：** - - - **TypeError** - target_features的类型不是numpy.ndarray。 - - **ValueError** - iters的值都不是正int.Z - - .. py:method:: evaluate(original_images, inversion_images, labels=None, new_network=None) - - 通过三个指标评估还原图像的质量：原始图像和还原图像之间的平均L2距离和SSIM值，以及新模型对还原图像的推理结果在真实标签上的置信度平均值。 - - **参数：** - - - **original_images** (numpy.ndarray) - 原始图像，其形状应为(img_num, channels, img_width, img_height)。 - - **inversion_images** (numpy.ndarray) - 还原图像，其形状应为(img_num, channels, img_width, img_height)。 - - **labels** (numpy.ndarray) - 原始图像的ground truth标签。默认值：None。 - - **new_network** (Cell) - 其结构包含self._network所有部分的网络。_network，但加载了不同的模型文件。默认值：None。 - - **返回：** - - - **float** - l2距离。 - - **float** - 平均ssim值。 - - **Union** [float, None] - 平均置信度。如果labels或new_network为 None，则该值为None。 - - -.. py:class:: mindarmour.DPModel(micro_batches=2, norm_bound=1.0, noise_mech=None, clip_mech=None, **kwargs) - - DPModel用于构建差分隐私训练的模型。 - - 这个类就是重载Mindpore.train.model.Model。 - - 详情请查看：`教程 `_。 - - **参数：** - - - **micro_batches** (int) - 从原始批次拆分的小批次数。默认值：2。 - - **norm_bound** (float) - 用于剪裁绑定，如果设置为1，将返回原始数据。默认值：1.0。 - - **norm_bound** (float) - 对象可以生成不同类型的噪音。默认值：None。 - - **clip_mech** (Mechanisms) - 该对象用于更新自适应剪裁。默认值：None。 - - **异常：** - - - **ValueError** - DPOptimizer和noise_mech都为None或非None。 - - **ValueError** - noise_mech或DPOtimizer的mech方法是自适应的，而clip_mech不是None。 - .. py:class:: mindarmour.BlackModel @@ -191,7 +53,7 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 **返回：** - **bool** - 如果为True，则输入样本是对抗性的。如果为False，则输入样本不是对抗性的。 - + .. py:method:: predict(inputs) 使用用户指定的模型进行预测。预测结果的shape应该是(m,n)，其中n表示此模型分类的类数。 @@ -203,25 +65,23 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 **异常：** - **NotImplementedError** - 抽象方法未实现。 - - + .. py:class:: mindarmour.Detector 所有对抗样本检测器的抽象基类。 - - .. py:method:: fit(inputs, labels=None) - 拟合阈值，拒绝与去噪样本差异大于阈值的对抗样本。当应用于正常样本时，阈值由假正率决定。 + .. py:method:: detect(inputs) + + 从输入样本中检测对抗样本。 **参数：** - - **inputs** (numpy.ndarray) - 用于计算阈值的输入样本。 - - **labels** (numpy.ndarray) - 训练数据的标签。默认值：None。 + - **inputs** (Union[numpy.ndarray, list, tuple]) - 要检测的输入样本。 **异常：** - **NotImplementedError** - 抽象方法未实现。 - + .. py:method:: detect_diff(inputs) 计算输入样本和去噪样本之间的差值。 @@ -234,14 +94,14 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 - **NotImplementedError** - 抽象方法未实现。 - - .. py:method:: detect(inputs) + .. py:method:: fit(inputs, labels=None) - 从输入样本中检测对抗样本。 + 拟合阈值，拒绝与去噪样本差异大于阈值的对抗样本。当应用于正常样本时，阈值由假正率决定。 **参数：** - - **inputs** (Union[numpy.ndarray, list, tuple]) - 要检测的输入样本。 + - **inputs** (numpy.ndarray) - 用于计算阈值的输入样本。 + - **labels** (numpy.ndarray) - 训练数据的标签。默认值：None。 **异常：** @@ -254,7 +114,7 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 **参数：** - **inputs** (Union[numpy.ndarray, list, tuple]) - 要转换的输入样本。 - + **异常：** - **NotImplementedError** - 抽象方法未实现。 @@ -266,7 +126,7 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 **参数：** - **network** (Cell) - 要防御的MindSpore风格的深度学习模型。 - + .. py:method:: batch_defense(inputs, labels, batch_size=32, epochs=5) 带有批量样本的防御模型。 @@ -285,7 +145,7 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 **异常：** - **ValueError** - batch_size为0。 - + .. py:method:: defense(inputs, labels) 带样本的防御模型。 @@ -298,40 +158,12 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 **异常：** - **NotImplementedError** - 抽象方法未实现。 - -.. py:class:: mindarmour.ConceptDriftCheckTimeSeries(window_size=100, rolling_window=10, step=10, threshold_index=1.5, need_label=False) - - 概念漂移检查时间序列（ConceptDriftCheckTimeSeries）用于样本序列分布变化检测。 - - 有关详细信息，请查看：`教程 `_. - - **参数：** - - - **window_size** (int) - 概念窗口的大小，不小于10。如果给定输入数据，window_size在[10, 1/3*len(input data)]中。如果数据是周期性的，通常window_size等于2-5个周期，例如，对于月/周数据，30/7天的数据量是一个周期。默认值：100。 - - **rolling_window** (int) - 平滑窗口大小，在[1, window_size]中。默认值：10。 - - **step** (int) - 滑动窗口的跳跃长度，在[1, window_size]中。默认值：10。 - - **threshold_index** (float) - 阈值索引，:math:`(-\infty, +\infty)`。默认值：1.5。 - - **need_label** (bool) - False或True。如果need_label=True，则需要概念漂移标签。默认值：False。 - - .. py:method:: concept_check(data) - - 在数据系列中查找概念漂移位置。 - - **参数：** - - - **data(numpy.ndarray) - 输入数据。数据的shape可以是(n,1)或(n,m)。请注意，每列（m列）是一个数据序列。 - **返回：** - - - **numpy.ndarray** - 样本序列的概念漂移分数。 - - **float** - 判断概念漂移的阈值。 - - **list** - 概念漂移的位置。 - -.. py::class:: mindarmour.Fuzzer(target_model) +.. py:class:: mindarmour.Fuzzer(target_model) 深度神经网络的模糊测试框架。 - 参考文献：`DeepHunter: A Coverage-Guided Fuzz Testing Framework for Deep Neural Networks `_。 + 参考文献： `DeepHunter: A Coverage-Guided Fuzz Testing Framework for Deep Neural Networks `_。 **参数：** @@ -340,10 +172,11 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 .. py:method:: fuzzing(mutate_config, initial_seeds, coverage, evaluate=True, max_iters=10000, mutate_num_per_seed=20) 深度神经网络的模糊测试。 - **参数：** + **参数：** - **mutate_config** (list) - 变异方法配置。格式为: .. code-block:: python + mutate_config = [{'method': 'GaussianBlur', 'params': {'ksize': [1, 2, 3, 5], 'auto_param': [True, False]}}, @@ -362,7 +195,7 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 - 支持的方法在列表 `self._strategies` 中，每个方法的参数必须在可选参数的范围内。支持的方法分为两种类型： - 首先，自然鲁棒性方法包括：'Translate', 'Scale'、'Shear'、'Rotate'、'Perspective'、'Curve'、'GaussianBlur'、'MotionBlur'、'GradientBlur'、'Contrast'、'GradientLuminance'、'UniformNoise'、'GaussianNoise'、'SaltAndPepperNoise'、'NaturalNoise'。 - 其次，对抗样本攻击方式包括：'FGSM'、'PGD'和'MDIM'。'FGSM'、'PGD'和'MDIM'分别是 FastGradientSignMethod、ProjectedGradientDent和MomentumDiverseInputIterativeMethod的缩写。 `mutate_config` 必须包含在['Contrast', 'GradientLuminance', 'GaussianBlur', 'MotionBlur', 'GradientBlur', 'UniformNoise', 'GaussianNoise', 'SaltAndPepperNoise', 'NaturalNoise']中的方法。 - + - 第一类方法的参数设置方式可以在 `mindarmour/natural_robustness/transform/image `_ 中看到。第二类方法参数配置参考 `self._attack_param_checklists` 。 - **initial_seeds** (list[list]) - 用于生成变异样本的初始种子队列。初始种子队列的格式为[[image_data, label], [...], ...]，且标签必须为one-hot。 - **coverage** (CoverageMetrics) - 神经元覆盖率指标类。 @@ -383,4 +216,166 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 - **ValueError** - 参数'Coverage'必须是CoverageMetrics的子类。 - **ValueError** - 初始种子队列为空。 - **ValueError** - 初始种子队列中的种子不是包含两个元素。 - + +.. py:class:: mindarmour.DPModel(micro_batches=2, norm_bound=1.0, noise_mech=None, clip_mech=None, **kwargs) + + DPModel用于构建差分隐私训练的模型。 + + 这个类就是重载Mindpore.train.model.Model。 + + 详情请查看： `教程 `_。 + + **参数：** + + - **micro_batches** (int) - 从原始批次拆分的小批次数。默认值：2。 + - **norm_bound** (float) - 用于剪裁绑定，如果设置为1，将返回原始数据。默认值：1.0。 + - **norm_bound** (float) - 对象可以生成不同类型的噪音。默认值：None。 + - **clip_mech** (Mechanisms) - 该对象用于更新自适应剪裁。默认值：None。 + + **异常：** + + - **ValueError** - DPOptimizer和noise_mech都为None或非None。 + - **ValueError** - noise_mech或DPOtimizer的mech方法是自适应的，而clip_mech不是None。 + +.. py:class:: mindarmour.MembershipInference(model, n_jobs=-1) + + 成员推理是由Shokri、Stronati、Song和Shmatikov提出的一种用于推测用户隐私数据的灰盒攻击。它需要训练样本的loss或logits结果。（隐私是指单个用户的一些敏感属性）。 + + 有关详细信息，请参见：`教程 `_。 + + 参考文献：`Reza Shokri, Marco Stronati, Congzheng Song, Vitaly Shmatikov. Membership Inference Attacks against Machine Learning Models. 2017. `_。 + + **参数：** + + - **model** (Model) - 目标模型。 + - **n_jobs** (int) - 并行运行的任务数量。-1表示使用所有处理器，否则n_jobs的值必须为正整数。 + + **异常：** + + - **TypeError** - 模型的类型不是Mindspore.Model。 + - **TypeError** - n_jobs的类型不是int。 + - **ValueError** - n_jobs的值既不是-1，也不是正整数。 + + .. py:method:: eval(dataset_train, dataset_test, metrics) + + 评估目标模型的不同隐私。 + 评估指标应由metrics规定。 + + **参数：** + + - **dataset_train** (minspore.dataset) - 目标模型的训练数据集。 + - **dataset_test** (minspore.dataset) - 目标模型的测试数据集。 + - **metrics** (Union[list, tuple]) - 评估指标。指标的值必须在["precision", "accuracy", "recall"]中。默认值：["precision"]。 + + **返回：** + + - **list** - 每个元素都包含攻击模型的评估指标。 + + .. py:method:: train(dataset_train, dataset_test, attack_config) + + 根据配置，使用输入数据集训练攻击模型。 + + 将攻击模型保存至self._attack_list。 + + **参数：** + + - **dataset_train** (minspore.dataset) - 目标模型的训练数据集。 + - **dataset_test** (minspore.dataset) - 目标模型的测试集。 + - **attack_config** (Union[list, tuple]) - 攻击模型的参数设置。格式为 + .. code_block:: + + attack_config = + [{"method": "knn", "params": {"n_neighbors": [3, 5, 7]}}, + {"method": "lr", "params": {"C": np.logspace(-4, 2, 10)}}] + + - 支持的方法有knn、lr、mlp和rf，每个方法的参数必须在可变参数的范围内。参数实现的提示可在下面找到： + - `KNN `_ ， + - `LR `_ ， + - `RF `_ ， + - `MLP `_ 。 + + **异常：** + + - **KeyError** - attack_config中的配置没有键{"method", "params"}。 + - **NameError** - attack_config中的方法（不区分大小写）不在["lr", "knn", "rf", "mlp"]中。 + +.. py:class:: mindarmour.ImageInversionAttack(network, input_shape, input_bound, loss_weights=(1, 0.2, 5)) + + 一种用于通过还原图像的深层表达来重建图像的攻击方法。 + + 参考文献：`Aravindh Mahendran, Andrea Vedaldi. Understanding Deep Image Representations by Inverting Them. 2014. `_。 + + **参数：** + + - **network** (Cell) - 网络，用于推断图像的深层特征。 + - **input_shape** (tuple) - 单个网络输入的数据形状，应与给定网络一致。形状的格式应为(channel, image_width, image_height)。 + - **input_bound** (Union[tuple, list]) - 原始图像的像素范围，应该像[minimum_pixel, maximum_pixel]或(minimum_pixel, maximum_pixel)。 + - **loss_weights** (Union[list, tuple]) - InversionLoss中三个子损失的权重，可以调整以获得更好的结果。默认值：(1, 0.2, 5)。 + + **异常：** + + - **TypeError** - 网络类型不是Cell。 + - **ValueError** - input_shape的值都不是正int。 + - **ValueError** - loss_weights的值都不是正值。 + + .. py:method:: evaluate(original_images, inversion_images, labels=None, new_network=None) + + 通过三个指标评估还原图像的质量：原始图像和还原图像之间的平均L2距离和SSIM值，以及新模型对还原图像的推理结果在真实标签上的置信度平均值。 + + **参数：** + + - **original_images** (numpy.ndarray) - 原始图像，其形状应为(img_num, channels, img_width, img_height)。 + - **inversion_images** (numpy.ndarray) - 还原图像，其形状应为(img_num, channels, img_width, img_height)。 + - **labels** (numpy.ndarray) - 原始图像的ground truth标签。默认值：None。 + - **new_network** (Cell) - 其结构包含self._network所有部分的网络。_network，但加载了不同的模型文件。默认值：None。 + + **返回：** + + - **float** - l2距离。 + - **float** - 平均ssim值。 + - **Union** [float, None] - 平均置信度。如果labels或new_network为 None，则该值为None。 + + .. py:method:: generate(target_features, iters=100) + + 根据target_features重建图像。 + + **参数：** + + - **iters** (int) - 逆向攻击的迭代次数，应为正整数。默认值：100。 + + **返回：** + + - **numpy.ndarray** - 重建图像，预计与原始图像相似。 + + **异常：** + + - **TypeError** - target_features的类型不是numpy.ndarray。 + - **ValueError** - iters的值都不是正int.Z + +.. py:class:: mindarmour.ConceptDriftCheckTimeSeries(window_size=100, rolling_window=10, step=10, threshold_index=1.5, need_label=False) + + 概念漂移检查时间序列（ConceptDriftCheckTimeSeries）用于样本序列分布变化检测。 + + 有关详细信息，请查看： `教程 `_。 + + **参数：** + + - **window_size** (int) - 概念窗口的大小，不小于10。如果给定输入数据，window_size在[10, 1/3*len(input data)]中。如果数据是周期性的，通常window_size等于2-5个周期，例如，对于月/周数据，30/7天的数据量是一个周期。默认值：100。 + - **rolling_window** (int) - 平滑窗口大小，在[1, window_size]中。默认值：10。 + - **step** (int) - 滑动窗口的跳跃长度，在[1, window_size]中。默认值：10。 + - **threshold_index** (float) - 阈值索引，:math:`(-\infty, +\infty)`。默认值：1.5。 + - **need_label** (bool) - False或True。如果need_label=True，则需要概念漂移标签。默认值：False。 + + .. py:method:: concept_check(data) + + 在数据系列中查找概念漂移位置。 + + **参数：** + + - **data(numpy.ndarray) - 输入数据。数据的shape可以是(n,1)或(n,m)。请注意，每列（m列）是一个数据序列。 + + **返回：** + + - **numpy.ndarray** - 样本序列的概念漂移分数。 + - **float** - 判断概念漂移的阈值。 + - **list** - 概念漂移的位置。 diff --git a/docs/api/api_python/mindarmour.utils.rst b/docs/api/api_python/mindarmour.utils.rst index c8d6995..e82de81 100644 --- a/docs/api/api_python/mindarmour.utils.rst +++ b/docs/api/api_python/mindarmour.utils.rst @@ -3,49 +3,6 @@ mindarmour.utils MindArmour的工具方法，包含日志记录和网络包装。 -.. py:class:: mindarmour.utils.GradWrap(network) - - 构建一个网络，以计算输入空间中网络输出的梯度，并由 `weight` 加权，表示为雅可比矩阵。 - - **参数：** - - - **network** (Cell) - 要包装的目标网络。 - - .. py:method:: construct(*data) - - 计算雅可比矩阵（jacobian matrix）。 - - **参数：** - - - **data** (Tensor) - 数据由输入和权重组成。 - - **inputs** - 网络的输入。 - - **weight** - 每个梯度的权重，'weight'与'inputs'的维度相同。 - - **返回：** - - - **Tensor** - 雅可比矩阵。 - -.. py:class:: mindarmour.utils.GradWrapWithLoss(network) - - 构造一个网络来计算输入空间中损失函数的梯度，并由 `weight` 加权。 - - **参数：** - - - **network** (Cell) - 要包装的目标网络。 - - .. py:method:: construct(inputs, labels) - - 使用标签和权重计算 `inputs` 的梯度。 - - **参数：** - - - **inputs** (Tensor) - 网络的输入。 - - **labels** (Tensor) - 输入的标签。 - - **返回：** - - - **Tensor** - 梯度矩阵。 - .. py:class:: mindarmour.utils.LogUtil 日志记录模块。 @@ -68,16 +25,16 @@ MindArmour的工具方法，包含日志记录和网络包装。 - **ValueError** - 输入handler不是logging.Handler的实例。 - .. py:method:: info(tag, msg, *args) + .. py:method:: debug(tag, msg, *args) - 记录'[tag] msg % args'，严重性为'INFO'。 + 记录'[tag] msg % args'，严重性为'DEBUG'。 **参数：** - **tag** (str) - Logger标记。 - **msg** (str) - Logger消息。 - **args** (Any) - 辅助值。 - + .. py:method:: error(tag, msg, *args) 记录'[tag] msg % args'，严重性为'ERROR'。 @@ -95,28 +52,27 @@ MindArmour的工具方法，包含日志记录和网络包装。 **返回：** - **Object** - 类 `LogUtil` 的实例。 - - - .. py:method:: debug(tag, msg, *args) - 记录'[tag] msg % args'，严重性为'DEBUG'。 + .. py:method:: info(tag, msg, *args) + + 记录'[tag] msg % args'，严重性为'INFO'。 **参数：** - **tag** (str) - Logger标记。 - **msg** (str) - Logger消息。 - **args** (Any) - 辅助值。 - + .. py:method:: set_level(level) 设置此logger的日志级别，级别必须是整数或字符串。支持的级别为 'NOTSET'(integer: 0)、'ERROR'(integer: 1-40)、'WARNING'('WARN', integer: 1-30)、'INFO'(integer: 1-20)以及'DEBUG'(integer: 1-10) - + 例如，如果logger.set_level('WARNING')或logger.set_level(21)，则在运行时将打印脚本中的logger.warn()和logger.error()，而logger.info()或logger.debug()将不会打印。 **参数：** - **level** (Union[int, str]) - logger的级别。 - + .. py:method:: warn(tag, msg, *args) 记录'[tag] msg % args'，严重性为'WARNING'。 @@ -126,4 +82,46 @@ MindArmour的工具方法，包含日志记录和网络包装。 - **tag** (str) - Logger标记。 - **msg** (str) - Logger消息。 - **args** (Any) - 辅助值。 - + +.. py:class:: mindarmour.utils.GradWrapWithLoss(network) + + 构造一个网络来计算输入空间中损失函数的梯度，并由 `weight` 加权。 + + **参数：** + + - **network** (Cell) - 要包装的目标网络。 + + .. py:method:: construct(inputs, labels) + + 使用标签和权重计算 `inputs` 的梯度。 + + **参数：** + + - **inputs** (Tensor) - 网络的输入。 + - **labels** (Tensor) - 输入的标签。 + + **返回：** + + - **Tensor** - 梯度矩阵。 + +.. py:class:: mindarmour.utils.GradWrap(network) + + 构建一个网络，以计算输入空间中网络输出的梯度，并由 `weight` 加权，表示为雅可比矩阵。 + + **参数：** + + - **network** (Cell) - 要包装的目标网络。 + + .. py:method:: construct(*data) + + 计算雅可比矩阵（jacobian matrix）。 + + **参数：** + + - **data** (Tensor) - 数据由输入和权重组成。 + - **inputs** - 网络的输入。 + - **weight** - 每个梯度的权重，'weight'与'inputs'的维度相同。 + + **返回：** + + - **Tensor** - 雅可比矩阵。