做端侧向量检索这件事说实话最初并不是为了赶时髦。我是给客户做商品图搜索功能时被逼出来的方案——图片数据敏感不能出内网服务器又不想扩容预算卡得很死。后来调研了一圈发现浏览器端的能力早就够用了TensorFlow.js 能跑特征提取模型Web Worker 能隔离计算压力1024 维向量的相似度计算在纯前端也能扛住百万级数据。于是我就把整套链路从“上传图片-云端算-云端查”变成了“本地算-本地查”云端只负责下发静态资源。这篇文章就把我落地这套方案的完整思路、实操步骤和踩过的坑都拆开讲。先说这个方案适合谁。如果你手里有这些需求中的任意一个端侧向量检索都值得认真看一眼以图搜图的个人图库、本地商品库管理、敏感场景下的图片检索、低服务器预算但又想体验智能搜索的应用。只要用户用的是现代浏览器数据量在百万条以内响应时间能容忍一两百毫秒到半秒这套思路就能直接套用。下面我会从整体设计、技术选型、核心实现、性能实测到问题排查一条线讲清楚。1. 整体设计拆解为什么把向量检索全部搬到端侧1.1 端侧方案要解决的三个核心痛点我当时的客户场景很简单产品目录里有五万多张商品图需要支持“拍照找同款”。最初部署的是传统的云端方案——图片上传到服务器Python 服务调模型提取特征向量再丢进向量数据库做相似度检索。功能是能跑但客户的 IT 部门提了三个要求直接把这个方案否了。第一是数据合规。商品图涉及未公开的新品设计图客户明确要求图片不能离开内部网络。云端方案意味着每次检索都要把图片传到公网服务器这在合规层面直接不成立。第二是成本控制。五万张图的全量特征提取如果用 GPU 云主机跑一次性成本加上持续的服务运维一个月下来几千块是跑不掉的。第三是延迟体验。图片上传到云端再返回结果跨地域网络下平均延迟至少三百到五百毫秒而且高峰期并发一上来服务器经常超时。端侧方案正好同时解决这三个问题。浏览器本地跑模型图片从头到尾不离开用户设备算力用用户设备的 GPU/CPU云端没有持续费用特征提取加检索全在本地完成没有网络请求延迟反而更低。当然代价也有——把计算压力从服务器转移到用户设备上对用户设备的性能有基本要求这也是后面要重点处理的问题。1.2 架构分层主线程、Worker 与索引层各司其职整套端侧架构我拆成了三层分工很明确。第一层是主线程负责一切与用户交互相关的事情文件选择、Canvas 绘图、拍照预览、结果展示。这一层的原则是“只传数据不搞计算”任何 CPU 密集的操作都不允许出现在这里否则页面卡顿用户马上能感知到。第二层是 Web Worker 线程这是真正的“计算中枢”。模型加载、图像预处理、特征向量提取、向量检索全在 Worker 内完成。主线程通过 postMessage 把图像数据丢给 WorkerWorker 算完把结果抛回来中间不阻塞 UI。第三层是索引层我把它放在 Worker 内部维护。这一层管理所有已入库的特征向量负责插入、删除、检索和周期性重建。索引的数据结构一开始我就没打算用暴力全扫而是做了签名向量粗筛加精确计算的混合方案后面会细说。选择 Web Worker 而不是其他方案理由也很直接如果不把推理放到 WorkerTensorFlow.js 的 WebGL 后端跑一次 MobileNet 推理虽然只要二三十毫秒但在主线程里这个时间足够造成可见的掉帧——尤其在用户连续拖入多张图片、批量提取特征的时候。放到 Worker 后主线程的任务只剩消息收发帧率稳定在 60fps 没有问题。1.3 为什么是 1024 维精度、内存和速度的三角权衡特征维度不是拍脑袋定的。常见视觉模型输出的特征维度其实各不相同MobileNet V2 的全局池化层输出是 1280 维EfficientNet-Lite0 是 1280 维ResNet50 是 2048 维。这些原始维度直接拿去建索引性能开销偏大而且实验下来我发现高维特征里存在明显冗余——很多维度对区分商品类别毫无贡献。我的做法是在模型转换时额外接一个全连接层把输出压到 1024 维。这个维度看起来是个不错的平衡点单条向量的存储开销是 4KBFloat32一百万条就是 4GB有点吃紧但如果我改用 Float16 存储1024 维单条只要 2KB一百万条才 2GB这在浏览器端是可以接受的。再往下压到 512 维也不是不行但实测检索 top5 准确率会掉 2% 到 3%我的场景接受不了。所以 1024 维是一个典型的精度-内存-速度三角权衡维度太高内存和计算时间爆炸维度太低特征区分度不够。压缩后的 1024 维特征在我这套商品检索场景下召回率和原始特征基本持平但内存开销小了一半这个性价比是划算的。2. 核心环节实现模型转换、Worker 推理与索引检索2.1 模型导出与转换Keras 到 TensorFlow.js 的完整链路我用的是 Keras 训练好的分类模型导出的处理方式是去掉最后接的分类层只留特征提取部分然后接一个自定义的全连接降维层。这里有个必须提前说的坑TensorFlow.js 转换器对 Keras 的自定义层支持是有限的我曾经写过的一个 L2 正则层在转换时直接报错。解决方案是把自定义层重构成标准层组合或者用 tf.function 包装后导出 SavedModel再转成 TF.js 格式。转换命令长这样tensorflowjs_converter \ --input_formatkeras \ --output_formattfjs_graph_model \ --quantization_bytes1 \ --output_node_namesfeature_vector \ ./model.h5 \ ./tfjs_modelquantization_bytes1 意思是做 8bit 量化模型体积直接缩到原来的四分之一。我原来那个 MobileNet V2 基础模型是 14MB量化后 3.5MB页面加载负担小了很多。代价是精度轻微下降但我实测下来 top5 准确率只降了 0.8%对商品检索场景完全够用。如果是人脸识别这种对精度极其敏感的场景就要谨慎考虑量化或者退回 Float16 量化试试。转换完成后产物包含一个 model.json 和一组二进制权重文件。注意整个目录要放在静态服务器上运行时 TensorFlow.js 会按 manifest 记录去拉取分片权重。2.2 Worker 中的模型加载与推理代码骨架逐行解析Worker 内部我维护了一个“模型未就绪时先缓存任务”的机制。因为 TF.js 模型加载是异步的用户可能在模型还没 ready 时就快速拖入图片如果直接进入推理流程模型对象还是 null会报错。我的处理是任务队列加自锁状态代码如下// feature-worker.js let model null; let ready false; const taskQueue []; async function initModel() { const modelUrl await getCachedModelUrl(); model await tf.loadGraphModel(modelUrl); // 预热模型用一张全零图跑一次推理避免首次实际预测时产生明显延迟 warmup(); ready true; while (taskQueue.length) { const task taskQueue.shift(); await handleTask(task); } } self.onmessage async (e) { const { id, data, taskType } e.data; if (taskType embed) { if (!ready) { taskQueue.push({ id, data, taskType }); return; } const result await handleTask({ id, data, taskType }); self.postMessage(result); } }; async function handleTask({ id, data, taskType }) { const tensor tf.browser.fromPixels(data, 4) .resizeBilinear([224, 224]) .expandDims(0); const normalized tensor.div(127.5).sub(1); const pred model.predict(normalized); const vec pred.dataSync(); tensor.dispose(); pred.dispose(); return { id, vec }; }这段代码有几个细节值得单独说明。细节一tf.browser.fromPixels 的输入类型。这个方法接收 ImageData、HTMLCanvasElement 或 HTMLVideoElement但不接收 Blob。也就是说主线程从input typefile拿到 File 对象后不能直接传给 Worker 调用 fromPixels必须先解码成 Bitmap 或 Canvas 再传。我在主线程用 createImageBitmap(file) 拿到 ImageBitmap通过 transferable 对象传给 Worker这样可以避免结构化克隆的性能损耗。细节二归一化的写法。tensor.div(127.5).sub(1) 是把像素值从 [0, 255] 映射到 [-1, 1]这是 MobileNet 系列训练时的标准预处理方式。如果训练模型时用的是别的归一化策略这里要对应调整否则特征分布会乱检索精度直接崩。细节三dispose 的时机。model.predict 产生的输出 tensor用完后必须 dispose。TensorFlow.js 的 WebGL 后端如果频繁创建 tensor 而不释放显存会被耗光页面就会越来越卡甚至崩溃。我的习惯是推理函数里所有中间 tensor 都包在 tf.tidy 里const pred tf.tidy(() { const t tf.browser.fromPixels(data, 4).resizeBilinear([224, 224]).expandDims(0); const normalized t.div(127.5).sub(1); return model.predict(normalized); });这样中间结果自动回收只需要手动 dispose 最终输出。2.3 索引结构与检索算法百万级数据量的端侧解法向量库的规模决定索引策略。我的目标量级是五十万到一百万条直接暴力全扫在纯 JS 里也是能跑的——50 万条 1024 维 Float16 向量一次遍历算余弦相似度大约需要 200 到 300 毫秒。这个速度对交互式检索完全够用所以我一开始并没有急着上复杂索引而是先做了个最小验证。但暴力扫的问题不在计算而在内存分配。如果每次查询都新建一个 Float32Array 来存相似度分数50 万条会分配 4MB 临时数组GC 压力不小。我的优化方案是预分配一个 Float32Array 作为结果缓冲区查询时直接写入对应索引最后只做一次 top-K 选择。top-K 的实现用最小堆避免全排序。JS 里堆的代码很短我贴一个简化版function topKSimilarities(scores, k) { const heap []; const heapifyUp (arr, i) { while (i 0) { const parent (i - 1) 1; if (arr[i] arr[parent]) { [arr[i], arr[parent]] [arr[parent], arr[i]]; i parent; } else break; } }; const heapifyDown (arr, i) { while (true) { let smallest i; const left 2 * i 1; const right 2 * i 2; if (left arr.length arr[left] arr[smallest]) smallest left; if (right arr.length arr[right] arr[smallest]) smallest right; if (smallest ! i) { [arr[i], arr[smallest]] [arr[smallest], arr[i]]; i smallest; } else break; } }; for (let i 0; i scores.length; i) { if (heap.length k) { heap.push(scores[i]); heapifyUp(heap, heap.length - 1); } else if (scores[i] heap[0]) { heap[0] scores[i]; heapifyDown(heap, 0); } } return heap.sort((a, b) b - a); }这个堆的核心逻辑是维护一个容量为 K 的最小堆堆顶是当前 K 个最大相似度里的最小值。遍历新分数时如果比堆顶大就替换堆顶并下沉调整否则跳过。这样遍历完所有向量后堆里就是分数最高的 K 个排序复杂度从 O(N log N) 降到 O(N log K)。不过这只是基础版本。真正跑到 100 万条时暴力全扫的时间会涨到 500 到 600 毫秒虽然可以接受但离“流畅”还有差距。后来我加了混合索引先对每条 1024 维向量做一次 PCA 压缩到 32 维签名向量检索时先用签名向量做粗筛把候选集从 100 万缩小到 5 万左右再在这 5 万里做精确距离计算。实测下来检索耗时可降到 35 到 50 毫秒排序结果和全量暴力扫几乎一致。2.4 任务调度与并发控制Worker 不是万能的Worker 解决了主线程卡顿但 Worker 内部还有一个并发问题容易被忽视。TensorFlow.js 的 WebGL 后端依赖 GPU 上下文多个预测如果同时发起会导致 GL 上下文频繁切换反而比串行更慢。所以我在 Worker 里加了个互斥锁确保任意时刻只有一次 predict 在跑。并发控制的代码其实就是一个简单的标志位let predicting false; const waitQueue []; async function runPredict(tensor) { if (predicting) { return await new Promise((resolve) { waitQueue.push({ resolve, tensor }); }); } predicting true; try { const result await model.predict(tensor); return result; } finally { predicting false; if (waitQueue.length) { const next waitQueue.shift(); runPredict(next.tensor).then(next.resolve); } } }这个实现保证了 predict 的串行执行逻辑简单但很有效。批量导入图片时任务会排队依次执行吞吐量虽然不会增加但至少不会出现 GPU 上下文切换导致的性能毛刺。另一个容易忽略的点是 postMessage 的数据传输方式。主线程向 Worker 传图片时如果直接传 ImageData浏览器会做结构化克隆也就是深拷贝100 张图就是 100 次大内存拷贝。正确的做法是使用 transferable object比如把 ArrayBuffer 的所有权转移给 Workerconst buffer await imageBitmapToArrayBuffer(bitmap); worker.postMessage({ buf: buffer }, [buffer]);这样数据是零拷贝移交主线程不再持有这个 ArrayBuffer性能提升非常明显。3. 实测性能数据与调优记录3.1 一组有代表性的数据我手上的测试环境是 MacBook Pro M1 Pro、Chrome 120数据集是 55 万张商品图特征向量 1024 维 Float16。我把关键耗时整理成表格方便对比操作耗时模型加载冷启动含模型下载1.2 秒模型加载IndexedDB 缓存命中120 毫秒单张图像特征提取224x22418 毫秒按条批量特征提取Worker 串行约 140 毫秒/10 条50 万向量暴力扫描 top50260 毫秒混合索引粗筛 精确检索35 毫秒结果回传主线程小于 1 毫秒单看单张 18 毫秒的推理速度大家可能没概念。换算一下就是用户一次性拖入 50 张图批量提取特征大约 1.4 秒虽然能感觉到进度条在走但不会让人抓狂。检索端 35 毫秒基本是无感的用户在搜索框输入或拍照后结果几乎秒出。低端设备上的表现会差不少。我在一台 2018 年的 Intel 核显笔记本上测试模型加载多花 300 毫秒特征提取每张涨到 45 毫秒检索仍然在 50 毫秒左右。原因是检索部分的计算量以内存带宽为主CPU 主频影响没有推理那么大而推理的 WebGL 后端在弱 GPU 上确实吃力这是硬件决定的不算方案缺陷。3.2 性能调优的顺序先推理后索引这是经验之谈性能调优我踩过几次弯路总结出的顺序是先保证推理一致性再优化内存分配最后才是索引算法调优。推理一致性指的是预处理流程必须和训练时一致。我见过很多人拿到模型后直接用原图尺寸丢进网络结果要么报错要么精度稀烂。统一走 resizeBilinear 到 224x224、div(127.5).sub(1) 是基本操作这个不改后面所有优化都没有意义。内存分配的优化是容易被忽略但收益巨大的部分。刚才提到的预分配相似度结果缓冲区就是在这一步做的。一个 50 万长度的 Float32Array 预分配后反复使用比每次查询都 new 一个数组省掉了大量 GC 成本。测过用 Chrome 的任务管理器观察 JS 堆内存优化前查询时堆内存会周期性飙升优化后曲线平稳得多。索引算法的优化是最后一步因为它的复杂度最高。如果没有明显瓶颈暴力全扫也能接受的话就别提前引入聚类和签名向量这些复杂机制否则调试成本很高。我从暴力扫升级到混合索引是在数据量涨到 80 万、单次查询超过 400 毫秒之后才动手的。4. 常见问题与排查技巧实录4.1 模型加载失败或一直 pending问题多半在格式和路径排查模型加载问题我的顺序是先看 Network 面板确认文件是否都 200再判断 JSON 格式。这里有个特别容易踩的坑TensorFlow.js 有 loadGraphModel 和 loadLayersModel 两个加载函数分别对应 Graph model 和 Layers model。两者的 JSON 结构完全不同——GraphModel 的 JSON 里没有 layers 字段而 LayersModel 的结构里有 layers 数组。搞混的话浏览器会报错比如 This document has no layers 或者提示找不到 modelTopology。我的建议是模型转换时指定 --output_formattfjs_graph_model然后统一用 loadGraphModel 加载。GraphModel 对推理更友好图结构更完整而且量化支持更好。另一个是缓存问题。模型静态资源如果放到 CDN要注意 CDN 的回源策略。我一度直接把模型丢在一个没配置好缓存的对象存储桶上用户首次加载模型等了 8 秒体验直接崩盘。现在我的方案是把模型包放到支持 ETag 的静态服务器上配合 IndexedDB 做版本缓存加载时间稳定在 1 秒内。4.2 检索结果不准按照这三步定位结果不准是向量检索最让人头疼的问题。我的排查顺序固定为三步。第一步检查预处理一致性。训练时用的归一化参数和推理时是否一致输入尺寸是否统一。很多时候用户反馈“搜索结果很差”我去一看发现是不同图片走了不同尺寸的缩放特征分布错位导致的。第二步检查向量是否归一化。有些模型输出的 embedding 没有做 L2 normalize如果直接拿来做余弦相似度结果会被向量长度干扰。我的做法是在推理后统一做一次归一化把向量长度拉回 1function l2Normalize(vec) { let sum 0; for (let i 0; i vec.length; i) sum vec[i] * vec[i]; const norm Math.sqrt(sum) || 1e-8; const out new Float32Array(vec.length); for (let i 0; i vec.length; i) out[i] vec[i] / norm; return out; }归一化之后余弦相似度就等价于点积检索算法可以用更高效的实现。第三步回头怀疑模型本身。如果预处理和归一化都没问题但结果依然不好那就要思考模型是不是适配当前的业务场景。比如拿人脸识别模型去做商品检索特征语义完全不匹配效果无论如何都不可能好。模型选型是检索质量的天花板后面的一切优化都只是逼近这个天花板。4.3 Worker 传输效率与内存泄漏关键在引用管理上面的坑比较浅但下面这些就很隐蔽了。我详细讲讲 Worker 传输的细节。第一点是 transfer list 的使用。postMessage 第二个参数用于指定哪些 ArrayBuffer 要把所有权转移给 Worker。如果忘了传第二个参数ArrayBuffer 会走结构化克隆的深拷贝路径大图数据拷贝上百 MB 都是常有的事。不过注意transferable 一旦转移主线程就无法再访问这个 buffer所以只适合一次性使用的数据。第二种更隐蔽的坑是 worker 线程里的内存泄漏。我遇到过多次检索后台堆内存持续上涨的问题排查后发现问题并不全在 tensor 没有 dispose——而是 postMessage 回传向量时如果返回的 ArrayBuffer 在主线程被缓存到集合里且未及时释放相当于 worker 每次都在无意识地为这些“永久引用”产生新对象。解决方法是主线程处理完向量后主动置空引用或者复用固定长度的 ArrayBuffer 池。4.4 兼容性边界Safari 的 OffscreenCanvas 和 iOS 的纹理尺寸兼容性是端侧方案绕不开的话题。Web Worker 所有主流浏览器都支持但 OffscreenCanvas 在 Safari 的支持很差——直到 16.4 版本才基本完整。如果用户群体里有不少 iOS Safari主线程就别依赖 OffscreenCanvas 的 transferToImageBitmap稳妥做法是在主线程用 Canvas 处理图片然后把 ImageData 传给 Worker。另一件容易被忽略的事是 WebGL 纹理尺寸限制。iOS 上 2D 纹理的最大尺寸通常是 4096 或 8192 像素如果图像超过这个限制模型会报 INVALID_VALUE 错误。所以输入图像在传给 Worker 前最好就缩放到 224 到 512 之间既避免纹理超限也减少数据传输量。4.5 增量更新的合并索引策略向量库不是静态的用户会不断往库里加图。如果每次新增都全量重建索引会带来不必要的计算开销。我的方案是维护一个“新增批”和一个“主索引”各自独立检索后合并结果。具体流程是新向量先插入一个缓冲的数组中检索时同时查主索引和缓冲数组把两部分结果合并后按相似度排序。当缓冲数组的长度达到阈值比如 1 万条后台触发一次合并重建把缓冲内容并入主索引重新做聚类划分。合并重建任务我放在 requestIdleCallback 里执行避开用户操作高峰不影响交互体验。5. 踩坑记录与实战心得整个项目做完我最想分享的是一条血泪教训端侧方案看似替云端省了钱但把问题转移到了静态资源分发和设备兼容上这两块一点不能省心。有一次我为了赶进度把模型 JSON 和权重文件直接放在没配缓存的测试服务器上结果用户加载模型要 8 秒直接被客户投诉“页面打不开”。后来我仔细配置了静态服务器模型文件加 ETag 和 Cache-Control前端用 IndexedDB 做二次缓存并实现版本号机制——模型更新时强制重新拉取避免新旧权重混用。这一套做完模型加载稳定在 1 秒内才算是真正能上线。另一个经验是不要一开始就追求百万级性能。我建议新手从 1000 张图起步先跑通端到端流程确认特征质量达标再逐步扩容到十万级、百万级。因为 1000 张图时排查问题非常容易等到百万级才发现特征质量不对回头换模型、改预处理代价就大了。性能优化的顺序也请记牢先保证推理一致性预处理统一再优化内存管理dispose 和缓冲区复用最后才是索引算法调优。顺序反了很容易陷入调参泥潭——一会儿觉得是归一化不对一会儿觉得是聚类参数有问题最后发现根因是最基础的 resize 写错了。如果未来还往这个方向深入我觉得有几个值得探索的扩展点一是把 TF.js 的 WebGL 后端替换为 WebGPU 后端推理速度还能再上一个台阶二是用 WASM SIMD 优化距离计算的密集循环把检索耗时的下限进一步压低三是结合 IndexedDB 做向量库的持久化让用户关掉浏览器再打开索引数据依然在不用重新导入图片。这些方向我部分已经在测试了有结论再跟大家分享。