mcpField
G
gemini-live-audio

gemini-live-audio

github.com/calesthio开发219105 次安装15 周前更新
代码仓库

关于 gemini-live-audio

gemini-live-audio 是面向实时语音交互的 Gemini Live API 使用技能,适用于构建支持轮流对话、打断和工具调用的语音体验。它涵盖双向流式会话的媒体传输、会话管理和工具响应处理,并区分不同部署与翻译模式。

主要功能

  1. 01通过 WebSocket 进行双向实时会话
  2. 02处理音频、图像及文本流
  3. 03配置转写、语音和轮次检测
  4. 04支持打断与函数调用流程
  5. 05管理会话恢复及部署边界

适用场景

  1. 01构建实时语音助手或接待系统
  2. 02在对话中调用函数或工具
  3. 03为语音交互提供字幕和记录
  4. 04搭建实时语音翻译流程

安装

复制下面的命令,在终端中运行。

$npx skills add https://github.com/calesthio/generative-media-skills --skill gemini-live-audio

安装后在 Claude Code 中输入/gemini-live-audio确认已加载。

附带文件EVAL.md

详细介绍

Gemini Live 音频

当任务涉及实时语音交互,而非批量生成旁白时,请使用此技能。Gemini Live 面向双向会话:输入麦克风音频或流式媒体,输出模型语音,并处理轮流发言、中断、工具和会话生命周期等问题。如果交付内容是完成的配音、有声书、播客旁白或离线转录,除非用户明确需要实时轮流发言,否则应优先选择 TTS 或语音转文本技能。

以下所有时效性信息均已于 2026-07-10 根据 Google AI 和 Google Cloud 官方文档核实。模型名称、预览版/正式发布状态、价格、速率限制、支持区域和治理控制经常变化;在生产环境上线、做出采购承诺或部署到受监管环境前,请重新查阅官方文档。

已记录的事实

产品当前形态
  • Gemini Live API 是一种有状态的 WebSocket API,适用于低延迟语音和视觉交互。它可以处理连续的音频、图像、文本流;API 参考文档中还提到视频。它会返回语音/音频输出,并且可根据配置和模型返回文本/函数调用事件。
  • Google AI Live API 页面目前指出,Interactions API 已正式发布,并建议使用它来获取最新功能和模型。请将此技能视为专用于 Live API 的指南;对于从零开始构建的生产级 Agent,请先确认 Google 推荐使用 Live API 还是 Interactions API,再确定架构。
  • Google AI Developer API 文档将 Live API 标记为预览版。Google Cloud / Gemini Enterprise Agent Platform 文档则单独说明了 Vertex/企业版的可用性,以及正式发布的 Gemini 2.5 Flash Native Audio 模型。请将 Developer API 和 Gemini Enterprise Agent Platform 视为不同的部署平台,它们在身份验证、条款、区域、治理、配额和支持方面均有差异。
  • 截至 2026-07-10,文档记录的主要 Live Agent 模型系列包括 Developer API 文档中的 gemini-3.1-flash-live-preview,以及 Gemini Enterprise Agent Platform 文档中的 gemini-live-2.5-flash-native-audio / Gemini 2.5 Flash Live API Native Audio。Live Translation 单独记录为 gemini-3.5-live-translate-preview。
  • 当模型是能够推理、提问、调用工具并处理轮次的助手时,请使用 Live Agent 模式。当模型是口译流程——输入一种语言的音频,输出另一种语言的译音——时,请使用 Live Translation 模式。文档说明,Live Translation 仅支持音频,且仅用于翻译,并非由工具/指令驱动的 Agent 平台。
