Transformers documentation
Ajouter des composants de traitement audio
Ajouter des composants de traitement audio
Les modèles audio nécessitent un extracteur de caractéristiques accessible via le point d'entrée AutoFeatureExtractor.
Pour les étapes de modèle et de configuration, suivez d'abord le guide modulaire.
Extracteur de caractéristiques
Ajoutez un extracteur de caractéristiques lorsque le modèle consomme de l’audio brut ou des caractéristiques dérivées de l’audio.
Créez feature_extraction_<model_name>.py dans le répertoire du modèle. Héritez de SequenceFeatureExtractor afin que la nouvelle classe bénéficie du comportement partagé de padding, de troncature, de sauvegarde et de chargement.
from ...feature_extraction_sequence_utils import SequenceFeatureExtractor
class MyModelFeatureExtractor(SequenceFeatureExtractor):
model_input_names = ["input_features", "attention_mask"]
def __init__(self, feature_size=80, sampling_rate=16000, padding_value=0.0, **kwargs):
super().__init__(feature_size=feature_size, sampling_rate=sampling_rate, padding_value=padding_value, **kwargs)
def __call__(self, raw_speech, sampling_rate=None, **kwargs):
if sampling_rate is not None and sampling_rate != self.sampling_rate:
raise ValueError(f"`sampling_rate` must be {self.sampling_rate}, but got {sampling_rate}.")
# Convert raw_speech to model features here.
...Gardez le constructeur petit et sérialisable. Stockez chaque valeur nécessaire pour reproduire le prétraitement en tant qu’attribut d’instance, et évitez de stocker des valeurs propres à l’exécution, telles que des fichiers ouverts, des appareils ou des tableaux audio décodés.
La méthode __call__ doit valider le taux d'échantillonnage d'entrée lorsque les utilisateurs transmettent sampling_rate. Si le taux d'entrée diffère du taux attendu par le modèle, lever une erreur au lieu de rééchantillonner silencieusement.
Enregistrez l’extracteur de caractéristiques avec le point de contrôle en l’instantiant dans le script de conversion et en appelant save_pretrained(). Ne créez ni ne modifiez manuellement les fichiers de configuration de prétraitement.
Voir Gemma4AudioFeatureExtractor pour référence.
Enregistrer les classes
Ajoutez les nouvelles classes à __all__ en bas du fichier, puis régénérez __init__.py avec :
python utils/check_inits.py --fix_and_overwrite
Associez la nouvelle classe à la configuration du modèle afin que AutoFeatureExtractor puisse la charger. Ajoutez une entrée à FEATURE_EXTRACTOR_MAPPING_NAMES dans src/transformers/models/auto/feature_extraction_auto.py, en suivant le modèle des entrées voisines. Vérifiez ensuite que le type de modèle y figure sous FEATURE_EXTRACTOR_MAPPING_NAMES pour AutoFeatureExtractor.
FEATURE_EXTRACTOR_MAPPING_NAMESpour AutoFeatureExtractor
Tests
Ajoutez des tests pour chaque composant de traitement audio dans le répertoire de tests du modèle. Les tests de l’extracteur de caractéristiques se trouvent généralement dans tests/models/<model_name>/test_feature_extraction_<model_name>.py.
Pour les extracteurs de caractéristiques qui héritent de SequenceFeatureExtractor, héritez de SequenceFeatureExtractionTestMixin. Le mixin couvre le comportement d'enregistrement et de chargement, le bourrage (padding), la troncature, la conversion en tenseurs et les propriétés courantes des extracteurs de caractéristiques. Fournissez un objet tester avec prepare_feat_extract_dict() et prepare_inputs_for_common() afin que le mixin puisse instancier l'extracteur de caractéristiques et construire de courtes entrées audio factices.
from ...test_sequence_feature_extraction_common import SequenceFeatureExtractionTestMixin
class MyModelFeatureExtractionTest(SequenceFeatureExtractionTestMixin, unittest.TestCase):
feature_extraction_class = MyModelFeatureExtractor
def setUp(self):
self.feat_extract_tester = MyModelFeatureExtractionTester(self)Ajoutez des tests ciblés pour le comportement spécifique au modèle dont le mixin n’a pas connaissance. Pour les extracteurs de caractéristiques audio, cela signifie généralement vérifier la forme des caractéristiques renvoyée par __call__, valider qu’un sampling_rate incorrect provoque une erreur, et vérifier toute normalisation ou calcul de caractéristique personnalisé.
Si le modèle dispose également d'un ProcessorMixin qui encapsule l'extracteur de caractéristiques, ajoutez tests/models/<model_name>/test_processing_<model_name>.py et héritez de ProcessorTesterMixin. Définissez processor_class et surchargez les méthodes de classe _setup_<component>() pour les composants qui ne peuvent pas être construits sans arguments. Utilisez _setup_test_attributes() pour exposer les jetons de substitution utilisés par les tests de processeur communs.
from ...test_processing_common import ProcessorTesterMixin
class MyModelProcessorTest(ProcessorTesterMixin, unittest.TestCase):
processor_class = MyModelProcessor
@classmethod
def _setup_feature_extractor(cls):
return cls._get_component_class_from_processor("feature_extractor")(sampling_rate=16000)
@classmethod
def _setup_test_attributes(cls, processor):
cls.audio_token = getattr(processor, "audio_token", "")Étapes suivantes
- Lisez le guide Génération automatique des docstrings pour générer automatiquement des docstrings cohérentes avec
@auto_docstring. - Consultez le guide Extracteurs de caractéristiques pour le comportement de prétraitement destiné aux utilisateurs.