基于PyTorch的鱼类识别全流程：CNN训练到浏览器Web部署实践

简介基于Python与PyTorch框架的常见鱼类分类识别项目带有可直接运行的HTML网页交互界面适合刚接触深度学习图像分类的开发者作为入门实战练习。压缩包共368个文件包含361张鱼类图片、3个Python脚本、3个txt文本和1个html页面整体大小约23.11MB。图片数据集按类别存放且包含翻转、旋转45度等增强版本可作为训练与验证样本txt文本记录图片路径与对应标签三个Python脚本分别完成数据列表生成、CNN模型训练和本地网页服务启动训练日志会记录每个epoch的验证集损失值与准确率便于直观查看模型收敛情况。项目结构清晰、依赖简洁配置好PyTorch环境后即可体验从数据准备到训练再到浏览器端识别预览的完整流程。已有157人学习下载适合希望快速搭建CNN图像分类demo并理解项目结构的初学者。1. 一个浏览器打开的鱼类识别项目数据集、CNN训练和 HTML 页面的完整闭环做图像分类的工程师应该都遇到过这种尴尬模型在 notebook 里跑得好好的精度也有但拿给同事看的时候总不能让人家打开终端敲命令。这个资源解决的就是这个问题——它把常见鱼类的图片数据集、基于 Python PyTorch 的 CNN 训练脚本以及一个能直接在浏览器里访问的 HTML 页面打包在了一起。你按顺序跑完三个脚本浏览器打开http://127.0.0.1:4399就能上传一张鱼的照片看到模型返回的类别判断。适合第一次想跑通「数据 → 训练 → Web 部署」全流程的人也适合需要快速做一个图像识别 demo 交差的场景。整体思路不复杂但每一步都有值得注意的细节下面按实际运行顺序拆开讲。2. 环境与目录先让 PyTorch Flask 的底子不拖后腿2.1 环境安装requirement.txt 与虚拟环境的实际操作下载解压后第一件事是装环境。资源里带了requirement.txt作者的说明里也附了环境安装教程链接。我的习惯是先用 conda 建一个干净的虚拟环境避免把系统 Python 搞乱conda create -n fish python3.8 conda activate fish pip install -r requirement.txt提示如果 conda 创建环境很慢可以加-c https://mirrors.aliyun.com/anaconda/pkgs/main/指定国内镜像源。先说逻辑为什么要虚拟环境因为 PyTorch 的版本和 CUDA 版本绑定很紧而你机器上跑着的其他项目可能依赖不同版本的 torch。隔离环境后这个项目里的依赖随便折腾坏了删掉重建就行。requirement.txt里通常包含 torch、torchvision、flask、pillow 这些核心库其中 torch 和 torchvision 的版本要对应否则 import 阶段就会报错。有一个常见问题需要提前说如果你只有 CPU 机器安装时请主动安装 CPU 版本的 torch命令是pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu。否则默认装的是 CUDA 版虽然也能在 CPU 上跑但体积大好几 GB纯属浪费。装完后在 Python 里执行下面这段确认 torch 能正常加载python -c import torch; print(torch.__version__, torch.cuda.is_available())能打印出版本号就是环境 OK。torch.cuda.is_available()输出False不代表不能跑只是训练会走 CPU速度慢一些。文件里的链接是作者留的环境安装参考我建议新手直接照做但如果你已经装过 PyTorch完全可以跳过这一步只需补齐 flask 和 pillow 这类轻量依赖。2.2 数据集命名规则_flip和_rotated45不是乱写的数据集文件夹里放着每个类别的图片文件名像这样181986ae-ddf1-4134-b050-05529630c5c1-290mm.jpg181986ae-ddf1-4134-b050-05529630c5c1-290m_flip.jpg181986ae-ddf1-4134-b050-05529630c5c1-290m_rotated45.jpg前面那串带横杠的字符串是图片的唯一编号后面接的是原始图片的采集尺寸再到_flip和_rotated45这两个后缀分别代表水平翻转和旋转 45 度。这是最基础的图像数据增强手段同一张鱼的照片经过翻转和旋转后相当于给模型多看了两个不同视角的样本。鱼类识别里鱼在图片里的朝向本身就不固定翻转和旋转正好模拟了这种不确定性能有效提升模型的泛化能力而不需要额外去网上找更多图片。这个命名习惯也提示了一件事数据集文件夹下大概率是按类别分子目录的某个目录下的图片全部属于同一个鱼种。GT 标签就来源于这个目录名而不是文件名里的编号。如果你自己以后收集数据集我建议沿用这个结构——省去写标注工具的时间脚本也能直接复用。2.3 三个脚本各管一段01 生成标签02 训练模型03 起 Web 服务整个项目的执行顺序是固定的依次运行01数据集文本生成制作.py、02深度学习模型训练.py和03html_server.py。这三个脚本的职责边界很清楚脚本职责产出物01 数据集文本生成制作.py读取数据集目录生成图片路径与标签的对应关系train.txt、val.txt02 深度学习模型训练.py读取 txt 文件训练 CNN 模型模型权重文件、训练日志 log03 html_server.py加载训练好的模型启动 Web 服务浏览器可访问的 URL很多人拿到代码后习惯先打开 03 看网页效果这样只会得到一个报错——因为模型还没训练出来html_server.py根本加载不到权重文件。所以老老实实按顺序跑。每个脚本的产物也是下一步的输入01 生成 txt02 读 txt03 读模型。这条链路是这套代码的主干理解它后面出任何问题都能快速定位出在哪个环节。3. 从图片到标签01 脚本的 TXT 生成逻辑与路径坑3.1 遍历目录、生成 train.txt / val.txt 的常见写法01 脚本的核心工作不涉及模型它只做一件事把「图片在哪」和「这是什么鱼」这两条信息写进文本文件。常见做法是遍历数据集根目录下的每个子目录子目录名作为类别名内部图片的路径和类别编号拼成一行写入 txt。代码大概是这样的import os from sklearn.model_selection import train_test_split data_root 数据集 # 数据集根目录 classes sorted(os.listdir(data_root)) # 每个子目录名是一个类别 class_to_id {cls: idx for idx, cls in enumerate(classes)} # 类别名映射编号 image_paths [] image_labels [] for cls in classes: cls_dir os.path.join(data_root, cls) for fname in os.listdir(cls_dir): if fname.lower().endswith((.jpg, .jpeg, .png)): image_paths.append(os.path.join(cls_dir, fname)) image_labels.append(class_to_id[cls]) # 按 8:2 划分训练集和验证集stratify 保证类别比例一致 train_paths, val_paths, train_labels, val_labels train_test_split( image_paths, image_labels, test_size0.2, stratifyimage_labels, random_state42 ) with open(train.txt, w, encodingutf-8) as f: for path, label in zip(train_paths, train_labels): f.write(f{path} {label}\n) with open(val.txt, w, encodingutf-8) as f: for path, label in zip(val_paths, val_labels): f.write(f{path} {label}\n) print(类别映射:, class_to_id) print(训练集样本数:, len(train_paths), 验证集样本数:, len(val_paths))这段代码的逻辑是这样首先用os.listdir拿到所有类别的目录名enumerate把目录名转成从 0 开始的数字编号——这就是 CNN 输出层每个节点对应的类别。然后遍历每个类别目录把图片的完整路径和标签编号配对。train_test_split按 8:2 切分时用了stratifyimage_labels它的作用是保证切分后的训练集和验证集里每个类别的样本比例和原始数据集一致防止某些稀有鱼类全被切到验证集导致训练时没见过这个类。random_state42是随机种子固定它能保证每次运行划分结果一致方便复现。写 txt 时每行格式是路径 空格 标签这个格式是后面 02 脚本用split()解析的约定两边必须对齐。3.2 翻转和旋转后的图片标签为什么不会乱你可能已经注意到同一张鱼的高清原图、翻转图、旋转图都在文件夹里。按上面的遍历逻辑它们会全部进入同一种鱼的目录下所以打上的标签编号是完全一样的。也就是说数据增强并没有改变类别归属只是增加了样本量。这种做法的好处是在规模较小的鱼种数据集上不需要额外采集图片就能把训练样本扩充 3 倍左右CNN 见过不同姿态的鱼之后对新的测试照片更不容易认错。但这里有一个隐藏问题需要留意如果原图、翻转图、旋转图被随机切分很可能出现「同一张鱼的原图在训练集、翻转图在验证集」的情况那验证集的准确率会虚高。严谨一点的做法是在切分时按图片编号去重——保证同一编号的所有增强图要么全进训练集要么全进验证集。这个资源没有在说明里提及这个细节介意的话可以在 01 脚本里按文件名的 UUID 前缀做分组切分否则就接受这个轻微的数据泄漏风险。对小项目 demo 来说影响不大但如果你要写论文或做正式评估这一步必须补上。3.3 路径分隔符和编码的实际问题这部分是我自己跑这类脚本时踩过最多的坑集中说一下。第一Windows 下的路径分隔符。如果你的数据集是 Windows 上解压的os.path.join会生成反斜杠路径数据集\鲤鱼\xxx.jpg写入 txt 后依然保留反斜杠。02 脚本在 Linux 服务器上跑的话open()读到的路径是数据集\鲤鱼\xxx.jpg此时应使用path.replace(\\, /)统一转为正斜杠再写入 text 文件。任何深度学习训练脚本都应该使用相对路径的 UNIX 风格否则换一台机器路径就全断了。第二txt 文件编码。如果数据集目录名或文件名带中文比如「数据集」这个根目录名就是中文写入 txt 时用encodingutf-8读取时也用encodingutf-8两边不一致就会报UnicodeDecodeError。Windows 默认的记事本保存是 GBK而 Python 在 Linux 下默认 UTF-8使用open(path, r, encodingutf-8)读取才能避免这种问题。第三路径里混有空格的情况。前文用split()来解析路径和标签如果路径里有空格split()会把路径拆成多个字段标签解析就错位了。更稳妥的写法是用rsplit( , 1)从右侧只拆一次这样路径即使有空格也能完整保留。我一般会让 txt 的格式变成标签 路径解析时先读标签再读路径逻辑更顺。4. CNN 训练看日志判断模型有没有学进去而不是只看准确率4.1 网络结构为什么小数据集不建议从头设计深层网络02 脚本是整套代码的核心负责真正训练 CNN。对于常见鱼类识别这种小规模数据集我建议使用 torchvision 自带的预训练模型作为特征提取器常见选择是 ResNet18。它是个 18 层的残差网络参数 1100 万左右单张图片在 CPU 上推理大约需要几十毫秒属于精度和速度都比较均衡的选项。完整代码结构如下import torch import torch.nn as nn from torchvision import models, transforms from torch.utils.data import Dataset, DataLoader from PIL import Image # 自定义 Dataset读取 txt 中记录的路径和标签 class FishDataset(Dataset): def __init__(self, txt_path, transformNone): self.samples [] with open(txt_path, r, encodingutf-8) as f: for line in f: path, label line.rsplit( , 1) self.samples.append((path, int(label))) self.transform transform def __len__(self): return len(self.samples) def __getitem__(self, idx): path, label self.samples[idx] image Image.open(path).convert(RGB) if self.transform: image self.transform(image) return image, label # 使用预训练 ResNet18替换最后一层全连接 model models.resnet18(weightsmodels.ResNet18_Weights.IMAGENET1K_V1) num_classes 5 # 实际类别数由 01 脚本输出的 txt 决定 model.fc nn.Linear(model.fc.in_features, num_classes) # 训练集做随机翻转增强验证集只做缩放 train_transform transforms.Compose([ transforms.Resize((224, 224)), transforms.RandomHorizontalFlip(), transforms.ToTensor(), transforms.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225]) ]) val_transform transforms.Compose([ transforms.Resize((224, 224)), transforms.ToTensor(), transforms.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225]) ]) train_loader DataLoader(FishDataset(train.txt, train_transform), batch_size16, shuffleTrue) val_loader DataLoader(FishDataset(val.txt, val_transform), batch_size16, shuffleFalse)关键点在于weightsmodels.ResNet18_Weights.IMAGENET1K_V1这行。它加载了在 ImageNet 上预训练好的权重而不是从零开始训练。这样做的好处很明显ImageNet 上学到的边缘、纹理、形状特征对鱼类这种物体识别是有迁移价值的预训练权重把模型初始化到一个比较好的位置后面只需用少量鱼类图片微调即可。如果你从零训练一个随机初始化的 ResNet18在这个小数据集上基本会过拟合训练损失降不下去验证集准确率也上不来。num_classes的取值要和 01 脚本输出的类别数一致全连接层的输出节点是从 0 到num_classes - 1多了少了一旦模型保存后面推理也会对应不上。训练集加了RandomHorizontalFlip它对加载的图片随机水平翻转是又一层数据增强和数据集文件夹里预置的_flip图片是两回事——预置的翻转图扩充了静态样本训练时的随机翻转让每个 epoch 看到的样本有细微不同进一步抑制过拟合。4.2 训练参数epoch、batch、学习率怎么定训练过程比较常规但有几个参数值得说透参数推荐取值原因epoch2030小数据集上预训练模型收敛快30 轮之后验证集准确率基本到平台期batch_size16数据集量小batch 太大容易导致梯度方向过于平滑太小则训练不稳定学习率0.001微调阶段不建议用 0.01 以上的学习率容易破坏预训练权重优化器Adam自适应学习率省去手动调整学习率衰减的麻烦损失函数CrossEntropyLoss多分类任务的标准选择内部会做 softmax训练循环里一般每训练完一个 epoch就在验证集上算一次平均 loss 和准确率并把结果追加写入日志文件。这也就是资源描述里说的「训练完成之后会有 log 日志保存本地里面记录了每个 epoch 的验证集损失值和准确率」。判断模型好坏的依据不是训练集 loss而是验证集 loss 和准确率。如果训练集 loss 一直下降、验证集 loss 先降后升这是典型的过拟合信号说明模型开始死记训练样本了。此时应该提前停止训练不是硬跑完预设的 30 轮。我一般看到验证集准确率连续 5 个 epoch 没有提升就把当前最优的权重保存下来。4.3 模型保存与加载存 state_dict 而不是整个模型训练完后保存模型这里有个细节容易被新手忽略。看下面的保存方式best_acc 0.0 for epoch in range(30): # 训练和验证逻辑省略计算 val_acc if val_acc best_acc: best_acc val_acc torch.save(model.state_dict(), best_model.pth) print(fEpoch {epoch}: save best model, acc{val_acc:.4f})model.state_dict()保存的是模型的全部权重参数是一个 dict 对象。推荐保存它而不是整个模型对象原因有二一是 state_dict 文件更小只包含权重二是加载时你必须先构建同样的网络结构再灌入权重这个「先建结构再灌权重」的过程强制你保持训练和推理的代码一致反而不容易出错。加载是这样model models.resnet18(weightsNone) model.fc nn.Linear(model.fc.in_features, num_classes) model.load_state_dict(torch.load(best_model.pth, map_locationcpu)) model.eval()要特别注意的是map_locationcpu。如果你在 GPU 上训练了模型拿到没有独显的电脑上做网页推理不加这个参数会直接报 CUDA 相关的错。另外模型保存时处于训练模式加载后必须调用model.eval()切换到推理模式否则 Dropout 和 BatchNorm 的行为不一致同一张图预测结果可能在四次运行中不重样。很多网页识别概率不稳、这次对那次错的情况就是漏了eval()导致的。5. 避坑环境、端口、标签对不上的高频翻车现场5.1 现象浏览器打开http://127.0.0.1:4399一直转圈页面加载不出来原因03html_server.py根本没有运行或者运行了但端口被别的程序占用了。Flask 默认服务app.run(host127.0.0.1, port4399)如果这个端口被其他进程占用服务启动会直接报错退出终端里也看不到任何 URL 信息。解决先在终端确认 03 脚本是否打印了Running on http://127.0.0.1:4399之类的字样确认后在浏览器重新输入。如果端口占用把代码里的port4399改成port5000或port8080然后重新运行脚本。我一般建议改端口而不是杀进程因为杀进程可能误伤其他正在运行的项目。5.2 现象训练跑完了网页预测结果一直集中在某一个类别原因标签和路径没对齐或者数据集类别严重不平衡。训练时模型发现只要全部猜样本最多的那个类就能拿到很高的准确率于是「偷懒」把所有图片都归为这一类。这类问题在 02 脚本的训练日志里能看到端倪——验证集准确率不低但每一类的召回率差距很大。解决先检查 01 脚本生成的 train.txt打印前 20 行确认路径对应的类别编号是否和目录名一致。然后统计每个类别的图片数量。如果某个类别图片数量是其他类的两倍以上建议在 01 脚本里加stratifyimage_labels保证训练集和验证集的类别比例一致。还有一个常用做法是在损失函数上做文章给样本少的类别设置更高的权重class_weights torch.tensor([1.0, 1.5, 1.2, 0.8, 2.0]) # 按每个类别样本数的倒数设置 criterion nn.CrossEntropyLoss(weightclass_weights)weight参数让模型在计算损失时对稀有类别的错误分类加大惩罚从而把注意力从高频类别上拉回来一部分。5.3 现象运行 01 脚本时提示No such file or directory或者UnicodeDecodeError原因数据集文件夹路径不对或者 txt 的编码和读取时不一致。尤其是根目录叫「数据集」这种中文名称时在 Windows 下用 GBK 写入、在 Linux 下用 UTF-8 读取就会解码失败。解决第一步可以先在 01 脚本开头打印os.path.abspath(data_root)确认脚本运行时的当前目录和数据集实际位置对得上。第二步确保写入和读取 txt 时都显式加上encodingutf-8。如果别人的 txt 已经是 GBK 编码可以用下面这段快速转码iconv -f GBK -t UTF-8 train.txt train_utf8.txt mv train_utf8.txt train.txt5.4 现象用 CPU 训练一个 epoch 要跑十几分钟原因没有安装 CUDA 版本的 PyTorchtorch.cuda.is_available()返回False所有计算全压在 CPU 上。解决这是环境问题不是代码问题。如果你电脑有 NVIDIA 显卡先确认驱动版本再重装对应 CUDA 版本的 PyTorch。如果没显卡就不要用 ResNet18 这种模型把网络换成更轻量的torchvision.models.mobilenet_v2它参数量只有 ResNet18 的一半左右CPU 训练速度能提升明显精度损失在可接受范围。另一种思路是减小图片尺寸和 batch_size把Resize((224, 224))改成Resize((160, 160))简单粗暴但有效。5.5 现象网页能打开但上传图片后提示识别失败或页面报错原因大概率是模型类别数和网页显示的类别数不一致或者 03 脚本没有正确处理上传的图片格式。解决先看终端窗口有没有抛异常。如果是 key 不存在之类的字典报错说明idx_to_class映射写错了——07 训练时类别编号从 0 开始网页显示时要从模型输出的索引映射回类别名这个映射需要和 01 脚本里的class_to_id保持一致。上传图片角度检查一下图片格式Flask 端一般只接受jpg/png/jpeg有些手机拍出来是 HEIC 格式浏览器上传前先转成 jpg 再试。提示遇到问题先看终端Flask 服务的所有异常都会打印在终端里。浏览器页面上的提示不一定准确终端里的堆栈才是真正的线索。6. 把准确率往上拉的收尾习惯批量验证与类别扩展模型训练完网页也能识别了但这时候项目只算完成了一半。我每次训练完都会额外做一遍批量验证用训练时留下的 val.txt把所有验证集图片跑一遍统计每一类的准确率和召回率而不只是看一个总准确率数字。这一步很有用因为总准确率会掩盖单类表现差的问题——比如某一种鱼和另一种鱼外观很像模型容易把这两种搞混但你只看准确率 90% 是发现不了这个问题的。批量验证的脚本很轻量核心就是把验证集图片全部过一遍模型按类别统计correct_per_class [0] * num_classes total_per_class [0] * num_classes with torch.no_grad(): for images, labels in val_loader: outputs model(images) _, preds torch.max(outputs, 1) for label, pred in zip(labels, preds): total_per_class[label] 1 if label pred: correct_per_class[label] 1 for i in range(num_classes): print(fClass {i}: {correct_per_class[i]}/{total_per_class[i]})把每一类的分母和分子打在屏幕上一眼就能看出哪类样本少、哪类容易混。找到混淆严重的两个类别后我会回到数据集里对比它们各自的图片观察是不是拍摄角度或背景差异太大。如果某个类别的图片大多是在同一个背景下拍的模型很可能学到了背景而不是鱼本身这时候需要补充不同背景的图片或者对训练集做更强的颜色抖动增强。至于类别扩展流程非常简单在数据集文件夹下新建一个类别目录把新鱼种图片放进去重新运行 01 生成 txt再重新训练一遍网页上的类别列表自然就多了一项。注意类别目录名的命名风格要和现有目录保持一致训练时它会被os.listdir自动识别并分配编号。只要 01、02、03 三个脚本的类别顺序是从同一份数据生成的就不会出现网页显示类别和模型输出对不上的问题。说一个我自己的习惯每次训练完我都会从验证集里随机抽 20 张图片让模型预测后把图片和预测结果拼成一张大图肉眼过一遍。准确率 0.95 听上去很美但当你亲眼看到模型把一条鲫鱼识别成鲤鱼时才会认真审视数据集的质量问题——是不是两类鱼混放在同一个目录了是不是某张图本身就不清晰这个动作花不了几分钟但能避免你在错误的方向上浪费更多时间。从那以后我每训练完一个版本模型都强制自己走一遍「抽 20 张肉眼验证」再宣布完成。希望这个习惯对你的项目也有用。本文还有配套的精品资源点击获取