媒体与传输边界
  • 传输:持久 WSS 会话。使用 SDK 时,采用 Live 连接/会话抽象;使用原始 WebSocket 时,连接到文档所述的 BidiGenerateContent 端点,并自行管理 JSON 消息、设置、实时输入、服务端内容、工具调用和关闭。
  • 会话设置在连接开始时完成。初始设置消息/配置包括模型、响应模态、生成参数、系统指令和工具。不要假设可以在连接中自由更改模型;对于重大变更,应设计重新连接/恢复路径。
  • 音频输入:原始小端序 16 位 PCM。原生输入采样率为 16 kHz;文档称 Live API 可以重采样,但生产环境中的客户端除非有经过测量的理由,否则应发送 audio/pcm;rate=16000。
  • 音频输出:原始小端序 16 位 PCM,采样率为 24 kHz。
  • 将麦克风音频切分为较小的帧。Google 的最佳实践建议使用 20-40 ms 的分块以降低延迟,并警告不要大量缓冲输入。除非有意牺牲延迟来换取稳定性,否则客户端缓冲的实际上限为 100 ms。
  • Developer API 概览文档说明,图像为 JPEG 格式,最高支持 1 FPS。视频/图像输入支持情况及定价因模型和服务平台而异;在承诺支持实时屏幕共享、摄像头或帧输入前,请核实具体模型页面。
  • 原生音频 Live 模型支持音频响应模态。如果产品需要获取模型口述回答的文本,请启用输出音频转写,不要假设原生音频响应会输出文本。
转写、语言、语音与轮次交接
  • 启用会话配置后,Live API 支持转写用户输入和模型输出的音频。可将这些转写用于 UI 字幕、日志、QA 和交接摘要;未经单独验证,不要将其宣传为可用于法庭的转写稿。
  • Developer 文档列出了 Live 对多种语言的广泛支持;概览强调语音 Agent 用例支持 70 种语言,而功能页面目前列出支持 97 种语言。原生音频模型可以自然切换语言;如需限制语言行为,请在系统指令中指定输出语言。非原生/级联模型可以使用 speech_config.language_code。
  • 语音选择通过 speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName 配置。官方文档为 Gemini Live API / Native Audio(Vertex)列出了 30 种语音选项,并指出原生音频模型可以使用 AI Studio 中可用的 TTS 语音集。提供具体语音名称前,请务必核实当前语音列表。
  • 支持用户插话。当用户在模型说话时开口,服务端可以发送中断信号。客户端必须立即停止/丢弃排队的播放内容;否则用户会听到过时音频,并觉得系统没有理会自己。
  • 可以配置自动 VAD,也可以禁用自动 VAD,由客户端发送 activityStart 和 activityEnd。使用自动 VAD 时,prefixPaddingMs 可保护词语的起始部分,silenceDurationMs 控制轮次结束延迟。Google 文档指出,500-800 ms 的静音时长是较好的平衡,并警告过低的阈值会导致话语被截断;手动 VAD 应包含说话前的上下文,并避免过于激进地截断语音结束部分。
  • Proactive Audio 和 Affective Dialog 是 Gemini 2.5 Flash Live API Native Audio 文档所述的原生音频功能。只有在获得用户明确同意并制定 QA 计划后,才将其用于环境感知或面向设备的体验;这些功能会改变系统响应的时机和原因。
工具和 Agent 行为
  • Live API 支持函数调用和 Google Search grounding。它并不支持所有非 Live 工具;截至 2026-06-01 的 Live 工具页面上,官方工具表列出的 Google Maps、代码执行和 URL context 均不受所比较的 Live 模型支持。
  • 与某些非 Live SDK 工作流不同,Live API 不会自动处理工具响应。客户端必须接收工具调用事件、执行/调度允许的函数,并将 FunctionResponse 对象发回。
  • 不同模型的工具行为有所不同。文档列出,Gemini 3.1 Flash Live Preview 的函数调用仅支持同步方式,而 Gemini 2.5 Flash Live Preview 支持同步和异步函数调用。除非所选模型官方支持非阻塞工具,否则不要承诺提供此类工具。
  • 对于支持的非阻塞工具,应审慎设计函数声明和响应调度方式:中断、等到空闲,或静默存储/稍后使用。时机不当的工具响应可能会导致 Agent 打断敏感语音,或忽略重要事件。
  • 使用 Google Search grounding 可以提升信息的时效性,但也涉及定价和数据保留方面的影响。在隐私敏感或零保留范围内,请确认是否允许使用 Search grounding。
