Hub Python Library documentation
HfApi クライアント
HfApi クライアント
以下は、Hugging Face Hub の API の Python ラッパーとして機能する HfApi クラスのドキュメントです。
HfApiのすべてのメソッドは、パッケージのルートから直接アクセスすることもできます。両方のアプローチについて、以下に詳しく説明します。
ルートメソッドを使用する方がよりシンプルですが、HfApiクラスの方がより柔軟性があります。
特に、すべてのHTTP呼び出しで再利用されるトークンを渡すことができます。これはhf auth loginやlogin()とは異なり、トークンはマシン上に永続化されません。
また、別のエンドポイントを指定したり、カスタムのユーザーエージェントを設定したりすることも可能です。
from huggingface_hub import HfApi, list_models
# Use root method
models = list_models()
# Or configure a HfApi client
hf_api = HfApi(
endpoint="https://huggingface.co", # Can be a Private Hub endpoint.
token="hf_xxx", # Token is not persisted on the machine.
)
models = hf_api.list_models()HfApi
クラス huggingface_hub.HfApi
< source >( endpoint: str | None = Nonetoken: str | bool | None = Nonelibrary_name: str | None = Nonelibrary_version: str | None = Noneuser_agent: dict | str | None = Noneheaders: dict[str, str] | None = None )
パラメータ
- endpoint (
str, 省略可) — Hub のエンドポイントです。デフォルト値は https://huggingface.co です。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - library_name (
str, オプション) — HTTP リクエストを発行するライブラリの名前です。user-agent ヘッダーに追加されます。例:"transformers"。 - library_version (
str、省略可) — HTTP リクエストを発行するライブラリのバージョンです。user-agent ヘッダーに追加されます。例:"4.24.0"。 - user_agent (
str,dict, 省略可) — 辞書または単一の文字列形式のユーザーエージェント情報です。インストールされているパッケージに関する情報で補完されます。 - headers (
dict, 任意) — 各リクエストに送信する追加のヘッダーです。例:{"X-My-Header": "value"}。 ここで渡されたヘッダーは、デフォルトのヘッダーよりも優先されます。
HTTP経由でHugging Face Hubとやり取りするためのクライアント。
クライアントは、Hub（HF エンドポイント、認証、ユーザーエージェントなど）へのすべてのリクエストで使用する上位の設定で初期化されます。HfApiクライアントの使用が推奨されますが、必須ではありません。huggingface_hubのルートに、そのすべての公開メソッドが直接公開されているためです。
accept_access_request
< source >( repo_id: struser: str | None = Nonerequest_id: str | None = Nonerepo_type: str | None = Nonetoken: bool | str | None = None )
パラメータ
- repo_id (
str) — アクセス要求を受け入れるリポジトリのID。 - user (
str, 任意) — アクセス要求を受け入れるユーザーのユーザー名です。userとrequest_idのうち、正確に1つを指定する必要があります。 - request_id (
str, 省略可) — 承認するアクセスリクエストの ID（AccessRequestを参照）。リポジトリがリクエスト送信者のユーザー名を共有しないように設定されている場合に必須です。userとrequest_idのうち、ちょうど 1 つを指定する必要があります。 - repo_type (
str, 省略可) — アクセス要求を受け入れるリポジトリの種類です。model、dataset、spaceのいずれかである必要があります。 デフォルトはmodelです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
例外
HfHubHTTPError
HfHubHTTPError— リポジトリがゲート付きでない場合、HTTP 400 が返されます。HfHubHTTPError— リポジトリへのアクセス権限が読み取り専用の場合、HTTP 403 が返されます。リポジトリが属する組織でwriteまたはadminのロールを持っていない場合、またはreadトークンを渡した場合に、この状況が発生し得ます。HfHubHTTPError— ユーザーが Hub に存在しない場合、HTTP 404 が返されます。HfHubHTTPError— ユーザーのアクセスリクエストが見つからない場合、HTTP 404 が返されます。HfHubHTTPError— ユーザーのアクセスリクエストが既に承認リストに含まれている場合、HTTP 404 が返されます。
指定されたゲート付きリポジトリに対するユーザーのアクセス要求を受け入れます。
リクエストが承認されると、ユーザーはリポジトリ内の任意のファイルをダウンロードし、コミュニティタブにアクセスできるようになります。承認モードが自動の場合、リクエストを手動で承認する必要はありません。承認されたリクエストは、cancel_access_request()およびreject_access_request()を使用して、いつでもキャンセルまたは拒否できます。
ゲート付きリポジトリの詳細については、https://huggingface.co/docs/hub/models-gatedを参照してください。
add_collection_item
< source >( collection_slug: stritem_id: stritem_type: CollectionItemType_Tnote: str | None = Noneexists_ok: bool = Falsetoken: bool | str | None = None )
パラメータ
- collection_slug (
str) — 更新するコレクションのスラッグです。例:"TheBloke/recent-models-64f9a55bb3115b4f513ec026"。 - item_id (
str) — コレクションに追加するアイテムの ID。リポジトリ/スペース/データセットには repo_id、論文には論文 ID、別のコレクションのスラグ（例:"moonshotai/kimi-k2"）、またはバケット ID（例:"namespace/bucket-name"）を使用します。 - item_type (
str) — 追加するアイテムの種類。"model"、"dataset"、"space"、"paper"、"collection"、または"bucket"のいずれかです。 - note (
str, 任意) — コレクション内のアイテムに付与するメモです。メモの最大サイズは500文字です。 - exists_ok (
bool, 省略可) —Trueの場合、アイテムが既に存在していてもエラーを発生させません。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
例外
HfHubHTTPError
HfHubHTTPError— リポジトリへのアクセス権限が読み取り専用の場合、HTTP 403 が返されます。リポジトリが属する組織でwriteまたはadminのロールを持っていない場合、またはreadトークンを渡した場合に、この状況が発生し得ます。HfHubHTTPError— コレクションに追加しようとしたアイテムが Hub に存在しない場合、HTTP 404 が返されます。HfHubHTTPError— コレクションに追加しようとしたアイテムが既にコレクションに存在する場合（かつ exists_ok=False の場合）、HTTP 409 が返されます
Hub上のコレクションにアイテムを追加します。
戻り値: Collection
例:
>>> from huggingface_hub import add_collection_item
>>> collection = add_collection_item(
... collection_slug="davanstrien/climate-64f99dc2a5067f6b65531bab",
... item_id="pierre-loic/climate-news-articles",
... item_type="dataset"
... )
>>> collection.items[-1].item_id
"pierre-loic/climate-news-articles"
# ^item got added to the collection on last position
# Add item with a note
>>> add_collection_item(
... collection_slug="davanstrien/climate-64f99dc2a5067f6b65531bab",
... item_id="datasets/climate_fever",
... item_type="dataset",
... note="This dataset adopts the FEVER methodology that consists of 1,535 real-world claims regarding climate-change collected on the internet."
... )
(...)add_space_secret
< source >( repo_id: strkey: strvalue: strdescription: str | None = Nonetoken: bool | str | None = None )
パラメータ
- repo_id (
str) — 更新するリポジトリの ID。例:"bigcode/in-the-stack"。 - key (
str) — シークレットキー。例:"GITHUB_API_KEY" - value (
str) — シークレットの値。例:"your_github_api_key"。 - description (
str, 任意) — シークレットの説明。例:"Github API key to access the Github API"。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
Spaceにシークレットを追加または更新します。
Secretsを使用すると、Spaceにシークレットキーやトークンを設定できますが、ハードコードする必要はありません。 詳細については、https://huggingface.co/docs/hub/spaces-overview#managing-secretsを参照してください。
add_space_variable
< source >( repo_id: strkey: strvalue: strdescription: str | None = Nonetoken: bool | str | None = None )
パラメータ
- repo_id (
str) — 更新するリポジトリの ID。例:"bigcode/in-the-stack"。 - key (
str) — 変数のキー。例:"MODEL_REPO_ID" - value (
str) — 変数の値。例:"the_model_repo_id"。 - description (
str) — 変数の説明です。例:"Model Repo ID of the implemented model"。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
Space内の変数を追加または更新します。
Variables を使用すると、Space にハードコードせずに環境変数を設定できます。 詳細については、https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables を参照してください。
auth_check
< source >( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = Nonewrite: bool = False )
パラメータ
- repo_id (
str) — アクセスを確認するリポジトリです。形式は"user/repo_name"である必要があります。 例:"user/my-cool-model"。 - repo_type (
str, 省略可) — リポジトリの種類。"model"、"dataset"、または"space"のいずれかである必要があります。 指定しない場合、デフォルトは"model"です。 - token (
Union[bool, str, None], 省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。 - write (
bool、省略可) —Trueの場合、ユーザーがリポジトリに対してコンテンツの書き込み権限を持っているかどうかを確認します。False（デフォルト）の場合、読み取りアクセスのみを確認します。
-
RepositoryNotFoundError — リポジトリが存在しない、プライベートである、またはユーザーがアクセス権限を持っていない場合に発生します。
repo_idまたはrepo_typeが誤っている場合、またはリポジトリがプライベートであるがユーザーが認証されていない場合に発生する可能性があります。 -
GatedRepoError — リポジトリが存在するが、ゲート付きであり、ユーザーがアクセス権限を持っていない場合に発生します。
Hugging Face Hub上の特定のリポジトリに、提供されたユーザートークンがアクセスできるかどうかを確認します。
このメソッドは、提供されたトークンで認証されたユーザーが、指定されたリポジトリにアクセスできるかどうかを検証します。リポジトリが見つからない場合、またはユーザーにアクセスに必要な権限がない場合、このメソッドは適切な例外を発生させます。
例:
ユーザーがリポジトリにアクセスできるか確認します:
>>> from huggingface_hub import auth_check
>>> from huggingface_hub.utils import GatedRepoError, RepositoryNotFoundError
try:
auth_check("user/my-cool-model")
except GatedRepoError:
# Handle gated repository error
print("You do not have permission to access this gated repository.")
except RepositoryNotFoundError:
# Handle repository not found error
print("The repository was not found or you do not have access.")この例では:
- ユーザーがアクセス権限を持っている場合、メソッドは正常に完了します。
- リポジトリがゲート付きであるか存在しない場合、適切な例外がスローされ、ユーザーがそれらを適切に処理できるようになります。
batch_bucket_files
< source >( bucket_id: stradd: list[tuple[str | Path | bytes, str]] | None = Nonecopy: list[tuple[str, str, str, str]] | None = Nonedelete: list[str] | None = Nonetoken: str | bool | None = None )
パラメータ
- bucket_id (
str) — バケットの ID (例:"username/my-bucket")。 - add (
listoftuple, optional) — アップロードするファイル。各要素は(source, destination)のタプルで、sourceはローカルファイルへのパス(strまたはPath)または生のbytesコンテンツ、destinationはバケット内のパスです。 - copy (
listのtuple, 任意の) — xet ハッシュでコピーするファイル。各要素は(source_repo_type, source_repo_id, xet_hash, destination)のタプルで、以下を指定します:source_repo_typeはソースリポジトリのタイプです:"model"、"dataset"、"space"、または"bucket"。source_repo_idは、ソースリポジトリまたはバケットのIDです（例:"username/my-model"）。xet_hashは、コピーするファイルの xet ハッシュです。destinationはバケット内の宛先パスです。 これはサーバーサイドの操作であり、データのダウンロードや再アップロードは行われません。
- delete (
listofstr, 任意) — バケットから削除するファイルのパス。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
例外
BucketBatchError
BucketBatchError— サーバーが一部の操作の失敗を報告した場合に発生します。エラーはすべての操作が送信された後に一度だけ発生するため、バッチ内の他の操作は適用されています。
バケット内のファイルを追加、コピー、および/または削除します。
これはトランザクション非対応の操作です。処理中にエラーが発生した場合、一部のファイルがアップロード、コピー、または削除された一方で、他のファイルがまだ処理されていない可能性があります。
例:
>>> from huggingface_hub import batch_bucket_files
# Upload files
>>> batch_bucket_files(
... "username/my-bucket",
... add=[
... ("./model.safetensors", "models/model.safetensors"),
... (b'{{"key": "value"}}', "config.json"),
... ],
... )
# Copy xet files from another bucket or repo (server-side, no data transfer)
>>> batch_bucket_files(
... "username/my-bucket",
... copy=[
... ("bucket", "username/source-bucket", "<xethash_1>", "models/model.safetensors"),
... ("model", "username/my-model", "<xethash_2>", "models/config.safetensors"),
... ],
... )
# Delete files
>>> batch_bucket_files("username/my-bucket", delete=["old-model.bin"])
# Upload and delete in one batch
>>> batch_bucket_files(
... "username/my-bucket",
... add=[("./new.txt", "new.txt")],
... delete=["old.txt"],
... )bucket_info
< source >( bucket_id: strtoken: bool | str | None = None ) → BucketInfo
パラメータ
- bucket_id (
str) — バケットの ID (例:"username/my-bucket")。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
バケット情報。
例外
BucketNotFoundError または or
BucketNotFoundError— バケットが見つからない場合。存在しないことが原因である可能性があります。or—privateに設定されているため、アクセス権限がないためです。
Hub上の特定のバケットに関する情報を取得します。
例:
>>> from huggingface_hub import bucket_info
>>> info = bucket_info(bucket_id="Wauplin/first-bucket")
>>> info.id
'Wauplin/first-bucket'
>>> info.private
False
>>> info.created_at
datetime.datetime(2026, 2, 6, 17, 37, 57, tzinfo=datetime.timezone.utc)
>>> info.size
551879671
>>> info.total_files
12cancel_access_request
< source >( repo_id: struser: str | None = Nonerequest_id: str | None = Nonerepo_type: str | None = Nonetoken: bool | str | None = None )
パラメータ
- repo_id (
str) — アクセス要求を取り消すリポジトリのID。 - user (
str, 省略可) — アクセス要求のキャンセル対象となるユーザー名。userとrequest_idのうち、正確に1つを指定する必要があります。 - request_id (
str, 省略可) — キャンセルするアクセスリクエストの ID（AccessRequestを参照）。リポジトリがリクエスト送信者のユーザー名を共有しないように設定されている場合に必須です。userとrequest_idのうち、ちょうど 1 つを指定する必要があります。 - repo_type (
str, 省略可) — アクセス要求を取り消すリポジトリの種類。model、dataset、spaceのいずれかである必要があります。 デフォルトはmodelです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
例外
HfHubHTTPError
HfHubHTTPError— リポジトリがゲート付きでない場合、HTTP 400 が返されます。HfHubHTTPError— リポジトリへのアクセス権限が読み取り専用の場合、HTTP 403 が返されます。リポジトリが属する組織でwriteまたはadminのロールを持っていない場合、またはreadトークンを渡した場合に、この状況が発生し得ます。HfHubHTTPError— ユーザーが Hub に存在しない場合、HTTP 404 が返されます。HfHubHTTPError— ユーザーのアクセスリクエストが見つからない場合、HTTP 404 が返されます。HfHubHTTPError— ユーザーのアクセスリクエストが既に保留リストにある場合、HTTP 404 が返されます。
指定されたゲート付きリポジトリに対するユーザーのアクセスリクエストをキャンセルします。
キャンセルされたリクエストは保留リストに戻り、ユーザーはリポジトリへのアクセスを失います。
ゲート付きリポジトリの詳細については、https://huggingface.co/docs/hub/models-gatedを参照してください。
cancel_job
< source >( job_id: strnamespace: str | None = Nonetoken: bool | str | None = None )
パラメータ
- job_id (
str) — Job の ID。 - namespace (
str, 省略可能) — Job が実行されている namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。
Hugging Faceのインフラストラクチャ上で、計算ジョブをキャンセルします。
change_discussion_status
< source >( repo_id: strdiscussion_num: intnew_status: Literal['open', 'closed']token: bool | str | None = Nonecomment: str | None = Nonerepo_type: str | None = None ) → DiscussionStatusChange
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - discussion_num (
int) — Discussion または Pull Request の番号です。正の整数である必要があります。 - new_status (
str) — ディスカッションの新しいステータス。"open"または"closed"のいずれかです。 - comment (
str, 省略可) — ステータス変更と同時に投稿する任意のコメント。 - repo_type (
str, 省略可) — データセットまたはスペースにアップロードする場合は"dataset"または"space"、モデルにアップロードする場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
ステータス変更イベント
DiscussionまたはPull Requestを閉じるか、再オープンします。
例:
>>> HfApi().change_discussion_status(
... repo_id="username/repo_name",
... discussion_num=34,
... new_status="closed"
... )
# DiscussionStatusChange(id='deadbeef0000000', type='status-change', ...)
以下のエラーを発生させます：
- HuggingFace API がエラーを返した場合に
HTTPErrorValueError一部のパラメータ値が無効な場合- RepositoryNotFoundError ダウンロード元のリポジトリが見つからない場合に発生します。存在しないか、
privateに設定されておりアクセス権限がないことが原因です。
コメントの議論
< source >( repo_id: strdiscussion_num: intcomment: strtoken: bool | str | None = Nonerepo_type: str | None = None ) → DiscussionComment
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - discussion_num (
int) — Discussion または Pull Request の番号です。正の整数である必要があります。 - comment (
str) — 作成するコメントの内容。コメントはMarkdown形式の書式に対応しています。 - repo_type (
str, 省略可) — データセットまたはスペースにアップロードする場合は"dataset"または"space"、モデルにアップロードする場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
新しく作成されたコメント
指定されたDiscussionに新しいコメントを作成します。
例:
>>> comment = """
... Hello @otheruser!
...
... # This is a title
...
... **This is bold**, *this is italic* and ~this is strikethrough~
... And [this](http://url) is a link
... """
>>> HfApi().comment_discussion(
... repo_id="username/repo_name",
... discussion_num=34,
... comment=comment
... )
# DiscussionComment(id='deadbeef0000000', type='comment', ...)
以下のエラーを発生させます：
- HuggingFace API がエラーを返した場合に
HTTPErrorValueError一部のパラメータ値が無効な場合- RepositoryNotFoundError ダウンロード元のリポジトリが見つからない場合に発生します。存在しないか、
privateに設定されておりアクセス権限がないことが原因です。
copy_files
< source >( source: strdestination: strtoken: str | bool | None = None )
パラメータ
- source (
str) —hf://URI 形式のソースの場所。バケットパス（例:"hf://buckets/my-bucket/path/to/file"）またはリポジトリパス（例:"hf://username/my-model/weights.bin"、"hf://datasets/username/my-dataset/data/"）を指定できます。 - destination (
str) —hf://URI 形式の宛先位置。バケット（例:"hf://buckets/my-bucket/target/path"）またはリポジトリ（例:"hf://username/my-model/target/path"）を指します。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
例外
ValueError
ValueError— ソース/デスティネーションのURIが無効な場合、またはバケットからリポジトリへコピーする場合に発生します。
Hub上の異なる場所間でファイルをコピーします。
バケットまたはリポジトリ（モデル、データセット、スペース）から、バケットまたは別のリポジトリにファイルをコピーします。 単一のファイルとフォルダ全体をサポートしています。
フォルダをコピーする際、ソースパスの末尾に/がある場合、rsync 形式のセマンティクスが適用されます。つまり、ソースフォルダ自体をネストせずに、その中身をデスティネーションにコピーします。末尾に/がない場合、ソースフォルダはデスティネーション内にネストされます（cp -rと同様）。
リポジトリからバケットにコピーする際、.gitattributesファイルはgit固有のメタデータでありバケットの文脈では関連がないため、自動的に除外されます。
リポジトリ間のコピーは内部でCommitOperationCopyを使用し、宛先リポジトリにコミットを作成します。バケットからリポジトリへのコピーはサポートされていません。
サーバーサイドのコピーは、同じストレージリージョン内でのみ機能します。
例:
>>> from huggingface_hub import copy_files
# Copy a single file between buckets
>>> copy_files("hf://buckets/my-bucket/data.bin", "hf://buckets/other-bucket/data.bin")
# Copy a folder into another bucket (nests: backup/models/...)
>>> copy_files("hf://buckets/my-bucket/models", "hf://buckets/other-bucket/backup/")
# Copy folder contents (trailing /): files go directly into backup/
>>> copy_files("hf://buckets/my-bucket/models/", "hf://buckets/other-bucket/backup/")
# Copy a file from a model repo to a bucket
>>> copy_files("hf://username/my-model/model.safetensors", "hf://buckets/my-bucket/")
# Copy an entire dataset to a bucket
>>> copy_files("hf://datasets/username/my-dataset/", "hf://buckets/my-bucket/datasets/")
# Copy files between repositories
>>> copy_files("hf://username/source-model/", "hf://username/dest-model/")
# Copy a file from one repo to another
>>> copy_files("hf://username/source-model/config.json", "hf://username/dest-model/config.json")create_branch
< source >( repo_id: strbranch: strrevision: str | None = Nonetoken: bool | str | None = Nonerepo_type: str | None = Noneexist_ok: bool = False )
パラメータ
- repo_id (
str) — ブランチが作成されるリポジトリです。 例:"user/my-cool-model"。 - branch (
str) — 作成するブランチの名前。 - revision (
str, 任意) — ブランチを作成する元の git リビジョンです。ブランチ名、またはコミットの OID/SHA を16進数文字列として指定できます。デフォルトでは、"main"ブランチの先頭です。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - repo_type (
str, 省略可) — データセットまたはスペースのブランチを作成する場合は"dataset"または"space"、モデルにタグを付ける場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - exist_ok (
bool、省略可能、デフォルトはFalse) —Trueの場合、ブランチが既に存在していてもエラーを発生させません。
例外
RepositoryNotFoundError または BadRequestError または HfHubHTTPError
- RepositoryNotFoundError — リポジトリが見つからない場合（エラー 404）：repo_id/repo_type が誤っている、非公開リポジトリであるが認証されていない、またはリポジトリが存在しない。
- BadRequestError —
ブランチの参照が無効な場合。例:
refs/pr/5または ‘refs/foo/bar’。 - HfHubHTTPError —
リポジトリにブランチが既に存在する場合（エラー 409）かつ、
exist_okがFalseに設定されている場合。
Hub上のリポジトリで、指定されたリビジョン（デフォルトはmain）を起点として新しいブランチを作成します。
ニーズに合ったリビジョンを見つけるには、list_repo_refs()またはlist_repo_commits()を使用できます。
create_bucket
< source >( bucket_id: strprivate: bool | None = Nonevisibility: Literal['public', 'private'] | None = Noneresource_group_id: str | None = Noneregion: REPO_REGIONS | None = Noneexist_ok: bool = Falsetoken: bool | str | None = None ) → BucketUrl
パラメータ
- bucket_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とバケット名です。 名前空間が指定されない場合、現在のユーザーの名前空間にバケットが作成されます。 - private (
bool、省略可) — バケットをプライベートにするかどうか。None（デフォルト）の場合、組織のデフォルトがプライベートでない限り、バケットはパブリックになります。visibilityと同時に指定することはできません。 - visibility (
Literal["public", "private"], 省略可) — バケットの可視性。"public"または"private"を指定できます。None（デフォルト）の場合、組織のデフォルトが private になっていない限り、バケットは public になります。 - resource_group_id (
str, 任意) — バケットを作成するリソースグループ。リソースグループは Enterprise Hub 組織でのみ利用可能であり、組織のどのメンバーがリソースにアクセスできるかを定義できます。リソースグループの ID は、Hub 上のリソースのページの URL から確認できます（例:"66670e5163145ca562cb1988"）。リソースグループの詳細については、https://huggingface.co/docs/hub/en/security-resource-groups を参照してください。 - region (
Literal["us", "eu"], 省略可) — バケットを作成するクラウドリージョン。"us"または"eu"のいずれかです。指定しない場合、デフォルトのリージョンにバケットが作成されます。Team プラン以上が必要です。 - exist_ok (
bool、省略可能、デフォルトはFalse) —Trueの場合、バケットが既に存在していてもエラーを発生させません。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
endpoint、namespace、bucket_id などの属性を含む、新しく作成されたバケットの URL。
Hubにバケットを作成します。
例:
>>> from huggingface_hub import create_bucket
>>> url = create_bucket(bucket_id="my-bucket")
>>> url.bucket_id
'user/my-bucket'
>>> url.url
'https://huggingface.co/buckets/user/my-bucket'
>>> url.uri.to_uri()
'hf://buckets/user/my-bucket'
>>> create_bucket(bucket_id="my-bucket", private=True, exist_ok=True)
BucketUrl(...)
>>> create_bucket(bucket_id="my-bucket", region="us")
BucketUrl(...)create_collection
< source >( title: strnamespace: str | None = Nonedescription: str | None = Noneprivate: bool = Falseresource_group_id: str | None = Noneexists_ok: bool = Falsetoken: bool | str | None = None )
パラメータ
- title (
str) — 作成するコレクションのタイトル。例:"Recent models"。 - namespace (
str, 省略可) — 作成するコレクションのネームスペース（ユーザー名または組織名）です。省略した場合、オーナー名がデフォルトとして使用されます。 - description (
str, 省略可) — 作成するコレクションの説明です。説明の最大長は150文字です。 - private (
bool、省略可能) — コレクションをプライベートにするかどうか。デフォルトはFalse（つまりパブリックコレクション）です。 - resource_group_id (
str, 任意) — コレクションを、所有組織のリソースグループに割り当てます。組織が所有するコレクションでのみ有効です。リソースグループ ID は 24 文字の 16 進数文字列です。 - exists_ok (
bool, 省略可) —Trueの場合、コレクションが既に存在していてもエラーを発生させません。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
Hubで新しいCollectionを作成します。
戻り値: Collection
create_commit
< source >( repo_id: stroperations: Iterable[CommitOperation]commit_message: strcommit_description: str | None = Nonetoken: str | bool | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecreate_pr: bool | None = Nonenum_threads: int = 5parent_commit: str | None = Nonerun_as_future: bool = False_hot_reload: bool | None = None ) → CommitInfo or Future
パラメータ
- repo_id (
str) — コミットが作成されるリポジトリ。例:"username/custom_transformers" - operations (
Iterableの~hf_api.CommitOperation) — コミットに含める操作のイテラブル。以下のいずれかです:~hf_api.CommitOperationAddを使用してファイルをアップロードします~hf_api.CommitOperationDeleteを使用してファイルを削除します~hf_api.CommitOperationCopyを使用してファイルをコピーします
Operationオブジェクトは、アップロードに関する情報が含まれるように変更されます。同じオブジェクトを複数のコミットに再利用しないでください。
- commit_message (
str) — 作成されるコミットのサマリー（最初の行）です。 - commit_description (
str, 省略可) — 作成されるコミットの説明 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - repo_type (
str, 任意) — データセット、スペース、またはカーネルのリポジトリにアップロードする場合は、それぞれ"dataset"、"space"、"kernel"を設定します。モデルにアップロードする場合はNoneまたは"model"です。デフォルトはNoneです。 - revision (
str, 省略可) — コミット元の git リビジョンです。デフォルトでは、"main"ブランチの先頭になります。 - create_pr (
boolean, 省略可) — そのコミットで Pull Request を作成するかどうか。デフォルトはFalseです。revisionが設定されていない場合、PR は"main"ブランチに対して作成されます。revisionが設定されておりブランチである場合、PR はそのブランチに対して作成されます。revisionが設定されているがブランチ名でない場合（例: コミット OID）、サーバーからRevisionNotFoundErrorが返されます。 - num_threads (
int, 任意) — ファイルのアップロードに使用する同時実行スレッド数。デフォルト値は 5 です。2 に設定すると、同時にアップロードされるファイルは最大 2 個になります。 - parent_commit (
str, 省略可能) — 親コミットの OID / SHA を16進数文字列として指定します。 略記法（先頭7文字）もサポートされています。指定され、create_prがFalseの場合、revisionがparent_commitを指していないとコミットは失敗します。指定され、create_prがTrueの場合、プルリクエストはparent_commitから作成されます。parent_commitを指定することで、変更をコミットする前にリポジトリが変更されていないことを保証でき、 リポジトリが並行して更新 / コミットされる場合に特に有用です。 - run_as_future (
bool, 省略可) — このメソッドをバックグラウンドで実行するかどうか。バックグラウンドジョブは、メインスレッドをブロックせずにシーケンシャルに実行されます。run_as_future=Trueを渡すと、Future オブジェクトが返されます。デフォルトはFalseです。
戻り値
CommitInfoまたはFuture
新しく作成されたコミットに関する情報（コミットハッシュ、コミットURL、PR URL、コミットメッセージなど）を含むCommitInfoのインスタンスを返します。run_as_future=Trueが渡された場合、実行時に結果を含むFutureオブジェクトを返します。
例外
ValueError または RepositoryNotFoundError
ValueError— コミットメッセージが空の場合。ValueError— 親コミットが有効なコミット OID ではない場合。ValueError— 無効なメタデータセクションを含むREADME.mdファイルがコミットされた場合。この場合、ファイルのアップロードを試みる前に、コミットが早期に失敗します。ValueError—create_prがTrueであり、かつ revision がNoneでも"main"でもない場合。- RepositoryNotFoundError — リポジトリが見つからない場合（エラー 404）：repo_id/repo_type が誤っている、非公開リポジトリであるが認証されていない、またはリポジトリが存在しない。
指定されたリポジトリにコミットを作成し、必要に応じてファイルを削除およびアップロードします。
CommitOperationの入力リストは、コミット処理中に変更されます。同じオブジェクトを複数のコミットに再利用しないでください。
create_commitは、リポジトリがすでに Hub に存在することを前提としています。Client error 404 が返された場合は、認証が有効であること、トークンに必要な権限が付与されていること、repo_idとrepo_typeが正しく設定されていることを確認してください。リポジトリが存在しない場合は、create_repo() を使用して先に作成してください。
create_commitは、LFSファイルが25,000件、通常ファイルのペイロードが1GBに制限されています。
create_discussion
< source >( repo_id: strtitle: strtoken: bool | str | None = Nonedescription: str | None = Nonerepo_type: str | None = Nonepull_request: bool = False )
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - title (
str) — ディスカッションのタイトルです。最大200文字、最小3文字でなければなりません。先頭と末尾の空白は除去されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - description (
str, 任意) — Pull Request 用の任意の説明です。 デフォルト値は"Discussion opened with the huggingface_hub Python library"です。 - pull_request (
bool, 省略可能) — Pull Requestまたはdiscussionを作成するかどうか。Trueの場合、Pull Requestを作成します。Falseの場合、discussionを作成します。デフォルトはFalseです。 - repo_type (
str, 省略可) — データセットまたはスペースにアップロードする場合は"dataset"または"space"、モデルにアップロードする場合はNoneまたは"model"を設定します。デフォルトはNoneです。
DiscussionまたはPull Requestを作成します。
プログラムによって作成されたPull Requestsは"draft"ステータスになります。
変更を含む Pull Request の作成は、HfApi.create_commit() を一度に実行することでも可能です。
以下のエラーを発生させます：
- HuggingFace API がエラーを返した場合に
HTTPErrorValueError一部のパラメータ値が無効な場合- RepositoryNotFoundError ダウンロード元のリポジトリが見つからない場合に発生します。存在しないか、
privateに設定されておりアクセス権限がないことが原因です。
create_inference_endpoint
< source >( name: strrepository: strframework: straccelerator: strinstance_size: strinstance_type: strregion: strvendor: straccount_id: str | None = Noneprivate_link_account_id: str | None = Noneprivate_link_region: str | None = Nonemin_replica: int = 1max_replica: int = 1scaling_metric: InferenceEndpointScalingMetric | None = Nonescaling_threshold: float | None = Nonescale_to_zero_timeout: int | None = Nonerevision: str | None = Nonetask: str | None = Nonecustom_image: dict | None = Nonecontainer_registry_username: str | None = Nonecontainer_registry_password: str | None = Nonecontainer_command: list[str] | None = Nonecontainer_args: list[str] | None = Noneenv: dict[str, str] | None = Nonesecrets: dict[str, str] | None = Nonetype: InferenceEndpointType | str = <InferenceEndpointType.AUTHENTICATED: 'authenticated'>domain: str | None = Nonepath: str | None = Nonecache_http_responses: bool | None = Nonetags: list[str] | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None ) → InferenceEndpoint
パラメータ
- name (
str) — 新しいInference Endpointの一意の名前。 - repository (
str) — Inference Endpointに関連付けられたモデルリポジトリの名前（例:"gpt2"）。 - framework (
str) — モデルで使用される機械学習フレームワーク（例:"custom"）。 - accelerator (
str) — 推論に使用するハードウェアアクセラレータ（例:"cpu"）。 - instance_size (
str) — モデルのホスティングに使用するインスタンスのサイズまたはタイプ（例:"x4"）。 - instance_type (
str) — Inference Endpoint がデプロイされるクラウドインスタンスの種類（例:"intel-icl"）。 - region (
str) — Inference Endpoint が作成されるクラウドリージョン（例:"us-east-1"）。 - vendor (
str) — Inference Endpoint がホストされるクラウドプロバイダーまたはベンダー（例:"aws"）。 - account_id (
str, 省略可) — 非推奨であり、無視されます。AWS PrivateLink を設定するには、private_link_account_idとprivate_link_regionを使用してください。 - private_link_account_id (
str, 任意) — AWS PrivateLink 経由で Inference Endpoint にアクセスが許可される AWS アカウント ID。private_link_regionが必要です。 - private_link_region (
str, 任意) — PrivateLinkのエントリポイントのAWSリージョン("us-east-1"または"eu-west-1")。private_link_account_idのVPCエンドポイントが接続先となるリージョンです。コンピュートのregionおよびvendorとは独立しています。 - min_replica (
int, 任意) — Inference Endpoint で稼働させ続けるレプリカ（インスタンス）の最小数です。ゼロスケーリングを有効にするには、この値を 0 に設定し、scale_to_zero_timeoutをそれに応じて調整してください。デフォルト値は 1 です。 - max_replica (
int, 任意) — Inference Endpoint のレプリカ（インスタンス）をスケーリングする際の最大数。デフォルト値は 1 です。 - scaling_metric (
strまたはInferenceEndpointScalingMetric、省略可) — スケーリング用のメトリック参照です。指定する場合、“pendingRequests” または “hardwareUsage” のいずれかです。デフォルトは None (HF Endpoints サービスがメトリックを指定することを意味します)。 - scaling_threshold (
float, 任意) — スケールアップをトリガーするために使用されるスケーリングメトリクスの閾値です。スケーリングメトリクスが指定されていない場合は無視されます。 デフォルトは None です（HF Endpoints サービスが閾値を指定することを意味します）。 - scale_to_zero_timeout (
int, 任意) — 非アクティブなエンドポイントがゼロにスケーリングされるまでの時間（分）。None に設定され、min_replicaが 0 でない場合、ゼロへのスケーリングは行われません。デフォルト値は None です。 - revision (
str, 任意) — Inference Endpoint にデプロイする特定のモデルのリビジョン（例:"6c0e6080953db56375760c0471a8c5f2929baf11"）。 - task (
str, 任意) — モデルをデプロイするタスク（例:"text-classification"）。 - custom_image (
dict, 省略可) — 実行するコンテナイメージです。イメージのバリアントをキーとする辞書（例:{"vLLM": {"url": "vllm/vllm-openai:v0.23.0", "port": 8000}}、sGLang、tgi、tei、llamacpp、hfServeなど）として渡すことも、カスタムコンテナを記述するフラットな辞書（例:{"url": ..., "port": ...}）として渡すこともできます。後者の場合は{"custom": ...}として送信されます（例を参照）。デフォルトでは、Hugging Face が管理するイメージが使用されます。 - container_registry_username (
str, 省略可) — カスタムコンテナイメージをホストするレジストリへの認証に使用するユーザー名。 - container_registry_password (
str, 省略可) — カスタムコンテナイメージをホストするレジストリへの認証に使用するパスワード。container_registry_usernameが必要です。指定されていない場合、APIペイロードから省略されます。 - container_command (
list[str]、省略可) — コンテナのエントリポイントコマンドを上書きします（APIペイロードのmodel.commandにマッピングされます）。マネージドエンジンイメージ（vLLM、SGLang など）およびカスタムイメージの両方で動作します。 - container_args (
list[str]、省略可) — コンテナのエントリポイントに追加される引数です（APIペイロードのmodel.argsに対応します）。マネージドエンジンイメージ（vLLM、SGLang など）およびカスタムイメージの両方で動作します。 - env (
dict[str, str]、省略可) — コンテナ環境に注入する非シークレットの環境変数。 - secrets (
dict[str, str]、省略可) — コンテナ環境に注入するシークレット値。 - type ([`InferenceEndpointType]
, *optional*) -- The type of the Inference Endpoint, which can be“authenticated”(default),“public”or“private”`. - domain (
str, 任意) — Inference Endpoint のデプロイメントに使用するカスタムドメインです。設定されている場合、Inference Endpoint はこのドメインで利用可能になります（例:"my-new-domain.cool-website.woof"）。 - path (
str, 任意) — デプロイされたモデルへのカスタムパスです。/で始まる必要があります（例:"/models/google-bert/bert-base-uncased"）。 - cache_http_responses (
bool, 省略可) — Inference Endpoint からの HTTP 応答をキャッシュするかどうか。デフォルトはFalseです。 - tags (
list[str]、任意) — Inference Endpointに関連付けるタグのリストです。 - namespace (
str, 省略可) — Inference Endpoint が作成される namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
更新されたInference Endpointに関する情報。
新しいInference Endpointを作成します。
accelerator、instance_size、instance_type、region、vendor の値は相互に依存しています。有効な組み合わせを確認するには、list_inference_endpoints_hardware() を使用してください。
例:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> endpoint = api.create_inference_endpoint(
... "my-endpoint-name",
... repository="gpt2",
... framework="pytorch",
... task="text-generation",
... accelerator="cpu",
... vendor="aws",
... region="us-east-1",
... type="authenticated",
... instance_size="x2",
... instance_type="intel-icl",
... )
>>> endpoint
InferenceEndpoint(name='my-endpoint-name', status="pending",...)
# Run inference on the endpoint
>>> endpoint.client.text_generation(...)
"..."# Start an Inference Endpoint running Zephyr-7b-beta on TGI
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> endpoint = api.create_inference_endpoint(
... "aws-zephyr-7b-beta-0486",
... repository="HuggingFaceH4/zephyr-7b-beta",
... framework="pytorch",
... task="text-generation",
... accelerator="gpu",
... vendor="aws",
... region="us-east-1",
... type="authenticated",
... instance_size="x1",
... instance_type="nvidia-a10g",
... env={
... "MAX_BATCH_PREFILL_TOKENS": "2048",
... "MAX_INPUT_LENGTH": "1024",
... "MAX_TOTAL_TOKENS": "1512",
... "MODEL_ID": "/repository"
... },
... custom_image={
... "healthRoute": "/health",
... "url": "ghcr.io/huggingface/text-generation-inference:1.1.0",
... },
... secrets={"MY_SECRET_KEY": "secret_value"},
... tags=["dev", "text-generation"],
... )# Start an Inference Endpoint running ProsusAI/finbert while scaling to zero in 15 minutes
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> endpoint = api.create_inference_endpoint(
... "finbert-classifier",
... repository="ProsusAI/finbert",
... framework="pytorch",
... task="text-classification",
... min_replica=0,
... scale_to_zero_timeout=15,
... accelerator="cpu",
... vendor="aws",
... region="us-east-1",
... type="authenticated",
... instance_size="x2",
... instance_type="intel-icl",
... )
>>> endpoint.wait(timeout=300)
# Run inference on the endpoint
>>> endpoint.client.text_generation(...)
TextClassificationOutputElement(label='positive', score=0.8983615040779114)create_inference_endpoint_from_catalog
< source >( repo_id: str | None = Nonerecipe_id: str | None = Nonename: str | None = Noneaccelerator: Literal['cpu', 'gpu', 'neuron'] | str | None = Nonegguf_file: str | None = Nonetoken: bool | str | None = Nonenamespace: str | None = None ) → InferenceEndpoint
パラメータ
- repo_id (
str, 任意) — Inference Endpoint としてデプロイするカタログ内のモデルの ID。recipe_idと排他です。 - recipe_id (
str, 任意) — デプロイするカタログレシピのIDです（InferenceCatalogRecipeを参照）。repo_idとは排他的です。 - name (
str, 省略可) — 新しい Inference Endpoint の一意の名前です。指定しない場合、ランダムな名前が生成されます。 - accelerator (
str, 省略可) — 推論に使用するハードウェアアクセラレーターです。指定可能な値には"cpu"、"gpu"、"neuron"などが含まれます。指定しない場合、サーバーはモデルに適したデフォルトを使用します。repo_idと併せて使用する場合のみ有効です。 - gguf_file (
str, 省略可) — デプロイする GGUF ファイル。1 つの量子化ごとに 1 つのレシピを持つモデル用です（例:"Qwen2.5-Coder-32B-Instruct-Q4_K_M.gguf"）。repo_idと組み合わせて使用する場合のみ有効です。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。 - namespace (
str, 省略可) — Inference Endpoint が作成される namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。
新しいInference Endpointに関する情報。
Hugging Face Inference Catalogから新しいInference Endpointを作成します。
Inference Catalogの目的は、推論用に最適化され、デフォルト設定がテスト済みのモデルの厳選リストを提供することです。カタログで利用可能なモデルのリストは、https://huggingface.co/proxy/endpoints.huggingface.co/catalogを参照してください。
各カタログモデルは、レシピを通じてデプロイされます。レシピとは、そのモデル用にテスト済みのハードウェアとエンジンの組み合わせです。モデルのデフォルトレシピをデプロイするにはrepo_idを渡し、必要に応じてacceleratorとgguf_fileで絞り込みます。または、list_inference_catalog()で一覧表示される特定のレシピをデプロイするにはrecipe_idを渡します。
create_inference_endpoint_from_catalogは実験的な機能です。将来、API が変更される可能性があります。ご意見やご要望がございましたら、フィードバックをお寄せください。
create_pull_request
< source >( repo_id: strtitle: strtoken: bool | str | None = Nonedescription: str | None = Nonerepo_type: str | None = None )
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - title (
str) — ディスカッションのタイトルです。最大200文字、最小3文字でなければなりません。先頭と末尾の空白は除去されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - description (
str, 任意) — Pull Request 用の任意の説明です。 デフォルト値は"Discussion opened with the huggingface_hub Python library"です。 - repo_type (
str, 省略可) — データセットまたはスペースにアップロードする場合は"dataset"または"space"、モデルにアップロードする場合はNoneまたは"model"を設定します。デフォルトはNoneです。
Pull Request を作成します。プログラムによって作成された Pull Request は"draft"ステータスになります。
変更を含む Pull Request の作成は、HfApi.create_commit() を一度に実行することでも可能です。
これはHfApi.create_discussion()のラッパーです。
以下のエラーを発生させます：
- HuggingFace API がエラーを返した場合に
HTTPErrorValueError一部のパラメータ値が無効な場合- RepositoryNotFoundError ダウンロード元のリポジトリが見つからない場合に発生します。存在しないか、
privateに設定されておりアクセス権限がないことが原因です。
create_repo
< source >( repo_id: strtoken: str | bool | None = Noneprivate: bool | None = Nonevisibility: RepoVisibility_T | None = Nonerepo_type: str | None = Noneexist_ok: bool = Falseresource_group_id: str | None = Noneregion: REPO_REGIONS | None = Nonespace_sdk: str | None = Nonespace_hardware: SpaceHardware | None = Nonespace_sleep_time: int | None = Nonespace_secrets: list[dict[str, str]] | None = Nonespace_variables: list[dict[str, str]] | None = Nonespace_volumes: list[Volume] | None = Nonespace_template: str | None = None ) → RepoUrl
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - private (
bool、省略可) — リポジトリを非公開にするかどうか。None（デフォルト）の場合、組織のデフォルトが非公開でない限り、リポジトリは公開になります。リポジトリが既に存在する場合、この値は無視されます。visibilityと同時に指定することはできません。 - visibility (
Literal["public", "private", "protected"], 省略可) — リポジトリの公開設定。"public"または"private"、またはSpacesの場合は"protected"を指定できます。None(デフォルト)の場合、組織のデフォルトがprivateでない限り、リポジトリはpublicになります。リポジトリが既に存在する場合、この値は無視されます。 - repo_type (
str, 省略可) — データセットまたはスペースにアップロードする場合は"dataset"または"space"、モデルにアップロードする場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - exist_ok (
bool、省略可能、デフォルトはFalse) —Trueの場合、リポジトリが既に存在していてもエラーを発生させません。 - resource_group_id (
str, 任意) — リポジトリを作成するリソースグループ。リソースグループは Enterprise Hub 組織でのみ利用可能であり、組織のどのメンバーがリソースにアクセスできるかを定義できます。リソースグループの ID は、Hub 上のリソースのページの URL から確認できます（例:"66670e5163145ca562cb1988"）。リソースグループの詳細については、https://huggingface.co/docs/hub/en/security-resource-groups を参照してください。 - region (
Literal["us", "eu"], 省略可) — リポジトリを作成するクラウドリージョン。"us"または"eu"のいずれかです。指定しない場合、リポジトリはデフォルトのリージョンに作成されます。Team プラン以上が必要です。 - space_sdk (
str, 省略可) — repo_type が “space” の場合に使用する SDK を選択します。“streamlit”、“gradio”、“docker”、“static” のいずれかを指定できます。"static"Spaces はすべてのユーザーに無料です。その他の SDK は計算リソース上で実行されるため、無料のcpu-basicハードウェアではサブスクリプション（ユーザーは PRO、組織は Team または Enterprise）が必要です。一方、有料ハードウェアでは請求設定（支払い方法と事前購入クレジット）のみで利用できます。 - space_hardware (
SpaceHardwareまたはstr、省略可能) — repo_type が “space” の場合の Hardware の選択です。完全なリストについては SpaceHardware を参照してください。 - space_sleep_time (
int, 任意) — Space がスリープ状態に入るまで、待機状態を何秒間待つかを指定します。Space がスリープしないようにするには-1を設定してください（アップグレードされたハードウェアのデフォルト動作です）。無料のハードウェアでは、スリープ時間を設定できません（値は 48 時間の待機に固定されています）。 詳細は https://huggingface.co/docs/hub/spaces-gpus#sleep-time を参照してください。 - space_secrets (
list[dict[str, str]], 省略可) — Space に設定するシークレットキーのリストです。各項目は{"key": ..., "value": ..., "description": ...}の形式で、description は省略可能です。 詳細については、https://huggingface.co/docs/hub/spaces-overview#managing-secrets を参照してください。 - space_variables (
list[dict[str, str]]、省略可) — Space で設定する公開環境変数のリストです。各項目は{"key": ..., "value": ..., "description": ...}の形式で、description は省略可能です。 詳細については、https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables を参照してください。 - space_volumes (
list[Volume], 省略可) — Space の作成時にマウントする Volume オブジェクトのリストです。各ボリュームにはtype("bucket"、"model"、"dataset"、または"space")、source(リポジトリまたはバケットの ID)、mount_path(コンテナ内のパス)、および省略可能なrevision、read_only、pathフィールドがあります。 repo_type が “space” の場合のみ適用されます。 - space_template (
str, optional) — 公式テンプレートから新しい Space を作成します。テンプレートのリポジトリ ID (例:"SpacesExamples/jupyterlab") またはその短縮名 (例:"JupyterLab") を指定できます。利用可能なテンプレートのリストを取得するには、HfApi.list_space_templates() を使用してください。repo_type が “space” の場合にのみ適用されます。テンプレートがプライベートでの利用を推奨されており、かつ visibility が明示的に設定されていない場合、Space はプライベートとして作成されます。
戻り値
新しく作成されたリポジトリのURL。値はstrのサブクラスで、endpoint、repo_type、repo_idなどの属性を含みます。
HuggingFace Hub に空のリポジトリを作成します。
create_scheduled_job
< source >( image: strcommand: list[str]schedule: strsuspend: bool | None = Noneconcurrency: bool | None = Noneenv: dict[str, Any] | None = Nonesecrets: dict[str, Any] | None = Noneflavor: JobHardware | str | None = Nonetimeout: int | float | str | None = Noneattempts: int | None = Nonename: str | None = Nonelabels: dict[str, str] | None = Nonevolumes: list[Volume] | None = Noneexpose: list[int] | None = Noneexpose_public: list[int] | None = Noneresource_group_id: str | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None )
パラメータ
- image (
str) — 使用する Docker イメージです。 例:"ubuntu"、"python:3.12"、"pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel"。 Space からのイメージの例:"hf.co/spaces/lhoestq/duckdb"。 - command (
list[str]) — 実行するコマンド。例:["echo", "hello"]。 - schedule (
str) — “@annually”、“@yearly”、“@monthly”、“@weekly”、“@daily”、“@hourly”、または CRON スケジュール式（例: 毎週月曜日の午前9時を指定する ‘0 9 * * 1’）のいずれかです。 - suspend (
bool, 省略可能) — True の場合、スケジュールされた Job が停止（一時停止）されます。デフォルトは False です。 - concurrency (
bool, 省略可) — True の場合、この Job の複数のインスタンスが並行して実行できます。デフォルトは False です。 - env (
dict[str, Any]、省略可) — Job の環境変数を定義します。 - secrets (
dict[str, Any], 省略可) — Job のシークレット環境変数を定義します。 - flavor (
str, 任意) — ハードウェアの Flavor です。使用可能な値についてはJobHardwareを参照してください。 デフォルト値は"cpu-basic"です。 - timeout (
Union[int, float, str], 省略可) — Job の最大実行時間: 単位は s (秒、デフォルト)、m (分)、h (時間)、d (日) を持つ int。 例: 5 分なら300または"5m"。 - attempts (
int, 任意) — 各実行の最大試行回数（最初の試行を含む）です。デフォルト値は 1 です。 - name (
str, 省略可) — スケジュールされた Job の名前です。nameラベルとして保存されます。labelsにnameキーを同時に指定することはできません。名前の一意性は必須ではありません。デフォルトでは、イメージとコマンドから派生した名前（短いハッシュサフィックス付き）が使用されます。 - labels (
dict[str, str], 省略可) — ジョブに付与するラベル（キーと値のペア）。 - volumes (
list[Volume]、任意) — ジョブのコンテナにボリュームとしてマウントする Hugging Face Buckets または Repos。 各ボリュームは Volume で、type("bucket"、"model"、"dataset"、または"space")、source(例:"username/my-bucket")、およびmount_path(例:"/data") を持ちます。 - expose (
list[int], 任意) — ジョブプロキシ経由で公開するコンテナポートです。リストに指定された各ポートは、パブリックなジョブドメイン（例:https://<job_id>--8000.hf.jobs）からアクセスできます。アクセスには常に、そのジョブのネームスペースに対する読み取り権限を持つ HF トークンが必要です。認証なしでのアクセスにはexpose_publicを使用してください。 - expose_public (
list[int], 省略可) — 認証なしで Jobs プロキシ経由で公開するポートです。exposeに列挙する必要はありません。 - resource_group_id (
str, 任意) — スケジュールされた Job を作成するリソースグループの ID です。組織内のリソースへのアクセス制御や、コストの帰属・支出上限機能に使用されます。指定されない場合、スケジュールされた Job はリソースグループの外に作成されます。 - namespace (
str, 省略可能) — Job が作成される namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。
Hugging Face のインフラストラクチャ上で、スケジュールされた compute Jobs を作成します。
例:
最初のスケジュールされたJobを作成します:
>>> from huggingface_hub import create_scheduled_job
>>> create_scheduled_job(image="python:3.12", command=["python", "-c" ,"print('Hello from HF compute!')"], schedule="@hourly")CRONスケジュール式を使用します:
>>> from huggingface_hub import create_scheduled_job
>>> create_scheduled_job(image="python:3.12", command=["python", "-c" ,"print('this runs every 5min')"], schedule="*/5 * * * *")スケジュールされたGPUジョブを作成します:
>>> from huggingface_hub import create_scheduled_job
>>> image = "pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel"
>>> command = ["python", "-c", "import torch; print(f'This code ran with the following GPU: {torch.cuda.get_device_name()}')"]
>>> create_scheduled_job(image=image, command=command, flavor="a10g-small", schedule="@hourly")create_scheduled_uv_job
< source >( script: strscript_args: list[str] | None = Noneschedule: strsuspend: bool | None = Noneconcurrency: bool | None = Nonedependencies: list[str] | None = Nonepython: str | None = Noneimage: str | None = Noneenv: dict[str, Any] | None = Nonesecrets: dict[str, Any] | None = Noneflavor: JobHardware | str | None = Nonetimeout: int | float | str | None = Noneattempts: int | None = Nonename: str | None = Nonelabels: dict[str, str] | None = Nonevolumes: list[Volume] | None = Noneexpose: list[int] | None = Noneexpose_public: list[int] | None = Noneresource_group_id: str | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None )
パラメータ
- script (
str) — UV スクリプトのパスまたは URL、またはコマンド。 - script_args (
list[str]、省略可) — スクリプトまたはコマンドに渡す引数。 - schedule (
str) — “@annually”、“@yearly”、“@monthly”、“@weekly”、“@daily”、“@hourly”、または CRON スケジュール式（例: 毎週月曜日の午前9時を指定する ‘0 9 * * 1’）のいずれかです。 - suspend (
bool, 省略可能) — True の場合、スケジュールされた Job が停止（一時停止）されます。デフォルトは False です。 - concurrency (
bool, 省略可) — True の場合、この Job の複数のインスタンスが並行して実行できます。デフォルトは False です。 - dependencies (
list[str], 任意) — UVスクリプトの実行に使用する依存関係。 - python (
str, 省略可能) — 特定の Python バージョンを使用します。デフォルトは 3.12 です。 - image (
str、任意、デフォルト値は “ghcr.io/astral-sh/uv —python3.12-bookworm”):uvがインストールされたカスタム Docker イメージを使用します。 - env (
dict[str, Any]、省略可) — Job の環境変数を定義します。 - secrets (
dict[str, Any], 省略可) — Job のシークレット環境変数を定義します。 - flavor (
str, 任意) — ハードウェアの Flavor です。使用可能な値についてはJobHardwareを参照してください。 デフォルト値は"cpu-basic"です。 - timeout (
Union[int, float, str], 省略可) — Job の最大実行時間: 単位は s (秒、デフォルト)、m (分)、h (時間)、d (日) を持つ int。 例: 5 分なら300または"5m"。 - attempts (
int, 任意) — 各実行の最大試行回数（最初の試行を含む）です。デフォルト値は 1 です。 - name (
str, 省略可) — スケジュールされた Job の名前です。nameラベルとして保存されます。labelsにnameキーを同時に指定することはできません。名前の一意性は必須ではありません。デフォルトでは、スクリプトとその引数から派生した名前（短いハッシュサフィックス付き）が使用されます。 - labels (
dict[str, str], 省略可) — ジョブに付与するラベル（キーと値のペア）。 - volumes (
list[Volume]、任意) — ジョブのコンテナにボリュームとしてマウントする Hugging Face Buckets または Repos。 各ボリュームは Volume で、type("bucket"、"model"、"dataset"、または"space")、source(例:"username/my-bucket")、およびmount_path(例:"/data") を持ちます。 - expose (
list[int], 任意) — ジョブプロキシ経由で公開するコンテナポートです。リストに指定された各ポートは、パブリックなジョブドメイン（例:https://<job_id>--8000.hf.jobs）からアクセスできます。アクセスには常に、そのジョブのネームスペースに対する読み取り権限を持つ HF トークンが必要です。認証なしでのアクセスにはexpose_publicを使用してください。 - expose_public (
list[int], 省略可) — 認証なしで Jobs プロキシ経由で公開するポートです。exposeに列挙する必要はありません。 - resource_group_id (
str, 任意) — スケジュールされた Job を作成するリソースグループの ID です。組織内のリソースへのアクセス制御や、コストの帰属・支出上限機能に使用されます。指定されない場合、スケジュールされた Job はリソースグループの外に作成されます。 - namespace (
str, 省略可能) — Job が作成される namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。
Hugging Faceのインフラストラクチャ上でUVスクリプトジョブを実行します。
hf jobs uv runとは異なり、このメソッドは、UV スクリプトが PEP 723 ヘッダーに含めることのできる任意の[tool.hf-jobs]テーブル（Jobs ガイドを参照）を無視します。ここでは、起動設定を明示的に渡す必要があります。
例:
URLからスクリプトをスケジュールする:
>>> from huggingface_hub import create_scheduled_uv_job
>>> script = "https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py"
>>> script_args = ["--model_name_or_path", "Qwen/Qwen2-0.5B", "--dataset_name", "trl-lib/Capybara", "--push_to_hub"]
>>> create_scheduled_uv_job(script, script_args=script_args, dependencies=["trl"], flavor="a10g-small", schedule="@weekly")ローカルスクリプトをスケジュールする:
>>> from huggingface_hub import create_scheduled_uv_job
>>> script = "my_sft.py"
>>> script_args = ["--model_name_or_path", "Qwen/Qwen2-0.5B", "--dataset_name", "trl-lib/Capybara", "--push_to_hub"]
>>> create_scheduled_uv_job(script, script_args=script_args, dependencies=["trl"], flavor="a10g-small", schedule="@weekly")コマンドをスケジュールします:
>>> from huggingface_hub import create_scheduled_uv_job
>>> script = "lighteval"
>>> script_args= ["endpoint", "inference-providers", "model_name=openai/gpt-oss-20b,provider=auto", "lighteval|gsm8k|0|0"]
>>> create_scheduled_uv_job(script, script_args=script_args, dependencies=["lighteval"], flavor="a10g-small", schedule="@weekly")create_tag
< source >( repo_id: strtag: strtag_message: str | None = Nonerevision: str | None = Nonetoken: bool | str | None = Nonerepo_type: str | None = Noneexist_ok: bool = False )
パラメータ
- repo_id (
str) — コミットにタグを付けるリポジトリです。 例:"user/my-cool-model"。 - tag (
str) — 作成するタグの名前。 - tag_message (
str, 省略可) — 作成するタグの説明です。 - revision (
str, 任意) — タグ付けする git リビジョンです。ブランチ名、またはコミットの OID/SHA を16進数文字列として指定できます。略記法（先頭7文字）もサポートされています。デフォルトでは、"main"ブランチのヘッドが使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - repo_type (
str, 省略可) — データセットまたはスペースにタグを付ける場合は"dataset"または"space"、モデルにタグを付ける場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - exist_ok (
bool、省略可能、デフォルトはFalse) —Trueの場合、タグが既に存在していてもエラーを発生させません。
- RepositoryNotFoundError — リポジトリが見つからない場合（エラー 404）：repo_id/repo_type が誤っている、非公開リポジトリであるが認証されていない、またはリポジトリが存在しない。
- RevisionNotFoundError — リポジトリ上でリビジョンが見つからない場合（エラー 404）。
- HfHubHTTPError —
リポジトリにブランチが既に存在する場合（エラー 409）かつ、
exist_okがFalseに設定されている場合。
Hub上のリポジトリの特定のコミットにタグを付けます。
create_webhook
< source >( url: str | None = Nonejob_id: str | None = Nonewatched: list[dict | WebhookWatchedItem]domains: list[constants.WEBHOOK_DOMAIN_T] | None = Nonesecret: str | None = Nonesecrets: dict[str, str] | None = Nonetoken: bool | str | None = None ) → WebhookInfo
パラメータ
- url (
str) — ペイロードを送信するURL。 - job_id (
str) — 環境変数 WEBHOOK_PAYLOAD 内の Webhook ペイロードでトリガーするソース Job の ID。 利便性のため、追加の環境変数 WEBHOOK_REPO_ID、WEBHOOK_REPO_TYPE、WEBHOOK_SECRET が利用可能です。 - watched (
list[WebhookWatchedItem]) — Webhook が監視する WebhookWatchedItem のリストです。ユーザー、組織、モデル、データセット、スペース、バケットなどが対象となります。 監視対象は、プレーンな辞書として指定することもできます。 - domains (
list[Literal["repo", "discussion"]], 省略可) — 監視するドメインのリストです。“repo”、“discussion”、またはその両方を指定できます。デフォルトでは両方を監視します。 - secret (
str, 任意) — ペイロードに署名するためのシークレット。 - secrets (
dict[str, str], 省略可) — Webhook によってトリガーされる Job 用のシークレット環境変数です（例:{"HF_TOKEN": "hf_***"}）。job_idと併用する場合のみ有効です。ソース Job のシークレットは Webhook にコピーされないため、ここで渡す必要があります。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
新しく作成されたWebhookに関する情報。
新しいWebhookを作成します。
Webhookは、URLにペイロードを送信するか、Hugging Faceのインフラストラクチャ上でJobを実行するかのいずれかの動作をします。
この関数は、urlまたはjob_idのいずれか1つを引数として呼び出す必要がありますが、両方を指定することはできません。
例:
URLにペイロードを送信するWebhookを作成します
>>> from huggingface_hub import create_webhook
>>> payload = create_webhook(
... watched=[{"type": "user", "name": "julien-c"}, {"type": "org", "name": "HuggingFaceH4"}],
... url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
... domains=["repo", "discussion"],
... secret="my-secret",
... )
>>> print(payload)
WebhookInfo(
id="654bbbc16f2ec14d77f109cc",
url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
job=None,
watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
domains=["repo", "discussion"],
secret="my-secret",
disabled=False,
)Job を実行し、その後、この Job をトリガーする Webhook を作成します
>>> from huggingface_hub import create_webhook, run_job
>>> job = run_job(
... image="ubuntu",
... command=["bash", "-c", r"echo An event occurred in $WEBHOOK_REPO_ID: $WEBHOOK_PAYLOAD"],
... )
>>> payload = create_webhook(
... watched=[{"type": "user", "name": "julien-c"}, {"type": "org", "name": "HuggingFaceH4"}],
... job_id=job.id,
... domains=["repo", "discussion"],
... secret="my-secret",
... )
>>> print(payload)
WebhookInfo(
id="654bbbc16f2ec14d77f109cc",
url=None,
job=JobSpec(
docker_image='ubuntu',
space_id=None,
command=['bash', '-c', 'echo An event occurred in $WEBHOOK_REPO_ID: $WEBHOOK_PAYLOAD'],
arguments=[],
environment={},
secrets=[],
flavor='cpu-basic',
timeout=None,
tags=None,
arch=None
),
watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
domains=["repo", "discussion"],
secret="my-secret",
disabled=False,
)dataset_info
< source >( repo_id: strrevision: str | None = Nonetimeout: float | None = Nonefiles_metadata: bool = Falseexpand: list[ExpandDatasetProperty_T] | None = Nonetoken: bool | str | None = None ) → hf_api.DatasetInfo
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - revision (
str, 任意) — 情報を取得するデータセットリポジトリのリビジョン。 - timeout (
float, 任意) — Hub へのリクエストにタイムアウトを設定するかどうか。 - files_metadata (
bool, 省略可) — リポジトリ内のファイルのメタデータ（サイズ、LFS メタデータなど）を取得するかどうか。デフォルトはFalseです。 - expand (
list[ExpandDatasetProperty_T], 任意) — レスポンスで返すプロパティのリストを指定します。指定した場合、リストに含まれるプロパティのみが返されます。files_metadataが渡されている場合は、このパラメーターを使用できません。 指定可能な値は"author"、"cardData"、"citation"、"createdAt"、"disabled"、"description"、"downloads"、"downloadsAllTime"、"gated"、"lastModified"、"likes"、"mainSize"、"paperswithcode_id"、"private"、"siblings"、"sha"、"tags"、"trendingScore"、"usedStorage"、および"resourceGroup"です。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
データセットリポジトリの情報。
huggingface.co上の特定の1つのデータセットに関する情報を取得します。
Datasetは、許可されたトークンを渡すことでプライベートに設定できます。
以下のエラーを発生させます：
- RepositoryNotFoundError ダウンロード元のリポジトリが見つからない場合に発生します。存在しないか、
privateに設定されておりアクセス権限がないことが原因です。- RevisionNotFoundError ダウンロード元のリビジョンが見つからない場合に発生します。
delete_branch
< source >( repo_id: strbranch: strtoken: bool | str | None = Nonerepo_type: str | None = None )
パラメータ
- repo_id (
str) — ブランチが削除されるリポジトリ。 例:"user/my-cool-model"。 - branch (
str) — 削除するブランチの名前。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - repo_type (
str, 省略可) — データセットまたはスペースのブランチを作成する場合は"dataset"または"space"、モデルにタグを付ける場合はNoneまたは"model"を設定します。デフォルトはNoneです。
- RepositoryNotFoundError — リポジトリが見つからない場合（エラー 404）：repo_id/repo_type が誤っている、非公開リポジトリであるが認証されていない、またはリポジトリが存在しない。
- HfHubHTTPError —
保護されたブランチの削除を試みた場合。例:
mainは削除できません。 - HfHubHTTPError — 存在しないブランチの削除を試みた場合。
Hub上のリポジトリからブランチを削除します。
delete_bucket
< source >( bucket_id: strmissing_ok: bool = Falsetoken: bool | str | None = None )
パラメータ
- bucket_id (
str) — バケットの ID (例:"username/my-bucket")。 - missing_ok (
bool、省略可、デフォルトはFalse) —Trueの場合、バケットが存在しない場合にエラーを発生させません。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
例外
BucketNotFoundError
BucketNotFoundError— バケットが見つからず、missing_okがFalse（デフォルト）に設定されている場合。
Hubからバケットを削除します。
delete_collection
< source >( collection_slug: strmissing_ok: bool = Falsetoken: bool | str | None = None )
パラメータ
- collection_slug (
str) — 削除するコレクションのスラッグです。例:"TheBloke/recent-models-64f9a55bb3115b4f513ec026"。 - missing_ok (
bool、省略可) —Trueの場合、コレクションが存在しない場合にエラーを発生させません。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
Hub上のコレクションを削除します。
例:
>>> from huggingface_hub import delete_collection
>>> collection = delete_collection("username/useless-collection-64f9a55bb3115b4f513ec026", missing_ok=True)これは元に戻せない操作です。削除されたコレクションは復元できません。
delete_collection_item
< source >( collection_slug: stritem_object_id: strmissing_ok: bool = Falsetoken: bool | str | None = None )
パラメータ
- collection_slug (
str) — 更新するコレクションのスラッグです。例:"TheBloke/recent-models-64f9a55bb3115b4f513ec026"。 - item_object_id (
str) — コレクション内のアイテムのIDです。これは Hub 上のアイテムの ID（repo_id または paper id）ではありません。 CollectionItem オブジェクトから取得する必要があります。例:collection.items[0].item_object_id。 - missing_ok (
bool、省略可) —Trueの場合、アイテムが存在しない場合にエラーを発生させません。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
コレクションからアイテムを削除します。
例:
>>> from huggingface_hub import get_collection, delete_collection_item
# Get collection first
>>> collection = get_collection("TheBloke/recent-models-64f9a55bb3115b4f513ec026")
# Delete item based on its ID
>>> delete_collection_item(
... collection_slug="TheBloke/recent-models-64f9a55bb3115b4f513ec026",
... item_object_id=collection.items[-1].item_object_id,
... )delete_file
< source >( path_in_repo: strrepo_id: strtoken: str | bool | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecommit_message: str | None = Nonecommit_description: str | None = Nonecreate_pr: bool | None = Noneparent_commit: str | None = None )
パラメータ
- path_in_repo (
str) — リポジトリ内の相対ファイルパス。例:"checkpoints/1fec34a/weights.bin" - repo_id (
str) — ファイルが削除されるリポジトリ。例:"username/custom_transformers" - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - repo_type (
str, 省略可) — ファイルがデータセットまたはスペースにある場合は"dataset"または"space"、モデルにある場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - revision (
str, 省略可) — コミット元の git リビジョンです。デフォルトでは、"main"ブランチの先頭になります。 - commit_message (
str, 任意) — 生成されるコミットのサマリー / タイトル / 最初の行です。デフォルトはf"Delete {path_in_repo} with huggingface_hub"です。 - commit_description (
str, 省略可) — 生成されたコミットの説明 - create_pr (
boolean, 省略可) — そのコミットで Pull Request を作成するかどうか。デフォルトはFalseです。revisionが設定されていない場合、PR は"main"ブランチに対して作成されます。revisionが設定されておりブランチである場合、PR はそのブランチに対して作成されます。revisionが設定されているがブランチ名でない場合（例: コミット OID）、サーバーからRevisionNotFoundErrorが返されます。 - parent_commit (
str, 省略可能) — 親コミットの OID / SHA を16進数文字列として指定します。略記法（先頭7文字）もサポートされています。 指定され、create_prがFalseの場合、revisionがparent_commitを指していないとコミットは失敗します。 指定され、create_prがTrueの場合、parent_commitからプルリクエストが作成されます。parent_commitを指定することで、変更をコミットする前にリポジトリが変更されていないことを保証でき、リポジトリが並行して更新 / コミットされる場合に特に有用です。
指定されたリポジトリ内のファイルを削除します。
以下のエラーを発生させます：
- HuggingFace API がエラーを返した場合に
HTTPErrorValueError一部のパラメータ値が無効な場合- RepositoryNotFoundError ダウンロード元のリポジトリが見つからない場合に発生します。存在しないか、
privateに設定されておりアクセス権限がないことが原因です。- RevisionNotFoundError ダウンロード元のリビジョンが見つからない場合に発生します。
- EntryNotFoundError ダウンロード対象のファイルが見つからない場合。
delete_files
< source >( repo_id: strdelete_patterns: list[str]token: bool | str | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecommit_message: str | None = Nonecommit_description: str | None = Nonecreate_pr: bool | None = Noneparent_commit: str | None = None )
パラメータ
- repo_id (
str) — フォルダが削除されるリポジトリ。例:"username/custom_transformers" - delete_patterns (
list[str]) — 削除するファイルまたはフォルダーのリスト。各文字列は、ファイルパス、フォルダーパス、またはワイルドカードパターンであることができます。パターンは、こちらにドキュメント化されている Standard Wildcards (globbing patterns) です。 パターンマッチングはfnmatchに基づいています。 なお、fnmatchは従来の Unix シェルの globbing と異なり、*がパス境界をまたいでマッチします。 例:["file.txt", "folder/", "data/*.parquet"] - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを保存されたトークンに渡します。 - repo_type (
str, 任意) — ファイルを削除するリポジトリの種類。"model"、"dataset"、または"space"を指定できます。デフォルトは"model"です。 - revision (
str, 省略可) — コミット元の git リビジョンです。デフォルトでは、"main"ブランチの先頭になります。 - commit_message (
str, 任意) — 生成されたコミットのサマリー（最初の行）です。デフォルトはf"Delete files using huggingface_hub"です。 - commit_description (
str, 省略可) — 生成されたコミットの説明です。 - create_pr (
boolean, 省略可) — そのコミットで Pull Request を作成するかどうか。デフォルトはFalseです。revisionが設定されていない場合、PR は"main"ブランチに対して作成されます。revisionが設定されておりブランチである場合、PR はそのブランチに対して作成されます。revisionが設定されているがブランチ名でない場合（例: コミット OID）、サーバーからRevisionNotFoundErrorが返されます。 - parent_commit (
str, 省略可能) — 親コミットの OID / SHA を16進数文字列として指定します。略記法（先頭7文字）もサポートされています。 指定され、create_prがFalseの場合、revisionがparent_commitを指していないとコミットは失敗します。 指定され、create_prがTrueの場合、parent_commitからプルリクエストが作成されます。parent_commitを指定することで、変更をコミットする前にリポジトリが変更されていないことを保証でき、リポジトリが並行して更新 / コミットされる場合に特に有用です。
Hub上のリポジトリからファイルを削除します。
フォルダパスが指定された場合、そのフォルダ自体と、その中に含まれていたすべてのファイルが削除されます。
delete_folder
< source >( path_in_repo: strrepo_id: strtoken: bool | str | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecommit_message: str | None = Nonecommit_description: str | None = Nonecreate_pr: bool | None = Noneparent_commit: str | None = None )
パラメータ
- path_in_repo (
str) — リポジトリ内の相対フォルダパス。例:"checkpoints/1fec34a"。 - repo_id (
str) — フォルダが削除されるリポジトリ。例:"username/custom_transformers" - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを保存されたトークンに渡します。 - repo_type (
str, 省略可) — フォルダーがデータセットまたはスペースにある場合は"dataset"または"space"、モデルにある場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - revision (
str, 省略可) — コミット元の git リビジョンです。デフォルトでは、"main"ブランチの先頭になります。 - commit_message (
str, 任意) — 生成されるコミットのサマリー / タイトル / 最初の行です。デフォルトはf"Delete folder {path_in_repo} with huggingface_hub"です。 - commit_description (
str, 省略可) — 生成されたコミットの説明です。 - create_pr (
boolean, 省略可) — そのコミットで Pull Request を作成するかどうか。デフォルトはFalseです。revisionが設定されていない場合、PR は"main"ブランチに対して作成されます。revisionが設定されておりブランチである場合、PR はそのブランチに対して作成されます。revisionが設定されているがブランチ名でない場合（例: コミット OID）、サーバーからRevisionNotFoundErrorが返されます。 - parent_commit (
str, 省略可能) — 親コミットの OID / SHA を16進数文字列として指定します。略記法（先頭7文字）もサポートされています。 指定され、create_prがFalseの場合、revisionがparent_commitを指していないとコミットは失敗します。 指定され、create_prがTrueの場合、parent_commitからプルリクエストが作成されます。parent_commitを指定することで、変更をコミットする前にリポジトリが変更されていないことを保証でき、リポジトリが並行して更新 / コミットされる場合に特に有用です。
指定されたリポジトリ内のフォルダーを削除します。
create_commit() メソッドのシンプルなラッパーです。
delete_inference_endpoint
< source >( name: strnamespace: str | None = Nonetoken: bool | str | None = None )
パラメータ
- name (
str) — 削除する Inference Endpoint の名前。 - namespace (
str, 省略可) — Inference Endpoint が配置されている namespace です。デフォルトでは現在のユーザーになります。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
Inference Endpointを削除します。
この操作は元に戻せません。Inference Endpoint の課金を避けたい場合は、pause_inference_endpoint() で一時停止するか、scale_to_zero_inference_endpoint() でスケールをゼロにすることをお勧めします。
便宜のため、InferenceEndpoint.delete() を使用して Inference Endpoint を削除することもできます。
delete_repo
< source >( repo_id: strtoken: str | bool | None = Nonerepo_type: str | None = Nonemissing_ok: bool = False )
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - repo_type (
str, 任意) — データセットまたはスペースにアップロードする場合は"dataset"または"space"、モデルにアップロードする場合はNoneまたは"model"を設定します。 - missing_ok (
bool、省略可、デフォルトはFalse) —Trueの場合、リポジトリが存在しない場合にエラーを発生させません。
- RepositoryNotFoundError —
削除対象のリポジトリが見つからず、
missing_okがFalse（デフォルト）に設定されている場合。
HuggingFace Hubからリポジトリを削除します。注意: この操作は元に戻せません。
delete_scheduled_job
< source >( scheduled_job_id: strnamespace: str | None = Nonetoken: bool | str | None = None )
パラメータ
- scheduled_job_id (
str) — スケジュールされた Job の ID。 - namespace (
str, 省略可能) — スケジュールされた Job が存在する namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。
Hugging Face のインフラストラクチャ上でスケジュールされた compute Job を削除します。
delete_space_secret
< source >( repo_id: strkey: strtoken: bool | str | None = None )
パラメータ
- repo_id (
str) — 更新するリポジトリの ID。例:"bigcode/in-the-stack"。 - key (
str) — シークレットキー。例:"GITHUB_API_KEY"。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
Spaceからシークレットを削除します。
Secretsを使用すると、Spaceにシークレットキーやトークンを設定できますが、ハードコードする必要はありません。 詳細については、https://huggingface.co/docs/hub/spaces-overview#managing-secretsを参照してください。
delete_space_variable
< source >( repo_id: strkey: strtoken: bool | str | None = None )
パラメータ
- repo_id (
str) — 更新するリポジトリの ID。例:"bigcode/in-the-stack"。 - key (
str) — 変数のキー。例:"MODEL_REPO_ID" - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
Spaceから変数を削除します。
Variables を使用すると、Space にハードコードせずに環境変数を設定できます。 詳細については、https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables を参照してください。
delete_space_volumes
< source >( repo_id: strtoken: bool | str | None = None )
パラメータ
- repo_id (
str) — 更新する Space の ID。例:"username/my-space"。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
例外
BadRequestError
BadRequestError— Spaceにボリュームが接続されていない場合。
Spaceからすべてのボリュームを削除します。
delete_tag
< source >( repo_id: strtag: strtoken: bool | str | None = Nonerepo_type: str | None = None )
パラメータ
- repo_id (
str) — タグを削除するリポジトリ。 例:"user/my-cool-model"。 - tag (
str) — 削除するタグの名前。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - repo_type (
str, 任意) — データセットまたはスペースにタグを付ける場合は"dataset"または"space"、モデルにタグを付ける場合はNoneまたは"model"を設定します。デフォルトはNoneです。
- RepositoryNotFoundError — リポジトリが見つからない場合（エラー 404）：repo_id/repo_type が誤っている、非公開リポジトリであるが認証されていない、またはリポジトリが存在しない。
- RevisionNotFoundError — タグが見つからない場合。
Hub上のリポジトリからタグを削除します。
delete_webhook
< source >( webhook_id: strtoken: bool | str | None = None ) → None
パラメータ
- webhook_id (
str) — 削除する Webhook の一意の識別子です。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
None
Webhookを削除します。
disable_space_dev_mode
< source >( repo_id: strtoken: bool | str | None = None ) → SpaceRuntime
パラメータ
- repo_id (
str) — 開発モードを無効にする Space の ID。例:"Salesforce/BLIP2"。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Spaceのランタイムに関する情報。
例外
RepositoryNotFoundError または HfHubHTTPError または BadRequestError
- RepositoryNotFoundError — Space が見つからない場合（エラー 404）に発生します。おそらく repo_id が誤っているか、Space がプライベートであるにもかかわらず認証されていないことが原因です。
- HfHubHTTPError — 403 Forbidden: Spaceのdevモードを設定できるのは、そのSpaceの所有者のみです。所有していないSpaceを操作したい場合は、Discussionを開いて所有者に依頼するか、そのSpaceを複製してください。
- BadRequestError — Space が静的 Space の場合です。静的 Space は常に稼働しており、請求は発生しません。静的 Space を非表示にする場合は、プライベートに設定できます。
Spaceで開発モードを無効にします。
Spaces Dev Mode は、Space コンテナ自体を停止せずにアプリケーションを再起動できるため、アプリケーションのデバッグを容易にし、Spaces での反復開発を高速化します。Dev Mode を有効にするには PRO または Team & Enterprise プランが必要ですが、無効にする操作は常に許可されています（例：サブスクリプションの有効期限が切れた後）。詳細は https://huggingface.co/docs/hub/spaces-dev-mode を参照してください。
disable_webhook
< source >( webhook_id: strtoken: bool | str | None = None ) → WebhookInfo
パラメータ
- webhook_id (
str) — 無効化対象のWebhookの一意な識別子です。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
無効化されたWebhookに関する情報。
Webhookを無効化します（「無効」にします）。
例:
>>> from huggingface_hub import disable_webhook
>>> disabled_webhook = disable_webhook("654bbbc16f2ec14d77f109cc")
>>> disabled_webhook
WebhookInfo(
id="654bbbc16f2ec14d77f109cc",
url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
jon=None,
watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
domains=["repo", "discussion"],
secret="my-secret",
disabled=True,
)download_bucket_files
< source >( bucket_id: strfiles: list[tuple[str | BucketFile, str | Path]]raise_on_missing_files: bool = Falsetoken: str | bool | None = None )
パラメータ
- bucket_id (
str) — バケットの ID (例:"username/my-bucket")。 - files (
list[tuple[Union[str, BucketFile], Union[str, Path]]]) — タプル (source, destination) のリストとしてダウンロードするファイルです。形式の詳細については、上記の説明を参照してください。 - raise_on_missing_files (
bool, 省略可) —Trueの場合、要求されたファイルがバケットに存在しないときにEntryNotFoundErrorを発生させます。False(デフォルト) の場合、存在しないファイルは警告とともにスキップされます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
バケットからファイルをダウンロードします。
Files input は (remote file, local file) のタプルのリストで、remote file はバケット内のファイルのパスまたは BucketFile オブジェクト、local file はローカルファイルシステム上の宛先パスです。
BucketFile オブジェクト（list_bucket_tree() から取得したもの）を渡す場合、メソッドはメタデータの取得ステップをスキップして、ファイルを直接ダウンロードします。
例:
>>> from huggingface_hub import download_bucket_files
>>> download_bucket_files(
... bucket_id="username/my-bucket",
... files=[
... ("models/model.safetensors", "./local/model.safetensors"),
... ("config.json", "./local/config.json"),
... ],
... )>>> from huggingface_hub import download_bucket_files
>>> parquet_files = [file for file in list_bucket_tree(bucket_id="username/my-bucket") if file.path.endswith(".parquet")]
>>> download_bucket_files(
... bucket_id="username/my-bucket",
... files=[(file, f"./local/{file.path}") for file in parquet_files],
... )duplicate_repo
< source >( from_id: strto_id: str | None = Nonerepo_type: str | None = Noneprivate: bool | None = Nonevisibility: RepoVisibility_T | None = Nonetoken: bool | str | None = Noneexist_ok: bool = Falseresource_group_id: str | None = Nonespace_hardware: SpaceHardware | None = Nonespace_sleep_time: int | None = Nonespace_secrets: list[dict[str, str]] | None = Nonespace_variables: list[dict[str, str]] | None = Nonespace_volumes: list[Volume] | None = None ) → DuplicatedRepoUrl
パラメータ
- from_id (
str) — 複製するリポジトリの ID。例:"openai/gdpval"。 - to_id (
str, 省略可) — 新しいリポジトリの ID。例:"myorg/my-gdpval"。指定しない場合、新しいリポジトリは元のリポジトリと同じ名前になりますが、あなたのアカウント内に作成されます。 - repo_type (
str, 省略可) — データセットまたは Space を複製する場合は"dataset"または"space"、モデルを複製する場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - private (
bool、省略可) — 新しいリポジトリをプライベートにするかどうか。デフォルトでは、元のリポジトリと同じプライバシー設定が適用されます。visibilityと同時に指定することはできません。 - visibility (
Literal["public", "private", "protected"], 省略可) — 新しいリポジトリの公開設定。"public"または"private"、Spaces の場合は"protected"を指定できます。デフォルトでは、元のリポジトリと同じ公開設定が適用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - exist_ok (
bool、省略可能、デフォルトはFalse) —Trueの場合、リポジトリが既に存在していてもエラーを発生させません。 - resource_group_id (
str, 任意) — 新しいリポジトリを作成するリソースグループ。リソースグループは Enterprise Hub の組織でのみ利用可能であり、組織のどのメンバーがそのリソースにアクセスできるかを定義できます。リソースグループの ID は、Hub 上のリソースのページの URL から確認できます（例:"66670e5163145ca562cb1988"）。リソースグループの詳細については、https://huggingface.co/docs/hub/en/security-resource-groups を参照してください。 - space_hardware (
SpaceHardwareまたはstr、省略可能) — repo_type が “space” の場合の Hardware の選択です。例:"t4-medium"。 完全なリストについては SpaceHardware を参照してください。 - space_sleep_time (
int, 任意) — Space がスリープ状態に入るまで、待機状態を何秒間待つかを指定します。 Space をスリープさせたくない場合は-1を設定してください（アップグレードされたハードウェアのデフォルト動作です）。無料のハードウェアでは、スリープ時間を設定できません（値は 48 時間の待機に固定されています）。repo_type が “space” の場合にのみ適用されます。詳細は https://huggingface.co/docs/hub/spaces-gpus#sleep-time を参照してください。 - space_secrets (
list[dict[str, str]], 省略可) — Space に設定するシークレットキーのリストです。各項目は{"key": ..., "value": ..., "description": ...}の形式で、description は省略可能です。 repo_type が “space” の場合にのみ適用されます。 詳細については、https://huggingface.co/docs/hub/spaces-overview#managing-secrets を参照してください。 - space_variables (
list[dict[str, str]]、省略可) — Space で設定する公開環境変数のリストです。各項目は{"key": ..., "value": ..., "description": ...}の形式で、description は省略可能です。repo_type が “space” の場合のみ適用されます。詳細については、https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables を参照してください。 - space_volumes (
list[Volume], 省略可) — Space の複製時にマウントする Volume オブジェクトのリストです。各ボリュームには、type("bucket"、"model"、"dataset"、または"space")、source（リポジトリまたはバケットの ID）、mount_path（コンテナ内のパス）、および省略可能なrevision、read_only、pathフィールドがあります。 repo_type が “space” の場合のみ適用されます。
新しく作成されたリポジトリへのURL。値はendpoint、repo_type、repo_id、files_copy_pendingなどの属性を含む、RepoUrl（およびstr）のサブクラスです。
例外
RepositoryNotFoundError または HfHubHTTPError
- RepositoryNotFoundError —
from_idまたはto_idのいずれかが見つからない場合。存在しないか、privateに設定されていてアクセス権限がないことが原因です。 HfHubHTTPError— HuggingFace APIがエラーを返した場合
Hub上のリポジトリ（モデル、データセット、またはSpace）を複製します。
これは、ローカルでのダウンロード/アップロードの往復を必要とせずに、完全な git 履歴と LFS オブジェクトを保持したサーバーサイドのコピーを実行します。
git の履歴は即座にコピーされますが、このメソッドが返却された後も、LFS/Xet ファイルがバックグラウンドでコピーされ続ける場合があります。その場合、返却値の files_copy_pending は True となり、コピーが完了するまで新しいリポジトリからこれらのファイルをダウンロードしようとすると失敗する可能性があります。
例:
>>> from huggingface_hub import duplicate_repo
# Duplicate a model to your account
>>> repo_url = duplicate_repo("google/gemma-7b")
>>> repo_url
RepoUrl('https://huggingface.co/nateraw/gemma-7b',...)
>>> repo_url.files_copy_pending
True
# Duplicate a dataset with a custom name
>>> duplicate_repo("openai/gdpval", to_id="myorg/my-gdpval", repo_type="dataset")
RepoUrl('https://huggingface.co/datasets/myorg/my-gdpval',...)
# Duplicate a Space with custom hardware
>>> duplicate_repo("multimodalart/dreambooth-training", repo_type="space", space_hardware="t4-medium")
RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...)edit_discussion_comment
< source >( repo_id: strdiscussion_num: intcomment_id: strnew_content: strtoken: bool | str | None = Nonerepo_type: str | None = None ) → DiscussionComment
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - discussion_num (
int) — Discussion または Pull Request の番号です。正の整数である必要があります。 - comment_id (
str) — 編集するコメントのIDです。 - new_content (
str) — コメントの新しい内容です。コメントはMarkdown形式の書式に対応しています。 - repo_type (
str, 省略可) — データセットまたはスペースにアップロードする場合は"dataset"または"space"、モデルにアップロードする場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
編集されたコメント
Discussion / Pull Request のコメントを編集します。
以下のエラーを発生させます：
- HuggingFace API がエラーを返した場合に
HTTPErrorValueError一部のパラメータ値が無効な場合- RepositoryNotFoundError ダウンロード元のリポジトリが見つからない場合に発生します。存在しないか、
privateに設定されておりアクセス権限がないことが原因です。
enable_space_dev_mode
< source >( repo_id: strtoken: bool | str | None = None ) → SpaceRuntime
パラメータ
- repo_id (
str) — 開発モードを有効にする Space の ID。例:"Salesforce/BLIP2"。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Spaceのランタイムに関する情報。
例外
RepositoryNotFoundError または HfHubHTTPError または BadRequestError
- RepositoryNotFoundError — Space が見つからない場合（エラー 404）に発生します。おそらく repo_id が誤っているか、Space がプライベートであるにもかかわらず認証されていないことが原因です。
- HfHubHTTPError — 403 Forbidden: Spaceのdevモードを設定できるのは、そのSpaceの所有者のみです。所有していないSpaceを操作したい場合は、Discussionを開いて所有者に依頼するか、そのSpaceを複製してください。
- BadRequestError — Space が静的 Space の場合です。静的 Space は常に稼働しており、請求は発生しません。静的 Space を非表示にする場合は、プライベートに設定できます。
Spaceで開発モードを有効にします。
Spaces Dev Mode は、Space コンテナ自体を停止せずにアプリケーションを再起動できるため、アプリケーションのデバッグを容易にし、Spaces での反復開発を高速化します。この機能は、PRO または Team & Enterprise プランの一部として利用できます。詳細は https://huggingface.co/docs/hub/spaces-dev-mode を参照してください。
enable_webhook
< source >( webhook_id: strtoken: bool | str | None = None ) → WebhookInfo
パラメータ
- webhook_id (
str) — 有効化対象のWebhookの一意な識別子です。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
有効化されたWebhookに関する情報。
Webhookを有効化します（「アクティブ」状態になります）。
例:
>>> from huggingface_hub import enable_webhook
>>> enabled_webhook = enable_webhook("654bbbc16f2ec14d77f109cc")
>>> enabled_webhook
WebhookInfo(
id="654bbbc16f2ec14d77f109cc",
job=None,
url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
domains=["repo", "discussion"],
secret="my-secret",
disabled=False,
)fetch_job_logs
< source >( job_id: strnamespace: str | None = Nonefollow: bool = Falsetail: int | None = Nonetoken: bool | str | None = None )
パラメータ
- job_id (
str) — Job の ID。 - namespace (
str, 省略可能) — Job が実行されている namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - follow (
bool, 省略可) —Trueの場合、ジョブが完了するまでリアルタイムでログをストリーミングします（ブロッキング）。Falseの場合（デフォルト）、現在利用可能なログのみを取得して即座に返します（ノンブロッキング）。 - tail (
int, 省略可能) — ログから返す行数の最大値。follow=Trueと組み合わせると、最後の N 行から開始し、新しいログのストリーミングを続けます。follow=Falseの場合、現在利用可能なログから最後の N 行のみを返します。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。
Hugging Face のインフラストラクチャ上の compute Job からすべてのログを取得します。
例:
>>> from huggingface_hub import fetch_job_logs, run_job
>>> job = run_job(image="python:3.12", command=["python", "-c" ,"print('Hello from HF compute!')"])
>>> for log in fetch_job_logs(job_id=job.id):
... print(log)
Hello from HF compute!
>>> # Non-blocking: fetch only currently available logs
>>> for log in fetch_job_logs(job_id=job.id, follow=False):
... print(log)
>>> # Stream logs starting from the last 100 lines
>>> for log in fetch_job_logs(job_id=job.id, follow=True, tail=100):
... print(log)fetch_job_metrics
< source >( job_id: strnamespace: str | None = Nonefollow: bool = Falsetoken: bool | str | None = None )
パラメータ
- job_id (
str) — Job の ID。 - namespace (
str, 省略可能) — Job が実行されている namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - follow (
bool, 省略可) —Trueの場合、ジョブが完了するまでメトリクスをリアルタイムでストリーミングします（ブロッキング）。Falseの場合（デフォルト）、現在のメトリクスのみを取得して返します（ノンブロッキング）。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。
Hugging Faceのインフラストラクチャ上のcompute Jobからライブメトリクスを取得します。
例:
>>> from huggingface_hub import fetch_job_metrics, run_job
>>> job = run_job(image="python:3.12", command=["python", "-c" ,"print('Hello from HF compute!')"], flavor="a10g-small")
>>> for metrics in fetch_job_metrics(job_id=job.id):
... print(metrics)
{
"cpu_usage_pct": 0,
"cpu_millicores": 3500,
"memory_used_bytes": 1306624,
"memory_total_bytes": 15032385536,
"rx_bps": 0,
"tx_bps": 0,
"gpus": {
"882fa930": {
"utilization": 0,
"memory_used_bytes": 0,
"memory_total_bytes": 22836000000
}
},
"replica": "57vr7"
}
>>> # Stream metrics until the job completes
>>> for metrics in fetch_job_metrics(job_id=job.id, follow=True):
... print(metrics)fetch_space_logs
< source >( repo_id: strbuild: bool = Falsefollow: bool = Falsetoken: bool | str | None = None ) → Iterable[str]
パラメータ
- repo_id (
str) — Space の ID。例:"bigcode/in-the-stack"。 - build (
bool、省略可能、デフォルトはFalse) —Trueの場合、コンテナのビルドログを取得します（SpaceがBUILD_ERRORで停止している場合に便利です）。False（デフォルト）の場合、実行ログ、つまり実行中のアプリケーションのstdout/stderrを取得します。 - follow (
bool、省略可能、デフォルトはFalse) —Trueの場合、サーバーがストリームを閉じるかKeyboardInterruptが発生するまで、ログをリアルタイムで（ブロッキング方式で）ストリーミングします。False（デフォルト）の場合、現在バッファリングされているログのみを取得して即座に返します（ノンブロッキング、docker logsと同様の動作）。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。デフォルトでは、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。詳細は https://huggingface.co/docs/huggingface_hub/quick-start#authentication を参照してください。
戻り値
Iterable[str]
利用可能なログ行を生成するジェネレーター。
Hub上のSpaceの実行ログまたはビルドログを取得します。
Spaceのビルド失敗や実行時クラッシュのデバッグに有用です。特に、ブラウザでログを確認できないスクリプトやエージェント型ワークフローからの利用時に役立ちます。
例:
>>> from huggingface_hub import fetch_space_logs
>>> # Non-blocking: print currently available run logs and exit.
>>> for line in fetch_space_logs("username/my-space"):
... print(line, end="")
>>> # Debug a build failure:
>>> for line in fetch_space_logs("username/my-space", build=True):
... print(line, end="")
>>> # Stream run logs until the server closes the stream.
>>> for line in fetch_space_logs("username/my-space", follow=True):
... print(line, end="")file_exists
< source >( repo_id: strfilename: strrepo_type: str | None = Nonerevision: str | None = Nonetoken: str | bool | None = None )
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - filename (
str) — チェックするファイルの名前。例:"config.json" - repo_type (
str, 省略可) — データセットまたはスペースからリポジトリ情報を取得する場合は"dataset"または"space"、モデルからリポジトリ情報を取得する場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - revision (
str, 任意) — 情報を取得するリポジトリのリビジョンです。デフォルトは"main"ブランチです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
Hugging Face Hub上のリポジトリにファイルが存在するかどうかを確認します。
get_bucket_file_metadata
< source >( bucket_id: strremote_path: strtoken: str | bool | None = None ) → BucketFileMetadata
パラメータ
- bucket_id (
str) — バケットの ID (例:"username/my-bucket")。 - remote_path (
str) — バケット内のファイルのパス。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
サイズとxet情報を含むファイルのメタデータ。
バケット内のファイルのメタデータを取得します。
get_bucket_paths_info
< source >( bucket_id: strpaths: Iterable[str]token: str | bool | None = None ) → Iterable[BucketFile]
パラメータ
- bucket_id (
str) — バケットの ID (例:"username/my-bucket")。 - paths (
Iterable[str]) — 情報取得対象のパスです。存在しないパスは、例外を発生させることなく無視されます。 ファイルパスのみサポートされています。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Iterable[BucketFile]
BucketFile オブジェクトのイテラブルとしての、パスに関する情報。
バケットのパスに関する情報を取得します。
呼び出しは1000パスずつのバッチで行われます。結果は受信された時点で返されます。
例:
>>> from huggingface_hub import get_bucket_paths_info
>>> paths_info = get_bucket_paths_info("username/my-bucket", ["file.txt", "checkpoints/model.safetensors"])
>>> for info in paths_info:
... print(info)
BucketFile(type='file', path='file.txt', size=2379, xet_hash='96e637d9665bd35477b1908a23f2e254edfba0618dbd2d62f90a6baee7d139cf', mtime=datetime.datetime(2024, 9, 25, 15, 31, 2, 346000, tzinfo=datetime.timezone.utc))
BucketFile(type='file', path='checkpoints/model.safetensors', size=2408828, xet_hash='3ed0e9fefe788ddd61d1e26eba67057e9740a064b009256fbafadf6bb95785ca', mtime=datetime.datetime(2024, 9, 25, 15, 31, 2, 346000, tzinfo=datetime.timezone.utc))get_collection
< source >( collection_slug: strtoken: bool | str | None = None )
パラメータ
- collection_slug (
str) — Hub のコレクションのスラッグです。例:"TheBloke/recent-models-64f9a55bb3115b4f513ec026"。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
Hub上のCollectionに関する情報を取得します。
戻り値: Collection
例:
>>> from huggingface_hub import get_collection
>>> collection = get_collection("TheBloke/recent-models-64f9a55bb3115b4f513ec026")
>>> collection.title
'Recent models'
>>> len(collection.items)
37
>>> collection.items[0]
CollectionItem(
item_object_id='651446103cd773a050bf64c2',
item_id='TheBloke/U-Amethyst-20B-AWQ',
item_type='model',
position=88,
note=None
)get_dataset_leaderboard
< source >( repo_id: strbase_model_only: bool | None = Nonetoken: bool | str | None = Nonetimeout: float | None = None ) → list[DatasetLeaderboardEntry]
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名です。例:"allenai/olmOCR-bench"。 - base_model_only (
boolまたはNone、省略可能) — デフォルトでは、リーダーボードにはbase_model関係が宣言されていないモデル（つまり正規/ルートリポジトリ）のみが含まれます。これは Hub のデフォルトのリーダーボード表示と一致します。親モデルを宣言しているファインチューニング済みまたは派生リポジトリは除外されます。このフィルタを無効にして、モデルがベースモデルの関係を宣言しているかどうかに関わらず、すべての提出結果を含めるには、base_model_only=Falseを渡してください。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - timeout (
float, 任意) — Hub へのリクエストにタイムアウトを設定するかどうか。
戻り値
list[DatasetLeaderboardEntry]
ランキング順に並べられたリーダーボードのエントリを表すDatasetLeaderboardEntryオブジェクトのリスト。
Hub上のデータセットのリーダーボードを取得します。
リーダーボードは、指定されたベンチマークデータセットでの評価スコアに基づいてモデルをランキングします。すべてのデータセットにリーダーボードがあるわけではなく、評価結果が提出されたベンチマークデータセットのみが対象です。これにより、スコアをデータセット中心の視点で確認できます。モデル中心の視点で確認するには、expand=["evalResults"] を指定して model_info() を使用してください。
以下のエラーを発生させます：
- RepositoryNotFoundError リポジトリが見つからない場合。存在しないか、
privateに設定されておりアクセス権限がない可能性があります。- HfHubHTTPError データセットにリーダーボードがない場合。
例:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> leaderboard = api.get_dataset_leaderboard("allenai/olmOCR-bench")
>>> leaderboard[0].model_id
'datalab-to/chandra-ocr-2'
>>> leaderboard[0].rank
1
# Include fine-tuned / derivative models too
>>> full_leaderboard = api.get_dataset_leaderboard("allenai/olmOCR-bench", base_model_only=False)有効なデータセットタグをすべて、ネストされた名前空間オブジェクトとして一覧表示します。
get_discussion_details
< source >( repo_id: strdiscussion_num: intrepo_type: str | None = Nonetoken: bool | str | None = None )
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - discussion_num (
int) — Discussion または Pull Request の番号です。正の整数である必要があります。 - repo_type (
str, 省略可) — データセットまたはスペースにアップロードする場合は"dataset"または"space"、モデルにアップロードする場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
HubからDiscussion / Pull Requestの詳細を取得します。
以下のエラーを発生させます：
- HuggingFace API がエラーを返した場合に
HTTPErrorValueError一部のパラメータ値が無効な場合- RepositoryNotFoundError ダウンロード元のリポジトリが見つからない場合に発生します。存在しないか、
privateに設定されておりアクセス権限がないことが原因です。
get_full_repo_name
< source >( model_id: strorganization: str | None = Nonetoken: bool | str | None = None ) → str
パラメータ
- model_id (
str) — モデルの名前。 - organization (
str, 任意) — 指定した場合、リポジトリ名はユーザーネームスペースではなく、組織のネームスペースに配置されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
str
組織が指定されない場合はユーザーのネームスペース内のリポジトリ名（{username}/{model_id}）、指定される場合は組織のネームスペース内のリポジトリ名（{organization}/{model_id}）です。
指定されたモデルIDと任意の組織に対して、リポジトリ名を返します。
get_hf_file_metadata
< source >( url: strtoken: bool | str | None = Nonetimeout: float | None = 10 )
パラメータ
- url (
str) — ファイルの URL。例えば、hf_hub_url() が返すものなど。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - timeout (
float、任意、デフォルト値は 10)— サーバーがメタデータを送信するのを、諦める前に何秒間待つかを指定します。
指定されたURLの、Hub上でバージョン管理されているファイルのメタデータを取得します。
get_inference_endpoint
< source >( name: strnamespace: str | None = Nonetoken: bool | str | None = None ) → InferenceEndpoint
パラメータ
- name (
str) — 情報取得対象のInference Endpointの名前。 - namespace (
str, 省略可) — Inference Endpoint が配置されている namespace です。デフォルトでは現在のユーザーになります。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
要求されたInference Endpointに関する情報。
Inference Endpointに関する情報を取得します。
例:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> endpoint = api.get_inference_endpoint("my-text-to-image")
>>> endpoint
InferenceEndpoint(name='my-text-to-image', ...)
# Get status
>>> endpoint.status
'running'
>>> endpoint.url
'https://my-text-to-image.region.vendor.endpoints.huggingface.cloud'
# Run inference
>>> endpoint.client.text_to_image(...)有効なモデルタグをすべてネストされた名前空間オブジェクトとして一覧表示します
get_organization_overview
< source >( organization: strtoken: bool | str | None = None ) → Organization
パラメータ
- organization (
str) — 概要を取得する組織の名前。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Organization
組織の概要を含むOrganizationオブジェクト。
例外
HTTPError
HTTPError— Hub に組織が存在しない場合、HTTP 404 が返されます。
Hub上の組織の概要を取得します。
get_paths_info
< source >( repo_id: strpaths: list[str] | strexpand: bool = Falserevision: str | None = Nonerepo_type: str | None = Nonetoken: str | bool | None = None ) → list[Union[RepoFile, RepoFolder]]
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - paths (
Union[list[str], str], 任意) — 情報取得対象のパスです。存在しないパスは、例外を発生させることなく無視されます。 - expand (
bool、省略可能、デフォルトはFalse) — パスに関する追加情報（例: 最終コミットやファイルのセキュリティスキャン結果）を取得するかどうか。この操作はサーバーにとってコストが高いため、1ページあたりの結果は50件（1000件ではなく）に制限されます。ページネーションはhuggingface_hubで実装されているため、結果を取得するまでの時間がかかる点を除けば、ユーザーには透過的です。 - revision (
str, 任意) — 情報を取得するリポジトリのリビジョンです。デフォルトは"main"ブランチです。 - repo_type (
str, 省略可) — 情報を取得するリポジトリの種類（"model"、"dataset"、または"space"）。 デフォルトは"model"です。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
list[Union[RepoFile, RepoFolder]]
RepoFileオブジェクトとRepoFolderオブジェクトのリストとして、パスに関する情報。
- RepositoryNotFoundError — リポジトリが見つからない場合（エラー 404）: repo_id/repo_type が誤っている、プライベートリポジトリだが認証されていない、またはリポジトリが存在しない。
- RevisionNotFoundError — リポジトリ上でリビジョンが見つからない場合（エラー 404）。
リポジトリのパスに関する情報を取得します。
例:
>>> from huggingface_hub import get_paths_info
>>> paths_info = get_paths_info("allenai/c4", ["README.md", "en"], repo_type="dataset")
>>> paths_info
[
RepoFile(path='README.md', size=2379, blob_id='f84cb4c97182890fc1dbdeaf1a6a468fd27b4fff', lfs=None, last_commit=None, security=None),
RepoFolder(path='en', tree_id='dc943c4c40f53d02b31ced1defa7e5f438d5862e', last_commit=None)
]get_repo_discussions
< source >( repo_id: strauthor: str | None = Nonediscussion_type: constants.DiscussionTypeFilter | None = Nonediscussion_status: constants.DiscussionStatusFilter | None = Nonerepo_type: str | None = Nonetoken: bool | str | None = None ) → Iterator[Discussion]
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - author (
str, 省略可) — ディスカッションの著者で絞り込むために値を渡します。Noneはフィルタリングしないことを意味します。 デフォルトはNoneです。 - discussion_type (
str, 省略可) — プルリクエストのみを取得するには"pull_request"、ディスカッションのみを取得するには"discussion"を設定します。両方ともを取得するには"all"またはNoneを設定します。デフォルトはNoneです。 - discussion_status (
str, 省略可) —"open"(それぞれ"closed") に設定すると、オープン (それぞれクローズ) されたディスカッションのみを取得します。"all"またはNoneに設定すると、両方とも取得します。 デフォルトはNoneです。 - repo_type (
str, 省略可) — データセットまたはスペースから取得する場合は"dataset"または"space"、モデルから取得する場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Iterator[Discussion]
Discussionオブジェクトのイテレータ。
指定されたリポジトリのディスカッションとプルリクエストを取得します。
例:
get_safetensors_metadata
< source >( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonetoken: bool | str | None = Nonetimeout: float | None = 10 ) → SafetensorsRepoMetadata
パラメータ
- repo_id (
str) —/で区切られたユーザー名または組織名とリポジトリ名。 - repo_type (
str, 省略可) — ファイルがデータセットまたはスペースにある場合は"dataset"または"space"、モデルにある場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - revision (
str, 省略可) — ファイルを取得する git リビジョンです。ブランチ名、タグ、またはコミットハッシュを指定できます。デフォルトでは、"main"ブランチの先頭が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - timeout (
float、省略可、デフォルト値は 10)— サーバーがデータを送信するのを、諦める前に何秒間待つかを指定します。safetensors ファイルのヘッダーを取得する各リクエストに渡されます。タイムアウトを無効にするにはNoneを設定してください（接続が停止した際に呼び出しが無限にハングする可能性があるため、非推奨です）。
戻り値
SafetensorsRepoMetadata
safetensorsリポジトリに関する情報。
例外
NotASafetensorsRepoError または SafetensorsParsingError
NotASafetensorsRepoError— リポジトリがsafetensorsのリポジトリでない場合、つまりmodel.safetensorsファイルまたはmodel.safetensors.index.jsonファイルのいずれも存在しない場合に発生します。SafetensorsParsingError— safetensorsファイルのヘッダーを正しく解析できなかった場合に発生します。
Hub上のsafetensorsリポジトリのメタデータを解析します。
まず、リポジトリが単一のsafetensorsファイルか、シャード化されたsafetensorsリポジトリかをチェックします。単一のsafetensorsファイルの場合は、このファイルからメタデータを解析します。シャード化されたsafetensorsリポジトリの場合は、インデックスファイルからメタデータを解析し、その後、各シャードからメタデータを解析します。
単一のsafetensorsファイルからメタデータを解析するには、parse_safetensors_file_metadata()を使用します。
main上のシャード化されたモデルのすべてのシャードヘッダーを1回のリクエストで取得するには、get_sharded_safetensors_metadata()を使用します。
safetensors形式の詳細については、https://huggingface.co/docs/safetensors/index#formatを参照してください。
例:
# Parse repo with single weights file
>>> metadata = get_safetensors_metadata("bigscience/bloomz-560m")
>>> metadata
SafetensorsRepoMetadata(
metadata=None,
sharded=False,
weight_map={'h.0.input_layernorm.bias': 'model.safetensors', ...},
files_metadata={'model.safetensors': SafetensorsFileMetadata(...)}
)
>>> metadata.files_metadata["model.safetensors"].metadata
{'format': 'pt'}
# Parse repo with sharded model
>>> metadata = get_safetensors_metadata("bigscience/bloom")
Parse safetensors files: 100%|██████████████████████████████████████████| 72/72 [00:12<00:00, 5.78it/s]
>>> metadata
SafetensorsRepoMetadata(metadata={'total_size': 352494542848}, sharded=True, weight_map={...}, files_metadata={...})
>>> len(metadata.files_metadata)
72 # All safetensors files have been fetched
# Parse repo with sharded model
>>> get_safetensors_metadata("runwayml/stable-diffusion-v1-5")
NotASafetensorsRepoError: 'runwayml/stable-diffusion-v1-5' is not a safetensors repo. Couldn't find 'model.safetensors.index.json' or 'model.safetensors' files.get_sharded_safetensors_metadata
< source >( repo_id: strfilename: str = 'model.safetensors.index.json'token: bool | str | None = Nonetimeout: float | None = 10 ) → SafetensorsRepoMetadata
パラメータ
- repo_id (
str) —/で区切られたユーザー名または組織名とリポジトリ名。 - filename (
str, オプション) — リポジトリ内のsafetensorsインデックスファイルのパスです。デフォルトは"model.safetensors.index.json"です。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - timeout (
float、任意、デフォルト値は 10)— サーバーからデータを受信するのを、何秒待ってから諦めるかを指定します。Noneに設定するとタイムアウトが無効になります（接続が停止した際に呼び出しが無限にハングする可能性があるため、推奨されません）。
戻り値
SafetensorsRepoMetadata
get_safetensors_metadata() と同じメタデータ。
mainのHub上のシャード化されたsafetensorsモデルのすべてのシャードのメタデータを、get_safetensors_metadata()が各シャードのヘッダーを解析する代わりに、単一のリクエストで取得します。Hugging Face Hubのみ。
get_space_runtime
< source >( repo_id: strtoken: bool | str | None = None ) → SpaceRuntime
パラメータ
- repo_id (
str) — 更新するリポジトリの ID。例:"bigcode/in-the-stack"。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Spaceのステージやハードウェアなど、Spaceに関するランタイム情報。
Spaceのランタイム情報を取得します。
get_space_secrets
< source >( repo_id: strtoken: bool | str | None = None ) → dict[str, SpaceSecret]
パラメータ
- repo_id (
str) — クエリ対象のリポジトリの ID。例:"bigcode/in-the-stack"。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
dict[str, SpaceSecret]
シークレット名をキーとするSpaceSecretオブジェクトの辞書。
Spaceからすべてのシークレットを取得します。
シークレット値は書き込み専用であり、読み戻すことはできません。返されるのはキー、説明、最終更新時刻のみです。
Secretsを使用すると、Spaceにシークレットキーやトークンを設定できますが、ハードコードする必要はありません。 詳細については、https://huggingface.co/docs/hub/spaces-overview#managing-secretsを参照してください。
get_space_variables
< source >( repo_id: strtoken: bool | str | None = None )
パラメータ
- repo_id (
str) — クエリ対象のリポジトリの ID。例:"bigcode/in-the-stack"。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
Spaceからすべての変数を取得します。
Variables を使用すると、Space にハードコードせずに環境変数を設定できます。 詳細については、https://huggingface.co/docs/hub/spaces-overview#managing-secrets-and-environment-variables を参照してください。
get_user_overview
< source >( username: strtoken: bool | str | None = None ) → User
パラメータ
- username (
str) — 概要を取得するユーザーのユーザー名。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
User
ユーザーの概要を含むUserオブジェクト。
例外
HfHubHTTPError
HfHubHTTPError— ユーザーが Hub に存在しない場合、HTTP 404 が返されます。
Hub上のユーザーの概要を取得します。
get_webhook
< source >( webhook_id: strtoken: bool | str | None = None ) → WebhookInfo
パラメータ
- webhook_id (
str) — 取得する Webhook の一意の識別子です。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Webhookに関する情報。
idを指定してWebhookを取得します。
例:
>>> from huggingface_hub import get_webhook
>>> webhook = get_webhook("654bbbc16f2ec14d77f109cc")
>>> print(webhook)
WebhookInfo(
id="654bbbc16f2ec14d77f109cc",
job=None,
watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
secret="my-secret",
domains=["repo", "discussion"],
disabled=False,
)get_zero_gpu_quota
< source >( token: bool | str | None = None ) → ZeroGpuQuota
パラメータ
- token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。ファイングレイントークンには「Billing > Read billing usage and payment method status」の権限が必要であり、OAuth トークンにはread-billingスコープが必要です。
戻り値
認証済みユーザーのZeroGPUクォータ。
認証済みユーザーのZeroGPUクォータを取得します。
ZeroGPU Spaces をプログラムから呼び出す際（アプリ、エージェント、MCP サーバーなどから）の ZeroGPU 使用状況を追跡するのに便利です。詳細は https://huggingface.co/docs/hub/spaces-zerogpu を参照してください。
例:
>>> from huggingface_hub import get_zero_gpu_quota
>>> quota = get_zero_gpu_quota()
>>> quota
ZeroGpuQuota(base=2400, remaining=1810, resets_at=datetime.datetime(2026, 9, 30, 9, 12, 3, tzinfo=datetime.timezone.utc), overquota_used=0)
>>> print(f"{quota.remaining / 60:.1f} minutes left")
30.2 minutes leftgrant_access
< source >( repo_id: struser: strrepo_type: str | None = Nonetoken: bool | str | None = None )
パラメータ
- repo_id (
str) — アクセス権を付与するリポジトリのIDです。 - user (
str) — アクセス権限を付与するユーザーのユーザー名です。 - repo_type (
str, 省略可) — アクセス権を付与するリポジトリの種類です。model、dataset、spaceのいずれかである必要があります。 デフォルト値はmodelです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
例外
HfHubHTTPError
HfHubHTTPError— リポジトリがゲート付きでない場合、HTTP 400 が返されます。HfHubHTTPError— ユーザーがすでにリポジトリにアクセス権限を持っている場合、HTTP 400 が返されます。HfHubHTTPError— リポジトリへのアクセス権限が読み取り専用の場合、HTTP 403 が返されます。リポジトリが属する組織でwriteまたはadminのロールを持っていない場合、またはreadトークンを渡した場合に、この状況が発生し得ます。HfHubHTTPError— ユーザーが Hub に存在しない場合、HTTP 404 が返されます。
指定されたゲート付きリポジトリに対して、ユーザーへのアクセス権を付与します。
アクセス権限の付与には、ユーザー自身がアクセスリクエストを送信する必要はありません。ユーザーは自動的に承認リストに追加され、ファイルをダウンロードできるようになります。付与したアクセス権限は、cancel_access_request()またはreject_access_request()を使用して、いつでも取り消すことができます。
ゲート付きリポジトリの詳細については、https://huggingface.co/docs/hub/models-gatedを参照してください。
hf_hub_download
< source >( repo_id: strfilename: strsubfolder: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | Path | None = Nonelocal_dir: str | Path | None = Noneforce_download: bool = Falseetag_timeout: float = 10token: bool | str | None = Nonelocal_files_only: bool = Falsetqdm_class: type[base_tqdm] | None = Nonedry_run: bool = False ) → str or DryRunFileInfo
パラメータ
- repo_id (
str) —/で区切られたユーザー名または組織名とリポジトリ名。 - filename (
str) — リポジトリ内のファイル名です。 - subfolder (
str、省略可) — リポジトリ内のフォルダーに対応する省略可能な値です。 - repo_type (
str, 任意) — データセットまたはスペースからダウンロードする場合は"dataset"または"space"、モデルからダウンロードする場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - revision (
str, 省略可) — ブランチ名、タグ、またはコミットハッシュである、任意の Git リビジョン ID。 - cache_dir (
str,Path, 省略可) — キャッシュされたファイルを保存するフォルダへのパス。 - local_dir (
strまたはPath、任意) — 指定された場合、ダウンロードされたファイルはこのディレクトリ以下に配置されます。 - force_download (
bool、任意、デフォルトはFalse) — ローカルキャッシュに既に存在する場合でも、ファイルをダウンロードするかどうか。 - etag_timeout (
float、任意、デフォルトは10) — ETagを取得する際、httpx2.requestに渡される、サーバーからデータを受信するまでの待機秒数(タイムアウト)です。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - local_files_only (
bool、任意、デフォルトはFalse) —Trueの場合、ファイルのダウンロードを回避し、ローカルにキャッシュされたファイルが存在する場合はそのパスを返します。 - tqdm_class (
tqdm、任意) — 指定された場合、プログレスバーのデフォルトの動作を上書きします。渡される引数はtqdm.auto.tqdmを継承するか、少なくともその動作を模倣している必要があります。デフォルトでは、HF_HUB_DISABLE_PROGRESS_BARS環境変数を設定することで無効化できる、HF独自のプログレスバーが使用されます。 - dry_run (
bool、省略可、デフォルトはFalse) —Trueの場合、ファイルをダウンロードせずにドライランを実行します。ダウンロードされる内容に関する情報を含むDryRunFileInfoオブジェクトを返します。
戻り値
str または DryRunFileInfo
dry_run=Falseの場合: ファイルのローカルパス、またはネットワークがオフの場合はディスクにキャッシュされたファイルの最終バージョン。dry_run=Trueの場合: ダウンロード情報を含むDryRunFileInfoオブジェクト。
例外
RepositoryNotFoundError または RevisionNotFoundError または ~utils.RemoteEntryNotFoundError または LocalEntryNotFoundError または EnvironmentError または OSError または ValueError
- RepositoryNotFoundError —
ダウンロード元のリポジトリが見つからない場合に発生します。存在しないか、
privateに設定されておりアクセス権限がないことが原因です。 - RevisionNotFoundError — ダウンロード元のリビジョンが見つからない場合。
~utils.RemoteEntryNotFoundError— ダウンロード対象のファイルが見つからない場合。- LocalEntryNotFoundError — ネットワークが無効または利用不可で、ファイルがキャッシュに見つからない場合。
EnvironmentError—token=Trueであるが、トークンが見つからない場合。OSError— ETag を決定できない場合。ValueError— パラメータの値が無効な場合。
ローカルキャッシュに存在しない場合、指定されたファイルをダウンロードします。
新しいキャッシュファイルのレイアウトは以下のようになります:
- cache ディレクトリには、repo_id ごとに1つのサブフォルダが含まれます（リポジトリタイプで名前空間が区切られています）。
- 各リポジトリフォルダ内には以下が含まれます:
- refs は、最新既知の revision => commit_hash のペアのリストです
- blobsには、実際のファイルのブロブが含まれています（LFSファイルかどうかによって、git-shaまたはsha256で識別されます）。
- snapshotsにはコミットごとに1つのサブフォルダが含まれており、各「コミット」には、その特定のコミット時点で解決されたファイルのサブセットが含まれます。各ファイル名は、その特定のコミット時点のblobへのシンボリックリンクです。
[ 96] .
└── [ 160] models--julien-c--EsperBERTo-small
├── [ 160] blobs
│ ├── [321M] 403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
│ ├── [ 398] 7cb18dc9bafbfcf74629a4b760af1b160957a83e
│ └── [1.4K] d7edf6bd2a681fb0175f7735299831ee1b22b812
├── [ 96] refs
│ └── [ 40] main
└── [ 128] snapshots
├── [ 128] 2439f60ef33a0d46d85da5001d52aeda5b00ce9f
│ ├── [ 52] README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
│ └── [ 76] pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
└── [ 128] bbc77c8132af1cc5cf678da3f1ddf2de43606d48
├── [ 52] README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e
└── [ 76] pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bdlocal_dir が指定されている場合、リポジトリのファイル構造がこの場所に複製されます。このオプションを使用すると、cache_dir は使用されず、local_dir のルートに .cache/huggingface/ フォルダが作成され、ダウンロードされたファイルに関連する一部のメタデータが保存されます。この仕組みはメインのキャッシュシステムほど堅牢ではありませんが、リポジトリの最新バージョンを定期的に取得するために最適化されています。
hide_discussion_comment
< source >( repo_id: strdiscussion_num: intcomment_id: strtoken: bool | str | None = Nonerepo_type: str | None = None ) → DiscussionComment
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - discussion_num (
int) — Discussion または Pull Request の番号です。正の整数である必要があります。 - comment_id (
str) — 編集するコメントのIDです。 - repo_type (
str, 省略可) — データセットまたはスペースにアップロードする場合は"dataset"または"space"、モデルにアップロードする場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
非表示のコメント
Discussion / Pull Request のコメントを非表示にします。
非表示コメントの内容はもう取得できません。コメントの非表示は元に戻せません。
以下のエラーを発生させます：
- HuggingFace API がエラーを返した場合に
HTTPErrorValueError一部のパラメータ値が無効な場合- RepositoryNotFoundError ダウンロード元のリポジトリが見つからない場合に発生します。存在しないか、
privateに設定されておりアクセス権限がないことが原因です。
inspect_job
< source >( job_id: strnamespace: str | None = Nonetoken: bool | str | None = None )
パラメータ
- job_id (
str) — Job の ID。 - namespace (
str, 省略可能) — Job が実行されている namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。
Hugging Faceのインフラストラクチャ上で実行されているCompute Jobを検査します。
例:
>>> from huggingface_hub import inspect_job, run_job
>>> job = run_job(image="python:3.12", command=["python", "-c" ,"print('Hello from HF compute!')"])
>>> inspect_job(job_id=job.id)
JobInfo(
id='68780d00bbe36d38803f645f',
created_at=datetime.datetime(2025, 7, 16, 20, 35, 12, 808000, tzinfo=datetime.timezone.utc),
docker_image='python:3.12',
space_id=None,
command=['python', '-c', "print('Hello from HF compute!')"],
arguments=[],
environment={},
secrets={},
flavor='cpu-basic',
status=JobStatus(stage='RUNNING', message=None)
)inspect_scheduled_job
< source >( scheduled_job_id: strnamespace: str | None = Nonetoken: bool | str | None = None )
パラメータ
- scheduled_job_id (
str) — スケジュールされた Job の ID。 - namespace (
str, 省略可能) — スケジュールされた Job が存在する namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。
Hugging Faceのインフラストラクチャ上でスケジュールされた計算Jobを検査します。
kernel_info
< source >( repo_id: strrevision: str | None = Nonetimeout: float | None = Nonetoken: bool | str | None = None ) → ModelInfo
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - revision (
str, 任意) — カーネルリポジトリから情報を取得する際のリビジョン。 - timeout (
float, 任意) — Hub へのリクエストにタイムアウトを設定するかどうか。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
カーネルリポジトリの情報。
huggingface.co上の特定の1つのカーネルに関する情報を取得します。
list_accepted_access_requests
< source >( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = None ) → Iterable[AccessRequest]
パラメータ
- repo_id (
str) — アクセスリクエストを取得するリポジトリのIDです。 - repo_type (
str, 省略可) — アクセス要求を取得するリポジトリの種類。model、dataset、spaceのいずれかである必要があります。 デフォルトはmodelです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Iterable[AccessRequest]
AccessRequestオブジェクトのイテラブルです。各アイテムには、username、request_id、email、status、timestampという属性が含まれます。ゲート付きリポジトリにカスタムフォームがある場合、fields属性にはユーザーの回答が設定されます。
例外
HfHubHTTPError
HfHubHTTPError— リポジトリがゲート付きでない場合、HTTP 400 が返されます。HfHubHTTPError— リポジトリへのアクセス権限が読み取り専用の場合、HTTP 403 が返されます。リポジトリが属する組織でwriteまたはadminのロールを持っていない場合、またはreadトークンを渡した場合に、この状況が発生し得ます。
指定されたゲート付きリポジトリの承認済みアクセスリクエストを取得します。
承認されたリクエストとは、ユーザーがリポジトリへのアクセスをリクエストし、そのリクエストが承認されたことを意味します。ユーザーはリポジトリ内の任意のファイルをダウンロードできます。承認モードが自動の場合、このリストにはデフォルトですべてのリクエストが含まれる必要があります。承認されたリクエストは、cancel_access_request()およびreject_access_request()を使用して、いつでもキャンセルまたは拒否できます。キャンセルされたリクエストは保留リストに戻り、拒否されたリクエストは拒否リストに移動します。どちらの場合も、ユーザーはリポジトリへのアクセスを失います。
ゲート付きリポジトリの詳細については、https://huggingface.co/docs/hub/models-gatedを参照してください。
例:
>>> from huggingface_hub import list_accepted_access_requests
>>> requests = list(list_accepted_access_requests("meta-llama/Llama-2-7b"))
>>> len(requests)
411
>>> requests[0]
[
AccessRequest(
username='clem',
request_id='655f3a1c9e6b2d4f8a7c1e05',
fullname='Clem 🤗',
email='***',
timestamp=datetime.datetime(2023, 11, 23, 18, 4, 53, 828000, tzinfo=datetime.timezone.utc),
status='accepted',
fields=None,
),
...
]list_bucket_tree
< source >( bucket_id: strprefix: str | None = Nonerecursive: bool | None = Nonetoken: str | bool | None = None ) → Iterable[Union[BucketFile, BucketFolder]]
パラメータ
- bucket_id (
str) — バケットの ID (例:"username/my-bucket")。 - prefix (
str, 任意) — このプレフィックスで始まるパスを持つファイルに結果を絞り込みます。 - recursive (
bool, 省略可) —Trueの場合、ファイルを再帰的に一覧表示します。False(デフォルト) の場合、ルートディレクトリ内のファイルとディレクトリのみを一覧表示します。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Iterable[Union[BucketFile, BucketFolder]]
ファイルおよびディレクトリの情報（パスなど）を含む、BucketFileおよびBucketFolderオブジェクトのイテラブル
バケット内のファイルをリスト表示します。
list_buckets
< source >( namespace: str | None = Nonesearch: str | None = Nonetoken: bool | str | None = None ) → Iterable[BucketInfo]
パラメータ
- namespace (
str, 省略可) — この namespace（ユーザーまたは組織）配下のバケットをリスト表示します。デフォルトでは、ユーザーのバケットをリスト表示します。 - search (
str, 任意) — バケット名を絞り込むための検索文字列。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Iterable[BucketInfo]
BucketInfoオブジェクトのイテラブル。
特定のネームスペースの下にあるHubのバケットをリスト表示します。
例:
>>> from huggingface_hub import list_buckets
>>> for bucket in list_buckets(): # lists buckets in the user's namespace
... print(bucket)
>>> for bucket in list_buckets(namespace="huggingface"): # lists buckets in the "huggingface" organization
... print(bucket)
>>> for bucket in list_buckets(search="my-prefix"): # filter buckets by name
... print(bucket)list_collections
< source >( owner: list[str] | str | None = Noneitem: list[str] | str | None = Nonesort: CollectionSort_T | None = Nonelimit: int | None = Nonetoken: bool | str | None = None ) → Iterable[Collection]
パラメータ
- owner (
list[str]またはstr、省略可) — オーナーのユーザー名でフィルタリングします。 - item (
list[str]またはstr、省略可能) — 特定のアイテムを含むコレクションをフィルタリングします。例:"models/teknium/OpenHermes-2.5-Mistral-7B"、"datasets/squad"または"papers/2311.12983"。 - sort (
Literal["lastModified", "trending", "upvotes"], 任意) — コレクションを最終更新日時、トレンド、またはアップボートの順に並べ替えます。 - limit (
int, 省略可能) — 返されるコレクションの最大数。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Iterable[Collection]
Collectionオブジェクトのイテラブル。
いくつかのフィルターを指定して、Huggingface Hub上のコレクションをリスト表示します。
コレクションをリスト表示する際、各コレクションのアイテムリストは最大4件に切り詰められます。コレクションのすべてのアイテムを取得するには、get_collection()を使用する必要があります。
list_daily_papers
< source >( date: str | None = Nonetoken: bool | str | None = Noneweek: str | None = Nonemonth: str | None = Nonesubmitter: str | None = Nonesort: DailyPapersSort_T | None = Nonep: int | None = Nonelimit: int | None = None ) → Iterable[PaperInfo]
パラメータ
- date (
str, 任意) — 日次ペーパーを取得する日付 (ISO 形式: YYYY-MM-DD)。 デフォルトでは、最新のものが使用されます。 - token (Union[bool, str, None], 任意) —
有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されているトークンが使用されます。認証を無効にするには、
Falseを渡します。 - week (
str, 任意) — ISO形式（YYYY-Www）で、日次ペーパーを取得する対象の週を指定します。例:2025-W09。 - month (
str, 任意) — 日次論文を取得する対象の月（ISO形式 YYYY-MM）。例:2025-02。 - submitter (
str, 省略可) — フィルタリング対象のデイリーペーパーの提出者のユーザー名。 - sort (
Literal["publishedAt", "trending"], 任意) — デイリーペーパーの並び順。publishedAtまたはtrendingのいずれかです。 デフォルトは"publishedAt"です。 - p (
int, 省略可能) — ページネーション用のページ番号。デフォルトは 0 です。 - limit (
int, 任意) — 取得する論文の上限数。デフォルトは 50 です。
戻り値
Iterable[PaperInfo]
huggingface_hub.hf_api.PaperInfoオブジェクトのイテラブルです。
Hugging Face Hubで指定した日に日に公開されたデイリーペーパーをリスト表示します。
list_dataset_parquet_files
< source >( repo_id: strconfig: str | None = Nonetoken: bool | str | None = None ) → list[DatasetParquetEntry]
パラメータ
- repo_id (
str) — データセットのリポジトリ ID（例:"username/dataset-name"）。 - config (
str, 任意) — 特定の config/サブセット名でフィルタリングします。指定した場合、その config に対応する parquet ファイルのみが返されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
list[DatasetParquetEntry]
DatasetParquetEntryオブジェクトのリスト。各parquetファイルの設定、split、URL、サイズが含まれます。
Hub上のデータセットで利用可能なparquetファイルをリスト表示します。
Hub にホストされているすべてのデータセットは、Dataset Viewer によって自動的に Parquet に変換されます。 このメソッドは、Parquet ファイルのリストを、それぞれの URL、config、split、サイズとともに返します。
list_datasets
< source >( filter: str | Iterable[str] | None = Noneauthor: str | None = Nonebenchmark: Literal[True] | Literal['official'] | str | None = Nonedataset_name: str | None = Nonegated: bool | None = Nonelanguage_creators: str | list[str] | None = Nonelanguage: str | list[str] | None = Nonemultilinguality: str | list[str] | None = Nonesize_categories: str | list[str] | None = Nonetask_categories: str | list[str] | None = Nonetask_ids: str | list[str] | None = Nonesearch: str | None = Nonesort: DatasetSort_T | None = Nonelimit: int | None = Noneexpand: list[ExpandDatasetProperty_T] | None = Nonefull: bool | None = Nonetoken: bool | str | None = None ) → Iterable[DatasetInfo]
パラメータ
- filter (
strまたはIterable[str]、省略可能) — Hub上のデータセットをフィルタリングするための文字列または文字列のリスト。 - author (
str, 省略可) — 返されるデータセットの著者を識別する文字列。 - benchmark (
True、"official"、str、省略可) — ベンチマークによってデータセットをフィルタリングします。Trueまたは"official"を指定すると、公式ベンチマークのデータセットが返されます。将来の互換性を考慮し、ベンチマーク名を表す文字列（現在サポートされているのは “official” のみ）も指定できます。 - dataset_name (
str, 任意) — Hub 上でSQACやwikineuralのように、名前によってデータセットを識別するために使用できる文字列または文字列のリスト - gated (
bool, 省略可) — Hub上のデータセットがゲート付きかどうかでフィルタリングするためのブール値です。デフォルトでは、すべてのデータセットが返されます。gated=Trueを渡すと、ゲート付きのデータセットのみが返されます。gated=Falseを渡すと、ゲートなしのデータセットのみが返されます。 - language_creators (
strまたはList、省略可) — Hub 上のデータセットを、データのキュレーション方法（crowdsourcedやmachine_generatedなど）で識別するために使用できる文字列または文字列のリスト。 - language (
strまたはList、省略可) — Hub でデータセットを絞り込むための 2 文字の言語を表す文字列または文字列のリスト。 - multilinguality (
strまたはList、省略可) — 複数の言語を含むデータセットに対するフィルタを表す文字列または文字列のリスト。 - size_categories (
strまたはList、省略可) —100K<n<1Mや1M<n<10Mのように、データセットのサイズによって Hub 上のデータセットを識別するために使用できる文字列または文字列のリストです。 - task_categories (
strまたはList、省略可) — Hub 上で、audio_classificationやnamed_entity_recognitionのような設計されたタスクによってデータセットを識別するために使用できる文字列または文字列のリストです。 - task_ids (
strまたはList、省略可) —speech_emotion_recognitionやparaphraseのような特定のタスクによって、Hub 上のデータセットを識別するために使用できる文字列または文字列のリストです。 - search (
str, 任意) — 返されるデータセットに含まれる文字列。 - sort (
DatasetSort_T, optional) — 結果のデータセットをソートするためのキー。指定可能な値は “created_at”、“downloads”、“last_modified”、“likes”、“trending_score” です。 - limit (
int, 任意) — 取得するデータセット数の上限です。このオプションをNoneにすると、すべてのデータセットが取得されます。 - expand (
list[ExpandDatasetProperty_T], 任意) — レスポンスで返すプロパティのリスト。指定した場合、リストに含まれるプロパティのみが返されます。fullが渡されている場合は、このパラメーターを使用できません。 指定可能な値は"author"、"cardData"、"citation"、"createdAt"、"disabled"、"description"、"downloads"、"downloadsAllTime"、"gated"、"lastModified"、"likes"、"mainSize"、"paperswithcode_id"、"private"、"siblings"、"sha"、"tags"、"trendingScore"、"usedStorage"、および"resourceGroup"です。 - full (
bool, 省略可) —last_modified、card_data、ファイルを含む、すべてのデータセットデータを取得するかどうかを指定します。PapersWithCode ID など、有用な情報が含まれる場合があります。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Iterable[DatasetInfo]
huggingface_hub.hf_api.DatasetInfoオブジェクトのイテラブルです。
いくつかのフィルターを指定して、Huggingface Hub にホストされているデータセットのリストを取得します。
filter引数を使った使用例:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
# List all datasets
>>> api.list_datasets()
# List only the text classification datasets
>>> api.list_datasets(filter="task_categories:text-classification")
# List only the datasets in russian for language modeling
>>> api.list_datasets(
... filter=("language:ru", "task_ids:language-modeling")
... )
# List FiftyOne datasets (identified by the tag "fiftyone" in dataset card)
>>> api.list_datasets(filter="fiftyone")list_inference_catalog
< source >( accelerator: Literal['cpu', 'gpu', 'neuron'] | str | None = Noneengine: Literal['llamacpp', 'sglang', 'tei', 'vllm'] | str | None = Nonelicense: str | None = Nonetask: str | None = Nonesearch: str | None = Nonelimit: int | None = Nonetoken: bool | str | None = None ) → list[InferenceCatalogModel]
パラメータ
- accelerator (
str、省略可) — このアクセラレーター（"cpu"、"gpu"または"neuron"）のレシピを持つモデルのみを返します。 - engine (
str, 省略可) — この推論エンジン用のレシピを持つモデルのみを返します（例:"vllm"、"llamacpp"、"tei"、"sglang"）。 - license (
str, 省略可) — このライセンス（例:"Apache 2.0"）のモデルのみを返します。 - task (
str, 省略可) — このタスク用のモデルのみを返します（例:"text-generation"）。 - search (
str, 任意) — この検索クエリに一致するモデルのみを返します。 - limit (
int, 省略可能) — 返すモデルの最大数。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。
戻り値
list[InferenceCatalogModel]
カタログで利用可能なモデルと、それぞれにテスト済みのレシピ。
Hugging Face Inference Catalog で利用可能なモデルのリストを表示します。
Inference Catalogの目的は、推論用に最適化され、デフォルト設定がテスト済みのモデルの厳選リストを提供することです。カタログで利用可能なモデルのリストは、https://huggingface.co/proxy/endpoints.huggingface.co/catalogを参照してください。
カタログからモデルまたはレシピをデプロイするには、create_inference_endpoint_from_catalog()を使用します。
例:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> catalog = api.list_inference_catalog(task="text-generation", accelerator="neuron")
>>> [(model.repo_id, [recipe.id for recipe in model.recipes]) for model in catalog]
[('meta-llama/Llama-3.1-8B-Instruct', ['sizzling-biryani-g4xsi1ac', 'artisanal-quinoa-yz9ynamx']), ...]
list_inference_catalogは実験的な機能です。将来、API が変更される可能性があります。ご意見やご要望がございましたら、フィードバックをお寄せください。
list_inference_endpoints
< source >( namespace: str | None = Nonetoken: bool | str | None = None ) → listInferenceEndpoint
パラメータ
- namespace (
str, 省略可) — エンドポイントのリストを取得する namespace です。デフォルトでは現在のユーザーが使用されます。すべての namespace（つまり、個人 namespace とユーザーが所属するすべての組織）からすべてのエンドポイントをリストするには、"*"を設定してください。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
指定された名前空間のすべての推論エンドポイントのリスト。
指定された名前空間のすべての推論エンドポイントをリストします。
list_inference_endpoints_hardware
< source >( namespace: str | None = Nonetoken: bool | str | None = None ) → list[InferenceEndpointHardware]
パラメータ
- namespace (
str, 省略可) — 利用可能なハードウェアとアクセラレーターのクォータをリスト表示する名前空間。デフォルトでは現在のユーザーが使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。
戻り値
list[InferenceEndpointHardware]
すべてのベンダーとリージョンで利用可能なハードウェア（現在利用できないものや非推奨とされているものを含む）。
Inference Endpoint のデプロイに使用できるハードウェアをリスト表示します。
各エントリには、create_inference_endpoint()で期待される正確なvendor、region、accelerator、instance_type、instance_sizeの値に加えて、価格とネームスペースのアクセラレータ割当が含まれています。
list_jobs
< source >( status: list[JobStage | str] | JobStage | str | None = Nonelabels: dict[str, str] | None = Nonetimeout: int | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None ) → Iterable[JobInfo]
パラメータ
- status (
JobStage、strまたはlist、省略可) — 指定したステータスを持つJobのみを返します。例:"RUNNING"または[JobStage.RUNNING, JobStage.SCHEDULING]。 可能な値については、JobStageを参照してください。 - labels (
dict[str, str]、任意) — 指定されたすべてのkey=valueラベルを持つJobのみを返します。例:{"env": "prod", "team": "ml"}。 - timeout (
float, 任意) — Hub へのリクエストにタイムアウトを設定するかどうか。 - namespace (
str, 省略可能) — ジョブのリストを取得する namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。
戻り値
Iterable[JobInfo]
JobInfoオブジェクトのイテラブル。
Hugging Faceのインフラストラクチャ上で計算ジョブをリスト表示します。
list_jobs_hardware
< source >( token: bool | str | None = None ) → list[JobHardwareInfo]
戻り値
list[JobHardwareInfo]
利用可能なハードウェア構成のリスト。
Hugging Face のインフラストラクチャ上で、Jobs に利用可能なハードウェアオプションをリスト表示します。
例:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> hardware_list = api.list_jobs_hardware()
>>> hardware_list[0]
JobHardwareInfo(name='cpu-basic', pretty_name='CPU Basic', cpu='2 vCPU', ram='16 GB', ephemeral_storage='20 GB', accelerator=None, unit_cost_micro_usd=167, unit_cost_usd=0.000167, unit_label='minute')
>>> hardware_list[0].name
'cpu-basic'
# Filter GPU options
>>> gpu_hardware = [hw for hw in hardware_list if hw.accelerator is not None]
>>> gpu_hardware[0].accelerator.model
'T4'list_lfs_files
< source >( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = None ) → Iterable[LFSFileInfo]
パラメータ
- repo_id (
str) — LFS ファイルのリストを取得するリポジトリ。 - repo_type (
str, 任意) — リポジトリの種類。dataset または space から一覧を取得する場合は"dataset"または"space"、model から一覧を取得する場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Iterable[LFSFileInfo]
LFSFileInfoオブジェクトのイテレータ。
Hub上のリポジトリ内のすべてのLFSファイルをリスト表示します。
これは主に、リポジトリが使用しているストレージ量をカウントし、最終的にpermanently_delete_lfs_files()を使用して大きなファイルをクリーンアップするために有用です。この操作は恒久的であり、削除されたファイルを参照するすべてのコミットに影響を及ぼし、元に戻すことはできません。
例:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> lfs_files = api.list_lfs_files("username/my-cool-repo")
# Filter files to delete based on a combination of `filename`, `pushed_at`, `ref` or `size`.
# e.g. select only LFS files in the "checkpoints" folder
>>> lfs_files_to_delete = (lfs_file for lfs_file in lfs_files if lfs_file.filename.startswith("checkpoints/"))
# Permanently delete LFS files
>>> api.permanently_delete_lfs_files("username/my-cool-repo", lfs_files_to_delete)list_liked_repos
< source >( user: str | None = Nonetoken: bool | str | None = None ) → UserLikes
パラメータ
- user (
str, 任意) — いいねを取得したいユーザーの名前。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
ユーザー名と、リポジトリIDの3つのリスト（モデル用、データセット用、Spaces用）を含むオブジェクト。
例外
ValueError
ValueError—userが渡されず、トークンが見つからない場合（引数からでも、マシンからでも）。
huggingface.coでユーザーが「いいね」したすべての公開リポジトリをリスト表示します。
このリストは公開されているため、トークンは省略可能です。userが指定されない場合、デフォルトでログイン中のユーザーが使用されます。
また、unlike()も参照してください。
list_models
< source >( filter: str | Iterable[str] | None = Noneauthor: str | None = Noneapps: str | list[str] | None = Nonegated: bool | None = Noneinference: Literal['warm'] | None = Noneinference_provider: Literal['all'] | PROVIDER_T | list[PROVIDER_T] | None = Nonetrained_dataset: str | list[str] | None = Nonesearch: str | None = Nonepipeline_tag: str | None = Nonenum_parameters: str | None = Noneemissions_thresholds: tuple[float, float] | None = Nonesort: ModelSort_T | None = Nonelimit: int | None = Noneexpand: list[ExpandModelProperty_T] | None = Nonefull: bool | None = NonecardData: bool = Falsefetch_config: bool = Falsetoken: bool | str | None = None ) → Iterable[ModelInfo]
パラメータ
- filter (
strまたはIterable[str]、省略可) — Hub 上のモデルをフィルタリングするための文字列または文字列のリスト。 モデルは、ライブラリ、言語、タスク、タグなどによってフィルタリングできます。 - author (
str, 省略可) — 返されるモデルの作成者（ユーザーまたは組織）を識別する文字列。 - apps (
strまたはList、省略可) — Hub 上のモデルをフィルタリングするための、指定されたアプリをサポートする文字列または文字列のリストです。例として"ollama"や["ollama", "vllm"]があります。 - gated (
bool, 省略可) — Hub上のモデルがゲート付きかどうかでフィルタリングするためのブール値です。デフォルトでは、すべてのモデルが返されます。gated=Trueが渡された場合、ゲート付きのモデルのみが返されます。gated=Falseが渡された場合、ゲートなしのモデルのみが返されます。 - inference (
Literal["warm"], 省略可能) — “warm”の場合、Hub上で現在少なくとも1つのプロバイダーによって提供されているモデルに絞り込みます。 - inference_provider (
Literal["all"]またはstr、省略可) — 特定のプロバイダーによって提供されている Hub 上のモデルをフィルタリングするための文字列です。"all"を渡すと、少なくとも 1 つのプロバイダーによって提供されているすべてのモデルを取得できます。 - trained_dataset (
strまたはList、省略可) — Hub 上のモデルの学習済みデータセットの文字列タグ、または文字列タグのリスト。 - search (
str, 任意) — 返されるモデル ID に含まれる文字列。 - pipeline_tag (
str, オプション) —summarizationのような、Hub 上でモデルをフィルタリングするための文字列のパイプラインタグ。 - num_parameters (
str, 省略可) — パラメータ数でモデルをフィルタリングします。Hub UI および API と同じ範囲構文を受け付けます。例えば"min:6B,max:128B"、"min:6B"または"max:128B"などです。 - emissions_thresholds (
Tuple, オプション) — グラム単位で、結果のモデルをフィルタリングするための最小および最大のカーボンフットプリントを表す、2つのintまたはfloatのタプルです。 - sort (
ModelSort_T, 任意) — 結果のモデルをソートするためのキー。指定可能な値は “created_at”、“downloads”、“last_modified”、“likes”、“trending_score” です。 - limit (
int, 任意) — 取得するモデル数の上限です。このオプションをNoneにすると、すべてのモデルが取得されます。 - expand (
list[ExpandModelProperty_T], 任意) — レスポンスで返すプロパティのリストです。指定した場合、リストに含まれるプロパティのみが返されます。full、cardData、またはfetch_configが渡されている場合は、このパラメータを使用できません。 指定可能な値は"author"、"cardData"、"config"、"createdAt"、"disabled"、"downloads"、"downloadsAllTime"、"evalResults"、"gated"、"gguf"、"inference"、"inferenceProviderMapping"、"lastModified"、"library_name"、"likes"、"mask_token"、"model-index"、"pipeline_tag"、"private"、"safetensors"、"sha"、"siblings"、"spaces"、"tags"、"transformersInfo"、"trendingScore"、"widgetData"、および"resourceGroup"です。 - full (
bool, 省略可) —last_modified、sha、ファイル、tagsを含むすべてのモデルデータを取得するかどうか。フィルタを使用する場合、デフォルトではTrueに設定されます。 - cardData (
bool, オプション) — モデルのメタデータも取得するかどうか。炭素排出量、メトリクス、学習に使用されたデータセットなど、有用な情報が含まれる場合があります。 - fetch_config (
bool, 省略可能) — モデルの構成も取得するかどうか。fullには、サイズが大きいため含まれていません。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Iterable[ModelInfo]
huggingface_hub.hf_api.ModelInfoオブジェクトのイテラブルです。
いくつかのフィルターを指定して、Huggingface Hub にホストされているモデルのリストを取得します。
例:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
# List all models
>>> api.list_models()
# List text classification models
>>> api.list_models(filter="text-classification")
# List models from the KerasHub library
>>> api.list_models(filter="keras-hub")
# List models served by Cohere
>>> api.list_models(inference_provider="cohere")
# List models with "bert" in their name
>>> api.list_models(search="bert")
# List models with "bert" in their name and pushed by google
>>> api.list_models(search="bert", author="google")
# List models with 6B to 128B parameters
>>> api.list_models(num_parameters="min:6B,max:128B", sort="likes")list_organization_followers
< source >( organization: strtoken: bool | str | None = None ) → Iterable[User]
パラメータ
- organization (
str) — フォロワーを取得する組織の名前。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Iterable[User]
組織のフォロワーのUserオブジェクトのリスト。
例外
HfHubHTTPError
HfHubHTTPError— 組織が Hub に存在しない場合、HTTP 404 が返されます。
Hub上の組織のフォロワーをリスト表示します。
list_organization_members
< source >( organization: strtoken: bool | str | None = None ) → Iterable[User]
パラメータ
- organization (
str) — メンバーを取得する組織の名前。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Iterable[User]
組織のメンバーを含むUserオブジェクトのリスト。
例外
HfHubHTTPError
HfHubHTTPError— 組織が Hub に存在しない場合、HTTP 404 が返されます。
Hub上の組織のメンバーの一覧。
list_papers
< source >( query: str | None = Nonelimit: int | None = Nonetoken: bool | str | None = None ) → Iterable[PaperInfo]
パラメータ
- query (
str, 任意) — 論文を検索するためのクエリ文字列です。 指定された場合、クエリに一致する論文が返されます。 - limit (
int, 任意) — 返す論文の最大数。 - token (Union[bool, str, None], 任意) —
有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、
Falseを渡します。
戻り値
Iterable[PaperInfo]
huggingface_hub.hf_api.PaperInfoオブジェクトのイテラブルです。
検索クエリを指定して、Hugging Face Hub上の日次ペーパーのリストを取得します。
list_pending_access_requests
< source >( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = None ) → Iterable[AccessRequest]
パラメータ
- repo_id (
str) — アクセスリクエストを取得するリポジトリのIDです。 - repo_type (
str, 省略可) — アクセス要求を取得するリポジトリの種類。model、dataset、spaceのいずれかである必要があります。 デフォルトはmodelです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Iterable[AccessRequest]
AccessRequestオブジェクトのイテラブルです。各アイテムには、username、request_id、email、status、timestampという属性が含まれます。ゲート付きリポジトリにカスタムフォームがある場合、fields属性にはユーザーの回答が設定されます。
例外
HfHubHTTPError
HfHubHTTPError— リポジトリがゲート付きでない場合、HTTP 400 が返されます。HfHubHTTPError— リポジトリへのアクセス権限が読み取り専用の場合、HTTP 403 が返されます。リポジトリが属する組織でwriteまたはadminのロールを持っていない場合、またはreadトークンを渡した場合に、この状況が発生し得ます。
指定されたゲート付きリポジトリの保留中のアクセスリクエストを取得します。
保留中のリクエストとは、ユーザーがリポジトリへのアクセスを要求したものの、まだ処理されていない状態を指します。 承認モードが自動の場合、このリストは空であるはずです。保留中のリクエストは、accept_access_request() および reject_access_request() を使用して承認または拒否できます。
ゲート付きリポジトリの詳細については、https://huggingface.co/docs/hub/models-gatedを参照してください。
例:
>>> from huggingface_hub import list_pending_access_requests, accept_access_request
# List pending requests
>>> requests = list(list_pending_access_requests("meta-llama/Llama-2-7b"))
>>> len(requests)
411
>>> requests[0]
[
AccessRequest(
username='clem',
request_id='655f3a1c9e6b2d4f8a7c1e05',
fullname='Clem 🤗',
email='***',
timestamp=datetime.datetime(2023, 11, 23, 18, 4, 53, 828000, tzinfo=datetime.timezone.utc),
status='pending',
fields=None,
),
...
]
# Accept Clem's request
>>> accept_access_request("meta-llama/Llama-2-7b", "clem")list_rejected_access_requests
< source >( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = None ) → Iterable[AccessRequest]
パラメータ
- repo_id (
str) — アクセスリクエストを取得するリポジトリのIDです。 - repo_type (
str, 省略可) — アクセス要求を取得するリポジトリの種類。model、dataset、spaceのいずれかである必要があります。 デフォルトはmodelです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Iterable[AccessRequest]
AccessRequestオブジェクトのイテラブルです。各アイテムには、username、request_id、email、status、timestampという属性が含まれます。ゲート付きリポジトリにカスタムフォームがある場合、fields属性にはユーザーの回答が設定されます。
例外
HfHubHTTPError
HfHubHTTPError— リポジトリがゲート付きでない場合、HTTP 400 が返されます。HfHubHTTPError— リポジトリへのアクセス権限が読み取り専用の場合、HTTP 403 が返されます。リポジトリが属する組織でwriteまたはadminのロールを持っていない場合、またはreadトークンを渡した場合に、この状況が発生し得ます。
指定されたゲート付きリポジトリの拒否されたアクセスリクエストを取得します。
リクエストが拒否された場合、ユーザーがリポジトリへのアクセスを要求し、そのリクエストがリポジトリのオーナー（あなたまたは組織の他のユーザー）によって明示的に拒否されたことを意味します。ユーザーはリポジトリのファイルをダウンロードできません。拒否されたリクエストは、accept_access_request() および cancel_access_request() を使用して、いつでも承認またはキャンセルできます。キャンセルされたリクエストは保留リストに戻り、承認されたリクエストは承認リストに移動します。
ゲート付きリポジトリの詳細については、https://huggingface.co/docs/hub/models-gatedを参照してください。
例:
>>> from huggingface_hub import list_rejected_access_requests
>>> requests = list(list_rejected_access_requests("meta-llama/Llama-2-7b"))
>>> len(requests)
411
>>> requests[0]
[
AccessRequest(
username='clem',
request_id='655f3a1c9e6b2d4f8a7c1e05',
fullname='Clem 🤗',
email='***',
timestamp=datetime.datetime(2023, 11, 23, 18, 4, 53, 828000, tzinfo=datetime.timezone.utc),
status='rejected',
fields=None,
),
...
]list_repo_commits
< source >( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = Nonerevision: str | None = Noneformatted: bool = False ) → list[GitCommitInfo]
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - repo_type (
str, 省略可) — データセットまたは Space のコミットをリストする場合は"dataset"または"space"、モデルからリストする場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - revision (
str, 省略可) — コミット元の git リビジョンです。デフォルトでは、"main"ブランチの先頭になります。 - formatted (
bool) — コミットのHTML形式のタイトルと説明を返すかどうか。デフォルトはFalseです。
戻り値
list[GitCommitInfo]
Hub上のリポジトリのコミットに関する情報を含むオブジェクトのリスト。
- RepositoryNotFoundError — リポジトリが見つからない場合（エラー 404）: repo_id/repo_type が誤っている、プライベートリポジトリだが認証されていない、またはリポジトリが存在しない。
- RevisionNotFoundError — リポジトリ上でリビジョンが見つからない場合（エラー 404）。
Hub上のリポジトリの指定されたリビジョンのコミット一覧を取得します。
コミットは日付順に並べ替えられます（最新のコミットが先頭）。
例:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
# Commits are sorted by date (last commit first)
>>> initial_commit = api.list_repo_commits("gpt2")[-1]
# Initial commit is always a system commit containing the `.gitattributes` file.
>>> initial_commit
GitCommitInfo(
commit_id='9b865efde13a30c13e0a33e536cf3e4a5a9d71d8',
authors=['system'],
created_at=datetime.datetime(2019, 2, 18, 10, 36, 15, tzinfo=datetime.timezone.utc),
title='initial commit',
message='',
formatted_title=None,
formatted_message=None
)
# Create an empty branch by deriving from initial commit
>>> api.create_branch("gpt2", branch="new_empty_branch", revision=initial_commit.commit_id)list_repo_files
< source >( repo_id: strrevision: str | None = Nonerepo_type: str | None = Nonetoken: str | bool | None = None ) → list[str]
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - revision (
str, 任意) — 情報を取得するリポジトリのリビジョン。 - repo_type (
str, 省略可) — データセットまたはスペースにアップロードする場合は"dataset"または"space"、モデルにアップロードする場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
list[str]
指定されたリポジトリ内のファイルのリスト
指定されたリポジトリ内のファイルのリストを取得します。
list_repo_likers
< source >( repo_id: strrepo_type: str | None = Nonetoken: bool | str | None = None ) → Iterable[User]
パラメータ
- repo_id (
str) — 取得するリポジトリです。例:"user/my-cool-model"。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - repo_type (
str, 省略可) — データセットまたはスペースにアップロードする場合は"dataset"または"space"、モデルにアップロードする場合はNoneまたは"model"を設定します。デフォルトはNoneです。
戻り値
Iterable[User]
huggingface_hub.hf_api.Userオブジェクトのイテラブルです。
Hugging Face Hub上の特定のリポジトリに「いいね」をつけたすべてのユーザーをリスト表示します。
また、list_liked_repos()も参照してください。
list_repo_refs
< source >( repo_id: strrepo_type: str | None = Noneinclude_pull_requests: bool = Falsetoken: str | bool | None = None ) → GitRefs
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - repo_type (
str, 省略可) — データセット、Space、Kernel の refs を一覧表示する場合は"dataset"、"space"、"kernel"、モデルから一覧表示する場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - include_pull_requests (
bool, 省略可能) — プルリクエストの refs をリストに含めるかどうか。デフォルトはFalseです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Hub上のリポジトリのブランチとタグに関するすべての情報を含むオブジェクト。
指定されたリポジトリのrefs（タグとブランチ）のリストを取得します。
例:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.list_repo_refs("gpt2")
GitRefs(branches=[GitRefInfo(name='main', ref='refs/heads/main', target_commit='e7da7f221d5bf496a48136c0cd264e630fe9fcc8')], converts=[], tags=[])
>>> api.list_repo_refs("bigcode/the-stack", repo_type='dataset')
GitRefs(
branches=[
GitRefInfo(name='main', ref='refs/heads/main', target_commit='18edc1591d9ce72aa82f56c4431b3c969b210ae3'),
GitRefInfo(name='v1.1.a1', ref='refs/heads/v1.1.a1', target_commit='f9826b862d1567f3822d3d25649b0d6d22ace714')
],
converts=[],
tags=[
GitRefInfo(name='v1.0', ref='refs/tags/v1.0', target_commit='c37a8cd1e382064d8aced5e05543c5f7753834da')
]
)list_repo_tree
< source >( repo_id: strpath_in_repo: str | None = Nonerecursive: bool = Falseexpand: bool = Falserevision: str | None = Nonerepo_type: str | None = Nonetoken: str | bool | None = None ) → Iterable[Union[RepoFile, RepoFolder]]
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - path_in_repo (
str, 省略可) — リポジトリ内のツリー（フォルダ）の相対パスです。例:"checkpoints/1fec34a/results"。デフォルトでは、リポジトリのルートツリー（フォルダ）になります。 - recursive (
bool、省略可能、デフォルトはFalse) — ツリーのファイルとフォルダを再帰的に一覧表示するかどうか。 - expand (
bool、省略可能、デフォルトはFalse) — ツリーのファイルやフォルダーに関する追加情報（最終コミットやファイルのセキュリティスキャン結果など）を取得するかどうかを指定します。この操作はサーバーにとってコストが高いため、1ページあたりの返却結果は50件（1000件ではなく）に制限されます。 ページネーションはhuggingface_hubで実装されているため、結果を取得するまでの時間がかかる点を除けば、ユーザーには透過的です。 - revision (
str, 任意) — ツリーを取得するリポジトリのリビジョンです。デフォルトは"main"ブランチです。 - repo_type (
str, 省略可) — ツリーを取得するリポジトリの種類（"model"、"dataset"、"space"または"kernel"）。 デフォルトは"model"です。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Iterable[Union[RepoFile, RepoFolder]]
ツリーのファイルとフォルダに関する情報。RepoFileオブジェクトとRepoFolderオブジェクトのイテラブルです。ファイルとフォルダの順序は保証されません。
例外
RepositoryNotFoundError または RevisionNotFoundError または ~utils.RemoteEntryNotFoundError
- RepositoryNotFoundError — リポジトリが見つからない場合（エラー 404）: repo_id/repo_type が誤っている、プライベートリポジトリだが認証されていない、またはリポジトリが存在しない。
- RevisionNotFoundError — リポジトリ上でリビジョンが見つからない場合（エラー 404）。
~utils.RemoteEntryNotFoundError— リポジトリ上にツリー（フォルダ）が存在しない場合（エラー 404）。
リポジトリツリーのファイルとフォルダをリスト表示し、それらの情報取得
例:
リポジトリのツリーに関する情報を取得します。
>>> from huggingface_hub import list_repo_tree
>>> repo_tree = list_repo_tree("lysandre/arxiv-nlp")
>>> repo_tree
<generator object HfApi.list_repo_tree at 0x7fa4088e1ac0>
>>> list(repo_tree)
[
RepoFile(path='.gitattributes', size=391, blob_id='ae8c63daedbd4206d7d40126955d4e6ab1c80f8f', lfs=None, last_commit=None, security=None),
RepoFile(path='README.md', size=391, blob_id='43bd404b159de6fba7c2f4d3264347668d43af25', lfs=None, last_commit=None, security=None),
RepoFile(path='config.json', size=554, blob_id='2f9618c3a19b9a61add74f70bfb121335aeef666', lfs=None, last_commit=None, security=None),
RepoFile(
path='flax_model.msgpack', size=497764107, blob_id='8095a62ccb4d806da7666fcda07467e2d150218e',
lfs={'size': 497764107, 'sha256': 'd88b0d6a6ff9c3f8151f9d3228f57092aaea997f09af009eefd7373a77b5abb9', 'pointer_size': 134}, last_commit=None, security=None
),
RepoFile(path='merges.txt', size=456318, blob_id='226b0752cac7789c48f0cb3ec53eda48b7be36cc', lfs=None, last_commit=None, security=None),
RepoFile(
path='pytorch_model.bin', size=548123560, blob_id='64eaa9c526867e404b68f2c5d66fd78e27026523',
lfs={'size': 548123560, 'sha256': '9be78edb5b928eba33aa88f431551348f7466ba9f5ef3daf1d552398722a5436', 'pointer_size': 134}, last_commit=None, security=None
),
RepoFile(path='vocab.json', size=898669, blob_id='b00361fece0387ca34b4b8b8539ed830d644dbeb', lfs=None, last_commit=None, security=None)]
]リポジトリのツリーに関するさらなる情報（最終コミットとファイルのセキュリティスキャン結果）を取得します
>>> from huggingface_hub import list_repo_tree
>>> repo_tree = list_repo_tree("prompthero/openjourney-v4", expand=True)
>>> list(repo_tree)
[
RepoFolder(
path='feature_extractor',
tree_id='aa536c4ea18073388b5b0bc791057a7296a00398',
last_commit={
'oid': '47b62b20b20e06b9de610e840282b7e6c3d51190',
'title': 'Upload diffusers weights (#48)',
'date': datetime.datetime(2023, 3, 21, 9, 5, 27, tzinfo=datetime.timezone.utc)
}
),
RepoFolder(
path='safety_checker',
tree_id='65aef9d787e5557373fdf714d6c34d4fcdd70440',
last_commit={
'oid': '47b62b20b20e06b9de610e840282b7e6c3d51190',
'title': 'Upload diffusers weights (#48)',
'date': datetime.datetime(2023, 3, 21, 9, 5, 27, tzinfo=datetime.timezone.utc)
}
),
RepoFile(
path='model_index.json',
size=582,
blob_id='d3d7c1e8c3e78eeb1640b8e2041ee256e24c9ee1',
lfs=None,
last_commit={
'oid': 'b195ed2d503f3eb29637050a886d77bd81d35f0e',
'title': 'Fix deprecation warning by changing `CLIPFeatureExtractor` to `CLIPImageProcessor`. (#54)',
'date': datetime.datetime(2023, 5, 15, 21, 41, 59, tzinfo=datetime.timezone.utc)
},
security={
'safe': True,
'av_scan': {'virusFound': False, 'virusNames': None},
'pickle_import_scan': None
}
)
...
]list_scheduled_jobs
< source >( labels: dict[str, str] | None = Nonetimeout: int | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None ) → list[ScheduledJobInfo]
パラメータ
- labels (
dict[str, str]、任意) — 指定されたkey=valueラベルをすべて持つスケジュール済みJobのみを返します。例:{"env": "prod", "team": "ml"}。 - timeout (
float, 任意) — Hub へのリクエストにタイムアウトを設定するかどうか。 - namespace (
str, 省略可能) — ジョブのリストを取得する namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。
戻り値
list[ScheduledJobInfo]
ScheduledJobInfoオブジェクトのリスト。
Hugging Face のインフラストラクチャ上でスケジュールされた compute Jobs を一覧表示します。
list_space_templates
< source >( token: str | bool | None = None ) → list[SpaceTemplate]
パラメータ
- token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
list[SpaceTemplate]
利用可能なSpaceテンプレートのリスト。
Hubで利用可能な公式Spaceテンプレートのリストを表示します。
返されたテンプレートのrepo_id(またはその短縮名name)をspace_templateとしてHfApi.create_repo()に渡すことで、そのテンプレートから新しいSpaceを初期化できます。
list_spaces
< source >( filter: str | Iterable[str] | None = Noneauthor: str | None = Nonesearch: str | None = Nonedatasets: str | Iterable[str] | None = Nonemodels: str | Iterable[str] | None = Nonelinked: bool = Falsesort: SpaceSort_T | None = Nonelimit: int | None = Noneexpand: list[ExpandSpaceProperty_T] | None = Nonefull: bool | None = Nonetoken: bool | str | None = None ) → Iterable[SpaceInfo]
パラメータ
- filter (
strまたはIterable、省略可) — Hub 上の Spaces を識別するために使用できる文字列タグまたはタグのリスト。 - author (
str, 任意) — 返される Spaces の作成者を識別する文字列。 - search (
str, 任意) — 返される Spaces に含まれる文字列。 - datasets (
strまたはIterable、省略可) — データセットを利用する Spaces を返すかどうかを指定します。 特定のデータセットの名前を文字列として渡すことができます。 - models (
strまたはIterable、省略可) — モデルを利用している Spaces を返すかどうかを指定します。 特定のモデルの名前を文字列として渡すことができます。 - linked (
bool, 省略可) — モデルまたはデータセットを使用している Spaces を返すかどうかを指定します。 - sort (
SpaceSort_T, 任意) — 結果のスペースをソートするためのキーです。指定可能な値は “created_at”、“last_modified”、“likes”、“trending_score” です。 - limit (
int, 任意) — 取得する Spaces の数に上限を設けます。このオプションをNoneにすると、すべての Spaces が取得されます。 - expand (
list[ExpandSpaceProperty_T], 任意) — レスポンスで返すプロパティのリスト。指定した場合、リストに含まれるプロパティのみが返されます。fullが渡されている場合は、このパラメーターを使用できません。 指定可能な値は"author"、"cardData"、"datasets"、"disabled"、"lastModified"、"createdAt"、"likes"、"models"、"private"、"region"、"runtime"、"sdk"、"siblings"、"sha"、"subdomain"、"tags"、"trendingScore"、"usedStorage"、"visibility"、および"resourceGroup"です。 - full (
bool, 省略可) —last_modified、siblings、card_dataフィールドを含むすべての Spaces データを取得するかどうか。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Iterable[SpaceInfo]
huggingface_hub.hf_api.SpaceInfoオブジェクトのイテラブルです。
いくつかのフィルターを指定して、Huggingface Hub にホストされているスペースのリストを取得します。
list_spaces_hardware
< source >( token: bool | str | None = None ) → list[JobHardwareInfo]
戻り値
list[JobHardwareInfo]
利用可能なハードウェア構成のリスト。
Spacesで利用可能なハードウェアオプションをリスト表示します。
list_user_followers
< source >( username: strtoken: bool | str | None = None ) → Iterable[User]
パラメータ
- username (
str) — フォロワーを取得するユーザーのユーザー名。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Iterable[User]
ユーザーのフォロワーを含むUserオブジェクトのリスト。
例外
HfHubHTTPError
HfHubHTTPError— ユーザーが Hub に存在しない場合、HTTP 404 が返されます。
Hub上のユーザーのフォロワーのリストを取得します。
list_user_following
< source >( username: strtoken: bool | str | None = None ) → Iterable[User]
パラメータ
- username (
str) — フォローしているユーザーを取得する対象のユーザー名。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Iterable[User]
そのユーザーがフォローしているユーザーのUserオブジェクトのリスト。
例外
HfHubHTTPError
HfHubHTTPError— ユーザーが Hub に存在しない場合、HTTP 404 が返されます。
Hub上でユーザーがフォローしているユーザーのリストを取得します。
list_user_repos
< source >( namespace: str | None = Nonetoken: bool | str | None = None ) → Iterable[RepoStorageInfo]
ストレージ情報付きで、ユーザーまたは組織のすべてのリポジトリ（モデル、データセット、スペース、バケット）をリスト表示します。
認証済みユーザーには/api/settings/repositoriesエンドポイント、組織には/api/organizations/{namespace}/settings/repositoriesエンドポイントを使用します。
list_webhooks
< source >( token: bool | str | None = None ) → list[WebhookInfo]
パラメータ
- token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
list[WebhookInfo]
Webhook情報オブジェクトのリスト。
設定済みのすべてのWebhookをリスト表示します。
例:
>>> from huggingface_hub import list_webhooks
>>> webhooks = list_webhooks()
>>> len(webhooks)
2
>>> webhooks[0]
WebhookInfo(
id="654bbbc16f2ec14d77f109cc",
watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
url="https://webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
secret="my-secret",
domains=["repo", "discussion"],
disabled=False,
)merge_pull_request
< source >( repo_id: strdiscussion_num: inttoken: bool | str | None = Nonecomment: str | None = Nonerepo_type: str | None = None ) → DiscussionStatusChange
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - discussion_num (
int) — Discussion または Pull Request の番号です。正の整数である必要があります。 - comment (
str, 省略可) — ステータス変更と同時に投稿する任意のコメント。 - repo_type (
str, 省略可) — データセットまたはスペースにアップロードする場合は"dataset"または"space"、モデルにアップロードする場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
ステータス変更イベント
Pull Request をマージします。
以下のエラーを発生させます：
- HuggingFace API がエラーを返した場合に
HTTPErrorValueError一部のパラメータ値が無効な場合- RepositoryNotFoundError ダウンロード元のリポジトリが見つからない場合に発生します。存在しないか、
privateに設定されておりアクセス権限がないことが原因です。
model_info
< source >( repo_id: strrevision: str | None = Nonetimeout: float | None = NonesecurityStatus: bool | None = Nonefiles_metadata: bool = Falseexpand: list[ExpandModelProperty_T] | None = Nonetoken: bool | str | None = None ) → huggingface_hub.hf_api.ModelInfo
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - revision (
str, 任意) — 情報を取得するモデルリポジトリのリビジョン。 - timeout (
float, 任意) — Hub へのリクエストにタイムアウトを設定するかどうか。 - securityStatus (
bool、任意) — モデルのリポジトリからもセキュリティステータスを取得するかどうか。セキュリティステータスはsecurity_repo_statusフィールドに返されます。 - files_metadata (
bool, 省略可) — リポジトリ内のファイルのメタデータ（サイズ、LFS メタデータなど）を取得するかどうか。デフォルトはFalseです。 - expand (
list[ExpandModelProperty_T], 任意) — レスポンスで返すプロパティのリストです。指定した場合、リストに含まれるプロパティのみが返されます。securityStatusまたはfiles_metadataが渡されている場合、このパラメータは使用できません。 指定可能な値は"author"、"baseModels"、"cardData"、"childrenModelCount"、"config"、"createdAt"、"disabled"、"downloads"、"downloadsAllTime"、"evalResults"、"gated"、"gguf"、"inference"、"inferenceProviderMapping"、"lastModified"、"library_name"、"likes"、"mask_token"、"model-index"、"pipeline_tag"、"private"、"safetensors"、"sha"、"siblings"、"spaces"、"tags"、"transformersInfo"、"trendingScore"、"widgetData"、"usedStorage"、および"resourceGroup"です。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
モデルリポジトリの情報。
huggingface.co上の特定の1つのモデルに関する情報を取得します
Modelは、許可されたトークンを渡すか、ログインしている場合にプライベートに設定できます。
以下のエラーを発生させます：
- RepositoryNotFoundError ダウンロード元のリポジトリが見つからない場合に発生します。存在しないか、
privateに設定されておりアクセス権限がないことが原因です。- RevisionNotFoundError ダウンロード元のリビジョンが見つからない場合に発生します。
move_bucket
< source >( from_id: strto_id: strtoken: bool | str | None = None )
パラメータ
- from_id (
str) —/で区切られた名前空間(ユーザーまたは組織)とバケット名です。元のバケット識別子(例:"username/my-bucket")。 - to_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とバケット名。最終的なバケット識別子（例:"username/new-bucket-name"または"organization/my-bucket"）。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
例外
BucketNotFoundError
BucketNotFoundError— ソースのバケットが見つからない場合。存在しないか、privateに設定されておりアクセス権限がない可能性があります。
バケットを“namespace1/repo_name1”から“namespace2/repo_name2”に移動します
いくつかの制約がある点にご注意ください。リポジトリの移動に関する詳細は、https://hf.co/docs/hub/repositories-settings#renaming-or-transferring-a-repoを参照してください。
move_repo
< source >( from_id: strto_id: strrepo_type: str | None = Nonetoken: str | bool | None = None )
パラメータ
- from_id (
str) —/で区切られた名前空間(ユーザーまたは組織)とリポジトリ名。元のリポジトリ識別子。 - to_id (
str) —/で区切られた名前空間(ユーザーまたは組織)とリポジトリ名。最終的なリポジトリ識別子。 - repo_type (
str, 省略可) — データセットまたはスペースにアップロードする場合は"dataset"または"space"、モデルにアップロードする場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
リポジトリをnamespace1/repo_name1からnamespace2/repo_name2へ移動する
いくつかの制約がある点にご注意ください。リポジトリの移動に関する詳細は、https://hf.co/docs/hub/repositories-settings#renaming-or-transferring-a-repoを参照してください。
以下のエラーを発生させます：
- RepositoryNotFoundError ダウンロード元のリポジトリが見つからない場合に発生します。存在しないか、
privateに設定されておりアクセス権限がないことが原因です。
paper_info
< source >( id: str ) → PaperInfo
Hub上の論文の情報を取得します。
parse_safetensors_file_metadata
< source >( repo_id: strfilename: strrepo_type: str | None = Nonerevision: str | None = Nonetoken: bool | str | None = Nonetimeout: float | None = 10 ) → SafetensorsFileMetadata
パラメータ
- repo_id (
str) —/で区切られたユーザー名または組織名とリポジトリ名。 - filename (
str) — リポジトリ内のファイル名です。 - repo_type (
str, 省略可) — ファイルがデータセットまたはスペースにある場合は"dataset"または"space"、モデルにある場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - revision (
str, 省略可) — ファイルを取得する git リビジョンです。ブランチ名、タグ、またはコミットハッシュを指定できます。デフォルトでは、"main"ブランチの先頭が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - timeout (
float、任意、デフォルト値は 10)— サーバーからデータを受信するのを、何秒待ってから諦めるかを指定します。Noneに設定するとタイムアウトが無効になります（接続が停止した際に呼び出しが無限にハングする可能性があるため、推奨されません）。
戻り値
SafetensorsFileMetadata
safetensorsファイルに関する情報。
例外
NotASafetensorsRepoError または SafetensorsParsingError
NotASafetensorsRepoError— リポジトリがsafetensorsのリポジトリでない場合、つまりmodel.safetensorsファイルまたはmodel.safetensors.index.jsonファイルのいずれも存在しない場合に発生します。SafetensorsParsingError— safetensorsファイルのヘッダーを正しく解析できなかった場合に発生します。
Hub上のsafetensorsファイルからメタデータを解析します。
リポジトリ内のすべてのsafetensorsファイルからメタデータを一度に解析するには、get_safetensors_metadata()を使用します。
safetensors形式の詳細については、https://huggingface.co/docs/safetensors/index#formatを参照してください。
pause_inference_endpoint
< source >( name: strnamespace: str | None = Nonetoken: bool | str | None = None ) → InferenceEndpoint
パラメータ
- name (
str) — 一時停止する Inference Endpoint の名前。 - namespace (
str, 省略可) — Inference Endpoint が配置されている namespace です。デフォルトでは現在のユーザーになります。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
一時停止されたInference Endpointに関する情報。
Inference Endpointを一時停止します。
一時停止されたInference Endpointには料金は発生しません。resume_inference_endpoint()を使用して、いつでも再開できます。 これは、scale_to_zero_inference_endpoint()を使用してInference Endpointをゼロにスケーリングすることとは異なり、後者の場合はリクエストが送信されると自動的に再起動されます。
便宜のため、pause_inference_endpoint() を使用して Inference Endpoint を一時停止することもできます。
pause_space
< source >( repo_id: strtoken: bool | str | None = None ) → SpaceRuntime
パラメータ
- repo_id (
str) — 一時停止する Space の ID。例:"Salesforce/BLIP2"。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
stage=PAUSED や要求されたハードウェアなど、Spaceに関するランタイム情報。
例外
RepositoryNotFoundError または HfHubHTTPError または BadRequestError
- RepositoryNotFoundError — Space が見つからない場合（エラー 404）に発生します。おそらく repo_id が誤っているか、Space がプライベートであるにもかかわらず認証されていないことが原因です。
- HfHubHTTPError — 403 Forbidden: Spaceを一時停止できるのは所有者のみです。所有していないSpaceを管理したい場合は、Discussionを開いて所有者に依頼するか、Spaceを複製してください。
- BadRequestError — Space が静的 Space の場合です。静的 Space は常に稼働しており、請求は発生しません。静的 Space を非表示にする場合は、プライベートに設定できます。
Spaceを一時停止します。
一時停止された Space は、オーナーによって手動で再起動されるまで実行を停止します。これは、48 時間の非アクティブ状態後に無料の Space が移行するスリープ状態とは異なります。選択したハードウェアにかかわらず、一時停止中の時間はアカウントに請求されません。Space を再起動するには、restart_space() を使用し、Space の設定ページにアクセスしてください。
詳細については、ドキュメントをご覧ください。
permanently_delete_lfs_files
< source >( repo_id: strlfs_files: Iterable[LFSFileInfo]rewrite_history: bool = Truerepo_type: str | None = Nonetoken: bool | str | None = None )
パラメータ
- repo_id (
str) — LFS ファイルのリストを取得するリポジトリ。 - lfs_files (
Iterable[LFSFileInfo]) — リポジトリから恒久的に削除するLFSFileInfoアイテムのイテラブルです。リポジトリ内のすべてのLFSファイルをリスト表示するには、list_lfs_files()を使用してください。 - rewrite_history (
bool、省略可、デフォルトはTrue) — 削除された LFS ファイルを参照するファイルポインタを除去するためにリポジトリの履歴を書き換えるかどうか（推奨）。 - repo_type (
str, 任意) — リポジトリの種類。dataset または space から一覧を取得する場合は"dataset"または"space"、model から一覧を取得する場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
Hub上のリポジトリからLFSファイルを恒久的に削除します。
これは恒久的な操作であり、削除されたファイルを参照するすべてのコミットに影響を与え、リポジトリを破損させる可能性があります。この操作は元に戻せません。その影響を十分に理解している場合のみ使用してください。
例:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> lfs_files = api.list_lfs_files("username/my-cool-repo")
# Filter files to delete based on a combination of `filename`, `pushed_at`, `ref` or `size`.
# e.g. select only LFS files in the "checkpoints" folder
>>> lfs_files_to_delete = (lfs_file for lfs_file in lfs_files if lfs_file.filename.startswith("checkpoints/"))
# Permanently delete LFS files
>>> api.permanently_delete_lfs_files("username/my-cool-repo", lfs_files_to_delete)preupload_lfs_files
< source >( repo_id: stradditions: Iterable[CommitOperationAdd]token: str | bool | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecreate_pr: bool | None = Nonenum_threads: int = 5free_memory: bool = Truegitignore_content: str | None = None )
パラメータ
- repo_id (
str) — ファイルをコミットするリポジトリです。例:"username/custom_transformers" - additions (
Iterableof CommitOperationAdd) — アップロードするファイルのリストです。警告: このリスト内のオブジェクトは、アップロードに関する情報を含むように変更されます。同じオブジェクトを複数のコミットに再利用しないでください。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - repo_type (
str, 任意) — アップロード先のリポジトリの種類（例:"model"（デフォルト）、"dataset"、"space"、または"kernel"）。 - revision (
str, 省略可) — コミット元の git リビジョンです。デフォルトでは、"main"ブランチの先頭になります。 - create_pr (
boolean, 省略可) — そのコミットで Pull Request を作成するかどうか。デフォルトはFalseです。 - num_threads (
int, 任意) — ファイルのアップロードに使用する同時実行スレッド数。デフォルト値は 5 です。2 に設定すると、同時にアップロードされるファイルは最大 2 個になります。 - free_memory (
bool、省略可能、デフォルトはTrue) —Trueの場合、アップロード後、メモリを節約するために、各CommitOperationAddのpath_or_fileobj属性が空のbytesオブジェクトに置き換えられます。後続の create_commit() 呼び出しの外で操作オブジェクトを再利用する必要がある場合は、Falseに設定してください。 - gitignore_content (
str, 省略可) — 無視すべきファイルを特定するための.gitignoreファイルの内容です。優先順位は、まずgitignore_contentが渡されているかを確認し、次にコミット対象のファイル一覧に.gitignoreファイルが存在するかを確認し、最後に Hub に既にホストされている.gitignoreファイル (存在する場合) をデフォルトとして使用することです。
将来のコミットに備えて、LFSファイルをS3に事前アップロードします。
このメソッドは、アップロードするファイルをオンザフライで生成しており、アップロード前にすべてをメモリに保存したくない場合に便利です。
これは上級者向けのメソッドです。通常のコミットを行うために直接呼び出す必要はありません。 代わりに、create_commit()を直接使用してください。
コミット操作は処理の過程で変更されます。特に、添付された
path_or_fileobjは、メモリを節約するためにアップロード後に削除されます（空のbytesオブジェクトに置き換えられます）。create_commit()に渡す場合を除き、同じオブジェクトを再利用しないでください。コミット操作オブジェクトから添付されたコンテンツを削除したくない場合は、free_memory=Falseを渡してください。
例:
>>> from huggingface_hub import CommitOperationAdd, preupload_lfs_files, create_commit, create_repo
>>> repo_id = create_repo("test_preupload").repo_id
# Generate and preupload LFS files one by one
>>> operations = [] # List of all `CommitOperationAdd` objects that will be generated
>>> for i in range(5):
... content = ... # generate binary content
... addition = CommitOperationAdd(path_in_repo=f"shard_{i}_of_5.bin", path_or_fileobj=content)
... preupload_lfs_files(repo_id, additions=[addition]) # upload + free memory
... operations.append(addition)
# Create commit
>>> create_commit(repo_id, operations=operations, commit_message="Commit all shards")read_paper
< source >( id: str ) → str
Hub上の論文ページのMarkdownコンテンツを取得します。
reject_access_request
< source >( repo_id: struser: str | None = Nonerequest_id: str | None = Nonerepo_type: str | None = Nonerejection_reason: str | Nonetoken: bool | str | None = None )
パラメータ
- repo_id (
str) — アクセス要求を拒否するリポジトリのID。 - user (
str, 省略可) — アクセス要求を拒否する対象のユーザー名。userとrequest_idのうち、ちょうど 1 つを指定する必要があります。 - request_id (
str, 省略可) — 拒否するアクセスリクエストの ID（AccessRequestを参照）。リポジトリがリクエスト送信者のユーザー名を共有しないように設定されている場合に必須です。userとrequest_idのうち、ちょうど 1 つを指定する必要があります。 - repo_type (
str, 省略可) — アクセス要求を拒否するリポジトリの種類です。model、dataset、またはspaceのいずれかである必要があります。 デフォルトはmodelです。 - rejection_reason (
str, 任意) — ユーザーに表示される任意の拒否理由（最大200文字）。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
例外
HfHubHTTPError
HfHubHTTPError— リポジトリがゲート付きでない場合、HTTP 400 が返されます。HfHubHTTPError— リポジトリへのアクセス権限が読み取り専用の場合、HTTP 403 が返されます。リポジトリが属する組織でwriteまたはadminのロールを持っていない場合、またはreadトークンを渡した場合に、この状況が発生し得ます。HfHubHTTPError— ユーザーが Hub に存在しない場合、HTTP 404 が返されます。HfHubHTTPError— ユーザーのアクセスリクエストが見つからない場合、HTTP 404 が返されます。HfHubHTTPError— ユーザーのアクセスリクエストが既に拒否リストに含まれている場合、HTTP 404 が返されます。
指定されたゲート付きリポジトリに対するユーザーのアクセス要求を拒否します。
拒否されたリクエストは、拒否リストに移動します。ユーザーはリポジトリのファイルをダウンロードできません。拒否されたリクエストは、accept_access_request()およびcancel_access_request()を使用して、いつでも承認またはキャンセルできます。キャンセルされたリクエストは保留リストに戻り、承認されたリクエストは承認リストに移動します。
ゲート付きリポジトリの詳細については、https://huggingface.co/docs/hub/models-gatedを参照してください。
rename_discussion
< source >( repo_id: strdiscussion_num: intnew_title: strtoken: bool | str | None = Nonerepo_type: str | None = None ) → DiscussionTitleChange
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - discussion_num (
int) — Discussion または Pull Request の番号です。正の整数である必要があります。 - new_title (
str) — ディスカッションの新しいタイトル - repo_type (
str, 省略可) — データセットまたはスペースにアップロードする場合は"dataset"または"space"、モデルにアップロードする場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
タイトル変更イベント
Discussionの名前を変更します。
例:
>>> new_title = "New title, fixing a typo"
>>> HfApi().rename_discussion(
... repo_id="username/repo_name",
... discussion_num=34,
... new_title=new_title
... )
# DiscussionTitleChange(id='deadbeef0000000', type='title-change', ...)
以下のエラーを発生させます：
- HuggingFace API がエラーを返した場合に
HTTPErrorValueError一部のパラメータ値が無効な場合- RepositoryNotFoundError ダウンロード元のリポジトリが見つからない場合に発生します。存在しないか、
privateに設定されておりアクセス権限がないことが原因です。
repo_exists
< source >( repo_id: strrepo_type: str | None = Nonetoken: str | bool | None = None )
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - repo_type (
str, 省略可) — データセットまたはスペースからリポジトリ情報を取得する場合は"dataset"または"space"、モデルからリポジトリ情報を取得する場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
Hugging Face Hubにリポジトリが存在するかどうかを確認します。
repo_info
< source >( repo_id: strrevision: str | None = Nonerepo_type: str | None = Nonetimeout: float | None = Nonefiles_metadata: bool = Falseexpand: ExpandModelProperty_T | ExpandDatasetProperty_T | ExpandSpaceProperty_T | None = Nonetoken: bool | str | None = None ) → Union[SpaceInfo, DatasetInfo, ModelInfo]
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - revision (
str, 任意) — 情報を取得するリポジトリのリビジョン。 - repo_type (
str, 省略可) — データセットまたはスペースからリポジトリ情報を取得する場合は"dataset"または"space"、モデルからリポジトリ情報を取得する場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - timeout (
float, 任意) — Hub へのリクエストにタイムアウトを設定するかどうか。 - expand (
ExpandModelProperty_TまたはExpandDatasetProperty_TまたはExpandSpaceProperty_T、任意) — レスポンスで返すプロパティのリストです。指定した場合、リストに含まれるプロパティのみが返されます。files_metadataが渡されている場合は、このパラメータを使用できません。 利用可能なプロパティの完全なリストについては、model_info()、dataset_info() または space_info() を参照してください。 - files_metadata (
bool, 省略可) — リポジトリ内のファイルのメタデータ（サイズ、LFS メタデータなど）を取得するかどうか。デフォルトはFalseです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Union[SpaceInfo, DatasetInfo, ModelInfo]
リポジトリの情報が、huggingface_hub.hf_api.DatasetInfo、huggingface_hub.hf_api.ModelInfo、または huggingface_hub.hf_api.SpaceInfo オブジェクトとして。
指定されたタイプの指定されたリポジトリのinfoオブジェクトを取得します。
以下のエラーを発生させます：
- RepositoryNotFoundError ダウンロード元のリポジトリが見つからない場合に発生します。存在しないか、
privateに設定されておりアクセス権限がないことが原因です。- RevisionNotFoundError ダウンロード元のリビジョンが見つからない場合に発生します。
request_space_hardware
< source >( repo_id: strhardware: SpaceHardwaretoken: bool | str | None = Nonesleep_time: int | None = None ) → SpaceRuntime
パラメータ
- repo_id (
str) — 更新するリポジトリの ID。例:"bigcode/in-the-stack"。 - hardware (
strまたは SpaceHardware) — Space を実行するハードウェア。例:"t4-medium"。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - sleep_time (
int, 任意) — Space がスリープ状態に入るまで、待機状態を何秒間待つかを指定します。Space がスリープしないようにするには-1を設定してください（アップグレードされたハードウェアのデフォルト動作です）。無料ハードウェアでは、スリープ時間を設定できません（値は 48 時間の待機に固定されています）。詳細は https://huggingface.co/docs/hub/spaces-gpus#sleep-time を参照してください。
戻り値
Spaceのステージやハードウェアなど、Spaceに関するランタイム情報。
Space用の新しいハードウェアをリクエストします。
Space リポジトリを作成する際に、ハードウェアを直接リクエストすることも可能です。詳細は create_repo() を参照してください。
rerun_job
< source >( job_id: strnamespace: str | None = Nonetoken: bool | str | None = None ) → JobInfo
既存のJobのspec（リトライ設定やリソース設定を含む）を使用して、新しいJobを実行します。
resolve_revision
< source >( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | Path | None = Nonelocal_files_only: bool = Falsetoken: bool | str | None = None ) → ResolvedRevision
パラメータ
- repo_id (
str) —/で区切られたユーザー名または組織名とリポジトリ名。 - repo_type (
str, 省略可) — リポジトリがデータセット、スペース、またはカーネルのリポジトリの場合は、それぞれ"dataset"、"space"、"kernel"に設定します。モデルの場合はNoneまたは"model"です。デフォルトはNoneです。 - revision (
str, オプション) — 解決するリビジョンです。ブランチ名、タグ、PR リファレンス、コミットハッシュのいずれかを使用できます。デフォルトでは、デフォルトブランチが使用されます。ResolvedRevision が渡された場合は、そのまま返されます。ただし、別のリポジトリに対して解決された場合は、最初に要求されたリビジョンが再度解決されます。 - cache_dir (
str,Path, 省略可) — キャッシュされたファイルを保存するフォルダへのパスです。デフォルトではHF_HUB_CACHEの値が使用されます。 - local_files_only (
bool、任意、デフォルトはFalse) —Trueの場合、Hub に接続せずにローカルキャッシュのみからリビジョンを解決します。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
要求されたリビジョンと、それが解決されるコミットハッシュの両方を保持するstrのサブクラス。
- RevisionResolutionError — リビジョンを解決できない場合: Hub に接続できず、ローカルにキャッシュが存在しない場合。
- RevisionNotFoundError — Hub上にリビジョンが存在しない場合。
- RepositoryNotFoundError —
リポジトリが見つからない場合。存在しないか、
privateに設定されておりアクセス権限がない可能性があります。
リビジョン（ブランチ、タグ、PR リファレンス）をコミットハッシュに解決します。
これは、リポジトリの複数のコンポーネント（config、weights、tokenizer など）を個別にダウンロードして読み込むライブラリ向けに設計されています。リビジョンを一度解決し、返されたResolvedRevisionをそのまま渡すことで、リポジトリがその間に更新されていても、以降のすべての呼び出しが正確に同じコミットを対象とすることを保証します。また、コミットハッシュを用いたダウンロードは Hub に問い合わせることなくローカルキャッシュから提供できるため、HTTP 呼び出しの回数を削減できます。
revision -> commit hash のマッピングは、ベストエフォートでディスク上にキャッシュされます（キャッシュの refs/ フォルダ内）。その後、Hub に接続できない場合（オフラインモード、接続エラー、タイムアウト、Hub のダウンタイムなど）には、キャッシュされた値がフォールバックとして使用されます。
フルリポジトリのスナップショットのダウンロードのみが必要な場合、snapshot_download()を1回呼び出すだけで十分であり、すでに適切な処理が行われます。
resolve_revisionは、ファイルを個別にダウンロードする場合にのみ有用です。
例:
>>> from huggingface_hub import hf_hub_download, resolve_revision
>>> revision = resolve_revision("openai-community/gpt2")
>>> revision
ResolvedRevision(initial=None, resolved='607a30d783dfa663caf39e06633721c8d4cfcd7e')
# Pass it around: every download is pinned to the same commit
>>> config = hf_hub_download("openai-community/gpt2", "config.json", revision=revision)
>>> weights = hf_hub_download("openai-community/gpt2", "model.safetensors", revision=revision)restart_space
< source >( repo_id: strtoken: bool | str | None = Nonefactory_reboot: bool = False ) → SpaceRuntime
パラメータ
- repo_id (
str) — 再起動する Space の ID。例:"Salesforce/BLIP2"。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - factory_reboot (
bool, 省略可) —Trueの場合、Space はキャッシュなしで最初から再構築されます。
戻り値
Spaceのランタイムに関する情報。
例外
RepositoryNotFoundError または HfHubHTTPError または BadRequestError
- RepositoryNotFoundError — Space が見つからない場合（エラー 404）に発生します。おそらく repo_id が誤っているか、Space がプライベートであるにもかかわらず認証されていないことが原因です。
- HfHubHTTPError — 403 Forbidden: Spaceを再起動できるのは所有者のみです。所有していないSpaceを再起動したい場合は、Discussionを開いて所有者に依頼するか、そのSpaceを複製してください。
- BadRequestError — Space が静的 Space の場合です。静的 Space は常に稼働しており、請求は発生しません。静的 Space を非表示にする場合は、プライベートに設定できます。
Spaceを再起動してください。
Space を一時停止（pause_space() を参照）した場合、プログラムによって Space を再起動できる唯一の方法です。再起動するには、Space の所有者である必要があります。アップグレードされたハードウェアを使用している場合、Space が再起動されるとすぐにアカウントに請求が行われます。Space の現在の状態に関係なく、再起動をトリガーできます。
詳細については、ドキュメントをご覧ください。
resume_inference_endpoint
< source >( name: strnamespace: str | None = Nonerunning_ok: bool = Truetoken: bool | str | None = None ) → InferenceEndpoint
パラメータ
- name (
str) — 再開する Inference Endpoint の名前。 - namespace (
str, 省略可) — Inference Endpoint が配置されている namespace です。デフォルトでは現在のユーザーになります。 - running_ok (
bool, 省略可能) —Trueの場合、Inference Endpoint が既に実行中であってもエラーは発生しません。デフォルト値はTrueです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
再開されたInference Endpointに関する情報。
Inference Endpointを再開します。
便宜のため、InferenceEndpoint.resume() を使用して Inference Endpoint を再開することもできます。
resume_scheduled_job
< source >( scheduled_job_id: strnamespace: str | None = Nonetoken: bool | str | None = None )
パラメータ
- scheduled_job_id (
str) — スケジュールされた Job の ID。 - namespace (
str, 省略可能) — スケジュールされた Job が存在する namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。
Hugging Face のインフラストラクチャ上でスケジュールされた compute Job を再開（一時停止解除）します。
revision_exists
< source >( repo_id: strrevision: strrepo_type: str | None = Nonetoken: str | bool | None = None )
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - revision (
str) — 確認するリポジトリのリビジョン。 - repo_type (
str, 省略可) — データセットまたはスペースからリポジトリ情報を取得する場合は"dataset"または"space"、モデルからリポジトリ情報を取得する場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
Hugging Face Hub上のリポジトリに特定のリビジョンが存在するかどうかを確認します。
run_as_future
< source >( fn: Callable[..., R]*args**kwargs ) → Future
メソッドをバックグラウンドで実行し、Futureインスタンスを返します。
主な目的は、メインスレッドをブロックせずにメソッドを実行することです（例: トレーニング中にデータをプッシュする）。バックグラウンドジョブはキューに格納されて順序が保たれますが、並列実行はされません。APIへの多数の呼び出しを並列化してスクリプトを高速化したい場合は、独自のThreadPoolExecutorを設定して使用する必要があります。
注: upload_file()、upload_folder()、create_commit() などのよく使われるメソッドには、バックグラウンドで直接呼び出すための run_as_future: bool 引数が用意されています。これらは api.run_as_future(...) を呼び出すのと同じですが、記述が簡潔です。
run_job
< source >( image: strcommand: list[str]env: dict[str, Any] | None = Nonesecrets: dict[str, Any] | None = Noneflavor: JobHardware | str | None = Nonetimeout: int | float | str | None = Noneattempts: int | None = Nonename: str | None = Nonelabels: dict[str, str] | None = Nonevolumes: list[Volume] | None = Noneexpose: list[int] | None = Noneexpose_public: list[int] | None = Nonessh: bool = Falsenetwork_group: str | None = Nonenetwork_aliases: list[str] | None = Noneresource_group_id: str | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None )
パラメータ
- image (
str) — 使用する Docker イメージです。 例:"ubuntu"、"python:3.12"、"pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel"。 Space からのイメージの例:"hf.co/spaces/lhoestq/duckdb"。 - command (
list[str]) — 実行するコマンド。例:["echo", "hello"]。 - env (
dict[str, Any]、省略可) — Job の環境変数を定義します。 - secrets (
dict[str, Any], 省略可) — Job のシークレット環境変数を定義します。 - flavor (
str, 任意) — ハードウェアの Flavor です。使用可能な値についてはJobHardwareを参照してください。 デフォルト値は"cpu-basic"です。 - timeout (
Union[int, float, str], 省略可) — Job の最大実行時間: 単位は s (秒、デフォルト)、m (分)、h (時間)、d (日) を持つ int。 例: 5 分なら300または"5m"。 - attempts (
int, 任意) — 初期実行を含む最大試行回数です。デフォルト値は 1 です。例えば、3 を指定すると、失敗した Job は最大 2 回リトライされます。 - name (
str, 省略可) — Job の名前です。nameラベルとして保存されます。labelsにnameキーを同時に渡すことはできません。名前の一意性は必須ではありません。デフォルトでは、イメージとコマンドから派生した名前（短いハッシュサフィックス付き）が使用されます。 - labels (
dict[str, str], 省略可) — ジョブに付与するラベル（キーと値のペア）。 - volumes (
list[Volume]、任意) — ジョブのコンテナにボリュームとしてマウントする Hugging Face Buckets または Repos。 各ボリュームは Volume で、type("bucket"、"model"、"dataset"、または"space")、source(例:"username/my-bucket")、およびmount_path(例:"/data") を持ちます。 - expose (
list[int], 任意) — ジョブプロキシ経由で公開するコンテナポートです。リストに指定された各ポートは、パブリックなジョブドメイン（例:https://<job_id>--8000.hf.jobs）からアクセスできます。アクセスには常に、そのジョブのネームスペースに対する読み取り権限を持つ HF トークンが必要です。認証なしでのアクセスにはexpose_publicを使用してください。 - expose_public (
list[int], 省略可) — 認証なしで Jobs プロキシ経由で公開するポートです。exposeに列挙する必要はありません。 - ssh (
bool, 省略可能) — True の場合、ジョブのコンテナはjob.status.ssh_urlで指定された URL 経由で SSH 接続可能になります（例:ssh <job_id>@ssh.hf.jobs、または CLI からhf jobs ssh <job_id>）。接続には、ジョブのネームスペースへの書き込みアクセス権と、Hub に登録された SSH 公開鍵が必要です（https://huggingface.co/settings/keys）。デフォルトは False です。 - network_group (
str, 省略可) — 参加するネットワークグループの名前。同じ namespace と resource group を共有し、同じグループに属するジョブは一緒に配置され、すべてのポートで相互に通信できます。各メンバー内で、HF_NETWORK_GROUP_HOSTNAMEはグループのすべてのメンバーに解決されます。小文字の英数字とダッシュのみ使用でき、最大 46 文字です。 - network_aliases (
list[str], 省略可) — このジョブがネットワークグループ内で要求するエイリアスです。メンバーは、エイリアスを要求しているジョブに${HF_NETWORK_GROUP_PREFIX}<alias>経由でアクセスできます。複数のジョブが同じエイリアスを要求できます。小文字の英数字とダッシュのみ使用でき、最大34文字、ジョブ内で一意である必要があります。network_groupが必須です。 - resource_group_id (
str, 任意) — Job を作成するリソースグループの ID です。組織内のリソースへのアクセス制御や、コストの帰属・支出上限機能に使用されます。指定されない場合、Job はリソースグループの外に作成されます。 - namespace (
str, 省略可能) — Job が作成される namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。
Hugging Faceのインフラストラクチャ上でcompute Jobsを実行します。
例:
最初のJobを実行する:
>>> from huggingface_hub import run_job
>>> run_job(image="python:3.12", command=["python", "-c" ,"print('Hello from HF compute!')"])GPUジョブの実行:
>>> from huggingface_hub import run_job
>>> image = "pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel"
>>> command = ["python", "-c", "import torch; print(f'This code ran with the following GPU: {torch.cuda.get_device_name()}')"]
>>> run_job(image=image, command=command, flavor="a10g-small")ボリュームを指定してジョブを実行する:
>>> from huggingface_hub import Volume, run_job
>>> dataset_volume = Volume(type="dataset", source="HuggingFaceFW/fineweb", mount_path="/data")
>>> output_bucket_volume = Volume(type="bucket", source="username/my-bucket", mount_path="/output")
>>> image = "duckdb/duckdb"
>>> command = ["duckdb", "-c", "COPY (SELECT * FROM '/data/**/*.parquet' LIMIT 5) TO '/output/first-rows.parquet'"]
>>> run_job(image=image, command=command, volumes=[dataset_volume, output_bucket_volume])run_uv_job
< source >( script: strscript_args: list[str] | None = Nonedependencies: list[str] | None = Nonepython: str | None = Noneimage: str | None = Noneenv: dict[str, Any] | None = Nonesecrets: dict[str, Any] | None = Noneflavor: JobHardware | str | None = Nonetimeout: int | float | str | None = Noneattempts: int | None = Nonename: str | None = Nonelabels: dict[str, str] | None = Nonevolumes: list[Volume] | None = Noneexpose: list[int] | None = Noneexpose_public: list[int] | None = Nonessh: bool = Falsenetwork_group: str | None = Nonenetwork_aliases: list[str] | None = Noneresource_group_id: str | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None )
パラメータ
- script (
str) — UV スクリプトのパスまたは URL、またはコマンド。 - script_args (
list[str]、省略可) — スクリプトまたはコマンドに渡す引数。 - dependencies (
list[str], 任意) — UVスクリプトの実行に使用する依存関係。 - python (
str, 省略可能) — 特定の Python バージョンを使用します。デフォルトは 3.12 です。 - image (
str、任意、デフォルト値は “ghcr.io/astral-sh/uv —python3.12-bookworm”):uvがインストールされたカスタム Docker イメージを使用します。 - env (
dict[str, Any]、省略可) — Job の環境変数を定義します。 - secrets (
dict[str, Any], 省略可) — Job のシークレット環境変数を定義します。 - flavor (
str, 任意) — ハードウェアの Flavor です。使用可能な値についてはJobHardwareを参照してください。 デフォルト値は"cpu-basic"です。 - timeout (
Union[int, float, str], 省略可) — Job の最大実行時間: 単位は s (秒、デフォルト)、m (分)、h (時間)、d (日) を持つ int。 例: 5 分なら300または"5m"。 - attempts (
int, 任意) — 初期実行を含む最大試行回数。デフォルトは 1 です。 - name (
str, 省略可) — Job の名前です。nameラベルとして保存されます。labelsにnameキーを同時に渡すことはできません。名前の一意性は必須ではありません。デフォルトでは、スクリプトとその引数から派生した名前（短いハッシュサフィックス付き）が使用されます。 - labels (
dict[str, str], 省略可) — ジョブに付与するラベル（キーと値のペア）。 - volumes (
list[Volume]、任意) — ジョブのコンテナにボリュームとしてマウントする Hugging Face Buckets または Repos。 各ボリュームは Volume で、type("bucket"、"model"、"dataset"、または"space")、source(例:"username/my-bucket")、およびmount_path(例:"/data") を持ちます。 - expose (
list[int], 任意) — ジョブプロキシ経由で公開するコンテナポートです。リストに指定された各ポートは、パブリックなジョブドメイン（例:https://<job_id>--8000.hf.jobs）からアクセスできます。アクセスには常に、そのジョブのネームスペースに対する読み取り権限を持つ HF トークンが必要です。認証なしでのアクセスにはexpose_publicを使用してください。 - expose_public (
list[int], 省略可) — 認証なしで Jobs プロキシ経由で公開するポートです。exposeに列挙する必要はありません。 - ssh (
bool, 省略可能) — True の場合、ジョブのコンテナはjob.status.ssh_urlで指定された URL 経由で SSH 接続可能になります（例:ssh <job_id>@ssh.hf.jobs、または CLI からhf jobs ssh <job_id>）。接続には、ジョブのネームスペースへの書き込みアクセス権と、Hub に登録された SSH 公開鍵が必要です（https://huggingface.co/settings/keys）。デフォルトは False です。 - network_group (
str, 省略可) — 参加するネットワークグループの名前。同じ namespace と resource group を共有し、同じグループに属するジョブは一緒に配置され、すべてのポートで相互に通信できます。各メンバー内で、HF_NETWORK_GROUP_HOSTNAMEはグループのすべてのメンバーに解決されます。小文字の英数字とダッシュのみ使用でき、最大 46 文字です。 - network_aliases (
list[str], 省略可) — このジョブがネットワークグループ内で要求するエイリアスです。メンバーは、エイリアスを要求しているジョブに${HF_NETWORK_GROUP_PREFIX}<alias>経由でアクセスできます。複数のジョブが同じエイリアスを要求できます。小文字の英数字とダッシュのみ使用でき、最大34文字、ジョブ内で一意である必要があります。network_groupが必須です。 - resource_group_id (
str, 任意) — Job を作成するリソースグループの ID です。組織内のリソースへのアクセス制御や、コストの帰属・支出上限機能に使用されます。指定されない場合、Job はリソースグループの外に作成されます。 - namespace (
str, 省略可能) — Job が作成される namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。
Hugging Faceのインフラストラクチャ上でUVスクリプトジョブを実行します。
hf jobs uv runとは異なり、このメソッドは、UV スクリプトが PEP 723 ヘッダーに含めることのできる任意の[tool.hf-jobs]テーブル（Jobs ガイドを参照）を無視します。ここでは、起動設定を明示的に渡す必要があります。
例:
URLからスクリプトを実行する:
>>> from huggingface_hub import run_uv_job
>>> script = "https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py"
>>> script_args = ["--model_name_or_path", "Qwen/Qwen2-0.5B", "--dataset_name", "trl-lib/Capybara", "--push_to_hub"]
>>> run_uv_job(script, script_args=script_args, dependencies=["trl"], flavor="a10g-small")ローカルスクリプトを実行します:
>>> from huggingface_hub import run_uv_job
>>> script = "my_sft.py"
>>> script_args = ["--model_name_or_path", "Qwen/Qwen2-0.5B", "--dataset_name", "trl-lib/Capybara", "--push_to_hub"]
>>> run_uv_job(script, script_args=script_args, dependencies=["trl"], flavor="a10g-small")コマンドを実行します:
>>> from huggingface_hub import run_uv_job
>>> script = "lighteval"
>>> script_args= ["endpoint", "inference-providers", "model_name=openai/gpt-oss-20b,provider=auto", "lighteval|gsm8k|0|0"]
>>> run_uv_job(script, script_args=script_args, dependencies=["lighteval"], flavor="a10g-small")volumeをマウントします。例えば、学習中にモデルのチェックポイントを保存する場合などです。
>>> from huggingface_hub import Volume, run_uv_job
>>> script = "my_sft.py"
>>> script_args = ["--output_dir", "/training-outputs/training-v3-final", ...]
>>> checkpoints_bucket = Volume(type="bucket", source="username/my-bucket", mount_path="/training-outputs")
>>> run_uv_job(script, script_args=script_args, volumes=[checkpoints_bucket])scale_to_zero_inference_endpoint
< source >( name: strnamespace: str | None = Nonetoken: bool | str | None = None ) → InferenceEndpoint
パラメータ
- name (
str) — ゼロにスケーリングする Inference Endpoint の名前。 - namespace (
str, 省略可) — Inference Endpoint が配置されている namespace です。デフォルトでは現在のユーザーになります。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
スケーリングがゼロに設定されたInference Endpointに関する情報。
Scale Inference Endpoint to zero.
スケールがゼロに設定された Inference Endpoint には料金は発生しません。次のリクエスト時に、コールドスタートの遅延を伴いながら再開されます。これは、pause_inference_endpoint() で Inference Endpoint を一時停止した場合とは異なり、その場合は resume_inference_endpoint() による手動での再開が必要になります。
For convenience, you can also scale an Inference Endpoint to zero using InferenceEndpoint.scale_to_zero().
search_spaces
< source >( query: strfilter: str | Iterable[str] | None = Nonesdk: str | list[str] | None = Noneinclude_non_running: bool = Falsetoken: bool | str | None = None ) → Iterable[SpaceSearchResult]
パラメータ
- query (
str) — 検索クエリ文字列。 - filter (
strまたはIterable[str]、省略可) — フィルタリングに使用する文字列タグまたはタグのリスト。 - sdk (
strまたはlist[str]、省略可) — SDK でフィルタリングします（例:"gradio"、"docker"、"static"）。 - include_non_running (
bool, 省略可能) — 結果に実行されていない Spaces を含めるかどうか。デフォルトはFalseです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Iterable[SpaceSearchResult]
SpaceSearchResultオブジェクトのイテラブル。
Hub上でセマンティック検索を使用して検索スペースを検索します。
このエンドポイントは、複数語のクエリに対してセマンティック検索（埋め込みベース）、単一語のクエリに対して全文検索を使用します。
set_space_sleep_time
< source >( repo_id: strsleep_time: inttoken: bool | str | None = None ) → SpaceRuntime
パラメータ
- repo_id (
str) — 更新するリポジトリの ID。例:"bigcode/in-the-stack"。 - sleep_time (
int, 任意) — Space がスリープ状態に入るまで、待機状態を何秒間待つかを指定します。Space が一時停止しない場合は-1を設定してください（アップグレードされたハードウェアのデフォルト動作です）。無料ハードウェアでは、スリープ時間を設定できません（値は 48 時間の待機に固定されています）。詳細は https://huggingface.co/docs/hub/spaces-gpus#sleep-time を参照してください。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
Spaceのステージやハードウェアなど、Spaceに関するランタイム情報。
アップグレードされたハードウェアで実行されているSpaceのカスタムスリープ時間を設定します。
Space は、X 秒間アクティビティがないとスリープ状態になります。Space が「sleep」モードにある間は請求されません。新しい訪問者が Space にアクセスすると、Space が「wake up」します。設定可能なスリープ時間は、アップグレードされたハードウェアでのみ利用できます。スリープステージの詳細については、https://huggingface.co/docs/hub/spaces-gpus#sleep-timeを参照してください。
request_space_hardware()でハードウェアをリクエストする際に、カスタムのスリープ時間を設定することも可能です。
set_space_volumes
< source >( repo_id: strvolumes: list[Volume]token: bool | str | None = None )
パラメータ
- repo_id (
str) — 更新する Space の ID。例:"username/my-space"。 - volumes (
list[Volume]) — マウントする Volume オブジェクトのリスト。各ボリュームには、type("bucket"、"model"、"dataset"、または"space")、source(リポジトリまたはバケットの ID)、mount_path(コンテナ内のパス)、および任意のrevision、read_only、pathフィールドがあります。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
例外
BadRequestError
BadRequestError— Space が静的な Space の場合（静的な Space では volumes はサポートされていません）。
Space のボリュームを設定します。
Spaceにマウントされているボリュームのリストを設定（または置き換えます）。各ボリュームは、SpaceのコンテナにHubリソース（モデル、データセット、またはストレージバケット）へのアクセスを提供します。
例:
>>> from huggingface_hub import HfApi, Volume
>>> api = HfApi()
>>> api.set_space_volumes(
... "username/my-space",
... volumes=[
... Volume(type="model", source="username/my-model", mount_path="/models", read_only=True),
... Volume(type="bucket", source="username/my-bucket", mount_path="/data"),
... ],
... )snapshot_download
< source >( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | Path | None = Nonelocal_dir: str | Path | None = Noneetag_timeout: float = 10force_download: bool = Falsetoken: bool | str | None = Nonelocal_files_only: bool = Falseallow_patterns: list[str] | str | None = Noneignore_patterns: list[str] | str | None = Nonemax_workers: int = 8tqdm_class: type[base_tqdm] | None = Nonedry_run: bool = False ) → str or list of DryRunFileInfo
パラメータ
- repo_id (
str) —/で区切られたユーザー名または組織名とリポジトリ名。 - repo_type (
str, 任意) — データセットまたはスペースからダウンロードする場合は"dataset"または"space"、モデルからダウンロードする場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - revision (
str, 省略可) — ブランチ名、タグ、またはコミットハッシュである、任意の Git リビジョン ID。 - cache_dir (
str,Path, 省略可) — キャッシュされたファイルを保存するフォルダへのパス。 - local_dir (
strまたはPath、省略可能) — 指定された場合、ダウンロードされたファイルはこのディレクトリ以下に配置されます。 - etag_timeout (
float、任意、デフォルトは10) — ETagを取得する際、httpx2.requestに渡される、サーバーからデータを受信するまでの待機秒数(タイムアウト)です。 - force_download (
bool、省略可、デフォルトはFalse) — ローカルキャッシュに既に存在する場合でも、ファイルをダウンロードするかどうか。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - local_files_only (
bool、任意、デフォルトはFalse) —Trueの場合、ファイルのダウンロードを回避し、ローカルにキャッシュされたファイルが存在する場合はそのパスを返します。 - allow_patterns (
list[str]またはstr、省略可) — 指定された場合、少なくとも1つのパターンに一致するファイルのみがダウンロードされます。 - ignore_patterns (
list[str]またはstr、省略可) — 指定された場合、これらのパターンのいずれかに一致するファイルはダウンロードされません。 - max_workers (
int, 任意) — ファイルをダウンロードするための同時実行スレッド数（1スレッド = 1ファイルのダウンロード）です。 デフォルト値は 8 です。 - tqdm_class (
tqdm、任意) — 指定された場合、プログレスバーのデフォルトの動作を上書きします。渡される引数はtqdm.auto.tqdmを継承するか、少なくともその動作を模倣している必要があります。なお、tqdm_classは個々のダウンロードには渡されません。デフォルトでは、HF_HUB_DISABLE_PROGRESS_BARS環境変数を設定することで無効化できる、HF独自のプログレスバーが使用されます。 - dry_run (
bool、省略可、デフォルトはFalse) —Trueの場合、ファイルをダウンロードせずにドライランを実行します。ダウンロードされる内容に関する情報が含まれる DryRunFileInfo オブジェクトのリストを返します。
戻り値
str または DryRunFileInfo のリスト
dry_run=Falseの場合: リポジトリのスナップショットのフォルダパス。dry_run=Trueの場合: ダウンロード情報を含むDryRunFileInfoオブジェクトのリスト。
例外
RepositoryNotFoundError または RevisionNotFoundError または EnvironmentError または OSError または ValueError
- RepositoryNotFoundError —
ダウンロード元のリポジトリが見つからない場合に発生します。存在しないか、
privateに設定されておりアクセス権限がないことが原因です。 - RevisionNotFoundError — ダウンロード元のリビジョンが見つからない場合。
EnvironmentError—token=Trueが設定されている場合で、トークンが見つからない場合に発生します。OSError— ETag を決定できない場合。ValueError— パラメータの値が無効な場合。
リポジトリのファイルをダウンロードします。
指定されたリビジョンのリポジトリのファイルのスナップショット全体をダウンロードします。事前にどのファイルが必要か分からない場合、リポジトリのすべてのファイルを取得したい場合に便利です。実際のファイル名をそのフォルダに対する相対パスとして保持するため、すべてのファイルはフォルダ内にネストされます。allow_patternsとignore_patternsを使用して、ダウンロードするファイルをフィルタリングすることもできます。
local_dir が指定されている場合、リポジトリのファイル構造がこの場所に複製されます。このオプションを使用すると、cache_dir は使用されず、local_dir のルートに .cache/huggingface/ フォルダが作成され、ダウンロードされたファイルに関連する一部のメタデータが保存されます。この仕組みはメインのキャッシュシステムほど堅牢ではありませんが、リポジトリの最新バージョンを定期的に取得するように最適化されています。
代替案としてリポジトリをクローンする方法がありますが、これにはgitとgit-lfsがインストールされ、正しく設定されている必要があります。また、gitを使用してリポジトリをクローンする際、ダウンロードするファイルをフィルタリングすることはできません。
space_info
< source >( repo_id: strrevision: str | None = Nonetimeout: float | None = Nonefiles_metadata: bool = Falseexpand: list[ExpandSpaceProperty_T] | None = Nonetoken: bool | str | None = None ) → SpaceInfo
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - revision (
str, 任意) — 情報を取得するスペースリポジトリのリビジョン。 - timeout (
float, 任意) — Hub へのリクエストにタイムアウトを設定するかどうか。 - files_metadata (
bool, 省略可) — リポジトリ内のファイルのメタデータ（サイズ、LFS メタデータなど）を取得するかどうか。デフォルトはFalseです。 - expand (
list[ExpandSpaceProperty_T], 任意) — レスポンスで返すプロパティのリスト。指定した場合、リストに含まれるプロパティのみが返されます。fullが渡されている場合は、このパラメーターを使用できません。 指定可能な値は"author"、"cardData"、"createdAt"、"datasets"、"disabled"、"lastModified"、"likes"、"models"、"private"、"region"、"runtime"、"sdk"、"siblings"、"sha"、"subdomain"、"tags"、"trendingScore"、"usedStorage"、"visibility"、および"resourceGroup"です。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
スペースのリポジトリ情報。
huggingface.co上の特定の1つのSpaceに関する情報を取得します。
許可されたトークンを渡すことで、Spaceをプライベートに設定できます。
以下のエラーを発生させます：
- RepositoryNotFoundError ダウンロード元のリポジトリが見つからない場合に発生します。存在しないか、
privateに設定されておりアクセス権限がないことが原因です。- RevisionNotFoundError ダウンロード元のリビジョンが見つからない場合に発生します。
super_squash_history
< source >( repo_id: strbranch: str | None = Nonecommit_message: str | None = Nonerepo_type: str | None = Nonetoken: str | bool | None = None )
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - branch (
str, 任意) — squash するブランチです。デフォルトでは、"main"ブランチのヘッドです。 - commit_message (
str, 省略可) — squash された commit に使用する commit message。 - repo_type (
str, 省略可) — データセットまたは Space のコミットをリストする場合は"dataset"または"space"、モデルからリストする場合はNoneまたは"model"を設定します。デフォルトはNoneです。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
- RepositoryNotFoundError — リポジトリが見つからない場合（エラー 404）: repo_id/repo_type が誤っている、プライベートリポジトリだが認証されていない、またはリポジトリが存在しない。
- RevisionNotFoundError — squash 対象のブランチが見つからない場合。
- BadRequestError — ブランチの参照が無効な場合。タグでは履歴をsquashできません。
Hub上のリポジトリのブランチでコミット履歴をsquashします。
リポジトリの履歴をsquash（結合）することは、数百回のコミットを行うことが見込まれ、履歴を煩雑にしたくない場合に有用です。コミットのsquashは、ブランチの先頭（head）からのみ実行できます。
squash された後、コミット履歴は復元できません。これは元に戻せない操作です。
ブランチの履歴がsquashされた後、履歴が分岐しているため、他のブランチにマージすることはできません。
例:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
# Create repo
>>> repo_id = api.create_repo("test-squash").repo_id
# Make a lot of commits.
>>> api.upload_file(repo_id=repo_id, path_in_repo="file.txt", path_or_fileobj=b"content")
>>> api.upload_file(repo_id=repo_id, path_in_repo="lfs.bin", path_or_fileobj=b"content")
>>> api.upload_file(repo_id=repo_id, path_in_repo="file.txt", path_or_fileobj=b"another_content")
# Squash history
>>> api.super_squash_history(repo_id=repo_id)suspend_scheduled_job
< source >( scheduled_job_id: strnamespace: str | None = Nonetoken: bool | str | None = None )
パラメータ
- scheduled_job_id (
str) — スケジュールされた Job の ID。 - namespace (
str, 省略可能) — スケジュールされた Job が存在する namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。
Hugging Face のインフラストラクチャ上でスケジュールされた compute Job を一時停止（サスペンド）します。
sync_bucket
< source >( source: str | None = Nonedest: str | None = Nonedelete: bool = Falseignore_times: bool = Falseignore_sizes: bool = Falseexisting: bool = Falseignore_existing: bool = Falseinclude: list[str] | None = Noneexclude: list[str] | None = Nonefilter_from: str | None = Noneplan: str | None = Noneapply: str | None = Nonedry_run: bool = Falseverbose: bool = Falsequiet: bool = Falsetoken: bool | str | None = None ) → [SyncPlan]
パラメータ
- source (str、任意) —
ソースパス: ローカルディレクトリまたは
hf://buckets/namespace/bucket_name(/prefix)。applyを使用しない場合は必須です。 - dest (str、任意) —
宛先パス: ローカルディレクトリまたは
hf://buckets/namespace/bucket_name(/prefix)。applyを使用しない場合は必須です。 - delete (bool、optional、デフォルトは False) — ソースに存在しない宛先のファイルを削除します。
- ignore_times (bool、任意、デフォルトは False) — 変更時刻を無視し、サイズのみを基準としてファイルをスキップします。
- ignore_sizes (bool、任意、デフォルトは False) — ファイルサイズを無視し、変更時刻のみを基準としてファイルをスキップします。
- existing (bool、任意、デフォルトは False) — 受信側で新しいファイルの作成をスキップします（既存のファイルのみを更新します）。
- ignore_existing (bool、任意、デフォルトは False) — 受信側に既に存在するファイルの更新をスキップします（新規ファイルのみを作成します）。
- include (list[str], optional) — パターン（fnmatch形式）に一致するファイルを含めます。
- exclude (list[str], optional) — パターン（fnmatch形式）に一致するファイルを除外します。
- filter_from (str, optional) — インクルード/エクスクルードルールを含むフィルタファイルへのパス。
- plan (str, optional) — 実行せずに、この JSONL ファイルに同期プランを保存します。
- apply (str, optional) —
以前に保存したプランファイルを適用します。設定されている場合、
sourceとdestは不要です。 - dry_run (bool、任意、デフォルトは False) — 実行せずに、同期計画を JSONL 形式で標準出力に出力します。
- verbose (bool、任意、デフォルトは False) — ファイルごとの詳細な操作を表示します。
- quiet (bool、任意、デフォルトは False) — すべての出力とプログレスバーを抑制します。
- token (Union[bool, str, None], optional) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。
戻り値
[SyncPlan]
計算（または読み込み）された同期プラン。
ローカルディレクトリとバケット間でファイルを同期します。
これはhf buckets sync CLIコマンドと同等です。sourceまたはdestのいずれかはバケットパス(hf://buckets/...)であり、もう一方はローカルディレクトリパスである必要があります。
例:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
# Upload local directory to bucket
>>> api.sync_bucket("./data", "hf://buckets/username/my-bucket")
# Download bucket to local directory
>>> api.sync_bucket("hf://buckets/username/my-bucket", "./data")
# Sync with delete and filtering
>>> api.sync_bucket(
... "./data",
... "hf://buckets/username/my-bucket",
... delete=True,
... include=["*.safetensors"],
... )
# Dry run: preview what would be synced
>>> plan = api.sync_bucket("./data", "hf://buckets/username/my-bucket", dry_run=True)
>>> plan.summary()
{'uploads': 3, 'downloads': 0, 'deletes': 0, 'skips': 1, 'total_size': 4096}
# Save plan for review, then apply
>>> api.sync_bucket("./data", "hf://buckets/username/my-bucket", plan="sync-plan.jsonl")
>>> api.sync_bucket(apply="sync-plan.jsonl")sync_job_volume
< source >( source: str | Pathmount_path: strremote_name: str | None = Noneread_only: bool = Truenamespace: str | None = Nonetoken: bool | str | None = None ) → Volume
パラメータ
- source (
strまたはPath) — 同期するローカルディレクトリへのパスです。 - mount_path (
str) — Job コンテナ内のマウントパスです。例:"/inputs"。/で始まる必要があります。 - remote_name (
str, 省略可) — 同期先のバケットのサブフォルダ名です。デフォルトでは、ソースパスとマシンのホスト名から導出される{dirname}-{hash}形式の名前が使用されます。 - read_only (
bool、省略可能、デフォルトはTrue) — Job 内でボリュームを読み取り専用としてマウントします。Job がバケットフォルダに書き戻せるようにするには、Falseを渡します（その後にsync_bucket()で出力を取得する場合など）。 - namespace (
str, 任意) —jobs-artifactsバケットを所有するネームスペースです。デフォルトでは、現在のユーザーのネームスペースが使用されます。ボリュームをマウントするJobと同じネームスペースを使用してください。 - token (
Union[bool, str, None], 省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。
戻り値
同期対象のサブフォルダーにスコープされたバケットボリューム。run_job()、run_uv_job()、create_scheduled_job()、または create_scheduled_uv_job() の volumes リストに渡すために使用します。
ローカルディレクトリをバケットに同期し、Jobでマウントできる準備が整ったVolumeを返します。
ファイルは、{namespace}/jobs-artifacts バケットのサブフォルダーにアップロードされます（プライベートとして自動作成されます。既に存在しパブリックである場合は警告が表示されます）。sync_bucket() と同じ同期ロジックが使用されるため、同じディレクトリを再同期しても、新規または変更されたファイルのみがアップロードされます。デフォルトでは、サブフォルダー名はディレクトリパスとマシンのホスト名から派生されるため、同じディレクトリからの繰り返し呼び出しでは同じリモートフォルダーが再利用されます。固定の名前を使用するには、remote_name を渡します。
データはバケットにマウントされるのではなく、コピーされることに注意してください。同期後にローカルで加えた変更は Job に反映されません（更新するには sync_job_volume を再実行してください）。また、ボリュームはデフォルトで読み取り専用としてマウントされます。Job が読み書き可能なボリュームに書き込んだデータを取得するには、sync_bucket() を使用してバケットのフォルダを同期してください。ソースディレクトリが空の場合（出力ディレクトリなど）、ボリュームをマウントできるようにプレースホルダーの .keep ファイルがアップロードされます。
例:
>>> from huggingface_hub import run_uv_job, sync_job_volume
# Upload ./training-data once, then run multiple jobs against it
>>> volume = sync_job_volume("./training-data", "/data")
>>> run_uv_job("train.py", script_args=["--learning-rate", "0.01"], volumes=[volume])
>>> run_uv_job("train.py", script_args=["--learning-rate", "0.05"], volumes=[volume])
# Read-write volume to retrieve outputs after the job completes
>>> volume = sync_job_volume("./outputs", "/outputs", read_only=False)
>>> job = run_uv_job("process.py", volumes=[volume])trigger_scheduled_job
< source >( scheduled_job_id: strnamespace: str | None = Nonetoken: bool | str | None = None ) → JobInfo
パラメータ
- scheduled_job_id (
str) — スケジュールされた Job の ID。 - namespace (
str, 省略可能) — スケジュールされた Job が存在する namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。
戻り値
トリガーされた実行に関する情報。
- HfHubHTTPError —
別のインスタンスがすでに実行中で、スケジュールされたジョブで
concurrencyが無効になっている場合、HTTP 409 が返されます。
スケジュールされたJobを即座に実行するようにトリガーします。
これにより、スケジュールされたジョブのspecが即座に1回実行されます。スケジュールは変更されず、次のスケジュール実行にも影響しません。すでにインスタンスが実行中で、かつスケジュールされたジョブが並行実行を許可していない場合、リクエストは拒否されます（HTTP 409）。
とは異なり
< source >( repo_id: strtoken: bool | str | None = Nonerepo_type: str | None = None )
パラメータ
- repo_id (
str) — いいねを解除するリポジトリです。例:"user/my-cool-model"。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - repo_type (
str, 省略可) — データセットやスペースのいいね解除の場合は"dataset"または"space"、モデルのいいね解除の場合はNoneまたは"model"を設定します。デフォルトはNoneです。
- RepositoryNotFoundError — リポジトリが見つからない場合（エラー 404）：repo_id/repo_type が誤っている、非公開リポジトリであるが認証されていない、またはリポジトリが存在しない。
Hub上の特定のリポジトリとは異なり（例：お気に入りリストから削除）。
スパム利用を防ぐため、スクリプトからリポジトリにlikeすることはできません。
また、list_liked_repos()も参照してください。
update_bucket_settings
< source >( bucket_id: strprivate: booltoken: bool | str | None = None )
パラメータ
- bucket_id (
str) — バケットの ID (例:"username/my-bucket")。 - private (
bool) — バケットをプライベートにするかどうか。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
例外
BucketNotFoundError または or
BucketNotFoundError— バケットが見つからない場合。存在しないことが原因である可能性があります。or—privateに設定されているため、アクセス権限がないためです。
Hub上のバケットの設定を更新します。
現在、サポートされている設定はバケットの可視性のみです。
update_collection_item
< source >( collection_slug: stritem_object_id: strnote: str | None = Noneposition: int | None = Nonetoken: bool | str | None = None )
パラメータ
- collection_slug (
str) — 更新するコレクションのスラッグです。例:"TheBloke/recent-models-64f9a55bb3115b4f513ec026"。 - item_object_id (
str) — コレクション内のアイテムのIDです。これは Hub 上のアイテムの ID（repo_id または paper id）ではありません。 CollectionItem オブジェクトから取得する必要があります。例:collection.items[0].item_object_id。 - note (
str, 任意) — コレクション内のアイテムに付与するメモです。メモの最大サイズは500文字です。 - position (
int, 任意) — コレクション内のアイテムの新しい位置。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
コレクション内のアイテムを更新します。
例:
>>> from huggingface_hub import get_collection, update_collection_item
# Get collection first
>>> collection = get_collection("TheBloke/recent-models-64f9a55bb3115b4f513ec026")
# Update item based on its ID (add note + update position)
>>> update_collection_item(
... collection_slug="TheBloke/recent-models-64f9a55bb3115b4f513ec026",
... item_object_id=collection.items[-1].item_object_id,
... note="Newly updated model!",
... position=0,
... )update_collection_metadata
< source >( collection_slug: strtitle: str | None = Nonedescription: str | None = Noneposition: int | None = Noneprivate: bool | None = Nonetheme: str | None = Nonetoken: bool | str | None = None )
パラメータ
- collection_slug (
str) — 更新するコレクションのスラッグです。例:"TheBloke/recent-models-64f9a55bb3115b4f513ec026"。 - title (
str) — 更新するコレクションのタイトル。 - description (
str, 省略可) — 更新するコレクションの説明です。説明の最大サイズは150文字です。 - position (
int, 任意) — ユーザーのコレクション一覧における、コレクションの新しい位置。 - private (
bool、省略可能) — コレクションをプライベートにするかどうか。 - theme (
str, 任意) — Hub上のコレクションのテーマ。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
Hub上のコレクションのメタデータを更新します。
すべての引数は任意です。提供されたメタデータのみが更新されます。
戻り値: Collection
例:
>>> from huggingface_hub import update_collection_metadata
>>> collection = update_collection_metadata(
... collection_slug="username/iccv-2023-64f9a55bb3115b4f513ec026",
... title="ICCV Oct. 2023",
... description="Portfolio of models, datasets, papers and demos I presented at ICCV Oct. 2023",
... private=False,
... theme="pink",
... )
>>> collection.slug
"username/iccv-oct-2023-64f9a55bb3115b4f513ec026"
# ^collection slug got updated but not the trailing IDupdate_collection_resource_group
< source >( collection_slug: strresource_group_id: str | Nonetoken: bool | str | None = None )
パラメータ
- collection_slug (
str) — 更新するコレクションのスラッグです。例:"TheBloke/recent-models-64f9a55bb3115b4f513ec026"。 - resource_group_id (
strまたはNone) — コレクションを割り当てるリソースグループを、24文字の16進数文字列として指定します。Noneの場合、コレクションはリソースグループから削除されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
コレクションをリソースグループに割り当て、またはリソースグループから削除します。
組織が所有するコレクションでのみ有効です。
update_inference_endpoint
< source >( name: straccelerator: str | None = Noneinstance_size: str | None = Noneinstance_type: str | None = Nonemin_replica: int | None = Nonemax_replica: int | None = Nonescale_to_zero_timeout: int | None = Nonescaling_metric: InferenceEndpointScalingMetric | None = Nonescaling_threshold: float | None = Nonerepository: str | None = Noneframework: str | None = Nonerevision: str | None = Nonetask: str | None = Nonecustom_image: dict | None = Nonecontainer_command: list[str] | None = Nonecontainer_args: list[str] | None = Nonetensor_parallel_size: int | None = Nonedata_parallel_size: int | None = Noneenv: dict[str, str] | None = Nonesecrets: dict[str, str] | None = Nonedomain: str | None = Nonepath: str | None = Nonecache_http_responses: bool | None = Nonetags: list[str] | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None ) → InferenceEndpoint
パラメータ
- name (
str) — 更新する Inference Endpoint の名前。 - accelerator (
str, 省略可) — 推論に使用するハードウェアアクセラレータ（例:"cpu"）。 - instance_size (
str, 省略可) — モデルのホスティングに使用するインスタンスのサイズまたはタイプ（例:"x4"）。 - instance_type (
str, 任意) — Inference Endpoint がデプロイされるクラウドインスタンスの種類（例:"intel-icl"）。 - min_replica (
int、省略可) — Inference Endpoint で稼働を維持するレプリカ（インスタンス）の最小数。 - max_replica (
int、省略可) — Inference Endpoint のスケーリング先となるレプリカ（インスタンス）の最大数です。 - scale_to_zero_timeout (
int, 任意) — 非アクティブなエンドポイントがゼロにスケーリングされるまでの時間（分単位）。 - scaling_metric (
strまたはInferenceEndpointScalingMetric、省略可) — スケーリング用のメトリック参照です。指定する場合、“pendingRequests” または “hardwareUsage” のいずれかです。 デフォルト値は None です。 - scaling_threshold (
float, 任意) — スケールアップをトリガーするために使用されるスケーリングメトリクスの閾値です。スケーリングメトリクスが指定されていない場合は無視されます。 デフォルト値は None です。 - repository (
str, 任意) — Inference Endpointに関連付けられたモデルリポジトリの名前（例:"gpt2"）。 - framework (
str, 任意) — モデルで使用される機械学習フレームワーク（例:"custom"）。 - revision (
str, 任意) — Inference Endpoint にデプロイする特定のモデルのリビジョン（例:"6c0e6080953db56375760c0471a8c5f2929baf11"）。 - task (
str, 任意) — モデルをデプロイするタスク（例:"text-classification"）。 - custom_image (
dict, 任意) — 実行するコンテナイメージです。イメージのバリアントをキーとする辞書（例:{"vLLM": {"url": "vllm/vllm-openai:v0.23.0", "port": 8000}}、sGLang、tgi、tei、llamacpp、hfServeなど）として渡すことも、カスタムコンテナを記述するフラットな辞書（例:{"url": ..., "port": ...}）として渡すこともできます。後者の場合は{"custom": ...}として送信されます。 - container_command (
list[str]、省略可) — コンテナのエントリポイントコマンドを上書きします（APIペイロードのmodel.commandにマッピングされます）。マネージドエンジンイメージ（vLLM、SGLang など）およびカスタムイメージの両方で動作します。 - container_args (
list[str]、省略可) — コンテナのエントリポイントに追加される引数です（APIペイロードのmodel.argsに対応します）。マネージドエンジンイメージ（vLLM、SGLang など）およびカスタムイメージの両方で動作します。 - tensor_parallel_size (
int, 省略可) — 単一のモデルコピーを分割して配置するアクセラレータの数（vLLM および SGLang イメージ）。エンジンイメージの設定内に書き込まれます。API はmodel.imageを全体として要求するため、custom_imageが指定されていない場合、エンドポイントに現在設定されているイメージを取得して、その場で更新します。 - data_parallel_size (
int, 省略可) — 1つのアクセラレータごとに1つのモデルコピーを実行する、モデルコピーの数（vLLMイメージ）。tensor_parallel_sizeと同じ処理が行われます。 - env (
dict[str, str]、省略可) — コンテナ環境に注入する非シークレットの環境変数 - secrets (
dict[str, str]、省略可) — コンテナ環境に注入するシークレット値。 - domain (
str, 任意) — Inference Endpoint のデプロイメントに使用するカスタムドメインです。設定されている場合、Inference Endpoint はこのドメインで利用可能になります（例:"my-new-domain.cool-website.woof"）。 - path (
str, 任意) — デプロイされたモデルへのカスタムパスです。/で始まる必要があります（例:"/models/google-bert/bert-base-uncased"）。 - cache_http_responses (
bool, 任意) — Inference EndpointからのHTTPレスポンスをキャッシュするかどうかを指定します。 - tags (
list[str]、任意) — Inference Endpointに関連付けるタグのリストです。 - namespace (
str, 省略可) — Inference Endpoint が更新される namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
更新されたInference Endpointに関する情報。
Inference Endpointを更新します。
このメソッドでは、compute設定、デプロイされたモデル、ルート、またはそれらの任意の組み合わせを更新できます。 すべての引数は任意ですが、少なくとも1つは指定する必要があります。
便宜のため、InferenceEndpoint.update() を使用して Inference Endpoint を更新することもできます。
update_job_expose
< source >( job_id: strexpose: list[int] | None = Noneexpose_public: list[int] | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None ) → JobInfo
パラメータ
- job_id (
str) — 実行中の Job の ID。 - expose (
list[int], 任意) — Jobs プロキシ経由で公開するポート。アクセスには、その Job の namespace に対する読み取りアクセス権限を持つ HF トークンが必要です。 - expose_public (
list[int], 省略可) — 認証なしで Jobs プロキシ経由で公開するポートです。exposeに列挙する必要はありません。 - namespace (
str, 省略可能) — Job の Namespace です。デフォルトでは、現在のユーザーの Namespace が使用されます。 - token (
boolまたはstr、省略可能) — ユーザーアクセストークン。デフォルトでは、ローカルに保存されたトークンが使用されます。
戻り値
更新されたJob。
実行中のJobの公開ポートを、再実行せずに置き換えます。
exposeとexpose_publicを組み合わせることで、完全なポート設定が構成されます。どちらのリストにも含まれていないポートは閉じられます。両方を渡さないと、公開されているすべてのポートが閉じられます。
update_job_labels
< source >( job_id: strlabels: dict[str, str]namespace: str | None = Nonetoken: bool | str | None = None ) → JobInfo
パラメータ
- job_id (
str) — Job の ID。 - labels (
dict[str, str]) — ジョブに設定する新しいラベルです。既存のすべてのラベルを置き換えます。 キーと値の両方は、最大100文字で、英数字、ダッシュ、アンダースコアのみを含む必要があります。 - namespace (
str, 省略可能) — Job が実行されている namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。
戻り値
更新されたジョブ情報。
既存のJobのラベルを更新します。
既存のユーザー指定ラベルをすべて新しいラベルに置き換えます。
update_repo_settings
< source >( repo_id: strgated: Literal['auto', 'manual', False] | None = Noneprivate: bool | None = Nonevisibility: RepoVisibility_T | None = Nonetoken: str | bool | None = Nonerepo_type: str | None = None )
パラメータ
- repo_id (
str) — スラッシュ（/）で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - gated (
Literal["auto", "manual", False], 省略可能) — リポジトリのゲート状態。None(に設定した場合（デフォルト）、リポジトリのgated設定は更新されません。- “auto”: リポジトリはゲート付きであり、事前定義された基準に基づいてアクセスリクエストが自動的に承認または拒否されます。
- “manual”: リポジトリはゲート付きであり、アクセスのリクエストには手動での承認が必要です。
- False : リポジトリはゲートされておらず、誰でもアクセスできます。
- private (
bool、省略可) — リポジトリをプライベートにするかどうか。visibilityと同時に指定することはできません。 - visibility (
Literal["public", "private", "protected"], 省略可) — リポジトリの公開設定。"public"または"private"、Spaces の場合は"protected"を指定できます。 - token (
Union[str, bool, None], 省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、False を渡してください。 - repo_type (
str, 任意) — 設定を更新するリポジトリの種類 ("model"、"dataset"または"space")。 デフォルトは"model"です。
例外
ValueError または HfHubHTTPError または RepositoryNotFoundError
ValueError— gatedが“auto”、“manual”、Falseのいずれでもない場合。ValueError— repo_typeがconstants.REPO_TYPESの値のいずれでもない場合。- HfHubHTTPError — Hugging Face Hub API へのリクエストが失敗した場合。
- RepositoryNotFoundError —
ダウンロード元のリポジトリが見つからない場合に発生します。存在しないか、
privateに設定されておりアクセス権限がないことが原因です。
リポジトリの設定を更新します。ゲート付きアクセスと可視性を含みます。
リポジトリの使用方法に対する制御を強化するため、Hub ではリポジトリの作成者が、リポジトリへのアクセスリクエストを有効にしたり、リポジトリの公開設定を変更したりできます。
update_scheduled_job_labels
< source >( scheduled_job_id: strlabels: dict[str, str]namespace: str | None = Nonetoken: bool | str | None = None ) → ScheduledJobInfo
パラメータ
- scheduled_job_id (
str) — スケジュールされた Job の ID。 - labels (
dict[str, str]) — スケジュールされたジョブに設定する新しいラベルです。既存のすべてのラベルを置き換えます。 キーと値の両方は最大100文字で、英数字、ダッシュ、アンダースコアのみを含む必要があります。 - namespace (
str, 省略可能) — スケジュールされた Job が存在する namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。
戻り値
ScheduledJobInfo
更新されたスケジュール済みジョブの情報。
既存のスケジュール済みJobのラベルを更新します。
既存のユーザー指定ラベルをすべて新しいラベルに置き換えます。
update_scheduled_job_schedule
< source >( scheduled_job_id: strschedule: strnamespace: str | None = Nonetoken: bool | str | None = None ) → ScheduledJobInfo
パラメータ
- scheduled_job_id (
str) — スケジュールされた Job の ID。 - schedule (
str) — “@annually”、“@yearly”、“@monthly”、“@weekly”、“@daily”、“@hourly”、または CRON スケジュール式（例: 毎週月曜日の午前9時を指定する ‘0 9 * * 1’）のいずれかです。 - namespace (
str, 省略可能) — スケジュールされた Job が存在する namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。
戻り値
ScheduledJobInfo
更新されたスケジュール済みジョブの情報。
既存のスケジュール済みJobの実行タイミングを変更します。
スケジュールのみが更新されます。Job の仕様、ラベル、および停止状態は保持されます。スケジュールを変更せずに、スケジュールされた Job を今すぐ一度実行するには、代わりに trigger_scheduled_job() を使用してください。
update_webhook
< source >( webhook_id: strurl: str | None = Nonejob_id: str | None = Nonewatched: list[dict | WebhookWatchedItem] | None = Nonedomains: list[constants.WEBHOOK_DOMAIN_T] | None = Nonesecret: str | None = Nonesecrets: dict[str, str] | None = Nonetoken: bool | str | None = None ) → WebhookInfo
パラメータ
- webhook_id (
str) — 更新対象のWebhookの一意な識別子です。 - url (
str, 任意) — ペイロードが送信されるURL。 - job_id (
str, 任意) — WebhookペイロードでトリガーするソースJobのID。secretsを設定する場合は必須です。 - watched (
list[WebhookWatchedItem], optional) — 監視するアイテムのリストです。ユーザー、組織、モデル、データセット、スペースのいずれかになります。詳細は WebhookWatchedItem を参照してください。監視対象のアイテムは、プレーンな辞書として指定することもできます。 - domains (
list[Literal["repo", "discussion"]], 省略可) — 監視するドメインです。“repo”、“discussion”、またはその両方を指定できます。 - secret (
str, 省略可能) — ペイロードに署名するために使用されるシークレットです。セキュリティの追加のレイヤーを提供します。 - secrets (
dict[str, str], 省略可) — WebhookによってトリガーされるJob用のシークレット環境変数です。リストに列挙されたキーは保存済みの値を置き換え、空文字列は該当するシークレットを削除し、省略されたキーは保存済みの値を保持します。job_idが必要です。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
戻り値
更新されたWebhookに関する情報。
既存のWebhookを更新します。
例:
>>> from huggingface_hub import update_webhook
>>> updated_payload = update_webhook(
... webhook_id="654bbbc16f2ec14d77f109cc",
... url="https://new.webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
... watched=[{"type": "user", "name": "julien-c"}, {"type": "org", "name": "HuggingFaceH4"}],
... domains=["repo"],
... secret="my-secret",
... )
>>> print(updated_payload)
WebhookInfo(
id="654bbbc16f2ec14d77f109cc",
job=None,
url="https://new.webhook.site/a2176e82-5720-43ee-9e06-f91cb4c91548",
watched=[WebhookWatchedItem(type="user", name="julien-c"), WebhookWatchedItem(type="org", name="HuggingFaceH4")],
domains=["repo"],
secret="my-secret",
disabled=False,upload_attachment
< source >( path: str | Pathtoken: bool | str | None = None ) → str
パラメータ
- path (
strまたはPath) — アップロードするファイルへのパスです。対応する形式は、PNG、JPEG、GIF、WebP、MP4、MOV、WebM、MP3、WAV です。 ファイルサイズは 10MB 未満である必要があります（動画の場合は 50MB 未満）。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。トークンにはdiscussion.write権限が必要です。匿名でアップロードする場合は、Falseを渡してください。
戻り値
str
アップロードされたファイルのURL。
例外
ValueError
ValueError— ファイル形式がサポートされていない場合。
画像、動画、または音声ファイルを Hub にアップロードし、その URL を返します。
ファイルをDiscussionまたはPull Requestのコメント欄にドラッグ＆ドロップした際に、HubのWebエディターが実行する処理です。返されたURLを説明欄やコメントに埋め込みます。画像には、動画にはURLそのもの、音声ファイルには<audio controls src="url"></audio>を使用します。
upload_file
< source >( path_or_fileobj: str | Path | bytes | BinaryIOpath_in_repo: strrepo_id: strtoken: str | bool | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecommit_message: str | None = Nonecommit_description: str | None = Nonecreate_pr: bool | None = Noneparent_commit: str | None = Nonerun_as_future: bool = False_hot_reload: bool | None = None ) → CommitInfo or Future
パラメータ
- path_or_fileobj (
str、Path、bytes、またはIO) — ローカルマシン上のファイルへのパス、またはバイナリデータストリーム / fileobj / バッファ。 - path_in_repo (
str) — リポジトリ内の相対ファイルパス。例:"checkpoints/1fec34a/weights.bin" - repo_id (
str) — ファイルがアップロードされるリポジトリ。例:"username/custom_transformers" - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - repo_type (
str, 任意) — データセット、スペース、またはカーネルのリポジトリにアップロードする場合は、それぞれ"dataset"、"space"、"kernel"を設定します。モデルにアップロードする場合はNoneまたは"model"です。デフォルトはNoneです。 - revision (
str, 省略可) — コミット元の git リビジョンです。デフォルトでは、"main"ブランチの先頭になります。 - commit_message (
str, 任意) — 生成されたコミットのサマリー / タイトル / 最初の行 - commit_description (
str, 省略可) — 生成されたコミットの説明 - create_pr (
boolean, 省略可) — そのコミットで Pull Request を作成するかどうか。デフォルトはFalseです。revisionが設定されていない場合、PR は"main"ブランチに対して作成されます。revisionが設定されておりブランチである場合、PR はそのブランチに対して作成されます。revisionが設定されているがブランチ名でない場合（例: コミット OID）、サーバーからRevisionNotFoundErrorが返されます。 - parent_commit (
str, 省略可能) — 親コミットの OID / SHA を16進数文字列として指定します。略記法（先頭7文字）もサポートされています。 指定され、create_prがFalseの場合、revisionがparent_commitを指していないとコミットは失敗します。 指定され、create_prがTrueの場合、parent_commitからプルリクエストが作成されます。parent_commitを指定することで、変更をコミットする前にリポジトリが変更されていないことを保証でき、リポジトリが並行して更新 / コミットされる場合に特に有用です。 - run_as_future (
bool, 省略可) — このメソッドをバックグラウンドで実行するかどうか。バックグラウンドジョブは、メインスレッドをブロックせずにシーケンシャルに実行されます。run_as_future=Trueを渡すと、Future オブジェクトが返されます。デフォルトはFalseです。
戻り値
CommitInfoまたはFuture
新しく作成されたコミットに関する情報（コミットハッシュ、コミットURL、PR URL、コミットメッセージなど）を含むCommitInfoのインスタンスを返します。run_as_future=Trueが渡された場合、実行時に結果を含むFutureオブジェクトを返します。
ローカルファイル（最大50 GB）を指定されたリポジトリにアップロードします。アップロードはHTTPのPOSTリクエストを通じて行われ、gitやgit-lfsのインストールは不要です。
以下のエラーを発生させます：
- HuggingFace API がエラーを返した場合に
HTTPErrorValueError一部のパラメータ値が無効な場合- RepositoryNotFoundError ダウンロード元のリポジトリが見つからない場合に発生します。存在しないか、
privateに設定されておりアクセス権限がないことが原因です。- RevisionNotFoundError ダウンロード元のリビジョンが見つからない場合に発生します。
upload_fileは、リポジトリがすでに Hub に存在することを前提としています。Client error 404 が返された場合は、認証が有効であること、トークンに必要な権限が付与されていること、repo_idとrepo_typeが正しく設定されていることを確認してください。リポジトリが存在しない場合は、create_repo() を使用して先に作成してください。
例:
>>> from huggingface_hub import upload_file
>>> with open("./local/filepath", "rb") as fobj:
... upload_file(
... path_or_fileobj=fileobj,
... path_in_repo="remote/file/path.h5",
... repo_id="username/my-dataset",
... repo_type="dataset",
... token="my_token",
... )
>>> upload_file(
... path_or_fileobj=".\\local\\file\\path",
... path_in_repo="remote/file/path.h5",
... repo_id="username/my-model",
... token="my_token",
... )
>>> upload_file(
... path_or_fileobj=".\\local\\file\\path",
... path_in_repo="remote/file/path.h5",
... repo_id="username/my-model",
... token="my_token",
... create_pr=True,
... )upload_folder
< source >( repo_id: strfolder_path: str | Pathpath_in_repo: str | None = Nonecommit_message: str | None = Nonecommit_description: str | None = Nonetoken: str | bool | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonecreate_pr: bool | None = Noneparent_commit: str | None = Noneallow_patterns: list[str] | str | None = Noneignore_patterns: list[str] | str | None = Nonedelete_patterns: list[str] | str | None = Nonerun_as_future: bool = False ) → CommitInfo or Future
パラメータ
- repo_id (
str) — ファイルがアップロードされるリポジトリ。例:"username/custom_transformers" - folder_path (
strまたはPath) — ローカルファイルシステム上でアップロードするフォルダへのパス - path_in_repo (
str, 省略可能) — リポジトリ内のディレクトリの相対パスです。例:"checkpoints/1fec34a/results"。デフォルトでは、リポジトリのルートフォルダになります。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - repo_type (
str, 任意) — データセット、スペース、またはカーネルのリポジトリにアップロードする場合は、それぞれ"dataset"、"space"、"kernel"を設定します。モデルにアップロードする場合はNoneまたは"model"です。デフォルトはNoneです。 - revision (
str, 省略可) — コミット元の git リビジョンです。デフォルトでは、"main"ブランチの先頭になります。 - commit_message (
str, 任意) — 生成されたコミットのサマリー / タイトル / 最初の行です。デフォルト値は:f"Upload {path_in_repo} with huggingface_hub" - commit_description (
str任意) — 生成されたコミットの説明 - create_pr (
boolean、省略可) — そのコミットで Pull Request を作成するかどうか。デフォルトはFalseです。PR は常にデフォルトブランチに対して開かれます。create_pr=Trueとrevisionの両方を設定すると、ValueErrorが発生します。なお、create_pr=Trueを指定した各呼び出しで新しい Pull Request が開かれます。中断されたアップロードを既存の PR に再開するには、代わりにrevision="refs/pr/N"を指定して再実行してください。 - parent_commit (
str, 省略可能) — 親コミットの OID / SHA を16進数文字列として指定します。略記法（先頭7文字）もサポートされています。 指定され、かつcreate_prがFalseの場合、revisionがparent_commitを指していないとコミットは失敗します。parent_commitを指定することで、変更をコミットする前にリポジトリが変更されていないことを保証でき、リポジトリが並行して更新 / コミットされる場合に特に有用です。アップロードが複数のコミットに分割される場合（大きなフォルダなど）、parent_commitは最初のコミットにのみ適用されます。 - allow_patterns (
list[str]またはstr、省略可) — 指定された場合、少なくとも1つのパターンに一致するファイルのみがアップロードされます。 - ignore_patterns (
list[str]またはstr、省略可) — 指定された場合、これらのパターンのいずれかに一致するファイルはアップロードされません。 - delete_patterns (
list[str]またはstr、省略可) — 指定された場合、新しいファイルをコミットする際に、これらのパターンのいずれかに一致するリモートファイルがリポジトリから削除されます。すでにどのファイルがアップロードされているか不明な場合に便利です。 注: 不整合を避けるため、.gitattributesファイルはパターンに一致していても削除されません。 - run_as_future (
bool, 省略可) — このメソッドをバックグラウンドで実行するかどうか。バックグラウンドジョブは、メインスレッドをブロックせずにシーケンシャルに実行されます。run_as_future=Trueを渡すと、Future オブジェクトが返されます。デフォルトはFalseです。
戻り値
CommitInfoまたはFuture
新しく作成されたコミットに関する情報（コミットハッシュ、コミットURL、PR URL、コミットメッセージなど）を含むCommitInfoのインスタンスを返します。run_as_future=Trueが渡された場合、実行時に結果を含むFutureオブジェクトを返します。
ローカルフォルダを指定されたリポジトリにアップロードします。アップロードはHTTPリクエストを通じて行われ、gitやgit-lfsのインストールは不要です。
フォルダの構造は保持されます。リポジトリ内に同名のファイルが既に存在する場合、そのファイルは上書きされます。その他のファイルは変更されません。
allow_patterns と ignore_patterns の引数を使用して、アップロードするファイルを指定します。これらのパラメータは、単一のパターンまたはパターンのリストを受け取ります。パターンは、こちらにドキュメント化されている標準ワイルドカード（globbing パターン）です。allow_patterns と ignore_patterns の両方が指定された場合、両方の制約が適用されます。デフォルトでは、フォルダー内のすべてのファイルがアップロードされます。
delete_patterns 引数を使用して、削除したいリモートファイルを指定します。入力タイプは allow_patterns と同じです（上記を参照）。path_in_repo も指定されている場合、パターンはこのフォルダからの相対パスに対して照合されます。例えば、upload_folder(..., path_in_repo="experiment", delete_patterns="logs/*") は、./experiment/logs/ 配下のすべてのリモートファイルを削除します。パターンに一致する場合でも、.gitattributes ファイルは削除されません。
サブディレクトリ内のどこかに存在する.git/フォルダは無視されます。ただし、.gitignoreファイルは考慮されない点にご注意ください。
hf_xet がインストールされている場合（デフォルト）、ファイルはストリーミングパイプラインを通じてアップロードされます。フォルダが Hub と照合されている間にアップロードが開始され、アップロード用のチャンク分割が行われると同時にファイルのハッシュが計算されます（読み取りは1パスのみ）。また、大規模なフォルダはサーバーの制限を超えないように自動的に複数のバッチでコミットされます（後続のコミットにはコミットメッセージに(part N)のサフィックスが付与されます）。アップロードが中断された場合、同じ呼び出しを再実行すると再開されます。すでにコミットされたファイルはスキップされ、すでにアップロードされたデータは重複排除されます。hf_xet がインストールされていない場合、create_commit() を使用して作成される単一のコミットにフォールバックします。
以下のエラーを発生させます：
- HuggingFace API がエラーを返した場合に
HTTPErrorValueError一部のパラメータ値が無効な場合
upload_folderは、リポジトリが Hub に既に存在することを前提としています。Client error 404 が返された場合は、認証が有効であること、トークンに必要な権限が付与されていること、repo_idとrepo_typeが正しく設定されていることを確認してください。リポジトリが存在しない場合は、まず create_repo() を使用して作成してください。
例:
# Upload checkpoints folder except the log files
>>> upload_folder(
... folder_path="local/checkpoints",
... path_in_repo="remote/experiment/checkpoints",
... repo_id="username/my-dataset",
... repo_type="datasets",
... token="my_token",
... ignore_patterns="**/logs/*.txt",
... )
# Upload checkpoints folder including logs while deleting existing logs from the repo
# Useful if you don't know exactly which log files have already being pushed
>>> upload_folder(
... folder_path="local/checkpoints",
... path_in_repo="remote/experiment/checkpoints",
... repo_id="username/my-dataset",
... repo_type="datasets",
... token="my_token",
... delete_patterns="**/logs/*.txt",
... )
# Upload checkpoints folder while creating a PR
>>> upload_folder(
... folder_path="local/checkpoints",
... path_in_repo="remote/experiment/checkpoints",
... repo_id="username/my-dataset",
... repo_type="datasets",
... token="my_token",
... create_pr=True,
... )verify_repo_checksums
< source >( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonelocal_dir: str | Path | None = Nonecache_dir: str | Path | None = Nonetoken: str | bool | None = None ) → FolderVerification
パラメータ
- repo_id (
str) —/で区切られた名前空間（ユーザーまたは組織）とリポジトリ名。 - repo_type (
str, 省略可) — ツリーを取得するリポジトリの種類（"model"、"dataset"、または"space"）。 デフォルトは"model"です。 - revision (
str, 任意) — ツリーを取得するリポジトリのリビジョンです。デフォルトは"main"ブランチです。 - local_dir (
strまたはPath、省略可能) — 検証対象のローカルディレクトリです。 - cache_dir (
strまたはPath、省略可) — 検証対象のキャッシュディレクトリです。 - token (Union[bool, str, None], optional) —
有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、
Falseを渡します。
戻り値
FolderVerification
検証の詳細を含む構造化された結果。
- RepositoryNotFoundError — リポジトリが見つからない場合（エラー 404）: repo_id/repo_type が誤っている、プライベートリポジトリだが認証されていない、またはリポジトリが存在しない。
- RevisionNotFoundError — リポジトリ上でリビジョンが見つからない場合（エラー 404）。
リポジトリのローカルファイルを、Hubのチェックサムに対して検証します。
wait_for_job
< source >( job_id: str | list[str]timeout: float | None = Nonepoll_interval: float = 1.0stages: list[JobStage] | None = Nonenamespace: str | None = Nonetoken: bool | str | None = None ) → JobInfo or list[JobInfo]
パラメータ
- job_id (
strまたはlist[str]) — Job の ID、または待機する Job ID のリストです。リストが渡された場合、JobInfo のリストが返されます（同じ順序で）。 - timeout (
float, 省略可) — Job の完了を待機する最大時間（秒）。Noneの場合は、無期限に待機します。 - poll_interval (
float, 任意) — 各ステータスチェックの間隔を秒単位で指定します。デフォルト値は1秒です。 - stages (
list[JobStage]、省略可) — 待機するステージです。デフォルトでは、ターミナルステージ（"COMPLETED"、"CANCELED"、"ERROR"、"DELETED"）を指定します。Job の実行開始を待機するには、例えば[JobStage.RUNNING]を渡します。 ターミナルステージは、この値に関係なく常に待機を停止します。 - namespace (
str, 省略可能) — Job が実行されている namespace です。デフォルトでは、現在のユーザーの namespace が使用されます。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。指定しない場合、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。 参照: https://huggingface.co/docs/huggingface_hub/quick-start#authentication。
戻り値
JobInfoまたはlist[JobInfo]
最終的なJob info(s)。
例外
TimeoutError
TimeoutError— 少なくとも1つのJobがtimeout秒後に目標のステージのいずれかに到達していない場合。
Hugging Face のインフラストラクチャ上で、1 つ以上の compute Jobs が指定されたステージに到達するまで待機します。
各 Job のステータスは、そのステージが stages（デフォルトではターミナルステージ: "COMPLETED"、"CANCELED"、"ERROR" または "DELETED"）のいずれかになるまで、poll_interval 秒ごとに inspect_job() でポーリングされます。いずれの場合も、最終的な JobInfo が返されます。失敗またはキャンセルされた Job は 例外を発生させません — 結果に基づいて処理を行うには、job.status.stage を確認してください。
ターミナルステージは、stages に列挙されていなくても、常に待機を停止します。これにより、Job が到達することのないステージ（例: スケジューリング中に失敗する Job に対して "RUNNING" を待機すること）を永遠に待たないようにします。
wait_for_space
< source >( repo_id: strtimeout: float | None = Nonepoll_interval: float = 1.0token: bool | str | None = None ) → SpaceRuntime
パラメータ
- repo_id (
str) — 待機する Space の ID。例:"username/my-space"。 - timeout (
float, 省略可) — 待機する最大時間(秒)。Noneの場合、無限に待機します。 - poll_interval (
float, 任意) — ステータスチェック間の秒数。デフォルトは1秒です。 - token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークンです。デフォルトでは、ローカルに保存されたトークンが使用されます。これが推奨される認証方法です。認証を無効にするにはFalseを設定してください。https://huggingface.co/docs/huggingface_hub/quick-start#authentication を参照してください。
戻り値
Spaceが終端状態に達した時点での最終的なランタイム情報。
例外
TimeoutError
TimeoutError— Space がtimeout秒後に到達していない場合。
Spaceが終端状態（ビルド中/起動中ではない状態）に達するまで待機します。
ポーリングは、Space のステージが中間状態（BUILDING、RUNNING_BUILDING、APP_STARTING、RUNNING_APP_STARTING）でなくなるまで、poll_interval 秒ごとに get_space_runtime() を呼び出します。いずれの場合も最終的な SpaceRuntime を返します。結果に基づいて処理を行うには、runtime.stage を確認してください（例：RUNNING と BUILD_ERROR の区別）。
whoami
< source >( token: bool | str | None = Nonecache: bool = False )
パラメータ
- token (
boolまたはstr、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。 - cache (
bool, 省略可) —whoami呼び出しの結果を、その後の呼び出しのためにキャッシュするかどうか。 最初の呼び出し中にエラーが発生した場合、結果はキャッシュされません。 デフォルトはFalseです。
HF APIを呼び出して「whoami」を確認します。
cache=Trueを渡すと、そのPythonプロセスが存続する間、結果がキャッシュされ、以降の呼び出しで再利用されます。セキュリティ上の理由からこのエンドポイントはレート制限が厳しく設定されているため、whoamiを複数回呼び出す予定がある場合に便利です。
API データクラス
AccessRequest
class huggingface_hub.hf_api.AccessRequest
< source >( username: str | Nonerequest_id: strfullname: str | Noneemail: str | Nonetimestamp: datetimestatus: Literal['pending', 'accepted', 'rejected']fields: dict[str, Any] | None = None )
パラメータ
- username (
str, 省略可) — アクセスをリクエストしたユーザーのユーザー名。リポジトリがリクエスト者のユーザー名を共有しないように設定されている場合はNoneになります。その場合は、request_idを使用してリクエストを承認、拒否、またはキャンセルしてください。 - request_id (
str) — アクセスリクエストのIDです。ユーザー名が共有されていない場合でも、常に設定されます。 - fullname (
str, 省略可) — アクセスをリクエストしたユーザーのフルネームです。リポジトリがリクエスト者のユーザー名を共有しないように設定されている場合はNoneになります。 - email (
str, 任意) — アクセスをリクエストしたユーザーのメールアドレス。ユーザーが手動でアクセス権限を付与された場合、またはリポジトリがリクエスト者のメールアドレスを共有しないように設定されている場合はNoneになります。 - timestamp (
datetime) — リクエストのタイムスタンプ。 - status (
Literal["pending", "accepted", "rejected"]) — リクエストのステータス。["pending", "accepted", "rejected"]のいずれかです。 - fields (
dict[str, Any]、省略可) — ゲートフォームでユーザーが入力する追加のフィールド。
ユーザーのアクセス要求に関する情報を含むデータ構造。
BucketFile
Hub上のバケット内のファイルに関する情報を含みます。このオブジェクトはlist_bucket_tree()によって返されます。
RepoFileと同様に、バケット内のファイル用です。
BucketFileMetadata
クラス huggingface_hub.BucketFileMetadata
< source >( size: intxet_file_data: XetFileData )
バケット内のファイルに関する情報を含むデータ構造。
get_bucket_file_metadata()によって返されます。
BucketInfo
クラス huggingface_hub.BucketInfo
< source >( **kwargs )
Hub上のバケットに関する情報を含みます。このオブジェクトはbucket_info()およびlist_buckets()によって返されます。
BucketUrl
クラス huggingface_hub.BucketUrl
< source >( url: strendpoint: str = '' )
パラメータ
- url (
str) — バケットの URL の文字列値。 - endpoint (
str, 省略可) — Hub のエンドポイントです。デフォルト値は https://huggingface.co です。
Hub上のバケットURLを説明します。
BucketUrl は create_bucket() によって返されます。初期化時に、URL が解析されてプロパティが設定されます。
- エンドポイント (
str) strの名前空間- bucket_id (
str) - URL (
str) - uri (
HfUri)
DatasetLeaderboardEntry
クラス huggingface_hub.DatasetLeaderboardEntry
< source >( **kwargs )
パラメータ
- rank (
int) — リーダーボード上のモデルの順位（1始まり）。 - model_id (
str) — モデルの ID(例:"meta-llama/Llama-3-8b")。 - value (
float) — 評価スコアの値。 - filename (
str) — 評価データを含む結果ファイルの名前。 - verified (
bool) — 結果が検証済みかどうかを示します。 - source (
dict[str, Any]、省略可) — 評価結果のソースに関する情報。"url"、"name"、"isExternal"などのキーが含まれます。すべてのエントリにソースがあるとは限りません。 - author (
UserまたはOrganization) — API レスポンスの"type"フィールドに基づいて解析されたモデルの作成者です。 - pull_request (
int, 省略可能) — リーダーボードのエントリに関連付けられているプルリクエスト番号（該当する場合）。 - notes (
str, 任意) — リーダーボードのエントリに関連付けられたメモ（ある場合）。
Hub上のデータセットリーダーボードの単一エントリに関する情報を含みます。
リーダーボードは、特定のベンチマークデータセットでの評価スコアに基づいてモデルをランキングします。
このオブジェクトはget_dataset_leaderboard()によって返されます。特定のモデルのベンチマーク全体での評価結果を取得するには、model_info()にexpand=["evalResults"]を指定してModelInfo.eval_resultsを参照し、EvalResultEntryを参照してください。
EvalResultEntry
クラス huggingface_hub.EvalResultEntry
< source >( dataset_id: strtask_id: strvalue: typing.Anydataset_revision: str | None = Noneverify_token: str | None = Nonedate: str | None = Nonesource_url: str | None = Nonesource_name: str | None = Nonesource_user: str | None = Nonesource_org: str | None = Nonenotes: str | None = None )
パラメータ
- dataset_id (
str) — Hub からのベンチマークデータセット ID。例: “cais/hle”, “Idavidrein/gpqa”。 - task_id (
str) — ベンチマーク内のタスク識別子です。例: “gpqa_diamond”。 - value (
Any) — メトリックの値です。例: 20.90。 - dataset_revision (
str, 省略可) — ベンチマークデータの Git SHA です。 - verify_token (
str, 省略可) — 評価が監査可能かつ再現可能であることを証明するために使用できる署名です。 - date (
str, 省略可) — 評価が実行された日時 (ISO-8601 形式)。デフォルトでは git コミット時刻が使用されます。 - source_url (
str, 任意) — 評価ソースへのリンク（例: https://huggingface.co/spaces/SaylorTwift/smollm3-mmlu-pro）。source_name、source_user、またはsource_orgが指定されている場合は必須です。 - source_name (
str, 省略可) — ソースの表示名です。例: “Eval Logs”。 - source_user (
str, 任意) — 帰属表示用の HF ユーザー名です。例: “celinah”。 - source_org (
str, 任意) — 帰属表示用の HF 組織名。例: “cais”。 - notes (
str, optional) — Details about the evaluation setup. Example: “tools”, “no-tools”, “chain-of-thought”.
.eval_results/*.yaml形式の評価結果エントリ。
モデルリポジトリに保存され、モデルページおよびベンチマークデータセットのリーダーボードに自動的に表示される評価スコアを表します。
README.mdのレガシーなmodel-index形式には、代わりにEvalResultを使用してください。
詳細については、https://huggingface.co/docs/hub/eval-resultsを参照してください。
例:
>>> from huggingface_hub import EvalResultEntry
>>> # Minimal example with required fields only
>>> result = EvalResultEntry(
... dataset_id="Idavidrein/gpqa",
... task_id="gpqa_diamond",
... value=0.412,
... )
>>> # Full example with all fields
>>> result = EvalResultEntry(
... dataset_id="cais/hle",
... task_id="default",
... value=20.90,
... dataset_revision="5503434ddd753f426f4b38109466949a1217c2bb",
... verify_token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
... date="2025-01-15T10:30:00Z",
... source_url="https://huggingface.co/datasets/cais/hle",
... source_name="CAIS HLE",
... source_org="cais",
... notes="no-tools",
... )
SyncOperation
クラス huggingface_hub.SyncOperation
< source >( action: typing.Literal['upload', 'download', 'delete', 'skip']path: strsize: int | None = Nonereason: str = ''local_mtime: str | None = Noneremote_mtime: str | None = Nonebucket_file: huggingface_hub._buckets.BucketFile | None = None )
実行される同期操作を表します。
SyncPlan
クラス huggingface_hub.SyncPlan
< source >( source: strdest: strtimestamp: stroperations: list = <factory> )
完全な同期計画を表します。
CommitInfo
クラス huggingface_hub.CommitInfo
< source >( commit_url: str*args**kwargs )
パラメータ
- commit_url (
str) — コミットが見つかるURL。 - commit_message (
str) — 作成されたコミットのサマリー（最初の行）です。 - commit_description (
str) — 作成されたコミットの説明です。空でも構いません。 - oid (
str) — コミットハッシュID。例:"91c54ad1727ee830252e457677f467be0bfd8a57"。 - pr_url (
str, 任意) — 作成された PR の URL (存在する場合)。create_pr=Trueが渡された場合に設定されます。 - pr_revision (
str, 任意) — 作成された PR のリビジョン(存在する場合)。create_pr=Trueが渡された場合に設定されます。例:"refs/pr/1"。 - pr_num (
int, 任意) — 作成された PR ディスカッションの番号（存在する場合）。create_pr=Trueが渡された場合に設定されます。get_discussion_details() のdiscussion_numとして渡すことができます。例:1。 - repo_url (
RepoUrl) — repo_id や repo_type などの情報を含むコミットのリポジトリ URL。
新しく作成されたコミットに関する情報を含むデータ構造。
Hub上でコミットを作成するすべてのメソッドによって返されます: create_commit()、upload_file()、upload_folder()、delete_file()、delete_folder()。後方互換性のためにstrを継承していますが、str固有のメソッドの使用は非推奨です。
DatasetInfo
クラス huggingface_hub.DatasetInfo
< source >( **kwargs )
パラメータ
- id (
str) — データセットのID。 - author (
str) — データセットの作成者。 - card_data (
DatasetCardData、任意) — huggingface_hub.repocard_data.DatasetCardData オブジェクトとしての Dataset Card メタデータ。 - citation (
str, 任意) — データセットの引用情報です。 - created_at (
datetime, 任意) — Hub 上のリポジトリの作成日付です。なお、最小値は2022-03-02T23:29:04.000Zであり、作成日付の保存を開始した日付に対応しています。 - description (
str, 省略可) — データセットの説明。 - disabled (
bool, オプション) — リポジトリが無効化されているかどうか。 - downloads (
int) — 過去30日間のデータセットのダウンロード数。 - downloads_all_time (
int) — 作成以降のダウンロード総数。 - gated (
Literal["auto", "manual", False], 省略可) — リポジトリがゲート付きかどうか。 ゲート付きの場合、承認が手動か自動かを示します。 - last_modified (
datetime, 任意) — リポジトリへの最終コミットの日付。 - likes (
int) — データセットの「いいね」数。 - main_size (
int, 任意) — データセットのメインブランチのサイズ（バイト単位）。 - paperswithcode_id (
str, 省略可) — データセットの Papers with code ID。 - private (
bool) — リポジトリがプライベートかどうかを示します。 - resource_group (
dict, 任意) — データセットのリソースグループ情報。 - sha (
str) — この特定のリビジョンにおけるリポジトリのSHA。 - siblings (
list[RepoSibling]) — このデータセットを構成するhuggingface_hub.hf_api.RepoSiblingオブジェクトのリスト。 - tags (
list[str]) — データセットのタグのリストです。 - trending_score (
int, 任意) — データセットのトレンドスコア。 - used_storage (
int, 任意) — Hub 上のデータセットのサイズ（バイト単位）。
Hub上のデータセットに関する情報を含みます。このオブジェクトはdataset_info()およびlist_datasets()によって返されます。
このクラスのほとんどの属性はオプションです。これは、Hubが返すデータが実行されたクエリに依存するためです。 一般的に、クエリが具体的であればあるほど、より多くの情報が返されます。逆に、list_datasets()を使用してデータセットをリスト表示する場合、属性のサブセットのみが返されます。
DryRunFileInfo
クラス huggingface_hub.DryRunFileInfo
< source >( commit_hash: strfile_size: int | Nonefilename: strlocal_path: stris_cached: boolwill_download: bool )
パラメータ
- commit_hash (
str) — ファイルに関連する commit_hash です。 - file_size (
int, 任意) — ファイルサイズが既知の場合の値。LFSファイルの場合、ポインタではなく実際のLFSファイルのサイズが含まれます。 - filename (
str) — リポジトリ内のファイル名。 - is_cached (
bool) — ファイルがローカルにキャッシュ済みかどうかを示します。 - will_download (
bool) —hf_hub_downloadがdry_run=Falseで呼び出された場合、ファイルがダウンロードされるかどうかを示します。 実際には、ファイルがキャッシュされていない場合、またはforce_download=Trueの場合、will_download はTrueになります。
ファイルのダウンロードのドライランを実行した際に返される情報。
dry_run=Trueの場合、hf_hub_download()によって返されます。
DuplicatedRepoUrl
クラス huggingface_hub.DuplicatedRepoUrl
< source >( url: Anyendpoint: str | None = None )
duplicate_repo() が返す RepoUrl。
GitRefInfo
クラス huggingface_hub.GitRefInfo
< source >( name: strref: strtarget_commit: str )
Hub上のリポジトリのgit参照に関する情報を含みます。
GitCommitInfo
クラス huggingface_hub.GitCommitInfo
< source >( commit_id: strauthors: list[str]created_at: datetimetitle: strmessage: strformatted_title: str | Noneformatted_message: str | None )
パラメータ
- commit_id (
str) — コミットの OID (例:"e7da7f221d5bf496a48136c0cd264e630fe9fcc8") - authors (
list[str]) — コミットの著者名のリストです。 - created_at (
datetime) — コミットが作成された日時。 - title (
str) — コミットのタイトルです。これは著者が入力する自由記述の値です。 - message (
str) — コミットの説明です。これは著者が入力する自由記述の値です。 - formatted_title (
str) — HTML形式で整形されたコミットのタイトル。formatted=Trueが設定されている場合のみ返されます。 - formatted_message (
str) — HTML形式で整形されたコミットの説明。formatted=Trueが設定されている場合のみ返されます。
Hub上のリポジトリのgitコミットに関する情報を含みます。詳細については、list_repo_commits()を参照してください。
GitRefs
クラス huggingface_hub.GitRefs
< source >( branches: list[GitRefInfo]converts: list[GitRefInfo]tags: list[GitRefInfo]pull_requests: list[GitRefInfo] | None = None )
パラメータ
- branches (
list[GitRefInfo]) — リポジトリ上のブランチに関する情報が含まれる GitRefInfo のリスト。 - converts (
list[GitRefInfo]) — リポジトリ上の“convert”リファレンスに関する情報が含まれるGitRefInfoのリストです。 Convertsは、Datasetリポジトリにおいて前処理済みデータをプッシュするために（内部的に）使用されるリファレンスです。 - tags (
list[GitRefInfo]) — リポジトリのタグに関する情報が含まれるGitRefInfoのリスト。 - pull_requests (
list[GitRefInfo]、省略可) — リポジトリのプルリクエストに関する情報が含まれるGitRefInfoのリストです。include_prs=Trueが設定されている場合のみ返されます。
Hub上のリポジトリのすべてのgit参照に関する情報を含みます。
オブジェクトは、list_repo_refs()によって返されます。
InferenceProviderMapping
KernelInfo
クラス huggingface_hub.KernelInfo
< source >( **kwargs )
パラメータ
- id (
str) — カーネルリポジトリのID。 - author (
str, 任意) — カーネルリポジトリの作成者。 - downloads (
int, 任意) — 過去30日間のカーネルリポジトリのダウンロード数。 - gated (
Literal["auto", "manual", False], 省略可) — リポジトリがゲート付きかどうか。ゲート付きの場合、承認が手動か自動かを指定します。 - last_modified (
datetime, 任意) — リポジトリへの最終コミットの日付。 - likes (
int, 省略可) — カーネルリポジトリの「いいね」数。 - private (
bool, 省略可能) — リポジトリがプライベートかどうかを示します。 - sha (
str, 任意) — この特定のリビジョンのリポジトリSHA。
Hub上のカーネルリポジトリに関する情報を含みます。このオブジェクトはkernel_info()によって返されます。
LFSFileInfo
クラス huggingface_hub.hf_api.LFSFileInfo
< source >( **kwargs )
Hub上のリポジトリにLFSとして保存されているファイルに関する情報を含みます。
リポジトリからLFSファイルをリスト表示し、恒久的に削除して空き領域を確保する文脈で使用されます。 詳細については、list_lfs_files()およびpermanently_delete_lfs_files()を参照してください。
Git LFS ファイルは、パフォーマンスを最適化するために、ファイルパスではなく SHA-256 オブジェクト ID で追跡されます。 このアプローチは必須です。1 つのオブジェクトが異なるコミット間で複数のパスから参照され得るため、これらの関連性を検索して解決することは現実的ではないからです。各 SHA にどのファイル名が関連付けられているかを確認する方法については、ドキュメントをご覧ください。
例:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> lfs_files = api.list_lfs_files("username/my-cool-repo")
# Filter files to delete based on a combination of `filename`, `pushed_at`, `ref` or `size`.
# e.g. select only LFS files in the "checkpoints" folder
>>> lfs_files_to_delete = (lfs_file for lfs_file in lfs_files if lfs_file.filename.startswith("checkpoints/"))
# Permanently delete LFS files
>>> api.permanently_delete_lfs_files("username/my-cool-repo", lfs_files_to_delete)ModelInfo
クラス huggingface_hub.ModelInfo
< source >( **kwargs )
パラメータ
- id (
str) — モデルのID。 - author (
str, 省略可) — モデルの作成者。 - base_models (
list[str], 任意) — このモデルが派生したベースモデルのリスト。 - card_data (
ModelCardData、任意) — huggingface_hub.repocard_data.ModelCardData オブジェクトとしての Model Card Metadata。 - children_model_count (
int, 任意) — このモデルから派生した子モデルの数。 - config (
dict、任意) — モデルの設定です。 - created_at (
datetime, 任意) — Hub 上のリポジトリの作成日付です。なお、最小値は2022-03-02T23:29:04.000Zであり、作成日付の保存を開始した日付に対応しています。 - disabled (
bool, オプション) — リポジトリが無効化されているかどうか。 - downloads (
int) — 過去30日間のモデルのダウンロード数。 - downloads_all_time (
int) — モデルの作成以降の累計ダウンロード数。 - eval_results (
list[EvalResultEntry], 任意) — モデルの評価結果。 - gated (
Literal["auto", "manual", False], 省略可) — リポジトリがゲート付きかどうか。 ゲート付きの場合、承認が手動か自動かを示します。 - gguf (
dict, 任意) — モデルのGGUF情報。 - inference (
Literal["warm"], 省略可) — Inference Providers におけるモデルのステータス。少なくとも 1 つのプロバイダーによってサーブされている場合、Warm となります。 - inference_provider_mapping (
list[InferenceProviderMapping]、省略可) — ユーザーのプロバイダーの順序に従って並べられたInferenceProviderMappingのリストです。 - last_modified (
datetime, 任意) — リポジトリへの最終コミットの日付。 - library_name (
str, 省略可) — モデルに関連付けられたライブラリ。 - likes (
int) — モデルの「いいね」数。 - mask_token (
str, 省略可) — モデルで使用されるマスクトークン。 - model_index (
dict, 任意) — 評価用のモデルインデックス。 - pipeline_tag (
str, 省略可) — モデルに関連付けられたパイプラインタグ。 - private (
bool) — リポジトリがプライベートかどうかを示します。 - resource_group (
dict, 任意) — モデルのリソースグループ情報。 - safetensors (
SafeTensorsInfo, 任意) — モデルのsafetensors情報。 - security_repo_status (
dict, 任意) — モデルのセキュリティスキャンのステータス。 - sha (
str, 任意) — この特定のリビジョンのリポジトリSHA。 - siblings (
list[RepoSibling]) — モデルを構成するhuggingface_hub.hf_api.RepoSiblingオブジェクトのリスト。 - spaces (
list[str]、任意) — このモデルを使用しているスペースのリスト。 - tags (
list[str]) — モデルのタグのリストです。card_data.tagsとは異なり、Hub によって計算される追加のタグ（サポートされているライブラリ、モデルの arXiv など）が含まれます。 - transformers_info (
TransformersInfo、任意) — モデルに関連付けられた Transformers 固有の情報（auto クラス、プロセッサーなど）。 - trending_score (
int, 任意) — モデルのトレンドスコア。 - used_storage (
int, 任意) — Hub 上のモデルのサイズ（バイト単位）。 - widget_data (
Any, 省略可) — モデルに関連付けられたウィジェットデータ。
Hub上のモデルに関する情報を含みます。このオブジェクトはmodel_info()およびlist_models()によって返されます。
このクラスのほとんどの属性はオプションです。これは、Hubが返すデータは発行されたクエリに依存するためです。 一般的に、クエリが具体的であればあるほど、より多くの情報が返されます。逆に、list_models()を使用してモデルをリスト表示する場合、属性のサブセットのみが返されます。
RepoSibling
クラス huggingface_hub.hf_api.RepoSibling
< source >( rfilename: strsize: int | None = Noneblob_id: str | None = Nonelfs: BlobLfsInfo | None = None )
パラメータ
- rfilename (str) — リポジトリのルートからの相対パスのファイル名。
- size (
int, 任意) — ファイルのサイズ（バイト単位）です。repo_info() のfiles_metadata引数がTrueに設定されている場合に定義されます。それ以外の場合はNoneになります。 - blob_id (
str, 任意) — ファイルの git OID です。この属性は、repo_info() のfiles_metadata引数がTrueに設定されている場合に定義されます。それ以外の場合はNoneになります。 - lfs (
BlobLfsInfo、任意) — ファイルの LFS メタデータです。この属性は、repo_info() のfiles_metadata引数がTrueに設定されており、かつファイルが Git LFS で保存されている場合に定義されます。それ以外の場合はNoneになります。
Hub上のリポジトリ内のリポジトリファイルに関する基本的な情報を含みます。
このクラスの属性は、
rfilenameを除いてすべてオプションです。これは、Hub上のリポジトリをリスト表示する際（list_models()、list_datasets()またはlist_spaces()を使用する場合）には、ファイル名のみが返されるためです。ファイルサイズ、blob ID、LFSの詳細などの追加情報が必要な場合は、バックエンドサーバーにこれらの情報を取得させる際に制約が増えるため、リポジトリを1つずつ特定して明示的にリクエストする必要があります（model_info()、dataset_info()またはspace_info()を使用）。
RepoFile
クラス huggingface_hub.RepoFile
< source >( **kwargs )
パラメータ
- path (str) — リポジトリのルートからの相対パス。
- size (
int) — ファイルのサイズ（バイト単位）。 - blob_id (
str) — ファイルの git OID です。 - lfs (
BlobLfsInfo、任意) — ファイルのLFSメタデータ。 - xet_hash (
str, 任意) — ファイルの Xet ハッシュ。 - last_commit (
LastCommitInfo、任意) — ファイルの最終コミットのメタデータです。list_repo_tree() と get_paths_info() がexpand=Trueを指定して呼び出された場合のみ定義されます。 - security (
BlobSecurityInfo、省略可) — ファイルのセキュリティスキャンに関するメタデータです。list_repo_tree() および get_paths_info() をexpand=Trueで呼び出した場合のみ定義されます。
Hub上のファイルに関する情報を含みます。
RepoUrl
クラス huggingface_hub.RepoUrl
< source >( url: Anyendpoint: str | None = None )
パラメータ
- url (
Any) — リポジトリの URL の文字列値。 - endpoint (
str, 省略可) — Hub のエンドポイントです。デフォルト値は https://huggingface.co です。
例外
HfUriError
HfUriError— URLを解析できない場合（例：正規化された単一セグメントのリポジトリ、または不明なrepo_type）。
Hub上のリポジトリURLを記述するstrのサブクラス。
RepoUrl は HfApi.create_repo によって返されます。後方互換性のために str を継承しています。初期化時に URL が解析され、プロパティが設定されます。
- エンドポイント (
str) strの名前空間- repo_name (
str) - repo_id (
str) - repo_type (
Literal["model", "dataset", "space"]) - URL (
str)
例:
>>> RepoUrl('https://huggingface.co/openai-community/gpt2')
RepoUrl('https://huggingface.co/openai-community/gpt2', endpoint='https://huggingface.co', repo_type='model', repo_id='openai-community/gpt2')
>>> RepoUrl('https://huggingface.co/proxy/hub-ci.huggingface.co/datasets/dummy_user/dummy_dataset', endpoint='https://huggingface.co/proxy/hub-ci.huggingface.co')
RepoUrl('https://huggingface.co/proxy/hub-ci.huggingface.co/datasets/dummy_user/dummy_dataset', endpoint='https://huggingface.co/proxy/hub-ci.huggingface.co', repo_type='dataset', repo_id='dummy_user/dummy_dataset')
>>> RepoUrl('hf://datasets/my-user/my-dataset')
RepoUrl('hf://datasets/my-user/my-dataset', endpoint='https://huggingface.co', repo_type='dataset', repo_id='user/dataset')
>>> HfApi.create_repo("dummy_model")
RepoUrl('https://huggingface.co/Wauplin/dummy_model', endpoint='https://huggingface.co', repo_type='model', repo_id='Wauplin/dummy_model')SafetensorsRepoMetadata
クラス huggingface_hub.utils.SafetensorsRepoMetadata
< source >( metadata: dict | Nonesharded: boolweight_map: dictfiles_metadata: dict )
パラメータ
- metadata (
dict, 任意) — 存在する場合、‘model.safetensors.index.json’ファイルに含まれるメタデータです。シャード化されたモデルの場合のみ設定されます。 - sharded (
bool) — リポジトリにシャード化されたモデルが含まれているかどうかを示します。 - weight_map (
dict[str, str]) — すべての重みのマップです。キーはテンソル名、値はテンソルを含むファイル名です。 - files_metadata (
dict[str, SafetensorsFileMetadata]) — すべてのファイルのメタデータのマッピングです。キーはファイル名、値は対応するファイルのメタデータであり、SafetensorsFileMetadataオブジェクトとして表されます。 - parameter_count (
dict[str, int]) — データ型ごとのパラメータ数のマップです。キーはデータ型、値はそのデータ型のパラメータ数です。
Safetensorsリポジトリのメタデータ。
リポジトリのルートに、model.safetensors ウェイトファイル（非共有モデル）または model.safetensors.index.json インデックスファイル（シャーディングされたモデル）のいずれかが含まれている場合、そのリポジトリは Safetensors リポジトリとみなされます。
このクラスは、get_safetensors_metadata()によって返されます。
safetensors形式の詳細については、https://huggingface.co/docs/safetensors/index#formatを参照してください。
SafetensorsFileMetadata
クラス huggingface_hub.utils.SafetensorsFileMetadata
< source >( metadata: dicttensors: dict )
Hub上でホストされているSafetensorsファイルのメタデータ。
このクラスは、parse_safetensors_file_metadata()によって返されます。
safetensors形式の詳細については、https://huggingface.co/docs/safetensors/index#formatを参照してください。
SpaceInfo
クラス huggingface_hub.SpaceInfo
< source >( **kwargs )
パラメータ
- id (
str) — Space の ID。 - author (
str, 任意) — Space の作成者。 - card_data (
SpaceCardData、任意) — Space Card のメタデータを huggingface_hub.repocard_data.SpaceCardData オブジェクトとして指定します。 - created_at (
datetime, 任意) — Hub 上のリポジトリの作成日付です。なお、最小値は2022-03-02T23:29:04.000Zであり、作成日付の保存を開始した日付に対応しています。 - datasets (
list[str], 任意) — Space で使用されるデータセットのリスト。 - disabled (
bool, 任意) — Space が無効化されているかどうか。 - gated (
Literal["auto", "manual", False], 省略可) — リポジトリがゲート付きかどうか。 ゲート付きの場合、承認が手動か自動かを示します。 - host (
str, 省略可) — Space のホスト URL。 - last_modified (
datetime, 任意) — リポジトリへの最終コミットの日付。 - likes (
int) — Spaceの「いいね」数。 - models (
list[str], 任意) — Space で使用されるモデルのリスト。 - private (
bool) — リポジトリがプライベートかどうかを示します。 - region (
Literal["us", "eu"], 省略可) — Space が保存されているクラウドリージョン。 - resource_group (
dict, 任意) — Spaceのリソースグループ情報。 - runtime (
SpaceRuntime、任意) — Space のランタイム情報を huggingface_hub.hf_api.SpaceRuntime オブジェクトとして表します。 - sdk (
str, 省略可) — Spaceで使用されるSDK。 - sha (
str, 任意) — この特定のリビジョンのリポジトリSHA。 - siblings (
list[RepoSibling]) — Space を構成する huggingface_hub.hf_api.RepoSibling オブジェクトのリスト。 - subdomain (
str, 省略可) — Space のサブドメイン。 - tags (
list[str]) — Spaceのタグのリストです。 - trending_score (
int, 任意) — Space のトレンドスコアです。 - used_storage (
int, 任意) — Hub上のSpaceのサイズ（バイト単位）。 - visibility (
Literal["public", "private", "protected"], 省略可) — Space の公開設定です。privateとは異なり、private と protected の Space を区別できます。Space のみ利用可能で、モデル、データセット、バケットには適用されません。
Hub上のSpaceに関する情報を含みます。このオブジェクトはspace_info()およびlist_spaces()によって返されます。
このクラスのほとんどの属性はオプションです。これは、Hubから返されるデータが実行されたクエリに依存するためです。 一般的に、クエリが具体的であればあるほど、より多くの情報が返されます。逆に、list_spaces()を使用してスペースの一覧を取得する場合は、属性のサブセットのみが返されます。
SpaceSearchResult
クラス huggingface_hub.SpaceSearchResult
< source >( data: dict )
パラメータ
- id (
str) — Space の ID（例:"username/repo-name"）。 - author (
str) — Space の作成者。 - title (
str) — Space の表示タイトルです。 - emoji (
strまたはNone) — Space の絵文字アイコン。 - sdk (
strまたはNone) — Space で使用される SDK（例:"gradio"、"docker"、"static"）。 - likes (
int) — いいねの数。 - private (
bool) — Spaceがプライベートかどうかを示します。 - tags (
list[str]またはNone) — タグのリスト。 - runtime (SpaceRuntime または
None) — ランタイム情報（ステージ、ハードウェアなど）。 - ai_short_description (
strまたはNone) — AIによって生成された短い説明です。 - ai_category (
strまたはNone) — AI によって生成されたカテゴリ（例:"Image Generation"）。 - semantic_relevancy_score (
floatまたはNone) — 検索クエリに対するセマンティック関連性スコア(0〜1)。 - trending_score (
intまたはNone) — トレンドスコア。
Spacesセマンティック検索APIからの単一の結果。
HfApi.search_spaces()によって返されます。
TensorInfo
クラス huggingface_hub.utils.TensorInfo
< source >( dtype: typing.Literal['F64', 'F32', 'F16', 'BF16', 'I64', 'I32', 'I16', 'I8', 'U8', 'U3', 'BOOL']shape: listdata_offsets: tuple )
テンソルに関する情報。
safetensors形式の詳細については、https://huggingface.co/docs/safetensors/index#formatを参照してください。
ユーザー
クラス huggingface_hub.User
< source >( **kwargs )
パラメータ
- username (
str) — Hub 上のユーザー名(一意)。 - fullname (
str) — ユーザーの氏名。 - avatar_url (
str) — ユーザーのアバターのURL。 - details (
str, 省略可) — ユーザーの詳細情報。 - is_following (
bool, 省略可) — 認証済みユーザーがこのユーザーをフォローしているかどうかを示します。 - is_pro (
bool、省略可) — ユーザーがプロユーザーかどうかを示します。 - num_models (
int, 任意) — ユーザーが作成するモデルの数。 - num_datasets (
int, 任意) — ユーザーが作成するデータセットの数。 - num_spaces (
int, 任意) — ユーザーが作成したスペースの数。 - num_discussions (
int, 任意) — ユーザーが開始したディスカッションの数。 - num_papers (
int, 省略可) — ユーザーが著者として関与した論文の数。 - num_upvotes (
int, 省略可) — ユーザーが受け取った高評価の数。 - num_likes (
int, 任意) — ユーザーが付けた「いいね」の数。 - num_following (
int, 任意) — このユーザーがフォローしているユーザー数。 - num_followers (
int, 省略可) — このユーザーをフォローしているユーザー数。 - orgs (
Organizationのリスト) — ユーザーが所属している組織のリスト。
Hub上のユーザーに関する情報を含みます。
UserLikes
クラス huggingface_hub.UserLikes
< source >( user: strtotal: intdatasets: list[str]kernels: list[str]models: list[str]spaces: list[str] )
Hub におけるユーザーの「いいね」に関する情報を含みます。
WebhookInfo
クラス huggingface_hub.WebhookInfo
< source >( id: strurl: str | Nonejob: JobSpec | Nonewatched: list[WebhookWatchedItem]domains: list[constants.WEBHOOK_DOMAIN_T]secret: str | Nonedisabled: bool )
パラメータ
- id (
str) — WebhookのID。 - url (
str, 任意) — WebhookのURL。 - job (
JobSpec, 省略可) — トリガーする Job の仕様。 - watched (
list[WebhookWatchedItem]) — Webhook が監視しているアイテムのリストです。WebhookWatchedItemを参照してください。 - domains (
list[WEBHOOK_DOMAIN_T]) — Webhookが監視するドメインのリストです。["repo", "discussion"]のいずれかになります。 - secret (
str, 任意) — Webhookのシークレット。 - disabled (
bool) — Webhookが無効化されているかどうかを示します。
Webhookに関する情報を含むデータ構造。
urlまたはjobのいずれかが指定されていますが、両方が指定されているわけではありません。
WebhookWatchedItem
class huggingface_hub.WebhookWatchedItem
< source >( type: Literal['bucket', 'dataset', 'model', 'org', 'space', 'user']name: str )
Webhookによって監視されるアイテムに関する情報を含むデータ構造。
CommitOperation
CommitOperation()でサポートされている値は以下の通りです。
クラス huggingface_hub.CommitOperationAdd
< source >( path_in_repo: strpath_or_fileobj: str | pathlib.Path | bytes | typing.BinaryIO )
パラメータ
- path_in_repo (
str) — リポジトリ内の相対ファイルパス。例:"checkpoints/1fec34a/weights.bin" - path_or_fileobj (
str,Path,bytes, またはBinaryIO) — 次のいずれか:- アップロードするローカルファイルへのパス(
strまたはpathlib.Pathとして) - アップロードするファイルの内容を保持するバイトのバッファ(
bytes) io.BufferedIOBaseのサブクラスである「ファイルオブジェクト」で、通常はopen(path, "rb")を使用して取得します。seek()とtell()メソッドをサポートする必要があります。
- アップロードするローカルファイルへのパス(
例外
ValueError
ValueError—path_or_fileobjがstr、Path、bytes、io.BufferedIOBaseのいずれでもない場合。ValueError—path_or_fileobjがstrまたはPathであるが、既存のファイルへのパスではない場合。ValueError—path_or_fileobjがio.BufferedIOBaseであるが、seek()とtell()の両方をサポートしていない場合。
Hub上のリポジトリにファイルをアップロードするために必要な情報を保持するデータ構造。
as_file
< source >( with_tqdm: bool = False )
path_or_fileobjの背後にある基礎データを、ファイルのようなオブジェクトとして読み取れるようにするコンテキストマネージャーです。
例:
>>> operation = CommitOperationAdd(
... path_in_repo="remote/dir/weights.h5",
... path_or_fileobj="./local/weights.h5",
... )
CommitOperationAdd(path_in_repo='remote/dir/weights.h5', path_or_fileobj='./local/weights.h5')
>>> with operation.as_file() as file:
... content = file.read()
>>> with operation.as_file(with_tqdm=True) as file:
... while True:
... data = file.read(1024)
... if not data:
... break
config.json: 100%|█████████████████████████| 8.19k/8.19k [00:02<00:00, 3.72kB/s]
>>> with operation.as_file(with_tqdm=True) as file:
... httpx2.put(..., data=file)
config.json: 100%|█████████████████████████| 8.19k/8.19k [00:02<00:00, 3.72kB/s]クラス huggingface_hub.CommitOperationDelete
< source >( path_in_repo: stris_folder: typing.Union[bool, typing.Literal['auto']] = 'auto' )
パラメータ
- path_in_repo (
str) — リポジトリ内の相対ファイルパスです。ファイルの場合は"checkpoints/1fec34a/weights.bin"、フォルダの場合は"checkpoints/1fec34a/"のように指定します。 - is_folder (
boolまたはLiteral["auto"]、省略可) — Delete Operation がフォルダに適用されるかどうかを指定します。“auto” の場合、パスの末尾が ”/” で終わるかどうか（フォルダ）を調べることにより、パスの種類（ファイルまたはフォルダ）が自動的に推測されます。パスの種類を明示的に設定するには、is_folder=Trueまたはis_folder=Falseを設定できます。
Hub上のリポジトリからファイルまたはフォルダを削除するために必要な情報を保持するデータ構造
クラス huggingface_hub.CommitOperationCopy
< source >( src_path_in_repo: strpath_in_repo: strsrc_revision: str | None = Nonesrc_repo_id: str | None = Nonesrc_repo_type: str | None = None_src_oid: str | None = None_dest_oid: str | None = None_is_duplicated: bool = False )
パラメータ
- src_path_in_repo (
str) — コピー対象のファイルのリポジトリ内の相対ファイルパス。例:"checkpoints/1fec34a/weights.bin" - path_in_repo (
str) — リポジトリ内の相対ファイルパス。ファイルをコピーする先を指定します。例:"checkpoints/1fec34a/weights_copy.bin" - src_revision (
str, 省略可能) — コピーするファイルの git リビジョンです。有効な git リビジョンであれば何でも指定できます。 デフォルトでは、ターゲットのコミットリビジョンが使用されます。 - src_repo_id (
str, 省略可) — コピー元のソースリポジトリ（例:"username/source-model"）。 デフォルトでは、コピー先のリポジトリが使用されます（リポジトリ内コピー）。 - src_repo_type (
str, 省略可) — ソースリポジトリの種類 ("model"、"dataset"または"space")。src_repo_idが設定されている場合は必須です。
Hub上のリポジトリでファイルをコピーするために必要な情報を保持するデータ構造。
LFSファイルと通常のファイルの両方がサポートされています。LFSファイルはサーバー側でコピーされ、通常のファイルはコミットの一部としてダウンロードされ、再アップロードされます。
src_repo_id と src_repo_type を設定することで、リポジトリ間のコピーがサポートされています。リポジトリ間の LFS コピーの場合、コミットが作成される前に、LFS オブジェクトが宛先リポジトリに複製されます。これは create_commit() によって自動的に処理されます。なお、リポジトリ間のコピーは同じ ストレージリージョン 内でのみ動作し、リージョンをまたぐコピーはサポートされていません。
注: CommitOperationCopyとCommitOperationDeleteを組み合わせることで、Hub上のLFSファイルをリネームできます。
CommitScheduler
クラス huggingface_hub.CommitScheduler
< source >( repo_id: strfolder_path: str | pathlib.Pathevery: int | float = 5path_in_repo: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Noneprivate: bool | None = Nonetoken: str | None = Noneallow_patterns: list[str] | str | None = Noneignore_patterns: list[str] | str | None = Nonesquash_history: bool = Falsehf_api: typing.Optional[ForwardRef('HfApi')] = None )
パラメータ
- repo_id (
str) — コミット先リポジトリの ID。 - folder_path (
strまたはPath) — 定期的にアップロードするローカルフォルダへのパス。 - every (
intまたはfloat、任意) — 各コミット間の間隔（分）です。デフォルトは5分です。 - path_in_repo (
str, オプション) — リポジトリ内のディレクトリの相対パスです。例:"checkpoints/"。デフォルトでは、リポジトリのルートフォルダが使用されます。 - repo_type (
str, 省略可) — コミット先のリポジトリの種類です。デフォルトはmodelです。 - revision (
str, 省略可) — コミット先リポジトリのリビジョンです。デフォルトはmainです。 - private (
bool、省略可) — リポジトリを非公開にするかどうか。None（デフォルト）の場合、組織のデフォルトが非公開でない限り、リポジトリは公開になります。リポジトリが既に存在する場合、この値は無視されます。 - token (
str, 省略可能) — リポジトリにコミットするために使用するトークン。デフォルトでは、マシンに保存されているトークンが使用されます。 - allow_patterns (
list[str]またはstr、省略可) — 指定された場合、少なくとも1つのパターンに一致するファイルのみがアップロードされます。 - ignore_patterns (
list[str]またはstr、省略可) — 指定された場合、これらのパターンのいずれかに一致するファイルはアップロードされません。 - squash_history (
bool, 任意) — 各コミット後にリポジトリの履歴をスクワッシュするかどうか。デフォルトはFalseです。コミットをスクワッシュすることは、リポジトリが大きくなりすぎた場合にパフォーマンスの低下を避けるのに役立ちます。 - hf_api (
HfApi、任意) — Hub にコミットするために使用する HfApi クライアントです。カスタム設定（ユーザーエージェント、トークンなど）を指定して設定できます。
ローカルフォルダを一定間隔（例：5分ごとに）でHubにアップロードするためのスケジューラー。
スケジューラーの推奨される使用法は、コンテキストマネージャーとして使用することです。これにより、スクリプトが終了した際にスケジューラーが適切に停止され、最後のコミットがトリガーされることが保証されます。スケジューラーは、stop メソッドによって手動で停止することもできます。使用方法の詳細については、アップロードガイドを参照してください。
例:
>>> from pathlib import Path
>>> from huggingface_hub import CommitScheduler
# Scheduler uploads every 10 minutes
>>> csv_path = Path("watched_folder/data.csv")
>>> CommitScheduler(repo_id="test_scheduler", repo_type="dataset", folder_path=csv_path.parent, every=10)
>>> with csv_path.open("a") as f:
... f.write("first line")
# Some time later (...)
>>> with csv_path.open("a") as f:
... f.write("second line")コンテキストマネージャを使用した例:
>>> from pathlib import Path
>>> from huggingface_hub import CommitScheduler
>>> with CommitScheduler(repo_id="test_scheduler", repo_type="dataset", folder_path="watched_folder", every=10) as scheduler:
... csv_path = Path("watched_folder/data.csv")
... with csv_path.open("a") as f:
... f.write("first line")
... (...)
... with csv_path.open("a") as f:
... f.write("second line")
# Scheduler is now stopped and last commit have been triggeredフォルダを Hub にプッシュし、コミット情報を返します。
このメソッドは直接呼び出すことを意図していません。スケジューラによってバックグラウンドで実行され、並行コミットを避けるためのキュー機構が尊重されます。メソッドを直接呼び出すと、並行性の問題が発生する可能性があります。
push_to_hubのデフォルトの動作は、フォルダをappend-only（追記専用）であると仮定することです。フォルダ内のすべてのファイルを列挙し、変更されたファイルのみをアップロードします。変更が見つからない場合、何もコミットせずにメソッドが返ります。この動作を変更したい場合は、CommitSchedulerを継承してこのメソッドをオーバーライドできます。例えば、コミットする前にデータを1つのファイルに圧縮してまとめる場合に便利です。詳細と例については、統合ガイドを参照してください。
push_to_hubをトリガーし、futureを返します。
このメソッドはevery分ごとに自動的に呼び出されます。次のスケジュールされたコミットを待たずに、すぐにコミットをトリガーするために、手動で呼び出すこともできます。