SpringBoot垃圾分类识别小程序:模型部署与联调实战
简介:这是一份面向毕业设计、课程设计与项目实践的Spring Boot垃圾分类识别小程序项目资源,适合计算机相关专业学生用于系统设计、功能演示与二次开发。项目采用前后端分离思路,前端为小程序Vue页面,后端基于Spring Boot提供接口服务,围绕垃圾分类识别核心业务展开,涵盖页面展示、交互逻辑、样式适配与配置部署等环节。资源包共304个文件,以vue、js、scss、json、png等类型为主,如Vue组件负责页面结构,JavaScript实现交互逻辑,SCSS定制样式,JSON存放配置数据,同时包含环境配置文件、说明文档、图标和示例图片,整体仅1.59MB,轻量精炼,便于快速启动和按需修改。当前已有70人学习浏览,适合作为毕业设计参考资料,帮助理解垃圾分类小程序从界面到后端的完整关联。内含设计资料与源码,可支撑课题分析、模块拆解和设计说明书撰写,也为课程设计和项目实践提供了可直接落地的参考实现。
1. 为什么要做“SpringBoot + 垃圾分类识别小程序”
把手机摄像头对准一个塑料瓶,小程序页面上直接显示“可回收物”,这个看似简单的交互,背后是一条完整的工程链路:模型推理、后端接口、小程序上传与状态管理。这个题目最容易被低估的地方,是它不只是“训练一个图像分类模型”,也不只是“写一个SpringBoot CRUD”,而是要在一个毕业设计的时间预算内,把识别模型、服务端、移动端三件事串成一个能现场演示的闭环。
我做这类项目时,第一版一定会先跑通一个最小闭环:模型不管准确率多差,先能从图片输出类别;后端不管代码多糙,先能接收文件并返回JSON;小程序不管页面多难看,先能把相册里的图片传到后端。闭环通了,后面所有的优化都是在给这个管道加厚。SpringBoot负责提供稳定的HTTP服务,小程序负责把拍照成本降到最低,识别模型负责把“是什么垃圾”这个核心问题答出来。这个组合最大的优势是每层都能独立替换,模型不行换模型,前端不满意换前端,后端接口保持不变。
2. SpringBoot 集成垃圾分类识别模型:从选型到 ONNX 推理
2.1 模型选型:为什么我不用 ResNet,而是选 MobileNetV3
垃圾分类识别的输入是普通手机拍摄的照片,场景可能在家里、楼道、垃圾桶旁,光照不稳定,背景杂乱,但分类类别并不算多。常见做法是分成可回收物、厨余垃圾、有害垃圾、其他垃圾四大类,再细一点可以扩充到几十个小类。面对这种任务,模型的第一诉求不是精度上限,而是推理耗时和部署体积。
ResNet50 在 ImageNet 上的精度确实高,但把一张 224x224 的图片跑一次前向推理,在纯 CPU 环境下的耗时通常在 80ms 以上,如果并发上来,SpringBoot 服务的线程会被推理请求占满。MobileNetV3-Large 在同样输入尺寸下,CPU 推理能压到 20ms 到 40ms,模型文件大约在 20MB 左右,对小程序场景的体验要友好得多。
我一般直接用 TensorFlow 2 或 PyTorch 训练 MobileNetV3,训练完成后不直接调 Python 服务,而是把模型导出成 ONNX 格式,再在 SpringBoot 里用 onnxruntime 做推理。这样整个项目打包成一个 Java 进程,不需要额外部署 Python 环境,也不会出现“模型服务挂了但 Web 端还活着”的分裂状态。
2.2 把训练好的模型导出成 ONNX,并在 SpringBoot 里加载
训练部分核心代码如下,使用 PyTorch 内置的 mobilenet_v3_large,替换分类头为自定义类别数,并导出 ONNX:
import torch
from torchvision import models
model = models.mobilenet_v3_large(weights=models.MobileNet_V3_Large_Weights.IMAGENET1K_V1)
model.classifier[3] = torch.nn.Linear(model.classifier[3].in_features, 4)
checkpoint = torch.load("garbage_model.pth", map_location="cpu")
model.load_state_dict(checkpoint["model_state_dict"])
model.eval()
dummy_input = torch.randn(1, 3, 224, 224)
torch.onnx.export(
model,
dummy_input,
"garbage_model.onnx",
input_names=["input"],
output_names=["output"],
dynamic_axes={"input": {0: "batch"}, "output": {0: "batch"}},
opset_version=12,
)
print("export onnx done")
这里替换 model.classifier[3] 是因为 MobileNetV3 的分类头是 Sequential,最后一层线性层的输出维度是 4,对应四分类。导出时固定输入尺寸 224x224,与训练时保持一致。导出后可以用 netron 查看模型输入输出名,后面写 Java 代码时要用这些名字。
SpringBoot 侧引入 ONNX Runtime 依赖:
<dependency>
<groupId>com.microsoft.onnxruntime</groupId>
<artifactId>onnxruntime</artifactId>
<version>1.16.3</version>
</dependency>
对应的推理服务类:
import ai.onnxruntime.*;
import org.springframework.core.io.ClassPathResource;
import org.springframework.stereotype.Service;
import javax.annotation.PostConstruct;
import java.awt.image.BufferedImage;
import java.util.Map;
@Service
public class GarbageClassifyService {
private OrtEnvironment env;
private OrtSession session;
@PostConstruct
public void init() throws Exception {
env = OrtEnvironment.getEnvironment();
OrtSession.SessionOptions options = new OrtSession.SessionOptions();
options.setOptimizationLevel(OrtSession.SessionOptions.OptLevel.ALL_OPT);
session = env.createSession(new ClassPathResource("models/garbage_model.onnx").getInputStream(), options);
}
public int classify(float[][][] normalizedPixels) throws OrtException {
float[][][][] input = new float[1][224][224][3];
input[0] = normalizedPixels;
OnnxTensor tensor = OnnxTensor.createTensor(env, input);
OrtSession.Result result = session.run(Map.of("input", tensor));
float[][] output = (float[][]) result.get(0).getValue();
return argmax(output[0]);
}
private int argmax(float[] arr) {
int idx = 0;
for (int i = 1; i < arr.length; i++) {
if (arr[i] > arr[idx]) idx = i;
}
return idx;
}
}
这段代码要注意两点:ONNX 的输入张量布局是 batch, height, width, channel ,也就是 NHWC,而 PyTorch 导出时默认是 NCHW,所以导出前要么在 export 里加 channels_last=True 并转换,要么在 Java 端做维度置换。我这里选择在 Java 端把图片像素组织成 224x224x3,避免改动训练代码。
2.3 ONNX Runtime 的线程数与优化选项
OptLevel.ALL_OPT 会启用图优化,包括算子融合和常量折叠,对推理延迟有明显改善。还有一个容易被忽略的参数是线程数:
options.setIntraOpNumThreads(2);
默认情况下 ONNX Runtime 会按 CPU 核心数创建线程池,这在服务器上可能抢走 SpringBoot 业务线程的 CPU 资源。我一般设置为 1 到 2,大部分移动端分类模型在单线程下也就慢几毫秒,但整体服务的吞吐会稳定很多。
第一次加载模型时的耗时通常在 300ms 以上,所以 @PostConstruct 里做初始化是必须的,不能在请求进来后才创建 Session。 createSession 时传入 InputStream 是从 classpath 读取模型文件,模型放在 src/main/resources/models/ 目录下即可。
3. 小程序与 SpringBoot 的识别接口联调:上传、超时与异常降级
3.1 REST 接口设计:POST /api/classify 的请求和响应
小程序端通过 wx.uploadFile 上传图片,后端接收 MultipartFile,做预处理,返回 JSON。接口设计上我只暴露一个 POST 接口,不做多接口拆分,因为识别链路里最耗时的不是网络传输,是图片解码和模型推理。
@RestController
@RequestMapping("/api")
public class ClassifyController {
private final GarbageClassifyService classifyService;
private final ImagePreprocessService preprocessService;
public ClassifyController(GarbageClassifyService classifyService, ImagePreprocessService preprocessService) {
this.classifyService = classifyService;
this.preprocessService = preprocessService;
}
@PostMapping("/classify")
public ResponseEntity<Map<String, Object>> classify(@RequestParam("file") MultipartFile file) {
try {
float[][][] pixels = preprocessService.process(file.getBytes());
long start = System.currentTimeMillis();
int label = classifyService.classify(pixels);
long cost = System.currentTimeMillis() - start;
Map<String, Object> resp = new HashMap<>();
resp.put("code", 0);
resp.put("label", label);
resp.put("category", categoryName(label));
resp.put("costMs", cost);
return ResponseEntity.ok(resp);
} catch (Exception e) {
Map<String, Object> err = new HashMap<>();
err.put("code", 500);
err.put("message", "图片解析失败,请换一张清晰的图片");
return ResponseEntity.status(HttpStatus.OK).body(err);
}
}
}
返回 code=0 表示成功, code=500 表示业务失败。这里故意把异常也返回 HTTP 200,是因为小程序端处理业务错误比处理 HTTP 错误更直观, wx.uploadFile 在 HTTP 500 时会把 statusCode 变成非 2xx,但返回体里的业务信息反而容易被忽略。
3.2 SpringBoot 上传参数:文件大小、超时和线程池
小程序拍照上传的图片大小通常在 1MB 到 5MB 之间,如果不限制,用户可能传原图,导致上传耗时过长。我在 application.yml 里的配置如下:
spring:
servlet:
multipart:
max-file-size: 5MB
max-request-size: 6MB
mvc:
async:
request-timeout: 10000
max-file-size 限制单文件大小为 5MB,超过直接返回 413; max-request-size 限制整个请求体大小。 async.request-timeout 是异步请求的超时时间,这个参数在识别场景很关键,因为 ONNX 推理如果遇到大图片预处理耗时较长,可能会导致连接挂起。
还要注意 spring.servlet.multipart 和旧版 spring.http.multipart 的区别,SpringBoot 2.x 之后配置前缀是 spring.servlet.multipart ,老资料里写的 spring.http.multipart 在 SpringBoot 2.0+ 已经失效。
3.3 接小程序端的三个偏好参数:name、timeout、header
小程序端 wx.uploadFile 的代码,我一般这样写:
wx.chooseMedia({
count: 1,
mediaType: ['image'],
sourceType: ['album', 'camera'],
success(res) {
const tempFilePath = res.tempFiles[0].tempFilePath;
wx.uploadFile({
url: 'http://localhost:8080/api/classify',
filePath: tempFilePath,
name: 'file',
timeout: 10000,
success(uploadRes) {
const data = JSON.parse(uploadRes.data);
if (data.code === 0) {
wx.setStorageSync('lastCategory', data.category);
} else {
wx.showToast({ title: data.message, icon: 'none' });
}
},
fail() {
wx.showToast({ title: '网络异常,请重试', icon: 'none' });
}
});
}
});
name: 'file' 必须和后端 @RequestParam("file") 保持一致,这是最常见的小程序联调报错点。 timeout: 10000 是小程序端上传超时,和后端 async.request-timeout 对应,两端都设置,避免任何一端无限制等待。
3.4 本地联调工具:curl 一条命令验证接口
在开发阶段,我不用小程序反复点,直接用 curl 验证后端:
curl -X POST http://localhost:8080/api/classify \
-F "file=@/Users/me/test_bottle.jpg" \
-w "\nHTTP %{http_code}, total %{time_total}s\n"
返回结果类似:
{"code":0,"label":0,"category":"可回收物","costMs":35}
costMs 超过 200ms 时就需要检查是否图片过大或模型没有 Warmup。这个字段留着,给答辩演示时展示“识别耗时只有几十毫秒”,比口头解释有说服力。
4. 小程序识别页的加载体验:动态标题与加载页改造
4.1 识别流程的三阶段状态管理
小程序页面不能像普通 Web 页面那样随意管理状态,拍照、上传、识别这三个阶段如果状态切换不及时,会出现用户重复点击、上传了但不知道在等什么的问题。我把页面状态拆成三个: idle (空闲)、 uploading (上传中)、 done (完成)。
Page({
data: {
status: 'idle',
imagePath: '',
category: '',
costMs: 0
},
startRecognize() {
if (this.data.status === 'uploading') return;
this.setData({ status: 'uploading' });
// 调用 wx.uploadFile
}
});
status === 'uploading' 时按钮置灰,防止用户重复提交。这个状态管理看起来简单,但如果不做,用户快速点击两次会发出两个请求,后端每个请求都会跑一次推理,浪费资源还容易导致页面数据错乱。
4.2 修改刚进入的加载页面:用骨架屏代替空白
“修改刚进入的加载页面”是搜索里的高频词,放到识别场景里就是:用户选择图片后,到后端返回结果之间,页面不能白屏。最简单的做法是给识别结果区域做一个骨架屏,或者用一张遮罩图加文案。
wx.showLoading({
title: '识别中...',
mask: true
});
mask: true 表示显示遮罩层,防止用户点击穿透。但 showLoading 的样式比较单调,我一般会在页面上放一个真实的预览图,让用户看到自己选的图片已经就位,同时在图片上叠加一个加载动画,这样比纯 loading 文案的体验好很多。用 CSS 动画实现:
.scanning-overlay {
position: absolute;
top: 0;
left: 0;
right: 0;
bottom: 0;
background: linear-gradient(
180deg,
transparent 0%,
rgba(255, 255, 255, 0.3) 50%,
transparent 100%
);
animation: scan 1.5s linear infinite;
}
视觉上是一条光线在图片上反复扫过,用户能感知到“正在识别”。注意动画帧率,用 transform 或 background-position 实现,避免操作 layout 属性造成卡顿。
4.3 小程序动态设置标题:按识别结果设置导航栏
识别完成后,页面标题如果一直叫“垃圾分类识别”就太浪费了。在小程序里可以用 wx.setNavigationBarTitle 动态修改,让标题直接显示结果:
if (data.code === 0) {
wx.setNavigationBarTitle({
title: data.category + ' · 识别结果'
});
}
这里有个细节: wx.setNavigationBarTitle 的 title 最长 8 个汉字左右,超过会截断。所以我在后端返回的 category 直接用“可回收物”这类短词,不用“可回收垃圾”这种会被截断的长文案。动态标题的好处不只是好看,用户截图分享时,标题栏和结果一起截进去,信息完整度更高。
4.4 原生小程序还是 uniapp:我的选择
选原生小程序还是 uniapp,取决于你有没有多端发布的需求。uniapp 的好处是一套代码编译到微信、支付宝、H5 等多个平台,社区里 uniapp微信小程序 的资料非常多;但坏处是打包体积大,且原生组件的一些细节行为在跨端时会有差异。
我做这个项目选的是原生微信小程序,理由很简单:只需要跑在微信上,不需要 H5 和 App;原生 wx.uploadFile 在上传大图时行为更稳定;页面只有两三个,迁到 uniapp 的成本也不高。如果你有 H5 演示的需求,可以用 uniapp,但要注意在 manifest.json 里配好 mp-weixin 的 appid ,否则真机预览会报错。
5. 训练数据迭代与 SpringBoot 参数排错:从 60% 到 90% 的实测路径
5.1 数据组织方式:按目录名做标签
垃圾分类数据集的常见组织方式是每个类别一个文件夹:
data/
可回收物/
bottle_001.jpg
paper_002.jpg
厨余垃圾/
banana_peel_001.jpg
有害垃圾/
battery_001.jpg
其他垃圾/
tissue_001.jpg
PyTorch 的 ImageFolder 可以直接按目录名生成标签。注意目录名的顺序决定了训练后数字标签的映射顺序,我建议在训练脚本里把类别名输出到一个文本文件,避免 SpringBoot 端写死索引:
with open("classes.txt", "w", encoding="utf-8") as f:
for cls in dataset.classes:
f.write(cls + "\n")
SpringBoot 加载这个文件,按行号取类别名,这样后端代码不会受到类别变动的影响。
5.2 解决准确率不达标的三个步骤
第一版模型如果准确率低于 60%,一般不是模型结构的问题,而是训练策略的问题。我按顺序检查三个环节:
第一,类别样本数是否均衡。可回收物如果只有 50 张,而厨余垃圾有 300 张,模型会倾向把模糊图片分到厨余。对少样本类别做数据增强,例如随机旋转 15 度、水平翻转、亮度扰动,会比直接加训练轮数更有效。
第二,输入图像是否包含过多背景。垃圾桶旁边拍的照片,背景可能占了大半张图,模型学到的可能是背景特征。训练时可以用随机裁剪加缩放,强制模型关注物体本身:
from torchvision import transforms
train_transform = transforms.Compose([
transforms.RandomResizedCrop(224, scale=(0.6, 1.0)),
transforms.RandomHorizontalFlip(),
transforms.ColorJitter(brightness=0.2, contrast=0.2),
transforms.ToTensor(),
transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225])
])
第三,阈值设置。Softmax 输出的是概率分布,如果所有类别概率都在 0.4 以下,说明模型对这张图没有把握。后端可以加一个阈值判断,低于阈值返回“无法识别”,而不是强行给一个错误分类:
float maxProb = output[0][label];
if (maxProb < 0.6) {
// 返回 code=2,提示用户重拍
}
5.3 SpringBoot 版本太高:javax 与 jakarta 命名空间迁移
搜索词里“springboot版本太高”出现频率很高,说的就是 SpringBoot 3.x 带来的命名空间迁移。SpringBoot 3.x 基于 JDK 17,把原来的 javax.servlet 改成了 jakarta.servlet ,导致大量老项目在升级时编译报错。
我做这个项目时选的 SpringBoot 3.2 + JDK 17,代码里 import javax.annotation.PostConstruct 已过时,应该用:
import jakarta.annotation.PostConstruct;
还有一个容易踩的坑是 javax.validation 也会迁到 jakarta.validation 。如果你在 IDEA 里用 Spring Initializr 创建项目,默认版本可能就是 3.x,老教程里基于 javax 的代码需要手动替换。如果你更熟悉 SpringBoot 2.7,直接选 2.7.18 也能满足这个项目需求,二者在功能上对单接口的识别服务几乎没有差别。
| 对比项 | SpringBoot 2.7 | SpringBoot 3.x |
|---|---|---|
| JDK 要求 | 8/11/17 | 17+ |
| Servlet 命名空间 | javax.servlet | jakarta.servlet |
| 注解校验 | javax.validation | jakarta.validation |
| 依赖兼容性 | 兼容老组件 | 部分组件需升级 |
5.4 本地实测与性能数据记录
模型和接口都通起来后,我建议建一个实测记录表,每隔几轮训练记录一组数据。表格放到项目 README 里,答辩时可以直接展示:
| 输入图片特征 | 推理耗时(ms) | 分类结果 | 是否准确 |
|---|---|---|---|
| 干净的矿泉水瓶 | 28 | 可回收物 | 是 |
| 沾了油的塑料餐盒 | 45 | 可回收物 | 否 |
| 昏暗灯光下的香蕉皮 | 33 | 厨余垃圾 | 是 |
这个表的用处不只是给答辩看,更是帮你判断模型的问题集中在哪类图片上。如果“沾了油的塑料餐盒”总是误判,说明数据里缺少这种特征样本,补充数据时就有方向。
6. 答辩演示前三个小技巧:curl 回归、断网兜底与冷启动预热
6.1 一个 curl 回归脚本,避免答辩现场翻车
答辩前我习惯准备一个回归脚本,把测试图片和期望分类写进去,一键跑完:
#!/bin/bash
BASE_URL="http://localhost:8080"
check() {
local img=$1
local expect=$2
local result=$(curl -s -X POST "$BASE_URL/api/classify" -F "file=@$img")
local category=$(echo "$result" | sed 's/.*\"category\":\"\([^\"]*\)\".*/\1/')
if [ "$category" == "$expect" ]; then
echo "$img -> PASS"
else
echo "$img -> FAIL, got $category"
fi
}
check "testdata/bottle.jpg" "可回收物"
check "testdata/banana.jpg" "厨余垃圾"
脚本里的 sed 解析 JSON 只适用于返回结构固定的接口,如果你后面加了字段,可以用 python3 -m json.tool 或 jq 替代。重点是现场演示前跑一次,确保模型版本和代码版本是匹配的。
6.2 断网兜底:小程序离线识别提示
演示现场的最大风险是网络抖动,SpringBoot 服务跑在本地,但手机小程序连的 Wi-Fi 可能访问不到本地端口。我会在手机和电脑连接同一个手机热点时,把 url 改成电脑的局域网 IP,例如 http://192.168.1.5:8080/api/classify 。
小程序里还要做一层兜底: wx.uploadFile 的 fail 回调里提示用户检查网络,而不是任由 loading 一直转。如果演示时间充裕,我会在备用手机上下载好两张测试图,切到飞行模式后直接演示“断网提示”,反而显得项目对异常处理有考虑。
6.3 冷启动预热:让第一次请求不慢
SpringBoot 启动后,ONNX Runtime 的 Session 虽然已经在 @PostConstruct 里创建好了,但第一次推理时 JIT 编译和内存分配仍然会让耗时飙高。我一般在监听 ApplicationReadyEvent 时跑一次预热:
@Component
public class ModelWarmupRunner implements ApplicationRunner {
private final GarbageClassifyService classifyService;
private final ImagePreprocessService preprocessService;
public ModelWarmupRunner(GarbageClassifyService classifyService, ImagePreprocessService preprocessService) {
this.classifyService = classifyService;
this.preprocessService = preprocessService;
}
@Override
public void run(ApplicationArguments args) throws Exception {
byte[] dummy = new byte[224 * 224 * 3];
float[][][] pixels = preprocessService.process(dummy);
long start = System.currentTimeMillis();
int label = classifyService.classify(pixels);
System.out.println("warmup done, label=" + label + ", cost=" + (System.currentTimeMillis() - start) + "ms");
}
}
ApplicationRunner.run 在 SpringBoot 启动完成后被调用,dummy 图片的像素值全为 0 不影响预热目标。这样答辩演示第一张图识别时,耗时就是正常水平,不会出现“第一次 800ms,之后 40ms”这种需要解释的数据波动。
线下验收时我还会用 curl -w 测一次完整请求的总耗时,目标值压在 150ms 以内,包含图片解码、预处理、模型推理和 JSON 序列化。超过这个值就回到第 2 章检查 setIntraOpNumThreads 的配置,或者把上传图片尺寸在小程序端先压缩到 800px 宽再上传。
更多推荐
所有评论(0)