huggingface_hub v1.0: 五年打造開放機器學習的基礎

TL;DR: 在五年的開發之後，huggingface_hub 已達到 v1.0——這是一個標誌著此函式庫成熟的里程碑，作為支援 200,000 依賴的函式庫 的 Python 套件，並提供存取超過 200 萬個公開模型、50 萬個公開資料集與 100 萬個公開 Spaces 的核心功能。此版本引入了為支援未來十年的開放機器學習而設計的重大變更，由全球近 300 位貢獻者與數百萬使用者共同推動。 🚀 我們強烈建議升級至 v1.0，以受惠於重大的效能提升與新功能。

函式庫背後的故事

此函式庫從 2020 年的簡易 Git 包裝器演變為支援 Hugging Face Hub 的成熟基礎，歷時五年。

基礎時期 (2020-2021)

早期的發行奠定了基礎：版本 0.0.8 引入了首批包裝 Git 指令的 API，版本 0.0.17 則加入了針對私有倉庫與上傳的 token 驗證。

巨大的轉變：從 Git 到 HTTP (2022)

2022 年 6 月，版本 0.8.1 引入了 HTTP Commit API，允許透過 HTTP 上傳檔案而不需 Git LFS，並新增了跨函式庫共享的 git 感知快取布局。

擴展的 API 範圍 (2022–2024)

隨著 Hub 的成長，函式庫加入了倉庫中繼資料、webhook、Spaces 管理、推論端點、工作 API、社群功能（如 pull request 與評論），以及按請求付費的推論提供者 (Inference Providers)。

準備。Xet。出發！ (2024-2025)

版本 0.30.0 引入了 Xet，一種區塊級儲存協定；此遷移在超過 6,000,000 個倉庫間透明地搬移了 77PB+ 的資料，實現了更快速的上傳與下載。

衡量成長與影響

此函式庫如今獲得廣泛採用，支援數百萬個模型，並被數十萬使用者與公司使用。

  • 每月下載量 1.135 億次，累計 16 億次（2025 年 10 月）。
  • 支援存取 200 萬以上的公開模型、50 萬以上的公開資料集、100 萬以上的公開 Spaces（另有私有副本）。
  • 每日使用者超過 6 萬人，月活使用者超過 55 萬人。
  • 受到 20 萬家企業的信任，從新創公司到《財富》500 強皆有使用。
  • 作為超過 200,000 個 GitHub 倉庫與 3,000 個 PyPI 套件的依賴，涵蓋主要框架如 Keras、LangChain、PaddleOCR、ChatTTS、YOLO、Google Generative AI、Moshi、NVIDIA NeMo 與 Open Sora。
  • 由近 300 位貢獻者共同打造。

為未來十年打造

版本 1.0 引入策略性重大變更，以擴展函式庫在未來十年的規模。

使用 httpx 與 hf_xet 的現代 HTTP 基礎設施

遷移至 httpx 並預設使用 hf_xet 可提升效能、執行緒安全性與非同步支援。

  • httpx 取代 requests，提供原生 HTTP/2、真正的執行緒安全性，以及統一的同步/非同步 API。
  • hf_xet 現已成為檔案傳輸的預設套件，取代可選的 hf_transfer。
  • 自訂 HTTP 後端可從 configure_http_backend() 遷移至 set_client_factory() 與 set_async_client_factory()。

使用 MCP 與 Tiny-Agents 簡化代理程式

MCP 整合與 tiny-agents 讓開發者能以約 70 行 Python 建構 AI 代理程式。

  • MCPClient 提供了代理程式與工具互動的標準化方式。
  • tiny-agents CLI 可直接從 Hub 執行代理程式，連接本地或遠端 MCP 伺服器，並使用任何 Gradio Space 作為工具。
  • 基於現有的 InferenceClient 以及其支援數十個 Inference Providers 的功能構建。

為現代工作流程打造的完整 CLI

重新設計的 hf CLI 以 Typer 為基礎的介面取代 huggingface-cli，涵蓋驗證、傳輸、倉庫管理、快取與工作等功能。

  • hf auth login 用於驗證。
  • hf download 與 hf upload 用於檔案傳輸。
  • hf repo 用於倉庫管理。
  • hf cache ls 與 hf cache rm 用於快取管理。
  • hf jobs run 用於雲端運算。
  • 跨平台安裝程式：
# macOS or Linux
curl -LsSf https://hf.co/cli/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

為未來清理舊有結構

移除舊有類別與模式，以簡化程式碼基礎並聚焦於前瞻功能。

  • 基於 Git 的 Repository 類別已移除；基於 HTTP 的方法如 upload_file() 與 create_commit() 現已成為標準。
  • Token 管理已從 HfFolder 移至明確的 login()、logout() 與 get_token() 函式。
  • 舊的 InferenceApi 類別已被功能更完整的 InferenceClient 取代。
  • hf_transfer 完全被 hf_xet 二進位套件取代。
  • 大多數棄用皆於數月前公告，並提供警告與遷移指引。

遷移指南

完整的遷移指南簡化升級流程，除 transformers v5 外，對大多數函式庫維持向後相容性。

  • 指南提供每項變更的逐步說明，並解釋其必要性。
  • 在可能的情況下保留向後相容性；例如，HfHubHttpError 同時繼承舊的 requests 與新的 httpx 基礎 HTTPError 類別。
  • 先前的 v0.* 版本僅保留於 PyPI 供安全性更新使用，開發重點則放在 v1.0 及之後的版本。
  • 主要例外是 transformers，其 v4 版需要 huggingface_hub v0.x，而即將推出的 v5 版則需要 v1.x（請參閱 issue #3340 中的相容性表格）。

致謝

感謝所有貢獻者、社群與使用者。

  • 超過 280 位貢獻者透過程式碼、文件、翻譯與社群支援共同打造此函式庫。
  • 更廣大的 Hugging Face 社群提供了回饋、錯誤回報與建議。
  • 從個人開發者到大型企業的使用者皆信任 huggingface_hub 以驅動其工作流程。

Sources