Configurar recursos do Gemini

Este documento mostra como configurar vários recursos dos modelos do Gemini ao usar a API Gemini Live. É possível configurar o uso de ferramentas, como chamadas de função e embasamento, e recursos de áudio nativos, como diálogo afetivo e áudio proativo.

Configurar o uso de ferramentas

Várias ferramentas são compatíveis com diferentes versões de modelos com suporte à API Gemini Live, incluindo:

Para ativar uma ferramenta específica para uso em respostas retornadas, inclua o nome dela na lista tools ao inicializar o modelo. As seções a seguir fornecem exemplos de como usar cada uma das ferramentas integradas no código.

Chamadas de função

Use chamadas de função quando quiser que o modelo interaja com sistemas ou APIs externos que você gerencia. Use isso para tarefas como verificar um banco de dados, enviar um e-mail ou interagir com uma API personalizada.

O modelo gera uma chamada de função, e o aplicativo executa o código e envia os resultados de volta ao modelo.

Todas as funções precisam ser declaradas no início da sessão enviando definições de ferramentas como parte da mensagem LiveConnectConfig.

Para ativar as chamadas de função, inclua function_declarations na lista tools na mensagem de configuração:

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())

Para exemplos de uso de chamadas de função em instruções do sistema, consulte nosso exemplo de práticas recomendadas.

Use Embasamento com a Pesquisa Google quando quiser que o modelo forneça respostas mais precisas e factuais, ancorando-as em fontes de informações verificáveis. Use isso para tarefas como pesquisar na Web.

Ao contrário das chamadas de função, a integração do lado do servidor processa a recuperação de informações automaticamente.

Para ativar o recurso de Embasamento com a Pesquisa Google, inclua google_search na lista tools na mensagem de configuração:

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())

Embasamento com o Mecanismo RAG da Vertex AI

É possível usar o Mecanismo RAG da Vertex AI com a API Live para embasar, armazenar e recuperar contextos. Use isso para tarefas como recuperar informações de um corpus de documentos. Assim como o Embasamento com a Pesquisa Google, o embasamento RAG é processado do lado do servidor e recupera automaticamente informações do corpus especificado:

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())

Para mais informações, consulte Usar o Mecanismo RAG da Vertex AI no Gemini Live API.

Configurar recursos de áudio nativos

Os modelos que têm recursos de áudio nativos oferecem suporte aos seguintes recursos:

Configurar o diálogo afetivo

Quando o diálogo afetivo está ativado, o modelo tenta entender e responder com base no tom de voz e nas expressões emocionais do usuário.

Para ativar o diálogo afetivo, defina enable_affective_dialog como true na mensagem de configuração:

Python

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

Configurar o áudio proativo

O áudio proativo permite controlar quando o modelo responde. Por exemplo, você pode pedir ao Gemini para responder apenas quando solicitado ou quando temas específicos forem discutidos. Para conferir uma demonstração em vídeo do áudio proativo, consulte Gemini LiveAPI Native Audio Preview.

Para ativar o áudio proativo, configure o campo proactivity na mensagem de configuração e defina proactive_audio como true:

Python

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

Exemplo de conversa

Confira um exemplo de como seria uma conversa com o Gemini sobre culinária:

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."

Casos de uso comuns

Ao usar o áudio proativo, o Gemini funciona da seguinte maneira:

  • Responde com latência mínima: o Gemini responde depois que o usuário termina de falar, reduzindo interrupções e ajudando o Gemini a não perder o contexto se uma interrupção ocorrer.
  • Evita interrupções: o áudio proativo ajuda o Gemini a evitar interrupções de ruídos de fundo ou conversas externas e impede que o Gemini responda se conversas externas forem introduzidas durante uma conversa.
  • Processa interrupções: se o usuário precisar interromper durante uma resposta do Gemini, o áudio proativo facilita o back-channel adequado do Gemini (ou seja, as interrupções adequadas são processadas), em vez de um usuário usar palavras de preenchimento, como umm ou uhh.
  • Ouve o áudio: o Gemini pode ouvir um arquivo de áudio que não seja a voz do falante e, posteriormente, responder a perguntas sobre esse arquivo de áudio na conversa.

Faturamento

Enquanto o Gemini estiver ouvindo uma conversa, os tokens de áudio de entrada serão cobrados.

Para tokens de áudio de saída, você só será cobrado quando o Gemini responder. Se o Gemini não responder ou ficar em silêncio, não haverá cobrança nos tokens de áudio de saída.

Para mais informações, consulte Preços da plataforma de agentes do Gemini Enterprise.

A seguir

Para mais informações sobre como usar a API Gemini Live, consulte: