Best practice per l'API Gemini Live

Per ottenere risultati migliori dall'API Gemini Live, concentrati sulle seguenti best practice:

Progetta istruzioni di sistema chiare

Per ottenere le migliori prestazioni dall'API Gemini Live, ti consigliamo di avere un insieme ben definito di istruzioni di sistema (SI) che definisca la persona dell'agente, le regole di conversazione e i guardrail, in questo ordine.

Per ottenere risultati ottimali, separa ogni agente in un SI distinto.

  1. Specifica l'utente tipo dell'agente: fornisci dettagli sul nome, sul ruolo e su eventuali caratteristiche preferite dell'agente. Se vuoi specificare l'accento, assicurati di specificare anche la lingua di output preferita (ad esempio, un accento britannico per un madrelingua inglese).

  2. Specifica le regole di conversazione: inserisci queste regole nell'ordine in cui ti aspetti che il modello le segua. Delinea gli elementi una tantum della conversazione e i loop di conversazione. Ad esempio:

    • Elemento una tantum: raccogli i dettagli di un cliente una sola volta (ad esempio nome, località, numero della carta fedeltà).
    • Loop conversazionale: l'utente può discutere di consigli, prezzi, resi e consegne e potrebbe voler passare da un argomento all'altro. Fai sapere al modello che può continuare questo ciclo di conversazione per tutto il tempo che l'utente desidera.

  3. Specifica le chiamate agli strumenti all'interno di un flusso in frasi distinte: ad esempio, se un passaggio una tantum per raccogliere i dettagli di un cliente richiede la chiamata di una funzione get_user_info, potresti dire: Il primo passaggio consiste nel raccogliere le informazioni dell'utente. Prima di tutto, chiedi all'utente di fornire il suo nome, la sua posizione e il numero della sua carta fedeltà. Quindi richiama get_user_info con questi dettagli.

  4. Aggiungi eventuali guardrail necessari: fornisci eventuali guardrail generali per le conversazioni che non vuoi che il modello esegua. Puoi fornire esempi specifici di cosa vuoi che faccia il modello se si verifica x, ad esempio y. Se non ottieni ancora il livello di precisione preferito, utilizza la parola unmistakably per guidare il modello verso la precisione.

Definisci gli strumenti con precisione

Quando utilizzi gli strumenti con l'API Gemini Live, sii specifico nelle definizioni degli strumenti. Assicurati di indicare a Gemini in quali condizioni deve essere richiamata una chiamata dello strumento. Per maggiori dettagli, consulta Definizioni degli strumenti.

Crea prompt efficaci

  • Utilizza prompt chiari: fornisci esempi di ciò che il modello deve e non deve fare nei prompt e cerca di limitare i prompt a uno per persona o ruolo alla volta. Anziché utilizzare prompt lunghi di più pagine, valuta la possibilità di utilizzare il prompt chaining. Il modello offre le prestazioni migliori per le attività con singole chiamate di funzione.

    # 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.

  • Fornisci comandi e informazioni iniziali: l'API Gemini Live si aspetta l'input utente'utente prima di rispondere. Per fare in modo che l'API Gemini Live avvii la conversazione, includi un prompt che chieda di salutare l'utente o di iniziare la conversazione. Includi informazioni sull'utente per consentire all'API Gemini Live di personalizzare il saluto.

Ripresa della sessione

  1. Utilizza la ripresa trasparente della sessione: configura la connessione con SessionResumptionConfig(transparent=True) in genai.types.LiveConnectConfig. Ciò indica che il client intende gestire il ripristino della sessione senza problemi, consentendo funzionalità come la riproduzione dei messaggi non utilizzati al momento della riconnessione.
from google.genai import types

session_handle: str | None = None

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

  1. Mantieni e aggiorna l'handle della sessione: ascolta i messaggi session_resumption_update dal server. Se resumable è true e viene fornito un new_handle, memorizza questo handle. Questo handle è essenziale per riconnettersi allo stesso stato della sessione in caso di disconnessione.

  2. Memorizza nel buffer i messaggi inviati ed elimina quelli confermati: per assicurarti che nessun messaggio del client venga perso durante una disconnessione, mantieni un buffer dei messaggi inviati all'API Gemini Live. Il messaggio session_resumption_update conterrà last_consumed_client_message_index quando è abilitato il ripristino della sessione trasparente, indicando l'ultimo messaggio elaborato dal server. Utilizza questo indice per rimuovere i messaggi confermati dal buffer. Per monitorare correttamente i messaggi, l'indice gestito dall'utente deve iniziare da 1, perché l'indice 0 indica the session is not resumable. Ogni messaggio successivo inviato al modello deve incrementare questo indice di 1. A ogni ripresa della sessione, assicurati che l'indice venga reimpostato su 1 per il messaggio iniziale trasmesso utilizzando la nuova connessione.

  3. Gestisci le disconnessioni in modo controllato:

    • Segnale GoAway: il server invia un messaggio go_away prima di una disconnessione prevista (ad esempio un timeout). Il gestore deve ascoltare questo evento e poi riconnettersi in modo proattivo utilizzando l'handle più recente.
    • Errori API: i problemi di rete possono causare genai_errors.APIError (ad esempio, i codici 1000 o 1006 per gli errori WebSocket). Il gestore deve rilevare questi errori sia nei loop di invio che in quelli di ricezione e attivare il processo di aggiornamento o riconnessione della sessione.

  4. Implementa la riconnessione con la riproduzione dei messaggi: quando si verifica una disconnessione, crea una nuova sessione utilizzando client.aio.live.connect con l'handle della sessione più recente. Dopo aver stabilito la nuova connessione, invia nuovamente tutti i messaggi nel buffer che non sono stati confermati dal server prima della disconnessione. Il primo messaggio inviato nel buffer deve essere contrassegnato come indice 1 per la nuova connessione.

Attiva la compressione della finestra di contesto

Utilizza ContextWindowCompressionConfig per configurare la finestra di contesto della sessione per le sessioni lunghe, poiché i token audio in tempo reale si accumulano rapidamente (circa 25 token al secondo di audio).

Avviso: la compressione del contesto causerà la perdita della cronologia delle conversazioni.

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),
  ),
)

Calcolo dell'utilizzo dei token

La struttura di fatturazione dell'API Gemini Live è descritta in dettaglio nella pagina dei prezzi. Durante ogni turno, l'API fattura tutti i token di contesto, che comprendono sia la cronologia della conversazione sia le istruzioni di sistema fornite dall'utente. Gli sviluppatori possono monitorare e calcolare questi addebiti estraendo il campo usage_metadata fornito nella risposta del modello.

# 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)

Rilevamento di attività vocale (VAD)

Per impostazione predefinita, l'API Gemini Live utilizza il VAD fornito da Gemini.

Quando utilizzi il VAD dell'API Gemini Live, puoi configurare il modello in modo che restituisca esplicitamente gli eventi VAD. Se attivi explicit_vad_signal nella tua configurazione, puoi monitorare e acquisire questi eventi direttamente dalle risposte del modello.

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)

Se preferisci utilizzare un sistema di rilevamento delle attività personalizzato, devi disattivare il rilevamento di attività vocale (VAD) predefinito e segnalare manualmente i turni dell'utente al modello Gemini. A questo scopo, vengono trasmessi eventi ActivityStart o ActivityEnd per definire i limiti dell'interazione.

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

Imposta il codice lingua dell'audio

Per mantenere la coerenza, ti consigliamo di impostare esplicitamente il codice della lingua e della voce nella configurazione. Senza questa definizione, Gemini potrebbe modificare la lingua della conversazione in base al contesto fornito.

from google.genai import types

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

Inoltre, menziona quanto segue nell'istruzione di sistema:

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

Per i modelli audio in tempo reale come gemini-3.8-live, puoi migliorare la qualità della trascrizione per il riconoscimento vocale automatico (ASR) multilingue fornendo suggerimenti sulla lingua nella configurazione della sessione. Per saperne di più, consulta Attiva la trascrizione audio per la sessione.

Controlla il ritmo del parlato con una voce di riferimento

Nei modelli audio live come Gemini 3.8 Live, i prompt delle istruzioni di sistema che chiedono al modello di parlare più velocemente o più lentamente non modificano in modo affidabile la velocità di sintesi vocale. Per controllare il ritmo del parlato, configura una voce personalizzata nel campo replicated_voice_config con un campione audio di riferimento accelerato o rallentato. Le risposte sintetizzate ereditano la velocità e la cadenza del parlato del campione che passi nel campo voice_sample_audio.

Per regolare il ritmo del parlato con una voce di riferimento, completa i seguenti passaggi:

  1. Ottieni un campione audio pulito di 10-20 secondi della voce target. Puoi registrare un campione della tua voce o acquisire una risposta da una voce predefinita utilizzando un'istruzione di sistema neutra senza istruzioni sul ritmo. Per le linee guida per la registrazione, consulta Utilizza una voce personalizzata.

  2. Applica il time stretching con conservazione del tono per velocizzare o rallentare il campione ed esporta il risultato come file WAV mono little-endian con segno a 16 bit e 24 kHz. Utilizza un filtro che preservi l'intonazione, come il filtro ffmpeg atempo con un moltiplicatore compreso tra 0.8 e 1.5, in modo che la velocità di parlato cambi senza alterare l'intonazione o il timbro della voce. I valori inferiori a 1.0 rallentano la voce, mentre i valori superiori a 1.0 la velocizzano.

    Ad esempio, il seguente comando ffmpeg accelera una registrazione di riferimento a 1,25x, preservando l'intonazione e formattando l'output come file WAV mono a 16 bit e 24 kHz:

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

    Sostituisci quanto segue:

    • INPUT_WAV: il percorso del campione vocale originale.
    • PACED_WAV: il percorso di output per il file WAV mono a 24 kHz con scalabilità temporale.

  3. Leggi il file WAV con scalabilità temporale e passa i relativi byte a ReplicatedVoiceConfig in 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,
            ),
        ),
    ),
)

    Sostituisci PACED_WAV con il percorso del tuo file WAV mono a 24 kHz con scalabilità temporale.

Imposta il codice lingua della trascrizione

Specifica i codici lingua della trascrizione per aumentare l'accuratezza della trascrizione utilizzando il formato del codice lingua BCP-47.

Nota: l'attivazione della trascrizione introduce più token.

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']
  ),
)

Bias di trascrizione con un vocabolario personalizzato

I nomi dei prodotti, i nomi in codice interni, i nomi dei farmaci e gli identificatori stilizzati sono spesso assenti dal vocabolario predefinito di un modello di riconoscimento vocale, pertanto il modello trascrive la parola comune più vicina. Elenca questi termini nel campo custom_vocabulary di input_audio_transcription per orientare il riconoscimento verso le parole effettivamente pronunciate dagli utenti.

from google.genai import types

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

La configurazione precedente produce le seguenti differenze di trascrizione per lo stesso audio:

Termine parlato Senza custom_vocabulary Con custom_vocabulary
QwikPay QuickPay QwikPay
Xylotek Xilotech Xylotek
Traefik Trafic Traefik
latte d'avena latte d'avena latte d'avena

L'ortografia esatta è importante quando passi le trascrizioni a strumenti, query di ricerca o record dei clienti, dove un errore di battitura come QuickPay non corrisponde a nulla.

L'elenco del vocabolario personalizzato nell'istruzione di sistema non produce lo stesso risultato. L'utilizzo di custom_vocabulary influisce sul riconoscimento vocale durante l'elaborazione dell'audio, mentre l'istruzione di sistema raggiunge il modello solo dopo la trascrizione dell'audio.

Mantieni l'elenco mirato a termini di dominio, nomi di brand e nomi propri distinti, anziché a parole comuni di uso quotidiano. Puoi fornire fino a 1000 termini.

Buffering del client

Non eseguire il buffering dell'audio di input in modo significativo (ad esempio, 1 secondo) prima dell'invio. Invia piccoli blocchi (tra 20 ms e 40 ms) per ridurre al minimo la latenza.

Ricampionamento

Assicurati che l'applicazione client ricampiona l'input del microfono (spesso 44,1 kHz o 48 kHz) a 16 kHz prima della trasmissione.

Esempio

Questo esempio combina le best practice e le linee guida per la progettazione delle istruzioni di sistema per guidare le prestazioni del modello come career coach.

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

Definizioni degli strumenti

Questo JSON definisce le chiamate di funzione pertinenti nell'esempio di career coach. Per ottenere risultati ottimali quando definisci le funzioni, includi i relativi nomi, descrizioni, parametri e condizioni di chiamata.

[
 {
   "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"]
   }
 }
]

Ulteriori informazioni

Per ulteriori informazioni sull'utilizzo dell'API Gemini Live, consulta: