A chamada de função facilita o recebimento de saídas de dados estruturados de modelos generativos. Você pode 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 você conecta modelos generativos a sistemas externos para que o conteúdo gerado inclui as informações mais atualizadas e precisas.
É possível fornecer descrições de funções aos modelos do Gemini. São que você escreve na linguagem do app (ou seja, não são Google Cloud Functions). O modelo pode pedir que você chame uma função e retorne o resultado para ajudar o modelo a lidar com sua consulta.
Confira a Introdução à chamada de função para aprender mais.
Exemplo de API para controle de iluminação
Imagine que você tem um sistema básico de controle de iluminação com um aplicativo de programação interface de usuário (API) e quer permitir que os usuários controlem as luzes por meio de interfaces solicitações de texto. Use o recurso de chamada de função para interpretar a iluminação alterar solicitações de usuários e convertê-las em chamadas de API para definir a iluminação valores. Esse sistema hipotético de controle de iluminação permite controlar brilho da luz e sua temperatura da cor, definidas como dois elementos parâmetros:
Parâmetro | Tipo | Obrigatório | Descrição |
---|---|---|---|
brightness |
number | sim | Nível de iluminação de 0 a 100. Zero é desativado e 100 é brilho total. |
colorTemperature |
string | sim | A temperatura da cor da luminária, que pode ser daylight , cool ou warm . |
Para simplificar, esse sistema de iluminação imaginário tem apenas uma luz, então o usuário não precisa especificar uma sala ou um local. Este é um exemplo de solicitação JSON você pode enviar à API de controle de iluminação para mudar o nível de luz para 50% usando a temperatura da cor da luz do dia:
{
"brightness": "50",
"colorTemperature": "daylight"
}
Neste tutorial, mostramos como configurar uma chamada de função para a API Gemini para interpretar solicitações de iluminação dos usuários e mapeá-las para as configurações da API para controlar uma o brilho da luz e os valores de temperatura da cor.
Antes de começar: configurar o projeto e a chave de API
Antes de chamar a API Gemini, você precisa definir seu projeto e configurar sua 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 aplicativo, mas podem chamar serviços ou APIs seu aplicativo. A API Gemini não chama essa função diretamente, então você pode controlar como e quando essa função é executada por meio do seu aplicativo o código-fonte é alterado. 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 para o modelo generativo. Quando declarar uma função a ser usada pelo modelo, inclua o máximo de detalhes possível nas descrições de funções e parâmetros. 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 a seguir mostra como declare 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
Para usar a chamada de função com um modelo, você precisa fornecer seu
declarações de função quando você inicializa o objeto de modelo. Você declara funções
definindo 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 da função, é possível solicitar
o modelo com a função definida. Use a chamada de função com
comandos de chat (sendMessage()
), já que a chamada de função geralmente se beneficia da
ter o 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());
}