Live API - WebSockets API reference

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

ביקורים

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

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

חיבור WebSocket

כדי להתחיל סשן, צריך להתחבר לנקודת הקצה הזו של WebSocket:

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent

הגדרת הסשן

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

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

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


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

מידע נוסף על שדה ה-API זמין במאמר generationConfig.

שליחת הודעות

כדי להחליף הודעות בחיבור 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)

הודעות שרת עשויות לכלול את השדה usageMetadata, אבל אם לא, הן יכללו רק אחד מהשדות האחרים מההודעה BidiGenerateContentServerMessage. (האיחוד messageType לא מופיע ב-JSON, ולכן השדה יופיע ברמה העליונה של ההודעה).

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

ActivityEnd

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

סימן לסיום הפעילות של המשתמש.

ActivityHandling

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

טיפוסים בני מנייה (enum)
ACTIVITY_HANDLING_UNSPECIFIED אם לא צוין, ברירת המחדל היא START_OF_ACTIVITY_INTERRUPTS.
START_OF_ACTIVITY_INTERRUPTS אם הערך הוא true, התחלת הפעילות תפריע לתשובה של המודל (נקראת גם 'הפרעה'). התשובה הנוכחית של המודל תופסק ברגע ההפרעה. זאת התנהגות ברירת המחדל.
NO_INTERRUPTION התגובה של המודל לא תופרע.

ActivityStart

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

סימון של תחילת הפעילות של המשתמש.

AudioTranscriptionConfig

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

ההגדרה של תמלול האודיו.

AutomaticActivityDetection

הגדרת זיהוי אוטומטי של פעילות.

שדות
disabled

bool

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

StartSensitivity

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

int32

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

EndSensitivity

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

int32

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

BidiGenerateContentClientContent

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

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

שדות
turns[]

Content

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

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

bool

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

BidiGenerateContentRealtimeInput

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

המודלים השונים (אודיו, וידאו וטקסט) מטופלים כשידורים בו-זמניים. אין ערובה לסדר הזרמים האלה.

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

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

Blob

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

הוצא משימוש: במקום זאת, צריך להשתמש באחד מהערכים audio, ‏ video או text.
audio

Blob

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

Blob

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

ActivityStart

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

ActivityEnd

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

bool

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

צריך לשלוח את האירוע הזה רק כשהאפשרות לזיהוי אוטומטי של פעילות מופעלת (זוהי ברירת המחדל).

הלקוח יכול לפתוח מחדש את הסטרימינג על ידי שליחת הודעת אודיו.
text

string

אופציונלי. הם יוצרים את מקור הקלט של הטקסט בזמן אמת.

BidiGenerateContentServerContent

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

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

שדות
generationComplete

bool

פלט בלבד. אם הערך הוא True, המשמעות היא שהמודל הושלם.

אם המודל יופסק במהלך היצירה, לא תופיע ההודעה generation_complete בתור מושעה. הוא יעבור את המצב interrupted > turn_complete.

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

bool

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

bool

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

GroundingMetadata

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

BidiGenerateContentTranscription

פלט בלבד. פלט של תמליל אודיו. התמליל נשלח בנפרד מהודעות אחרות מהשרת, ואין הבטחה לסדר מסוים, במיוחד לא בין serverContent לבין outputTranscription הזה.
modelTurn

Content

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

BidiGenerateContentServerMessage

הודעת התגובה לשיחה BidiGenerateContent.

שדות
usageMetadata

UsageMetadata

פלט בלבד. מטא-נתונים של שימוש לגבי התשובות.
שדה האיחוד messageType. סוג ההודעה. הערך של messageType יכול להיות רק אחת מהאפשרויות הבאות:
setupComplete

BidiGenerateContentSetupComplete

פלט בלבד. נשלחת בתגובה להודעת BidiGenerateContentSetup מהלקוח כשההתקנה מסתיימת.
serverContent

BidiGenerateContentServerContent

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

BidiGenerateContentToolCall

פלט בלבד. מבקשים מהלקוח להריץ את functionCalls ולהחזיר את התשובות עם הערכים התואמים של id.
toolCallCancellation

BidiGenerateContentToolCallCancellation

פלט בלבד. הודעה ללקוח על כך שצריך לבטל ToolCallMessage שהונפק בעבר עם הערכים של id שצוינו.
goAway

GoAway

פלט בלבד. הודעה על כך שהשרת ינותק בקרוב.
sessionResumptionUpdate

SessionResumptionUpdate

פלט בלבד. עדכון של מצב ההמשך של הסשן.

BidiGenerateContentSetup

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

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

שדות
model

string

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

פורמט: models/{model}
generationConfig

GenerationConfig

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

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

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

Content

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

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

Tool

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

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

RealtimeInputConfig

אופציונלי. הגדרת הטיפול בקלט בזמן אמת.
sessionResumption

SessionResumptionConfig

אופציונלי. הגדרת מנגנון להמשך סשן.

אם השדה הזה נכלל, השרת ישלח הודעות SessionResumptionUpdate.
contextWindowCompression

ContextWindowCompressionConfig

אופציונלי. הגדרת מנגנון דחיסת חלון הקשר.

אם תכללו את האפשרות הזו, השרת יפחית באופן אוטומטי את גודל ההקשר אם הוא חורג מהאורך שהוגדר.
outputAudioTranscription

AudioTranscriptionConfig

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

BidiGenerateContentSetupComplete

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

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

BidiGenerateContentToolCall

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

שדות
functionCalls[]

FunctionCall

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

BidiGenerateContentToolCallCancellation

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

שדות
ids[]

string

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

BidiGenerateContentToolResponse

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

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

שדות
functionResponses[]

FunctionResponse

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

BidiGenerateContentTranscription

תמליל של אודיו (קלט או פלט).

שדות
text

string

טקסט התמליל.

ContextWindowCompressionConfig

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

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

SlidingWindow

מנגנון של חלון הזזה.
triggerTokens

int64

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

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

אם לא מגדירים את הערך, ברירת המחדל היא 80% מהמגבלה של חלון ההקשר של המודל. כך נשארים 20% לבקשה הבאה של המשתמש או לתשובה הבאה של המודל.

EndSensitivity

קובעת איך מזוהה סיום הדיבור.

טיפוסים בני מנייה (enum)
END_SENSITIVITY_UNSPECIFIED ערך ברירת המחדל הוא END_SENSITIVITY_HIGH.
END_SENSITIVITY_HIGH הזיהוי האוטומטי מסיים את הדיבור בתדירות גבוהה יותר.
END_SENSITIVITY_LOW זיהוי אוטומטי מסיים את הדיבור בתדירות נמוכה יותר.

GoAway

הודעה על כך שהשרת ינותק בקרוב.

שדות
timeLeft

Duration

הזמן שנותר עד לסיום החיבור יופיע כ-ABORTED.

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

RealtimeInputConfig

הגדרת התנהגות הקלט בזמן אמת ב-BidiGenerateContent.

שדות
automaticActivityDetection

AutomaticActivityDetection

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

ActivityHandling

אופציונלי. מגדיר את ההשפעה של הפעילות.
turnCoverage

TurnCoverage

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

SessionResumptionConfig

הגדרה של המשך סשן.

ההודעה הזו כלולה בהגדרות הסשן בתור BidiGenerateContentSetup.sessionResumption. אם ההגדרה הזו מופעלת, השרת ישלח הודעות SessionResumptionUpdate.

שדות
handle

string

הכינוי של סשן קודם. אם הוא לא קיים, נוצר סשן חדש.

מזהי הסשנים מגיעים מערכים של SessionResumptionUpdate.token בחיבורים קודמים.

SessionResumptionUpdate

עדכון של מצב ההמשך של הסשן.

השדה נשלח רק אם BidiGenerateContentSetup.sessionResumption הוגדר.

שדות
newHandle

string

כינוי חדש שמייצג מצב שאפשר להמשיך ממנו. הערך יהיה ריק אם resumable=false.
resumable

bool

הערך True אם אפשר להמשיך את הסשן הנוכחי בשלב הזה.

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

SlidingWindow

השיטה SlidingWindow פועלת על ידי הטלת תוכן בתחילת חלון ההקשר. ההקשר שייווצר תמיד יתחיל בתחילת תורו של משתמש בתפקיד USER. הוראות המערכת וכל BidiGenerateContentSetup.prefixTurns תמיד יישארו בתחילת התוצאה.

שדות
targetTokens

int64

מספר הטוקנים היעד שרוצים לשמור. ערך ברירת המחדל הוא trigger_tokens/2.

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

StartSensitivity

קובעת איך נקבע תחילת הדיבור.

טיפוסים בני מנייה (enum)
START_SENSITIVITY_UNSPECIFIED ערך ברירת המחדל הוא START_SENSITIVITY_HIGH.
START_SENSITIVITY_HIGH זיהוי אוטומטי יזהה את תחילת הדיבור בתדירות גבוהה יותר.
START_SENSITIVITY_LOW זיהוי אוטומטי יזהה את תחילת הדיבור בתדירות נמוכה יותר.

TurnCoverage

אפשרויות לגבי הקלט שייכלל בתור של המשתמש.

טיפוסים בני מנייה (enum)
TURN_COVERAGE_UNSPECIFIED אם לא צוין, ברירת המחדל היא TURN_INCLUDES_ONLY_ACTIVITY.
TURN_INCLUDES_ONLY_ACTIVITY תורו של המשתמש כולל רק פעילות מאז התור הקודם, לא כולל חוסר פעילות (למשל, שקט בשידור האודיו). זאת התנהגות ברירת המחדל.
TURN_INCLUDES_ALL_INPUT תורו של המשתמש כולל את כל הקלט בזמן אמת מאז התור הקודם, כולל חוסר פעילות (למשל, שקט בשידור האודיו).

UsageMetadata

מטא-נתונים של שימוש לגבי תשובות.

שדות
promptTokenCount

int32

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

int32

מספר הטוקנים בחלק של ההנחיה שנשמר במטמון (התוכן שנשמר במטמון)
responseTokenCount

int32

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

int32

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

int32

פלט בלבד. מספר הטוקנים של המחשבות בדגמי החשיבה.
totalTokenCount

int32

פלט בלבד. המספר הכולל של הטוקנים בבקשה ליצירה (הנחיה + מועמדים לתגובה).
promptTokensDetails[]

ModalityTokenCount

פלט בלבד. רשימת המודלים שעברו עיבוד בקלט הבקשה.
cacheTokensDetails[]

ModalityTokenCount

פלט בלבד. רשימת המודלים של התוכן שנשמר במטמון בקלט הבקשה.
responseTokensDetails[]

ModalityTokenCount

פלט בלבד. רשימת המודלים שהוחזרו בתגובה.
toolUsePromptTokensDetails[]

ModalityTokenCount

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

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

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