# VoxtralRealtime VoxtralRealtime 是由 [Mistral AI](https://mistral.ai) 推出的流式语音转文本模型，专为实时自动语音识别（ASR）而设计。与处理完整音频文件的离线 [Voxtral](./voxtral) 模型不同，VoxtralRealtime 采用低延迟、增量式转写架构，通过分块处理实时到达的音频来实现该目标。 该模型将音频编码器与基于 Mistral 的语言模型解码器相结合，利用时间条件嵌入以及带有填充缓存的因果卷积，以实现高效的流式推理。 ## 用法 ### 离线转录 要转录完整的音频文件，请直接使用处理器和模型。生成长度会根据音频长度自动确定。 ```python from datasets import load_dataset from transformers import AutoProcessor, VoxtralRealtimeForConditionalGeneration repo_id = "mistralai/Voxtral-Mini-4B-Realtime-2602" processor = AutoProcessor.from_pretrained(repo_id) model = VoxtralRealtimeForConditionalGeneration.from_pretrained(repo_id, device_map="auto") ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation") audio = ds[0]["audio"]["array"] inputs = processor(audio, return_tensors="pt").to(model.device) inputs = inputs.to(model.device, dtype=model.dtype) outputs = model.generate(**inputs) decoded_outputs = processor.batch_decode(outputs, skip_special_tokens=True) print(decoded_outputs[0]) ``` ### 批量离线转录 可以在单次前向传播中转写多个音频样本： ```python from datasets import load_dataset from transformers import AutoProcessor, VoxtralRealtimeForConditionalGeneration repo_id = "mistralai/Voxtral-Mini-4B-Realtime-2602" processor = AutoProcessor.from_pretrained(repo_id) model = VoxtralRealtimeForConditionalGeneration.from_pretrained(repo_id, device_map="auto") ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation") audio = [ds[i]["audio"]["array"] for i in range(2)] inputs = processor(audio, return_tensors="pt").to(model.device) inputs = inputs.to(model.device, dtype=model.dtype) outputs = model.generate(**inputs) decoded_outputs = processor.batch_decode(outputs, skip_special_tokens=True) for decoded_output in decoded_outputs: print(decoded_output) ``` ### 流式转录 > [!NOTE] > 这是一个实验性功能，API 可能会发生变化。 对于实时转录，音频将按照以下规则分块： ```python from threading import Thread import numpy as np import torch from datasets import load_dataset from transformers import ( TextIteratorStreamer, VoxtralRealtimeForConditionalGeneration, VoxtralRealtimeProcessor, ) model_id = "mistralai/Voxtral-Mini-4B-Realtime-2602" processor = VoxtralRealtimeProcessor.from_pretrained(model_id) model = VoxtralRealtimeForConditionalGeneration.from_pretrained(model_id, device_map=torch.accelerator.current_accelerator()) ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation") audio = ds[0]["audio"]["array"] # Manually pad the audio to account for right padding tokens required by the model xaudio = np.pad(audio, (0, processor.num_right_pad_tokens * processor.raw_audio_length_per_tok)) first_chunk_inputs = processor( audio[:processor.num_samples_first_audio_chunk], is_streaming=True, is_first_audio_chunk=True, return_tensors="pt" ) first_chunk_inputs.to(model.device, dtype=model.dtype) def input_features_generator(): yield first_chunk_inputs.input_features mel_frame_idx = processor.num_mel_frames_first_audio_chunk hop_length = processor.feature_extractor.hop_length win_length = processor.feature_extractor.win_length start_idx = mel_frame_idx * hop_length - win_length // 2 end_idx = start_idx + processor.num_samples_per_audio_chunk while (end_idx:=start_idx + processor.num_samples_per_audio_chunk) < audio.shape[0]: inputs = processor( audio[start_idx:end_idx], is_streaming=True, is_first_audio_chunk=False, return_tensors="pt" ) inputs.to(model.device, dtype=model.dtype) yield inputs.input_features mel_frame_idx += processor.audio_length_per_tok start_idx = mel_frame_idx * hop_length - win_length // 2 streamer = TextIteratorStreamer(processor.tokenizer, skip_special_tokens=True, clean_up_tokenization_spaces=True) generate_kwargs = { "input_ids": first_chunk_inputs.input_ids, "input_features": input_features_generator(), "num_delay_tokens": first_chunk_inputs.num_delay_tokens, "streamer": streamer, } thread = Thread(target=model.generate, kwargs=generate_kwargs) thread.start() # Iterate over the streamer to get text chunks as they are generated print("Model output (streaming):", end=" ", flush=True) for text_chunk in streamer: print(text_chunk, end="", flush=True) ``` 该模型由 [Eustache Le Bihan](https://huggingface.co/eustlb) 贡献。 ## VoxtralRealtimeConfig[[transformers.VoxtralRealtimeConfig]] #### transformers.VoxtralRealtimeConfig[[transformers.VoxtralRealtimeConfig]] ```python transformers.VoxtralRealtimeConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, audio_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, text_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, projector_hidden_act: str = 'gelu', audio_length_per_tok: int = 8, default_num_delay_tokens: int = 6, downsample_factor: int = 4, tie_word_embeddings: bool = True, use_cache: bool = True) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/voxtral_realtime/configuration_voxtral_realtime.py#L125) **参数：** audio_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`，*可选*)：音频骨干网络的配置对象或字典。 text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`，*可选*)：文本骨干网络的配置对象或字典。 projector_hidden_act (`str`，*可选*，默认为 `gelu`)：多模态投影器所使用的激活函数。 audio_length_per_tok (`int`，*可选*，默认为 8)：每个文本标记对应的音频帧数。 default_num_delay_tokens (`int`, *可选*, 默认为 6) : 用于流式传输的默认延迟 token 数量。 downsample_factor (`int`，*可选*，默认为 4)：在投影之前应用于音频特征的降采样因子。 tie_word_embeddings (`bool`，*可选*，默认为 `True`)：是否根据模型的 `tied_weights_keys` 映射来绑定权重嵌入。 use_cache (`bool`，*可选*，默认为 `True`)：模型是否应返回最后的键/值注意力（并非所有模型都使用）。仅当 `config.is_decoder=True` 或模型为仅解码器生成模型时相关。 这是用于存储 VoxtralRealtimeModel 配置的类。它根据指定的参数实例化 Voxtral Realtime 模型，并定义模型架构。使用默认值实例化配置将得到与 [mistralai/Voxtral-Mini-4B-Realtime-2602](https://huggingface.co/mistralai/Voxtral-Mini-4B-Realtime-2602) 类似的配置。 配置对象继承自 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。 ```python >>> from transformers import VoxtralRealtimeForConditionalGeneration, VoxtralRealtimeConfig >>> # Initializing a VoxtralRealtime configuration >>> configuration = VoxtralRealtimeConfig() >>> # Initializing a model with random weights >>> model = VoxtralRealtimeForConditionalGeneration(configuration) >>> # Accessing the model configuration >>> configuration = model.config ``` ## VoxtralRealtimeEncoderConfig[[transformers.VoxtralRealtimeEncoderConfig]] #### transformers.VoxtralRealtimeEncoderConfig[[transformers.VoxtralRealtimeEncoderConfig]] ```python transformers.VoxtralRealtimeEncoderConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, vocab_size: int = 131072, hidden_size: int = 1280, intermediate_size: int = 5120, num_hidden_layers: int = 32, num_attention_heads: int = 32, activation_function: str = 'gelu', num_mel_bins: int = 128, initializer_range: float = 0.02, attention_dropout: float | int = 0.0, hidden_act: str = 'silu', max_position_embeddings: int = 1500, rms_norm_eps: float = 1e-05, rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None, sliding_window: int = 750, head_dim: int = 64, use_cache: bool = True) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/voxtral_realtime/configuration_voxtral_realtime.py#L73) **参数：** vocab_size (`int`，*可选*，默认值为 `131072`)：模型的词汇表大小。定义了 `input_ids` 可以表示的不同 token 数量。 hidden_size (`int`，*可选*，默认为 `1280`)：隐藏表示的维度。 intermediate_size (`int`，*可选*，默认值为 `5120`)：MLP 表示的维度。 num_hidden_layers (`int`，*可选*，默认为 `32`)：Transformer 解码器中的隐藏层数。 num_attention_heads (`int`，*可选*，默认为 `32`)：Transformer 解码器中每个注意力层的注意力头数量。 activation_function (`str`，*可选*，默认为 `gelu`)：解码器中的非线性激活函数（函数或字符串）。例如，`"gelu"`、`"relu"`、`"silu"` 等。 num_mel_bins (`int`，*可选*，默认为 `128`)：每个输入帧使用的 mel 特征数量。应与 `AutoFeatureExtractor` 类中使用的值对应。 initializer_range (`float`，*可选*，默认值为 `0.02`)：用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。 attention_dropout (`Union[float, int]`，*可选*，默认值为 `0.0`)：注意力概率的 dropout 比率。 hidden_act (`str`，*可选*，默认为 `silu`)：解码器中的非线性激活函数（函数或字符串）。例如，`"gelu"`、`"relu"`、`"silu"` 等。 max_position_embeddings (`int`，*可选*，默认为 `1500`)：该模型可能使用的最大序列长度。 rms_norm_eps (`float`，*可选*，默认值为 `1e-05`)：rms 归一化层中使用的 epsilon。 rope_parameters (`Union[~modeling_rope_utils.RopeParameters, dict]`, *可选*) : 包含 RoPE 嵌入配置参数的字典。该字典应包含 `rope_theta` 的值，并且如果希望使用更长的 `max_position_embeddings` 配合 RoPE，则可选地包含用于缩放的参数。 sliding_window (`int`，*可选*，默认为 `750`)：滑动窗口注意力机制的窗口大小。如果为 `None`，则不应用滑动窗口。 head_dim (`int`, *可选*, 默认为 `64`) : 注意力头维度。如果为 None，则默认为 hidden_size // num_attention_heads use_cache (`bool`，*可选*，默认为 `True`)：模型是否应返回最后的键/值注意力（并非所有模型都使用）。仅当 `config.is_decoder=True` 或模型为仅解码器生成模型时相关。 这是用于存储 VoxtralRealtimeModel 配置的类。它根据指定的参数实例化 Voxtral Realtime 模型，并定义模型架构。使用默认值实例化配置将得到与 [mistralai/Voxtral-Mini-4B-Realtime-2602](https://huggingface.co/mistralai/Voxtral-Mini-4B-Realtime-2602) 类似的配置。 配置对象继承自 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。 示例： ```python >>> from transformers import VoxtralRealtimeEncoderConfig, VoxtralRealtimeEncoder >>> # Initializing a VoxtralRealtimeEncoderConfig >>> configuration = VoxtralRealtimeEncoderConfig() >>> # Initializing a VoxtralRealtimeEncoder (with random weights) >>> model = VoxtralRealtimeEncoder(configuration) >>> # Accessing the model configuration >>> configuration = model.config ``` ## VoxtralRealtimeTextConfig[[transformers.VoxtralRealtimeTextConfig]] #### transformers.VoxtralRealtimeTextConfig[[transformers.VoxtralRealtimeTextConfig]] ```python transformers.VoxtralRealtimeTextConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, vocab_size: int = 32000, hidden_size: int = 4096, intermediate_size: int = 14336, num_hidden_layers: int = 32, num_attention_heads: int = 32, num_key_value_heads: int = 8, head_dim: int | None = None, hidden_act: str = 'silu', max_position_embeddings: int = 131072, initializer_range: float = 0.02, rms_norm_eps: float = 1e-06, use_cache: bool = True, pad_token_id: int | None = None, bos_token_id: int | None = 1, eos_token_id: int | list[int] | None = 2, rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None, sliding_window: int | None = 4096, attention_dropout: float | int = 0.0) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/voxtral_realtime/configuration_voxtral_realtime.py#L26) **参数：** vocab_size (`int`，*可选*，默认值为 `32000`)：模型的词汇表大小。定义了 `input_ids` 可以表示的不同 token 数量。 hidden_size (`int`，*可选*，默认为 `4096`)：隐藏表示的维度。 intermediate_size (`int`，*可选*，默认值为 `14336`)：MLP 表示的维度。 num_hidden_layers (`int`，*可选*，默认为 `32`)：Transformer 解码器中的隐藏层数。 num_attention_heads (`int`，*可选*，默认为 `32`)：Transformer 解码器中每个注意力层的注意力头数量。 num_key_value_heads (`int`, *可选*，默认为 `8`) : 这是用于实现 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 头应通过对该组内所有原始头进行平均池化来构建。更多详情请参阅 [这篇论文](https://huggingface.co/papers/2305.13245)。如果未指定，则默认为 `num_attention_heads`。 head_dim (`int`, *可选*) : 注意力头维度。如果为 None，则默认为 hidden_size // num_attention_heads hidden_act (`str`，*可选*，默认为 `silu`)：解码器中的非线性激活函数（函数或字符串）。例如，`"gelu"`、`"relu"`、`"silu"` 等。 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`, *可选*) : 词表中用于填充的 Token id。 bos_token_id (`int`，*可选*，默认为 `1`)：词汇表中用于表示流开始的 Token id。 eos_token_id (`Union[int, list[int]]`，*可选*，默认为 `2`)：词汇表中用于表示流结束（end-of-stream）的 token id。 rope_parameters (`Union[~modeling_rope_utils.RopeParameters, dict]`, *可选*) : 包含 RoPE 嵌入配置参数的字典。该字典应包含 `rope_theta` 的值，并且如果希望使用更长的 `max_position_embeddings` 配合 RoPE，则可选地包含用于缩放的参数。 sliding_window (`int`, *可选*，默认为 `4096`)：滑动窗口注意力的窗口大小。如果为 `None`，则不应用滑动窗口。 attention_dropout (`Union[float, int]`，*可选*，默认值为 `0.0`)：注意力概率的 dropout 比率。 这是用于存储 VoxtralRealtimeModel 配置的类。它根据指定的参数实例化 Voxtral Realtime 模型，并定义模型架构。使用默认值实例化配置将得到与 [mistralai/Voxtral-Mini-4B-Realtime-2602](https://huggingface.co/mistralai/Voxtral-Mini-4B-Realtime-2602) 类似的配置。 配置对象继承自 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。 ## VoxtralRealtimeFeatureExtractor[[transformers.VoxtralRealtimeFeatureExtractor]] #### transformers.VoxtralRealtimeFeatureExtractor[[transformers.VoxtralRealtimeFeatureExtractor]] ```python transformers.VoxtralRealtimeFeatureExtractor(feature_size = 128, sampling_rate = 16000, hop_length = 160, n_fft = 400, win_length = 400, padding_value = 0.0, global_log_mel_max = 1.5, **kwargs) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/voxtral_realtime/feature_extraction_voxtral_realtime.py#L32) **参数：** feature_size (`int`，*可选*，默认为 128)：提取特征的维度。 sampling_rate (`int`，*可选*，默认值为 16000)：音频文件应被数字化采样的采样率，单位为赫兹（Hz）。 hop_length (`int`, *可选*，默认为 160)：用于获取梅尔频率系数的 STFT 的重叠窗口长度。 n_fft (`int`，*可选*，默认为 512)：傅里叶变换的大小。 win_length (`int`，*可选*，默认为 400)：STFT 计算的窗口长度。 padding_value (`float`, *可选*, 默认值为 0.0) : 用于填充音频的填充值。应对应静音。 构建一个 VOXTRAL_REALTIME 特征提取器。 此特征提取器继承自 [SequenceFeatureExtractor](/docs/transformers/main/zh/main_classes/feature_extractor#transformers.SequenceFeatureExtractor)，后者包含了大部分主要方法。有关这些方法的更多信息，请参阅该父类。 此类使用自定义的 numpy 实现的`Short Time Fourier Transform`从原始语音中提取 mel 滤波器组特征，其结果应与 pytorch 的`torch.stft`等效。 ## VoxtralRealtimeProcessor[[transformers.VoxtralRealtimeProcessor]] #### transformers.VoxtralRealtimeProcessor[[transformers.VoxtralRealtimeProcessor]] ```python transformers.VoxtralRealtimeProcessor(feature_extractor, tokenizer) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/voxtral_realtime/processing_voxtral_realtime.py#L50) **参数：** feature_extractor (`VoxtralRealtimeFeatureExtractor`)：特征提取器是必需的输入。 tokenizer (`MistralCommonBackend`)：分词器是必需的输入。 构建一个 VoxtralRealtimeProcessor，它将特征提取器和分词器封装为单个处理器。 [VoxtralRealtimeProcessor](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeProcessor) 提供了 [VoxtralRealtimeFeatureExtractor](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeFeatureExtractor) 和 [MistralCommonBackend](/docs/transformers/main/zh/model_doc/mistral#transformers.MistralCommonBackend) 的所有功能。有关更多信息，请参阅 [~VoxtralRealtimeFeatureExtractor](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeFeatureExtractor) 和 [~MistralCommonBackend](/docs/transformers/main/zh/model_doc/mistral#transformers.MistralCommonBackend)。 #### __调用__[[transformers.VoxtralRealtimeProcessor.__call__]] ```python __call__(audio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor'], NoneType] = None, is_streaming: bool = False, is_first_audio_chunk: bool | None = True, **kwargs: *) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/voxtral_realtime/processing_voxtral_realtime.py#L130) **参数：** audio (`AudioInput`，*可选*)：作为 NumPy 数组或 PyTorch 张量提供的输入音频或音频批次。 is_streaming (`bool`，*可选*，默认为 `False`)：是否以流式模式处理音频。当为 `True` 时，可以使用 `is_first_audio_chunk` 来区分首个数据块与后续数据块，从而分块传入音频。 is_first_audio_chunk (`bool`, *可选*，默认为 `True`) : 当前音频是否为流式会话中的第一个数据块。当为 `True` 时，音频将被编码为包含分词文本的完整转录请求。当为 `False` 时，仅提取音频特征（跳过文本编码）。当 `is_streaming=False` 时，必须为 `True`。 **返回：** [BatchFeature](/docs/transformers/main/zh/main_classes/feature_extractor#transformers.BatchFeature) 一个包含以下字段的 [BatchFeature](/docs/transformers/main/zh/main_classes/feature_extractor#transformers.BatchFeature)： - **input_ids** -- 要输入模型的 token id 列表。当 `is_first_audio_chunk=True` 时返回。 - **attention_mask** -- 指定模型应关注哪些令牌的索引列表。当 `is_first_audio_chunk=True` 时返回。 - **input_features** -- 从音频输入中提取的梅尔频谱特征。 - **num_delay_tokens** -- 用于流式传输的延迟 token 数量。 用于为 Voxtral Realtime 模型准备音频输入的主要方法。该方法使用 `mistral_common` 将音频编码为转录请求，对生成的文本进行分词，并使用特征提取器提取梅尔频谱特征。支持流式和非流式模式。 ## VoxtralRealtimeEncoder[[transformers.VoxtralRealtimeEncoder]] #### transformers.VoxtralRealtimeEncoder[[transformers.VoxtralRealtimeEncoder]] ```python transformers.VoxtralRealtimeEncoder(config: VoxtralRealtimeEncoderConfig) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/voxtral_realtime/modeling_voxtral_realtime.py#L499) **参数：** config ([VoxtralRealtimeEncoderConfig](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeEncoderConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。 VoxtralRealtime 编码器，即 Whisper 编码器。 该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。 该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。 #### forward[[transformers.VoxtralRealtimeEncoder.forward]] ```python forward(input_features: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, padding_cache: transformers.models.voxtral_realtime.modeling_voxtral_realtime.VoxtralRealtimeConv1dPaddingCache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, use_padding_cache: bool | None = None, attention_mask: typing.Optional[torch.Tensor] = None, **kwargs: *) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/voxtral_realtime/modeling_voxtral_realtime.py#L530) **参数：** input_features (`torch.Tensor`，形状为 `(batch_size, sequence_length, feature_dim)`，*可选*) : 与输入音频特征对应的张量。可以使用 [VoxtralRealtimeFeatureExtractor](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeFeatureExtractor) 获取音频特征。有关详细信息，请参阅 `VoxtralRealtimeFeatureExtractor.__call__()`（[VoxtralRealtimeProcessor](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeProcessor) 使用 [VoxtralRealtimeFeatureExtractor](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeFeatureExtractor) 处理音频）。 position_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids) past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/main/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/main/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。 padding_cache (`VoxtralRealtimeConv1dPaddingCache`, *可选*) : 用于卷积层填充的缓存，以在流式块之间保持状态。 inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。 use_cache (`bool`，*可选*)：如果设置为 `True`，则会返回 `past_key_values` 键值状态，可用于加速解码（参见 `past_key_values`）。 use_padding_cache (`bool`, *可选*) : 是否使用填充缓存。 attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask) **返回：** [BaseModelOutputWithPooling](/docs/transformers/main/zh/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) 或 `tuple(torch.Tensor)` 一个 [BaseModelOutputWithPooling](/docs/transformers/main/zh/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) 或 `torch.Tensor` 元组（如果传入了 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[VoxtralRealtimeConfig](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeConfig)）和输入。 [VoxtralRealtimeEncoder](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeEncoder) 的 forward 方法重写了 `__call__` 特殊方法。 尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。 - **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 模型最后一层输出的隐藏状态序列。 - **pooler_output**（形状为 `(batch_size, hidden_size)` 的 `torch.Tensor`）-- 序列中第一个 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 后的注意力权重，用于在自注意力头中计算加权平均值。 ## VoxtralRealtimeModel[[transformers.VoxtralRealtimeModel]] #### transformers.VoxtralRealtimeModel[[transformers.VoxtralRealtimeModel]] ```python transformers.VoxtralRealtimeModel(config: VoxtralRealtimeConfig) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/voxtral_realtime/modeling_voxtral_realtime.py#L863) **参数：** config ([VoxtralRealtimeConfig](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。 VoxtralRealtime 模型由流式 Whisper 风格的编码器、多模态投影器、基于 Mistral 的语言模型以及时间嵌入组成，不包含语言建模头。 该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。 该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。 #### forward[[transformers.VoxtralRealtimeModel.forward]] ```python forward(input_ids: typing.Optional[torch.LongTensor] = None, input_features: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, encoder_past_key_values: transformers.cache_utils.Cache | None = None, padding_cache: transformers.models.voxtral_realtime.modeling_voxtral_realtime.VoxtralRealtimeConv1dPaddingCache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, encoder_inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, num_delay_tokens: typing.Union[int, torch.Tensor] = None, **kwargs: *) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/voxtral_realtime/modeling_voxtral_realtime.py#L920) **参数：** input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/main/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids) input_features (`torch.Tensor`，形状为 `(batch_size, sequence_length, feature_dim)`，*可选*) : 与输入音频特征对应的张量。可以使用 [VoxtralRealtimeFeatureExtractor](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeFeatureExtractor) 获取音频特征。有关详细信息，请参阅 `VoxtralRealtimeFeatureExtractor.__call__()`（[VoxtralRealtimeProcessor](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeProcessor) 使用 [VoxtralRealtimeFeatureExtractor](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeFeatureExtractor) 处理音频）。 attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask) position_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids) past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/main/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/main/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。 encoder_past_key_values (`Cache`，*可选*)：编码器的预计算隐藏状态（自注意力块中的键和值）。 padding_cache (`VoxtralRealtimeConv1dPaddingCache`, *可选*) : 用于卷积层填充的缓存，以在流式块之间保持状态。 inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。 encoder_inputs_embeds (`torch.Tensor`, *可选*) : 可选地，您可以选择直接为编码器传递嵌入表示，而不是传递 `input_features`。 use_cache (`bool`，*可选*)：如果设置为 `True`，则会返回 `past_key_values` 键值状态，可用于加速解码（参见 `past_key_values`）。 num_delay_tokens (`int` 或 `torch.Tensor`，*可选*)：准备输入时使用的延迟 token 数量。 **返回：** `VoxtralRealtimeModelOutputWithPast` 或 `tuple(torch.Tensor)` `VoxtralRealtimeModelOutputWithPast` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[VoxtralRealtimeConfig](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeConfig)）和输入。 [VoxtralRealtimeModel](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeModel) 的 forward 方法重写了 `__call__` 特殊方法。 尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。 - **encoder_past_key_values** (`Cache`，*可选*) -- 音频编码器中预计算的隐藏状态（自注意力块中的键和值），可用于加速顺序解码。 - **padding_cache** (`VoxtralRealtimeConv1dPaddingCache`，*可选*) -- 用于卷积层填充的缓存，以在流式块之间保持状态。 - **audio_hidden_states** (`torch.Tensor`，*可选*) -- 在添加到文本嵌入之前投影后的音频隐藏状态。 ## VoxtralRealtimeForConditionalGeneration[[transformers.VoxtralRealtimeForConditionalGeneration]] #### transformers.VoxtralRealtimeForConditionalGeneration[[transformers.VoxtralRealtimeForConditionalGeneration]] ```python transformers.VoxtralRealtimeForConditionalGeneration(config: VoxtralRealtimeConfig) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/voxtral_realtime/modeling_voxtral_realtime.py#L1011) #### forward[[transformers.VoxtralRealtimeForConditionalGeneration.forward]] ```python forward(input_ids: typing.Optional[torch.LongTensor] = None, input_features: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, encoder_past_key_values: transformers.cache_utils.Cache | None = None, padding_cache: transformers.models.voxtral_realtime.modeling_voxtral_realtime.VoxtralRealtimeConv1dPaddingCache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, encoder_inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, logits_to_keep: typing.Union[int, torch.Tensor] = 0, num_delay_tokens: typing.Union[int, torch.Tensor] = None, **kwargs: *) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/voxtral_realtime/modeling_voxtral_realtime.py#L1024) **参数：** input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/main/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids) input_features (`torch.Tensor`，形状为 `(batch_size, sequence_length, feature_dim)`，*可选*) : 与输入音频特征对应的张量。可以使用 [VoxtralRealtimeFeatureExtractor](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeFeatureExtractor) 获取音频特征。有关详细信息，请参阅 `VoxtralRealtimeFeatureExtractor.__call__()`（[VoxtralRealtimeProcessor](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeProcessor) 使用 [VoxtralRealtimeFeatureExtractor](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeFeatureExtractor) 处理音频）。 attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask) position_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids) past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/main/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/main/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。 encoder_past_key_values (`Cache`，*可选*)：编码器的预计算隐藏状态（自注意力块中的键和值），可用于加速顺序解码。 padding_cache (`VoxtralRealtimeConv1dPaddingCache`, *可选*) : 用于卷积层填充的缓存，以在流式块之间保持状态。 inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。 encoder_inputs_embeds (`torch.Tensor`, *可选*) : 可选地，您可以选择直接为编码器传递嵌入表示，而不是传递 `input_features`。 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`，则必须是一维张量，对应于序列长度维度中需要保留的索引。这在使用打包张量格式（将批次和序列长度合并为单一维度）时非常有用。 num_delay_tokens (`int` 或 `torch.Tensor`，*可选*)：准备输入时使用的延迟 token 数量，详情请参见 [~VoxtralRealtimeProcessor](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeProcessor)。 **返回：** `VoxtralRealtimeCausalLMOutputWithPast` 或 `tuple(torch.Tensor)` `VoxtralRealtimeCausalLMOutputWithPast` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[VoxtralRealtimeConfig](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeConfig)）和输入。 [VoxtralRealtimeForConditionalGeneration](/docs/transformers/main/zh/model_doc/voxtral_realtime#transformers.VoxtralRealtimeForConditionalGeneration) 的 forward 方法重写了 `__call__` 特殊方法。 尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。 - **encoder_past_key_values** (`Cache`，*可选*) -- 音频编码器中预计算的隐藏状态（自注意力块中的键和值），可用于加速顺序解码。 - **padding_cache** (`VoxtralRealtimeConv1dPaddingCache`，*可选*) -- 用于卷积层填充的缓存，以在流式块之间保持状态。 示例： ```python >>> import torch >>> from transformers import VoxtralRealtimeForConditionalGeneration, AutoProcessor >>> from datasets import load_dataset >>> repo_id = "mistralai/Voxtral-Mini-4B-Realtime-2602" >>> processor = AutoProcessor.from_pretrained(repo_id) >>> model = VoxtralRealtimeForConditionalGeneration.from_pretrained(repo_id, dtype=torch.bfloat16, device_map="auto") >>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation") >>> audio = ds[0]["audio"]["array"] >>> inputs = processor(audio, return_tensors="pt") >>> inputs = inputs.to(model.device, dtype=model.dtype) >>> outputs = model.generate(**inputs) >>> processor.batch_decode(outputs, skip_special_tokens=True) ``` #### get_audio_features[[transformers.VoxtralRealtimeForConditionalGeneration.get_audio_features]] ```python get_audio_features(*args, **kwargs) ``` [来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/voxtral_realtime/modeling_voxtral_realtime.py#L1021)