在 Transformers.js 中实验跨源存储 API

Cross‑Origin Storage（COS）API 允许 Web 应用通过加密哈希而非 URL 来存储和检索大文件，使不同来源能够共享缓存资源，而不会被浏览器的来源分区缓存阻止命中。通过在 Transformers.js 中启用实验性标志，开发者可以避免在每个站点上重新下载相同的模型权重和 Wasm 运行时，从而节省带宽和存储空间。

Transformers.js 中的缓存隔离问题

浏览器通过来源对 HTTP 缓存进行隔离，以防止时序攻击，因此从不同站点获取的相同资源会被分别存储。在 Transformers.js 示例中，访问 https://googlechrome.github.io 上的 ASR 示例会缓存 Whisper 模型（约 177 MB）和 ONNX Runtime Wasm 文件（约 4,733 kB）。从另一个来源（例如 https://rawcdn.rawgit.net）加载相同的示例时，浏览器会再次下载并缓存这些资源，即使字节完全相同。

跨源存储 API 如何解决该问题

COS 引入了 navigator.crossOriginStorage，它通过哈希（例如 SHA‑256）而非 URL 来标识文件。当站点按哈希请求文件时，如果存储中已有该哈希，API 会返回一个 FileSystemFileHandle；否则会回退到网络并将文件写入 COS 以供后续使用。由于键是哈希，任何之前存储了相同字节的来源都能命中缓存，从而消除重复下载。

在 Transformers.js 中集成 COS

Transformers.js 提供了一个可选的后端，当标志 env.experimental_useCrossOriginStorage 设置为 true 时使用 COS。库会从 Hugging Face Hub 上存储的原始指针计算每个 Xet 跟踪的模型文件（例如 ONNX 权重文件）的 SHA‑256 哈希，并将该哈希传递给 navigator.crossOriginStorage.requestFileHandle。如果文件已存在于 COS 中，则会立即读取；否则会下载并存储，以供下一个调用者使用。启用该功能只需在首次 pipeline 调用前添加一行代码：

import { env, pipeline } from "https://cdn.jsdelivr.net/npm/@huggingface/transformers@4.2.0\); // 👇 Opt in to the experimental Cross‑Origin Storage cache backend.
env.experimental_useCrossOriginStorage = true;
const asr = await pipeline('automatic-speech-recognition', 'Xenova/whisper-tiny.en', { device: 'webgpu' });
const result = await asr('jfk.wav');
console.log(result);

控制可见性和完整性

通过 COS 存储文件时，开发者可以指定 origins 选项：

• origins: '*' 使资源全局可用，适用于共享的模型权重或 Wasm 运行时。
• 类似 origins: ['https://write.example.com', 'https://calculate.example.com'] 的列表限制仅这些站点访问。
• 省略 origins 则将文件限制在同站点来源。 可见性只能提升（例如从受限提升为全局），且永不降低，这可防止恶意站点缩小公共资源的受众。API 还在写入时验证提供的数据与声明的哈希是否匹配；不匹配会抛出错误，从而实现自动完整性检查，无需额外代码。

隐私考虑

由于任何站点都可以通过哈希探测文件，COS 引入了可用性门控：浏览器可能会隐藏仅在少数来源出现的文件，以防止指纹识别。因此，requestFileHandle 返回的错误并不一定意味着文件不存在；它可能表明浏览器正在隐藏确认信息。应用应将该错误视为缓存未命中，并回退到网络请求。

试用指南

要立即进行实验，请从 Chrome 网上应用店安装 Cross‑Origin Storage 扩展，该扩展会为 navigator.crossOriginStorage 注入一个 polyfill。启用扩展后，打开启用了 COS 的 ASR 示例页面 https://googlechrome.github.io/samples/transformersjs-automatic-speech-recognition/index3.html，让其加载 Whisper 模型，然后从另一个来源打开相同的示例（https://rawcdn.rawgit.net/GoogleChrome/samples/1e4f2b8c10adc394352c6ec8327bb503bac7aba1/transformersjs-automatic-speech-recognition/index3.html）。在没有 COS 时需要重新下载的 177 MB 文件，此时模型会在毫秒级从 COS 提供。扩展的弹出窗口会显示通过 SHA‑256 哈希标识的共享资源以及拥有该资源的两个来源。

行动号召

如果你正在构建 Transformers.js 应用，请在首次 pipeline() 调用前添加 env.experimental_useCrossOriginStorage = true，安装 COS 扩展，并确认网络面板中不再出现重复下载。每个选择加入的站点都会让所有其他站点的用户体验更快、更省流量。此选项无需风险：如果 COS API 不可用（未安装扩展），代码会回退到默认的 Cache API。关于该 API 的反馈可通过 GitHub 上的 Cross‑Origin Storage 仓库提交，Chrome 团队也在考虑实现原生支持。