基于PyTorch与PyQt5的乳腺癌超声分割诊断系统实战

上周帮一个做毕设的朋友看代码，他的乳腺超声分割模型在验证集上 Dice 跑到 0.91，画面很漂亮。结果他把预测掩膜叠回原图问我：为什么这一张的轮廓框住了整幅超声图。我让他把标签图单独打出来看，问题出在数据本身——数据集里同一张超声图对应两个病灶，标签是两张_mask.png，他的加载函数图省事只读了文件名最短的那张，于是"双病灶"样本在训练时全部变成了"单病灶"，模型学出来的边界自然是错的。这种不写在论文里、但能实实在在毁掉结果的问题，贯穿了这套系统从数据加载到界面显示的每一个环节。

这篇就围绕"基于深度学习的乳腺癌智能检测分割与诊断系统"这个项目，把 Python 源码、PyQt5 界面、数据集和训练代码这条链路完整拆开聊一遍。适合正在做医学图像方向毕设、课程设计或者大作业的同学，也适合第一次想把分割模型落到一个"能点得动"的桌面程序上的人。我不会给你一份号称万能的配置清单，而是把每一处选择的理由、参数的来路、真实踩过的坑都讲清楚，你看完应该能自己把结构改成适合自己数据的样子。

说明：本文讨论的是一个用于学习与研究的图像分割和分类系统，输出结果仅作技术演示与教学参考，不能作为任何临床诊断依据。

1. 从一张超声图到一句"良性/恶性"：这套系统的任务链路拆解

很多人接到这个题目，第一反应是"不就是个二分类吗，拿 ResNet 跑一下完事"。真做起来会发现，只给"良性/恶性"这个结论，答辩时很难说清楚依据在哪里；医生看片子也是先圈出病灶位置、量一量形态边缘是否规则，再综合判断。所以这套系统做成了两段式：先做目标分割把病灶区域从整幅超声图中抠出来，再基于这个区域做良恶性判别。这个顺序不是凑工作量，而是有实际收益的。

1.1 分割打底带来的两个直接好处

第一个好处是把无关区域排除掉。乳腺超声图像的成像范围很大，脂肪层、腺体、胸肌回声全部混在一起，病灶可能只占画面很小一块。直接拿整图做分类，卷积网络要花大量容量去"学会忽略"背景，样本量小的时候很容易过拟合到扫描仪、探头这些域特征上。先分割出感兴趣区域（ROI），再对 ROI 做分类，输入的信息密度一下子就上去了。

第二个好处是可解释性。分割掩膜可以直接叠加显示在界面上，用户看到的是"模型认为这里有问题"，而不是一个孤零零的概率数字。对于教学演示类项目，这一点在展示环节的加分远比多涨 0.5 个点准确率重要。

我一般会把它拆成三张表来对照，方便理清每个模块的输入输出边界：

1.2 建议的工程目录结构

别小看这一步。我见过太多项目把训练脚本、预测脚本、界面代码、权重文件全塞在一个文件夹里，最后自己都分不清哪个model.pth是哪个实验的产物。下面这套结构是我反复用过、扩展性比较舒服的：

breast_ai/ ├── data/ │ ├── raw/ # 原始数据集，只读不改 │ └── splits/ # train.txt / val.txt / test.txt ├── src/ │ ├── datasets/ │ │ └── busi.py # Dataset 与掩膜合并逻辑 │ ├── models/ │ │ ├── unet.py # 分割网络 │ │ └── classifier.py # 分类网络 │ ├── losses.py # Dice / BCE / 复合损失 │ ├── metrics.py # 评估指标实现 │ ├── train_seg.py │ ├── train_cls.py │ └── infer.py # 供界面调用的推理封装 ├── ui/ │ ├── main_window.py │ └── worker.py # QThread 推理线程 ├── weights/ └── requirements.txt

关键点是推理逻辑必须独立于界面。infer.py里只依赖 PyTorch 和 NumPy，不 import 任何 PyQt5 的东西。这样你既可以在命令行批量跑测试集算指标，也能在界面里直接调用同一个函数，不会出现"训练时好好的、界面里结果不一样"的诡异问题。

1.3 为什么选 PyTorch 加 PyQt5 这套组合

深度学习框架这边没什么可纠结的，PyTorch 的动态图和调试体验对教学项目更友好，print一下 tensor 的形状就能定位大部分问题，不用去理解静态图的占位符机制。医学图像分割这个细分方向，公开实现的 U-Net 变体、指标库、预训练权重也基本都以 PyTorch 为主。

