Hub Python Library documentation

ファイルシステムAPI

Hub Python Library

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

ファイルシステムAPI

HfFileSystem クラスは、fsspec をベースとした Hugging Face Hub 向けの Pythonic なファイルインターフェースを提供します。

HfFileSystem

HfFileSystem は fsspec をベースにしているため、fsspec が提供するほとんどの API と互換性があります。詳細については、こちらのガイドと fsspec の API リファレンスを参照してください。

クラス huggingface_hub.HfFileSystem

( *args**kwargs )

パラメータ

endpoint (str, 省略可) — Hub のエンドポイントです。デフォルト値は https://huggingface.co です。
token (bool または str、省略可能) — 有効なユーザーアクセストークン（文字列）です。デフォルトでは、ローカルに保存されたトークンが使用されます。これが認証の推奨方法です（https://huggingface.co/docs/huggingface_hub/quick-start#authenticationを参照）。認証を無効にするには、Falseを渡します。
block_size (int, 省略可) — ファイルの読み書きに使用するブロックサイズ。
expand_info (bool, 任意) — ファイルの情報を展開するかどうかを指定します。
max_workers (int, オプション) — 大規模なディレクトリを並列で列挙するために使用される同時リクエストの最大数（find()を参照）。デフォルト値は 16 です。並列列挙を無効にするには 1 に設定してください。
live_follow (bool, オプション) — Hub上でバケットのファイル変更が発生した際に追従するかどうかを指定します。これにより、HfFileSystem.invalidate_cache() を手動で呼び出すことなく、キャッシュされたリストを最新の状態に保つことができます。有効にすると、バケットのリストを取得する際に、そのバケットのHubイベントフィードへのバックグラウンド接続が開かれます。モデル、データセット、スペースのリポジトリには影響しません（これらの変更はHubから配信されないため）。
**storage_options (dict, 任意) — ファイルシステム用の追加オプション。fsspecのドキュメントを参照してください。

リモートのHugging Face Hubリポジトリをローカルファイルシステムのようにアクセスします。

HfFileSystem は fsspec 互換性を提供しており、それを必要とするライブラリ（pandas で Hugging Face のデータセットを直接読み込む場合など）に便利です。ただし、この互換性レイヤーにより追加のオーバーヘッドが発生します。パフォーマンスと信頼性を高めるため、可能な場合は HfApi のメソッドを使用することをお勧めします。

ファイルシステムはhf://プロトコルのパスをサポートしており、以下のURLスキームに従います:

Models、Datasets、Spacesリポジトリ:

hf://<repo-id>[@<revision>]/<path/in/repo>
hf://datasets/<repo-id>[@<revision>]/<path/in/repo>
hf://spaces/<repo-id>[@<revision>]/<path/in/repo>

バケット（汎用ストレージ）:

hf://buckets/<bucket-id>/<path/in/bucket>

注: HfFileSystemを直接使用する場合、パスにhf://プロトコルプレフィックスを付けることは任意です。

使用方法:

>>> from huggingface_hub import hffs

>>> # List files
>>> hffs.glob("my-username/my-model/*.bin")
['my-username/my-model/pytorch_model.bin']
>>> hffs.ls("datasets/my-username/my-dataset", detail=False)
['datasets/my-username/my-dataset/.gitattributes', 'datasets/my-username/my-dataset/README.md', 'datasets/my-username/my-dataset/data.json']

>>> # Read/write files
>>> with hffs.open("my-username/my-model/pytorch_model.bin") as f:
...     data = f.read()
>>> with hffs.open("my-username/my-model/pytorch_model.bin", "wb") as f:
...     f.write(data)

認証用のトークンを指定します:

>>> from huggingface_hub import HfFileSystem
>>> hffs = HfFileSystem(token=token)

cp_file

( path1: strpath2: strrevision: str | None = None**kwargs )

パラメータ

path1 (str) — コピー元のソースパス。
path2 (str) — コピー先のパス。
revision (str, 任意) — コピー元の git リビジョン。

リポジトリ内またはリポジトリ間でファイルをコピーするか、バケットにコピーします。

注: 可能な場合は、パフォーマンス向上のためHfApi.upload_file()を使用してください。

が存在します

( path**kwargs ) → bool

パラメータ

path (str) — 確認するパス。

戻り値

bool

ファイルが存在する場合はTrue、それ以外の場合はFalse。

ファイルが存在するかどうかを確認します。

詳細については、fsspecのドキュメントを参照してください。

注: 可能な場合は、パフォーマンス向上のためHfApi.file_exists()を使用してください。

find

( path: strmaxdepth: int | None = Nonewithdirs: bool = Falsedetail: bool = Falserefresh: bool = Falserevision: str | None = None**kwargs ) → Union[list[str], dict[str, dict[str, Any]]]

パラメータ

path (str) — ファイルの一覧を取得するルートパス。
maxdepth (int, 省略可) — サブディレクトリに降下する最大深度。
withdirs (bool, 任意) — 出力にディレクトリパスを含めるかどうか。デフォルトは False です。
detail (bool, 省略可) — True の場合、パスからファイル情報へのマッピングを含む dict を返します。デフォルトは False です。
refresh (bool, 省略可) — True の場合、キャッシュをバイパスして最新のデータを取得します。デフォルトは False です。
revision (str, 任意) — 一覧を取得する git リビジョン。

戻り値

Union[list[str], dict[str, dict[str, Any]]]

パスのリストまたはファイル情報の辞書。

パス以下のすべてのファイルをリスト表示します。

詳細については、fsspecのドキュメントを参照してください。

大規模なリポジトリは、Hubのtreeエンドポイントのカーソルベースのページネーションを回避するために、ディレクトリごとに並列で一覧表示されます。この設定は、HfFileSystemのmax_workers引数で調整できます。

get_file

( rpathlpath = Nonecallback = <fsspec.callbacks.NoOpCallback object at 0x7f9673955c90>outfile = None**kwargs )

パラメータ

rpath (str) — ダウンロード元のリモートパス。
lpath (str, 省略可) — ダウンロード先ローカルパス。outfile が指定されている場合は省略できます。
callback (Callback, 任意) — ダウンロードの進捗を追跡するための任意のコールバックです。デフォルトではコールバックなしです。
outfile (IO, 省略可能) — 書き出し先として使用する任意のファイルライクオブジェクト。指定された場合、lpath は無視されます。

単一のリモートファイルをローカルにコピーします。

注: 可能な場合は、パフォーマンス向上のためHfApi.hf_hub_download()またはHfApi.download_bucket_filesを使用してください。

glob

( path: strmaxdepth: int | None = None**kwargs ) → list[str]

パラメータ

path (str) — 一致させるパスパターン。
maxdepth (int, 任意) — ディレクトリに降下する最大深度。デフォルトでは制限なし。

戻り値

list[str]

パターンに一致するパスのリスト。

globマッチングでファイルを検索します。

詳細については、fsspecのドキュメントを参照してください。

情報

( path: strrefresh: bool = Falserevision: str | None = None**kwargs ) → dict[str, Any]

パラメータ

path (str) — 情報取得対象のパス。
refresh (bool, 省略可) — True の場合、キャッシュをバイパスして最新のデータを取得します。デフォルトは False です。
revision (str, 任意) — 情報取得に使用する git リビジョン。

戻り値

dict[str, Any]

ファイル情報（タイプ、サイズ、コミット情報など）を含む辞書。

ファイルまたはディレクトリに関する情報を取得します。

詳細については、fsspecのドキュメントを参照してください。

注: 可能な場合は、パフォーマンス向上のためHfApi.get_paths_info()またはHfApi.repo_info()を使用してください (バケットの場合はHfApi.get_bucket_paths_info()またはHfApi.bucket_info())

invalidate_cache

( path: str | None = None )

パラメータ

path (str, 任意) — キャッシュからクリアするパスです。指定しない場合、キャッシュ全体がクリアされます。

指定されたパスのキャッシュをクリアします。

詳細については、fsspecのドキュメントを参照してください。

isdir

( path ) → bool

パラメータ

path (str) — 確認するパス。

戻り値

bool

path がディレクトリの場合に True、それ以外の場合は False を返します。

パスがディレクトリかどうかを確認します。

詳細については、fsspecのドキュメントを参照してください。

isfile

( path ) → bool

パラメータ

path (str) — 確認するパス。

戻り値

bool

path がファイルの場合は True、それ以外の場合は False。

パスがファイルかどうかを確認します。

詳細については、fsspecのドキュメントを参照してください。

ls

( path: strdetail: bool = Truerefresh: bool = Falserevision: str | None = None**kwargs ) → list[Union[str, dict[str, Any]]]

パラメータ

path (str) — ディレクトリへのパス。
detail (bool, 省略可能) — True の場合、ファイル情報を含む辞書のリストを返します。False の場合、ファイルパスのリストを返します。デフォルトは True です。
refresh (bool, 省略可) — True の場合、キャッシュをバイパスして最新のデータを取得します。デフォルトは False です。
revision (str, 任意) — 一覧を取得する git リビジョン。

戻り値

list[Union[str, dict[str, Any]]]

ファイルパスのリスト（detail=Falseの場合）またはファイル情報の辞書のリスト（detail=Trueの場合）。

ディレクトリの内容をリスト表示します。

詳細については、fsspecのドキュメントを参照してください。

注: 可能な場合は、パフォーマンス向上のためHfApi.list_repo_tree()を使用してください。

修正済み

( path: str**kwargs ) → datetime

パラメータ

path (str) — ファイルへのパス。

戻り値

datetime

ファイルの最終変更時刻。

ファイルの最終変更時刻を取得します。

詳細については、fsspecのドキュメントを参照してください。

resolve_path

( path: strrevision: str | None = None ) → HfFileSystemResolvedPath

パラメータ

path (str) — 解決するパス。
revision (str, 省略可能) — 解決するリポジトリの revision です。デフォルトでは、パスで指定された revision になります。

戻り値

HfFileSystemResolvedPath

repo_type、repo_id、revision、path_in_repo を含む解決済みパス情報。

例外

ValueError または NotImplementedError

ValueError — path に矛盾するリビジョン情報が含まれている場合。
NotImplementedError — リポジトリのリスト取得を試みた場合。

Hugging Face のファイルシステムパスを各コンポーネントに分解します。

rm

( path: strrecursive: bool = Falsemaxdepth: int | None = Nonerevision: str | None = None**kwargs )

パラメータ

path (str) — 削除するパス。
recursive (bool, 省略可) — True の場合、ディレクトリとその中身すべてを削除します。デフォルトは False です。
maxdepth (int, 省略可) — 再帰的に削除する際に訪れるサブディレクトリの最大数。
revision (str, 任意) — 削除元の git リビジョン。

リポジトリからファイルを削除します。

詳細については、fsspecのドキュメントを参照してください。

注: 可能な場合は、パフォーマンス向上のためHfApi.delete_file()を使用してください。

url

( path: str ) → str

パラメータ

path (str) — URL を取得するパス。

戻り値

str

Hub上のファイルまたはディレクトリにアクセスするためのHTTP URL。

指定されたパスのHTTP URLを取得します。

walk

( path: str*args**kwargs ) → Iterator[tuple[str, list[str], list[str]]]

パラメータ

path (str) — ファイルの一覧を取得するルートパス。

戻り値

Iterator[tuple[str, list[str], list[str]]]

(path, ディレクトリ名のリスト, ファイル名のリスト)のタプルのイテレータ。

指定されたパス以下のすべてのファイルを返します。

詳細については、fsspecのドキュメントを参照してください。

Update on GitHub

←MCPクライアント HF URI→