浏览器端跑YOLOv8：基于ONNX Runtime Web的前端目标检测实战

1. 为什么要在浏览器里跑YOLOv8——前端推理的实用场景与可行性

1.1 什么场景下"浏览器跑模型"是真需求

先说一个反直觉的结论：并不是所有目标检测任务都需要上服务器。很多人一听“浏览器跑YOLOv8”，第一反应是“性能不够”、“不如直接用Python写后端”，但实际业务里有一类情况，浏览器端推理的价值是后端方案替代不了的——隐私敏感、低延迟预览、离线可用、以及不想为一次性演示搭建GPU服务。

我做过一个车间质检的Demo，需要让产线工人用手机浏览器对着零件拍照，立即识别表面缺陷。数据不能出车间，不可能把图片传到云端。这时候浏览器端跑模型几乎是唯一选择。另一个典型场景是文档扫描类工具：在本地预览框里实时框出证件、票据的边缘，用户还没点击上传，检测结果就已经画在画面上了。这类“预处理型”检测不要求最高精度，但要求零等待、不占服务器带宽，浏览器推理刚好覆盖。

所以我的判断标准很简单：如果模型运行结果只影响当前用户、不需要跨设备共享，且对延迟要求很高，前端推理就是合理架构。ONNX Runtime Web是目前把这件事做的最省心的方案之一——它能加载YOLOv8导出的标准ONNX模型，在浏览器里通过WebAssembly或WebGPU执行，不需要懂C++也不需要碰TensorFlow.js那套独立生态。

1.2 ONNX Runtime Web的前世今生：WebAssembly与WebGL/WebGPU的取舍

ONNX Runtime Web本质上是ONNX Runtime在浏览器端的编译产物。它有两种执行后端：一种是走WebAssembly（WASM），纯CPU计算；另一种走WebGL或WebGPU，利用GPU加速。WASM后端兼容性最好，几乎所有现代浏览器都能跑，但在手机上跑YOLOv8这种模型还是比较吃力，所以实际项目里我一般优先走WebGPU，实在兼容不了再降级到WASM。

这里要理解一个关键点：WebGPU不是WebGL的替代者，而是更现代的GPU抽象层。WebGL2能做的事很有限，主要是纹理上传和片段着色器计算，ONNX Runtime Web在WebGL后端下会把很多算子拼成纹理采样操作，效率勉强能用；WebGPU则支持compute shader，跟原生GPU计算更接近，执行YOLOv8的卷积算子要快得多。从我的实测看，在MacBook Air M1上，用WebGPU跑YOLOv8s，推理时间大概在15~25ms左右，而WASM后端要100ms以上，差距非常明显。

不过要注意，WebGPU目前（2025年前后）在Safari和部分安卓WebView里支持还不完整。如果你做的产品要覆盖大量存量用户，最好做成“优先WebGPU、失败自动降级WASM”的加载策略。这一点在后面的工程化部分我再展开说。另外，ONNX Runtime Web并不要求你前端懂什么底层原理，它把模型图和算子都封装好了，你只需要关心输入输出张量怎么组织——这也是它比直接手写WebGL着色器方案更可行的原因。

2. 环境准备与模型导出：把YOLOv8的PyTorch模型转为ONNX

2.1 导出ONNX前的关键配置（opset、动态维度、简化）

从PyTorch导出ONNX，最重要的三个选择是opset版本、输入维度是否动态、以及是否做模型简化。opset决定ONNX算子集的版本，ONNX Runtime Web对不同opset的支持有差异，实测opset 12到17之间都挺稳，我习惯用16。动态维度的问题要单独说：YOLOv8的输入通常固定为640x640，导出时如果你用dynamic_axes允许高度和宽度变化，模型会多出一堆Resize和Slice算子，前端处理起来复杂度暴增。而且ONNX Runtime Web对动态shape支持的并不好，某些算子在动态shape下可能被优化掉导致输出size不对。所以我建议固定输入尺寸640x640，不做动态维度，前端一律resize到640再送入模型。

模型简化则依赖onnxsim，它会把一些冗余的Transpose、Reshape合并掉，减少模型体积和推理耗时。YOLOv8导出的原始ONNX里有一些训练时才用到的节点，简化后能去掉。这一步不是必须，但我强烈建议做，尤其是后面还要转INT8量化的情况。

2.2 手把手导出并验证ONNX模型

我用的是Ultralytics官方提供的导出脚本，其实你只需要装好ultralytics包，然后执行：

bash复制yolo export model=yolov8s.pt format=onnx imgsz=640 opset=16 simplify=True

这条命令会在yolov8s.onnx存放路径下生成简化后的ONNX模型。如果你的环境里没有CUDA，纯CPU导出也没问题，它只是个图转换过程，不涉及训练。导出完成后，强烈建议用onnxruntime先在本机跑一次推理，确保输出张量没问题：

python复制import onnxruntime as ort
import numpy as np
from PIL import Image

session = ort.InferenceSession("yolov8s.onnx", providers=["CPUExecutionProvider"])
input_name = session.get_inputs()[0].name
# 构造一个640x640的随机RGB数据（0-255归一化到0-1）
dummy = np.random.rand(1, 3, 640, 640).astype(np.float32) * 0.5
outputs = session.run(None, {input_name: dummy})
print(outputs[0].shape)  # 通常是(1, 84, 8400)

如果输出shape是(1, 84, 8400)