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. 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. 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 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. 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:

Parâmetro	Tipo	Obrigatório	Descrição
brightness	number	sim	Nível de luz de 0 a 100. Zero é desativado e 100 é brilho total.
colorTemperature	string	sim	Temperatura de cor do dispositivo de iluminação, que pode ser daylight, cool ou warm.

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. Este é um exemplo de solicitação JSON você pode enviar à API de controle de iluminação para mudar o nível de iluminação 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 os valores de brilho e temperatura da cor da luz.

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.

Expanda para ver como configurar seu projeto e a chave de API

Receber e proteger sua chave de API

Você precisa de uma chave de API para chamar a API Gemini. Se você ainda não tiver uma, crie uma chave no Google AI Studio.

Gerar uma chave de API

É altamente recomendável não verificar uma chave de API na sua versão. de controle de acesso.

Armazene sua chave de API em um repositório de secrets, como o Google Cloud Secret Manager

Neste tutorial, presumimos que você esteja acessando sua chave de API como um ambiente variável.

Importar o pacote do SDK e configurar a chave de API

No seu aplicativo, faça o seguinte:

1. No diretório do módulo, get o pacote do SDK do Go:

   go get github.com/google/generative-ai-go
   

2. Importe o pacote e configure o serviço com sua chave de API:

   import (
     // import standard libraries
     // Import the GenerativeAI package for Go
     "github.com/google/generative-ai-go/genai"
     "google.golang.org/api/option"
   )
   
   ctx := context.Background()
   // Access your API key as an environment variable
   client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
   if err != nil {
     log.Fatal(err)
   }
   defer client.Close()
   
   // ...
   

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. 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:

func setLightValues(brightness int, colorTemp string) map[string]any {
    // This mock API returns the requested lighting values
    return map[string]any{
        "brightness":       brightness,
        "colorTemperature": colorTemp}
}

Criar uma declaração de função

Crie a declaração de função que você vai transmitir ao 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 abaixo mostra como declarar a função de controle de iluminação:

lightControlTool := &genai.Tool{
    FunctionDeclarations: []*genai.FunctionDeclaration{{
        Name:        "controlLight",
        Description: "Set the brightness and color temperature of a room light.",
        Parameters: &genai.Schema{
            Type: genai.TypeObject,
            Properties: map[string]*genai.Schema{
                "brightness": {
                    Type:        genai.TypeString,
                    Description: "Light level from 0 to 100. Zero is off and"+
                        " 100 is full brightness.",
                },
                "colorTemperature": {
                    Type:        genai.TypeString,
                    Description: "Color temperature of the light fixture which" +
                        " can be `daylight`, `cool` or `warm`.",
                },
            },
            Required: []string{"brightness", "colorTemperature"},
        },
    }},
}

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:

// ...

lightControlTool := &genai.Tool{
    // ...
}

// Use a model that supports function calling, like a Gemini 1.5 model
model := client.GenerativeModel("gemini-1.5-flash")

// Specify the function declaration.
model.Tools = []*genai.Tool{lightControlTool}

Gerar uma chamada de função

Depois de inicializar o modelo com as declarações de função, você pode solicitar 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.

// Start new chat session.
session := model.StartChat()

prompt := "Dim the lights so the room feels cozy and warm."

// Send the message to the generative model.
resp, err := session.SendMessage(ctx, genai.Text(prompt))
if err != nil {
    log.Fatalf("Error sending message: %v\n", err)
}

// Check that you got the expected function call back.
part := resp.Candidates[0].Content.Parts[0]
funcall, ok := part.(genai.FunctionCall)
if !ok {
    log.Fatalf("Expected type FunctionCall, got %T", part)
}
if g, e := funcall.Name, lightControlTool.FunctionDeclarations[0].Name; g != e {
    log.Fatalf("Expected FunctionCall.Name %q, got %q", e, g)
}
fmt.Printf("Received function call response:\n%q\n\n", part)

apiResult := map[string]any{
    "brightness":  "30",
    "colorTemperature":  "warm" }

// Send the hypothetical API result back to the generative model.
fmt.Printf("Sending API result:\n%q\n\n", apiResult)
resp, err = session.SendMessage(ctx, genai.FunctionResponse{
    Name:     lightControlTool.FunctionDeclarations[0].Name,
    Response: apiResult,
})
if err != nil {
    log.Fatalf("Error sending message: %v\n", err)
}

// Show the model's response, which is expected to be text.
for _, part := range resp.Candidates[0].Content.Parts {
    fmt.Printf("%v\n", part)
}