Instructivo sobre llamadas a funciones

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

Las llamadas a función facilitan la obtención de resultados de datos estructurados desde generativos. Luego, puedes usar estos resultados para llamar a otras APIs y mostrar los datos de respuesta relevantes para el modelo. En otras palabras, las llamadas a función te ayudan a conectar modelos generativos a sistemas externos para que el contenido generado incluya la información más actualizada y precisa.

Puedes proporcionarles descripciones de funciones a los modelos de Gemini. Son funciones que escribes en el lenguaje de tu app (es decir, Google Cloud Functions). Es posible que el modelo te solicite que llames a una función y le envíes el resultado para ayudarlo a controlar tu consulta.

Si aún no lo has hecho, consulta la Introducción a la llamada a función para aprender más.

Ejemplo de API para el control de iluminación

Imagina que tienes un sistema de control de iluminación básico con una aplicación (API), y quieres permitir que los usuarios controlen las luces mediante solicitudes de texto. Puedes usar la función Llamadas a función para interpretar la iluminación de los usuarios y convertirlas en llamadas a la API para establecer la iluminación de salida. Este hipotético sistema de control de iluminación te permite controlar la el brillo de la luz y su temperatura de color, que se definen como dos parámetros:

Parámetro	Tipo	Obligatorio	Descripción
brightness	número	sí	Nivel de luz de 0 a 100. Cero es la opción de apagado y 100 es el brillo máximo.
colorTemperature	string	sí	Temperatura de color de la lámpara, que puede ser daylight, cool o warm.

Para simplificar, este sistema de iluminación imaginario solo tiene una luz, por lo que el usuario no necesita especificar una sala o ubicación. Este es un ejemplo de una solicitud JSON podrías enviar a la API de control de iluminación para cambiar el nivel de luz al 50% usando la temperatura de color de la luz diurna:

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

En este instructivo, se muestra cómo configurar una llamada a función para que la API de Gemini haga lo siguiente: interpretar las solicitudes de iluminación de los usuarios y asignarlas a la configuración de la API para controlar un el brillo de la luz y los valores de temperatura de color.

Antes de comenzar: Configura tu proyecto y clave de API

Antes de llamar a la API de Gemini, debes configurar tu proyecto y tu clave de API.

Expande para ver cómo configurar tu proyecto y la clave de API

Cómo obtener y proteger tu clave de API

Necesitas una clave de API para llamar a la API de Gemini. Si aún no tienes uno, crear una clave en Google AI Studio.

Obtén una clave de API

Te recomendamos que no incluyas una clave de API en tu versión un sistema de control de calidad.

Debes almacenar tu clave de API en un almacén de secretos, como Secret Manager de Google Cloud.

En este instructivo, se supone que accedes a tu clave de API como una variable de entorno.

Importa el paquete del SDK y configura tu clave de API

En tu aplicación, haz lo siguiente:

1. En el directorio de tu módulo, ejecuta el comando get en el paquete del SDK de Go:

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

2. Importa el paquete y configura el servicio con tu clave 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()
   
   // ...
   

Define una función de API

Crea una función que realice una solicitud a la API. Esta función debe definirse en el código de tu aplicación, pero podrían llamar a servicios o APIs fuera de tu aplicación. La API de Gemini no llama a esta función directamente, por lo que puedes controlar cómo y cuándo se ejecuta a través del código de tu aplicación. A modo de demostración, este instructivo define una función de API simulada que solo muestra los valores de iluminación 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}
}

Crea una declaración de función

Crea la declaración de función que pasarás al modelo generativo. Cuando declares una función para que la use el modelo, debes incluir tantos detalles como sea posible en las descripciones de la función y los parámetros. El modelo generativo usa esta información para determinar qué función seleccionar y cómo proporcionar de salida para los parámetros en la llamada a función. El siguiente código muestra cómo Declara la función de control de la iluminación:

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"},
        },
    }},
}

Declara funciones durante la inicialización del modelo

Cuando quieras usar las llamadas a función con un modelo, debes proporcionar tu las declaraciones de función cuando inicializas el objeto del modelo. Declaras funciones estableciendo el parámetro Tools del 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}

Genera una llamada a función

Una vez que hayas inicializado el modelo con tus declaraciones de función, puedes solicitarle el modelo con la función definida. Deberías usar las llamadas a funciones con las instrucciones de chat (SendMessage()), ya que las llamadas a función suelen beneficiarse de con el contexto de instrucciones y respuestas 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)
}