Transformers documentation

Voxtral

Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.2).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

该模型于 2025-07-18 贡献至 Hugging Face Transformers。

Voxtral

Voxtral 是 Ministral 3B 和 Mistral Small 3B 的升级版本，通过支持音频输入来扩展其语言处理能力。它旨在处理语音转录、翻译和音频理解等任务。

您可以在 Mistral 的发布博客文章中阅读更多详情。

该模型提供两个检查点：

3B：mistralai/Voxtral-Mini-3B-2507
24B：mistralai/Voxtral-Small-24B-2507

主要功能

Voxtral 在 Ministral-3B 的基础上增加了音频处理能力：

转录模式：包含一个专门用于语音转录的模式。默认情况下，Voxtral 会检测口语语言并相应地进行转录。
长上下文：凭借 32k token 的上下文窗口，Voxtral 可处理长达 30 分钟的音频用于转录，或长达 40 分钟的音频用于更广泛的音频理解。
集成问答与摘要：支持直接查询音频并生成结构化摘要，无需依赖独立的 ASR 和语言模型。
多语言支持：自动检测语言，并在多种广泛使用的语言中表现良好，包括英语、西班牙语、法语、葡萄牙语、印地语、德语、荷兰语和意大利语。
通过语音进行函数调用：可根据检测到的用户意图，直接从语音输入触发函数或工作流。
文本能力：保持了其 Ministral-3B 基础模型强大的文本处理性能。

用法

音频指令模式

该模型支持音频-文本指令，包括多轮和多音频交互，所有处理均以批量方式进行。

➡️ 音频 + 文本指令

from transformers import AutoProcessor, VoxtralForConditionalGeneration


repo_id = "mistralai/Voxtral-Mini-3B-2507"

processor = AutoProcessor.from_pretrained(repo_id)
model = VoxtralForConditionalGeneration.from_pretrained(repo_id, device_map="auto")

conversation = [
    {
        "role": "user",
        "content": [
            {
                "type": "audio",
                "url": "https://huggingface.co/datasets/eustlb/audio-samples/resolve/main/dude_where_is_my_car.wav",
            },
            {"type": "text", "text": "What can you tell me about this audio?"},
        ],
    }
]

inputs = processor.apply_chat_template(conversation)
inputs = inputs.to(model.device)

outputs = model.generate(**inputs, max_new_tokens=500)
decoded_outputs = processor.batch_decode(outputs[:, inputs.input_ids.shape[1]:], skip_special_tokens=True)

print("\nGenerated response:")
print("=" * 80)
print(decoded_outputs[0])
print("=" * 80)

➡️ 多音频 + 文本指令

from transformers import AutoProcessor, VoxtralForConditionalGeneration


repo_id = "mistralai/Voxtral-Mini-3B-2507"

processor = AutoProcessor.from_pretrained(repo_id)
model = VoxtralForConditionalGeneration.from_pretrained(repo_id, device_map="auto")

conversation = [
    {
        "role": "user",
        "content": [
            {
                "type": "audio",
                "path": "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/mary_had_lamb.mp3",
            },
            {
                "type": "audio",
                "path": "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/winning_call.mp3",
            },
            {"type": "text", "text": "What sport and what nursery rhyme are referenced?"},
        ],
    }
]

inputs = processor.apply_chat_template(conversation)
inputs = inputs.to(model.device)

outputs = model.generate(**inputs, max_new_tokens=500)
decoded_outputs = processor.batch_decode(outputs[:, inputs.input_ids.shape[1]:], skip_special_tokens=True)

print("\nGenerated response:")
print("=" * 80)
print(decoded_outputs[0])
print("=" * 80)

➡️ 多轮对话：

from transformers import AutoProcessor, VoxtralForConditionalGeneration


repo_id = "mistralai/Voxtral-Mini-3B-2507"

processor = AutoProcessor.from_pretrained(repo_id)
model = VoxtralForConditionalGeneration.from_pretrained(repo_id, device_map="auto")

conversation = [
    {
        "role": "user",
        "content": [
            {
                "type": "audio",
                "path": "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/obama.mp3",
            },
            {
                "type": "audio",
                "path": "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/bcn_weather.mp3",
            },
            {"type": "text", "text": "Describe briefly what you can hear."},
        ],
    },
    {
        "role": "assistant",
        "content": "The audio begins with the speaker delivering a farewell address in Chicago, reflecting on his eight years as president and expressing gratitude to the American people. The audio then transitions to a weather report, stating that it was 35 degrees in Barcelona the previous day, but the temperature would drop to minus 20 degrees the following day.",
    },
    {
        "role": "user",
        "content": [
            {
                "type": "audio",
                "path": "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/dude_where_is_my_car.wav",
            },
            {"type": "text", "text": "Ok, now compare this new audio with the previous one."},
        ],
    },
]

inputs = processor.apply_chat_template(conversation)
inputs = inputs.to(model.device)

outputs = model.generate(**inputs, max_new_tokens=500)
decoded_outputs = processor.batch_decode(outputs[:, inputs.input_ids.shape[1]:], skip_special_tokens=True)

print("\nGenerated response:")
print("=" * 80)
print(decoded_outputs[0])
print("=" * 80)

➡️ 仅文本：

from transformers import AutoProcessor, VoxtralForConditionalGeneration


repo_id = "mistralai/Voxtral-Mini-3B-2507"

processor = AutoProcessor.from_pretrained(repo_id)
model = VoxtralForConditionalGeneration.from_pretrained(repo_id, device_map="auto")

conversation = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "What if a cyber brain could possibly generate its own ghost, and create a soul all by itself?",
            },
        ],
    }
]

inputs = processor.apply_chat_template(conversation)
inputs = inputs.to(model.device)

outputs = model.generate(**inputs, max_new_tokens=500)
decoded_outputs = processor.batch_decode(outputs[:, inputs.input_ids.shape[1]:], skip_special_tokens=True)

print("\nGenerated response:")
print("=" * 80)
print(decoded_outputs[0])
print("=" * 80)

➡️ 仅音频：

from transformers import AutoProcessor, VoxtralForConditionalGeneration


repo_id = "mistralai/Voxtral-Mini-3B-2507"

processor = AutoProcessor.from_pretrained(repo_id)
model = VoxtralForConditionalGeneration.from_pretrained(repo_id, device_map="auto")

conversation = [
    {
        "role": "user",
        "content": [
            {
                "type": "audio",
                "path": "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/dude_where_is_my_car.wav",
            },
        ],
    }
]

inputs = processor.apply_chat_template(conversation)
inputs = inputs.to(model.device)

outputs = model.generate(**inputs, max_new_tokens=500)
decoded_outputs = processor.batch_decode(outputs[:, inputs.input_ids.shape[1]:], skip_special_tokens=True)

print("\nGenerated response:")
print("=" * 80)
print(decoded_outputs[0])
print("=" * 80)

➡️ 批量推理！

from transformers import AutoProcessor, VoxtralForConditionalGeneration


repo_id = "mistralai/Voxtral-Mini-3B-2507"

processor = AutoProcessor.from_pretrained(repo_id)
model = VoxtralForConditionalGeneration.from_pretrained(repo_id, device_map="auto")

conversations = [
    [
        {
            "role": "user",
            "content": [
                {
                    "type": "audio",
                    "path": "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/obama.mp3",
                },
                {
                    "type": "audio",
                    "path": "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/bcn_weather.mp3",
                },
                {
                    "type": "text",
                    "text": "Who's speaking in the speech and what city's weather is being discussed?",
                },
            ],
        }
    ],
    [
        {
            "role": "user",
            "content": [
                {
                    "type": "audio",
                    "path": "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/winning_call.mp3",
                },
                {"type": "text", "text": "What can you tell me about this audio?"},
            ],
        }
    ],
]

inputs = processor.apply_chat_template(conversations)
inputs = inputs.to(model.device)

