huggingface_hub v1.0 への移行

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

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

Python 3.9以降

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

HTTPXへの移行

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

破壊的変更

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

• プロキシ設定: 「メソッド単位」のプロキシはサポートされなくなりました。プロキシは、HTTP_PROXY および HTTPS_PROXY 環境変数を使用してグローバルに設定する必要があります。
• カスタム HTTP バックエンド: configure_http_backend 関数は削除されました。HTTP クライアントを設定するには、set_client_factory() および set_async_client_factory() を使用してください。
• エラー処理: 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は、コンテキストマネージャーとして使用できるようになりました。これは、言語モデルからトークンをストリーミングする際に、接続が正しく閉じられることを保証するために特に有用です。
• 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 CLI をラップする薄いラッパーでした。ターミナルで 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で削除され、以下の新しい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()およびupload_folder()関数は、現在、Hub上で作成されたコミットのURLを返します。以前は、ファイルまたはフォルダのURLを返していました。これは、create_commit()、delete_file()およびdelete_folder()の戻り値と整合させるためです。

Update on GitHub