Bermigrasi dari Audio Native Gemini 2.5 Flash Live API ke Gemini 3.8 Live

Dokumen ini menjelaskan perubahan yang diperlukan saat bermigrasi dari Gemini 2.5 Flash Live API Native Audio ke Gemini 3.8 Live.

Perubahan panggilan fungsi

Server Audio Native Gemini 2.5 Flash Live API memungkinkan panggilan alat asinkron. Sebaliknya, Gemini 3.8 Live mendukung panggilan fungsi asinkron dengan perubahan perilaku berikut:

• Gemini 3.8 Live mendukung pemblokiran panggilan fungsi saat deklarasi fungsi menyatakan behavior=BLOCKING dalam penyiapan. Jika input baru diterima selama eksekusi panggilan fungsi pemblokiran, server Live API akan membatalkan panggilan fungsi saat ini.

• Opsi scheduling=interrupt ke FunctionResponse mengubah perilaku:

  Penjadwalan FunctionResponse	Siapa yang berbicara	Audio Native Gemini 2.5 Flash Live API	Gemini 3.8 Live
  mengganggu	model	Menghentikan respons model aktif secara langsung; memutar respons alat.	Menghentikan respons model aktif secara langsung; memutar respons alat.
  mengganggu	pengguna	Segera menginterupsi; memutar respons alat melalui pengguna.	Menunggu pengguna selesai sebelum memutar respons alat.

Mengurangi pemindaian yang berlebihan dan percobaan ulang panggilan fungsi

Gemini 3.8 Live terkadang melakukan panggilan fungsi beruntun yang berlebihan dalam satu giliran saat alat tidak menampilkan hasil. Hal ini dapat mencakup pengulangan parameter yang bervariasi, sweeping dua hingga lima kali, sebelum merespons. Perilaku ini meningkatkan time-to-first-audio (TTFA) dan menghasilkan ucapan penggantian yang tidak akurat.

Panggilan fungsi berurutan yang berlebihan disebabkan oleh Gemini 3.8 Live yang mencoba menyelesaikan kueri. Jika alat menampilkan respons yang tidak informatif atau kosong, seperti {"results": [], "total_available": 0} atau None, model tidak dapat membedakan antara "habis secara permanen", "periode kueri terlalu sempit", atau "argumen tidak valid". Model mencoba memperluas atau memvariasikan kueri dalam upaya meningkatkan hasil, dan mulai menyapu.

Terapkan praktik pelengkap berikut:

• Menampilkan respons fungsi yang informatif: Setiap respons alat harus berisi informasi tentang error atau hasil, untuk memandu model Gemini 3.8 Live tentang cara melanjutkan.

  Tabel berikut menjelaskan kasus, cara model harus merespons, dan contoh payload yang diperlukan untuk membantu model:

  Kasus	Yang Harus Dilakukan Model	Konten Payload yang Wajib
  Kueri valid yang tidak menampilkan hasil. Mencoba lagi tidak akan membantu.	Hentikan penelusuran, beri tahu pengguna, dan tawarkan alternatif.	status: 'no_results', retryable: false, dan pesan bahasa alami yang jelas dan mudah dipahami.
  Argumen tidak valid atau tidak ada (misalnya, "penyedia salah").	Berhenti menelusuri, dan minta pengguna untuk mengklarifikasi atau mengonfirmasi.	status: 'invalid_argument', reason_code, retryable: false, dan valid_options
  Kueri valid yang memiliki jendela kosong. Kueri yang lebih luas benar-benar membantu.	Lakukan satu percobaan ulang yang wajar.	status: 'no_results_in_range', retryable: true, dan retry_hint

  Contoh berikut menunjukkan contoh payload saat search_appointment dipanggil, tetapi semua kemungkinan tanggal tidak tersedia. Pengguna berharap untuk mencoba vendor, bukan menyapu tanggal:

  def search_appointment(vendor: str, date: Datetime):
  
  # BEFORE (Invites Sweeping):
  {
    "results": [],
    "total_available": 0
  }
  
  # AFTER - Exhausted / Dead End (Stops Sweeping):
  {
    "results": [],
    "status": "no_availability",
    "retryable": false,
    "message": "No appointments are available for this provider for the foreseeable future. Searching other dates will not surface anything; openings only come from cancellations.",
    "suggested_next_step": "offer_waitlist_or_a_different_provider"
  }
  
  # AFTER - Invalid Argument (Prompts User Clarification):
  {
    "results": [],
    "status": "invalid_argument",
    "reason": "no_such_provider",
    "retryable": false,
    "message": "There is no provider named 'Mr. Johnson'. Ask the caller to confirm the name.",
    "valid_options": ["Dr. Johnson", "Dr. Chen"]
  }
  

  Contoh berikut menunjukkan penanganan saat check_user_account tidak menampilkan kecocokan persis. Hasil yang diharapkan adalah mengubah kueri penelusuran atau mengalihkan kembali kontrol ke pengguna, bukan mencoba lagi:

  def check_user_account(user_name: str, phone_suffix: str):...
  
  # Checked user account but not existing
  # BEFORE: insufficient error information
  {
   "found": false,
   "matches": []
  }
  
  # AFTER: providing sufficient information to the LiveAPI to avoid further retries because the retries have been exhausted.
  {
   "status": "EXHAUSTED",
   "retryable": false,
   "search_criteria": {
     "name": "Alex Rivera",
     "phone_suffix": "4921"
   },
   "search_scope": "Checked active orders, archived accounts, and guest checkouts across all regions.",
   "guidance": "Exhaustive search completed with 0 matches. Do NOT retry with parameter substrings or variations. Inform the user that no account was found matching those details, and ask if they have an Order ID or billing email."
  }
  

• Kebijakan percobaan ulang petunjuk sistem: Lengkapi respons informatif dengan batasan eksplisit dalam petunjuk sistem:

  "When a tool returns no results, tell the user the result before calling the
  tool again. If a call fails for a reason fundamental to the arguments (for
  example, the entity does not exist), do not silently retry with variations;
  ask the user to clarify or confirm. You may broaden a query once when a
  result set is simply empty. Do not run repeated searches with different
  parameters on your own initiative. Hard cap: Never issue more than two
  consecutive function calls without saying something back to the user."
  

Pertukaran histori sesi

Di Audio Native Gemini 2.5 Flash Live API, send_client_content digunakan untuk menyiapkan pengisian histori sebelum giliran pertama, dan untuk menambahkan histori tambahan selama pertengahan sesi.

Di Gemini 3.8 Live, jika Anda ingin menggunakan metode send_client_content untuk menyiapkan pengisian histori, di bagian HistoryConfig pesan penyiapan, tetapkan initial_history_in_client_content=True. Setelah menerima setup_complete. Kemudian, Anda dapat memanggil send_client_content berulang kali untuk membuat histori hingga pesan terakhir tempat turn_complete=True disetel.

Perbedaan perilaku model

Tabel berikut menjelaskan perbedaan perilaku model untuk audio, multimodal, dan output antara Audio Native Gemini 2.5 Flash Live API dan Gemini 3.8 Live:

Kode Python berikut menunjukkan cara menyetel media_resolution dan custom_vocabulary:

# Example: Setting media_resolution for image frames in Gemini 3.8 Live
from google import genai
from google.genai import types

client = genai.Client()

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,  # or MEDIA_RESOLUTION_LOW or MEDIA_RESOLUTION_MEDIUM
)

async with client.aio.live.connect(
    model="gemini-3.8-live",
    config=config,
) as session:
    # Send image frames with the configured resolution budget
    ...


# Example: Setting custom_vocabulary for domain-specific word biasing in Gemini 3.8 Live
from google import genai
from google.genai import types

client = genai.Client()

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    input_audio_transcription=types.AudioTranscriptionConfig(
        custom_vocabulary=["Gemini", "MagicWord", "Lagrangian"],
    ),
)

async with client.aio.live.connect(
    model="gemini-3.8-live",
    config=config,
) as session:
    ...

Kompatibilitas framework pihak ketiga

Bagian berikut menjelaskan cara kerja framework pihak ketiga dengan Gemini 3.8 Live:

LiveKit

Plugin Google RealtimeModel LiveKit mendukung Gemini 3.8 Live, tetapi setelan berikut tidak didukung di plugin Google LiveKit:

• thinking_level
• enable_affective_dialog
• proactivity

Sebaiknya Anda berhati-hati saat menggunakan plugin Google LiveKit, karena memerlukan adaptasi yang cermat agar dapat berfungsi dengan Gemini 3.8 Live.

Pipecat

Pipecat mendukung Gemini 3.8 Live, dengan perubahan berikut:

• Konfigurasi Pemikiran: menghapus level pemikiran karena tidak didukung oleh Gemini 3.8 Live.

• Pipecat menghubungkan endpoint Agent Platform menggunakan GoogleVertexLLMService melalui konektor GeminiLiveLLMService.

Telemetri penggunaan token tingkat kabel

Setiap giliran server menampilkan frame usage_metadata. Hal ini konsisten di seluruh Audio Native Gemini 2.5 Flash Live API dan Gemini 3.8 Live. Metadata penggunaan lebih dikategorikan, seperti token yang di-cache, token penggunaan alat, token dalam berbagai modalitas, dan sebagainya.

Batasan dan mitigasi model yang diketahui

Untuk mengetahui informasi tentang batasan dan mitigasi yang diketahui saat mengembangkan aplikasi dengan Gemini 3.8 Live, lihat Batasan yang diketahui.

Checklist migrasi

Berikut adalah checklist migrasi klien yang dapat Anda gunakan saat melakukan migrasi dari Audio Native Live API Gemini 2.5 Flash ke Gemini 3.8 Live:

• Pemanggilan fungsi:

  • Respons alat yang informatif: Refaktorkan semua pengendali alat untuk menampilkan kode status eksplisit, tanda yang dapat dicoba lagi, dan penjelasan bahasa alami. Jangan pernah menampilkan None kosong atau {} kosong.

  • Kebijakan petunjuk sistem: Menambahkan batasan eksplisit yang melarang percobaan ulang alat secara diam-diam, mewajibkan konfirmasi pengguna jika argumen gagal, dan membatasi panggilan alat berturut-turut.

  • Pencocokan ID panggilan alat: Pastikan FunctionResponse meneruskan id=fc.id di setiap respons alat.

  • Perubahan perilaku penjadwalan fungsi: Saat pengguna berbicara, scheduling=interrupt akan di-downgrade ke scheduling=when_idle untuk memberikan pengalaman pengguna yang lebih lancar.

• Sesi: batasi send_client_content: Gunakan send_client_content untuk menetapkan histori awal dengan memberikan HistoryConfig yang masuk akal.

• Berpikir: hapus peretasan berpikir tingkat perintah: Untuk mencegah audio terputus, hapus semua teks perintah yang mencoba menerapkan skema berpikir langkah demi langkah atau batas token.