1. 数据管线的中枢：Dataset类在PyTorch里的角色
1.1 一上来就搞懂，为什么先学Dataset
我刚开始碰PyTorch时，照着教程跑MNIST分类，代码里有一行trainloader = DataLoader(trainset, batch_size=64, shuffle=True)，当时想都没想就往下抄。直到自己做图像分类，拿到的是一堆散落在文件夹里的图片，才发现torchvision.datasets.MNIST根本不适用，而DataLoader又必须接收一个“数据集对象”。那一刻我才意识到，Dataset不是一个锦上添花的抽象，而是PyTorch数据管线的入口。
简单说，Dataset描述的是“数据长什么样、怎么按索引拿到某一条”。DataLoader负责“按你的要求把多条数据打包、打乱、送给模型”。前者是菜谱，后者是厨师。很多新手误以为把数据读进内存再切片就是Dataset，这会在后续做大数据集、多进程加载时彻底卡住。
这篇学习日记，我打算把Dataset和TensorBoard两件事掰开揉碎，用我踩过的坑、改过的代码、画出来的那些“奇怪曲线”讲一遍，争取让看这篇的人少走一个月的弯路。
1.2 手写第一个Dataset子类
PyTorch的Dataset使用方式很简单：继承torch.utils.data.Dataset，实现__len__和__getitem__两个方法。
import os from PIL import Image from torch.utils.data import Dataset class MyImageDataset(Dataset): def __init__(self, image_dir, label_file): self.image_dir = image_dir self.samples = [] with open(label_file, 'r') as f: for line in f: path, label = line.strip().split(',') self.samples.append((path, int(label))) def __len__(self): return len(self.samples) def __getitem__(self, idx): img_name, label = self.samples[idx] img_path = os.path.join(self.image_dir, img_name) image = Image.open(img_path).convert('RGB') # 此处可以加transform，后面细说 return image, label__init__里只做了两件事：记录目录、读取样本清单。我不会在这个函数里把全部图片一次性加载到内存，因为实际项目里的图片数量可能上万张，一次性读入既浪费内存又拖慢启动。正确的思路是：__init__存“如何找到数据”，__getitem__存“找到并读出某一条数据”。
__getitem__接收一个索引，返回一个样本。在训练时，进程会反复调用它。比如batch_size=64，每处理一个batch就要调用64次。所以这个方法的性能直接影响训练速度，里面的IO操作要尽量精简。
1.3 三个方法各司其职，别把逻辑混在一起
很多初学者会在__getitem__里偷偷做全局预处理，比如给整个数据集算均值方差再归一化。这不是绝对错误，但会让每个epoch重复计算同样的统计量，不划算。正确做法：
__init__：负责元信息，如文件路径、标签映射、transform对象。__len__：返回样本总数，方便DataLoader计算epoch大小。__getitem__：负责单条数据的读取和基础变换。
为了验证是否写对，可以先不用DataLoader，手动索引几个样本：
ds = MyImageDataset('images/', 'labels.txt') print(len(ds)) img, label = ds[0] print(img.size, label)这一步能提前暴露文件路径、标签解析之类的问题，而不是等到训练时才炸出来。
2. 真正训练时Dataset要配合的三件套
2.1 transform：把预处理从训练循环里剥离
如果只做“读取图片返回PIL对象”，和模型训练之间还差得远。图像要变成tensor、要归一化、可能要resize、要做随机裁剪增强。这些操作放哪里最合适？答案在__getitem__里，而不是训练循环里。
原因很简单：Dataset里做transform，DataLoader可以用多个子进程并行执行，不会阻塞主训练流程；而且随机增强每次访问都会执行，天然适配 epoch 间的数据多样性。
以torchvision为例：
from torchvision import transforms transform_train = transforms.Compose([ transforms.Resize((224, 224)), transforms.RandomHorizontalFlip(), transforms.ColorJitter(brightness=0.2, contrast=0.2), transforms.ToTensor(), transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]) ]) transform_val = transforms.Compose([ transforms.Resize((224, 224)), transforms.ToTensor(), transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]) ])这两套transform分别绑定到训练集和验证集，训练集用随机增强，验证集只做固定缩放。如果把它们放到训练循环里，每次手动切换会非常麻烦。
另一个细节：ToTensor()会把PIL图像从HWC、0-255的uint8转换成CHW、0-1的float32。Normalize再按通道减均值、除方差。很多人在自定义Dataset里忘了这两步，结果模型训练时Loss不降，排查半天。
2.2 DataLoader参数别乱填，每个都有讲究
手动索引只能验证正确性，真正训练要用DataLoader。它的参数不多，但每个都值得认真对待：
from torch.utils.data import DataLoader train_loader = DataLoader( train_dataset, batch_size=64, shuffle=True, num_workers=4, pin_memory=True, drop_last=True )shuffle控制是否打乱。训练集需要打乱，验证集不用。num_workers是子进程数量，它决定了数据读取有多并行。设0表示主进程内同步读取，适合快速调试；设4意味着4个worker同时读数据并放入队列。看起来越大越好，但文件IO、内存带宽会成为瓶颈，设太大反而频繁切换进程，导致训练时CPU使用率飘忽不定。
pin_memory在GPU训练时能减少数据从CPU到GPU的拷贝时间，但前提是你确实在用GPU。
drop_last对最后一个不足batch大小的小尾巴处理方式。如果数据集大小是1000，batch_size是64，最后会剩40张。drop_last=True会丢弃这部分。对于batch normalization这类依赖统计量的层，小batch会引入噪声，丢弃反而更稳定。
2.3 collate_fn：批数据组装规则的自定义
当每个样本的形状一致时，DataLoader默认会把样本堆叠成batch tensor。但如果你的样本长度不一，比如NLP里的句子，或者检测任务里的变长框标注，就得自己写组装函数。
def collate_fn(batch): images = torch.stack([item[0] for item in batch], dim=0) # 假设label是长度不一的list，做手动padding max_len = max([len(item[1]) for item in batch]) padded_labels = [] for item in batch: label = item[1] padded = torch.cat([label, torch.zeros(max_len - len(label))]) padded_labels.append(padded) return images, torch.stack(padded_labels, dim=0)这个函数接收一个batch的list，每个元素是__getitem__的返回值，你需要把它整理成模型能接受的格式。写完后传给DataLoader的collate_fn参数。我最初对这一段很抗拒，觉得麻烦，但后来遇到一个OCR项目，每个样本的文本框数量不一样，才发现自定义组装是躲不掉的。
3. TensorBoard：训练过程的可视化与调试
3.1 第一次用TensorBoard需要的东西
PyTorch内置了对TensorBoard的支持，不需要额外装tf相关的全家桶，只需：
pip install tensorboard然后在代码里：
from torch.utils.tensorboard import SummaryWriter writer = SummaryWriter('runs/exp1')runs/exp1是日志目录。训练结束后，终端执行：
tensorboard --logdir runs --port 6006浏览器打开http://localhost:6006就能看到仪表盘。注意启动命令里给的是runs而不是runs/exp1，这样在一个页面里可以看到所有实验的对比曲线。
3.2 add_scalar：把loss和accuracy画出来
训练循环里最常用的就是记录标量：
for epoch in range(epochs): running_loss = 0.0 for i, (inputs, labels) in enumerate(train_loader): inputs, labels = inputs.to(device), labels.to(device) optimizer.zero_grad() outputs = model(inputs) loss = criterion(outputs, labels) loss.backward() optimizer.step() running_loss += loss.item() if i % 50 == 49: writer.add_scalar('train/loss', running_loss / 50, global_step) running_loss = 0.0 global_step += 1这里global_step一定要手动维护，它代表“当前是第几个batch”。如果不递增，曲线会永远画在一个点上。
除了loss，建议把学习率也记进去：
writer.add_scalar('train/lr', optimizer.param_groups[0]['lr'], global_step)如果你用了学习率调度器，这条曲线能帮你判断是否下降过快或过慢。一个常见的误操作是想当然地在每个epoch记录，但如果epoch较大，曲线会显得很稀疏，难以观察loss震荡的细节。
3.3 add_image：还原模型看到的数据
数据预处理最容易在无形中出错：归一化写反、通道顺序不对、resize导致样貌变形。解决这类问题最直接的办法是把__getitem__产出的一张图喂给TensorBoard看一眼。
from torchvision.utils import make_grid def show_batch(writer, images, tag, n=8): # images是CHW格式、值域0-1的tensor列表 img_grid = make_grid(images[:n], normalize=True, scale_each=True) writer.add_image(tag, img_grid) show_batch(writer, batch_images, 'train/sample')make_grid会把多张图拼成一格，方便整体观察。normalize=True自动把超出[0,1]范围的数值缩放到可视范围，避免出现全黑或全白。add_graph还能把你定义的模型画出来。
3.4 add_graph：把模型内部结构也拖出来
对调试网络结构非常有用：
dummy_input = torch.randn(1, 3, 224, 224).to(device) writer.add_graph(model, dummy_input)日志里会出现模型的计算图，每个模块的输入输出尺寸一目了然。我第一次用这功能时，发现一个卷积层后面居然接着一个维度不匹配的层，就是通过计算图里张量尺寸看出来的。没有这个功能，我只能一层层打印shape，效率低得多。
4. 调试数据集和可视化时最常踩的坑
4.1 路径拼接与文件名，低级错误最致命
常见的坑包括：标签文件里的文件名带/但与实际目录不一致、图片后缀大小写不统一、Windows下\与Linux的/混用导致路径错误。
经验做法：
- 统一用
pathlib.Path处理路径，不要手拼字符串。 - 在
__init__完成后打印前5个样本的完整路径，肉眼确认存在。 - 用
sorted(os.listdir(dir))对比标签文件数量与实际图片数量，少了说明有图片没被记录。
这类问题不在模型层面，但一旦出现，会以“数据集从头到尾全是错的”方式呈现，训练结果完全没有意义。
4.2 图像通道顺序和数值范围，错得悄无声息
torchvision模型默认期望输入是[N, C, H, W]的float32，值域经过Normalize。如果你的图片来自OpenCV读取，通道顺序是BGR，直接转tensor就会导致颜色通道互换，模型表现大打折扣。
解决方案：
# OpenCV读入的BGR转RGB image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)数值范围上，PIL的ToTensor()自动把uint8的0-255转成0-1，但如果你用numpy直接构造tensor，就要手动除以255。这一步最容易遗漏，因为程序不会报错，Loss曲线可能正常下降，但最终结果就是不如预期。
4.3 num_workers多进程，有时导致内存爆炸
有一个惨痛教训：项目服务器有64G内存，我把num_workers设成32，数据原始分辨率是4000x3000，每个worker会缓存一批解码后的图像。结果训练还没开始，内存已经耗尽，系统直接OOM。
解决思路：num_workers并不是越大越好。经验值是与CPU核心数相等或减半，同时让__getitem__里不要做过于昂贵的大图解码。可以考虑先resize再缓存。
还有一个Windows下的特殊问题：DataLoader多进程必须在if __name__ == '__main__':保护下运行，否则会触发递归创建子进程的报错。这在Linux下不会发生，但跨平台调试时很多人被卡住。
4.4 TensorBoard端口占用与日志目录混乱
有时启动TensorBoard提示Address already in use，直接换端口：
tensorboard --logdir runs --port 6007更麻烦的是日志目录混乱。如果每次实验都写到同一个runs/exp1，新曲线会和旧曲线混在一起，谁是谁看不清。建议每次实验用带时间戳的目录：
from datetime import datetime log_dir = f"runs/{datetime.now().strftime('%m%d_%H%M')}_exp1" writer = SummaryWriter(log_dir)跑完对比时，把多个实验的log目录一起扔给TensorBoard，它会按目录区分曲线颜色，非常直观。
4.5 三板斧：单步打印、小样本验证、可视化确认
写Dataset和可视化时，我养成了一个固定流程，建议直接抄：
第一步，单步调试。在__getitem__里打印返回的shape和数值范围。
第二步，小样本冒烟测试。不用全量数据，取32条做3个batch，看loss是否在合理范围下降，同时TensorBoard里是否出现图像和标量。
第三步，可视化确认。每次新加数据预处理，先把add_image的结果截图存在本地，和原图对比确认没有通道错乱、归一化错乱。
这套流程看起来啰嗦，但能拦截绝大部分数据管线问题。真等训练跑了三小时才发现数据错了，才是最亏的。
5. 从跑通到看懂：这两个组件带来的实际提升
写这篇学习日记时，我回想了自己的学习曲线：最开始是“照抄教程跑MNIST”，然后是“以为自己会了”，再到“遇到真实数据手忙脚乱”，最后才是“老老实实把Dataset和TensorBoard用熟”。
Dataset的价值不是让你多写两个方法，而是逼你把数据管线当成一等公民对待。数据读取得当、预处理规范、batch组装可靠，训练流程才谈得上稳定复现。TensorBoard的价值则是给你一双在训练中观察的眼睛。Loss突然不降、验证精度波动、学习率过陡，这些问题在曲线上比在控制台打印里清晰得多。
如果你刚好在学PyTorch，我建议别急着往模型结构里钻，先把今天这两个组件上手。跑通一个最小的数据集，画出一条收敛的loss曲线，看到一个batch的图像被正确喂进网络，那种“数据不再失控”的感觉，是后续学任何复杂模型的地基。
我个人在实际操作中还有一个体会：这两个组件一旦熟练，再看别人的开源代码，就不会再被trainset、writer = SummaryWriter()这些“魔法”挡住理解。所有看似封装高级的代码，底层都是这两个基础概念的组合。从这个角度说，花一周把它们彻底弄透，比盲刷十个模型教程划算得多。
