التثبيت

يعمل Transformers مع PyTorch. وقد تم اختباره على Python 3.11+ وPyTorch 2.6+.

بيئة افتراضية

uv هو مدير حزم ومشاريع بايثون فائق السرعة مبني على لغة Rust، ويتطلب افتراضياً بيئة افتراضية لإدارة المشاريع المختلفة وتجنب مشاكل التوافق بين الاعتماديات.

يمكن استخدامه كبديل مباشر لـ pip، لكن إذا كنت تفضل استخدام pip، فاحذف uv من الأوامر أدناه.

راجع وثائق التثبيت الخاصة بـ uv لتثبيت uv.

أنشئ بيئة افتراضية لتثبيت Transformers فيها.

uv venv .env
source .env/bin/activate

Python

قم بتثبيت Transformers باستخدام الأمر التالي.

uv هو مدير حزم ومشاريع بلغة بايثون سريع مبني على لغة روست.

nvidia-smi

uv pip install "transformers[torch]"

nvidia-smi

uv pip install torch --index-url https://pypi.nvidia.com
uv pip install transformers

uv pip install torch --index-url https://download.pytorch.org/whl/cpu
uv pip install transformers

xpu-smi

uv pip install "transformers[torch]" --extra-index-url https://download.pytorch.org/whl/xpu

اختبر ما إذا كان التثبيت ناجحًا باستخدام الأمر التالي. يجب أن يعيد تسمية (label) ودرجة (score) للنص المقدم.

python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))"
[{'label': 'POSITIVE', 'score': 0.9998704791069031}]

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

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

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

قم بالتثبيت من المصدر باستخدام الأمر التالي.

uv pip install git+https://github.com/huggingface/transformers

تحقق من نجاح التثبيت باستخدام الأمر أدناه. يجب أن يعيد وسمًا (label) ودرجة (score) للنص المقدم.

python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))"
[{'label': 'POSITIVE', 'score': 0.9998704791069031}]

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

يُعدّ التثبيت القابل للتعديل مفيدًا إذا كنت تقوم بالتطوير محليًا باستخدام Transformers. فهو يربط نسختك المحلية من Transformers بمستودع Transformers repository بدلاً من نسخ الملفات. تُضاف هذه الملفات إلى مسار الاستيراد (import path) في Python.

git clone https://github.com/huggingface/transformers.git
cd transformers
uv pip install -e .

يجب عليك الاحتفاظ بمجلد Transformers المحلي لمواصلة استخدامه.

حدّث نسختك المحلية من Transformers بأحدث التغييرات في المستودع الرئيسي باستخدام الأمر التالي.

cd ~/transformers/
git pull

conda

conda هو مدير حزم لا يعتمد على لغة برمجية محددة. قم بتثبيت Transformers من قناة conda-forge في البيئة الافتراضية التي أنشأتها حديثًا.

conda install conda-forge::transformers

الإعداد

بعد التثبيت، يمكنك تحديد موقع ذاكرة التخزين المؤقت لـ Transformers أو إعداد المكتبة للاستخدام دون اتصال.

مجلد التخزين المؤقت

عند تحميل نموذج مُدرَّب مسبقًا باستخدام from_pretrained()، يتم تنزيل النموذج من Hub وتخزينه مؤقتًا محليًا.

عند تمرير تجزئة التزامن (commit hash)، يستخدم Transformers ذاكرة التخزين المؤقت المحلية لملفات ذلك التزامن ولا يعيد التحقق من Hub لكل ملف على حدة (بما في ذلك الملفات المعروفة بأنها مفقودة). هذا هو السلوك الافتراضي عند عدم تحديد أي مراجعة (revision).

عند تمرير فرع أو وسم، يتواصل Transformers مع Hub مرة واحدة عند بدء التحميل لاختيار الالتزام، ثم يستخدم ذاكرة التخزين المؤقت بالطريقة نفسها لملفات ذلك الالتزام.

المجلد الافتراضي المحدد بواسطة متغير البيئة الخاص بالصدفة HF_HUB_CACHE هو ~/.cache/huggingface/hub. في نظام Windows، يكون المجلد الافتراضي C:\Users\username\.cache\huggingface\hub.

قم بتخزين نموذج في مجلد مختلف عن طريق تغيير المسار في متغيرات البيئة التالية (مرتبة حسب الأولوية).

1. HF_HUB_CACHE (الافتراضي)
2. HF_HOME
3. XDG_CACHE_HOME + /huggingface (فقط إذا لم يتم تعيين HF_HOME)

الوضع دون اتصال

يتطلب استخدام Transformers في بيئة غير متصلة أو محمية بجدار ناري وجود الملفات المُحمّلة والمخزّنة مؤقتًا مسبقًا. حمّل مستودع نموذج من Hub باستخدام طريقة snapshot_download.

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

from huggingface_hub import snapshot_download

snapshot_download(repo_id="meta-llama/Llama-2-7b-hf", repo_type="model")

اضبط متغير البيئة HF_HUB_OFFLINE=1 لمنع استدعاءات HTTP إلى Hub عند تحميل نموذج.

خيار آخر لتحميل الملفات المخزنة مؤقتًا فقط هو تعيين local_files_only=True في from_pretrained().

from transformers import LlamaForCausalLM

model = LlamaForCausalLM.from_pretrained("./path/to/local/directory", local_files_only=True)

يمكن لوضع عدم الاتصال (أو local_files_only=True) أن يحوّل فرعًا أو وسمًا إلى التزامن إذا كانت عملية تحميل سابقة عبر الإنترنت قد حفظت تلك العلاقة في ذاكرة التخزين المؤقت. أما إذا لم تُحفظ العلاقة من قبل، فإن Transformers يحتفظ بالفرع أو الوسم الذي طلبته ويواصل عملية التحميل الاعتيادية دون اتصال. وستحصل على نفس نتائج التخزين المؤقت أو أخطاء الملفات المفقودة كما في التحميل الاعتيادي دون اتصال.