API Filesystem

Kelas HfFileSystem menyediakan antarmuka file yang pythonic ke Hugging Face Hub berdasarkan fsspec.

HfFileSystem

HfFileSystem didasarkan pada fsspec, sehingga kompatibel dengan sebagian besar API yang ditawarkannya. Untuk detail lebih lanjut, lihat panduan kami dan API Reference fsspec.

kelas huggingface_hub.HfFileSystem

< source >

( *args**kwargs )

Parameter

endpoint (str, opsional) — Endpoint dari Hub. Defaultnya adalah https://huggingface.co.
token (bool atau str, opsional) — Token akses pengguna yang valid (string). Secara default menggunakan token yang disimpan secara lokal, yang merupakan metode autentikasi yang direkomendasikan (lihat https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Untuk menonaktifkan autentikasi, berikan False.
block_size (int, opsional) — Ukuran blok untuk membaca dan menulis file.
expand_info (bool, opsional) — Apakah akan memperluas informasi file.
max_workers (int, opsional) — Jumlah maksimum permintaan konkuren yang digunakan untuk mendaftar direktori besar secara paralel (lihat find()). Bawaan adalah 16. Atur ke 1 untuk menonaktifkan pendaftaran paralel.
live_follow (bool, opsional) — Apakah akan mengikuti perubahan file di bucket saat terjadi di Hub, sehingga daftar cache tetap terkini tanpa perlu pemanggilan manual HfFileSystem.invalidate_cache(). Ketika diaktifkan, melisting sebuah bucket akan membuka koneksi latar belakang ke feed event Hub untuk bucket tersebut. Tidak berdampak pada repositori model, dataset, dan space (Hub tidak menyediakan feed perubahan untuk jenis repositori tersebut).
**storage_options (dict, opsional) — Opsi tambahan untuk sistem file. Lihat dokumentasi fsspec.

Akses repositori Hugging Face Hub jarak jauh seolah-olah itu adalah sistem file lokal.

HfFileSystem menyediakan kompatibilitas fsspec, yang berguna untuk pustaka yang membutuhkannya (misalnya, membaca dataset Hugging Face langsung dengan pandas). Namun, hal ini memperkenalkan overhead tambahan karena lapisan kompatibilitas tersebut. Untuk kinerja dan keandalan yang lebih baik, disarankan untuk menggunakan metode HfApi ketika memungkinkan.

Sistem file mendukung jalur untuk protokol hf://, yang mengikuti skema URL berikut:

Repositori Models, Datasets, dan Spaces:

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

Buckets (penyimpanan generik):

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

Catatan: saat menggunakan HfFileSystem secara langsung, meneruskan prefiks protokol hf:// bersifat opsional dalam path.

Penggunaan:

>>> 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)

Tentukan token untuk autentikasi:

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

cp_file

< source >

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

Parameter

path1 (str) — Path sumber untuk disalin.
path2 (str) — Jalur tujuan untuk menyalin.
revision (str, opsional) — Revisi git untuk disalin.

Salin file di dalam atau antar repositori, atau ke dalam bucket.

Catatan: Jika memungkinkan, gunakan HfApi.upload_file() untuk kinerja yang lebih baik.

ada

< source >

( path**kwargs ) → bool

Parameter

path (str) — Path untuk diperiksa.

Mengembalikan

bool

True jika file ada, False jika tidak.

Periksa apakah file ada.

Untuk detail lebih lanjut, lihat dokumentasi fsspec.

Catatan: Jika memungkinkan, gunakan HfApi.file_exists() untuk kinerja yang lebih baik.

find

< source >

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

Parameter

path (str) — Path root untuk mendaftar file.
maxdepth (int, opsional) — Kedalaman maksimum untuk masuk ke subdirektori.
withdirs (bool, opsional) — Sertakan jalur direktori dalam output. Defaultnya False.
detail (bool, opsional) — Jika True, mengembalikan dict yang memetakan path ke informasi file. Defaultnya False.
refresh (bool, opsional) — Jika True, lewati cache dan ambil data terbaru. Defaultnya False.
revision (str, opsional) — Revisi git yang akan diurutkan.

Mengembalikan

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

Daftar path atau dict informasi file.

Daftarkan semua file di bawah path.

Untuk detail lebih lanjut, lihat dokumentasi fsspec.

Repositori besar diurutkan per direktori, secara paralel, untuk menghindari paginasi berbasis kursor dari endpoint tree Hub. Sesuaikan ini dengan argumen max_workers dari HfFileSystem.

get_file

< source >

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

Parameter

rpath (str) — Jarak jauh untuk diunduh.
lpath (str, opsional) — Jalur lokal untuk mengunduh. Dapat diabaikan jika outfile disediakan.
callback (Callback, opsional) — opsional untuk melacak progres unduhan. Secara default tidak ada callback.
outfile (IO, opsional) — Objek seperti file opsional untuk ditulis. Jika disediakan, lpath diabaikan.

Salin satu file jarak jauh ke lokal.

Catatan: Jika memungkinkan, gunakan HfApi.hf_hub_download() atau HfApi.download_bucket_files untuk kinerja yang lebih baik.

glob

< source >

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

