# Hub ile Dosya Sistemi API'si aracılığıyla etkileşime geçin

[HfApi](/docs/huggingface_hub/v2.4.0/tr/package_reference/hf_api#huggingface_hub.HfApi)'nin yanı sıra `huggingface_hub` kütüphanesi, Hugging Face Hub'a yönelik pythonik, [fsspec-uyumlu](https://filesystem-spec.readthedocs.io/en/latest/) bir dosya arayüzü olan [HfFileSystem](/docs/huggingface_hub/v2.4.0/tr/package_reference/hf_file_system#huggingface_hub.HfFileSystem)'i de sağlar. [HfFileSystem](/docs/huggingface_hub/v2.4.0/tr/package_reference/hf_file_system#huggingface_hub.HfFileSystem), [HfApi](/docs/huggingface_hub/v2.4.0/tr/package_reference/hf_api#huggingface_hub.HfApi) üzerine inşa edilir ve `cp`, `mv`, `ls`, `du`, `glob`, `get_file` ve `put_file` gibi tipik dosya sistemi tarzı işlemler sunar.

> [!WARNING]
> [HfFileSystem](/docs/huggingface_hub/v2.4.0/tr/package_reference/hf_file_system#huggingface_hub.HfFileSystem), bunu gerektiren kütüphaneler için (örneğin `pandas` ile Hugging Face veri kümelerini ve depolarını doğrudan okuma) faydalı olan fsspec uyumluluğu sağlar. Ancak bu uyumluluk katmanı nedeniyle ek bir yük getirir. Daha iyi performans ve güvenilirlik için mümkün olduğunda [HfApi](/docs/huggingface_hub/v2.4.0/tr/package_reference/hf_api#huggingface_hub.HfApi) yöntemlerinin kullanılması önerilir.

## Kullanım

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

İsteğe bağlı `revision` argümanı, bir dal, etiket adı veya commit hash'i gibi belirli bir commit'ten bir işlem çalıştırmak için geçirilebilir. `revision`'in Buckets ile uyumlu olmadığını unutmayın.

Python'ın yerleşik `open` fonksiyonunun aksine, `fsspec`'in `open` fonksiyonu varsayılan olarak ikili modda, `"rb"` çalışır. Bu, metin modunda okuma için modu açıkça `"r"` ve yazma için `"w"` olarak belirlemeniz gerektiği anlamına gelir. Bir dosyaya ekleme (modlar `"a"` ve `"ab"`) henüz desteklenmiyor.

## Büyük depoların listelenmesi

`find` ve `glob` gibi dosyaları özyinelemeli olarak listeleme işlemleri, depoyun tüm içeriğini getirmelidir. Hub bu girdileri sayfa sayfa döndürür ve bir sayfa, önceki sayfa alındıktan sonra istenebilir: 800 bin dosya içeren bir depoyu listelemek ~800 ardışık istek ve dolayısıyla yaklaşık 30 dakika gerektirir.

Bunu önlemek için [HfFileSystem](/docs/huggingface_hub/v2.4.0/tr/package_reference/hf_file_system#huggingface_hub.HfFileSystem), büyük depoları dizin dizin, paralel olarak listeler:

```python
>>> from huggingface_hub import hffs

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

Eşzamanlı istek sayısı, [HfFileSystem](/docs/huggingface_hub/v2.4.0/tr/package_reference/hf_file_system#huggingface_hub.HfFileSystem)'in `max_workers` argümanı tarafından kontrol edilir. Varsayılan değeri 16'dır ve paralel listelemeyi devre dışı bırakmak için 1 olarak ayarlanabilir. `maxdepth` parametresinin geçirilmesinin de listelemeleri önemli ölçüde hızlandırdığını unutmayın; çünkü Hub bu durumda yalnızca gerçekten istenen girdileri döndürür.

## Listeleri güncel tutun

Dizinler bir kez listelenir ve içerikleri önbelleğe alınır, bu nedenle başka biri tarafından az önce değiştirilen bir dizin otomatik olarak algılanmaz. [HfFileSystem.invalidate_cache()](/docs/huggingface_hub/v2.4.0/tr/package_reference/hf_file_system#huggingface_hub.HfFileSystem.invalidate_cache) önbelleğe alınmış listelemeleri, bir yol (ve üst dizinleri) için veya argüman verilmeden çağrıldığında her yerde düşürür:

```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']
```

Bucket'ler için `huggingface_hub` bunu sizin için yapabilir: Hub, bir bucket'taki dosya değişikliklerini gerçekleşme anında akış olarak iletir ve [HfFileSystem](/docs/huggingface_hub/v2.4.0/tr/package_reference/hf_file_system#huggingface_hub.HfFileSystem), bir değişiklik geldiği anda bu değişiklikten etkilenen listelemeleri kaldırır. Bunu `live_follow=True` ile etkinleştirin:

```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']
```

Ayrıca `fsspec.filesystem("hf", live_follow=True)` ile fsspec üzerinden veya bunu kabul eden kütüphanelerin (pandas, arrow, ...) `storage_options` argümanı üzerinden de geçirilebilir.

Bunları bilmeniz gerekir:

- **Sadece variller.** Model, veri seti ve alan depoları git depolarıdır ve Hub bunlardaki değişiklikleri akış olarak iletmez: yeni bir commit'i görmek için `refresh=True` parametresini [HfFileSystem.ls()](/docs/huggingface_hub/v2.4.0/tr/package_reference/hf_file_system#huggingface_hub.HfFileSystem.ls) fonksiyonuna (veya [HfApi.list_repo_tree()](/docs/huggingface_hub/v2.4.0/tr/package_reference/hf_api#huggingface_hub.HfApi.list_repo_tree) fonksiyonunu) kullanın.
- **Sadece listeler ve bunların taşıdığı meta veriler yenilenir.** Bir dosyanın içeriği her zaman Hub'dan istendiğinden, canlı izleme yalnızca `ls`, `info`, `exists`, `glob`, ... komutlarının raporladıklarını etkiler.
- İzleme, bir varlık kutusu (bucket) listelendiği anda başlar ve izlenen her varlık kutusu için bir arka plan bağlantısı açık tutulur; bu bağlantı tüm [HfFileSystem](/docs/huggingface_hub/v2.4.0/tr/package_reference/hf_file_system#huggingface_hub.HfFileSystem) örnekleri tarafından paylaşılır. Bu nedenle seçenek varsayılan olarak kapalıdır (opt-in).

## Entegrasyonlar

[HfFileSystem](/docs/huggingface_hub/v2.4.0/tr/package_reference/hf_file_system#huggingface_hub.HfFileSystem), URL şu şemayı izlediği sürece `fsspec` ile entegre olan herhangi bir kitaplıkla kullanılabilir:

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

Veri kümeleri için `repo_type_prefix` değeri `datasets/`, Spaces için `spaces/` şeklindedir ve modellerin URL'de bir önekeye ihtiyacı yoktur.

Depoların yanı sıra [HfFileSystem](/docs/huggingface_hub/v2.4.0/tr/package_reference/hf_file_system#huggingface_hub.HfFileSystem), S3 benzeri bir nesne depolama olan Hugging Face Buckets'leri de destekler (daha fazla ayrıntı için bkz. [bu kılavuz](./buckets)):

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

Hub ile etkileşimi [HfFileSystem](/docs/huggingface_hub/v2.4.0/tr/package_reference/hf_file_system#huggingface_hub.HfFileSystem) ile basitleştiren bazı ilginçi entegrasyonlar aşağıda listelenmiştir:

* Bir Hub deposundan [Pandas](https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html#reading-writing-remote-files) DataFrame okuma/yazma:

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

Aynı iş akışı, [Dask](https://docs.dask.org/en/stable/how-to/connect-to-remote-data.html) ve [Polars](https://pola-rs.github.io/polars/py-polars/html/reference/io.html) veri çerçeveleri için de kullanılabilir.

* Querying (uzak) [DuckDB](https://duckdb.org/docs/guides/python/filesystems) ile Hub dosyaları:

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

* Hub'ı [Zarr](https://zarr.readthedocs.io/en/stable/tutorial.html#io-with-fsspec) ile bir dizi deposu olarak kullanma:

  ```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]
  ```

## Kimlik Doğrulama

Birçok durumda, Hub ile etkileşime girmek için bir Hugging Face hesabıyla oturum açmış olmanız gerekir. Hub'daki kimlik doğrulama yöntemleri hakkında daha fazla bilgi edinmek için belgelerin [Authentication](../quick-start#authentication) bölümüne bakın.

`token` değerini [HfFileSystem](/docs/huggingface_hub/v2.4.0/tr/package_reference/hf_file_system#huggingface_hub.HfFileSystem) sınıfına argüman olarak geçirerek programatik olarak oturum açmak da mümkündür:

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

Bu şekilde oturum açarsanız, kaynak kodunuzu paylaşırken token'ı yanlışlıkla sızdırmamaya dikkat edin!