huggingface_hub v1.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 上分享代码一样简单呢？

在 HF Mirror Hub 的早期，研究人员和实践者面临一个共同的困扰。训练最先进的模型需要大量的计算资源和专业知识。一旦训练完成，这些模型往往孤立存在，存储在本地机器上，并通过（失效的）Google Drive 链接分享。AI 社区在重复劳动，浪费资源，错失协作机会。

HF Mirror Hub 应运而生，成为这一挑战的答案。最初，它主要用于分享与 transformers 库兼容的检查点。与 Hub 交互的所有 Python 代码都存在于该库中，其他库无法重用。

2020 年底，我们发布了 huggingface_hub v0.0.1，其简单使命是：从 transformers 中提取内部逻辑，并创建一个专用库，统一在 HF Mirror Hub 上访问和分享机器学习模型与数据集的方式。最初，这个库就像是一个用于下载文件和管理仓库的 Git 包装器。五年间，经过 35 多次发布，huggingface_hub 已远远超越其起源。

让我们回顾那段旅程。

奠基之年（2020-2021）

早期版本确立了基础。版本 0.0.8 引入了我们的首个 API，封装 Git 命令以与仓库交互。版本 0.0.17 带来了基于令牌的身份验证，实现了对私有仓库的安全访问和上传。这些是谦卑的开端，但它们为后续的一切奠定了基础。

伟大转变：从 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 和提交、读取文件或同步文件夹、管理标签、分支和发布周期。仓库元数据和 webhook 也补齐了整个体系，让团队能够实时响应变更。

与此同时，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 万+个公共 Space 提供支持，若计入私有仓库则约为其两倍。
每日有 6 万+名用户使用，每月 55 万+
受到从初创公司到财富 500 强的 20 万+ 家公司信赖

但当你审视整个生态系统时，真正的规模才变得清晰。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 等）也受益于这一基础。

最引人注目的是什么？大多数第三方集成都是自发发生的，我们并未参与其中。HF Mirror 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 让 Agent 变得简单

0.32.0 版本引入了模型上下文协议（MCP）集成和 tiny-agents，从根本上改变了开发者构建 AI agent 的方式。过去需要复杂框架集成的工作，现在只需约 70 行 Python 代码。

MCPClient 为 AI agent 提供了一种与工具交互的标准化方式，而 tiny-agents CLI 让你可以直接从 Hub 运行 agent。连接到本地或远程 MCP 服务器，使用任何 Gradio Space 作为工具，构建自然且响应迅速的对话式 agent。

所有这些都构建在我们现有的InferenceClient及其支持的数十个 Inference Providers 之上。我们确实相信 Agents 是未来，而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类已被移除。像upload_file()和create_commit()这样基于 HTTP 的方法更简单、更可靠，也更适合现代工作流。HfFolder令牌管理已被显式的login()、logout()和get_token()函数所取代。旧的InferenceApi类已被功能更完整的InferenceClient所取代。hf_transfer已被hf_xet二进制包完全替代。

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

迁移指南

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

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

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

致谢

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

我们也深深感谢整个 HF Mirror 社区的反馈、错误报告和建议，正是这些塑造了这个库。

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

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