# مُرمِّز Higgs Audio V2

## نظرة عامة

- معدل إطارات منخفض: عند 25 إطاراً في الثانية، يُقلّل مُرمّزنا (tokenizer) معدل الإطارات إلى النصف مقارنةً بالعديد من الخطوط الأساس (baselines) مع الحفاظ على جودة صوتية عالية.
- تدريب موحّد بمعدل 24 كيلوهرتز: نخلط مقاطع الكلام والموسيقى وأحداث الصوت في نموذج واحد، لالتقاط التفاصيل الدلالية والصوتية معاً، مما يسهّل بشكل كبير تدريب نماذج اللغة الصوتية.
- استدلال سريع: من خلال تجنّب خطوات الانتشار، يعالج مُشفِّرنا/مُفكّكنا الدفعات بسرعة، مما يجعله عملياً للمهام الفورية أو واسعة النطاق.

**بنية النموذج:**

    

## الاستخدام

```python
from datasets import Audio, load_dataset

from transformers import AutoFeatureExtractor, HiggsAudioV2TokenizerModel

# load model and feature extractor
model_id = "eustlb/higgs-audio-v2-tokenizer"
feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)
model = HiggsAudioV2TokenizerModel.from_pretrained(model_id, device_map="auto")

# load audio sample
dummy_dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
dummy_dataset = dummy_dataset.cast_column("audio", Audio(sampling_rate=feature_extractor.sampling_rate))
audio_sample = dummy_dataset[-1]["audio"]["array"]
inputs = feature_extractor(raw_audio=audio_sample, sampling_rate=feature_extractor.sampling_rate, return_tensors="pt").to(model.device)

# encode and decode
encoder_outputs = model.encode(inputs["input_values"])
decoder_outputs = model.decode(encoder_outputs.audio_codes)
audio_values = decoder_outputs.audio_values

# or the equivalent with a forward pass
audio_values = model(inputs["input_values"]).audio_values
```

## HiggsAudioV2TokenizerConfig[[transformers.HiggsAudioV2TokenizerConfig]]

#### transformers.HiggsAudioV2TokenizerConfig[[transformers.HiggsAudioV2TokenizerConfig]]

