从 Gemini 2.5 Flash Live API Native Audio 迁移到 Gemini 3.8 Live

本文档介绍了从 Gemini 2.5 Flash Live API 原生音频迁移到 Gemini 3.8 Live 时需要进行的更改。

函数调用方面的变化

Gemini 2.5 Flash Live API 原生音频服务器支持异步工具调用。相比之下，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`、以及清晰的说明性自然语言消息。
实参无效或不存在（例如“提供方错误”）。	停止搜索，并要求用户澄清或确认。	`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 端点。

线级 token 使用情况遥测

每个服务器回合都会返回一个 usage_metadata 帧。这在 Gemini 2.5 Flash Live API Native Audio 和 Gemini 3.8 Live 中是一致的。使用情况元数据更加细化，例如缓存的 token、工具使用 token、不同模态的 token 等等。

已知模型限制和缓解措施

如需了解使用 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 来设置初始历史记录。
思考：清除提示级思考技巧：为防止音频丢失，请移除所有尝试强制执行逐步思考架构或令牌限制的提示文本。