# DiffusionGemma

## 개요

DiffusionGemma는 표준 인과 언어 모델의 순차적 병목 현상을 줄이기 위해 설계되었습니다. 추론 속도를 위해 특별히 최적화된 인코더-디코더 아키텍처를 사용합니다.

Encoder는 prefill 용도로 작동하여 초기 프롬프트를 처리하고 KV 캐시를 생성합니다. 이후 Decoder는 양방향 attention을 활용하여 토큰의 입력 블록(‘canvas’)을 처리하며, cross-attention을 통해 캐시된 컨텍스트에 접근합니다.

추론 시 DiffusionGemma는 멀티 캔버스 샘플링을 활용합니다. 토큰을 하나씩 생성하는 대신, 모델은 diffusion sampler를 사용하여 토큰 블록 전체를 반복적으로 디노이즈합니다. 캔버스가 완전히 디노이즈되면 인코더를 통해 처리된 후 KV cache에 추가되고, 이후 모델은 다음 캔버스를 생성합니다. 이러한 블록 오토레거시브 방식은 더 높은 속도로 텍스트 생성을 가능하게 합니다.

모델 카드와 체크포인트는 [여기](https://huggingface.co/google/diffusiongemma-26B-A4B-it)에서 찾을 수 있습니다. 모델에 대한 시각적 가이드는 [여기](https://newsletter.maartengrootendorst.com/p/a-visual-guide-to-diffusiongemma)에서 확인할 수 있습니다.

## 사용 예시

텍스트 확산 모델이며 커스텀 생성 루프를 갖추고 있지만, [DiffusionGemmaGenerationMixin.generate()](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.DiffusionGemmaGenerationMixin.generate)를 통해 텍스트를 생성할 수 있는 다른 모델들과 대부분의 인터페이스를 공유합니다. 애플리케이션에서 다른 `transformers` 모델을 사용 중이라면, 이 모델로 직접 교체할 수 있어야 합니다.

> [!NOTE]
> DiffusionGemma는 Transformers와 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))
```

### 스트리밍

텍스트를 생성할 수 있는 다른 모델과 마찬가지로, 스트리머 클래스를 설정하여 텍스트를 스트리밍할 수 있습니다. 다른 모델과 달리, 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개의 토큰으로 구성된 블록을 반복적으로 정제하도록 학습됩니다. 일부 응용 프로그램에서는 무작위 토큰에서 시작하는 대신 디코더의 시작점을 제공하는 것이 유리할 수 있습니다. 모든 모델 인터페이스에서 사용할 수 있는 `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/main/src/transformers/models/diffusion_gemma/configuration_diffusion_gemma.py#L35)

**매개변수:**

vocab_size (`int`, *선택 사항*, 기본값 `262144`) : 모델의 어휘 크기입니다. `input_ids`로 표현할 수 있는 서로 다른 토큰의 수를 정의합니다.

hidden_size (`int`, *선택 사항*, 기본값 `2304`) : 숨겨진 표현의 차원.

intermediate_size (`int`, *선택 사항*, 기본값 `9216`) : MLP 표현의 차원.

num_hidden_layers (`int`, *선택 사항*, 기본값 `30`) : Transformer 디코더의 숨겨진 레이어 수.

num_attention_heads (`int`, *선택 사항*, 기본값 `8`) : Transformer decoder의 각 attention layer에 사용할 attention head의 수입니다.

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 헤드는 해당 그룹 내 모든 원래 헤드를 meanpooling하여 구성해야 합니다. 자세한 내용은 [이 논문](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 normalization 레이어에서 사용되는 epsilon 값입니다.

pad_token_id (`int`, *선택 사항*, 기본값 `0`) : 어휘에서 패딩에 사용되는 토큰 ID입니다.

eos_token_id (`Union[int, list[int]]`, *선택 사항*, 기본값 `1`) : 어휘에서 스트림 종료에 사용되는 토큰 ID입니다.

bos_token_id (`int`, *선택 사항*, 기본값 `2`) : 어휘에서 스트림 시작에 사용되는 토큰 ID입니다.

tie_word_embeddings (`bool`, *선택 사항*, 기본값 `True`) : 모델의 `tied_weights_keys` 매핑에 따라 가중치 임베딩을 묶을지 여부.

rope_parameters (`dict`, *선택*) : RoPE 임베딩의 구성 매개변수를 포함하는 사전입니다. 사전에는 `rope_theta` 값이 포함되어야 하며, 더 긴 `max_position_embeddings`로 RoPE를 사용하려는 경우 스케일링에 사용되는 매개변수를 선택적으로 포함할 수 있습니다.

attention_bias (`bool`, *선택 사항*, 기본값 `False`) : self-attention에서 query, key, value 및 output projection layer에 bias를 사용할지 여부.

attention_dropout (`Union[int, float]`, *선택 사항*, 기본값 `0.0`) : attention 확률에 적용할 dropout 비율입니다.

sliding_window (`int`, *선택 사항*, 기본값 `512`) : Sliding window attention의 윈도우 크기입니다. `None`인 경우 sliding window가 적용되지 않습니다.

layer_types (`list[str]`, *선택 사항*) : 각 레이어 인덱스를 해당 레이어 유형에 명시적으로 매핑하는 리스트입니다. 제공되지 않으면 config 값에 기반하여 자동으로 생성됩니다.

use_bidirectional_attention (`str`, *선택 사항*) : 양방향 어텐션 동작을 제어합니다. `"vision"`으로 설정하면 비전 토큰은 양방향으로 어텐션을 수행하고 텍스트 토큰은 인과적 어텐션을 사용합니다. `"all"`로 설정하면 모든 토큰이 양방향 어텐션을 사용합니다.

num_experts (`int`, *선택 사항*) : MoE 레이어의 라우팅된 전문가(expert) 수.

top_k_experts (`int`, *선택 사항*) : MoE 레이어에서 토큰당 활성화되는 전문가의 수.

moe_intermediate_size (`int`, *선택 사항*) : MoE 레이어에서 각 전문가의 피드포워드 네트워크의 중간(숨겨진) 크기입니다.

이것은 DiffusionGemmaModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Diffusion Gemma 모델을 인스턴스화하고 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 [google/diffusiongemma-26B-A4B-it](https://huggingface.co/google/diffusiongemma-26B-A4B-it)의 구성과 유사한 구성이 생성됩니다.

Configuration 객체는 [PreTrainedConfig](/docs/transformers/main/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/main/ko/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/main/src/transformers/models/diffusion_gemma/configuration_diffusion_gemma.py#L163)

**매개변수:**

text_config (`Union[~models.diffusion_gemma.configuration_diffusion_gemma.DiffusionGemmaTextConfig, dict[str, Any]]`, *선택*) : 텍스트 백본의 config 객체 또는 사전입니다.

vision_config (`Union[~configuration_utils.PreTrainedConfig, dict[str, Any]]`, *선택*) : 비전 백본의 config 객체 또는 사전입니다.

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) : 캔버스 크기, 즉 블록 확산(block diffusion)에서의 블록 길이입니다. 빈 캔버스를 초기화하는 데 사용됩니다.

이것은 DiffusionGemmaModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Diffusion Gemma 모델을 인스턴스화하고 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 [google/diffusiongemma-26B-A4B-it](https://huggingface.co/google/diffusiongemma-26B-A4B-it)의 구성과 유사한 구성이 생성됩니다.

Configuration 객체는 [PreTrainedConfig](/docs/transformers/main/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/main/ko/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/main/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L247)

**매개변수:**

sequences (`torch.LongTensor`, shape `(batch_size, sequence_length)`) : `generate` 메서드에 `input_ids`가 제공된 경우 프롬프트를 포함하여 생성된 시퀀스입니다.

tokens_per_forward (`torch.LongTensor`, shape: (`batch_size`)) : 이 `generate` 호출에서 배치의 각 멤버에 대해 forward당 토큰 수입니다. 이는 텍스트 확산 모델에서 보조 평가 지표로 자주 사용됩니다.

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/main/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/main/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L548)

**매개변수:**

input_ids (*torch.LongTensor*, shape *(batch_size, sequence_length)*, *선택 사항*) : 생성을 위한 프롬프트로 사용되는 시퀀스.

past_key_values ([Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache), *선택 사항*) : 디코더의 과거 키 값과 과거 어텐션 마스크를 포함하는 Cache 객체. 이 값이 설정되어 있으면 `input_ids`와/또는 `pixel_values`는 캐시되지 않은 데이터에만 대응해야 합니다.

streamer (`BaseStreamer`, *선택 사항*) : 생성된 시퀀스를 스트리밍하는 데 사용되는 Streamer 객체입니다. 생성된 토큰은 `streamer.put(token_ids)`를 통해 전달되며, 스트리머는 추가적인 처리를 담당합니다. 스트리머 객체에 `put_draft` 메서드가 있는 경우, 디노이징 단계의 토큰은 해당 메서드로 전송됩니다.

**고급 사용자를 위한 추가 인자:**

generation_config ([DiffusionGemmaGenerationConfig](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.DiffusionGemmaGenerationConfig), *선택*) : 생성 호출의 기본 파라미터화로 사용할 생성 구성입니다. 모델의 기본값을 덮어씁니다. 모델 체크포인트에 `generation_config.json` 파일이 있으면 모델 기본값은 해당 파일에서 로드됩니다. 그렇지 않으면 빈 `DiffusionGemmaGenerationConfig` 인스턴스가 됩니다. 추가적인 단축 방식으로, `generation_config`의 속성과 일치하는 `**kwargs`는 해당 속성을 덮어씁니다.

logits_processor ([LogitsProcessorList](/docs/transformers/main/ko/internal/generation_utils#transformers.LogitsProcessorList), *optional*) : 인자와 생성 구성에서 기본으로 생성되는 logits processor를 보완하는 사용자 정의 logits processor입니다. diffusion logits에 적용되며, 제공된 경우 이 processor들이 가장 먼저 적용됩니다. 이 기능은 고급 사용자를 위한 것입니다. 예를 들어, AR LLM과 함께 일반적으로 사용되는 logits processor를 여기에 전달할 수 있습니다.

stopping_criteria ([StoppingCriteriaList](/docs/transformers/main/ko/internal/generation_utils#transformers.StoppingCriteriaList), *optional*) : 인자와 generation config로 구성된 기본 블록 오토레그레시브 stopping criteria를 보완하는 사용자 정의 stopping criteria입니다. 제공된 경우, 이 기준이 먼저 적용됩니다. 이 기능은 고급 사용자를 위한 것입니다. 예를 들어, AR LLM에서 일반적으로 사용되는 stopping criteria를 여기에 전달할 수 있습니다.

kwargs (`dict[str, Any]`, *선택*) : `generation_config`의 즉석 파라미터화 및/또는 모델의 `forward` 함수로 전달될 추가적인 모델 전용 kwargs입니다. 예를 들어, `decoder_input_ids`를 사용하여 시작 캔버스를 설정할 수 있습니다.

**반환값:** `torch.LongTensor` 또는 [DiffusionGemmaGenerationOutput](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.DiffusionGemmaGenerationOutput)

- `torch.LongTensor`: id 형식의 생성된 텍스트.
- [DiffusionGemmaGenerationOutput](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.DiffusionGemmaGenerationOutput): 생성된 텍스트(`sequences`)와 기타 선택적 출력을 포함하는 `ModelOutput` 인스턴스.

확산 모델을 사용하여 텍스트를 생성합니다.

외부 루프는 캔버스(토큰 블록)의 자기회귀 생성을 수행하고, 내부 루프는

각 캔버스에 대해 확산을 수행하는 루프입니다. 알고리즘은 대략 다음과 같이 작동합니다:
```
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/main/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L55)

**출력의 길이를 제어하는 매개변수:**

max_new_tokens (`int`, *선택 사항*) : 프롬프트의 토큰 수를 무시하고 생성할 최대 토큰 수입니다.

max_length (`int`, *선택 사항*) : 출력 시퀀스의 최대 길이. 모델이 생성할 토큰 수를 제어하는 데는 `max_new_tokens`를 사용하는 것이 권장됩니다.

**확산 매개변수:**

max_denoising_steps (`int`) : 수행할 최대 디노이징 단계 수.

sampler_config (`EntropyBoundSamplerConfig`) : 샘플러의 설정입니다. 텍스트 확산 모델에서 샘플러가 어떻게 작동하는지 알아보려면 [EntropyBoundSampler](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.EntropyBoundSampler)를 참고하세요.

t_min (`float`) : 스케줄의 최종 온도, 즉 마지막 디노이징 단계에서의 온도입니다. 자세한 내용은 [LinearTemperatureScheduleLogitsProcessor](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.LinearTemperatureScheduleLogitsProcessor)를 참조하세요.

t_max (`float`) : 스케줄의 초기 온도, 즉 첫 번째 디노이징 단계에서의 값입니다. 자세한 내용은 [LinearTemperatureScheduleLogitsProcessor](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.LinearTemperatureScheduleLogitsProcessor)를 참조하세요.

stability_threshold (`int`) : 중단 기준을 트리거하기 위해 승인된 캔버스가 동일해야 하는 스텝 수. 자세한 내용은 [StableAndConfidentStoppingCriteria](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.StableAndConfidentStoppingCriteria)를 참조하세요.

confidence_threshold (`float`) : 온도 스케일링된 logits의 엔트로피 평균이 정지 기준을 트리거하도록 하는 임계값. 자세한 내용은 [StableAndConfidentStoppingCriteria](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.StableAndConfidentStoppingCriteria)를 참조하세요.

**캐시를 제어하는 매개변수:**

cache_implementation (`str`, *선택 사항*) : `generate`에서 더 빠른 디코딩을 위해 인스턴스화될 캐시 클래스의 이름입니다. 가능한 값은 다음과 같습니다:  - `"dynamic"`: [DynamicCache](/docs/transformers/main/ko/internal/generation_utils#transformers.DynamicCache) - `"static"`: [StaticCache](/docs/transformers/main/ko/internal/generation_utils#transformers.StaticCache) - `"offloaded"`: `DynamicCache(offloaded=True)` - `"offloaded_static"`: `StaticCache(offloaded=True)` - `"quantized"`: [QuantizedCache](/docs/transformers/main/ko/internal/generation_utils#transformers.QuantizedCache)  지정되지 않으면 모델의 기본 캐시(대부분 [DynamicCache](/docs/transformers/main/ko/internal/generation_utils#transformers.DynamicCache)입니다)를 사용합니다. 자세한 내용은 [캐시 문서](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요.

cache_config (`dict`, *선택 사항*, 기본값 `None`) : key-value cache 클래스에서 사용되는 인수는 `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/main/ko/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/main/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L320)

**매개변수:**

entropy_bound (`float`) : 엔트로피 상한. 이 값이 높을수록 더 많은 토큰이 수락됩니다. 적용 방식에 대한 자세한 내용은 [EntropyBoundSampler.accept_canvas()](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.EntropyBoundSampler.accept_canvas)의 docstring을 참고하세요.

엔트로피 바운더리 샘플러에 대한 구성 클래스입니다.

## 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/main/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L343)

**매개변수:**

config (`EntropyBoundSamplerConfig`) : 샘플러의 구성입니다.

canvas_length (`int`) : 캔버스의 길이.

vocab_size (`int`) : 어휘의 크기.

max_denoising_steps (`int`) : 노이즈 제거 단계의 최대 수. (이 샘플러에서는 사용되지 않음)

Sampler 클래스는 무작위 토큰으로 캔버스를 초기화하고, 토큰 수준 엔트로피에 기반하여 토큰을 수락하며, 수락되지 않은 토큰을 다시 노이즈 처리합니다.

샘플러 루프가 작동하는 방식의 개요는 다음과 같습니다.
```
          +-----------------------+
          | 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/main/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L406)

**매개변수:**

current_canvas (`torch.LongTensor`) : 현재 캔버스.

denoiser_canvas (`torch.LongTensor`) : denoiser 예측에서 샘플링된 캔버스.

logits (`torch.Tensor`) : denoiser에서 생성된 logits입니다.

cur_step (`int`) : 현재 단계.

**반환값:** `torch.LongTensor`

수락된 캔버스.

엔트로피 한계에 기반하여 denoiser로부터 토큰을 수락합니다. 보다 구체적으로, 샘플링은 다음과 같이 가장 낮은 엔트로피를 가진 k개의 토큰을 수락하는 방식으로 진행됩니다.

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

여기서 좌변은 해당 토큰들 간의 결합 상호 정보의 상한이므로, 샘플러는 서로 대략 독립적인 k개의 토큰을 선택합니다.

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/main/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L394)

`canvas_length` 토큰 크기의 새로운 캔버스를 초기화하고, 어휘에서 무작위로 값을 채워 반환합니다.

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

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

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L450)

**매개변수:**

accepted_canvas (`torch.LongTensor`) : 허용된 캔버스.

cur_step (`int`) : 현재 단계. (이 샘플러에서는 사용되지 않음)

**반환값:** `torch.LongTensor`

재노이즈된 캔버스.

수락되지 않은 모든 토큰을 다시 노이즈 처리합니다.

## StableAndConfidentStoppingCriteria[[transformers.StableAndConfidentStoppingCriteria]]

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

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

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L484)

**매개변수:**

stability_threshold (`int`) : 정지 조건을 트리거하기 위해 승인된 캔버스가 동일해야 하는 스텝 수.

confidence_threshold (`float`) : 온도 스케일링된 logits의 엔트로피 평균이 정지 기준을 트리거하도록 하는 임계값.

확산 프로세스가 확신하고 안정적일 때 중단하는 적응형 중단 전략입니다. 보다 구체적으로:
- `stability_threshold` 단계 동안 승인된 캔버스가 동일할 때 확산 과정은 안정적입니다.
- 처리된 logits의 엔트로피 평균이 `confidence_threshold`보다 낮을 때 diffusion process는 confident 상태입니다.

## 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/main/src/transformers/models/diffusion_gemma/generation_diffusion_gemma.py#L276)

**매개변수:**

t_min (`float`) : 스케줄의 최종 온도, 즉 마지막 디노이징 단계에서의 값.

t_max (`float`) : 스케줄의 초기 온도, 즉 첫 번째 디노이징 단계에서의 값.

max_denoising_steps (`int`) : 노이즈 제거 단계의 최대 수.

logits에 선형 temperature 스케줄을 적용하는 logits processor입니다. `TemperatureLogitsWarper`와 유사하지만, temperature가 현재 step의 함수라는 점이 다릅니다.

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/main/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L817)

**매개변수:**

config ([PreTrainedConfig](/docs/transformers/main/ko/main_classes/configuration#transformers.PreTrainedConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

이 모델은 [PreTrainedModel](/docs/transformers/main/ko/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`)에 대한 mock 값입니다: 속성 접근 체인, 호출은 pass-through 데코레이터처럼 동작하며, `repr`은 해당 점으로 구분된 경로입니다. 또한 이를 베이스 클래스로 사용하면 plain-`type` 베이스로 대체됩니다(PEP 560 `__mro_entries__`). 따라서 실제 서브클래스는 정상적인 메타클래스를 유지하고, `inspect.signature`는 mock의 `__init__`가 아닌 실제 `__init__`를 읽습니다.

## DiffusionGemmaModel[[transformers.DiffusionGemmaModel]]

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

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

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L1452)

**매개변수:**

config ([DiffusionGemmaConfig](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.DiffusionGemmaConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

특정 헤드가 위에 없는 상태에서 원시 hidden-states를 출력하는 기본 Diffusion Gemma Model입니다.

이 모델은 [PreTrainedModel](/docs/transformers/main/ko/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/main/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L1494)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 캔버스 컨텍스트로 인코딩될 프롬프트의 캐시되지 않은 토큰 ID입니다.

attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length)` 또는 `dict`, *선택 사항*) : 입력 토큰에 대한 마스크.

past_key_values (`~cache_utils.Cache`, *선택*) : 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key 및 value)입니다. 일반적으로 `use_cache=True` 또는 `config.use_cache=True`일 때 모델이 디코딩의 이전 단계에서 반환한 `past_key_values`로 구성됩니다. 입력으로 [Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `past_key_values`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/main/ko/internal/generation_utils#transformers.DynamicCache)가 초기화됩니다. 모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다. `past_key_values`를 사용하는 경우, 이 모델에 과거 key value 상태가 제공되지 않은 `input_ids`(처리되지 않은 항목)만 `(batch_size, unprocessed_length)` 형식으로 입력해야 하며, `(batch_size, sequence_length)` 형식의 모든 `input_ids`를 입력하지 않습니다.

position_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 각 입력 시퀀스의 토큰 위치 인덱스입니다. `[0, config.n_positions - 1]` 범위에서 선택됩니다. [위치 ID란 무엇인가요?](../glossary#position-ids)

decoder_input_ids (`torch.LongTensor`, shape `(batch_size, canvas_length)`, *선택 사항*) : 정제할 캔버스의 토큰 ID입니다.

self_conditioning_logits (`torch.Tensor`, shape `(batch_size, canvas_length, vocab_size)`, *선택 사항*) : 이전 denoising 단계의 self-conditioning logits입니다. self-conditioning embeddings을 계산하는 데 사용됩니다.

self_conditioning_mask (`torch.BoolTensor`, shape `(batch_size,)`, *선택 사항*) : `self_conditioning_logits`에 대한 예시별 마스크입니다. `False`로 설정된 예시는 해당 예시에 대해 logits가 전달되지 않은 것과 동일한 방식으로 zeroed self-conditioning 신호를 받습니다. self-conditioning이 확률에 따라 예시별로 활성화되는 학습 시 유용합니다.

decoder_attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length+canvas_length)` 또는 `dict`, *선택 사항*) : 디코더 KV 캐시의 어텐션 마스크입니다. 패딩되거나 채워지지 않은 인코더 KV 캐시 항목을 지정하는 데 사용됩니다.

decoder_position_ids (`torch.LongTensor`, shape `(batch_size, canvas_length)`, *선택 사항*) : 캔버스 내 토큰의 위치 ID입니다.

mm_encoder_outputs (`dict[str, ~modeling_outputs.BaseModelOutputWithPooling]`, *선택 사항*) : 키가 지원되는 모달리티이고 값이 해당 모달리티의 인코딩된 출력인 Dict입니다. 각 인코딩된 출력은 (`pooler_output`, *선택 사항*: `last_hidden_states`, *선택 사항*: `hidden_states`, *선택 사항*: `attentions`)의 튜플로 구성되며, `pooler_output`의 shape은 `(batch_size, sequence_length, hidden_size)`, *선택 사항*)입니다. 이는 인코더의 멀티모달 특징을 텍스트 임베딩으로 병합한 시퀀스입니다.

**반환값:** `DiffusionGemmaModelOutputWithPast` 또는 `tuple(torch.Tensor)`

`DiffusionGemmaModelOutputWithPast` 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되었거나 `config.return_dict=False`인 경우)로, 구성([DiffusionGemmaConfig](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.DiffusionGemmaConfig))과 입력에 따라 다양한 요소를 포함합니다.

[DiffusionGemmaModel](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.DiffusionGemmaModel)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`) -- 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.

  `past_key_values`가 사용되면, `(batch_size, 1, hidden_size)` 형태의 시퀀스의 마지막 hidden-state만 출력됩니다.
- **past_key_values** (`Cache`, *선택 사항*, `use_cache=True`가 전달되었거나 `config.use_cache=True`인 경우 반환됨) -- [Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache) 인스턴스입니다. 자세한 내용은 [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요.

  순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록의 key와 value, 그리고 `config.is_encoder_decoder=True`인 경우 크로스 어텐션 블록의 key와 value)를 포함합니다(입력 `past_key_values` 참조).
- **hidden_states** (`tuple(torch.Tensor)`, *선택 사항*, `output_hidden_states=True`가 전달되었거나 `config.output_hidden_states=True`인 경우 반환됨) -- `torch.Tensor`의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 형태는 `(batch_size, sequence_length, hidden_size)`입니다.

  각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.
- **attentions** (`tuple(torch.Tensor)`, *선택 사항*, `output_attentions=True`가 전달되었거나 `config.output_attentions=True`인 경우 반환됨) -- 각 레이어마다 하나씩 포함된 `torch.Tensor`의 튜플로, 모양은 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치입니다.
- **encoder_last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택*) -- 인코더의 마지막 레이어 출력에서 생성된 hidden state 시퀀스입니다. `input_ids`가 제공된 경우에만 설정되며, 예를 들어 학습 중 인코더에 대한 autoregressive loss를 계산하는 데 사용됩니다.

## DiffusionGemmaEncoderModel[[transformers.DiffusionGemmaEncoderModel]]

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

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

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L995)

**매개변수:**

config ([DiffusionGemmaConfig](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.DiffusionGemmaConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

언어 모델링 헤드가 *없는* 비전 백본과 언어 모델로 구성된 DiffusionGemma 인코더 모델입니다. Gemma4Model과 매우 유사하지만, 오디오 또는 비디오 입력을 지원하지 않으며 내부 레이어에서는 항상 MoE 코드 경로를 가정합니다.

이 모델은 [PreTrainedModel](/docs/transformers/main/ko/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/main/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L1060)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 어휘(input sequence tokens)의 인덱스입니다. 기본적으로 패딩은 무시됩니다. [AutoTokenizer](/docs/transformers/main/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [입력 ID란 무엇인가요?](../glossary#input-ids)

pixel_values (`torch.Tensor`, shape `(batch_size, num_channels, image_size, image_size)`, *선택 사항*) : 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 `image_processor_class`을(를) 사용하여 얻을 수 있습니다. 자세한 내용은 `image_processor_class.__call__`을(를) 참조하세요 ([Gemma4Processor](/docs/transformers/main/ko/model_doc/gemma4#transformers.Gemma4Processor)는 `image_processor_class`을(를) 사용하여 이미지를 처리합니다).

attention_mask (`Union[torch.Tensor, dict]` 형상 `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 어텐션 수행을 방지하기 위한 마스크. `[0, 1]`에서 선택된 마스크 값:  - **마스크되지 않은** 토큰은 1, - **마스크된** 토큰은 0.  [어텐션 마스크란?](../glossary#attention-mask)

position_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 각 입력 시퀀스의 토큰 위치 인덱스입니다. `[0, config.n_positions - 1]` 범위에서 선택됩니다. [위치 ID란 무엇인가요?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *선택*) : 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key 및 value)입니다. 일반적으로 `use_cache=True` 또는 `config.use_cache=True`일 때 모델이 디코딩의 이전 단계에서 반환한 `past_key_values`로 구성됩니다. 입력으로 [Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `past_key_values`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/main/ko/internal/generation_utils#transformers.DynamicCache)가 초기화됩니다. 모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다. `past_key_values`를 사용하는 경우, 이 모델에 과거 key value 상태가 제공되지 않은 `input_ids`(처리되지 않은 항목)만 `(batch_size, unprocessed_length)` 형식으로 입력해야 하며, `(batch_size, sequence_length)` 형식의 모든 `input_ids`를 입력하지 않습니다.

mm_token_type_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 각 모달리티에 해당하는 입력 시퀀스 토큰의 인덱스입니다. 예를 들어 텍스트(0), 이미지(1), 비디오(2) 등이 있습니다. 멀티모달 토큰 타입 ID는 [AutoProcessor](/docs/transformers/main/ko/model_doc/auto#transformers.AutoProcessor)를 사용하여 얻을 수 있습니다. 자세한 내용은 [ProcessorMixin.__call__()](/docs/transformers/main/ko/main_classes/processors#transformers.ProcessorMixin.__call__)를 참조하세요.

inputs_embeds (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) : `input_ids`를 전달하는 대신 임베디드 표현을 직접 전달할 수 있습니다. 이는 모델의 내부 임베딩 조회 행렬보다 `input_ids` 인덱스를 관련 벡터로 변환하는 방식에 대해 더 많은 제어가 필요한 경우 유용합니다.

image_position_ids (`torch.LongTensor`, shape `(batch_size, max_patches, 2)`, *선택 사항*) : 이미지 프로세서에서 생성된 2D 패치 위치 좌표이며, `(-1, -1)`은 패딩을 나타냅니다. 위치 임베딩 계산을 위해 비전 인코더로 전달됩니다.

mm_encoder_outputs (`dict[str, ~modeling_outputs.BaseModelOutputWithPooling]`, *선택 사항*) : 키가 지원되는 모달리티이고 값이 해당 모달리티의 인코딩된 출력인 Dict입니다. 각 인코딩된 출력은 (`pooler_output`, *선택 사항*: `last_hidden_states`, *선택 사항*: `hidden_states`, *선택 사항*: `attentions`)의 튜플로 구성되며, `pooler_output`의 shape은 `(batch_size, sequence_length, hidden_size)`, *선택 사항*)입니다. 이는 인코더의 멀티모달 특징을 텍스트 임베딩으로 병합한 시퀀스입니다.

**반환값:** [BaseModelOutputWithPast](/docs/transformers/main/ko/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) 또는 `tuple(torch.Tensor)`

[BaseModelOutputWithPast](/docs/transformers/main/ko/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) 또는 `torch.Tensor`의 튜플(`return_dict=False`이 전달되었거나 `config.return_dict=False`인 경우)로, 구성([DiffusionGemmaConfig](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.DiffusionGemmaConfig)) 및 입력에 따라 다양한 요소를 포함합니다.

[DiffusionGemmaEncoderModel](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.DiffusionGemmaEncoderModel)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`) -- 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.

  `past_key_values`가 사용되면, `(batch_size, 1, hidden_size)` 형태의 시퀀스의 마지막 hidden-state만 출력됩니다.
- **past_key_values** (`Cache`, *선택 사항*, `use_cache=True`가 전달되었거나 `config.use_cache=True`인 경우 반환됨) -- [Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache) 인스턴스입니다. 자세한 내용은 [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요.

  순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록의 key와 value, 그리고 `config.is_encoder_decoder=True`인 경우 크로스 어텐션 블록의 key와 value)를 포함합니다(입력 `past_key_values` 참조).
- **hidden_states** (`tuple(torch.Tensor)`, *선택 사항*, `output_hidden_states=True`가 전달되었거나 `config.output_hidden_states=True`인 경우 반환됨) -- `torch.Tensor`의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 형태는 `(batch_size, sequence_length, hidden_size)`입니다.

  각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.
- **attentions** (`tuple(torch.Tensor)`, *선택 사항*, `output_attentions=True`가 전달되었거나 `config.output_attentions=True`인 경우 반환됨) -- 각 레이어마다 하나씩 포함된 `torch.Tensor`의 튜플로, 모양은 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치입니다.

## DiffusionGemmaEncoderTextModel[[transformers.DiffusionGemmaEncoderTextModel]]

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

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

[소스](https://github.com/huggingface/transformers/blob/main/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/main/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L909)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 어휘(input sequence tokens)의 인덱스입니다. 기본적으로 패딩은 무시됩니다. [AutoTokenizer](/docs/transformers/main/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/main/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [입력 ID란 무엇인가요?](../glossary#input-ids)

attention_mask (`Union[torch.Tensor, dict]` 형상 `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 어텐션 수행을 방지하기 위한 마스크. `[0, 1]`에서 선택된 마스크 값:  - **마스크되지 않은** 토큰은 1, - **마스크된** 토큰은 0.  [어텐션 마스크란?](../glossary#attention-mask)

position_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 각 입력 시퀀스의 토큰 위치 인덱스입니다. `[0, config.n_positions - 1]` 범위에서 선택됩니다. [위치 ID란 무엇인가요?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *선택*) : 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key 및 value)입니다. 일반적으로 `use_cache=True` 또는 `config.use_cache=True`일 때 모델이 디코딩의 이전 단계에서 반환한 `past_key_values`로 구성됩니다. 입력으로 [Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `past_key_values`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/main/ko/internal/generation_utils#transformers.DynamicCache)가 초기화됩니다. 모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다. `past_key_values`를 사용하는 경우, 이 모델에 과거 key value 상태가 제공되지 않은 `input_ids`(처리되지 않은 항목)만 `(batch_size, unprocessed_length)` 형식으로 입력해야 하며, `(batch_size, sequence_length)` 형식의 모든 `input_ids`를 입력하지 않습니다.

inputs_embeds (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) : `input_ids`를 전달하는 대신 임베디드 표현을 직접 전달할 수 있습니다. 이는 모델의 내부 임베딩 조회 행렬보다 `input_ids` 인덱스를 관련 벡터로 변환하는 방식에 대해 더 많은 제어가 필요한 경우 유용합니다.

**반환값:** [BaseModelOutputWithPast](/docs/transformers/main/ko/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) 또는 `tuple(torch.Tensor)`

[BaseModelOutputWithPast](/docs/transformers/main/ko/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되었거나 `config.return_dict=False`인 경우)로, 구성([DiffusionGemmaConfig](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.DiffusionGemmaConfig)) 및 입력에 따라 다양한 요소를 포함합니다.

[DiffusionGemmaEncoderTextModel](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.DiffusionGemmaEncoderTextModel)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`) -- 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.

  `past_key_values`가 사용되면, `(batch_size, 1, hidden_size)` 형태의 시퀀스의 마지막 hidden-state만 출력됩니다.
- **past_key_values** (`Cache`, *선택 사항*, `use_cache=True`가 전달되었거나 `config.use_cache=True`인 경우 반환됨) -- [Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache) 인스턴스입니다. 자세한 내용은 [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요.

  순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록의 key와 value, 그리고 `config.is_encoder_decoder=True`인 경우 크로스 어텐션 블록의 key와 value)를 포함합니다(입력 `past_key_values` 참조).
- **hidden_states** (`tuple(torch.Tensor)`, *선택 사항*, `output_hidden_states=True`가 전달되었거나 `config.output_hidden_states=True`인 경우 반환됨) -- `torch.Tensor`의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 형태는 `(batch_size, sequence_length, hidden_size)`입니다.

  각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.
- **attentions** (`tuple(torch.Tensor)`, *선택 사항*, `output_attentions=True`가 전달되었거나 `config.output_attentions=True`인 경우 반환됨) -- 각 레이어마다 하나씩 포함된 `torch.Tensor`의 튜플로, 모양은 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치입니다.

## DiffusionGemmaDecoderModel[[transformers.DiffusionGemmaDecoderModel]]

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

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

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L1175)

DiffusionGemma용 Decoder 모델.

Bidirectional self-attention과 인코더의 KV cache에 대한 cross-attention을 사용하여 canvas 토큰을 처리합니다. 디코더는 KV cache를 읽지만 업데이트하지는 않습니다. 이러한 차이점을 제외하면 `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/main/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L1217)

**매개변수:**

decoder_input_ids (`torch.LongTensor`, shape `(batch_size, canvas_length)`) : 정제할 캔버스의 토큰 ID입니다.

past_key_values (`~cache_utils.Cache`, *선택*) : 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key 및 value)입니다. 일반적으로 `use_cache=True` 또는 `config.use_cache=True`일 때 모델이 디코딩의 이전 단계에서 반환한 `past_key_values`로 구성됩니다. 입력으로 [Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `past_key_values`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/main/ko/internal/generation_utils#transformers.DynamicCache)가 초기화됩니다. 모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다. `past_key_values`를 사용하는 경우, 이 모델에 과거 key value 상태가 제공되지 않은 `input_ids`(처리되지 않은 항목)만 `(batch_size, unprocessed_length)` 형식으로 입력해야 하며, `(batch_size, sequence_length)` 형식의 모든 `input_ids`를 입력하지 않습니다.

self_conditioning_logits (`torch.Tensor`, shape `(batch_size, canvas_length, vocab_size)`, *선택 사항*) : 이전 denoising 단계에서 가져온 self-conditioning logits으로, self-conditioning embeddings을 계산하는 데 사용됩니다.

self_conditioning_mask (`torch.BoolTensor`, shape `(batch_size,)`, *선택 사항*) : `self_conditioning_logits`에 대한 예시별 마스크입니다. `False`로 설정된 예시는 해당 예시에 대해 logits가 전달되지 않은 것과 동일한 방식으로 zeroed self-conditioning 신호를 받습니다. self-conditioning이 확률에 따라 예시별로 활성화되는 학습 시 유용합니다.

decoder_attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length+canvas_length)` 또는 `dict`, *선택 사항*) : 디코더 KV 캐시의 어텐션 마스크입니다. 패딩되거나 채워지지 않은 인코더 KV 캐시 항목을 지정하는 데 사용됩니다.

decoder_position_ids (`torch.LongTensor`, shape `(batch_size, canvas_length)`, *선택 사항*) : 캔버스 내 토큰의 위치 ID입니다.

**반환값:** [BaseModelOutput](/docs/transformers/main/ko/main_classes/output#transformers.modeling_outputs.BaseModelOutput) 또는 `tuple(torch.Tensor)`

설정([DiffusionGemmaConfig](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.DiffusionGemmaConfig)) 및 입력에 따라 다양한 요소를 포함하는 [BaseModelOutput](/docs/transformers/main/ko/main_classes/output#transformers.modeling_outputs.BaseModelOutput) 또는 `torch.Tensor` 튜플(`return_dict=False`이 전달되거나 `config.return_dict=False`인 경우).

[DiffusionGemmaDecoderModel](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.DiffusionGemmaDecoderModel)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`) -- 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.
- **hidden_states** (`tuple(torch.Tensor)`, *선택 사항*, `output_hidden_states=True`가 전달되었거나 `config.output_hidden_states=True`인 경우 반환됨) -- `torch.Tensor`의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 형태는 `(batch_size, sequence_length, hidden_size)`입니다.

  각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.
- **attentions** (`tuple(torch.Tensor)`, *선택 사항*, `output_attentions=True`가 전달되었거나 `config.output_attentions=True`인 경우 반환됨) -- 각 레이어마다 하나씩 포함된 `torch.Tensor`의 튜플로, 모양은 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치입니다.

## DiffusionGemmaForBlockDiffusion[[transformers.DiffusionGemmaForBlockDiffusion]]

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

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

[소스](https://github.com/huggingface/transformers/blob/main/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L1579)

블록 확산을 위한 DiffusionGemma 모델입니다. 프롬프트 KV 캐시로 조건부 설정된 입력 캔버스의 hidden states를 얻기 위해 `DiffusionGemmaModel`을 호출합니다. LM Head와 self-conditioning 블록을 사용하여 해당 hidden states를 다음 캔버스를 샘플링하기 위한 logits 및 다음 블록 확산 단계의 self-conditioning embeddings로 변환합니다.

#### 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/main/src/transformers/models/diffusion_gemma/modeling_diffusion_gemma.py#L1601)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 캔버스 컨텍스트로 인코딩될 프롬프트의 캐시되지 않은 토큰 ID입니다.

attention_mask (`torch.LongTensor`, shape `(batch_size, sequence_length)` 또는 `dict`, *선택 사항*) : 입력 토큰에 대한 마스크.

past_key_values (`~cache_utils.Cache`, *선택*) : 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key 및 value)입니다. 일반적으로 `use_cache=True` 또는 `config.use_cache=True`일 때 모델이 디코딩의 이전 단계에서 반환한 `past_key_values`로 구성됩니다. 입력으로 [Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `past_key_values`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/main/ko/internal/generation_utils#transformers.DynamicCache)가 초기화됩니다. 모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다. `past_key_values`를 사용하는 경우, 이 모델에 과거 key value 상태가 제공되지 않은 `input_ids`(처리되지 않은 항목)만 `(batch_size, unprocessed_length)` 형식으로 입력해야 하며, `(batch_size, sequence_length)` 형식의 모든 `input_ids`를 입력하지 않습니다.

position_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 각 입력 시퀀스의 토큰 위치 인덱스입니다. `[0, config.n_positions - 1]` 범위에서 선택됩니다. [위치 ID란 무엇인가요?](../glossary#position-ids)

decoder_input_ids (`torch.LongTensor`, shape `(batch_size, canvas_length)`, *선택 사항*) : 정제할 캔버스의 토큰 ID입니다.

self_conditioning_logits (`torch.Tensor`, shape `(batch_size, canvas_length, vocab_size)`, *선택 사항*) : 이전 denoising 단계의 self-conditioning logits입니다. self-conditioning embeddings을 계산하는 데 사용됩니다.

self_conditioning_mask (`torch.BoolTensor`, shape `(batch_size,)`, *선택 사항*) : `self_conditioning_logits`에 대한 예시별 마스크입니다. `False`로 설정된 예시는 해당 예시에 대해 logits가 전달되지 않은 것과 동일한 방식으로 zeroed self-conditioning 신호를 받습니다. self-conditioning이 확률에 따라 예시별로 활성화되는 학습 시 유용합니다.

decoder_attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length+canvas_length)` 또는 `dict`, *선택 사항*) : 디코더 KV 캐시의 어텐션 마스크입니다. 패딩되거나 채워지지 않은 인코더 KV 캐시 항목을 지정하는 데 사용됩니다.

decoder_position_ids (`torch.LongTensor`, shape `(batch_size, canvas_length)`, *선택 사항*) : 캔버스 내 토큰의 위치 ID입니다.

mm_encoder_outputs (`dict[str, ~modeling_outputs.BaseModelOutputWithPooling]`, *선택 사항*) : 키가 지원되는 모달리티이고 값이 해당 모달리티의 인코딩된 출력인 Dict입니다. 각 인코딩된 출력은 (`pooler_output`, *선택 사항*: `last_hidden_states`, *선택 사항*: `hidden_states`, *선택 사항*: `attentions`)의 튜플로 구성되며, `pooler_output`의 shape은 `(batch_size, sequence_length, hidden_size)`, *선택 사항*)입니다. 이는 인코더의 멀티모달 특징을 텍스트 임베딩으로 병합한 시퀀스입니다.

**반환값:** `DiffusionGemmaBlockDiffusionOutputWithPast` 또는 `tuple(torch.Tensor)`

`DiffusionGemmaBlockDiffusionOutputWithPast` 또는 `torch.Tensor`의 튜플(`return_dict=False`이 전달되었거나 `config.return_dict=False`인 경우)로, 구성([DiffusionGemmaConfig](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.DiffusionGemmaConfig))과 입력에 따라 다양한 요소를 포함합니다.

[DiffusionGemmaForBlockDiffusion](/docs/transformers/main/ko/model_doc/diffusion_gemma#transformers.DiffusionGemmaForBlockDiffusion)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **loss** (shape `(1,)`의 `torch.Tensor`, *선택 사항*) -- 언어 모델링 손실.
- **logits** (`torch.Tensor`, shape `(batch_size, canvas_length, config.text_config.vocab_size)`) -- 언어 모델링 헤드의 예측 점수 (SoftMax 적용 전 각 어휘 토큰의 점수).
- **past_key_values** (`Cache`, *선택 사항*, `use_cache=True`가 전달되었거나 `config.use_cache=True`인 경우 반환됨) -- [Cache](/docs/transformers/main/ko/internal/generation_utils#transformers.Cache) 인스턴스입니다. 자세한 내용은 [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요.

  순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록의 key와 value)를 포함합니다(입력 `past_key_values` 참조).
- **hidden_states** (`tuple(torch.Tensor)`, *선택 사항*, `output_hidden_states=True`가 전달되었거나 `config.output_hidden_states=True`인 경우 반환됨) -- `torch.Tensor`의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 형태는 `(batch_size, sequence_length, hidden_size)`입니다.

  각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.
- **attentions** (`tuple(torch.Tensor)`, *선택 사항*, `output_attentions=True`가 전달되었거나 `config.output_attentions=True`인 경우 반환됨) -- 각 레이어마다 하나씩 포함된 `torch.Tensor`의 튜플로, 모양은 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치입니다.
- **encoder_last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택*) -- 인코더의 마지막 레이어 출력에서 생성된 hidden state 시퀀스입니다. `input_ids`가 제공된 경우에만 설정되며, 예를 들어 학습 중 인코더에 대한 autoregressive loss를 계산하는 데 사용됩니다.

예:

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