# 오디오 처리 컴포넌트 추가

오디오 모델은 [AutoFeatureExtractor](/docs/transformers/main/ko/model_doc/auto#transformers.AutoFeatureExtractor) 진입점 뒤에 접근 가능한 feature extractor가 필요합니다.

> [!NOTE]
> 모델 및 구성 단계의 경우, 먼저 [모듈형](./modular_transformers) 가이드를 따르세요.

## Feature extractor

모델이 원시 오디오 또는 오디오에서 파생된 특징을 소비할 때 feature extractor를 추가합니다.

모델 디렉터리에서 `feature_extraction_<model_name>.py`를 생성합니다. [SequenceFeatureExtractor](/docs/transformers/main/ko/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`를 전달할 때 입력 샘플링 레이트를 검증해야 합니다. 입력 레이트가 모델의 예상 레이트와 다르면, 조용히 리샘플링하는 대신 오류를 발생시키세요.

변환 스크립트에서 feature extractor를 인스턴스화하고 [save_pretrained()](/docs/transformers/main/ko/main_classes/feature_extractor#transformers.FeatureExtractionMixin.save_pretrained)를 호출하여 체크포인트와 함께 저장하세요. 전처리 설정 파일을 수동으로 생성하거나 수정하지 마세요.

> [!TIP]
> 참고로 [Gemma4AudioFeatureExtractor](/docs/transformers/main/ko/model_doc/gemma4#transformers.Gemma4AudioFeatureExtractor)를 확인하세요.

## 클래스 등록

`__all__`에 새 클래스를 파일 하단에 추가한 다음, 다음 명령으로 `__init__.py`를 다시 생성합니다:

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

새 클래스를 모델 구성에 매핑하여 [AutoFeatureExtractor](/docs/transformers/main/ko/model_doc/auto#transformers.AutoFeatureExtractor)가 로드할 수 있도록 합니다. `src/transformers/models/auto/feature_extraction_auto.py`의 `FEATURE_EXTRACTOR_MAPPING_NAMES`에 항목을 추가하되, 주변 항목의 패턴을 따릅니다. 그런 다음 [AutoFeatureExtractor](/docs/transformers/main/ko/model_doc/auto#transformers.AutoFeatureExtractor)의 `FEATURE_EXTRACTOR_MAPPING_NAMES` 아래에 해당 모델 유형이 표시되는지 확인합니다.

- [AutoFeatureExtractor](/docs/transformers/main/ko/model_doc/auto#transformers.AutoFeatureExtractor)의 `FEATURE_EXTRACTOR_MAPPING_NAMES`

## 테스트

모델 테스트 디렉터리에서 각 오디오 처리 컴포넌트에 대한 테스트를 추가하세요. Feature extractor 테스트는 보통 `tests/models/<model_name>/test_feature_extraction_<model_name>.py`에 있습니다.

[SequenceFeatureExtractor](/docs/transformers/main/ko/main_classes/feature_extractor#transformers.SequenceFeatureExtractor)를 상속하는 feature extractor의 경우 `SequenceFeatureExtractionTestMixin`을 상속합니다. 이 mixin은 저장 및 로드 동작, padding, truncation, tensor 변환, 그리고 일반적인 feature extractor 속성을 커버합니다. mixin이 feature extractor를 인스턴스화하고 짧은 더미 오디오 입력을 구성할 수 있도록 `prepare_feat_extract_dict()`와 `prepare_inputs_for_common()`를 갖춘 tester 객체를 제공하세요.

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

mixin이 인지하지 못하는 모델 고유 동작에 대한 집중 테스트를 추가하세요. 오디오 feature extractor의 경우, 일반적으로 `__call__`가 반환하는 feature shape을 확인하고, 잘못된 `sampling_rate`가 오류를 발생시키는지 검증하며, 사용자 정의 정규화 또는 feature 계산을 확인하는 것을 의미합니다.

모델에 feature extractor를 감싸는 [ProcessorMixin](/docs/transformers/main/ko/main_classes/processors#transformers.ProcessorMixin)도 있는 경우, `tests/models/<model_name>/test_processing_<model_name>.py`를 추가하고 `ProcessorTesterMixin`을 상속하세요. `processor_class`를 설정하고, 인자 없이 생성할 수 없는 컴포넌트에 대해서는 `_setup_<component>()` 클래스 메서드를 오버라이드하세요. 공통 processor 테스트에서 사용하는 placeholder token을 노출하려면 `_setup_test_attributes()`를 사용하세요.

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

## 다음 단계

- `@auto_docstring`을 사용하여 일관된 docstring을 자동 생성하는 [Auto-generating docstrings](./auto_docstring) 가이드를 읽어보세요.
- 사용자 대상 전처리 동작에 대해서는 [Feature extractors](./feature_extractors) 가이드를 참조하세요.