Adicionar componentes de processamento de áudio

Os modelos de áudio exigem um extrator de recursos acessível por meio do ponto de entrada AutoFeatureExtractor.

Para as etapas de modelo e configuração, siga primeiro o guia modular.

Extrator de recursos

Adicione um extrator de recursos quando o modelo consumir áudio bruto ou recursos derivados de áudio.

Crie feature_extraction_<model_name>.py no diretório do modelo. Herde de SequenceFeatureExtractor para que a nova classe obtenha o comportamento compartilhado de padding, truncamento, salvamento e carregamento.

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

Mantenha o construtor pequeno e serializável. Armazene todos os valores necessários para reproduzir o pré-processamento como atributos de instância e evite armazenar valores apenas de tempo de execução, como arquivos abertos, dispositivos ou arrays de áudio decodificados.

O método __call__ deve validar a taxa de amostragem de entrada quando os usuários passam sampling_rate. Se a taxa de entrada diferir da taxa esperada pelo modelo, lance um erro em vez de reamostrar silenciosamente.

Salve o extrator de recursos junto com o checkpoint, instanciando-o no script de conversão e chamando save_pretrained(). Não crie nem edite manualmente os arquivos de configuração de pré-processamento.

Consulte Gemma4AudioFeatureExtractor para referência.

Registre as classes

Adicione as novas classes a __all__ no final do arquivo e, em seguida, regenere o __init__.py com:

python utils/check_inits.py --fix_and_overwrite

Mapeie a nova classe para a configuração do modelo para que AutoFeatureExtractor possa carregá-la. Adicione uma entrada em FEATURE_EXTRACTOR_MAPPING_NAMES em src/transformers/models/auto/feature_extraction_auto.py, seguindo o padrão das entradas próximas. Em seguida, verifique se o tipo de modelo aparece lá em FEATURE_EXTRACTOR_MAPPING_NAMES para AutoFeatureExtractor.

• FEATURE_EXTRACTOR_MAPPING_NAMES para AutoFeatureExtractor

Testes

Adicione testes para cada componente de processamento de áudio no diretório de testes do modelo. Os testes do extrator de características geralmente ficam em tests/models/<model_name>/test_feature_extraction_<model_name>.py.

Para extratores de recursos que herdam de SequenceFeatureExtractor, herde de SequenceFeatureExtractionTestMixin. O mixin cobre o comportamento de salvar e carregar, padding, truncamento, conversão para tensor e propriedades comuns de extratores de recursos. Forneça um objeto tester com prepare_feat_extract_dict() e prepare_inputs_for_common() para que o mixin possa instanciar o extrator de recursos e construir entradas de áudio falsas e curtas.

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)

Adicione testes focados no comportamento específico do modelo que o mixin não conhece. Para extratores de recursos de áudio, isso geralmente significa verificar a forma dos recursos retornada por __call__, validar que uma sampling_rate incorreta gera um erro e verificar qualquer normalização ou cálculo de recurso personalizado.

Se o modelo também tiver um ProcessorMixin que encapsula o extrator de recursos, adicione tests/models/<model_name>/test_processing_<model_name>.py e herde de ProcessorTesterMixin. Defina processor_class e sobrescreva os métodos de classe _setup_<component>() para componentes que não podem ser construídos sem argumentos. Use _setup_test_attributes() para expor os tokens de substituição usados pelos testes comuns de processador.

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óximas etapas

• Leia o guia Geração automática de docstrings para gerar automaticamente docstrings consistentes com @auto_docstring.
• Leia o guia de Extratores de recursos para o comportamento de pré-processamento voltado ao usuário.