Memulai dan mengelola sesi live

Gemini Live API memungkinkan interaksi suara dan teks berlatensi rendah dengan memproses streaming audio atau teks berkelanjutan yang disebut sesi untuk memberikan respons lisan yang cepat dan mirip manusia. Pengelolaan siklus proses sesi, mulai dari handshake awal hingga penghentian secara 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, Google Gen AI SDK, atau WebSocket.

Halaman ini juga menunjukkan cara melakukan hal berikut:

• Memperpanjang sesi melebihi batas waktu default
• Melanjutkan sesi sebelumnya
• Memperbarui petunjuk sistem selama sesi
• Memperbarui petunjuk dan alat sistem selama sesi dengan Gemini 3.8 Live
• Mengonfigurasi jendela konteks sesi
• Mengaktifkan transkripsi untuk sesi
• Mengenkripsi data sesi dengan Kunci enkripsi yang dikelola pelanggan (CMEK)

Masa aktif sesi

Tanpa kompresi jendela konteks, sesi khusus audio 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 hingga waktu yang tidak terbatas.

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

Sesi serentak maksimum

Kuota sesi serentak diperiksa saat sesi dimulai dan berlaku baik saat Anda menggunakan Bayar sesuai penggunaan Standar (PayGo Standar) atau Throughput yang Disediakan:

• Untuk gemini-3.8-live, kuota sesi serentak berlaku untuk sesi Gemini Live API dan sesi Live Avatar. Untuk melihat batas spesifik project Anda, buka halaman Quotas and System Limits di konsolGoogle Cloud dan filter untuk gemini-3.8-live. Untuk mengetahui informasi selengkapnya, lihat Kuota sesi serentak Gemini 3.8 Live.
• Untuk gemini-live-2.5-flash-native-audio, Anda dapat memiliki hingga 1.000 sesi serentak per project secara default.

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 Mulai sesi untuk memulai percakapan.

Untuk mengakhiri sesi, klik Hentikan sesi.

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 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-3.8-live"
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 ini bersifat regional dan menggunakan token pemilik 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-3.8-live"
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())
      

Catatan: Meskipun beberapa parameter termasuk petunjuk sistem dapat disesuaikan di tengah sesi, model dan parameter lainnya biasanya tidak dapat diubah setelah pesan penyiapan diproses.

Memperpanjang sesi

Catatan: Ekstensi sesi hanya tersedia saat menggunakan Google Gen AI SDK, bukan Vertex AI Studio.

Durasi maksimum default sesi percakapan adalah 10 menit, yang dapat Anda perpanjang menggunakan notifikasi goAway. Notifikasi goAway (BidiGenerateContentServerMessage.goAway) dikirim ke klien 60 detik sebelum sesi berakhir.

Untuk memperpanjang sesi melebihi batas koneksi 10 menit, Anda harus terhubung kembali menggunakan melanjutkan 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 konteks yang tetap utuh di koneksi baru. Tidak ada batasan berapa kali Anda dapat melakukannya. Untuk mengetahui contoh cara melanjutkan sesi, lihat Melanjutkan sesi sebelumnya.

Contoh berikut menunjukkan cara mendeteksi penghentian sesi yang akan datang 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

Penting: Jika Anda perlu memastikan retensi data nol di aplikasi, jangan aktifkan pelanjutan sesi.

Gemini Live API mendukung melanjutkan sesi untuk mencegah pengguna kehilangan konteks percakapan selama koneksi terputus singkat (misalnya, beralih dari Wi-Fi ke 5G). Anda dapat melanjutkan sesi sebelumnya dalam waktu 24 jam. Pelanjutan sesi dicapai dengan menyimpan data yang di-cache, termasuk perintah teks, video, audio, dan output model. Privasi level project diterapkan untuk data yang di-cache ini.

Secara default, pelanjutan 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 kelanjutan. Jika WebSocket terputus, klien dapat terhubung kembali dan menyertakan kredensial ini dalam pesan penyiapan baru. Server kemudian memulihkan konteks sebelumnya, sehingga percakapan dapat berlanjut dengan lancar.

Jendela waktu untuk melanjutkan 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 melanjutkan 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-3.8-live"

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 pelanjutan sesi, Anda juga dapat mengaktifkan mode transparan untuk membantu membuat proses pelanjutan 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 lanjutan.

Untuk mengaktifkan mode transparan:

Python

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

Mengenkripsi data sesi dengan CMEK

Pelanjutan sesi menyimpan data sesi yang di-cache dalam penyimpanan hingga 24 jam. Untuk melindungi data tersebut dengan kunci Anda sendiri, bukanGoogle-owned and Google-managed encryption key, gunakan profil penayangan. Profil penyajian menautkan kunci Cloud Key Management Service ke project, lokasi, dan cakupan API. Meskipun profil penayangan ada, Agent Platform akan mengenkripsi data secara otomatis—konfigurasi sesi dan format permintaan Anda tidak berubah.

