简介面向深度学习与图像识别方向的学习者压缩包提供一套完整的舌苔识别检测系统项目适合毕业设计、课程实践或中医舌诊数字化研究。源码基于Python实现包含PyQt5图形界面、已训练好的模型权重及配套毕业论文完整覆盖数据标注、图像增强、DCGAN扩充样本、卷积神经网络训练、舌苔分类与体质辨识等关键流程并与论文中的需求分析、网络设计相互对应。开发者可从中学习深度模型在医学图像分类中的落地方法也可直接运行界面完成舌苔图像检测演示。包内共110个文件主要涉及Python源码、PyQt5界面文件、模型权重.pth、论文文档.docx以及舌象图像样本.jpg整体约104.93MB目录清晰便于按模块查阅。该压缩包在CSDN已有536人学习下载对于准备相关课题的本科生与研究者而言能够提供从数据准备到系统实现的一手参考亦可作为二次开发和功能扩展的基础。1. 舌苔识别检测系统从模型到界面的完整落地舌苔识别这个方向属于典型的计算机视觉与中医诊断交叉场景。做出来的系统不是摆个实验室 Demo而是要同时解决三件事舌象图片里“舌体在哪、苔色苔质怎么量化、结论怎么让医生看得懂”。这套基于深度学习的舌苔识别检测系统最大的价值在于把过去凭经验的“看舌象”转成了可复现的算法流程。无论你是想快速出一套毕设级完整系统还是作为中医信息化产品的视觉前端这套方案都能直接作为起点。对于刚接触视觉项目的开发者它能帮你把数据集构建、模型训练、界面封装这条链路一次走通对于已经在做辅助诊断系统的团队它的价值集中体现在“轻量模型 桌面端交互”这种务实组合上。系统在技术选型上走的是成熟路径检测模型负责定位舌体分类模型负责辨识苔色与苔质PyQt5 界面把模型输出变成可视化的诊断报告。我不止一次见过同学把模型训练得很好最后却卡在界面集成上所以这篇笔记会带着你把每一步跑通。文章里我会用模拟项目X的经验来讲解部署和调试中的思路很多细节是跑完一遍流程才会注意到的。2. 舌象数据与预处理模型效果的上限由这里决定2.1 舌象数据集的特点光照与舌体分割是绕不开的两个坎舌苔识别模型的训练数据来源大多是从医院采集的舌象照片和公开的中医舌诊图谱。数据有几个显著特点首先舌体在整张图中的占比差异很大有的图片舌头几乎充满画面有的则带有嘴唇、牙齿甚至面部皮肤其次不同采集设备拍出的色彩还原度不一样手机、单反、医用舌象仪之间有明显差异第三光照条件是最大的干扰项冷白光和暖黄光下的同一舌象色差肉眼可见。从这些特点能推出一个关键结论训练之前不做舌体检测的模型几乎不可能稳定工作。因为分类网络对全局特征敏感背景比例一大注意力就被分散了。所以常见做法是两步走先用目标检测模型把舌头从原图中框出来再做裁剪和透视校正最后才进入分类网络。这种做法对最终识别效果提升明显也是这套系统把检测和分类分成两个环节的原因。2.2 舌体检测标注用 LabelImg 完成矩形框标注的实操标注工具我一般推荐 LabelImg它足够简单输出 Pascal VOC 格式的 XML 文件后续转成模型训练格式也方便。安装方式不再赘述直接说标注时的操作规范。# 创建标注环境并启动 LabelImg conda create -n labelimg python3.9 -y conda activate labelimg pip install labelimg labelimg # 启动后打开图片目录设置保存目录为 XML标注时有一个操作细节值得注意左侧工具栏要提前选成 PascalVOC 模式这样保存的才是 XML 而不是 YOLO 的 txt。标注过程中每个图片只需要框出舌体区域类名统一命名为 tongue。框的范围建议贴着舌缘轮廓走不要包含嘴唇和下唇阴影这部分语义噪声会让检测框忽大忽小。2.3 VOC 转 YOLO 格式脚本转换与坐标归一化边界坑检测模型的数据格式我推荐转成 YOLO 格式的 txt因为后续训练脚本和推理脚本都按这个格式读取坐标。转换的核心是把 XML 里的绝对坐标除以图片宽高得到 0 到 1 之间的归一化中心点坐标和宽高值。import os import xml.etree.ElementTree as ET def convert_voc_to_yolo(xml_path, out_dir, class_names): tree ET.parse(xml_path) root tree.getroot() img_w int(root.find(size).find(width).text) img_h int(root.find(size).find(height).text) out_lines [] for obj in root.iter(object): name obj.find(name).text if name not in class_names: continue cls_id class_names.index(name) box obj.find(bndbox) x1, y1, x2, y2 [float(box.find(v).text) for v in [xmin, ymin, xmax, ymax]] x1 max(0, min(x1, img_w - 1)) y1 max(0, min(y1, img_h - 1)) x2 max(0, min(x2, img_w - 1)) y2 max(0, min(y2, img_h - 1)) if x2 x1 or y2 y1: continue # 无效框直接跳过 x_c (x1 x2) / 2.0 / img_w y_c (y1 y2) / 2.0 / img_h w (x2 - x1) / img_w h (y2 - y1) / img_h out_lines.append(f{cls_id} {x_c:.6f} {y_c:.6f} {w:.6f} {h:.6f}) if out_lines: with open(os.path.join(out_dir, os.path.splitext(os.path.basename(xml_path))[0] .txt), w) as f: f.write(\n.join(out_lines)) class_names [tongue] # 遍历所有 XML 调用 convert_voc_to_yolo(xml_path, labels, class_names)脚本里有几个边界要注意坐标裁剪那一步不能省略否则个别标注框越界会让训练 loss 直接变成 NaN过滤 x2x1 这种无效框能避免训练时读取空标注导致数据加载中断类名索引从 0 开始类别多时错一位就会全错。转换完成后把 txt 文件和原图按 YOLO 惯例放到 images 和 labels 两个目录下训练脚本会按路径对应去读。2.4 苔色与苔质分类数据的组织目录结构就是标签分类数据集的组织方式简单直接的做法是用文件夹名当标签。建议按“苔色 苔质”分别建目录因为两者在临床上关注维度不同合并成单一标签会放大类间混淆。dataset_classify/ ├── train/ │ ├── bai_ni # 白苔腻 │ ├── bai_bo # 白苔薄 │ ├── huang_ni # 黄苔腻 │ ├── huang_bo # 黄苔薄 │ └── ... └── val/ ├── bai_ni └── ...这种目录结构用 torchvision 的 ImageFolder 接口可以直接加载不需要写自定义 Dataset。分类标签的命名建议用拼音或英文缩写中文字段名在 Windows 环境容易出现编码问题这一点尤其要注意。数据集规模建议每类不少于 500 张类别不平衡严重时用加权采样具体做法后面讲训练时再展开。3. 模型选型与训练检测、分类两条线并行推进3.1 检测模型选择轻量级 YOLO 系列更适合桌面端部署舌体检测这个任务本身不复杂——画面里通常只有一到两个目标类别只有一类难点主要在尺度变化和边缘模糊。这种任务用 YOLOv5s 或 YOLOv8s 这类轻量版本就足够参数量适中CPU 上也能勉强推理GPU 上实时性很好。盲目上 YOLOv5x 这种大模型对舌体检测没有额外收益反而让推理时间成倍增长。# tongue.yaml train: dataset_detect/images/train val: dataset_detect/images/val nc: 1 names: [tongue]训练命令相对固定需要关注的参数主要是图片尺寸和批次大小。舌体检测对分辨率不算敏感640 的输入尺寸可以满足要求批次大小根据显存调整6GB 显存跑 16 没问题不够就降到 8损失一点点收敛速度但不会报 OOM。模型收敛后 mAP0.5 通常能到 0.95 以上毕竟目标单一且特征显著。3.2 分类模型选型ResNet 与 EfficientNet 的实际对比苔色苔质分类对颜色纹理细节比较敏感网络不能太浅。实践中用得多的有两个方向ResNet50 属于稳妥之选收敛稳定参数适中EfficientNet-B0 在同样精度下参数量更小但训练时需要更强的数据增强配合否则容易欠拟合。mobileViT 这类轻量级网络我也试过精度相比 ResNet 略有下降故在 CPU 部署场景有限的情况下还是优先推荐 ResNet。import torch.nn as nn from torchvision.models import resnet50 def build_classifier(num_classes, pretrainedTrue): model resnet50(weightsIMAGENET1K_V1 if pretrained else None) in_features model.fc.in_features model.fc nn.Sequential( nn.Dropout(0.3), nn.Linear(in_features, 256), nn.ReLU(inplaceTrue), nn.Dropout(0.2), nn.Linear(256, num_classes) ) return model替换全连接层时要注意保持 in_features 的一致性做法是先从原模型读出来再构建新层不要写死 2048否则换网络结构就要连带改。Dropout 加在分类头里能在一定程度上抑制过拟合因为舌象数据类内差异较大模型很容易死记训练集的纹理细节。3.3 训练配置与数据增强参数怎么设才不玄学训练分类网络时数据增强策略和训练超参是决定效果的关键因素。舌象图片的增强和自然图像不同常规的随机裁剪缩放固然有用但更要重视的是色彩抖动因为颜色是苔色分类的直接依据但也需要注意避免过度偏离真实舌色。import torch from torchvision import transforms from torch.utils.data import DataLoader from torchvision.datasets import ImageFolder train_transform transforms.Compose([ transforms.RandomResizedCrop(224, scale(0.7, 1.0)), transforms.RandomHorizontalFlip(p0.5), transforms.ColorJitter(brightness0.3, contrast0.3, saturation0.2, hue0.05), transforms.ToTensor(), transforms.Normalize(mean[0.485, 0.456, 0.406], std[0.229, 0.224, 0.225]) ]) dataset ImageFolder(dataset_classify/train, transformtrain_transform) loader DataLoader(dataset, batch_size32, shuffleTrue, num_workers4, pin_memoryTrue)训练参数方面常见做法是 SG 优化器配合阶梯式学习率初始学习率设置在 0.001 到 0.01 之间具体数值要看数据集规模和任务难度epoch 设置 50 到 100 轮用验证集 loss 保存最优权重。损失函数用带权重的 CrossEntropyLoss类别样本数差异大时一定要启用权重参数否则样本量大的类别会主导梯度更新。from torch.nn import CrossEntropyLoss class_weights torch.tensor([1.0, 1.2, 1.5, 0.8, 1.3]) # 按各类样本占比的倒数平滑 criterion CrossEntropyLoss(weightclass_weights)一个容易被忽略的参数是验证集变换验证时只能用 Resize CenterCrop不能加 Random 系列增强否则指标会有波动。4. PyQt5 界面集成把模型输出变成可操作的报告4.1 界面整体结构与线程设计PyQt5 界面在这套系统中的职责是选择图片、展示原图与检测结果、触发分类推理并显示诊断结论。界面布局我采用左侧原图预览、右侧结果面板的两栏结构底部放一个“开始识别”按钮和日志输出框。整体设计类似一个检测工具类的软件但核心目标很清晰——让操作者不用接触代码就能完成整套识别流程。界面开发最需要避开的坑是耗时操作阻塞主线程。PyTorch 的 GPU 推理虽然快但在 CPU 上跑一次完整流程可能需要几百毫秒如果直接写在按钮的槽函数里界面会卡住不动。正确做法是利用 QThread 把推理放到后台线程主线程只负责更新 UI。from PyQt5.QtCore import QThread, pyqtSignal class InferThread(QThread): finished pyqtSignal(dict) def __init__(self, image_path, detect_model, classify_model, device): super().__init__() self.image_path image_path self.detect_model detect_model self.classify_model classify_model self.device device def run(self): result run_pipeline(self.image_path, self.detect_model, self.classify_model, self.device) self.finished.emit(result)这种设计需要注意的细节是线程里不要再访问 UI 控件只通过信号传递结果如果用户连续点击按钮要设置 busy 标志位防止重复启动线程。4.2 torch.load 的坑直接加载模型文件为什么会炸模型加载是集成阶段的高频翻车点。PyTorch 的 state_dict 保存方式有两种只保存权重的 .pth 文件和包含完整模型结构的 .pt 文件两者加载方式完全不同界面启动时加载不对就会报错。import torch from models.resnet import build_classifier device torch.device(cuda if torch.cuda.is_available() else cpu) # 情况一只有 state_dict必须先构建模型再 load model build_classifier(num_classes5) model.load_state_dict(torch.load(classify_best.pth, map_locationdevice)) model.to(device).eval() # 情况二完整模型文件直接加载即可 model torch.load(classify_best.pt, map_locationdevice) model.to(device).eval()很多同学在训练脚本里用的是 model.state_dict() 保存到了界面端却按完整模型去 load就会出现 missing keys 或 unexpected keys 的报错。建议在保存模型时把优化器状态、epoch、best_acc 一起打包成字典这样后面做断点续训加载时能省很多事。加载前打印一遍 model.keys() 花不了几秒钟却能避免后续排查的大半天时间。4.3 推理管线编排从原图到报告的一体化实现完整的识别流程是先用检测模型定位舌头裁剪出舌体区域后再送入分类模型。这里需要注意两个细节检测框要适度外扩不能贴着框边缘裁剪以免丢失舌缘信息如果检测置信度低于某个阈值界面应该给出提示让用户重新拍摄而不是硬分类。import cv2 import torch import numpy as np def run_pipeline(image_path, detect_model, classify_model, device, conf_thres0.5, expand_ratio0.1): img cv2.imread(image_path) img_rgb cv2.cvtColor(img, cv2.COLOR_BGR2RGB) results detect_model(img_rgb) if len(results.boxes) 0: return {error: 未检测到舌体请调整拍摄角度或光线后重试} box results.boxes[0].xyxy[0].cpu().numpy().astype(int) conf results.boxes[0].conf[0].item() if conf conf_thres: return {error: f舌体检测置信度偏低({conf:.2f})建议重新拍摄} x1, y1, x2, y2 box dw, dh int((x2 - x1) * expand_ratio), int((y2 - y1) * expand_ratio) h, w img.shape[:2] x1, y1 max(0, x1 - dw), max(0, y1 - dh) x2, y2 min(w, x2 dw), min(h, y2 dh) crop img_rgb[y1:y2, x1:x2] crop cv2.resize(crop, (224, 224)) crop_tensor torch.from_numpy(crop.transpose(2, 0, 1)).float().div(255) crop_tensor crop_tensor.unsqueeze(0).to(device) with torch.no_grad(): logits classify_model(crop_tensor) prob torch.softmax(logits, dim1) idx torch.argmax(prob, dim1).item() conf prob[0, idx].item() return {box: box.tolist(), class_id: idx, class_name: class_names[idx], confidence: conf}推理管线里几个关键参数值得留意expand_ratio 外扩比例取 0.1 比较合适外扩太多会把嘴唇和背景纳入分类区域干扰苔色判断分类模型的输入尺寸要和训练时一致否则预处理统计量不匹配会带来精度下降softmax 后的置信度是给界面展示用的而训练时用的 CrossEntropyLoss 自带 softmax两者不要弄混。4.4 界面结果展示与状态管理结果展示部分需要同时呈现检测框图片、苔质苔色结论、置信度三个信息。检测框的绘制在 QPixmap 上同步进行不能只画在原始图像矩阵里因为界面显示的图片经过了缩放适配。建议绘制时把检测框坐标按缩放比例映射回显示坐标系才能让框和舌头位置准确对应。def update_result(self, result_dict): if error in result_dict: self.result_label.setText(result_dict[error]) return box result_dict[box] self.result_label.setText( f舌苔类型{result_dict[class_name]}\n f置信度{result_dict[confidence]:.2%} ) self.draw_box(box)状态管理方面要注意按钮的可用状态切换推理中禁用按钮避免重复点击、等待检测结果时清空旧结果、遇到错误时恢复按钮可用状态。这些看似琐碎的细节往往比模型调参更影响实际使用体验。5. 部署与模型压缩让系统在 CPU 上也能有可用体验5.1 模型格式转换与推理框架选型纯 PyTorch 的加载推理方式在 GPU 环境下表现良好但若目标是普通办公电脑 CPU 部署那么换成 ONNX Runtime 或者 OpenVINO 会有明显效果提升——同样的模型转换后推理耗时往往能下降到原始版本的一半甚至更少。import torch # 以分类模型为例导出 ONNX model build_classifier(num_classes5) model.load_state_dict(torch.load(classify_best.pth, map_locationcpu)) model.eval() dummy_input torch.randn(1, 3, 224, 224) torch.onnx.export( model, dummy_input, classify.onnx, input_names[input], output_names[output], dynamic_axes{input: {0: batch}, output: {0: batch}}, opset_version12 )导出 ONNX 时有两个细节dynamic_axes 让 batch 维度可变这样推理时可以传单张也可以传多张opset_version 不宜过高旧版 ONNX Runtime 对高版本算子支持不完整实际运行会报 unsupported operator 错误。5.2 推理函数的替换ONNX Runtime 接口与 PyTorch 的差异换用 ONNX Runtime 后推理函数的写法完全不同尤其要注意输入数据的格式和维度顺序。PyTorch 模型直接接收 tensor而 ONNX Runtime 需要 numpy 数组并且要指定输入输出节点名称。import onnxruntime as ort import numpy as np class OnnxClassifier: def __init__(self, onnx_path, device_index0): providers [CUDAExecutionProvider, CPUExecutionProvider] if device_index 0 else [CPUExecutionProvider] self.session ort.InferenceSession(onnx_path, providersproviders) self.input_name self.session.get_inputs()[0].name self.output_name self.session.get_outputs()[0].name def predict(self, tensor_np): # tensor_np: (1, 3, 224, 224) float32 numpy outs self.session.run([self.output_name], {self.input_name: tensor_np}) return outs[0]大多数 ONNX 部署的报错集中在 provider 指定上。CUDAExecutionProvider 前置的情况下如果当前机器没有 GPU 或 CUDA 库不匹配初始化会报错。稳妥的做法是先尝试全部 provider失败就回退到 CPU。5.3 量化INT8 对舌苔识别精度的影响有多大想要进一步压缩模型体积可以考虑 INT8 量化。PyTorch 的量化分为训练后动态量化和静态量化。对分类模型来说静态量化通常能把模型体积缩小到约四分之一推理速度提升 1.5 到 2 倍但精度损失需要实测确定——舌苔分类对颜色和纹理细节比较敏感量化后掉点可能比自然图像分类更明显。model_fp32 build_classifier(num_classes5) model_fp32.load_state_dict(torch.load(classify_best.pth, map_locationcpu)) model_fp32.eval() model_quantized torch.quantization.quantize_dynamic( model_fp32, {torch.nn.Linear}, dtypetorch.qint8 ) torch.save(model_quantized.state_dict(), classify_quantized.pth)一个实操建议在已经完成系统开发和部署之后量化优化可以作为后续版本迭代的一部分来推进。第一版先用 FP32 跑通全流程确认检测和分类的准确率达标后再做量化压缩。如果量化后精度下降明显退回 FP32 成本并不高留一条后悔药路径总归是好的。6. 常见问题排查与避坑指南6.1 检测模型在验证集效果很好但界面上框不住舌头这个翻车现象出现频率很高。模型独测时 mAP 很高但到实际使用时对不上甚至框偏到嘴唇上。原因通常有两个第一训练数据里全是规范的正角度舌象照片而实际使用时用户拍的图可能是仰角、侧面或者舌头没有完全伸出的状态这属于典型的数据分布不一致第二界面端推理时缩放的尺寸和训练不一致YOLO 模型对输入分辨率有一定要求如果被界面代码随意 resize检测效果会退化严重。解决思路要有两手准备。一是数据层面增加多角度、多光照的样本模拟用户真实拍摄场景二是推理端严格保持训练时的预处理流程把 resize 逻辑直接复用训练代码里的预处理函数不要在界面端重新写一遍。6.2 分类模型对黄苔、白苔的判断总是摇摆不定苔色分类的理想入参是颜色还原度较高的图像。如果图片整体偏黄或者偏白分类器就会不稳定同一张舌象在不同显示器上可能得到不同结论。产生这个问题的根源在于训练数据里的色调多样性和实际使用环境的漂移不一致。解决思路包括加强 ColorJitter 增强让模型见过更宽的色域在界面端增加白平衡校正选项让用户手动调整后再识别输出 Top2 概率而不是只给最高类别当两个类别概率接近时提示“黄白苔界限模糊建议结合临床诊断”。这类提示看似简单但对实际医疗场景的价值远大于盲目输出一个不确定的结论。6.3 界面启动后无响应或直接闪退PyQt5 界面闪退通常有几个原因模型路径不存在但代码没有判断、ONNX Runtime DLL 加载失败、设备号超出范围。排查时先在纯命令行环境加载模型不要直接启动界面python -c import torch; mtorch.load(classify_best.pt, map_locationcpu); print(model ok) python -c import onnxruntime as ort; sort.InferenceSession(classify.onnx, providers[CPUExecutionProvider]); print(onnx ok)如果这两步都通过再去检查界面代码。QThread 里抛出的异常默认不会导致进程崩溃但会在 Qt 事件循环里留下未捕获异常。建议在 run() 方法里包一层 try-except把异常信息通过信号传回主界面显示。class InferThread(QThread): finished pyqtSignal(dict) error pyqtSignal(str) def run(self): try: result run_pipeline(self.image_path, self.detect_model, self.classify_model, self.device) self.finished.emit(result) except Exception as e: self.error.emit(str(e))异常信息在日志框打印出来而不是让程序直接崩溃这种习惯做项目时能节约大量时间。6.4 模型加载在 Windows 下路径报错Windows 下使用中文路径或包含中文名的模型文件时PyTorch 和 OpenCV 偶尔会出现编码问题。这需要从根源上避免使用中文路径和中文文件名统一用英文。另外模型文件放在项目根目录的 models/ 文件夹里不要放在桌面或下载目录既方便打包也避免权限问题。6.5 训练时 loss 不降或直接变成 NaNloss 变成 NaN 的原因多半是学习率过大、数据里有异常像素值或者标注越界。检测模型训练时重点检查标注坐标是否全部归一化到 [0,1] 区间分类模型训练时检查输入图片是否有损坏文件。更直接的办法是降低初始学习率从 0.001 开始确认 loss 正常下降后再逐步加大。7. 系统验证与扩展如何确认模型真的可靠这套系统做完之后验证是必不可少的一步。舌苔识别系统的验证不同于普通分类任务不能只盯着准确率还要关注临床可用性。我通常的做法是准备一份留出测试集里面全部是训练阶段没有见过的真实场景图片包括不同光照、不同设备、不同角度然后统计检测成功率和分类混淆矩阵。import numpy as np from sklearn.metrics import confusion_matrix, classification_report def evaluate(model, loader, device): model.eval() all_preds, all_labels [], [] with torch.no_grad(): for images, labels in loader: images, labels images.to(device), labels.to(device) outputs model(images) _, preds torch.max(outputs, 1) all_preds.extend(preds.cpu().numpy()) all_labels.extend(labels.cpu().numpy()) cm confusion_matrix(all_labels, all_preds) print(classification_report(all_labels, all_preds, target_namesclass_names)) return cm从混淆矩阵里能看到的不只是准确率还有具体哪些类别互相混淆。黄苔和白苔之间的混淆是常见问题但这代表的是标注标准模糊不是模型缺陷。这时候要做的是回看标注数据确认标注人员之间对“黄”和“白”的颜色界定是否一致必要时重新清洗部分标签。扩展方向上值得做的改造有把检测框的输出从矩形框升级为舌体轮廓分割 mask用 U-Net 做舌体分割能拿到更精确的舌体区域分类输入质量比矩形裁剪好不少把分类网络改成多标签输出——一个舌头可以同时有“薄”和“白”的属性多标签结构更接近临床语义在界面端增加批量识别功能一次导入数十张图片自动出报告对体检中心这种场景的实用价值明显。对整个系统做个评价的话需要清楚它只能提供辅助参考不能替代任何专业医疗判断。界面展示的置信度严格来说明确标注“AI 辅助结果”这在中医信息化项目中既是对规范的尊重也是对使用者的保护。这是这套系统开发过程中最重要的一条教训——技术指标再好也要想清楚使用边界。希望这篇踩坑笔记能帮到你搭建属于自己的舌象分析系统的时候少走一些弯路。本文还有配套的精品资源点击获取 舌苔识别检测系统：从模型训练到界面部署的完整实践
简介面向深度学习与图像识别方向的学习者压缩包提供一套完整的舌苔识别检测系统项目适合毕业设计、课程实践或中医舌诊数字化研究。源码基于Python实现包含PyQt5图形界面、已训练好的模型权重及配套毕业论文完整覆盖数据标注、图像增强、DCGAN扩充样本、卷积神经网络训练、舌苔分类与体质辨识等关键流程并与论文中的需求分析、网络设计相互对应。开发者可从中学习深度模型在医学图像分类中的落地方法也可直接运行界面完成舌苔图像检测演示。包内共110个文件主要涉及Python源码、PyQt5界面文件、模型权重.pth、论文文档.docx以及舌象图像样本.jpg整体约104.93MB目录清晰便于按模块查阅。该压缩包在CSDN已有536人学习下载对于准备相关课题的本科生与研究者而言能够提供从数据准备到系统实现的一手参考亦可作为二次开发和功能扩展的基础。1. 舌苔识别检测系统从模型到界面的完整落地舌苔识别这个方向属于典型的计算机视觉与中医诊断交叉场景。做出来的系统不是摆个实验室 Demo而是要同时解决三件事舌象图片里“舌体在哪、苔色苔质怎么量化、结论怎么让医生看得懂”。这套基于深度学习的舌苔识别检测系统最大的价值在于把过去凭经验的“看舌象”转成了可复现的算法流程。无论你是想快速出一套毕设级完整系统还是作为中医信息化产品的视觉前端这套方案都能直接作为起点。对于刚接触视觉项目的开发者它能帮你把数据集构建、模型训练、界面封装这条链路一次走通对于已经在做辅助诊断系统的团队它的价值集中体现在“轻量模型 桌面端交互”这种务实组合上。系统在技术选型上走的是成熟路径检测模型负责定位舌体分类模型负责辨识苔色与苔质PyQt5 界面把模型输出变成可视化的诊断报告。我不止一次见过同学把模型训练得很好最后却卡在界面集成上所以这篇笔记会带着你把每一步跑通。文章里我会用模拟项目X的经验来讲解部署和调试中的思路很多细节是跑完一遍流程才会注意到的。2. 舌象数据与预处理模型效果的上限由这里决定2.1 舌象数据集的特点光照与舌体分割是绕不开的两个坎舌苔识别模型的训练数据来源大多是从医院采集的舌象照片和公开的中医舌诊图谱。数据有几个显著特点首先舌体在整张图中的占比差异很大有的图片舌头几乎充满画面有的则带有嘴唇、牙齿甚至面部皮肤其次不同采集设备拍出的色彩还原度不一样手机、单反、医用舌象仪之间有明显差异第三光照条件是最大的干扰项冷白光和暖黄光下的同一舌象色差肉眼可见。从这些特点能推出一个关键结论训练之前不做舌体检测的模型几乎不可能稳定工作。因为分类网络对全局特征敏感背景比例一大注意力就被分散了。所以常见做法是两步走先用目标检测模型把舌头从原图中框出来再做裁剪和透视校正最后才进入分类网络。这种做法对最终识别效果提升明显也是这套系统把检测和分类分成两个环节的原因。2.2 舌体检测标注用 LabelImg 完成矩形框标注的实操标注工具我一般推荐 LabelImg它足够简单输出 Pascal VOC 格式的 XML 文件后续转成模型训练格式也方便。安装方式不再赘述直接说标注时的操作规范。# 创建标注环境并启动 LabelImg conda create -n labelimg python3.9 -y conda activate labelimg pip install labelimg labelimg # 启动后打开图片目录设置保存目录为 XML标注时有一个操作细节值得注意左侧工具栏要提前选成 PascalVOC 模式这样保存的才是 XML 而不是 YOLO 的 txt。标注过程中每个图片只需要框出舌体区域类名统一命名为 tongue。框的范围建议贴着舌缘轮廓走不要包含嘴唇和下唇阴影这部分语义噪声会让检测框忽大忽小。2.3 VOC 转 YOLO 格式脚本转换与坐标归一化边界坑检测模型的数据格式我推荐转成 YOLO 格式的 txt因为后续训练脚本和推理脚本都按这个格式读取坐标。转换的核心是把 XML 里的绝对坐标除以图片宽高得到 0 到 1 之间的归一化中心点坐标和宽高值。import os import xml.etree.ElementTree as ET def convert_voc_to_yolo(xml_path, out_dir, class_names): tree ET.parse(xml_path) root tree.getroot() img_w int(root.find(size).find(width).text) img_h int(root.find(size).find(height).text) out_lines [] for obj in root.iter(object): name obj.find(name).text if name not in class_names: continue cls_id class_names.index(name) box obj.find(bndbox) x1, y1, x2, y2 [float(box.find(v).text) for v in [xmin, ymin, xmax, ymax]] x1 max(0, min(x1, img_w - 1)) y1 max(0, min(y1, img_h - 1)) x2 max(0, min(x2, img_w - 1)) y2 max(0, min(y2, img_h - 1)) if x2 x1 or y2 y1: continue # 无效框直接跳过 x_c (x1 x2) / 2.0 / img_w y_c (y1 y2) / 2.0 / img_h w (x2 - x1) / img_w h (y2 - y1) / img_h out_lines.append(f{cls_id} {x_c:.6f} {y_c:.6f} {w:.6f} {h:.6f}) if out_lines: with open(os.path.join(out_dir, os.path.splitext(os.path.basename(xml_path))[0] .txt), w) as f: f.write(\n.join(out_lines)) class_names [tongue] # 遍历所有 XML 调用 convert_voc_to_yolo(xml_path, labels, class_names)脚本里有几个边界要注意坐标裁剪那一步不能省略否则个别标注框越界会让训练 loss 直接变成 NaN过滤 x2x1 这种无效框能避免训练时读取空标注导致数据加载中断类名索引从 0 开始类别多时错一位就会全错。转换完成后把 txt 文件和原图按 YOLO 惯例放到 images 和 labels 两个目录下训练脚本会按路径对应去读。2.4 苔色与苔质分类数据的组织目录结构就是标签分类数据集的组织方式简单直接的做法是用文件夹名当标签。建议按“苔色 苔质”分别建目录因为两者在临床上关注维度不同合并成单一标签会放大类间混淆。dataset_classify/ ├── train/ │ ├── bai_ni # 白苔腻 │ ├── bai_bo # 白苔薄 │ ├── huang_ni # 黄苔腻 │ ├── huang_bo # 黄苔薄 │ └── ... └── val/ ├── bai_ni └── ...这种目录结构用 torchvision 的 ImageFolder 接口可以直接加载不需要写自定义 Dataset。分类标签的命名建议用拼音或英文缩写中文字段名在 Windows 环境容易出现编码问题这一点尤其要注意。数据集规模建议每类不少于 500 张类别不平衡严重时用加权采样具体做法后面讲训练时再展开。3. 模型选型与训练检测、分类两条线并行推进3.1 检测模型选择轻量级 YOLO 系列更适合桌面端部署舌体检测这个任务本身不复杂——画面里通常只有一到两个目标类别只有一类难点主要在尺度变化和边缘模糊。这种任务用 YOLOv5s 或 YOLOv8s 这类轻量版本就足够参数量适中CPU 上也能勉强推理GPU 上实时性很好。盲目上 YOLOv5x 这种大模型对舌体检测没有额外收益反而让推理时间成倍增长。# tongue.yaml train: dataset_detect/images/train val: dataset_detect/images/val nc: 1 names: [tongue]训练命令相对固定需要关注的参数主要是图片尺寸和批次大小。舌体检测对分辨率不算敏感640 的输入尺寸可以满足要求批次大小根据显存调整6GB 显存跑 16 没问题不够就降到 8损失一点点收敛速度但不会报 OOM。模型收敛后 mAP0.5 通常能到 0.95 以上毕竟目标单一且特征显著。3.2 分类模型选型ResNet 与 EfficientNet 的实际对比苔色苔质分类对颜色纹理细节比较敏感网络不能太浅。实践中用得多的有两个方向ResNet50 属于稳妥之选收敛稳定参数适中EfficientNet-B0 在同样精度下参数量更小但训练时需要更强的数据增强配合否则容易欠拟合。mobileViT 这类轻量级网络我也试过精度相比 ResNet 略有下降故在 CPU 部署场景有限的情况下还是优先推荐 ResNet。import torch.nn as nn from torchvision.models import resnet50 def build_classifier(num_classes, pretrainedTrue): model resnet50(weightsIMAGENET1K_V1 if pretrained else None) in_features model.fc.in_features model.fc nn.Sequential( nn.Dropout(0.3), nn.Linear(in_features, 256), nn.ReLU(inplaceTrue), nn.Dropout(0.2), nn.Linear(256, num_classes) ) return model替换全连接层时要注意保持 in_features 的一致性做法是先从原模型读出来再构建新层不要写死 2048否则换网络结构就要连带改。Dropout 加在分类头里能在一定程度上抑制过拟合因为舌象数据类内差异较大模型很容易死记训练集的纹理细节。3.3 训练配置与数据增强参数怎么设才不玄学训练分类网络时数据增强策略和训练超参是决定效果的关键因素。舌象图片的增强和自然图像不同常规的随机裁剪缩放固然有用但更要重视的是色彩抖动因为颜色是苔色分类的直接依据但也需要注意避免过度偏离真实舌色。import torch from torchvision import transforms from torch.utils.data import DataLoader from torchvision.datasets import ImageFolder train_transform transforms.Compose([ transforms.RandomResizedCrop(224, scale(0.7, 1.0)), transforms.RandomHorizontalFlip(p0.5), transforms.ColorJitter(brightness0.3, contrast0.3, saturation0.2, hue0.05), transforms.ToTensor(), transforms.Normalize(mean[0.485, 0.456, 0.406], std[0.229, 0.224, 0.225]) ]) dataset ImageFolder(dataset_classify/train, transformtrain_transform) loader DataLoader(dataset, batch_size32, shuffleTrue, num_workers4, pin_memoryTrue)训练参数方面常见做法是 SG 优化器配合阶梯式学习率初始学习率设置在 0.001 到 0.01 之间具体数值要看数据集规模和任务难度epoch 设置 50 到 100 轮用验证集 loss 保存最优权重。损失函数用带权重的 CrossEntropyLoss类别样本数差异大时一定要启用权重参数否则样本量大的类别会主导梯度更新。from torch.nn import CrossEntropyLoss class_weights torch.tensor([1.0, 1.2, 1.5, 0.8, 1.3]) # 按各类样本占比的倒数平滑 criterion CrossEntropyLoss(weightclass_weights)一个容易被忽略的参数是验证集变换验证时只能用 Resize CenterCrop不能加 Random 系列增强否则指标会有波动。4. PyQt5 界面集成把模型输出变成可操作的报告4.1 界面整体结构与线程设计PyQt5 界面在这套系统中的职责是选择图片、展示原图与检测结果、触发分类推理并显示诊断结论。界面布局我采用左侧原图预览、右侧结果面板的两栏结构底部放一个“开始识别”按钮和日志输出框。整体设计类似一个检测工具类的软件但核心目标很清晰——让操作者不用接触代码就能完成整套识别流程。界面开发最需要避开的坑是耗时操作阻塞主线程。PyTorch 的 GPU 推理虽然快但在 CPU 上跑一次完整流程可能需要几百毫秒如果直接写在按钮的槽函数里界面会卡住不动。正确做法是利用 QThread 把推理放到后台线程主线程只负责更新 UI。from PyQt5.QtCore import QThread, pyqtSignal class InferThread(QThread): finished pyqtSignal(dict) def __init__(self, image_path, detect_model, classify_model, device): super().__init__() self.image_path image_path self.detect_model detect_model self.classify_model classify_model self.device device def run(self): result run_pipeline(self.image_path, self.detect_model, self.classify_model, self.device) self.finished.emit(result)这种设计需要注意的细节是线程里不要再访问 UI 控件只通过信号传递结果如果用户连续点击按钮要设置 busy 标志位防止重复启动线程。4.2 torch.load 的坑直接加载模型文件为什么会炸模型加载是集成阶段的高频翻车点。PyTorch 的 state_dict 保存方式有两种只保存权重的 .pth 文件和包含完整模型结构的 .pt 文件两者加载方式完全不同界面启动时加载不对就会报错。import torch from models.resnet import build_classifier device torch.device(cuda if torch.cuda.is_available() else cpu) # 情况一只有 state_dict必须先构建模型再 load model build_classifier(num_classes5) model.load_state_dict(torch.load(classify_best.pth, map_locationdevice)) model.to(device).eval() # 情况二完整模型文件直接加载即可 model torch.load(classify_best.pt, map_locationdevice) model.to(device).eval()很多同学在训练脚本里用的是 model.state_dict() 保存到了界面端却按完整模型去 load就会出现 missing keys 或 unexpected keys 的报错。建议在保存模型时把优化器状态、epoch、best_acc 一起打包成字典这样后面做断点续训加载时能省很多事。加载前打印一遍 model.keys() 花不了几秒钟却能避免后续排查的大半天时间。4.3 推理管线编排从原图到报告的一体化实现完整的识别流程是先用检测模型定位舌头裁剪出舌体区域后再送入分类模型。这里需要注意两个细节检测框要适度外扩不能贴着框边缘裁剪以免丢失舌缘信息如果检测置信度低于某个阈值界面应该给出提示让用户重新拍摄而不是硬分类。import cv2 import torch import numpy as np def run_pipeline(image_path, detect_model, classify_model, device, conf_thres0.5, expand_ratio0.1): img cv2.imread(image_path) img_rgb cv2.cvtColor(img, cv2.COLOR_BGR2RGB) results detect_model(img_rgb) if len(results.boxes) 0: return {error: 未检测到舌体请调整拍摄角度或光线后重试} box results.boxes[0].xyxy[0].cpu().numpy().astype(int) conf results.boxes[0].conf[0].item() if conf conf_thres: return {error: f舌体检测置信度偏低({conf:.2f})建议重新拍摄} x1, y1, x2, y2 box dw, dh int((x2 - x1) * expand_ratio), int((y2 - y1) * expand_ratio) h, w img.shape[:2] x1, y1 max(0, x1 - dw), max(0, y1 - dh) x2, y2 min(w, x2 dw), min(h, y2 dh) crop img_rgb[y1:y2, x1:x2] crop cv2.resize(crop, (224, 224)) crop_tensor torch.from_numpy(crop.transpose(2, 0, 1)).float().div(255) crop_tensor crop_tensor.unsqueeze(0).to(device) with torch.no_grad(): logits classify_model(crop_tensor) prob torch.softmax(logits, dim1) idx torch.argmax(prob, dim1).item() conf prob[0, idx].item() return {box: box.tolist(), class_id: idx, class_name: class_names[idx], confidence: conf}推理管线里几个关键参数值得留意expand_ratio 外扩比例取 0.1 比较合适外扩太多会把嘴唇和背景纳入分类区域干扰苔色判断分类模型的输入尺寸要和训练时一致否则预处理统计量不匹配会带来精度下降softmax 后的置信度是给界面展示用的而训练时用的 CrossEntropyLoss 自带 softmax两者不要弄混。4.4 界面结果展示与状态管理结果展示部分需要同时呈现检测框图片、苔质苔色结论、置信度三个信息。检测框的绘制在 QPixmap 上同步进行不能只画在原始图像矩阵里因为界面显示的图片经过了缩放适配。建议绘制时把检测框坐标按缩放比例映射回显示坐标系才能让框和舌头位置准确对应。def update_result(self, result_dict): if error in result_dict: self.result_label.setText(result_dict[error]) return box result_dict[box] self.result_label.setText( f舌苔类型{result_dict[class_name]}\n f置信度{result_dict[confidence]:.2%} ) self.draw_box(box)状态管理方面要注意按钮的可用状态切换推理中禁用按钮避免重复点击、等待检测结果时清空旧结果、遇到错误时恢复按钮可用状态。这些看似琐碎的细节往往比模型调参更影响实际使用体验。5. 部署与模型压缩让系统在 CPU 上也能有可用体验5.1 模型格式转换与推理框架选型纯 PyTorch 的加载推理方式在 GPU 环境下表现良好但若目标是普通办公电脑 CPU 部署那么换成 ONNX Runtime 或者 OpenVINO 会有明显效果提升——同样的模型转换后推理耗时往往能下降到原始版本的一半甚至更少。import torch # 以分类模型为例导出 ONNX model build_classifier(num_classes5) model.load_state_dict(torch.load(classify_best.pth, map_locationcpu)) model.eval() dummy_input torch.randn(1, 3, 224, 224) torch.onnx.export( model, dummy_input, classify.onnx, input_names[input], output_names[output], dynamic_axes{input: {0: batch}, output: {0: batch}}, opset_version12 )导出 ONNX 时有两个细节dynamic_axes 让 batch 维度可变这样推理时可以传单张也可以传多张opset_version 不宜过高旧版 ONNX Runtime 对高版本算子支持不完整实际运行会报 unsupported operator 错误。5.2 推理函数的替换ONNX Runtime 接口与 PyTorch 的差异换用 ONNX Runtime 后推理函数的写法完全不同尤其要注意输入数据的格式和维度顺序。PyTorch 模型直接接收 tensor而 ONNX Runtime 需要 numpy 数组并且要指定输入输出节点名称。import onnxruntime as ort import numpy as np class OnnxClassifier: def __init__(self, onnx_path, device_index0): providers [CUDAExecutionProvider, CPUExecutionProvider] if device_index 0 else [CPUExecutionProvider] self.session ort.InferenceSession(onnx_path, providersproviders) self.input_name self.session.get_inputs()[0].name self.output_name self.session.get_outputs()[0].name def predict(self, tensor_np): # tensor_np: (1, 3, 224, 224) float32 numpy outs self.session.run([self.output_name], {self.input_name: tensor_np}) return outs[0]大多数 ONNX 部署的报错集中在 provider 指定上。CUDAExecutionProvider 前置的情况下如果当前机器没有 GPU 或 CUDA 库不匹配初始化会报错。稳妥的做法是先尝试全部 provider失败就回退到 CPU。5.3 量化INT8 对舌苔识别精度的影响有多大想要进一步压缩模型体积可以考虑 INT8 量化。PyTorch 的量化分为训练后动态量化和静态量化。对分类模型来说静态量化通常能把模型体积缩小到约四分之一推理速度提升 1.5 到 2 倍但精度损失需要实测确定——舌苔分类对颜色和纹理细节比较敏感量化后掉点可能比自然图像分类更明显。model_fp32 build_classifier(num_classes5) model_fp32.load_state_dict(torch.load(classify_best.pth, map_locationcpu)) model_fp32.eval() model_quantized torch.quantization.quantize_dynamic( model_fp32, {torch.nn.Linear}, dtypetorch.qint8 ) torch.save(model_quantized.state_dict(), classify_quantized.pth)一个实操建议在已经完成系统开发和部署之后量化优化可以作为后续版本迭代的一部分来推进。第一版先用 FP32 跑通全流程确认检测和分类的准确率达标后再做量化压缩。如果量化后精度下降明显退回 FP32 成本并不高留一条后悔药路径总归是好的。6. 常见问题排查与避坑指南6.1 检测模型在验证集效果很好但界面上框不住舌头这个翻车现象出现频率很高。模型独测时 mAP 很高但到实际使用时对不上甚至框偏到嘴唇上。原因通常有两个第一训练数据里全是规范的正角度舌象照片而实际使用时用户拍的图可能是仰角、侧面或者舌头没有完全伸出的状态这属于典型的数据分布不一致第二界面端推理时缩放的尺寸和训练不一致YOLO 模型对输入分辨率有一定要求如果被界面代码随意 resize检测效果会退化严重。解决思路要有两手准备。一是数据层面增加多角度、多光照的样本模拟用户真实拍摄场景二是推理端严格保持训练时的预处理流程把 resize 逻辑直接复用训练代码里的预处理函数不要在界面端重新写一遍。6.2 分类模型对黄苔、白苔的判断总是摇摆不定苔色分类的理想入参是颜色还原度较高的图像。如果图片整体偏黄或者偏白分类器就会不稳定同一张舌象在不同显示器上可能得到不同结论。产生这个问题的根源在于训练数据里的色调多样性和实际使用环境的漂移不一致。解决思路包括加强 ColorJitter 增强让模型见过更宽的色域在界面端增加白平衡校正选项让用户手动调整后再识别输出 Top2 概率而不是只给最高类别当两个类别概率接近时提示“黄白苔界限模糊建议结合临床诊断”。这类提示看似简单但对实际医疗场景的价值远大于盲目输出一个不确定的结论。6.3 界面启动后无响应或直接闪退PyQt5 界面闪退通常有几个原因模型路径不存在但代码没有判断、ONNX Runtime DLL 加载失败、设备号超出范围。排查时先在纯命令行环境加载模型不要直接启动界面python -c import torch; mtorch.load(classify_best.pt, map_locationcpu); print(model ok) python -c import onnxruntime as ort; sort.InferenceSession(classify.onnx, providers[CPUExecutionProvider]); print(onnx ok)如果这两步都通过再去检查界面代码。QThread 里抛出的异常默认不会导致进程崩溃但会在 Qt 事件循环里留下未捕获异常。建议在 run() 方法里包一层 try-except把异常信息通过信号传回主界面显示。class InferThread(QThread): finished pyqtSignal(dict) error pyqtSignal(str) def run(self): try: result run_pipeline(self.image_path, self.detect_model, self.classify_model, self.device) self.finished.emit(result) except Exception as e: self.error.emit(str(e))异常信息在日志框打印出来而不是让程序直接崩溃这种习惯做项目时能节约大量时间。6.4 模型加载在 Windows 下路径报错Windows 下使用中文路径或包含中文名的模型文件时PyTorch 和 OpenCV 偶尔会出现编码问题。这需要从根源上避免使用中文路径和中文文件名统一用英文。另外模型文件放在项目根目录的 models/ 文件夹里不要放在桌面或下载目录既方便打包也避免权限问题。6.5 训练时 loss 不降或直接变成 NaNloss 变成 NaN 的原因多半是学习率过大、数据里有异常像素值或者标注越界。检测模型训练时重点检查标注坐标是否全部归一化到 [0,1] 区间分类模型训练时检查输入图片是否有损坏文件。更直接的办法是降低初始学习率从 0.001 开始确认 loss 正常下降后再逐步加大。7. 系统验证与扩展如何确认模型真的可靠这套系统做完之后验证是必不可少的一步。舌苔识别系统的验证不同于普通分类任务不能只盯着准确率还要关注临床可用性。我通常的做法是准备一份留出测试集里面全部是训练阶段没有见过的真实场景图片包括不同光照、不同设备、不同角度然后统计检测成功率和分类混淆矩阵。import numpy as np from sklearn.metrics import confusion_matrix, classification_report def evaluate(model, loader, device): model.eval() all_preds, all_labels [], [] with torch.no_grad(): for images, labels in loader: images, labels images.to(device), labels.to(device) outputs model(images) _, preds torch.max(outputs, 1) all_preds.extend(preds.cpu().numpy()) all_labels.extend(labels.cpu().numpy()) cm confusion_matrix(all_labels, all_preds) print(classification_report(all_labels, all_preds, target_namesclass_names)) return cm从混淆矩阵里能看到的不只是准确率还有具体哪些类别互相混淆。黄苔和白苔之间的混淆是常见问题但这代表的是标注标准模糊不是模型缺陷。这时候要做的是回看标注数据确认标注人员之间对“黄”和“白”的颜色界定是否一致必要时重新清洗部分标签。扩展方向上值得做的改造有把检测框的输出从矩形框升级为舌体轮廓分割 mask用 U-Net 做舌体分割能拿到更精确的舌体区域分类输入质量比矩形裁剪好不少把分类网络改成多标签输出——一个舌头可以同时有“薄”和“白”的属性多标签结构更接近临床语义在界面端增加批量识别功能一次导入数十张图片自动出报告对体检中心这种场景的实用价值明显。对整个系统做个评价的话需要清楚它只能提供辅助参考不能替代任何专业医疗判断。界面展示的置信度严格来说明确标注“AI 辅助结果”这在中医信息化项目中既是对规范的尊重也是对使用者的保护。这是这套系统开发过程中最重要的一条教训——技术指标再好也要想清楚使用边界。希望这篇踩坑笔记能帮到你搭建属于自己的舌象分析系统的时候少走一些弯路。本文还有配套的精品资源点击获取