البدء السريع

يُعدّ Hugging Face Hub الوجهة الأساسية لمشاركة نماذج تعلّم الآلة، والعروض التوضيحية، ومجموعات البيانات، والمقاييس. تساعدك مكتبة huggingface_hub على التفاعل مع الـ Hub دون مغادرة بيئة التطوير الخاصة بك. يمكنك إنشاء المستودعات وإدارتها بسهولة، وتنزيل الملفات ورفعها، والحصول على بيانات وصفية مفيدة للنماذج ومجموعات البيانات من الـ Hub.

التثبيت

للبداية، قم بتثبيت مكتبة huggingface_hub:

pip install --upgrade huggingface_hub

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

يأتي huggingface_hub أيضًا مع واجهة سطر أوامر hf تتيح لك التفاعل مع Hub مباشرةً من الطرفية. إذا كنت تستخدم وكلاء ذكاء اصطناعي (Claude Code، Codex، Cursor، ...)، فقم بتثبيت المهارة (Skill) للسماح لوكيلك باستخدام واجهة سطر الأوامر:

تم النسخ

# works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills`
hf skills add

اطّلع على دليل واجهة سطر أوامر Hugging Face للوكلاء الذكيين لمزيد من التفاصيل.

تنزيل الملفات

المستودعات على Hub مُتحكَّم بها في إصداراتها عبر git، ويمكن للمستخدمين تنزيل ملف واحد أو المستودع بأكمله. يمكنك استخدام الدالة hf_hub_download() لتنزيل الملفات. ستقوم هذه الدالة بتنزيل ملف وتخزينه مؤقتًا على القرص المحلي لديك. في المرة التالية التي تحتاج فيها إلى ذلك الملف، سيُحمَّل من ذاكرتك المؤقتة، لذا لا حاجة إلى إعادة تنزيله.

ستحتاج إلى معرف المستودع واسم الملف الذي تريد تنزيله. على سبيل المثال، لتنزيل ملف تكوين نموذج Pegasus:

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json")

لتحميل إصدار محدد من الملف، استخدم معامل revision لتحديد اسم الفرع أو العلامة أو تجزئة الالتزام. إذا اخترت استخدام تجزئة الالتزام، فيجب أن تكون التجزئة بطولها الكامل بدلاً من تجزئة الالتزام المختصرة المكونة من 7 أحرف:

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(
...     repo_id="google/pegasus-xsum",
...     filename="config.json",
...     revision="4d33b01d79672f27f001f6abade33f22d993b151"
... )

لمزيد من التفاصيل والخيارات، راجع مرجع واجهة برمجة التطبيقات الخاص بـ hf_hub_download().

المصادقة

في كثير من الحالات، يجب أن تكون مسجّل الدخول بحساب Hugging Face للتفاعل مع الـHub: تنزيل المستودعات الخاصة، رفع الملفات، إنشاء طلبات الدمج (PRs)،... أنشئ حسابًا إذا لم يكن لديك حساب بالفعل.

أمر تسجيل الدخول

أسهل طريقة للمصادقة هي عبر أمر login():

hf auth login

إذا كنت مسجّل الدخول بالفعل، فسيُعيد الأمر فورًا. لفرض تسجيل الدخول مجددًا، استخدم hf auth login --force. إذا لم تكن مسجّل الدخول، فسيُطلب منك تسجيل الدخول عبر متصفحك: افتح الرابط المطبوع، أدخل الرمز المختصر، وافق على الطلب، وسيتم استرداد رمز وصول وحفظه في مجلد HF_HOME (الافتراضي هو ~/.cache/huggingface/token). ينتهي صلاحية الرمز بعد فترة ما، لكنه يُحدَّث تلقائيًا ما دمت تستمر في استخدامه. أي سكربت أو مكتبة تتفاعل مع Hub ستستخدم هذا الرمز عند إرسال الطلبات. أو يمكنك لصق رمز وصول المستخدم الذي تم إنشاؤه من صفحة الإعدادات.

يمكن أن تتمتع رموز وصول المستخدم read أو write. تأكد من امتلاك رمز وصول write إذا كنت ترغب في إنشاء مستودع أو تحريره. وإلا، فمن الأفضل توليد رمز read لتقليل المخاطر في حال تسرب رمزك عن غير قصد.

بديلًا عن ذلك، يمكنك تسجيل الدخول برمجيًا باستخدام login() في دفتر ملاحظات أو سكربت:

>>> from huggingface_hub import login
>>> login()

يمكنك تسجيل الدخول إلى حساب واحد فقط في كل مرة. عند تسجيل الدخول إلى حساب جديد، سيتم تسجيل خروجك تلقائيًا من الحساب السابق. لتحديد الحساب النشط حاليًا، ما عليك سوى تنفيذ الأمر hf auth whoami.

بمجرد تسجيل الدخول، ستستخدم جميع الطلبات الموجّهة إلى Hub - حتى تلك التي لا تتطلب المصادقة بالضرورة - رمز الوصول الخاص بك افتراضيًا. إذا كنت ترغب في تعطيل الاستخدام الضمني لرمزك، فيجب عليك تعيين HF_HUB_DISABLE_IMPLICIT_TOKEN=1 كمتغير بيئة (انظر المرجع).

إدارة عدة رموز محلية

يمكنك حفظ عدة رموز على جهازك ببساطة عن طريق تسجيل الدخول باستخدام أمر login() مع كل رمز. إذا كنت بحاجة إلى التبديل بين هذه الرموز محليًا، يمكنك استخدام أمر auth switch:

hf auth switch

ستطلب منك هذه الأوامر اختيار رمز باسمه من قائمة الرموز المحفوظة. بمجرد الاختيار، يصبح الرمز المختار الرمز النشط، وسيُستخدم لجميع التفاعلات مع Hub.

يمكنك سرد جميع رموز الوصول المتاحة على جهازك باستخدام hf auth list.

متغير البيئة

يمكن أيضًا استخدام متغير البيئة HF_TOKEN للمصادقة. وهذا مفيد بشكل خاص في Space حيث يمكنك تعيين HF_TOKEN كـ سر Space.

جديد: يتيح لك Google Colaboratory تحديد مفاتيح خاصة لدفاترك. حدّد سرّ HF_TOKEN ليتم المصادقة تلقائيًا!

تتمتع المصادقة عبر متغير بيئة أو سرّ بأولوية على الرمز المحفوظ على جهازك.

معلمات الطريقة

وأخيرًا، من الممكن أيضًا المصادقة عن طريق تمرير رمزك إلى أي طريقة تقبل token كمتغير.

from huggingface_hub import whoami

user = whoami(token=...)

يُنصح عادةً بتجنّب ذلك، باستثناء الحالات التي لا ترغب فيها في تخزين رمزك بشكل دائم، أو عندما تحتاج إلى التعامل مع عدة رموز في آنٍ واحد.

يرجى توخي الحذر عند تمرير الرموز (tokens) كمتغير. يُعدّ أفضل ممارسة دائمًا تحميل الرمز من مخزن آمن بدلاً من تضمينه بشكل ثابت في قاعدة الكود الخاصة بك أو في دفتر الملاحظات (notebook). فالتضمين الثابت للرموز يشكّل خطر تسرّب كبيرًا إذا قمت بمشاركة كودك عن غير قصد.

إنشاء مستودع

بمجرد تسجيلك وتسجيل دخولك، أنشئ مستودعًا باستخدام دالة create_repo():

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model")

إذا كنت ترغب في أن يكون مستودعك خاصاً، فـ:

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model", private=True)

لن تكون المستودعات الخاصة مرئية لأي شخص عداك أنت.

لإنشاء مستودع أو لدفع المحتوى إلى Hub، يجب عليك تقديم رمز وصول للمستخدم (User Access Token) يحمل صلاحية write. يمكنك اختيار الصلاحية عند إنشاء الرمز في صفحة الإعدادات.

رفع الملفات

استخدم دالة upload_file() لإضافة ملف إلى المستودع الذي أنشأته للتو. عليك تحديد:

1. مسار الملف المراد رفعه.
2. مسار الملف في المستودع.
3. معرّف المستودع الذي تريد إضافة الملف إليه.

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.upload_file(
...     path_or_fileobj="/home/lysandre/dummy-test/README.md",
...     path_in_repo="README.md",
...     repo_id="lysandre/test-model",
... )

لرفع أكثر من ملف في وقت واحد، اطّلع على دليل Upload الذي سيُعرّفك على عدة طرق لرفع الملفات (مع git أو بدونه).

الخطوات التالية

توفّر مكتبة huggingface_hub طريقة سهلة للمستخدمين للتفاعل مع Hub باستخدام Python. لمعرفة المزيد حول كيفية إدارة ملفاتك ومستودعاتك على Hub، ننصح بقراءة أدلة الاستخدام الخاصة بنا:

• إدارة مستودعك.
• تنزيل الملفات من Hub.
• رفع الملفات إلى Hub.
• ابحث في Hub عن النموذج أو مجموعة البيانات المطلوبة.
• تشغيل الاستدلال عبر خدمات متعددة للنماذج المستضافة على Hugging Face Hub.