Hugging Face 發佈 huggingface_hub v1.0,遷移至 httpx、重設計 hf CLI 並採用 hf_xet
huggingface_hub v1.0: Five Years of Building the Foundation of Open Machine Learning
Hugging Face 發佈 Python 套件 huggingface_hub v1.0,遷移至 httpx,推出重設計的 hf CLI,並將 hf_xet 設為檔案傳輸預設套件。
文章集中説明 httpx、hf CLI 與 hf_xet 的變更,並列出 transformers v4、v5 的版本相容要求,便於維護者評估升級範圍。
簡介:經過五年開發,huggingface_hub 已達 v1.0,標誌着程式庫日趨成熟。它是 Python 套件,為200,000 個相依程式庫提供支援,並提供核心功能,讓用戶存取超過 2 百萬個公開模型、0.5 百萬個公開資料集,以及 1 百萬個公開 Spaces。這次發布包含破壞性變更,旨在支援未來十年的開放機器學習發展,背後由全球近 300 位貢獻者和數百萬用戶推動。
🚀 我們強烈建議升級至 v1.0,以享用重大效能提升和新功能。
pip install --upgrade huggingface_hub
本次版本主要變更包括改用 httpx 作為後端程式庫、全面重新設計 hf CLI(取代已棄用的 huggingface-cli),採用 Typer 介面並大幅擴充功能集,以及全面採用 hf_xet 傳輸檔案,取代舊有的 hf_transfer。請在此查看完整發布説明。
我們努力確保
huggingface_hubv1.0.0 維持向後相容。實際上,大部分 ML 程式庫都應可在 v0.x 和 v1.x 版本中順暢運作。主要例外是transformers:其 v4 版本明確要求huggingface_hubv0.x,而即將推出的 v5 版本則要求 v1.x。如需瞭解各程式庫的詳細相容性,請參閲此問題中的表格。
程式庫背後的故事
每個重要程式庫都有一段故事。對 huggingface_hub 而言,一切始於一個簡單想法:分享機器學習模型,可否像在 GitHub 分享程式碼一樣容易?
Hugging Face Hub 發展初期,研究人員和實務工作者都面對同一種挫折。訓練最先進模型需要大量運算資源和專業知識。訓練完成後,模型往往各自獨立,儲存在本機電腦,再透過(失效的)Google Drive 連結分享。AI 社羣重複做相同工作、浪費資源,也錯失合作機會。
Hugging Face Hub 應運而生,解決了這項挑戰。最初,它主要用來分享與 transformers 程式庫相容的檢查點。所有用於與 Hub 互動的 Python 程式碼都放在這個程式庫內,令其他程式庫無法重用。
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 年六月,0.8.1 版帶來關鍵轉變:我們推出 HTTP Commit API。用戶不再需要安裝 Git 和 Git LFS,可直接透過 HTTP 請求上載檔案。全新的 create_commit() API 大幅簡化工作流程,尤其適用於難以透過 Git LFS 處理的大型模型檔案。此外,我們亦引入具 Git 感知能力的快取檔案佈局。現在所有程式庫(不只 transformers,也包括第三方程式庫)都共用同一個快取,並提供明確版本管理和檔案去重。
這不只是技術改進,更是理念上的轉變。我們不再為 transformers 建立 Git 包裝層,而是建構專為機器學習成品而設的基礎設施,供 ML 生態系統中的任何程式庫使用。
不斷擴展的 API 範圍(2022–2024)
Hub 從模型儲存庫發展成完整平台時,huggingface_hub 亦不斷擴充 API。核心儲存庫功能日趨成熟,包括列出檔案樹、瀏覽 refs 和 commits、讀取檔案或同步資料夾、管理標籤、分支和發布週期。儲存庫中繼資料和 webhook 亦完善了功能,讓團隊可即時回應變更。
與此同時,Spaces 成為在 Hub 直接託管和分享互動式 ML 示範的簡單而強大方式。之後,huggingface_hub 取得完整程式化控制功能,可部署和管理 Spaces(硬件請求、密鑰、環境配置和上載)。我們亦整合 Inference Endpoints,讓模型可部署於正式環境規模的基礎設施。最後,Jobs API 於稍後推出(2025 年第 3 季),完善我們的運算服務。
社交和社羣功能亦成為一等公民:從拉取請求和評論 API,到用戶和組織資訊、儲存庫讚好、關注和追隨者,再到用於整理和分享相關資源的Collections。日常使用體驗亦有所改善,包括在 Colab 無縫驗證、可續傳下載、可靠上載大型資料夾等。
接着推出 0.28.0 版和 Inference Providers 生態系統。我們不再依賴單一推論後端,而是與多個無伺服器供應商(Together AI、SambaNova、Replicate、Cerebras、Groq 等)合作,以透明路由方式提供統一 API。我們採用按請求收費的推論架構,切合用戶實際工作方式。
準備就緒,Xet 出發!(2024–2025)
0.30.0 版推出 Xet,這是一種用於在 Git 儲存庫儲存大型物件的突破性新協定。與在檔案層級去重的 Git LFS 不同,Xet 在區塊層級運作(每個區塊 64KB)。更新資料集或模型中的大型檔案時,只會上載或下載有變更的區塊,而非整個檔案。
這次遷移規模龐大,涉及超過 500,000 個儲存庫中的 20 petabytes 數據,但過程完全透明,並維持完整向後相容。一年後,所有超過 77PB、分佈於超過 6,000,000 個儲存庫的數據均已遷移至 Xet 後端,令上載和下載更快速、更智能。整個過程無須用戶介入,現有工作流程亦不受影響 🔥
衡量增長和影響
衡量開源程式庫的增長和影響並不容易。數字本身便訴説着故事:
- 每月下載 113.5 百萬次,累計下載16 億次(2025 年十月)。
- 支援存取2M+ 個公開模型、500k+ 個公開資料集、1M+ 個公開 Spaces;若計入私人儲存庫,數量約為兩倍。
- 每天有60k+ 名用戶使用,每月有550k+ 名用戶使用
- 獲200k+ 間公司信賴,從初創公司到《財富》500 強企業
從生態系統便可看出真正規模。huggingface_hub 是 GitHub 上超過200,000 個儲存庫和 PyPI 上3,000 個套件的相依套件,支援 Keras、LangChain、PaddleOCR、ChatTTS、YOLO、Google Generative AI、Moshi、NVIDIA NeMo 和 Open Sora 等大型第三方框架,也支援 ML 領域無數規模較小的程式庫和工具。我們自己的生態系統(transformers、diffusers、datasets、sentence-transformers、lighteval、gradio、peft、trl、smolagents、timm、lerobot 等)亦以此為基礎。
值得注意的是,大部分第三方整合都是自然形成的,我們並未參與其中。Hugging Face Hub 以無數方式賦能 ML 社羣;看到它發展得如此廣泛、獲得如此廣泛採用,我們仍深感謙卑。
為未來十年奠基
v1.0 不只是達成一個里程碑,更是為未來十年的開放機器學習奠定基礎。我們所作的破壞性變更並非任意決定,而是策略性選擇,讓 huggingface_hub 能配合 AI 的爆發式增長擴展,同時維持數百萬開發者倚賴的可靠性。
以 httpx 和 hf_xet 打造現代 HTTP 基礎設施
v1.0 最重要的架構變更,是由 requests 遷移至 httpx。這不只是更換相依套件,而是根本升級,讓程式庫踏入現代 HTTP 時代。
為何選用 httpx?優勢顯著:原生支援 HTTP/2,提升連線效率;具備真正的執行緒安全性,可讓多個執行緒安全地重用連線。最重要的是,httpx 為同步和異步操作提供統一 API,消除同步與異步推論用戶端之間細微的行為差異。
此次遷移盡可能做到透明。大部分用戶無須作任何改動。若你使用自訂 HTTP 後端,我們已提供清晰的遷移方式,由 configure_http_backend() 改用 set_client_factory() 和 set_async_client_factory()。
此外,hf_xet 現已成為 Hub 檔案上載和下載的預設套件,取代先前可選用的 hf_transfer;後者現已完全移除。
透過 MCP 和 Tiny-Agents 簡化代理開發
0.32.0 版推出模型上下文協定(MCP)整合和 tiny-agents,徹底改變開發者建立 AI 代理的方式。以往需要複雜框架整合,現在只需約 70 行 Python 程式碼。
MCPClient 為 AI 代理提供與工具互動的標準方式,而 tiny-agents CLI 則讓你可直接從 Hub 執行代理。連接本機或遠端 MCP 伺服器,把任何 Gradio Space 當作工具使用,並建立互動自然、反應靈敏的對話式代理。
以上功能均建基於現有的 InferenceClient 及其支援的數十個 Inference Providers。我們相信代理是未來,而 huggingface_hub 會提供基礎元件,讓 AI 建構者能探索代理應用。
支援現代工作流程的完整 CLI
CLI 已由簡單命令列工具,演進成完整的 ML 操作介面。精簡的 hf 命令取代舊有 huggingface-cli,採用現代資源-動作模式:
hf auth login用於驗證hf download和hf upload用於檔案傳輸hf repo用於儲存庫管理hf cache ls和hf cache rm用於快取管理hf jobs run用於雲端運算
CLI 隨附沙盒安裝程式,方便你升級,而不會破壞現有開發環境:
# On macOS or Linux
curl -LsSf https://hf.co/cli/install.sh | sh
# or on Windows
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"
CLI 現已支援自動補全,並提供跨平台安裝程式,使用體驗與現代開發者工具同樣完善。
為未來精簡整理
v1.0 移除了阻礙發展的舊式模式。以 Git 為基礎的 Repository 類別已移除。upload_file() 和 create_commit() 等 HTTP 方法更簡單、可靠,也更適合現代工作流程。HfFolder token 管理方式已由明確的 login()、logout() 和 get_token() 函數取代。舊有 InferenceApi 類別則由功能更完整的 InferenceClient 取代。hf_transfer 亦已全面改由二進位套件 hf_xet 取代。
這些變更並非輕率作出。大部分棄用項目都提前數月公佈,並附有清晰警告和遷移指引。最終成果是更精簡、更易維護的程式碼庫,讓我們可聚焦未來功能,而非繼續支援已棄用模式。
遷移指南
我們明白破壞性變更會造成不便,因此投入大量心力,務求令遷移盡可能順暢。我們的完整遷移指南逐步説明每項變更,並解釋各項變更的必要性。
最重要的是,我們盡可能維持向後相容。例如,HfHubHttpError 同時繼承舊有 requests 和新 httpx 的基礎 HTTPError 類別,確保不同版本之間的錯誤處理仍可運作。
這次發布代表我們全面投入未來,並會專注於 v1.0 及後續版本,確保提供社羣所需的效能、功能和工具,方便與 Hugging Face Hub 互動。舊有 v0.* 版本仍會在 PyPI 上提供,但只會接收安全漏洞更新。
我們努力確保
huggingface_hubv1.0.0 維持向後相容。實際上,大部分 ML 程式庫都應可在 v0.x 和 v1.x 版本中順暢運作。主要例外是transformers:其 v4 版本明確要求huggingface_hubv0.x,而即將推出的 v5 版本則要求 v1.x。如需瞭解各程式庫的詳細相容性,請參閲此問題中的表格。
鳴謝
感謝 280+ 位貢獻者透過程式碼、文件、翻譯和社羣支援共同打造此程式庫!
我們亦由衷感謝 Hugging Face 社羣所有成員,感謝大家提供意見、錯誤報告和建議,協助塑造這個程式庫。
最後,衷心感謝由個人開發者到大型企業的所有用戶,信任 huggingface_hub 為工作流程提供支援。你們的支持推動我們持續改進和創新。
請在 GitHub 為我們加星 ⭐,表達支持,並協助我們繼續為開放機器學習奠定基礎。五年過去,但這仍只是開始!
來源:Hugging Face Blog · huggingface.co
