Skip to content

级联架构

Supported in ADKPython v2.13.0Experimental

在级联架构中,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) 或耳机,以防扬声器输出被麦克风拾取为虚假的用户打断。