Instructivo sobre llamadas a funciones

Las llamadas a funciones te permiten obtener resultados de datos estructurados de los modelos generativos con mayor facilidad. 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.

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

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

Define una función de API

Crea una función que realice una solicitud a la API. Esta función se debe definir dentro del código de tu aplicación, pero podría 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:

async function setLightValues(brightness, colorTemp) {
  return {
    brightness: brightness,
    colorTemperature: colorTemp
  };
}

Crea declaraciones de funciones

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 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 iluminación:

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

// Put functions in a "map" keyed by the function name so it is easier to call
const functions = {
  controlLight: ({ brightness, colorTemperature }) => {
    return setLightValues( brightness, colorTemperature)
  }
};

Cómo declarar funciones durante la inicialización del modelo

Cuando quieras usar llamadas a función con un modelo, debes proporcionar tus declaraciones de función cuando inicialices el objeto del modelo. Para declarar funciones, debes configurar el parámetro tools del modelo:

const { GoogleGenerativeAI } = require("@google/generative-ai");

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

const generativeModel = genAI.getGenerativeModel({
  model: "gemini-2.0-flash",
  // Specify the function declaration.
  tools: {
    functionDeclarations: [controlLightFunctionDeclaration],
  },
});

Genera una llamada a función

Una vez que hayas inicializado el modelo con tus declaraciones de funciones, puedes solicitarle la función definida. Debes usar llamadas a función con instrucciones de chat (sendMessage()), ya que, por lo general, las llamadas a función se benefician de tener el contexto de las instrucciones y respuestas anteriores.

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

const result = await chat.sendMessage(prompt);
const call = result.response.functionCalls()[0];

if (call) {
  // Call the executable function
  const apiResponse = await functions[call.name](call.args);

  // Send the API response back to the model
  const result2 = await chat.sendMessage([{functionResponse: {
    name: 'controlLight',
    response: apiResponse
  }}]);

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

Modo de llamada a función

Puedes usar el parámetro de llamada a función mode para modificar el comportamiento de ejecución de la función. Hay tres modos disponibles:

  • AUTO: Es el comportamiento predeterminado del modelo. El modelo decide predecir una llamada a función o una respuesta de lenguaje natural.
  • ANY: El modelo está restringido para predecir siempre una llamada a función. Si no se proporciona allowed_function_names, el modelo elige entre todas las declaraciones de funciones disponibles. Si se proporciona allowed_function_names, el modelo elige entre el conjunto de funciones permitidas.
  • NONE: El modelo no predecirá una llamada a función. En este caso, el comportamiento del modelo es el mismo que si no pasas ninguna declaración de función.

También puedes pasar un conjunto de allowed_function_names que, cuando se proporciona, limita las funciones a las que llamará el modelo. Solo debes incluir allowed_function_names cuando el modo sea ANY. Los nombres de las funciones deben coincidir con los nombres de las declaraciones de funciones. Con el modo establecido en ANY y el conjunto allowed_function_names, el modelo predecirá una llamada a función del conjunto de nombres de funciones proporcionados.

Para especificar el modo de llamada a función, configura un parámetro toolConfig cuando inicialices el modelo generativo.

const generativeModel2 = genAI.getGenerativeModel({
  // Setting a function calling mode is only available in Gemini 1.5 Pro.
  model: "gemini-1.5-pro-latest",
  tools: {
    functionDeclarations: [getExchangeRateFunctionDeclaration],
  },
  toolConfig: {
    functionCallingConfig: {
      // Possible values are: Mode.AUTO, Mode.ANY, Mode.NONE
      mode: FunctionCallingMode.ANY
    }
  }
});