CleverHans (latest release: v4.0.0)

Этот репозиторий содержит исходный код CleverHans — библиотеки Python для оценки уязвимости систем машинного обучения к состязательным примерам. Подробнее о таких уязвимостях можно узнать в сопутствующем блоге.

Библиотека CleverHans находится в постоянном развитии и всегда рада вкладу в виде новейших атак и защит. В частности, мы всегда приветствуем помощь в решении открытых вопросов.

Начиная с версии v4.0.0, CleverHans поддерживает 3 фреймворка: JAX, PyTorch и TF2. В настоящее время мы в первую очередь реализуем атаки в PyTorch, но очень приветствуем вклад для всех трёх фреймворков. В версиях v3.1.0 и более ранних CleverHans поддерживал TF1; код для v3.1.0 можно найти в cleverhans_v3.1.0/ или переключившись на более ранний релиз на GitHub.

Библиотека сосредоточена на предоставлении эталонных реализаций атак против моделей машинного обучения, чтобы помочь в сравнительном тестировании моделей на устойчивость к состязательным примерам.

Структура каталогов следующая: cleverhans/ содержит реализации атак, tutorials/ — скрипты, демонстрирующие возможности CleverHans, а defenses/ — реализации защит. Каждый фреймворк имеет свой подкаталог внутри этих папок, например cleverhans/jax.

Настройка CleverHans

Зависимости

Эта библиотека использует Jax, PyTorch или TensorFlow 2 для ускорения графовых вычислений, выполняемых многими моделями машинного обучения. Поэтому установка одной из этих библиотек является обязательным условием.

Установка

После того как зависимости установлены, вы можете установить CleverHans с помощью pip или клонировав этот репозиторий на GitHub.

Установка через pip

Если вы устанавливаете CleverHans с помощью pip, выполните следующую команду:

pip install cleverhans

Будет установлена последняя версия, загруженная на Pypi. Если вместо этого вы хотите установить самую свежую версию, используйте:

pip install git+https://github.com/cleverhans-lab/cleverhans.git#egg=cleverhans

Установка для разработки

Если вы хотите сделать редактируемую установку CleverHans, чтобы иметь возможность разрабатывать библиотеку и вносить изменения обратно, сначала сделайте форк репозитория на GitHub, а затем клонируйте свой форк в каталог по вашему выбору:

git clone https://github.com/<your-org>/cleverhans

Затем вы можете установить локальный пакет в «редактируемом» режиме, чтобы добавить его в ваш PYTHONPATH:

cd cleverhans
pip install -e .

Поддерживаемые в настоящее время конфигурации

Хотя CleverHans, вероятно, будет работать и на многих других конфигурациях машин, в настоящее время мы тестируем его с Python 3.6, Jax 0.2, PyTorch 1.7 и Tensorflow 2.4 на Ubuntu 18.04 LTS (Bionic Beaver).

Получение поддержки

Если у вас есть запрос на поддержку, пожалуйста, задайте вопрос на StackOverflow, а не открывайте issue в трекере GitHub. Трекер issues на GitHub следует использовать только для сообщения об ошибках или запросов новых функций.

Участие в разработке

Вклад приветствуется! Чтобы ускорить процесс рецензирования кода, мы просим:

• Новые проекты и функции координировать на дискуссионном форуме.
• При внесении вклада в код CleverHans следует придерживаться стиля кодирования Black в ваших pull request.
• Мы не принимаем pull request, добавляющие git-подмодули, из-за проблем, возникающих при поддержке git-подмодулей.

Исправления ошибок могут быть инициированы через pull request на GitHub.

Учебные пособия: каталог tutorials

Чтобы помочь вам начать работу с функциями, предоставляемыми этой библиотекой, папка tutorials/ содержит следующие учебные пособия:

• MNIST с FGSM и PGD (jax, tf2): это руководство рассказывает, как обучить модель MNIST и создать состязательные примеры с помощью метода быстрого градиентного знака и проективного градиентного спуска.
• CIFAR10 с FGSM и PGD (pytorch, tf2): это руководство рассказывает, как обучить модель CIFAR10 и создать состязательные примеры с помощью метода быстрого градиентного знака и проективного градиентного спуска.

ПРИМЕЧАНИЕ: за учебными пособиями тщательно следят, в том смысле, что мы используем непрерывную интеграцию, чтобы гарантировать их работоспособность. Они не считаются частью API и могут быть изменены в любое время без предупреждения. Вам не следует писать сторонний код, который импортирует учебные пособия, и ожидать, что интерфейс не сломается. Только основная библиотека подлежит нашему правилу шестимесячного предупреждения об устаревании интерфейса.

ПРИМЕЧАНИЕ: пожалуйста, создайте тему на дискуссионном форуме, прежде чем писать новое учебное пособие. Поскольку каждое новое руководство включает большой объём дублирующегося кода по сравнению с существующими руководствами, и поскольку каждая строка кода требует постоянного тестирования и сопровождения бессрочно, мы в целом предпочитаем не добавлять новые руководства. Каждое учебное пособие должно демонстрировать совершенно иной способ использования библиотеки. Просто использование другой атаки, модели или набора данных недостаточно для оправдания поддержки параллельного руководства.

Примеры: каталог examples

Папка examples/ содержит дополнительные скрипты, демонстрирующие различные способы использования библиотеки CleverHans, или помогающие начать участвовать в различных состязаниях по состязательным примерам. Мы не обеспечиваем почти такой же уровень постоянного сопровождения или поддержки для этого каталога, как для остальной части библиотеки, и если код здесь сломается, мы можем просто удалить его без предупреждения.

Поскольку мы недавно прекратили поддержку TF1, каталог examples/ сейчас пуст, но вы можете отправить свои варианты использования через pull request :)

Старые примеры для CleverHans v3.1.0 и более ранних версий можно найти в cleverhans_v3.1.0/examples/.

Отчёт о результатах тестирования

При составлении отчётов о результатах тестирования, пожалуйста:

• Используйте версионированный релиз CleverHans. Список выпущенных версий можно найти здесь.
• Либо используйте последнюю версию, либо, если вы сравниваете с более ранней публикацией, используйте ту же версию, что и более ранняя публикация.
• Укажите, какой метод атаки использовался.
• Укажите все переменные конфигурации, использованные для определения поведения атаки.

Например, вы можете указать: «Мы оценили устойчивость нашего метода к состязательной атаке, используя v4.0.0 CleverHans. На тестовом наборе, модифицированном с помощью FastGradientMethod с максимальной нормой eps 0,3, мы получили точность на тестовом наборе 71,3%».

Цитирование этой работы