الانتقال إلى huggingface_hub v1.0

يُعد إصدار v1.0 محطة بارزة لمكتبة huggingface_hub. وهو يعبّر عن التزامنا باستقرار واجهة برمجة التطبيقات ونضج المكتبة. لقد أجرينا عدة تحسينات وتغييرات كاسرة لجعل المكتبة أكثر متانة وسهولة في الاستخدام.

يهدف هذا الدليل إلى مساعدتك في نقل كودك الحالي إلى الإصدار الجديد. إذا كانت لديك أي أسئلة أو ملاحظات، يرجى إعلامنا من خلال فتح مشكلة على GitHub.

Python 3.9+

يتطلب huggingface_hub الآن Python 3.9 أو إصدارًا أحدث. لم يعد Python 3.8 مدعومًا.

الانتقال إلى HTTPX

يستخدم الآن مكتبة huggingface_hub httpx بدلاً من requests لإجراء طلبات HTTP. تم إجراء هذا التغيير لتحسين الأداء وللدعم المتساوي لكل من الطلبات المتزامنة وغير المتزامنة. لذلك، تم التخلي عن كل من تبعيات requests وaiohttp.

التغييرات الجذرية

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

• إعدادات الوكيل: لم تعد وكلاء “لكل طريقة” مدعومة. يجب إعداد الوكلاء على مستوى النظام باستخدام متغيرات البيئة HTTP_PROXY وHTTPS_PROXY.
• خادم HTTP مخصص: تم حذف الدالة configure_http_backend. يجب عليك الآن استخدام set_client_factory() و set_async_client_factory() لإعداد عملاء HTTP.
• معالجة الأخطاء: لم تعد أخطاء HTTP موروثة من requests.HTTPError، بل أصبحت موروثة من httpx.HTTPError. ننصح بالالتقاط HfHubHTTPError (المستورد عبر from huggingface_hub.utils import HfHubHTTPError)، وهو فئة فرعية من requests.HTTPError في الإصدار v0.x ومن httpx.HTTPError في الإصدار v1.x. إن الالتقاط من خطأ huggingface_hub يضمن توافق كودك مع كلا الإصدارين القديم والجديد من المكتبة.
• SSLError: لا يحتوي httpx على مفهوم SSLError. أصبح الآن httpx.ConnectError عامًا.
• LocalEntryNotFoundError: لم يعد هذا الخطأ يرث من HTTPError. لقد عرّفنا الآن EntryNotFoundError (جديدًا) يرثه كل من LocalEntryNotFoundError (إذا لم يُعثر على الملف في ذاكرة التخزين المؤقت المحلية) وRemoteEntryNotFoundError (إذا لم يُعثر على الملف في المستودع على Hub). الخطأ البعيد فقط هو الذي يرث من HTTPError.
• InferenceClient: أصبح بإمكانك الآن استخدام InferenceClient كمدير سياق. وهذا مفيد بشكل خاص عند بث الرموز من نموذج لغوي لضمان إغلاق الاتصال بشكل صحيح.
• AsyncInferenceClient: تم إزالة معامل trust_env من مُنشئ AsyncInferenceClient. تُعتبر متغيرات البيئة موثوقة افتراضيًا بواسطة httpx. إذا كنت لا تريد صراحةً الثقة بالبيئة، فيجب عليك تكوين ذلك باستخدام set_async_client_factory().

لمزيد من التفاصيل، يمكنك الاطلاع على PR #3328 الذي أدخل httpx.

لماذا httpx؟

يُحسّن الانتقال من requests إلى httpx عدة جوانب رئيسية تعزز أداء المكتبة وموثوقيتها وقابليتها للصيانة:

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

دعم HTTP/2: يوفر httpx دعمًا أصليًا لـ HTTP/2، مما يحقق كفاءة أعلى عند إرسال عدة طلبات إلى نفس الخادم (وهو بالضبط حالتنا). وهذا يعني انخفاض زمن الاستجابة وتقليل استهلاك الموارد مقارنةً بـ HTTP/1.1.

واجهة موحّدة للمزامنة وغير المزامنة: على عكس إعدادنا السابق الذي اعتمد على تبعيات منفصلة لـrequests (مزامنة) وaiohttp (غير مزامنة)، يوفر httpx عميلين مزامناً وغير مزامن بسلوك متطابق. وهذا يضمن أن تتمتع InferenceClient وAsyncInferenceClient بوظائف متسقة، ويُلغي الفروق الدقيقة في السلوك التي كانت موجودة سابقاً بين التنفيذين.

تحسين معالجة أخطاء SSL: يتعامل httpx مع أخطاء SSL بسلاسة أكبر، مما يجعل تصحيح أخطاء الاتصال أسهل وأكثر موثوقية.

بنية تحتية آمنة للمستقبل: يُحافظ على httpx بنشاط وهو مصمم لتطبيقات بايثون الحديثة. في المقابل، يوجد requests في وضع الصيانة ولن يتلقى تحديثات رئيسية مثل تحسينات أمان الخيوط أو دعم HTTP/2.

معالجة أفضل لمتغيرات البيئة: يوفر httpx معالجة أكثر اتساقًا لمتغيرات البيئة عبر سياقي المزامنة وغير المتزامنة، مما يقضي على عدم الاتساق السابق حيث كان requests يقرأ متغيرات البيئة المحلية افتراضيًا بينما لم يكن aiohttp يفعل ذلك.

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

hf_transfer

الآن، بما أن جميع المستودعات على Hub أصبحت مفعّلةً بتقنية Xet، وأن hf_xet هو الطريقة الافتراضية لتنزيل/رفع الملفات، فقد أزلنا الدعم للحزمة الاختيارية hf_transfer. وبالتالي، يتم تجاهل متغير البيئة HF_HUB_ENABLE_HF_TRANSFER. استخدم HF_XET_HIGH_PERFORMANCE بدلاً من ذلك.

فئة المستودع

تمت إزالة فئة Repository في الإصدار v1.0. كانت هذه الفئة غلافًا رفيعًا حول واجهة سطر الأوامر git لإدارة المستودعات. يمكنك ما زال استخدام git مباشرةً في الطرفية، لكن النهج الموصى به هو استخدام واجهة برمجة التطبيقات (API) القائمة على HTTP في مكتبة huggingface_hub للحصول على تجربة أكثر سلاسة، خاصة عند التعامل مع الملفات الكبيرة.

إليك خريطة من فئة Repository القديمة إلى فئة HfApi الجديدة:

طريقة Repository	طريقة HfApi
repo.clone_from	snapshot_download
repo.git_add + git_commit + git_push	upload_file()، upload_folder()، create_commit()
repo.git_tag	create_tag
repo.git_branch	create_branch

فئة HfFolder

HfFolder كان يُستخدم لإدارة رمز وصول المستخدم. استخدم login() لحفظ رمز جديد، وlogout() لحذفه، وwhoami() للتحقق من المستخدم المرتبط بالرمز الحالي. أخيرًا، استخدم get_token() لاسترجاع رمز المستخدم داخل سكربت.

فئة InferenceApi

كانت InferenceApi فئة للتفاعل مع واجهة برمجة تطبيقات الاستدلال. يُوصى الآن باستخدام فئة InferenceClient بدلاً منها.

الميزات الأخرى غير المدعومة

تمت إزالة بعض الأساليب والمعاملات في الإصدار v1.0. أما تلك المذكورة أدناه فقد تم إيقاف استخدامها مسبقاً مع رسالة تحذير في الإصدارات v0.x.

• تمت إزالة constants.hf_cache_home. يُرجى استخدام HF_HOME بدلاً منه.
• تمت إزالة معاملات use_auth_token من جميع الطرق. يُرجى استخدام token بدلاً من ذلك.
• تمت إزالة طريقة get_token_permission.
• تمت إزالة طريقة update_repo_visibility. يُرجى استخدام update_repo_settings بدلاً منها.
• تمت إزالة معامل is_write_action من build_hf_headers وكذلك write_permission من login. وقد تم استبعاد مفهوم “إذن الكتابة” ولم يعد ذا صلة الآن، إذ أن الرموز الدقيقة (fine-grained tokens) هي الطريقة الموصى بها.
• تمت إعادة تسمية معامل new_session في login إلى skip_if_logged_in من أجل وضوح أفضل.
• تمت إزالة المعاملات resume_download وforce_filename وlocal_dir_use_symlinks من hf_hub_download وsnapshot_download.
• تمت إزالة المعاملات library وlanguage وtags وtask من list_models.

أوامر ذاكرة التخزين المؤقت لسطر الأوامر

أُعيد تصميم إدارة الكاش من سطر الأوامر ليتبع سير عمل مستوحى من Docker. تم إزالة huggingface-cli الذي تم إيقافه، ويستبدله hf (المُقدَّم في الإصدار v0.34) بواجهة سطر أوامر أوضح تعتمد على نمط المورد-الإجراء. كما تم إزالة الأوامر القديمة hf cache scan وhf cache delete في الإصدار v1.0، وتم استبدالها بالثلاثية الجديدة أدناه:

• hf cache ls يعرض إدخالات ذاكرة التخزين المؤقت في جدول موجز أو بصيغة JSON أو CSV. استخدم --revisions لفحص المراجعات الفردية، وأضف تعبيرات --filter مثل size>1GB أو accessed>30d، وادمجها مع --quiet عندما تحتاج إلى المعرّفات فقط.
• يحذف hf cache rm إدخالات الكاش المحددة. مرّر معرّفًا واحدًا أو أكثر للمستودعات (مثل model/bert-base-uncased) أو تجزئات المراجعات، وأضف اختياريًا --dry-run للمعاينة أو --yes لتخطي مطالبة التأكيد. يستبدل هذا كلا من سير عمل واجهة TUI التفاعلية و--disable-tui من الأمر السابق.
• hf cache prune يؤدي مهمة التنظيف الشائعة المتمثلة في حذف المراجعات غير المُشار إليها دفعة واحدة. أضف --dry-run أو --yes بنفس الطريقة المستخدمة مع hf cache rm.

أخيرًا، تم حذف الإضافة [cli] - أصبحت واجهة سطر الأوامر مدمجة الآن مع الحزمة الأساسية huggingface_hub.

دعم TensorFlow و Keras 2.x

تمت إزالة جميع الأكواد والتبعيات المتعلقة بـ TensorFlow في الإصدار v1.0. وتشمل التغييرات الكاسرة التالية:

• لم يعد huggingface_hub[tensorflow] اعتمادًا إضافيًا مدعومًا
• تمت إزالة دالتي الأداة split_tf_state_dict_into_shards وget_tf_storage_size.
• لم تعد الإصدارات tensorflow وfastai وfastcore مشمولة في الترويسات المدمجة.

تمت إزالة تكامل Keras 2.x أيضًا. ويشمل ذلك فئة KerasModelHubMixin وأدوات save_pretrained_keras وfrom_pretrained_keras وpush_to_hub_keras. يُعد Keras 2.x مكتبة قديمة وغير مدعومة. النهج الموصى به هو استخدام Keras 3.x الذي يتم تكامله بشكل وثيق مع Hub (أي أنه يحتوي على طريقة مدمجة لتحميل/دفع إلى Hub). إذا كنت لا تزال ترغب في العمل مع Keras 2.x، فيجب عليك خفض إصدار huggingface_hub إلى إصدار v0.x.

قيم الإرجاع لـ upload_file و upload_folder

تعيد الدالتان upload_file() وupload_folder() الآن عنوان URL للالتزام (commit) الذي تم إنشاؤه على Hub. في السابق، كانتا تعيدان عنوان URL للملف أو المجلد. يأتي هذا التغيير ليتوافق مع القيمة المُعادة للدوال create_commit() وdelete_file() وdelete_folder().

Update on GitHub