gemini-multimodal-playground

用 Gemini 2.0 实时语音视频对话：在浏览器里"看见"AI思考

场景切入：为什么你需要这个工具？

想象这样一个画面：你在电脑前，戴着耳机，对着一个对话框说话。你的摄像头对准桌上的论文，屏幕另一端的 AI 不仅能听懂你说的每一句话，还能实时"看见"你翻到哪一页、指着哪段文字。当它回应时，声音不再是冷冰冰的文本，而是一个带着语调的真人式回答——这就是 gemini-multimodal-playground 正在做的事情。

Google 在 2024 年底开放了 Gemini 2.0 的实时多模态 API（目前 API 免费额度充足），允许开发者通过 WebSocket 直接向模型发送音频、视频帧和文本流，并接收实时的音频回复。这个项目就是围绕这一能力构建的完整应用。

项目背景与作者

saharmor/gemini-multimodal-playground 由独立开发者 Sahar Mor 创建维护。Sahar 是一位活跃的 AI 应用开发者，同时也是 AI Tidbits Newsletter 的运营者，长期关注 AI Agent、语音 AI 和多模态大模型领域。项目的目标非常明确：让开发者零门槛体验 Gemini 2.0 的实时多模态能力，无论是语音对话、视频分析还是屏幕共享。

项目采用 Apache-2.0 开源许可，代码结构清晰，提供两种使用形态：完整的全栈 Web 应用和轻量的独立 Python 脚本。

核心功能：从语音到视频的全模态交互

实时语音对话

项目支持通过麦克风实时输入语音，Gemini 2.0 模型以流式音频方式返回语音回复。支持选择不同的语音音色（Puck、Charon、Kore、Fenrir、Aoede 等），让 AI 的声音更加自然多样。语音通过 PyAudio 采集 PCM 格式数据，经 base64 编码后通过 WebSocket 发送到 Gemini 的 BidiGenerateContent API，响应中的音频数据同样通过 base64 返回给客户端播放。整个链路是端到端实时的。

视频输入（摄像头 + 屏幕共享）

除了语音，项目还支持两种视频输入模式：实时摄像头和屏幕共享。这意味着用户可以让 Gemini"看见"自己、文档、白板，或任何屏幕上的内容。结合语音指令，可以实现"帮我解释这张图"、"这个代码哪里有 bug"等非常自然的交互方式。视频帧以 JPEG 格式 base64 编码后随 WebSocket 消息发送。

全栈 Web 应用架构

项目采用经典的全栈分离架构：

• 后端（Python）：基于 FastAPI + Uvicorn，使用原生 websockets 库直连 Google Generative Language API 的 WebSocket 端点。每个客户端连接创建一个 GeminiConnection 实例，维护独立的 WebSocket 会话。FastAPI 的 WebSocket 路由处理客户端连接，在 receive_from_client 和 receive_from_gemini 两个异步任务中处理双向消息流，使用 asyncio.TaskGroup 并发运行。
• 前端（TypeScript / Next.js 15）：Next.js 15 + React 19 + Tailwind CSS + Radix UI，构建现代化的响应式界面。用户可在界面上配置系统提示词（System Prompt）、选择输入模式（视频/屏幕共享）、选择语音音色、开关 Google 搜索功能和打断功能。前端通过 WebSocket 与后端通信，将麦克风采集的音频数据实时推送到后端，同时播放后端转发回来的模型音频回复。

独立脚本版本

除了全栈版，项目还提供了 standalone 独立脚本版本，使用 Python Tkinter 构建桌面 GUI。Tkinter 内置的 VoiceEqualizer 组件提供实时音量条可视化，配合 voice_activity_detector 做语音活动检测。这个版本不需要 Node.js 环境，依赖更轻量，适合快速体验或作为二次开发的基础。

技术栈详解

后端核心技术亮点在于 GeminiConnection 类：它直接构建符合 Google Generative Language API 规范的 WebSocket 握手消息，设置 generation_config 中的 response_modalities: ["AUDIO"] 让模型返回音频流，并通过 system_instruction 注入系统提示词。整个通信完全基于 JSON-over-WebSocket，无需额外的 SDK 封装。

上手门槛

全栈 Web 版本需要同时配置 Python 后端和 Next.js 前端：

1. 申请 Google AI Studio API Key（免费）
2. 克隆代码后，创建 .env 文件填入 GEMINI_API_KEY
3. 后端：pip install -r requirements.txt && python backend/main.py
4. 前端：cd frontend && npm install && npm run dev
5. 浏览器打开 http://localhost:3000

独立脚本版本门槛更低，但需确保系统已安装 Tkinter（Linux 下需 apt-get install python3-tk）。配置好 API Key 后直接 python standalone.py 即可运行。

项目对硬件要求不高，无需 GPU。CPU 足够处理音频采集、WebSocket 转发和语音合成。唯一需要注意的是音频反馈问题——如果开启"允许打断"但使用扬声器而非耳机，麦克风会拾取 AI 的语音输出导致循环打断，建议使用耳机。

局限与风险

音频反馈问题：文档中专门提到 Gemini 可能被自己的输出打断，因为麦克风会采集到扬声器的声音。这是多模态实时语音系统的经典难题，项目提供了两种缓解方式：关闭"允许打断"或使用耳机，但无法从根本解决。

非生产级架构：项目定位是 Playground（游乐场），WebSocket 连接管理较为简单（基于内存字典的 connections），没有连接池管理、断线重连、限流等生产级考量，不适合直接作为生产服务部署。

Tkinter 依赖：Tkinter 是 Python 内置 GUI 库，但在某些精简 Linux 环境中可能缺失或版本不兼容，需要额外安装。

API 稳定性：项目依赖 Google Gemini 2.0 实验版 API（gemini-2.0-flash-exp），API 端点和数据格式可能在未来版本中发生变化。

行业意义与趋势

多模态 Agent 的基础设施价值：这个项目代表了一种新兴的 AI 应用架构——将大模型的实时多模态输入输出能力（语音、视频）封装为可用的应用层。与传统的"语音助手"不同，Gemini 2.0 的 WebSocket 实时 API 使得语音不再是"先转文字再处理再转语音"的三段式延迟，而是真正的端到端流式交互。

Web 应用 + 独立脚本的双轨策略：作者同时提供全栈 Web 版本和 Tkinter 独立脚本，体现了 AI 应用开发中的两种路径：Web 版适合远程协作和用户体验，独立脚本版适合快速本地实验。这种双轨设计在 AI 开源工具中越来越常见。

Gemini 2.0 的 API 开放意义：Google 开放 Gemini 实时 API 且提供免费额度（目前），正在降低多模态 AI 应用的开发门槛。这个项目是目前体验 Gemini 2.0 多模态能力最低成本的方案之一，对于 AI 爱好者理解实时语音视频交互的工作原理非常有价值。