إرجاع المستوى الحالي لسجل الجذر الخاص بـ HuggingFace Hub.

تتوفر مستويات التسجيل التالية في HuggingFace Hub:

• huggingface_hub.logging.CRITICAL, huggingface_hub.logging.FATAL
• huggingface_hub.logging.ERROR
• huggingface_hub.logging.WARNING, huggingface_hub.logging.WARN
• huggingface_hub.logging.INFO
• huggingface_hub.logging.DEBUG

يحدد مستوى المسجّل الجذري (root logger) الخاص بـ HuggingFace Hub.

يحدد مستوى التفصيل إلى logging.INFO.

يحدد مستوى التفصيل إلى logging.DEBUG.

يحدد مستوى التفصيل إلى logging.WARNING.

يحدد مستوى التفصيل إلى logging.ERROR.

تعطيل انتشار مخرجات سجلات المكتبة. لاحظ أن انتشار السجلات معطّل افتراضيًا.

تفعيل انتشار مخرجات سجلات المكتبة. يُرجى تعطيل المُعالِج الافتراضي الخاص بـ HuggingFace Hub لمنع تسجيل السجلات مرتين إذا تم تكوين المُسجِّل الجذري.

يعيد مسجلاً (logger) بالاسم المحدد. لا يُفترض أن يصل مستخدمو المكتبة إلى هذه الدالة مباشرة.

>>> from huggingface_hub import logging

>>> logger = logging.get_logger(__name__)
>>> logging.set_verbosity_info()

تحقق مما إذا كانت أشرطة التقدم معطّلة على مستوى النظام أو لمجموعة محددة.

تعيد هذه الدالة ما إذا كانت أشرطة التقدم معطّلة لمجموعة معينة أو على مستوى النظام ككل. تتحقق أولاً من متغير البيئة HF_HUB_DISABLE_PROGRESS_BARS، ثم من الإعدادات البرمجية.

تعطيل أشرطة التقدم إما على مستوى النظام أو لمجموعة محددة.

تحديث حالة أشرطة التقدم بناءً على اسم المجموعة. إذا لم يُقدَّم اسم للمجموعة، يتم تعطيل جميع أشرطة التقدم. تحترم هذه العملية إعداد متغير البيئة HF_HUB_DISABLE_PROGRESS_BARS.

يعمل كاستدعاء عادي وكإدارة سياق: disable_progress_bars() # يُعطّل حتى استدعاء enable_progress_bars() with disable_progress_bars(): # يُعطّل ضمن الكتلة، ويُعيد التفعيل عند الخروج …

فعّل أشرطة التقدم إما على مستوى النظام أو لمجموعة محددة.

تقوم هذه الدالة بتفعيل أشرطة التقدم للمجموعة المحددة أو على مستوى النظام إذا لم تُحدد مجموعة. وتخضع هذه العملية لإعداد البيئة HF_HUB_DISABLE_PROGRESS_BARS.

اضبط مصنع عميل HTTP الذي سيستخدمه huggingface_hub.

مصنع العميل هو طريقة تُرجع كائن httpx2.Client. عند أول استدعاء لـ get_session()، سيُستخدم مصنع العميل لإنشاء كائن httpx2.Client جديد سيُشارك بين جميع الاستدعاءات التي يجريها huggingface_hub.

قد يكون ذلك مفيدًا إذا كنت تشغّل سكربتاتك في بيئة محددة تتطلب تكوينًا مخصصًا (مثل وكيل مخصص أو شهادات).

استخدم get_session() للحصول على httpx2.Client مُهيأ بشكل صحيح.

احصل على كائن httpx2.Client باستخدام مصنع النقل من المستخدم.

هذا العميل مشترك بين جميع الاستدعاءات التي يجريها huggingface_hub. لذلك، يجب ألا تُغلقه يدويًا.

استخدم set_client_factory() لتخصيص httpx2.Client.

أغلق httpx2.Client العام المستخدم بواسطة huggingface_hub.

إذا أُغلق عميل، فسيتم إنشاؤه مرة أخرى عند الاستدعاء التالي لـ get_session().

قد يكون مفيدًا إذا تم تحديث شهادة SSL، على سبيل المثال.

اضبط مصنع عميل HTTP غير المتزامن الذي سيستخدمه huggingface_hub.

مصنع العميل غير المتزامن (async client factory) هو طريقة تُرجع كائن httpx2.AsyncClient. قد يكون هذا مفيدًا إذا كنت تشغّل سكربتاتك في بيئة محددة تتطلب تكوينًا مخصصًا (مثل وكيل مخصص أو شهادات). استخدم get_async_session() للحصول على httpx2.AsyncClient مُهيأ بشكل صحيح.

