.. raw:: html

.. image:: https://badge.fury.io/py/foolbox.svg :target: https://badge.fury.io/py/foolbox

.. image:: https://readthedocs.org/projects/foolbox/badge/?version=latest :target: https://foolbox.readthedocs.io/en/latest/

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/ambv/black

.. image:: https://joss.theoj.org/papers/10.21105/joss.02607/status.svg :target: https://doi.org/10.21105/joss.02607

=============================================================================================================================== Foolbox：用于在 PyTorch、TensorFlow 和 JAX 中基准机器学习模型鲁棒性的快速对抗攻击工具

Foolbox <https://foolbox.jonasrauber.de>_ 是一个 Python 库，可让您轻松地对深度神经网络等机器学习模型执行对抗攻击。它基于 EagerPy 构建，原生支持 PyTorch <https://pytorch.org>、TensorFlow <https://www.tensorflow.org> 和 JAX <https://github.com/google/jax>_ 中的模型。

🔥 设计

Foolbox 3 已经从头重写， 使用 EagerPy <https://github.com/jonasrauber/eagerpy>_ 替代 NumPy， 以实现对 PyTorch、TensorFlow 和 JAX 中开发模型的原生性能， 且仅需一套代码库即可完成，无需重复编写。

• 原生性能：Foolbox 3 基于 EagerPy 构建，在 PyTorch、TensorFlow 和 JAX 中原生运行，并真正支持批量处理。
• 最先进攻击：Foolbox 提供大量最先进的基于梯度和基于决策的对抗攻击方法。
• 类型检查：借助 Foolbox 中丰富的类型注解，在运行代码之前即可捕获错误。

📖 文档

• 指南：开始使用 Foolbox 的最佳地点是官方 指南 <https://foolbox.jonasrauber.de>_。
• 教程：如果您正在寻找教程，请查看此 Jupyter 笔记本 <https://github.com/jonasrauber/foolbox-native-tutorial/blob/master/foolbox-native-tutorial.ipynb>_ |colab|。
• 文档：API 文档可在 ReadTheDocs <https://foolbox.readthedocs.io/en/stable/> 上找到。

.. |colab| image:: https://colab.research.google.com/assets/colab-badge.svg :target: https://colab.research.google.com/github/jonasrauber/foolbox-native-tutorial/blob/master/foolbox-native-tutorial.ipynb

🚀 快速入门

.. code-block:: bash

pip install foolbox

Foolbox 经过 Python 3.8 及更高版本的测试；不过，它很可能也能在 3.6 至 3.8 版本中正常工作。要将其与 PyTorch <https://pytorch.org>、TensorFlow <https://www.tensorflow.org> 或 JAX <https://github.com/google/jax>_ 一起使用，需要分别安装相应的框架。这些框架并未被声明为依赖项，因为并非所有人都希望同时使用并安装它们，而且其中一些软件包针对不同的架构和 CUDA 版本有不同的构建版本。除此之外，所有必要的依赖项都会自动安装。

我们当前用于测试的版本可在下方的 兼容性部分 <#-compatibility>_ 中查看，但通常情况下，更新的版本也应能正常工作。

🎉 示例

.. code-block:: python

import foolbox as fb

model = ... fmodel = fb.PyTorchModel(model, bounds=(0, 1))

attack = fb.attacks.LinfPGD() epsilons = [0.0, 0.001, 0.01, 0.03, 0.1, 0.3, 0.5, 1.0] _, advs, success = attack(fmodel, images, labels, epsilons=epsilons)

更多示例可在 examples <./examples/> 文件夹中找到，例如完整的 ResNet-18 示例 <./examples/single_attack_pytorch_resnet18.py>_。

📄 引用

如果您在工作中使用了 Foolbox，请引用我们的 JOSS 关于 Foolbox Native（即 Foolbox 3.0）的文章 <https://doi.org/10.21105/joss.02607>_ 以及我们在 ICML 研讨会发表的关于 Foolbox 的论文 <https://arxiv.org/abs/1707.04131>_，引用格式如下：

.. code-block::

@article{rauber2017foolboxnative, doi = {10.21105/joss.02607}, url = {https://doi.org/10.21105/joss.02607}, year = {2020}, publisher = {The Open Journal}, volume = {5}, number = {53}, pages = {2607}, author = {Jonas Rauber 和 Roland Zimmermann、Matthias Bethge、Wieland Brendel}, title = {Foolbox Native：用于在 PyTorch、TensorFlow 和 JAX 中基准机器学习模型鲁棒性的快速对抗攻击工具}, journal = {Journal of Open Source Software} }

.. code-block::

@inproceedings{rauber2017foolbox, title={Foolbox：用于基准机器学习模型鲁棒性的 Python 工具箱}, author={Rauber, Jonas 和 Brendel, Wieland、Bethge, Matthias}, booktitle={Reliable Machine Learning in the Wild Workshop，第 34 届国际机器学习大会}, year={2017}, url={http://arxiv.org/abs/1707.04131}, }

👍 贡献

我们欢迎各种形式的贡献，请参阅我们的 开发指南 <https://foolbox.jonasrauber.de/guide/development.html>。特别是，欢迎您贡献 新的对抗攻击 <https://foolbox.jonasrauber.de/guide/adding_attacks.html>。如果您想提供帮助，也可以查看标记为 欢迎贡献 <https://github.com/bethgelab/foolbox/issues?q=is%3Aopen+is%3Aissue+label%3A%22contributions+welcome%22>_ 的问题。

💡 有问题吗？

如果您有任何问题或需要帮助，欢迎在 GitHub 上提交一个问题。待 GitHub Discussions 公开可用后，我们将切换到该平台。

💨 性能

Foolbox 3.0 比 Foolbox 1 和 2 快得多。基本的 性能比较_ 可在 performance 文件夹中找到。

🐍 兼容性

我们目前使用的版本如下：

• PyTorch 1.10.1
• TensorFlow 2.6.3
• JAX 0.2.517
• NumPy 1.18.1

.. _性能比较: performance/README.md

Foolbox 快速上手指南

Foolbox 是一个用于对机器学习模型（如深度神经网络）进行对抗攻击的 Python 库。Foolbox 3 基于 EagerPy 重构，原生支持 PyTorch、TensorFlow 和 JAX，无需代码复制即可在同一代码库中实现高性能攻击。

环境准备

系统要求

• Python 版本：推荐 Python 3.8 及以上（理论上兼容 3.6 - 3.8）。
• 操作系统：Linux, macOS, Windows。

前置依赖

Foolbox 本身不强制捆绑深度学习框架，你需要根据项目需求单独安装以下任一框架：

• PyTorch
• TensorFlow
• JAX

注意：由于不同架构和 CUDA 版本的构建差异，请前往各框架官网获取适合你环境的安装命令。

安装步骤

使用 pip 安装 Foolbox 核心库：

pip install foolbox

如果你希望使用国内镜像源加速安装，推荐使用清华源：

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

安装完成后，确保已单独安装了对应的深度学习框架（例如 pip install torch 或 pip install tensorflow）。

基本使用

以下是一个基于 PyTorch 的最简使用示例，演示如何加载模型并执行 LinfPGD 对抗攻击。

代码示例

import foolbox as fb

# 1. 加载你的预训练模型 (此处为占位符，需替换为实际模型)
model = ... 

# 2. 将模型包装为 Foolbox 模型，指定输入数据范围 (例如归一化到 0-1)
fmodel = fb.PyTorchModel(model, bounds=(0, 1))

# 3. 选择攻击算法 (此处为 Linf 范数下的 PGD 攻击)
attack = fb.attacks.LinfPGD()

# 4. 定义扰动强度列表 (epsilons)
epsilons = [0.0, 0.001, 0.01, 0.03, 0.1, 0.3, 0.5, 1.0]

# 5. 执行攻击
# images: 输入图像张量, labels: 真实标签张量
_, advs, success = attack(fmodel, images, labels, epsilons=epsilons)

说明

• bounds=(0, 1)：表示模型输入数据的像素值范围，请根据你的预处理流程调整（如 (-1, 1)）。
• success：返回一个布尔数组，指示在每个 epsilon 强度下攻击是否成功。
• 更多完整示例（如 ResNet-18 实战）可参考官方仓库的 examples 文件夹。