# التثبيت

يعمل Transformers مع [PyTorch](https://pytorch.org/get-started/locally/). وقد تم اختباره على Python 3.11+ وPyTorch 2.6+.

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

[uv](https://docs.astral.sh/uv/) هو مدير حزم ومشاريع بايثون فائق السرعة مبني على لغة Rust، ويتطلب افتراضياً [بيئة افتراضية](https://docs.astral.sh/uv/pip/environments/) لإدارة المشاريع المختلفة وتجنب مشاكل التوافق بين الاعتماديات.

يمكن استخدامه كبديل مباشر لـ [pip](https://pip.pypa.io/en/stable/)، لكن إذا كنت تفضل استخدام pip، فاحذف `uv` من الأوامر أدناه.

> [!TIP]
> راجع وثائق [التثبيت](https://docs.astral.sh/uv/guides/install-python/) الخاصة بـ uv لتثبيت uv.

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

```bash
uv venv .env
source .env/bin/activate
```

## Python

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

[uv](https://docs.astral.sh/uv/) هو مدير حزم ومشاريع بلغة بايثون سريع مبني على لغة روست.

لتثبيت Transformers مع PyTorch لبطاقة NVIDIA GPU (CUDA)، ثبّت برامج تشغيل CUDA المناسبة لـ [PyTorch](https://pytorch.org/get-started/locally).

نفّذ الأمر أدناه للتحقق مما إذا كان نظامك يكتشف معالج رسومي من NVIDIA.

```bash
nvidia-smi
```

```bash
uv pip install "transformers[torch]"
```

لتثبيت Transformers مع PyTorch على أجهزة NVIDIA Spark (مثل حاسوب RTX Spark المحمول) الذي يعمل بنظام ARM64، ثبّت PyTorch من فهرس NVIDIA PyPI. تتطلب هذه الأجهزة إصدارات PyTorch الخاصة بـ ARM64 من NVIDIA، وهي غير متوفرة في فهرس PyPI الافتراضي أو في فهرس عجلات PyTorch القياسي.

نفّذ الأمر أدناه للتحقق مما إذا كان نظامك يكتشف معالج رسومي من NVIDIA.

```bash
nvidia-smi
```

قم بتثبيت PyTorch من فهرس NVIDIA PyPI، ثم ثبّت Transformers.

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

لتثبيت نسخة Transformers تعمل على المعالج فقط، نفّذ الأمر التالي.

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

لتثبيت Transformers مع PyTorch لبطاقة الرسوميات من Intel (XPU)، ثبّت [مُشغِّلات Intel GPU (XPU) المناسبة لـ PyTorch](https://www.intel.com/content/www/us/en/developer/articles/tool/pytorch-prerequisites-for-intel-gpu/2-13.html) وأضف عنوان فهرس PyTorch الخاص ببطاقة الرسوميات من Intel (XPU).

بعد تثبيت برامج التشغيل، نفّذ الأمر أدناه [للتحقق مما إذا كان نظامك يكتشف معالج رسومي من Intel](https://dgpu-docs.intel.com/driver/verification.html).

```bash
xpu-smi
```

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

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

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

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

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

السلبي هو أن أحدث إصدار قد لا يكون دائمًا مستقرًا. إذا واجهت أي مشاكل، يرجى فتح [قضية على GitHub](https://github.com/huggingface/transformers/issues) حتى نتمكن من إصلاحها في أقرب وقت ممكن.

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

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

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

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

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

يُعدّ [التثبيت القابل للتعديل](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs) مفيداً إذا كنت تقوم بالتطوير محلياً باستخدام Transformers. فهو يربط نسختك المحلية من Transformers بمستودع [المستودع](https://github.com/huggingface/transformers) الخاص بـ Transformers بدلاً من نسخ الملفات. وتُضاف هذه الملفات إلى مسار الاستيراد في Python.

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

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

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

```bash
cd ~/transformers/
git pull
```

## conda

[conda](https://docs.conda.io/projects/conda/en/stable/#) هو مدير حزم لا يعتمد على لغة برمجية محددة. قم بتثبيت Transformers من قناة [conda-forge](https://anaconda.org/conda-forge/transformers) في البيئة الافتراضية التي أنشأتها حديثًا.

```bash
conda install conda-forge::transformers
```

## الإعداد

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

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

عند تحميل نموذج مُدرَّب مسبقًا باستخدام [from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.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](https://hf.co/docs/huggingface_hub/package_reference/environment_variables#hfhubcache) (الافتراضي)
2. [HF_HOME](https://hf.co/docs/huggingface_hub/package_reference/environment_variables#hfhome)
3. [XDG_CACHE_HOME](https://hf.co/docs/huggingface_hub/package_reference/environment_variables#xdgcachehome) + `/huggingface` (فقط إذا لم يتم تعيين `HF_HOME`)

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

يتطلب استخدام Transformers في بيئة غير متصلة أو محمية بجدار ناري وجود الملفات المُحمّلة والمخزّنة مؤقتًا مسبقًا. حمّل مستودع نموذج من Hub باستخدام طريقة [snapshot_download](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/file_download#huggingface_hub.snapshot_download).

> [!TIP]
> راجع دليل [تنزيل الملفات من Hub](https://hf.co/docs/huggingface_hub/guides/download) لمعرفة المزيد من الخيارات لتنزيل الملفات من Hub. يمكنك تنزيل الملفات من إصدارات محددة، وتنزيلها من سطر الأوامر، وحتى تصفية الملفات التي تريد تنزيلها من مستودع.

```py
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()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained).

```py
from transformers import LlamaForCausalLM

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

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