如何在浏览器里跑 ONNX 模型：ONNX Runtime Web 完整入门指南

如何在浏览器里跑 ONNX 模型ONNX Runtime Web 完整入门指南【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime上传一张照片给网页工具等服务器转一圈才返回结果——其实推理这一步本可以发生在你的浏览器里。ONNX Runtime Web 是 ONNX Runtime 官方提供的 JavaScript 库它把 C 推理引擎编译成 WebAssembly配合 WebGL / WebGPU 加速让 ONNX 模型免安装、免上传直接在浏览器完成推理。它能帮你做什么最典型的场景是敏感数据不想出端的处理。比如一个网页版的 OCR 或医学影像标注工具图片数据如果走服务器就要面对合规与隐私审查换成 ONNX Runtime Web 后推理在前端本地完成数据不离开浏览器天然省掉了这一层顾虑。第二类是实时交互类应用。图像分割、目标检测这类工具用户点一下就要看到结果传统请求—响应链路的网络延迟会被放大本地推理把往返时间压缩到毫秒级交互体验更接近桌面软件。这依赖的是 WASM 后端接近原生的执行速度以及 GPU 后端对大张量运算的并行加速。第三类是被低估的复用价值。同一套 JavaScript 推理代码在浏览器和 Node.js 里都能跑。你在浏览器端验证过的模型与参数可以直接搬到服务端或 CI 脚本里用 WASM 后端做离线批处理代码不用改两份。最小可用上手路径安装只需一条命令npm install onnxruntime-web下面这段代码演示最短的推理流程创建会话、构造一个输入张量、执行推理并读取输出。输入名请替换成你模型里的实际名字可用 ONNX 工具查看模型输入。import * as ort from onnxruntime-web; const session await ort.InferenceSession.create(model.onnx, { executionProviders: [wasm], graphOptimizationLevel: all }); const input new ort.Tensor(float32, new Float32Array(784), [1, 1, 28, 28]); const outputs await session.run({ /* 模型输入名: input */ input }); console.log(outputs[Object.keys(outputs)[0]].data);从创建会话到拿到输出核心就是这两步。graphOptimizationLevel: all让引擎尽量做图优化默认值就可以这里显式写出便于理解。怎么选、怎么配ONNX Runtime Web 里执行后端叫 EPExecution Provider执行提供器。模型加载后图会被切分能交给某个 EP 的子图就走该 EP剩下的回落最终按优先级并行执行四个后端怎么选先看这张表你的场景推荐配置原因算子覆盖不确定、以 NLP 模型为主executionProviders: [wasm]WASM 后端覆盖 ai.onnx / ai.onnx.ml 全量算子还兼容量化模型最不容易踩坑Chrome / Edge 上的视觉模型executionProviders: [webgpu]低延迟 GPU 访问性能优于已进维护模式的 WebGL需要兼容 iOS、Safari 或老设备[webgpu, wasm]或直接[wasm]WebGPU 在 iOS 与 Safari 上不可用WASM 是唯一全覆盖选项Node.js 环境复用同一套代码默认 WASM 单线程Node.js 只支持单线程 WASM EP无法多线程几个分场景的补充建议WASM 线程数不设置时默认取min(4, 逻辑核数 / 2)并且只有浏览器环境才启用。需要调大时在创建会话前设置ort.env.wasm.numThreads 4;即可不要超过物理核心数。WebGPU 的 FP16Float16 精度需要 Chrome 121 或 Edge 122Windows 下 WebGPU 本身要求 Chromium 113。低配浏览器上建议显式关闭 FP16避免精度路径不一致。WebNN目前标记为实验特性且需要浏览器以--enable-featuresWebMachineLearningNeuralNetwork启动不适合直接面向最终用户。常见坑与处理现象用了webgl后端控制台出现弃用警告且后续版本算子不再新增。原因WebGLonnxjs后端已进入维护模式仓库明确推荐转向 WebGPU。解法新项目直接用webgpu无法使用 WebGPU 的老环境回落wasm。现象同样的模型在桌面 Chrome 正常在 iPhone Safari 上创建会话失败。原因WebGPU 暂不支持 Safari 与 iOS。解法executionProviders按[webgpu, wasm]顺序给出引擎会自动回落或在特性检测后直接走 WASM。现象同一份代码搬到 Node.js 里推理明显变慢。原因Node.js 只支持单线程 WASM EP多线程不生效。解法预期内就按单线程评估性能多线程需求保留在浏览器端或用其他部署形态跑批处理。现象模型文件几十 MB首屏加载明显卡顿。原因原始 ONNX 体积大且未压缩。解法先做静态量化压缩模型体积再对.onnx开启 gzip浏览器传输层并把模型拉取放在requestIdleCallback这类空闲时机执行避免阻塞首屏。现象配置了 WebNN 却没有任何效果。原因它仍是实验特性浏览器默认关闭。解法确认启动参数带了--enable-featuresWebMachineLearningNeuralNetwork并只在内测流程中使用不要作为生产依赖。写在最后如果你的模型能导出成 ONNX 格式而用户又在意加载速度或数据不出端ONNX Runtime Web 是目前浏览器端最省事的选择WASM 兜底、WebGPU 提速一条配置就能覆盖大多数浏览器。下一步可以先从仓库里的官方示例跑通一个最小模型再对照算子清单确认你的模型能完全落在目标后端上。文档入口js/web/README.md含各平台兼容性矩阵可运行示例samples/nodejs/01_basic-usage/WebGPU 算子清单js/web/docs/webgpu-operators.mdWebGL 算子清单js/web/docs/webgl-operators.md【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考