Live API - WebSockets API reference

Interfejs Live API jest interfejsem stateful API, który używa WebSockets. W tej sekcji znajdziesz dodatkowe informacje o interfejsie WebSockets API.

Sesje

Połączenie WebSocket nawiązuje sesję 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.
  • odbierać prośby o wykonanie funkcji, wysłane z serwera Gemini.

Połączenie WebSocket

Aby rozpocząć sesję, połącz się z tym punktem końcowym WebSocket:

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent

Konfiguracja sesji

Początkowy komunikat po nawiązaniu połączenia określa konfigurację sesji, która obejmuje model, parametry generowania, instrukcje systemu i narzędzia.

Podczas sesji możesz zmieniać parametry konfiguracji z wyjątkiem modelu.

Poniżej znajdziesz przykładową konfigurację. Pamiętaj, że wielkość liter w nazwach pakietów SDK może się różnić. Opcje konfiguracji pakietu Python SDK możesz sprawdzić tutaj.


{
  "model": string,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object,
    "mediaResolution": object
  },
  "systemInstruction": string,
  "tools": [object]
}

Więcej informacji o polu API znajdziesz w sekcji generationConfig.

Wysyłanie wiadomości

Aby wymieniać wiadomości przez połączenie WebSocket, klient musi wysłać obiekt JSON przez otwarte połączenie WebSocket. Obiekt JSON musi mieć dokładnie jedno z tych pól:


{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}

Obsługiwane wiadomości od klienta

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

Wiadomość Opis
BidiGenerateContentSetup Konfiguracja sesji do wysłania w pierwszej wiadomości
BidiGenerateContentClientContent Przyrostowa aktualizacja treści bieżącej rozmowy przesyłana z klienta
BidiGenerateContentRealtimeInput Wprowadzanie tekstu, dźwięku lub obrazu w czasie rzeczywistym
BidiGenerateContentToolResponse Odpowiedź na ToolCallMessage otrzymaną z serwera

Odbieranie wiadomości

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

Zapoznaj się z tymi informacjami:

async with client.aio.live.connect(model='...', config=config) as session:
    await session.send(input='Hello world!', end_of_turn=True)
    async for message in session.receive():
        print(message)

Wiadomości serwera mogą zawierać pole usageMetadata, ale poza tym dokładnie jedno z innych pól wiadomościBidiGenerateContentServerMessage. (zbior messageType nie jest wyrażony w formacie JSON, więc pole pojawi się na najwyższym poziomie wiadomości).

Wiadomości i wydarzenia

ActivityEnd

Ten typ nie ma pól.

Oznacza koniec aktywności użytkownika.

ActivityHandling

różne sposoby obsługi aktywności użytkowników;

Wartości w polu enum
ACTIVITY_HANDLING_UNSPECIFIED Jeśli nie podasz żadnej opcji, domyślne działanie to START_OF_ACTIVITY_INTERRUPTS.
START_OF_ACTIVITY_INTERRUPTS Jeśli ma wartość prawda, rozpoczęcie aktywności przerywa odpowiedź modelu (tzw. „wtargnięcie”). Obecna odpowiedź modelu zostanie przerwana w momencie przerwania. Jest to zachowanie domyślne.
NO_INTERRUPTION Odpowiedź modelu nie zostanie przerwana.

ActivityStart

Ten typ nie ma pól.

Oznacza początek aktywności użytkownika.

AudioTranscriptionConfig

Ten typ nie ma pól.

Konfiguracja transkrypcji audio.

AutomaticActivityDetection

Konfiguruje automatyczne wykrywanie aktywności.

Pola
disabled

bool

Opcjonalnie. Jeśli jest włączona (domyślnie), wykryta głos i tekst są uznawane za aktywność. Jeśli jest wyłączona, klient musi wysyłać sygnały aktywności.
startOfSpeechSensitivity

StartSensitivity

Opcjonalnie. Określa, jak prawdopodobne jest wykrycie mowy.
prefixPaddingMs

int32

Opcjonalnie. Wymagany czas trwania wykrytej mowy przed podaniem początku mowy. Im niższa jest ta wartość, tym bardziej czułe jest wykrywanie początku mowy i tym krótsze wypowiedzi mogą być rozpoznawane. Zwiększa to jednak prawdopodobieństwo wyników fałszywie pozytywnych.
endOfSpeechSensitivity

EndSensitivity

Opcjonalnie. Określa, jak prawdopodobne jest zakończenie wykrycia mowy.
silenceDurationMs

int32

Opcjonalnie. Wymagany czas trwania wykrycia niemowy (np. ciszy) przed podaniem zakończenia mowy. Im większa jest ta wartość, tym dłuższe mogą być przerwy w mowie bez przerywania aktywności użytkownika, ale spowoduje to wydłużenie opóźnienia modelu.

BidiGenerateContentClientContent

Przyrostowa aktualizacja bieżącej rozmowy wysłana z klienta. Wszystkie te treści są bezwarunkowo dołączane do historii rozmowy i używane jako część promptu do generowania treści.

Komunikat w tym miejscu przerwie bieżące generowanie modelu.

Pola
turns[]

Content

Opcjonalnie. Treść dołączona do bieżącej rozmowy z modelem.

W przypadku zapytań z jednym ruchem jest to pojedyncza instancja. W przypadku zapytań wieloetapowych jest to powtarzalne pole, które zawiera historię rozmowy i ostatnie żądanie.
turnComplete

bool

Opcjonalnie. Jeśli to ustawienie ma wartość true, generowanie treści na serwerze powinno się rozpocząć od aktualnie gromadzonego promptu. W przeciwnym razie serwer czeka na dodatkowe komunikaty przed rozpoczęciem generowania.

BidiGenerateContentRealtimeInput

dane wejściowe użytkownika, które są wysyłane w czasie rzeczywistym;

Różne modalności (dźwięk, obraz i tekst) są obsługiwane jako równoległe strumienie. Kolejność tych strumieni nie jest gwarantowana.

Różni się ona od BidiGenerateContentClientContent w kilku aspektach:

  • mogą być przesyłane bez przerwy w generowaniu modelu;
  • Jeśli trzeba mieszać dane przeplatane w BidiGenerateContentClientContent i BidiGenerateContentRealtimeInput, serwer próbuje zoptymalizować odpowiedź, ale nie ma żadnych gwarancji.
  • Koniec tury nie jest wyraźnie określony, ale wynika z działania użytkownika (np. zakończenia mowy).
  • Dane są przetwarzane stopniowo jeszcze przed zakończeniem tury, aby zoptymalizować szybki start odpowiedzi modelu.
Pola
mediaChunks[]

Blob

Opcjonalnie. Wstawione bajty danych dla wejścia multimedialnego. Nie można podać więcej niż 1 elementu w polu mediaChunks. Wszystkie elementy oprócz pierwszego zostaną zignorowane.

WYCOFANO: użyj jednej z tych wartości: audio, video lub text.
audio

Blob

Opcjonalnie. Tworzą one strumień danych wejściowych audio w czasie rzeczywistym.
video

Blob

Opcjonalnie. Tworzą one strumień danych wideo w czasie rzeczywistym.
activityStart

ActivityStart

Opcjonalnie. Oznacza początek aktywności użytkownika. Dane te mogą być wysyłane tylko wtedy, gdy automatyczne wykrywanie aktywności (czyli po stronie serwera) jest wyłączone.
activityEnd

ActivityEnd

Opcjonalnie. Oznacza koniec aktywności użytkownika. Dane te mogą być wysyłane tylko wtedy, gdy automatyczne wykrywanie aktywności (czyli po stronie serwera) jest wyłączone.
audioStreamEnd

bool

Opcjonalnie. Wskazuje, że strumień audio został zakończony, np. z powodu wyłączenia mikrofonu.

Powinien być wysyłany tylko wtedy, gdy włączone jest automatyczne wykrywanie aktywności (co jest domyślną opcją).

Klient może ponownie otworzyć strumień, wysyłając wiadomość audio.
text

string

Opcjonalnie. Tworzą one strumień danych tekstowych w czasie rzeczywistym.

BidiGenerateContentServerContent

Przyrostowa aktualizacja serwera generowana przez model w odpowiedzi na wiadomości od klienta.

Treści są generowane tak szybko, jak to możliwe, a nie w czasie rzeczywistym. Klienci mogą wybrać buforowanie i odtwarzanie w czasie rzeczywistym.

Pola
generationComplete

bool

Tylko dane wyjściowe. Jeśli ma wartość true (prawda), wskazuje, że model został wygenerowany.

Gdy model zostanie przerwany podczas generowania, w przerwanym etapie nie pojawi się wiadomość „generation_complete”, tylko „interrupted > turn_complete”.

Gdy model zakłada odtwarzanie w czasie rzeczywistym, między zdarzeniami generation_complete i turn_complete wystąpi opóźnienie spowodowane oczekiwaniem modelu na zakończenie odtwarzania.
turnComplete

bool

Tylko dane wyjściowe. Jeśli ma wartość true (prawda), wskazuje, że model ukończył swoją kolejkę. Generowanie rozpocznie się dopiero po otrzymaniu kolejnych wiadomości od klientów.
interrupted

bool

Tylko dane wyjściowe. Jeśli ma wartość true, oznacza, że wiadomość od klienta przerwała bieżące generowanie modelu. Jeśli klient odtwarza treści w czasie rzeczywistym, jest to dobry sygnał, aby zatrzymać i opróżnić bieżącą kolejkę odtwarzania.
groundingMetadata

GroundingMetadata

Tylko dane wyjściowe. metadane odniesienia dla wygenerowanych treści;
outputTranscription

BidiGenerateContentTranscription

Tylko dane wyjściowe. Wyjście transkrypcji audio. Transkrypcja jest wysyłana niezależnie od innych wiadomości serwera i nie ma określonej kolejności, w szczególności między serverContent a tym outputTranscription.
modelTurn

Content

Tylko dane wyjściowe. Treści wygenerowane przez model w ramach bieżącej rozmowy z użytkownikiem.

BidiGenerateContentServerMessage

Odpowiedź na wywołanie BidiGenerateContent.

Pola
usageMetadata

UsageMetadata

Tylko dane wyjściowe. Metadane dotyczące odpowiedzi.
Pole unii messageType. Typ wiadomości. messageType może być tylko jednym z tych elementów:
setupComplete

BidiGenerateContentSetupComplete

Tylko dane wyjściowe. Wysłana w odpowiedzi na wiadomość BidiGenerateContentSetup od klienta po zakończeniu konfiguracji.
serverContent

BidiGenerateContentServerContent

Tylko dane wyjściowe. Treści wygenerowane przez model w odpowiedzi na wiadomości od klientów.
toolCall

BidiGenerateContentToolCall

Tylko dane wyjściowe. Poproś klienta o wykonanie functionCalls i zwrócenie odpowiedzi z odpowiednimi wartościami id.
toolCallCancellation

BidiGenerateContentToolCallCancellation

Tylko dane wyjściowe. Powiadomienie dla klienta, że wcześniej wydany ToolCallMessage z określonymi id powinien zostać anulowany.
goAway

GoAway

Tylko dane wyjściowe. powiadomienie, że serwer wkrótce się rozłączy;
sessionResumptionUpdate

SessionResumptionUpdate

Tylko dane wyjściowe. Aktualizacja stanu wznowienia sesji.

BidiGenerateContentSetup

Wiadomość do wysłania w pierwszym (i tylko w pierwszym) BidiGenerateContentClientMessage. Zawiera konfigurację, która będzie obowiązywać przez cały czas trwania strumieniowego wywołania RPC.

Klienci powinni zaczekać na wiadomość BidiGenerateContentSetupComplete, zanim wyślą kolejne wiadomości.

Pola
model

string

Wymagane. Nazwa zasobu modelu. Jest to identyfikator modelu, którego chcesz użyć.

Format: models/{model}
generationConfig

GenerationConfig

Opcjonalnie. Konfiguracja generowania.

Nieobsługiwane są następujące pola:

  • responseLogprobs
  • responseMimeType
  • logprobs
  • responseSchema
  • stopSequence
  • routingConfig
  • audioTimestamp
systemInstruction

Content

Opcjonalnie. Użytkownik podał instrukcje systemowe dotyczące modelu.

Uwaga: w częściach należy używać tylko tekstu, a treści w każdej części powinny być umieszczone w osobnym akapicie.
tools[]

Tool

Opcjonalnie. Lista Tools, których model może użyć do wygenerowania następnej odpowiedzi.

Tool to fragment kodu, który umożliwia systemowi interakcję z systemami zewnętrznymi w celu wykonania działania lub zestawu działań wykraczających poza wiedzę i zakres modelu.
realtimeInputConfig

RealtimeInputConfig

Opcjonalnie. Konfiguruje obsługę danych wejściowych w czasie rzeczywistym.
sessionResumption

SessionResumptionConfig

Opcjonalnie. Konfiguruje mechanizm wznawiania sesji.

Jeśli jest dołączony, serwer będzie wysyłać wiadomości SessionResumptionUpdate.
contextWindowCompression

ContextWindowCompressionConfig

Opcjonalnie. Konfiguruje mechanizm kompresji okna kontekstowego.

Jeśli jest dołączony, serwer automatycznie zmniejszy rozmiar kontekstu, gdy przekroczy skonfigurowaną długość.
outputAudioTranscription

AudioTranscriptionConfig

Opcjonalnie. Jeśli to ustawienie jest włączone, umożliwia transkrypcję wyjścia audio modelu. Transkrypcja jest dopasowywana do kodu języka określonego dla wyjściowego dźwięku (jeśli jest skonfigurowany).

BidiGenerateContentSetupComplete

Ten typ nie ma pól.

Wysłano w odpowiedzi na wiadomość BidiGenerateContentSetup od klienta.

BidiGenerateContentToolCall

Poproś klienta o wykonanie functionCalls i zwrócenie odpowiedzi z odpowiednimi wartościami id.

Pola
functionCalls[]

FunctionCall

Tylko dane wyjściowe. Wywołanie funkcji do wykonania.

BidiGenerateContentToolCallCancellation

Powiadomienie dla klienta, że wcześniej wydany ToolCallMessage z określonymi id nie powinien zostać wykonany i powinien zostać anulowany. Jeśli wywołania tych narzędzi miały jakieś skutki uboczne, klienci mogą spróbować cofnąć te wywołania. Ta wiadomość pojawia się tylko wtedy, gdy klienci przerywają kolejność serwera.

Pola
ids[]

string

Tylko dane wyjściowe. Identyfikatory wywołań narzędzia, które mają zostać anulowane.

BidiGenerateContentToolResponse

Odpowiedź wygenerowana przez klienta na ToolCall otrzymaną z serwera. Poszczególne obiekty FunctionResponse są dopasowywane do odpowiednich obiektów FunctionCall za pomocą pola id.

Pamiętaj, że w przypadku wywołania funkcji interfejsów unary i GenerateContent po stronie serwera następuje wymiana części Content, a w przypadku wywołania funkcji interfejsów bidi GenerateContent następuje wymiana dedykowanego zestawu wiadomości.

Pola
functionResponses[]

FunctionResponse

Opcjonalnie. Odpowiedź na wywołania funkcji.

BidiGenerateContentTranscription

Transkrypcja dźwięku (dane wejściowe lub wyjściowe).

Pola
text

string

tekst transkrypcji;

ContextWindowCompressionConfig

Umożliwia kompresję okna kontekstowego – mechanizm zarządzania oknem kontekstowym modelu, który nie przekracza określonej długości.

Pola
Pole unii compressionMechanism. Używany mechanizm kompresji okna kontekstowego. compressionMechanism może być tylko jednym z tych elementów:
slidingWindow

SlidingWindow

mechanizm przesuwającego się okna.
triggerTokens

int64

Liczba tokenów (przed wykonaniem tury), która powoduje kompresję okna kontekstowego.

Możesz go użyć, aby zachować równowagę między jakością a opóźnieniem, ponieważ krótsze okna kontekstu mogą przyspieszyć działanie modelu. Jednak każda operacja kompresji powoduje tymczasowe zwiększenie opóźnienia, dlatego nie należy ich często uruchamiać.

Jeśli nie zostanie ustawiony, domyślnie zostanie użyte 80% limitu okna kontekstowego modelu. Pozostałe 20% to czas potrzebny na przetworzenie kolejnego żądania użytkownika i odpowiedzi modelu.

EndSensitivity

Określa sposób wykrywania końca mowy.

Wartości w polu enum
END_SENSITIVITY_UNSPECIFIED Wartość domyślna to END_SENSITIVITY_HIGH.
END_SENSITIVITY_HIGH Automatyczne wykrywanie kończy rozpoznawanie mowy częściej.
END_SENSITIVITY_LOW Automatyczne wykrywanie kończy rozpoznawanie mowy rzadziej.

GoAway

powiadomienie, że serwer wkrótce się rozłączy;

Pola
timeLeft

Duration

Pozostały czas do zakończenia połączenia jako ABORTED (anulowane).

Czas trwania nigdy nie będzie krótszy niż minimalny czas określony w modelu, który zostanie podany wraz z ograniczeniami stawek dla tego modelu.

RealtimeInputConfig

Konfiguruje zachowanie wprowadzania danych w czasie rzeczywistym w aplikacji BidiGenerateContent.

Pola
automaticActivityDetection

AutomaticActivityDetection

Opcjonalnie. Jeśli nie zostanie ustawiony, automatyczne wykrywanie aktywności jest domyślnie włączone. Jeśli automatyczne wykrywanie głosu jest wyłączone, klient musi wysyłać sygnały aktywności.
activityHandling

ActivityHandling

Opcjonalnie. Określa efekt działania.
turnCoverage

TurnCoverage

Opcjonalnie. Określa, które dane wejściowe są uwzględniane w ruchu użytkownika.

SessionResumptionConfig

Konfiguracja wznawiania sesji.

Ten komunikat jest uwzględniony w konfiguracji sesji jako BidiGenerateContentSetup.sessionResumption. Jeśli jest skonfigurowany, serwer będzie wysyłać wiadomości SessionResumptionUpdate.

Pola
handle

string

Identyfikator poprzedniej sesji. Jeśli nie ma sesji, zostanie utworzona nowa.

Identyfikatory sesji pochodzą z wartości SessionResumptionUpdate.token w poprzednich połączeniach.

SessionResumptionUpdate

Aktualizacja stanu wznowienia sesji.

Wysłano tylko wtedy, gdy ustawiono wartość BidiGenerateContentSetup.sessionResumption.

Pola
newHandle

string

Nowy nick, który reprezentuje stan, który można wznowić. Pusty, jeśli resumable=fałsz.
resumable

bool

Wartość „PRAWDA”, jeśli bieżącą sesję można wznowić w danym momencie.

W niektórych momentach sesji wznowienie nie jest możliwe. Na przykład, gdy model wykonuje wywołania funkcji lub generuje dane. W takim stanie wznowienie sesji (za pomocą tokena z poprzedniej sesji) spowoduje utratę części danych. W takich przypadkach wartość newHandle będzie pusta, a wartość resumable będzie fałszywa.

SlidingWindow

Metoda SlidingWindow odrzuca dane na początku okna kontekstu. Wynikowy kontekst zawsze rozpocznie się na początku tury roli UŻYTKOWNIK. Instrukcje systemu i wszystkie BidiGenerateContentSetup.prefixTurns będą zawsze widoczne na początku wyniku.

Pola
targetTokens

int64

Docelowa liczba tokenów do zachowania. Wartość domyślna to trigger_tokens/2.

Odrzucenie części okna kontekstowego powoduje tymczasowy wzrost opóźnienia, dlatego należy skalibrować tę wartość, aby uniknąć częstych operacji kompresji.

StartSensitivity

Określa sposób wykrywania początku mowy.

Wartości w polu enum
START_SENSITIVITY_UNSPECIFIED Wartość domyślna to START_SENSITIVITY_HIGH.
START_SENSITIVITY_HIGH Automatyczne wykrywanie będzie częściej wykrywać początek mowy.
START_SENSITIVITY_LOW Automatyczne wykrywanie będzie rzadziej wykrywać początek mowy.

TurnCoverage

Opcje dotyczące tego, które dane wejściowe są uwzględniane w ruchu użytkownika.

Wartości w polu enum
TURN_COVERAGE_UNSPECIFIED Jeśli nie podasz żadnej opcji, domyślne działanie to TURN_INCLUDES_ONLY_ACTIVITY.
TURN_INCLUDES_ONLY_ACTIVITY Aktywność użytkownika obejmuje tylko działania od ostatniej kolejki, z wyłączeniem okresów bezczynności (np. ciszy w strumieniu audio). Jest to zachowanie domyślne.
TURN_INCLUDES_ALL_INPUT Przebieg użytkownika obejmuje wszystkie dane wejściowe w czasie rzeczywistym od ostatniego przebiegu, w tym okresy bezczynności (np. cisza w strumieniu audio).

UsageMetadata

Metadane dotyczące użytkowania odpowiedzi.

Pola
promptTokenCount

int32

Tylko dane wyjściowe. Liczba tokenów w prompcie. Gdy ustawisz wartość cachedContent, nadal będzie to łączny docelowy rozmiar promptu, co oznacza, że uwzględnia on liczbę tokenów w treściach w pamięci podręcznej.
cachedContentTokenCount

int32

Liczba tokenów w części prompta, która jest przechowywana w pamięci podręcznej (treści w pamięci podręcznej)
responseTokenCount

int32

Tylko dane wyjściowe. Łączna liczba tokenów we wszystkich wygenerowanych odpowiedziach.
toolUsePromptTokenCount

int32

Tylko dane wyjściowe. Liczba tokenów obecnych w prośbach dotyczących korzystania z narzędzia.
thoughtsTokenCount

int32

Tylko dane wyjściowe. Liczba tokenów myśli dla modeli myślących.
totalTokenCount

int32

Tylko dane wyjściowe. Łączna liczba tokenów w żądaniu generowania (prompt + kandydaci do odpowiedzi).
promptTokensDetails[]

ModalityTokenCount

Tylko dane wyjściowe. Lista modalności przetworzonych w danych wejściowych
cacheTokensDetails[]

ModalityTokenCount

Tylko dane wyjściowe. Lista modalności treści z pamięci podręcznej w danych wejściowych zapytania.
responseTokensDetails[]

ModalityTokenCount

Tylko dane wyjściowe. Lista modalności zwróconych w odpowiedzi.
toolUsePromptTokensDetails[]

ModalityTokenCount

Tylko dane wyjściowe. Lista modalności przetworzonych na potrzeby danych wejściowych zapytania o użycie narzędzia.

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, ModalityTokenCount i Tool znajdziesz w artykule Generowanie treści.