浏览器 AI 抠图:模型 CDN 回退与 Cache 缓存
抠图库明明是通过 npm 安装的,第一次打开却还是卡在“加载模型”。原因是 npm 包里只有 JavaScript 和 WASM 胶水代码,真正的模型数据要另外下载,体积在百兆级;CDN 不可达、数据前缀写错或缓存没命中,都会让页面停在进度条上。
先给结论
浏览器抠图的模型分发可以拆成四件事:
- 库本地、数据远程:
@imgly/background-removal走 npm,模型与 WASM 数据默认从staticimgly.com下载; - 三级回退:官方 CDN → 自定义 CDN → 本站
public/imgly-data/,只在下载阶段失败时切换; - base 必须绝对:库内部用
new URL(name, publicPath)拼地址,/imgly-data/这样的相对前缀会直接抛Invalid URL; - 缓存按完整 URL:Cache API 以分片 URL 为键,不同数据源的缓存各自独立,换 CDN 不会错误复用。
可以直接打开 去除图片背景工具 观察首次加载与二次打开的区别。
模型为什么不在 npm 包里
@imgly/background-removal 1.7.0 的默认数据源是:
https://staticimgly.com/@imgly/background-removal-data/1.7.0/dist/
门户源码注释记录了数据体积:完整数据 328MB,按需拷贝 fp16 模型与 WASM 后,本站 public/imgly-data/ 约 118MB。把这么大的二进制塞进 npm 包,会让安装、构建和发布都变得不可控,所以库选择“代码走 npm、数据走 CDN”。
这也决定了隐私边界:图片全程在本机推理,不会上传;但首次使用需要下载模型。页面上写“纯本地处理”并不矛盾,下载的是模型,不是用户图片。
模型固定为 isnet_fp16。源码注释给的理由是与参考实现保持一致的精度/速度平衡;换模型会改变数据文件与缓存键,不能只改一个字符串。
三级数据源与配置入口
数据源按固定顺序排列,前一个不可用才尝试下一个:
function buildSources(): ImglySource[] {
const sources: ImglySource[] = [{ dataBase: OFFICIAL_DATA_PREFIX }]
if (configuredBase) {
const remote = normalizeBase(configuredBase)
sources.push({ dataBase: remote, publicPath: remote })
}
sources.push({ dataBase: localBase(), publicPath: localBase() })
return sources
}
三段分别是:
| 顺序 | 数据源 | 配置方式 | 适用场景 |
|---|---|---|---|
| 1 | 官方 CDN | 不传 publicPath,用库内置默认值 | 默认,版本随包自洽 |
| 2 | 自定义 CDN | NUXT_PUBLIC_IMGLY_BASE 或 setImglyBase | 官方源慢、需要走自有 OSS |
| 3 | 本站 public | /imgly-data/ | 内网、离线部署、CDN 全部不可用 |
自定义前缀的目录结构必须与官方一致:resources.json 加内容哈希分片平铺在同一层,并且配置 CORS。只改前缀、不改目录结构,库找不到 resources.json,同样会在下载阶段失败。
app/plugins/api-config.ts 在客户端启动时把运行时配置写进工具函数:
setImglyBase(String(config.public.imglyBase || ''))
所以切换 CDN 不需要改代码,部署时给一个环境变量即可。
绝对 base 的必要性
normalizeBase 的职责是把用户写的各种前缀统一成绝对 URL,并确保以 / 结尾:
function normalizeBase(base: string): string {
let b = base.trim()
if (b.startsWith('/')) {
b = window.location.origin + b
} else if (!/^https?:\/\//i.test(b)) {
b = `${window.location.origin}/${b}`
}
return b.endsWith('/') ? b : `${b}/`
}
不这么做会怎样?库在解析资源名时用的是 new URL(name, publicPath)。第二个参数如果是相对路径,浏览器会直接报错:
new URL('resources.json', '/imgly-data/')
TypeError: Invalid URL
new URL('resources.json', 'http://localhost:3001/imgly-data/')
http://localhost:3001/imgly-data/resources.json
这个错误发生在库内部,页面只能看到“加载失败”,很难从堆栈反推到 publicPath。凡是把静态资源目录传给第三方库,都要先确认它期望的是目录 URL 还是可解析的绝对 base。
回退边界:只在下载阶段
三级数据源不是“任何失败都重试”。判断条件在 runWithSourceFallback 里:
try {
const result = await withResourceCache(source.dataBase, () =>
run(source.publicPath, bridge.onLibProgress)
)
bridge.done()
return result
} catch (err) {
if (bridge.enteredProcess || i === sources.length - 1) {
throw err
}
// 下载阶段失败,落到下一个数据源
}
enteredProcess 在收到第一个 compute:* 事件时置为 true。含义是:模型数据已经下载完,进入推理阶段;此时失败与数据源无关,换源只会重复下载再失败。下载阶段失败(404、CORS、网络中断)才继续尝试下一个源。
这个区分很重要。把所有异常都当成“换源重试”,会让一个推理错误在三个源上各跑一遍,用户等待时间成倍增加,最后拿到的还是同一个错误。
进度也只有两类事件:
fetch:<key>:资源下载,按已下载字节汇总到 2%–55%;compute:*:解码、推理阶段,收到后从 60% 开始缓慢推进到 88%。
推理期间库长时间不发事件,所以源码用定时器做缓动,越接近 88% 走得越慢,完成时直接置 100%。进度只增不减,避免多个分片并行时数字来回跳。这个“假进度”不是伪造结果,而是让用户知道页面还活着;真正的完成信号仍然是 Promise resolve。
Cache API 垫片
本站 public 与自建 OSS 的静态文件通常没有强缓存头,二次打开仍会重新下载。门户在调用库期间临时替换全局 fetch:
const cache = await caches.open(`imgly-data-${MODEL}`)
const hit = await cache.match(url)
if (hit) return hit
const resp = await origFetch(input, init)
if (resp.ok) {
await cache.put(url, resp.clone())
}
return resp
几个实现细节:
- 只拦截
url.startsWith(base)的请求,页面其他接口不受影响; - 缓存键是完整 URL,官方源、自定义源、本站源的同一分片各自一份,不会串源;
resp.clone()一份交给调用方、一份写入缓存,避免响应体被读两次;- 用
fetchShimDepth计数,嵌套调用时只在最外层替换与还原,finally保证异常也能恢复; - 缓存名带模型名,换模型不会读到旧数据。
在已经打开过抠图页的浏览器里,可以验证缓存确实写入了:
const keys = await caches.keys()
// ["imgly-data-isnet_fp16"]
const cache = await caches.open('imgly-data-isnet_fp16')
const entries = await cache.keys()
// 第一条为 https://staticimgly.com/@imgly/background-removal-data/1.7.0/dist/resources.json
这只能证明垫片命中了官方源并写入清单;分片会按同样逻辑逐个写入。是否全部缓存成功,取决于网络是否在下载过程中中断。
一个现实边界:如果浏览器禁用了 Cache Storage(部分无痕模式、存储被策略关闭),caches.open 会抛错,当前垫片没有降级为“直接 fetch”,三级源都会失败。要兼容这种环境,需要在外层捕获存储错误,再以不缓存的模式调用库。另一个成本是配额:118MB 模型会占用站点存储,浏览器在磁盘紧张时可能清理,二次打开不一定百分百命中。
预加载、文件校验与隐私
页面在空闲时预加载模型:
const idle = (window as any).requestIdleCallback
if (typeof idle === 'function') {
idle(() => { preloadCutoutModel() }, { timeout: 5000 })
} else {
setTimeout(() => { preloadCutoutModel() }, 2500)
}
预加载失败会被静默吞掉,等用户真正点“开始抠图”时再重试并给出错误。这样首屏不会被百兆下载阻塞,用户上传图片的交互也先可用。
文件校验只做两件事:类型必须以 image/ 开头,大小不超过 50MB。源图和结果都用 URL.createObjectURL 展示,替换图片、组件卸载时都会 revokeObjectURL,避免 Blob 一直占内存。需要把图片转成文本嵌入时,可以再用 图片转 Base64 工具;需要纯色占位图时用 占位图工具。
验证清单
| 场景 | 预期 |
|---|---|
| 首次打开,官方 CDN 可用 | 从 staticimgly.com 下载,Cache Storage 出现 imgly-data-isnet_fp16 |
| 官方 CDN 下载失败 | 自动尝试自定义源,再尝试本站 /imgly-data/ |
NUXT_PUBLIC_IMGLY_BASE 写成 /imgly-data/ | 归一化为绝对 URL 后正常工作 |
| 直接把相对 base 传给库 | 抛 TypeError: Invalid URL |
| 推理阶段报错 | 不换源,直接显示失败 |
| 断网后二次打开 | 已缓存分片命中,不再发请求 |
| 上传非图片或超过 50MB | 前端提示,不进入推理 |
FAQ
第一次抠图很慢是正常的吗?
正常。首次需要下载模型与 WASM 数据,体积在百兆级;下载完成后写入 Cache Storage,二次使用会快很多。页面在空闲时预加载,提前打开工具页可以减少等待。
图片会上传到服务器吗?
不会。图片只在本机解码和推理,网络请求仅用于下载模型数据。页面的隐私说明与实现一致。
换 CDN 后缓存会重复下载吗?
会。缓存键是完整 URL,不同源的同一分片被视为不同资源。这样避免串源,但切换前缀后需要重新缓存一次。
为什么推理失败不自动换源?
模型数据已经下载完成,推理失败通常来自图片、内存或运行时限制,换源不会改变结果,只会重复下载和等待。只有下载阶段失败才值得换源。
无痕模式能用吗?
取决于浏览器的存储策略。Cache Storage 被禁用时,当前实现会在打开缓存时失败;可以关闭缓存垫片后直接请求模型数据,但每次都要重新下载。
结语
浏览器抠图的难点不在模型调用,而在把百兆级模型可靠地送到浏览器:数据源要能回退,base 要能被 new URL 解析,缓存要按完整 URL 隔离,失败重试要分清下载与推理。把这四件事写清楚,工具才不是“网络好时能用”。更多前端实现记录在 前端开发 分类下。
Comments
No comments yet — be the first to say something