從 Gemini 2.5 Flash Live API Native Audio 遷移至 Gemini 3.8 Live

本文說明從 Gemini 2.5 Flash Live API Native Audio 遷移至 Gemini 3.8 Live 時，需要進行的變更。

函式呼叫變更

Gemini 2.5 Flash Live API Native Audio 伺服器支援非同步工具呼叫。相較之下，Gemini 3.8 Live 支援非同步函式呼叫，並有下列行為異動：

如果函式宣告在設定中宣告 behavior=BLOCKING，Gemini 3.8 Live 就支援封鎖函式呼叫。如果在執行封鎖函式呼叫期間收到新輸入內容，Live API 伺服器就會取消目前的函式呼叫。

scheduling=interrupt選項的 FunctionResponse 變更行為：

`FunctionResponse` 排定時間	誰在說話	Gemini 2.5 Flash Live API 原生音訊	Gemini 3.8 Live
中斷	模型	立即停止使用中的模型回覆；播放工具的回覆。	立即停止使用中的模型回覆；播放工具的回覆。
中斷	使用者	立即中斷，並透過使用者的聲音播放工具的回覆。	等待使用者完成操作，再播放工具的回覆內容。

減少多餘的掃描和函式呼叫重試

如果工具未傳回任何結果，Gemini 3.8 Live 有時會在單一回合中重複呼叫函式。這可能包括重複不同的參數，在回應前掃過兩到五次。這項行為會增加第一個音訊生成時間 (TTFA)，並產生不準確的回溯語音。

Gemini 3.8 Live 嘗試解決查詢時，會導致函式呼叫重複執行。如果工具傳回的結果沒有資訊或空白 (例如 {"results": [], "total_available": 0} 或 None)，模型就無法區分「永久耗盡」、「查詢視窗太窄」或「無效引數」。模型會嘗試擴大或改變查詢，以改善結果，並開始掃描。

請採取下列互補做法：

傳回資訊豐富的函式回應：每個工具回應都必須包含錯誤或結果的相關資訊，引導 Gemini 3.8 Live 模型後續作業。

下表說明各種情況、模型應如何回應，以及協助模型所需的酬載範例：

案件	模型應執行的動作	必要酬載內容
有效查詢，但未傳回任何結果。重試也無法解決問題。	停止搜尋、通知使用者，並提供替代方案。	`status: 'no_results'`、 `retryable: false`、以及清楚的自然語言說明訊息。
引數無效或不存在 (例如「wrong provider」)。	停止搜尋，並請使用者釐清或確認。	`status: 'invalid_argument'`、 `reason_code`、 `retryable: false` 和 `valid_options` 清單
有效查詢，但視窗空白。範圍較廣的查詢確實有幫助。	執行一次合理的重試。	`status: 'no_results_in_range'`、 `retryable: true`和 `retry_hint`

以下範例顯示酬載範例，其中會呼叫 search_appointment，但所有可能日期都無法預訂。使用者希望試用供應商，而不是掃描日期：

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"]
}

以下範例說明 check_user_account 未傳回完全相符結果時的處理方式。預期結果是修改搜尋查詢或將控制權轉移回使用者，而不是重試：

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."
}

系統指令重試政策：在系統指令中加入明確限制，補充資訊豐富的回覆內容：

"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."

工作階段記錄交換

在 Gemini 2.5 Flash Live API Native Audio 中，send_client_content 用於在第一輪之前設定記錄播種，以及在會期中新增額外記錄。

在 Gemini 3.8 Live 中，如要使用 send_client_content 方法設定記錄播種，請在設定訊息的 HistoryConfig 部分中設定 initial_history_in_client_content=True。收到 setup_complete 後。然後重複呼叫 send_client_content，直到最後一則訊息設定 turn_complete=True 為止，即可建構記錄。

模型行為差異

下表說明 Gemini 2.5 Flash Live API Native Audio 和 Gemini 3.8 Live 在音訊、多模態和輸出方面的模型行為差異：

功能	Gemini 2.5 Flash Live API 原生音訊	Gemini 3.8 Live
情緒感知對話	透過 `enable_affective_dialog` 旗標支援。	預設為啟用。
主動式音訊	透過 `proactivity` 標記支援。	預設為啟用。
圖片或影片影格權杖	降低每影格的預設預算。	傳遞圖片影格時，一律支援 `media_resolution`。可讓您權衡成本與準確度。
轉錄稿和內容	穩定的基準轉錄內容。	您可以新增 `custom_vocabulary`，為特定領域的字詞提供自訂調整，以提高準確率。

下列 Python 程式碼示範如何設定 media_resolution 和 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:
    ...

第三方架構相容性

以下各節說明第三方架構如何與 Gemini 3.8 Live 搭配運作：

LiveKit

LiveKit 的 Google 外掛程式 RealtimeModel 支援 Gemini 3.8 Live，但 LiveKit 的 Google 外掛程式不支援下列設定：

thinking_level
enable_affective_dialog
proactivity

建議您使用 LiveKit 的 Google 外掛程式時格外謹慎，因為必須仔細調整，才能與 Gemini 3.8 Live 搭配使用。

Pipecat

Pipecat 支援 Gemini 3.8 Live，並進行下列變更：

思考設定：移除思考程度，因為 Gemini 3.8 Live 不支援這項設定。
Pipecat 會透過 GeminiLiveLLMService 連接器使用 GoogleVertexLLMService 連線至 Agent Platform 端點。

線路層級的權杖用量遙測

每個伺服器回合都會傳回 usage_metadata 頁框。這項設定在 Gemini 2.5 Flash Live API Native Audio 和 Gemini 3.8 Live 中皆一致。使用量中繼資料的分類更細，例如快取權杖、工具使用權杖、不同模式的權杖等。

已知模型限制和解決方法

如要瞭解使用 Gemini 3.8 Live 開發應用程式時的已知限制和解決方法，請參閱「已知限制」。

遷移工作檢查清單

以下是從 Gemini 2.5 Flash Live API Native Audio 遷移至 Gemini 3.8 Live 時可使用的用戶端遷移檢查清單：

呼叫函式：
- 提供實用資訊的工具回應：重構所有工具處理常式，傳回明確的狀態碼、可重試的旗標和自然語言說明。請勿傳回空白 None 或空值 {}。
- 系統指令政策：新增明確限制，禁止無聲工具重試、要求使用者確認引數失敗，以及限制連續工具呼叫次數。
- 工具呼叫 ID 比對：請確保 FunctionResponse 會在每次工具回覆時傳遞 id=fc.id。
- 函式排程行為變更：使用者說話時，scheduling=interrupt 會降級為 scheduling=when_idle，提供更流暢的使用者體驗。
工作階段：限制 send_client_content：使用 send_client_content，透過提供合理的 HistoryConfig 設定初始記錄。
思考：清除提示層級的思考捷徑：為避免音訊中斷，請移除所有嘗試強制執行逐步思考架構或權杖限制的提示文字。