# Adicionar componentes de processamento de áudio

Os modelos de áudio exigem um extrator de recursos acessível por meio do ponto de entrada [AutoFeatureExtractor](/docs/transformers/main/pt/model_doc/auto#transformers.AutoFeatureExtractor).

> [!NOTE]
> Para as etapas de modelo e configuração, siga primeiro o guia [modular](./modular_transformers).

## 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](/docs/transformers/main/pt/main_classes/feature_extractor#transformers.SequenceFeatureExtractor) para que a nova classe obtenha o comportamento compartilhado de padding, truncamento, salvamento e carregamento.

```py
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()](/docs/transformers/main/pt/main_classes/feature_extractor#transformers.FeatureExtractionMixin.save_pretrained). Não crie nem edite manualmente os arquivos de configuração de pré-processamento.

> [!TIP]
> Consulte [Gemma4AudioFeatureExtractor](/docs/transformers/main/pt/model_doc/gemma4#transformers.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:

```bash
python utils/check_inits.py --fix_and_overwrite
```

Mapeie a nova classe para a configuração do modelo para que [AutoFeatureExtractor](/docs/transformers/main/pt/model_doc/auto#transformers.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](/docs/transformers/main/pt/model_doc/auto#transformers.AutoFeatureExtractor).

- `FEATURE_EXTRACTOR_MAPPING_NAMES` para [AutoFeatureExtractor](/docs/transformers/main/pt/model_doc/auto#transformers.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](/docs/transformers/main/pt/main_classes/feature_extractor#transformers.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.

```py
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](/docs/transformers/main/pt/main_classes/processors#transformers.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.

```py
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](./auto_docstring) para gerar automaticamente docstrings consistentes com `@auto_docstring`.
- Leia o guia de [Extratores de recursos](./feature_extractors) para o comportamento de pré-processamento voltado ao usuário.