É 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 (o suporte para chamadas de função está em fase de pré-lançamento) |
Limitações:
- O número máximo de funções que podem ser chamadas é 64.
- O
FunctionCallingConfig
só está disponível no modelogemini-1.5-pro-001
.
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. |
|
Opcional: Descrição e propósito da funçã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. |
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
(Visualização prévia)
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-preview-0409
.
Parâmetros | |
---|---|
|
Opcional:
|
|
Opcional: Nomes de funções a serem chamadas. Definido apenas quando |
Examples
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
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-preview-0409
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
A seguir
Para consultar a documentação detalhada, acesse: