Multimodal Live API

Interfejs API multimodalny na żywo umożliwia dwukierunkowe interakcje głosowe i wideo z Gemini o niskim opóźnieniu. Dzięki interfejsowi API Multimodal Live możesz zapewnić użytkownikom naturalne, przypominające ludzkie rozmowy głosowe oraz możliwość przerywania odpowiedzi modelu za pomocą poleceń głosowych. Model może przetwarzać dane wejściowe w postaci tekstu, dźwięku i obrazu oraz generować dane wyjściowe w postaci tekstu i dźwięku.

Możliwości

Interfejs API Multimodal Live obejmuje te najważniejsze funkcje:

• Multimodalność: model może widzieć, słyszeć i mówić.
• Interakcja w czasie rzeczywistym z minimalnym opóźnieniem: zapewnia szybkie odpowiedzi.
• Pamięć sesji: model zachowuje pamięć o wszystkich interakcjach w ramach pojedynczej sesji, przywołując wcześniej usłyszane lub wyświetlone informacje.
• Obsługa wywoływania funkcji, wykonywania kodu i wyszukiwania jako narzędzia: umożliwia integrację z zewnętrznymi usługami i źródłami danych.
• Automatyczne wykrywanie aktywności głosowej (VAD): model może dokładnie rozpoznać, kiedy użytkownik zaczyna i przestaje mówić. Umożliwia to naturalne konwersacyjne interakcje i umożliwia użytkownikom przerwanie działania modelu w dowolnym momencie.

Interfejs API Multimodal Live możesz wypróbować w Google AI Studio.

Rozpocznij

Interfejs API Multimodal Live to interfejs stateful API, który korzysta z WebSockets.

W tej sekcji znajdziesz przykład użycia interfejsu Multimodal Live API do generowania tekstu na podstawie tekstu za pomocą Pythona w wersji 3.9 lub nowszej.

Instalowanie biblioteki Gemini API

Aby zainstalować pakiet google-genai, użyj tego polecenia pip:

!pip3 install google-genai

Importowanie zależności

Aby zaimportować zależności:

from google import genai

Wysyłanie i odbieranie SMS-ów

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())

Przewodnik integracji

W tej sekcji opisano, jak działa integracja z interfejsem Multimodal Live API.

Sesje

Sesja reprezentuje pojedyncze połączenie WebSocket między klientem a serwerem Gemini.

Gdy klient inicjuje nowe połączenie, sesja może wymieniać się wiadomościami z serwerem, aby:

• Wysyłanie tekstu, dźwięku lub filmu na serwer Gemini.
• otrzymywać odpowiedzi w formie dźwięku, tekstu lub wywołania funkcji z serwera Gemini;

Konfiguracja sesji jest wysyłana w pierwszej wiadomości po nawiązaniu połączenia. Konfiguracja sesji obejmuje model, parametry generowania, instrukcje dotyczące systemu i narzędzia.

Poniżej znajdziesz przykładową konfigurację:

{​​
  "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":[]
}

Więcej informacji znajdziesz w artykule BidiGenerateContentSetup.

Wysyłanie wiadomości

Wiadomości to ciągi znaków w formacie JSON wymieniane przez połączenie WebSocket.

Aby wysłać wiadomość, klient musi wysłać obsługiwaną wiadomość klienta w postaci ciągu w formacie JSON za pomocą jednego z otwartych połączeń WebSocket.

Obsługiwane wiadomości od klienta

W tabeli poniżej znajdziesz obsługiwane wiadomości od klienta:

Odbieranie wiadomości

Aby otrzymywać wiadomości od Gemini, nasłuchuj zdarzenia WebSocket o nazwie „message”, a potem przeanalizuj wynik zgodnie z definicją obsługiwanych wiadomości serwera.

Zapoznaj się z tymi informacjami:

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

Obsługiwane komunikaty serwera

Obsługiwane komunikaty serwera znajdziesz w tabeli poniżej:

Przyrostowe aktualizacje treści

Używaj przyrostowych aktualizacji do wysyłania danych wejściowych tekstowych, ustanawiania kontekstu sesji lub przywracania kontekstu sesji. W przypadku krótkich kontekstów możesz wysyłać interakcje krok po kroku, aby reprezentować dokładną sekwencję zdarzeń. W przypadku dłuższych kontekstów zalecamy podanie podsumowania w jednej wiadomości, aby zwolnić okno kontekstu na potrzeby dalszych interakcji.

Oto przykładowy komunikat kontekstowy:

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

Pamiętaj, że chociaż elementy treści mogą mieć typ functionResponse, nie należy używać wartości BidiGenerateContentClientContent do przekazywania odpowiedzi na wywołania funkcji wydawane przez model. Należy zamiast tego używać elementu BidiGenerateContentToolResponse. BidiGenerateContentClientContent należy używać tylko do określenia poprzedniego kontekstu lub do wprowadzenia tekstu do konwersacji.

Strumieniowe przesyłanie dźwięku i wideo

Wywoływanie funkcji

Wszystkie funkcje muszą zostać zadeklarowane na początku sesji przez wysłanie definicji narzędzia w ramach komunikatu BidiGenerateContentSetup.

Aby dowiedzieć się więcej o wywoływaniu funkcji, zapoznaj się z samouczkiem dotyczącym wywoływania funkcji.

Na podstawie jednego prompta model może wygenerować wiele wywołań funkcji i kodu niezbędnego do połączenia ich danych wyjściowych. Ten kod jest wykonywany w środowisku piaskownicy, generując kolejne wiadomości BidiGenerateContentToolCall. Wykonanie zostaje wstrzymane do czasu, aż będą dostępne wyniki każdego wywołania funkcji, co zapewnia sekwencyjne przetwarzanie.

Klient powinien odpowiedzieć BidiGenerateContentToolResponse.

Wejścia i wyjścia audio negatywnie wpływają na zdolność modelu do korzystania z funkcji wywoływania.

Formaty audio

Interfejs API Multimodal Live obsługuje te formaty audio:

• Format audio wejściowego: surowy 16-bitowy PCM z częstotliwością 16 kHz w formacie little-endian
• Format wyjściowy dźwięku: surowy 16-bitowy dźwięk PCM w formacie little-endian z częstotliwością 24 kHz

Instrukcje systemowe

Możesz podać instrukcje systemowe, aby lepiej kontrolować wyniki modelu oraz określić ton i wyrazy emocjonalne odpowiedzi audio.

Instrukcje systemowe są dodawane do promptu przed rozpoczęciem interakcji i pozostają w mocy przez całą sesję.

Instrukcje systemowe można ustawić tylko na początku sesji, bezpośrednio po nawiązaniu połączenia. Aby przekazać modelowi dodatkowe dane podczas sesji, użyj przyrostowych aktualizacji treści.

Dozwolone dźwięki

Użytkownicy mogą w dowolnym momencie przerwać działanie modelu. Gdy wykrywanie aktywności głosowej wykryje przerwę, bieżące generowanie zostanie anulowane i odrzucone. W historii sesji są przechowywane tylko informacje już wysłane do klienta. Następnie serwer wysyła wiadomość BidiGenerateContentServerContent, aby zgłosić przerwanie połączenia.

Dodatkowo serwer Gemini odrzuca wszystkie oczekujące wywołania funkcji i wysyła wiadomość BidiGenerateContentServerContent z identyfikatorami anulowanych połączeń.

Głosy

Interfejs API Multimodal Live obsługuje te głosy: Aoede, Charon, Fenrir, Kore i Puck.

Aby określić głos, ustaw voice_name w obiekcie speech_config w ramach konfiguracji sesji.

Oto przykład obiektu speech_config w formie zapisu JSON:

{
  "voice_config": {
    "prebuilt_voice_config ": {
      "voice_name": <var>VOICE_NAME</var>
    }
  }
}

Ograniczenia

Podczas planowania projektu weź pod uwagę te ograniczenia interfejsu API Multimodal Live i Gemini 2.0.

Uwierzytelnianie klienta

Interfejs API Live multimodalny zapewnia uwierzytelnianie serwera na serwer i nie jest zalecany do bezpośredniego użycia przez klienta. Dane wejściowe klienta powinny być kierowane przez pośredni serwer aplikacji, aby umożliwić bezpieczne uwierzytelnianie za pomocą interfejsu Multimodal Live API.

W przypadku aplikacji internetowych i mobilnych zalecamy korzystanie z integracji oferowanej przez naszych partnerów w ramach Daily.

Historia rozmowy

Model śledzi interakcje w ramach sesji, ale nie zapisuje historii rozmów. Po zakończeniu sesji odpowiedni kontekst jest usuwany.

Aby przywrócić poprzednią sesję lub przekazać modelowi historyczny kontekst interakcji z użytkownikiem, aplikacja powinna prowadzić własny dziennik rozmów i używać wiadomości BidiGenerateContentClientContent, aby wysyłać te informacje na początku nowej sesji.

Maksymalny czas trwania sesji

Czas trwania sesji jest ograniczony do 15 minut w przypadku dźwięku lub do 2 minut w przypadku dźwięku i obrazu. Gdy czas trwania sesji przekroczy limit, połączenie zostanie zakończone.

Model jest też ograniczony rozmiarem kontekstu. Wysyłanie dużych fragmentów treści wraz ze strumieniami wideo i dźwięku może spowodować wcześniejsze zakończenie sesji.

wykrywanie aktywności głosowej (VAD);

Model automatycznie wykrywa aktywność głosową (VAD) w ciągłym strumieniu wejściowym dźwięku. Funkcja VAD jest zawsze włączona, a jej parametry nie są konfigurowalne.

Liczba tokenów

Liczba tokenów nie jest obsługiwana.

Ograniczenia liczby żądań

Obowiązują te limity szybkości:

• 3 jednoczesne sesje na klucz interfejsu API
• 4 mln tokenów na minutę

Wiadomości i zdarzenia

Więcej informacji o najczęstszych typach

Więcej informacji o najczęściej używanych typach zasobów API Blob, Content, FunctionCall, FunctionResponse, GenerationConfig, GroundingMetadata i Tool znajdziesz w artykule Generowanie treści.