简介一份基于Transformer模型的木薯叶病虫害分类Python源码主要面向深度学习方向的本科生、研究生以及需要完成期末大作业的开发者能够帮助快速搭建图像分类任务的核心流程也可作为项目模板直接参考。压缩包共包含12个文件核心为6个Python脚本分别负责模型结构搭建、数据集读取、训练启动、全局参数配置等关键环节另附5个pyc编译缓存和1份说明文档整体大小仅11KB轻量简洁阅读和修改都很方便。目前已有199人学习下载代码均经过本地编译验证难度适中并获得助教老师审定完成度较高。读者可以从中学到一套完整且可扩展的分类方案包括GPU环境适配、超参数调整方法、运行流程说明等非常适合用于课程设计、人工智能实训或者Transformer应用研究的实战演练。1. 把木薯叶分类做成 Transformer 高分项目这份 python 源码能直接跑通做课程设计最怕的不是模型不会写而是代码压缩包解压以后缺文件、缺依赖、一运行就报错。这份 python 实现的基于 transformer 模型的木薯叶病虫害分类源码属于那种解压就能跑的完整工程入口脚本、模型定义、全局配置、GPU 设置、数据集加载、README 一应俱全目录里连编译过的__pycache__都留着说明作者确实在本机跑通过。它的难点适中恰好卡在“能讲清楚 transformer 原理”和“期末答辩不翻车”之间适合做本科毕业设计、深度学习课程期末大作业也适合想用 ViT 做图像分类但不想从零搭框架的从业者。整套代码的骨架就是以 Vision Transformer 为核心的图像分类流水线下面按我拆项目的习惯从结构、数据、模型、训练到避坑一条线过一遍。2. 项目结构先拆清哪些文件负责什么从哪里下手改拿到任何源码压缩包第一步不是看算法而是先摸清目录结构。这份资源里代码文件集中在根目录几个.py文件各司其职还有一个__pycache__文件夹存放 Python 3.7 的字节码缓存这反而说明原作者用的解释器版本大概率是 3.7 左右。我先按文件职责拆一遍再给出推荐的阅读和修改顺序。2.1 文件职责对照与启动入口把根目录下关键文件的作用整理成表后续改哪里、看哪里就一目了然文件职责备注run.py程序启动入口调用 main 里的训练/评估流程从run.py入手不要从main.py入手main.py主流程控制组装数据集、模型、优化器修改训练超参数最常碰它Global_Variable.py全局变量和路径配置数据集路径、保存路径一般在这里改Gpu.pyGPU 设备选择与管理无 GPU 环境会自动回落 CPUModel.pyTransformer 模型结构定义核心文件ViT 的 patch embedding 和 encoder 在这里CassavaDataset.py自定义 Dataset负责读图和预处理换数据集时主要改这里README.md项目说明和运行指引先读它能少踩一半坑这种拆法最大的好处是职责单一想改运行设备就动Gpu.py想改数据增广就动CassavaDataset.py想换模型结构就动Model.py。我一般建议按“README → Global_Variable → CassavaDataset → Model → main → run”的顺序读因为先摸清配置和数据加载再看模型和训练逻辑思路最顺畅。2.2 从 README 与全局配置入手README 是作者留给后来者的第一手运行指引第一遍直接信它。如果 README 里写了python run.py那就先在命令行执行把环境跑通再说。跑通之后再打开Global_Variable.py这里通常集中定义了数据根目录、类别数量、图像尺寸、epoch 数、学习率等常量。常见的做法是这样# Global_Variable.py 典型内容按自己数据路径改 DATA_ROOT ./data/cassava # 数据集根目录 SAVE_PATH ./checkpoints # 模型保存目录 NUM_CLASSES 5 # 木薯叶病害类别数 IMG_SIZE 224 # 输入图像尺寸 PATCH_SIZE 16 # patch 大小 EPOCHS 50 # 训练轮数 BATCH_SIZE 32 # 批大小 LEARNING_RATE 1e-4 # 初始学习率这段代码的逻辑很清楚前四行决定数据从哪读、模型输出多大、输入图多大后三行决定训练要跑多久、每步喂多少张图、权重更新步长多大。参数配置和模型结构是解耦的改PATCH_SIZE时要注意它必须能被IMG_SIZE整除否则位置编码维度对不上模型会直接报错。这个细节下面避坑章节还会展开讲。3. 数据加载与预处理CassavaDataset.py 是怎么把图像喂给 Transformer 的Transformer 吃的是 patch 序列但磁盘上存的是整张图片中间这层转换由CassavaDataset.py完成。这个文件决定模型看到什么、以什么顺序看直接影响最终分类精度。3.1 自定义 Dataset 的核心实现这份资源没有用现成的ImageFolder而是自己实现了 Dataset说明作者对数据预处理有控制欲也说明数据集目录结构不太适合ImageFolder的“按子目录分类别”约定。核心逻辑通常是这样# CassavaDataset.py 核心骨架 import torch from torch.utils.data import Dataset from PIL import Image import os class CassavaDataset(Dataset): def __init__(self, image_dir, label_file, transformNone): self.image_dir image_dir self.transform transform self.image_paths [] self.labels [] with open(label_file, r) as f: lines f.read().strip().splitlines() for line in lines: # 每行形如 xxx.jpg 3表示类别3 path, label line.split() self.image_paths.append(os.path.join(image_dir, path)) self.labels.append(int(label)) def __len__(self): return len(self.image_paths) def __getitem__(self, idx): image Image.open(self.image_paths[idx]).convert(RGB) label self.labels[idx] if self.transform: image self.transform(image) return image, label这段代码在__init__里读取一个“图像路径 数字标签”的文本文件建立完整的样本索引在__getitem__里按索引加载图片、转成 RGB、做预处理。逻辑说明一句话transform由外部传入Dataset 本身不关心用 RandomResizedCrop 还是 Flip这样数据增强策略可以独立调整。参数说明image_dir是图片所在的绝对或相对路径label_file是标签文件路径。如果原项目不是读 txt而是直接用目录结构映射标签那__init__里就会换成os.listdir遍历子目录。无论哪种写法__getitem__返回的(image, label)都是后续 DataLoader 批量打包的素材。3.2 自动切分训练集与验证集木薯叶这种农业影像数据类别分布天然不均衡——健康的叶子远多于发病初期的叶子。所以训练前必须切出验证集否则没法判断模型是记住训练集还是学会泛化。切分逻辑通常在main.py里完成# main.py 中数据集切分的常见写法 from torch.utils.data import random_split, DataLoader full_dataset CassavaDataset( image_dir./data/cassava/images, label_file./data/cassava/labels.txt, transformtrain_transform, ) val_size int(0.2 * len(full_dataset)) train_size len(full_dataset) - val_size train_dataset, val_dataset random_split( full_dataset, [train_size, val_size] )切分比例 8:2 是分类任务的常见默认值数据量小可以改成 9:1但验证集太小会导致评估指标波动剧烈20 个样本和 200 个样本的准确率方差完全不同。random_split的细节是它接收的是 Dataset 长度列表返回的子集共享同一个底层数据引用不会复制图片内存开销可以忽略。这里容易被忽略的一点是val_dataset复用了train_transform如果训练用了 RandomHorizontalFlip 这类随机增强验证集也会被随机翻转导致验证指标忽高忽低。正确做法是单独定义一个只含 Resize 和 Normalize 的验证 transform保证评估时每次看到的是同一张图的同一形态。4. 模型结构与训练管线从 patch embedding 到 run.py 一键启动这份资源最核心的资产是Model.py里基于 transformer 的分类模型以及main.py、run.py配套的训练流程。先把模型讲透再讲训练超参和启动方式。4.1 用卷积实现 patch embedding 的 ViT 骨架Vision Transformer 的标准做法是把图像切成一串 patch每个 patch 展平后过线性映射得到 embedding。作者在Model.py里的常见实现是用nn.Conv2d一步完成切块和映射效率比手动切片高而且能利用卷积的局部感受野先做一次特征提取# Model.py 中 patch embedding 与 transformer encoder 的核心片段 import torch import torch.nn as nn class PatchEmbed(nn.Module): def __init__(self, in_channels3, img_size224, patch_size16, embed_dim768): super().__init__() self.grid_size img_size // patch_size self.num_patches self.grid_size * self.grid_size self.proj nn.Conv2d(in_channels, embed_dim, kernel_sizepatch_size, stridepatch_size) def forward(self, x): # x: (B, 3, 224, 224) - (B, 196, 768) x self.proj(x) # (B, 768, 14, 14) x x.flatten(2) # (B, 768, 196) x x.transpose(1, 2) # (B, 196, 768) return x class CassavaViT(nn.Module): def __init__(self, num_classes5): super().__init__() self.patch_embed PatchEmbed() self.cls_token nn.Parameter(torch.randn(1, 1, 768)) self.encoder nn.TransformerEncoder( nn.TransformerEncoderLayer(d_model768, nhead12, dim_feedforward3072, dropout0.1), num_layers6, ) self.head nn.Linear(768, num_classes) def forward(self, x): x self.patch_embed(x) # (B, 196, 768) x torch.cat([self.cls_token.expand(x.size(0), -1, -1), x], dim1) x self.encoder(x) x x[:, 0] # 取 CLS token return self.head(x)关键在这一行注释标注的维度变换nn.Conv2d的 kernel_size 和 stride 都等于patch_size所以空间维直接除以 16224 变成 14展平成 196 个 token每个 token 是 768 维。cls_token是可学习参数拼在序列最前面最终分类只用它的输出这是 ViT 的标志性设计。nn.TransformerEncoderLayer是 PyTorch 内置实现包含了自注意力、前馈网络、LayerNorm 和残差连接不比自己手写 Multi-Head Attention 差。参数说明nhead12表示 12 个注意力头dim_feedforward3072是 FFN 中间层维度通常是d_model的 4 倍num_layers6是 encoder 堆叠层数。数据量只有几千张时可以把这个模型换小把embed_dim降到 512、num_layers降到 4训练时间能省一半精度不会掉太多。4.2 GPU 设备管理与训练主循环Gpu.py负责把模型和数据搬上 CUDA这个文件看着简单但最容易出错。常见的写法是# Gpu.py设备选择与初始化 import torch def get_device(): if torch.cuda.is_available(): device torch.device(cuda) torch.backends.cudnn.benchmark True # 输入尺寸固定时加速 else: device torch.device(cpu) return devicetorch.backends.cudnn.benchmark True的意思是当输入尺寸固定时让 cuDNN 自动搜最优卷积算法能小幅度提速。如果显存不足可以在训练脚本里按需开启混合精度。main.py的训练循环里还有几个隐藏细节优化器选 AdamW 而不是 Adam因为 ViT 对权重衰减更敏感AdamW 能正确处理解耦的 weight decay学习率常用 1e-4配合余弦退火调度器loss 用 CrossEntropyLoss它内部自带 softmax不需要在模型输出后手动加激活。跑训练时用的命令很简单# 直接启动训练自动选择 GPU 或 CPU python run.pyrun.py是入口它会把main.py里定义的训练函数包一层。如果run.py内有参数解析就把 batch size、epoch 等通过命令行参数传入如果没有就按Global_Variable.py的默认值执行。训练过程中需要看两类日志一是 loss 的变化曲线正常是从大到小逐步收敛二是每个 epoch 结束后的验证集准确率如果验证准确率一直徘徊在 20% 左右等于随机猜说明模型没学起来优先检查数据标签是否对齐。4.3 从零训练还不够预训练权重与迁移学习木薯叶病害数据集的规模通常在几千到两万张这个量级从零训练一个 ViT 很容易过拟合。Model.py里如果有load_state_dict的逻辑说明原项目预留了加载预训练权重的接口。常见做法是先用 ImageNet 上预训练好的 ViT 权重初始化 backbone再微调分类头# 迁移学习初始化模型权重 def load_pretrained(model, pretrained_pathNone): if pretrained_path: state_dict torch.load(pretrained_path, map_locationcpu) # 严格匹配除分类头以外的层 model.load_state_dict(state_dict, strictFalse) print(Loaded pretrained weights from, pretrained_path) return modelstrictFalse的含义是允许缺失或形状不匹配的 key比如分类头的fc.weight形状从 1000 变成 5 会匹配失败但不会影响整体加载。手头没有预训练文件时模型会从零训练效果看数据量。这里有个取舍如果期末答辩只看运行结果那用预训练权重微调是捷径如果导师要求讲清 transformer 原理那从零训练配合可视化反而更好讲。项目源码是完整可运行的即使不加载预训练权重也能跑通只是收敛速度慢、最终精度低一些。5. 复现避坑木薯叶分类项目最容易翻车的五个点这份源码本地编译过肯定能跑但复现过程中环境的细微差异仍然会导致各种翻车。我整理了五个高概率踩坑点都是实际运行这类 Transformer 分类项目时血泪换来的经验按“现象 → 原因 → 解决”写清楚。5.1 数据集图片尺寸与 Patch 尺寸不匹配现象运行run.py后报错size mismatch for position embedding或者模型 forward 阶段维度对不上。原因IMG_SIZE设置成 224PATCH_SIZE设置成 16但实际读进来的图片被 Resize 成了 225×225或者数据集原图就是 512×512 而 transform 里没有 Resize导致 patch 切分后 token 数量不是预期的 196。解决先检查IMG_SIZE能否被PATCH_SIZE整除再确认CassavaDataset.py的 transform 里第一个操作是Resize((IMG_SIZE, IMG_SIZE))。经验做法是# 在 Dataset 的 transform 里强制统一尺寸 from torchvision import transforms train_transform transforms.Compose([ transforms.Resize((224, 224)), # 先定尺寸 transforms.RandomHorizontalFlip(), transforms.ToTensor(), transforms.Normalize(mean[0.5, 0.5, 0.5], std[0.5, 0.5, 0.5]), ])把Resize放在第一位保证任何输入图进入模型之前都被统一成 224×224位置编码才能和 patch 序列对齐。修改这一步后别再动PATCH_SIZE除非你真的理解 position embedding 的插值逻辑。5.2 标签文件与图片目录对不上现象训练 loss 一直在 1.6 附近下不去验证准确率在 20%~30% 之间震荡和随机猜测差不多。原因labels.txt里的文件名顺序和image_dir里的实际图片命名不一致可能标签文件是从别的数据集拷来的或者图片有重复名字。解决写一个五行的脚本遍历图片目录生成标签对照# 重新生成标签文件确保顺序与文件系统一致 import os with open(labels.txt, w) as f: for idx, fname in enumerate(os.listdir(./data/cassava/images)): # 假设类别由所在子目录决定这里按文件名前缀映射 label 0 if fname.startswith(healthy) else 1 f.write(f{fname} {label}\n)startswith只是示例实际类别映射要按原数据集标注规则来重点是“文件名和标签写在同一行、一一对应”。改完后重新跑第一步看 loss 有没有下降趋势没有的话再查__getitem__里读到的图像和标签是否真的是成对的。5.3 显存不足导致的 OOM现象batch size 设 32forward 刚跑完就报CUDA out of memory。原因ViT 的 self-attention 复杂度是序列长度的平方196 个 token 在 12 层 encoder 下激活值很占显存一批 32 张 224×224 的 RGB 图在 6GB 的卡上很容易爆。解决优先减小 batch size再考虑降低embed_dim最后才是换更小的输入尺寸。调参时注意BATCH_SIZE16时别忘了同步调低LEARNING_RATE否则梯度噪声变大收敛反而变慢。手动改参数前先看显卡显存# 查看当前显存占用 nvidia-smi如果显存占用率已经 90% 以上BATCH_SIZE直接砍半这是性价比最高的做法不需要动模型结构。5.4 模型和数据设备不一致现象运行时报Expected all tensors to be on the same device, but found at least two devices。原因Model.py的模型搬上了 GPU但main.py构造 DataLoader 时忘记给 batch 调.to(device)数据和权重一个在 CPU 一个在 CUDA。解决在训练循环第一步强制把输入和标签搬上设备。这类错误看起来低级但在复现别人项目时极其常见因为原作者在自己机器上能跑不代表换台机器环境一致。排查办法for batch_idx, (images, labels) in enumerate(train_loader): images images.to(device) # 关键一行 labels labels.to(device)每次从 DataLoader 取完 batch 先做这一步再进 forward就能杜绝设备不一致的报错。5.5 复现环境的 Python 版本陷阱现象跑run.py时ImportError提示某个库找不到或者语法不兼容。原因目录里的__pycache__显示原项目用的是 CPython 3.7如果本机是 Python 3.10 或 3.11某些第三方库的二进制版本不兼容。解决优先用 conda 建一个 Python 3.8 环境再按依赖安装 pytorch、torchvision、pillow、numpy、tqdm。装依赖尽量用国内镜像否则编译 torch 那一步很容易卡住# 创建虚拟环境并安装依赖 conda create -n cassava python3.8 -y conda activate cassava pip install torch torchvision pillow numpy tqdm -i https://pypi.tuna.tsinghua.edu.cn/simplePython 3.8 对 3.7 写的代码几乎完全兼容又能避免老版本解释器缺少新版库支持的麻烦。如果__pycache__里既有 3.7 的.pyc又存在语法错误的提示优先删掉这个缓存文件夹再跑它有时会残留过期字节码干扰运行。6. 验证模型不是只看准确率画出混淆矩阵和训练曲线训练跑完run.py会输出验证集上最终的准确率但答辩和自测时一个总数掩盖了太多信息。木薯叶病害五分类里如果模型把其他病错判成健康误差在小样本类别上会被均匀稀释。所以最后这一步我会把模型预测结果落成三样东西分类报告、混淆矩阵图、准确率曲线。这套验证流程应该在main.py里加一小段独立函数不影响原训练逻辑。6.1 分类报告与混淆矩阵可视化加载训练好的权重对验证集做一次完整推理然后生成每个类别的 precision、recall、F1# evaluate.py推理验证集并输出分类报告 from sklearn.metrics import classification_report, confusion_matrix import torch def evaluate(model, val_loader, device): model.eval() all_preds, all_labels [], [] with torch.no_grad(): for images, labels in val_loader: images images.to(device) outputs model(images) preds outputs.argmax(dim1).cpu().numpy() all_preds.extend(preds) all_labels.extend(labels.numpy()) print(classification_report(all_labels, all_preds, digits4)) return confusion_matrix(all_labels, all_preds)model.eval()会关闭 Dropout 和 BatchNorm 的 batch 统计更新保证推理结果稳定。torch.no_grad()关闭梯度追踪显存占用降低一大截。argmax(dim1)是取每个样本 logits 最大值所在的类别索引。分类报告里support一列如果某类只有几十个样本看 F1 比看 accuracy 靠谱得多类别不均衡时 macro avg 才是真实水平。如果 macro avg 比 accuracy 低 10 个百分点以上说明小样本类别基本没学会后续应该做类别加权 loss 或数据过采样。6.2 训练曲线与单张图推理验证训练过程中的 loss 和准确率如果只在终端打印事后没法复盘。建议改成把每个 epoch 的值写入列表最后画成两条曲线这是答辩时最直观的素材# 训练后绘制 loss/acc 曲线 import matplotlib.pyplot as plt def plot_curves(train_losses, val_accs): plt.figure(figsize(10, 4)) plt.subplot(1, 2, 1) plt.plot(train_losses, labeltrain loss) plt.xlabel(epoch) plt.legend() plt.subplot(1, 2, 2) plt.plot(val_accs, labelval acc) plt.xlabel(epoch) plt.legend() plt.tight_layout() plt.savefig(training_curves.png, dpi150)曲线能暴露一个问题val acc 先升后降说明过拟合这时候应该提前停止或加大数据增广。最后的单图推理函数也很简单加载一张图片、走一遍 transform、model(img.unsqueeze(0))输出各类别概率取 top-1 作为预测。这个函数看起来不起眼但答辩时现场演示一张叶子图片出结果比口头讲十句都有效。6.3 结束前的一个小习惯从那以后我每次拿到一份分类项目源码都强制自己先跑通再改参改完参数立刻看训练曲线受害者矩阵确认三个问题loss 有没有降、混淆矩阵的对角线是不是最亮、小样本类别有没有一片 0 的列。这三关过了这个项目才算真正属于你而不是只会在命令行敲python run.py。希望帮到你。本文还有配套的精品资源点击获取
