Multimodal Live API

L'API Multimodal Live consente interazioni vocali e video bidirezionali con latenza ridotta con Gemini. Con l'API Multimodal Live, puoi offrire agli utenti finali l'esperienza di conversazioni vocali naturali e simili a quelle umane, nonché la possibilità di interrompere le risposte del modello utilizzando i comandi vocali. Il modello può elaborare input di testo, audio e video e fornire output di testo e audio.

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:fornisce risposte rapide.
• Memoria di sessione:il modello conserva la memoria di tutte le interazioni all'interno di una singola sessione, richiamando le informazioni ascoltate o viste in precedenza.
• Supporto per chiamate di funzioni, esecuzione di codice e Ricerca come strumento: consente l'integrazione con servizi e origini dati esterni.
• Rilevamento automatico dell'attività vocale (VAD): il modello è in grado di riconoscere con precisione quando l'utente inizia e interrompe a parlare. Ciò consente interazioni conversazionali naturali e consente agli utenti di interrompere il modello in qualsiasi momento.

Puoi provare l'API Multimodal Live in Google AI Studio.

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:

from google import genai

Inviare e ricevere un SMS

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model_id = "gemini-2.0-flash-exp"
config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model_id, config=config) as session:
        while True:
            message = input("User> ")
            if message.lower() == "exit":
                break
            await session.send(message, end_of_turn=True)

            async for response in session.receive():
                if response.text is None:
                    continue
                print(response.text, end="")

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

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 sopra indicati tramite una connessione WebSocket aperta.

Messaggi client supportati

Consulta i messaggi client supportati nella tabella seguente:

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:

Aggiornamenti incrementali dei contenuti

Utilizza gli aggiornamenti incrementali per inviare input di testo, stabilire o 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.

Riproduzione in streaming di audio e video

Chiamata di funzione

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

Consulta il tutorial sulle chiamate di funzione per scoprire di più 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.

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

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: Aoede, Charon, Fenrir, Kore e Puck.

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": <var>VOICE_NAME</var>
    }
  }
}

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.

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

Cronologia conversazione

Sebbene il modello tenga traccia delle interazioni all'interno della sessione, la cronologia delle conversazioni non viene archiviata. Al termine di una sessione, 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 attiva e i relativi parametri non sono configurabili.

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

Ulteriori informazioni sui tipi comuni

Per saperne di più sui tipi di risorse API di uso comune Blob, Content, FunctionCall, FunctionResponse, GenerationConfig, GroundingMetadata e Tool, consulta Generare contenuti.