As funções personalizadas podem ser definidas e fornecidas a um modelo de IA generativa usando chamadas de função. O modelo não invoca diretamente essas funções, mas gera uma saída de dados estruturados que especifica o nome da função e os argumentos sugeridos. Essa saída permite chamar APIs externas, e a saída da API resultante pode ser incorporada de volta ao modelo, permitindo respostas de consulta mais abrangentes. A chamada de função permite que os LLMs interajam com informações em tempo real e vários serviços, como bancos de dados, sistemas de gestão de relacionamento com o cliente e repositórios de documentos, melhorando a capacidade de fornecer respostas relevantes e contextuais.
Como a chamada de funções funciona
As funções são descritas usando declarações de função. Depois que você transmite uma lista de declarações de função em uma consulta para um modelo de linguagem, o modelo retorna um objeto em um formato de esquema compatível com OpenAPI que inclui os nomes das funções e os respectivos argumentos e tenta responder à consulta do usuário com uma das funções retornadas. O modelo de linguagem entende o propósito de uma função analisando a declaração dela. O modelo não chama a função. Em vez disso, um desenvolvedor usa o objeto de esquema compatível com OpenAPI na resposta para chamar a função retornada pelo modelo.
Ao implementar a chamada de função, você cria uma ou mais declarações
de função e as adiciona a um objeto tools
transmitido ao modelo. Cada declaração de função contém informações sobre uma
função que inclui o seguinte:
- Nome da função
- Parâmetros de função em um formato de esquema compatível com OpenAPI. Um subconjunto selecionado é aceito. Ao usar curl, o esquema é especificado usando JSON.
- Descrição da função (opcional). Para melhores resultados, recomendamos incluir uma descrição.
A API Gemini também oferece suporte à chamada de função paralela, em que você pode chamar várias funções em um único turno.
Este documento inclui exemplos de curl que fazem chamadas REST com a
classe GenerativeModel
e os respectivos métodos.
- Amostras de curl da chamada de função (link em inglês)
Modelos compatíveis
Os modelos a seguir são compatíveis com a chamada de funções:
gemini-1.0-pro
gemini-1.0-pro-001
gemini-1.5-flash-latest
gemini-1.5-pro-latest
Modo da chamada de função
Você pode usar a função que chama mode para definir o comportamento de execução para essa chamada. Há três modos disponíveis:
AUTO
: o comportamento padrão do modelo. O modelo decide prever uma chamada de função ou uma resposta de linguagem natural.ANY
: o modelo é restrito a sempre prever uma chamada de função. Seallowed_function_names
não for fornecido, o modelo escolherá dentre todas as declarações de função disponíveis. Seallowed_function_names
for fornecido, o modelo escolherá uma opção no conjunto de funções permitidas.NONE
: o modelo não vai prever uma chamada de função. Nesse caso, o comportamento do modelo é o mesmo que você faria se não transmitir nenhuma declaração de função.
Também é possível transmitir um conjunto de allowed_function_names
que, quando fornecido, limita
as funções que o modelo chamará. Inclua
allowed_function_names
apenas quando o modo for ANY
. Os nomes das funções precisam corresponder
aos nomes de declaração de função. Com o modo definido como ANY
e o allowed_function_names
definido, o modelo prevê uma chamada de função com base no conjunto de nomes de função fornecido.
Veja parte de um exemplo de solicitação que define o modo como ANY
e especifica uma lista de funções permitidas:
"tool_config": {
"function_calling_config": {
"mode": "ANY",
"allowed_function_names": ["find_theaters", "get_showtimes"]
},
}
Amostras de cURL de chamada de função
Quando você usa cURL, as informações da função e do parâmetro são incluídas no
elemento tools
. Cada declaração de função no elemento tools
contém o nome da função, os parâmetros especificados usando o esquema compatível com OpenAPI e uma descrição da função. Os exemplos a seguir demonstram como usar os comandos curl com a chamada de função:
Exemplo de curl de uma única interação
Interação única é quando você chama o modelo de idioma uma vez. Com a chamada de função, um caso de uso de uma única resposta pode ser ao fornecer ao modelo uma consulta em linguagem natural e uma lista de funções. Nesse caso, o modelo usa a declaração da função, que inclui o nome, os parâmetros e a descrição da função, para prever qual função será chamada e os argumentos com os quais será feita a chamada.
O exemplo de curl a seguir é um exemplo de transmissão da descrição de uma função que retorna informações sobre onde um filme está sendo reproduzido. Várias
declarações de função estão incluídas na solicitação, como find_movies
e
find_theaters
.
Função de turno única que chama a solicitação de exemplo de curl
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \ -H 'Content-Type: application/json' \ -d '{ "contents": { "role": "user", "parts": { "text": "Which theaters in Mountain View show Barbie movie?" } }, "tools": [ { "function_declarations": [ { "name": "find_movies", "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "description": { "type": "string", "description": "Any kind of description including category or genre, title words, attributes, etc." } }, "required": [ "description" ] } }, { "name": "find_theaters", "description": "find theaters based on location and optionally movie title which is currently playing in theaters", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "string", "description": "Any movie title" } }, "required": [ "location" ] } }, { "name": "get_showtimes", "description": "Find the start times for movies playing in a specific theater", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "string", "description": "Any movie title" }, "theater": { "type": "string", "description": "Name of the theater" }, "date": { "type": "string", "description": "Date for requested showtime" } }, "required": [ "location", "movie", "theater", "date" ] } } ] } ] }'
A resposta a esse exemplo de curl pode ser semelhante a esta.
Função de uma só atividade que chama a resposta de exemplo de curl
[{ "candidates": [ { "content": { "parts": [ { "functionCall": { "name": "find_theaters", "args": { "movie": "Barbie", "location": "Mountain View, CA" } } } ] }, "finishReason": "STOP", "safetyRatings": [ { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE" } ] } ], "usageMetadata": { "promptTokenCount": 9, "totalTokenCount": 9 } }]
Exemplo de interação única usando o modo QUALQUER
O exemplo de curl a seguir é semelhante ao
exemplo de turno único, mas define
o modo como ANY
:
"tool_config": {
"function_calling_config": {
"mode": "ANY"
},
}
Chamada de função de turno único usando o modo QUALQUER (solicitação)
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \ -H 'Content-Type: application/json' \ -d '{ "contents": { "role": "user", "parts": { "text": "What movies are showing in North Seattle tonight?" } }, "tools": [ { "function_declarations": [ { "name": "find_movies", "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "description": { "type": "string", "description": "Any kind of description including category or genre, title words, attributes, etc." } }, "required": [ "description" ] } }, { "name": "find_theaters", "description": "find theaters based on location and optionally movie title which is currently playing in theaters", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "string", "description": "Any movie title" } }, "required": [ "location" ] } }, { "name": "get_showtimes", "description": "Find the start times for movies playing in a specific theater", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "string", "description": "Any movie title" }, "theater": { "type": "string", "description": "Name of the theater" }, "date": { "type": "string", "description": "Date for requested showtime" } }, "required": [ "location", "movie", "theater", "date" ] } } ] } ], "tool_config": { "function_calling_config": { "mode": "ANY" }, } }'
O resultado será mais ou menos assim:
Chamada de função de turno único usando o modo QUALQUER (resposta)
{ "candidates": [ { "content": { "parts": [ { "functionCall": { "name": "find_movies", "args": { "description": "", "location": "North Seattle, WA" } } } ], "role": "model" }, "finishReason": "STOP", "index": 0, "safetyRatings": [ { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE" } ] } ], "promptFeedback": { "safetyRatings": [ { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE" } ] } }
Exemplo de turno único usando o modo QUALQUER e funções permitidas
O exemplo de curl a seguir é semelhante ao
exemplo de turno único, mas define
o modo como ANY
e inclui uma lista de funções
permitidas:
"tool_config": {
"function_calling_config": {
"mode": "ANY",
"allowed_function_names": ["find_theaters", "get_showtimes"]
},
}
Chamada de função de turno único usando o modo QUALQUER e funções permitidas (solicitação)
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \ -H 'Content-Type: application/json' \ -d '{ "contents": { "role": "user", "parts": { "text": "What movies are showing in North Seattle tonight?" } }, "tools": [ { "function_declarations": [ { "name": "find_movies", "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "description": { "type": "string", "description": "Any kind of description including category or genre, title words, attributes, etc." } }, "required": [ "description" ] } }, { "name": "find_theaters", "description": "find theaters based on location and optionally movie title which is currently playing in theaters", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "string", "description": "Any movie title" } }, "required": [ "location" ] } }, { "name": "get_showtimes", "description": "Find the start times for movies playing in a specific theater", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "string", "description": "Any movie title" }, "theater": { "type": "string", "description": "Name of the theater" }, "date": { "type": "string", "description": "Date for requested showtime" } }, "required": [ "location", "movie", "theater", "date" ] } } ] } ], "tool_config": { "function_calling_config": { "mode": "ANY", "allowed_function_names": ["find_theaters", "get_showtimes"] }, } }'
O modelo não consegue prever a função find_movies
porque não está na lista de funções permitidas. Portanto, ele prevê uma função diferente. A resposta
pode ser semelhante a esta:
Chamada de função de turno único usando o modo QUALQUER e funções permitidas (resposta)
{ "candidates": [ { "content": { "parts": [ { "functionCall": { "name": "find_theaters", "args": { "location": "North Seattle, WA", "movie": null } } } ], "role": "model" }, "finishReason": "STOP", "index": 0, "safetyRatings": [ { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE" } ] } ], "promptFeedback": { "safetyRatings": [ { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE" } ] } }
Exemplos de curl com várias interações
Você pode implementar um cenário de chamada de função com vários turnos fazendo o seguinte:
- Receba uma resposta de chamada de função chamando o modelo de linguagem. Esta é a primeira rodada.
- Chame o modelo de linguagem usando a resposta da chamada de função da primeira curva e a resposta da função recebida ao chamar essa função. Esta é a segunda curva.
A resposta da segunda curva resume os resultados para responder à consulta na primeira curva ou contém uma segunda chamada de função que pode ser usada para receber mais informações sobre a consulta.
Este tópico inclui dois exemplos de curl de várias interações:
- Exemplo de curl que usa uma resposta de função de uma curva anterior
- Exemplo de curl que chama um modelo de linguagem várias vezes
Exemplo de curl que usa uma resposta de uma curva anterior
A amostra de curl a seguir chama a função e os argumentos retornados pelo exemplo de turno único anterior para receber uma resposta. O método e os parâmetros retornados pelo exemplo de conversão única estão nesse JSON.
"functionCall": {
"name": "find_theaters",
"args": {
"movie": "Barbie",
"location": "Mountain View, CA"
}
}
Função de várias interações que chama a solicitação de exemplo curl
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \ -H 'Content-Type: application/json' \ -d '{ "contents": [{ "role": "user", "parts": [{ "text": "Which theaters in Mountain View show Barbie movie?" }] }, { "role": "model", "parts": [{ "functionCall": { "name": "find_theaters", "args": { "location": "Mountain View, CA", "movie": "Barbie" } } }] }, { "role": "function", "parts": [{ "functionResponse": { "name": "find_theaters", "response": { "name": "find_theaters", "content": { "movie": "Barbie", "theaters": [{ "name": "AMC Mountain View 16", "address": "2000 W El Camino Real, Mountain View, CA 94040" }, { "name": "Regal Edwards 14", "address": "245 Castro St, Mountain View, CA 94040" }] } } } }] }], "tools": [{ "functionDeclarations": [{ "name": "find_movies", "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.", "parameters": { "type": "OBJECT", "properties": { "location": { "type": "STRING", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "description": { "type": "STRING", "description": "Any kind of description including category or genre, title words, attributes, etc." } }, "required": ["description"] } }, { "name": "find_theaters", "description": "find theaters based on location and optionally movie title which is currently playing in theaters", "parameters": { "type": "OBJECT", "properties": { "location": { "type": "STRING", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "STRING", "description": "Any movie title" } }, "required": ["location"] } }, { "name": "get_showtimes", "description": "Find the start times for movies playing in a specific theater", "parameters": { "type": "OBJECT", "properties": { "location": { "type": "STRING", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "STRING", "description": "Any movie title" }, "theater": { "type": "STRING", "description": "Name of the theater" }, "date": { "type": "STRING", "description": "Date for requested showtime" } }, "required": ["location", "movie", "theater", "date"] } }] }] }'
A resposta a este exemplo de curl inclui o resultado da chamada do método find_theaters
. O resultado será mais ou menos assim:
Função de várias interações que chama a resposta de exemplo de curl
{ "candidates": [ { "content": { "parts": [ { "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14." } ] } } ], "usageMetadata": { "promptTokenCount": 9, "candidatesTokenCount": 27, "totalTokenCount": 36 } }
Exemplo de curl que chama um modelo de linguagem várias vezes
O exemplo de curl a seguir chama o modelo de linguagem várias vezes para chamar uma função. Cada vez que o modelo chama a função, ele pode usar uma função diferente para responder a uma consulta do usuário diferente na solicitação.
Função de várias interações que chama a solicitação de exemplo curl
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \ -H 'Content-Type: application/json' \ -d '{ "contents": [{ "role": "user", "parts": [{ "text": "Which theaters in Mountain View show Barbie movie?" }] }, { "role": "model", "parts": [{ "functionCall": { "name": "find_theaters", "args": { "location": "Mountain View, CA", "movie": "Barbie" } } }] }, { "role": "function", "parts": [{ "functionResponse": { "name": "find_theaters", "response": { "name": "find_theaters", "content": { "movie": "Barbie", "theaters": [{ "name": "AMC Mountain View 16", "address": "2000 W El Camino Real, Mountain View, CA 94040" }, { "name": "Regal Edwards 14", "address": "245 Castro St, Mountain View, CA 94040" }] } } } }] }, { "role": "model", "parts": [{ "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14." }] },{ "role": "user", "parts": [{ "text": "Can we recommend some comedy movies on show in Mountain View?" }] }], "tools": [{ "functionDeclarations": [{ "name": "find_movies", "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.", "parameters": { "type": "OBJECT", "properties": { "location": { "type": "STRING", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "description": { "type": "STRING", "description": "Any kind of description including category or genre, title words, attributes, etc." } }, "required": ["description"] } }, { "name": "find_theaters", "description": "find theaters based on location and optionally movie title which is currently playing in theaters", "parameters": { "type": "OBJECT", "properties": { "location": { "type": "STRING", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "STRING", "description": "Any movie title" } }, "required": ["location"] } }, { "name": "get_showtimes", "description": "Find the start times for movies playing in a specific theater", "parameters": { "type": "OBJECT", "properties": { "location": { "type": "STRING", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "STRING", "description": "Any movie title" }, "theater": { "type": "STRING", "description": "Name of the theater" }, "date": { "type": "STRING", "description": "Date for requested showtime" } }, "required": ["location", "movie", "theater", "date"] } }] }] }'
Função de várias interações que chama a resposta de exemplo de curl
[{ "candidates": [ { "content": { "parts": [ { "functionCall": { "name": "find_movies", "args": { "description": "comedy", "location": "Mountain View, CA" } } } ] }, "finishReason": "STOP", "safetyRatings": [ { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE" } ] } ], "usageMetadata": { "promptTokenCount": 48, "totalTokenCount": 48 } } ]
Práticas recomendadas
Siga estas práticas recomendadas para melhorar a precisão e a confiabilidade das chamadas de função.
Campos da tecla de função
É essencial definir com precisão suas funções ao integrá-las às solicitações. Cada função depende de parâmetros específicos que orientam o comportamento e a interação dela com o modelo. Veja uma análise dos principais parâmetros usados
na matriz functions_declarations
.
function_declarations
(matriz):
- Contém um ou mais objetos, cada um representando uma função distinta.
Em cada objeto function_declarations
:
name
(string): o identificador exclusivo da função na chamada de API.- Prática recomendada: use nomes claros e descritivos sem caracteres de espaço, ponto (
.
) ou traço (-
). Em vez disso, use caracteres de sublinhado (_
) ou letras concatenadas.
- Prática recomendada: use nomes claros e descritivos sem caracteres de espaço, ponto (
description
(string): uma explicação abrangente da finalidade e dos recursos da função.- Prática recomendada: inclua detalhes, clareza e especificidade nas descrições de funções, fornecendo exemplos, se necessário. Por exemplo, em vez de
find theaters
, usefind theaters based on location and optionally movie title that is currently playing in theaters.
. Evite descrições muito amplas ou ambíguas.
- Prática recomendada: inclua detalhes, clareza e especificidade nas descrições de funções, fornecendo exemplos, se necessário. Por exemplo, em vez de
parameters
(objeto): define os dados de entrada exigidos pela função.type
(string): especifica o tipo de dados geral (por exemplo,object
).properties
(objeto):- Lista parâmetros individuais, cada um com:
type
(string): o tipo de dados do parâmetro (por exemplo,string
,integer
,boolean
).- Prática recomendada: use parâmetros fortemente tipados para reduzir as alucinações artificiais do modelo. Por exemplo, se os valores dos parâmetros forem de um conjunto finito, use um campo
enum
em vez de listar os valores na descrição (por exemplo,"type": "enum", "values": ["now_playing", "upcoming"]
). Se o valor do parâmetro for sempre um número inteiro, defina o tipo comointeger
em vez denumber
.
- Prática recomendada: use parâmetros fortemente tipados para reduzir as alucinações artificiais do modelo. Por exemplo, se os valores dos parâmetros forem de um conjunto finito, use um campo
description
(string): uma explicação clara da finalidade e do formato esperado do parâmetro.- Prática recomendada: apresente exemplos e restrições concretos. Por exemplo, em vez de
the location to search
, useThe city and state, e.g. San Francisco, CA or a zip code e.g. 95616
.
- Prática recomendada: apresente exemplos e restrições concretos. Por exemplo, em vez de
- Lista parâmetros individuais, cada um com:
required
(matriz):- Uma matriz de strings listando os nomes dos parâmetros obrigatórios para o funcionamento da função.
Comando do usuário
Para melhores resultados, inclua os seguintes detalhes antes da consulta do usuário:
- Contexto adicional para o modelo. Por exemplo,
You are a movie API assistant to help users find movies and showtimes based on their preferences.
. - Detalhes ou instruções sobre como e quando usar as funções. Por exemplo,
Don't make assumptions on showtimes. Always use a future date for showtimes.
. - Instruções para fazer perguntas esclarecedoras se as consultas do usuário forem ambíguas. Por exemplo,
Ask clarifying questions if not enough information is available to complete the request.
.
Parâmetros de amostragem
Para o parâmetro de temperatura, use 0
ou outro valor baixo. Isso instrui o modelo a gerar resultados mais confiáveis e reduz alucinações.
Invocação da API
Se o modelo propor a invocação de uma função que envia uma ordem, atualiza um banco de dados ou tem consequências significativas, valide a chamada de função com o usuário antes de executá-la.