From 2a4882770e8c164f86546b3a7d0f81cddcf184df Mon Sep 17 00:00:00 2001 From: xumengjuan1 Date: Fri, 22 Jul 2022 10:11:12 +0800 Subject: [PATCH] modify doc --- .../mindarmour.adv_robustness.attacks.rst | 750 ++++++++++----------- .../mindarmour.adv_robustness.defenses.rst | 109 ++- .../mindarmour.adv_robustness.detectors.rst | 337 ++++----- .../mindarmour.adv_robustness.evaluations.rst | 151 ++--- docs/api/api_python/mindarmour.fuzz_testing.rst | 216 +++--- .../api_python/mindarmour.privacy.diff_privacy.rst | 261 ++++--- .../api_python/mindarmour.privacy.evaluation.rst | 125 ++-- .../api_python/mindarmour.privacy.sup_privacy.rst | 159 ++--- docs/api/api_python/mindarmour.reliability.rst | 131 ++-- docs/api/api_python/mindarmour.rst | 396 +++++------ docs/api/api_python/mindarmour.utils.rst | 97 ++- 11 files changed, 1214 insertions(+), 1518 deletions(-) diff --git a/docs/api/api_python/mindarmour.adv_robustness.attacks.rst b/docs/api/api_python/mindarmour.adv_robustness.attacks.rst index 4c7523f..4a6cc39 100644 --- a/docs/api/api_python/mindarmour.adv_robustness.attacks.rst +++ b/docs/api/api_python/mindarmour.adv_robustness.attacks.rst @@ -9,16 +9,15 @@ mindarmour.adv_robustness.attacks 参考文献：`I. J. Goodfellow, J. Shlens, and C. Szegedy, "Explaining and harnessing adversarial examples," in ICLR, 2015. `_。 - **参数：** - - - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 - - **alpha** (Union[float, None]) - 单步随机扰动与数据范围的比例。默认值：None。 - - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值, 数据最大值)的形式出现。默认值：(0.0, 1.0)。 - - **norm_level** (Union[int, str, numpy.inf]) - 范数类型。 - 可取值：numpy.inf、1、2、'1'、'2'、'l1'、'l2'、'np.inf'、'inf'、'linf'。默认值：2。 - - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **loss_fn** (Union[loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + 参数： + - **network** (Cell) - 目标模型。 + - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 + - **alpha** (Union[float, None]) - 单步随机扰动与数据范围的比例。默认值：None。 + - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值, 数据最大值)的形式出现。默认值：(0.0, 1.0)。 + - **norm_level** (Union[int, str, numpy.inf]) - 范数类型。 + 可取值：numpy.inf、1、2、'1'、'2'、'l1'、'l2'、'np.inf'、'inf'、'linf'。默认值：2。 + - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 + - **loss_fn** (Union[loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 .. 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) @@ -27,20 +26,18 @@ mindarmour.adv_robustness.attacks 参考文献：`Florian Tramer, Alexey Kurakin, Nicolas Papernot, "Ensemble adversarial training: Attacks and defenses" in ICLR, 2018 `_。 - **参数：** - - - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 - - **alpha** (float) - 单步随机扰动与数据范围的比例。默认值：0.035。 - - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 - - **norm_level** (Union[int, str, numpy.inf]) - 范数类型。 - 可取值：numpy.inf、1、2、'1'、'2'、'l1'、'l2'、'np.inf'、'inf'、'linf'。默认值：2。 - - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **loss_fn** (Union[loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + 参数： + - **network** (Cell) - 目标模型。 + - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 + - **alpha** (float) - 单步随机扰动与数据范围的比例。默认值：0.035。 + - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 + - **norm_level** (Union[int, str, numpy.inf]) - 范数类型。 + 可取值：numpy.inf、1、2、'1'、'2'、'l1'、'l2'、'np.inf'、'inf'、'linf'。默认值：2。 + - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 + - **loss_fn** (Union[loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 - **异常：** - - - **ValueError** - `eps` 小于 `alpha` 。 + 异常： + - **ValueError** - `eps` 小于 `alpha` 。 .. py:class:: mindarmour.adv_robustness.attacks.FastGradientSignMethod(network, eps=0.07, alpha=None, bounds=(0.0, 1.0), is_targeted=False, loss_fn=None) @@ -48,14 +45,13 @@ mindarmour.adv_robustness.attacks 参考文献：`Ian J. Goodfellow, J. Shlens, and C. Szegedy, "Explaining and harnessing adversarial examples," in ICLR, 2015 `_。 - **参数：** - - - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 - - **alpha** (Union[float, None]) - 单步随机扰动与数据范围的比例。默认值：None。 - - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 - - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **loss_fn** (Union[Loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + 参数： + - **network** (Cell) - 目标模型。 + - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 + - **alpha** (Union[float, None]) - 单步随机扰动与数据范围的比例。默认值：None。 + - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 + - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 + - **loss_fn** (Union[Loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 .. py:class:: mindarmour.adv_robustness.attacks.RandomFastGradientSignMethod(network, eps=0.07, alpha=0.035, bounds=(0.0, 1.0), is_targeted=False, loss_fn=None) @@ -64,18 +60,16 @@ mindarmour.adv_robustness.attacks 参考文献：`F. Tramer, et al., "Ensemble adversarial training: Attacks and defenses," in ICLR, 2018 `_。 - **参数：** + 参数： + - **network** (Cell) - 目标模型。 + - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 + - **alpha** (float) - 单步随机扰动与数据范围的比例。默认值：0.005。 + - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 + - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 + - **loss_fn** (Union[Loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 - - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 - - **alpha** (float) - 单步随机扰动与数据范围的比例。默认值：0.005。 - - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 - - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **loss_fn** (Union[Loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 - - **异常：** - - - **ValueError** - `eps` 小于 `alpha` 。 + 异常： + - **ValueError** - `eps` 小于 `alpha` 。 .. py:class:: mindarmour.adv_robustness.attacks.LeastLikelyClassMethod(network, eps=0.07, alpha=None, bounds=(0.0, 1.0), loss_fn=None) @@ -83,13 +77,12 @@ mindarmour.adv_robustness.attacks 参考文献：`F. Tramer, et al., "Ensemble adversarial training: Attacks and defenses," in ICLR, 2018 `_。 - **参数：** - - - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 - - **alpha** (Union[float, None]) - 单步随机扰动与数据范围的比例。默认值：None。 - - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 - - **loss_fn** (Union[Loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + 参数： + - **network** (Cell) - 目标模型。 + - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 + - **alpha** (Union[float, None]) - 单步随机扰动与数据范围的比例。默认值：None。 + - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 + - **loss_fn** (Union[Loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 .. py:class:: mindarmour.adv_robustness.attacks.RandomLeastLikelyClassMethod(network, eps=0.07, alpha=0.035, bounds=(0.0, 1.0), loss_fn=None) @@ -99,43 +92,38 @@ mindarmour.adv_robustness.attacks 参考文献：`F. Tramer, et al., "Ensemble adversarial training: Attacks and defenses," in ICLR, 2018 `_。 - **参数：** - - - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 - - **alpha** (float) - 单步随机扰动与数据范围的比例。默认值：0.005。 - - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 - - **loss_fn** (Union[Loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + 参数： + - **network** (Cell) - 目标模型。 + - **eps** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.07。 + - **alpha** (float) - 单步随机扰动与数据范围的比例。默认值：0.005。 + - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 + - **loss_fn** (Union[Loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 - **异常：** - - - **ValueError** - `eps` 小于 `alpha` 。 + 异常： + - **ValueError** - `eps` 小于 `alpha` 。 .. py:class:: mindarmour.adv_robustness.attacks.IterativeGradientMethod(network, eps=0.3, eps_iter=0.1, bounds=(0.0, 1.0), nb_iter=5, loss_fn=None) 所有基于迭代梯度的攻击的抽象基类。 - **参数：** - - - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。 - - **eps_iter** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.1。 - - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 - - **nb_iter** (int) - 迭代次数。默认值：5。 - - **loss_fn** (Union[Loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + 参数： + - **network** (Cell) - 目标模型。 + - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。 + - **eps_iter** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.1。 + - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 + - **nb_iter** (int) - 迭代次数。默认值：5。 + - **loss_fn** (Union[Loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 .. py:method:: generate(inputs, labels) 根据输入样本和原始/目标标签生成对抗样本。 - **参数：** - - - **inputs** (Union[numpy.ndarray, tuple]) - 良性输入样本，用于创建对抗样本。 - - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。 - - **异常：** + 参数： + - **inputs** (Union[numpy.ndarray, tuple]) - 良性输入样本，用于创建对抗样本。 + - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。 - - **NotImplementedError** - 此函数在迭代梯度方法中不可用。 + 异常： + - **NotImplementedError** - 此函数在迭代梯度方法中不可用。 .. 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) @@ -143,28 +131,25 @@ mindarmour.adv_robustness.attacks 参考文献：`A. Kurakin, I. Goodfellow, and S. Bengio, "Adversarial examples in the physical world," in ICLR, 2017 `_。 - **参数：** - - - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。 - - **eps_iter** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.1。 - - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 - - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **nb_iter** (int) - 迭代次数。默认值：5。 - - **loss_fn** (Union[Loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + 参数： + - **network** (Cell) - 目标模型。 + - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。 + - **eps_iter** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.1。 + - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 + - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 + - **nb_iter** (int) - 迭代次数。默认值：5。 + - **loss_fn** (Union[Loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 .. py:method:: generate(inputs, labels) 使用迭代FGSM方法生成对抗样本。 - **参数：** - - - **inputs** (Union[numpy.ndarray, tuple]) - 良性输入样本，用于创建对抗样本。 - - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。 + 参数： + - **inputs** (Union[numpy.ndarray, tuple]) - 良性输入样本，用于创建对抗样本。 + - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。 - **返回：** - - - **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) @@ -172,32 +157,29 @@ mindarmour.adv_robustness.attacks 参考文献：`Y. Dong, et al., "Boosting adversarial attacks with momentum," arXiv:1710.06081, 2017 `_。 - **参数：** - - - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。 - - **eps_iter** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.1。 - - **bounds** (tuple) - 数据的上下界，表示数据范围。 - 以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 - - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **nb_iter** (int) - 迭代次数。默认值：5。 - - **decay_factor** (float) - 迭代中的衰变因子。默认值：1.0。 - - **norm_level** (Union[int, str, numpy.inf]) - 范数类型。 - 可取值：numpy.inf、1、2、'1'、'2'、'l1'、'l2'、'np.inf'、'inf'、'linf'。默认值：numpy.inf。 - - **loss_fn** (Union[Loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + 参数： + - **network** (Cell) - 目标模型。 + - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。 + - **eps_iter** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.1。 + - **bounds** (tuple) - 数据的上下界，表示数据范围。 + 以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 + - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 + - **nb_iter** (int) - 迭代次数。默认值：5。 + - **decay_factor** (float) - 迭代中的衰变因子。默认值：1.0。 + - **norm_level** (Union[int, str, numpy.inf]) - 范数类型。 + 可取值：numpy.inf、1、2、'1'、'2'、'l1'、'l2'、'np.inf'、'inf'、'linf'。默认值：numpy.inf。 + - **loss_fn** (Union[Loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 .. py:method:: generate(inputs, labels) 根据输入数据和原始/目标标签生成对抗样本。 - **参数：** + 参数： + - **inputs** (Union[numpy.ndarray, tuple]) - 良性输入样本，用于创建对抗样本。 + - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。 - - **inputs** (Union[numpy.ndarray, tuple]) - 良性输入样本，用于创建对抗样本。 - - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。 - - **返回：** - - - **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) @@ -205,30 +187,27 @@ mindarmour.adv_robustness.attacks 参考文献：`A. Madry, et al., "Towards deep learning models resistant to adversarial attacks," in ICLR, 2018 `_。 - **参数：** - - - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。 - - **eps_iter** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.1。 - - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 - - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **nb_iter** (int) - 迭代次数。默认值：5。 - - **norm_level** (Union[int, str, numpy.inf]) - 范数类型。 - 可取值：numpy.inf、1、2、'1'、'2'、'l1'、'l2'、'np.inf'、'inf'、'linf'。默认值：'numpy.inf'。 - - **loss_fn** (Union[Loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + 参数： + - **network** (Cell) - 目标模型。 + - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。 + - **eps_iter** (float) - 攻击产生的单步对抗扰动占数据范围的比例。默认值：0.1。 + - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 + - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 + - **nb_iter** (int) - 迭代次数。默认值：5。 + - **norm_level** (Union[int, str, numpy.inf]) - 范数类型。 + 可取值：numpy.inf、1、2、'1'、'2'、'l1'、'l2'、'np.inf'、'inf'、'linf'。默认值：'numpy.inf'。 + - **loss_fn** (Union[Loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 .. py:method:: generate(inputs, labels) 基于BIM方法迭代生成对抗样本。通过带有参数norm_level的投影方法归一化扰动。 - **参数：** - - - **inputs** (Union[numpy.ndarray, tuple]) - 良性输入样本，用于创建对抗样本。 - - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。 + 参数： + - **inputs** (Union[numpy.ndarray, tuple]) - 良性输入样本，用于创建对抗样本。 + - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。 - **返回：** - - - **numpy.ndarray** - 生成的对抗样本。 + 返回： + - **numpy.ndarray** - 生成的对抗样本。 .. 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) @@ -236,27 +215,24 @@ mindarmour.adv_robustness.attacks 参考文献：`Xie, Cihang and Zhang, et al., "Improving Transferability of Adversarial Examples With Input Diversity," in CVPR, 2019 `_。 - **参数：** - - - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。 - - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 - - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **prob** (float) - 对输入样本的转换概率。默认值：0.5。 - - **loss_fn** (Union[Loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + 参数： + - **network** (Cell) - 目标模型。 + - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。 + - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 + - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 + - **prob** (float) - 对输入样本的转换概率。默认值：0.5。 + - **loss_fn** (Union[Loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 .. py:method:: generate(inputs, labels) 基于多样性输入迭代法生成对抗样本。 - **参数：** - - - **inputs** (Union[numpy.ndarray, tuple]) - 良性输入样本，用于创建对抗样本。 - - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。 - - **返回：** + 参数： + - **inputs** (Union[numpy.ndarray, tuple]) - 良性输入样本，用于创建对抗样本。 + - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。 - - **numpy.ndarray** - 生成的对抗样本。 + 返回： + - **numpy.ndarray** - 生成的对抗样本。 .. 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) @@ -264,16 +240,15 @@ mindarmour.adv_robustness.attacks 参考文献：`Xie, Cihang and Zhang, et al., "Improving Transferability of Adversarial Examples With Input Diversity," in CVPR, 2019 `_。 - **参数：** - - - **network** (Cell) - 目标模型。 - - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。 - - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 - - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **norm_level** (Union[int, str, numpy.inf]) - 范数类型。 - 可取值：numpy.inf、1、2、'1'、'2'、'l1'、'l2'、'np.inf'、'inf'、'linf'。默认值：'l1'。 - - **prob** (float) - 对输入样本的转换概率。默认值：0.5。 - - **loss_fn** (Union[Loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 + 参数： + - **network** (Cell) - 目标模型。 + - **eps** (float) - 攻击产生的对抗性扰动占数据范围的比例。默认值：0.3。 + - **bounds** (tuple) - 数据的上下界，表示数据范围。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 + - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 + - **norm_level** (Union[int, str, numpy.inf]) - 范数类型。 + 可取值：numpy.inf、1、2、'1'、'2'、'l1'、'l2'、'np.inf'、'inf'、'linf'。默认值：'l1'。 + - **prob** (float) - 对输入样本的转换概率。默认值：0.5。 + - **loss_fn** (Union[Loss, None]) - 用于优化的损失函数。如果为None，则输入网络已配备损失函数。默认值：None。 .. py:class:: mindarmour.adv_robustness.attacks.DeepFool(network, num_classes, model_type='classification', reserve_ratio=0.3, max_iters=50, overshoot=0.02, norm_level=2, bounds=None, sparse=True) @@ -281,41 +256,37 @@ mindarmour.adv_robustness.attacks 参考文献：`DeepFool: a simple and accurate method to fool deep neural networks `_。 - **参数：** - - - **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, numpy.inf]) - 矢量范数类型。可取值：numpy.inf或2。默认值：2。 - - **bounds** (Union[tuple, list]) - 数据范围的上下界。以(数据最小值，数据最大值)的形式出现。默认值：None。 - - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为one-hot编码。默认值：True。 + 参数： + - **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, numpy.inf]) - 矢量范数类型。可取值：numpy.inf或2。默认值：2。 + - **bounds** (Union[tuple, list]) - 数据范围的上下界。以(数据最小值，数据最大值)的形式出现。默认值：None。 + - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为one-hot编码。默认值：True。 .. py:method:: generate(inputs, labels) 根据输入样本和原始标签生成对抗样本。 - **参数：** - - - **inputs** (Union[numpy.ndarray, tuple]) - 输入样本。 - - - 如果 `model_type` ='classification'，则输入的格式应为numpy.ndarray。输入的格式可以是(input1, input2, ...)。 - - 如果 `model_type` ='detection'，则只能是一个数组。 + 参数： + - **inputs** (Union[numpy.ndarray, tuple]) - 输入样本。 - - **labels** (Union[numpy.ndarray, tuple]) - 目标标签或ground-truth标签。 + - 如果 `model_type` ='classification'，则输入的格式应为numpy.ndarray。输入的格式可以是(input1, input2, ...)。 + - 如果 `model_type` ='detection'，则只能是一个数组。 - - 如果 `model_type` ='classification'，标签的格式应为numpy.ndarray。 - - 如果 `model_type` ='detection'，标签的格式应为(gt_boxes, gt_labels)。 + - **labels** (Union[numpy.ndarray, tuple]) - 目标标签或ground-truth标签。 - **返回：** + - 如果 `model_type` ='classification'，标签的格式应为numpy.ndarray。 + - 如果 `model_type` ='detection'，标签的格式应为(gt_boxes, gt_labels)。 - - **numpy.ndarray** - 对抗样本。 + 返回： + - **numpy.ndarray** - 对抗样本。 - **异常：** - - - **NotImplementedError** - `norm_level` 不在[2, numpy.inf, '2', 'inf']中。 + 异常： + - **NotImplementedError** - `norm_level` 不在[2, numpy.inf, '2', 'inf']中。 .. 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=5e-3, initial_const=1e-2, abort_early_check_ratio=5e-2, targeted=False, fast=True, abort_early=True, sparse=True) @@ -323,39 +294,36 @@ mindarmour.adv_robustness.attacks 参考文献：`Nicholas Carlini, David Wagner: "Towards Evaluating the Robustness of Neural Networks" `_。 - **参数：** - - - **network** (Cell) - 目标模型。 - - **num_classes** (int) - 模型输出的标签数，应大于零。 - - **box_min** (float) - 目标模型输入的下界。默认值：0。 - - **box_max** (float) - 目标模型输入的上界。默认值：1.0。 - - **bin_search_steps** (int) - 用于查找距离和置信度之间的最优trade-off常数的二分查找步数。默认值：5。 - - **max_iterations** (int) - 最大迭代次数，应大于零。默认值：1000。 - - **confidence** (float) - 对抗样本输出的置信度。默认值：0。 - - **learning_rate** (float) - 攻击算法的学习率。默认值：5e-3。 - - **initial_const** (float) - 用于平衡扰动范数和置信度差异的初始trade-off常数。默认值：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，则输入标签为one-hot编码。默认值：True。 + 参数： + - **network** (Cell) - 目标模型。 + - **num_classes** (int) - 模型输出的标签数，应大于零。 + - **box_min** (float) - 目标模型输入的下界。默认值：0。 + - **box_max** (float) - 目标模型输入的上界。默认值：1.0。 + - **bin_search_steps** (int) - 用于查找距离和置信度之间的最优trade-off常数的二分查找步数。默认值：5。 + - **max_iterations** (int) - 最大迭代次数，应大于零。默认值：1000。 + - **confidence** (float) - 对抗样本输出的置信度。默认值：0。 + - **learning_rate** (float) - 攻击算法的学习率。默认值：5e-3。 + - **initial_const** (float) - 用于平衡扰动范数和置信度差异的初始trade-off常数。默认值：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，则输入标签为one-hot编码。默认值：True。 .. py:method:: generate(inputs, labels) 根据输入数据和目标标签生成对抗样本。 - **参数：** - - - **inputs** (numpy.ndarray) - 输入样本。 - - **labels** (numpy.ndarray) - 输入样本的真值标签或目标标签。 + 参数： + - **inputs** (numpy.ndarray) - 输入样本。 + - **labels** (numpy.ndarray) - 输入样本的真值标签或目标标签。 - **返回：** - - - **numpy.ndarray** - 生成的对抗样本。 + 返回： + - **numpy.ndarray** - 生成的对抗样本。 .. 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) @@ -363,30 +331,27 @@ mindarmour.adv_robustness.attacks 参考文献：`The limitations of deep learning in adversarial settings `_。 - **参数：** - - - **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，则输入标签为one-hot编码。默认值：True。 + 参数： + - **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，则输入标签为one-hot编码。默认值：True。 .. py:method:: generate(inputs, labels) 批量生成对抗样本。 - **参数：** + 参数： + - **inputs** (numpy.ndarray) - 输入样本。 + - **labels** (numpy.ndarray) - 目标标签。 - - **inputs** (numpy.ndarray) - 输入样本。 - - **labels** (numpy.ndarray) - 目标标签。 - - **返回：** - - - **numpy.ndarray** - 对抗样本。 + 返回： + - **numpy.ndarray** - 对抗样本。 .. py:class:: mindarmour.adv_robustness.attacks.LBFGS(network, eps=1e-5, bounds=(0.0, 1.0), is_targeted=True, nb_iter=150, search_iters=30, loss_fn=None, sparse=False) @@ -394,29 +359,26 @@ mindarmour.adv_robustness.attacks 参考文献：`Pedro Tabacof, Eduardo Valle. "Exploring the Space of Adversarial Images" `_。 - **参数：** - - - **network** (Cell) - 被攻击模型的网络。 - - **eps** (float) - 攻击步长。默认值：1e-5。 - - **bounds** (tuple) - 数据的上下界。默认值：(0.0, 1.0) - - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：True。 - - **nb_iter** (int) - lbfgs优化器的迭代次数，应大于零。默认值：150。 - - **search_iters** (int) - 步长的变更数，应大于零。默认值：30。 - - **loss_fn** (Functions) - 替代模型的损失函数。默认值：None。 - - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为one-hot编码。默认值：False。 + 参数： + - **network** (Cell) - 被攻击模型的网络。 + - **eps** (float) - 攻击步长。默认值：1e-5。 + - **bounds** (tuple) - 数据的上下界。默认值：(0.0, 1.0) + - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：True。 + - **nb_iter** (int) - lbfgs优化器的迭代次数，应大于零。默认值：150。 + - **search_iters** (int) - 步长的变更数，应大于零。默认值：30。 + - **loss_fn** (Functions) - 替代模型的损失函数。默认值：None。 + - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为one-hot编码。默认值：False。 .. py:method:: generate(inputs, labels) 根据输入数据和目标标签生成对抗样本。 - **参数：** - - - **inputs** (numpy.ndarray) - 良性输入样本，用于创建对抗样本。 - - **labels** (numpy.ndarray) - 原始/目标标签。 + 参数： + - **inputs** (numpy.ndarray) - 良性输入样本，用于创建对抗样本。 + - **labels** (numpy.ndarray) - 原始/目标标签。 - **返回：** - - - **numpy.ndarray** - 生成的对抗样本。 + 返回： + - **numpy.ndarray** - 生成的对抗样本。 .. py:class:: mindarmour.adv_robustness.attacks.GeneticAttack(model, model_type='classification', targeted=True, reserve_ratio=0.3, sparse=True, pop_size=6, mutation_rate=0.005, per_bounds=0.15, max_steps=1000, step_size=0.20, temp=0.3, bounds=(0, 1.0), adaptive=False, c=0.1) @@ -426,44 +388,41 @@ mindarmour.adv_robustness.attacks 参考文献： `Moustafa Alzantot, Yash Sharma, Supriyo Chakraborty, "GeneticAttack: Practical Black-box Attacks with Gradient-FreeOptimization" `_。 - **参数：** - - - **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]) - 数据的上下界。以(数据最小值，数据最大值)的形式出现。默认值：(0, 1.0)。 - - **adaptive** (bool) - 为True，则打开突变参数的动态缩放。如果为false，则打开静态突变参数。默认值：False。 - - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为one-hot编码。默认值：True。 - - **c** (Union[int, float]) - 扰动损失的权重。默认值：0.1。 + 参数： + - **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]) - 数据的上下界。以(数据最小值，数据最大值)的形式出现。默认值：(0, 1.0)。 + - **adaptive** (bool) - 为True，则打开突变参数的动态缩放。如果为false，则打开静态突变参数。默认值：False。 + - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为one-hot编码。默认值：True。 + - **c** (Union[int, float]) - 扰动损失的权重。默认值：0.1。 .. py:method:: generate(inputs, labels) 根据输入数据和目标标签（或ground_truth标签）生成对抗样本。 - **参数：** - - - **inputs** (Union[numpy.ndarray, tuple]) - 输入样本。 + 参数： + - **inputs** (Union[numpy.ndarray, tuple]) - 输入样本。 - - 如果 `model_type` ='classification'，则输入的格式应为numpy.ndarray。输入的格式可以是(input1, input2, ...)。 - - 如果 `model_type` ='detection'，则只能是一个数组。 + - 如果 `model_type` ='classification'，则输入的格式应为numpy.ndarray。输入的格式可以是(input1, input2, ...)。 + - 如果 `model_type` ='detection'，则只能是一个数组。 - - **labels** (Union[numpy.ndarray, tuple]) - 目标标签或ground-truth标签。 + - **labels** (Union[numpy.ndarray, tuple]) - 目标标签或ground-truth标签。 - - 如果 `model_type` ='classification'，标签的格式应为numpy.ndarray。 - - 如果 `model_type` ='detection'，标签的格式应为(gt_boxes, gt_labels)。 + - 如果 `model_type` ='classification'，标签的格式应为numpy.ndarray。 + - 如果 `model_type` ='detection'，标签的格式应为(gt_boxes, gt_labels)。 - **返回：** - - - **numpy.ndarray** - 每个攻击结果的布尔值。 - - **numpy.ndarray** - 生成的对抗样本。 - - **numpy.ndarray** - 每个样本的查询次数。 + 返回： + - **numpy.ndarray** - 每个攻击结果的布尔值。 + - **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) @@ -471,50 +430,45 @@ mindarmour.adv_robustness.attacks 参考文献：`Chen J, Michael I. Jordan, Martin J. Wainwright. HopSkipJumpAttack: A Query-Efficient Decision-Based Attack. 2019. arXiv:1904.02144 `_。 - **参数：** - - - **model** (BlackModel) - 目标模型。 - - **init_num_evals** (int) - 梯度估计的初始评估数。默认值：100。 - - **max_num_evals** (int) - 梯度估计的最大评估数。默认值：1000。 - - **stepsize_search** (str) - 表示要如何搜索步长； - - - 可取值为'geometric_progression'或'grid_search'。默认值：'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，则输入标签为one-hot编码。默认值：True。 - - **异常：** - - - **ValueError** - `stepsize_search` 不在['geometric_progression','grid_search']中。 - - **ValueError** - `constraint` 不在['l2', 'linf']中 + 参数： + - **model** (BlackModel) - 目标模型。 + - **init_num_evals** (int) - 梯度估计的初始评估数。默认值：100。 + - **max_num_evals** (int) - 梯度估计的最大评估数。默认值：1000。 + - **stepsize_search** (str) - 表示要如何搜索步长； + + - 可取值为'geometric_progression'或'grid_search'。默认值：'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，则输入标签为one-hot编码。默认值：True。 + + 异常： + - **ValueError** - `stepsize_search` 不在['geometric_progression','grid_search']中。 + - **ValueError** - `constraint` 不在['l2', 'linf']中 .. py:method:: generate(inputs, labels) 在for循环中生成对抗图像。 - **参数：** + 参数： + - **inputs** (numpy.ndarray) - 原始图像。 + - **labels** (numpy.ndarray) - 目标标签。 - - **inputs** (numpy.ndarray) - 原始图像。 - - **labels** (numpy.ndarray) - 目标标签。 - - **返回：** - - - **numpy.ndarray** - 每个攻击结果的布尔值。 - - **numpy.ndarray** - 生成的对抗样本。 - - **numpy.ndarray** - 每个样本的查询次数。 + 返回： + - **numpy.ndarray** - 每个攻击结果的布尔值。 + - **numpy.ndarray** - 生成的对抗样本。 + - **numpy.ndarray** - 每个样本的查询次数。 .. py:method:: set_target_images(target_images) 设置目标图像进行目标攻击。 - **参数：** - - - **target_images** (numpy.ndarray) - 目标图像。 + 参数： + - **target_images** (numpy.ndarray) - 目标图像。 .. py:class:: mindarmour.adv_robustness.attacks.NES(model, scene, max_queries=10000, top_k=-1, num_class=10, batch_size=128, epsilon=0.3, samples_per_draw=128, momentum=0.9, learning_rate=1e-3, max_lr=5e-2, min_lr=5e-4, sigma=1e-3, 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=1e-3, conservative=2, sparse=True) @@ -529,59 +483,54 @@ mindarmour.adv_robustness.attacks 参考文献：`Andrew Ilyas, Logan Engstrom, Anish Athalye, and Jessy Lin. Black-box adversarial attacks with limited queries and information. In ICML, July 2018 `_。 - **参数：** - - - **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，则输入标签为one-hot编码。默认值：True。 + 参数： + - **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，则输入标签为one-hot编码。默认值：True。 .. py:method:: generate(inputs, labels) 根据输入数据和目标标签生成对抗样本。 - **参数：** - - - **inputs** (numpy.ndarray) - 良性输入样本。 - - **labels** (numpy.ndarray) - 目标标签。 + 参数： + - **inputs** (numpy.ndarray) - 良性输入样本。 + - **labels** (numpy.ndarray) - 目标标签。 - **返回：** + 返回： + - **numpy.ndarray** - 每个攻击结果的布尔值。 + - **numpy.ndarray** - 生成的对抗样本。 + - **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** - `scene` 不在['Label_Only', 'Partial_Info', 'Query_Limit']中 + 异常： + - **ValueError** - 在'Label-Only'或'Partial-Info'设置中 `top_k` 小于0。 + - **ValueError** - 在'Label-Only'或'Partial-Info'设置中target_imgs为None。 + - **ValueError** - `scene` 不在['Label_Only', 'Partial_Info', 'Query_Limit']中 .. py:method:: set_target_images(target_images) 在'Partial-Info'或'Label-Only'设置中设置目标攻击的目标样本。 - **参数：** - - - **target_images** (numpy.ndarray) - 目标攻击的目标样本。 + 参数： + - **target_images** (numpy.ndarray) - 目标攻击的目标样本。 .. py:class:: mindarmour.adv_robustness.attacks.PointWiseAttack(model, max_iter=1000, search_iter=10, is_targeted=False, init_attack=None, sparse=True) @@ -590,30 +539,27 @@ mindarmour.adv_robustness.attacks 参考文献：`L. Schott, J. Rauber, M. Bethge, W. Brendel: "Towards the first adversarially robust neural network model on MNIST", ICLR (2019) `_。 - **参数：** - - - **model** (BlackModel) - 目标模型。 - - **max_iter** (int) - 生成对抗图像的最大迭代轮数。默认值：1000。 - - **search_iter** (int) - 二进制搜索的最大轮数。默认值：10。 - - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **init_attack** (Union[Attack, None]) - 用于查找起点的攻击。默认值：None。 - - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为one-hot编码。默认值：True。 + 参数： + - **model** (BlackModel) - 目标模型。 + - **max_iter** (int) - 生成对抗图像的最大迭代轮数。默认值：1000。 + - **search_iter** (int) - 二进制搜索的最大轮数。默认值：10。 + - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 + - **init_attack** (Union[Attack, None]) - 用于查找起点的攻击。默认值：None。 + - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为one-hot编码。默认值：True。 .. py:method:: generate(inputs, labels) 根据输入样本和目标标签生成对抗样本。 - **参数：** + 参数： + - **inputs** (numpy.ndarray) - 良性输入样本，用于创建对抗样本。 + - **labels** (numpy.ndarray) - 对于有目标的攻击，标签是对抗性的目标标签。对于无目标攻击，标签是ground-truth标签。 - - **inputs** (numpy.ndarray) - 良性输入样本，用于创建对抗样本。 - - **labels** (numpy.ndarray) - 对于有目标的攻击，标签是对抗性的目标标签。对于无目标攻击，标签是ground-truth标签。 - - **返回：** - - - **numpy.ndarray** - 每个攻击结果的布尔值。 - - **numpy.ndarray** - 生成的对抗样本。 - - **numpy.ndarray** - 每个样本的查询次数。 + 返回： + - **numpy.ndarray** - 每个攻击结果的布尔值。 + - **numpy.ndarray** - 生成的对抗样本。 + - **numpy.ndarray** - 每个样本的查询次数。 .. 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) @@ -622,68 +568,62 @@ mindarmour.adv_robustness.attacks 参考文献：`Rayan Mosli, Matthew Wright, Bo Yuan, Yin Pan, "They Might NOT Be Giants: Crafting Black-Box Adversarial Examples with Fewer Queries Using Particle Swarm Optimization", arxiv: 1909.07490, 2019. `_。 - **参数：** - - - **model** (BlackModel) - 目标模型。 - - **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]) - 数据的上下界。以(数据最小值，数据最大值)的形式出现。默认值：None。 - - **targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。 `model_type` ='detection'仅支持无目标攻击，默认值：False。 - - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为one-hot编码。默认值：True。 - - **model_type** (str) - 目标模型的类型。现在支持'classification'和'detection'。默认值：'classification'。 - - **reserve_ratio** (Union[int, float]) - 攻击后可检测到的对象百分比，用于 `model_type` ='detection'模式。保留比率应在(0, 1)的范围内。默认值：0.3。 + 参数： + - **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]) - 数据的上下界。以(数据最小值，数据最大值)的形式出现。默认值：None。 + - **targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。 `model_type` ='detection'仅支持无目标攻击，默认值：False。 + - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为one-hot编码。默认值：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'，则只能是一个数组。 + 参数： + - **inputs** (Union[numpy.ndarray, tuple]) - 输入样本。 - - **labels** (Union[numpy.ndarray, tuple]) - 目标标签或ground-truth标签。 + - 如果 `model_type` ='classification'，则输入的格式应为numpy.ndarray。输入的格式可以是(input1, input2, ...)。 + - 如果 `model_type` ='detection'，则只能是一个数组。 - - 如果 `model_type` ='classification'，标签的格式应为numpy.ndarray。 - - 如果 `model_type` ='detection'，标签的格式应为(gt_boxes, gt_labels)。 + - **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** - 每个样本的查询次数。 + 返回： + - **numpy.ndarray** - 每个攻击结果的布尔值。 + - **numpy.ndarray** - 生成的对抗样本。 + - **numpy.ndarray** - 每个样本的查询次数。 .. 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) - 数据的上下界。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 - - **max_iter** (int) - 生成对抗样本的最大迭代。默认值：100。 - - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 - - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为one-hot编码。默认值：True。 + 参数： + - **model** (BlackModel) - 目标模型。 + - **bounds** (tuple) - 数据的上下界。以(数据最小值，数据最大值)的形式出现。默认值：(0.0, 1.0)。 + - **max_iter** (int) - 生成对抗样本的最大迭代。默认值：100。 + - **is_targeted** (bool) - 如果为True，则为目标攻击。如果为False，则为无目标攻击。默认值：False。 + - **sparse** (bool) - 如果为True，则输入标签为稀疏编码。如果为False，则输入标签为one-hot编码。默认值：True。 .. py:method:: generate(inputs, labels) 根据输入数据和目标标签生成对抗样本。 - **参数：** - - - **inputs** (numpy.ndarray) - 原始的、未受扰动的输入。 - - **labels** (numpy.ndarray) - 目标标签。 - - **返回：** + 参数： + - **inputs** (numpy.ndarray) - 原始的、未受扰动的输入。 + - **labels** (numpy.ndarray) - 目标标签。 - - **numpy.ndarray** - 每个攻击结果的布尔值。 - - **numpy.ndarray** - 生成的对抗样本。 - - **numpy.ndarray** - 每个样本的查询次数。 + 返回： + - **numpy.ndarray** - 每个攻击结果的布尔值。 + - **numpy.ndarray** - 生成的对抗样本。 + - **numpy.ndarray** - 每个样本的查询次数。 diff --git a/docs/api/api_python/mindarmour.adv_robustness.defenses.rst b/docs/api/api_python/mindarmour.adv_robustness.defenses.rst index 03f4a41..c24dae6 100644 --- a/docs/api/api_python/mindarmour.adv_robustness.defenses.rst +++ b/docs/api/api_python/mindarmour.adv_robustness.defenses.rst @@ -7,54 +7,47 @@ mindarmour.adv_robustness.defenses 使用给定的对抗样本进行对抗训练。 - **参数：** - - - **network** (Cell) - 要防御的MindSpore网络。 - - **loss_fn** (Union[Loss, None]) - 损失函数。默认值：None。 - - **optimizer** (Cell) - 用于训练网络的优化器。默认值：None。 + 参数： + - **network** (Cell) - 要防御的MindSpore网络。 + - **loss_fn** (Union[Loss, None]) - 损失函数。默认值：None。 + - **optimizer** (Cell) - 用于训练网络的优化器。默认值：None。 .. py:method:: defense(inputs, labels) 通过使用输入样本进行训练来增强模型。 - **参数：** - - - **inputs** (numpy.ndarray) - 输入样本。 - - **labels** (numpy.ndarray) - 输入样本的标签。 - - **返回：** + 参数： + - **inputs** (numpy.ndarray) - 输入样本。 + - **labels** (numpy.ndarray) - 输入样本的标签。 - - **numpy.ndarray** - 防御操作的损失。 + 返回： + - **numpy.ndarray** - 防御操作的损失。 .. py:class:: mindarmour.adv_robustness.defenses.AdversarialDefenseWithAttacks(network, attacks, loss_fn=None, optimizer=None, bounds=(0.0, 1.0), replace_ratio=0.5) 利用特定的攻击方法和给定的对抗例子进行对抗训练，以增强模型的鲁棒性。 - **参数：** + 参数： + - **network** (Cell) - 要防御的MindSpore网络。 + - **attacks** (list[Attack]) - 攻击方法序列。 + - **loss_fn** (Union[Loss, None]) - 损失函数。默认值：None。 + - **optimizer** (Cell) - 用于训练网络的优化器。默认值：None。 + - **bounds** (tuple) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 + - **replace_ratio** (float) - 用对抗样本替换原始样本的比率，必须在0到1之间。默认值：0.5。 - - **network** (Cell) - 要防御的MindSpore网络。 - - **attacks** (list[Attack]) - 攻击方法序列。 - - **loss_fn** (Union[Loss, None]) - 损失函数。默认值：None。 - - **optimizer** (Cell) - 用于训练网络的优化器。默认值：None。 - - **bounds** (tuple) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 - - **replace_ratio** (float) - 用对抗样本替换原始样本的比率，必须在0到1之间。默认值：0.5。 - - **异常：** - - - **ValueError** - `replace_ratio` 不在0和1之间。 + 异常： + - **ValueError** - `replace_ratio` 不在0和1之间。 .. py:method:: defense(inputs, labels) 通过使用从输入样本生成的对抗样本进行训练来增强模型。 - **参数：** - - - **inputs** (numpy.ndarray) - 输入样本。 - - **labels** (numpy.ndarray) - 输入样本的标签。 + 参数： + - **inputs** (numpy.ndarray) - 输入样本。 + - **labels** (numpy.ndarray) - 输入样本的标签。 - **返回：** - - - **numpy.ndarray** - 对抗性防御操作的损失。 + 返回： + - **numpy.ndarray** - 对抗性防御操作的损失。 .. py:class:: mindarmour.adv_robustness.defenses.NaturalAdversarialDefense(network, loss_fn=None, optimizer=None, bounds=(0.0, 1.0), replace_ratio=0.5, eps=0.1) @@ -62,14 +55,13 @@ mindarmour.adv_robustness.defenses 参考文献：`A. Kurakin, et al., "Adversarial machine learning at scale," in ICLR, 2017 `_。 - **参数：** - - - **network** (Cell) - 要防御的MindSpore网络。 - - **loss_fn** (Union[Loss, None]) - 损失函数。默认值：None。 - - **optimizer** (Cell)：用于训练网络的优化器。默认值：None。 - - **bounds** (tuple) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 - - **replace_ratio** (float) - 用对抗样本替换原始样本的比率。默认值：0.5。 - - **eps** (float) - 攻击方法（FGSM）的步长。默认值：0.1。 + 参数： + - **network** (Cell) - 要防御的MindSpore网络。 + - **loss_fn** (Union[Loss, None]) - 损失函数。默认值：None。 + - **optimizer** (Cell)：用于训练网络的优化器。默认值：None。 + - **bounds** (tuple) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 + - **replace_ratio** (float) - 用对抗样本替换原始样本的比率。默认值：0.5。 + - **eps** (float) - 攻击方法（FGSM）的步长。默认值：0.1。 .. py:class:: mindarmour.adv_robustness.defenses.ProjectedAdversarialDefense(network, loss_fn=None, optimizer=None, bounds=(0.0, 1.0), replace_ratio=0.5, eps=0.3, eps_iter=0.1, nb_iter=5, norm_level='inf') @@ -77,31 +69,28 @@ mindarmour.adv_robustness.defenses 参考文献：`A. Madry, et al., "Towards deep learning models resistant to adversarial attacks," in ICLR, 2018 `_。 - **参数：** - - - **network** (Cell) - 要防御的MindSpore网络。 - - **loss_fn** (Union[Loss, None]) - 损失函数。默认值：None。 - - **optimizer** (Cell) - 用于训练网络的优化器。默认值：None。 - - **bounds** (tuple) - 输入数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 - - **replace_ratio** (float) - 用对抗样本替换原始样本的比率。默认值：0.5。 - - **eps** (float) - PGD攻击参数epsilon。默认值：0.3。 - - **eps_iter** (int) - PGD攻击参数，内环epsilon。默认值：0.1。 - - **nb_iter** (int) - PGD攻击参数，迭代次数。默认值：5。 - - **norm_level** (Union[int, char, numpy.inf]) - 范数类型。可选值：1、2、np.inf、'l1'、'l2'、'np.inf' 或 'inf'。默认值：'inf'。 + 参数： + - **network** (Cell) - 要防御的MindSpore网络。 + - **loss_fn** (Union[Loss, None]) - 损失函数。默认值：None。 + - **optimizer** (Cell) - 用于训练网络的优化器。默认值：None。 + - **bounds** (tuple) - 输入数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 + - **replace_ratio** (float) - 用对抗样本替换原始样本的比率。默认值：0.5。 + - **eps** (float) - PGD攻击参数epsilon。默认值：0.3。 + - **eps_iter** (int) - PGD攻击参数，内环epsilon。默认值：0.1。 + - **nb_iter** (int) - PGD攻击参数，迭代次数。默认值：5。 + - **norm_level** (Union[int, char, numpy.inf]) - 范数类型。可选值：1、2、np.inf、'l1'、'l2'、'np.inf' 或 'inf'。默认值：'inf'。 .. py:class:: mindarmour.adv_robustness.defenses.EnsembleAdversarialDefense(network, attacks, loss_fn=None, optimizer=None, bounds=(0.0, 1.0), replace_ratio=0.5) 使用特定攻击方法列表和给定的对抗样本进行对抗训练，以增强模型的鲁棒性。 - **参数：** - - - **network** (Cell) - 要防御的MindSpore网络。 - - **attacks** (list[Attack]) - 攻击方法序列。 - - **loss_fn** (Union[Loss, None]) - 损失函数。默认值：None。 - - **optimizer** (Cell) - 用于训练网络的优化器。默认值：None。 - - **bounds** (tuple) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 - - **replace_ratio** (float) - 用对抗样本替换原始样本的比率，必须在0到1之间。默认值：0.5。 - - **异常：** + 参数： + - **network** (Cell) - 要防御的MindSpore网络。 + - **attacks** (list[Attack]) - 攻击方法序列。 + - **loss_fn** (Union[Loss, None]) - 损失函数。默认值：None。 + - **optimizer** (Cell) - 用于训练网络的优化器。默认值：None。 + - **bounds** (tuple) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 + - **replace_ratio** (float) - 用对抗样本替换原始样本的比率，必须在0到1之间。默认值：0.5。 - - **ValueError** - `replace_ratio` 不在0和1之间。 + 异常： + - **ValueError** - `replace_ratio` 不在0和1之间。 diff --git a/docs/api/api_python/mindarmour.adv_robustness.detectors.rst b/docs/api/api_python/mindarmour.adv_robustness.detectors.rst index d1771bd..993c160 100644 --- a/docs/api/api_python/mindarmour.adv_robustness.detectors.rst +++ b/docs/api/api_python/mindarmour.adv_robustness.detectors.rst @@ -9,68 +9,58 @@ mindarmour.adv_robustness.detectors 参考文献： `MagNet: a Two-Pronged Defense against Adversarial Examples, by Dongyu Meng and Hao Chen, at CCS 2017. `_。 - **参数：** - - - **auto_encoder** (Model) - 一个（训练过的）自动编码器，对输入图片进行重构。 - - **false_positive_rate** (float) - 检测器的误报率。默认值：0.01。 - - **bounds** (tuple) - (clip_min, clip_max)。默认值：(0.0, 1.0)。 + 参数： + - **auto_encoder** (Model) - 一个（训练过的）自动编码器，对输入图片进行重构。 + - **false_positive_rate** (float) - 检测器的误报率。默认值：0.01。 + - **bounds** (tuple) - (clip_min, clip_max)。默认值：(0.0, 1.0)。 .. py:method:: detect(inputs) 检测输入样本是否具有对抗性。 - **参数：** - - - **inputs** (numpy.ndarray) - 待判断的可疑样本。 + 参数： + - **inputs** (numpy.ndarray) - 待判断的可疑样本。 - **返回：** - - - **list[int]** - 样本是否具有对抗性。如果res[i]=1，则索引为i的输入样本是对抗性的。 + 返回： + - **list[int]** - 样本是否具有对抗性。如果res[i]=1，则索引为i的输入样本是对抗性的。 .. py:method:: detect_diff(inputs) 检测原始样本和重建样本之间的距离。 - **参数：** - - - **inputs** (numpy.ndarray) - 输入样本。 + 参数： + - **inputs** (numpy.ndarray) - 输入样本。 - **返回：** - - - **float** - 重建样本和原始样本之间的距离。 + 返回： + - **float** - 重建样本和原始样本之间的距离。 .. py:method:: fit(inputs, labels=None) 查找给定数据集的阈值，以区分对抗样本。 - **参数：** - - - **inputs** (numpy.ndarray) - 输入样本。 - - **labels** (numpy.ndarray) - 输入样本的标签。默认值：None。 - - **返回：** + 参数： + - **inputs** (numpy.ndarray) - 输入样本。 + - **labels** (numpy.ndarray) - 输入样本的标签。默认值：None。 - - **float** - 区分对抗样本和良性样本的阈值。 + 返回： + - **float** - 区分对抗样本和良性样本的阈值。 .. py:method:: set_threshold(threshold) 设置阈值。 - **参数：** - - - **threshold** (float) - 检测阈值。 + 参数： + - **threshold** (float) - 检测阈值。 .. py:method:: transform(inputs) 重建输入样本。 - **参数：** - - - **inputs** (numpy.ndarray) - 输入样本。 + 参数： + - **inputs** (numpy.ndarray) - 输入样本。 - **返回：** - - - **numpy.ndarray** - 重建图像。 + 返回： + - **numpy.ndarray** - 重建图像。 .. py:class:: mindarmour.adv_robustness.detectors.DivergenceBasedDetector(auto_encoder, model, option='jsd', t=1, bounds=(0.0, 1.0)) @@ -78,13 +68,12 @@ mindarmour.adv_robustness.detectors 参考文献： `MagNet: a Two-Pronged Defense against Adversarial Examples, by Dongyu Meng and Hao Chen, at CCS 2017. `_。 - **参数：** - - - **auto_encoder** (Model) - 编码器模型。 - - **model** (Model) - 目标模型。 - - **option** (str) - 用于计算发散的方法。默认值：'jsd'。 - - **t** (int) - 用于克服数值问题的温度。默认值：1。 - - **bounds** (tuple) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 + 参数： + - **auto_encoder** (Model) - 编码器模型。 + - **model** (Model) - 目标模型。 + - **option** (str) - 用于计算发散的方法。默认值：'jsd'。 + - **t** (int) - 用于克服数值问题的温度。默认值：1。 + - **bounds** (tuple) - 数据的上下界。以(clip_min, clip_max)的形式出现。默认值：(0.0, 1.0)。 .. py:method:: detect_diff(inputs) @@ -92,17 +81,14 @@ mindarmour.adv_robustness.detectors 距离由JSD计算。 - **参数：** - - - **inputs** (numpy.ndarray) - 输入样本。 - - **返回：** - - - **float** - 距离。 + 参数： + - **inputs** (numpy.ndarray) - 输入样本。 - **异常：** + 返回： + - **float** - 距离。 - - **NotImplementedError** - 不支持参数 `option` 。 + 异常： + - **NotImplementedError** - 不支持参数 `option` 。 .. py:class:: mindarmour.adv_robustness.detectors.RegionBasedDetector(model, number_points=10, initial_radius=0.0, max_radius=1.0, search_step=0.01, degrade_limit=0.0, sparse=False) @@ -110,193 +96,165 @@ mindarmour.adv_robustness.detectors 参考文献： `Mitigating evasion attacks to deep neural networks via region-based classification `_。 - **参数：** - - - **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。 + 参数： + - **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(inputs) 判断输入样本是否具有对抗性。 - **参数：** - - - **inputs** (numpy.ndarray) - 待判断的可疑样本。 + 参数： + - **inputs** (numpy.ndarray) - 待判断的可疑样本。 - **返回：** - - - **list[int]** - 样本是否具有对抗性。如果res[i]=1，则索引为i的输入样本是对抗性的。 + 返回： + - **list[int]** - 样本是否具有对抗性。如果res[i]=1，则索引为i的输入样本是对抗性的。 .. py:method:: detect_diff(inputs) 返回原始预测结果和基于区域的预测结果。 - **参数：** - - - **inputs** (numpy.ndarray) - 输入样本。 + 参数： + - **inputs** (numpy.ndarray) - 输入样本。 - **返回：** - - - **numpy.ndarray** - 输入样本的原始预测结果和基于区域的预测结果。 + 返回： + - **numpy.ndarray** - 输入样本的原始预测结果和基于区域的预测结果。 .. py:method:: fit(inputs, labels=None) 训练检测器来决定最佳半径。 - **参数：** - - - **inputs** (numpy.ndarray) - 良性样本。 - - **labels** (numpy.ndarray) - 输入样本的ground truth标签。默认值：None。 - - **返回：** + 参数： + - **inputs** (numpy.ndarray) - 良性样本。 + - **labels** (numpy.ndarray) - 输入样本的ground truth标签。默认值：None。 - - **float** - 最佳半径。 + 返回： + - **float** - 最佳半径。 .. py:method:: set_radius(radius) 设置半径。 - **参数：** - - - **radius** (float) - 区域的半径。 + 参数： + - **radius** (float) - 区域的半径。 .. py:method:: transform(inputs) 为输入样本生成超级立方体。 - **参数：** - - - **inputs** (numpy.ndarray) - 输入样本。 + 参数： + - **inputs** (numpy.ndarray) - 输入样本。 - **返回：** - - - **numpy.ndarray** - 每个样本对应的超立方体。 + 返回： + - **numpy.ndarray** - 每个样本对应的超立方体。 .. 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。 + 参数： + - **model** (Model) - 目标模型。 + - **ksize** (int) - 平滑窗口大小。默认值：3。 + - **is_local_smooth** (bool) - 如果为True，则触发局部平滑。如果为False，则无局部平滑。默认值：True。 + - **metric** (str) - 距离方法。默认值：'l1'。 + - **false_positive_ratio** (float) - 良性样本上的假正率。默认值：0.05。 .. py:method:: detect(inputs) 检测输入样本是否为对抗样本。 - **参数：** + 参数： + - **inputs** (numpy.ndarray) - 待判断的可疑样本。 - - **inputs** (numpy.ndarray) - 待判断的可疑样本。 - - **返回：** - - - **list[int]** - 样本是否具有对抗性。如果res[i]=1，则索引为i的输入样本是对抗样本。 + 返回： + - **list[int]** - 样本是否具有对抗性。如果res[i]=1，则索引为i的输入样本是对抗样本。 .. py:method:: detect_diff(inputs) 返回输入样本与其平滑对应样本之间的原始距离值（在应用阈值之前）。 - **参数：** - - - **inputs** (numpy.ndarray) - 待判断的可疑样本。 + 参数： + - **inputs** (numpy.ndarray) - 待判断的可疑样本。 - **返回：** - - - **float** - 距离。 + 返回： + - **float** - 距离。 .. py:method:: fit(inputs, labels=None) 训练检测器来决定阈值。适当的阈值能够确保良性样本上的实际假正率小于给定值。 - **参数：** - - - **inputs** (numpy.ndarray) - 良性样本。 - - **labels** (numpy.ndarray) - 默认None。 + 参数： + - **inputs** (numpy.ndarray) - 良性样本。 + - **labels** (numpy.ndarray) - 默认None。 - **返回：** - - - **float** - 阈值，大于该距离的距离报告为正，即对抗性。 + 返回： + - **float** - 阈值，大于该距离的距离报告为正，即对抗性。 .. py:method:: set_threshold(threshold) 设置阈值。 - **参数：** - - - **threshold** (float) - 检测阈值。 + 参数： + - **threshold** (float) - 检测阈值。 .. py:class:: mindarmour.adv_robustness.detectors.EnsembleDetector(detectors, policy='vote') 集合检测器，通过检测器列表从输入样本中检测对抗样本。 - **参数：** - - - **detectors** (Union[tuple, list]) - 检测器方法列表。 - - **policy** (str) - 决策策略，取值可为'vote'、'all'、'any'。默认值：'vote' + 参数： + - **detectors** (Union[tuple, list]) - 检测器方法列表。 + - **policy** (str) - 决策策略，取值可为'vote'、'all'、'any'。默认值：'vote' .. py:method:: detect(inputs) 从输入样本中检测对抗性示例。 - **参数：** - - - **inputs** (numpy.ndarray) - 输入样本。 - - **返回：** + 参数： + - **inputs** (numpy.ndarray) - 输入样本。 - - **list[int]** - 样本是否具有对抗性。如果res[i]=1，则索引为i的输入样本是对抗样本。 + 返回： + - **list[int]** - 样本是否具有对抗性。如果res[i]=1，则索引为i的输入样本是对抗样本。 - **异常：** - - - **ValueError** - 不支持策略。 + 异常： + - **ValueError** - 不支持策略。 .. py:method:: detect_diff(inputs) 此方法在此类中不可用。 - **参数：** - - - **inputs** (Union[numpy.ndarray, list, tuple]) - 用于创建对抗样本。 + 参数： + - **inputs** (Union[numpy.ndarray, list, tuple]) - 用于创建对抗样本。 - **异常：** - - - **NotImplementedError** - 此函数在集成中不可用。 + 异常： + - **NotImplementedError** - 此函数在集成中不可用。 .. py:method:: fit(inputs, labels=None) 像机器学习模型一样拟合检测器。此方法在此类中不可用。 - **参数：** - - - **inputs** (numpy.ndarray) - 计算阈值的数据。 - - **labels** (numpy.ndarray) - 数据的标签。默认值：None。 + 参数： + - **inputs** (numpy.ndarray) - 计算阈值的数据。 + - **labels** (numpy.ndarray) - 数据的标签。默认值：None。 - **异常：** - - - **NotImplementedError** - 此函数在集成中不可用。 + 异常： + - **NotImplementedError** - 此函数在集成中不可用。 .. py:method:: transform(inputs) 过滤输入样本中的对抗性噪声。 此方法在此类中不可用。 - **参数：** - - - **inputs** (Union[numpy.ndarray, list, tuple]) - 用于创建对抗样本。 - - **异常：** + 参数： + - **inputs** (Union[numpy.ndarray, list, tuple]) - 用于创建对抗样本。 - - **NotImplementedError** - 此函数在集成中不可用。 + 异常： + - **NotImplementedError** - 此函数在集成中不可用。 .. py:class:: mindarmour.adv_robustness.detectors.SimilarityDetector(trans_model, max_k_neighbor=1000, chunk_size=1000, max_buffer_size=10000, tuning=False, fpr=0.001) @@ -304,18 +262,17 @@ mindarmour.adv_robustness.detectors 参考文献： `Stateful Detection of Black-Box Adversarial Attacks by Steven Chen, Nicholas Carlini, and David Wagner. at arxiv 2019 `_。 - **参数：** + 参数： + - **trans_model** (Model) - 一个MindSpore模型，将输入数据编码为低维向量。 + - **max_k_neighbor** (int) - 最近邻的最大数量。默认值：1000。 + - **chunk_size** (int) - 缓冲区大小。默认值：1000。 + - **max_buffer_size** (int) - 最大缓冲区大小。默认值：10000。 + - **tuning** (bool) - 计算k个最近邻的平均距离。 - - **trans_model** (Model) - 一个MindSpore模型，将输入数据编码为低维向量。 - - **max_k_neighbor** (int) - 最近邻的最大数量。默认值：1000。 - - **chunk_size** (int) - 缓冲区大小。默认值：1000。 - - **max_buffer_size** (int) - 最大缓冲区大小。默认值：10000。 - - **tuning** (bool) - 计算k个最近邻的平均距离。 + - 如果'tuning'为true，k= `max_k_neighbor` 。 + - 如果为False，k=1,..., `max_k_neighbor` 。默认值：False。 - - 如果'tuning'为true，k= `max_k_neighbor` 。 - - 如果为False，k=1,..., `max_k_neighbor` 。默认值：False。 - - - **fpr** (float) - 合法查询序列上的误报率。默认值：0.001 + - **fpr** (float) - 合法查询序列上的误报率。默认值：0.001 .. py:method:: clear_buffer() @@ -325,79 +282,67 @@ mindarmour.adv_robustness.detectors 处理查询以检测黑盒攻击。 - **参数：** - - - **inputs** (numpy.ndarray) - 查询序列。 + 参数： + - **inputs** (numpy.ndarray) - 查询序列。 - **异常：** - - - **ValueError** - 阈值或set_threshold方法中 `num_of_neighbors` 参数不可用。 + 异常： + - **ValueError** - 阈值或set_threshold方法中 `num_of_neighbors` 参数不可用。 .. py:method:: detect_diff(inputs) 从输入样本中检测对抗样本，如常见机器学习模型中的predict_proba函数。 - **参数：** - - - **inputs** (Union[numpy.ndarray, list, tuple]) - 用于创建对抗样本。 + 参数： + - **inputs** (Union[numpy.ndarray, list, tuple]) - 用于创建对抗样本。 - **异常：** - - - **NotImplementedError** - 此函数在 `SimilarityDetector` 类（class）中不可用。 + 异常： + - **NotImplementedError** - 此函数在 `SimilarityDetector` 类（class）中不可用。 .. py:method:: fit(inputs, labels=None) 处理输入训练数据以计算阈值。 适当的阈值应确保假正率低于给定值。 - **参数：** - - - **inputs** (numpy.ndarray) - 用于计算阈值的训练数据。 - - **labels** (numpy.ndarray) - 训练数据的标签。 - - **返回：** + 参数： + - **inputs** (numpy.ndarray) - 用于计算阈值的训练数据。 + - **labels** (numpy.ndarray) - 训练数据的标签。 - - **list[int]** - 最近邻的数量。 + 返回： + - **list[int]** - 最近邻的数量。 - - **list[float]** - 不同k的阈值。 + - **list[float]** - 不同k的阈值。 - **异常：** - - - **ValueError** - 训练数据个数小于 `max_k_neighbor`。 + 异常： + - **ValueError** - 训练数据个数小于 `max_k_neighbor`。 .. py:method:: get_detected_queries() 获取检测到的查询的索引。 - **返回：** - - - **list[int]** - 检测到的恶意查询的序列号。 + 返回： + - **list[int]** - 检测到的恶意查询的序列号。 .. py:method:: get_detection_interval() 获取相邻检测之间的间隔。 - **返回：** - - - **list[int]** - 相邻检测之间的查询数。 + 返回： + - **list[int]** - 相邻检测之间的查询数。 .. py:method:: set_threshold(num_of_neighbors, threshold) 设置参数num_of_neighbors和threshold。 - **参数：** - - - **num_of_neighbors** (int) - 最近邻的数量。 - - **threshold** (float) - 检测阈值。 + 参数： + - **num_of_neighbors** (int) - 最近邻的数量。 + - **threshold** (float) - 检测阈值。 .. py:method:: transform(inputs) 过滤输入样本中的对抗性噪声。 - **参数：** - - - **inputs** (Union[numpy.ndarray, list, tuple]) - 用于创建对抗样本。 - - **异常：** + 参数： + - **inputs** (Union[numpy.ndarray, list, tuple]) - 用于创建对抗样本。 - - **NotImplementedError** - 此函数在 `SimilarityDetector` 类（class）中不可用。 + 异常： + - **NotImplementedError** - 此函数在 `SimilarityDetector` 类（class）中不可用。 diff --git a/docs/api/api_python/mindarmour.adv_robustness.evaluations.rst b/docs/api/api_python/mindarmour.adv_robustness.evaluations.rst index 9bacbe8..9508c51 100644 --- a/docs/api/api_python/mindarmour.adv_robustness.evaluations.rst +++ b/docs/api/api_python/mindarmour.adv_robustness.evaluations.rst @@ -7,64 +7,57 @@ mindarmour.adv_robustness.evaluations 攻击方法的评估指标。 - **参数：** + 参数： + - **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。 - - **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。 + 异常： + - **ValueError** - 如果 `targeted` 为True时， `target_label` 为None。 .. py:method:: avg_conf_adv_class() 计算对抗类的平均置信度（ACAC）。 - **返回：** - - - **float** - 范围在（0,1）之间。值越高，攻击就越成功。 + 返回： + - **float** - 范围在（0,1）之间。值越高，攻击就越成功。 .. py:method:: avg_conf_true_class() 计算真类的平均置信度（ACTC）。 - **返回：** - - - **float** - 范围在（0,1）之间。值越低，攻击就越成功。 + 返回： + - **float** - 范围在（0,1）之间。值越低，攻击就越成功。 .. py:method:: avg_lp_distance() 计算平均lp距离（lp-dist）。 - **返回：** - - - **float** - 返回所有成功对抗样本的平均'l0'、'l2'或'linf'距离，返回值包括以下情况： + 返回： + - **float** - 返回所有成功对抗样本的平均'l0'、'l2'或'linf'距离，返回值包括以下情况： - - 如果返回值 :math:`>=` 0，则为平均lp距离。值越低，攻击就越成功。 - - 如果返回值为-1，则没有成功的对抗样本。 + - 如果返回值 :math:`>=` 0，则为平均lp距离。值越低，攻击就越成功。 + - 如果返回值为-1，则没有成功的对抗样本。 .. py:method:: avg_ssim() 计算平均结构相似性（ASS）。 - **返回：** - - - **float** - 平均结构相似性。 + 返回： + - **float** - 平均结构相似性。 - - 如果返回值在（0,1）之间，则值越高，攻击越成功。 - - 如果返回值为-1，则没有成功的对抗样本。 + - 如果返回值在（0,1）之间，则值越高，攻击越成功。 + - 如果返回值为-1，则没有成功的对抗样本。 .. py:method:: mis_classification_rate() 计算错误分类率（MR）。 - **返回：** - - - **float** - 范围在（0,1）之间。值越高，攻击就越成功。 + 返回： + - **float** - 范围在（0,1）之间。值越高，攻击就越成功。 .. py:method:: nte() @@ -72,123 +65,109 @@ mindarmour.adv_robustness.evaluations 参考文献：`Towards Imperceptible and Robust Adversarial Example Attacks against Neural Networks `_。 - **返回：** - - - **float** - 范围在（0,1）之间。值越高，攻击就越成功。 + 返回： + - **float** - 范围在（0,1）之间。值越高，攻击就越成功。 .. 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) - 攻击预算，最大查询数。 + 参数： + - **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:: asv() 计算攻击成功率方差（ASV）。 - **返回：** - - - **float** - 值越低，防守就越强。如果num_adv_samples=0，则返回-1。 + 返回： + - **float** - 值越低，防守就越强。如果num_adv_samples=0，则返回-1。 .. py:method:: fpr() 计算基于查询的检测器的假正率（FPR）。 - **返回：** - - - **float** - 值越低，防御的可用性越高。如果num_adv_samples=0，则返回-1。 + 返回： + - **float** - 值越低，防御的可用性越高。如果num_adv_samples=0，则返回-1。 .. py:method:: qcv() 计算查询计数方差（QCV）。 - **返回：** - - - **float** - 值越高，防守就越强。如果num_adv_samples=0，则返回-1。 + 返回： + - **float** - 值越高，防守就越强。如果num_adv_samples=0，则返回-1。 .. py:method:: qrv() 计算良性查询响应时间方差（QRV）。 - **返回：** - - - **float** - 值越低，防御的可用性越高。如果num_adv_samples=0，则返回-1。 + 返回： + - **float** - 值越低，防御的可用性越高。如果num_adv_samples=0，则返回-1。 .. 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的一维数组。 + 参数： + - **raw_preds** (numpy.ndarray) - 原始模型上某些样本的预测结果。 + - **def_preds** (numpy.ndarray) - 防御模型上某些样本的预测结果。 + - **true_labels** (numpy.ndarray) - 样本的ground-truth标签，一个大小为ground-truth的一维数组。 .. py:method:: cav() 计算分类精度方差（CAV）。 - **返回：** - - - **float** - 值越高，防守就越成功。 + 返回： + - **float** - 值越高，防守就越成功。 .. py:method:: ccv() 计算分类置信度方差（CCV）。 - **返回：** - - - **float** - 值越低，防守就越成功。如果返回值== -1，则说明样本数量为0。 + 返回： + - **float** - 值越低，防守就越成功。如果返回值== -1，则说明样本数量为0。 .. py:method:: cos() 参考文献：`Calculate classification output stability (COS) `_。 - **返回：** - - - **float** - 如果返回值>=0，则是有效的防御。值越低，防守越成功。如果返回值== -1, 则说明样本数量为0。 + 返回： + - **float** - 如果返回值>=0，则是有效的防御。值越低，防守越成功。如果返回值== -1, 则说明样本数量为0。 .. py:method:: crr() 计算分类校正率（CRR）。 - **返回：** - - - **float** - 值越高，防守就越成功。 + 返回： + - **float** - 值越高，防守就越成功。 .. py:method:: csr() 计算分类牺牲比（CSR），越低越好。 - **返回：** - - - **float** - 值越低，防守就越成功。 + 返回： + - **float** - 值越低，防守就越成功。 .. py:class:: mindarmour.adv_robustness.evaluations.RadarMetric(metrics_name, metrics_data, labels, title, scale='hide') 雷达图，通过多个指标显示模型的鲁棒性。 - **参数：** - - - **metrics_name** (Union[tuple, list]) - 要显示的度量名称数组。每组值对应一条雷达曲线。 - - **metrics_data** (numpy.ndarray) - 多个雷达曲线的每个度量的（归一化）值，如[[0.5, 0.8, ...], [0.2,0.6,...], ...]。 - - **labels** (Union[tuple, list]) - 所有雷达曲线的图例。 - - **title** (str) - 图表的标题。 - - **scale** (str) - 用于调整轴刻度的标量，如'hide'、'norm'、'sparse'、'dense'。默认值：'hide'。 - - **异常：** + 参数： + - **metrics_name** (Union[tuple, list]) - 要显示的度量名称数组。每组值对应一条雷达曲线。 + - **metrics_data** (numpy.ndarray) - 多个雷达曲线的每个度量的（归一化）值，如[[0.5, 0.8, ...], [0.2,0.6,...], ...]。 + - **labels** (Union[tuple, list]) - 所有雷达曲线的图例。 + - **title** (str) - 图表的标题。 + - **scale** (str) - 用于调整轴刻度的标量，如'hide'、'norm'、'sparse'、'dense'。默认值：'hide'。 - - **ValueError** - `scale` 值不在['hide', 'norm', 'sparse', 'dense']中。 + 异常： + - **ValueError** - `scale` 值不在['hide', 'norm', 'sparse', 'dense']中。 .. py:method:: show() diff --git a/docs/api/api_python/mindarmour.fuzz_testing.rst b/docs/api/api_python/mindarmour.fuzz_testing.rst index 7870beb..d7f2236 100644 --- a/docs/api/api_python/mindarmour.fuzz_testing.rst +++ b/docs/api/api_python/mindarmour.fuzz_testing.rst @@ -9,58 +9,54 @@ mindarmour.fuzz_testing 参考文献：`DeepHunter: A Coverage-Guided Fuzz Testing Framework for Deep Neural Networks `_。 - **参数：** - - - **target_model** (Model) - 目标模糊模型。 + 参数： + - **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** - `initial_seeds` 中的种子未包含两个元素。 + 参数： + - **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** - `initial_seeds` 中的种子未包含两个元素。 .. py:class:: mindarmour.fuzz_testing.CoverageMetrics(model, incremental=False, batch_size=32) @@ -70,23 +66,20 @@ mindarmour.fuzz_testing 参考文献： `DeepGauge: Multi-Granularity Testing Criteria for Deep Learning Systems `_。 - **参数：** - - - **model** (Model) - 被测模型。 - - **incremental** (bool) - 指标将以增量方式计算。默认值：False。 - - **batch_size** (int) - 模糊测试批次中的样本数。默认值：32。 + 参数： + - **model** (Model) - 被测模型。 + - **incremental** (bool) - 指标将以增量方式计算。默认值：False。 + - **batch_size** (int) - 模糊测试批次中的样本数。默认值：32。 .. py:method:: get_metrics(dataset) 计算给定数据集的覆盖率指标。 - **参数：** - - - **dataset** (numpy.ndarray) - 用于计算覆盖指标的数据集。 + 参数： + - **dataset** (numpy.ndarray) - 用于计算覆盖指标的数据集。 - **异常：** - - - **NotImplementedError** - 抽象方法。 + 异常： + - **NotImplementedError** - 抽象方法。 .. py:class:: mindarmour.fuzz_testing.NeuronCoverage(model, threshold=0.1, incremental=False, batch_size=32) @@ -94,114 +87,99 @@ mindarmour.fuzz_testing 神经元覆盖率等于网络中激活的神经元占总神经元的比例。 - **参数：** - - - **model** (Model) - 被测模型。 - - **threshold** (float) - 用于确定神经元是否激活的阈值。默认值：0.1。 - - **incremental** (bool) - 指标将以增量方式计算。默认值：False。 - - **batch_size** (int) - 模糊测试批次中的样本数。默认值：32。 + 参数： + - **model** (Model) - 被测模型。 + - **threshold** (float) - 用于确定神经元是否激活的阈值。默认值：0.1。 + - **incremental** (bool) - 指标将以增量方式计算。默认值：False。 + - **batch_size** (int) - 模糊测试批次中的样本数。默认值：32。 .. py:method:: get_metrics(dataset) 获取神经元覆盖率的指标：激活的神经元占网络中神经元总数的比例。 - **参数：** + 参数： + - **dataset** (numpy.ndarray) - 用于计算覆盖率指标的数据集。 - - **dataset** (numpy.ndarray) - 用于计算覆盖率指标的数据集。 - - **返回：** - - - **float** - 'neuron coverage'的指标。 + 返回： + - **float** - 'neuron coverage'的指标。 .. py:class:: mindarmour.fuzz_testing.TopKNeuronCoverage(model, top_k=3, incremental=False, batch_size=32) 计算前k个激活神经元的覆盖率。当隐藏层神经元的输出值在最大的 `top_k` 范围内，神经元就会被激活。`top_k` 神经元覆盖率等于网络中激活神经元占总神经元的比例。 - **参数：** - - - **model** (Model) - 被测模型。 - - **top_k** (int) - 当隐藏层神经元的输出值在最大的 `top_k` 范围内，神经元就会被激活。默认值：3。 - - **incremental** (bool) - 指标将以增量方式计算。默认值：False。 - - **batch_size** (int) - 模糊测试批次中的样本数。默认值：32。 + 参数： + - **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) - 用于计算覆盖率指标的数据集。 - - **返回：** + 参数： + - **dataset** (numpy.ndarray) - 用于计算覆盖率指标的数据集。 - - **float** - 'top k neuron coverage'的指标。 + 返回： + - **float** - 'top k neuron coverage'的指标。 .. py:class:: mindarmour.fuzz_testing.NeuronBoundsCoverage(model, train_dataset, incremental=False, batch_size=32) 获取'neuron boundary coverage'的指标 :math:`NBC = (|UpperCornerNeuron| + |LowerCornerNeuron|)/(2*|N|)` ，其中 :math:`|N|` 是神经元的数量，NBC是指测试数据集中神经元输出值超过训练数据集中相应神经元输出值的上下界的神经元比例。 - **参数：** - - - **model** (Model) - 等待测试的预训练模型。 - - **train_dataset** (numpy.ndarray) - 用于确定神经元输出边界的训练数据集。 - - **incremental** (bool) - 指标将以增量方式计算。默认值：False。 - - **batch_size** (int) - 模糊测试批次中的样本数。默认值：32。 + 参数： + - **model** (Model) - 等待测试的预训练模型。 + - **train_dataset** (numpy.ndarray) - 用于确定神经元输出边界的训练数据集。 + - **incremental** (bool) - 指标将以增量方式计算。默认值：False。 + - **batch_size** (int) - 模糊测试批次中的样本数。默认值：32。 .. py:method:: get_metrics(dataset) 获取'neuron boundary coverage'的指标。 - **参数：** - - - **dataset** (numpy.ndarray) - 用于计算覆盖指标的数据集。 - - **返回：** + 参数： + - **dataset** (numpy.ndarray) - 用于计算覆盖指标的数据集。 - - **float** - 'neuron boundary coverage'的指标。 + 返回： + - **float** - 'neuron boundary 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。 + 参数： + - **model** (Model) - 等待测试的预训练模型。 + - **train_dataset** (numpy.ndarray) - 用于确定神经元输出边界的训练数据集。 + - **incremental** (bool) - 指标将以增量方式计算。默认值：False。 + - **batch_size** (int) - 模糊测试批次中的样本数。默认值：32。 .. py:method:: get_metrics(dataset) 获取超激活神经元覆盖率（'super neuron activation coverage'）的指标。 - **参数：** - - - **dataset** (numpy.ndarray) - 用于计算覆盖指标的数据集。 + 参数： + - **dataset** (numpy.ndarray) - 用于计算覆盖指标的数据集。 - **返回：** - - - **float** - 超激活神经元覆盖率（'super neuron activation coverage'）的指标 + 返回： + - **float** - 超激活神经元覆盖率（'super neuron activation coverage'）的指标 .. py:class:: mindarmour.fuzz_testing.KMultisectionNeuronCoverage(model, train_dataset, segmented_num=100, incremental=False, batch_size=32) 获取K分神经元覆盖率的指标。KMNC度量测试集神经元输出落在训练集输出范围k等分间隔上的比例。 - **参数：** - - - **model** (Model) - 等待测试的预训练模型。 - - **train_dataset** (numpy.ndarray) - 用于确定神经元输出边界的训练数据集。 - - **segmented_num** (int) - 神经元输出间隔的分段部分数量。默认值：100。 - - **incremental** (bool) - 指标将以增量方式计算。默认值：False。 - - **batch_size** (int) - 模糊测试批次中的样本数。默认值：32。 + 参数： + - **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) - 用于计算覆盖指标的数据集。 - - **返回：** + 参数： + - **dataset** (numpy.ndarray) - 用于计算覆盖指标的数据集。 - - **float** - 'k-multisection neuron coverage'的指标。 + 返回： + - **float** - 'k-multisection neuron coverage'的指标。 diff --git a/docs/api/api_python/mindarmour.privacy.diff_privacy.rst b/docs/api/api_python/mindarmour.privacy.diff_privacy.rst index 2ab924a..e537831 100644 --- a/docs/api/api_python/mindarmour.privacy.diff_privacy.rst +++ b/docs/api/api_python/mindarmour.privacy.diff_privacy.rst @@ -7,49 +7,43 @@ mindarmour.privacy.diff_privacy 基于 :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。 + 参数： + - **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) - 梯度。 - - **返回：** + 参数： + - **gradients** (Tensor) - 梯度。 - - **Tensor** - 生成的shape与给定梯度相同的噪声。 + 返回： + - **Tensor** - 生成的shape与给定梯度相同的噪声。 .. py:class:: mindarmour.privacy.diff_privacy.NoiseAdaGaussianRandom(norm_bound=1.0, initial_noise_multiplier=1.0, seed=0, noise_decay_rate=6e-6, 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'。 + 参数： + - **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) - 梯度。 + 参数： + - **gradients** (Tensor) - 梯度。 - **返回：** - - - **Tensor** - 生成的shape与给定梯度相同的噪声。 + 返回： + - **Tensor** - 生成的shape与给定梯度相同的噪声。 .. 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) @@ -60,30 +54,26 @@ mindarmour.privacy.diff_privacy 其中，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。 - - **返回：** + 参数： + - **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** - 更新后的梯度裁剪阈值。 + 返回： + - **Tensor** - 更新后的梯度裁剪阈值。 .. py:method:: construct(empirical_fraction, norm_bound) 更新 `norm_bound` 的值。 - **参数：** + 参数： + - **empirical_fraction** (Tensor) - 梯度裁剪的经验分位数,最大值不超过 `target_unclipped_quantile` 。 + - **norm_bound** (Tensor) - 梯度的l2范数的裁剪范围。 - - **empirical_fraction** (Tensor) - 梯度裁剪的经验分位数,最大值不超过 `target_unclipped_quantile` 。 - - **norm_bound** (Tensor) - 梯度的l2范数的裁剪范围。 - - **返回：** - - - **Tensor** - 生成的shape与给定梯度相同的噪声。 + 返回： + - **Tensor** - 生成的shape与给定梯度相同的噪声。 .. py:class:: mindarmour.privacy.diff_privacy.NoiseMechanismsFactory @@ -93,22 +83,19 @@ mindarmour.privacy.diff_privacy .. py:method:: create(mech_name, norm_bound=1.0, initial_noise_multiplier=1.0, seed=0, noise_decay_rate=6e-6, 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。 - - **异常：** + 参数： + - **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']中。 + 异常： + - **NameError** - `mech_name` 必须在['Gaussian', 'AdaGaussian']中。 - **返回：** - - - **Mechanisms** - 产生的噪声类别机制。 + 返回： + - **Mechanisms** - 产生的噪声类别机制。 .. py:class:: mindarmour.privacy.diff_privacy.ClipMechanismsFactory @@ -118,22 +105,19 @@ mindarmour.privacy.diff_privacy .. py:method:: 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。 - - **异常：** + 参数： + - **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']中。 + 异常： + - **NameError** - `mech_name` 必须在['Gaussian']中。 - **返回：** - - - **Mechanisms** - 产生的噪声类别机制。 + 返回： + - **Mechanisms** - 产生的噪声类别机制。 .. py:class:: mindarmour.privacy.diff_privacy.PrivacyMonitorFactory @@ -145,18 +129,16 @@ mindarmour.privacy.diff_privacy 创建隐私预算监测类。 - **参数：** - - - **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]) - 用于创建隐私监视器的关键字参数。 + 参数： + - **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** - 隐私监视器。 + 返回： + - **Callback** - 隐私监视器。 .. py:class:: mindarmour.privacy.diff_privacy.RDPMonitor(num_samples, batch_size, initial_noise_multiplier=1.5, max_eps=10.0, target_delta=1e-3, max_delta=None, target_eps=None, orders=None, noise_decay_mode='Time', noise_decay_rate=6e-4, per_print_times=50, dataset_sink_mode=False) @@ -169,36 +151,33 @@ mindarmour.privacy.diff_privacy 参考文献： `Rényi Differential Privacy of the Sampled Gaussian Mechanism `_。 - **参数：** - - - **num_samples** (int) - 训练数据集中的样本总数。 - - **batch_size** (int) - 训练时批处理中的样本数。 - - **initial_noise_multiplier** (Union[float, int]) - 高斯噪声标准偏差除以norm_bound的比率，将用于计算隐私预算。默认值：1.5。 - - **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。 + 参数： + - **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:: max_epoch_suggest() 估计最大训练epoch，以满足预定义的隐私预算。 - **返回：** - - - **int** - 建议的最大训练epoch。 + 返回： + - **int** - 建议的最大训练epoch。 .. py:method:: step_end(run_context) 在每个训练步骤后计算隐私预算。 - **参数：** - - - **run_context** (RunContext) - 包含模型的一些信息。 + 参数： + - **run_context** (RunContext) - 包含模型的一些信息。 .. py:class:: mindarmour.privacy.diff_privacy.ZCDPMonitor(num_samples, batch_size, initial_noise_multiplier=1.5, max_eps=10.0, target_delta=1e-3, noise_decay_mode='Time', noise_decay_rate=6e-4, per_print_times=50, dataset_sink_mode=False) @@ -213,66 +192,58 @@ mindarmour.privacy.diff_privacy 参考文献：`Concentrated Differentially Private Gradient Descent with Adaptive per-Iteration Privacy Budget `_。 - **参数：** - - - **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。 + 参数： + - **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:: max_epoch_suggest() 估计最大训练epoch，以满足预定义的隐私预算。 - **返回：** - - - **int** - 建议的最大训练epoch。 + 返回： + - **int** - 建议的最大训练epoch。 .. py:method:: step_end(run_context) 在每个训练步骤后计算隐私预算。 - **参数：** - - - **run_context** (RunContext) - 包含模型的一些信息。 + 参数： + - **run_context** (RunContext) - 包含模型的一些信息。 .. py:class:: mindarmour.privacy.diff_privacy.DPOptimizerClassFactory(micro_batches=2) 优化器的工厂类。 - **参数：** + 参数： + - **micro_batches** (int) - 从原始批次拆分的小批次中的样本数量。默认值：2。 - - **micro_batches** (int) - 从原始批次拆分的小批次中的样本数量。默认值：2。 - - **返回：** - - - **Optimizer** - 优化器类。 + 返回： + - **Optimizer** - 优化器类。 .. py:method:: create(policy) 创建DP优化器。策略可以是'sgd'、'momentum'、'adam'。 - **参数：** - - - **policy** (str) - 选择原始优化器类型。 + 参数： + - **policy** (str) - 选择原始优化器类型。 - **返回：** - - - **Optimizer** - 一个带有差分加噪的优化器。 + 返回： + - **Optimizer** - 一个带有差分加噪的优化器。 .. py:method:: set_mechanisms(policy, *args, **kwargs) 获取噪音机制对象。策略可以是'Gaussian'或'AdaGaussian'。候选的args和kwargs可以在mechanisms.py 的 :class:`NoiseMechanismsFactory` 类中看到。 - **参数：** - - - **policy** (str) - 选择机制类型。 + 参数： + - **policy** (str) - 选择机制类型。 .. py:class:: mindarmour.privacy.diff_privacy.DPModel(micro_batches=2, norm_bound=1.0, noise_mech=None, clip_mech=None, optimizer=nn.Momentum, **kwargs) @@ -282,17 +253,15 @@ mindarmour.privacy.diff_privacy 详情请查看： `教程 `_。 - **参数：** - - - **micro_batches** (int) - 从原始批次拆分的小批次数。默认值：2。 - - **norm_bound** (float) - 用于裁剪范围，如果设置为1，将返回原始数据。默认值：1.0。 - - **noise_mech** (Mechanisms) - 用于生成不同类型的噪音。默认值：None。 - - **clip_mech** (Mechanisms) - 用于更新自适应剪裁。默认值：None。 - - **optimizer** (Cell) - 用于更新差分隐私训练过程中的模型权重值。默认值：nn.Momentum。 - - **异常：** - - - **ValueError** - optimizer值为None。 - - **ValueError** - optimizer不是DPOptimizer，且noise_mech为None。 - - **ValueError** - optimizer是DPOptimizer，且noise_mech非None。 - - **ValueError** - noise_mech或DPOptimizer的mech方法是自适应的，而clip_mech不是None。 + 参数： + - **micro_batches** (int) - 从原始批次拆分的小批次数。默认值：2。 + - **norm_bound** (float) - 用于裁剪范围，如果设置为1，将返回原始数据。默认值：1.0。 + - **noise_mech** (Mechanisms) - 用于生成不同类型的噪音。默认值：None。 + - **clip_mech** (Mechanisms) - 用于更新自适应剪裁。默认值：None。 + - **optimizer** (Cell) - 用于更新差分隐私训练过程中的模型权重值。默认值：nn.Momentum。 + + 异常： + - **ValueError** - optimizer值为None。 + - **ValueError** - optimizer不是DPOptimizer，且noise_mech为None。 + - **ValueError** - optimizer是DPOptimizer，且noise_mech非None。 + - **ValueError** - noise_mech或DPOptimizer的mech方法是自适应的，而clip_mech不是None。 diff --git a/docs/api/api_python/mindarmour.privacy.evaluation.rst b/docs/api/api_python/mindarmour.privacy.evaluation.rst index 76600bc..36b8c60 100644 --- a/docs/api/api_python/mindarmour.privacy.evaluation.rst +++ b/docs/api/api_python/mindarmour.privacy.evaluation.rst @@ -11,58 +11,52 @@ mindarmour.privacy.evaluation 参考文献：`Reza Shokri, Marco Stronati, Congzheng Song, Vitaly Shmatikov. Membership Inference Attacks against Machine Learning Models. 2017. `_。 - **参数：** + 参数： + - **model** (Model) - 目标模型。 + - **n_jobs** (int) - 并行运行的任务数量。-1表示使用所有处理器，否则n_jobs的值必须为正整数。 - - **model** (Model) - 目标模型。 - - **n_jobs** (int) - 并行运行的任务数量。-1表示使用所有处理器，否则n_jobs的值必须为正整数。 - - **异常：** - - - **TypeError** - 模型的类型不是 :class:`mindspore.Model` 。 - - **TypeError** - `n_jobs` 的类型不是int。 - - **ValueError** - `n_jobs` 的值既不是-1，也不是正整数。 + 异常： + - **TypeError** - 模型的类型不是 :class:`mindspore.Model` 。 + - **TypeError** - `n_jobs` 的类型不是int。 + - **ValueError** - `n_jobs` 的值既不是-1，也不是正整数。 .. py:method:: eval(dataset_train, dataset_test, metrics) 评估目标模型的隐私泄露程度。 评估指标应由metrics规定。 - **参数：** - - - **dataset_train** (minspore.dataset) - 目标模型的训练数据集。 - - **dataset_test** (minspore.dataset) - 目标模型的测试数据集。 - - **metrics** (Union[list, tuple]) - 评估指标。指标的值必须在["precision", "accuracy", "recall"]中。默认值：["precision"]。 - - **返回：** + 参数： + - **dataset_train** (minspore.dataset) - 目标模型的训练数据集。 + - **dataset_test** (minspore.dataset) - 目标模型的测试数据集。 + - **metrics** (Union[list, tuple]) - 评估指标。指标的值必须在["precision", "accuracy", "recall"]中。默认值：["precision"]。 - - **list** - 每个元素都包含攻击模型的评估指标。 + 返回： + - **list** - 每个元素都包含攻击模型的评估指标。 .. py:method:: train(dataset_train, dataset_test, attack_config) 根据配置，使用输入数据集训练攻击模型。 - **参数：** - - - **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，每个方法的参数必须在可变参数的范围内。参数实现的提示可在下面找到： + 参数： + - **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 `_ - - `RF `_ - - `MLP `_ + - 支持的方法有knn、lr、mlp和rf，每个方法的参数必须在可变参数的范围内。参数实现的提示可在下面找到： - **异常：** + - `KNN `_ + - `LR `_ + - `RF `_ + - `MLP `_ - - **KeyError** - `attack_config` 中的配置没有键{"method", "params"}。 - - **NameError** - `attack_config` 中的方法（不区分大小写）不在["lr", "knn", "rf", "mlp"]中。 + 异常： + - **KeyError** - `attack_config` 中的配置没有键{"method", "params"}。 + - **NameError** - `attack_config` 中的方法（不区分大小写）不在["lr", "knn", "rf", "mlp"]中。 .. py:class:: mindarmour.privacy.evaluation.ImageInversionAttack(network, input_shape, input_bound, loss_weights=(1, 0.2, 5)) @@ -70,51 +64,44 @@ mindarmour.privacy.evaluation 参考文献：`Aravindh Mahendran, Andrea Vedaldi. Understanding Deep Image Representations by Inverting Them. 2014. `_。 - **参数：** + 参数： + - **network** (Cell) - 网络，用于推断图像的深层特征。 + - **input_shape** (tuple) - 单个网络输入的数据形状，应与给定网络一致。形状的格式应为(channel, image_width, image_height)。 + - **input_bound** (Union[tuple, list]) - 原始图像的像素范围，应该像[minimum_pixel, maximum_pixel]或(minimum_pixel, maximum_pixel)。 + - **loss_weights** (Union[list, tuple]) - InversionLoss中三个子损失的权重，可以调整以获得更好的结果。默认值：(1, 0.2, 5)。 - - **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` 的值有非正整数。 - - **ValueError** - `loss_weights` 的值有非正数。 + 异常： + - **TypeError** - 网络类型不是Cell。 + - **ValueError** - `input_shape` 的值有非正整数。 + - **ValueError** - `loss_weights` 的值有非正数。 .. py:method:: evaluate(original_images, inversion_images, labels=None, new_network=None) 通过三个指标评估还原图像的质量：原始图像和还原图像之间的平均L2距离和SSIM值，以及新模型对还原图像的推理结果在真实标签上的置信度平均值。 - **参数：** - - - **original_images** (numpy.ndarray) - 原始图像，其形状应为(img_num, channels, img_width, img_height)。 - - **inversion_images** (numpy.ndarray) - 还原图像，其形状应为(img_num, channels, img_width, img_height)。 - - **labels** (numpy.ndarray) - 原始图像的ground truth标签。默认值：None。 - - **new_network** (Cell) - 其结构包含self._network中所有网络，但加载了不同的模型文件。默认值：None。 - - **返回：** + 参数： + - **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中所有网络，但加载了不同的模型文件。默认值：None。 - - **float** - l2距离。 - - **float** - 平均ssim值。 - - **Union[float, None]** - 平均置信度。如果 `labels` 或 `new_network` 为None，则该值为None。 + 返回： + - **float** - l2距离。 + - **float** - 平均ssim值。 + - **Union[float, None]** - 平均置信度。如果 `labels` 或 `new_network` 为None，则该值为None。 .. py:method:: generate(target_features, iters=100) 根据 `target_features` 重建图像。 - **参数：** - - - **target_features** (numpy.ndarray) - 原始图像的深度表示。 `target_features` 的第一个维度应该是img_num。需要注意的是，如果img_num等于1，则 `target_features` 的形状应该是(1, dim2, dim3, ...)。 - - **iters** (int) - 逆向攻击的迭代次数，应为正整数。默认值：100。 - - **返回：** - - - **numpy.ndarray** - 重建图像，预计与原始图像相似。 + 参数： + - **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` 的值都不是正整数. + 异常： + - **TypeError** - target_features的类型不是numpy.ndarray。 + - **ValueError** - `iters` 的值都不是正整数. diff --git a/docs/api/api_python/mindarmour.privacy.sup_privacy.rst b/docs/api/api_python/mindarmour.privacy.sup_privacy.rst index c6f67b1..25cc3f4 100644 --- a/docs/api/api_python/mindarmour.privacy.sup_privacy.rst +++ b/docs/api/api_python/mindarmour.privacy.sup_privacy.rst @@ -10,18 +10,16 @@ mindarmour.privacy.sup_privacy 详情请查看： `应用抑制隐私机制保护用户隐私 `_。 - **参数：** - - - **model** (SuppressModel) - SuppressModel 实例。 - - **suppress_ctrl** (SuppressCtrl) - SuppressCtrl 实例。 + 参数： + - **model** (SuppressModel) - SuppressModel 实例。 + - **suppress_ctrl** (SuppressCtrl) - SuppressCtrl 实例。 .. py:method:: step_end(run_context) 更新用于抑制模型实例的掩码矩阵张量。 - **参数：** - - - **run_context** (RunContext) - 包含模型的一些信息。 + 参数： + - **run_context** (RunContext) - 包含模型的一些信息。 .. py:class:: mindarmour.privacy.sup_privacy.SuppressModel(network, loss_fn, optimizer, **kwargs) @@ -29,20 +27,18 @@ mindarmour.privacy.sup_privacy 有关详细信息，请查看： `应用抑制隐私机制保护用户隐私 `_。 - **参数：** - - - **network** (Cell) - 要训练的神经网络模型。 - - **loss_fn** (Cell) - 优化器的损失函数。 - - **optimizer** (Optimizer) - 优化器实例。 - - **kwargs** - 创建抑制模型时使用的关键字参数。 + 参数： + - **network** (Cell) - 要训练的神经网络模型。 + - **loss_fn** (Cell) - 优化器的损失函数。 + - **optimizer** (Optimizer) - 优化器实例。 + - **kwargs** - 创建抑制模型时使用的关键字参数。 .. py:method:: link_suppress_ctrl(suppress_pri_ctrl) SuppressCtrl实例关联到SuppressModel实例。 - **参数：** - - - **suppress_pri_ctrl** (SuppressCtrl) - SuppressCtrl实例。 + 参数： + - **suppress_pri_ctrl** (SuppressCtrl) - SuppressCtrl实例。 .. py:class:: mindarmour.privacy.sup_privacy.SuppressPrivacyFactory @@ -52,22 +48,20 @@ mindarmour.privacy.sup_privacy .. 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.90, sparse_start=0.0) - **参数：** - - - **networks** (Cell) - 要训练的神经网络模型。此网络参数应与SuppressModel()的'network'参数相同。 - - **mask_layers** (list) - 需要抑制的训练网络层的描述。 - - **policy** (str) - 抑制隐私训练的训练策略。默认值："local_train"，表示本地训练。 - - **end_epoch** (int) - 最后一次抑制操作对应的epoch序号，0`_。 - **参数：** - - - **networks** (Cell) - 要训练的神经网络模型。 - - **mask_layers** (list) - 需要抑制的层的描述。 - - **end_epoch** (int) - 最后一次抑制操作对应的epoch序号。 - - **batch_num** (int) - 一个epoch中的batch数量。 - - **start_epoch** (int) - 第一个抑制操作对应的epoch序号。 - - **mask_times** (int) - 抑制操作的数量。 - - **lr** (Union[float, int]) - 学习率。 - - **sparse_end** (float) - 要到达的稀疏性。 - - **sparse_start** (Union[float, int]) - 要启动的稀疏性。 + 参数： + - **networks** (Cell) - 要训练的神经网络模型。 + - **mask_layers** (list) - 需要抑制的层的描述。 + - **end_epoch** (int) - 最后一次抑制操作对应的epoch序号。 + - **batch_num** (int) - 一个epoch中的batch数量。 + - **start_epoch** (int) - 第一个抑制操作对应的epoch序号。 + - **mask_times** (int) - 抑制操作的数量。 + - **lr** (Union[float, int]) - 学习率。 + - **sparse_end** (float) - 要到达的稀疏性。 + - **sparse_start** (Union[float, int]) - 要启动的稀疏性。 .. py:method:: calc_actual_sparse_for_conv(networks) 计算con1层和con2层的网络稀疏性。 - **参数：** - - - **networks** (Cell) - 要训练的神经网络模型。 + 参数： + - **networks** (Cell) - 要训练的神经网络模型。 .. py:method:: calc_actual_sparse_for_fc1(networks) 计算全连接1层的实际稀疏 - **参数：** - - - **networks** (Cell) - 要训练的神经网络模型。 + 参数： + - **networks** (Cell) - 要训练的神经网络模型。 .. py:method:: calc_actual_sparse_for_layer(networks, layer_name) 计算一个网络层的实际稀疏性 - **参数：** - - - **networks** (Cell) - 要训练的神经网络模型。 - - **layer_name** (str) - 目标层的名称。 + 参数： + - **networks** (Cell) - 要训练的神经网络模型。 + - **layer_name** (str) - 目标层的名称。 .. py:method:: calc_theoretical_sparse_for_conv() @@ -128,23 +118,21 @@ mindarmour.privacy.sup_privacy 对整个模型的用于加法运算和乘法运算的掩码数组进行更新。 - **参数：** - - - **networks** (Cell) - 训练网络。 - - **cur_step** (int) - 整个训练过程的当前epoch。 - - **target_sparse** (float) - 要到达的稀疏性。默认值：0.0。 + 参数： + - **networks** (Cell) - 训练网络。 + - **cur_step** (int) - 整个训练过程的当前epoch。 + - **target_sparse** (float) - 要到达的稀疏性。默认值：0.0。 .. 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) - 目标层的索引。 + 参数： + - **weight_array_flat** (numpy.ndarray) - 层参数权重数组。 + - **sparse_weight_thd** (float) - 绝对值小于该阈值的权重会被抑制。 + - **sparse_stop_pos** (int) - 要抑制的最大元素数。 + - **weight_abs_max** (float) - 权重的最大绝对值。 + - **layer_index** (int) - 目标层的索引。 .. py:method:: update_mask_layer_approximity(weight_array_flat, weight_array_flat_abs, actual_stop_pos, layer_index) @@ -152,38 +140,35 @@ mindarmour.privacy.sup_privacy 禁用clipping lower、clipping、adding noise操作。 - **参数：** - - - **weight_array_flat** (numpy.ndarray) - 层参数权重数组。 - - **weight_array_flat_abs** (numpy.ndarray) - 层参数权重的绝对值的数组。 - - **actual_stop_pos** (int) - 应隐藏实际参数编号。 - - **layer_index** (int) - 目标层的索引。 + 参数： + - **weight_array_flat** (numpy.ndarray) - 层参数权重数组。 + - **weight_array_flat_abs** (numpy.ndarray) - 层参数权重的绝对值的数组。 + - **actual_stop_pos** (int) - 应隐藏实际参数编号。 + - **layer_index** (int) - 目标层的索引。 .. 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的当前步骤。 + 参数： + - **cur_epoch** (int) - 整个训练过程的当前epoch。 + - **cur_step** (int) - 整个训练过程的当前步骤。 + - **cur_step_in_epoch** (int) - 当前epoch的当前步骤。 .. py:class:: mindarmour.privacy.sup_privacy.MaskLayerDes(layer_name, grad_idx, is_add_noise, is_lower_clip, min_num, upper_bound=1.20) 对抑制目标层的描述。 - **参数：** - - - **layer_name** (str) - 层名称，如下获取一个层的名称： - .. code-block:: + 参数： + - **layer_name** (str) - 层名称，如下获取一个层的名称： + .. code-block:: - for layer in networks.get_parameters(expand=True): - if layer.name == "conv": ... + for layer in networks.get_parameters(expand=True): + if layer.name == "conv": ... - - **grad_idx** (int) - 掩码层在梯度元组中的索引。可参考 `model.py `_ 中TrainOneStepCell的构造函数，在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小于（参数总数量 *　`SupperssCtrl.sparse_end` ），则min_num无效。 - - **upper_bound** (Union[float, int]) - 此层权重的最大abs值，默认值：1.20。如果参数num大于100000，则upper_bound无效。 + - **grad_idx** (int) - 掩码层在梯度元组中的索引。可参考 `model.py `_ 中TrainOneStepCell的构造函数，在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小于（参数总数量 *　`SupperssCtrl.sparse_end` ），则min_num无效。 + - **upper_bound** (Union[float, int]) - 此层权重的最大abs值，默认值：1.20。如果参数num大于100000，则upper_bound无效。 diff --git a/docs/api/api_python/mindarmour.reliability.rst b/docs/api/api_python/mindarmour.reliability.rst index ad9869b..f15aa56 100644 --- a/docs/api/api_python/mindarmour.reliability.rst +++ b/docs/api/api_python/mindarmour.reliability.rst @@ -9,34 +9,30 @@ MindArmour的可靠性方法。 详情请查看 `实现模型故障注入评估模型容错性 `_。 - **参数：** - - - **model** (Model) - 需要评估模型。 - - **fi_type** (list) - 故障注入的类型，包括'bitflips_random'（随机翻转）、'bitflips_designated'（翻转关键位）、'random'、'zeros'、'nan'、'inf'、'anti_activation'、'precision_loss'等。 - - **fi_mode** (list) - 故障注入的模式。可选值：'single_layer'，'all_layer'。 - - **fi_size** (list) - 故障注入的次数，表示需要注入多少值。 + 参数： + - **model** (Model) - 需要评估模型。 + - **fi_type** (list) - 故障注入的类型，包括'bitflips_random'（随机翻转）、'bitflips_designated'（翻转关键位）、'random'、'zeros'、'nan'、'inf'、'anti_activation'、'precision_loss'等。 + - **fi_mode** (list) - 故障注入的模式。可选值：'single_layer'，'all_layer'。 + - **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) - 评估数，这将决定批处理大小。 - - **返回：** + 参数： + - **ds_data** (np.ndarray) - 输入测试数据。评估基于这些数据。 + - **ds_label** (np.ndarray) - 数据的标签，对应于数据。 + - **iter_times** (int) - 评估数，这将决定批处理大小。 - - **list** - 故障注入的结果。 + 返回： + - **list** - 故障注入的结果。 .. py:method:: metrics() 最终结果的指标。 - **返回：** - - - **list** - 结果总结。 + 返回： + - **list** - 结果总结。 .. py:class:: mindarmour.reliability.ConceptDriftCheckTimeSeries(window_size=100, rolling_window=10, step=10, threshold_index=1.5, need_label=False) @@ -45,64 +41,56 @@ MindArmour的可靠性方法。 有关详细信息，请查看 `实现时序数据概念漂移检测应用 `_。 - **参数：** - - - **window_size** (int) - 概念窗口的大小，不小于10。如果给定输入数据， `window_size` 在[10, 1/3*len( `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。 + 参数： + - **window_size** (int) - 概念窗口的大小，不小于10。如果给定输入数据， `window_size` 在[10, 1/3*len( `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列）是一个数据序列。 - - **data** (numpy.ndarray) - 输入数据。数据的shape可以是(n,1)或(n,m)。 - 请注意，每列（m列）是一个数据序列。 - - **返回：** - - - **numpy.ndarray** - 样本序列的概念漂移分数。 - - **float** - 判断概念漂移的阈值。 - - **list** - 概念漂移的位置。 + 返回： + - **numpy.ndarray** - 样本序列的概念漂移分数。 + - **float** - 判断概念漂移的阈值。 + - **list** - 概念漂移的位置。 .. py:class:: mindarmour.reliability.OodDetector(model, ds_train) 分布外检测器的抽象类。 - **参数：** - - - **model** (Model) - 训练模型。 - - **ds_train** (numpy.ndarray) - 训练数据集。 + 参数： + - **model** (Model) - 训练模型。 + - **ds_train** (numpy.ndarray) - 训练数据集。 .. py:method:: get_optimal_threshold(label, ds_eval) 获取最佳阈值。尝试找到一个最佳阈值来检测OOD样本。最佳阈值由标记的数据集 `ds_eval` 计算。 - **参数：** - - - **label** (numpy.ndarray) - 区分图像是否为分布内或分布外的标签。 - - **ds_eval** (numpy.ndarray) - 帮助查找阈值的测试数据集。 + 参数： + - **label** (numpy.ndarray) - 区分图像是否为分布内或分布外的标签。 + - **ds_eval** (numpy.ndarray) - 帮助查找阈值的测试数据集。 - **返回：** - - - **float** - 最佳阈值。 + 返回： + - **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) - 测试数据集。 + 参数： + - **threshold** (float) - 判断ood数据的阈值。可以根据经验设置值，也可以使用函数get_optimal_threshold。 + - **ds_test** (numpy.ndarray) - 测试数据集。 - **返回：** - - - **numpy.ndarray** - 检测结果。0表示数据不是ood，1表示数据是ood。 + 返回： + - **numpy.ndarray** - 检测结果。0表示数据不是ood，1表示数据是ood。 .. py:class:: mindarmour.reliability.OodDetectorFeatureCluster(model, ds_train, n_cluster, layer) @@ -110,35 +98,30 @@ MindArmour的可靠性方法。 有关详细信息，请查看 `实现图像数据概念漂移检测应用 `_。 - **参数：** - - - **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'中命名模型层的更多详细信息。 + 参数： + - **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:: get_optimal_threshold(label, ds_eval) - **参数：** + 参数： + - **label** (numpy.ndarray) - 区分图像是否为分布内或分布外的标签。 + - **ds_eval** (numpy.ndarray) - 帮助查找阈值的测试数据集。 - - **label** (numpy.ndarray) - 区分图像是否为分布内或分布外的标签。 - - **ds_eval** (numpy.ndarray) - 帮助查找阈值的测试数据集。 - - **返回：** - - - **float** - 最佳阈值。 + 返回： + - **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) - 测试数据集。 - - **返回：** + 参数： + - **threshold** (float) - 判断ood数据的阈值。可以根据经验设置值，也可以使用函数get_optimal_threshold。 + - **ds_test** (numpy.ndarray) - 测试数据集。 - - **numpy.ndarray** - 检测结果。0表示数据不是ood，1表示数据是ood。 + 返回： + - **numpy.ndarray** - 检测结果。0表示数据不是ood，1表示数据是ood。 diff --git a/docs/api/api_python/mindarmour.rst b/docs/api/api_python/mindarmour.rst index 4b241c0..b03131c 100644 --- a/docs/api/api_python/mindarmour.rst +++ b/docs/api/api_python/mindarmour.rst @@ -13,28 +13,24 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 根据输入样本及其标签来批量生成对抗样本。 - **参数：** + 参数： + - **inputs** (Union[numpy.ndarray, tuple]) - 生成对抗样本的原始样本。 + - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。 + - **batch_size** (int) - 一个批次中的样本数。默认值：64。 - - **inputs** (Union[numpy.ndarray, tuple]) - 生成对抗样本的原始样本。 - - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。 - - **batch_size** (int) - 一个批次中的样本数。默认值：64。 - - **返回：** - - - **numpy.ndarray** - 生成的对抗样本。 + 返回： + - **numpy.ndarray** - 生成的对抗样本。 .. py:method:: generate(inputs, labels) 根据正常样本及其标签生成对抗样本。 - **参数：** - - - **inputs** (Union[numpy.ndarray, tuple]) - 生成对抗样本的原始样本。 - - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。 + 参数： + - **inputs** (Union[numpy.ndarray, tuple]) - 生成对抗样本的原始样本。 + - **labels** (Union[numpy.ndarray, tuple]) - 原始/目标标签。若每个输入有多个标签，将它包装在元组中。 - **异常：** - - - **NotImplementedError** - 此为抽象方法。 + 异常： + - **NotImplementedError** - 此为抽象方法。 .. py:class:: mindarmour.BlackModel @@ -44,27 +40,23 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 检查输入样本是否为对抗样本。 - **参数：** - - - **data** (numpy.ndarray) - 要检查的输入样本，通常是一些恶意干扰的样本。 - - **label** (numpy.ndarray) - 对于目标攻击，标签是受扰动样本的预期标签。对于无目标攻击，标签是相应未扰动样本的原始标签。 - - **is_targeted** (bool) - 对于有目标/无目标攻击，请选择True/False。 - - **返回：** + 参数： + - **data** (numpy.ndarray) - 要检查的输入样本，通常是一些恶意干扰的样本。 + - **label** (numpy.ndarray) - 对于目标攻击，标签是受扰动样本的预期标签。对于无目标攻击，标签是相应未扰动样本的原始标签。 + - **is_targeted** (bool) - 对于有目标/无目标攻击，请选择True/False。 - - **bool** - 如果为True，则输入样本是对抗性的。如果为False，则输入样本不是对抗性的。 + 返回： + - **bool** - 如果为True，则输入样本是对抗性的。如果为False，则输入样本不是对抗性的。 .. py:method:: predict(inputs) 使用用户指定的模型进行预测。预测结果的shape应该是(m,n)，其中n表示此模型分类的类数。 - **参数：** + 参数： + - **inputs** (numpy.ndarray) - 要预测的输入样本。 - - **inputs** (numpy.ndarray) - 要预测的输入样本。 - - **异常：** - - - **NotImplementedError** - 抽象方法未实现。 + 异常： + - **NotImplementedError** - 抽象方法未实现。 .. py:class:: mindarmour.Detector @@ -74,90 +66,76 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 从输入样本中检测对抗样本。 - **参数：** - - - **inputs** (Union[numpy.ndarray, list, tuple]) - 要检测的输入样本。 + 参数： + - **inputs** (Union[numpy.ndarray, list, tuple]) - 要检测的输入样本。 - **异常：** - - - **NotImplementedError** - 抽象方法未实现。 + 异常： + - **NotImplementedError** - 抽象方法未实现。 .. py:method:: detect_diff(inputs) 计算输入样本和去噪样本之间的差值。 - **参数：** - - - **inputs** (Union[numpy.ndarray, list, tuple]) - 要检测的输入样本。 + 参数： + - **inputs** (Union[numpy.ndarray, list, tuple]) - 要检测的输入样本。 - **异常：** - - - **NotImplementedError** - 抽象方法未实现。 + 异常： + - **NotImplementedError** - 抽象方法未实现。 .. py:method:: fit(inputs, labels=None) 拟合阈值，拒绝与去噪样本差异大于阈值的对抗样本。当应用于正常样本时，阈值由假正率决定。 - **参数：** - - - **inputs** (numpy.ndarray) - 用于计算阈值的输入样本。 - - **labels** (numpy.ndarray) - 训练数据的标签。默认值：None。 - - **异常：** + 参数： + - **inputs** (numpy.ndarray) - 用于计算阈值的输入样本。 + - **labels** (numpy.ndarray) - 训练数据的标签。默认值：None。 - - **NotImplementedError** - 抽象方法未实现。 + 异常： + - **NotImplementedError** - 抽象方法未实现。 .. py:method:: transform(inputs) 过滤输入样本中的对抗性噪声。 - **参数：** - - - **inputs** (Union[numpy.ndarray, list, tuple]) - 要转换的输入样本。 - - **异常：** + 参数： + - **inputs** (Union[numpy.ndarray, list, tuple]) - 要转换的输入样本。 - - **NotImplementedError** - 抽象方法未实现。 + 异常： + - **NotImplementedError** - 抽象方法未实现。 .. py:class:: mindarmour.Defense(network) 所有防御类的抽象基类，用于防御对抗样本。 - **参数：** - - - **network** (Cell) - 要防御的MindSpore风格的深度学习模型。 + 参数： + - **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。 - - **返回：** + 参数： + - **inputs** (numpy.ndarray) - 生成对抗样本的原始样本。 + - **labels** (numpy.ndarray) - 输入样本的标签。 + - **batch_size** (int) - 一个批次中的样本数。默认值：32。 + - **epochs** (int) - epochs的数量。默认值：5。 - - **numpy.ndarray** - `batch_defense` 操作的损失。 + 返回： + - **numpy.ndarray** - `batch_defense` 操作的损失。 - **异常：** - - - **ValueError** - `batch_size` 为0。 + 异常： + - **ValueError** - `batch_size` 为0。 .. py:method:: defense(inputs, labels) 对输入进行防御操作。 - **参数：** - - - **inputs** (numpy.ndarray) - 生成对抗样本的原始样本。 - - **labels** (numpy.ndarray) - 输入样本的标签。 + 参数： + - **inputs** (numpy.ndarray) - 生成对抗样本的原始样本。 + - **labels** (numpy.ndarray) - 输入样本的标签。 - **异常：** - - - **NotImplementedError** - 抽象方法未实现。 + 异常： + - **NotImplementedError** - 抽象方法未实现。 .. py:class:: mindarmour.Fuzzer(target_model) @@ -165,57 +143,53 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 参考文献： `DeepHunter: A Coverage-Guided Fuzz Testing Framework for Deep Neural Networks `_。 - **参数：** - - - **target_model** (Model) - 目标模糊模型。 + 参数： + - **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** - 初始种子队列中的种子不是包含两个元素。 + 参数： + - **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.DPModel(micro_batches=2, norm_bound=1.0, noise_mech=None, clip_mech=None, optimizer=nn.Momentum, **kwargs) @@ -225,20 +199,18 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 详情请查看： `应用差分隐私机制保护用户隐私 `_。 - **参数：** - - - **micro_batches** (int) - 从原始批次拆分的小批次数。默认值：2。 - - **norm_bound** (float) - 用于裁剪的约束，如果设置为1，将返回原始数据。默认值：1.0。 - - **noise_mech** (Mechanisms) - 用于生成不同类型的噪音。默认值：None。 - - **clip_mech** (Mechanisms) - 用于更新自适应剪裁。默认值：None。 - - **optimizer** (Cell) - 用于更新差分隐私训练过程中的模型权重值。默认值：nn.Momentum。 + 参数： + - **micro_batches** (int) - 从原始批次拆分的小批次数。默认值：2。 + - **norm_bound** (float) - 用于裁剪的约束，如果设置为1，将返回原始数据。默认值：1.0。 + - **noise_mech** (Mechanisms) - 用于生成不同类型的噪音。默认值：None。 + - **clip_mech** (Mechanisms) - 用于更新自适应剪裁。默认值：None。 + - **optimizer** (Cell) - 用于更新差分隐私训练过程中的模型权重值。默认值：nn.Momentum。 - **异常：** - - - **ValueError** - `optimizer` 值为None。 - - **ValueError** - `optimizer` 不是DPOptimizer，且 `noise_mech` 为None。 - - **ValueError** - `optimizer` 是DPOptimizer，且 `noise_mech` 非None。 - - **ValueError** - `noise_mech` 或DPOptimizer的mech方法是自适应的，而 `clip_mech` 不是None。 + 异常： + - **ValueError** - `optimizer` 值为None。 + - **ValueError** - `optimizer` 不是DPOptimizer，且 `noise_mech` 为None。 + - **ValueError** - `optimizer` 是DPOptimizer，且 `noise_mech` 非None。 + - **ValueError** - `noise_mech` 或DPOptimizer的mech方法是自适应的，而 `clip_mech` 不是None。 .. py:class:: mindarmour.MembershipInference(model, n_jobs=-1) @@ -248,58 +220,52 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 参考文献：`Reza Shokri, Marco Stronati, Congzheng Song, Vitaly Shmatikov. Membership Inference Attacks against Machine Learning Models. 2017. `_。 - **参数：** - - - **model** (Model) - 目标模型。 - - **n_jobs** (int) - 并行运行的任务数量。-1表示使用所有处理器，否则n_jobs的值必须为正整数。 + 参数： + - **model** (Model) - 目标模型。 + - **n_jobs** (int) - 并行运行的任务数量。-1表示使用所有处理器，否则n_jobs的值必须为正整数。 - **异常：** - - - **TypeError** - 模型的类型不是Mindspore.Model。 - - **TypeError** - `n_jobs` 的类型不是int。 - - **ValueError** - `n_jobs` 的值既不是-1，也不是正整数。 + 异常： + - **TypeError** - 模型的类型不是Mindspore.Model。 + - **TypeError** - `n_jobs` 的类型不是int。 + - **ValueError** - `n_jobs` 的值既不是-1，也不是正整数。 .. py:method:: eval(dataset_train, dataset_test, metrics) 评估目标模型的不同隐私。 评估指标应由metrics规定。 - **参数：** - - - **dataset_train** (minspore.dataset) - 目标模型的训练数据集。 - - **dataset_test** (minspore.dataset) - 目标模型的测试数据集。 - - **metrics** (Union[list, tuple]) - 评估指标。指标的值必须在["precision", "accuracy", "recall"]中。默认值：["precision"]。 - - **返回：** + 参数： + - **dataset_train** (minspore.dataset) - 目标模型的训练数据集。 + - **dataset_test** (minspore.dataset) - 目标模型的测试数据集。 + - **metrics** (Union[list, tuple]) - 评估指标。指标的值必须在["precision", "accuracy", "recall"]中。默认值：["precision"]。 - - **list** - 每个元素都包含攻击模型的评估指标。 + 返回： + - **list** - 每个元素都包含攻击模型的评估指标。 .. py:method:: train(dataset_train, dataset_test, attack_config) 根据配置，使用输入数据集训练攻击模型。 - **参数：** - - - **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)}}] + 参数： + - **dataset_train** (minspore.dataset) - 目标模型的训练数据集。 + - **dataset_test** (minspore.dataset) - 目标模型的测试集。 + - **attack_config** (Union[list, tuple]) - 攻击模型的参数设置。格式为: + .. code-block:: - - 支持的方法有knn、lr、mlp和rf，每个方法的参数必须在可变参数的范围内。参数实现的提示可在下面找到： + attack_config = + [{"method": "knn", "params": {"n_neighbors": [3, 5, 7]}}, + {"method": "lr", "params": {"C": np.logspace(-4, 2, 10)}}] - - `KNN `_ - - `LR `_ - - `RF `_ - - `MLP `_ + - 支持的方法有knn、lr、mlp和rf，每个方法的参数必须在可变参数的范围内。参数实现的提示可在下面找到： - **异常：** + - `KNN `_ + - `LR `_ + - `RF `_ + - `MLP `_ - - **KeyError** - `attack_config` 中的配置没有键{"method", "params"}。 - - **NameError** - `attack_config` 中的方法（不区分大小写）不在["lr", "knn", "rf", "mlp"]中。 + 异常： + - **KeyError** - `attack_config` 中的配置没有键{"method", "params"}。 + - **NameError** - `attack_config` 中的方法（不区分大小写）不在["lr", "knn", "rf", "mlp"]中。 .. py:class:: mindarmour.ImageInversionAttack(network, input_shape, input_bound, loss_weights=(1, 0.2, 5)) @@ -307,54 +273,47 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 参考文献：`Aravindh Mahendran, Andrea Vedaldi. Understanding Deep Image Representations by Inverting Them. 2014. `_。 - **参数：** + 参数： + - **network** (Cell) - 网络，用于推断图像的深层特征。 + - **input_shape** (tuple) - 单个网络输入的数据形状，应与给定网络一致。形状的格式应为(channel, image_width, image_height)。 + - **input_bound** (Union[tuple, list]) - 原始图像的像素范围，应该像[minimum_pixel, maximum_pixel]或(minimum_pixel, maximum_pixel)。 + - **loss_weights** (Union[list, tuple]) - InversionLoss中三个子损失的权重，可以调整以获得更好的结果。默认值：(1, 0.2, 5)。 - - **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` 的值有非正整数。 - - **ValueError** - `loss_weights` 的值有非正数。 + 异常： + - **TypeError** - 网络类型不是Cell。 + - **ValueError** - `input_shape` 的值有非正整数。 + - **ValueError** - `loss_weights` 的值有非正数。 .. py:method:: evaluate(original_images, inversion_images, labels=None, new_network=None) 通过三个指标评估还原图像的质量：原始图像和还原图像之间的平均L2距离和SSIM值，以及新模型对还原图像的推理结果在真实标签上的置信度平均值。 - **参数：** - - - **original_images** (numpy.ndarray) - 原始图像，其形状应为(img_num, channels, img_width, img_height)。 - - **inversion_images** (numpy.ndarray) - 还原图像，其形状应为(img_num, channels, img_width, img_height)。 - - **labels** (numpy.ndarray) - 原始图像的ground truth标签。默认值：None。 - - **new_network** (Cell) - 其结构包含self._network中所有网络，但加载了不同的模型文件。默认值：None。 + 参数： + - **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中所有网络，但加载了不同的模型文件。默认值：None。 - **返回：** - - - **float** - l2距离。 - - **float** - 平均ssim值。 - - **Union** [float, None] - 平均置信度。如果labels或new_network为 None，则该值为None。 + 返回： + - **float** - l2距离。 + - **float** - 平均ssim值。 + - **Union** [float, None] - 平均置信度。如果labels或new_network为 None，则该值为None。 .. py:method:: generate(target_features, iters=100) 根据 `target_features` 重建图像。 - **参数：** - - - **target_features** (numpy.ndarray) - 原始图像的深度表示。 `target_features` 的第一个维度应该是img_num。 - 需要注意的是，如果img_num等于1，则 `target_features` 的形状应该是(1, dim2, dim3, ...)。 - - **iters** (int) - 逆向攻击的迭代次数，应为正整数。默认值：100。 + 参数： + - **target_features** (numpy.ndarray) - 原始图像的深度表示。 `target_features` 的第一个维度应该是img_num。 + 需要注意的是，如果img_num等于1，则 `target_features` 的形状应该是(1, dim2, dim3, ...)。 + - **iters** (int) - 逆向攻击的迭代次数，应为正整数。默认值：100。 - **返回：** + 返回： + - **numpy.ndarray** - 重建图像，预计与原始图像相似。 - - **numpy.ndarray** - 重建图像，预计与原始图像相似。 - - **异常：** - - - **TypeError** - target_features的类型不是numpy.ndarray。 - - **ValueError** - `iters` 的有非正整数. + 异常： + - **TypeError** - target_features的类型不是numpy.ndarray。 + - **ValueError** - `iters` 的有非正整数. .. py:class:: mindarmour.ConceptDriftCheckTimeSeries(window_size=100, rolling_window=10, step=10, threshold_index=1.5, need_label=False) @@ -362,24 +321,21 @@ MindArmour是MindSpore的工具箱，用于增强模型可信，实现隐私保 有关详细信息，请查看： `实现时序数据概念漂移检测应用 `_。 - **参数：** - - - **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。 + 参数： + - **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列）是一个数据序列。 - - **返回：** + 参数： + - **data** (numpy.ndarray) - 输入数据。数据的shape可以是(n,1)或(n,m)。请注意，每列（m列）是一个数据序列。 - - **numpy.ndarray** - 样本序列的概念漂移分数。 - - **float** - 判断概念漂移的阈值。 - - **list** - 概念漂移的位置。 + 返回： + - **numpy.ndarray** - 样本序列的概念漂移分数。 + - **float** - 判断概念漂移的阈值。 + - **list** - 概念漂移的位置。 diff --git a/docs/api/api_python/mindarmour.utils.rst b/docs/api/api_python/mindarmour.utils.rst index a93681d..e2385b4 100644 --- a/docs/api/api_python/mindarmour.utils.rst +++ b/docs/api/api_python/mindarmour.utils.rst @@ -9,59 +9,52 @@ MindArmour的工具方法。 在长期运行的脚本中记录随时间推移的日志统计信息。 - **异常：** - - - **SyntaxError** - 创建此类异常。 + 异常： + - **SyntaxError** - 创建此类异常。 .. py:method:: add_handler(handler) 添加日志模块支持的其他处理程序。 - **参数：** - - - **handler** (logging.Handler) - 日志模块支持的其他处理程序。 + 参数： + - **handler** (logging.Handler) - 日志模块支持的其他处理程序。 - **异常：** - - - **ValueError** - 输入handler不是logging.Handler的实例。 + 异常： + - **ValueError** - 输入handler不是logging.Handler的实例。 .. py:method:: debug(tag, msg, *args) 记录'[tag] msg % args'，严重性为'DEBUG'。 - **参数：** - - - **tag** (str) - Logger标记。 - - **msg** (str) - Logger消息。 - - **args** (Any) - 辅助值。 + 参数： + - **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) - 辅助值。 + 参数： + - **tag** (str) - Logger标记。 + - **msg** (str) - Logger消息。 + - **args** (Any) - 辅助值。 .. py:method:: get_instance() 获取类 `LogUtil` 的实例。 - **返回：** - - - **Object** - 类 `LogUtil` 的实例。 + 返回： + - **Object** - 类 `LogUtil` 的实例。 .. py:method:: info(tag, msg, *args) 记录'[tag] msg % args'，严重性为'INFO'。 - **参数：** - - - **tag** (str) - Logger标记。 - - **msg** (str) - Logger消息。 - - **args** (Any) - 辅助值。 + 参数： + - **tag** (str) - Logger标记。 + - **msg** (str) - Logger消息。 + - **args** (Any) - 辅助值。 .. py:method:: set_level(level) @@ -69,60 +62,52 @@ MindArmour的工具方法。 例如，如果logger.set_level('WARNING')或logger.set_level(21)，则在运行时将打印脚本中的logger.warn()和logger.error()，而logger.info()或logger.debug()将不会打印。 - **参数：** - - - **level** (Union[int, str]) - logger的级别。 + 参数： + - **level** (Union[int, str]) - logger的级别。 .. py:method:: warn(tag, msg, *args) 记录'[tag] msg % args'，严重性为'WARNING'。 - **参数：** - - - **tag** (str) - Logger标记。 - - **msg** (str) - Logger消息。 - - **args** (Any) - 辅助值。 + 参数： + - **tag** (str) - Logger标记。 + - **msg** (str) - Logger消息。 + - **args** (Any) - 辅助值。 .. py:class:: mindarmour.utils.GradWrapWithLoss(network) 构造一个网络来计算输入空间中损失函数的梯度，并由 `weight` 加权。 - **参数：** - - - **network** (Cell) - 要包装的目标网络。 + 参数： + - **network** (Cell) - 要包装的目标网络。 .. py:method:: construct(inputs, labels) 使用标签和权重计算 `inputs` 的梯度。 - **参数：** - - - **inputs** (Tensor) - 网络的输入。 - - **labels** (Tensor) - 输入的标签。 - - **返回：** + 参数： + - **inputs** (Tensor) - 网络的输入。 + - **labels** (Tensor) - 输入的标签。 - - **Tensor** - 梯度矩阵。 + 返回： + - **Tensor** - 梯度矩阵。 .. py:class:: mindarmour.utils.GradWrap(network) 构建一个网络，以计算输入空间中网络输出的梯度，并由 `weight` 加权，表示为雅可比矩阵。 - **参数：** - - - **network** (Cell) - 要包装的目标网络。 + 参数： + - **network** (Cell) - 要包装的目标网络。 .. py:method:: construct(*data) 计算雅可比矩阵（jacobian matrix）。 - **参数：** - - - **data** (Tensor) - 数据由输入和权重组成。 - - - inputs: 网络的输入。 - - weight: 每个梯度的权重，'weight'与'labels'的shape相同。 + 参数： + - **data** (Tensor) - 数据由输入和权重组成。 - **返回：** + - inputs: 网络的输入。 + - weight: 每个梯度的权重，'weight'与'labels'的shape相同。 - - **Tensor** - 雅可比矩阵。 + 返回： + - **Tensor** - 雅可比矩阵。