Introdução à chamada de função com a API Gemini

Com o recurso de chamada de função da API Gemini, é possível criar funções definições ao modelo. O modelo não invoca diretamente essas funções, mas gera uma saída estruturada que especifica um nome de função e argumentos sugeridos. Em seguida, você pode usar o nome e os argumentos da função para chamar uma função e você pode incorporar a saída resultante da API em outra consulta para o modelo, permitindo que ele forneça uma resposta mais abrangente e tome ações adicionais.

A chamada de função permite que os usuários interajam com informações e serviços em tempo real, como bancos de dados, sistemas de gestão de relacionamento com o cliente e repositórios de documentos. O recurso também melhora a capacidade do modelo de fornecer respostas relevantes e contextuais. A chamada de função é melhor para interagir com recursos sistemas. Se o caso de uso exigir que o modelo realize a computação, mas não envolva sistemas ou APIs externos, use a execução de código.

Para conferir um exemplo de chamada de função, consulte o notebook "light bot".

Como a chamada de funções funciona

Você usa o recurso de chamada de função adicionando dados de consulta estruturados que descrevem interfaces de programação, chamadas de declarações de função, para um comando de modelo. O declarações de função fornecem o nome da função da API, explicam sua finalidade, parâmetros compatíveis e descrições desses parâmetros. Depois de transmitir uma lista de declarações de função em uma consulta para o modelo, ele analisa as declarações de função e o restante da consulta para determinar como usar a API declarada em resposta à solicitação.

O modelo retorna um objeto em um esquema compatível com a OpenAPI especificando como chamar uma ou mais das funções declaradas para responder à pergunta do usuário. Em seguida, você pode usar os parâmetros de chamada de função recomendados, chamar a API real, receber uma resposta e fornecer essa resposta ao usuário ou realizar outras ações. Observe que o modelo não chama ou funções declaradas. Em vez disso, use os parâmetros do objeto de esquema retornado para chamar a função. A API Gemini também oferece suporte a chamadas de função paralelas, em que o modelo recomenda várias chamadas de função da API com base em uma única solicitação.

Declarações de função

Ao implementar a chamada de função em um comando, você cria um objeto tools, que contém um ou mais function declarations. Você define as funções usando JSON, especificamente com uma selecionar subconjunto da Esquema OpenAPI . Uma única declaração de função pode incluir os seguintes parâmetros:

  • name (string): o identificador exclusivo da função na API. a chamada.
  • description (string): uma explicação abrangente da função propósito e capacidades.
  • parameters (objeto): define os dados de entrada exigidos pela função.
    • type (string): especifica o tipo de dados geral, como object.
    • properties (objeto): lista parâmetros individuais, cada um com:
      • type (string): o tipo de dados do parâmetro, como string, integer, boolean.
      • description (string): uma explicação clara do parâmetro e o formato esperado.
    • required (matriz): uma matriz de strings que lista os nomes dos parâmetros obrigatórios para que a função funcione.

Para exemplos de código de uma declaração de função usando comandos cURL, consulte os Exemplos de chamada de função. Para exemplos de criar declarações de função usando os SDKs da API Gemini, consulte Tutorial de chamada de função.

Práticas recomendadas para declarações de função

Definir com precisão as funções é essencial ao integrá-las aos seus solicitações. Cada função depende de parâmetros específicos que orientam o comportamento dela e interação com o modelo. A listagem a seguir fornece orientações sobre definir os parâmetros de uma função individual em um functions_declarations; matriz.

  • name: use nomes claros e descritivos sem espaços, pontos (.) ou caracteres de traço (-). Em vez disso, use caracteres sublinhados (_). ou CamelCase.

  • description: forneça descrições detalhadas, claras e específicas das funções, incluindo exemplos, se necessário. Por exemplo, em vez de find theaters, use find theaters based on location and optionally movie title that is currently playing in theaters.. Evite descrições muito amplas ou ambíguas.

  • properties > type: use parâmetros fortemente tipados para reduzir as alucinações do modelo. Por exemplo, se os valores de parâmetro forem de um conjunto limitado, use um campo enum em vez de listar os valores na descrição (por exemplo, "type": "enum", "values": ["now_playing", "upcoming"]). Se o O valor do parâmetro é sempre um número inteiro, defina o tipo como integer em vez number

  • properties > description: apresente restrições e exemplos concretos. Por exemplo, em vez de the location to search, use The city and state, e.g. San Francisco, CA or a zip code e.g. 95616.

Para conferir mais práticas recomendadas ao usar a chamada de função, consulte a seção Práticas recomendadas.

Modo da chamada de função

É possível usar a função que chama o parâmetro mode para modificar o comportamento de execução do recurso. Há três modos disponíveis:

  • AUTO: o comportamento padrão do modelo. O modelo decide se quer prever uma chamada de função ou uma resposta de linguagem natural.
  • ANY: o modelo é restrito a sempre prever uma chamada de função. Se allowed_function_names não for fornecido, o modelo vai escolher entre todas as declarações de função disponíveis. Se allowed_function_names for fornecido, o modelo vai escolher entre o conjunto de funções permitidas.
  • NONE: o modelo não vai prever uma chamada de função. Nesse caso, o modelo será o mesmo que acontece quando você não passa nenhuma declaração de função.

O uso do modo ANY ("chamada de função forçada") é compatível apenas com os modelos Gemini 1.5 Pro e Gemini 1.5 Flash.

Também é possível transmitir um conjunto de allowed_function_names que, quando fornecido, limita as funções que o modelo vai chamar. Só inclua allowed_function_names quando o modo for ANY. Os nomes das funções precisam ser iguais nomes de declaração de função. Com o modo definido como ANY e o allowed_function_names definido, o modelo vai prever uma chamada de função do de nomes de função fornecido.

O seguinte snippet de código de uma solicitação de exemplo mostra como Defina mode como ANY e especifique uma lista de funções permitidas:

"tool_config": {
  "function_calling_config": {
    "mode": "ANY",
    "allowed_function_names": ["find_theaters", "get_showtimes"]
  },
}

Exemplos de chamada de função

Esta seção fornece exemplos de comandos para chamada de função usando comandos cURL. Os exemplos incluem cenários com uma ou várias voltas e a ativação diferentes modos de chamada de função.

Ao usar comandos cURL com esse recurso, as informações de função e parâmetro são incluídas no elemento tools. Cada declaração de função na O elemento tools contém o nome da função, e você especifica os parâmetros usando um esquema compatível com OpenAPI, e uma descrição da função.

Exemplo de interação única

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.

Exemplo de solicitação de chamada de função de uma só atividade

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 curva única usando o modo QUALQUER

O exemplo de curl a seguir é semelhante ao exemplo de uma única volta, mas define o modo como ANY:

"tool_config": {
  "function_calling_config": {
    "mode": "ANY"
  },
}

Chamada de função de uma única etapa usando o modo ANY (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 uma única volta 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 retorno único usando o modo QUALQUER e funções permitidas

O exemplo de curl a seguir é semelhante ao exemplo de uma única volta, 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 uma única atividade usando o modo ANY e as 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 pode prever a função find_movies porque ela 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 uma única etapa usando QUALQUER modo 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 várias interações

Você pode implementar um cenário de chamada de função com vários turnos fazendo o seguinte:

  1. Receba uma resposta de chamada de função chamando o modelo de linguagem. Esta é a primeira rodada.
  2. 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:

Usar 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": "user",
    "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
  }
}

Chamar o modelo várias vezes

O exemplo de cURL a seguir chama o modelo de IA generativa 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": "user",
    "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.

Comando do usuário

Para melhores resultados, adicione ao início 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. 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.