显著性库

更新

🔴   现在与框架无关！(核心示例笔记本)  🔴

🔗   如需进一步了解这些方法以及更多结果图示例，请参阅我们的 Github Pages 网站  🔗

如果您是从旧版本升级，请将旧的导入语句更新为 import saliency.tf1 as saliency。我们提供了封装器，使与框架无关的版本能够兼容 TensorFlow 1 模型。(TensorFlow 1 示例笔记本)

🔴   新增性能信息曲线（PIC）——一种不依赖人工评估的指标，用于评价显著性方法的质量。 (示例笔记本)  🔴

显著性方法

本仓库包含以下显著性技术的代码实现：

• 引导式积分梯度*（论文，海报)
• XRAI*（论文，海报)
• 平滑梯度*（论文）
• 原始梯度 （论文, 论文）
• 引导式反向传播（论文）
• 积分梯度（论文）
• 屏蔽法
• Grad-CAM（论文）
• 模糊积分梯度（论文）

*由 PAIR 团队开发。

此列表绝非完整。我们欢迎通过 Pull Request 添加新方法！

显著性方法的评估

该仓库提供性能信息曲线（PIC）的实现——一种不依赖人工评估的指标，用于评价显著性方法的质量 （论文, 海报, 代码, 笔记本).

下载

# 安装核心子包：
pip install saliency

# 安装核心和 tf1 子包：
pip install saliency[tf1]

或获取开发版本：

git clone https://github.com/pair-code/saliency
cd saliency

使用

显著性库包含两个子包：

• core 使用通用的 call_model_function，可与任何机器学习框架配合使用。
• tf1 直接接受输入输出张量，并为每种方法设置必要的计算图操作。

Core

每个显著性掩码类都继承自 CoreSaliency 基类。该类包含以下方法：

• GetMask(x_value, call_model_function, call_model_args=None): 根据显著性技术，返回与非批量输入 x_value 形状相同的掩码。
• GetSmoothedMask(x_value, call_model_function, call_model_args=None, stdev_spread=.15, nsamples=25, magnitude=True): 使用平滑梯度技术，返回与非批量输入 x_value 形状相同的平滑化掩码。

可视化模块包含两种显著性可视化方法：

• VisualizeImageGrayscale(image_3d, percentile): 对各通道的绝对值进行降维，生成一个单通道的 2D 图像，并按给定百分位数截断图像。该方法返回一个归一化到 0 到 1 的 2D 张量。
• VisualizeImageDiverging(image_3d, percentile): 对各通道的值进行降维，生成一个单通道的 2D 图像，并按给定百分位数截断图像。该方法返回一个归一化到 -1 到 1 的 2D 张量，其中零值保持不变。

如果显著性掩码中数值的正负号并不重要，则使用 VisualizeImageGrayscale；否则使用 VisualizeImageDiverging。有关应使用哪种可视化方法的更多细节，请参阅平滑梯度论文。

call_model_function

call_model_function 是我们将输入传递给模型并获取计算显著性掩码所需输出的方式。该方法的描述及预期输出格式已在 CoreSaliency 类说明中给出，并针对每种方法单独列出。

示例

这个 iPython 笔记本示例 展示了这些技术，是一个不错的起点。

以下是使用 TensorFlow 2 进行 IG+平滑梯度的简要示例：

import saliency.core as saliency
import tensorflow as tf

...

# 在此处构建 call_model_function。
def call_model_function(x_value_batched, call_model_args, expected_keys):
	tape = tf.GradientTape()
	grads = np.array(tape.gradient(output_layer, images))
	return {saliency.INPUT_OUTPUT_GRADIENTS: grads}

...

# 加载数据。
image = GetImagePNG(...)

# 计算 IG+平滑梯度。
ig_saliency = saliency.IntegratedGradients()
smoothgrad_ig = ig_saliency.GetSmoothedMask(image, 
											call_model_function, 
                                            call_model_args=None)

# 计算用于可视化的 2D 张量。
grayscale_visualization = saliency.VisualizeImageGrayscale(
    smoothgrad_ig)

TF1

每个显著性掩码类都继承自 TF1Saliency 基类。该类包含以下方法：

• __init__(graph, session, y, x): 显著性掩码的构造函数。此方法可能会修改图结构，有时还会创建一个新的计算图。通常，它会在图中添加节点，因此不应频繁调用。y 是用于计算显著性掩码的输出张量，x 是输入张量，其最外层维度表示批次大小。
• GetMask(x_value, feed_dict): 根据显著性技术，返回与非批处理形式的 x_value 形状相同的掩码。
• GetSmoothedMask(x_value, feed_dict): 使用 SmoothGrad 技术，返回对非批处理形式的 x_value 进行平滑处理后的掩码。

可视化模块包含两种可视化方法：

• VisualizeImageGrayscale(image_3d, percentile): 对每个通道的绝对值进行降维，生成一个二维单通道图像，并按给定百分位数裁剪图像。该方法返回一个归一化到 0 到 1 范围内的二维张量。
• VisualizeImageDiverging(image_3d, percentile): 对每个通道的值进行降维，生成一个二维单通道图像，并按给定百分位数裁剪图像。该方法返回一个归一化到 -1 到 1 范围内的二维张量，其中零值保持不变。

