Percakapan interaktif dengan Live API

Panduan ini menunjukkan cara melakukan percakapan interaktif secara real-time menggunakan Live API. Halaman ini membahas beberapa topik berikut:

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

  1. Buka halaman Vertex AI Studio > Stream realtime.
  2. 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

  1. Buka halaman Vertex AI Studio > Stream realtime.
  2. Di peluas Output, pilih suara dari menu drop-down Suara.
  3. Di perluasan yang sama, pilih bahasa dari menu drop-down Bahasa.
  4. 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.
  • VAD yang dikelola klien: Untuk mengelola VAD dari aplikasi Anda, nonaktifkan VAD otomatis dengan menyetel realtimeInputConfig.automaticActivityDetection.disabled ke true. Dalam mode ini, klien Anda bertanggung jawab untuk mendeteksi ucapan pengguna dan mengirim pesan activityStart dan activityEnd 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:

  1. Giliran 1: Percakapan dimulai. Permintaan ini menggunakan 12.000 token.
    • Ukuran total konteks: 12.000 token
  2. Giliran 2: Permintaan kedua menggunakan 12.000 token lainnya.
    • Ukuran total konteks: 24.000 token
  3. 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

  1. Buka halaman 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 = 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: