# AWS Trainium

[TorchNeuron](https://github.com/aws-neuron/torch-neuronx) هو واجهة PyTorch الأصلية لـ Trainium2 و Trainium3. يعمل Diffusers على هذه الوحدات من خلال الحزمة `torch_neuronx`، التي تسجّل جهازًا باسم `"neuron"`، مما يتيح تشغيل خطوط الأنابيب بنفس الكود المستخدم على أي جهاز آخر.

يتوفر وضعان للتنفيذ:

| الوضع | كيفية التفعيل | ملاحظات |
|---|---|---|
| مباشر | `pipe.to("neuron")` | عمليات تُنفَّذ واحدة تلو الأخرى، غير متزامنة |
| تجميع | `torch.compile(module, backend="neuron")` | تجميع الرسم البياني الكامل، الأشكال الثابتة |

اتبع [توثيق AWS Neuron](https://awsdocs-neuron.readthedocs-hosted.com/en/latest/) لإعداد حزمة Neuron SDK وتثبيت `torch_neuronx`. بمجرد التثبيت، يقوم `import torch` بتحميلها تلقائياً وتسجيل جهاز `"neuron"`، لذا فإن `pipe.to("neuron")` هو التغيير الوحيد المطلوب. أضف `import torch_neuronx` فقط إذا كنت قد عطّلت التحميل التلقائي للواجهة الخلفية باستخدام `TORCH_DEVICE_BACKEND_AUTOLOAD=0`.

في الوضع العاجل، يُجمَّع كل عملية في المرة الأولى التي تُنفَّذ فيها. أما في الوضع المُجمَّع، فإن الاستدعاء الأول يُجمِّع الرسم البياني. وكلا الوضعين يخزّنان صيغة التنفيذ المُجمَّعة لـ Neuron (NEFF) في `tmp/neff_cache` افتراضيًا، وتُفرَّغ تلك المجلدة عند إعادة التشغيل. اضبط `TORCH_NEURONX_NEFF_CACHE_DIR` على مجلد دائم للاحتفاظ بالذاكرة المؤقتة.

## الوضع الجشع

يتناسب نموذج FLUX.2-klein-4B مع وحدة NeuronCore واحدة، لذا انقل خط الأنابيب بالكامل إلى جهاز `"neuron"`.

```python
import torch

from diffusers import Flux2KleinPipeline

pipe = Flux2KleinPipeline.from_pretrained("black-forest-labs/FLUX.2-klein-4B", dtype=torch.bfloat16)
pipe.to("neuron")

image = pipe(
    prompt="a golden retriever surfing a wave, photorealistic",
    height=1024,
    width=1024,
    num_inference_steps=4,
).images[0]

image.save("output.png")
```

إذا كان النموذج كبيرًا جدًا ليُحمَّل على نواة NeuronCore واحدة، أو إذا كان لديك عدة نوى وتريد تقليل زمن الاستجابة، فقسّم النماذج على النوى بدلاً من ذلك. راجع قسم [التوازي على مستوى المصفوفات](#tensor-parallelism).

## وضع التجميع

يسجّل TorchNeuron `"neuron"` كاسم لخلفية `torch.compile`، لذا تُجمَّع المكونات كما تُجمَّع أي أهداف أخرى لـ`torch.compile`. تكون الاستدعاء الأول (إحماء) بطيئاً لأنه يقوم بالتجميع؛ أما الاستدعاءات اللاحقة ذات الأشكال نفسها فتعيد استخدام الرسم البياني المُجمَّع.

> [!IMPORTANT]
> يتطلب TorchNeuron *أشكالاً ثابتة*، لذا مرّر `dynamic=False`. أي قيمة جديدة لـ `height` أو `width` ستُعيد التجميع لذلك الشكل. أما الأشكال التي شوهدت مسبقاً فتُعاد استخدامها. تغيير `num_inference_steps` لا يُعيد التجميع.

```python
import torch

from diffusers import Flux2KleinPipeline

pipe = Flux2KleinPipeline.from_pretrained("black-forest-labs/FLUX.2-klein-4B", dtype=torch.bfloat16)
pipe.to("neuron")
pipe.transformer.compile(backend="neuron", fullgraph=True, dynamic=False)

# Warmup — triggers static graph compilation.
pipe(prompt="warmup", height=1024, width=1024, num_inference_steps=4)

# Later calls with the same shapes reuse the compiled graph.
image = pipe(
    prompt="a golden retriever surfing a wave, photorealistic",
    height=1024,
    width=1024,
    num_inference_steps=4,
).images[0]

image.save("output.png")
```

بالنسبة إلى نماذج Transformers التي تحتوي على كتل متكررة، استخدم `compile_repeated_blocks(...)` لتجميع تلك الكتل بشكل فردي. يتم إعادة استخدام هذا الكتل مما يقلل وقت التجميع بشكل كبير.

## توازي الموتر

اتبع دليل [التوازي على مستوى الموترات](../training/distributed_inference#tensor-parallelism) لتحميل النموذج، وخطط التقسيم، والقيود. لتكييف مثالها لمنصة Neuron، استبدل إعداد مجموعة العمليات والأجهزة الخاصة بـ CUDA بما يلي.

على Neuron، قم بتهيئة مجموعة العمليات باستخدام `backend="neuron"` وابنِ الشبكة باستخدام `DeviceMesh("neuron", ...)`.

```python
import torch
import torch.distributed as dist
from torch.distributed.device_mesh import DeviceMesh

from diffusers import TensorParallelConfig

dist.init_process_group(backend="neuron")
mesh = DeviceMesh("neuron", list(range(dist.get_world_size())))
device = torch.neuron.current_device()
parallel_config = TensorParallelConfig(mesh=mesh)
```

مرّر هذا `parallel_config` إلى [from_pretrained()](/docs/diffusers/main/ar/api/models/overview#diffusers.ModelMixin.from_pretrained) الخاص بالحوّال (transformer) واستخدم `device` لمكوّنات خط المعالجة المتبقية.

شغّل عملية واحدة لكل NeuronCore. اضبط `--nproc_per_node` على عدد NeuronCores التي تريد تقسيمها.

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