# 开始使用 Canary Library

欢迎来到更简单的Canary模型对抗鲁棒性评估框架学习教程！

在本章节中，我们将使用 Canary、Canary Library和 PyTorch 构建一个简单的模型鲁棒性测试任务。我们在Canary Library提供了大量攻击方法和预训练模型，并确保它们可用，这将极大简化研究人员的工作量，研究人员再也不用四处寻找或者复现经典的代码了（Really？）。

让我们开始吧！

# 第0步：准备

在开始编写任何实际代码之前，让我们确保我们已经做好了一切必要的准备。

# 安装依赖项

我们安装 PyTorch (和Torchvision) 和 Canary 所需的软件包：

pip install torch torchvision torchaudio
pip install -r requirement.txt

* 为确保Canary Library项目可用，我们推荐PyTorch的版本应至少 ≥ 2.0.0

# 准备数据集与模型

使用Canary Library，如果你只是想评估一下你的攻击方法是否有效，或者只是单纯想体验一下对抗攻击过程，你就无需准备任何数据集与模型。

# 准备对抗攻击(Adversarial Attack)方法

使用Canary Library，如果你只是想评估一下你的模型是否足够对抗鲁棒，或者只是单纯想体验一下对抗攻击过程，你就无需准备任何对抗攻击方法。

好了，我们的准备工作就是这么轻松愉快（且高效）~

# 第1步：配置Canary

# 新建工程并构建目录

首先，我们新建一个目录结构：

.
├── run.py
├── config.json
└── Canary_SEFI

# 引入Canary Library

👇请将该部分存放在run.py中👇

我们首先引入必要依赖，并加载Canary Library模型和攻击方法至Canary：

import random
import numpy as np
from canary_sefi.core.function.enum.multi_db_mode_enum import MultiDatabaseMode
from canary_sefi.core.function.helper.multi_db import use_multi_database
from canary_sefi.core.function.helper.recovery import global_recovery
from canary_sefi.service.security_evaluation import SecurityEvaluation
from canary_sefi.task_manager import task_manager

from canary_sefi.core.component.component_manager import SEFI_component_manager

# 加载Canary Lib中的模型
from canary_lib import canary_lib_model
SEFI_component_manager.add_all(canary_lib_model)

# 加载Canary Lib中的攻击方法
from canary_lib import canary_lib_attacker
SEFI_component_manager.add_all(canary_lib_attacker)

接下来，我们构建配置：

example_config = {
    # 数据集配置
    "dataset_size": 10,  # 用于测试的图片数量
    "dataset": {
        "dataset_name": "CIFAR10", # 数据集名称，此处是Torchvision定义的数据集会自动加载
        "dataset_type": "TEST", # 数据集类型
        "n_classes": 10, # 数据集类数量
        "is_gray": False, # 数据集是否是灰度图
    },
    # 数据集随机选取图片的种子
    "dataset_seed": random.Random().randint(10000, 100000), 
    # 模型配置
    "model_list": [
        "ResNet(CIFAR-10)"  # 模型名，本例中模型名是 Canary Lib 中的模型 ResNet(CIFAR-10)
    ],
    "inference_batch_config": {  # 模型预测的 Batch 数
        "ResNet(CIFAR-10)": 5,
    },
    # 攻击方法配置
    "attacker_list": {
        "I_FGSM": [  # 攻击方法名，本例中攻击方法名是 Canary Lib 中的攻击方法 I_FGSM
            "ResNet(CIFAR-10)",  # 攻击方法攻击的目标模型
        ],
    },
    "attacker_config": {  # 攻击配置参数
        "I_FGSM": {  # 这是 Canary Lib 中的攻击方法 I_FGSM 推荐的攻击参数
            "clip_min": 0,
            "clip_max": 1,
            "eps_iter": 2.5 * ((1 / 255) / 100),
            "nb_iter": 100,
            "norm": np.inf,
            "attack_type": "UNTARGETED",
            "epsilon": 1 / 255,
        }
    },
    "adv_example_generate_batch_config": {  # 模型生成对抗样本的 Batch 数
        "I_FGSM": {
            "ResNet(CIFAR-10)": 5,
        }
    },
    # 转移测试模式：本例中我们只选择了一个模型，不存在转移测试，因此为NOT
    "transfer_attack_test_mode": "NOT"
}

# 第2步：Canary启动

我们需要更改一下Canary的系统配置，并将以下内容存入 config.json（如果没有）。在本例中，我们只需要关注datasetPath和baseTempPath，它们分别是数据集路径和临时文件路径。

{
  "appName": "CANARY Test",
  "appDesc": "This is an example program to start test using Canary SEFI",
  "datasetPath": "/workplace/dataset/",
  "baseTempPath": "/workplace/temp/",
  "centerDatabasePath": "/workplace/temp/",
  "system": {
    "limited_read_img_size": 900,
    "use_file_memory_cache": true,
    "save_fig_model": "save_img_file"
  }
}

最后，我们使用该配置启动Canary运行评估测试：

if __name__ == "__main__":
    # 初始化任务，使用显卡CUDA设备运行任务
    task_manager.init_task(show_logo=True, run_device="cuda")

    # 设置当前模式为简单数据库模式（非高级用户请勿修改此设置）
    use_multi_database(mode=MultiDatabaseMode.SIMPLE)

    # 使用配置构建评估任务并启动
    security_evaluation = SecurityEvaluation(example_config)
    security_evaluation.attack_full_test()

# 最后提示

恭喜，您刚刚使用I-FGSM对ResNet(CIFAR-10)模型进行了一次对抗攻击，并评估了该模型的鲁棒性与攻击方法的有效性。相较于上一章节，您会发现本章的教程如此简单，您既没有自行实现、集成、训练模型，也没有尝试复现攻击算法，但Canary依旧完成了和此前相同的工作。

Canary Lib就是这样一个库，旨在最大程度的减少您不必要的工作量。使得研究人员可以将目光集中在攻击算法的实现、模型鲁棒性的评估与增强上，而不必因为对照试验而心烦意乱。

本章由 孙家正(Jiazheng Sun) 编写

← 开始使用 Canary 安装 Canary →