Memulai dan mengelola sesi live

Live API memungkinkan interaksi suara dan teks dengan latensi rendah dengan memproses aliran 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 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.

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 Melanjutkan sesi sebelumnya.

Untuk memperpanjang sesi:

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

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.

Berikut adalah contoh pengaktifan kelanjutan sesi dan pengambilan ID handle:

Python

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


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

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": {
     "session_resumption_config": {
        "transparent": True,
     }
   }
}

Memperbarui petunjuk sistem selama sesi

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_client_content(
      turns=types.Content(
          role="system", parts=[types.Part(text="new system instruction")]
      ),
      turn_complete=False
  )

Mengonfigurasi jendela konteks sesi

Jendela konteks Live API digunakan untuk menyimpan data yang di-streaming secara 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