Multimodal Live API

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

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

استخدام Multimodal Live API

يصف هذا القسم كيفية استخدام Multimodal Live API مع أحد حِزم تطوير البرامج (SDK) الخاصة بنا. لمزيد من المعلومات عن واجهة برمجة التطبيقات WebSockets API الأساسية، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات WebSockets API أدناه.

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

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-exp"

config = {"response_modalities": ["TEXT"]}

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

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

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

تلقّي الصوت

يوضّح المثال التالي كيفية تلقّي بيانات صوتية وكتابتها في ملف .wav.

import asyncio
import wave
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-exp"

config = {"response_modalities": ["AUDIO"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        wf = wave.open("audio.wav", "wb")
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(24000)

        message = "Hello? Gemini are you there?"
        await session.send(input=message, end_of_turn=True)

        async for idx,response in async_enumerate(session.receive()):
            if response.data is not None:
                wf.writeframes(response.data)

            # Comment this out to print audio data info
            # if response.server_content.model_turn is not None:
            #      print(response.server_content.model_turn.parts[0].inline_data.mime_type)

        wf.close()

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

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

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

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

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

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

تتيح لك تعليمات النظام توجيه سلوك النموذج استنادًا إلى احتياجاتك وحالات الاستخدام المحدّدة. يمكن ضبط تعليمات النظام في إعدادات الإعداد وستظل سارية طوال الجلسة.

from google.genai import types

config = {
    "system_instruction": types.Content(
        parts=[
            types.Part(
                text="You are a helpful assistant and answer in a friendly tone."
            )
        ]
    ),
    "response_modalities": ["TEXT"],
}

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

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

from google.genai import types

turns = [
    types.Content(parts=[types.Part(text="What is the capital of France?")], role="user"),
    types.Content(parts=[types.Part(text="Paris")], role="model")
]
await session.send(input=types.LiveClientContent(turns=turns))

turns = [types.Content(parts=[types.Part(text="What is the capital of Germany?")], role="user")]
await session.send(input=types.LiveClientContent(turns=turns, turn_complete=True))

{
  "clientContent": {
    "turns": [
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": true
  }
}

بالنسبة إلى السياقات الأطول، ننصحك بتقديم ملخّص رسالة واحد لتحرير فترَة السياق للتفاعلات اللاحقة.

تغيير الأصوات

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

لتحديد صوت، اضبط اسم الصوت ضمن عنصر speechConfig كجزء من إعدادات الجلسة:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
        )
    )
)

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "Kore"
    }
  }
}

استخدام استدعاء الدالة

يمكنك تحديد الأدوات باستخدام واجهة برمجة التطبيقات Multimodal Live API. اطّلِع على الدليل التعليمي لاستدعاء الدوالّ للحصول على مزيد من المعلومات حول استدعاء الدوالّ.

يجب تحديد الأدوات كجزء من إعداد الجلسة:

config = types.LiveConnectConfig(
    response_modalities=["TEXT"],
    tools=[set_light_values]
)

async with client.aio.live.connect(model=model, config=config) as session:
    await session.send(input="Turn the lights down to a romantic level", end_of_turn=True)

    async for response in session.receive():
        print(response.tool_call)

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

يجب أن يردّ العميل باستخدام BidiGenerateContentToolResponse.

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

التعامل مع المقاطعات

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

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

async for response in session.receive():
    if response.server_content.interrupted is not None:
        # The generation was interrupted

القيود

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

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

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

سجل المحادثة

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

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

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

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

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

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

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

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

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

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

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

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

مرجع واجهة برمجة التطبيقات WebSockets

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

الجلسات

يُنشئ اتصال WebSocket جلسة بين العميل وخادم Gemini. بعد أن يبدأ أحد العملاء عملية اتصال جديدة، يمكن للجلسة تبادل الرسائل مع الخادم لإجراء ما يلي:

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

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

راجِع المثال التالي على الإعداد. يُرجى العِلم أنّ طريقة كتابة الاسم في حِزم SDK قد تختلف. يمكنك الاطّلاع على خيارات ضبط حزمة تطوير البرامج (SDK) لنظام التشغيل Python هنا.

{
  "model": string,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object
  },
  "systemInstruction": string,
  "tools": [object]
}

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

لتبادل الرسائل عبر اتصال WebSocket، يجب أن يرسل العميل عنصر JSON عبر اتصال WebSocket مفتوح. يجب أن يتضمّن عنصر JSON حقلًا واحدًا بالضبط من مجموعة العناصر التالية:

{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}

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

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

تلقي الرسائل

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

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

async with client.aio.live.connect(model='...', config=config) as session:
    await session.send(input='Hello world!', end_of_turn=True)
    async for message in session.receive():
        print(message)

ستتضمّن رسائل الخادم حقلًا واحدًا بالضبط من مجموعة العناصر التالية:

{
  "setupComplete": BidiGenerateContentSetupComplete,
  "serverContent": BidiGenerateContentServerContent,
  "toolCall": BidiGenerateContentToolCall,
  "toolCallCancellation": BidiGenerateContentToolCallCancellation
}

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

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

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

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

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

عمليات الدمج مع جهات خارجية

بالنسبة إلى عمليات نشر تطبيقات الويب والتطبيقات المتوافقة مع الأجهزة الجوّالة، يمكنك استكشاف الخيارات من:

• يوميًا
• Livekit