Guida per gli sviluppatori a Gemini 3.8 Live

Gemini 3.8 Live è un modello conversazionale in tempo reale creato per interazioni vocali e video bidirezionali a bassa latenza e per la sintesi di avatar live faccia a faccia. Progettato per flussi di lavoro conversazionali continui, 3.8 Live fornisce dialogo empatico, filtro audio proattivo, strumenti di blocco con annullamento automatico e cambio lingua multilingue dinamico attivati per impostazione predefinita.

Questo documento tratta i seguenti argomenti:

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

Ruolo nella famiglia Gemini

3.8 Live è progettato per interazioni di streaming in tempo reale. Opera su WebSocket bidirezionali, elaborando la voce, i feed della videocamera live e le trasmissioni dello schermo con una latenza inferiore al secondo durante la generazione di audio a 24 kHz e avatar video sincronizzati a 24 FPS.

Specifiche e confronti dei modelli

La tabella seguente confronta le specifiche tra 3.8 Live e i modelli API Gemini Live precedenti:

Quando utilizzare Gemini 3.8 Live

Utilizza 3.8 Live nei seguenti scenari:

• Hai bisogno di una bassa latenza conversazionale, di un'alternanza naturale e di un ripristino rapido quando l'utente interrompe (interruzione).
• 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 fare il rendering di avatar digitali parlanti con animazione facciale e playback a 24 FPS senza pipeline di rendering esterne.
• Gli utenti conversano in più lingue, il che richiede il rilevamento e il cambio della lingua durante lo streaming tra le lingue supportate.
• Hai bisogno di un bias del vocabolario specifico 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 voce sintetizzata in tempo reale.

  Puoi utilizzare avatar stock 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, consulta Configurare 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 vocale nell'input audio dell'utente per regolare il tono vocale e il ritmo conversazionale.
  • Audio proattivo: attivato per impostazione predefinita in 3.8 Live. Il modello filtra il rumore ambientale e la voce 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 fornisce comportamenti di chiamata di strumenti progettati per la voce in tempo reale:

  • Esecuzione asincrona non bloccante: quando il modello genera una chiamata di strumenti, la sessione audio rimane attiva in modo che l'agente possa eseguire lo streaming di riconoscimenti conversazionali ("Let me pull up your account details...") e gestire l'input di follow-up mentre l'app client chiama le API di backend.
  • Chiamate di blocco con annullamento automatico (behavior="BLOCKING"): quando una dichiarazione di funzione imposta behavior="BLOCKING", la generazione si mette in pausa fino all' arrivo della risposta dello strumento. Se arriva un nuovo input utente durante l'esecuzione della chiamata di blocco, il server API Gemini Live annulla la chiamata in attesa.
  • Gestione dell'interruzione educata: 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 riduce la pianificazione a WHEN_IDLE quando la voce dell'utente è attiva e riproduce la risposta dopo che l'utente ha finito di parlare.

• Cambio lingua multilingue dinamico 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 a Cloud de Confiance by S3NS utilizzando le Credenziali predefinite dell'applicazione (ADC).

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

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 di strumenti asincrona

L'esempio seguente stabilisce una sessione in tempo reale con gemini-3.8-live, configura il bias 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 API richieste

Quando crei con 3.8 Live, segui queste convenzioni API:

• Risposte di funzione informative: 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 dalla macchina, ad esempio "ok", "no_results" o "invalid_argument".
  • retryable: impostalo 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 ripetizione degli strumenti a livello di prompt: includi un limite di ripetizione in system_instruction. Ad esempio: "Se una chiamata di strumenti non restituisce risultati, informa l'utente anziché eseguire ricerche ripetute con variazioni dei parametri. Non eseguire mai più di due chiamate di strumenti consecutive senza parlare con l'utente."
• Corrispondenza rigorosa FunctionResponse:
  • 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.
• Inserimento della cronologia delle conversazioni: se inserisci la cronologia multi-turno 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 ulteriori informazioni sulla migrazione da gemini-live-2.5-flash-native-audio a gemini-3.8-live, consulta Eseguire la migrazione da Gemini 2.5 Flash Live API Native Audio 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:

• Pagina del modello Gemini 3.8 Live
• Configurare gli avatar live
• Best practice con l'API Gemini Live
• Eseguire la migrazione da Gemini 2.5 Flash Live API Native Audio a Gemini 3.8 Live
• Tutorial Python sull'API Gemini Live
• Introduzione al notebook Live Avatar
• Skill del servizio API Gemini Live