שיטות מומלצות לשימוש ב-Gemini Live API

כדי לקבל תוצאות טובות יותר מ-Gemini Live API, כדאי להתמקד בשיטות המומלצות הבאות:

תכנון הוראות מערכת ברורות

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

כדי לקבל את התוצאות הטובות ביותר, מומלץ להפריד כל סוכן ל-SI נפרד.

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

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

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

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

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

הגדרת כלים בצורה מדויקת

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

יצירת הנחיות אפקטיביות

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

    # Prompt chaining example.
chainable_long_prompt = """
You need to perform a sequence of tasks.
First, you should do task1; after that, task2; later, task3; and finally, task4.
"""

# New initial prompt
"""
You need to perform a sequence of tasks. Once you finish the current task, call
the `get_next_prompt` function to get instructions for the next task.
"""

PROMPT_LIST = ["Now, do task1", "Now, do task2", "Now, do task3", "Now, do task 4", "all tasks done"]
def get_next_prompt():
  # Provide this function as a tool to the model. 
  for prompt in PROMPT_LIST:
    yield prompt

# Catch and execute tool call `get_next_prompt` and send the new prompt back to the model.

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

המשך הסשן

  1. שימוש בחידוש הפעלה שקוף של סשן: הגדרת החיבור עם SessionResumptionConfig(transparent=True) ב-genai.types.LiveConnectConfig. האות הזה מציין שהלקוח מתכוון לטפל בחידוש ההפעלה של הסשן בצורה חלקה, וכך לאפשר תכונות כמו הפעלה חוזרת של הודעות שלא נצרכו לאחר חיבור מחדש.
from google.genai import types

session_handle: str | None = None

live_config = types.LiveConnectConfig(
  session_resumption=types.SessionResumptionConfig(
      handle=session_handle,
      transparent=True,
  ),
)

  1. תחזוקה ועדכון של נתוני הפעילות: האזנה להודעות session_resumption_update מהשרת. אם resumable הוא true ומסופק new_handle, המערכת מאחסנת את ה-handle הזה. הטוקן הזה חיוני לחיבור מחדש לאותו מצב סשן אם מתרחש ניתוק.

  2. שמירת הודעות שנשלחו במאגר זמני ומחיקת הודעות שאושר שהתקבלו: כדי לוודא שלא יאבדו הודעות של לקוחות במהלך ניתוק, צריך לשמור במאגר זמני את ההודעות שנשלחו ל-Gemini Live API. ההודעה session_resumption_update תכיל את last_consumed_client_message_index כשחידוש הסשן השקוף מופעל, ותציין את ההודעה האחרונה שעובדה על ידי השרת. אפשר להשתמש באינדקס הזה כדי להסיר מהמאגר הודעות שאושרה קבלתן. כדי לעקוב אחרי הודעות בצורה נכונה, האינדקס שמנוהל על ידי המשתמש צריך להתחיל ב-1, כי אינדקס 0 מציין the session is not resumable. כל הודעה נוספת שנשלחת למודל צריכה להגדיל את האינדקס הזה ב-1. בכל חידוש של סשן, צריך לוודא שהאינדקס מאופס ל-1 עבור ההודעה הראשונית שמועברת באמצעות החיבור החדש.

  3. טיפול בניתוקים בצורה חלקה:

    • אות GoAway: השרת שולח הודעת go_away לפני ניתוק צפוי (כמו פסק זמן). חשבון הניהול צריך להאזין לזה, ואז להתחבר מחדש באופן יזום באמצעות ה-handle העדכני.
    • שגיאות ב-API: בעיות ברשת יכולות לגרום לשגיאות genai_errors.APIError (לדוגמה, קודים 1000 או 1006 לשגיאות ב-WebSocket). חשוב שהחשבון הניהולי יזהה את השגיאות האלה בלולאות השליחה והקבלה, ויפעיל את תהליך עדכון הסשן או החיבור מחדש.

  4. הטמעה של חיבור מחדש עם הפעלה חוזרת של הודעות: כשמתרחש ניתוק, צריך ליצור סשן חדש באמצעות client.aio.live.connect עם ה-handle העדכני של הסשן. אחרי יצירת החיבור החדש, צריך לשלוח מחדש את כל ההודעות במאגר שלא התקבלו מהשרת לפני הניתוק. ההודעה הראשונה שנשלחת במאגר צריכה להיות מסומנת כמדד 1 בחיבור החדש.

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

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

אזהרה: דחיסת ההקשר תגרום לאובדן היסטוריית השיחה.

from google.genai import types