界面选 PyQt5 的理由则更实际：它足够成熟，能做出表格、文件夹选择、图像缩放这类"看起来像个正经软件"的控件，同时社区里现成的问题解答非常多。你遇到窗口不显示、中文乱码、图标缺失这类问题，基本都能搜到别人踩过的同款。相比之下 Tkinter 做复杂布局会比较痛苦，Web 方案又要额外学前端和部署，对只想把算法展示出来的项目来说不划算。

有一点要提前想清楚：界面里的推理线程和主线程是两回事。这个坑我在第 5 节会专门拆开讲，因为它经常表现为"程序点了没反应"，让人以为是模型太慢，其实是主线程被阻塞了。

2. BUSI 数据集落地：多掩膜合并、角落文字与划分策略

模型结构抄一抄就有了，真正拉开差距的是数据处理这一段。乳腺超声公开数据集里，BUSI 是使用频率比较高的一个，包含正常、良性、恶性三类，每张图都配有专家标注的掩膜。听起来很规整，实际打开一看，细节问题一堆。

2.1 目录结构与掩膜匹配的正确写法

数据集的典型组织方式是按类别分文件夹，图像与掩膜同名并加后缀：

Dataset_BUSI_with_GT/ ├── benign/ │ ├── benign (1).png │ ├── benign (1)_mask.png │ └── benign (1)_mask_1.png # 同一张图的第二个病灶 ├── malignant/ └── normal/

normal目录下的掩膜基本是全黑的，这一点要在标签生成阶段处理掉——如果直接当成"无病灶"的正样本喂给分割网络，模型会被大量全零标签带偏，倾向于输出一片空。我通常的做法是分割训练集只保留benign和malignant，把normal留给分类任务或者只做负样本对照。

匹配掩膜时，不要用简单的glob("*_mask*.png")然后取第一个，必须先按文件名主干归组，再把同一组的掩膜做并集。合并后的掩膜就是这张图全部病灶的区域，这一步漏了，多病灶样本的标注就是残缺的。核心逻辑大概是这样：

import numpy as np from PIL import Image from pathlib import Path def load_image_and_mask(img_path: Path): # 去掉 .png 得到主干，再收集它所有掩膜 stem = img_path.stem # 例如 "benign (1)" mask_files = sorted(img_path.parent.glob(f"{stem}_mask*.png")) if not mask_files: raise FileNotFoundError(f"找不到掩膜: {img_path}") img = np.array(Image.open(img_path).convert("L"), dtype=np.uint8) # 多掩膜取并集，而不是覆盖 merged = np.zeros(img.shape, dtype=np.uint8) for mf in mask_files: m = np.array(Image.open(mf).convert("L"), dtype=np.uint8) if m.shape != merged.shape: m = np.array(Image.fromarray(m).resize( (merged.shape[1], merged.shape[0]), Image.NEAREST)) merged = np.maximum(merged, m) mask = (merged > 127).astype(np.uint8) # 二值化，注意用最近邻缩放 return img, mask

这里有两个细节值得单独说。掩膜缩放必须用最近邻插值（Image.NEAREST），双线性插值会造出 0 到 255 之间的灰边，二值化之后边缘会多出一圈幽灵像素。二值化阈值取 127 是个习惯值，如果你的掩膜来源于不同标注工具，先统计一下像素值分布，确认它确实是 0/255 而不是 0/1。

2.2 角落的水印文字必须裁掉

BUSI 的原图右下角有一小段文字标注，内容大概是类别和图像尺寸。它本身不影响人看，但对模型是个非常讨厌的捷径特征：良性图的文字和恶性图的文字是不同的，网络完全可以靠右下角那几个像素把分类做对，看起来准确率很高，实际毫无意义。更糟的是，如果测试集里也有这段文字，指标会虚高到离谱。

处理方式有两种：一是统一裁掉底部一块区域，二是把这块区域用邻域像素填掉。我通常用第一种，简单粗暴：

def crop_annotation(img, mask, crop_bottom=25): h, w = img.shape return img[:h - crop_bottom, :], mask[:h - crop_bottom, :]

裁多少要看你的数据版本。建议先随机抽 20 张，把右下角放大看一眼文字的像素范围，再定这个值。宁多裁一点，别少裁。

2.3 超声图像增强的边界在哪里

数据增强这块很容易用力过猛。医学图像和自然图像的分布差别很大，超声的灰度值直接对应组织回声强弱，某些变换会破坏这个物理含义。

可以放心用的：水平翻转、小角度旋转（±15 度以内）、轻微亮度对比度扰动、随机缩放加裁剪。这些变换不会改变"亮的地方还是亮的"这个前提。

要谨慎或避免的：垂直翻转，乳腺解剖结构有明确的方向性；弹性形变，它会改变病灶边缘的形态学特征，而边缘是否规则恰恰是良恶性判别的重要依据；颜色抖动和饱和度调整，超声本来就是单通道的，没有颜色可言；随机擦除，擦掉一块可能正好把病灶盖住，标签却还是原来的，等于造了错样本。

一个我踩过的坑是增强后掩膜和图像没同步。用 albumentations 这类库时要确保图像和掩膜放进同一个 transform，掩膜走最近邻插值：

import albumentations as A train_tf = A.Compose([ A.HorizontalFlip(p=0.5), A.Rotate(limit=15, border_mode=0, p=0.5), A.RandomBrightnessContrast(brightness_limit=0.15, contrast_limit=0.15, p=0.3), A.Resize(256, 256), ], additional_targets={}) # 使用时把 mask 作为 mask 参数传入，库内部会保证几何变换一致 out = train_tf(image=img, mask=mask)

2.4 类别失衡下的数据划分

BUSI 的三类分布很不均匀，良性数量大约是恶性的两倍，正常类最少。做患者级划分是最理想的做法（同一患者的所有图像只出现在一个子集里），但如果数据集没给患者编号，就只能按图像随机划分。这时候要注意：同一张图如果被切成了多个 patch，这些 patch 必须落在同一个子集，否则就是数据泄漏。

划分比例我一般用 7:1.5:1.5。样本本来就少，验证集留太大不划算，但也不能不留——用训练集指标判断收敛是自欺欺人。划分结果写进splits/*.txt固定下来，之后所有实验都用同一份，别每次跑都重新随机，否则你没法比较两个模型到底谁更好。

类别失衡的补偿手段有三条常见路线：给损失函数加类别权重、在采样器里做加权采样、对少数类做过采样。我的经验是优先调损失权重，因为它不改变数据分布，只是让梯度更关注少数类；加权采样容易让模型反复看同一批少数类样本，过拟合得非常快。

3. 分割网络怎么搭：U-Net 编码器、复合损失与 Dice 指标的配合

分割这一块，结构上其实没有太多花哨的余地。样本量几百张的数量级，去堆很深的网络或者用很复杂的注意力模块，收益远不如把数据管好。

3.1 U-Net 在小样本医学图像上为什么依然好用

U-Net 的核心是编码器逐层下采样提取语义、解码器逐层上采样恢复分辨率，中间用跳跃连接把编码器的高分辨率特征直接拼到解码器上。这个设计对医学图像特别合适，原因在于医学目标往往边界模糊、形状不规则。深层特征知道"这里有病灶"，但已经丢失了精确的定位信息；浅层特征保留了边缘细节，却不知道哪些是病灶。跳跃连接把两者拼起来，网络才能既知道有没有、又知道在哪里。

我自己实现的时候喜欢用最朴素的版本：四次下采样，通道数 32-64-128-256-512，每次两个 3×3 卷积加 BatchNorm 加 ReLU，上采样用双线性插值加卷积而不是转置卷积。转置卷积容易产生棋盘格伪影，在分割边界上表现为规则的小方格，叠加显示时很难看。双线性上采样加卷积虽然慢一点点，但输出干净得多，这个取舍我觉得很值。

编码器可以换成 ImageNet 预训练的 ResNet34 或 EfficientNet，对小数据集帮助明显。但要注意一点：灰度图只有一个通道，而预训练权重是按三通道训练的。把单通道复制成三通道是常见做法，能复用权重，代价是参数量比单通道多。如果显存紧张，也可以保留单通道输入，只加载除第一层之外的权重。

3.2 BCE 加 Dice 复合损失，为什么要给 Dice 加权

单纯用二元交叉熵（BCE）训练分割，在正负样本极度不均时会出问题：病灶只占图像百分之几的像素，网络只要全部预测为背景，BCE 就已经很低了。它优化的是像素级准确率，而这个指标在失衡场景下毫无意义。

Dice 损失直接优化预测掩膜和真实掩膜的重叠度，对失衡天然不敏感，因为它衡量的是交集占并集的比例，跟背景有多少像素没关系。但 Dice 单独用也不理想，它梯度在预测和标签完全不相交时会不稳定，训练前期容易震荡。

所以通常把两者加起来：

import torch import torch.nn as nn import torch.nn.functional as F class BCEDiceLoss(nn.Module): def __init__(self, bce_weight=0.5, dice_weight=1.0): super().__init__() self.bce_weight = bce_weight self.dice_weight = dice_weight def forward(self, logits, targets, eps=1e-6): # logits: (B, 1, H, W)，targets: (B, 1, H, W) 取值 0/1 bce = F.binary_cross_entropy_with_logits(logits, targets) probs = torch.sigmoid(logits) probs = probs.view(probs.size(0), -1) targets = targets.view(targets.size(0), -1) inter = (probs * targets).sum(dim=1) union = probs.sum(dim=1) + targets.sum(dim=1) dice = (2 * inter + eps) / (union + eps) dice_loss = 1 - dice.mean() return self.bce_weight * bce + self.dice_weight * dice_loss

权重的分配我是这样定的：Dice 权重设 1.0，BCE 设 0.5。理由是在小病灶上 Dice 的梯度信号更直接，给你更快的收敛；BCE 作为稳定项，权重小一点，防止 Dice 在空掩膜或极小病灶上把训练带崩。这个比例不是定律，如果你发现训练早期 loss 剧烈震荡，把 BCE 权重提到 0.8 到 1.0 试试。

提示：计算 Dice 时一定要加eps。当某张图的预测和标签都全零（比如 batch 里混入了无病灶样本），分母为零，会产生 NaN 并污染整个 batch 的梯度，训练几轮之后 loss 突然变成 nan，多半就是这个原因。

3.3 训练循环、指标计算与阈值后处理

训练循环本身没什么特别，但有几个地方值得写清楚。优化器用 Adam，学习率 1e-4，配余弦退火；batch size 在 256×256 输入下取 8，显存不够就降到 4 并相应调小学习率。梯度裁剪加上，clip_grad_norm_(model.parameters(), 1.0)，能挡掉一部分异常梯度。

验证阶段算 Dice 和 IoU，注意要在 sigmoid 之后、按阈值二值化之后算，而不是拿概率图算，否则报出来的数字会比实际部署时的表现好。阈值默认 0.5，但如果你的模型偏向保守（漏检多），可以扫一遍 0.3 到 0.7，取验证集上敏感度和 Dice 综合最优的值，这个阈值要记下来，推理时用同一个。

预测完之后加一步连通域后处理：取最大连通域，去掉面积小于某个阈值的孤立小斑块。超声图像里 speckle 噪声很重，模型偶尔会在一片噪声上激活出几十个像素的小块，视觉上很干扰。用scipy.ndimage.label配合binary_opening做一次开运算加最大连通域筛选，通常能明显改善观感：

import numpy as np from scipy import ndimage def postprocess(prob: np.ndarray, thr=0.5, min_area=100): binary = (prob > thr).astype(np.uint8) # 开运算抹掉细小的椒盐状激活 binary = ndimage.binary_opening(binary, structure=np.ones((3, 3))) labeled, n = ndimage.label(binary) if n == 0: return np.zeros_like(binary, dtype=np.uint8) # 只保留最大连通域 sizes = ndimage.sum(binary, labeled, range(1, n + 1)) keep = np.argmax(sizes) + 1 return (labeled == keep).astype(np.uint8)

这一步的min_area需要按图像实际尺寸调。如果你的输入是 256×256，100 像素大约对应原图上两三百像素的面积，这个量级基本能滤掉噪声又不会误删真病灶。参数值最好在验证集上抽几张图肉眼确认一遍。

4. 良恶性判别的两条路线：从掩膜到最终结论

分割做完，拿到掩膜，接下来的问题是怎么把它用到分类上。这里有两条路，各有取舍。

4.1 路线一：按掩膜裁 ROI，再接一个分类网络

第一种做法最直观：算出掩膜的外接矩形，向外扩一圈留出边界上下文，从原图上裁出这块区域，然后送进一个分类网络。

外扩多少要斟酌。完全不外扩，输入刚好贴着病灶边缘，模型看不到周边的组织回声对比，反而判断力下降；外扩太多，又退回到整图分类的问题。我一般按短边的 15% 到 25% 外扩，然后统一 resize 到 224×224。

裁出来的区域要补齐成方形再 resize，否则拉伸会改变病灶的长宽比，而形态比例本身是判别依据之一。补齐用边缘反射或者补零都可以，实测补零（黑边）效果更稳。

分类网络我建议从 ResNet18 或 EfficientNet-B0 这类轻量模型起步，ImageNet 预训练权重加载上，只训练最后两层加分类头，学习率 1e-3；训几轮之后再整体微调，学习率降到 1e-4。这个"先冻后放"的顺序在小样本上非常关键，直接全量微调容易把预训练学到的通用特征在几十个 epoch 里冲干净。

有个细节容易被忽略：分类网络必须看分割给的掩膜吗。如果训练时分类器看到的是专家标注掩膜裁出的 ROI，而部署时看到的是分割网络预测的掩膜裁出的 ROI，两者有差距（预测的掩膜可能偏大或偏小），分类性能会掉。解决办法是用预测掩膜重新生成一批 ROI 做微调，或者干脆在训练时就加一点掩膜扰动（随机膨胀/腐蚀几个像素）做增强，让分类器对边界误差不敏感。这个技巧我用过之后，端到端指标稳定了不少。

4.2 路线二：共享编码器加双输出头

第二种做法是一个编码器同时接两个头：一个头上采样输出分割图，另一个头做全局池化后输出分类概率，两个损失加权求和联合训练。

优点是参数量省、推理只跑一次；多任务学习还能互相正则化，分割任务迫使编码器学到病灶的形状信息，分类任务迫使它学到语义信息，两边都能受益。缺点也明显：两个损失的量级不平衡会导致其中一个任务主导训练。分割损失通常在 0.3 到 0.8 之间，分类的交叉熵在 0.1 到 0.6 之间波动，如果不加权，你很可能看到分割指标涨得很好而分类纹丝不动，或者反过来。

实操上我建议给分割损失乘 1.0、分类损失乘 1.5 到 2.0，先让分类指标正常收敛，再回头看分割有没有被拖累。另外这种共享结构对 batch 里的样本有要求——分类任务需要三个类别的样本都有，分割任务只需要有病灶的样本，如果 batch 里全是正常样本，分割那一路的标签全零，梯度会有噪声。用一个平衡采样器能缓解这个问题。

两条路线的对比可以这样看：

如果这是你第一个医学图像项目，我建议先走路线一，把两段都跑通、指标稳住，再考虑换成路线二对比效果。两条路都做完写进报告，本身就是很有说服力的对比实验。

4.3 指标选择：为什么准确率会骗人

分类这块最容易犯的错是只报准确率。假设测试集里 70% 是良性，模型学会无脑输出"良性"，准确率就能到 70%。这在医学场景下意味着大量恶性被漏判，后果比误判严重得多。

该报的指标至少要有这几个：敏感度（真正例率，衡量恶性有没有被找出来）、特异度（真负例率，衡量良性有没有被误判成恶性）、AUC（不受阈值影响的整体区分能力）、F1（精确率和召回率的调和平均）。如果数据集三类都要判，还要看混淆矩阵，特别是良性和恶性之间的互混有多少。

还有个工程上的习惯：把单张推理耗时也记录下来。P50 和 P95 都测一下，因为界面上的体验取决于最慢那几张，而不是平均值。

5. PyQt5 界面工程化：线程、显示异常与高分屏适配

算法跑通只是前半程。把模型塞进界面之后，会遇到一批和算法完全无关、但足够折腾人的问题。

5.1 界面功能分区与控件组织

我的习惯是主窗口用标签页分三个区域，逻辑清晰也好讲：

• 单图检测：左边显示原图和叠加掩膜，右边是结论、置信度、病灶面积占比，下面一个"选择图像"按钮和一个"开始分析"按钮。
• 批量处理：一个文件夹选择器、一个文件列表、一个进度条、一个导出结果表格的按钮。
• 模型设置：切换分割权重和分类权重的下拉框、设备选择（CPU/GPU）、置信度阈值调节滑块。

图像显示用QLabel配合QPixmap，缩放时用setScaledContents(False)再手动按比例 resize，避免拉伸变形。如果原图是单通道灰度，需要先转成三通道 QImage 的Format_RGB888，直接用灰度格式在部分平台上会显示成奇怪的颜色。

结论显示不要只写"恶性"两个字，把置信度和分割指标一起放上去，比如"恶性，置信度 0.87，病灶面积占图像 3.2%"。信息量上去了，答辩的时候也好讲。

5.2 用 QThread 跑推理：为什么不能在主线程里做

这是新手最常踩的坑，也是"界面卡死"的第一大来源。PyQt5 的主线程负责事件循环，所有控件重绘、按钮响应都在这个线程里。你只要在主线程里调一次model(image)，整个界面就会冻结到推理结束。CPU 上跑一次可能一两秒，看起来只是"顿一下"；但如果跑批量任务，几百张图下去，程序直接无响应，用户会以为它崩了。

正确的做法是把推理放到QThread里，通过信号槽把结果传回主线程更新界面。worker 线程里绝对不能直接碰任何控件，这是硬约束，违反了轻则界面错乱，重则直接闪退。

from PyQt5.QtCore import QThread, pyqtSignal import numpy as np class InferWorker(QThread): finished_ok = pyqtSignal(object, object, str) # 原图, 掩膜, 结论 failed = pyqtSignal(str) def __init__(self, engine, img_path): super().__init__() self.engine = engine # 封装好的推理对象 self.img_path = img_path def run(self): try: img, mask, label = self.engine.predict(self.img_path) self.finished_ok.emit(img, mask, label) except Exception as e: self.failed.emit(str(e))

主线程里创建 worker、连接信号、调用start()。注意InferWorker(self)传 parent 是为了让 Qt 管理生命周期，但如果你的 worker 是长期复用的，父对象设成 None 手动管理更安全，避免窗口关闭时线程还在跑导致解释器退出时报错。

关于阻塞式调用的又一个坑：有些人会用while worker.isRunning(): pass去"等"线程结束，这等于把主线程又占住了，界面照样卡死。要用信号驱动，不要用轮询等待。

5.3 OpenGL 导致窗口不显示、高分屏错位这类问题的处理

有一类问题非常折磨人：代码没有任何异常，进程也起来了，但窗口就是不出现。常见的诱因是 Qt 的渲染后端在某些环境下初始化失败，尤其是在虚拟机、远程桌面或者显卡驱动不完整的机器上。

处理方式是在创建 QApplication 之前设置渲染后端属性，注意顺序，这行代码写在 QApplication 后面完全无效：

import sys from PyQt5.QtCore import Qt from PyQt5.QtWidgets import QApplication # 必须在 QApplication 实例化之前设置 QApplication.setAttribute(Qt.AA_UseSoftwareOpenGL, True) # 高分屏缩放，同样要在实例化前设置 QApplication.setAttribute(Qt.AA_EnableHighDpiScaling, True) QApplication.setAttribute(Qt.AA_UseHighDpiPixmaps, True) app = QApplication(sys.argv)

软件渲染会牺牲一点性能，但对这种以 2D 图像展示为主的程序完全够用，换来的是在所有机器上都能开起来。如果必须用硬件渲染，也可以改环境变量指定后端，但软件渲染是最省心的兜底方案。

高分屏问题是另一类。4K 屏上默认可能显示成指甲盖大小，或者控件文字被截断。开启AA_EnableHighDpiScaling之后，还要注意所有硬编码的像素尺寸都要重新检查一遍——你在 1080P 上调好的 300×300 显示区，在 200% 缩放下会显得很小。建议布局全部用QVBoxLayout/QHBoxLayout这类布局管理器，少用setGeometry绝对定位，缩放适配会好很多。

提示：如果界面里的中文显示成方块，通常是字体问题。可以显式设置app.setFont(QFont("Microsoft YaHei", 10))，或者在打包时确保字体文件被包含进去。这个问题在开发机上往往不出现，换个环境才暴露。

批量处理那块还有个小细节值得做：进度条要真正反映进度，而不是走个假动画。每处理完一张 emit 一次进度信号，同时把已完成的结果追加进表格。用户体验上的差别很大，而且如果中途某张图报错，你能立刻知道卡在第几张。

6. 从训练到打包：只在交付前一夜暴露的那些坑

6.1 模型加载方式不一致导致的指标跳水

训练时 Dice 0.9，界面里跑同一张图变成 0.5，这种"指标跳水"绝大多数不是模型的问题，而是推理路径和验证路径不一致。

常见的不一致点有三个。第一个是忘了切 eval 模式。model.eval()会关闭 Dropout 并让 BatchNorm 使用训练时累积的统计量而不是当前 batch 的统计量。批量推理时忘了这行，BN 用的是每批数据自己的均值方差，单张推理时就是用它自己的统计量，输出必然和训练时不一样。

第二个是忘了torch.no_grad()。虽然它主要影响显存和速度，但在某些层的行为上也存在差异，而且不做的话单张图显存占用会明显偏高。

第三个是输入归一化的参数不统一。训练时用了 ImageNet 的 mean/std，推理时忘了做，或者反过来；又或者训练时归一化用的是img/255，推理时用了(img-128)/128。这种错误不会有任何报错，只会让结果悄悄变差。我的做法是把预处理逻辑写成一个函数，训练和推理都调它，从源头上消除分歧。

还有一个容易忽略的点是设备一致性。加载权重时用torch.load(path, map_location="cpu")再手动搬到目标设备上，比让 PyTorch 按保存时的设备直接加载更稳，尤其是你在 GPU 机器上训练、在笔记本上演示的情况。

6.2 显存、批量大小和输入尺寸的三角关系

显存不够是训练阶段最常见的报错。这三者的关系大致是：显存占用和 batch size 成正比，和输入边长大致成平方关系。把输入从 512 降到 256，显存占用能降到大约四分之一，这是比调 batch size 更有效的杠杆。

但输入尺寸不能无脑降。超声图像里小病灶可能只有几十个像素，降到 256 之后可能只剩十几个像素，分割网络基本学不出来。所以尺寸的确定流程应该是：先看数据集中最小病灶的尺寸，估算它在目标输入尺寸下还剩多少像素，确保不少于 10 到 15 个像素，再据此定输入大小。

如果显存实在不够，还有两个手段：混合精度训练和梯度累积。梯度累积是模拟大 batch 的效果，跑 4 个小 batch 累积一次梯度再更新，显存占用是单个小 batch 的量级，代价是训练慢一点。实现上就几行：

accum_steps = 4 for i, (imgs, masks) in enumerate(loader): imgs, masks = imgs.to(device), masks.to(device) logits = model(imgs) loss = criterion(logits, masks) / accum_steps loss.backward() if (i + 1) % accum_steps == 0: torch.nn.utils.clip_grad_norm_(model.parameters(), 1.0) optimizer.step() optimizer.zero_grad()

注意 loss 要除以累积步数，否则梯度会等比放大，学习率相当于被乘以了 4。

6.3 PyInstaller 打包与资源路径

把程序交给别人用的时候，对方大概率没有 Python 环境和那一堆依赖，打包成可执行文件是最省事的方式。PyInstaller 用起来简单，但有几个坑。

权重文件和配置文件不会自动被打进去，需要用--add-data显式声明。更麻烦的是，打包之后程序的运行目录会变，用相对路径读文件会找不到。解决办法是运行时动态判断：

import sys from pathlib import Path def resource_path(rel: str) -> Path: if hasattr(sys, "_MEIPASS"): base = Path(sys._MEIPASS) # 打包后的临时解压目录 else: base = Path(__file__).resolve().parent return base / rel weights = resource_path("weights/unet_best.pth")

体积问题也常见。PyTorch 相关的一堆动态库加上去，包体很容易到一两个 G。用虚拟环境从零装依赖再打包，能省掉不少无关的包；CUDA 版的 PyTorch 体积尤其大，如果你的演示机没有 GPU，直接装 CPU 版本打包，体积能小一大截。

最后是首次启动慢的问题。打包后的程序第一次运行要把内容解压到临时目录，可能等十几秒才出窗口，用户会以为没启动又点一次。可以在打包配置里关闭控制台，或者干脆加个启动画面提示正在加载。加模型预热也有帮助——程序启动时先跑一次空输入的前向，把第一次推理的初始化开销提前吃掉，之后的交互就顺滑了。

最后分享一个我实际用下来很值的小习惯：每次训练完，把配置、指标和一张典型样本的可视化图一起存进runs/时间戳/目录里。这个项目在调试阶段会反复改参数、换骨干网络，跑十几组实验之后你一定会忘记哪组对应哪份权重。有了这个记录，回看对比时省下的时间远超写这几行保存代码的成本。