博客 / 詳情

返回

huggingface_hub 1.0 正式版現已發佈：開源機器學習基礎五週年回顧

簡要總結： 經過五年的持續開發，huggingface_hub 發佈 v1.0 正式版！這一里程碑標誌着這個庫的成熟與穩定。它已成為 Python 生態中支撐 20 萬個依賴庫 的核心組件，並提供訪問超過 200 萬公開模型、50 萬公開數據集 和 100 萬 Space 應用 的基礎能力。本次更新包含為支持未來十年開源機器學習生態而做出的重大變更，由近 300 位貢獻者和數百萬用户共同推動發展。

🚀 強烈建議儘快升級至 v1.0，以體驗更優性能和全新功能。

pip install --upgrade huggingface_hub

此次重大版本更新包括以下內容：

  • 使用 httpx 作為新後端請求庫；
  • 全新設計的 hf 命令行工具（取代已棄用的 huggingface-cli），採用 Typer 構建，功能更加豐富；
  • 文件傳輸全面遷移至 hf_xet，徹底淘汰舊的 hf_transfer 工具。

查看完整的 v1.0 發佈説明

我們儘可能確保 v1.0.0 與舊版本兼容。大多數機器學習庫無需修改即可兼容 v0.x 和 v1.x。主要例外是 transformers：v4 版本依賴 v0.x，計劃中的 v5 將轉向 v1.x。查看此 issue 獲取詳細的庫兼容性表。

背後的故事

每個主流庫背後都有一段故事。huggingface_hub 的故事始於一個簡單的想法：如果共享機器學習模型像在 GitHub 上分享代碼一樣容易，會怎樣？

在 Hugging Face Hub 的早期階段，研究人員和開發者常常面臨一個困擾：
訓練一個先進的模型不僅耗時、耗資源，而且在訓練完成後，模型往往“被困”在個人電腦裏，只能通過不穩定的 Google Drive 鏈接進行分享。
這導致社區重複造輪子，資源浪費嚴重，協作效率極低。

為了解決這一問題，Hugging Face Hub 應運而生。最初，它的功能很簡單，只是用於共享和託管與 transformers 庫兼容的模型檢查點。而與 Hub 交互的全部 Python 邏輯代碼，也都內置在 transformers 庫中，其他庫無法複用這些功能。

直到 2020 年底，我們推出了 huggingface_hub 的首個版本 v0.0.1，它的初衷是：將原本封裝在 transformers 庫中的內部邏輯獨立出來，構建一個專用庫，用於統一訪問和共享 Hugging Face Hub 上的機器學習模型與數據集。最早的版本非常簡潔，它只是一個 Git 操作的封裝工具，用於下載文件和管理倉庫。但五年過去，歷經 35+ 個版本迭代，huggingface_hub 已遠遠超越最初的設想。

讓我們一起來回顧這段發展歷程。

奠基階段（2020–2021）

最初的幾個版本為整個庫打下了基礎。
版本 0.0.8 引入了第一個 API，通過封裝 Git 命令，實現與模型倉庫的交互。
接着在版本 0.0.17 中，加入了基於 token 的認證機制，支持訪問私有倉庫並安全上傳內容。
雖然這些功能看起來很基礎，但它們構成了後來所有進步的基石。

重要轉折：從 Git 到 HTTP（2022）

2022 年 6 月，版本 0.8.1 發佈，這是 Hugging Face Hub 發展史上的一個轉折點——我們引入了 HTTP Commit API。

從此，用户無需再安裝 Git 和 Git LFS，也能直接通過 HTTP 上傳文件。新推出的 create_commit() API 極大簡化了上傳流程，尤其適合處理大型模型文件——這些文件過去通過 Git LFS 操作起來十分繁瑣。

此外，該版本還引入了支持 Git 結構感知的緩存機制。所有使用 huggingface_hub 的庫（無論是官方的 transformers，還是第三方庫）現在都能共享同一套緩存系統，具備顯式的版本控制和文件去重功能。

這不僅僅是一次技術優化，更是一次理念上的飛躍。
我們不再只是為 transformers 構建 Git 工具，而是在構建一套專為機器學習模型和數據打造的基礎設施，面向整個機器學習生態服務。

API 能力的全面擴展（2022–2024）

隨着 Hugging Face Hub 從一個模型倉庫逐步發展為一個完整的平台，huggingface_hub 的 API 能力也不斷拓展，滿足更多場景需求。

核心的倉庫操作功能不斷成熟，支持：

  • 列出文件樹（list tree）
  • 瀏覽引用（refs）與提交記錄（commits）
  • 讀取文件或同步整個文件夾
  • 管理標籤、分支和發佈週期（release cycle）
  • 查詢倉庫元數據與設置 webhook，幫助團隊實時響應變更

與此同時，Hub 上的 Spaces 功能開始嶄露頭角，它是一個簡單卻強大的方式，可以直接在 Hub 上託管和分享交互式的機器學習演示項目。huggingface_hub 也逐步實現了對 Spaces 的完整程序化管理能力，包括硬件資源申請、環境配置、密鑰管理、文件上傳等。

為了支持模型在生產環境中的部署，我們還集成了 Inference Endpoints。而在 2025 年第三季度，Jobs API 的加入，進一步完善了 Hugging Face 的計算服務能力。

在此過程中，社區與社交層也被提升為一等公民。現在支持：

  • 創建和管理 Pull Requests 和評論
  • 查詢用户與組織信息
  • 倉庫點贊、關注、粉絲功能
  • 使用 Collections 整理和分享資源合集

同時，日常使用體驗也得到了顯著優化：Colab 中的無縫認證、大型文件夾上傳的可靠性提升、支持斷點續傳等功能，使開發更加高效流暢。

隨後，在版本 v0.28.0 中，我們推出了 推理服務提供方生態。不再依賴單一的推理後端，而是與多家無服務器推理平台合作，包括 Together AI、SambaNova、Replicate、Cerebras、Groq 等，用户通過一個統一的 API 即可調用多個後端，路由透明，按請求計費，真正實現了“按需調用，輕鬆推理”。

Ready. Xet. Go!（2024–2025）

在版本 v0.30.0 中，我們發佈了 Xet —— 一種顛覆性的 Git 大文件存儲協議。

與傳統的 Git LFS（只支持文件級去重）不同，Xet 在更精細的粒度（每 64KB 為一塊）進行數據去重與傳輸優化。當你更新一個大型模型或數據文件時，系統只會上傳或下載發生變更的部分，而不是整個文件。

這場大規模遷移 始於 50 多萬個倉庫，涉及超過 20PB 的數據。但令人驚喜的是，這一遷移過程對用户是完全透明的，100% 向後兼容，無需手動干預，也沒有中斷現有流程。

一年後，超過 6,000,000 個倉庫、77PB+ 的數據已成功遷移至 Xet 後端，帶來了更快、更智能的上傳與下載體驗 🔥

成長與影響力衡量

衡量一個開源庫的成長和影響力並不容易，但有時，數字本身就是最好的證明：

  • 每月下載量達 1.135 億次，累計下載超 16 億次（截至 2025 年 10 月）
  • 提供訪問 200 萬+ 公共模型、50 萬+ 公共數據集 和 100 萬+ 公共 Spaces —— 如果包括私有倉庫，總量大約翻倍
  • 每日活躍用户超過 6 萬人，每月活躍用户超過 55 萬人
  • 被全球 20 萬+ 企業 信賴使用，從初創公司到《財富》500 強企業

但真正體現其規模的，是整個生態的廣度和深度。huggingface_hub 已成為 GitHub 上 超過 20 萬個倉庫 和 PyPI 上 3,000 個軟件包 的 依賴核心 ，涵蓋主流框架如 Keras、LangChain、PaddleOCR、ChatTTS、YOLO、Google Generative AI、Moshi、NVIDIA NeMo、Open Sora 等，還有無數小型工具與項目。Hugging Face 自家生態（如 transformers、diffusers、datasets、sentence-transformers、gradio、peft、trl 等）也都建立在其之上。

最令人欣慰的是，這些第三方集成大多數都是自然發生的，我們並未主動推動。這正是 Hugging Face Hub 釋放力量的體現——它讓整個機器學習社區能夠更加開放、高效地協作與創新，而它如今的廣泛使用程度，也遠超我們的最初預期。

面向未來十年的構建

v1.0 不只是一個版本號的躍遷，它代表的是：為未來十年開放式機器學習奠定堅實基礎。我們做出的破壞性更新並非隨意為之，而是出於戰略考慮，為了讓 huggingface_hub 能夠應對 AI 的高速發展，並保持全球數百萬開發者所依賴的穩定性與可靠性。

現代化 HTTP 架構：httpx 與 hf_xet

v1.0 最重要的架構變更，是將底層 HTTP 請求庫從 requests 遷移至 httpx。這不僅是依賴項的替換，而是一次真正意義上的升級，使整個庫正式邁入現代 HTTP 時代。

為什麼選擇 httpx？
它帶來的好處非常顯著：

  • 原生支持 HTTP/2，連接效率更高
  • 完整的線程安全，可在多線程間安全複用連接
  • 最關鍵的是：提供統一的同步與異步接口，徹底消除原先同步與異步推理客户端之間的微妙差異

此次遷移的設計儘可能做到“對用户透明”，大多數用户無需做任何修改。對於使用自定義 HTTP 後端的開發者，我們提供了清晰的遷移路徑，將 configure_http_backend() 替換為 set_client_factory() 或 set_async_client_factory()。

同時，hf_xet 現已成為 Hub 上傳和下載文件的默認工具包，完全取代此前的可選方案 hf_transfer，後者已被徹底移除。

MCP 與 Tiny-Agents：讓智能體開發觸手可及

在 v0.32.0 中，我們引入了 Model Context Protocol（模型上下文協議，MCP）集成 和 tiny-agents 工具鏈，這從根本上改變了構建 AI Agent 的方式。曾經需要複雜框架集成的任務，如今只需大約 70 行 Python 代碼即可完成。

MCPClient 提供了一個標準化接口，使 AI Agent 能夠輕鬆與各種工具進行交互；而 tiny-agents CLI 工具則允許你直接從 Hub 啓動 Agent。你可以連接本地或遠程 MCP 服務器，將任意 Gradio Space 用作工具，並構建出自然、流暢、響應迅速的對話式智能體。

所有這些，都是在我們現有的 InferenceClient 以及其支持的多家推理服務商的基礎上構建的。我們堅信 Agent 是未來，而 huggingface_hub 將持續提供這些構建 AI 工具的基礎模塊，助力開發者快速落地創新想法。

面向現代工作流的全功能命令行工具

Hugging Face 的 CLI 工具已經從一個簡單的命令行工具，發展為一個 功能全面的機器學習操作接口。全新設計的 hf 命令取代了老舊的 huggingface-cli，採用現代化的“資源-動作”模式：

  • hf auth login：用户認證
  • hf download 和 hf upload：文件上傳與下載
  • hf repo：倉庫管理
  • hf cache ls 和 hf cache rm：緩存管理
  • hf jobs run：運行雲端計算任務

CLI 提供了 沙箱式安裝器，可以在不破壞現有開發環境的前提下快速安裝或升級：

# macOS 或 Linux
curl -LsSf https://hf.co/cli/install.sh | sh

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

CLI 還支持命令自動補全，並在各大主流平台上都能順利運行。如今的 Hugging Face CLI，已經具備與現代開發工具媲美的體驗和易用性。

為未來清理技術債

在 v1.0 中，我們移除了部分阻礙未來發展的舊功能和用法：

  • 基於 Git 的 Repository 類已被移除。
  • HTTP 接口如 upload_file() 和 create_commit() 變得更簡潔、更穩定，也更適應現代化工作流。
  • HfFolder 的 token 管理方式已被顯式的 login()、logout() 和 get_token() 函數所取代，使用方式更直觀。
  • 原有的 InferenceApi 類被功能更完善的 InferenceClient 替代。
  • 文件傳輸工具 hf_transfer 被徹底淘汰，現已由全新的二進制工具包 hf_xet 完全接管。

這些變更並非倉促決策，我們在數月前就已發佈棄用通知，附帶清晰的遷移指引。最終目標是打造一個 更清晰、更易維護 的代碼庫，讓我們能夠集中精力開發面向未來的新特性，而不是繼續兼容過時的實現方式。

遷移指南

我們理解，破壞性更新可能會對現有項目造成困擾。正因如此，我們投入了大量精力，儘可能讓遷移過程順暢無痛。官方的 遷移指南 提供了每項變更的 逐步説明，並解釋了背後的原因。

最重要的是，我們在可能的地方 保留了向後兼容性。例如 HfHubHttpError 同時繼承了舊版 requests 和新版 httpx 的 HTTPError 異常類，確保原有錯誤處理邏輯依然生效。

從 v1.0 起，我們將全面聚焦新版的開發與維護，確保為社區提供更高性能、更豐富功能和更完善的工具。舊版（v0.*）仍可在 PyPI 下載，但今後只會進行安全性補丁更新，不再添加新功能。

我們盡力確保 huggingface_hub v1.0.0 與舊版兼容。在實際使用中，大多數機器學習庫在 v0.x 與 v1.x 之間都能無縫切換。主要例外是 transformers：其 v4 版本明確依賴 v0.x，而即將發佈的 v5 將改為依賴 v1.x。想了解各主流庫的兼容情況，請參考這個 兼容性彙總表。

特別緻謝

感謝 280 多位為本庫貢獻代碼、文檔、翻譯和社區支持的開發者們！

同時也感謝 Hugging Face 社區提供的反饋、Bug 報告與建議，這些都幫助我們不斷完善產品。

最後，衷心感謝廣大用户 —— 無論是獨立開發者還是大型企業 —— 感謝你們信任 huggingface_hub，讓它成為你們工作流程的一部分。是你們的支持激勵我們不斷前行。

如果你喜歡這個項目，歡迎到 GitHub 點個星 ⭐，支持我們繼續建設開源機器學習的未來！

五年已過，但一切才剛剛開始！

英文原文: https://huggingface.co/blog/huggingface-hub-v1

原文作者: Lucain Pouget, Célina Hanouti, Lysandre, Julien Chaumond

譯者: Luke, Hugging Face Fellow

人工智能
user avatar
0 位用戶收藏了這個故事！

發佈 評論

Some HTML is okay.