Interfejs Live API umożliwia dwukierunkowe interakcje z użyciem głosu i wideo z niewielkimi opóźnieniami dzięki Gemini. Za pomocą interfejsu Live API możesz zapewnić użytkownikom naturalne konwersacje z głosem brzmiącym jak ludzki oraz możliwość przerywania odpowiedzi modelu za pomocą poleceń głosowych. Model może przetwarzać tekst, dźwięk i wideo, a także generować tekst i dźwięk.
Interfejs Live API możesz wypróbować w Google AI Studio.
Nowości
Aby poznać najnowsze funkcje i możliwości interfejsu Live API, sprawdź Changelog.
Korzystanie z interfejsu Live API
W tej sekcji opisaliśmy, jak korzystać z interfejsu Live API z jednym z naszych pakietów SDK. Więcej informacji o interfejsie WebSockets API znajdziesz w dokumentacji referencyjnej interfejsu WebSockets API.
Aby korzystać ze wszystkich funkcji, zainstaluj najnowszą wersję pakietu SDK, np.
pip install -U google-genai
.
Wysyłanie i odbieranie SMS-ów
import asyncio
from google import genai
client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"
config = {"response_modalities": ["TEXT"]}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
while True:
message = input("User> ")
if message.lower() == "exit":
break
await session.send_client_content(
turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
)
async for response in session.receive():
if response.text is not None:
print(response.text, end="")
if __name__ == "__main__":
asyncio.run(main())
Odbieranie dźwięku
Ten przykład pokazuje, jak odbierać dane audio i zapisywać je w pliku .wav
.
import asyncio
import wave
from google import genai
client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"
config = {"response_modalities": ["AUDIO"]}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
wf = wave.open("audio.wav", "wb")
wf.setnchannels(1)
wf.setsampwidth(2)
wf.setframerate(24000)
message = "Hello? Gemini are you there?"
await session.send_client_content(
turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
)
async for idx,response in async_enumerate(session.receive()):
if response.data is not None:
wf.writeframes(response.data)
# Un-comment this code to print audio data info
# if response.server_content.model_turn is not None:
# print(response.server_content.model_turn.parts[0].inline_data.mime_type)
wf.close()
if __name__ == "__main__":
asyncio.run(main())
Formaty audio
Dane audio w Live API są zawsze w postaci surowych danych 16-bitowego formatu PCM w systemie little-endian. Wyjście audio zawsze używa częstotliwości próbkowania 24 kHz. Wejście audio ma domyślnie częstotliwość 16 kHz, ale interfejs Live API w razie potrzeby przepróbkuje sygnał, aby można było przesłać dowolną częstotliwość próbkowania. Aby przekazać częstotliwość próbkowania wejściowego dźwięku, ustaw typ MIME każdego bloba zawierającego dźwięk na wartość, np. audio/pcm;rate=16000
.
strumieniowanie dźwięku i obrazu,
Instrukcje systemowe
Instrukcje systemu umożliwiają kierowanie działaniem modelu na podstawie Twoich konkretnych potrzeb i przypadków użycia. Instrukcje dotyczące systemu można ustawić w konfiguracji i będą one obowiązywać przez całą sesję.
from google.genai import types
config = {
"system_instruction": types.Content(
parts=[
types.Part(
text="You are a helpful assistant and answer in a friendly tone."
)
]
),
"response_modalities": ["TEXT"],
}
Przyrostowe aktualizacje treści
Używaj przyrostowych aktualizacji, aby wysyłać dane wejściowe tekstowe, ustalać kontekst sesji lub przywracać kontekst sesji. W przypadku krótkich kontekstów możesz wysyłać interakcje krok po kroku, aby reprezentować dokładną sekwencję zdarzeń:
Python
turns = [
{"role": "user", "parts": [{"text": "What is the capital of France?"}]},
{"role": "model", "parts": [{"text": "Paris"}]},
]
await session.send_client_content(turns=turns, turn_complete=False)
turns = [{"role": "user", "parts": [{"text": "What is the capital of Germany?"}]}]
await session.send_client_content(turns=turns, turn_complete=True)
JSON
{
"clientContent": {
"turns": [
{
"parts":[
{
"text": ""
}
],
"role":"user"
},
{
"parts":[
{
"text": ""
}
],
"role":"model"
}
],
"turnComplete": true
}
}
W przypadku dłuższych kontekstów zalecamy podanie podsumowania w jednej wiadomości, aby zwolnić okno kontekstu na potrzeby kolejnych interakcji.
Zmień głosy
Interfejs Live API obsługuje te głosy: Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus i Zephyr.
Aby określić głos, ustaw nazwę głosu w obiekcie speechConfig
w ramach konfiguracji sesji:
Python
from google.genai import types
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
speech_config=types.SpeechConfig(
voice_config=types.VoiceConfig(
prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
)
)
)
JSON
{
"voiceConfig": {
"prebuiltVoiceConfig": {
"voiceName": "Kore"
}
}
}
Zmień język
Interfejs Live API obsługuje wiele języków.
Aby zmienić język, skonfiguruj kod języka w obiekcie speechConfig
w ramach konfiguracji sesji:
from google.genai import types
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
speech_config=types.SpeechConfig(
language_code="de-DE",
)
)
Korzystanie z narzędzi
Za pomocą interfejsu Live API możesz definiować narzędzia takie jak wywoływanie funkcji, wykonywanie kodu i wyszukiwarka Google.
Korzystanie z wywołania funkcji
Deklaracje funkcji możesz definiować w ramach konfiguracji sesji. Więcej informacji znajdziesz w samouczku dotyczącym wywoływania funkcji.
Po otrzymaniu wywołań narzędzia klient powinien odpowiedzieć listą obiektów FunctionResponse
za pomocą metody session.send_tool_response
.
import asyncio
from google import genai
from google.genai import types
client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"
# Simple function definitions
turn_on_the_lights = {"name": "turn_on_the_lights"}
turn_off_the_lights = {"name": "turn_off_the_lights"}
tools = [{"function_declarations": [turn_on_the_lights, turn_off_the_lights]}]
config = {"response_modalities": ["TEXT"], "tools": tools}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
prompt = "Turn on the lights please"
await session.send_client_content(turns={"parts": [{"text": prompt}]})
async for chunk in session.receive():
if chunk.server_content:
if chunk.text is not None:
print(chunk.text)
elif chunk.tool_call:
function_responses = []
for fc in tool_call.function_calls:
function_response = types.FunctionResponse(
id=fc.id,
name=fc.name,
response={ "result": "ok" } # simple, hard-coded function response
)
function_responses.append(function_response)
await session.send_tool_response(function_responses=function_responses)
if __name__ == "__main__":
asyncio.run(main())
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 przetwarzanie sekwencyjne.
Wejścia i wyjścia audio negatywnie wpływają na zdolność modelu do używania funkcji wywoływania.
Użyj wykonania kodu
Wykonywanie kodu możesz zdefiniować w ramach konfiguracji sesji. Więcej informacji znajdziesz w samouczku dotyczącym wykonywania kodu.
import asyncio
from google import genai
from google.genai import types
client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"
tools = [{'code_execution': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
prompt = "Compute the largest prime palindrome under 100000."
await session.send_client_content(turns={"parts": [{"text": prompt}]})
async for chunk in session.receive():
if chunk.server_content:
if chunk.text is not None:
print(chunk.text)
model_turn = chunk.server_content.model_turn
if model_turn:
for part in model_turn.parts:
if part.executable_code is not None:
print(part.executable_code.code)
if part.code_execution_result is not None:
print(part.code_execution_result.output)
if __name__ == "__main__":
asyncio.run(main())
Korzystanie z groundingu z użyciem wyszukiwarki Google
Funkcję Grounding z użyciem wyszukiwarki Google możesz włączyć w ramach konfiguracji sesji. Więcej informacji znajdziesz w samouczku na temat technik uziemienia.
import asyncio
from google import genai
from google.genai import types
client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"
tools = [{'google_search': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
prompt = "When did the last Brazil vs. Argentina soccer match happen?"
await session.send_client_content(turns={"parts": [{"text": prompt}]})
async for chunk in session.receive():
if chunk.server_content:
if chunk.text is not None:
print(chunk.text)
# The model might generate and execute Python code to use Search
model_turn = chunk.server_content.model_turn
if model_turn:
for part in model_turn.parts:
if part.executable_code is not None:
print(part.executable_code.code)
if part.code_execution_result is not None:
print(part.code_execution_result.output)
if __name__ == "__main__":
asyncio.run(main())
Połączenie kilku narzędzi
Możesz łączyć różne narzędzia w ramach interfejsu Live API:
prompt = """
Hey, I need you to do three things for me.
1. Compute the largest prime palindrome under 100000.
2. Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024?
3. Turn on the lights
Thanks!
"""
tools = [
{"google_search": {}},
{"code_execution": {}},
{"function_declarations": [turn_on_the_lights, turn_off_the_lights]},
]
config = {"response_modalities": ["TEXT"], "tools": tools}
Zarządzanie powiadomieniami
Użytkownicy mogą w dowolnym momencie przerwać działanie modelu. Gdy wykrywanie aktywności związanej z głosem (VAD) wykryje przerwanie, trwają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.
Dodatkowo serwer Gemini odrzuca wszystkie oczekujące wywołania funkcji i wysyła wiadomość BidiGenerateContentServerContent
z identyfikatorami anulowanych połączeń.
async for response in session.receive():
if response.server_content.interrupted is True:
# The generation was interrupted
Konfigurowanie wykrywania aktywności głosowej (VAD)
Możesz skonfigurować wykrywanie aktywności głosowej (VAD) lub je wyłączyć.
Korzystanie z automatycznego wykrywania dźwięku
Domyślnie model automatycznie wykonuje wykrywanie dźwięku w ciągłym strumieniu wejściowym dźwięku. Funkcję VAD można skonfigurować za pomocą pola realtimeInputConfig.automaticActivityDetection
w konfiguracji konfiguracji.
Gdy strumień audio jest wstrzymany przez ponad sekundę (np. dlatego, że użytkownik wyłączył mikrofon), należy wysłać zdarzenie audioStreamEnd
, aby opróżnić pamięć podręczną z dźwięku. Klient może wznowić wysyłanie danych audio w dowolnym momencie.
# example audio file to try:
# URL = "https://storage.googleapis.com/generativeai-downloads/data/hello_are_you_there.pcm"
# !wget -q $URL -O sample.pcm
import asyncio
from pathlib import Path
from google import genai
client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"
config = {"response_modalities": ["TEXT"]}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
audio_bytes = Path("sample.pcm").read_bytes()
await session.send_realtime_input(
audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
)
# if stream gets paused, send:
# await session.send_realtime_input(audio_stream_end=True)
async for response in session.receive():
if response.text is not None:
print(response.text)
if __name__ == "__main__":
asyncio.run(main())
W przypadku send_realtime_input
interfejs API automatycznie reaguje na dźwięk na podstawie wykrywania mowy. Funkcja send_client_content
dodaje wiadomości do kontekstu modelu w kolejności, a funkcja send_realtime_input
jest zoptymalizowana pod kątem szybkości działania kosztem porządku decyzyjnego.
Konfigurowanie automatycznego wykrywania dźwięku
Aby uzyskać większą kontrolę nad działaniem funkcji VAD, możesz skonfigurować te parametry: Więcej informacji znajdziesz w dokumentacji interfejsu API.
from google.genai import types
config = {
"response_modalities": ["TEXT"],
"realtime_input_config": {
"automatic_activity_detection": {
"disabled": False, # default
"start_of_speech_sensitivity": types.StartSensitivity.START_SENSITIVITY_LOW,
"end_of_speech_sensitivity": types.EndSensitivity.END_SENSITIVITY_LOW,
"prefix_padding_ms": 20,
"silence_duration_ms": 100,
}
}
}
Wyłączanie automatycznego wykrywania przerw
Automatyczne wykrywanie mowy można też wyłączyć, ustawiając wartość parametru realtimeInputConfig.automaticActivityDetection.disabled
na true
w wiadomości konfiguracyjnej. W tej konfiguracji klient odpowiada za wykrywanie mowy użytkownika i wysyłanie wiadomości activityStart
i activityEnd
w odpowiednich momentach. W tej konfiguracji nie jest wysyłana wiadomość audioStreamEnd
. Zamiast tego każde przerwanie strumienia jest oznaczane komunikatem activityEnd
.
config = {
"response_modalities": ["TEXT"],
"realtime_input_config": {"automatic_activity_detection": {"disabled": True}},
}
async with client.aio.live.connect(model=model, config=config) as session:
# ...
await session.send_realtime_input(activity_start=types.ActivityStart())
await session.send_realtime_input(
audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
)
await session.send_realtime_input(activity_end=types.ActivityEnd())
# ...
Pobieranie liczby tokenów
Łączną liczbę wykorzystanych tokenów znajdziesz w polu usageMetadata zwracanego komunikatu serwera.
async for message in session.receive():
# The server will periodically send messages that include UsageMetadata.
if message.usage_metadata:
usage = message.usage_metadata
print(
f"Used {usage.total_token_count} tokens in total. Response token breakdown:"
)
for detail in usage.response_tokens_details:
match detail:
case types.ModalityTokenCount(modality=modality, token_count=count):
print(f"{modality}: {count}")
Wydłużanie czasu trwania sesji
Maksymalny czas trwania sesji można wydłużyć do nieograniczonego za pomocą 2 mechanizmów:
Ponadto przed zakończeniem sesji otrzymasz wiadomość GoAway, która umożliwi Ci podjęcie dalszych działań.
Włącz kompresję okna kontekstowego
Aby umożliwić dłuższe sesje i uniknąć nagłego zakończenia połączenia, możesz włączyć kompresję okna kontekstowego, ustawiając pole contextWindowCompression w ramach konfiguracji sesji.
W ContextWindowCompressionConfig możesz skonfigurować mechanizm okna przesuwającego oraz liczbę tokenów, które uruchamiają kompresję.
from google.genai import types
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
context_window_compression=(
# Configures compression with default parameters.
types.ContextWindowCompressionConfig(
sliding_window=types.SlidingWindow(),
)
),
)
Konfigurowanie wznawiania sesji
Aby zapobiec zakończeniu sesji, gdy serwer okresowo resetuje połączenie WebSocket, skonfiguruj pole sessionResumption w konfiguracji konfiguracji.
Przekazanie tej konfiguracji powoduje, że serwer wysyła wiadomości SessionResumptionUpdate, których można użyć do wznowienia sesji, przekazując ostatni token wznowienia jako SessionResumptionConfig.handle
kolejnego połączenia.
import asyncio
from google import genai
from google.genai import types
client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"
async def main():
print(f"Connecting to the service with handle {previous_session_handle}...")
async with client.aio.live.connect(
model=model,
config=types.LiveConnectConfig(
response_modalities=["AUDIO"],
session_resumption=types.SessionResumptionConfig(
# The handle of the session to resume is passed here,
# or else None to start a new session.
handle=previous_session_handle
),
),
) as session:
while True:
await session.send_client_content(
turns=types.Content(
role="user", parts=[types.Part(text="Hello world!")]
)
)
async for message in session.receive():
# Periodically, the server will send update messages that may
# contain a handle for the current state of the session.
if message.session_resumption_update:
update = message.session_resumption_update
if update.resumable and update.new_handle:
# The handle should be retained and linked to the session.
return update.new_handle
# For the purposes of this example, placeholder input is continually fed
# to the model. In non-sample code, the model inputs would come from
# the user.
if message.server_content and message.server_content.turn_complete:
break
if __name__ == "__main__":
asyncio.run(main())
otrzymywać wiadomość przed zakończeniem sesji;
Serwer wysyła wiadomość GoAway, która sygnalizuje, że bieżące połączenie zostanie wkrótce zakończone. Wiadomość zawiera timeLeft, czyli pozostały czas, oraz umożliwia podjęcie dalszych działań, zanim połączenie zostanie zakończone jako ABORTED.
async for response in session.receive():
if response.go_away is not None:
# The connection will soon be terminated
print(response.go_away.time_left)
otrzymywać wiadomość, gdy generowanie zostanie zakończone;
Serwer wysyła wiadomość generationComplete, która sygnalizuje, że model zakończył generowanie odpowiedzi.
async for response in session.receive():
if response.server_content.generation_complete is True:
# The generation is complete
Zmień rozdzielczość multimediów
Rozdzielczość multimediów wejściowych możesz określić, ustawiając pole mediaResolution
w ramach konfiguracji sesji:
from google.genai import types
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,
)
Odbieranie zapisów tekstowych
Możesz włączyć transkrypcję wyjścia audio modelu. Język transkrypcji jest określany na podstawie odpowiedzi modelu.
import asyncio
from google import genai
from google.genai import types
client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"
config = {"response_modalities": ["AUDIO"],
"output_audio_transcription": {}
}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
message = "Hello? Gemini are you there?"
await session.send_client_content(
turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
)
async for response in session.receive():
if response.server_content.model_turn:
print("Model turn:", response.server_content.model_turn)
if response.server_content.output_transcription:
print("Transcript:", response.server_content.output_transcription.text)
if __name__ == "__main__":
asyncio.run(main())
Ograniczenia
Podczas planowania projektu weź pod uwagę te ograniczenia interfejsu Live API i Gemini 2.0.
Sposoby odpowiedzi
W ramach konfiguracji sesji możesz ustawić tylko 1 rodzaj odpowiedzi (TEXT
lub AUDIO
) na sesję. Próba ustawienia obu spowoduje wyświetlenie komunikatu o błędzie konfiguracji. Oznacza to, że możesz skonfigurować model tak, aby odpowiadał w postaci tekstu lub dźwięku, ale nie w obu tych formatach w ramach tej samej sesji.
Uwierzytelnianie klienta
Interfejs Live API zapewnia uwierzytelnianie serwera z serwerem i nie jest zalecany do bezpośredniego korzystania przez klienta. Dane wejściowe klienta powinny być kierowane przez pośredni serwer aplikacji, aby zapewnić bezpieczne uwierzytelnianie za pomocą interfejsu Live API.
Czas trwania sesji
Czas trwania sesji można wydłużyć do nieograniczonego, włączając kompresję sesji. Bez kompresji sesje z tylko dźwiękiem są ograniczone do 15 minut, a sesje z dźwiękiem i wideo do 2 minut. Przekroczenie tych limitów bez kompresji spowoduje przerwanie połączenia.
Możesz też skonfigurować wznawianie sesji, aby umożliwić klientowi wznowienie zakończonej sesji.
Okno kontekstu
Okno kontekstu sesji ma limit 32 tys. tokenów.
Obsługiwane języki
Interfejs Live API obsługuje te języki:
Język | Kod BCP-47 |
---|---|
niemiecki (Niemcy) | de-DE |
angielski (Australia) | en-AU |
angielski (UK) | en-GB |
angielski (Indie) | en-IN |
angielski (USA) | en-US |
hiszpański (Stany Zjednoczone) | es-US |
Język francuski (Francja) | fr-FR |
hindi (Indie) | hi-IN |
portugalski (Brazylia) | pt-BR |
arabski (ogólny) | ar-XA |
hiszpański (Hiszpania) | es-ES |
francuski (Kanada) | fr-CA |
indonezyjski (Indonezja) | id-ID |
włoski (Włochy) | it-IT |
japoński (Japonia) | ja-JP |
turecki (Turcja) | tr-TR |
wietnamski (Wietnam) | vi-VN |
bengalski (Indie) | bn-IN |
gudźarati (Indie) | gu-IN |
kannada (Indie) | kn-IN |
malajalam (Indie) | ml-IN |
marathi (Indie) | mr-IN |
tamilski (Indie) | ta-IN |
telugu (Indie) | te-IN |
niderlandzki (Holandia) | nl-NL |
koreański (Korea Południowa) | ko-KR |
chiński mandaryński (Chiny), | cmn-CN |
polski (Polska) | pl-PL |
rosyjski (Rosja) | ru-RU |
tajski (Tajlandia) | th-TH |
Integracje z rozwiązaniami innych firm
W przypadku wdrożeń aplikacji internetowych i mobilnych możesz zapoznać się z opcjami dostępnymi w tych usługach: