GANDissect

项目 | 演示 | 论文 | 视频

GAN Dissection 是一种检查生成对抗网络（GAN）内部表示的方法，以理解其内部单元如何与人类可解释的概念相对应。它是 NetDissect 的一部分。

这个仓库允许你解剖一个 GAN 模型，并将解剖结果以静态摘要或交互式可视化的方式呈现。尝试我们的交互式 GANPaint 演示，与 GAN 互动并绘制图像。

概述

生成对抗网络的可视化与理解
David Bau、Jun-Yan Zhu、Hendrik Strobelt、Bolei Zhou、Joshua B. Tenenbaum、William T. Freeman、Antonio Torralba
MIT CSAIL、MIT-IBM Watson AI Lab、香港中文大学、IBM 研究院
发表于 arXiv，2018年。

分析与应用

GAN 中可解释的单元

分析不同层

诊断和改进 GAN

从会议室中移除物体

从不同自然场景中移除窗户

在图像中插入新物体

发布历史

v 0.9 alpha - 2018年11月26日

快速入门

让我们设置环境并解剖一个 churchoutdoor GAN。这需要一块支持 CUDA 的 GPU 和一定的磁盘空间。

设置

要从本仓库安装所有必需的软件，请确保已安装 conda，然后运行：

script/setup_env.sh      # 创建包含依赖项的 conda 环境
script/make_dirs.sh      # 创建数据集和解剖目录
script/download_data.sh  # 下载支持数据和演示用 GAN
source activate netd     # 进入 conda 环境
pip install -v -e .      # 将本地 netdissect 包链接到环境中

详细信息。该代码依赖于 Python 3、PyTorch 4.1 以及其他几个包。对于 conda 用户，script/environment.yml 提供了详细的依赖关系。对于 pip 用户，setup.py 列出了所有必需的依赖项。

数据。download_data.sh 脚本会下载用于解剖分类器的分割数据集、用于解剖 GAN 的分割网络，以及若干用于解剖的示例 GAN 模型。这些文件将被下载到 dataset/ 和 models/ 目录中。如果你不想下载示例网络，可以使用 python -m netdissect --download 命令仅下载 netdissect 本身所需的数据和模型。

解剖一个 GAN

GAN 示例：解剖由 Karras 训练的 LSUN 客厅渐进式 GAN 的三层：

python -m netdissect \
   --gan \
   --model "netdissect.proggan.from_pth_file('models/karras/livingroom_lsun.pth')" \
   --outdir "dissect/livingroom" \
   --layer layer1 layer4 layer7 \
   --size 1000

结果会在 dissect/livingroom/dissect.html 生成一个静态 HTML 页面，并在 dissect/livingroom/dissect.json 生成一个包含指标的 JSON 文件。

你可以测试自己的模型：--model 参数是一个完全限定的 Python 函数或构造函数，用于加载要测试的 GAN。--layer 参数是完全限定的层名（类似于 state_dict 样式）。

默认情况下，使用基于场景的分割，但可以通过向 --segmenter 提供替代的类构造函数来替换不同的分割器类。有关分割器基类的信息，请参阅 netdissect/segmenter.py。

运行 GAN 编辑服务器（alpha）

一旦 GAN 被解剖，你就可以运行一个提供 API 的 Web 服务器，该服务器可以根据（可选）干预生成图像。

python -m netdissect.server --address 0.0.0.0

编辑界面（右）将在 http://localhost:5001/ 提供服务。

其他 URL：

• http://localhost:5001/api/ui 是 OpenAPI/Swagger 界面，用于直接测试 GAN 干预。
• http://localhost:5001/data/livingroom/dissect.html 是静态的网络解剖报告。
• http://localhost:5001/data/livingroom/edit.html 是一个基于解剖的界面，用于测试干预。
• 待办事项：http://localhost:5001/ganpaint.html 将提供 GANpaint 服务。

高级用法

解剖一个分类器（NetDissect）

分类器示例：解剖 torchvision 中预训练的 alexnet 的三层：

python -m netdissect \
   --model "torchvision.models.alexnet(pretrained=True)" \
   --layers features.6:conv3 features.8:conv4 features.10:conv5 \
   --imgsize 227 \
   --outdir dissect/alexnet-imagenet

分类器不需要特殊的 Web 服务器。

命令行详细说明

netdissect 命令行工具的文档。

