Hugging Face's logo

Transformers documentation

X-Codec

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

نُشر هذا النموذج في أوراق HF في 30 أغسطس 2024، وأُضيف إلى مكتبة Hugging Face Transformers في 15 أغسطس 2025.

X-Codec

نظرة عامة

قُدِّم نموذج X-Codec في Codec Does Matter: Exploring the Semantic Shortcoming of Codec for Audio Language Model من قِبل Zhen Ye وPeiwen Sun وJiahe Lei وHongzhan Lin وXu Tan وZheqi Dai وQiuqiang Kong وJianyi Chen وJiahao Pan وQifeng Liu وYike Guo وWei Xue.

نموذج X-Codec هو مشفّر صوتي عصبي يدمج المعلومات الدلالية من النماذج ذاتية الإشراف (مثل HuBERT) إلى جانب المعلومات الصوتية التقليدية. وهذا يتيح:

  • استكمال الموسيقى: يؤدي نمذجة أفضل للدلالات الموسيقية إلى استكمالات أكثر تماسكاً.
  • توليد الصوت من النص: يلتقط X-Codec المحاذاة الدلالية بين أوامر النص والصوت المولّد.
  • تجزئة الصوت الواعية بالمعنى: يُستخدم X-Codec كمجزِّئ صوتي في نموذج توليد الأغاني من الكلمات YuE.

ينص ملخص الورقة البحثية على ما يلي:

دفع التطور الأخير في توليد الصوت بشكل كبير قدرات نماذج اللغة الكبيرة (LLMs). ركّزت الأبحاث القائمة على نماذج اللغة الصوتية بشكل أساسي على تحسين بنية نماذج اللغة الصوتية ومقياسها، فضلاً عن الاستفادة من مجموعات بيانات أكبر، وعادةً ما تُستخدم مشفّرات صوتية (acoustic codecs) مثل EnCodec لتجزئة الصوت. ومع ذلك، صُممت هذه المشفّرات في الأصل لضغط الصوت، مما قد يؤدي إلى أداء غير مثالي في سياق نماذج اللغة الصوتية. يهدف بحثنا إلى معالجة أوجه القصور في مشفّرات نماذج اللغة الصوتية الحالية، وتحديداً تحدياتها في الحفاظ على السلامة الدلالية في الصوت المولّد. فعلى سبيل المثال، غالباً ما تعاني الأساليب القائمة مثل VALL-E، التي تشترط توليد الرموز الصوتية على النصوص المنقولة نصياً، من عدم دقة المحتوى ومعدلات خطأ الكلمات (WER) المرتفعة بسبب سوء تفسير الرموز الصوتية دلالياً، مما يؤدي إلى تخطي الكلمات وأخطاء أخرى. للتغلب على هذه المشكلات، نقترح نهجاً بسيطاً وفعالاً يُدعى X-Codec. يدمج X-Codec الميزات الدلالية من مشفّر دلالي مُدرَّب مسبقاً قبل مرحلة التكميم المتجهي المتبقي (RVQ)، ويقدّم خسارة إعادة بناء دلالية بعد RVQ. من خلال تعزيز القدرة الدلالية للمشفّر، يقلّل X-Codec بشكل كبير من WER في مهام تركيب الكلام، ويمدّ هذه الفوائد إلى التطبيقات غير الكلامية، بما في ذلك توليد الموسيقى والأصوات. تُظهر تجاربنا في مهام النص إلى الكلام، واستكمال الموسيقى، والنص إلى الصوت، أن دمج المعلومات الدلالية يحسّن بشكل كبير الأداء العام لنماذج اللغة في توليد الصوت.

بطاقات النماذج:

تمت مساهمة هذا النموذج من قِبل Manal El Aidouni. يمكن العثور على الكود الأصلي هنا ونقاط التفتيش الأصلية للنماذج الخمسة المختلفة هنا.

يمكن العثور على العروض التوضيحية في هذه الصفحة.

مثال على الاستخدام

فيما يلي مثال سريع على كيفية ترميز وفك ترميز صوت باستخدام هذا النموذج:

from datasets import Audio, load_dataset

from transformers import AutoFeatureExtractor, XcodecModel


dummy_dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")

# load model and feature extractor
model_id = "hf-audio/xcodec-hubert-librispeech"
model = XcodecModel.from_pretrained(model_id, device_map="auto")
feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)

# load audio sample
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

للاستماع إلى الصوت الأصلي والصوت المُعاد بناؤه، شغّل المقطع البرمجي أدناه ثم افتح الملفين original.wav وreconstruction.wav في مشغل الموسيقى لديك للمقارنة.

