# huggingface_hub v1.0 への移行

v1.0 のリリースは、`huggingface_hub` ライブラリにとって大きなマイルストーンです。これは、API の安定性とライブラリの成熟に対する私たちのコミットメントを示しています。ライブラリをより堅牢で使いやすくするために、いくつかの改善と破壊的変更（breaking changes）を行いました。

このガイドは、既存のコードを新しいバージョンに移行する際に役立てていただくことを目的としています。ご質問やフィードバックがございましたら、[GitHubでissueを作成する](https://github.com/huggingface/huggingface_hub/issues)ことでお知らせください。

## Python 3.9以降

`huggingface_hub`はPython 3.9以降を必要とします。Python 3.8はサポートされなくなりました。

## HTTPXへの移行

`huggingface_hub` ライブラリは、HTTP リクエストに `requests` の代わりに [`httpx`](https://www.python-httpx.org/) を使用するようになりました。この変更は、パフォーマンスを向上させ、同期リクエストと非同期リクエストを同じ方法でサポートするために実施されました。そのため、`requests` と `aiohttp` の両方の依存関係を削除しました。

### 破壊的変更

これはライブラリ全体に影響する大きな変更です。可能な限り透明性を保つよう努めていますが、場合によってはコードの更新が必要になる可能性があります。この過程で導入された破壊的変更（breaking changes）の一覧は以下の通りです：

- **プロキシ設定**: 「メソッド単位」のプロキシはサポートされなくなりました。プロキシは、`HTTP_PROXY` および `HTTPS_PROXY` 環境変数を使用してグローバルに設定する必要があります。
- **カスタム HTTP バックエンド**: `configure_http_backend` 関数は削除されました。HTTP クライアントを設定するには、[set_client_factory()](/docs/huggingface_hub/v2.4.0/ja/package_reference/utilities#huggingface_hub.set_client_factory) および [set_async_client_factory()](/docs/huggingface_hub/v2.4.0/ja/package_reference/utilities#huggingface_hub.set_async_client_factory) を使用してください。
- **エラー処理**: HTTP エラーは `requests.HTTPError` からではなく、`httpx.HTTPError` から継承されるようになりました。[HfHubHTTPError](/docs/huggingface_hub/v2.4.0/ja/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`は、コンテキストマネージャーとして使用できるようになりました。これは、言語モデルからトークンをストリーミングする際に、接続が正しく閉じられることを保証するために特に有用です。
- **`AsyncInferenceClient`**: `AsyncInferenceClient`のコンストラクタから`trust_env`パラメータが削除されました。`httpx`では、環境変数がデフォルトで信頼されます。環境を明示的に信頼したくない場合は、[set_async_client_factory()](/docs/huggingface_hub/v2.4.0/ja/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` CLI をラップする薄いラッパーでした。ターミナルで `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/ja/package_reference/hf_api#huggingface_hub.HfApi.upload_file)、[upload_folder()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.upload_folder)、[create_commit()](/docs/huggingface_hub/v2.4.0/ja/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/ja/package_reference/authentication#huggingface_hub.login)を、削除するには[logout()](/docs/huggingface_hub/v2.4.0/ja/package_reference/authentication#huggingface_hub.logout)を、現在のトークンに関連付けられたユーザーを確認するには[whoami()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.whoami)を使用します。最後に、スクリプト内でユーザーのトークンを取得するには`get_token()`を使用します。

## `InferenceApi` クラス

`InferenceApi` は、Inference API と対話するためのクラスでした。現在は、代わりに [InferenceClient](/docs/huggingface_hub/v2.4.0/ja/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で削除され、以下の新しい3つのコマンドに置き換えられます。

- `hf cache ls` は、キャッシュエントリを簡潔なテーブル、JSON、または CSV 形式で一覧表示します。個別のリビジョンを確認するには `--revisions` を使用し、`size>1GB` や `accessed>30d` のような `--filter` 式を追加できます。識別子のみが必要な場合は、`--quiet` と組み合わせて使用してください。
- `hf cache rm` は、選択したキャッシュエントリを削除します。1 つ以上のリポジトリ 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のサポート

TensorFlow関連のコードおよび依存関係はすべてv1.0で削除されました。これには、以下の破壊的変更が含まれます。

- `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/ja/package_reference/hf_api#huggingface_hub.HfApi.upload_file)および[upload_folder()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.upload_folder)関数は、現在、Hub上で作成されたコミットのURLを返します。以前は、ファイルまたはフォルダのURLを返していました。これは、[create_commit()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.create_commit)、[delete_file()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.delete_file)および[delete_folder()](/docs/huggingface_hub/v2.4.0/ja/package_reference/hf_api#huggingface_hub.HfApi.delete_folder)の戻り値と整合させるためです。