Generar un resultado estructurado (como JSON) con la API de Gemini

Gemini API muestra respuestas como texto no estructurado de forma predeterminada. Sin embargo, algunos casos de uso requieren texto estructurado, como JSON. Por ejemplo, es posible que uses la respuesta para otras tareas posteriores que requieran un esquema de datos establecido.

Para garantizar que el resultado generado por el modelo siempre cumpla con un esquema específico, puedes definir un esquema de respuesta, que funciona como un modelo para las respuestas del modelo. Luego, puedes extraer datos directamente de la salida del modelo con menos procesamiento posterior.

Estos son algunos ejemplos:

• Asegúrate de que la respuesta de un modelo genere un JSON válido y cumpla con el esquema que proporcionaste.
  Por ejemplo, el modelo puede generar entradas estructuradas para recetas que siempre incluyan el nombre de la receta, la lista de ingredientes y los pasos. Luego, puedes analizar y mostrar esta información con mayor facilidad en la IU de tu app.

• Restringe la forma en que un modelo puede responder durante las tareas de clasificación.
  Por ejemplo, puedes hacer que el modelo analice el texto con un conjunto específico de etiquetas (por ejemplo, un conjunto específico de enums como positive y negative), en lugar de las etiquetas que produce el modelo (que podrían tener un grado de variabilidad como good, positive, negative o bad).

En esta guía, se muestra cómo generar un resultado JSON proporcionando un responseSchema en una llamada a generateContent. Se enfoca en la entrada de solo texto, pero Gemini también puede producir respuestas estructuradas a solicitudes multimodales que incluyen imágenes, videos y audio como entrada.

En la parte inferior de esta página, encontrarás más ejemplos, como cómo generar valores de enum como salida. Para ver ejemplos adicionales de cómo generar resultados estructurados, consulta la lista de Esquemas de ejemplo y respuestas del modelo en la documentación de Google Cloud.

Otras opciones para trabajar con Gemini API

• De manera opcional, experimenta con una versión alternativa "Google AI" de la función Gemini API
  Obtén acceso sin costo (dentro de los límites y cuando esté disponible) con Google AI Studio y los SDKs de cliente Google AI. Estos SDKs deben usarse solo para crear prototipos en apps web y para dispositivos móviles.

  Una vez que estés familiarizado con el funcionamiento de un Gemini API, migra a nuestros SDKs de Vertex AI in Firebase (esta documentación), que tienen muchas funciones adicionales importantes para las apps web y para dispositivos móviles, como proteger la API del abuso con Firebase App Check y compatibilidad con archivos multimedia grandes en las solicitudes.

• De manera opcional, llama al Vertex AI Gemini API del servidor (como con Python, Node.js o Go)
  Usa los SDK de Vertex AI del servidor, Firebase Genkit o Firebase Extensions para Gemini API.

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 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 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.

Paso 1: Define un esquema de respuesta

Define un esquema de respuesta para especificar la estructura del resultado de un modelo, los nombres de los campos y el tipo de datos esperado para cada campo.

Cuando un modelo genera su respuesta, usa el nombre del campo y el contexto de tu instrucción. Para que tu intención sea clara, te recomendamos que uses una estructura clara, nombres de campos inequívocos y, si es necesario, descripciones.

Consideraciones para los esquemas de respuesta

Ten en cuenta lo siguiente cuando escribas tu esquema de respuesta:

• El tamaño del esquema de respuesta se considera para el límite de tokens de entrada.

• La función de esquema de respuesta admite los siguientes tipos de MIME de respuesta:

  • application/json: Es el JSON de salida como se define en el esquema de respuesta (útil para los requisitos de salida estructurada).

  • text/x.enum: Muestra un valor de enumeración como se define en el esquema de respuesta (útil para las tareas de clasificación).

• La función de esquema de respuesta admite los siguientes campos de esquema:

  enum items

  maxItems nullable

  properties required

  Si usas un campo no compatible, el modelo aún puede controlar tu solicitud, pero ignorará el campo. Ten en cuenta que la lista anterior es un subconjunto del objeto de esquema de OpenAPI 3.0 (consulta la referencia del esquema de Vertex AI).

• 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 opuesto al comportamiento predeterminado de Vertex AI Gemini API.

Paso 2: Envía un mensaje con un esquema de respuesta para generar JSON

En el siguiente ejemplo, se muestra cómo generar un resultado JSON estructurado.

Para generar un resultado estructurado, debes especificar durante la inicialización del modelo el responseMimeType apropiado (en este ejemplo, application/json), así como el responseSchema que deseas que use el modelo.

Gemini 1.5 Pro y Gemini 1.5 Flash admiten el uso de responseSchema.

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

Ejemplos adicionales

Para ver ejemplos adicionales sobre cómo puedes usar y generar resultados estructurados, consulta la lista de Esquemas de ejemplo y respuestas del modelo en la documentación de Google Cloud.

Genera valores de enum como salida

En el siguiente ejemplo, se muestra cómo usar un esquema de respuesta para una tarea de clasificación. Se le pide al modelo que identifique el género de una película según su descripción. El resultado es un valor de enumeración de texto sin formato que el modelo selecciona de una lista de valores definidos en el esquema de respuesta proporcionado.

Para realizar esta tarea de clasificación estructurada, debes especificar durante la inicialización del modelo el responseMimeType apropiado (en este ejemplo, text/x.enum), así como el responseSchema que deseas que use el modelo.

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

Otras opciones para controlar la generación de contenido

• Obtén más información sobre el diseño de instrucciones para que puedas influir en el modelo y generar resultados específicos según tus necesidades.
• Configura los parámetros del modelo para controlar cómo este genera una respuesta. Estos parámetros incluyen los tokens de salida máximos, la temperatura, topK y topP.
• Usa la configuración de seguridad para ajustar la probabilidad de recibir respuestas que se puedan considerar dañinas, como incitación al odio o a la violencia y contenido sexual explícito.
• Establece instrucciones del sistema para guiar el comportamiento del modelo. Esta función es como un “preámbulo” que agregas antes de que se exponga el modelo a cualquier otra instrucción del usuario final.

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