# AMD GPU

تعمل وحدات معالجة الرسوميات [AMD Instinct](https://www.amd.com/en/products/accelerators/instinct.html) (سلاسل MI200 وMI300 وMI350) و[Radeon](https://www.amd.com/en/products/graphics/desktops/radeon.html) على PyTorch عبر [ROCm](https://rocm.docs.amd.com/)، وهو حزمة برمجيات وحدات معالجة الرسوميات من AMD. يستخدم إصدار PyTorch المبني على ROCm [HIP](https://rocm.docs.amd.com/projects/HIP/en/latest/what_is_hip.html)، وهو واجهة برمجة تشبه CUDA من AMD، لعرض وحدات معالجة الرسوميات من AMD عبر واجهة `torch.cuda`. سلسلة الأجهزة هي `cuda`، لذا فإن الكود المكتوب لوحدات معالجة الرسوميات من NVIDIA يعمل دون أي تغيير. يتحقق Transformers من `torch.version.hip` وقت التشغيل للتمييز بين النوعين، ويوجّه نوى الانتباه ونوى Hub إلى الإصدارات المخصصة لـ AMD.

## التثبيت

قم بتثبيت ROCm من صورة Docker الخاصة بـ [huggingface/transformers-pytorch-amd-gpu](https://hub.docker.com/r/huggingface/transformers-pytorch-amd-gpu). تتضمن هذه الصورة نسخة ROCm من PyTorch، ونسخة من `flash-attn` مخصصة لبطاقات MI300 وMI350 الرسومية (`gfx942` و`gfx950`)، بالإضافة إلى تثبيت Transformers من المصدر.

```bash
docker run -it --device=/dev/kfd --device=/dev/dri --group-add video \
    --ipc=host --shm-size 16G \
    huggingface/transformers-pytorch-amd-gpu
```

`--device=/dev/kfd` و `--device=/dev/dri` تُتيح الوصول إلى معالجات AMD الرسومية داخل الحاوية. ثبّت [kernels](https://github.com/huggingface/kernels) داخل الحاوية من أجل [use Hub kernels](#use-hub-kernels).

```bash
pip install "transformers[kernels]"
```

للتثبيت على نظامك الخاص بدلاً من ذلك، اختر ROCm في [محدد تثبيت PyTorch](https://pytorch.org/get-started/locally/) وتأكد من أن إصدار ROCm من العجلة مدعوم من قِبل برنامج تشغيلك.

تحقق من أن PyTorch يرى وحدات معالجة الرسوميات من AMD.

```py
import torch

print(torch.version.hip, torch.cuda.is_available(), torch.cuda.device_count())
print(torch.cuda.get_device_properties(0).gcnArchName)
```

```txt
7.2.53211 True 2
gfx942:sramecc+:xnack-
```

`torch.version.hip` تكون `None` في بناء PyTorch الخاص بـ CUDA. يبلّغ `gcnArchName` عن معمارية وحدة معالجة الرسوميات، على سبيل المثال `gfx942` لـ MI300، و`gfx950` لـ MI350، و`gfx1151` لـ Ryzen AI Max (Strix Halo).

## اختيار وحدات معالجة الرسوميات وترتيبها

استخدم `HIP_VISIBLE_DEVICES` لاختيار وحدات معالجة الرسوميات وتحديد ترتيبها. اضبطه على نفس سطر الأوامر الخاص بالتنفيذ.

```cli
HIP_VISIBLE_DEVICES=0,2 torchrun trainer-program.py ...
```

يرى PyTorch وحدات معالجة الرسوميات 0 و2 فقط، وهي مُرسَلة إلى `cuda:0` و`cuda:1`. يقوم `ROCR_VISIBLE_DEVICES` بتصفية وحدات معالجة الرسوميات على مستوى أدنى في المكدس، وغالباً ما يُعيّنه مجدولو العناقيد. إذا تم تعيين كلاهما، فإن `HIP_VISIBLE_DEVICES` يُفهرس وحدات معالجة الرسوميات التي تبقى مرئية بواسطة `ROCR_VISIBLE_DEVICES`.

استخدم `rocm-smi` أو `amd-smi` لعرض قائمة ببطاقات الرسوميات ومفاتيحها.

## تشغيل الاستدلال

يتعرّف [Pipeline](/docs/transformers/main/ar/main_classes/pipelines#transformers.Pipeline) و`device_map="auto"` على معالجات AMD الرسومية ويضعان النموذج على `cuda` تلقائيًا. يمكنك أيضًا تمرير `device_map="cuda"` أو `device_map="cuda:1"` بشكل صريح.

```py
from transformers import AutoModelForCausalLM, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-0.6B")
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B", dtype="bfloat16", device_map="auto"
)

inputs = tokenizer("The French Bread Law states", return_tensors="pt").to(model.device)
output = model.generate(**inputs, do_sample=False, max_new_tokens=50)
print(tokenizer.decode(output[0], skip_special_tokens=True))
```

```txt
The French Bread Law states that the French government must provide a certain amount of bread for the citizens of the country. The law is passed by the French parliament. The French parliament is a body of the French government. The French government is a body of the French state. The
```

## اختر واجهة خلفية للانتباه

اضبط واجهة الانتباه باستخدام `attn_implementation` عند تحميل النموذج، حيث ينطبق ذلك على كل من الاستدلال والتدريب. الخيار الافتراضي هو SDPA ويعمل على كل معالج رسومي من AMD مدعوم بواسطة PyTorch. كما يتوفر خياران لـ FlashAttention.

| `attn_implementation` | يتطلب | ملاحظات |
|---|---|---|
| `"sdpa"` | – | افتراضي. |
| `"flash_attention_2"` | [flash-attn](https://github.com/Dao-AILab/flash-attention#amd-rocm-support) المصمّم لـ ROCm، أو [kernels](https://github.com/huggingface/kernels) | يستخدم حزمة `flash-attn` عند تثبيتها. يدعم واجهة Composable Kernel (CK) الافتراضية معالجات MI200 وMI300 وMI355 وRDNA 3/4، ويتضمن [صورة Docker](#installation) هذه الحزمة على MI300 أو MI350. وإلا، يتم تحميل [amd/aiter-flash-attn](https://huggingface.co/kernels/amd/aiter-flash-attn) من Hub. |
| `"flash_attention_3"` | [النواة](https://github.com/huggingface/kernels) | يحمّل [amd/aiter-flash-attn](https://huggingface.co/kernels/amd/aiter-flash-attn)، وهو نواة FlashAttention مُجمّعة مسبقاً من مكتبة [AITER](https://github.com/ROCm/aiter) الخاصة بـ AMD. لا يتطلب أي عملية تجميع. |

```py
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    dtype="bfloat16",
    device_map="auto",
    attn_implementation="flash_attention_3",
)
```

على ROCm، يحل `flash_attention_3` إلى نواة AITER ويسجّل ما يلي. يستخدم Transformers حالياً الاسم المستعار `kernels-community/aiter-flash-attn`، والذي يعيد التوجيه إلى `amd/aiter-flash-attn`. تشير الرسالة إلى حزمة FlashAttention-3، لذا تظهر حتى عند تثبيت `flash_attention_2`.

```txt
You do not have `flash_attn` installed, using `kernels-community/aiter-flash-attn` from the `kernels` library instead!
```

يمكنك أيضًا تمرير مستودع النواة مباشرةً باستخدام `attn_implementation="kernels-community/aiter-flash-attn"`. راجع [واجهات الانتباه الخلفية](./attention_interface) لمعرفة كيفية اختيار الواجهات الخلفية.

## استخدام نواة Hub

اضبط `use_kernels=True` في [from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) لاستبدال الطبقات المدعومة بنوى مُحسَّنة من Hub. يكتشف Transformers بيئة ROCm ويختار بناء AMD لكل طبقة، مثل [amd/aiter-rope](https://huggingface.co/kernels/amd/aiter-rope) للتضمينات الدورانية و[kernels-community/liger-kernels](https://huggingface.co/kernels/kernels-community/liger-kernels) لـ RMSNorm. عند كتابة [KernelConfig](/docs/transformers/main/ar/main_classes/kernels#transformers.KernelConfig) مخصص، استخدم `"rocm"` كمفتاح للجهاز للخرائط الخاصة بـ AMD.

```py
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B", dtype="bfloat16", device_map="auto", use_kernels=True
)
```

تعمل نواة Hub بشكل رئيسي على تسريع مرحلة التعبئة (prefill) والدفعات الكبيرة. قم بإجراء اختبارات أداء على حمل العمل الخاص بك قبل تفعيلها لفك الترميز في الدفعات الصغيرة. راجع [تحميل النوى](./kernel_doc/loading_kernels) للاطلاع على التخصيص الكامل.

## كمّ النماذج

تشمل الطرق المدعومة على ROCm [AWQ](./quantization/awq) و[GPT-QModel](./quantization/gptq) و[compressed-tensors](./quantization/compressed_tensors) و[Quark](./quantization/quark) من AMD. كما يحظى [bitsandbytes](./quantization/bitsandbytes) بدعم جزئي. تدعم وحدات معالجة الرسومات MI300 والأحدث منها تنسيق FP8 بشكل أصلي. راجع [جدول التوافق](./quantization/overview) للحصول على القائمة الكاملة.

## التدريب باستخدام Trainer

يتعرّف [TrainingArguments](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments) على معالجات AMD الرسومية ويضبط الجهاز على `cuda` تلقائيًا.

```py
from transformers import TrainingArguments

training_args = TrainingArguments(
    output_dir="./outputs",
    bf16=True,
)
```

### التدريب الموزّع

يأتي بناء PyTorch الخاص بـ ROCم مع RCCL، وهو تنفيذ AMD لواجهة NCCL، لذا تعمل واجهة `nccl` الخلفية، و`torchrun`، و[FSDP](./fsdp)، و[DeepSpeed](./main_classes/deepspeed)، وواجهة Transformers الموزعة دون أي تغييرات.

```py
import torch
from transformers import AutoModelForCausalLM, DistributedConfig

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-1.7B",
    dtype=torch.bfloat16,
    distributed_config=DistributedConfig(tp_size=2, fsdp_size=4),
)
```

```bash
torchrun --nproc_per_node=8 train.py
```

راجع [توازي الموترات](./tensor_parallelism)، و[توازي الخبراء](./expert_parallelism)، و[FSDP](./fsdp) لمعرفة الخيارات المتاحة.

## القيود

- `CodeCarbonCallback` غير متوافق مع ROCm. اضبط `report_to` في [TrainingArguments](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments) لاستبعاد `codecarbon`.
- تعتمد طرق التكميم المميزة بعلامة 🔴 لـ ROCm في [جدول التوافق](./quantization/overview) على نوى CUDA فقط، وتفشل في التحميل على وحدات معالجة الرسوميات من AMD.

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

- اقرأ [وثائق ROCm](https://rocm.docs.amd.com/) لإعداد برنامج التشغيل وPyTorch.
- تصفّح حزم ROCm في منظمات [AMD](https://huggingface.co/amd) و[kernels-community](https://huggingface.co/kernels-community).
- اقرأ [تحميل النوى](./kernel_doc/loading_kernels) لتخصيص النوى التي تحل محل طبقات معينة.