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

بالإضافة إلى [HfApi](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_api#huggingface_hub.HfApi)، توفر مكتبة `huggingface_hub` واجهة ملفات [HfFileSystem](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_file_system#huggingface_hub.HfFileSystem) بأسلوب بايثون ومتوافقة مع [fsspec](https://filesystem-spec.readthedocs.io/en/latest/) للوصول إلى Hugging Face Hub. يقوم [HfFileSystem](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_file_system#huggingface_hub.HfFileSystem) على أساس [HfApi](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_api#huggingface_hub.HfApi) ويقدم عمليات نمطية لنظام الملفات مثل `cp` و`mv` و`ls` و`du` و`glob` و`get_file` و`put_file`.

> [!WARNING]
> يوفر [HfFileSystem](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_file_system#huggingface_hub.HfFileSystem) توافقًا مع fsspec، وهو أمر مفيد للمكتبات التي تتطلب ذلك (مثل قراءة مجموعات بيانات Hugging Face والخزائن مباشرةً باستخدام `pandas`). ومع ذلك، فإنه يُدخل عبئًا إضافيًا بسبب هذا طبقة التوافق. للحصول على أداء وموثوقية أفضل، يُنصح باستخدام طرق [HfApi](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_api#huggingface_hub.HfApi) كلما أمكن ذلك.

## الاستخدام

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

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

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

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

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

لتجنّب ذلك، يدرج [HfFileSystem](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_file_system#huggingface_hub.HfFileSystem) المستودعات الكبيرة مجلداً بمجلد، بالتوازي:

```python
>>> 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](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_file_system#huggingface_hub.HfFileSystem). القيمة الافتراضية هي 16، ويمكن ضبطها على 1 لتعطيل القوائم المتوازية. لاحظ أن تمرير `maxdepth` يسرّع أيضاً بشكل كبير من عملية القوائم، حيث أن Hub يعيد في هذه الحالة فقط العناصر المطلوبة فعلياً.

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

تُدرج المجلدات مرة واحدة ويُخزَّن محتواها مؤقتًا، لذا فإن أي تغييرات أجراها شخص آخر على مجلد ما لا تُلتقط تلقائيًا. [HfFileSystem.invalidate_cache()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_file_system#huggingface_hub.HfFileSystem.invalidate_cache) يُلغي القوائم المخزنة مؤقتًا، إما لمسار واحد (وآبائه) أو لكل المسارات عند استدعائه دون أي حجة:

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

بالنسبة للحاويات، يمكن لـ`huggingface_hub` القيام بذلك نيابةً عنك: حيث يبث مركز Hugging Face تغييرات ملفات الحاوية لحظة حدوثها، ويتخلص [HfFileSystem](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_file_system#huggingface_hub.HfFileSystem) من القوائم المتأثرة بالتغيير فور وصوله. فعّله باستخدام `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']
```

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

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

- **الدلاء فقط.** مستودعات النماذج والمجموعات البيانات والمساحات هي مستودعات git ولا يقوم الـ Hub ببث تغييراتها: مرّر `refresh=True` إلى [HfFileSystem.ls()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_file_system#huggingface_hub.HfFileSystem.ls) (أو استخدم [HfApi.list_repo_tree()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_api#huggingface_hub.HfApi.list_repo_tree)) لرؤية التزام الجديد.
- **يتم تحديث القوائم والميتاداتا المرفقة بها فقط.** عند قراءة ملف، يُطلب محتواه دائمًا من Hub، لذا فإن المتابعة الحية تؤثر فقط على ما تُبلّغ عنه `ls`، `info`، `exists`، `glob`، ...
- يبدأ المتابعة بمجرد إدراج دلو، ويُحافظ على اتصال خلفي واحد مفتوح لكل دلو يتم متابعته، ويُشارك بين جميع كائنات [HfFileSystem](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_file_system#huggingface_hub.HfFileSystem). ولهذا السبب، تكون هذه الخيار اختيارياً.

## التكاملات

يمكن استخدام [HfFileSystem](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_file_system#huggingface_hub.HfFileSystem) مع أي مكتبة تكامل مع `fsspec`، شريطة أن يتبع الرابط المخطط التالي:

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

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

بالإضافة إلى المستودعات، يدعم [HfFileSystem](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_file_system#huggingface_hub.HfFileSystem) أيضًا حاويات Hugging Face Buckets وهي تخزين كائنات يشبه S3 (انظر [هذا الدليل](./buckets) لمزيد من التفاصيل):

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

فيما يلي بعض التكاملات المثيرة للاهتمام حيث يسهّل [HfFileSystem](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_file_system#huggingface_hub.HfFileSystem) التفاعل مع Hub:

* قراءة/كتابة إطار بيانات [Pandas](https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html#reading-writing-remote-files) من مستودع 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")
  ```

يمكن استخدام نفس سير العمل أيضًا لإطارات بيانات [Dask](https://docs.dask.org/en/stable/how-to/connect-to-remote-data.html) و[Polars](https://pola-rs.github.io/polars/py-polars/html/reference/io.html).

* Querying ملفات (remot) Hub باستخدام [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()
  ```

* استخدام Hub كمخزن مصفوفات مع [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]
  ```

## المصادقة

في كثير من الحالات، يجب تسجيل الدخول بحساب Hugging Face للتفاعل مع Hub. راجع قسم [المصادقة](../quick-start#authentication) في التوثيق لمعرفة المزيد حول طرق المصادقة على Hub.

من الممكن أيضًا تسجيل الدخول برمجياً عن طريق تمرير `token` الخاص بك كحجة إلى [HfFileSystem](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_file_system#huggingface_hub.HfFileSystem):

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

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