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

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

איך לנסח הוראות מערכת ברורות

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

כדי לקבל את התוצאות הטובות ביותר, כדאי להפריד כל נציג ל-SI נפרד.

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

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

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

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

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

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

כשמשתמשים בכלים עם 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, מאחסנים את הכינוי הזה. הכינוי הזה חיוני כדי להתחבר מחדש לאותו מצב סשן אם מתרחש ניתוק.

  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 לפני ניתוק צפוי (כמו זמן קצוב לתפוגה). המנהל צריך להאזין לאירוע הזה, ואז להתחבר מחדש באופן יזום באמצעות נקודת האחיזה האחרונה.
    • שגיאות API: בעיות ברשת יכולות לגרום ל-genai_errors.APIError (לדוגמה, קודים 1000 או 1006 לשגיאות WebSocket). המנהל צריך לזהות את השגיאות האלה גם בלולאות השליחה וגם בלולאות הקבלה, ולהפעיל את תהליך עדכון הסשן או החיבור מחדש.

  4. הטמעת חיבור מחדש עם הפעלה מחדש של הודעות: כשהחיבור מתנתק, יוצרים סשן חדש באמצעות client.aio.live.connect עם נקודת האחיזה האחרונה של הסשן. אחרי שהחיבור החדש נוצר, שולחים מחדש את כל ההודעות במאגר הזמני שהשרת לא אישר לפני הניתוק. ההודעה הראשונה שנשלחת במאגר צריכה להיות מסומנת באינדקס 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-3.8-live, אתם יכולים לשפר את איכות התמלול של זיהוי דיבור אוטומטי (ASR) בכמה שפות על ידי מתן רמזים לשפה בהגדרות של הסשן. איך מפעילים תמלול אודיו בסשן

שליטה בקצב הדיבור באמצעות קול לדוגמה

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

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

  1. משיגים דגימת אודיו נקייה של 10-20 שניות של הקול הרצוי. אתם יכולים להקליט דגימת קול משלכם או לתעד תשובה מקול מובנה באמצעות הוראת מערכת ניטרלית בלי הנחיות לקצב הדיבור. הנחיות להקלטה מפורטות במאמר שימוש בקול בהתאמה אישית.

  2. מפעילים מתיחת זמן ששומרת על גובה הצליל כדי להאיץ או להאט את הדגימה, ומייצאים את התוצאה כקובץ WAV מונו Little-endian חתום של 24kHz, ‏ 16 ביט. משתמשים במסנן ששומר על גובה הצליל, כמו המסנן ffmpeg atempo, עם מכפיל בין 0.8 ל-1.5, כדי שקצב הדיבור ישתנה בלי לשנות את גובה הצליל או את גוון הקול. ערכים נמוכים מ-1.0 מאטים את הקול, וערכים גבוהים מ-1.0 מאיצים אותו.

    לדוגמה, הפקודה הבאה של ffmpeg מגבירה את המהירות של הקלטת עזר ל-1.25x, תוך שמירה על גובה הצליל ועיצוב הפלט כקובץ WAV מונו של 24kHz ו-16 ביט:

    ffmpeg -i INPUT_WAV \
  -filter:a "atempo=1.25" -ar 24000 -ac 1 -sample_fmt s16 \
  PACED_WAV

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫INPUT_WAV: הנתיב לדגימת הקול המקורית.
    • ‫PACED_WAV: נתיב הפלט של קובץ ה-WAV במונו, 24kHz, עם שינוי קצב הדיבור.

  3. קוראים את קובץ ה-WAV עם קנה המידה של הזמן ומעבירים את הבייטים שלו אל ReplicatedVoiceConfig ב-LiveConnectConfig:

    from google.genai import types

with open("PACED_WAV", "rb") as f:
  voice_sample_bytes = f.read()

config = types.LiveConnectConfig(
    response_modalities=[types.Modality.AUDIO],
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            replicated_voice_config=types.ReplicatedVoiceConfig(
                mime_type="audio/wav",
                voice_sample_audio=voice_sample_bytes,
            ),
        ),
    ),
)

    מחליפים את PACED_WAV בנתיב לקובץ ה-WAV המונופוני של 24kHz עם שינוי קצב הדיבור.

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

כדי לשפר את דיוק התמלול, ציינו את קודי השפה של התמלול בפורמט קוד השפה 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']
  ),
)

הטיית התמלול באמצעות אוצר מילים מותאם אישית

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

from google.genai import types

config = types.LiveConnectConfig(
  input_audio_transcription=types.AudioTranscriptionConfig(
      language_codes=['en-US'],
      custom_vocabulary=['QwikPay', 'Xylotek', 'Traefik', 'oatmilk'],
  ),
)

התצורה הקודמת יוצרת את ההבדלים הבאים בתמלול של אותו קטע אודיו:

מונח מדובר בלי custom_vocabulary עם custom_vocabulary
QwikPay QuickPay QwikPay
Xylotek Xilotech Xylotek
Traefik Trafic Traefik
חלב שיבולת שועל חלב שיבולת שועל חלב שיבולת שועל

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

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

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

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

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

דגימה מחדש

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

דוגמה

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

**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: