第 4 部分：理解 RunConfig¶

在第 3 部分中，你学习了如何处理来自 run_live() 的事件以处理模型响应、工具调用和流式更新。本部分向你展示如何通过 RunConfig 配置这些流式会话——控制响应格式、管理会话生命周期以及实施生产约束。

你将学到什么：本部分涵盖响应模态及其约束、探讨 BIDI 和 SSE 流式模式之间的差异、检查 ADK 会话与 Live API 会话之间的关系，并展示如何通过会话恢复和上下文窗口压缩管理会话持续时间。你将了解如何处理并发会话配额、实现配额管理的架构模式，并通过 max_llm_calls 和音频持久化选项配置成本控制。通过掌握 RunConfig，你可以构建生产就绪的流式应用程序，在功能丰富性与操作约束之间取得平衡。

了解更多

有关与音频/视频相关的 RunConfig 配置的详细信息，请参见第 5 部分：Live API 中的音频、图像和视频。

RunConfig 参数快速参考¶

本表提供了本部分涵盖的所有 RunConfig 参数的快速参考：

参数	类型	目的	平台支持	参考
response_modalities	list[str]	控制输出格式（TEXT 或 AUDIO）	两者	详情
streaming_mode	StreamingMode	选择 BIDI 或 SSE 模式	两者	详情
session_resumption	SessionResumptionConfig	启用自动重新连接	两者	详情
context_window_compression	ContextWindowCompressionConfig	无限会话持续时间	两者	详情
max_llm_calls	int	限制每个会话的总 LLM 调用	两者	详情
save_live_blob	bool	持久化音频/视频流	两者	详情
custom_metadata	dict[str, Any]	将元数据附加到调用事件	两者	详情
support_cfc	bool	启用组合函数调用	Gemini（仅限 2.x 模型）	详情
speech_config	SpeechConfig	语音和语言配置	两者	第 5 部分：语音配置
input_audio_transcription	AudioTranscriptionConfig	转录用户语音	两者	第 5 部分：音频转录
output_audio_transcription	AudioTranscriptionConfig	转录模型语音	两者	第 5 部分：音频转录
realtime_input_config	RealtimeInputConfig	VAD 配置	两者	第 5 部分：语音活动检测
proactivity	ProactivityConfig	启用主动音频	Gemini（仅限原生音频）	第 5 部分：主动性和情感对话
enable_affective_dialog	bool	情感适应	Gemini（仅限原生音频）	第 5 部分：主动性和情感对话

源引用

run_config.py

平台支持图例：

两者：在 Gemini Live API 和 Vertex AI Live API 上均受支持
Gemini：仅在 Gemini Live API 上受支持
特定于模型：需要特定的模型架构（例如，原生音频）

导入路径：

上表中引用的所有配置类型类均从 google.genai.types 导入：

from google.genai import types
from google.adk.agents.run_config import RunConfig, StreamingMode

# 配置类型通过 types 模块访问
run_config = RunConfig(
    session_resumption=types.SessionResumptionConfig(),
    context_window_compression=types.ContextWindowCompressionConfig(...),
    speech_config=types.SpeechConfig(...),
    # 等等
)

RunConfig 类本身和 StreamingMode 枚举从 google.adk.agents.run_config 导入。

响应模态¶

响应模态控制模型如何生成输出——作为文本或音频。Gemini Live API 和 Vertex AI Live API 都有相同的限制：每个会话只有一个响应模态。

配置：

# 第 2 阶段：会话初始化 - RunConfig 决定流式行为

# 默认行为：ADK 在未指定时自动将 response_modalities 设置为 ["AUDIO"]
# （原生音频模型需要）
run_config = RunConfig(
    streaming_mode=StreamingMode.BIDI  # 双向 WebSocket 通信
)

# 上面等同于：
run_config = RunConfig(
    response_modalities=["AUDIO"],  # 由 ADK 在 run_live() 中自动设置
    streaming_mode=StreamingMode.BIDI  # 双向 WebSocket 通信
)

# ✅ 正确：仅文本响应
run_config = RunConfig(
    response_modalities=["TEXT"],  # 模型仅以文本响应
    streaming_mode=StreamingMode.BIDI  # 仍然使用双向流式处理
)

# ✅ 正确：仅音频响应（显式）
run_config = RunConfig(
    response_modalities=["AUDIO"],  # 模型仅以音频响应
    streaming_mode=StreamingMode.BIDI  # 双向 WebSocket 通信
)

Gemini Live API 和 Vertex AI Live API 都将会话限制为单个响应模态。尝试同时使用两者将导致 API 错误：

# ❌ 不正确：不支持同时使用两种模态
run_config = RunConfig(
    response_modalities=["TEXT", "AUDIO"],  # 错误：不能同时使用
    streaming_mode=StreamingMode.BIDI
)
# 来自 Live API 的错误："Only one response modality is supported per session"

默认行为：

当未指定 response_modalities 时，ADK 的 run_live() 方法会自动将其设置为 ["AUDIO"]，因为原生音频模型需要显式的响应模态。如果需要，你可以通过显式设置 response_modalities=["TEXT"] 来覆盖此设置。

关键约束：

你必须在会话开始时选择 TEXT 或 AUDIO。不能在会话中途切换模态
对于原生音频模型，你必须选择 AUDIO。如果你想从原生音频模型接收音频和文本响应，请使用音频转录功能，该功能提供音频输出的文本转录。有关详细信息，请参阅音频转录
响应模态仅影响模型输出——你始终可以发送文本、语音或视频输入（如果模型支持这些输入模态），无论选择的响应模态如何

StreamingMode：BIDI 或 SSE¶

ADK 支持两种不同的流式模式，它们使用不同的 API 端点和协议：

StreamingMode.BIDI：ADK 使用 WebSocket 连接到 Live API（通过 live.connect() 的双向流式端点）
StreamingMode.SSE：ADK 使用 HTTP 流式传输连接到 标准 Gemini API（通过 generate_content_async() 的一元/流式端点）

“Live API”专门指双向 WebSocket 端点 (live.connect())，而“Gemini API”或“标准 Gemini API”指传统的基于 HTTP 的端点 (generate_content() / generate_content_async())。两者都是更广泛的 Gemini API 平台的一部分，但使用不同的协议和功能。

注意： 这些模式指的是 ADK 到 Gemini API 的通信协议，而不是你的应用程序的面向客户端的架构。你可以使用任一模式为你的客户端构建 WebSocket 服务器、REST API、SSE 端点或任何其他架构。

本指南重点介绍 StreamingMode.BIDI，这是实时音频/视频交互和 Live API 功能所必需的。但是，了解 BIDI 和 SSE 模式之间的差异以选择适合你用例的方法是值得的。

配置：

from google.adk.agents.run_config import RunConfig, StreamingMode

# 用于实时音频/视频的 BIDI 流式处理
run_config = RunConfig(
    streaming_mode=StreamingMode.BIDI,
    response_modalities=["AUDIO"]  # 支持音频/视频模态
)

# 用于基于文本的交互的 SSE 流式处理
run_config = RunConfig(
    streaming_mode=StreamingMode.SSE,
    response_modalities=["TEXT"]  # 仅文本模态
)

协议和实现差异¶

这两种流式模式在通信模式和功能上存在根本差异。BIDI 模式启用真正的双向通信，你可以在接收模型响应的同时发送新输入，而 SSE 模式遵循传统的请求-响应模式，你发送完整的请求并流式传回响应。

StreamingMode.BIDI - 双向 WebSocket 通信：

BIDI 模式建立持久的 WebSocket 连接，允许同时发送和接收。这启用了实时功能，如中断、实时音频流和立即轮流：

sequenceDiagram
    participant App as 你的应用程序
    participant ADK as ADK
    participant Queue as LiveRequestQueue
    participant Gemini as Gemini Live API

    Note over ADK,Gemini: "协议：WebSocket"

    App->>ADK: runner.run_live(run_config)
    ADK->>Gemini: live.connect() - WebSocket
    activate Gemini

    Note over ADK,Queue: "可以在接收时发送"

    App->>Queue: send_content(text)
    Queue->>Gemini: "→ 内容（通过 WebSocket）"
    App->>Queue: send_realtime(audio)
    Queue->>Gemini: "→ 音频 blob（通过 WebSocket）"

    Gemini-->>ADK: "← 部分响应 (partial=True)"
    ADK-->>App: "← 事件：部分文本/音频"
    Gemini-->>ADK: "← 部分响应 (partial=True)"
    ADK-->>App: "← 事件：部分文本/音频"

    App->>Queue: send_content(interrupt)
    Queue->>Gemini: "→ 新内容"

    Gemini-->>ADK: ← turn_complete=True
    ADK-->>App: "← 事件：回合完成"

    deactivate Gemini

    Note over ADK,Gemini: "回合检测：turn_complete 标志"

StreamingMode.SSE - 单向 HTTP 流式传输：

SSE（服务器发送事件）模式使用 HTTP 流式传输，你预先发送完整的请求，然后作为块流接收响应。这是一种更简单、更传统的模式，适用于基于文本的聊天应用程序：

sequenceDiagram
    participant App as 你的应用程序
    participant ADK as ADK
    participant Gemini as Gemini API

    Note over ADK,Gemini: "协议：HTTP"

    App->>ADK: runner.run(run_config)
    ADK->>Gemini: generate_content_stream() - HTTP
    activate Gemini

    Note over ADK,Gemini: "请求发送完毕，然后流式传输响应"

    Gemini-->>ADK: "← 部分块 (partial=True)"
    ADK-->>App: "← 事件：部分文本"
    Gemini-->>ADK: "← 部分块 (partial=True)"
    ADK-->>App: "← 事件：部分文本"
    Gemini-->>ADK: "← 部分块 (partial=True)"
    ADK-->>App: "← 事件：部分文本"

    Gemini-->>ADK: "← 最终块 (finish_reason=STOP)"
    ADK-->>App: "← 事件：完整响应"

    deactivate Gemini

    Note over ADK,Gemini: "回合检测：finish_reason"

Progressive SSE Streaming¶

Progressive SSE streaming 是一个实验性功能，可增强 SSE 模式传递流式响应的方式。启用后，此功能通过以下方式改进响应聚合：

内容排序保留：保持混合内容类型的原始顺序（文本、函数调用、内联数据）
智能文本合并：仅合并相同类型的连续文本部分（常规文本与思考文本）
渐进式交付：将所有中间块标记为 partial=True，最后有一个最终聚合响应
延迟函数执行：跳过在部分事件中执行函数调用，仅在最终聚合事件中执行它们以避免重复执行

启用功能：

这是一个实验性（WIP 阶段）功能，默认情况下禁用。通过环境变量启用：

export ADK_ENABLE_PROGRESSIVE_SSE_STREAMING=1

何时使用：

你正在使用 StreamingMode.SSE 并需要更好地处理混合内容类型（文本 + 函数调用）
你的响应包括与常规文本混合的思考文本（扩展思考）
你希望确保函数调用在完整响应聚合后只执行一次

注意： 此功能仅影响 StreamingMode.SSE。它不适用于 StreamingMode.BIDI（本指南的重点），后者使用 Live API 的原生双向协议。

何时使用每种模式¶

你在 BIDI 和 SSE 之间的选择取决于你的应用程序要求和需要支持的交互模式。以下是一个实用指南，帮助你选择：

在以下情况下使用 BIDI：

构建具有实时交互的语音/视频应用程序
需要双向通信（边接收边发送）
需要 Live API 功能（音频转录、VAD、主动性、情感对话）
支持中断和自然的轮流对话（参见第 3 部分：处理中断标志）
实现实时流式工具或实时数据馈送
可以规划并发会话配额（50-1,000 个会话，取决于平台/层级）

在以下情况下使用 SSE：

构建基于文本的聊天应用程序
标准请求/响应交互模式
使用不支持 Live API 的模型（例如，Gemini 1.5 Pro、Gemini 1.5 Flash）
无需 WebSocket 要求的简单部署
需要更大的上下文窗口（Gemini 1.5 支持最多 2M 令牌）
优先选择标准 API 速率限制（RPM/TPM）而不是并发会话配额

流式模式和模型兼容性

