Eseguire la migrazione dall'API Gemini 2.5 Flash Live Native Audio a Gemini 3.8 Live

Questo documento descrive le modifiche necessarie durante la migrazione da Gemini 2.5 Flash Live API Native Audio a Gemini 3.8 Live.

Modifiche alla chiamata di funzione

Il server audio nativo dell'API Gemini 2.5 Flash Live consente chiamate asincrone agli strumenti. Al contrario, Gemini 3.8 Live supporta la chiamata di funzioni asincrona con le seguenti modifiche del comportamento:

• Gemini 3.8 Live supporta la funzione di blocco delle chiamate di funzioni quando la dichiarazione di funzione dichiara behavior=BLOCKING nella configurazione. Se viene ricevuto un nuovo input durante l'esecuzione della chiamata di funzione di blocco, il server dell'API Live annulla la chiamata di funzione corrente.

• Il comportamento dell'opzione scheduling=interrupt per FunctionResponse è cambiato:

  Pianificazione di FunctionResponse	Chi sta parlando	API Gemini 2.5 Flash Live Audio nativo	Gemini 3.8 Live
  interrompi	modello	Interrompe la risposta immediata del modello attivo e riproduce la risposta dello strumento.	Interrompe la risposta immediata del modello attivo e riproduce la risposta dello strumento.
  interrompere	utente	Interrompe immediatamente; riproduce la risposta dello strumento per l'utente.	Attende che l'utente finisca prima di riprodurre la risposta dello strumento.

Mitigazione di sweep ridondanti e tentativi di chiamata di funzione

A volte Gemini 3.8 Live esegue chiamate di funzioni ridondanti consecutive in un singolo turno quando uno strumento non restituisce risultati. che possono includere la ripetizione di parametri variabili, la scansione da due a cinque volte prima di rispondere. Il comportamento aumenta il tempo al primo audio (TTFA) e produce un discorso di riserva impreciso.

Le chiamate di funzioni ridondanti consecutive sono causate da Gemini 3.8 Live che tenta di risolvere le query. Quando uno strumento restituisce una risposta non informativa o vuota, ad esempio {"results": [], "total_available": 0} o None, il modello non riesce a distinguere tra "esaurimento permanente", "finestra di query troppo ristretta" o "argomento non valido". Il modello tenta di ampliare o variare la query nel tentativo di migliorare i risultati e inizia la scansione.

Applica le seguenti pratiche complementari:

• Restituisci risposte informative alle funzioni: ogni risposta dello strumento deve contenere informazioni sull'errore o sui risultati, per guidare il modello Gemini 3.8 Live su come procedere.

  La tabella seguente descrive i casi, il modo in cui il modello dovrebbe rispondere e l'esempio di payload richiesto per assistere il modello:

  Richiesta	Cosa deve fare il modello	Contenuti del payload obbligatori
  Query valida che non restituisce risultati. Riprovare non servirà.	Interrompi la ricerca, informa l'utente e offri alternative.	status: 'no_results', retryable: false, e un messaggio esplicativo chiaro in linguaggio naturale.
  Argomento non valido o inesistente (ad esempio, "fornitore errato").	Interrompi la ricerca e chiedi all'utente di chiarire o confermare.	status: 'invalid_argument', reason_code, retryable: false e elenco valid_options
  Query valida con una finestra vuota. Una query più ampia è davvero utile.	Esegui un tentativo ragionevole.	status: 'no_results_in_range', retryable: true e retry_hint

  L'esempio seguente mostra un esempio di payload in cui viene chiamato search_appointment, ma tutte le potenziali date non sono disponibili. L'utente si aspetta di provare un fornitore anziché scorrere le date:

  def search_appointment(vendor: str, date: Datetime):
  
  # BEFORE (Invites Sweeping):
  {
    "results": [],
    "total_available": 0
  }
  
  # AFTER - Exhausted / Dead End (Stops Sweeping):
  {
    "results": [],
    "status": "no_availability",
    "retryable": false,
    "message": "No appointments are available for this provider for the foreseeable future. Searching other dates will not surface anything; openings only come from cancellations.",
    "suggested_next_step": "offer_waitlist_or_a_different_provider"
  }
  
  # AFTER - Invalid Argument (Prompts User Clarification):
  {
    "results": [],
    "status": "invalid_argument",
    "reason": "no_such_provider",
    "retryable": false,
    "message": "There is no provider named 'Mr. Johnson'. Ask the caller to confirm the name.",
    "valid_options": ["Dr. Johnson", "Dr. Chen"]
  }
  

  L'esempio seguente mostra la gestione quando check_user_account non restituisce corrispondenze esatte. Il risultato previsto è la modifica della query di ricerca o il trasferimento del controllo all'utente anziché il nuovo tentativo:

  def check_user_account(user_name: str, phone_suffix: str):...
  
  # Checked user account but not existing
  # BEFORE: insufficient error information
  {
   "found": false,
   "matches": []
  }
  
  # AFTER: providing sufficient information to the LiveAPI to avoid further retries because the retries have been exhausted.
  {
   "status": "EXHAUSTED",
   "retryable": false,
   "search_criteria": {
     "name": "Alex Rivera",
     "phone_suffix": "4921"
   },
   "search_scope": "Checked active orders, archived accounts, and guest checkouts across all regions.",
   "guidance": "Exhaustive search completed with 0 matches. Do NOT retry with parameter substrings or variations. Inform the user that no account was found matching those details, and ask if they have an Order ID or billing email."
  }
  

• Norme sui tentativi per le istruzioni di sistema: integra le risposte informative con un vincolo esplicito nelle istruzioni di sistema:

  "When a tool returns no results, tell the user the result before calling the
  tool again. If a call fails for a reason fundamental to the arguments (for
  example, the entity does not exist), do not silently retry with variations;
  ask the user to clarify or confirm. You may broaden a query once when a
  result set is simply empty. Do not run repeated searches with different
  parameters on your own initiative. Hard cap: Never issue more than two
  consecutive function calls without saying something back to the user."
  

Scambio della cronologia delle sessioni

Nell'API Gemini 2.5 Flash Live Native Audio, send_client_content viene utilizzato per configurare l'inizializzazione della cronologia prima del primo turno e per aggiungere cronologia extra a metà sessione.

In Gemini 3.8 Live, se vuoi utilizzare il metodo send_client_content per configurare l'inizializzazione della cronologia, nella sezione HistoryConfig del messaggio di configurazione, imposta initial_history_in_client_content=True. Dopo aver ricevuto setup_complete. Puoi quindi chiamare send_client_content ripetutamente per creare la cronologia fino all'ultimo messaggio in cui è impostato turn_complete=True.

Differenze nel comportamento del modello

La seguente tabella descrive le differenze di comportamento del modello per audio, multimodale e output tra l'API Gemini 2.5 Flash Live Native Audio e Gemini 3.8 Live:

Il seguente codice Python mostra l'impostazione di media_resolution e custom_vocabulary:

# Example: Setting media_resolution for image frames in Gemini 3.8 Live
from google import genai
from google.genai import types

client = genai.Client()

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,  # or MEDIA_RESOLUTION_LOW or MEDIA_RESOLUTION_MEDIUM
)

async with client.aio.live.connect(
    model="gemini-3.8-live",
    config=config,
) as session:
    # Send image frames with the configured resolution budget
    ...


# Example: Setting custom_vocabulary for domain-specific word biasing in Gemini 3.8 Live
from google import genai
from google.genai import types

client = genai.Client()

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    input_audio_transcription=types.AudioTranscriptionConfig(
        custom_vocabulary=["Gemini", "MagicWord", "Lagrangian"],
    ),
)

async with client.aio.live.connect(
    model="gemini-3.8-live",
    config=config,
) as session:
    ...

Compatibilità con framework di terze parti

Le sezioni seguenti descrivono il funzionamento dei framework di terze parti con Gemini 3.8 Live:

LiveKit

Il plug-in Google RealtimeModel di LiveKit supporta Gemini 3.8 Live, ma le seguenti impostazioni non sono supportate nel plug-in Google di LiveKit:

• thinking_level
• enable_affective_dialog
• proactivity

Ti consigliamo di prestare particolare attenzione quando utilizzi il plug-in Google di LiveKit, perché richiede un adattamento accurato per funzionare con Gemini 3.8 Live.

Pipecat

Pipecat supporta Gemini 3.8 Live, con le seguenti modifiche:

• Configurazione del pensiero: rimuovi il livello di ragionamento perché non è supportato da Gemini 3.8 Live.

• Pipecat si connette agli endpoint di Agent Platform utilizzando GoogleVertexLLMService tramite il connettore GeminiLiveLLMService.

Telemetria sull'utilizzo dei token a livello di cavo

Ogni turno del server restituisce un frame usage_metadata. Questo vale per l'API Gemini 2.5 Flash Live Native Audio e Gemini 3.8 Live. I metadati di utilizzo sono più categorizzati, ad esempio token memorizzati nella cache, token di utilizzo degli strumenti, token in diverse modalità e così via.

Limitazioni e mitigazioni note del modello

Per informazioni sulle limitazioni e le mitigazioni note durante lo sviluppo di applicazioni con Gemini 3.8 Live, consulta Limitazioni note.

Elenco di controllo per la migrazione

Di seguito è riportato un elenco di controllo per la migrazione dei client che puoi utilizzare durante la migrazione dall'API Gemini 2.5 Flash Live Native Audio a Gemini 3.8 Live:

• Chiamata di funzione:

  • Risposte informative degli strumenti: refattorizza tutti i gestori degli strumenti per restituire codici di stato espliciti, flag di ripetizione e spiegazioni in linguaggio naturale. Non restituire mai None nudo o {} vuoto.

  • Norme sulle istruzioni di sistema: aggiungi vincoli espliciti che vietano i nuovi tentativi silenziosi degli strumenti, richiedono la conferma dell'utente in caso di errori degli argomenti e limitano le chiamate consecutive agli strumenti.

  • Corrispondenza dell'ID chiamata allo strumento: assicurati che FunctionResponse passi id=fc.id in ogni risposta dello strumento.

  • Modifica del comportamento di pianificazione delle funzioni: quando l'utente parla, il scheduling=interrupt viene declassato a scheduling=when_idle per offrire un'esperienza utente più fluida.

• Sessione: limita send_client_content: utilizza send_client_content per impostare la cronologia iniziale fornendo un HistoryConfig ragionevole.

• Pensiero: elimina gli hack di pensiero a livello di prompt: per evitare l'interruzione dell'audio, rimuovi tutto il testo del prompt che tenta di imporre schemi di pensiero passo passo o limiti di token.