Skip to content

实时智能体支持的模型

Supported in ADKPython v0.1.0

实时智能体需要一个能够维持双向连接的模型；标准的 Gemini 模型无法做到。关于 ADK 在实时智能体之外支持的模型，以及非 Gemini 提供商，请参阅智能体模型。

实时模型

实时智能体运行在能够端到端接收音频输入并产生音频输出的模型上，中间没有文本转语音的阶段。这正是它们能够以自然韵律产生类人语音的原因，也是标准 Gemini 模型在双向连接上无法做到的。

模型 AI Studio Agent Platform
Gemini 2.5 Flash Live gemini-2.5-flash-native-audio-preview-12-2025 (Preview) gemini-live-2.5-flash-native-audio (GA)
Gemini 3.1 Flash Live gemini-3.1-flash-live-preview (Preview) 不可用

Gemini 2.5 Flash Live 是同一个模型，只是在两个后端上 ID 不同；功能完全一致。gemini-live-2.5-flash-native-audio 是 ADK 的 LlmAgent.DEFAULT_LIVE_MODEL，也是唯一公开可用的 Live 模型和本节示例中使用的模型。

Gemini 3.1 Flash Live 是更新的模型，延迟更低，但仅在 AI Studio 上可用，且缺少 2.5 的部分功能——切换前请参阅各模型的功能支持。

选择后端

实时模型通过两个后端之一来访问。ADK 使用相同的代码与两个后端通信；你通过环境变量进行切换，因此可以在一个后端上开发，在另一个后端上部署。

AI Studio Agent Platform
全称 Google AI Studio Gemini Enterprise Agent Platform
最适合 原型开发、开发测试 生产环境、企业级
认证 API key (GOOGLE_API_KEY) 云凭据 (GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION)
设置 仅需 API key 云项目设置
限制 会话时长和并发数 会话时长和并发数

通过 GOOGLE_GENAI_USE_ENTERPRISE 环境变量进行切换（FALSE 表示 AI Studio，TRUE 表示 Agent Platform）；无需修改代码。请参阅快速开始进行设置。

Agent Platform：不支持 global 位置

Live 模型在 GOOGLE_CLOUD_LOCATION=global 时不可用。请使用区域端点 （如 us-central1、us-east1 或 asia-northeast1），并在部署前对照 Agent Platform 位置 中的端点位置表进行检查。

这些模型直接生成音频，具有自然韵律，并且能够自动检测对话语言。你在此基础上配置的内容——语音、转录、轮次检测——在配置中有描述。

有一个属性在模型级别固定：实时模型仅生成音频。它们不支持 TEXT 响应模态，因此要在语音的同时获取文本，你需要使用音频转录。

各模型的功能支持

部分 RunConfig 和工具设置取决于你运行的是哪个模型：

功能 Gemini 2.5 Flash Live Gemini 3.1 Flash Live
主动性和情感对话 通过 RunConfig 可选启用 不支持
工具上的 response_scheduling 支持 不支持；函数调用是同步的，模型会保持静默直到你返回工具响应
思维控制 thinking_budget thinking_level（minimal、low、medium、high）

从 2.5 迁移到 3.1

保留 RunConfig.proactivity 或 RunConfig.enable_affective_dialog 设置是最常见的升级失败原因——请移除它们。另外还有两个差异会影响客户端代码：单个服务器事件现在可以同时携带多个内容部分，因此请遍历 event.content.parts 而不是读取 parts[0]；轮次覆盖范围现在默认包含所有检测到的音频活动和视频帧，如果你持续流式传输视频，这会改变 token 成本。参见上游迁移说明。

平台限制和配额

两个后端都对连接和会话的运行时长以及同时运行的会话数量进行了限制。这些数字会变化，因此请以官方文档为准，并在生产环境中依赖某个限制之前进行验证。

限制 AI Studio Agent Platform
会话时长，仅音频 15 分钟 15 分钟
会话时长，音频 + 视频 2 分钟 2 分钟
连接生命周期 约 10 分钟 约 10 分钟
并发会话数 参见速率限制 按量付费每个项目最多 1,000 个；使用 Provisioned Throughput 无限制

Agent Platform 默认还将对话会话限制在 10 分钟，这与上述仅音频的限制是分开的。

启用上下文窗口压缩可以让会话时长超过限制。在 Agent Platform 上，可以通过 Cloud Console 配额页面 中的 "Bidi generate content concurrent requests" 请求增加并发会话数。请根据 AI Studio、Gemini API 速率限制 和 Agent Platform 的文档验证当前的数字。

如何处理模型名称

从环境变量读取模型名称，而不是硬编码。同一个模型在 AI Studio 和 Agent Platform 上有不同的 ID，因此 .env 变量可以让一个代码库同时支持两个后端，并且可以隔离模型弃用的影响。

推荐模式：

import os
from google.adk.agents import Agent

# 使用环境变量，并设置合理的默认值作为回退
agent = Agent(
    name="my_agent",
    model=os.getenv("DEMO_AGENT_MODEL", "gemini-live-2.5-flash-native-audio"),
    tools=[...],
    instruction="..."
)

为什么使用环境变量：

  • 后端特定的 ID：同一个模型在 AI Studio 和 Agent Platform 上的名称不同，因此在它们之间切换意味着要更改模型 ID。使用环境变量可以将此信息从代码中剥离
  • 模型可用性变化：模型会定期发布和弃用。一年前编写的实时智能体不应在代码中绑定到一个已经不存在的模型
  • 环境特定的配置：为开发、预发布和生产环境使用不同的模型

在 .env 文件中配置：

# AI Studio
DEMO_AGENT_MODEL=gemini-2.5-flash-native-audio-preview-12-2025

# AI Studio，如果你不需要主动性、情感对话或非阻塞工具
# DEMO_AGENT_MODEL=gemini-3.1-flash-live-preview

# Agent Platform
# DEMO_AGENT_MODEL=gemini-live-2.5-flash-native-audio

环境变量加载顺序

使用 python-dotenv 的 .env 文件时，你必须在导入任何读取环境变量的模块之前调用 load_dotenv()。否则，os.getenv() 将返回 None 并回退到默认值，忽略你的 .env 配置。

main.py 中的正确顺序：

from dotenv import load_dotenv
from pathlib import Path

# 在导入智能体之前加载 .env 文件
load_dotenv(Path(__file__).parent / ".env")

# 现在可以安全地导入使用环境变量的模块
from google_search_agent.agent import agent

错误顺序（不会生效）：

from dotenv import load_dotenv
from google_search_agent.agent import agent  # 智能体在此处读取环境变量

# 太晚了！智能体已经使用默认模型初始化
load_dotenv(Path(__file__).parent / ".env")

这是 Python 的导入行为：当你导入一个模块时，其顶层代码会立即执行。如果你的智能体模块在导入时调用了 os.getenv("DEMO_AGENT_MODEL")，那么 .env 文件必须已经加载。

选择合适的模型：

  1. 选择后端：原型开发使用 AI Studio，生产环境使用 Agent Platform。这决定了上表中的 ID 列，在 Agent Platform 上也确定了模型——Gemini 2.5 Flash Live 是唯一可用的 Live 模型
  2. 检查当前可用性：请参阅上表中的模型表和官方文档
  3. 配置环境变量：在 .env 文件中设置模型名称，并在构建智能体时从该文件读取

模型兼容性和可用性

有关模型兼容性和可用性的最新信息：

在部署到生产环境之前，请务必在官方文档中验证模型可用性和功能支持情况。