儲存

Hugging Face Hub 上的儲存庫與軟體開發平臺上的儲存庫不同。它們包含的檔案具有以下特點：

• 大——模型或資料集檔案通常在 GB 甚至更大範圍。我們有一些 TB 級的檔案！
• 二進位制——預設情況下不可讀（例如，Safetensors 或 Parquet）

儘管 Hub 利用了 Git 支援的現代版本控制，但這些差異使得模型和資料集儲存庫與僅包含原始碼的儲存庫大相徑庭。

將這些檔案直接儲存在 Git 儲存庫中是不切實際的。Git 儲存庫背後的典型儲存系統不適合此類檔案，而且當你克隆一個儲存庫時，Git 會檢索整個歷史記錄，包括所有檔案修訂。對於大型二進位制檔案來說，這可能非常龐大，迫使你下載可能永遠不需要的千兆位元組歷史資料。

相反，在 Hub 上，這些大型檔案透過“指標檔案”進行跟蹤，並透過 `.gitattributes` 檔案進行標識（兩者都將在下面詳細討論），它們保留在 Git 儲存庫中，而實際資料則儲存在遠端儲存（如 Amazon S3）中。因此，儲存庫保持小巧，典型的 Git 工作流也保持高效。

從歷史上看，Hub 儲存庫一直依賴 Git LFS 來實現這種機制。雖然 Git LFS 仍然受支援並廣泛使用（請參閱下面的舊版部分），但 Hub 正在引入一個專門為 AI/ML 開發構建的現代化自定義儲存系統，它支援塊級重複資料刪除、更小的上傳和比 Git LFS 更快的下載。

Xet

Hugging Face 於 2024 年 8 月收購了 XetHub，這是一家位於西雅圖的種子期初創公司，旨在取代 Hub 上的 Git LFS。

與 Git LFS 類似，基於 Xet 的儲存庫利用 S3 作為遠端儲存，並在儲存庫根目錄中使用 `.gitattributes` 檔案來幫助識別哪些檔案應該遠端儲存。

同時，Git LFS 指標檔案提供元資料以定位遠端儲存中的實際檔案內容

• SHA256: 為實際的大檔案提供唯一識別符號。此識別符號是透過計算檔案內容的 SHA-256 雜湊值生成的。
• 指標大小: 儲存在 Git 倉庫中的指標檔案的大小。
• 遠端檔案大小: 指示實際大檔案的大小（以位元組為單位）。此元資料對於驗證和管理儲存及傳輸操作都很有用。

Xet 指標本身包含所有這些資訊。有關詳細資訊，請參閱關於與 Git LFS 的向後相容性的部分，其中增加了用於引用 Xet 儲存中檔案的 `Xet backed hash` 欄位。

與 Git LFS 在檔案級別進行重複資料刪除不同，啟用 Xet 的儲存庫在位元組級別進行重複資料刪除。當基於 Xet 儲存的檔案更新時，只有修改過的資料會上傳到遠端儲存，從而顯著節省網路傳輸。對於許多工作流，例如模型檢查點的增量更新或向資料集中追加/插入新資料，這可以提高您和您的協作者的迭代速度。要了解有關 Xet 儲存中重複資料刪除的更多資訊，請參閱下面的重複資料刪除部分。

使用 Xet 儲存

要開始使用 Xet 儲存，您需要一個支援 Xet 的儲存庫和一個支援 Xet 的 huggingface_hub Python 庫版本。截至 2025 年 5 月 23 日，支援 Xet 的儲存庫已成為 Hub 上所有新使用者和組織的預設設定。

要獲取 Xet 感知版本的 `huggingface_hub`，只需安裝最新版本即可。

pip install -U huggingface_hub

自 `huggingface_hub` 0.32.0 版本起，這還將安裝 `hf_xet`。`hf_xet` 包將 `huggingface_hub` 與 Xet 後端的 Rust 客戶端 `xet-core` 整合。

如果您使用 `transformers` 或 `datasets` 庫，它已經在使用 `huggingface_hub`。只要 `huggingface_hub` 的版本 >= 0.32.0，就不需要進一步的操作。

如果安裝了版本 >= 0.30.0 且 < 0.32.0 的 `huggingface_hub`，則必須顯式安裝 `hf_xet`

pip install -U hf-xet

就這樣！你現在可以享受 Xet 對上傳和下載的重複資料刪除帶來的好處。使用 `huggingface_hub` 版本 < 0.30.0 的團隊成員仍然可以透過 LFS 橋提供的向後相容性上傳和下載儲存庫。

要檢視更詳細的使用文件，請參考 `huggingface_hub` 的文件：

• 上傳
• 下載
• 管理 `hf_xet` 快取

建議

Xet 與 Hub 當前基於 Python 的工作流程無縫整合。但是，您可以考慮以下幾個步驟，以充分利用 Xet 儲存的優勢：

• 使用 `hf_xet`：雖然 Xet 仍與針對 Git LFS 最佳化的舊版客戶端向後相容，但 `hf_xet` 與 `huggingface_hub` 的整合可提供最佳的基於分塊的效能，並加快大型檔案的迭代速度。
• 利用 `hf_xet` 環境變數：`hf_xet` 的預設安裝旨在支援最廣泛的硬體。要利用具有更多網路頻寬或處理能力的設定，請查閱 `hf_xet` 的環境變數，以進一步加快下載和上傳速度。
• 利用頻繁的增量提交：Xet 的塊級重複資料刪除意味著您可以安全地對模型或資料集進行增量更新。只上傳更改的塊，因此頻繁提交既快速又節省儲存空間。
• 在 .gitattributes 中明確指定：在定義 Xet 或 LFS 模式時，使用精確的副檔名（例如，`*.safetensors`，`*.bin`）以避免不必要地將較小的檔案透過大檔案儲存路由。
• 優先考慮社群訪問：Xet 大幅提高了大檔案傳輸的效率和規模。與其調整儲存庫結構以減小其總大小（或單個檔案的大小），不如為協作者和社群使用者組織儲存庫，以便他們可以輕鬆導航和檢索所需內容。

當前限制

儘管 Xet 為基於 Git 的儲存帶來了細粒度的重複資料刪除和增強的效能，但某些功能和平臺相容性仍在開發中。因此，在使用啟用 Xet 的儲存庫時，請記住以下限制：

• 僅限 64 位系統：`hf_xet` 客戶端目前需要 64 位架構；不支援 32 位系統。
• 部分 JavaScript 庫支援：huggingface.js 庫對 Xet 支援的儲存庫功能有限；計劃在未來的版本中增加額外的覆蓋範圍。
• 暫無完整 Web 支援：透過 Hub Web 介面進行分塊上傳的完整支援仍在開發中。
• 不支援歐盟地區：計劃支援 Xet 支援的儲存庫的歐盟儲存區域，但仍在開發中。
• Git 客戶端整合 (git-xet)：已計劃但仍在開發中。

重複資料刪除

支援 Xet 的儲存庫利用內容定義分塊 (CDC) 來在位元組級別（約 64KB 資料，也稱為“塊”）進行重複資料刪除。每個塊都透過一個滾動雜湊來標識，該雜湊根據實際檔案內容確定塊邊界，使其能夠抵禦檔案中任意位置的插入或刪除。當使用支援 Xet 的客戶端將檔案上傳到支援 Xet 的儲存庫時，其內容會被分解成這些可變大小的塊。只有 Xet 儲存中尚未存在的新塊才會在分塊後保留，其餘所有內容都會被丟棄。

為了避免在塊級別進行通訊和管理的開銷，新的塊被分組到64MB 的塊中並上傳。每個塊在內容定址儲存 (CAS) 中儲存一次，並以其雜湊值作為鍵。

Hub 目前的建議是將檔案限制在 20GB。以 64KB 的分塊大小計算，一個 20GB 的檔案有 312,500 個分塊，其中許多版本之間保持不變。Git LFS 旨在只注意到檔案已更改並存儲該修訂的全部內容。透過在分塊級別進行重複資料刪除，Xet 後端可以只儲存檔案中修改過的內容（可能只有幾 KB 或 MB），並安全地對跨儲存庫共享的塊進行重複資料刪除。對於模型和資料集儲存庫中的大型二進位制檔案，這顯著提高了檔案傳輸時間。

欲瞭解更多詳情，請參閱從檔案到塊和從塊到塊的部落格文章，或者 Low 等人撰寫的Git 是資料論文，該論文在 Hugging Face 收購 XetHub 之前曾作為 XetHub 的啟動點。

與 LFS 的向後相容性

Xet 儲存為現有 Hub 儲存庫提供了無縫過渡。完全不需要了解是否涉及 Xet 後端。Xet 支援的儲存庫繼續使用 Git LFS 指標檔案格式；`Xet backed hash` 的新增僅作為方便在 Web 介面中顯示。實際上，這意味著如果你對現有儲存庫和新建立的儲存庫進行 `bare clone`，它們看起來不會有任何不同。每個大型檔案（或二進位制檔案）將繼續擁有一個與 Git LFS 指標檔案規範相匹配的指標檔案。

這種對稱性允許不感知 Xet 的客戶端（例如，舊版本的 `huggingface_hub`）與支援 Xet 的儲存庫進行互動而無需擔憂。事實上，在一個儲存庫中，支援 Git LFS 和 Xet 支援的檔案的混合。Xet 後端指示檔案是位於 Git LFS 還是 Xet 儲存中，允許下游服務從 S3 請求適當的 URL，無論哪個儲存系統持有內容。

在 Xet 架構中，下載的向後相容性由 Git LFS 網橋實現。Xet 感知客戶端將從 CAS 接收檔案重建資訊以下載 Xet 支援的檔案，而傳統客戶端將從網橋獲取單個 URL，該網橋負責重建請求檔案並返回資源 URL。這允許透過 URL 下載檔案，以便您可以繼續使用 Hub 的 Web 介面或 `curl`。

同時，來自非 Xet 感知客戶端的上傳仍遵循標準的 Git LFS 路徑，即使檔案已經由 Xet 支援。一旦檔案上傳到 LFS，後臺程序會自動遷移內容，將其轉換為 Xet 支援的版本。結合 Git LFS 網橋，這使得儲存庫維護者和 Hub 的其餘部分可以按照自己的節奏無縫採用 Xet。

安全模型

Xet 儲存透過加密雜湊以隱私敏感的方式對 Hugging Face 中儲存的所有分塊進行資料去重。分塊的內容受到保護，並與儲存庫許可權關聯。也就是說，您只能讀取重現您有權訪問的檔案所需的塊，不能多讀。有關詳細資訊，請參閱 xet-core。

舊版儲存：Git LFS

Hub 上的舊版儲存系統 Git LFS 採用了許多與 Xet 支援的儲存庫相同的約定。Hub 的 Git LFS 後端是 Amazon Simple Storage Service (S3)。當呼叫 Git LFS 時，它使用 SHA 雜湊將檔案內容儲存在 S3 中，以便將來訪問。這種儲存架構相對簡單，並允許 Hub 儲存數百萬個模型、資料集和 Spaces 儲存庫的檔案（截至本文撰寫時共計 45PB）。

Git LFS 的主要限制在於其以檔案為中心的重複資料刪除方法。對檔案的任何更改，無論大小如何，都意味著整個檔案都被版本化——導致檔案傳輸中產生顯著的開銷，因為整個檔案會被上傳（如果提交到儲存庫）或下載（如果拉取最新版本到您的機器）。

這導致開發人員體驗變差，並導致額外儲存的泛濫。