尧图网页设计 
简介这是一份面向计算机、数学、电子信息类专业学生的中医舌苔分析Web应用完整开发源码适合作为课程设计、期末大作业或毕业设计参考。项目核心是基于深度学习的舌象四维分类——舌色、舌苔色、薄厚、腻否处理流程先由YOLOv5目标检测与Segment Anything模型完成舌象分割再由ResNet50残差网络完成分类多模型拼接的工程化设计对视觉应用入门与进阶都很有借鉴意义。压缩包为zip格式共84个文件大小约2.5MB其中22个Python文件承载后端算法、接口与模型推理24个Vue文件构成浏览器端界面另有SQL数据库、JS脚本、JSON配置、CSS样式和项目说明文档目录结构清晰可对照理解前后端协作与部署逻辑同时包含模型调用、路由配置和数据库表结构呈现完整项目范式。目前已有369人学习下载资源内包含可直接运行的源码和使用前必读说明需要读者具备一定Python和Web基础能自行调试并扩展功能。1. 中医舌苔项目 Web 应用一条检测、分割、分类全在线的 Python 实现拖一张舌头照片到网页里几秒钟后页面弹回舌色、舌苔色、薄厚度、腻否四个维度的分析结果——这个中医舌苔项目就这么直接。它不是一个只跑算法脚本的玩具而是一套完整的 Web 应用后端用 Flask 组织 API前端是 Vite 构建的 Vue 工程深度学习链路由 YOLOv5 检测、Segment Anything 分割、ResNet50 分类三块拼接而成全部跑在浏览器交互层背后。压缩包里是项目全部 python 源码、说明文档和数据库文件按文档步骤能直接本地复现。想用 Python 做课程设计、期末大作业或者毕设参考的这份源码比从头搭框架省太多时间想研究舌象分类的多模型拼接的思路也很值得拆开看。2. 技术拆解YOLOv5 SAM ResNet50 三条模型链怎么协作2.1 先看目录这个项目把后端模块放得清清楚楚解压后第一件事不是急着跑命令而是把文件层级认清楚。项目的后端主体非常接近 Flask 标准工程结构run.py是启动入口requirements.txt是依赖清单config目录下面放着配置routes目录定义 API 路由models目录是模型封装orm目录负责和数据库打交道根目录还有一个AppDatabase.db这是 SQLite 的数据库文件。前端则整体收在frontend目录里里面有package.json、vite.config.js、src、public一眼就能认出是 Vite Vue 的工程。这种组织方式对复现很友好。很多课程设计项目喜欢把所有代码堆在两个 py 文件里看起来简单真要改功能时改到怀疑人生。这个项目把路由、模型、ORM 分开意味着你要替换某个算法时只需要动models目录里的对应类路由层和前端基本不用碰。对我这种习惯先读目录再动手的人来说这种结构省掉了一大半这文件是干嘛的的排查时间。前端部分还带了vitest.config.js和cypress.config.js说明项目里配了单元测试和 E2E 测试。虽然跑主流程用不到但如果你要做二次开发拿它当测试脚手架也挺合适。需要注意一点README.md和Readme.md同时在工程目录里出现以Readme.md为准里面写的是启动顺序别把两个文件混着看。2.2 为什么是三个模型拼接而不是一个模型打天下项目描述里反复提到多模型拼接这是理解整个项目的关键。舌象分析这个任务其实分两段先要从一张杂乱背景的照片里定位出舌体再对舌体本身做分类。如果只用一个分类模型它会不停地把背景噪声也学进去比如把嘴唇、牙齿、舌头阴影当成特征。项目里选的方案是先把脏活拆开。第一段是 YOLOv5 目标检测。它负责输出舌体位置的边界框把舌头从照片中切出来。这一步的好处是后面的模型不用再关心舌头到底在哪这件事输入被固定成一块相对干净的舌象区域。第二段是 Segment Anything 模型也就是 Meta 开源的 SAM。YOLOv5 给的是矩形框框里仍然带着嘴唇、牙齿甚至皮肤SAM 做的是像素级分割生成精确的舌体掩膜用掩膜把背景像素直接抹掉。这一步非常关键因为 ResNet50 分类时如果看到嘴唇或者牙齿底色很容易把舌色判断偏。第三段是 ResNet50 残差网络做四分类任务舌色、舌苔色、薄厚、腻否。值得注意的是这四个维度不是简单的四分类输出项目中把它拆成多任务。通常实现方式是在 ResNet50 的最后一层换上多个分类头每个头负责一个维度我在实际项目里也见过拆成四个独立模型的做法但那样部署太重。这个项目选择共享主干、多个输出头的做法训练和推理效率都更高。说到底三模型拼接不是炫技而是把定位—分割—分类三个难度不同的问题交给最擅长它们的模型。这种思路在你以后做其他医学影像分类也通用先检测再分割再分类的三段式往往比端到端强行上一个大模型效果更可控也更省钱。2.3 推理链路核心代码解读把链路串起来的推理代码是这个项目最值得读的部分。常见的写法是在routes里注册一个上传接口接口内部依次调用三个模型的封装类最后拼成 JSON 返回。下面这段代码是这类推理链路的典型骨架我在代码里加了推理顺序和参数作用的标注。# inference.py —— 全局推理骨架逻辑示意 import cv2 import numpy as np from models.yolo import YOLODetector from models.sam import SAMSegmentor from models.resnet import ResNetClassifier # 初始化三个模型detector 是 YOLOv5sam 是分割模型classifier 是 ResNet50 def run_tongue_pipeline(image_path: str) - dict: # 1) YOLOv5 目标检测返回 [x1, y1, x2, y2] 的边界框 bbox YOLODetector.detect(image_path) if bbox is None: # 如果检测不到舌体直接给兜底结果避免后续模型报错 return {code: 400, message: 未检测到舌体请重新拍摄} # 2) 按边界框裁剪原图缩小 SAM 的输入范围降低显存占用 img cv2.imread(image_path) x1, y1, x2, y2 [int(v) for v in bbox] crop img[y1:y2, x1:x2] # 3) SAM 分割返回与原图同尺寸的 0/1 掩膜 mask SAMSegmentor.segment(crop) # 用掩膜把非舌体区域置为黑色背景 masked cv2.bitwise_and(crop, crop, maskmask.astype(np.uint8)) # 4) ResNet50 对掩膜后的舌象做多维度分类 result ResNetClassifier.classify(masked) # 返回示例{tongue_color: 淡红, coating_color: 白, thickness: 薄, greasiness: 不腻} return {code: 200, data: result}四段逻辑里有两个参数值得盯一下第一个是bbox为空时的兜底分支很多复现者图省事会直接让 YOLOv5 返回 None然后下一行就崩了这里必须有条件判断。第二个是cv2.bitwise_and之前的掩膜类型转换SAM 原始输出往往是 float 类型不转成uint8OpenCV 的位运算会直接报类型错误。这两个点就是看起来照着写、一跑就翻车的高发区。分类器部分项目用的是 ResNet50 预训练权重加微调。分类头输出的原始 logits 需要经过 softmax 转成概率每个维度保留概率最高的那一个作为预测标签。实际部署时为了省一次推理常见做法是把四个分类头拼成一个全连接矩阵做一次前向推理只带四个 argmax 出来。3. 本地复现从 Python 环境到前端构建照着跑就能过3.1 虚拟环境与依赖安装我接到这种带深度学习模型的源码包第一原则永远是不要用全局 Python 跑先把环境隔离出来。项目依赖里既要有torch、torchvision、opencv-python这种重量级库又要有 Flask、SQLAlchemy 之类的 Web 框架混在全局环境里轻则版本打架重则把系统里别的项目搞到跑不起来。打开终端在项目根目录执行下面的命令。# 进入项目根目录创建 Python 3.8 的虚拟环境 python -m venv venv # Linux / macOS 激活环境 source venv/bin/activate # Windows 激活环境 venv\Scripts\activate # 安装项目依赖requirements.txt 里已经锁好了版本 pip install -r requirements.txt这里说明一下为什么建议用venv而不是直接conda create。如果你是 Anaconda 用户用 conda 创建环境当然没问题但很多课程设计机器上既有 conda 又有系统 Python两者混着用容易把当前环境变量搞乱。venv 是干净且零额外依赖的方案只要 Python 版本对得上就不会有意外。requirements.txt里的依赖里大概率会同时出现torch和torchvision。这两个包的版本必须严格配套比如torch 1.13.1就要配torchvision 0.14.1。在安装完成后建议加跑一行验证。# 验证 torch 和 torchvision 版本是否配套 python -c import torch, torchvision; print(torch.__version__, torchvision.__version__)如果版本号对不上比如 torch 是 2.0 而 torchvision 还是 0.14后面加载 ResNet50 时大概率会收到RuntimeError: Couldnt load custom C ops之类的报错。这是我在帮别人排查时最常碰到的问题没有之一。3.2 后端启动与数据库初始化依赖装好后启动后端理论上只需要一行命令。项目根目录的run.py就是入口它会读取config里的环境配置创建 Flask app然后监听默认端口。# 在项目根目录venv 环境下执行 python run.py启动过程里有几个细节值得检查。第一端口是不是被占用Flask 默认监听 5000 端口如果你本机已经有服务占了这个端口启动会直接失败报Address already in use改config里的端口号就好。第二启动日志里如果出现AppDatabase.db does not exist说明数据库还没初始化。项目里AppDatabase.db是直接放在根目录的如果压缩包被解压时漏了这个文件就需要用 orm 目录下的建表逻辑来重建。手动初始化数据库通常是这样的流程项目里应该有对应的 CLI 命令没有的话可以直接在 Python shell 里执行建表操作。# 从项目根目录打开 Python 交互环境执行建表 python -c from orm import init_db; init_db()init_db函数一般会在 orm 包的__init__.py里定义它会把 models 目录下定义的数据模型通过 SQLAlchemy 映射成 SQLite 表。执行完后再看根目录AppDatabase.db文件会重新生成。这里有个细节SQLite 文件一旦生成在根目录后续启动run.py时千万不要把启动目录切到子文件夹否则 Flask 会去子文件夹里找AppDatabase.db找不到就自动新建一个空库你会遇到明明建了表为什么提示没有这个表的诡异问题。这个坑我后面在避坑章节还会展开。3.3 前端 Vite Vue 构建与联调后端起来了接下来是前端。这部分对纯 Python 用户来说可能是最陌生的但其实流程非常机械。先确认你机器上有 Node.js建议 16 以上的版本然后进入frontend目录。# 进入前端目录 cd frontend # 安装依赖package.json 里已经声明了全部前端包 npm install # 开发模式启动默认走 Vite 的热更新 npm run devnpm install需要一点耐心因为 Vue 项目会把 axios、element-plus 这一层的依赖全拉下来网速慢的话会有几分钟空白。装完以后npm run dev会本地起一个 Vite 服务默认端口通常是 5173终端会显示可访问的地址。联调前的最后一步是确认 API 地址。前端.env文件或者vite.config.js的 proxy 配置里会把/api请求代理到后端地址。如果代理配置指错了端口前端会一直报跨域或 404。常见的正确配置是后端跑在http://localhost:5000前端开发服务器通过 proxy 把请求转发到5000。如果你用的是生产构建还需要先执行npm run build再把dist目录交给 Nginx 托管同时 Nginx 里配一份反向代理到 Flask 的/api。// vite.config.js —— 开发代理配置示意 export default { server: { proxy: { // 所有 /api 开头的请求代理到 Flask 后端 /api: { target: http://localhost:5000, changeOrigin: true } } } }changeOrigin: true这个参数要注意不写的话请求头里的 Host 名会保留成前端域名后端如果做了域名校验就会返回异常。这是前后端联调里出现要么跨域要么 404时第一个要检查的地方。4. 避坑手册五个最容易翻车的点与解决办法4.1 模型权重路径不对加载不报错推理结果全空现象程序能启动前端页面也能打开但上传一张舌头照片后后端返回未检测到舌体或者分类结果始终是同一个值换多少张图都一样。原因YOLOv5 和 SAM 的权重文件在项目里是以相对路径引用的比如weights/best.pt。当你把项目从压缩包解压后如果直接用了 IDE 里某个偏好的工作目录启动run.py相对路径会解析到错误位置。模型加载到一半会走 catch 分支表面上不报错实际上加载的是随机初始化权重推理结果自然全废。解决建议强制用绝对路径定位权重文件。在模型的加载代码里改成os.path.dirname(__file__)拼出权重目录而不是用.表示当前目录。改完以后要重新启动后端并盯着启动日志确认类似Loaded weights from /absolute/path/best.pt的日志真正打出这行日志比什么断言都靠谱。4.2 torch 与 CUDA 版本不匹配显卡形同虚设现象模型推理时 GPU 占用率始终是 0%推理速度慢到每张图要十几秒终端里不断出现UserWarning: CUDA initialization: CUDA_DEVICE_NOT_FOUND。原因装了 CPU 版的torch或者 torch 的 CUDA 版本和显卡驱动不匹配。检查后发现 requirements.txt 里的torch是 PyPI 默认的 CPU 版本这个版本用起来没问题但根本不会调显卡。解决先把 GPU 上的推理显存需求压到最低然后重装对应 CUDA 版本的 torch。NVIDIA 显卡先去官网查驱动支持的 CUDA 版本再按对应命令安装比如安装 CUDA 11.8 配套的 torch。# 以 torch 2.0 CUDA 11.8 为例先卸载 CPU 版 pip uninstall torch torchvision # 安装 CUDA 12.1 版本注意是 cu121 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121如果显卡实在不支持那就老老实实 CPU 推理不要试图在代码里强制.to(cuda)那只会收到 RuntimeError。项目功能上 CPU 也能跑通只是慢备选方案是缩小输入尺寸。4.3 图片上传格式与大小前端不拦后端必崩现象上传 jpg 没问题一上传 png 或者超高清大图后端就 500日志里是cv2.error: OpenCV(4.x) ... assertion failed。原因OpenCV 的imread对部分格式支持不完整尤其是带透明通道的 PNG 或者 16 位深度的 TIFF。另外前端没做图片压缩几张 12MP 的手机原图直接塞进来后端cv2.resize时内存飙升触发 OOM。解决前端上传组件里强制转码和压缩统一输出为 RGB 的 JPEG尺寸限制在 1024 像素以内。这个限制放在前端比后端做省事并且用户体验也好。后端接口里也得再校验一次 Content-Type 和文件后缀双保险。# 后端校验文件类型的示意代码 ALLOWED_TYPES {image/jpeg, image/png} def valid_upload(file): # 检查 MIME 类型忽略大小写 if file.mimetype not in ALLOWED_TYPES: return False return True图片尺寸这块项目原始代码如果没做预缩放我一般会建议在 YOLOv5 检测前加一步用cv2.resize把最长边压到 1280。超过这个尺寸对检测精度提升有限但推理耗时和内存占用是成倍上涨的得不偿失。4.4 数据库文件或表缺失登录注册全 500现象从压缩包解压后没看到AppDatabase.db或者启动时它在根目录生成但等页面注册时一直 500日志提示sqlite3.OperationalError: no such table: user。原因项目自带的AppDatabase.db没被正确解压或者启动了两次run.py其中一次改变了工作目录导致 SQLAlchemy 在另一个路径下新建了空库。解决第一步先确认根目录下AppDatabase.db存在并且文件大小不是 0 字节。如果是不存在或者为空执行建表初始化。第二步检查orm目录里有没有init_db之类的函数没有的话就在run.py里手动调用db.create_all()。之后启动服务时固定目录不要用python app/run.py这种从子目录执行的姿势老老实实退到根目录再启动。4.5 SAM 分割掩膜为空或全黑分类结果完全不可用现象检测正常、分割也走完了但分类结果永远是舌色偏黑之类的不合理输出。把中间结果保存出来一看掩膜全黑。原因SAM 生成的概率图里低于阈值的像素全被置为 0而这个阈值得看项目自带的权重和数据。如果参数是写死的比如mask_threshold0.5在一些对比度不高的舌象上就会把所有像素判定为背景导致分割出的舌体直接变黑块。解决把掩膜生成后的像素值分布打出来看最大最小值和均值。如果均值低于 0.1先把阈值降到 0.3 再试。更稳的做法是不硬编码阈值而是直接用 SAM 输出的 logits 取 top-k 像素来做自适应效果会好很多。# 自适应掩膜阈值示意用 logits 分位数代替固定阈值 import numpy as np def adaptive_mask(pred_logits, quantile0.7): # 取一个分位数作为阈值避开对比度差异 threshold np.quantile(pred_logits, quantile) return (pred_logits threshold).astype(np.uint8)要注意这个兜底逻辑要和业务对齐如果一张舌象本身就淡阈值太低会把背景也划进来此时应该结合 YOLOv5 的框做裁剪约束。我习惯把分割结果可视化成中间图的输出开关留在代码里排查问题时比盯着一堆数字直观得多。5. 进阶替换成你自己的数据集和模型并验证输出当你想把项目改成自己的舌象数据集核心改动集中在models目录和config。ResNet50 的分类头要按你的维度数量改比如原项目是四个维度每个维度 3 到 4 个类别你要改成两个维度就删掉对应输出头重新微调时冻结主干、只训练分类头这样数据量小也不容易过拟合。YOLOv5 部分如果你要检测的是别的部位需要重新标注数据格式走 YOLOv5 的 label 格式即每个目标一行class x_center y_center width height注意是中心点加宽高的归一化坐标。验证输出时我通常会做两个动作。第一保存中间结果到debug目录把 YOLOv5 画框图、SAM 掩膜图、ResNet50 掩膜分类图三张并排拼在一起一眼就能看出是哪一环出问题。第二做一个小批量一致性测试统计同一个用户在相同光照条件下上传五张同一舌象照片的推理结果看四个维度的输出是否稳定。稳定输出比单张错对重要因为这类项目最大的风险就是随机性。部署层面如果想让前后端不再分开启动可以直接用 Nginx 托管frontend/dist静态文件然后反向代理/api到 Flask。这样从用户视角只有一个端口绕开了开发模式下的跨域问题。优化推理速度时可以把 YOLOv5 的权重转成 ONNX 或者 TensorRT但这种优化会让代码可读性变差建议先把功能稳定跑通再去动。反向代理配置举例如下。server { listen 80; # 静态文件路由 location / { root /path/to/frontend/dist; index index.html; } # API 反向代理 location /api/ { proxy_pass http://127.0.0.1:5000; proxy_set_header Host $host; } }从那以后我每次复现这种带深度学习的 Web 项目都会强制自己先走一遍核目录、查版本、启数据库、验中间结果四步。前两步省去大部分环境问题后两步把模型链路是否正常从黑匣子变成可见状态。你接手这份源码时别直接双击运行照着本文顺序走一遍很多所谓的玄学报错会消失。希望帮到你。本文还有配套的精品资源点击获取 中医舌苔检测Web应用：Python+YOLOv5+SAM+ResNet50多模型协作
简介这是一份面向计算机、数学、电子信息类专业学生的中医舌苔分析Web应用完整开发源码适合作为课程设计、期末大作业或毕业设计参考。项目核心是基于深度学习的舌象四维分类——舌色、舌苔色、薄厚、腻否处理流程先由YOLOv5目标检测与Segment Anything模型完成舌象分割再由ResNet50残差网络完成分类多模型拼接的工程化设计对视觉应用入门与进阶都很有借鉴意义。压缩包为zip格式共84个文件大小约2.5MB其中22个Python文件承载后端算法、接口与模型推理24个Vue文件构成浏览器端界面另有SQL数据库、JS脚本、JSON配置、CSS样式和项目说明文档目录结构清晰可对照理解前后端协作与部署逻辑同时包含模型调用、路由配置和数据库表结构呈现完整项目范式。目前已有369人学习下载资源内包含可直接运行的源码和使用前必读说明需要读者具备一定Python和Web基础能自行调试并扩展功能。1. 中医舌苔项目 Web 应用一条检测、分割、分类全在线的 Python 实现拖一张舌头照片到网页里几秒钟后页面弹回舌色、舌苔色、薄厚度、腻否四个维度的分析结果——这个中医舌苔项目就这么直接。它不是一个只跑算法脚本的玩具而是一套完整的 Web 应用后端用 Flask 组织 API前端是 Vite 构建的 Vue 工程深度学习链路由 YOLOv5 检测、Segment Anything 分割、ResNet50 分类三块拼接而成全部跑在浏览器交互层背后。压缩包里是项目全部 python 源码、说明文档和数据库文件按文档步骤能直接本地复现。想用 Python 做课程设计、期末大作业或者毕设参考的这份源码比从头搭框架省太多时间想研究舌象分类的多模型拼接的思路也很值得拆开看。2. 技术拆解YOLOv5 SAM ResNet50 三条模型链怎么协作2.1 先看目录这个项目把后端模块放得清清楚楚解压后第一件事不是急着跑命令而是把文件层级认清楚。项目的后端主体非常接近 Flask 标准工程结构run.py是启动入口requirements.txt是依赖清单config目录下面放着配置routes目录定义 API 路由models目录是模型封装orm目录负责和数据库打交道根目录还有一个AppDatabase.db这是 SQLite 的数据库文件。前端则整体收在frontend目录里里面有package.json、vite.config.js、src、public一眼就能认出是 Vite Vue 的工程。这种组织方式对复现很友好。很多课程设计项目喜欢把所有代码堆在两个 py 文件里看起来简单真要改功能时改到怀疑人生。这个项目把路由、模型、ORM 分开意味着你要替换某个算法时只需要动models目录里的对应类路由层和前端基本不用碰。对我这种习惯先读目录再动手的人来说这种结构省掉了一大半这文件是干嘛的的排查时间。前端部分还带了vitest.config.js和cypress.config.js说明项目里配了单元测试和 E2E 测试。虽然跑主流程用不到但如果你要做二次开发拿它当测试脚手架也挺合适。需要注意一点README.md和Readme.md同时在工程目录里出现以Readme.md为准里面写的是启动顺序别把两个文件混着看。2.2 为什么是三个模型拼接而不是一个模型打天下项目描述里反复提到多模型拼接这是理解整个项目的关键。舌象分析这个任务其实分两段先要从一张杂乱背景的照片里定位出舌体再对舌体本身做分类。如果只用一个分类模型它会不停地把背景噪声也学进去比如把嘴唇、牙齿、舌头阴影当成特征。项目里选的方案是先把脏活拆开。第一段是 YOLOv5 目标检测。它负责输出舌体位置的边界框把舌头从照片中切出来。这一步的好处是后面的模型不用再关心舌头到底在哪这件事输入被固定成一块相对干净的舌象区域。第二段是 Segment Anything 模型也就是 Meta 开源的 SAM。YOLOv5 给的是矩形框框里仍然带着嘴唇、牙齿甚至皮肤SAM 做的是像素级分割生成精确的舌体掩膜用掩膜把背景像素直接抹掉。这一步非常关键因为 ResNet50 分类时如果看到嘴唇或者牙齿底色很容易把舌色判断偏。第三段是 ResNet50 残差网络做四分类任务舌色、舌苔色、薄厚、腻否。值得注意的是这四个维度不是简单的四分类输出项目中把它拆成多任务。通常实现方式是在 ResNet50 的最后一层换上多个分类头每个头负责一个维度我在实际项目里也见过拆成四个独立模型的做法但那样部署太重。这个项目选择共享主干、多个输出头的做法训练和推理效率都更高。说到底三模型拼接不是炫技而是把定位—分割—分类三个难度不同的问题交给最擅长它们的模型。这种思路在你以后做其他医学影像分类也通用先检测再分割再分类的三段式往往比端到端强行上一个大模型效果更可控也更省钱。2.3 推理链路核心代码解读把链路串起来的推理代码是这个项目最值得读的部分。常见的写法是在routes里注册一个上传接口接口内部依次调用三个模型的封装类最后拼成 JSON 返回。下面这段代码是这类推理链路的典型骨架我在代码里加了推理顺序和参数作用的标注。# inference.py —— 全局推理骨架逻辑示意 import cv2 import numpy as np from models.yolo import YOLODetector from models.sam import SAMSegmentor from models.resnet import ResNetClassifier # 初始化三个模型detector 是 YOLOv5sam 是分割模型classifier 是 ResNet50 def run_tongue_pipeline(image_path: str) - dict: # 1) YOLOv5 目标检测返回 [x1, y1, x2, y2] 的边界框 bbox YOLODetector.detect(image_path) if bbox is None: # 如果检测不到舌体直接给兜底结果避免后续模型报错 return {code: 400, message: 未检测到舌体请重新拍摄} # 2) 按边界框裁剪原图缩小 SAM 的输入范围降低显存占用 img cv2.imread(image_path) x1, y1, x2, y2 [int(v) for v in bbox] crop img[y1:y2, x1:x2] # 3) SAM 分割返回与原图同尺寸的 0/1 掩膜 mask SAMSegmentor.segment(crop) # 用掩膜把非舌体区域置为黑色背景 masked cv2.bitwise_and(crop, crop, maskmask.astype(np.uint8)) # 4) ResNet50 对掩膜后的舌象做多维度分类 result ResNetClassifier.classify(masked) # 返回示例{tongue_color: 淡红, coating_color: 白, thickness: 薄, greasiness: 不腻} return {code: 200, data: result}四段逻辑里有两个参数值得盯一下第一个是bbox为空时的兜底分支很多复现者图省事会直接让 YOLOv5 返回 None然后下一行就崩了这里必须有条件判断。第二个是cv2.bitwise_and之前的掩膜类型转换SAM 原始输出往往是 float 类型不转成uint8OpenCV 的位运算会直接报类型错误。这两个点就是看起来照着写、一跑就翻车的高发区。分类器部分项目用的是 ResNet50 预训练权重加微调。分类头输出的原始 logits 需要经过 softmax 转成概率每个维度保留概率最高的那一个作为预测标签。实际部署时为了省一次推理常见做法是把四个分类头拼成一个全连接矩阵做一次前向推理只带四个 argmax 出来。3. 本地复现从 Python 环境到前端构建照着跑就能过3.1 虚拟环境与依赖安装我接到这种带深度学习模型的源码包第一原则永远是不要用全局 Python 跑先把环境隔离出来。项目依赖里既要有torch、torchvision、opencv-python这种重量级库又要有 Flask、SQLAlchemy 之类的 Web 框架混在全局环境里轻则版本打架重则把系统里别的项目搞到跑不起来。打开终端在项目根目录执行下面的命令。# 进入项目根目录创建 Python 3.8 的虚拟环境 python -m venv venv # Linux / macOS 激活环境 source venv/bin/activate # Windows 激活环境 venv\Scripts\activate # 安装项目依赖requirements.txt 里已经锁好了版本 pip install -r requirements.txt这里说明一下为什么建议用venv而不是直接conda create。如果你是 Anaconda 用户用 conda 创建环境当然没问题但很多课程设计机器上既有 conda 又有系统 Python两者混着用容易把当前环境变量搞乱。venv 是干净且零额外依赖的方案只要 Python 版本对得上就不会有意外。requirements.txt里的依赖里大概率会同时出现torch和torchvision。这两个包的版本必须严格配套比如torch 1.13.1就要配torchvision 0.14.1。在安装完成后建议加跑一行验证。# 验证 torch 和 torchvision 版本是否配套 python -c import torch, torchvision; print(torch.__version__, torchvision.__version__)如果版本号对不上比如 torch 是 2.0 而 torchvision 还是 0.14后面加载 ResNet50 时大概率会收到RuntimeError: Couldnt load custom C ops之类的报错。这是我在帮别人排查时最常碰到的问题没有之一。3.2 后端启动与数据库初始化依赖装好后启动后端理论上只需要一行命令。项目根目录的run.py就是入口它会读取config里的环境配置创建 Flask app然后监听默认端口。# 在项目根目录venv 环境下执行 python run.py启动过程里有几个细节值得检查。第一端口是不是被占用Flask 默认监听 5000 端口如果你本机已经有服务占了这个端口启动会直接失败报Address already in use改config里的端口号就好。第二启动日志里如果出现AppDatabase.db does not exist说明数据库还没初始化。项目里AppDatabase.db是直接放在根目录的如果压缩包被解压时漏了这个文件就需要用 orm 目录下的建表逻辑来重建。手动初始化数据库通常是这样的流程项目里应该有对应的 CLI 命令没有的话可以直接在 Python shell 里执行建表操作。# 从项目根目录打开 Python 交互环境执行建表 python -c from orm import init_db; init_db()init_db函数一般会在 orm 包的__init__.py里定义它会把 models 目录下定义的数据模型通过 SQLAlchemy 映射成 SQLite 表。执行完后再看根目录AppDatabase.db文件会重新生成。这里有个细节SQLite 文件一旦生成在根目录后续启动run.py时千万不要把启动目录切到子文件夹否则 Flask 会去子文件夹里找AppDatabase.db找不到就自动新建一个空库你会遇到明明建了表为什么提示没有这个表的诡异问题。这个坑我后面在避坑章节还会展开。3.3 前端 Vite Vue 构建与联调后端起来了接下来是前端。这部分对纯 Python 用户来说可能是最陌生的但其实流程非常机械。先确认你机器上有 Node.js建议 16 以上的版本然后进入frontend目录。# 进入前端目录 cd frontend # 安装依赖package.json 里已经声明了全部前端包 npm install # 开发模式启动默认走 Vite 的热更新 npm run devnpm install需要一点耐心因为 Vue 项目会把 axios、element-plus 这一层的依赖全拉下来网速慢的话会有几分钟空白。装完以后npm run dev会本地起一个 Vite 服务默认端口通常是 5173终端会显示可访问的地址。联调前的最后一步是确认 API 地址。前端.env文件或者vite.config.js的 proxy 配置里会把/api请求代理到后端地址。如果代理配置指错了端口前端会一直报跨域或 404。常见的正确配置是后端跑在http://localhost:5000前端开发服务器通过 proxy 把请求转发到5000。如果你用的是生产构建还需要先执行npm run build再把dist目录交给 Nginx 托管同时 Nginx 里配一份反向代理到 Flask 的/api。// vite.config.js —— 开发代理配置示意 export default { server: { proxy: { // 所有 /api 开头的请求代理到 Flask 后端 /api: { target: http://localhost:5000, changeOrigin: true } } } }changeOrigin: true这个参数要注意不写的话请求头里的 Host 名会保留成前端域名后端如果做了域名校验就会返回异常。这是前后端联调里出现要么跨域要么 404时第一个要检查的地方。4. 避坑手册五个最容易翻车的点与解决办法4.1 模型权重路径不对加载不报错推理结果全空现象程序能启动前端页面也能打开但上传一张舌头照片后后端返回未检测到舌体或者分类结果始终是同一个值换多少张图都一样。原因YOLOv5 和 SAM 的权重文件在项目里是以相对路径引用的比如weights/best.pt。当你把项目从压缩包解压后如果直接用了 IDE 里某个偏好的工作目录启动run.py相对路径会解析到错误位置。模型加载到一半会走 catch 分支表面上不报错实际上加载的是随机初始化权重推理结果自然全废。解决建议强制用绝对路径定位权重文件。在模型的加载代码里改成os.path.dirname(__file__)拼出权重目录而不是用.表示当前目录。改完以后要重新启动后端并盯着启动日志确认类似Loaded weights from /absolute/path/best.pt的日志真正打出这行日志比什么断言都靠谱。4.2 torch 与 CUDA 版本不匹配显卡形同虚设现象模型推理时 GPU 占用率始终是 0%推理速度慢到每张图要十几秒终端里不断出现UserWarning: CUDA initialization: CUDA_DEVICE_NOT_FOUND。原因装了 CPU 版的torch或者 torch 的 CUDA 版本和显卡驱动不匹配。检查后发现 requirements.txt 里的torch是 PyPI 默认的 CPU 版本这个版本用起来没问题但根本不会调显卡。解决先把 GPU 上的推理显存需求压到最低然后重装对应 CUDA 版本的 torch。NVIDIA 显卡先去官网查驱动支持的 CUDA 版本再按对应命令安装比如安装 CUDA 11.8 配套的 torch。# 以 torch 2.0 CUDA 11.8 为例先卸载 CPU 版 pip uninstall torch torchvision # 安装 CUDA 12.1 版本注意是 cu121 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121如果显卡实在不支持那就老老实实 CPU 推理不要试图在代码里强制.to(cuda)那只会收到 RuntimeError。项目功能上 CPU 也能跑通只是慢备选方案是缩小输入尺寸。4.3 图片上传格式与大小前端不拦后端必崩现象上传 jpg 没问题一上传 png 或者超高清大图后端就 500日志里是cv2.error: OpenCV(4.x) ... assertion failed。原因OpenCV 的imread对部分格式支持不完整尤其是带透明通道的 PNG 或者 16 位深度的 TIFF。另外前端没做图片压缩几张 12MP 的手机原图直接塞进来后端cv2.resize时内存飙升触发 OOM。解决前端上传组件里强制转码和压缩统一输出为 RGB 的 JPEG尺寸限制在 1024 像素以内。这个限制放在前端比后端做省事并且用户体验也好。后端接口里也得再校验一次 Content-Type 和文件后缀双保险。# 后端校验文件类型的示意代码 ALLOWED_TYPES {image/jpeg, image/png} def valid_upload(file): # 检查 MIME 类型忽略大小写 if file.mimetype not in ALLOWED_TYPES: return False return True图片尺寸这块项目原始代码如果没做预缩放我一般会建议在 YOLOv5 检测前加一步用cv2.resize把最长边压到 1280。超过这个尺寸对检测精度提升有限但推理耗时和内存占用是成倍上涨的得不偿失。4.4 数据库文件或表缺失登录注册全 500现象从压缩包解压后没看到AppDatabase.db或者启动时它在根目录生成但等页面注册时一直 500日志提示sqlite3.OperationalError: no such table: user。原因项目自带的AppDatabase.db没被正确解压或者启动了两次run.py其中一次改变了工作目录导致 SQLAlchemy 在另一个路径下新建了空库。解决第一步先确认根目录下AppDatabase.db存在并且文件大小不是 0 字节。如果是不存在或者为空执行建表初始化。第二步检查orm目录里有没有init_db之类的函数没有的话就在run.py里手动调用db.create_all()。之后启动服务时固定目录不要用python app/run.py这种从子目录执行的姿势老老实实退到根目录再启动。4.5 SAM 分割掩膜为空或全黑分类结果完全不可用现象检测正常、分割也走完了但分类结果永远是舌色偏黑之类的不合理输出。把中间结果保存出来一看掩膜全黑。原因SAM 生成的概率图里低于阈值的像素全被置为 0而这个阈值得看项目自带的权重和数据。如果参数是写死的比如mask_threshold0.5在一些对比度不高的舌象上就会把所有像素判定为背景导致分割出的舌体直接变黑块。解决把掩膜生成后的像素值分布打出来看最大最小值和均值。如果均值低于 0.1先把阈值降到 0.3 再试。更稳的做法是不硬编码阈值而是直接用 SAM 输出的 logits 取 top-k 像素来做自适应效果会好很多。# 自适应掩膜阈值示意用 logits 分位数代替固定阈值 import numpy as np def adaptive_mask(pred_logits, quantile0.7): # 取一个分位数作为阈值避开对比度差异 threshold np.quantile(pred_logits, quantile) return (pred_logits threshold).astype(np.uint8)要注意这个兜底逻辑要和业务对齐如果一张舌象本身就淡阈值太低会把背景也划进来此时应该结合 YOLOv5 的框做裁剪约束。我习惯把分割结果可视化成中间图的输出开关留在代码里排查问题时比盯着一堆数字直观得多。5. 进阶替换成你自己的数据集和模型并验证输出当你想把项目改成自己的舌象数据集核心改动集中在models目录和config。ResNet50 的分类头要按你的维度数量改比如原项目是四个维度每个维度 3 到 4 个类别你要改成两个维度就删掉对应输出头重新微调时冻结主干、只训练分类头这样数据量小也不容易过拟合。YOLOv5 部分如果你要检测的是别的部位需要重新标注数据格式走 YOLOv5 的 label 格式即每个目标一行class x_center y_center width height注意是中心点加宽高的归一化坐标。验证输出时我通常会做两个动作。第一保存中间结果到debug目录把 YOLOv5 画框图、SAM 掩膜图、ResNet50 掩膜分类图三张并排拼在一起一眼就能看出是哪一环出问题。第二做一个小批量一致性测试统计同一个用户在相同光照条件下上传五张同一舌象照片的推理结果看四个维度的输出是否稳定。稳定输出比单张错对重要因为这类项目最大的风险就是随机性。部署层面如果想让前后端不再分开启动可以直接用 Nginx 托管frontend/dist静态文件然后反向代理/api到 Flask。这样从用户视角只有一个端口绕开了开发模式下的跨域问题。优化推理速度时可以把 YOLOv5 的权重转成 ONNX 或者 TensorRT但这种优化会让代码可读性变差建议先把功能稳定跑通再去动。反向代理配置举例如下。server { listen 80; # 静态文件路由 location / { root /path/to/frontend/dist; index index.html; } # API 反向代理 location /api/ { proxy_pass http://127.0.0.1:5000; proxy_set_header Host $host; } }从那以后我每次复现这种带深度学习的 Web 项目都会强制自己先走一遍核目录、查版本、启数据库、验中间结果四步。前两步省去大部分环境问题后两步把模型链路是否正常从黑匣子变成可见状态。你接手这份源码时别直接双击运行照着本文顺序走一遍很多所谓的玄学报错会消失。希望帮到你。本文还有配套的精品资源点击获取