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

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

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

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

تتطلب واجهات 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 من توفر الحزم وتثبيت الإصدارات عند تفعيل خادم خلفي.