Thêm các thành phần xử lý âm thanh

Các mô hình âm thanh yêu cầu một bộ trích xuất đặc trưng có thể truy cập thông qua điểm vào AutoFeatureExtractor.

Đối với các bước về mô hình và cấu hình, hãy làm theo hướng dẫn modular trước.

Bộ trích xuất đặc trưng

Thêm bộ trích xuất đặc trưng khi mô hình sử dụng âm thanh thô hoặc các đặc trưng được suy ra từ âm thanh.

Tạo feature_extraction_<model_name>.py trong thư mục mô hình. Kế thừa từ SequenceFeatureExtractor để lớp mới có được hành vi đệm (padding), cắt (truncation), lưu và tải chung.

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

Giữ constructor nhỏ gọn và có thể serialize được. Lưu trữ mọi giá trị cần thiết để tái tạo tiền xử lý dưới dạng thuộc tính của instance, và tránh lưu trữ các giá trị chỉ dùng trong thời gian chạy như tệp đang mở, thiết bị, hoặc mảng âm thanh đã giải mã.

Phương thức __call__ phải kiểm tra tần số lấy mẫu đầu vào khi người dùng truyền sampling_rate. Nếu tần số đầu vào khác với tần số mong đợi của mô hình, hãy ném ra một lỗi thay vì tự động lấy mẫu lại một cách im lặng.

Lưu feature extractor cùng với checkpoint bằng cách khởi tạo nó trong script chuyển đổi và gọi save_pretrained(). Không tự động tạo hoặc chỉnh sửa các tệp cấu hình tiền xử lý.

Xem Gemma4AudioFeatureExtractor để tham khảo.

Đăng ký các lớp

Thêm các lớp mới vào __all__ ở cuối tệp, sau đó tạo lại __init__.py bằng:

python utils/check_inits.py --fix_and_overwrite

Ánh xạ lớp mới đến cấu hình mô hình để AutoFeatureExtractor có thể tải nó. Thêm một mục vào FEATURE_EXTRACTOR_MAPPING_NAMES trong src/transformers/models/auto/feature_extraction_auto.py, làm theo mẫu của các mục lân cận. Sau đó, xác minh rằng loại mô hình xuất hiện ở đó dưới FEATURE_EXTRACTOR_MAPPING_NAMES cho AutoFeatureExtractor.

• FEATURE_EXTRACTOR_MAPPING_NAMES cho AutoFeatureExtractor

Kiểm thử

Thêm các bài kiểm tra cho từng thành phần xử lý âm thanh trong thư mục kiểm tra mô hình. Các bài kiểm tra bộ trích xuất đặc trưng thường nằm trong tests/models/<model_name>/test_feature_extraction_<model_name>.py.

Đối với các feature extractor kế thừa từ SequenceFeatureExtractor, hãy kế thừa từ SequenceFeatureExtractionTestMixin. Mixin này bao phủ hành vi lưu và tải, padding, truncation, chuyển đổi tensor, và các thuộc tính phổ biến của feature extractor. Cung cấp một đối tượng tester có prepare_feat_extract_dict() và prepare_inputs_for_common() để mixin có thể khởi tạo feature extractor và xây dựng các đầu vào âm thanh giả ngắn.

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)

Thêm các bài kiểm tra tập trung cho hành vi cụ thể của mô hình mà mixin không nắm được. Đối với bộ trích xuất đặc trưng âm thanh, điều đó thường có nghĩa là kiểm tra hình dạng đặc trưng được trả về bởi __call__, xác minh rằng một sampling_rate không chính xác sẽ gây ra lỗi, và kiểm tra bất kỳ phép chuẩn hóa hoặc tính toán đặc trưng tùy chỉnh nào.

Nếu model cũng có ProcessorMixin bao bọc feature extractor, hãy thêm tests/models/<model_name>/test_processing_<model_name>.py và kế thừa từ ProcessorTesterMixin. Đặt processor_class và ghi đè các phương thức lớp _setup_<component>() cho các thành phần không thể được khởi tạo mà không có đối số. Sử dụng _setup_test_attributes() để phơi bày các token placeholder được dùng trong các bài kiểm tra processor chung.

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

Các bước tiếp theo

• Đọc hướng dẫn Tự động tạo docstring để tự động tạo các docstring nhất quán với @auto_docstring.
• Đọc hướng dẫn Trích xuất đặc trưng để biết về hành vi tiền xử lý dành cho người dùng.