liveapi-service

LiveAPI Service Skill

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

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

前置条件

运行生成流程前，请确保主机上具备以下内容：

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

• 在运行生成的客户端的主机上配置了 Application Default Credentials：

  gcloud auth application-default login
  

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

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

参考文件

references/ 中提供的文件（不要将它们视为独立的 Skill——它们会按需加载）：

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

步骤

步骤 1：复制参考文件

将此 Skill 的 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，此后类 MUST 暴露以下异步方法：

• 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 和后端服务的服务（语言不限）。该服务 MUST 复用第 1 步中的 ClientMessage / ServerMessage proto 进行线路通信。用户应能通过 UI 执行以下操作：

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

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

处理 interrupt 信号

当 ServerMessage 的 server_content 中出现 interrupted: true 时，UI MUST：

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

处理转写 finished 信号

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

第 7 步：生成 how_to_test_with_ui.md

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

• 启动后端服务的准确 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 密钥进行身份验证。