Chinese ver. API for adv_robustness

docs/api/api_python/mindarmour.adv_robustness.attacks.rst

@@ -0,0 +1,652 @@
+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)
+
+    增加椒盐噪声的量以生成对抗样本。
+
+    **参数：**
+
+    - **model** (BlackModel) - 目标模型。
+    - **bounds** (tuple) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。
+    - **max_iter** (int) - 生成对抗样本的最大迭代。默认值：100。
+    - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。
+    - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为onehot编码。默认值：True。
+
+    .. py:method:: generate(inputs, labels)
+
+        根据输入数据和目标标签生成对抗样本。
+    
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 原始的、未受扰动的输入。
+        - **labels** (numpy.ndarray) - 目标标签。
+
+        **返回：**
+
+        - **numpy.ndarray** - 每个攻击结果的布尔值。
+        - **numpy.ndarray** - 生成的对抗样本。
+        - **numpy.ndarray** - 每个样本的查询次数。
+
+.. 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)
+
+    所有基于迭代梯度的攻击的抽象基类。
+
+    **参数：**
+
+    - **network** (Cell) - 目标模型。
+    - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。
+    - **eps_iter** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.1。
+    - **bounds** (tuple) - 数据的上下界，表示数据范围。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。
+    - **nb_iter** (int) - 迭代次数。默认值：5。
+    - **loss_fn** (Loss) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。
+
+    .. py:method:: generate(inputs, labels)
+
+        根据输入样本和原始/目标标签生成对抗样本。
+
+        **参数：**
+
+        - **inputs** (Union[numpy.ndarray, tuple]) - 用作创建对抗样本的引用的良性输入样本。
+        - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。
+
+        **异常：**
+
+        - **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）攻击遵循基本迭代法，并在每次迭代时对输入数据应用随机转换。对输入数据的这种转换可以提高对抗样本的可转移性。
+
+    参考文献：`Xie, Cihang and Zhang, et al., "Improving Transferability of Adversarial Examples With Input Diversity," in CVPR, 2019 <https://arxiv.org/abs/1803.06978>`_。
+
+    **参数：**
+
+    - **network** (Cell) - 目标模型。
+    - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。
+    - **bounds** (tuple) - 数据的上下界，表示数据范围。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。
+    - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。
+    - **prob** (float) - 转换概率。默认值：0.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" <https://arxiv.org/abs/1608.04644>`_。
+
+    **参数：**
+
+    - **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)
+
+        根据输入数据和目标标签生成对抗样本。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 输入样本。
+        - **labels** (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)
+
+    遗传攻击（Genetic Attack）表示基于遗传算法的黑盒攻击，属于差分进化算法。
+
+    此攻击是由Moustafa Alzantot等人（2018）提出的。 
+
+    参考文献： `Moustafa Alzantot, Yash Sharma, Supriyo Chakraborty, "GeneticAttack: Practical Black-box Attacks with Gradient-FreeOptimization" <https://arxiv.org/abs/1805.11090>`_。
+
+    **参数：**
+
+    - **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。
+
+    .. 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)。
+
+        **返回：**
+
+        - **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)
+
+    随机最不可能类攻击方法：以置信度最小类别对应的梯度加一个随机扰动为攻击方向。
+
+    具有随机扰动的单步最不可能类方法（Single Step Least-Likely Class Method）是随机FGSM的变体，它以最不可能类为目标，以生成对抗样本。
+
+    参考文献：`F. Tramer, et al., "Ensemble adversarial training: Attacks and defenses," in ICLR, 2018 <https://arxiv.org/abs/1705.07204>`_。
+
+    **参数：**
+
+    - **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.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 <https://arxiv.org/abs/1705.07204>`_。
+
+    **参数：**
+
+    - **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.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. <https://arxiv.org/abs/1412.6572>`_。
+
+    **参数：**
+
+    - **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。
+    - **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）攻击是一种动量迭代法，在每次迭代时对输入数据应用随机变换。对输入数据的这种转换可以提高对抗样本的可转移性。
+
+    参考文献：`Xie, Cihang and Zhang, et al., "Improving Transferability of Adversarial Examples With Input Diversity," in CVPR, 2019 <https://arxiv.org/abs/1803.06978>`_。
+
+    **参数：**
+
+    - **network** (Cell) - 目标模型。
+    - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。
+    - **bounds** (tuple) - 数据的上下界，表示数据范围。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。
+    - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。
+    - **norm_level** (Union[int, numpy.inf]) - 范数的顺序。可取值：np.inf、1或2。默认值：'l1'。
+    - **prob** (float) - 转换概率。默认值：0.5。
+    - **loss_fn** (Loss) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。
+
+
+.. 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）是一种基于输入特征显著图的有目标的迭代攻击。它使用每个类标签相对于输入的每个组件的损失梯度。然后，使用显著图来选择产生最大误差的维度。
+
+    参考文献：`The limitations of deep learning in adversarial settings <https://arxiv.org/abs/1511.07528>`_。
+
+    **参数：**
+
+    - **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。
+    - **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.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等人提出的用于对抗性训练的攻击。
+
+    参考文献：`A. Madry, et al., "Towards deep learning models resistant to adversarial attacks," in ICLR, 2018 <https://arxiv.org/abs/1706.06083>`_。
+
+    **参数：**
+
+    - **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。
+
+    
+    .. py:method:: generate(inputs, labels)    
+    
+        基于BIM方法迭代生成对抗样本。通过带有参数norm_level的投影方法归一化扰动。
+
+        **参数：**
+
+        - **inputs** (Union[numpy.ndarray, tuple]) - 用作创建对抗样本的引用的良性输入样本。
+        - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。
+
+        **返回：**
+
+        - **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)
+
+    DeepFool是一种无目标的迭代攻击，通过将良性样本移动到最近的分类边界并跨越边界来实现。
+
+    参考文献：`DeepFool: a simple and accurate method to fool deep neural networks <https://arxiv.org/abs/1511.04599>`_。
+
+    **参数：**
+
+    - **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。
+    - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为onehot编码。默认值：True。
+
+    .. 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)。
+
+        **返回：**
+
+        - **numpy.ndarray** - 对抗样本。
+
+        **异常：**
+
+        - **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)
+
+    PSO攻击表示基于粒子群优化（Particle Swarm Optimization）算法的黑盒攻击，属于差分进化算法。
+    此攻击是由Rayan Mosli等人（2019）提出的。 
+
+    参考文献：`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. <https://arxiv.org/abs/1909.07490>`_。
+
+    **参数：**
+
+    - **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'。
+    - **reserve_ratio** (Union[int, float]) - 攻击后可检测到的对象百分比，特别是当model_type='detection'。保留比率应在(0, 1)的范围内。默认值：0.3。
+
+
+    .. 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)。
+
+        **返回：**
+
+        - **numpy.ndarray** - 每个攻击结果的布尔值。
+        - **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)
+
+    参考文献：`A. Kurakin, I. Goodfellow, and S. Bengio, "Adversarial examples in the physical world," in ICLR, 2017 <https://arxiv.org/abs/1607.02533>`_。
+
+    **参数：**
+
+    - **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。
+
+    .. py:method:: generate(inputs, labels)    
+
+        简单的迭代FGSM方法生成对抗样本。
+
+        **参数：**
+
+        - **inputs** (Union[numpy.ndarray, tuple]) - 用作创建对抗样本的引用的良性输入样本。
+        - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。
+        
+        **返回：**
+
+        - **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）攻击计算输入数据的梯度，然后使用梯度的符号创建对抗性噪声。
+
+    参考文献：`Ian J. Goodfellow, J. Shlens, and C. Szegedy, "Explaining and harnessing adversarial examples," in ICLR, 2015 <https://arxiv.org/abs/1412.6572>`_。
+
+    **参数：**
+
+    - **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.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 <https://arxiv.org/abs/1804.08598>`_。
+
+    **参数：**
+
+    - **model** (BlackModel) - 要攻击的目标模型。
+    - **scene** (str) - 'Label_Only'、'Partial_Info'、'Query_Limit'中的场景。
+    - **max_queries** (int) - 生成对抗样本的最大查询编号。默认值：10000。
+    - **top_k** (int) - 用于Partial-Info或Label-Only设置，表示攻击者可用的（Top-k）信息数量。对于Query-Limited设置，此输入应设置为-1。默认值：-1。
+    - **num_class** (int) - 数据集中的类数。默认值：10。
+    - **batch_size** (int) - 批次大小。默认值：128。
+    - **epsilon** (float) - 攻击中允许的最大扰动。默认值：0.3。
+    - **samples_per_draw(int) - 对偶采样中绘制的样本数。默认值：128。
+    - **momentum** (float) - 动量。默认值：0.9。
+    - **learning_rate** (float) - 学习率。默认值：1e-3。
+    - **max_lr** (float) - 最大学习率。默认值：5e-2。
+    - **min_lr** (float) - 最小学习率。默认值：5e-4。
+    - **sigma** (float) - 随机噪声的步长。默认值：1e-3。
+    - **plateau_length** (int) - 退火算法中使用的平台长度。默认值：20。
+    - **plateau_drop** (float) - 退火算法中使用的平台Drop。默认值：2.0。
+    - **adv_thresh** (float) - 对抗阈值。默认值：0.25。
+    - **zero_iters** (int) - 用于代理分数的点数。默认值：10。
+    - **starting_eps** (float) - Label-Only设置中使用的启动epsilon。默认值：1.0。
+    - **starting_delta_eps** (float) - Label-Only设置中使用的delta epsilon。默认值：0.5。
+    - **label_only_sigma** (float) - Label-Only设置中使用的Sigma。默认值：1e-3。
+    - **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)    
+    
+        根据输入数据和目标标签生成对抗样本。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 良性输入样本。
+        - **labels** (numpy.ndarray) - 目标标签。
+
+        **返回：**
+
+        - **numpy.ndarray** - 每个攻击结果的布尔值。
+        - **numpy.ndarray** - 生成的对抗样本。
+        - **numpy.ndarray** - 每个样本的查询次数。
+
+        **异常：**
+
+        - **ValueError** - 在Label-Only或Partial-Info设置中top_k小于0。
+        - **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)
+
+    单步最不可能类方法（Single Step Least-Likely Class Method）是FGSM的变体，它以最不可能类为目标，以生成对抗样本。
+
+    参考文献：`F. Tramer, et al., "Ensemble adversarial training: Attacks and defenses," in ICLR, 2018 <https://arxiv.org/abs/1705.07204>`_。
+
+    **参数：**
+
+    - **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）确保使用最小数量的更改像素为每个原始样本生成对抗样本。那些更改的像素将使用二进制搜索，以确保对抗样本和原始样本之间的距离尽可能接近。
+
+    参考文献：`L. Schott, J. Rauber, M. Bethge, W. Brendel: "Towards the first adversarially robust neural network model on MNIST", ICLR (2019) <https://arxiv.org/abs/1805.09190>`_。
+
+    **参数：**
+
+    - **model** (BlackModel) - 目标模型。
+    - **max_iter** (int) - 生成对抗图像的最大迭代轮数。默认值：1000。
+    - **search_ter** (int) - 二进制搜索的最大轮数。默认值：10。
+    - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。
+    - **init_attack** (Attack) - 用于查找起点的攻击。默认值：None。
+    - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为onehot编码。默认值：True。
+
+
+    .. py:method:: generate(inputs, labels)    
+
+        根据输入样本和目标标签生成对抗样本。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 用作创建对抗样本的引用的良性输入样本。
+        - **labels** (numpy.ndarray) - 对于有目标的攻击，标签是对抗性的目标标签。对于无目标攻击，标签是ground-truth标签。
+
+        **返回：**
+
+        - **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 <https://arxiv.org/abs/1705.07204>`_。
+
+    **参数：**
+
+    - **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" <https://arxiv.org/abs/1510.05328>`_。
+
+    **参数：**
+
+    - **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)
+
+    Chen、Jordan和Wainwright提出的HopSkipJumpAttack是一种基于决策的攻击。此攻击需要访问目标模型的输出标签。
+
+    参考文献：`Chen J, Michael I. Jordan, Martin J. Wainwright.
+    HopSkipJumpAttack: A Query-Efficient Decision-Based Attack. 2019.
+    arXiv:1904.02144 <https://arxiv.org/abs/1904.02144>`_。
+
+    **参数：**
+
+    - **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:: set_target_images(target_images)
+
+        设置目标图像进行目标攻击。
+
+        **参数：**
+
+        - **target_images** (numpy.ndarray) - 目标图像。
+
+    .. py:method:: generate(inputs, labels)    
+
+        在for循环中生成对抗图像。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 原始图像。
+        - **labels** (numpy.ndarray) - 目标标签。
+
+        **返回：**
+
+        - **numpy.ndarray** - 每个攻击结果的布尔值。
+        - **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，从而生成对抗样本。
+
+    参考文献：'Y. Dong, et al., "Boosting adversarial attacks with momentum," arXiv:1710.06081, 2017 <https://arxiv.org/abs/1710.06081>`_。
+
+    **参数：**
+
+    - **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)    
+
+        根据输入数据和原始/目标标签生成对抗样本。
+
+        **参数：**
+
+        - **inputs** (Union[numpy.ndarray, tuple]) - 用作创建对抗样本的引用的良性输入样本。
+        - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。
+
+        **返回：**
+
+        - **numpy.ndarray** - 生成的对抗样本。

docs/api/api_python/mindarmour.adv_robustness.detectors.rst

@@ -0,0 +1,400 @@
+mindarmour.adv_robustness.detectors
+===================================
+
+此模块包括用于区分对抗样本和良性样本的检测器方法。
+
+.. py:class:: mindarmour.adv_robustness.detectors.DivergenceBasedDetector(auto_encoder, model, option='jsd', t=1, bounds=(0.0, 1.0))
+
+    基于发散的检测器学习通过js发散来区分正常样本和对抗样本。
+
+    参考文献：`MagNet: a Two-Pronged Defense against Adversarial Examples, by Dongyu Meng and Hao Chen, at CCS 2017. <https://arxiv.org/abs/1705.09064>`_。
+
+    **参数：**
+
+    - **auto_encoder** (Model) - 编码器模型。
+    - **model** (Model) - 目标模型。
+    - **option** (str) - 用于计算发散的方法。默认值：'jsd'。
+    - **t** (int) - 用于克服数值问题的温度。默认值：1。
+    - **bounds** (tuple) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。
+
+    .. py:method:: detect_diff(inputs)    
+   
+        检测原始样本和重建样本之间的距离。
+
+        距离由JSD计算。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 输入样本。
+
+        **返回：**
+
+        - **float** - 距离。
+
+        **异常：**
+
+        - **NotImplementedError** - 不支持参数 `option` 。
+        
+.. py:class:: mindarmour.adv_robustness.detectors.EnsembleDetector(detectors, policy='vote')
+
+
+    **参数：**
+
+    - **detectors** (Union[tuple, list]) - 检测器方法列表。
+    - **policy** (str) - 决策策略，取值可为'vote'、'all'、'any'。默认值：'vote'
+
+    .. py:method:: detect_diff(inputs)    
+   
+        此方法在此类中不可用。
+
+        **参数：**
+
+        - **inputs** (Union[numpy.ndarray, list, tuple]) - 数据被用作创建对抗样本的引用。
+
+        **异常：**
+
+        - **NotImplementedError** - 此函数在集成中不可用。
+        
+    .. py:method:: detect(inputs)    
+   
+        从输入样本中检测对抗性示例。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 输入样本。
+
+        **返回：**
+
+        - **list[int]** - 样本是否具有对抗性。如果res[i]=1，则索引为i的输入样本是对抗性的。
+
+        **异常：**
+
+        - **ValueError** - 不支持策略。
+            
+    .. 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.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 <https://arxiv.org/abs/1709.05583>`_。
+
+    **参数：**
+
+    - **model** (Model) - 目标模型。
+    - **number_points** (int) - 从原始样本的超立方体生成的样本数。默认值：10。
+    - **initial_radius** (float) - 超立方体的初始半径。默认值：0.0。
+    - **max_radius** (float) - 超立方体的最大半径。默认值：1.0。
+    - **search_step** (float) - 搜索半径期间增量。默认值：0.01。
+    - **degrade_limit** (float) - 分类精度的可接受下降。默认值：0.0。
+    - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为onehot编码。默认值：False。
+
+    
+    .. py:method:: detect_diff(inputs)    
+   
+        返回原始预测结果和基于区域的预测结果。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 输入样本。
+
+        **返回：**
+
+        - **numpy.ndarray** - 输入样本的原始预测结果和基于区域的预测结果。
+        
+    .. py:method:: detect(inputs)    
+   
+        判断输入样本是否具有对抗性。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 待判断的可疑样本。
+
+        **返回：**
+
+        - **list[int]** - 样本是否具有对抗性。如果res[i]=1，则索引为i的输入样本是对抗性的。
+
+    .. py:method:: fit(inputs, labels=None)    
+   
+        训练检测器来决定最佳半径。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 良性样本。
+        - **labels** (numpy.ndarray) - 输入样本的ground truth标签。默认值：None。
+
+        **返回：**
+
+        - **float** - 最佳半径。
+        
+    .. py:method:: transform(inputs)    
+   
+        为输入样本生成超级立方体。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 输入样本。
+
+        **返回：**
+
+        - **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))
+
+    检测器重建输入样本，测量重建误差，并拒绝重建误差大的样本。
+
+    参考文献：`MagNet: a Two-Pronged Defense against Adversarial Examples, by Dongyu Meng and Hao Chen, at CCS 2017. <https://arxiv.org/abs/1705.09064>`_。
+
+    **参数：**
+
+    - **auto_encoder** (Model) - 一个（训练过的）自动编码器，通过减少编码表示输入。
+    - **false_positive_rate** (float) - 检测器的误报率。默认值：0.01。
+    - **bounds** (tuple) - (clip_min, clip_max)。默认值：(0.0, 1.0)。
+
+    .. py:method:: detect_diff(inputs)    
+
+        检测原始样本和重建样本之间的距离。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 输入样本。
+
+        **返回：**
+
+        - **float** - 重建样本和原始样本之间的距离。
+
+    .. py:method:: detect(inputs)    
+   
+        检测输入样本是否具有对抗性。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 待判断的可疑样本。
+
+        **返回：**
+
+        - **list[int]** - 样本是否具有对抗性。如果res[i]=1，则索引为i的输入样本是对抗性的。
+        
+    .. py:method:: fit(inputs, labels=None)    
+   
+        查找给定数据集的阈值，以区分对抗样本。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 输入样本。
+        - **labels** (numpy.ndarray) - 输入样本的标签。默认值：None。
+
+        **返回：**
+
+      - **float** - 区分对抗样本和良性样本的阈值。
+        
+    .. py:method:: transform(inputs)    
+   
+        重建输入样本。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 输入样本。
+
+        **返回：**
+
+        - **numpy.ndarray** - 重建图像。
+        
+    .. py:method:: set_threshold(threshold)    
+   
+        设置参数阈值。
+
+        **参数：**
+
+        - **threshold** (float) - 检测阈值。
+            
+.. 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 <https://arxiv.org/abs/1907.05587>`_。
+
+    **参数：**
+
+    - **trans_model** (Model) - 一个MindSpore模型，将输入数据编码为低维向量。
+    - **max_k_neighbor** (int) - 最近邻的最大数量。默认值：1000。
+    - **chunk_size** (int) - 缓冲区大小。默认值：1000。
+    - **max_buffer_size** (int) - 最大缓冲区大小。默认值：10000。默认值：False。
+    - **fpr** (float) - 合法查询序列上的误报率。默认值：0.001
+
+    
+    .. py:method:: detect_diff(inputs)    
+   
+        从输入样本中检测对抗样本，如常见机器学习模型中的predict_proba函数。
+
+        **参数：**
+
+        - **inputs** (Union[numpy.ndarray, list, tuple]) - 数据被用作创建对抗样本的引用。
+
+        **异常：**
+
+        - **NotImplementedError** - 此函数在类 `SimilarityDetector` 中不可用。
+        
+    .. py:method:: detect(inputs)    
+   
+        处理查询以检测黑盒攻击。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 查询顺序。
+
+        **异常：**
+
+        - **ValueError** - 阈值或num_of_neighbors的参数不可用。
+        
+    .. py:method:: fit(inputs, labels=None)    
+   
+        处理输入训练数据以计算阈值。
+        适当的阈值应确保假正率低于给定值。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 用于计算阈值的训练数据。
+        - **labels** (numpy.ndarray) - 训练数据的标签。
+
+        **返回：**
+
+        - **list[int]** - 最近邻的数量。
+
+        - **list[float]** - 不同K的计算阈值。
+
+        **异常：**
+
+        - **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) - 待判断的可疑样本。
+
+        **返回：**
+
+        - **float** - 距离。
+        
+    .. py:method:: detect(inputs)    
+   
+        检测输入样本是否为对抗样本。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 待判断的可疑样本。
+
+        **返回：**
+
+        - **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)    
+   
+        设置参数阈值。
+
+        **参数：**
+
+        - **threshold** (float) - 检测阈值。
+            

docs/api/api_python/mindarmour.adv_robustness.evaluations.rst

@@ -0,0 +1,193 @@
+mindarmour.adv_robustness.evaluations
+=====================================
+
+此模块包括各种指标，用于评估攻击或防御的结果。
+
+.. py:class:: mindarmour.adv_robustness.evaluations.DefenseEvaluate(raw_preds, def_preds, true_labels)
+
+    防御方法的评估指标。
+
+    **参数：**
+
+    - **raw_preds** (numpy.ndarray) - 原始模型上某些样本的预测结果。
+    - **def_preds** (numpy.ndarray) - 防御模型上某些样本的预测结果。
+    - **true_labels** (numpy.ndarray) - 样本的ground-truth标签，一个大小为ground-truth的一维数组。
+
+    .. py:method:: ccv()
+
+        计算分类置信度方差（CCV）。
+
+        **返回：**
+
+        - **float** - 值越低，防守就越成功。如果返回值== -1，则说明样本数量为0。
+
+    .. py:method:: cos()
+
+        参考文献：`Calculate classification output stability (COS) <https://en.wikipedia.org/wiki/Jensen%E2%80%93Shannon_divergence>`_。
+
+        **返回：**
+
+        - **float** - 如果返回值>=0，则是有效的防御。值越低，防守越成功。如果返回值== -1, 则说明样本数量为0。
+
+    .. py:method:: csr()
+
+        计算分类牺牲比（CSR），越低越好。
+
+        **返回：**
+
+        - **float** - 值越低，防守就越成功。
+        
+    .. py:method:: crr()
+
+        计算分类校正率（CRR）。
+
+        **返回：**
+
+        - **float** - 值越高，防守就越成功。
+        
+    .. py:method:: cav()
+
+        计算分类精度方差（CAV）。
+
+        **返回：**
+
+        - **float** - 值越高，防守就越成功。
+        
+.. py:class:: mindarmour.adv_robustness.evaluations.AttackEvaluate(inputs, labels, adv_inputs, adv_preds, targeted=False, target_label=None)
+
+    攻击方法的评估指标。
+
+    **参数：**
+
+    - **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。
+
+    **异常：**
+
+    - **ValueError** - 如果targeted为True时，target_label为None。
+
+    .. py:method:: nte()
+
+        计算噪声容量估计（NTE）。
+
+        参考文献：`Towards Imperceptible and Robust Adversarial Example Attacks against Neural Networks <https://arxiv.org/abs/1801.04693>`_。
+
+        **返回：**
+
+        - **float** - 范围在（0,1）之间。值越高，攻击就越成功。
+        
+    .. py:method:: avg_lp_distance()
+
+        计算平均lp距离（lp-dist）。
+
+        **返回：**
+
+        - **float** - 返回所有成功对抗样本的平均'l0'、'l2'或'linf'距离，返回值包括以下情况。
+        如果返回值 :math:`>=` 0，则为平均lp距离。值越低，攻击就越成功。
+        如果返回值为-1，则没有成功的对抗样本。
+
+    .. py:method:: mis_classification_rate()
+
+        计算错误分类率（MR）。
+
+        **返回：**
+
+        - **float** - 范围在（0,1）之间。值越高，攻击就越成功。
+        
+    .. py:method:: avg_ssim()
+
+        计算平均结构相似性（ASS）。
+
+        **返回：**
+
+        - **float** - 平均结构相似性。
+        如果返回值在（0,1）之间，则值越高，攻击越成功。
+        如果返回值为-1，则没有成功的对抗样本。
+
+    .. py:method:: avg_conf_adv_class()
+
+        计算对抗类的平均置信度（ACAC）。
+
+        **返回：**
+
+        - **float** - 范围在（0,1）之间。值越高，攻击就越成功。
+        
+    .. py:method:: avg_conf_true_class()
+
+        计算真类的平均置信度（ACTC）。
+
+        **返回：**
+
+        - **float** - 范围在（0,1）之间。值越低，攻击就越成功。
+        
+.. 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'。
+
+    **异常：**
+
+    - **ValueError** - scale值不在['hide', 'norm', 'sparse', 'dense']中。
+
+    .. py:method:: show()
+
+        显示雷达图。
+
+.. 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)
+
+    反黑盒防御方法的评估指标。
+
+    **参数：**
+
+    - **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) - 攻击预算，最大查询数。
+
+
+    .. py:method:: qcv()
+
+        计算查询计数方差（QCV）。
+
+        **返回：**
+
+        - **float** - 值越高，防守就越强。如果num_adv_samples=0，则返回-1。
+        
+    .. py:method:: asv()
+
+        计算攻击成功率方差（ASV）。
+
+        **返回：**
+
+        - **float** - 值越低，防守就越强。如果num_adv_samples=0，则返回-1。
+        
+    .. py:method:: fpr()
+
+        计算基于查询的检测器的假正率（FPR）。
+
+        **返回：**
+
+        - **float** - 值越低，防御的可用性越高。如果num_adv_samples=0，则返回-1。
+        
+    .. py:method:: qrv()
+
+        计算良性查询响应时间方差（QRV）。
+
+        **返回：**
+
+        - **float** - 值越低，防御的可用性越高。如果num_adv_samples=0，则返回-1。

docs/api/api_python/mindarmour.reliability.rst

@@ -0,0 +1,147 @@
+mindarmour.reliability
+======================
+
+MindArmour的可靠性方法。
+
+..py:class:: mindarmour.reliability.FaultInjector(model, fi_type=None, fi_mode=None, fi_size=None)
+
+    故障注入模块模拟深度神经网络的各种故障场景，并评估模型的性能和可靠性。
+
+    详情请查看 `教程<https://mindspore.cn/mindarmour/docs/zh-CN/master/fault_injection.html>`_。
+
+    **参数：**
+
+    - **model** (Model) - 需要评估模型。
+    - **fi_type** (list) - 故障注入的类型，包括bitflips_random（随机翻转）、bitflips_designated（翻转关键位）、random、zeros、na- **n、inf、anti_activation precision_loss等。
+    - **fi_mode** (list) - 故障注入的模式。仅在单层或所有层上注入故障。
+    - **fi_size** (list) - 故障注入的次数，表示需要注入多少值。
+
+    
+    .. py:method:: kick_off(ds_data, ds_label, iter_times=100)
+
+        故障注入后启动并返回最终结果。
+
+        **参数：**
+
+        - **ds_data** (np.ndarray) - 输入测试数据。评估基于这些数据。
+        - **ds_label** (np.ndarray) - 数据的标签，对应于数据。
+        - **iter_times** (int) - 评估数，这将决定批处理大小。
+
+        **返回：**
+
+        - **list** - 故障注入的结果。
+    
+    .. py:method:: metrics()
+
+        最终结果的指标。
+
+        **返回：**
+
+        - **list** - 结果总结。
+
+..py:class:: mindarmour.reliability.OodDetector(model, ds_train)
+
+    分布外检测器的抽象类。
+
+    **参数：**
+
+    - **model** (Model) - 训练模型。
+    - **ds_train** (numpy.ndarray) - 训练数据集。
+
+    .. py:method:: get_optimal_threshold(label, ds_eval)
+
+        获取最佳阈值。尝试找到一个最佳阈值来检测OOD样本。最佳阈值由标记的数据集 `ds_eval` 计算。
+
+        **参数：**
+
+        - **label** (numpy.ndarray) - 区分图像是否为分布内或分布外的标签。
+        - **ds_eval** (numpy.ndarray) - 帮助查找阈值的测试数据集。
+
+        **返回：**
+
+        - **float** - 最佳阈值。
+
+    .. py:method:: ood_predict(threshold, ds_test)
+
+        分布外（out-of-distribution，OOD）检测。此函数的目的是检测被视为 `ds_test` 的图像是否为OOD样本。如果一张图像的预测分数大于 `threshold` ，则该图像为分布外。
+
+        **参数：**
+
+        - **threshold** (float) - 判断ood数据的阈值。可以根据经验设置值，也可以使用函数get_optimal_threshold。
+        - **ds_test** (numpy.ndarray) - 测试数据集。
+
+        **返回：**
+
+        - **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）用于样本序列分布变化检测。
+    有关详细信息，请查看`教程<https://mindspore.cn/mindarmour/docs/zh-CN/master/concept_drift_time_series.html>`_。
+
+    **参数：**
+
+    - **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)
+
+    训练OOD检测器。提取训练数据特征，得到聚类中心。测试数据特征与聚类中心之间的距离确定图像是否为分布外（OOD）图像。
+
+    有关详细信息，请查看`教程<https://mindspore.cn/mindarmour/docs/zh-CN/master/concept_drift_images.html>`_。
+
+    **参数：**
+
+    - **model** (Model) - 训练模型。
+    - **ds_train** (numpy.ndarray) - 训练数据集。
+    - **n_cluster** (int) - 聚类编号。取值属于[2,100]。
+    通常，n_cluster等于训练数据集的类号。如果OOD检测器在测试数据集中性能较差，我们可以适当增加n_cluster的值。
+    - **layer** (str) - 特征层的名称。layer (str)由'name[:Tensor]'表示，其中'name'由用户在训练模型时给出。
+    请查看有关如何在'README.md'中命名模型层的更多详细信息。
+
+    .. py:method:: ood_predict(threshold, ds_test)
+
+        分布外（out-of-distribution，OOD）检测。此函数的目的是检测被视为 `ds_test` 的图像是否为OOD样本。如果一张图像的预测分数大于 `threshold` ，则该图像为分布外。
+
+        **参数：**
+
+        - **threshold** (float) - 判断ood数据的阈值。可以根据经验设置值，也可以使用函数get_optimal_threshold。
+        - **ds_test** (numpy.ndarray) - 测试数据集。
+
+        **返回：**
+
+           - **numpy.ndarray** - 检测结果。0表示数据不是ood，1表示数据是ood。
+
+    .. py:method:: get_optimal_threshold(label, ds_eval)
+
+
+        **参数：**
+
+        - **label** (numpy.ndarray) - 区分图像是否为分布内或分布外的标签。
+        - **ds_eval** (numpy.ndarray) - 帮助查找阈值的测试数据集。
+
+        **返回：**
+
+        - **float** - 最佳阈值。
+