MobileNetV3花卉分类实战：从PyTorch训练到ONNX边缘部署

这个月开始做一个花卉品种分类的小实验：一万两千多张图片，38个类别，机器是一张老实的8GB显存消费级显卡，后续还打算把模型放到低算力的设备上跑。选型几乎没什么悬念——MobileNetV3，具体是V3-Small还是V3-Large，训练完看指标再定。而这次和以往不太一样的地方是，整个训练代码我决定通过 Claude Code 来写，顺便验证一下它在真实深度学习任务里到底能扛多少活。这篇文章就是一次完整的训练记录：模型选型、数据整理、代码落地、踩坑修复、最后导出部署文件，能复现的部分我都尽量写细，方便同样在做轻量分类任务的人参考。

1. 先交代一下：这个训练任务是什么、模型为什么选MobileNetV3

任务本身不复杂：给定一批品种形态相近的花卉照片，要求输出对应类别。难就难在类别之间有大量相似样本，比如同属不同种的菊花，肉眼都要看半天，模型必须学会更细粒度的特征。而部署端给的限制又很死——没有服务器显卡，只能在ARM小盒子上跑，因此模型体积和推理速度比绝对精度更敏感。

我一开始列了三个候选：ResNet18、EfficientNet-B0、MobileNetV3。ResNet18参数约1100万，跑起来倒是稳，但迁移到边缘设备后单帧推理时间不理想；EfficientNet-B0精度高一些，可它依赖的Swish和缩放策略在ONNX导出时容易踩版本兼容的坑。MobileNetV3有两个规格，Small约250万参数，Large约540万参数，配合预训练权重和迁移学习，已经完全能覆盖这个花卉任务的复杂度。

表格里的准确率都是公开权重在ImageNet上的参考值，对我们这个领域任务而言实际准确率会更低一些，但排名趋势差不多。我最终决定先用V3-Small做完整跑通，再考虑是否升级到V3-Large。

1.1 MobileNetV3“轻”在哪：三个关键设计

很多没接触过轻量网络的人会以为 MobileNetV3 只是把普通卷积层变少。实际上它轻的核心是结构本身换了算子。

第一，深度可分离卷积（Depthwise Separable Convolution）。普通卷积同时处理空间信息和通道信息，计算量是 K×K×Ci×Co×H×W；深度可分离卷积把过程拆成两层：先做深度卷积，每个通道单独做一次3×3卷积，负责空间特征，再用1×1卷积负责通道间的信息融合。计算量被压到原来的八分之一到九分之一。这个思路可以类比成整理书房：普通做法是一个人把每本书拿出来翻一遍再放回，深度可分离是先按类别把书分到不同书架上，再在书架之间做快速二次整理，效率自然高很多。

第二，SE模块（Squeeze-and-Excitation）。它是一个很轻量的通道注意力机制：对每个通道的特征图求全局平均，得到通道描述向量，再用两个全连接层学到每个通道的权重系数，最后把权重乘回原特征图。这等于告诉网络“当前样本中哪些通道更重要”，代价只有几百个参数，但能稳定提升一到两个点准确率。

第三，h-swish激活函数。原版Swish是 x·sigmoid(x)，效果好但sigmoid计算开销大。MobileNetV3用了hard-swish近似，用ReLU6把计算变成分段线性函数，在移动端推理时比sigmoid快很多，精度损失很小。另外V3的尾部结构也经过精简，去掉了耗时的瓶颈层，进一步降低延迟。

1.2 Claude Code在这个项目里的角色

我不会把 Claude Code 描述成无所不能的“自动炼丹师”。它更像一个非常熟悉 PyTorch、能直接读项目文件、跑命令、并根据报错信息快速修改代码的结对工程师。它的价值在于把“查API、写样板代码、格式化数据管道、修常见Bug”这些杂活接手，而模型怎么选、学习率怎么调、数据有没有问题，仍然需要我自己判断。