على عكس httpx2.Client الذي يُشارَك بين جميع الاستدعاءات التي يجريها huggingface_hub، فإن httpx2.AsyncClient لا يُشارَك. يُوصى باستخدام مدير سياق غير متزامن (async context manager) لضمان إغلاق العميل بشكل صحيح عند الخروج من السياق.

أعد كائن httpx2.AsyncClient باستخدام مصنع النقل من المستخدم.

استخدم set_async_client_factory() لتخصيص httpx2.AsyncClient.

على عكس httpx2.Client الذي يُشارَك بين جميع الاستدعاءات التي يجريها huggingface_hub، فإن httpx2.AsyncClient لا يُشارَك. يُوصى باستخدام مدير سياق غير متزامن (async context manager) لضمان إغلاق العميل بشكل صحيح عند الخروج من السياق.

الإصدار الداخلي لـ response.raise_for_status() الذي سيُحسّن خطأ HTTPError المحتمل. الاستثناء المُثار سيكون نسخة من HfHubHTTPError.

This helper is meant to be the unique method to raise_for_status when making a call to the Hugging Face Hub.

يُستدعى عند فشل الطلب:

• RepositoryNotFoundError إذا تعذّر العثور على المستودع الذي سيتم التنزيل منه. قد يكون السبب في ذلك عدم وجوده، أو أن repo_type غير مضبوط بشكل صحيح، أو أن المستودع private ولا تملك صلاحية الوصول إليه.
• GatedRepoError إذا كان المستودع موجودًا لكنه محمي (gated) والمستخدم غير مدرج في القائمة المصرّح لها.
• RevisionNotFoundError إذا كان المستودع موجودًا لكن تعذّر العثور على المراجعة.
• EntryNotFoundError إذا كان المستودع موجودًا لكن تعذّر العثور على العنصر (مثل الملف المطلوب).
• BadRequestError إذا فشل الطلب مع خطأ HTTP 400 BadRequest.
• HfHubHTTPError إذا فشل الطلب لسبب غير مدرج أعلاه.

يعيد ما إذا كنا في وضع عدم الاتصال بالنسبة إلى Hub.

عند تفعيل الوضع دون اتصال، ستُطلق جميع طلبات HTTP المُرسلة باستخدام get_session استثناءً من نوع OfflineModeIsEnabled.

from huggingface_hub import is_offline_mode

def list_files(repo_id: str):
    if is_offline_mode():
        ... # list files from local cache (degraded experience but still functional)
    else:
        ... # list files from Hub (complete experience)

HTTPError لتوريثها لأي خطأ HTTP مخصص يُستدعى في HF Hub.

تُحوَّل أي HTTPError على الأقل إلى HfHubHTTPError. وإذا أرسل الخادم بعض المعلومات، فسيتم إضافتها إلى رسالة الخطأ.

تفاصيل مضافة:

• يُستخرج معرّف الطلب من الترويسات حسب ترتيب الأولوية: “X-Request-Id”، “X-Amzn-Trace-Id”، “X-Amz-Cf-Id”.
• رسالة خطأ الخادم من الترويسة X-Error-Message.
• رسالة خطأ الخادم إذا تم العثور على واحدة في جسم الاستجابة.

    import httpx2
    from huggingface_hub.utils import get_session, hf_raise_for_status, HfHubHTTPError

    response = get_session().post(...)
    try:
        hf_raise_for_status(response)
    except HfHubHTTPError as e:
        print(str(e)) # formatted message
        e.request_id, e.server_message # details returned by server

        # Complete the error message with additional information once it's raised
        e.append_to_message("
ate_commit` expects the repository to exist.")
        raise

تُستدعى عند محاولة الوصول إلى عنوان URL على hf.co باسم مستودع غير صالح، أو باسم مستودع خاص لا يملك المستخدم صلاحية الوصول إليه.

>>> from huggingface_hub import model_info
>>> model_info("<non_existent_repository>")
(...)
huggingface_hub.errors.RepositoryNotFoundError: 401 Client Error. (Request ID: PvMw_VjBMjVdMz53WKIzP)

Repository Not Found for url: https://huggingface.co/api/models/%3Cnon_existent_repository%3E.
Please make sure you specified the correct `repo_id` and `repo_type`.
If the repo is private, make sure you are authenticated and your token has the required permissions.
Invalid username or password.

تُستدعى عند محاولة الوصول إلى مستودع محمي لا يوجد المستخدم في قائمة المصرّح لهم.

ملاحظة: مشتقة من RepositoryNotFoundError لضمان التوافق مع الإصدارات السابقة.

>>> from huggingface_hub import model_info
>>> model_info("<gated_repository>")
(...)
huggingface_hub.errors.GatedRepoError: 403 Client Error. (Request ID: ViT1Bf7O_026LGSQuVqfa)

Cannot access gated repo for url https://huggingface.co/api/models/ardent-figment/gated-model.
Access to model ardent-figment/gated-model is restricted and you are not in the authorized list.
Visit https://huggingface.co/ardent-figment/gated-model to ask for access.

تُستدعى عند محاولة الوصول إلى عنوان URL على hf.co يحتوي على مستودع صالح لكن إصدارًا (revision) غير صالح.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', 'config.json', revision='<non-existent-revision>')
(...)
huggingface_hub.errors.RevisionNotFoundError: 404 Client Error. (Request ID: Mwhe_c3Kt650GcdKEFomX)

Revision Not Found for url: https://huggingface.co/bert-base-cased/resolve/%3Cnon-existent-revision%3E/config.json.

تُستدعى بواسطة HfApi.resolve_revision() عندما لا يمكن تحديد المراجعة إلى تجزئة التزامن: تعذّر الوصول إلى Hub (وضع عدم الاتصال، خطأ في الاتصال، انتهاء المهلة، توقف Hub، …) ولم يتم العثور على إدخال مطابق في ذاكرة التخزين المؤقت المحلية.

تُستدعى بواسطة hf_raise_for_status عندما يعيد الخادم خطأ HTTP 400.

>>> resp = httpx2.post("hf.co/api/check", ...)
>>> hf_raise_for_status(resp, endpoint_name="check")
huggingface_hub.errors.BadRequestError: Bad request for check endpoint: {details} (Request ID: XXX)

تُستدعى عند عدم العثور على الإدخال، سواء محلياً أو عن بُعد.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-existent-file>')
(...)
huggingface_hub.errors.RemoteEntryNotFoundError (...)
>>> hf_hub_download('bert-base-cased', '<non-existent-file>', local_files_only=True)
(...)
huggingface_hub.utils.errors.LocalEntryNotFoundError (...)

تُستدعى عند محاولة الوصول إلى عنوان URL على hf.co يحتوي على مستودع ورسم صحيحين، لكن اسم ملف غير صالح.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-existent-file>')
(...)
huggingface_hub.errors.EntryNotFoundError: 404 Client Error. (Request ID: 53pNl6M0MxsnG5Sw8JA6x)

Entry Not Found for url: https://huggingface.co/bert-base-cased/resolve/main/%3Cnon-existent-file%3E.

تُستدعى عند محاولة الوصول إلى ملف أو لقطة غير موجودة على القرص عند تعطيل الشبكة أو عدم توفرها (مشكلة اتصال). قد يكون العنصر موجودًا على Hub.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-cached-file>',  local_files_only=True)
(...)
huggingface_hub.errors.LocalEntryNotFoundError: Cannot find the requested files in the disk cache and outgoing traffic has been disabled. To enable hf.co look-ups and downloads online, set 'local_files_only' to False.

تُستدعى بواسطة snapshot_download() عندما لا يمكن الوصول إلى Hub (سواءً بسبب عدم الاتصال، أو مشكلة في الاتصال، أو local_files_only=True) ويُعرف أن لقطة التخزين المؤقت غير مكتملة: حيث تكون بعض الملفات المدرجة في قائمة شجرة التخزين المؤقت للمستودع مفقودة من اللقطة المحلية.

هذا صنف فرعي من LocalEntryNotFoundError من أجل التوافق مع الإصدارات السابقة.

يحتوي السمة snapshot_path على المسار إلى اللقطة المحلية غير المكتملة، مما يتيح لمكتبة لاحقة تحديد أحدث الملفات المخزنة مؤقتًا على الرغم من كونها معروفة بأنها غير مكتملة.

يُستدعى بواسطة get_cached_repo_tree() عندما لا يكون هناك فهرس شجرة مخزّن مسبقًا للمراجعة المطلوبة.

يتم ملء قائمة الشجرة كنتيجة ثانوية لاستدعاء snapshot_download().

تُستدعى عند إرسال طلب مع تعيين HF_HUB_OFFLINE=1 كمتغير بيئة.

يرسل بيانات التلميتري التي تساعد في تتبع استخدام مكتبات HF المختلفة.

يساعدنا هذا البيانات الاستخدام في تصحيح المشكلات وتحديد أولويات الميزات الجديدة. ومع ذلك، نفهم أن ليس كل شخص يرغب في مشاركة معلومات إضافية، ونحترم خصوصيتك. يمكنك تعطيل جمع بيانات القياس عن بُعد عن طريق تعيين HF_HUB_DISABLE_TELEMETRY=1 كمتغير بيئة. كما يتم تعطيل القياس عن بُعد في وضع عدم الاتصال (أي عند تعيين HF_HUB_OFFLINE=1).

تُنفَّذ عملية جمع بيانات القياس في خيط منفصل لتقليل الأثر على المستخدم.

>>> from huggingface_hub.utils import send_telemetry

# Send telemetry without library information
>>> send_telemetry("ping")

# Send telemetry to subtopic with library information
>>> send_telemetry("gradio/local_link", library_name="gradio", library_version="3.22.1")

# Send telemetry with additional data
>>> send_telemetry(
...     topic="examples",
...     library_name="transformers",
...     library_version="4.26.0",
...     user_agent={"pipeline": "text_classification", "framework": "flax"},
... )

تحقق من القيم المستلمة كحجة لأي طريقة عامة في huggingface_hub.

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

المُتحقِّقون:

• validate_repo_id(): يجب أن يكون repo_id إما "repo_name" أو "namespace/repo_name". يشير Namespace إلى اسم مستخدم أو منظمة.
• ~utils.smoothly_deprecate_legacy_arguments: تجاهل proxies عند تنزيل الملفات (يجب ضبطها على مستوى النظام).

>>> from huggingface_hub.utils import validate_hf_hub_args

>>> @validate_hf_hub_args
... def my_cool_method(repo_id: str):
...     print(repo_id)

>>> my_cool_method(repo_id="valid_repo_id")
valid_repo_id

>>> my_cool_method("other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

>>> my_cool_method(repo_id="other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

استثناء عام يُرميه مُتحقّقات huggingface_hub.

يرث من ValueError.

تحقق من أن repo_id صالح.

لا يُقصد بهذا أن يحلّ محلّ التحقق السليم الذي يتم إجراؤه على Hub، بل لتجنّب عدم الاتساق المحلي قدر الإمكان (مثال: تمرير repo_type في repo_id أمر ممنوع).

القواعد:

• بين 1 و96 حرفًا.
• إما “repo_name” أو “namespace/repo_name”
• [a-zA-Z0-9] أو ”-” أو ”_” أو ”.”
• يُمنع استخدام “—” و “..”

صالح: "foo"، "foo/bar"، "123"، "Foo-BAR_foo.bar123"

غير صالح: "datasets/foo/bar"، ".repo_id"، "foo--bar"، "foo.git"

>>> from huggingface_hub.utils import validate_repo_id
>>> validate_repo_id(repo_id="valid_repo_id")
>>> validate_repo_id(repo_id="other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

تمت مناقشته في https://github.com/huggingface/huggingface_hub/issues/1008. في moon-landing (مستودع داخلي):

• https://github.com/huggingface/moon-landing/blob/main/server/lib/Names.ts#L27
• https://github.com/huggingface/moon-landing/blob/main/server/views/components/NewRepoForm/NewRepoForm.svelte#L138

إلغاء استخدام الحجج القديمة بسلاسة في قاعدة أكواد huggingface_hub.

تتجاهل هذه الدالة بعض المعاملات غير المدعومة بعد من kwargs وتحذّر المستخدم من أنها مُتجاهلة. الهدف هو تجنّب كسر الكود الحالي مع توجيه المستخدم إلى الطريقة الجديدة للقيام بالأشياء.

قائمة بالحجج غير المدعومة:

• proxies: لإعداد الوكلاء، يجب على المستخدم إما استخدام متغير البيئة HTTP_PROXY أو تكوين httpx2.Client يدويًا باستخدام الدالة set_client_factory().

  في huggingface_hub 0.x، كان proxies قاموسًا يُمرَّر مباشرة إلى requests.request. منذ huggingface_hub 1.x، لم تعد الوكلاء proxies لكل طلب مدعومة. وبشكل خاص، لم يعد من الممكن تكوين الوكلاء على أساس كل طلب على حدة. الحل هو تكوينها عالميًا باستخدام دالة set_client_factory() أو باستخدام متغير البيئة HTTP_PROXY.

  لمزيد من التفاصيل، راجع:

  • https://httpx2.pydantic.dev/advanced/proxies/

• resume_download: تم إيقاف استخدامه دون بديل. huggingface_hub يستأنف التنزيلات دائمًا كلما كان ذلك ممكنًا.

• force_filename: تم إيقاف استخدامه دون بديل. يكون اسم الملف دائمًا مطابقًا لذلك الموجود على Hub.

• local_dir_use_symlinks: تم إيقاف استخدامه دون بديل. لم يعد تنزيل الملفات إلى مجلد محلي يستخدم الروابط الرمزية.