配置 Gemini 功能

本文档介绍了如何在使用 Gemini Live API 时配置 Gemini 模型的各种功能。您可以配置工具使用（例如函数调用和接地）以及原生音频功能（例如共情对话和主动音频）。

如需了解详情，请在您选择的环境中运行以下笔记本：

• “Multimodal Live API (WebSocket) 简介”：

  在 Colab 中打开 | 在 Colab Enterprise 中打开 | 在 Agent Platform Workbench 中打开 | 在 GitHub 上查看

• “Multimodal Live API (Google Gen AI SDK) 简介”：

  在 Colab 中打开 | 在 Colab Enterprise 中打开 | 在 Agent Platform Workbench 中打开 | 在 GitHub 上查看

配置工具使用

多种工具与支持 Gemini Live API 的各种版本的模型兼容，包括：

• 函数调用
• 使用 Google 搜索建立依据
• 在 Gemini Enterprise Agent Platform 上通过 RAG Engine 接地（预览版）

如需启用特定工具以在返回的回答中使用，请在初始化模型时将该工具的名称包含在 tools 列表中。以下各部分提供了有关如何在代码中使用每种内置工具的示例。

重要提示：在同一设置请求中，Gemini API 不支持将搜索工具（例如 googleSearch）与非搜索工具（例如函数调用或 Gemini Enterprise Agent Platform RAG 引擎 retrieval 工具）结合使用。仅当所有工具都是搜索工具时，才支持使用多个工具。

函数调用

如果您希望模型与您管理的外部系统或 API 进行互动，请使用函数调用。此功能适用于检查数据库、发送电子邮件或与自定义 API 互动等任务。

模型会生成函数调用，而您的应用会执行代码并将结果发送回模型。

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

如需启用函数调用，请在设置消息的 tools 列表中添加 function_declarations：

Python

import asyncio

from google import genai
from google.genai.types import (
    Content,
    LiveConnectConfig,
    Part,
)

# Initialize the client.
client = genai.Client(
    vertexai=True,
    project="GOOGLE_CLOUD_PROJECT",  # Replace with your project ID
    location="LOCATION",  # Replace with your location
)

MODEL_ID = "gemini-live-2.5-flash-native-audio"


def get_current_weather(location: str) -> str:
    """Example method. Returns the current weather.

    Args:
        location: The city and state, e.g. San Francisco, CA
    """
    weather_map: dict[str, str] = {
        "Boston, MA": "snowing",
        "San Francisco, CA": "foggy",
        "Seattle, WA": "raining",
        "Austin, TX": "hot",
        "Chicago, IL": "windy",
    }
    return weather_map.get(location, "unknown")


async def main():
    config = LiveConnectConfig(
        response_modalities=["AUDIO"],
        tools=[get_current_weather],
    )

    async with client.aio.live.connect(
        model=MODEL_ID,
        config=config,
    ) as session:
        text_input = "Get the current weather in Boston."
        print(f"Input: {text_input}")

        await session.send_client_content(
            turns=Content(role="user", parts=[Part(text=text_input)])
        )

        async for message in session.receive():
            if message.tool_call:
                function_responses = []
                for function_call in message.tool_call.function_calls:
                    print(f"FunctionCall > {function_call}")
                    # Execute the tool and send the response back to the model.
                    result = get_current_weather(**function_call.args)
                    function_responses.append(
                        {
                            "name": function_call.name,
                            "response": {"result": result},
                            "id": function_call.id,
                        }
                    )
                if function_responses:
                    await session.send_tool_response(function_responses=function_responses)


if __name__ == "__main__":
    asyncio.run(main())
  

如需查看在系统指令中使用函数调用的示例，请参阅我们的最佳实践示例。

依托 Google 搜索进行接地

如果您希望模型通过将回答固定到可验证的信息来源来提供更准确、更真实的回答，请使用依托 Google 搜索进行接地。用于执行搜索网络等任务。

与函数调用不同，服务器端集成会自动处理信息检索。

如需启用“依托 Google 搜索进行接地”，请在设置消息的 tools 列表中添加 google_search：

Python

import asyncio

from google import genai
from google.genai.types import (
    Content,
    LiveConnectConfig,
    Part,
)

# Initialize the client.
client = genai.Client(
    vertexai=True,
    project="GOOGLE_CLOUD_PROJECT",  # Replace with your project ID
    location="LOCATION",  # Replace with your location
)

MODEL_ID = "gemini-live-2.5-flash-native-audio"


async def main():
    config = LiveConnectConfig(
        response_modalities=["AUDIO"],
        tools=[{"google_search": {}}],
    )

    async with client.aio.live.connect(
        model=MODEL_ID,
        config=config,
    ) as session:
        text_input = "What is the current weather in Toronto, Canada?"
        print(f"Input: {text_input}")

        await session.send_client_content(
            turns=Content(role="user", parts=[Part(text=text_input)])
        )

        async for message in session.receive():
            # Consume the messages from the model.
            # In native audio, the model response is in audio format.
            pass


if __name__ == "__main__":
    asyncio.run(main())
  

使用 Gemini Enterprise Agent Platform 上的 RAG 引擎建立依据

预览

此功能受服务专用条款的“通用服务条款”部分中的“非正式版产品条款”的约束。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

您可以将 RAG Engine 与 Live API 搭配使用，以实现上下文的接地、存储和检索。可用于从文档语料库中检索信息等任务。与“依托 Google 搜索进行接地”功能类似，RAG 接地在服务器端处理，并自动从您指定的语料库中检索信息：

Python

import asyncio

from google import genai
from google.genai.types import (
    Content,
    LiveConnectConfig,
    Part,
    Retrieval,
    Tool,
    VertexRagStore,
    VertexRagStoreRagResource,
)

# Initialize the client.
client = genai.Client(
    vertexai=True,
    project="GOOGLE_CLOUD_PROJECT",  # Replace with your project ID
    location="LOCATION",  # Replace with your location
)

MODEL_ID = "gemini-live-2.5-flash-native-audio"


async def main():
    rag_store = VertexRagStore(
        rag_resources=[
            VertexRagStoreRagResource(
                rag_corpus="RESOURCE_NAME"  # Replace with your corpus resource name
            )
        ],
        # Set `store_context` to true to allow Live API sink context into your memory corpus.
        store_context=True,
    )

    config = LiveConnectConfig(
        response_modalities=["AUDIO"],
        tools=[Tool(retrieval=Retrieval(vertex_rag_store=rag_store))],
    )

    async with client.aio.live.connect(
        model=MODEL_ID,
        config=config,
    ) as session:
        text_input = "YOUR_TEXT_INPUT"
        print(f"Input: {text_input}")

        await session.send_client_content(
            turns=Content(role="user", parts=[Part(text=text_input)])
        )

        async for message in session.receive():
            # Consume the messages from the model.
            # In native audio, the model response is in audio format.
            pass


if __name__ == "__main__":
    asyncio.run(main())
  

如需了解详情，请参阅 在 Gemini Live API 中使用 Gemini Enterprise Agent Platform 上的 RAG 引擎。

配置原生音频功能

预览

此功能受服务专用条款的“通用服务条款”部分中的“非正式版产品条款”的约束。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

具有原生音频功能的模型支持以下功能：

• 30 种高清语音
• 24 种语言
• 主动音频
• 共情对话

注意：原生音频不支持 response_modalities=["TEXT"]。

配置共情对话

重要提示：共情对话可能会产生意外结果。

启用共情对话后，模型会尝试根据用户的语气和情感表达来理解和做出回答。

如需启用共情对话，请在设置消息中将 enable_affective_dialog 设置为 true：

Python

config = LiveConnectConfig(
    response_modalities=["AUDIO"],
    enable_affective_dialog=True,
)
  

配置主动音频

借助主动音频，您可以控制模型何时响应。例如，您可以让 Gemini 仅在收到提示或讨论特定主题时做出回答。如需观看主动音频的视频演示，请参阅 Gemini Live API 原生音频预览。

如需启用主动音频，请在设置消息中配置 proactivity 字段，并将 proactive_audio 设置为 true：

Python

config = LiveConnectConfig(
    response_modalities=["AUDIO"],
    proactivity=ProactivityConfig(proactive_audio=True),
)
  

对话示例

以下示例展示了与 Gemini 就烹饪进行对话的可能情形：

Prompt: "You are an AI assistant in Italian cooking; only chime in when the topic is about Italian cooking."

Speaker A: "I really love cooking!" (No response from Gemini.)

Speaker B: "Oh yes, me too! My favorite is French cuisine." (No response from
Gemini.)

Speaker A: "I really like Italian food; do you know how to make a pizza?"

(Italian cooking topic will trigger response from Gemini.)
Gemini Live API: "I'd be happy to help! Here's a recipe for a pizza."

常见使用场景

使用主动音频时，Gemini 的行为如下：

• 以最短的延迟时间做出回答：Gemini 会在用户说完话后立即做出回答，从而减少中断，并帮助 Gemini 在发生中断时不会丢失上下文。
• 避免中断：主动音频可帮助 Gemini 避免受到背景噪音或外部对话的干扰，并防止 Gemini 在对话期间因外部对话而做出回应。
• 处理中断：如果用户需要在 Gemini 回答期间中断，主动音频可让 Gemini 更轻松地进行适当的后向通道处理（即处理适当的中断），而不是像用户使用填充词（例如 umm 或 uhh）时那样。
• 共同聆听音频：Gemini 可以共同聆听不是说话者声音的音频文件，然后在对话中回答与该音频文件相关的问题。

结算

在 Gemini 聆听对话时，系统会收取输入音频token费用。

对于输出音频token，只有在 Gemini 回答时才会收费。如果 Gemini 不回应或保持静默，则不会收取输出音频token的费用。

如需了解详情，请参阅 Gemini Enterprise Agent Platform 价格。

后续步骤

如需详细了解如何使用 Gemini Live API，请参阅：

• Gemini Live API 概览
• Gemini Live API 参考文档
• 开始和管理实时会话