التفاعل مع Hub عبر واجهة برمجة التطبيقات Filesystem

بالإضافة إلى HfApi، توفر مكتبة huggingface_hub واجهة ملفات HfFileSystem بأسلوب بايثون ومتوافقة مع fsspec للوصول إلى Hugging Face Hub. يقوم HfFileSystem على أساس HfApi ويقدم عمليات نمطية لنظام الملفات مثل cp وmv وls وdu وglob وget_file وput_file.

يوفر HfFileSystem توافقًا مع fsspec، وهو أمر مفيد للمكتبات التي تتطلب ذلك (مثل قراءة مجموعات بيانات Hugging Face والخزائن مباشرةً باستخدام pandas). ومع ذلك، فإنه يُدخل عبئًا إضافيًا بسبب هذا طبقة التوافق. للحصول على أداء وموثوقية أفضل، يُوصى باستخدام طرق HfApi كلما أمكن ذلك.

الاستخدام

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

يمكن تمرير الحجة الاختيارية revision لتنفيذ عملية من التزامن المحدد، مثل فرع أو اسم وسم أو تجزئة التزامن. لاحظ أن revision غير متوافق مع Buckets.

على عكس الدالة open المدمجة في Python، فإن الدالة open في fsspec تعتمد افتراضيًا على الوضع الثنائي "rb". وهذا يعني أنه يجب عليك تحديد الوضع بشكل صريح كـ "r" للقراءة و "w" للكتابة في وضع النص. كما أن الإضافة إلى ملف (الأنماط "a" و "ab") غير مدعومة بعد.

قائمة المستودعات الكبيرة

تتطلب عمليات سرد الملفات بشكل متكرر، مثل find وglob، جلب المحتوى الكامل للمستودع. تُعيد المنصة هذه العناصر صفحةً تلو الأخرى، ولا يمكن طلب صفحة إلا بعد استلام الصفحة السابقة: فسرْد مستودع يحتوي على 800 ألف ملف يتطلب حوالي 800 طلب متسلسل، وبالتالي يستغرق نحو 30 دقيقة.

لتجنّب ذلك، يدرج HfFileSystem المستودعات الكبيرة مجلداً بمجلد، بالتوازي:

>>> from huggingface_hub import hffs

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

يتم التحكم في عدد الطلبات المتزامنة عبر معامل max_workers الخاص بـ HfFileSystem. القيمة الافتراضية هي 16 ويمكن ضبطها على 1 لتعطيل القوائم المتوازية. يرجى ملاحظة أن تمرير maxdepth يسرّع القوائم بشكل كبير أيضاً، حيث أن Hub يعيد فقط العناصر المطلوبة فعلياً.

حافظ على تحديث القوائم

تُدرج المجلدات مرة واحدة ويُخزَّن محتواها مؤقتًا، لذا فإن المجلد الذي قام شخص آخر بتعديله للتو لن يُلتقط تلقائيًا. HfFileSystem.invalidate_cache() يُلغي القوائم المخزنة مؤقتًا، إما لمسار واحد (وآبائه) أو في كل مكان عند استدعائه دون أي حجة:

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

بالنسبة للحاويات، يمكن لـhuggingface_hub القيام بذلك نيابةً عنك: حيث يبث مركز Hugging Face تغييرات ملفات الحاوية لحظة حدوثها، ويقوم HfFileSystem بإسقاط القوائم المتأثرة بالتغيير فور وصوله. فعّله باستخدام live_follow=True:

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

يمكن أيضًا تمريره عبر fsspec، باستخدام fsspec.filesystem("hf", live_follow=True) أو عبر معامل storage_options في المكتبات التي تقبله (pandas، arrow، …).

بعض الأمور التي يجب معرفتها بشأنه:

• الدلاء فقط. مستودعات النماذج والمجموعات البيانات والمساحات هي مستودعات git ولا يقوم الـ Hub ببث تغييراتها: مرّر refresh=True إلى HfFileSystem.ls() (أو استخدم HfApi.list_repo_tree()) لرؤية التزام الجديد.
• يتم تحديث القوائم والميتاداتا المرفقة بها فقط. عند قراءة ملف، يتم دائمًا طلب محتواه من الـ Hub، لذا فإن المتابعة الحية تؤثر فقط على ما تبيّنه أوامر ls، info، exists، glob، …
• يبدأ المتابعة بمجرد إدراج دلو، ويُحافظ على اتصال خلفي واحد مفتوح لكل دلو يتم متابعته، ويُشارك بين جميع كائنات HfFileSystem. ولهذا السبب، تكون هذه الخيار اختيارياً.

التكاملات

يمكن استخدام HfFileSystem مع أي مكتبة تكامل مع fsspec، شريطة أن يتبع الرابط المخطط التالي:

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

يكون repo_type_prefix هو datasets/ لمجموعات البيانات، وspaces/ للمساحات، بينما لا تحتاج النماذج إلى بادئة في عنوان URL.

بالإضافة إلى المستودعات، يدعم HfFileSystem أيضًا حاويات Hugging Face Buckets وهي تخزين كائنات يشبه S3 (انظر هذا الدليل لمزيد من التفاصيل):

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

فيما يلي بعض التكاملات المثيرة للاهتمام حيث يسهّل HfFileSystem التفاعل مع Hub:

• قراءة/كتابة إطار بيانات Pandas من مستودع Hub/إليه:

  تم النسخ

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

يمكن استخدام نفس سير العمل أيضًا لإطارات بيانات Dask وPolars.

• استعلام ملفات (البعيدة) في Hub باستخدام DuckDB:

  تم النسخ

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

  تم النسخ

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

المصادقة

في كثير من الحالات، يجب تسجيل الدخول بحساب Hugging Face للتفاعل مع Hub. راجع قسم المصادقة في التوثيق لمعرفة المزيد حول طرق المصادقة على Hub.

من الممكن أيضًا تسجيل الدخول برمجياً عن طريق تمرير token الخاص بك كحجة إلى HfFileSystem:

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

إذا قمت بتسجيل الدخول بهذه الطريقة، فانتبه إلى عدم تسريب الرمز عن طريق الخطأ عند مشاركة كودك المصدري!