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 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 tu 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 función"), el modelo y tu app deben pasar información entre sí, por lo que la forma recomendada de usar las llamadas a función 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 meteorológica; 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:

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 funciones". 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 en lenguaje natural, como la siguiente: On October 17, 2024, in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

Implementa llamadas a función

Antes de comenzar

Si aún no lo hiciste, completa la guía de introducción a los SDKs de Vertex AI in Firebase. Asegúrate de haber realizado todo 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 necesarias.

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

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

Después de conectar la app a Firebase, agregar el SDK y, luego, inicializar el servicio Vertex AI y el modelo generativo, podrás 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 la muestra de código completa para este ejemplo de llamada a función más adelante en esta página.

Paso 1: Escribe la función

Imagina que tienes una app en la que un usuario puede ingresar una instrucción como: 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 le proporcionarás al modelo más adelante (paso siguiente de esta guía).

En tu declaración, incluye la mayor cantidad de detalles 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.

  • Se admiten los siguientes atributos: type, nullable, required, format, description, properties, items y 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 omitirlos o propagarlos. 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).

Obtén información para elegir un modelo de Gemini y, opcionalmente, 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 el mensaje 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 muestre la información del clima, tu app debe devolverla al modelo.

Luego, el modelo realiza su procesamiento final y genera una respuesta final en 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.

El modelo puede pedir que se vuelva 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 podría solicitar llamadas a funciones 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 imponer algunas restricciones sobre cómo y si el modelo debe usar las declaraciones de función 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.

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

• Crea conversaciones de varios turnos (chat).
• Genera texto a partir de instrucciones solo de texto.
• Genera texto a partir de instrucciones multimodales (incluidos texto, imágenes, PDF, video y audio).

Aprende a controlar la generación de contenido

• Comprende el diseño de instrucciones, incluidas las prácticas recomendadas, las estrategias y los ejemplos de instrucciones.
• Configura los parámetros del modelo, como la temperatura y la cantidad máxima de tokens de salida.
• Usa la configuración de seguridad para ajustar la probabilidad de recibir respuestas que puedan considerarse dañinas.

Más información sobre los modelos de Gemini

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