---

Opacus 是一个支持使用差分隐私训练 PyTorch 模型的库。它只需对客户端代码进行极小的改动即可实现训练，对训练性能的影响也很小，并且允许客户端实时跟踪当前已消耗的隐私预算。

目标用户

本次代码发布面向两类目标用户：

1. 机器学习从业者会发现，由于只需少量代码改动，这为他们提供了一个以温和方式入门差分隐私模型训练的途径。
2. 差分隐私领域的研究人员则会发现，该库易于实验和调试，使他们能够专注于核心问题。

最新动态

2024年12月18日：我们更新了此 教程，展示了如何将 LoRA 和 peft 库与 DP-SGD 结合使用。

2024年8月20日：我们在 Opacus 中引入了 快速梯度裁剪 和 Ghost 裁剪，显著降低了 DP-SGD 的内存需求。更多信息请参阅我们的 博客文章。

安装

最新版本的 Opacus 可通过 pip 安装：

pip install opacus

或者，也可以通过 conda 安装：

conda install -c conda-forge opacus

你还可以直接从源码安装以获取最新功能（但可能伴随一些小问题或偶尔出现的 bug）：

git clone https://github.com/pytorch/opacus.git
cd opacus
pip install -e .

快速开始

要使用差分隐私训练你的模型，你只需实例化一个 PrivacyEngine，并将你的模型、数据加载器和优化器传递给引擎的 make_private() 方法，即可获得对应的私有版本。

# 按照常规方式定义你的组件
model = Net()
optimizer = SGD(model.parameters(), lr=0.05)
data_loader = torch.utils.data.DataLoader(dataset, batch_size=1024)

# 使用 PrivacyEngine
privacy_engine = PrivacyEngine()
model, optimizer, data_loader = privacy_engine.make_private(
    module=model,
    optimizer=optimizer,
    data_loader=data_loader,
    noise_multiplier=1.1,
    max_grad_norm=1.0,
)
# 现在就可以像往常一样继续训练了

MNIST 示例 展示了使用 Opacus 的端到端运行流程。示例文件夹 中还包含更多类似的示例。

深入学习

交互式教程

我们构建了一系列基于 IPython 的教程，旨在以温和的方式介绍如何使用隐私保护技术训练模型以及 Opacus 的各项功能。

• 使用 BERT 在差分隐私下构建文本分类器
• 使用差分隐私构建图像分类器
• 训练用于姓名分类的差分隐私 LSTM 模型
• Opacus 指南：高级功能介绍
• Opacus 指南：梯度采样器
• Opacus 指南：模块验证器和修复工具
• Opacus 指南：非包装模式下的训练

技术报告与引用

介绍 Opacus 的技术报告，其中阐述了其设计原则、数学基础和基准测试结果，可在此处找到： https://arxiv.org/abs/2109.12298。

如果你在论文中使用了 Opacus，请参考以下引用格式：

@article{opacus,
  title={Opacus: {U}ser-Friendly Differential Privacy Library in {PyTorch}},
  author={Ashkan Yousefpour and Igor Shilov and Alexandre Sablayrolles and Davide Testuggine and Karthik Prasad and Mani Malek and John Nguyen and Sayan Ghosh and Akash Bharadwaj and Jessica Zhao and Graham Cormode and Ilya Mironov},
  journal={arXiv preprint arXiv:2109.12298},
  year={2021}
}

博客文章与演讲

如果你想深入了解 DP-SGD 及相关主题，可以查看我们的系列博客文章和演讲：

• 在 Opacus 中启用快速梯度裁剪和 Ghost 裁剪
• 差分隐私系列第一部分 | 解释 DP-SGD 算法
• 差分隐私系列第二部分 | 在 Opacus 中高效计算每样本梯度
• PriCon 2020 教程：使用 Opacus 进行差分隐私模型训练
• PyTorch 上的差分隐私 | PyTorch 开发者日 2020
• Opacus v1.0 亮点 | PyTorch 开发者日 2021

常见问题解答

请访问 FAQ 页面，获取关于差分隐私和 Opacus 的一些常见问题的答案。

贡献

有关如何参与贡献的信息，请参阅 CONTRIBUTING 文件。同时，也请查阅仓库内的 README 文件，了解代码的组织结构。

许可证

本项目采用 Apache 2.0 许可证发布，详情请参阅 LICENSE 文件。

Opacus 快速上手指南

Opacus 是一个用于在 PyTorch 中训练差分隐私（Differential Privacy, DP）模型的库。它只需极少的代码改动即可实现隐私保护训练，支持实时追踪隐私预算消耗，且对训练性能影响较小。

环境准备

• 系统要求：支持 Linux、macOS 和 Windows。
• 前置依赖：
  • Python 3.8+
  • PyTorch 1.8+ (建议安装最新稳定版)
  • torchvision (可选，用于图像示例)

注意：请确保已正确安装 PyTorch。国内用户推荐使用清华或阿里镜像源安装 PyTorch 基础环境。

安装步骤

你可以选择通过 pip 或 conda 进行安装。国内开发者建议使用国内镜像源以加速下载。

方式一：使用 pip 安装（推荐）

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

方式二：使用 conda 安装

conda install -c conda-forge opacus

方式三：从源码安装（获取最新特性）

如果你需要体验最新的功能（可能包含未发布的修复或实验性特性），可以从 GitHub 克隆源码安装：

git clone https://github.com/pytorch/opacus.git
cd opacus
pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

使用 Opacus 进行差分隐私训练非常简单，核心步骤是实例化 PrivacyEngine 并调用 make_private() 方法包装你的模型、优化器和数据加载器。

以下是最小化的使用示例：

import torch
from torch.utils.data import DataLoader
from torch.optim import SGD
from opacus import PrivacyEngine

# 1. 定义常规组件 (模型、优化器、数据加载器)
model = Net()  # 替换为你的模型定义
optimizer = SGD(model.parameters(), lr=0.05)
data_loader = DataLoader(dataset, batch_size=1024)

# 2. 初始化 PrivacyEngine
privacy_engine = PrivacyEngine()

# 3. 将组件转换为隐私保护版本
model, optimizer, data_loader = privacy_engine.make_private(
    module=model,
    optimizer=optimizer,
    data_loader=data_loader,
    noise_multiplier=1.1,      # 噪声乘数，控制隐私强度
    max_grad_norm=1.0,         # 最大梯度范数，用于梯度裁剪
)

# 4. 开始正常训练循环
# 接下来的训练代码 (forward, loss.backward, optimizer.step) 无需更改
for epoch in range(num_epochs):
    for inputs, targets in data_loader:
        optimizer.zero_grad()
        outputs = model(inputs)
        loss = criterion(outputs, targets)
        loss.backward()
        optimizer.step()
        
    # 可选：查看当前消耗的隐私预算
    epsilon = privacy_engine.get_epsilon(delta=1e-5)
    print(f"Epoch {epoch}: Epsilon = {epsilon}")

关键参数说明：

• noise_multiplier: 添加到梯度的噪声标准差与裁剪阈值的比率。值越大，隐私性越强，但模型效用可能降低。
• max_grad_norm: 每个样本梯度的最大范数阈值，超过此值的梯度将被裁剪。

更多完整示例（如 MNIST 分类、BERT 文本分类等）请参考官方 examples 目录或交互式教程。