简介这份压缩包围绕人工智能主题的微信小程序实战演示面向具备基础小程序语法、希望了解人工智能功能如何嵌入页面与交互的学习者也可供前端开发者参考项目组织方式。包内共59个文件、约1.36MB包含JavaScript业务逻辑、WXML页面结构、WXSS样式与JSON配置另有较多PNG、GIF、JPG图片素材及一份README说明目录涉及首页、关于、个人中心、待办等页面并配有通用工具、录音播放与消息组件相关代码素材可用于导航图标、录音波形和功能演示。已有243人学习下载具备一定参考热度。读者可从中获得较完整的小程序目录骨架、页面注册与配置范例、组件拆分思路、录音播放等交互逻辑的串联方式以及图片素材的组织方法便于对照搭建自己的人工智能演示项目并理解调试入口。1. 一份能跑通的小程序 AI 骨架先看它替你解决了哪三件事把人工智能塞进微信小程序难点从来不是调一次接口而是调完之后的那些琐事密钥放哪、录音格式对不对、真机上为什么一直转圈、并发上来后账单为什么翻倍。这个 demo 就是把这些琐事提前踩过一遍的端到端骨架——小程序端负责采集音频、图片和文本自建转发层负责鉴权与协议转换AI 服务只暴露一个内部接口。它解决三件事一是给出可运行的调用链路二是把密钥和超时收敛到服务端三是留出替换模型的接口位。适合正在给小程序加语音识别、图片理解或问答能力的前后端也适合想先跑通再谈优化的团队。2. 拆包看分层小程序端、转发层、AI 服务各管一段拿到一个 demo 压缩包最容易犯的错是从第一个文件开始逐个读。更省时间的做法是先看目录确认它把职责切成了几层再决定从哪一层下手改。这份包的分层比较典型小程序端只做采集和展示转发层做鉴权、限流和错误码归一AI 调用被封在一个独立模块里换模型时只动那一处。2.1 目录分层与各自的责任边界先给一张我拆包时惯用的对照表按职责而不是按文件名归类。实际目录名可能略有差异但结构基本对得上。位置承担的职责改动频率miniprogram/pages/页面结构、按钮与结果展示高业务都在这miniprogram/utils/request.js统一请求封装、超时、错误提示中接新接口时改miniprogram/utils/recorder.js录音生命周期、格式与采样率低定好就不动miniprogram/utils/image.js选图、压缩、转 base64 或直传低server/app.py路由、参数校验、转发入口中server/ai_client.pyAI 接口调用、重试、结果解析高换模型改这里server/config.py密钥、域名、超时阈值低走环境变量server/requirements.txt依赖版本锁定低这张表的意义在于当你只想换个模型时改动应该被限制在ai_client.py一个文件里当你只想调 UI不该碰server/。如果拆包后发现 AI 调用散落在页面 JS 里那这份 demo 就只能当参考不能当骨架用。采集层和转发层的分界线要划清楚。小程序端不应该知道 AI 服务长什么样它只知道「我 POST 一个文件到/api/v1/asr拿回一段文字」。这条约定一旦立住后面换供应商、加灰度、做 A/B 都只是服务端的事前端不用跟着发版。2.2 为什么中间要夹一层自建后端新手最常见的做法是把 AI 服务的地址和密钥直接写进小程序代码wx.request一调就完事本地调试还真能跑通。这条路走不通的原因不是技术是暴露面小程序包会被反编译密钥等于公开就算用临时凭证签名逻辑也在客户端一样能被复用。夹一层自建后端换来三样东西。第一是密钥只在服务端环境变量里出现客户端拿不到。第二是协议转换很多 AI 接口要求multipart/form-data或特定 header小程序端的wx.uploadFile行为和浏览器表单有差异在服务端抹平比在前端绕坑省事。第三是可控性限流、缓存、幂等、日志埋点这些上线必备的东西只有放在自己控制的一层才做得进去。代价是多一跳网络和一个需要维护的服务。对 demo 阶段来说这个代价可以接受因为转发层代码量很小一个路由加一个客户端封装就够。真正麻烦的是域名和备案这部分在第 5 章会单独说。选型上Python 侧用 Flask 或 FastAPI 都行demo 里常见的是 Flask胜在依赖少、启动快如果后续要接流式返回FastAPI 的异步更顺手。我一般按「要不要流式」来定一次性返回结果的场景用 Flask 足够需要边生成边推送的场景直接上 FastAPI省得后期重写。2.3 第一次启动的最小步骤不要一上来就真机预览先在本地把转发层跑起来用 curl 打一遍确认服务本身没问题再去联调小程序。这样出问题时能立刻判断是前端还是后端。# 1. 进入服务端目录建虚拟环境隔离依赖避免污染全局 cd server python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate # 2. 装依赖版本以 requirements.txt 锁定为准 pip install -r requirements.txt # 3. 用环境变量注入密钥不要写进代码或配置文件 export AI_ENDPOINThttps://your-ai-endpoint/v1/recognize export AI_KEYsk-xxxxxxxx export REQUEST_TIMEOUT25 # 4. 启动监听 0.0.0.0 方便手机在同一局域网访问 python app.py --host 0.0.0.0 --port 8000前三步是环境准备重点是密钥走环境变量而不是硬编码第四步的--host 0.0.0.0是给真机调试用的绑127.0.0.1的话手机连不上。REQUEST_TIMEOUT设 25 秒是个经验值语音识别这类接口在音频较长时容易超过 10 秒设太短会大量误判为超时。服务起来后先用命令行验一遍别急着开开发者工具# 用一个短音频打一次确认链路通、返回结构符合预期 curl -X POST http://127.0.0.1:8000/api/v1/asr \ -F file./samples/hello.mp3 \ -F formatmp3 \ -H X-Client-Id: local-test # 期望返回类似{code:0,text:...,elapsed_ms:1830}X-Client-Id这个头在 demo 里通常用于日志归属和简单限流正式环境要换成签名或登录态。返回体里带elapsed_ms是个好习惯后面排查「为什么慢」时不用靠猜。本地 curl 通了再打开开发者工具导入miniprogram/目录把request.js里的BASE_URL改成局域网 IP勾选「不校验合法域名」做第一轮联调。这一步跑通说明分层是对的剩下的就是逐个功能替换成自己的业务。3. 接通第一个 AI 能力请求封装、超时与参数怎么定链路通了之后真正决定这个 demo 好不好用的是请求封装的质量。封装写得糙后面每接一个能力都要复制一遍超时和错误处理封装写得好接新接口只是加一个函数。3.1 小程序端的统一请求封装不要在页面里直接写wx.request或wx.uploadFile。页面拿到的东西应该是「成功的数据」或「可展示的错误文案」而不是statusCode和errMsg。// utils/request.js const BASE_URL http://192.168.1.20:8000; // 调试期用局域网 IP上线换 https 域名 const DEFAULT_TIMEOUT 30000; // 统一错误码页面只认这几个不关心底层是网络错误还是业务错误 const ERR { NETWORK: network_error, TIMEOUT: timeout, SERVER: server_error, EMPTY: empty_result, }; function normalizeError(res, err) { if (err /timeout/i.test(err.errMsg || )) return ERR.TIMEOUT; if (!res) return ERR.NETWORK; if (res.statusCode 500) return ERR.SERVER; if (res.statusCode ! 200) return ERR.SERVER; return null; } // 上传文件语音、图片都走这个 function upload({ url, filePath, name file, formData {} }) { return new Promise((resolve, reject) { const task wx.uploadFile({ url: BASE_URL url, filePath, name, formData, timeout: DEFAULT_TIMEOUT, success: (res) { const bad normalizeError(res); if (bad) return reject({ code: bad, raw: res }); let data; try { // uploadFile 的 data 是字符串必须手动解析 data JSON.parse(res.data); } catch (e) { return reject({ code: ERR.SERVER, raw: res }); } if (data.code ! 0) return reject({ code: ERR.SERVER, msg: data.msg }); if (!data.text !data.result) return reject({ code: ERR.EMPTY }); resolve(data); }, fail: (err) reject({ code: normalizeError(null, err), raw: err }), }); // 把 task 抛出去页面可以调 abort避免用户返回后请求还在跑 resolve.task task; }); } module.exports { upload, ERR };这段代码有三个关键点。第一wx.uploadFile返回的res.data是字符串不是对象直接当 JSON 用会在真机上炸这是翻车率最高的一行。第二超时设置在wx.uploadFile的timeout字段上默认值在不同基础库下表现不一致显式写死 30000 更稳。第三把task挂在 promise 上页面onUnload时可以abort否则用户退出页面后请求还在跑回调里再去setData会报页面已销毁的警告。BASE_URL调试期用局域网 IP上线必须换成已配置的 https 域名这条没有例外。DEFAULT_TIMEOUT给 30 秒是上限保护具体接口的超时应该由服务端控制客户端只做兜底否则两边都设超时容易出现「服务端还在算、客户端已经放弃」的浪费。3.2 服务端转发超时、重试与错误码归一转发层的核心不是转发是把上游的不确定性收敛成下游能处理的结果。上游可能超时、可能返回 429、可能返回一段结构完全不同的错误体这些都不该让小程序去分辨。# server/ai_client.py import os, time, requests ENDPOINT os.environ[AI_ENDPOINT] API_KEY os.environ[AI_KEY] TIMEOUT float(os.environ.get(REQUEST_TIMEOUT, 25)) MAX_RETRY 2 # 只对可重试的错误重试网络抖动、限流、5xx RETRYABLE {429, 500, 502, 503, 504} def call_ai(file_bytes, fmtmp3): last_err None for attempt in range(MAX_RETRY 1): try: resp requests.post( ENDPOINT, headers{Authorization: fBearer {API_KEY}}, files{file: (faudio.{fmt}, file_bytes, faudio/{fmt})}, data{format: fmt, sample_rate: 16000, channel: 1}, timeout(5, TIMEOUT), # (连接超时, 读取超时) ) except requests.Timeout as e: last_err (timeout, str(e)) continue except requests.RequestException as e: last_err (network, str(e)) continue if resp.status_code in RETRYABLE and attempt MAX_RETRY: # 指数退避避免瞬间打满上游配额 time.sleep(0.5 * (2 ** attempt)) last_err (retryable, resp.status_code) continue if resp.status_code ! 200: return {code: 5001, msg: fupstream_{resp.status_code}} body resp.json() text body.get(result, {}).get(text, ).strip() if not text: return {code: 5002, msg: empty_result} return {code: 0, text: text} return {code: 5003, msg: last_err[0] if last_err else unknown}timeout(5, TIMEOUT)这个元组容易写错第一个是建立连接的时间第二个是等待响应的时间只写一个数字的话两者相同长音频场景下连接很快但读取很久统一设 25 秒会误杀。重试只针对RETRYABLE里那几个状态码业务错误比如参数不合法返回 400重试多少次都是错白白消耗配额。退避用0.5 * 2^n两次重试最多多等 1.5 秒够用且不会把用户晾太久。返回值统一成{code: 0/5xxx, text: ...}这一种结构页面的错误处理才能只有一套逻辑。上游到底返回什么字段在这里就被吃掉了。3.3 参数怎么定一张表说清哪些能调参数不是越多越好改错一个采样率识别率能掉一半。下面这几个是实际调过的。参数常用取值影响调整建议sample_rate16000低于 8000 高频丢失高于 16000 体积翻倍收益很小语音固定 16000channel1双声道多数接口只取单声道白传一倍数据固定单声道formatmp3 / aac / pcmpcm 无压缩、体积大mp3 兼容性最好小程序录音用 mp3timeout25s太短误判超时太长用户干等按音频时长动态算max_retry2再多也救不回来只是拖时间保持 2图片quality70~80压缩率与识别精度的平衡点先 80 再往下试超时这里值得单说一句。固定 25 秒对 10 秒以内的短语音是浪费对 60 秒的长语音又不够。更合理的做法是按音频时长估算timeout max(15, duration * 0.6)给上游留出处理时间同时不让用户等太久。这个公式不精确但比拍一个固定值靠谱。图片侧的quality参数在wx.compressImage里控制压缩质量70 到 80 之间通常能兼顾体积和识别率。低于 60 时文字类图片的识别准确率会明显下降这个边界值得自己在真机上测一遍再定。4. 三条输入链录音、拍照、文本采集的落地写法AI 能力好不好用一半取决于采集。采集做不好模型再强也是垃圾进垃圾出。三条链路的共性是要有明确的生命周期和失败兜底。4.1 录音链路从权限到文件路径录音在小程序里是个状态机授权、开始、暂停、停止、上传、清理。少一步就会出问题比如没停就上传会拿到空文件。// utils/recorder.js const recorder wx.getRecorderManager(); let currentPath null; function startRecord() { return new Promise((resolve, reject) { // 先查授权用户拒绝过要引导去设置页 wx.getSetting({ success: (res) { if (res.authSetting[scope.record] false) { return reject({ code: auth_denied }); } recorder.start({ duration: 60000, // 最长 60 秒超时自动停 sampleRate: 16000, // 必须与后端参数一致 numberOfChannels: 1, encodeBitRate: 48000, format: mp3, }); resolve(); }, fail: () reject({ code: auth_check_failed }), }); }); } recorder.onStop((res) { currentPath res.tempFilePath; }); recorder.onError((err) { currentPath null; }); function stopRecord() { return new Promise((resolve) { recorder.onStop((res) resolve(res.tempFilePath)); recorder.stop(); }); } // 页面卸载时务必清理否则临时文件会累积 function cleanup() { currentPath null; } module.exports { startRecord, stopRecord, cleanup };sampleRate必须和后端请求里的参数一致前端录 44100 后端声明 16000识别结果会变成一堆乱码这是最典型的「看起来通了但结果不对」。duration设 60 秒是硬上限超过这个长度的音频大多数接口会拒绝或者按截断处理与其让用户录完再报错不如提前掐断。onStop回调是异步的recorder.stop()之后立刻读currentPath大概率还是 null。所以stopRecord里重新注册了一次onStop再返回 promise这个写法比在页面里等setTimeout稳得多。tempFilePath是临时文件小程序重启后就没了。如果业务需要保留得用wx.saveFile存到本地但要注意存储配额别把用户空间塞满。4.2 图片链路选图、压缩与体积控制图片这条链路的坑集中在体积上。手机直出的照片动辄四五兆base64 之后再涨三分之一很容易撞上请求体大小限制。// utils/image.js const MAX_SIZE 1024 * 1024; // 1MB超过就压缩 function chooseAndCompress() { return new Promise((resolve, reject) { wx.chooseMedia({ count: 1, mediaType: [image], sourceType: [album, camera], sizeType: [compressed], // 先用系统压缩减少后续处理 success: async (res) { const file res.tempFiles[0]; if (file.size MAX_SIZE) return resolve(file.tempFilePath); try { // 二次压缩quality 是唯一需要调的参数 const out await wx.compressImage({ src: file.tempFilePath, quality: 75, }); resolve(out.tempFilePath); } catch (e) { reject({ code: compress_failed }); } }, fail: (err) reject({ code: choose_cancel, raw: err }), }); }); } module.exports { chooseAndCompress };sizeType: [compressed]会让系统先压一次多数情况下这一步就够MAX_SIZE的判断只是兜底。quality: 75是个折中值文字类图片建议提到 85风景类可以降到 65差别在于细节保留。上传时用wx.uploadFile而不是转 base64 塞进wx.request。base64 会让请求体膨胀约 33%而且大字符串在 iOS 上解析容易卡顿直传文件流更稳。如果服务端只接受 base64转换放在服务端做不要在小程序里做。4.3 文本与状态机把「转圈」变成可解释的进度文本输入看起来最简单但它是唯一需要处理「流式返回」的链路。一次性返回和逐字返回的体验差距很大前者用户要盯着空白等十几秒。状态机我一般只设四个状态idle、recording、uploading、done加一个error兜底。页面根据状态决定按钮文案和是否禁用比零散的loading布尔值可靠。状态触发UI 表现可执行操作idle初始 / 重置按钮可点开始录音、选图、输入recording点击开始显示计时停止、取消uploading停止后自动进入转圈 禁用仅取消done收到结果展示文本重新开始error任意失败错误文案 重试重试、返回uploading状态必须禁用重复点击否则用户手快连点两次两次请求同时发出去第二次的结果可能覆盖第一次也可能是重复计费。这个保护用状态机做比用时间戳去重干净。流式返回的实现方式是在服务端用 SSE 或分块传输小程序端用wx.request的enableChunked: true配合onChunkReceived接收。这个能力对基础库版本有要求用之前先查目标用户的基础库分布别为了一个体验优化把老设备全排除掉。5. 避坑与排查五条从真机日志里捞出来的记录下面这几条都是调这个 demo 时真实撞过的每条按现象、原因、解决写。有些问题在开发者工具里永远复现不了只能真机见。5.1 上传与格式类两个必踩的坑第一条真机上一直返回empty_result开发者工具正常。现象是模拟器里录音上传能识别出文字扫码到手机上同样的操作返回空。原因是开发者工具的录音走的是电脑麦克风格式和采样率比较规整真机录音在部分安卓机型上会忽略sampleRate参数实际输出 44100Hz 或双声道而后端按 16000 单声道去解析波形对不上识别自然为空。解决分两步一是在上传前用wx.getFileSystemManager().getFileInfo拿到真实文件大小结合录音时长反推码率码率异常时提示用户重录二是在服务端做一层格式探测读文件头判断真实采样率和声明值不一致时先转码再送上游。转码用 ffmpeg 一行命令就够别在前端做。第二条图片上传偶发413大图必现。现象是拍风景照上传失败拍文档没事。原因是wx.chooseMedia的sizeType: [compressed]只是「倾向压缩」不是保证压缩部分机型对超过一定尺寸的图片会跳过压缩直接返回原图。解决是把体积判断做成硬门槛file.size超过阈值就必须走wx.compressImage二次压缩压缩后仍然超限就降quality重试一次还不行就提示用户裁剪。同时服务端要把请求体上限调到一个合理值别用默认的 1MB图片场景至少给到 8MB给压缩失败留余量。5.2 域名、鉴权与配置类第三条开发者工具勾了「不校验合法域名」能跑上线后全部请求失败。现象是发布体验版后所有接口报request:fail url not in domain list。原因很直接开发者工具的跳过校验只对开发环境生效体验版和正式版都走真实校验而且域名必须是 https、已备案、并且在后台配置过。解决是在上线前把BASE_URL换成正式 https 域名在小程序后台的服务器域名里配置request和uploadFile两类注意这两类是分开配的只配request的话wx.uploadFile照样失败。域名不能带端口、不能用 IP、不能是短链这几条任一不满足都会配置失败。血泪经验是提审前专门跑一遍体验版别等审核通过才发现。第四条密钥轮换后服务起不来日志只有一行KeyError。现象是运维换了密钥重启服务直接崩报KeyError: AI_KEY。原因是os.environ[AI_KEY]这种写法在变量缺失时直接抛异常而启动脚本里环境变量的加载顺序依赖了 shell 的export用 systemd 或容器启动时根本没读到。解决是把必需的环境变量做启动自检缺失时打印明确提示而不是抛栈同时把所有环境变量收敛到一个config.py里集中读取用os.environ.get加默认值或显式报错。容器部署时用env_file而不是命令行export避免不同启动方式行为不一致。5.3 超时、并发与真机差异第五条并发一上来一半请求超时上游账单还翻了倍。现象是压测时 20 并发成功率掉到 50%但上游控制台显示请求量是预期的两倍。原因是客户端超时 30 秒服务端超时 25 秒客户端先放弃后用户点重试而服务端的第一次请求还在跑等于一次用户操作消耗了两次配额重试逻辑又对超时做了重试三次叠加。解决是把超时链路统一客户端超时 服务端超时 上游超时逐层递减客户端永远比服务端多留 5 秒缓冲。重试只在一处做要么服务端要么客户端不能两边都重试。再加一层幂等键同一个用户同一次操作携带相同的request_id服务端在有效期内直接返回缓存结果把重复请求挡在计费之前。层级超时设置重试策略小程序端30s不重试交给用户手动转发层25s最多 2 次指数退避上游调用20s不重试这张表的意义是把「谁负责重试」写死。三层都重试是灾难一层都不重试又太脆指定转发层做唯一的重试点是成本和成功率之间的平衡。6. 从 demo 到能上线限流、缓存与一套可复现的自测用例demo 跑通和能上线之间隔着三样东西限流、缓存、可复现的验证。前两样决定成本和稳定性后一样决定你敢不敢改代码。6.1 三个必须加的保护幂等键。每次用户操作生成一个request_id服务端用request_id 用户标识做键缓存 5 分钟。重复请求直接返回上次结果既防连点也防网络重试带来的重复计费。实现上不必上 Redis进程内带过期的字典在单实例阶段够用多实例再换。按用户限流。免费额度和付费额度分开算用滑动窗口计数。关键是限流要返回明确的错误码和剩余次数让前端能展示「今日还剩 3 次」而不是笼统报错。限流阈值按业务定语音识别这类重操作我一般给每分钟 5 次图片理解给每分钟 10 次。结果缓存。同一张图片、同一段音频在短时间内重复提交的概率不低用内容哈希做键缓存结果命中率往往比想象中高。哈希在服务端算不要在前端算完传上来避免被伪造。这三样加起来代码量不超过一百行但对成本和体验的影响远大于调模型参数。6.2 一套能反复跑的自测用例改完代码要能快速确认没退化。我习惯留一组固定输入加固定断言每次改动后跑一遍。用例输入期望覆盖点短语音3 秒 mp3返回非空文本耗时 3s基础链路长语音55 秒 mp3返回非空耗时 20s超时边界空文件0 字节code5002异常输入大图4MB jpg压缩后成功413不出现体积控制重复提交同一request_id两次第二次命中缓存耗时 100ms幂等并发 10混合输入成功率 ≥ 95%限流与超时把这些用例写成一个 shell 脚本或者 Python 测试文件接在 CI 里改动提交前自动跑。比手工点页面可靠得多尤其是超时相关的用例手工根本压不出来。6.3 一个容易被忽略的收尾技巧最后说个细节服务端日志里一定要记录上游的elapsed_ms和请求体大小。这两项在排查「为什么这个用户总失败」时是黑匣子——大概率是他的音频特别长或者图片特别大而不是接口不稳定。没有这两项你只能靠猜。我自己的习惯是每次改完ai_client.py里的任何参数先跑一遍那六个用例再上真机用三种不同机型各走一遍录音和拍照。有一次图省事跳过了真机这一步结果一个安卓机型的采样率问题拖了三天才定位到从那以后每次改动都强制走一遍这个流程。希望帮到你。本文还有配套的精品资源点击获取