浏览器端侧 AI 实战指南在沙箱中运行高维特征提取与视觉检索系列二系列一里我们跑通了 TensorFlow.js 加载 MobileNet 做图像分类算是把浏览器端侧 AI 的门敲开了。但真到做视觉检索这类业务的时候分类模型那点输出根本不够用——你得把一张图变成一串具有区分度的特征向量还要让这些向量在不同图片之间可比。说得直白些这就是高维特征提取用提取出来的向量去做以图搜图、相似图片检测、商品同款识别。这篇文章就干这件事从模型选型、沙箱环境配置到向量存储与相似度检索完整走一遍浏览器端侧视觉检索的落地流程。先说我的结论在浏览器沙箱里做视觉检索现在已经不是“能不能做”的问题而是“怎么做才稳”的问题。选对特征提取模型、配好跨域隔离、设计好向量存储2000张图以内的本地以图搜图完全可以跑在用户浏览器里图片不出本机隐私安全服务器零压力。下面我把整个链路拆开讲。1. 方案选型为什么是CLIP ONNX Runtime Web1.1 从图像分类到高维特征图像分类模型输出的是一组类别概率比如“猫 0.85、狗 0.12”这个结果只能回答“这是什么”没法回答“这两张图像不像”。高维特征提取则完全不同它把图像编码成固定长度的数值向量比如512维、768维向量之间的距离直接反映图像的语义相似度。猫和狗的特征向量可能比较接近猫和汽车的特征向量就离得远。所以视觉检索的第一步不是选检索算法而是选一个能产出好特征向量的模型。这个模型的质量决定了检索效果的瓶颈后面的存储和检索手段都无法突破这个瓶颈。浏览器端可选择的特征提取模型其实不少但效果差异非常大。我整理了一张对比表都是我在本地环境实测过的状态模型特征维度Wasm推理耗时单张CPU语义能力浏览器落地难度MobileNetV3-Largepooled1280约80ms偏底层视觉特征能区分物体但语义弱低TF.js可直接跑ResNet50pooled2048约300ms比MobileNet好一点但维度高、存储大低CLIP ViT-B/32512约450ms强语义对齐支持图文跨模态检索中需导ONNXDINOv2 ViT-B/14768约600ms自监督特征细节能力强中高算子兼容性差Chinese-CLIP ViT-B/16512约400ms中文场景效果更好支持文本匹配图像中需导ONNX我最终选的是CLIP ViT-B/32核心原因是它在“语义相似度”上的表现明显优于普通分类模型。CLIP通过大规模图文对比学习训练特征向量天然被拉近到“语义一致”的区域这对以图搜图特别重要。比如你想搜“穿红裙子的女孩在草地上”MobileNet特征只能告诉你“有裙子、有草地”但CLIP特征能更好捕捉到“红裙子女孩”这个组合概念。1.2 为什么选择ONNX Runtime Web而不是TensorFlow.js系列一用的是TensorFlow.js这没问题但它不是所有模型都能跑。CLIP这类Transformer结构模型需要自定义算子TF.js的支持不算差可一旦涉及text encoder、tokenizer这些配套模块工程复杂度会明显上升。ONNX Runtime Web是另一个思路它基于Wasm和WebGPU运行ONNX模型算子覆盖面大PyTorch导出的模型基本能直接跑而且多线程能力比TF.js的Wasm后端稳。在沙箱环境里ONNX Runtime的线程模型更可控。它能使用SharedArrayBuffer做多线程推理配合SIMD指令加速在普通笔记本上CLIP单张图推理能压到400ms左右。如果启用WebGPU执行后端可以做到150ms以内基本达到可用状态。如果你不想手动处理模型导出也可以用Transformers.js它封装了HuggingFace生态底层还是ONNX Runtime Web提供了更高层API。我这次选择ONNX Runtime Web直接操作是因为后续要做自定义预处理和向量存储自己控制整个推理管线更方便。1.3 为什么要在沙箱里跑而不是后端算我的观点很明确视觉检索这类强隐私业务特征提取越靠近数据源头越好。用户上传的图片往往包含人脸、地点、物品等敏感信息如果全部传到服务器提取特征不仅带宽消耗大还有数据合规风险。浏览器天生提供了一套沙箱环境——页面里的JS代码跑在隔离的渲染进程里没有直接读写用户文件系统的权限不能随意访问其他站点数据这是履行隐私承诺的基础保障。更关键的是Web Worker和WebAssembly在沙箱内部又划出了一层“子沙箱”。AI模型运行在Wasm虚拟机上无法直接触碰DOM也不能偷偷发起网络请求把特征结果传出去。对于很多业务场景来说这种隔离本身就是卖点图片不出本机特征就在本地检索结果也留在浏览器里。2. 沙箱环境跨域隔离与Worker线程配置2.1 浏览器沙箱给AI运行划了哪些线我之前看到不少人听到“沙箱”就以为是Docker容器或者虚拟机其实浏览器端侧的沙箱是另一套机制。它限制的是页面代码能接触到的系统资源没有任意文件读写、没有任意网络请求、内存受限、存储受限。这些限制对普通网页是安全红利但对AI推理来说就是需要绕过的障碍。最直接的问题是性能。Wasm代码本身运行在受限的线性内存区域里为了多线程推理ONNX Runtime需要用到SharedArrayBuffer——这是浏览器沙箱中一块可以被多个Worker共享的内存区域。但浏览器为了防止Spectre类CPU漏洞攻击默认禁用了SharedArrayBuffer你必须主动打开“跨域隔离”才能使用。第二个问题是存储。浏览器LocalStorage只有5MB左右根本存不下高维特征向量我使用IndexedDB存储向量单条512维Float32向量约2KB1万条图片向量约20MBIndexedDB完全可以承受。但要注意如果站点没有申请持久化存储浏览器在空间紧张时可能回收存储我会在后面专门讲这个坑。2.2 COOP/COEP跨域隔离配置要在沙箱里用SharedArrayBuffer跑ONNX多线程必须配置两个响应头Cross-Origin-Opener-Policy: same-origin Cross-Origin-Embedder-Policy: require-corpCOOP保证顶层窗口和其他来源窗口隔离COEP要求页面所有资源都显式支持跨域加载。配置后window.crossOriginIsolated会变成trueSharedArrayBuffer才可用。我用Vite做开发服务器时在vite.config.js里加了一段配置import { defineConfig } from vite; import { createServer } from vite; export default defineConfig({ plugins: [ { name: configure-coop-coep, configureServer(server) { server.middlewares.use((req, res, next) { res.setHeader(Cross-Origin-Opener-Policy, same-origin); res.setHeader(Cross-Origin-Embedder-Policy, require-corp); next(); }); } } ] });生产环境则在Nginx里配置add_header Cross-Origin-Opener-Policy same-origin always; add_header Cross-Origin-Embedder-Policy require-corp always;配置完最明显的标志就是crossOriginIsolated为true。如果模型文件和Wasm文件放在CDN它们也必须返回Access-Control-Allow-Origin和Cross-Origin-Resource-Policy: cross-origin响应头否则COEP会拦截所有外部资源加载控制台里会看到一片红色的加载失败。2.3 CSP与存储权限CSP内容安全策略也是沙箱里的一个隐形绊脚石。ONNX Runtime加载Wasm文件时如果页面CSP配置了script-src必须显式允许wasm-unsafe-eval。我遇到过线上部署后模型加载直接白屏排查了半天才发现是CSP把Wasm编译给拦了。一个兼容性比较好的CSP配置Content-Security-Policy: default-src self; script-src self wasm-unsafe-eval; worker-src self blob:; img-src self blob: data:; connect-src self https://your-cdn.example.com存储权限方面建议在建立索引前主动申请持久化存储if (navigator.storage navigator.storage.persist) { const persisted await navigator.storage.persist(); console.log(持久化存储申请结果:, persisted); }我之前在无痕模式下测试时IndexedDB数据在标签页关闭后被清掉就是因为没有申请持久化。另外模型文件不建议每次加载都从网络请求可以把ONNX和Wasm的响应缓存起来CacheStorage在这种场景比浏览器默认HTTP缓存更可控。3. 高维特征提取模型导出、预处理与推理3.1 用PyTorch导出CLIP视觉编码器CLIP模型在HuggingFace上有现成权重我用的openai/clip-vit-base-patch32。但直接导出整个CLIPModel会带着text encoder和对比损失头浏览器端根本用不上。正确做法是只导出vision encoder加visual projection输出最终归一化前的图像特征。这里有一个容易踩的大坑model.vision_model的pooler_output是768维而CLIP最终用于对比学习的图像特征经过visual_projection投影成512维。不能只导出vision_model否则维度对不上。我写了个小包装类处理import torch from transformers import CLIPModel model CLIPModel.from_pretrained(openai/clip-vit-base-patch32) model.eval() class CLIPVisionExport(torch.nn.Module): def __init__(self, clip_model): super().__init__() self.vision_model clip_model.vision_model self.visual_projection clip_model.visual_projection def forward(self, pixel_values): vision_output self.vision_model(pixel_values) pooler_output vision_output[pooler_output] return self.visual_projection(pooler_output) wrapper CLIPVisionExport(model) dummy_input torch.randn(1, 3, 224, 224) torch.onnx.export( wrapper, dummy_input, clip_vision.onnx, input_names[pixel_values], output_names[image_features], dynamic_axes{ pixel_values: {0: batch}, image_features: {0: batch} }, opset_version14 ) print(导出完成输出维度应为 512)动态轴batch这个设置很关键。浏览器端可能一次提取1张也可能一次提取8张做批处理如果没有动态batch维度推理时固定尺寸会遇到不必要的reshape。导出阶段还有一个细节是算子版本。opset_version不要太高ONNX Runtime Web的算子兼容范围有限如果导出报错优先降低opset版本或者把Transformer里不常用的算子替换成兼容版本。3.2 浏览器端初始化ONNX Session在Web Worker里创建session避免阻塞UI线程。我一般把Wasm路径和模型路径都指向本地或CDN固定目录import * as ort from onnxruntime-web; let session null; async function initSession() { if (session) return session; ort.env.wasm.wasmPaths /wasm/; ort.env.wasm.numThreads navigator.hardwareConcurrency || 4; session await ort.InferenceSession.create(/models/clip_vision.onnx, { executionProviders: [webgpu, wasm], graphOptimizationLevel: all }); return session; }executionProviders: [webgpu, wasm]是一个降级链浏览器支持WebGPU就用GPU推理不支持则自动退到Wasm。注意numThreads参数的配置依赖SharedArrayBuffer所以COOP/COEP头必须提前配好。启用多线程后首次推理会有一个创建线程池的延迟大概几百毫秒。建议在页面加载后就立即初始化session把线程池预热放在用户真正上传图片之前。3.3 图像预处理必须对齐训练配置CLIP的预处理和ImageNet分类模型完全不一样。很多人在浏览器端跑CLIP特征结果全是NaN或者检索效果稀烂十有八九是归一化参数错了。CLIP使用的mean和std是mean [0.48145466, 0.4578275, 0.40821073] std [0.26862954, 0.26130258, 0.27577711]注意不是ImageNet的[0.485, 0.456, 0.406]。把这两组数搞混特征分布直接偏掉检索效果自然崩塌。图像尺寸也要对齐模型训练分辨率ViT-B/32是224×224ViT-B/16也是224×224如果你的模型是224就统一resize到224。我建议用createImageBitmap解码图片再用OffscreenCanvas缩放这样可以放在Worker里执行不占用UI线程async function preprocessImage(bitmap, size 224) { const canvas new OffscreenCanvas(size, size); const ctx canvas.getContext(2d, { willReadFrequently: true }); ctx.drawImage(bitmap, 0, 0, size, size); const imageData ctx.getImageData(0, 0, size, size); const data imageData.data; const mean [0.48145466, 0.4578275, 0.40821073]; const std [0.26862954, 0.26130258, 0.27577711]; const float32 new Float32Array(3 * size * size); const len size * size; for (let i 0; i len; i) { float32[i] (data[i * 4] / 255 - mean[0]) / std[0]; float32[len i] (data[i * 4 1] / 255 - mean[1]) / std[1]; float32[2 * len i] (data[i * 4 2] / 255 - mean[2]) / std[2]; } return float32; }这段代码做了三件事RGB值归一化到0-1、减去均值除以方差、按CHW通道顺序排列。ONNX模型输入的Tensor布局一般是NCHW也就是batch、channel、height、width别把顺序搞成NHWC否则推理结果会莫名其妙地差。3.4 Worker推理与消息协议整个特征提取链路放在Worker里主线程只负责把图片的ImageBitmap通过postMessage发过去收到的就是高维特征向量。我的消息协议设计得很简单// worker.js self.onmessage async (e) { const { taskId, imageBitmap } e.data; try { const session await initSession(); const pixels await preprocessImage(imageBitmap); const tensor new ort.Tensor(float32, pixels, [1, 3, 224, 224]); const results await session.run({ pixel_values: tensor }); const feature results.image_features.data; // 把特征缓冲转移回主线程避免结构化克隆拷贝的开销 self.postMessage({ taskId, feature: feature.buffer, batchId: e.data.batchId }, [feature.buffer]); } catch (err) { self.postMessage({ taskId, error: err.message }); } };这里有个容易被忽略的性能细节使用[feature.buffer]作为第二个参数可以把ArrayBuffer的所有权转移给主线程而不是复制一份。对于512维Float32Array区别不大但如果一次处理8张图累积下来能省不少拷贝开销。主线程侧批量处理多张图片时我建议并发度控制在navigator.hardwareConcurrency - 1左右。如果同时把十几张ImageBitmap扔给WorkerWorker里虽然是异步处理但CPU线程过饱和反而会比串行更慢。4. 视觉检索向量存储与KNN匹配4.1 向量数据落盘IndexedDB方案特征提取出来后面临两个问题存在哪、怎么查。浏览器本地没有专门的向量数据库我又不想引入超过20MB的Wasm ANN库所以选择了IndexedDB 内存暴力检索的组合。IndexedDB存储设计function openVectorDB() { return new Promise((resolve, reject) { const request indexedDB.open(visual-search-db, 1); request.onupgradeneeded (event) { const db event.target.result; if (!db.objectStoreNames.contains(vectors)) { const store db.createObjectStore(vectors, { keyPath: id }); store.createIndex(by_batch, batchId, { unique: false }); } if (!db.objectStoreNames.contains(meta)) { db.createObjectStore(meta, { keyPath: id }); } }; request.onsuccess () resolve(request.result); request.onerror () reject(request.error); }); }vectors表存的是向量和批次信息meta表存图片缩略图、原始文件名、时间戳。查询时先遍历vectors取出全部向量到内存建立本地的检索列表然后做相似度匹配。这种方案在1万条以内非常舒服查询延迟只有十几毫秒。存储成本算一笔账512维Float32数组是2048字节加上IndexedDB的记录索引开销单条约2.2KB。1万条图片约22MB10万条约220MB。一般用户的浏览器分配给单个站点的存储空间有几百MB到几GB所以10万条以内不需要太担心容量。但如果单条图片还需要存缩略图缩略图Base64会明显放大存储。建议缩略图统一压缩到96×96用WebP格式再存IndexedDB否则5000张图的缩略图就可能吃掉100MB以上。4.2 L2归一化后的余弦检索实现余弦相似度是视觉检索最常用的度量方式范围在-1到1之间越接近1表示越相似。直接实现需要计算两个向量的模长并做除法但一个常见的优化是先把所有向量做L2归一化让模长变成1。这样余弦相似度就变成了点积计算量少一半。提取特征后统一做L2归一化这一步在Worker里就可以完成function l2Normalize(vector, out new Float32Array(vector.length)) { let sum 0; for (let i 0; i vector.length; i) { sum vector[i] * vector[i]; } const norm Math.sqrt(sum) || 1; for (let i 0; i vector.length; i) { out[i] vector[i] / norm; } return out; }之后检索时只需要计算点积function knnSearch(queryVector, vectors, k 5) { const scored new Array(vectors.length); for (let i 0; i vectors.length; i) { const v vectors[i].vector; let dot 0; for (let j 0; j queryVector.length; j) { dot queryVector[j] * v[j]; } scored[i] { idx: vectors[i].id, score: dot }; } scored.sort((a, b) b.score - a.score); return scored.slice(0, k); }这是我验证过最简单可靠的检索实现。在1万条512维向量里做一次全量扫描普通笔记本上大约耗时20-40ms用户几乎无感知。但如果向量库增长到100万条全量扫描会到秒级那就需要上更复杂的索引方案了。检索结果建议返回topK时带上score阈值。我通常在显示时把低于0.75的相似度标记为“可能不相关”避免搜索结果全是低质量匹配影响体验。4.3 数据量增长后的检索优化方向如果你的目标是百万级向量浏览器暴力KNN就不够用了。我有几个实际考虑过的优化方案按实施成本从低到高排列第一是降维。先用PCA把512维降到128维虽然会有精度损失但检索耗时会降到原来的四分之一存储也大幅缩小。浏览器端用简单的矩阵乘法就能完成PCA变换不需要额外库。第二是乘积量化Product Quantization。先把向量切分成若干子向量每个子向量用k-means聚类成256个簇用簇ID替代原始数值。这种方式存储能压缩到原来的十分之一甚至更低但需要离线训练码本前端实现复杂度高适合对容量极度敏感的场景。第三是引入WebGPU并行计算。ONNX Runtime的WebGPU执行后端支持通用矩阵乘法把全量向量拼成一个大矩阵查询向量和整个矩阵做一次BatchMatMul点积结果一次返回吞吐量比纯JS循环高不少。我在实验里用WebGPU加速后10万条检索延迟能控制在50ms内。不管用哪种方案前提都是特征向量质量过关。模型选不好后面索引再快也搜不出想要的东西。5. 常见报错与性能排查5.1 沙箱相关报错我落地过程中遇到最多的问题都集中在沙箱隔离和跨域资源加载上列个速查表现象根本原因解决方案SharedArrayBuffer is not defined没有配置COOP/COEP跨域隔离未生效配置响应头确认crossOriginIsolated为true模型加载时Failed to fetch跨域请求被CORS拦截或COEP缺少CORP头CDN配置Access-Control-Allow-Origin和Cross-Origin-Resource-PolicyCSP报错wasm-unsafe-eval页面CSP限制Wasm编译CSP中加入script-src wasm-unsafe-evalWorker创建失败Worker脚本跨域或CSP worker-src未放行检查worker-src和脚本同源IndexedDB写入报QuotaExceededError浏览器存储配额不足调用navigator.storage.persist申请持久化压缩缩略图最坑的一次是我把模型文件放在了自己的对象存储服务上主站配了COEP但CDN没有返回CORP响应头结果本地开发环境跑得好好的线上模型死活加载不出来。所以COEP开起来之后所有静态资源所在的CDN都需要配合这个很容易漏。5.2 特征提取与推理性能问题第一次跑通的时候单张图从上传到拿到特征花了将近2秒这显然不合格。后来逐步定位到几个瓶颈图片解码是最大瓶颈。直接用FileReader读成DataURL再丢给Image解析解码大图非常慢。改成createImageBitmap(file)会快很多因为浏览器对createImageBitmap有解码优化而且它能在Worker里并行执行。推理后端选择也很重要。Wasm单线程跑CLIP确实慢启用SIMD 多线程后速度提升2-3倍开启WebGPU后更快但不要指望所有用户都能用上WebGPU。我的策略是页面启动时探测navigator.gpu是否存在存在就优先WebGPU否则退到Wasm。session初始化不能放在每次推理内部。ONNX Runtime创建session时会做大量图优化和内存分配耗时常常在几百毫秒这个只在进程生命周期初始化一次。5.3 兼容性与降级策略浏览器端的碎片化比想象中严重。WebGPU在较新的Chrome、Edge上稳定但在Safari上推进缓慢iOS Safari 18才能比较好地支持。好在ONNX Runtime允许执行后端降级页面初始化时先检测function getExecutionProviders() { const hasWebGpu typeof navigator ! undefined gpu in navigator; return hasWebGpu ? [webgpu, wasm] : [wasm]; }Wasm执行后端也有版本差异。老版本浏览器不支持SIMD如果遇到undefined is not a function或者wasm: is not defined这类错误检查一下浏览器是否支持SIMD不支持就退化到单线程Wasm再不行就提示用户升级浏览器。我一般会把兼容性信息输出在调试面板里当前是否crossOriginIsolated、是否WebGPU可用、Wasm线程数是多少。这样用户反馈问题时我第一时间就能判断是环境问题还是代码问题。6. 完整Demo端到端浏览器以图搜图6.1 页面交互与整体流程为了验证整条链路我做了一个最简可用的本地以图搜图Demo交互流程只有三步用户选择一批图片作为图库浏览器提取每张图的512维特征并存入IndexedDB。用户上传一张查询图片浏览器提取特征。在全局向量列表里做KNN匹配把top5图片缩略图和相似度分数展示出来。整个过程中没有任何网络请求把图片发出去全部在本地完成。这在产品层面是个不错的隐私卖点同时也是我验证浏览器端侧AI能力边界的好样例。工程结构visual-search/ ├── public/ │ ├── models/ │ │ └── clip_vision.onnx │ └── wasm/ │ ├── ort-wasm-simd-threaded.wasm │ └── ort-wasm-simd-threaded.mjs ├── src/ │ ├── main.js │ ├── worker.js │ └── vector-store.js └── index.html6.2 核心代码剖析主线程负责UI交互和图片文件输入真正吃性能的工作全部在Worker里。主要流程如下// main.js const worker new Worker(/src/worker.js); worker.onmessage async (e) { const { taskId, feature, error } e.data; if (error) { console.error(taskId, error); return; } const vector new Float32Array(feature); await vectorStore.save({ id: taskId, vector }); if (taskId query) { const result await knnSearch(vector, loadedVectors, 5); renderResults(result); } }; async function buildIndex(files) { const batchId Date.now(); for (const file of files) { const bitmap await createImageBitmap(file); const taskId img_${Date.now()}_${Math.random().toString(16).slice(2)}; worker.postMessage({ taskId, batchId, imageBitmap: bitmap }, [bitmap]); } } async function searchByImage(file) { const bitmap await createImageBitmap(file); worker.postMessage({ taskId: query, imageBitmap: bitmap }, [bitmap]); }注意postMessage的第二个参数同样是transferables把ImageBitmap的所有权转移给Worker。这样主线程不需要再持有这个位图对象内存占用更低。在Worker内部我把imageBitmap直接交给preprocessImage然后走推理。增加batchId是为了支持“建索引时同时搜索”的场景避免查询结果混入还在建立索引的批次。6.3 本地测试效果与选型建议我用COCO数据集的子集跑了一个快速验证选2000张图片建立本地索引耗时大约12秒完成全量特征提取平均每张6ms解码 400ms推理。这里推理占大头因为COCO图片是JPEG解码本身很快但CLIP的Transformer结构在Wasm下确实比MobileNet重不少。检索阶段找一张查询图从2000条512维向量里返回top5单次查询在10ms以内。如果特征存储在IndexedDB里第一次查询需要从IndexedDB把所有向量load到内存2000条约4MB加载时间约几十毫秒之后查询就是纯内存操作。如果你也想做一个类似的浏览器端视觉检索功能我的选型建议是图片量在1万以内直接CLIP ONNX Runtime Web IndexedDB暴力KNN省心可靠。图片量在10万级别优先考虑WebGPU加速的全量扫描或者PCA降维到128维后再扫。图片量超过百万浏览器端暴力检索已经不现实建议只把特征提取放在端侧检索部分迁到服务端或使用更专业的向量数据库。从系列一的基本分类到这篇文章的高维特征提取与检索浏览器端AI的边界已经被推得相当远了。我个人在实际操作中的体会是很多人一上来就追求最新最重的模型结果卡在算子兼容性和性能优化上反而忽略了业务流程是否真的需要那么强的视觉语义。CLIP ViT-B/32在大多数检索场景里已经足够好先把链路跑通后续再按需换更大的模型才是正路。最后分享一个小技巧在开发调试阶段把Worker里的推理耗时、预处理耗时、IndexedDB读写耗时分别打点记录输出到控制台或者页面调试面板。你会发现性能瓶颈往往不在模型推理而是在图片解码、数据拷贝、存储序列化这些边缘环节。处理好这些细节浏览器端侧AI的体验会有一个非常明显的提升。