小程序物体识别工程实践：Flask+ONNX Runtime云服务器部署指南

简介：面向从零搭建小程序物体识别应用的开发者，内容以腾讯云轻量云服务器部署为主线，覆盖前端开发、后端服务、环境管理与模型调用等完整链路，适合有一定编程基础、想贯通前后端与人工智能落地流程的学习者。压缩包共三千八百三十二个文件，大小约四百一十四兆，其中以js、ts等脚本与类型定义文件为主，涵盖前端页面逻辑与依赖包；大量md与json说明文档和配置信息便于查阅；还附带微信开发者工具安装程序及物体识别模型压缩包，方便直接复现调试。内容不仅涉及服务器创建、操作系统配置与依赖安装，还对YOLOv3目标检测网络的结构和多尺度识别原理进行说明，并展示了小程序如何发送请求、后端如何调用模型并回传识别结果，帮助读者建立全栈视野。项目目录按前端依赖、图片样本、工具程序和模型文件分层，便于按需查阅；已有四百八十一人学习下载，适合用作课程设计、毕业设计或个人实战项目的基础参考。

1. 小程序物体识别项目：拍照到 Top-5 识别结果的轻量闭环

第一次做物体识别小程序，最容易掉进去的坑就是把模型塞进手机端，结果被几十 MB 的包体积和真机内存折磨到怀疑人生。这份工程换了一条更务实的路：小程序端只负责拍照、上传和渲染结果，识别推理全部放在腾讯云轻量云服务器上，CPU 跑 ONNX 模型也能稳定返回 Top-5 标签和置信度。你拿到的是一个完整闭环——从微信里选一张图，到服务端返回“这是什么、概率多少”，前后端代码都能直接跑。适合正在做图像类小程序、又不想被端侧推理细节拖住的全栈和前端开发，也可以作为把本地模型迁移到云服务器的现成参考。

2. 整体架构与目录结构：一次识别请求从拍照到返回标签的完整链路

动手跑之前，先把三段式链路和工程边界弄清楚。这份工程刻意把前后端拆成两个独立目录，互不引用代码，接口是它们唯一的契约。这样做的直接好处是：服务端能用 curl 单独验证，小程序端切到真机时只关心上传和渲染，排查问题时的边界非常清楚。

2.1 三段式链路：小程序端、服务端、推理模型各管一段

一次完整识别的链路如下：

1. 小程序端调用 wx.chooseMedia 拍照或从相册选图，拿到本地临时文件路径；
2. 通过 wx.uploadFile 以 multipart/form-data 方式 POST 到服务端的 /upload 接口；
3. Flask 接口接收图片，先做格式和大小校验，再保存到 uploads 临时目录；
4. predict.py 用 ONNX Runtime 加载本地模型，对图片做预处理后推理，拿到 1000 类概率并排序出 Top-5；
5. 接口按 { code, msg, data } 结构返回标签和置信度，小程序端渲染成条形图，同时服务端删除临时文件。

链路里前端不直接接触模型，模型也不关心用户是哪台手机。当需要换识别能力时，只需要改服务端一个文件，小程序端一行不动，这个解耦在二次开发阶段价值最高。

2.2 目录结构：两个子工程，一条接口契约

工程根目录下分为 miniprogram 和 server 两个子工程，核心文件如下表所示。

server 是一个标准 Python 工程，miniprogram 是一个原生小程序工程。两者的契约只有两个接口路径和一套 JSON 格式，没有共享类、没有共享工具函数，部署时可以各自独立发布。我比较推荐这种结构：后期如果要把模型换成 GPU 推理服务，后端可以整体替换，小程序端完全无感。

2.3 技术选型：为什么是 Flask + ONNX Runtime + 原生小程序

识别引擎优先用自建 ONNX 模型而不是直接调平台图像识别服务，主要考虑三个场景：离线可运行、模型可替换、请求没有额外成本。ONNX 模型是单文件部署，服务器上不需要装训练框架，CPU 环境下 ONNX Runtime 的推理速度对小流量场景足够。

Flask 的定位是轻量 HTTP 封装，真正的耗时在依赖加载和推理，选它不会成为瓶颈。部署时用 Gunicorn 接管进程管理，单机 2 核 4G 内存完全够用。小程序端选原生框架，是为了避免多一层框架对调试造成干扰；页面就一个，原生写法足够。

2.4 接口约定：先定协议，再写页面

整个项目只暴露两个接口：健康检查和图片识别。约定如下表所示。

错误时统一返回非 0 的 code，message 直接给用户可读文案。小程序端不做复杂错误判断，只根据 code 是否等于 0 决定渲染结果还是弹出 Toast，这个约定让前端逻辑保持得很薄。

2.5 资源占用估算：模型常驻内存与临时文件生命周期

整个服务跑起来后的资源模型很简单：ONNX 模型常驻内存，Gunicorn 每核一个 worker，模型会被加载两次（每个 worker 一份），2 核 4G 内存算宽裕。单张 8M 上限的 JPEG 解码成 RGB 位图峰值在 30M 左右，预处理完就释放，不会长驻。uploads 目录里的临时文件生命周期只有几秒，正常识别完立刻删除，不会持续占磁盘；真正要防的是服务进程崩溃时清理逻辑没走到，残留文件越积越多。常见做法是 main.py 启动时对 uploads 目录做一次清空，或者交给 systemd tmpfiles 清理，保证重启即干净。

3. 服务端核心实现：Flask 上传接口与 ONNX 推理的完整链路

服务端是整条链路的发动机。下面按依赖初始化、上传接口、推理封装、本地验证四步走，代码可以照着抄。

3.1 初始化依赖：用 venv 隔离环境，requirements 保持精简

进入 server 目录后，先创建虚拟环境再装依赖。requirements.txt 内容如下：

# server/requirements.txt flask gunicorn onnxruntime pillow numpy opencv-python

安装命令：

cd server python3 -m venv venv ./venv/bin/pip install -r requirements.txt

这里刻意不锁死版本号，目的是兼容不同的 Python 小版本。onnxruntime 在 CPU 上装默认包即可，不需要额外编译；opencv-python 在预处理里用来做图像形态处理时会用到，虽然 demo 里 Pillow 是主角，但保留它对后续换预处理算子有好处。如果服务器内存紧张，可以不装 opencv，推理路径只用 pillow 和 numpy。

3.2 上传接口：main.py 里的文件校验与临时清理

main.py 的完整实现如下：

# server/main.py import os from flask import Flask, request, jsonify from werkzeug.utils import secure_filename from predict import run_predict app = Flask(__name__) # 限制单次上传 8M，超出直接 413，避免超大图拖垮进程 app.config['MAX_CONTENT_LENGTH'] = 8 * 1024 * 1024 UPLOAD_DIR = './uploads' ALLOWED_EXT = {'jpg', 'jpeg', 'png', 'webp', 'bmp'} os.makedirs(UPLOAD_DIR, exist_ok=True) def allowed_file(name: str) -> bool: """只允许常见图片后缀，防上传可执行文件""" return '.' in name and name.rsplit('.', 1)[1].lower() in ALLOWED_EXT @app.route('/healthz', methods=['GET']) def health(): return jsonify(code=0, msg='ok') @app.route('/upload', methods=['POST']) def upload(): f = request.files.get('file') if f is None: return jsonify(code=1, msg='缺少 file 字段'), 400 if not allowed_file(f.filename): return jsonify(code=1, msg='不支持的图片格式'), 400 filename = secure_filename(f.filename) save_path = os.path.join(UPLOAD_DIR, filename) f.save(save_path) try: items = run_predict(save_path) finally: # 识别完立即删除，避免临时目录只增不减 if os.path.exists(save_path): os.remove(save_path) return jsonify(code=0, msg='ok', data=items) if __name__ == '__main__': # 开发阶段监听所有网卡，后续由 gunicorn 接管 app.run(host='0.0.0.0', port=8080, debug=False)

逻辑说明：接口只接受 multipart 表单，字段名固定为 file，这个字段名必须和小程序端 wx.uploadFile 的 name 参数一致。MAX_CONTENT_LENGTH 是 Flask 内置限制，超过 8M 会直接返回 413，小程序端后续也要做同样量级的压缩。secure_filename 会把上传文件名里的路径分隔符和特殊字符过滤掉，防止路径穿越。

参数含义很好记：8080 是服务内部端口，Gunicorn 只绑定 127.0.0.1 转发，不直接暴露给公网；识别完成后 finally 里做清理，哪怕模型推理抛异常，临时图片也不会残留。

3.3 推理封装：predict.py 里模型只加载一次，预处理和模型强相关

predict.py 是整个项目技术含量比较高的一个文件，实现如下：

# server/predict.py import os import numpy as np import onnxruntime as ort from PIL import Image, ImageOps # 模型和标签相对本文件路径，路径不要写死绝对路径 BASE_DIR = os.path.dirname(os.path.abspath(__file__)) MODEL_PATH = os.path.join(BASE_DIR, 'models', 'mobilenetv3.onnx') LABEL_PATH = os.path.join(BASE_DIR, 'models', 'imagenet_labels.txt') # 模块级加载一次，进程内复用；顶层加载能省掉每次请求的初始化耗时 session = ort.InferenceSession(MODEL_PATH, providers=['CPUExecutionProvider']) # 标签顺序必须和训练时一致，错一行结果全错 labels = [line.strip() for line in open(LABEL_PATH, encoding='utf-8')] def softmax(x: np.ndarray) -> np.ndarray: # 减最大值做数值稳定，防止 exp 溢出 e = np.exp(x - np.max(x)) return e / np.sum(e) def preprocess(img: Image.Image, size: int = 224) -> np.ndarray: # exif_transpose 纠正手机照片的旋转信息，否则竖拍图会被模型看反 img = ImageOps.exif_transpose(img).convert('RGB') img = img.resize((size, size)) arr = np.asarray(img, dtype=np.float32) / 255.0 # 常用图像识别模型的归一化参数，必须和导出的模型输入对齐 mean = np.array([0.485, 0.456, 0.406], dtype=np.float32) std = np.array([0.229, 0.224, 0.225], dtype=np.float32) arr = (arr - mean) / std # 从 HWC 转 CHW 并补 batch 维 return np.transpose(arr, (2, 0, 1))[None, ...].astype(np.float32) def run_predict(image_path: str, top_k: int = 5) -> list: image = Image.open(image_path) input_tensor = preprocess(image) input_name = session.get_inputs()[0].name outputs = session.run(None, {input_name: input_tensor})[0] probs = softmax(outputs[0]) idx = np.argsort(probs)[::-1][:top_k] return [ {'label': labels[i], 'confidence': round(float(probs[i]), 4)} for i in idx ]

逻辑说明：session 放在模块顶层，第一次导入模型时要加载几百毫秒到几秒，之后每次推理只是 run 一次，不会重复加载。providers 显式指定 CPUExecutionProvider，避免装了带 CUDA 的 onnxruntime 后在无 GPU 机器上报错。preprocess 里的 size、mean、std 必须和模型导出时保持一致，最常见的翻车就是换模型后忘了改归一化参数。

置信度返回的是浮点数，前端直接拿它乘 100 渲染百分比宽度。如果资源里的模型文件缺失，需要先看 server/models 目录下是否附带了转换脚本，把模型导成 ONNX 后再启动服务；这种问题在部署时比较常见，第 5 章的常见问题里单独列了处理方式。

3.4 先用 curl 验证服务端，再动小程序端

服务端启动后，先用命令行验证接口，不要直接打开开发者工具。命令如下：

# 启动（开发模式） cd server ./venv/bin/python main.py # 另开一个终端验证健康检查 curl http://127.0.0.1:8080/healthz # 上传一张本地测试图 curl -F "file=@./test.jpg" http://127.0.0.1:8080/upload

期望返回大致如下：

{"code": 0, "msg": "ok", "data": [{"label": "tabby cat", "confidence": 0.91}, {"label": "..."}]}

这一步验证通过，说明服务端链路是完整的。如果 curl 返回 400 或 500，先看终端日志：400 多为字段名或格式错误，500 多为模型文件缺失、标签表路径错误或依赖缺失。这一步做扎实了，后面接小程序端时基本一次通过。

4. 小程序端核心实现：选图上传与 Top-5 结果渲染

小程序端只做三件事：拿图、传图、展示识别结果。下面按页面骨架、选图上传、压缩降级、工程配置四块拆开讲。

4.1 页面骨架：index.wxml 里的预览区和结果条形图

识别页的 wxml 结构如下：

<!-- miniprogram/pages/index/index.wxml --> <view class="page"> <view class="actions"> <button type="primary" bindtap="chooseFromAlbum">从相册选择</button> <button bindtap="takePhoto">拍照识别</button> </view> <image wx:if="{{previewUrl}}" src="{{previewUrl}}" mode="aspectFill" class="preview"></image> <view class="result" wx:if="{{results.length}}"> <view class="result-item" wx:for="{{results}}" wx:key="label"> <text class="label">{{item.label}}</text> <view class="bar"> <view class="bar-inner" style="width: {{item.confidence * 100}}%"></view> </view> <text class="conf">{{item.confidence}}</text> </view> </view> </view>

逻辑说明：两个按钮分别对应相册选图和拍照，previewUrl 负责识别前把原图显示出来，让用户确认传的图没有传错。results 是数组，wx:for 渲染 Top-5 标签列表，每条结果包含 label、confidence 两个字段，条形图宽度直接用置信度百分比。

bar-inner 的宽度是百分比字符串，WXML 里 item.confidence 是 0 到 1 的小数，乘 100 后刚好是百分比。如果后端返回的 confidence 已经是 0 到 100，这里就不要乘 100，这个单位约定要在接口联调时先对齐。

4.2 拍照与选图：chooseMedia 参数差在哪

页面逻辑层 index.js 的核心代码如下：

// miniprogram/pages/index/index.js Page({ data: { previewUrl: '', results: [], uploading: false }, takePhoto() { // sourceType 为 camera 时调用相机，不弹相册 wx.chooseMedia({ count: 1, mediaType: ['image'], sourceType: ['camera'], sizeType: ['compressed'], success: (res) => this.upload(res.tempFiles[0].tempFilePath) }); }, chooseFromAlbum() { // sourceType 为 album 时只从相册选 wx.chooseMedia({ count: 1, mediaType: ['image'], sourceType: ['album'], sizeType: ['compressed'], success: (res) => this.upload(res.tempFiles[0].tempFilePath) }); }, upload(filePath) { if (this.data.uploading) return; this.setData({ uploading: true, results: [], previewUrl: filePath }); wx.uploadFile({ url: 'https://your-domain.com/upload', filePath, name: 'file', timeout: 30000, header: { 'X-Token': wx.getStorageSync('token') || '' }, success: (res) => { const data = JSON.parse(res.data); if (data.code === 0) { this.setData({ results: data.data }); } else { wx.showToast({ title: data.msg, icon: 'none' }); } }, fail: () => { wx.showToast({ title: '上传失败，请检查网络', icon: 'none' }); }, complete: () => { this.setData({ uploading: false }); } }); } });

逻辑说明：wx.chooseMedia 是基础库 2.10.0 之后的推荐 API，旧的 wx.chooseImage 也能用，但 chooseMedia 一次把拍照、相册、压缩策略统一了。count 固定 1，只允许单图识别；mediaType 限定 image，避免误选视频；sizeType 为 compressed，保证上传的是压缩图，边缘情况下业务层还要再压一次。

upload 里的 name 必须和服务端 request.files.get('file') 对得上，改成其他字段名两端要同时改。url 在实际部署时换成本项目第 5 章的 HTTPS 域名；本地调试可以把 url 改成 http://内网 IP:8080，同时在开发者工具里临时勾选“不校验合法域名”，这个开关只用于开发期。header 里的 X-Token 是预留的鉴权位，公开部署时建议加一层校验。

4.3 上传前的压缩与失败降级

服务端限制了 8M，多数手机拍出来的图在 2M 到 5M 之间，直接用 compressed 通常够。遇到大图或者连续拍照的场景，可以在 upload 里加一层兜底压缩：

// 超过 1M 的图先走一次压缩，质量 80 足够识别用 function ensureCompressed(filePath, maxSize = 1024 * 1024) { return new Promise((resolve) => { wx.getFileInfo({ filePath, success: (info) => { if (info.size <= maxSize) return resolve(filePath); wx.compressImage({ src: filePath, quality: 80, success: (res) => resolve(res.tempFilePath), fail: () => resolve(filePath) // 压缩失败就传原图，让服务端兜底 }); }, fail: () => resolve(filePath) }); }); }

逻辑说明：wx.compressImage 的 quality 取值范围 0 到 100，识别场景 80 已经足够，太小会丢边缘纹理。压缩失败时不要中断链路，直接传原图交给服务端限制，这个降级逻辑能避免真机上出现“相册图传不上去”的情况。如果连续多次上传失败，优先怀疑是不是超过了单个请求体大小，而不是代码逻辑。

4.4 app.json 与开发者工具配置：本地联调的开关

app.json 里需要把页面注册到位，并给网络请求设置合理超时：

{ "pages": ["pages/index/index"], "window": { "navigationBarTitleText": "物体识别", "navigationBarBackgroundColor": "#ffffff" }, "networkTimeout": { "request": 30000, "uploadFile": 60000 } }

networkTimeout 的 uploadFile 建议比 wx.uploadFile 里的 timeout 略大，因为 HTTPS 握手和慢网络下大图上传耗时都会被算进超时。本地联调阶段，开发者工具的“详情-本地设置-不校验合法域名”勾上，才能用 http://IP:8080 调试；到了真机预览和上线阶段，必须切换成第 5 章的 HTTPS 环境，否则真机上传会被微信拦截。这个拦截图经常让第一次上手的开发者误以为自己代码写错了，实际只是域名校验没过。

5. 腾讯云轻量云服务器部署与避坑：从裸机到 HTTPS 对外可访问

部署这部分踩坑最多，所以单独成章。目标是把服务端做成：开机自启、进程崩溃自动拉起、外部只能走 HTTPS 访问，并且把这期间常见的翻车点集中列出来。

5.1 服务器初始化：选型、安全组和系统依赖

腾讯云轻量云服务器选 2 核 4G 内存的配置即可，系统镜像选 Ubuntu 22.04 这类常规发行版。登录后在控制台把防火墙放行 22、80、443；8080 端口只在开发期临时放行，上线后从安全组层面收掉。

sudo apt update && sudo apt upgrade -y sudo apt install -y python3-venv python3-pip nginx git git clone <你的工程仓库地址> ~/recog cd ~/recog/server python3 -m venv venv ./venv/bin/pip install -r requirements.txt

注意 python3-venv 在精简镜像上经常没预装，不装的话创建 venv 会直接报错。克隆工程后建议先手动执行一次 ./venv/bin/python main.py，确认模型能加载、接口能通，再做守护进程；先跑通再上 systemd 能少绕很多弯。此时访问不了外网是正常的，因为 Gunicorn 还没接上。

5.2 systemd 守护 Gunicorn：挂掉能自愈，重启不丢服务

开发用的 app.run 不适合线上，进程一断服务就没了。项目一般会提供 systemd 服务文件，内容参考如下：

# /etc/systemd/system/recognize.service [Unit] Description=recognize server After=network.target [Service] User=ubuntu WorkingDirectory=/home/ubuntu/recog/server ExecStart=/home/ubuntu/recog/server/venv/bin/gunicorn -w 2 -b 127.0.0.1:8080 main:app Restart=always RestartSec=3 Environment=PYTHONUNBUFFERED=1 [Install] WantedBy=multi-user.target

sudo systemctl daemon-reload sudo systemctl enable --now recognize

参数说明：gunicorn 的 -w 2 对应两核 CPU，每核一个 worker；-b 只绑定 127.0.0.1，保证外部只能通过 Nginx 反向代理进入，不让 8080 直接暴露。Restart=always 让进程异常退出后 3 秒自动拉起，enable 是开机自启的关键，没这一步重启服务器后服务会静默消失。

5.3 Nginx 反向代理与 HTTPS：小程序合法域名的最后一环

小程序真机环境要求 uploadFile 的目标必须是 HTTPS，并且域名要提前配置到小程序后台的合法域名白名单里。Nginx 配置如下：

server { listen 80; server_name your-domain.com; return 301 https://$host$request_uri; } server { listen 443 ssl; http2 on; server_name your-domain.com; ssl_certificate /etc/nginx/ssl/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/privkey.pem; client_max_body_size 8m; location /upload { proxy_pass http://127.0.0.1:8080; proxy_read_timeout 60s; } location /healthz { proxy_pass http://127.0.0.1:8080; } }

sudo nginx -t && sudo systemctl reload nginx

两个最容易翻车的参数：client_max_body_size 默认只有 1M，不调大就等着收 413；proxy_read_timeout 默认 60 秒，网络差或模型冷加载时响应可能逼近超时，调大一点更稳。证书的获取方式多样，常见做法是用平台免费证书或 certbot 签发，签发后把证书路径换到上面的 ssl 配置里。域名和控制台安全组弄好后，把 https 域名填进小程序后台的上传合法域名列表，路径不用填，真机才真正能传图。

5.4 常见问题与排查：五类上线翻车现场

下面五条基本覆盖了从裸机到能跑最常见的坑，每条按现象、原因、解决三个步骤记录。

1. 真机上传报错“不在以下合法域名列表中”。现象：开发者工具里正常，一上真机就失败；原因：小程序对合法域名做了强制校验，要求 HTTPS 且域名必须在后台白名单里，IP 直接访问会被拦截；解决：绑定域名、配置证书、把 https 地址填进 uploadFile 合法域名。本地调试走“不校验合法域名”开关，上线前必须关掉。

2. 上传大图返回 413 Request Entity Too Large。现象：小图能识别，拍照原图必挂；原因：Nginx 默认 client_max_body_size 为 1M，Flask 又限制了 8M，两头不一致；解决：Nginx 配 8m，Flask 的 MAX_CONTENT_LENGTH 保持 8M 或更大，同时在小程序端压缩后再传。

3. curl 通、浏览器通，小程序真机不通。现象：同一张图 curl 返回正常结果，真机一直超时；原因：证书链不完整、域名校验没通过、或后台合法域名没配置，任一个没满足都会被拦；解决：按 5.3 的配置依次核对，用手机浏览器先打开健康检查接口，能出 JSON 再怀疑小程序端。

4. 模型加载耗尽内存或启动极慢。现象：systemd 启动后看到日志里 RepeatedCrashReport，或者进程起不来；原因：ONNX 模型过大而服务器内存太小，或模型加载逻辑放在了每个 worker 初始化阶段；解决：选 2G 以上内存的机型，把 session 加载放在模块顶层而不是函数内部，也可以先量化压缩模型再上服务器。

5. 换服务器后识别结果全错。现象：本地测试正常，换到云服务器后 Top-1 完全不对；原因：标签表路径用了绝对路径，或者 labels 行序和模型输出不对齐；解决：路径改成相对 predict.py 的 BASE_DIR 拼接，并在部署后先用一张已知图片 curl 验证 Top-5，再允许接小程序。

这条排查清单建议直接贴在 README 里，团队内部遇到同类问题先翻一遍，能省掉大量重复沟通。

6. 二次开发与改造：把它变成可交付的识别服务

跑通只是第一步，多数人拿到这份工程后还想换模型、加鉴权、接自己的业务。最后给两个改造方向和一个验证习惯。

6.1 换识别模型：预测代码只改三处

替换模型时，把 server/models 下的模型文件和标签表替换，然后同步修改 predict.py 的 MODEL_PATH、LABEL_PATH 和 preprocess 里的输入尺寸与归一化参数。换完模型不要直接上线，先用 curl 验证一张标注过的图：

curl -F "file=@./known_cat.jpg" http://127.0.0.1:8080/upload

对比返回的 Top-1 是否符合预期再继续。标签行序和模型输出的映射是模型服务最容易错的地方，先验证后上线能避开绝大多数事故。

6.2 加识别缓存与防抖：应对重复上传

同一张图被反复识别是常见场景，可以在服务端按图片 MD5 加一层结果缓存，识别过的不再走模型推理，QPS 压力立刻小很多。小程序端给上传按钮加 uploading 防抖，已经在传图时置灰按钮，避免用户在慢网络下疯狂点击。

从这次拆工程里我最大的收获是验证顺序：改完模型、改完配置，强制走一遍“冷启动 → curl 单图 → 真机上传”三连。这个习惯让我少踩了至少一半部署坑，比什么调试技巧都值钱。希望帮到你。

本文还有配套的精品资源，点击获取