Hub Python Library documentation
迁移到 huggingface_hub v1.0
迁移到 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