# Добавление компонентов обработки аудио

Аудиомоделям требуется экстрактор признаков, доступный через точку входа [AutoFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoFeatureExtractor).

> [!NOTE]
> Для шагов с моделью и конфигурацией сначала следуйте [модульному](./modular_transformers) руководству.

## Извлекатель признаков

Добавьте экстрактор признаков, если модель принимает сырой аудиопоток или аудиопроизводные признаки.

Создайте `feature_extraction_<model_name>.py` в каталоге модели. Наследуйте от [SequenceFeatureExtractor](/docs/transformers/v5.23.0/ru/main_classes/feature_extractor#transformers.SequenceFeatureExtractor), чтобы новый класс получил общее поведение для выравнивания, усечения, сохранения и загрузки.

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

Держите конструктор компактным и сериализуемым. Храните все значения, необходимые для воспроизведения предобработки, в качестве атрибутов экземпляра, и избегайте хранения значений, используемых только во время выполнения, таких как открытые файлы, устройства или декодированные аудиомассивы.

Метод `__call__` должен проверять входную частоту дискретизации, если пользователь передаёт `sampling_rate`. Если входная частота отличается от ожидаемой моделью, необходимо вызывать ошибку, а не выполнять повторную дискретизацию без уведомления.

Сохраните экстрактор признаков вместе с контрольной точкой, создав его экземпляр в скрипте конвертации и вызвав [save_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/feature_extractor#transformers.FeatureExtractionMixin.save_pretrained). Не создавайте и не редактируйте файлы конфигурации предобработки вручную.

> [!TIP]
> См. [Gemma4AudioFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/gemma4#transformers.Gemma4AudioFeatureExtractor) для справки.

## Регистрация классов

Добавьте новые классы в `__all__` в конце файла, затем пересоздайте `__init__.py` с помощью:

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

Свяжите новый класс с конфигурацией модели, чтобы [AutoFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoFeatureExtractor) мог его загрузить. Добавьте запись в `FEATURE_EXTRACTOR_MAPPING_NAMES` в файле `src/transformers/models/auto/feature_extraction_auto.py`, следуя шаблону соседних записей. Затем убедитесь, что тип модели присутствует в `FEATURE_EXTRACTOR_MAPPING_NAMES` для [AutoFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoFeatureExtractor).

- `FEATURE_EXTRACTOR_MAPPING_NAMES` для [AutoFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoFeatureExtractor)

## Тестирование

Добавьте тесты для каждого компонента обработки аудио в каталоге тестов модели. Тесты для извлечения признаков обычно находятся в `tests/models/<model_name>/test_feature_extraction_<model_name>.py`.

Для экстракторов признаков, наследующихся от [SequenceFeatureExtractor](/docs/transformers/v5.23.0/ru/main_classes/feature_extractor#transformers.SequenceFeatureExtractor), наследуйтесь от `SequenceFeatureExtractionTestMixin`. Миксин покрывает поведение сохранения и загрузки, выравнивание, усечение, преобразование в тензоры и общие свойства экстрактора признаков. Предоставьте объект тестера с методами `prepare_feat_extract_dict()` и `prepare_inputs_for_common()`, чтобы миксин мог создать экземпляр экстрактора признаков и построить короткие тестовые аудиовходы.

```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)
```

Добавляйте целенаправленные тесты для модельно-специфичного поведения, о котором миксин не знает. Для аудио-фич-экстракторов это обычно означает проверку формы фич, возвращаемой `__call__`, проверку того, что неверное значение `sampling_rate` вызывает ошибку, а также проверку любой кастомной нормализации или вычисления фич.

Если у модели также есть [ProcessorMixin](/docs/transformers/v5.23.0/ru/main_classes/processors#transformers.ProcessorMixin), который оборачивает feature extractor, добавьте `tests/models/<model_name>/test_processing_<model_name>.py` и унаследуйте класс от `ProcessorTesterMixin`. Задайте `processor_class` и переопределите класс-методы `_setup_<component>()` для компонентов, которые не могут быть созданы без аргументов. Используйте `_setup_test_attributes()`, чтобы объявить placeholder-токены, используемые в общих тестах процессора.

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

## Дальнейшие шаги

- Ознакомьтесь с руководством [Автоматическая генерация docstrings](./auto_docstring), чтобы автоматически генерировать согласованные docstrings с помощью `@auto_docstring`.
- Ознакомьтесь с руководством [Feature extractors](./feature_extractors), чтобы узнать о поведении предобработки, доступном пользователю.

