1. 从一行文件名说起：show_featuremap.py 到底在解决什么问题

第一次看到show_featuremap.py这个文件名，很多人会下意识觉得它只是个“小工具脚本”——毕竟名字里带show，听起来像是随手写来打印点东西的临时文件。但真正在卷积神经网络（CNN）的调试和可视化环节里摸爬滚打过的人都知道，一个能把特征图（feature map）稳定、清晰、可对比地展示出来的脚本，往往比训练脚本本身还难写好。原因很简单：训练脚本有明确的损失函数和优化目标，跑完看 loss 曲线就行；而特征图可视化没有标准答案，它面对的是高维张量、通道冗余、数值范围漂移、可视化失真等一系列“看起来能跑、实际上看不出问题”的坑。

show_featuremap.py的核心任务，是把卷积层输出的中间激活值（activation）从[N, C, H, W]这样的四维张量，转换成人类眼睛能理解、能对比、能判断“这个卷积核到底学到了什么”的图像网格。它通常出现在模型调试、论文配图、教学演示、模型可解释性分析这几类场景里。适合阅读这篇内容的人包括：正在训练自己第一个 CNN、想看看卷积层到底在“看”什么的学生；需要为技术报告或论文准备特征图对比图的工程师；以及在做模型压缩、剪枝、量化时，想通过特征图变化判断哪一层最敏感的研究者。

我见过太多人把特征图可视化写成“取一个 batch，循环通道，plt.imshow一下”就完事。结果出来的图要么一片漆黑，要么全白，要么通道之间毫无对比度，最后得出“我的模型好像没学到东西”的错误结论。问题往往不在模型，而在可视化脚本本身。show_featuremap.py这个标题背后，真正值得拆解的是一整套关于张量处理、归一化策略、通道排布、色彩映射和批量对比的工程细节。下面我就按实际写这个脚本时会遇到的顺序，把每个环节的“为什么”和“怎么做”讲透。

2. 特征图可视化前必须想清楚的三个张量问题

2.1 维度顺序：NCHW 还是 NHWC，差一步就全错

卷积层输出的张量维度顺序取决于你用的框架。PyTorch 默认是[N, C, H, W]，TensorFlow/Keras 默认是[N, H, W, C]。show_featuremap.py第一步要做的不是画图，而是确认维度语义。我踩过最典型的坑是：拿到一个[1, 64, 56, 56]的张量，想当然地按[N, H, W, C]去取feature_map[0, :, :, 0]，结果取出来的是第一个通道的第一行，画出来是一条细线，还以为是模型输出异常。

正确的做法是先打印feature_map.shape，然后根据框架和层类型判断。如果是 PyTorch 的nn.Conv2d输出，几乎可以确定是[N, C, H, W]。取第n个样本、第c个通道的特征图，应该写feature_map[n, c, :, :]。如果是 Keras 的Conv2D输出，则是feature_map[n, :, :, c]。这个顺序一旦搞反，后续所有归一化和排布都会错位。

提示：在脚本里加一行assert或打印语句确认维度，比事后对着黑图排查半小时要划算得多。我习惯在show_featuremap.py开头写一个_infer_layout(shape)的小函数，根据维度数量和典型尺寸范围给出提示，虽然不能百分百自动判断，但能拦住大部分低级错误。

2.2 通道数量：64 个通道不可能一张一张看

一个标准的卷积层动辄输出 64、128、256 个通道。如果每个通道单独弹一个窗口，看完一层要关 64 次图，效率极低，而且无法横向对比。show_featuremap.py必须解决“多通道网格排布”的问题。常见做法是取前k个通道（比如 16 或 32 个），排成rows × cols的网格。这里有个经验：网格的行列数尽量接近正方形，比如 16 个通道排成 4×4，32 个排成 4×8 或 6×6（留空）。行列差距太大时，人眼对通道间差异的感知会下降。

另一个容易被忽略的点是通道选择策略。直接取前 16 个通道不一定有代表性，因为通道顺序在训练后并没有语义排序。更合理的做法有两种：一是按通道激活值的方差排序，取方差最大的前 k 个，这些通道通常包含更丰富的空间结构；二是随机采样，适合快速浏览整体情况。我在实际调试时，通常先用随机采样看整体，再用方差排序看重点通道。

2.3 数值范围：为什么你的特征图总是“一片灰”

原始特征图的数值范围可能非常宽，比如从 -12.7 到 8.3，也可能非常窄，比如集中在 0.001 附近。直接丢给imshow，默认会按数据的最小最大值映射到 0-255，如果存在极端离群值，大部分像素就会被压缩到很窄的灰度区间，看起来就是一片灰。这就是“模型没学到东西”错觉的最大来源。

show_featuremap.py里必须做归一化，但归一化策略有讲究。最简单的是逐通道 min-max 归一化：对每个通道单独计算(x - min) / (max - min + eps)。这样每个通道都能充分利用 0-1 的显示范围，通道之间的相对强度关系虽然被抹掉了，但空间结构最清晰。另一种是全局归一化：所有通道用同一个 min 和 max，保留通道间强度对比，但弱通道可能看不清。我的建议是：调试空间结构时用逐通道归一化，对比通道强度时用全局归一化，脚本里最好把两种模式都做成参数。

3. 把张量变成图像：归一化、色彩映射与网格拼接的实操细节

3.1 逐通道归一化的实现与边界情况

逐通道归一化的代码看起来简单，但有几个边界情况必须处理。第一，max - min可能为 0，比如某个通道经过 ReLU 后全是 0，这时候除法会得到 NaN。必须加一个极小值eps，比如1e-8。第二，如果通道内存在 NaN 或 Inf（训练不稳定时常见），归一化会污染整个通道，最好先做torch.nan_to_num或np.nan_to_num。第三，归一化后的数据类型要转成float32或uint8，imshow对uint8的 0-255 和float的 0-1 处理方式不同，混用会导致显示异常。

我通常会在show_featuremap.py里写一个normalize_channel(fm, mode='per_channel')函数，内部用numpy或torch实现，并加一个clip_percentile参数。有时候极端值只占几个像素，用 1% 和 99% 分位数做裁剪再归一化，视觉效果比直接用 min-max 更稳。这个技巧在可视化 ReLU 后的特征图时特别有用，因为 ReLU 会把负值全压成 0，导致 min 恒为 0，max 受少数强激活影响很大。

3.2 色彩映射：灰度、jet 还是 viridis

imshow默认用viridis，但特征图可视化里最常用的其实是灰度图和jet。灰度图适合看空间结构，jet适合看强度对比，但jet有个著名问题：它的亮度变化不是单调的，会在黄色区域产生虚假的“高亮带”，容易误导判断。viridis和magma是感知均匀的，亮度单调递增，更适合定量对比。我的习惯是：论文配图用viridis或gray，快速调试用jet因为对比强烈。

还有一个细节是vmin和vmax的设置。如果已经做了逐通道归一化到 0-1，就显式设置vmin=0, vmax=1，避免imshow自动缩放导致不同子图之间的对比失效。这个坑我在早期经常踩：每个子图单独imshow时看起来都正常，拼在一起才发现有的通道被自动拉伸了，通道间根本没法比。

3.3 网格拼接：用 subplot 还是手动拼大图

matplotlib的subplot是最直观的网格方式，但通道数多的时候，子图之间的间距、标题、坐标轴会占用大量空间，而且保存高分辨率图时容易错位。更可控的做法是手动创建一个大的numpy画布，把每个通道归一化后的图按位置填进去，最后一次性imshow。这样没有子图边框，通道之间紧密排列，适合做论文里的特征图对比图。

手动拼接的关键是计算画布尺寸和填充位置。假设每个通道图是h × w，网格是rows × cols，画布就是(rows * h, cols * w)。填充时注意numpy的行列顺序和图像坐标的对应关系。我一般会加 1-2 像素的间隔线，用固定值（比如 0.5）填充，这样通道边界清晰，不会糊成一片。如果通道数不够填满网格，剩余位置填 0 或留白，不要拉伸图像。

4. 让脚本真正好用：批量对比、层间追踪与保存策略

4.1 一次看多层：层间特征图对比的组织方式

单独看一层的特征图，只能判断“这一层有没有学到东西”，但很难判断“学得对不对”。真正有价值的调试是层间对比：把conv1、conv2、conv3的输出按列排布，同一列是同一层，同一行是不同输入样本。这样一眼就能看出感受野如何逐层扩大、特征如何从边缘纹理变成语义部件。

show_featuremap.py如果只支持单层，价值会大打折扣。我的做法是让脚本接受一个“层名列表”和“输入样本列表”，内部用 hook 或直接调用中间层输出，收集所有需要的特征图，然后按样本 × 层的网格排布。这里要注意不同层的空间尺寸可能不同，比如conv1是 56×56，conv3是 14×14，拼接前需要统一缩放到相同高度，或者按原始尺寸分别排布、用不同大小的画布。我倾向于保持原始尺寸，因为缩放会引入插值伪影，影响对特征清晰度的判断。

4.2 保存策略：PNG、PDF 还是直接进 TensorBoard

调试阶段，直接弹窗看最快，但弹窗多了会卡死。批量实验时，保存成文件更靠谱。show_featuremap.py的保存策略要考虑三点：格式、命名和目录结构。格式上，PNG 适合快速查看，PDF 适合论文（矢量图放大不糊），如果只是自己看，PNG 足够。命名上，建议包含层名_样本ID_归一化模式_时间戳，比如conv2_sample03_perchannel_20250101.png，这样事后翻文件夹能快速定位。目录结构按实验名或模型名分文件夹，避免所有图堆在一个目录里。

如果项目已经在用 TensorBoard，直接把特征图网格作为图像 summary 写进去是更优雅的方案。torch.utils.tensorboard的add_image支持[C, H, W]或[N, C, H, W]，但注意它内部会做自己的归一化，和脚本里的归一化可能冲突。我的经验是：如果要用 TensorBoard，脚本里就不要再做归一化，把原始特征图传进去，让 TensorBoard 处理；如果要自己控制归一化，就保存成文件再手动上传。

4.3 性能与内存：大 batch 和大通道数下的取舍

特征图可视化本身不涉及梯度，但中间激活值可能很大。比如一个[32, 256, 56, 56]的 float32 张量，占用约 32×256×56×56×4 字节，接近 100MB。如果同时 hook 多层，内存会迅速膨胀。show_featuremap.py里必须做取舍：要么限制 batch size（比如只取前 4 个样本），要么限制通道数（比如每层只取前 32 个通道），要么用torch.no_grad()并及时把张量转到 CPU 后释放。

我在实际使用中，通常会在脚本里加一个max_samples和max_channels参数，默认值设小一点（比如 4 和 16），需要详细看时再调大。另外，如果只是快速检查，可以把特征图先下采样到较小尺寸再可视化，比如用adaptive_avg_pool2d降到 28×28，这样内存和显示压力都小很多，空间结构仍然可辨。

5. 那些只有踩过才知道的坑：从黑图到误判的完整排查链路

5.1 黑图排查：从数据范围到显示管道的逐层检查

第一次跑show_featuremap.py出来全黑，是最常见的情况。排查要按管道顺序来，不要跳步。第一步，打印特征图的min、max、mean、std。如果max和min都是 0，说明这一层输出全零，可能是 ReLU 把负值全杀了，或者输入本身有问题。如果max很大但mean接近 0，说明存在极端离群值，归一化被少数像素主导。第二步，检查归一化后的范围是否在 0-1 之间，有没有 NaN。第三步，检查imshow的vmin、vmax和cmap设置。第四步，检查保存图像时的数据类型和通道顺序，比如 RGB 和 BGR 搞反会导致颜色异常，但不会全黑。

我遇到过一次全黑是因为特征图是float64，而imshow对float64的 0-1 范围处理正常，但保存成 PNG 时被截断成 0。后来统一转成float32再归一化就解决了。这个坑很隐蔽，因为弹窗显示正常，只有保存文件才出问题。

5.2 通道间对比失效：全局归一化与逐通道归一化的选择错误

有时候图不是全黑，但所有通道看起来都差不多，看不出差异。这通常是归一化模式选错了。如果用了全局归一化，而某个通道的激活值整体偏弱，它就会被压缩到很窄的灰度范围，看起来和其他通道一样“灰”。这时候换成逐通道归一化，弱通道的空间结构会立刻显现。反过来，如果你想比较“哪个通道响应更强”，逐通道归一化会抹掉强度信息，必须用全局归一化。

我的建议是在show_featuremap.py里把两种模式都实现，并且默认用逐通道，因为调试空间结构的需求更常见。如果要做通道强度对比，可以额外输出一个“通道平均激活值”的柱状图，比看灰度图更准确。

5.3 层间尺寸不一致导致的拼接错位

层间对比时，不同层的特征图尺寸不同，直接按相同网格拼接会错位。比如conv1是 56×56，conv2是 28×28，如果都按 4×4 网格拼，conv2的每个子图只有conv1的四分之一大，视觉上不协调。解决办法有两种：一是按层分别拼接，每层单独一张图，图与图之间用标题区分；二是统一缩放到相同高度，但保持宽高比，用白色填充。我倾向于第一种，因为缩放会模糊特征细节，而层间对比本来就是为了看细节变化。

如果一定要拼在一张图里，可以用matplotlib的GridSpec做不等宽布局，让每层的子图尺寸按原始比例分配。这个实现起来稍复杂，但效果最好。我在一个教学演示项目里用过这种方式，把conv1到conv5的输出按列排布，每列宽度按特征图尺寸递减，看起来像金字塔，非常直观。

6. 从脚本到工具：参数化设计与复用建议

6.1 用 argparse 把关键选择暴露出来

一个只能硬编码的show_featuremap.py复用价值很低。我习惯用argparse把几个关键参数暴露出来：--model（模型定义或权重路径）、--input（输入图像或张量路径）、--layers（要可视化的层名，逗号分隔）、--samples（样本索引）、--channels（每层通道数）、--norm（归一化模式）、--cmap（色彩映射）、--save-dir（保存目录）。这样同一个脚本可以在不同项目里直接用命令行调用，不需要改代码。

参数默认值要选“最安全”的：--channels 16、--norm per_channel、--cmap viridis、--samples 0。这样即使什么都不传，也能出一张可看的图，不会因为参数缺失而报错。

6.2 把可视化逻辑和模型逻辑解耦

show_featuremap.py最容易写乱的地方是把模型加载、前向传播和可视化混在一起。我的做法是拆成三个部分：load_model()负责加载模型和权重，extract_features()负责跑前向并收集中间层输出，visualize()负责归一化和绘图。这样换模型时只需要改load_model()，换可视化风格时只需要改visualize()，互不影响。

extract_features()里用 PyTorch 的register_forward_hook是最干净的方式，不需要改模型定义。hook 函数把输出存到一个字典里，key 是层名。注意 hook 会在每次前向时触发，如果模型有多个分支或循环，要确保只收集需要的层。跑完后记得remove()掉 hook，避免影响后续推理。

6.3 一个可复用的最小实现骨架

下面是我常用的一个简化版骨架，去掉了具体模型依赖，只保留核心逻辑。你可以把它作为show_featuremap.py的起点，按自己的模型和需求填充。

import argparse import numpy as np import torch import matplotlib.pyplot as plt def normalize_channel(fm, mode='per_channel', eps=1e-8): fm = np.nan_to_num(fm) if mode == 'per_channel': mn = fm.min(axis=(1, 2), keepdims=True) mx = fm.max(axis=(1, 2), keepdims=True) else: mn = fm.min() mx = fm.max() return (fm - mn) / (mx - mn + eps) def make_grid(fms, rows, cols, gap=2, fill=0.5): h, w = fms[0].shape canvas = np.full((rows * h + (rows - 1) * gap, cols * w + (cols - 1) * gap), fill, dtype=np.float32) for idx, fm in enumerate(fms[:rows * cols]): r, c = divmod(idx, cols) y = r * (h + gap) x = c * (w + gap) canvas[y:y + h, x:x + w] = fm return canvas def visualize(feature_maps, layer_name, save_path=None, cmap='viridis'): fms = normalize_channel(feature_maps, mode='per_channel') n = len(fms) cols = int(np.ceil(np.sqrt(n))) rows = int(np.ceil(n / cols)) grid = make_grid(fms, rows, cols) plt.figure(figsize=(cols * 2, rows * 2)) plt.imshow(grid, cmap=cmap, vmin=0, vmax=1) plt.title(layer_name) plt.axis('off') if save_path: plt.savefig(save_path, bbox_inches='tight', dpi=150) plt.close() if __name__ == '__main__': parser = argparse.ArgumentParser() parser.add_argument('--channels', type=int, default=16) parser.add_argument('--cmap', type=str, default='viridis') parser.add_argument('--save-dir', type=str, default='./featuremaps') args = parser.parse_args() # 这里填充模型加载、前向传播和特征提取逻辑 # 假设 feature_maps 是 [C, H, W] 的 numpy 数组 # visualize(feature_maps[:args.channels], 'conv1', ...)

这个骨架里，normalize_channel和make_grid是最核心的两个函数，几乎每个特征图可视化脚本都绕不开。你可以在此基础上加层间对比、批量样本、TensorBoard 输出等功能。

7. 一些实际使用中的个人体会

特征图可视化这件事，工具本身不复杂，难的是“看到图之后怎么判断”。我自己的经验是：不要指望一张图能告诉你模型哪里有问题，而是要通过对比来定位差异。比如同一个输入，分别看训练前和训练后的特征图，看激活模式有没有从随机变得结构化；同一个层，看不同类别的输入，看通道响应有没有类别选择性；同一个模型，看剪枝前后的特征图，看哪些通道的响应明显变弱。

另外，show_featuremap.py的输出最好和损失曲线、准确率曲线放在一起看。特征图好看不代表模型性能好，有时候模型过拟合了，特征图反而更“清晰”。反过来，特征图看起来杂乱，但验证集准确率在涨，可能只是可视化归一化没调好。把可视化当成辅助判断工具，而不是唯一依据，这个心态很重要。

最后分享一个小技巧：如果你经常需要对比不同实验的特征图，可以在脚本里加一个“固定随机种子”的选项，确保每次采样通道和样本的顺序一致。这样两次运行的结果可以直接逐像素对比，省去很多“这张图和那张图是不是同一个通道”的困惑。这个细节很小，但在长期调试中能省下大量时间。