# إضافة مكونات معالجة الصوت

تتطلب نماذج الصوت مستخرج ميزات يمكن الوصول إليه من خلال نقطة الدخول [AutoFeatureExtractor](/docs/transformers/main/ar/model_doc/auto#transformers.AutoFeatureExtractor).

> [!NOTE]
> بالنسبة إلى خطوات النموذج والتكوين، اتبع أولاً الدليل [المنفصل](./modular_transformers).

## مستخرج الميزات

أضِف مستخرج ميزات عندما يستهلك النموذج صوتًا خامًا أو ميزات مشتقة من الصوت.

أنشئ `feature_extraction_<model_name>.py` في مجلد النموذج. ورث من [SequenceFeatureExtractor](/docs/transformers/main/ar/main_classes/feature_extractor#transformers.SequenceFeatureExtractor) حتى تحصل الفئة الجديدة على سلوك مشترك للتوسيد (padding) والقطع (truncation) والحفظ والتحميل.

```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`. إذا اختلف المعدل المُدخل عن المعدل المتوقع للنموذج، فقم برفع خطأ بدلاً من إعادة أخذ العينات بصمت.

احفظ مستخرج الميزات مع نقطة الحفظ عن طريق إنشاء مثيل له في سكربت التحويل واستدعاء [save_pretrained()](/docs/transformers/main/ar/main_classes/feature_extractor#transformers.FeatureExtractionMixin.save_pretrained). لا تنشئ أو تحرر ملفات إعدادات ما قبل المعالجة يدويًا.

> [!TIP]
> راجع [Gemma4AudioFeatureExtractor](/docs/transformers/main/ar/model_doc/gemma4#transformers.Gemma4AudioFeatureExtractor) للاطلاع على التفاصيل.

## تسجيل الفئات

أضف الفئات الجديدة إلى `__all__` في أسفل الملف، ثم أعد توليد `__init__.py` باستخدام:

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

خريطة الفئة الجديدة إلى إعدادات النموذج بحيث يمكن لـ [AutoFeatureExtractor](/docs/transformers/main/ar/model_doc/auto#transformers.AutoFeatureExtractor) تحميلها. أضف إدخالاً إلى `FEATURE_EXTRACTOR_MAPPING_NAMES` في `src/transformers/models/auto/feature_extraction_auto.py`، متبعاً نمط الإدخالات المجاورة. ثم تحقق من ظهور نوع النموذج هناك تحت `FEATURE_EXTRACTOR_MAPPING_NAMES` لـ [AutoFeatureExtractor](/docs/transformers/main/ar/model_doc/auto#transformers.AutoFeatureExtractor).

- `FEATURE_EXTRACTOR_MAPPING_NAMES` لـ [AutoFeatureExtractor](/docs/transformers/main/ar/model_doc/auto#transformers.AutoFeatureExtractor)

## الاختبار

أضِف اختبارات لكل مكوّن معالجة الصوت في مجلد اختبارات النموذج. عادةً ما تُوضع اختبارات مستخرج الميزات في `tests/models/<model_name>/test_feature_extraction_<model_name>.py`.

بالنسبة لاستخراجات الميزات التي ترث من [SequenceFeatureExtractor](/docs/transformers/main/ar/main_classes/feature_extractor#transformers.SequenceFeatureExtractor)، ارث من `SequenceFeatureExtractionTestMixin`. يغطي الميكسِن سلوك الحفظ والتحميل، والتعبئة (padding)، والقطع (truncation)، وتحويل المصفوفات (tensors)، وخصائص مستخرجات الميزات الشائعة. قدّم كائن مُختبِر (tester) يحتوي على `prepare_feat_extract_dict()` و`prepare_inputs_for_common()` حتى يتمكن الميكسِن من إنشاء مستخرج الميزات وبناء مدخلات صوتية قصيرة وهمية.

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

أضِف اختبارات مركّزة للسلوك الخاص بالنموذج الذي لا يعرفه الميكسِن. بالنسبة لاستخراجات السمات الصوتية، يعني ذلك عادةً التحقق من شكل السمات الذي يعيده `__call__`، والتحقق من أن `sampling_rate` غير الصحيح يثير خطأً، والتحقق من أي تطبيع مخصص أو حساب سمات.

إذا كان النموذج يحتوي أيضًا على [ProcessorMixin](/docs/transformers/main/ar/main_classes/processors#transformers.ProcessorMixin) يغلّف مستخرج الميزات، أضف `tests/models/<model_name>/test_processing_<model_name>.py` وارث من `ProcessorTesterMixin`. اضبط `processor_class` وأعد تعريف أساليب الفئة `_setup_<component>()` للمكونات التي لا يمكن إنشاؤها دون حُجج. استخدم `_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) لتوليد توثيق متسق تلقائيًا باستخدام `@auto_docstring`.
- اقرأ دليل [مستخرجات الميزات](./feature_extractors) لمعرفة سلوك ما قبل المعالجة الموجه للمستخدمين.