本地目录里有1万多张照片，你想做“以图搜图”、按视觉相似度去重，或者从素材库里找出所有同款包装图。过去我的第一反应是调云端API，传图片上去，拿向量回来再对接向量数据库。直到有一次处理一批不能出内网的图片，我彻底放弃了这个思路——图片一旦传上去，隐私边界就破了。后来我完整搭了一套浏览器端方案：TensorFlow.js负责跑模型，Web Worker负责推理，1024维视觉特征向量在内存和IndexedDB之间完成检索，整个过程没有任何云端计算，也不需要数据库服务。这篇文章就把这套方案的架构决策、核心实现、性能实测和踩坑记录完整分享出来，给想做端侧AI、本地知识库、私有化素材检索的朋友作参考。
1. 为什么要做端侧向量检索，而不是调用云端API
先别急着写代码，把为什么选择端侧这条路想清楚。很多人一听“浏览器里跑模型”，第一反应是性能够不够、有没有必要。这个质疑合理，但得分场景。
1.1 这个项目到底解决什么问题
传统的以图搜图链路是：上传图片到服务器 -> 服务端跑embedding模型 -> 得到特征向量 -> 存入向量数据库 -> 查询时再算相似度。这套链路很成熟，但它有三个无法回避的问题。
第一是隐私。图片这种数据极其敏感，人脸照片、产品设计稿、内部资料截图，只要出了本地硬盘，就相当于把控制权交了出去。即使云厂商承诺不查看，合规压力和心理门槛都在。第二是成本。“0云端成本”不是说静态托管也不要钱，而是指没有按推理次数计费的GPU实例、没有按存储量计费的向量数据库、没有按流量计费的API调用。你搭一个自己用的工具，每个月账单是0，这和云端方案的月租费是完全不同的概念。第三是可用性。内网环境、离线环境、临时演示环境，云端API根本连不上。
所以这个项目的核心定位很明确：它是一个完全运行在用户浏览器里的本地图片特征提取与相似度检索工具，适合个人本地相册管理、企业内部素材库、离线演示系统，以及所有“图片不能出内网”的场景。
1.2 这套方案适合谁、不适合谁
我得先把边界划清楚，避免你看了开头就盲目套用。
端侧方案最舒服的场景是数据量在万级以下。1万张图片，每张提取一个1024维向量，内存占用大约是1万乘以1024乘以4字节，也就是40MB左右，浏览器扛得住。检索时用暴力遍历加矩阵运算，1万条也就是几十毫秒的事。如果数据量到了百万级，浏览器内存会先撑不住，检索速度也会明显劣化，这时候还是得老老实实用服务端向量数据库，或者走WebAssembly + 分片索引的极端优化路线。
另外还要想清楚应用场景。如果你是做C端产品的图像搜索功能，有大量并发用户，那端侧方案只适合做前端预处理，最终的召回和排序还是得靠服务端。但如果你做的是工具型应用、内部系统、个人项目，数据量可控，那端侧方案从部署成本到隐私表现都是碾压性的优势。
1.3 端侧推理的成本账
很多人误以为“本地推理”没有成本，其实成本从云端转移到了客户端设备上。用户打开页面时，需要下载模型文件、加载推理运行时、占用CPU或GPU资源。这些成本不是货币，而是加载时间、内存占用和耗电。
好处是这笔成本只付一次。模型文件可以通过浏览器缓存或者Service Worker缓存下来，第二次打开几乎秒加载。云端方案则是每次调用都要付费，数据量越大账单越吓人。对于个人工具和内部系统，端侧方案在总拥有成本上完胜。
2. 1024维特征向量是怎么来的
核心链路的第一步是“提特征”。我们要把一张图片变成一串固定长度的数字，这个数字串要能表达图片的视觉语义——相似的图片在向量空间里距离近，不同的图片距离远。
2.1 视觉embedding模型选择
做视觉向量最常见的做法是用分类模型去掉最后的全连接分类层，把倒数第二层的特征图池化成一个向量。但这会带来一个问题：分类模型训练时用的是ImageNet那样的大数据集，最后一层之前的特征更多关注“这是什么物体”，而不是“这两张图视觉上像不像”。所以更靠谱的做法是直接使用为图像检索设计的embedding模型，比如MobileNetV2/V3加Metric Learning微调后的版本，或者EfficientNet-Lite系列的embedding输出。
我实际用的是MobileNetV2作为backbone，在倒数第二层接了一个全连接层输出1024维向量，用ArcFace或者Triplet Loss在相似图数据集上微调过。这样模型对“同款不同角度”“同款不同光照”的容忍度会更好。如果只拿一个裸的分类模型直接截断输出，检索效果往往差强人意。
TensorFlow.js运行这种模型没有任何问题。MobileNetV2参数量大约350万，FP32模型文件约14MB，量化到uint8后可以压到4MB左右，在浏览器里加载和推理都很轻松。
2.2 TensorFlow.js如何运行模型
TensorFlow.js（简称tfjs）有三个核心后端：WebGL、WASM和WebGPU。
WebGL后端利用GPU加速矩阵运算，推理速度最快，但兼容性偶尔有坑，比如某些老显卡驱动会导致精度问题。WASM后端是纯CPU计算，兼容性最好，速度比WebGL慢，但在移动端和低端设备上反而更稳定。WebGPU是新生代，性能上限最高，但现在还需要手动开启浏览器特性，暂时不放在生产方案里。
我的建议是默认用WASM后端，理由是稳定和可预测。对于MobileNetV2这种规模的模型，WASM推理一张224x224的图片在桌面端大约50到150毫秒，移动端大约300到800毫秒，完全够用。如果你需要极致的批量处理速度，可以动态切到WebGL，后面我会讲切换方法和注意事项。
模型文件本身需要从TensorFlow的SavedModel或者Keras的H5格式转换成tfjs的格式。转换工具是官方提供的tensorflowjs_converter命令，转换完成后生产一份model.json加若干分片权重文件，部署时扔到静态目录就行。
2.3 为什么输出定在1024维
这里有个很实际的问题：向量维度是不是越大越好？1024维是工程上的一个折中。
维度越高，表达能力越强，能保留更多视觉细节，但存储和计算开销也线性增长。512维能省一半内存，但实验下来在细粒度检索上，区分度会明显下降。128维这种轻量级配置只适合粗分类级别的相似度判断。1024维在万级数据量下的内存开销是40MB，检索一次是千万次浮点运算，对浏览器来说都在舒适区。
另外一个关键细节是向量要做L2归一化。归一化之后，向量的模长变成1，余弦相似度就等于内积，也就是点积。这大大简化了后续检索算法的实现，矩阵乘法算出来的就是相似度，不用再单独计算余弦值了。
3. 检索链路的多线程设计与存储选型
特征向量生产出来了，接下来要解决两个问题：向量存哪里，以及检索怎么跑得快还不卡界面。这就引出了Web Worker和IndexedDB。
3.1 主线程和Worker的分工
在浏览器里，JavaScript默认跑在UI主线程上。如果在主线程里跑TensorFlow.js推理，用户会看到页面卡死，交互全部无响应，这在真实项目里是不可接受的。
所以我的架构是：主线程只负责文件读取、UI渲染和向量检索结果展示，所有模型加载和推理逻辑全部塞进Web Worker。Worker是浏览器里的独立线程，有自己独立的JavaScript上下文，和主线程通过postMessage通信。
这里有一个性能关键点：图片数据从主线程传到Worker时，要用可转移对象（transferable objects）。最理想的做法是主线程用createImageBitmap把图片文件解码成ImageBitmap，然后通过postMessage的第二个参数直接转移给Worker。ImageBitmap是支持转移的，转移之后主线程不再持有这块内存，Worker可以直接使用，没有任何结构化克隆的拷贝开销。
Worker内部拿到ImageBitmap之后，用tf.browser.fromPixels把它转成张量，做resize、归一化、推理，最后把1024维Float32Array返回给主线程。主线程拿到向量后存入内存索引，并通过IndexedDB持久化。
Worker还要处理模型初始化。tensorflow.js在Worker里初始化和主线程不一样，需要手动指定WASM路径、调用tf.ready等待后端就绪，然后再加载模型。这一块顺序错了就会出现各种诡异报错，后面踩坑部分我会细讲。
3.2 特征向量的持久化：IndexedDB
页面刷新之后，内存里的向量就没了，总不能每次打开都重新提取一次全部图片的特征。所以向量必须持久化，浏览器端的持久化方案就是IndexedDB。
IndexedDB是一个事务型的NoSQL数据库，适合存储结构化数据和二进制数据。我把每个向量作为一条记录，字段包含：vector（Float32Array）、thumbBlob（压缩后的缩略图Blob）、原始文件名、图片尺寸、创建时间。缩略图也存进去，这样检索结果页可以直接从IndexedDB读取缩略图，不需要再等原图加载。
有一个经验是：写IndexedDB要批量操作，不要一张图一条事务。我实测下来，1万条向量逐条写入大约需要几十秒，但如果攒够500条一次性写入一个事务，耗时可以压缩到几秒。另外存储时向量直接存Float32Array，不要转成普通数组。Float32Array转普通数组，内存占用直接翻三倍，IndexedDB里的存储空间也白白浪费。
3.3 检索算法：先从暴力检索开始
检索方案我强烈建议从暴力检索起步，别一上来就上IVF、HNSW这类近似最近邻索引。原因很简单：万级数据量下，暴力检索在浏览器里已经足够快。
暴力检索的数学本质是：把所有向量排列成一个矩阵，形状是（N, 1024），查询向量是一个（1024, 1）的列向量，二者做矩阵乘法，得到（N, 1）的相似度分数。因为向量已经L2归一化，这个分数就是余弦相似度。
如果用纯JavaScript循环做，1万条乘以1024维，大约一千万次乘加运算，实测大约30到60毫秒。如果改用TensorFlow.js的张量批量运算，让WebGL或者WASM后端来做矩阵乘法，时间可以压到5毫秒以内，不过要承担数据从内存搬运到张量的拷贝开销。日常使用不急的话，纯JavaScript遍历完全可以接受，代码简单、没有张量生命周期管理的问题。
真正的索引优化要等到数据量超过5万条以上再考虑。真到那时候，我会优先考虑按类别粗分桶做倒排，然后再在桶内做暴力检索，而不是在浏览器里硬塞一个HNSW库。浏览器端的堆内存限制决定了，超大数据量终归要走向服务端方案，端侧适合的是轻量、隐私、中小规模的应用。
4. 完整实操：从零构建本地图片相似检索
理论说够了，下面进入实操环节。我按实际开发顺序，把模型准备、Worker实现、主线程存储与检索、性能优化四部分完整走一遍。
4.1 准备浏览器端的embedding模型
首先你需要一个输入为（1, 224, 224, 3）、输出为（1, 1024）的视觉embedding模型。这个模型可以自己训练，也可以从开源模型库找MobileNetV2或者EfficientNet的embedding版本。
模型准备好之后，用官方转换工具导出成tfjs格式。假设你已经有一个SavedModel格式的模型目录，执行下面的命令：
tensorflowjs_converter \ --input_format=tf_saved_model \ --output_format=tfjs_graph_model \ --signature_name=serving_default \ --quantization_bytes=1 \ ./saved_model \ ./public/models/embedding--quantization_bytes=1表示把权重量化成uint8，模型体积可以压缩到原来的四分之一到五分之一。量化后精度会有一点点损失，但视觉embedding的鲁棒性通常不受明显影响。转换完成后，public/models/embedding目录下会有model.json和若干个bin分片文件。
4.2 Worker端的特征提取实现
Worker文件是整个方案的核心。我的worker.js结构如下：
// worker.js importScripts('/vendor/tf.min.js'); let model = null; const MODEL_URL = '/models/embedding/model.json'; const INPUT_SIZE = 224; async function ensureInit() { if (model) return; // 优先使用 WASM 后端，稳定且内存可控 tf.setBackend('wasm'); tf.wasm.setWasmPaths('/vendor/wasm/'); await tf.ready(); model = await tf.loadGraphModel(MODEL_URL); } async function extractEmbedding(bitmap) { return tf.tidy(() => { let input = tf.browser.fromPixels(bitmap); if (input.shape[0] !== INPUT_SIZE || input.shape[1] !== INPUT_SIZE) { input = tf.image.resizeBilinear(input, [INPUT_SIZE, INPUT_SIZE]); } const batched = input.expandDims(0).toFloat().div(255); // ImageNet 标准化参数，按模型训练时的预处理保持一致 const mean = tf.tensor4d([0.485, 0.456, 0.406]).reshape([1, 1, 1, 3]); const std = tf.tensor4d([0.229, 0.224, 0.225]).reshape([1, 1, 1, 3]); const normalized = batched.sub(mean).div(std); const vec = model.predict(normalized); // 形状 [1, 1024] const norm = vec.norm(); return vec.div(norm).squeeze(); // 形状 [1024] }); } self.onmessage = async (e) => { const { id, type, bitmap } = e.data; try { if (type === 'init') { await ensureInit(); postMessage({ id, type: 'ready' }); } else if (type === 'extract') { await ensureInit(); const embedding = await extractEmbedding(bitmap); const data = await embedding.data(); // Float32Array embedding.dispose(); // 直接转移 ArrayBuffer，避免拷贝 postMessage({ id, type: 'embedding', embedding: data }, [data.buffer]); } } catch (err) { postMessage({ id, type: 'error', message: err.message }); } finally { if (bitmap) bitmap.close(); } };几个关键细节说明如下。
tf.tidy是TensorFlow.js的自动内存管理器，回调里创建的所有中间张量都会在回调结束后自动释放。推理代码务必包在tidy里，否则每次提取都会泄漏一部分GPU内存，页面跑几百张图之后就会崩溃。
embedding.data()返回的是Promise ，这一步是异步的，原因是数据要从后端计算设备复制回CPU。这里需要用await等待，而且调用data()之后，embedding张量已经不再需要，可以手动dispose。
postMessage的第二个参数是转移列表。Float32Array的底层ArrayBuffer被转移后，Worker这边就不能再访问了，所以转移之前要先拿到数据，转移之后不要再碰。在主线程那边，收到的embedding已经是一个独立的Float32Array。
bitmap.close()也很重要。ImageBitmap占用的是GPU内存，不主动关闭会泄漏。在finally里统一关闭，保证即使推理出错也能释放。
4.3 主线程的向量存储与TopK检索实现
主线程这边的职责是：接受图片文件，转成ImageBitmap，丢给Worker提特征；拿到特征后写入内存索引和IndexedDB；查询时执行相似度计算和TopK排序。
// main.js const worker = new Worker('/worker.js'); worker.postMessage({ id: 0, type: 'init' }); let seq = 0; let metaList = []; // 每张图的元信息 let vectorChunks = []; // 向量分块存储，每块 Float32Array worker.onmessage = async (e) => { const msg = e.data; if (msg.type === 'embedding') { await handleEmbedding(msg.id, msg.embedding); } else if (msg.type === 'error') { console.error('Worker 错误:', msg.message); } }; async function handleEmbedding(fileId, vec) { const vecCopy = new Float32Array(vec); const meta = metaMap.get(fileId); metaList.push(meta); // 追加到向量分块中，末尾一块快满时新建一块 const lastChunk = vectorChunks[vectorChunks.length - 1]; const insertPos = lastChunk ? lastChunk.used : 0; if (!lastChunk || insertPos + 1024 > lastChunk.data.length) { const newChunk = { data: new Float32Array(1024 * 512), used: 0 }; vectorChunks.push(newChunk); } const chunk = vectorChunks[vectorChunks.length - 1]; chunk.data.set(vecCopy, chunk.used); chunk.used += 1024; await saveRecordToIDB(metaList.length - 1, vecCopy, meta); } function searchByVector(queryVec, topK = 10) { const query = new Float32Array(queryVec); const results = []; let base = 0; for (const chunk of vectorChunks) { const count = chunk.used / 1024; for (let i = 0; i < count; i++) { let score = 0; const offset = i * 1024; for (let j = 0; j < 1024; j++) { score += query[j] * chunk.data[offset + j]; } results.push({ index: base + i, score }); } base += count; } results.sort((a, b) => b.score - a.score); return results.slice(0, topK).map(r => ({ meta: metaList[r.index], score: r.score })); }向量存储我用的是分块策略。每个Float32Array预分配1024乘512个元素，也就是512张图的容量。新向量先追加到当前块，块满就新建。这样可以避免每加一张图就整体resize一次大数组，也方便检索时连续内存访问。
IndexedDB的存储逻辑我简化一下，核心就是用事务批量写入。搜索函数返回的是TopK相似项，UI层拿到之后从IndexedDB里取缩略图显示。
这里有一个值得注意的地方：queryVec在检索前一定要确保是L2归一化过的。训练好的模型输出已经归一化过了，但如果你从IndexedDB里读出来的向量是旧版本没归一化的数据，检索结果会直接崩掉。我的做法是在写入IndexedDB之前强制做一次归一化检查，模长偏离1超过千分之一的就重新归一化再写。
4.4 实测性能参考
我在MacBook Air M1上做了一组测试，浏览器是Chrome稳定版，后端WASM。
单张图片从读取到返回向量，大约需要80到120毫秒，其中模型推理占大头。如果用WebGL后端，可以压到40到60毫秒，但WebGL在M1上偶尔会出现精度抖动，同一个模型同一张图两次推理的向量余弦相似度只有0.9992，看起来微不足道，但在相似度阈值0.995附近会造成误判。所以我生产环境一直用WASM。
批量入库1万张图片，平均每张耗时110毫秒，加上IndexedDB批量写入，总计约15分钟。这个速度对于本地工具完全够用。
检索性能方面，1万条向量暴力遍历约35毫秒，排序约20毫秒，总计约55毫秒。如果改用TensorFlow.js张量矩阵乘法，MatMul本身只要1.8毫秒，但向量从内存拷贝到张量的时间要8到10毫秒，所以整体也就快一倍左右。日常交互场景，50毫秒和5毫秒的差别其实不容易感知，所以我一直用纯JavaScript遍历，代码更可维护。
5. 高频踩坑指南
这段内容是我花最多时间整理的部分，每一个坑都是真实报错现场。
5.1 模型加载与Worker初始化的顺序问题
最大的坑就是Worker里TensorFlow.js的初始化顺序。很多人习惯在主线程加载tfjs，然后new Worker直接在里面用tf，结果报错“tf is not defined”。原因很简单，importScripts加载的脚本和主线程的import是两个完全独立的东西，Worker里必须自己加载一份。
另一个问题是后端初始化顺序。如果直接在onmessage里调用model.predict，而model还没加载完成，predict会静默返回undefine或者抛异常。我的做法是：启动Worker后立刻发一个init消息，Worker内部await ensureInit完成后再通知主线程ready。主线程收到ready之前，不要发任何extract任务。这个流程既保证初始化唯一，也避免并发创建模型实例。
5.2 WASM二进制路径与后端切换
WASM后端的二进制文件需要单独从CDN下载，默认路径指向CDN。如果你想做离线应用，必须手动指定本地路径。我用的是setWasmPaths：
tf.wasm.setWasmPaths('/vendor/wasm/');这里要特别注意：目录下需要包含tfjs-backend-wasm.wasm和tfjs-backend-wasm-simd.wasm两个文件。版本必须和tfjs主库版本严格对应，混版本会导致wasm加载后初始化失败，报错信息又不明确。
切换后端时还有个经典问题：WebGL后端初始化失败后，tfjs会自动回退到CPU后端，CPU后端的MobileNetV2推理速度慢到无法接受（单张可能要2到3秒）。回退不会报错，只有通过tf.getBackend()主动检查才能发现。所以初始化完成后，务必加一行断言：
if (tf.getBackend() !== 'wasm' && tf.getBackend() !== 'webgl') { throw new Error('后端初始化失败: ' + tf.getBackend()); }5.3 Service Worker 注册失败：could not register service worker: invalidstatee
如果你的项目里同时用了Service Worker做离线缓存，很可能遇到这条报错。这个错误的字面意思是“注册时上下文状态无效”，最常见的触发场景有几种。
第一，页面没有运行在安全上下文里。Service Worker要求HTTPS协议，localhost是例外。你用file://协议直接打开页面，Service Worker注册必然失败，但Web Worker正常。第二，WebView环境不完全支持Service Worker，比如某些App的内置浏览器。第三，重复注册相同作用域的Service Worker，路径不一致但作用域重叠，旧的注册状态还没清理完。第四，在页面加载初期、文档状态还没稳定时就调用了register，某些浏览器会直接抛这个错。
排查方法是：先用navigator.serviceWorker.getRegistration()确认当前作用域已有注册；注册调用务必加.catch处理并打日志；开发阶段用localhost访问，部署阶段确保HTTPS；如果只是做离线缓存，也可以用不用Service Worker，直接用浏览器的HTTP缓存配合IndexedDB就够了。
5.4 图片解码兼容性与EXIF方向
createImageBitmap并不是万能的。你从手机里导出的HEIC格式图片，Chrome桌面版可能解不出来；某些截图工具生成的PNG带透明通道，直接喂给tf.browser.fromPixels会出现四通道，张量形状变成（高, 宽, 4），模型的输入通道是3，直接报错。
还有一个隐藏很深的坑是EXIF方向。有些手机相机拍出来的JPEG，像素数据本身是旋转前的，EXIF字段里存着旋转方向信息。createImageBitmap在大多数现代浏览器里会自动应用EXIF方向，但如果你做批量文件读取时用FileReader读ArrayBuffer再手动解码，EXIF方向就会被忽略，导致所有竖拍照片的检索特征偏转90度，相似度检索效果大打折扣。
我的规避方案是：统一用createImageBitmap处理文件对象，不手动解码二进制；遇到透明通道时，先把ImageBitmap绘制到一个不透明的canvas上补白底，再转回ImageBitmap或直接转张量。
5.5 内存泄漏排查
TensorFlow.js推理最常见的问题就是内存泄漏。如果你发现页面长时间运行后越来越卡、GPU进程内存暴涨，十有八九是张量没有释放。
排查技巧是定期打印tf.memory()：
console.table(tf.memory());重点关注numTensors字段，这个数字只增不减就说明有张量泄漏。我的代码里所有推理逻辑都放在tf.tidy里，只有最终需要返回的张量在tidy外面手动dispose。IndexedDB读取大Blob时也会产生临时内存，用完要主动置空引用。
另外一个容易忽略的点是worker.onmessage里拿到的Float32Array，如果没拷贝就直接存进内存索引，等下一轮postMessage再复用时，这个ArrayBuffer可能已经被转移掉或者被后续消息覆盖。所以我在handleEmbedding里的第一件事就是new Float32Array(vec)做一份拷贝，确保后续使用安全。
6. 可以继续扩展的方向
这套端侧架构搭好之后，扩展空间其实比想象中大得多。
6.1 从图片检索到更多模态
1024维视觉向量只是起点。同样的链路完全可以扩展到文本embedding、音频embedding。只要模型能跑在TensorFlow.js里，特征能归一化成固定维度向量，就能复用这套Web Worker推理加本地索引的方案。
比如你可以把文档标题和摘要跑一个文本embedding模型，然后把文本向量和图片向量放在同一个向量空间里，实现跨模态检索。用户在搜索框输入一句描述，得到一个文本向量，去和图片向量的索引算相似度，就实现了“以文搜图”。这套逻辑不需要任何服务端组件，对本地知识库工具特别合适。
6.2 模型量化与WebGPU加速
模型量化方面，我建议优先尝试uint8量化。MobileNetV2这类模型对量化非常鲁棒，14MB压到4MB，加载速度快三倍，推理速度在WASM后端还能提升20%到30%，精度损失在检索场景下几乎可以忽略。
WebGPU后端越来越成熟。Chrome已经默认支持，TensorFlow.js的WebGPU后端在MobileNetV2上的推理延迟能压到10毫秒以内。唯一需要注意的是WebGPU和WebGL不能同时在一个页面初始化，切换后端前要重新加载模型缓存。等WebGPU兼容性再稳一点，我大概率会把生产环境切过去，尤其是移动端。
6.3 最后一点个人体会
做这套方案之前，我总默认“AI能力=云端API”，直到被隐私需求逼着把整个推理链路搬进浏览器，才发现端侧的空间比想象中大。TensorFlow.js的模型和性能已经不是瓶颈，Web Worker解决了卡顿问题，IndexedDB解决了持久化问题，这三件套组合在一起，就是一个完整的端侧AI基础设施。
我个人实际使用中最大的感受是：端侧方案的精髓不只是省成本，而是让你敢处理那些“不能上传”的数据。很多需求过去因为隐私合规原因只能搁置，现在可以直接在浏览器里做。如果你手头也有类似的需求——本地图片去重、私人相册搜索、离线素材管理——照着这条链路搭一套，踩坑的部分我已经替你趟完了。这套方案后续还可以继续扩展，比如接入HNSW库做更大规模索引，或者把检索封装成一个开箱即用的Web组件，留给真正需要的人。
