오디오 처리 컴포넌트 추가하기

오디오 처리 컴포넌트 추가하기 (Add audio processing components)

오디오 모델에는 feature extractor가 필요하고, 이는 AutoFeatureExtractor라는 진입점(entry point) 뒤에서 접근할 수 있어요. 이 페이지에서는 새로운 오디오 모델에 feature extractor를 추가하고, 등록하고, 테스트하는 전체 과정을 살펴볼 거예요.

출처: 문서

본문

[!NOTE] 모델과 설정(config) 단계는 먼저 modular 가이드를 따라 진행해 주세요.

Feature extractor

모델이 원시 오디오(raw audio)나 오디오에서 파생된 feature를 사용할 때는 feature extractor를 추가해요.

모델 디렉터리에 feature_extraction_<model_name>.py를 만들고, SequenceFeatureExtractor를 상속받아요. 그래야 padding, truncation, 저장(saving), 로딩(loading) 동작을 새 클래스가 공유할 수 있어요.

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

생성자(constructor)는 작고 직렬화 가능하게 유지해요. 전처리를 재현하는 데 필요한 모든 값을 인스턴스 속성으로 저장하고, 열린 파일(open files)이나 디바이스, 디코딩된 오디오 배열 같은 실행 시점(runtime)에만 필요한 값은 저장하지 않는 게 좋아요.

__call__ 메서드는 사용자가 sampling_rate를 전달했을 때 입력 sampling rate를 반드시 검증해야 해요. 입력 rate가 모델이 기대하는 rate와 다르면 조용히 resampling 하지 말고 오류를 발생시켜야 해요.

feature extractor를 변환(conversion) 스크립트에서 인스턴스화하고 save_pretrained()를 호출해서 checkpoint와 함께 저장해요. 전처리 설정 파일을 직접 만들거나 편집하지 마세요.

[!TIP] 참고로 Gemma4AudioFeatureExtractor를 확인해 보세요.

클래스 등록하기 (Register the classes)

모델 패키지의 __init__.py에서 새 클래스를 노출해요. 주변 모델들이 사용하는 lazy import 패턴을 따르고, 클래스가 요구하는 선택적 의존성과 동일한 의존성으로 import를 가드(guard)해 주세요.

새 클래스를 모델 config에 매핑해서 AutoFeatureExtractor가 로드할 수 있게 해요. src/transformers/models/auto/feature_extraction_auto.py의 FEATURE_EXTRACTOR_MAPPING_NAMES에 주변 항목 패턴대로 항목을 추가해요. 그 다음 모델 타입이 AutoFeatureExtractor용 FEATURE_EXTRACTOR_MAPPING_NAMES 아래에 나타나는지 확인해 주세요.

테스트 (Testing)

모델 테스트 디렉터리에 각 오디오 처리 컴포넌트에 대한 테스트를 추가해요. feature extractor 테스트는 보통 tests/models/<model_name>/test_feature_extraction_<model_name>.py에 둬요.

SequenceFeatureExtractor를 상속받는 feature extractor는 SequenceFeatureExtractionTestMixin을 상속받아요. 이 mixin은 저장/로드 동작, padding, truncation, tensor 변환, 그리고 일반적인 feature extractor 속성을 다뤄요. prepare_feat_extract_dict()와 prepare_inputs_for_common()을 제공하는 tester 객체를 만들어서 mixin이 feature extractor를 인스턴스화하고 짧은 더미(dummy) 오디오 입력을 만들 수 있게 해요.

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이 모르는 모델 특정 동작에 대한 집중(focused) 테스트도 추가해요. 오디오 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()를 사용해서 공통 processor 테스트가 쓰는 placeholder 토큰을 노출해요.

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

다음 단계 (Next steps)

더 알아보기 (Learn more)