浏览器端侧视觉AI工程实践：从模型转换到实时推理

1. 项目概述：当视觉AI不再依赖服务器，而是在你打开的标签页里实时呼吸

“把神经网络塞进一个浏览器标签页”——这句话乍听像一句技术圈的玩笑话，但过去三年里，我亲手在 Chrome、Edge、Safari 上跑通了从 MobileNetV2 到 YOLOv5s 的轻量化视觉模型，全程不发一次 HTTP 请求，所有推理都在window对象里完成。这不是 Demo，而是我们团队为某款工业质检 SaaS 产品做的端侧降本方案：把原本每张图都要上传云端、等待 300ms 响应的缺陷识别流程，压缩成本地 42ms 完成的实时反馈。用户甚至没意识到 AI 已经“住进”了浏览器。

核心关键词就藏在这句话里：神经网络是能力内核，浏览器是运行容器，端侧是部署范式，视觉AI是任务类型，工程是成败分水岭。注意，这里说的不是“用 TensorFlow.js 跑个 MNIST”，而是真实产线场景下的端侧视觉 AI 工程落地——它要扛住 Chrome 内存限制、应对 Safari WebKit 的 WebGL 兼容断层、在低端安卓手机上维持 15FPS 的视频流推理、还要让产品经理能看懂模型精度下降 0.8% 是因为量化误差还是预处理 Bug。这背后没有魔法，只有一连串被反复锤炼过的工程选择：为什么选 WebAssembly 而不是纯 WebGL？为什么必须手写 Tensor 缓存池？为什么OffscreenCanvas在 iOS 16.4 才真正可用？这些细节，才是“塞进去”三个字背后的全部真相。

适合谁读？如果你正面临这些具体问题：想把训练好的 PyTorch 模型部署到网页但卡在模型转换环节；发现 TF.js 推理速度比本地 Python 慢 3 倍却找不到瓶颈；需要支持微信内置浏览器（X5 内核）但文档里查不到兼容性表；或者只是好奇“浏览器里到底能塞多大的神经网络”——那这篇就是为你写的。它不讲反向传播数学推导，不堆砌论文指标，只记录我在 17 个真实项目中踩过的坑、验证过的参数、以及最终留在生产环境里的那一行行代码。

2. 端侧视觉AI的整体设计思路：为什么“塞进标签页”比“部署到云”更难？

2.1 根本矛盾：浏览器不是操作系统，而是一个受控沙箱

很多人第一次尝试端侧 AI 时，会下意识把浏览器当成轻量级 Linux：装个 Python、pip install torch、load_model() 就完事。但现实是，浏览器对资源的管控比 iOS App Sandbox 更严苛。它有三道硬性枷锁：

• 内存墙：Chrome 标签页默认内存上限约 1.5GB（64 位），但实际可用常不足 800MB。一个未量化的 ResNet50 模型权重就占 98MB，加上输入 Tensor、中间激活值、WebGL 纹理缓存，很容易触发Out of memory。我曾在一个医疗影像标注工具中，因未释放GPUTexture导致连续标注 12 张 CT 图后标签页崩溃，错误日志里只有一行status_access_violation——这是浏览器内核直接 kill 进程的信号。

• 计算墙：CPU 单线程执行 JS，GPU 通过 WebGL 或 WebGPU 调用，但两者间存在严重带宽瓶颈。举个实测数据：在 MacBook Pro M1 上，用 WebAssembly 跑 MobileNetV2 的 CPU 推理耗时 86ms；换成 WebGL 后，单纯把图像数据从 CPU 传到 GPU 纹理就要 32ms，再加 shader 计算 41ms，总耗时反而升到 73ms。这意味着“GPU 加速”在端侧不是无条件成立，而是需要精细的流水线编排。

• 生态墙：不同浏览器内核对 AI 相关 API 的支持度天差地别。比如createImageBitmap在 Chrome 59+ 支持，但 Safari 直到 16.4 才修复transferToImageBitmap的内存泄漏；WebNNAPI 在 Chrome 119 才进入 Origin Trial，而 Edge 已默认启用。更麻烦的是微信 X5 内核——它基于旧版 Blink，不支持OffscreenCanvas，所有 canvas 操作都强制同步到主线程，导致视频流推理帧率直接掉到 3FPS。

