Hugging Face 发布 huggingface_hub v1.0，经 35+ 个版本迭代后迈入 1.0 里程碑

TL;DR：经过五年的开发，huggingface_hub 已达到 v1.0——这一里程碑标志着该库作为 Python 包的成熟，它支撑着 200,000 个依赖库，并为访问超过 200 万个公共模型、50 万个公共数据集和 100 万个公共 Spaces 提供核心功能。此版本引入了破坏性变更，旨在支持开放机器学习的下一个十年，由近 300 名贡献者和数百万用户组成的全球社区驱动。

🚀 我们强烈建议升级到 v1.0，以享受重大的性能改进和新功能。

pip install --upgrade huggingface_hub

此版本的主要变更包括：迁移到 httpx 作为后端库，完全重新设计的 hf CLI（取代已弃用的 huggingface-cli），采用基于 Typer 的界面并显著扩展了功能集，以及全面采用 hf_xet 进行文件传输，取代旧的 hf_transfer。您可以在此处找到完整发布说明。

我们努力确保 huggingface_hub v1.0.0 保持向后兼容。实际上，大多数 ML 库应能无缝兼容 v0.x 和 v1.x 版本。主要例外是 transformers，其 v4 版本明确要求 huggingface_hub v0.x，而即将发布的 v5 版本则要求 v1.x。有关各库的详细兼容性概述，请参阅此 issue 中的表格。

库背后的故事

每个重要的库都有一个故事。对于 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 带来了基于令牌的身份验证，实现了对私有仓库和上传的安全访问。这些是 humble 的开端，但它们为后续的一切奠定了基础。

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

2022 年 6 月，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、读取文件或同步文件夹、管理标签、分支和发布周期。仓库元数据和 webhooks 完善了整体能力，让团队可以实时响应变更。

与此同时，Spaces 作为一种简单而强大的方式出现，可以直接在 Hub 上托管和分享交互式 ML 演示。随着时间推移，huggingface_hub 获得了完整的编程控制能力，可以部署和管理 Spaces（硬件请求、密钥、环境配置、上传）。为了在生产级基础设施上部署模型，Inference Endpoints 也被集成进来。最后，Jobs API 在之后（2025 年第三季度）推出，完善了我们的计算能力。

社交和社区层也成为一等公民：从用于拉取请求和评论的 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 PB 的数据。然而它是在完全向后兼容的情况下透明完成的。一年后，超过 6,000,000 个仓库中的全部 77PB+ 数据都已迁移到 Xet 后端，实现了更快（也更智能！）的上传和下载。这一切无需用户干预，也没有中断现有工作流程 🔥

衡量增长与影响

衡量一个开源库的增长和影响是一项棘手的任务。数字本身就能讲述一个故事：

每月 1.135 亿次下载，总计 16 亿次（2025 年 10 月）。
为 200 万+ 个公开模型、50 万+ 个公开数据集、100 万+ 个公开 Spaces 提供访问支持，若计入私有仓库则约为其两倍。
每日有 6 万+ 用户使用，每月 55 万+
受到从初创公司到财富 500 强的 20 万+ 家公司信赖

但真正的规模在审视整个生态系统时才变得清晰。huggingface_hub 是 GitHub 上超过 20 万个仓库和 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 社区，而我们不断为其发展之远、应用之广而感到谦卑。

为下一个十年而构建

1.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 及其支持的数十个推理提供商之上。我们坚信智能体是未来，而 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 现在感觉和任何现代开发者工具一样精致。

为未来清理旧账

1.0 版本移除了阻碍我们前进的旧有模式。基于 Git 的 Repository 类已被移除。基于 HTTP 的方法如 upload_file() 和 create_commit() 更简单、更可靠，也更适合现代工作流。HfFolder 令牌管理已被显式的 login()、logout() 和 get_token() 函数取代。旧的 InferenceApi 类已被功能更完整的 InferenceClient 取代。hf_transfer 已被 hf_xet 二进制包完全替代。

这些改动并非轻率做出。大多数弃用都在数月前提前公布，并附有明确的警告和迁移指南。结果是代码库更干净、更易维护，能够专注于前瞻性功能，而不是支持已弃用的模式。

迁移指南

我们理解破坏性变更会带来不便。因此我们投入了大量精力，让迁移尽可能顺利。我们的全面迁移指南为每项变更提供了分步说明，并解释了每项变更的必要性。

最重要的是，我们在可能的情况下都保持了向后兼容性。例如，HfHubHttpError 同时继承自旧的 requests 和新的 httpx 基类 HTTPError，确保错误处理在各个版本间继续有效。通过此版本，我们完全致力于未来，并将专注于 v1.0 及更高版本，确保我们能够提供社区与 Hugging Face Hub 交互所需的性能、功能和工具。之前的 v0.* 版本仍将在 PyPI 上提供，但只会收到漏洞更新。

我们努力确保 huggingface_hub v1.0.0 保持向后兼容。实际上，大多数 ML 库应能无缝兼容 v0.x 和 v1.x 版本。主要例外是 transformers，其 v4 版本明确要求 huggingface_hub v0.x，而即将发布的 v5 版本则要求 v1.x。有关各库兼容性的详细概览，请参阅此 issue 中的表格。

致谢

感谢我们的 280 多位贡献者，他们通过代码、文档、翻译和社区支持构建了这个库！

我们也深深感谢整个 Hugging Face 社区的反馈、错误报告和建议，它们塑造了这个库。

最后，衷心感谢我们的用户——从个人开发者到大型企业——信任huggingface_hub来驱动你们的工作流程。你们的支持激励我们不断改进和创新。

请在 GitHub 上为我们加星 ⭐，以表示您的支持，并帮助我们继续构建开放机器学习的基础。五年过去了，但这仍然只是开始！