会话、身份验证、费用、配额和治理
  • 如果不压缩上下文窗口,文档中说明的会话时长限制为:仅音频会话 15 分钟,音频+视频会话 2 分钟。Google 还说明,连接的生命周期约为 10 分钟。对于生产环境中的长时间会话,请使用上下文窗口压缩和会话恢复。
  • 会话恢复需要接收并存储恢复句柄/令牌,并使用最新句柄重新连接。Developer API 文档提到恢复令牌的有效期为 2 小时;Gemini Enterprise 零数据保留文档称,Live 会话恢复会存储缓存数据,包括文本/视频/音频提示数据和模型输出,最长 24 小时。请将这些视为特定服务界面的规则,并在承诺数据保留期限前进行核实。
  • 不同模型类别的上下文窗口各不相同:Google 文档列出的原生音频输出模型为 128k 个令牌,其他 Live 模型为 32k 个令牌。音频令牌累积很快;Google 文档按每秒约 25 个令牌计价/计数音频。
  • 速率限制按项目计算,并随模型和使用层级而异。实验版/预览版模型通常有更严格的速率限制。进行负载测试前,请在 AI Studio 或 Google Cloud 中查看当前限制。
  • Developer API 在 2026-07-10 列出的付费价格中,gemini-3.1-flash-live-preview 的价格为:每百万个文本输入令牌 $0.75、每百万个音频输入令牌 $3.00(约每分钟 $0.005)、每百万个图像/视频输入令牌 $1.00(约每分钟 $0.002)、每百万个文本输出令牌 $4.50,以及每百万个音频输出令牌 $12.00(约每分钟 $0.018)。根据每秒 25 个音频令牌计算,Live Translate 音频的输入/输出合计价格约为每分钟 $0.0368。引用价格前请再次核实。
  • Developer API 免费层的内容可能会被用于改进 Google 产品;文档说明付费层的内容不会用于改进产品。启用后,Developer API 日志可能会因项目日志记录而保留;滥用监控/grounding 另有各自的保留规则。对于受监管的用户,请评估 Gemini Enterprise Agent Platform,而不要默认使用 API 密钥。
  • Gemini Enterprise Agent Platform 使用 Google Cloud 身份验证/IAM、区域/全球端点、企业支持/SLA 选项、预配吞吐量和数据驻留控制。仅选择端点并不能保证数据驻留;Cloud 文档区分了端点路由与静态数据及 ML 处理方面的承诺。全球端点可最大限度提高可用性/降低延迟,但不提供区域隔离。
  • 要在 Gemini Enterprise Agent Platform 上实现零数据保留,请勿启用请求-响应日志记录或 Live 会话恢复,了解滥用监控的例外情况,并考虑内存缓存设置。对于 Developer API 的 ZDR,付费服务有训练限制,但 Search/Maps grounding 和滥用监控有各自的保留限制。

实证/运维观察

此技能未附带任何第一方基准测试。请勿编造延迟或质量数据。如果用户关注延迟,请在目标网络、浏览器/设备、模型和部署服务界面上进行项目专属测量。

生产语音系统的运维观察结果,必须在目标应用中验证:

  • 感知延迟通常主要由麦克风采集、VAD 语音结束延迟、客户端缓冲、播放调度和重连处理决定,而不只是模型推理。
  • 如果插话处理导致输出缓冲区中残留过时音频,即使演示效果出色,也可能无法在生产环境中正常运行。
  • 与文本聊天相比,Live 函数调用需要更严格的架构和流程设计,因为用户通过语音交互时,难以在操作执行前检查或编辑参数。
  • 应分别测试实时翻译和语音 Agent 行为;适用于强大助手的设置可能并不适合翻译,因为翻译需要低延迟的持续流式传输,而不是需要深思熟虑的轮次。

生产环境启发式建议

选择合适的 Gemini Live 模式

当用户需要以下功能时,使用 Gemini Live Agent:

  • 语音助手、教练、导师、礼宾人员、采访者、接待员、NPC、操作员或视觉辅助 Agent;
  • 插话和自然的轮流对话;
  • 实时使用工具/调用函数;
  • 对话中的屏幕/摄像头/图像上下文;
  • 语音互动的同时显示转录文本。

当用户需要以下功能时,使用 Live Translation:

  • 低延迟的语音到语音口译;
  • 从源语言到目标语言的音频转换;
  • 不需要工具、Agent 操作、多模态推理,也不需要超出口译行为的、过多依赖特定人设的对话。

当用户需要以下功能时,不要将 Gemini Live 作为主要工具:

  • 精心制作的预录旁白文件;
  • 为现有视频确定性地生成字幕;
  • 带词级时间戳的离线批量转录;
  • 长篇音频母带处理、音乐或音效;
  • 未经法律审核同意、录音、保留期限和升级处理要求的受监管呼叫中心部署。
架构选择

对于原型和可信的服务端环境,后端到 Gemini 的 WebSocket 方案最简单:

  1. 浏览器/移动端采集麦克风音频,以及可选的摄像头/屏幕帧。
  2. 客户端通过 WebRTC/WebSocket 将数据流传输到你的后端。
  3. 后端向 Gemini 进行身份验证,应用策略/工具限制,并转发获准的媒体。
  4. 后端返回音频块、转录事件、工具调用确认和状态更新。

若要实现客户端直连 Gemini 的最低延迟,请使用临时令牌:

  1. 客户端向你的后端进行身份验证。
  2. 后端请求临时令牌,最好将令牌限制在指定模型/配置/工具策略范围内。
  3. 客户端使用该令牌打开 Live API WebSocket。
  4. 后端仍负责控制工具执行、用户身份、日志记录策略和升级处理。

只有在仍能保护密钥、限制可用工具、记录用户同意并监控滥用行为时,才优先选择客户端直连 Gemini。切勿在浏览器或移动应用中放入长期有效的 API 密钥。

语音 Agent 的系统指令设计

将 Live Agent 指令写成操作策略,而不是长篇说明:

  1. 人设和角色:Agent 的身份、声音/语气、领域和语言。
  2. 对话流程:哪些问题只问一次、哪些内容可以重复,以及何时进行总结。
  3. 工具策略:每个函数的确切调用条件、执行有实质影响的操作前必须获得的确认,以及等待期间应说什么。
  4. 安全/同意边界:录音告知、紧急情况处理限制、隐私和升级处理。
  5. 回复风格:语音回复简短、每次只问一个问题、不使用 Markdown、不透露隐藏的思维链。

对于语音体验,默认应保持回复简短。每轮只问一个问题。调用会花费资金、更改账户、进行预订、发送消息或披露敏感数据的工具前,先用语音确认高风险事实。

音频和延迟设置

除非测量结果表明需要调整,否则请从以下设置开始:

  • 输入格式:单声道 PCM16 小端序,采样率为 16 kHz;
  • 输出播放:PCM16,采样率为 24 kHz;
  • 输入块大小:20-40 ms;
  • 自动 VAD 静音时长:500-800 ms;
  • 前缀填充:设置为非零值;通过首音节被截断的测试进行调整;
  • 客户端输入缓冲区:在网络连接稳定的前提下尽可能小,通常低于 100 ms;
  • 播放缓冲区:设置为足以避免咔嗒声/中断,但在被打断时立即丢弃;
  • 会话生命周期:长时间通话时启用上下文压缩;实现 GoAway 和重新连接/恢复逻辑。
语音工具调用安全

在向用户开放工具前,先对其分类:

  • 只读工具:天气、订单状态、产品查询。用户提出请求时,通常可以直接运行,无需确认。
  • 低影响写入工具:创建草稿、添加备注、设置提醒。如果内容很重要,则需确认。
  • 高影响写入工具:购买、提交表单、取消服务、发送消息、解锁门、更新财务/健康/法律数据。必须明确确认,并口头概述参数。
  • 后台工具:长时间搜索、CRM 查询、RAG、创建工单。仅在模型支持且用户体验仍然易于理解时,才以非阻塞方式使用。

将函数架构设计得范围明确。包含枚举、单位、区域设置、时区、不可逆/操作标记,以及工具响应中面向用户的确认文本。不要依赖模型根据函数名称推断策略。

治理与同意

在将 Live 音频体验投入生产前,请记录:

  • 音频是录制还是仅串流;
  • 是否存储转录文本、存储多久,以及谁可以访问;
  • 应用使用的是 Developer API 免费层、付费层还是 Gemini Enterprise Agent Platform;
  • grounding、日志记录、会话恢复或缓存是否会改变数据保留情况;
  • 是否告知用户他们正在与 AI 对话;
  • 当地法律是否要求通话录音获得双方同意;
  • 针对紧急情况、未成年人、医疗/法律/财务建议或虐待问题的升级处理路径。

关于语音相似度和媒体权利,除非 Google 明确支持该工作流,且用户已记录相关权利/同意,否则不要暗示 Gemini 语音是克隆的人类语音。避免未经授权的提示词,模仿真人、名人、员工或客户。

完整示例

示例 1:带订单查询功能的零售支持语音 Agent

生产目标:低延迟语音助手回答产品和订单相关问题、查询订单状态,并且仅在获得确认后创建退货标签。

适用模式:Gemini Live Agent,而非 Live Translation。

需验证的模型/平台:在 Developer API 上使用 gemini-3.1-flash-live-preview 进行原型开发;对于生产支持、IAM、数据驻留以及支持/SLA,请考虑使用 Gemini Enterprise Agent Platform。

输入和限制:

  • 浏览器麦克风,面向英语和西班牙语用户,无摄像头。
  • 需要转录文本用于支持质量检查。
  • 只读工具 get_order_status(order_id, postal_code)。
  • 写入工具 create_return_label(order_id, reason) 需要确认。
  • 不修改付款信息,不提供医疗/法律建议。

会话配置示意:

{
  "model": "gemini-3.1-flash-live-preview",
  "response_modalities": ["AUDIO"],
  "output_audio_transcription": {},
  "input_audio_transcription": {},
  "speech_config": {
    "voice_config": {
      "prebuilt_voice_config": { "voice_name": "Kore" }
    }
  },
  "realtime_input_config": {
    "automatic_activity_detection": {
      "prefix_padding_ms": 300,
      "silence_duration_ms": 700
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "get_order_status",
          "description": "Look up status for an authenticated order when the user provides order ID and postal code.",
          "parameters": {
            "type": "object",
            "properties": {
              "order_id": { "type": "string" },
              "postal_code": { "type": "string" }
            },
            "required": ["order_id", "postal_code"]
          }
        },
        {
          "name": "create_return_label",
          "description": "Create a return shipping label only after the user explicitly confirms the order ID and return reason.",
          "parameters": {
            "type": "object",
            "properties": {
              "order_id": { "type": "string" },
              "reason": { "type": "string" },
              "confirmed_by_user": { "type": "boolean" }
            },
            "required": ["order_id", "reason", "confirmed_by_user"]
          }
        }
      ]
    }
  ]
}

系统指令摘录:

You are Mira, a concise retail support voice assistant.
Speak in the user's language when you can do so clearly.
Ask one question at a time. Keep spoken answers under 20 seconds unless the user asks for detail.
For order lookup, collect order ID and postal code, then call get_order_status.
Before creating a return label, summarize the order ID and reason, ask "Should I create the return label now?", and call create_return_label only if the user explicitly says yes.
Never ask for full payment card numbers. If the user asks for a refund decision, explain you can create a return request but a human reviews refunds.
If the user interrupts, stop your current explanation and answer the new question.

预期结果:

  • 对话自然流畅,可快速处理打断;通过语音和 UI 转录文本返回订单状态。
  • 仅在获得明确确认后才创建退货标签。

失败模式:

  • Agent 在获得确认前调用 create_return_label。
  • 被打断后音频仍继续播放。
  • VAD 截断订单号或邮政编码。
  • 语言自动切换让质量检查团队感到意外;如有需要,请在指令中限制语言。
  • 不必要地启用搜索 grounding,导致数据保留/成本方面的风险。

变体:

  • 改用经后端代理的架构,以便更严格地控制工具。
  • 仅在 WebSocket 媒体路径中使用临时令牌,同时由后端管理工具。
  • 只有在验证模型支持情况、会话时长、成本和用户同意后,才添加摄像头/屏幕。
示例 2:实时语音到语音的活动翻译

生产意图:为远程听众近乎实时地将演讲者的日语翻译成英语。

适用模式:使用 gemini-3.5-live-translate-preview 进行实时翻译,而非通用 Live Agent。

输入与限制:

  • 单路演讲者音频,无工具,无助手角色设定。
  • 目标语言为英语。
  • 音频必须保持连续;转录稿有帮助,但不是主要交付内容。
  • 关键片段需由人工口译员兜底。

工作流:

  1. 确认当前 Live Translation 文档中支持源语言和目标语言。
  2. 配置 Live API 的翻译设置,包括源语言和目标语言。
  3. 将演讲者音频采集为 PCM16,以 20-40 ms 为块并持续流式传输。
  4. 播放翻译后的输出,并将抖动缓冲区调优为优先保证清晰易懂,而非应对频繁打断的对话。
  5. 记录输入/输出时间、丢帧、误译和听众反馈。

预期结果:

  • 系统表现为翻译流水线,不会提出澄清问题、调用工具或采取行动。

故障模式:

  • 使用了 Agent 提示词,导致系统生成摘要或回复,而不是直接翻译。
  • 应用等待完整轮次结束,造成不可接受的延迟。
  • 混合语言切换或名称被误译;如果 API 支持,请提供术语表/上下文并提前测试。
  • 未审核敏感活动音频的保留情况。

变体:

  • 对于用户要求 AI 做笔记或调用工具的双语会议,应使用 Live Agent 加翻译策略,而非 Live Translation。
  • 对于广播质量的字幕,应在活动结束后单独进行转录/字幕质量审核。
示例 3:现场技术人员视觉支持 Agent

生产意图:技术人员将移动摄像头对准设备并提出口头问题。Agent 可以识别可能的部件、要求用户换个角度拍摄,并创建支持工单。

适用模式:如果所选模型/界面支持,则使用 Gemini Live Agent,并输入音频和低帧率图像/视频。

输入与限制:

  • 移动设备麦克风和摄像头帧。
  • 不得声称能够做出确定性的安全诊断。
  • 工具 create_support_ticket(summary, severity, asset_id, photo_refs) 需要用户确认。
  • 会话可能超过 2 分钟,因此必须实现压缩/恢复或会话交接。

系统指令摘录:

You are an equipment support assistant for trained technicians.
Use visual context only to guide inspection; do not certify equipment as safe.
Ask for a closer view, better lighting, or label photo when needed.
If a potential hazard is visible or described, tell the technician to follow their site safety procedure and stop remote troubleshooting.
Before creating a support ticket, summarize the observed issue, asset ID, severity, and photos to attach, then ask for confirmation.

预期结果:

  • 提供简短的语音指导;视觉输入不足时要求提供更清晰的画面;使用审慎的安全措辞;创建工单前先确认。

故障模式:

  • 未实现压缩/恢复/交接,导致会话在文档所述的音频+视频时限后终止。
  • 视觉帧频率过低或模糊,无法提供可靠指导。
  • Agent 对诊断或安全问题言过其实。
  • 工具调用包含用户未批准或数据策略不允许的图像/音频。

变体:

  • 如果摄像头流式传输成本过高或无法使用,则应按用户请求采集静态图像,并以 <=1 FPS 发送。
  • 在确认模型/位置支持后,使用 Gemini Enterprise 区域端点进行数据治理。

生产环境 QA 检查清单

发布前,请在真实设备和嘈杂环境中进行测试:

  • 音频格式:验证输入为 PCM16 单声道、输入采样率为 16 kHz、输出播放采样率为 24 kHz,并确认原始音频块没有端序或 WAV 头错误。
  • 延迟:测量从麦克风输入到首段音频、语音结束到首段音频、中断到静音、重新连接时间,以及工具调用往返时间。
  • 插话:在模型说话时,用简短、较长和嘈杂的语句进行打断;确认会丢弃过时的输出。
  • VAD:测试首个音节被截断、句中停顿、长时间思考停顿、简短确认、序列号和带口音的语音。
  • 转录文本:将输入/输出转录文本与录音进行比较,以评估是否达到产品要求的准确度;若未经过正式验证,请将其标记为辅助功能。
  • 工具:模拟缺少参数、请求含糊、函数重复调用、响应延迟、工具错误,以及需要确认的高影响操作。
  • 会话生命周期:测试 2 分钟、10 分钟、15 分钟、重新连接、GoAway、上下文压缩和恢复行为。
  • 成本:估算每分钟输入和输出音频令牌成本,以及 Search/工具成本;设置支出和速率限制警报。
  • 隐私:验证同意提示、录音指示、日志保留、转录文本存储、grounding 保留期限以及 ZDR 约束。
  • 安全:使用已配置的安全设置,测试骚扰、自残、医疗/法律/金融、紧急情况、未成年人及不允许的冒充场景。

来源清单

以下官方来源已于 2026-07-10 查阅并核实:

评论

支持 Markdown