简介这是一份面向人工智能与微信小程序开发初学者的实战型演示项目源码适合希望把AI能力落地到小程序端、或需要完整项目练手的开发者参考。项目围绕语音交互与智能对话场景展开涵盖首页、关于、个人中心、待办事项等页面模块并包含消息组件与录音、播放等工具脚本可帮助读者理解小程序页面结构、组件通信与AI接口调用的基本流程。压缩包共59个文件约1.36MB其中23个png与4个gif、2个jpg构成图标与动效素材12个js与5个json负责逻辑与配置7个wxss、5个wxml搭建界面样式与结构另有1个md说明文档整体轻量、便于快速导入微信开发者工具运行。目前已有242人学习浏览适合作为课程设计、毕业项目或自学练手的参考模板读者可从中获取页面组织方式、录音与语音播放实现思路以及AI演示模块的接入参考并在此基础上二次开发。1. 人工智能实战微信小程序demo.zip一个压缩包背后能跑通什么拿到「人工智能实战微信小程序demo.zip」这个标题的人多半不是想听概念而是想知道解压之后到底能不能跑、跑起来要改哪几行、模型放哪、真机预览会不会白屏。我见过太多人卡在第一步——把压缩包解压到中文路径然后开发者工具报一堆找不到模块的错最后怀疑人生。这个标题真正指向的是一套「微信小程序前端 AI 推理后端」的最小闭环小程序负责拍照、选图、上传、展示结果后端负责跑模型、返回结构化数据。它适合两类人一类是想把本地训好的模型塞进小程序里做演示的算法同学另一类是接了个「AI 识别」需求但不知道从哪下手的前端。下面我按自己复现过多次的路径把选型、目录、参数、坑一条条拆开讲。2. 先定架构小程序端到底该不该直接跑模型2.1 三种常见架构的取舍做 AI 小程序第一件事不是写代码而是决定推理放在哪。常见做法有三种我按落地难度和适用场景排一下。第一种是纯云端推理。小程序只负责采集图片用wx.uploadFile把图传到自己的服务端服务端用 Python 加载模型推理返回 JSON。优点是模型随便换、算力不受限、小程序包体小缺点是必须有公网服务端且要处理上传耗时和并发。第二种是端侧推理。用微信官方的推理能力或第三方 WASM 方案把模型转成小程序能加载的格式直接在手机本地算。优点是离线可用、没有服务端成本缺点是模型体积受限、算子支持有限、转换过程容易翻车而且不同机型性能差异很大。第三种是混合。简单模型放端侧做预处理或粗筛复杂模型走云端精算。听起来很美但调试成本翻倍新手不建议一上来就这么干。我的建议很直接如果你手里是一个「实战 demo」优先选纯云端推理。因为 demo 的核心价值是证明链路通而不是压榨性能。等链路跑通、需求确认了再考虑把轻量模型下沉到端侧。2.2 目录结构怎么摆才不乱解压一个 AI 小程序 demo最怕的是文件到处扔。我一般会强制成下面这种结构前后端分仓或分目录都行关键是边界清晰ai-miniprogram-demo/ ├── miniprogram/ # 小程序端 │ ├── pages/ │ │ ├── index/ # 首页选图/拍照入口 │ │ └── result/ # 结果页展示识别结果 │ ├── utils/ │ │ └── request.js # 统一封装上传与请求 │ ├── app.js │ └── app.json ├── server/ # 推理服务端 │ ├── app.py # 接口入口 │ ├── model/ │ │ └── model.onnx # 模型文件 │ ├── preprocess.py # 图像预处理 │ └── requirements.txt └── README.md这个结构的好处是小程序端永远不碰模型文件服务端永远不碰页面逻辑。很多人把模型塞进miniprogram目录结果包体直接超限预览都过不去。2.3 接口协议先约定死在写任何代码之前先把请求和返回的字段定死否则前后端联调就是互相甩锅。我一般用下面这个最小协议字段方向类型说明image请求file用户选择的图片文件model_name请求string指定调用的模型标识code返回int0 成功非 0 失败label返回string识别出的类别名score返回float置信度0 到 1cost_ms返回int服务端推理耗时便于排查字段定好之后前端只管传图后端只管回这三个值。别在 demo 阶段搞什么多模型动态路由那是给自己挖坑。3. 服务端最小推理接口从加载模型到返回 JSON3.1 用 Flask 起一个能收图的接口服务端我一般用 Flask因为它足够轻几十行就能跑起来。下面是一个可以直接抄的最小实现模型用 ONNX Runtime 加载避免依赖重型框架# server/app.py import io import time import numpy as np from flask import Flask, request, jsonify from PIL import Image import onnxruntime as ort app Flask(__name__) # 全局加载一次模型避免每次请求都重新加载 SESSION ort.InferenceSession(model/model.onnx) INPUT_NAME SESSION.get_inputs()[0].name def preprocess(image_bytes): 把上传的图片统一成模型需要的输入格式 img Image.open(io.BytesIO(image_bytes)).convert(RGB) img img.resize((224, 224)) # 与训练时保持一致 arr np.asarray(img).astype(np.float32) / 255.0 arr np.transpose(arr, (2, 0, 1)) # HWC - CHW return np.expand_dims(arr, axis0) # 增加 batch 维度 app.route(/predict, methods[POST]) def predict(): start time.time() file request.files.get(image) if file is None: return jsonify({code: 1, msg: no image}) tensor preprocess(file.read()) outputs SESSION.run(None, {INPUT_NAME: tensor}) logits outputs[0][0] idx int(np.argmax(logits)) score float(np.exp(logits[idx]) / np.sum(np.exp(logits))) return jsonify({ code: 0, label: str(idx), score: round(score, 4), cost_ms: int((time.time() - start) * 1000) }) if __name__ __main__: app.run(host0.0.0.0, port5000)这段代码有三个关键点。第一SESSION在模块加载时就初始化绝对不能放在predict函数里否则每次请求都重新加载模型耗时从几十毫秒变成几秒。第二预处理里的resize((224, 224))必须和训练时一致尺寸对不上输出就是随机噪声。第三np.transpose把通道顺序从 HWC 转成 CHW这是 PyTorch 系模型的惯例如果你用的是 TensorFlow 导出的模型这一步可能不需要要看模型输入定义。3.2 参数怎么改才不出错上面代码里有几个参数是高频改动点我列一下常见取值和影响参数常见值改动影响resize 尺寸224 / 256 / 320必须等于训练输入尺寸改错直接掉点归一化方式/255 或 mean/std与训练预处理一致否则置信度失真batch 维度1demo 阶段固定为 1别开批量端口5000本地调试随意部署时注意防火墙归一化这块特别容易翻车。有些模型训练时用的是 ImageNet 的 mean 和 std你只做/255模型也能出结果但置信度会整体偏低看起来像「模型不准」其实是预处理错了。3.3 本地先自测别急着连小程序服务端起好之后先用 curl 打一发确认接口本身没问题curl -X POST http://127.0.0.1:5000/predict \ -F imagetest.jpg返回里code为 0、label和score都有值说明服务端这条链路是通的。这一步不做直接去小程序里调出了问题你根本分不清是前端传参错了还是后端崩了。我一般会准备三张测试图一张明显正例、一张明显负例、一张纯色图看返回是否合理。4. 小程序端上传与展示从选图到渲染结果4.1 选图和上传的完整逻辑小程序端核心就两件事拿到图片临时路径然后上传。下面这段是utils/request.js里的封装// miniprogram/utils/request.js const BASE_URL http://127.0.0.1:5000; function predict(imagePath) { return new Promise((resolve, reject) { wx.uploadFile({ url: ${BASE_URL}/predict, filePath: imagePath, name: image, // 必须和服务端 request.files.get(image) 对应 success(res) { // uploadFile 返回的是字符串需要手动解析 const data JSON.parse(res.data); if (data.code 0) { resolve(data); } else { reject(new Error(data.msg || infer failed)); } }, fail(err) { reject(err); } }); }); } module.exports { predict };这里有个血泪经验wx.uploadFile的success回调里res.data是字符串不是对象。很多人直接res.data.label拿到的是undefined然后怀疑后端没返回。必须JSON.parse一次。另外name字段必须和服务端取值一致写成file还是image要两边对齐否则服务端拿到的是空。4.2 页面里怎么调在首页里用户点按钮选图选完直接调上传// miniprogram/pages/index/index.js const { predict } require(../../utils/request); Page({ data: { imagePath: , label: , score: 0 }, chooseImage() { wx.chooseMedia({ count: 1, mediaType: [image], success: (res) { const path res.tempFiles[0].tempFilePath; this.setData({ imagePath: path }); this.doPredict(path); } }); }, async doPredict(path) { wx.showLoading({ title: 识别中 }); try { const result await predict(path); this.setData({ label: result.label, score: result.score }); } catch (e) { wx.showToast({ title: 识别失败, icon: none }); } finally { wx.hideLoading(); } } });wx.chooseMedia是新版 API老项目里可能还是wx.chooseImage两者返回结构不同迁移时注意tempFilePaths和tempFiles的区别。showLoading和hideLoading要成对出现放在finally里最稳否则请求失败时 loading 会一直转。4.3 真机预览必须处理的域名问题开发者工具里勾选「不校验合法域名」就能跑但真机预览不行。真机要求请求域名是 HTTPS 且已备案配置。demo 阶段有两个务实做法一是用内网穿透工具把本地服务映射成一个临时 HTTPS 地址填到小程序后台的 request 合法域名里二是直接在真机上用「开发版」并打开调试模式临时绕过校验。注意临时绕过只适合自己调试任何要给别人用的版本都必须走正规 HTTPS 域名否则对方一打开就是请求失败。5. 避坑与排查那些让 demo 跑不起来的细节5.1 上传后服务端收到空文件现象是服务端request.files.get(image)返回None接口直接走错误分支。原因通常有两个前端name字段和服务端取值不一致或者前端传的是filePath但路径本身失效了。解决方法是先在wx.uploadFile的success里打印res.statusCode如果是 400基本就是字段名对不上同时确认imagePath是tempFilePath而不是别的字段。5.2 模型输出全是同一个类别现象是不管传什么图返回的label都一样score还很高。原因大概率是预处理和训练不一致最常见的是归一化方式错了或者通道顺序反了。RGB 转成 BGR、HWC 没转 CHW都会让模型「看到」一张完全不同的图。解决办法是拿一张训练集里的图在服务端单独跑一遍预处理把处理后的张量形状和数值范围打印出来和训练脚本对比。5.3 开发者工具能跑真机白屏现象是工具里一切正常真机打开页面空白。原因通常是真机不支持本地 HTTP 请求或者小程序包体超限。先看调试器里的网络面板如果请求全部失败就是域名问题如果页面根本没渲染检查app.json里的页面路径是否写错以及有没有把大模型文件误打进miniprogram目录导致包体超过 2MB。5.4 推理耗时忽高忽低现象是同样的图有时 50ms有时 800ms。原因是第一次请求触发了模型懒加载或算子编译后面才稳定。解决办法是在服务启动后先跑一次「预热推理」用一张全零张量走一遍SESSION.run把初始化成本提前消化掉。这个技巧在 demo 演示时特别有用避免第一次点击就卡住。5.5 图片方向不对导致识别错现象是手机拍的竖图识别结果离谱。原因是部分机型拍照后 EXIF 里带旋转信息而 PIL 读取时不一定自动应用。解决办法是在预处理里加一步方向校正或者用ImageOps.exif_transpose处理。这个坑很隐蔽因为你在电脑上看图是正的但程序读到的像素是旋转过的。6. 进阶技巧把 demo 变成可演示的稳定版本6.1 用预热和超时控制提升演示稳定性demo 最大的敌人是演示时翻车。我一般会在服务端启动时做两件事预热推理和设置请求超时。预热上面说了超时则是给SESSION.run外面包一层时间统计超过阈值就返回一个兜底结果而不是让前端一直转圈。前端也要设timeoutwx.uploadFile默认超时较长演示场景建议压到 5 秒。6.2 结果页加一个「置信度可视化」纯文字展示label和score说服力有限。我会在结果页加一个简单的进度条宽度按score百分比来用户一眼就能看出模型有多确定。这个改动很小但演示效果提升明显。代码上就是一个view的style绑定宽度不需要引入图表库。6.3 模型替换时的检查清单当你把 demo 里的模型换成自己训的模型时按下面这个顺序检查能省掉大量调试时间检查项确认内容输入尺寸与训练时resize尺寸一致输入布局NCHW 还是 NHWC和导出时一致归一化mean/std 或 /255与训练一致输出含义argmax 对应的是类别索引还是别的类别映射索引到类别名的映射表要同步更新这五项里任何一项对不上模型都会「能跑但不对」而这种错误最难排查因为它不报错。6.4 我自己的习惯我现在做这类 demo第一步永远不是写页面而是先用 curl 把服务端打通确认输入输出符合预期第二步再写小程序端且前端只做展示不做任何计算第三步在真机上完整走一遍把域名、包体、超时全部暴露出来。这套顺序让我少熬了很多夜。希望帮到你。本文还有配套的精品资源点击获取