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 ביט ב-16kHz little-endian
• פורמט אודיו בפלט: אודיו PCM גולמי של 16 ביט בקצב 24kHz ב-little-endian

סטרימינג של אודיו ווידאו

הוראות למערכת

הוראות המערכת מאפשרות לכם לקבוע את ההתנהגות של מודל על סמך הצרכים הספציפיים שלכם ותרחישי השימוש שלכם. אפשר להגדיר הוראות למערכת בתצורת ההגדרה, והן יישארו בתוקף לכל אורך הסשן.

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 דקות של אודיו או ל-2 דקות של אודיו ווידאו. כשמשך הסשן חורג מהמגבלה, החיבור מסתיים.

המודל מוגבל גם על ידי גודל ההקשר. שליחת קטעי תוכן גדולים לצד הסטרימינג של הווידאו והאודיו עלולה לגרום לסיום מוקדם יותר של הסשן.

זיהוי פעילות קול (VAD)

המודל מבצע זיהוי פעילות קול (VAD) באופן אוטומטי על מקור קלט אודיו רציף. VAD תמיד מופעל, ואי אפשר לשנות את הפרמטרים שלו.

מספר הטוקנים

אין תמיכה בספירת אסימונים.

הגבלות קצב

חלות עליך מגבלות הקצב הבאות:

• 3 סשנים בו-זמנית לכל מפתח API
• 4 מיליון טוקנים לדקה

הפניית API ל-WebSockets

Multimodal Live API הוא ממשק API עם שמירת מצב שמשתמש ב-WebSockets. בקטע הזה מפורטים פרטים נוספים על WebSockets API.

ביקורים

חיבור WebSocket יוצר סשן בין הלקוח לבין שרת Gemini. אחרי שהלקוח יוצר חיבור חדש, הסשן יכול להחליף הודעות עם השרת כדי:

• שליחת טקסט, אודיו או וידאו לשרת Gemini.
• קבלת בקשות לשיחות אודיו, טקסט או פונקציות משרת Gemini.

ההודעה הראשונית אחרי החיבור מגדירה את הגדרות הסשן, כולל המודל, הפרמטרים ליצירה, הוראות המערכת והכלים.

בהגדרה לדוגמה הבאה מוסבר איך עושים את זה. חשוב לזכור שיכול להיות שינוי באותיות הרישיות של השם ב-SDK. כאן אפשר למצוא את אפשרויות ההגדרה של Python SDK.

{
  "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, צריך להאזין לאירוע 'message' ב-WebSocket, ואז לנתח את התוצאה בהתאם להגדרה של הודעות השרת הנתמכות.

תוכלו לעיין במקורות המידע הבאים:

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
}

הודעות שרת נתמכות

בטבלה הבאה מפורטות הודעות השרת הנתמכות:

הודעות ואירועים

מידע נוסף על סוגי קבצים נפוצים

מידע נוסף על סוגי המשאבים הנפוצים של ממשקי API, Blob, ‏ Content, ‏ FunctionCall, ‏ FunctionResponse,‏ GenerationConfig, ‏ GroundingMetadata ו-Tool, זמין במאמר יצירת תוכן.

שילובים עם צד שלישי

לפריסות של אפליקציות לאינטרנט ולנייד, אפשר לבחור מבין האפשרויות הבאות:

• מדי יום
• Livekit