Keract: Keras 激活值 + 梯度

寻求贡献者将此库升级至 Tensorflow 2.16+

已在 Tensorflow 2.9、2.10、2.11、2.12、2.13、2.14 和 2.15 上测试过（2023年11月17日）。

不兼容 Tensorflow 2.16 及以上版本。

pip install keract

您刚刚找到了一种方法，可以获取 TensorFlow/Keras 模型（LSTM、卷积网络等）中每一层的激活值（输出）和梯度。

重要提示：嵌套模型支持不佳。TensorFlow 的最新版本使得可靠地提取层输出变得极其困难。请参阅示例部分，了解可行的操作。

API

• get_activations
• display_activations
• display_heatmaps
• get_gradients_of_trainable_weights
• get_gradients_of_activations
• persist_to_json_file
• load_activations_from_json_file

获取激活值（节点/层的输出为 NumPy 数组）

keract.get_activations(model, x, layer_names=None, nodes_to_evaluate=None, output_format='simple', nested=False, auto_compile=True)

为 Keras 模型和输入 X 获取激活值（节点/层的输出为 NumPy 数组）。默认情况下，会返回所有层的所有激活值。

• model: 已编译的 Keras 模型，或以下之一：['vgg16', 'vgg19', 'inception_v3', 'inception_resnet_v2', 'mobilenet_v2', 'mobilenetv2', ...]。
• x: 作为输入馈送到模型的 NumPy 数组。如果是多输入，则 x 应为 List 类型。
• layer_names: （可选）要返回激活值的单个层名或层名列表。在非常大的网络中，计算评估所有层/节点的开销较高时，此参数很有用。
• nodes_to_evaluate: （可选）要评估的 Keras 节点列表。
• output_format: 更改函数输出字典的键。
  • simple: 输出键将与 Keras 层的名称匹配。例如 Dense(1, name='d1') 将返回 {'d1': ...}。
  • full: 输出键将与输出层的完整名称匹配。在上述示例中，它将返回 {'d1/BiasAdd:0': ...}。
  • numbered: 输出键将是基于模型中各层定义顺序的索引范围。
• nested: 如果指定，将递归遍历模型定义以检索嵌套层。递归将在模型树的叶层或 layer_names 中指定名称的层处结束。例如，一个 Sequential 模型嵌套在另一个 Sequential 模型中被视为嵌套。
• auto_compile: 如果设置为 True，将在需要时自动编译模型。

返回值：字典 {层名（由 output_format 指定）-> 层输出/节点的激活值（NumPy 数组）}。

示例

import numpy as np
from tensorflow.keras import Input, Model
from tensorflow.keras.layers import Dense, concatenate
from keract import get_activations

# 模型定义
i1 = Input(shape=(10,), name='i1')
i2 = Input(shape=(10,), name='i2')

a = Dense(1, name='fc1')(i1)
b = Dense(1, name='fc2')(i2)

c = concatenate([a, b], name='concat')
d = Dense(1, name='out')(c)
model = Model(inputs=[i1, i2], outputs=[d])

# 模型输入
x = [np.random.uniform(size=(32, 10)), np.random.uniform(size=(32, 10))]

# 调用以获取模型的激活值。
activations = get_activations(model, x, auto_compile=True)

# 打印激活值的形状。
[print(k, '->', v.shape, '- Numpy array') for (k, v) in activations.items()]

# 输出：
# i1 -> (32, 10) - Numpy array
# i2 -> (32, 10) - Numpy array
# fc1 -> (32, 1) - Numpy array
# fc2 -> (32, 1) - Numpy array
# concat -> (32, 2) - Numpy array
# out -> (32, 1) - Numpy array

显示您获得的激活值

keract.display_activations(activations, cmap=None, save=False, directory='.', data_format='channels_last', fig_size=(24, 24), reshape_1d_layers=False)

使用 matplotlib 绘制各层的激活值。

输入参数：

• activations: 字典 - 将层映射到其激活值的字典（get_activations 的输出）。
• cmap: （可选）字符串 - 有效的 matplotlib 颜色映射。
• save: （可选）布尔值 - 如果为 True，则保存激活值图像而不是显示。
• directory: （可选）字符串 - 保存激活值的位置（如果 save 为 True）。
• data_format: （可选）字符串 - 取值为 "channels_last"（默认）或 "channels_first"。
• reshape_1d_layers: （可选）布尔值 - 尝试将大型 1D 层重塑为正方形或矩形。
• fig_size: （可选）(float, float) - 宽度、高度，单位为英寸。

输入数据的维度顺序。"channels_last" 对应于形状为 (batch, steps, channels) 的输入（Keras 中时间序列数据的默认格式），而 "channels_first" 对应于形状为 (batch, channels, steps) 的输入。

将激活值以热图形式叠加在图像上显示

keract.display_heatmaps(activations, input_image, directory='.', save=False, fix=True, merge_filters=False)

为每层的所有滤波器绘制激活值热图，并将其叠加在输入图像上。

输入参数：

• activations: 将层映射到其激活值的字典（get_activations 的输出）。
• input_image: NumPy 数组 - 作为 x 传递给 get_activations 的图像。
• directory: （可选）字符串 - 存储热图的位置（如果 save 为 True）。
• save: （可选）布尔值 - 如果为 True，则保存热图而不是显示。
• fix: （可选）布尔值 - 如果为 True，将对错误的图像进行自动检查和修复。
• merge_filters: （可选）布尔值 - 如果为 True，则为每层生成一张包含所有滤波器平均值的热图；如果为 False，则为每层中的每个滤波器分别生成一张热图。

获取可训练权重的梯度

keract.get_gradients_of_trainable_weights(model, x, y)

• model: 一个 keras.models.Model 对象。
• x: 作为输入馈送到模型的 NumPy 数组。如果是多输入，则 x 应为 List 类型。
• y: 标签（NumPy 数组）。遵循 Keras 规范。

输出是一个字典，将每个可训练权重映射到其关于 x 和 y 的梯度值。

获取激活值的梯度

keract.get_gradients_of_activations(model, x, y, layer_name=None, output_format='simple')

• model: 一个 keras.models.Model 对象。
• x: 用于作为模型输入的 NumPy 数组。如果是多输入情况，x 应为列表类型。
• y: 标签（NumPy 数组）。遵循 Keras 的约定。
• layer_name: （可选）指定要返回激活值的层名称。
• output_format: 改变函数输出字典的键名格式。
  • simple: 输出键将与 Keras 层的名称一致。例如，Dense(1, name='d1') 将返回 {'d1': ...}。
  • full: 输出键将与输出层的完整名称匹配。在上述例子中，它将返回 {'d1/BiasAdd:0': ...}。
  • numbered: 输出键将是基于模型中各层定义顺序的索引范围。

返回值：字典 {层名称（由 output_format 指定） -> 该层输出/节点的梯度激活值（NumPy 数组）}。

输出是一个字典，将每一层映射到其关于输入 x 和标签 y 的梯度值。

将激活值保存为 JSON 文件

keract.persist_to_json_file(activations, filename)

• activations: 激活值（层到数值的字典）
• filename: 输出文件名（JSON 格式）

从 JSON 文件加载激活值

keract.load_activations_from_json_file(filename)

• filename: 要读取激活值的文件名（JSON 格式）

返回激活值。

示例

提供了以下示例：

• keras.models.Sequential - mnist.py
• keras.models.Model - multi_inputs.py
• 循环神经网络 - recurrent.py

以 LeNet 网络处理 MNIST 数据集为例，我们可以获取批次大小为 128 的激活值：

conv2d_1/Relu:0
(128, 26, 26, 32)

conv2d_2/Relu:0
(128, 24, 24, 64)

max_pooling2d_1/MaxPool:0
(128, 12, 12, 64)

dropout_1/cond/Merge:0
(128, 12, 12, 64)

flatten_1/Reshape:0
(128, 9216)

dense_1/Relu:0
(128, 128)

dropout_2/cond/Merge:0
(128, 128)

dense_2/Softmax:0
(128, 10)

我们可以对这些激活值进行可视化。以下是使用 VGG16 的另一个示例：

cd examples
pip install -r examples-requirements.txt
python vgg16.py

一只猫。

VGG16 第一卷积层的输出。

此外，我们还可以可视化激活值的热图：

cd examples
pip install -r examples-requirements.txt
python heat_map.py

限制与改进方向

在某些特定情况下，Keract 对包含子模型的复杂模型支持不够完善。欢迎 fork 本仓库并提交 PR 来修复这些问题！

引用

@misc{Keract,
  author = {Philippe Remy},
  title = {Keract：用于可视化激活值和梯度的库},
  year = {2020},
  publisher = {GitHub},
  journal = {GitHub 仓库},
  howpublished = {\url{https://github.com/philipperemy/keract}},
}

贡献者

Keract 快速上手指南

Keract 是一个用于提取和可视化 TensorFlow/Keras 模型各层激活值（Activations）和梯度（Gradients）的轻量级库。它支持 LSTM、卷积神经网络等多种架构，帮助开发者直观地理解模型内部运作。

注意：当前版本兼容 TensorFlow 2.9 至 2.15。暂不支持 TensorFlow 2.16 及以上版本。

环境准备

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

• 操作系统：Linux, macOS 或 Windows
• Python 版本：3.7+
• 核心依赖：
  • TensorFlow (版本范围：2.9 - 2.15)
  • Keras (通常随 TensorFlow 内置)
  • Matplotlib (用于可视化)
  • NumPy

安装步骤

您可以直接使用 pip 进行安装。国内用户推荐使用清华或阿里镜像源以加速下载。

标准安装：

pip install keract

使用国内镜像源加速安装：

pip install keract -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下是最简单的使用示例，演示如何构建一个多输入模型并提取所有层的激活值。

1. 提取激活值 (Get Activations)

此代码将创建一个简单的 Keras 模型，传入随机数据，并获取每一层的输出张量（Numpy 数组）。

import numpy as np
from tensorflow.keras import Input, Model
from tensorflow.keras.layers import Dense, concatenate
from keract import get_activations

# 1. 定义模型
i1 = Input(shape=(10,), name='i1')
i2 = Input(shape=(10,), name='i2')

a = Dense(1, name='fc1')(i1)
b = Dense(1, name='fc2')(i2)

c = concatenate([a, b], name='concat')
d = Dense(1, name='out')(c)
model = Model(inputs=[i1, i2], outputs=[d])

# 2. 准备输入数据 (多输入情况下 x 应为列表)
x = [np.random.uniform(size=(32, 10)), np.random.uniform(size=(32, 10))]

# 3. 获取激活值
# auto_compile=True 会在需要时自动编译模型
activations = get_activations(model, x, auto_compile=True)

# 4. 打印结果形状
for layer_name, activation in activations.items():
    print(f"{layer_name} -> {activation.shape}")

输出示例：

i1 -> (32, 10)
i2 -> (32, 10)
fc1 -> (32, 1)
fc2 -> (32, 1)
concat -> (32, 2)
out -> (32, 1)

2. 可视化激活值 (Display Activations)

获取激活值后，可以使用 display_activations 直接绘制图像查看。

from keract import display_activations

# 将上一步获取的 activations 字典传入
# cmap: 颜色映射，save: 是否保存文件，fig_size: 画布大小
display_activations(activations, cmap="viridis", save=False, fig_size=(12, 12))

3. 进阶功能：热力图与梯度

除了基础激活值，Keract 还支持生成叠加在原图上的热力图以及计算梯度。

• 生成热力图 (适用于图像模型，如 VGG, ResNet)：

  from keract import display_heatmaps
  # input_image 是原始输入图像的 numpy 数组
  display_heatmaps(activations, input_image, save=False)
  

• 获取权重梯度：

  from keract import get_gradients_of_trainable_weights
  # y 是对应的标签
  gradients = get_gradients_of_trainable_weights(model, x, y)
  

• 获取激活值的梯度：

  from keract import get_gradients_of_activations
  grad_activations = get_gradients_of_activations(model, x, y)
  

4. 数据持久化

您可以将提取的激活值保存为 JSON 文件以便后续分析。

from keract import persist_to_json_file, load_activations_from_json_file

# 保存
persist_to_json_file(activations, 'my_activations.json')

# 加载
loaded_activations = load_activations_from_json_file('my_activations.json')