---
title: "الجلسة التاسعة | Voice & Multimodal Agents with Pipecat"
aliases:
  - "Session 09 - Voice and Multimodal Agents"
  - "AI Camp v2 - Session 09"
tags:
  - AI-Camp-v2
  - Systems
  - Voice-Agents
  - Pipecat
  - Multimodal-AI
  - Real-Time-AI
session: 9
duration: "3 hours"
duration_minutes: 180
track: Systems
status: planned
language: ar
prerequisites:
  - "[[06_LLM_Engineering_RAG_Application]]"
  - "[[08_Agentic_AI_Tools_MCP_Multi_Agent]]"
---

# الجلسة التاسعة: Voice & Multimodal Agents with Pipecat

> [!info] بطاقة الجلسة
> - **المسار:** Systems — هندسة أنظمة الذكاء الاصطناعي
> - **المدة:** 3 ساعات (180 دقيقة)
> - **المستوى:** متوسط إلى متقدم — طلاب السنوات الأخيرة والخريجون الذين يملكون أساسًا برمجيًا
> - **طبيعة الجلسة:** شرح معماري موجّه + بناء حي + اختبارات تفاعلية
> - **المشروع الرئيسي:** **English Voice Coach — Real-Time Conversational Agent**
> - **الامتداد الاختياري:** **VisionTutor — Image-Aware Voice Assistant**
> - **التقنيات:** Python · Pipecat · WebRTC · VAD · STT · LLM/Tools · TTS

## 🎯 نظرة عامة

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

تستند الجلسة إلى **Pipecat** بوصفه إطارًا لتنظيم خدمات وعمليات معالجة الصوت والنص والوسائط ضمن Pipeline. الهدف ليس جمع خدمات STT وLLM وTTS فقط، بل بناء **تجربة حوارية متماسكة** يمكن قياس جودتها واكتشاف إخفاقاتها.

> [!abstract] الهدف الرئيسي
> بناء Voice Agent قابل للتشغيل والتجربة، ثم تقييم **دقة فهم الكلام، وملاءمة الردود، والمقاطعات، وزمن الاستجابة، وسلامة تنفيذ الأدوات**.

> [!important] نطاق الجلسة
> **المطلوب الأساسي:** إنجاز English Voice Coach متصل بالصوت وقادر على إجراء حوار متعدد الأدوار واستخدام أداة آمنة واحدة على الأقل. **VisionTutor امتداد اختياري** بعد نجاح التطبيق الأساسي؛ لا يُشترط بناء مشروعين كاملين خلال ثلاث ساعات.

## ✅ مخرجات التعلم

بنهاية الجلسة يستطيع الطالب أن:

- يشرح الفرق بين التطبيق النصي والوكيل الصوتي الفوري، وبين **Chained STT → LLM → TTS** و**Speech-to-Speech** على المستوى المعماري.
- يحدد وظيفة **Transport وFrames وProcessors وPipeline** في Pipecat.
- يبيّن دور **VAD** والكشف عن نهاية دور المستخدم وسبب عدم تطابقهما دائمًا.
- يشغّل محادثة صوتية عبر واجهة متوافقة مع **WebRTC**.
- يدمج منطق أداة آمنة من الجلسة الثامنة دون افتراض إمكان توصيل Agent خارجي مباشرة بلا تكييف.
- ينفّذ اختبار **Barge-in** ويتحقق من توقف الكلام السابق وعدم اختلاط الردود.
- يقيس زمن الاستجابة بطريقة قابلة لإعادة المقارنة، ويوثق الفشل وحدوده.
- يحدد متطلبات الخصوصية والتعامل مع أخطاء الاتصال ومفاتيح الخدمات.

---

## 🧠 الجزء النظري — من الصوت إلى قرارٍ ثم صوت

### 1. هندسة الوكيل الصوتي — Voice Agent Architecture

