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.
A chamada de função pode 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 saber 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:
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.
Crie uma declaração de função que descreva a função e os parâmetros dela.
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.
Configure o app para que o modelo possa enviar as informações necessárias para que o app chame a função.
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 externa de serviço meteorológico 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:
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Entrada | |||
location |
Objeto | Sim | O nome da cidade e do estado para consultar a previsão do tempo. Somente cidades dos EUA são aceitas. Precisa ser sempre um objeto aninhado de city e state.
|
date |
String | Sim | Data para buscar o clima (sempre no formato YYYY-MM-DD).
|
| Saída | |||
temperature |
Número inteiro | Sim | Temperatura (em Fahrenheit) |
chancePrecipitation |
String | Sim | Possibilidade de chuva (expressa em porcentagem) |
cloudConditions |
String | Sim | Condições do Cloud (clear, partlyCloudy,
mostlyCloudy, cloudy)
|
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
Se ainda não fez isso, conclua o guia de primeiros passos para os SDKs Vertex AI in Firebase. Verifique se você fez o seguinte:
Configure um projeto do Firebase novo ou existente, incluindo o uso do plano de preços Blaze e a ativação das APIs necessárias.
Conecte seu app ao Firebase, incluindo o registro e a adição da configuração do Firebase.
Adicione o SDK e inicialize o serviço 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,maximumeoneOf.
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.
Se a resposta de uma chamada de função não for suficiente para o modelo gerar a resposta final, ele poderá pedir 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 uso de 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.
| Mode | Descrição |
|---|---|
AUTO |
O comportamento padrão do modelo. O modelo decide se vai usar uma chamada de função ou uma resposta de linguagem natural. |
ANY |
O modelo precisa usar chamadas de função ("chamada de função forçada"). Para limitar
o modelo a um subconjunto de funções, especifique os nomes das funções permitidas em
allowedFunctionNames.
|
NONE |
O modelo não pode usar chamadas de função. Esse comportamento é equivalente a uma solicitação de modelo sem declarações de função associadas. |
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 possam ser consideradas nocivas.
Saiba mais sobre os modelos do Gemini
Saiba mais sobre os modelos disponíveis para vários casos de uso e as cotas e os preços.Enviar feedback sobre sua experiência com o Vertex AI in Firebase