所以，“塞进标签页”的本质，是把一个本该在 Linux 服务器上自由呼吸的神经网络，压缩进一个由 V8 引擎、Blink 渲染器、ANGLE 图形层共同构筑的精密牢笼。设计思路的第一步，永远不是“怎么跑模型”，而是“怎么给模型造一间合规的牢房”。

2.2 方案选型逻辑：WebGL、WebAssembly、WebNN 三选一的底层权衡

当前主流端侧推理方案有三个技术栈，选择依据不是“哪个更新潮”，而是“哪个最匹配你的硬件基线和精度容忍度”：

• WebGL 方案（TF.js 默认）：
  优势：兼容性最好，Chrome 49+/Firefox 51+/Safari 15.4+ 均支持；利用 GPU 并行计算，对卷积密集型模型（如 CNN）加速明显。
  劣势：API 抽象层厚，调试困难；纹理尺寸必须是 2 的幂次方（如 256×256），非标准分辨率需 padding；不支持动态 shape，输入尺寸必须编译期固定。
  适用场景：对兼容性要求极高（需支持 2018 年后的主流机型），且模型结构简单（MobileNet、ShuffleNet）、输入尺寸固定的项目。我们给某银行远程开户系统做的活体检测，就用此方案——它要兼容大量老年用户的老款安卓机，宁可牺牲 12% 速度也要保证 99.2% 设备覆盖率。

• WebAssembly 方案（ONNX Runtime Web / WebDNN）：
  优势：CPU 推理稳定可控，无 GPU 兼容问题；支持动态 shape 和复杂控制流（LSTM、seq2seq）；内存管理透明，可精确控制 Tensor 生命周期。
  劣势：纯 CPU 计算，大模型延迟高；WASM 模块体积大（YOLOv5s WASM 文件 12MB），首次加载慢。
  适用场景：需要支持 LSTM 时序建模（如手势识别）、或目标设备 GPU 性能极弱（低端联发科 MT6737）、或对首屏加载时间敏感（需流式加载 WASM）的项目。我们为某智能手表网页版做的跌倒检测，就选 WASM——手表 WebKit 不支持 WebGL 计算着色器，且内存仅 512MB。

• WebNN 方案（Chrome 119+ / Edge 119+）：
  优势：浏览器原生 AI 加速 API，直接调用系统 NPU/ASIC（如 Mac M 系列芯片的 Neural Engine）；理论性能最高，功耗最低；支持 FP16 低精度计算。
  劣势：目前仅 Chrome/Edge 新版本支持，Safari 和 Firefox 无计划；API 尚未稳定，Chrome 122 已废弃mlGraph接口；需手动处理算子融合。
  适用场景：面向高端用户、可强制升级浏览器的 B 端工具（如设计师用的 AI 构图辅助插件），且模型已做极致量化（INT8）。我们给某 Adobe 插件做的实时背景虚化，就用 WebNN——M2 芯片上 INT8 YOLOv8n 推理仅需 9ms，功耗比 WebGL 低 40%。

提示：不存在“银弹方案”。我们曾为同一款工业相机质检工具同时实现三套方案：Chrome 用户走 WebNN，Safari 用户降级到 WebGL，老旧安卓机用户 fallback 到 WASM。通过navigator.ml?.supported和navigator.gpu?.requestAdapter动态探测，再配合 CDN 分发不同 bundle，这才是真实工程的选择。

2.3 模型瘦身哲学：不是“剪枝+量化”，而是“为浏览器重写计算图”

很多工程师以为，把 PyTorch 模型导出为 ONNX，再用onnx-simplifier优化，就能塞进浏览器。但实际落地时，80% 的失败源于模型本身与浏览器运行时的基因冲突。真正的瘦身，是三阶段手术：

第一阶段：语义精简（Semantic Pruning）
删除所有与推理无关的节点。例如：

• PyTorch 中常见的torch.nn.Dropout层，在推理时本该被忽略，但 ONNX 导出时若未设model.eval()，会保留Dropout算子，而 TF.js 不支持该算子，直接报错；
• torch.nn.BatchNorm2d的track_running_stats=True会生成BatchNormalization算子，但某些 WebGL 后端不支持其epsilon参数，需手动替换为InstanceNormalization；
• torchvision.transforms.Resize在导出时会固化为Resize算子，但浏览器中图像缩放应由canvas.drawImage()完成，而非在模型内计算——这会导致双倍 resize 失真。

第二阶段：算子重写（Operator Rewriting）
将不兼容算子映射为浏览器友好版本。典型例子：

• Softmax：WebGL 后端计算不稳定，改用LogSoftmax + Exp组合，避免指数溢出；
• GatherND（常用在注意力机制中）：WebGL 不支持，重写为Reshape + Gather + Reshape三步；
• ScatterND：同理，拆解为TensorScatterAdd等基础算子组合。
  我们维护了一个browser-op-rewrite规则库，包含 47 条针对 TF.js/WebNN 的算子映射规则，每次模型更新都自动扫描并重写。

第三阶段：内存契约（Memory Contract）
强制模型遵守浏览器内存契约。关键动作：

• 所有中间 Tensor 必须复用内存池，禁止new Float32Array(size)频繁分配；
• 输入 Tensor 与输出 Tensor 共享 buffer（in-place inference），减少 30% 内存占用；
• 激活值（Activation）采用Uint8Array存储，推理时再 cast 为Float32Array，节省 75% 内存。
  实测表明，对 MobileNetV2 做完整三阶段瘦身，模型体积从 17.2MB 降至 4.3MB，首帧推理延迟从 210ms 降至 68ms。

3. 核心细节解析：从模型转换到实时推理的 7 个生死关

3.1 模型转换：ONNX 是起点，不是终点

PyTorch → ONNX → 浏览器，这个链条里，ONNX 只是中间协议，真正的坑在 ONNX 与浏览器运行时的语义鸿沟。以最常见的torch.nn.Conv2d为例：

# PyTorch 定义 conv = nn.Conv2d(in_channels=3, out_channels=32, kernel_size=3, stride=2, padding=1) # 导出 ONNX 时若未指定 dynamic_axes，会生成固定 shape 的 graph torch.onnx.export(model, dummy_input, "model.onnx", input_names=["input"], output_names=["output"], dynamic_axes={"input": {0: "batch", 2: "height", 3: "width"}})

问题在于：TF.js 的tf.loadGraphModel会将dynamic_axes解析为tf.tensor的shape参数，但 WebGL 后端要求所有 tensor shape 在 shader 编译时确定。结果就是——Chrome 控制台报错Invalid tensor shape: [?,3,?,?]，而 Safari 直接静默失败。

解决方案是：在 ONNX 层面固化 shape，用预处理补偿灵活性。我们开发了一个onnx-shape-fuser工具：

1. 读取 ONNX 模型，提取所有Conv、Pool算子的stride/padding参数；
2. 根据输入尺寸约束（如最大支持 1024×768），反向计算各层输出尺寸；
3. 用onnx.helper.make_tensor_value_info强制重写所有 tensor 的shape字段；
4. 生成新 ONNX，并附带preprocess.js：根据实际输入尺寸，动态计算需 padding 的像素数，并调用ctx.drawImage()预处理。

这样，模型获得确定性 shape，预处理承担尺寸适配，二者解耦。实测后，模型加载成功率从 63% 提升至 99.8%。

3.2 输入预处理：Canvas 是最快的图像处理器

端侧视觉 AI 的最大误区，是把预处理当成“模型前几层”。实际上，在浏览器中，<canvas>的drawImage()比任何 JS 实现的归一化都快 10 倍以上。原因很简单：drawImage()是浏览器渲染管线原生操作，直接走 GPU 纹理采样，而 JS 数组遍历是纯 CPU 操作。

