تكامل مكتبتك مع Hub

يهدف Hugging Face Hub إلى تسهيل مشاركة نماذج تعلّم الآلة والنقاط المحفوظة والمخرجات. وتشمل هذه المبادرة دمج الـ Hub مع العديد من المكتبات الخارجية الرائعة في المجتمع. ومن بين المكتبات التي تم دمجها بالفعل spaCy وSentence Transformers وOpenCLIP وtimm، إلى جانب العديد من المكتبات الأخرى. ويعني الدمج أن بإمكان المستخدمين تنزيل الملفات ورفعها إلى الـ Hub مباشرةً من مكتبتك. ونأمل أن تقوم بدمج مكتبتك وانضم إلينا في نشر الذكاء الاصطناعي للجميع.

توفر عملية دمج Hub مع مكتبتك العديد من الفوائد، بما في ذلك:

• استضافة مجانية للنماذج لك وللمستخدمين.
• إدارة إصدارات الملفات المدمجة - حتى للملفات الضخمة - بفضل Git-Xet.
• ميزات المجتمع (المناقشات، طلبات الدمج، الإعجابات).
• مقاييس الاستخدام لجميع النماذج التي تم تشغيلها باستخدام مكتبتك.

يساعدك هذا الشرح التعليمي على دمج Hub في مكتبتك حتى يستفيد مستخدموك من جميع الميزات التي يقدمها Hub.

قبل أن تبدأ، ننصحك بإنشاء حساب Hugging Face يمكنك من خلاله إدارة مستودعاتك وملفاتك.

إذا كنت بحاجة إلى مساعدة في عملية التكامل، فلا تتردد في فتح قضية، وسنكون سعداء للغاية بمساعدتك.

التنفيذ

غالبًا ما يعني تنفيذ تكامل مكتبة مع Hub توفير طرق مدمجة لتحميل النماذج من Hub والسماح للمستخدمين بدفع نماذج جديدة إلى Hub. ستغطي هذه القسم الأساسيات حول كيفية القيام بذلك باستخدام مكتبة huggingface_hub. للحصول على إرشادات أكثر تعمقًا، راجع هذا الدليل.

التثبيت

لدمج مكتبتك مع Hub، ستحتاج إلى إضافة مكتبة huggingface_hub كاعتمادية:

pip install huggingface_hub

لمزيد من التفاصيل حول تثبيت huggingface_hub، راجع هذا الدليل.

في هذا الدليل، سنركّز على مكتبات بايثون. إذا كنت قد نفّذت مكتبتك بلغة جافاسكربت، يمكنك استخدام @huggingface/hub بدلاً من ذلك. أما بقية المنطق (أي استضافة الملفات، ومقاطع الأكواد، وما إلى ذلك) فلا يعتمد على لغة البرمجة.

تم النسخ

npm add @huggingface/hub

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

hf auth login

يُخبرهم الأمر إن كانوا مسجّلين بالفعل ويطلب منهم إدخال رمزهم. ثم يتم التحقق من الرمز وحفظه في مجلد HF_HOME (الافتراضي هو ~/.cache/huggingface/token). وسيستخدم أي سكربت أو مكتبة تتفاعل مع Hub هذا الرمز عند إرسال الطلبات.

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

from huggingface_hub import login
login()

المصادقة اختيارية عند تنزيل الملفات من المستودعات العامة على Hub.

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

تتيح التكاملات للمستخدمين تنزيل نموذج من Hub وإنشائه مباشرةً من مكتبتك. وغالبًا ما يتحقق ذلك من خلال توفير طريقة (عادةً ما تُسمى from_pretrained أو load_from_hf) يجب أن تكون خاصة بمكتبتك. ولإنشاء نموذج من Hub، يجب أن تفعل مكتبتك ما يلي:

• تنزيل الملفات من Hub. وهذا ما سنناقشه الآن.
• أنشئ نموذج Python من هذه الملفات.

استخدم طريقة hf_hub_download لتنزيل الملفات من مستودع على Hub. تُحفظ الملفات المنزلة في ذاكرة التخزين المؤقت: ~/.cache/huggingface/hub. لن يضطر المستخدمون إلى إعادة تنزيل الملف في المرة التالية التي يستخدمونه فيها، مما يوفر الكثير من الوقت للملفات الكبيرة. علاوة على ذلك، إذا تم تحديث المستودع بإصدار جديد من الملف، فسيقوم huggingface_hub بتنزيل أحدث إصدار تلقائيًا وحفظه في ذاكرة التخزين المؤقت. لا يحتاج المستخدمون إلى القلق بشأن تحديث ملفاتهم يدويًا.

على سبيل المثال، حمّل ملف config.json من مستودع lysandre/arxiv-nlp:

>>> from huggingface_hub import hf_hub_download
>>> config_path = hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json")
>>> config_path
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json'

config_path يحتوي الآن على مسار إلى الملف المُحمَّل. يُكفَل وجود الملف وأنه محدَّث.

إذا كانت مكتبتك بحاجة إلى تنزيل مستودع كامل، فاستخدم snapshot_download. سيتولى هذا الأمر تنزيل جميع الملفات بالتوازي. القيمة المُعادَة هي مسار إلى المجلد الذي يحتوي على الملفات المنزلة.

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp")
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade'

تتوفر خيارات عديدة لتنزيل الملفات من إصدار محدد، وتصفية الملفات المراد تنزيلها، وتوفير مجلد تخزين مؤقت مخصص، وتنزيل الملفات إلى مجلد محلي، وغيرها. راجع دليل التنزيل لمزيد من التفاصيل.

رفع الملفات إلى Hub

قد ترغب أيضًا في توفير طريقة تتيح للمستخدمين رفع نماذجهم الخاصة إلى Hub. وهذا يتيح للمجتمع بناء منظومة من النماذج المتوافقة مع مكتبتك. وتوفر مكتبة huggingface_hub طرقًا لإنشاء المستودعات ورفع الملفات:

• create_repo ينشئ مستودعًا على Hub.
• تُحمّل upload_file وupload_folder الملفات إلى مستودع على Hub.

تُنشئ طريقة create_repo مستودعًا على Hub. استخدم معامل repo_id لتوفير اسم لمستودعك:

>>> from huggingface_hub import create_repo
>>> create_repo(repo_id="test-model")
'https://huggingface.co/lysandre/test-model'

عندما تتحقق من حسابك على Hugging Face، يجب أن ترى الآن مستودع test-model تحت نطاقك.

تُحمّل طريقة upload_file ملفًا إلى Hub. وتتطلب هذه الطريقة ما يلي:

• مسار إلى الملف المراد رفعه.
• المسار الأخير في المستودع.
• المستودع الذي ترغب في دفع الملفات إليه.

على سبيل المثال:

>>> from huggingface_hub import upload_file
>>> upload_file(
...    path_or_fileobj="/home/lysandre/dummy-test/README.md", 
...    path_in_repo="README.md", 
...    repo_id="lysandre/test-model"
... )
'https://huggingface.co/lysandre/test-model/blob/main/README.md'

إذا قمت بالتحقق من حسابك على Hugging Face، فيجب أن ترى الملف داخل مستودعك.

عادةً، تقوم المكتبة بتسلسل النموذج في مجلد محلي ثم رفع المجلد بأكمله إلى Hub دفعة واحدة. يمكن القيام بذلك باستخدام upload_folder:

>>> from huggingface_hub import upload_folder
>>> upload_folder(
...     folder_path="/home/lysandre/dummy-test",
...     repo_id="lysandre/test-model",
... )

لمزيد من التفاصيل حول كيفية رفع الملفات، راجد دليل الرفع.

بطاقات النماذج

بطاقات النماذج هي ملفات ترافق النماذج وتوفر معلومات مفيدة. في الخلفية، بطاقات النماذج هي ملفات Markdown بسيطة مع بيانات وصفية إضافية. بطاقات النماذج أساسية للعثور على النماذج، وقابلية إعادة الإنتاج، والمشاركة! يمكنك العثور على بطاقة النموذج كملف README.md في أي مستودع نموذج. راجع دليل بطاقات النماذج لمزيد من التفاصيل حول كيفية إنشاء بطاقة نموذج جيدة.

إذا سمح لك مكتبتك بدفع نموذج إلى Hub، فيُوصى بإنشاء بطاقة نموذج دنيا تتضمن بيانات وصفية مُعبأة مسبقًا (عادةً library_name، pipeline_tag أو tags) ومعلومات حول كيفية تدريب النموذج. سيساعد ذلك في توفير وصف موحّد لجميع النماذج المبنية باستخدام مكتبتك.

سجّل مكتبتك

أحسنت! يجب أن تكون لديك الآن مكتبة قادرة على تحميل نموذج من Hub ودفع نماذج جديدة في النهاية. الخطوة التالية هي التأكد من أن نماذجك على Hub موثقة جيدًا ومدمجة مع المنصة. للقيام بذلك، يمكن تسجيل المكتبات على Hub، مما يأتي مع بعض الفوائد للمستخدمين:

• يمكن عرض تسمية أنيقة على صفحة النموذج (مثل KerasNLP بدلاً من keras-nlp)
• يتم إضافة رابط إلى مستودع مكتبتك وتوثيقها إلى كل صفحة نموذج
• يمكن تعريف قاعدة عدد تنزيلات مخصصة
• يمكن توليد مقاطع كود لعرض كيفية تحميل النموذج باستخدام مكتبتك

لتسجيل مكتبة جديدة، يرجى فتح طلب سحب هنا باتباع التعليمات أدناه:

• يجب أن يكون معرّف المكتبة (id) أحرفًا صغيرة ومفصولة بشرطات (مثال: "adapter-transformers"). تأكد من الحفاظ على الترتيب الأبجدي عند فتح طلب الإرسال (PR).
• اضبط repoName وprettyLabel باستخدام تنسيق سهل الاستخدام (مثال: DeepForest).
• اضبط repoUrl برابط إلى كود المصدر الخاص بالمكتبة (عادةً مستودع GitHub).
• (اختياري) اضبط docsUrl برابط إلى توثيقات المكتبة. إذا كان التوثيق موجودًا في مستودع GitHub المشار إليه أعلاه، فلا حاجة لضبطه مرتين.
• اضبط filter على false.
• (اختياري) حدد كيفية احتساب عمليات التنزيل من خلال تعيين countDownload. يمكن تتبع التنزيلات بناءً على امتدادات الملفات أو أسماء الملفات. تأكد من عدم تكرار عملية الاحتساب. على سبيل المثال، إذا كان تحميل النموذج يتطلب 3 ملفات، فيجب أن تحسب قاعدة عدد التنزيلات عمليات التنزيل على ملف واحد فقط من بين الملفات الثلاثة. وإلا، فسيتم المبالغة في تقدير عدد التنزيلات. ملاحظة: إذا كانت المكتبة تستخدم أحد ملفات الإعداد الافتراضية (config.json، config.yaml، hyperparams.yaml، params.json، وmeta.yaml، راجع هنا)، فلا حاجة إلى تعريف قاعدة لعدد التنزيلات يدوياً.
• (اختياري) عرّف snippets لإعلام المستخدم بكيفية إنشاء نموذج بسرعة. مزيد من التفاصيل أدناه.

قبل فتح طلب الدمج، تأكد من أن نموذجًا واحدًا على الأقل مُشار إليه في https://huggingface.co/models?other=my-library-name. وإذا لم يكن الأمر كذلك، فيجب تحديث بيانات وصفية لبطاقات النماذج ذات الصلة باستخدام library_name: my-library-name (انظر مثال). وإذا لم تكن مالك النماذج على Hub، فيرجى فتح طلبات دمج (انظر مثال).

إليك مثالًا مبسطًا لإضافة التكامل مع VFIMamba.

مقتطفات الأكواد

نوصي بإضافة مقتطف من الشرح يوضح كيفية استخدام النموذج في مكتبتك المخصصة.

لإضافة مقتطف كود، يجب عليك تحديث ملف model-libraries-snippets.ts بتعليمات نموذجك. على سبيل المثال، تتضمن تكامل Asteroid مقتطف كود موجز يوضح كيفية تحميل نموذج Asteroid واستخدامه:

const asteroid = (model: ModelData) =>
`from asteroid.models import BaseModel
  
model = BaseModel.from_pretrained("${model.id}")`;

سيؤدي ذلك أيضًا إلى إضافة وسم إلى نموذجك حتى يتمكن المستخدمون من تحديد النماذج من مكتبتك بسرعة.

بمجرد إضافة مقتطفك إلى model-libraries-snippets.ts، يمكنك الإشارة إليه في model-libraries.ts كما هو موضح أعلاه.

وثّق مكتبتك

أخيرًا، يمكنك إضافة مكتبتك إلى توثيق Hub. راجع على سبيل المثال طلب الدمج الخاص بـ Setfit الذي أضاف SetFit إلى التوثيق.