# DiffusionGemma

## 概述

DiffusionGemma 旨在降低标准因果语言模型的顺序瓶颈。它采用专为推理速度优化的编码器-解码器架构。

编码器以预填充（prefill）模式运行，处理初始提示并生成 KV 缓存。随后，解码器利用双向注意力机制处理一个输入块（即“画布”）的 token，并通过交叉注意力访问缓存的上下文。

在推理阶段，DiffusionGemma 采用了多画布采样（multi-canvas sampling）。模型不再逐个生成 token，而是使用扩散采样器（diffusion sampler）对一整块 token 进行迭代去噪。当一个画布完全去噪后，它会经过编码器处理并被追加到 KV 缓存中，随后模型生成下一个画布。这种块自回归（block-autoregressive）方法有助于以更高的速度进行文本生成。

您可以在[此处](https://huggingface.co/google/diffusiongemma-26B-A4B-it)找到模型卡片和检查点。您可以在[此处](https://newsletter.maartengrootendorst.com/p/a-visual-guide-to-diffusiongemma)找到该模型的可视化指南。

## 使用示例

尽管这是一个文本扩散模型，并且拥有自定义的生成循环，但其大部分接口与其他能够使用 [DiffusionGemmaGenerationMixin.generate()](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.DiffusionGemmaGenerationMixin.generate) 生成文本的模型是共享的。如果您在应用中使用的是另一个 `transformers` 模型，应该可以直接将其替换为该模型。

> [!NOTE]
> DiffusionGemma 在 Transformers 和 Diffusers 中均可使用，但 Diffusers 是其主要的开发平台。Diffusers 提供了完整的调度器选项、流水线工具以及新功能（例如额外的调度器、停止条件和采样策略），这些功能仅会在 Diffusers 中添加。请参阅 [DiffusionGemma](https://huggingface.co/docs/diffusers/api/pipelines/diffusion_gemma) 以获取使用示例，并在 Diffusers 上提交 [issue](https://github.com/huggingface/diffusers/issues) 以尝试不同的调度器或请求新功能。Transformers 中的实现仅接收错误修复，不会添加新功能。

### 常见注意事项

- DiffusionGemma 不接受 `use_cache`。它始终使用 KV 缓存；
- 像 `top_k` 这样的常用标志在发布当天将不可用，但如果它们与文本扩散兼容，后续会逐步添加。

### 基础示例

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

### 流式

与其他能够生成文本的模型一样，你可以设置一个 streamer 类来流式输出文本。与其他模型不同的是，DiffusionGemma 会在生成最终文本之前先生成中间草稿。你可以使用 `TextDiffusionStreamer` 来可视化这些草稿。

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

### 设置起始去噪输出

模型经过训练，可迭代地优化 256 个 token 的块。在某些应用场景中，为解码器提供一个起始点，而非从随机 token 开始，可能更有益。您可以使用所有模型接口中均可用的 `decoder_input_ids` 来设置起始画布。

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

## DiffusionGemmaTextConfig[[transformers.DiffusionGemmaTextConfig]]

#### transformers.DiffusionGemmaTextConfig[[transformers.DiffusionGemmaTextConfig]]

```python
transformers.DiffusionGemmaTextConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, vocab_size: int = 262144, hidden_size: int = 2304, intermediate_size: int = 9216, num_hidden_layers: int = 30, num_attention_heads: int = 8, num_key_value_heads: int = 4, head_dim: int = 256, hidden_activation: str = 'gelu_pytorch_tanh', max_position_embeddings: int = 131072, initializer_range: float = 0.02, rms_norm_eps: float = 1e-06, pad_token_id: int | None = 0, eos_token_id: int | list[int] | None = 1, bos_token_id: int | None = 2, tie_word_embeddings: bool = True, rope_parameters: dict | None = None, attention_bias: bool = False, attention_dropout: int | float | None = 0.0, sliding_window: int = 512, layer_types: list[str] | None = None, use_bidirectional_attention: typing.Optional[typing.Literal['all', 'vision']] = None, num_experts: int | None = None, top_k_experts: int | None = None, moe_intermediate_size: int | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/configuration_diffusion_gemma.py#L35)

**参数：**

vocab_size (`int`，*可选*，默认值为 `262144`)：模型的词汇表大小。定义了 `input_ids` 可以表示的不同 token 的数量。

hidden_size (`int`，*可选*，默认为 `2304`)：隐藏表示的维度。

intermediate_size (`int`，*可选*，默认为 `9216`)：MLP 表示的维度。

num_hidden_layers (`int`，*可选*，默认为 `30`)：Transformer 解码器中的隐藏层数。

num_attention_heads (`int`，*可选*，默认为 `8`)：Transformer 解码器中每个注意力层的注意力头数量。

num_key_value_heads (`int`, *可选*，默认为 `4`) : 这是用于实现 Grouped Query Attention 的 key_value 头数量。如果 `num_key_value_heads=num_attention_heads`，模型将使用 Multi Head Attention (MHA)；如果 `num_key_value_heads=1`，模型将使用 Multi Query Attention (MQA)；否则将使用 GQA。在将多头检查点转换为 GQA 检查点时，每个组的 key 和 value 头应通过对该组内所有原始头进行平均池化来构建。更多详情请参阅 [这篇论文](https://huggingface.co/papers/2305.13245)。如果未指定，则默认为 `num_attention_heads`。

head_dim (`int`, *可选*, 默认为 `256`) : 注意力头维度。如果为 None，则默认为 hidden_size // num_attention_heads

hidden_activation (`str`，*可选*，默认为 `gelu_pytorch_tanh`)：解码器中的非线性激活函数（函数或字符串）。例如，`"gelu"`、`"relu"`、`"silu"` 等。

max_position_embeddings (`int`，*可选*，默认值为 `131072`)：该模型可能使用的最大序列长度。

initializer_range (`float`，*可选*，默认值为 `0.02`)：用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。

rms_norm_eps (`float`，*可选*，默认为 `1e-06`)：rms 归一化层使用的 epsilon。

pad_token_id (`int`，*可选*，默认为 `0`)：词表中用于填充的 Token ID。

eos_token_id (`Union[int, list[int]]`，*可选*，默认为 `1`)：词汇表中用于表示流结束（end-of-stream）的 Token ID。

bos_token_id (`int`，*可选*，默认为 `2`)：词汇表中用于表示流起始的 Token id。

tie_word_embeddings (`bool`，*可选*，默认为 `True`)：是否根据模型的 `tied_weights_keys` 映射来绑定权重嵌入。

rope_parameters (`dict`, *可选*) : 包含 RoPE 嵌入配置参数的字典。该字典应包含 `rope_theta` 的值，并且如果您希望使用更长的 `max_position_embeddings` 来使用 RoPE，则可选地包含用于缩放的参数。

attention_bias (`bool`，*可选*，默认为 `False`)：在自注意力机制中，是否在查询、键、值和输出投影层中使用偏置。

attention_dropout (`Union[int, float]`，*可选*，默认值为 `0.0`)：注意力概率的 dropout 比率。

sliding_window (`int`, *可选*，默认为 `512`)：滑动窗口注意力机制的窗口大小。如果为 `None`，则不应用滑动窗口。

layer_types (`list[str]`，*可选*)：一个列表，用于显式地将每个层索引与其层类型进行映射。如果未提供，将根据配置值自动生成。

use_bidirectional_attention (`str`, *可选*) : 控制双向注意力行为。当设置为 `"vision"` 时，视觉标记使用双向注意力，而文本标记使用因果注意力。当设置为 `"all"` 时，所有标记均使用双向注意力。

num_experts (`int`, *可选*) : MoE 层中路由专家的数量。

top_k_experts (`int`, *可选*) : MoE 层中每个 token 激活的专家数量。

moe_intermediate_size (`int`, *可选*) : MoE 层中每个专家的前馈网络的中间（隐藏）维度。

这是用于存储 DiffusionGemmaModel 配置的类。它根据指定的参数实例化 Diffusion Gemma 模型，并定义模型架构。使用默认值实例化配置将得到与 [google/diffusiongemma-26B-A4B-it](https://huggingface.co/google/diffusiongemma-26B-A4B-it) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

## DiffusionGemmaConfig[[transformers.DiffusionGemmaConfig]]

#### transformers.DiffusionGemmaConfig[[transformers.DiffusionGemmaConfig]]

```python
transformers.DiffusionGemmaConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, text_config: transformers.models.diffusion_gemma.configuration_diffusion_gemma.DiffusionGemmaTextConfig | dict[str, typing.Any] | None = None, vision_config: transformers.configuration_utils.PreTrainedConfig | dict[str, typing.Any] | None = None, boi_token_id: int | None = 255999, eoi_token_id: int | None = 258882, image_token_id: int | None = 258880, initializer_range: float | None = 0.02, tie_word_embeddings: bool = True, canvas_length: int | None = 256)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/configuration_diffusion_gemma.py#L162)

**参数：**

text_config (`Union[~models.diffusion_gemma.configuration_diffusion_gemma.DiffusionGemmaTextConfig, dict[str, Any]]`, *可选*) : 文本骨干网络的配置对象或字典。

vision_config (`Union[~configuration_utils.PreTrainedConfig, dict[str, Any]]`, *可选*) : 视觉骨干网络的配置对象或字典。

boi_token_id (`int`, *可选*，默认为 255999)：用于包裹图像提示的图像起始标记索引。

eoi_token_id (`int`, *可选*，默认为 258882)：用于包裹图像提示的图像结束标记索引。

image_token_id (`int`, *可选*, 默认为 `258880`) : 用作输入图像占位符的图像标记索引。

initializer_range (`float`，*可选*，默认值为 `0.02`)：用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。

tie_word_embeddings (`bool`，*可选*，默认为 `True`)：是否根据模型的 `tied_weights_keys` 映射来绑定权重嵌入。

canvas_length (`int`，*可选*，默认为 256)：画布的大小，换言之，即块扩散中的块长度。用于初始化一个空画布。

这是用于存储 DiffusionGemmaModel 配置的类。它根据指定的参数实例化 Diffusion Gemma 模型，并定义模型架构。使用默认值实例化配置将得到与 [google/diffusiongemma-26B-A4B-it](https://huggingface.co/google/diffusiongemma-26B-A4B-it) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

示例：

```python
>>> from transformers import (
>>>     DiffusionGemmaConfig,
>>>     DiffusionGemmaModel,
>>>     DiffusionGemmaTextConfig,
>>>     Gemma4VisionConfig,
>>> )

>>> # Initializing a DiffusionGemma Text config.
>>> text_config = DiffusionGemmaTextConfig()

>>> # Initializing a Gemma 4 vision config (DiffusionGemma uses Gemma 4's vision block).
>>> vision_config = Gemma4VisionConfig()

>>> # Initializing a DiffusionGemma text config
>>> configuration = DiffusionGemmaConfig(text_config, vision_config)

>>> # Initializing a model from the configuration
>>> model = DiffusionGemmaModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## DiffusionGemmaGenerationOutput[[transformers.DiffusionGemmaGenerationOutput]]

#### transformers.DiffusionGemmaGenerationOutput[[transformers.DiffusionGemmaGenerationOutput]]

```python
transformers.DiffusionGemmaGenerationOutput(sequences: LongTensor, tokens_per_forward: int | None = None, past_key_values: transformers.cache_utils.Cache | None = None, logits: None = None, scores: None = None, hidden_states: None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L247)

**参数：**

sequences (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`)：生成的序列，如果 `generate` 方法提供了 `input_ids`，则包含提示词。

tokens_per_forward (`torch.LongTensor`，形状为 (`batch_size`) ) : 在此 `generate` 调用中，批次内每个成员每次前向传播的 token 数量。这通常用作文本扩散模型的次要评估指标。

past_key_values (`Cache`)：用于生成的缓存。在多轮会话中，可以将其传递给后续的 `generate` 调用以加速生成。

logits (`None`) : 未使用。为保持向后兼容而保留在接口中。

scores (`None`) : 未使用。为保持向后兼容而保留在接口中。

hidden_states (`None`) : 未使用。为保持向后兼容而保留在接口中。

DiffusionGemma 生成的输出类。

## DiffusionGemmaGenerationMixin[[transformers.DiffusionGemmaGenerationMixin]]

#### transformers.DiffusionGemmaGenerationMixin[[transformers.DiffusionGemmaGenerationMixin]]

```python
transformers.DiffusionGemmaGenerationMixin()
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L543)

DiffusionGemma 生成的 Mixin 类。包含所有模型级别的方法。

#### generate[[transformers.DiffusionGemmaGenerationMixin.generate]]

```python
generate(input_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, streamer: transformers.generation.streamers.BaseStreamer | None = None, generation_config: transformers.models.diffusion_gemma.generation_diffusion_gemma.DiffusionGemmaGenerationConfig | None = None, logits_processor: transformers.generation.logits_process.LogitsProcessorList | None = None, stopping_criteria: transformers.generation.stopping_criteria.StoppingCriteriaList | None = None, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L548)

**参数：**

input_ids (*torch.LongTensor*，形状为 *(batch_size, sequence_length)*，*可选*)：用作生成提示的序列。

past_key_values ([Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache)，*可选*)：包含解码器过去键值对和过去注意力掩码的 Cache 对象。如果已设置，`input_ids` 和/或 `pixel_values` 必须仅对应未缓存的数据。

streamer (`BaseStreamer`，*可选*)：用于流式传输生成序列的 Streamer 对象。生成的 token 会通过 `streamer.put(token_ids)` 传递，由 streamer 负责后续处理。如果 streamer 对象具有 `put_draft` 方法，则去噪步骤中的 token 将被发送到该方法。

**高级用户的额外参数：**

generation_config ([DiffusionGemmaGenerationConfig](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.DiffusionGemmaGenerationConfig), *可选*) : 用作生成调用基础参数化的生成配置，将覆盖模型的默认设置。如果模型检查点包含 `generation_config.json` 文件，则模型默认设置将从该文件加载。否则，它将是一个空的 `DiffusionGemmaGenerationConfig` 实例。作为额外的快捷方式，`**kwargs` 中与 `generation_config` 属性匹配的参数将覆盖这些属性。

logits_processor ([LogitsProcessorList](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.LogitsProcessorList)，*可选*)：自定义的 logits 处理器，用于补充由参数和生成配置构建的默认 logits 处理器，并应用于扩散 logits。如果提供，这些处理器将最先被应用。此功能面向高级用户。例如，您可以在此处传入通常与自回归 LLM 一起使用的 logits 处理器。

stopping_criteria ([StoppingCriteriaList](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.StoppingCriteriaList)，*optional*)：自定义停止条件，用于补充由参数和生成配置构建的默认块自回归停止条件。如果提供，这些条件将首先被应用。此功能面向高级用户。例如，您可以在此处传入通常与 AR LLM 一起使用的停止条件。

kwargs (`dict[str, Any]`, *可选*) : 用于临时参数化 `generation_config` 和/或额外的模型特定 kwargs，这些参数将被转发到模型的 `forward` 函数。例如，您可以使用 `decoder_input_ids` 来设置起始画布。

**返回：** `torch.LongTensor` 或 [DiffusionGemmaGenerationOutput](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.DiffusionGemmaGenerationOutput)

- `torch.LongTensor`：以 ID 形式表示的生成文本。
- [DiffusionGemmaGenerationOutput](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.DiffusionGemmaGenerationOutput)：`ModelOutput` 实例，包含生成的文本（`sequences`）以及其他可选输出。

使用扩散模型生成文本。

它包含一个外层循环，用于自回归地生成画布（即 token 块），以及一个内

对每个画布执行扩散的循环。该算法大致按以下方式工作：
```
1. Autoregressive canvas generation loop:
    a. Encode all previous tokens using the encoder, to get the KV cache.
    b. Prepare data for the new denoising loop
    c. For each denoising (diffusion) step:
        i.   Run the decoder, taking the current canvas, the encoder KV cache, and the self-conditioning logits
             (if available) as inputs.
        ii.  Select new canvas tokens from the output logits.
        iii. Apply the sampler acceptance and renoising logic.
        iv.  Update the diffusion stopping criteria.
        v.   Use the output logits as self-conditioning logits for the next step.
    d. Append the new denoised canvas to the sequence of generated tokens.
    e. Check if any autoregressive stopping criteria are met, and break the outer loop if all sequences have
       met them. Replaces generated tokens in finished sequences by pad.
    f. Prepare tensors for the next block
```

示例：

```python
>>> from transformers import DiffusionGemmaForBlockDiffusion, AutoProcessor, TextDiffusionStreamer

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

>>> chat = [{"role": "user", "content": "Why is the sky blue?"},]
>>> processor = AutoProcessor.from_pretrained("google/diffusiongemma-26B-A4B-it")
>>> input_ids = processor.apply_chat_template(chat, tokenize=True, return_tensors="pt")

>>> streamer = TextDiffusionStreamer(tokenizer=processor.tokenizer)
>>> model.generate(input_ids.to(model.device), max_new_tokens=512, streamer=streamer)
```

## DiffusionGemmaGenerationConfig[[transformers.DiffusionGemmaGenerationConfig]]

#### transformers.DiffusionGemmaGenerationConfig[[transformers.DiffusionGemmaGenerationConfig]]

```python
transformers.DiffusionGemmaGenerationConfig(**kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L55)

**控制输出长度的参数：**

max_new_tokens (`int`, *可选*) : 要生成的最大 token 数，忽略提示词中的 token 数量。

max_length (`int`, *可选*) : 输出序列的最大长度。建议使用 `max_new_tokens` 来控制模型生成的 token 数量。

**扩散参数：**

max_denoising_steps (`int`) : 要执行的最大去噪步数。

sampler_config (`EntropyBoundSamplerConfig`)：采样器的配置。请参阅 [EntropyBoundSampler](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.EntropyBoundSampler) 以了解采样器在文本扩散模型中的工作原理。

t_min (`float`) : 调度中的最终温度，即最后一个去噪步骤时的温度。有关更多详细信息，请参阅 [LinearTemperatureScheduleLogitsProcessor](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.LinearTemperatureScheduleLogitsProcessor)。

t_max (`float`) : 调度中的初始温度，即第一个去噪步骤时的温度。有关更多详细信息，请参阅 [LinearTemperatureScheduleLogitsProcessor](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.LinearTemperatureScheduleLogitsProcessor)。

stability_threshold (`int`) : 触发停止条件前，已接受的画布必须保持相同的步数。有关更多详细信息，请参阅 [StableAndConfidentStoppingCriteria](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.StableAndConfidentStoppingCriteria)。

confidence_threshold (`float`) : 用于触发停止条件的、经温度缩放后的 logits 熵均值的阈值。有关更多详细信息，请参阅 [StableAndConfidentStoppingCriteria](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.StableAndConfidentStoppingCriteria)。

**控制缓存的参数：**

cache_implementation (`str`, *可选*) : 将在 `generate` 中实例化的缓存类名称，用于加速解码。可能的取值包括：  - `"dynamic"`: [DynamicCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.DynamicCache) - `"static"`: [StaticCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.StaticCache) - `"offloaded"`: `DynamicCache(offloaded=True)` - `"offloaded_static"`: `StaticCache(offloaded=True)` - `"quantized"`: [QuantizedCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.QuantizedCache)  如果未指定，我们将使用该模型的默认缓存（通常是 [DynamicCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.DynamicCache)）。有关更多信息，请参阅我们的 [缓存文档](https://huggingface.co/docs/transformers/en/kv_cache)。

cache_config (`dict`，*可选*，默认为 `None`)：键值缓存类中使用的参数可通过 `cache_config` 传入。

**可在生成时使用的特殊标记：**

bos_token_id (`int`, *可选*) : *序列起始*标记的 id。

pad_token_id (`int`, *可选*)：*padding* 令牌的 id。

eos_token_id (`Union[int, list[int]]`，*可选*)：*序列结束*标记的 id。可选地，使用列表来设置多个*序列结束*标记。

一个针对 [DiffusionGemmaGenerationMixin.generate()](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.DiffusionGemmaGenerationMixin.generate) 进行了参数化定制的 GenerationConfig 类。

## EntropyBoundSamplerConfig[[transformers.EntropyBoundSamplerConfig]]

#### transformers.EntropyBoundSamplerConfig[[transformers.EntropyBoundSamplerConfig]]

```python
transformers.EntropyBoundSamplerConfig(entropy_bound: float)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L320)

**参数：**

entropy_bound (`float`) : 熵边界。该值越高，接受的 token 数量越多。有关其应用方式的详细信息，请参阅 [EntropyBoundSampler.accept_canvas()](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.EntropyBoundSampler.accept_canvas) 的文档字符串。

熵界采样器的配置类。

## EntropyBoundSampler[[transformers.EntropyBoundSampler]]

#### transformers.EntropyBoundSampler[[transformers.EntropyBoundSampler]]

```python
transformers.EntropyBoundSampler(config: EntropyBoundSamplerConfig, canvas_length: int, vocab_size: int, max_denoising_steps: int)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L343)

**参数：**

config (`EntropyBoundSamplerConfig`)：采样器的配置。

canvas_length (`int`) : 画布的长度。

vocab_size (`int`) : 词汇表的大小。

max_denoising_steps (`int`) : 去噪步骤的最大数量。（此采样器中未使用）

采样器类，使用随机 token 初始化画布，基于 token 级熵接受 token，并对未被接受的 token 重新加噪。

以下是采样器循环工作原理的大致示意图：
```
          +-----------------------+
          | Canvas initialization |
          | x_T ∈ U(V)            |
          +-----------+-----------+
                      |
                      v
           +----------+---------+       +---------------------+
+--------->| Current canvas x_t |------>| Denoiser canvas x_D |
|          +----------+---------+       +----------+----------+
|                      \                          /
|                       \                        /
|                        \   Acceptance logic   /
|                         v                    v
|                       +-------------------------+
| Stop if max           | Accepted canvas x_{t-1} |
| denosing steps        +------------+------------+      +-------------------+
| reached or                          \                  | New canvas ∈ U(V) |
| adaptive stopping                    \                 +---------+---------+
| triggers                              \    Renoising logic      /
|                                        v                       v
|                                       +-------------------------+
+---------------------------------------| Next canvas x_{t-1}     |
                                        +-------------------------+
```

#### accept_canvas[[transformers.EntropyBoundSampler.accept_canvas]]

```python
accept_canvas(current_canvas: LongTensor, denoiser_canvas: LongTensor, logits: Tensor, cur_step: int)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L406)

**参数：**

current_canvas (`torch.LongTensor`) : 当前画布。

denoiser_canvas (`torch.LongTensor`) : 从去噪器预测中采样的画布。

logits (`torch.Tensor`) : 去噪器输出的 logits。

cur_step (`int`) : 当前步骤。

**返回：** `torch.LongTensor`

已接受的画布。

根据熵阈值接受来自去噪器的 token。更具体地说，采样过程通过接受熵最低的 k 个 token 来进行，使得

sum_i^k entropy_i - max(entropy_1, ..., entropy_k) <= entropy_bound,

其中，左侧是这些 token 之间联合互信息的上界，因此采样器会选择 k 个近似独立的 token。

最初提出于 https://arxiv.org/pdf/2505.24857

#### initialize_canvas[[transformers.EntropyBoundSampler.initialize_canvas]]

```python
initialize_canvas(batch_size: int, device: device)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L394)

初始化并返回一个包含 `canvas_length` 个 token 的新画布，其值从词表中随机选取。

#### renoise_canvas[[transformers.EntropyBoundSampler.renoise_canvas]]

```python
renoise_canvas(accepted_canvas: LongTensor, cur_step: int)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L450)

**参数：**

accepted_canvas (`torch.LongTensor`) : 接受的画布。

cur_step (`int`) : 当前步数。（此采样器中未使用）

**返回：** `torch.LongTensor`

重新加噪后的画布。

重新噪声化所有未被接受的 token。

## StableAndConfidentStoppingCriteria[[transformers.StableAndConfidentStoppingCriteria]]

#### transformers.StableAndConfidentStoppingCriteria[[transformers.StableAndConfidentStoppingCriteria]]

```python
transformers.StableAndConfidentStoppingCriteria(stability_threshold: int, confidence_threshold: float)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L484)

**参数：**

stability_threshold (`int`) : 触发停止条件前，已接受的画布必须保持相同的步数。

confidence_threshold (`float`) : 用于触发停止条件的、温度缩放后 logits 的熵均值的阈值。

一种自适应停止策略，当扩散过程变得自信且稳定时停止。更具体地说：
- 当在 `stability_threshold` 个步骤中接受的画布相同时，扩散过程是稳定的。
- 当处理后的 logits 的熵的均值低于 `confidence_threshold` 时，扩散过程会表现出较高的置信度。

## LinearTemperatureScheduleLogitsProcessor[[transformers.LinearTemperatureScheduleLogitsProcessor]]

#### transformers.LinearTemperatureScheduleLogitsProcessor[[transformers.LinearTemperatureScheduleLogitsProcessor]]

```python
transformers.LinearTemperatureScheduleLogitsProcessor(t_min: float, t_max: float, max_denoising_steps: int)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L276)

**参数：**

t_min (`float`) : 调度中的最终温度，即最后一个去噪步骤时的温度。

t_max (`float`) : 调度中的初始温度，即第一个去噪步骤时的温度。

max_denoising_steps (`int`) : 去噪步骤的最大数量。

对 logits 应用线性温度调度的 logits 处理器。这与 `TemperatureLogitsWarper` 类似，不同之处在于温度是当前步数的函数。

在第 n 步（共 N 步）时，温度 t 由公式 t = t_min + ((t_max - t_min) * (n/N)) 给出。

## DiffusionGemmaPreTrainedModel[[transformers.DiffusionGemmaPreTrainedModel]]

#### transformers.DiffusionGemmaPreTrainedModel[[transformers.DiffusionGemmaPreTrainedModel]]

```python
transformers.DiffusionGemmaPreTrainedModel(config: PreTrainedConfig, *inputs, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L817)

**参数：**

config ([PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.DiffusionGemmaPreTrainedModel.forward]]

```python
forward(*args, **kwargs)
```

点分路径（例如 `torch.float32`）的模拟值：属性访问链和调用行为如同透传装饰器，`repr` 为点分路径，将其用作基类时会替换为普通的 `type` 基类（PEP 560 `__mro_entries__`），因此真实的子类保留正常的元类，且 `inspect.signature` 读取的是它们真实的 `__init__`，而非模拟对象的。

## DiffusionGemmaModel[[transformers.DiffusionGemmaModel]]

#### transformers.DiffusionGemmaModel[[transformers.DiffusionGemmaModel]]

```python
transformers.DiffusionGemmaModel(config: DiffusionGemmaConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L1452)

**参数：**

config ([DiffusionGemmaConfig](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.DiffusionGemmaConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

未添加任何特定头部的裸 Diffusion Gemma 模型，直接输出原始隐藏状态。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.DiffusionGemmaModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Union[torch.Tensor, dict, NoneType] = None, past_key_values: transformers.cache_utils.Cache | None = None, position_ids: typing.Optional[torch.LongTensor] = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, self_conditioning_logits: typing.Optional[torch.Tensor] = None, self_conditioning_mask: typing.Optional[torch.BoolTensor] = None, decoder_attention_mask: typing.Union[torch.Tensor, dict, NoneType] = None, decoder_position_ids: typing.Optional[torch.LongTensor] = None, mm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L1494)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于编码为画布上下文的提示词的未缓存 token ID。

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)` 或 `dict`，*可选*) : 输入标记的掩码。

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

