Tutorial sobre chamada de função

Python Node.js Go Dart (Flutter) Android Swift Web REST

A chamada de função facilita a geração de saídas de dados estruturados de modelos generativos. É possível usar essas saídas para chamar outras APIs e retornar os dados de resposta relevantes ao modelo. Em outras palavras, a chamada de função ajuda a conectar modelos generativos a sistemas externos para que o conteúdo gerado inclua as informações mais atualizadas e precisas.

É possível fornecer descrições de funções aos modelos do Gemini. Essas são funções que você escreve no idioma do seu app, ou seja, elas não são funções do Google Cloud. O modelo pode pedir que você chame uma função e envie de volta o resultado para ajudar o modelo a processar sua consulta.

Se ainda não fez isso, confira a Introdução à chamada de função para saber mais.

Exemplo de API para controle de iluminação

Imagine que você tem um sistema básico de controle de iluminação com uma interface de programação de aplicativos (API) e quer permitir que os usuários controlem as luzes por meio de solicitações de texto simples. Você pode usar o recurso de chamada de função para interpretar solicitações de mudança de iluminação dos usuários e traduzi-las em chamadas de API para definir os valores de iluminação. Esse sistema hipotético de controle de iluminação permite controlar o brilho da luz e a temperatura de cor, definidos como dois parâmetros separados:

Para simplificar, esse sistema de iluminação imaginário tem apenas uma luz, para que o usuário não precise especificar um cômodo ou local. Confira um exemplo de solicitação JSON que pode ser enviada à API de controle de iluminação para mudar o nível de luz para 50% usando a temperatura de cor do dia:

{
  "brightness": "50",
  "colorTemperature": "daylight"
}

Este tutorial mostra como configurar uma chamada de função para a API Gemini para interpretar as solicitações de iluminação dos usuários e mapeá-las para as configurações da API para controlar os valores de brilho e temperatura de cor de uma luz.

Antes de começar: configure o projeto e a chave de API

Antes de chamar a API Gemini, você precisa configurar seu projeto e a chave de API.

Definir uma função de API

Crie uma função que faça uma solicitação de API. Essa função precisa ser definida no código do seu aplicativo, mas pode chamar serviços ou APIs fora dele. A API Gemini não chama essa função diretamente. Assim, você pode controlar como e quando ela é executada pelo código do aplicativo. Para fins de demonstração, este tutorial define uma função de API simulada que retorna apenas os valores de iluminação solicitados:

async function setLightValues(brightness, colorTemp) {
  // This mock API returns the requested lighting values
  return {
    brightness: brightness,
    colorTemperature: colorTemp
  };
}

Criar declarações de função

Crie a declaração de função que você vai transmitir ao modelo generativo. Ao declarar uma função para uso pelo modelo, inclua o máximo de detalhes possível nas descrições da função e do parâmetro. O modelo generativo usa essas informações para determinar qual função selecionar e como fornecer valores para os parâmetros na chamada de função. O código abaixo mostra como declarar a função de controle de iluminação:

// Function declaration, to pass to the model.
const controlLightFunctionDeclaration = {
  name: "controlLight",
  parameters: {
    type: "OBJECT",
    description: "Set the brightness and color temperature of a room light.",
    properties: {
      brightness: {
        type: "NUMBER",
        description: "Light level from 0 to 100. Zero is off and 100 is full brightness.",
      },
      colorTemperature: {
        type: "STRING",
        description: "Color temperature of the light fixture which can be `daylight`, `cool` or `warm`.",
      },
    },
    required: ["brightness", "colorTemperature"],
  },
};

// Executable function code. Put it in a map keyed by the function name
// so that you can call it once you get the name string from the model.
const functions = {
  controlLight: ({ brightness, colorTemp }) => {
    return setLightValues( brightness, colorTemp)
  }
};

Declarar funções durante a inicialização do modelo

Quando você quer usar a chamada de função com um modelo, é necessário fornecer as declarações de função ao inicializar o objeto do modelo. Para declarar funções, defina o parâmetro tools do modelo:

<html>
  <body>
    <!-- ... Your HTML and CSS -->

    <script type="importmap">
      {
        "imports": {
          "@google/generative-ai": "https://esm.run/@google/generative-ai"
        }
      }
    </script>
    <script type="module">
      import { GoogleGenerativeAI } from "@google/generative-ai";

      // Fetch your API_KEY
      const API_KEY = "...";

      // Access your API key (see "Set up your API key" above)
      const genAI = new GoogleGenerativeAI(API_KEY);

      // ...

      const generativeModel = genAI.getGenerativeModel({
        // Use a model that supports function calling, like a Gemini 1.5 model
        model: "gemini-1.5-flash",

        // Specify the function declaration.
        tools: {
          functionDeclarations: [controlLightFunctionDeclaration],
        },
      });
    </script>
  </body>
</html>

Gerar uma chamada de função

Depois de inicializar o modelo com as declarações de função, você pode solicitar o modelo com a função definida. Use chamadas de função com comandos de chat (sendMessage()), já que as chamadas de função geralmente se beneficiam do contexto de comandos e respostas anteriores.

const chat = generativeModel.startChat();
const prompt = "Dim the lights so the room feels cozy and warm.";

// Send the message to the model.
const result = await chat.sendMessage(prompt);

// For simplicity, this uses the first function call found.
const call = result.response.functionCalls()[0];

if (call) {
  // Call the executable function named in the function call
  // with the arguments specified in the function call and
  // let it call the hypothetical API.
  const apiResponse = await functions[call.name](call.args);

  // Send the API response back to the model so it can generate
  // a text response that can be displayed to the user.
  const result = await chat.sendMessage([{functionResponse: {
    name: 'controlLight',
    response: apiResponse
  }}]);

  // Log the text response.
  console.log(result.response.text());
}