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 fwss://{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 访问intro_multimodal_live_api.ipynb直接访问 Multimodal Live API演示文本到文本text-to-text与文本到音频text-to-audio两种生成方式。适合想理解 API 原始调用方式、熟悉 WebSocket 消息格式的读者。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.ipynbLive API 的快速开始教程intro_live_api_native_audio.ipynb聚焦原生音频native audio模型的接入方式。真实场景用例基于 Live API 的实时 RAGMultimodal Live API 的价值不止于聊天仓库提供了两个将实时流式对话与检索增强生成RAG结合的完整用例Interactive Loan Application Assistant以 Gemini 2.0 为核心的个人文件助手演示。用户可以通过自然语言理解并交互自己的贷款文档loan documents模型基于文档内容生成基于事实的语音与文本回答是文件问答 实时语音的典型组合。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.pyPython 后端核心代码backend/requirements.txtPython 依赖清单frontend/index.html前端 HTML 应用frontend/script.js前端主逻辑其中需要配置PROXY_URL与PROJECT_IDfrontend/gemini-live-api.js与 Gemini API 交互的脚本frontend/live-media-manager.js媒体输入/输出管理frontend/pcm-processor.jsPCM 音频处理编解码、分包frontend/cookieJar.jsCookie 管理。本地部署步骤完整流程# 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 --projectYOUR-PROJECT-ID \ --regionus-central1 \ --source./ \ --allow-unauthenticated \ --port8000 \ 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即可使用。核心 APIsrc/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.jsconst 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 SDKgoogle-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.pyGeminiLive类封装genai.Client用 SDK 的aio.live.connect建立会话并通过asyncio.gather并发处理音频发送、视频发送与响应接收async with self.client.aio.live.connect(modelself.model, configconfig) 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 KitADK与LiveKit建立 WebRTC 到 Gemini Live 的低延迟桥接让用户通过自然语音完成机票与酒店的搜索、预订和管理。系统架构与协议生命周期其架构图livekit-adk/README.md完整描绘了从浏览器到 Gemini 的链路会话建立客户端向/token请求令牌触发后台实例化LiveKitGeminiBridgeWebRTC 加入浏览器加入 LiveKit 房间Bridge 同时将一个虚拟音频参与者接入房间上行链路用户 → Gemini客户端通过 WebRTC 将用户音频送入 LiveKit 房间LiveKitGeminiBridge订阅音轨将48kHz 音频降采样为 16kHz 单声道 PCM推入 ADK 的LiveRequestQueueADKRunner通过底层安全 WebSocketbidiGenerateContent协议流式发送给 Gemini Live API下行链路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 Orchestratoragent.py根智能体监听用户意图通过 ADK 原生的智能体路由工具调用将控制权委托给子智能体FlightBookingAgentagents/flight_booking.py专精机票搜索与预订内置search_flights、book_flight、cancel_flight三个 mock 工具并配置HotelBookingAgent为子智能体以支持静默交接HotelBookingAgentagents/hotel_booking.py专精住宿查询与预订内置search_hotels、book_hotel、cancel_hotel三个 mock 工具。Runner 配置app/main.py使用InMemorySessionService或DatabaseSessionService持久化对话历史并通过自定义的SessionResumptionIsolationPlugin在子智能体交接时清除会话恢复句柄避免出现基于 key 的 Gemini API 错误runner Runner( app_namelivekit-adk, agentagent.root_agent, session_servicesession_service, auto_create_sessionTrue, plugins[SessionResumptionIsolationPlugin()] )针对原生音频模型的RunConfigapp/livekit_bridge.py同样关键run_config RunConfig( streaming_modeStreamingMode.BIDI, response_modalities[AUDIO], input_audio_transcriptiontypes.AudioTranscriptionConfig(), output_audio_transcriptiontypes.AudioTranscriptionConfig(), session_resumptiontypes.SessionResumptionConfig(), enable_affective_dialogTrue )response_modalities[AUDIO]对原生音频 Gemini 模型至关重要强制直接输出音频以保证自然的语音节奏output_audio_transcription要求 Gemini 随音频流一并返回文本转写便于桥接层在 UI 上展示。本地运行创建app/.env配置模型与 LiveKit 参数# Model selection DEMO_AGENT_MODELgemini-live-2.5-flash-native-audio # LiveKit Settings (Local development values) USE_LIVEKITtrue LIVEKIT_URLws://localhost:7880 LIVEKIT_API_KEYdevkey LIVEKIT_API_SECRETsecretmacOS 下用 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-bitfloat位深数据包播放器Packet Player解码并播放 Base64 PCM 字符串可粘贴多个连续数据包来测试流式音频链路需确保采样率等设置与数据一致。典型调试流程在PCM Generator标签页选择麦克风、配置采样率/声道/位深录制并复制 Base64 字符串切换到Packet Player标签页粘贴数据可点 Add Packet 追加多段点击Decode Play All Packets验证收发链路是否正确。资源地图按需取用资源相对路径适用场景Multimodal Live API 目录入口gemini/multimodal-live-api/README.md全局导航与资源索引直接访问 API 入门intro_multimodal_live_api.ipynb理解底层调用Gen AI SDK 入门intro_multimodal_live_api_genai_sdk.ipynbPython 工程集成贷款文档问答RAGreal_time_rag_bank_loans_gemini_2_0.ipynb文档型实时语音问答零售实时 RAGreal_time_rag_retail_gemini_2_0.ipynb检索增强实时问答入门 Web 应用websocket-demo-app语音 摄像头最小可运行示例React 全功能客户端react-demo-app工具调用、流式传输、媒体处理纯 JS 最小实现plain-js-demo-app理解核心 API 机制Python SDK 后端示例plain-js-python-sdk-demo-app官方 SDK 后端集成实时顾问realtime-advisor-demo-app打断控制、知识注入、双模式客服智能体customer-support-demo-app情感对话、多模态、工具执行游戏助手gaming-assistant-demo-app人设切换、屏幕共享LiveKit ADK 多智能体livekit-adk企业级 WebRTC 语音编排PCM 调试工具pcm-audio-debuggerPCM 数据编解码验证结语从 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考