# LongCat-AudioDiT

LongCat-AudioDiT هو نموذج انتشار لتوليد الصوت من النص من Meituan LongCat. يكشف تكامل diffusers واجهة [DiffusionPipeline](/docs/diffusers/main/ar/api/pipelines/overview#diffusers.DiffusionPipeline) قياسية لتوليد الصوت المشروط بالنص.

تم تكييف خط أنابيب هذا من التنفيذ المرجعي لـ LongCat-AudioDiT: https://github.com/meituan-longcat/LongCat-AudioDiT

يدعم هذا الخط أنماط التحميل من مجلد محلي أو مستودع في Hugging Face Hub بتنسيق diffusers (الذي يحتوي على مجلدات فرعية `text_encoder/`، `transformer/`، `vae/`، `tokenizer/`، و`scheduler/`).

## الاستخدام

```py
import soundfile as sf
import torch
from diffusers import LongCatAudioDiTPipeline

pipeline = LongCatAudioDiTPipeline.from_pretrained(
    "ruixiangma/LongCat-AudioDiT-1B-Diffusers",
    dtype=torch.float16,
)
pipeline = pipeline.to("cuda")  # or "mps", "xpu", "cpu"

prompt = "A calm ocean wave ambience with soft wind in the background."
audio = pipeline(
    prompt,
    audio_duration_s=5.0,
    num_inference_steps=16,
    guidance_scale=4.0,
    generator=torch.Generator("cuda").manual_seed(42),
).audios[0, 0]

sf.write("longcat.wav", audio, pipeline.sample_rate)
```

## نصائح

- `audio_duration_s` هو الطريقة الأكثر مباشرةً للتحكم في مدة المخرجات.
- استخدم `generator=torch.Generator("cuda").manual_seed(42)` لجعل عملية التوليد قابلة للتكرار.
- شكل المخرجات هو `(batch, channels, samples)` - استخدم `.audios[0, 0]` للحصول على عينة صوت واحدة.
- تُخرج خط الأنابيب صوتًا أحادي القناة (قناة واحدة). إذا كنت بحاجة إلى صوت ستيريو، يمكنك تكرار القناة: `audio.unsqueeze(0).repeat(1, 2, 1)`.

## LongCatAudioDiTPipeline[[diffusers.LongCatAudioDiTPipeline]]

#### diffusers.LongCatAudioDiTPipeline[[diffusers.LongCatAudioDiTPipeline]]

```python
diffusers.LongCatAudioDiTPipeline(vae: LongCatAudioDiTVae, text_encoder: UMT5EncoderModel, tokenizer: PreTrainedTokenizerBase, transformer: LongCatAudioDiTTransformer, scheduler: diffusers.schedulers.scheduling_flow_match_euler_discrete.FlowMatchEulerDiscreteScheduler | None = None)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/longcat_audio_dit/pipeline_longcat_audio_dit.py#L99)

#### __call__[[diffusers.LongCatAudioDiTPipeline.__call__]]

```python
__call__(prompt: str | list[str], negative_prompt: str | list[str] | None = None, audio_duration_s: float | None = None, latents: typing.Optional[torch.Tensor] = None, num_inference_steps: int = 16, guidance_scale: float = 4.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, output_type: str = 'np', return_dict: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'])
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/longcat_audio_dit/pipeline_longcat_audio_dit.py#L219)

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

prompt (`str` أو `list[str]`) : موجه أو موجهات توجه توليد الصوت.

negative_prompt (`str` أو `list[str]`، *اختياري*) : موجه(ات) سلبية(ة) للإرشاد الحر من التصنيف.

audio_duration_s (`float`، *اختياري*) : مدة الصوت المستهدفة بالثواني. يتم تجاهل هذا المعامل عند تقديم `latents`.

latents (`torch.Tensor`، *اختياري*) : كامنات ضجيج مُولّدة مسبقًا من الشكل `(batch_size, duration, latent_dim)`.

num_inference_steps (`int`، القيمة الافتراضية 16) : عدد خطوات إزالة الضوضاء.

guidance_scale (`float`، القيمة الافتراضية 4.0) : مقياس التوجيه للتوجيه الحر من التصنيف.

generator (`torch.Generator` أو `list[torch.Generator]`، *اختياري*) : مولّد عشوائي أو مولّدات عشوائية.

output_type (`str`، الافتراضي `"np"`) : صيغة الإخراج: `"np"` أو `"pt"` أو `"latent"`.

return_dict (`bool`، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع `AudioPipelineOutput`.

callback_on_step_end (`Callable`، *اختياري*) : دالة تُستدعى في نهاية كل خطوة إزالة ضوضاء مع خط الأنابيب، فهرس الخطوة، خطوة الزمن، ومداخلات المصفوفات المحددة بواسطة `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`list`، الافتراضي `["latents"]`) : مدخلات Tensor تُمرَّر إلى `callback_on_step_end`.

**يعيد:** [AudioPipelineOutput](/docs/diffusers/main/ar/api/pipelines/audioldm2#diffusers.AudioPipelineOutput) أو `tuple`

[AudioPipelineOutput](/docs/diffusers/main/ar/api/pipelines/audioldm2#diffusers.AudioPipelineOutput) إذا كان `return_dict` هو True، وإلا فسيكون `tuple`. عند إرجاع tuple، يكون العنصر الأول هو موجة الصوت المولّدة.

الدالة التي تُستدعى عند استدعاء خط الأنابيب للتوليد.

أمثلة:
```py
>>> import soundfile as sf
>>> import torch
>>> from diffusers import LongCatAudioDiTPipeline

>>> pipe = LongCatAudioDiTPipeline.from_pretrained("ruixiangma/LongCat-AudioDiT-1B-Diffusers")
>>> pipe.to("cuda")

>>> prompt = "A calm ocean wave ambience with soft wind in the background."
>>> audio = pipe(
...     prompt,
...     audio_duration_s=5.0,
...     num_inference_steps=20,
...     guidance_scale=4.0,
...     generator=torch.Generator("cuda").manual_seed(42),
... ).audios[0, 0]
>>> sf.write("output.wav", audio, pipe.sample_rate)
```

#### from_pretrained[[diffusers.LongCatAudioDiTPipeline.from_pretrained]]

```python
from_pretrained(pretrained_model_name_or_path: str | os.PathLike, **kwargs)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L638)

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

pretrained_model_name_or_path (`str` أو `os.PathLike`، *اختياري*) : يمكن أن يكون أحد ما يلي: - نص، وهو *repo id* (مثل `CompVis/ldm-text2im-large-256`) لخط أنابيب مُدرَّب مسبقًا مستضاف على Hub. - مسار إلى *مجلد* (مثل `./my_pipeline_directory/`) يحتوي على أوزان خط أنابيب محفوظة باستخدام [save_pretrained()](/docs/diffusers/main/ar/api/pipelines/overview#diffusers.DiffusionPipeline.save_pretrained).

dtype (`torch.dtype` أو `dict[str, Union[str, torch.dtype]]`، *اختياري*) : تجاوز `torch.dtype` الافتراضي وتحميل النموذج بنوع بيانات آخر. لتحميل النماذج الفرعية بأنواع بيانات مختلفة، مرّر `dict` (على سبيل المثال `{'transformer': torch.bfloat16, 'vae': torch.float16}`). اضبط نوع البيانات الافتراضي للمكونات غير المحددة باستخدام `default` (على سبيل المثال `{'transformer': torch.bfloat16, 'default': torch.float16}`). إذا لم يُحدد مكوّن ولم يُضبط نوع بيانات افتراضي، يُستخدم `torch.float32`.

custom_pipeline (`str`, *اختياري*) : > [!WARNING] > 🧪 هذه ميزة تجريبية وقد تتغير في المستقبل.  يمكن أن يكون:  - نصًا، وهو *repo id* (مثل `hf-internal-testing/diffusers-dummy-pipeline`) لخط أنابيب مخصص مستضاف على Hub. يجب أن يحتوي المستودع على ملف يُسمى pipeline.py يحدد خط الأنابيب المخصص. - نصًا، وهو *اسم الملف* لخط أنابيب مجتمعي مستضاف على GitHub تحت [Community](https://github.com/huggingface/diffusers/tree/main/examples/community). يجب أن تتطابق أسماء الملفات الصالحة مع اسم الملف وليس مع سكربت خط الأنابيب (`clip_guided_stable_diffusion` بدلاً من `clip_guided_stable_diffusion.py`). يتم تحميل خطوط الأنابيب المجتمعية دائمًا من فرع main الحالي على GitHub. - مسار إلى مجلد (`./my_pipeline_directory/`) يحتوي على خط أنابيب مخصص. يجب أن يحتوي المجلد على ملف يُسمى `pipeline.py` يحدد خط الأنابيب المخصص.  لمزيد من المعلومات حول كيفية تحميل وإنشاء خطوط أنابيب مخصصة، يرجى الاطلاع على [تحميل وإضافة خطوط أنابيب مخصصة](https://huggingface.co/docs/diffusers/using-diffusers/custom_pipeline_overview)

force_download (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان يجب إجبار إعادة تنزيل أوزان النموذج وملفات الإعداد، مع تجاوز النسخ المخزنة مؤقتًا إذا كانت موجودة.

cache_dir (`Union[str, os.PathLike]`، *اختياري*) : مسار إلى مجلد حيث تُخزَّن مؤقتًا إعدادات النموذج المُسبق التحميل المُحمَّل إذا لم يُستخدم التخزين المؤقت القياسي.

proxies (`Dict[str, str]`، *اختياري*) : قاموس لخوادم الوكيل (proxy servers) للاستخدام حسب البروتوكول أو نقطة النهاية، على سبيل المثال، `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. تُستخدم هذه الوكلاء في كل طلب.

output_loading_info(`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان يجب إرجاع قاموس يحتوي على المفاتيح الناقصة والمفاتيح غير المتوقعة ورسائل الأخطاء أم لا.

local_files_only (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان سيتم تحميل أوزان النموذج المحلية وملفات الإعداد فقط أم لا. إذا تم ضبطه على `True`، فلن يتم تنزيل النموذج من Hub.

token (`str` أو *bool*، *اختياري*) : الرمز الذي يُستخدم كتوكن مصادقة HTTP bearer للملفات البعيدة. إذا كان `True`، يُستخدم التوكن المولّد من `diffusers-cli login` (المخزَّن في `~/.huggingface`).

revision (`str`، *اختياري*، القيمة الافتراضية `"main"`) : إصدار النموذج المحدد الذي سيتم استخدامه. يمكن أن يكون اسم فرع، أو اسم وسم، أو معرف التزامن، أو أي معرّف مسموح به بواسطة Git.

custom_revision (`str`, *اختياري*) : إصدار النموذج المحدد للاستخدام. يمكن أن يكون اسم فرع، أو اسم وسم، أو معرف التزامن (commit id) مشابهًا لـ`revision` عند تحميل خط أنابيب مخصص من Hub. الافتراضي هو أحدث إصدار مستقر من 🤗 Diffusers.

mirror (`str`، *اختياري*) : مصدر مرآة لحل مشاكل إمكانية الوصول إذا كنت تقوم بتنزيل نموذج في الصين. نحن لا نضمن حداثة المصدر أو أمانه، وينبغي لك الرجوع إلى موقع المرآة لمزيد من المعلومات.

device_map (`str`، *اختياري*) : الاستراتيجية التي تحدد كيفية توزيع المكونات المختلفة للخط الأنابيب على الأجهزة المتاحة. حاليًا، يتم دعم `device_map` "balanced" فقط. راجع [هذا](https://huggingface.co/docs/diffusers/main/en/tutorials/inference_with_big_models#device-placement) لمعرفة المزيد.

max_memory (`Dict`، *اختياري*) : قاموس معرّف الجهاز للذاكرة القصوى. إذا لم يتم ضبطه، فسيتم افتراضياً استخدام أقصى ذاكرة متاحة لكل وحدة معالجة رسومية (GPU) والذاكرة العشوائية المتاحة للمعالج المركزي (CPU).

offload_folder (`str` أو `os.PathLike`، *اختياري*) : المسار لتفريغ الأوزان إذا احتوى device_map على القيمة `"disk"`.

offload_state_dict (`bool`, *اختياري*) : إذا كان `True`، يتم نقل حالة المعالج المركزي (CPU state dict) مؤقتًا إلى القرص الصلب لتجنب نفاد ذاكرة المعالج المركزي (CPU RAM) إذا لم يتسع وزن حالة المعالج المركزي (CPU state dict) بالإضافة إلى أكبر شريحة (shard) من نقطة الحفظ (checkpoint). القيمة الافتراضية هي `True` عند وجود أي نقل إلى القرص (disk offload).

low_cpu_mem_usage (`bool`، *اختياري*، القيمة الافتراضية هي `True` إذا كانت إصدار torch >= 1.9.0 وإلا `False`) : تسريع تحميل النموذج من خلال تحميل الأوزان المُسبقة التدريب فقط دون تهيئة الأوزان. كما يحاول هذا الخيار عدم استخدام أكثر من 1x حجم النموذج في ذاكرة المعالج المركزي (بما في ذلك الذروة) أثناء تحميل النموذج. مدعوم فقط لـ PyTorch >= 1.9.0. إذا كنت تستخدم إصدارًا أقدم من PyTorch، فإن تعيين هذا الحجة إلى `True` سيؤدي إلى رفع خطأ.

use_safetensors (`bool`، *اختياري*، القيمة الافتراضية `None`) : إذا كانت القيمة `None`، يتم تنزيل أوزان safetensors إذا كانت متاحة **و** إذا كانت مكتبة safetensors مثبتة. إذا كانت القيمة `True`، يتم تحميل النموذج قسريًا من أوزان safetensors. إذا كانت القيمة `False`، لا يتم تحميل أوزان safetensors.

use_onnx (`bool`، *اختياري*، القيمة الافتراضية `None`) : إذا تم ضبطه على `True`، فسيتم تنزيل أوزان ONNX دائمًا إذا كانت موجودة. إذا تم ضبطه على `False`، فلن يتم تنزيل أوزان ONNX أبدًا. افتراضيًا، تكون القيمة الافتراضية لـ`use_onnx` هي سمة الفئة `_is_onnx` وهي `False` لخطوط الأنابيب غير ONNX و`True` لخطوط الأنابيب ONNX. تشمل أوزان ONNX كلا الملفين المنتهي بـ`.onnx` و`.pb`.

kwargs (باقي قاموس من معاملات الكلمات المفتاحية، *اختياري*) : يمكن استخدامه لتجاوز متغيرات التحميل والحفظ (مكونات خط الأنابيب الخاصة بفئة خط الأنابيب المحددة). تُمرَّر المكونات المُتجاوزة مباشرةً إلى طريقة `__init__` لخط الأنابيب. راجع المثال أدناه لمزيد من المعلومات.

variant (`str`، *اختياري*) : تحميل الأوزان من اسم ملف متغير محدد مثل `"fp16"` أو `"ema"`.

disable_mmap ('bool', *اختياري*، القيمة الافتراضية هي 'False') : ما إذا كان سيتم تعطيل mmap عند تحميل نموذج Safetensors. يمكن أن يؤدي هذا الخيار إلى أداء أفضل عندما يكون النموذج على وحدة تخزين شبكية أو قرص صلب، حيث قد لا تتعامل هذه الوسائط بشكل جيد مع طبيعة عمليات البحث (seek) التي يتطلبها mmap.

أنشئ خط أنابيب انتشار PyTorch من أوزان خط أنابيب مُدرَّب مسبقًا.

يتم ضبط خط الأنابيب في وضع التقييم (`model.eval()`) افتراضيًا.

إذا ظهرت لك رسالة الخطأ أدناه، فأنت بحاجة إلى ضبط الأوزان لمهمتك التالية:

```
Some weights of UNet2DConditionModel were not initialized from the model checkpoint at stable-diffusion-v1-5/stable-diffusion-v1-5 and are newly initialized because the shapes did not match:
- conv_in.weight: found shape torch.Size([320, 4, 3, 3]) in the checkpoint and torch.Size([320, 9, 3, 3]) in the model instantiated
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.
```

> [!TIP] > لاستخدام النماذج الخاصة أو [المقيّدة](https://huggingface.co/docs/hub/models-gated#gated-models)، سجّل الدخول
باستخدام `hf > auth login`.

أمثلة:

```py
>>> from diffusers import DiffusionPipeline

>>> # Download pipeline from huggingface.co and cache.
>>> pipeline = DiffusionPipeline.from_pretrained("CompVis/ldm-text2im-large-256")

>>> # Download pipeline that requires an authorization token
>>> # For more information on access tokens, please refer to this section
>>> # of the documentation](https://huggingface.co/docs/hub/security-tokens)
>>> pipeline = DiffusionPipeline.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5")

>>> # Use a different scheduler
>>> from diffusers import LMSDiscreteScheduler

>>> scheduler = LMSDiscreteScheduler.from_config(pipeline.scheduler.config)
>>> pipeline.scheduler = scheduler
```