huggingface_hub v1.0：五年构建开放机器学习基础

TL;DR: 经过五年的开发，huggingface_hub 已达到 v1.0——这一里程碑标志着该库作为 Python 包的成熟度，支撑着 200,000 个依赖库，并提供访问超过 200 万公共模型、50 万公共数据集和 100 万公共 Spaces 的核心功能。本次发布引入了旨在支持下一个十年开放机器学习的破坏性变更，由近 300 位贡献者和数百万用户的全球社区推动。 🚀 我们强烈建议升级到 v1.0，以受益于显著的性能提升和新功能。

库背后的故事

该库从 2020 年的一个简单 Git 包装器演变为支撑 Hugging Face Hub 的成熟基础，历时五年。

基础年代（2020-2021）

早期版本奠定了基础：版本 0.0.8 引入了首批包装 Git 命令的 API，版本 0.0.17 为私有仓库和上传添加了基于令牌的身份验证。

巨大转变：从 Git 到 HTTP（2022）

2022 年 6 月，版本 0.8.1 引入了 HTTP Commit API，允许通过 HTTP 上传文件而无需 Git LFS，并添加了跨库共享的 git 感知缓存布局。

API 范围扩展（2022–2024）

随着 Hub 的增长，库添加了用于仓库元数据、webhook、Spaces 管理、推理端点、作业 API、社区功能（如拉取请求和评论）以及按请求付费推理的 Inference Providers 的基础功能。

准备。Xet。出发！（2024-2025）

版本 0.30.0 引入了 Xet，一种块级存储协议；迁移在超过 6,000,000 个仓库之间透明地移动了 77PB+ 数据，实现了更快的上传和下载。

衡量增长与影响

该库如今被广泛采用，支撑数百万模型，服务于数十万用户和公司。

  • 每月下载量 1.135 亿，累计 16 亿（2025 年 10 月）。
  • 支撑访问 200 万以上的公共模型、50 万以上的公共数据集、100 万以上的公共 Spaces（以及私有副本）。
  • 拥有 60,000+ 日活用户，550,000+ 月活用户。
  • 受到 200,000+ 公司信任，涵盖初创企业到《财富》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() 现已成为标准。
  • 令牌管理从 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