级联架构¶
在级联架构中,CascadeLive 将流式语音转文本 (STT)、文本推理 LLM 以及流式文本转语音 (TTS) 串联起来。音频依次流经三个阶段:语音识别将用户音频转录为文本,LLM 基于文本进行推理并调用工具,语音合成将流式传输的文本回复转换为音频。
你在智能体的 model 参数上配置 CascadeLive,因此你的 Runner.run_live() 循环、请求队列、工具、回调和工作流保持不变。同一个智能体还可以通过 Runner.run_async() 处理纯文本请求,此时会绕过语音阶段并直接调用内部文本模型。
有关与原生语音到语音模型的对比,请参阅选择语音架构。
配置级联智能体¶
向 Agent 传递一个包含文本 LLM、语音转文本提供商和文本转语音提供商的 CascadeLive 实例:
google.adk.live 中的 GeminiSTT 和 GeminiTTS 使用你现有的 Google 凭据,无需额外安装软件包。
from google.adk.agents import Agent
from google.adk.live import CascadeLive, GeminiSTT, GeminiTTS
from google.genai import types
root_agent = Agent(
name="voice_assistant",
model=CascadeLive(
model="gemini-3.8-flash",
stt=GeminiSTT(),
tts=GeminiTTS(speech_config="Kore"),
),
instruction=(
"你是一个语音助手。请将回答保持在一到两句简短的话内,"
"并且每句话都以标点符号结尾。将数字、符号和缩写写为口播词。"
),
tools=[...],
generate_content_config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(
thinking_level=types.ThinkingLevel.LOW
),
),
)
安装 ElevenLabs 额外依赖(pip install "google-adk[elevenlabs]")并在环境中设置 ELEVENLABS_API_KEY。
from google.adk.agents import Agent
from google.adk.integrations.eleven_labs import ElevenLabsSTT, ElevenLabsTTS
from google.adk.live import CascadeLive
from google.genai import types
root_agent = Agent(
name="voice_assistant",
model=CascadeLive(
model="gemini-3.8-flash",
stt=ElevenLabsSTT(),
tts=ElevenLabsTTS(),
),
instruction=(
"你是一个语音助手。请将回答保持在一到两句简短的话内,"
"并且每句话都以标点符号结尾。将数字、符号和缩写写为口播词。"
),
tools=[...],
generate_content_config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(
thinking_level=types.ThinkingLevel.LOW
),
),
)
智能体上的两项设置会直接影响语音延迟和合成质量:
- 尽量减少模型思考:模型思考在发出第一个响应 token 之前运行,并直接增加获得首段音频的时间(time-to-first-audio)。在
generate_content_config中设置较低的思考级别(或在使用 token 预算的模型上设置零思考预算)。 - 提示词要求句子带标点且不使用缩写:内置的 TTS 提供商在句子边界拆分文本,以便在 LLM 完成完整回复之前就开始播放第一句。第一句中的缩写(如
Dr. Smith)可能会触发提前拆分,而没有标点的输出在开始播放之前会缓冲更长时间。
使用 adk web 运行智能体,或使用 Runner.run_live() 驱动它。cascade 示例中提供了一个包含 Gemini 和 ElevenLabs 语音提供商的完整可运行示例。
工作原理¶
sequenceDiagram
participant Client as 客户端
participant STT as 语音转文本 (STT)
participant LLM as 文本 LLM
participant TTS as 文本转语音 (TTS)
Client->>STT: 流式传输用户音频
STT-->>Client: 部分输入转录
STT->>LLM: 最终用户转录
LLM->>TTS: 流式文本 token
TTS-->>Client: 合成的音频块
TTS-->>Client: 口播输出转录
字幕与轮次检测¶
- 实时字幕采用替换而非追加:当用户说话时,中间转录结果会到达
event.input_transcription。与以增量单词片段形式流式传输的原生音频模型不同,级联模式下的每个中间更新都包含截至目前的完整话语假设,因此你的客户端应替换显示的字幕,而不是向其追加。 - 自定义词汇与客户端控制的 VAD:服务端语音活动检测 (VAD) 默认启用。要提供领域词汇或通过
GeminiSTT从客户端控制轮次边界(如按住说话),请传递audio_transcription_config,或禁用自动活动检测并调用send_activity_start()和send_activity_end():
from google.adk.live import GeminiSTT
from google.genai import types
stt = GeminiSTT(
audio_transcription_config=types.AudioTranscriptionConfig(
language_codes=["en-US"],
custom_vocabulary=["Cymbal Direct", "Altostrat"],
),
activity_detection=types.AutomaticActivityDetection(disabled=True),
)
插话将历史截断为用户听到的内容¶
TTS 提供商合成即将到来的句子的速度快于实时播放,因此当用户在回复中途中断时,客户端缓冲区通常包含用户尚未听到的音频。
当发生中断时,CascadeLive 会暂停合成和 LLM 生成,发出中断事件以便客户端停止播放,并估算客户端实际播放了多少音频。只有用户听到的单词才会保存到会话历史记录和最终的 output_transcription 中,因此后续轮次绝不会引用未口播的文本。
自定义语音转换¶
要集成其他语音提供商或在各阶段之间检查文本,请从 google.adk.live 继承 LiveIngress(用于语音转文本)或 LiveEgress(用于文本转语音):
LiveIngress读取传入的音频流并产出语音开始、部分转录和轮次结束事件(UserSpeechStarted、PartialTranscript、UserTurnFinished)。LiveEgress读取流式 LLM 文本增量并产出合成的音频块和口播转录事件(AudioChunk、AgentSpokenOutput),直至完成或取消。
由于在合成之前 LLM 输出是纯文本,你可以包装任何 LiveEgress,在生成单个音频帧之前对文本进行修订或转换:
import asyncio
from typing import AsyncGenerator, AsyncIterator
from google.adk.live import EgressEvent, LiveEgress
class RedactingTTS(LiveEgress):
"""在合成前从流式 LLM 文本中脱敏敏感模式。"""
def __init__(self, inner_tts: LiveEgress, redact_fn):
self._tts = inner_tts
self._redact = redact_fn
async def __call__(
self, text: AsyncIterator[str], *, cancel: asyncio.Event
) -> AsyncGenerator[EgressEvent, None]:
async def sanitized_text() -> AsyncGenerator[str, None]:
async for delta in text:
yield self._redact(delta)
async for event in self._tts(sanitized_text(), cancel=cancel):
yield event
考量与限制¶
- 基于静默的轮次检测:服务端 VAD 会在静默达到阈值后结束用户轮次,因此句子中间较长的停顿可能会将一次话语拆分为两轮。在 STT 提供商上调整静默阈值,或使用客户端控制的活动信号。
- 避免在同步工具执行期间说话:如果用户在同步工具调用仍在运行时说完话,新的用户轮次会落在工具调用及其响应之间,导致该会话中后续的模型请求失败。
- 客户端回声消除:使用浏览器或硬件声学回声消除 (AEC) 或耳机,以防扬声器输出被麦克风拾取为虚假的用户打断。