深度学习张量转PSD分层可视化：从BCHW到可编辑文档的工程实践

我得先承认一个听起来不太搭的组合：把深度学习里的张量，直接画成 Photoshop 的 PSD 文件。这块工具最后被命名为 draw_tensor2psd_v4.py，最新跑出来的结果文件夹叫“结果0129”，里面是模拟项目 X 的一次语义分割训练在验证集上的完整分层存档。之前我习惯把中间层特征图导成 PNG 拼图，后来发现真的不够用——拼完的图没办法分层查看，想单独确认某一个通道的响应区域，只能重新写代码再导一次。于是上个月我把这个脚本彻底重写到了 v4，整个过程踩了不少坑，也顺带把输出结果从“能看的图”升级成了“能让不写代码的人直接打开做标注的文档”。

这篇主要写给三类人：一是训练 CV 模型的开发者，二是负责对模型输出做人工质检的协作人员，三是想把网络中间结果变成可交付素材的人。我会先解释为什么做这个格式转换，再拆解 v4 的核心实现管线，然后按版本演进把踩过的坑讲清楚，最后用“结果0129”里面的实际案例完整复盘一遍图层结构。

1. Tensor 和 PSD 看着不搭边，但这个转换解决了我的真实痛点

1.1 常规可视化方案的三个短板

深度学习训练中最常用的特征可视化方案，无非是直接把 tensor 转成缩略图，或者把原始数组存成 npy 之类的二进制文件。这两种方案我在不同阶段都长期用过，各自的问题也体会得很清楚。

第一种是“拼图式缩略图”。训练脚本里写一句torchvision.utils.make_grid，把 64 个通道拼成一张 8×8 的网格图，看起来效率很高，但拼完之后每个通道的细节几乎全丢了。拿一个 shape 为 [1,3,512,512] 的语义分割输出来说，三个通道分别是背景、主体、边缘，用 matplotlib 横排拼成一张图，看图的人拿到的是三张小图的并排组合。他想单独把第二个通道拉高对比度，做不到；想看看第三个通道叠加到原始图上位置对不对，也做不到。这是格式本身的局限，不是任何看图工具能解决的。

第二种是“npy 原始数组”。从保存信息的角度看，npy 是最完整的，但除了写代码的人，没人能直接看。我自己隔两周回来，也得重新写个 load 脚本、加个 normalize，才敢确认里面到底装了什么。如果要把结果发给协作的标注员或者上游业务同事，发一个 npy 过去基本等于没发。

第三种是 TensorBoard 或类似工具。这类工具在模型调试期非常有用，能直接看 scalar、graph、image 三种面板，但它的交互是围绕“开发者本机”设计的，不方便把一个训练过程的中间结果打包交付给外部协作人员。对方需要安装环境、启动服务、翻 tab，门槛太高。

1.2 为什么偏偏选 PSD 当交付格式

PSD 有几个特质，恰好是上面这些方案都缺的。

第一，原生支持多图层。每个通道可以独立成一个图层，打开之后想关哪层关哪层，想单独盯哪个通道就单独盯哪个，不会互相遮挡。第二，图层可以设置混合模式。把概率图设为 SCREEN 叠到原图上，暗部会被弱化，高响应区域会在灰度原图里直接亮起来，这种叠加效果非常适合做判读。第三，有完整的分组机制。输入、中间特征、最终输出、叠加判读可以分门别类放到不同组里，目录树一展开，整个张量的结构清清楚楚。第四，Photoshop 是通用工具，不写代码的协作人员几乎都能直接打开。

这个选择不是为了炫技，而是协作链条决定的。模型训练完之后，很多问题并不是“指标差多少”，而是“这一批结果里哪些样本的分割质量有问题”。与其在群里发十几张 PNG 让协作人员来回翻，不如直接给一个分好层的 PSD，让他们自己在画布里开关图层、放大局部、标注反馈。v4 脚本本质上就是把“模型输出”和“人工判读”这两个环节用文件格式连接起来。

1.3 脚本边界：什么时候用，什么时候别用

有个问题必须先讲清楚：不是所有 tensor 都适合往 PSD 里塞。v4 我设了几个硬边界，避免脚本被滥用。

适合的场景主要有四类：语义分割/多分类分割的概率输出、目标检测的类别 score map、多尺度特征图、生成模型的各 stage 输出。这些内容的共同点是通道之间有明确的语义区分，而且需要人眼逐层检查。不适合的场景包括：超大超高维度的稀疏特征、需要做精确数值分析的中间激活。前者放进 PSD 只会让文件臃肿到打不开，后者请继续走 npy 或者 parquet，数值分析不应该经过图像压缩通道。还有一个硬限制是单边像素不要超过两万。虽然 PSD 格式本身支持大画布，但超过一定尺寸后 Photoshop 的打开速度和内存占用都会变得不可控。

边界设清楚之后，脚本就不会被滥用。v4 在入口处加了一个 shape 和 dtype 的检查函数，不满足条件直接抛异常，宁可让用户改用其他方案，也不要生成一个谁都打不开的巨型文件。

2. v4 核心实现：从 BCHW 张量到分层文档的转换管线

2.1 输入预处理：张量归一化与伪彩色映射

tensor 进入脚本之前，通常还停留在 float32 范围，从负值到几十都有。直接把它当作灰度图写进图层，会得到一张半黑的废图。PIL 这类图像库只能理解 0-255 的整数，负值和超过 1.0 的值全部会被截断或溢出。所以每个通道都必须做独立归一化。

v4 默认采用 min-max 到 0-255 的方式，并同时在图层名称里保留原始 [min, max] 范围，方便后期判断动态范围。但这里有一个很常见的坑：如果某个通道的数值集中在 0 附近，只有个别离群点很大，min-max 会把噪声一起放大，整个图看起来全是雪花。针对这种情况，v4 额外加了一个百分位截断选项，默认取 0.5% 到 99.5% 分位作为映射区间。这个选项在处理医学影像切片时尤其有用，因为很多器官区域的灰度值占比极高，极小部分高亮值如果不做截断，会把主体区域压到几乎看不见。

单通道数据默认输出灰度图。如果用户想用伪彩色观察响应强度，v4 支持通过配置传入 colormap，内部调用 matplotlib 的 colormap 把归一化后的单通道数组映射成 RGB。这个功能我用得很多，尤其是看网络中间层的特征图时，灰度图的细节表现力远不如暖色系的伪彩色图。

import numpy as np from PIL import Image def channel_to_layer(tensor_c, cmap=None, clip=(0.5, 99.5)): # 输入是单通道 float32 tensor lo, hi = np.percentile(tensor_c, clip[0]), np.percentile(tensor_c, clip[1]) norm = np.clip((tensor_c - lo) / (hi - lo + 1e-6), 0, 1) arr = (norm * 255).astype(np.uint8) if cmap is None: rgb = np.stack([arr] * 3, axis=-1) else: cm = matplotlib.colormaps[cmap] rgb = (cm(arr / 255.0)[:, :, :3] * 255).astype(np.uint8) return Image.fromarray(rgb, "RGB"), lo, hi

这段代码虽然简单，但把 per-channel 的动态范围问题解决了。实际使用中，我强烈建议在输出文件里记录每个通道的 lo、hi，否则三个月后再看同一个 PSD，根本想不起来当时到底有没有做截断。

2.2 图层组与命名策略：让 PSD 打开后一眼看懂

图层命名是 v4 改动最多的部分。v1 时代我用的名字是 Layer_0、Layer_1，打开 PSD 之后完全不知道哪层是哪层。v4 统一了命名模板：

{scope}/{channel:02d}_{tag}_[{min:.1f},{max:.1f}]

scope 代表来源组名，比如 input、feat、prob；channel 是通道索引；tag 是外部传入的语义标签，比如 background、vessel、edge。打开图层列表，一眼就能看出这一层是哪个阶段的哪个通道、数值范围大概在什么级别。

分组策略同样有讲究。v4 按来源把图层分成四组：组 input 放原始输入，组 feat 放中间特征，组 prob 放模型概率输出，组 overlay 放各种叠加判读结果。这样设计的原因是不同角色的人会关注不同的组。模型训练者主要看 feat 和 prob，协作标注人员主要看 input 和 overlay，把分组切分好，等于给不同角色画好了浏览路径。

2.3 核心代码骨架与关键参数说明

下面给出 v4 的主流程骨架，代码做了简化，重点是展示图层组织逻辑：

def draw_tensor2psd(tensor, out_path, config): # tensor 期望输入 [B, C, H, W] assert tensor.ndim == 4, "只支持四维 BCHW 张量" layers = [] for b in range(tensor.shape[0]): for c in range(tensor.shape[1]): img, lo, hi = channel_to_layer( tensor[b, c], cmap=config.get("cmap"), clip=config.get("clip", (0.5, 99.5)) ) layer_name = f"{config.get('scope','feat')}/{c:02d}_[{lo:.2f},{hi:.2f}]" layers.append((layer_name, img, config.get("blend", "normal"))) write_psd_layers(out_path, layers, groups=config.get("groups"))

代码本身并不复杂，真正的复杂度在于“write_psd_layers”这一步。底层组装 PSd 文件时，我封装了一个 psd_adapter.py，所有和 psd-tools 版本相关的 API 调用都收在这个文件里。不同版本的 psd-tools 对图层创建、混合模式枚举的命名有差异，v3 到 v4 的过程中我没少被这个坑绊倒。封装之后，库升级时只需要改一个适配文件，主流程完全不动。

2.4 输出落盘：为什么 v4 改成了边转换边写入

v3 版本的内存问题非常严重。当时的流程是先把所有通道的 PIL.Image 对象塞进一个 list，等全部生成完再统一交给组装器。跑小 tensor 没问题，但有一次导出一批 16 个 batch、每个 batch 128 通道的高分辨率特征图，每个通道图像换算出来几百 KB，堆叠起来就是几个 GB，加上 Python 对象和图表库的临时内存，16GB 内存的机器直接卡死。v4 改成生成一个通道就压缩一个、写入一个临时块，最后再统一组装 PSD 文档结构。内存峰值直接降到原来的十分之一左右。代价是过程不可断点续传，但 PSD 写入本身很快，这点代价完全可接受。

3. 从 v1 到 v4，我踩过的那些真实坑

3.1 float32 直接写图层导致的半黑图

第一次写 v1 时，我把 float32 的 tensor 直接丢给 PIL，输出结果是一大片暗色、完全不可用的图。原因在上面提过：PIL 只能理解 0-255 整数，而我的 tensor 里负值很多，正值又大于 255，直接转换时全部被截断或者溢出，视觉表现就是半黑半花。后来所有入口都强制走 channel_to_layer 这个归一化函数，问题才算根治。

这个坑看起来很低级，但很容易阴魂不散。尤其是当你从某个项目拷贝代码到另一个项目时，新项目的 tensor 范围可能不是 0-1，而是[-5, 20]，换了环境就忘记检查，输出又会变成黑图。

3.2 转置与坐标系方向：HWC 和 WxH 的战争

PIL 的 Image.size 参数顺序是 (W, H)，而 numpy 数组的习惯是 (H, W, C)。第一次实现时，我把 tensor[b, c] 这个二维数组直接转成了 Image，方向搞反，输出图片整体转了 90 度。更麻烦的是，当输入切片本身做过坐标准换，转置方向会被叠加放大，看起来要么是左右镜像，要么是上下颠倒，很难一眼发现问题。

v4 中所有涉及 shape 的地方都统一走一个 shape_to_size 辅助函数，不再手写 tuple。同样的规则用在 colormap 映射后，必须保证拿到的是 (H, W, C) 的连续数组，然后再交给 PIL。这个辅助函数看起来多此一举，但在我踩过两次转置坑之后，已经成为所有图像处理入口的标配。

3.3 混合模式枚举在不同版本里的兼容问题

v3 之前，我在代码里直接写字符串 "screen"，低版本的 psd-tools 能识别，但高版本根枚举名变了，要求传 BlendMode.SCREEN，而且大小写不敏感问题也坑过一次。混合模式一旦写错，PSD 打开后图层的显示效果完全不对，甚至有些库版本会静默忽略错误模式，让你以为没生效。

v4 做了两层适配：先从配置读字符串，再映射到当前版本的枚举，映射表单独放在 constants.py。实测下来，SCREEN 和 NORMAL 是最稳的，SCREEN 适合高响应区域叠加，NORMAL 适合原值显示。COLORDODGE 这类混合模式虽然在某些场景视觉效果很强，但会让部分轻量看图软件渲染崩溃，我默认不推荐。

下面是我常用的混合模式对照表，写配置时可以直接参考：

3.4 16 位深度：看着专业，实际兼容性一塌糊涂

v4 中间版本试验过 16 位深度输出。16 位图层的理论优势是动态范围更精细，能保留更多浮点信息，但实际使用时的兼容性问题让人头大。Photoshop 能正常打开，但很多轻量看图软件直接不识别；psd-tools 自己对 16 位的合成支持也不一致，预览图层时经常整层渲染成黑色。考虑到交付对象不一定都用桌面版 PS，最终 v4 默认输出 8 位 RGB。16 位只保留了一个实验开关，默认关闭。

如果你确实需要 16 位输出做严谨的数值观察，我建议不要把希望全压在 PSD 上，直接保留 npy 原始数据才是更负责任的做法。PSD 在这个场景里更适合做“人眼判读层”，而不是数值存储层。

3.5 图层数量膨胀与 PSD 性能

图层数超过几百层后，Photoshop 打开和切换图层都会明显卡顿。v4 加了一个 max_layers 参数，默认把相似语义的通道合并成一张多行拼图图层。例如把“所有背景类预测”合并成一张，而不是把 512 个通道全部展开。这个策略牺牲了一部分单独查看的灵活性，换来了文件的可打开性。在“结果0129”里，我最终用的是 32 层结构，每个图层都有明确含义，PS 打开速度也很快。

4. 结果0129 实战复盘：一个分割模型输出的图层拆解

4.1 为什么叫“结果0129”

这个文件夹叫结果0129，原因很朴素：它是 v4 脚本跑出来的第 129 组输出，而跑数据的那天正好是 1 月 29 日。文件名带着日期和序号一起，后续整理时不用再翻实验记录，看目录名就能推断出大致的时间线。

4.2 数据与模型情况

模拟项目 X 的任务是从 512×512 的单通道灰度切片中分割血管结构。模型是轻量 U 型结构，输入是 1×512×512，输出是 [1,3,512,512]，三个通道分别预测背景、血管主干、血管分支，每通道的数值范围都在 0 到 1 之间。验证集一共 20 个切片，我用 v4 脚本全部转成了 PSD，文件名格式是 0129_CTA_slice_0001.psd。输入数据是脱敏后的模拟切片，没有涉及真实患者信息，只看算法效果。

4.3 PSD 打开后的图层结构

“结果0129”里其中一份 PSD 的图层结构如下：

组01_输入 ├─ slice_0001_gray [0,255] 组02_模型输出 ├─ C00_background [0.00,1.00] ├─ C01_vessel_main [0.00,0.98] └─ C02_vessel_branch [0.00,0.87] 组03_叠加判读 ├─ main_screen SCREEN ├─ branch_screen SCREEN └─ main_mask_05 MULTIPLY 组04_伪彩 ├─ C01_heat_main └─ C02_heat_branch

这个结构完全围绕人工判读设计。组01 是最原始的输入，用来和输出结果对齐坐标；隐藏掉其他组时，它就是一张干净的灰度切片。组02 是纯模型输出，不带任何后期处理，怀疑模型问题的时候可以直接看原始概率。组03 是给不写代码的协作人员用的，默认打开时，彩色图层叠在灰度原图上，血管主干和分支的高响应区域会直接亮起来，一眼就能看出预测位置准不准。组04 负责细节观察，暖色伪彩能放大微小的响应差异。

4.4 和传统缩略图方案的实际对比

同一份验证集，传统流程会输出一张 4×5 的缩略图拼图，其实用性有明显短板。第一，有问题的区域没法放大到局部。第二，三通道概率图叠在一起时互相遮挡，视觉判断容易失真。第三，协作人员拿到拼图后想反馈“第几张图哪个位置有问题”，只能靠文字描述，沟通成本很高。

PSD 版本的收益是直接的：协作人员打开文件后，可以自由开关图层、缩放画布、在图层上画标记。我把结果0129发给协作标注员试用，他们的反馈是可以快速把预测错误的切片单独挑出来，比之前看 PNG 拼图快很多。这里不是说 PSD 万能，只是在“模型输出交给人工质检”这个具体场景里，分层文档确实比静态拼图好用得多。

5. 后续扩展：从专用脚本到通用小工具

5.1 命令行参数化

写 v4 时我把硬编码全部抽了出来，目前脚本可以通过一个 JSON 配置文件控制输入路径、输出目录、归一化方式、colormap、混合模式、图层合并策略。下一次训练换了数据集，完全不用改代码，只改配置。这个改动虽然简单，但实际节省的时间非常多，尤其是要频繁对比多组实验中间结果时。

JSON 配置的核心字段大概长这样：

{ "input": "./results/result_0129/npz", "output": "./results/result_0129/psd", "normalize": "percentile", "clip": [0.5, 99.5], "cmap": "magma", "blend_map": { "prob": "screen", "feat": "normal" }, "max_layers": 32 }

5.2 批处理与缩略图预览

生成结果0129 时，我顺手加了 thumbnail 参数。每个 PSD 旁边会同时生成一张合层后的 preview.png，方便在文件管理器里扫一眼，不必每次打开几百 MB 的工程文件。这个功能对批量筛选非常实用。现在每个验证集切片输出时，都是一对文件：PSD 用于详细判读，preview.png 用于快速索引。

5.3 与 psd-tools 生态的边界提醒

先说一个使用前必须知道的事实：psd-tools 这类开源 PSD 组装库对高级特性支持有限，比如图层样式、蒙版、智能对象这些，我目前只用了基础图层和混合模式。如果你的需求变成“要生成带蒙版和调整层的 PSD 模板”，在这个库上硬撑会很痛苦。那种场景更适合考虑通过官方扩展机制直接控制 Photoshop 进程，从零生成带完整样式的文档，不过那就是另一个话题了。

我在实际使用中的体会是：深度学习输出的可视化，重点往往不在算法本身，而在交付对象怎么看到它。一份能让协作者直接打开的 PSD，有时候比十张截图更能推动问题解决。最后再分享一个小技巧：导出时一定把每个通道的动态范围写进图层名，看图的人第一眼就知道哪个层需要拉伸。这个习惯我是从 v1 踩坑踩出来的，现在每个输出的 PSD 都沿用这套命名规则。如果你也在做模型输出的手工质检，建议下次训练完，顺手把验证集结果导成 PSD 试试。