Buckets:

hf-doc-build
/

doc

Files
xet
hf-doc-build/doc / diffusers /v0.43.0 /ar /api /pipelines /diffusion_gemma.md
mishig
2 days ago
preview code
download
raw
23.3 kB
# DiffusionGemma

DiffusionGemma هو نموذج لغة مُرمِّز-مُفكِّك يعتمد على الانتشار على مستوى الكتل. يقرأ المُرمِّز السببي الموجه النظيف (وأي كتل تم توليدها سابقًا) إلى ذاكرة KV، بينما يُزيل المُفكِّك الاتجاهي الضوضاء من «لوحة» بحجم ثابت تتكون من `canvas_length` رمزًا من خلال الانتباه المتقاطع إلى تلك الذاكرة. يتناوب التوليد بين حلقة خارجية ذاتية التراجع على مستوى اللوحات وحلقة داخلية لإزالة الضوضاء، حيث يقوم كل خطوة فيها بسحب رموز مرشحة، والتأكيد على الأكثر ثقة منها عبر [BlockRefinementScheduler](/docs/diffusers/v0.43.0/ar/api/schedulers/block_refinement#diffusers.BlockRefinementScheduler) في وضع التلطيخ المنتظم، وإعادة إضافة الضوضاء إلى البقية. يقع النموذج نفسه في `transformers` باسم `DiffusionGemmaForBlockDiffusion`؛ والنقطة الفاحصة المُصدَّرة هي [`google/diffusiongemma-26B-A4B-it`](https://huggingface.co/google/diffusiongemma-26B-A4B-it).

## الاستخدام

```py
import torch
from transformers import AutoProcessor, DiffusionGemmaForBlockDiffusion
from diffusers import BlockRefinementScheduler, DiffusionGemmaPipeline
model_id = "google/diffusiongemma-26B-A4B-it"
model = DiffusionGemmaForBlockDiffusion.from_pretrained(model_id, dtype=torch.bfloat16, device_map="auto")
processor = AutoProcessor.from_pretrained(model_id)
scheduler = BlockRefinementScheduler()
pipe = DiffusionGemmaPipeline(model=model, scheduler=scheduler, processor=processor)
pipe.model.model.decoder = torch.compile(pipe.model.model.decoder, mode="reduce-overhead", fullgraph=True)
output = pipe(
    prompt="Why is the sky blue?",
    gen_length=256,
    num_inference_steps=48,
    cache_implementation="static",
)
print(output.texts[0])
```

`num_inference_steps` هو عدد خطوات إزالة الضوضاء لكل لوحة (48 يتطابق مع نقطة التفتيش المنشورة)؛ فعدد خطوات أقل يكون أسرع لكنه يخفض الجودة. يتيح `cache_implementation="static"` أن يُجمَّع المُفكِّك باستخدام `torch.compile` مع cudagraphs (انظر [التخزين المؤقت الثابت والتجميع](#static-cache-and-compilation))؛ احذف كليهما للحصول على تشغيل أبسط بتخزين مؤقت ديناميكي.

للإدخالات متعددة الأدوار أو متعددة الوسائط، مرّر محادثة خام `messages` بدلاً من `prompt`. وهو قائمة من قواميس `{"role", "content"}` بالصيغة المعتادة للمحادثات، يمرّ المعالج بها عبر قالب المحادثة الخاص به:

```py
messages = [
    {"role": "user", "content": "Why is the sky blue?"},
]
# or with an image:
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "image": image},
            {"type": "text", "text": "Describe this image."},
        ],
    },
]
output = pipe(messages=messages, gen_length=256)
```

في حالة دور مستخدم واحد، يمكنك تجاوز `messages` وتقديم `image` إلى جانب `prompt`؛ حيث يقوم المعالج بتحويلها تلقائيًا إلى مدخلات الصورة الخاصة بالنموذج.

## المجدولون

المجدول هو المُعيّن الذي يُزيل الضوضاء من كل لوحة، وهو قابل للاستبدال: استبدله لتغيير استراتيجية العينة دون المساس بأي شيء آخر. تتوفر ثلاثة مجدولات:

- [BlockRefinementScheduler](/docs/diffusers/v0.43.0/ar/api/schedulers/block_refinement#diffusers.BlockRefinementScheduler) (الافتراضي): يثبّت الرموز الأكثر ثقة في كل خطوة (تلك التي تتجاوز `threshold`، بالإضافة إلى حصة متساوية لكل خطوة) ويعيد إضافة الضوضاء إلى البقية. كما يتيح `editing_threshold` إعادة تحرير الرموز المثبتة مسبقًا.
- [DiscreteDDIMScheduler](/docs/diffusers/v0.43.0/ar/api/schedulers/discrete_ddim#diffusers.DiscreteDDIMScheduler): يعيّن كل موضع من التوزيع الخلفي المنفصل الدقيق لعملية التلوث المنتظمة (D3PM). وهو خالٍ من المعلمات، والخطوة النهائية تلتزم بشكل حتمي بالرموز المتوقعة.
- [EntropyBoundScheduler](/docs/diffusers/v0.43.0/ar/api/schedulers/entropy_bound#diffusers.EntropyBoundScheduler): يُثبّت المواضع ذات الإنتروبيا الأدنى التي تبقى إنتروبياها المشتركة دون `entropy_bound`، بحيث تُقبل الرموز شبه المستقلة معًا. وهو يُبرّد درجة حرارة العينة من `t_max` (`0.8`) في الخطوة الأولى إلى `t_min` (`0.4`) في الخطوة الأخيرة، بما يتوافق مع مُعيّن نقاط التفتيش المُصدر.

```py
from diffusers import DiscreteDDIMScheduler, EntropyBoundScheduler
pipe.scheduler = DiscreteDDIMScheduler()
# or: pipe.scheduler = EntropyBoundScheduler(entropy_bound=0.1)
output = pipe(prompt="Why is the sky blue?", gen_length=256, num_inference_steps=48)
print(output.texts[0])
```

تُضبط خيارات العينة الخاصة بالجدول الزمني (مثل `threshold`/`top_k` لتحسين الكتلة، وحد الإنتروبيا، ...) على إعدادات الجدول الزمني:

```py
from diffusers import BlockRefinementScheduler
pipe.scheduler = BlockRefinementScheduler.from_config(pipe.scheduler.config, threshold=0.9)
```

يُخفّض `EntropyBoundScheduler` درجة حرارة العينة (`t_max`/`t_min`) داخلياً على مدى خطوات إزالة الضوضاء؛ بينما يستخدم `DiscreteDDIMScheduler` و`BlockRefinementScheduler` قيمة `temperature` الثابتة المُمرَّرة إلى خط الأنابيب (`0.0` للاستخدام الجشع).

### عينة التنبؤ والتصحيح

`DiscreteDDIMScheduler` يدعم مُصحِّح التنبؤ-التصحيح مع استبعاد عنصر واحد (leave-one-out predictor-corrector) في [Uniform Diffusion Models Revisited: Leave-One-Out Denoiser and Absorbing State Reformulation](https://huggingface.co/papers/2605.22765). فهو يُحسّن اللوحة عبر `corrector_steps` من عمليات مسح غيبس (Gibbs sweeps) تعيد أخذ عينات من المواضع الأقل ثقة من الشرطي أحادي الإحداثي (one-coordinate conditional) للتوزيع الحدي الضوضائي (noisy marginal)، مما يُبقي ذلك التوزيع الحدي دون تغيير ويحسّن التوليد دون أي تكلفة تدريب إضافية. ويعمل مباشرة على نقطة التفتيش (checkpoint) المنشورة: ففي الانتشار المنتظم (uniform diffusion) يمكن استبدال مُزيل الضوضاء (denoiser) والخلفي (posterior) الخاص باستبعاد عنصر واحد بشكل مكافئ بصيغة مغلقة، لذا يستعيد المُصحِّح كميات استبعاد عنصر واحد التي يحتاجها دون أي إعادة تدريب.

تُدمج عمليات المسح المُصحِّحة ضمن ميزانية `num_inference_steps` بدلاً من إضافتها فوقها: حيث يُنفّذ خط الأنابيب عدداً أقل من خطوات المُتنبّئ ويخصص التقدّمات المحرَّرة للمُصحِّحات، وبالتالي يبقى إجمالي عدد تقدّمات النموذج `num_inference_steps` وتكون تكلفة المُتنبّئ-المُصحِّح مماثلة لتكلفة العيّنات الأصلية البسيطة.

```py
from diffusers import DiscreteDDIMScheduler
pipe.scheduler = DiscreteDDIMScheduler(corrector_steps=2, corrector_k=12)
output = pipe(prompt="Why is the sky blue?", gen_length=256, num_inference_steps=48)
print(output.texts[0])
```

## مُكيّفات PEFT

نموذج إزالة الضوضاء هو نموذج 🤗 Transformers، لذا يتم تحميل المُكيّفات (adapters) عبر تكامل [PEFT](https://huggingface.co/docs/peft) الأصلي الخاص به بدلاً من واجهة `load_lora_weights` في مكتبة diffusers. وبما أن هذا التكامل لا يعتمد على نوع المُكيّف، فإن نفس الاستدعاءات تُحمّل LoRA أو DoRA أو أي مُكيّف PEFT آخر (مثل ناتج `SFTTrainer` من TRL). قم بإدارة المُكيّفات على مكوّن النموذج مباشرةً:

```py
pipe.model.load_adapter("path/to/adapter", adapter_name="sft")  # LoRA, DoRA, ...
pipe.model.set_adapter("sft")
output = pipe(prompt="Why is the sky blue?", gen_length=256)
pipe.model.disable_adapters()  # run the base model
pipe.model.delete_adapter("sft")
```

تبقى المُكيّفات نشطة وغير مدمجة: يربط DiffusionGemma أوزان الأساس للمُشفِّر والمُفكِّك، لذا فإن دمج المُكيّف فيهما سيُفسد كلا الفرعين.

## التخزين المؤقت الثابت والتجميع

تعبّئ خطّ الأنابيب المُشفِّر مرة واحدة لكل كتلة في ذاكرة مؤقتة قابلة لإعادة الاستخدام (من نوع `DynamicCache` افتراضيًا). عند تمرير `cache_implementation="static"`، يتم استخدام `StaticCache` ذو شكل ثابت بدلاً من ذلك، مما يتيح لك `torch.compile` المُفكِّك باستخدام cudagraphs لتحقيق تسريع إضافي (حيث يحدد خطّ الأنابيب كل خطوة وينسخ logits حتى لا يتم تجاوز ذاكرة cudagraph)؛ وهذا هو الإعداد المعروض في [الاستخدام](#usage). احذف كلا من استدعاء `torch.compile` و`cache_implementation="static"` للحصول على تشغيل أبسط بذاكرة مؤقتة ديناميكية.

## الإيقاف التكيفي

تتقارب كتلة عادةً قبل استنفاد جميع `num_inference_steps`، لذا يقوم خط الأنابيب افتراضيًا بتجميد كل مثال في الدفعة بمجرد أن يصبح تنبؤ argmax الخاص به مستقرًا لعدد `stability_threshold` من الخطوات وأن ينخفض متوسط إنتروبيا الرمز الواحد إلى ما دون `confidence_threshold` (`0.005`، القيمة المستخدمة في نقطة التفتيش المنشورة). ينتهي حلقة إزالة الضوضاء بمجرد تجميد جميع الأمثلة. يقلل هذا تقريبًا من عدد عمليات تمرير المُفكِّك إلى النصف عند جودة مطابقة، وهو أكبر رافعة منفردة لإنتاجية النظام. مرر `confidence_threshold=None` لتشغيل `num_inference_steps` الكاملة دائمًا:

```py
output = pipe(prompt="Why is the sky blue?", gen_length=256, confidence_threshold=None)  # disable adaptive stopping
```

## المكالمات العكسية

تُنفَّذ استدعاءات المراجعة (Callbacks) بعد كل خطوة إزالة ضوضاء. مرّر `callback_on_step_end_tensor_inputs` لاختيار المصفوفات (tensors) التي تُدرج في `callback_kwargs`؛ حيث يتوفر `canvas` (رموز الكتل الحالية) و`logits`. أعد `{"canvas": ...}` من استدعاء المراجعة لاستبدال الـ canvas.

```py
def on_step_end(pipe, step, timestep, callback_kwargs):
    canvas = callback_kwargs["canvas"]
    # Inspect or modify `canvas` here.
    return {"canvas": canvas}
out = pipe(
    prompt="Why is the sky blue?",
    callback_on_step_end=on_step_end,
    callback_on_step_end_tensor_inputs=["canvas"],
)
```

## DiffusionGemmaPipeline[[diffusers.DiffusionGemmaPipeline]]

#### diffusers.DiffusionGemmaPipeline[[diffusers.DiffusionGemmaPipeline]]

```python
diffusers.DiffusionGemmaPipeline(model: Any, scheduler: BlockRefinementScheduler | DiscreteDDIMScheduler | EntropyBoundScheduler, processor: Any)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/diffusion_gemma/pipeline_diffusion_gemma.py#L53)

**المعاملات:**

model ([DiffusionGemmaForBlockDiffusion](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/diffusion_gemma#transformers.DiffusionGemmaForBlockDiffusion)) : مُزيل الضوضاء الخاص بالانتشار الكتلوي (مُشفِّر سببي + مُفكِّك ثنائي الاتجاه بأوزان مرتبطة).

scheduler ([BlockRefinementScheduler](/docs/diffusers/v0.43.0/ar/api/schedulers/block_refinement#diffusers.BlockRefinementScheduler) أو [DiscreteDDIMScheduler](/docs/diffusers/v0.43.0/ar/api/schedulers/discrete_ddim#diffusers.DiscreteDDIMScheduler) أو [EntropyBoundScheduler](/docs/diffusers/v0.43.0/ar/api/schedulers/entropy_bound#diffusers.EntropyBoundScheduler)) : المُعيّن الذي يُثبّت رموز اللوحة ويضيف الضوضاء إليها في كل خطوة إزالة ضوضاء.

processor ([ProcessorMixin](https://huggingface.co/docs/transformers/v5.22.2/en/main_classes/processors#transformers.ProcessorMixin)) : المعالج المستخدم لتطبيق قالب المحادثة وفك ترميز الرموز المولّدة.

خط أنابيب لتوليد النص بالانتشار على مستوى الكتل في DiffusionGemma.

DiffusionGemma هو نموذج مُرمِّز-مُفكِّك يعتمد على الانتشار على مستوى الكتل: يقرأ المُرمِّز السببي المُوجِّه النظيف (وأي كتل تم توليدها سابقًا) إلى ذاكرة KV، بينما يُزيل المُفكِّك الاتجاهي الضوضاء من «لوحة» بحجم ثابت يتكوّن من `canvas_length` رمزًا من خلال الانتباه المتقاطع إلى تلك الذاكرة. يتناوب التوليد بين حلقة خارجية ذاتية التراجع على مستوى اللوحات وحلقة داخلية لإزالة الضوضاء، حيث يقوم كل خطوة فيها بسحب رموز مرشحة، وتثبيت الأكثر ثقة عبر [BlockRefinementScheduler](/docs/diffusers/v0.43.0/ar/api/schedulers/block_refinement#diffusers.BlockRefinementScheduler) (وضع إتلاف منتظم، `mask_token_id=None`)، وإعادة إضافة الضوضاء إلى البقية.

من المتوقع أن يكون النموذج مثيلًا من `DiffusionGemmaForBlockDiffusion` يعرّف `forward(input_ids, decoder_input_ids=..., self_conditioning_logits=..., ...)` ويعيد قيم logits بأبعاد `[batch, canvas_length, vocab_size]` على اللوحة. راجع بطاقة النموذج على https://huggingface.co/google/diffusiongemma-26B-A4B-it.

#### __call__[[diffusers.DiffusionGemmaPipeline.__call__]]

```python
__call__(prompt: str | list[str] | None = None, messages: list[dict] | None = None, image: Any | list[Any] | None = None, add_generation_prompt: bool = True, gen_length: int = 256, num_inference_steps: int = 48, temperature: float = 0.0, cache_implementation: str | None = None, eos_early_stop: bool = True, eos_token_id: int | None = None, stability_threshold: int = 1, confidence_threshold: float | None = 0.005, generator: torch.Generator | None = None, output_type: str = 'text', return_dict: bool = True, callback_on_step_end: Callable[[Any, int, int, dict], dict] | PipelineCallback | MultiPipelineCallbacks | None = None, callback_on_step_end_tensor_inputs: list[str] | None = None)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/diffusion_gemma/pipeline_diffusion_gemma.py#L163)

**المعاملات:**

prompt (`str` أو `List[str]`، *اختياري*) : نصّ الأمر، مُغلَّف بقالب المحادثة ومُرمَّز بواسطة المعالج. قدّم هذا أو `messages`.

messages (`List[Dict]`، *اختياري*) : محادثة دردشة خام للتشفير، مثل `[{"role": "user", "content": "Hello"}]` أو محادثة متعددة الأدوار / متعددة الوسائط. استخدم هذا بدلاً من `prompt` لأي شيء يتجاوز دور مستخدم واحد.

image (`PIL.Image.Image` أو `List`، *اختياري*) : صورة أو صور لاقترانها مع `prompt` للتوليد متعدد الوسائط؛ يقوم المعالج بتحويلها إلى مدخلات الصور الخاصة بالنموذج. للحصول على تخطيطات أغنى، ضع محتوى الصورة مباشرةً في `messages`.

add_generation_prompt (`bool`، القيمة الافتراضية `True`) : ما إذا كان يجب إضافة موجه التوليد عند تطبيق قالب المحادثة.

gen_length (`int`، القيمة الافتراضية `256`) : عدد الرموز التي سيتم توليدها، مع تقريبها لأعلى إلى مضاعف لطول `canvas_length` الخاص بالنموذج.

num_inference_steps (`int`، القيمة الافتراضية `48`) : عدد خطوات إزالة الضوضاء لكل لوحة.

temperature (`float`، القيمة الافتراضية `0.0`) : درجة حرارة العينة لـ `DiscreteDDIMScheduler`/`BlockRefinementScheduler` (حيث أن `0.0` تعني أخذ القيمة القصوى greedily)؛ يتجاهل `EntropyBoundScheduler` هذه القيمة ويخفّض حرارته الخاصة. إعدادات العينة الأخرى (مثل `top_k`، `threshold`، `t_min`/`t_max`) هي إعدادات للمجدول (scheduler)؛ اضبطها على المجدول، على سبيل المثال `pipe.scheduler = BlockRefinementScheduler.from_config(pipe.scheduler.config, top_k=...)`.

cache_implementation (`str`, *اختياري*) : اضبطه على `"static"` لملء المُشفِّر مرة واحدة لكل كتلة في `StaticCache` دائم، وتشغيل المُفكِّك ضده بأشكال ثابتة، بدلاً من إعادة ترميز التسلسل الكامل في كل خطوة. كما تتيح لك الأشكال الثابتة تجميع المُفكِّك، على سبيل المثال `pipe.model.model.decoder = torch.compile(pipe.model.model.decoder, fullgraph=True)`.
eos_early_stop (`bool`، القيمة الافتراضية `True`) : ما إذا كان يجب التوقف عن توليد المزيد من اللوحات بمجرد أن تُصدر كل تسلسل رمز EOS.
eos_token_id (`int`، *اختياري*) : معرّف رمز EOS للإيقاف المبكر. في حال عدم توفره، يُرجع إلى مُجزّئ المُعالِج.
stability_threshold (`int`، القيمة الافتراضية `1`) : عدد الخطوات المتتالية التي يجب أن تبقى فيها توقع argmax الخاص بمثال دون تغيير حتى يُحتسب ذلك المثال مستقرًا. يُستخدم فقط عند تعيين `confidence_threshold`.

confidence_threshold (`float`، *اختياري*، القيمة الافتراضية `0.005`) : تجميد كل مثال بمجرد أن يصبح مستقرًا (انظر `stability_threshold`) وأن متوسط إنتروبيا الرمز الواحد للتنبؤات المُشكَّلة بواسطة المُجدول (scheduler-shaped prediction logits) يكون أقل من هذه القيمة. ينتهي حلقة إزالة الضوضاء (denoising loop) للكتلة بمجرد تجميد جميع الأمثلة. يُسرّع عملية التوليد مع الحفاظ على الجودة نفسها؛ القيمة الافتراضية تتطابق مع نقطة الفحص (checkpoint) المُصدَّرة. اضبطها على `None` لتشغيل جميع `num_inference_steps` دائمًا.

generator (`torch.Generator`، *اختياري*) : مولّد الأرقام العشوائية (RNG) للعينات.

output_type (`str`، الافتراضي `"text"`) : `"text"` يترجم التسلسلات إلى نصوص (يتطلب معالجًا)؛ `"seq"` يعيد معرّفات الرموز فقط.
return_dict (`bool`، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع [DiffusionGemmaPipelineOutput](/docs/diffusers/v0.43.0/ar/api/pipelines/diffusion_gemma#diffusers.DiffusionGemmaPipelineOutput) بدلاً من tuple.

callback_on_step_end (`Callable` أو `PipelineCallback`، *اختياري*) : استدعاء يُنفَّذ بعد كل خطوة إزالة ضوضاء بتوقيع `callback_on_step_end(self, step, timestep, callback_kwargs)`. مفاتيح المصفوفات المسموح بها: `canvas`، `logits`.
callback_on_step_end_tensor_inputs (`List[str]`، *اختياري*) : مفاتيح المصفوفات (Tensor) التي يجب تمريرها إلى الدالة الاستدعائية (callback).

**يعيد:** [DiffusionGemmaPipelineOutput](/docs/diffusers/v0.43.0/ar/api/pipelines/diffusion_gemma#diffusers.DiffusionGemmaPipelineOutput) أو `tuple`

معرّفات الرموز المولّدة (`sequences`) و، في حالة `output_type="text"`، `texts` المُفكّكة.

توليد النص باستخدام الانتشار الكتلوي.

أمثلة:
```python
>>> import torch
>>> from transformers import AutoProcessor, DiffusionGemmaForBlockDiffusion
>>> from diffusers import BlockRefinementScheduler, DiffusionGemmaPipeline
>>> model_id = "google/diffusiongemma-26B-A4B-it"
>>> model = DiffusionGemmaForBlockDiffusion.from_pretrained(model_id, dtype=torch.bfloat16, device_map="auto")
>>> processor = AutoProcessor.from_pretrained(model_id)
>>> scheduler = BlockRefinementScheduler()
>>> pipe = DiffusionGemmaPipeline(model=model, scheduler=scheduler, processor=processor)
>>> output = pipe(prompt="Why is the sky blue?", gen_length=256)
>>> print(output.texts[0])
```

## DiffusionGemmaPipelineOutput[[diffusers.DiffusionGemmaPipelineOutput]]

#### diffusers.DiffusionGemmaPipelineOutput[[diffusers.DiffusionGemmaPipelineOutput]]

```python
diffusers.DiffusionGemmaPipelineOutput(sequences: torch.LongTensor, texts: list[str] | None = None)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/diffusion_gemma/pipeline_output.py#L25)

**المعاملات:**

sequences (`torch.LongTensor` من الشكل `(batch_size, gen_length)`) : معرّفات الرموز المولّدة (تمت إزالة النص التمهيدي).

texts (`list[str]`، *اختياري*) : النص المُفكَّك، سلسلة نصية واحدة لكل تسلسل. يُعيَّن فقط عند `output_type="text"`.

فئة الإخراج لتوليد الانتشار على مستوى الكتل في DiffusionGemma.
Xet Storage Details

Size:: 23.3 kB
Xet hash:: 522177eb302e46a13f79ed7f6b458adc7edf4c5438ccc122801011cf52019def
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.