position_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids)

decoder_input_ids (`torch.LongTensor`，形状为 `(batch_size, canvas_length)`，*可选*)：用于精化的画布的 Token ID。

self_conditioning_logits (`torch.Tensor`，形状为 `(batch_size, canvas_length, vocab_size)`，*可选*)：来自上一步去噪的自条件 logits，用于计算自条件嵌入。

self_conditioning_mask (`torch.BoolTensor`，形状为 `(batch_size,)`，*可选*) : 针对 `self_conditioning_logits` 的逐样本掩码：设置为 `False` 的样本将获得置零的自条件信号，就好像未为其传入任何 logits 一样。这在训练时非常有用，因为自条件信号会以一定概率逐样本启用。

decoder_attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length+canvas_length)` 或 `dict`，*可选*) : 解码器 KV 缓存的注意力掩码。用于指定填充或未填充的编码器 KV 缓存条目。

decoder_position_ids (`torch.LongTensor`，形状为 `(batch_size, canvas_length)`，*可选*)：画布中各个 token 的位置 ID。

mm_encoder_outputs (`dict[str, ~modeling_outputs.BaseModelOutputWithPooling]`, *可选*) : 一个字典，其中键为支持的模态，值为该模态的编码输出。每个编码输出是一个元组，由 (`pooler_output`, *可选*: `last_hidden_states`, *可选*: `hidden_states`, *可选*: `attentions`) 组成，其中 `pooler_output` 的形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)，表示编码器生成的多模态特征序列，并已融合到文本嵌入中。

**返回：** `DiffusionGemmaModelOutputWithPast` 或 `tuple(torch.Tensor)`

`DiffusionGemmaModelOutputWithPast` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[DiffusionGemmaConfig](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.DiffusionGemmaConfig)）和输入。

[DiffusionGemmaModel](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.DiffusionGemmaModel) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 模型最后一层输出的隐藏状态序列。

  如果使用了 `past_key_values`，则仅输出形状为 `(batch_size, 1, hidden_size)` 的序列的最后一个隐藏状态。
- **past_key_values**（`Cache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）—— 它是一个 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/kv_cache)。

  包含预计算的隐藏状态（自注意力块中的键和值，以及如果 `config.is_encoder_decoder=True` 则还包括交叉注意力块中的键和值），可用于（参见 `past_key_values` 输入）加速顺序解码。
- **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **attentions** (`tuple(torch.Tensor)`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。
- **encoder_last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`，*可选*）-- 编码器最后一层输出的隐藏状态序列。仅在提供 `input_ids` 时设置，例如在训练期间用于计算编码器的自回归损失。

## DiffusionGemmaEncoderModel[[transformers.DiffusionGemmaEncoderModel]]

#### transformers.DiffusionGemmaEncoderModel[[transformers.DiffusionGemmaEncoderModel]]

```python
transformers.DiffusionGemmaEncoderModel(config: DiffusionGemmaConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L995)

**参数：**

config ([DiffusionGemmaConfig](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.DiffusionGemmaConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

DiffusionGemma 编码器模型由视觉骨干网络和语言模型组成，*不包含*语言建模头。它与 Gemma4Model 非常相似，区别在于它不支持音频或视频输入，并且始终假设内部层采用 MoE 代码路径。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### forward[[transformers.DiffusionGemmaEncoderModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, pixel_values: typing.Optional[torch.Tensor] = None, attention_mask: typing.Union[torch.Tensor, dict, NoneType] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, mm_token_type_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, image_position_ids: typing.Optional[torch.LongTensor] = None, mm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L1060)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

pixel_values (`torch.Tensor`，形状为 `(batch_size, num_channels, image_size, image_size)`，*可选*) : 与输入图像对应的张量。可以使用 `image_processor_class` 获取像素值。有关详细信息，请参阅 `image_processor_class.__call__`（[Gemma4Processor](/docs/transformers/v5.23.0/zh/model_doc/gemma4#transformers.Gemma4Processor) 使用 `image_processor_class` 处理图像）。

attention_mask (`Union[torch.Tensor, dict]`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值在 `[0, 1]` 中选取： - 对于**未掩码**的标记，值为 1； - 对于**已掩码**的标记，值为 0。 [什么是注意力掩码？](../glossary#attention-mask)

position_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

mm_token_type_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：与每种模态匹配的输入序列 token 的索引。例如文本 (0)、图像 (1)、视频 (2)。可以使用 [AutoProcessor](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoProcessor) 获取多模态 token 类型 ID。有关详细信息，请参阅 [ProcessorMixin.__call__()](/docs/transformers/v5.23.0/zh/main_classes/processors#transformers.ProcessorMixin.__call__)。

inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。

image_position_ids (`torch.LongTensor`，形状为 `(batch_size, max_patches, 2)`，*可选*)：来自图像处理器（image processor）的 2D patch 位置坐标，其中 `(-1, -1)` 表示填充（padding）。该参数会传递给视觉编码器（vision encoder），用于计算位置嵌入（positional embedding）。

mm_encoder_outputs (`dict[str, ~modeling_outputs.BaseModelOutputWithPooling]`, *可选*) : 一个字典，其中键为支持的模态，值为该模态的编码输出。每个编码输出是一个元组，由 (`pooler_output`, *可选*: `last_hidden_states`, *可选*: `hidden_states`, *可选*: `attentions`) 组成，其中 `pooler_output` 的形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)，表示编码器生成的多模态特征序列，并已融合到文本嵌入中。

**返回：** [BaseModelOutputWithPast](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) 或 `tuple(torch.Tensor)`

一个 [BaseModelOutputWithPast](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) 或 `torch.Tensor` 元组（如果传入了 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[DiffusionGemmaConfig](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.DiffusionGemmaConfig)）和输入。

[DiffusionGemmaEncoderModel](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.DiffusionGemmaEncoderModel) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 模型最后一层输出的隐藏状态序列。

  如果使用了 `past_key_values`，则仅输出形状为 `(batch_size, 1, hidden_size)` 的序列的最后一个隐藏状态。
- **past_key_values**（`Cache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）—— 它是一个 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/kv_cache)。

  包含预计算的隐藏状态（自注意力块中的键和值，以及如果 `config.is_encoder_decoder=True` 则还包括交叉注意力块中的键和值），可用于（参见 `past_key_values` 输入）加速顺序解码。
- **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **attentions** (`tuple(torch.Tensor)`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。

## DiffusionGemmaEncoderTextModel[[transformers.DiffusionGemmaEncoderTextModel]]

#### transformers.DiffusionGemmaEncoderTextModel[[transformers.DiffusionGemmaEncoderTextModel]]

```python
transformers.DiffusionGemmaEncoderTextModel(config: DiffusionGemmaTextConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L881)

#### forward[[transformers.DiffusionGemmaEncoderTextModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Union[torch.Tensor, dict, NoneType] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L909)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

attention_mask (`Union[torch.Tensor, dict]`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值在 `[0, 1]` 中选取： - 对于**未掩码**的标记，值为 1； - 对于**已掩码**的标记，值为 0。 [什么是注意力掩码？](../glossary#attention-mask)

position_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。

**返回：** [BaseModelOutputWithPast](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) 或 `tuple(torch.Tensor)`

一个 [BaseModelOutputWithPast](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) 或 `torch.Tensor` 元组（如果传入了 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[DiffusionGemmaConfig](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.DiffusionGemmaConfig)）和输入。

[DiffusionGemmaEncoderTextModel](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.DiffusionGemmaEncoderTextModel) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 模型最后一层输出的隐藏状态序列。

  如果使用了 `past_key_values`，则仅输出形状为 `(batch_size, 1, hidden_size)` 的序列的最后一个隐藏状态。
- **past_key_values**（`Cache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）—— 它是一个 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/kv_cache)。

  包含预计算的隐藏状态（自注意力块中的键和值，以及如果 `config.is_encoder_decoder=True` 则还包括交叉注意力块中的键和值），可用于（参见 `past_key_values` 输入）加速顺序解码。
- **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **attentions** (`tuple(torch.Tensor)`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。

## DiffusionGemmaDecoderModel[[transformers.DiffusionGemmaDecoderModel]]

#### transformers.DiffusionGemmaDecoderModel[[transformers.DiffusionGemmaDecoderModel]]

```python
transformers.DiffusionGemmaDecoderModel(config: DiffusionGemmaConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L1175)

DiffusionGemma 的解码器模型。

通过双向自注意力机制以及对编码器 KV 缓存的交叉注意力机制处理画布 token。解码器读取但不更新 KV 缓存。除这些差异外，它与 `DiffusionGemmaEncoderTextModel` 类似，并且它们共享所有共有的权重。

#### forward[[transformers.DiffusionGemmaDecoderModel.forward]]

```python
forward(decoder_input_ids: LongTensor, past_key_values: transformers.cache_utils.Cache | None = None, self_conditioning_logits: typing.Optional[torch.Tensor] = None, self_conditioning_mask: typing.Optional[torch.BoolTensor] = None, decoder_attention_mask: typing.Union[torch.Tensor, dict, NoneType] = None, decoder_position_ids: typing.Optional[torch.LongTensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L1217)

**参数：**

decoder_input_ids (`torch.LongTensor`，形状为 `(batch_size, canvas_length)`)：待细化画布的 Token ID。

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

self_conditioning_logits (`torch.Tensor`，形状为 `(batch_size, canvas_length, vocab_size)`，*可选*)：来自上一步去噪的自条件 logits，用于计算自条件嵌入。

self_conditioning_mask (`torch.BoolTensor`，形状为 `(batch_size,)`，*可选*) : 针对 `self_conditioning_logits` 的逐样本掩码：设置为 `False` 的样本将获得置零的自条件信号，就好像未为其传入任何 logits 一样。这在训练时非常有用，因为自条件信号会以一定概率逐样本启用。

decoder_attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length+canvas_length)` 或 `dict`，*可选*) : 解码器 KV 缓存的注意力掩码。用于指定填充或未填充的编码器 KV 缓存条目。

decoder_position_ids (`torch.LongTensor`，形状为 `(batch_size, canvas_length)`，*可选*)：画布中各个 token 的位置 ID。

**返回：** [BaseModelOutput](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.BaseModelOutput) 或 `tuple(torch.Tensor)`

一个 [BaseModelOutput](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.BaseModelOutput) 或 `torch.Tensor` 元组（如果传入了 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[DiffusionGemmaConfig](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.DiffusionGemmaConfig)）和输入。

[DiffusionGemmaDecoderModel](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.DiffusionGemmaDecoderModel) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 模型最后一层输出的隐藏状态序列。
- **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **attentions** (`tuple(torch.Tensor)`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。

## DiffusionGemmaForBlockDiffusion[[transformers.DiffusionGemmaForBlockDiffusion]]

#### transformers.DiffusionGemmaForBlockDiffusion[[transformers.DiffusionGemmaForBlockDiffusion]]

```python
transformers.DiffusionGemmaForBlockDiffusion(config: DiffusionGemmaConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L1579)

用于块扩散的 DiffusionGemma 模型。它调用 `DiffusionGemmaModel` 以获取输入画布的隐藏状态，该状态以提示 KV 缓存为条件。利用其 LM Head 和自条件块，它将那些隐藏状态转换为 logits，以采样下一个画布，以及用于下一个块扩散步骤的自条件嵌入。

#### forward[[transformers.DiffusionGemmaForBlockDiffusion.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Union[torch.Tensor, dict, NoneType] = None, past_key_values: transformers.cache_utils.Cache | None = None, position_ids: typing.Optional[torch.LongTensor] = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, self_conditioning_logits: typing.Optional[torch.Tensor] = None, self_conditioning_mask: typing.Optional[torch.BoolTensor] = None, decoder_attention_mask: typing.Union[torch.Tensor, dict, NoneType] = None, decoder_position_ids: typing.Optional[torch.LongTensor] = None, mm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L1601)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于编码为画布上下文的提示词的未缓存 token ID。

attention_mask (`torch.LongTensor`，形状为 `(batch_size, sequence_length)` 或 `dict`，*可选*) : 输入标记的掩码。

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

position_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids)

decoder_input_ids (`torch.LongTensor`，形状为 `(batch_size, canvas_length)`，*可选*)：用于精化的画布的 Token ID。

self_conditioning_logits (`torch.Tensor`，形状为 `(batch_size, canvas_length, vocab_size)`，*可选*)：来自上一步去噪的自条件 logits，用于计算自条件嵌入。

self_conditioning_mask (`torch.BoolTensor`，形状为 `(batch_size,)`，*可选*) : 针对 `self_conditioning_logits` 的逐样本掩码：设置为 `False` 的样本将获得置零的自条件信号，就好像未为其传入任何 logits 一样。这在训练时非常有用，因为自条件信号会以一定概率逐样本启用。

decoder_attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length+canvas_length)` 或 `dict`，*可选*) : 解码器 KV 缓存的注意力掩码。用于指定填充或未填充的编码器 KV 缓存条目。

decoder_position_ids (`torch.LongTensor`，形状为 `(batch_size, canvas_length)`，*可选*)：画布中各个 token 的位置 ID。

mm_encoder_outputs (`dict[str, ~modeling_outputs.BaseModelOutputWithPooling]`, *可选*) : 一个字典，其中键为支持的模态，值为该模态的编码输出。每个编码输出是一个元组，由 (`pooler_output`, *可选*: `last_hidden_states`, *可选*: `hidden_states`, *可选*: `attentions`) 组成，其中 `pooler_output` 的形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)，表示编码器生成的多模态特征序列，并已融合到文本嵌入中。

**返回：** `DiffusionGemmaBlockDiffusionOutputWithPast` 或 `tuple(torch.Tensor)`

`DiffusionGemmaBlockDiffusionOutputWithPast` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[DiffusionGemmaConfig](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.DiffusionGemmaConfig)）和输入。

[DiffusionGemmaForBlockDiffusion](/docs/transformers/v5.23.0/zh/model_doc/diffusion_gemma#transformers.DiffusionGemmaForBlockDiffusion) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*) -- 语言建模损失。
- **logits**（形状为 `(batch_size, canvas_length, config.text_config.vocab_size)` 的 `torch.Tensor`）-- 语言建模头的预测分数（SoftMax 之前每个词汇表 token 的分数）。
- **past_key_values**（`Cache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）—— 它是一个 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/kv_cache)。

  包含预计算的隐藏状态（自注意力块中的键和值），可用于（参见 `past_key_values` 输入）加速顺序解码。
- **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **attentions** (`tuple(torch.Tensor)`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。
- **encoder_last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`，*可选*）-- 编码器最后一层输出的隐藏状态序列。仅在提供 `input_ids` 时设置，例如在训练期间用于计算编码器的自回归损失。

示例：

```python
>>> from PIL import Image
>>> from transformers import AutoProcessor, DiffusionGemmaForBlockDiffusion

>>> model = DiffusionGemmaForBlockDiffusion.from_pretrained("google/diffusiongemma-26B-A4B-it")
>>> 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": "Where is the cat standing?"},
...         ]
...     },
... ]

>>> inputs = processor.apply_chat_template(
...     messages,
...     tokenize=True,
...     return_dict=True,
...     return_tensors="pt",
...     add_generation_prompt=True
... )
>>> # Generate
>>> generate_ids = model.generate(**inputs)
>>> processor.batch_decode(generate_ids, skip_special_tokens=True)[0]
```

