# advGAN

**Repository Path**: Solbrilo/adv-gan

## Basic Information

- **Project Name**: advGAN
- **Description**: 专业实训项目，仅供学习
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-22
- **Last Updated**: 2026-06-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# GE-AdvGAN：基于梯度编辑的对抗生成模型

[![preprint](https://img.shields.io/static/v1?label=arXiv&message=2401.06031&color=B31B1B)](https://arxiv.org/abs/2401.06031)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Venue:SDM 2024](https://img.shields.io/badge/Venue-SDM%202024-007CFF)](https://www.siam.org/conferences/cm/conference/sdm24)
</div>

<table align="center">
  <tr>
    <td align="center">
      <img src="./flowchart.png" alt="GE-AdvGAN 框架图" style="width: 600px;"/>
      <br>
      <em style="font-size: 18px;"><strong style="font-size: 18px;">图 1：</strong>GE-AdvGAN 框架示意图</em>
    </td>
  </tr>
</table>

本仓库是论文 [GE-AdvGAN: Gradient Editing-based Adversarial Generative Model](https://arxiv.org/abs/2401.06031) 的实现代码。

在原始训练与评估代码的基础上，仓库现在还包含一套已经可以本地运行的 Web 对抗攻击演示系统，适合用于课程展示、内部汇报、毕业设计原型和服务器部署演示。

## 一、仓库当前包含的内容

当前仓库主要分为两部分：

1. 原始 GE-AdvGAN 训练与实验复现代码
2. 面向演示部署的推理与 Web 服务代码

其中 Web 演示系统当前支持：

- 上传单张图片
- 自动发现仓库中的生成器 checkpoint
- 选择识别模型
- 设置推理阶段攻击参数
- 可选自动裁剪 1:1 输入区域，避免非方图被直接拉伸
- 生成对抗样本
- 可选降噪输出，通过候选扰动搜索降低明显条纹
- 展示攻击前后识别结果
- 展示攻击成功率、置信度变化、扰动强度、视觉降幅等指标
- 下载本次生成的图像、JSON 报告与 TXT 报告
- 自动清理历史运行产物

## 二、优化后的项目结构

为了让仓库更清晰，当前结构做了两点整理：

1. 将运行脚本集中到 `scripts/` 目录，根目录保留兼容入口
2. 将说明文档集中到 `docs/` 目录，减少根目录文档堆积

主要目录如下：

```text
advGAN_pytorch/
|-- dataset/                  # 数据集与标注
|-- docs/                     # 说明文档
|   |-- DEPLOY.md             # 部署说明
|   |-- FRONTEND_BACKEND_SETUP.md
|   `-- MODEL_SHARING.md
|-- models/                   # 迁移评估模型参数（tf_*.npy）
|-- output/                   # 训练输出与生成器权重
|-- scripts/                  # 训练/评估/工具脚本
|   |-- run_baseline.sh
|   |-- run_GE.sh
|   `-- run_deploy_eval.sh
|-- torch_nets/               # 迁移模型定义
|-- visual_search.py          # 视觉候选搜索与条纹评分工具
|-- webapp/                   # Web 演示服务
|   |-- runtime/              # 运行时结果目录
|   |-- static/               # 前端静态页面
|   |-- config.py             # Web 配置
|   |-- inference.py          # 单图推理与对抗样本生成
|   `-- server.py             # FastAPI 服务
|-- deploy_model.py           # 离线部署评估脚本
|-- main.py                   # 训练入口
|-- run_webapp.py             # Web 服务启动入口
|-- requirements-common.txt   # 通用依赖
|-- requirements-web.txt      # Web 依赖
`-- README.md
```

补充说明：

- 根目录的 `run_baseline.sh`、`run_GE.sh`、`run_deploy_eval.sh` 仍然可用，它们会转发到 `scripts/` 中的正式脚本。
- `webapp/runtime/`、`__pycache__/`、日志目录和部署测试输出已经加入忽略规则，避免运行产物污染仓库。

## 三、环境要求

原始论文代码建议优先使用较稳定的旧版环境：

- Python `3.8` 或 `3.9`
- PyTorch `1.8`
- `pretrainedmodels==0.7.4`
- NumPy `1.19+`
- Pandas `1.2+`

先安装通用依赖：

```bash
pip install -r requirements-common.txt
```

如果你要运行 Web 演示服务，再安装额外依赖：

```bash
pip install -r requirements-web.txt
```

## 四、模型与权重

原始实验所需的预训练模型下载地址：

[下载预训练模型](https://drive.google.com/file/d/1t0eNl5cgySR8Dg5Fpq04mWuoiY7yQEB4/view?usp=sharing)

对于 Web 演示和离线推理，最关键的是训练得到的生成器权重，例如：

- `output/netG_epoch_20.pth`
- `output/netG_epoch_40.pth`
- `output/netG_epoch_60.pth`
- `output/netG_epoch_60_essay.pth`
- `output/netG_epoch_60_mildvisual.pth`
- `output/netG_epoch_60_v3.pth`

Web 页面会自动扫描仓库中的兼容 `.pth` 生成器文件，并在页面中供你选择。当前消融结果推荐优先使用 `output/netG_epoch_60_mildvisual.pth`；如果希望 Web 默认选中它，可以设置环境变量 `ADVGAN_DEFAULT_GENERATOR=output/netG_epoch_60_mildvisual.pth`。

### 当前低条纹优化路线

本仓库当前把“攻击能力”和“视觉影响”分成两层处理：

1. 训练端推荐使用 `legacy_mild_visual` 配置，在 legacy 生成器上加入轻量 L1、顶格像素、bandpass 和 flat-area 视觉正则。
2. 推理端提供视觉候选搜索，对已有 checkpoint 也能使用，并在 transfer guard 约束下选择更低视觉评分的候选。

注意事项：

- 当前最优 raw checkpoint 是 `output/netG_epoch_60_mildvisual.pth`。
- `output/netG_epoch_60_v3.pth`、`output/*_v2.pth` 这类权重仍可继续用于对比或 Web 演示，但当前消融不建议把它们作为最终低条纹主结果。
- Web 演示中的“降噪输出”默认使用 `wide` 候选预设和 `stripe_score`，并使用当前所选识别模型做快速 guard，适合交互演示。
- 严格的 9 个 TensorFlow 迁移模型 ASR 保底，应使用 `deploy_model.py --visual-search transfer_guard` 离线生成和评估。
- 如果某个低条纹候选会破坏 base 已成功的攻击，候选搜索会回退到 base 输出，优先保证攻击效果。
- 在攻击成功边界附近，Web 端会使用贴近 base 的 `blend` 过渡候选减少“扰动强度跨过某一点后条纹突然变重”的硬切换；这个边界由图片、识别模型、`epsilon_linf_255` 和 `perturbation_scale` 共同决定，不是固定数值。

### 生成器结构更新（Checkerboard 修复）

为减轻训练后对抗样本中常见的棋盘格阴影，当前仓库已经对生成器结构做了针对性调整：

- `models.py` 中的生成器 decoder 已由 `ConvTranspose2d` 改为 `bilinear upsample + Conv2d + ReflectionPad2d`
- 新版生成器直接输出与输入同尺寸的扰动，不再依赖 `[:, :, :-1, :-1]` 这类手工裁边
- `ResnetBlock` 默认归一化已统一为 `InstanceNorm2d`，以减少生成器内部风格不一致带来的伪纹理

兼容性说明：

- `deploy_model.py` 与 `webapp/inference.py` 仍兼容旧版生成器 checkpoint
- 旧权重可以继续用于离线评估和 Web 演示
- 当前消融显示，legacy 架构在迁移 ASR 上更稳；新版 current 生成器仍可作为 checkerboard 修复路线继续实验，但不作为当前推荐主模型

### 对象存储下载（团队协作）

为了避免大文件进入 Git 历史，推荐将权重放到对象存储，并通过清单脚本下载。

1. 维护者准备清单（示例）：

```bash
python scripts/make_model_manifest.py --base-url https://YOUR_STORAGE_HOST/advgan-artifacts/
```

2. 组员按清单下载并校验：

```bash
python scripts/download_models.py --manifest scripts/model_manifest.json
```

3. 仅验证本地文件完整性：

```bash
python scripts/download_models.py --manifest scripts/model_manifest.json --check-only
```

如果你当前使用的是示例清单，也可以将 `--manifest` 换成 `scripts/model_manifest.example.json`。  
更多说明见 [docs/MODEL_SHARING.md](./docs/MODEL_SHARING.md)。

## 五、训练与实验运行

### 1. Baseline 实验

```bash
bash scripts/run_baseline.sh
```

或者继续沿用原来的根目录入口：

```bash
bash run_baseline.sh
```

### 2. GE-AdvGAN 实验

```bash
bash scripts/run_GE.sh
```

或者：

```bash
bash run_GE.sh
```

如果你需要自定义参数，可以直接修改 `scripts/` 下对应脚本，或者手动运行 `main.py`。

### 3. 推荐的低条纹训练命令

如果目标是降低黑白条纹，同时尽量保留迁移攻击能力，当前消融后推荐使用 `legacy_mild_visual` 配置重新训练：

```bash
python main.py --exp_name GE_legacy_mild_visual --model inceptionv3 \
  --generator_arch legacy \
  --save_path output/ablation/GE_legacy_mild_visual/ \
  --adv_lambda 10 --pert_lambda 1 --N 10 --rho 0.5 --sigma 16 --epsilon 16 \
  --smooth_kernel_size 3 --tv_lambda 0.05 --hf_lambda 0.01 \
  --l1_lambda 0.001 --actual_saturation_lambda 0.0005 \
  --actual_saturation_threshold 14 --bandpass_lambda 0.003 --flat_area_lambda 0.001 \
  --visual_warmup_epochs 20 --attack_margin 2.0 --success_reg_only
```

关键参数说明：

- `--generator_arch legacy`：当前消融里 legacy 生成器的迁移 ASR 明显稳定于 current 生成器。
- `--l1_lambda`：轻量压低平均扰动强度。
- `--actual_saturation_lambda`：惩罚实际扰动 `adv_images - x` 顶到 `epsilon` 附近，而不是只看 clamp 前扰动。
- `--bandpass_lambda`：压制 `smooth3(diff) - smooth21(diff)` 这类中频条纹能量。
- `--flat_area_lambda`：在平坦区域更严格地惩罚扰动，减少背景、天空、墙面等位置的可见痕迹。
- `--visual_warmup_epochs 20`：前 20 个 epoch 逐步打开视觉正则，避免训练一开始就把攻击压没。
- `--attack_margin 2.0`：让源模型攻击达到一定 margin 后再更积极地让视觉正则接管。
- `--success_reg_only`：只对已经攻击成功的样本加强视觉约束，降低 ASR 被正则拖垮的风险。

训练日志中会额外输出 `loss_flat_area`、`loss_actual_saturation`、`loss_bandpass` 和 `visual_factor`，用于判断视觉正则是否开始生效。

本次 5 组消融的结论是：`legacy_mild_visual` 在 100 张、4 个迁移模型复核中取得最高平均 ASR，同时视觉指标明显优于 GE-essay 参考权重。`current_control` 和此前 `v3/current` 权重迁移 ASR 明显偏低，暂不作为最终主模型。

### 4. 消融结果摘要

本次消融统一使用 `epsilon=16`、`smooth_kernel_size=3`。第一阶段使用 100 张图片和 2 个迁移模型；第二阶段对候选模型使用 100 张图片和 4 个迁移模型复核。

| checkpoint | 2 模型平均 ASR | L1 | 顶格像素比例 | Stripe |
|---|---:|---:|---:|---:|
| `output/netG_epoch_60_essay.pth` | 91.0% | 13.37 | 69.6% | 61.34 |
| `output/netG_epoch_60_legacycontrol.pth` | 92.5% | 11.40 | 47.9% | 47.55 |
| `output/netG_epoch_60_legacysat.pth` | 90.5% | 11.62 | 51.0% | 49.27 |
| `output/netG_epoch_60_bandpass.pth` | 93.0% | 12.41 | 58.2% | 52.70 |
| `output/netG_epoch_60_mildvisual.pth` | **95.5%** | **11.33** | **47.2%** | **47.81** |
| `output/netG_epoch_60_currentcontrol.pth` | 67.5% | 13.95 | 75.3% | 62.45 |

4 模型复核中，`output/netG_epoch_60_mildvisual.pth` 的平均迁移 ASR 为 `88.5%`，高于 GE-essay 参考权重的 `84.5%`。因此当前推荐：

- raw checkpoint：`output/netG_epoch_60_mildvisual.pth`
- 最干净展示输出：在该 checkpoint 上再运行 `transfer_guard + wide`

## 六、离线部署评估

仓库中已经提供离线推理与评估脚本 `deploy_model.py`，适合在正式部署前做 smoke test。

示例：

```bash
python deploy_model.py \
  --generator-path output/netG_epoch_60.pth \
  --output-dir deploy_outputs/ge_demo_smoke \
  --max-samples 20
```

它会：

- 读取 `dataset/images.csv`
- 从 `dataset/images/` 中加载图片
- 生成对抗样本
- 输出 `deployment_metrics.json`

### 视觉候选搜索与迁移 guard

如果要在离线阶段对已有 checkpoint 做低条纹后处理，并且希望 9 个 TensorFlow 迁移模型逐模型 ASR 尽量不低于 base，可以开启：

```bash
python deploy_model.py \
  --generator-path output/netG_epoch_60_mildvisual.pth \
  --baseline-generator-path output/netG_epoch_60_mildvisual.pth \
  --output-dir deploy_outputs/mildvisual_wide_transfer_guard \
  --report-path deploy_outputs/mildvisual_wide_transfer_guard.json \
  --visual-search transfer_guard \
  --visual-candidate-preset wide \
  --asr-drop-tolerance 0.0 \
  --epsilon-linf-255 16 \
  --perturbation-scale 1.0 \
  --smoothing-kernel-size 3 \
  --transfer-models-dir ./models
```

`transfer_guard` 的核心逻辑：

- 默认 `standard` 预设保留 12 组旧候选；推荐汇报/报告使用 `wide` 预设，它会额外加入更强缩放、更强平滑、中频衰减、边缘掩码、顶格像素压缩、自适应 `satkeep` 和贴近 base 的 `blend` 过渡候选。
- `standard` 且严格保底时沿用历史 `visual_score`；`wide` 或允许 ASR 容忍下降时使用 `stripe_score = l1 + clip_fraction * 24 + bandpass_energy * 2 + flat_area_l1` 排序，更关注顶格像素和中频条纹。
- 严格模式下，只有候选在所有迁移模型上都不破坏 base 已成功的攻击时，才允许被选中。
- 当设置 `--asr-drop-tolerance 0.02` 时，脚本会在每个迁移模型最多 2% base-success 样本损失的约束内，继续尝试更干净的低 `stripe_score` 候选。
- 如果没有候选满足保底条件，自动回退到 `base`。
- 报告中会输出逐模型 base ASR、selected ASR、`asr_drop_by_model`、视觉指标下降比例、`stripe_score` 降幅和候选选择分布。

在本地 50 张、`tf_inception_v3 + tf_resnet_v2_50` 的严格 guard 复核中，`output/netG_epoch_60_mildvisual.pth` 经 `wide` 候选搜索后 ASR 未下降，L1 从 `11.25` 降到 `6.20`，`stripe_score` 从 `47.61` 降到 `19.61`，接近 epsilon 顶格像素比例从 `46.5%` 降到 `1.2%`。

推荐验收标准：

- 硬性通过条件：9 个迁移模型每一个的 selected ASR 相比 base 下降不超过 2%。
- 推荐目标：平均 ASR 下降不超过 1%。
- `clip_fraction` 相比 base 降低至少 50%。
- `bandpass_energy` 相比 base 降低至少 35%。
- `flat_area_l1` 相比 base 降低至少 20%。
- 如果 relaxed guard 没有达到 ASR 门槛，最终报告应改用 `--asr-drop-tolerance 0.0` 的 strict guard 结果。

如果你需要调用脚本封装版本：

```bash
bash scripts/run_deploy_eval.sh
```

或者：

```bash
bash run_deploy_eval.sh
```

## 七、Web 演示服务

### 1. 新增的核心文件

Web 演示部分主要位于 `webapp/`：

- `webapp/server.py`：FastAPI 后端接口
- `webapp/inference.py`：单图推理、分类与对抗样本生成逻辑
- `webapp/config.py`：运行配置、保留策略、跨域配置
- `webapp/static/index.html`：前端页面结构
- `webapp/static/app.js`：上传、结果渲染与交互逻辑
- `webapp/static/styles.css`：液态玻璃 + 星空科技风样式
- `visual_search.py`：共享视觉候选搜索、条纹评分与候选选择逻辑
- `run_webapp.py`：启动入口

### 2. 当前支持的能力

当前 Web 演示系统已经不只是一个简单上传页，而是一个完整的本地演示控制台，支持：

- 上传单张图片
- 选择生成器 checkpoint
- 选择识别模型
- 调节：
  - `epsilon_linf_255`
  - `perturbation_scale`
  - `top_k`
- 可选：
  - `自动裁剪 1:1`：先居中截取正方形区域再送入推理，避免非方图被强制拉伸。
  - `降噪输出`：生成低条纹候选，并优先保留当前识别模型下仍有效的结果。
- 展示：
  - 原图
  - 对抗样本
  - 扰动可视化
  - 攻击成功率
  - Top-1 是否变化
  - 响应耗时
  - Linf 扰动
  - 原图与对抗样本 Top-K 识别结果
  - 置信度变化与摘要指标
  - 图片预处理方式与推理前尺寸
  - 降噪候选、视觉评分降幅、顶格像素降幅和中频条纹降幅
- 下载：
  - 原图
  - 对抗样本
  - 扰动图
  - JSON 报告
  - TXT 报告

### 3. 页面风格与交互

当前前端页面已经做了完整的一轮演示化优化，主要特性包括：

- 更紧凑的实验控制台双栏布局
- 分层展示结果，不再一次性堆满所有内容
- 深色科技风 + 星空背景
- 液态玻璃风格面板
- 图像对比页优先展示生成结果
- 再次点击生成时会清空上一轮图片、预测、指标和下载链接
- 生成中会显示醒目的等待面板
- 勾选“降噪输出”时，会显示候选搜索进度条和耗时提示
- 扰动指标面板中内置 `avg_l1_255_per_pixel`、`l2_255`、`linf_255`、`normalized_linf`、`perturbation_energy` 和视觉降幅说明
- 轻量动画与状态切换

### 4. 本地启动

```bash
python run_webapp.py --host 0.0.0.0 --port 8000
```

然后访问：

```text
http://127.0.0.1:8000
```

### 5. 服务器启动方式

简单启动：

```bash
python run_webapp.py --host 0.0.0.0 --port 8000
```

生产风格启动：

```bash
uvicorn webapp.server:app --host 0.0.0.0 --port 8000
```

如果你准备正式部署到公网，建议再配合 Nginx 或 Caddy 做反向代理。

### 6. 可选环境变量

支持以下可选变量：

- `ADVGAN_DEFAULT_GENERATOR`
- `ADVGAN_DEFAULT_CLASSIFIER`
- `ADVGAN_DEFAULT_EPSILON`
- `ADVGAN_DEFAULT_SCALE`
- `ADVGAN_SMOOTH_KERNEL`
- `ADVGAN_AUTO_SQUARE_CROP`
- `ADVGAN_VISUAL_DENOISE`
- `ADVGAN_RUNTIME_DIR`
- `ADVGAN_SHARED_STATIC_DIR`
- `ADVGAN_ROOT_PATH`
- `ADVGAN_MAX_UPLOAD_MB`
- `ADVGAN_TOP_K`
- `ADVGAN_MAX_TOP_K`
- `ADVGAN_CORS_ORIGINS`
- `ADVGAN_ARTIFACT_RETENTION_HOURS`
- `ADVGAN_MAX_SAVED_REQUESTS`

示例：

```bash
export ADVGAN_DEFAULT_GENERATOR=output/netG_epoch_60.pth
export ADVGAN_DEFAULT_CLASSIFIER=mobilenet_v3_large
export ADVGAN_AUTO_SQUARE_CROP=true
export ADVGAN_VISUAL_DENOISE=false
export ADVGAN_ARTIFACT_RETENTION_HOURS=6
export ADVGAN_MAX_SAVED_REQUESTS=20
python run_webapp.py --host 0.0.0.0 --port 8000
```

部署到子路径时，例如 `/advgan_demo`，需要设置：

```bash
export ADVGAN_ROOT_PATH=/advgan_demo
```

如果要复用 Nebularive 主站的共享静态资源，可以设置：

```bash
export ADVGAN_SHARED_STATIC_DIR=/www/wwwroot/nebularive.top/static
```

### 7. 识别模型说明

- 默认支持 `torchvision` 模型
- 如果环境中安装了 `pretrainedmodels`，页面还会额外显示与仓库实验更一致的模型选项
- 某些 `torchvision` 模型首次运行时会自动下载权重
- 如果某个模型没有可读类别名，页面会退回显示 `class_<id>`

## 八、运行时文件与自动清理

### 1. 会不会在本地留下文件

会。

每次请求会在默认目录 `webapp/runtime/requests/` 下生成一个结果目录，里面通常包含：

- `original.png`
- `adversarial.png`
- `perturbation.png`
- `report.json`
- `report.txt`

这些文件用于前端展示、下载和后续分析。

### 2. 上传图片是否原样保存

不会原样保存用户上传的原始文件字节。

当前流程会先把上传图片读入内存，再经过：

- `resize`
- `tensor` 转换
- 模型推理

最后输出一份处理后的 `original.png` 作为展示用原图副本。

如果启用“自动裁剪 1:1”，`original.png` 展示的是中心正方形裁剪并 resize 到推理尺寸后的图像；如果关闭该选项，则沿用直接缩放到 `299 x 299` 的旧流程。

### 3. 自动清理机制

为了避免 `webapp/runtime/requests/` 无限增长，系统已经加入自动清理逻辑：

- 服务启动时会先清理一次
- 每次调用 `/api/attack` 前也会清理一次

默认策略：

- 超过 `12` 小时的请求目录自动删除
- 最多保留 `40` 个请求目录

对应环境变量：

- `ADVGAN_ARTIFACT_RETENTION_HOURS`
- `ADVGAN_MAX_SAVED_REQUESTS`

## 九、部署文档

更详细的部署说明请查看：

- [docs/DEPLOY.md](./docs/DEPLOY.md)

前后端协作文档请查看：

- [docs/FRONTEND_BACKEND_SETUP.md](./docs/FRONTEND_BACKEND_SETUP.md)

## 十、当前版本的边界

目前这套 Web 系统已经可以本地稳定跑通，但仍然属于“演示优先”的版本，当前默认假设如下：

- 仅支持 untargeted attack
- 仅支持单图请求
- 暂不包含用户鉴权
- 暂不包含任务队列
- 暂不包含历史记录数据库
- Web 降噪只使用当前识别模型做快速 guard，不声称 9 模型迁移 ASR 严格保底
- 严格迁移 ASR 保底需要通过 `deploy_model.py --visual-search transfer_guard` 离线验收

它已经适合用于课程展示、毕业设计演示、内部汇报或服务端原型验证。

## 十一、降低视觉条纹的当前方案

这轮优化的核心判断是：明显黑白条纹并不只是普通平滑不够，而是 `G.sign()` 攻击方向与 `Linf clamp` 容易鼓励生成器把大量像素推到 `±epsilon`。因此当前方案同时包含训练端和推理端。

### 1. 训练端推荐方案

训练端新增的关键参数已经接入 `main.py` 和 `advGan_GE.py`：

- `--ge_direction_mode sign|hybrid`
- `--actual_saturation_lambda`
- `--actual_saturation_threshold`
- `--bandpass_lambda`
- `--flat_area_lambda`
- `--flat_area_sensitivity`
- `--visual_warmup_epochs`
- `--success_reg_only`

推荐训练命令见第五节“推荐的低条纹训练命令”。当前主线是 `legacy_mild_visual`：保留 legacy 生成器的迁移攻击稳定性，只加入轻量视觉正则，避免 current/v3 路线中出现的 ASR 明显下降。

### 2. 推理端视觉候选搜索

推理端的 `visual_search.py` 提供两套候选预设：

- `standard`：保留 12 组历史候选，适合复现实验和对比旧结果。
- `wide`：在 `standard` 基础上扩展到 41 组候选，适合当前低条纹汇报和 Web 演示。

`standard` 候选包括：

- `base`
- `scale_0.9`
- `scale_0.8`
- `smooth_3`
- `smooth_5`
- `bandpass_0.3`
- `edge_mask_0.6`
- `scale_0.9_smooth_3`
- `scale_0.8_smooth_3`
- `scale_0.9_bandpass_0.3`
- `smooth_3_bandpass_0.3`
- `scale_0.9_edge_mask_0.6`

`wide` 会额外加入：

- 更低强度缩放：`scale_0.7`、`scale_0.6`
- 更强平滑与中频衰减：如 `smooth_7`、`bandpass_0.5`、`scale_0.8_bandpass_0.5`
- 更强边缘掩码：如 `edge_mask_0.8`、`scale_0.8_edge_mask_0.8`
- 顶格像素压缩：如 `satkeep_0.5`、`satkeep_0.25`
- 自适应顶格像素压缩：如 `satkeep_r0.75_k0.75`、`satkeep_r0.85_k0.75`、`satkeep_r0.90_k0.85`
- 贴近 base 的平滑过渡候选：如 `blend90_edge_mask_0.8`、`blend92_smooth_7`、`blend85_scale_0.7_smooth_3`

候选评分同时保留历史指标和当前低条纹指标：

```text
visual_score = l1 + clip_fraction * 16 + bandpass_energy * 1.5 + flat_area_l1
stripe_score = l1 + clip_fraction * 24 + bandpass_energy * 2 + flat_area_l1
```

其中：

- `l1`：平均像素改变量。
- `clip_fraction`：接近 `±epsilon` 的像素比例。
- `bandpass_energy`：中频条纹能量。
- `flat_area_l1`：平坦区域的加权扰动强度。
- `stripe_score`：当前推荐的低条纹选择指标，相比 `visual_score` 更重视顶格像素比例和中频条纹能量。

`satkeep` 的固定阈值规则是：对 `|diff_255| > 12` 的像素执行 `sign(diff) * (12 + (|diff|-12)*keep_ratio)`。自适应 `satkeep` 会把阈值改为随当前 `epsilon_linf_255` 成比例变化，以避免在较低扰动强度附近完全不生效。

`blend` 候选用于攻击成功边界附近的平滑过渡。它会把低条纹候选与原始 base 扰动按比例混合，降低“base 刚成功时只能回退到强条纹 base”的突变概率。

### 3. 离线严格保底

严格保底应使用：

```bash
python deploy_model.py \
  --generator-path output/netG_epoch_60_mildvisual.pth \
  --baseline-generator-path output/netG_epoch_60_mildvisual.pth \
  --output-dir deploy_outputs/mildvisual_wide_transfer_guard \
  --report-path deploy_outputs/mildvisual_wide_transfer_guard.json \
  --visual-search transfer_guard \
  --visual-candidate-preset wide \
  --asr-drop-tolerance 0.0 \
  --transfer-models-dir ./models
```

`transfer_guard` 会逐图、逐候选、逐迁移模型记录攻击是否成功。`--asr-drop-tolerance 0.0` 表示严格不破坏 base 已成功样本；`--asr-drop-tolerance 0.02` 表示每个迁移模型最多允许 2% 的 base-success 样本损失，用于换取更明显的条纹下降。

### 4. Web 快速降噪

Web 演示中的“降噪输出”默认使用 `wide + stripe_score`，但为了交互速度，只使用当前页面选择的识别模型做快速 guard。它适合演示和人工查看视觉效果，不等价于 9 个迁移模型的严格离线验收。

Web 端选择策略：

- 如果 base 已攻击成功，只接受同样攻击成功且 `stripe_score` 明显更低的候选。
- 如果没有这样的候选，回退到 `base`，优先保证攻击成功。
- 如果 base 尚未攻击成功，优先选择低条纹、低原类别置信度的候选，用于成功边界前的视觉预览。
- 返回报告会包含 `candidate_preset`、`stripe_score`、`selection_mode` 和 `selection_metadata`，方便定位候选选择原因。

### 5. 轻量验证命令

代码改动后建议至少运行：

```bash
python -m compileall main.py models.py advGan_GE.py advGan_baseline.py deploy_model.py webapp visual_search.py
node --check webapp/static/app.js
```

如果要验证候选搜索的离线输出，可以先小样本运行：

```bash
python deploy_model.py \
  --generator-path output/netG_epoch_60_mildvisual.pth \
  --baseline-generator-path output/netG_epoch_60_mildvisual.pth \
  --output-dir deploy_outputs/smoke_mildvisual_transfer_guard \
  --report-path deploy_outputs/smoke_mildvisual_transfer_guard.json \
  --max-samples 20 \
  --device auto \
  --visual-search transfer_guard \
  --visual-candidate-preset wide \
  --asr-drop-tolerance 0.0 \
  --transfer-models-dir ./models
```

### 6. 推荐验收顺序

1. 先评估 base checkpoint，记录 9 个迁移模型逐模型 ASR。
2. 再运行 `--visual-search transfer_guard`。
3. 检查每个迁移模型 selected ASR 相比 base 下降是否不超过 2%；如果使用 strict guard，则应不低于 base。
4. 检查 `stripe_score`、`clip_fraction`、`bandpass_energy`、`flat_area_l1` 是否明显下降。
5. 如果 relaxed guard 没有达到 ASR 门槛，改用 `--asr-drop-tolerance 0.0` 的 strict guard 结果。

## 十二、后续建议

如果你后面还想继续扩展，可以优先考虑：

1. 增加异步任务队列，支持耗时 GPU 推理
2. 增加用户鉴权和操作日志
3. 给不同 checkpoint 增加元数据说明
4. 增加历史结果页面和报告下载管理
5. 增加 Web 端异步降噪任务进度
6. 增加 Docker 与反向代理配置
7. 将离线 transfer-guard 的逐模型 success matrix 可视化

## 十三、引用

```bibtex
@article{zhu2024ge,
  title={GE-AdvGAN: Improving the transferability of adversarial samples by gradient editing-based adversarial generative model},
  author={Zhu, Zhiyu and Chen, Huaming and Wang, Xinyi and Zhang, Jiayu and Jin, Zhibo and Choo, Kim-Kwang Raymond},
  journal={arXiv preprint arXiv:2401.06031},
  year={2024}
}
```

## 十四、参考项目

参考代码来源：

[advGAN_pytorch](https://github.com/mathcbc/advGAN_pytorch.git)
[GE-advGAN](https://github.com/LMBTough/GE-advGAN.git)