# LLaDA2

[LLaDA2](https://huggingface.co/collections/inclusionAI/llada21) هو عائلة من نماذج اللغة الانتشارية المنفصلة التي تولّد النص من خلال تحسين تكراري على مستوى الكتل. وبدلاً من التوليد التتابعي رمزًا تلو الآخر، يبدأ LLaDA2 بتسلسل مقنّع بالكامل ثم يكشف الرموز تدريجيًا بناءً على درجة الثقة عبر خطوات تحسين متعددة.

## الاستخدام

```py
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

from diffusers import BlockRefinementScheduler, LLaDA2Pipeline

model_id = "inclusionAI/LLaDA2.1-mini"
model = AutoModelForCausalLM.from_pretrained(
    model_id, trust_remote_code=True, dtype=torch.bfloat16, device_map="auto"
)
tokenizer = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
scheduler = BlockRefinementScheduler()

pipe = LLaDA2Pipeline(model=model, scheduler=scheduler, tokenizer=tokenizer)
output = pipe(
    prompt="Write a short poem about the ocean.",
    gen_length=256,
    block_length=32,
    num_inference_steps=32,
    threshold=0.7,
    editing_threshold=0.5,
    max_post_steps=16,
    temperature=0.0,
)
print(output.texts[0])
```

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

تُنفَّذ استدعاءات الأحداث (Callbacks) بعد كل خطوة تحسين. مرّر `callback_on_step_end_tensor_inputs` لاختيار المصفوفات (tensors) التي سيتم تضمينها في `callback_kwargs`. في التنفيذ الحالي، يتم توفير `block_x` (نافذة التسلسل قيد التحسين) و`transfer_index` (قناع التثبيت لملء الأقنعة)؛ أعد `{"block_x": ...}` من استدعاء الحدث لاستبدال النافذة.

```py
def on_step_end(pipe, step, timestep, callback_kwargs):
    block_x = callback_kwargs["block_x"]
    # Inspect or modify `block_x` here.
    return {"block_x": block_x}

out = pipe(
    prompt="Write a short poem.",
    callback_on_step_end=on_step_end,
    callback_on_step_end_tensor_inputs=["block_x"],
)
```

## المعلمات الموصى بها

تدعم نماذج LLaDA2.1 وضعين:

| الوضع | `threshold` | `editing_threshold` | `max_post_steps` |
|------|-------------|---------------------|------------------|
| الجودة | 0.7 | 0.5 | 16 |
| السرعة | 0.5 | `None` | 16 |

مرّر `editing_threshold=None` أو `0.0` أو قيمة سالبة لتعطيل التعديل بعد القناع.

لنماذج LLaDA2.0، عطّل التحرير عن طريق تمرير `editing_threshold=None` أو `0.0`.

لجميع النماذج: `block_length=32`، `temperature=0.0`، `num_inference_steps=32`.

## LLaDA2Pipeline[[diffusers.LLaDA2Pipeline]]

#### diffusers.LLaDA2Pipeline[[diffusers.LLaDA2Pipeline]]

```python
diffusers.LLaDA2Pipeline(model: Any, scheduler: BlockRefinementScheduler, tokenizer: Any | None = None)
```

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

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

تحتفظ هذه المسار الوظيفي بسلسلة قالب مملوءة بـ`mask_token_id` وتُحسّنها على شكل كتل. في كل خطوة تحسين، تُسحب رموز مرشحة للكتلة النشطة وتُثبَّت مجموعة فرعية منها بناءً على درجة الثقة.

من المتوقع أن يقبل النموذج قناع الانتباه و`position_ids`، وأن يعيد قيم اللوجيت على شكل `[batch, seq, vocab_size]`.

#### __call__[[diffusers.LLaDA2Pipeline.__call__]]

```python
__call__(prompt: str | list[str] | None = None, messages: list[dict[str, str]] | None = None, input_ids: torch.LongTensor | None = None, attention_mask: torch.LongTensor | None = None, use_chat_template: bool = True, add_generation_prompt: bool = True, gen_length: int = 2048, block_length: int | None = None, num_inference_steps: int = 32, temperature: float = 0.0, top_p: float | None = None, top_k: int | None = None, sampling_method: str = 'multinomial', threshold: float = 0.7, editing_threshold: float | None = 0.5, max_post_steps: int = 16, minimal_topk: int = 1, eos_early_stop: bool = True, eos_token_id: int | None = None, mask_token_id: int | None = None, generator: torch.Generator | None = None, output_type: str = 'text', return_dict: bool = True, callback_on_step_end: Callable[[int, int, dict], None] | 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/llada2/pipeline_llada2.py#L242)

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

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

messages (`List[Dict[str, str]]`، *اختياري*) : رسائل الدردشة التي سيتم ترميزها (مثل `[{"role": "user", "content": "Hello"}]`). له الأولوية على `prompt` عند تقديمه. يتطلب مُرمِّزًا (tokenizer) يحتوي على `apply_chat_template`.

input_ids (`torch.LongTensor`، *اختياري*) : معرّفات مدخلات مُجزّأة مسبقًا. لها الأولوية على `prompt` و`messages`.

attention_mask (`torch.LongTensor`, *اختياري*) : قناع لكل رمز (1 للرموز الصالحة في الاستعلام، 0 للتعبئة) يطابق شكل `input_ids`. يُستخدم فقط عند تقديم `input_ids`. عند إهماله (مع تقديم `input_ids`)، تُعامل جميع المواضع على أنها صالحة. عند بناء المدخلات من `prompt` / `messages`، يُنقل قناع المُجزّئ تلقائيًا.

use_chat_template (`bool`، القيمة الافتراضية `True`) : ما إذا كان سيتم تغليف الأمر (prompt) في قالب محادثة.

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

gen_length (`int`) : عدد الرموز التي سيتم توليدها.

block_length (`int`، *اختياري*) : حجم الكتلة للتحسين. إذا لم يُقدَّم، يُستخدم `block_length` المُهيأ في المجدول.

num_inference_steps (`int`) : عدد خطوات التحسين لكل كتلة.

temperature (`float`) : درجة حرارة العينة.

top_p (`float`، *اختياري*) : حدّ قطع عينات النواة.

top_k (`int`، *اختياري*) : حدّ قطع أخذ العينة Top-k.

sampling_method (`str`) : طريقة أخذ العينات (`auto`، `greedy`، `multinomial`).

threshold (`float`) : عتبة الثقة لالتزام الرموز.

editing_threshold (`float`, *اختياري*) : عتبة الثقة لتحرير الرموز التي تم التأكيد عليها مسبقًا (غير المقنّعة). عند أن تكون موجبة، بعد حل جميع الرموز المقنّعة في الكتلة، يستمر خط المعالجة في التحسين: إذا توقع النموذج رمزًا مختلفًا بثقة تتجاوز هذه العتبة، يتم استبدال الرمز الحالي. اضبط القيمة على `None` أو `0.0` أو قيمة سالبة لتعطيل التحرير. القيمة الافتراضية هي `0.5`.

max_post_steps (`int`) : الحد الأقصى لعدد تكرارات التحسين الإضافية بعد حل جميع رموز الأقنعة في الكتلة. يُستخدم فقط عند تفعيل `editing_threshold`. القيمة الافتراضية هي `16`.

minimal_topk (`int`) : الحد الأدنى لعدد الرموز التي يجب تثبيتها في كل خطوة.

eos_early_stop (`bool`) : ما إذا كان يجب التوقف بعد تثبيت EOS في كتلة.

eos_token_id (`int`، *اختياري*) : معرّف رمز EOS المستخدم للإيقاف المبكر.

mask_token_id (`int`، *اختياري*) : معرّف رمز القناع (Mask token) المستخدم للقالب.

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

output_type (`str`، الافتراضي `"text"`) : صيغة الإخراج. `"text"` يرمز التسلسلات إلى نصوص (يتطلب مُرمِّزًا). `"seq"` يعيد تسلسلات معرّفات الرموز الخام فقط.

return_dict (`bool`، *اختياري*، الافتراضي `True`) : ما إذا كان يجب إرجاع [LLaDA2PipelineOutput](/docs/diffusers/v0.43.0/ar/api/pipelines/llada2#diffusers.LLaDA2PipelineOutput) بدلاً من tuple.

callback_on_step_end (`Callable` أو `PipelineCallback`، *اختياري*) : استدعاء يُنفَّذ بعد كل خطوة تحسين، وتوقيعه `callback_on_step_end(self, step: int, timestep: int, callback_kwargs: Dict)`.

callback_on_step_end_tensor_inputs (`List[str]`، *اختياري*) : مفاتيح المصفوفات (Tensor) التي يجب تمريرها إلى الدالة الاستدعائية (callback). المفاتيح المسموح بها: `block_x`، `transfer_index`، `editing_transfer_index`، `sampled_tokens`، `sampled_probs`، `active_block`.

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

إذا كان `return_dict` هو `True`، يُعاد [LLaDA2PipelineOutput](/docs/diffusers/v0.43.0/ar/api/pipelines/llada2#diffusers.LLaDA2PipelineOutput)، وإلا يُعاد `tuple` حيث العنصر الأول هو معرّفات الرموز المولّدة (`torch.LongTensor`) والعنصر الثاني هو النصوص المُفكّكة (`list[str]`)، أو `None` عندما يكون `output_type` هو `"seq"`.

توليد النص مع تحسين على مستوى الكتل.

أمثلة:
```python
>>> import torch
>>> from transformers import AutoModelForCausalLM, AutoTokenizer
>>> from diffusers import BlockRefinementScheduler, LLaDA2Pipeline

>>> model_id = "inclusionAI/LLaDA2.1-mini"
>>> model = AutoModelForCausalLM.from_pretrained(
...     model_id, trust_remote_code=True, dtype=torch.bfloat16, device_map="auto"
... )
>>> tokenizer = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
>>> scheduler = BlockRefinementScheduler()

>>> pipe = LLaDA2Pipeline(model=model, scheduler=scheduler, tokenizer=tokenizer)
>>> output = pipe(prompt="What is the meaning of life?", gen_length=256)
>>> print(output.texts[0])
```

## LLaDA2PipelineOutput[[diffusers.LLaDA2PipelineOutput]]

#### diffusers.LLaDA2PipelineOutput[[diffusers.LLaDA2PipelineOutput]]

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

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