用法：python -m netdissect [-h] [--model MODEL] [--pthfile PTHFILE]
                            [--outdir OUTDIR] [--layers LAYERS [LAYERS ...]]
                            [--segments SEGMENTS] [--segmenter SEGMENTER]
                            [--download] [--imgsize IMGSIZE]
                            [--netname NETNAME] [--meta META [META ...]]
                            [--examples EXAMPLES] [--size SIZE]
                            [--batch_size BATCH_SIZE]
                            [--num_workers NUM_WORKERS]
                            [--quantile_threshold {[0-1],iqr}] [--no-labels]
                            [--maxiou] [--covariance] [--no-images]
                            [--no-report] [--no-cuda] [--gen] [--gan]
                            [--perturbation PERTURBATION] [--add_scale_offset]
                            [--quiet]

可选参数：

  -h, --help            显示此帮助信息并退出
  --model MODEL         用于测试的模型构造函数
  --pthfile PTHFILE     模型 .pth 文件的文件名
  --outdir OUTDIR       解剖输出的目录
  --layers LAYERS [LAYERS ...]
                        以空格分隔的要解剖的层名称列表，格式为 layername[:reportedname]
  --segments SEGMENTS   包含分割数据集的目录
  --segmenter SEGMENTER
                        分割类的构造函数
  --download            如果需要，则下载 Broden 数据集
  --imgsize IMGSIZE     使用的输入图像大小
  --netname NETNAME     生成报告中网络的名称
  --meta META [META ...]
                        要添加到报告中的元数据 JSON 文件
  --examples EXAMPLES   每个单元的图像示例数量
  --size SIZE           使用的数据集子集大小
  --batch_size BATCH_SIZE
                        前向传播的批量大小
  --num_workers NUM_WORKERS
                        DataLoader 工作线程的数量
  --quantile_threshold {[0-1],iqr}
                        用于掩码的分位数
  --no-labels           禁用单元标注
  --maxiou              启用 MaxIOU 计算
  --covariance          启用协方差计算
  --no-images           禁用单元图像的生成
  --no-report           禁用报告摘要的生成
  --no-cuda             禁用 CUDA 的使用
  --gen                 测试生成器模型（例如 GAN）
  --gan                 --gen 的同义词
  --perturbation PERTURBATION
                        要应用的扰动攻击文件名
  --add_scale_offset    根据步幅和填充偏移掩码
  --quiet               静音控制台输出

API，适用于分类器

该工具也可以在代码中作为函数使用，具体步骤如下：

1. 加载您希望解剖的卷积神经网络模型，并调用 imodel = InstrumentedModel(model)，然后通过 imodel.retain_layers([layernames,..]) 对模型进行插桩。
2. 使用 BrodenDataset 类加载分割数据集；通过 transform_image 参数对图像进行归一化以适应模型要求，并通过 size 参数截断数据集。
3. 选择一个用于写入输出的目录，然后调用 dissect(outdir, imodel, dataset)。

可以通过减小 BrodenDataset 的 size 来快速进行近似解剖。生成示例图像可能耗时较长，可通过 examples_per_unit 设置每单位生成的图像数量。

示例：

    from netdissect import InstrumentedModel, dissect
    from netdissect import BrodenDataset

    model = InstrumentedModel(load_my_model())
    model.eval()
    model.cuda()
    model.retain_layers(['conv1', 'conv2', 'conv3', 'conv4', 'conv5'])
    bds = BrodenDataset('dataset/broden1_227',
            transform_image=transforms.Compose([
                transforms.ToTensor(),
                transforms.Normalize(IMAGE_MEAN, IMAGE_STDEV)]),
            size=10000)
    dissect('result/dissect', model, bds,
            batch_size=100,
            examples_per_unit=10)

Broden 数据集主要针对自然场景照片中的语义对象、部件、材质、颜色等。如果您想使用不同的语义分割来分析模型，可以替换其他分割数据集，并提供一个 segrunner 参数，该参数描述了如何从数据集中获取分割结果和 RGB 图像。详细信息请参阅 ClassifierSegRunner。

API，适用于生成器

同样地：

1. 加载您希望解剖的生成器模型，并调用 retain_layers(model, [layernames,..]) 对模型进行插桩。
2. 创建用于测试的 z 输入样本数据集。如果您的模型使用均匀正态分布，z_dataset_for_model 可以生成这样的数据集。
3. 选择一个用于写入输出的目录，然后调用 dissect(outdir, model, dataset, segrunner=GeneratorSegRunner())。

