# Moonshine [Moonshine](https://huggingface.co/papers/2410.15608) est un modèle de reconnaissance vocale encodeur-décodeur optimisé pour la transcription en temps réel et la reconnaissance de commandes vocales. Plutôt que d'utiliser des embeddings de position absolus traditionnels, Moonshine utilise le Rotary Position Embedding (RoPE) pour traiter des énoncés de longueurs variables sans recourir au padding. Cela améliore l'efficacité lors de l'inférence, ce qui en fait un choix idéal pour les appareils aux ressources limitées. Vous pouvez trouver tous les points de contrôle originaux de Moonshine sous l'organisation [Useful Sensors](https://huggingface.co/UsefulSensors). > [!TIP] > Cliquez sur les modèles Moonshine dans la barre latérale droite pour plus d’exemples sur la façon d’appliquer Moonshine à différentes tâches de reconnaissance vocale. L'exemple ci-dessous montre comment transcrire la parole en texte avec [Pipeline](/docs/transformers/main/fr/main_classes/pipelines#transformers.Pipeline) ou la classe [AutoModel](/docs/transformers/main/fr/model_doc/auto#transformers.AutoModel). ```python from transformers import pipeline pipeline = pipeline( task="automatic-speech-recognition", model="UsefulSensors/moonshine-base", device=0 ) pipeline("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac") ``` ```python from datasets import load_dataset from transformers import AutoProcessor, MoonshineForConditionalGeneration processor = AutoProcessor.from_pretrained("UsefulSensors/moonshine-base") model = MoonshineForConditionalGeneration.from_pretrained("UsefulSensors/moonshine-base", device_map="auto") ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", split="validation") audio_sample = ds[0]["audio"] input_features = processor( audio_sample["array"], sampling_rate=audio_sample["sampling_rate"], return_tensors="pt" ) input_features = input_features.to(model.device, dtype=model.dtype) predicted_ids = model.generate(**input_features, cache_implementation="static") transcription = processor.batch_decode(predicted_ids, skip_special_tokens=True) print(transcription) ``` ## MoonshineConfig[[transformers.MoonshineConfig]] #### transformers.MoonshineConfig[[transformers.MoonshineConfig]] ```python transformers.MoonshineConfig(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, 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, is_encoder_decoder: bool = True, vocab_size: int = 32768, hidden_size: int = 288, intermediate_size: int = 1152, encoder_num_hidden_layers: int = 6, decoder_num_hidden_layers: int = 6, encoder_num_attention_heads: int = 8, decoder_num_attention_heads: int = 8, encoder_num_key_value_heads: int | None = None, decoder_num_key_value_heads: int | None = None, pad_head_dim_to_multiple_of: int | None = None, encoder_hidden_act: str = 'gelu', decoder_hidden_act: str = 'silu', max_position_embeddings: int = 512, initializer_range: float = 0.02, decoder_start_token_id: int = 1, use_cache: bool = True, rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None, attention_bias: bool = False, attention_dropout: float | int = 0.0, bos_token_id: int | None = 1, eos_token_id: int | list[int] | None = 2, pad_token_id: int | None = None, tie_word_embeddings: bool = True) ``` [Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/moonshine/configuration_moonshine.py#L30) **Paramètres :** is_encoder_decoder (`bool`, *facultatif*, valeur par défaut `True`) : Indique si le modèle est utilisé comme encodeur/décodeur ou non. vocab_size (`int`, *facultatif*, valeur par défaut `32768`) : Taille du vocabulaire du modèle. Définit le nombre de jetons différents qui peuvent être représentés par `input_ids`. hidden_size (`int`, *facultatif*, par défaut `288`) : Dimension des représentations cachées. intermediate_size (`int`, *facultatif*, par défaut `1152`) : Dimension des représentations MLP. encoder_num_hidden_layers (`int`, *facultatif*, valeur par défaut `6`) : Nombre de couches cachées dans l'encodeur Transformer. Utilise la même valeur que `num_layers` si non défini. decoder_num_hidden_layers (`int`, *facultatif*, valeur par défaut `6`) : Nombre de couches cachées dans le décodeur Transformer. Utilise la même valeur que `num_layers` si non défini. encoder_num_attention_heads (`int`, *facultatif*, valeur par défaut `8`) : Nombre de têtes d'attention pour chaque couche d'attention dans l'encodeur Transformer. decoder_num_attention_heads (`int`, *facultatif*, valeur par défaut `8`) : Nombre de têtes d'attention pour chaque couche d'attention du décodeur Transformer. encoder_num_key_value_heads (`int`, *facultatif*) : C'est le nombre de têtes key_value à utiliser pour implémenter l'attention Grouped Query. Si `encoder_num_key_value_heads=encoder_num_attention_heads`, le modèle utilisera l'attention Multi Head (MHA) ; si `encoder_num_key_value_heads=1`, il utilisera l'attention Multi Query (MQA) ; sinon, c'est la GQA qui est utilisée. Lors de la conversion d'un checkpoint multi-têtes vers un checkpoint GQA, chaque tête clé et valeur de groupe doit être construite en effectuant un meanpooling de toutes les têtes d'origine appartenant à ce groupe. Pour plus de détails, consultez [cet article](https://huggingface.co/papers/2305.13245). S'il n'est pas spécifié, la valeur par défaut est `num_attention_heads`. decoder_num_key_value_heads (`int`, *facultatif*) : C'est le nombre de têtes key_value à utiliser pour implémenter l'attention Grouped Query. Si `decoder_num_key_value_heads=decoder_num_attention_heads`, le modèle utilisera l'attention Multi Head (MHA), si `decoder_num_key_value_heads=1` le modèle utilisera l'attention Multi Query (MQA), sinon GQA est utilisée. Lors de la conversion d'un checkpoint multi-têtes vers un checkpoint GQA, chaque tête key et value de groupe doit être construite en effectuant un meanpooling de toutes les têtes d'origine au sein de ce groupe. Pour plus de détails, consultez [cet article](https://huggingface.co/papers/2305.13245). S'il n'est pas spécifié, la valeur par défaut est `decoder_num_attention_heads`. pad_head_dim_to_multiple_of (`int`, *facultatif*) : Ajuste la dimension de la tête dans l'encodeur et le décodeur au multiple supérieur de cette valeur. Nécessaire pour utiliser certaines implémentations d'attention optimisées. encoder_hidden_act (`str` ou `function`, *facultatif*, par défaut `"gelu"`) : Fonction d'activation non linéaire (fonction ou chaîne de caractères) dans l'encodeur. decoder_hidden_act (`str` ou `function`, *facultatif*, par défaut `"silu"`) : La fonction d'activation non linéaire (fonction ou chaîne de caractères) dans le décodeur. max_position_embeddings (`int`, *facultatif*, valeur par défaut `512`) : La longueur de séquence maximale avec laquelle ce modèle pourrait être utilisé. initializer_range (`float`, *facultatif*, valeur par défaut `0.02`) : L'écart-type de la truncated_normal_initializer utilisé pour l'initialisation de toutes les matrices de poids. decoder_start_token_id (`int`, *facultatif*, valeur par défaut `1`) : si un modèle encodeur-décodeur commence le décodage avec un jeton différent de `bos`, l'identifiant de ce jeton. use_cache (`bool`, *facultatif*, valeur par défaut `True`) : Indique si le modèle doit retourner les dernières attentions clés/valeurs (non utilisé par tous les modèles). Pertinent uniquement si `config.is_decoder=True` ou si le modèle est un modèle génératif de type décodeur uniquement. rope_parameters (`Union[~modeling_rope_utils.RopeParameters, dict]`, *facultatif*) : Dictionnaire contenant les paramètres de configuration pour les embeddings RoPE. Le dictionnaire doit contenir une valeur pour `rope_theta` et, le cas échéant, les paramètres utilisés pour le mise à l'échelle si vous souhaitez utiliser RoPE avec des `max_position_embeddings` plus longs. attention_bias (`bool`, *facultatif*, valeur par défaut `False`) : Indique s'il faut utiliser un biais dans les couches de projection de requête, de clé, de valeur et de sortie lors de l'auto-attention. attention_dropout (`Union[float, int]`, *facultatif*, valeur par défaut `0.0`) : Le taux de dropout appliqué aux probabilités d'attention. bos_token_id (`int`, *facultatif*, valeur par défaut `1`) : Identifiant du jeton utilisé pour le début de flux dans le vocabulaire. eos_token_id (`Union[int, list[int]]`, *facultatif*, valeur par défaut `2`) : Identifiant de jeton utilisé pour la fin de flux dans le vocabulaire. pad_token_id (`int`, *facultatif*) : Identifiant de jeton utilisé pour le bourrage dans le vocabulaire. tie_word_embeddings (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut lier les embeddings de poids selon la correspondance `tied_weights_keys` du modèle. Ceci est la classe de configuration destinée à stocker la configuration d'un MoonshineModel. Elle est utilisée pour instancier un modèle Moonshine en fonction des arguments spécifiés, en définissant l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de [UsefulSensors/moonshine-tiny](https://huggingface.co/UsefulSensors/moonshine-tiny) Les objets de configuration héritent de [PreTrainedConfig](/docs/transformers/main/fr/main_classes/configuration#transformers.PreTrainedConfig) et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de [PreTrainedConfig](/docs/transformers/main/fr/main_classes/configuration#transformers.PreTrainedConfig) pour plus d’informations. Exemple : ```python >>> from transformers import MoonshineModel, MoonshineConfig >>> # Initializing a Moonshine style configuration >>> configuration = MoonshineConfig().from_pretrained("UsefulSensors/moonshine-tiny") >>> # Initializing a model from the configuration >>> model = MoonshineModel(configuration) >>> # Accessing the model configuration >>> configuration = model.config ``` ## MoonshineModel[[transformers.MoonshineModel]] #### transformers.MoonshineModel[[transformers.MoonshineModel]] ```python transformers.MoonshineModel(config: MoonshineConfig) ``` [Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/moonshine/modeling_moonshine.py#L703) **Paramètres :** config ([MoonshineConfig](/docs/transformers/main/fr/model_doc/moonshine#transformers.MoonshineConfig)) : Classe de configuration du modèle contenant tous les paramètres du modèle. L'initialisation à partir d'un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode [from_pretrained()](/docs/transformers/main/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle. Le modèle Moonshine brut, qui produit des états cachés bruts sans aucune tête spécifique au sommet. Ce modèle hérite de [PreTrainedModel](/docs/transformers/main/fr/main_classes/model#transformers.PreTrainedModel). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, l'élagage des têtes, etc.). Ce modèle est également une sous-classe de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l’utilisation et le comportement généraux. #### forward[[transformers.MoonshineModel.forward]] ```python forward(input_values: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.LongTensor] = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: tuple[tuple[torch.Tensor]] | None = None, past_key_values: transformers.cache_utils.EncoderDecoderCache | None = None, decoder_inputs_embeds: tuple[torch.Tensor] | None = None, decoder_position_ids: tuple[torch.LongTensor] | None = None, use_cache: bool | None = None, **kwargs: *) ``` [Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/moonshine/modeling_moonshine.py#L732) **Paramètres :** input_values (`torch.Tensor` de forme `(batch_size, audio_length)`) : Valeurs flottantes de la forme d’onde brute de la parole. La forme d’onde brute peut être obtenue en chargeant un fichier audio `.flac` ou `.wav` dans un tableau de type `list[float]`, un `numpy.ndarray` ou un `torch.Tensor`, *par exemple* via la bibliothèque torchcodec (`pip install torchcodec`) ou la bibliothèque soundfile (`pip install soundfile`). Pour préparer le tableau en `input_values`, il convient d’utiliser [AutoFeatureExtractor](/docs/transformers/main/fr/model_doc/auto#transformers.AutoFeatureExtractor) pour l’ajustement (padding) et la conversion en tenseur de type `torch.Tensor`. attention_mask (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Masque pour éviter d'appliquer l'attention aux indices des jetons de bourrage. Les valeurs du masque sont choisies dans `[0, 1]` : - 1 pour les jetons qui ne sont **pas masqués**, - 0 pour les jetons qui sont **masqués**. [Qu'est-ce qu'un masque d'attention ?](../glossary#attention-mask) decoder_input_ids (`torch.LongTensor` de forme `(batch_size, target_sequence_length)`, *facultatif*) : Indices des jetons de la séquence d'entrée du décodeur dans le vocabulaire. Les indices peuvent être obtenus à l'aide de [AutoTokenizer](/docs/transformers/main/fr/model_doc/auto#transformers.AutoTokenizer). Consultez [PreTrainedTokenizer.encode()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) et [PreTrainedTokenizer.__call__()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) pour plus de détails. [Quelles sont les identifiants d'entrée du décodeur ?](../glossary#decoder-input-ids) decoder_attention_mask (`torch.LongTensor` de forme `(batch_size, target_sequence_length)`, *facultatif*) : Masque pour éviter d'appliquer l'attention à certains indices de jetons. Par défaut, un masque causal est utilisé afin de s'assurer que le modèle ne peut consulter que les entrées précédentes pour prédire le futur. encoder_outputs (`tuple[tuple[torch.Tensor]]`, *facultatif*) : le tuple est composé de (`last_hidden_state`, *facultatif* : `hidden_states`, *facultatif* : `attentions`) `last_hidden_state` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) est une séquence d'états cachés à la sortie de la dernière couche de l'encodeur. Utilisé dans l'attention croisée du décodeur. past_key_values (`~cache_utils.EncoderDecoderCache`, *facultatif*) : États cachés précalculés (clés et valeurs dans les blocs d'auto-attention et dans les blocs d'attention croisée) qui peuvent être utilisés pour accélérer le décodage séquentiel. Il s'agit généralement des `past_key_values` renvoyés par le modèle à une étape antérieure du décodage, lorsque `use_cache=True` ou `config.use_cache=True`. Seule une instance de [Cache](/docs/transformers/main/fr/internal/generation_utils#transformers.Cache) est autorisée en entrée, voir notre [guide sur le cache kv](https://huggingface.co/docs/transformers/en/kv_cache). Si aucun `past_key_values` n'est transmis, [DynamicCache](/docs/transformers/main/fr/internal/generation_utils#transformers.DynamicCache) est initialisé par défaut. Le modèle renverra le même format de cache que celui fourni en entrée. Si `past_key_values` sont utilisés, l'utilisateur doit fournir uniquement les `input_ids` non traités (ceux pour lesquels les états de clés et de valeurs passées ne sont pas fournis à ce modèle) de forme `(batch_size, unprocessed_length)` au lieu de tous les `input_ids` de forme `(batch_size, sequence_length)`. decoder_inputs_embeds (`tuple[torch.Tensor]` de forme `(batch_size, target_sequence_length, hidden_size)`, *facultatif*) : Facultativement, au lieu de passer `decoder_input_ids`, vous pouvez choisir de passer directement une représentation intégrée. Si `past_key_values` est utilisé, il est facultatif de n'entrer que les derniers `decoder_inputs_embeds` (voir `past_key_values`). Cela est utile si vous souhaitez un meilleur contrôle sur la conversion des indices `decoder_input_ids` en vecteurs associés que la matrice de recherche d'intégration interne du modèle. Si `decoder_input_ids` et `decoder_inputs_embeds` sont tous deux non définis, `decoder_inputs_embeds` prend la valeur de `inputs_embeds`. decoder_position_ids (`torch.LongTensor` de forme `(batch_size, target_sequence_length)`) : Indices des positions des jetons de chaque séquence d'entrée dans les embeddings de position. Utilisés pour calculer les embeddings de position jusqu'à `config.decoder_config.max_position_embeddings` use_cache (`bool`, *facultatif*) : Si défini sur `True`, les états clé-valeur de `past_key_values` sont renvoyés et peuvent être utilisés pour accélérer le décodage (voir `past_key_values`). **Retourne :** [Seq2SeqModelOutput](/docs/transformers/main/fr/main_classes/output#transformers.modeling_outputs.Seq2SeqModelOutput) ou `tuple(torch.Tensor)` Un [Seq2SeqModelOutput](/docs/transformers/main/fr/main_classes/output#transformers.modeling_outputs.Seq2SeqModelOutput) ou un tuple de `torch.Tensor` (si `return_dict=False` est passé ou lorsque `config.return_dict=False`) comprenant divers éléments selon la configuration ([MoonshineConfig](/docs/transformers/main/fr/model_doc/moonshine#transformers.MoonshineConfig)) et les entrées. La méthode forward du [MoonshineModel](/docs/transformers/main/fr/model_doc/moonshine#transformers.MoonshineModel) redéfinit la méthode spéciale `__call__`. Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance `Module` plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement. - **last_hidden_state** (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`) -- Séquence d'états cachés à la sortie de la dernière couche du décodeur du modèle. Si `past_key_values` est utilisé, seule la dernière hidden-state des séquences de forme `(batch_size, 1, hidden_size)` est renvoyée. - **past_key_values** (`EncoderDecoderCache`, *facultatif*, renvoyé lorsque `use_cache=True` est passé ou lorsque `config.use_cache=True`) -- Il s'agit d'une instance de [EncoderDecoderCache](/docs/transformers/main/fr/internal/generation_utils#transformers.EncoderDecoderCache). Pour plus de détails, consultez notre [guide sur le cache kv](https://huggingface.co/docs/transformers/en/kv_cache). Contient des états cachés précalculés (clés et valeurs dans les blocs d'auto-attention et dans les blocs d'attention croisée) qui peuvent être utilisés (voir l'entrée `past_key_values`) pour accélérer le décodage séquentiel. - **decoder_hidden_states** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings, si le modèle possède une couche d’embedding, + un pour la sortie de chaque couche) de forme `(batch_size, sequence_length, hidden_size)`. États cachés du décodeur à la sortie de chaque couche, plus les sorties d'incorporation initiale facultatives. - **decoder_attentions** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`. Poids d'attention du décodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention. - **cross_attentions** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`. Poids d'attention de la couche d'attention croisée du décodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'attention croisée. - **encoder_last_hidden_state** (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) -- Séquence d'états cachés à la sortie de la dernière couche de l'encodeur du modèle. - **encoder_hidden_states** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings, si le modèle possède une couche d’embedding, + un pour la sortie de chaque couche) de forme `(batch_size, sequence_length, hidden_size)`. États cachés de l'encodeur à la sortie de chaque couche, plus les sorties d'incorporation initiales facultatives. - **encoder_attentions** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`. Poids d'attention de l'encodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention. Exemple : ```python >>> import torch >>> from transformers import AutoFeatureExtractor, MoonshineModel >>> from datasets import load_dataset >>> model = MoonshineModel.from_pretrained("UsefulSensors/moonshine-tiny") >>> feature_extractor = AutoFeatureExtractor.from_pretrained("UsefulSensors/moonshine-tiny") >>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation") >>> inputs = feature_extractor(ds[0]["audio"]["array"], return_tensors="pt") >>> input_values = inputs.input_values >>> decoder_input_ids = torch.tensor([[1, 1]]) * model.config.decoder_start_token_id >>> last_hidden_state = model(input_values, decoder_input_ids=decoder_input_ids).last_hidden_state >>> list(last_hidden_state.shape) [1, 2, 288] ``` #### _mask_input_features[[transformers.MoonshineModel._mask_input_features]] ```python _mask_input_features() ``` [Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/moonshine/modeling_moonshine.py#L725) Les masques extraient les caractéristiques le long de l'axe temporel et/ou de l'axe des caractéristiques selon [SpecAugment](https://huggingface.co/papers/1904.08779). ## MoonshineForConditionalGeneration[[transformers.MoonshineForConditionalGeneration]] #### transformers.MoonshineForConditionalGeneration[[transformers.MoonshineForConditionalGeneration]] ```python transformers.MoonshineForConditionalGeneration(config: MoonshineConfig) ``` [Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/moonshine/modeling_moonshine.py#L825) **Paramètres :** config ([MoonshineConfig](/docs/transformers/main/fr/model_doc/moonshine#transformers.MoonshineConfig)) : Classe de configuration du modèle contenant tous les paramètres du modèle. L'initialisation à partir d'un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode [from_pretrained()](/docs/transformers/main/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle. Le modèle Moonshine avec une tête de modélisation de langage. Peut être utilisé pour la reconnaissance automatique de la parole. Ce modèle hérite de [PreTrainedModel](/docs/transformers/main/fr/main_classes/model#transformers.PreTrainedModel). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, l'élagage des têtes, etc.). Ce modèle est également une sous-classe de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l’utilisation et le comportement généraux. #### forward[[transformers.MoonshineForConditionalGeneration.forward]] ```python forward(input_values: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.LongTensor] = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: tuple[tuple[torch.Tensor]] | None = None, past_key_values: transformers.cache_utils.EncoderDecoderCache | None = None, decoder_inputs_embeds: tuple[torch.Tensor] | None = None, decoder_position_ids: tuple[torch.LongTensor] | None = None, use_cache: bool | None = None, labels: typing.Optional[torch.LongTensor] = None, **kwargs: *) ``` [Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/moonshine/modeling_moonshine.py#L845) **Paramètres :** input_values (`torch.Tensor` de forme `(batch_size, audio_length)`) : Valeurs flottantes de la forme d’onde brute de la parole. La forme d’onde brute peut être obtenue en chargeant un fichier audio `.flac` ou `.wav` dans un tableau de type `list[float]`, un `numpy.ndarray` ou un `torch.Tensor`, *par exemple* via la bibliothèque torchcodec (`pip install torchcodec`) ou la bibliothèque soundfile (`pip install soundfile`). Pour préparer le tableau en `input_values`, il convient d’utiliser [AutoFeatureExtractor](/docs/transformers/main/fr/model_doc/auto#transformers.AutoFeatureExtractor) pour l’ajustement (padding) et la conversion en tenseur de type `torch.Tensor`. attention_mask (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Masque pour éviter d'appliquer l'attention aux indices des jetons de bourrage. Les valeurs du masque sont choisies dans `[0, 1]` : - 1 pour les jetons qui ne sont **pas masqués**, - 0 pour les jetons qui sont **masqués**. [Qu'est-ce qu'un masque d'attention ?](../glossary#attention-mask) decoder_input_ids (`torch.LongTensor` de forme `(batch_size, target_sequence_length)`, *facultatif*) : Indices des jetons de la séquence d'entrée du décodeur dans le vocabulaire. Les indices peuvent être obtenus à l'aide de [AutoTokenizer](/docs/transformers/main/fr/model_doc/auto#transformers.AutoTokenizer). Consultez [PreTrainedTokenizer.encode()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) et [PreTrainedTokenizer.__call__()](/docs/transformers/main/fr/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) pour plus de détails. [Quelles sont les identifiants d'entrée du décodeur ?](../glossary#decoder-input-ids) decoder_attention_mask (`torch.LongTensor` de forme `(batch_size, target_sequence_length)`, *facultatif*) : Masque pour éviter d'appliquer l'attention à certains indices de jetons. Par défaut, un masque causal est utilisé afin de s'assurer que le modèle ne peut consulter que les entrées précédentes pour prédire le futur. encoder_outputs (`tuple[tuple[torch.Tensor]]`, *facultatif*) : le tuple est composé de (`last_hidden_state`, *facultatif* : `hidden_states`, *facultatif* : `attentions`) `last_hidden_state` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) est une séquence d'états cachés à la sortie de la dernière couche de l'encodeur. Utilisé dans l'attention croisée du décodeur. past_key_values (`~cache_utils.EncoderDecoderCache`, *facultatif*) : États cachés précalculés (clés et valeurs dans les blocs d'auto-attention et dans les blocs d'attention croisée) qui peuvent être utilisés pour accélérer le décodage séquentiel. Il s'agit généralement des `past_key_values` renvoyés par le modèle à une étape antérieure du décodage, lorsque `use_cache=True` ou `config.use_cache=True`. Seule une instance de [Cache](/docs/transformers/main/fr/internal/generation_utils#transformers.Cache) est autorisée en entrée, voir notre [guide sur le cache kv](https://huggingface.co/docs/transformers/en/kv_cache). Si aucun `past_key_values` n'est transmis, [DynamicCache](/docs/transformers/main/fr/internal/generation_utils#transformers.DynamicCache) est initialisé par défaut. Le modèle renverra le même format de cache que celui fourni en entrée. Si `past_key_values` sont utilisés, l'utilisateur doit fournir uniquement les `input_ids` non traités (ceux pour lesquels les états de clés et de valeurs passées ne sont pas fournis à ce modèle) de forme `(batch_size, unprocessed_length)` au lieu de tous les `input_ids` de forme `(batch_size, sequence_length)`. decoder_inputs_embeds (`tuple[torch.Tensor]` de forme `(batch_size, target_sequence_length, hidden_size)`, *facultatif*) : Facultativement, au lieu de passer `decoder_input_ids`, vous pouvez choisir de passer directement une représentation intégrée. Si `past_key_values` est utilisé, il est facultatif de n'entrer que les derniers `decoder_inputs_embeds` (voir `past_key_values`). Cela est utile si vous souhaitez un meilleur contrôle sur la conversion des indices `decoder_input_ids` en vecteurs associés que la matrice de recherche d'intégration interne du modèle. Si `decoder_input_ids` et `decoder_inputs_embeds` sont tous deux non définis, `decoder_inputs_embeds` prend la valeur de `inputs_embeds`. decoder_position_ids (`torch.LongTensor` de forme `(batch_size, target_sequence_length)`) : Indices des positions des jetons de chaque séquence d'entrée dans les embeddings de position. Utilisés pour calculer les embeddings de position jusqu'à `config.decoder_config.max_position_embeddings` use_cache (`bool`, *facultatif*) : Si défini sur `True`, les états clé-valeur de `past_key_values` sont renvoyés et peuvent être utilisés pour accélérer le décodage (voir `past_key_values`). labels (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Étiquettes pour le calcul de la perte de modélisation de langage masquée. Les indices doivent être compris dans `[0, ..., config.vocab_size]` ou égaux à -100 (voir la docstring de `input_ids`). Les jetons dont l'indice est défini sur `-100` sont ignorés (masqués) ; la perte n'est calculée que pour les jetons dont l'étiquette est comprise dans `[0, ..., config.vocab_size]`. **Retourne :** [Seq2SeqLMOutput](/docs/transformers/main/fr/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) ou `tuple(torch.Tensor)` Un [Seq2SeqLMOutput](/docs/transformers/main/fr/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) ou un tuple de `torch.Tensor` (si `return_dict=False` est passé ou lorsque `config.return_dict=False`) comprenant divers éléments en fonction de la configuration ([MoonshineConfig](/docs/transformers/main/fr/model_doc/moonshine#transformers.MoonshineConfig)) et des entrées. La méthode forward de [MoonshineForConditionalGeneration](/docs/transformers/main/fr/model_doc/moonshine#transformers.MoonshineForConditionalGeneration) redéfinit la méthode spéciale `__call__`. Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance `Module` plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement. - **loss** (`torch.Tensor` de forme `(1,)`, *facultatif*, renvoyé lorsque `labels` est fourni) -- Perte de modélisation du langage. - **logits** (`torch.Tensor` de forme `(batch_size, sequence_length, config.vocab_size)`) -- Scores de prédiction de la tête de modélisation du langage (scores pour chaque jeton du vocabulaire avant SoftMax). - **past_key_values** (`EncoderDecoderCache`, *facultatif*, renvoyé lorsque `use_cache=True` est passé ou lorsque `config.use_cache=True`) -- Il s'agit d'une instance de [EncoderDecoderCache](/docs/transformers/main/fr/internal/generation_utils#transformers.EncoderDecoderCache). Pour plus de détails, consultez notre [guide sur le cache kv](https://huggingface.co/docs/transformers/en/kv_cache). Contient des états cachés précalculés (clés et valeurs dans les blocs d'auto-attention et dans les blocs d'attention croisée) qui peuvent être utilisés (voir l'entrée `past_key_values`) pour accélérer le décodage séquentiel. - **decoder_hidden_states** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings, si le modèle possède une couche d’embedding, + un pour la sortie de chaque couche) de forme `(batch_size, sequence_length, hidden_size)`. États cachés du décodeur à la sortie de chaque couche, plus les sorties de l'intégration initiale. - **decoder_attentions** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`. Poids d'attention du décodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention. - **cross_attentions** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`. Poids d'attention de la couche d'attention croisée du décodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'attention croisée. - **encoder_last_hidden_state** (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) -- Séquence d'états cachés à la sortie de la dernière couche de l'encodeur du modèle. - **encoder_hidden_states** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings, si le modèle possède une couche d’embedding, + un pour la sortie de chaque couche) de forme `(batch_size, sequence_length, hidden_size)`. États cachés de l'encodeur à la sortie de chaque couche, plus les sorties des embeddings initiaux. - **encoder_attentions** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`. Poids d'attention de l'encodeur, après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention. Exemple : ```python >>> import torch >>> from transformers import AutoProcessor, MoonshineForConditionalGeneration >>> from datasets import load_dataset >>> processor = AutoProcessor.from_pretrained("UsefulSensors/moonshine-tiny") >>> model = MoonshineForConditionalGeneration.from_pretrained("UsefulSensors/moonshine-tiny") >>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation") >>> inputs = processor(ds[0]["audio"]["array"], return_tensors="pt") >>> input_values = inputs.input_values >>> generated_ids = model.generate(input_values, max_new_tokens=100) >>> transcription = processor.batch_decode(generated_ids, skip_special_tokens=True)[0] >>> transcription 'Mr. Quilter is the apostle of the middle classes, and we are glad to welcome his gospel.' ``` #### generate[[transformers.MoonshineForConditionalGeneration.generate]] ```python generate(inputs: typing.Optional[torch.Tensor] = None, generation_config: transformers.generation.configuration_utils.GenerationConfig | None = None, logits_processor: transformers.generation.logits_process.LogitsProcessorList | None = None, stopping_criteria: transformers.generation.stopping_criteria.StoppingCriteriaList | None = None, prefix_allowed_tokens_fn: collections.abc.Callable[[int, torch.Tensor], list[int]] | None = None, synced_gpus: bool | None = None, assistant_model: typing.Optional[ForwardRef('PreTrainedModel')] = None, streamer: typing.Optional[ForwardRef('BaseStreamer')] = None, negative_prompt_ids: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, custom_generate: str | collections.abc.Callable | None = None, **kwargs) ``` [Source](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/utils.py#L2581) **Paramètres :** inputs (`torch.Tensor` de forme variable selon la modalité, *facultatif*) : La séquence utilisée comme invite pour la génération ou comme entrées du modèle pour l'encodeur. Si `None`, la méthode l'initialise avec `bos_token_id` et une taille de lot de 1. Pour les modèles uniquement décodeurs, `inputs` doit être au format de `input_ids`. Pour les modèles encodeur-décodeur, *inputs* peut représenter l'un des éléments suivants : `input_ids`, `input_values`, `input_features` ou `pixel_values`. generation_config ([GenerationConfig](/docs/transformers/main/fr/main_classes/text_generation#transformers.GenerationConfig), *facultatif*) : La configuration de génération à utiliser comme paramétrage de base pour l'appel de génération. Les `**kwargs` passés à generate qui correspondent aux attributs de `generation_config` les remplaceront. Si `generation_config` n'est pas fourni, la valeur par défaut sera utilisée, avec la priorité de chargement suivante : 1) depuis le fichier modèle `generation_config.json`, s'il existe ; 2) depuis la configuration du modèle. Veuillez noter que les paramètres non spécifiés hériteront des valeurs par défaut de [GenerationConfig](/docs/transformers/main/fr/main_classes/text_generation#transformers.GenerationConfig), dont la documentation doit être consultée pour paramétrer la génération. logits_processor (`LogitsProcessorList`, *facultatif*) : Processeurs de logits personnalisés qui complètent les processeurs de logits par défaut créés à partir des arguments et de la configuration de génération. Si un processeur de logits est transmis qui a déjà été créé avec les arguments ou une configuration de génération, une erreur est levée. Cette fonctionnalité est destinée aux utilisateurs avancés. stopping_criteria (`StoppingCriteriaList`, *facultatif*) : Critères d'arrêt personnalisés qui complètent les critères d'arrêt par défaut construits à partir des arguments et d'une configuration de génération. Si un critère d'arrêt est transmis qui a déjà été créé à partir des arguments ou d'une configuration de génération, une erreur est levée. Si votre critère d'arrêt dépend de l'entrée `scores`, assurez-vous de passer `return_dict_in_generate=True, output_scores=True` à `generate`. Cette fonctionnalité est destinée aux utilisateurs avancés. prefix_allowed_tokens_fn (`Callable[[int, torch.Tensor], list[int]]`, *facultatif*) : Si fournie, cette fonction contraint la recherche par faisceau aux jetons autorisés uniquement à chaque étape. Si elle n'est pas fournie, aucune contrainte n'est appliquée. Cette fonction prend 2 arguments : l'identifiant du lot `batch_id` et `input_ids`. Elle doit retourner une liste des jetons autorisés pour l'étape de génération suivante, conditionnée par l'identifiant du lot `batch_id` et les jetons précédemment générés `inputs_ids`. Cet argument est utile pour la génération contrainte conditionnée par le préfixe, comme décrit dans [Autoregressive Entity Retrieval](https://huggingface.co/papers/2010.00904). synced_gpus (`bool`, *facultatif*) : Indique s'il faut continuer à exécuter la boucle while jusqu'à max_length. Sauf si cette valeur est remplacée, ce drapeau est défini sur `True` lors de l'utilisation de `FullyShardedDataParallel` ou de DeepSpeed ZeRO Stage 3 avec plusieurs GPU, afin d'éviter tout blocage si un GPU termine la génération avant les autres. Sinon, la valeur par défaut est `False`. assistant_model (`PreTrainedModel`, *facultatif*) : Un modèle assistant pouvant être utilisé pour accélérer la génération. Le modèle assistant doit utiliser exactement le même tokenizer. L'accélération est obtenue lorsque la prédiction des jetons candidats par le modèle assistant est beaucoup plus rapide que l'exécution de la génération avec le modèle depuis lequel vous appelez generate. Par conséquent, le modèle assistant doit être beaucoup plus petit. streamer (`BaseStreamer`, *facultatif*) : Objet Streamer qui sera utilisé pour diffuser les séquences générées. Les jetons générés sont transmis via `streamer.put(token_ids)` et le streamer est responsable de tout traitement ultérieur. negative_prompt_ids (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Le prompt négatif requis par certains processeurs tels que CFG. La taille du lot doit correspondre à la taille du lot d'entrée. Il s'agit d'une fonctionnalité expérimentale, susceptible de subir des modifications cassant l'API dans les versions futures. negative_prompt_attention_mask (`torch.LongTensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Attention_mask pour `negative_prompt_ids`. custom_generate (`str` ou `Callable`, *facultatif*) : L'un des éléments suivants : - `str` (nom du dépôt sur le Hugging Face Hub) : exécute la fonction `generate` personnalisée définie dans `custom_generate/generate.py` de ce dépôt, à la place de la méthode standard `generate`. Le dépôt remplace entièrement la logique de génération, et le type de retour peut différer. - `str` (chemin d'accès local au dépôt) : idem, mais à partir d'un chemin local. Les répertoires locaux nécessitent également `trust_remote_code=True`, car le fichier local `custom_generate/generate.py` est exécuté. - `Callable` : `generate` effectue les étapes habituelles de préparation des entrées, puis appelle le callable fourni pour exécuter la boucle de décodage. Pour plus d'informations, consultez [la documentation](../../generation_strategies#custom-generation-methods). kwargs (`dict[str, Any]`, *facultatif*) : Paramétrage ad hoc de `generation_config` et/ou d'autres kwargs spécifiques au modèle qui seront transmis à la fonction `forward` du modèle. Si le modèle est un modèle encoder-décodeur, les kwargs spécifiques à l'encodeur ne doivent pas être préfixés et les kwargs spécifiques au décodeur doivent être préfixés par *decoder_*. **Retourne :** [ModelOutput](/docs/transformers/main/fr/main_classes/output#transformers.utils.ModelOutput) ou `torch.LongTensor` Un [ModelOutput](/docs/transformers/main/fr/main_classes/output#transformers.utils.ModelOutput) (si `return_dict_in_generate=True` ou lorsque `config.return_dict_in_generate=True`) ou un `torch.LongTensor`. Si le modèle n'*est pas* un modèle encodeur-décodeur (`model.config.is_encoder_decoder=False`), les types [ModelOutput](/docs/transformers/main/fr/main_classes/output#transformers.utils.ModelOutput) possibles sont : - [GenerateDecoderOnlyOutput](/docs/transformers/main/fr/internal/generation_utils#transformers.generation.GenerateDecoderOnlyOutput), - [GenerateBeamDecoderOnlyOutput](/docs/transformers/main/fr/internal/generation_utils#transformers.generation.GenerateBeamDecoderOnlyOutput) Si le modèle est un modèle encodeur-décodeur (`model.config.is_encoder_decoder=True`), les types [ModelOutput](/docs/transformers/main/fr/main_classes/output#transformers.utils.ModelOutput) possibles sont : - [GenerateEncoderDecoderOutput](/docs/transformers/main/fr/internal/generation_utils#transformers.generation.GenerateEncoderDecoderOutput), - [GenerateBeamEncoderDecoderOutput](/docs/transformers/main/fr/internal/generation_utils#transformers.generation.GenerateBeamEncoderDecoderOutput) Génère des séquences d'identifiants de jetons pour les modèles dotés d'une tête de modélisation de langage. La plupart des paramètres de contrôle de la génération sont définis dans `generation_config` qui, s'il n'est pas transmis, sera réglé sur la configuration de génération par défaut du modèle. Vous pouvez remplacer n'importe quel `generation_config` en transmettant les paramètres correspondants à generate(), par exemple `.generate(inputs, num_beams=4, do_sample=True)`. Pour un aperçu des stratégies de génération et des exemples de code, consultez le [guide suivant](../generation_strategies).