```python
transformers.HiggsAudioV2TokenizerConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, target_bandwidths: list[int | float] | tuple[int | float, ...] = (0.5, 1, 1.5, 2, 4), sample_rate: int = 24000, kernel_size: int = 3, channel_ratios: list[int] | tuple[int, ...] = (1, 1), strides: list[int] | tuple[int, ...] = (1, 1), block_dilations: list[int] | tuple[int, ...] = (1, 1), unit_kernel_size: int = 3, codebook_size: int = 1024, codebook_dim: int = 64, initializer_range: float = 0.02, acoustic_model_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, semantic_model_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, semantic_sample_rate: int = 16000, downsample_factor: int = 320)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/higgs_audio_v2_tokenizer/configuration_higgs_audio_v2_tokenizer.py#L34)

**المعاملات:**

target_bandwidths (`List[float]`، *اختياري*، القيمة الافتراضية `[0.5, 1, 1.5, 2]`) : نطاق نطاقات التردد المختلفة (بوحدة كيلوبت/ثانية) التي يمكن للنموذج ترميز الصوت بها.

sample_rate (`int`، *اختياري*، القيمة الافتراضية `24000`) : معدل أخذ العينات الذي يجب أن تُرقَم به ملفات الصوت، ويُعبَّر عنه بالهرتز (Hz).

kernel_size (`int`، *اختياري*، القيمة الافتراضية 3) : حجم النواة للتمرير الأولي الدلالي.

channel_ratios (`List[float]`، *اختياري*، القيمة الافتراضية `[1, 1]`) : عوامل التوسيع لعدد قنوات الإخراج في كل كتلة دلالية.

strides (`List[int]`، *اختياري*، القيمة الافتراضية `[1, 1]`) : خطوات لكل كتلة من مشفّرات الدلالات.

block_dilations (`List[int]`، *اختياري*، القيمة الافتراضية `[1, 1]`) : عوامل التمدد للوحدات المتبقية في الكتل الدلالية.

unit_kernel_size (`int`، *اختياري*، القيمة الافتراضية 3) : حجم النواة داخل كل ResidualUnit في الكتل الدلالية.

codebook_size (`int`، *اختياري*، القيمة الافتراضية `1024`) : عدد كتيّبات الأكواد المتوازية التي يستخدمها النموذج.

codebook_dim (`int`، *اختياري*، القيمة الافتراضية `64`) : بُعد متجه التضمين لكل كتاب رموز.

initializer_range (`float`، *اختياري*، القيمة الافتراضية `0.02`) : الانحراف المعياري لـ truncated_normal_initializer المستخدم في تهيئة جميع مصفوفات الأوزان.

acoustic_model_config (`Union[Dict, AutoConfig]`، *اختياري*) : نسخة من إعدادات نموذج الصوت (DAC).

semantic_model_config (`Union[Dict, AutoConfig]`، *اختياري*) : نسخة من كائن التهيئة لنموذج الدلالات (HuBERT).

semantic_sample_rate (`int`، *اختياري*، القيمة الافتراضية 16000) : معدل أخذ العينات الذي يتوقع به النموذج الدلالي إدخال الصوت، بالهرتز (Hz).

downsample_factor (`int`, *اختياري*, القيمة الافتراضية 320) : عامل تقليل العينة للميزات الدلالية.

هذه فئة الإعدادات المخزنة لإعدادات نموذج HiggsAudioV2TokenizerModel. تُستخدم لاستحداث نموذج Higgs Audio V2 Tokenizer وفقًا للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى إعدادات مشابهة لتلك الخاصة بـ [bosonai/higgs-audio-v2-tokenizer](https://huggingface.co/bosonai/higgs-audio-v2-tokenizer)

ترث كائنات الإعداد من [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) لمزيد من المعلومات.

مثال:

```python
>>> from transformers import HiggsAudioV2TokenizerModel, HiggsAudioV2TokenizerConfig

>>> # Initializing configuration
>>> configuration = HiggsAudioV2TokenizerConfig()

>>> # Initializing a model (with random weights) from the configuration
>>> model = HiggsAudioV2TokenizerModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## HiggsAudioV2TokenizerModel[[transformers.HiggsAudioV2TokenizerModel]]

#### transformers.HiggsAudioV2TokenizerModel[[transformers.HiggsAudioV2TokenizerModel]]

```python
transformers.HiggsAudioV2TokenizerModel(config: HiggsAudioV2TokenizerConfig)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/higgs_audio_v2_tokenizer/modeling_higgs_audio_v2_tokenizer.py#L456)

**المعاملات:**

config ([HiggsAudioV2TokenizerConfig](/docs/transformers/main/ar/model_doc/higgs_audio_v2_tokenizer#transformers.HiggsAudioV2TokenizerConfig)) : فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. عند التهيئة باستخدام ملف إعدادات، لا يتم تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة [from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) لتحميل أوزان النموذج.

نموذج HiggsAudioV2Tokenizer لتشفير الصوت العصبي.

يرث هذا النموذج من [PreTrainedModel](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel). راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التنزيل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).

هذا النموذج هو أيضاً فئة فرعية من [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.

#### فك الترميز[[transformers.HiggsAudioV2TokenizerModel.decode]]

```python
decode(audio_codes: Tensor, return_dict: bool | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/higgs_audio_v2_tokenizer/modeling_higgs_audio_v2_tokenizer.py#L564)

**المعاملات:**

audio_codes (`torch.LongTensor` من الشكل `(batch_size, num_quantizers, codes_length)`) : فهارس رموز منفصلة محسوبة باستخدام `model.encode`.

return_dict (`bool`، *اختياري*) : ما إذا كان يجب إرجاع [ModelOutput](/docs/transformers/main/ar/main_classes/output#transformers.utils.ModelOutput)

**يعيد:**

قيم الصوت المُفكّكة ذات الشكل `(batch_size, channels, num_samples)` التي تم الحصول عليها باستخدام جزء المُفكّك من HiggsAudioV2Tokenizer.

#### encode[[transformers.HiggsAudioV2TokenizerModel.encode]]

```python
encode(input_values: Tensor, bandwidth: float | None = None, return_dict: bool | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/higgs_audio_v2_tokenizer/modeling_higgs_audio_v2_tokenizer.py#L512)

**المعاملات:**

input_values (`torch.Tensor` من الشكل `(batch_size, channels, num_samples)`) : قيم رقمية عشرية لموجة الصوت المدخلة.

bandwidth (`float`، *اختياري*) : عرض النطاق الترددي المستهدف بوحدة (kbps) يدعم فقط القيم الموجودة في `config.target_bandwidths`. القيمة الافتراضية هي أعلى عرض نطاق ترددي متاح `4.0` kbps.

return_dict (`bool`، *اختياري*) : ما إذا كان يجب إرجاع [ModelOutput](/docs/transformers/main/ar/main_classes/output#transformers.utils.ModelOutput) أم لا.

**يعيد:**

`torch.LongTensor` من الشكل `(batch_size, num_quantizers, codes_length)` يحتوي على رموز الصوت المشفرة المنفصلة.

#### forward[[transformers.HiggsAudioV2TokenizerModel.forward]]

```python
forward(input_values: Tensor, audio_codes: typing.Optional[torch.Tensor] = None, bandwidth: float | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/higgs_audio_v2_tokenizer/modeling_higgs_audio_v2_tokenizer.py#L592)

**المعاملات:**

input_values (`torch.Tensor` من الشكل `(batch_size, channels, num_samples)`) : القيم العائمة الخام لموجة الصوت المدخلة.

audio_codes (`torch.LongTensor` من الشكل `(batch_size, num_quantizers, codes_length)` : فهارس رموز منفصلة محسوبة باستخدام `model.encode`.

bandwidth (`float`، *اختياري*) : عرض النطاق الترددي المستهدف بالكيلوبت في الثانية. يجب أن يكون أحد قيم `config.target_bandwidths`. القيمة الافتراضية هي أعلى عرض نطاق ترددي متاح.

bandwidth (`float`، *اختياري*) : عرض النطاق الترددي المستهدف بالكيلوبت في الثانية. يجب أن يكون أحد قيم `config.target_bandwidths`. القيمة الافتراضية هي أعلى عرض نطاق ترددي متاح.

**يعيد:** `HiggsAudioV2TokenizerOutput` أو tuple `(audio_codes, audio_values)`

- `audio_codes` من الشكل `(batch_size, num_quantizers, codes_length)`: الرموز المنفصلة المُكمّاة.
- `audio_values` من الشكل `(batch_size, channels, num_samples)`: موجة الصوت المُعاد بناؤها بناءً على الرموز.

تُعيد طريقة [HiggsAudioV2TokenizerModel](/docs/transformers/main/ar/model_doc/higgs_audio_v2_tokenizer#transformers.HiggsAudioV2TokenizerModel) الخاصة بالتقديم (forward) تعريف الطريقة الخاصة `__call__`.

على الرغم من أنه يجب تعريف وصفة المرور الأمامي داخل هذه الدالة، إلا أنه ينبغي استدعاء كائن `Module` بدلاً من هذه الدالة، لأن الكائن يتولى تنفيذ خطوات المعالجة المسبقة والمعالجة اللاحقة، بينما تتجاهل الدالة هذه الخطوات بصمت.

مثال:

```python
>>> from datasets import load_dataset
>>> from transformers import AutoFeatureExtractor, HiggsAudioV2TokenizerModel

>>> model_id = "hf-audio/higgs_audio_v2_tokenizer-hubert-librispeech"
>>> model = HiggsAudioV2TokenizerModel.from_pretrained(model_id)
>>> feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)

>>> dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> dataset = dataset.cast_column("audio", Audio(sampling_rate=feature_extractor.sampling_rate))
>>> audio_sample = dataset[0]['audio']['array']

>>> inputs = feature_extractor(raw_audio=audio_sample, return_tensors="pt")

>>> outputs = model(**inputs)
>>> audio_codes = outputs.audio_codes
>>> audio_values = outputs.audio_values
```