É possível apresentar funções personalizadas para um modelo de IA generativa com a API de chamada 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 ou sistemas de informação externos, como bancos de dados, sistemas de gestão de relacionamento com o cliente e repositórios de documentos. A saída da API resultante pode ser usada pelo LLM para melhorar a qualidade da resposta.
Para ver mais documentos conceituais sobre chamadas de funções, consulte Como chamar de funções.
Modelos com suporte:
Modelo | Versão |
---|---|
Gemini 1.5 Flash | gemini-1.5-flash-001 |
Gemini 1.5 Pro | gemini-1.5-pro-001 |
Gemini 1.0 Pro | gemini-1.0-pro-001 gemini-1.0-pro-002 |
Limitações:
- O número máximo de declarações de função que podem ser fornecidas com a solicitação é 128.
- O
FunctionCallingConfig.Mode.ANY
só está disponível com modelosGemini 1.5 Pro
.
Exemplo de sintaxe
Sintaxe para enviar uma solicitação de API de chamada de função.
curl
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:generateContent \ -d '{ "contents": [{ ... }], "tools": [{ "function_declarations": [ { ... } ] }] }'
Python
gemini_model = GenerativeModel( MODEL_ID, generation_config=generation_config, tools=[ Tool( function_declarations=[ FunctionDeclaration( ... ) ] ) ], )
Lista de parâmetros
Confira exemplos para detalhes de implementação.
FunctionDeclaration
Uma representação estruturada de uma declaração de função, conforme definido pela especificação OpenAPI 3.0 (link em inglês) que representa uma função em que o modelo pode gerar entradas JSON.
Parâmetros | |
---|---|
|
O nome da função a ser chamada. Precisa começar com uma letra ou um sublinhado. Precisa ser az, AZ, 0-9 ou conter sublinhados e traços, com um tamanho máximo de 64. |
|
Opcional: A descrição e o propósito da função. O modelo usa isso para decidir como e se a função será chamada. Para melhores resultados, recomendamos incluir uma descrição. |
|
Opcional: Descreve os parâmetros da função no formato de objeto de esquema JSON da OpenAPI: especificação OpenAPI 3.0. |
|
Opcional: Descreve a saída da função no formato de objeto de esquema JSON da OpenAPI: especificação OpenAPI 3.0. |
Para mais informações, consulte Chamada de função.
Schema
O esquema é usado para definir o formato dos dados de entrada e saída em uma chamada de função. Uma representação estruturada de uma declaração de função, conforme definido pela especificação de Esquema da OpenAPI 3.0.
Parâmetros | |
---|---|
tipo |
enumerado. O tipo dos dados. Precisa ser um dos:
|
description |
Opcional: Descrição dos dados. |
enum |
Opcional: Valores possíveis do elemento de |
items |
Opcional: Esquema dos elementos de |
properties |
Opcional: Esquema das propriedades de |
required |
Opcional: Propriedades obrigatórias de |
nullable |
Opcional: Indica se o valor pode ser |
FunctionCallingConfig
O FunctionCallingConfig
controla o comportamento do modelo e
determina que tipo de função chamar.
Esse recurso está disponível apenas para o modelo gemini-1.5-pro-001
.
Parâmetros | |
---|---|
|
Opcional:
|
|
Opcional: Nomes de funções a serem chamadas. Definido apenas quando |
Exemplos
Enviar uma declaração de função
O exemplo a seguir é um exemplo básico de envio de uma consulta e uma declaração de função ao modelo.
REST
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto.
- LOCATION: a região para processar a solicitação.
- MODEL_ID: o ID do modelo que está sendo processado.
- ROLE: a identidade da entidade que cria a mensagem.
- TEXT: o comando a ser enviado para o modelo.
- NAME: o nome da função a ser chamada.
- DESCRIPTION: descrição e propósito da função.
- Para outros campos, consulte a tabela Lista de parâmetros.
Método HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent
Corpo JSON da solicitação:
{ "contents": [{ "role": "ROLE", "parts": [{ "text": "TEXT" }] }], "tools": [{ "function_declarations": [ { "name": "NAME", "description": "DESCRIPTION", "parameters": { "type": "TYPE", "properties": { "location": { "type": "TYPE", "description": "DESCRIPTION" } }, "required": [ "location" ] } } ] }] }
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo com o nome request.json
e execute o comando a seguir:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
" https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"
PowerShell
Salve o corpo da solicitação em um arquivo com o nome request.json
e execute o comando a seguir:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri " https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content
Exemplo de comando curl
PROJECT_ID=myproject
LOCATION=us-central1
MODEL_ID=gemini-1.0-pro-002
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:generateContent \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "What is the weather in Boston?"
}]
}],
"tools": [{
"functionDeclarations": [
{
"name": "get_current_weather",
"description": "Get the current weather in a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
}
},
"required": [
"location"
]
}
}
]
}]
}'
Python
Node.js
Java
Go
REST (OpenAI)
É possível chamar a API Function Calling usando a biblioteca OpenAI. Para mais informações, consulte Chamar o Gemini usando a biblioteca da OpenAI.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto.
- LOCATION: a região para processar a solicitação.
- MODEL_ID: o ID do modelo que está sendo processado.
Método HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions
Corpo JSON da solicitação:
{ "model": "google/MODEL_ID", "messages": [ { "role": "user", "content": "What is the weather in Boston?" } ], "tools": [ { "type": "function", "function": { "name": "get_current_weather", "description": "Get the current weather in a given location", "parameters": { "type": "OBJECT", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" } }, "required": ["location"] } } } ] }
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo com o nome request.json
e execute o comando a seguir:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions"
PowerShell
Salve o corpo da solicitação em um arquivo com o nome request.json
e execute o comando a seguir:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions" | Select-Object -Expand Content
Python (OpenAI)
É possível chamar a API Function Calling usando a biblioteca OpenAI. Para mais informações, consulte Chamar o Gemini usando a biblioteca da OpenAI.
Enviar uma declaração de função com FunctionCallingConfig
O exemplo abaixo demonstra como transmitir um FunctionCallingConfig
.
ao modelo.
O functionCallingConfig
garante que a saída do modelo seja sempre um
chamada de função específica. Para configurar:
- Defina a função que chama
mode
comoANY
. Especifique os nomes das funções que você quer usar em
allowed_function_names
. Seallowed_function_names
estiver vazio, qualquer uma das funções fornecidas podem ser retornados.
REST
PROJECT_ID=myproject
LOCATION=us-central1
MODEL_ID=gemini-1.5-pro-001
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:generateContent \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "Do you have the White Pixel 8 Pro 128GB in stock in the US?"
}]
}],
"tools": [{
"functionDeclarations": [
{
"name": "get_product_sku",
"description": "Get the available inventory for a Google products, e.g: Pixel phones, Pixel Watches, Google Home etc",
"parameters": {
"type": "object",
"properties": {
"product_name": {"type": "string", "description": "Product name"}
}
}
},
{
"name": "get_store_location",
"description": "Get the location of the closest store",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "Location"}
},
}
}
]
}],
"toolConfig": {
"functionCallingConfig": {
"mode":"ANY",
"allowedFunctionNames": ["get_product_sku"]
}
},
"generationConfig": {
"temperature": 0.95,
"topP": 1.0,
"maxOutputTokens": 8192
}
}'
Python
Node.js
Go
REST (OpenAI)
É possível chamar a API Function Calling usando a biblioteca OpenAI. Para mais informações, consulte Chamar o Gemini usando a biblioteca da OpenAI.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- PROJECT_ID: o ID do projeto.
- LOCATION: a região para processar a solicitação.
- MODEL_ID: o ID do modelo que está sendo processado.
Método HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions
Corpo JSON da solicitação:
{ "model": "google/MODEL_ID", "messages": [ { "role": "user", "content": "What is the weather in Boston?" } ], "tools": [ { "type": "function", "function": { "name": "get_current_weather", "description": "Get the current weather in a given location", "parameters": { "type": "OBJECT", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" } }, "required": ["location"] } } } ], "tool_choice": "auto" }
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo com o nome request.json
e execute o comando a seguir:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions"
PowerShell
Salve o corpo da solicitação em um arquivo com o nome request.json
e execute o comando a seguir:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions" | Select-Object -Expand Content
Python (OpenAI)
É possível chamar a API Function Calling usando a biblioteca OpenAI. Para mais informações, consulte Chamar o Gemini usando a biblioteca da OpenAI.
A seguir
Para consultar a documentação detalhada, acesse: