Live API

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

אפשר לנסות את Live API ב-Google AI Studio.

מה חדש

ל-Live API יש תכונות ויכולות חדשות!

יכולות חדשות:

  • שני קולות חדשים ו-30 שפות חדשות, עם אפשרות להגדרת שפת פלט
  • רזולוציות תמונה שניתן להגדיר 66/256 אסימונים
  • כיסוי של פנייה שניתן להגדרה: שליחת כל הקלט כל הזמן או רק כשהמשתמש מדבר
  • הגדרה אם הקלט יפריע למודל או לא
  • זיהוי פעילות קולנית שניתן להתאמה אישית ואירועי לקוח חדשים לסימון סיום תורו
  • ספירת אסימונים
  • אירוע לקוח לאיתות על סיום הסטרימינג
  • העברת טקסט בסטרימינג
  • אפשרות להגדיר המשך סשן, כאשר נתוני הסשן מאוחסנים בשרת למשך 24 שעות
  • תמיכה בסשנים ארוכים יותר באמצעות חלון הקשר נגלל

אירועים של לקוחות חדשים:

  • סיום סטרימינג של אודיו / המיקרופון נסגר
  • אירועי התחלה/סיום של פעילות לשליטה ידנית במעבר של פנייה

אירועים חדשים בשרת:

  • התראה על סיום פעילות שמציינת שצריך להפעיל מחדש את הסשן
  • היצירה הושלמה

שימוש ב-Live API

בקטע הזה נסביר איך להשתמש ב-Live API עם אחד מחבילות ה-SDK שלנו. מידע נוסף על WebSockets API הבסיסי זמין במאמר WebSockets API reference.

שליחה וקבלה של הודעות טקסט

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"

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_client_content(
                turns={"role": "user", "parts": [{"text": message}]}, turn_complete=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-live-001"

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_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

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

            # Un-comment this code 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())

פורמטים של אודיו

ה-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
turns = [
    {"role": "user", "parts": [{"text": "What is the capital of France?"}]},
    {"role": "model", "parts": [{"text": "Paris"}]},
]

await session.send_client_content(turns=turns, turn_complete=False)

turns = [{"role": "user", "parts": [{"text": "What is the capital of Germany?"}]}]

await session.send_client_content(turns=turns, turn_complete=True)
{
  "clientContent": {
    "turns": [
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": true
  }
}

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

שינוי קולות

ה-Live API תומך בקולות הבאים: Puck,‏ Charon,‏ Kore,‏ Fenrir,‏ Aoede,‏ Leda,‏ Orus ו-Zephyr.

כדי לציין קול, מגדירים את שם הקול באובייקט 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"
    }
  }
}

שימוש בקריאה לפונקציה

אפשר להגדיר כלים באמצעות 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_client_content(
        turns={
            "role": "user",
            "parts": [{"text": "Turn the lights down to a romantic level"}],
        },
        turn_complete=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

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

כברירת מחדל, המודל מבצע זיהוי פעילות קול (VAD) באופן אוטומטי על מקור קלט אודיו רצוף. אפשר להגדיר את VAD באמצעות השדה realtimeInputConfig.automaticActivityDetection בהגדרת ההגדרה.

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

לחלופין, אפשר להשבית את ה-VAD האוטומטי על ידי הגדרת realtimeInputConfig.automaticActivityDetection.disabled ל-true בהודעת ההגדרה. בהגדרה הזו, הלקוח אחראי לזיהוי הדיבור של המשתמש ולשליחת ההודעות activityStart ו-activityEnd בזמנים המתאימים. לא נשלח audioStreamEnd בהגדרה הזו. במקום זאת, כל הפסקה בשידור מסומנת בהודעה activityEnd.

התמיכה ב-SDK לתכונה הזו תהיה זמינה בשבועות הקרובים.

קבלת מספר הטוקנים

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

from google.genai import types

async with client.aio.live.connect(
    model='gemini-2.0-flash-live-001',
    config=types.LiveConnectConfig(
        response_modalities=['AUDIO'],
    ),
) as session:
    # Session connected
    while True:
        await session.send_client_content(
            turns=types.Content(role='user', parts=[types.Part(text='Hello world!')])
        )
        async for message in session.receive():
            # The server will periodically send messages that include
            # UsageMetadata.
            if message.usage_metadata:
                usage = message.usage_metadata
                print(
                    f'Used {usage.total_token_count} tokens in total. Response token'
                    ' breakdown:'
                )
            for detail in usage.response_tokens_details:
                match detail:
                  case types.ModalityTokenCount(modality=modality, token_count=count):
                      print(f'{modality}: {count}')

            # For the purposes of this example, placeholder input is continually fed
            # to the model. In non-sample code, the model inputs would come from
            # the user.
            if message.server_content and message.server_content.turn_complete:
                break

הגדרת המשך הסשן

משך הסשן מוגבל, אבל אפשר להגדיר את השדה sessionResumption בהגדרת ההגדרה.

העברת ההגדרה הזו מאפשרת תמיכה בהמשך סשן, וגורמת לשרת לשלוח הודעות SessionResumptionUpdate. אפשר להשתמש בהן כדי להמשיך את הסשן על ידי העברת אסימון ההמשך האחרון בתור SessionResumptionConfig.handle של החיבור הבא.

from google.genai import types

print(f"Connecting to the service with handle {previous_session_handle}...")
async with client.aio.live.connect(
    model="gemini-2.0-flash-live-001",
    config=types.LiveConnectConfig(
        response_modalities=["AUDIO"],
        session_resumption=types.SessionResumptionConfig(
            # The handle of the session to resume is passed here,
            # or else None to start a new session.
            handle=previous_session_handle
        ),
    ),
) as session:
    # Session connected
    while True:
        await session.send_client_content(
            turns=types.Content(
                role="user", parts=[types.Part(text="Hello world!")]
            )
        )
        async for message in session.receive():
            # Periodically, the server will send update messages that may
            # contain a handle for the current state of the session.
            if message.session_resumption_update:
                update = message.session_resumption_update
                if update.resumable and update.new_handle:
                    # The handle should be retained and linked to the session.
                    return update.new_handle

            # For the purposes of this example, placeholder input is continually fed
            # to the model. In non-sample code, the model inputs would come from
            # the user.
            if message.server_content and message.server_content.turn_complete:
                break

לקבל הודעה לפני שהסשן יתנתק

השרת שולח הודעה מסוג GoAway שמסמנת שהחיבור הנוכחי יסתיים בקרוב. ההודעה הזו כוללת את timeLeft, שמציינת את הזמן שנותר ומאפשרת לבצע פעולות נוספות לפני שהחיבור יסתיים כ-ABORTED.

קבלת הודעה כשהיצירה תסתיים

השרת שולח הודעה מסוג generationComplete שמציינת שהמודל סיים ליצור את התגובה.

הפעלת דחיסת חלון ההקשר

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

בקובץ ContextWindowCompressionConfig אפשר להגדיר מנגנון חלון הזזה ומספר האסימונים שמפעילים את הדחיסה.

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    context_window_compression=(
        # Configures compression with default parameters.
        types.ContextWindowCompressionConfig(
            sliding_window=types.SlidingWindow(),
        )
    ),
)

שינוי רזולוציית המדיה

כדי לציין את רזולוציית המדיה של מדיית הקלט, מגדירים את השדה mediaResolution כחלק מהגדרת הסשן:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,
)

מגבלות

כשאתם מתכננים את הפרויקט, כדאי לקחת בחשבון את המגבלות הבאות של Live API ו-Gemini 2.0.

אימות לקוח

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

משך הסשן המקסימלי

משך הסשן מוגבל ל-15 דקות של אודיו או ל-2 דקות של אודיו ווידאו. כשמשך הסשן חורג מהמגבלה, החיבור מסתיים.

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

חלון ההקשר

לכל סשן יש מגבלה של 32 אלף טוקנים בחלון הקשר.

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

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