本地目录里有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数据库适合存储结构化数据和二进制数据。我把每个向量作为一条记录字段包含vectorFloat32Array、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_formattf_saved_model \ --output_formattfjs_graph_model \ --signature_nameserving_default \ --quantization_bytes1 \ ./saved_model \ ./public/models/embedding--quantization_bytes1表示把权重量化成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。如果你想做离线应用必须手动指定本地路径。我用的是setWasmPathstf.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组件留给真正需要的人。