Transformers documentation

Voxtral

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Este modelo foi contribuído para o Hugging Face Transformers em 18/07/2025.

Voxtral

Voxtral é uma atualização de Ministral 3B e Mistral Small 3B, estendendo suas capacidades de linguagem com suporte a entrada de áudio. Ele foi projetado para lidar com tarefas como transcrição de fala, tradução e compreensão de áudio.

Você pode ler mais no post de lançamento da Mistral.

O modelo está disponível em dois checkpoints:

Principais recursos

O Voxtral é construído sobre o Ministral-3B, adicionando capacidades de processamento de áudio:

  • Modo de transcrição: Inclui um modo dedicado para transcrição de fala. Por padrão, o Voxtral detecta o idioma falado e o transcreve de acordo.
  • Contexto de longa duração: Com uma janela de contexto de 32k tokens, o Voxtral pode processar até 30 minutos de áudio para transcrição ou 40 minutos para uma compreensão mais ampla do áudio.
  • Q&A e resumo integrados: Suporta consultas diretas a áudio e a geração de resumos estruturados sem depender de modelos separados de ASR e de linguagem.
  • Suporte multilíngue: detecta automaticamente o idioma e apresenta bom desempenho em vários idiomas amplamente falados, incluindo inglês, espanhol, francês, português, hindi, alemão, holandês e italiano.
  • Chamada de funções por voz: Permite acionar funções ou fluxos de trabalho diretamente a partir da entrada de voz com base na intenção do usuário detectada.
  • Capacidades de texto: Mantém o forte desempenho de processamento de texto da sua base Ministral-3B.

Uso

Modo de Instrução de Áudio

O modelo suporta instruções de áudio e texto, incluindo interações de múltiplas rodadas e de múltiplos áudios, todas processadas em lotes.

➡️ áudio + instrução de texto

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)

➡️ multiáudio + instrução de texto

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)

➡️ multi-turn:

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)

➡️ apenas texto:

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)

➡️ somente áudio:

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)

➡️ inferência em lote!

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)

Modo de Transcrição

Use o modelo para transcrever áudio (desempenho de ponta em inglês, espanhol, francês, português, hindi, alemão, holandês e italiano)! Ele também suporta detecção automática de idioma.

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)

Este modelo foi contribuído por Eustache Le Bihan.

VoxtralConfig

classe transformers.VoxtralConfig

< >

( 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 = Noneaudio_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonetext_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneaudio_token_id: int | None = Noneprojector_hidden_act: str = 'gelu' )

Parâmetros

  • audio_config (Union[dict, ~configuration_utils.PreTrainedConfig], opcional) — O objeto de configuração ou dicionário do backbone de áudio.
  • text_config (Union[dict, ~configuration_utils.PreTrainedConfig], opcional) — O objeto de configuração ou dicionário do backbone de texto.
  • audio_token_id (int, opcional) — O índice do token de áudio usado como marcador de posição para o áudio de entrada.
  • projector_hidden_act (str, opcional, padrão gelu) — A função de ativação usada pelo projetor multimodal.

Esta é a classe de configuração para armazenar a configuração de um VoxtralModel. Ela é usada para instanciar um modelo Voxtral de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do mistralai/Voxtral-Mini-3B-2507

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Exemplo:

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

classe transformers.VoxtralEncoderConfig

< >

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

Parâmetros

  • vocab_size (int, opcional, padrão 51866) — Tamanho do vocabulário do modelo. Define o número de tokens diferentes que podem ser representados pelos input_ids.
  • hidden_size (int, opcional, padrão 1280) — Dimensão das representações ocultas.
  • intermediate_size (int, opcional, padrão 5120) — Dimensão das representações do MLP.
  • num_hidden_layers (int, opcional, padrão 32) — Número de camadas ocultas no decodificador do Transformer.
  • num_attention_heads (int, opcional, padrão 20) — Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.
  • scale_embedding (bool, opcional, padrão False) — Se as embeddings devem ser escalonadas dividindo por sqrt(d_model).
  • activation_function (str, opcional, padrão gelu) — A função de ativação não linear (função ou string) no decodificador. Por exemplo, "gelu", "relu", "silu", etc.
  • num_mel_bins (int, opcional, padrão 128) — Número de recursos mel usados por quadro de entrada. Deve corresponder ao valor utilizado na classe AutoFeatureExtractor.
  • max_source_positions (int, opcional, padrão 1500) — O comprimento máximo da sequência de recursos de filtro-banco log-mel com o qual este modelo pode ser utilizado.
  • initializer_range (float, opcional, padrão 0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.
  • attention_dropout (Union[float, int], opcional, padrão 0.0) — A taxa de dropout para as probabilidades de atenção.
  • dropout (Union[float, int], opcional, padrão 0.0) — A proporção para todas as camadas de dropout.
  • layerdrop (Union[float, int], opcional, padrão 0.0) — A probabilidade de LayerDrop. Consulte o [artigo do LayerDrop](veja https://huggingface.co/papers/1909.11556) para mais detalhes.
  • activation_dropout (Union[float, int], opcional, padrão 0.0) — A taxa de dropout para as ativações dentro da camada totalmente conectada.

Esta é a classe de configuração para armazenar a configuração de um VoxtralModel. Ela é usada para instanciar um modelo Voxtral de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do mistralai/Voxtral-Mini-3B-2507

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

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

classe transformers.VoxtralProcessor

< >

( feature_extractortokenizer )

Parâmetros

  • feature_extractor (WhisperFeatureExtractor) — O extrator de recursos é uma entrada obrigatória.
  • tokenizer (MistralCommonBackend) — O tokenizer é uma entrada obrigatória.

Constrói um VoxtralProcessor que encapsula um extrator de recursos e um tokenizador em um único processador.

VoxtralProcessor oferece todas as funcionalidades de WhisperFeatureExtractor e MistralCommonBackend. Consulte ~WhisperFeatureExtractor e ~MistralCommonBackend para mais informações.

__call__

< >

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

Parâmetros

  • text (Union[str, list[str], list[list[str]]], opcional) — A sequência ou lote de sequências a ser codificada. Cada sequência pode ser uma string ou uma lista de strings (string pré-tokenizada). Se você passar uma entrada pré-tokenizada, defina is_split_into_words=True para evitar ambiguidade com entradas em lote.
  • max_source_positions (int, kwargs, opcional, padrão 3000) — Número máximo de posições por bloco ao dividir os recursos do espectrograma mel ao longo da dimensão do tempo.
  • return_mm_token_type_ids (bool, kwargs) — Se deve retornar os ids de tipo de token multimodal indicando as posições dos tokens placeholder multimodais.
  • return_text_replacement_offsets (bool, kwargs) — Se deve retornar os deslocamentos de caracteres para cada placeholder multimodal e sua substituição.
  • return_tensors (str ou TensorType, opcional) — Se definido, retornará tensors de um framework específico. Os valores aceitos são:
    • 'pt': Retorna objetos torch.Tensor do PyTorch.
    • 'np': Retorna objetos np.ndarray do NumPy.
  • **kwargs (ProcessingKwargs, opcional) — Opções de processamento adicionais para cada modalidade (texto, imagens, vídeos, áudio). Os parâmetros específicos do modelo estão listados acima; consulte a classe TypedDict para a lista completa de argumentos suportados.

Método para preparar o texto a ser fornecido como entrada para o modelo. Este método encaminha os argumentos text para o __call__() do MistralCommonBackend para codificar o texto. Consulte a docstring dos métodos acima para mais informações. Este método não suporta áudio. Para preparar o áudio, use:

  1. método apply_chat_template apply_chat_template().
  2. método apply_transcription_request apply_transcription_request().

VoxtralEncoder

classe transformers.VoxtralEncoder

< >

( config: VoxtralEncoderConfig )

Parâmetros

  • config (VoxtralEncoderConfig) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.

O codificador Voxtral, que é um codificador Whisper.

Este modelo herda de PreTrainedModel. Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.)

Este modelo também é uma subclasse de torch.nn.Module do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.

forward

< >

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

Parâmetros

  • input_features (torch.LongTensor de forma (batch_size, feature_size, sequence_length)) — Valores em ponto flutuante dos recursos mel extraídos da forma de onda bruta da fala. A forma de onda bruta da fala pode ser obtida carregando um arquivo de áudio .flac ou .wav em um array do tipo list[float] ou um numpy.ndarray, por exemplo, por meio da biblioteca soundfile (pip install soundfile). Para preparar o array para input_features, o AutoFeatureExtractor deve ser usado para extrair os recursos mel, aplicar padding e converter em um tensor do tipo torch.Tensor. Veja 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

classe transformers.VoxtralModel

< >

( config: VoxtralConfig )

Parâmetros

  • config (VoxtralConfig) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.

O modelo Voxtral, que consiste em um codificador Whisper, um projetor multimodal e um modelo de linguagem Llama, sem uma cabeça de modelagem de linguagem.

Este modelo herda de PreTrainedModel. Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.)

Este modelo também é uma subclasse de torch.nn.Module do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.

forward

< >

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

Parâmetros

  • input_ids (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Índices dos tokens da sequência de entrada no vocabulário. O padding será ignorado por padrão.

    Os índices podem ser obtidos usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() e PreTrainedTokenizer.call() para mais detalhes.

    O que são IDs de entrada?

  • input_features (torch.Tensor de forma (batch_size, sequence_length, feature_dim), opcional) — Os tensores correspondentes às características de áudio de entrada. As características de áudio podem ser obtidas usando WhisperFeatureExtractor. Consulte WhisperFeatureExtractor.call() para mais detalhes (VoxtralProcessor usa WhisperFeatureExtractor para processar áudios).
  • attention_mask (torch.Tensor de forma (batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em [0, 1]:
    • 1 para tokens que não estão mascarados,
    • 0 para tokens que estão mascarados.

    O que são máscaras de atenção?

  • position_ids (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Índices das posições dos tokens de cada sequência de entrada nos embeddings de posição. Selecionados no intervalo [0, config.n_positions - 1].

    O que são IDs de posição?

  • past_key_values (~cache_utils.Cache, opcional) — Estados ocultos pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste no past_key_values retornado pelo modelo em uma etapa anterior da decodificação, quando use_cache=True ou config.use_cache=True.

    Apenas uma instância de Cache é permitida como entrada, consulte nosso guia de cache de kv. Se nenhum past_key_values for passado, DynamicCache será inicializado por padrão.

    O modelo sairá no mesmo formato de cache que é fornecido como entrada.

    Se past_key_values forem usados, espera-se que o usuário insira apenas os input_ids não processados (aqueles que não têm seus estados de chave e valor passados fornecidos a este modelo) com a forma (batch_size, unprocessed_length), em vez de todos os input_ids com a forma (batch_size, sequence_length).

  • inputs_embeds (torch.Tensor de forma (batch_size, sequence_length, hidden_size), opcional) — Opcionalmente, em vez de passar input_ids, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices de input_ids nos vetores associados do que a matriz de busca de incorporação interna do modelo.
  • use_cache (bool, opcional) — Se definido como True, os estados de chave-valor past_key_values são retornados e podem ser usados para acelerar a decodificação (veja past_key_values).

Retorna

VoxtralModelOutputWithPast ou tuple(torch.Tensor)

Uma VoxtralModelOutputWithPast ou uma tupla de torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False), contendo vários elementos dependendo da configuração (VoxtralConfig) e das entradas.

O método forward do VoxtralModel substitui o método especial __call__.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de Module em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

  • last_hidden_state (torch.Tensor de forma (batch_size, sequence_length, hidden_size)) — Sequência de estados ocultos na saída da última camada do modelo.

    Se past_key_values for usado, apenas o último hidden-state das sequências, com forma (batch_size, 1, hidden_size), é retornado.

  • past_key_values (Cache, opcional, retornado quando use_cache=True é passado ou quando config.use_cache=True) — É uma instância de Cache. Para mais detalhes, consulte nosso guia de cache kv.

    Contém estados ocultos pré-computados (chaves e valores nos blocos de autoatenção e, opcionalmente, se config.is_encoder_decoder=True, nos blocos de atenção cruzada) que podem ser usados (veja a entrada past_key_values) para acelerar a decodificação sequencial.

  • hidden_states (tuple(torch.Tensor), opcional, retornado quando output_hidden_states=True é passado ou quando config.output_hidden_states=True) — Tupla de torch.Tensor (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma (batch_size, sequence_length, hidden_size).

    Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.

  • attentions (tuple(torch.Tensor), opcional, retornado quando output_attentions=True é passado ou quando config.output_attentions=True) — Tupla de torch.Tensor (um para cada camada) com forma (batch_size, num_heads, sequence_length, sequence_length).

    Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção.

  • audio_hidden_states (torch.Tensor, opcional) — Estados ocultos de áudio projetados.

VoxtralForConditionalGeneration

classe transformers.VoxtralForConditionalGeneration

< >

( config: VoxtralConfig )

Parâmetros

  • config (VoxtralConfig) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.

O modelo Voxtral, que consiste em um codificador Whisper, um projetor multimodal e um modelo de linguagem Llama.

Este modelo herda de PreTrainedModel. Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.)

Este modelo também é uma subclasse de torch.nn.Module do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.

forward

< >

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

Parâmetros

  • input_ids (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Índices dos tokens da sequência de entrada no vocabulário. O padding será ignorado por padrão.

    Os índices podem ser obtidos usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() e PreTrainedTokenizer.call() para mais detalhes.

    O que são IDs de entrada?

  • input_features (torch.Tensor de forma (batch_size, sequence_length, feature_dim), opcional) — Os tensores correspondentes às características de áudio de entrada. As características de áudio podem ser obtidas usando WhisperFeatureExtractor. Consulte WhisperFeatureExtractor.call() para mais detalhes (VoxtralProcessor usa WhisperFeatureExtractor para processar áudios).
  • attention_mask (torch.Tensor de forma (batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em [0, 1]:
    • 1 para tokens que não estão mascarados,
    • 0 para tokens que estão mascarados.

    O que são máscaras de atenção?

  • position_ids (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Índices das posições dos tokens de cada sequência de entrada nos embeddings de posição. Selecionados no intervalo [0, config.n_positions - 1].

    O que são IDs de posição?

  • past_key_values (~cache_utils.Cache, opcional) — Estados ocultos pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste no past_key_values retornado pelo modelo em uma etapa anterior da decodificação, quando use_cache=True ou config.use_cache=True.

    Apenas uma instância de Cache é permitida como entrada, consulte nosso guia de cache de kv. Se nenhum past_key_values for passado, DynamicCache será inicializado por padrão.

    O modelo sairá no mesmo formato de cache que é fornecido como entrada.

    Se past_key_values forem usados, espera-se que o usuário insira apenas os input_ids não processados (aqueles que não têm seus estados de chave e valor passados fornecidos a este modelo) com a forma (batch_size, unprocessed_length), em vez de todos os input_ids com a forma (batch_size, sequence_length).

  • inputs_embeds (torch.Tensor de forma (batch_size, sequence_length, hidden_size), opcional) — Opcionalmente, em vez de passar input_ids, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices de input_ids nos vetores associados do que a matriz de busca de incorporação interna do modelo.
  • labels (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Rótulos para o cálculo da perda de modelagem de linguagem mascarada. Os índices devem estar em [0, ..., config.vocab_size] ou ser -100 (veja a docstring de input_ids). Tokens com índices definidos como -100 são ignorados (mascarados); a perda é calculada apenas para os tokens com rótulos em [0, ..., config.vocab_size].
  • use_cache (bool, opcional) — Se definido como True, os estados de chave-valor past_key_values são retornados e podem ser usados para acelerar a decodificação (veja past_key_values).
  • logits_to_keep (Union[int, torch.Tensor], opcional, padrão 0) — Se for um int, calcula os logits para os últimos logits_to_keep tokens. Se for 0, calcula os logits para todos os input_ids (caso especial). Apenas os logits do último token são necessários para a geração, e calculá-los apenas para esse token pode economizar memória, o que se torna bastante significativo para sequências longas ou tamanho de vocabulário grande. Se for um torch.Tensor, deve ser 1D, correspondendo aos índices a serem mantidos na dimensão de comprimento da sequência. Isso é útil ao usar o formato de tensor empacotado (uma única dimensão para lote e comprimento da sequência).

Retorna

CausalLMOutputWithPast ou tuple(torch.Tensor)

Um CausalLMOutputWithPast ou uma tupla de torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários elementos, dependendo da configuração (VoxtralConfig) e das entradas.

O método forward de VoxtralForConditionalGeneration substitui o método especial __call__.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de Module em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

  • loss (torch.Tensor de forma (1,), opcional, retornado quando labels é fornecido) — Perda de modelagem de linguagem (para previsão do próximo token).

  • logits (torch.Tensor de forma (batch_size, sequence_length, config.vocab_size)) — Pontuações de previsão da cabeça de modelagem de linguagem (pontuações para cada token do vocabulário antes do SoftMax).

  • past_key_values (Cache, opcional, retornado quando use_cache=True é passado ou quando config.use_cache=True) — É uma instância de Cache. Para mais detalhes, consulte nosso guia de cache kv.

    Contém estados ocultos pré-computados (chaves e valores nos blocos de autoatenção) que podem ser usados (veja a entrada past_key_values) para acelerar a decodificação sequencial.

  • hidden_states (tuple(torch.Tensor), opcional, retornado quando output_hidden_states=True é passado ou quando config.output_hidden_states=True) — Tupla de torch.Tensor (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma (batch_size, sequence_length, hidden_size).

    Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.

  • attentions (tuple(torch.Tensor), opcional, retornado quando output_attentions=True é passado ou quando config.output_attentions=True) — Tupla de torch.Tensor (um para cada camada) com forma (batch_size, num_heads, sequence_length, sequence_length).

    Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção.

Exemplo:

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

< >

( *args**kwargs )

Update on GitHub