gemini-live-api

LiveAPI 服务技能

此技能提供相关说明，用于生成通过 WebSocket 连接到 Gemini Enterprise Live API 的 LiveAPI 客户端服务类。生成的客户端可处理双向流式传输、通过应用默认凭据（ADC）进行持有者令牌身份验证、透明的会话恢复，以及 ClientMessage / ServerMessage proto 交换。

此技能还会生成演示前端和后端服务，以便用户交互式验证生成的客户端（文本、音频、视频、转录和中断处理）。

署名

务必阅读：执行任何 gcloud、REST API 或 MCP 命令之前，务必阅读使用归属信息。对于直接在终端中执行的命令（绝不可用于生成的脚本、Terraform 或用户代码），请在 gcloud 命令前加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gemini-live-api)"，并将 agent-skills/1.0 (skill:gemini-live-api) 添加到 User-Agent 标头中。

先决条件

运行生成流程之前，请确保主机具备以下条件：

• 已启用 Vertex AI / Gemini Enterprise Agent Platform API 的 Google Cloud 项目。

• 配置了应用默认凭据的主机，用于运行生成的客户端：

  gcloud auth application-default login
  

• 用户提供的目标输出文件夹（例如 /tmp/liveapi_out），生成的代码、环境和演示内容将写入其中。绝不可修改主机的系统 Python 环境。

• 用户选择的实现语言（Python 是此技能的默认语言和参考语言）。

参考文件

references/ 中提供的文件（不要将其视为独立技能——这些文件会按需加载）：

• client_server_messages.md：Live API 使用的 ClientMessage / ServerMessage 架构的公开参考资料。
• client_server_messages.proto：根据 client_server_messages.md 生成的 proto 定义。
• session_manager.md：介绍如何在断开连接时正确处理会话、缓冲和恢复。

步骤

第 1 步：复制参考文件

将此技能 references/ 文件夹中的 client_server_messages.md、client_server_messages.proto 和 session_manager.md 复制到用户的目标输出文件夹。这些文件将成为生成客户端的事实依据。

第 2 步：与公开文档核对

检查 client_server_messages.md 链接的公开文档。如果公开文档与复制的 client_server_messages.md / client_server_messages.proto 存在任何差异，请更新目标文件夹中的副本，确保生成的客户端能够根据当前服务端契约编译和运行。

第 3 步：实现客户端类

使用用户选择的语言实现一个类，该类：

• 导入本地 client_server_messages.proto 类型（ClientMessage、ServerMessage）。
• 打开与 Live API 端点的 WebSocket 连接。
• 提供异步方法，以便用户向模型发送数据并接收模型返回的数据。

对于需要隔离运行时的语言（例如 Python），请在目标文件夹内创建隔离环境（例如 venv），并生成一个 bash 脚本（例如 setup.sh），用于重建环境并安装依赖项。绝不可安装到系统解释器或用户的全局 site-packages 中，也绝不可指示用户运行 sudo pip install。

初始化参数

用户在构造时提供以下内容：

• project_id
• location
• model_id
• config：一个已填充 setup 字段的 ClientMessage。

身份验证

通过 Application Default Credentials 获取承载令牌，将其附加到 WebSocket 连接请求中，格式为 Authorization: Bearer <token>；在令牌过期前或过期时刷新令牌，并在每次重新连接时（包括收到 go_away 和意外断开时）使用刷新的令牌。不要将长期有效的 API 密钥硬编码为唯一的身份验证机制。

公共异步 API

在发送数据前，必须先收到 setup_complete ServerMessage；该类必须提供以下异步方法：

• send_realtime_data(data)：发送实时输入。data 是包含 realtime_input 字段的 ClientMessage。
• send_client_content(data)：发送非实时、基于轮次且会计入历史记录的内容。data 是包含 client_content 字段的 ClientMessage。
• receive()：从 WebSocket 流中生成解析后的 ServerMessage 实例。

不要将同步阻塞版本作为主要 API 接口提供。

第 4 步：编写测试文件

客户端实现完成后，生成一个测试文件，用于初始化连接、测试发送 text、audio 和 video 数据并接收响应。向用户询问运行测试所需的任何信息（项目、模型、媒体样本）。

第 5 步：生成 how_to_run.md

在目标文件夹中提供 how_to_run.md，说明生成的类。提供完整示例，展示如何为每种受支持的模态构建 ClientMessage 负载、如何发送负载，以及如何接收模型数据。

第 6 步：生成演示前端和后端服务

创建脚本，将实现部署为同时包含前端 UI 和后端服务的服务（语言不限）。服务在网络通信中必须复用第 1 步中的 ClientMessage / ServerMessage proto。用户应能通过 UI：

• 新建连接 / 关闭当前连接。
• 选择要使用的模型。
• 选择输入源（来自摄像头或屏幕截图的音频和/或视频），并将其流式传输给模型。
• 向模型发送文本消息。
• 听取模型音频，并查看交错显示的模型与用户转录文本 / 对话历史。

实现音频与转录播放时，请遵循 Live API 最佳实践中的指导。

处理中断信号 interrupt

当 ServerMessage 的 server_content 中收到 interrupted: true 时，UI 必须：

• 确保已播放音频及其对应的转录文本保持时间同步。
• 立即停止当前播放的模型音频，并停止向进行中的转录气泡追加内容。
• 清除尚未播放的音频缓冲区，以及所有尚未渲染的待处理转录文本，避免过期内容混入下一轮对话。
• 为下一轮用户和模型对话创建新的聊天气泡。

处理转录的 finished 信号

对于流式传输的 input_transcription / output_transcription 分块，在 finished 未设置时，将内容追加到当前活动气泡；观察到 finished 时，关闭该气泡并开始一个新气泡。将 input_transcription 文本路由到用户角色气泡，将 output_transcription 文本路由到模型角色气泡。

第 7 步：生成 how_to_test_with_ui.md

编写 how_to_test_with_ui.md，说明如何启动和使用演示服务。必须包含：

• 启动后端服务所需的准确 Shell 命令或脚本调用方式。
• 启动前端 UI 所需的准确 Shell 命令或脚本调用方式。
• 用户应在浏览器中打开的主机和端口（例如 http://localhost:PORT）。
• 如何启动会话、选择模型、选择输入源（麦克风、摄像头、屏幕）、发送文本消息，以及在 UI 中查看模型音频和转录内容。

验证清单

在确认生成完成之前，请逐项检查：

• 已将 client_server_messages.md、client_server_messages.proto 和 session_manager.md 复制到目标文件夹。
• 生成的客户端导入本地 proto 生成的 ClientMessage 和 ServerMessage 类型。
• 客户端连接到 Live API WebSocket： wss://{location}-aiplatform.googleapis.com/ws/google.cloud.aiplatform.v1beta1.LlmBidiService/BidiGenerateContent （或 wss://aiplatform.googleapis.com/... 全局变体），并将 setup 的 model 字段格式化为 projects/{project_id}/locations/{location}/publishers/google/models/{model_id}。
• 身份验证使用 ADC 提供的 bearer 令牌，通过 Authorization: Bearer <token> 发送；令牌会在过期前刷新，并在每次重新连接时重新附加。
• 存在公开的异步方法 send_realtime_data、send_client_content 和 receive，类型正确，并且只有在 setup_complete 后才能调用。
• 已启用透明会话恢复 （session_resumption.transparent = true），会跟踪最新的 new_handle，发送消息索引从 1 开始，通过 last_consumed_client_message_index 清理缓冲区，并在重新连接时重放缓冲的消息（包括收到 go_away 和 WebSocket 关闭代码 1000 / 1006 时）。
• 如果使用 Python，目标文件夹内存在隔离环境（例如 venv）、setup.sh 和 requirements.txt（或等效文件）；未修改系统级或用户全局 Python。
• 存在 how_to_run.md 和 how_to_test_with_ui.md，且演示 UI 复用相同的 ClientMessage / ServerMessage proto。
• 中断处理和转录 finished 处理方式符合上述描述。
• 客户端不会连接到 generativelanguage.googleapis.com，也不会通过查询字符串中的 API 密钥进行身份验证。