Multimodal Live API

Multimodal Live API 支持使用文本、音频和视频输入以及音频和文本输出的低延迟双向互动。这有助于实现自然的、类似人类的语音对话，并能够随时中断模型。该模型的视频理解功能扩展了沟通模式，让您可以分享摄像头输入或屏幕投放内容，并提出相关问题。

功能

Multimodal Live API 包含以下主要功能：

  • 多模态：该模型可以看到、听到和说话。
  • 低延迟实时互动：模型可以提供快速响应。
  • 会话记忆：该模型会保留单个会话中的所有互动记忆，从而回想之前听到或看到的信息。
  • 支持函数调用、代码执行和“搜索作为工具”：您可以将模型与外部服务和数据源集成。

Multimodal Live API 专为服务器到服务器通信而设计。

对于网站和移动应用，我们建议您使用 Daily 合作伙伴提供的集成服务。

开始

如需试用 Multimodal Live API，请前往 Vertex AI Studio，然后点击试用 Multimodal Live。

Multimodal Live API 是一种使用 WebSockets 的有状态 API。

本部分通过示例介绍了如何使用 Python 3.9 及更高版本的 Multimodal Live API 进行文本到文本生成。

Gen AI SDK for Python

了解如何安装或更新 Gen AI SDK for Python。

如需了解详情，请参阅 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=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True
 

from google import genai
from google.genai.types import LiveConnectConfig, HttpOptions, Modality

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))
model_id = "gemini-2.0-flash-exp"

async with client.aio.live.connect(
    model=model_id,
    config=LiveConnectConfig(response_modalities=[Modality.TEXT]),
) as session:
    text_input = "Hello? Gemini, are you there?"
    print("> ", text_input, "\n")
    await session.send(input=text_input, end_of_turn=True)

    response = []

    async for message in session.receive():
        if message.text:
            response.append(message.text)

    print("".join(response))
# Example output:
# >  Hello? Gemini, are you there?

# Yes, I'm here. What would you like to talk about?

集成指南

本部分介绍了如何与 Multimodal 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
}

支持的服务器消息

请参阅下表中支持的服务器消息：

消息 说明
BidiGenerateContentSetupComplete 来自客户端的 BidiGenerateContentSetup 消息，在设置完成时发送
BidiGenerateContentServerContent 模型为客户端消息生成的内容
BidiGenerateContentToolCall 请求客户端运行函数调用并返回包含匹配 ID 的响应
BidiGenerateContentToolCallCancellation 当函数调用因用户中断模型输出而被取消时发送

增量内容更新

使用增量更新发送文本输入、建立会话上下文或恢复会话上下文。对于简短的情境，您可以发送精细互动来表示确切的事件顺序。对于较长的上下文，建议提供单个消息摘要，以便为后续互动腾出上下文窗口。

请参阅以下上下文消息示例：

{
  "clientContent": {
    "turns": [
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": true
  }
}

请注意，虽然内容部分可以是 functionResponse 类型，但不应使用 BidiGenerateContentClientContent 来对模型发出的函数调用提供响应。应改用 BidiGenerateContentToolResponse。BidiGenerateContentClientContent 应仅用于建立先前情境或向对话提供文本输入。

在线播放音频和视频

代码执行

如需详细了解代码执行，请参阅代码执行。

函数调用

必须在会话开始时声明所有函数，方法是将工具定义作为 BidiGenerateContentSetup 消息的一部分发送。

您可以使用 JSON 定义函数，具体而言，使用 OpenAPI 架构格式的部分子集。单个函数声明可以包含以下参数：

  • name（字符串）：API 调用中函数的唯一标识符。

  • description（字符串）：全面说明函数的用途和功能。

  • 参数（对象）：定义函数所需的输入数据。

    • type（字符串）：指定整体数据类型，例如对象。

    • properties（对象）：列出各个参数，每个参数包含：

      • type（字符串）：参数的数据类型，例如字符串、整数、布尔值。
      • description（字符串）：清楚地说明参数的用途和预期格式。

    • required（数组）：一个字符串数组，用于列出函数运行所必需的参数名称。

如需查看使用 curl 命令的函数声明的代码示例，请参阅使用 Gemini API 调用函数简介。如需查看使用 Gemini API SDK 创建函数声明的示例，请参阅函数调用教程。

从单个提示中，模型可以生成多个函数调用以及串联其输出所需的代码。此代码在沙盒环境中执行，并生成后续的 BidiGenerateContentToolCall 消息。执行会暂停，直到每个函数调用的结果都可用，以确保顺序处理。

客户端应返回 BidiGenerateContentToolResponse 响应。

如需了解详情，请参阅函数调用简介。

音频格式

Multimodal Live API 支持以下音频格式：

  • 输入音频格式：16kHz 小端字节序的原始 16 位 PCM 音频
  • 输出音频格式：24kHz 小端字节序的原始 16 位 PCM 音频

系统指令

您可以提供系统指令，以更好地控制模型的输出，并指定语音回答的语气和情感。

系统说明会在互动开始前添加到提示中，并在整个会话期间保持有效。

系统说明只能在会话开始时（即初始连接后立即）设置。如需在会话期间向模型提供更多输入，请使用增量内容更新。

中断

用户可以随时中断模型的输出。当语音活动检测 (VAD) 检测到中断时，系统会取消并舍弃正在生成的音频。只有已发送给客户端的信息会保留在会话历史记录中。然后，服务器会发送 BidiGenerateContentServerContent 消息来报告中断。

此外，Gemini 服务器会舍弃所有待处理的函数调用，并发送包含已取消调用的 ID 的 BidiGenerateContentServerContent 消息。

语音

Multimodal Live API 支持以下语音：

  • Puck
  • Charon
  • Kore
  • Fenrir
  • Aoede

如需指定语音，请在会话配置中，在 speechConfig 对象中设置 voiceName。

请参阅 speechConfig 对象的以下 JSON 表示法：

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "VOICE_NAME"
    }
  }
}

限制

在规划项目时，请考虑 Multimodal Live API 和 Gemini 2.0 的以下限制。

客户端身份验证

Multimodal Live API 仅提供服务器到服务器身份验证，不建议直接供客户端使用。客户端输入应通过中间应用服务器路由，以便通过 Multimodal Live API 进行安全身份验证。

对话记录

虽然该模型会跟踪会话内的互动，但不会存储对话记录。会话结束后，系统会清除相应上下文。

为了恢复之前的会话或向模型提供用户互动的历史上下文，应用应维护自己的对话日志，并在新的会话开始时使用 BidiGenerateContentClientContent 消息发送此信息。

会话时长上限

会话时长：音频不超过 15 分钟，音频和视频不超过 2 分钟。当会话时长超出限制时，连接会终止。

模型还受上下文大小的限制。在视频和音频流中发送大量内容可能会导致会话提前终止。

语音活动检测 (VAD)

该模型会自动对连续的音频输入流执行语音活动检测 (VAD)。VAD 始终处于启用状态，其参数不可配置。

其他限制

不支持手动端点设置。

音频输入和音频输出会对模型使用函数调用功能的能力产生负面影响。

token 计数

不支持 token 计数。

速率限制

以下速率限制适用：

  • 每个 API 密钥 3 个并发会话
  • 每分钟 400 万个 token

消息和事件

BidiGenerateContentClientContent

对客户端传送的当前对话进行增量更新。此处的所有内容都会无条件附加到对话历史记录中，并用作向模型发出生成内容的提示的一部分。

此处显示消息会中断任何当前的模型生成。

字段
turns[]

Content

可选。附加到与模型当前对话的内容。

对于单轮查询，这是单个实例。对于多轮查询，这是包含对话历史记录和最新请求的重复字段。
turn_complete

bool

可选。如果为 true，表示服务器内容生成应从当前累积的提示开始。否则，服务器会等待其他消息，然后再开始生成。

BidiGenerateContentRealtimeInput

实时发送的用户输入。

这与 ClientContentUpdate 在以下几个方面有所不同：

  • 可以连续发送，不会中断模型生成。
  • 如果需要混合在 ClientContentUpdate 和 RealtimeUpdate 中交错的数据，服务器会尝试进行优化以获得最佳响应，但无法保证。
  • 未明确指定转换结束时间，而是从用户活动（例如语音结束）派生而来。
  • 即使在对话结束之前，系统也会增量处理数据，以便优化模型快速开始回答。
  • 始终假定为用户的输入（无法用于填充对话记录）。
字段
media_chunks[]

Blob

可选。媒体输入的内嵌字节数据。

BidiGenerateContentServerContent

模型为响应客户端消息而生成的增量服务器更新。

内容会尽快生成，但不是实时生成。客户端可以选择缓冲并实时播放。

字段
turn_complete

bool

仅限输出。如果为 true，则表示模型已生成完毕。系统仅会在响应其他客户端消息时开始生成。可与 content 一起设置，表示 content 是轮次中的最后一个。
interrupted

bool

仅限输出。如果为 true，则表示客户端消息中断了当前的模型生成。如果客户端正在实时播放内容，则表示可以停止并清空当前队列。如果客户端正在实时播放内容，则表示可以停止并清空当前的播放队列。
grounding_metadata

GroundingMetadata

仅限输出。元数据用于指定生成内容的依据来源。
model_turn

Content

仅限输出。模型在与用户的当前对话中生成的内容。

BidiGenerateContentSetup

要在第一条（也是唯一一条）客户端消息中发送的消息。包含在流式传输会话期间应用的配置。

客户端应先等待 BidiGenerateContentSetupComplete 消息，然后才能发送任何其他消息。

字段
model

string

必需。要使用的发布商模型或调优后模型端点的完全限定名称。

发布商模型格式：projects/{project}/locations/{location}/publishers/\*/models/\*
generation_config

GenerationConfig

可选。生成配置。

不支持以下字段：

  • responseLogprobs
  • responseMimeType
  • logprobs
  • responseSchema
  • stopSequence
  • routingConfig
  • audioTimestamp
system_instruction

Content

可选。用户为模型提供的系统说明。注意：部分中应仅使用文本。每个部分的内容将在单独的段落中。
tools[]

Tool

可选。模型可能用于生成下一个回答的 Tools 列表。

Tool 是一段代码，可让系统与外部系统进行交互，以在模型知识和范围之外执行操作或一组操作。

BidiGenerateContentSetupComplete

此类型没有字段。

作为对客户端发送的 BidiGenerateContentSetup 消息的响应而发送。

BidiGenerateContentToolCall

请求客户端执行 functionCalls 并返回包含匹配 id 的响应。

字段
function_calls[]

FunctionCall

仅限输出。要执行的函数调用。

BidiGenerateContentToolCallCancellation

向客户端发送通知，告知之前针对指定 id 签发的 ToolCallMessage 不应执行，应予取消。如果这些工具调用产生了副作用，客户端可能会尝试撤消工具调用。只有在客户端中断服务器转换时，才会出现此消息。

字段
ids[]

string

仅限输出。要取消的工具调用的 ID。

BidiGenerateContentToolResponse

客户端针对从服务器收到的 ToolCall 生成的响应。各个 FunctionResponse 对象会通过 id 字段与相应的 FunctionCall 对象进行匹配。

请注意，在单个调用和服务器流式 GenerateContent API 中，函数调用是通过交换 Content 部分进行的，而在双向 GenerateContent API 中，函数调用是通过这组专用消息进行的。

字段
function_responses[]

FunctionResponse

可选。对函数调用的响应。

后续步骤