Live API 的内置工具

本指南介绍了如何使用 Live API 提供的内置工具来增强模型互动。本指南涵盖了以下主题：

• 函数调用：介绍如何定义模型可以调用的自定义函数，以便与外部系统进行交互。
• 代码执行：说明如何让模型生成并运行 Python 代码来执行计算任务。
• 使用 Google 搜索建立依据：介绍如何将模型与 Google 搜索相关联，以便根据实时公开信息生成回答。
• 使用 Vertex AI RAG 引擎进行接地：详细介绍了如何使用您自己的私有数据源来接地模型回答。
• 原生音频：涵盖高级音频功能，包括主动响应和理解情绪提示。

如需启用工具，请在初始化模型时将其添加到 tools 列表中。下表对可用的工具进行了概要比较。

工具	说明	使用场景
函数调用	使模型能够调用您定义的外部函数。模型会返回要使用的函数名称和实参。	与外部 API、数据库或其他服务集成，例如查看天气或预订航班。
代码执行	允许模型在沙盒环境中生成并运行 Python 代码，以执行计算或任务。	解决数学问题、执行数据分析，或通过简短的 Python 脚本完成的任何任务。
使用 Google 搜索建立依据	将模型与 Google 搜索相关联，以便模型根据最新的公开网络信息生成回答。这是一种接地形式。	回答有关近期事件或热点话题的问题，其中当前信息至关重要。
通过 Vertex AI RAG Engine 接地	使用检索增强生成 (RAG) 将模型连接到您的私有数据源或精选数据源。	构建一个聊天机器人，该机器人可以根据您公司的内部文档或产品手册回答问题。

支持的模型

您可以将 Live API 与以下模型搭配使用：

模型版本	可用性级别
gemini-live-2.5-flash	非公开正式版^*
gemini-live-2.5-flash-preview-native-audio	公开预览版

^*如需申请访问权限，请与您的 Google 客户代表联系。

函数调用

使用函数调用创建函数说明，然后在请求中将该说明传递给模型。模型的响应包括与说明匹配的函数名称以及用于调用该函数的参数。

在会话开始时，通过将工具定义作为 LiveConnectConfig 消息的一部分发送，来声明所有函数。

如需启用函数调用，请在 tools 列表中添加 function_declarations：

Python

import asyncio
from google import genai
from google.genai import types

client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION,
)
model = "gemini-live-2.5-flash"

# Simple function definitions
turn_on_the_lights = {"name": "turn_on_the_lights"}
turn_off_the_lights = {"name": "turn_off_the_lights"}

tools = [{"function_declarations": [turn_on_the_lights, turn_off_the_lights]}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Turn on the lights please"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)
            elif chunk.tool_call:
                function_responses = []
                for fc in tool_call.function_calls:
                    function_response = types.FunctionResponse(
                        name=fc.name,
                        response={ "result": "ok" } # simple, hard-coded function response
                    )
                    function_responses.append(function_response)

                await session.send_tool_response(function_responses=function_responses)


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

Python

代码执行

您可以将代码执行与 Live API 搭配使用，以直接生成和执行 Python 代码。如需为回答启用代码执行功能，请在 tools 列表中添加 code_execution：

Python

import asyncio
from google import genai
from google.genai import types


client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION,
)
model = "gemini-live-2.5-flash"

tools = [{'code_execution': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Compute the largest prime palindrome under 100000."
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)
            
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                      if part.executable_code is not None:
                        print(part.executable_code.code)

                      if part.code_execution_result is not None:
                        print(part.code_execution_result.output)

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

使用 Google 搜索建立依据

您可以通过在 tools 列表中添加 google_search，将 Grounding with Google Search 与 Live API 搭配使用：

Python

import asyncio
from google import genai
from google.genai import types

client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION,
)
model = "gemini-live-2.5-flash"


tools = [{'google_search': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "When did the last Brazil vs. Argentina soccer match happen?"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)

                # The model might generate and execute Python code to use Search
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                        if part.executable_code is not None:
                        print(part.executable_code.code)

                        if part.code_execution_result is not None:
                        print(part.code_execution_result.output)

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

通过 Vertex AI RAG Engine 接地（预览版）

您可以将 Live API 连接到 Vertex AI RAG Engine，以基于您的私密数据源为模型回答提供依据。如需启用 Vertex AI RAG 引擎接地，请使用您的 VertexRagStore 详细信息配置 retrieval 工具：

Python

from google import genai
from google.genai import types
from google.genai.types import (Content, LiveConnectConfig, HttpOptions, Modality, Part)
from IPython import display

PROJECT_ID=YOUR_PROJECT_ID
LOCATION=YOUR_LOCATION
TEXT_INPUT=YOUR_TEXT_INPUT
MODEL_NAME="gemini-live-2.5-flash"

client = genai.Client(
   vertexai=True,
   project=PROJECT_ID,
   location=LOCATION,
)

rag_store=types.VertexRagStore(
   rag_resources=[
       types.VertexRagStoreRagResource(
           rag_corpus=  # Use memory corpus if you want to store context.
       )
   ],
   # Set `store_context` to true to allow Live API sink context into your memory corpus.
   store_context=True
)

async with client.aio.live.connect(
   model=MODEL_NAME,
   config=LiveConnectConfig(response_modalities=[Modality.TEXT],
                            tools=[types.Tool(
                                retrieval=types.Retrieval(
                                    vertex_rag_store=rag_store))]),
) as session:
   text_input=TEXT_INPUT
   print("> ", text_input, "\n")
   await session.send_client_content(
       turns=Content(role="user", parts=[Part(text=text_input)])
   )

   async for message in session.receive():
       if message.text:
           display.display(display.Markdown(message.text))
           continue

如需了解详情，请参阅在 Gemini Live API 中使用 Vertex AI RAG 引擎。

（公开预览版）原生音频

预览版

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

Gemini 2.5 Flash with Live API 引入了原生音频功能，可增强标准 Live API 功能。原生音频提供更丰富、更自然的语音互动，支持 24 种语言的 30 种高清语音。它还包含两项仅适用于原生音频的新功能： 主动音频和 共情对话。

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

使用主动音频

主动音频功能可让模型仅在相关时做出响应。启用后，模型会主动生成文本转写和音频回答，但仅针对定向到设备的查询。系统会忽略非设备定向的查询。

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

Python

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

使用共情对话

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

共情对话功能可让使用 Live API 原生音频的模型更好地理解用户的情感表达并做出适当的响应，从而实现更细致的对话。

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

Python

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

更多信息

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

• Live API 概览
• Live API 参考文档
• 互动式对话