先交代一下场景。我前段时间接了个内部工具的活：要在浏览器里管理上万张本地图片，用户可以框选一张目标图，系统自动找出所有"看起来差不多"的图片——类似以图搜图，但有一个硬性前提：这些照片属于用户隐私数据，一张都不能上传到服务器。我最初也想过成熟的云方案：图片传对象存储，调一次视觉 Embedding API 拿到向量，再丢进向量数据库做相似检索。算完账我就放弃了。后来我把整条链路搬到端上：TensorFlow.js 加载视觉模型、Web Worker 里跑推理和检索、IndexedDB 存 1024 维浮点向量，整套流程下来项目里没写一个上传接口。本文就把这套端侧视觉向量检索架构的选型逻辑、完整实现和实测数据写清楚，适合正在做图片搜索、本地相册、敏感素材库这类功能的前端和全栈开发者参考。
1. 先算一笔账：为什么"图片不上云"值得专门做一套架构
1.1 云端的真实开销：不只是 GPU 推理费
很多人以为调一次视觉模型 API 只要几分钱，量大了再说。但真实业务里，成本是按"全链路"叠加的：图片要传对象存储，算存储费；建库时每张图调用一次 Embedding 接口，算推理费；向量进了云数据库，按容量和 QPS 计费；用户反复导入、删除、重建索引，每一轮都在烧钱。我做了一个很粗略的估算：一万张图建库，加上一年内大约三百个用户的增量导入，仅向量相关的云端成本就在每月大几百到上千元量级。单个用户看不多，乘上用户规模就完全不是一个数量级了。
而且这还没算"重复计算"的浪费。同一个用户导入同一批图片，云端没法复用上一轮的结果，只能重新抽特征。端侧方案里这些开销全部消失：模型权重是公开的静态资源，从 CDN 拉一次可以缓存；特征提取用的是用户自己设备的 CPU/GPU；向量库存在用户自己的浏览器里。业务方需要付的钱，从头到尾只有静态资源的带宽，甚至这一步也可以省——把模型打进安装包/离线包，就真的零成本了。
1.2 隐私合规成本：比你想的更贵
图片属于高度敏感的个人数据，尤其是当检索目标涉及人物、证件、室内环境时，处理链条上的每个环节都可能被监管和审计盯上。云端方案里，图片上传、存储、模型调用、向量落库，每一步都可能引发数据保护义务：存储期限、删除机制、访问审计、事故通报。这些在架构评审里都是实打实的时间成本和法务成本。
端侧方案最省心的地方在于：数据不出设备，架构上就没有"用户照片流转到服务端"这件事。你不需要为图片设计云端删除机制，不需要担心训练数据被复用，不需要处理"用户要求彻底删除"时的跨系统级联清理。我个人的体会是，当隐私保护由架构本身保证时，产品反而敢做很多原本不敢做的功能——比如在本地相册里直接做人物聚类、场景识别，这些功能如果走云端，光评审可能就要好几轮。
1.3 端侧方案的边界：它适合什么场景
当然，端侧不是银弹。这套方案最适合的是"单用户本地数据规模在数千到数万张"的场景：个人相册、本地知识库、离线素材管理、企业内部敏感资料检索。它不适合需要多人共享同一份索引的场景，也不适合数据规模达到百万级、需要全局实时更新的场景——这些依然是云向量数据库的主场。
另外要提醒一句：这里说的"0 云端成本"，指的是用户图片的处理、存储、检索都不经过云端推理和云数据库。模型权重文件本身仍然需要一次获取，可以是 CDN 也可以是应用自带。这部分是一次性的公开静态资源，不产生按量推理费，但如果你追求字面意义的"完全离线"，记得把模型一并打包。
2. 选型依据：TensorFlow.js 和 Web Worker 是如何配合的
2.1 为什么是 TensorFlow.js 而不是其他推理框架
浏览器端跑模型的选项其实不少：ONNX Runtime Web、WebGPU 原生推理、TensorFlow.js，我都试过。ONNX Runtime Web 的优势是模型生态广，PyTorch 导出的 ONNX 基本都能转，但它在浏览器里的算子兼容性要逐个踩，遇到不支持的算子就得改模型结构，调试成本偏高。WebGPU 的推理性能确实惊艳，但浏览器支持还没到可以无脑用的程度，而且写算子优化的门槛对业务团队不友好。
TensorFlow.js 胜在生态成熟和调试成本低：Keras/TF Hub 上的模型基本可以直接加载，后端抽象做得不错——同一份代码可以跑 WebGL、WASM 或纯 CPU，运行时切换后端只需要一行tf.setBackend()。对业务型项目来说，稳定跑通比极致性能重要得多，这也是我最终选它的核心原因。它牺牲的那点性能，实际场景里完全可以通过"在 Worker 里异步跑"来弥补。
2.2 Web Worker 真正的价值：主线程不卡，才能谈体验
TensorFlow.js 推理本身不算慢，但它有个致命问题：模型加载、张量创建、WebGL 上下文初始化都会把主线程卡住。图片加载本身已经占用了大量主线程时间，再叠加模型推理，页面直接进入"假死"状态。用户滑动相册的时候卡住两秒，这个产品就废了。
Web Worker 在这里解决的其实不是"性能"，而是"主线程可用性"。把推理放进独立线程，UI 线程只负责接收 ImageBitmap 和展示结果。这里有一个容易忽略的细节：TensorFlow.js 的 WebGL 后端在 Worker 里跑，需要借助 OffscreenCanvas 创建独立的 WebGL 上下文，代码上要先用canvas.transferControlToOffscreen()把画布控制权转给 Worker；如果不想要这个复杂度，WASM 后端在 Worker 里是直接可以跑的，稳定性更好。我的做法是：桌面端用 WebGL，移动端兜底用 WASM，避免 Safari 上 OffscreenCanvas 的各种兼容问题。
2.3 1024 维向量：模型输出层的取舍逻辑
向量维度直接决定检索精度和资源占用的平衡。128 维、256 维的向量对人脸这种高度结构化的任务够用，但对"场景相似""物体相似"这种开放视觉任务，信息容量明显偏紧；2048 维以上区分度更高，但每一条向量占 8KB 内存，一万条就是 80MB，移动端会很难受。1024 维是当前很多开源视觉表征模型默认的输出维度，也被大量应用在知识图谱实体向量、多模态检索空间里，属于"够用且不贵"的甜点位。
需要注意，并不是所有模型都刚好输出 1024 维。比如 MobileNetV2 的最后一个卷积层输出 1280 维，ResNet 系列常见 2048 维。我的做法是在导出模型时固定加一个 Dense(1024) 层，再接 L2 Normalization，把任何模型的输出统一到 1024 维单位向量。这一步很关键：归一化之后，余弦相似度就等价于点积，检索时能省掉大量开方运算。另外，维度统一也方便后续把文本向量、知识图谱实体向量放进同一个向量空间做多模态检索，这个我们后面还会提到。
3. 动手实现：从原始图片到可检索的向量库
3.1 特征提取 Worker 的完整实现
先看核心的 Worker 代码。我用importScripts加载 TensorFlow.js，然后初始化后端，再加载模型。注意postMessage传结果时把Float32Array的底层 buffer 一并 transfer 出去，避免主线程再复制一份 4KB 的数据。
// feature-worker.js importScripts('https://cdn.jsdelivr.net/npm/@tensorflow/tfjs@4.17.0'); let model = null; tf.setBackend('webgl') .then(() => tf.ready()) .then(() => postMessage({ type: 'backend-ready' })); self.onmessage = async (e) => { const { type, payload } = e.data; if (type === 'init') { model = await tf.loadLayersModel(payload.modelUrl); // 预热一次，避免第一次推理时 WebGL 编译着色器卡顿明显 const dummy = tf.zeros([1, 224, 224, 3]); model.predict(dummy); dummy.dispose(); postMessage({ type: 'ready' }); } if (type === 'extract') { const vec = await extractFeature(payload.imageBitmap); postMessage({ type: 'result', id: payload.id, vec }, [vec.buffer]); } }; function extractFeature(imageBitmap) { return tf.tidy(() => { const tensor = tf.browser .fromPixels(imageBitmap) .resizeBilinear([224, 224]) .div(255) .expandDims(0); const feature = model.predict(tensor).squeeze(); // L2 归一化，让检索阶段直接用点积 const normalized = feature.div(tf.norm(feature)); return normalized.dataSync(); }); }主线程这边，用createImageBitmap把文件解码成位图，然后直接 transfer 给 Worker，渲染线程完全不碰像素数据：
// main.js const worker = new Worker('feature-worker.js'); async function sendToWorker(file, fileId) { const bitmap = await createImageBitmap(file); worker.postMessage( { type: 'extract', payload: { id: fileId, imageBitmap: bitmap } }, [bitmap] ); }这里有个经验：dataSync()会在 Worker 内阻塞等待结果，这是刻意为之——阻塞的是 Worker 线程而不是主线程，换来代码同步书写的简洁性，在业务代码里完全可接受。
3.2 建库流程与 IndexedDB 持久化
建库的本质就是"遍历图片 → 提取特征 → 持久化"。我推荐用一个批次任务队列控制并发，不要一次性把所有图片砸给 Worker。原因有两个：一是解码大量 ImageBitmap 会瞬间吃掉很多内存；二是 WebGL context 处理过多并发请求容易触发浏览器回收。我的队列实现是每个批次 4 张，处理完一批再进下一批。
持久化我用 IndexedDB，封装层用了idb-keyval，代码可以很短：
import { set, get, update } from 'https://cdn.jsdelivr.net/npm/idb-keyval@6.5.0/+esm'; async function saveVector(fileId, vec) { await set(`vec_${fileId}`, vec); // vec 是 Float32Array，IndexedDB 原生支持 } async function saveMeta(fileId, meta) { await set(`meta_${fileId}`, meta); } async function loadAllVectors() { const keys = await get('all_ids') ?? []; const vecs = await Promise.all(keys.map((id) => get(`vec_${id}`))); return { ids: keys, vecs }; }存储层面有个取舍：每个向量单独存一条记录，更新灵活，但读取时Promise.all会建立大量连接，万条数据可能要几百毫秒；如果是一次性全量加载，更快的做法是拼成一个大二进制块整体写入，读取时直接切分。我的建议是：相册达到两万张以上就拼块存储，一条记录放全部向量的二进制数据，读取一次搞定，实测加载时间能缩短一半以上。
3.3 检索端的余弦相似度与 Top-K 实现
由于存储前已经做了 L2 归一化，检索阶段只需要算点积，然后取 Top-K。直接写一个朴素循环，对一万条向量来说完全够用：
function searchTopK(queryVec, ids, vecs, k = 10) { // queryVec 是 Float32Array(1024)，vecs 是二维结构，每条也是 Float32Array(1024) const n = ids.length; const scores = new Float32Array(n); for (let i = 0; i < n; i++) { const v = vecs[i]; let dot = 0; for (let j = 0; j < 1024; j++) { dot += queryVec[j] * v[j]; } scores[i] = dot; } // 取 Top-K，数据量不大时直接排序后切片即可 const idx = Array.from({ length: n }, (_, i) => i); idx.sort((a, b) => scores[b] - scores[a]); return idx.slice(0, k).map((i) => ({ id: ids[i], score: scores[i] })); }这个循环对 5 万条 1024 维向量要做约 5 千万次浮点乘加，JavaScript 里实测大概 30 到 80 毫秒。如果你的目标是十万条以上，建议用Float32Array展开成连续内存块，配合Math.fround或者干脆编译一个小 WASM 模块来做矩阵乘，性能会再提一个量级。但在此之前，先问自己一个问题：浏览器里管理超过十万张本地图片，是不是应该考虑桌面端原生应用了？这个边界我们后面细说。
4. 实测数据与内存、兼容性的坑
4.1 三个环节的耗时：模型加载、特征提取与检索
我在两台设备上做了实测：一台是 MacBook Pro（M1 芯片，Chrome 112），一台是 Pixel 6（Android Chrome，WASM 后端）。模型用的是 MobileNetV2 结构、输入 224×224、输出 1024 维。
| 阶段 | 桌面端（WebGL） | 移动端（WASM） |
|---|---|---|
| 首次模型加载（含权重拉取） | 约 1.5 秒（本地静态资源） | 约 3 秒（本地静态资源） |
| 单张图片特征提取 | 40~80 毫秒 | 300~600 毫秒 |
| 建库 5000 张图（队列并发 4） | 约 5 分钟 | 约 25 分钟 |
| 检索 Top-10（5 万条向量） | 约 30 毫秒 | 约 80 毫秒 |
这份数据仅供参考，但它说明几件事：检索本身根本不是瓶颈，瓶颈全在特征提取；移动端 WASM 提取 5000 张图需要二十多分钟，所以产品上必须设计"后台持续建库"的交互，不能让用户干等；模型首次加载的延迟可以用进度条和预热来掩盖，预热那一次推理虽然慢，但能避免后续每张图都触发着色器编译。
4.2 Web Worker 里的张量泄漏问题
这是我这次踩得最深的坑。TensorFlow.js 的tf.tidy()只能管理函数内创建的 tensor，但dataSync()返回的是普通Float32Array，不归 tidy 管，它由 JavaScript 引擎正常 GC。真正的问题出在 WebGL backend：如果你在predict之后忘记dispose()输入张量，GPU 显存会被持续占用，最终 WebGL context 直接丢失，后续所有推理全部报错。
实测表现很典型：处理 5000 张图，如果每个循环里漏掉一个dispose()，Chrome 的 GPU 内存曲线会一路爬升，在三千张左右突然崩掉，报错是CONTEXT_LOST_WEBGL。修法有两个层面：代码层面统一用tf.engine().startScope()/endScope()包住推理逻辑，scope 结束自动释放内部张量；架构层面控制并发，两三个 Worker 同时跑 WebGL 推理也会加速 context 丢失，我最后只保留了单个 Worker 处理特征提取。
还有一个隐蔽的内存问题：postMessage传ImageBitmap时，如果忘了把 bitmap 放进 transfer list，主线程和 Worker 会各持一份像素数据。我的主线程代码里专门写了[bitmap]这个参数，就是为了避免重复占内存。
4.3 移动端 Safari 的兼容性细节
Safari 是这套方案里最磨人的一环。iPhone 相册导出的照片大量是 HEIC 格式，createImageBitmap在部分 Safari 版本上对 HEIC 解码支持时好时坏，表现在代码里就是文件能选、位图解不出来。我的兼容策略是：文件选择阶段统一用 Canvas 转成 JPEG 再交给 Worker，虽然多一步解码，但格式统一之后后面所有逻辑都省心。
另一个已知问题是 OffscreenCanvas 在 Safari 的支持不如 Chrome，导致 Worker 内 WebGL 后端不稳定。我的做法是运行时探测：
const backend = isSafari ? 'wasm' : 'webgl'; await tf.setBackend(backend); await tf.ready();WASM 后端在移动端的单张推理虽然慢一点，但胜在稳定，对相册检索这种非实时场景完全够用。最后提醒一点：从 CDN 加载模型权重时，model.json和分片的.bin文件都必须配置正确的 CORS 响应头，否则在跨域 Worker 里会直接加载失败，而且报错信息很含糊，排查起来特别费时间。
5. 这套方案的真实边界与后续演进
5.1 "100% 隐私"这句话要打什么折扣
标题里写"100% 隐私安全"，技术层面指的是用户图片和特征向量全程不出设备，模型权重是公开数据，从 CDN 拉取不涉及用户隐私。但我要提醒做产品的人：这种声明必须是整包行为，不能只看功能链路。如果页面里还挂了统计埋点、错误上报、远程配置 SDK，那"隐私"的边界就要重新界定。用户照片不出设备，不等于用户行为数据不出设备。
我的做法是把统计最小化，只在应用内做本地日志，不上报任何图片相关的元信息。这样无论从产品宣传还是从后续审计角度看，说"图片不上云"都是经得起推敲的。给同样在做这类工具的同学一个建议：不要在功能做完了才补隐私声明，架构评审阶段就把"什么数据碰都不能碰"划清楚。
5.2 规模上限：什么时候该从端侧迁移
端侧的硬上限来自三个地方：IndexedDB 配额、内存占用、检索延迟。单条 1024 维 Float32 向量占 4KB，十万条就是 400MB，再加缩略图缓存，移动端浏览器很容易触发存储压力。内存里全量加载十万条向量也是 400MB，桌面端还好，手机上就非常紧张了。
所以在千万级向量之前就必须做两件事：一是量化，把 Float32 压到 int8，每条向量降到 1KB，十万条才 100MB；二是索引化，从暴力搜索升级到 HNSW 或 IVF。WebAssembly 社区已经有可用的 HNSW 实现，配合 int8 量化，浏览器里支持百万级向量检索是可行的。但如果目标是千万级以上，我建议老实迁移到服务端，别跟浏览器较劲。端侧方案最合适的定位就是"个人级、相册级"数据规模，想清楚这个边界，架构才不会一开始就选错。
5.3 可以继续做的优化：多模态统一空间与增量更新
1024 维这个维度还有一个隐藏优势：它可以和文本向量、知识图谱实体向量放到同一个向量空间。很多开源多模态模型的文本端和图像端都对齐到同一个空间，这样"用户拍一张照片、搜到包含同款物体的历史截图、再跳转到对应的文本记录"这类跨模态检索就能直接实现。我在这个项目里下一步计划就是把本地笔记的关键词向量也灌进去，做一个本地私有的多模态知识检索工具。
增量更新方面，架构天然支持：新图片只需要走一遍提取流程，追加存储，不需要重建已有索引，检索时把新向量并入内存数组即可。删图也一样，从 IndexedDB 删除记录、从内存数组移除对应下标。这些在云端往往涉及批量任务，在端侧都是毫秒级操作。
最后说个实在的：这套架构我前后跑了大半个月，最耗时间的不是模型选型也不是检索逻辑，而是内存曲线和 Safari 兼容性。如果让我重来一遍，第一件事就会把"图片格式统一转换 + Worker 内 WASM 兜底"这个组合提前定下来。端侧 AI 的技术栈看着热闹，真正决定方案能不能落地的，往往不是性能数字，而是边界条件有没有从一开始划清楚：数据规模多大、目标浏览器是哪几个、隐私承诺到底到什么程度。把这几个问题想透，TensorFlow.js、Web Worker、1024 维向量这些工具才会真正变成你的武器，而不是你被它们拖着走。
