Gemini 3.8 Live 开发者指南

Gemini 3.8 Live 是一款实时对话模型,专为低延迟双向语音和视频互动以及面对面实时虚拟形象合成而构建。3.8 Live 专为连续对话工作流而设计,提供默认启用的情感对话、主动音频过滤、自动取消屏蔽工具和动态多语言切换功能。

本文档介绍了以下主题:

  • 3.8 Live 在 Gemini 模型系列中的定位。
  • 3.8 Live 的主要功能。
  • 与 Google Gen AI SDK 集成。
  • 必需的 API 规则和惯例。
  • 从早期 Gemini Live API 模型迁移。

在 Gemini 系列中的角色

3.8 Live 专为实时流式传输互动而设计。它通过双向 WebSocket 运行,以亚秒级延迟处理语音、实时摄像头画面和屏幕广播,同时生成 24 kHz 音频和同步的 24 FPS 视频头像。

模型规格和比较

下表比较了 3.8 Live 和早期 Gemini Live API 模型的规格:

属性 Gemini 3.8 Live Gemini 2.5 Flash Live API 原生音频(正式版基准)
模型 ID gemini-3.8-live gemini-live-2.5-flash-native-audio
发布阶段 正式版 (GA) 正式版 (GA)
输入模态 音频(16 kHz PCM)、视频(1 FPS JPEG)、文本 音频(16 kHz PCM)、视频(1 FPS JPEG)、文本
输出模态 音频(24 kHz PCM)、视频(24 FPS MP4 实时虚拟形象)、文本 音频(24 kHz PCM)、文本
实时虚拟形象合成 24 FPS 同步视频输出 不支持
共情对话 默认处于启用状态 需要明确配置
主动音频 默认处于启用状态 需要明确配置
函数调用执行 异步非阻塞和自动取消阻塞 (behavior="BLOCKING") 异步和同步
打断处理 礼貌插话降级(在用户说话时等待) 立即中断(可与用户音频重叠)
语言支持 在支持的语言之间动态切换 支持的语言
网域偏向 支持AudioTranscriptionConfig中的 custom_vocabulary 标准基准转写
视觉标记控件 可配置的 media_resolution(LOW、MEDIUM、HIGH) 每帧固定 token 预算

Gemini 3.8 Live 的适用场景

在以下场景中使用 3.8 Live:

  • 您需要实现低对话延迟、自然轮替,以及在用户打断(插话)时快速恢复。
  • 您的应用会调用外部工具,并且需要非阻塞执行,以便在后端系统处理请求时继续输出音频。
  • 您希望在不使用外部渲染流水线的情况下,以 24 FPS 的帧率渲染具有同步面部动画和对口型功能的说话数字虚拟形象。
  • 您的用户使用多种语言进行对话,因此需要进行中途语言检测并在支持的语言之间切换。
  • 您需要针对技术术语、SKU 或品牌名称进行特定领域的词汇偏置。

如需了解完整规范和配额限制,请参阅 3.8 Live 模型页面。

Gemini 3.8 Live 的主要功能

3.8 Live 引入了以下功能:

  • 24 FPS 实时虚拟形象视频合成:3.8 Live 直接根据模型输出生成同步的 24 FPS MP4 视频流 (response_modalities=["VIDEO"])。生成的面部表情和嘴唇动作会与合成语音实时同步。

    您可以使用预构建的库存头像或提供自定义参考图片,来构建数字管家、客服智能体、虚拟导师或互动角色。如需了解设置详情,请参阅配置实时虚拟形象。

  • 默认启用的共情对话和主动音频:

    • 共情对话:在 3.8 Live 中默认启用。该模型会处理用户音频输入中的声学韵律、语音提示、停顿和语音语调,以调整语音语调和对话节奏。
    • 主动音频:在 3.8 Live 中默认处于启用状态。该模型会过滤环境噪音和背景语音,仅在用户发出指令时生成音频回答。
  • 异步和自动取消屏蔽函数调用:3.8 Live 提供了专为实时语音设计的工具调用行为:

    • 非阻塞异步执行:当模型生成工具调用时,音频会话会保持活跃状态,以便智能体在客户端应用调用后端 API 时,流式传输对话确认(“让我调出您的账号详细信息…”)并处理后续输入。
    • 自动取消阻塞调用 (behavior="BLOCKING"):当函数声明设置 behavior="BLOCKING" 时,生成操作会暂停,直到收到工具回答。如果在阻塞调用运行期间有新的用户输入,Gemini Live API 服务器会取消待处理的调用。
    • 礼貌插话处理:在早期模型中,当用户说话时,如果返回包含 scheduling="INTERRUPT" 的工具回答,则会与用户音频重叠。在 3.8 Live 中,当用户正在说话时,服务器会将时间表降级为 WHEN_IDLE,并在用户说完后播放回答。
  • 动态多语言切换和自定义词汇表:

    • 多语言支持:在会话期间检测并切换支持的语言,无需重启或重新配置连接。
    • 自定义词汇偏向:使用 custom_vocabulary 接受 AudioTranscriptionConfig(通过 input_audio_transcription)中特定领域的关键字、专有名词、医学术语和产品代码,以提高转录准确率。
  • 具有 media_resolution 控制的多模态视觉定位:接受实时视频流(1 FPS JPEG 帧,建议分辨率为 768x768),并允许您配置 media_resolution(MEDIA_RESOLUTION_LOW、MEDIA_RESOLUTION_MEDIUM、MEDIA_RESOLUTION_HIGH),以平衡每帧 token 使用量和视觉细节。

快速入门

在开始之前,请使用应用默认凭证 (ADC) 向 Google Cloud 进行身份验证。

在以下代码示例中,将 PROJECT_ID 替换为您的 Google Cloud 项目 ID。

安装 SDK

安装或更新 Google Gen AI SDK 和音频依赖项:

pip install --upgrade google-genai websockets numpy

启动具有异步工具调用的双向会话

以下示例展示了如何与 gemini-3.8-live 建立实时会话、选择预构建的声音 (Aoede)、配置自定义词汇偏好,以及运行非阻塞异步函数调用:

import asyncio
from google import genai
from google.genai import types

PROJECT_ID = "PROJECT_ID"
LOCATION = "us-central1"
MODEL_ID = "gemini-3.8-live"

# Initialize the Gen AI client for enterprise.
client = genai.Client(enterprise=True, project=PROJECT_ID, location=LOCATION)

# Define a tool for asynchronous execution.
order_lookup_tool = types.FunctionDeclaration(
    name="lookup_order_status",
    description="Fetches real-time shipping status for a customer order ID.",
    parameters=types.Schema(
        type="OBJECT",
        properties={
            "order_id": types.Schema(
                type="STRING",
                description="The order ID, for example, ORD-8472",
            ),
        },
        required=["order_id"],
    ),
)

# Configure the live connection.
config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    system_instruction=types.Content(
        parts=[
            types.Part.from_text(
                text=(
                    "You are an enterprise concierge. When you call a tool, "
                    "briefly acknowledge the request and tell the user what you're doing. "
                    "If a tool returns no results, inform the user before trying again. "
                    "Never issue more than two consecutive tool calls without speaking."
                )
            )
        ]
    ),
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Aoede")
        ),
    ),
    input_audio_transcription=types.AudioTranscriptionConfig(
        custom_vocabulary=["ORD-8472", "Gemini Live", "Express Shipping"]
    ),
    output_audio_transcription=types.AudioTranscriptionConfig(),
    tools=[types.Tool(function_declarations=[order_lookup_tool])],
)

async def handle_tool_call(session, function_call):
    """Executes backend calls asynchronously without blocking incoming audio."""
    order_id = function_call.args.get("order_id", "")
    await asyncio.sleep(2.0)  # Simulate backend API latency.

    if not order_id.startswith("ORD-"):
        result = {
            "status": "invalid_argument",
            "retryable": False,
            "message": f"Order ID '{order_id}' is invalid. Ask the user to verify.",
        }
    else:
        result = {
            "status": "ok",
            "retryable": False,
            "order_id": order_id,
            "shipping_status": "Out for delivery by 4:00 PM",
        }

    # Send tool response matching the call ID.
    await session.send_tool_response(
        function_responses=[
            types.FunctionResponse(
                id=function_call.id,
                name=function_call.name,
                response=result,
            )
        ]
    )

async def main():
    async with client.aio.live.connect(model=MODEL_ID, config=config) as session:
        print(f"Connected to {MODEL_ID}")

        # Send initial text or stream 16 kHz PCM audio chunks.
        await session.send_realtime_input(
            text="Hi! Can you check the status of order ORD-8472?"
        )

        async for message in session.receive():
            # Handle asynchronous tool calls.
            if message.tool_call:
                for call in message.tool_call.function_calls:
                    asyncio.create_task(handle_tool_call(session, call))

            # Process audio output chunks and transcriptions.
            if message.server_content:
                if (
                    message.server_content.output_transcription
                    and message.server_content.output_transcription.text
                ):
                    print(
                        f"Agent: {message.server_content.output_transcription.text}",
                        end="",
                        flush=True,
                    )

if __name__ == "__main__":
    asyncio.run(main())

必需的 API 规则和惯例

使用 3.8 Live 进行构建时,请遵循以下 API 惯例:

  • 提供有用的函数响应:不要从工具处理程序返回空字典 ({}) 或 None。当工具返回错误或空载荷时,3.8 Live 可能会生成带有修改后参数的重复函数调用,除非响应中包含状态字段。在每个工具响应中返回结构化字段:
    • status:机器可读的状态字符串,例如 "ok"、"no_results" 或 "invalid_argument"。
    • retryable:如果重复调用会返回相同的结果,则设置为 false。
    • message 或 guidance:用于指定要向用户报告的状态的文本。
  • 提示级工具重试限制:在 system_instruction 中添加重试限制。例如:“如果工具调用未返回任何结果, 请告知用户,而不是使用不同的参数重复搜索。 在未与用户对话的情况下,连续运行的工具调用不得超过两次。”
  • 严格 FunctionResponse 匹配:
    • 每个 FunctionResponse 轮次都必须提供前一个 FunctionCall 中的确切 id。
    • 直接在 FunctionResponse.response 中传递响应对象。
  • 流式音频格式:
    • 输入音频:16 kHz、16 位、小端序、单声道 PCM (audio/pcm;rate=16000),以 20 毫秒到 100 毫秒的数据块进行流式传输。
    • 输出音频:24 kHz 单声道 PCM。
  • 移除了旧版参数:请勿在配置中传递 enable_affective_dialog 或 proactivity;这些功能在 3.8 Live 中默认处于启用状态。
  • 播种对话记录:如果您使用 send_client_content 播种多轮对话记录,请等到客户端应用收到 setup_complete 服务器帧并配置 HistoryConfig(initial_history_in_client_content=True)。

迁移到 Gemini 3.8 Live

如需详细了解如何从 gemini-live-2.5-flash-native-audio 迁移到 gemini-3.8-live,请参阅从 Gemini 2.5 Flash Live API Native Audio 迁移到 Gemini 3.8 Live。

开发者核对清单

在部署应用之前,请验证以下各项:

其他资源

如需了解详情,请参阅以下资源: