Diffprivlib v0.6

Diffprivlib 是一个用于差分隐私（DP）的通用库。如果您希望：

• 尝试差分隐私技术
• 探索差分隐私对机器学习和数据分析应用的影响
• 原型设计您自己的差分隐私算法

自 2019 年首次发布以来，diffprivlib 已被证明是差分隐私社区中不可或缺的资源，获得了数百次引用、星标、分支和部署。该库降低了新科学家和工程师进入差分隐私领域并进行学习的门槛，催生了新的研究，并成为新算法和新库的基准。

注意： diffprivlib 的公开发布仅用于研究和教育目的。如果您有意在生产环境中使用 diffprivlib，请与我们联系。

入门：30 秒内实现差分隐私的机器学习

我们使用 Iris 数据集，让我们加载它并进行 80/20 的训练/测试集划分。

from sklearn import datasets
from sklearn.model_selection import train_test_split

dataset = datasets.load_iris()
X_train, X_test, y_train, y_test = train_test_split(dataset.data, dataset.target, test_size=0.2)

现在，让我们训练一个差分隐私朴素贝叶斯分类器。我们的分类器 运行方式与 sklearn 分类器完全相同，因此您可以快速上手。

diffprivlib.models.GaussianNB 可以 无需任何参数 运行，尽管这会触发警告（我们需要指定 bounds 参数来避免此情况）。隐私级别由参数 epsilon 控制，该参数在分类器初始化时传入（例如 GaussianNB(epsilon=0.1)）。默认值为 epsilon = 1.0。

from diffprivlib.models import GaussianNB

clf = GaussianNB()
clf.fit(X_train, y_train)

现在我们可以对未见过的样本进行分类，同时确信训练好的模型是差分隐私的，并且保护了训练集中“个体”的隐私（毕竟，花朵也有隐私权嘛！）。

clf.predict(X_test)

每次调用 .fit() 训练模型时，由于差分隐私的随机性，都会生成不同的模型。因此，即使使用相同的训练数据重新训练，准确率也会有所变化。不妨亲自尝试一下，看看结果吧！

print("测试准确率：%f" % clf.score(X_test, y_test))

我们可以轻松评估不同 epsilon 值下的模型准确率，并使用 matplotlib 绘制图表。

import numpy as np
import matplotlib.pyplot as plt

epsilons = np.logspace(-2, 2, 50)
bounds = ([4.3, 2.0, 1.1, 0.1], [7.9, 4.4, 6.9, 2.5])
accuracy = list()

for epsilon in epsilons:
    clf = GaussianNB(bounds=bounds, epsilon=epsilon)
    clf.fit(X_train, y_train)
    
    accuracy.append(clf.score(X_test, y_test))

plt.semilogx(epsilons, accuracy)
plt.title("差分隐私朴素贝叶斯准确率")
plt.xlabel("epsilon")
plt.ylabel("准确率")
plt.show()

恭喜您！您已经使用差分隐私库完成了您的第一个差分隐私机器学习任务！更多示例请查看 notebooks 目录，或直接深入 源码。

内容

Diffprivlib 由四个主要组件组成：

1. 机制： 这些是差分隐私的构建模块，所有实现差分隐私的模型都会使用它们。机制几乎没有默认设置，主要供专家在实现自有模型时使用。不过，它们也可以独立于模型用于单独的研究等。
2. 模型： 本模块包含具有差分隐私功能的机器学习模型。目前，Diffprivlib 提供聚类、分类、回归、降维和预处理等模型。
3. 工具： Diffprivlib 配备了多种用于差分隐私数据分析的通用工具。其中包括差分隐私直方图，其格式与 Numpy 的 histogram 函数 相同。
4. 预算管理器： BudgetAccountant 类可用于跟踪隐私预算，并利用高级组合技术计算总隐私损失。

安装

使用 pip 安装

该库专为 Python 3 设计。 可以通过 PyPI 仓库使用 pip（或 pip3）安装：

pip install diffprivlib

手动安装

要获取最新版本的库，您可以下载源代码或将仓库克隆到您选择的目录中：

git clone https://github.com/IBM/differential-privacy-library

要在项目文件夹中安装 diffprivlib，请执行以下操作（或者您也可以运行 python3 -m pip install .）：

pip install .

该库附带一组基本的 pytest 单元测试。要检查您的安装是否正常，可以在安装目录中运行所有单元测试：

pytest

引用 diffprivlib

如果您在研究中使用 diffprivlib，请考虑引用以下参考文献：

@article{diffprivlib,
  title={Diffprivlib：{IBM} 差分隐私库},
  author={Holohan, Naoise and Braghin, Stefano and Mac Aonghusa, P{\'o}l and Levacher, Killian},
  year={2019},
  journal = {ArXiv e-prints},
  archivePrefix = "arXiv",
  volume = {1907.02444 [cs.CR]},
  primaryClass = "cs.CR",
  month = jul
}

参考文献

• Holohan, N., Antonatos, S., Braghin, S. 和 Mac Aonghusa, P., 2018. 差分隐私中的有界拉普拉斯机制. 隐私与保密期刊 第10卷第1期.
• Holohan, N., Braghin, S., Mac Aonghusa, P. 和 Levacher, K., 2019. Diffprivlib：IBM 差分隐私库. ArXiv e-prints 1907.02444 [cs.CR].
• Ludwig, H., Baracaldo, N., Thomas, G., Zhou, Y., Anwar, A., Rajamoni, S., Ong, Y., Radhakrishnan, J., Verma, A., Sinn, M. 和 Purcell, M., 2020. IBM 联邦学习：企业级框架白皮书 v0.1. ArXiv e-prints 2007.10987 [cs.LG].
• Holohan, N. 和 Braghin, S., 2021. 差分隐私中的安全随机采样. 载于《计算机安全—ESORICS 2021：第26届欧洲计算机安全研究研讨会，德国达姆施塔特，2021年10月4日至8日，论文集，第二部分 第26章（第523–542页）。Springer International Publishing.
• Holohan, N., 2023. 用于差分隐私的随机数生成器与种子设置. ArXiv e-prints 2307.03543 [cs.CR].
• Holohan, N., Braghin, S. 和 Suliman, M., 2024. 为噪声添加提供保障的浮点运算. 载于2024年ACM SIGSAC计算机与通信安全会议论文集（第1954–1966页）。

致谢

本仓库中的工作部分得到了欧盟“地平线”研究与创新计划的资助，资助编号分别为951911（AI4Media）和101070473（FLUIDOS）。

Diffprivlib 快速上手指南

Diffprivlib 是 IBM 开源的通用差分隐私（Differential Privacy, DP）库，旨在降低研究人员和工程师进入差分隐私领域的门槛。它提供了与 scikit-learn 兼容的机器学习模型、基础机制及隐私预算跟踪工具，适用于实验、原型开发及数据分析。

注意：该库主要用于研究和教育目的。若需在生产环境中使用，请联系官方团队。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：Python 3.6 及以上
• 核心依赖：
  • numpy
  • scikit-learn
  • matplotlib (用于绘图示例)
  • pytest (可选，用于运行测试)

确保已安装 Python 3 及 pip 包管理工具。

安装步骤

方式一：通过 PyPI 安装（推荐）

使用 pip 直接安装稳定版：

pip install diffprivlib

国内用户加速建议：如果下载速度较慢，可使用国内镜像源（如清华源）：

pip install diffprivlib -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：从源码安装（获取最新版本）

克隆仓库并本地安装：

git clone https://github.com/IBM/differential-privacy-library
cd differential-privacy-library
pip install .

验证安装

安装完成后，可运行内置单元测试检查环境是否正常：

pytest

基本使用

Diffprivlib 的设计理念是与 scikit-learn 保持接口一致。以下示例展示如何在 30 秒内训练一个具有差分隐私保护的朴素贝叶斯分类器。

1. 数据准备

加载经典的 Iris 数据集并进行训练集/测试集划分：

from sklearn import datasets
from sklearn.model_selection import train_test_split

dataset = datasets.load_iris()
X_train, X_test, y_train, y_test = train_test_split(dataset.data, dataset.target, test_size=0.2)

2. 训练差分隐私模型

导入 GaussianNB 模型。该模型用法与普通 sklearn 模型完全相同。

• epsilon: 控制隐私保护强度（默认 1.0，值越小隐私性越强，但准确率可能下降）。
• bounds: 数据边界范围（强烈建议指定以消除警告并提高准确性）。

from diffprivlib.models import GaussianNB

# 定义数据边界 (根据 Iris 数据集特征范围)
bounds = ([4.3, 2.0, 1.1, 0.1], [7.9, 4.4, 6.9, 2.5])

# 初始化并训练模型
clf = GaussianNB(bounds=bounds, epsilon=1.0)
clf.fit(X_train, y_train)

3. 预测与评估

使用训练好的模型进行预测，并计算准确率。由于差分隐私引入了随机噪声，每次运行 .fit() 得到的模型和准确率都会略有不同。

# 预测
predictions = clf.predict(X_test)

# 评估准确率
print("Test accuracy: %f" % clf.score(X_test, y_test))

4. 进阶：探索隐私预算对准确率的影响

可以通过循环不同的 epsilon 值，观察隐私保护强度与模型性能之间的权衡关系：

import numpy as np
import matplotlib.pyplot as plt
from diffprivlib.models import GaussianNB

epsilons = np.logspace(-2, 2, 50)
bounds = ([4.3, 2.0, 1.1, 0.1], [7.9, 4.4, 6.9, 2.5])
accuracy = list()

for epsilon in epsilons:
    clf = GaussianNB(bounds=bounds, epsilon=epsilon)
    clf.fit(X_train, y_train)
    accuracy.append(clf.score(X_test, y_test))

plt.semilogx(epsilons, accuracy)
plt.title("Differentially private Naive Bayes accuracy")
plt.xlabel("epsilon")
plt.ylabel("Accuracy")
plt.show()

更多详细示例（如聚类、回归、直方图统计等）请参考项目官方 notebooks 目录。