我们的标准预处理流水线如下：

// 1. 创建 OffscreenCanvas（避免主线程阻塞） const offscreen = new OffscreenCanvas(width, height); const ctx = offscreen.getContext('2d'); // 2. 绘制原始图像（自动缩放+裁剪） ctx.imageSmoothingQuality = 'high'; // Safari 16.4+ 支持 ctx.drawImage(video, 0, 0, video.width, video.height, 0, 0, width, height); // 3. 读取像素（关键：用 getImageData 而非 toDataURL） const imageData = ctx.getImageData(0, 0, width, height); const pixels = imageData.data; // Uint8ClampedArray // 4. JS 层仅做最简归一化：pixels[i] /= 255.0 // （注意：此处不转 float32，留到 WASM 内存池统一处理）

注意：getImageData返回的是Uint8ClampedArray，直接作为 WASM 内存视图使用，避免new Float32Array(pixels)的拷贝开销。我们测试过，对 640×480 图像，drawImage + getImageData耗时 4.2ms，而 JS 循环归一化耗时 18.7ms。

3.3 内存池设计：为什么必须手写 Tensor 缓存

浏览器 GC 机制对 AI 推理极不友好。TF.js 默认的tf.tidy()会在每次推理后回收所有中间 Tensor，但频繁 GC 会引发主线程卡顿（尤其在 30FPS 视频流中）。我们实测发现：在 Chrome 115 上，连续 100 帧推理后，GC pause 时间累计达 1200ms，帧率暴跌至 8FPS。

解决方案是：手写内存池（Memory Pool），实现 Tensor 的显式生命周期管理：

class TensorPool { private pool: Map<string, Tensor[]> = new Map(); // 根据 shape 和 dtype 申请 Tensor acquire(shape: number[], dtype: 'float32' | 'int32'): Tensor { const key = `${shape.join('x')}_${dtype}`; const list = this.pool.get(key) || []; if (list.length > 0) { return list.pop()!; } // 池空时创建新 Tensor return tf.tensor(new Float32Array(shape.reduce((a, b) => a * b, 1)), shape, dtype); } // 归还 Tensor 到池 release(tensor: Tensor): void { const key = `${tensor.shape.join('x')}_${tensor.dtype}`; const list = this.pool.get(key) || []; list.push(tensor); this.pool.set(key, list); } } // 使用示例 const pool = new TensorPool(); const input = pool.acquire([1, 3, 224, 224], 'float32'); // ... 推理 ... pool.release(input); // 显式归还，不触发 GC

实测效果：内存池启用后，100 帧推理 GC pause 时间降至 47ms，帧率稳定在 28FPS。更重要的是，内存占用曲线变得平滑，无尖峰波动。

3.4 WebGL 纹理优化：为什么 2 的幂次方不是教条

WebGL 要求纹理尺寸为 2 的幂次方（NPOT），但真实摄像头分辨率（如 1280×720）不是。传统做法是 padding 到 2048×1024，但这浪费 58% 纹理内存，且 padding 区域参与卷积计算，引入噪声。

我们的破局点是：利用 WebGL 2.0 的OES_texture_half_float_linear扩展，在非 NPOT 纹理上启用双线性插值。步骤如下：

1. 检测扩展支持：gl.getExtension('OES_texture_half_float_linear')；
2. 创建非 NPOT 纹理：gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.HALF_FLOAT_OES, data)；
3. 设置纹理参数：gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE)；
4. 在 shader 中，用texture2D(sampler, uv)采样，自动启用双线性插值。

实测表明，对 1280×720 输入，纹理内存从 8.3MB（2048×1024）降至 2.3MB（1280×720），且模型精度无损。目前 Chrome 95+/Edge 95+ 均支持该扩展。

3.5 视频流推理：OffscreenCanvas 是唯一出路

<video>元素的video.play()会触发主线程渲染，若在requestAnimationFrame中直接ctx.drawImage(video, ...)，会导致视频流卡顿。正确姿势是：

• 使用OffscreenCanvas在 Worker 线程中处理视频帧；
• 主线程只负责video.requestVideoFrameCallback()获取帧时间戳；
• Worker 线程通过transferControlToOffscreen()接收HTMLVideoElement，调用copyImageBitmap()获取帧；
• 推理完成后，用postMessage({type: 'result', data})通知主线程渲染。

我们封装了VideoInferenceWorker类，内部自动处理：

• 帧率自适应（根据推理耗时动态调整requestVideoFrameCallback间隔）；
• 帧丢弃策略（当推理延迟 > 2 帧时，跳过中间帧，只处理最新帧）；
• 内存泄漏防护（ImageBitmap使用后立即close()）。

实测在 iPhone 12 上，开启 30FPS 视频流推理，主线程 FPS 保持 58-60，无卡顿。

3.6 模型加载：如何让 12MB 的 WASM 在 3 秒内可用

WASM 模块体积大，传统fetch().then(wasmBytes => WebAssembly.instantiate())会阻塞主线程。我们的分阶段加载策略：

1. 预加载（Preload）：在页面初始化时，用<link rel="preload" href="model.wasm" as="fetch">提前建立连接；
2. 流式编译（Streaming Compile）：WebAssembly.compileStreaming(fetch('model.wasm'))，边下载边编译；
3. 内存预分配（Memory Pre-allocation）：WASM 模块声明memory: { initial: 256, maximum: 1024 }，避免运行时扩容；
4. 实例懒创建（Lazy Instantiation）：WASM module 编译完成后，不立即instantiate()，待用户点击“开始检测”时再创建实例，节省初始内存。

组合使用后，12MB WASM 在 4G 网络下平均加载时间为 2.7s，95% 分位低于 3.2s。

3.7 精度保障：浏览器浮点差异的终极对策

不同浏览器的Math.sin()、Math.exp()实现精度不同，导致同一模型在 Chrome/Safari 上输出差异达 0.003。这对分类任务影响小，但对回归任务（如关键点坐标预测）致命。

我们的对策是：在 WASM 中嵌入 IEEE 754 标准浮点库。具体做法：

• 用 Rust 编写f32::sin()、f32::exp()等函数，确保跨平台一致性；
• 编译为 WASM 时，禁用--no-float-abi，强制使用软浮点；
• 在 JS 层，所有涉及数学运算的 Tensor 操作（如tf.mul()、tf.exp()）均代理到 WASM 函数。

实测表明，同一模型在 Chrome 122/Safari 17.4/Edge 122 上的输出差异从 0.003 降至 1e-7，满足工业级精度要求。

4. 实操过程：从零搭建一个端侧人脸检测系统（含完整代码）

4.1 环境准备：最小可行技术栈

我们放弃复杂的构建工具链，用最简方式验证可行性：

• 模型选择：BlazeFace（Google 开源的轻量级人脸检测，ONNX 版本仅 2.1MB）；
• 运行时：ONNX Runtime Web（WASM 后端，兼容性最佳）；
• 构建工具：esbuild（零配置，10ms 完成打包）；
• 本地服务：npx serve -s dist（避免 CORS 问题）。

项目结构：

blazeface-web/ ├── src/ │ ├── model/ # ONNX 模型文件 │ ├── index.html # 主页面 │ ├── main.ts # 入口逻辑 │ └── inference.ts # 推理核心 ├── dist/ # 构建输出 └── package.json

关键依赖：

{ "dependencies": { "onnxruntime-web": "^1.17.0" }, "devDependencies": { "esbuild": "^0.19.0", "typescript": "^5.3.0" } }

提示：不要用 Webpack/Vite。它们的 HMR 会干扰 WASM 内存管理，导致RuntimeError: memory access out of bounds。esbuild 的纯静态打包，是端侧 AI 工程的黄金标准。

4.2 模型转换与优化：从 PyTorch 到浏览器就绪

BlazeFace 原始 PyTorch 模型需三步改造：

Step 1：移除训练专用算子
原始模型含torch.nn.functional.interpolate(mode='bilinear')，ONNX 导出后生成Resize算子，但 ONNX Runtime Web 不支持coordinate_transformation_mode='half_pixel'。解决方案：用torch.nn.Upsample替代，并指定mode='bilinear'和align_corners=False。

Step 2：固化输入 shape
BlazeFace 支持动态 batch，但浏览器要求固定 shape。修改导出脚本：

dummy_input = torch.randn(1, 3, 128, 128) # 强制 batch=1, size=128x128 torch.onnx.export(model, dummy_input, "blazeface.onnx", input_names=["input"], output_names=["scores", "boxes"], opset_version=12, # 关键：禁用 dynamic_axes )

Step 3：ONNX 优化
用onnxsim简化计算图，再用onnxruntime-tools量化：

# 安装工具 pip install onnxsim onnxruntime-tools # 简化 python -m onnxsim blazeface.onnx blazeface-sim.onnx # INT8 量化（使用默认 calibration dataset） python -m onnxruntime_tools.quantization.calibrate --input blazeface-sim.onnx \ --output blazeface-int8.onnx --calibrate_method MinMax

最终得到blazeface-int8.onnx，体积 1.3MB，精度损失 <0.5%（COCO AP）。

4.3 核心推理代码：72 行实现稳定人脸检测

src/inference.ts是整个系统的心脏，以下是精简后的核心逻辑（已去除日志和错误处理）：

import * as ort from 'onnxruntime-web'; // 1. 初始化会话（单例） let session: ort.InferenceSession | null = null; export async function initModel(): Promise<void> { // 使用 wasm 后端，禁用 webgl（避免 safari 兼容问题） const wasmOptions: ort.WasmSessionOptions = { graphOptimizationLevel: 'all', executionProviders: ['wasm'], }; session = await ort.InferenceSession.create('./model/blazeface-int8.onnx', wasmOptions); } // 2. 预处理：canvas → tensor export function preprocess(canvas: HTMLCanvasElement): ort.Tensor { const ctx = canvas.getContext('2d')!; const imageData = ctx.getImageData(0, 0, 128, 128); const pixels = imageData.data; // RGB → BGR, 归一化, reshape to [1,3,128,128] const data = new Float32Array(1 * 3 * 128 * 128); for (let i = 0; i < 128 * 128; i++) { const r = pixels[i * 4 + 0]; const g = pixels[i * 4 + 1]; const b = pixels[i * 4 + 2]; data[i * 3 + 0] = b / 255.0; // B data[i * 3 + 1] = g / 255.0; // G data[i * 3 + 2] = r / 255.0; // R } return new ort.Tensor('float32', data, [1, 3, 128, 128]); } // 3. 推理 export async function detectFaces( inputTensor: ort.Tensor ): Promise<{ boxes: number[]; scores: number[] }> { if (!session) throw new Error('Model not initialized'); // 执行推理 const feeds: Record<string, ort.Tensor> = { input: inputTensor }; const outputMap = await session.run(feeds); // 解析输出（blazeface 输出：scores[1,896], boxes[1,896,16]） const scores = Array.from(outputMap.scores.data as Float32Array); const boxes = Array.from(outputMap.boxes.data as Float32Array); // NMS 后处理（简化版，仅 CPU 实现） const nmsResults = nms(boxes, scores, 0.5, 0.3); return { boxes: nmsResults.boxes.flat(), scores: nmsResults.scores, }; } // 4. NMS 实现（关键：避免创建新数组） function nms(boxes: number[], scores: number[], iouThreshold: number, scoreThreshold: number) { const keep: number[] = []; const order = scores.map((s, i) => i).sort((a, b) => scores[b] - scores[a]); for (const i of order) { if (scores[i] < scoreThreshold) continue; let keepIt = true; for (const j of keep) { const iou = computeIOU(boxes.slice(i * 16, i * 16 + 4), boxes.slice(j * 16, j * 16 + 4)); if (iou > iouThreshold) { keepIt = false; break; } } if (keepIt) keep.push(i); } return { boxes: keep.map(i => boxes.slice(i * 16, i * 16 + 4)), scores: keep.map(i => scores[i]), }; } function computeIOU(boxA: number[], boxB: number[]): number { const xA = Math.max(boxA[0], boxB[0]); const yA = Math.max(boxA[1], boxB[1]); const xB = Math.min(boxA[2], boxB[2]); const yB = Math.min(boxA[3], boxB[3]); const interArea = Math.max(0, xB - xA) * Math.max(0, yB - yA); const boxAArea = (boxA[2] - boxA[0]) * (boxA[3] - boxA[1]); const boxBArea = (boxB[2] - boxB[0]) * (boxB[3] - boxB[1]); return interArea / (boxAArea + boxBArea - interArea); }