接下来的章节会按照实际推进顺序写：数据预处理、模型定义、训练主循环、排错、导出。凡是涉及Claude Code生成的地方，我会同时给出我当时提出的需求描述和最终落地代码，方便你看出“人提供什么信息，才能换来高质量代码”。

2. Claude Code 怎么用在训练项目：人定思路，它写代码

很多人第一次用终端里的AI助手会犯同一个错误：只丢一句“帮我写一个训练MobileNetV3的代码”就等着结果，然后拿到的代码根本跑不通。这次实践下来，我的经验是把它当成一个没有上下文概念、但执行能力很强的工程师，你需要给它足够的约束和目标。

2.1 启动会话与工作方式

进入项目目录后在终端启动：

cd ~/projects/flower-classify claude

启动后可以直接输入需求。我第一次的需求是：

“在这个项目里新增一个训练脚本，使用torchvision的mobilenet_v3_small模型，读取data/train和data/val两个目录（标准ImageFolder结构），类别数通过读取目录自动获取。训练30个epoch，batch size 64，使用SGD优化器和余弦退火学习率。需要支持--resume断点续训，训练完成后保存最佳模型到checkpoints/best.pth，并输出每个epoch的loss和准确率到CSV日志。”

我没有让它一次生成全部工程，而是一个脚本一个脚本地给任务，因为分阶段做，它能从现有代码里推断数据类型和命名习惯，生成结果更匹配。

2.2 需求描述里的四个固定要素

这四要素是我对比了几个项目后总结出来的，能明显降低返工率：

1. 任务边界：要用哪个库、哪个模型、要不要预训练权重，输入是什么目录、输出是什么文件。模糊的描述只会换来通用代码。
2. 运行约束：显存大小、操作系统、是否使用GPU、是否考虑混合精度。不告诉它8GB显存，它可能默认给你塞个很大的batch size。
3. 希望看到什么结果：打印日志、保存checkpoint、导出CSV、画训练曲线，还是全部都要。需求里写清楚，就不用二次加功能。
4. 验收标准：能跑通一轮、验证集准确率达到多少、推理延迟多少。这个尤其重要，因为AI生成的代码“看起来对”和“真正对”是两回事。

我当时给它的需求描述模板大致如下（中英文都可以，我更推荐英文，模型对英文文档的检索更准）：

I'm doing a 38-class flower classification task. Data is stored in ImageFolder format under data/train and data/val. Use torchvision mobilenet_v3_small with pretrained weights, replace the final classifier for 38 classes. Use SGD with momentum=0.9, weight_decay=1e-4, cosine annealing schedule with 3-epoch linear warmup. Train 30 epochs with amp mixed precision. Save best checkpoint by val top-1 accuracy. Write training logs to logs/train_log.csv.

2.3 三个月用下来，它的边界在哪里

第一，它不会替你判断模型选型。你问“V3-Small和V3-Large该选哪个”，它会列出对比，但决策必须基于你自己的数据规模、部署平台和延迟要求。

第二，它生成的代码不一定完全正确。有一个很典型的例子：它曾把验证集的Normalize参数写成了与预训练权重不一致的均值方差，导致验证准确率惨不忍睹。这类问题写代码时看不出，只能通过实验曲线发现。

第三，它不能保证显存一定够用。生成训练循环时，它不会主动探测你的GPU显存，也不会替你算给定batch size和图片尺寸的显存占用。遇到OOM需要自己定位，还是得靠batch size、分辨率、梯度累积这些手段一起上。

3. 数据侧：从杂乱图片目录到可用的DataLoader

训练代码可以靠AI生成，但数据的整理没有捷径。这个项目里最耗时的是清理原始数据：有的照片是灰度图，有的是RGBA，还有一部分文件后缀是jpg但内容已经损坏。PyTorch的ImageFolder在读取时会报错，而且报错信息往往不直接指向坏文件，而是整个DataLoader崩掉。

3.1 固定目录结构

我先按标准ImageFolder格式整理：

data/ ├── train/ │ ├── class_01/ │ ├── class_02/ │ └── ... └── val/ ├── class_01/ ├── class_02/ └── ...

训练集大概10200张，验证集留了2600张，按类别分层划分，避免某些小类在验证集中一条不剩。划分时固定了随机种子，保证每次复现实验用的是同一份划分。

清理坏样本的脚本我直接交给Claude Code写了，需求是“扫描目录下所有图片，尝试用PIL打开，灰度图转为RGB，无法打开的移动到corrupted/目录，并输出报告”。这个脚本几十行就搞定，一次性跑完，删掉了37张坏图。这也算是“让AI处理机械任务”的典型场景。

3.2 数据增强和归一化：迁移学习最容易翻车的地方

数据增强我选择的是一个偏保守的组合：随机裁剪、随机水平翻转、轻微颜色抖动。花卉分类不是对抗性很强的任务，过强的增强反而会拉长收敛时间。验证集只做Resize到256、CenterCrop到224和归一化。

这里必须强调一个关键点：使用ImageNet预训练权重时，输入数据的均值方差必须和预训练时一致。torchvision官方预训练权重用的均值是[0.485, 0.456, 0.406]，方差是[0.229, 0.224, 0.225]。如果归一化参数写错，模型看到的输入分布和它学到的特征分布完全不同，迁移效果会大打折扣。我当时差点栽在这个坑上，后面排错部分会详细说。

最终的transform代码大致是这个样子：

from torchvision import transforms train_transform = transforms.Compose([ transforms.RandomResizedCrop(224, scale=(0.7, 1.0)), transforms.RandomHorizontalFlip(), transforms.ColorJitter(brightness=0.2, contrast=0.2, saturation=0.2), transforms.ToTensor(), transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]) ]) val_transform = transforms.Compose([ transforms.Resize(256), transforms.CenterCrop(224), transforms.ToTensor(), transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]) ])

3.3 DataLoader参数和一眼验证小技巧

DataLoader的参数直接影响训练体验。我用的是batch_size=64，shuffle=True，num_workers=4，pin_memory=True。这里pin_memory在GPU训练时能减少CPU到GPU拷贝的时间，建议开着。shuffle只给训练集开，验证集必须保持False，否则每次评估的样本顺序都是乱的，不利于复现。

数据管道搭好后，不要急着训练，先用一个几行的小脚本检查每个batch的shape和取值范围：

for images, labels in train_loader: print(images.shape, images.min().item(), images.max().item()) print(labels.unique()) break

这一步能第一时间发现通道数不对、归一化没有生效、类别索引越界等问题。我第一次跑的时候就发现labels.unique()输出只有0和1，最后定位到类别目录竟然只有两个子文件夹——数据拷贝中断导致大部分类别没拷全。这种问题如果直接开训，两个小时后才会在loss曲线上一脸懵，而事前检查只需要几秒钟。

4. 模型定义与训练主循环：从假骨架到真训练

数据没问题之后，开始进入核心环节。我仍然按照“分步提需求”的方式和Claude Code协作：先让它生成模型构建脚本，再让它生成训练验证循环，最后合并。

4.1 预训练权重：轻量模型的加速器

MobileNetV3的参数量虽然小，但它是为ImageNet这种千万级数据量设计的。我们的花卉数据只有一万多张，从头训练很难收敛，而且容易过拟合。使用预训练权重是必然选择。

在torchvision中加载预训练模型非常直接：

from torchvision.models import mobilenet_v3_small, MobileNet_V3_Small_Weights num_classes = 38 model = mobilenet_v3_small(weights=MobileNet_V3_Small_Weights.IMAGENET1K_V1) # 替换最后的分类器 in_features = model.classifier[3].in_features model.classifier[3] = nn.Linear(in_features, num_classes)

这里需要解释一下为什么替换的是classifier[3]。MobileNetV3-Small的classifier是一个Sequential容器，包含：一个全连接Linear(576, 1024)、Hardswish激活、Dropout、以及最后的Linear(1024, num_classes)。所以最后一个线性层在索引3的位置。如果不清楚结构，可以先用print(model)看一眼再动手，不要硬记索引。

4.2 冻结微调和解冻微调的两段式策略

由于数据量有限，我采用了两段式训练：前5个epoch只更新分类头，冻结前面的backbone；第6个epoch开始解冻全部参数，用一个较小的学习率做全局微调。这个策略的好处是让随机初始化的新分类头先适应预训练特征，避免一开始就用大梯度把特征破坏。

代码实现方式：

for param in model.parameters(): param.requires_grad = False for param in model.classifier.parameters(): param.requires_grad = True optimizer = optim.SGD([ {"params": model.classifier.parameters(), "lr": 1e-2}, ], momentum=0.9, weight_decay=1e-4) # 训练5轮后解冻 for param in model.parameters(): param.requires_grad = True optimizer.add_param_group({"params": [p for p in model.parameters() if p.requires_grad], "lr": 1e-3})

在第二步时要注意，optimizer.add_param_group会把原来的参数组保留，所以原来分类头的学习率会继续沿用1e-2，而新加入的backbone参数组用1e-3。如果你希望解冻后所有参数统一用1e-3，更干净的做法是重新构建一个optimizer，而不是add_param_group。

4.3 优化器、学习率调度和混合精度

优化器我选SGD + momentum + weight_decay，而不是Adam。这个选择基于经验：对ImageNet预训练模型做迁移微调，SGD配合调整后的学习率通常比Adam更稳，虽然Adam前期收敛更快，但后期容易徘徊在次优解。当然这并非绝对规律，如果数据量特别小，Adam可能更省心。

学习率调度选的是“3个epoch线性warmup + 余弦退火”。warmup是为了避免训练初期大学习率把预训练权重冲坏，余弦退火则让训练后期学习率平滑衰减到接近0。PyTorch实现余弦退火很简单：

from torch.optim.lr_scheduler import CosineAnnealingLR, LinearLR warmup = LinearLR(optimizer, start_factor=0.1, end_factor=1.0, total_iters=3) cosine = CosineAnnealingLR(optimizer, T_max=27, eta_min=1e-6) scheduler = SequentialLR(optimizer, schedulers=[warmup, cosine], milestones=[3])

混合精度方面，我在确认显存吃紧后开启AMP。PyTorch 1.6以上自带torch.cuda.amp，对MobileNetV3这种轻量网络收益很大：显存占用降低约40%，训练速度提升20%-30%，精度几乎无损。

scaler = torch.cuda.amp.GradScaler() with torch.cuda.amp.autocast(): outputs = model(images) loss = criterion(outputs, labels) scaler.scale(loss).backward() scaler.step(optimizer) scaler.update() optimizer.zero_grad()

注意：AMP自动混合精度不会自动帮你降低显存到“绝对够用”，它只是把部分算子从FP32降到FP16，因此和batch size、分辨率是叠加关系，三者一起调才能解决大模型的OOM问题。

4.4 训练验证主循环：日志、checkpoint和一个容易被忽略的细节

训练主循环里有一个细节值得单独拎出来说：验证阶段一定不要开梯度计算，要包在torch.no_grad()里。推理时的BN统计量也需要注意，MobileNetV3用的是BatchNorm，验证时要确保模型处于model.eval()状态，这样BN才会用运行均值而不是当前batch统计量。很多新手训完发现验证准确率乱跳，往往是这个原因。

训练循环整体如下：

def train_one_epoch(model, loader, criterion, optimizer, scaler): model.train() total_loss, correct, total = 0.0, 0, 0 for images, labels in loader: images, labels = images.to(device), labels.to(device) optimizer.zero_grad() with torch.cuda.amp.autocast(): outputs = model(images) loss = criterion(outputs, labels) scaler.scale(loss).backward() scaler.step(optimizer) scaler.update() total_loss += loss.item() * images.size(0) correct += (outputs.argmax(1) == labels).sum().item() total += labels.size(0) return total_loss / total, correct / total def validate(model, loader, criterion): model.eval() total_loss, correct, total = 0.0, 0, 0 with torch.no_grad(): for images, labels in loader: images, labels = images.to(device), labels.to(device) outputs = model(images) loss = criterion(outputs, labels) total_loss += loss.item() * images.size(0) correct += (outputs.argmax(1) == labels).sum().item() total += labels.size(0) return total_loss / total, correct / total

每轮训练后我都把结果追加写入logs/train_log.csv，再用一个小脚本在后端画曲线。画曲线不是锦上添花，而是第一时间发现异常的手段。只看loss数字无法快速判断“过拟合是第几轮开始的”，但曲线图一目了然。

5. 现场排错：训练过程中真实遇到的三个麻烦

训练记录的价值不只是“跑通了”，更在那些卡住的时刻。这次训练前后踩了三类问题，每个都花了不少时间定位。我尽量把排查思路还原出来，比单纯贴答案更有参考价值。

5.1 第一个Bug：DataLoader卡死，训练进度条半天不动

刚启动训练时，终端卡在“Loading data”阶段，GPU利用率一直是0，CPU倒是跑满。第一反应是数据集太大？但只有一万多张图，读取不该这么慢。我直接把问题抛给Claude Code：“训练启动后一直卡在数据加载阶段，GPU没有使用率，CPU占用很高，可能是什么原因”。它给出的排查建议很直接：先试试num_workers=0，如果立刻恢复正常，说明问题出在多进程数据加载上。

果然，把num_workers从8改成0后，训练正常启动。问题根因算是清楚了，但真正的修复不是改成0，而是降到4并确认没有其他干扰。后来我查到这台机器上的磁盘IO资源被日志进程占满，导致多个DataLoader worker频繁切换、互相争抢IO。把日志写入频率降低后，num_workers=4恢复正常。这个Bug给我的教训是：遇到卡死，先不要怀疑模型，先隔离数据加载链路，最小化复现。

5.2 第二个Bug：训练集Loss降到0.1，验证集准确率却只有60%

这是这次训练中最气人的一个Bug。训练集loss一路降到0.1，train准确率已经到99%了，但验证集准确率死活卡在60%上下。第一反应肯定是过拟合，可即使过拟合，验证准确率也不至于和训练集差这么多。我把训练曲线图发给Claude Code，得到的建议是按顺序检查：数据泄露、预处理不一致、类别标签错位。

检查后发现，问题是验证集的transform里漏写了归一化。训练时用了完整的ToTensor + Normalize，验证时因为复制代码疏忽，直接把Normalize注释掉了。模型预训练时看到的是均值0.485、方差0.229的分布，验证时喂给它的是0到1的原始像素值，分布错位导致验证loss一直很高。修复后同一轮验证准确率直接跳到89%。这是一个非常典型的迁移学习坑：预训练模型不改输入端的预处理，等于让模型看一张“颜色失真”的图。

这种“训练好、验证差”的问题，排查顺序应该是：先确认训练集和验证集预处理完全一致，再检查数据切分是否重叠，最后才怀疑过拟合。

5.3 第三个Bug：batch size 64直接把8GB显存打爆

MobileNetV3-Small本身的参数量很小，但输入分辨率224、batch size 64配合AMP，在8GB显存上还是遇到OOM。报错信息很直接：CUDA out of memory。Claude Code给出的第一个建议是“尝试batch size减半”，但并不想放弃等效batch size，因为学习率已经按64调度好了。最终采用“batch size降到32 + 梯度累积两步”的方案，等效出一个64的梯度，行为和原计划一致。

accumulation_steps = 2 scaler = torch.cuda.amp.GradScaler() for i, (images, labels) in enumerate(loader): images, labels = images.to(device), labels.to(device) with torch.cuda.amp.autocast(): outputs = model(images) loss = criterion(outputs, labels) loss = loss / accumulation_steps scaler.scale(loss).backward() if (i + 1) % accumulation_steps == 0: scaler.step(optimizer) scaler.update() optimizer.zero_grad()

梯度累积最关键的一步是：loss要先除以累积步数，再反向传播，否则累加的梯度相当于把学习率放大了accumulation_steps倍。这条当时是Claude Code代码里已经写好的，但我还是在review时确认了一遍——这类“AI给对了，人不能因此不看”的细节，才是正确使用工具的方式。

6. 最终结果与导出部署：从PyTorch到边缘设备

6.1 训练曲线和最终指标

训练共30个epoch，前5轮冻结backbone只练分类头，之后解冻全部参数微调。从训练曲线看，冻结阶段验证准确率就能达到87%，解冻后继续上升，在第26轮左右接近收敛，Top-1准确率约92.1%。由于类别不平衡，我额外看了宏平均F1，大概0.90，说明模型不是靠少数大类撑起来的，小类也学到了一定区分度。

从混淆矩阵看，主要的错分集中在几个外观高度相似的品种上。这类错分很难靠模型结构改进，更有效的做法是增加对应类别的训练样本，或者加入一些针对性的裁剪增强。模型在结构上已经练到头了，剩余问题主要在数据侧。

6.2 模型体量与推理耗时

MobileNetV3-Small导出的FP32权重文件约21MB，导出为ONNX后体积在10MB附近，如果做INT8量化可以压到3MB左右。CPU环境推理单张224×224图片耗时约35ms，对于ARM设备也能在100ms以内完成推理，完全满足项目需求。如果后续发现长尾类别的准确率不够，可以考虑切到V3-Large，代价是推理耗时大约翻倍，但模型体积也只是从几十MB涨到几十MB，仍然可以接受。

这里有一个经验：评估模型能不能上线，不要只看参数量，要看“导出格式下的实际体积”和“目标设备上的实测延迟”。PyTorch的state_dict体积和ONNX量化后的体积差别很大，只有跑过目标硬件才知道数值。

6.3 导出ONNX与TorchScript的实用代码

我最终同时导出了ONNX和TorchScript两份文件，方便在不同推理框架里测试。导出时要固定输入尺寸，并切换到eval模式，否则导出的图里会包含训练相关的计算分支。

import torch model.load_state_dict(torch.load("checkpoints/best.pth", map_location="cpu")) model.eval() dummy_input = torch.randn(1, 3, 224, 224) torch.onnx.export( model, dummy_input, "models/flower_v3_small.onnx", opset_version=12, input_names=["input"], output_names=["output"], dynamic_axes={"input": {0: "batch"}, "output": {0: "batch"}} ) traced = torch.jit.trace(model, dummy_input) traced.save("models/flower_v3_small.pt")

导出完成后，我用ONNX Runtime做了回读验证，把同一个batch分别用PyTorch和ONNX Runtime推理，对比输出向量。两者最大绝对误差在1e-4量级，基本可以认定导出无损。如果你在导出时遇到算子不兼容，优先检查opset_version是不是太老，部分MobileNetV3的激活算子需要较新的opset才能完整映射。

最后说一点我的个人体会。这次用Claude Code写训练代码，体验最好的地方不是“它把代码写对了”，而是“它能在我描述完问题后，几秒钟内给出多个排查方向”。像数据加载卡死、验证集预处理不一致这种问题，它比搜索引擎快，也比翻文档直观。但它不会替你做实验设计，更不会替你看数据。真正有价值的判断——该不该冻结、学习率该怎么调、是不是过拟合——还是得人来做。所以如果让我给一个建议：把Claude Code当成一个勤快、反应快、但经验不多的提前判断力的同事，花30秒把需求、边界和验收标准说清楚，它就能帮你把脏活累活干完，让你把时间省下来用在真正重要的调参和数据理解上。