mindarmour.privacy.diff_privacy

本模块提供差分隐私功能,以保护用户隐私。

class mindarmour.privacy.diff_privacy.NoiseGaussianRandom(norm_bound=1.0, initial_noise_multiplier=1.0, seed=0, decay_policy=None)[源代码]

基于高斯机制产生噪声,方法是 \(mean=0\) 以及 \(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。

样例:

>>> from mindspore import Tensor
>>> from mindspore.common import dtype as mstype
>>> from mindarmour.privacy.diff_privacy import NoiseGaussianRandom
>>> gradients = Tensor([0.2, 0.9], mstype.float32)
>>> norm_bound = 0.1
>>> initial_noise_multiplier = 1.0
>>> seed = 0
>>> decay_policy = None
>>> net = NoiseGaussianRandom(norm_bound, initial_noise_multiplier, seed, decay_policy)
>>> res = net(gradients)
construct(gradients)[源代码]

产生的高斯噪声。

参数:

  • gradients (Tensor) - 梯度。

返回:

  • Tensor - 生成的shape与给定梯度相同的噪声。

class mindarmour.privacy.diff_privacy.NoiseAdaGaussianRandom(norm_bound=1.0, initial_noise_multiplier=1.0, seed=0, noise_decay_rate=6e-06, decay_policy='Exp')[源代码]

自适应高斯噪声产生机制。噪音会随着训练而衰减。衰减模式可以是’Time’、’Step’、’Exp’。 在模型训练过程中,将更新 self._noise_multiplier

参数:

  • norm_bound (float) - 梯度的l2范数的裁剪范围。默认值:1.0。

  • initial_noise_multiplier (float) - 高斯噪声标准偏差除以norm_bound的比率,将用于计算隐私预算。默认值:1.0。

  • seed (int) - 原始随机种子,如果seed=0随机正态将使用安全随机数。如果seed!=0随机正态将使用给定的种子生成值。默认值:0。

  • noise_decay_rate (float) - 控制噪声衰减的超参数。默认值:6e-6。

  • decay_policy (str) - 噪声衰减策略包括’Step’、’Time’、’Exp’。默认值:’Exp’。

样例:

>>> from mindspore import Tensor
>>> from mindspore.common import dtype as mstype
>>> from mindarmour.privacy.diff_privacy import NoiseAdaGaussianRandom
>>> gradients = Tensor([0.2, 0.9], mstype.float32)
>>> norm_bound = 1.0
>>> initial_noise_multiplier = 1.0
>>> seed = 0
>>> noise_decay_rate = 6e-6
>>> decay_policy = "Exp"
>>> net = NoiseAdaGaussianRandom(norm_bound, initial_noise_multiplier, seed, noise_decay_rate, decay_policy)
>>> res = net(gradients)
construct(gradients)[源代码]

生成的自适应高斯噪声。

参数:

  • gradients (Tensor) - 梯度。

返回:

  • Tensor - 生成的shape与给定梯度相同的噪声。

class mindarmour.privacy.diff_privacy.AdaClippingWithGaussianRandom(decay_policy='Linear', learning_rate=0.001, target_unclipped_quantile=0.9, fraction_stddev=0.01, seed=0)[源代码]

自适应剪裁。如果 deay_policy 是’Linear’,则更新公式 \(norm\_bound = norm\_bound - learning\_rate*(beta - target\_unclipped\_quantile)\)

如果 deay_policy 是’Geometric’,则更新公式为 \(norm\_bound = norm\_bound*exp(-learning\_rate*(empirical\_fraction - target\_unclipped\_quantile))\)

其中,beta是值最多为 target_unclipped_quantile 的样本的经验分数。

参数:

  • decay_policy (str) - 自适应剪裁的衰变策略, decay_policy 必须在[‘Linear’, ‘Geometric’]中。默认值:’Linear’。

  • learning_rate (float) - 更新范数裁剪的学习率。默认值:0.001。

  • target_unclipped_quantile (float) - 范数裁剪的目标分位数。默认值:0.9。

  • fraction_stddev (float) - 高斯正态的stddev,用于 empirical_fraction ,公式为empirical_fraction + N(0, fraction_stddev)。默认值:0.01。

  • seed (int) - 原始随机种子,如果seed=0随机正态将使用安全随机数。如果seed!=0随机正态将使用给定的种子生成值。默认值:0。

返回:

  • Tensor - 更新后的梯度裁剪阈值。

样例:

>>> from mindspore import Tensor
>>> from mindspore.common import dtype as mstype
>>> from mindarmour.privacy.diff_privacy import AdaClippingWithGaussianRandom
>>> decay_policy = 'Linear'
>>> beta = Tensor(0.5, mstype.float32)
>>> norm_bound = Tensor(1.0, mstype.float32)
>>> beta_stddev = 0.01
>>> learning_rate = 0.001
>>> target_unclipped_quantile = 0.9
>>> ada_clip = AdaClippingWithGaussianRandom(decay_policy=decay_policy,
...                                          learning_rate=learning_rate,
...                                          target_unclipped_quantile=target_unclipped_quantile,
...                                          fraction_stddev=beta_stddev)
>>> next_norm_bound = ada_clip(beta, norm_bound)
construct(empirical_fraction, norm_bound)[源代码]

更新norm_bound的值。

参数:

  • empirical_fraction (Tensor) - 梯度裁剪的经验分位数,最大值不超过 target_unclipped_quantile

  • norm_bound (Tensor) - 梯度的l2范数的裁剪范围。

返回:

  • Tensor - 生成的shape与给定梯度相同的噪声。

class mindarmour.privacy.diff_privacy.NoiseMechanismsFactory[源代码]

噪声产生机制的工厂类。它目前支持高斯随机噪声(Gaussian Random Noise)和自适应高斯随机噪声(Adaptive Gaussian Random Noise)。

详情请查看: 教程

create(mech_name, norm_bound=1.0, initial_noise_multiplier=1.0, seed=0, noise_decay_rate=6e-06, decay_policy=None)[源代码]

参数:

  • mech_name (str) - 噪声生成策略,可以是’Gaussian’或’AdaGaussian’。噪声在’AdaGaussian’机制下衰减,而在’Gaussian’机制下则恒定。

  • norm_bound (float) - 梯度的l2范数的裁剪范围。默认值:1.0。

  • initial_noise_multiplier (float) - 高斯噪声标准偏差除以norm_bound的比率,将用于计算隐私预算。默认值:1.0。

  • seed (int) - 原始随机种子,如果seed=0随机正态将使用安全随机数。如果seed!=0随机正态将使用给定的种子生成值。默认值:0。

  • noise_decay_rate (float) - 控制噪声衰减的超参数。默认值:6e-6。

  • decay_policy (str) - 衰减策略。如果decay_policy为None,则不需要更新参数。默认值:None。

异常:

  • NameError - mech_name 必须在[‘Gaussian’, ‘AdaGaussian’]中。

返回:

  • Mechanisms - 产生的噪声类别机制。

样例:

>>> from mindarmour.privacy.diff_privacy import NoiseMechanismsFactory
>>> norm_bound = 1.0
>>> initial_noise_multiplier = 1.0
>>> noise_mechanism = NoiseMechanismsFactory()
>>> clip = noise_mechanism.create('Gaussian',
...                               norm_bound=norm_bound,
...                               initial_noise_multiplier=initial_noise_multiplier)
class mindarmour.privacy.diff_privacy.ClipMechanismsFactory[源代码]

梯度剪裁机制的工厂类。它目前支持高斯随机噪声(Gaussian Random Noise)的自适应剪裁(Adaptive Clipping)。

详情请查看: 教程

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,公式为 \(empirical\_fraction + N(0, fraction\_stddev)\) 。默认值:0.01。

  • seed (int) - 原始随机种子,如果seed=0随机正态将使用安全随机数。如果seed!=0随机正态将使用给定的种子生成值。默认值:0。

异常:

  • NameError - mech_name 必须在[‘Gaussian’]中。

返回:

  • Mechanisms - 产生的噪声类别机制。

样例:

>>> from mindspore import Tensor
>>> from mindspore.common import dtype as mstype
>>> from mindarmour.privacy.diff_privacy import ClipMechanismsFactory
>>> decay_policy = 'Linear'
>>> beta = Tensor(0.5, mstype.float32)
>>> norm_bound = Tensor(1.0, mstype.float32)
>>> beta_stddev = 0.01
>>> learning_rate = 0.001
>>> target_unclipped_quantile = 0.9
>>> clip_mechanism = ClipMechanismsFactory()
>>> ada_clip = clip_mechanism.create('Gaussian',
...                                  decay_policy=decay_policy,
...                                  learning_rate=learning_rate,
...                                  target_unclipped_quantile=target_unclipped_quantile,
...                                  fraction_stddev=beta_stddev)
>>> next_norm_bound = ada_clip(beta, norm_bound)
class mindarmour.privacy.diff_privacy.PrivacyMonitorFactory[源代码]

DP训练隐私监视器的工厂类。

详情请查看: 教程

create(policy, *args, **kwargs)[源代码]

创建隐私预算监测类。

参数:

  • policy (str) - 监控策略,现支持’rdp’和’zcdp’。 - 如果策略为’rdp’,监控器将根据Renyi差分隐私(Renyi differential privacy,RDP)理论计算DP训练的隐私预算; - 如果策略为’zcdp’,监控器将根据零集中差分隐私(zero-concentrated differential privacy,zCDP)理论计算DP训练的隐私预算。注意,’zcdp’不适合子采样噪声机制。

  • args (Union[int, float, numpy.ndarray, list, str]) - 用于创建隐私监视器的参数。

  • kwargs (Union[int, float, numpy.ndarray, list, str]) - 用于创建隐私监视器的关键字参数。

返回:

  • Callback - 隐私监视器。

样例:

>>> from mindarmour.privacy.diff_privacy import PrivacyMonitorFactory
>>> rdp = PrivacyMonitorFactory.create(policy='rdp', num_samples=60000, batch_size=32)
class mindarmour.privacy.diff_privacy.RDPMonitor(num_samples, batch_size, initial_noise_multiplier=1.5, max_eps=10.0, target_delta=0.001, max_delta=None, target_eps=None, orders=None, noise_decay_mode='Time', noise_decay_rate=0.0006, per_print_times=50, dataset_sink_mode=False)[源代码]

基于Renyi差分隐私(RDP)理论,计算DP训练的隐私预算。根据下面的参考文献,如果随机化机制被认为具有α阶的ε’-Renyi差分隐私,它也满足常规差分隐私(ε, δ),如下所示:

\[(ε'+\frac{log(1/δ)}{α-1}, δ)\]

详情请查看: 教程

参考文献: 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。

样例:

>>> from mindarmour.privacy.diff_privacy import PrivacyMonitorFactory
>>> rdp = PrivacyMonitorFactory.create(policy='rdp', num_samples=100, batch_size=32)
max_epoch_suggest()[源代码]

估计最大训练epoch,以满足预定义的隐私预算。

返回:

  • int - 建议的最大训练epoch。

step_end(run_context)[源代码]

在每个训练步骤后计算隐私预算。

参数:

  • run_context (RunContext) - 包含模型的一些信息。

class mindarmour.privacy.diff_privacy.ZCDPMonitor(num_samples, batch_size, initial_noise_multiplier=1.5, max_eps=10.0, target_delta=0.001, noise_decay_mode='Time', noise_decay_rate=0.0006, per_print_times=50, dataset_sink_mode=False)[源代码]

基于零集中差分隐私(zCDP)理论,计算DP训练的隐私预算。根据下面的参考文献,如果随机化机制满足ρ-zCDP机制,它也满足传统的差分隐私(ε, δ),如下所示:

\[(ρ+2\sqrt{ρ*log(1/δ)}, δ)\]

注意,ZCDPMonitor不适合子采样噪声机制(如NoiseAdaGaussianRandom和NoiseGaussianRandom)。未来将开发zCDP的匹配噪声机制。

详情请查看: 教程

参考文献: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。

样例:

>>> from mindarmour.privacy.diff_privacy import PrivacyMonitorFactory
>>> zcdp = PrivacyMonitorFactory.create(policy='zcdp',
...                                     num_samples=100,
...                                     batch_size=32,
...                                     initial_noise_multiplier=1.5)
max_epoch_suggest()[源代码]

估计最大训练epoch,以满足预定义的隐私预算。

返回:

  • int - 建议的最大训练epoch。

step_end(run_context)[源代码]

在每个训练步骤后计算隐私预算。

参数:

  • run_context (RunContext) - 包含模型的一些信息。

class mindarmour.privacy.diff_privacy.DPOptimizerClassFactory(micro_batches=2)[源代码]

优化器的工厂类。

参数:

  • micro_batches (int) - 从原始批次拆分的小批次中的样本数量。默认值:2。

返回:

  • Optimizer - 优化器类。

样例:

>>> from mindarmour.privacy.diff_privacy import DPOptimizerClassFactory
>>> class Net(nn.Cell):
...     def __init__(self):
...         super(Net, self).__init__()
...         self._relu = nn.ReLU()
...     def construct(self, inputs):
...         out = self._relu(inputs)
...         return out
>>> network = Net()
>>> GaussianSGD = DPOptimizerClassFactory(micro_batches=2)
>>> GaussianSGD.set_mechanisms('Gaussian', norm_bound=1.0, initial_noise_multiplier=1.5)
>>> net_opt = GaussianSGD.create('Momentum')(params=network.trainable_params(),
...                                          learning_rate=0.001,
...                                          momentum=0.9)
create(policy)[源代码]

创建DP优化器。策略可以是’sgd’、’momentum’、’adam’。

参数:

  • policy (str) - 选择原始优化器类型。

返回:

  • Optimizer - 一个带有差分加噪的优化器。

set_mechanisms(policy, *args, **kwargs)[源代码]

获取噪音机制对象。策略可以是’Gaussian’或’AdaGaussian’。候选的args和kwargs可以在mechanisms.py的NoiseMechanismsFactory类中看到。

参数:

  • policy (str) - 选择机制类型。

class mindarmour.privacy.diff_privacy.DPModel(micro_batches=2, norm_bound=1.0, noise_mech=None, clip_mech=None, **kwargs)[源代码]

DPModel用于构建差分隐私训练的模型。

这个类重载自Mindpore.train.model.Model。

详情请查看: 教程

参数:

  • micro_batches (int) - 从原始批次拆分的小批次数。默认值:2。

  • norm_bound (float) - 用于裁剪范围,如果设置为1,将返回原始数据。默认值:1.0。

  • noise_mech (Mechanisms) - 对象可以生成不同类型的噪音。默认值:None。

  • clip_mech (Mechanisms) - 该对象用于更新自适应剪裁。默认值:None。

异常:

  • ValueError - DPOptimizer和noise_mech都为None或非None。

  • ValueError - noise_mech或DPOtimizer的mech方法是自适应的,而clip_mech不是None。