التخزين المؤقت

يعمل التخزين المؤقت على إعادة استخدام مخرجات الطبقات الوسيطة عبر خطوات إزالة الضوضاء لتسريع الاستدلال. يستهلك هذا الأسلوب ذاكرة أكبر ولا يتطلب تدريبًا. فعّل طريقة ما عبر إعدادات على محوّل يدعم التخزين المؤقت.

اختر طريقة تخزين مؤقت

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

بث الانتباه الهرمي

يقوم Pyramid Attention Broadcast (PAB) بتقريب الانتباه عبر خطوات إزالة الضوضاء من خلال إعادة استخدام مخرجات الانتباه لبعض الكتل وخطوات الزمن بدلاً من إعادة الحساب في كل خطوة. يميّز الإعداد بين أنواع الانتباه (المكانية، الزمنية، المتقاطعة) عندما تتوفر في النموذج. لا يكشف كل نموذج فيديو عن الأنواع الثلاثة، لذا اضبط فقط النطاقات التي تتطابق مع الكتل المتوفرة لديك.

يستخدم كل نوع *_attention_block_skip_range (تكرار إعادة الحساب مقابل إعادة الاستخدام داخل النافذة) و*_attention_timestep_skip_range (خطوات إزالة الضوضاء التي يمكن تجاوزها). يجب عليك تمرير current_timestep_callback حتى يتمكن الخطاف من قراءة الخطوة الزمنية الحالية للخط. عادةً ما تعني التجاوزات الأوسع أو الأكثر عدوانية مزيدًا من السرعة ومزيدًا من مخاطر الجودة.

مرّر PyramidAttentionBroadcastConfig لتفعيله.

import torch
from diffusers import CogVideoXPipeline, PyramidAttentionBroadcastConfig

pipe = CogVideoXPipeline.from_pretrained("THUDM/CogVideoX-5b", dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

config = PyramidAttentionBroadcastConfig(
    spatial_attention_block_skip_range=2,
    spatial_attention_timestep_skip_range=(100, 800),
    current_timestep_callback=lambda: pipe.current_timestep,
)
pipe.transformer.enable_cache(config)

FasterCache

يخزّن FasterCache ميزات الانتباه ويعيد استخدامها بطريقة مشابهة لـ PAB. كما يمكنه تجاوز الفرع غير الشرطي في التوجيه الحر من التصنيف وتقديره من الفرع الشرطي عندما تكون الكمونيات المتتالية متكررة بما يكفي.

مرّر FasterCacheConfig لتفعيله. وبالمثل مع PAB، اضبط *_attention_block_skip_range و*_attention_timestep_skip_range لأنواع الانتباه التي لديك، بالإضافة إلى خيارات تخطي فرع CFG عندما ترغب في ذلك.

import torch
from diffusers import CogVideoXPipeline, FasterCacheConfig

pipe = CogVideoXPipeline.from_pretrained("THUDM/CogVideoX-5b", dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

config = FasterCacheConfig(
    spatial_attention_block_skip_range=2,
    spatial_attention_timestep_skip_range=(-1, 681),
    current_timestep_callback=lambda: pipe.current_timestep,
    attention_weight_callback=lambda _: 0.3,
    unconditional_batch_skip_range=5,
    unconditional_batch_timestep_skip_range=(-1, 781),
    tensor_format="BFCHW",
)
pipe.transformer.enable_cache(config)

SeaCache

يقارن SeaCache مؤشرات التطور الطيفي الواعي (SEA) بين خطوات إزالة الضوضاء المتتالية. عندما يبقى التغيير المتراكم دون حد معين، يتخطى مجموعة كتل التحويلي ويتنبأ بالمخرجات من بقايا مخزنة مسبقًا. الطريقة تقريبية ومصممة لتوليد الفيديو.

تشمل المكيّفات المدمجة في SeaCache ما يلي:

• Cosmos 3 هو التكامل الأساسي المُحسَّن والمُقيَّم.
• يستخدم Wan T2V مسار كتل التكرار العام كنموذج توضيحي لكيفية توفير كامنات الرؤية الخام إلى SeaCache. قد لا تنطبق نفس معاملات التخزين المؤقت على Wan أو غيرها من متغيرات Wan.

فعّل SeaCache على المحوّل. يربط حلقة إزالة الضوضاء في Cosmos 3 خطوة المجدول، وقيمة sigma، وعدد الخطوات إلى كل cache_context، لذا لا حاجة إلى أي معاملات إضافية.

from diffusers import Cosmos3OmniPipeline, SeaCacheConfig

pipe = Cosmos3OmniPipeline.from_pretrained("nvidia/Cosmos3-Nano")
pipe.transformer.enable_cache(SeaCacheConfig(threshold=0.2, max_consecutive_cached=2))

قد تُغيّر SeaCache المخرجات. استدعِ pipe.transformer.disable_cache() عندما تحتاج إلى تشغيل كل خطوة عبر المحوّل الكامل. يعمل نفس استدعاء التفعيل مع Cosmos3OmniPipeline وCosmos3OmniModularPipeline وCosmos3DistilledModularPipeline.

لاستخدام SeaCache مع محوّل فيديو آخر، اتبع إضافة التخزين المؤقت إلى نموذج جديد. كما يحتاج SeaCache إلى step_index وsigma وnum_inference_steps في كل cache_context، وإلى raw_vision_callback عندما لا يتوفر مُكيّف مدمج. اضبط المعلمات لكل نموذج ومجدول.

FirstBlockCache

يتحقق FirstBlockCacheConfig من مقدار تغيّر الطبقات المبكرة في مُزيل الضوضاء من خطوة زمنية إلى التالية. إذا كان التغير صغيراً، يتخطّى النموذج الطبقات اللاحقة المكلفة ويعيد استخدام المخرجات السابقة.

فعّله عبر enable_cache حتى تبقى disable_cache وis_cache_enabled متزامنة. القيمة الافتراضية لـthreshold هي 0.05. القيمة الأعلى مثل 0.2 تتخطى العملية بشكل متكرر أكثر لتحقيق سرعة إضافية، لكن جودة التوليد قد تنخفض.

import torch
from diffusers import DiffusionPipeline, FirstBlockCacheConfig

pipe = DiffusionPipeline.from_pretrained(
    "Qwen/Qwen-Image", dtype=torch.bfloat16
)
pipe.transformer.enable_cache(FirstBlockCacheConfig(threshold=0.2))

TaylorSeer ذاكرة مؤقتة

يعمل TaylorSeer Cache على تسريع استنتاج النماذج الانتشارية (Diffusion) باستخدام توسعات متسلسلة تايلور عبر خطوات إزالة الضوضاء. فهو يتنبأ بتفعيلات الخطوات اللاحقة بناءً على تفعيلات الخطوات السابقة، ويعيد استخدام تلك التنبؤات لعدة خطوات، مما يقلل من حجم العمل الكامل الذي يقوم به نموذج التحويل (Transformer).

• cache_interval: عدد الخطوات لإعادة استخدام المخرجات المخزنة مؤقتًا قبل إجراء تمرير أمامي كامل
• disable_cache_before_step: الخطوات الأولية التي تستخدم الحسابات الكاملة لجمع البيانات للتقديرات
• max_order: يمكن أن تكون رتب تايلور الأعلى أكثر دقة لكنها تستهلك ذاكرة أكبر. حافظ على هذا عند 1 ما لم يكن لديك سبب لتغييره.

import torch
from diffusers import FluxPipeline, TaylorSeerCacheConfig

pipe = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    dtype=torch.bfloat16,
).to("cuda")  # or "mps", "xpu", "cpu"

config = TaylorSeerCacheConfig(
    cache_interval=5,
    max_order=1,
    disable_cache_before_step=10,
    taylor_factors_dtype=torch.bfloat16,
)
pipe.transformer.enable_cache(config)

MagCache

يتخطى MagCache كتل التحويل بناءً على مقدار التحديث المتبقي. تتناقص مقادير التحديث بشكل متوقع عبر عملية إزالة الضوضاء، ويتتبع MagCache ميزانية خطأ من نسب المقادير المحسوبة مسبقًا (mag_ratios) لتحديد متى يكون إعادة الاستخدام آمنة. هذه النسب مرتبطة بنقطة الحفظ ومجدول التدرج المحدد. يمكن استيفاء النسب المستمدة من عدد خطوات عالٍ لتقليل عدد الخطوات.

تم قياس FLUX_MAG_RATIOS المرفقة على FLUX.1. تحتاج النماذج الأخرى، بما في ذلك Flux2 وFlux2 Klein، إلى إجراء معايرة خاص بها.

يتبع MagCache خطوتين:

1. المعايرة: نفّذ الاستدلال مرة واحدة مع calibrate=True. يقيس الخطاف (hook) أحجام البواقي (residuals) ويُطبع النسب المحسوبة.
2. الاستدلال: عطّل ذاكرة التخزين المؤقت للمعايرة، ثم مرّر تلك النسب إلى MagCacheConfig للتسريع.

قد يؤثر التوجيه الحر من التصنيف على المعايرة. تدخل خطوط الأنابيب التي تستخدم CFG الحقيقي مع سياقات متسلسلة، مثل Flux عندما يكون true_cfg_scale > 1، إلى cache_context("cond") وcache_context("uncond") بشكل منفصل. قد تطبع المعايرة مصفوفة واحدة لكل سياق، لكن عليك استخدام المصفوفة الشرطية في معظم الحالات. تنتج خطوط الأنابيب التي تجمع CFG عن طريق دمج المدخلات الشرطية وغير الشرطية (على سبيل المثال، CogVideoX) مصفوفة مشتركة واحدة يمكنك استخدامها مباشرة.

import torch
from diffusers import FluxPipeline, MagCacheConfig
from diffusers.hooks.mag_cache import FLUX_MAG_RATIOS

pipe = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-schnell",
    dtype=torch.bfloat16
).to("cuda")  # or "mps", "xpu", "cpu"

