Memulai dan mengelola sesi live

Gemini Live API memungkinkan interaksi suara dan teks dengan latensi rendah dengan memproses streaming audio atau teks berkelanjutan yang disebut sesi untuk memberikan respons lisan yang langsung dan mirip manusia. Pengelolaan siklus proses sesi, mulai dari handshake awal hingga penghentian yang tuntas, dikontrol oleh developer.

Halaman ini menunjukkan cara memulai sesi percakapan dengan model Gemini menggunakan Gemini Live API. Anda dapat memulai sesi menggunakan Vertex AI Studio, Gen AI SDK, atau WebSockets.

Halaman ini juga menunjukkan cara melakukan hal berikut:

  • Memperpanjang sesi di luar batas waktu default
  • Melanjutkan sesi sebelumnya
  • Memperbarui petunjuk sistem selama sesi
  • Mengonfigurasi jendela konteks sesi
  • Mengaktifkan transkripsi untuk sesi

Masa aktif sesi

Tanpa kompresi, sesi audio saja dibatasi hingga 15 menit, dan sesi audio-video dibatasi hingga 2 menit. Jika batas ini terlampaui, sesi akan berakhir, tetapi Anda dapat menggunakan kompresi jendela konteks untuk memperpanjang sesi tanpa batas waktu.

Masa aktif koneksi dibatasi hingga sekitar 10 menit. Saat koneksi berakhir, sesi juga akan berakhir. Dalam hal ini, Anda dapat mengonfigurasi satu sesi agar tetap aktif di beberapa koneksi menggunakan kelanjutan sesi. Anda juga akan menerima pesan GoAway sebelum koneksi berakhir, sehingga Anda dapat mengambil tindakan lebih lanjut.

Sesi serentak maksimum

Anda dapat memiliki hingga 1.000 sesi serentak per project dengan paket bayar sesuai penggunaan (PayGo). Batas ini tidak berlaku untuk pelanggan yang menggunakan Throughput yang Disediakan.

Mulai sesi

Tab berikut menunjukkan cara memulai sesi percakapan langsung menggunakan Vertex AI Studio, Gen AI SDK, atau WebSockets:

Konsol

  1. Buka Vertex AI Studio > Stream realtime.
  2. Klik Mulai sesi untuk memulai percakapan.

Untuk mengakhiri sesi, klik Hentikan sesi.

Python

Sebelum memulai, Anda harus melakukan autentikasi ke Vertex AI menggunakan kunci API atau kredensial default aplikasi (ADC): 

gcloud auth application-default login

Untuk mengetahui informasi selengkapnya tentang penyiapan autentikasi, lihat panduan memulai kami. 

import asyncio
from google import genai

# Replace the PROJECT_ID and LOCATION with your Project ID and location. 
client = genai.Client(vertexai=True, project="PROJECT_ID", location="LOCATION")

# Configuration
MODEL = "gemini-live-2.5-flash-preview-native-audio-09-2025"
config = {
   "response_modalities": ["audio"],
}

async def main():
   # Establish WebSocket session
   async with client.aio.live.connect(model=MODEL, config=config) as session:
       print("Session established. Sending audio...")

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

Python

Saat menggunakan WebSockets, koneksi dibuat dengan handshake WebSocket standar. Endpoint bersifat regional dan menggunakan token bearer OAuth 2.0 untuk autentikasi. Dalam skenario ini, token autentikasi biasanya diteruskan di header WebSocket (seperti Authorization: Bearer [TOKEN]). 

import asyncio
import websockets

# Replace the PROJECT_ID and LOCATION with your Project ID and location. 
PROJECT_ID = "PROJECT_ID"
LOCATION = "LOCATION"

# Authentication
token_list = !gcloud auth application-default print-access-token
ACCESS_TOKEN = token_list[0]

# Configuration
MODEL_ID = "gemini-live-2.5-flash-preview-native-audio-09-2025"
MODEL = f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}"
config = {
   "response_modalities": ["audio"],
}

# Construct the WSS URL
HOST = f"{LOCATION}-aiplatform.googleapis.com"
URI = f"wss://{HOST}/ws/google.cloud.aiplatform.v1.LlmBidiService/BidiGenerateContent"

async def main():
   headers = {"Authorization": f"Bearer {ACCESS_TOKEN}"}
  
   async with websockets.connect(URI, additional_headers=headers) as ws:
       print("Session established.")

       # Send Setup (Handshake)
       await ws.send(json.dumps({
           "setup": {
               "model": MODEL,
               "generation_config": config
           }
       }))
    # Send audio/video ...

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

Memperpanjang sesi

