Transformers documentation
Gemma3n
该模型于 2024-11-12 在 HF papers 上发布，并于 2025-06-26 贡献至 Hugging Face Transformers。
Gemma3n
概述
Gemma3n 是一个多模态模型，提供预训练和指令微调版本，规模有 E4B 和 E2B 两种。虽然该模型的语言模型架构与之前的 Gemma 版本共享了大部分组件，但其中包含许多新增特性，包括 Alternating Updates（AltUp）、Learned Augmented Residual Layer（LAuReL）、MatFormer、Per-Layer Embeddings（PLE）、Activation Sparsity with Statistical Top-k 以及 KV cache 共享。其语言模型采用了与 Gemma 3 类似的注意力模式，即每 4 层局部滑动窗口自注意力层之后交替使用一层全局自注意力层，最大上下文长度为 32k 个 token。Gemma 3n 引入了 MobileNet v5 作为视觉编码器，默认分辨率为 768x768 像素，并新增了一个基于 Universal Speech Model（USM）架构训练而成的音频编码器。
经过指令微调的变体通过知识蒸馏和强化学习进行了后训练。
您可以在 Gemma 3n 发布中找到所有原始的 Gemma 3n 检查点。
点击右侧边栏中的 Gemma 3n 模型，以查看更多将 Gemma 应用于不同视觉、音频和语言任务的示例。
在 from_pretrained() 中设置
use_kernels=True，即可用 Hub 上的优化内核替换受支持的层。有关详细信息，请参阅 加载内核。
以下示例演示了如何使用 Pipeline 或 AutoModel 类基于图像生成文本。
from transformers import pipeline
pipeline = pipeline(
task="image-text-to-text",
model="google/gemma-3n-e4b",
device=0,
)
pipeline(
"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg",
text="<start_of_image> What is shown in this image?"
)from transformers import AutoProcessor, Gemma3nForConditionalGeneration
model = Gemma3nForConditionalGeneration.from_pretrained(
"google/gemma-3n-e4b-it",
device_map="auto",
attn_implementation="sdpa"
)
processor = AutoProcessor.from_pretrained(
"google/gemma-3n-e4b-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(model.device)
output = model.generate(**inputs, max_new_tokens=50, cache_implementation="static")
print(processor.decode(output[0], skip_special_tokens=True))备注
使用 Gemma3nForConditionalGeneration 处理图像、音频和文本、图像和文本、图像和音频、音频和文本、仅图像以及仅音频输入。
Gemma 3n 支持每个输入包含多张图片，但请确保在将图片传递给处理器之前已正确进行批处理。每个批次应为一个包含一张或多张图片的列表。
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?"}, ] }, ]传递给处理器的文本应在需要插入图像的位置包含
<image_soft_token>标记。Gemma 3n 每个输入最多接受一个目标音频片段，但可以在少样本提示中提供多个音频片段，例如。
传递给处理器的文本中，应在需要插入音频片段的位置包含
<audio_soft_token>标记。处理器拥有自己的 apply_chat_template() 方法，用于将聊天消息转换为模型输入。
Gemma3nAudioFeatureExtractor
类 transformers.Gemma3nAudioFeatureExtractor
< source >( feature_size: int = 128sampling_rate: int = 16000padding_value: float = 0.0return_attention_mask: bool = Trueframe_length_ms: float = 32.0hop_length_ms: float = 10.0min_frequency: float = 125.0max_frequency: float = 7600.0preemphasis: float = 0.97preemphasis_htk_flavor: bool = Truefft_overdrive: bool = Truedither: float = 0.0input_scale_factor: float = 1.0mel_floor: float = 1e-05per_bin_mean: collections.abc.Sequence[float] | None = Noneper_bin_stddev: collections.abc.Sequence[float] | None = None**kwargs )
参数
- feature_size (
int，可选，默认为 128) — 提取特征的维度。 - sampling_rate (
int，可选，默认为 16000) — 音频文件应被数字化时的采样率，以赫兹 (Hz) 为单位。 - padding_value (
float，可选，默认为 0.0) — 用于填充音频的填充值。该值应对应静音。 - return_attention_mask (
bool，可选，默认为True) — 是否返回生成 MEL 频谱图时使用的注意力掩码。 - frame_length_ms (
float，可选，默认值为 32.0) — 帧的长度，单位为毫秒。 - hop_length_ms (
float，可选，默认为 10.0) — 用于获取梅尔频率系数的 STFT 的重叠窗口长度。 - min_frequency (
float，可选，默认值为 125.0) — Mel 滤波器组的最小频率（单位：Hz）。 - max_frequency (
float，可选，默认值为 7600.0) — Mel 滤波器组的最大频率（单位：Hz）。 - preemphasis (
float，可选，默认为 0.97) — 预加重系数。 - preemphasis_htk_flavor (
bool，可选，默认为True) — 是否使用 HTK 风格的预加重。 - fft_overdrive (
bool，可选，默认为True) — 是否使用 FFT 过驱动。 - dither (
float, 可选，默认为 0.0) — 添加抖动。也就是说，为每一帧添加少量高斯噪声。 例如，使用 0.0001 可添加以 0.0 为中心、标准差为 0.0001 的正态分布抖动（假设 raw_speech 的范围为 [-1,+1]）。 值 0.0 表示不添加抖动。 抖动的作用类似于spectrogram(mel_floor=...)。当信号中存在 VAD 截断时，它会降低具有硬零区段的信号的高 log_mel_fbank 值。 - input_scale_factor (
float，可选，默认为 1.0) — 应用于输入波形的缩放因子。 - mel_floor (
float，可选，默认为 1e-05) — 梅尔频谱图的最小值，用于避免 log(0)。 - per_bin_mean (
Optional[Sequence[float]]，可选) — 用于分箱归一化的均值。 - per_bin_stddev (
Optional[Sequence[float]], 可选) — 用于按 bin 归一化的标准差值。
用于通用语音模型的音频特征提取器 https://huggingface.co/papers/2303.01037。
Gemma3nProcessor
class transformers.Gemma3nProcessor
< source >( feature_extractorimage_processortokenizerchat_template = Noneaudio_seq_length: int = 188image_seq_length: int = 256**kwargs )
参数
- feature_extractor（
Gemma3nAudioFeatureExtractor）— 特征提取器是必需的输入。 - image_processor (
SiglipImageProcessor) — 图像处理器是必需的输入。 - tokenizer (
GemmaTokenizer) — 分词器是必需的输入。 - chat_template (
str) — 一个 Jinja 模板，用于将聊天中的消息列表转换为可分词的字符串。 - audio_seq_length (
int，可选，默认值为 188) — 将添加到文本提示中的音频软标记数量 - image_seq_length (
int，可选，默认为 256) — 应添加的图像软标记数量
构造一个 Gemma3nProcessor，它将特征提取器、图像处理器和分词器封装为单一处理器。
Gemma3nProcessor 提供了 Gemma3nAudioFeatureExtractor、SiglipImageProcessor 和 GemmaTokenizer 的所有功能。有关更多信息，请参阅 ~Gemma3nAudioFeatureExtractor、~SiglipImageProcessor 和 ~GemmaTokenizer。
__call__
< source >( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonetext: str | list[str] | list[list[str]] = Noneaudio: numpy.ndarray | list[float] | list[numpy.ndarray] | list[list[float]] | None = None**kwargs: *<class 'transformers.models.gemma3n.processing_gemma3n.Gemma3nProcessorKwargs'> ) → ~feature_extraction_utils.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。 - text (
Union[str, list[str], list[list[str]]]，可选) — 要编码的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果传入预分词输入，请设置is_split_into_words=True，以避免与批量输入产生歧义。 - audio (
Union[numpy.ndarray, list[float], list[numpy.ndarray], list[list[float]]], 可选) — 要处理的音频或音频批次。每个音频可以是 NumPy 数组或 PyTorch 张量。 如果为 NumPy 数组/PyTorch 张量，每个音频的形状应为 (C, T)，其中 C 为通道数，T 为音频的采样长度。 - return_tensors (
str或 TensorType, 可选) — 如果设置，将返回特定框架的张量。可接受的值为：'pt'：返回 PyTorchtorch.Tensor对象。'np'：返回 NumPynp.ndarray对象。
- **kwargs (ProcessingKwargs，可选) — 每种模态（文本、图像、视频、音频）的额外处理选项。模型特定参数已在上方列出；有关支持参数的完整列表，请参阅 TypedDict 类。
返回值
~feature_extraction_utils.BatchFeature
- data (
dict，可选) — 由 call/pad 方法返回的列表/数组/张量字典（例如 ‘input_values’、‘attention_mask’ 等）。 - tensor_type (
Union[None, str, TensorType], 可选) — 您可以在此处指定 tensor_type，以便在初始化时将 PyTorch/Numpy 张量中的整数列表进行转换。 - skip_tensor_conversion（
list[str]或set[str]，可选）——即使指定了tensor_type，也不应转换为张量的键的列表或集合。
Gemma3nTextConfig
class transformers.Gemma3nTextConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevocab_size: int = 262400hidden_size: int = 2048intermediate_size: int | list[int] = 16384num_hidden_layers: int = 35num_attention_heads: int = 8num_key_value_heads: int = 2head_dim: int = 256hidden_activation: str = 'gelu_pytorch_tanh'max_position_embeddings: int = 32768initializer_range: float = 0.02rms_norm_eps: float = 1e-06use_cache: bool = Truepad_token_id: int | None = 0eos_token_id: int | list[int] | None = 1bos_token_id: int | None = 2tie_word_embeddings: bool = Truerope_parameters: dict | None = Noneattention_bias: bool = Falseattention_dropout: int | float | None = 0.0sliding_window: int = 512layer_types: list[str] | None = Nonefinal_logit_softcapping: float = 30.0vocab_size_per_layer_input: int = 262144hidden_size_per_layer_input: int = 256altup_active_idx: int = 0altup_coef_clip: float = 120.0altup_correct_scale: bool = Truealtup_num_inputs: int = 4num_kv_shared_layers: int = 15laurel_rank: int = 64activation_sparsity_pattern: float | list[float] | None = None )
参数
- vocab_size (
int，可选，默认为262400) — 模型的词汇表大小。定义了input_ids可以表示的不同 token 数量。 - hidden_size (
int，可选，默认为2048) — 隐藏表示的维度。 - intermediate_size (
Union[int, list[int]]，可选，默认为16384) — MLP 表示的维度。 - num_hidden_layers (
int，可选，默认为35) — Transformer 解码器中的隐藏层数量。 - num_attention_heads (
int，可选，默认为8) — Transformer 解码器中每个注意力层的注意力头数量。 - num_key_value_heads (
int, 可选，默认为2) — 这是用于实现 Grouped Query Attention 的 key_value 头数。如果num_key_value_heads=num_attention_heads，模型将使用 Multi Head Attention (MHA)；如果num_key_value_heads=1，模型将使用 Multi Query Attention (MQA)；否则将使用 GQA。在将多头检查点转换为 GQA 检查点时，每个组的 key 和 value 头应通过对该组内所有原始头进行平均池化来构建。更多详情请参阅 这篇论文。如果未指定，则默认为num_attention_heads。 - head_dim (
int，可选，默认为256) — 注意力头维度。如果为 None，则默认为 hidden_size // num_attention_heads - hidden_activation (
str, 可选, 默认为gelu_pytorch_tanh) — 解码器中的非线性激活函数（函数或字符串）。例如，"gelu"、"relu"、"silu"等。 - max_position_embeddings (
int，可选，默认为32768) — 该模型可能使用的最大序列长度。 - 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 (
Union[int, list[int]]，可选，默认为1) — 词汇表中用于表示流结束（end-of-stream）的 token id。 - bos_token_id (
int，可选，默认为2) — 词汇表中用于表示流起始的 Token id。 - tie_word_embeddings (
bool，可选，默认为True) — 是否根据模型的tied_weights_keys映射来绑定权重嵌入。 - rope_parameters (
dict, 可选) — 包含 RoPE 嵌入配置参数的字典。该字典应包含rope_theta的值，并且如果希望使用 RoPE 处理更长的max_position_embeddings，则可选地包含用于缩放的参数。 - attention_bias (
bool，可选，默认为False) — 在自注意力机制中，是否在 query、key、value 和 output 投影层中使用偏置。 - attention_dropout (
Union[int, float]，可选，默认为0.0) — 注意力概率的 dropout 比率。 - sliding_window (
int，可选，默认为512) — 滑动窗口注意力的窗口大小。如果为None，则不应用滑动窗口。 - layer_types (
list[str], 可选) — 一个列表，用于显式地将每个层索引映射到其层类型。如果未提供，将根据 config 值自动生成。 - final_logit_softcapping (
float, 可选，默认为30.0) — 在计算概率分布之前应用于最终 logits 的软截断值。Logits 会按tanh(logit / cap) * cap进行缩放。 - vocab_size_per_layer_input (
int，可选，默认为 262144) — 用于增强标准嵌入的逐层文本嵌入的词汇表大小。 - hidden_size_per_layer_input (
int，可选，默认为 256) — 逐层嵌入的隐藏表示维度。 - altup_active_idx (
int，可选，默认为 0) — AltUp 用于计算额外预测或修正当前活跃预测的预测索引。 - altup_coef_clip (
float, 可选，默认为 120.0) — AltUp 预测或校正系数权重的最大幅度。 - altup_correct_scale (
bool，可选，默认为True) — 如果为 True，则在altup_active_idx处对修正后的预测应用AltUp.correct_output_scale。 - altup_num_inputs (
int，可选，默认为 4) — 给定输入序列时，AltUp 应生成的预测数量。 - num_kv_shared_layers (
int, 可选，默认为 15) — 共享 KV 缓存值的层数。在前向传播过程中，模型中最后num_kv_shared_layers层会“共享”KV 值，即该范围内的每个本地层和全局层分别使用进入该范围之前最后一个本地层或全局层计算出的 KV 缓存值。该值应为注意力模式大小的整数倍（参见layer_types参数）。 - laurel_rank (
int，可选，默认值为 64) — Learned Augmented Residual Layer 中线性投影的中间维度大小。 - activation_sparsity_pattern (
Sequence[float], 可选) — 用于提取指定层 top-k 激活值的稀疏因子。提供的 Sequence 必须为模型中的每一层显式指定一个稀疏值。默认情况下，前 10 层为稀疏层，稀疏因子为 0.95，其余层为稠密层。
这是用于存储 Gemma3nModel 配置的类。它根据指定的参数实例化 Gemma3N 模型，并定义模型架构。使用默认值实例化配置将得到与 google/gemma-3n-E4B 类似的配置。
配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。
>>> from transformers import Gemma3nTextModel, Gemma3nTextConfig
>>> # Initializing a Gemma3nText gemma3n_text-E4B style configuration
>>> configuration = Gemma3nTextConfig()
>>> # Initializing a model from the gemma3n_text-E4B style configuration
>>> model = Gemma3nTextModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configGemma3nVisionConfig
class transformers.Gemma3nVisionConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonearchitecture: str = 'mobilenetv5_300m_enc'initializer_range: float = 0.02do_pooling: bool = Falsemodel_args: dict | None = Nonehidden_size: int = 2048vocab_size: int = 128vocab_offset: int = 262144rms_norm_eps: float = 1e-06 )
参数
- architecture (
str，可选，默认为"resnet50") — 要加载的 timm 架构。 - initializer_range (
float，可选，默认为0.02) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。 - do_pooling (
bool，可选，默认为True) — 是否对TimmWrapperModel中的 last_hidden_state 执行池化。 - model_args (
dict[str, Any], 可选) — 传递给timm.create_model函数的额外关键字参数。例如，对于timm/vit_base_patch32_clip_448.laion2b_ft_in12k_in1k，使用model_args={"depth": 3}可以创建一个包含 3 个 block 的模型。默认值为None。 - hidden_size (
int，可选，默认为2048) — 隐藏表示的维度。 - vocab_size (
int, 可选，默认为128) — 模型的词汇表大小。定义了input_ids可以表示的不同 token 数量。 - vocab_offset (
int，可选，默认值为 262144) —Gemma3nMultimodalEmbedder所嵌入的 token id 在分词器词表中的索引，与Gemma3nMultimodalEmbedder.embedding表中从 0 开始的索引之间的偏移量。 - rms_norm_eps (
float，可选，默认为1e-06) — RMS 归一化层使用的 epsilon 值。
这是用于存储 Gemma3nModel 配置的类。它根据指定的参数实例化 Gemma3N 模型，并定义模型架构。使用默认值实例化配置将得到与 google/gemma-3n-E4B 类似的配置。
配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。
示例：
>>> from transformers import Gemma3nVisionConfig, TimmWrapper
>>> # Initializing a TimmWrapper gemma3n_vision-E4B-style configuration
>>> configuration = Gemma3nVisionConfig()
>>> # Initializing a gemma3n_vision-E4B-style TimmWrapper from the configuration
>>> model = TimmWrapper(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configGemma3nAudioConfig
class transformers.Gemma3nAudioConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevocab_size: int = 128vocab_offset: int = 262272input_feat_size: int = 128hidden_size: int = 1536rms_norm_eps: float = 1e-06gradient_clipping: float = 10000000000.0conf_attention_chunk_size: int = 12conf_attention_context_left: int = 13conf_attention_context_right: int = 0conf_attention_logit_cap: float = 50.0conf_num_attention_heads: int = 8conf_num_hidden_layers: int = 12conf_conv_kernel_size: int = 5conf_reduction_factor: int = 4conf_residual_weight: float = 0.5sscp_conv_channel_size: list[int] | tuple[int, int] = (128, 32)sscp_conv_group_norm_eps: float = 0.001sscp_conv_kernel_size: list | tuple[tuple[int, int], tuple[int, int]] = ((3, 3), (3, 3))sscp_conv_stride_size: list | tuple[tuple[int, int], tuple[int, int]] = ((2, 2), (2, 2)) )
参数
- vocab_size (
int, 可选，默认为128) — 模型的词汇表大小。定义了input_ids可以表示的不同 token 数量。 - vocab_offset (
int，可选，默认值为 262272) —Gemma3nMultimodalEmbedder嵌入的 token id 在分词器词表中的索引，与Gemma3nMultimodalEmbedder.embedding表中从 0 开始的索引之间的偏移量。 - input_feat_size (
int，可选，默认为 128) — 每个梅尔频谱帧中的通道数。 - hidden_size (
int，可选，默认为1536) — 隐藏表示的维度。 - rms_norm_eps (
float，可选，默认为1e-06) — RMS 归一化层使用的 epsilon 值。 - gradient_clipping (
float，可选，默认为 10000000000.0) — 用于稳定极大梯度值的裁剪阈值。 - conf_attention_chunk_size (
int, 可选，默认为 12) — 通用语音模型中 Conformer（“conf”）部分内局部注意力处理的子序列大小。 - conf_attention_context_left (
int, 可选，默认为 13) — Universal Speech Model 中 Conformer（“conf”）部分内局部注意力的左侧上下文大小。 - conf_attention_context_right (
int, 可选，默认为 0) — 通用语音模型中 Conformer（“conf”）部分内局部注意力的右侧上下文大小。 - conf_attention_logit_cap (
float，可选，默认值为 50.0) — 在 Universal Speech Model 的 Conformer（“conf”）部分中，局部注意力期间应用的 Logit 上限。 - conf_num_attention_heads (
int, 可选，默认为 8) — 通用语音模型中 Conformer（“conf”）部分内局部注意力机制的注意力头数量。 - conf_num_hidden_layers (
int，可选，默认为 12) — 通用语音模型中 Conformer（“conf”）部分内使用局部注意力的层数。 - conf_conv_kernel_size (
int，可选，默认为 5) — 通用语音模型中 Conformer（“conf”）部分内 Conformer 模块的卷积核大小。 - conf_reduction_factor (
int，可选，默认为 4) — 在 Universal Speech Model 的 Conformer（“conf”）部分中，Conformer 块所使用的缩减因子。 - conf_residual_weight (
float，可选，默认值为 0.5) — 通用语音模型中 Conformer（“conf”）部分内部的残差连接权重。 - sscp_conv_channel_size (
tuple(int, int)，可选，默认为(128, 32)) — 通用语音模型中子采样卷积投影（“sscp”）部分中第一层和第二层卷积层的通道大小。 - sscp_conv_group_norm_eps (
float, 可选，默认值为 0.001) — 在 Universal Speech Model 的 Sub-sample Convolution Projection（“sscp”）部分中，子采样卷积投影的组归一化所使用的 Epsilon。 - sscp_conv_kernel_size (
tuple(tuple(int, int), tuple(int, int))，可选，默认为((3, 3), (3, 3))) — Universal Speech Model 中 Sub-sample Convolution Projection（“sscp”）部分内，下采样卷积投影中两个卷积层的核大小。核大小以每个层的高度和宽度的元组形式指定，其中高度对应时间维度，宽度对应频率维度。 - sscp_conv_stride_size (
tuple(tuple(int, int), tuple(int, int))，可选，默认为((2, 2), (2, 2))) — Universal Speech Model 中 Sub-sample Convolution Projection（“sscp”）部分内子采样卷积投影中两个卷积层的步长大小。步长大小以每个层的高度和宽度元组形式指定，其中高度对应时间维度，宽度对应频率维度。
这是用于存储 Gemma3nModel 配置的类。它根据指定的参数实例化 Gemma3N 模型，并定义模型架构。使用默认值实例化配置将得到与 google/gemma-3n-E4B 类似的配置。
配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。
示例：
>>> from transformers import Gemma3nAudioConfig, Gemma3nAudioEncoder
>>> # Initializing a Gemma3nAudioEncoder gemma3n_audio-E4B-style configuration
>>> configuration = Gemma3nAudioConfig()
>>> # Initializing a model from the gemma3n_audio-E4B style configuration
>>> model = Gemma3nAudioEncoder(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configGemma3nConfig
class transformers.Gemma3nConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonetext_config: transformers.models.gemma3n.configuration_gemma3n.Gemma3nTextConfig | dict[str, typing.Any] | None = Nonevision_config: transformers.models.gemma3n.configuration_gemma3n.Gemma3nVisionConfig | dict[str, typing.Any] | None = Noneaudio_config: transformers.models.gemma3n.configuration_gemma3n.Gemma3nAudioConfig | dict[str, typing.Any] | None = Noneaudio_soft_tokens_per_image: int | None = 188vision_soft_tokens_per_image: int | None = 256boi_token_id: int | None = 255999eoi_token_id: int | None = 262144image_token_id: int | None = 262145boa_token_id: int | None = 256000eoa_token_id: int | None = 262272audio_token_id: int | None = 262273initializer_range: float | None = 0.02tie_word_embeddings: bool | None = Trueuse_cache: bool = True )
参数
- text_config (
Union[~models.gemma3n.configuration_gemma3n.Gemma3nTextConfig, dict[str, Any]], 可选) — 文本骨干网络的配置对象或字典。 - vision_config (
Union[~models.gemma3n.configuration_gemma3n.Gemma3nVisionConfig, dict[str, Any]]，可选) — 视觉骨干网络的配置对象或字典。 - audio_config (
Union[~models.gemma3n.configuration_gemma3n.Gemma3nAudioConfig, dict[str, Any]]，可选) — 音频骨干网络的配置对象或字典。 - audio_soft_tokens_per_image（
int，可选，默认值为 188）—— 每个音频片段的软标记数量。 - vision_soft_tokens_per_image (
int，可选，默认值为 256) — 每张图片的软标记数量。 - boi_token_id (
int，可选，默认为 255999) — 用于包裹图像提示的图像起始（begin-of-image）标记索引。 - eoi_token_id (
int, 可选，默认为 262144) — 用于包裹图像提示的图像结束标记索引。 - image_token_id (
int，可选，默认为262145) — 用作输入图像占位符的图像 token 索引。 - boa_token_id (
int，可选，默认为 256000) — 用于包裹音频提示的音频起始（begin-of-audio）标记索引。 - eoa_token_id (
int, 可选，默认为 262272) — 用于包裹音频提示的音频结束标记索引。 - audio_token_id (
int，可选，默认为262273) — 用作输入音频占位符的音频 token 索引。 - initializer_range (
float，可选，默认为0.02) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。 - tie_word_embeddings (
bool，可选，默认为True) — 是否根据模型的tied_weights_keys映射来绑定权重嵌入。 - use_cache (
bool，可选，默认为True) — 模型是否应返回最后一次键/值注意力（并非所有模型都使用）。仅当config.is_decoder=True或模型为仅解码器生成式模型时相关。
这是用于存储 Gemma3nModel 配置的类。它根据指定的参数实例化 Gemma3N 模型，并定义模型架构。使用默认值实例化配置将得到与 google/gemma-3n-E4B 类似的配置。
配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。
示例：
>>> from transformers import Gemma3nForConditionalGeneration, Gemma3nConfig, Gemma3nTextConfig
>>> # Initializing a MobileNet vision config, which is loaded from TIMM
>>> vision_config = Gemma3nVisionConfig()
>>> # Initializing a Gemma3n Audio config
>>> audio_config = Gemma3nAudioConfig()
>>> # Initializing a Gemma3n Text config
>>> text_config = Gemma3nTextConfig()
>>> # Initializing a Gemma3n gemma-3-4b style configuration
>>> configuration = Gemma3nConfig(text_config, vision_config, audio_config)
>>> # Initializing a model from the gemma-3-4b style configuration
>>> model = Gemma3nTextConfig(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configGemma3nTextModel
class transformers.Gemma3nTextModel
< source >( config: Gemma3nTextConfig )
参数
- config (Gemma3nTextConfig) — 模型配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
不带语言建模头的基础 Gemma 3n 语言模型。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneper_layer_inputs: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPast or tuple(torch.Tensor)
参数
- input_ids (
torch.LongTensor形状为(batch_size, sequence_length), ，可选) — 输入序列中各 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 AutoTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。
- per_layer_inputs (
torch.Tensor，可选，默认为 None) — 预计算的逐层嵌入。如果为 None，则会在提供 input_ids 时从 input_ids 推导得出。 - attention_mask (
torch.Tensor形状为(batch_size, sequence_length), ，可选) — 用于避免对填充 token 索引执行注意力机制的掩码。掩码值取自[0, 1]:- 1 表示未被屏蔽的 token，
- 对于被掩码的 token，值为 0。
- 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 cache 指南。 如果未传入
past_key_values，则默认会初始化 DynamicCache。模型将输出与输入相同的缓存格式。
如果使用了
past_key_values，用户应仅输入未处理的input_ids（即未向该模型提供其过去键值状态的那些），其形状为(batch_size, unprocessed_length)，而不是形状为(batch_size, sequence_length)的全部input_ids。 - inputs_embeds（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor，可选） — 可选地，您可以选择直接传入嵌入表示，而不是传入input_ids。如果您希望对input_ids索引如何转换为相应向量拥有比模型内部嵌入查找矩阵更多的控制权，这将非常有用。 - use_cache (
bool，可选) — 如果设置为True，则会返回past_key_values键值状态，可用于加速解码（参见past_key_values）。
返回值
BaseModelOutputWithPast 或 tuple(torch.Tensor)
一个 BaseModelOutputWithPast 或 torch.Tensor 元组（如果传入了 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（Gemma3nConfig）和输入。
Gemma3nTextModel 的 forward 方法重写了 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义，但之后应调用
Module实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。
last_hidden_state（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor）— 模型最后一层输出的隐藏状态序列。如果使用了
past_key_values，则仅输出形状为(batch_size, 1, hidden_size)的序列的最后一个隐藏状态。past_key_values（
Cache，可选，在传入use_cache=True或config.use_cache=True时返回）—— 它是一个 Cache 实例。更多详情，请参阅我们的 kv cache 指南。包含预计算的隐藏状态（自注意力块中的键和值，以及如果
config.is_encoder_decoder=True则还包括交叉注意力块中的键和值），可用于（参见past_key_values输入）加速顺序解码。hidden_states (
tuple(torch.Tensor)，可选，当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
attentions (
tuple(torch.Tensor)，可选，当传入output_attentions=True或config.output_attentions=True时返回) — 一个torch.Tensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力权重，即经过注意力 softmax 之后的权重，用于在自注意力头中计算加权平均值。
Gemma3nModel
class transformers.Gemma3nModel
< source >( config: Gemma3nConfig )
参数
- config (Gemma3nConfig) — 模型配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
基础 Gemma 3n 模型，包含视觉骨干网络、音频骨干网络以及不带语言建模头的语言模型。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Nonepixel_values: typing.Optional[torch.Tensor] = Noneinput_features: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneinput_features_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Nonetoken_type_ids: typing.Optional[torch.LongTensor] = Noneinputs_embeds: typing.Optional[torch.Tensor] = Noneper_layer_inputs: typing.Optional[torch.Tensor] = Noneuse_cache: bool | None = Nonemm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> )
input_features_mask (torch.Tensor，形状为 (batch_size, sequence_length)，可选)：
input_features 的注意力掩码，其中非零值标记有效的音频帧。
per_layer_inputs (torch.Tensor，可选)：
预计算的逐层输入文本嵌入，形状为 (batch_size, sequence_length, num_hidden_layers, hidden_size_per_layer_input)。如果提供该参数，将直接使用这些嵌入，而不是在文本模型中通过 get_per_layer_inputs() 从 input_ids 计算得到。如果调用 forward 时使用 inputs_embeds 而非 input_ids，则应预先计算这些嵌入并随 inputs_embeds 一起传入，否则逐层嵌入中的 token 身份分量将被省略。
示例：
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> from transformers import AutoProcessor, Gemma3nForConditionalGeneration
>>> model = Gemma3nForConditionalGeneration.from_pretrained("google/gemma3n2-3b-mix-224")
>>> processor = AutoProcessor.from_pretrained("google/gemma3n2-3b-mix-224")
>>> prompt = "Where is the cat standing?"
>>> url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"
>>> with httpx.stream("GET", url) as response:
... image = Image.open(BytesIO(response.read()))
>>> 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
< source >( pixel_values: Tensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)
参数
- pixel_values (
torch.Tensor，形状为(batch_size, num_channels, image_size, image_size)) — 与输入图像对应的张量。可以使用 SiglipImageProcessor 获取像素值。有关详细信息，请参阅 SiglipImageProcessor.call()（Gemma3nProcessor 使用 SiglipImageProcessor 处理图像）。
返回值
BaseModelOutputWithPooling 或 tuple(torch.Tensor)
一个 BaseModelOutputWithPooling 或 torch.Tensor 元组（如果传入了 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（Gemma3nConfig）和输入。
将视觉模型的最后一个隐藏状态投影到语言模型空间。
last_hidden_state（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor）— 模型最后一层输出的隐藏状态序列。pooler_output (
torch.Tensor，形状为(batch_size, hidden_size)) — 序列中第一个 token（分类 token）的最后一层隐藏状态，经过用于辅助预训练任务的层进一步处理后得到。例如，对于 BERT 系列模型，这返回的是分类 token 经过线性层和 tanh 激活函数处理后的结果。线性层的权重在预训练期间通过下一句预测（分类）目标进行训练。hidden_states (
tuple(torch.Tensor)，可选，当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
attentions (
tuple(torch.Tensor)，可选，当传入output_attentions=True或config.output_attentions=True时返回) — 一个torch.Tensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力权重，即经过注意力 softmax 之后的权重，用于在自注意力头中计算加权平均值。
get_audio_features
< source >( input_features: Tensorinput_features_mask: Tensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Gemma3nAudioEncoderModelOutput or tuple(torch.Tensor)
参数
- input_features (
torch.Tensor，形状为(num_images, seq_length, num_features)) — 与输入音频对应的张量。 - input_features_mask (
torch.Tensor，形状为(num_images, seq_length)) — 输入音频的注意力掩码。
返回值
Gemma3nAudioEncoderModelOutput 或 tuple(torch.Tensor)
Gemma3nAudioEncoderModelOutput 或 torch.Tensor 元组（当传入 return_dict=False 或 config.return_dict=False 时），其包含的元素取决于配置（Gemma3nConfig）和输入。
将音频编码器的最后一个隐藏状态投影到语言模型空间。
last_hidden_state（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor）— 模型最后一层输出的隐藏状态序列。pooler_output (
torch.Tensor，形状为(batch_size, hidden_size)) — 序列中第一个 token（分类 token）的最后一层隐藏状态，经过用于辅助预训练任务的层进一步处理后得到。例如，对于 BERT 系列模型，这返回的是分类 token 经过线性层和 tanh 激活函数处理后的结果。线性层的权重在预训练期间通过下一句预测（分类）目标进行训练。hidden_states (
tuple(torch.Tensor)，可选，当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
attentions (
tuple(torch.Tensor)，可选，当传入output_attentions=True或config.output_attentions=True时返回) — 一个torch.Tensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力权重，即经过注意力 softmax 之后的权重，用于在自注意力头中计算加权平均值。
audio_mel_mask（
torch.BoolTensor，可选）— 形状为(batch_size, num_frames)的 torch.BoolTensor
Gemma3nForCausalLM
类 transformers.Gemma3nForCausalLM
< source >( config: Gemma3nTextConfig )
参数
- config (Gemma3nTextConfig) — 模型配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
带有语言建模头的基础 Gemma 3n 语言模型。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = Nonelogits_to_keep: typing.Union[int, torch.Tensor] = 0**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → CausalLMOutputWithPast or tuple(torch.Tensor)
参数
- input_ids (
torch.LongTensor形状为(batch_size, sequence_length), ，可选) — 输入序列中各 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 AutoTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。
- attention_mask (
torch.Tensor形状为(batch_size, sequence_length), ，可选) — 用于避免对填充 token 索引执行注意力机制的掩码。掩码值取自[0, 1]:- 1 表示未被屏蔽的 token，
- 对于被掩码的 token，值为 0。
- 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 cache 指南。 如果未传入
past_key_values，则默认会初始化 DynamicCache。模型将输出与输入相同的缓存格式。
如果使用了
past_key_values，用户应仅输入未处理的input_ids（即未向该模型提供其过去键值状态的那些），其形状为(batch_size, unprocessed_length)，而不是形状为(batch_size, sequence_length)的全部input_ids。 - inputs_embeds（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor，可选） — 可选地，您可以选择直接传入嵌入表示，而不是传入input_ids。如果您希望对input_ids索引如何转换为相应向量拥有比模型内部嵌入查找矩阵更多的控制权，这将非常有用。 - labels (
torch.LongTensor，形状为(batch_size, sequence_length)，可选) — 用于计算掩码语言建模损失的标签。索引值应在[0, ..., config.vocab_size]范围内，或为 -100（参见input_ids的文档字符串）。索引值设为-100的 token 将被忽略（即被掩码），损失仅针对标签位于[0, ..., config.vocab_size]范围内的 token 进行计算。 - use_cache (
bool，可选) — 如果设置为True，则会返回past_key_values键值状态，可用于加速解码（参见past_key_values）。 - logits_to_keep (
Union[int, torch.Tensor], 可选，默认为0) — 如果为int，则计算最后logits_to_keep个 token 的 logits。如果为0，则计算所有input_ids的 logits（特殊情况）。生成过程只需要最后一个 token 的 logits，仅针对该 token 进行计算可以节省内存，对于长序列或大词汇量而言，这种节省相当显著。 如果为torch.Tensor，则必须是一维张量，对应于序列长度维度中需要保留的索引。 这在使用打包张量格式（将批次和序列长度合并为单一维度）时非常有用。
返回值
CausalLMOutputWithPast 或 tuple(torch.Tensor)
一个 CausalLMOutputWithPast 或 torch.Tensor 元组（如果传入了 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（Gemma3nConfig）和输入。
Gemma3nForCausalLM 的 forward 方法重写了 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义，但之后应调用
Module实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。
loss (
torch.Tensor，形状为(1,)，可选，当提供labels时返回) — 语言建模损失（用于下一个 token 预测）。logits（形状为
(batch_size, sequence_length, config.vocab_size)的torch.Tensor）— 语言建模头的预测分数（SoftMax 之前每个词汇表 token 的分数）。past_key_values（
Cache，可选，在传入use_cache=True或config.use_cache=True时返回）—— 它是一个 Cache 实例。更多详情，请参阅我们的 kv cache 指南。包含预计算的隐藏状态（自注意力块中的键和值），可用于（参见
past_key_values输入）加速顺序解码。hidden_states (
tuple(torch.Tensor)，可选，当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
attentions (
tuple(torch.Tensor)，可选，当传入output_attentions=True或config.output_attentions=True时返回) — 一个torch.Tensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力权重，即经过注意力 softmax 之后的权重，用于在自注意力头中计算加权平均值。
示例：
>>> from transformers import AutoTokenizer, Gemma3nForCausalLM
>>> model = Gemma3nForCausalLM.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?"Gemma3nForConditionalGeneration
class transformers.Gemma3nForConditionalGeneration
< source >( config: Gemma3nConfig )
参数
- config (Gemma3nConfig) — 模型配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。
基础 Gemma 3n 模型，包含视觉骨干网络、音频骨干网络、语言模型以及语言建模头。
该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。
该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Nonepixel_values: typing.Optional[torch.Tensor] = Noneinput_features: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneinput_features_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Nonetoken_type_ids: typing.Optional[torch.LongTensor] = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = Nonelogits_to_keep: typing.Union[int, torch.Tensor] = 0per_layer_inputs: typing.Optional[torch.Tensor] = Nonemm_encoder_outputs: dict[str, transformers.modeling_outputs.BaseModelOutputWithPooling] | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Gemma3nCausalLMOutputWithPast or tuple(torch.Tensor)
参数
- input_ids (
torch.LongTensor形状为(batch_size, sequence_length), ，可选) — 输入序列中各 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 AutoTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。
- pixel_values (
torch.Tensor，形状为(batch_size, num_channels, image_size, image_size)，可选) — 与输入图像对应的张量。可以使用 SiglipImageProcessor 获取像素值。有关详细信息，请参阅 SiglipImageProcessor.call()（Gemma3nProcessor 使用 SiglipImageProcessor 处理图像）。 - input_features (
torch.Tensor，形状为(batch_size, sequence_length, feature_dim)，可选) — 与输入音频特征对应的张量。可以使用 Gemma3nAudioFeatureExtractor 获取音频特征。有关详细信息，请参阅Gemma3nAudioFeatureExtractor.__call__()（Gemma3nProcessor 使用 Gemma3nAudioFeatureExtractor 来处理音频）。 - attention_mask (
torch.Tensor形状为(batch_size, sequence_length), ，可选) — 用于避免对填充 token 索引执行注意力机制的掩码。掩码值取自[0, 1]:- 1 表示未被屏蔽的 token，
- 对于被掩码的 token，值为 0。
- input_features_mask (
torch.Tensor，可选，默认为 None) — 输入音频的注意力掩码。 - 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 cache 指南。 如果未传入
past_key_values，则默认会初始化 DynamicCache。模型将输出与输入相同的缓存格式。
如果使用了
past_key_values，用户应仅输入未处理的input_ids（即未向该模型提供其过去键值状态的那些），其形状为(batch_size, unprocessed_length)，而不是形状为(batch_size, sequence_length)的全部input_ids。 - token_type_ids (
torch.LongTensor形状为(batch_size, sequence_length), ，可选) — 用于指示输入中第一和第二部分的片段 token 索引。索引取值范围为[0, 1]:- 0 对应 sentence A 标记，
- 1 对应于 sentence B 标记。
- inputs_embeds（形状为
(batch_size, sequence_length, hidden_size)的torch.Tensor，可选） — 可选地，您可以选择直接传入嵌入表示，而不是传入input_ids。如果您希望对input_ids索引如何转换为相应向量拥有比模型内部嵌入查找矩阵更多的控制权，这将非常有用。 - labels（形状为
(batch_size, sequence_length)的torch.LongTensor，可选） — 用于计算掩码语言建模损失的标签。索引应在[0, ..., config.text_config.vocab_size]范围内，或为 -100（参见input_ids的文档字符串）。索引设置为-100的 token 将被忽略（即被掩码），损失仅针对标签位于[0, ..., config.text_config.vocab_size]范围内的 token 进行计算。 - use_cache (
bool，可选) — 如果设置为True，则会返回past_key_values键值状态，可用于加速解码（参见past_key_values）。 - logits_to_keep (
Union[int, torch.Tensor], 可选，默认为0) — 如果为int，则计算最后logits_to_keep个 token 的 logits。如果为0，则计算所有input_ids的 logits（特殊情况）。生成过程只需要最后一个 token 的 logits，仅针对该 token 进行计算可以节省内存，对于长序列或大词汇量而言，这种节省相当显著。 如果为torch.Tensor，则必须是一维张量，对应于序列长度维度中需要保留的索引。 这在使用打包张量格式（将批次和序列长度合并为单一维度）时非常有用。 - per_layer_inputs (
torch.Tensor, 可选) — 预计算的逐层输入文本嵌入，形状为(batch_size, sequence_length, num_hidden_layers, hidden_size_per_layer_input)。如果提供了该参数，将直接使用这些嵌入，而不会在文本模型中通过get_per_layer_inputs()从input_ids计算得到。如果调用forward时传入的是inputs_embeds而不是input_ids，则应预先计算这些逐层嵌入，并随inputs_embeds一起传入，否则逐层嵌入中的 token 标识分量将被省略。 - mm_encoder_outputs (
dict[str, ~modeling_outputs.BaseModelOutputWithPooling], 可选) — 一个字典，其中键为支持的模态，值为该模态的编码输出。每个编码输出是一个元组，由 (pooler_output、可选：last_hidden_states、可选：hidden_states、可选：attentions)pooler_output，形状为(batch_size, sequence_length, hidden_size)，可选) 组成，它是编码器融合到文本嵌入中的多模态特征序列。
返回值
Gemma3nCausalLMOutputWithPast 或 tuple(torch.Tensor)
Gemma3nCausalLMOutputWithPast 或 torch.Tensor 元组（如果传入 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（Gemma3nConfig）和输入。
Gemma3nForConditionalGeneration 的 forward 方法重写了 __call__ 特殊方法。
尽管前向传播的实现需要在此函数中定义，但之后应调用
Module实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。
loss (
torch.Tensor，形状为(1,)，可选，当提供labels时返回) — 语言建模损失（用于下一个 token 预测）。logits（形状为
(batch_size, sequence_length, config.text_config.vocab_size)的torch.Tensor）— 语言建模头的预测分数（SoftMax 之前每个词汇表 token 的分数）。past_key_values（
Cache，可选，在传入use_cache=True或config.use_cache=True时返回）—— 它是一个 Cache 实例。更多详情，请参阅我们的 kv cache 指南。包含预计算的隐藏状态（自注意力块中的键和值），可用于（参见
past_key_values输入）加速顺序解码。hidden_states (
tuple[torch.Tensor]，可选，当传入output_hidden_states=True或config.output_hidden_states=True时返回) — 一个torch.Tensor元组（如果模型具有嵌入层，则包含嵌入层输出的一个张量，以及每个层输出的一个张量），形状为(batch_size, sequence_length, hidden_size)。模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
attentions (
tuple[torch.Tensor]，可选，当传入output_attentions=True或config.output_attentions=True时返回) — 一个torch.Tensor元组（每层一个），形状为(batch_size, num_heads, sequence_length, sequence_length)。注意力权重，即经过注意力 softmax 之后的权重，用于在自注意力头中计算加权平均值。
image_hidden_states (
torch.Tensor，可选) — 大小为(batch_size, num_images, sequence_length, hidden_size)的torch.Tensor。 由视觉编码器生成的模型 image_hidden_states，即对最后一个隐藏状态进行投影后的结果。audio_hidden_states (
torch.Tensor, 可选) — 大小为(batch_size, num_images, sequence_length, hidden_size)的torch.Tensor。 由音频编码器生成并在投影最后一个隐藏状态后得到的模型的 audio_hidden_states。
示例：
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> 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,
... tokenizer=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"get_image_features
< source >( pixel_values: Tensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> )
参数
- pixel_values (
torch.Tensor，形状为(batch_size, num_channels, image_size, image_size)) — 与输入图像对应的张量。可以使用 SiglipImageProcessor 获取像素值。有关详细信息，请参阅 SiglipImageProcessor.call()（Gemma3nProcessor 使用 SiglipImageProcessor 处理图像）。
示例：
>>> from PIL import Image
>>> from transformers import AutoProcessor, Gemma3nForConditionalGeneration
>>> model = Gemma3nForConditionalGeneration.from_pretrained("google/gemma-3n-E4B")
>>> processor = AutoProcessor.from_pretrained("google/gemma-3n-E4B")
>>> messages = [
... {
... "role": "user", "content": [
... {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"},
... {"type": "text", "text": "Where is the cat standing?"},
... ]
... },
... ]
>>> inputs = processor.apply_chat_template(
... messages,
... tokenize=True,
... return_dict=True,
... return_tensors="pt",
... add_generation_prompt=True
... )
>>> # Generate
>>> generate_ids = model.generate(**inputs)
>>> processor.batch_decode(generate_ids, skip_special_tokens=True)[0]