你有没有认真算过，用TensorFlow.js在浏览器端做视觉向量特征检索，一年能省下多少云端API调用费？传统“以图搜图”走云端，每处理一万张图片就要买请求配额、付带宽费，更麻烦的是图像里往往带着人脸、位置、文档信息，一上服务器就会牵扯一堆隐私合规问题。最近我把一个图片管理应用的特征检索链路整个改成纯端侧方案：TensorFlow.js加载视觉模型，在Web Worker里把每张图实时转成1024维特征向量，然后直接在浏览器内完成向量检索。跑通之后，云端成本确实是0，“数据不出端”也不再是一句宣传语，而是架构上天然成立的事实。
这篇文章会把我的方案和踩坑过程完整记下来，从选型、特征提取、检索索引、Web Worker集成到性能实测都有，适合正在考虑端侧AI、相似图片检索、图像去重这类需求的人参考。我会把“为什么这么设计”和“实际跑起来是什么表现”分开讲，尽量做到能直接照着落地。
1. 先想清楚：端侧检索到底解决了什么，又改了什么
1.1 传统云端架构的三座大山：账单、延迟与合规
所谓“以图搜图”，本质上就是给每张图抽一个特征向量，然后做向量相似度检索。云端方案一般长这样：图片上传到服务器，服务器调用视觉模型或者云端API抽取特征，写入云数据库，检索时再把查询图片也传上去，在云服务器上做向量搜索。
这个链路跑起来之后，你会发现账单没那么简单。API调用费只是一部分，图片上传消耗的带宽、云端对象存储、向量数据库的托管费用、CDN回源流量，每一项都在产生持续成本。我之前统计过一个中等规模的个人相册应用，日均处理两千张图片，仅仅特征抽取API一个月就能烧掉几百块钱，而且用户量只要翻一倍，账单几乎线性增长。
延迟是第二个问题。一张2MB的图片在普通4G网络下上传，单程就要一两秒，云端推理再快，最后结果返回也得用户等。用户滑动相册、点开图片、想要立刻看到相似图，等待超过1秒，体感就会很差。更别提弱网环境下整个功能基本不可用。
合规是第三个隐形负担。用户的相册、截图、扫描文档里，人脸和地理位置信息到处都是。只要图片内容经过服务器，就要考虑数据存储安全、访问权限控制、数据处理协议、合规审计这一整套事情。个人开发者做个小工具，压上这些负担基本就做不下去了。这三个问题叠加起来，你才会理解“端侧”不是一种炫技，而是很多场景下绕不开的选择。
1.2 全端侧方案的架构变化
全端侧方案把整个链路搬到浏览器里，架构变成这样：
- 图片采集自始至终留在本地，不经过任何网络请求；
- TensorFlow.js在浏览器中加载视觉模型，完成特征抽取；
- 特征向量以及向量索引直接存储在浏览器本地；
- 检索计算发生在Web Worker线程里，主线程只负责展示结果。
这个改动最直接的效果是：云服务器、对象存储、向量数据库、API网关，这些基础设施全部不用再碰了。成本从“按量付费”变成“硬件本来就有的算力”，也就是零增量成本。延迟也从“上传-排队-推理-返回”变成了“本地模型推理-本地索引搜索”，网络耗时被彻底拿掉。
隐私和安全方面，因为图片从未离开设备，数据库里没有用户图片，日志里没有用户图片，网络请求里没有用户图片，所以“数据不出端”不再是一个流程承诺，而是一个架构约束。当然我要严谨补充一句：这里说的100%隐私，是指在架构上消除了图片外传的通道，不代表浏览器和插件本身绝对安全。但如果你的威胁模型是“防止开发者通过服务器收集用户图片”，这个方案从源头上就解决了。
1.3 适用边界：什么场景适合，什么场景别硬上
凡事都有边界，端侧向量检索不是万能药。它最适合这几类场景：
- 个人知识库、本地相册、截图管理工具，用户数据高度私密且规模偏向个人；
- 企业内部素材库，图片不允许离开内网环境；
- 断网环境下的图像检索，比如飞机、船舶、野外作业场景；
- 轻量级相似图去重，照片批量入库时自动识别重复和相似图片。
不适合硬上的场景我也踩过：如果特征库规模要达到百万级以上，纯浏览器端的内存和CPU会非常吃力，除非你能接受很慢的检索速度；如果模型每天都要更新，端侧模型的下载和版本管理会变成头疼的问题；如果多用户之间需要共享检索结果，那本质上还是需要一个服务端来做聚合索引，这时候硬做端侧反而舍近求远。
2. 方案选型复盘：为什么偏偏是TensorFlow.js加Web Worker
2.1 端侧推理框架对比：TF.js、ONNX Runtime Web与纯JS计算
做端侧AI推理，浏览器里有几条路可选，我先把实际对比放出来：
| 方案 | 生态衔接 | 浏览器兼容性 | 模型来源 | 适合场景 |
|---|---|---|---|---|
| TensorFlow.js | Keras/TF SavedModel直接转换 | Chrome/Firefox/Safari均有覆盖 | TensorFlow生态 | 从TF训练链路迁移到Web的团队 |
| ONNX Runtime Web | ONNX模型丰富 | 广泛，底层走WASM/WebGL | PyTorch等导出ONNX | 模型训练框架是PyTorch |
| WebGPU原生推理 | 无现成算库 | 兼容性不完整 | 自己写shader | 啃硬核底层，工期宽松 |
| 纯JS手写CNN | 无依赖 | 最兼容 | 自己实现 | 只有极简单模型的教学场景 |
我最后选了TensorFlow.js，原因很直接：我的特征抽取模型原本就是Keras训练出来的，导出成tfjs格式只需要一条命令，张量的预处理、reshape、归一化等算子全部现成，而且浏览器里的内存管理接口（tf.tidy、tf.dispose）设计得很顺手。ONNX Runtime Web我也试过，模型转换没问题，但涉及到自定义的预处理步骤时，还是得自己在JS里拼张量，开发效率明显低一些。
2.2 Web Worker不是优化项，而是必需项
刚开始我的第一版实现是直接在主线程里跑模型推理的。单张图片的推理时间其实不算长，但如果用户一次性导入100张图片入库，连续推理的阻塞时间就会非常明显。页面不是完全卡死，而是滚动变得一顿一顿，按钮点击反馈延迟，动画掉帧，这是典型的JS长任务占满了主线程的表现。
Web Worker的引入把推理和检索从主线程剥离出去。主线程继续负责渲染界面、处理用户交互，Worker线程在后台执行模型推理和相似度计算。两者之间通过postMessage传递消息，只有4KB左右的特征向量需要在消息里往返，而不是把图片数据一遍遍在主线程和Worker之间复制，所以通信开销非常可控。
更关键的一点是：向量检索同样是个计算密集任务。当特征库到达上万条时，每次搜索要对所有向量做点积计算，这也是毫秒级以上但稳定占住CPU的活儿。如果不放进Worker，用户每一次搜索都可能感受到页面微卡。所以在这个方案里，Web Worker不是可选的性能优化，而是保证基本交互体验的前提。
2.3 1024维特征向量从哪来：模型改造与输出层设计
说到1024维，很多人的第一反应是“某个预训练模型直接输出1024维”。实际上我没直接用现成模型，因为大部分公开图像分类模型的输出是一个1000类的分类概率，不是适合做检索的特征向量。我采取的做法是迁移学习改造模型，把它变成一个embedding模型。
具体来说，在原始预训练模型的基础上，把最后的1000类全连接分类层拿掉，替换成这样的结构：全局平均池化层、一个输出1024维的全连接层、一个L2归一化层。训练时用三元组损失或者ArcFace这类度量学习损失，让模型输出的1024维向量在欧氏空间里的距离能真实反映图像的视觉相似度。
为什么要1024维而不是128维或2048维，这背后是平衡取舍。维度太低，特征表达力不够，相近类别的图像在空间里容易挤成一团；维度太高，每条向量占用的内存和计算量都会显著上升。1024维用Float32存储，单个向量正好4KB，一万条向量就是40MB，对现代浏览器来说还比较舒适，检索时每计算一次相似度要做1024次浮点乘法加法，纯JS跑也能接受。这个维度放在端侧，是一个很合理的中间地带。
3. 特征提取链路：从图片到归一化向量的工程实现
3.1 模型准备与转换：h5到tfjs格式
模型在训练阶段用Python完成，保存成h5或者SavedModel之后，转换到tfjs格式非常顺。我使用的是TensorFlow官方提供的tensorflowjs_converter工具，命令大致如下：
tensorflowjs_converter \ --input_format=keras \ --output_format=tfjs_layers_model \ /path/to/feature_extractor.h5 \ /path/to/tfjs_model转换完成之后，目录里会有一个model.json和几个权重分片.bin文件。这里有个细节值得提醒：如果模型里带了一些自定义层，转换时可能会报错，所以训练阶段尽量全部用Keras内置层，比如GlobalAveragePooling2D、Dense、Lambda这类。如果确实需要自定义操作，优先把它改写成Keras支持的数学组合，而不是硬塞一个自定义函数进去。
加载模型的时候，TensorFlow.js有两种接口：tf.loadLayersModel对应上面的layers模型，tf.loadGraphModel对应SavedModel转换来的graph模型。我用的是前者，因为保留了Keras层的结构，输出张量的名字和形状都比较直观。加载之后你可以在代码里打印一下model.outputs，确认输出形状是不是[null, 1024]，这一步能避免后面很多坑。
3.2 Worker内图像预处理与张量构造
特征模型在训练时用的是224x224的输入尺寸，所以在推理之前，图片要先经过“解码-缩放-转张量-归一化”这条流水线。在Web Worker里做这件事，我推荐用createImageBitmap加上OffscreenCanvas，而不是依赖主线程的<canvas>元素，这样解码和缩放都不会占用主线程。
核心代码如下：
async function decodeToTensor(blob) { const bitmap = await createImageBitmap(blob); const canvas = new OffscreenCanvas(bitmap.width, bitmap.height); const ctx = canvas.getContext('2d'); ctx.drawImage(bitmap, 0, 0); const imageData = ctx.getImageData(0, 0, bitmap.width, bitmap.height); bitmap.close(); let tensor = tf.tensor3d( new Uint8Array(imageData.data.buffer), [imageData.height, imageData.width, 4] ); tensor = tf.image.resizeBilinear(tensor, [224, 224]); const rgb = tf.slice(tensor, [0, 0, 0], [-1, -1, 3]); // RGBA -> RGB const floatImg = tf.cast(rgb, 'float32'); const normalized = tf.div(floatImg, 127.5); const input = tf.expandDims(tf.sub(normalized, 1), 0); // [1,224,224,3], 归一化到[-1,1] tensor.dispose(); rgb.dispose(); floatImg.dispose(); normalized.dispose(); return input; }这里有一个很多初学者容易漏的细节：ImageData的通道顺序是RGBA，而绝大多数视觉模型的输入是RGB三通道。如果不把Alpha通道去掉，张量形状会变成[224,224,4]，模型输入层会直接报错，或者更隐蔽地出现精度下降。我用tf.slice把前三个通道截出来，等于为模型准备了干净的RGB输入。
3.3 推理、特征后处理与内存回收
输入张量准备好之后，推理和特征处理可以连在一起写。TensorFlow.js的默认后端是WebGL，但我们最终在Worker里会切到WASM或CPU后端，这个我后面细说。推理代码本身不算复杂：
const normalizedTensor = tf.tidy(() => { const output = model.predict(input); // [1, 1024] const feats = output.squeeze(); // [1024] const norm = tf.sqrt(tf.sum(tf.mul(feats, feats), -1)); return tf.div(feats, norm); // L2归一化 }); const vector = await normalizedTensor.data(); input.dispose(); normalizedTensor.dispose();这里核心是两步：一是取模型输出的1024维向量，二是在送到检索索引之前做L2归一化。为什么要归一化？因为我们的相似度计算用的是余弦相似度，而余弦相似度对于模长不敏感。L2归一化之后，所有向量都被压到单位超球面上，这时“余弦相似度”在数值上就等于“点积”，检索阶段就不需要再考虑模长了。
内存回收是端侧推理最容易翻车的地方。TensorFlow.js里的每一个张量都会占住底层内存，如果长期运行不释放，最终会把浏览器内存吃光。tf.tidy会自动释放回调里创建的中间张量，但要注意回调返回的张量不会被释放，所以我把它留在外部再手动dispose。如果做一个批量入库功能，每处理一张图就调用一次上面的流程，并且把临时Bitmap及时close()，内存曲线就能保持平稳。
4. 检索索引与查询：端侧万级特征库怎么做才不卡
4.1 向量规模的内存与耗时估算
开始写检索之前，先得对规模有一个量级概念。1024维Float32数组，每条向量4KB，我用一张表把不同规模下的内存占用列出来：
| 特征库规模 | 向量裸数据占用 | 加上索引和元数据后的预估 |
|---|---|---|
| 1千条 | 约4MB | 约6-8MB |
| 1万条 | 约40MB | 约50-60MB |
| 10万条 | 约400MB | 约450-500MB |
这个数据告诉我们两件事：第一，个人相册、小型素材库这种几千到几万条的量级，浏览器端完全扛得住；第二，一旦逼近10万条，内存压力就会非常明显，普通低配设备可能会被浏览器直接限制。所以我的建议是，端侧特征库的舒适工作区间在1万到3万条之间，超过这个数量就要考虑分片检索或者降维。
4.2 余弦相似度计算与批量点积优化
因为所有向量都已经L2归一化，搜索时只需要计算查询向量和库内向量的点积。这个操作是纯数值计算，我用一个大Float32Array把所有特征库按行连续存储，配合一个简单的循环去扫：
function searchTopK(query, features, count, k = 10) { const dim = 1024; const scores = []; for (let i = 0; i < count; i++) { const offset = i * dim; let score = 0; for (let j = 0; j < dim; j++) { score += query[j] * features[offset + j]; } scores.push({ index: i, score }); } scores.sort((a, b) => b.score - a.score); return scores.slice(0, k); }这段代码的时间复杂度是O(N×1024)。一万条的规模，一次全量扫描大概要做一千万次浮点乘加，现代设备哪怕用纯JS跑，也就是十几毫秒；10万条会放大到一百毫秒以上。对于用户主动触发的“相似图片”搜索，十几毫秒的延迟完全无感。唯一要注意的是别在每次搜索时都重新分配scores数组，最好的做法是维护一个固定大小的最小堆，或者直接复用已经分配好的数组，避免频繁触发垃圾回收。
如果库继续变大，有一些优化空间：把查询拆到WebAssembly里加速；或者对向量空间做聚类，先找到最近的几个簇中心，只在簇内做暴力搜索。但这些属于扩展话题，对于端侧万级规模的场景，上面的全量扫描配合少量工程优化已经足够稳定。
4.3 增量索引维护与插入删除
特征库不是一成不变的，用户会不断导入新图，也可能删除图片。这里建议把图片元数据和向量索引分开管理：图片ID、创建时间、缩略图这些放进IndexedDB，而向量本身以追加的方式写进一个大的Float32Array。
插入新向量时，直接分配一块新的Float32Array，把旧数据拷贝过去，再加入新向量，整体成本是可以接受的。删除时最稳妥的做法不是物理搬数据，而是维护一个“删除标记”数组，搜索时跳过被标记的位置。虽然删除标记会让内存产生一些碎片，但换来的是代码逻辑简单、主线程和Worker之间不需要频繁同步大规模数据。如果你确实需要紧凑存储，可以定期做一次“全量重建”，把有效向量重新拷贝成新数组，顺便清理标记。
4.4 在IndexedDB中持久化特征库
只保存在内存里的特征库，用户刷新一次页面就全没了，这不可接受。IndexedDB可以存ArrayBuffer，非常适合整块保存特征库。我的做法是把整个Float32Array当成一个对象放进IndexedDB：
function saveSnapshot(buffer) { return new Promise((resolve, reject) => { const req = indexedDB.open('vision-search', 1); req.onupgradeneeded = () => { req.result.createObjectStore('snapshot'); }; req.onsuccess = () => { const tx = req.result.transaction('snapshot', 'readwrite'); tx.objectStore('snapshot').put(buffer, 'features'); tx.oncomplete = resolve; tx.onerror = () => reject(tx.error); }; }); } function loadSnapshot() { return new Promise((resolve) => { const req = indexedDB.open('vision-search', 1); req.onsuccess = () => { const readTx = req.result.transaction('snapshot', 'readonly'); const getReq = readTx.objectStore('snapshot').get('features'); getReq.onsuccess = () => { if (getReq.result) { resolve(new Float32Array(getReq.result)); } else { resolve(null); } }; }; }); }加载完成后，只要把得到的Float32Array交给Worker里的检索模块，它就能脱离IndexedDB独立工作。每做一次批量修改，我就调用一次saveSnapshot，确保刷新之后特征库还在。要注意的是，IndexedDB在不同浏览器下有存储配额限制，所以特征库规模越大，这个持久化方案就越要考虑分片存储，不过这是后话。
5. Web Worker集成细节：模型推理不阻塞UI的完整写法
5.1 主线程与Worker通信的消息设计
把模型和特征库放进Worker后，主线程和Worker之间需要一套清晰的消息协议。我按照操作类型设计了几种消息：
// 主线程 -> Worker { type: 'init', modelUrl: '/models/feature_extractor/model.json' } { type: 'extract', id: 'img_001', bitmap: imageBitmap } { type: 'search', id: 'q_001', query: Float32Array(1024), topK: 10 } { type: 'insert', id: 'img_002', vector: Float32Array(1024) } { type: 'remove', id: 'img_002' } // Worker -> 主线程 { type: 'ready' } { type: 'extractDone', id: 'img_001', vector: Float32Array(1024) } { type: 'searchDone', id: 'q_001', results: [{id, score}] }这套消息设计看起来简单，但我特别建议把id字段全程带上。因为Worker是异步的，多个请求并发返回时，如果没有ID对应，主线程根本不知道哪条结果属于哪个任务。我第一版就是吃了这个亏，批量抽取时结果全乱套。
5.2 Transferable传输与OffscreenCanvas
Worker和主线程之间传数据，最怕大对象的结构化克隆。JS里字符串、数组、对象默认都要被复制一份，图片的像素数据动辄几MB，复制一次就是明显的卡顿。解决办法是把数据转移所有权。
比如主线程拿到用户选择的文件后，先把它变成ImageBitmap，然后通过postMessage的第二个参数，把底层内存直接转移给Worker：
const bitmap = await createImageBitmap(file); worker.postMessage({ type: 'extract', id, bitmap }, [bitmap]);这样主线程这边不再持有bitmap的内存，Worker直接接管，整个过程零拷贝。Worker里接收到bitmap之后，再绘制到OffscreenCanvas上取ImageData，流程就是我前面写的decodeToTensor。这个组合非常适合批量图片入库场景，因为大批量图片交接不会阻塞主线程。
5.3 后端选型：为什么Worker里常要手动切CPU/WASM
TensorFlow.js默认在浏览器里尝试用WebGL做后端，因为GPU并行计算快。但在Worker里，很多浏览器的WebGL上下文创建会受限，模型初始化可能直接抛异常。而且就算能创建，多个WebGL上下文同时存在也容易出现资源争抢和内存暴涨。
我实际在Worker里的做法是显式切到WASM后端：
importScripts('https://cdn.jsdelivr.net/npm/@tensorflow/tfjs@4.20.0/dist/tf.min.js'); importScripts('https://cdn.jsdelivr.net/npm/@tensorflow/tfjs-backend-wasm@4.20.0/dist/tf-backend-wasm.js'); tf.setBackend('wasm'); tf.setWasmPaths('https://cdn.jsdelivr.net/npm/@tensorflow/tfjs-backend-wasm@4.20.0/dist/'); await tf.ready();如果网络环境不适合加载WASM分片，退一步用tf.setBackend('cpu')也能跑，只是单张特征提取耗时可能从二三十毫秒涨到四五十毫秒，还在可接受范围内。这里有个更深的坑：WASM多线程需要服务器开启Cross-Origin-Opener-Policy和Cross-Origin-Embedder-Policy头才能启用SharedArrayBuffer。如果你的项目没有控制响应头的权限，WASM就只能在单线程模式下跑，性能会打折，但稳定性足够。我最后是在开发服务器上手动加这两个头，生产环境如果条件允许也建议打开。
6. 实测数据与踩坑清单：性能基线、内存表现与三个高频坑
6.1 我环境下的性能基线
实测环境：MacBook Pro 2021（M1 Pro），Chrome 118，WASM单线程后端；另一台是中端安卓手机，Chrome浏览器，同样WASM后端。结果如下，仅供参考：
| 场景 | PC浏览器 | 中端安卓手机 |
|---|---|---|
| 单张特征提取（224x224） | 15-35ms | 80-150ms |
| 首次加载模型冷启动 | 约1-2s | 约3-5s |
| 1万条向量全量检索 | 约8-15ms | 约25-50ms |
| 10万条向量全量检索 | 约80-150ms | 约300-500ms |
冷启动耗时主要花在下载模型分片和初始化WASM运行时上，属于一次性成本。实际使用中，用户进入页面后我先在后台执行init，等他浏览相册的功夫模型已经就绪。如果你对首屏启动特别敏感，可以考虑把模型文件放进Service Worker缓存，第二次访问的冷启动会快很多。
6.2 内存增长的来源与预防
端侧方案最容易出现内存问题的地方有三个：图片解码后的像素数据、推理过程中的中间张量、以及不断累积的历史消息对象。像素数据如果处理完不关闭ImageBitmap，大图片会在浏览器里滞留很久；推理中间张量如果不用tf.tidy包裹，每抽一张图就可能泄漏几十MB；消息对象如果不做引用清理，长时间批量入库时主线程侧会积压大量对象。
我的习惯是在每次批量任务前和任务后分别打印一次张量数目：
console.log(tf.memory().numTensors, tf.memory().numBytes);正常执行完一次完整特征提取，张量数目应该回到基线。如果发现每次循环后数量递增，就去检查是不是有中间张量没被释放。调试这种问题，用tf.dispose()逐个释放虽然慢，但能准确找出泄漏点。
6.3 三个高频坑：通道顺序、tidy误用、模型CORS路径
先说通道顺序。ImageData是RGBA，模型要的是RGB，忘了tf.slice去掉Alpha通道的话，轻则Shape不匹配，重则模型前端报错。这个坑在前期试跑阶段很容易碰到，但一碰上就很误导人，因为编译期不报错，运行期报错信息还经常指向模型加载。
第二个坑是tf.tidy滥用异步操作。tf.tidy的回调在执行完之后会统一释放内部创建的中间张量，但如果你在回调里写了await，整个执行顺序就乱了，返回的可能是已经被释放的张量。正确做法是只用同步的TensorFlow.js算子完成计算，最后返回一个张量，再在外部去调用data()异步取数。
第三个坑是模型文件的CORS和路径问题。Worker里通过fetch加载model.json和权重分片，如果模型文件放在不配置跨域头的对象存储上，请求会被浏览器拦截；如果模型model.json里引用的分片路径是相对路径，而你放在构建资源目录的不同层级，也会导致404。我的经验是：模型文件不要放在CDN下面随随便便引用，先在本地启动一个最简单的静态服务，验证model.json能被正确加载，再考虑上CDN。另外生产环境尽量用版本号放在目录里，比如/models/v1/model.json，因为模型迭代后旧版本会被新版本覆盖，已打开的页面就会出现加载错乱。
拖过这些坑之后，整个链路就比较稳定了：用户选图，Worker抽取特征，特征进入索引，搜索时毫秒级返回相似结果，全程无网络请求。现在回过头看，这套方案最值钱的地方不是省了那点API费用，而是把一个原本需要服务器基础设施支撑的AI功能，压缩成了一个纯前端模块。以后想扩展，可以考虑加图片聚类、按人物或场景做分组，这些能力在端侧只要维护好向量索引，都能继续长出来。
