HuggingFace Hubのルートロガーの現在のレベルを返します。

HuggingFace Hubには、以下のログレベルがあります。

• huggingface_hub.logging.CRITICAL, huggingface_hub.logging.FATAL
• huggingface_hub.logging.ERROR
• huggingface_hub.logging.WARNING, huggingface_hub.logging.WARN
• huggingface_hub.logging.INFO
• huggingface_hub.logging.DEBUG

HuggingFace Hubのルートロガーのレベルを設定します。

冗長性をlogging.INFOに設定します。

冗長度をlogging.DEBUGに設定します。

冗長性をlogging.WARNINGに設定します。

冗長性をlogging.ERRORに設定します。

ライブラリのログ出力の伝播を無効にします。なお、ログの伝播はデフォルトで無効になっています。

ライブラリのログ出力の伝播を有効にします。ルートロガーが設定されている場合、重複ログを防ぐために HuggingFace Hub のデフォルトハンドラーを無効にしてください。

指定された名前のロガーを返します。この関数は、ライブラリのユーザーが直接アクセスすることを想定していません。

>>> from huggingface_hub import logging

>>> logger = logging.get_logger(__name__)
>>> logging.set_verbosity_info()

進捗バーがグローバルで無効化されているか、特定のグループに対して無効化されているかを確認します。

この関数は、指定されたグループまたはグローバルでプログレスバーが無効化されているかどうかを返します。 まずHF_HUB_DISABLE_PROGRESS_BARS環境変数をチェックし、次にプログラマティックな設定を調べます。

進捗バーをグローバルで、または指定されたグループに対して無効にします。

この関数は、グループ名に基づいてプログレスバーの状態を更新します。 グループ名が指定されない場合、すべてのプログレスバーが無効になります。この操作は、HF_HUB_DISABLE_PROGRESS_BARS 環境変数の設定を尊重します。

通常の呼び出しとコンテキストマネージャーの両方として機能します: disable_progress_bars() # enable_progress_bars() が呼ばれるまで無効化 with disable_progress_bars(): # ブロック内では無効化し、終了時に再有効化 …

進捗バーをグローバルで、または指定されたグループに対して有効にします。

この関数は、指定されたグループ、またはグループが指定されていない場合はグローバルに、プログレスバーを有効に設定します。この操作は、HF_HUB_DISABLE_PROGRESS_BARS環境設定の対象となります。

huggingface_hubで使用するHTTPクライアントファクトリを設定します。

クライアントファクトリは、httpx2.Clientオブジェクトを返すメソッドです。get_session()が初めて呼び出されたとき、クライアントファクトリが使用されて新しいhttpx2.Clientオブジェクトが作成され、huggingface_hubによるすべての呼び出しで共有されます。

スクリプトを、カスタム設定（カスタムプロキシや証明書など）を必要とする特定の環境で実行する場合に、この機能は役立ちます。

httpx2.Client を正しく設定するために、get_session() を使用します。

ユーザーのトランスポートファクトリを使用して、httpx2.Clientオブジェクトを取得します。

このクライアントは、huggingface_hub によって行われるすべての呼び出しで共有されます。そのため、手動で閉じないでください。

httpx2.Clientをカスタマイズするには、set_client_factory()を使用します。

huggingface_hubで使用されているグローバルのhttpx2.Clientを閉じます。

Client がクローズされている場合、get_session() の次の呼び出し時に再作成されます。

SSL証明書が更新された場合などに有用です。

huggingface_hubで使用するHTTP非同期クライアントファクトリを設定します。

非同期クライアントファクトリは、httpx2.AsyncClientオブジェクトを返すメソッドです。 スクリプトを、カスタム設定（カスタムプロキシや証明書など）を必要とする特定の環境で実行する場合に、この機能は役立ちます。 正しく設定されたhttpx2.AsyncClientを取得するには、get_async_session()を使用してください。

huggingface_hub によるすべての呼び出しで共有される httpx2.Client とは異なり、httpx2.AsyncClient は共有されません。 コンテキストが終了した際にクライアントが適切に閉じられるようにするため、非同期コンテキストマネージャーの使用を推奨します。

