在 Transformers.js 中實驗 Cross-Origin Storage API

Cross‑Origin Storage (COS) API 允許網頁應用透過加密雜湊而非 URL 來儲存和檢索大型檔案，使得來源能在不被瀏覽器的來源分區快取阻擋命中的情況下共享快取資源。在 Transformers.js 中啟用實驗性旗標後，開發者可避免在每個網站重新下載相同的模型權重和 Wasm 執行階段，節省頻寬與儲存空間。

Transformers.js 中的快取隔離問題

瀏覽器會依據來源隔離 HTTP 快取，以防止時序攻擊，因此從不同網站取得的相同資源會被分開儲存。在 Transformers.js 示範中，於 https://googlechrome.github.io 訪問 ASR 示範會快取 Whisper 模型（約 177 MB）和 ONNX 執行階段 Wasm 檔案（約 4,733 kB）。從不同來源（例如 https://rawcdn.rawgit.net）載入同一個示範會迫使瀏覽器重新下載並快取這些資源，儘管位元組完全相同。

Cross‑Origin Storage 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。啟用擴充功能後，在 https://googlechrome.github.io/samples/transformersjs-automatic-speech-recognition/index3.html 上開啟已啟用 COS 的 ASR 示範，讓它載入 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 擴充功能，並確認在 Network 索引標籤中重複下載已消失。每個選擇加入的網站都會讓其他網站的使用者體驗變得更快速且更具成本效益。此選擇加入是無風險的：如果 COS API 無法使用（未安裝擴充功能），程式碼會回退到預設的 Cache API。對 API 的回饋可以透過 GitHub 上的 Cross‑Origin Storage 儲存庫發送，Chrome 團隊也正在考慮原生實作。