Transformers 文件
Gemma 3
並獲得增強的文件體驗
開始使用
Gemma 3
Gemma 3 是一個多模態模型，具有預訓練和指令微調變體，提供 1B、13B 和 27B 引數。其架構與之前的 Gemma 版本基本相同。主要區別在於每隔一個全域性自注意力層交替使用 5 個區域性滑動視窗自注意力層，支援 128K 令牌的更長上下文長度，以及一個可以“平移和掃描”高解析度影像以防止資訊在高解析度影像或非正方形寬高比影像中丟失的 SigLip 編碼器。
指令微調變體透過知識蒸餾和強化學習進行後訓練。
您可以在 Gemma 3 釋出中找到所有原始 Gemma 3 檢查點。
點選右側邊欄中的 Gemma 3 模型，檢視更多 Gemma 應用於不同視覺和語言任務的示例。
以下示例演示如何使用 Pipeline 或 AutoModel 類根據影像生成文字。
import torch
from transformers import pipeline
pipeline = pipeline(
task="image-text-to-text",
model="google/gemma-3-4b-pt",
device=0,
torch_dtype=torch.bfloat16
)
pipeline(
"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg",
text="<start_of_image> What is shown in this image?"
)量化透過以較低精度表示權重來減少大型模型的記憶體負擔。有關更多可用量化後端，請參閱量化概述。
以下示例使用torchao僅將權重量化為int4。
# pip install torchao
import torch
from transformers import TorchAoConfig, Gemma3ForConditionalGeneration, AutoProcessor
quantization_config = TorchAoConfig("int4_weight_only", group_size=128)
model = Gemma3ForConditionalGeneration.from_pretrained(
"google/gemma-3-27b-it",
torch_dtype=torch.bfloat16,
device_map="auto",
quantization_config=quantization_config
)
processor = AutoProcessor.from_pretrained(
"google/gemma-3-27b-it",
padding_side="left"
)
messages = [
{
"role": "system",
"content": [
{"type": "text", "text": "You are a helpful assistant."}
]
},
{
"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("cuda")
output = model.generate(**inputs, max_new_tokens=50, cache_implementation="static")
print(processor.decode(output[0], skip_special_tokens=True))使用 AttentionMaskVisualizer 可以更好地理解模型能夠或不能關注的令牌。
from transformers.utils.attention_visualizer import AttentionMaskVisualizer
visualizer = AttentionMaskVisualizer("google/gemma-3-4b-it")
visualizer("<img>What is shown in this image?")
注意事項
對於影像和文字以及僅影像輸入，請使用 Gemma3ForConditionalGeneration。
Gemma 3 支援多張輸入影像，但在將影像傳遞給處理器之前，請確保它們已正確批處理。每個批次都應該是一個或多個影像的列表。
url_cow = "https://media.istockphoto.com/id/1192867753/photo/cow-in-berchida-beach-siniscola.jpg?s=612x612&w=0&k=20&c=v0hjjniwsMNfJSuKWZuIn8pssmD5h5bSN1peBd1CmH4=" url_cat = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg" messages =[ { "role": "system", "content": [ {"type": "text", "text": "You are a helpful assistant."} ] }, { "role": "user", "content": [ {"type": "image", "url": url_cow}, {"type": "image", "url": url_cat}, {"type": "text", "text": "Which image is cuter?"}, ] }, ]傳遞給處理器的文字應在需要插入影像的位置包含
<start_of_image>令牌。處理器擁有自己的 apply_chat_template() 方法，可將聊天訊息轉換為模型輸入。
預設情況下，影像不會被裁剪，只有基本影像會轉發到模型。在高解析度影像或非正方形寬高比影像中，由於視覺編碼器使用固定的 896x896 解析度，可能會導致偽影。為了防止這些偽影並提高推理效能，請設定
do_pan_and_scan=True以將影像裁剪成多個較小的補丁，並將其與基本影像嵌入連線起來。您可以停用平移和掃描以加快推理速度。inputs = processor.apply_chat_template( messages, tokenize=True, return_dict=True, return_tensors="pt", add_generation_prompt=True, + do_pan_and_scan=True, ).to("cuda")對於以純文字模式訓練的 Gemma-3 1B 檢查點，請改用 AutoModelForCausalLM。
import torch from transformers import AutoModelForCausalLM, AutoTokenizer tokenizer = AutoTokenizer.from_pretrained( "google/gemma-3-1b-pt", ) model = AutoModelForCausalLM.from_pretrained( "google/gemma-3-1b-pt", torch_dtype=torch.bfloat16, device_map="auto", attn_implementation="sdpa" ) input_ids = tokenizer("Plants create energy through a process known as", return_tensors="pt").to("cuda") output = model.generate(**input_ids, cache_implementation="static") print(tokenizer.decode(output[0], skip_special_tokens=True))
Gemma3影像處理器
class transformers.Gemma3ImageProcessor
< 源 >( do_resize: bool = True size: typing.Optional[dict[str, int]] = None resample: Resampling = <Resampling.BILINEAR: 2> do_rescale: bool = True rescale_factor: typing.Union[int, float] = 0.00392156862745098 do_normalize: bool = True image_mean: typing.Union[float, list[float], NoneType] = None image_std: typing.Union[float, list[float], NoneType] = None do_convert_rgb: typing.Optional[bool] = None do_pan_and_scan: typing.Optional[bool] = None pan_and_scan_min_crop_size: typing.Optional[int] = None pan_and_scan_max_num_crops: typing.Optional[int] = None pan_and_scan_min_ratio_to_activate: typing.Optional[float] = None **kwargs )
引數
- do_resize (
bool, 可選，預設為True) — 是否將影像的（高、寬）尺寸調整為指定的size。可在preprocess方法中透過do_resize覆蓋。 - size (
dict[str, int]可選，預設為{"height" -- 224, "width": 224})：調整大小後圖像的尺寸。可在preprocess方法中透過size覆蓋。 - resample (
PILImageResampling, 可選，預設為Resampling.BILINEAR) — 如果調整影像大小，則使用的重取樣濾波器。可在preprocess方法中透過resample覆蓋。 - do_rescale (
bool, 可選，預設為True) — 是否按指定的比例rescale_factor重新縮放影像。可在preprocess方法中透過do_rescale覆蓋。 - rescale_factor (
int或float, 可選，預設為1/255) — 如果重新縮放影像，則使用的比例因子。可在preprocess方法中透過rescale_factor覆蓋。 - do_normalize (
bool, 可選，預設為True) — 是否透過指定的均值和標準差對影像進行歸一化。可在preprocess方法中透過do_normalize覆蓋。 - image_mean (
float或list[float], 可選，預設為[0.5, 0.5, 0.5]) — 如果對影像進行歸一化，則使用的均值。這是一個浮點數或浮點數列表，其長度與影像中的通道數相同。可在preprocess方法中透過image_mean引數覆蓋。 - image_std (
float或list[float], 可選，預設為[0.5, 0.5, 0.5]) — 如果對影像進行歸一化，則使用的標準差。這是一個浮點數或浮點數列表，其長度與影像中的通道數相同。可在preprocess方法中透過image_std引數覆蓋。 - do_convert_rgb (
bool, 可選，預設為True) — 是否將影像轉換為 RGB 格式。 - do_pan_and_scan (
bool, 可選) — 是否對影像應用pan_and_scan。 - pan_and_scan_min_crop_size (
int, 可選) — 平移和掃描中每個裁剪的最小尺寸。 - pan_and_scan_max_num_crops (
int, 可選) — 平移和掃描中每張影像的最大裁剪數量。 - pan_and_scan_min_ratio_to_activate (
float, 可選) — 啟用平移和掃描的最小寬高比。
構造 SigLIP 影像處理器。
pan_and_scan
< 源 >( image: ndarray pan_and_scan_min_crop_size: int pan_and_scan_max_num_crops: int pan_and_scan_min_ratio_to_activate: float data_format: typing.Union[str, transformers.image_utils.ChannelDimension, NoneType] = None input_data_format: typing.Union[str, transformers.image_utils.ChannelDimension, NoneType] = None )
引數
- image (
np.ndarray) — 要調整大小的影像。 - pan_and_scan_min_crop_size (
int, 可選) — 平移和掃描中每個裁剪的最小尺寸。 - pan_and_scan_max_num_crops (
int, 可選) — 平移和掃描中每張影像的最大裁剪數量。 - pan_and_scan_min_ratio_to_activate (
float, 可選) — 啟用平移和掃描的最小寬高比。 - data_format (
str或ChannelDimension, 可選) — 影像的通道維度格式。如果未提供，將與輸入影像的格式相同。 - input_data_format (
ChannelDimension或str, 可選) — 輸入影像的通道維度格式。如果未提供，將自動推斷。
平移和掃描影像，當寬高比超過允許的最小比率時，將其裁剪成較小的影像。
preprocess
< 源 >( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']] do_resize: typing.Optional[bool] = None size: typing.Optional[dict[str, int]] = None resample: Resampling = None do_rescale: typing.Optional[bool] = None rescale_factor: typing.Optional[float] = None do_normalize: typing.Optional[bool] = None image_mean: typing.Union[float, list[float], NoneType] = None image_std: typing.Union[float, list[float], NoneType] = None return_tensors: typing.Union[str, transformers.utils.generic.TensorType, NoneType] = None data_format: typing.Optional[transformers.image_utils.ChannelDimension] = <ChannelDimension.FIRST: 'channels_first'> input_data_format: typing.Union[str, transformers.image_utils.ChannelDimension, NoneType] = None do_convert_rgb: typing.Optional[bool] = None do_pan_and_scan: typing.Optional[bool] = None pan_and_scan_min_crop_size: typing.Optional[int] = None pan_and_scan_max_num_crops: typing.Optional[int] = None pan_and_scan_min_ratio_to_activate: typing.Optional[float] = None )
引數
- images (
ImageInput) — 待預處理的影像。期望單個或批次影像，畫素值範圍為 0 到 255。如果傳入的影像畫素值在 0 到 1 之間，請設定do_rescale=False。 - do_resize (
bool, 可選，預設為self.do_resize) — 是否調整影像大小。 - size (
dict[str, int], 可選，預設為self.size) — 調整大小後圖像的尺寸。 - resample (
int, 可選，預設為self.resample) — 如果調整影像大小，則使用的重取樣濾波器。可以是列舉PILImageResampling之一。僅在do_resize設定為True時有效。 - do_rescale (
bool, 可選，預設為self.do_rescale) — 是否重新縮放影像。 - rescale_factor (
float, 可選，預設為self.rescale_factor) — 如果do_rescale設定為True，則用於重新縮放影像的比例因子。 - do_normalize (
bool, 可選，預設為self.do_normalize) — 是否對影像進行歸一化。 - image_mean (
float或list[float], 可選，預設為self.image_mean) — 用於歸一化的影像均值。僅在do_normalize設定為True時有效。 - image_std (
float或list[float], 可選，預設為self.image_std) — 用於歸一化的影像標準差。僅在do_normalize設定為True時有效。 - return_tensors (
str或TensorType, 可選) — 要返回的張量型別。可以是以下之一：- 未設定：返回
np.ndarray列表。 TensorType.TENSORFLOW或'tf'：返回tf.Tensor批次。TensorType.PYTORCH或'pt'：返回torch.Tensor批次。TensorType.NUMPY或'np'：返回np.ndarray批次。TensorType.JAX或'jax'：返回jax.numpy.ndarray批次。
- 未設定：返回
- data_format (
ChannelDimension或str, 可選, 預設為ChannelDimension.FIRST) — 輸出影像的通道維度格式。可以是以下之一："channels_first"或ChannelDimension.FIRST：影像格式為 (num_channels, height, width)。"channels_last"或ChannelDimension.LAST：影像格式為 (height, width, num_channels)。- 未設定：使用輸入影像的通道維度格式。
- input_data_format (
ChannelDimension或str, 可選) — 輸入影像的通道維度格式。如果未設定，則從輸入影像推斷通道維度格式。可以是以下之一："channels_first"或ChannelDimension.FIRST：影像格式為 (num_channels, height, width)。"channels_last"或ChannelDimension.LAST：影像格式為 (height, width, num_channels)。"none"或ChannelDimension.NONE：影像格式為 (height, width)。
- do_convert_rgb (
bool, 可選, 預設為self.do_convert_rgb) — 是否將影像轉換為RGB。 - do_pan_and_scan (
bool, 可選, 預設為self.do_convert_rgb) — 是否對影像應用pan_and_scan。 - pan_and_scan_min_crop_size (
int, 可選, 預設為self.pan_and_scan_min_crop_size) — 平移和掃描中每個裁剪的最小尺寸。 - pan_and_scan_max_num_crops (
int, 可選, 預設為self.pan_and_scan_max_num_crops) — 平移和掃描中每張影像的最大裁剪數量。 - pan_and_scan_min_ratio_to_activate (
float, 可選, 預設為self.pan_and_scan_min_ratio_to_activate) — 啟用平移和掃描的最小縱橫比。
預處理一張或一批影像。
Gemma3ImageProcessorFast
class transformers.Gemma3ImageProcessorFast
< 源 >( **kwargs: typing_extensions.Unpack[transformers.models.gemma3.image_processing_gemma3_fast.Gemma3FastImageProcessorKwargs] )
構造一個快速Gemma3影像處理器。
pan_and_scan_batched
< 源 >( images: torch.Tensor pan_and_scan_min_crop_size: int pan_and_scan_max_num_crops: int pan_and_scan_min_ratio_to_activate: float )
透過裁剪成較小的影像來平移和掃描影像，當縱橫比超過允許的最小比率時。
preprocess
< 源 >( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']] **kwargs: typing_extensions.Unpack[transformers.models.gemma3.image_processing_gemma3_fast.Gemma3FastImageProcessorKwargs] ) → <class 'transformers.image_processing_base.BatchFeature'>
引數
- 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_resize (
bool, 可選) — 是否調整影像大小。 - size (
dict[str, int], 可選) — 描述模型的最大輸入維度。 - default_to_square (
bool, 可選) — 如果 size 是整數，是否預設將影像調整為正方形。 - resample (
Union[PILImageResampling, F.InterpolationMode, NoneType]) — 如果調整影像大小，要使用的重取樣過濾器。可以是列舉PILImageResampling之一。僅當do_resize設定為True時有效。 - do_center_crop (
bool, 可選) — 是否中心裁剪影像。 - crop_size (
dict[str, int], 可選) — 應用center_crop後輸出影像的大小。 - do_rescale (
bool, 可選) — 是否重新縮放影像。 - rescale_factor (
Union[int, float, NoneType]) — 如果do_rescale設定為True，則按此重新縮放影像的因子。 - do_normalize (
bool, 可選) — 是否標準化影像。 - image_mean (
Union[float, list[float], NoneType]) — 用於標準化的影像均值。僅當do_normalize設定為True時有效。 - image_std (
Union[float, list[float], NoneType]) — 用於標準化的影像標準差。僅當do_normalize設定為True時有效。 - do_convert_rgb (
bool, 可選) — 是否將影像轉換為RGB。 - return_tensors (
Union[str, ~utils.generic.TensorType, NoneType]) — 如果設定為“pt”，則返回堆疊張量，否則返回張量列表。 - data_format (
~image_utils.ChannelDimension, 可選) — 僅支援ChannelDimension.FIRST。為與慢速處理器相容而新增。 - input_data_format (
Union[str, ~image_utils.ChannelDimension, NoneType]) — 輸入影像的通道維度格式。如果未設定，則從輸入影像推斷通道維度格式。可以是以下之一："channels_first"或ChannelDimension.FIRST：影像格式為 (num_channels, height, width)。"channels_last"或ChannelDimension.LAST：影像格式為 (height, width, num_channels)。"none"或ChannelDimension.NONE：影像格式為 (height, width)。
- device (
torch.device, 可選) — 用於處理影像的裝置。如果未設定，則從輸入影像推斷裝置。 - disable_grouping (
bool, 可選) — 是否停用按大小分組影像以單獨處理而不是批次處理。如果為 None，則如果影像在 CPU 上則設定為 True，否則設定為 False。此選擇基於經驗觀察，詳情請見：https://github.com/huggingface/transformers/pull/38157 - do_pan_and_scan (
bool, 可選) — 是否對影像應用pan_and_scan。 - pan_and_scan_min_crop_size (
int, 可選) — 平移和掃描中每個裁剪的最小尺寸。 - pan_and_scan_max_num_crops (
int, 可選) — 平移和掃描中每張影像的最大裁剪數量。 - pan_and_scan_min_ratio_to_activate (
float, 可選) — 啟用平移和掃描的最小縱橫比。
返回
<class 'transformers.image_processing_base.BatchFeature'>
- data (
dict) — 由 call 方法返回的列表/陣列/張量字典（“pixel_values”等）。 - tensor_type (
Union[None, str, TensorType], 可選) — 您可以在此處提供一個`tensor_type`，以便在初始化時將整數列表轉換為PyTorch/TensorFlow/Numpy張量。
Gemma3Processor
class transformers.Gemma3Processor
< 源 >( image_processor tokenizer chat_template = None image_seq_length: int = 256 **kwargs )
此方法將其所有引數轉發到 GemmaTokenizerFast 的 batch_decode()。有關更多資訊，請參閱此方法的文件字串。
Gemma3TextConfig
class transformers.Gemma3TextConfig
< 源 >( vocab_size = 262208 hidden_size = 2304 intermediate_size = 9216 num_hidden_layers = 26 num_attention_heads = 8 num_key_value_heads = 4 head_dim = 256 hidden_activation = 'gelu_pytorch_tanh' max_position_embeddings = 131072 initializer_range = 0.02 rms_norm_eps = 1e-06 use_cache = True pad_token_id = 0 eos_token_id = 1 bos_token_id = 2 tie_word_embeddings = True rope_theta = 1000000.0 attention_bias = False attention_dropout = 0.0 query_pre_attn_scalar = 256 sliding_window = 4096 layer_types = None final_logit_softcapping = None attn_logit_softcapping = None rope_scaling = None rope_local_base_freq = 10000.0 **kwargs )
引數
- vocab_size (
int, 可選, 預設為 262208) — Gemma3Text 模型的詞彙量。定義了呼叫 Gemma3TextModel 時可以透過inputs_ids表示的不同 token 的數量。 - hidden_size (
int, 可選, 預設為 2304) — 隱藏表示的維度。 - intermediate_size (
int, 可選, 預設為 9216) — MLP 表示的維度。 - num_hidden_layers (
int, 可選, 預設為 26) — Transformer 解碼器中的隱藏層數量。 - num_attention_heads (
int, 可選, 預設為 8) — Transformer 解碼器中每個注意力層的注意力頭數量。 - num_key_value_heads (
int, 可選, 預設為 4) — 這是應該用於實現分組查詢注意力的 key_value 頭數量。如果num_key_value_heads=num_attention_heads，模型將使用多頭注意力 (MHA)；如果num_key_value_heads=1，模型將使用多查詢注意力 (MQA)，否則使用 GQA。將多頭檢查點轉換為 GQA 檢查點時，每個分組鍵和值頭應透過對其組內的所有原始頭進行均值池化來構建。有關更多詳細資訊，請檢視 此論文。如果未指定，將預設為num_attention_heads。 - head_dim (
int, 可選, 預設為 256) — 注意力頭維度。 - hidden_activation (
str或function, 可選, 預設為"gelu_pytorch_tanh") — 解碼器中的非線性啟用函式（函式或字串）。如果未指定，將預設為"gelu_pytorch_tanh"。"gelu_pytorch_tanh"使用"gelu"啟用函式的近似值。 - max_position_embeddings (
int, 可選, 預設為 131072) — 此模型可能使用的最大序列長度。 - initializer_range (
float, 可選, 預設為 0.02) — 用於初始化所有權重矩陣的 truncated_normal_initializer 的標準差。 - rms_norm_eps (
float, 可選, 預設為 1e-06) — RMS 標準化層使用的 epsilon。 - use_cache (
bool, 可選, 預設為True) — 模型是否應返回最後一個鍵/值注意力（並非所有模型都使用）。僅當config.is_decoder=True時相關。 - pad_token_id (
int, 可選, 預設為 0) — 填充 token ID。 - eos_token_id (
int, 可選, 預設為 1) — 流結束標記 ID。 - bos_token_id (
int, 可選, 預設為 2) — 流開始標記 ID。 - tie_word_embeddings (
bool, 可選, 預設為True) — 是否繫結詞嵌入。 - rope_theta (
float, 可選, 預設為 1000000.0) — RoPE 嵌入的基本週期。 - attention_bias (
bool, 預設為False, 可選, 預設為False) — 在自注意力過程中，是否在查詢、鍵、值和輸出投影層中使用偏置。 - attention_dropout (
float, 可選, 預設為 0.0) — 注意力機率的 dropout 比率。 - query_pre_attn_scalar (
float, 可選, 預設為 256) — 用於注意力分數的縮放因子。 - sliding_window (
int, 可選, 預設為 4096) — 在 Gemma3Text 中，每隔一層使用滑動視窗注意力。這是滑動視窗的大小。 - layer_types (
list, 可選) — 每層的注意力模式。 - final_logit_softcapping (
float, 可選) — 對 logits 應用 tanh 軟上限時的縮放因子。 - attn_logit_softcapping (
float, 可選) — 對注意力分數應用 tanh 軟上限時的縮放因子。 - rope_scaling (
Dict, 可選) — 包含用於全域性注意力的 RoPE 嵌入的縮放配置的字典。注意：如果您應用新的 RoPE 型別並期望模型在更長的max_position_embeddings上工作，我們建議您相應地更新此值。預期內容：rope_type(str)：要使用的 RoPE 的子變體。可以是 ['default', 'linear', 'dynamic', 'yarn', 'longrope', 'llama3'] 之一，其中 'default' 是原始的 RoPE 實現。factor(float, 可選)：與除 'default' 之外的所有 RoPE 型別一起使用。應用於 RoPE 嵌入的縮放因子。在大多數縮放型別中，x 的factor將使模型能夠處理長度為 x * 原始最大預訓練長度的序列。original_max_position_embeddings(int, 可選)：與 'dynamic'、'longrope' 和 'llama3' 一起使用。預訓練期間使用的原始最大位置嵌入。attention_factor(float, 可選)：與 'yarn' 和 'longrope' 一起使用。應用於注意力計算的縮放因子。如果未指定，則預設為實現建議的值，使用factor欄位推斷建議值。beta_fast(float, 可選)：僅與 'yarn' 一起使用。設定線性斜坡函式中（僅）外推邊界的引數。如果未指定，則預設為 32。beta_slow(float, 可選)：僅與 'yarn' 一起使用。設定線性斜坡函式中（僅）插值邊界的引數。如果未指定，則預設為 1。short_factor(list[float], 可選)：僅與 'longrope' 一起使用。應用於短上下文（<original_max_position_embeddings）的縮放因子。必須是一個數字列表，其長度與隱藏大小除以注意力頭數再除以 2 相同。long_factor(list[float], 可選)：僅與 'longrope' 一起使用。應用於長上下文（<original_max_position_embeddings）的縮放因子。必須是一個數字列表，其長度與隱藏大小除以注意力頭數再除以 2 相同。low_freq_factor(float, 可選)：僅與 'llama3' 一起使用。應用於 RoPE 低頻分量的縮放因子。high_freq_factor(float, 可選)：僅與 'llama3' 一起使用。應用於 RoPE 高頻分量的縮放因子。 - rope_local_base_freq (float, 可選, 預設為 10000.0) — 用於區域性注意力的 RoPE 嵌入的基本週期。
這是用於儲存 Gemma3TextModel 配置的配置類。它用於根據指定引數例項化 Gemma3Text 模型，定義模型架構。使用預設值例項化配置將產生與 Gemma3Text-7B 類似的配置。例如 google/gemma3_text-7b 配置物件繼承自 PretrainedConfig，可用於控制模型輸出。有關更多資訊，請參閱 PretrainedConfig 的文件。
>>> from transformers import Gemma3TextModel, Gemma3TextConfig
>>> # Initializing a Gemma3Text gemma3_text-7b style configuration
>>> configuration = Gemma3TextConfig()
>>> # Initializing a model from the gemma3_text-7b style configuration
>>> model = Gemma3TextModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configGemma3Config
class transformers.Gemma3Config
< source >( text_config: typing.Union[transformers.models.gemma3.configuration_gemma3.Gemma3TextConfig, dict[str, typing.Any], NoneType] = None vision_config: typing.Union[transformers.models.siglip.configuration_siglip.SiglipVisionConfig, dict[str, typing.Any], NoneType] = None mm_tokens_per_image: int = 256 boi_token_index: int = 255999 eoi_token_index: int = 256000 image_token_index: int = 262144 initializer_range: float = 0.02 **kwargs )
引數
- text_config (
Union[Gemma3TextConfig, dict], 可選) — 文字骨幹的配置物件。 - vision_config (
Union[AutoConfig, dict], 可選) — 自定義視覺配置或字典。 - mm_tokens_per_image (
int, 可選, 預設為 256) — 每個影像嵌入的 token 數量。 - boi_token_index (
int, 可選, 預設為 255999) — 用於封裝影像提示的影像開始標記索引。 - eoi_token_index (
int, 可選, 預設為 256000) — 用於封裝影像提示的影像結束標記索引。 - image_token_index (
int, 可選, 預設為 262144) — 用於編碼影像提示的影像標記索引。 - initializer_range (
float, 可選, 預設為 0.02) — 用於初始化所有權重矩陣的 truncated_normal_initializer 的標準差。
這是用於儲存 Gemma3ForConditionalGeneration 配置的配置類。它用於根據指定引數例項化 Gemma3ForConditionalGeneration，定義模型架構。使用預設值例項化配置將產生與 PaliGemma-2B 類似的配置。
配置物件繼承自 PretrainedConfig，可用於控制模型輸出。有關更多資訊，請參閱 PretrainedConfig 的文件。
示例
>>> from transformers import Gemma3ForConditionalGeneration, Gemma3Config, SiglipVisionConfig, Gemma3TextConfig
>>> # Initializing a Siglip-like vision config
>>> vision_config = SiglipVisionConfig()
>>> # Initializing a Gemma3 Text config
>>> text_config = Gemma3TextConfig()
>>> # Initializing a Gemma3 gemma-3-4b style configuration
>>> configuration = Gemma3Config(vision_config, text_config)
>>> # Initializing a model from the gemma-3-4b style configuration
>>> model = Gemma3TextConfig(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configGemma3TextModel
class transformers.Gemma3TextModel
< source >( config: Gemma3TextConfig )
引數
- config (Gemma3TextConfig) — 包含模型所有引數的模型配置類。用配置檔案初始化不會載入與模型關聯的權重，只會載入配置。檢視 from_pretrained() 方法以載入模型權重。
裸 Gemma3 文字模型輸出原始隱藏狀態，沒有任何特定頭部。
此模型繼承自 PreTrainedModel。檢視超類文件以瞭解庫為其所有模型實現的通用方法（例如下載或儲存、調整輸入嵌入大小、修剪頭部等）。
此模型也是 PyTorch torch.nn.Module 的子類。將其作為常規 PyTorch 模組使用，並參考 PyTorch 文件以瞭解所有與一般用法和行為相關的事項。
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = None attention_mask: typing.Optional[torch.Tensor] = None position_ids: typing.Optional[torch.LongTensor] = None past_key_values: typing.Optional[transformers.cache_utils.Cache] = None inputs_embeds: typing.Optional[torch.FloatTensor] = None use_cache: typing.Optional[bool] = None output_attentions: typing.Optional[bool] = None output_hidden_states: typing.Optional[bool] = None cache_position: typing.Optional[torch.LongTensor] = None **flash_attn_kwargs: typing_extensions.Unpack[transformers.modeling_flash_attention_utils.FlashAttentionKwargs] ) → transformers.modeling_outputs.BaseModelOutputWithPast 或 tuple(torch.FloatTensor)
引數
- input_ids (
torch.LongTensor形狀為(batch_size, sequence_length), 可選) — 詞彙表中輸入序列 token 的索引。預設情況下，填充將被忽略。索引可以使用 AutoTokenizer 獲取。有關詳細資訊，請參閱 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。
- attention_mask (
torch.Tensor形狀為(batch_size, sequence_length), 可選) — 遮罩以避免對填充 token 索引執行注意力操作。遮罩值在[0, 1]中選擇：- 1 表示 未遮罩 的 token，
- 0 表示 已遮罩 的 token。
- position_ids (
torch.LongTensor形狀為(batch_size, sequence_length), 可選) — 每個輸入序列 token 在位置嵌入中的位置索引。選擇範圍為[0, config.n_positions - 1]。 - past_key_values (
~cache_utils.Cache, 可選) — 預計算的隱藏狀態（自注意力塊中的鍵和值以及交叉注意力塊中的鍵和值），可用於加速順序解碼。這通常包括模型在解碼上一階段返回的past_key_values，當use_cache=True或config.use_cache=True時。允許兩種格式：
- Cache 例項，請參閱我們的 kv 快取指南；
- 長度為
config.n_layers的tuple(torch.FloatTensor)元組，每個元組包含兩個形狀為(batch_size, num_heads, sequence_length, embed_size_per_head)的張量。這也被稱為舊版快取格式。
模型將輸出與輸入相同的快取格式。如果沒有傳入
past_key_values，將返回舊版快取格式。如果使用
past_key_values，使用者可以選擇僅輸入最後一個input_ids（那些沒有將其過去的鍵值狀態提供給此模型的）形狀為(batch_size, 1)，而不是所有input_ids形狀為(batch_size, sequence_length)。 - inputs_embeds (
torch.FloatTensor形狀為(batch_size, sequence_length, hidden_size), 可選) — 可選地，您可以選擇直接傳遞嵌入表示，而不是傳遞input_ids。如果您希望對如何將input_ids索引轉換為關聯向量具有比模型內部嵌入查詢矩陣更多的控制，這將很有用。 - use_cache (
bool, 可選) — 如果設定為True，則返回past_key_values鍵值狀態，可用於加速解碼（參見past_key_values）。 - output_attentions (
bool, 可選) — 是否返回所有注意力層的注意力張量。有關更多詳細資訊，請參閱返回張量中的attentions。 - output_hidden_states (
bool, 可選) — 是否返回所有層的隱藏狀態。有關更多詳細資訊，請參閱返回張量中的hidden_states。 - cache_position (
torch.LongTensor形狀為(sequence_length), 可選) — 表示輸入序列 token 在序列中位置的索引。與position_ids不同，此張量不受填充影響。它用於在正確位置更新快取並推斷完整的序列長度。
返回
transformers.modeling_outputs.BaseModelOutputWithPast 或 tuple(torch.FloatTensor)
一個 transformers.modeling_outputs.BaseModelOutputWithPast 或一個 torch.FloatTensor 元組（如果傳入 return_dict=False 或 config.return_dict=False），包含根據配置 (Gemma3Config) 和輸入的不同元素。
-
last_hidden_state (
torch.FloatTensor, 形狀為(batch_size, sequence_length, hidden_size)) — 模型最後一層輸出的隱藏狀態序列。如果使用了
past_key_values，則只輸出形狀為(batch_size, 1, hidden_size)的序列的最後一個隱藏狀態。 -
past_key_values (
Cache, 可選, 當傳入use_cache=True或config.use_cache=True時返回) — 它是一個 Cache 例項。有關更多詳細資訊，請參閱我們的 kv 快取指南。包含預計算的隱藏狀態（自注意力塊中的鍵和值，如果
config.is_encoder_decoder=True，則可選地包含交叉注意力塊中的鍵和值），可用於加速順序解碼（參見past_key_values輸入）。 -
hidden_states (
tuple(torch.FloatTensor), 可選, 當傳入output_hidden_states=True或config.output_hidden_states=True時返回) —torch.FloatTensor元組（如果模型有嵌入層，則一個用於嵌入層的輸出，+ 一個用於每個層的輸出），形狀為(batch_size, sequence_length, hidden_size)。模型在每個層輸出的隱藏狀態以及可選的初始嵌入輸出。
-
attentions (
tuple(torch.FloatTensor), 可選, 當傳入output_attentions=True或config.output_attentions=True時返回) —torch.FloatTensor元組（每個層一個），形狀為(batch_size, num_heads, sequence_length, sequence_length)。注意力 softmax 後的注意力權重，用於計算自注意力頭中的加權平均值。
Gemma3TextModel 的 forward 方法，覆蓋了 __call__ 特殊方法。
儘管前向傳遞的配方需要在此函式中定義，但之後應呼叫 Module 例項，而不是此函式，因為前者負責執行預處理和後處理步驟，而後者則默默地忽略它們。
Gemma3Model
class transformers.Gemma3Model
< source >( config: Gemma3Config )
引數
- config (Gemma3Config) — 包含模型所有引數的模型配置類。用配置檔案初始化不會載入與模型關聯的權重，只會載入配置。檢視 from_pretrained() 方法以載入模型權重。
基礎 Gemma3 模型，由視覺骨幹和不帶語言建模頭部的語言模型組成。
此模型繼承自 PreTrainedModel。檢視超類文件以瞭解庫為其所有模型實現的通用方法（例如下載或儲存、調整輸入嵌入大小、修剪頭部等）。
此模型也是 PyTorch torch.nn.Module 的子類。將其作為常規 PyTorch 模組使用，並參考 PyTorch 文件以瞭解所有與一般用法和行為相關的事項。
forward
< source >( input_ids: LongTensor = None pixel_values: FloatTensor = None attention_mask: typing.Optional[torch.Tensor] = None position_ids: typing.Optional[torch.LongTensor] = None past_key_values: typing.Union[list[torch.FloatTensor], transformers.cache_utils.Cache, NoneType] = None token_type_ids: typing.Optional[torch.LongTensor] = None cache_position: typing.Optional[torch.LongTensor] = None inputs_embeds: typing.Optional[torch.FloatTensor] = None labels: typing.Optional[torch.LongTensor] = None use_cache: typing.Optional[bool] = None output_attentions: typing.Optional[bool] = None output_hidden_states: typing.Optional[bool] = None return_dict: typing.Optional[bool] = None **lm_kwargs ) → transformers.models.gemma3.modeling_gemma3.Gemma3ModelOutputWithPast 或 tuple(torch.FloatTensor)
引數
- input_ids (
torch.LongTensor形狀為(batch_size, sequence_length)) — 詞彙表中輸入序列 token 的索引。預設情況下，填充將被忽略。索引可以使用 AutoTokenizer 獲取。有關詳細資訊，請參閱 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。
- pixel_values (
torch.FloatTensor形狀為(batch_size, num_channels, image_size, image_size)) — 對應於輸入影像的張量。畫素值可以使用{image_processor_class}獲取。有關詳細資訊，請參閱{image_processor_class}.__call__（{processor_class}使用{image_processor_class}處理影像）。 - attention_mask (
torch.Tensor形狀為(batch_size, sequence_length), 可選) — 遮罩以避免對填充 token 索引執行注意力操作。遮罩值在[0, 1]中選擇：- 1 表示 未遮罩 的 token，
- 0 表示 已遮罩 的 token。
- position_ids (
torch.LongTensor形狀為(batch_size, sequence_length), 可選) — 每個輸入序列 token 在位置嵌入中的位置索引。選擇範圍為[0, config.n_positions - 1]。 - past_key_values (
Union[list[torch.FloatTensor], ~cache_utils.Cache, NoneType]) — 預計算的隱藏狀態（自注意力塊中的鍵和值以及交叉注意力塊中的鍵和值），可用於加速順序解碼。這通常包括模型在解碼上一階段返回的past_key_values，當use_cache=True或config.use_cache=True時。允許兩種格式：
- Cache 例項，請參閱我們的 kv 快取指南；
- 長度為
config.n_layers的tuple(torch.FloatTensor)元組，每個元組包含兩個形狀為(batch_size, num_heads, sequence_length, embed_size_per_head)的張量。這也被稱為舊版快取格式。
模型將輸出與輸入相同的快取格式。如果沒有傳入
past_key_values，將返回舊版快取格式。如果使用
past_key_values，使用者可以選擇僅輸入最後一個input_ids（那些沒有將其過去的鍵值狀態提供給此模型的）形狀為(batch_size, 1)，而不是所有input_ids形狀為(batch_size, sequence_length)。 - token_type_ids (
torch.LongTensor形狀為(batch_size, sequence_length), 可選) — 分段 token 索引，指示輸入的第一個和第二個部分。索引選擇範圍為[0, 1]：- 0 對應於 句子 A token，
- 1 對應於 句子 B token。
- cache_position (
torch.LongTensor形狀為(sequence_length), 可選) — 表示輸入序列 token 在序列中位置的索引。與position_ids不同，此張量不受填充影響。它用於在正確位置更新快取並推斷完整的序列長度。 - inputs_embeds (
torch.FloatTensor形狀為(batch_size, sequence_length, hidden_size), 可選) — 可選地，您可以選擇直接傳遞嵌入表示，而不是傳遞input_ids。如果您希望對如何將input_ids索引轉換為關聯向量具有比模型內部嵌入查詢矩陣更多的控制，這將很有用。 - labels (
torch.LongTensor，形狀為(batch_size, sequence_length)，可選) — 用於計算遮蔽語言建模損失的標籤。索引應為[0, ..., config.text_config.vocab_size]或 -100 (參見input_ids文件字串)。索引設定為-100的標記將被忽略（遮蔽），損失僅針對標籤在[0, ..., config.text_config.vocab_size]中的標記計算。 - use_cache (
bool, 可選) — 如果設定為True，將返回past_key_values鍵值狀態，可用於加速解碼 (參見past_key_values)。 - output_attentions (
bool, 可選) — 是否返回所有注意力層的注意力張量。更多詳細資訊請參見返回張量下的attentions。 - output_hidden_states (
bool, 可選) — 是否返回所有層的隱藏狀態。更多詳細資訊請參見返回張量下的hidden_states。 - return_dict (
bool, 可選) — 是否返回 ModelOutput 而不是普通的元組。
返回
transformers.models.gemma3.modeling_gemma3.Gemma3ModelOutputWithPast 或 tuple(torch.FloatTensor)
一個 transformers.models.gemma3.modeling_gemma3.Gemma3ModelOutputWithPast 或一個 torch.FloatTensor 元組 (如果傳入 return_dict=False 或 config.return_dict=False)，其中包含根據配置 (Gemma3Config) 和輸入而變化的各種元素。
-
last_hidden_state (形狀為
(batch_size, sequence_length, hidden_size)的torch.FloatTensor, 可選) — 模型最後一層輸出的隱藏狀態序列。 -
past_key_values (
tuple(tuple(torch.FloatTensor)), 可選, 當傳入use_cache=True或config.use_cache=True時返回) — 長度為config.n_layers的tuple(torch.FloatTensor)元組，每個元組包含 2 個形狀為(batch_size, num_heads, sequence_length, embed_size_per_head)的張量)包含預計算的隱藏狀態（自注意力塊中的鍵和值），可用於（參見
past_key_values輸入）加速順序解碼。 -
hidden_states (
tuple[torch.FloatTensor, ...], 可選, 當傳入output_hidden_states=True或config.output_hidden_states=True時返回) — 形狀為(batch_size, sequence_length, hidden_size)的torch.FloatTensor元組 (如果模型有嵌入層，則為嵌入輸出一個，加上每個層的輸出一個)。模型在每個層輸出的隱藏狀態以及可選的初始嵌入輸出。
-
attentions (
tuple[torch.FloatTensor, ...], 可選, 當傳入output_attentions=True或config.output_attentions=True時返回) — 形狀為(batch_size, num_heads, sequence_length, sequence_length)的torch.FloatTensor元組 (每個層一個)。注意力 softmax 後的注意力權重，用於計算自注意力頭中的加權平均值。
-
image_hidden_states (
torch.FloatTensor, 可選) — 形狀為(batch_size, num_images, sequence_length, hidden_size)的torch.FloatTensor。由視覺編碼器生成並在投影最後一個隱藏狀態後的影像隱藏狀態。
Gemma3Model 的 forward 方法，重寫了 __call__ 特殊方法。
儘管前向傳遞的配方需要在此函式中定義，但之後應呼叫 Module 例項，而不是此函式，因為前者負責執行預處理和後處理步驟，而後者則默默地忽略它們。
示例
>>> from PIL import Image
>>> import requests
>>> from transformers import AutoProcessor, Gemma3ForConditionalGeneration
>>> model = Gemma3ForConditionalGeneration.from_pretrained("google/gemma32-3b-mix-224")
>>> processor = AutoProcessor.from_pretrained("google/gemma32-3b-mix-224")
>>> prompt = "Where is the cat standing?"
>>> url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"
>>> image = Image.open(requests.get(url, stream=True).raw)
>>> inputs = processor(images=image, text=prompt, return_tensors="pt")
>>> # Generate
>>> generate_ids = model.generate(**inputs,)
>>> processor.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)[0]
"Where is the cat standing?\nsnow"get_image_features
< 源 >( pixel_values: Tensor ) → image_features (torch.Tensor)
將視覺模型的最後一個隱藏狀態投影到語言模型空間中。
Gemma3ForCausalLM
類 transformers.Gemma3ForCausalLM
< 源 >( config: Gemma3TextConfig )
引數
- config (Gemma3TextConfig) — 包含模型所有引數的模型配置類。使用配置檔案初始化不會載入與模型相關的權重，只加載配置。請檢視 from_pretrained() 方法來載入模型權重。
用於因果語言建模的 Gemma3 模型。
此模型繼承自 PreTrainedModel。檢視超類文件以瞭解庫為其所有模型實現的通用方法（例如下載或儲存、調整輸入嵌入大小、修剪頭部等）。
此模型也是 PyTorch torch.nn.Module 的子類。將其作為常規 PyTorch 模組使用，並參考 PyTorch 文件以瞭解所有與一般用法和行為相關的事項。
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: typing.Optional[transformers.cache_utils.Cache] = None inputs_embeds: typing.Optional[torch.FloatTensor] = None labels: typing.Optional[torch.LongTensor] = None use_cache: typing.Optional[bool] = None output_attentions: typing.Optional[bool] = None output_hidden_states: typing.Optional[bool] = None cache_position: typing.Optional[torch.LongTensor] = None logits_to_keep: typing.Union[int, torch.Tensor] = 0 **loss_kwargs ) → transformers.modeling_outputs.CausalLMOutputWithPast 或 tuple(torch.FloatTensor)
引數
- input_ids (
torch.LongTensor，形狀為(batch_size, sequence_length), 可選) — 詞彙表中輸入序列標記的索引。預設情況下，填充將被忽略。索引可以使用 AutoTokenizer 獲取。有關詳細資訊，請參見 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。
- attention_mask (
torch.Tensor，形狀為(batch_size, sequence_length), 可選) — 掩碼，用於避免對填充標記索引執行注意力操作。掩碼值在[0, 1]中選擇：- 1 表示未被掩碼的標記，
- 0 表示被掩碼的標記。
- position_ids (
torch.LongTensor，形狀為(batch_size, sequence_length), 可選) — 每個輸入序列標記在位置嵌入中的位置索引。選擇範圍在[0, config.n_positions - 1]。 - past_key_values (
~cache_utils.Cache, 可選) — 預計算的隱藏狀態（自注意力塊和交叉注意力塊中的鍵和值），可用於加速順序解碼。這通常包括模型在解碼上一階段返回的past_key_values，當use_cache=True或config.use_cache=True時。允許兩種格式：
- Cache 例項，參見我們的 kv 快取指南；
- 長度為
config.n_layers的tuple(torch.FloatTensor)元組，每個元組包含 2 個形狀為(batch_size, num_heads, sequence_length, embed_size_per_head)的張量)。這也被稱為傳統快取格式。
模型將輸出與輸入相同的快取格式。如果未傳入
past_key_values，將返回傳統快取格式。如果使用
past_key_values，使用者可以選擇只輸入形狀為(batch_size, 1)的最後input_ids(那些沒有將其過去的鍵值狀態提供給此模型的輸入 ID)，而不是形狀為(batch_size, sequence_length)的所有input_ids。 - inputs_embeds (
torch.FloatTensor，形狀為(batch_size, sequence_length, hidden_size), 可選) — （可選）您可以選擇直接傳入嵌入表示，而不是傳入input_ids。如果您希望對如何將input_ids索引轉換為相關向量有更多控制，而不是使用模型的內部嵌入查詢矩陣，這將很有用。 - labels (
torch.LongTensor，形狀為(batch_size, sequence_length), 可選) — 用於計算遮蔽語言建模損失的標籤。索引應為[0, ..., config.vocab_size]或 -100 (參見input_ids文件字串)。索引設定為-100的標記將被忽略（遮蔽），損失僅針對標籤在[0, ..., config.vocab_size]中的標記計算。 - use_cache (
bool, 可選) — 如果設定為True，將返回past_key_values鍵值狀態，可用於加速解碼 (參見past_key_values)。 - output_attentions (
bool, 可選) — 是否返回所有注意力層的注意力張量。更多詳細資訊請參見返回張量下的attentions。 - output_hidden_states (
bool, 可選) — 是否返回所有層的隱藏狀態。更多詳細資訊請參見返回張量下的hidden_states。 - cache_position (
torch.LongTensor，形狀為(sequence_length), 可選) — 指示輸入序列標記在序列中位置的索引。與position_ids不同，此張量不受填充影響。它用於在正確位置更新快取並推斷完整的序列長度。 - logits_to_keep (
Union[int, torch.Tensor], 預設為0) — 如果是int，則計算最後logits_to_keep個標記的 logits。如果是0，則計算所有input_ids的 logits（特殊情況）。生成時只需要最後一個標記的 logits，並且僅計算該標記的 logits 可以節省記憶體，這對於長序列或大詞彙量來說非常重要。如果是torch.Tensor，則必須是 1D，對應於序列長度維度中要保留的索引。這在使用打包張量格式（批次和序列長度的單個維度）時很有用。
返回
transformers.modeling_outputs.CausalLMOutputWithPast 或 tuple(torch.FloatTensor)
一個 transformers.modeling_outputs.CausalLMOutputWithPast 或一個 torch.FloatTensor 元組 (如果傳入 return_dict=False 或 config.return_dict=False)，其中包含根據配置 (Gemma3Config) 和輸入而變化的各種元素。
-
loss (
torch.FloatTensor形狀為(1,)，可選，當提供labels時返回) — 語言建模損失（用於下一個 token 預測）。 -
logits (形狀為
(batch_size, sequence_length, config.vocab_size)的torch.FloatTensor) — 語言建模頭部的預測分數（SoftMax 之前的每個詞彙標記的分數）。 -
past_key_values (
Cache, 可選, 當傳入use_cache=True或config.use_cache=True時返回) — 它是一個 Cache 例項。有關更多詳細資訊，請參閱我們的 kv 快取指南。包含預計算的隱藏狀態（自注意力塊中的鍵和值），可用於（參見
past_key_values輸入）加速順序解碼。 -
hidden_states (
tuple(torch.FloatTensor), 可選, 當傳入output_hidden_states=True或config.output_hidden_states=True時返回) —torch.FloatTensor元組（如果模型有嵌入層，則一個用於嵌入層的輸出，+ 一個用於每個層的輸出），形狀為(batch_size, sequence_length, hidden_size)。模型在每個層輸出的隱藏狀態以及可選的初始嵌入輸出。
-
attentions (
tuple(torch.FloatTensor), 可選, 當傳入output_attentions=True或config.output_attentions=True時返回) —torch.FloatTensor元組（每個層一個），形狀為(batch_size, num_heads, sequence_length, sequence_length)。注意力 softmax 後的注意力權重，用於計算自注意力頭中的加權平均值。
Gemma3ForCausalLM 的 forward 方法，重寫了 __call__ 特殊方法。
儘管前向傳遞的配方需要在此函式中定義，但之後應呼叫 Module 例項，而不是此函式，因為前者負責執行預處理和後處理步驟，而後者則默默地忽略它們。
示例
>>> from transformers import AutoTokenizer, Gemma3ForCausalLM
>>> model = Gemma3ForCausalLM.from_pretrained("google/gemma-2-9b")
>>> tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-9b")
>>> 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?"Gemma3ForConditionalGeneration
類 transformers.Gemma3ForConditionalGeneration
< 源 >( config: Gemma3Config )
引數
- config (Gemma3Config) — 包含模型所有引數的模型配置類。使用配置檔案初始化不會載入與模型相關的權重，只加載配置。請檢視 from_pretrained() 方法來載入模型權重。
Gemma3 基礎模型，由視覺主幹和無語言建模頭的語言模型組成。
此模型繼承自 PreTrainedModel。檢視超類文件以瞭解庫為其所有模型實現的通用方法（例如下載或儲存、調整輸入嵌入大小、修剪頭部等）。
此模型也是 PyTorch torch.nn.Module 的子類。將其作為常規 PyTorch 模組使用，並參考 PyTorch 文件以瞭解所有與一般用法和行為相關的事項。
forward
< 源 >( input_ids: LongTensor = None pixel_values: FloatTensor = None attention_mask: typing.Optional[torch.Tensor] = None position_ids: typing.Optional[torch.LongTensor] = None past_key_values: typing.Union[list[torch.FloatTensor], transformers.cache_utils.Cache, NoneType] = None token_type_ids: typing.Optional[torch.LongTensor] = None cache_position: typing.Optional[torch.LongTensor] = None inputs_embeds: typing.Optional[torch.FloatTensor] = None labels: typing.Optional[torch.LongTensor] = None use_cache: typing.Optional[bool] = None output_attentions: typing.Optional[bool] = None output_hidden_states: typing.Optional[bool] = None return_dict: typing.Optional[bool] = None logits_to_keep: typing.Union[int, torch.Tensor] = 0 **lm_kwargs ) → transformers.models.gemma3.modeling_gemma3.Gemma3CausalLMOutputWithPast 或 tuple(torch.FloatTensor)
引數
- input_ids (
torch.LongTensor，形狀為(batch_size, sequence_length)) — 詞彙表中輸入序列標記的索引。預設情況下，填充將被忽略。索引可以使用 AutoTokenizer 獲取。有關詳細資訊，請參見 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。
- pixel_values (
torch.FloatTensor，形狀為(batch_size, num_channels, image_size, image_size)) — 對應於輸入影像的張量。畫素值可以使用{image_processor_class}獲取。有關詳細資訊，請參見{image_processor_class}.__call__({processor_class}使用{image_processor_class}處理影像)。 - attention_mask (
torch.Tensor，形狀為(batch_size, sequence_length), 可選) — 掩碼，用於避免對填充標記索引執行注意力操作。掩碼值在[0, 1]中選擇：- 1 表示未被掩碼的標記，
- 0 表示被掩碼的標記。
- position_ids (
torch.LongTensor，形狀為(batch_size, sequence_length), 可選) — 每個輸入序列標記在位置嵌入中的位置索引。選擇範圍在[0, config.n_positions - 1]。 - past_key_values (
Union[list[torch.FloatTensor], ~cache_utils.Cache, NoneType]) — 預計算的隱藏狀態（自注意力塊和交叉注意力塊中的鍵和值），可用於加速順序解碼。這通常包括模型在解碼上一階段返回的past_key_values，當use_cache=True或config.use_cache=True時。允許兩種格式：
- Cache 例項，參見我們的 kv 快取指南；
- 長度為
config.n_layers的tuple(torch.FloatTensor)元組，每個元組包含 2 個形狀為(batch_size, num_heads, sequence_length, embed_size_per_head)的張量)。這也被稱為傳統快取格式。
模型將輸出與輸入相同的快取格式。如果未傳入
past_key_values，將返回傳統快取格式。如果使用
past_key_values，使用者可以選擇只輸入形狀為(batch_size, 1)的最後input_ids(那些沒有將其過去的鍵值狀態提供給此模型的輸入 ID)，而不是形狀為(batch_size, sequence_length)的所有input_ids。 - token_type_ids (
torch.LongTensor，形狀為(batch_size, sequence_length), 可選) — 段標記索引，用於指示輸入的第一個和第二個部分。索引在[0, 1]中選擇：- 0 對應於 句子 A 標記，
- 1 對應於 句子 B 標記。
- cache_position (
torch.LongTensor，形狀為(sequence_length), 可選) — 指示輸入序列標記在序列中位置的索引。與position_ids不同，此張量不受填充影響。它用於在正確位置更新快取並推斷完整的序列長度。 - inputs_embeds (
torch.FloatTensor，形狀為(batch_size, sequence_length, hidden_size), 可選) — （可選）您可以選擇直接傳入嵌入表示，而不是傳入input_ids。如果您希望對如何將input_ids索引轉換為相關向量有更多控制，而不是使用模型的內部嵌入查詢矩陣，這將很有用。 - labels (
torch.LongTensor，形狀為(batch_size, sequence_length), 可選) — 用於計算遮蔽語言建模損失的標籤。索引應為[0, ..., config.text_config.vocab_size]或 -100 (參見input_ids文件字串)。索引設定為-100的標記將被忽略（遮蔽），損失僅針對標籤在[0, ..., config.text_config.vocab_size]中的標記計算。 - use_cache (
bool, 可選) — 如果設定為True，將返回past_key_values鍵值狀態，可用於加速解碼 (參見past_key_values)。 - output_attentions (
bool, 可選) — 是否返回所有注意力層的注意力張量。更多詳細資訊請參見返回張量下的attentions。 - output_hidden_states (
bool, 可選) — 是否返回所有層的隱藏狀態。更多詳細資訊請參見返回張量下的hidden_states。 - return_dict (
bool, 可選) — 是否返回 ModelOutput 而不是普通的元組。 - logits_to_keep (
Union[int, torch.Tensor], 預設為0) — 如果是int，則計算最後logits_to_keep個標記的 logits。如果是0，則計算所有input_ids的 logits（特殊情況）。生成時只需要最後一個標記的 logits，並且僅計算該標記的 logits 可以節省記憶體，這對於長序列或大詞彙量來說非常重要。如果是torch.Tensor，則必須是 1D，對應於序列長度維度中要保留的索引。這在使用打包張量格式（批次和序列長度的單個維度）時很有用。
返回
transformers.models.gemma3.modeling_gemma3.Gemma3CausalLMOutputWithPast 或 tuple(torch.FloatTensor)
一個 transformers.models.gemma3.modeling_gemma3.Gemma3CausalLMOutputWithPast 或一個 torch.FloatTensor 元組 (如果傳入 return_dict=False 或 config.return_dict=False)，其中包含根據配置 (Gemma3Config) 和輸入而變化的各種元素。
-
loss (
torch.FloatTensor形狀為(1,)，可選，當提供labels時返回) — 語言建模損失（用於下一個 token 預測）。 -
logits (形狀為
(batch_size, sequence_length, config.text_config.vocab_size)的torch.FloatTensor) — 語言建模頭的預測分數（SoftMax 之前的每個詞彙標記的分數）。 -
past_key_values (
tuple(tuple(torch.FloatTensor)), 可選, 當傳入use_cache=True或config.use_cache=True時返回) — 長度為config.n_layers的tuple(torch.FloatTensor)元組，每個元組包含 2 個形狀為(batch_size, num_heads, sequence_length, embed_size_per_head)的張量)包含預計算的隱藏狀態（自注意力塊中的鍵和值），可用於（參見
past_key_values輸入）加速順序解碼。 -
hidden_states (
tuple[torch.FloatTensor], 可選, 當傳入output_hidden_states=True或config.output_hidden_states=True時返回) —torch.FloatTensor的元組（如果模型有嵌入層，則包含嵌入層的輸出，加上每一層的輸出），形狀為(batch_size, sequence_length, hidden_size)。模型在每個層輸出的隱藏狀態以及可選的初始嵌入輸出。
-
attentions (
tuple[torch.FloatTensor], 可選, 當傳入output_attentions=True或config.output_attentions=True時返回) —torch.FloatTensor的元組（每一層一個），形狀為(batch_size, num_heads, sequence_length, sequence_length)。注意力 softmax 後的注意力權重，用於計算自注意力頭中的加權平均值。
-
image_hidden_states (
torch.FloatTensor, 可選) — 形狀為(batch_size, num_images, sequence_length, hidden_size)的torch.FloatTensor。由視覺編碼器在投影最後隱藏狀態後生成的模型 image_hidden_states。
Gemma3ForConditionalGeneration 的 forward 方法，會覆蓋 __call__ 特殊方法。
儘管前向傳遞的配方需要在此函式中定義，但之後應呼叫 Module 例項，而不是此函式，因為前者負責執行預處理和後處理步驟，而後者則默默地忽略它們。
示例
>>> from PIL import Image
>>> import requests
>>> from transformers import AutoProcessor, Gemma3ForConditionalGeneration
>>> model = Gemma3ForConditionalGeneration.from_pretrained("google/gemma-3-4b-it")
>>> processor = AutoProcessor.from_pretrained("google/gemma-3-4b-it")
>>> messages = [
... {
... "role": "system",
... "content": [
... {"type": "text", "text": "You are a helpful assistant."}
... ]
... },
... {
... "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, clean_up_tokenization_spaces=False)[0]
"user\nYou are a helpful assistant.\n\n\n\n\n\nWhere is the cat standing?\nmodel\nBased on the image, the cat is standing in a snowy area, likely outdoors. It appears to"