Live API 內建工具

本指南將說明如何使用 Live API 提供的內建工具，提升模型互動體驗。本指南涵蓋下列主題：

• 函式呼叫：說明如何定義模型可呼叫的自訂函式，與外部系統互動。
• 執行程式碼：說明如何讓模型生成及執行 Python 程式碼，以執行運算工作。
• 運用 Google 搜尋建立基準：說明如何將模型連結至 Google 搜尋，根據即時公開資訊生成回覆。
• 利用 Vertex AI RAG 引擎建立基準：詳細說明如何使用自有私人資料來源，建立模型回覆基準。
• 原生音訊：涵蓋進階音訊功能，包括主動回應和瞭解情緒提示。

如要啟用工具，請在初始化模型時將工具納入 tools 清單。下表提供可用工具的比較概要。

工具	說明	用途
函式呼叫	讓模型呼叫您定義的外部函式。模型會傳回要使用的函式名稱和引數。	與外部 API、資料庫或其他服務整合，例如查詢天氣或預訂航班。
程式碼執行	允許模型在沙箱環境中生成及執行 Python 程式碼，以執行計算或工作。	解決數學問題、執行資料分析，或完成任何可透過簡短 Python 指令碼完成的工作。
以 Google 搜尋建立基準	將模型連結至 Google 搜尋，根據最新的公開網路資訊生成回覆。這是一種接地形式。	回答有關近期事件或主題的問題，這類問題需要最新的資訊。
使用 Vertex AI RAG 引擎的依據功能	使用檢索增強生成 (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 搜尋建立基準

如要搭配 Live API 使用「以 Google 搜尋建立基準」功能，請在 tools 清單中加入 google_search：

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 引擎建立基準 (預先發布版)

將 Live API 連結至 Vertex AI RAG 引擎，即可根據私人資料來源建立模型回覆基準。如要啟用 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 種 HD 高音質語音，提供更豐富自然的語音互動。此外，這項技術還包含兩項原生音訊專屬的新功能： 主動式音訊和 情感對話。

注意： 原生音訊不支援 response_modalities=["TEXT"]。

使用主動音訊

主動音訊功能可讓模型只在相關情況下回覆。啟用後，模型會主動生成文字轉錄稿和語音回覆，但僅限針對裝置的查詢。系統會忽略非裝置導向的查詢。

如要使用主動式音訊，請在設定訊息中設定 proactivity 欄位，並將 proactive_audio 設為 true：

Python

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

使用情緒感知對話

重要事項： Affective Dialog 可能會產生非預期的結果。

情感對話功能可讓模型使用 Live API 原生音訊，進一步瞭解使用者的情緒表達並做出適當回應，進而進行更細膩的對話。

如要啟用情緒感知對話，請在設定訊息中將 enable_affective_dialog 設為 true：

Python

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

更多資訊

如要進一步瞭解如何使用 Live API，請參閱：

• Live API 總覽
• Live API 參考資料指南
• 互動式對話