live_config = types.LiveConnectConfig(
  context_window_compression=types.ContextWindowCompressionConfig(
    trigger_tokens=100_000, # For better clarity
    sliding_window=types.SlidingWindow(target_tokens=4_000),
  ),
)

חישוב השימוש בטוקנים

מבנה החיוב של Gemini Live API מפורט בדף התמחור. במהלך כל תור, ה-API מחייב על כל טוקני ההקשר, שכוללים גם את היסטוריית השיחות וגם את הוראות המערכת שהמשתמש סיפק. מפתחים יכולים לעקוב אחרי החיובים האלה ולחשב אותם על ידי חילוץ השדה usage_metadata שמופיע בתשובה של המודל.

# Example code to get token usage
from google.genai import live

session: live.AsyncSession
async for response in session.receive():
  if response.usage_metadata is not None:
    print("Token usage:", response.usage_metadata)

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

כברירת מחדל, Gemini Live API משתמש ב-VAD שמסופק על ידי Gemini.

כשמשתמשים ב-VAD של Gemini Live API, אפשר להגדיר את המודל כך שיחזיר אירועי VAD באופן מפורש. אם מפעילים את explicit_vad_signal בהגדרות, אפשר לעקוב אחרי האירועים האלה ולתעד אותם ישירות מהתשובות של המודל.

from google.genai import types
from google.genai import live

live_config = types.LiveConnectConfig(
  explicit_vad_signal=True
)

session: live.AsyncSession
# In receive loop
async for response in session.receive():
  if response.voice_activity is not None:
    print("Get VAD event", response.voice_activity)

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

from google.genai import live
from google.genai import types

# Disable VAD in config
live_config = types.LiveConnectConfig(
  realtime_input_config=types.RealtimeInputConfig(
    automatic_activity_detection=types.AutomaticActivityDetection(
        disabled=True
    ),
  ),
)

session: live.AsyncSession
await session.send_realtime_input( # Send activity start
    activity_start=types.ActivityStart()
)
for audio_bytes in bytes_to_send_queue: # Send user data
    await session.send_realtime_input(
        audio=types.Blob(
            data=audio_bytes,
            mime_type=f"audio/pcm;rate=16000",
        )
    )
await session.send_realtime_input(activity_end=types.ActivityEnd()) # Send activity end

הגדרת קוד שפת האודיו

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

from google.genai import types

config = types.LiveConnectConfig(
  speech_config=types.SpeechConfig(
    language_code="en-US",
  ),
)

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

RESPOND IN {OUTPUT_LANGUAGE}. YOU MUST RESPOND UNMISTAKABLY IN {OUTPUT_LANGUAGE}.

במודלים של אודיו מקורי כמו gemini-live-2.5-flash-native-audio, אפשר לשפר את איכות התמלול של זיהוי דיבור אוטומטי (ASR) בכמה שפות על ידי הוספת רמזים לגבי השפה בהגדרות של הסשן. מידע נוסף זמין במאמר הפעלת תמלול אודיו בסשן.

הגדרת קוד שפת התמלול

כדי לשפר את דיוק התמליל, צריך לציין את קודי השפה של התמליל בפורמט קוד השפה BCP-47.

הערה: הפעלת התמלול מוסיפה עוד טוקנים.

from google.genai import types

config = types.LiveConnectConfig(
  input_audio_transcription=types.AudioTranscriptionConfig(
      language_codes=['en-US']  # This supports multiple language codes.
  ),
  output_audio_transcription=types.AudioTranscriptionConfig(
      language_codes=['en-US']
  ),
)

אגירת נתונים בצד הלקוח

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

Resampling

לפני השידור, צריך לוודא שאפליקציית הלקוח מבצעת דגימה מחדש של קלט המיקרופון (לרוב 44.1‎ kHz או 48‎ kHz) ל-16‎ kHz.

דוגמה

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

**Persona:**
You are Laura, a career coach from Brooklyn, NY. You specialize in providing
data-driven advice to give your clients a fresh perspective on the career
questions they're navigating. Your special sauce is providing quantitative,
data-driven insights to help clients think about their issues in a different
way. You leverage statistics, research, and psychology as much as possible.
You only speak to your clients in English, no matter what language they speak
to you in.

**Conversational Rules:**

1. **Introduce yourself:** Warmly greet the client.

2. **Intake:** Ask for your client's full name, date of birth, and state they're
calling in from. Call `create_client_profile` to create a new patient profile.

3. **Discuss the client's issue:** Get a sense of what the client wants to
cover in the session. DO NOT repeat what the client is saying back to them in
your response. Don't ask more than a few questions here.

4. **Reframe the client's issue with real data:** NO PLATITUDES. Start providing
data-driven insights for the client, but embed these as general facts within
conversation. This is what they're coming to you for: your unique thinking on
the subjects that are stressing them out. Show them a new way of thinking about
something. Let this step go on for as long as the client wants. As part of this,
if the client mentions wanting to take any actions, update
`add_action_items_to_profile` to remind the client later.

5. **Next appointment:** Call `get_next_appointment` to see if another
appointment has already been scheduled for the client. If so, then share the
date and time with the client and confirm if they'll be able to attend. If
there is no appointment, then call `get_available_appointments` to see openings.
Share the list of openings with the client and ask what they would prefer. Save
their preference with `schedule_appointment`. If the client prefers to schedule
offline, then let them know that's perfectly fine and to use the patient portal.

**General Guidelines:** You're meant to be a witty, snappy conversational
partner. Keep your responses short and progressively disclose more information
if the client requests it. Don't repeat what the client says back to them.
Each of your responses should add to the conversation, not just recap what
the client said. Be relatable by bringing in your own background 
growing up professionally in Brooklyn, NY. If a client tries to get you off
track, gently bring them back to the workflow articulated above.

**Guardrails:** If the client is being hard on themselves, never encourage that.
Remember that your ultimate goal is to create a supportive environment for your
clients to thrive.

הגדרות של כלי

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

[
 {
   "name": "create_client_profile",
   "description": "Creates a new client profile with their personal details. Returns a unique client ID. \n**Invocation Condition:** Invoke this tool *only after* the client has provided their full name, date of birth, AND state. This should only be called once at the beginning of the 'Intake' step.",
   "parameters": {
     "type": "object",
     "properties": {
       "full_name": {
         "type": "string",
         "description": "The client's full name."
       },
       "date_of_birth": {
         "type": "string",
         "description": "The client's date of birth in YYYY-MM-DD format."
       },
       "state": {
         "type": "string",
         "description": "The 2-letter postal abbreviation for the client's state (e.g., 'NY', 'CA')."
       }
     },
     "required": ["full_name", "date_of_birth", "state"]
   }
 },
 {
   "name": "add_action_items_to_profile",
   "description": "Adds a list of actionable next steps to a client's profile using their client ID. \n**Invocation Condition:** Invoke this tool *only after* a list of actionable next steps has been discussed and agreed upon with the client during the 'Actions' step. Requires the `client_id` obtained from the start of the session.",
   "parameters": {
     "type": "object",
     "properties": {
       "client_id": {
         "type": "string",
         "description": "The unique ID of the client, obtained from create_client_profile."
       },
       "action_items": {
         "type": "array",
         "items": {
           "type": "string"
         },
         "description": "A list of action items for the client (e.g., ['Update resume', 'Research three companies'])."
       }
     },
     "required": ["client_id", "action_items"]
   }
 },
 {
   "name": "get_next_appointment",
   "description": "Checks if a client has a future appointment already scheduled using their client ID. Returns the appointment details or null. \n**Invocation Condition:** Invoke this tool at the *start* of the 'Next Appointment' workflow step, immediately after the 'Actions' step is complete. This is used to check if an appointment *already exists*.",
   "parameters": {
     "type": "object",
     "properties": {
       "client_id": {
         "type": "string",
         "description": "The unique ID of the client."
       }
     },
     "required": ["client_id"]
   }
 },
 {
   "name": "get_available_appointments",
   "description": "Fetches a list of the next available appointment slots. \n**Invocation Condition:** Invoke this tool *only if* the `get_next_appointment` tool was called and it returned `null` (or an empty response), indicating no future appointment is scheduled.",
   "parameters": {
     "type": "object",
     "properties": {}
   }
 },
 {
   "name": "schedule_appointment",
   "description": "Books a new appointment for a client at a specific date and time. \n**Invocation Condition:** Invoke this tool *only after* `get_available_appointments` has been called, a list of openings has been presented to the client, and the client has *explicitly confirmed* which specific date and time they want to book.",
   "parameters": {
     "type": "object",
     "properties": {
       "client_id": {
         "type": "string",
         "description": "The unique ID of the client."
       },
       "appointment_datetime": {
         "type": "string",
         "description": "The chosen appointment slot in ISO 8601 format (e.g., '2025-10-30T14:30:00')."
       }
     },
     "required": ["client_id", "appointment_datetime"]
   }
 }
]

מידע נוסף

מידע נוסף על שימוש ב-Gemini Live API: