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.config
Gemma3Config
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.config
Gemma3TextModel
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"