# 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](/docs/transformers/v5.23.0/vi/model_doc/auto#transformers.AutoFeatureExtractor).

> [!NOTE]
> Đố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](./modular_transformers) 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](/docs/transformers/v5.23.0/vi/main_classes/feature_extractor#transformers.SequenceFeatureExtractor) để lớp mới có được hành vi đệm (padding), cắt (truncation), lưu và tải chung.

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

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 xác thực 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()](/docs/transformers/v5.23.0/vi/main_classes/feature_extractor#transformers.FeatureExtractionMixin.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ý.

> [!TIP]
> Xem [Gemma4AudioFeatureExtractor](/docs/transformers/v5.23.0/vi/model_doc/gemma4#transformers.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:

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

Ánh xạ lớp mới đến cấu hình mô hình để [AutoFeatureExtractor](/docs/transformers/v5.23.0/vi/model_doc/auto#transformers.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](/docs/transformers/v5.23.0/vi/model_doc/auto#transformers.AutoFeatureExtractor).

- `FEATURE_EXTRACTOR_MAPPING_NAMES` cho [AutoFeatureExtractor](/docs/transformers/v5.23.0/vi/model_doc/auto#transformers.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](/docs/transformers/v5.23.0/vi/main_classes/feature_extractor#transformers.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.

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

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](/docs/transformers/v5.23.0/vi/main_classes/processors#transformers.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.

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

## Các bước tiếp theo

- Đọc hướng dẫn [Tự động tạo docstring](./auto_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](./feature_extractors) để biết về hành vi tiền xử lý dành cho người dùng.

