Guida per gli sviluppatori a Gemini 3.8 Live

Gemini 3.8 Live è un modello conversazionale in tempo reale progettato per interazioni vocali e video bidirezionali a bassa latenza e sintesi di avatar live faccia a faccia. Progettato per workflow conversazionali continui, 3.8 Live offre un dialogo affettivo abilitato per impostazione predefinita, un filtro audio proattivo, strumenti di blocco con annullamento automatico e un passaggio dinamico tra più lingue.

Questo documento tratta i seguenti argomenti:

  • Come si inserisce 3.8 Live nella famiglia di modelli Gemini.
  • Funzionalità chiave nella versione 3.8 Live.
  • Integrazione con l'SDK Google Gen AI.
  • Regole e convenzioni API obbligatorie.
  • Migrazione dai modelli API Gemini Live precedenti.

Ruolo nella famiglia di modelli Gemini

3.8 Live è progettato per interazioni di streaming in tempo reale. Funziona tramite WebSocket bidirezionali, elaborando parlato, feed della videocamera in diretta e trasmissioni dello schermo con una latenza inferiore al secondo, generando al contempo audio a 24 kHz e avatar video sincronizzati a 24 FPS.

Specifiche e confronti dei modelli

La seguente tabella mette a confronto le specifiche dei modelli API Gemini Live 3.8 Live e precedenti:

Attributo Gemini 3.8 Live Audio nativo dell'API Gemini 2.5 Flash Live (baseline GA)
ID modello gemini-3.8-live gemini-live-2.5-flash-native-audio
Fase di lancio Disponibilità generale (GA) Disponibilità generale (GA)
Modalità di input Audio (PCM a 16 kHz), video (JPEG a 1 FPS), testo Audio (PCM a 16 kHz), video (JPEG a 1 FPS), testo
Modalità di output Audio (PCM a 24 kHz), video (avatar live MP4 a 24 FPS), testo Audio (PCM a 24 kHz), testo
Sintesi di avatar live Output video sincronizzato a 24 f/s Non supportato
Dialogo empatico Questa opzione è attiva per impostazione predefinita Richiede una configurazione esplicita
Audio proattivo Questa opzione è attiva per impostazione predefinita Richiede una configurazione esplicita
Esecuzione della chiamata di funzione Asincrona non bloccante e bloccante con annullamento automatico (behavior="BLOCKING") Asincrona e sincrona
Gestione dell'interruzione Downgrade dell'interruzione limitata (attende quando l'utente parla) Interruzione immediata (può sovrapporsi all'audio dell'utente)
Lingue supportate Passaggio dinamico tra le lingue supportate durante lo stream Lingue supportate
Bias del dominio Supporta custom_vocabulary in AudioTranscriptionConfig Trascrizione di base standard
Controllo visivo dei token media_resolution configurabile (LOW, MEDIUM, HIGH) Budget di token fisso per frame

Quando utilizzare Gemini 3.8 Live

Utilizza 3.8 Live nei seguenti scenari:

  • Hai bisogno di una bassa latenza di conversazione, di un'alternanza naturale dei turni e di un recupero rapido quando l'utente interrompe (barge-in).
  • La tua app chiama strumenti esterni e richiede un'esecuzione non bloccante in modo che l'output audio continui mentre i sistemi di backend elaborano le richieste.
  • Vuoi eseguire il rendering di avatar digitali parlanti con animazione facciale sincronizzata e sincronizzazione labiale a 24 FPS senza pipeline di rendering esterne.
  • I tuoi utenti conversano in più lingue, il che richiede il rilevamento della lingua durante la conversazione e il passaggio da una lingua supportata all'altra.
  • Hai bisogno di una distorsione del vocabolario specifica per il dominio per la terminologia tecnica, gli SKU o i nomi dei brand.

Per le specifiche complete e i limiti di quota, consulta la pagina del modello 3.8 Live.

Funzionalità principali di Gemini 3.8 Live

3.8 Live introduce le seguenti funzionalità:

  • Sintesi video di avatar live a 24 FPS: 3.8 Live genera stream video MP4 sincronizzati a 24 FPS (response_modalities=["VIDEO"]) direttamente dall'output del modello. Le espressioni facciali e i movimenti delle labbra generati si allineano alla sintesi vocale in tempo reale.

    Puoi utilizzare avatar predefiniti o fornire immagini di riferimento personalizzate per creare concierge digitali, agenti dell'assistenza clienti, tutor virtuali o personaggi interattivi. Per i dettagli sulla configurazione, vedi Configura gli avatar live.

  • Dialogo empatico e audio proattivo attivati per impostazione predefinita:

    • Dialogo empatico: attivato per impostazione predefinita in 3.8 Live. Il modello elabora la prosodia acustica, i segnali vocali, le pause e l'inflessione del parlato nell'input audio dell'utente per regolare il tono della voce e il ritmo della conversazione.
    • Audio proattivo: attivato per impostazione predefinita in 3.8 Live. Il modello filtra il rumore ambientale e il parlato di sottofondo, generando risposte audio solo quando l'utente si rivolge a lui.
  • Chiamata di funzione di blocco asincrona e con annullamento automatico: 3.8 Live offre comportamenti di chiamata allo strumento progettati per il parlato in tempo reale:

    • Esecuzione asincrona non bloccante: quando il modello genera una chiamata allo strumento, la sessione audio rimane attiva in modo che l'agente possa trasmettere in streaming conferme conversazionali ("Fammi recuperare i dettagli del tuo account…") e gestire l'input di follow-up mentre l'app client chiama le API di backend.
    • Annullamento automatico delle chiamate di blocco (behavior="BLOCKING"): quando una dichiarazione di funzione imposta behavior="BLOCKING", la generazione viene messa in pausa fino all'arrivo della risposta dello strumento. Se arriva un nuovo input utente mentre è in corso la chiamata di blocco, il server dell'API Gemini Live annulla la chiamata in attesa.
    • Gestione delle interruzioni limitate: nei modelli precedenti, la restituzione di una risposta dello strumento con scheduling="INTERRUPT" mentre l'utente parlava si sovrapponeva all'audio dell'utente. In 3.8 Live, il server esegue il downgrade della pianificazione a WHEN_IDLE quando l'utente parla e riproduce la risposta dopo che l'utente ha finito di parlare.
  • Cambio dinamico della lingua e vocabolario personalizzato:

    • Supporto multilingue: rileva e passa da una lingua supportata all'altra durante la sessione senza riavviare o riconfigurare la connessione.
    • Bias del vocabolario personalizzato: accetta parole chiave specifiche del dominio, nomi propri, termini medici e codici prodotto in AudioTranscriptionConfig (tramite input_audio_transcription) utilizzando custom_vocabulary per migliorare l'accuratezza della trascrizione.
  • Grounding visivo multimodale con controllo media_resolution: accetta stream video in tempo reale (frame JPEG a 1 FPS, risoluzione consigliata 768x768) e consente di configurare media_resolution (MEDIA_RESOLUTION_LOW, MEDIA_RESOLUTION_MEDIUM, MEDIA_RESOLUTION_HIGH) per bilanciare l'utilizzo dei token per frame e i dettagli visivi.

Guida rapida

Prima di iniziare, esegui l'autenticazione in Google Cloud utilizzando le credenziali predefinite dell'applicazione (ADC).

Nel seguente esempio di codice, sostituisci PROJECT_ID con il tuo ID progetto Google Cloud .

Installa l'SDK

Installa o aggiorna l'SDK Google Gen AI e le dipendenze audio:

pip install --upgrade google-genai websockets numpy

Avvia una sessione bidirezionale con chiamata allo strumento asincrona

L'esempio seguente stabilisce una sessione in tempo reale con gemini-3.8-live, seleziona una voce predefinita (Aoede), configura la personalizzazione del vocabolario personalizzato ed esegue chiamate di funzione asincrone non bloccanti:

import asyncio
from google import genai
from google.genai import types

PROJECT_ID = "PROJECT_ID"
LOCATION = "us-central1"
MODEL_ID = "gemini-3.8-live"

# Initialize the Gen AI client for enterprise.
client = genai.Client(enterprise=True, project=PROJECT_ID, location=LOCATION)

# Define a tool for asynchronous execution.
order_lookup_tool = types.FunctionDeclaration(
    name="lookup_order_status",
    description="Fetches real-time shipping status for a customer order ID.",
    parameters=types.Schema(
        type="OBJECT",
        properties={
            "order_id": types.Schema(
                type="STRING",
                description="The order ID, for example, ORD-8472",
            ),
        },
        required=["order_id"],
    ),
)

# Configure the live connection.
config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    system_instruction=types.Content(
        parts=[
            types.Part.from_text(
                text=(
                    "You are an enterprise concierge. When you call a tool, "
                    "briefly acknowledge the request and tell the user what you're doing. "
                    "If a tool returns no results, inform the user before trying again. "
                    "Never issue more than two consecutive tool calls without speaking."
                )
            )
        ]
    ),
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Aoede")
        ),
    ),
    input_audio_transcription=types.AudioTranscriptionConfig(
        custom_vocabulary=["ORD-8472", "Gemini Live", "Express Shipping"]
    ),
    output_audio_transcription=types.AudioTranscriptionConfig(),
    tools=[types.Tool(function_declarations=[order_lookup_tool])],
)

