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

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

إذا لم تكن على دراية بمتغيرات البيئة، فإليك مقالات عامة عنها على macOS وLinux وعلى Windows.

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

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

عام

HF_INFERENCE_ENDPOINT

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

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

HF_HOME

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

يكون الافتراضي "~/.cache/huggingface" ما لم يتم تعيين XDG_CACHE_HOME.

HF_HUB_CACHE

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

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

HF_XET_CACHE

لإعداد المكان الذي يخزّن فيه Xet ذاكرة التخزين المؤقت للتجزئات وبيانات التحميل المرحلية محليًا. راجع ذاكرة التخزين المؤقت في Xet لمزيد من التفاصيل.

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

HF_ASSETS_CACHE

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

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

HF_TOKEN

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

لمزيد من التفاصيل حول المصادقة، راجع هذا القسم.

HF_TOKEN_PATH

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

HF_HUB_VERBOSITY

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

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

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

HF_HUB_ETAG_TIMEOUT

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

HF_HUB_DOWNLOAD_TIMEOUT

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

Xet

متغيرات بيئة Xet الأخرى

• HF_HUB_DISABLE_XET
• HF_XET_CACHE
• HF_XET_HIGH_PERFORMANCE
• HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY

HF_XET_CHUNK_CACHE_SIZE_BYTES

لم يعد لهذا المتغير أي تأثير. لم يعد hf_xet يستخدم ذاكرة تخزين مؤقت محلية للقطع لتنزيلات الملفات، وإعداد هذا المتغير لا يُفعّلها. راجع xet-core#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، فسيتم رفع استثناء OfflineModeIsEnabled.

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

إذا كنت ترغب في التحقق مما إذا كان الوضع غير المتصل مفعلاً أم لا، يمكنك استخدام أداة المساعدة is_offline_mode().

HF_HUB_DISABLE_IMPLICIT_TOKEN

لا يُشترط المصادقة لكل طلب إلى Hub. على سبيل المثال، لا يتطلب طلب تفاصيل عن نموذج "gpt2" المصادقة. ومع ذلك، إذا كان المستخدم مسجلاً الدخول، فإن السلوك الافتراضي هو إرسال الرمز دائماً لتسهيل تجربة المستخدم (تجنّب استلام خطأ HTTP 401 Unauthorized) عند الوصول إلى المستودعات الخاصة أو المحمية. ولحماية الخصوصية، يمكنك تعطيل هذا السلوك عن طريق تعيين HF_HUB_DISABLE_IMPLICIT_TOKEN=1. في هذه الحالة، لن يُرسل الرمز إلا لاستدعاءات «صلاحيات الكتابة» (مثال: إنشاء 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 لتعطيل هذا التحذير.

لمزيد من التفاصيل، راجع قيود ذاكرة التخزين المؤقت.

HF_HUB_DISABLE_EXPERIMENTAL_WARNING

بعض ميزات huggingface_hub تجريبية. وهذا يعني أنه يمكنك استخدامها، لكننا لا نضمن صيانتها في المستقبل. على وجه الخصوص، قد نقوم بتحديث واجهة برمجة التطبيقات (API) أو سلوك هذه الميزات دون أي دورة إهمال (deprecation cycle). يتم إطلاق رسالة تحذير عند استخدام ميزة تجريبية لتنبيهك إلى ذلك. إذا كنت مرتاحًا لتصحيح أي مشكلات محتملة باستخدام ميزة تجريبية، يمكنك تعيين 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 في حال عدم توفرها. لا يُصدر هذا الفحص سوى تلميح، ولا يلمس أبداً مجلدات مهاراتك.

قبل تشغيل امتداد سطر الأوامر مثبّت، يتحقق (بحد أقصى مرة واحدة كل 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، فيُرجى النظر في فتح مشكلة وإدراج معلومات التشخيص لمساعدتنا على فهم سبب عدم عمل Xet لديك.

HF_HUB_ENABLE_HF_TRANSFER

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

HF_HUB_DISABLE_SHARED_BLOBS

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

HF_XET_HIGH_PERFORMANCE

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

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

للمزيد من المعلومات حول فوائد تخزين Xet وhf_xet، راجع هذا القسم.

HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY

لم يعد هذا المتغير مستخدماً. فمنذ hf_xet 1.3.0، تُكتب الملفات دائماً إلى القرص المحلي بشكل تسلسلي (انظر كاتب الملفات في v1.3.0).

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

لإتقان جميع متغيرات البيئة ضمن منظومة 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.

XDG_CACHE_HOME

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

هذه هي الطريقة الافتراضية لتكوين المكان الذي يجب كتابة البيانات غير الأساسية (المخزنة مؤقتًا) الخاصة بالمستخدم عليه في أجهزة لينكس.

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

Update on GitHub