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

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

يهدف هذا الدليل إلى مساعدتك في نقل كودك الحالي إلى الإصدار الجديد. إذا كانت لديك أي أسئلة أو ملاحظات، يرجى إعلامنا من خلال [فتح مشكلة على GitHub](https://github.com/huggingface/huggingface_hub/issues).

## Python 3.9+

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

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

يستخدم الآن مكتبة `huggingface_hub` [`httpx`](https://www.python-httpx.org/) بدلاً من `requests` لإجراء طلبات HTTP. تم إجراء هذا التغيير لتحسين الأداء وللدعم المتساوي لكل من الطلبات المتزامنة وغير المتزامنة. لذلك، تم التخلي عن كل من تبعيات `requests` و`aiohttp`.

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

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

- **إعدادات الوكيل**: لم تعد وكلاء "لكل طريقة" مدعومة. يجب إعداد الوكلاء على مستوى النظام باستخدام متغيرات البيئة `HTTP_PROXY` و`HTTPS_PROXY`.
- **خادم HTTP مخصص**: تم حذف الدالة `configure_http_backend`. يجب عليك الآن استخدام [set_client_factory()](/docs/huggingface_hub/main/ar/package_reference/utilities#huggingface_hub.set_client_factory) و [set_async_client_factory()](/docs/huggingface_hub/main/ar/package_reference/utilities#huggingface_hub.set_async_client_factory) لإعداد عملاء HTTP.
- **معالجة الأخطاء**: لم تعد أخطاء HTTP موروثة من `requests.HTTPError`، بل أصبحت موروثة من `httpx.HTTPError`. ننصح بالالتقاط [HfHubHTTPError](/docs/huggingface_hub/main/ar/package_reference/utilities#huggingface_hub.errors.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()](/docs/huggingface_hub/main/ar/package_reference/utilities#huggingface_hub.set_async_client_factory).

لمزيد من التفاصيل، يمكنك الاطلاع على [PR #3328](https://github.com/huggingface/huggingface_hub/pull/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`](../package_reference/environment_variables) بدلاً من ذلك.

## فئة `Repository`

تمت إزالة فئة `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()](/docs/huggingface_hub/main/ar/package_reference/hf_api#huggingface_hub.HfApi.upload_file)، [upload_folder()](/docs/huggingface_hub/main/ar/package_reference/hf_api#huggingface_hub.HfApi.upload_folder)، [create_commit()](/docs/huggingface_hub/main/ar/package_reference/hf_api#huggingface_hub.HfApi.create_commit) |
| `repo.git_tag`                             | `create_tag`                                          |
| `repo.git_branch`                          | `create_branch`                                       |

## فئة `HfFolder`

`HfFolder` كان يُستخدم لإدارة رمز وصول المستخدم. استخدم [login()](/docs/huggingface_hub/main/ar/package_reference/authentication#huggingface_hub.login) لحفظ رمز جديد، و[logout()](/docs/huggingface_hub/main/ar/package_reference/authentication#huggingface_hub.logout) لحذفه، و[whoami()](/docs/huggingface_hub/main/ar/package_reference/hf_api#huggingface_hub.HfApi.whoami) للتحقق من المستخدم المرتبط بالرمز الحالي. أخيرًا، استخدم `get_token()` لاسترجاع رمز المستخدم داخل سكربت.

## فئة `InferenceApi`

كانت `InferenceApi` فئة للتفاعل مع واجهة برمجة تطبيقات الاستدلال. يُوصى الآن باستخدام فئة [InferenceClient](/docs/huggingface_hub/main/ar/package_reference/inference_client#huggingface_hub.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) بواجهة سطر أوامر أوضح تعتمد على نمط المورد-الإجراء. كما تم في الإصدار v1.0 إزالة الأوامر القديمة `hf cache scan` و`hf cache delete`، واستُبدلت بالثلاثية الجديدة أدناه:

- `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()](/docs/huggingface_hub/main/ar/package_reference/hf_api#huggingface_hub.HfApi.upload_file) و[upload_folder()](/docs/huggingface_hub/main/ar/package_reference/hf_api#huggingface_hub.HfApi.upload_folder) الآن عنوان URL للالتزام (commit) الذي تم إنشاؤه على Hub. في السابق، كانتا تعيدان عنوان URL للملف أو المجلد. يأتي هذا التغيير ليتوافق مع القيمة المُعادة للدوال [create_commit()](/docs/huggingface_hub/main/ar/package_reference/hf_api#huggingface_hub.HfApi.create_commit) و[delete_file()](/docs/huggingface_hub/main/ar/package_reference/hf_api#huggingface_hub.HfApi.delete_file) و[delete_folder()](/docs/huggingface_hub/main/ar/package_reference/hf_api#huggingface_hub.HfApi.delete_folder).