Panduan ini menunjukkan cara melakukan percakapan interaktif secara real-time menggunakan Live API. Halaman ini membahas beberapa topik berikut:
- Mulai percakapan: Pelajari cara memulai percakapan menggunakan Vertex AI Studio, Gen AI SDK, atau WebSockets.
- Mengubah setelan bahasa dan suara: Sesuaikan suara dan bahasa yang disintesis untuk respons model.
- Mengubah setelan deteksi aktivitas suara: Konfigurasi cara model mendeteksi ucapan pengguna untuk memungkinkan interupsi alami.
- Mengelola jendela konteks: Kontrol cara histori percakapan disimpan dan dikompresi untuk mengelola penggunaan token.
- Memperpanjang dan melanjutkan sesi: Pelajari cara memperpanjang durasi sesi aktif dan terhubung kembali ke sesi sebelumnya.
Live API memungkinkan interaksi suara dan video dua arah dengan latensi rendah dengan Gemini.
Model yang didukung
Anda dapat menggunakan Live API dengan model berikut:
Versi model | Tingkat ketersediaan |
---|---|
gemini-live-2.5-flash |
GA Pribadi* |
gemini-live-2.5-flash-preview-native-audio |
Pratinjau publik |
* Untuk meminta akses, hubungi perwakilan tim akun Google Anda.
Mulai percakapan
Anda dapat memulai percakapan menggunakan Vertex AI Studio, Gen AI SDK, atau dengan membuat permintaan langsung dengan WebSockets.
Metode | Deskripsi | Kasus Penggunaan |
---|---|---|
Vertex AI Studio | UI berbasis web untuk pengujian dan eksperimen API yang cepat dan tanpa kode. | Ideal untuk pemula, pembuatan prototipe cepat, dan menjelajahi fitur API tanpa menulis kode. |
Gen AI SDK | Library Python yang menyediakan antarmuka tingkat tinggi yang mudah digunakan untuk berinteraksi dengan API. API ini menangani pengelolaan koneksi dan menyederhanakan pengiriman serta penerimaan data. | Direkomendasikan untuk sebagian besar pengembangan aplikasi di Python, terutama untuk aplikasi yang memerlukan input dan output audio. |
WebSockets | Protokol tingkat rendah untuk komunikasi dua arah yang langsung dan persisten dengan API. Metode ini mengharuskan Anda menangani penyiapan koneksi, pemformatan pesan, dan encoding data secara manual. | Cocok untuk aplikasi yang dibangun dalam bahasa selain Python atau untuk developer yang memerlukan kontrol terperinci atas protokol komunikasi. |
Konsol
- Buka halaman Vertex AI Studio > Stream realtime.
- Untuk memulai percakapan, klik Mulai sesi.
Untuk mengakhiri sesi, klik
Hentikan sesi.Python
Contoh berikut menunjukkan cara menyiapkan percakapan interaktif real-time. Untuk menjalankan kode ini, Anda memerlukan komputer lokal dengan mikrofon dan speaker; kode ini tidak berfungsi di notebook Colab. Contoh ini memungkinkan Anda mengirim perintah audio dan menerima respons audio dari API.
""" # Installation # on linux sudo apt-get install portaudio19-dev # on mac brew install portaudio python3 -m venv env source env/bin/activate pip install google-genai """ import asyncio import pyaudio from google import genai from google.genai import types CHUNK=4200 FORMAT=pyaudio.paInt16 CHANNELS=1 RECORD_SECONDS=5 MODEL = 'gemini-live-2.5-flash' INPUT_RATE=16000 OUTPUT_RATE=24000 client = genai.Client( vertexai=True, project=GOOGLE_CLOUD_PROJECT, location=GOOGLE_CLOUD_LOCATION, ) config = { "response_modalities": ["AUDIO"], "input_audio_transcription": {}, # Configure input transcription "output_audio_transcription": {}, # Configure output transcription } async def main(): print(MODEL) p = pyaudio.PyAudio() async with client.aio.live.connect(model=MODEL, config=config) as session: #exit() async def send(): stream = p.open( format=FORMAT, channels=CHANNELS, rate=INPUT_RATE, input=True, frames_per_buffer=CHUNK) while True: frame = stream.read(CHUNK) await session.send(input={"data": frame, "mime_type": "audio/pcm"}) await asyncio.sleep(10**-12) async def receive(): output_stream = p.open( format=FORMAT, channels=CHANNELS, rate=OUTPUT_RATE, output=True, frames_per_buffer=CHUNK) async for message in session.receive(): if message.server_content.input_transcription: print(message.server_content.model_dump(mode="json", exclude_none=True)) if message.server_content.output_transcription: print(message.server_content.model_dump(mode="json", exclude_none=True)) if message.server_content.model_turn: for part in message.server_content.model_turn.parts: if part.inline_data.data: audio_data=part.inline_data.data output_stream.write(audio_data) await asyncio.sleep(10**-12) send_task = asyncio.create_task(send()) receive_task = asyncio.create_task(receive()) await asyncio.gather(send_task, receive_task) asyncio.run(main())
Python
Untuk menyiapkan percakapan tempat Anda mengirim perintah teks dan menerima respons audio, gunakan kode berikut:
# Set model generation_config CONFIG = {"response_modalities": ["AUDIO"]} headers = { "Content-Type": "application/json", "Authorization": f"Bearer {bearer_token[0]}", } async def main() -> None: # Connect to the server async with connect(SERVICE_URL, additional_headers=headers) as ws: # Setup the session async def setup() -> None: await ws.send( json.dumps( { "setup": { "model": "gemini-live-2.5-flash", "generation_config": CONFIG, } } ) ) # Receive setup response raw_response = await ws.recv(decode=False) setup_response = json.loads(raw_response.decode("ascii")) print(f"Connected: {setup_response}") return # Send text message async def send() -> bool: text_input = input("Input > ") if text_input.lower() in ("q", "quit", "exit"): return False msg = { "client_content": { "turns": [{"role": "user", "parts": [{"text": text_input}]}], "turn_complete": True, } } await ws.send(json.dumps(msg)) return True # Receive server response async def receive() -> None: responses = [] # Receive chucks of server response async for raw_response in ws: response = json.loads(raw_response.decode()) server_content = response.pop("serverContent", None) if server_content is None: break model_turn = server_content.pop("modelTurn", None) if model_turn is not None: parts = model_turn.pop("parts", None) if parts is not None: for part in parts: pcm_data = base64.b64decode(part["inlineData"]["data"]) responses.append(np.frombuffer(pcm_data, dtype=np.int16)) # End of turn turn_complete = server_content.pop("turnComplete", None) if turn_complete: break # Play the returned audio message display(Markdown("**Response >**")) display(Audio(np.concatenate(responses), rate=24000, autoplay=True)) return await setup() while True: if not await send(): break await receive()
Jalankan fungsi main
untuk memulai percakapan. Kemudian, Anda dapat memasukkan perintah. Untuk keluar, ketik q
, quit
, atau exit
.
await main()
Mengubah setelan bahasa dan suara
Live API menggunakan Chirp 3 untuk mendukung respons ucapan yang disintesis dalam berbagai suara dan bahasa HD. Untuk mengetahui daftar lengkap dan demo setiap suara, lihat Chirp 3: Suara HD.
Untuk menyetel suara dan bahasa respons, lakukan hal berikut:
Konsol
- Buka halaman Vertex AI Studio > Stream realtime.
- Di peluas Output, pilih suara dari menu drop-down Suara.
- Di perluasan yang sama, pilih bahasa dari menu drop-down Bahasa.
- Untuk memulai sesi, klik Mulai sesi.
Python
config = LiveConnectConfig( response_modalities=["AUDIO"], speech_config=SpeechConfig( voice_config=VoiceConfig( prebuilt_voice_config=PrebuiltVoiceConfig( voice_name=voice_name, ) ), language_code="en-US", ), )
Mengubah setelan deteksi aktivitas suara
Deteksi aktivitas suara (VAD) memungkinkan model mengenali saat seseorang berbicara, yang penting untuk memungkinkan interupsi alami dalam percakapan. Anda dapat menggunakan VAD otomatis default atau mengelolanya dari klien Anda.
VAD otomatis (default): Model melakukan VAD pada aliran input audio berkelanjutan.
- Anda dapat mengonfigurasi setelan VAD, seperti sensitivitas, menggunakan kolom
realtimeInputConfig.automaticActivityDetection
dari pesan penyiapan. - Saat VAD mendeteksi gangguan, model akan menghentikan responsnya saat ini, dan server akan mengirim pesan untuk melaporkan gangguan tersebut.
- Jika streaming audio dijeda selama lebih dari satu detik (misalnya, pengguna membisukan mikrofonnya), kirim peristiwa
audioStreamEnd
untuk menghapus semua audio yang di-cache.
- Anda dapat mengonfigurasi setelan VAD, seperti sensitivitas, menggunakan kolom
VAD yang dikelola klien: Untuk mengelola VAD dari aplikasi Anda, nonaktifkan VAD otomatis dengan menyetel
realtimeInputConfig.automaticActivityDetection.disabled
ketrue
. Dalam mode ini, klien Anda bertanggung jawab untuk mendeteksi ucapan pengguna dan mengirim pesanactivityStart
danactivityEnd
untuk mengontrol alur percakapan.
Python
config = LiveConnectConfig( response_modalities=["TEXT"], realtime_input_config=RealtimeInputConfig( automatic_activity_detection=AutomaticActivityDetection( disabled=False, # default start_of_speech_sensitivity=StartSensitivity.START_SENSITIVITY_LOW, # Either START_SENSITIVITY_LOW or START_SENSITIVITY_HIGH end_of_speech_sensitivity=EndSensitivity.END_SENSITIVITY_LOW, # Either END_SENSITIVITY_LOW or END_SENSITIVITY_HIGH prefix_padding_ms=20, silence_duration_ms=100, ) ), ) async with client.aio.live.connect( model=MODEL_ID, config=config, ) as session: audio_bytes = Path("sample.pcm").read_bytes() await session.send_realtime_input( media=Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000") ) # if stream gets paused, send: # await session.send_realtime_input(audio_stream_end=True) response = [] async for message in session.receive(): if message.server_content.interrupted is True: # The model generation was interrupted response.append("The session was interrupted") if message.text: response.append(message.text) display(Markdown(f"**Response >** {''.join(response)}"))
Mengelola sesi percakapan
Bagian ini menjelaskan cara mengelola durasi, konteks, dan status sesi.
Memperpanjang sesi
Perpanjangan sesi hanya tersedia saat Anda menggunakan Gen AI SDK. Model ini tidak tersedia di Vertex AI Studio.
Durasi maksimum default sesi percakapan adalah 10 menit. Notifikasi goAway
(BidiGenerateContentServerMessage.goAway
) dikirim ke klien 60 detik sebelum sesi berakhir.
Anda dapat memperpanjang durasi sesi dalam kelipatan 10 menit menggunakan Gen AI SDK. Tidak ada batasan berapa kali Anda dapat memperpanjang sesi. Untuk contohnya, lihat Mengaktifkan dan menonaktifkan kelanjutan sesi.
Melanjutkan sesi
Kelanjutan sesi memungkinkan Anda terhubung kembali ke sesi sebelumnya dalam waktu 24 jam dengan menyimpan data yang di-cache, termasuk teks, video, perintah audio, dan output model. Privasi tingkat project diterapkan untuk data yang di-cache ini. Secara default, kelanjutan sesi dinonaktifkan.
Untuk mengaktifkan kelanjutan sesi, tetapkan kolom sessionResumption
dari pesan BidiGenerateContentSetup
. Jika diaktifkan, server akan mengambil snapshot konteks sesi saat ini secara berkala dan menyimpannya. Saat snapshot berhasil diambil, resumptionUpdate
akan ditampilkan dengan ID handle yang dapat Anda gunakan untuk melanjutkan sesi nanti.
Contoh berikut menunjukkan cara mengaktifkan kelanjutan sesi dan mengambil ID handle:
Python
import asyncio from google import genai from google.genai import types client = genai.Client( vertexai=True, project=GOOGLE_CLOUD_PROJECT, location=GOOGLE_CLOUD_LOCATION, ) model = "gemini-live-2.5-flash" 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())
Untuk melanjutkan sesi dengan lancar, aktifkan mode transparan:
Python
types.LiveConnectConfig( response_modalities=["AUDIO"], session_resumption=types.SessionResumptionConfig( transparent=True, ), )
Mengelola jendela konteks
Live API menggunakan jendela konteks untuk menyimpan histori percakapan, yang mencakup data yang di-streaming (25 token per detik untuk audio, 258 TPS untuk video), input teks, dan output model.
Untuk mencegah sesi berakhir tiba-tiba saat jendela konteks penuh, API menggunakan kompresi jendela konteks. Saat jumlah data di jendela konteks mencapai ukuran maksimum (trigger_tokens
), API akan memangkas giliran percakapan yang paling lama hingga ukuran konteks dikurangi ke ukuran target yang ditentukan (target_tokens
).
Misalnya, jika panjang konteks maksimum Anda adalah 32000
token dan ukuran target Anda adalah 16000
token:
- Giliran 1: Percakapan dimulai. Permintaan ini menggunakan 12.000 token.
- Ukuran total konteks: 12.000 token
- Giliran 2: Permintaan kedua menggunakan 12.000 token lainnya.
- Ukuran total konteks: 24.000 token
- Putaran 3: Permintaan ketiga menggunakan 14.000 token.
- Total ukuran konteks: 38.000 token
Karena ukuran total konteks (38.000) kini melebihi maksimum (32.000), kompresi jendela konteks dipicu. API akan menghapus giliran terlama hingga jumlah total token sama dengan atau di bawah ukuran target (16.000):
- Tindakan ini menghapus Turn 1 (12.000 token). Totalnya sekarang adalah 26.000 token.
- Tindakan ini akan menghapus Turn 2 (12.000 token). Totalnya sekarang 14.000 token.
Hanya Turn 3 yang tetap berada di jendela konteks, dan percakapan berlanjut dari titik tersebut.
Panjang minimum dan maksimum untuk panjang konteks dan ukuran target adalah:
Setelan (flag API) | Nilai minimum | Nilai maksimum |
---|---|---|
Panjang konteks maksimum (trigger_tokens ) |
5.000 | 128.000 |
Ukuran konteks target (target_tokens ) |
0 | 128.000 |
Untuk menyetel jendela konteks:
Konsol
- Buka halaman Vertex AI Studio > Stream realtime.
- Klik untuk membuka menu Lanjutan.
- Di bagian Konteks Sesi, gunakan penggeser Ukuran konteks maks untuk menetapkan ukuran konteks ke nilai antara 5.000 dan 128.000.
- (Opsional) Di bagian yang sama, gunakan penggeser Ukuran konteks target untuk menetapkan ukuran target ke nilai antara 0 dan 128.000.
Python
Tetapkan kolom context_window_compression.trigger_tokens
dan
context_window_compression.sliding_window.target_tokens
dalam pesan penyiapan:
config = types.LiveConnectConfig( temperature=0.7, response_modalities=['TEXT'], system_instruction=types.Content( parts=[types.Part(text='test instruction')], role='user' ), context_window_compression=types.ContextWindowCompressionConfig( trigger_tokens=1000, sliding_window=types.SlidingWindow(target_tokens=10), ), )
Memperbarui petunjuk sistem selama sesi
Live API memungkinkan Anda memperbarui petunjuk sistem selama sesi aktif. Anda dapat menggunakannya untuk menyesuaikan perilaku model, seperti mengubah bahasa respons atau mengubah gaya bahasanya.
Untuk memperbarui petunjuk sistem di tengah sesi, kirim konten teks dengan peran system
. Instruksi yang diperbarui tetap berlaku untuk sesi lainnya.
Python
session.send_client_content( turns=types.Content( role="system", parts=[types.Part(text="new system instruction")] ), turn_complete=False )
Sesi serentak
Anda dapat memiliki hingga 5.000 sesi serentak per project.
Informasi selengkapnya
Untuk mengetahui informasi selengkapnya tentang penggunaan Live API, lihat: