简介这是一份面向微信小程序开发者和深度学习初学者的物体识别实战资源包涵盖小程序前端、腾讯云轻量服务器、Django后端及YOLOv3模型部署适合希望从零搭建并串联完整识别系统的读者。压缩包共3832个文件约414.62MB以JavaScript/TypeScript代码文件为主辅以Markdown文档、JSON配置、license许可等js/ts文件对应前后端逻辑md文件提供使用说明json文件保存配置信息既包含小程序逻辑与Node.js依赖也包含YOLOv3模型及微信开发者工具安装程序目录结构清晰便于按模块查阅。目前已有481人学习下载。读者可从中掌握小程序界面开发、云服务器配置、Anaconda环境管理、Django接口编写和YOLOv3模型部署等关键技能理解前后端数据交互与模型调用流程并借助完整目录结构快速定位所需内容。1. 小程序物体识别开发先搞定腾讯云轻量云服务器这套地基做小程序物体识别很多人第一步就卡在服务器搭建上。本地调试好好的一部署到云端就各种玄学问题其实多半不是代码问题而是服务器的系统镜像、Python 环境、依赖版本没配对。尤其是用腾讯云轻量云服务器做后端它的默认镜像环境和本地 Mac 或 Windows 差异很大稍不注意就会在模型加载、API 调用上报错。这套环境我前后帮人排过不少坑核心就是先把服务器选对、环境装稳、再让小程序能真正调通云端接口。无论你是刚入门的小程序开发者还是准备把物体识别 Demo 做成正经服务的熟手这篇笔记能让你从选服务器一路走到接口验证跑通。2. 选型与准备轻量云服务器、系统镜像、基础环境2.1 为什么选腾讯云轻量云服务器腾讯云轻量云服务器是一个很务实的选择尤其是针对小程序后端这类中小型负载。它不像云服务器 CVM 那样有复杂的网络和磁盘配置项创建实例时直接选好套餐就行CPU、内存、带宽、流量包都是打包好的。对于物体识别这种需要跑 Python 推理服务的场景2 核 4G 的套餐基本够用如果模型稍微大一点比如用 YOLO 系列或者 EfficientNet建议直接上 4 核 8G否则并发一上来 CPU 直接打满接口延迟会非常明显。轻量云服务器还有个好处是自带独立的公网 IP不用像传统方式那样额外绑定弹性 IP。小程序端要求服务器域名必须备案且走 HTTPS轻量云的控制台里能直接配置防火墙规则把端口放行逻辑做得比 CVM 简单直接。第一次用的话这种低门槛会省掉很多网络层面的麻烦。2.2 系统镜像选择Ubuntu 22.04 LTS 是省心之选创建服务器时系统镜像我建议选 Ubuntu 22.04 LTS不要选 CentOS也不要选带宝塔面板的镜像。原因很简单腾讯云轻量服务器的 CentOS 镜像在 2024 年已经停止维护很多软件源失效装 Python 依赖时容易 404而宝塔面板虽然方便但它会预装一套自己的 Python 和 Nginx后续部署时容易和我们的环境冲突排查起来非常难受。Ubuntu 22.04 LTS 自带 Python 3.10这个版本对 PyTorch、TensorFlow 以及常见的物体识别库兼容性都很好。选好镜像后在控制台重置密码然后用 SSH 登录服务器第一步先把系统包更新到最新状态。登录方式我一般用终端直接 ssh root服务器IP如果服务器是密钥登录记得在创建时把密钥下载保存好。2.3 基础依赖安装编译工具与系统库物体识别服务离不开一些系统级的依赖库尤其是 OpenCV 和图像处理相关的库。Ubuntu 22.04 默认环境比较干净需要手动安装编译工具链和图像库。这里不要偷懒跳过后面很多诡异的报错都是因为缺了这些底层库。apt update apt upgrade -y apt install -y build-essential cmake git wget curl apt install -y libgl1 libglib2.0-0 libsm6 libxext6 libxrender-dev第一行是更新软件源和系统包第一次登录服务器必做。第二行安装的是编译工具像 cmake 和 build-essential后续如果某些 Python 包需要从源码编译这些都是前提。第三行是 OpenCV 等图像处理库的运行时依赖缺了 libgl1 的话import cv2 时大概率会报 libGL.so.1 找不到的错误这是最常见的一个坑。2.4 Python 虚拟环境准备不要污染系统 Python很多人图省事直接 pip install 到系统 Python 里结果把系统环境搞得一团糟。我一般会给物体识别服务单独建一个虚拟环境这样不同项目的依赖互相不干扰出了问题直接删掉重建也很干净。腾讯云轻量服务器上我习惯用 venv不需要额外安装 virtualenv 之类的工具。apt install -y python3-venv python3-pip mkdir -p /opt/object-recognition cd /opt/object-recognition python3 -m venv venv source venv/bin/activate pip install --upgrade pip setuptools wheel创建虚拟环境后所有依赖都装在这个 venv 里。注意激活虚拟环境后命令行提示符前面会出现 (venv) 字样看到这个再执行 pip install 才是装进虚拟环境。如果没看到说明激活失败检查一下是否在目标目录下执行了 source 命令。3. 搭建物体识别后端框架选择、模型准备、API 服务3.1 物体识别框架与依赖清单物体识别服务端常见的方案有几种直接用 TensorFlow Object Detection API、用 PyTorch 加载 YOLO 模型、或者用百度的 PaddleDetection。考虑到部署简便性和社区资料丰富程度我这里用的是 PyTorch 配合 YOLOv5 的方式。YOLOv5 的代码仓库结构清晰weights 文件下载方便而且对 CPU 推理也有不错的优化。依赖安装直接进虚拟环境然后按照 PyTorch 官方给的命令装对应版本。服务器没有 GPU所以装 CPU 版即可千万不要装 CUDA 版否则 torch 会去找 NVIDIA 驱动然后报错。pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu pip install opencv-python pillow numpy pip install flask flask-cors gunicornCPU 版的 torch 和 torchvision 必须一起装版本要匹配。如果分开装很容易出现 torch 2.x 配上 torchvision 0.15 之类的不兼容组合加载模型时直接报错。Flask 用作 API 框架gunicorn 是生产环境的 WSGI 服务器比 Flask 自带的开发服务器稳定很多并发能力也不在一个量级。3.2 下载 YOLOv5 仓库与模型权重YOLOv5 仓库本身在 GitHub 上直接 clone 下来然后用里面的依赖文件安装剩余包。模型权重建议下载 yolov5s.pt这是 smallest 版本CPU 上做物体识别速度相对可以接受精度对于大多数 Demo 和中小型项目也够用。如果对精度要求高可以换 yolov5m但 CPU 推理时间会明显变长。cd /opt/object-recognition git clone https://github.com/ultralytics/yolov5.git cd yolov5 pip install -r requirements.txt wget -P weights/ https://github.com/ultralytics/yolov5/releases/download/v6.2/yolov5s.pt这里要注意requirements.txt 里会包含 torch 的安装项如果之前已经装好了 CPU 版 torchpip 在安装时可能检测到已满足要求就不会重复装但有些情况下它会试图把 torch 替换成最新版导致 CPU 版被覆盖。为避免这种情况可以在安装 requirements.txt 之前先查看一下里面是否对 torch 有版本限定如果有把它注释掉再安装。3.3 编写 Flask 接口接收图片并返回识别结果模型准备好后需要一个 Web 接口来接收小程序上传的图片然后调用 YOLO 模型推理把识别结果返回给前端。这里我写一个简单的 Flask 应用接口路径设计为 /detect接收 POST 请求请求体里带图片文件返回 JSON 格式的检测结果包含物体类别、置信度和坐标框。import base64 import io import cv2 import numpy as np import torch from flask import Flask, request, jsonify from PIL import Image app Flask(__name__) model torch.hub.load(/opt/object-recognition/yolov5, custom, path/opt/object-recognition/yolov5/weights/yolov5s.pt, sourcelocal, force_reloadFalse) model.conf 0.4 model.iou 0.45 app.route(/detect, methods[POST]) def detect(): file request.files.get(image) if file is None: return jsonify({code: 400, msg: missing image}), 400 img_bytes file.read() img Image.open(io.BytesIO(img_bytes)).convert(RGB) img_array np.array(img) results model(img_array) detections [] for *box, conf, cls in results.xyxy[0].tolist(): detections.append({ class: model.names[int(cls)], confidence: round(conf, 4), bbox: [round(x, 2) for x in box] }) return jsonify({code: 0, data: detections}) if __name__ __main__: app.run(host0.0.0.0, port5000)代码里的 torch.hub.load 是关键sourcelocal 表示从本地加载仓库而不是每次去 GitHub 拉取这样离线也能用。path 参数直接指向下载好的权重文件。conf 和 iou 分别控制置信度阈值和 NMS 阈值conf 设置太低会出现大量误检框建议 0.3 到 0.5 之间调优。接口接收 image 字段前端小程序端用 wx.uploadFile 上传时字段名要对应上。3.4 用 gunicorn 启动服务并绑定公网端口Flask 自带的开发服务器只能用于本地调试真正对外提供服务要用 gunicorn。gunicorn 支持多 worker 并发处理请求对小程序端的并发上传更友好。启动参数里绑定 0.0.0.0 表示监听所有网卡这样腾讯云的公网 IP 才能访问到。cd /opt/object-recognition/yolov5 source /opt/object-recognition/venv/bin/activate gunicorn -w 2 -b 0.0.0.0:5000 app:app这里 app:app 指的是 app.py 文件里的 app 实例。如果文件命名不是 app.py对应修改前缀。worker 数量设置为 2 比较稳妥轻量服务器 CPU 核心数有限开太多 worker 反而会因为 GIL 和上下文切换导致性能下降。启动后终端会显示监听地址看到 listening 字样就说明服务起来了。注意必须先在轻量云控制台的防火墙规则中放行 5000 端口否则外部访问会超时。4. 小程序端接入域名配置、HTTPS 证书、上传图片接口4.1 小程序合法域名与 HTTPS 要求微信小程序有一个硬性要求request 和 uploadFile 的域名必须是 HTTPS且域名需要在小程序管理后台配置到白名单里。开发阶段可以在开发者工具里勾选「不校验合法域名」但真机预览时这个选项不生效。所以服务器端必须配好 HTTPS否则小程序端调用接口时直接报 url not in domain list 或者 SSL certificate error。腾讯云轻量云服务器本身不提供 HTTPS 证书托管需要单独申请 SSL 证书。腾讯云有免费的 DV 证书可以申请有效期一年申请后下载 Nginx 格式的证书文件上传到服务器再用 Nginx 做反向代理把 443 端口的请求转发到 gunicorn 的 5000 端口。4.2 安装 Nginx 并配置反向代理Nginx 在这里的作用是终止 SSL 连接再把请求转发给后端的 gunicorn。这样后端 Flask 应用不用处理证书逻辑保持简单。同时 Nginx 也能对请求体大小做限制小程序上传图片一般不会太大设置 10m 足够。apt install -y nginx安装完成后编辑 /etc/nginx/sites-available/default 或者新建一个配置文件这里直接改默认站点配置server { listen 443 ssl http2; server_name yourdomain.com; ssl_certificate /etc/nginx/ssl/yourdomain.crt; ssl_certificate_key /etc/nginx/ssl/yourdomain.key; client_max_body_size 10m; location / { proxy_pass http://127.0.0.1:5000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } } server { listen 80; server_name yourdomain.com; return 301 https://$host$request_uri; }把 yourdomain.com 替换成自己备案通过的域名证书文件路径对应放好。80 端口配置了跳转所有 HTTP 请求自动转到 HTTPS避免用户访问到不带证书的端口。配置完成后执行 nginx -t 检查语法然后 systemctl reload nginx 让配置生效。提示如果小程序端提示证书无效检查证书文件是否包含完整的证书链。某些 DV 证书下载后包含 ca-bundle 文件需要把主证书和中间证书拼接在一起。4.3 小程序端 wx.uploadFile 调用示例小程序端代码相对简单核心是用 wx.uploadFile 把图片文件 POST 到服务器接口。注意 header 里不用手动设置 Content-Typewx.uploadFile 会自动生成带 boundary 的 multipart 表单数据后端 Flask 直接用 request.files.get 就能取到文件。wx.chooseMedia({ count: 1, mediaType: [image], sourceType: [album, camera], success(res) { const tempFilePath res.tempFiles[0].tempFilePath; wx.uploadFile({ url: https://yourdomain.com/detect, filePath: tempFilePath, name: image, success(uploadRes) { const data JSON.parse(uploadRes.data); if (data.code 0) { console.log(识别结果, data.data); } }, fail(err) { console.error(上传失败, err); } }); } });name 字段必须填写 image和 Flask 后端 request.files.get(image) 对应大小写也要一致。如果后端收不到文件先看 Nginx 日志和 gunicorn 日志大部分情况是字段名不匹配或请求被防火墙拦截。返回的数据是 JSON 字符串需要 JSON.parse 之后才能拿到对象数组。识别结果里每个对象的 class 字段就是物体类别名称。4.4 大模型与并发场景的服务器参数调优如果识别服务不止一个人用或者图片分辨率较高需要调整一些参数来避免服务崩溃。gunicorn 的 worker 数和超时时间是最核心的。CPU 推理本身耗时较长默认的 30 秒超时经常不够用需要把 timeout 调大同时通过线程模式来提升吞吐量。gunicorn -w 2 --threads 4 --timeout 120 -b 0.0.0.0:5000 app:app--threads 4 表示每个 worker 开启 4 个线程这样同一个 worker 在处理一个耗时推理时其他线程还能接收新请求。timeout 120 表示 worker 超过 120 秒没有响应会被 gunicorn 杀掉重启对物体识别这种耗时任务来说更安全。如果图片特别大或者模型推理超过 30 秒默认配置下会出现 502 或 worker timeout 错误这个参数就是专门解决这个问题的。5. 排查与避坑腾讯云轻量服务器上最常见的五个问题5.1 报 libGL.so.1 找不到现象pip 安装 opencv-python 成功但 import cv2 时提示 ImportError: libGL.so.1: cannot open shared object file。原因Ubuntu 22.04 最小化安装没有包含 OpenCV 所需的 OpenGL 运行库pip 安装的 opencv-python 是 prebuilt wheel动态链接到系统库系统缺了就报错。解决执行 apt install -y libgl1 libglib2.0-0 libsm6 libxext6 libxrender-dev然后在虚拟环境里验证 import cv2 是否正常。这个库缺失是最常见的翻车点很多人以为是 opencv 没装好重装好几遍都没用其实是系统库的事。5.2 小程序端请求报域名不在合法列表现象真机上调用接口提示 request 的 url not in domain list开发者工具里勾选了不校验合法域名能通但手机就是不行。原因微信小程序对 request 和 uploadFile 的域名有严格限制必须是 HTTPS 且在小程序管理后台配置为业务域名。开发阶段的忽略选项只对开发者工具有效。解决登录小程序管理后台在开发管理 - 开发设置 - 服务器域名里添加 https://yourdomain.com。注意域名不能带路径不能带端口必须是标准 443 端口。如果小程序涉及多个环境开发版、体验版、正式版可以配不同域名但要分别配置。5.3 gunicorn 启动失败提示 ModuleNotFoundError现象执行 gunicorn app:app 后报 ModuleNotFoundError: No module named app但 Flask 直接 python app.py 能跑。原因gunicorn 启动时的当前工作目录不在 app.py 所在目录或者是没有激活虚拟环境就启动了 gunicorn导致 gunicorn 解析不到模块路径。解决先确认在 /opt/object-recognition/yolov5 目录下执行且已经 source venv/bin/activate。用 which gunicorn 检查是否指向虚拟环境路径如果指向系统路径说明激活失败重新激活后再启动。还有一个细节gunicorn 默认不会递归查找模块如果 app.py 在子目录里需要 cd 到那个目录再启动或者用 gunicorn --chdir /path/to/dir app:app。5.4 HTTPS 证书配置后小程序仍报 SSL 错误现象浏览器访问 HTTPS 域名正常但小程序端报 SSL certificate error或者提示证书链不完整。原因腾讯云申请的免费证书下载时是多个文件包括 crt 和 key但有些证书还带一个 ca-bundle 中间证书。如果只配置了域名证书没有把中间证书一起配置部分移动端系统会校验失败。解决下载证书时选择 Nginx 格式里面通常包含 .crt 和 .key 两个文件。如果 Nginx 配置后仍有问题查看证书文件内容确认是否包含 -----BEGIN CERTIFICATE----- 多段内容。缺少中间证书时把 ca-bundle 文件内容追加到 crt 文件末尾形成一个完整的证书链文件然后重载 Nginx。5.5 上传图片后接口返回 502 Bad Gateway现象小程序上传图片到服务器Nginx 返回 502查看 Nginx 错误日志显示 connect() failed (111: Connection refused) while connecting to upstream。原因gunicorn 服务可能挂了或者 Nginx 配置的 proxy_pass 端口和 gunicorn 监听的端口不一致。也可能 gunicorn 因为超时或内存不足被系统杀掉。解决用 ps aux | grep gunicorn 查看进程是否存在。如果进程不存在查看 gunicorn 日志启动时加上 --error-logfile确认崩溃原因。排查端口ss -tlnp | grep 5000 看端口是否在监听。常见情况是启动服务时用了 5001 端口但 Nginx 里写的是 5000。另外轻量服务器内存不足时gunicorn 也可能被 OOM Killer 杀掉查看 dmesg | tail 确认。6. 验证跑通从服务器回环测试到小程序真机联调全流程6.1 服务器端本地验证接口服务部署完后先不要急着打开小程序先在服务器上用 curl 做一次完整的接口测试。准备一张图片比如 cat.jpg放到服务器任意位置然后执行curl -X POST -F imagecat.jpg http://127.0.0.1:5000/detect因为是在服务器本机测试不需要走 HTTPS直接访问 gunicorn 监听的端口就行。正常返回结果是类似这样的 JSON{code:0,data:[{class:cat,confidence:0.8876,bbox:[120.3,45.2,482.1,369.7]}]}这里的 confidence 是置信度越接近 1 越好。bbox 是物体框的坐标四个数字分别是左上角 x、y 和右下角 x、y。如果返回 code 400说明上传字段名不对或图片格式有问题先检查 -F 参数里的 image 部分。这一步通过说明后端模型推理和接口逻辑都是通的问题只可能出现在网络层或者小程序端。6.2 通过 HTTPS 域名测试接口本地回环测试通过后还需要测试经过 Nginx 和 HTTPS 证书的完整链路。执行下面的命令注意把域名换成自己的curl -k -X POST -F imagecat.jpg https://yourdomain.com/detect-k 参数表示跳过证书校验因为 curl 可能不信任刚刚配置的自签或免费证书。如果这一步返回结果和上一步一致说明 Nginx 反向代理、SSL 证书链路、gunicorn 后端全部正常。这里如果返回 404检查 Nginx location 配置看 proxy_pass 是否写对了路径如果返回 502回到第 5.5 节排查 gunicorn 状态。6.3 小程序开发者工具联调服务器链路通了接下来打开微信开发者工具先在小程序项目中确认 request 合法域名已经配置。开发阶段可以在详情面板里勾选「不校验合法域名、web-view业务域名、TLS 版本以及 HTTPS 证书」但要注意这只是开发调试用真机预览不能依赖这个选项。在小程序代码中调用 wx.uploadFile 上传图片成功后打 console.log 输出返回值。开发者工具的 Network 面板能看到请求的完整链路包括请求头、响应体和耗时。如果能看到正确的识别 JSON说明整个流程跑通了。此时可以把图片换成不同的物体比如杯子、手机、人等验证模型的泛化能力。6.4 真机预览与性能验收开发工具通不代表示真机没问题尤其是 HTTPS 证书链和图片上传在真机上更容易暴露问题。用开发者工具点击预览生成二维码后用手机扫码打开小程序选择相册图片或直接拍照识别。重点观察两个指标一是从选择图片到拿到识别结果的总耗时二是返回结果中置信度是否合理。CPU 推理在轻量服务器上通常需要 2 到 5 秒取决于图片大小和模型复杂度。如果耗时超过 8 秒可能需要压缩图片后再上传小程序端可以用 wx.compressImage 先把图片压到 1080px 以内一方面减少传输时间另一方面也降低服务端推理压力。6.5 日志排查的最后一道防线全部链路走完后如果还有偶发问题日志是最后的突破口。我习惯把 gunicorn 的日志单独输出到文件里方便回溯。gunicorn -w 2 --threads 4 --timeout 120 \ --access-logfile /var/log/object_recognition_access.log \ --error-logfile /var/log/object_recognition_error.log \ -b 0.0.0.0:5000 app:app访问日志记录每个请求的时间、状态码和耗时错误日志记录 Python 异常和 gunicorn 自身的错误。小程序的请求失败时先看访问日志里有没有对应记录有记录说明请求到达了后端问题在应用逻辑没记录说明请求在 Nginx 层被拦截去看 Nginx 的 error.log。从那以后我每次部署新的识别服务都强制自己先走一遍 curl 回环测试再上小程序顺序反了就容易把问题混在一起增加排查成本。这套流程你照着走一遍基本能避免大部分部署期的怪问题希望帮到你。本文还有配套的精品资源点击获取