Parameter

path (str) — Pola jalur yang akan dicocokkan.
maxdepth (int, opsional) — Kedalaman maksimum untuk masuk ke dalam direktori. Secara default, tidak ada batas.

Mengembalikan

list[str]

Daftar path yang cocok dengan pola.

Cari file dengan glob-matching.

Untuk detail lebih lanjut, lihat dokumentasi fsspec.

info

< source >

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

Parameter

path (str) — Path untuk mendapatkan info.
refresh (bool, opsional) — Jika True, lewati cache dan ambil data terbaru. Defaultnya False.
revision (str, opsional) — Revisi git untuk diambil informasinya.

Mengembalikan

dict[str, Any]

Dictionary yang berisi informasi file (tipe, ukuran, info commit, dll.).

Dapatkan informasi tentang file atau direktori.

Untuk detail lebih lanjut, lihat dokumentasi fsspec.

Catatan: Jika memungkinkan, gunakan HfApi.get_paths_info() atau HfApi.repo_info() untuk kinerja yang lebih baik (atau HfApi.get_bucket_paths_info() atau HfApi.bucket_info() untuk bucket)

invalidate_cache

< source >

( path: str | None = None )

Parameter

path (str, opsional) — Path untuk dibersihkan dari cache. Jika tidak diberikan, seluruh cache akan dibersihkan.

Bersihkan cache untuk path tertentu.

Untuk detail lebih lanjut, lihat dokumentasi fsspec.

isdir

< source >

( path ) → bool

Parameter

path (str) — Path untuk diperiksa.

Mengembalikan

bool

True jika path adalah direktori, False selain itu.

Periksa apakah sebuah path adalah direktori.

Untuk detail lebih lanjut, lihat dokumentasi fsspec.

isfile

< source >

( path ) → bool

Parameter

path (str) — Path untuk diperiksa.

Mengembalikan

bool

True jika path adalah file, False selain itu.

Periksa apakah sebuah path adalah file.

Untuk detail lebih lanjut, lihat dokumentasi fsspec.

ls

< source >

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

Parameter

path (str) — Path ke direktori.
detail (bool, opsional) — Jika True, mengembalikan daftar kamus yang berisi informasi file. Jika False, mengembalikan daftar path file. Defaultnya True.
refresh (bool, opsional) — Jika True, lewati cache dan ambil data terbaru. Defaultnya False.
revision (str, opsional) — Revisi git yang akan diurutkan.

Mengembalikan

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

Daftar jalur file (jika detail=False) atau daftar kamus informasi file (jika detail=True).

Daftarkan isi direktori.

Untuk detail lebih lanjut, lihat dokumentasi fsspec.

Catatan: Jika memungkinkan, gunakan HfApi.list_repo_tree() untuk kinerja yang lebih baik.

dimodifikasi

< source >

( path: str**kwargs ) → datetime

Parameter

path (str) — Path ke file.

Mengembalikan

datetime

Waktu modifikasi terakhir file.

Dapatkan waktu modifikasi terakhir dari sebuah file.

Untuk detail lebih lanjut, lihat dokumentasi fsspec.

resolve_path

< source >

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

Parameter

path (str) — Path yang akan dipecahkan.
revision (str, opsional) — Revisi repo yang akan di-resolve. Secara default menggunakan revisi yang ditentukan dalam path.

Mengembalikan

HfFileSystemResolvedPath

Informasi path yang telah dipecah, berisi repo_type, repo_id, revision, dan path_in_repo.

Membuang

ValueError atau NotImplementedError

ValueError — Jika path berisi informasi revisi yang saling bertentangan.
NotImplementedError — Jika mencoba membuat daftar repositori.

Menyelesaikan jalur file sistem Hugging Face menjadi komponen-komponennya.

rm

< source >

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

Parameter

path (str) — Path yang akan dihapus.
recursive (bool, opsional) — Jika True, hapus direktori dan semua isinya. Defaultnya False.
maxdepth (int, opsional) — Jumlah maksimum subdirektori yang akan dikunjungi saat penghapusan rekursif.
revision (str, opsional) — Revisi git yang akan dihapus.

Hapus file dari repositori.

Untuk detail lebih lanjut, lihat dokumentasi fsspec.

Catatan: Jika memungkinkan, gunakan HfApi.delete_file() untuk kinerja yang lebih baik.

url

< source >

( path: str ) → str

Parameter

path (str) — Path untuk mendapatkan URL.

Mengembalikan

str

URL HTTP untuk mengakses file atau direktori di Hub.

Dapatkan URL HTTP dari path yang diberikan.

berjalan

< source >

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

Parameter

path (str) — Path root untuk mendaftar file.

Mengembalikan

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

Iterator dari tuple (path, daftar nama direktori, daftar nama file).

Kembalikan semua file di bawah path yang diberikan.

Untuk detail lebih lanjut, lihat dokumentasi fsspec.

Update on GitHub

Hub Python Library

API Filesystem

HfFileSystem

kelas huggingface_hub.HfFileSystem

cp_file

ada

find

get_file

glob

info

invalidate_cache

isdir

isfile

ls

dimodifikasi

resolve_path

rm

url

berjalan