```mermaid
flowchart TD
    A["Microphone / Browser"] --> B["WebRTC Transport"]
    B --> C["VAD + Turn Detection"]
    C --> D["Streaming STT"]
    D --> E["Context + LLM / Agent"]
    E <--> F["Approved Tools"]
    E --> G["Streaming TTS"]
    G --> H["Audio Playback"]
    H --> I["User Interruption"]
    I --> C
```

| المكوّن | وظيفته | السؤال الهندسي |
|---|---|---|
| **Microphone / Transport** | استقبال الصوت وإرساله وتلقي الصوت الناتج | هل الاتصال مستقر؟ وهل توجد معالجة لصدى الصوت؟ |
| **VAD** | رصد احتمال وجود كلام بشري | متى يبدأ الكلام ومتى يصمت المستخدم؟ |
| **Turn Detection** | تحديد ما إذا كان المستخدم أنهى دوره الحواري | هل الصمت القصير يعني نهاية الجملة؟ |
| **STT** | تحويل الصوت إلى نص، وقد يقدم نتائج جزئية ونهائية | ما أثر الضجيج واللهجات وأخطاء التفريغ؟ |
| **LLM / Agent** | فهم الطلب وصياغة الرد واستدعاء الأدوات | هل يملك السياق الصحيح؟ وهل استخدام الأدوات مسموح؟ |
| **TTS** | توليد صوت مسموع من النص الناتج | متى يبدأ أول صوت؟ وهل الرد طويل جدًا؟ |
| **Context & State** | تتبع أدوار المحادثة وحالة التنفيذ | ماذا يحدث عند المقاطعة أو الطلب المتكرر؟ |

> [!note] تمييز مهم
> **VAD ليس كاشفًا مؤكدًا لانتهاء الدور**: قد يتوقف المتحدث لحظة للتفكير ثم يكمل. يؤدي الاعتماد على الصمت وحده إلى ردود مبكرة ومقاطعة المستخدم دون قصد.

### 2. Pipecat: Pipelines, Frames & Processors

- **Pipeline:** ترتيب مكونات المعالجة التي تمر عبرها البيانات.
- **Frames:** رسائل بيانات أو تحكم تحمل الصوت أو النص أو الصور أو أحداث التفاعل.
- **Processors:** مكونات تتعامل مع Frames؛ كالتفريغ والتوليد الصوتي وإدارة السياق.
- **Transport:** قناة التواصل مع العميل؛ ويجب توافق اختيار Transport في طرف العميل والخادم.

يعرض المدرب تمرير رسالة صوتية خلال النظام، ثم يوضح أين تظهر **Transcription Frames** وأين يبدأ إنتاج الصوت، وكيف تؤثر إشارة المقاطعة في العمل الجاري. يستفاد من مثال Pipecat الرسمي كأساس لبيئة المختبر بدل كتابة جميع طبقات الاتصال أثناء الجلسة.

### 3. Streaming, WebRTC & Latency

| المفهوم | التفسير التطبيقي |
|---|---|
| **Streaming** | وصول ومعالجة أجزاء متتابعة من الصوت أو النص بدلاً من انتظار النتيجة النهائية كاملة. |
| **WebRTC** | آلية اتصال فوري مناسبة لنقل الوسائط بين المتصفح والخادم، مع دعم خصائص مهمة لجودة الاتصال الصوتي. |
| **Latency** | الزمن الذي يشعر به المستخدم قبل بدء الرد وما يتبعه من تأخر أثناء المحادثة. |
| **Time to First Audio (TTFA)** | الفترة بين حدث بداية القياس المتفق عليه وبدء وصول/تشغيل صوت رد الوكيل. |
| **Barge-in** | قدرة المستخدم على بدء الكلام أثناء رد الوكيل والتسبب في إيقاف أو تعديل الرد الجاري. |

**مثال ميزانية زمن الاستجابة** (تصوري، وليست أرقام أداء مضمونة):

1. نهاية دور المستخدم أو اتخاذ قرار نهاية الدور.
2. اكتمال النص المطلوب من STT.
3. بدء معالجة النموذج أو الأداة.
4. وصول أول جزء مناسب إلى TTS.
5. وصول أول صوت وتشغيله لدى المستخدم.

> [!tip] القياس الصحيح
> اتفقوا على **نقطة بداية واحدة** لكل تجربة (مثل نهاية دور المستخدم المكتشفة)، ثم احسبوا زمن وصول أول صوت مسموع من جهة العميل. لا تخلطوا بين زمن تنفيذ LLM وحده وزمن الاستجابة الملموسة لدى المستخدم.

### 4. Turn-Taking, Interruption & Context

تشرح الجلسة السيناريوهات التالية:

- يبدأ المستخدم الكلام بينما الوكيل يقرأ ردًا طويلًا → **إيقاف الصوت المتبقي** والتعامل مع الدور الجديد.
- توقف المستخدم مؤقتًا داخل الجملة → لا ينبغي القفز إلى إجابة مبكرة بلا مبرر.
- وصول نص جزئي غير دقيق من STT → لا يُنفّذ إجراء حساس اعتمادًا على افتراض غير مؤكد.
- حدوث مقاطعة خلال تنفيذ أداة → تحديد سياسة واضحة لإلغاء الطلب أو انتظار نتيجته أو تجاهل مخرجات الرد القديم.
- طلب معلومة سابقة في الحوار → استرجاع سياق الجلسة دون خلطه ببيانات جلسة أخرى.

> [!warning] تنبيه حول الأدوات
> **إيقاف الصوت لا يعني أن إجراء الأداة قد أُلغي.** أي أداة ذات آثار جانبية تحتاج قواعد مستقلة للتفويض والتأكيد، وسياسة واضحة للتكرار والإلغاء، حتى لا تؤدي المقاطعة إلى تنفيذ الإجراء مرتين.

### 5. Multimodal Voice Agents

يمكن توسيع تفاعل الوكيل ليشمل صورة من المستخدم أو إطار فيديو، بالإضافة إلى السؤال الصوتي. في هذا النمط يجب الانتباه إلى:

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

> [!example] مثال VisionTutor
> يرسل المستخدم صورة لرسم تخطيطي لشبكة عصبية ثم يسأل بصوته: «اشرح لي ما وظيفة طبقة الـOutput؟». يفهم النظام السؤال في سياق الصورة ثم يرد صوتيًا.

---

## 🧪 المشروع الأساسي — English Voice Coach

### فكرة المنتج

مساعد صوتي يجري محادثة قصيرة باللغة الإنجليزية مع المتعلم، يتكيف مع موضوع المحادثة ويقدم **تغذية راجعة تعليمية بسيطة** حول وضوح الفكرة وصياغة الجملة، ويقترح تعبيرًا أفضل عندما يلزم.

**ما يميّز المشروع عن Voice Chatbot بسيط:**

1. التفاعل قائم على **الأدوار الصوتية** لا رسائل نصية منفصلة فقط.
2. يتمكن المتعلم من **مقاطعة الرد** أو طلب توضيح أثناء الحوار.
3. يستدعي الوكيل **أداة محددة** لاختيار موضوع تدريب أو مستوى صعوبة من بيانات محلية.
4. يظهر الملخص النهائي **ملاحظتين مفيدتين فقط** بدل إغراق المتعلم بالتصحيحات أثناء الحديث.
5. يوثق فريق العمل **زمن الاستجابة ونتائج اختبارات المقاطعة**.

### المتطلبات الوظيفية (MVP)

- [ ] يبدأ المستخدم الجلسة من واجهة Browser متصلة بالوكيل.
- [ ] يستطيع إجراء **ثلاثة أدوار حوارية متتالية على الأقل** صوتيًا.
- [ ] يفهم النظام سؤالًا باللغة الإنجليزية ويرد **بصوت إنجليزي واضح**.
- [ ] يستخدم أداة `get_practice_topic(level)` أو أداة مشابهة منطقها مأخوذ من الجلسة الثامنة.
- [ ] يستطيع المستخدم مقاطعة رد صوتي طويل وتقديم سؤال جديد.
- [ ] يطلب الوكيل توضيحًا عند عدم فهم النص المستخرج بدل افتراض معنى غير مؤكد.
- [ ] يقدم في نهاية الحوار **ملخصًا موجزًا** وتوصية واحدة للتحسين.

### آلية إعادة استخدام Agent الجلسة الثامنة

بدلاً من نقل كامل النظام كما هو، نحدد **واجهة تكييف (Adapter)** بين الوكيل الصوتي والمنطق السابق:

```text
Voice Input → STT → Conversation Turn
                       ↓
              Tool/Agent Adapter
                       ↓
             Approved Tool Result
                       ↓
             Short Voice Response → TTS
```

يجب أن يحترم الـAdapter حدود زمن الانتظار، وأن يميز بين رد قصير مناسب للصوت وبين تقرير طويل يُفضّل عرضه كتابيًا. وإذا لم يكن وكيل الجلسة الثامنة جاهزًا، يُستبدل مؤقتًا بأداة بيانات محلية بسيطة **لضمان إنجاز المشروع الأساسي**.

### خطوات المختبر

#### المرحلة 1 — تشغيل قالب Pipecat جاهز

- [ ] تشغيل مثال Pipecat الرسمي بعد ضبط البيئة والاعتماديات.
- [ ] ضبط مفاتيح الخدمات في `.env` محليًا وعدم رفع الملف إلى Git.
- [ ] تشغيل واجهة اتصال صوتي واختبار صلاحية الميكروفون.
- [ ] التأكد من عمل المسار الأساسي **STT → LLM → TTS**.

#### المرحلة 2 — بناء شخصية English Voice Coach

- [ ] تحديد دور النظام وقواعد الحوار باللغة الإنجليزية.
- [ ] طلب ردود قصيرة وطبيعية تناسب الاستجابة الصوتية.
- [ ] إعداد قائمة موضوعات (Daily Life, Technical Interview, University, Travel).
- [ ] تحديد طريقة تقديم التغذية الراجعة بعد انتهاء التمرين، لا بعد كل كلمة.

#### المرحلة 3 — Tool Integration

- [ ] ربط أداة `get_practice_topic` بواجهة واضحة للمدخلات والنتائج.
- [ ] التحقق من الوسائط المدخلة للأداة وحدود القيم المقبولة.
- [ ] اختبار نجاح الاستدعاء وفشله أو انتهاء مهلته.
- [ ] إرجاع رسالة صوتية مفهومة عندما تتعطل الأداة.

#### المرحلة 4 — Interruption & Reliability

- [ ] تشغيل رد صوتي طويل نسبيًا ومقاطعته بسؤال جديد.
- [ ] التحقق من توقف الصوت القديم وعدم تداخل الإجابات.
- [ ] اختبار صمت قصير وسط كلام المستخدم.
- [ ] اختبار تعذر التفريغ أو انقطاع اتصال خدمة واحدة.

#### المرحلة 5 — Measurements & Demo

- [ ] تنفيذ **5 تجارب** متشابهة وتسجيل TTFA وفق تعريف قياس ثابت.
- [ ] توثيق الحالة الوسيطة/المتوسط وملاحظة أي قيم متطرفة، دون ادعاء دقة إحصائية واسعة.
- [ ] تسجيل حالة نجاح وحالة فشل مع تفسير سبب الفشل المحتمل.
- [ ] تقديم عرض صوتي قصير أو تسجيل بموافقة جميع المشاركين الظاهرين فيه.

### الامتداد الاختياري — VisionTutor

إذا نجح الفريق في الـMVP قبل نهاية المختبر، يضيف **صورة ثابتة واحدة** عبر آلية ملائمة لقدرات خدماته ونموذجه، ثم يطرح سؤالًا صوتيًا عنها ويستقبل شرحًا صوتيًا.

> [!warning] ترتيب الأولويات
> **لا يُطلب** بث فيديو مباشر أو تحليل مستمر للكاميرا أو مزامنة عدة وسائط عالية التردد خلال الجلسة. تُنقل هذه التحسينات إلى مشروع التخرج لمن يرغب.

---

## ⏱️ الجدول الزمني — 180 دقيقة

| الزمن | المدة | النشاط | النتيجة |
|---|---:|---|---|
| 00:00–00:15 | 15 د | عرض حي ونقاش عن تجربة المحادثة الطبيعية | فهم الهدف والمشكلات الواقعية |
| 00:15–00:40 | 25 د | Pipecat Architecture: Transport, Frames, STT/LLM/TTS | مخطط معماري واضح |
| 00:40–01:00 | 20 د | VAD، نهاية الدور، المقاطعات، Streaming، Latency | فهم التحديات والتقييم |
| 01:00–01:10 | 10 د | استراحة | — |
| 01:10–01:30 | 20 د | تشغيل القالب التجهيزي واختبار الاتصال | Voice Pipeline يعمل |
| 01:30–02:05 | 35 د | بناء English Voice Coach متعدد الأدوار | محادثة صوتية تفاعلية |
| 02:05–02:30 | 25 د | ربط أداة من الجلسة الثامنة عبر Adapter | Tool-enabled Voice Agent |
| 02:30–02:50 | 20 د | اختبار المقاطعات والفشل وقياس TTFA | سجل قياسات وحالات |
| 02:50–03:00 | 10 د | عروض مختصرة، أسئلة، وتحديد الواجب | خطة إكمال واضحة |

> [!tip] توزيع الوقت
> يعتمد المختبر على **Starter Template يعمل مسبقًا**؛ لا تتسع 3 ساعات للتعريف بكل خدمات STT/TTS، وبناء واجهة WebRTC من الصفر، ودمج الأدوات، وإضافة الرؤية الحاسوبية معًا.

## 📦 التسليم النهائي (Deliverables)

- [ ] مستودع يحوي **English Voice Coach** قابلًا للتشغيل.
- [ ] `README.md` يشرح المتطلبات والخدمات وخطوات التشغيل ومشكلات الإعداد المتوقعة.
- [ ] `.env.example` يوضح أسماء المتغيرات دون حفظ أي أسرار حقيقية.
- [ ] مخطط مختصر للـPipeline وموضع Tool Adapter.
- [ ] تسجيل أو عرض لتفاعل صوتي من **3 أدوار أو أكثر**.
- [ ] دليل على اختبار **Barge-in** واختبار فشل واحد.
- [ ] ملف `evaluation.md` أو `metrics.csv` يحوي تعريف القياس وخمس نتائج TTFA على الأقل.
- [ ] Pull Request إلى مستودع المعسكر، مع تعليقات مراجعة من الطالب.

### معايير القبول والتقييم

| المعيار | الوزن |
|---|---:|
| صحة تشغيل المسار الصوتي والمحادثة متعددة الأدوار | 30% |
| دمج أداة بشكل واضح وسليم | 20% |
| اختبار المقاطعة وإدارة السياق والفشل | 25% |
| جودة القياسات وتوثيق الأدلة | 15% |
| تنظيم المشروع والتسليم عبر PR | 10% |
| **المجموع** | **100%** |

> [!note] VisionTutor
> يُعامل كتحسين إضافي اختياري **ولا يُعاقَب** من لم ينفذه إذا استوفى متطلبات المشروع الأساسي.

## 🧰 استعدادات المدرب قبل الجلسة

- [ ] اختبار توافق نسخة Pipecat المختارة مع المثال الرسمي وأسماء الواجهات البرمجية؛ **لا تعتمد على أسماء أصناف قديمة دون تحقق**.
- [ ] إعداد Starter Repo يحتوي Pipecat Voice Bot يعمل، وخيار اتصال مناسب للبيئة المحلية.
- [ ] تجهيز موارد الاعتماديات مسبقًا لتقليل أثر ضعف الإنترنت في المختبر.
- [ ] توفير مفاتيح خدمات أو حصص تجريبية **دون مشاركتها داخل الشيفرة أو ملفات Git**.
- [ ] إعداد سيناريو Offline/Recorded Demo بديل عندما يتعذر استخدام الميكروفون أو خدمة سحابية.
- [ ] تحضير ملف اختبار للمقاطعة وبيانات محلية بسيطة لأداة `get_practice_topic`.
- [ ] تجهيز حالات فشل مقصودة: STT غير واضح، استجابة أداة بطيئة، انقطاع TTS.
- [ ] اختبار سماعات الرأس والميكروفونات لتجنب تغذية الصوت الراجعة.

## 🔐 الخصوصية والأمان

- لا تسجلوا أصوات الطلاب أو صورهم دون **موافقة واضحة**؛ ولا تشاركوا التسجيلات خارج نطاق التدريب بغير إذن.
- لا تضعوا مفاتيح API في المستودع أو كود الواجهة الأمامية.
- لا ترسلوا تسجيلات حساسة أو بيانات شخصية إلى خدمات خارجية دون حاجة وإذن مناسبين.
- لا تمنحوا أدوات الوكيل صلاحيات تعديل ملفات أو إجراء معاملات حقيقية ضمن التطبيق التعليمي.
- احذفوا أو أخفوا النصوص الحساسة من Logs وTraces وأمثلة العرض.
- عند تعطل خدمة مهمة، أعيدوا رسالة توضح المشكلة بدلاً من إيهام المستخدم بأن العملية نجحت.

---

## 🔗 مراجع ومصادر رسمية

1. [Pipecat — Official Documentation](https://docs.pipecat.ai/overview/introduction)
2. [Pipecat — Quickstart](https://docs.pipecat.ai/pipecat/get-started/quickstart)
3. [Pipecat — Pipeline & Frame Processing](https://docs.pipecat.ai/pipecat/learn/pipeline)
4. [Pipecat — Your First Agent](https://docs.pipecat.ai/pipecat/learn/your-first-agent)
5. [Pipecat — Choosing a Transport](https://docs.pipecat.ai/client/concepts/choosing-a-transport)
6. [Pipecat — Service Events & Errors](https://docs.pipecat.ai/pipecat/fundamentals/error-handling)
7. [Pipecat — Examples](https://docs.pipecat.ai/pipecat/examples/overview)

> [!note] بخصوص التوثيق
> تتطور واجهات Pipecat بسرعة. اختَر نسخة محددة للمعسكر واتبع أمثلتها الرسمية عند إعداد الكود؛ هذه المذكرة تصف **الأهداف الهندسية** ولا تفترض ثبات كل اسم API في الإصدارات المقبلة.

## 🏁 خلاصة الجلسة

**تطوير Voice Agent احترافي لا ينتهي بمجرد نطق النموذج لإجابته.** التجربة الناجحة تتطلب توقيتًا مناسبًا للأدوار، وإدارة للمقاطعة والسياق، وحدودًا واضحة لاستخدام الأدوات، وقياسًا واقعيًا لزمن الاستجابة، وسلوكًا مفهومًا عند حدوث خطأ.

> [!success] النتيجة المتوقعة
> يخرج الطالب من الجلسة بمساعد صوتي يعمل ويمكن عرضه واختباره، مع **فهم هندسي للأجزاء التي تجعله صالحًا للتطوير إلى منتج حقيقي** في الجلسة العاشرة.