如果显著性掩码中的值的符号不重要，则使用 VisualizeImageGrayscale；否则使用 VisualizeImageDiverging。有关应使用哪种可视化方法的更多详细信息，请参阅 SmoothGrad 论文。

示例

这个示例 iPython 笔记本 展示了这些技术，是一个不错的起点。

另一个使用 TensorFlow 中的 Guided Backprop 和 SmoothGrad 的示例：

from saliency.tf1 import GuidedBackprop
from saliency.tf1 import VisualizeImageGrayscale
import tensorflow.compat.v1 as tf

...
# 在此处构建 TensorFlow 计算图。
y = logits[5]
x = tf.placeholder(...)
...

# 计算引导反向传播。
# 注意：这会创建另一个会被缓存的计算图，应尽量避免多次创建。
guided_backprop_saliency = GuidedBackprop(graph, session, y, x)

...
# 加载数据。
image = GetImagePNG(...)
...

smoothgrad_guided_backprop =
    guided_backprop_saliency.GetMask(image, feed_dict={...})

# 计算用于可视化的二维张量。
grayscale_visualization = visualization.VisualizeImageGrayscale(
    smoothgrad_guided_backprop)

结论/免责声明

如果您对该库有任何疑问或改进建议，请联系 PAIR-code/saliency 仓库的所有者。

本项目并非 Google 官方产品。

Saliency 快速上手指南

Saliency 是一个由 Google PAIR 团队开发的框架无关（Framework-agnostic）库，用于生成和可视化深度学习模型的显著性图（Saliency Maps），帮助理解模型关注的图像区域。支持 TensorFlow 1、TensorFlow 2 及其他通过回调函数适配的框架。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：建议 Python 3.7+
• 前置依赖：
  • 基础版：仅需 numpy 等基础科学计算库。
  • TensorFlow 用户：需预先安装 tensorflow (TF1 或 TF2)。
  • 其他框架：无需特定框架依赖，只需实现标准的 call_model_function 接口。

安装步骤

方式一：通过 Pip 安装（推荐）

安装核心包（适用于所有框架，包括 TF2）：

pip install saliency

安装核心包 + TensorFlow 1 支持包：

pip install saliency[tf1]

国内加速提示：如果下载速度较慢，可使用清华或阿里镜像源：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple saliency
# 或
pip install -i https://mirrors.aliyun.com/pypi/simple/ saliency[tf1]

方式二：源码安装（开发版）

git clone https://github.com/pair-code/saliency
cd saliency
pip install -e .

基本使用

Saliency 提供两种使用模式：

1. Core 模式：框架无关，通过 call_model_function 适配任意模型（推荐 TF2 及非 TF 用户）。
2. TF1 模式：专为 TensorFlow 1 设计，直接操作 Graph 和 Session。

以下展示最常用的 Core 模式 结合 TensorFlow 2 的使用示例（计算 Integrated Gradients + SmoothGrad）：

代码示例

import saliency.core as saliency
import tensorflow as tf
import numpy as np

# 1. 定义模型调用函数
# 该函数接收输入并返回计算显著性所需的梯度信息
def call_model_function(x_value_batched, call_model_args, expected_keys):
    # x_value_batched: 批量化的输入数据
    # 需要确保模型是可微分的
    with tf.GradientTape() as tape:
        tape.watch(x_value_batched)
        # 假设 model 是你的预处理好的 TF2 模型
        predictions = model(x_value_batched) 
        # 选择需要解释的输出类别索引，例如第 0 类
        output_layer = predictions[:, 0] 
    
    # 计算输入相对于输出的梯度
    grads = tape.gradient(output_layer, x_value_batched)
    
    # 返回格式必须符合库的要求
    return {saliency.INPUT_OUTPUT_GRADIENTS: grads.numpy()}

# 2. 加载数据 (假设已有一个归一化后的单张图片数组，形状不含 batch 维)
# image = GetImagePNG(...) 
# 此处仅为示意，实际需替换为你的图片加载逻辑
image = np.random.rand(224, 224, 3).astype(np.float32) 

# 3. 初始化显著性方法并计算掩码
# 使用 Integrated Gradients (IG)
ig_saliency = saliency.IntegratedGradients()

# 计算平滑后的掩码 (IG + SmoothGrad)
# stdev_spread: 噪声标准差，nsamples: 采样次数
smoothgrad_ig = ig_saliency.GetSmoothedMask(
    image, 
    call_model_function, 
    call_model_args=None,
    stdev_spread=0.15,
    nsamples=25
)

# 4. 可视化处理
# 将 3D 掩码转换为 2D 灰度图用于显示 (值域 0-1)
grayscale_visualization = saliency.VisualizeImageGrayscale(
    smoothgrad_ig, 
    percentile=99 # 截断分布以增强对比度
)

# grayscale_visualization 即为最终可用于 matplotlib 显示的 2D 数组

关键方法说明

• GetMask: 获取基础显著性掩码。
• GetSmoothedMask: 自动应用 SmoothGrad 技术，通过添加噪声并多次采样来平滑结果，通常视觉效果更佳。
• VisualizeImageGrayscale: 适用于不关心梯度正负号的场景，输出归一化到 [0, 1]。
• VisualizeImageDiverging: 适用于关心梯度方向（正/负影响）的场景，输出归一化到 [-1, 1]。

更多详细用法及针对 TF1 的示例，请参考官方仓库中的 Examples_core.ipynb 和 Examples_tf1.ipynb。