tf-explain

tf-explain 将可解释性方法实现为 Tensorflow 2.x 的回调函数，旨在 简化神经网络的理解过程。 详情请参阅 介绍 tf-explain：TensorFlow 2.0 的可解释性工具

文档: https://tf-explain.readthedocs.io

安装

tf-explain 已发布在 PyPI 上。安装步骤如下：

virtualenv venv -p python3.8
pip install tf-explain

tf-explain 兼容 Tensorflow 2.x。它并未被声明为依赖项，以便您可以选择完整版或仅限 CPU 的独立版本。在完成上述安装后，请运行以下命令以安装 Tensorflow：

# 适用于 CPU 或 GPU
pip install tensorflow==2.6.0

OpenCV 也是其依赖项之一。安装方法如下：

# 适用于 CPU 或 GPU
pip install opencv-python

快速入门

tf-explain 提供了两种应用可解释性方法的方式。完整的可用方法列表请参见 可用方法 部分。

在已训练模型上

最佳方式可能是加载一个已训练好的模型，并在其上应用这些方法。

# 加载预训练模型或您自己的模型
model = tf.keras.applications.vgg16.VGG16(weights="imagenet", include_top=True)

# 加载一张示例图片（或多张）
img = tf.keras.preprocessing.image.load_img(IMAGE_PATH, target_size=(224, 224))
img = tf.keras.preprocessing.image.img_to_array(img)
data = ([img], None)

# 启动解释器
explainer = GradCAM()
grid = explainer.explain(data, model, class_index=281)  # 281 是 ImageNet 中的虎斑猫类别索引

explainer.save(grid, ".", "grad_cam.png")

在训练过程中

如果您希望在训练过程中监控模型的表现，也可以将其作为 Keras 回调函数使用，并直接在 TensorBoard 中查看结果。

from tf_explain.callbacks.grad_cam import GradCAMCallback

model = [...]

callbacks = [
    GradCAMCallback(
        validation_data=(x_val, y_val),
        class_index=0,
        output_dir=output_dir,
    )
]

model.fit(x_train, y_train, batch_size=2, epochs=2, callbacks=callbacks)

可用方法

1. 激活可视化
2. 普通梯度
3. 梯度乘以输入
4. 遮挡敏感性分析
5. Grad CAM（类激活图）
6. 平滑梯度
7. 积分梯度

激活可视化

可视化给定输入如何通过特定的激活层输出

from tf_explain.callbacks.activations_visualization import ActivationsVisualizationCallback

model = [...]

callbacks = [
    ActivationsVisualizationCallback(
        validation_data=(x_val, y_val),
        layers_name=["activation_1"],
        output_dir=output_dir,
    ),
]

model.fit(x_train, y_train, batch_size=2, epochs=2, callbacks=callbacks)

普通梯度

可视化梯度对输入图像的重要性

from tf_explain.callbacks.vanilla_gradients import VanillaGradientsCallback

model = [...]

callbacks = [
    VanillaGradientsCallback(
        validation_data=(x_val, y_val),
        class_index=0,
        output_dir=output_dir,
    ),
]

model.fit(x_train, y_train, batch_size=2, epochs=2, callbacks=callbacks)

梯度乘以输入

普通梯度 的变体，将梯度与输入值加权结合

from tf_explain.callbacks.gradients_inputs import GradientsInputsCallback

model = [...]

callbacks = [
    GradientsInputsCallback(
        validation_data=(x_val, y_val),
        class_index=0,
        output_dir=output_dir,
    ),
]

model.fit(x_train, y_train, batch_size=2, epochs=2, callbacks=callbacks)

遮挡敏感性分析

通过逐块遮挡图像的不同部分，可视化各部分对神经网络置信度的影响

from tf_explain.callbacks.occlusion_sensitivity import OcclusionSensitivityCallback

model = [...]

callbacks = [
    OcclusionSensitivityCallback(
        validation_data=(x_val, y_val),
        class_index=0,
        patch_size=4,
        output_dir=output_dir,
    ),
]

model.fit(x_train, y_train, batch_size=2, epochs=2, callbacks=callbacks)

Grad CAM

通过查看激活图，可视化图像各部分对神经网络输出的影响

摘自 Grad-CAM：基于梯度的定位技术，用于从深度网络中获取可视化解释

from tf_explain.callbacks.grad_cam import GradCAMCallback

model = [...]

callbacks = [
    GradCAMCallback(
        validation_data=(x_val, y_val),
        class_index=0,
        output_dir=output_dir,
    ),
]

model.fit(x_train, y_train, batch_size=2, epochs=2, callbacks=callbacks)

平滑梯度

可视化在决策过程中，输入上的稳定化梯度

摘自 平滑梯度：通过添加噪声来去除噪声

from tf_explain.callbacks.smoothgrad import SmoothGradCallback

model = [...]

callbacks = [
    SmoothGradCallback(
        validation_data=(x_val, y_val),
        class_index=0,
        num_samples=20,
        noise=1.,
        output_dir=output_dir,
    ),
]

model.fit(x_train, y_train, batch_size=2, epochs=2, callbacks=callbacks)

集成梯度

可视化输入在向决策点演进过程中梯度的平均值

摘自 深度神经网络的公理化归因

from tf_explain.callbacks.integrated_gradients import IntegratedGradientsCallback

model = [...]

callbacks = [
    IntegratedGradientsCallback(
        validation_data=(x_val, y_val),
        class_index=0,
        n_steps=20,
        output_dir=output_dir,
    )
]

model.fit(x_train, y_train, batch_size=2, epochs=2, callbacks=callbacks)

路线图

• 支持子类化 API
• 添加更多方法
  • GradCAM++
  • 集成梯度
  • 引导平滑梯度
  • LRP
• 自动生成 API 文档及文档测试

贡献

如需参与项目贡献，请阅读专门章节。

引用

我们提供了一份CFF 格式的引用文件，用于引用本项目。请在 GitHub 页面右侧栏点击“引用此仓库”按钮，即可获取 BibTeX 格式的引用信息。

tf-explain 快速上手指南

tf-explain 是一个基于 TensorFlow 2.x 的可解释性工具库，它将多种神经网络解释方法（如 Grad-CAM、SmoothGrad 等）实现为 Keras 回调函数或独立解释器，帮助开发者直观理解模型的决策过程。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：3.6, 3.7 或 3.8
• 核心依赖：
  • TensorFlow 2.x (推荐 2.6.0)
  • OpenCV (opencv-python)

国内加速建议：安装依赖时建议使用清华或阿里镜像源以提升下载速度。 例如：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <包名>

安装步骤

推荐使用虚拟环境进行隔离安装。请依次执行以下命令：

1. 创建并激活虚拟环境

   virtualenv venv -p python3.8
   source venv/bin/activate  # Windows 用户请使用: venv\Scripts\activate
   

2. 安装 tf-explain

   pip install tf-explain
   

3. 安装 TensorFlow 和 OpenCV 由于 tf-explain 未强制绑定特定版本的 TensorFlow，您需要手动安装兼容版本及图像处理依赖：

   # 安装 TensorFlow (CPU/GPU 通用)
   pip install tensorflow==2.6.0
   
   # 安装 OpenCV
   pip install opencv-python
   

   (若需国内加速，请在上述命令中加入 -i https://pypi.tuna.tsinghua.edu.cn/simple)

基本使用

tf-explain 提供两种主要使用方式：直接对已训练好的模型进行解释，或在训练过程中通过 Callback 实时监控。

方式一：解释已训练的模型

这是最常用的方式，加载预训练模型或您自己的模型，对特定输入生成热力图。以下示例使用 Grad-CAM 方法分析 ImageNet 预训练的 VGG16 模型：

import tensorflow as tf
from tf_explain.core.grad_cam import GradCAM

# 1. 加载预训练模型 (或使用您自己的 model)
model = tf.keras.applications.vgg16.VGG16(weights="imagenet", include_top=True)

# 2. 加载并预处理图片
img = tf.keras.preprocessing.image.load_img("path_to_your_image.jpg", target_size=(224, 224))
img = tf.keras.preprocessing.image.img_to_array(img)
data = ([img], None)

# 3. 初始化解释器并生成结果
# class_index=281 对应 ImageNet 中的 "tabby cat" (虎斑猫)
explainer = GradCAM()
grid = explainer.explain(data, model, class_index=281)

# 4. 保存结果图片
explainer.save(grid, ".", "grad_cam_output.png")

方式二：在训练过程中监控 (TensorBoard)

如果您希望在模型训练期间实时观察可解释性结果，可以将其作为 Keras Callback 使用，结果将直接输出到 TensorBoard 或指定目录。

from tf_explain.callbacks.grad_cam import GradCAMCallback

# 假设 model 已经定义
# model = [...]

# 配置回调函数
callbacks = [
    GradCAMCallback(
        validation_data=(x_val, y_val),  # 验证集数据
        class_index=0,                   # 需要解释的类别索引
        output_dir="./logs/grad_cam",    # 输出目录
    )
]

# 开始训练
model.fit(x_train, y_train, batch_size=2, epochs=2, callbacks=callbacks)

训练完成后，您可以启动 TensorBoard 查看可视化结果：

tensorboard --logdir=./logs

支持的解释方法

除了上述示例中的 Grad-CAM，本工具还支持以下方法（均可作为独立解释器或 Callback 使用）：

• Activations Visualization: 可视化特定层的激活输出。
• Vanilla Gradients: 可视化输入图像上的梯度重要性。
• Gradients*Inputs: 结合输入值加权的梯度变体。
• Occlusion Sensitivity: 通过遮挡部分图像来评估其对置信度的影响。
• SmoothGrad: 通过添加噪声平滑梯度，减少视觉噪点。
• Integrated Gradients: 计算从基线到输入的积分梯度。