# Gemma4 통합

## 개요

Gemma 4 12B Unified는 **인코더가 없는** 멀티모달 모델로, 사전 학습 및 지시 튜닝된 변형이 있습니다. 전용 인코더 타워를 사용하는 [표준 Gemma 4](./gemma4)와 달리, Gemma 4 12B Unified는 경량 선형 파이프라인을 통해 원시 입력을 언어 모델의 임베딩 공간으로 직접 투영합니다. 이를 통해 강력한 멀티모달 성능을 유지하면서 더 단순한 아키텍처를 구현합니다.

표준 Gemma 4와의 주요 차이점:
- **비전 타워 없음**: 원시 픽셀 패치가 2D 위치 임베딩을 인자화한 `Dense + LayerNorm` 파이프라인을 통해 LM 공간으로 직접 투사되어, 비전 인코더를 대체합니다.
- **오디오 타워 없음**: 16kHz의 원시 웨이브폼 샘플을 고정 길이의 프레임으로 분할한 후, 간단한 `RMSNorm → Linear` 파이프라인을 통해 투영하여, 멜 스펙트로그램 + Conformer 인코더를 대체합니다.
- **공유 멀티모달 파이프라인**: 비전과 오디오 모두 텍스트 히든 공간으로의 최종 투영에 동일한 `Gemma4UnifiedMultimodalEmbedder`(RMSNorm → Linear)를 사용합니다.

원본 Gemma 4 12B Unified 체크포인트는 [Gemma 4](https://huggingface.co/collections/google/gemma-4) 릴리스에서 찾을 수 있습니다.

### Encoder-Free Vision Pipeline

…

1. **패치화(Patchification)**: 이미지는 `16×16` 픽셀 패치로 나뉩니다
2. **Patch Merging**: 인접한 `3×3` 패치를 `48×48` 모델 패치로 병합하며, 각 패치는 `48² × 3 = 6,912`개의 원시 픽셀 채널을 가집니다
3. **Projection**: `LayerNorm → Dense → LayerNorm`은 각 병합된 패치를 LM 임베딩 차원으로 투영합니다
4. **Positional Embedding**: Factorized 2D positional embeddings가 추가됩니다 (x축과 y축에 대해 각각 학습된 임베딩을 합산)
5. **최종 Norm**: 최종적으로 `LayerNorm`이 적용됩니다
6. **Multimodal Embedder**: `RMSNorm → Linear`을 통해 텍스트 hidden size로 투사

표준 Gemma 4와 마찬가지로, 이 모델은 **고정된 토큰 예산**을 사용하여 **크기가 다른 이미지**를 처리합니다. 동일한 제약 조건이 적용됩니다:
- …
- 높이와 너비 모두 **48**(= 패치 크기 16 × 풀링 커널 3)로 나누어떨어져야 합니다

> [!IMPORTANT]
> Gemma 4 12B Unified는 **mean/std 정규화를 적용하지 않습니다**. 모델 자체의 patch embedding 레이어가 내부적으로 최종 스케일링을 처리합니다.

이미지당 소프트 토큰 수는 설정할 수 있습니다. 지원되는 옵션과 기본값(**280 soft tokens**)은 다음과 같습니다:

| 소프트 토큰 | 패치(풀링 전) | 대략적인 이미지 영역 |
|:-----------:|:------------------------:|:-------------------:|
| 70          | 630                      | 약 161K 픽셀        |
| 140         | 1,260                    | 약 323K 픽셀        |
| **280**     | **2,520**                | **약 645K 픽셀**    |
| 560         | 5,040                    | 약 130만 픽셀        |
| 1,120       | 10,080                   | 약 260만 픽셀        |

### Encoder-Free 오디오 파이프라인

오디오 파이프라인도 유사하게 단순화되었습니다. mel 스펙트로그램을 계산하고 Conformer 인코더를 통해 처리하는 대신, 원본 16 kHz 웨이브폼 샘플은 다음과 같이

1. 각 640개의 샘플(16 kHz에서 프레임당 40ms)로 구성된 고정 길이 프레임으로 **Chunked**
2. `Gemma4UnifiedMultimodalEmbedder`를 통해 `RMSNorm → Linear`로 **직접 투영**

**다운샘플링이 없으므로** 출력 소프트 토큰의 수는 입력 프레임 수와 동일하며, `ceil(num_samples / 640)`입니다.

## 사용 예시

아래 예제는 [Pipeline](/docs/transformers/v5.23.0/ko/main_classes/pipelines#transformers.Pipeline) 또는 [AutoModel](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoModel) 클래스를 사용하여 이미지와 오디오 샘플을 기반으로 텍스트를 생성하는 방법을 보여줍니다.

```python
from transformers import pipeline

pipe = pipeline(
    task="any-to-any",
    model="google/gemma-4-12B-it",
)

image_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?"
            }
        ]
    }
]

image_output = pipe(image_messages, return_full_text=False)
print(image_output[0]["generated_text"])

audio_messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Please transcribe the following audio:"},
            {
                "type": "audio",
                "url": "https://huggingface.co/datasets/eustlb/audio-samples/resolve/main/bcn_weather.mp3",
            },
        ],
    }
]

audio_output = pipe(audio_messages, return_full_text=False)
print(audio_output[0]["generated_text"])
```

### 이미지

```python
from transformers import AutoModelForMultimodalLM, AutoProcessor

model = AutoModelForMultimodalLM.from_pretrained(
    "google/gemma-4-12B-it",
    device_map="auto"
)
processor = AutoProcessor.from_pretrained(
    "google/gemma-4-12B-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,
).to(model.device)
input_len = inputs["input_ids"].shape[-1]

output = model.generate(**inputs, max_new_tokens=50, cache_implementation="static")
print(processor.decode(output[0][input_len:], skip_special_tokens=True))
```

### 오디오

```python
from transformers import AutoModelForMultimodalLM, AutoProcessor

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Please transcribe the following audio:"},
            {
                "type": "audio",
                "url": "https://huggingface.co/datasets/eustlb/audio-samples/resolve/main/bcn_weather.mp3",
            },
        ],
    }
]

model = AutoModelForMultimodalLM.from_pretrained(
    "google/gemma-4-12B-it",
    device_map="auto"
)
processor = AutoProcessor.from_pretrained(
    "google/gemma-4-12B-it"
)

inputs = processor.apply_chat_template(
    messages,
    tokenize=True,
    add_generation_prompt=True,
    return_dict=True,
    return_tensors="pt"
).to(model.device, dtype=model.dtype)

input_len = inputs["input_ids"].shape[-1]

outputs = model.generate(**inputs, max_new_tokens=200)
print(processor.decode(outputs[0][input_len:], skip_special_tokens=False))
```

## Gemma4UnifiedAudioConfig[[transformers.Gemma4UnifiedAudioConfig]]

#### transformers.Gemma4UnifiedAudioConfig[[transformers.Gemma4UnifiedAudioConfig]]

```python
transformers.Gemma4UnifiedAudioConfig(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, audio_embed_dim: int = 640, rms_norm_eps: float = 1e-06, initializer_range: float = 0.02)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified/configuration_gemma4_unified.py#L36)

**매개변수:**

audio_embed_dim (`int`, 기본값 640) : 멀티모달 임베더에 입력되는 오디오 특징의 차원. 각 오디오 소프트 토큰은 `audio_samples_per_token` 샘플의 원시 웨이브폼 프레임이므로 `audio_embed_dim == audio_samples_per_token`입니다.

rms_norm_eps (`float`, *선택 사항*, 기본값 `1e-06`) : rms normalization 레이어에서 사용되는 epsilon 값입니다.

initializer_range (`float`, *선택 사항*, 기본값 `0.02`) : 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다.

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

Configuration 객체는 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)의 문서를 참고하세요.

## Gemma4UnifiedConfig[[transformers.Gemma4UnifiedConfig]]

#### transformers.Gemma4UnifiedConfig[[transformers.Gemma4UnifiedConfig]]

```python
transformers.Gemma4UnifiedConfig(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.gemma4_unified.configuration_gemma4_unified.Gemma4UnifiedTextConfig | dict[str, typing.Any] | None = None, vision_config: transformers.models.gemma4_unified.configuration_gemma4_unified.Gemma4UnifiedVisionConfig | dict[str, typing.Any] | None = None, audio_config: transformers.models.gemma4_unified.configuration_gemma4_unified.Gemma4UnifiedAudioConfig | dict[str, typing.Any] | None = None, boi_token_id: int | None = 255999, eoi_token_id: int | None = 258882, image_token_id: int | None = 258880, video_token_id: int | None = 258884, boa_token_id: int | None = 256000, eoa_token_index: int | None = 258883, audio_token_id: int | None = 258881, initializer_range: float | None = 0.02, tie_word_embeddings: bool = True)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified/configuration_gemma4_unified.py#L283)

**매개변수:**

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

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

audio_config (`Union[~models.gemma4_unified.configuration_gemma4_unified.Gemma4UnifiedAudioConfig, dict[str, Any]]`, *선택*) : 오디오 백본의 config 객체 또는 사전입니다.

boi_token_id (`int`, *선택 사항*, 기본값 255999) : 이미지 프롬프트를 감싸는 이미지 시작 토큰 인덱스입니다.

eoi_token_id (`int`, *선택 사항*, 기본값 258882) : 이미지 프롬프트를 감싸는 이미지 종료 토큰 인덱스입니다.

image_token_id (`int`, *선택 사항*, 기본값 `258880`) : 입력 이미지의 자리표시자로 사용되는 이미지 토큰 인덱스입니다.

video_token_id (`int`, *선택 사항*, 기본값 `258884`) : 입력 비디오의 플레이스홀더로 사용되는 비디오 토큰 인덱스입니다.

boa_token_id (`int`, *선택 사항*, 기본값 256000) : 오디오 프롬프트를 감싸는 오디오 시작 토큰 인덱스입니다.

eoa_token_index (`int`, *선택 사항*, 기본값 258883) : 오디오 프롬프트를 감싸는 오디오 종료 토큰 인덱스입니다.

audio_token_id (`int`, *선택 사항*, 기본값 `258881`) : 입력 오디오의 플레이스홀더로 사용되는 오디오 토큰 인덱스입니다.

initializer_range (`float`, *선택 사항*, 기본값 `0.02`) : 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다.

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

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

Configuration 객체는 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)의 문서를 참고하세요.

예:

```python
>>> from transformers import (
>>>     Gemma4UnifiedAudioConfig,
>>>     Gemma4UnifiedConfig,
>>>     Gemma4UnifiedForConditionalGeneration,
>>>     Gemma4UnifiedTextConfig,
>>>     Gemma4UnifiedVisionConfig,
>>> )

>>> # Initializing a Gemma 4 Audio config.
>>> audio_config = Gemma4UnifiedAudioConfig()

>>> # Initializing a Gemma 4 Text config.
>>> text_config = Gemma4UnifiedTextConfig()

>>> # Initializing a Gemma 4 vision config.
>>> vision_config = Gemma4UnifiedVisionConfig()

>>> # Initializing a Gemma 4 config similar to google/gemma-4-e2b-it
>>> configuration = Gemma4UnifiedConfig(text_config, vision_config, audio_config)

>>> # Initializing a model from the google/gemma-4-e2b-it configuration
>>> model = Gemma4UnifiedForConditionalGeneration(configuration)

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

## Gemma4UnifiedTextConfig[[transformers.Gemma4UnifiedTextConfig]]

#### transformers.Gemma4UnifiedTextConfig[[transformers.Gemma4UnifiedTextConfig]]

```python
transformers.Gemma4UnifiedTextConfig(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 = 262144, initializer_range: float = 0.02, rms_norm_eps: float = 1e-06, use_cache: bool = True, 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 = 1024, layer_types: list[str] | None = None, final_logit_softcapping: float | None = None, use_bidirectional_attention: typing.Optional[typing.Literal['all', 'vision']] = 'vision', attention_k_eq_v: bool = False, num_kv_shared_layers: int = 0, use_double_wide_mlp: bool = False)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified/configuration_gemma4_unified.py#L88)

**매개변수:**

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`, *선택 사항*, 기본값 `262144`) : 이 모델이 사용될 수 있는 최대 시퀀스 길이입니다.

initializer_range (`float`, *선택 사항*, 기본값 `0.02`) : 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다.

rms_norm_eps (`float`, *선택 사항*, 기본값 `1e-06`) : rms normalization 레이어에서 사용되는 epsilon 값입니다.

use_cache (`bool`, *선택 사항*, 기본값 `True`) : 모델이 마지막 key/values attention을 반환할지 여부입니다(모든 모델에서 사용되지 않음). `config.is_decoder=True`인 경우 또는 모델이 decoder-only 생성 모델인 경우에만 관련이 있습니다.

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`, *선택 사항*, 기본값 `1024`) : Sliding window attention의 윈도우 크기입니다. `None`인 경우 sliding window가 적용되지 않습니다.

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

final_logit_softcapping (`float`, *선택 사항*) : 확률 분포를 계산하기 전에 최종 logits에 적용되는 소프트 캡핑 값입니다. Logits는 `tanh(logit / cap) * cap`로 스케일링됩니다.

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

attention_k_eq_v (`bool`, 기본값 `False`) : 키와 값이 동일한 투영 가중치를 공유하는지 여부. `True`인 경우, 키 투영 출력을 값 투영으로 재사용합니다.

num_kv_shared_layers (`int`, 기본값 0) : 동일한 key-value 투영을 공유하는 연속 디코더 레이어의 수입니다. 값이 0이면 공유가 없음을 의미하며(각 레이어가 독립적인 KV 투영을 가짐).

use_double_wide_mlp (`bool`, 기본값 `False`) : fused gate와 up projections를 사용하는 double-width MLP를 사용할지 여부.

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

Configuration 객체는 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)의 문서를 참고하세요.

## Gemma4UnifiedVisionConfig[[transformers.Gemma4UnifiedVisionConfig]]

#### transformers.Gemma4UnifiedVisionConfig[[transformers.Gemma4UnifiedVisionConfig]]

```python
transformers.Gemma4UnifiedVisionConfig(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, patch_size: int = 16, pooling_kernel_size: int = 3, mm_embed_dim: int = 3840, mm_posemb_size: int = 1120, rms_norm_eps: float = 1e-06, output_proj_dims: int = 3840, initializer_range: float = 0.02)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified/configuration_gemma4_unified.py#L238)

**매개변수:**

patch_size (`int`, 기본값 16) : 픽셀 단위의 이미지 패치 크기. 이미지는 이 해상도에서 먼저 패치화됩니다.

pooling_kernel_size (`int`, 기본값 3) : 패치를 모델 패치로 병합할 때 사용할 커널 크기. 3×3 병합은 `patch_size * pooling_kernel_size = 48` 픽셀 크기의 모델 패치를 생성합니다.

mm_embed_dim (`int`, 기본값 3840) : 패치 임베딩 Dense 투영의 숨겨진 차원(텍스트 모델의 `hidden_size`와 일치).

mm_posemb_size (`int`, 기본값 1120) : 분해된 2D 위치 임베딩 테이블의 크기입니다. 테이블의 모양은 `(mm_posemb_size, 2, mm_embed_dim)`이며, 축별로 조회됩니다.

rms_norm_eps (`float`, *선택 사항*, 기본값 `1e-06`) : rms normalization 레이어에서 사용되는 epsilon 값입니다.

output_proj_dims (`int`, 기본값 3840) : 멀티모달 임베더 투영의 출력 차원(텍스트 히든 사이즈로 매핑됨). 이는 런타임에 복합 구성의 text_config.hidden_size 값으로 설정됩니다.

initializer_range (`float`, *선택 사항*, 기본값 `0.02`) : 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다.

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

Configuration 객체는 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)의 문서를 참고하세요.

## Gemma4UnifiedAudioFeatureExtractor[[transformers.Gemma4UnifiedAudioFeatureExtractor]]

#### transformers.Gemma4UnifiedAudioFeatureExtractor[[transformers.Gemma4UnifiedAudioFeatureExtractor]]

```python
transformers.Gemma4UnifiedAudioFeatureExtractor(feature_size: int = 640, sampling_rate: int = 16000, padding_value: float = 0.0, audio_samples_per_token: int = 640, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified/feature_extraction_gemma4_unified.py#L30)

**매개변수:**

feature_size (`int`, *선택 사항*, 기본값 640) : 추출된 특징의 차원(토큰당 샘플 수).

sampling_rate (`int`, *선택 사항*, 기본값 16000) : 오디오 파일을 디지털화할 때 사용할 샘플링 주파수입니다. 헤르츠(Hz) 단위로 표시됩니다.

padding_value (`float`, *선택 사항*, 기본값 0.0) : 오디오를 패딩하는 데 사용되는 패딩 값입니다.

audio_samples_per_token (`int`, *선택 사항*, 기본값 640) : 출력 토큰당 원시 오디오 샘플 수. 16 kHz에서 640 샘플은 40ms에 해당합니다.

인코더 없이 원시 웨이브폼을 프레임으로 분할하는 오디오 특징 추출기

`audio_samples_per_token` 샘플 단위로 고정 길이의 프레임으로 분할하는 표준 Gemma4 오디오 피처 추출기와 달리, 이 통합 버전은 16 kHz의 원시 오디오를 단순히 분할합니다. 각 프레임은 원시 웨이브폼 샘플을 특징으로 하는 단일 오디오 소프트 토큰이 됩니다.

#### __call__[[transformers.Gemma4UnifiedAudioFeatureExtractor.__call__]]

```python
__call__(raw_speech: numpy.ndarray | list[float] | list[numpy.ndarray] | list[list[float]], padding: bool | str = 'longest', max_length: int | None = None, truncation: bool = True, return_tensors: str | transformers.utils.generic.TensorType | None = None, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified/feature_extraction_gemma4_unified.py#L95)

**매개변수:**

raw_speech : 처리할 원시 오디오 웨이브폼입니다.

padding (`str`, *선택 사항*, 기본값 `"longest"`) : 길이가 다른 배치에 대한 패딩 전략입니다.

max_length (`int`, *선택 사항*) : 오디오당 생성할 최대 토큰 수.

truncation (`bool`, *선택 사항*, 기본값 `True`) : `max_length` 토큰을 초과하는 오디오를 잘라낼지 여부.

return_tensors (`str`, *선택 사항*) : 반환할 텐서의 유형.

통합 모델을 위해 원시 오디오 웨이브폼을 고정 길이의 프레임으로 분할합니다.

## Gemma4UnifiedImageProcessor[[transformers.Gemma4UnifiedImageProcessor]]

#### transformers.Gemma4UnifiedImageProcessor[[transformers.Gemma4UnifiedImageProcessor]]

```python
transformers.Gemma4UnifiedImageProcessor(**kwargs: *<class 'transformers.models.gemma4_unified.image_processing_gemma4_unified.Gemma4UnifiedImageProcessorKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified/image_processing_gemma4_unified.py#L214)

**매개변수:**

do_convert_rgb (`bool`, *kwargs*, *선택 사항*, 기본값 `True`) : 이미지를 RGB로 변환할지 여부.

do_resize (`bool`, *kwargs*, *선택 사항*, 기본값 `True`) : 이미지를 리사이즈할지 여부.

size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*, 기본값 `None`) : 모델의 최대 입력 차원을 설명합니다.

default_to_square (`bool`, *kwargs*, *선택 사항*, 기본값 `True`) : size가 int인 경우 리사이즈 시 정사각형 이미지로 설정할지 여부.

crop_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : `center_crop`를 적용한 후의 출력 이미지 크기.

resample (`Annotated[Union[int, PILImageResampling, NoneType], None]`, *kwargs*, 기본값 `3`) : 이미지를 리사이즈할 때 사용할 리샘플링 필터입니다. `PILImageResampling` enum 중 하나를 사용할 수 있습니다. `do_resize`가 `True`로 설정된 경우에만 효과가 있습니다.

do_rescale (`bool`, *kwargs*, *선택 사항*, 기본값 `True`) : 이미지를 다시 스케일링할지 여부.

rescale_factor (`float`, *kwargs*, *선택 사항*, 기본값 `0.00392156862745098`) : `do_rescale`이 `True`로 설정된 경우 이미지를 재조정하는 데 사용되는 재조정 계수입니다.

do_normalize (`bool`, *kwargs*, *선택 사항*, 기본값 `False`) : 이미지를 정규화할지 여부.

image_mean (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *선택 사항*, 기본값은 `[0.0, 0.0, 0.0]`) : 정규화에 사용할 이미지 평균입니다. `do_normalize`가 `True`로 설정된 경우에만 효과가 있습니다.

image_std (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *선택 사항*, 기본값은 `[1.0, 1.0, 1.0]`) : 정규화에 사용할 이미지 표준 편차입니다. `do_normalize`가 `True`로 설정된 경우에만 효과가 있습니다.

do_pad (`bool`, *kwargs*, *선택*) : 이미지를 패딩할지 여부입니다. 패딩은 배치 내 가장 큰 크기로 수행하거나, 이미지마다 고정된 정사각형 크기로 수행합니다. 정확한 패딩 전략은 모델에 따라 달라집니다.

pad_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : 이미지를 패딩할 `{"height": int, "width" int}` 크기를 지정합니다. 전처리용으로 제공된 모든 이미지 크기보다 커야 합니다. `pad_size`가 제공되지 않으면, 이미지는 배치 내 가장 큰 높이와 너비로 패딩됩니다. `do_pad=True.`일 때만 적용됩니다.

do_center_crop (`bool`, *kwargs*, *선택*) : 이미지를 중앙 크롭할지 여부.

data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *선택*) : `ChannelDimension.FIRST`만 지원됩니다. 느린 프로세서와의 호환성을 위해 추가되었습니다.

input_data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *선택*) : 입력 이미지의 채널 차원 형식입니다. 설정하지 않으면 입력 이미지에서 채널 차원 형식을 추론합니다. 다음 중 하나일 수 있습니다: - `"channels_first"` 또는 `ChannelDimension.FIRST`: (num_channels, height, width) 형식의 이미지. - `"channels_last"` 또는 `ChannelDimension.LAST`: (height, width, num_channels) 형식의 이미지. - `"none"` 또는 `ChannelDimension.NONE`: (height, width) 형식의 이미지.

device (`Annotated[Union[str, torch.device, NoneType], None]`, *kwargs*) : 비디오를 처리할 장치입니다. 설정되지 않은 경우, 입력 비디오에서 장치를 추론합니다.

return_tensors (`Annotated[str | ~utils.generic.TensorType | None, None]`, *kwargs*) : `'pt'`로 설정된 경우 스택된 텐서를 반환하고, 그렇지 않으면 텐서 목록을 반환합니다.

disable_grouping (`bool`, *kwargs*, *선택*) : 이미지의 크기에 따른 그룹화를 비활성화하여 이미지를 배치 대신 개별적으로 처리할지 여부입니다. None인 경우, 이미지가 CPU에 있으면 True, 그렇지 않으면 False로 설정됩니다. 이 선택은 https://github.com/huggingface/transformers/pull/38157에 자세히 설명된 경험적 관찰에 기반합니다.

image_seq_length (`int`, *kwargs*, *선택*) : 입력의 각 이미지에 사용할 이미지 토큰의 수입니다. 하위 호환성을 위해 추가되었지만, 향후 모델에서는 프로세서 속성으로 설정해야 합니다.

patch_size (`int`, *kwargs*, *선택 사항*) : 병합 전 픽셀 단위 teacher 이미지 패치 크기.

max_soft_tokens (`int`, *kwargs*, *선택*) : 패치 병합 후 이미지당 최대 소프트(비전) 토큰 수. {70, 140, 280, 560, 1120} 중 하나여야 합니다.

pooling_kernel_size (`int`, *kwargs*, *선택*) : teacher patches를 model patches로 병합하기 위한 커널 크기.

Gemma4 통합 이미지 프로세서를 생성합니다.

## Gemma4UnifiedVideoProcessor[[transformers.Gemma4UnifiedVideoProcessor]]

#### transformers.Gemma4UnifiedVideoProcessor[[transformers.Gemma4UnifiedVideoProcessor]]

```python
transformers.Gemma4UnifiedVideoProcessor(**kwargs: *<class 'transformers.models.gemma4_unified.video_processing_gemma4_unified.Gemma4UnifiedVideoProcessorKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified/video_processing_gemma4_unified.py#L216)

**매개변수:**

do_convert_rgb (`bool`, *kwargs*, *선택 사항*, 기본값 `True`) : 이미지를 RGB로 변환할지 여부.

do_resize (`bool`, *kwargs*, *선택 사항*, 기본값 `True`) : 이미지를 리사이즈할지 여부.

size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*, 기본값 `None`) : 모델의 최대 입력 차원을 설명합니다.

default_to_square (`bool`, *kwargs*, *선택 사항*, 기본값 `True`) : size가 int인 경우 리사이즈 시 정사각형 이미지로 설정할지 여부.

resample (`Annotated[Union[int, PILImageResampling, NoneType], None]`, *kwargs*, 기본값 `3`) : 이미지를 리사이즈할 때 사용할 리샘플링 필터입니다. `PILImageResampling` enum 중 하나를 사용할 수 있습니다. `do_resize`가 `True`로 설정된 경우에만 효과가 있습니다.

do_rescale (`bool`, *kwargs*, *선택 사항*, 기본값 `True`) : 이미지를 다시 스케일링할지 여부.

rescale_factor (`float`, *kwargs*, *선택 사항*, 기본값 `0.00392156862745098`) : `do_rescale`이 `True`로 설정된 경우 이미지를 재조정하는 데 사용되는 재조정 계수입니다.

do_normalize (`bool`, *kwargs*, *선택 사항*, 기본값 `True`) : 이미지를 정규화할지 여부.

image_mean (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *선택 사항*, 기본값은 `[0.0, 0.0, 0.0]`) : 정규화에 사용할 이미지 평균입니다. `do_normalize`가 `True`로 설정된 경우에만 효과가 있습니다.

image_std (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *선택 사항*, 기본값은 `[1.0, 1.0, 1.0]`) : 정규화에 사용할 이미지 표준 편차입니다. `do_normalize`가 `True`로 설정된 경우에만 효과가 있습니다.

do_center_crop (`bool`, *kwargs*, *선택*) : 이미지를 중앙 크롭할지 여부.

do_pad (`bool`, *kwargs*, *선택*) : 이미지를 패딩할지 여부입니다. 패딩은 배치 내 가장 큰 크기로 수행하거나, 이미지마다 고정된 정사각형 크기로 수행합니다. 정확한 패딩 전략은 모델에 따라 달라집니다.

crop_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : `center_crop`를 적용한 후의 출력 이미지 크기.

data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *선택*) : `ChannelDimension.FIRST`만 지원됩니다. 느린 프로세서와의 호환성을 위해 추가되었습니다.

input_data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *선택*) : 입력 이미지의 채널 차원 형식입니다. 설정하지 않으면 입력 이미지에서 채널 차원 형식을 추론합니다. 다음 중 하나일 수 있습니다: - `"channels_first"` 또는 `ChannelDimension.FIRST`: (num_channels, height, width) 형식의 이미지. - `"channels_last"` 또는 `ChannelDimension.LAST`: (height, width, num_channels) 형식의 이미지. - `"none"` 또는 `ChannelDimension.NONE`: (height, width) 형식의 이미지.

device (`Annotated[Union[str, torch.device, NoneType], None]`, *kwargs*) : 비디오를 처리할 장치입니다. 설정되지 않은 경우, 입력 비디오에서 장치를 추론합니다.

do_sample_frames (`bool`, *kwargs*, *선택 사항*, 기본값 `True`) : 처리 전에 비디오에서 프레임을 샘플링할지, 아니면 비디오 전체를 처리할지를 결정합니다.

video_metadata (`Annotated[~video_utils.VideoMetadata | dict | list[dict | ~video_utils.VideoMetadata] | list[list[dict | ~video_utils.VideoMetadata]] | None, None]`, *kwargs*) : 총 길이, fps, 총 프레임 수에 대한 정보를 포함하는 비디오의 메타데이터입니다. 비디오에서 프레임을 샘플링하거나 타임스탬프를 계산하는 데 사용됩니다. 비디오를 수동으로 디코딩하여 처리하려는 경우를 제외하고는 메타데이터를 전달하지 마세요

fps (`Annotated[int | float | None, None]`, *kwargs*) : `do_sample_frames=True`일 때 초당 샘플링할 대상 프레임 수.

num_frames (`Annotated[int | None, None]`, *kwargs*, 기본값 `32`) : `do_sample_frames=True`일 때 샘플링할 최대 프레임 수.

return_metadata (`bool`, *kwargs*, *선택 사항*, 기본값 `False`) : 비디오 메타데이터를 반환할지 여부입니다. 비디오 메타데이터는 비디오 길이, fps, 디코딩 백엔드 등에 대한 정보를 포함하는 객체입니다.

return_tensors (`Annotated[str | ~utils.generic.TensorType | None, None]`, *kwargs*) : 설정된 경우, 특정 프레임워크의 텐서를 반환합니다. 허용되는 값은 다음과 같습니다: - `'pt'`: PyTorch `torch.Tensor` 객체를 반환합니다. - `'np'`: NumPy `np.ndarray` 객체를 반환합니다.

patch_size (`int`, *kwargs*, *선택 사항*) : 픽셀 단위 이미지 패치의 크기.

max_soft_tokens (`int`, *kwargs*, *선택*) : 비디오 프레임당 최대 소프트(비전) 토큰 수. {70, 140, 280, 560, 1120} 중 하나여야 합니다.

pooling_kernel_size (`int`, *kwargs*, *선택 사항*) : 패치화 이후에 적용되는 공간 풀링 커널 크기.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/v5.23.0/ko/main_classes/processors#transformers.ProcessingKwargs), *optional*) : 각 모달리티(텍스트, 이미지, 비디오, 오디오)에 대한 추가 처리 옵션입니다. 모델별 매개변수는 위에 나열되어 있으며, 지원되는 인수의 전체 목록은 TypedDict 클래스를 참조하세요.

Gemma4UnifiedVideoProcessor 비디오 프로세서를 생성합니다.

#### preprocess[[transformers.Gemma4UnifiedVideoProcessor.preprocess]]

```python
preprocess(videos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]]], **kwargs: *<class 'transformers.models.gemma4_unified.video_processing_gemma4_unified.Gemma4UnifiedVideoProcessorKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified/video_processing_gemma4_unified.py#L275)

**매개변수:**

videos (`Union[list[PIL.Image.Image], numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor], list[list[PIL.Image.Image]], list[list[numpy.ndarray]], list[list[torch.Tensor]], ~video_utils.URL, list[~video_utils.URL], list[list[~video_utils.URL]], ~video_utils.Path, list[~video_utils.Path], list[list[~video_utils.Path]]]`) : 전처리할 비디오입니다. 픽셀 값이 0에서 255 범위로 이루어진 단일 비디오 또는 비디오 배치(batch)를 입력으로 기대합니다. 픽셀 값이 0에서 1 범위로 이루어진 비디오를 전달하는 경우, `do_rescale=False`로 설정하십시오.

do_convert_rgb (`bool`, *kwargs*, *선택*) : 이미지를 RGB로 변환할지 여부.

do_resize (`bool`, *kwargs*, *선택*) : 이미지를 리사이즈할지 여부.

size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : 모델의 최대 입력 차원을 설명합니다.

default_to_square (`bool`, *kwargs*, *선택*) : size가 int인 경우 리사이즈 시 정사각형 이미지로 기본 설정할지 여부.

resample (`Annotated[Union[int, PILImageResampling, NoneType], None]`, *kwargs*) : 이미지를 리사이즈할 때 사용할 리샘플링 필터입니다. `PILImageResampling` enum 중 하나를 사용할 수 있습니다. `do_resize`가 `True`로 설정된 경우에만 효과가 있습니다.

do_rescale (`bool`, *kwargs*, *선택*) : 이미지를 다시 스케일링할지 여부.

rescale_factor (`float`, *kwargs*, *선택*) : `do_rescale`가 `True`로 설정된 경우 이미지를 재조정하는 데 사용되는 재조정 계수입니다.

do_normalize (`bool`, *kwargs*, *선택*) : 이미지를 정규화할지 여부.

image_mean (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *선택*) : 정규화에 사용할 이미지 평균값. `do_normalize`이 `True`로 설정된 경우에만 효과가 있습니다.

image_std (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *선택*) : 정규화에 사용할 이미지 표준 편차. `do_normalize`가 `True`로 설정된 경우에만 효과가 있습니다.

do_center_crop (`bool`, *kwargs*, *선택*) : 이미지를 중앙 크롭할지 여부.

do_pad (`bool`, *kwargs*, *선택*) : 이미지를 패딩할지 여부입니다. 패딩은 배치 내 가장 큰 크기로 수행하거나, 이미지마다 고정된 정사각형 크기로 수행합니다. 정확한 패딩 전략은 모델에 따라 달라집니다.

crop_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : `center_crop`를 적용한 후의 출력 이미지 크기.

data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *선택*) : `ChannelDimension.FIRST`만 지원됩니다. 느린 프로세서와의 호환성을 위해 추가되었습니다.

input_data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *선택*) : 입력 이미지의 채널 차원 형식입니다. 설정하지 않으면 입력 이미지에서 채널 차원 형식을 추론합니다. 다음 중 하나일 수 있습니다: - `"channels_first"` 또는 `ChannelDimension.FIRST`: (num_channels, height, width) 형식의 이미지. - `"channels_last"` 또는 `ChannelDimension.LAST`: (height, width, num_channels) 형식의 이미지. - `"none"` 또는 `ChannelDimension.NONE`: (height, width) 형식의 이미지.

device (`Annotated[Union[str, torch.device, NoneType], None]`, *kwargs*) : 비디오를 처리할 장치입니다. 설정되지 않은 경우, 입력 비디오에서 장치를 추론합니다.

do_sample_frames (`bool`, *kwargs*, *선택*) : 처리 전에 비디오에서 프레임을 샘플링할지, 아니면 비디오 전체를 처리할지 여부.

video_metadata (`Annotated[~video_utils.VideoMetadata | dict | list[dict | ~video_utils.VideoMetadata] | list[list[dict | ~video_utils.VideoMetadata]] | None, None]`, *kwargs*) : 총 길이, fps, 총 프레임 수에 대한 정보를 포함하는 비디오의 메타데이터입니다. 비디오에서 프레임을 샘플링하거나 타임스탬프를 계산하는 데 사용됩니다. 비디오를 수동으로 디코딩하여 처리하려는 경우를 제외하고는 메타데이터를 전달하지 마세요

fps (`Annotated[int | float | None, None]`, *kwargs*) : `do_sample_frames=True`일 때 초당 샘플링할 대상 프레임 수.

num_frames (`Annotated[int | None, None]`, *kwargs*) : `do_sample_frames=True`일 때 샘플링할 최대 프레임 수.

return_metadata (`bool`, *kwargs*, *선택*) : 비디오 메타데이터를 반환할지 여부입니다. 비디오 메타데이터는 비디오 길이, fps, 디코딩 백엔드 등에 대한 정보를 포함하는 객체입니다.

return_tensors (`Annotated[str | ~utils.generic.TensorType | None, None]`, *kwargs*) : `'pt'`로 설정된 경우 스택된 텐서를 반환하고, 그렇지 않으면 텐서 목록을 반환합니다.

patch_size (`int`, *kwargs*, *선택 사항*) : 픽셀 단위 이미지 패치의 크기.

max_soft_tokens (`int`, *kwargs*, *선택*) : 비디오 프레임당 최대 소프트(비전) 토큰 수. {70, 140, 280, 560, 1120} 중 하나여야 합니다.

pooling_kernel_size (`int`, *kwargs*, *선택 사항*) : 패치화 이후에 적용되는 공간 풀링 커널 크기.

**반환값:** `~image_processing_base.BatchFeature`

- **data** (`dict`) -- __call__ 메서드가 반환하는 리스트/배열/텐서 딕셔너리('pixel_values' 등).
- **tensor_type** (`Union[None, str, TensorType]`, *선택 사항*) -- 초기화 시 PyTorch/Numpy 텐서에서 정수 목록을 변환하려면 여기에 tensor_type을 지정할 수 있습니다.

## Gemma4UnifiedProcessor[[transformers.Gemma4UnifiedProcessor]]

#### transformers.Gemma4UnifiedProcessor[[transformers.Gemma4UnifiedProcessor]]

```python
transformers.Gemma4UnifiedProcessor(feature_extractor, image_processor, tokenizer, video_processor, chat_template = None, image_seq_length: int = 280, audio_seq_length: int = 750, audio_ms_per_token: int = 40, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified/processing_gemma4_unified.py#L94)

**매개변수:**

feature_extractor (*Gemma4UnifiedAudioFeatureExtractor*) : feature extractor는 필수 입력입니다.

image_processor (*Gemma4UnifiedImageProcessor*) : 이미지 프로세서가 필수 입력입니다.

tokenizer (*tokenizer_class*) : 토크나이저는 필수 입력입니다.

video_processor (*Gemma4UnifiedVideoProcessor*) : 비디오 프로세서가 필수 입력입니다.

chat_template (*str*) : 채팅의 메시지 목록을 토큰화 가능한 문자열로 변환하는 Jinja 템플릿입니다.

image_seq_length (*int*, *optional*, 기본값 280) : 플레이스홀더 확장에 사용되는 이미지당 소프트 토큰 수입니다.

audio_seq_length (*int*, *optional*, 기본값 750) : 오디오 세그먼트당 최대 오디오 소프트 토큰 수입니다. 동적 오디오 토큰 수가 계산될 때 상한으로 작용합니다.

audio_ms_per_token (*int*, *optional*, 기본값 40) : 출력 소프트 토큰당 오디오 밀리초 수. `ceil(duration_ms / audio_ms_per_token)`로 오디오 플레이스홀더 토큰 수를 동적으로 계산하는 데 사용됩니다. 기본값 40은 10ms 프레임에 대한 SSCP 컨볼루션의 4배 시간 감소에서 유래합니다.

feature extractor, image processor, tokenizer, video processor를 단일 프로세서로 감싸는 Gemma4UnifiedProcessor를 생성합니다.

[*Gemma4UnifiedProcessor*]는 [*Gemma4UnifiedAudioFeatureExtractor*], [*Gemma4UnifiedImageProcessor*], [*tokenizer_class*], 그리고 [*Gemma4UnifiedVideoProcessor*]의 모든 기능을 제공합니다. 자세한 내용은 [*~Gemma4UnifiedAudioFeatureExtractor*], [*~Gemma4UnifiedImageProcessor*], [*~tokenizer_class*], 그리고 [*~Gemma4UnifiedVideoProcessor*]를 참고하세요.

#### __call__[[transformers.Gemma4UnifiedProcessor.__call__]]

```python
__call__(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, text: str | list[str] | list[list[str]] | None = None, videos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = None, audio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None, **kwargs: *<class 'transformers.processing_utils.ProcessingKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/processing_utils.py#L670)

**매개변수:**

images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`, *선택*) : 전처리할 이미지. 픽셀 값이 0에서 255 범위로 이루어진 단일 이미지 또는 배치 이미지를 기대합니다. 픽셀 값이 0에서 1 범위로 이루어진 이미지를 전달하는 경우 `do_rescale=False`로 설정하세요.

text (`Union[str, list[str], list[list[str]]]`, *선택*) : 인코딩할 시퀀스 또는 시퀀스 배치입니다. 각 시퀀스는 문자열 또는 문자열 목록(사전 토큰화된 문자열)일 수 있습니다. 사전 토큰화된 입력을 전달하는 경우, 배치 입력과의 혼동을 피하기 위해 `is_split_into_words=True`를 설정하세요.

videos (`Union[list[PIL.Image.Image], numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor], list[list[PIL.Image.Image]], list[list[numpy.ndarray]], list[list[torch.Tensor]], ~video_utils.URL, list[~video_utils.URL], list[list[~video_utils.URL]], ~video_utils.Path, list[~video_utils.Path], list[list[~video_utils.Path]]]`, *선택*) : 전처리할 비디오입니다. 픽셀 값이 0에서 255 범위를 가지는 단일 비디오 또는 비디오 배치(batch)를 기대합니다. 픽셀 값이 0에서 1 범위를 가지는 비디오를 전달하는 경우 `do_rescale=False`로 설정하세요.

audio (`Union[numpy.ndarray, torch.Tensor, collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence[torch.Tensor]]`, *선택 사항*) : 준비할 오디오 또는 오디오 배치입니다. 각 오디오는 NumPy 배열 또는 PyTorch 텐서일 수 있습니다. NumPy 배열/PyTorch 텐서의 경우, 각 오디오의 shape은 (C, T)여야 하며, 여기서 C는 채널 수, T는 오디오의 샘플 길이입니다.

return_mm_token_type_ids (`bool`, *kwargs*) : 멀티모달 플레이스홀더 토큰의 위치를 나타내는 멀티모달 토큰 타입 ID를 반환할지 여부.

return_text_replacement_offsets (`bool`, *kwargs*) : 각 멀티모달 플레이스홀더 및 그 대체 문자열의 문자 오프셋을 반환할지 여부.

return_tensors (`str` 또는 [TensorType](/docs/transformers/v5.23.0/ko/internal/file_utils#transformers.TensorType), *optional*) : 설정된 경우, 특정 프레임워크의 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:  - `'pt'`: PyTorch `torch.Tensor` 객체를 반환합니다. - `'np'`: NumPy `np.ndarray` 객체를 반환합니다.

- ****kwargs** ([ProcessingKwargs](/docs/transformers/v5.23.0/ko/main_classes/processors#transformers.ProcessingKwargs), *optional*) : 각 모달리티(텍스트, 이미지, 비디오, 오디오)에 대한 추가 처리 옵션입니다. 모델별 매개변수는 위에 나열되어 있으며, 지원되는 인수의 전체 목록은 TypedDict 클래스를 참조하세요.

## Gemma4UnifiedPreTrainedModel[[transformers.Gemma4UnifiedPreTrainedModel]]

#### transformers.Gemma4UnifiedPreTrainedModel[[transformers.Gemma4UnifiedPreTrainedModel]]

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified/modeling_gemma4_unified.py#L527)

**매개변수:**

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

이 모델은 [PreTrainedModel](/docs/transformers/v5.23.0/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.Gemma4UnifiedPreTrainedModel.forward]]

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

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

## Gemma4UnifiedModel[[transformers.Gemma4UnifiedModel]]

#### transformers.Gemma4UnifiedModel[[transformers.Gemma4UnifiedModel]]

```python
transformers.Gemma4UnifiedModel(config: Gemma4UnifiedConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified/modeling_gemma4_unified.py#L936)

**매개변수:**

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

언어 모델링 헤드가 없는 언어 모델, 비전 백본, 오디오 백본으로 구성된 기본 Gemma 4 모델.

이 모델은 [PreTrainedModel](/docs/transformers/v5.23.0/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.Gemma4UnifiedModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, pixel_values: typing.Optional[torch.Tensor] = None, pixel_values_videos: typing.Optional[torch.Tensor] = None, input_features: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, input_features_mask: typing.Optional[torch.Tensor] = 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, use_cache: bool | None = None, image_position_ids: typing.Optional[torch.LongTensor] = None, video_position_ids: typing.Optional[torch.LongTensor] = None, num_frames_per_video: 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/gemma4_unified/modeling_gemma4_unified.py#L1037)

**매개변수:**

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

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

pixel_values_videos (`torch.Tensor`, shape `(batch_size, num_frames, num_channels, frame_size, frame_size)`, *선택 사항*) : 입력 비디오에 해당하는 텐서입니다. 비디오의 픽셀 값은 [Gemma4UnifiedVideoProcessor](/docs/transformers/v5.23.0/ko/model_doc/gemma4_unified#transformers.Gemma4UnifiedVideoProcessor)를 사용하여 얻을 수 있습니다. 자세한 내용은 [Gemma4UnifiedVideoProcessor.__call__()](/docs/transformers/v5.23.0/ko/model_doc/molmo2#transformers.Molmo2VideoProcessor.__call__)를 참조하세요 ([Gemma4UnifiedProcessor](/docs/transformers/v5.23.0/ko/model_doc/gemma4_unified#transformers.Gemma4UnifiedProcessor)는 비디오 처리에 [Gemma4UnifiedVideoProcessor](/docs/transformers/v5.23.0/ko/model_doc/gemma4_unified#transformers.Gemma4UnifiedVideoProcessor)를 사용합니다).

input_features (`torch.Tensor`, shape `(batch_size, sequence_length, feature_dim)`, *선택 사항*) : 입력 오디오 특징에 해당하는 텐서입니다. 오디오 특징은 [Gemma4UnifiedAudioFeatureExtractor](/docs/transformers/v5.23.0/ko/model_doc/gemma4_unified#transformers.Gemma4UnifiedAudioFeatureExtractor)를 사용하여 얻을 수 있습니다. 자세한 내용은 [Gemma4UnifiedAudioFeatureExtractor.__call__()](/docs/transformers/v5.23.0/ko/model_doc/gemma4_unified#transformers.Gemma4UnifiedAudioFeatureExtractor.__call__)를 참조하세요 ([Gemma4UnifiedProcessor](/docs/transformers/v5.23.0/ko/model_doc/gemma4_unified#transformers.Gemma4UnifiedProcessor)는 오디오 처리에 [Gemma4UnifiedAudioFeatureExtractor](/docs/transformers/v5.23.0/ko/model_doc/gemma4_unified#transformers.Gemma4UnifiedAudioFeatureExtractor)를 사용합니다).

attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크입니다. `[0, 1]`에서 선택된 마스크 값: - **마스크되지 않은** 토큰은 1, - **마스크된** 토큰은 0. [attention 마스크란?](../glossary#attention-mask)

input_features_mask (`torch.Tensor`, shape `(num_images, seq_length)`) : 입력 오디오에 대한 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/v5.23.0/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `past_key_values`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/v5.23.0/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/v5.23.0/ko/model_doc/auto#transformers.AutoProcessor)를 사용하여 얻을 수 있습니다. 자세한 내용은 [ProcessorMixin.__call__()](/docs/transformers/v5.23.0/ko/main_classes/processors#transformers.ProcessorMixin.__call__)를 참조하세요.

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

use_cache (`bool`, *선택 사항*) : `True`로 설정하면 `past_key_values` 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(`past_key_values` 참조).

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

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

num_frames_per_video (`torch.LongTensor`, shape `(num_videos,)`, *선택 사항*) : 각 비디오에 속하는 프레임 수. 모든 비디오의 프레임이 단일 축을 따라 연결되므로 `pixel_values_videos`가 전달될 때 필수입니다.

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)`, *선택 사항*)입니다. 이는 인코더의 멀티모달 특징을 텍스트 임베딩으로 병합한 시퀀스입니다.

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

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

[Gemma4UnifiedModel](/docs/transformers/v5.23.0/ko/model_doc/gemma4_unified#transformers.Gemma4UnifiedModel)의 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/v5.23.0/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 가중치입니다.
- **image_hidden_states** (`torch.Tensor`, *선택 사항*) -- 크기가 `(batch_size, num_images, sequence_length, hidden_size)`인 `torch.Tensor`. 비전 인코더가 생성한 모델의 image_hidden_states로, 마지막 hidden state를 투영한 후의 값입니다.
- **audio_hidden_states** (`torch.Tensor`, *선택*) -- 크기가 `(batch_size, num_images, sequence_length, hidden_size)`인 `torch.Tensor`. 오디오 인코더에 의해 생성된 모델의 audio_hidden_states로, 마지막 hidden state를 투영한 후의 값입니다.
- **shared_kv_states** (`dict`, *선택 사항*) -- 레이어 유형 문자열을 (key_states, value_states) 텐서 튜플로 매핑하는 사전. KV 공유 시 레이어 간 공유된 KV 상태를 전달하는 데 사용됩니다.

## Gemma4UnifiedTextModel[[transformers.Gemma4UnifiedTextModel]]

#### transformers.Gemma4UnifiedTextModel[[transformers.Gemma4UnifiedTextModel]]

```python
transformers.Gemma4UnifiedTextModel(config: Gemma4UnifiedTextConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified/modeling_gemma4_unified.py#L560)

**매개변수:**

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

언어 모델링 헤드가 없는 기본 Gemma 4 통합 언어 모델입니다.

이 모델은 [PreTrainedModel](/docs/transformers/v5.23.0/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.Gemma4UnifiedTextModel.forward]]

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified/modeling_gemma4_unified.py#L589)

**매개변수:**

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

attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크입니다. `[0, 1]`에서 선택된 마스크 값: - **마스크되지 않은** 토큰은 1, - **마스크된** 토큰은 0. [attention 마스크란?](../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/v5.23.0/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `past_key_values`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/v5.23.0/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` 인덱스를 관련 벡터로 변환하는 방식에 대해 더 많은 제어가 필요한 경우 유용합니다.

use_cache (`bool`, *선택 사항*) : `True`로 설정하면 `past_key_values` 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(`past_key_values` 참조).

logits_to_keep (`Union[int, torch.Tensor]`, *선택 사항*, 기본값 `0`) : `int`인 경우, 마지막 `logits_to_keep` 토큰에 대한 logits를 계산합니다. `0`인 경우, 모든 `input_ids`에 대한 logits를 계산합니다(특수한 경우). 생성에는 마지막 토큰의 logits만 필요하며, 해당 토큰에 대해서만 계산하면 메모리를 절약할 수 있습니다. 이는 긴 시퀀스나 큰 어휘 크기의 경우 상당한 이점을 제공합니다. `torch.Tensor`인 경우, 시퀀스 길이 차원에서 유지할 인덱스에 해당하는 1차원 텐서여야 합니다. 이는 packed tensor 형식(배치와 시퀀스 길이를 단일 차원으로 사용하는 경우)을 사용할 때 유용합니다.

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

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

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

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

- **shared_kv_states** (`dict`, *선택 사항*) -- 레이어 유형 문자열을 (key_states, value_states) 텐서 튜플로 매핑하는 사전. KV 공유 시 레이어 간 공유된 KV 상태를 전달하는 데 사용됩니다.

## Gemma4UnifiedForCausalLM[[transformers.Gemma4UnifiedForCausalLM]]

#### transformers.Gemma4UnifiedForCausalLM[[transformers.Gemma4UnifiedForCausalLM]]

```python
transformers.Gemma4UnifiedForCausalLM(config: Gemma4UnifiedTextConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified/modeling_gemma4_unified.py#L734)

**매개변수:**

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

언어 모델링 헤드가 포함된 기본 Gemma 4 언어 모델입니다.

이 모델은 [PreTrainedModel](/docs/transformers/v5.23.0/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.Gemma4UnifiedForCausalLM.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, logits_to_keep: typing.Union[int, torch.Tensor] = 0, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified/modeling_gemma4_unified.py#L751)

**매개변수:**

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

attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크입니다. `[0, 1]`에서 선택된 마스크 값: - **마스크되지 않은** 토큰은 1, - **마스크된** 토큰은 0. [attention 마스크란?](../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/v5.23.0/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `past_key_values`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/v5.23.0/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` 인덱스를 관련 벡터로 변환하는 방식에 대해 더 많은 제어가 필요한 경우 유용합니다.

labels (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 인과 언어 모델링 손실을 계산하기 위한 라벨. 인덱스는 `[-100, 0, ..., config.vocab_size]` 범위여야 합니다(`input_ids` docstring 참조). 인덱스가 `-100`로 설정된 토큰은 무시(마스크)되며, 손실은 라벨이 `[0, ..., config.vocab_size]` 범위에 있는 토큰에 대해서만 계산됩니다. 라벨은 **내부적으로 시프트**되어 `labels[..., 1:]`이 `logits[..., :-1, :]`를 예측하는 데 사용됩니다. `input_ids`와 일치하는 시프트되지 않은 라벨을 전달하세요(즉, `labels = input_ids`). 라벨을 전달하기 전에 직접 시프트하지 마세요(**금지**). 라벨이 이미 시프트된 경우(예: 시퀀스 병렬 처리)에는 `shift_labels` 키워드 인수로 전달하면 그대로 사용됩니다. 손실이 계산되려면 `labels`를 전달해야 합니다.

use_cache (`bool`, *선택 사항*) : `True`로 설정하면 `past_key_values` 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(`past_key_values` 참조).

logits_to_keep (`Union[int, torch.Tensor]`, *선택 사항*, 기본값 `0`) : `int`인 경우, 마지막 `logits_to_keep` 토큰에 대한 logits를 계산합니다. `0`인 경우, 모든 `input_ids`에 대한 logits를 계산합니다(특수한 경우). 생성에는 마지막 토큰의 logits만 필요하며, 해당 토큰에 대해서만 계산하면 메모리를 절약할 수 있습니다. 이는 긴 시퀀스나 큰 어휘 크기의 경우 상당한 이점을 제공합니다. `torch.Tensor`인 경우, 시퀀스 길이 차원에서 유지할 인덱스에 해당하는 1차원 텐서여야 합니다. 이는 packed tensor 형식(배치와 시퀀스 길이를 단일 차원으로 사용하는 경우)을 사용할 때 유용합니다.

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

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

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

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

- **loss** (`torch.Tensor`, shape `(1,)`, *선택 사항*, `labels`가 제공될 때 반환됨) -- 언어 모델링 손실(다음 토큰 예측용).
- **logits** (`torch.Tensor`, shape `(batch_size, sequence_length, config.text_config.vocab_size)`) -- 언어 모델링 헤드에 의한 예측 점수(SoftMax 적용 전 각 어휘 토큰의 점수).
- **past_key_values** (`Cache`, *선택 사항*, `use_cache=True`가 전달되었거나 `config.use_cache=True`인 경우 반환됨) -- [Cache](/docs/transformers/v5.23.0/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 가중치입니다.
- **image_hidden_states** (`torch.Tensor`, *선택*) -- 크기가 `(batch_size, num_images, sequence_length, hidden_size)`인 `torch.Tensor`. 비전 인코더가 마지막 hidden state를 투영한 후 생성한 모델의 image_hidden_states.
- **audio_hidden_states** (`torch.Tensor`, *선택*) -- 크기가 `(batch_size, num_images, sequence_length, hidden_size)`인 `torch.Tensor`. 오디오 인코더에 의해 생성된 모델의 audio_hidden_states로, 마지막 hidden state를 투영한 후의 값입니다.
- **shared_kv_states** (`dict`, *선택 사항*) -- 레이어 유형 문자열을 (key_states, value_states) 텐서 튜플로 매핑하는 사전. KV 공유 시 레이어 간 공유된 KV 상태를 전달하는 데 사용됩니다.

예:

```python
>>> from transformers import AutoTokenizer, Gemma4UnifiedForCausalLM

>>> model = Gemma4UnifiedForCausalLM.from_pretrained("google/gemma-4-12B-it")
>>> tokenizer = AutoTokenizer.from_pretrained("google/gemma-4-12B-it")

>>> prompt = "What is your favorite condiment?"
>>> inputs = tokenizer(prompt, return_tensors="pt")

>>> # Generate
>>> generate_ids = model.generate(inputs.input_ids, max_length=30)
>>> tokenizer.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)[0]
"What is your favorite condiment?"
```

## Gemma4UnifiedForConditionalGeneration[[transformers.Gemma4UnifiedForConditionalGeneration]]

#### transformers.Gemma4UnifiedForConditionalGeneration[[transformers.Gemma4UnifiedForConditionalGeneration]]

```python
transformers.Gemma4UnifiedForConditionalGeneration(config: Gemma4UnifiedConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4_unified/modeling_gemma4_unified.py#L1347)

**매개변수:**

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

비전 백본, 오디오 백본, 언어 모델, 언어 모델링 헤드로 구성된 기본 Gemma 4 모델.

이 모델은 [PreTrainedModel](/docs/transformers/v5.23.0/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.Gemma4UnifiedForConditionalGeneration.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, pixel_values: typing.Optional[torch.Tensor] = None, pixel_values_videos: typing.Optional[torch.Tensor] = None, input_features: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, input_features_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, image_position_ids: typing.Optional[torch.LongTensor] = None, video_position_ids: typing.Optional[torch.LongTensor] = None, num_frames_per_video: 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, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, logits_to_keep: typing.Union[int, torch.Tensor] = 0, 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/gemma4_unified/modeling_gemma4_unified.py#L1373)

**매개변수:**

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

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

pixel_values_videos (`torch.Tensor`, shape `(batch_size, num_frames, num_channels, frame_size, frame_size)`, *선택 사항*) : 입력 비디오에 해당하는 텐서입니다. 비디오의 픽셀 값은 [Gemma4UnifiedVideoProcessor](/docs/transformers/v5.23.0/ko/model_doc/gemma4_unified#transformers.Gemma4UnifiedVideoProcessor)를 사용하여 얻을 수 있습니다. 자세한 내용은 [Gemma4UnifiedVideoProcessor.__call__()](/docs/transformers/v5.23.0/ko/model_doc/molmo2#transformers.Molmo2VideoProcessor.__call__)를 참조하세요 ([Gemma4UnifiedProcessor](/docs/transformers/v5.23.0/ko/model_doc/gemma4_unified#transformers.Gemma4UnifiedProcessor)는 비디오 처리에 [Gemma4UnifiedVideoProcessor](/docs/transformers/v5.23.0/ko/model_doc/gemma4_unified#transformers.Gemma4UnifiedVideoProcessor)를 사용합니다).

input_features (`torch.Tensor`, shape `(batch_size, sequence_length, feature_dim)`, *선택 사항*) : 입력 오디오 특징에 해당하는 텐서입니다. 오디오 특징은 [Gemma4UnifiedAudioFeatureExtractor](/docs/transformers/v5.23.0/ko/model_doc/gemma4_unified#transformers.Gemma4UnifiedAudioFeatureExtractor)를 사용하여 얻을 수 있습니다. 자세한 내용은 [Gemma4UnifiedAudioFeatureExtractor.__call__()](/docs/transformers/v5.23.0/ko/model_doc/gemma4_unified#transformers.Gemma4UnifiedAudioFeatureExtractor.__call__)를 참조하세요 ([Gemma4UnifiedProcessor](/docs/transformers/v5.23.0/ko/model_doc/gemma4_unified#transformers.Gemma4UnifiedProcessor)는 오디오 처리에 [Gemma4UnifiedAudioFeatureExtractor](/docs/transformers/v5.23.0/ko/model_doc/gemma4_unified#transformers.Gemma4UnifiedAudioFeatureExtractor)를 사용합니다).

attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크입니다. `[0, 1]`에서 선택된 마스크 값: - **마스크되지 않은** 토큰은 1, - **마스크된** 토큰은 0. [attention 마스크란?](../glossary#attention-mask)

input_features_mask (`torch.Tensor`, shape `(num_images, seq_length)`) : 입력 오디오에 대한 attention mask입니다.

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

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

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

num_frames_per_video (`torch.LongTensor`, shape `(num_videos,)`, *선택 사항*) : 각 비디오에 속하는 프레임 수. 모든 비디오의 프레임이 단일 축을 따라 연결되므로 `pixel_values_videos`가 전달될 때 필수입니다.

past_key_values (`~cache_utils.Cache`, *선택*) : 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key 및 value)입니다. 일반적으로 `use_cache=True` 또는 `config.use_cache=True`일 때 모델이 디코딩의 이전 단계에서 반환한 `past_key_values`로 구성됩니다. 입력으로 [Cache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `past_key_values`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/v5.23.0/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/v5.23.0/ko/model_doc/auto#transformers.AutoProcessor)를 사용하여 얻을 수 있습니다. 자세한 내용은 [ProcessorMixin.__call__()](/docs/transformers/v5.23.0/ko/main_classes/processors#transformers.ProcessorMixin.__call__)를 참조하세요.

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

labels (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : masked language modeling loss를 계산하기 위한 라벨. 인덱스는 `[0, ..., config.vocab_size]` 범위 내이거나 -100이어야 합니다(`input_ids` docstring 참조). 인덱스가 `-100`으로 설정된 토큰은 무시(마스크)되며, loss는 `[0, ..., config.vocab_size]` 범위의 라벨을 가진 토큰에 대해서만 계산됩니다.

use_cache (`bool`, *선택 사항*) : `True`로 설정하면 `past_key_values` 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(`past_key_values` 참조).

logits_to_keep (`Union[int, torch.Tensor]`, *선택 사항*, 기본값 `0`) : `int`인 경우, 마지막 `logits_to_keep` 토큰에 대한 logits를 계산합니다. `0`인 경우, 모든 `input_ids`에 대한 logits를 계산합니다(특수한 경우). 생성에는 마지막 토큰의 logits만 필요하며, 해당 토큰에 대해서만 계산하면 메모리를 절약할 수 있습니다. 이는 긴 시퀀스나 큰 어휘 크기의 경우 상당한 이점을 제공합니다. `torch.Tensor`인 경우, 시퀀스 길이 차원에서 유지할 인덱스에 해당하는 1차원 텐서여야 합니다. 이는 packed tensor 형식(배치와 시퀀스 길이를 단일 차원으로 사용하는 경우)을 사용할 때 유용합니다.

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)`, *선택 사항*)입니다. 이는 인코더의 멀티모달 특징을 텍스트 임베딩으로 병합한 시퀀스입니다.

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

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

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

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

- **loss** (`torch.Tensor`, shape `(1,)`, *선택 사항*, `labels`가 제공될 때 반환됨) -- 언어 모델링 손실(다음 토큰 예측용).
- **logits** (`torch.Tensor`, shape `(batch_size, sequence_length, config.text_config.vocab_size)`) -- 언어 모델링 헤드에 의한 예측 점수(SoftMax 적용 전 각 어휘 토큰의 점수).
- **past_key_values** (`Cache`, *선택 사항*, `use_cache=True`가 전달되었거나 `config.use_cache=True`인 경우 반환됨) -- [Cache](/docs/transformers/v5.23.0/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 가중치입니다.
- **image_hidden_states** (`torch.Tensor`, *선택*) -- 크기가 `(batch_size, num_images, sequence_length, hidden_size)`인 `torch.Tensor`. 비전 인코더가 마지막 hidden state를 투영한 후 생성한 모델의 image_hidden_states.
- **audio_hidden_states** (`torch.Tensor`, *선택*) -- 크기가 `(batch_size, num_images, sequence_length, hidden_size)`인 `torch.Tensor`. 오디오 인코더에 의해 생성된 모델의 audio_hidden_states로, 마지막 hidden state를 투영한 후의 값입니다.
- **shared_kv_states** (`dict`, *선택 사항*) -- 레이어 유형 문자열을 (key_states, value_states) 텐서 튜플로 매핑하는 사전. KV 공유 시 레이어 간 공유된 KV 상태를 전달하는 데 사용됩니다.

예:

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

>>> model = Gemma4UnifiedForConditionalGeneration.from_pretrained("google/gemma-4-12B-it")
>>> processor = AutoProcessor.from_pretrained("google/gemma-4-12B-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]
```

