做端侧视觉检索这几个月，我最大的体会是：真正的隐私不是“上云后加密”，而是“根本不上云”。标题里那句话——“0 云端成本与 100% 隐私安全”——听起来有点营销味，但它确实把我做的一个东西概括完了：用 TensorFlow.js 在浏览器里跑图像特征提取，用 Web Worker 扛住计算，最后直接在本地完成 1024 维向量的检索，全程没有任何一行数据离开用户的设备。这篇文章就把整个项目的思路、实现细节和踩过的坑拆开讲一遍，给想在自己项目里集成端侧 AI 检索的同学一个可复用的参考。
1. 先从问题出发：为什么视觉检索必须“端侧化”
1.1 传统视觉检索的云端成本和隐私难题
大多数视觉检索系统长这样：用户上传一张图，服务器跑一遍模型，把图片转换成向量，再在数据库里跟历史向量做相似度计算，最后返回结果。这个架构跑得通，但它有两个很难回避的痛点。
第一个是成本。模型推理要 GPU，向量比对要内存，数据规模上来之后还要上专用检索服务。就算你只做一个个人用的相册检索工具，只要图片数量到了几万张，单台服务器就开始吃紧。我见过不少小团队把图片特征全部塞进云数据库，每个月账单几千块钱，产品却没有一分钱收入。
第二个是隐私，这个比成本更致命。用户把照片传上去，就意味着视觉特征被复制了一份放在你手里。哪怕你承诺“用完即删”，合规上依然有巨大风险。医疗影像、设计稿、私人相册这种敏感数据，很多用户是根本不愿意上传的，再好的功能，只要涉及上传，他们就直接拒绝。
所以“端侧”不是炫技，而是产品形态的必然选择。既然浏览器已经有能力跑模型和算向量，那为什么还要把数据送出去？
1.2 端侧推理的轻量化和可行性
这里我说的“端侧”，特指纯浏览器环境，不需要装 App，不需要本地 Python 环境，打开网页就能用。可能有人会问：浏览器里跑深度学习，能吃吗？
能，而且近几年已经很成熟。TensorFlow.js 把模型编译成可以在浏览器里跑的格式，底层自动选择 WebGL、WASM 或 CPU 后端。尤其随着 WebAssembly SIMD 的普及，纯 CPU 推理的 224×224 分类模型在普通笔记本上也就是几十毫秒的量级。视觉特征提取通常只需要前向推理一次，没有训练过程，这个计算压力对现代设备来说完全可控。
我在这个项目里验证过的路径是：浏览器加载一个 MobileNet 模型，对图片做一次前向传播，拿到 1024 维特征向量，再把这个向量和本地已有的向量库做比对。整个过程主线程几乎不被拖累，因为模型推理和向量比对都放进了 Web Worker。
1.3 这个项目适合哪些场景，不适合哪些场景
先说适合的。本地图片管理工具，用户给自己的照片库建索引，按内容搜相似图；企业内部的设计素材检索，设计稿涉及保密要求，不能上传云端；浏览器插件类的“以图搜图”，想搜本地目录里的图片，又不想建立云端数据库；还有任何对隐私极度敏感的 C 端产品，用端侧检索作为卖点本身就是一个信任标签。
不适合的也很明显。如果你的库有几百万甚至上千万条向量，需要复杂的 ANN 索引和集群调度，那毫无疑问应该用服务端方案。端侧检索能覆盖的量级，我从经验上讲，纯暴力检索在几万条 1024 维向量内是可以用丝滑来形容的，到了十万条需要做分层优化，超过几十万条就只能做压缩或分片了。浏览器不是万能的，但比很多人想象得能干。
2. 方案选型的灵魂三问：TensorFlow.js、Web Worker、1024 维
2.1 为什么是 TensorFlow.js，而不是 ONNX Runtime Web 或 WebDNN
做浏览器端模型推理，可选方案不止 TensorFlow.js。ONNX Runtime Web 可以把 PyTorch 导出的模型直接跑在浏览器里，WebDNN 也曾经是小众选项。但我最后选了 TensorFlow.js，理由很简单：生态成熟、资料多、部署链路短。
TensorFlow.js 的模型格式是 tfjs 的 layers/graph model，用官方转换工具把 SavedModel 或 Keras H5 转过来就能直接加载。最关键的是，tfjs 支持在加载时指定输出层。这对视觉检索是救命功能——我不想要 1000 类的分类 logits，我要的是中间层的图像特征，TensorFlow.js 允许我在加载时传入 outputLayer 名称，直接拿到那个 1024 维的向量。
ONNX Runtime Web 的性能其实并不差，但它在“取中间层输出”这种需求上要多写不少代码，生态里的现成视觉模型也相对少。WebDNN 就更小众了，维护力度明显不足。做工程不是做学术选型，社区活跃度和踩坑案例数量很重要，TensorFlow.js 在这些维度上优势很明显。
2.2 为什么必须加 Web Worker，能否单线程硬扛
端侧检索整个流程可以拆成两个阶段：第一阶段是图像特征提取，前向传播计算量大，第二阶段是向量检索，涉及内存遍历和计算相似度。如果这两件事都放在主线程里做，结果就是用户拖入一张图片，页面直接卡住，滚动不了，按钮点不了，体验非常糟糕。
Web Worker 解决的是“让计算离开主线程”的问题。JavaScript 是单线程语言，但浏览器允许你开多个后台线程，每个 Worker 有自己的全局上下文。把模型加载和向量比对全部塞进 Worker 里，主线程只负责 UI 交互和展示结果，用户操作就始终是流畅的。
能不能不用 Worker？如果你的图片量很小，比如只有几十张，模型推理 20 毫秒，检索 2 毫秒，那确实没必要。但一旦进入“成百上千张图片”的使用场景，加载模型时的解析、第一次推理时的编译、大向量表的复制，任何一个动作都可能让主线程卡顿几百毫秒。用 Worker 不是性能洁癖，而是产品体验的底线。
2.3 为什么是 1024 维，128、512 不行吗
这个数字要先从模型说起。我用的 MobileNet v1，输入 224×224×3，经过一系列深度可分离卷积之后，在最后的全局平均池化层输出 1024 维浮点向量。换句话说，1024 不是我们拍脑袋定的，而是模型架构决定的。当然你可以在最后一层加个 Dense 投影层把维度降下去，但我实测下来，1024 维在这个模型上是“性价比最优”的形态。
维度太低，比如 128 维，特征区分度会明显下降。不同图片之间的余弦相似度拉不开差距，检索结果里会出现很多看起来毫无关系但“距离很近”的错误匹配。维度太高，比如 2048 维，区分度未必提升多少，但内存占用和计算量却翻倍。
还有一个工程上的理由：1024 维 Float32 向量正好是 4KB（1024 × 4 字节）。这个大小对现代 CPU 缓存非常友好，遍历一万条向量就是 40MB 的顺序读，配合内存带宽其实很快。所以从 MobileNet 池化层直接拿 1024 维向量，是模型结构、内存开销和检索效果三者之间的平衡点。
3. 端侧特征提取的实现细节：从图片到 1024 维向量
3.1 模型选型与加载：MobileNet 的 1024 维秘密
MobileNet v1 的结构核心是深度可分离卷积，把标准卷积拆成“逐通道卷积 + 逐点卷积”，参数量和计算量直接降低一个量级。它最后的特征图是 7×7×1024，经过 Global Average Pooling 之后，每张图片就变成一条 1024 维向量。
在 TensorFlow.js 里，加载这个模型的关键代码非常简单：
const model = await tf.loadGraphModel( 'https://example.com/models/mobilenet-v1/model.json', { outputLayer: 'global_average_pooling2d_1' } );outputLayer这个参数至关重要。默认加载模型会把最后的 logits 也带上，输出形状是 [1, 1000]，那是分类得分，不是我们需要的向量。指定global_average_pooling2d_1之后，模型输出就是 [1, 1024] 的二维张量，直接就是图片的语义特征。
这里强烈建议把模型文件部署在支持 CORS 的静态服务上，并使用 HTTPS。踩过坑的人都知道，浏览器加载模型跨域报错是最常见的问题之一，后面排查章节我会单独讲。
3.2 Web Worker 里的图片解码与张量转换
主线程拿到用户选择的 File 对象之后，整个 AI 计算流程的工作流应该是：
- 主线程把 File 对象通过
postMessage传给 Worker。 - Worker 内部用
createImageBitmap(file)解码图片，拿到位图数据。 - 位图缩放到 224×224，用 Canvas 转成 RGB 像素数据。
- 像素数据传给
tf.tensor3d，并做归一化到 [-1, 1] 区间。 - 执行模型推理，拿到特征向量。
整个过程里，Worker 有一个天然优势：它支持createImageBitmap和OffscreenCanvas，可以在后台线程直接完成图像解码与缩放，不会占用主线程的渲染管线。这是很多浏览器应用忽略的性能细节。
转换张量的代码大致长这样：
async function imageFileToTensor(file) { const bitmap = await createImageBitmap(file); const canvas = new OffscreenCanvas(224, 224); const ctx = canvas.getContext('2d'); ctx.drawImage(bitmap, 0, 0, 224, 224); const imageData = ctx.getImageData(0, 0, 224, 224); const input = tf.tensor3d(new Float32Array(imageData.data), [224, 224, 4]); return input.slice([0, 0, 0], [224, 224, 3]) .reverse(2) .div(127.5) .sub(1); }注意reverse(2)是因为 MobileNet 的预训练权重用的是 RGB 顺序，而 Canvas 的 ImageData 是 RGBA。这个顺序问题非常隐蔽，如果不做反转，你提取出来的特征向量完全不可用，但程序又不报错，排查起来特别痛苦。
3.3 特征归一化与向量的语义意义
拿到模型输出的 [1, 1024] 张量之后，第一步操作永远是把数据拉平成 Float32Array，然后做 L2 归一化。为什么必须归一化？
因为后面做相似度计算时，我要用余弦相似度。余弦相似度看的是两个向量的方向是否一致，跟长度无关。归一化之后，向量长度变成 1，余弦相似度就退化为内积。这不仅是数学上的简化，更重要的是，工程上可以直接用 SIMD 优化的批量内积计算替代逐条余弦公式，性能差距有三倍以上。
function normalizeVector(vec) { let sum = 0; for (let i = 0; i < vec.length; i++) { sum += vec[i] * vec[i]; } const norm = Math.sqrt(sum) || 1; for (let i = 0; i < vec.length; i++) { vec[i] /= norm; } return vec; }归一化之后的特征向量有什么语义？打个比方，MobileNet 的 1024 维空间里，每一维并不是“是不是猫”这种可解释的概念，更像是一个 1024 维语义空间的坐标。经过大量图片训练后，同一个物体的不同拍摄角度、不同光照条件，映射到这个空间里的点会聚在一起，方向和语义紧密相关。因此内积越大，两个点在语义上越接近。
4. 本地向量库的构建与检索：零云端的关键拼图
4.1 IndexedDB 存储设计
有了向量，接下来就是持久化。我们不可能每次刷新页面都重新提取几千张图的特征，数据必须落在本地。IndexedDB 是浏览器内置的非关系型数据库，也是本地存储向量的事实标准。
我的存储结构设计成三个字段：id是自增主键，feature是 Float32Array 转成的 ArrayBuffer，meta是 JSON 对象，记录图片名称、缩略图 Blob、时间戳等信息。
const tx = db.transaction('vectors', 'readwrite'); const store = tx.objectStore('vectors'); store.put({ id: autoIncrementId, feature: featureVector.buffer, meta: { name: fileName, thumb: thumbnailBlob } });真正的向量以二进制形式存成 ArrayBuffer，不要用 JSON 数组存。我见过有人把 Float32Array 展开成普通数组再 JSON.stringify 存进去，一条向量存成几千字符的文本，结果一个 5000 张图片的库占用几十 MB 而且读取慢。用 ArrayBuffer 的话，一条向量就是 4KB，5000 条也就是 20MB，而且 IndexedDB 读取 ArrayBuffer 是零拷贝的，效率完全不在一个量级。
批量写入一定要用事务批处理，不要逐条单独开事务。浏览器每开一个 IndexedDB 事务都有固定开销，逐条 put 一千条数据的耗时可能是事务内的数倍。
4.2 暴力检索的优化：预归一化 + 最大堆
端侧库的规模通常不会超过几万条，这种情况下，一个经典的暴力 Top-K 检索，也就是“把每条向量跟查询向量做内积，取最大 K 个值”，完全够用。但优化空间依然不小。
第一个优化是预归一化。上面说过，入库前就把向量全部归一化，于是检索阶段只需要做点积，不需要再算分母。点积本质上是一次长度为 1024 的循环累加，对现代 CPU 来说极其友好。
第二个优化是内存连续性。把整个向量库读出来，放进一个大的 Float32Array 里，结构上就是“由 1024 列组成的矩阵”。遍历的时候用偏移量定位，访问连续内存，比逐条读取对象再取属性要快得多。
第三个优化是 Top-K 选择。如果你需要的不只是最相似的一张图，而是 10 张，最简单的方式是全量算完后对整个数组排序。但排序复杂度是 O(n log n)，而维护一个容量为 K 的最小堆，遍历一遍即可，复杂度降到 O(n log k)。当 K 远小于 n 时，性能差异非常明显。我实测里，K=10、n=10000 的情况下，堆方式比全排序快了近十倍。
4.3 检索代码实战：从 Query 到 Top-K
我把检索的核心循环写在下面，几百条注释已经把每一步解释清楚：
function searchTopK(queryVector, vectorMatrix, k) { const n = vectorMatrix.length / 1024; const heap = []; // 存放 [score, id]，始终维护 k 个最大的 for (let i = 0; i < n; i++) { let score = 0; const offset = i * 1024; for (let j = 0; j < 1024; j++) { score += queryVector[j] * vectorMatrix[offset + j]; } if (heap.length < k) { heap.push([score, i]); if (heap.length === k) { heap.sort((a, b) => a[0] - b[0]); // 小顶堆初始化 } } else if (score > heap[0][0]) { heap[0] = [score, i]; heap.sort((a, b) => a[0] - b[0]); } } return heap.sort((a, b) => b[0] - a[0]); }这段代码我在项目里用的是简化版，用数组加 sort 代替了真正的堆实现。如果你想追求极致性能，可以自己写一个二叉堆，但对于从 localStorage 读几百 KB 数据的场景，上述代码已经表现足够理想。核心思想是：只保留 K 个候选，维持它们有序，每次遇到更大 score 就替换掉当前最小值。
4.4 大数据量下的性能分层策略
暴力检索在几千条向量的时候是“优雅”的，到五万条以上就必须分层。
我在项目里做了一组压测，6 年前的 MacBook Pro 上，纯 WASM 双精度浮点点积，一万条 1024 维向量的全量内积大约耗时 15 毫秒左右。到了五万条，时间涨到 80 毫秒，肉眼已经能感知到卡顿。终端设备硬件参差不齐，手机尤其弱，所以预留一个性能降级策略很重要。
分层方案我总结成三层：
- 第一层，直接用暴力检索，适用于一万条以内。
- 第二层，加一道粗筛，做法是对向量降维到 128 维，先粗筛掉明显不相关的 90%，然后再对剩余候选做全量 1024 维精算。
- 第三层，对向量做乘积量化（PQ 压缩），把一条 1024 维浮点向量量化成几十字节，在内存里缓存压缩后的码本，这样单库能撑到几十万的量级，代价是检索精度会有几个百分点的损失。
大多数项目做到第二层就够了。第三层适合有重度检索需求的场景，但实现复杂度明显上升，我建议先做前两层，等真的撞到瓶颈再上 PQ。
5. 性能调优与浏览器硬件的“斤斤计较”
5.1 显存与内存：dispose()是必修课
TensorFlow.js 管理的是一个和原生环境不同的内存池。你在浏览器里创建的每一个 Tensor，如果手动调用.dispose()或者用tf.tidy()包裹，内存是不会被 JavaScript 垃圾回收器自动回收的。新手项目跑几次模型推理之后，页面越来越卡，最后直接崩溃，绝大多数都是这个原因。
我在实战中养成了几条铁律：
- 模型推理、张量创建、Tensor 中间结果，全部用
tf.tidy()包起来。 - 凡是需要跨函数共享的 Tensor，必须在用完后显式调用
dispose()。 - 拿到最终特征向量后，立刻调用
.dataSync()拷贝成纯 JavaScript 数组，同时把模型输出 Tensor 释放掉。 - 一次完整推理流程中，尽量复用输入 Tensor，不要反复创建销毁。
一个典型反例是：有人每次推理都tf.zeros([1,224,224,3])再填充值，然后推理完不释放。只跑十次就吃掉几十 MB 显存。这种“内存泄漏”不是 bug，是习惯问题。
5.2 WASM 后端 vs WebGL 后端的取舍
TensorFlow.js 有 WebGL、WASM、CPU 三个主要后端。对于特征提取这种单次前向推理任务，WebGL 后端的训练性能最好，但它有几个致命问题：一是在部分老旧显卡上精度不稳定，二是 WebGL 上下文在主线程和 Worker 之间的限制很多，三是移动端兼容性参差。
我在 Worker 里实际使用的后端是 WASM。WASM 后端的性能虽然没有 WebGL 那么夸张，但它的确定性极好，跨平台表现一致，尤其配合 SIMD 后，MobileNet 的一次推理在一台普通 i7 笔记本上大概 60-80 毫秒。这个速度完全可以接受。
选 WASM 还有一个隐藏理由：它不依赖 GPU 渲染管线，所以即使页面开着几十个标签页、GPU 资源被大量抢占，推理速度依然稳。产品稳定性很多时候比峰值性能更重要。
设置后端的代码就一行：
await tf.setBackend('wasm'); await tf.ready();5.3 Transferable Objects：零拷贝传递大块二进制数据
主线程和 Worker 之间传数据，最常规的方式是结构化克隆，也就是把数据复制一份。但对一个动辄几 MB 的 Float32Array 来说，复制成本极高。解决方法是使用 Transferable Objects，把底层 ArrayBuffer 的所有权直接转移给接收方，数据零拷贝。
在实际项目里，我把索引用的向量矩阵预先在 Worker 里组装好。每次用户发起检索时，查询向量用一个 Float32Array 传过去，并显式声明 transfer：
worker.postMessage( { type: 'search', query: queryVector.buffer }, [queryVector.buffer] );第二个参数数组里列出的 buffer，会被直接转移，不再复制。代价是主线程里原来的对象就不能再用了，但对于一次性查询向量来说完全无所谓。
5.4 实测数据：端侧到底能抗多少量级
我自己的测试环境，一台 2020 款 M1 MacBook Air，Chrome 120：
- 图片解码加缩放：约 5 毫秒
- MobileNet 单张图特征提取（WASM 后端）：约 55 毫秒
- 10000 条 1024 维向量的暴力内积检索：约 10 毫秒
- 包括读取 IndexedDB 在内，一次完整“查询 → 返回 Top-10”总耗时约 90 毫秒
在配置低一点的 Android 手机上，这个数字会放大 2 到 3 倍，全程依旧在 300 毫秒以内，交互上是无感的。所以一万条以内，端侧暴力检索完全不是问题；五万条以内，配合降维粗筛也还流畅；再往上，就该考虑近似检索了。对于绝大多数“个人知识库”级别的应用，这个方案绰绰有余。
6. 踩坑记录与排查清单：那些文档里不写的事
6.1 模型加载慢和加载失败的几类原因
第一类是跨域。TensorFlow.js 加载模型时会对 model.json 发一个 fetch 请求，任何跨域资源都必须正确配置 CORS 响应头。我在项目里因为临时用了一个不支持 CORS 的图床，花了半小时排查这个白屏问题。解决方法是把模型放到同域、或使用配置正确 CORS 的对象存储，唯一的例外是开发环境可以用本地服务代理转发。
第二类是相对路径坑。模型内部引用的分片权重文件，用的是 model.json 里的相对路径，而浏览器是拿“页面 URL”做基准解析的。如果页面 URL 在 /tools/search/ 下，模型在 /models/ 下，相对路径就失效了。我建议始终给模型提供完整绝对 URL，避免这个祖传坑。
第三类是首次加载编译慢。WASM 后端第一次推理前会做线程池初始化和模型编译，耗时可能达到 2-3 秒。不要把这个时间算进“推理性能”里，要做预加载：页面空闲时就初始化 TensorFlow.js 后端并加载模型，用户真正使用时才能秒开。
6.2 Safari 与隐私模式下的 IndexedDB 坑
Safari 的 IndexedDB 支持虽然存在，但一直不够稳定。最大的坑有两个：第一，隐私模式下 Safari 会把 IndexedDB 的数据放在内存里，刷新页面就没了，你不能把隐私模式当成持久化环境来做紧急备份；第二，Safari 某些老版本对 IndexedDB 的事务并发支持有限，读写事务同时打开时会抛AbortError。
我的处理方式是在启动时做一次存储可用性探测，写入一条测试记录再读取并删除，失败就启用内存降级方案。虽然不能完全取代数据库，但至少不会让整个应用崩溃。
6.3 结果不准：相似度阈值该定多少
所有检索系统都会遇到一个问题：图库里根本没有相似的图，但它还是会返回“最相似”的前十名，而且分数看起来很合理。我见过不少用户因为这个原因，把完全不相关的图片当成了匹配结果。
归一化之后，内积值在 -1 到 1 之间。MobileNet 特征空间的特性是，任何两张随机图片的余弦相似度大概在 0.4 到 0.7 之间，真正同类别图片的相似度通常在 0.85 以上。我在项目里把阈值定在 0.78，低于这个值就认为没有匹配项。但阈值的选择跟你的图库内容强相关，建议发布前自己用一批正负样本做测试。
值得注意的坑是：检索 Top-K 时，不能只看分数，还要设置一个“最低分数门槛”。只取 Top-K 不设门槛，是“假阳性”的万恶之源。
6.4 多 Worker 场景下会不会“打架”
如果你的应用需要同时处理多路任务，比如一边批量入库图片，一边响应用户检索，通常会开多个 Worker。这里最隐蔽的问题是：TensorFlow.js 在每个 Worker 里加载模型，是各加载各的。每个 Worker 都有完整模型副本，内存占用是叠加的，模型解析时间也是叠加的。
更隐蔽的是，两个 Worker 同时用 WASM 后端初始化线程池，会造成一段时间的 CPU 争抢，表现为两端任务同时变慢。我在项目里的策略是：一个 Worker 专职负责模型推理和特征提取，另一个 Worker 专职负责向量检索和 IndexedDB 读写。模型推理 Worker 串行处理所有入库和查询特征提取，检索 Worker 不加载模型，只做向量计算。这样既避免重复加载，也让检索的实时性得到保证。
7. 最后说点实操体会
项目做下来，我的最大感受是：端侧 AI 的门槛已经低到任何一个前端开发者都能上手，但真正拉开差距的是工程细节。TensorFlow.js 让模型运行变得简单，Web Worker 让计算不阻塞 UI，IndexedDB 让数据有了永久归宿，这三者组合起来，确实可以把“云端检索”整体替代掉。你不需要有深度学习背景，只需要理解自己的业务数据长什么样，然后耐心做几轮性能和精度调优。
如果这个方向你想继续深挖，我建议下一步尝试自己训练一个小模型替换 MobileNet。比如用 EfficentNet-Lite 在自有数据集上微调，或者用对比学习把特征空间训练得更有区分度，1024 维向量的检索效果会再上一个台阶。端侧这条路，越走越宽。
