diffusers/main/ar/optimization/attention_backends.md

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

موزّع الانتباه هو ميزة تجريبية. يرجى فتح مشكلة إذا كان لديك أي ملاحظات أو واجهت أي مشكلات.

توجّه معظم نماذج التحوّل في Diffusers الانتباه عبر موزّع الانتباه لتتمكن من تبديل الخلفيات المحسّنة خلف واجهة برمجة واحدة. يدير الموزّع التطبيقات المسجّلة ويعرض مسار استدعاء موحّد لها. بعض النماذج، مثل العديد من الترميز-فك الترميز التلقائي، لا تستخدم الموزّع بسبب بنيتها الداخلية، وبالتالي فإن تبديل الخلفية لا يؤثر على طبقات الانتباه فيها.

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

عائلة الانتباه	الميزة الرئيسية
FlashAttention	يقلل عمليات القراءة/الكتابة للذاكرة من خلال التقطيع وإعادة الحساب
محرك AI Tensor لـ ROCm	تنفيذ FlashAttention مُحسّن لتسريعات AMD ROCm
SageAttention	يكمّم الانتباه إلى int8
FlexAttention	PyTorch FlexAttention
أصلي في PyTorch	التنفيذ المدمج في PyTorch باستخدام scaled_dot_product_attention
xFormers	انتباه موفّر للذاكرة مع دعم لأنواع مختلفة من نواة الانتباه

تتطلب واجهات Hub الخلفية (الأسماء *_hub) مكتبة Kernels وتنزّل النواة عند الاستخدام الأول. كما تتطلب واجهات Hub الخلفية الخاصة بـ SageAttention ضبط DIFFUSERS_TRUST_REMOTE_KERNELS=true (انظر Trusting remote kernels). أما الواجهات الخلفية الأخرى فتتطلب حزمها الخاصة، مثل flash-attn أو sageattention. ويحدد جدول Available backends المتطلبات التي يتحقق منها Diffusers عند تفعيل واجهة خلفية.

تعيين واجهة خلفية على النموذج

يتجوّل أسلوب set_attention_backend() في طبقات الانتباه في النموذج ويطبّق الخلفية المختارة على كل طبقة. كما يضبط الخلفية النشطة على مستوى العملية في الموزّع على القيمة نفسها.

يمسح reset_attention_backend() الخلفية (backend) على طبقات الانتباه فقط. لا يمسح الخلفية النشطة على مستوى العملية بأكملها. للتبديل المؤقت الذي يعيد الخلفية النشطة السابقة عند الخروج، استخدم مدير السياق attention_backend.

يتيح المثال أدناه تفعيل _flash_3_hub (FlashAttention-3 من Hub) باستخدام device_map="cuda".

import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
    "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"
)
pipeline.transformer.set_attention_backend("_flash_3_hub")

prompt = """
cinematic film still of a cat sipping a margarita in a pool in Palm Springs, California
highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain
"""
pipeline(prompt).images[0]

تتطلب واجهات FlashAttention-3 غير المرتبطة بالمستودع (_flash_3، _flash_varlen_3) بناء FlashAttention-3 من المصدر، وسيتم إيقاف استخدامها قريباً. استخدم _flash_3_hub أو _flash_3_varlen_hub بدلاً من ذلك.

جرّب واجهة خلفية مؤقتًا

يُعيّن مُدير السياق attention_backend() الخلفية النشطة على مستوى العملية طوال مدة الكتلة، ويعيد الخلفية السابقة عند الخروج من الكتلة. استخدمه لتجربة خلفية في استدعاء واحد دون ترك خلفية مطبقة بشكل دائم من set_attention_backend().

import torch
from diffusers import QwenImagePipeline, attention_backend

pipeline = QwenImagePipeline.from_pretrained(
    "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"
)
prompt = """
cinematic film still of a cat sipping a margarita in a pool in Palm Springs, California
highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain
"""

with attention_backend("_flash_3_hub"):
    image = pipeline(prompt).images[0]

يعمل معظم محركات الانتباه الخلفية مع torch.compile. يعتمد ما إذا كان ذلك يسرّع خط أنابيبك على النموذج والمحرك الخلفي. راجع الدقة والتجميع.

الثقة في النوى عن بُعد

تحتاج واجهات Hub الخلفية إلى مكتبة Kernels أولاً، ثم تقوم Diffusers بجلب نواة Hub عند الاستخدام الأول.

تنزّل واجهات الخلفية الخاصة بانتباه Hub نوى الحساب باستخدام مكتبة Kernels وتنفّذها محليًا. تُحلّ معظم أسماء انتباه Hub (_flash_3_hub، وflash_hub، وواجهات الخلفية الأخرى *_hub) إلى منظمة kernels-community. هذه المنظمة ناشر موثوق في Kernels، لذا يحمّل Diffusers تلك نوى الانتباه دون ضبط DIFFUSERS_TRUST_REMOTE_KERNELS.

تُحمّل واجهات SageAttention Hub الخلفية (sage_hub وsage_blackwell_hub) من منظمة SageAttention بدلاً من ذلك. اضبط DIFFUSERS_TRUST_REMOTE_KERNELS=true لاستخدامها.

تتميز ميزات أخرى مدعومة بالنواة، مثل GGUF وNunchaku Lite، بقدرتها على جلب النوى من ناشرين خارج نطاق kernels-community. تبقى هذه المسارات محظورة ما لم تقم بالموافقة عليها باستخدام DIFFUSERS_TRUST_REMOTE_KERNELS. عند ضبط هذا الإعداد، يقوم Diffusers بتحويل trust_remote_code=True إلى Kernels حتى يتمكن الناشر غير الموثوق من التحميل أيضًا.

export DIFFUSERS_TRUST_REMOTE_KERNELS=true

فعّل هذا الخيار فقط بعد فحص مستودع النواة. بدونه، يؤدي تحميل نواة من ناشر غير موثوق إلى رفع خطأ. يقوم Diffusers بإجراء هذا الفحص بنفسه، لذا ينطبق الأمر أيضاً على kernels<0.14.0، الذي يسبق وجود الحجة trust_remote_code. يؤدي تعيين DIFFUSERS_DISABLE_REMOTE_CODE=true إلى تعطيل الكود عن بُعد على مستوى النظام بالكامل، وله الأولوية على DIFFUSERS_TRUST_REMOTE_KERNELS.

فحوصات

يمكن لمُوزِّع الانتباه (attention dispatcher) تشغيل فحوصات تصحيح الأخطاء قبل كل استدعاء انتباه مُوزَّع. تعتمد الفحوصات التي تُشغَّل على القيود المسجَّلة للخلفية النشطة (active backend).

1. تحقّق فحوصات الأجهزة من أن متجهات الاستعلام والمفتاح والقيمة موجودة على نفس الجهاز.
2. تتحقق فحوصات أنواع البيانات، عند تسجيلها، من تطابق أنواع البيانات (dtypes) وغالباً ما تتطلب bfloat16 أو float16.
3. تحقّق فحوصات الأبعاد من أبعاد المصفوفات (tensors) وتمنع خلط أقنعة الانتباه (attention masks) مع أعلام السببية (causal flags).

فعّل الفحوصات باستخدام متغير البيئة DIFFUSERS_ATTN_CHECKS. تُضيف الفحوصات عبئًا إضافيًا، لذا فهي معطّلة افتراضيًا.

export DIFFUSERS_ATTN_CHECKS=yes

عند تفعيل الفحوصات، ينفّذ Diffusers تلك القيود قبل كل استدعاء انتباه مُوجَّه. يستدعي المثال منخفض المستوى أدناه dispatch_attention_fn مباشرةً. لا يحتاج الاستدلال عبر خط الأنابيب إلى ذلك الاستيراد. ما يحتاجه فقط هو ضبط الخلفية عبر set_attention_backend() أو attention_backend().

import torch
from diffusers.models.attention_dispatch import attention_backend, dispatch_attention_fn

query = torch.randn(1, 10, 8, 64, dtype=torch.bfloat16, device="cuda")
key = torch.randn(1, 10, 8, 64, dtype=torch.bfloat16, device="cuda")
value = torch.randn(1, 10, 8, 64, dtype=torch.bfloat16, device="cuda")

try:
    with attention_backend("flash"):
        output = dispatch_attention_fn(query, key, value)
        print("✓ Flash Attention works with checks enabled")
except Exception as e:
    print(f"✗ Flash Attention failed: {e}")

الواجهات الخلفية المتاحة

راجع الجدول أدناه للحصول على قائمة كاملة بالخوادم الخلفية المتاحة لانتباه (attention) ومتغيراتها. يتحقق Diffusers من توفر الحزم وتثبيت الإصدارات عند تفعيل خادم خلفي.

اسم الخلفية	العائلة	الوصف	المتطلبات
native	PyTorch الأصلي	الخلفية الافتراضية باستخدام scaled_dot_product_attention من PyTorch	لا شيء
flex	FlexAttention	PyTorch FlexAttention	torch>=2.5.0
_native_cudnn	PyTorch الأصلي	الانتباه المُحسَّن بواسطة CuDNN	CUDA + CuDNN
_native_efficient	PyTorch الأصلي	انتباه موفّر للذاكرة	لا شيء سوى PyTorch
_native_flash	PyTorch الأصلي	FlashAttention في PyTorch	CUDA
_native_math	PyTorch الأصلي	انتباه قائم على الرياضيات (بديل احتياطي)	لا شيء
_native_npu	PyTorch الأصلي	انتباه مُحسَّن لوحدة المعالجة العصبية	torch_npu
_native_xla	PyTorch الأصلي	انتباه مُحسَّن بواسطة XLA	torch_xla>=2.2
flash	FlashAttention	FlashAttention-2	flash-attn>=2.6.3
flash_hub	FlashAttention	FlashAttention-2 من نواة Hub	kernels>=0.12
flash_varlen	FlashAttention	FlashAttention بطول متغير	flash-attn>=2.6.3
flash_varlen_hub	FlashAttention	FlashAttention بطول متغير من نواة Hub	kernels>=0.12
aiter_fa2_hub	محرك AI Tensor لـ ROCm	FlashAttention-2 لـ AMD ROCm من نواة Hub (bfloat16)	kernels>=0.12، ROCm
flash_4_hub	FlashAttention	FlashAttention-4 من نواة Hub	kernels>=0.12.3
_flash_3	FlashAttention	FlashAttention-3 (محلي؛ سيُتوقف عن استخدامه قريباً)	بناء FA3 من المصدر
_flash_varlen_3	FlashAttention	FlashAttention-3 بطول متغير (محلي؛ سيُتخلى عنه قريباً)	بناء FA3 من المصدر
_flash_3_hub	FlashAttention	FlashAttention-3 من نواة Hub	kernels>=0.12
_flash_3_varlen_hub	FlashAttention	FlashAttention-3 بطول متغير من نواة Hub	kernels>=0.12
sage	SageAttention	الانتباه المُكمَّم (INT8 QK)	sageattention>=2.1.1
sage_hub	SageAttention	الانتباه المُكمَّم (INT8 QK) من نواة Hub	kernels>=0.12, DIFFUSERS_TRUST_REMOTE_KERNELS=true
sage_blackwell_hub	SageAttention	انتباه SageAttention3 FP4 لشرائح SM120 Blackwell من نواة Hub	kernels>=0.12, DIFFUSERS_TRUST_REMOTE_KERNELS=true
sage_varlen	SageAttention	SageAttention بطول متغير	sageattention>=2.1.1
_sage_qk_int8_pv_fp8_cuda	SageAttention	INT8 QK + FP8 PV (CUDA)	sageattention>=2.1.1
_sage_qk_int8_pv_fp8_cuda_sm90	SageAttention	INT8 QK + FP8 PV (SM90)	sageattention>=2.1.1؛ SM90
_sage_qk_int8_pv_fp16_cuda	SageAttention	INT8 QK + FP16 PV (CUDA)	sageattention>=2.1.1
_sage_qk_int8_pv_fp16_triton	SageAttention	INT8 QK + FP16 PV (Triton)	sageattention>=2.1.1
xformers	xFormers	انتباه موفّر للذاكرة	xformers>=0.0.29