Transformers 文档

Gemma 3

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

PyTorch SDPA

Gemma 3

Gemma 3 是一个多模态模型,具有预训练和指令微调变体,提供 1B、13B 和 27B 参数。其架构与之前的 Gemma 版本基本相同。主要区别在于每隔一个全局自注意力层交替使用 5 个局部滑动窗口自注意力层,支持 128K 令牌的更长上下文长度,以及一个可以“平移和扫描”高分辨率图像以防止信息在高分辨率图像或非正方形宽高比图像中丢失的 SigLip 编码器。

指令微调变体通过知识蒸馏和强化学习进行后训练。

您可以在 Gemma 3 发布中找到所有原始 Gemma 3 检查点。

点击右侧边栏中的 Gemma 3 模型,查看更多 Gemma 应用于不同视觉和语言任务的示例。

以下示例演示如何使用 PipelineAutoModel 类根据图像生成文本。

流水线
自动模型
Transformers CLI
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 (intfloat, 可选,默认为 1/255) — 如果重新缩放图像,则使用的比例因子。可在 preprocess 方法中通过 rescale_factor 覆盖。
  • do_normalize (bool, 可选,默认为 True) — 是否通过指定的均值和标准差对图像进行归一化。可在 preprocess 方法中通过 do_normalize 覆盖。
  • image_mean (floatlist[float], 可选,默认为 [0.5, 0.5, 0.5]) — 如果对图像进行归一化,则使用的均值。这是一个浮点数或浮点数列表,其长度与图像中的通道数相同。可在 preprocess 方法中通过 image_mean 参数覆盖。
  • image_std (floatlist[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 (strChannelDimension, 可选) — 图像的通道维度格式。如果未提供,将与输入图像的格式相同。
  • input_data_format (ChannelDimensionstr, 可选) — 输入图像的通道维度格式。如果未提供,将自动推断。

平移和扫描图像,当宽高比超过允许的最小比率时,将其裁剪成较小的图像。

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 (floatlist[float], 可选,默认为 self.image_mean) — 用于归一化的图像均值。仅在 do_normalize 设置为 True 时有效。
  • image_std (floatlist[float], 可选,默认为 self.image_std) — 用于归一化的图像标准差。仅在 do_normalize 设置为 True 时有效。
  • return_tensors (strTensorType, 可选) — 要返回的张量类型。可以是以下之一:
    • 未设置:返回 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 (ChannelDimensionstr, 可选, 默认为 ChannelDimension.FIRST) — 输出图像的通道维度格式。可以是以下之一:
    • "channels_first"ChannelDimension.FIRST:图像格式为 (num_channels, height, width)。
    • "channels_last"ChannelDimension.LAST:图像格式为 (height, width, num_channels)。
    • 未设置:使用输入图像的通道维度格式。
  • input_data_format (ChannelDimensionstr, 可选) — 输入图像的通道维度格式。如果未设置,则从输入图像推断通道维度格式。可以是以下之一:
    • "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 )

参数

  • image (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 )

batch_decode

< >

( *args **kwargs )

此方法将其所有参数转发到 GemmaTokenizerFast 的 batch_decode()。有关更多信息,请参阅此方法的文档字符串。

decode

< >

( *args **kwargs )

此方法将其所有参数转发给 GemmaTokenizerFast 的 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 (strfunction, 可选, 默认为 "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

< >

( 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 类似的配置。

例如 google/gemma-3-4b

配置对象继承自 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

< >

( 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 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.BaseModelOutputWithPasttuple(torch.FloatTensor)

参数

  • input_ids (torch.LongTensor 形状为 (batch_size, sequence_length), 可选) — 词汇表中输入序列 token 的索引。默认情况下,填充将被忽略。

    索引可以使用 AutoTokenizer 获取。有关详细信息,请参阅 PreTrainedTokenizer.encode()PreTrainedTokenizer.call()

    什么是输入 ID?

  • 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]

    什么是位置 ID?

  • past_key_values (~cache_utils.Cache, 可选) — 预计算的隐藏状态(自注意力块中的键和值以及交叉注意力块中的键和值),可用于加速顺序解码。这通常包括模型在解码上一阶段返回的 past_key_values,当 use_cache=Trueconfig.use_cache=True 时。

    允许两种格式:

    • Cache 实例,请参阅我们的 kv 缓存指南
    • 长度为 config.n_layerstuple(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.BaseModelOutputWithPasttuple(torch.FloatTensor)

一个 transformers.modeling_outputs.BaseModelOutputWithPast 或一个 torch.FloatTensor 元组(如果传入 return_dict=Falseconfig.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=Trueconfig.use_cache=True 时返回) — 它是一个 Cache 实例。有关更多详细信息,请参阅我们的 kv 缓存指南

    包含预计算的隐藏状态(自注意力块中的键和值,如果 config.is_encoder_decoder=True,则可选地包含交叉注意力块中的键和值),可用于加速顺序解码(参见 past_key_values 输入)。

  • hidden_states (tuple(torch.FloatTensor), 可选, 当传入 output_hidden_states=Trueconfig.output_hidden_states=True 时返回) — torch.FloatTensor 元组(如果模型有嵌入层,则一个用于嵌入层的输出,+ 一个用于每个层的输出),形状为 (batch_size, sequence_length, hidden_size)

    模型在每个层输出的隐藏状态以及可选的初始嵌入输出。

  • attentions (tuple(torch.FloatTensor), 可选, 当传入 output_attentions=Trueconfig.output_attentions=True 时返回) — torch.FloatTensor 元组(每个层一个),形状为 (batch_size, num_heads, sequence_length, sequence_length)

    注意力 softmax 后的注意力权重,用于计算自注意力头中的加权平均值。

Gemma3TextModel 的 forward 方法,覆盖了 __call__ 特殊方法。

尽管前向传递的配方需要在此函数中定义,但之后应调用 Module 实例,而不是此函数,因为前者负责运行预处理和后处理步骤,而后者则默默地忽略它们。

Gemma3Model

class transformers.Gemma3Model

< >

( 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 **lm_kwargs ) transformers.models.gemma3.modeling_gemma3.Gemma3ModelOutputWithPasttuple(torch.FloatTensor)

参数

  • input_ids (torch.LongTensor 形状为 (batch_size, sequence_length)) — 词汇表中输入序列 token 的索引。默认情况下,填充将被忽略。

    索引可以使用 AutoTokenizer 获取。有关详细信息,请参阅 PreTrainedTokenizer.encode()PreTrainedTokenizer.call()

    什么是输入 ID?

  • 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]

    什么是位置 ID?

  • past_key_values (Union[list[torch.FloatTensor], ~cache_utils.Cache, NoneType]) — 预计算的隐藏状态(自注意力块中的键和值以及交叉注意力块中的键和值),可用于加速顺序解码。这通常包括模型在解码上一阶段返回的 past_key_values,当 use_cache=Trueconfig.use_cache=True 时。

    允许两种格式:

    • Cache 实例,请参阅我们的 kv 缓存指南
    • 长度为 config.n_layerstuple(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。

    什么是 token 类型 ID?

  • 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.Gemma3ModelOutputWithPasttuple(torch.FloatTensor)

一个 transformers.models.gemma3.modeling_gemma3.Gemma3ModelOutputWithPast 或一个 torch.FloatTensor 元组 (如果传入 return_dict=Falseconfig.return_dict=False),其中包含根据配置 (Gemma3Config) 和输入而变化的各种元素。

  • last_hidden_state (形状为 (batch_size, sequence_length, hidden_size)torch.FloatTensor, 可选) — 模型最后一层输出的隐藏状态序列。

  • past_key_values (tuple(tuple(torch.FloatTensor)), 可选, 当传入 use_cache=Trueconfig.use_cache=True 时返回) — 长度为 config.n_layerstuple(torch.FloatTensor) 元组,每个元组包含 2 个形状为 (batch_size, num_heads, sequence_length, embed_size_per_head) 的张量)

    包含预计算的隐藏状态(自注意力块中的键和值),可用于(参见 past_key_values 输入)加速顺序解码。

  • hidden_states (tuple[torch.FloatTensor, ...], 可选, 当传入 output_hidden_states=Trueconfig.output_hidden_states=True 时返回) — 形状为 (batch_size, sequence_length, hidden_size)torch.FloatTensor 元组 (如果模型有嵌入层,则为嵌入输出一个,加上每个层的输出一个)。

    模型在每个层输出的隐藏状态以及可选的初始嵌入输出。

  • attentions (tuple[torch.FloatTensor, ...], 可选, 当传入 output_attentions=Trueconfig.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)

参数

  • pixel_values (torch.FloatTensor],形状为 (batch_size, channels, height, width)) — 对应于输入图像的张量。

返回

image_features (torch.Tensor)

形状为 (num_images, image_length, embed_dim) 的图像特征张量。

将视觉模型的最后一个隐藏状态投影到语言模型空间中。

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.CausalLMOutputWithPasttuple(torch.FloatTensor)

参数

  • input_ids (torch.LongTensor,形状为 (batch_size, sequence_length), 可选) — 词汇表中输入序列标记的索引。默认情况下,填充将被忽略。

    索引可以使用 AutoTokenizer 获取。有关详细信息,请参见 PreTrainedTokenizer.encode()PreTrainedTokenizer.call()

    什么是 input ID?

  • attention_mask (torch.Tensor,形状为 (batch_size, sequence_length), 可选) — 掩码,用于避免对填充标记索引执行注意力操作。掩码值在 [0, 1] 中选择:

    • 1 表示未被掩码的标记,
    • 0 表示被掩码的标记。

    什么是 attention mask?

  • position_ids (torch.LongTensor,形状为 (batch_size, sequence_length), 可选) — 每个输入序列标记在位置嵌入中的位置索引。选择范围在 [0, config.n_positions - 1]

    什么是 position ID?

  • past_key_values (~cache_utils.Cache, 可选) — 预计算的隐藏状态(自注意力块和交叉注意力块中的键和值),可用于加速顺序解码。这通常包括模型在解码上一阶段返回的 past_key_values,当 use_cache=Trueconfig.use_cache=True 时。

    允许两种格式:

    • Cache 实例,参见我们的 kv 缓存指南
    • 长度为 config.n_layerstuple(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.CausalLMOutputWithPasttuple(torch.FloatTensor)

一个 transformers.modeling_outputs.CausalLMOutputWithPast 或一个 torch.FloatTensor 元组 (如果传入 return_dict=Falseconfig.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=Trueconfig.use_cache=True 时返回) — 它是一个 Cache 实例。有关更多详细信息,请参阅我们的 kv 缓存指南

    包含预计算的隐藏状态(自注意力块中的键和值),可用于(参见 past_key_values 输入)加速顺序解码。

  • hidden_states (tuple(torch.FloatTensor), 可选, 当传入 output_hidden_states=Trueconfig.output_hidden_states=True 时返回) — torch.FloatTensor 元组(如果模型有嵌入层,则一个用于嵌入层的输出,+ 一个用于每个层的输出),形状为 (batch_size, sequence_length, hidden_size)

    模型在每个层输出的隐藏状态以及可选的初始嵌入输出。

  • attentions (tuple(torch.FloatTensor), 可选, 当传入 output_attentions=Trueconfig.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.Gemma3CausalLMOutputWithPasttuple(torch.FloatTensor)

参数

  • input_ids (torch.LongTensor,形状为 (batch_size, sequence_length)) — 词汇表中输入序列标记的索引。默认情况下,填充将被忽略。

    索引可以使用 AutoTokenizer 获取。有关详细信息,请参见 PreTrainedTokenizer.encode()PreTrainedTokenizer.call()

    什么是 input ID?

  • 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 表示被掩码的标记。

    什么是 attention mask?

  • position_ids (torch.LongTensor,形状为 (batch_size, sequence_length), 可选) — 每个输入序列标记在位置嵌入中的位置索引。选择范围在 [0, config.n_positions - 1]

    什么是 position ID?

  • past_key_values (Union[list[torch.FloatTensor], ~cache_utils.Cache, NoneType]) — 预计算的隐藏状态(自注意力块和交叉注意力块中的键和值),可用于加速顺序解码。这通常包括模型在解码上一阶段返回的 past_key_values,当 use_cache=Trueconfig.use_cache=True 时。

    允许两种格式:

    • Cache 实例,参见我们的 kv 缓存指南
    • 长度为 config.n_layerstuple(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 标记。

    什么是 token type ID?

  • 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.Gemma3CausalLMOutputWithPasttuple(torch.FloatTensor)

一个 transformers.models.gemma3.modeling_gemma3.Gemma3CausalLMOutputWithPast 或一个 torch.FloatTensor 元组 (如果传入 return_dict=Falseconfig.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=Trueconfig.use_cache=True 时返回) — 长度为 config.n_layerstuple(torch.FloatTensor) 元组,每个元组包含 2 个形状为 (batch_size, num_heads, sequence_length, embed_size_per_head) 的张量)

    包含预计算的隐藏状态(自注意力块中的键和值),可用于(参见 past_key_values 输入)加速顺序解码。

  • hidden_states (tuple[torch.FloatTensor], 可选, 当传入 output_hidden_states=Trueconfig.output_hidden_states=True 时返回) — torch.FloatTensor 的元组(如果模型有嵌入层,则包含嵌入层的输出,加上每一层的输出),形状为 (batch_size, sequence_length, hidden_size)

    模型在每个层输出的隐藏状态以及可选的初始嵌入输出。

  • attentions (tuple[torch.FloatTensor], 可选, 当传入 output_attentions=Trueconfig.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"
< > 在 GitHub 上更新