!369 Add Chinese ver. API for Fuzzing, Privacy, and MindArmour module

Merge pull request !369 from 张澍坤/master

.jenkins/test/config/dependent_packages.yaml

@@ -1,2 +1,3 @@
 mindspore:
-  'mindspore/mindspore/version/202203/20220327/r1.7_20220327165532_a09b49185a11ac1deba9e80009be3e48813ec3b2/'
+  'mindspore/mindspore/version/202205/20220525/master_20220525210238_42306df4865f816c48a720d98e50ba2e586b1f59/'
+

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

@@ -104,4 +104,4 @@ mindarmour.adv_robustness.defenses
     - **eps** (float) - PGD攻击参数epsilon。默认值：0.3。
     - **eps_iter** (int) - PGD攻击参数，内环epsilon。默认值：0.1。
     - **nb_iter** (int) - PGD攻击参数，迭代次数。默认值：5。
-    - **norm_level** (str) - 范数类型。'inf'或'l2'。默认值：'inf'。
+    - **norm_level** (Union[int, char, numpy.inf]) - 范数类型。可选值：1、2、np.inf、'l1'、'l2'、'np.inf' 或 'inf'。默认值：'inf'。

docs/api/api_python/mindarmour.fuzz_testing.rst

@@ -0,0 +1,209 @@
+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)
+
+    深度神经网络的模糊测试框架。
+
+    参考文献：`DeepHunter: A Coverage-Guided Fuzz Testing Framework for Deep Neural Networks <https://dl.acm.org/doi/10.1145/3293882.3330579>`_。
+
+    **参数：**
+
+    - **target_model** (Model) - 目标模糊模型。
+
+    .. 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]}},
+                  {'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) - 神经元覆盖率指标类。
+        - **evaluate** (bool) - 是否返回评估报告。默认值：True。
+        - **max_iters** (int) - 选择要变异的种子的最大数量。默认值：10000。
+        - **mutate_num_per_seed** (int) - 每个种子的最大变异次数。默认值：20。
+
+        **返回：**
+
+        - **list** - 模糊测试生成的变异样本。
+        - **list** - 变异样本的ground truth标签。
+        - **list** - 预测结果。
+        - **list** - 变异策略。
+        - **dict** - Fuzzer的指标报告。
+
+        **异常：**
+
+        - **ValueError** - 参数'Coverage'必须是CoverageMetrics的子类。
+        - **ValueError** - 初始种子队列为空。
+        - **ValueError** - 初始种子队列中的种子不是包含两个元素。
+
+.. py:class:: mindarmour.fuzz_testing.CoverageMetrics(model, incremental=False, batch_size=32)
+
+    计算覆盖指标的神经元覆盖类的抽象基类。
+
+    众所周知，训练后网络的每个神经元输出有一个输出范围（我们称之为原始范围），测试数据集用于估计训练网络的准确性。然而，不同的测试数据集，神经元的输出分布会有所不同。因此，与传统模糊测试类似，模型模糊测试意味着测试这些神经元的输出，并评估在测试数据集上神经元输出值占原始范围的比例。
+
+    参考文献： `DeepGauge: Multi-Granularity Testing Criteria for Deep Learning Systems <https://arxiv.org/abs/1803.07519>`_。
+
+    **参数：**
+
+    - **model** (Model) - 被测模型。
+    - **incremental** (bool) - 指标将以增量方式计算。默认值：False。
+    - **batch_size** (int) - 模糊测试批次中的样本数。默认值：32。
+    
+    .. py:method:: get_metrics(dataset)
+
+        计算给定数据集的覆盖率指标。
+
+        **参数：**
+
+        - **dataset** (numpy.ndarray) - 用于计算覆盖指标的数据集。
+
+        **异常：**
+
+        - **NotImplementedError** - 抽象方法。
+        
+.. 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是指测试数据集中神经元输出值超过训练数据集中相应神经元输出值的上下界的神经元比例。
+
+    **参数：**
+
+    - **model** (Model) - 等待测试的预训练模型。
+    - **train_dataset** (numpy.ndarray) - 用于确定神经元输出边界的训练数据集。
+    - **incremental** (bool) - 指标将以增量方式计算。默认值：False。
+    - **batch_size** (int) - 模糊测试批次中的样本数。默认值：32。
+    
+    .. py:method:: get_metrics(dataset)
+
+        获取'neuron boundary coverage'的指标。
+
+        **参数：**
+
+        - **dataset** (numpy.ndarray) - 用于计算覆盖指标的数据集。
+
+        **返回：**
+
+        - **float** - 'neuron boundary coverage'的指标。
+
+        
+.. 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'的指标。
+
+        

docs/api/api_python/mindarmour.privacy.diff_privacy.rst

@@ -0,0 +1,304 @@
+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')
+
+    自适应高斯噪声产生机制。噪音会随着训练而衰减。衰减模式可以是'Time'、'Step'、'Exp'。
+    在模型训练过程中，将更新 `self._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'。
+
+    .. py:method:: construct(gradients)
+
+        生成的自适应高斯噪声。
+
+        **参数：**
+
+        - **gradients** (Tensor) - 梯度。
+
+        **返回：**
+
+        - **Tensor** - 生成的shape与给定梯度相同的噪声。
+    
+.. py::class:: mindarmour.privacy.diff_privacy.DPOptimizerClassFactory(micro_batches=2)
+
+    优化器的工厂类。
+
+    **参数：**
+
+    - **micro_batches** (int) - 从原始批次拆分的小批次中的样本数量。默认值：2。
+
+    **返回：**
+
+    - **Optimizer** - 优化器类。
+
+    .. py:method:: create(policy)
+
+        创建DP优化器。策略可以是'sgd'、'momentum'、'adam'。
+
+        **参数：**
+
+        - **policy** (str) - 选择原始优化器类型。
+
+        **返回：**
+
+        - **Optimizer** - 一个带有差分加噪的优化器。
+
+    .. py:method:: set_mechanisms(policy, *args, **kwargs)
+
+        获取噪音机制对象。策略可以是'Gaussian'或'AdaGaussian'。候选的args和kwargs可以在mechanisms.py的NoiseMechanismsFactory类中看到。
+
+        **参数：**
+
+        - **policy** (str) - 选择机制类型。
+
+    
+.. 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` 。
+
+    **参数：**
+
+    - **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)
+
+        产生的高斯噪声。
+
+        **参数：**
+
+        - **gradients** (Tensor) - 梯度。
+
+        **返回：**
+
+        - **Tensor** - 生成的shape与给定梯度相同的噪声。
+    
+.. py::class:: mindarmour.privacy.diff_privacy.NoiseMechanismsFactory
+    
+    噪声机制的工厂类
+
+    噪声产生机制的包装器。它目前支持高斯随机噪声（Gaussian Random Noise）和自适应高斯随机噪声（Adaptive Gaussian Random Noise）。
+
+    详情请查看： `教程 <https://mindspore.cn/mindarmour/docs/zh-CN/master/protect_user_privacy_with_differential_privacy.html#%E5%B7%AE%E5%88%86%E9%9A%90%E7%A7%81>`_。
+
+    .. py:method:: create(mech_name, norm_bound=1.0, initial_noise_multiplier=1.0, seed=0, noise_decay_rate=6e-06, decay_policy=None)
+
+        **参数：**
+
+        - **mech_name** (str) - 噪声生成策略，可以是'Gaussian'或'AdaGaussian'。噪声在'AdaGaussian'机制下衰减，而在'Gaussian'机制下则恒定。
+        - **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) - 衰减策略。如果decay_policy为None，则不需要更新参数。默认值：None。
+
+        **异常：**
+
+        - **NameError** - `mech_name` 必须在['Gaussian', 'AdaGaussian']中。
+
+        **返回：**
+
+        - **Mechanisms** - 产生的噪声类别机制。
+
+        
+        
+.. py::class:: mindarmour.privacy.diff_privacy.ClipMechanismsFactory
+
+    剪裁机制的工厂类
+    噪声生成机制的裁剪包装器。它目前支持高斯随机噪声（Gaussian Random Noise）的自适应剪裁（Adaptive Clipping）。
+
+    详情请查看： `教程 <https://mindspore.cn/mindarmour/docs/zh-CN/master/protect_user_privacy_with_differential_privacy.html#%E5%B7%AE%E5%88%86%E9%9A%90%E7%A7%81>`_。
+
+    .. py:method:: ClipMechanismsFactory.create(mech_name, decay_policy='Linear', learning_rate=0.001, target_unclipped_quantile=0.9, fraction_stddev=0.01, seed=0)
+
+        **参数：**
+
+        - **mech_name** (str) - 噪声裁剪生成策略，现支持'Gaussian'。
+        - **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，公式为 :math:`empirical\_fraction + N(0, fraction\_stddev)` 。默认值：0.01。
+        - **seed** (int) - 原始随机种子，如果seed=0随机正态将使用安全随机数。如果seed!=0随机正态将使用给定的种子生成值。默认值：0。
+
+        **异常：**
+
+        - **NameError** - `mech_name` 必须在['Gaussian']中。
+
+        **返回：**
+
+        - **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)
+
+    基于Renyi差分隐私（RDP）理论，计算DP训练的隐私预算。根据下面的参考文献，如果随机化机制被认为具有α阶的ε'-Renyi差分隐私，它也满足常规差分隐私(ε, δ)，如下所示：
+
+    .. math::
+        (ε'+\frac{log(1/δ)}{α-1}, δ)
+
+    详情请查看： `教程 <https://mindspore.cn/mindarmour/docs/zh-CN/master/protect_user_privacy_with_differential_privacy.html#%E5%B7%AE%E5%88%86%E9%9A%90%E7%A7%81>`_。
+
+    参考文献：`Rényi Differential Privacy of the Sampled Gaussian Mechanism <https://arxiv.org/abs/1908.10530>`_。
+
+    **参数：**
+
+    - **num_samples** (int) - 训练数据集中的样本总数。
+    - **batch_size** (int) - 训练时批处理中的样本数。
+    - **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。
+    - **target_eps** (Union[float, int, None]) - DP训练的目标epsilon预算。如果target_eps设置为ε，则隐私预算ε将在整个训练过程中是固定的。默认值：None。
+    - **orders** (Union[None, list[int, float]]) - 用于计算rdp的有限阶数，必须大于1。不同阶的隐私预算计算结果会有所不同。为了获得更严格（更小）的隐私预算估计，可以尝试阶列表。默认值：None。
+    - **noise_decay_mode** (Union[None, str]) - 训练时添加噪音的衰减模式，可以是None、'Time'、'Step'、'Exp'。默认值：'Time'。
+    - **noise_decay_rate** (float) - 训练时噪音的衰变率。默认值：6e-4。
+    - **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` 的样本的经验分数。
+
+    **参数：**
+
+    - **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。
+
+    **返回：**
+
+    - **Tensor** - 更新后的梯度裁剪阈值。
+
+    .. py:method:: AdaClippingWithGaussianRandom.construct(empirical_fraction, norm_bound)
+
+        更新norm_bound的值。
+
+        **参数：**
+
+        - **empirical_fraction** (Tensor) - 梯度裁剪的经验分位数。
+        - **norm_bound** (Tensor) - 梯度的l2范数的裁剪范围。
+
+        **返回：**
+
+        - **Tensor** - 生成的shape与给定梯度相同的噪声。
+    
+.. py::class:: mindarmour.privacy.diff_privacy.PrivacyMonitorFactory
+
+    DP训练隐私监视器的工厂类。
+    
+    详情请查看： `教程 <https://mindspore.cn/mindarmour/docs/zh-CN/master/protect_user_privacy_with_differential_privacy.html#%E5%B7%AE%E5%88%86%E9%9A%90%E7%A7%81>`_。
+
+    .. 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.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机制，它也满足传统的差分隐私（ε, δ），如下所示：
+
+    .. math::
+        (ρ+２\sqrt{ρ*log(1/δ)}, δ)
+
+    注意，ZCDPMonitor不适合子采样噪声机制（如NoiseAdaGaussianRandom和NoiseGaussianRandom）。未来将开发zCDP的匹配噪声机制。
+
+    详情请查看：  `教程 <https://mindspore.cn/mindarmour/docs/zh-CN/master/protect_user_privacy_with_differential_privacy.html#%E5%B7%AE%E5%88%86%E9%9A%90%E7%A7%81>`_。
+
+    参考文献：`Concentrated Differentially Private Gradient Descent with Adaptive per-Iteration Privacy Budget <https://arxiv.org/abs/1808.09501>`_。
+
+    **参数：**
+
+    - **num_samples** (int) - 训练数据集中的样本总数。
+    - **batch_size** (int) - 训练时批处理中的样本数。
+    - **initial_noise_multiplier(Union[float, int]) - 高斯噪声标准偏差除以norm_bound的比率，将用于计算隐私预算。默认值：1.5。
+    - **max_eps** (Union[float, int]) - DP训练的最大可接受epsilon预算，用于估计最大训练epoch。默认值：10.0。
+    - **target_delta** (Union[float, int]) - DP训练的目标delta预算。如果target_delta设置为δ，则隐私预算δ将在整个训练过程中是固定的。默认值：1e-3。
+    - **noise_decay_mode** (Union[None, str]) - 训练时添加噪音的衰减模式，可以是None、'Time'、'Step'、'Exp'。默认值：'Time'。
+    - **noise_decay_rate** (float) - 训练时噪音的衰变率。默认值：6e-4。
+    - **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.DPModel(micro_batches=2, norm_bound=1.0, noise_mech=None, clip_mech=None, **kwargs)
+
+    DPModel用于构建差分隐私训练的模型。
+    
+    这个类重载自Mindpore.train.model.Model。
+
+    详情请查看： `教程 <https://mindspore.cn/mindarmour/docs/zh-CN/master/protect_user_privacy_with_differential_privacy.html#%E5%B7%AE%E5%88%86%E9%9A%90%E7%A7%81>`_。
+
+    **参数：**
+
+    - **micro_batches** (int) - 从原始批次拆分的小批次数。默认值：2。
+    - **norm_bound** (float) - 用于裁剪范围，如果设置为1，将返回原始数据。默认值：1.0。
+    - **noise_mech** (Mechanisms) - 对象可以生成不同类型的噪音。默认值：None。
+    - **clip_mech** (Mechanisms) - 该对象用于更新自适应剪裁。默认值：None。
+
+    **异常：**
+
+    - **ValueError** - DPOptimizer和noise_mech都为None或非None。
+    - **ValueError** - noise_mech或DPOtimizer的mech方法是自适应的，而clip_mech不是None。
+
+    

docs/api/api_python/mindarmour.privacy.evaluation.rst

@@ -0,0 +1,123 @@
+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. <https://arxiv.org/pdf/1412.0035.pdf>`_。
+
+    **参数：**
+    
+    - **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结果。
+    （隐私是指单个用户的一些敏感属性）。
+
+    有关详细信息，请参见： `教程 <https://mindspore.cn/mindarmour/docs/en/master/test_model_security_membership_inference.html>`_。
+
+    参考文献：`Reza Shokri, Marco Stronati, Congzheng Song, Vitaly Shmatikov.
+    Membership Inference Attacks against Machine Learning Models. 2017. <https://arxiv.org/abs/1610.05820v2>`_。
+
+    **参数：**
+    
+    - **model** (Model) - 目标模型。
+    - **n_jobs** (int) - 并行运行的任务数量。-1表示使用所有处理器，否则n_jobs的值必须为正整数。
+
+    **异常：**
+    
+    - **TypeError** - 模型的类型不是Mindpore.train.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:: python
+               attack_config = 
+                   [{"method": "knn", "params": {"n_neighbors": [3, 5, 7]}},
+                    {"method": "lr", "params": {"C": np.logspace(-4, 2, 10)}}]
+
+            - 支持的方法有knn、lr、mlp和rf，每个方法的参数必须在可变参数的范围内。参数实现的提示可在下面找到：
+            - `KNN <https://scikit-learn.org/stable/modules/generated/sklearn.neighbors.KNeighborsClassifier.html>`_,
+            - `LR <https://scikit-learn.org/stable/modules/generated/sklearn.linear_model.LogisticRegression.html>`_,
+            - `RF <https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.RandomForestClassifier.html>`_,
+            - `MLP <https://scikit-learn.org/stable/modules/generated/sklearn.neural_network.MLPRegressor.html>`_.
+
+        **异常：**
+        
+        - **KeyError** - attack_config中的配置没有键{"method", "params"}。
+        - **NameError** - attack_config中的方法（不区分大小写）不在["lr", "knn", "rf", "mlp"]中。
+        

docs/api/api_python/mindarmour.privacy.sup_privacy.rst

@@ -0,0 +1,194 @@
+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):
+
+    - **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
+
+    SuppressCtrl机制的工厂类。
+
+    详情请查看： `教程 <https://mindspore.cn/mindarmour/docs/zh-CN/master/protect_user_privacy_with_suppress_privacy.html#%E5%BC%95%E5%85%A5%E6%8A%91%E5%88%B6%E9%9A%90%E7%A7%81%E8%AE%AD%E7%BB%83>`_。
+    
+    .. 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<start_epoch<=end_epoch<=100。默认值：10。此end_epoch参数应与mindspore.train.model.train()的'epoch'参数相同。
+        - **batch_num** (int) - 一个epoch中批次的数量，应等于num_samples/batch_size。默认值：20。
+        - **start_epoch** (int) - 第一个抑制操作对应的epoch序号，0<start_epoch<=end_epoch<=100。默认值：3。
+        - **mask_times** (int) - 抑制操作的数量。默认值：1000。
+        - **lr** (Union[float, int]) - 学习率，在训练期间应保持不变。0<lr<=0.50. 默认值：0.05。此lr参数应与mindspore.nn.SGD()的'learning_rate'参数相同。
+        - **sparse_end** (float) - 要到达的稀疏性，0.0<=sparse_start<sparse_end<1.0。默认值：0.90。
+        - **sparse_start** (Union[float, int]) - 抑制操作启动时对应的稀疏性，0.0<=sparse_start<sparse_end<1.0。默认值：0.0。
+
+        **返回：**
+
+        - **SuppressCtrl** - 抑制隐私机制的类。
+
+        
+
+.. py:class:: mindarmour.privacy.sup_privacy.SuppressModel(network, loss_fn, optimizer, **kwargs)
+
+    完整的模型训练功能。抑制隐私函数嵌入到重载的mindspore.train.model.Model中。
+
+    有关详细信息，请查看： `教程 <https://mindspore.cn/mindarmour/docs/zh-CN/master/protect_user_privacy_with_suppress_privacy.html>`_。
+
+    **参数：**
+
+    - **network** (Cell) - 要训练的神经网络模型。
+    - **loss_fn** (Cell) - 计算logits和labels之间的softmax交叉熵。
+    - **optimizer** (Optimizer) - 优化器实例。
+    - **kwargs** - 创建抑制模型时使用的关键字参数。
+
+    .. py:method:: link_suppress_ctrl(suppress_pri_ctrl)
+
+        SuppressCtrl实例关联到SuppressModel实例。
+
+        **参数：**
+
+        - **suppress_pri_ctrl** (SuppressCtrl) - SuppressCtrl实例。
+        
+    
+.. py:class:: mindarmour.privacy.sup_privacy.SuppressMasker(model, suppress_ctrl)
+
+    周期性检查抑制隐私功能状态和切换（启动/关闭）抑制操作。
+
+    详情请查看： `教程 <https://mindspore.cn/mindarmour/docs/zh-CN/master/protect_user_privacy_with_suppress_privacy.html#%E5%BC%95%E5%85%A5%E6%8A%91%E5%88%B6%E9%9A%90%E7%A7%81%E8%AE%AD%E7%BB%83>`_。
+
+    **参数：**
+
+    - **model** (SuppressModel) - SuppressModel 实例。
+    - **suppress_ctrl** (SuppressCtrl) - SuppressCtrl实例。
+
+    .. py:method:: step_end(run_context)
+
+        更新用于抑制模型实例的掩码矩阵张量。
+
+        **参数：**
+
+        - **run_context** (RunContext) - 包含模型的一些信息。
+        
+        
+    
+.. py:class:: mindarmour.privacy.sup_privacy.SuppressCtrl(networks, mask_layers, end_epoch, batch_num, start_epoch, mask_times, lr, sparse_end, sparse_start)
+
+    完成抑制隐私操作，包括计算抑制比例，找到应该抑制的参数，并永久抑制这些参数。
+
+    详情请查看： `教程 <https://mindspore.cn/mindarmour/docs/zh-CN/master/protect_user_privacy_with_suppress_privacy.html#%E5%BC%95%E5%85%A5%E6%8A%91%E5%88%B6%E9%9A%90%E7%A7%81%E8%AE%AD%E7%BB%83>`_。
+
+    **参数：**
+
+    - **networks** (Cell) - 要训练的神经网络模型。
+    - **mask_layers** (list) - 需要抑制的层的描述。
+    - **end_epoch** (int) - 最后一次抑制操作对应的epoch序号。
+    - **batch_num** (int) - 一个epoch中的grad操作的数量。
+    - **start_epoch** (int) - 第一个抑制操作对应的epoch序号。
+    - **mask_times** (int) - 抑制操作的数量。
+    - **lr** (Union[float, int]) - 学习率。
+    - **sparse_end** (float) - 要到达的稀疏性。
+    - **sparse_start** (Union[float, int]) - 要启动的稀疏性。
+
+    .. py:method:: update_mask_layer(weight_array_flat, sparse_weight_thd, sparse_stop_pos, weight_abs_max, layer_index)
+
+        对单层的用于加法运算和乘法运算的掩码数组进行更新。
+
+        **参数：**
+
+        - **weight_array_flat** (numpy.ndarray) - 层参数权重数组。
+        - **sparse_weight_thd** (float) - 绝对值小于该阈值的权重会被抑制。
+        - **sparse_stop_pos** (int) - 要抑制的最大元素数。
+        - **weight_abs_max** (float) - 权重的最大绝对值。
+        - **layer_index** (int) - 目标层的索引。
+
+    .. py:method:: print_paras()
+
+        显示参数信息
+
+    .. py:method:: update_status(cur_epoch, cur_step, cur_step_in_epoch)
+
+        更新抑制操作状态。
+
+        **参数：**
+
+        - **cur_epoch** (int) - 整个训练过程的当前epoch。
+        - **cur_step** (int) - 整个训练过程的当前步骤。
+        - **cur_step_in_epoch** (int) - 当前epoch的当前步骤。
+
+    .. py:method:: update_mask(networks, cur_step, target_sparse=0.0)
+
+        对整个模型的用于加法运算和乘法运算的掩码数组进行更新。
+
+        **参数：**
+
+        - **networks** (Cell) - 训练网络。
+        - **cur_step** (int) - 整个训练过程的当前epoch。
+        - **target_sparse** (float) - 要到达的稀疏性。默认值：0.0。
+        
+    .. py:method:: update_mask_layer_approximity(weight_array_flat, weight_array_flat_abs, actual_stop_pos, layer_index)
+
+        对单层的用于加法运算和乘法运算的掩码数组进行更新。
+        
+        禁用clipping lower、clipping、adding noise操作
+
+        **参数：**
+
+        - **weight_array_flat** (numpy.ndarray) - 层参数权重数组。
+        - **weight_array_flat_abs** (numpy.ndarray) - 层参数权重的绝对值的数组。
+        - **actual_stop_pos** (int) - 应隐藏实际参数编号。
+        - **layer_index** (int) - 目标层的索引。
+        
+    .. py:method:: reset_zeros()
+
+        将用于加法运算的掩码数组设置为0。
+        
+    .. py:method:: calc_actual_sparse_for_conv(networks)
+
+        计算con1层和con2层的网络稀疏性。
+
+        **参数：**
+
+        - **networks** (Cell) - 要训练的神经网络模型。
+        
+    .. py:method:: calc_theoretical_sparse_for_conv()
+
+        计算con1层和con2层的掩码矩阵的实际稀疏性。
+        
+    .. py:method:: calc_actual_sparse_for_fc1(networks)
+
+        计算全连接1层的实际稀疏
+
+        **参数：**
+
+        - **networks** (Cell) - 要训练的神经网络模型。
+
+    .. py:method:: calc_actual_sparse_for_layer(networks, layer_name)
+
+        计算一个网络层的实际稀疏性
+
+        **参数：**
+
+        - **networks** (Cell) - 要训练的神经网络模型。
+        - **layer_name** (str) - 目标层的名称。
+    

docs/api/api_python/mindarmour.rst

@@ -0,0 +1,386 @@
+mindarmour
+==========
+
+MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保护机器学习。
+
+.. py:class:: mindarmour.Attack
+
+    所有通过创建对抗样本的攻击类的抽象基类。
+    
+    对抗样本是通过向原始样本添加对抗噪声来生成的。
+
+    .. py:method:: batch_generate(inputs, labels, batch_size=64)
+
+        根据输入样本及其标签来批量生成对抗样本。
+
+        **参数：**
+
+        - **inputs** (Union[numpy.ndarray, tuple]) - 生成对抗样本的原始样本。
+        - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。
+        - **batch_size** (int) - 一个批次中的样本数。默认值：64。
+
+        **返回：**
+
+        - **numpy.ndarray** - 生成的对抗样本。
+    
+    .. py:method:: generate(inputs, labels)
+
+        根据正常样本及其标签生成对抗样本。
+
+        **参数：**
+
+        - **inputs** (Union[numpy.ndarray, tuple]) - 生成对抗样本的原始样本。
+        - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。
+
+        **异常：**
+
+        - **NotImplementedError** - 此为抽象方法。
+       
+.. py:class:: mindarmour.MembershipInference(model, n_jobs=-1)
+
+    成员推理是由Shokri、Stronati、Song和Shmatikov提出的一种用于推测用户隐私数据的灰盒攻击。它需要训练样本的loss或logits结果。（隐私是指单个用户的一些敏感属性）。
+
+    有关详细信息，请参见 ：`教程 <https://mindspore.cn/mindarmour/docs/en/master/test_model_security_membership_inference.html>`_。
+
+    参考文献：`Reza Shokri, Marco Stronati, Congzheng Song, Vitaly Shmatikov. Membership Inference Attacks against Machine Learning Models. 2017. <https://arxiv.org/abs/1610.05820v2>`_。
+
+    **参数：**
+
+    - **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 <https://scikit-learn.org/stable/modules/generated/sklearn.neighbors.KNeighborsClassifier.html>`_ ，
+            - `LR <https://scikit-learn.org/stable/modules/generated/sklearn.linear_model.LogisticRegression.html>`_ ，
+            - `RF <https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.RandomForestClassifier.html>`_ ，
+            - `MLP <https://scikit-learn.org/stable/modules/generated/sklearn.neural_network.MLPRegressor.html>`_ 。
+
+        **异常：**
+
+        - **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. <https://arxiv.org/pdf/1412.0035.pdf>`_。
+
+    **参数：**
+
+    - **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。
+
+    详情请查看：`教程 <https://mindspore.cn/mindarmour/docs/zh-CN/master/protect_user_privacy_with_differential_privacy.html#%E5%B7%AE%E5%88%86%E9%9A%90%E7%A7%81>`_。
+
+    **参数：**
+
+    - **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
+
+    将目标模型视为黑盒的抽象类。模型应由用户定义。
+
+    .. py:method:: is_adversarial(data, label, is_targeted)
+
+        检查输入样本是否为对抗样本。
+
+        **参数：**
+
+        - **data** (numpy.ndarray) - 要检查的输入样本，通常是一些恶意干扰的样本。
+        - **label** (numpy.ndarray) - 对于目标攻击，标签是受扰动样本的预期标签。对于无目标攻击，标签是相应未扰动样本的原始标签。
+        - **is_targeted** (bool) - 对于有目标/无目标攻击，请选择True/False。
+
+        **返回：**
+
+        - **bool** - 如果为True，则输入样本是对抗性的。如果为False，则输入样本不是对抗性的。
+        
+    .. py:method:: predict(inputs)
+
+        使用用户指定的模型进行预测。预测结果的shape应该是(m,n)，其中n表示此模型分类的类数。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 要预测的输入样本。
+
+        **异常：**
+
+        - **NotImplementedError** - 抽象方法未实现。
+        
+    
+.. py:class:: mindarmour.Detector
+
+    所有对抗样本检测器的抽象基类。
+        
+    .. py:method:: fit(inputs, labels=None)
+
+        拟合阈值，拒绝与去噪样本差异大于阈值的对抗样本。当应用于正常样本时，阈值由假正率决定。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 用于计算阈值的输入样本。
+        - **labels** (numpy.ndarray) - 训练数据的标签。默认值：None。
+
+        **异常：**
+
+        - **NotImplementedError** - 抽象方法未实现。
+    
+    .. py:method:: detect_diff(inputs)
+
+        计算输入样本和去噪样本之间的差值。
+
+        **参数：**
+
+        - **inputs** (Union[numpy.ndarray, list, tuple]) - 要检测的输入样本。
+
+        **异常：**
+
+        - **NotImplementedError** - 抽象方法未实现。
+
+        
+    .. py:method:: detect(inputs)
+
+        从输入样本中检测对抗样本。
+
+        **参数：**
+
+        - **inputs** (Union[numpy.ndarray, list, tuple]) - 要检测的输入样本。
+
+        **异常：**
+
+        - **NotImplementedError** - 抽象方法未实现。
+
+    .. py:method:: transform(inputs)
+
+        过滤输入样本中的对抗性噪声。
+
+        **参数：**
+
+        - **inputs** (Union[numpy.ndarray, list, tuple]) - 要转换的输入样本。
+        
+        **异常：**
+
+        - **NotImplementedError** - 抽象方法未实现。
+
+.. py:class:: mindarmour.Defense(network)
+
+    所有防御类的抽象基类，用于防御对抗样本。
+
+    **参数：**
+
+    - **network** (Cell) - 要防御的MindSpore风格的深度学习模型。
+    
+    .. py:method:: batch_defense(inputs, labels, batch_size=32, epochs=5)
+
+        带有批量样本的防御模型。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 生成对抗样本的原始样本。
+        - **labels** (numpy.ndarray) - 输入样本的标签。
+        - **batch_size** (int) - 一个批次中的样本数。默认值：32。
+        - **epochs** (int) - epochs的数量。默认值：5。
+
+        **返回：**
+
+        - **numpy.ndarray** - 批处理防御操作的损失。
+
+        **异常：**
+
+        - **ValueError** - batch_size为0。
+    
+    .. py:method:: defense(inputs, labels)
+
+        带样本的防御模型。
+
+        **参数：**
+
+        - **inputs** (numpy.ndarray) - 生成对抗样本的原始样本。
+        - **labels** (numpy.ndarray) - 输入样本的标签。
+
+        **异常：**
+
+        - **NotImplementedError** - 抽象方法未实现。
+        
+.. py:class:: mindarmour.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.Fuzzer(target_model)
+
+    深度神经网络的模糊测试框架。
+
+    参考文献：`DeepHunter: A Coverage-Guided Fuzz Testing Framework for Deep Neural Networks <https://dl.acm.org/doi/10.1145/3293882.3330579>`_。
+
+    **参数：**
+
+    - **target_model** (Model) - 目标模糊模型。
+
+    .. 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]}},
+                     {'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 <https://gitee.com/mindspore/mindarmour/tree/master/mindarmour/natural_robustness/transform/image>`_ 中看到。第二类方法参数配置参考 `self._attack_param_checklists` 。
+        - **initial_seeds** (list[list]) - 用于生成变异样本的初始种子队列。初始种子队列的格式为[[image_data, label], [...], ...]，且标签必须为one-hot。
+        - **coverage** (CoverageMetrics) - 神经元覆盖率指标类。
+        - **evaluate** (bool) - 是否返回评估报告。默认值：True。
+        - **max_iters** (int) - 选择要变异的种子的最大数量。默认值：10000。
+        - **mutate_num_per_seed** (int) - 每个种子的最大变异次数。默认值：20。
+
+        **返回：**
+
+        - **list** - 模糊测试生成的变异样本。
+        - **list** - 变异样本的ground truth标签。
+        - **list** - 预测结果。
+        - **list** - 变异策略。
+        - **dict** - Fuzzer的指标报告。
+
+        **异常：**
+
+        - **ValueError** - 参数'Coverage'必须是CoverageMetrics的子类。
+        - **ValueError** - 初始种子队列为空。
+        - **ValueError** - 初始种子队列中的种子不是包含两个元素。
+        

docs/api/api_python/mindarmour.utils.rst

@@ -0,0 +1,129 @@
+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
+
+    日志记录模块。
+
+    在长期运行的脚本中记录随时间推移的日志统计信息。
+
+    **异常：**
+
+    - **SyntaxError** - 创建此类异常。
+
+    .. py:method:: add_handler(handler)
+
+        添加日志模块支持的其他处理程序。
+
+        **参数：**
+
+        - **handler** (logging.Handler) - 日志模块支持的其他处理程序。
+
+        **异常：**
+
+        - **ValueError** - 输入handler不是logging.Handler的实例。
+
+    .. py:method:: info(tag, msg, *args)
+
+        记录'[tag] msg % args'，严重性为'INFO'。
+
+        **参数：**
+
+        - **tag** (str) - Logger标记。
+        - **msg** (str) - Logger消息。
+        - **args** (Any) - 辅助值。
+    
+    .. py:method:: error(tag, msg, *args)
+
+        记录'[tag] msg % args'，严重性为'ERROR'。
+
+        **参数：**
+
+        - **tag** (str) - Logger标记。
+        - **msg** (str) - Logger消息。
+        - **args** (Any) - 辅助值。
+
+    .. py:method:: get_instance()
+
+        获取类 `LogUtil` 的实例。
+
+        **返回：**
+
+        - **Object** - 类 `LogUtil` 的实例。
+        
+    
+    .. py:method:: debug(tag, msg, *args)
+
+        记录'[tag] msg % args'，严重性为'DEBUG'。
+
+        **参数：**
+
+        - **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'。
+
+        **参数：**
+
+        - **tag** (str) - Logger标记。
+        - **msg** (str) - Logger消息。
+        - **args** (Any) - 辅助值。
+        

mindarmour/adv_robustness/defenses/projected_adversarial_defense.py

@@ -38,7 +38,8 @@ class ProjectedAdversarialDefense(AdversarialDefenseWithAttacks):
             Default:0.1.
         nb_iter (int): PGD attack parameters, number of iteration.
             Default: 5.
-        norm_level (str): Norm type. 'inf' or 'l2'. Default: 'inf'.
+        norm_level (Union[int, char, numpy.inf]): Norm type. 1, 2, np.inf, 'l1', 'l2', 'np.inf' or 'inf'.
+            Default: 'inf'.
 
     Examples:
         >>> from mindspore.nn.optim.momentum import Momentum