# Interaksi dengan Hub melalui Filesystem API

Selain [HfApi](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi), pustaka `huggingface_hub` menyediakan [HfFileSystem](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_file_system#huggingface_hub.HfFileSystem), antarmuka file yang pythonic dan [fsspec-compatible](https://filesystem-spec.readthedocs.io/en/latest/) untuk Hugging Face Hub. [HfFileSystem](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_file_system#huggingface_hub.HfFileSystem) dibangun di atas [HfApi](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi) dan menawarkan operasi bergaya sistem file yang umum seperti `cp`, `mv`, `ls`, `du`, `glob`, `get_file`, dan `put_file`.

> [!WARNING]
> [HfFileSystem](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_file_system#huggingface_hub.HfFileSystem) menyediakan kompatibilitas fsspec, yang berguna untuk pustaka yang membutuhkannya (misalnya, membaca dataset dan bucket Hugging Face secara 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](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi) ketika memungkinkan.

## Penggunaan

```python
>>> from huggingface_hub import hffs

>>> # List all files in a dataset directory
>>> hffs.ls("datasets/my-username/my-dataset-repo/data", detail=False)
['datasets/my-username/my-dataset-repo/data/train.csv', 'datasets/my-username/my-dataset-repo/data/test.csv']

>>> # List all files in a bucket directory
>>> hffs.ls("buckets/my-username/my-bucket/experiment-data", detail=False)
['bucket/my-username/my-bucket/data/train-0000.parquet', 'bucket/my-username/my-bucket/data/train-0001.parquet', ...]

>>> # List all ".csv" files in a dataset repository
>>> hffs.glob("datasets/my-username/my-dataset-repo/**/*.csv")
['datasets/my-username/my-dataset-repo/data/train.csv', 'datasets/my-username/my-dataset-repo/data/test.csv']

>>> # Read a remote file
>>> with hffs.open("datasets/my-username/my-dataset-repo/data/train.csv", "r") as f:
...     train_data = f.readlines()

>>> # Read the content of a remote file as a string
>>> train_data = hffs.read_text("datasets/my-username/my-dataset-repo/data/train.csv", revision="dev")

>>> # Write a remote file
>>> with hffs.open("datasets/my-username/my-dataset-repo/data/validation.csv", "w") as f:
...     f.write("text,label")
...     f.write("Fantastic movie!,good")
```

Argumen opsional `revision` dapat diteruskan untuk menjalankan operasi dari commit tertentu, seperti cabang, nama tag, atau hash commit. Perhatikan bahwa `revision` tidak kompatibel dengan Buckets.

Berbeda dengan `open` bawaan Python, `open` dari `fsspec` secara default menggunakan mode biner, `"rb"`. Artinya, Anda harus secara eksplisit mengatur mode sebagai `"r"` untuk membaca dan `"w"` untuk menulis dalam mode teks. Menambahkan ke file (mode `"a"` dan `"ab"`) belum didukung.

## Mencantumkan repositori besar

Operasi yang mendaftar file secara rekursif, seperti `find` dan `glob`, perlu mengambil seluruh konten repositori. Hub mengembalikan entri-entri tersebut per halaman, dan sebuah halaman hanya dapat diminta setelah halaman sebelumnya diterima: mendaftar repositori yang berisi 800k file membutuhkan ~800 permintaan berurutan, dan karenanya sekitar 30 menit.

Untuk menghindari hal itu, [HfFileSystem](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_file_system#huggingface_hub.HfFileSystem) mendaftar repositori besar per direktori, secara paralel:

```python
>>> from huggingface_hub import hffs

>>> # Takes ~30s on a repository holding 800k files
>>> files = hffs.glob("datasets/allenai/objaverse/**/*.glb", maxdepth=3)
```

Jumlah permintaan konkuren dikendalikan oleh argumen `max_workers` dari [HfFileSystem](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_file_system#huggingface_hub.HfFileSystem). Nilainya secara default adalah 16 dan dapat diatur ke 1 untuk menonaktifkan daftar paralel. Perhatikan bahwa meneruskan `maxdepth` juga secara signifikan mempercepat proses daftar, karena Hub kemudian hanya mengembalikan entri yang benar-benar diminta.

## Jaga agar daftar tetap mutakhir

Direktori hanya terdaftar sekali dan isinya di-cache, sehingga direktori yang baru saja diubah oleh orang lain tidak akan diambil secara otomatis. [HfFileSystem.invalidate_cache()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_file_system#huggingface_hub.HfFileSystem.invalidate_cache) membuang daftar yang di-cache, baik untuk satu path (dan induknya) maupun di mana pun ketika dipanggil tanpa argumen:

```python
>>> hffs.ls("buckets/my-username/my-bucket/data", detail=False)  # listing is cached
>>> # ... another process uploads a file to the bucket ...
>>> hffs.invalidate_cache("buckets/my-username/my-bucket/data")
>>> hffs.ls("buckets/my-username/my-bucket/data", detail=False)  # listed again
['buckets/my-username/my-bucket/data/train.csv', 'buckets/my-username/my-bucket/data/new-file.csv']
```

Untuk bucket, `huggingface_hub` dapat melakukannya untuk Anda: Hub mengalirkan perubahan file bucket saat terjadi dan [HfFileSystem](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_file_system#huggingface_hub.HfFileSystem) membuang daftar yang terpengaruh oleh perubahan begitu perubahan tersebut tiba. Aktifkan dengan `live_follow=True`:

```python
>>> from huggingface_hub import HfFileSystem
>>> hffs = HfFileSystem(live_follow=True)
>>> hffs.ls("buckets/my-username/my-bucket/data", detail=False)  # starts following that bucket
>>> # ... another process uploads a file to the bucket ...
>>> hffs.ls("buckets/my-username/my-bucket/data", detail=False)  # refreshed as changes arrive
['buckets/my-username/my-bucket/data/train.csv', 'buckets/my-username/my-bucket/data/new-file.csv']
```

Hal ini juga dapat diteruskan melalui fsspec, dengan `fsspec.filesystem("hf", live_follow=True)` atau melalui argumen `storage_options` dari pustaka yang menerimanya (pandas, arrow, ...).

Beberapa hal yang perlu diketahui tentangnya:

- **Hanya bucket.** Repositori model, dataset, dan space adalah repositori git dan Hub tidak mengalirkan perubahan mereka: berikan `refresh=True` ke [HfFileSystem.ls()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_file_system#huggingface_hub.HfFileSystem.ls) (atau gunakan [HfApi.list_repo_tree()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.list_repo_tree)) untuk melihat commit baru.
- **Hanya daftar dan metadata yang dibawa yang diperbarui.** Membaca file selalu meminta kontennya dari Hub, sehingga pengikut langsung hanya memengaruhi apa yang dilaporkan oleh `ls`, `info`, `exists`, `glob`, ...
- Proses mengikuti dimulai begitu sebuah bucket terdaftar, dan satu koneksi latar belakang dipertahankan terbuka untuk setiap bucket yang diikuti, yang dibagikan oleh semua instans [HfFileSystem](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_file_system#huggingface_hub.HfFileSystem). Itulah mengapa opsi ini bersifat opt-in.

## Integrasi

[HfFileSystem](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_file_system#huggingface_hub.HfFileSystem) dapat digunakan dengan pustaka apa pun yang mengintegrasikan `fsspec`, asalkan URL mengikuti skema:

```
hf://[<repo_type_prefix>]<repo_id>[@<revision>]/<path/in/repo>
```

`repo_type_prefix` adalah `datasets/` untuk dataset, `spaces/` untuk Spaces, dan model tidak memerlukan awalan dalam URL.

Selain repositori, [HfFileSystem](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_file_system#huggingface_hub.HfFileSystem) juga mendukung Hugging Face Buckets yang merupakan penyimpanan objek serupa S3 (lihat [panduan ini](./buckets) untuk detail lebih lanjut):

```
hf://buckets/<bucket_id>/<path/in/bucket>
```

Beberapa integrasi menarik di mana [HfFileSystem](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_file_system#huggingface_hub.HfFileSystem) menyederhanakan interaksi dengan Hub tercantum di bawah ini:

* Membaca/menulis [Pandas](https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html#reading-writing-remote-files) DataFrame dari/ke repositori Hub:

  ```python
  >>> import pandas as pd

  >>> # Read a remote CSV file into a dataframe
  >>> df = pd.read_csv("hf://datasets/my-username/my-dataset-repo/train.csv")
  >>> df = pd.read_csv("hf://buckets/my-username/my-bucket/train.csv")

  >>> # Write a dataframe to a remote CSV file
  >>> df.to_csv("hf://datasets/my-username/my-dataset-repo/test.csv")
  >>> df.to_csv("hf://buckets/my-username/my-bucket/test.csv")
  ```

Alur kerja yang sama juga dapat digunakan untuk DataFrame [Dask](https://docs.dask.org/en/stable/how-to/connect-to-remote-data.html) dan [Polars](https://pola-rs.github.io/polars/py-polars/html/reference/io.html).

* Querying File Hub (remote) dengan [DuckDB](https://duckdb.org/docs/guides/python/filesystems):

  ```python
  >>> from huggingface_hub import HfFileSystem
  >>> import duckdb

  >>> fs = HfFileSystem()
  >>> duckdb.register_filesystem(fs)
  >>> # Query a remote file and get the result back as a dataframe
  >>> fs_query_file = "hf://datasets/my-username/my-dataset-repo/data_dir/data.parquet"
  >>> df = duckdb.query(f"SELECT * FROM '{fs_query_file}' LIMIT 10").df()
  ```

* Menggunakan Hub sebagai penyimpanan array dengan [Zarr](https://zarr.readthedocs.io/en/stable/tutorial.html#io-with-fsspec):

  ```python
  >>> import numpy as np
  >>> import zarr

  >>> embeddings = np.random.randn(50000, 1000).astype("float32")

  >>> # Write an array to a repo
  >>> root = zarr.open_group("hf://my-username/my-model-repo/array-store", mode="w")
  >>> foo = root.create_group("embeddings")
  >>> foobar = foo.zeros(name="experiment_0", shape=(50000, 1000), chunks=(10000, 1000), dtype="f4")
  >>> foobar[:] = embeddings

  >>> # Read an array from a repo
  >>> root = zarr.open_group("hf://my-username/my-model-repo/array-store", mode="r")
  >>> first_row = root["embeddings/experiment_0"][0]
  ```

## Autentikasi

Dalam banyak kasus, Anda harus masuk dengan akun Hugging Face untuk berinteraksi dengan Hub. Lihat bagian [Authentication](../quick-start#authentication) di dokumentasi untuk mempelajari lebih lanjut tentang metode autentikasi di Hub.

Anda juga dapat masuk secara programatik dengan meneruskan `token` Anda sebagai argumen ke [HfFileSystem](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_file_system#huggingface_hub.HfFileSystem):

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

Jika Anda masuk dengan cara ini, berhati-hatilah agar tidak tanpa sengaja membocorkan token saat membagikan kode sumber Anda!