오디오 처리 컴포넌트 추가

오디오 모델은 AutoFeatureExtractor 진입점 뒤에 접근 가능한 feature extractor가 필요합니다.

모델 및 구성 단계의 경우, 먼저 모듈형 가이드를 따르세요.

Feature extractor

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

모델 디렉터리에서 feature_extraction_<model_name>.py를 생성합니다. SequenceFeatureExtractor를 상속하여 새로운 클래스가 공유 패딩, 잘라내기, 저장 및 로드 동작을 갖도록 합니다.

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()를 호출하여 체크포인트와 함께 저장하세요. 전처리 설정 파일을 수동으로 생성하거나 수정하지 마세요.

참고로 Gemma4AudioFeatureExtractor를 확인하세요.

클래스 등록

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

python utils/check_inits.py --fix_and_overwrite

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

• AutoFeatureExtractor의 FEATURE_EXTRACTOR_MAPPING_NAMES

테스트

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

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

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도 포함된 경우, tests/models/<model_name>/test_processing_<model_name>.py를 추가하고 ProcessorTesterMixin을 상속하세요. processor_class를 설정하고, 인자 없이 생성할 수 없는 컴포넌트에 대해 _setup_<component>() 클래스 메서드를 오버라이드하세요. 공통 프로세서 테스트에서 사용되는 플레이스홀더 토큰을 노출하려면 _setup_test_attributes()를 사용하세요.

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 가이드를 읽어보세요.
• 사용자 대상 전처리 동작에 대해서는 Feature extractors 가이드를 참조하세요.