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"],
}

עדכוני תוכן מצטברים

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

PythonJSON
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 כחלק מהגדרת הסשן:

PythonJSON
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
}

הודעות לקוח נתמכות

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

הודעה תיאור
BidiGenerateContentSetup הגדרות הסשן שיישלחו בהודעה הראשונה
BidiGenerateContentClientContent עדכון מצטבר של התוכן של השיחה הנוכחית שנשלח מהלקוח
BidiGenerateContentRealtimeInput קלט אודיו או וידאו בזמן אמת
BidiGenerateContentToolResponse תגובה להודעה ToolCallMessage שהתקבלה מהשרת

קבלת הודעות

כדי לקבל הודעות מ-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
}

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

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

הודעה תיאור
BidiGenerateContentSetupComplete הודעת BidiGenerateContentSetup מהלקוח, שנשלחת בסיום ההתקנה
BidiGenerateContentServerContent תוכן שנוצר על ידי המודל בתגובה להודעת לקוח
BidiGenerateContentToolCall בקשה ללקוח להריץ את קריאות הפונקציה ולהחזיר את התשובות עם המזהים התואמים
BidiGenerateContentToolCallCancellation ההודעה נשלחת כשקריאה לפונקציה מבוטלת כי המשתמש מפריע לפלט של המודל

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

BidiGenerateContentClientContent

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

הודעה כאן תפריע ליצירת מודל כלשהי.

שדות
turns[]

Content

זה שינוי אופציונלי. התוכן שמצורף לשיחה הנוכחית עם המודל.

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

turn_complete

bool

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

BidiGenerateContentRealtimeInput

קלט של משתמש שנשלח בזמן אמת.

יש כמה הבדלים בין BidiGenerateContentClientContent לבין BidiGenerateContentClientContent:

  • ניתן לשלוח אותם באופן רציף ללא הפרעה ליצירת המודל.
  • אם יש צורך לשלב נתונים שמקובצים בין BidiGenerateContentClientContent ל-BidiGenerateContentRealtimeInput, השרת מנסה לבצע אופטימיזציה כדי לקבל את התגובה הטובה ביותר, אבל אין ערובה לכך.
  • סוף התור לא מצוין באופן מפורש, אלא נגזר מפעילות המשתמש (לדוגמה, סוף הדיבור).
  • עוד לפני סיום התור, הנתונים עוברים עיבוד מצטבר כדי לבצע אופטימיזציה להתחלה מהירה של התשובה מהמודל.
  • תמיד נחשבת לקלט של המשתמש (אי אפשר להשתמש בה כדי לאכלס את היסטוריית השיחות). אפשר לשלוח אותם ברציפות ללא הפסקות. המודל מזהה באופן אוטומטי את תחילת הדיבור של המשתמש ואת סיום הדיבור שלו, ומתחיל או מפסיק את הסטרימינג של התשובה בהתאם. הנתונים מעובדים באופן מצטבר כשהם מגיעים, כדי לצמצם את זמן האחזור.
שדות
media_chunks[]

Blob

זה שינוי אופציונלי. נתוני בייטים מוטמעים לקלט מדיה.

BidiGenerateContentServerContent

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

התוכן נוצר במהירות האפשרית, ולא בזמן אמת. לקוחות יכולים לבחור לאגור את הנתונים ולנגן אותם בזמן אמת.

שדות
turn_complete

bool

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

interrupted

bool

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

grounding_metadata

GroundingMetadata

פלט בלבד. מטא-נתונים של התוכן שנוצר.

model_turn

Content

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

BidiGenerateContentSetup

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

לקוחות צריכים להמתין להודעה BidiGenerateContentSetupComplete לפני שליחת הודעות נוספות.

שדות
model

string

חובה. שם המשאב של הדגם. זהו מזהה לשימוש במודל.

פורמט: models/{model}

generation_config

GenerationConfig

זה שינוי אופציונלי. הגדרות היצירה.

אין תמיכה בשדות הבאים:

  • responseLogprobs
  • responseMimeType
  • logprobs
  • responseSchema
  • stopSequence
  • routingConfig
  • audioTimestamp
system_instruction

Content

זה שינוי אופציונלי. המשתמש סיפק הוראות מערכת עבור המודל.

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

tools[]

Tool

זה שינוי אופציונלי. רשימה של Tools שהמודל עשוי להשתמש בה כדי ליצור את התשובה הבאה.

Tool הוא קטע קוד שמאפשר למערכת לקיים אינטראקציה עם מערכות חיצוניות כדי לבצע פעולה או קבוצת פעולות מחוץ לידע ולהיקף של המודל.

BidiGenerateContentSetupComplete

אין שדות לסוג הזה.

נשלחה בתגובה להודעת BidiGenerateContentSetup מהלקוח.

BidiGenerateContentToolCall

מבקשים מהלקוח להריץ את קריאות הפונקציה ולהחזיר את התשובות עם הערכים התואמים של id.

שדות
function_calls[]

FunctionCall

פלט בלבד. קריאת הפונקציה שרוצים לבצע.

BidiGenerateContentToolCallCancellation

הודעה ללקוח על כך שלא היה צריך לבצע את ה-ToolCallMessage שהונפק בעבר עם הערכים של id שצוינו, ויש לבטל אותו. אם היו תופעות לוואי לקריאות האלה לכלי, לקוחות עשויים לנסות לבטל את הקריאות לכלי. ההודעה הזו מופיעה רק במקרים שבהם הלקוחות מפריעים לסבבים של השרת.

שדות
ids[]

string

פלט בלבד. המזהים של הקריאות לכלי שרוצים לבטל.

BidiGenerateContentToolResponse

תגובה שנוצרה על ידי הלקוח לתגובה ToolCall שהתקבלה מהשרת. אובייקטים ספציפיים מסוג FunctionResponse מותאמים לאובייקטים המתאימים מסוג FunctionCall באמצעות השדה id.

חשוב לזכור שבקריאה לפונקציות של GenerateContent API חד-כיווניות ושל GenerateContent API בסטרימינג בצד השרת, הקריאה מתבצעת על ידי החלפה של החלקים Content, ואילו בקריאה לפונקציות של GenerateContent API דו-כיווניות, הקריאה מתבצעת באמצעות קבוצת ההודעות הייעודית הזו.

שדות
function_responses[]

FunctionResponse

זה שינוי אופציונלי. התגובה לקריאות הפונקציה.

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

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

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

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