Llamadas a función con la API de Gemini


Los modelos generativos son potentes para resolver muchos tipos de problemas. Sin embargo, tienen las siguientes limitaciones:

  • Se congelan después del entrenamiento, lo que lleva a un conocimiento inactivo.
  • No pueden consultar ni modificar datos externos.

Las llamadas a función pueden ayudarte a superar algunas de estas limitaciones. A veces, la llamada a función se denomina uso de herramientas porque permite que un modelo use herramientas externas, como APIs y funciones, para generar su respuesta final.

Puedes obtener más información sobre las llamadas a función en la documentación de Google Cloud, que incluye una lista útil de casos de uso para las llamadas a función.

Las llamadas a función son compatibles con Gemini 1.0 Pro, Gemini 1.5 Pro y Gemini 1.5 Flash.

En esta guía, se muestra cómo puedes implementar una configuración de llamada a función similar al ejemplo que se describe en la siguiente sección principal de esta página. A grandes rasgos, estos son los pasos para configurar las llamadas a función en tu app:

  1. Escribe una función que pueda proporcionarle al modelo la información que necesita para generar su respuesta final (por ejemplo, la función puede llamar a una API externa).

  2. Crea una declaración de función que describa la función y sus parámetros.

  3. Proporciona la declaración de la función durante la inicialización del modelo para que este sepa cómo usarla, si es necesario.

  4. Configura tu app para que el modelo pueda enviar la información necesaria para que la app llame a la función.

  5. Pasa la respuesta de la función al modelo para que este pueda generar su respuesta final.

Ir a la implementación de código

Descripción general de un ejemplo de llamada a función

Cuando envías una solicitud al modelo, también puedes proporcionarle un conjunto de “herramientas” (como funciones) que puede usar para generar su respuesta final. Para usar estas funciones y llamarlas ("llamadas a funciones"), el modelo y tu app deben pasar información entre sí, por lo que la forma recomendada de usar las llamadas a funciones es a través de la interfaz de chat de varias vueltas.

Imagina que tienes una app en la que un usuario podría ingresar un mensaje como el siguiente: What was the weather in Boston on October 17, 2024?.

Es posible que los modelos de Gemini no conozcan esta información del clima. Sin embargo, imagina que conoces una API de servicio meteorológico externo que puede proporcionarla. Puedes usar las llamadas a función para darle al modelo de Gemini una ruta de acceso a esa API y su información meteorológica.

Primero, escribes una función fetchWeather en tu app que interactúa con esta API externa hipotética, que tiene esta entrada y salida:

Parámetro Tipo Obligatorio Descripción
Entrada
location Objeto Sí Es el nombre de la ciudad y su estado para obtener el clima.
Solo se admiten ciudades de EE.UU. Siempre debe ser un objeto anidado de city y state.
date String Sí Es la fecha para la que se recuperará el clima (siempre debe estar en formato YYYY-MM-DD).
Salida
temperature Número entero Sí Temperatura (en grados Fahrenheit)
chancePrecipitation String Sí Probabilidad de precipitaciones (expresada como porcentaje)
cloudConditions String Sí Condiciones de la nube (una de clear, partlyCloudy, mostlyCloudy, cloudy)

Cuando inicializas el modelo, le indicas que existe esta función fetchWeather y cómo se puede usar para procesar las solicitudes entrantes, si es necesario. Esto se denomina "declaración de función". El modelo no llama a la función directamente. En cambio, a medida que el modelo procesa la solicitud entrante, decide si la función fetchWeather puede ayudarlo a responderla. Si el modelo decide que la función puede ser útil, genera datos estructurados que ayudarán a que tu app llame a la función.

Vuelve a mirar la solicitud entrante: What was the weather in Boston on October 17, 2024?. Es probable que el modelo decida que la función fetchWeather puede ayudarlo a generar una respuesta. El modelo analizaría qué parámetros de entrada se necesitan para fetchWeather y, luego, generaría datos de entrada estructurados para la función que se ven de la siguiente manera:

{
  functionName: fetchWeather,
  location: {
    city: Boston,
    state: Massachusetts  // the model can infer the state from the prompt
  },
  date: 2024-10-17
}

El modelo pasa estos datos de entrada estructurados a tu app para que esta pueda llamar a la función fetchWeather. Cuando tu app recibe las condiciones climáticas de la API, pasa la información al modelo. Esta información del clima permite que el modelo complete su procesamiento final y genere su respuesta a la solicitud inicial de What was the weather in Boston on October 17, 2024?.

El modelo podría proporcionar una respuesta final de lenguaje natural, como la siguiente: On October 17, 2024, in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

Diagrama que muestra cómo las llamadas a funciones implican que el modelo interactúe con una función en tu app 

Implementa llamadas a función

Antes de comenzar

Si aún no lo hiciste, completa la guía de introducción a los SDK de Vertex AI in Firebase. Asegúrate de haber hecho lo siguiente:

  1. Configura un proyecto de Firebase nuevo o existente, incluido el uso del plan de precios Blaze y la habilitación de las APIs requeridas.

  2. Conecta tu app a Firebase, lo que incluye registrarla y agregar la configuración de Firebase a ella.

  3. Agrega el SDK y, luego, inicializa el servicio de Vertex AI y el modelo generativo en tu app.

Una vez que hayas conectado tu app a Firebase, agregado el SDK y inicializado el servicio Vertex AI y el modelo generativo, todo estará listo para llamar a Gemini API.

En los pasos restantes de esta guía, se muestra cómo implementar una configuración de llamada a función similar al flujo de trabajo que se describe en Descripción general de un ejemplo de llamada a función (consulta la sección superior de esta página).

Puedes ver el ejemplo de código completo de esta función de llamada más adelante en esta página.

Paso 1: Escribe la función

Imagina que tienes una app en la que un usuario podría ingresar un mensaje como el siguiente: What was the weather in Boston on October 17, 2024?. Es posible que los modelos de Gemini no conozcan esta información del clima. Sin embargo, imagina que conoces una API de servicio meteorológico externo que puede proporcionarla. El ejemplo de esta guía se basa en esta API externa hipotética.

Escribe la función en tu app que interactuará con la API externa hipotética y proporciona al modelo la información que necesita para generar su solicitud final. En este ejemplo del clima, será una función fetchWeather la que realice la llamada a esta hipotética API externa.

Paso 2: Crea una declaración de función

Crea la declaración de función que más adelante le proporcionarás al modelo (siguiente paso de esta guía).

En tu declaración, incluye tantos detalles como sea posible en las descripciones de la función y sus parámetros.

El modelo usa la información de la declaración de la función para determinar qué función seleccionar y cómo proporcionar valores de parámetros para la llamada real a la función. Consulta Comportamientos y opciones adicionales más adelante en esta página para saber cómo el modelo puede elegir entre las funciones y cómo puedes controlar esa elección.

Ten en cuenta lo siguiente sobre el esquema que proporciones:

  • Debes proporcionar declaraciones de funciones en un formato de esquema que sea compatible con el esquema de OpenAPI. Vertex AI ofrece asistencia limitada del esquema de OpenAPI.

    • Los siguientes atributos son compatibles: type, nullable, required, format, description, properties, items, enum.

    • Los siguientes atributos no son compatibles: default, optional, maximum, oneOf.

  • De forma predeterminada, para los SDK de Vertex AI in Firebase, todos los campos se consideran obligatorios, a menos que los especifiques como opcionales en un array optionalProperties. En el caso de estos campos opcionales, el modelo puede propagarlos o omititlos. Ten en cuenta que esto es lo opuesto al comportamiento predeterminado de Vertex AI Gemini API.

Para conocer las prácticas recomendadas relacionadas con las declaraciones de funciones, incluidas sugerencias de nombres y descripciones, consulta Prácticas recomendadas en la documentación de Google Cloud.

A continuación, te indicamos cómo puedes escribir una declaración de función:

Paso 3: Proporciona la declaración de la función durante la inicialización del modelo

La cantidad máxima de declaraciones de funciones que puedes proporcionar con la solicitud es de 128. Consulta Comportamientos y opciones adicionales más adelante en esta página para saber cómo el modelo puede elegir entre las funciones y cómo puedes controlar esa elección (con un toolConfig para establecer el modo de llamada a función).

Aprende a elegir un modelo de Gemini y, de manera opcional, una ubicación adecuada para tu caso de uso y app.

Paso 4: Llama a la función para invocar la API externa

Si el modelo decide que la función fetchWeather puede ayudarlo a generar una respuesta final, tu app debe realizar la llamada real a esa función con los datos de entrada estructurados que proporciona el modelo.

Dado que la información debe pasarse de un lado a otro entre el modelo y la app, la forma recomendada de usar las llamadas a función es a través de la interfaz de chat de varias vueltas.

En el siguiente fragmento de código, se muestra cómo se le indica a tu app que el modelo quiere usar la función fetchWeather. También muestra que el modelo proporcionó los valores de parámetros de entrada necesarios para la llamada a función (y su API externa subyacente).

En este ejemplo, la solicitud entrante contenía la instrucción What was the weather in Boston on October 17, 2024?. A partir de esta instrucción, el modelo infirió los parámetros de entrada que requiere la función fetchWeather (es decir, city, state y date).

Paso 5: Proporciona el resultado de la función al modelo para generar la respuesta final

Después de que la función fetchWeather muestra la información del clima, tu app debe pasarla al modelo.

Luego, el modelo realiza su procesamiento final y genera una respuesta final de lenguaje natural como la siguiente: On October 17, 2024 in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

Comportamientos y opciones adicionales

Estos son algunos comportamientos adicionales de las llamadas a función que debes adaptar a tu código y las opciones que puedes controlar.

Es posible que el modelo solicite volver a llamar a una función o a otra.

Si la respuesta de una llamada a función no es suficiente para que el modelo genere su respuesta final, es posible que el modelo solicite una llamada a función adicional o una llamada a una función completamente diferente. Esto último solo puede ocurrir si le proporcionas más de una función al modelo en la lista de declaraciones de funciones.

Tu app debe adaptarse a que el modelo pueda solicitar llamadas de función adicionales.

Es posible que el modelo solicite llamar a varias funciones al mismo tiempo.

Puedes proporcionar hasta 128 funciones en la lista de declaración de funciones al modelo. Teniendo en cuenta esto, el modelo puede decidir que se necesitan varias funciones para ayudarlo a generar su respuesta final. Y puede decidir llamar a algunas de estas funciones al mismo tiempo, lo que se denomina llamada a función en paralelo.

Tu app debe adaptarse a que el modelo pueda solicitar varias funciones que se ejecuten al mismo tiempo, y debe proporcionar todas las respuestas de las funciones al modelo.

Gemini 1.5 Pro y Gemini 1.5 Flash admiten llamadas a función en paralelo.

Puedes controlar cómo y si el modelo puede solicitar llamar a funciones.

Puedes colocar algunas restricciones sobre cómo y si el modelo debe usar las declaraciones de funciones proporcionadas. Esto se denomina establecer el modo de llamada a función. Estos son algunos ejemplos:

  • En lugar de permitir que el modelo elija entre una respuesta inmediata de lenguaje natural y una llamada a función, puedes forzarlo para que siempre use llamadas a función. Esto se denomina llamada a función forzada.

  • Si proporcionas varias declaraciones de funciones, puedes restringir el modelo para que use solo un subconjunto de las funciones proporcionadas.

Para implementar estas restricciones (o modos), agrega una configuración de herramienta (toolConfig) junto con la instrucción y las declaraciones de funciones. En la configuración de la herramienta, puedes especificar uno de los siguientes modos. El modo más útil es ANY.

Modo Descripción
AUTO El comportamiento predeterminado del modelo. El modelo decide si usar una llamada a función o una respuesta de lenguaje natural.
ANY El modelo debe usar llamadas a función ("llamada a función forzada"). Para limitar el modelo a un subconjunto de funciones, especifica los nombres de las funciones permitidas en allowedFunctionNames.
NONE El modelo no debe usar llamadas a función. Este comportamiento es equivalente a una solicitud de modelo sin ninguna declaración de función asociada.

El modo de llamada a función es compatible con Gemini 1.5 Pro y Gemini 1.5 Flash.

¿Qué más puedes hacer?

Prueba otras funciones de Gemini API

Aprende a controlar la generación de contenido

También puedes experimentar con instrucciones y configuraciones de modelos con Vertex AI Studio.

Más información sobre los modelos de Gemini

Obtén información sobre los modelos disponibles para varios casos de uso y sus cuotas y precios.


Envía comentarios sobre tu experiencia con Vertex AI in Firebase