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.
שליחה וקבלה של הודעות טקסט
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"],
}
עדכוני תוכן מצטברים
משתמשים בעדכונים מצטברים כדי לשלוח קלט טקסט, ליצור הקשר של סשן או לשחזר הקשר של סשן. בהקשרים קצרים, אפשר לשלוח אינטראקציות מפורטות כדי לייצג את רצף האירועים המדויק:
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
כחלק מהגדרת הסשן:
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
הגדרת המשך סשן
כדי למנוע סיום סשן כשהשרת מאפס מדי פעם את החיבור ל-WebSocket, מגדירים את השדה 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.
שיטות תגובה
אפשר להגדיר רק אופן תגובה אחד (TEXT
או AUDIO
) לכל סשן בהגדרת הסשן. ניסיון להגדיר את שניהם יוביל להצגת הודעת שגיאה בתצורה. כלומר, אפשר להגדיר את המודל להגיב בטקסט או באודיו, אבל לא בשניהם באותו סשן.
אימות לקוח
ה-Live API מספק אימות רק בין שרתים, ולא מומלץ לשימוש ישיר בלקוח. יש לנתב את הקלט של הלקוח דרך שרת אפליקציות ביניים כדי לבצע אימות מאובטח באמצעות Live API.
משך הביקור
כדי להאריך את משך הסשן ללא הגבלה, צריך להפעיל דחיסת סשנים. בלי דחיסת הנתונים, סשנים של אודיו בלבד מוגבלים ל-15 דקות, וסשנים של אודיו וווידאו מוגבלים ל-2 דקות. חריגה מהמגבלות האלה ללא דחיסת הנתונים תגרום לניתוק החיבור.
חלון ההקשר
לסשן יש מגבלה של 32 אלף טוקנים בחלון הקשר.
שפות נתמכות
ב-Live API יש תמיכה בשפות הבאות:
שפה | קוד BCP-47 |
---|---|
גרמנית (גרמניה) | de-DE |
אנגלית (אוסטרליה) | en-AU |
אנגלית (בריטניה) | en-GB |
אנגלית (הודו) | en-IN |
אנגלית (ארה"ב) | en-US |
ספרדית (ארצות הברית) | es-US |
צרפתית (צרפת) | fr-FR |
הינדית (הודו) | hi-IN |
פורטוגזית (ברזיל) | pt-BR |
ערבית (גנרי) | ar-XA |
ספרדית (ספרד) | es-ES |
צרפתית (קנדה) | fr-CA |
אינדונזית (אינדונזיה) | id-ID |
איטלקית (איטליה) | it-IT |
יפנית (יפן) | ja-JP |
טורקית (טורקיה) | tr-TR |
וייטנאמית (וייטנאם) | vi-VN |
בנגלית (הודו) | bn-IN |
גוג'ראטית (הודו) | gu-IN |
קאנדה (הודו) | kn-IN |
מליאלאם (הודו) | ml-IN |
מראטהית (הודו) | mr-IN |
טמילית (הודו) | ta-IN |
טלוגו (הודו) | te-IN |
הולנדית (הולנד) | nl-NL |
קוריאנית (דרום קוריאה) | ko-KR |
סינית מנדרינית (סין) | cmn-CN |
פולנית (פולין) | pl-PL |
רוסית (רוסיה) | ru-RU |
תאילנדית (תאילנד) | th-TH |
שילובים עם צדדים שלישיים
לפריסות של אפליקציות לאינטרנט ולנייד, אפשר לבחור מבין האפשרויות הבאות: