迁移到 huggingface_hub v1.0

v1.0 版本是 huggingface_hub 库的一个重要里程碑。它标志着我们对 API 稳定性的承诺以及该库的成熟。我们进行了一些改进和破坏性变更，以使该库更加健壮且易于使用。

本指南旨在帮助您将现有代码迁移到新版本。如果您有任何问题或反馈，请通过在 GitHub 上提交 issue告知我们。

Python 3.9+

huggingface_hub 现在需要 Python 3.9 或更高版本。不再支持 Python 3.8。

HTTPX 迁移

huggingface_hub 库现在使用 httpx 而非 requests 来处理 HTTP 请求。此更改旨在提升性能，并以相同的方式支持同步和异步请求。因此，我们移除了对 requests 和 aiohttp 的依赖。

破坏性变更

这是一项影响整个库的重大变更。虽然我们已尽力使该变更尽可能透明，但在某些情况下，您可能需要更新代码。以下是此过程中引入的破坏性变更列表：

代理配置：不再支持“按方法”的代理。必须使用 HTTP_PROXY 和 HTTPS_PROXY 环境变量全局配置代理。
自定义 HTTP 后端：configure_http_backend 函数已被移除。现在应使用 set_client_factory() 和 set_async_client_factory() 来配置 HTTP 客户端。
错误处理：HTTP 错误不再继承自 requests.HTTPError，而是继承自 httpx.HTTPError。我们建议捕获 HfHubHTTPError（通过 from huggingface_hub.utils import HfHubHTTPError 导入），它在 v0.x 中是 requests.HTTPError 的子类，在 v1.x 中是 httpx.HTTPError 的子类。捕获来自 huggingface_hub 的错误可确保您的代码兼容该库的旧版本和新版本。
SSLError：httpx 没有 SSLError 的概念。它现在是一个通用的 httpx.ConnectError。
LocalEntryNotFoundError：此错误不再继承自 HTTPError。我们现在定义了一个新的 EntryNotFoundError，LocalEntryNotFoundError（当本地缓存中未找到文件时）和 RemoteEntryNotFoundError（当 Hub 上的仓库中未找到文件时）均继承自它。只有远程错误继承自 HTTPError。
InferenceClient：InferenceClient 现在可以作为上下文管理器使用。这在从语言模型流式传输 token 时尤为有用，可确保连接被正确关闭。
AsyncInferenceClient：AsyncInferenceClient 的构造函数中已移除 trust_env 参数。httpx 默认信任环境变量。如果您明确不希望信任环境变量，则必须通过 set_async_client_factory() 进行配置。

有关更多详细信息，您可以查看引入 httpx 的 PR #3328。

为什么选择 httpx？

从 requests 迁移到 httpx 带来了多项关键改进，提升了库的性能、可靠性和可维护性：

线程安全与连接复用：httpx 在设计上是线程安全的，因此我们可以安全地在多个线程中复用同一个客户端。这种连接复用减少了为每个 HTTP 请求建立新连接的开销，从而提升了性能，尤其是在频繁向 Hub 发起请求时。

HTTP/2 支持：httpx 提供原生的 HTTP/2 支持，在对同一服务器发起多个请求时效率更高（这正是我们的使用场景）。与 HTTP/1.1 相比，这意味着更低的延迟和更少的资源消耗。

统一的同步/异步 API：与我们之前分别使用 requests（同步）和 aiohttp（异步）依赖项的设置不同，httpx 提供了行为完全一致的同步和异步客户端。这确保了 InferenceClient 和 AsyncInferenceClient 具有功能一致性，并消除了此前两种实现之间存在的细微行为差异。

改进的 SSL 错误处理：httpx 能够更优雅地处理 SSL 错误，使连接问题的调试更加简单可靠。

面向未来的架构：httpx 处于积极维护状态，专为现代 Python 应用设计。相比之下，requests 已进入维护模式，不会获得线程安全性改进或 HTTP/2 支持等重大更新。

更优的环境变量处理：httpx 在同步和异步上下文中对环境变量提供了更一致的处理，消除了之前 requests 默认读取本地环境变量而 aiohttp 不读取的不一致问题。

向 httpx 的迁移使 huggingface_hub 拥有了一个现代、高效且易于维护的 HTTP 后端。虽然大多数用户应能体验到无缝的运行，但底层的改进为所有 Hub 交互提供了更好的性能和可靠性。

hf_transfer

目前，Hub 上的所有仓库均已启用 Xet，且 hf_xet 已成为下载/上传文件的默认方式，因此我们已移除对 hf_transfer 可选包的支持。因此，HF_HUB_ENABLE_HF_TRANSFER 环境变量将被忽略。请改用 HF_XET_HIGH_PERFORMANCE。

仓库类

Repository 类已在 v1.0 中移除。它原本是对 git 命令行接口的一个轻量封装，用于管理仓库。您仍然可以直接在终端中使用 git，但推荐的做法是使用 huggingface_hub 库中基于 HTTP 的 API，以获得更流畅的体验，尤其是在处理大文件时。

以下是从旧版 Repository 类到新版 HfApi 类的映射：

`Repository` 方法	`HfApi` 方法
`repo.clone_from`	`snapshot_download`
`repo.git_add` + `git_commit` + `git_push`	upload_file()、upload_folder()、create_commit()
`repo.git_tag`	`create_tag`
`repo.git_branch`	`create_branch`

HfFolder 类

HfFolder 曾用于管理用户访问令牌。使用 login() 保存新令牌，使用 logout() 删除令牌，使用 whoami() 查看与当前令牌关联的用户。最后，在脚本中使用 get_token() 获取用户的令牌。

InferenceApi 类

InferenceApi 是一个用于与 Inference API 交互的类。现在建议使用 InferenceClient 类。

其他已弃用的功能

v1.0 中已移除了一些方法和参数。以下列出的方法和参数在 v0.x 中已被弃用，并附有警告信息。

constants.hf_cache_home 已被移除。请改用 HF_HOME。
use_auth_token 参数已从所有方法中移除。请改用 token。
get_token_permission 方法已被移除。
update_repo_visibility 方法已被移除。请改用 update_repo_settings。
is_write_action 参数已从 build_hf_headers 中移除，write_permission 也已从 login 中移除。“写入权限”这一概念已被移除，在细粒度令牌成为推荐方法后，它已不再相关。
login 中的 new_session 参数已重命名为 skip_if_logged_in，以提高清晰度。
resume_download、force_filename 和 local_dir_use_symlinks 参数已从 hf_hub_download 和 snapshot_download 中移除。
library、language、tags 和 task 参数已从 list_models 中移除。

CLI 缓存命令

通过 CLI 进行的缓存管理已重新设计，以遵循受 Docker 启发的工作流程。已弃用的 huggingface-cli 已被移除，hf（在 v0.34 中引入）取而代之，提供了一个更清晰的资源-操作 CLI。旧版的 hf cache scan 和 hf cache delete 命令也在 v1.0 中被移除，并由以下新的三个命令取代：

hf cache ls 以简洁的表格、JSON 或 CSV 格式列出缓存条目。使用 --revisions 可检查各个修订版本，添加 --filter 表达式（例如 size>1GB 或 accessed>30d），并在仅需标识符时与 --quiet 结合使用。
hf cache rm 用于删除选定的缓存条目。请传入一个或多个仓库 ID（例如 model/bert-base-uncased）或修订哈希值，并可选择添加 --dry-run 以预览操作，或添加 --yes 以跳过确认提示。此命令取代了之前命令中的交互式 TUI 和 --disable-tui 工作流。
hf cache prune 可一次性执行常见的清理任务，即删除未引用的修订版本。与 hf cache rm 一样，添加 --dry-run 或 --yes 即可。

最后，[cli] 附加组件已被移除 - CLI 现在随核心 huggingface_hub 包一起发布。

TensorFlow 和 Keras 2.x 支持

v1.0 中已移除所有与 TensorFlow 相关的代码和依赖项。其中包括以下破坏性变更：

huggingface_hub[tensorflow] 不再受支持的额外依赖项
split_tf_state_dict_into_shards 和 get_tf_storage_size 实用函数已被移除。
tensorflow、fastai 和 fastcore 版本不再包含在内置头文件中。

Keras 2.x 集成也已被移除。这包括 KerasModelHubMixin 类以及 save_pretrained_keras、from_pretrained_keras 和 push_to_hub_keras 工具。Keras 2.x 是一个已弃用且不再维护的库。推荐的做法是使用与 Hub 紧密集成的 Keras 3.x（即它包含内置的加载/推送到 Hub 的方法）。如果您仍希望使用 Keras 2.x，应将 huggingface_hub 降级到 v0.x 版本。

upload_file 和 upload_folder 的返回值

upload_file() 和 upload_folder() 函数现在返回在 Hub 上创建的 commit 的 URL。此前，它们返回的是文件或文件夹的 URL。此更改旨在与 create_commit()、delete_file() 和 delete_folder() 的返回值保持一致。

Update on GitHub

Hub Python Library