# 迁移到 huggingface_hub v1.0

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

本指南旨在帮助您将现有代码迁移到新版本。如果您有任何问题或反馈，请通过[在 GitHub 上提交 issue](https://github.com/huggingface/huggingface_hub/issues)告知我们。

## Python 3.9+

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

## HTTPX 迁移

`huggingface_hub` 库现在使用 [`httpx`](https://www.python-httpx.org/) 而非 `requests` 来处理 HTTP 请求。此更改旨在提升性能，并以相同的方式支持同步和异步请求。因此，我们移除了对 `requests` 和 `aiohttp` 的依赖。

### 破坏性变更

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

- **代理配置**：不再支持“按方法”配置的代理。必须使用 `HTTP_PROXY` 和 `HTTPS_PROXY` 环境变量全局配置代理。
- **自定义 HTTP 后端**：`configure_http_backend` 函数已被移除。现在应使用 [set_client_factory()](/docs/huggingface_hub/v2.4.0/zh/package_reference/utilities#huggingface_hub.set_client_factory) 和 [set_async_client_factory()](/docs/huggingface_hub/v2.4.0/zh/package_reference/utilities#huggingface_hub.set_async_client_factory) 来配置 HTTP 客户端。
- **错误处理**：HTTP 错误不再继承自 `requests.HTTPError`，而是继承自 `httpx.HTTPError`。我们建议捕获 [HfHubHTTPError](/docs/huggingface_hub/v2.4.0/zh/package_reference/utilities#huggingface_hub.errors.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()](/docs/huggingface_hub/v2.4.0/zh/package_reference/utilities#huggingface_hub.set_async_client_factory) 进行配置。

有关更多详细信息，您可以查看引入 `httpx` 的 [PR #3328](https://github.com/huggingface/huggingface_hub/pull/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`](../package_reference/environment_variables)。

## `Repository` 类

`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()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.upload_file)、[upload_folder()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.upload_folder)、[create_commit()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.create_commit) |
| `repo.git_tag`                             | `create_tag`                                          |
| `repo.git_branch`                          | `create_branch`                                       |

## `HfFolder` 类

`HfFolder` 曾用于管理用户访问令牌。使用 [login()](/docs/huggingface_hub/v2.4.0/zh/package_reference/authentication#huggingface_hub.login) 保存新令牌，使用 [logout()](/docs/huggingface_hub/v2.4.0/zh/package_reference/authentication#huggingface_hub.logout) 删除令牌，使用 [whoami()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.whoami) 查看与当前令牌关联的用户。最后，在脚本中使用 `get_token()` 获取用户的令牌。

## `InferenceApi` 类

`InferenceApi` 是一个用于与 Inference API 交互的类。现在建议使用 [InferenceClient](/docs/huggingface_hub/v2.4.0/zh/package_reference/inference_client#huggingface_hub.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()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.upload_file) 和 [upload_folder()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.upload_folder) 函数现在返回在 Hub 上创建的 commit 的 URL。此前，它们返回的是文件或文件夹的 URL。此更改旨在与 [create_commit()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.create_commit)、[delete_file()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.delete_file) 和 [delete_folder()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.delete_folder) 的返回值保持一致。