模型评测在工程里通常被当成一件“后台任务”来处理准备好数据集租一台带 GPU 的机器拉代码、装环境、跑脚本最后把指标写进表格。Trunchbull 这个项目换了一个角度把“真实模型 任意基准集”评测直接放进浏览器。用户在页面上选择模型文件和基准数据推理在本机浏览器内完成评测结果当场就能看到。这个思路对需要对比模型、验证数据集、或者不想把数据交给第三方服务的人来说很有吸引力。从项目标题里的 Show HN 可以看出它更像一个面向开发者社区的实验性工具而非企业级评测平台。真正吸引人的不是“多了一个评测网站”而是它把模型推理、基准数据加载、指标统计和结果展示压缩到了浏览器端。本文围绕这个思路展开三部分内容先讲清浏览器评测的技术链路再给出一套最小可运行实现最后整理运行验证、常见问题和工程化建议。即使你不打算直接用 Trunchbull这套模式也能帮你理解浏览器端模型推理的边界。1. 先理解 Trunchbull 解决的核心问题模型评测为什么折腾1.1 传统评测的成本集中在环境而不是模型本身常规的模型评测流程看起来不复杂下载公开基准集写好推理脚本加载模型权重批量跑前向计算最后统计准确率、F1 或困惑度等指标。真正跑起来之后问题往往集中在环境上。模型格式不统一需要先做转换或适配。推理框架依赖特定 CUDA 版本、Python 版本和第三方库。数据集文件可能很大下载、解压、预处理都要时间。多人协作时每个人本地的依赖版本不一致评测结果难以对齐。如果使用在线评测 API还需要考虑数据上传和隐私问题。这些成本里最浪费时间的不是模型前向计算本身而是“让评测环境可用”这一步。Trunchbull 的思路之所以有价值是因为它把环境简化成了浏览器只要浏览器支持相应的 Runtime模型和数据都从本地或静态 URL 加载评测就基本可复现。1.2 “真实模型”和“任意基准集”指的是什么标题里有两个关键词需要拆开理解。“真实模型”指的是真正加载模型权重文件对每条基准样本执行完整的前向计算而不是用规则、预计算分数或简化网络代替。准确率、延迟、内存占用这些指标只有建立在真实推理上才有意义。“任意基准集”指的是评测数据不是写死在工具里的而是由使用者自行提供。可以是公开的图片分类集、文本分类集、某项业务自建的小样本集也可以是几条用于冒烟测试的示例数据。工具本身不判断基准集是否合理只负责按统一流程跑完并报告结果。1.3 浏览器评测的边界也要提前说清楚浏览器不是万能的。以下场景更适合浏览器评测模型体量较小权重文件在几十 MB 到几百 MB 之间。基准集可以分页或按需加载不需要一次性装入内存。关注推理延迟、吞吐量、量化前后差异等相对指标。需要保护数据隐私数据不希望离开本机。以下场景现阶段尽量避开百亿参数以上的大模型浏览器内存和显存都难以承载。超大基准集比如百万级样本客户端逐条跑完耗时过长。对硬件环境要求完全一致的精确评测因为浏览器会受到设备、后台任务和浏览器版本影响。注意浏览器评测更适合“快速对比”和“初步验证”不建议作为唯一依据来决定生产环境的模型选型。正式发布前仍然要在服务器上做一轮受控测试。2. 在浏览器跑“真实模型”依赖哪几条技术链路2.1 WebAssembly 和 WebGPU 是底座浏览器本身不能直接执行 Python 训练框架导出的模型文件需要一个能运行神经网络运算的运行时。当前主流路径有两类WebAssemblyWASM把推理算子编译成浏览器可执行的二进制指令通过 SIMD 指令和多线程优化获得接近原生 CPU 的推理速度。WebGPU调用浏览器暴露的 GPU 能力适合矩阵计算密集的模型。WebGL 是老一代方案兼容性好但能力弱现在更多作为回退选项。WebAssembly 的特点是“稳”几乎所有现代浏览器都支持WebGPU 的特点是“快”但浏览器覆盖和版本差异比 WASM 大。实际实现里通常会做一个自动选择优先 WebGPU不可用时回退到 WASM。2.2 模型需要先转换成浏览器 Runtime 能识别的格式不同推理运行时对应不同模型格式。常见组合关系如下运行时主要模型格式适用场景ONNX Runtime WebONNX分类、检测、OCR、语音模型来源丰富Transformers.js转换后的模型文件文本分类、摘要、嵌入等 NLP 任务llama.cpp Web 构建GGUF本地运行小型 LLMTensorFlow.jsTF SavedModel / Layers老项目迁移、前端已有 TF 生态实际使用中要注意模型导出为 ONNX 时如果输入是动态长度需要打开动态轴dynamic axes选项否则推理时固定序列长度会带来很大限制。模型量化fp16、int8、int4能显著减小体积和提升速度但会带来精度损失评测时最好同时跑原始精度和量化版本对比差异。2.3 不要把“跑通推理”和“完成评测”混为一谈很多人在浏览器里加载模型成功后就认为评测功能完成了。实际上评测还包含三件容易被忽略的事数据加载和预处理是否正确图片要 resize、归一化文本要 tokenize特征顺序要一致。推理结果如何映射成指标得到 logits 之后要判断是取 argmax、做 softmax还是按阈值分类。延迟统计是否可靠第一次推理包含初始化开销必须做 warmup否则测出来的延迟会明显偏高。这三件事任何一个出错最终指标都会“看起来很对但经不起复现”。下一部分开始动手实现会把这些点逐一落到代码里。3. 环境准备浏览器、构建工具和最小项目骨架3.1 先确认浏览器的能力边界不同浏览器的推理能力差异很大尤其是 WebGPU 和多线程支持。建议在项目文档里放一张能力表格让使用者在跑评测前先自查能力Chrome/EdgeFirefoxSafari影响WebAssembly支持支持支持基础推理能力WASM SIMD支持支持支持显著提升 CPU 推理速度SharedArrayBuffer需要跨源隔离需要跨源隔离支持多线程推理必需WebGPU支持正在推进部分支持GPU 加速API 仍在演进这里最需要注意的是 SharedArrayBuffer。如果要用多线程 WASM 推理页面必须设置跨源隔离响应头Cross-Origin-Opener-Policy: same-origin和Cross-Origin-Embedder-Policy: require-corp。没有这两个头多线程初始化会直接报错但设置了 require-corp 之后页面引用的外部资源又必须允许跨源访问。这是一对经常让人卡住的连锁问题。3.2 最小依赖选择Vite TypeScript ONNX Runtime Web为了把实现聚焦在评测逻辑上下面用 Vite 作为构建工具TypeScript 写代码推理运行时采用 ONNX Runtime Web。这是一个覆盖面广、文档完整、容易替换成其他 Runtime 的组合。示例package.json{ name: browser-benchmark-skeleton, private: true, type: module, scripts: { dev: vite, build: vite build, preview: vite preview }, dependencies: { onnxruntime-web: ^1.18.0 }, devDependencies: { typescript: ^5.4.0, vite: ^5.2.0 } }Vite 只是一个示例选择如果你更熟悉 Webpack 或 esbuild也可以替换。重点是要保证 WASM 文件能被正确加载以及开发服务器的响应头配置正确。3.3 目录结构按“模型、数据、代码、页面”分开建议目录结构如下browser-benchmark-skeleton/ ├─ public/ │ ├─ models/ │ │ └─ model.onnx │ └─ data/ │ └─ benchmark.jsonl ├─ src/ │ ├─ main.ts │ └─ benchmark.ts ├─ index.html ├─ package.json ├─ tsconfig.json └─ vite.config.ts模型和基准数据放在public/下是为了让浏览器通过静态 URL 直接访问。正式项目里模型文件可能来自对象存储基准数据可能来自接口但本地开发用静态文件最方便调试。Vite 配置要处理两件事把 ONNX Runtime 的 WASM 文件复制到可访问目录以及让开发服务器返回跨源隔离响应头。示例配置如下import { defineConfig } from vite; import { viteStaticCopy } from vite-plugin-static-copy; export default defineConfig({ plugins: [ viteStaticCopy({ targets: [ { src: node_modules/onnxruntime-web/dist/*.wasm, dest: wasm } ] }) ], server: { headers: { Cross-Origin-Opener-Policy: same-origin, Cross-Origin-Embedder-Policy: require-corp } } });如果不想引入额外的复制插件也可以把 WASM 文件直接放到public/目录然后用配置参数指定路径。关键是确保运行时能找到对应版本的 WASM 文件版本不匹配时浏览器会给出难以理解的初始化错误。4. 最小可运行在浏览器里加载模型并对基准集跑推理4.1 基准数据格式建议用 JSONL一次推理需要一条样本一条样本至少包含唯一编号、输入内容、期望输出。对于文本分类任务可以用 JSONL 格式每行一个 JSON 对象{id: sample-0001, text: 这家餐厅的菜品很新鲜, label: positive} {id: sample-0002, text: 等待时间太长了, label: negative}这里的字段名可以根据模型调整。图片分类则可以换成图片 URL 或 Base64 数据。无论什么格式读取后都要先统一成内存里的结构体避免在推理循环里反复处理字符串。export interface BenchmarkItem { id: string; input: number[] | string; expected: string; } export interface BenchmarkOutput { itemId: string; prediction: string; correct: boolean; latencyMs: number; }4.2 初始化推理 SessionONNX Runtime Web 创建一个 Session本质上就是加载模型并解析其计算图。代码里需要注意三个参数执行提供者优先级、图优化级别、缓存选项。import * as ort from onnxruntime-web; export async function loadModel(modelUrl: string) { const session await ort.InferenceSession.create(modelUrl, { executionProviders: [webgpu, wasm], graphOptimizationLevel: all, enableCpuMemArena: true }); return session; }这里把执行提供者顺序设为[webgpu, wasm]意思是浏览器支持 WebGPU 时优先使用否则自动回退到 WASM。graphOptimizationLevel: all会开启尽可能多的计算图优化对提升推理速度有帮助但如果模型本身有特殊算子遇到问题可以先降级为basic对比。4.3 加入 warmup 并执行评测循环评测循环的核心不只是“跑 N 次推理”而是保证每次推理都是可比较的。这里要处理几个隐藏问题输入张量的数据类型、内存复用、warmup 次数、异常隔离。import type { InferenceSession, Tensor } from onnxruntime-web; import type { BenchmarkItem, BenchmarkOutput } from ./benchmark; async function runBenchmark( session: InferenceSession.InferenceSession, items: BenchmarkItem[], warmupRounds 1 ): PromiseBenchmarkOutput[] { // 先跑 warmup排除第一次初始化、算子编译和缓存冷启动的开销 for (let i 0; i warmupRounds; i) { const dummyInput new ort.Tensor(float32, new Float32Array(64), [1, 64]); await session.run({ input: dummyInput }); } const results: BenchmarkOutput[] []; for (const item of items) { const start performance.now(); try { const inputTensor: Tensor toTensor(item.input); const feeds { input: inputTensor }; const outputs await session.run(feeds); const prediction decodeOutput(outputs); const latencyMs performance.now() - start; results.push({ itemId: item.id, prediction, correct: prediction item.expected, latencyMs }); } catch (error) { console.error(推理失败${item.id}, error); results.push({ itemId: item.id, prediction: ERROR, correct: false, latencyMs: 0 }); } } return results; } function toTensor(input: number[] | string): Tensor { // 简化实现实际项目需要在这里完成词表映射或图片预处理 const data new Float32Array(input.length); input.forEach((value, index) { data[index] Number(value); }); return new ort.Tensor(float32, data, [1, input.length]); } function decodeOutput(outputs: Recordstring, Tensor): string { // 简化实现取 logits 最后一维 argmax const logits Object.values(outputs)[0].data as Float32Array; let bestIndex 0; let bestValue -Infinity; for (let i 0; i logits.length; i) { if (logits[i] bestValue) { bestValue logits[i]; bestIndex i; } } return String(bestIndex); }这个示例把toTensor和decodeOutput做了最简处理。实际项目中文本模型必须引入 tokenizer图片模型必须做 resize 和归一化。这里最重要的是评测循环的结构warmup、计时、异常隔离、结果收集这四个环节缺一不可。注意session.run返回的 Tensor 数据在异步处理过程中不要直接复用底层缓冲区否则下一次推理可能覆盖上次的数据。4.4 在页面上输出汇总结果评测跑完后需要把原始结果和汇总指标展示出来。汇总指标至少包含总样本数、正确数、准确率、平均延迟、P95 延迟。export function summarize(results: BenchmarkOutput[]) { const total results.length; const correct results.filter((r) r.correct).length; const latencies results.map((r) r.latencyMs).sort((a, b) a - b); const p95Index Math.min(latencies.length - 1, Math.floor(latencies.length * 0.95)); return { total, correct, accuracy: total 0 ? correct / total : 0, avgLatencyMs: latencies.length 0 ? latencies.reduce((a, b) a b, 0) / latencies.length : 0, p95LatencyMs: latencies[p95Index] ?? 0 }; }页面里的展示逻辑很简单一个选择模型文件的按钮一个选择 JSONL 数据文件的按钮一个“开始评测”按钮以及一个结果表格。文件读取用FileReader或URL.createObjectURL都可以。评测是异步且耗时的操作建议在界面上显示进度避免用户认为页面卡死。5. 评测指标和关键参数怎么定才可信5.1 指标不是只有准确率准确率是最直观的指标但对于模型选型来说远远不够。至少需要区分三类指标指标类型代表指标回答的问题效果指标准确率、F1、AUC、困惑度模型预测得准不准性能指标平均延迟、P95 延迟、吞吐量模型跑得快不快资源指标内存占用、模型体积、GPU 显存模型能不能部署在目标设备上在浏览器环境里性能指标的波动比服务器环境大得多。同一台电脑浏览器后台开着视频、风扇降频、浏览器版本升级都会改变延迟结果。因此单次评测的延迟没有意义至少需要多次运行并观察分布。5.2 影响结果的关键参数速查表在浏览器评测场景以下参数最影响结果的可比性参数常见值作用设置不合适时的表现warmup 次数1 到 3预热算子、缓存、GPU 上下文平均延迟偏高前几条样本明显慢batch size1每次前向处理样本数太大时内存暴涨太小时吞吐量偏低执行提供者webgpu / wasm决定用 GPU 还是 CPUWebGPU 不可用时报错或回退失败精度fp32 / fp16 / int8权重和激活的数值精度量化后准确率意外下降线程数默认WASM 多线程推理设置过高导致性能回退输入长度固定或动态影响计算量和显存固定长度过大浪费动态未打开则报错一个常见误区是“为了测准确率所以把 batch size 调大”。准确率和 batch size 理论上无关除非模型内部有依赖 batch 的统计操作。性能指标才需要关注 batch size。实际评测时准确率评测用 batch size 1 最稳妥性能指标再单独做 batch 扫描。5.3 浏览器评测与服务器评测的差异要写进报告同类模型在浏览器和服务器上跑出的准确率应该基本一致但延迟和吞吐量会有数量级差异。差异来源包括浏览器 Runtime 的算子实现未完全覆盖某些模型会回退到 fallback kernel。WebGPU 的 GPU 调度和 CUDA 不同显存管理策略也不同。WASM 多线程需要跨源隔离缺头时单线程运行会显著变慢。浏览器后台任务、定时器、动画帧都可能抢占执行时间。因此评测报告里除了指标还要记录浏览器名称、版本、操作系统、是否启用 WebGPU、模型格式、量化精度、数据文件和切换逻辑否则换一个人运行同一套评测结果往往对不上。6. 运行验证怎么判断一次评测是可信的6.1 先用小样本验证正确性再跑完整基准集第一次跑评测不要直接加载上千条数据。建议先用 5 到 10 条样本确认流程正确检查以下问题每条样本是否进入了模型推理而不是被异常跳过。输出的标签是否和手工推理结果一致。延迟数据是否在合理区间而非第一轮异常高、后续异常低。错误样本的日志是否能定位到具体输入。要特别警惕全流程“顺利跑完”但准确率接近随机的情况。这种状况通常是预处理和模型训练时的预处理不一致导致的比如归一化参数、图像通道顺序、文本截断方式。此时需要把模型在服务器端用原生框架跑同样的输入做对比找出差异。6.2 通过浏览器开发者工具确认资源状态评测过程中打开开发者工具确认三件事Network 面板里模型文件和 WASM 文件是否加载成功有没有 404 或 CORS 错误。Console 面板有没有未捕获的异常特别是 WebGPU 创建失败、SharedArrayBuffer 头部缺失。Performance 面板在评测期间有没有出现明显的长任务、GC 抖动或后台任务抢占。这三项任何一个有问题评测结果都可能是“跑通了但不可比”。6.3 建立可复现评测检查清单发布评测功能前建议按下面的清单检查一遍模型文件版本有记录模型哈希可计算。基准数据文件版本有记录样本数量明确。浏览器名称和版本能自动采集并写入报告。runtime 版本和 WASM 文件版本一致。评测前执行过 warmup。每条样本的输入和输出能追溯到原始数据。多次运行结果在合理误差范围内。异常样本单独记录不计入不细分。结果导出为 JSON包含所有元信息。这个清单既适用于 Trunchbull 这类浏览器工具也适用于任何要对外发布的自动化评测脚本。7. 常见问题排查从现象倒推原因浏览器评测的问题通常集中在加载、初始化、推理和结果四个阶段。下面按频率列出最常见的现象和排查路径。问题现象可能原因检查方式处理建议控制台报 CORS 错误模型或数据来自其他域名未允许跨源Network 面板看响应头静态资源允许 CORS或同源部署WASM 文件 404WASM 路径配置不对版本不匹配Network 面板看请求 URL复制正确版本的 wasm 到 public 目录SharedArrayBuffer 未定义缺少跨源隔离响应头检查 Network 响应头配置 COOP/COEP 头WebGPU 初始化失败浏览器版本不支持或设备被禁用控制台查navigator.gpu回退到 WASM 执行提供者推理结果全为 NaN输入未归一化、精度过低、除零打印输入张量数值范围检查预处理和量化设置延迟忽高忽低浏览器后台任务、GC、降频Performance 面板多跑几轮取分位数避免后台标签页模型文件几百 MB页面卡死一次性读取了大文件Memory 面板看堆内存改用流式加载并限制模型大小同一模型两次准确率不同存在随机性或数据顺序变化检查 tokenizer 和采样参数固定随机种子统一预处理7.1 跨源隔离头导致外部资源失败这是最典型的连锁问题。为了让 WASM 多线程可用页面设置了Cross-Origin-Embedder-Policy: require-corp但模型文件正好放在 CDN 上CDN 的响应头没有Access-Control-Allow-Origin或Cross-Origin-Resource-Policy于是模型加载失败。排查顺序是先去掉 COEP 头确认模型能加载再重新加回头逐一看静态资源是否都允许跨源。不要同时改多个配置否则很难定位是哪个响应头引起的。7.2 动态输入形状报错ONNX 模型如果导出时输入维度固定比如文本输入是[1, 128]那么传入长度 64 的样本会直接报维度不匹配。处理方式有两种导出模型时打开动态轴让seq_len维度为动态。推理前把所有文本 pad 到固定长度并用 attention mask 屏蔽 padding 部分。第二种方式实现简单但固定长度过大会浪费计算量。评测工具最好两种都支持并在 UI 上显示当前模型的输入签名。7.3 评测过程中页面被后台化延迟失真浏览器为了省电会降低后台标签页的定时器精度和渲染频率。如果评测在中途切换标签页测出的延迟会包含大量调度延迟不可信。预防做法评测开始前提示用户保持标签页前台在结果报告里记录评测耗时和浏览器 visibility 状态延迟指标使用 P95 而不是平均值受单个长任务影响更小。8. 工程化建议和扩展方向8.1 评测配置要外置不要写死在代码里模型 URL、数据 URL、warmup 次数、执行提供者顺序、量化精度这些都应该从页面 UI 或 JSON 配置中读取而不是写在源码里。推荐设计一份评测配置{ model: { url: /models/model.onnx, provider: webgpu, fallbackProvider: wasm, precision: fp32 }, benchmark: { dataUrl: /data/benchmark.jsonl, warmupRounds: 2, timeoutMs: 10000 }, output: { includeRawResults: false, saveToLocal: true } }配置外置的好处是复用同一个前端页面可以测多个模型和多个数据集不需要改代码重新构建。8.2 结果导出要包含元信息评测结果的 JSON 不能只有一组准确率和延迟还要包含恢复现场所需的全部信息。推荐结构如下{ summary: { accuracy: 0.923, avgLatencyMs: 12.4, p95LatencyMs: 21.8, total: 1000, correct: 923 }, environment: { browser: Chrome 126, platform: Windows 11, webgpu: true, runtimeVersion: onnxruntime-web 1.18.0, modelHash: sha256:... }, config: { modelUrl: /models/model.onnx, dataUrl: /data/benchmark.jsonl, warmupRounds: 2 }, failures: [] }模型文件的哈希是很多人忽略的字段。没有哈希几个月后很难确认当前评测到底用的哪个权重文件。8.3 扩展方向按需求和资源分批实现如果要在 Trunchbull 思路的基础上继续扩展可以按下面的优先级考虑接入 Web Worker把推理放到 worker 线程避免阻塞 UI。多会话并发多个模型并行评测对比同一份基准集上的差异。数据懒加载大基准集分页读取避免一次加载全部样本。结果可视化输出混淆矩阵、分类错误样本列表、延迟分布直方图。自动重跑支持一键重跑多次并给出均值和置信区间。接入自动化测试用 Playwright 无头浏览器跑完整评测把结果作为回归报告。对于个人开发者和研究团队前两项已经能覆盖大部分日常对比需求。更重的功能要结合真实评测场景来决定不必一开始就做得像企业评测平台。8.4 学习环境和生产环境的差异要分清学习环境本地 Vite 开发服务器用静态模型文件和小数据集跑通流程即可。测试环境固定浏览器版本使用 CI 容器配合 Playwright 记录自动化截图和报告。生产环境模型和数据走对象存储并配置 CORS评测记录写入后端结果持久化失败样本单独存储。浏览器评测最大的优势是低门槛和隐私保护最大的风险是环境不可控。只要在报告里把环境信息记录完整把一次评测定义成“某浏览器、某版本、某配置下的结果”它就能成为模型选型和回归验证的有效工具。最后给一个实际建议不要急着把所有模型都塞进浏览器。先选一个你已经知道标准答案的小模型和一份小数据集把加载、推理、统计、导出全流程跑通再逐步扩展到更大的模型和更接近真实分布的基准集。这样遇到的每一个问题都能定位在具体环节上而不是像传统评测那样最后甩给你一堆依赖报错和版本冲突。
浏览器端模型评测实战：基于WebGPU与WASM的推理实现
模型评测在工程里通常被当成一件“后台任务”来处理准备好数据集租一台带 GPU 的机器拉代码、装环境、跑脚本最后把指标写进表格。Trunchbull 这个项目换了一个角度把“真实模型 任意基准集”评测直接放进浏览器。用户在页面上选择模型文件和基准数据推理在本机浏览器内完成评测结果当场就能看到。这个思路对需要对比模型、验证数据集、或者不想把数据交给第三方服务的人来说很有吸引力。从项目标题里的 Show HN 可以看出它更像一个面向开发者社区的实验性工具而非企业级评测平台。真正吸引人的不是“多了一个评测网站”而是它把模型推理、基准数据加载、指标统计和结果展示压缩到了浏览器端。本文围绕这个思路展开三部分内容先讲清浏览器评测的技术链路再给出一套最小可运行实现最后整理运行验证、常见问题和工程化建议。即使你不打算直接用 Trunchbull这套模式也能帮你理解浏览器端模型推理的边界。1. 先理解 Trunchbull 解决的核心问题模型评测为什么折腾1.1 传统评测的成本集中在环境而不是模型本身常规的模型评测流程看起来不复杂下载公开基准集写好推理脚本加载模型权重批量跑前向计算最后统计准确率、F1 或困惑度等指标。真正跑起来之后问题往往集中在环境上。模型格式不统一需要先做转换或适配。推理框架依赖特定 CUDA 版本、Python 版本和第三方库。数据集文件可能很大下载、解压、预处理都要时间。多人协作时每个人本地的依赖版本不一致评测结果难以对齐。如果使用在线评测 API还需要考虑数据上传和隐私问题。这些成本里最浪费时间的不是模型前向计算本身而是“让评测环境可用”这一步。Trunchbull 的思路之所以有价值是因为它把环境简化成了浏览器只要浏览器支持相应的 Runtime模型和数据都从本地或静态 URL 加载评测就基本可复现。1.2 “真实模型”和“任意基准集”指的是什么标题里有两个关键词需要拆开理解。“真实模型”指的是真正加载模型权重文件对每条基准样本执行完整的前向计算而不是用规则、预计算分数或简化网络代替。准确率、延迟、内存占用这些指标只有建立在真实推理上才有意义。“任意基准集”指的是评测数据不是写死在工具里的而是由使用者自行提供。可以是公开的图片分类集、文本分类集、某项业务自建的小样本集也可以是几条用于冒烟测试的示例数据。工具本身不判断基准集是否合理只负责按统一流程跑完并报告结果。1.3 浏览器评测的边界也要提前说清楚浏览器不是万能的。以下场景更适合浏览器评测模型体量较小权重文件在几十 MB 到几百 MB 之间。基准集可以分页或按需加载不需要一次性装入内存。关注推理延迟、吞吐量、量化前后差异等相对指标。需要保护数据隐私数据不希望离开本机。以下场景现阶段尽量避开百亿参数以上的大模型浏览器内存和显存都难以承载。超大基准集比如百万级样本客户端逐条跑完耗时过长。对硬件环境要求完全一致的精确评测因为浏览器会受到设备、后台任务和浏览器版本影响。注意浏览器评测更适合“快速对比”和“初步验证”不建议作为唯一依据来决定生产环境的模型选型。正式发布前仍然要在服务器上做一轮受控测试。2. 在浏览器跑“真实模型”依赖哪几条技术链路2.1 WebAssembly 和 WebGPU 是底座浏览器本身不能直接执行 Python 训练框架导出的模型文件需要一个能运行神经网络运算的运行时。当前主流路径有两类WebAssemblyWASM把推理算子编译成浏览器可执行的二进制指令通过 SIMD 指令和多线程优化获得接近原生 CPU 的推理速度。WebGPU调用浏览器暴露的 GPU 能力适合矩阵计算密集的模型。WebGL 是老一代方案兼容性好但能力弱现在更多作为回退选项。WebAssembly 的特点是“稳”几乎所有现代浏览器都支持WebGPU 的特点是“快”但浏览器覆盖和版本差异比 WASM 大。实际实现里通常会做一个自动选择优先 WebGPU不可用时回退到 WASM。2.2 模型需要先转换成浏览器 Runtime 能识别的格式不同推理运行时对应不同模型格式。常见组合关系如下运行时主要模型格式适用场景ONNX Runtime WebONNX分类、检测、OCR、语音模型来源丰富Transformers.js转换后的模型文件文本分类、摘要、嵌入等 NLP 任务llama.cpp Web 构建GGUF本地运行小型 LLMTensorFlow.jsTF SavedModel / Layers老项目迁移、前端已有 TF 生态实际使用中要注意模型导出为 ONNX 时如果输入是动态长度需要打开动态轴dynamic axes选项否则推理时固定序列长度会带来很大限制。模型量化fp16、int8、int4能显著减小体积和提升速度但会带来精度损失评测时最好同时跑原始精度和量化版本对比差异。2.3 不要把“跑通推理”和“完成评测”混为一谈很多人在浏览器里加载模型成功后就认为评测功能完成了。实际上评测还包含三件容易被忽略的事数据加载和预处理是否正确图片要 resize、归一化文本要 tokenize特征顺序要一致。推理结果如何映射成指标得到 logits 之后要判断是取 argmax、做 softmax还是按阈值分类。延迟统计是否可靠第一次推理包含初始化开销必须做 warmup否则测出来的延迟会明显偏高。这三件事任何一个出错最终指标都会“看起来很对但经不起复现”。下一部分开始动手实现会把这些点逐一落到代码里。3. 环境准备浏览器、构建工具和最小项目骨架3.1 先确认浏览器的能力边界不同浏览器的推理能力差异很大尤其是 WebGPU 和多线程支持。建议在项目文档里放一张能力表格让使用者在跑评测前先自查能力Chrome/EdgeFirefoxSafari影响WebAssembly支持支持支持基础推理能力WASM SIMD支持支持支持显著提升 CPU 推理速度SharedArrayBuffer需要跨源隔离需要跨源隔离支持多线程推理必需WebGPU支持正在推进部分支持GPU 加速API 仍在演进这里最需要注意的是 SharedArrayBuffer。如果要用多线程 WASM 推理页面必须设置跨源隔离响应头Cross-Origin-Opener-Policy: same-origin和Cross-Origin-Embedder-Policy: require-corp。没有这两个头多线程初始化会直接报错但设置了 require-corp 之后页面引用的外部资源又必须允许跨源访问。这是一对经常让人卡住的连锁问题。3.2 最小依赖选择Vite TypeScript ONNX Runtime Web为了把实现聚焦在评测逻辑上下面用 Vite 作为构建工具TypeScript 写代码推理运行时采用 ONNX Runtime Web。这是一个覆盖面广、文档完整、容易替换成其他 Runtime 的组合。示例package.json{ name: browser-benchmark-skeleton, private: true, type: module, scripts: { dev: vite, build: vite build, preview: vite preview }, dependencies: { onnxruntime-web: ^1.18.0 }, devDependencies: { typescript: ^5.4.0, vite: ^5.2.0 } }Vite 只是一个示例选择如果你更熟悉 Webpack 或 esbuild也可以替换。重点是要保证 WASM 文件能被正确加载以及开发服务器的响应头配置正确。3.3 目录结构按“模型、数据、代码、页面”分开建议目录结构如下browser-benchmark-skeleton/ ├─ public/ │ ├─ models/ │ │ └─ model.onnx │ └─ data/ │ └─ benchmark.jsonl ├─ src/ │ ├─ main.ts │ └─ benchmark.ts ├─ index.html ├─ package.json ├─ tsconfig.json └─ vite.config.ts模型和基准数据放在public/下是为了让浏览器通过静态 URL 直接访问。正式项目里模型文件可能来自对象存储基准数据可能来自接口但本地开发用静态文件最方便调试。Vite 配置要处理两件事把 ONNX Runtime 的 WASM 文件复制到可访问目录以及让开发服务器返回跨源隔离响应头。示例配置如下import { defineConfig } from vite; import { viteStaticCopy } from vite-plugin-static-copy; export default defineConfig({ plugins: [ viteStaticCopy({ targets: [ { src: node_modules/onnxruntime-web/dist/*.wasm, dest: wasm } ] }) ], server: { headers: { Cross-Origin-Opener-Policy: same-origin, Cross-Origin-Embedder-Policy: require-corp } } });如果不想引入额外的复制插件也可以把 WASM 文件直接放到public/目录然后用配置参数指定路径。关键是确保运行时能找到对应版本的 WASM 文件版本不匹配时浏览器会给出难以理解的初始化错误。4. 最小可运行在浏览器里加载模型并对基准集跑推理4.1 基准数据格式建议用 JSONL一次推理需要一条样本一条样本至少包含唯一编号、输入内容、期望输出。对于文本分类任务可以用 JSONL 格式每行一个 JSON 对象{id: sample-0001, text: 这家餐厅的菜品很新鲜, label: positive} {id: sample-0002, text: 等待时间太长了, label: negative}这里的字段名可以根据模型调整。图片分类则可以换成图片 URL 或 Base64 数据。无论什么格式读取后都要先统一成内存里的结构体避免在推理循环里反复处理字符串。export interface BenchmarkItem { id: string; input: number[] | string; expected: string; } export interface BenchmarkOutput { itemId: string; prediction: string; correct: boolean; latencyMs: number; }4.2 初始化推理 SessionONNX Runtime Web 创建一个 Session本质上就是加载模型并解析其计算图。代码里需要注意三个参数执行提供者优先级、图优化级别、缓存选项。import * as ort from onnxruntime-web; export async function loadModel(modelUrl: string) { const session await ort.InferenceSession.create(modelUrl, { executionProviders: [webgpu, wasm], graphOptimizationLevel: all, enableCpuMemArena: true }); return session; }这里把执行提供者顺序设为[webgpu, wasm]意思是浏览器支持 WebGPU 时优先使用否则自动回退到 WASM。graphOptimizationLevel: all会开启尽可能多的计算图优化对提升推理速度有帮助但如果模型本身有特殊算子遇到问题可以先降级为basic对比。4.3 加入 warmup 并执行评测循环评测循环的核心不只是“跑 N 次推理”而是保证每次推理都是可比较的。这里要处理几个隐藏问题输入张量的数据类型、内存复用、warmup 次数、异常隔离。import type { InferenceSession, Tensor } from onnxruntime-web; import type { BenchmarkItem, BenchmarkOutput } from ./benchmark; async function runBenchmark( session: InferenceSession.InferenceSession, items: BenchmarkItem[], warmupRounds 1 ): PromiseBenchmarkOutput[] { // 先跑 warmup排除第一次初始化、算子编译和缓存冷启动的开销 for (let i 0; i warmupRounds; i) { const dummyInput new ort.Tensor(float32, new Float32Array(64), [1, 64]); await session.run({ input: dummyInput }); } const results: BenchmarkOutput[] []; for (const item of items) { const start performance.now(); try { const inputTensor: Tensor toTensor(item.input); const feeds { input: inputTensor }; const outputs await session.run(feeds); const prediction decodeOutput(outputs); const latencyMs performance.now() - start; results.push({ itemId: item.id, prediction, correct: prediction item.expected, latencyMs }); } catch (error) { console.error(推理失败${item.id}, error); results.push({ itemId: item.id, prediction: ERROR, correct: false, latencyMs: 0 }); } } return results; } function toTensor(input: number[] | string): Tensor { // 简化实现实际项目需要在这里完成词表映射或图片预处理 const data new Float32Array(input.length); input.forEach((value, index) { data[index] Number(value); }); return new ort.Tensor(float32, data, [1, input.length]); } function decodeOutput(outputs: Recordstring, Tensor): string { // 简化实现取 logits 最后一维 argmax const logits Object.values(outputs)[0].data as Float32Array; let bestIndex 0; let bestValue -Infinity; for (let i 0; i logits.length; i) { if (logits[i] bestValue) { bestValue logits[i]; bestIndex i; } } return String(bestIndex); }这个示例把toTensor和decodeOutput做了最简处理。实际项目中文本模型必须引入 tokenizer图片模型必须做 resize 和归一化。这里最重要的是评测循环的结构warmup、计时、异常隔离、结果收集这四个环节缺一不可。注意session.run返回的 Tensor 数据在异步处理过程中不要直接复用底层缓冲区否则下一次推理可能覆盖上次的数据。4.4 在页面上输出汇总结果评测跑完后需要把原始结果和汇总指标展示出来。汇总指标至少包含总样本数、正确数、准确率、平均延迟、P95 延迟。export function summarize(results: BenchmarkOutput[]) { const total results.length; const correct results.filter((r) r.correct).length; const latencies results.map((r) r.latencyMs).sort((a, b) a - b); const p95Index Math.min(latencies.length - 1, Math.floor(latencies.length * 0.95)); return { total, correct, accuracy: total 0 ? correct / total : 0, avgLatencyMs: latencies.length 0 ? latencies.reduce((a, b) a b, 0) / latencies.length : 0, p95LatencyMs: latencies[p95Index] ?? 0 }; }页面里的展示逻辑很简单一个选择模型文件的按钮一个选择 JSONL 数据文件的按钮一个“开始评测”按钮以及一个结果表格。文件读取用FileReader或URL.createObjectURL都可以。评测是异步且耗时的操作建议在界面上显示进度避免用户认为页面卡死。5. 评测指标和关键参数怎么定才可信5.1 指标不是只有准确率准确率是最直观的指标但对于模型选型来说远远不够。至少需要区分三类指标指标类型代表指标回答的问题效果指标准确率、F1、AUC、困惑度模型预测得准不准性能指标平均延迟、P95 延迟、吞吐量模型跑得快不快资源指标内存占用、模型体积、GPU 显存模型能不能部署在目标设备上在浏览器环境里性能指标的波动比服务器环境大得多。同一台电脑浏览器后台开着视频、风扇降频、浏览器版本升级都会改变延迟结果。因此单次评测的延迟没有意义至少需要多次运行并观察分布。5.2 影响结果的关键参数速查表在浏览器评测场景以下参数最影响结果的可比性参数常见值作用设置不合适时的表现warmup 次数1 到 3预热算子、缓存、GPU 上下文平均延迟偏高前几条样本明显慢batch size1每次前向处理样本数太大时内存暴涨太小时吞吐量偏低执行提供者webgpu / wasm决定用 GPU 还是 CPUWebGPU 不可用时报错或回退失败精度fp32 / fp16 / int8权重和激活的数值精度量化后准确率意外下降线程数默认WASM 多线程推理设置过高导致性能回退输入长度固定或动态影响计算量和显存固定长度过大浪费动态未打开则报错一个常见误区是“为了测准确率所以把 batch size 调大”。准确率和 batch size 理论上无关除非模型内部有依赖 batch 的统计操作。性能指标才需要关注 batch size。实际评测时准确率评测用 batch size 1 最稳妥性能指标再单独做 batch 扫描。5.3 浏览器评测与服务器评测的差异要写进报告同类模型在浏览器和服务器上跑出的准确率应该基本一致但延迟和吞吐量会有数量级差异。差异来源包括浏览器 Runtime 的算子实现未完全覆盖某些模型会回退到 fallback kernel。WebGPU 的 GPU 调度和 CUDA 不同显存管理策略也不同。WASM 多线程需要跨源隔离缺头时单线程运行会显著变慢。浏览器后台任务、定时器、动画帧都可能抢占执行时间。因此评测报告里除了指标还要记录浏览器名称、版本、操作系统、是否启用 WebGPU、模型格式、量化精度、数据文件和切换逻辑否则换一个人运行同一套评测结果往往对不上。6. 运行验证怎么判断一次评测是可信的6.1 先用小样本验证正确性再跑完整基准集第一次跑评测不要直接加载上千条数据。建议先用 5 到 10 条样本确认流程正确检查以下问题每条样本是否进入了模型推理而不是被异常跳过。输出的标签是否和手工推理结果一致。延迟数据是否在合理区间而非第一轮异常高、后续异常低。错误样本的日志是否能定位到具体输入。要特别警惕全流程“顺利跑完”但准确率接近随机的情况。这种状况通常是预处理和模型训练时的预处理不一致导致的比如归一化参数、图像通道顺序、文本截断方式。此时需要把模型在服务器端用原生框架跑同样的输入做对比找出差异。6.2 通过浏览器开发者工具确认资源状态评测过程中打开开发者工具确认三件事Network 面板里模型文件和 WASM 文件是否加载成功有没有 404 或 CORS 错误。Console 面板有没有未捕获的异常特别是 WebGPU 创建失败、SharedArrayBuffer 头部缺失。Performance 面板在评测期间有没有出现明显的长任务、GC 抖动或后台任务抢占。这三项任何一个有问题评测结果都可能是“跑通了但不可比”。6.3 建立可复现评测检查清单发布评测功能前建议按下面的清单检查一遍模型文件版本有记录模型哈希可计算。基准数据文件版本有记录样本数量明确。浏览器名称和版本能自动采集并写入报告。runtime 版本和 WASM 文件版本一致。评测前执行过 warmup。每条样本的输入和输出能追溯到原始数据。多次运行结果在合理误差范围内。异常样本单独记录不计入不细分。结果导出为 JSON包含所有元信息。这个清单既适用于 Trunchbull 这类浏览器工具也适用于任何要对外发布的自动化评测脚本。7. 常见问题排查从现象倒推原因浏览器评测的问题通常集中在加载、初始化、推理和结果四个阶段。下面按频率列出最常见的现象和排查路径。问题现象可能原因检查方式处理建议控制台报 CORS 错误模型或数据来自其他域名未允许跨源Network 面板看响应头静态资源允许 CORS或同源部署WASM 文件 404WASM 路径配置不对版本不匹配Network 面板看请求 URL复制正确版本的 wasm 到 public 目录SharedArrayBuffer 未定义缺少跨源隔离响应头检查 Network 响应头配置 COOP/COEP 头WebGPU 初始化失败浏览器版本不支持或设备被禁用控制台查navigator.gpu回退到 WASM 执行提供者推理结果全为 NaN输入未归一化、精度过低、除零打印输入张量数值范围检查预处理和量化设置延迟忽高忽低浏览器后台任务、GC、降频Performance 面板多跑几轮取分位数避免后台标签页模型文件几百 MB页面卡死一次性读取了大文件Memory 面板看堆内存改用流式加载并限制模型大小同一模型两次准确率不同存在随机性或数据顺序变化检查 tokenizer 和采样参数固定随机种子统一预处理7.1 跨源隔离头导致外部资源失败这是最典型的连锁问题。为了让 WASM 多线程可用页面设置了Cross-Origin-Embedder-Policy: require-corp但模型文件正好放在 CDN 上CDN 的响应头没有Access-Control-Allow-Origin或Cross-Origin-Resource-Policy于是模型加载失败。排查顺序是先去掉 COEP 头确认模型能加载再重新加回头逐一看静态资源是否都允许跨源。不要同时改多个配置否则很难定位是哪个响应头引起的。7.2 动态输入形状报错ONNX 模型如果导出时输入维度固定比如文本输入是[1, 128]那么传入长度 64 的样本会直接报维度不匹配。处理方式有两种导出模型时打开动态轴让seq_len维度为动态。推理前把所有文本 pad 到固定长度并用 attention mask 屏蔽 padding 部分。第二种方式实现简单但固定长度过大会浪费计算量。评测工具最好两种都支持并在 UI 上显示当前模型的输入签名。7.3 评测过程中页面被后台化延迟失真浏览器为了省电会降低后台标签页的定时器精度和渲染频率。如果评测在中途切换标签页测出的延迟会包含大量调度延迟不可信。预防做法评测开始前提示用户保持标签页前台在结果报告里记录评测耗时和浏览器 visibility 状态延迟指标使用 P95 而不是平均值受单个长任务影响更小。8. 工程化建议和扩展方向8.1 评测配置要外置不要写死在代码里模型 URL、数据 URL、warmup 次数、执行提供者顺序、量化精度这些都应该从页面 UI 或 JSON 配置中读取而不是写在源码里。推荐设计一份评测配置{ model: { url: /models/model.onnx, provider: webgpu, fallbackProvider: wasm, precision: fp32 }, benchmark: { dataUrl: /data/benchmark.jsonl, warmupRounds: 2, timeoutMs: 10000 }, output: { includeRawResults: false, saveToLocal: true } }配置外置的好处是复用同一个前端页面可以测多个模型和多个数据集不需要改代码重新构建。8.2 结果导出要包含元信息评测结果的 JSON 不能只有一组准确率和延迟还要包含恢复现场所需的全部信息。推荐结构如下{ summary: { accuracy: 0.923, avgLatencyMs: 12.4, p95LatencyMs: 21.8, total: 1000, correct: 923 }, environment: { browser: Chrome 126, platform: Windows 11, webgpu: true, runtimeVersion: onnxruntime-web 1.18.0, modelHash: sha256:... }, config: { modelUrl: /models/model.onnx, dataUrl: /data/benchmark.jsonl, warmupRounds: 2 }, failures: [] }模型文件的哈希是很多人忽略的字段。没有哈希几个月后很难确认当前评测到底用的哪个权重文件。8.3 扩展方向按需求和资源分批实现如果要在 Trunchbull 思路的基础上继续扩展可以按下面的优先级考虑接入 Web Worker把推理放到 worker 线程避免阻塞 UI。多会话并发多个模型并行评测对比同一份基准集上的差异。数据懒加载大基准集分页读取避免一次加载全部样本。结果可视化输出混淆矩阵、分类错误样本列表、延迟分布直方图。自动重跑支持一键重跑多次并给出均值和置信区间。接入自动化测试用 Playwright 无头浏览器跑完整评测把结果作为回归报告。对于个人开发者和研究团队前两项已经能覆盖大部分日常对比需求。更重的功能要结合真实评测场景来决定不必一开始就做得像企业评测平台。8.4 学习环境和生产环境的差异要分清学习环境本地 Vite 开发服务器用静态模型文件和小数据集跑通流程即可。测试环境固定浏览器版本使用 CI 容器配合 Playwright 记录自动化截图和报告。生产环境模型和数据走对象存储并配置 CORS评测记录写入后端结果持久化失败样本单独存储。浏览器评测最大的优势是低门槛和隐私保护最大的风险是环境不可控。只要在报告里把环境信息记录完整把一次评测定义成“某浏览器、某版本、某配置下的结果”它就能成为模型选型和回归验证的有效工具。最后给一个实际建议不要急着把所有模型都塞进浏览器。先选一个你已经知道标准答案的小模型和一份小数据集把加载、推理、统计、导出全流程跑通再逐步扩展到更大的模型和更接近真实分布的基准集。这样遇到的每一个问题都能定位在具体环节上而不是像传统评测那样最后甩给你一堆依赖报错和版本冲突。