huggingface--transformers/docs/source/en/model_doc/diffusion_gemma.md

This model was contributed to Hugging Face Transformers on 2026-06-10.

DiffusionGemma

Overview

DiffusionGemma is engineered to reduce the sequential bottlenecks of standard causal language models. It employs an encoder-decoder architecture specifically optimized for inference speed.

The encoder operates in a prefill capacity, processing the initial prompt and generating the KV cache. The decoder then utilizes bidirectional attention to process an input block (a 'canvas') of tokens, accessing the cached context via cross-attention.

During inference, DiffusionGemma leverages multi-canvas sampling. Rather than generating one token at a time, the model iteratively denoises a full block of tokens using a diffusion sampler. Once a canvas is fully denoised, it is processed by the encoder and appended to the KV cache, after which the model generates the next canvas. This block-autoregressive approach facilitates text generation at higher speeds.

You can find the model card and checkpoint here. You can find a visual guide to the model here.

Usage examples

Despite it being a text diffusion model and having a custom generation loop, most of the interface is shared with other models that can generate text with [DiffusionGemmaGenerationMixin.generate]. If you're using another transformers model in your app, you should be able to directly replace it with this model.

Note

DiffusionGemma is available in both Transformers and Diffusers, but Diffusers is its primary home. Diffusers has the full set of scheduling options, pipeline utilities, and new features (additional schedulers, stopping criteria, sampling strategies) are only added there. See the DiffusionGemma for usage examples, and open an issue on Diffusers to experiment with different schedulers or request a feature. The Transformers implementation only receives bug fixes but no new features.

Common caveats

• DiffusionGemma doesn't accept use_cache. It always uses a KV cache;
• Support for common flags like top_k won't be available at release day, but will be added over time if they are compatible with text diffusion.

Basic example

from transformers import DiffusionGemmaForBlockDiffusion, AutoProcessor


model = DiffusionGemmaForBlockDiffusion.from_pretrained(
    "google/diffusiongemma-26B-A4B-it", device_map="auto",
)
processor = AutoProcessor.from_pretrained("google/diffusiongemma-26B-A4B-it")

messages = [
    {
        "role": "user", "content": [
            {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"},
            {"type": "text", "text": "What is shown in this image?"},
        ]
    },
]
inputs = processor.apply_chat_template(
    messages,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
    add_generation_prompt=True,
    # Add the following to enable thinking
    # enable_thinking=True,
).to(model.device)
input_len = inputs["input_ids"].shape[-1]

# Set `cache_implementation="static"` in `generate` to trigger `torch.compile`.
# Compilation is much faster, after warming up!
output = model.generate(**inputs, max_new_tokens=256)
print(processor.decode(output.sequences[0][input_len:], skip_special_tokens=True))

Streaming

Like other models that can generate text, you can set a streamer class to stream text. Unlike other models, DiffusionGemma generates intermediate drafts before the final text. You can visualize them with TextDiffusionStreamer

from transformers import TextDiffusionStreamer

# (... copy from the example above, up to the `generate` call)
streamer = TextDiffusionStreamer(tokenizer=processor.tokenizer)
model.generate(**inputs, max_new_tokens=256, streamer=streamer)

Setting a starting denoising output

The model is trained to iteratively refine blocks of 256 tokens. On some applications, it may be beneficial to provide a starting point for the decoder, rather than starting from random tokens. You can use the decoder_input_ids, available on all model interfaces, to set the starting canvas.

initial_estimate = ... # a tensor with shape (bsz, 256)
model.generate(**inputs, max_new_tokens=256, decoder_input_ids=initial_estimate)

DiffusionGemmaTextConfig

autodoc DiffusionGemmaTextConfig

DiffusionGemmaConfig

autodoc DiffusionGemmaConfig

DiffusionGemmaGenerationOutput

autodoc DiffusionGemmaGenerationOutput

DiffusionGemmaGenerationMixin

autodoc DiffusionGemmaGenerationMixin - generate

DiffusionGemmaGenerationConfig

autodoc DiffusionGemmaGenerationConfig

EntropyBoundSamplerConfig

autodoc EntropyBoundSamplerConfig

EntropyBoundSampler

autodoc EntropyBoundSampler

StableAndConfidentStoppingCriteria

autodoc StableAndConfidentStoppingCriteria

LinearTemperatureScheduleLogitsProcessor

autodoc LinearTemperatureScheduleLogitsProcessor

DiffusionGemmaPreTrainedModel

autodoc DiffusionGemmaPreTrainedModel - forward

DiffusionGemmaModel

autodoc DiffusionGemmaModel - forward

DiffusionGemmaEncoderModel

autodoc DiffusionGemmaEncoderModel - forward

DiffusionGemmaEncoderTextModel

autodoc DiffusionGemmaEncoderTextModel - forward

DiffusionGemmaDecoderModel

autodoc DiffusionGemmaDecoderModel - forward

DiffusionGemmaForBlockDiffusion

autodoc DiffusionGemmaForBlockDiffusion - forward