CMEK profil inferensi untuk Gemini Live API didukung di multi-region us dan eu. Region global tidak didukung.

Untuk menyiapkan CMEK untuk Gemini Live API, lakukan hal berikut:

1. Aktifkan Cloud KMS API dan Agent Platform API di project Anda. Lihat Sebelum memulai.
2. Buat kunci Cloud KMS di multi-region us atau eu. Lihat Membuat key ring dan kunci.
3. Berikan peran roles/cloudkms.cryptoKeyEncrypterDecrypter kepada agen layanan Gemini Enterprise Agent Platform pada kunci. Lihat Memberikan izin Agent Platform.
4. Buat profil penayangan yang menetapkan scope ke GEMINI_LIVE dan cmekConfig.encryptionSpec.kmsKeyName ke kunci Anda. Lihat Membuat profil penayangan.

Catatan: Data yang disimpan sebelum Anda membuat profil penayangan tidak akan dienkripsi ulang secara retroaktif dengan kunci Anda.

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 gaya bahasa.

Metode berikut berlaku untuk Audio Native Live API Gemini 2.5 Flash. Untuk Gemini 3.8 Live, lihat Memperbarui petunjuk dan alat sistem dengan Gemini 3.8 Live.

Untuk memperbarui petunjuk sistem di tengah sesi, Anda dapat mengirim konten teks dengan peran system. System instruction yang diperbarui akan tetap berlaku selama sisa sesi.

Python

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

Memperbarui petunjuk dan alat sistem dengan Gemini 3.8 Live

Dengan Gemini 3.8 Live, Anda dapat memperbarui petunjuk sistem dan alat sesi aktif dengan mengirimkan pesan BidiGenerateContentContextUpdate. Misalnya, Anda dapat mengubah bahasa atau gaya bahasa respons, atau memberi model serangkaian fungsi yang berbeda saat percakapan beralih ke tugas baru. Dengan Google Gen AI SDK, panggil send_context_update. Dengan WebSocket, tetapkan kolom context_update pesan klien. Jangan kirim konten klien dengan peran system ke Gemini 3.8 Live.

Tetapkan kolom yang ingin Anda ubah:

• system_instruction: Mengganti petunjuk sistem dari pesan penyiapan untuk sisa sesi.
• tools: Mengganti seluruh daftar alat sesi. Sertakan setiap alat yang masih dapat digunakan oleh model. Untuk menghapus semua alat, kirim daftar kosong.

Kolom yang tidak Anda tetapkan akan mempertahankan nilai saat ini. Update diproses secara berurutan dengan input sesi lainnya.

Catatan: Petunjuk dan alat sistem adalah bagian dari awalan perintah model, jadi memperbaruinya akan membatalkan cache perintah dan dapat meningkatkan latensi respons berikutnya. Perbarui hanya jika diperlukan.

Python

from google.genai import types

# Replace the system instruction.
await session.send_context_update(
    system_instruction="Respond only in Spanish."
)

# Replace the tool list.
get_current_weather = types.FunctionDeclaration(
    name="get_current_weather",
    description="Get the current weather in a given location",
    parameters=types.Schema(
        type=types.Type.OBJECT,
        properties={"location": types.Schema(type=types.Type.STRING)},
    ),
)
await session.send_context_update(
    tools=[types.Tool(function_declarations=[get_current_weather])]
)

# Remove all tools.
await session.send_context_update(tools=[])
      

Alat sisi server disiapkan saat sesi dimulai, sehingga batasan berikut berlaku saat update alat menyertakannya. Deklarasi fungsi tidak terpengaruh dan dapat ditambahkan dalam update alat apa pun.

• Untuk menggunakan Grounding dengan Google Penelusuran setelah update alat, deklarasikan juga google_search dalam pesan penyiapan.
• Alat Web Grounding for Enterprise, Agent Search, dan RAG Engine hanya dapat dideklarasikan dalam pesan penyiapan. context_update yang menyertakannya akan menampilkan error INVALID_ARGUMENT.

Mengonfigurasi jendela konteks sesi

Jendela konteks Gemini 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. Semua model Gemini Live API memiliki batas jendela konteks 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 mungkin akan 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 memotong giliran terlama jika diaktifkan. Jika token yang terakumulasi melebihi panjang maksimum yang ditentukan (ditetapkan menggunakan penggeser Max content size 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 khusus audio mungkin dibatasi hingga sekitar 15 menit sebelum mencapai batas pasti.

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 perlu menambahkan objek input_audio_transcription dan output_audio_transcription serta memastikan text disertakan dalam response_modalities.

Untuk meningkatkan kualitas transkripsi 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 hal 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 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

• Mengirim streaming audio dan video
• Praktik terbaik dengan Gemini Live API
• Mendesain perintah multimodal
• Pengantar panggilan fungsi