# 1. Calibration Step
# Run full inference to measure model behavior.
calib_config = MagCacheConfig(calibrate=True, num_inference_steps=4)
pipe.transformer.enable_cache(calib_config)

# Run a prompt to trigger calibration
pipe("A cat playing chess", num_inference_steps=4)
# Prints: [MagCache] Calibration Complete. Copy these values to MagCacheConfig(mag_ratios=...):

# 2. Inference Step
# Disable calibration hooks before enabling MagCache for inference.
pipe.transformer.disable_cache()

# Apply ratios from calibration, or use the Flux defaults:
# mag_ratios=FLUX_MAG_RATIOS
mag_config = MagCacheConfig(
    mag_ratios=[1.0, 1.37, 0.97, 0.87],
    num_inference_steps=4
)

pipe.transformer.enable_cache(mag_config)

image = pipe("A cat playing chess", num_inference_steps=4).images[0]

ذاكرة التخزين المؤقت لنص KV

يحسب TextKVCacheConfig إسقاطات المفاتيح والقيم للنص مرة واحدة ويعيد استخدامها في كل خطوة إزالة ضوضاء بدلاً من إعادة حسابها. حالياً، لا يربط apply_text_kv_cache() سوى NucleusMoEImageTransformerBlock. فعّله باستخدام enable_cache.

import torch
from diffusers import NucleusMoEImagePipeline, TextKVCacheConfig

pipe = NucleusMoEImagePipeline.from_pretrained(
    "NucleusAI/NucleusMoE-Image", dtype=torch.bfloat16
)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

pipe.transformer.enable_cache(TextKVCacheConfig())

image = pipe("A cat holding a sign that says hello world", num_inference_steps=50).images[0]

إضافة التخزين المؤقت إلى نموذج جديد

تُربط طرق التخزين المؤقت (Cache) بالنموذج عبر الخطافات (hooks)، وتعتمد هذه الخطافات على فئة النموذج، ومكاتب التحويل (transformer blocks) الخاصة به، وحلقة إزالة الضوضاء (denoising loop) في خط المعالجة. قم بإعداد جميع العناصر الثلاثة الثلاثة قبل استدعاء enable_cache على نموذج جديد.

1. ورث من CacheMixin في فئة التحويل. يضيف هذا enable_cache وdisable_cache وcache_context.

2. سجّل تخطيط المخرجات للكتلة المحوّلة (transformer block) في _register_transformer_blocks_metadata داخل hooks/_helpers.py. تستخدم الطرق التي تتخطى أو تعيد استخدام كتل كاملة، مثل FirstBlockCache وMagCache وSeaCache، هذا التخطيط للعثور على الحالات المخفية (hidden states) في مخرجات الكتلة.

   تم النسخ

   TransformerBlockRegistry.register(
       model_class=MyTransformerBlock,
       metadata=TransformerBlockMetadata(
           return_hidden_states_index=0,
           return_encoder_hidden_states_index=None,
       ),
   )

3. غلّف كل استدعاء لمحوّل داخل حلقة إزالة الضوضاء في خط المعالجة بـcache_context. استخدم أسماء منفصلة، مثل "cond" و"uncond"، عندما يشغّل التوجيه الحر من التصنيف الفروع الشرطية وغير الشرطية كاستدعاءات منفصلة، بحيث يحتفظ كل فرع بحالة ذاكرته المؤقتة الخاصة به.

   تم النسخ

   with self.transformer.cache_context("cond"):
       noise_pred = self.transformer(hidden_states=latents, timestep=timestep, ...)[0]

تحتاج PAB وFasterCache أيضًا إلى current_timestep_callback حتى تتمكن الخطافات من قراءة الخطوة الزمنية الحالية. تحقق من جودة المخرجات على النموذج الجديد، لأن إعدادات الكاش المُحسَّنة لنموذج واحد غالبًا لا تنتقل إلى نموذج آخر.