swift-huggingface 發行說明 / 新功能

Hugging Face 宣佈推出 swift-huggingface，這是一個全新的 Swift 套件，提供完整的 Hugging Face Hub 客戶端。此函式庫解決了 Swift 生態系統中關於大型模型下載、與 Python 的快取同步以及驗證彈性等關鍵的可靠性與開發者體驗缺口。

可靠的模型下載與續傳支援

swift-huggingface 以基於 URLSession 下載任務的穩健系統取代了先前不可靠的下載機制。它提供明確的進度追蹤以及續傳中斷下載的能力，這對於機器學習中常見的多 GB 檔案至關重要。

主要的下載功能包括：

  • Resume Support：resumeDownloadFile 方法允許開發者使用已保存的續傳資料，從中斷的地方繼續下載。
  • Snapshot Downloads：downloadSnapshot 函式管理整個模型倉庫，追蹤中繼資料以確保在後續呼叫時僅下載已變更的檔案。
  • Filtered Downloads：使用者可以指定模式（例如 *.safetensors、*.json），僅下載倉庫中必要的檔案。

與 Python 相容的快取結構

為了消除重複下載，swift-huggingface 實作了與 Python huggingface_hub 函式庫相容的快取結構。這使得 Swift 應用程式能共享已透過 Python CLI 或 transformers 函式庫下載的模型。

快取採用內容位址儲存（content‑addressed storage），檔案依其 ETag 存放於 blobs/ 目錄。快照目錄使用指向這些 blob 的符號連結，以減少磁碟使用量。函式庫遵循標準的環境變數慣例來決定快取位置，會檢查 HF_HUB_CACHE、HF_HOME，若未設定則預設為 ~/.cache/huggingface/hub。為防止多行程存取時的競爭條件，函式庫使用 flock(2) 檔案鎖定。

彈性的驗證與 OAuth 2.0

驗證透過 TokenProvider 模式管理，使憑證來源明確。函式庫支援多種驗證流程：

  • Auto-detection：自動在環境變數（HF_TOKEN、HUGGING_FACE_HUB_TOKEN）、令牌檔案或標準 HF CLI 位置中尋找令牌。
  • Static Tokens：為 CI/CD 環境明確提供的令牌。
  • Keychain Integration：透過系統 Keychain 為正式應用提供安全儲存。
  • OAuth 2.0：為面向使用者的應用提供完整實作，包含 HuggingFaceAuthenticationManager，負責系統瀏覽器登入、在 Keychain 中儲存令牌，以及自動令牌刷新。

完整的 Hub 與推論 API 支援

除了檔案操作之外，swift-huggingface 還提供完整的客戶端，以與 Hugging Face Hub 與推論服務提供者互動：

  • Hub API：支援列出與管理模型、資料集、Spaces、集合與討論。
  • Inference Client：InferenceClient 讓應用程式透過 Hugging Face 推論服務提供者存取數百個模型，包含 textToImage 等功能，可根據文字提示產生圖像。

未來路線圖與整合

目前正透過 Pull Request 與 swift-transformers 整合，以取代現有的 HubApi 實作。此更新將把 swift-huggingface 的可靠性擴展至 mlx-swift-lm 及其他生態系統函式庫的使用者。此外，Hugging Face 正在開發對 Xet storage backend 的支援，該後端將引入基於區塊的去重機制，進一步加速大型模型的下載。

Sources