Instructivo sobre llamadas a funciones

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

Las llamadas a función facilitan la obtención de resultados de datos estructurados de modelos generativos. Luego, puedes usar estos resultados para llamar a otras APIs y mostrar los datos de respuesta relevantes al 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. Estas son funciones que escribes en el lenguaje de tu app (es decir, no son Google Cloud Functions). El modelo puede pedirte que llames a una función y devuelvas el resultado para ayudar al modelo a controlar tu consulta.

Si aún no lo hiciste, consulta la Introducción a las llamadas a funciones para obtener más información.

API de ejemplo para control de iluminación

Imagina que tienes un sistema de control de iluminación básico con una interfaz de programación de aplicaciones (API) y quieres permitir que los usuarios controlen las luces mediante solicitudes de texto simples. Puedes usar la función Llamadas a funciones para interpretar las solicitudes de cambio de iluminación de los usuarios y traducirlas en llamadas a la API para establecer los valores de iluminación. Este hipotético sistema de control de iluminación te permite controlar el brillo de la luz y la temperatura de color, definidos como dos parámetros separados:

Para simplificar, este sistema de iluminación imaginario solo tiene una luz, por lo que el usuario no tiene que especificar una habitación o ubicación. Esta es una solicitud JSON de ejemplo que podrías enviar a la API de control de iluminación para cambiar el nivel de luz al 50% con la temperatura de color de 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 interprete las solicitudes de iluminación de los usuarios y las asigne a la configuración de la API para controlar los valores de brillo y temperatura de color de una luz.

Antes de comenzar: Configura tu proyecto y clave de API

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

Define una función de API

Crea una función que realice una solicitud a la API. Esta función debe definirse dentro del código de tu aplicación, pero podría llamar a servicios o a las 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 la aplicación. A modo de demostración, en este instructivo, se define una función de API de prueba 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 declaras una función para que la use el modelo, debes incluir la mayor cantidad de detalles posible en las descripciones de las funciones y los parámetros. El modelo generativo usa esta información para determinar qué función seleccionar y cómo proporcionar valores para los parámetros en la llamada a función. En el siguiente código, se muestra cómo declarar 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{"currencyDate", "currencyFrom"},
        },
    }},
}

Declara funciones durante la inicialización del modelo

Si deseas usar la llamada a función con un modelo, debes proporcionar las declaraciones de la función cuando inicialices el objeto del modelo. Para declarar las funciones, configura 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 las declaraciones de la función, puedes solicitarle al modelo con la función definida. Debes usar las llamadas a función con instrucciones de chat (SendMessage()), ya que las llamadas a función generalmente se benefician de tener el contexto de las instrucciones y las 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)
}