將 Hub 從 Git LFS 遷移到 Xet

釋出於 2025 年 7 月 15 日

在 GitHub 上更新

贊

賈裡德·蘇茲多夫 (Jared Sulzdorf)

jsulz

xet-team

約瑟夫·戈德列夫斯基 (Joseph Godlewski)

jgodlewski

xet-team

山姆·霍拉達恩 (Sam Horradarn)

sirahd

xet-team

今年 1 月，Hugging Face 的 Xet 團隊部署了一個新的儲存後端，此後不久便將約 6% 的 Hub 下載流量轉移到了該基礎設施。這代表著一個重要的里程碑，但這僅僅是個開始。在 6 個月內，50 萬個儲存 20 PB 資料的儲存庫加入了 Xet 遷移，因為 Hub 已經超越了 Git LFS，並正在向一個能夠隨 AI 構建者工作負載擴充套件的儲存系統過渡。

如今，Hub 上有超過 100 萬人正在使用 Xet。5 月，它成為 Hub 上新使用者和組織預設的儲存系統。僅有幾十個 GitHub 問題、論壇帖子和 Discord 訊息，這可能是如此規模遷移中最安靜的一次。

如何做到？首先，團隊憑藉多年構建和支援內容定址儲存 (CAS) 和 Rust 客戶端的經驗做好了準備，這些構成了系統基礎。如果沒有這些部分，Git LFS 可能仍然是 Hub 的未來。然而，這次遷移的無名英雄是

內部稱為 Git LFS Bridge 的一個不可或缺的基礎設施
晝夜不停執行的後臺內容遷移

這些元件共同使我們能夠在幾天內積極遷移 PB 級資料，而無需擔心對 Hub 或社群的影響。它們讓我們安心地在未來幾周和幾個月內更快地行動（跳到文章末尾👇檢視即將發生的事情）。

橋接和向後相容性

在規劃遷移到 Xet 的早期階段，我們做了一些關鍵的設計決策：

不會從 Git LFS “硬性切換”到 Xet
支援 Xet 的儲存庫應該能夠同時包含 Xet 和 LFS 檔案
從 LFS 到 Xet 的儲存庫遷移不需要“鎖定”；也就是說，它們可以在後臺執行，而不會中斷下載或上傳

受我們對社群的承諾驅動，這些看似簡單的決策產生了重大影響。最重要的是，我們不認為使用者和團隊必須立即改變他們的工作流程或下載新客戶端才能與支援 Xet 的儲存庫互動。

如果您有支援 Xet 的客戶端（例如，hf-xet，與 huggingface_hub 的 Xet 整合），上傳和下載將透過整個 Xet 堆疊。客戶端在上傳時會使用內容定義分塊將檔案分解成塊，或者在下載時請求檔案重建資訊。上傳時，塊被傳遞到 CAS 並存儲在 S3 中。下載期間，CAS 提供客戶端從 S3 請求以在本地重建檔案所需的塊範圍。

對於不支援基於分塊的檔案傳輸的舊版本 huggingface_hub 或 huggingface.js，您仍然可以下載和上傳到 Xet 儲存庫，但這些位元組將採取不同的路徑。當透過 resolve 端點從 Hub 請求 Xet 支援的檔案時，Git LFS Bridge 會構建並返回一個單獨的預簽名 URL，模仿 LFS 協議。然後，Bridge 完成從 S3 中儲存的內容重建檔案並將其返回給請求者的工作。

Git LFS Bridge flow — Git LFS Bridge 的極大簡化檢視——實際上，此路徑包括更多的 API 呼叫和元件，例如位於 Bridge 前端的 CDN、用於檔案元資料的 DynamoDB 以及 S3 本身。

要檢視實際效果，請右鍵單擊上圖並在新選項卡中開啟它。URL 從 https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/migrating-the-hub-to-xet/bridge.png 重定向到以 https://cas-bridge.xethub.hf.co/xet-bridge-us/... 開頭的 URL。您也可以在終端中使用 curl -vL 對同一 URL 檢視重定向。

同時，當非 Xet 感知客戶端上傳檔案時，檔案首先發送到 LFS 儲存，然後遷移到 Xet。這個“後臺遷移過程”在我們文件中簡要提及，它支援向 Xet 的遷移以及上傳向後相容性。它是數十 PB 模型和資料集遷移的幕後推手，並使 500,000 個儲存庫與 Xet 儲存保持同步，所有這些都沒有中斷。

每次需要將檔案從 LFS 遷移到 Xet 時，都會觸發一個 webhook，將事件推送到分散式佇列，由協調器處理。協調器

如果事件要求，則在儲存庫上啟用 Xet
獲取儲存庫中每個 LFS 檔案的 LFS 版本列表
根據檔案大小或檔案數量將檔案分批處理為作業；以 1000 個檔案或 500MB 為準，以先達到者為準
將作業放置在另一個佇列中，供遷移工作程序 pod 處理

然後，這些遷移工作程序獲取作業，每個 pod

下載批處理中列出的 LFS 檔案
使用 xet-core 將 LFS 檔案上傳到 Xet 內容定址儲存

Migration flow — 由 webhook 事件觸發的遷移流程；為簡潔起見，從協調器開始。

擴充套件遷移

四月，我們聯絡了 bartowski，詢問他們是否願意測試 Xet，從而測試了該系統的極限。bartowski 擁有近 500 TB 的資料，分佈在 2,000 個儲存庫中，其遷移揭示了一些薄弱環節：

用於全域性重複資料刪除的臨時分片檔案最初寫入 /tmp，然後移動到分片快取。然而，在我們的 worker pod 上，/tmp 和 Xet 快取位於不同的掛載點。移動失敗，分片檔案從未被刪除。最終磁碟被填滿，觸發了一波 裝置上沒有剩餘空間 錯誤。
在支援 Llama 4 釋出後，我們為突發下載擴充套件了 CAS，但遷移工作程序卻顛倒了局面，數百個多 GB 的上傳將 CAS 推到了其資源極限之外。
從理論上講，遷移工作程序能夠實現比報告的吞吐量高得多的吞吐量；對 pod 進行效能分析揭示了網路和 EBS I/O 瓶頸。

解決這個三頭怪物意味著觸及每一個層面——修補 xet-core、調整 CAS 大小以及增強工作節點規格。幸運的是，bartowski 願意與我們合作，直到每個儲存庫都遷移到 Xet。這些經驗教訓也為 Hub 上最大的儲存使用者（如 RichardErkhov（1.7PB 和 25,000 個儲存庫）和 mradermacher（6.1PB 和 42,000 個儲存庫 🤯））的遷移提供了動力。

與此同時，CAS 的吞吐量在第一次和最近一次大規模遷移之間增長了一個數量級