ユーザーのトランスポートファクトリを使用して、httpx2.AsyncClientオブジェクトを返します。

httpx2.AsyncClientをカスタマイズするには、set_async_client_factory()を使用します。

huggingface_hub によるすべての呼び出しで共有される httpx2.Client とは異なり、httpx2.AsyncClient は共有されません。 コンテキストが終了した際にクライアントが適切に閉じられるようにするため、非同期コンテキストマネージャーの使用を推奨します。

response.raise_for_status() の内部バージョンで、潜在的な HTTPError を詳細化します。 例外として送出されるのは HfHubHTTPError のインスタンスです。

This helper is meant to be the unique method to raise_for_status when making a call to the Hugging Face Hub.

リクエストが失敗した場合に発生します:

• RepositoryNotFoundError ダウンロード元のリポジトリが見つからない場合に発生します。リポジトリが存在しない、repo_type が正しく設定されていない、リポジトリがprivateでアクセス権限がないなどの理由が考えられます。
• GatedRepoError リポジトリが存在するが、ゲート付きであり、ユーザーが承認リストに含まれていない場合に発生します。
• RevisionNotFoundError リポジトリは存在するが、リビジョンが見つからない場合に発生します。
• EntryNotFoundError リポジトリは存在するが、エントリ（要求されたファイルなど）が見つからない場合。
• BadRequestError リクエストが HTTP 400 BadRequest エラーで失敗した場合。
• HfHubHTTPError 上記に列挙されていない理由でリクエストが失敗した場合。

Hubのオフラインモードかどうかを返します。

オフラインモードが有効な場合、get_sessionを使用して行われるすべてのHTTPリクエストでOfflineModeIsEnabled例外が発生します。

from huggingface_hub import is_offline_mode

def list_files(repo_id: str):
    if is_offline_mode():
        ... # list files from local cache (degraded experience but still functional)
    else:
        ... # list files from Hub (complete experience)

HF Hub で発生するカスタム HTTP エラー用に継承するための HTTPError。

すべての HTTPError は、少なくとも HfHubHTTPError に変換されます。サーバーから情報が返された場合、その情報はエラーメッセージに追加されます。

追加の詳細:

• リクエストIDは、優先順位に従ってヘッダーから取得されます: “X-Request-Id”、“X-Amzn-Trace-Id”、“X-Amz-Cf-Id”。
• ヘッダー「X-Error-Message」からのサーバーエラーメッセージ。
• レスポンスボディ内で見つかった場合のサーバーエラーメッセージ。

    import httpx2
    from huggingface_hub.utils import get_session, hf_raise_for_status, HfHubHTTPError

    response = get_session().post(...)
    try:
        hf_raise_for_status(response)
    except HfHubHTTPError as e:
        print(str(e)) # formatted message
        e.request_id, e.server_message # details returned by server

        # Complete the error message with additional information once it's raised
        e.append_to_message("
ate_commit` expects the repository to exist.")
        raise

無効なリポジトリ名で hf.co の URL にアクセスしようとした場合、またはユーザーがアクセス権限を持たないプライベートリポジトリ名でアクセスしようとした場合に発生します。

>>> from huggingface_hub import model_info
>>> model_info("<non_existent_repository>")
(...)
huggingface_hub.errors.RepositoryNotFoundError: 401 Client Error. (Request ID: PvMw_VjBMjVdMz53WKIzP)

Repository Not Found for url: https://huggingface.co/api/models/%3Cnon_existent_repository%3E.
Please make sure you specified the correct `repo_id` and `repo_type`.
If the repo is private, make sure you are authenticated and your token has the required permissions.
Invalid username or password.

ユーザーが承認リストに含まれていないゲート付きリポジトリにアクセスしようとした際に発生します。

注: 後方互換性を確保するために、RepositoryNotFoundErrorを継承しています。

>>> from huggingface_hub import model_info
>>> model_info("<gated_repository>")
(...)
huggingface_hub.errors.GatedRepoError: 403 Client Error. (Request ID: ViT1Bf7O_026LGSQuVqfa)

Cannot access gated repo for url https://huggingface.co/api/models/ardent-figment/gated-model.
Access to model ardent-figment/gated-model is restricted and you are not in the authorized list.
Visit https://huggingface.co/ardent-figment/gated-model to ask for access.

有効なリポジトリを持つが、無効なリビジョンの hf.co URL にアクセスしようとした際に発生します。

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', 'config.json', revision='<non-existent-revision>')
(...)
huggingface_hub.errors.RevisionNotFoundError: 404 Client Error. (Request ID: Mwhe_c3Kt650GcdKEFomX)

Revision Not Found for url: https://huggingface.co/bert-base-cased/resolve/%3Cnon-existent-revision%3E/config.json.

リビジョンをコミットハッシュに解決できない場合に、HfApi.resolve_revision() によって発生します。Hub にアクセスできなかった（オフラインモード、接続エラー、タイムアウト、Hub の停止など）こと、かつローカルキャッシュに一致するエントリが見つからなかったことを示します。

サーバーが HTTP 400 エラーを返した際に、hf_raise_for_status によって発生します。

>>> resp = httpx2.post("hf.co/api/check", ...)
>>> hf_raise_for_status(resp, endpoint_name="check")
huggingface_hub.errors.BadRequestError: Bad request for check endpoint: {details} (Request ID: XXX)

ローカルでもリモートでもエントリが見つからない場合に発生します。

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-existent-file>')
(...)
huggingface_hub.errors.RemoteEntryNotFoundError (...)
>>> hf_hub_download('bert-base-cased', '<non-existent-file>', local_files_only=True)
(...)
huggingface_hub.utils.errors.LocalEntryNotFoundError (...)

有効なリポジトリとリビジョンを持つ hf.co の URL にアクセスしようとした際に、ファイル名が無効な場合に発生します。

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-existent-file>')
(...)
huggingface_hub.errors.EntryNotFoundError: 404 Client Error. (Request ID: 53pNl6M0MxsnG5Sw8JA6x)

Entry Not Found for url: https://huggingface.co/bert-base-cased/resolve/main/%3Cnon-existent-file%3E.

ネットワークが無効または利用不可（接続の問題）の場合、ディスク上に存在しないファイルやスナップショットへのアクセスを試みた際に発生します。そのエントリは Hub 上に存在する可能性があります。

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-cached-file>',  local_files_only=True)
(...)
huggingface_hub.errors.LocalEntryNotFoundError: Cannot find the requested files in the disk cache and outgoing traffic has been disabled. To enable hf.co look-ups and downloads online, set 'local_files_only' to False.

Hubにアクセスできない場合（オフライン、接続の問題、またはlocal_files_only=True）かつ、キャッシュされたスナップショットが不完全であることが既知の場合に、snapshot_download()によって発生します。リポジトリのキャッシュされたツリー一覧に列挙されている一部のファイルが、ローカルスナップショットから欠落しています。

これは後方互換性のために用意されたLocalEntryNotFoundErrorのサブクラスです。

snapshot_path 属性は、不完全なローカルスナップショットへのパスを保持します。これにより、下流のライブラリは、ファイルが不完全であることが既知であっても、最新のキャッシュ済みファイルを特定できます。

要求されたリビジョンのツリー一覧がキャッシュされていない場合に、get_cached_repo_tree()によって発生します。

snapshot_download() の副作用として、ツリーの一覧が生成されます。

リクエストが行われたが、環境変数としてHF_HUB_OFFLINE=1が設定されている場合に発生します。

異なるHFライブラリの使用状況をトラッキングするために役立つテレメトリを送信します。

この使用データは、問題のデバッグや新機能の優先順位付けに役立ちます。ただし、すべてのユーザーが追加情報を共有したいわけではないことを理解しており、プライバシーを尊重しています。HF_HUB_DISABLE_TELEMETRY=1 を環境変数として設定することで、テレメトリの収集を無効にできます。オフラインモード（HF_HUB_OFFLINE=1 を設定した場合）でも、テレメトリは無効になります。

テレメトリの収集は、ユーザーへの影響を最小限に抑えるため、別スレッドで実行されます。

>>> from huggingface_hub.utils import send_telemetry

# Send telemetry without library information
>>> send_telemetry("ping")

# Send telemetry to subtopic with library information
>>> send_telemetry("gradio/local_link", library_name="gradio", library_version="3.22.1")

# Send telemetry with additional data
>>> send_telemetry(
...     topic="examples",
...     library_name="transformers",
...     library_version="4.26.0",
...     user_agent={"pipeline": "text_classification", "framework": "flax"},
... )

huggingface_hubの公開メソッドの引数として受け取られた値を検証します。

このデコレータの目的は、あらゆる場所で再利用される引数の検証を統一することです。デフォルトでは、定義されたすべてのバリデータがテストされます。

バリデータ:

• validate_repo_id(): repo_id は "repo_name" または "namespace/repo_name" である必要があります。Namespace はユーザー名または組織名です。
• ~utils.smoothly_deprecate_legacy_arguments: ファイルのダウンロード時にproxiesを無視します（グローバルに設定されるべきです）。

>>> from huggingface_hub.utils import validate_hf_hub_args

>>> @validate_hf_hub_args
... def my_cool_method(repo_id: str):
...     print(repo_id)

>>> my_cool_method(repo_id="valid_repo_id")
valid_repo_id

>>> my_cool_method("other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

>>> my_cool_method(repo_id="other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

huggingface_hubのバリデータによってスローされる汎用の例外です。

ValueErrorを継承します。

repo_id が有効であることを検証します。

これは、Hub上で行われる正式なバリデーションに代わるものではなく、可能な限りローカルでの不整合を回避するためのものです（例：repo_idにrepo_typeを渡すことは禁止されています）。

ルール:

• 1文字以上96文字以下。
• “repo_name”または“namespace/repo_name”
• [a-zA-Z0-9] または ”-”、”_”、”.”
• “—”と“..”は禁止されています

有効: "foo"、"foo/bar"、"123"、"Foo-BAR_foo.bar123"

無効な例: "datasets/foo/bar"、".repo_id"、"foo--bar"、"foo.git"

>>> from huggingface_hub.utils import validate_repo_id
>>> validate_repo_id(repo_id="valid_repo_id")
>>> validate_repo_id(repo_id="other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

https://github.com/huggingface/huggingface_hub/issues/1008 で議論されました。 moon-landing（内部リポジトリ）では：

• https://github.com/huggingface/moon-landing/blob/main/server/lib/Names.ts#L27
• https://github.com/huggingface/moon-landing/blob/main/server/views/components/NewRepoForm/NewRepoForm.svelte#L138

huggingface_hubのコードベースにおいて、レガシー引数をスムーズに非推奨化します。

この関数は、kwargs 内の非推奨の引数を無視し、それらが無視されることをユーザーに警告します。 既存のコードを壊さずに、ユーザーを新しい方法へと導くことが目的です。

非推奨引数のリスト:

• proxies: プロキシを設定するには、ユーザーは HTTP_PROXY 環境変数を使用するか、set_client_factory() 関数を使用して httpx2.Client を手動で設定する必要があります。

  huggingface_hub 0.x では、proxies は requests.request に直接渡される辞書でした。 huggingface_hub 1.x 以降、リクエストごとの proxies はサポートされなくなりました。 具体的には、リクエストごとにプロキシを設定することはできません。解決策として、set_client_factory() 関数または HTTP_PROXY 環境変数を使用して、グローバルに設定してください。

  詳細については、以下を参照してください:

  • https://httpx2.pydantic.dev/advanced/proxies/

• resume_download: 代替手段なしで非推奨になりました。huggingface_hub は、可能な限り常にダウンロードを再開します。

• force_filename: 代替なしで非推奨になりました。ファイル名は常に Hub 上のものと同じです。

• local_dir_use_symlinks: 代替手段なしで非推奨になりました。ローカルディレクトリへのダウンロードは、シンボリックリンクを使用しなくなりました。