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

HfApi'nin yanı sıra huggingface_hub kütüphanesi, Hugging Face Hub'a yönelik pythonik, fsspec-uyumlu bir dosya arayüzü olan HfFileSystem'i de sağlar. HfFileSystem, HfApi üzerine inşa edilir ve cp, mv, ls, du, glob, get_file ve put_file gibi tipik dosya sistemi tarzı işlemler sunar.

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 yöntemlerinin kullanılması önerilir.

Kullanım

>>> 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 kütüphanesinin 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 işlemleri (modlar "a" ve "ab") henüz desteklenmemektedir.

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, büyük depoları dizin dizin, paralel olarak listeler:

>>> 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'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ığına dikkat edin, çü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() ö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:

>>> 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, bir değişiklik geldiği anda bu değişiklikten etkilenen listelemeleri kaldırır. Bunu live_follow=True ile etkinleştirin:

>>> 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 değerini HfFileSystem.ls() fonksiyonuna (veya HfApi.list_repo_tree() fonksiyonunu kullanarak) iletin.
• 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 örnekleri tarafından paylaşılır. Bu nedenle seçenek varsayılan olarak kapalıdır (opt-in).

Entegrasyonlar

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, S3 benzeri bir nesne depolama olan Hugging Face Buckets'leri de destekler (daha fazla ayrıntı için bkz. bu kılavuz):

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

Hub ile etkileşimi HfFileSystem ile basitleştiren bazı ilginçi entegrasyonlar aşağıda listelenmiştir:

• Bir Hub deposundan Pandas DataFrame okuma/yazma:

  Kopyalandı

  >>> 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 ve Polars veri çerçeveleri için de kullanılabilir.

• DuckDB ile (uzaktaki) Hub dosyalarını sorgulama:

  Kopyalandı

  >>> 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 ile bir dizi deposu olarak kullanma:

  Kopyalandı

  >>> 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 bölümüne bakın.

token değerini HfFileSystem sınıfına argüman olarak geçirerek programatik olarak oturum açmak da mümkündür:

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