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 chamada 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 várias versões de modelos compatíveis com a API Gemini Live, incluindo:

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

Chamadas de função

Use a chamada 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 seu aplicativo executa o código e envia os resultados de volta para o 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 a chamada 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 ver exemplos de como usar a chamada de função em instruções do sistema, consulte nosso exemplo de práticas recomendadas.

Use o 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 da chamada de função, a integração do lado do servidor processa a recuperação de informações automaticamente.

Para ativar o embasamento com a Pesquisa Google, inclua google_search na lista tools da 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 de RAG da Vertex AI com a API Live para embasamento, armazenamento e recuperação de contextos. Use isso para tarefas como recuperar informações de um corpus de documentos. Assim como o embasamento com a Pesquisa Google, o embasamento com RAG é processado no 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 na API Gemini Live.

Configurar recursos de áudio nativos

Os modelos com recursos de áudio nativos oferecem suporte aos seguintes recursos:

Configurar a computação afetiva

Quando a conversa afetiva está ativada, 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

Com o áudio proativo, você controla quando o modelo responde. Por exemplo, você pode pedir para o Gemini responder apenas quando solicitado ou quando assuntos específicos forem discutidos. Para assistir a uma demonstração em vídeo do Proactive Audio, consulte Prévia de áudio nativo da API Gemini Live.

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 faz o seguinte:

  • 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 acontecer.
  • Evita interrupções: o áudio proativo ajuda o Gemini a evitar interrupções causadas por ruídos de fundo ou conversas externas e impede que ele responda se uma conversa externa for iniciada durante uma conversa.
  • Lida com interrupções: se o usuário precisar interromper uma resposta do Gemini, o áudio proativo facilita a resposta adequada do Gemini (ou seja, as interrupções adequadas são processadas), em vez de usar palavras de preenchimento, como hum ou ãh.
  • Ouve áudio com você: o Gemini pode ouvir um arquivo de áudio que não é a voz do falante e responder a perguntas sobre ele mais tarde na conversa.

Faturamento

Enquanto o Gemini ouve uma conversa, os tokens de áudio de entrada são cobrados.

Para tokens de áudio de saída, a cobrança só é feita quando o Gemini responde. Se o Gemini não responder ou ficar em silêncio, não haverá cobrança pelos tokens de áudio de saída.

Para mais informações, consulte Preços da Vertex AI.

A seguir

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