outputs = model.generate(**inputs, max_new_tokens=500)
decoded_outputs = processor.batch_decode(outputs[:, inputs.input_ids.shape[1]:], skip_special_tokens=True)

print("\nGenerated responses:")
print("=" * 80)
for decoded_output in decoded_outputs:
    print(decoded_output)
    print("=" * 80)

转录模式

使用模型转录音频（在英语、西班牙语、法语、葡萄牙语、印地语、德语、荷兰语和意大利语方面具有最先进的性能）！它还支持自动语言检测。

from transformers import AutoProcessor, VoxtralForConditionalGeneration


repo_id = "mistralai/Voxtral-Mini-3B-2507"

processor = AutoProcessor.from_pretrained(repo_id)
model = VoxtralForConditionalGeneration.from_pretrained(repo_id, device_map="auto")

# set the language if already known for better accuracy
inputs = processor.apply_transcription_request(language="en", audio="https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/obama.mp3", model_id=repo_id)

# # but you can also let the model detect the language automatically
# inputs = processor.apply_transcription_request(audio="https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/obama.mp3", model_id=repo_id)

inputs = inputs.to(model.device)
outputs = model.generate(**inputs, max_new_tokens=500)
decoded_outputs = processor.batch_decode(outputs[:, inputs.input_ids.shape[1]:], skip_special_tokens=True)

print("\nGenerated responses:")
print("=" * 80)
for decoded_output in decoded_outputs:
    print(decoded_output)
    print("=" * 80)

该模型由 Eustache Le Bihan 贡献。

VoxtralConfig

class transformers.VoxtralConfig

< source >

参数

audio_config (Union[dict, ~configuration_utils.PreTrainedConfig], 可选) — 音频骨干网络的配置对象或字典。
text_config (Union[dict, ~configuration_utils.PreTrainedConfig]，可选) — 文本骨干网络的配置对象或字典。
audio_token_id (int, 可选) — 用作输入音频占位符的音频 token 索引。
projector_hidden_act (str, 可选, 默认为 gelu) — 多模态投影器使用的激活函数。

这是用于存储 VoxtralModel 配置的类。它根据指定的参数实例化 Voxtral 模型，并定义模型架构。使用默认值实例化配置将生成与 mistralai/Voxtral-Mini-3B-2507 类似的配置。

配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。

示例：

>>> from transformers import VoxtralForConditionalGeneration, VoxtralConfig

>>> # Initializing a Voxtral configuration
>>> configuration = VoxtralConfig(audio_token_id=24, projector_hidden_act="gelu")

>>> # Initializing a 3B model with random weights
>>> model = VoxtralForConditionalGeneration(configuration)

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

VoxtralEncoderConfig

类 transformers.VoxtralEncoderConfig

< 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 = 51866hidden_size: int = 1280intermediate_size: int = 5120num_hidden_layers: int = 32num_attention_heads: int = 20scale_embedding: bool = Falseactivation_function: str = 'gelu'num_mel_bins: int = 128max_source_positions: int = 1500initializer_range: float = 0.02attention_dropout: float | int = 0.0dropout: float | int = 0.0layerdrop: float | int = 0.0activation_dropout: float | int = 0.0 )

参数

vocab_size (int，可选，默认为 51866) — 模型的词汇表大小。定义了 input_ids 可以表示的不同 token 数量。
hidden_size (int，可选，默认为 1280) — 隐藏表示的维度。
intermediate_size (int，可选，默认为 5120) — MLP 表示的维度。
num_hidden_layers (int，可选，默认为 32) — Transformer 解码器中的隐藏层数量。
num_attention_heads (int，可选，默认为 20) — Transformer 解码器中每个注意力层的注意力头数量。
scale_embedding (bool，可选，默认为 False) — 是否通过将嵌入除以 sqrt(d_model) 来对嵌入进行缩放。
activation_function (str，可选，默认为 gelu) — 解码器中的非线性激活函数（函数或字符串）。例如，"gelu"、"relu"、"silu" 等。
num_mel_bins (int, 可选，默认为 128) — 每个输入帧使用的 mel 特征数量。应与 AutoFeatureExtractor 类中使用的值相对应。
max_source_positions (int，可选，默认值为 1500) — 该模型可能使用的 log-mel 滤波器组特征的最大序列长度。
initializer_range (float，可选，默认为 0.02) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。
attention_dropout (Union[float, int]，可选，默认为 0.0) — 注意力概率的 dropout 比率。
dropout (Union[float, int]，可选，默认为 0.0) — 所有 dropout 层的比率。
layerdrop (Union[float, int]，可选，默认为 0.0) — LayerDrop 概率。有关更多详细信息，请参阅 [LayerDrop 论文](见 https://huggingface.co/papers/1909.11556)。
activation_dropout (Union[float, int]，可选，默认为 0.0) — 全连接层中激活值的 dropout 比率。

配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。

>>> from transformers import VoxtralEncoderConfig, VoxtralEncoder

>>> # Initializing a VoxtralEncoderConfig
>>> configuration = VoxtralEncoderConfig()

>>> # Initializing a VoxtralEncoder (with random weights)
>>> model = VoxtralEncoder(configuration)

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

VoxtralProcessor

class transformers.VoxtralProcessor

< source >

( feature_extractortokenizer )

参数

feature_extractor（WhisperFeatureExtractor）— 特征提取器是必需的输入。
tokenizer (MistralCommonBackend) — tokenizer 是必需的输入。

构建一个 VoxtralProcessor，它将特征提取器和分词器封装为单个处理器。

VoxtralProcessor 提供了 WhisperFeatureExtractor 和 MistralCommonBackend 的所有功能。有关更多信息，请参阅 ~WhisperFeatureExtractor 和 ~MistralCommonBackend。

call

< source >

( text: str | list[str] | list[list[str]] | None**kwargs: *<class 'transformers.models.voxtral.processing_voxtral.VoxtralProcessorKwargs'> )

参数

text (Union[str, list[str], list[list[str]]]，可选) — 要编码的序列或序列批次。每个序列可以是字符串或字符串列表（预分词字符串）。如果传入预分词输入，请设置 is_split_into_words=True，以避免与批量输入产生歧义。
max_source_positions (int，kwargs，可选，默认值为 3000) — 沿时间维度分割 mel 频谱图特征时，每个块的最大位置数。
return_tensors (str 或 TensorType, 可选) — 如果设置，将返回特定框架的张量。可接受的值为：
- 'pt'：返回 PyTorch torch.Tensor 对象。
- 'np'：返回 NumPy np.ndarray 对象。
**kwargs (ProcessingKwargs，可选) — 每种模态（文本、图像、视频、音频）的额外处理选项。模型特定参数已在上方列出；有关支持参数的完整列表，请参阅 TypedDict 类。

用于准备输入模型文本的方法。此方法将 text 参数转发给 MistralCommonBackend 的 __call__() 以编码文本。有关更多信息，请参阅上述方法的文档字符串。此方法不支持音频。要准备音频，请使用：

apply_chat_template apply_chat_template() 方法。
apply_transcription_request apply_transcription_request() 方法。

VoxtralEncoder

类 transformers.VoxtralEncoder

< source >

( config: VoxtralEncoderConfig )

参数

config (VoxtralEncoderConfig) — 模型配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

Voxtral 编码器，即 Whisper 编码器。

该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch torch.nn.Module 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

forward

< source >

( input_featuresattention_mask = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> )

参数

input_features (torch.LongTensor，形状为 (batch_size, feature_size, sequence_length)) — 从原始语音波形中提取的 mel 特征的浮点值。原始语音波形可以通过将 .flac 或 .wav 音频文件加载为 list[float] 类型的数组或 numpy.ndarray 来获取，例如通过 soundfile 库（pip install soundfile）。要将该数组准备为 input_features，应使用 AutoFeatureExtractor 来提取 mel 特征、填充并转换为 torch.Tensor 类型的张量。参见 call()
attention_mask (torch.Tensor), *optional*) -- Voxtral does not support masking of the input_features`, this argument is preserved for compatibility, but it is not used. By default the silence in the input log mel spectrogram are ignored.

VoxtralModel

class transformers.VoxtralModel

< source >

( config: VoxtralConfig )

参数

config (VoxtralConfig) — 模型的配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

Voxtral 模型由 Whisper 编码器、多模态投影器和 Llama 语言模型组成，不包含语言建模头。

该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch torch.nn.Module 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

forward

< source >

( input_ids: typing.Optional[torch.LongTensor] = Noneinput_features: 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'> ) → VoxtralModelOutputWithPast or tuple(torch.Tensor)

参数

input_ids (torch.LongTensor 形状为 (batch_size, sequence_length), ，可选) — 输入序列中各 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。
可以使用 AutoTokenizer 获取索引。有关详细信息，请参阅 PreTrainedTokenizer.encode() 和 PreTrainedTokenizer.call()。

什么是输入 ID？
input_features (torch.Tensor，形状为 (batch_size, sequence_length, feature_dim)，可选) — 与输入音频特征对应的张量。可以使用 WhisperFeatureExtractor 获取音频特征。有关详细信息，请参阅 WhisperFeatureExtractor.call()（VoxtralProcessor 使用 WhisperFeatureExtractor 处理音频）。
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].
什么是位置 ID？
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）。

返回值

VoxtralModelOutputWithPast 或 tuple(torch.Tensor)

VoxtralModelOutputWithPast 或 torch.Tensor 元组（当传入 return_dict=False 或 config.return_dict=False 时），其包含的元素取决于配置（VoxtralConfig）和输入。

VoxtralModel 的 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 之后的权重，用于在自注意力头中计算加权平均值。
audio_hidden_states (torch.Tensor，可选) — 投影后的音频隐藏状态。

VoxtralForConditionalGeneration

class transformers.VoxtralForConditionalGeneration

< source >

( config: VoxtralConfig )

参数

config (VoxtralConfig) — 模型的配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

Voxtral 模型由 Whisper 编码器、多模态投影器和 Llama 语言模型组成。

该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch torch.nn.Module 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

forward

< source >

( input_ids: typing.Optional[torch.LongTensor] = Noneinput_features: 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] = 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()。

什么是输入 ID？
input_features (torch.Tensor，形状为 (batch_size, sequence_length, feature_dim)，可选) — 与输入音频特征对应的张量。可以使用 WhisperFeatureExtractor 获取音频特征。有关详细信息，请参阅 WhisperFeatureExtractor.call()（VoxtralProcessor 使用 WhisperFeatureExtractor 处理音频）。
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].
什么是位置 ID？
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），其包含的元素取决于配置（VoxtralConfig）和输入。

VoxtralForConditionalGeneration 的 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 VoxtralForConditionalGeneration, AutoProcessor
>>> import torch

>>> device = "cuda" if torch.cuda.is_available() else "cpu"
>>> repo_id = "mistralai/Voxtral-Mini-3B-2507"

>>> processor = AutoProcessor.from_pretrained(repo_id)
>>> model = VoxtralForConditionalGeneration.from_pretrained(repo_id, dtype=torch.bfloat16, device_map=device)

>>> conversation = [
    {
        "role": "user",
        "content": [
            {
                "type": "audio",
                "url": "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/dude_where_is_my_car.wav",
            },
            {"type": "text", "text": "What can you tell me about this audio?"},
        ],
    }
]

>>> inputs = processor.apply_chat_template(conversation)
>>> inputs = inputs.to(device, dtype=torch.bfloat16)

>>> outputs = model.generate(**inputs, max_new_tokens=30)
>>> processor.batch_decode(outputs[:, inputs.input_ids.shape[1]:], skip_special_tokens=True)
["This audio is a humorous conversation between two friends, likely in English, where one of them is trying to figure out what the other's tattoo says."]

get_audio_features

< source >

( *args**kwargs )

Update on GitHub

←VisualBERT VoxtralRealtime→