Hugging Face's logo

Transformers documentation

Gemma4 통합

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

이 모델은 2026-06-03에 Hugging Face Transformers에 기여되었습니다.

Gemma4 통합

개요

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

표준 Gemma 4와의 주요 차이점:

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

원본 Gemma 4 12B Unified 체크포인트는 Gemma 4 릴리스에서 찾을 수 있습니다.

Encoder-Free Vision Pipeline

…

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

표준 Gemma 4와 마찬가지로, 이 모델은 고정된 토큰 예산을 사용하여 크기가 다른 이미지를 처리합니다. 동일한 제약 조건이 적용됩니다:

  • …
  • 높이와 너비 모두 48(= 패치 크기 16 × 풀링 커널 3)로 나누어떨어져야 합니다

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

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

소프트 토큰패치(풀링 전)대략적인 이미지 영역
70630약 161K 픽셀
1401,260약 323K 픽셀
2802,520약 645K 픽셀
5605,040약 130만 픽셀
1,12010,080약 260만 픽셀

Encoder-Free 오디오 파이프라인

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

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

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

사용 예시

아래 예제는 Pipeline 또는 AutoModel 클래스를 사용하여 이미지와 오디오 샘플을 기반으로 텍스트를 생성하는 방법을 보여줍니다.

Pipeline
AutoModel
from transformers import pipeline


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

image_messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "image",
                "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"
            },
            {
                "type": "text",
                "text": "What is shown in this image?"
            }
        ]
    }
]

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

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

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

Gemma4UnifiedAudioConfig

class transformers.Gemma4UnifiedAudioConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Noneaudio_embed_dim: int = 640rms_norm_eps: float = 1e-06initializer_range: float = 0.02 )

매개변수

  • audio_embed_dim (int, 기본값 640) — 멀티모달 임베더에 입력되는 오디오 특징의 차원입니다. 각 오디오 소프트 토큰은 audio_samples_per_token개의 샘플로 구성된 원시 웨이브폼 프레임이므로 audio_embed_dim == audio_samples_per_token입니다.
  • rms_norm_eps (float, 선택 사항, 기본값 1e-06) — rms 정규화 레이어에서 사용되는 epsilon 값입니다.
  • initializer_range (float, 선택 사항, 기본값 0.02) — 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다.

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

Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.

Gemma4UnifiedConfig

class transformers.Gemma4UnifiedConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonetext_config: transformers.models.gemma4_unified.configuration_gemma4_unified.Gemma4UnifiedTextConfig | dict[str, typing.Any] | None = Nonevision_config: transformers.models.gemma4_unified.configuration_gemma4_unified.Gemma4UnifiedVisionConfig | dict[str, typing.Any] | None = Noneaudio_config: transformers.models.gemma4_unified.configuration_gemma4_unified.Gemma4UnifiedAudioConfig | dict[str, typing.Any] | None = Noneboi_token_id: int | None = 255999eoi_token_id: int | None = 258882image_token_id: int | None = 258880video_token_id: int | None = 258884boa_token_id: int | None = 256000eoa_token_index: int | None = 258883audio_token_id: int | None = 258881initializer_range: float | None = 0.02tie_word_embeddings: bool = True )

매개변수

  • text_config (Union[~models.gemma4_unified.configuration_gemma4_unified.Gemma4UnifiedTextConfig, dict[str, Any]], 선택) — 텍스트 백본의 config 객체 또는 사전입니다.
  • vision_config (Union[~models.gemma4_unified.configuration_gemma4_unified.Gemma4UnifiedVisionConfig, dict[str, Any]], 선택) — 비전 백본의 config 객체 또는 사전입니다.
  • audio_config (Union[~models.gemma4_unified.configuration_gemma4_unified.Gemma4UnifiedAudioConfig, dict[str, Any]], 선택) — 오디오 백본의 config 객체 또는 사전입니다.
  • boi_token_id (int, 선택 사항, 기본값 255999) — 이미지 프롬프트를 감싸기 위한 begin-of-image 토큰 인덱스입니다.
  • eoi_token_id (int, 선택 사항, 기본값 258882) — 이미지 프롬프트를 감싸기 위한 end-of-image 토큰 인덱스입니다.
  • image_token_id (int, 선택 사항, 기본값 258880) — 입력 이미지의 자리표시자로 사용되는 이미지 토큰 인덱스입니다.
  • video_token_id (int, 선택 사항, 기본값 258884) — 입력 비디오의 플레이스홀더로 사용되는 비디오 토큰 인덱스입니다.
  • boa_token_id (int, 선택 사항, 기본값 256000) — 오디오 프롬프트를 감싸기 위한 begin-of-audio 토큰 인덱스입니다.
  • eoa_token_index (int, 선택 사항, 기본값 258883) — 오디오 프롬프트를 감싸기 위한 end-of-audio 토큰 인덱스입니다.
  • audio_token_id (int, 선택 사항, 기본값 258881) — 입력 오디오의 자리 표시자로 사용되는 오디오 토큰 인덱스입니다.
  • initializer_range (float, 선택 사항, 기본값 0.02) — 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다.
  • tie_word_embeddings (bool, 선택, 기본값 True) — 모델의 tied_weights_keys 매핑에 따라 가중치 임베딩을 묶을지 여부.

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

Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.

예:

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

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

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

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

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

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

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

Gemma4UnifiedTextConfig

class transformers.Gemma4UnifiedTextConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevocab_size: int = 262144hidden_size: int = 2304intermediate_size: int = 9216num_hidden_layers: int = 30num_attention_heads: int = 8num_key_value_heads: int = 4head_dim: int = 256hidden_activation: str = 'gelu_pytorch_tanh'max_position_embeddings: int = 262144initializer_range: float = 0.02rms_norm_eps: float = 1e-06use_cache: bool = Truepad_token_id: int | None = 0eos_token_id: int | list[int] | None = 1bos_token_id: int | None = 2tie_word_embeddings: bool = Truerope_parameters: dict | None = Noneattention_bias: bool = Falseattention_dropout: int | float | None = 0.0sliding_window: int = 1024layer_types: list[str] | None = Nonefinal_logit_softcapping: float | None = Noneuse_bidirectional_attention: typing.Optional[typing.Literal['all', 'vision']] = 'vision'attention_k_eq_v: bool = Falsenum_kv_shared_layers: int = 0use_double_wide_mlp: bool = False )

매개변수

  • vocab_size (int, 선택 사항, 기본값 262144) — 모델의 어휘 크기입니다. input_ids로 표현할 수 있는 서로 다른 토큰의 수를 정의합니다.
  • hidden_size (int, 선택 사항, 기본값 2304) — 숨겨진 표현의 차원입니다.
  • intermediate_size (int, 선택 사항, 기본값 9216) — MLP 표현의 차원입니다.
  • num_hidden_layers (int, 선택 사항, 기본값 30) — Transformer decoder의 숨겨진 레이어 수입니다.
  • 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)하여 구성해야 합니다. 자세한 내용은 이 논문을 참고하세요. 지정되지 않으면 num_attention_heads가 기본값으로 사용됩니다.
  • head_dim (int, 선택 사항, 기본값 256) — Attention head의 차원입니다. None인 경우 hidden_size // num_attention_heads가 기본값으로 사용됩니다.
  • hidden_activation (str, 선택 사항, 기본값 gelu_pytorch_tanh) — 디코더에서 사용되는 비선형 활성화 함수(함수 또는 문자열)입니다. 예를 들어, "gelu", "relu", "silu" 등이 있습니다.
  • max_position_embeddings (int, 선택 사항, 기본값 262144) — 이 모델이 사용될 수 있는 최대 시퀀스 길이입니다.
  • initializer_range (float, 선택 사항, 기본값 0.02) — 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다.
  • rms_norm_eps (float, 선택 사항, 기본값 1e-06) — rms 정규화 레이어에서 사용되는 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 및 출력 투영 계층에 bias를 사용할지 여부입니다.
  • attention_dropout (Union[int, float], 선택 사항, 기본값 0.0) — Attention 확률에 적용할 dropout 비율입니다.
  • sliding_window (int, 선택 사항, 기본값 1024) — 슬라이딩 윈도우 어텐션의 윈도우 크기입니다. None인 경우 슬라이딩 윈도우가 적용되지 않습니다.
  • layer_types (list[str], 선택 사항) — 각 레이어 인덱스를 해당 레이어 유형에 명시적으로 매핑하는 목록입니다. 제공되지 않으면 config 값에 기반하여 자동으로 생성됩니다.
  • final_logit_softcapping (float, 선택 사항) — 확률 분포를 계산하기 전에 최종 logits에 적용되는 소프트 캡핑 값입니다. Logits는 tanh(logit / cap) * cap로 스케일링됩니다.
  • use_bidirectional_attention (str, 선택 사항) — 양방향 어텐션 동작을 제어합니다. "vision"으로 설정하면 비전 토큰은 양방향 어텐션을 사용하고 텍스트 토큰은 인과적 어텐션을 사용합니다. "all"로 설정하면 모든 토큰이 양방향 어텐션을 사용합니다.
  • attention_k_eq_v (bool, 기본값 False) — 키와 값이 동일한 투영 가중치를 공유하는지 여부입니다. True인 경우, 키 투영 출력을 값 투영으로 재사용합니다.
  • num_kv_shared_layers (int, 기본값 0) — 동일한 key-value 투영을 공유하는 연속 디코더 레이어의 수입니다. 0은 공유가 없음을 의미하며(각 레이어가 독립적인 KV 투영을 가짐),
  • use_double_wide_mlp (bool, 기본값 False) — gate와 up 투영이 결합된 이중 폭 MLP를 사용할지 여부입니다.

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

Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.

Gemma4UnifiedVisionConfig

클래스 transformers.Gemma4UnifiedVisionConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonepatch_size: int = 16pooling_kernel_size: int = 3mm_embed_dim: int = 3840mm_posemb_size: int = 1120rms_norm_eps: float = 1e-06output_proj_dims: int = 3840initializer_range: float = 0.02 )

매개변수

  • patch_size (int, 기본값 16) — 픽셀 단위의 이미지 패치 크기입니다. 이미지는 이 해상도에서 먼저 패치화됩니다.
  • pooling_kernel_size (int, 기본값 3) — 패치를 모델 패치로 병합할 때 사용할 커널 크기입니다. 3×3 병합을 수행하면 크기가 patch_size * pooling_kernel_size = 48 픽셀인 모델 패치가 생성됩니다.
  • mm_embed_dim (int, 기본값 3840) — 패치 임베딩 Dense 투영의 숨겨진 차원(텍스트 모델의 hidden_size와 일치).
  • mm_posemb_size (int, 기본값 1120) — 인자분해된 2D 위치 임베딩 테이블의 크기입니다. 테이블의 shape은 (mm_posemb_size, 2, mm_embed_dim)이며, 축별로 조회됩니다.
  • rms_norm_eps (float, 선택 사항, 기본값 1e-06) — rms 정규화 레이어에서 사용되는 epsilon 값입니다.
  • output_proj_dims (int, 기본값 3840) — 멀티모달 임베더 투영의 출력 차원(텍스트 hidden size로 매핑됨). 이 값은 런타임에 복합 설정의 text_config.hidden_size로 설정됩니다.
  • initializer_range (float, 선택 사항, 기본값 0.02) — 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다.

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

Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.

Gemma4UnifiedAudioFeatureExtractor

클래스 transformers.Gemma4UnifiedAudioFeatureExtractor

< >

( feature_size: int = 640sampling_rate: int = 16000padding_value: float = 0.0audio_samples_per_token: int = 640**kwargs )

매개변수

  • feature_size (int, 선택 사항, 기본값 640) — 추출된 feature의 차원(토큰당 샘플 수)입니다.
  • sampling_rate (int, 선택 사항, 기본값 16000) — 오디오 파일을 디지털화할 때 사용할 샘플링 주파수(Hz).
  • padding_value (float, 선택 사항, 기본값 0.0) — 오디오 패딩에 사용되는 패딩 값입니다.
  • audio_samples_per_token (int, 선택 사항, 기본값 640) — 출력 토큰당 원시 오디오 샘플 수. 16 kHz에서 640개 샘플은 40ms에 해당합니다.

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

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

__call__

< >

( raw_speech: numpy.ndarray | list[float] | list[numpy.ndarray] | list[list[float]]padding: bool | str = 'longest'max_length: int | None = Nonetruncation: bool = Truereturn_tensors: str | transformers.utils.generic.TensorType | None = None**kwargs )

매개변수

  • raw_speech — 처리할 원시 오디오 웨이브폼입니다.
  • padding (str, 선택 사항, 기본값 "longest") — 길이가 다른 배치에 대한 패딩 전략입니다.
  • max_length (int, 선택) — 오디오당 생성할 최대 토큰 수.
  • truncation (bool, 선택, 기본값 True) — max_length 토큰을 초과하는 오디오를 잘라낼지 여부.
  • return_tensors (str, 선택 사항) — 반환할 텐서의 유형입니다.

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

Gemma4UnifiedImageProcessor

class transformers.Gemma4UnifiedImageProcessor

< >

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

매개변수

  • 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로 설정된 경우 이미지를 재조정(rescale)하는 데 사용할 재조정 계수입니다.
  • 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, optional) — 이미지를 패딩할지 여부입니다. 패딩은 배치 내 가장 큰 크기로 수행하거나, 이미지마다 고정된 정사각형 크기로 수행합니다. 정확한 패딩 전략은 모델에 따라 달라집니다.
  • pad_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 이미지를 패딩할 {"height": int, "width" int} 크기를 지정합니다. 전처리용으로 제공된 모든 이미지 크기보다 커야 합니다. pad_size가 제공되지 않으면, 배치 내 가장 큰 높이와 너비로 패딩됩니다. do_pad=True.일 때만 적용됩니다.
  • do_center_crop (bool, kwargs, 선택) — 이미지를 중앙으로 크롭할지 여부.
  • data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) — ChannelDimension.FIRST만 지원됩니다. 느린 프로세서와의 호환성을 위해 추가되었습니다.
  • input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) — 입력 이미지의 채널 차원 형식입니다. 설정되지 않으면 입력 이미지에서 채널 차원 형식을 추론합니다. 다음 중 하나일 수 있습니다:
    • "channels_first" 또는 ChannelDimension.FIRST: (num_channels, height, width) 형식의 이미지.
    • "channels_last" 또는 ChannelDimension.LAST: (height, width, num_channels) 형식의 이미지.
    • "none" 또는 ChannelDimension.NONE: (height, width) 형식의 이미지.
  • device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — 동영상을 처리할 장치입니다. 설정되지 않은 경우, 입력 동영상에서 장치를 추론합니다.
  • return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — 'pt'로 설정된 경우 스택된 텐서를 반환하고, 그렇지 않으면 텐서 목록을 반환합니다.
  • disable_grouping (bool, kwargs, 선택 사항) — 이미지를 크기에 따라 그룹화하는 것을 비활성화하여 배치 대신 개별적으로 처리할지 여부입니다. None인 경우, 이미지가 CPU에 있으면 True, 그렇지 않으면 False로 설정됩니다. 이 선택은 https://github.com/huggingface/transformers/pull/38157에 자세히 설명된 경험적 관찰에 기반합니다.
  • image_seq_length (int, kwargs, 선택 사항) — 입력에서 각 이미지에 사용할 이미지 토큰의 수입니다. 하위 호환성을 위해 추가되었지만, 향후 모델에서는 프로세서 속성으로 설정해야 합니다.
  • patch_size (int, kwargs, 선택 사항) — 병합 전 각 teacher 이미지 패치의 픽셀 단위 크기.
  • max_soft_tokens (int, kwargs, 선택) — 패치 병합 후 이미지당 최대 소프트(비전) 토큰 수입니다. {70, 140, 280, 560, 1120} 중 하나여야 합니다.
  • pooling_kernel_size (int, kwargs, 선택 사항) — 교사 패치를 모델 패치로 병합할 때 사용할 커널 크기입니다.

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

Gemma4UnifiedVideoProcessor

class transformers.Gemma4UnifiedVideoProcessor

< >

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

매개변수

  • 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로 설정된 경우 이미지를 재조정(rescale)하는 데 사용할 재조정 계수입니다.
  • 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, optional) — 이미지를 패딩할지 여부입니다. 패딩은 배치 내 가장 큰 크기로 수행하거나, 이미지마다 고정된 정사각형 크기로 수행합니다. 정확한 패딩 전략은 모델에 따라 달라집니다.
  • 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, 선택) — 각 모달리티(텍스트, 이미지, 비디오, 오디오)에 대한 추가 처리 옵션입니다. 모델별 매개변수는 위에 나열되어 있으며, 지원되는 인수의 전체 목록은 TypedDict 클래스를 참조하세요.

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

preprocess

< >

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

매개변수

  • 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, optional) — do_rescale이 True로 설정된 경우 이미지를 리스케일하기 위한 리스케일 팩터입니다.
  • do_normalize (bool, kwargs, optional) — 이미지를 정규화할지 여부.
  • 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, optional) — 이미지를 패딩할지 여부입니다. 패딩은 배치 내 가장 큰 크기로 수행하거나, 이미지마다 고정된 정사각형 크기로 수행합니다. 정확한 패딩 전략은 모델에 따라 달라집니다.
  • crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — center_crop을 적용한 후 출력 이미지의 크기.
  • data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) — ChannelDimension.FIRST만 지원됩니다. 느린 프로세서와의 호환성을 위해 추가되었습니다.
  • input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) — 입력 이미지의 채널 차원 형식입니다. 설정되지 않으면 입력 이미지에서 채널 차원 형식을 추론합니다. 다음 중 하나일 수 있습니다:
    • "channels_first" 또는 ChannelDimension.FIRST: (num_channels, height, width) 형식의 이미지.
    • "channels_last" 또는 ChannelDimension.LAST: (height, width, num_channels) 형식의 이미지.
    • "none" 또는 ChannelDimension.NONE: (height, width) 형식의 이미지.
  • device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — 동영상을 처리할 장치입니다. 설정되지 않은 경우, 입력 동영상에서 장치를 추론합니다.
  • do_sample_frames (bool, kwargs, 선택) — 처리 전에 비디오에서 프레임을 샘플링할지, 아니면 비디오 전체를 처리할지 여부를 지정합니다.
  • video_metadata (Annotated[~video_utils.VideoMetadata | dict | list[dict | ~video_utils.VideoMetadata] | list[list[dict | ~video_utils.VideoMetadata]] | None, None], kwargs) — 총 길이, fps, 총 프레임 수에 대한 정보를 포함하는 비디오의 메타데이터입니다. 비디오에서 프레임을 샘플링하거나 타임스탬프를 계산하는 데 사용됩니다. 비디오를 수동으로 디코딩하여 처리하려는 경우를 제외하고는 메타데이터를 전달하지 마세요.
  • fps (Annotated[int | float | None, None], kwargs) — do_sample_frames=True인 경우 초당 샘플링할 대상 프레임 수.
  • num_frames (Annotated[int | None, None], kwargs) — do_sample_frames=True일 때 샘플링할 최대 프레임 수.
  • return_metadata (bool, kwargs, 선택) — 비디오 메타데이터를 반환할지 여부를 지정합니다. 비디오 메타데이터는 비디오 길이, fps, 디코딩 백엔드 등에 대한 정보를 포함하는 객체입니다.
  • return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — 'pt'로 설정된 경우 스택된 텐서를 반환하고, 그렇지 않으면 텐서 목록을 반환합니다.
  • patch_size (int, kwargs, 선택 사항) — 픽셀 단위의 각 이미지 패치 크기입니다.
  • max_soft_tokens (int, kwargs, 선택) — 비디오 프레임당 최대 소프트(비전) 토큰 수. {70, 140, 280, 560, 1120} 중 하나여야 합니다.
  • pooling_kernel_size (int, kwargs, 선택 사항) — 패치화 이후에 적용되는 공간 풀링 커널 크기.

반환값

~image_processing_base.BatchFeature

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

Gemma4UnifiedProcessor

class transformers.Gemma4UnifiedProcessor

< >

( feature_extractorimage_processortokenizervideo_processorchat_template = Noneimage_seq_length: int = 280audio_seq_length: int = 750audio_ms_per_token: int = 40**kwargs )

매개변수

  • feature_extractor (Gemma4UnifiedAudioFeatureExtractor) — 피처 추출기는 필수 입력입니다.
  • image_processor (Gemma4UnifiedImageProcessor) — 이미지 프로세서가 필수 입력값입니다.
  • tokenizer (tokenizer_class) — 토크나이저는 필수 입력값입니다.
  • video_processor (Gemma4UnifiedVideoProcessor) — video processor는 필수 입력값입니다.
  • chat_template (str) — 채팅의 메시지 목록을 토큰화 가능한 문자열로 변환하는 Jinja 템플릿입니다.
  • image_seq_length (int, 선택, 기본값 280) — 플레이스홀더 확장에 사용되는 이미지당 소프트 토큰 수입니다.
  • audio_seq_length (int, optional, 기본값 750) — 오디오 세그먼트당 오디오 소프트 토큰의 최대 개수입니다. 동적 오디오 토큰 수가 계산될 때 상한으로 사용됩니다.
  • audio_ms_per_token (int, optional, 기본값 40) — 출력 소프트 토큰당 오디오 밀리초 수입니다. ceil(duration_ms / audio_ms_per_token)을 사용하여 오디오 플레이스홀더 토큰의 수를 동적으로 계산하는 데 사용됩니다. 기본값 40은 10ms 프레임에 대한 SSCP 컨볼루션의 4배 시간 축약에서 유래합니다.

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

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

__call__

< >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] | None = Nonevideos: 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] = Noneaudio: 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'> )

매개변수

  • 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, 선택 사항) — 설정된 경우, 특정 프레임워크의 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:
    • 'pt': PyTorch torch.Tensor 객체를 반환합니다.
    • 'np': NumPy np.ndarray 객체를 반환합니다.
  • **kwargs (ProcessingKwargs, 선택) — 각 모달리티(텍스트, 이미지, 비디오, 오디오)에 대한 추가 처리 옵션입니다. 모델별 매개변수는 위에 나열되어 있으며, 지원되는 인수의 전체 목록은 TypedDict 클래스를 참조하세요.

Gemma4UnifiedPreTrainedModel

class transformers.Gemma4UnifiedPreTrainedModel

< >

( config: PreTrainedConfig*inputs**kwargs )

매개변수

  • config (PreTrainedConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 연관된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.

이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.

forward

( *args**kwargs )

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

Gemma4UnifiedModel

class transformers.Gemma4UnifiedModel

< >

( config: Gemma4UnifiedConfig )

매개변수

  • config (Gemma4UnifiedConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 연관된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.

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

이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Nonepixel_values: typing.Optional[torch.Tensor] = Nonepixel_values_videos: typing.Optional[torch.Tensor] = Noneinput_features: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneinput_features_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Nonemm_token_type_ids: typing.Optional[torch.LongTensor] = Noneinputs_embeds: typing.Optional[torch.Tensor] = Noneuse_cache: bool | None = Noneimage_position_ids: typing.Optional[torch.LongTensor] = Nonevideo_position_ids: typing.Optional[torch.LongTensor] = Nonenum_frames_per_video: typing.Optional[torch.LongTensor] = Nonemm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Gemma4UnifiedModelOutputWithPast or tuple(torch.Tensor)

매개변수

  • input_ids (torch.LongTensor 형상이 (batch_size, sequence_length), 선택 사항) — 어휘(input vocabulary)에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 패딩은 무시됩니다.

    AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.

    입력 ID란 무엇인가요?

  • pixel_values (torch.Tensor, shape (batch_size, num_channels, image_size, image_size), 선택 사항) — 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 Gemma4UnifiedImageProcessor를 사용하여 얻을 수 있습니다. 자세한 내용은 Gemma4UnifiedImageProcessor.call()를 참조하세요 (Gemma4UnifiedProcessor는 이미지 처리에 Gemma4UnifiedImageProcessor를 사용합니다).
  • pixel_values_videos (torch.Tensor, shape (batch_size, num_frames, num_channels, frame_size, frame_size), 선택 사항) — 입력 비디오에 해당하는 텐서입니다. 비디오의 픽셀 값은 Gemma4UnifiedVideoProcessor를 사용하여 얻을 수 있습니다. 자세한 내용은 Gemma4UnifiedVideoProcessor.call()를 참조하세요 (Gemma4UnifiedProcessor는 비디오 처리에 Gemma4UnifiedVideoProcessor를 사용합니다).
  • input_features (torch.Tensor, shape (batch_size, sequence_length, feature_dim), 선택 사항) — 입력 오디오 특징에 해당하는 텐서입니다. 오디오 특징은 Gemma4UnifiedAudioFeatureExtractor를 사용하여 얻을 수 있습니다. 자세한 내용은 Gemma4UnifiedAudioFeatureExtractor.call()를 참조하세요 (Gemma4UnifiedProcessor는 오디오 처리에 Gemma4UnifiedAudioFeatureExtractor를 사용합니다).
  • attention_mask (torch.Tensor 형상이 (batch_size, sequence_length), 선택 사항) — 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크. [0, 1]에서 선택된 마스크 값: 마스크되지 않은 토큰은 1, 마스크된 토큰은 0. attention mask란 무엇인가요? [0, 1]:
    • 마스크되지 않은 토큰에 대해 1
    • 마스크된 토큰에 대해 0

    어텐션 마스크란 무엇인가요?

  • input_features_mask (torch.Tensor, shape (num_images, seq_length)) — 입력 오디오의 어텐션 마스크입니다.
  • position_ids (torch.LongTensor 의 shape (batch_size, sequence_length), , 선택 사항) — 위치 임베딩에서 각 입력 시퀀스 토큰의 위치 인덱스. 범위 [0, config.n_positions - 1].

    포지션 ID란 무엇인가요?

  • past_key_values (~cache_utils.Cache, 선택 사항) — 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(self-attention 블록과 cross-attention 블록의 key 및 value). 일반적으로 이는 past_key_values 디코딩의 이전 단계에서 모델이 반환한 use_cache=True 또는 config.use_cache=True.

    입력으로 Cache 인스턴스만 허용되며, kv cache 가이드를 참고하세요. past_key_values가 전달되지 않으면 기본적으로 DynamicCache가 초기화됩니다.

    모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다.

    past_key_values를 사용하는 경우, 이 모델에 과거 키 값 상태가 제공되지 않은 input_ids만 입력해야 하며, 이때의 shape은 (batch_size, unprocessed_length)입니다. shape이 (batch_size, sequence_length)인 전체 input_ids를 입력하지 않습니다.

  • mm_token_type_ids (torch.LongTensor, shape (batch_size, sequence_length), 선택 사항) — 각 모달리티와 일치하는 입력 시퀀스 토큰의 인덱스입니다. 예를 들어 텍스트(0), 이미지(1), 비디오(2) 등이 있습니다. 멀티모달 토큰 타입 ID는 AutoProcessor를 사용하여 얻을 수 있습니다. 자세한 내용은 ProcessorMixin.call()를 참조하세요.
  • inputs_embeds (torch.Tensor, shape (batch_size, sequence_length, hidden_size), 선택) — input_ids를 전달하는 대신 임베딩 표현을 직접 전달할 수 있습니다. 이는 모델 내부의 임베딩 조회 행렬보다 input_ids 인덱스를 관련 벡터로 변환하는 방식에 대해 더 세밀한 제어가 필요한 경우에 유용합니다.
  • use_cache (bool, 선택 사항) — True로 설정하면 past_key_values 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다( past_key_values 참조).
  • image_position_ids (torch.LongTensor, shape (batch_size, max_patches, 2), 선택 사항) — 이미지 프로세서에서 생성된 2D 패치 위치 좌표이며, (-1, -1)은 패딩을 나타냅니다. 위치 임베딩 계산에 사용되도록 비전 인코더로 전달됩니다.
  • video_position_ids (torch.LongTensor, shape (total_num_frames, max_patches, 2), 선택 사항) — 비디오 프로세서에서 생성된 2D 패치 위치 좌표이며, (-1, -1)은 패딩을 나타냅니다. 위치 임베딩 계산에 사용되도록 비전 인코더로 전달됩니다.
  • num_frames_per_video (torch.LongTensor, shape (num_videos,), 선택 사항) — 각 비디오에 속하는 프레임 수입니다. 모든 비디오의 프레임이 단일 축을 따라 연결되므로 pixel_values_videos를 전달할 때 필수입니다.
  • mm_encoder_outputs (dict[str, ~modeling_outputs.BaseModelOutputWithPooling], 선택 사항) — 키가 지원되는 모달리티이고 값이 해당 모달리티의 인코딩된 출력인 딕셔너리입니다. 각 인코딩된 출력은 (pooler_output, 선택 사항: last_hidden_states, 선택 사항: hidden_states, 선택 사항: attentions) pooler_output의 형태가 (batch_size, sequence_length, hidden_size)인 선택 사항)으로 구성된 튜플이며, 인코더의 멀티모달 특징을 텍스트 임베딩에 병합한 시퀀스입니다.

반환값

Gemma4UnifiedModelOutputWithPast 또는 tuple(torch.Tensor)

Gemma4UnifiedModelOutputWithPast 또는 torch.Tensor의 튜플(return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(Gemma4UnifiedConfig)과 입력에 따라 다양한 요소를 포함합니다.

Gemma4UnifiedModel의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.

이 함수 내에서 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 인스턴스입니다. 자세한 내용은 kv cache 가이드를 참고하세요.

    순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록의 key와 value)를 포함합니다(입력 past_key_values 참조).

  • hidden_states (tuple(torch.Tensor), 선택 사항, output_hidden_states=True가 전달되거나 config.output_hidden_states=True인 경우 반환됨) — torch.Tensor의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은 (batch_size, sequence_length, hidden_size)입니다.

    각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.

  • attentions (tuple(torch.Tensor), 선택 사항, output_attentions=True가 전달되었거나 config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된 torch.Tensor의 튜플로, 모양은 (batch_size, num_heads, sequence_length, sequence_length)입니다.

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

  • image_hidden_states (torch.Tensor, 선택 사항) — 크기가 (batch_size, num_images, sequence_length, hidden_size)인 torch.Tensor입니다. 비전 인코더가 생성한 모델의 image_hidden_states이며, 마지막 hidden state를 투영한 후의 값입니다.

  • audio_hidden_states (torch.Tensor, 선택 사항) — 크기가 (batch_size, num_images, sequence_length, hidden_size)인 torch.Tensor입니다. 오디오 인코더가 생성한 모델의 audio_hidden_states이며, 마지막 hidden state를 투영한 후의 값입니다.

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

Gemma4UnifiedTextModel

class transformers.Gemma4UnifiedTextModel

< >

( config: Gemma4UnifiedTextConfig )

매개변수

  • config (Gemma4UnifiedTextConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 연관된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.

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

이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Noneuse_cache: bool | None = Nonelogits_to_keep: typing.Union[int, torch.Tensor] = 0**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Gemma4UnifiedTextModelOutputWithPast or tuple(torch.Tensor)

매개변수

  • input_ids (torch.LongTensor 형상이 (batch_size, sequence_length), 선택 사항) — 어휘(input vocabulary)에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 패딩은 무시됩니다.

    AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.

    입력 ID란 무엇인가요?

  • attention_mask (torch.Tensor 형상이 (batch_size, sequence_length), 선택 사항) — 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크. [0, 1]에서 선택된 마스크 값: 마스크되지 않은 토큰은 1, 마스크된 토큰은 0. attention mask란 무엇인가요? [0, 1]:
    • 마스크되지 않은 토큰에 대해 1
    • 마스크된 토큰에 대해 0

    어텐션 마스크란 무엇인가요?

  • position_ids (torch.LongTensor 의 shape (batch_size, sequence_length), , 선택 사항) — 위치 임베딩에서 각 입력 시퀀스 토큰의 위치 인덱스. 범위 [0, config.n_positions - 1].

    포지션 ID란 무엇인가요?

  • past_key_values (~cache_utils.Cache, 선택 사항) — 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(self-attention 블록과 cross-attention 블록의 key 및 value). 일반적으로 이는 past_key_values 디코딩의 이전 단계에서 모델이 반환한 use_cache=True 또는 config.use_cache=True.

    입력으로 Cache 인스턴스만 허용되며, kv cache 가이드를 참고하세요. past_key_values가 전달되지 않으면 기본적으로 DynamicCache가 초기화됩니다.

    모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다.

    past_key_values를 사용하는 경우, 이 모델에 과거 키 값 상태가 제공되지 않은 input_ids만 입력해야 하며, 이때의 shape은 (batch_size, unprocessed_length)입니다. shape이 (batch_size, sequence_length)인 전체 input_ids를 입력하지 않습니다.

  • inputs_embeds (torch.Tensor, shape (batch_size, sequence_length, hidden_size), 선택) — input_ids를 전달하는 대신 임베딩 표현을 직접 전달할 수 있습니다. 이는 모델 내부의 임베딩 조회 행렬보다 input_ids 인덱스를 관련 벡터로 변환하는 방식에 대해 더 세밀한 제어가 필요한 경우에 유용합니다.
  • use_cache (bool, 선택 사항) — True로 설정하면 past_key_values 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다( past_key_values 참조).
  • logits_to_keep (Union[int, torch.Tensor], 선택 사항, 기본값 0) — int인 경우, 마지막 logits_to_keep 토큰에 대한 logits를 계산합니다. 0인 경우, 모든 input_ids에 대한 logits를 계산합니다(특수한 경우). 생성에는 마지막 토큰의 logits만 필요하며, 해당 토큰에 대해서만 계산하면 메모리를 절약할 수 있습니다. 이는 긴 시퀀스나 큰 어휘 크기의 경우 상당한 이점을 제공합니다. torch.Tensor인 경우, 시퀀스 길이 차원에서 유지할 인덱스에 해당하는 1차원 텐서여야 합니다. 이는 패킹된 텐서 형식(배치와 시퀀스 길이를 단일 차원으로 사용하는 경우)을 사용할 때 유용합니다.

반환값

Gemma4UnifiedTextModelOutputWithPast 또는 tuple(torch.Tensor)

Gemma4UnifiedTextModelOutputWithPast 또는 torch.Tensor의 튜플(return_dict=False가 전달되거나 config.return_dict=False인 경우)로, 구성(Gemma4UnifiedConfig)과 입력에 따라 다양한 요소를 포함합니다.

Gemma4UnifiedTextModel의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.

이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신 Module 인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.

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

Gemma4UnifiedForCausalLM

클래스 transformers.Gemma4UnifiedForCausalLM

< >

( config: Gemma4UnifiedTextConfig )

매개변수

  • config (Gemma4UnifiedTextConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 연관된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.

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

이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = Nonelogits_to_keep: typing.Union[int, torch.Tensor] = 0**kwargs ) → Gemma4UnifiedCausalLMOutputWithPast or tuple(torch.Tensor)

매개변수

  • input_ids (torch.LongTensor 형상이 (batch_size, sequence_length), 선택 사항) — 어휘(input vocabulary)에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 패딩은 무시됩니다.

    AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.

    입력 ID란 무엇인가요?

  • attention_mask (torch.Tensor 형상이 (batch_size, sequence_length), 선택 사항) — 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크. [0, 1]에서 선택된 마스크 값: 마스크되지 않은 토큰은 1, 마스크된 토큰은 0. attention mask란 무엇인가요? [0, 1]:
    • 마스크되지 않은 토큰에 대해 1
    • 마스크된 토큰에 대해 0

    어텐션 마스크란 무엇인가요?

  • position_ids (torch.LongTensor 의 shape (batch_size, sequence_length), , 선택 사항) — 위치 임베딩에서 각 입력 시퀀스 토큰의 위치 인덱스. 범위 [0, config.n_positions - 1].

    포지션 ID란 무엇인가요?

  • past_key_values (~cache_utils.Cache, 선택 사항) — 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(self-attention 블록과 cross-attention 블록의 key 및 value). 일반적으로 이는 past_key_values 디코딩의 이전 단계에서 모델이 반환한 use_cache=True 또는 config.use_cache=True.

    입력으로 Cache 인스턴스만 허용되며, kv cache 가이드를 참고하세요. past_key_values가 전달되지 않으면 기본적으로 DynamicCache가 초기화됩니다.

    모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다.

    past_key_values를 사용하는 경우, 이 모델에 과거 키 값 상태가 제공되지 않은 input_ids만 입력해야 하며, 이때의 shape은 (batch_size, unprocessed_length)입니다. shape이 (batch_size, sequence_length)인 전체 input_ids를 입력하지 않습니다.

  • inputs_embeds (torch.Tensor, shape (batch_size, sequence_length, hidden_size), 선택) — input_ids를 전달하는 대신 임베딩 표현을 직접 전달할 수 있습니다. 이는 모델 내부의 임베딩 조회 행렬보다 input_ids 인덱스를 관련 벡터로 변환하는 방식에 대해 더 세밀한 제어가 필요한 경우에 유용합니다.
  • labels (torch.LongTensor 형태가 (batch_size, sequence_length), 선택 사항) — causal language modeling loss를 계산하기 위한 라벨. 인덱스는 [-100, 0, ..., config.vocab_size] (참조 input_ids 문서 문자열). 인덱스가 -100 으로 설정된 토큰은 무시(마스크)되며, loss는 라벨이 [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차원 텐서여야 합니다. 이는 패킹된 텐서 형식(배치와 시퀀스 길이를 단일 차원으로 사용하는 경우)을 사용할 때 유용합니다.

반환값

Gemma4UnifiedCausalLMOutputWithPast 또는 tuple(torch.Tensor)

Gemma4UnifiedCausalLMOutputWithPast 또는 torch.Tensor의 튜플(return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(Gemma4UnifiedConfig)과 입력에 따라 다양한 요소를 포함합니다.

Gemma4UnifiedForCausalLM의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.

이 함수 내에서 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 인스턴스입니다. 자세한 내용은 kv cache 가이드를 참고하세요.

    순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록의 key와 value)를 포함합니다(입력 past_key_values 참조).

  • hidden_states (tuple[torch.Tensor], 선택 사항, output_hidden_states=True가 전달되거나 config.output_hidden_states=True인 경우 반환됨) — torch.Tensor의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은 (batch_size, sequence_length, hidden_size)입니다.

    각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.

  • attentions (tuple[torch.Tensor], 선택 사항, output_attentions=True가 전달되었거나 config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된 torch.Tensor의 튜플로, 모양은 (batch_size, num_heads, sequence_length, sequence_length)입니다.

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

  • image_hidden_states (torch.Tensor, 선택 사항) — 크기가 (batch_size, num_images, sequence_length, hidden_size)인 torch.Tensor입니다. 비전 인코더가 마지막 hidden state를 투사한 후 모델이 생성한 image_hidden_states입니다.

  • audio_hidden_states (torch.Tensor, 선택 사항) — 크기가 (batch_size, num_images, sequence_length, hidden_size)인 torch.Tensor입니다. 오디오 인코더가 생성한 모델의 audio_hidden_states이며, 마지막 hidden state를 투영한 후의 값입니다.

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

예:

>>> from transformers import AutoTokenizer, Gemma4UnifiedForCausalLM

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

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

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

Gemma4UnifiedForConditionalGeneration

class transformers.Gemma4UnifiedForConditionalGeneration

< >

( config: Gemma4UnifiedConfig )

매개변수

  • config (Gemma4UnifiedConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 연관된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.

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

이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Nonepixel_values: typing.Optional[torch.Tensor] = Nonepixel_values_videos: typing.Optional[torch.Tensor] = Noneinput_features: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneinput_features_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Noneimage_position_ids: typing.Optional[torch.LongTensor] = Nonevideo_position_ids: typing.Optional[torch.LongTensor] = Nonenum_frames_per_video: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Nonemm_token_type_ids: typing.Optional[torch.LongTensor] = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = Nonelogits_to_keep: typing.Union[int, torch.Tensor] = 0mm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Gemma4UnifiedCausalLMOutputWithPast or tuple(torch.Tensor)

매개변수

  • input_ids (torch.LongTensor 형상이 (batch_size, sequence_length), 선택 사항) — 어휘(input vocabulary)에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 패딩은 무시됩니다.

    AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.

    입력 ID란 무엇인가요?

  • pixel_values (torch.Tensor, shape (batch_size, num_channels, image_size, image_size), 선택 사항) — 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 Gemma4UnifiedImageProcessor를 사용하여 얻을 수 있습니다. 자세한 내용은 Gemma4UnifiedImageProcessor.call()를 참조하세요 (Gemma4UnifiedProcessor는 이미지 처리에 Gemma4UnifiedImageProcessor를 사용합니다).
  • pixel_values_videos (torch.Tensor, shape (batch_size, num_frames, num_channels, frame_size, frame_size), 선택 사항) — 입력 비디오에 해당하는 텐서입니다. 비디오의 픽셀 값은 Gemma4UnifiedVideoProcessor를 사용하여 얻을 수 있습니다. 자세한 내용은 Gemma4UnifiedVideoProcessor.call()를 참조하세요 (Gemma4UnifiedProcessor는 비디오 처리에 Gemma4UnifiedVideoProcessor를 사용합니다).
  • input_features (torch.Tensor, shape (batch_size, sequence_length, feature_dim), 선택 사항) — 입력 오디오 특징에 해당하는 텐서입니다. 오디오 특징은 Gemma4UnifiedAudioFeatureExtractor를 사용하여 얻을 수 있습니다. 자세한 내용은 Gemma4UnifiedAudioFeatureExtractor.call()를 참조하세요 (Gemma4UnifiedProcessor는 오디오 처리에 Gemma4UnifiedAudioFeatureExtractor를 사용합니다).
  • attention_mask (torch.Tensor 형상이 (batch_size, sequence_length), 선택 사항) — 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크. [0, 1]에서 선택된 마스크 값: 마스크되지 않은 토큰은 1, 마스크된 토큰은 0. attention mask란 무엇인가요? [0, 1]:
    • 마스크되지 않은 토큰에 대해 1
    • 마스크된 토큰에 대해 0

    어텐션 마스크란 무엇인가요?

  • input_features_mask (torch.Tensor, shape (num_images, seq_length)) — 입력 오디오의 어텐션 마스크입니다.
  • position_ids (torch.LongTensor 의 shape (batch_size, sequence_length), , 선택 사항) — 위치 임베딩에서 각 입력 시퀀스 토큰의 위치 인덱스. 범위 [0, config.n_positions - 1].

    포지션 ID란 무엇인가요?

  • 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(self-attention 블록과 cross-attention 블록의 key 및 value). 일반적으로 이는 past_key_values 디코딩의 이전 단계에서 모델이 반환한 use_cache=True 또는 config.use_cache=True.

    입력으로 Cache 인스턴스만 허용되며, kv cache 가이드를 참고하세요. past_key_values가 전달되지 않으면 기본적으로 DynamicCache가 초기화됩니다.

    모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다.

    past_key_values를 사용하는 경우, 이 모델에 과거 키 값 상태가 제공되지 않은 input_ids만 입력해야 하며, 이때의 shape은 (batch_size, unprocessed_length)입니다. shape이 (batch_size, sequence_length)인 전체 input_ids를 입력하지 않습니다.

  • mm_token_type_ids (torch.LongTensor, shape (batch_size, sequence_length), 선택 사항) — 각 모달리티와 일치하는 입력 시퀀스 토큰의 인덱스입니다. 예를 들어 텍스트(0), 이미지(1), 비디오(2) 등이 있습니다. 멀티모달 토큰 타입 ID는 AutoProcessor를 사용하여 얻을 수 있습니다. 자세한 내용은 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), 선택 사항) — 마스크 언어 모델링 손실을 계산하는 데 사용되는 라벨입니다. 인덱스는 [0, ..., config.vocab_size] 범위 내의 값이거나 -100이어야 합니다(input_ids docstring 참조). 인덱스가 -100으로 설정된 토큰은 무시(마스크)되며, 손실은 [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차원 텐서여야 합니다. 이는 패킹된 텐서 형식(배치와 시퀀스 길이를 단일 차원으로 사용하는 경우)을 사용할 때 유용합니다.
  • mm_encoder_outputs (dict[str, ~modeling_outputs.BaseModelOutputWithPooling], 선택 사항) — 키가 지원되는 모달리티이고 값이 해당 모달리티의 인코딩된 출력인 딕셔너리입니다. 각 인코딩된 출력은 (pooler_output, 선택 사항: last_hidden_states, 선택 사항: hidden_states, 선택 사항: attentions) pooler_output의 형태가 (batch_size, sequence_length, hidden_size)인 선택 사항)으로 구성된 튜플이며, 인코더의 멀티모달 특징을 텍스트 임베딩에 병합한 시퀀스입니다.

반환값

Gemma4UnifiedCausalLMOutputWithPast 또는 tuple(torch.Tensor)

Gemma4UnifiedCausalLMOutputWithPast 또는 torch.Tensor의 튜플(return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(Gemma4UnifiedConfig)과 입력에 따라 다양한 요소를 포함합니다.

Gemma4UnifiedForConditionalGeneration의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.

이 함수 내에서 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 인스턴스입니다. 자세한 내용은 kv cache 가이드를 참고하세요.

    순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록의 key와 value)를 포함합니다(입력 past_key_values 참조).

  • hidden_states (tuple[torch.Tensor], 선택 사항, output_hidden_states=True가 전달되거나 config.output_hidden_states=True인 경우 반환됨) — torch.Tensor의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은 (batch_size, sequence_length, hidden_size)입니다.

    각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.

  • attentions (tuple[torch.Tensor], 선택 사항, output_attentions=True가 전달되었거나 config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된 torch.Tensor의 튜플로, 모양은 (batch_size, num_heads, sequence_length, sequence_length)입니다.

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

  • image_hidden_states (torch.Tensor, 선택 사항) — 크기가 (batch_size, num_images, sequence_length, hidden_size)인 torch.Tensor입니다. 비전 인코더가 마지막 hidden state를 투사한 후 모델이 생성한 image_hidden_states입니다.

  • audio_hidden_states (torch.Tensor, 선택 사항) — 크기가 (batch_size, num_images, sequence_length, hidden_size)인 torch.Tensor입니다. 오디오 인코더가 생성한 모델의 audio_hidden_states이며, 마지막 hidden state를 투영한 후의 값입니다.

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

예:

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

>>> model = Gemma4UnifiedForConditionalGeneration.from_pretrained("google/gemma-4-12B-it")
>>> processor = AutoProcessor.from_pretrained("google/gemma-4-12B-it")

>>> messages = [
...     {
...         "role": "user", "content": [
...             {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"},
...             {"type": "text", "text": "Where is the cat standing?"},
...         ]
...     },
... ]

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

←Gemma4 GIT→