# متغيرات البيئة

يمكن تكوين `huggingface_hub` باستخدام متغيرات البيئة.

إذا لم تكن على دراية بمتغيرات البيئة، فإليك مقالات عامة عنها [على macOS وLinux](https://linuxize.com/post/how-to-set-and-list-environment-variables-in-linux/) وعلى [Windows](https://phoenixnap.com/kb/windows-set-environment-variable).

ستوجّهك هذه الصفحة عبر جميع متغيرات البيئة الخاصة بـ`huggingface_hub` ومعناها.

> [!TIP]
> تُقرأ جميع متغيرات البيئة عند استيراد `huggingface_hub`. لن تُؤخذ أي تعديلات تُجرى بعد ذلك في الاعتبار. تأكد من ضبط متغيرات البيئة الخاصة بك قبل استيراد `huggingface_hub`.

## عام

### HF_INFERENCE_ENDPOINT

لإعداد عنوان URL الأساسي لواجهة برمجة تطبيقات الاستدلال. قد ترغب في تعيين هذا المتغير إذا كانت مؤسستك تشير إلى بوابة واجهة برمجة التطبيقات (API Gateway) بدلاً من الإشارة مباشرةً إلى واجهة برمجة تطبيقات الاستدلال.

الافتراضي هو `"https://api-inference.huggingface.co"`.

### HF_HOME

لإعداد المكان الذي سيخزّن فيه `huggingface_hub` البيانات محليًا. على وجه التحديد، سيتم تخزين رمزك والمخزن المؤقت في هذا المجلد.

يكون الافتراضي `"~/.cache/huggingface"` ما لم يتم تعيين [XDG_CACHE_HOME](#xdgcachehome).

### HF_HUB_CACHE

لإعداد المكان الذي سيتم فيه تخزين المستودعات من Hub مؤقتًا محليًا (النماذج، مجموعات البيانات والمساحات).

يكون الافتراضي `"$HF_HOME/hub"` (على سبيل المثال `"~/.cache/huggingface/hub"` افتراضيًا).

### HF_XET_CACHE

لإعداد المكان الذي يخزّن فيه Xet ذاكرة التخزين المؤقت للتجزئات وبيانات التحميل المرحلية محليًا. راجع [ذاكرة التخزين المؤقت في Xet](../guides/manage-cache#xet-caching) لمزيد من التفاصيل.

يكون الافتراضي `"$HF_HOME/xet"` (على سبيل المثال `"~/.cache/huggingface/xet"` افتراضيًا).

### HF_ASSETS_CACHE

لإعداد المكان الذي سيتم فيه تخزين [الأصول](../guides/manage-cache#caching-assets) التي تنشئها المكتبات التابعة محليًا. يمكن أن تكون هذه الأصول بيانات مُعالجة مسبقًا، أو ملفات تم تنزيلها من GitHub، أو سجلات، وما إلى ذلك.

يكون الافتراضي `"$HF_HOME/assets"` (على سبيل المثال `"~/.cache/huggingface/assets"` افتراضيًا).

### HF_TOKEN

لإعداد رمز وصول المستخدم (User Access Token) للمصادقة على Hub. إذا تم تعيينه، فستستبدل هذه القيمة الرمز المخزّن على الجهاز (في `$HF_TOKEN_PATH` أو `"$HF_HOME/token"` إذا لم يُعتمد الأول).

لمزيد من التفاصيل حول المصادقة، راجع [هذا القسم](../quick-start#authentication).

### HF_TOKEN_PATH

لإعداد المكان الذي يجب أن يخزّن فيه `huggingface_hub` رمز الوصول للمستخدم. القيمة الافتراضية هي `"$HF_HOME/token"` (على سبيل المثال `~/.cache/huggingface/token` افتراضيًا).

### HF_HUB_VERBOSITY

حدد مستوى التفصيل الخاص بسجّال `huggingface_hub`. يجب أن يكون أحد القيم التالية: `{"debug", "info", "warning", "error", "critical"}`.

الافتراضي هو `"warning"`.

لمزيد من التفاصيل، راجع [مرجع التسجيل](../package_reference/utilities#huggingface_hub.utils.logging.get_verbosity).

### HF_HUB_ETAG_TIMEOUT

قيمة عددية صحيحة لتحديد عدد الثواني التي يجب انتظارها للحصول على استجابة الخادم عند جلب أحدث البيانات الوصفية من المستودع قبل تنزيل ملف. إذا انتهت مهلة الطلب، فسيستخدم `huggingface_hub` الملفات المخزنة محليًا بشكل افتراضي. يؤدي ضبط قيمة أدنى إلى تسريع سير العمل للأجهزة ذات الاتصال البطيء والتي لديها ملفات مخزنة مسبقًا. أما القيمة الأعلى فتضمن نجاح استدعاء البيانات الوصفية في حالات أكثر. القيمة الافتراضية هي 10 ثوانٍ.

### HF_HUB_DOWNLOAD_TIMEOUT

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

## Xet 

### متغيرات بيئة Xet الأخرى
* [`HF_HUB_DISABLE_XET`](../package_reference/environment_variables#hfhubdisablexet)
* [`HF_XET_CACHE`](../package_reference/environment_variables#hfxetcache)
* [`HF_XET_HIGH_PERFORMANCE`](../package_reference/environment_variables#hfxethighperformance)
* [`HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY`](../package_reference/environment_variables#hfxetreconstructwritesequentially)

### HF_XET_CHUNK_CACHE_SIZE_BYTES

لم يعد لهذا المتغير أي تأثير. لم يعد `hf_xet` يستخدم ذاكرة تخزين مؤقت محلية للقطع لتنزيلات الملفات، وإعداد هذا المتغير لا يُفعّلها. راجع [xet-core#715](https://github.com/huggingface/xet-core/issues/715) للتفاصيل.

### HF_XET_SHARD_CACHE_SIZE_LIMIT

لضبط حجم ذاكرة التخزين المؤقت لشظايا Xet محليًا. يؤدي زيادة هذا الحجم إلى تحسين كفاءة الرفع، حيث لا يتم إعادة رفع المقاطع المشار إليها في ملفات الشظايا المخزنة مؤقتًا. لاحظ أن الحد الأقصى الافتراضي المرني على الأرجح كافٍ لمعظم أحمال العمل.

القيمة الافتراضية هي `16000000000` (16 جيجابايت).

### HF_XET_NUM_CONCURRENT_RANGE_GETS

لم يعد هذا المتغير مستخدماً. فمنذ الإصدار 1.3.0 من `hf_xet`، يتم التحكم في التزامن أثناء التنزيل بشكل تكيفي.

## القيم المنطقية

تتوقع متغيرات البيئة التالية قيمة منطقية. يُعتبر المتغير `True` إذا كانت قيمته أحد القيم `{"1", "ON", "YES", "TRUE"}` (بغض النظر عن حالة الأحرف). وتُعتبر أي قيمة أخرى (أو غير معرّفة) `False`.

### HF_DEBUG

إذا تم ضبطه، يُضبط مستوى التسجيل لسجل `huggingface_hub` على DEBUG. بالإضافة إلى ذلك، سيتم تسجيل جميع الطلبات التي تُرسلها مكتبات HF كأوامر cURL مكافئة لتسهيل التصحيح وإعادة الإنتاج.

### HF_HUB_OFFLINE

إذا تم ضبطه، فلن تتم أي استدعاءات HTTP إلى Hugging Face Hub. إذا حاولت تنزيل الملفات، فسيتم الوصول إلى الملفات المخزنة مؤقتًا فقط. إذا لم يتم اكتشاف ملف مخزن مؤقت، فسيتم رفع خطأ. هذا مفيد في حال كان شبكتك بطيئة ولا يهمك امتلاك أحدث إصدار من ملف.

إذا تم تعيين `HF_HUB_OFFLINE=1` كمتغير بيئة وقمت باستدعاء أي طريقة من طرق [HfApi](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_api#huggingface_hub.HfApi)، فسيتم رفع استثناء [OfflineModeIsEnabled](/docs/huggingface_hub/v2.4.0/ar/package_reference/utilities#huggingface_hub.errors.OfflineModeIsEnabled).

**ملاحظة:** حتى إذا كان أحدث إصدار من ملف ما مخزّنًا مؤقتًا، فإن استدعاء `hf_hub_download` لا يزال يُطلق طلب HTTP للتحقق من عدم توفر إصدار أحدث. ضبط `HF_HUB_OFFLINE=1` سيتخطى هذا الاستدعاء مما يسرّع وقت التحميل لديك.

إذا كنت ترغب في التحقق مما إذا كان الوضع غير المتصل مفعلاً أم لا، يمكنك استخدام أداة المساعدة [is_offline_mode()](/docs/huggingface_hub/v2.4.0/ar/package_reference/utilities#huggingface_hub.is_offline_mode).

### HF_HUB_DISABLE_IMPLICIT_TOKEN

لا يُشترط المصادقة لكل طلب إلى Hub. على سبيل المثال، لا يتطلب طلب تفاصيل عن نموذج `"gpt2"` المصادقة. ومع ذلك، إذا كان المستخدم [مسجلاً الدخول](../package_reference/login)، فإن السلوك الافتراضي هو إرسال الرمز دائمًا لتسهيل تجربة المستخدم (تجنب الحصول على HTTP 401 Unauthorized) عند الوصول إلى المستودعات الخاصة أو المحمية. من أجل الخصوصية، يمكنك تعطيل هذا السلوك عن طريق تعيين `HF_HUB_DISABLE_IMPLICIT_TOKEN=1`. في هذه الحالة، لن يُرسل الرمز إلا لاستدعاءات "write-access" (مثال: إنشاء commit).

**ملاحظة:** تعطيل الإرسال الضمني للرمز يمكن أن يؤدي إلى آثار جانبية غير متوقعة. على سبيل المثال، إذا أردت عرض جميع النماذج على Hub، فلن يتم إدراج نماذجك الخاصة. سيتعين عليك تمرير معامل `token=True` بشكل صريح في سكربت الخاص بك.

### HF_HUB_DISABLE_PROGRESS_BARS

بالنسبة إلى المهام التي تستغرق وقتاً طويلاً، يعرض `huggingface_hub` شريط تقدم افتراضياً (باستخدام tqdm). يمكنك تعطيل جميع أشرطة التقدم دفعة واحدة عن طريق تعيين `HF_HUB_DISABLE_PROGRESS_BARS=1`.

### HF_HUB_DISABLE_SYMLINKS

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

مثال على حالة استخدام هو استخدام محرك أقراص شبكة مشترك (مثل NAS) كـ `HF_HUB_CACHE` عبر أجهزة تعمل بأنظمة تشغيل مختلفة. الروابط الرمزية التي تُنشأ على Linux ليست قابلة للتصفح دائمًا على Windows، مما يؤدي إلى أخطاء. ضبط `HF_HUB_DISABLE_SYMLINKS=1` يتجنب هذه المشكلة على حساب إزالة التكرار في مساحة القرص.

### HF_HUB_DISABLE_SYMLINKS_WARNING

إذا كنت تستخدم جهازًا يعمل بنظام ويندوز، يُوصى بتفعيل وضع المطوّر أو تشغيل `huggingface_hub` في وضع المسؤول. وإلا، لن يتمكن `huggingface_hub` من إنشاء روابط رمزية في نظام التخزين المؤقت لديك. ستتمكن من تنفيذ أي سكربت، لكن تجربة المستخدم ستتدهور لأن بعض الملفات الضخمة قد تنتهي مكررة على القرص الصلب. يتم إطلاق رسالة تحذير لتنبيهك إلى هذا السلوك. اضبط `HF_HUB_DISABLE_SYMLINKS_WARNING=1` لتعطيل هذا التحذير.

لمزيد من التفاصيل، راجع [قيود ذاكرة التخزين المؤقت](../guides/manage-cache#limitations).

### HF_HUB_DISABLE_EXPERIMENTAL_WARNING

بعض ميزات `huggingface_hub` تجريبية. وهذا يعني أنه يمكنك استخدامها، لكننا لا نضمن صيانتها في المستقبل. على وجه الخصوص، قد نقوم بتحديث واجهة برمجة التطبيقات (API) أو سلوك هذه الميزات دون أي دورة إهمال. يتم إطلاق رسالة تحذير عند استخدام ميزة تجريبية لتنبيهك إلى ذلك. إذا كنت مرتاحًا لتصحيح أي مشكلات محتملة تنشأ عن استخدام ميزة تجريبية، يمكنك تعيين `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1` لتعطيل التحذير.

إذا كنت تستخدم ميزة تجريبية، فيرجى إعلامنا! يمكن أن يساعدنا ملاحظاتك في تصميمها وتحسينها.

### HF_HUB_DISABLE_TELEMETRY

بشكل افتراضي، يتم جمع بعض البيانات بواسطة مكتبات HF (`transformers`، `datasets`، `gradio`،..) لمراقبة الاستخدام، وتصحيح المشكلات، والمساعدة في تحديد أولويات الميزات. تُعرّف كل مكتبة سياستها الخاصة (أي الاستخدامات المراد مراقبتها)، لكن التنفيذ الأساسي يتم في `huggingface_hub` (انظر `send_telemetry`).

يمكنك تعيين `HF_HUB_DISABLE_TELEMETRY=1` كمتغير بيئة لتعطيل قياسات الأداء على مستوى النظام بالكامل.

### HF_HUB_DISABLE_UPDATE_CHECK

بشكل افتراضي، يتحقق خط الأوامر `hf` من PyPI عن إصدار أحدث عند بدء التشغيل (مرة واحدة على الأكثر كل 24 ساعة) ويُطبع تحذيراً صفراء من سطر واحد إلى stderr عند توفر إصدار أحدث، مقترحاً `hf update`. التحقّق لا يُنفذ أي إجراء على الإصدارات التجريبية وقبل الإصدار.

كما يتحقق (مرة واحدة على الأكثر كل 24 ساعة، محلياً بالكامل) مما إذا كانت مهارة `hf-cli` مثبتة ومولّدة بواسطة النسخة قيد التشغيل، ويقترح `hf skills add` / `hf skills update` في حال عدم توفرها. لا يُصدر هذا الفحص سوى تلميح، ولا يلمس أبداً مجلدات مهاراتك.

قبل تشغيل [امتداد سطر الأوامر](../guides/cli-extensions) مثبّت، يتحقق (بحد أقصى مرة واحدة كل 24 ساعة لكل امتداد) مما إذا كان هناك التزام جديد أحدث متاح على GitHub، ويقترح `hf extensions update <name>` في حال وجوده. يستخدم `hf extensions list` نفس التحقق لعمود `LATEST`.

اضبط `HF_HUB_DISABLE_UPDATE_CHECK=1` لتخطي هذه الطلبات وكتم جميع هذه التلميحات. مفيد في بيئات CI دون اتصال أو عندما تفضل مخرجات shell أكثر هدوءاً.

### HF_HUB_DISABLE_XET

اضبطه لتعطيل استخدام `hf-xet`، حتى لو كان متاحًا في بيئة Python الخاصة بك. وذلك لأن `hf-xet` سيُستخدم تلقائيًا إذا تم العثور عليه، مما يتيح تعطيل استخدامه بشكل صريح. إذا كنت تقوم بتعطيل Xet، فيُرجى النظر في [فتح مشكلة وإدراج معلومات التشخيص](https://github.com/huggingface/xet-core?tab=readme-ov-file#issues-diagnostics--debugging) لمساعدتنا على فهم سبب عدم عمل Xet لديك.

### HF_HUB_ENABLE_HF_TRANSFER

> [!WARNING]
> هذا متغير بيئة مُتقادم. الآن، وبما أن Hugging Face Hub يعمل بالكامل عبر وحدة تخزين Xet، فإن جميع عمليات نقل الملفات تتم عبر حزمة `hf-xet` الثنائية. توفر هذه الحزمة نقلًا فعالًا باستخدام استراتيجية إزالة التكرار القائمة على المقاطع، وتتكامل بسلاسة مع `huggingface_hub`. وهذا يعني أن `hf_transfer` لم يعد قابلاً للاستخدام. إذا كنت مهتمًا بأداء أعلى، فتفضل بالاطلاع على [قسم `HF_XET_HIGH_PERFORMANCE`](#hf_xet_high_performance)

### HF_HUB_DISABLE_SHARED_BLOBS

اضبطه على `1` لتعطيل مخزن blobs المشترك على مستوى الكاش. بشكل افتراضي، تُخزَّن ملفات Xet التي تم تنزيلها بنجاح في `<CACHE_DIR>/blobs/<prefix>/<xet_hash>` وتُربط عبر روابط رمزية إلى كاش المستودعات، بحيث تُخزَّن الملفات المتطابقة على القرص مرة واحدة فقط عبر المستودعات ويمكن إعادة استخدامها دون الحاجة إلى إعادة الجلب. هذه التحسينات مفعّلة بشكل افتراضي، لكنها تُعطَّل إذا لم يكن Xet متاحًا (مثلًا إذا تم ضبط `HF_HUB_DISABLE_XET=1`) أو إذا لم تُدعَم الروابط الرمزية محليًا. في تلك الحالات، يعود النظام بصمت إلى التخزين المحلي العادي للمستودع. راجع [دليل التخزين المؤقت](../guides/manage-cache#shared-blobs-across-repos) للتفاصيل.

### HF_XET_HIGH_PERFORMANCE

اضبط `hf-xet` للعمل بإعدادات أعلى لتعظيم موارد الشبكة والقرص الصلب على الجهاز. سيحاول تفعيل وضع الأداء العالي إشباع عرض نطاق الشبكة لهذا الجهاز واستخدام جميع أنوية المعالج المركزي للأنشطة المتوازية للرفع/التنزيل.

فكّر في هذا على أنه مشابه لمتغير البيئة القديم `HF_HUB_ENABLE_HF_TRANSFER=1` لكنه مطبّق على `hf-xet`.

للمزيد من المعلومات حول فوائد تخزين Xet و`hf_xet`، راجع هذا [القسم](https://huggingface.co/docs/hub/xet/index).

### HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY

لم يعد هذا المتغير مستخدماً. فمنذ `hf_xet` 1.3.0، تُكتب الملفات دائماً إلى القرص المحلي بشكل تسلسلي (انظر [كاتب الملفات في v1.3.0](https://github.com/huggingface/xet-core/blob/v1.3.0/file_reconstruction/src/data_writer/data_writer.rs#L76-L91)).

## متغيرات البيئة غير المدعومة

لإتقان جميع متغيرات البيئة ضمن منظومة Hugging Face، تم تصنيف بعض المتغيرات كمهجورة. وعلى الرغم من أنها لا تزال تعمل، إلا أنها لم تعد لها الأولوية على بدائلها. توضح الجدول التالي المتغيرات المهجورة وبدائلها المقابلة:

| متغير غير مستخدم         | الاستبدال        |
| --------------------------- | ------------------ |
| `HUGGINGFACE_HUB_CACHE`     | `HF_HUB_CACHE`     |
| `HUGGINGFACE_ASSETS_CACHE`  | `HF_ASSETS_CACHE`  |
| `HUGGING_FACE_HUB_TOKEN`    | `HF_TOKEN`         |

## من أدوات خارجية

بعض متغيرات البيئة ليست خاصة بـ`huggingface_hub` لكنها تُؤخذ في الاعتبار عند ضبطها.

### DO_NOT_TRACK

قيمة منطقية. مكافئة لـ `HF_HUB_DISABLE_TELEMETRY`. عند ضبطها على true، يتم تعطيل القياس عن بُعد بشكل شامل في منظومة Hugging Face الخاصة بلغة بايثون (`transformers`، `diffusers`، `gradio`، إلخ). راجع https://donottrack.sh/ لمزيد من التفاصيل.

### NO_COLOR

قيمة منطقية. عند ضبطها، لن يطبع `hf` CLI أي ألوان ANSI. راجع [no-color.org](https://no-color.org/).

### XDG_CACHE_HOME

يُستخدم فقط عندما لا يكون `HF_HOME` مضبوطًا!

هذه هي الطريقة الافتراضية لتكوين المكان الذي يجب كتابة [البيانات غير الأساسية (المخزنة مؤقتًا) الخاصة بالمستخدم](https://wiki.archlinux.org/title/XDG_Base_Directory) عليه في أجهزة لينكس.

إذا لم يتم تعيين `HF_HOME`، فسيكون المسار الافتراضي للمنزل `"$XDG_CACHE_HOME/huggingface"` بدلاً من `"~/.cache/huggingface"`.