async def handle_tool_call(session, function_call):
    """Executes backend calls asynchronously without blocking incoming audio."""
    order_id = function_call.args.get("order_id", "")
    await asyncio.sleep(2.0)  # Simulate backend API latency.

    if not order_id.startswith("ORD-"):
        result = {
            "status": "invalid_argument",
            "retryable": False,
            "message": f"Order ID '{order_id}' is invalid. Ask the user to verify.",
        }
    else:
        result = {
            "status": "ok",
            "retryable": False,
            "order_id": order_id,
            "shipping_status": "Out for delivery by 4:00 PM",
        }

    # Send tool response matching the call ID.
    await session.send_tool_response(
        function_responses=[
            types.FunctionResponse(
                id=function_call.id,
                name=function_call.name,
                response=result,
            )
        ]
    )

async def main():
    async with client.aio.live.connect(model=MODEL_ID, config=config) as session:
        print(f"Connected to {MODEL_ID}")

        # Send initial text or stream 16 kHz PCM audio chunks.
        await session.send_realtime_input(
            text="Hi! Can you check the status of order ORD-8472?"
        )

        async for message in session.receive():
            # Handle asynchronous tool calls.
            if message.tool_call:
                for call in message.tool_call.function_calls:
                    asyncio.create_task(handle_tool_call(session, call))

            # Process audio output chunks and transcriptions.
            if message.server_content:
                if (
                    message.server_content.output_transcription
                    and message.server_content.output_transcription.text
                ):
                    print(
                        f"Agent: {message.server_content.output_transcription.text}",
                        end="",
                        flush=True,
                    )

if __name__ == "__main__":
    asyncio.run(main())

Regole e convenzioni obbligatorie per le API

Quando crei con 3.8 Live, segui queste convenzioni dell'API:

  • Risposte informative delle funzioni: non restituire un dizionario vuoto ({}) o None da un gestore di strumenti. Quando uno strumento restituisce un errore o un payload vuoto, 3.8 Live potrebbe generare chiamate di funzione ripetute con argomenti modificati, a meno che la risposta non includa campi di stato. Restituisci campi strutturati in ogni risposta dello strumento:
    • status: una stringa di stato leggibile da macchina, ad esempio "ok", "no_results" o "invalid_argument".
    • retryable: impostato su false quando la ripetizione della chiamata restituisce lo stesso risultato.
    • message o guidance: testo che specifica lo stato da segnalare all'utente.
  • Limiti di nuovi tentativi dello strumento a livello di prompt: includi un limite di nuovi tentativi nel tuo system_instruction. Ad esempio: "Se una chiamata allo strumento non restituisce risultati, informa l'utente anziché eseguire ricerche ripetute con variazioni dei parametri. Non eseguire mai più di due chiamate consecutive allo strumento senza parlare con l'utente."
  • Corrispondenza FunctionResponse rigorosa:
    • Ogni turno FunctionResponse deve fornire l'esatto id del FunctionCall precedente.
    • Passa gli oggetti di risposta direttamente in FunctionResponse.response.
  • Formati audio di streaming:
    • Audio di input: PCM mono a 16 kHz, 16 bit, little-endian (audio/pcm;rate=16000), trasmesso in streaming in blocchi da 20 ms a 100 ms.
    • Audio di output: PCM mono a 24 kHz.
  • Parametri legacy rimossi: non passare enable_affective_dialog o proactivity nella configurazione; queste funzionalità sono attivate per impostazione predefinita in 3.8 Live.
  • Inizializzazione della cronologia delle conversazioni: se inizializzi la cronologia multi-turn utilizzando send_client_content, attendi che l'app client riceva il frame del server setup_complete e configura HistoryConfig(initial_history_in_client_content=True).

Esegui la migrazione a Gemini 3.8 Live

Per saperne di più sulla migrazione da gemini-live-2.5-flash-native-audio a gemini-3.8-live, consulta Esegui la migrazione dall'audio nativo dell'API Gemini 2.5 Flash Live a Gemini 3.8 Live.

Elenco di controllo per gli sviluppatori

Verifica i seguenti elementi prima di eseguire il deployment dell'app:

Risorse aggiuntive

Per maggiori informazioni, consulta le seguenti risorse: