Agregar componentes de procesamiento de audio

Los modelos de audio requieren un extractor de características accesible a través del punto de entrada AutoFeatureExtractor.

Para los pasos del modelo y la configuración, sigue primero la guía modular.

Extracción de características

Agregue un extractor de características cuando el modelo consuma audio sin procesar o características derivadas del audio.

Cree feature_extraction_<model_name>.py en el directorio del modelo. Herede de SequenceFeatureExtractor para que la nueva clase obtenga el comportamiento compartido de relleno, truncamiento, guardado y carga.

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

Mantenga el constructor pequeño y serializable. Almacene cada valor necesario para reproducir el preprocesamiento como un atributo de instancia y evite almacenar valores solo de tiempo de ejecución, como archivos abiertos, dispositivos o matrices de audio decodificadas.

El método __call__ debe validar la tasa de muestreo de entrada cuando los usuarios pasan sampling_rate. Si la tasa de entrada difiere de la tasa esperada por el modelo, se debe lanzar un error en lugar de re-muestrear silenciosamente.

Guarde el extractor de características junto con el punto de control instanciándolo en el script de conversión y llamando a save_pretrained(). No cree ni edite manualmente los archivos de configuración de preprocesamiento.

Consulte Gemma4AudioFeatureExtractor como referencia.

Registrar las clases

Agrega las nuevas clases a __all__ al final del archivo y, a continuación, regenera __init__.py con:

python utils/check_inits.py --fix_and_overwrite

Mapea la nueva clase a la configuración del modelo para que AutoFeatureExtractor pueda cargarla. Añade una entrada a FEATURE_EXTRACTOR_MAPPING_NAMES en src/transformers/models/auto/feature_extraction_auto.py, siguiendo el patrón de las entradas cercanas. Luego, verifica que el tipo de modelo aparezca allí bajo FEATURE_EXTRACTOR_MAPPING_NAMES para AutoFeatureExtractor.

• FEATURE_EXTRACTOR_MAPPING_NAMES para AutoFeatureExtractor

Pruebas

Agregue pruebas para cada componente de procesamiento de audio en el directorio de pruebas del modelo. Las pruebas del extractor de características suelen estar en tests/models/<model_name>/test_feature_extraction_<model_name>.py.

Para los extractores de características que heredan de SequenceFeatureExtractor, hereda de SequenceFeatureExtractionTestMixin. El mixin cubre el comportamiento de guardado y carga, el relleno, la truncación, la conversión a tensores y las propiedades comunes de los extractores de características. Proporciona un objeto tester con prepare_feat_extract_dict() y prepare_inputs_for_common() para que el mixin pueda instanciar el extractor de características y construir entradas de audio falsas cortas.

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)

Añada pruebas centradas en el comportamiento específico del modelo que el mixin no conoce. Para los extractores de características de audio, eso suele implicar verificar la forma de las características devueltas por __call__, validar que una sampling_rate incorrecta provoque un error y comprobar cualquier normalización o cálculo de características personalizado.

Si el modelo también tiene un ProcessorMixin que envuelve el extractor de características, añade tests/models/<model_name>/test_processing_<model_name>.py y hereda de ProcessorTesterMixin. Establece processor_class y sobrescribe los métodos de clase _setup_<component>() para los componentes que no se pueden construir sin argumentos. Usa _setup_test_attributes() para exponer los tokens de marcador de posición utilizados por las pruebas comunes del procesador.

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", "")

Próximos pasos

• Lee la guía Generación automática de docstrings para generar docstrings consistentes automáticamente con @auto_docstring.
• Lea la guía de Feature extractors para el comportamiento de preprocesamiento orientado al usuario.