Google Cloud 生成式 AI 实战：Gemini Multimodal Live API 低延迟双向流式语音对话全指南

Google Cloud 生成式 AI 实战：Gemini Multimodal Live API 低延迟双向流式语音对话全指南

【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai

本篇技术指南围绕generative-ai仓库中gemini/multimodal-live-api目录展开，系统讲解 Google Cloud Gemini Multimodal Live API 的核心能力与落地路径：从入门 Notebook、实时 RAG 用例，到 WebSocket 原生音频 Demo 应用、企业级 LiveKit + ADK 多智能体语音编排，再到 PCM 音频调试工具。读完本文，你将掌握该 API 的底层协议、鉴权代理原理、三种部署方式（本地 / Cloud Shell / Cloud Run）以及 7 个可直接复用的 Demo 应用，能够快速构建自己的"可打断、可看画面、可说话"的实时语音助手。

Multimodal Live API 是什么：低延迟双向流式交互

Multimodal Live API 是 Google Cloud Vertex AI 提供的低延迟双向流式 API，核心特征如下：

• 多模态输入：支持文本、音频（麦克风）与视频（摄像头或屏幕共享）三种输入流；
• 多模态输出：可输出音频与文本；
• 自然对话体验：支持在交互的任何时刻打断（interrupt）模型，像人与人的对话一样随时插话；
• 实时视频理解：共享实时视频输入与屏幕录制内容，Gemini 可以跨视频画面进行推理并回答问题；
• 系统指令（System Instructions）：通过预设指令精确控制模型行为与输出风格。

底层协议：BidiGenerateContent 双向流

从源码层面看，Multimodal Live API 基于 WebSocket 双向流协议实现。在 websocket-demo-app/backend/main.py 中可以清晰看到其连接目标：

HOST = "us-central1-aiplatform.googleapis.com" SERVICE_URL = f"wss://{HOST}/ws/google.cloud.aiplatform.v1beta1.LlmBidiService/BidiGenerateContent"

即客户端通过wss://安全 WebSocket 连接到 Vertex AI 的LlmBidiService服务，调用BidiGenerateContent方法完成消息的双向转发。该文件中的proxy_task函数（main.py）展示了核心代理逻辑：前端 WebSocket 与后端 Gemini WebSocket 之间逐条 JSON 消息双向透传，从而隐藏 Bearer Token 鉴权细节，避免把敏感凭证暴露给浏览器端。

快速上手：两个入门 Notebook

仓库在gemini/multimodal-live-api/下提供了两条入门路径，分别对应"直接访问 API"与"通过 SDK 访问"：

1. intro_multimodal_live_api.ipynb：直接访问 Multimodal Live API，演示文本到文本（text-to-text）与文本到音频（text-to-audio）两种生成方式。适合想理解 API 原始调用方式、熟悉 WebSocket 消息格式的读者。

2. intro_multimodal_live_api_genai_sdk.ipynb：通过 Google Gen AI SDK 在 Vertex AI 上访问 Multimodal Live API，同样覆盖 text-to-text 与 text-to-audio 示例。SDK 封装了握手、鉴权与消息序列化，代码更简洁，适合在已有 Python 工程中集成。

此外目录下还有两个补充 Notebook 可进一步探索：

• live_api_quickstart.ipynb：Live API 的快速开始教程；
• intro_live_api_native_audio.ipynb：聚焦原生音频（native audio）模型的接入方式。

真实场景用例：基于 Live API 的实时 RAG

Multimodal Live API 的价值不止于"聊天"，仓库提供了两个将实时流式对话与检索增强生成（RAG）结合的完整用例：

1. Interactive Loan Application Assistant：以 Gemini 2.0 为核心的个人文件助手演示。用户可以通过自然语言理解并交互自己的贷款文档（loan documents），模型基于文档内容生成基于事实的语音与文本回答，是"文件问答 + 实时语音"的典型组合。

2. Real-time RAG for Retail：面向零售场景的实时 RAG 系统。它利用 Multimodal Live API 构建实时问答能力，输出音频与文本响应，且回答内容严格锚定（grounded）在给定的零售文档之上，防止模型"凭空发挥"。

这两个用例的共同模式是：检索到的文档片段注入会话上下文 + Live API 实时语音输出，非常适合客服、金融、电商等需要"边对话边查资料"的业务场景。

Demo 应用体系：从 WebSocket 代理到原生音频

gemini/multimodal-live-api下提供了 7 个 Demo 应用与 1 个调试工具，覆盖从最简骨架到生产级功能的完整梯度。下面按依赖复杂度逐一展开。

1. websocket-demo-app：最基础的语音 + 摄像头入门

websocket-demo-app 是一个让你"用语音和摄像头和 Gemini 2.0 对话"的 Web 应用，也是理解整个 API 调用链路的最佳起点。

架构：

• 后端（Python WebSocket Server）：负责鉴权，并作为前端与 Gemini API 之间的中间代理（即上文main.py的实现）；
• 前端（HTML/JavaScript）：提供用户界面，通过 WebSocket 与后端交互。

文件结构：

• backend/main.py：Python 后端核心代码；
• backend/requirements.txt：Python 依赖清单；
• frontend/index.html：前端 HTML 应用；
• frontend/script.js：前端主逻辑，其中需要配置PROXY_URL与PROJECT_ID；
• frontend/gemini-live-api.js：与 Gemini API 交互的脚本；
• frontend/live-media-manager.js：媒体输入/输出管理；
• frontend/pcm-processor.js：PCM 音频处理（编解码、分包）；
• frontend/cookieJar.js：Cookie 管理。

本地部署步骤（完整流程）：

# 1. 克隆仓库并进入目录 git clone <本仓库地址> cd generative-ai/gemini/multimodal-live-api/websocket-demo-app # 2. 创建并激活虚拟环境 python3 -m venv env source env/bin/activate # 3. 安装依赖 pip3 install -r backend/requirements.txt # 4. 启动 Python WebSocket 后端 python3 backend/main.py

接着配置前端：

• 打开frontend/script.js，将第 9 行const PROXY_URL = "wss://[THE_URL_YOU_COPIED_WITHOUT_HTTP]";改为const PROXY_URL = "ws://localhost:8000";。注意这里用的是ws（非安全 WebSocket），少一个 "s"；
• 将第 10 行的PROJECT_ID改为你的 Google Cloud 项目 ID；
• 保存后，另开一个终端窗口（保持后端运行）启动前端静态服务器：

cd frontend python3 -m http.server

然后按终端输出地址（如http://localhost:8000）在浏览器打开 UI。接下来获取访问凭证：

gcloud components update gcloud components install beta gcloud config set project YOUR-PROJECT-ID gcloud auth print-access-token

将输出的 Access Token 粘贴到页面 UI 的对应输入框，在 Model ID 输入框把YOUR-PROJECT-ID替换为你的项目 ID，点击Connect即可开始对话。

支持的交互方式：

• 文本输入：在输入框输入文字并点击发送箭头，模型以音频回应（请打开音量）；
• 语音输入：点击麦克风按钮开始说话，再点击带斜杠的麦克风按钮静音，模型以音频回应；
• 视频输入：模型会捕获摄像头画面并发送给 Gemini，你可以针对当前或此前的视频画面提问。

Cloud Shell 部署要点：上传或克隆代码到 Cloud Shell Editor 后，分别在两个终端运行后端（python3 backend/main.py）与前端（cd frontend && python3 -m http.server）；由于 Cloud Shell 的 Web Preview 只暴露指定端口，需要将script.js中的PROXY_URL改为形如wss://8080-cs-123456789-default.cs-us-central1-abcd.cloudshell.dev的 Web Preview 代理地址，随后通过 Web Preview 的 "Change port" 将预览端口改为 8000，最后用gcloud auth print-access-token获取凭证填入 UI。

Cloud Run 部署：将frontend/script.js中的PROXY_URL改为/ws（与前端、后端同容器，无需主机名），然后用一条命令部署：

gcloud run deploy --project=YOUR-PROJECT-ID \ --region=us-central1 \ --source=./ \ --allow-unauthenticated \ --port=8000 \ gemini-live-demo

部署成功后命令行会输出访问链接，浏览器打开后填入 Access Token 与项目 ID 即可使用。

2. React Demo App：完整的前端工程化方案

react-demo-app 是一个功能全面的 React 客户端，强调实时流式传输、工具调用（tool use）与媒体处理。

快速启动：

# 后端：安装依赖并启动代理服务器 pip install -r requirements.txt gcloud auth application-default login python server.py # 前端：安装 Node 模块并启动开发服务器 npm install npm run dev

浏览器打开http://localhost:5173即可使用。

核心 API：src/utils/gemini-api.js中的GeminiLiveAPI类管理 WebSocket 连接：

import { GeminiLiveAPI } from "./utils/gemini-api"; const client = new GeminiLiveAPI( "ws://localhost:8080", "your-project-id", "gemini-2.0-flash-exp" ); client.connect(); client.sendText("Hello Gemini");

媒体处理：应用使用 AudioWorklets 实现低延迟音频处理，public/audio-processors/capture.worklet.js负责麦克风采集，playback.worklet.js负责 PCM 音频播放。

关键配置：默认模型为gemini-live-2.5-flash-native-audio；语音（Voice）可在LiveAPIDemo.jsx中配置（Puck、Charon 等）；代理端口默认为8080（在server.py中设定）。

3. Plain JS Demo App：零依赖理解核心机制

plain-js-demo-app 用纯原生 JavaScript 实现，无任何框架依赖，是理解 API 底层机制的最佳切片。

快速启动：

pip3 install -r requirements.txt gcloud auth application-default login python3 server.py # 浏览器打开 http://localhost:8000

客户端 API 一览（frontend/geminilive.js）：

const client = new GeminiLiveAPI(proxyUrl, projectId, model); client.addFunction(toolInstance); // 添加自定义工具 client.connect(accessToken); // 连接（走代理时 token 可省略） client.sendText("Hello"); // 发送文本 client.sendAudioMessage(base64); // 发送音频（Base64） client.sendImageMessage(base64); // 发送图像（Base64）

媒体流式传输（frontend/mediaUtils.js）：

// 音频流 const audioStreamer = new AudioStreamer(client); await audioStreamer.start(deviceId); // 可指定设备 ID // 视频流（可指定帧率） const videoStreamer = new VideoStreamer(client); await videoStreamer.start({ fps: 1, deviceId: "..." }); // 音频播放 const player = new AudioPlayer(); await player.play(base64PCM);

自定义工具：继承FunctionCallDefinition基类即可注册客户端工具：

class MyTool extends FunctionCallDefinition { constructor() { super("tool_name", "description", parameters, required); } functionToCall(params) { // 工具实现 } }

配置项：模型默认gemini-live-2.5-flash-native-audio；语音可选 Puck、Charon、Kore、Fenrir、Aoede；响应可为音频、文本或两者兼有；工具支持自定义函数或 Google Grounding。代理服务器同时负责 Google Cloud 鉴权、向 Gemini API 转发 WebSocket、以及从frontend/目录提供静态文件。

4. Plain JS + Python SDK Demo App：官方 Python SDK 后端

plain-js-python-sdk-demo-app 采用Google Gen AI Python SDK（google-genai）作为后端、原生 JS 作为前端，展示如何构建"稳健 Python 后端 + 轻量前端"的实时多模态应用。

快速启动：

pip install -r requirements.txt gcloud auth application-default login python main.py # 浏览器打开 http://localhost:8000

配置：必须修改main.py顶部的PROJECT_ID：

# Configuration PROJECT_ID = os.getenv("PROJECT_ID", "your-project-id-here")

也可在启动前设置环境变量PROJECT_ID。

后端核心（gemini_live.py）：GeminiLive类封装genai.Client，用 SDK 的aio.live.connect建立会话，并通过asyncio.gather并发处理音频发送、视频发送与响应接收：

async with self.client.aio.live.connect(model=self.model, config=config) as session: await asyncio.gather( send_audio(), send_video(), receive_responses() )

前端（frontend/gemini-client.js）通过 WebSocket 与 FastAPI 后端通信，以 Base64 编码的媒体块上传、接收音频响应。

进阶 Demo：客服、游戏助手与实时顾问

下面三个 React 应用将 Live API 的能力推向具体业务形态，均遵循"Python 代理后端（server.py）+ React 前端（npm install && npm run dev，默认端口 5173）"的同一套启动范式。

客服智能体：情感识别 + 多模态 + 真实行动

customer-support-demo-app 模拟下一代客服场景，Agent 能"看到你看到的、听懂你的语气、并真实执行操作解决问题"：

• 多模态理解：客户可将商品举到摄像头前（如退货场景），Agent 同时听取语音；
• 情感对话（Affective Dialogue）：检测用户情绪并相应调整语气，营造更拟人的沟通；
• 真实行动：内置process_refund（按交易 ID 处理退款）与connect_to_human（复杂问题转接人工）两个自定义工具；
• 配置项：Project ID、代理 URL（默认ws://localhost:8080）、模型 ID、语音/温度，以及 "Affective Dialog"、"Google Grounding" 等开关均可在界面的 Configuration 下拉框中调整。

界面截图展示了该 Demo 的完整交互布局，左侧为能力说明与示例话术，中间为消息区，右侧为麦克风与摄像头控制：

游戏助手：人设切换 + 屏幕共享 + 主动播报

gaming-assistant-demo-app 是一个实时游戏陪玩 AI，它"看着你的屏幕、听着你的语音"来提供攻略建议：

• 人设系统（Persona System）：动态注入系统指令切换性格与语音，可选 Wise Wizard（智者巫师）、SciFi Robot（科幻机器人）、Commander（指挥官）；
• 原生音频：利用 Gemini 原生音频能力实现低延迟、有表现力的语音；
• 多模态输入：同时流式传输屏幕捕获与麦克风音频；
• Google Grounding：接入实时信息提供最新的游戏知识；
• 主动辅助（Proactive Assistance）：请求帮助时 Agent 可主动开口说话。

实时顾问：双模式切换与打断控制

realtime-advisor-demo-app 模拟一个"旁听会议并给建议"的商业顾问，亮点在于对交互节奏的精细控制：

• 双交互模式：通过 System Instructions 在Silent Mode（静默模式，只推送可视化信息弹窗，不发声）与Outspoken Mode（健谈模式，语音插话 + 展示可视化数据）之间切换；
• 知识注入：可在界面中间栏编辑文本，动态将业务数据（营收、员工数等）注入模型上下文；
• 打断控制（Barge-in Control）：演示通过activity_handling配置防止用户误打断顾问的回复；
• 工具调用：使用自定义show_modal工具向用户展示结构化信息。

企业级多智能体语音编排：LiveKit + Agent Development Kit

如果要在生产环境构建"WebRTC 低延迟音频 + 多智能体路由"的完整语音系统，仓库提供了 livekit-adk 这一企业级参考实现：基于 Google 的Agent Development Kit（ADK）与LiveKit，建立 WebRTC 到 Gemini Live 的低延迟桥接，让用户通过自然语音完成机票与酒店的搜索、预订和管理。

系统架构与协议生命周期

其架构图（livekit-adk/README.md）完整描绘了从浏览器到 Gemini 的链路：

1. 会话建立：客户端向/token请求令牌，触发后台实例化LiveKitGeminiBridge；
2. WebRTC 加入：浏览器加入 LiveKit 房间，Bridge 同时将一个虚拟音频参与者接入房间；
3. 上行链路（用户 → Gemini）：客户端通过 WebRTC 将用户音频送入 LiveKit 房间，LiveKitGeminiBridge订阅音轨，将48kHz 音频降采样为 16kHz 单声道 PCM，推入 ADK 的LiveRequestQueue；ADKRunner通过底层安全 WebSocket（bidiGenerateContent协议）流式发送给 Gemini Live API；
4. 下行链路（Gemini → 用户）：Gemini 通过 WebSocket 实时返回音频缓冲与文本转写，Bridge 将音频（重采样至 24kHz）推回 LiveKit 的LocalAudioTrack，并通过 WebRTCDataChannel发布转写文本。

其中app/livekit_bridge.py扮演低延迟音频转换与路由引擎：将 LiveKit 高保真音频标准化为16kHz 单声道 PCM，并按20ms、640 字节的小缓冲发包以降低 WebSocket 延迟；同时监听runner.run_live事件生成器，把模型文本输出打印到服务端控制台并发布到 DataChannel。

多智能体编排与运行配置

app/travel_booking/包内实现了三层层级式多智能体编排：

• Session Orchestrator（agent.py）：根智能体，监听用户意图，通过 ADK 原生的智能体路由工具调用将控制权委托给子智能体；
• FlightBookingAgent（agents/flight_booking.py）：专精机票搜索与预订，内置search_flights、book_flight、cancel_flight三个 mock 工具，并配置HotelBookingAgent为子智能体以支持静默交接；
• HotelBookingAgent（agents/hotel_booking.py）：专精住宿查询与预订，内置search_hotels、book_hotel、cancel_hotel三个 mock 工具。

Runner 配置（app/main.py）使用InMemorySessionService或DatabaseSessionService持久化对话历史，并通过自定义的SessionResumptionIsolationPlugin在子智能体交接时清除会话恢复句柄，避免出现基于 key 的 Gemini API 错误：

runner = Runner( app_name="livekit-adk", agent=agent.root_agent, session_service=session_service, auto_create_session=True, plugins=[SessionResumptionIsolationPlugin()] )

针对原生音频模型的RunConfig（app/livekit_bridge.py）同样关键：

run_config = RunConfig( streaming_mode=StreamingMode.BIDI, response_modalities=["AUDIO"], input_audio_transcription=types.AudioTranscriptionConfig(), output_audio_transcription=types.AudioTranscriptionConfig(), session_resumption=types.SessionResumptionConfig(), enable_affective_dialog=True )

• response_modalities=["AUDIO"]：对原生音频 Gemini 模型至关重要，强制直接输出音频以保证自然的语音节奏；
• output_audio_transcription：要求 Gemini 随音频流一并返回文本转写，便于桥接层在 UI 上展示。

本地运行：创建app/.env配置模型与 LiveKit 参数：

# Model selection DEMO_AGENT_MODEL="gemini-live-2.5-flash-native-audio" # LiveKit Settings (Local development values) USE_LIVEKIT=true LIVEKIT_URL=ws://localhost:7880 LIVEKIT_API_KEY=devkey LIVEKIT_API_SECRET=secret

macOS 下用 Homebrew 安装并启动 LiveKit 开发服务器：

brew install livekit livekit-server --dev

--dev模式默认监听localhost:7880，默认凭证为 API Keydevkey、API Secretsecret（与.env模板一致）。随后同步依赖并启动应用：

uv sync cd app && uv run --project .. python3 -m uvicorn main:app --reload

浏览器访问http://127.0.0.1:8000/static/livekit即可与语音助手对话。该 Demo 的界面截图展示了实时语音对话、文本转写与事件控制台（EVENT CONSOLE）的完整运行状态：

调试利器：PCM Audio Debugger

在开发实时语音应用时，PCM 数据的编解码最易出错。pcm-audio-debugger 提供了一个零依赖的单文件 HTML 工具，只需在浏览器中打开pcm-audio-debugger.html即可使用，包含两个核心功能：

• PCM 生成器（PCM Generator）：录制麦克风输入并转换为 Base64 编码的 PCM 数据，支持 8kHz–48kHz 采样率、Mono/Stereo 声道、8-bit / 16-bit（有符号）/ 32-bit（float）位深；
• 数据包播放器（Packet Player）：解码并播放 Base64 PCM 字符串，可粘贴多个连续数据包来测试流式音频链路，需确保采样率等设置与数据一致。

典型调试流程：在PCM Generator标签页选择麦克风、配置采样率/声道/位深，录制并复制 Base64 字符串；切换到Packet Player标签页粘贴数据（可点 Add Packet 追加多段），点击Decode & Play All Packets验证收发链路是否正确。

资源地图：按需取用

结语：从 Demo 到生产的最小路径

综合整个gemini/multimodal-live-api目录可以看到一条清晰的学习与落地路径：先用websocket-demo-app跑通"语音 + 摄像头 + WebSocket 代理"的最小闭环，理解BidiGenerateContent协议与 PCM 音频链路；再用plain-js-demo-app或react-demo-app掌握客户端 API 与工具调用；接着借鉴客服、游戏助手、实时顾问三个 Demo 将能力落到具体业务形态；当需要多智能体路由与 WebRTC 生产级音质时，直接采用livekit-adk的架构与配置；开发全程可用pcm-audio-debugger排查音频数据问题。这套由浅入深的资源组合，足以支撑你在 Google Cloud 上快速构建属于自己的实时多模态语音应用。

【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai