Live API 支持与 Gemini 建立低延迟的双向语音和视频互动。借助 Live API,您可以为最终用户提供自然的、类似人类的语音对话体验,并能够使用语音指令中断模型的回答。Live API 可以处理文本、音频和视频输入,并提供文本和音频输出。
如需详细了解 Live API,请参阅 Live API。
功能
Live API 包含以下主要功能:
- 多模态:模型可以看、听和说。
- 低延迟实时互动:模型可以快速提供回答。
- 会话记忆:模型会记住单个会话中的所有互动,并回忆之前听到或看到的信息。
- 支持函数调用、代码执行和“将搜索作为工具”:您可以将模型与外部服务和数据源集成。
Live API 专为服务器到服务器的通信而设计。
对于网站和移动应用,我们建议您使用 Daily 合作伙伴提供的集成。
支持的模型
开始使用
如需试用 Live API,请前往 Vertex AI Studio,然后点击开始会话。
Live API 是一种使用 WebSockets 的有状态 API。
本部分展示了一个示例,说明如何使用 Live API 进行文本到文本生成(使用 Python 3.9 及更高版本)。
Python
安装
pip install --upgrade google-genai
如需了解详情,请参阅 SDK 参考文档。
设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True
集成指南
本部分介绍了集成如何与 Live API 搭配使用。
会话
WebSocket 连接会在客户端与 Gemini 服务器之间建立会话。
客户端发起新连接后,会话可以与服务器交换消息,以执行以下操作:
- 向 Gemini 服务器发送文本、音频或视频。
- 接收来自 Gemini 服务器的音频、文本或函数调用请求。
会话配置在连接后的第一条消息中发送。会话配置包括模型、生成参数、系统指令和工具。
请参阅以下示例配置:
{
"model": string,
"generationConfig": {
"candidateCount": integer,
"maxOutputTokens": integer,
"temperature": number,
"topP": number,
"topK": integer,
"presencePenalty": number,
"frequencyPenalty": number,
"responseModalities": [string],
"speechConfig": object
},
"systemInstruction": string,
"tools": [object]
}
如需了解详情,请参阅 BidiGenerateContentSetup。
发送消息
消息是通过 WebSocket 连接交换的 JSON 格式的对象。
如需发送消息,客户端必须通过打开的 WebSocket 连接发送 JSON 对象。JSON 对象必须包含以下对象集中的一个字段:
{
"setup": BidiGenerateContentSetup,
"clientContent": BidiGenerateContentClientContent,
"realtimeInput": BidiGenerateContentRealtimeInput,
"toolResponse": BidiGenerateContentToolResponse
}
支持的客户端消息
请参阅下表中的支持的客户端消息:
消息 | 说明 |
---|---|
BidiGenerateContentSetup |
要在第一条消息中发送的会话配置 |
BidiGenerateContentClientContent |
从客户端传送的当前对话的增量内容更新 |
BidiGenerateContentRealtimeInput |
实时音频或视频输入 |
BidiGenerateContentToolResponse |
对从服务器收到的 ToolCallMessage 的响应 |
接收消息
如需接收来自 Gemini 的消息,请监听 WebSocket“message”事件,然后根据支持的服务器消息的定义解析结果。
请参阅以下内容:
ws.addEventListener("message", async (evt) => { if (evt.data instanceof Blob) { // Process the received data (audio, video, etc.) } else { // Process JSON response } });
服务器消息将包含以下对象集中的一个字段:
{
"setupComplete": BidiGenerateContentSetupComplete,
"serverContent": BidiGenerateContentServerContent,
"toolCall": BidiGenerateContentToolCall,
"toolCallCancellation": BidiGenerateContentToolCallCancellation
"usageMetadata": UsageMetadata
"goAway": GoAway
"sessionResumptionUpdate": SessionResumptionUpdate
"inputTranscription": BidiGenerateContentTranscription
"outputTranscription": BidiGenerateContentTranscription
}
支持的服务器消息
下表列出了支持的服务器消息:
消息 | 说明 |
---|---|
BidiGenerateContentSetupComplete |
来自客户端的 BidiGenerateContentSetup 消息,在设置完成后发送 |
BidiGenerateContentServerContent |
模型根据客户消息生成的内容 |
BidiGenerateContentToolCall |
请求客户端运行函数调用并返回具有匹配 ID 的响应 |
BidiGenerateContentToolCallCancellation |
当函数调用因用户中断模型输出而被取消时发送 |
UsageMetadata |
报告会话到目前为止使用的令牌数 |
GoAway |
表示当前连接即将终止的信号 |
SessionResumptionUpdate |
可恢复的会话检查点 |
BidiGenerateContentTranscription |
用户或模型的语音转写内容 |
增量内容更新
使用增量更新来发送文本输入、建立会话上下文或恢复会话上下文。对于简短的上下文,您可以发送逐轮互动来表示确切的事件序列。对于较长的上下文,建议提供单个消息摘要,以便为后续互动腾出上下文窗口。
请参阅以下示例上下文消息:
{ "clientContent": { "turns": [ { "parts":[ { "text": "" } ], "role":"user" }, { "parts":[ { "text": "" } ], "role":"model" } ], "turnComplete": true } }
请注意,虽然内容部分可以是 functionResponse
类型,但不应使用 BidiGenerateContentClientContent
来提供对模型发出的函数调用的回答。应改用 BidiGenerateContentToolResponse
。BidiGenerateContentClientContent
仅应用于建立之前的对话背景信息或向对话提供文本输入。
流式音频和视频
代码执行
如需详细了解代码执行,请参阅代码执行。
函数调用
所有函数都必须在会话开始时声明,方法是将工具定义作为 BidiGenerateContentSetup
消息的一部分发送。
您可以使用 JSON(具体来说是 OpenAPI 架构格式的选定子集)来定义函数。单个函数声明可以包含以下参数:
name(字符串):API 调用中函数的唯一标识符。
description(字符串):对函数用途和功能的全面说明。
parameters(对象):定义函数所需的输入数据。
type(字符串):指定总体数据类型,例如对象。
properties(对象):列出各个参数,每个参数都具有以下属性:
- type(字符串):参数的数据类型,例如字符串、整数、布尔值。
- description(字符串):清楚地说明参数的用途和预期格式。
required(数组):一个字符串数组,列出了函数运行所必需的参数名称。
如需查看使用 curl 命令进行函数声明的代码示例,请参阅使用 Gemini API 进行函数调用。 如需查看有关如何使用 Gemini API SDK 创建函数声明的示例,请参阅函数调用教程。
根据单个提示,模型可以生成多个函数调用以及将这些函数的输出串联起来所需的代码。此代码在沙盒环境中执行,生成后续的 BidiGenerateContentToolCall
消息。执行会暂停,直到每个函数调用的结果可用为止,从而确保顺序处理。
客户端应使用 BidiGenerateContentToolResponse
进行响应。
如需了解详情,请参阅函数调用简介。
音频格式
请参阅支持的音频格式列表。
系统指令
您可以提供系统指令,以便更好地控制模型的输出,并指定音频回答的语气和情感。
系统指令会在互动开始之前添加到提示中,并在整个会话期间保持有效。
系统指令只能在会话开始时设置,紧随初始连接之后。如需在会话期间向模型提供更多输入内容,请使用增量内容更新。
中断
用户可以随时中断模型的输出。当语音活动检测 (VAD) 检测到中断时,系统会取消并舍弃正在进行的生成操作。会话历史记录中仅保留已发送给客户端的信息。然后,服务器会发送 BidiGenerateContentServerContent
消息来报告中断情况。
此外,Gemini 服务器会舍弃所有待处理的函数调用,并发送一条 BidiGenerateContentServerContent
消息,其中包含已取消调用的 ID。
语音
如需指定语音,请在 speechConfig
对象中设置 voiceName
,作为会话配置的一部分。
请参阅以下 speechConfig
对象的 JSON 表示法:
{ "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "VOICE_NAME" } } }
如需查看支持的语音列表,请参阅更改语音和语言设置。
限制
在规划项目时,请考虑 Live API 和 Gemini 2.0 的以下限制。
客户端身份验证
Live API 仅提供服务器到服务器的身份验证,不建议直接在客户端中使用。客户端输入应通过中间应用服务器进行路由,以便通过 Live API 进行安全身份验证。
会话时长上限
对话会话的默认时长上限为 10 分钟。如需了解详情,请参阅会话时长。
语音活动检测 (VAD)
默认情况下,模型会对连续的音频输入流自动执行语音活动检测 (VAD)。可以使用设置消息的 RealtimeInputConfig.AutomaticActivityDetection
字段配置 VAD。
当音频流暂停超过一秒(例如,当用户关闭麦克风时),系统会发送 AudioStreamEnd
事件来清空所有缓存的音频。客户端可以随时恢复发送音频数据。
或者,您也可以在设置消息中将 RealtimeInputConfig.AutomaticActivityDetection.disabled
设置为 true
,以关闭自动 VAD。在此配置中,客户端负责检测用户语音,并在适当的时间发送 ActivityStart
和 ActivityEnd
消息。此配置中未发送 AudioStreamEnd
。而是会通过 ActivityEnd
消息标记任何流中断。
其他限制
不支持手动端点设置。
音频输入和音频输出会对模型使用函数调用的能力产生负面影响。
token 计数
不支持 token 计数。
速率限制
以下速率限制适用:
- 每个 API 密钥 5,000 个并发会话
- 每分钟 400 万个 token
消息和事件
BidiGenerateContentClientContent
从客户端传送的当前对话的增量更新。此处的所有内容都会无条件附加到对话历史记录中,并用作提示的一部分,以供模型生成内容。
此处的任何消息都会中断当前的模型生成。
字段 | |
---|---|
turns[] |
可选。附加到与模型当前对话的内容。 对于单轮查询,这是单个实例。对于多轮查询,这是包含对话历史记录和最新请求的重复字段。 |
turn_complete |
可选。如果为 true,则表示服务器内容生成应从当前累积的提示开始。否则,服务器将等待更多消息,然后才开始生成。 |
BidiGenerateContentRealtimeInput
实时发送的用户输入。
这与 ClientContentUpdate
有以下几点不同:
- 可以连续发送,不会中断模型生成。
- 如果需要混合使用交错分布在
ClientContentUpdate
和RealtimeUpdate
中的数据,服务器会尝试优化以获得最佳响应,但无法保证。 - 回合结束未明确指定,而是从用户活动(例如,语音结束)中推导得出。
- 即使在回合结束之前,系统也会以增量方式处理数据,以优化模型快速开始生成回答。
- 始终假定为用户输入(不能用于填充对话历史记录)。
字段 | |
---|---|
media_chunks[] |
可选。媒体输入的内嵌字节数据。 |
activity_start |
可选。标记用户活动的开始。只有在停用自动(即服务器端)活动检测功能时,才能发送此事件。 |
activity_end |
可选。标记用户活动的结束。只有在停用自动(即服务器端)活动检测功能时,才能发送此事件。 |
ActivityEnd
此类型没有字段。
标记用户 activity 的结束时间。
ActivityStart
此类型没有字段。
此消息中一次只能设置一个字段。标记用户活动的开始。
BidiGenerateContentServerContent
模型根据客户端消息生成的增量服务器更新。
内容会尽快生成,但不是实时生成。客户端可以选择缓冲并实时播放。
字段 | |
---|---|
turn_complete |
仅限输出。如果为 true,则表示模型已完成生成。只有在收到其他客户端消息后,才会开始生成。可与 |
interrupted |
仅限输出。如果为 true,表示客户端消息已中断当前模型生成。如果客户端正在实时播放内容,则这是一个很好的信号,表明应停止并清空当前队列。如果客户端正在实时播放内容,则这是一个很好的信号,表明应停止并清空当前播放队列。 |
generation_complete |
仅限输出。如果为 true,则表示模型已完成生成。 如果模型在生成过程中被中断,则中断的轮次中不会有“generation_complete”消息,而是会经历“interrupted > turn_complete”。 如果模型假设是实时播放,那么 generation_complete 和 turn_complete 之间会存在延迟,这是因为模型在等待播放完成。 |
grounding_metadata |
仅限输出。元数据用于指定用于为生成的内容提供依据的来源。 |
input_transcription |
可选。输入转写内容。转写独立于模型轮次,这意味着转写和模型轮次之间没有任何顺序关系。 |
output_transcription |
可选。输出转写内容。转写独立于模型轮次,这意味着转写和模型轮次之间没有任何顺序关系。 |
model_turn |
仅限输出。模型在与用户的当前对话中生成的内容。 |
转录
音频转写消息。
字段 | |
---|---|
text |
可选。转写文本。 |
finished |
可选。该布尔值表示转写结束。 |
BidiGenerateContentSetup
要在第一个也是唯一一个客户端消息中发送的消息。包含将在整个流式会话期间应用的配置。
客户端应先等待 BidiGenerateContentSetupComplete
消息,然后再发送任何其他消息。
字段 | |
---|---|
model |
必需。发布商模型的完全限定名称。 发布方模型格式: |
generation_config |
可选。生成配置。 不支持以下字段:
|
system_instruction |
可选。用户为模型提供的系统指令。注意:各部分中只能使用文本,并且每个部分中的内容都将位于单独的段落中。 |
tools[] |
可选。模型可能用于生成下一个回答的
|
session_resumption |
可选。配置会话恢复机制。如果包含,服务器将定期向客户端发送 |
context_window_compression |
可选。配置上下文窗口压缩机制。 如果包含此参数,服务器会将上下文窗口压缩到指定长度。 |
realtime_input_config |
可选。配置实时输入的处理方式。 |
input_audio_transcription |
可选。输入内容的转写与输入音频的语言一致。 |
output_audio_transcription |
可选。输出的转写内容与为输出音频指定的语言代码保持一致。 |
AudioTranscriptionConfig
此类型没有字段。
音频转写配置。
BidiGenerateContentSetupComplete
此类型没有字段。
为响应客户端发送的 BidiGenerateContentSetup
消息而发送。
BidiGenerateContentToolCall
请求客户端执行 function_calls
并返回具有匹配 id
的响应。
字段 | |
---|---|
function_calls[] |
仅限输出。要执行的函数调用。 |
BidiGenerateContentToolCallCancellation
通知客户端,之前发布的具有指定 id
的 ToolCallMessage
应该未执行,并且应该取消。如果这些工具调用存在副作用,客户端可能会尝试撤消这些工具调用。此消息仅在客户端中断服务器回合时出现。
字段 | |
---|---|
ids[] |
仅限输出。要取消的工具调用的 ID。 |
BidiGenerateContentToolResponse
客户端针对从服务器收到的 ToolCall
生成的响应。各个 FunctionResponse
对象通过 id
字段与各自的 FunctionCall
对象匹配。
请注意,在一元和服务器流式 GenerateContent API 中,函数调用是通过交换 Content
部分实现的,而在双向 GenerateContent API 中,函数调用是通过这些专用消息集实现的。
字段 | |
---|---|
function_responses[] |
可选。对函数调用的响应。 |
RealtimeInputConfig
配置 BidiGenerateContent
中的实时输入行为。
字段 | |
---|---|
automatic_activity_detection |
可选。如果未设置,则默认启用自动活动检测。如果自动语音检测功能已停用,客户端必须发送活动信号。 |
activity_handling |
可选。定义效果活动的具体效果。 |
turn_coverage |
可选。定义用户回合中包含哪些输入。 |
ActivityHandling
处理用户活动的不同方式。
枚举 | |
---|---|
ACTIVITY_HANDLING_UNSPECIFIED |
如果未指定,则默认行为为 START_OF_ACTIVITY_INTERRUPTS 。 |
START_OF_ACTIVITY_INTERRUPTS |
如果为 true,则 activity 的启动会中断模型的响应(也称为“抢占”)。模型当前的回答将在中断时被截断。这是默认行为。 |
NO_INTERRUPTION |
模型不会中断回答。 |
AutomaticActivityDetection
配置活动自动检测。
字段 | |
---|---|
start_of_speech_sensitivity |
可选。确定检测到语音的可能性。 |
end_of_speech_sensitivity |
可选。确定检测到的语音结束的可能性。 |
prefix_padding_ms |
可选。在提交语音开头之前检测到的所需语音时长。此值越低,语音开始检测的灵敏度越高,可识别的语音越短。不过,这也会增加出现假正例的概率。 |
silence_duration_ms |
可选。在提交语音结束之前检测到的静音(或非语音)的所需时长。此值越大,语音间断时间越长,而不会中断用户活动,但会增加模型的延迟时间。 |
disabled |
可选。如果启用,检测到的语音和文本输入将计为活动。如果停用,客户端必须发送活动信号。 |
EndSensitivity
结束语音识别的灵敏度。
枚举 | |
---|---|
END_SENSITIVITY_UNSPECIFIED |
默认值为 END_SENSITIVITY_LOW。 |
END_SENSITIVITY_HIGH |
自动检测功能更频繁地结束语音。 |
END_SENSITIVITY_LOW |
自动检测功能结束语音的频率较低。 |
StartSensitivity
开始语音识别的灵敏度。
枚举 | |
---|---|
START_SENSITIVITY_UNSPECIFIED |
默认值为 START_SENSITIVITY_LOW。 |
START_SENSITIVITY_HIGH |
自动检测功能会更频繁地检测到语音的开始。 |
START_SENSITIVITY_LOW |
自动检测功能检测到语音开始的频率会降低。 |
TurnCoverage
有关用户回合中包含哪些输入的选项。
枚举 | |
---|---|
TURN_COVERAGE_UNSPECIFIED |
如果未指定,则默认行为为 TURN_INCLUDES_ALL_INPUT 。 |
TURN_INCLUDES_ONLY_ACTIVITY |
用户轮次仅包括自上一个轮次以来的活动,不包括不活动(例如音频流中的静音)。 |
TURN_INCLUDES_ALL_INPUT |
用户轮次包括自上一个轮次以来的所有实时输入,包括不活动状态(例如音频流中的静音)。这是默认行为。 |
UsageMetadata
有关缓存内容使用情况的元数据。
字段 | |
---|---|
total_token_count |
缓存内容消耗的令牌总数。 |
text_count |
文本字符数。 |
image_count |
图片数量。 |
video_duration_seconds |
视频时长(以秒为单位)。 |
audio_duration_seconds |
音频时长(以秒为单位)。 |
GoAway
服务器很快将无法为客户端提供服务。
字段 | |
---|---|
time_left |
连接在终止为 ABORTED 状态之前的剩余时间。此处返回的最小时间与给定模型的速率限制一起以不同的方式指定。 |
SessionResumptionUpdate
更新会话恢复状态。
仅当设置了 BidiGenerateContentSetup.session_resumption
时才发送。
字段 | |
---|---|
new_handle |
表示可恢复状态的新句柄。如果 |
resumable |
如果会话可以在此点恢复,则为 true。 在某些情况下,可能无法恢复会话。在这种情况下,我们会发送更新后的空 new_handle,并将 resumable 设置为 false。此类情况的示例可以是模型执行函数调用或仅生成。在此状态下恢复会话(使用之前的会话令牌)会导致一些数据丢失。 |
last_consumed_client_message_index |
相应会话恢复令牌所表示的状态中包含的客户端发送的最后一条消息的索引。仅在设置了 有了此索引,用户便可透明地重新连接,避免丢失部分实时音频输入/视频。如果客户端希望暂时断开连接(例如,由于收到 GoAway 而断开连接),则可以通过缓冲自上次 它不会用于稍后的“恢复以还原状态”;在这些情况下,可能不需要部分音频和视频帧。 |