# DiffusionGemma

DiffusionGemma, blok-diffüzyon tabanlı bir kodlayıcı-çözücü (encoder-decoder) dil modelidir. Nedensel (causal) kodlayıcı, temiz istemi (prompt) ve daha önce üretilmiş blokları bir KV önbelleğine (KV cache) okur; çift yönlü (bidirectional) çözücü ise bu önbelleğe çapraz dikkat (cross-attention) uygulayarak `canvas_length` token boyutunda sabit bir "tuval"i (canvas) gürültüden arındırır. Üretim, tuvaller üzerinde dış bir otoregresif döngü ile iç bir gürültüden arındırma döngüsünü sırayla çalıştırır; her adımda aday token'lar örneklenir, en yüksek güvene sahip olanlar [BlockRefinementScheduler](/docs/diffusers/main/tr/api/schedulers/block_refinement#diffusers.BlockRefinementScheduler) aracılığıyla düzgün bozulma (uniform corruption) modunda sabitlenir ve kalanlar yeniden gürültülenir. Modelin kendisi `transformers` kütüphanesinde `DiffusionGemmaForBlockDiffusion` olarak yer alır; yayınlanan kontrol noktası (checkpoint) ise [`google/diffusiongemma-26B-A4B-it`](https://huggingface.co/google/diffusiongemma-26B-A4B-it)'tir.

## Kullanım

```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`, tuval başına gürültü azaltma adım sayısını belirtir (48, yayınlanan checkpoint ile eşleşir); daha az adım daha hızlıdır ancak kaliteyi düşürür. `cache_implementation="static"`, decoder'ın cudagraphs ile `torch.compile`-lenmesine olanak tanır (bkz. [Statik önbellek ve derleme](#static-cache-and-compilation)); daha basit bir dinamik önbellek çalıştırması için her ikisini de kaldırın.

Çok turlu veya çok modlu girdiler için `prompt` yerine ham bir `messages` sohbeti iletin. Bu, işleyicinin sohbet şablonundan geçirdiği, standart sohbet biçimindeki `{"role", "content"}` sözlüklerinden oluşan bir listedir:

```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)
```

Tek bir kullanıcı turu için `messages` parametresini atlayıp `image` değerini `prompt` ile birlikte geçebilirsiniz; işlemci bunu otomatik olarak modelin görüntü girdilerine dönüştürür.

## Zamanlayıcılar

Zamanlayıcı, her tuvali gürültüden arındıran örnekleyicidir ve değiştirilebilir: başka hiçbir şeye dokunmadan örneklemeyi değiştirme stratejisini değiştirmek için onu değiştirin. Üç zamanlayıcı kullanılabilir:

- [BlockRefinementScheduler](/docs/diffusers/main/tr/api/schedulers/block_refinement#diffusers.BlockRefinementScheduler) (varsayılan): her adımda en yüksek güvene sahip tokenları (eşik olan `threshold` üzerinde olanlar ve adımlar arasında eşit dağıtılan kota) onaylar ve kalanları yeniden gürültüler. `editing_threshold` ayrıca, daha önce onaylanmış tokenların yeniden düzenlenmesine olanak tanır.
- [DiscreteDDIMScheduler](/docs/diffusers/main/tr/api/schedulers/discrete_ddim#diffusers.DiscreteDDIMScheduler): her konumu, uniform bozma sürecinin (D3PM) kesin ayrık posterior dağılımından örnekler. Parametresizdir ve son adım, tahmin edilen tokenları deterministik olarak sabitler.
- [EntropyBoundScheduler](/docs/diffusers/main/tr/api/schedulers/entropy_bound#diffusers.EntropyBoundScheduler): `entropy_bound` altında kalan ortak entropiye sahip en düşük entropili konumları kabul eder, böylece yaklaşık bağımsız jetonlar birlikte kabul edilir. Örnekleme sıcaklığını ilk adımda `t_max` (`0.8`) değerinden son adımda `t_min` (`0.4`) değerine kadar düşürür; bu, yayınlanan kontrol noktasının örnekleme cihazıyla uyumludur.

```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])
```

Zamanlayıcıya özgü örneklem ayarları (blok-ince ayar `threshold`/`top_k`, entropi sınırı, ...) zamanlayıcı yapılandırmasında ayarlanır:

```py
from diffusers import BlockRefinementScheduler

pipe.scheduler = BlockRefinementScheduler.from_config(pipe.scheduler.config, threshold=0.9)
```

`EntropyBoundScheduler`, gürültü azaltma adımları boyunca örneklem sıcaklığını (`t_max`/`t_min`) içsel olarak azaltır; `DiscreteDDIMScheduler` ve `BlockRefinementScheduler`, pipeline'a geçirilen düz `temperature` değerini kullanır (açgözlü için `0.0`).

### Tahminci-düzeltici örneklemesi

`DiscreteDDIMScheduler`, [Uniform Diffusion Models Revisited: Leave-One-Out Denoiser and Absorbing State Reformulation](https://huggingface.co/papers/2605.22765) makalesindeki leave-one-out predictor-corrector yaklaşımını destekler. Bu yaklaşım, gürültülü marjinalin tek koordinat koşullu dağılımından en az güvenilen konumları yeniden örnekleyerek marjinali değişmeden bırakır ve ek eğitim maliyeti olmadan üretimi iyileştirir; bu işlem `corrector_steps` adet Gibbs süpürmesiyle tuvali rafine eder. Yayımlanan checkpoint üzerinde doğrudan çalışır: uniform diffusion için denoiser ile leave-one-out posterior kapalı formda birbirinin yerine kullanılabilir, bu sayede corrector yeniden eğitim gerektirmeden ihtiyaç duyduğu leave-one-out niceliklerini geri kazanır.

Corrector taramaları, `num_inference_steps` bütçesine eklenmek yerine bu bütçenin içine katılır: pipeline daha az predictor adımı çalıştırır ve açılan ileri geçişleri corrector'lara harcar; böylece modelin toplam ileri geçiş sayısı `num_inference_steps` olarak kalır ve predictor-corrector maliyeti, düz ancestral sampling ile aynıdır.

```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 adaptörleri

Gürültü azaltıcı bir 🤗 Transformers modelidir, bu nedenle adaptörler, diffusers `load_lora_weights` API'si yerine modelin yerel [PEFT](https://huggingface.co/docs/peft) entegrasyonu üzerinden yüklenir. Bu entegrasyon adaptör türünden bağımsız olduğundan, aynı çağrılar LoRA, DoRA veya herhangi bir diğer PEFT adaptörünü (ör. TRL'nin `SFTTrainer` çıktısı) yükler. Adaptörleri doğrudan model bileşeni üzerinde yönetin:

```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")
```

Adaptörler aktif ve birleştirilmemiş kalır: DiffusionGemma, kodlayıcı ve çözücü temel ağırlıklarını birbirine bağlar; bu nedenle bir adaptörü bunlara birleştirmek her iki dalı da bozar.

## Statik önbellek ve derleme

Pipeline, kodlayıcıyı (encoder) blok başına bir kez ön doldurur ve yeniden kullanılabilir bir önbelleğe (varsayılan olarak `DynamicCache`) yerleştirir. `cache_implementation="static"` parametresini geçmek, bunun yerine sabit şekilli bir `StaticCache` kullanır; bu önbelleğin şekilleri, çözücüye (decoder) cudagraphs ile `torch.compile` uygulayarak ek bir hızlanma elde etmenizi sağlar (pipeline her adımı işaretler ve cudagraph belleğinin üzerine yazılmaması için logitleri klonlar); bu, [Kullanım](#usage) bölümünde gösterilen yapılandırmadır. Daha basit bir dinamik önbellek çalıştırması için hem `torch.compile` çağrısını hem de `cache_implementation="static"` parametresini kaldırın.

## Uyarlanabilir durdurma

Bir blok genellikle tüm `num_inference_steps` harcanmadan önce yakınsar; bu nedenle varsayılan olarak pipeline, argmax tahmini `stability_threshold` adım boyunca kararlı kaldığında ve token başına ortalama entropisi `confidence_threshold` değerinin altına düştüğünde her batch örneğini dondurur (`0.005`, yayınlanan checkpoint'te kullanılan değer). Gürültüden arındırma döngüsü, tüm örnekler dondurulduğunda sona erer. Bu, eşleşen kalitede decoder ileri geçiş sayısını yaklaşık yarıya indirir ve en büyük tek başına verimlilik kaldıraçtır. Her zaman tam `num_inference_steps` adımını çalıştırmak için `confidence_threshold=None` parametresini iletin:

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

## Geri Çağrılar

Callbacks, her gürültü azaltma adımının ardından çalışır. `callback_kwargs` içinde hangi tensörlerin yer alacağını seçmek için `callback_on_step_end_tensor_inputs` parametresini iletin; `canvas` (mevcut blok jetonları) ve `logits` kullanılabilir. Canvas'ı değiştirmek için callback'den `{"canvas": ...}` döndürün.

```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)
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/diffusion_gemma/pipeline_diffusion_gemma.py#L53)

**Parametreler:**

model ([DiffusionGemmaForBlockDiffusion](https://huggingface.co/docs/transformers/main/en/model_doc/diffusion_gemma#transformers.DiffusionGemmaForBlockDiffusion)) : Blok-difüzyon gürültü azaltıcı (bağlı ağırlıklı nedensel kodlayıcı + çift yönlü çözücü).

scheduler ([BlockRefinementScheduler](/docs/diffusers/main/tr/api/schedulers/block_refinement#diffusers.BlockRefinementScheduler), [DiscreteDDIMScheduler](/docs/diffusers/main/tr/api/schedulers/discrete_ddim#diffusers.DiscreteDDIMScheduler) veya [EntropyBoundScheduler](/docs/diffusers/main/tr/api/schedulers/entropy_bound#diffusers.EntropyBoundScheduler)) : Her gürültü azaltma adımında tuval token'larını taahhüt eden ve yeniden gürültüleyen örnekleyici.

processor ([ProcessorMixin](https://huggingface.co/docs/transformers/main/en/main_classes/processors#transformers.ProcessorMixin)) : Sohbet şablonunu uygulamak ve üretilen token'ları çözmek için kullanılan işlemci.

DiffusionGemma blok-difüzyon metin üretimi için pipeline.

DiffusionGemma, blok-difüzyon kodlayıcı-çözücü (encoder-decoder) modelidir: nedensel kodlayıcı, temiz istemi (ve daha önce üretilmiş blokları) bir KV önbelleğine okur; çift yönlü çözücü ise bu önbelleğe çapraz dikkat (cross-attention) uygulayarak `canvas_length` token boyutunda sabit bir "tuval"i gürültüden arındırır. Üretim, tuvaller üzerinde dış bir otoregresif döngü ile iç bir gürültüden arındırma döngüsünü sırayla çalıştırır; her adımda aday tokenlar örneklenir, en güvenilenler [BlockRefinementScheduler](/docs/diffusers/main/tr/api/schedulers/block_refinement#diffusers.BlockRefinementScheduler) (düz bozulma modu, `mask_token_id=None`) aracılığıyla sabitlenir ve kalanlar yeniden gürültülenir.

Modelin, tuval üzerinde `[batch, canvas_length, vocab_size]` biçiminde logitler döndüren ve `forward(input_ids, decoder_input_ids=..., self_conditioning_logits=..., ...)` yöntemlerini açıklayan bir `DiffusionGemmaForBlockDiffusion` örneği olması beklenir. Model kartı için https://huggingface.co/google/diffusiongemma-26B-A4B-it adresine bakın.

#### __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)
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/diffusion_gemma/pipeline_diffusion_gemma.py#L163)

**Parametreler:**

prompt (`str` veya `List[str]`, *isteğe bağlı*) : İşleyici tarafından sohbet şablonuna sarılıp tokenize edilen istem metni. Bunun ya da `messages` parametresinin birini sağlayın.

messages (`List[Dict]`, *isteğe bağlı*) : Kodlanacak ham bir sohbet konuşması, örneğin `[{"role": "user", "content": "Hello"}]` veya çok turlu / çok modallı bir konuşma. Tek bir kullanıcı turundan fazlası için bunu `prompt` yerine kullanın.

image (`PIL.Image.Image` veya `List`, *isteğe bağlı*) : Çok modlu üretim için `prompt` ile eşleştirilecek görsel(ler); işlemci bunları modelin görsel girdilerine dönüştürür. Daha zengin yerleşimler için görsel içeriği doğrudan `messages` içine koyun.

add_generation_prompt (`bool`, varsayılan `True`) : Sohbet şablonu uygulanırken üretim istemcinin eklenip eklenmeyeceğini belirtir.

gen_length (`int`, varsayılan `256`) : Üretilecek jeton sayısı, modelin `canvas_length` değerinin katına yuvarlanır.

num_inference_steps (`int`, varsayılan `48`) : Tuval başına gürültü azaltma adımı sayısı.

temperature (`float`, varsayılan `0.0`) : `DiscreteDDIMScheduler`/`BlockRefinementScheduler` için örneklem sıcaklığı (`0.0` açgözlüdür); `EntropyBoundScheduler` bunu yoksayar ve kendi sıcaklığını soğutur. Diğer örneklem ayarları (ör. `top_k`, `threshold`, `t_min`/`t_max`) zamanlayıcı yapılandırmasıdır; bunları zamanlayıcıda ayarlayın, örn. `pipe.scheduler = BlockRefinementScheduler.from_config(pipe.scheduler.config, top_k=...)`.

cache_implementation (`str`, *isteğe bağlı*) : Her adımda tam diziyi yeniden kodlamak yerine, kodlayıcıyı blok başına bir kez kalıcı bir `StaticCache` içine önceden doldurmak ve sabit şekillerle kodlayıcıyı buna karşı çalıştırmak için `"static"` olarak ayarlayın. Sabit şekiller, kodlayıcıyı derlemenize de olanak tanır, örneğin `pipe.model.model.decoder = torch.compile(pipe.model.model.decoder, fullgraph=True)`.

eos_early_stop (`bool`, varsayılan `True`) : Her dizi EOS ürettiğinde, ek tuval üretmenin durdurulup durdurulmayacağı.

eos_token_id (`int`, *isteğe bağlı*) : Erken durdurma için EOS token kimliği. İşleyicinin (processor) tokenizer'ına geri düşer.

stability_threshold (`int`, varsayılan `1`) : Bir örneğin argmax tahmininin, o örneğin kararlı sayılması için kaç ardışık adımda değişmeden kalması gerektiğini belirtir. Yalnızca `confidence_threshold` ayarlandığında kullanılır.

confidence_threshold (`float`, *opsiyonel*, varsayılan `0.005`) : Her örneği, kararlı hale geldiğinde (bkz. `stability_threshold`) ve zamanlayıcı biçimli tahmin logitlerinin token başına ortalama entropisi bu değerin altında olduğunda dondurur. Blokta gürültü azaltma döngüsü, tüm örnekler dondurulduğunda sona erer. Eşleşen kalitede üretimi hızlandırır; varsayılan değer, yayınlanan kontrol noktasıyla eşleşir. Tüm `num_inference_steps` adımının her zaman çalıştırılması için `None` olarak ayarlayın.

generator (`torch.Generator`, *isteğe bağlı*) : Örnekleme için RNG.

output_type (`str`, varsayılan `"text"`) : `"text"` dizileri metinlere çözer (işleyici gerektirir); `"seq"` yalnızca jeton kimliklerini döndürür.

return_dict (`bool`, varsayılan `True`) : Bir tuple yerine [DiffusionGemmaPipelineOutput](/docs/diffusers/main/tr/api/pipelines/diffusion_gemma#diffusers.DiffusionGemmaPipelineOutput) döndürülüp döndürülmediğini belirtir.

callback_on_step_end (`Callable` veya `PipelineCallback`, *isteğe bağlı*) : İmzası `callback_on_step_end(self, step, timestep, callback_kwargs)` olan, her gürültü azaltma adımından sonra çalıştırılan geri çağrı. İzin verilen tensör anahtarları: `canvas`, `logits`.

callback_on_step_end_tensor_inputs (`List[str]`, *isteğe bağlı*) : Geri çağrıya iletilecek Tensor anahtarları.

**Dönüş:** [DiffusionGemmaPipelineOutput](/docs/diffusers/main/tr/api/pipelines/diffusion_gemma#diffusers.DiffusionGemmaPipelineOutput) veya `tuple`

Oluşturulan token kimlikleri (`sequences`) ve `output_type="text"` için çözümlenmiş `texts`.

Blok difüzyonu ile metin üretin.

Örnekler:
```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)
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/diffusion_gemma/pipeline_output.py#L25)

**Parametreler:**

sequences (`torch.LongTensor`, şekli `(batch_size, gen_length)`) : Üretilen token kimlikleri (istem çıkarılmıştır).

texts (`list[str]`, *isteğe bağlı*) : Çözümlenmiş metin, her dizi için bir dize. Yalnızca `output_type="text"` için ayarlanır.

DiffusionGemma blok-difüzyon üretimi için çıktı sınıfı.