浏览器 AI 抠图:模型 CDN 回退与 Cache 缓存

2026-11-19 前端开发 有希 32 views

抠图库明明是通过 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自定义 CDNNUXT_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

Sign in to join the discussion

No comments yet — be the first to say something

Related Articles