Skip to content

实时智能体的音频与视频

Supported in ADKPython v0.1.0

音频与视频是让实时智能体真正"活"起来的关键，也恰恰是对格式要求最严格的地方。Live API 要求音频使用特定的 PCM 采样率，而图像和视频帧的发送方式也与文本不同。

ADK 不会为你转换媒体格式。 采样率、编码和 MIME 类型的正确设置需要你自行负责，错误的格式不会产生有用的提示信息，只会导致静音、噪声或连接错误。以下就是具体的格式约定。

关于哪些模型支持这些模态，请参阅支持的模型。关于语音、转录和轮次检测，请参阅配置。如果你希望使用一个已经实现了所有这些功能的客户端，可以运行 adk web 来启动你的智能体；如果要编写自己的客户端，请参阅构建自定义服务器。

音频输入

通过 send_realtime() 以原始字节的方式发送麦克风音频。字节数据必须已经是 Live API 所期望的格式——ADK 会直接透传：

属性 值
编码 16 位 PCM，有符号，小端序
采样率 16,000 Hz (16 kHz)
声道 单声道
MIME 类型 audio/pcm;rate=16000 
from google.genai import types

live_request_queue.send_realtime(
    types.Blob(mime_type="audio/pcm;rate=16000", data=audio_data)
)

以小块传输音频以实现低延迟。LiveRequestQueue 会立即转发每个数据块，不会进行合并，因此你发送的块大小就是模型接收的粒度：

  • 超低延迟（实时对话）：每块 10-20 毫秒。
  • 均衡模式（推荐）：每块 50-100 毫秒。在 16 kHz 下，100 毫秒为 16000 × 0.1 × 2 = 3200 字节。
  • 较低开销：每块 100-200 毫秒。

在整个会话中使用一致的块大小，并且不要等待模型响应后再发送下一个块——模型是连续处理音频的，而非逐轮处理。当语音活动检测开启时（默认开启），持续发送音频流即可，让 API 自动检测语音；只有在禁用 VAD 时才需要发送活动信号。

音频输出

当设置 response_modalities=["AUDIO"]（实时模式的默认值）时，模型会以事件流上的 inline_data 部分返回音频：

属性 值
编码 16 位 PCM，有符号，小端序
采样率 24,000 Hz (24 kHz) —— 注意这与输入的 16 kHz 不同
声道 单声道
MIME 类型 audio/pcm;rate=24000 
async for event in runner.run_live(...):
    if event.content and event.content.parts:
        for part in event.content.parts:
            if part.inline_data and part.inline_data.mime_type.startswith("audio/pcm"):
                await play_audio(part.inline_data.data)  # 原始 24 kHz PCM 字节

返回的字节可直接播放，无需在你这边进行解码。Live API 在传输时使用 base64 编码音频，但 google.genai 会自动解码，所以 part.inline_data.data 已经是 bytes 类型。关于哪些事件携带音频以及它们与转录如何交错，请参阅事件。要将音频持久化到 artifact 服务，请设置 save_live_blob=True。

图像与视频

图像和视频以单独的 JPEG 帧通过与音频相同的 send_realtime() 方法发送。没有视频编解码器：视频流就是一系列静止帧，每一帧作为一个独立的 blob 发送。

属性 值
格式 JPEG (image/jpeg)
帧率 约每秒 1 帧（推荐上限）
分辨率 768×768 像素（推荐） 
from google.genai import types

live_request_queue.send_realtime(
    types.Blob(mime_type="image/jpeg", data=jpeg_bytes)
)

在约 1 FPS 的帧率下，模型可以看到用户摄像头对准或讨论的内容，但无法处理依赖于运动的任务。动作识别、运动分析和运动追踪需要的时间分辨率是这种方案无法提供的。

在 Shopper's Concierge 演示中，应用通过 send_realtime() 发送用户上传的图片；智能体识别上下文后在电商目录中搜索匹配的商品。

要将实时视频流输入到工具中，使智能体能够对到达的帧做出反应，请参阅流式工具。