Chamada de função usando a API Gemini

Os modelos generativos são poderosos na resolução de muitos tipos de problemas. No entanto, eles são limitados por limitações como:

• Eles são congelados após o treinamento, levando a um conhecimento desatualizado.
• Eles não podem consultar nem modificar dados externos.

As chamadas de função podem ajudar a superar algumas dessas limitações. A chamada de função às vezes é chamada de uso de ferramentas porque permite que um modelo use ferramentas externas, como APIs e funções, para gerar a resposta final.

Você pode aprender mais sobre a chamada de função na documentação do Google Cloud, incluindo uma lista útil de casos de uso para chamada de função.

A chamada de função é compatível com o Gemini 1.0 Pro, o Gemini 1.5 Pro e o Gemini 1.5 Flash.

Este guia mostra como implementar uma configuração de chamada de função semelhante ao exemplo descrito na próxima seção principal desta página. De modo geral, estas são as etapas para configurar a chamada de função no app:

1. Escreva uma função que possa fornecer ao modelo as informações necessárias para gerar a resposta final. Por exemplo, a função pode chamar uma API externa.

2. Crie uma declaração de função que descreva a função e os parâmetros dela.

3. Forneça a declaração de função durante a inicialização do modelo para que o modelo saiba como usar a função, se necessário.

4. Configure o app para que o modelo possa enviar as informações necessárias para que o app chame a função.

5. Transmita a resposta da função de volta ao modelo para que ele possa gerar a resposta final.

Ir para a implementação do código

Visão geral de um exemplo de chamada de função

Ao enviar uma solicitação para o modelo, você também pode fornecer um conjunto de "ferramentas" (como funções) que ele pode usar para gerar a resposta final. Para usar essas funções e chamá-las ("chamada de função"), o modelo e o app precisam transmitir informações um para o outro. Portanto, a maneira recomendada de usar a chamada de função é pela interface de chat multiresposta.

Imagine que você tenha um app em que um usuário possa inserir uma instrução como: What was the weather in Boston on October 17, 2024?.

Os modelos Gemini podem não conhecer essas informações meteorológicas. No entanto, imagine que você saiba de uma API de serviço meteorológico externa que possa fornecê-las. É possível usar a chamada de função para fornecer ao modelo Gemini um caminho para essa API e as informações meteorológicas.

Primeiro, você escreve uma função fetchWeather no app que interage com essa API externa hipotética, que tem essa entrada e saída:

Ao inicializar o modelo, você informa que essa função fetchWeather existe e como ela pode ser usada para processar solicitações recebidas, se necessário. Isso é chamado de "declaração de função". O modelo não chama a função diretamente. Em vez disso, enquanto o modelo processa a solicitação recebida, ele decide se a função fetchWeather pode ajudar a responder à solicitação. Se o modelo decidir que a função pode ser útil, ele vai gerar dados estruturados que ajudarão o app a chamar a função.

Analise novamente a solicitação recebida: What was the weather in Boston on October 17, 2024?. O modelo provavelmente decidiria que a função fetchWeather pode ajudar a gerar uma resposta. O modelo verifica quais parâmetros de entrada são necessários para fetchWeather e gera dados de entrada estruturados para a função, mais ou menos assim:

{
  functionName: fetchWeather,
  location: {
    city: Boston,
    state: Massachusetts  // the model can infer the state from the prompt
  },
  date: 2024-10-17
}

O modelo transmite esses dados de entrada estruturados para que o app possa chamar a função fetchWeather. Quando o app recebe as condições climáticas da API, ele transmite as informações para o modelo. Essas informações permitem que o modelo conclua o processamento final e gere a resposta à solicitação inicial de What was the weather in Boston on October 17, 2024?.

O modelo pode fornecer uma resposta final em linguagem natural, como: On October 17, 2024, in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

Implementar chamadas de função

Antes de começar

Conclua o guia para iniciantes dos SDKs do Vertex AI in Firebase, se ainda não tiver feito isso. Verifique se você fez o seguinte:

1. Configurou um projeto novo ou existente do Firebase, incluindo o uso do plano de preços Blaze e a ativação das APIs necessárias.

2. Conectou seu app ao Firebase, incluindo o registro e a adição da configuração do Firebase.

3. Adicione o SDK e inicialize o serviço do Vertex AI e o modelo generativo no seu app.

Depois de conectar seu app ao Firebase, adicionar o SDK e inicializar o serviço Vertex AI e o modelo generativo, você poderá chamar o Gemini API.

As etapas restantes neste guia mostram como implementar uma configuração de chamada de função semelhante ao fluxo de trabalho descrito em Visão geral de um exemplo de chamada de função (consulte a seção superior desta página).

Confira o exemplo de código completo para este exemplo de chamada de função mais adiante nesta página.

Etapa 1: escrever a função

Imagine que você tenha um app em que um usuário possa inserir uma instrução como: What was the weather in Boston on October 17, 2024?. Os modelos Gemini podem não conhecer essas informações meteorológicas. No entanto, imagine que você saiba de uma API de serviço meteorológico externa que possa fornecê-las. O exemplo deste guia depende dessa API externa hipotética.

Escreva a função no app que vai interagir com a API externa hipotética e fornecer ao modelo as informações necessárias para gerar a solicitação final. Neste exemplo de clima, será uma função fetchWeather que faz a chamada para essa API externa hipotética.

Etapa 2: criar uma declaração de função

Crie a declaração de função que você vai fornecer ao modelo mais tarde (próxima etapa deste guia).

Na declaração, inclua o máximo de detalhes possível nas descrições da função e dos parâmetros dela.

O modelo usa as informações na declaração de função para determinar qual função selecionar e como fornecer valores de parâmetro para a chamada real da função. Consulte Outros comportamentos e opções mais adiante nesta página para saber como o modelo pode escolher entre as funções e como controlar essa escolha.

Observe o seguinte sobre o esquema fornecido:

• Você precisa fornecer declarações de função em um formato de esquema compatível com o esquema da OpenAPI. A Vertex AI oferece suporte limitado ao esquema da OpenAPI.

  • Os seguintes atributos são aceitos: type, nullable, required, format, description, properties, items, enum.

  • Os seguintes atributos não são aceitos: default, optional, maximum e oneOf.

• Por padrão, para SDKs Vertex AI in Firebase, todos os campos são considerados obrigatórios, a menos que você os especifique como opcionais em uma matriz optionalProperties. Para esses campos opcionais, o modelo pode preenchê-los ou ignorá-los. Isso é o oposto do comportamento padrão do Vertex AI Gemini API.

Para conferir as práticas recomendadas relacionadas às declarações de função, incluindo dicas para nomes e descrições, consulte Práticas recomendadas na documentação do Google Cloud.

Veja como escrever uma declaração de função:

Etapa 3: fornecer a declaração de função durante a inicialização do modelo

O número máximo de declarações de função que você pode fornecer com a solicitação é 128. Consulte Outros comportamentos e opções mais adiante nesta página para saber como o modelo pode escolher entre as funções e como controlar essa escolha (usando um toolConfig para definir o modo de chamada de função).

Saiba como escolher um modelo do Gemini e, opcionalmente, um local adequado para seu caso de uso e app.

Etapa 4: chamar a função para invocar a API externa

Se o modelo decidir que a função fetchWeather pode realmente ajudar a gerar uma resposta final, seu app precisará fazer a chamada real para essa função usando os dados de entrada estruturados fornecidos pelo modelo.

Como as informações precisam ser transmitidas entre o modelo e o app, a maneira recomendada de usar a chamada de função é pela interface de chat multiresposta.

O snippet de código abaixo mostra como o app é informado de que o modelo quer usar a função fetchWeather. Ele também mostra que o modelo forneceu os valores de parâmetro de entrada necessários para a chamada de função (e a API externa).

Neste exemplo, a solicitação recebida continha o comando What was the weather in Boston on October 17, 2024?. Com base nesse comando, o modelo inferiu os parâmetros de entrada necessários para a função fetchWeather, ou seja, city, state e date.

Etapa 5: forneça a saída da função ao modelo para gerar a resposta final

Depois que a função fetchWeather retornar as informações meteorológicas, seu app precisa transmiti-las de volta ao modelo.

Em seguida, o modelo realiza o processamento final e gera uma resposta final em linguagem natural, como: On October 17, 2024 in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

Outros comportamentos e opções

Confira alguns comportamentos adicionais de chamada de função que você precisa acomodar no código e opções que podem ser controladas.

O modelo pode pedir para chamar uma função novamente ou outra função.

Se a resposta de uma chamada de função não for suficiente para o modelo gerar a resposta final, ele poderá solicitar outra chamada de função ou pedir uma chamada para uma função totalmente diferente. Isso só pode acontecer se você fornecer mais de uma função ao modelo na lista de declarações de função.

Seu app precisa acomodar o fato de que o modelo pode solicitar outras chamadas de função.

O modelo pode pedir para chamar várias funções ao mesmo tempo.

É possível fornecer até 128 funções na lista de declaração de funções para o modelo. Portanto, o modelo pode decidir que várias funções são necessárias para ajudar a gerar a resposta final. E pode decidir chamar algumas dessas funções ao mesmo tempo. Isso é chamado de chamada de função paralela.

O app precisa acomodar o fato de que o modelo pode solicitar várias funções executadas ao mesmo tempo e fornecer todas as respostas das funções de volta ao modelo.

A chamada de função paralela é compatível com o Gemini 1.5 Pro e o Gemini 1.5 Flash.

É possível controlar como e se o modelo pode solicitar a chamada de funções.

É possível impor algumas restrições sobre como e se o modelo precisa usar as declarações de função fornecidas. Isso é chamado de configuração do modo de chamada de função. Veja alguns exemplos:

• Em vez de permitir que o modelo escolha entre uma resposta de linguagem natural imediata e uma chamada de função, é possível forçar o modelo a usar sempre chamadas de função. Isso é chamado de chamada de função forçada.

• Se você fornecer várias declarações de função, poderá restringir o modelo para usar apenas um subconjunto das funções fornecidas.

Para implementar essas restrições (ou modos), adicione uma configuração de ferramenta (toolConfig) com o comando e as declarações de função. Na configuração da ferramenta, é possível especificar um dos seguintes modos. O modo mais útil é ANY.

O modo de chamada de função é compatível com o Gemini 1.5 Pro e o Gemini 1.5 Flash.

O que mais você pode fazer?

Testar outros recursos do Gemini API

• Crie conversas com vários turnos (chat).
• Gerar texto com base em comandos somente de texto.
• Gerar texto a partir de comandos multimodais (incluindo texto, imagens, PDFs, vídeo e áudio).

Saiba como controlar a geração de conteúdo

• Entenda o design de comandos, incluindo práticas recomendadas, estratégias e exemplos de comandos.
• Configure os parâmetros do modelo, como temperatura e máximo de tokens de saída.
• Use as configurações de segurança para ajustar a probabilidade de receber respostas que podem ser consideradas nocivas.

Saiba mais sobre os modelos do Gemini

Enviar feedback sobre sua experiência com o Vertex AI in Firebase