鲁棒性包

通过 pip 安装：pip install robustness

阅读文档：https://robustness.readthedocs.io/en/latest/index.html

robustness 是我们（MadryLab <http://madry-lab.ml>_ 的学生）创建的一个软件包，旨在使神经网络的训练、评估和探索更加灵活便捷。我们在几乎所有的项目中都会使用它（无论是否涉及对抗训练！），并且它也将成为我们未来许多代码发布版本的依赖项。使用该库的一些项目包括：

• “通过对抗鲁棒性学习感知对齐表示”的代码 <https://github.com/MadryLab/robust_representations>_ (https://arxiv.org/abs/1906.00945)
• “仅用一个（鲁棒）分类器进行图像合成”的代码 <https://github.com/MadryLab/robustness_applications>_ (https://arxiv.org/abs/1906.09453)
• “对抗鲁棒的 ImageNet 模型迁移能力更好吗？”的代码 <https://github.com/microsoft/robust-models-transfer>_ (https://arxiv.org/abs/2007.08489)
• “BREEDS：子群体分布偏移基准测试”的代码 <https://github.com/MadryLab/BREEDS-Benchmarks>_ (https://arxiv.org/abs/2008.04859)
• “基于平滑视觉Transformer的认证补丁鲁棒性”的代码 <https://github.com/MadryLab/smoothed-vit>_ (https://arxiv.org/abs/2110.07719)
• “非对抗性样本：设计用于鲁棒视觉的对象”的代码 <https://github.com/microsoft/unadversarial>_ (https://arxiv.org/abs/2012.12235)

我们在一系列教程和 API 参考中展示了如何使用该库。该库提供的功能包括：

• 使用 CLI 界面 <https://robustness.readthedocs.io/en/latest/example_usage/cli_usage.html>_ 为多种数据集/架构训练和评估标准及鲁棒模型。该库还支持添加 自定义数据集 <https://robustness.readthedocs.io/en/latest/example_usage/training_lib_part_2.html#training-on-custom-datasets>_ 和 自定义模型架构 <https://robustness.readthedocs.io/en/latest/example_usage/training_lib_part_2.html#training-with-custom-architectures>_。

.. code-block:: bash

python -m robustness.main --dataset cifar --data /path/to/cifar
--adv-train 0 --arch resnet18 --out-dir /logs/checkpoints/dir/

• 使用鲁棒（或标准）模型进行 输入空间操作 <https://robustness.readthedocs.io/en/latest/example_usage/input_space_manipulation.html>_——这包括生成对抗样本、反演表征、特征可视化等。该库提供了多种优化选项（例如，选择真实梯度或估计梯度、傅里叶基或像素基、自定义损失函数等），并且易于扩展。

.. code-block:: python

import torch as ch from robustness.datasets import CIFAR from robustness.model_utils import make_and_restore_model

ds = CIFAR('/path/to/cifar') model, _ = make_and_restore_model(arch='resnet50', dataset=ds, resume_path='/path/to/model', state_dict_path='model') model.eval() attack_kwargs = { 'constraint': 'inf', # L-inf PGD 'eps': 0.05, # Epsilon约束（L-inf范数） 'step_size': 0.01, # PGD的学习率 'iterations': 100, # PGD的步数 'targeted': True # 目标攻击 'custom_loss': None # 使用默认的交叉熵损失 }

_, test_loader = ds.make_loaders(workers=0, batch_size=10) im, label = next(iter(test_loader)) target_label = (label + ch.randint_like(label, high=9)) % 10 adv_out, adv_im = model(im, target_label, make_adv, **attack_kwargs)

• 将 robustness 作为包导入，从而可以轻松训练神经网络，并支持自定义损失函数、日志记录、数据加载等功能！我们的两部分教程提供了一个很好的入门介绍（第一部分 <https://robustness.readthedocs.io/en/latest/example_usage/training_lib_part_1.html>, 第二部分 <https://robustness.readthedocs.io/en/latest/example_usage/training_lib_part_2.html>）。

.. code-block:: python

from robustness import model_utils, datasets, train, defaults from robustness.datasets import CIFAR

我们使用 cox（http://github.com/MadryLab/cox）来记录、存储和分析结果。更多信息请参见 https//cox.readthedocs.io。

from cox.utils import Parameters import cox.store

硬编码的数据集、架构、批量大小、工作线程数

ds = CIFAR('/path/to/cifar') m, _ = model_utils.make_and_restore_model(arch='resnet50', dataset=ds) train_loader, val_loader = ds.make_loaders(batch_size=128，workers=8)

创建一个 cox 存储用于日志记录

out_store = cox.store.Store(OUT_DIR)

硬编码的基本参数

train_kwargs = { 'out_dir': "train_out", 'adv_train': 1, 'constraint': '2', 'eps': 0.5, 'attack_lr': 1.5, 'attack_steps': 20 } train_args = Parameters(train_kwargs)

填充默认参数中缺失的部分

train_args = defaults.check_and_fill_args(train_args， defaults.TRAINING_ARGS，CIFAR) train_args = defaults.check_and_fill_args(train_args， defaults.PGD_ARGS，CIFAR)

训练模型

train.train_model(train_args，m，（train_loader，val_loader），store=out_store)

注意：robustness 需要安装支持 CUDA 的 PyTorch。

预训练模型

除了训练代码外，我们还发布了针对不同数据集、范数和 ε 训练值的若干预训练模型。随着更多或更优模型的发布，此列表将不断更新。如果您在研究中使用这些模型，请引用本库（见下方的 BibTeX 条目）。

对于每种（模型，ε 测试）组合，我们都会以 2.5 * ε-test / num_steps 的步长运行 20 步和 100 步的 PGD。由于这两种准确率非常接近，我们不再考虑更多的 PGD 步数。对于每个 ε 测试值，我们会用粗体突出显示不同 ε 训练下达到的最佳鲁棒准确率。

注释 #1：我们并未进行超参数调优，而是直接沿用了标准训练时的超参数。探索不同的训练超参数很可能会使这些鲁棒准确率再提高几个百分点。

注释 #2：以下的 PyTorch 检查点（.pt）文件是使用以下版本的 PyTorch 和 Dill 保存的：

.. code-block::

torch==1.1.0 dill==0.2.9

CIFAR10 L2 范数（ResNet50）：

• ε = 0.0 <https://www.dropbox.com/s/yhpp4yws7sgi6lj/cifar_nat.pt?dl=0>_（标准训练）
• ε = 0.25 <https://www.dropbox.com/s/2qsp7pt6t7uo71w/cifar_l2_0_25.pt?dl=0>_
• ε = 0.5 <https://www.dropbox.com/s/1zazwjfzee7c8i4/cifar_l2_0_5.pt?dl=0>_
• ε = 1.0 <https://www.dropbox.com/s/s2x7thisiqxz095/cifar_l2_1_0.pt?dl=0>_

+--------------+----------------+-----------------+---------------------+---------------------+ | CIFAR10 L2-鲁棒准确率 | +--------------+----------------+-----------------+---------------------+---------------------+ | | ε-训练 | +--------------+----------------+-----------------+---------------------+---------------------+ | ε-测试 | 0.0 | 0.25 | 0.5 | 1.0 | +==============+================+=================+=====================+=====================+ | 0.0 | 95.25% / - | 92.77% / - | 90.83% / - | 81.62% / - | +--------------+----------------+-----------------+---------------------+---------------------+ | 0.25 | 8.66% / 7.34% | 81.21% / 81.19% | 82.34% / 82.31% | 75.53% / 75.53% | +--------------+----------------+-----------------+---------------------+---------------------+ | 0.5 | 0.28% / 0.14% | 62.30% / 62.13% | 70.17% / 70.11% | 68.63% / 68.61% | +--------------+----------------+-----------------+---------------------+---------------------+ | 1.0 | 0.00% / 0.00% | 21.18% / 20.66% | 40.47% / 40.22% | 52.72% / 52.61% | +--------------+----------------+-----------------+---------------------+---------------------+ | 2.0 | 0.00% / 0.00% | 0.58% / 0.46% | 5.23% / 4.97% | 18.59% / 18.05% | +--------------+----------------+-----------------+---------------------+---------------------+

CIFAR10 Linf范数（ResNet50）：

• ε = 0.0（PyTorch预训练模型）
• ε = 8/255 <https://www.dropbox.com/s/c9qlt1lbdnu9tlo/cifar_linf_8.pt?dl=0>_

+--------------+-----------------+---------------------+ | CIFAR10 Linf-鲁棒准确率 | +--------------+-----------------+---------------------+ | | ε-训练 | +--------------+-----------------+---------------------+ | ε-测试 | 0 / 255 | 8 / 255 | +==============+=================+=====================+ | 0 / 255 | 95.25% / - | 87.03% / - | +--------------+-----------------+---------------------+ | 8 / 255 | 0.00% / 0.00% | 53.49% / 53.29% | +--------------+-----------------+---------------------+ | 16 / 255 | 0.00% / 0.00% | 18.13% / 17.62% | +--------------+-----------------+---------------------+

ImageNet L2范数（ResNet50）：

• ε = 0.0（PyTorch预训练模型）
• ε = 3.0 <https://www.dropbox.com/s/knf4uimlqsi1yz8/imagenet_l2_3_0.pt?dl=0>_

+--------------+-----------------+---------------------+ | ImageNet L2-鲁棒准确率 | +--------------+-----------------+---------------------+ | | ε-训练 | +--------------+-----------------+---------------------+ | ε-测试 | 0.0 | 3.0 | +==============+=================+=====================+ | 0.0 | 76.13% / - | 57.90% / - | +--------------+-----------------+---------------------+ | 0.5 | 3.35% / 2.98% | 54.42% / 54.42% | +--------------+-----------------+---------------------+ | 1.0 | 0.44% / 0.37% | 50.67% / 50.67% | +--------------+-----------------+---------------------+ | 2.0 | 0.16% / 0.14% | 43.04% / 43.02% | +--------------+-----------------+---------------------+ | 3.0 | 0.13% / 0.12% | 35.16% / 35.09% | +--------------+-----------------+---------------------+

ImageNet Linf范数（ResNet50）：

• ε = 0.0（PyTorch预训练模型）
• ε = 4 / 255 <https://www.dropbox.com/s/axfuary2w1cnyrg/imagenet_linf_4.pt?dl=0>_
• ε = 8 / 255 <https://www.dropbox.com/s/yxn15a9zklz3s8q/imagenet_linf_8.pt?dl=0>_

+--------------+-----------------+---------------------+---------------------+ | ImageNet Linf-鲁棒准确率 | +--------------+-----------------+---------------------+---------------------+ | | ε-训练 | +--------------+-----------------+---------------------+---------------------+ | ε-测试 | 0.0 | 4 / 255 | 8 / 255 | +==============+=================+=====================+=====================+ | 0 / 255 | 76.13% / - | 62.42% / - | 47.91% / - | +--------------+-----------------+---------------------+---------------------+ | 4 / 255 | 0.04% / 0.03% | 33.58% / 33.38% | 33.06% / 33.03% | +--------------+-----------------+---------------------+---------------------+ | 8 / 255 | 0.01% / 0.01% | 13.13% / 12.73% | 19.63% / 19.52% | +--------------+-----------------+---------------------+---------------------+ | 16 / 255 | 0.01% / 0.01% | 1.53% / 1.37% | 5.00% / 4.82% | +--------------+-----------------+---------------------+---------------------+

引用

如果您在研究中使用本库，请按以下方式引用：

.. code-block:: bibtex

@misc{robustness, title={Robustness (Python Library)}, author={Logan Engstrom and Andrew Ilyas and Hadi Salman and Shibani Santurkar and Dimitris Tsipras}, year={2019}, url={https://github.com/MadryLab/robustness} }

（您是否使用过该软件包并觉得有用？请告诉我们！）

维护者

• Andrew Ilyas <https://twitter.com/andrew_ilyas>_
• Logan Engstrom <https://twitter.com/logan_engstrom>_
• Shibani Santurkar <https://twitter.com/ShibaniSan>_
• Dimitris Tsipras <https://twitter.com/tsiprasd>_
• Hadi Salman <https://twitter.com/hadisalmanX>_

贡献者/提交者 '''''''''''''''''''''''

• 请参阅 此处 <https://github.com/MadryLab/robustness/pulse>_

Robustness 快速上手指南

robustness 是由 MIT MadryLab 开发的 PyTorch 工具包，旨在让神经网络的训练、评估和探索（特别是对抗鲁棒性研究）变得更加灵活和简单。它支持标准训练和对抗训练，并提供丰富的输入空间操作功能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux 或 macOS (Windows 支持可能受限，推荐 Linux)
• Python: 建议 Python 3.6+
• 核心依赖:
  • PyTorch: 必须安装带有 CUDA 支持 的版本。
  • cox: 该库依赖 cox 进行日志记录和结果存储（通常会自动安装）。
• 硬件: 推荐使用 NVIDIA GPU 以加速训练和对抗样本生成。

安装步骤

您可以直接通过 pip 进行安装。为了提高下载速度，国内用户建议使用清华或阿里镜像源。

方式一：使用国内镜像源（推荐）

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

方式二：标准安装

pip install robustness

安装完成后，您可以访问官方文档获取更多细节：https://robustness.readthedocs.io

基本使用

robustness 提供了两种主要的使用方式：命令行接口 (CLI) 和 Python API。

1. 命令行快速训练 (CLI)

这是最简单的方式，无需编写代码即可启动标准训练或对抗训练。以下示例展示如何在 CIFAR-10 数据集上使用 ResNet18 进行标准训练（非对抗）：

python -m robustness.main --dataset cifar --data /path/to/cifar \
   --adv-train 0 --arch resnet18 --out-dir /logs/checkpoints/dir/

• --dataset: 指定数据集 (如 cifar, imagenet)。
• --data: 本地数据集路径。
• --adv-train: 设为 0 表示标准训练，设为 1 表示开启对抗训练。
• --arch: 模型架构 (如 resnet18, resnet50)。
• --out-dir: 模型检查和日志输出目录。

2. Python API 使用示例

如果您需要更灵活的控制（如自定义攻击参数、加载预训练模型），可以使用 Python API。以下示例演示了如何加载模型并生成有目标的对抗样本：

import torch as ch
from robustness.datasets import CIFAR
from robustness.model_utils import make_and_restore_model

# 1. 初始化数据集
ds = CIFAR('/path/to/cifar')

# 2. 加载模型 (可以是随机初始化或加载预训练权重)
model, _ = make_and_restore_model(arch='resnet50', dataset=ds, 
             resume_path='/path/to/model', state_dict_path='model')
model.eval()

# 3. 配置对抗攻击参数 (L-inf PGD)
attack_kwargs = {
   'constraint': 'inf',      # 约束类型: L-inf
   'eps': 0.05,              # 扰动上限
   'step_size': 0.01,        # 步长
   'iterations': 100,        # 迭代次数
   'targeted': True,         # 是否为有目标攻击
   'custom_loss': None       # 使用默认交叉熵损失
}

# 4. 获取测试数据
_, test_loader = ds.make_loaders(workers=0, batch_size=10)
im, label = next(iter(test_loader))

# 生成目标标签 (将真实标签随机改为其他类别)
target_label = (label + ch.randint_like(label, high=9)) % 10

# 5. 执行攻击并获取对抗样本
# adv_out: 模型对对抗样本的输出; adv_im: 生成的对抗图像
adv_out, adv_im = model(im, target_label, make_adv=True, **attack_kwargs)

3. 高级训练脚本 (使用 cox 日志系统)

对于需要自定义训练循环、损失函数或详细日志记录的研究项目，可以结合 cox 库进行编程式训练：

from robustness import model_utils, datasets, train, defaults
from robustness.datasets import CIFAR
from cox.utils import Parameters
import cox.store

# 初始化数据集和模型
ds = CIFAR('/path/to/cifar')
m, _ = model_utils.make_and_restore_model(arch='resnet50', dataset=ds)
train_loader, val_loader = ds.make_loaders(batch_size=128, workers=8)

# 创建日志存储
out_store = cox.store.Store("train_out")

# 配置训练参数 (此处示例为对抗训练)
train_kwargs = {
    'out_dir': "train_out",
    'adv_train': 1,           # 开启对抗训练
    'constraint': '2',        # L2 约束
    'eps': 0.5,
    'attack_lr': 1.5,
    'attack_steps': 20
}
train_args = Parameters(train_kwargs)

# 填充默认缺失参数
train_args = defaults.check_and_fill_args(train_args, defaults.TRAINING_ARGS, CIFAR)
train_args = defaults.check_and_fill_args(train_args, defaults.PGD_ARGS, CIFAR)

# 开始训练
train.train_model(train_args, m, (train_loader, val_loader), store=out_store)

提示: 更多预训练模型（涵盖不同数据集、范数约束和 $\epsilon$ 值）可在项目 README 的 "Pretrained models" 部分找到下载链接。使用时请注意对应的 PyTorch 版本兼容性（推荐 torch==1.1.0+ 用于加载旧版检查点，新版通常兼容良好）。