Hugging Face's logo

Hub Python Library documentation

واجهة برمجة تطبيقات نظام الملفات

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

واجهة برمجة تطبيقات نظام الملفات

توفر فئة HfFileSystem واجهة ملفات بأسلوب بايثون للوصول إلى Hugging Face Hub بناءً على fsspec.

HfFileSystem

HfFileSystem مبني على fsspec، لذا فهو متوافق مع معظم الواجهات البرمجية التي يوفرها. لمزيد من التفاصيل، راجع دليلنا ومرجع الواجهات البرمجية الخاص بـ fsspec.

فئة huggingface_hub.HfFileSystem

< >

( *args**kwargs )

المعاملات

  • endpoint (str، اختياري) — نقطة النهاية الخاصة بـ Hub. القيمة الافتراضية هي https://huggingface.co.
  • token (bool أو str، اختياري) — رمز وصول مستخدم صالح (نص). الافتراضي هو الرمز المحفوظ محليًا، وهو الطريقة الموصى بها للمصادقة (انظر https://huggingface.co/docs/huggingface_hub/quick-start#authentication). لإلغاء تفعيل المصادقة، مرّر False.
  • block_size (int, اختياري) — حجم الكتلة لقراءة الملفات وكتابتها.
  • expand_info (bool، اختياري) — ما إذا كان سيتم توسيع معلومات الملفات.
  • max_workers (int، اختياري) — الحد الأقصى لعدد الطلبات المتزامنة المستخدمة لجرد المجلدات الكبيرة بالتوازي (انظر find()). القيمة الافتراضية هي 16. اضبطها على 1 لتعطيل الجرد المتوازي.
  • live_follow (bool، اختياري) — ما إذا كان سيتم متابعة التغييرات في الملفات داخل الدلاء (buckets) كما تحدث على Hub، بحيث تبقى القوائم المخزنة مؤقتًا محدّثة دون الحاجة إلى استدعاءات يدوية لـ HfFileSystem.invalidate_cache(). عند التفعيل، يؤدي عرض قائمة الدلو إلى فتح اتصال في الخلفية مع قناة أحداث Hub الخاصة بذلك الدلو. لا يؤثر هذا الخيار على مستودعات النماذج والبيانات والمساحات (حيث لا يوفر Hub تغييرات لها).
  • **storage_options (dict، اختياري) — خيارات إضافية لنظام الملفات. راجع توثيق fsspec.

الوصول إلى مستودع بعيد على Hugging Face Hub وكأنه نظام ملفات محلي.

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

يدعم نظام الملفات المسارات الخاصة ببروتوكول hf://، والذي يتبع مخططات عناوين URL التالية:

  • مستودعات النماذج ومجموعات البيانات والمساحات:
hf://<repo-id>[@<revision>]/<path/in/repo>
hf://datasets/<repo-id>[@<revision>]/<path/in/repo>
hf://spaces/<repo-id>[@<revision>]/<path/in/repo>
  • الدلاء (التخزين العام):
hf://buckets/<bucket-id>/<path/in/bucket>

ملاحظة: عند استخدام HfFileSystem مباشرةً، يكون تمرير بادئة البروتوكول hf:// اختيارياً في المسارات.

طريقة الاستخدام:

>>> from huggingface_hub import hffs

>>> # List files
>>> hffs.glob("my-username/my-model/*.bin")
['my-username/my-model/pytorch_model.bin']
>>> hffs.ls("datasets/my-username/my-dataset", detail=False)
['datasets/my-username/my-dataset/.gitattributes', 'datasets/my-username/my-dataset/README.md', 'datasets/my-username/my-dataset/data.json']

>>> # Read/write files
>>> with hffs.open("my-username/my-model/pytorch_model.bin") as f:
...     data = f.read()
>>> with hffs.open("my-username/my-model/pytorch_model.bin", "wb") as f:
...     f.write(data)

حدد رمز المصادقة:

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

cp_file

< >

( path1: strpath2: strrevision: str | None = None**kwargs )

المعاملات

  • path1 (str) — المسار المصدر للنسخ منه.
  • path2 (str) — المسار الوجهة للنسخ إليه.
  • revision (str، اختياري) — مراجعة git التي سيتم النسخ منها.

انسخ ملفًا داخل مستودع أو بين مستودعات، أو إلى دلو.

ملاحظة: عند الإمكان، استخدم HfApi.upload_file() للحصول على أداء أفضل.

يوجد

< >

( path**kwargs ) → bool

المعاملات

  • path (str) — المسار الذي يجب فحصه.

يعيد

bool

صحيح إذا كان الملف موجودًا، وإلا فخطأ.

تحقق من وجود ملف.

لمزيد من التفاصيل، راجع توثيق fsspec.

ملاحظة: عند الإمكان، استخدم HfApi.file_exists() للحصول على أداء أفضل.

find

< >

( path: strmaxdepth: int | None = Nonewithdirs: bool = Falsedetail: bool = Falserefresh: bool = Falserevision: str | None = None**kwargs ) → Union[list[str], dict[str, dict[str, Any]]]

المعاملات

  • path (str) — المسار الجذري الذي تُستخرج منه قائمة الملفات.
  • maxdepth (int، اختياري) — العمق الأقصى للنزول إلى المجلدات الفرعية.
  • withdirs (bool، اختياري) — تضمين مسارات المجلدات في المخرجات. القيمة الافتراضية هي False.
  • detail (bool، اختياري) — إذا كانت القيمة True، تُرجع قاموسًا يربط المسارات بمعلومات الملفات. القيمة الافتراضية هي False.
  • refresh (bool، اختياري) — إذا كانت القيمة True، يتم تجاوز ذاكرة التخزين المؤقت وجلب أحدث البيانات. القيمة الافتراضية هي False.
  • revision (str، اختياري) — مراجعة git التي سيتم سرد العناصر منها.

يعيد

Union[list[str], dict[str, dict[str, Any]]]

قائمة مسارات أو قاموس لمعلومات الملفات.

قائمة بجميع الملفات الموجودة أسفل المسار.

لمزيد من التفاصيل، راجع توثيق fsspec.

تُدرج المستودعات الكبيرة مجلدًا بمجلد، بالتوازي، لتجاوز ترقيم الصفحات القائم على المؤشر في نقطة نهاية tree في Hub. اضبط ذلك باستخدام الحجة max_workers في HfFileSystem.

get_file

< >

( rpathlpath = Nonecallback = <fsspec.callbacks.NoOpCallback object at 0x7f9673955c90>outfile = None**kwargs )

المعاملات

  • rpath (str) — المسار البعيد للتنزيل منه.
  • lpath (str، اختياري) — المسار المحلي للتنزيل إليه. يمكن تركه فارغًا إذا تم تقديم outfile.
  • callback (Callback، اختياري) — دالة استدعاء اختيارية لتتبع تقدم التنزيل. القيمة الافتراضية هي عدم وجود دالة استدعاء.
  • outfile (IO، اختياري) — كائن يشبه الملف اختياري للكتابة إليه. إذا تم تقديمه، يتم تجاهل lpath.

نسخ ملف بعيد واحد إلى المحلي.

ملاحظة: عند الإمكان، استخدم HfApi.hf_hub_download() أو HfApi.download_bucket_files للحصول على أداء أفضل.

glob

< >

( path: strmaxdepth: int | None = None**kwargs ) → list[str]

المعاملات

  • path (str) — نمط المسار المطابق.
  • maxdepth (int, اختياري) — العمق الأقصى للنزول إلى المجلدات. افتراضيًا، لا يوجد حد.

يعيد

list[str]

قائمة بالمسارات المطابقة للنمط.

ابحث عن الملفات باستخدام مطابقة الأنماط (glob-matching).

لمزيد من التفاصيل، راجع توثيق fsspec.

معلومات

< >

( path: strrefresh: bool = Falserevision: str | None = None**kwargs ) → dict[str, Any]

المعاملات

  • path (str) — المسار الذي سيتم جلب المعلومات عنه.
  • refresh (bool، اختياري) — إذا كانت القيمة True، يتم تجاوز ذاكرة التخزين المؤقت وجلب أحدث البيانات. القيمة الافتراضية هي False.
  • revision (str، اختياري) — مراجعة git التي سيتم الحصول على المعلومات منها.

يعيد

dict[str, Any]

قاموس يحتوي على معلومات الملف (النوع، الحجم، معلومات الالتزام، وما إلى ذلك).

احصل على معلومات حول ملف أو مجلد.

لمزيد من التفاصيل، راجع توثيق fsspec.

ملاحظة: عند الإمكان، استخدم HfApi.get_paths_info() أو HfApi.repo_info() للحصول على أداء أفضل (أو HfApi.get_bucket_paths_info() أو HfApi.bucket_info() للحاويات)

invalidate_cache

< >

( path: str | None = None )

المعاملات

  • path (str، اختياري) — المسار الذي يجب مسحُه من ذاكرة التخزين المؤقت. إذا لم يُقدَّم، فسيتم مسح ذاكرة التخزين المؤقت بالكامل.

امسح ذاكرة التخزين المؤقت للمسار المحدد.

لمزيد من التفاصيل، راجع توثيق fsspec.

isdir

< >

( path ) → bool

المعاملات

  • path (str) — المسار الذي يجب فحصه.

يعيد

bool

صحيح إذا كان المسار مجلدًا، وإلا فخطأ.

تحقق مما إذا كان المسار مجلدًا.

لمزيد من التفاصيل، راجع توثيق fsspec.

isfile

< >

( path ) → bool

المعاملات

  • path (str) — المسار الذي يجب فحصه.

يعيد

bool

صحيح إذا كان المسار ملفًا، وإلا فخطأ.

تحقق مما إذا كان المسار ملفًا.

لمزيد من التفاصيل، راجع توثيق fsspec.

ls

< >

( path: strdetail: bool = Truerefresh: bool = Falserevision: str | None = None**kwargs ) → list[Union[str, dict[str, Any]]]

المعاملات

  • path (str) — المسار إلى المجلد.
  • detail (bool، اختياري) — إذا كانت القيمة True، تُرجع قائمة من القواميس تحتوي على معلومات الملفات. إذا كانت False، تُرجع قائمة من مسارات الملفات. القيمة الافتراضية هي True.
  • refresh (bool، اختياري) — إذا كانت القيمة True، يتم تجاوز ذاكرة التخزين المؤقت وجلب أحدث البيانات. القيمة الافتراضية هي False.
  • revision (str، اختياري) — مراجعة git التي سيتم سرد العناصر منها.

يعيد

list[Union[str, dict[str, Any]]]

قائمة مسارات الملفات (إذا كان detail=False) أو قواميس معلومات الملفات (إذا كان detail=True).

قائمة محتويات مجلد.

لمزيد من التفاصيل، راجع توثيق fsspec.

ملاحظة: عند الإمكان، استخدم HfApi.list_repo_tree() للحصول على أداء أفضل.

تم تعديل

< >

( path: str**kwargs ) → datetime

المعاملات

  • path (str) — مسار الملف.

يعيد

datetime

وقت آخر تعديل للملف.

احصل على وقت آخر تعديل للملف.

لمزيد من التفاصيل، راجع توثيق fsspec.

resolve_path

< >

( path: strrevision: str | None = None ) → HfFileSystemResolvedPath

المعاملات

  • path (str) — المسار الذي يجب حله.
  • revision (str، اختياري) — إصدار المستودع الذي يجب حله. الافتراضي هو الإصدار المحدد في المسار.

يعيد

HfFileSystemResolvedPath

معلومات المسار المحلول التي تحتوي على repo_type وrepo_id وrevision وpath_in_repo.

يرفع

ValueError أو NotImplementedError

  • ValueError — إذا احتوى المسار على معلومات إصدار متضاربة.
  • NotImplementedError — عند محاولة سرد المستودعات.

حل مسار نظام ملفات Hugging Face إلى مكوّناته.

rm

< >

( path: strrecursive: bool = Falsemaxdepth: int | None = Nonerevision: str | None = None**kwargs )

المعاملات

  • path (str) — المسار الذي سيتم حذفه.
  • recursive (bool, اختياري) — إذا كانت القيمة True، يتم حذف المجلد وكل محتوياته. القيمة الافتراضية هي False.
  • maxdepth (int، اختياري) — الحد الأقصى لعدد الدلائل الفرعية التي يجب زيارتها عند الحذف بشكل تكراري.
  • revision (str، اختياري) — مراجعة git التي سيتم الحذف منها.

حذف الملفات من مستودع.

لمزيد من التفاصيل، راجع توثيق fsspec.

ملاحظة: عند الإمكان، استخدم HfApi.delete_file() للحصول على أداء أفضل.

url

< >

( path: str ) → str

المعاملات

  • path (str) — المسار للحصول على عنوان URL الخاص به.

يعيد

str

رابط HTTP للوصول إلى الملف أو المجلد على Hub.

احصل على عنوان URL الخاص بـ HTTP للمسار المحدد.

مشي

< >

( path: str*args**kwargs ) → Iterator[tuple[str, list[str], list[str]]]

المعاملات

  • path (str) — المسار الجذري الذي تُستخرج منه قائمة الملفات.

يعيد

Iterator[tuple[str, list[str], list[str]]]

مُتكرِّر (iterator) من tuples من الشكل (path, قائمة أسماء المجلدات، قائمة أسماء الملفات).

إرجاع جميع الملفات الموجودة أسفل المسار المحدد.

لمزيد من التفاصيل، راجع توثيق fsspec.

Update on GitHub

←عميل MCP HF URIs→