التثبيت

قبل أن تبدأ، ستحتاج إلى إعداد بيئتك من خلال تثبيت الحزم المناسبة.

يُختبر huggingface_hub على Python 3.10+.

التثبيت باستخدام pip

يُوصى بشدة بتثبيت huggingface_hub في بيئة افتراضية. إذا لم تكن على دراية بالبيئات الافتراضية في بايثون، فاطّلع على هذا الدليل. تُسهّل البيئة الافتراضية إدارة المشاريع المختلفة، وتساعد على تجنب مشاكل التوافق بين الاعتماديات.

ابدأ بإنشاء بيئة افتراضية في مجلد مشروعك:

python -m venv .venv

فعّل بيئة التشغيل الافتراضية. على أنظمة لينكس وماك أو إس:

source .venv/bin/activate

تفعيل بيئة افتراضية على نظام ويندوز:

.venv/Scripts/activate

الآن أنت مستعد لتثبيت huggingface_hub من سجل PyPi:

pip install --upgrade huggingface_hub

بعد الانتهاء، تأكد من أن فحص التثبيت يعمل بشكل صحيح.

تثبيت التبعيات الاختيارية

بعض تبعيات huggingface_hub هي اختيارية لأنها غير مطلوبة لتشغيل الميزات الأساسية لـ huggingface_hub. ومع ذلك، قد لا تكون بعض ميزات huggingface_hub متاحة إذا لم يتم تثبيت التبعيات الاختيارية.

يمكنك تثبيت التبعيات الاختيارية عبر pip:

# Install dependencies for both torch-specific and MCP-specific features.
pip install 'huggingface_hub[mcp,torch]'

فيما يلي قائمة التبعيات الاختيارية في huggingface_hub:

• fastai، torch: التبعيات اللازمة لتشغيل الميزات الخاصة بالإطار.
• dev: التبعيات المساهمة في المكتبة. تتضمن testing (لتشغيل الاختبارات)، وtyping (لتشغيل أداة فحص الأنواع)، وquality (لتشغيل أدوات التدقيق).

التثبيت من المصدر

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

ومع ذلك، هذا يعني أن إصدار main قد لا يكون دائمًا مستقرًا. نسعى جاهدين للحفاظ على تشغيل إصدار main، وعادةً ما يتم حل معظم المشكلات خلال بضع ساعات أو يوم واحد. إذا واجهت مشكلة، فيرجى فتح مشكلة (Issue) حتى نتمكن من إصلاحها بشكل أسرع!

pip install git+https://github.com/huggingface/huggingface_hub

عند التثبيت من المصدر، يمكنك أيضًا تحديد فرع معين. وهذا مفيد إذا كنت ترغب في اختبار ميزة جديدة أو إصلاح خطأ جديد لم يتم دمجه بعد:

pip install git+https://github.com/huggingface/huggingface_hub@my-feature-branch

بعد الانتهاء، تأكد من أن فحص التثبيت يعمل بشكل صحيح.

التثبيت القابل للتعديل

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

# First, clone repo locally
git clone https://github.com/huggingface/huggingface_hub.git

# Then, install with -e flag
cd huggingface_hub
pip install -e .

ستربط هذه الأوامر المجلد الذي استنسلت فيه المستودع بمسارات مكتبات Python الخاصة بك. سيبحث Python الآن داخل المجلد الذي استنسلت فيه بالإضافة إلى مسارات المكتبات المعتادة. على سبيل المثال، إذا كانت حزم Python لديك تُثبَّت عادةً في ./.venv/lib/python3.13/site-packages/، فسيقوم Python أيضاً بالبحث في المجلد الذي استنسلته ./huggingface_hub/.

تثبيت واجهة سطر أوامر Hugging Face

استخدم مُثبِّلاتنا من سطر واحد لإعداد واجهة hf السطرية دون المساس ببيئة بايثون الخاصة بك:

على macOS و Linux:

curl -LsSf https://hf.co/cli/install.sh | bash

على نظام ويندوز:

powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

لتحديث تثبيت قائم، شغّل hf update — حيث يكتشف الطريقة التي تم بها تثبيت hf (المثبّت المستقل، أو Homebrew، أو pip) وينفّذ الأمر المطابق.

التثبيت باستخدام conda

إذا كنت أكثر إلمامًا به، يمكنك تثبيت huggingface_hub باستخدام قناة conda-forge:

conda install -c conda-forge huggingface_hub

بعد الانتهاء، تأكد من أن فحص التثبيت يعمل بشكل صحيح.

التحقق من التثبيت

بعد التثبيت، تحقق من أن huggingface_hub يعمل بشكل صحيح عن طريق تنفيذ الأمر التالي:

python -c "from huggingface_hub import model_info; print(model_info('gpt2'))"

ستجلب هذه الأوامر معلومات من Hub حول نموذج gpt2. يجب أن يبدو الناتج على النحو التالي:

Model Name: gpt2
Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space']
Task: text-generation

قيود ويندوز

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

• يعتمد نظام التخزين المؤقت في huggingface_hub على الروابط الرمزية لتخزين الملفات التي تم تنزيلها من Hub بكفاءة. على نظام Windows، يجب عليك تفعيل وضع المطور أو تشغيل سكربتك بصلاحيات المسؤول لتفعيل الروابط الرمزية. إذا لم تكن مفعّلة، فإن نظام التخزين المؤقت لا يزال يعمل ولكن بطريقة غير مُحسّنة. يرجى قراءة قسم قيود التخزين المؤقت لمزيد من التفاصيل.
• Filepaths on the Hub can have special characters (e.g. "path/to?/my/file"). Windows is more restrictive on special characters which makes it impossible to download those files on Windows. Hopefully this is a rare case. Please reach out to the repo owner if you think this is a mistake or to us to figure out a solution.

الخطوات التالية

بمجرد تثبيت huggingface_hub بشكل صحيح على جهازك، قد ترغب في إعداد متغيرات البيئة أو الاطلاع على أحد أدلةنا للبدء.