实操心得：NMS 必须手写，不能用tf.image.nonMaxSuppression()。因为 TF.js 的 NMS 是 WebGL 实现，会创建临时纹理，而 BlazeFace 的 896 个候选框在低端机上极易触发内存溢出。我们这段纯 JS NMS，耗时仅 1.2ms（iPhone SE 2020），且内存零分配。

4.4 页面集成：30 行 HTML 实现实时检测

index.html极简设计，突出工程实用性：

<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>BlazeFace Web</title> <style> body { margin: 0; overflow: hidden; } #video { width: 100vw; height: 100vh; object-fit: cover; } #canvas { position: absolute; top: 0; left: 0; } </style> </head> <body> <video id="video" autoplay muted playsinline></video> <canvas id="canvas"></canvas> <script type="module"> import { initModel, preprocess, detectFaces } from './main.js'; // 1. 初始化模型（页面加载时） initModel().then(() => console.log('Model loaded')); // 2. 获取摄像头 navigator.mediaDevices.getUserMedia({ video: true }) .then(stream => { const video = document.getElementById('video'); video.srcObject = stream; // 3. 实时推理循环 const canvas = document.getElementById('canvas'); const ctx = canvas.getContext('2d'); function loop() { if (video.readyState === video.HAVE_ENOUGH_DATA) { // 设置 canvas 尺寸匹配视频 canvas.width = video.videoWidth; canvas.height = video.videoHeight; // 绘制视频帧到 canvas ctx.drawImage(video, 0, 0, canvas.width, canvas.height); // 预处理 & 推理 const input = preprocess(canvas); detectFaces(input).then(result => { // 绘制检测框（省略绘制代码） drawBoxes(ctx, result.boxes, result.scores); }); } requestAnimationFrame(loop); } loop(); }); </script> </body> </html>

关键细节：

• playsinline属性确保 iOS 全屏播放；
• requestAnimationFrame保证与屏幕刷新率同步；
• video.readyState === video.HAVE_ENOUGH_DATA防止首帧未加载就绘图。

4.5 性能调优：实测数据与参数对照表

我们在 5 款设备上实测 BlazeFace Web 的性能，结果如下：

设备型号	浏览器	分辨率	平均帧率	首帧延迟	内存峰值	备注
iPhone 12	Safari 17.4	1280×720	22.3 FPS	184ms	312MB	启用 WebNN 后提升至 28.7 FPS
Pixel 6	Chrome 122	1080×720	29.1 FPS	142ms	287MB	WebGL 后端
iPad Air 4	Safari 17.4	2160×1620	18.6 FPS	210ms	405MB	OffscreenCanvas + Worker
Mi 11	Chrome 121	1440×1080	15.2 FPS	267ms	368MB	WASM 后端，启用 SIMD
MacBook Pro M1	Chrome 122	1920×1080	32.8 FPS	98ms	245MB	WebNN + Neural Engine

关键调优参数：

• WASM SIMD：在package.json中添加"onnxruntime-web": {"wasm": {"simd": true}}，M1/M2 芯片性能提升 35%；
• WebGL 纹理格式：gl.RGBA32F比gl.RGBA精度高，但内存翻倍，低端机慎用；
• NMS 阈值：scoreThreshold=0.5保证召回率，iouThreshold=0.3防止框重叠。

注意：不要迷信“最高帧率”。在工业场景中，我们常将帧率锁定在 15FPS，因为更高帧率会增加