# Gemma4

## 개요

Gemma 4는 사전 학습 및 지시 튜닝 변형이 제공되는 멀티모달 모델로, E2B, E4B, 31B, 26B-A4B(MoE) 파라미터 크기로 사용할 수 있습니다. Gemma 4 모델은 다음과 같은 기능을 제공합니다:
- Reasoning: 해당 계열의 모든 모델은 설정 가능한 사고(thinking) 모드를 갖춘 고도의 추론 능력(reasoner)을 지닌 모델로 설계되었습니다.
- Extended Multimodalities: 가변적인 종횡비와 해상도를 지원하는 텍스트, 이미지(모든 모델), 비디오, 오디오를 처리합니다(E2B 및 E4B 모델에 기본적으로 내장됨).
- 컨텍스트 윈도우 확장: 소형 모델은 128K 컨텍스트 윈도우를 제공하며, 다른 모델은 256K를 지원합니다.
- 향상된 코딩 및 에이전트 기능: 내장된 function-calling 지원과 함께 코딩 벤치마크에서 눈에 띄는 성능 향상을 달성하여, 고도로 자율적인 에이전트를 구동합니다.
- 네이티브 System Prompt 지원: Gemma 4는 system role에 대한 내장 지원을 도입하여 더 구조적이고 제어 가능한 대화를 가능하게 합니다.

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

### Gemma4 비전 모델

이전 Gemma 비전 릴리스와의 핵심 차이는 **고정된 예산의 토큰 수**를 사용하여 **크기가 다른 이미지**를 처리하는 새로운 설계입니다. 224×224와 같은 고정된 정사각형으로 모든 이미지를 압축하는 많은 모델과 달리, Gemma 4는 이미지의 자연스러운 종횡비를 유지하면서 적절한 크기로 조정합니다. 다음 제약 사항을 준수해야 합니다:
- …
- 높이와 너비 모두 **48**(= 패치 크기 16 × 풀링 커널 3)로 나누어떨어져야 합니다

> [!IMPORTANT]
> Gemma 4는 많은 다른 비전 모델에서 사용하는 표준 ImageNet 평균/표준편차 정규화를 **적용하지 않습니다**. 모델 자체의 패치 임베딩 레이어가 내부적으로 최종 스케일링을 처리합니다(값을 [-1, 1] 범위로 이동).

이미지 프로세서가 생성할 수 있는 "소프트 토큰"(비전 토큰이라고도 함)의 수는 설정할 수 있습니다. 지원되는 옵션은 아래에 나와 있으며 기본값은 이미지당 **280개의 소프트 토큰**입니다.

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

이미지의 각 패치에 대한 위치 정보를 인코딩하기 위해 Gemma 4는 학습된 2D 위치 임베딩 테이블을 사용합니다. 위치 테이블은 축당 최대 10,240개의 위치를 저장하여 모델이 매우 큰 이미지를 처리할 수 있도록 합니다. 각 위치는 패치 임베딩과 동일한 차원을 가진 학습된 벡터입니다. Gemma 4가 사용하는 2D RoPE는 주의 헤드 차원의 절반을 x축에 대해, 나머지 절반을 y축에 대해 독립적으로 회전시킵니다. 이를 통해 모델은 "위", "아래", "왼쪽", "오른쪽"과 같은 공간적 관계를 이해할 수 있습니다.

### 레이어별 임베딩(PLE)

Gemma 4는 입력에서 단일 공유 임베딩에만 의존하지 않고, 각 디코더 레이어에 보조 잔차 신호를 공급하는 Per-Layer Embeddings(PLE) 시스템을 도입했습니다.

PLE는 두 가지 구성 요소를 합산한 뒤 `1/√2`로 스케일링하여 각 decoder layer에 전달합니다:

1. Token-identity(`get_per_layer_inputs`): `embed_tokens_per_layer`에서 `input_ids`를 조회합니다. `embed_tokens_per_layer`는 `Gemma4TextScaledWordEmbedding`이며, `√(hidden_size_per_layer_input)`을 곱합니다. 패킹된 출력은 `[batch, seq, num_hidden_layers * hidden_size_per_layer_input]`에서 `[batch, seq, num_hidden_layers, hidden_size_per_layer_input]`으로 리사이즈됩니다.
2. 컨텍스트 인식(`project_per_layer_inputs`): `inputs_embeds`를 `per_layer_model_projection`(Linear 레이어)를 통해 투영한 뒤 `1/√(hidden_size)`로 스케일링하고, `[batch, seq, num_layers, ple_dim]`으로 리사이즈한 다음 `per_layer_projection_norm`(RMSNorm)로 정규화합니다.

두 구성 요소가 모두 사용 가능한 경우, 최종 레이어별 입력은 `(token_identity + context_aware) * (1/√2)`입니다. `input_ids`가 사용 불가능한 멀티모달 입력의 경우, 컨텍스트 인식 투사만 사용됩니다.

## 사용 예시

아래 예제는 [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

pipeline = pipeline(
    task="image-text-to-text",
    model="google/gemma-4-E2B-it",
)
pipeline(
    images="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg",
    text="<|image|>\n\nWhat is shown in this image?"
)
```

```python
from transformers import AutoModelForImageTextToText, AutoProcessor

model = AutoModelForImageTextToText.from_pretrained(
    "google/gemma-4-E2B-it",
    device_map="auto",
    attn_implementation="sdpa"
)
processor = AutoProcessor.from_pretrained(
    "google/gemma-4-E2B-it",
    padding_side="left"
)

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

### Function calling

```python
from transformers import AutoModelForCausalLM, AutoProcessor

WEATHER_TOOL = {
    "type": "function",
    "function": {
        "name": "get_n_day_weather_forecast",
        "description": "Get an N-day weather forecast",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                },
                "format": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "The temperature unit to use",
                },
                "num_days": {
                    "type": "integer",
                    "description": "The number of days to forecast",
                },
            },
            "required": ["location", "format", "num_days"],
        },
    },
}

messages = [
    {
        "role": "user",
        "content": "What's the weather like the next 3 days in San Francisco, CA (using F)?",
    },
]

model = AutoModelForCausalLM.from_pretrained(
    "google/gemma-4-E2B-it",
    device_map="auto",
    attn_implementation="sdpa"
)
processor = AutoProcessor.from_pretrained(
    "google/gemma-4-E2B-it",
    padding_side="left"
)

text = processor.apply_chat_template(
    messages,
    tools=[WEATHER_TOOL],
    tokenize=False,
    add_generation_prompt=True,
)

inputs = processor(text=text, return_tensors="pt").to(model.device)
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))
```

### Audio (E2B 및 E4B 전용)

```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/dude_where_is_my_car.wav",
            },
        ],
    }
]

model = AutoModelForMultimodalLM.from_pretrained(
    "google/gemma-4-E2B-it",
    device_map="auto",
    attn_implementation="sdpa"
)
processor = AutoProcessor.from_pretrained(
    "google/gemma-4-E2B-it",
    padding_side="left"
)

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

## Gemma4AudioConfig[[transformers.Gemma4AudioConfig]]

#### transformers.Gemma4AudioConfig[[transformers.Gemma4AudioConfig]]

```python
transformers.Gemma4AudioConfig(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, hidden_size: int = 1024, num_hidden_layers: int = 12, num_attention_heads: int = 8, hidden_act: str = 'silu', subsampling_conv_channels: list[int] | tuple[int, int] = (128, 32), conv_kernel_size: int = 5, residual_weight: float = 0.5, attention_chunk_size: int = 12, attention_context_left: int = 13, attention_context_right: int = 0, attention_logit_cap: float = 50.0, attention_invalid_logits_value: float = -1000000000.0, use_clipped_linears: bool = True, rms_norm_eps: float = 1e-06, gradient_clipping: float = 10000000000.0, output_proj_dims: int = 1536, initializer_range: float = 0.02)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4/configuration_gemma4.py#L29)

**매개변수:**

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

num_hidden_layers (`int`, *선택 사항*, 기본값 `12`) : Transformer decoder의 숨겨진 레이어 수입니다.

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

hidden_act (`str`, *선택 사항*, 기본값 `silu`) : 디코더에서 사용되는 비선형 활성화 함수(함수 또는 문자열). 예를 들어, `"gelu"`, `"relu"`, `"silu"` 등이 있습니다.

subsampling_conv_channels (`list[int]`, 기본값 `[128, 32]`) : Sub-sample Convolution Projection의 컨볼루션 레이어에 사용할 채널 크기입니다.

conv_kernel_size (`int`, *선택 사항*, 기본값 `5`) : 컨볼루션 커널의 크기입니다.

residual_weight (`float`, 기본값 `0.5`) : feedforward에서 residual과 결합하기 전에 hidden_states에 적용되는 스케일링입니다.

attention_chunk_size (`int`, 기본값 `12`) : attention 처리를 위한 서브 시퀀스 크기입니다.

attention_context_left (`int`, 기본값 `13`) : attention chunk의 왼쪽 컨텍스트 크기입니다.

attention_context_right (`int`, 기본값 `0`) : attention chunk의 오른쪽 컨텍스트 크기입니다.

attention_logit_cap (`float`, 기본값 `50.0`) : attention weights에 적용되는 상한값입니다.

attention_invalid_logits_value (`float`, 기본값 `1e-9`) : attention에서 잘못된 logits에 사용할 값.

use_clipped_linears (`bool`, 기본값은 `True`) : true인 경우, 모델 체크포인트에서 경계를 가져와 Linear 레이어에 클리핑을 적용합니다.

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

gradient_clipping (`float`, 기본값 `1e10`) : 극도로 큰 그래디언트 값을 안정화하기 위해 사용되는 클리핑 값.

output_proj_dims (`int`, 기본값 `1536`) : `hidden_size`에서 모델 출력으로의 최종 선형 투영 차원.

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

이것은 Gemma4Model의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Gemma4 모델을 인스턴스화하고 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 [google/gemma-4-e2b-it](https://huggingface.co/google/gemma-4-e2b-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)의 문서를 참고하세요.

## Gemma4VisionConfig[[transformers.Gemma4VisionConfig]]

#### transformers.Gemma4VisionConfig[[transformers.Gemma4VisionConfig]]

```python
transformers.Gemma4VisionConfig(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, hidden_size: int = 768, intermediate_size: int = 3072, num_hidden_layers: int = 16, num_attention_heads: int = 12, num_key_value_heads: int = 12, head_dim: int = 64, hidden_activation: str = 'gelu_pytorch_tanh', rms_norm_eps: float = 1e-06, max_position_embeddings: int = 131072, attention_bias: bool | None = False, attention_dropout: float | None = 0.0, rope_parameters: dict | None = None, pooling_kernel_size: int = 3, patch_size: int = 16, position_embedding_size: int = 10240, use_clipped_linears: bool = False, standardize: bool = False, initializer_range: float = 0.02)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4/configuration_gemma4.py#L270)

**매개변수:**

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

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

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

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

num_key_value_heads (`int`, *선택 사항*, 기본값 `12`) : 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`, *선택 사항*, 기본값 `64`) : 어텐션 헤드 차원입니다. None인 경우 hidden_size // num_attention_heads 값이 기본값으로 사용됩니다.

hidden_activation (`str`, *선택 사항*, 기본값 `gelu_pytorch_tanh`) : 디코더의 비선형 활성화 함수(함수 또는 문자열). 예를 들어, `"gelu"`, `"relu"`, `"silu"` 등.

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

max_position_embeddings (`int`, *선택 사항*, 기본값 `131072`) : 이 모델이 사용될 수 있는 최대 시퀀스 길이입니다.

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

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

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

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

patch_size (`int`, *선택 사항*, 기본값 `16`) : 각 패치의 크기(해상도).

position_embedding_size (`int`, 기본값 10240) : 비전 인코더의 최대 위치 임베딩 수입니다. 패치 임베더가 사용하는 학습된 2D 위치 임베딩 테이블의 크기를 제어합니다.

use_clipped_linears (`bool`, 기본값 `False`) : 가중치 클리핑(linear layer)을 사용할지 여부입니다. 활성화되면, 선형 레이어의 가중치가 순전파(forward pass) 중에 고정된 범위로 클램프되어 수치적 안정성이 향상됩니다.

standardize (`bool`, 기본값은 `False`) : true인 경우, pooler에서 반환된 soft token에 bias와 scale을 적용합니다.

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

이것은 Gemma4Model의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Gemma4 모델을 인스턴스화하고 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 [google/gemma-4-e2b-it](https://huggingface.co/google/gemma-4-e2b-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)의 문서를 참고하세요.

## Gemma4TextConfig[[transformers.Gemma4TextConfig]]

#### transformers.Gemma4TextConfig[[transformers.Gemma4TextConfig]]

```python
transformers.Gemma4TextConfig(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, 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 = 512, layer_types: list[str] | None = None, final_logit_softcapping: float | None = None, use_bidirectional_attention: typing.Optional[typing.Literal['all', 'vision']] = None, vocab_size_per_layer_input: int = 262144, hidden_size_per_layer_input: int = 256, attention_k_eq_v: bool = False, num_kv_shared_layers: int = 0, enable_moe_block: bool = False, use_double_wide_mlp: bool = False, num_experts: int | None = None, top_k_experts: int | None = None, moe_intermediate_size: int | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4/configuration_gemma4.py#L87)

**매개변수:**

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 값입니다.

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`, *선택 사항*, 기본값 `512`) : 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"`로 설정하면 모든 토큰이 양방향 어텐션을 사용합니다.

vocab_size_per_layer_input (`int`, 기본값 262144) : 레이어별 입력 임베딩(PLE)의 어휘 크기. 각 디코더 레이어에서 더 작은 임베딩이 추가되는 레이어별 잔류 스트림을 사용하는 모델에서 사용됩니다.

hidden_size_per_layer_input (`int`, 기본값 256) : PLE 시스템의 레이어별 숨김 차원입니다. 모든 레이어가 단일 테이블에 패킹되므로 실제 임베딩 가중치의 형태는 `[vocab_size_per_layer_input, num_hidden_layers * hidden_size_per_layer_input]`입니다. 전체 PLE 파이프라인에 대한 설명은 [Gemma4](https://huggingface.co/docs/transformers/main/en/model_doc/gemma4#per-layer-embeddings-ple) 문서를 참조하세요.

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

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

enable_moe_block (`bool`, 기본값 `False`) : 디코더 레이어에서 Mixture-of-Experts(MoE) 블록을 활성화할지 여부입니다. `True`인 경우, 해당 레이어는 희소 MoE 피드포워드 네트워크를 사용합니다.

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

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

top_k_experts (`int`, *선택 사항*) : MoE 레이어에서 토큰당 활성화되는 전문가의 수. `enable_moe_block=True`일 때만 사용됩니다.

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

이것은 Gemma4Model의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Gemma4 모델을 인스턴스화하고 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 [google/gemma-4-e2b-it](https://huggingface.co/google/gemma-4-e2b-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)의 문서를 참고하세요.

## Gemma4Config[[transformers.Gemma4Config]]

#### transformers.Gemma4Config[[transformers.Gemma4Config]]

```python
transformers.Gemma4Config(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.configuration_gemma4.Gemma4TextConfig | dict[str, typing.Any] | None = None, vision_config: transformers.models.gemma4.configuration_gemma4.Gemma4VisionConfig | dict[str, typing.Any] | None = None, audio_config: transformers.models.gemma4.configuration_gemma4.Gemma4AudioConfig | 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/configuration_gemma4.py#L322)

**매개변수:**

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

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

audio_config (`Union[~models.gemma4.configuration_gemma4.Gemma4AudioConfig, 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` 매핑에 따라 가중치 임베딩을 묶을지 여부.

이것은 Gemma4Model의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Gemma4 모델을 인스턴스화하고 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 [google/gemma-4-e2b-it](https://huggingface.co/google/gemma-4-e2b-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 (
>>>     Gemma4AudioConfig,
>>>     Gemma4Config,
>>>     Gemma4ForConditionalGeneration,
>>>     Gemma4TextConfig,
>>>     Gemma4VisionConfig,
>>> )

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

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

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

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

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

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

## Gemma4AudioFeatureExtractor[[transformers.Gemma4AudioFeatureExtractor]]

#### transformers.Gemma4AudioFeatureExtractor[[transformers.Gemma4AudioFeatureExtractor]]

```python
transformers.Gemma4AudioFeatureExtractor(feature_size: int = 128, sampling_rate: int = 16000, padding_value: float = 0.0, return_attention_mask: bool = True, frame_length_ms: float = 20.0, hop_length_ms: float = 10.0, min_frequency: float = 0.0, max_frequency: float = 8000.0, preemphasis: float = 0.0, preemphasis_htk_flavor: bool = True, fft_overdrive: bool = False, dither: float = 0.0, input_scale_factor: float = 1.0, mel_floor: float = 0.001, per_bin_mean: collections.abc.Sequence[float] | None = None, per_bin_stddev: collections.abc.Sequence[float] | None = None, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4/feature_extraction_gemma4.py#L49)

**매개변수:**

feature_size (`int`, *선택 사항*, 기본값 128) : 추출된 특징의 차원입니다.

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

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

return_attention_mask (`bool`, *선택 사항*, 기본값 `True`) : 생성된 MEL 스펙트로그램의 어텐션 마스크를 반환할지 여부입니다.

frame_length_ms (`float`, *선택 사항*, 기본값 20.0) : 프레임의 길이(밀리초).

hop_length_ms (`float`, *선택 사항*, 기본값 10.0) : Mel Frequency 계수를 얻기 위해 사용되는 STFT의 겹치는 윈도우 길이입니다.

min_frequency (`float`, *선택 사항*, 기본값 0.0) : Mel 필터 뱅크의 최소 주파수(Hz).

max_frequency (`float`, *선택 사항*, 기본값 8000.0) : Mel 필터 뱅크의 최대 주파수(Hz).

preemphasis (`float`, *선택 사항*, 기본값 0.0) : preemphasis 계수입니다.

preemphasis_htk_flavor (`bool`, *선택 사항*, 기본값 `True`) : HTK 스타일 사전 강조를 사용할지 여부.

fft_overdrive (`bool`, *선택 사항*, 기본값 `False`) : FFT 오버드라이브를 사용할지 여부.

dither (`float`, *선택 사항*, 기본값 0.0) : 디더링을 추가합니다. 즉, 각 프레임에 작은 가우시안 노이즈를 추가합니다. 예를 들어, 0.0001을 사용하면 0.0을 중심으로 표준편차가 0.0001인 정규 분포로 디더링을 추가합니다(원시 음성(raw_speech)의 범위가 [-1,+1]이라고 가정). 값 0.0은 디더링을 하지 않음을 의미합니다. 디더링은 `spectrogram(mel_floor=...)`와 유사한 효과를 냅니다. 신호에 VAD 컷오프가 존재하는 경우, 하드 제로(hard-zero) 구간이 있는 신호의 높은 log_mel_fbank 값을 줄여줍니다.

input_scale_factor (`float`, *선택 사항*, 기본값 1.0) : 입력 웨이브폼에 적용되는 스케일링 계수.

mel_floor (`float`, *선택 사항*, 기본값 0.001) : log(0)를 피하기 위한 Mel 스펙트로그램의 최소값.

per_bin_mean (`Optional[Sequence[float]]`, *선택 사항*) : 빈별 정규화를 위한 평균 값.

per_bin_stddev (`Optional[Sequence[float]]`, *선택 사항*) : 빈별 정규화를 위한 표준 편차 값.

음성 특징 추출기 Universal Speech Models https://huggingface.co/papers/2303.01037.

#### __call__[[transformers.Gemma4AudioFeatureExtractor.__call__]]

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4/feature_extraction_gemma4.py#L226)

**매개변수:**

raw_speech : MEL 스펙트로그램을 생성할 오디오입니다.

padding (`Union[bool, str, PaddingStrategy]`, *선택 사항*, 기본값 `"longest"`) : 길이가 다른 오디오 배치에 사용할 패딩 전략입니다.

max_length (`int`, *선택 사항*, 기본값 480000) : 지정된 경우, 허용되는 오디오의 최대 길이를 정의합니다. 이 길이보다 긴 오디오는 `truncation=True`인 경우 잘립니다.

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

pad_to_multiple_of (`int`, *선택 사항*, 기본값 128) : 패딩 시 이 값의 배수로 패딩합니다. 기본값은 최적의 TPU 지원을 위해 정의됩니다.

return_tensors (`Union[str, TensorType]`, *선택 사항*, 기본값 `None`) : 반환할 텐서의 유형(예: NumPy 또는 Torch).

return_attention_mask (`bool`, *선택 사항*, 기본값 `True`) : 생성된 MEL 스펙트로그램의 어텐션 마스크를 반환할지 여부입니다.

제공된 원시 음성에서 MEL 스펙트로그램 배치(batch)를 생성합니다.

이 구현은 내장된 `transformers.audio_utils.spectrogram()` 함수와 다른 윈도우링 및 사전 강조 알고리즘을 사용하므로 _다른_ 출력이 생성됩니다. 사전 학습된 모델을 사용하는 경우 특히 오디오 피처 추출기를 선택할 때 이 점을 신중하게 고려하세요.

## Gemma4ImageProcessorPil[[transformers.Gemma4ImageProcessorPil]]

#### transformers.Gemma4ImageProcessorPil[[transformers.Gemma4ImageProcessorPil]]

```python
transformers.Gemma4ImageProcessorPil(**kwargs: *<class 'transformers.models.gemma4.image_processing_pil_gemma4.Gemma4ImageProcessorKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4/image_processing_pil_gemma4.py#L137)

**매개변수:**

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*) : 모델의 최대 입력 차원을 설명합니다.

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*, *선택 사항*) : 픽셀 단위 이미지 패치의 크기.

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

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

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

#### preprocess[[transformers.Gemma4ImageProcessorPil.preprocess]]

```python
preprocess(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']], **kwargs: *<class 'transformers.models.gemma4.image_processing_pil_gemma4.Gemma4ImageProcessorKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4/image_processing_pil_gemma4.py#L167)

**매개변수:**

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`로 설정하세요.

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인 경우 리사이즈 시 정사각형 이미지로 기본 설정할지 여부.

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

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_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*, *선택 사항*) : 픽셀 단위 이미지 패치의 크기.

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을 지정할 수 있습니다.

## Gemma4ImageProcessor[[transformers.Gemma4ImageProcessor]]

#### transformers.Gemma4ImageProcessor[[transformers.Gemma4ImageProcessor]]

```python
transformers.Gemma4ImageProcessor(**kwargs: *<class 'transformers.models.gemma4.image_processing_gemma4.Gemma4ImageProcessorKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4/image_processing_gemma4.py#L136)

**매개변수:**

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*, *선택 사항*) : 픽셀 단위 이미지 패치의 크기.

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

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

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

#### preprocess[[transformers.Gemma4ImageProcessor.preprocess]]

```python
preprocess(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']], **kwargs: *<class 'transformers.models.gemma4.image_processing_gemma4.Gemma4ImageProcessorKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4/image_processing_gemma4.py#L193)

## Gemma4VideoProcessor[[transformers.Gemma4VideoProcessor]]

#### transformers.Gemma4VideoProcessor[[transformers.Gemma4VideoProcessor]]

```python
transformers.Gemma4VideoProcessor(**kwargs: *<class 'transformers.models.gemma4.video_processing_gemma4.Gemma4VideoProcessorKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4/video_processing_gemma4.py#L155)

**매개변수:**

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 클래스를 참조하세요.

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

#### preprocess[[transformers.Gemma4VideoProcessor.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.video_processing_gemma4.Gemma4VideoProcessorKwargs'>)
```

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

**매개변수:**

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을 지정할 수 있습니다.

## Gemma4Processor[[transformers.Gemma4Processor]]

#### transformers.Gemma4Processor[[transformers.Gemma4Processor]]

```python
transformers.Gemma4Processor(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/processing_gemma4.py#L87)

**매개변수:**

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

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

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

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

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를 단일 프로세서로 감싸는 Gemma4Processor를 생성합니다.

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

#### __call__[[transformers.Gemma4Processor.__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 클래스를 참조하세요.

## Gemma4PreTrainedModel[[transformers.Gemma4PreTrainedModel]]

#### transformers.Gemma4PreTrainedModel[[transformers.Gemma4PreTrainedModel]]

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4/modeling_gemma4.py#L1443)

**매개변수:**

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.Gemma4PreTrainedModel.forward]]

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

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

## Gemma4AudioModel[[transformers.Gemma4AudioModel]]

#### transformers.Gemma4AudioModel[[transformers.Gemma4AudioModel]]

```python
transformers.Gemma4AudioModel(config: Gemma4AudioConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4/modeling_gemma4.py#L1963)

[Universal Speech Model](https://huggingface.co/papers/2303.01037) 아키텍처를 기반으로 한 오디오 인코더입니다.

#### forward[[transformers.Gemma4AudioModel.forward]]

```python
forward(input_features: Tensor, attention_mask: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4/modeling_gemma4.py#L2020)

**매개변수:**

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

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

**반환값:**

`tuple[torch.Tensor, torch.BoolTensor]`

오디오 특징을 소프트 토큰으로 인코딩합니다.

## Gemma4VisionModel[[transformers.Gemma4VisionModel]]

#### transformers.Gemma4VisionModel[[transformers.Gemma4VisionModel]]

```python
transformers.Gemma4VisionModel(config: Gemma4VisionConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4/modeling_gemma4.py#L2055)

Gemma 4 Vision Encoder입니다.

#### forward[[transformers.Gemma4VisionModel.forward]]

```python
forward(pixel_values: Tensor, pixel_position_ids: LongTensor, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4/modeling_gemma4.py#L2076)

**매개변수:**

pixel_values (`torch.Tensor` 또는 `list[torch.Tensor]`) : 인코딩할 이미지. 단일 `[batch, channels, height, width]` 텐서(모든 이미지가 동일한 크기) 또는 `[1, channels, height, width]` 텐서의 목록(크기가 서로 다름).

pixel_position_ids (`torch.LongTensor`, shape `(batch_size, max_patches, 2)`) : 이미지에서 패치의 (x, y) 좌표로 표현된 위치입니다. 패딩 패치는 (-1, -1)로 표시됩니다.

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

구성([Gemma4Config](/docs/transformers/v5.23.0/ko/model_doc/gemma4#transformers.Gemma4Config))과 입력에 따라 다양한 요소를 포함하는 [BaseModelOutputWithPast](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되거나 `config.return_dict=False`인 경우).

패치에서 이미지 픽셀을 소프트 토큰으로 인코딩합니다.

- **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, 그리고 `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 가중치입니다.

## Gemma4TextModel[[transformers.Gemma4TextModel]]

#### transformers.Gemma4TextModel[[transformers.Gemma4TextModel]]

```python
transformers.Gemma4TextModel(config: Gemma4TextConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4/modeling_gemma4.py#L1544)

**매개변수:**

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

language modeling head가 없는 기본 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.Gemma4TextModel.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, per_layer_inputs: 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/modeling_gemma4.py#L1602)

**매개변수:**

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` 인덱스를 관련 벡터로 변환하는 방식에 대해 더 많은 제어가 필요한 경우 유용합니다.

per_layer_inputs (`torch.Tensor`, *선택 사항*) : `(batch_size, sequence_length, num_hidden_layers, hidden_size_per_layer_input)` 형태의 사전 계산된 레이어별 입력 텍스트 임베딩입니다. 이 값이 제공되면 텍스트 모델에서 `input_ids`를 `get_per_layer_inputs()`를 통해 계산하는 대신 이 값이 직접 사용됩니다. `input_ids` 대신 `inputs_embeds`로 `forward`를 호출하는 경우, 이 값들을 사전 계산하여 `inputs_embeds`와 함께 전달하는 것이 좋습니다. 그렇지 않으면 메인 임베딩을 역산해야 하므로 비용이 많이 듭니다.

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 형식(배치와 시퀀스 길이를 단일 차원으로 사용하는 경우)을 사용할 때 유용합니다.

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

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

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

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

- **shared_kv_states** (`KVSharingDict`, *선택 사항*) -- 레이어 유형 문자열을 (key_states, value_states) 텐서 튜플로 매핑하는 dict 유사 컨테이너입니다. KV 공유 과정에서 레이어 간에 공유된 KV 상태를 전달하는 데 사용됩니다.
- **router_logits** (`tuple(torch.Tensor)`, *선택 사항*, `output_router_logits=True`가 전달될 때 반환됨) -- 각 MoE 레이어에 하나씩 포함된 `torch.Tensor`의 튜플로, 모양은 `(batch_size * sequence_length, num_experts)`입니다.

## Gemma4ForCausalLM[[transformers.Gemma4ForCausalLM]]

#### transformers.Gemma4ForCausalLM[[transformers.Gemma4ForCausalLM]]

```python
transformers.Gemma4ForCausalLM(config: Gemma4TextConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4/modeling_gemma4.py#L1853)

**매개변수:**

config ([Gemma4TextConfig](/docs/transformers/v5.23.0/ko/model_doc/gemma4#transformers.Gemma4TextConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [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.Gemma4ForCausalLM.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, per_layer_inputs: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4/modeling_gemma4.py#L1870)

**매개변수:**

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 형식(배치와 시퀀스 길이를 단일 차원으로 사용하는 경우)을 사용할 때 유용합니다.

per_layer_inputs (`torch.Tensor`, *선택 사항*) : `(batch_size, sequence_length, num_hidden_layers, hidden_size_per_layer_input)` 형태의 사전 계산된 레이어별 입력 텍스트 임베딩입니다. 이 값이 제공되면 텍스트 모델에서 `input_ids`를 `get_per_layer_inputs()`를 통해 계산하는 대신 이 값이 직접 사용됩니다. `input_ids` 대신 `inputs_embeds`로 `forward`를 호출하는 경우, 이 값들을 사전 계산하여 `inputs_embeds`와 함께 전달하는 것이 좋습니다. 그렇지 않으면 메인 임베딩을 역산해야 하므로 비용이 많이 듭니다.

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

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

[Gemma4ForCausalLM](/docs/transformers/v5.23.0/ko/model_doc/gemma4#transformers.Gemma4ForCausalLM)의 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** (`KVSharingDict`, *선택 사항*) -- 레이어 유형 문자열을 (key_states, value_states) 텐서 튜플로 매핑하는 dict 유사 컨테이너입니다. KV 공유 과정에서 레이어 간에 공유된 KV 상태를 전달하는 데 사용됩니다.
- **router_logits** (`tuple(torch.Tensor)`, *선택 사항*, `output_router_logits=True`가 전달될 때 반환됨) -- 각 MoE 레이어에 하나씩 포함된 `torch.Tensor`의 튜플로, 모양은 `(batch_size * sequence_length, num_experts)`입니다.

예:

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

>>> model = Gemma4ForCausalLM.from_pretrained("google/gemma-4-E2B-it")
>>> tokenizer = AutoTokenizer.from_pretrained("google/gemma-4-E2B-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?"
```

## Gemma4Model[[transformers.Gemma4Model]]

#### transformers.Gemma4Model[[transformers.Gemma4Model]]

```python
transformers.Gemma4Model(config: Gemma4Config)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4/modeling_gemma4.py#L2231)

**매개변수:**

config ([Gemma4Config](/docs/transformers/v5.23.0/ko/model_doc/gemma4#transformers.Gemma4Config)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [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.Gemma4Model.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, per_layer_inputs: typing.Optional[torch.Tensor] = 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/modeling_gemma4.py#L2326)

**매개변수:**

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)`, *선택 사항*) : 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 [Gemma4ImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/gemma4#transformers.Gemma4ImageProcessor)를 사용하여 얻을 수 있습니다. 자세한 내용은 [Gemma4ImageProcessor.__call__()](/docs/transformers/v5.23.0/ko/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)를 참조하세요 ([Gemma4Processor](/docs/transformers/v5.23.0/ko/model_doc/gemma4#transformers.Gemma4Processor)는 이미지 처리에 [Gemma4ImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/gemma4#transformers.Gemma4ImageProcessor)를 사용합니다).

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

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

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`가 전달될 때 필수입니다.

per_layer_inputs (`torch.Tensor`, *선택 사항*) : `(batch_size, sequence_length, num_hidden_layers, hidden_size_per_layer_input)` 형태의 사전 계산된 레이어별 입력 텍스트 임베딩입니다. 이 값이 제공되면 텍스트 모델에서 `input_ids`를 `get_per_layer_inputs()`를 통해 계산하는 대신 이 값이 직접 사용됩니다. `input_ids` 대신 `inputs_embeds`로 `forward`를 호출하는 경우, 이 값들을 사전 계산하여 `inputs_embeds`와 함께 전달하는 것이 좋습니다. 그렇지 않으면 메인 임베딩을 역산해야 하므로 비용이 많이 듭니다.

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

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

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

[Gemma4Model](/docs/transformers/v5.23.0/ko/model_doc/gemma4#transformers.Gemma4Model)의 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** (`KVSharingDict`, *선택 사항*) -- 레이어 유형 문자열을 (key_states, value_states) 텐서 튜플로 매핑하는 dict 유사 컨테이너입니다. KV 공유 과정에서 레이어 간에 공유된 KV 상태를 전달하는 데 사용됩니다.
- **router_logits** (`tuple(torch.Tensor)`, *선택 사항*, `output_router_logits=True`가 전달될 때 반환됨) -- 각 MoE 레이어에 하나씩 포함된 `torch.Tensor`의 튜플로, 모양은 `(batch_size * sequence_length, num_experts)`입니다.

## Gemma4ForConditionalGeneration[[transformers.Gemma4ForConditionalGeneration]]

#### transformers.Gemma4ForConditionalGeneration[[transformers.Gemma4ForConditionalGeneration]]

```python
transformers.Gemma4ForConditionalGeneration(config: Gemma4Config)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/gemma4/modeling_gemma4.py#L2598)

**매개변수:**

config ([Gemma4Config](/docs/transformers/v5.23.0/ko/model_doc/gemma4#transformers.Gemma4Config)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [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.Gemma4ForConditionalGeneration.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, per_layer_inputs: typing.Optional[torch.Tensor] = 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/modeling_gemma4.py#L2624)

**매개변수:**

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)`, *선택 사항*) : 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 [Gemma4ImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/gemma4#transformers.Gemma4ImageProcessor)를 사용하여 얻을 수 있습니다. 자세한 내용은 [Gemma4ImageProcessor.__call__()](/docs/transformers/v5.23.0/ko/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__)를 참조하세요 ([Gemma4Processor](/docs/transformers/v5.23.0/ko/model_doc/gemma4#transformers.Gemma4Processor)는 이미지 처리에 [Gemma4ImageProcessor](/docs/transformers/v5.23.0/ko/model_doc/gemma4#transformers.Gemma4ImageProcessor)를 사용합니다).

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

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

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 형식(배치와 시퀀스 길이를 단일 차원으로 사용하는 경우)을 사용할 때 유용합니다.

per_layer_inputs (`torch.Tensor`, *선택 사항*) : `(batch_size, sequence_length, num_hidden_layers, hidden_size_per_layer_input)` 형태의 사전 계산된 레이어별 입력 텍스트 임베딩입니다. 이 값이 제공되면 텍스트 모델에서 `input_ids`를 `get_per_layer_inputs()`를 통해 계산하는 대신 이 값이 직접 사용됩니다. `input_ids` 대신 `inputs_embeds`로 `forward`를 호출하는 경우, 이 값들을 사전 계산하여 `inputs_embeds`와 함께 전달하는 것이 좋습니다. 그렇지 않으면 메인 임베딩을 역산해야 하므로 비용이 많이 듭니다.

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

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

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

[Gemma4ForConditionalGeneration](/docs/transformers/v5.23.0/ko/model_doc/gemma4#transformers.Gemma4ForConditionalGeneration)의 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** (`KVSharingDict`, *선택 사항*) -- 레이어 유형 문자열을 (key_states, value_states) 텐서 튜플로 매핑하는 dict 유사 컨테이너입니다. KV 공유 과정에서 레이어 간에 공유된 KV 상태를 전달하는 데 사용됩니다.
- **router_logits** (`tuple(torch.Tensor)`, *선택 사항*, `output_router_logits=True`가 전달될 때 반환됨) -- 각 MoE 레이어에 하나씩 포함된 `torch.Tensor`의 튜플로, 모양은 `(batch_size * sequence_length, num_experts)`입니다.

예:

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

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

