API Multimodal Live

L'API Multimodal Live consente interazioni bidirezionali a bassa latenza che utilizzano input di testo, audio e video, con output di audio e testo. In questo modo, è possibile conversare in modo naturale, con la possibilità di interrompere il modello in qualsiasi momento. La capacità di comprensione dei video del modello consente di espandere le modalità di comunicazione, in modo da condividere input della fotocamera o screencast e porre domande in merito.

Funzionalità

L'API Multimodal Live include le seguenti funzionalità principali:

  • Multimodalità: il modello può vedere, sentire e parlare.
  • Interazione in tempo reale a bassa latenza: il modello può fornire risposte rapide.
  • Memoria di sessione: il modello memorizza tutte le interazioni all'interno di un'unica sessione, richiamando le informazioni ascoltate o viste in precedenza.
  • Supporto per la chiamata di funzioni, l'esecuzione di codice e la Ricerca come strumento: puoi integrare il modello con servizi e origini dati esterni.

L'API Multimodal Live è progettata per la comunicazione server-to-server.

Per le app web e mobile, ti consigliamo di utilizzare l'integrazione dei nostri partner su Daily.

Inizia

L'API Multimodal Live è un'API con stato che utilizza WebSockets.

Questa sezione mostra un esempio di come utilizzare l'API Multimodal Live per la generazione di testo in testo utilizzando Python 3.9 e versioni successive.

Installa la libreria dell'API Gemini

Per installare il package google-genai, utilizza il seguente comando pip:

!pip3 install google-genai

Importa le dipendenze

Per importare le dipendenze:

import asyncio
import base64
import contextlib
import datetime
import os
import json
import wave
import itertools

from IPython.display import display, Audio
from google import genai

Imposta il nome del modello e la chiave API

MODEL = "models/gemini-2.0-flash-exp"
os.environ['GOOGLE_API_KEY'] = 'YOUR_API_KEY'

Inviare e ricevere SMS

client = genai.Client(
  http_options={
    'api_version': 'v1alpha',
    'url': 'generativelanguage.googleapis.com',
  }
)

config={
  "generation_config": {"response_modalities": ["TEXT"]}
}

async with client.aio.live.connect(model=MODEL, config=config) as session:
  message = "Hello? Gemini are you there?"
  print("> ", message, "\n")
  await session.send(message, end_of_turn=True)

  # For text responses, When the model's turn is complete it breaks out of the loop.
  async for response in session:
    model_turn = response.server_content.model_turn
    for part in model_turn.parts:
      print("- ", part.text)

Guida all'integrazione

Questa sezione descrive il funzionamento dell'integrazione con l'API Multimodal Live.

Sessioni

Una sessione rappresenta una singola connessione WebSocket tra il client e il server Gemini.

Dopo che un client ha avviato una nuova connessione, la sessione può scambiare messaggi con il server per:

  • Invia testo, audio o video al server Gemini.
  • Ricevere risposte audio, di testo o di chiamata di funzione dal server Gemini.

La configurazione della sessione viene inviata nel primo messaggio dopo la connessione. Una configurazione della sessione include il modello, i parametri di generazione, le istruzioni di sistema e gli strumenti.

Vedi la seguente configurazione di esempio:

{​​
  "model": string,
  "generation_config": {​​
    "candidate_count": integer,
    "max_output_tokens": integer,
    "temperature": number,
    "top_p": number,
    "top_k": integer,
    "presence_penalty": number,
    "frequency_penalty": number,
    "response_modalities": string,
    "speech_config":object
  },

  "system_instruction": "",
  "tools":[]
}

Per ulteriori informazioni, consulta BidiGenerateContentSetup.

Inviare messaggi

I messaggi sono stringhe in formato JSON scambiate tramite la connessione WebSocket.

Per inviare un messaggio, il client deve inviare un messaggio client supportato in una stringa formattata in JSON con uno dei metodi su una connessione WebSocket aperta.

Messaggi client supportati

Consulta i messaggi client supportati nella tabella seguente:

Messaggio Descrizione
BidiGenerateContentSetup Configurazione della sessione da inviare nel primo messaggio
BidiGenerateContentClientContent Aggiornamento incrementale dei contenuti della conversazione corrente inviati dal client
BidiGenerateContentRealtimeInput Input audio o video in tempo reale
BidiGenerateContentToolResponse Risposta a un ToolCallMessage ricevuto dal server

Ricevere messaggi

Per ricevere messaggi da Gemini, ascolta l'evento "message" di WebSocket, quindi analizza il risultato in base alla definizione dei messaggi del server supportati.

Consulta quanto segue:

ws.addEventListener("message", async (evt) => {
  if (evt.data instanceof Blob) {
    // Process the received data (audio, video, etc.)
  } else {
    // Process JSON response
  }
});

Messaggi del server supportati

Consulta i messaggi del server supportati nella tabella seguente:

Messaggio Descrizione
BidiGenerateContentSetupComplete Un messaggio BidiGenerateContentSetup inviato dal cliente al termine della configurazione
BidiGenerateContentServerContent Contenuti generati dal modello in risposta a un messaggio del cliente
BidiGenerateContentToolCall Richiedi al client di eseguire le chiamate di funzione e restituire le risposte con gli ID corrispondenti
BidiGenerateContentToolCallCancellation Inviato quando una chiamata di funzione viene annullata perché l'utente ha interrotto l'output del modello

Aggiornamenti incrementali dei contenuti

Utilizza gli aggiornamenti incrementali per inviare input di testo o stabilire/ripristinare il contesto della sessione. Per contesti brevi, puoi inviare interazioni passo passo per rappresentare la sequenza esatta di eventi. Per contesti più lunghi, è consigliabile fornire un riepilogo di un singolo messaggio per liberare la finestra del contesto per le interazioni successive.

Vedi il seguente esempio di messaggio contestuale:

{
  "client_content": {
    "turns": [
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turn_complete": true
  }
}

Tieni presente che, anche se le parti di contenuto possono essere di tipo functionResponse, BidiGenerateContentClientContent non deve essere utilizzato per fornire una risposta alle chiamate di funzione emesse dal modello. Dovresti utilizzare BidiGenerateContentToolResponse. BidiGenerateContentClientContent deve essere utilizzato solo per stabilire il contesto precedente o fornire input di testo alla conversazione.

Chiamata di funzione

Tutte le funzioni devono essere dichiarate all'inizio della sessione inviando le definizioni degli strumenti come parte del messaggio BidiGenerateContentSetup.

Le funzioni vengono definite utilizzando JSON, in particolare con un sottoinsieme selezionato del formato dello schema OpenAPI. Una singola dichiarazione di funzione può includere i seguenti parametri:

  • name (stringa): l'identificatore univoco della funzione all'interno della chiamata API.
  • description (stringa): una spiegazione completa dello scopo e delle funzionalità della funzione.
  • parameters (oggetto): definisce i dati di input richiesti dalla funzione.
    • type (stringa): specifica il tipo di dati complessivo, ad esempio oggetto.
    • properties (oggetto): elenca i singoli parametri, ciascuno con:
    • type (stringa): il tipo di dati del parametro, ad esempio stringa, intero, booleano.
    • description (stringa): una spiegazione chiara dello scopo e del formato previsto del parametro.
    • required (array): un array di stringhe che elenca i nomi dei parametri obbligatori per il funzionamento della funzione.

Per esempi di codice di una dichiarazione di funzione che utilizza i comandi cURL, consulta Introduzione alle chiamate di funzione con l'API Gemini. Per esempi su come creare dichiarazioni di funzioni utilizzando gli SDK dell'API Gemini, consulta il tutorial sulle chiamate di funzione.

Da un singolo prompt, il modello può generare più chiamate di funzione e il codice necessario per collegarne gli output. Questo codice viene eseguito in un ambiente sandbox, generando messaggi BidiGenerateContentToolCall successivi. L'esecuzione viene messa in pausa fino a quando non sono disponibili i risultati di ogni chiamata di funzione, il che garantisce l'elaborazione sequenziale.

Il cliente deve rispondere con BidiGenerateContentToolResponse.

Formati audio

L'API Multimodal Live supporta i seguenti formati audio:

  • Formato audio di input: audio PCM non compresso a 16 bit a 16 kHz little-endian
  • Formato audio di output: audio PCM non compresso a 16 bit a 24 kHz little-endian

Istruzioni di sistema

Puoi fornire istruzioni di sistema per controllare meglio l'output del modello e specificare il tono e il sentiment delle risposte audio.

Le istruzioni di sistema vengono aggiunte al prompt prima dell'inizio dell'interazione e rimangono in vigore per l'intera sessione.

Le istruzioni di sistema possono essere impostate solo all'inizio di una sessione, subito dopo la connessione iniziale. Per fornire ulteriori input al modello durante la sessione, utilizza gli aggiornamenti incrementali dei contenuti.

Interruzioni

Gli utenti possono interrompere l'output del modello in qualsiasi momento. Quando il Rilevamento attività vocale (VAD) rileva un'interruzione, la generazione in corso viene annullata e ignorata. Nella cronologia della sessione vengono conservate solo le informazioni già inviate al cliente. Il server invia quindi un messaggio BidiGenerateContentServerContent per segnalare l'interruzione.

Inoltre, il server Gemini ignora le chiamate di funzione in attesa e invia un messaggio BidiGenerateContentServerContent con gli ID delle chiamate annullate.

Voci

L'API Multimodal Live supporta le seguenti voci:

  • Puck
  • Caronte
  • Kore
  • Fenrir
  • Aoede

Per specificare una voce, imposta voice_name all'interno dell'oggetto speech_config, come parte della configurazione della sessione.

Consulta la seguente rappresentazione JSON di un oggetto speech_config:

{
  "voice_config": {
    "prebuilt_voice_config ": {
      "voice_name": VOICE_NAME
    }
  }
}

Limitazioni

Quando pianifichi il tuo progetto, tieni presente i seguenti limiti dell'API Multimodal Live e di Gemini 2.0.

Autenticazione client

L'API Multimodal Live fornisce solo l'autenticazione server-to-server e non è consigliata per l'utilizzo diretto del client. L'input del client deve essere instradato tramite un server di applicazioni intermedio per l'autenticazione sicura con l'API Multimodal Live.

Cronologia conversazione

Sebbene il modello tenga traccia delle interazioni all'interno della sessione, la cronologia esplicita della sessione accessibile tramite l'API non è ancora disponibile. Quando una sessione viene terminata, il contesto corrispondente viene cancellato.

Per ripristinare una sessione precedente o fornire al modello il contesto storico delle interazioni utente, l'applicazione deve gestire il proprio log delle conversazioni e utilizzare un messaggio BidiGenerateContentClientContent per inviare queste informazioni all'inizio di una nuova sessione.

Durata massima della sessione

La durata della sessione è limitata a 15 minuti per l'audio o a 2 minuti per audio e video. Quando la durata della sessione supera il limite, la connessione viene interrotta.

Il modello è limitato anche dalle dimensioni del contesto. L'invio di grandi blocchi di contenuti insieme agli stream video e audio potrebbe comportare l'interruzione anticipata della sessione.

Rilevamento attività vocale (VAD)

Il modello esegue automaticamente il rilevamento dell'attività vocale (VAD) su un stream di input audio continuo. La funzionalità VAD è sempre attivata e i relativi parametri non sono attualmente configurabili.

Limitazioni aggiuntive

L'endpointing manuale non è supportato.

Gli input e gli output audio influiscono negativamente sulla capacità del modello di utilizzare le chiamate di funzione.

Conteggio token

Il conteggio dei token non è supportato.

Limiti di frequenza

Si applicano i seguenti limiti di frequenza:

  • 3 sessioni simultanee per chiave API
  • 4 milioni di token al minuto

Messaggi ed eventi

BidiGenerateContentClientContent

Aggiornamento incrementale della conversazione corrente inviata dal client. Tutti i contenuti qui presenti vengono aggiunti incondizionatamente alla cronologia delle conversazioni e utilizzati come parte del prompt per il modello per generare contenuti.

Un messaggio qui interromperà qualsiasi generazione di modelli in corso.

Campi
turns[]

Content

Facoltativo. I contenuti aggiunti alla conversazione corrente con il modello.

Per le query con un solo tratto, si tratta di una singola istanza. Per le query con più turni, si tratta di un campo ripetuto che contiene la cronologia della conversazione e l'ultima richiesta.
turn_complete

bool

Facoltativo. Se true, indica che la generazione dei contenuti del server deve iniziare con il prompt attualmente accumulato. In caso contrario, il server attende altri messaggi prima di iniziare la generazione.

BidiGenerateContentRealtimeInput

Input utente inviati in tempo reale.

È diverso da BidiGenerateContentClientContent in alcuni modi:

  • Possono essere inviati continuamente senza interruzioni per la generazione del modello.
  • Se è necessario combinare i dati interlacciati in BidiGenerateContentClientContent e BidiGenerateContentRealtimeInput, il server tenta di ottimizzare per la risposta migliore, ma non ci sono garanzie.
  • La fine del turno non è specificata esplicitamente, ma deriva dall'attività dell'utente (ad esempio, la fine del discorso).
  • Anche prima della fine del turno, i dati vengono elaborati in modo incrementale per ottimizzare l'avvio rapido della risposta del modello.
  • È sempre input utente diretto dell'utente inviato in tempo reale. Possono essere inviati continuamente senza interruzioni. Il modello rileva automaticamente l'inizio e la fine del parlato dell'utente e avvia o termina lo streaming della risposta di conseguenza. I dati vengono elaborati in modo incrementale man mano che arrivano, riducendo al minimo la latenza.
Campi
media_chunks[]

Blob

Facoltativo. Dati in linea in byte per l'input multimediale.

BidiGenerateContentServerContent

Aggiornamento incrementale del server generato dal modello in risposta ai messaggi del client.

I contenuti vengono generati il più rapidamente possibile e non in tempo reale. I client possono scegliere di mettere in buffer e riprodurre i contenuti in tempo reale.

Campi
turn_complete

bool

Solo output. Se true, indica che la generazione del modello è stata completata. La generazione inizierà solo in risposta a ulteriori messaggi del client. Può essere impostato insieme a content, a indicare che content è l'ultimo della svolta.
interrupted

bool

Solo output. Se true, indica che un messaggio del client ha interrotto la generazione del modello corrente. Se il client riproduce i contenuti in tempo reale, è un buon segnale per interrompere e svuotare la coda di riproduzione corrente.
model_turn

Content

Solo output. I contenuti generati dal modello nell'ambito della conversazione in corso con l'utente.

BidiGenerateContentSetup

Messaggio da inviare nel primo e unico messaggio del cliente. Contiene la configurazione che verrà applicata per tutta la durata della sessione.

I client devono attendere un messaggio BidiGenerateContentSetupComplete prima di inviare altri messaggi.

Campi
model

string

Obbligatorio. Il nome della risorsa del modello. che funge da ID per il modello.

Formato: models/{model}
generation_config

GenerationConfig

Facoltativo. Configurazione della generazione.

I seguenti campi non sono supportati:

  • response_logprobs
  • response_mime_type
  • logprobs
  • response_schema
  • stop_sequence
  • routing_config
  • audio_timestamp
system_instruction

Content

Facoltativo. L'utente ha fornito le istruzioni di sistema per il modello.

Nota: nelle parti deve essere utilizzato solo testo e i contenuti di ogni parte saranno in un paragrafo separato.
tools[]

Tool

Facoltativo. Un elenco di Tools che il modello potrebbe utilizzare per generare la risposta successiva.

Un Tool è un frammento di codice che consente al sistema di interagire con sistemi esterni per eseguire un'azione o un insieme di azioni al di fuori della conoscenza e dell'ambito del modello.

BidiGenerateContentSetupComplete

Questo tipo non contiene campi.

Inviato in risposta a un messaggio BidiGenerateContentSetup del cliente.

BidiGenerateContentToolCall

Chiedi al client di eseguire il function_calls e di restituire le risposte con i id corrispondenti.

Campi
function_calls[]

FunctionCall

Solo output. La chiamata funzione da eseguire.

BidiGenerateContentToolCallCancellation

Notifica al cliente che un ToolCallMessage emesso in precedenza con i id specificati non deve essere stato eseguito e deve essere annullato. Se le chiamate allo strumento hanno avuto effetti collaterali, i client potrebbero tentare di annullarle. Questo messaggio si verifica solo nei casi in cui i client interrompono i turni del server.

Campi
ids[]

string

Solo output. Gli ID delle chiamate allo strumento da annullare.

BidiGenerateContentToolResponse

Risposta generata dal client a un ToolCall ricevuto dal server. I singoli oggetti FunctionResponse vengono associati ai rispettivi oggetti FunctionCall in base al campo id.

Tieni presente che nelle API GenerateContent con streaming server e univoche la chiamata di funzione avviene scambiando le parti Content, mentre nelle API GenerateContent bidirezionali la chiamata di funzione avviene tramite questo insieme di messaggi dedicato.

Campi
function_responses[]

FunctionResponse

Facoltativo. La risposta alle chiamate di funzione.

Vedi anche