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

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

توفر مكتبة Diffusers عدة خوارزميات انتباه مُحسّنة، أكثر كفاءة من حيث الذاكرة والحساب، من خلال موزّع الانتباه الخاص بها. يعمل الموزّع كموجّه لإدارة وتبديل بين تنفيذه المختلفة لخوارزميات الانتباه، ويوفر واجهة موحدة للتفاعل معها.

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

ستُظهر لك هذه الدليل كيفية ضبط واستخدام واجهات الانتباه المختلفة.

set_attention_backend

يتكرر أسلوب set_attention_backend() عبر جميع الوحدات في النموذج ويضبط واجهة الانتباه المناسبة للاستخدام. يستمر ضبط واجهة الانتباه حتى يتم استدعاء reset_attention_backend().

يُبيّن المثال أدناه كيفية تفعيل تطبيق _flash_3_hub الخاص بـ FlashAttention-3 من مكتبة kernels، مما يتيح لك استخدام نوى الحساب المُحسّنة من Hub فورًا دون الحاجة إلى أي إعداد.

يتطلب FlashAttention-3 معالجات رسومية من نوع Ampere كحد أدنى.

import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
    "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
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]

لاستعادة واجهة الانتباه الافتراضية، استدعِ reset_attention_backend().

pipeline.transformer.reset_attention_backend()

مدير السياق attention_backend

يُعيّن مُدير السياق attention_backend مؤقتًا واجهة خلفية للانتباه لنموذج ضمن نطاق السياق. خارج هذا النطاق، يُستخدم الانتباه الافتراضي (انتباه النقطي المتدرج الأصلي في PyTorch). وهذا مفيد إذا كنت ترغب في استخدام واجهات خلفية مختلفة لأجزاء مختلفة من خط الأنابيب، أو إذا أردت اختبار الواجهات الخلفية المختلفة.

import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
    "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
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 الخلفية وميزات أخرى مدعومة بنواة (مثل GGUF وNunchaku Lite) نوى الحساب من Hub باستخدام kernels وتنفّذ كودها محليًا.

بشكل افتراضي، لا يُحمّل kernels نواةً إلا إذا كان ناشرها ناشرًا موثوقًا به على Hub. النوى المنشورة تحت منظمة kernels-community موثوقة، لذا يحمّلها Diffusers دون أي إعداد إضافي. جميع واجهات الخلفية الأخرى للانتباه على Hub، بما في ذلك _flash_3_hub وflash_hub وsage_hub، تُحل إلى مستودعات kernels-community.

النوى من أي ناشر آخر غير مُدقَّقة. عند تحميل نواة منها، يتم تنزيل الكود وتنفيذه، ولا يمكن لـ Diffusers ضمان سلامته، لذا يبقى Diffusers معطّلًا ما لم تُفعّله صراحةً عبر متغير البيئة 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.

فحوصات

يتضمن مُوزّع الانتباه فحوصات تصحيح أخطاء تلتقط الأخطاء الشائعة قبل أن تسبب مشكلات.

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

فعّل هذه الفحوصات عن طريق تعيين متغير البيئة DIFFUSERS_ATTN_CHECKS. تضيف الفحوصات عبئًا إضافيًا على كل عملية انتباه، لذا فهي معطّلة افتراضيًا.

export DIFFUSERS_ATTN_CHECKS=yes

تُنفَّذ الفحوصات الآن قبل كل عملية انتباه.

import torch

query = torch.randn(1, 10, 8, 64, dtype=torch.bfloat16, device="cuda")  # or "mps", "xpu", "cpu"
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}")

يمكنك أيضًا تكوين السجل مباشرة.

from diffusers.models.attention_dispatch import _AttentionBackendRegistry

_AttentionBackendRegistry._checks_enabled = True

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

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