解剖所需的时间与数据集中样本的数量成正比。

    from netdissect import InstrumentedModel, dissect
    from netdissect import z_dataset_for_model, GeneratorSegRunner

    model = InstrumentedModel(load_my_model())
    model.eval()
    model.cuda()
    model.retain_layers(model, ['layer3', 'layer4', 'layer5'])
    zds = z_dataset_for_model(size, model)
    dissect('result/gandissect', model, zds,
            segrunner=GeneratorSegRunner(),
            batch_size=100,
            examples_per_unit=10)

GeneratorSegRunner 默认运行一个面向自然场景照片中语义对象、部件和材质的语义分割网络。若需使用其他语义分割，可在 GeneratorSegRunner 的构造函数中传入自定义的 Segmenter 子类。

引用

如果您在研究中使用此代码，请引用我们的论文：

@inproceedings{bau2019gandissect,
 title={GAN Dissection: Visualizing and Understanding Generative Adversarial Networks},
 author={Bau, David and Zhu, Jun-Yan and Strobelt, Hendrik and Zhou, Bolei and Tenenbaum, Joshua B. and Freeman, William T. and Torralba, Antonio},
 booktitle={Proceedings of the International Conference on Learning Representations (ICLR)},
 year={2019}
}

GANDissect 快速上手指南

GANDissect 是一个用于可视化及理解生成对抗网络（GAN）内部表示的工具。它能帮助开发者分析 GAN 内部单元如何与人类可理解的概念（如物体、纹理、颜色等）对齐，并支持对生成图像进行交互式编辑。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux (推荐) 或 macOS
• GPU: 需要支持 CUDA 的 NVIDIA GPU（用于加速模型推理和解剖分析）
• 磁盘空间: 建议预留至少 10GB 空间，用于下载数据集和预训练模型
• 前置依赖:
  • Python 3.x
  • Conda (推荐使用 Miniconda 或 Anaconda 管理环境)
  • PyTorch (代码依赖 PyTorch，安装脚本会自动配置兼容版本)

注意：国内用户若遇到 conda 或 pip 下载缓慢的问题，建议在运行安装脚本前配置清华源或中科大源。

安装步骤

本项目推荐使用 Conda 进行环境隔离和依赖管理。请按顺序执行以下命令：

1. 克隆仓库并进入目录

   git clone https://github.com/CSAILVision/gandissect.git
   cd gandissect
   

2. 创建康达环境并安装依赖 运行官方提供的设置脚本，它将自动创建名为 netd 的环境并安装所需包：

   script/setup_env.sh
   

3. 创建数据目录结构

   script/make_dirs.sh
   

4. 下载数据与示例模型 下载用于解剖分析的分割数据集、分割网络以及示例 GAN 模型（如 LSUN 教堂、卧室等）：

   script/download_data.sh
   

   提示：如果网络受限，此步骤可能耗时较长。若仅需核心功能而不需要示例模型，可后续按需下载。

5. 激活环境并链接本地包

   source activate netd
   pip install -v -e .
   

基本使用

安装完成后，您可以立即对预训练的 GAN 模型进行“解剖”分析。以下示例将分析一个生成卧室场景的 Progressive GAN 模型的三个层级。

运行解剖分析

在激活的 netd 环境中执行以下命令：

python -m netdissect \
   --gan \
   --model "netdissect.proggan.from_pth_file('models/karras/livingroom_lsun.pth')" \
   --outdir "dissect/livingroom" \
   --layer layer1 layer4 layer7 \
   --size 1000

参数说明：

• --gan: 指定目标为生成器模型。
• --model: 加载模型的 Python 函数路径。
• --outdir: 输出结果目录。
• --layer: 指定要分析的网络层名称（需与模型 state_dict 一致）。
• --size: 用于分析的采样图片数量（数量越大结果越准，但耗时越长）。

查看结果

命令执行完毕后，将在 dissect/livingroom/ 目录下生成以下文件：

• dissect.html: 静态 HTML 报告，包含各层级单元与语义概念的对应关系可视化。
• dissect.json: 包含详细量化指标的 JSON 文件。

您可以直接在浏览器中打开 dissect/livingroom/dissect.html 查看分析结果。

（可选）启动交互式编辑服务

如果您希望体验类似 GANpaint 的交互式图像编辑功能，可以启动本地 Web 服务器：

python -m netdissect.server --address 0.0.0.0

启动后，访问 http://localhost:5001/ 即可使用可视化界面，通过勾选语义标签来实时修改生成图像中的内容（如添加/移除窗户、树木等）。