SSE 模式通过 HTTP 流式传输使用标准 Gemini API (generate_content_async)，而 BIDI 模式通过 WebSocket 使用 Live API (live.connect())。Gemini 1.5 模型 (Pro, Flash) 不支持 Live API 协议，因此必须与 SSE 模式一起使用。Gemini 2.0/2.5 Live 模型支持这两种协议，但通常与 BIDI 模式一起使用以访问实时音频/视频功能。

通过 SSE 访问的标准 Gemini 模型（1.5 系列）¶

虽然本指南重点介绍使用 Gemini 2.0 Live 模型的双向流式处理，但 ADK 也通过 SSE 流式传输支持 Gemini 1.5 模型系列。这些模型提供了不同的权衡——更大的上下文窗口和经过验证的稳定性，但没有实时音频/视频功能。以下是 1.5 系列通过 SSE 访问时支持的功能：

模型：

gemini-1.5-pro
gemini-1.5-flash

支持：

✅ 文本输入/输出 (response_modalities=["TEXT"])
✅ SSE 流式传输 (StreamingMode.SSE)
✅ 具有自动执行功能的函数调用
✅ 大上下文窗口（1.5-pro 高达 2M 令牌）

不支持：

❌ Live audio features (audio I/O, transcription, VAD)
❌ Bidi-streaming via run_live()
❌ Proactivity and affective dialog
❌ Video input

Understanding Live API Connections and Sessions¶

When building ADK Bidi-streaming applications, it's essential to understand how ADK manages the communication layer between itself and the Live API backend. This section explores the fundamental distinction between connections (the WebSocket transport links that ADK establishes to Live API) and sessions (the logical conversation contexts maintained by Live API). Unlike traditional request-response APIs, the Bidi-streaming architecture introduces unique constraints: connection timeouts, session duration limits that vary by modality (audio-only vs audio+video), finite context windows, and concurrent session quotas that differ between Gemini Live API and Vertex AI Live API.

ADK `Session` vs Live API 会话¶

理解 ADK Session 和 Live API 会话 之间的区别对于构建可靠的 ADK 双向流式应用程序至关重要。

ADK Session (由 SessionService 管理)： - 通过 SessionService.create_session() 创建的持久对话存储，用于对话历史记录、事件和状态 - 存储选项：内存中、数据库 (PostgreSQL/MySQL/SQLite) 或 Vertex AI - 在多个 run_live() 调用和应用程序重启之间持续存在（使用持久的 SessionService）

Live API 会话（由 Live API 后端管理）： - 在 run_live() 事件循环运行时由 Live API 维护，并在通过调用 LiveRequestQueue.close() 结束流式传输时销毁 - 受平台持续时间限制，并且可以使用会话恢复句柄跨多个连接恢复（见下文 ADK 如何管理会话恢复）

它们如何协同工作：

当调用 run_live() 时：
从 SessionService 检索 ADK Session
使用来自 session.events 的对话历史记录初始化 Live API 会话
与 Live API 后端双向流式传输事件
随着新事件的发生更新 ADK Session
当 run_live() 结束时
Live API 会话终止
ADK Session 持久存在
当再次调用 run_live() 或 应用程序重新启动时：
- ADK 从 ADK Session 加载历史记录
- 使用该上下文创建一个新的 Live API 会话

简而言之，ADK Session 提供持久的长期对话存储，而 Live API 会话是短暂的流式上下文。这种分离使生产应用程序能够跨网络中断、应用程序重启和多个流式会话保持对话连续性。

下图说明了 ADK 会话持久性和短暂 Live API 会话上下文之间的关系，显示了如何跨多个 run_live() 调用维护对话历史记录：

sequenceDiagram
    participant App as 你的应用程序
    participant SS as SessionService
    participant ADK_Session as ADK 会话<br/>(持久存储)
    participant ADK as ADK (run_live)
    participant LiveSession as Live API 会话<br/>(短暂)

    Note over App,LiveSession: "第一次 run_live() 调用"

    App->>SS: get_session(user_id, session_id)
    SS->>ADK_Session: "加载会话数据"
    ADK_Session-->>SS: "包含事件历史的会话"
    SS-->>App: "会话对象"

    App->>ADK: runner.run_live(...)
    ADK->>LiveSession: "使用来自 ADK 会话的历史记录初始化"
    activate LiveSession

    Note over ADK,LiveSession: "双向流式传输..."

    ADK->>ADK_Session: "使用新事件更新"

    App->>ADK: queue.close()
    ADK->>LiveSession: "终止"
    deactivate LiveSession
    Note over LiveSession: "Live API 会话已销毁"
    Note over ADK_Session: "ADK 会话持久存在"

    Note over App,LiveSession: "第二次 run_live() 调用（或重启后）"

    App->>SS: get_session(user_id, session_id)
    SS->>ADK_Session: "加载会话数据"
    ADK_Session-->>SS: "包含事件历史的会话"
    SS-->>App: "会话对象（包含以前的历史记录）"

    App->>ADK: runner.run_live(...)
    ADK->>LiveSession: "使用完整历史记录初始化新会话"
    activate LiveSession

    Note over ADK,LiveSession: "双向流式传输继续..."

关键见解： - ADK 会话在多个 run_live() 调用和应用程序重启之间持续存在 - Live API 会话是短暂的——每个流式会话都会创建和销毁 - 对话连续性通过 ADK 会话的持久存储来维持 - SessionService 管理持久层（内存中、数据库或 Vertex AI）

现在我们了解了 ADK Session 对象和 Live API 会话之间的区别，让我们专注于 Live API 连接和会话——支持实时双向流式传输的后端基础设施。

Live API 连接和会话¶

理解 Live API 级别连接和会话之间的区别对于构建可靠的 ADK 双向流式应用程序至关重要。

连接：ADK 和 Live API 服务器之间的物理 WebSocket 链接。这是承载双向流式数据的网络传输层。

会话：Live API 维护的逻辑对话上下文，包括对话历史记录、工具调用状态和模型上下文。一个会话可以跨越多个连接。

方面	连接	会话
是什么？	WebSocket 网络连接	逻辑对话上下文
范围	传输层	应用层
可以跨越？	单个网络链路	通过恢复跨越多个连接
故障影响	网络错误或超时	丢失对话历史记录

各平台的 Live API 连接和会话限制¶

了解每个平台的约束对于生产规划至关重要。Gemini Live API 和 Vertex AI Live API 有不同的限制，影响对话可以运行多长时间以及多少用户可以同时连接。最重要的区别是 连接持续时间（单个 WebSocket 连接保持打开的时间）和 会话持续时间（逻辑对话可以持续的时间）。

约束类型	Gemini Live API (Google AI Studio)	Vertex AI Live API (Google Cloud)	备注
连接持续时间	~10 分钟	未单独记录	每个 Gemini WebSocket 连接自动终止；ADK 通过会话恢复透明地重新连接
会话持续时间（仅音频）	15 分钟	10 分钟	无上下文窗口压缩的最大会话持续时间。两个平台：启用上下文窗口压缩后无限制
会话持续时间（音频 + 视频）	2 分钟	10 分钟	Gemini 对视频有更短的限制；Vertex 平等对待所有会话。两个平台：启用上下文窗口压缩后无限制
并发会话	50 (Tier 1) 1,000 (Tier 2+)	高达 1,000	Gemini 限制因 API 层级而异；Vertex 限制是每个 Google Cloud 项目

源引用

Live API 会话恢复¶

默认情况下，Live API 将连接持续时间限制为大约 10 分钟——每个 WebSocket 连接在此持续时间后自动关闭。为了克服此限制并启用更长时间的对话，Live API 提供了会话恢复，这是一项透明地跨多个连接迁移会话的功能。启用后，Live API 生成恢复句柄，允许重新连接到相同的会话上下文，保留完整的对话历史记录和状态。

ADK 完全自动化了这一点：当你在 RunConfig 中启用会话恢复时，ADK 会自动处理所有重新连接逻辑——检测连接关闭、缓存恢复句柄并在后台无缝重新连接。你不需要编写任何重新连接代码。会话无缝地持续超过 10 分钟的连接限制，自动处理连接超时、网络中断和计划的重新连接。

ADK 重新连接管理的范围¶

ADK 管理 ADK 到 Live API 的连接（ADK 和 Gemini/Vertex Live API 后端之间的 WebSocket）。这对你的应用程序代码是透明的。

你的应用程序仍然负责：

管理到你的应用程序的客户端连接（例如，用户的 WebSocket 到你的 FastAPI 服务器）
如果需要，实施客户端重新连接逻辑
处理客户端和你的应用程序之间的网络故障

当 ADK 重新连接到 Live API 时，你的应用程序的事件循环继续正常运行——你继续从 run_live() 接收事件而不会中断。从你的应用程序的角度来看，Live API 会话无缝继续。

配置：

from google.genai import types

run_config = RunConfig(
    session_resumption=types.SessionResumptionConfig()
)

何时不启用会话恢复：

虽然建议对大多数生产应用程序使用会话恢复，但在以下情况下你可能不需要它：

短会话（<10 分钟）：如果你的会话通常在 ~10 分钟连接超时内完成，恢复会增加不必要的开销
无状态交互：每个回合都独立的请求-响应式交互不会从会话连续性中受益
开发/测试：当每个会话重新开始而不带过状态时，调试更简单
成本敏感型部署：会话恢复可能会产生额外的平台成本或资源使用（请与你的平台核实）

最佳实践：默认情况下为生产启用会话恢复，仅当你有特定理由不使用它时才禁用。

ADK 如何管理会话恢复¶

虽然 Gemini Live API 和 Vertex AI Live API 都支持会话恢复，但直接使用它需要管理恢复句柄、检测连接关闭并实施重新连接逻辑。ADK 承担了这一复杂性的全部责任，在幕后自动利用会话恢复，因此开发人员无需编写任何重新连接代码。你只需在 RunConfig 中启用它，ADK 就会透明地处理一切。

ADK 的自动管理：

初始连接：ADK 建立到 Live API 的 WebSocket 连接
句柄更新：在整个会话期间，Live API 发送包含更新句柄的 session_resumption_update 消息。ADK 自动将最新句柄缓存在 InvocationContext.live_session_resumption_handle 中
优雅连接关闭：当达到 ~10 分钟连接限制时，WebSocket 优雅关闭（无异常）
自动重新连接：ADK 的内部循环检测到关闭并使用最近缓存的句柄自动重新连接
会话继续：同一会话无缝继续，保留完整上下文

实现细节

在重新连接期间，ADK 从 InvocationContext.live_session_resumption_handle 检索缓存的句柄，并将其包含在 live.connect() 调用的新 LiveConnectConfig 中。这完全由 ADK 的内部重新连接循环处理——开发人员无需直接访问或管理这些句柄。

序列图：自动重新连接¶

下面的序列图说明了当达到 ~10 分钟连接超时时，ADK 如何自动管理 Live API 会话恢复。ADK 检测到优雅关闭，检索缓存的恢复句柄，并在无需更改应用程序代码的情况下透明地重新连接：

sequenceDiagram
    participant App as 你的应用程序
    participant ADK as ADK (run_live)
    participant WS as WebSocket 连接
    participant API as Live API (Gemini/Vertex AI)
    participant LiveSession as Live 会话上下文

    Note over App,LiveSession: "初始连接（启用会话恢复）"

    App->>ADK: runner.run_live(run_config=RunConfig(session_resumption=...))
    ADK->>API: WebSocket connect()
    activate WS
    API->>LiveSession: "创建新会话"
    activate LiveSession

    Note over ADK,API: "双向流式传输（0-10 分钟）"

    App->>ADK: send_content(text) / send_realtime(audio)
    ADK->>API: "→ 内容（通过 WebSocket）"
    API->>LiveSession: "更新对话历史记录"
    API-->>ADK: "← 流式响应"
    ADK-->>App: "← yield event"

    Note over API,LiveSession: "Live API 发送恢复句柄更新"
    API-->>ADK: session_resumption_update { new_handle: "abc123" }
    ADK->>ADK: "在 InvocationContext 中缓存句柄"

    Note over WS,API: "~10 分钟已过 - 连接超时"

    API->>WS: "关闭 WebSocket（优雅关闭）"
    deactivate WS
    Note over LiveSession: "会话上下文保留"

    Note over ADK: "检测到优雅关闭 - 未引发异常"
    ADK->>ADK: "while True 循环继续"

    Note over ADK,API: "自动重新连接"

    ADK->>API: WebSocket connect(session_resumption.handle="abc123")
    activate WS
    API->>LiveSession: "附加到现有会话"
    API-->>ADK: "会话恢复，具有完整上下文"

    Note over ADK,API: "双向流式传输继续"

    App->>ADK: send_content(text) / send_realtime(audio)
    ADK->>API: "→ 内容（通过 WebSocket）"
    API->>LiveSession: "更新对话历史记录"
    API-->>ADK: "← 流式响应"
    ADK-->>App: "← yield event"

    Note over App,LiveSession: "会话继续直到持续时间限制或显式关闭"

    deactivate WS
    deactivate LiveSession

事件和会话持久性

有关哪些事件保存到 ADK Session 与哪些仅在流式传输期间产生的详细信息，请参阅第 3 部分：保存到 ADK 会话的事件。

Live API 上下文窗口压缩¶

Problem: Live API sessions face two critical constraints that limit conversation duration. First, session duration limits impose hard time caps: without compression, Gemini Live API limits audio-only sessions to 15 minutes and audio+video sessions to just 2 minutes, while Vertex AI limits all sessions to 10 minutes. Second, context window limits restrict conversation length: models have finite token capacities (128k tokens for gemini-2.5-flash-native-audio-preview-12-2025, 32k-128k for Vertex AI models). Long conversations—especially extended customer support sessions, tutoring interactions, or multi-hour voice dialogues—will hit either the time limit or the token limit, causing the session to terminate or lose critical conversation history.

解决方案： 上下文窗口压缩同时解决了这两个约束。它使用滑动窗口方法，在令牌计数达到配置的阈值时自动压缩或总结早期的对话历史记录。Live API 保留最近上下文的全部细节，同时压缩较旧的部分。关键是，启用上下文窗口压缩将会话持续时间延长至无限时间，移除了会话持续时间限制（Gemini Live API 上的 15 分钟仅音频/2 分钟音频+视频；Vertex AI 上所有会话的 10 分钟），同时也防止了令牌限制耗尽。但是，这有一个权衡：由于该功能总结了早期的对话历史记录而不是保留全部，过去上下文的细节将随着时间的推移逐渐丢失。模型将能够访问较旧交换的压缩摘要，而不是完整的逐字历史记录。

平台行为和官方限制¶

会话持续时间管理和上下文窗口压缩是 Live API 平台功能。ADK 通过 RunConfig 配置这些功能并将配置传递给 Live API，但实际的执行和实现由 Gemini/Vertex AI Live API 后端处理。

重要：本指南中提到的持续时间限制和“无限”会话行为基于当前的 Live API 行为。这些限制可能会由 Google 更改。请始终在官方文档中验证当前的会话持续时间限制和压缩行为：

ADK 提供了一种通过 RunConfig 配置上下文窗口压缩的简单方法。但是，开发人员负责根据其特定要求——模型上下文窗口大小、预期的对话模式和质量需求——适当地配置压缩参数（trigger_tokens 和 target_tokens）：

from google.genai import types
from google.adk.agents.run_config import RunConfig

# For gemini-2.5-flash-native-audio-preview-12-2025 (128k context window)
run_config = RunConfig(
    context_window_compression=types.ContextWindowCompressionConfig(
        trigger_tokens=100000,  # 在 ~78% 的 128k 上下文处开始压缩
        sliding_window=types.SlidingWindow(
            target_tokens=80000  # 压缩至 ~62% 的上下文，保留最近的回合
        )
    )
)

它是如何工作的：

当启用上下文窗口压缩时：

Live API 监控对话上下文的总令牌计数
当上下文达到 trigger_tokens 阈值时，压缩激活
早期的对话历史记录使用滑动窗口方法进行压缩或总结
最近的上下文（最后 target_tokens 值）保留全部细节
两个关键效应同时发生：
会话持续时间限制被移除（Gemini Live API 上不再有 15 分钟/2 分钟上限，Vertex AI 上不再有 10 分钟上限）
令牌限制得到管理（无论对话长度如何，会话都可以无限期继续）

选择合适的阈值：

将 trigger_tokens 设置为模型上下文窗口的 70-80% 以留出余量
将 target_tokens 设置为 60-70% 以提供足够的压缩
使用实际的对话模式进行测试以优化这些值

参数选择策略：

上面的示例使用 78% 作为 trigger_tokens，62% 作为 target_tokens。理由如下：

trigger_tokens 为 78%：在达到硬性限制之前提供缓冲
为当前回合完成留出空间
防止响应中途的压缩中断
典型的对话可以继续进行几个回合
target_tokens 为 62%：压缩后留出大量空间
每次压缩释放 16 个百分点 (78% - 62%)
允许在下一次压缩之前进行多个回合
平衡上下文保留与压缩频率
根据你的用例进行调整：
长回合（详细的技术讨论）：增加缓冲 → 70% 触发，50% 目标
短回合（快速问答）：更紧的边距 → 85% 触发，70% 目标
上下文关键（需要历史细节）：更高的目标 → 80% 触发，70% 目标
性能敏感（最小化压缩开销）：更低的触发 → 70% 触发，50% 目标

始终使用实际的对话模式进行测试以找到最佳值。

何时不使用上下文窗口压缩¶

虽然压缩启用了无限的会话持续时间，但请考虑以下权衡：

上下文窗口压缩的权衡：

方面	有压缩	无压缩	最适合
会话持续时间	无限	15 分钟（音频） 2 分钟（视频）Gemini 10 分钟 Vertex	压缩：长会话无压缩：短会话
上下文质量	较旧的上下文被总结	完整的逐字历史记录	压缩：一般对话无压缩：精度关键
延迟	压缩开销	无开销	压缩：异步场景无压缩：实时
内存使用	有界	随会话增长	压缩：长会话无压缩：短会话
实现	配置阈值	无配置	压缩：生产无压缩：原型

常见用例：

✅ 在以下情况下启用压缩： - 会话需要超过平台持续时间限制（15/2/10 分钟） - 延长的对话可能达到令牌限制（2.5-flash 为 128k） - 持续数小时的客户支持会话 - 具有长时间交互的教育辅导

❌ 在以下情况下禁用压缩： - 所有会话在持续时间限制内完成 - 精确回忆早期对话是关键 - 开发/测试阶段（完整历史记录有助于调试） - 摘要导致的质量下降不可接受

最佳实践：仅在需要会话时间超过平台持续时间限制或对话可能超过上下文窗口令牌限制时启用压缩。

Best Practices for Live API Connection and Session Management¶

Essential: Enable Session Resumption¶

✅ 在生产应用程序的 RunConfig 中始终启用会话恢复
✅ 这使 ADK 能够自动透明地处理 Gemini 的约 10 分钟连接超时
✅ 会话在多个 WebSocket 连接之间无缝继续，不会中断用户
✅ 会话恢复句柄缓存和管理

from google.genai import types

run_config = RunConfig(
    response_modalities=["AUDIO"],
    session_resumption=types.SessionResumptionConfig()
)

推荐：为无限会话启用上下文窗口压缩¶

✅ 启用上下文窗口压缩 如果你需要超过 15 分钟（仅音频）或 2 分钟（音频+视频）的会话
✅ 一旦启用，会话持续时间变为无限——无需监控基于时间的限制
✅ 根据你的模型的上下文窗口配置 trigger_tokens 和 target_tokens
✅ 使用现实的对话模式测试压缩设置
⚠️ 明智地使用：压缩在总结期间会增加延迟，并可能丢失对话细微差别——仅当扩展会话对你的用例确实必要时才启用

from google.genai import types
from google.adk.agents.run_config import RunConfig

run_config = RunConfig(
    response_modalities=["AUDIO"],
    session_resumption=types.SessionResumptionConfig(),
    context_window_compression=types.ContextWindowCompressionConfig(
        trigger_tokens=100000,
        sliding_window=types.SlidingWindow(target_tokens=80000)
    )
)

可选：监控会话持续时间¶

仅适用于未使用上下文窗口压缩的情况：

✅ 关注 会话持续时间限制，而不是连接超时（ADK 自动处理这些）
✅ Gemini Live API：监控 15 分钟限制（仅音频）或 2 分钟限制（音频+视频）
✅ Vertex AI Live API：监控 10 分钟会话限制
✅ 在会话持续时间限制前 1-2 分钟警告用户
✅ 为超过会话限制的对话实施优雅的会话转换

并发 Live API 会话和配额管理¶

问题： 生产语音应用程序通常同时为多个用户提供服务，每个用户都需要自己的 Live API 会话。但是，Gemini Live API 和 Vertex AI Live API 都施加了严格的并发会话限制，这些限制因平台和定价层级而异。如果没有适当的配额规划和会话管理，应用程序可能会很快达到这些限制，导致新用户的连接失败或高峰使用期间的服务质量下降。

解决方案： 了解特定于平台的配额，设计你的架构以保持在并发会话限制内，在需要时实施会话池或排队策略，并主动监控配额使用情况。ADK 自动处理单个会话生命周期，但开发人员必须构建其应用程序以在配额约束内管理多个并发用户。

了解并发 Live API 会话配额¶

这两个平台都限制了可以同时运行多少个 Live API 会话，但限制和机制有很大不同：

Gemini Live API (Google AI Studio) - 基于层级的配额：

层级	并发会话	TPM（每分钟令牌数）	访问权限
免费层	有限*	1,000,000	免费 API 密钥
第 1 层	50	4,000,000	即用即付
第 2 层	1,000	10,000,000	更高的使用层级
第 3 层	1,000	10,000,000	更高的使用层级

*免费层并发会话限制未明确记录，但明显低于付费层。

来源

Gemini API 配额

Vertex AI Live API (Google Cloud) - 基于项目的配额：

资源类型	限制	范围
并发实时双向连接	每分钟 10 个	每个项目，每个区域
最大并发会话	高达 1,000	每个项目
会话创建/删除/更新	每分钟 100 个	每个项目，每个区域

来源

Vertex AI Live API | Vertex AI Quotas

请求增加配额：

要请求增加 Live API 并发会话，请导航到 Google Cloud Console 中的配额页面。过滤名为 "Bidi generate content concurrent requests" 的配额，以查找每个项目、区域和基础模型的配额值，并提交配额增加请求。你需要配额管理员角色 (roles/servicemanagement.quotaAdmin) 才能提出请求。有关详细说明，请参阅查看和管理配额。

Cloud Console 上的配额值

主要区别：

Gemini Live API：并发会话限制随 API 层级急剧扩展（50 → 1,000 个会话）。最适合具有不可预测或快速扩展的用户群且愿意支付更高层级费用的应用程序。
Vertex AI Live API：受连接建立速率（10/分钟）限制，但支持高达 1,000 个总并发会话。最适合具有逐步扩展模式和现有 Google Cloud 基础设施的企业应用程序。此外，你可以请求增加配额，以便为具有更高并发要求的生产部署做准备。

管理配额的架构模式¶

一旦你了解了并发会话配额，下一个挑战就是构建你的应用程序以在这些限制内有效运行。正确的方法取决于你的预期用户并发性、扩展要求和对排队的容忍度。本节介绍了两种架构模式——从用于低并发应用程序的简单直接映射到用于可能在高峰使用期间超过配额限制的应用程序的带排队的会话池。选择符合你当前规模的模式，并将其设计为随着用户群的增长而演变。

选择正确的架构：

                开始：设计配额管理
                              |
                              v
                   预期并发用户？
                     /                    \
            < 配额限制           > 配额限制或不可预测
                   |                              |
                   v                              v
          模式 1：直接映射    模式 2：会话池
          - 简单的 1:1 映射         - 排队等待用户
          - 无配额逻辑             - 优雅降级
          - 快速开发               - 高峰处理
                   |                              |
                   v                              v
              适合：                      适合：
              - 原型                       - 大规模生产
              - 小团队                     - 不可预测的负载
              - 受控用户                   - 公共应用程序

快速决策指南：

因素	直接映射	会话池
预期用户	始终 < 配额	可能超过配额
用户体验	始终即时	高峰期可能等待
实现复杂性	低	中
运营开销	无	监控队列深度
最适合	原型，内部工具	生产，公共应用

模式 1：直接映射（简单应用程序）¶

对于并发用户永远不会超过配额限制的小规模应用程序，为每个连接的用户创建一个专用的 Live API 会话，并进行简单的 1:1 映射：

当用户连接时： 立即为他们启动一个 run_live() 会话
当他们断开连接时： 会话结束
无配额管理逻辑： 假设你的总并发用户将始终低于你的配额限制

这是最简单的架构，非常适合原型、开发环境和具有可预测用户负载的小规模应用程序。

模式 2：带有排队的会话池¶

对于在高峰使用期间可能超过并发会话限制的应用程序，跟踪活动 Live API 会话的数量并在应用程序级别强制执行你的配额限制：

当新用户连接时： 检查是否有可用的会话槽
如果有槽可用： 立即启动会话
如果你已达到配额限制：
将用户放入等待队列
通知他们正在等待可用槽
随着会话结束： 自动处理队列以为等待用户启动会话

这提供了优雅降级——用户在高峰时段短暂等待，而不是经历硬连接故障。

其他控制¶

support_cfc（实验性）¶

此参数启用组合函数调用 (CFC)，允许模型以复杂的模式编排多个工具——并行调用工具，将输出链接为其他工具的输入，或根据中间结果有条件地执行工具。

⚠️ 实验性功能： CFC 支持是实验性的，可能会发生变化。

关键行为： 当 support_cfc=True 时，ADK 始终在内部使用 Live API (WebSocket)，无论 streaming_mode 设置如何。这是因为只有 Live API 后端支持 CFC 功能。

# 即使使用 SSE 模式，当启用 CFC 时，ADK 也会通过 Live API 进行路由
run_config = RunConfig(
    support_cfc=True,
    streaming_mode=StreamingMode.SSE  # ADK 在内部使用 Live API
)

模型要求：

ADK 在会话初始化时验证 CFC 兼容性，如果模型不受支持，将引发错误：

✅ 支持：gemini-2.x 模型（例如，gemini-2.5-flash-native-audio-preview-09-2025, gemini-2.0-flash-live-001）
❌ 不支持：gemini-1.5-x 模型
验证：当 support_cfc=True 时，ADK 检查模型名称是否以 gemini-2 开头 (runners.py:1200-1203)
代码执行器：当启用 CFC 时，ADK 自动注入 BuiltInCodeExecutor 以进行安全的并行工具执行

CFC 功能：

并行执行：同时调用多个独立工具（例如，一次获取多个城市的天气）
函数链：将一个工具的输出用作另一个工具的输入（例如，get_location() → get_weather(location)）
条件执行：根据先前工具调用的中间结果执行工具

用例：

CFC 专为受益于智能工具编排的复杂多步工作流而设计：

同时从多个 API 聚合数据
工具相互馈送的多步分析流水线
需要条件探索的复杂研究任务
任何需要超越顺序执行的复杂工具协调的场景

对于双向流式应用程序： 虽然 CFC 适用于 BIDI 模式，但它主要针对基于文本的工具编排进行了优化。对于实时音频/视频交互（本指南的重点），标准函数调用通常提供更好的性能和更简单的实现。

了解更多：

Gemini 函数调用指南 - 关于组合和并行函数调用的官方文档
ADK 并行函数示例 - 带有异步工具的工作示例
ADK 性能指南 - 并行就绪工具的最佳实践

max_llm_calls¶

此参数限制每个调用上下文允许的总 LLM 调用次数，提供针对失控成本和无限智能体循环的保护。

BIDI 流式处理的限制：

max_llm_calls 限制不适用于具有 StreamingMode.BIDI 的 run_live()。 此参数仅保护 SSE 流式处理模式和 run_async() 流。如果你正在构建双向流式处理应用程序（本指南的重点），你将不会从此参数获得自动成本保护。

对于实时流式处理会话，实现你自己的保障措施：

会话持续时间限制
轮次计数跟踪
通过在模型回合事件中跟踪令牌使用情况自定义成本监控（参见第 3 部分：事件类型和处理）
应用级断路器

save_live_blob¶

此参数控制是否将音频和视频流持久化到 ADK 的会话和制品服务以进行调试、合规性和质量保证。

迁移说明：save_live_audio 已弃用

如果你正在使用 save_live_audio： 此参数已弃用，取而代之的是 save_live_blob。ADK 将在弃用警告下自动将 save_live_audio=True 迁移到 save_live_blob=True，但此兼容层将在未来版本中删除。请更新你的代码以使用 save_live_blob。

目前，仅音频被持久化 通过 ADK 的实现。启用后，ADK 将音频流持久化到：

会话服务：对话历史记录包含音频引用
制品服务：音频文件存储带有唯一 ID

用例：

调试：语音交互问题，助手行为分析
合规性：受监管行业（医疗保健、金融服务）的审计跟踪
质量保证：监控对话质量，识别问题
训练数据：收集数据以进行模型改进
开发/测试：测试环境和成本敏感型部署

存储注意事项：

启用 save_live_blob=True 具有显著的存储影响：

音频文件大小：在 16kHz PCM 下，音频输入每分钟产生 ~1.92 MB
会话存储：音频存储在会话服务和制品服务中
保留策略：检查你的制品服务配置以了解保留期
成本影响：对于大容量语音应用程序，存储成本可能会迅速累积

最佳实践：

仅在需要时启用（调试、合规性、训练）
实施保留策略以自动删除旧的音频制品
考虑采样（例如，保存 10% 的会话以进行质量监控）
如果你的制品服务支持，请使用压缩

custom_metadata¶

此参数允许你将任意键值元数据附加到当前调用期间生成的事件。元数据存储在 Event.custom_metadata 字段中并持久化到会话存储，使你能够使用特定于应用程序的上下文标记事件，以进行分析、调试、路由或合规性跟踪。

配置：

from google.adk.agents.run_config import RunConfig

# 将元数据附加到此调用中的所有事件
run_config = RunConfig(
    custom_metadata={
        "user_tier": "premium",
        "session_type": "customer_support",
        "campaign_id": "promo_2025",
        "ab_test_variant": "variant_b"
    }
)

它是如何工作的：

当你在 RunConfig 中提供 custom_metadata 时：

元数据附加：字典附加到调用期间生成的每个 Event
会话持久性：带有元数据的事件存储在会话服务（数据库、Vertex AI 或内存）中
事件访问：通过 event.custom_metadata 从任何事件检索元数据
A2A 集成：对于智能体到智能体 (A2A) 通信，ADK 自动将 A2A 请求元数据传播到此字段

类型规范：

custom_metadata: Optional[dict[str, Any]] = None

元数据是一个灵活的字典，接受任何 JSON 可序列化的值（字符串、数字、布尔值、嵌套对象、数组）。

用例：

用户细分：使用用户层级、订阅级别或群组信息标记事件
会话分类：按类型（支持、销售、入职）标记会话以进行分析
活动跟踪：将事件与营销活动或实验相关联
A/B 测试：跟踪应用程序的哪个变体生成了事件
合规性：附加管辖区、同意标志或数据保留策略
调试：添加跟踪 ID、功能标志或环境标识符
分析：存储自定义维度以进行下游分析

示例 - 从事件中检索元数据：

async for event in runner.run_live(
    session=session,
    live_request_queue=queue,
    run_config=RunConfig(
        custom_metadata={"user_id": "user_123", "experiment": "new_ui"}
    )
):
    if event.custom_metadata:
        print(f"User: {event.custom_metadata.get('user_id')}")
        print(f"Experiment: {event.custom_metadata.get('experiment')}")

智能体到智能体 (A2A) 集成：

当使用 RemoteA2AAgent 时，ADK 自动从 A2A 请求中提取元数据并填充 custom_metadata：

# A2A 请求元数据自动映射到 custom_metadata
# 来源：a2a/converters/request_converter.py
custom_metadata = {
    "a2a_metadata": {
        # 原始 A2A 请求元数据出现在这里
    }
}

这使得元数据在多智能体架构中的智能体边界之间无缝传播。

最佳实践：

在整个应用程序中使用一致的键命名约定
避免在元数据中存储敏感数据（PII、凭据）——如有必要使用加密
保持元数据大小合理以最小化存储开销
记录元数据模式以确保团队一致性
考虑在生产调试中使用元数据进行会话筛选和搜索

support_cfc（实验性）¶

此参数启用组合函数调用 (CFC)，允许模型以复杂的模式编排多个工具——并行调用工具、将输出链接为其他工具的输入，或根据中间结果有条件地执行工具。

⚠️ 实验性功能： CFC 支持是实验性的，可能会发生变化。

关键行为： 当 support_cfc=True 时，ADK 始终在内部使用 Live API (WebSocket)，无论 streaming_mode 设置如何。这是因为只有 Live API 后端支持 CFC 功能。

# 即使使用 SSE 模式，当启用 CFC 时，ADK 也会通过 Live API 路由
run_config = RunConfig(
    support_cfc=True,
    streaming_mode=StreamingMode.SSE  # ADK 在内部使用 Live API
)

模型要求：

ADK 在会话初始化时验证 CFC 兼容性，如果模型不受支持，将引发错误：

✅ Supported: gemini-2.x models (e.g., gemini-2.5-flash-native-audio-preview-12-2025)
❌ Not supported: gemini-1.5-x models
Validation: ADK checks that the model name starts with gemini-2 when support_cfc=True (runners.py:1322-1328)
Code executor: ADK automatically injects BuiltInCodeExecutor when CFC is enabled for safe parallel tool execution

CFC 功能：

并行执行：同时调用多个独立工具（例如，一次获取多个城市的天气）
函数链：将一个工具的输出用作另一个工具的输入（例如，get_location() → get_weather(location)）
条件执行：根据先前工具调用的中间结果执行工具

用例：

CFC 专为受益于智能工具编排的复杂多步工作流而设计：

同时从多个 API 聚合数据
工具相互馈送的多步分析流水线
需要条件探索的复杂研究任务
任何需要超越顺序执行的复杂工具协调的场景

对于双向流式应用程序： 虽然 CFC 适用于 BIDI 模式，但它主要针对基于文本的工具编排进行了优化。对于实时音频/视频交互（本指南的重点），标准函数调用通常提供更好的性能和更简单的实现。

了解更多：

Gemini Function Calling Guide - Official documentation on compositional and parallel function calling
ADK Parallel Functions Example - Working example with async tools
ADK Performance Guide - Best practices for parallel-ready tools

总结¶

在本部分中，你了解了 RunConfig 如何通过声明性配置实现对 ADK 双向流式处理会话的复杂控制。我们介绍了响应模态及其约束，探讨了 BIDI 和 SSE 流式处理模式之间的差异，检查了 ADK 会话和 Live API 会话之间的关系，并学习了如何通过会话恢复和上下文窗口压缩管理会话持续时间。你现在了解了如何处理并发会话配额，实现配额管理的架构模式，通过 max_llm_calls 和音频持久化选项配置成本控制。凭借对 RunConfig 的掌握，你可以构建在功能丰富性与操作约束之间取得平衡的生产就绪流式处理应用程序——实现延长的对话、管理平台限制、有效地控制成本以及监控资源消耗。

← Previous: Part 3: Event Handling with run_live() | Next: Part 5: How to Use Audio, Image and Video →

第 4 部分：理解 RunConfig¶

RunConfig 参数快速参考¶

响应模态¶

StreamingMode：BIDI 或 SSE¶

协议和实现差异¶

Progressive SSE Streaming¶

何时使用每种模式¶

通过 SSE 访问的标准 Gemini 模型（1.5 系列）¶

Understanding Live API Connections and Sessions¶

ADK Session vs Live API 会话¶

Live API 连接和会话¶

各平台的 Live API 连接和会话限制¶

Live API 会话恢复¶

ADK 重新连接管理的范围¶

ADK 如何管理会话恢复¶

序列图：自动重新连接¶

Live API 上下文窗口压缩¶

平台行为和官方限制¶

何时不使用上下文窗口压缩¶

Best Practices for Live API Connection and Session Management¶

Essential: Enable Session Resumption¶

推荐：为无限会话启用上下文窗口压缩¶

可选：监控会话持续时间¶

并发 Live API 会话和配额管理¶

了解并发 Live API 会话配额¶

管理配额的架构模式¶

模式 1：直接映射（简单应用程序）¶

模式 2：带有排队的会话池¶

其他控制¶

support_cfc（实验性）¶

max_llm_calls¶

save_live_blob¶

custom_metadata¶

support_cfc（实验性）¶

总结¶

ADK `Session` vs Live API 会话¶