import soundfile as sf


original = audio_sample
reconstruction = audio_values[0].cpu().detach().numpy()
sampling_rate = feature_extractor.sampling_rate

sf.write("original.wav", original, sampling_rate)
sf.write("reconstruction.wav", reconstruction.T, sampling_rate)

XcodecConfig

فئة transformers.XcodecConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonetarget_bandwidths: list[int | float] | tuple[int | float, ...] = (0.5, 1, 1.5, 2, 4)sample_rate: int = 16000kernel_size: int = 3channel_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 = 3codebook_size: int = 1024codebook_dim: int | None = Noneinitializer_range: float = 0.02acoustic_model_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonesemantic_model_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None )

المعاملات

  • target_bandwidths (List[float]، اختياري، القيمة الافتراضية [0.5, 1, 1.5, 2, 4]) — نطاق النطاقات الترددية المختلفة (بوحدة kbps) التي يمكن للنموذج ترميز الصوت بها.
  • sample_rate (int، اختياري، القيمة الافتراضية 16000) — معدل أخذ العينات الذي يجب أن تُرقَم به ملفات الصوت، ويُعبَّر عنه بالهرتز (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، اختياري) — أبعاد متجه تضمين كل كتاب رموز.
  • initializer_range (float، اختياري، القيمة الافتراضية 0.02) — الانحراف المعياري لـ truncated_normal_initializer المستخدم في تهيئة جميع مصفوفات الأوزان.
  • acoustic_model_config (Union[Dict, DacConfig]، اختياري) — مثال من إعدادات النموذج الصوتي (DAC).
  • semantic_model_config (Union[Dict, HubertConfig, WavLMConfig], اختياري) — مثال من كائن التهيئة الخاص بالنموذج الدلالي (HuBERT).

هذه فئة الإعدادات المخزنة لإعدادات نموذج XcodecModel. تُستخدم لاستحداث نموذج Xcodec وفقاً للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيُنتج إعدادات مشابهة لتلك الخاصة بـ Manel/X-Codec

ترث كائنات التهيئة من PreTrainedConfig ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ PreTrainedConfig لمزيد من المعلومات.

مثال:

>>> from transformers import XcodecModel, XcodecConfig

>>> # Initializing configuration
>>> configuration = XcodecConfig()

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

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

XcodecModel

فئة transformers.XcodecModel

< >

( config: XcodecConfig )

المعاملات

  • config (XcodecConfig) — فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. لا يؤدي التهيئة باستخدام ملف الإعداد إلى تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة from_pretrained() لتحميل أوزان النموذج.

نموذج Xcodec، وهو ترميز صوتي عصبي.

يرث هذا النموذج من PreTrainedModel. راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التحميل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).

هذا النموذج هو أيضًا فئة فرعية من torch.nn.Module في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.

decode

< >

( audio_codes: Tensorreturn_dict: bool | None = None )

المعاملات

  • audio_codes (torch.LongTensor من الشكل (batch_size, num_quantizers, codes_length)) — فهارس رموز منفصلة محسوبة باستخدام model.encode.
  • return_dict (bool، اختياري) — ما إذا كان سيتم إرجاع ModelOutput

encode

< >

( input_values: Tensorbandwidth: float | None = Nonereturn_dict: bool | None = None )

المعاملات

  • input_values (torch.Tensor من الشكل (batch_size, channels, num_samples)) — قيم عشرية لموجة الصوت المدخلة.
  • bandwidth (float, اختياري) — النطاق الترددي المستهدف بوحدة (kbps) يدعم فقط القيم الموجودة في config.target_bandwidths. القيمة الافتراضية هي أعلى نطاق ترددي متاح 4.0 kbps.
  • return_dict (bool, اختياري) — ما إذا كان يجب إرجاع ModelOutput أم لا.

forward

< >

( input_values: Tensoraudio_codes: typing.Optional[torch.Tensor] = Nonebandwidth: float | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → XcodecOutput or tuple (audio_codes, audio_values)

المعاملات

  • 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. القيمة الافتراضية هي أعلى نطاق ترددي متاح.

يعيد

XcodecOutput أو مجموعة مرتبة (audio_codes, audio_values)

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

تتجاوز طريقة XcodecModel الخاصة بالتقديم (forward) الطريقة الخاصة __call__.

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

مثال:

>>> from datasets import load_dataset
>>> from transformers import AutoFeatureExtractor, XcodecModel

>>> model_id = "hf-audio/xcodec-hubert-librispeech"
>>> model = XcodecModel.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
Update on GitHub

←Whisper X-Codec2→