ShadowPEFT

يعزز ShadowPEFT نموذج فك الترميز الأساسي المجمد (decoder-only) بشبكة ظل خفيفة الوزن وقابلة للتدريب المسبق تعمل بالتوازي مع الهيكل العظمي. ينتج هيكل ظل صغير حالة ظل أولية s^(0)، ثم تنضم هذه الحالة إلى حلقة فك الترميز في النموذج الأساسي: في كل كتلة مستهدفة، يُحقن الفرق بين الحالات المخفية الأساسية وحالة الظل مرة أخرى في مدخلات الكتلة (تصحيح منخفض الرتبة)، وتُقدَّم حالة الظل عبر تحديث متبقي مُتحكَّم به (gated residual update) يُحسب من مخرجات الكتلة. يتم تدريب مكونات الظل فقط؛ بينما يبقى النموذج الأساسي مجمداً.

Input
  ├──► Shadow backbone (small, trainable) ──► s^(0)
  └──► Base model (frozen, large)
         block_0 ◄── inject(h, s) ─► h_0 ──► update ─► s_1
         block_1 ◄── inject(h, s) ─► h_1 ──► update ─► s_2
         ...                       (the (hidden, shadow) pair rides the loop together)

بما أن التكيف هو مسار يعتمد على المدخلات في فضاء الطبقات (حيث يتطور الحالة الظل مع البيانات) وليس فرقًا ثابتًا في فضاء الأوزان، فإن ShadowPEFT لا يمكن دمجها مع الأوزان الأساسية. يؤدي استدعاء merge أو merge_adapter أو merge_and_unload إلى رفع خطأ صريح. بالنسبة لنماذج اللغة في Transformers، يمكنك الحصول على الشبكة الظل الخفيفة الوزن بشكل مستقل باستخدام model.base_model.unload_shadow()، والتي تُرجع DetachedShadowModel مستقلًا. لا يُدعم التفريغ المستقل لنماذج Diffusers لأن إعادة بناء مُزيل الضوضاء الكامل تعتمد على البنية المعمارية.

تعمل إضافة عدة محوِّلات، والتبديل بينها باستخدام set_adapter، وحذفها، وتفعيلها/تعطيلها جميعها بنفس طريقة عمل طرق PEFT الأخرى. لا يمكن تفعيل محوِّل واحد في كل مرة، لأن حالة الظل هي مسار واحد عبر الشبكة.

يمكن بناء الهيكل الظلي بطريقتين، يتحكم فيهما ShadowConfig.shadow_model:

• "mirror" (الافتراضي): يتم إنشاء عمود فقري ظلّي أصغر حجمًا تلقائيًا. تستخدم نماذج اللغة نسخة مخفّضة من البنية الأساسية. تستخدم بنيات Diffusers التي لديها واجهة خلفية مسجّلة نموذجًا مشابهًا للبنية المخفّضة ومهيّأً من أوزان أساسية مختارة؛ بينما تعتمد البنيات المتوافقة التي لا تملك واجهة خلفية على شبكة MLP متبقية على مستوى الرمز. عندما يختلف حجم الإخفاء الظلّي عن الأساسي، تُجسر شبكة إسقاط مدرّبة هذا الفارق.
• معرف نموذج أو مسار محلي: يتم تحميل العمود الفقري كنموذج مُدرَّب مسبقًا أصغر حجمًا. تستخدم نماذج Transformers AutoModel؛ بينما تُعرّف واجهات Diffusers المسجلة تحميل نقاط التفتيش المتوافقة الخاصة بها.

يتم تحديد دعم Diffusers الواعي بالبنية تلقائيًا من فئة النموذج. حاليًا، يوجد مُنفِّذ مسجَّل لـ Flux2؛ بينما تستخدم نماذج Diffusers الأخرى المتوافقة القائمة على محولات عامة آلية الاحتياط العامة MLP. تبقى الاستدعاء المستقل لـ unload_shadow() غير مدعوم لجميع نماذج Diffusers لأن إعادة بناء مُزيل الضوضاء الكامل تعتمد على البنية.

مقارنةً بطرق LoRA، يضيف ShadowPEFT مزيدًا من المعاملات والحسابات (حيث يشغّل شبكةً موازيةً ويلفّ كتل فك الترميز كاملةً)، لكن المُكيّف هو شبكةٌ مكتفيةٌ ذاتيًا يمكن تدريبها مركزياً، وإعادة استخدامها عبر المهام، وتبديؤها من نموذجٍ صغيرٍ مُدرَّب مسبقاً. الخسارة الإضافية الاختيارية (auxiliary_loss_weight) تطبّق رأس المهمة على الحالة الظلية الأولية s^(0) وتضيفها إلى خسارة المهمة، مما يشجّع المسار الظلي القابل للفصل على حلّ المهمة بمفرده. بالنسبة لنماذج اللغة السببية، يُعاد استخدام رأس الإخراج الأساسي؛ شمل "lm_head" في modules_to_save لتدريبه وحفظه عبر آلية PEFT القياسية.

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

يدعم ShadowPEFT فك الترميز التدرّجي مع ذاكرة KV مزدوجة: واحدة للنموذج الأساسي المتجمّد والأخرى لهيكل الظل. عمليات الحقن/التحديث محلية على مستوى الرمز، لذا لا يحتاج الرمز الجديد سوى حالة ظله الخاصة s؛ وتُبقي السببية مفاتيح/قيم البادئة الأساسية (المُحسوبة تحت الحقن) صالحة. الكائن المرافق هو ShadowCache، ويُعاد بوصفه past_key_values عند use_cache=True. يمكنك تمرير use_cache=True إلى generate() كما هو معتاد.

out = model.generate(input_ids, max_new_tokens=32)  # dual KV cache enabled by default
# or explicitly:
out = model.generate(input_ids, use_cache=True, max_new_tokens=32)

لا يزال use_cache=False يعمل ويعيد معالجة التسلسل الكامل في كل خطوة (مفيد للتصحيح).

الاستخدام

from transformers import AutoModelForCausalLM
from peft import ShadowConfig, get_peft_model

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-0.6B")
config = ShadowConfig(r=8, shadow_num_hidden_layers=1, task_type="CAUSAL_LM")
model = get_peft_model(model, config)
model.print_healthcheck()

out = model.generate(input_ids, max_new_tokens=32)

لتشغيل العمود الفقري الظلّي من نموذج مُدرَّب مسبقًا أصغر حجمًا، مرّر معرّفه أو مساره كـshadow_model:

config = ShadowConfig(shadow_model="Qwen/Qwen3-0.6B", task_type="CAUSAL_LM")
model = get_peft_model(base_model, config)

تقييم مسار الظل

بشكل افتراضي، يكون مخرج النموذج (logits) هو النموذج الأساسي المُكيَّف بالظل: حيث تُحقن تصحيحات الظل في الحالات المخفية للنموذج الأساسي في كل طبقة، لذا فإن logits يعكس بالفعل ShadowPEFT (استخدم model.disable_adapter() للحصول على النموذج الأساسي العادي للمقارنة). بالإضافة إلى ذلك، يدرب الخسارة المساعدة مسار الظل على حل المهمة بمفرده.

لتقييم الشبكة الظل المستقلة لنموذج لغة Transformers (النموذج القابل للفصل والخفيف — المقابل لـ merge_and_unload في ShadowPEFT)، استخدم unload_shadow(). يعيد هذا الدالة head(projection(backbone(x))) كنموذج مهمة عادي يمكنك تقييمه مثل أي نموذج آخر: بالنسبة لمهمة LM السببية، يكون نموذج LM سببيًا قادرًا على التوليد (يدعم generate() وتخزين KV)، وبالنسبة لمهمة تصنيف التسلسل، فإنه يجمع الرمز الأخير ويعيد قيم logits للفئات. استدعاء هذه الدالة لنموذج Diffusers يثير NotImplementedError.

shadow = model.base_model.unload_shadow()  # a DetachedShadowModel (a PreTrainedModel)
shadow.eval()
# causal LM:
out = shadow.generate(input_ids, max_new_tokens=32)
# sequence classification:
logits = shadow(input_ids=input_ids, attention_mask=attention_mask).logits  # (batch, num_labels)

بشكل افتراضي (copy=False)، يتشارك النموذج المُعاد وحداته مع نموذج PEFT، ويصل إلى هذه الوحدات عبر مرجع ليس فرعيًا من الوحدات الفرعية، عمود فقري ظلّي يتشارك ترميزات الإدخال الأساسية المجمّدة. هذا مقبول للتقييم، لكنه يعني أن save_pretrained سيكتب نقطة تحقق دون جدول الترميزات. مرّر copy=True عندما تريد حفظ النموذج المستقل أو رفعه:

shadow = model.base_model.unload_shadow(copy=True)
shadow.save_pretrained("standalone-shadow")

واجهة برمجة التطبيقات

ShadowConfig

ShadowModel

ShadowCache