Multimodal Live API

تتيح Multimodal Live API تفاعلات صوتية ومرئيات ثنائية الاتجاه وسريعة الاستجابة مع Gemini. باستخدام Multimodal Live API، يمكنك منح العميل تجربة محادثات صوتية طبيعية تشبه المحادثات بين البشر، ومنح العميل إمكانية مقاطعة ردود النموذج باستخدام الطلبات الصوتية. يمكن للنموذج معالجة الإدخالات النصية والصوتية والفيديوهات، كما يمكنه تقديم مخرجات نصية وصوتية.

الإمكانات

تتضمّن واجهة برمجة التطبيقات Multimodal Live API الإمكانات الرئيسية التالية:

• التفاعل المتعدّد: يمكن للنموذج الرؤية والسمع والتحدّث.
• التفاعل في الوقت الفعلي بوقت استجابة منخفض: يوفّر هذا التفاعل ردودًا سريعة.
• ذاكرة الجلسة: يحتفظ النموذج بذاكرة لجميع التفاعلات ضمن جلسة واحدة، ويذكّر بالمعلومات التي سمعها أو رآها سابقًا.
• إتاحة استدعاء الدوالّ وتنفيذ الرموز البرمجية واستخدام "بحث Google" كأداة: يتيح ذلك الدمج مع الخدمات ومصادر البيانات الخارجية.
• ميزة "اكتشاف نشاط الصوت" الآلي: يمكن للنموذج تحديدًا التعرّف على الحالات التي يبدأ فيها المستخدم الكلام ويتوقف عنه. يتيح ذلك إجراء تفاعلات طبيعية في شكل محادثات، ويمنح المستخدمين إمكانية مقاطعة النموذج في أي وقت.

يمكنك تجربة واجهة برمجة التطبيقات Multimodal Live API في Google AI Studio.

البدء

Multimodal Live API هي واجهة برمجة تطبيقات مستندة إلى الحالة تستخدم WebSockets.

يعرض هذا القسم مثالاً على كيفية استخدام واجهة برمجة التطبيقات Multimodal Live API لإنشاء نص من نص آخر، باستخدام الإصدار 3.9 من Python أو الإصدارات الأحدث.

تثبيت مكتبة Gemini API

لتثبيت حزمة google-genai ، استخدِم الأمر pip التالي:

!pip3 install google-genai

استيراد المهام التابعة

لاستيراد التبعيات:

from google import genai

إرسال رسالة نصية واستلامها

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model_id = "gemini-2.0-flash-exp"
config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model_id, config=config) as session:
        while True:
            message = input("User> ")
            if message.lower() == "exit":
                break
            await session.send(message, end_of_turn=True)

            async for response in session.receive():
                if response.text is None:
                    continue
                print(response.text, end="")

if __name__ == "__main__":
    asyncio.run(main())

دليل الدمج

يصف هذا القسم آلية عمل الدمج مع Multimodal Live API.

الجلسات

تمثّل الجلسة اتصالاً واحدًا عبر WebSocket بين العميل وخادم Gemini.

بعد أن يبدأ العميل عملية اتصال جديدة، يمكن للجلسة تبادل الرسائل مع الخادم لتنفيذ ما يلي:

• أرسِل نصًا أو محتوى صوتيًا أو فيديو إلى خادم Gemini.
• تلقّي ردود صوتية أو نصية أو ردود على طلبات وظائف من خادم Gemini

يتم إرسال إعدادات الجلسة في أول رسالة بعد الاتصال. يتضمّن إعداد الجلسة النموذج ومَعلمات الإنشاء وتعليمات النظام والأدوات.

اطّلِع على مثال الإعداد التالي:

{​​
  "model": string,
  "generation_config": {​
    "candidate_count": integer,
    "max_output_tokens": integer,
    "temperature": number,
    "top_p": number,
    "top_k": integer,
    "presence_penalty": number,
    "frequency_penalty": number,
    "response_modalities": string,
    "speech_config":object
  },

  "system_instruction": "",
  "tools":[]
}

لمزيد من المعلومات، يُرجى الاطّلاع على BidiGenerateContentSetup.

إرسال الرسائل

الرسائل هي سلاسل بتنسيق JSON يتم تبادلها عبر اتصال WebSocket.

لإرسال رسالة، يجب أن يرسل العميل رسالة مقبولة في سلسلة بتنسيق JSON باستخدام أحد اتصالات WebSocket المفتوحة.

رسائل العملاء المتوافقة

يمكنك الاطّلاع على رسائل العملاء المتوافقة في الجدول التالي:

تلقي الرسائل

لتلقّي الرسائل من Gemini، انتظِر حدث WebSocket "message"، ثم قسِّم النتيجة وفقًا لتعريف رسائل الخادم المتوافقة.

يُرجى الاطّلاع على ما يلي:

ws.addEventListener("message", async (evt) => {
  if (evt.data instanceof Blob) {
    // Process the received data (audio, video, etc.)
  } else {
    // Process JSON response
  }
});

رسائل الخادم المتوافقة

يمكنك الاطّلاع على رسائل الخادم المتوافقة في الجدول التالي:

تعديلات المحتوى المتزايدة

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

راجِع المثال التالي لرسالة السياق:

{
  "client_content": {
    "turns": [
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turn_complete": true
  }
}

يُرجى العلم أنّه على الرغم من أنّ أجزاء المحتوى يمكن أن تكون من النوع functionResponse، يجب عدم استخدام BidiGenerateContentClientContent لتقديم استجابة لطلبات الدالة التي يصدرها النموذج. يجب استخدام BidiGenerateContentToolResponse بدلاً من ذلك. يجب استخدام BidiGenerateContentClientContent فقط لإنشاء سياق سابق أو تقديم إدخال نصي إلى المحادثة.

بث الصوت والفيديو

استدعاء الدوالّ

يجب الإعلان عن جميع الدوالّ في بداية الجلسة من خلال إرسال تعريفات الأدوات كجزء من رسالة BidiGenerateContentSetup.

اطّلِع على الدليل التعليمي لطلب الدوالّ للحصول على مزيد من المعلومات عن طلب الدوالّ.

من طلب واحد، يمكن للنموذج إنشاء طلبات دالة متعددة والتعليمات البرمجية اللازمة لربط نواتج هذه الطلبات. يتم تنفيذ هذا الرمز البرمجي في بيئة sandbox، ما يؤدي إلى إنشاء رسائل BidiGenerateContentToolCall لاحقة. يتم إيقاف التنفيذ مؤقتًا إلى أن تصبح نتائج كلّ استدعاء دالة متوفرة، ما يضمن المعالجة التسلسلية.

من المفترض أن يردّ العميل بـ BidiGenerateContentToolResponse.

تؤثر مدخلات الصوت ومخارجه سلبًا في قدرة النموذج على استخدام طلبات الدالة.

تنسيقات الصوت

تتيح واجهة برمجة التطبيقات Multimodal Live API تنسيقات الصوت التالية:

• تنسيق الصوت الذي يتم إدخاله: صوت PCM خام بترميز 16 بت بمعدّل 16 كيلوهرتز بترتيب الوحدات الأقل أهمية أولاً
• تنسيق الصوت الذي يتم إخراجه: صوت PCM خام بترميز 16 بت بمعدّل 24 كيلوهرتز بترتيب الوحدات الأقل أهمية أولاً

تعليمات النظام

يمكنك تقديم تعليمات للنظام للتحكّم بشكل أفضل في نتائج النموذج وتحديد نبرة الردود الصوتية ومشاعرها.

تتم إضافة تعليمات النظام إلى الطلب قبل بدء التفاعل وتبقى سارية طوال الجلسة.

لا يمكن ضبط تعليمات النظام إلا في بداية الجلسة، بعد الاتصال الأولي مباشرةً. لتقديم المزيد من المدخلات للنموذج أثناء الجلسة، استخدِم ميزة "تعديلات المحتوى المتزايدة".

المقاطعات

يمكن للمستخدمين إيقاف إخراج النموذج في أي وقت. عندما يرصد أسلوب "رصد النشاط الصوتي" (VAD) انقطاعًا، يتم إلغاء عملية الإنشاء الجارية ووضعها في المهملات. لا يتم الاحتفاظ في سجلّ الجلسة إلا بالمعلومات التي تم إرسالها إلى العميل من قبل. بعد ذلك، يُرسِل الخادم رسالة BidiGenerateContentServerContent للإبلاغ عن انقطاع الاتصال.

بالإضافة إلى ذلك، يتخلّص خادم Gemini من أي طلبات وظائف في انتظار المراجعة ويرسل رسالة BidiGenerateContentServerContent تتضمّن أرقام تعريف الطلبات المُلغاة.

الأصوات

تتيح Multimodal Live API الأصوات التالية: Aoede وCharon وFenrir وKore وPuck.

لتحديد صوت، اضبط voice_name ضمن كائن speech_config، كجزء من إعداد الجلسة.

اطّلِع على تمثيل JSON التالي لكائن speech_config:

{
  "voice_config": {
    "prebuilt_voice_config ": {
      "voice_name": <var>VOICE_NAME</var>
    }
  }
}

القيود

ضَع في اعتبارك القيود التالية في Multimodal Live API وGemini 2.0 عند التخطيط لمشروعك.

مصادقة العميل

لا توفّر واجهة برمجة التطبيقات Multimodal Live API سوى مصادقة بين الخوادم ولا يُنصح باستخدامها مباشرةً من قِبل العميل. يجب توجيه إدخال العميل من خلال خادم تطبيق وسيط للمصادقة الآمنة باستخدام واجهة برمجة التطبيقات Multimodal Live API.

بالنسبة إلى التطبيقات على الويب والأجهزة الجوّالة، ننصحك باستخدام عملية الدمج من شركائنا في Daily.

سجل المحادثة

في حين يتتبّع النموذج التفاعلات أثناء الجلسة، لا يتم تخزين سجلّ المحادثات. عند انتهاء جلسة، يتم محو السياق المقابل.

لاستعادة جلسة سابقة أو تزويد النموذج بالسياق السابق لتفاعلات المستخدمين، يجب أن يحتفظ التطبيق بسجلّ المحادثات الخاص به ويستخدم رسالة BidiGenerateContentClientContent لإرسال هذه المعلومات في بداية جلسة جديدة.

الحد الأقصى لمدة الجلسة

تقتصر مدة الجلسة على 15 دقيقة كحد أقصى للصوت أو دقيقتين كحد أقصى للصوت والفيديو. عندما تتجاوز مدة الجلسة الحدّ الأقصى، يتم إنهاء الاتصال.

يعتمد النموذج أيضًا على حجم السياق. قد يؤدي إرسال أجزاء كبيرة من المحتوى إلى جانب أحداث الفيديو والصوت إلى إنهاء الجلسة في وقت أقرب.

ميزة "رصد النشاط الصوتي" (VAD)

ينفِّذ النموذج تلقائيًا ميزة "رصد النشاط الصوتي" (VAD) على ملف تدفق إدخال صوتي متواصل. يكون "توقُّف الصوت أثناء الصمت" مفعَّلاً دائمًا، ولا يمكن ضبط مَعلماته.

عدد الرموز المميّزة

لا يمكن استخدام عدد الرموز المميّزة.

حدود معدّل الاستخدام

تنطبق حدود المعدّلات التالية:

• 3 جلسات متزامنة لكل مفتاح واجهة برمجة تطبيقات
• 4 مليون رمز مميّز في الدقيقة

الرسائل والأحداث

مزيد من المعلومات عن الأنواع الشائعة

لمزيد من المعلومات عن أنواع موارد واجهة برمجة التطبيقات الشائعة الاستخدام Blob Content وFunctionCall وFunctionResponse وGenerationConfig GroundingMetadata وTool، يُرجى الاطّلاع على إنشاء المحتوى.