Memulai dan mengelola sesi live

Gemini Live API memungkinkan interaksi suara dan teks 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 lancar, 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, Google Gen AI SDK, atau WebSocket.

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 jendela konteks, sesi audio saja dibatasi hingga 15 menit, dan sesi audio-video dibatasi hingga 2 menit karena batas token. Jika batas ini terlampaui, sesi akan dihentikan, tetapi Anda dapat menggunakan kompresi jendela konteks untuk memperpanjang sesi tanpa batas waktu.

Masa aktif koneksi dibatasi hingga sekitar 10 menit karena batasan koneksi WebSocket. Saat koneksi dihentikan, sesi juga akan dihentikan. 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.

Jumlah maksimum sesi serentak

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

Memulai sesi

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

Konsol

  1. Buka Vertex AI Studio > Stream realtime.
  2. Klik Start session untuk memulai percakapan.

Untuk mengakhiri sesi, klik Stop session.

Python

Sebelum memulai, Anda harus melakukan autentikasi ke Gemini Enterprise Agent Platform menggunakan kunci API atau kredensial default aplikasi (ADC): 

gcloud auth application-default login

Untuk mengetahui informasi selengkapnya tentang cara menyiapkan autentikasi, lihat panduan memulai. 

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-native-audio"
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 WebSocket, koneksi dibuat dengan handshake WebSocket standar Endpoint bersifat regional dan menggunakan token pembawa 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-native-audio"
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. Notifikasi goAway (BidiGenerateContentServerMessage.goAway) dikirim ke klien 60 detik sebelum sesi berakhir.

Untuk memperpanjang sesi melewati batas koneksi 10 menit, Anda harus terhubung kembali menggunakan kelanjutan sesi. Saat 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 yang utuh pada koneksi baru. Tidak ada batasan jumlah sesi yang dapat Anda lakukan. Untuk contoh melanjutkan sesi, lihat Melanjutkan sesi sebelumnya.

Contoh berikut menunjukkan cara mendeteksi penghentian sesi yang akan segera 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 singkat (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 teks, video, perintah audio, dan output model. Privasi level project diterapkan untuk data yang di-cache ini.

Secara default, kelanjutan sesi dinonaktifkan. Untuk mengaktifkan kelanjutan sesi, tetapkan kolom sessionResumption dari BidiGenerateContentSetup pesan. Jika diaktifkan, server akan mengirim pesan SessionResumptionUpdate secara berkala yang berisi session_id dan token kelanjutan. Jika WebSocket terputus, klien dapat terhubung kembali dan menyertakan kredensial ini dalam pesan penyiapan baru. Server kemudian memulihkan konteks sebelumnya, sehingga percakapan dapat dilanjutkan dengan lancar.

Periode kelanjutan terbatas (biasanya sekitar 10 menit). Jika klien tidak terhubung kembali dalam jangka waktu ini, status sesi akan dihapus untuk mengosongkan resource server.

Contoh berikut terhubung ke layanan, mendapatkan handle kelanjutan 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-native-audio"

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=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=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. Saat 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 fitur 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(
      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. Semua model Gemini Live API memiliki batas jendela konteks sebesar 128 ribu token.

Dalam sesi yang berjalan lama, seiring berjalannya percakapan, histori token audio dan teks akan terakumulasi. Jika histori ini melebihi batas model, model mungkin akan berhalusinasi, melambat, atau sesi dapat dihentikan secara paksa. Untuk mengaktifkan sesi yang lebih lama, 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. Saat token yang terakumulasi 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 terlama atau meringkasnya untuk mempertahankan konteks dalam batas. Di ContextWindowCompressionConfig, Anda dapat mengonfigurasi mekanisme jendela geser dan jumlah token yang ditentukan dalam parameter target_tokens yang memicu kompresi.

Hal ini memungkinkan durasi sesi yang secara teoritis tidak terbatas dari perspektif pengguna, karena "memori" terus dikelola. Tanpa kompresi, sesi audio saja mungkin dibatasi hingga sekitar 15 menit sebelum mencapai batas maksimum.

Panjang minimum dan maksimum untuk jendela 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 menetapkan jendela konteks:

Konsol

  1. Buka Vertex AI Studio > Stream realtime.
  2. Klik untuk membuka menu Advanced.
  3. Di bagian Session Context , gunakan penggeser Max context size untuk menetapkan ukuran konteks ke nilai antara 5.000 dan 128.000.
  4. (Opsional) Di bagian yang sama, gunakan penggeser Target context size 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 harus menambahkan objek input_audio_transcription dan output_audio_transcription serta memastikan text disertakan dalam response_modalities.

Untuk meningkatkan kualitas transkripsi untuk pengenalan ucapan otomatis (ASR) multibahasa, Anda dapat memberikan petunjuk bahasa menggunakan kolom language_codes dalam input_audio_transcription atau output_audio_transcription. Sebaiknya berikan petunjuk untuk meningkatkan kualitas transkripsi, karena petunjuk ini mengurangi risiko deteksi bahasa yang salah, terutama untuk perintah singkat. Kolom language_codes menerima daftar kode bahasa BCP-47 (misalnya, "en-US", "es-US").

config = {
    "response_modalities": ["audio", "text"],
    "input_audio_transcription": {
        "language_codes": ["en-US"]
    },
    "output_audio_transcription": {},
}

Memproses respons

Contoh kode berikut menunjukkan cara terhubung menggunakan sesi yang dikonfigurasi dan mengekstrak bagian teks (transkripsi) bersama 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