Durasi maksimum default sesi percakapan adalah 10 menit. goAway notifikasi (BidiGenerateContentServerMessage.goAway) dikirim ke klien 60 detik sebelum sesi berakhir.

Untuk memperpanjang sesi melewati batas koneksi 10 menit, Anda harus menghubungkan kembali menggunakan kelanjutan sesi. Saat Anda menerima notifikasi goAway, atau saat koneksi dihentikan karena alasan lain, Anda dapat memulai koneksi baru menggunakan handle sesi yang diperoleh selama sesi. Tindakan ini akan melanjutkan sesi Anda dengan konteksnya tetap utuh pada koneksi baru. Tidak ada batasan jumlah upaya yang dapat Anda lakukan. Untuk contoh melanjutkan sesi, lihat Melanjutkan sesi sebelumnya.

Contoh berikut menunjukkan cara mendeteksi penghentian sesi yang akan terjadi dengan memproses notifikasi goAway:

Python

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)

Melanjutkan sesi sebelumnya

Gemini Live API mendukung kelanjutan sesi untuk mencegah pengguna kehilangan konteks percakapan selama koneksi terputus sebentar (misalnya, beralih dari Wi-Fi ke 5G). Anda dapat melanjutkan sesi sebelumnya dalam waktu 24 jam. Kelanjutan sesi dicapai dengan menyimpan data yang di-cache, termasuk perintah teks, video, 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 mengirimkan pesan SessionResumptionUpdate secara berkala yang berisi session_id dan token pelanjutan. Jika WebSocket terputus, klien dapat terhubung kembali dan menyertakan kredensial ini dalam pesan penyiapan baru. Kemudian, server akan memulihkan konteks sebelumnya, sehingga percakapan dapat dilanjutkan dengan lancar.

Interval pelanjutan terbatas (biasanya sekitar 10 menit). Jika klien tidak terhubung kembali dalam jangka waktu ini, status sesi akan dibatalkan untuk membebaskan resource server.

Contoh berikut terhubung ke layanan, mendapatkan handle pelanjutan sesi, menyimulasikan pemutusan koneksi, lalu terhubung kembali menggunakan handle untuk melanjutkan sesi:

Python

import asyncio
from google import genai
from google.genai import types
import websockets

# Replace the PROJECT_ID and LOCATION with your Project ID and location.
client = genai.Client(vertexai=True, project="PROJECT_ID", location="LOCATION")

# Configuration
MODEL = "gemini-live-2.5-flash-preview-native-audio-09-2025"

async def resumable_session_example():
    """Demonstrates session resumption by connecting, disconnecting, and reconnecting."""
    session_handle = None

    print("Starting a new session...")
    try:
        async with client.aio.live.connect(
            model=MODEL,
            config=types.LiveConnectConfig(
                response_modalities=["audio"],
                session_resumption_config=types.SessionResumptionConfig(handle=None),
            ),
        ) as session:
            await session.send_content(
                content=types.Content(role="user", parts=[types.Part(text="Hello!")])
            )
            async for message in session.receive():
                if message.session_resumption_update:
                    update = message.session_resumption_update
                    if update.resumable and update.new_handle:
                        session_handle = update.new_handle
                        print(f"Received session handle: {session_handle}")
                        # For demonstration, we break to simulate a disconnect
                        # after receiving a handle.
                        break
                if message.server_content and message.server_content.turn_complete:
                    break
    except websockets.exceptions.WebSocketException as e:
        print(f"Initial connection failed: {e}")
        return

    if not session_handle:
        print("Did not receive a session handle. Cannot demonstrate resumption.")
        return

    print(f"\nSimulating disconnect and reconnecting with handle {session_handle}...")

    try:
        async with client.aio.live.connect(
            model=MODEL,
            config=types.LiveConnectConfig(
                response_modalities=["audio"],
                session_resumption_config=types.SessionResumptionConfig(handle=session_handle),
            ),
        ) as session:
            print("Successfully resumed session.")
            await session.send_content(
                content=types.Content(role="user", parts=[types.Part(text="I am back!")])
            )
            async for message in session.receive():
                if message.session_resumption_update:
                    update = message.session_resumption_update
                    if update.resumable and update.new_handle:
                        session_handle = update.new_handle
                        print(f"Received updated session handle: {session_handle}")
                if message.server_content:
                    print(f"Received server content: {message.server_content}")
                    if message.server_content.turn_complete:
                        break
            print("Resumed session finished.")
    except websockets.exceptions.WebSocketException as e:
        print(f"Failed to resume session: {e}")

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

Mengaktifkan kelanjutan sesi yang lancar dengan mode transparan

Saat mengaktifkan kelanjutan sesi, Anda juga dapat mengaktifkan mode transparan untuk membantu membuat proses kelanjutan lebih lancar bagi pengguna. Jika mode transparan diaktifkan, indeks pesan klien yang sesuai dengan snapshot konteks akan ditampilkan secara eksplisit. Hal ini membantu mengidentifikasi pesan klien mana yang perlu Anda kirim lagi, saat Anda melanjutkan sesi dari handle kelanjutan.

Untuk mengaktifkan mode transparan:

Python

config = {
   "response_modalities": ["audio"],
   "session_resumption_config": {
    "transparent": True,
   }
}

Memperbarui petunjuk sistem selama sesi

Gemini Live API memungkinkan Anda memperbarui petunjuk sistem selama sesi aktif. Gunakan ini untuk menyesuaikan respons model, seperti mengubah bahasa respons atau mengubah nada bahasa.

Untuk memperbarui petunjuk sistem di tengah sesi, Anda dapat mengirimkan konten teks dengan peran system. Petunjuk sistem yang diperbarui akan tetap berlaku untuk sesi yang tersisa.

Python

session.send_content(
      content=types.Content(
          role="system", parts=[types.Part(text="new system instruction")]
      ),
      turn_complete=False
  )

Mengonfigurasi jendela konteks sesi

Jendela konteks Gemini Live API digunakan untuk menyimpan data streaming real-time (25 token per detik (TPS) untuk audio dan 258 TPS untuk video) dan konten lainnya, termasuk input teks dan output model. Sesi memiliki batas jendela konteks berikut:

  • 128 ribu token untuk model audio native
  • 32 ribu token untuk model Live API lainnya

Dalam sesi yang berjalan lama, seiring berjalannya percakapan, histori token audio dan teks akan terakumulasi. Jika histori ini melebihi batas model, model dapat berhalusinasi, melambat, atau sesi dapat dihentikan secara paksa. Untuk mengaktifkan sesi yang lebih panjang, Anda dapat mengaktifkan kompresi jendela konteks dengan menetapkan kolom contextWindowCompression sebagai bagian dari konfigurasi sesi.

Kompresi jendela konteks menggunakan jendela geser sisi server untuk memangkas giliran terlama saat diaktifkan. Jika token yang terkumpul melebihi panjang maksimum yang ditentukan (ditetapkan menggunakan penggeser Ukuran konten maks di Vertex AI Studio, atau trigger_tokens di API), server akan otomatis memangkas giliran percakapan terlama atau meringkasnya untuk mempertahankan konteks dalam batas. Di ContextWindowCompressionConfig, Anda dapat mengonfigurasi mekanisme sliding window dan jumlah token yang ditentukan dalam parameter target_tokens yang memicu kompresi.

Hal ini memungkinkan durasi sesi yang secara teoretis tidak terbatas dari perspektif pengguna, karena "memori" dikelola secara terus-menerus. Tanpa kompresi, sesi khusus audio mungkin dibatasi hingga sekitar 15 menit sebelum mencapai batas ketat.

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

  1. Buka Vertex AI Studio > Stream realtime.
  2. Klik untuk membuka menu Lanjutan.
  3. Di bagian Konteks Sesi, gunakan penggeser Ukuran konteks maks untuk menetapkan ukuran konteks ke nilai antara 5.000 dan 128.000.
  4. (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 = {
   "response_modalities": ["audio"],
   # Configures compression
   "context_window_compression" : {
    "trigger_tokens": 10000,
    "sliding_window": {"target_tokens" : 512}
   }
}

Mengaktifkan transkripsi audio untuk sesi

Anda dapat mengaktifkan transkripsi untuk audio input dan output.

Untuk menerima transkripsi, Anda harus memperbarui konfigurasi sesi. Anda perlu menambahkan objek input_audio_transcription dan output_audio_transcription serta memastikan text disertakan dalam response_modalities.

config = {
    "response_modalities": ["audio", "text"],
    "input_audio_transcription": {},
    "output_audio_transcription": {},
}

Memproses respons

Contoh kode berikut menunjukkan cara menghubungkan menggunakan sesi yang dikonfigurasi dan mengekstrak bagian teks (transkripsi) bersama dengan data audio.

# Receive Output Loop
async for message in session.receive():
    server_content = message.server_content
    if server_content:
        # Handle Model Turns (Audio + Text)
        model_turn = server_content.model_turn
        if model_turn and model_turn.parts:
            for part in model_turn.parts:
                # Handle Text (Transcriptions)
                if part.text:
                    print(f"Transcription: {part.text}")
                # Handle Audio
                if part.inline_data:
                    audio_data = part.inline_data.data
                    # Process audio bytes...
                    pass

        # Check for turn completion
        if server_content.turn_complete:
            print("Turn complete.")

Langkah berikutnya