自己平时写图像处理的代码最烦的就是数据格式来回倒腾。刚拿到一张图要喂给模型得先转成数组再转成张量输出结果想存下来看一眼又得从张量折腾回数组再变回图片。每一步都有一堆细节稍微不注意要么报错要么图片颜色不对要么干脆跑出来的结果和想象中完全不是一回事。这篇东西就专门梳理一下 NumPy 数组、PIL Image、PyTorch Tensor 之间的互转方法把最常用的几个工具np.array()、Image.fromarray()、torch.from_numpy()、tensor.numpy()讲透包括每个函数的适用场景、常见坑、还有不同场景下的最佳实践。如果你也经常在这些格式之间反复横跳这篇文章应该能帮你省下不少排查问题的时间。1. 为什么数据格式互转是个大坑先说一个常见的场景你从某个数据集里读了一张图它是 PIL Image 格式然后你打算对它做一些缩放、裁剪、归一化发现用 NumPy 操作最顺手于是转成数组折腾完要训练了发现模型要的是 PyTorch Tensor于是再转成张量。这一通操作看着没什么其实每一步都有讲究。1.1 三种数据结构到底是什么很多人一上来就互转其实根本没搞明白这三种东西的本质。PIL Image 是图像在内存里的一种“打包”形式除了像素数据它还记录了宽、高、颜色模式之类的元信息就像一个装照片的相框照片本身在里面但相框额外告诉你这张照片是多大的、是彩色还是黑白。NumPy 数组则是纯粹的数值容器图像转成数组后就是一堆排好的数字三维的话长这样高度、宽度、通道数HWC。它没有“图像”的概念只是一堆可以随意做数学运算的数字。PyTorch Tensor 在数据结构上和 NumPy 数组有点像但它额外绑定了设备CPU/GPU、梯度、计算图这些属性更像是一个“长了眼睛”的数组——它知道自己在哪里、需要不需要算梯度、能不能反向传播。1.2 互转的根本目的是什么互转不是为了炫技而是因为在不同阶段你需要不同数据结构提供的能力图像读写和可视化最好用 PIL Image因为它天然支持保存成各种图片格式打开、压缩、显示都方便图像算法处理最好用 NumPy 数组因为可以直接下标索引像素、做矩阵运算、配合 OpenCV 之类的库处理模型训练和推理最好用 Tensor因为深度学习框架的计算图、自动求导、GPU 加速全部基于 Tensor。所以互转的本质就是在正确的时间把数据放在正确形态的容器里。1.3 转换思维要建立在哪里我见过很多人学互转就是死记 API今天记了np.array()明天用了torch.from_numpy()结果哪天换了个场景就懵了。实际上你只要建立一个坐标系图像是“人看的”数组是“算着用的”张量是“喂模型的”那转换方向就是按照流程来的人看的 → 算着用的 → 喂模型的反过来则是喂模型的 → 算着用的 → 人看的。理解了这条链路所有 API 就都串起来了。2. 核心转换四件套实战直接上代码把每个函数的用法、底层逻辑和注意事项全部拆一遍。2.1 np.array()从 PIL Image 到 NumPy 数组把一个 PIL Image 转成 NumPy 数组最简单的方法就是import numpy as np from PIL import Image # 随便打开一张图 img Image.open(example.jpg) img_array np.array(img) print(img_array.shape) # 例如 (480, 640, 3) —— 高480、宽640、3通道 print(img_array.dtype) # 通常是 uint8这里有个关键认知np.array()并不会改变数据本身的存储内容它只是把 PIL Image 内部的数据“暴露”成数组的形态。所以当你用img_array[0, 0]去修改第一个像素时要小心——在某些情况下这个修改也会反映到原图对象上。不过实际测试下来PIL Image 转数组之后数组通常是独立的内存拷贝改数组不会影响原图这是一个容易搞混的点。注意事项np.array()生成的是uint8类型的数组取值范围 0~255形状是(H, W, C)注意不是(C, H, W)。这一点太重要了几乎所有初学者都会在这上面栽一次如果图是RGBA模式数组形状就是(H, W, 4)多出一个 Alpha 透明度通道。我实际使用中的建议如果你要对数组做归一化比如除以 255 转成浮点数千万不要在uint8数组上操作——先转成float32再做除法否则会得到一堆 0 和 1 的截断结果。2.2 Image.fromarray()从 NumPy 数组到 PIL Image从数组转回图片主力函数是Image.fromarray()# 承接上面的 img_array img_recovered Image.fromarray(img_array) # 保存看看 img_recovered.save(recovered.jpg)这个函数的底层逻辑是它根据数组的 dtype 和形状自动推断应该以什么模式来解读数组。对于常见的uint8数组形状(H, W)→ 模式L灰度图形状(H, W, 3)→ 模式RGB形状(H, W, 4)→ 模式RGBA。最容易踩的坑dtype 不对。如果你把一个float32的数组直接传给Image.fromarray()它会报错或者生出一个异常图片。比如# 这里会报错因为 float32 不在 PIL 支持的范围 bad_array np.random.rand(100, 100, 3).astype(np.float32) Image.fromarray(bad_array) # ValueError: ndarray is not a PIL image解决办法是先把浮点数组转换到uint8范围一般有两种思路# 如果数据本身在 0~1 范围先乘以 255 再转 uint8 normalized_img (bad_array * 255).astype(np.uint8) Image.fromarray(normalized_img) # 如果数据在任意范围需要做 clip 防止越界 clipped np.clip(bad_array, 0, 255).astype(np.uint8) Image.fromarray(clipped)2.3 torch.from_numpy()从 NumPy 数组到 PyTorch Tensor这是训练链路中最常用的一步。把一个 NumPy 数组转成 Tensor 的推荐做法是import torch import numpy as np array np.random.rand(3, 224, 224).astype(np.float32) tensor torch.from_numpy(array)这里有一个极其重要的底层机制torch.from_numpy()转换出来的 Tensor 和原来的 NumPy 数组共享底层内存。也就是说你改了数组Tensor 也会跟着变反过来也一样。这既是一个特色也是一个隐患。举例来说arr np.ones((3, 3), dtypenp.float32) t torch.from_numpy(arr) arr[0, 0] 99 print(t) # 输出里 (0, 0) 位置也会是 99因为底层是同一块内存在训练过程中如果你用内存共享的方式改造数据需要特别注意不能无意识地修改 NumPy 数组导致 Tensor 变化。反过来如果希望转换之后不再受原数组影响可以显式加一个.clone()t torch.from_numpy(arr).clone()关于 dtype 的细节torch.from_numpy()对类型是有要求的NumPy dtype对应 Tensor dtypefloat32torch.float32float64torch.float64int64torch.int64uint8torch.uint8float16不支持直接转需要先转float32再转int8支持但 PyTorch 对int8的支持有限要注意运算如果你搞了一个float16的 NumPy 数组torch.from_numpy()会直接报错需要先转成float32。2.4 tensor.numpy()从 PyTorch Tensor 到 NumPy 数组反向转换也就是把 Tensor 变成 NumPy 数组方法是最直观的tensor torch.randn(3, 224, 224) array tensor.numpy()但这个简单的函数背后有几个隐蔽条件不注意就容易踩坑第一个坑GPU 上的 Tensor 不能直接 numpy()。如果你把 Tensor 放在 GPU 上比如tensor.cuda()调用.numpy()会直接报错TypeError: cant convert cuda:0 device type tensor to numpy. Use Tensor.cpu() to copy the tensor to host memory first.解决办法是先挪回 CPUarray tensor.cpu().numpy()第二个坑需要梯度的 Tensor 要先 detach。如果一个 Tensor 是带有梯度的比如模型输出outputoutput.requires_grad为 True调用.numpy()也会报错RuntimeError: Cant call numpy() on Tensor that requires grad. Use tensor.detach().numpy() instead.解决办法是先detach()再numpy()array tensor.detach().cpu().numpy()第三个坑内存共享的问题。和torch.from_numpy()类似tensor.numpy()转换出来的数组通常也和 Tensor 共享内存。也就是说如果你后续修改了数组Tensor 也会发生变化。有时候这是好事比如想就地做预处理有时候却是灾难比如你想保留一份原始数据做对比。稳妥起见需要独立数据时加.clone()array tensor.cpu().detach().clone().numpy()2.5 四件套总结对照转换方向核心函数内存关系常见坑PIL Image → NumPynp.array()通常拷贝形状是 HWCdtype 是 uint8NumPy → PIL ImageImage.fromarray()引用共享float 数组不能直接用NumPy → Tensortorch.from_numpy()共享内存float16 不支持、dtype 需匹配Tensor → NumPytensor.numpy()共享内存GPU tensor、requires_grad 不能直接转3. 从文件到张量的全链路操作单独的 API 会了只是第一步实际开发中遇到的情况要复杂得多。接下来结合一个完整的实操示例演示一下从文件到 Tensor 的完整链路同时把归一化、维度变换这些周边操作一并处理。3.1 一个完整的图片加载与预处理流程假设你现在有一个任务训练一个图像分类模型数据集的图片都是普通的 JPEG 文件需要先读取图片、缩放到指定尺寸、转成 Tensor然后喂给模型。import numpy as np import torch from PIL import Image def load_image_as_tensor(path, target_size(224, 224)): # 1. 读取图片得到 PIL Image img Image.open(path).convert(RGB) # 统一转成 RGB避免灰度图或 RGBA 图干扰 # 2. 缩放这里用简单 resize实际训练时可以用 RandomResizedCrop 之类 img img.resize(target_size, Image.BILINEAR) # 3. PIL Image → NumPy 数组 img_array np.array(img) # shape: (224, 224, 3), dtype: uint8 print(数组形状:, img_array.shape) # 4. 归一化到 [0, 1] 区间 img_array img_array.astype(np.float32) / 255.0 # 5. 调整维度HWC → CHW深度学习框架的通用输入格式 img_array np.transpose(img_array, (2, 0, 1)) # (224, 224, 3) → (3, 224, 224) # 6. NumPy → Tensor tensor torch.from_numpy(img_array) return tensor tensor load_image_as_tensor(example.jpg) print(tensor.shape, tensor.dtype) # torch.Size([3, 224, 224]) torch.float32观察这个流程有几个地方是刻意安排的。convert(RGB)这一步防的是一张图本身是灰度模式或 PNG 带透明度通道如果不统一处理后面数组维度就不是(H, W, 3)可能会影响模型输入。维度从 HWC 转 CHW 实际上是深度学习框架的历史习惯——大多数框架内部做卷积时把通道放在第二个维度上性能更好、处理更高效。3.2 加入 Batch 维度单个图片处理完之后送入模型往往还要一个 batch 维度。比如一次预测 8 张图输入形状应该是(8, 3, 224, 224)# 继续上面的代码 tensor_single load_image_as_tensor(example.jpg) # 用 unsqueeze 在维度 0 上增加一个批量维度 tensor_batch tensor_single.unsqueeze(0) # (3, 224, 224) → (1, 3, 224, 224)如果是一次处理多张图更常见的做法是先把所有图片转成数组放在一个列表中然后统一stacktensors [] for path in [a.jpg, b.jpg, c.jpg]: tensors.append(load_image_as_tensor(path)) tensor_batch torch.stack(tensors, dim0) # (3, 3, 224, 224)为什么这里强调stack而不是cat因为cat是拼接会保留每个 Tensor 的原始维度而stack会创建新的维度。对于多个单图 Tensor维度都是(3, 224, 224)用cat拼接会沿着已有通道维度拼变成(9, 224, 224)完全不对stack会在最前面插入新维度得到(3, 3, 224, 224)才是想要的结果。3.3 反向链路从 Tensor 到可查看的图片模型推理完得到的是一个 Tensor形状通常是(1, num_classes)或者(1, C, H, W)。前者是分类结果一般直接argmax就能得到标签后者是分割图、目标检测输出或者生成模型的输出需要可视化时就涉及反向链路# 假设 output 是分割模型的输出形状 (1, 3, 224, 224)值是 float output model(tensor_batch) # 第一步去掉 batch 维度 out output.squeeze(0) # (3, 224, 224) # 第二步去掉梯度、挪回 CPU out_array out.detach().cpu().numpy() # (3, 224, 224) # 第三步CHW → HWC out_array np.transpose(out_array, (1, 2, 0)) # (224, 224, 3) # 第四步归一化到 [0, 255] 并转成 uint8 out_array np.clip(out_array, 0, 1) # 如果模型输出经过 sigmoid值在 0~1 out_array (out_array * 255).astype(np.uint8) # 第五步数组 → PIL Image result_img Image.fromarray(out_array) result_img.save(result.jpg)注意detach()和cpu()的顺序我通常习惯先detach()再cpu()因为如果 Tensor 在 GPU 上且 requires_grad 为 True直接cpu()都有可能遇到问题先detach()把计算图断开更保险。这也是老手和新手在细节处理上的区别。3.4 批量处理时的转换策略实际工程中很少一张一张处理图片一般是一次性处理大量数据。这时候如果每次都用 PIL NumPy 互转效率不会太差但要注意一些操作习惯。# 一个高效的批量读取方案 import os from PIL import Image img_dir dataset/train img_paths [os.path.join(img_dir, f) for f in os.listdir(img_dir)] arrays [] for p in img_paths: img Image.open(p).convert(RGB).resize((224, 224)) arr np.array(img).astype(np.float32) / 255.0 arr np.transpose(arr, (2, 0, 1)) arrays.append(arr) # 一次性堆叠成 (N, 3, 224, 224) data np.stack(arrays, axis0) tensor torch.from_numpy(data) print(tensor.shape) # (N, 3, 224, 224)这个方案把转换集中在一个循环里完成最后统一from_numpy比每张图独立执行一次from_numpy要少很多调用开销。要注意np.stack之后数组会变成连续内存这对torch.from_numpy是很友好的因为共享内存机制喜欢连续内存布局。如果数组是切片或者转置得到的内部可能是不连续内存torch.from_numpy时 PyTorch 内部会自动处理但效率会打折扣。4. 常见报错与排查思路速查表这部分把这些年我在转换路上遇到过的、还有身边人经常问的问题集中整理一下直接做成速查表遇到问题对着查就行。4.1 报错信息对照表报错信息原因分析解决方案ValueError: ndarray is not a PIL image传给Image.fromarray()的数组 dtype 不在 PIL 支持范围如 float32把数组转成 uint8(arr * 255).astype(np.uint8)或者arr.astype(np.uint8)TypeError: cant convert np.ndarray of type numpy.float16torch.from_numpy()不支持 float16 数组先转 float32arr.astype(np.float32)再转 TensorTypeError: cant convert cuda:0 device type tensor to numpyGPU 上的 Tensor 直接调.numpy()先.cpu()再.numpy()RuntimeError: Cant call numpy() on Tensor that requires grad带梯度的 Tensor 直接调.numpy()先.detach()再.cpu()最后.numpy()ValueError: too many dimensions: 3 2Image.fromarray()接到三维数组但最后一个维度不是 3 或 4例如形状(224, 3, 224)检查数组的维度布局是否为(H, W, C)确认转置是否正确RuntimeError: expected dtype ... but got ...模型输入 Tensor 和模型权重 dtype 不一致通常是 NumPy 端 float64 转出 double 型 Tensor在转 Tensor 前统一用.astype(np.float32)4.2 共享内存问题导致的“灵异事件”这个坑特别隐蔽值得单独讲。有次一个朋友让我帮他看代码他的模型训练着训练着loss 突然变成 NaN。排查发现他在预处理阶段用torch.from_numpy()把数据转成 Tensor之后又用同一个 NumPy 数组做了后续处理把数组覆盖了Tensor 的值也随之改变数据出现脏值。检测是否共享内存的简单方法arr np.ones((2, 2), dtypenp.float32) t torch.from_numpy(arr) arr[0, 0] 100 if t[0, 0] 100: print(共享内存修改数组会改变 Tensor)如何避免意外修改所有需要独立数据的场景转换后立刻加.clone()t torch.from_numpy(arr).clone()这个习惯非常重要。在做数据增强或者拼接数据集时我几乎每次都加clone()宁可多占一点内存也不要数据被悄悄修改。4.3 图像颜色“发蓝发绿”的迷之问题有时你用Image.fromarray()保存出来的图片颜色不对红色变成蓝色、整体偏绿。这个问题几乎可以肯定是通道顺序错了。OpenCV 读进来的图是 BGRPIL Image 是 RGB两者转成数组后的通道排列不同如果你拿一个 OpenCV 读的数组去调Image.fromarray()颜色必然错乱。# 错误示例直接用 OpenCV 的 BGR 数组转 PIL Image import cv2 cv_img cv2.imread(example.jpg) # BGR 顺序 wrong_pil Image.fromarray(cv_img) # 颜色会偏蓝 # 正确做法先把 BGR 转 RGB rgb_img cv2.cvtColor(cv_img, cv2.COLOR_BGR2RGB) correct_pil Image.fromarray(rgb_img)同样的道理如果你从 PIL Image 转数组后转给 OpenCV 显示也要先convert(RGB)再cv2.cvtColor换成 BGR。这类问题非常好排查只要确认数据的通道排列是一致的。4.4 归一化操作应该放在哪一步最后的实战总结里必须提到归一化的位置。我见过太多人在这里出问题。在 NumPy 端归一化# 0~255 的 uint8 数组转为 0~1 的 float32 数组 img_array np.array(img).astype(np.float32) / 255.0在 Tensor 端归一化# 直接在 Tensor 上用 transforms from torchvision import transforms transform transforms.Compose([ transforms.ToTensor(), # 这会把 PIL Image 或 ndarray 转成 [0,1] 范围的 Tensor transforms.Normalize(mean[0.485, 0.456, 0.406], std[0.229, 0.224, 0.225]) ])transforms.ToTensor()底层做的事很多它会把 PIL Image 或 NumPy 数组直接变成float32的 Tensor自动把维度从 HWC 改成 CHW还会自动除以 255 归一化。如果你自己已经手工做了归一化和转置再叠加ToTensor()就会出现“除以两次 255”的效果数据直接被归一到 0~0.0039 的范围模型训练直接崩掉。所以记住两条铁律如果用了ToTensor()前面不要再手工归一化如果手工归一化了就直接用torch.from_numpy()来转不要再走ToTensor()。4.5 与 Dataset 封装代码结合的转换实践实际写训练代码时我更推荐把转换全部封装在__getitem__里面这样 Module 和转换逻辑就解耦了import torch from torch.utils.data import Dataset from PIL import Image import numpy as np class ImageDataset(Dataset): def __init__(self, img_paths, transformNone): self.img_paths img_paths self.transform transform def __len__(self): return len(self.img_paths) def __getitem__(self, idx): img Image.open(self.img_paths[idx]).convert(RGB) if self.transform: # 方案A走 TorchVision 的 transform 流程 tensor self.transform(img) else: # 方案B手动转 arr np.array(img).astype(np.float32) / 255.0 arr np.transpose(arr, (2, 0, 1)) tensor torch.from_numpy(arr) return tensor, label这种封装的好处是整条链路只跟__getitem__打交道需要增删改预处理逻辑时改 transform 或改转换代码就行不会牵连到其他地方。4.6 推理阶段的转换优化在模型的推理阶段tensor.numpy()有个额外需要注意的点如果你在 GPU 上推理需要先把结果搬回 CPU这个搬运本身是有开销的。如果你要批量推理最好积攒一批结果再统一搬运而不是每张图前向一次、搬运一次。GPU 上的 CPU 搬运非常耗时挤牙膏式搬运会让推理速度骤降。另一个值得说的是如果你连续多次在推理中使用.detach().cpu().numpy()每次都会产生一次内存拷贝可以复用同一个数组接收结果来减少 GC 开销但这样要小心生命周期问题一般我建议先保证正确性能问题出现时再针对性优化。5. 实操心得与经验扩展技术点讲得差不多聊一点实操层面的体会算是一些“过来人”的建议。5.1 涉及的周边知识点互转只是表面操作真正用好它还需要配合几个常见的周边要点第一个是astype引发的数据截断。很多人转 NumPy 数组时喜欢直接.astype(np.uint8)。如果原值是浮点数 300.6转成 uint8 后不是 300而是 44溢出回绕。正确的做法是先clip到 0~255再astype否则图像会变得花屏而这个 bug 特别难排查因为你肉眼看值好像“差不多”但图像明显不对。第二个是数据类型对齐。模型训练通常要求输入是float32但 NumPy 默认的浮点类型是float64。如果你不做显式转换torch.from_numpy()会生成float64的 Tensor这时候模型权重是float32输入是float64运算时类型不匹配会报错或者 PyTorch 自动做类型转换导致额外的内存开销。始终坚持astype(np.float32)是避免这类问题的最佳习惯。第三个是np.asarray和np.array的区别。很多代码里两个混用。np.array()默认会复制数组np.asarray()尽量不复制、直接复用原来的内存。对于大尺寸图片来说如果不需要复制用np.asarray()更省内存但前提是你清楚自己在做什么。如果你要的是“独立的数组”请坚持用np.array()如果你只是想临时看成数组用np.asarray()更好。5.2 我个人的转换思路总结我现在写代码时已经形成了肌肉记忆核心只有三步先判断数据当前是什么形态再判断目标是什么形态然后选择最少操作的路径。举个例子一个数组如果是uint8类型直接torch.from_numpy()转过去再在 Tensor 端做归一化比先变成float32、再归一化、再转 Tensor 要少两步更简洁。反过来说如果数据将来要送到 PIL Image 里保存那最好不要让数据变成float32直接保持uint8用Image.fromarray()一步到位。很多时候性能不差代码也很清爽。5.3 转换性能小技巧说到性能最后补充一个我自己常用的技巧np.ascontiguousarray()。前面提到torch.from_numpy()对内存连续性有要求如果数组来自切片、转置或不连续索引PyTorch 内部可能要做一次拷贝才能创建 Tensor。为了避免这个隐式拷贝可以主动保证内存连续。arr np.random.rand(100, 100, 3).astype(np.float32) arr_transposed np.transpose(arr, (2, 0, 1)) # 转置后内存是不连续的 tensor torch.from_numpy(arr_transposed) # 这里可能产生隐形拷贝如果想要既保持转置后的逻辑布局又确保内存连续可以使用arr_contiguous np.ascontiguousarray(arr_transposed) tensor torch.from_numpy(arr_contiguous) # 无额外拷贝在大规模数据处理时这种细节对速度的影响会被放大值得在实际工程中养成习惯。6. 最后的实操建议这些东西讲完真正想说的其实就一句互转方法并不难难的是分清每个转换背后的数据语义。uint8在图像里表示像素值 0~255在 Tensor 里表示带符号整数HWC是图像数组的自然排列CHW是深度学习框架的偏好内存共享在训练迭代里是效率利器在小批量调试时是隐形炸弹。把这两三条规律刻在脑子里比记一百个 API 都管用。我自己通常会在代码里写一个统一的转换层集中管理所有格式的互转这样无论项目怎么迭代、模型怎么换所有数据入口出口都是一致的排查问题的时候也只需要看这一层。大部分项目出现数据混乱的 bug根源都是转换代码散落在各个脚本里风格还不统一。如果你也有这方面的困扰不妨先从统一封装开始改。最后再分享一个小技巧当我们调试时不确定一个数组能不能直接进模型时可以在转换后打印三样东西——shape、dtype、min/max。如果这三个值都在预期范围内那么基本可以确定转换链路没问题。原图、标签、模型输出三者之间的衔接也会因为这一步检查而变得稳妥很多。
自己平时写图像处理的代码最烦的就是数据格式来回倒腾。刚拿到一张图要喂给模型得先转成数组再转成张量输出结果想存下来看一眼又得从张量折腾回数组再变回图片。每一步都有一堆细节稍微不注意要么报错要么图片颜色不对要么干脆跑出来的结果和想象中完全不是一回事。这篇东西就专门梳理一下 NumPy 数组、PIL Image、PyTorch Tensor 之间的互转方法把最常用的几个工具np.array()、Image.fromarray()、torch.from_numpy()、tensor.numpy()讲透包括每个函数的适用场景、常见坑、还有不同场景下的最佳实践。如果你也经常在这些格式之间反复横跳这篇文章应该能帮你省下不少排查问题的时间。1. 为什么数据格式互转是个大坑先说一个常见的场景你从某个数据集里读了一张图它是 PIL Image 格式然后你打算对它做一些缩放、裁剪、归一化发现用 NumPy 操作最顺手于是转成数组折腾完要训练了发现模型要的是 PyTorch Tensor于是再转成张量。这一通操作看着没什么其实每一步都有讲究。1.1 三种数据结构到底是什么很多人一上来就互转其实根本没搞明白这三种东西的本质。PIL Image 是图像在内存里的一种“打包”形式除了像素数据它还记录了宽、高、颜色模式之类的元信息就像一个装照片的相框照片本身在里面但相框额外告诉你这张照片是多大的、是彩色还是黑白。NumPy 数组则是纯粹的数值容器图像转成数组后就是一堆排好的数字三维的话长这样高度、宽度、通道数HWC。它没有“图像”的概念只是一堆可以随意做数学运算的数字。PyTorch Tensor 在数据结构上和 NumPy 数组有点像但它额外绑定了设备CPU/GPU、梯度、计算图这些属性更像是一个“长了眼睛”的数组——它知道自己在哪里、需要不需要算梯度、能不能反向传播。1.2 互转的根本目的是什么互转不是为了炫技而是因为在不同阶段你需要不同数据结构提供的能力图像读写和可视化最好用 PIL Image因为它天然支持保存成各种图片格式打开、压缩、显示都方便图像算法处理最好用 NumPy 数组因为可以直接下标索引像素、做矩阵运算、配合 OpenCV 之类的库处理模型训练和推理最好用 Tensor因为深度学习框架的计算图、自动求导、GPU 加速全部基于 Tensor。所以互转的本质就是在正确的时间把数据放在正确形态的容器里。1.3 转换思维要建立在哪里我见过很多人学互转就是死记 API今天记了np.array()明天用了torch.from_numpy()结果哪天换了个场景就懵了。实际上你只要建立一个坐标系图像是“人看的”数组是“算着用的”张量是“喂模型的”那转换方向就是按照流程来的人看的 → 算着用的 → 喂模型的反过来则是喂模型的 → 算着用的 → 人看的。理解了这条链路所有 API 就都串起来了。2. 核心转换四件套实战直接上代码把每个函数的用法、底层逻辑和注意事项全部拆一遍。2.1 np.array()从 PIL Image 到 NumPy 数组把一个 PIL Image 转成 NumPy 数组最简单的方法就是import numpy as np from PIL import Image # 随便打开一张图 img Image.open(example.jpg) img_array np.array(img) print(img_array.shape) # 例如 (480, 640, 3) —— 高480、宽640、3通道 print(img_array.dtype) # 通常是 uint8这里有个关键认知np.array()并不会改变数据本身的存储内容它只是把 PIL Image 内部的数据“暴露”成数组的形态。所以当你用img_array[0, 0]去修改第一个像素时要小心——在某些情况下这个修改也会反映到原图对象上。不过实际测试下来PIL Image 转数组之后数组通常是独立的内存拷贝改数组不会影响原图这是一个容易搞混的点。注意事项np.array()生成的是uint8类型的数组取值范围 0~255形状是(H, W, C)注意不是(C, H, W)。这一点太重要了几乎所有初学者都会在这上面栽一次如果图是RGBA模式数组形状就是(H, W, 4)多出一个 Alpha 透明度通道。我实际使用中的建议如果你要对数组做归一化比如除以 255 转成浮点数千万不要在uint8数组上操作——先转成float32再做除法否则会得到一堆 0 和 1 的截断结果。2.2 Image.fromarray()从 NumPy 数组到 PIL Image从数组转回图片主力函数是Image.fromarray()# 承接上面的 img_array img_recovered Image.fromarray(img_array) # 保存看看 img_recovered.save(recovered.jpg)这个函数的底层逻辑是它根据数组的 dtype 和形状自动推断应该以什么模式来解读数组。对于常见的uint8数组形状(H, W)→ 模式L灰度图形状(H, W, 3)→ 模式RGB形状(H, W, 4)→ 模式RGBA。最容易踩的坑dtype 不对。如果你把一个float32的数组直接传给Image.fromarray()它会报错或者生出一个异常图片。比如# 这里会报错因为 float32 不在 PIL 支持的范围 bad_array np.random.rand(100, 100, 3).astype(np.float32) Image.fromarray(bad_array) # ValueError: ndarray is not a PIL image解决办法是先把浮点数组转换到uint8范围一般有两种思路# 如果数据本身在 0~1 范围先乘以 255 再转 uint8 normalized_img (bad_array * 255).astype(np.uint8) Image.fromarray(normalized_img) # 如果数据在任意范围需要做 clip 防止越界 clipped np.clip(bad_array, 0, 255).astype(np.uint8) Image.fromarray(clipped)2.3 torch.from_numpy()从 NumPy 数组到 PyTorch Tensor这是训练链路中最常用的一步。把一个 NumPy 数组转成 Tensor 的推荐做法是import torch import numpy as np array np.random.rand(3, 224, 224).astype(np.float32) tensor torch.from_numpy(array)这里有一个极其重要的底层机制torch.from_numpy()转换出来的 Tensor 和原来的 NumPy 数组共享底层内存。也就是说你改了数组Tensor 也会跟着变反过来也一样。这既是一个特色也是一个隐患。举例来说arr np.ones((3, 3), dtypenp.float32) t torch.from_numpy(arr) arr[0, 0] 99 print(t) # 输出里 (0, 0) 位置也会是 99因为底层是同一块内存在训练过程中如果你用内存共享的方式改造数据需要特别注意不能无意识地修改 NumPy 数组导致 Tensor 变化。反过来如果希望转换之后不再受原数组影响可以显式加一个.clone()t torch.from_numpy(arr).clone()关于 dtype 的细节torch.from_numpy()对类型是有要求的NumPy dtype对应 Tensor dtypefloat32torch.float32float64torch.float64int64torch.int64uint8torch.uint8float16不支持直接转需要先转float32再转int8支持但 PyTorch 对int8的支持有限要注意运算如果你搞了一个float16的 NumPy 数组torch.from_numpy()会直接报错需要先转成float32。2.4 tensor.numpy()从 PyTorch Tensor 到 NumPy 数组反向转换也就是把 Tensor 变成 NumPy 数组方法是最直观的tensor torch.randn(3, 224, 224) array tensor.numpy()但这个简单的函数背后有几个隐蔽条件不注意就容易踩坑第一个坑GPU 上的 Tensor 不能直接 numpy()。如果你把 Tensor 放在 GPU 上比如tensor.cuda()调用.numpy()会直接报错TypeError: cant convert cuda:0 device type tensor to numpy. Use Tensor.cpu() to copy the tensor to host memory first.解决办法是先挪回 CPUarray tensor.cpu().numpy()第二个坑需要梯度的 Tensor 要先 detach。如果一个 Tensor 是带有梯度的比如模型输出outputoutput.requires_grad为 True调用.numpy()也会报错RuntimeError: Cant call numpy() on Tensor that requires grad. Use tensor.detach().numpy() instead.解决办法是先detach()再numpy()array tensor.detach().cpu().numpy()第三个坑内存共享的问题。和torch.from_numpy()类似tensor.numpy()转换出来的数组通常也和 Tensor 共享内存。也就是说如果你后续修改了数组Tensor 也会发生变化。有时候这是好事比如想就地做预处理有时候却是灾难比如你想保留一份原始数据做对比。稳妥起见需要独立数据时加.clone()array tensor.cpu().detach().clone().numpy()2.5 四件套总结对照转换方向核心函数内存关系常见坑PIL Image → NumPynp.array()通常拷贝形状是 HWCdtype 是 uint8NumPy → PIL ImageImage.fromarray()引用共享float 数组不能直接用NumPy → Tensortorch.from_numpy()共享内存float16 不支持、dtype 需匹配Tensor → NumPytensor.numpy()共享内存GPU tensor、requires_grad 不能直接转3. 从文件到张量的全链路操作单独的 API 会了只是第一步实际开发中遇到的情况要复杂得多。接下来结合一个完整的实操示例演示一下从文件到 Tensor 的完整链路同时把归一化、维度变换这些周边操作一并处理。3.1 一个完整的图片加载与预处理流程假设你现在有一个任务训练一个图像分类模型数据集的图片都是普通的 JPEG 文件需要先读取图片、缩放到指定尺寸、转成 Tensor然后喂给模型。import numpy as np import torch from PIL import Image def load_image_as_tensor(path, target_size(224, 224)): # 1. 读取图片得到 PIL Image img Image.open(path).convert(RGB) # 统一转成 RGB避免灰度图或 RGBA 图干扰 # 2. 缩放这里用简单 resize实际训练时可以用 RandomResizedCrop 之类 img img.resize(target_size, Image.BILINEAR) # 3. PIL Image → NumPy 数组 img_array np.array(img) # shape: (224, 224, 3), dtype: uint8 print(数组形状:, img_array.shape) # 4. 归一化到 [0, 1] 区间 img_array img_array.astype(np.float32) / 255.0 # 5. 调整维度HWC → CHW深度学习框架的通用输入格式 img_array np.transpose(img_array, (2, 0, 1)) # (224, 224, 3) → (3, 224, 224) # 6. NumPy → Tensor tensor torch.from_numpy(img_array) return tensor tensor load_image_as_tensor(example.jpg) print(tensor.shape, tensor.dtype) # torch.Size([3, 224, 224]) torch.float32观察这个流程有几个地方是刻意安排的。convert(RGB)这一步防的是一张图本身是灰度模式或 PNG 带透明度通道如果不统一处理后面数组维度就不是(H, W, 3)可能会影响模型输入。维度从 HWC 转 CHW 实际上是深度学习框架的历史习惯——大多数框架内部做卷积时把通道放在第二个维度上性能更好、处理更高效。3.2 加入 Batch 维度单个图片处理完之后送入模型往往还要一个 batch 维度。比如一次预测 8 张图输入形状应该是(8, 3, 224, 224)# 继续上面的代码 tensor_single load_image_as_tensor(example.jpg) # 用 unsqueeze 在维度 0 上增加一个批量维度 tensor_batch tensor_single.unsqueeze(0) # (3, 224, 224) → (1, 3, 224, 224)如果是一次处理多张图更常见的做法是先把所有图片转成数组放在一个列表中然后统一stacktensors [] for path in [a.jpg, b.jpg, c.jpg]: tensors.append(load_image_as_tensor(path)) tensor_batch torch.stack(tensors, dim0) # (3, 3, 224, 224)为什么这里强调stack而不是cat因为cat是拼接会保留每个 Tensor 的原始维度而stack会创建新的维度。对于多个单图 Tensor维度都是(3, 224, 224)用cat拼接会沿着已有通道维度拼变成(9, 224, 224)完全不对stack会在最前面插入新维度得到(3, 3, 224, 224)才是想要的结果。3.3 反向链路从 Tensor 到可查看的图片模型推理完得到的是一个 Tensor形状通常是(1, num_classes)或者(1, C, H, W)。前者是分类结果一般直接argmax就能得到标签后者是分割图、目标检测输出或者生成模型的输出需要可视化时就涉及反向链路# 假设 output 是分割模型的输出形状 (1, 3, 224, 224)值是 float output model(tensor_batch) # 第一步去掉 batch 维度 out output.squeeze(0) # (3, 224, 224) # 第二步去掉梯度、挪回 CPU out_array out.detach().cpu().numpy() # (3, 224, 224) # 第三步CHW → HWC out_array np.transpose(out_array, (1, 2, 0)) # (224, 224, 3) # 第四步归一化到 [0, 255] 并转成 uint8 out_array np.clip(out_array, 0, 1) # 如果模型输出经过 sigmoid值在 0~1 out_array (out_array * 255).astype(np.uint8) # 第五步数组 → PIL Image result_img Image.fromarray(out_array) result_img.save(result.jpg)注意detach()和cpu()的顺序我通常习惯先detach()再cpu()因为如果 Tensor 在 GPU 上且 requires_grad 为 True直接cpu()都有可能遇到问题先detach()把计算图断开更保险。这也是老手和新手在细节处理上的区别。3.4 批量处理时的转换策略实际工程中很少一张一张处理图片一般是一次性处理大量数据。这时候如果每次都用 PIL NumPy 互转效率不会太差但要注意一些操作习惯。# 一个高效的批量读取方案 import os from PIL import Image img_dir dataset/train img_paths [os.path.join(img_dir, f) for f in os.listdir(img_dir)] arrays [] for p in img_paths: img Image.open(p).convert(RGB).resize((224, 224)) arr np.array(img).astype(np.float32) / 255.0 arr np.transpose(arr, (2, 0, 1)) arrays.append(arr) # 一次性堆叠成 (N, 3, 224, 224) data np.stack(arrays, axis0) tensor torch.from_numpy(data) print(tensor.shape) # (N, 3, 224, 224)这个方案把转换集中在一个循环里完成最后统一from_numpy比每张图独立执行一次from_numpy要少很多调用开销。要注意np.stack之后数组会变成连续内存这对torch.from_numpy是很友好的因为共享内存机制喜欢连续内存布局。如果数组是切片或者转置得到的内部可能是不连续内存torch.from_numpy时 PyTorch 内部会自动处理但效率会打折扣。4. 常见报错与排查思路速查表这部分把这些年我在转换路上遇到过的、还有身边人经常问的问题集中整理一下直接做成速查表遇到问题对着查就行。4.1 报错信息对照表报错信息原因分析解决方案ValueError: ndarray is not a PIL image传给Image.fromarray()的数组 dtype 不在 PIL 支持范围如 float32把数组转成 uint8(arr * 255).astype(np.uint8)或者arr.astype(np.uint8)TypeError: cant convert np.ndarray of type numpy.float16torch.from_numpy()不支持 float16 数组先转 float32arr.astype(np.float32)再转 TensorTypeError: cant convert cuda:0 device type tensor to numpyGPU 上的 Tensor 直接调.numpy()先.cpu()再.numpy()RuntimeError: Cant call numpy() on Tensor that requires grad带梯度的 Tensor 直接调.numpy()先.detach()再.cpu()最后.numpy()ValueError: too many dimensions: 3 2Image.fromarray()接到三维数组但最后一个维度不是 3 或 4例如形状(224, 3, 224)检查数组的维度布局是否为(H, W, C)确认转置是否正确RuntimeError: expected dtype ... but got ...模型输入 Tensor 和模型权重 dtype 不一致通常是 NumPy 端 float64 转出 double 型 Tensor在转 Tensor 前统一用.astype(np.float32)4.2 共享内存问题导致的“灵异事件”这个坑特别隐蔽值得单独讲。有次一个朋友让我帮他看代码他的模型训练着训练着loss 突然变成 NaN。排查发现他在预处理阶段用torch.from_numpy()把数据转成 Tensor之后又用同一个 NumPy 数组做了后续处理把数组覆盖了Tensor 的值也随之改变数据出现脏值。检测是否共享内存的简单方法arr np.ones((2, 2), dtypenp.float32) t torch.from_numpy(arr) arr[0, 0] 100 if t[0, 0] 100: print(共享内存修改数组会改变 Tensor)如何避免意外修改所有需要独立数据的场景转换后立刻加.clone()t torch.from_numpy(arr).clone()这个习惯非常重要。在做数据增强或者拼接数据集时我几乎每次都加clone()宁可多占一点内存也不要数据被悄悄修改。4.3 图像颜色“发蓝发绿”的迷之问题有时你用Image.fromarray()保存出来的图片颜色不对红色变成蓝色、整体偏绿。这个问题几乎可以肯定是通道顺序错了。OpenCV 读进来的图是 BGRPIL Image 是 RGB两者转成数组后的通道排列不同如果你拿一个 OpenCV 读的数组去调Image.fromarray()颜色必然错乱。# 错误示例直接用 OpenCV 的 BGR 数组转 PIL Image import cv2 cv_img cv2.imread(example.jpg) # BGR 顺序 wrong_pil Image.fromarray(cv_img) # 颜色会偏蓝 # 正确做法先把 BGR 转 RGB rgb_img cv2.cvtColor(cv_img, cv2.COLOR_BGR2RGB) correct_pil Image.fromarray(rgb_img)同样的道理如果你从 PIL Image 转数组后转给 OpenCV 显示也要先convert(RGB)再cv2.cvtColor换成 BGR。这类问题非常好排查只要确认数据的通道排列是一致的。4.4 归一化操作应该放在哪一步最后的实战总结里必须提到归一化的位置。我见过太多人在这里出问题。在 NumPy 端归一化# 0~255 的 uint8 数组转为 0~1 的 float32 数组 img_array np.array(img).astype(np.float32) / 255.0在 Tensor 端归一化# 直接在 Tensor 上用 transforms from torchvision import transforms transform transforms.Compose([ transforms.ToTensor(), # 这会把 PIL Image 或 ndarray 转成 [0,1] 范围的 Tensor transforms.Normalize(mean[0.485, 0.456, 0.406], std[0.229, 0.224, 0.225]) ])transforms.ToTensor()底层做的事很多它会把 PIL Image 或 NumPy 数组直接变成float32的 Tensor自动把维度从 HWC 改成 CHW还会自动除以 255 归一化。如果你自己已经手工做了归一化和转置再叠加ToTensor()就会出现“除以两次 255”的效果数据直接被归一到 0~0.0039 的范围模型训练直接崩掉。所以记住两条铁律如果用了ToTensor()前面不要再手工归一化如果手工归一化了就直接用torch.from_numpy()来转不要再走ToTensor()。4.5 与 Dataset 封装代码结合的转换实践实际写训练代码时我更推荐把转换全部封装在__getitem__里面这样 Module 和转换逻辑就解耦了import torch from torch.utils.data import Dataset from PIL import Image import numpy as np class ImageDataset(Dataset): def __init__(self, img_paths, transformNone): self.img_paths img_paths self.transform transform def __len__(self): return len(self.img_paths) def __getitem__(self, idx): img Image.open(self.img_paths[idx]).convert(RGB) if self.transform: # 方案A走 TorchVision 的 transform 流程 tensor self.transform(img) else: # 方案B手动转 arr np.array(img).astype(np.float32) / 255.0 arr np.transpose(arr, (2, 0, 1)) tensor torch.from_numpy(arr) return tensor, label这种封装的好处是整条链路只跟__getitem__打交道需要增删改预处理逻辑时改 transform 或改转换代码就行不会牵连到其他地方。4.6 推理阶段的转换优化在模型的推理阶段tensor.numpy()有个额外需要注意的点如果你在 GPU 上推理需要先把结果搬回 CPU这个搬运本身是有开销的。如果你要批量推理最好积攒一批结果再统一搬运而不是每张图前向一次、搬运一次。GPU 上的 CPU 搬运非常耗时挤牙膏式搬运会让推理速度骤降。另一个值得说的是如果你连续多次在推理中使用.detach().cpu().numpy()每次都会产生一次内存拷贝可以复用同一个数组接收结果来减少 GC 开销但这样要小心生命周期问题一般我建议先保证正确性能问题出现时再针对性优化。5. 实操心得与经验扩展技术点讲得差不多聊一点实操层面的体会算是一些“过来人”的建议。5.1 涉及的周边知识点互转只是表面操作真正用好它还需要配合几个常见的周边要点第一个是astype引发的数据截断。很多人转 NumPy 数组时喜欢直接.astype(np.uint8)。如果原值是浮点数 300.6转成 uint8 后不是 300而是 44溢出回绕。正确的做法是先clip到 0~255再astype否则图像会变得花屏而这个 bug 特别难排查因为你肉眼看值好像“差不多”但图像明显不对。第二个是数据类型对齐。模型训练通常要求输入是float32但 NumPy 默认的浮点类型是float64。如果你不做显式转换torch.from_numpy()会生成float64的 Tensor这时候模型权重是float32输入是float64运算时类型不匹配会报错或者 PyTorch 自动做类型转换导致额外的内存开销。始终坚持astype(np.float32)是避免这类问题的最佳习惯。第三个是np.asarray和np.array的区别。很多代码里两个混用。np.array()默认会复制数组np.asarray()尽量不复制、直接复用原来的内存。对于大尺寸图片来说如果不需要复制用np.asarray()更省内存但前提是你清楚自己在做什么。如果你要的是“独立的数组”请坚持用np.array()如果你只是想临时看成数组用np.asarray()更好。5.2 我个人的转换思路总结我现在写代码时已经形成了肌肉记忆核心只有三步先判断数据当前是什么形态再判断目标是什么形态然后选择最少操作的路径。举个例子一个数组如果是uint8类型直接torch.from_numpy()转过去再在 Tensor 端做归一化比先变成float32、再归一化、再转 Tensor 要少两步更简洁。反过来说如果数据将来要送到 PIL Image 里保存那最好不要让数据变成float32直接保持uint8用Image.fromarray()一步到位。很多时候性能不差代码也很清爽。5.3 转换性能小技巧说到性能最后补充一个我自己常用的技巧np.ascontiguousarray()。前面提到torch.from_numpy()对内存连续性有要求如果数组来自切片、转置或不连续索引PyTorch 内部可能要做一次拷贝才能创建 Tensor。为了避免这个隐式拷贝可以主动保证内存连续。arr np.random.rand(100, 100, 3).astype(np.float32) arr_transposed np.transpose(arr, (2, 0, 1)) # 转置后内存是不连续的 tensor torch.from_numpy(arr_transposed) # 这里可能产生隐形拷贝如果想要既保持转置后的逻辑布局又确保内存连续可以使用arr_contiguous np.ascontiguousarray(arr_transposed) tensor torch.from_numpy(arr_contiguous) # 无额外拷贝在大规模数据处理时这种细节对速度的影响会被放大值得在实际工程中养成习惯。6. 最后的实操建议这些东西讲完真正想说的其实就一句互转方法并不难难的是分清每个转换背后的数据语义。uint8在图像里表示像素值 0~255在 Tensor 里表示带符号整数HWC是图像数组的自然排列CHW是深度学习框架的偏好内存共享在训练迭代里是效率利器在小批量调试时是隐形炸弹。把这两三条规律刻在脑子里比记一百个 API 都管用。我自己通常会在代码里写一个统一的转换层集中管理所有格式的互转这样无论项目怎么迭代、模型怎么换所有数据入口出口都是一致的排查问题的时候也只需要看这一层。大部分项目出现数据混乱的 bug根源都是转换代码散落在各个脚本里风格还不统一。如果你也有这方面的困扰不妨先从统一封装开始改。最后再分享一个小技巧当我们调试时不确定一个数组能不能直接进模型时可以在转换后打印三样东西——shape、dtype、min/max。如果这三个值都在预期范围内那么基本可以确定转换链路没问题。原图、标签、模型输出三者之间的衔接也会因为这一步检查而变得稳妥很多。
