# الصوت-النص-إلى-نص

تستقبل نماذج الصوت-النص-إلى-النص كلًا من الصوت والنص كمدخلات، وتولّد النص كمخرج. تجمع هذه النماذج بين فهم الصوت وتوليد اللغة، مما يتيح تنفيذ مهام مثل الإجابة عن الأسئلة الصوتية (مثلًا: «ما الذي يُقال في هذا المقطع؟»، و«ما المشاعر التي ينقلها المتحدث؟»، وفهم الحوار المنطوق. وعلى عكس نماذج التعرف التلقائي على الكلام (ASR) التقليدية التي تقتصر على تحويل الكلام إلى نص، يمكن لنماذج الصوت-النص-إلى-النص الاستدلال على محتوى الصوت، والالتزام بتعليمات معقدة، وإنتاج ردود سياقية بناءً على ما تسمعه.

يُظهر المثال أدناه كيفية تحميل نموذج ومعالج، ومرور ملف صوتي مع موجه نصي، وتوليد استجابة. في هذه الحالة، نطلب من النموذج نقل تسجيل صوتي إلى نص.

```python
from transformers import AudioFlamingo3ForConditionalGeneration, AutoProcessor

model_id = "nvidia/audio-flamingo-3-hf"
processor = AutoProcessor.from_pretrained(model_id)
model = AudioFlamingo3ForConditionalGeneration.from_pretrained(model_id, device_map="auto")

conversation = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Transcribe the input speech."},
            {"type": "audio", "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/WhDJDIviAOg_120_10.mp3"},
        ],
    }
]

inputs = processor.apply_chat_template(
    conversation,
    tokenize=True,
    add_generation_prompt=True,
    return_dict=True,
).to(model.device)

outputs = model.generate(**inputs, max_new_tokens=500)

decoded_outputs = processor.batch_decode(outputs[:, inputs.input_ids.shape[1]:], skip_special_tokens=True)
print(decoded_outputs)
## ["The transcription of the audio is 'summer follows spring the days grow longer and the nights are warm'."]
```

ستُظهر لك هذه الدليل كيفية:

1. قم بضبط [Audio Flamingo 3](https://huggingface.co/nvidia/audio-flamingo-3-hf) على مجموعة بيانات [AudioCaps](https://huggingface.co/datasets/OpenSound/AudioCaps) لتوصيف الصوت باستخدام LoRA.
2. استخدم النموذج المُحسَّن لديك للاستدلال.

> [!TIP]
> للاطلاع على جميع البنى المعمارية ونقاط التفتيش المتوافقة مع هذه المهمة، ننصح بالاطلاع على [صفحة المهمة](https://huggingface.co/tasks/audio-text-to-text).

قبل أن تبدأ، تأكد من تثبيت جميع المكتبات اللازمة:

```bash
pip install transformers datasets peft accelerate
```

ننصحك بتسجيل الدخول إلى حسابك على Hugging Face حتى تتمكن من رفع نموذجك ومشاركته مع المجتمع. عند الطلب، أدخل رمزك (token) لتسجيل الدخول:

```py
>>> from huggingface_hub import notebook_login
>>> notebook_login()
```

## تحميل مجموعة بيانات AudioCaps

ابدأ بتحميل مجموعة بيانات [AudioCaps](https://huggingface.co/datasets/OpenSound/AudioCaps) من مكتبة 🤗 Datasets في وضع البث. تحتوي هذه المجموعة على مقاطع صوتية مع عناوين وصفية، وهي مثالية لمهام وصف الصوت.

```py
>>> from datasets import load_dataset, Audio
>>> dataset = load_dataset("OpenSound/AudioCaps", split="train", streaming=True)
```

قم بتحويل عمود الصوت إلى 16kHz، وهو ما يتطلبه مستخرج ميزات Whisper الخاص بـ Audio Flamingo:

```py
>>> dataset = dataset.cast_column("audio", Audio(sampling_rate=16000))
```

قسّم مجموعة البيانات إلى مجموعات تدريب واختبار باستخدام `.take()` و`.skip()` لمجموعات البيانات التي يتم بثّها:

```py
>>> train_dataset = dataset.take(1000)
>>> eval_dataset = dataset.skip(1000).take(100)
```

انظر إلى مثال:

```py
>>> next(iter(train_dataset))
{'audiocap_id': 91139, 'youtube_id': 'r1nicOVtvkQ', 'start_time': 130, 'caption': 'A woman talks nearby as water pours', 'audio_length': 480000, 'audio': <datasets.features._torchcodec.AudioDecoder object at ...>}

```

تحتوي مجموعة البيانات على:

- `audio`: الموجة الصوتية
- `caption`: النص الوصفي المرافق للصوت

## المعالجة المسبقة

حمّل معالج Audio Flamingo للتعامل مع مدخلات الصوت والنص معًا:

```py
>>> from transformers import AutoProcessor
>>> processor = AutoProcessor.from_pretrained("nvidia/audio-flamingo-3-hf")
```

أنشئ مُجمِّع بيانات (data collator) يعالج أزواج الصوت والنص إلى الصيغة التي يتوقعها Audio Flamingo. يستخدم المُجمِّع قالب المحادثة (chat template) مع مصفوفات صوت مباشرة:

```py
>>> class AudioFlamingo3DataCollator:
...     """Data collator for Audio Flamingo 3 audio captioning training."""
...
...     def __init__(self, processor):
...         self.processor = processor
...
...     def __call__(self, features):
...         conversations = []
...
...         for feature in features:
...             # Build conversation format for Audio Flamingo
...             # Audio is passed directly as an array, no base64 encoding needed
...             sample = [
...                 {
...                     "role": "user",
...                     "content": [
...                         {"type": "text", "text": "Describe the audio."},
...                         {"type": "audio", "audio": feature["audio"].get_all_samples().data[0].numpy()},
...                     ],
...                 },
...                 {
...                     "role": "assistant",
...                     "content": [{"type": "text", "text": feature["caption"]}],
...                 }
...             ]
...             conversations.append(sample)
...
...         # Apply chat template and format labels for training
...         return self.processor.apply_chat_template(
...             conversations,
...             tokenize=True,
...             add_generation_prompt=False,
...             return_dict=True,
...             output_labels=True,  # Automatically creates labels for training
...         )
```

أنشئ مُجمِّع البيانات:

```py
>>> data_collator = AudioFlamingo3DataCollator(processor)
```

## تدريب

> [!TIP]
> إذا لم تكن على دراية بضبط نموذج باستخدام [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer)، فاطّلع على الدرس الأساسي [هنا](../training)!

حمّل نموذج Audio Flamingo. نستخدم دقة `bfloat16` و`device_map="auto"` لاستخدام ذاكرة فعّال:

```py
>>> from transformers import AudioFlamingo3ForConditionalGeneration
>>> import torch
>>> model = AudioFlamingo3ForConditionalGeneration.from_pretrained(
...     "nvidia/audio-flamingo-3-hf",
...     torch_dtype=torch.bfloat16,
...     device_map="auto",
... )
```

### إعداد LoRA

يتيح [LoRA](https://huggingface.co/docs/peft/conceptual_guides/adapter#low-rank-adaptation-lora) (التكيّف منخفض الرتبة) إجراء ضبط دقيق بكفاءة من خلال تدريب عدد صغير فقط من المعاملات الإضافية. قم بإعداد LoRA لاستهداف طبقات الانتباه وطبقات التغذية الأمامية في نموذج اللغة:

```py
>>> from peft import LoraConfig, get_peft_model
>>> lora_config = LoraConfig(
...     r=16,  # LoRA rank
...     lora_alpha=32,  # LoRA scaling factor
...     target_modules=[
...         # Language model attention
...         "q_proj",
...         "k_proj",
...         "v_proj",
...         "o_proj",
...         # Feed-forward layers
...         "gate_proj",
...         "up_proj",
...         "down_proj",
...     ],
...     lora_dropout=0.05,
...     bias="none",
...     task_type="CAUSAL_LM",
... )
>>> model = get_peft_model(model, lora_config)
>>> model.print_trainable_parameters()
trainable params: 44,302,336 || all params: 8,311,517,696 || trainable%: 0.5330

```

> [!TIP]
> يقلل LoRA بشكل كبير من استهلاك الذاكرة ووقت التدريب من خلال تحديث عدد صغير من معاملات المُكيِّف (adapter) بدلاً من النموذج الكامل. يستهدف هذا الإعداد طبقات الانتباه وطبقات التغذية الأمامية في نموذج اللغة مع إبقاء مُشفِّر الصوت مجمّداً، مما يجعل من الممكن ضبط الدقة على وحدة معالجة رسومية واحدة.

### إعداد التدريب

حدّد معاملات التدريب الفائقة في [TrainingArguments](/docs/transformers/main/ar/main_classes/trainer#transformers.TrainingArguments). لاحظ أننا نستخدم `max_steps` بدلاً من عدد الدورات (epochs) لأننا نستخدم مجموعة بيانات متدفقة:

```py
>>> from transformers import TrainingArguments, Trainer
>>> training_args = TrainingArguments(
...     output_dir="audio-flamingo-3-hf-lora-finetuned",
...     per_device_train_batch_size=4,
...     per_device_eval_batch_size=4,
...     gradient_accumulation_steps=4,
...     learning_rate=1e-4,
...     max_steps=500,  # Use max_steps with streaming datasets
...     bf16=True,
...     logging_steps=10,
...     eval_steps=100,
...     save_steps=250,
...     save_total_limit=2,  # Keep only the latest 2 checkpoints
...     save_only_model=True,  # Skip saving optimizer state to save disk space
...     eval_strategy="steps",
...     save_strategy="steps",
...     remove_unused_columns=False,
...     dataloader_num_workers=0,  # Must be 0 for streaming datasets
...     gradient_checkpointing=True,
...     report_to="none",
... )
```

مرّر حُجج التدريب إلى [Trainer](/docs/transformers/main/ar/main_classes/trainer#transformers.Trainer) مع النموذج ومجموعات البيانات ومُجمِّع البيانات:

```py
>>> trainer = Trainer(
...     model=model,
...     args=training_args,
...     train_dataset=train_dataset,
...     eval_dataset=eval_dataset,
...     data_collator=data_collator,
... )
>>> trainer.train()
```

احفظ مُكيّف LoRA والمعالج:

```py
>>> trainer.save_model()
>>> processor.save_pretrained("audio-flamingo-3-hf-lora-finetuned")
['audio-flamingo-3-hf-lora-finetuned/processor_config.json']

```

بمجرد اكتمال التدريب، شارك نموذجك على الـ Hub:

```py
>>> trainer.push_to_hub()
```

## الاستدلال

الآن بعد أن قمت بضبط النموذج، يمكنك استخدامه لتوصيف الصوت.

حمّل النموذج والمعالج المُحسَّنين:

```py
>>> from transformers import AudioFlamingo3ForConditionalGeneration, AutoProcessor
>>> from peft import PeftModel
>>> import torch
>>> base_model = AudioFlamingo3ForConditionalGeneration.from_pretrained(
...     "nvidia/audio-flamingo-3-hf",
...     torch_dtype=torch.bfloat16,
...     device_map="auto",
... )
>>> model = PeftModel.from_pretrained(base_model, "audio-flamingo-3-hf-lora-finetuned")
>>> processor = AutoProcessor.from_pretrained("audio-flamingo-3-hf-lora-finetuned")
```

تحميل عينة صوتية للاستدلال:

```py
>>> from datasets import load_dataset, Audio
>>> dataset = load_dataset("OpenSound/AudioCaps", split="test", streaming=True)
>>> dataset = dataset.cast_column("audio", Audio(sampling_rate=16000))
>>> sample = next(iter(dataset))
>>> audio = sample["audio"]
>>> audio_array = audio.get_all_samples().data[0].numpy() if hasattr(audio, "get_all_samples") else audio["array"]
```

جهّز المدخل بتنسيق محادثة:

```py
>>> messages = [
...     {
...         "role": "user",
...         "content": [
...             {"type": "text", "text": "Describe the audio."},
...             {"type": "audio", "audio": audio_array},
...         ],
...     }
... ]
>>> inputs = processor.apply_chat_template(
...     messages,
...     tokenize=True,
...     add_generation_prompt=True,
...     return_dict=True,
... ).to(device=model.device, dtype=model.dtype)
```

توليد استجابة:

```py
>>> with torch.no_grad():
...     output_ids = model.generate(**inputs, max_new_tokens=100)
>>> # Decode only the generated tokens
>>> input_len = inputs["input_ids"].shape[1]
>>> response = processor.tokenizer.decode(output_ids[0][input_len:], skip_special_tokens=True)
>>> print(response)
## A sewing machine is running while people are talking
```

## خط أنابيب

للاستدلال السريع، استخدم واجهة [Pipeline](/docs/transformers/main/ar/main_classes/pipelines#transformers.Pipeline) مع نموذج `any-to-any`. يستخدم المثال أدناه [Voxtral](https://huggingface.co/mistralai/Voxtral-Mini-3B-2507)، الذي يقبل مدخلات صوتية ونصية وينتج نصًا. راجع [دليل مهمة any-to-any](./any_to_any) لمزيد من الأمثلة.

```python
from transformers import pipeline

pipe = pipeline("any-to-any", model="mistralai/Voxtral-Mini-3B-2507")

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "audio",
                "url": "https://huggingface.co/datasets/raushan-testing-hf/audio-test/resolve/main/glass-breaking-151256.mp3",
            },
            {"type": "text", "text": "What do you hear in this audio?"},
        ],
    },
]

outputs = pipe(text=messages, max_new_tokens=100, return_full_text=False)
print(outputs[0]["generated_text"])
```

## قراءات إضافية

- يتناول [صفحة مهمة النص والصوت إلى النص](https://huggingface.co/tasks/audio-text-to-text) أنواع النماذج، وحالات الاستخدام، ومجموعات البيانات.
- [توثيق PEFT](https://huggingface.co/docs/peft) لمزيد من خيارات تكوين LoRA وطرق المحوِّلات الأخرى.
- بطاقة نموذج [Audio Flamingo 3](https://huggingface.co/nvidia/audio-flamingo-3-hf) للحصول على تفاصيل وإمكانيات محددة للنموذج.