Compila funciones de IA generativa con la tecnología de tus datos con Firebase Genkit

1. Antes de comenzar

En este codelab, aprenderás a usar Firebase Genkit, que es un framework de código abierto para integrar la IA generativa en tu app. Puedes usar Genkit con muchas habilidades y herramientas de desarrollo de apps que ya conoces, como Firestore.

Requisitos previos

• Estar familiarizado con Firestore, Node.js y TypeScript

Qué aprenderás

• Explora nuevas formas de compilar con Firestore mediante la búsqueda de similitud de vectores.
• Desmitifica la IA generativa y haz que sea práctico para el desarrollo "cotidiano" de apps con Genkit.
• Prepara tu solución para la integración y la implementación.

Requisitos

• Un navegador de tu elección, como Google Chrome
• Un entorno de desarrollo con un editor de código y una terminal
• Una Cuenta de Google para la creación y administración de tu proyecto de Firebase

2. Revisa la app web y los servicios en la nube que se usan

En esta sección, revisarás la app web que compilarás con este codelab y aprenderás sobre los servicios en la nube que usarás.

App web

En este codelab, trabajarás en la base de código de una app llamada Compass. Es una app de planificación de vacaciones. Los usuarios pueden elegir un destino, analizar sus actividades y crear un itinerario para su viaje.

La app debe mejorar la interacción con su página principal. Por lo tanto, en este codelab, implementarás dos ideas basadas en la IA generativa:

• Actualmente, la app muestra una lista estática de destinos. Modificarás la configuración para que sea dinámica.
• Implementarás un itinerario que se propaga automáticamente para aumentar la tasa de interés.

Servicios usados

En este codelab, usarás muchos servicios y funciones de Firebase y Cloud, y se te proporcionará la mayor parte del código de partida para ellos. En la siguiente tabla, se muestran los servicios que usarás y las razones para usarlos.

3. Configura tu entorno de desarrollo

Verifica la versión de Node.js:

1. En la terminal, verifica que tengas instalada la versión 20.0.0 de Node.js o una posterior:

   node -v
   

2. Si no tienes Node.js 20.0.0 o una versión posterior, descarga la última versión de LTS e instálala.

Obtén el código fuente para el codelab

Si tienes una cuenta de GitHub, haz lo siguiente:

1. Crea un repositorio nuevo con nuestra plantilla de github.com/FirebaseExtended/codelab-ai-genkit-rag
2. Clona el repositorio de GitHub del codelab que acabas de crear:

   git clone https://github.com/<your-github-handle>/codelab-ai-genkit-rag
   

Si no tienes Git instalado o prefieres no crear un repositorio nuevo, haz lo siguiente:

Descarga el repositorio de GitHub como un archivo ZIP.

Revisa la estructura de las carpetas

En tu máquina local, busca el repositorio clonado y revisa la estructura de carpetas:

La carpeta raíz incluye un archivo README.md que ofrece un inicio rápido para ejecutar la aplicación web con instrucciones optimizadas. Sin embargo, si estás principiante, deberías completar este codelab (en lugar de la guía de inicio rápido), ya que contiene el conjunto de instrucciones más completo.

Si no sabes si aplicaste correctamente el código como se indica a lo largo de este codelab, puedes encontrar el código de la solución en la rama de Git end.

Instala Firebase CLI

1. Verifica que hayas instalado Firebase CLI y que su versión 13.6 o una posterior:

   firebase --version
   

2. Si tienes instalado Firebase CLI, pero no es la versión 13.6 o posterior, actualízala:

   npm update -g firebase-tools
   

3. Si no tienes instalado Firebase CLI, instálalo:

   npm install -g firebase-tools
   

Si no puedes actualizar o instalar Firebase CLI debido a errores de permisos, consulta la documentación de npm o usa otra opción de instalación.

Accede a Firebase.

1. En la terminal, accede a Firebase:

   firebase login
   

   Si en la terminal se indica que ya accediste a Firebase, puedes pasar a la sección Configura tu proyecto de Firebase de este codelab.
2. En tu terminal, ingresa Y o N en función de si quieres que Firebase recopile datos. (cualquiera de las opciones funciona para este codelab)
3. En el navegador, selecciona tu Cuenta de Google y haz clic en Permitir.

Instala gcloud CLI de Google Cloud

1. Instala la CLI de gcloud.
2. En tu terminal, accede a Google Cloud:

   gcloud auth login
   

4. Configura el proyecto de Firebase

En esta sección, configurarás un proyecto de Firebase y registrarás una aplicación web de Firebase en él. También habilitarás algunos servicios que la aplicación web de muestra usa más adelante en este codelab.

Todos los pasos de esta sección se realizan en Firebase console.

Crea un proyecto de Firebase

1. Accede a Firebase console con una Cuenta de Google.
2. Haz clic en Crear un proyecto y, luego, ingresa un nombre para el proyecto (por ejemplo, Compass Codelab).
   Recuerda el ID del proyecto que se te asignó automáticamente para tu proyecto de Firebase (o haz clic en el ícono Editar para establecer el ID que prefieras). Necesitarás este ID más adelante para identificar el proyecto de Firebase en Firebase CLI. Si olvidas tu ID, podrás encontrarlo más adelante en Configuración del proyecto.
3. Haz clic en Continuar.
4. Si se te solicita, revisa y acepta las condiciones de Firebase y, luego, haz clic en Continuar.
5. En este codelab, no necesitas usar Google Analytics, por lo que debes desactivar la opción correspondiente.
6. Haz clic en Crear proyecto, espera a que se aprovisione tu proyecto y, luego, haz clic en Continuar.

Agregar una app web a tu proyecto de Firebase

1. Navega a la pantalla Descripción general del proyecto en el proyecto de Firebase y, luego, haz clic en Web.
2. En el cuadro de texto Sobrenombre de la app, ingresa un sobrenombre que se pueda recordar, como My Compass Codelab App.
3. Haz clic en Registrar app > Siguiente > Siguiente > Ir a la consola.
   Puedes omitir todos los pasos relacionados con el "hosting" en el flujo de app web porque, de manera opcional, configurarás un servicio de hosting más adelante en este codelab.

Perfecto. Ya registraste una app web en tu nuevo proyecto de Firebase.

Actualiza tu plan de facturación de Firebase

Para usar Firebase Genkit y Vertex AI (y sus servicios en la nube subyacentes), debes actualizar tu proyecto de Firebase para habilitar la facturación.

Además, ten en cuenta que, si habilitas la facturación en tu proyecto de Firebase, se te cobrarán las llamadas que Genkit realice a la API de Gemini. Obtén más información sobre los precios de Vertex AI.

Para actualizar el plan de facturación de tu proyecto, sigue estos pasos:

1. Navega a Planes de facturación de Firebase en tu proyecto de Firebase.
2. En el diálogo Planes de facturación de Firebase, selecciona el plan Blaze y cómpralo.

Habilite Cloud Firestore

1. Navega a Firestore con el panel de navegación izquierdo.
2. Haz clic en Crear base de datos > Iniciar en modo de prueba > Siguiente.
3. Selecciona tu ubicación preferida de Cloud Firestore (o simplemente déjala como predeterminada).
4. Haz clic en Habilitar.

Habilita Vertex AI

1. En la terminal, vincula gcloud CLI a tu proyecto de Firebase:

   gcloud config set project YOUR_PROJECT_ID
   

2. Habilita el servicio de Vertex AI:

   gcloud services enable aiplatform.googleapis.com
   

5. Configura la app web

Para ejecutar la app web, deberás ejecutar comandos en tu terminal y agregar código en el editor de código.

Configura Firebase CLI para que se ejecute en tu proyecto de Firebase

En la terminal, ejecuta el siguiente comando para indicarle a la CLI que use tu proyecto de Firebase:

firebase use YOUR_PROJECT_ID

Carga datos de Firestore

La base de código de este codelab ya tiene algunos datos de muestra generados para ti.

1. Para importar los datos a tu instancia de Firestore, ejecuta este comando en la terminal:

   cd load-firestore-data
   npm ci
   node index.js YOUR_PROJECT_ID
   cd ..
   

2. En Firebase console, navega a Firestore dentro de tu proyecto de Firebase. Deberías ver el esquema importado.

Conecta la app web a tu proyecto de Firebase

La base de código de tu app web necesita saber qué proyecto de Firebase debe usar para sus servicios, como la base de datos. Para ello, debes agregar la configuración de Firebase a la base de código de tu app.

1. Obtén la configuración de Firebase:
   1. En Firebase console, ve a Configuración del proyecto dentro de tu proyecto de Firebase.
   2. Desplázate hacia abajo hasta la sección Tus apps y selecciona la app web registrada.
   3. En el panel SDK setup and configuration, copia solo el fragmento const firebaseConfig = {...}.
2. Agrega la configuración de Firebase a la base de código de tu aplicación web:
   1. En el editor de código, abre el archivo genkit-functions/src/lib/genkit.config.ts.
   2. Reemplaza la sección relevante con el código que copiaste.
   3. Guarda el archivo.

Obtén una vista previa de la app web en tu navegador

1. En tu terminal, instala las dependencias y, luego, ejecuta la app web:

   npm install
   npm run dev
   

2. En tu navegador, ve a la URL de Hosting alojada de forma local para ver la app web. Por ejemplo, en la mayoría de los casos, la URL es http://localhost:3000/ o algo similar.

La página debería cargarse:

Compass es una app de Next.js que usa componentes del servidor de React, que es la página principal.

Haz clic en Encontrar mi viaje de ensueño. Puedes ver que, actualmente, muestra algunos datos hard-coded para algunos destinos fijos:

Siéntete libre de explorar. Cuando estés listo para continuar, haz clic en el botón de inicio (en la esquina superior derecha).

6. Comienza a usar Firebase Genkit

Ya tienes todo listo para dar el gran paso hacia la IA generativa. En esta sección del codelab, implementarás una función que sugiere un destino en función de la inspiración proporcionada por los usuarios.

Para lograrlo, usarás Firebase Genkit vinculado con Vertex AI de Google Cloud como proveedor del modelo generativo (Gemini). Además, usarás Firebase como almacén de estado de seguimiento y flujo (con Firestore). También puedes usar Firebase para implementar el código de Genkit con Firebase App Hosting.

Genkit tiene una "IU para desarrolladores" que hace que trabajar con la herramienta sea visual y más fácil de usar.

1. Para iniciar la IU de Genkit Developer, ejecuta este comando en una nueva ventana de terminal:

   cd genkit-functions
   npx genkit start
   

2. En tu navegador, navega a la URL de Genkit alojada localmente. En la mayoría de los casos, es http://localhost:4000/.

Integra un modelo de Gemini

Firebase Genkit proporciona el complemento Dotprompt y formato de texto para ayudarte a escribir y organizar tus instrucciones de IA generativa.

Dotprompt está diseñado con la premisa de que los mensajes son código. Escribes y mantienes tus instrucciones en archivos con formato especial llamados archivos dotprompt, haces un seguimiento de los cambios en ellas con el mismo sistema de control de versión que usas para tu código y las implementas junto con el código que llama a tus modelos de IA generativa.

Para usar Dotprompt, comienza con hello-world:

1. En el editor de código, abre el archivo genkit-functions/prompts/1-hello-world.prompt.
   Deberías ver que hay un esquema de entrada y uno de salida.
2. Abre dotprompt/1-hello-world en la IU de Firebase Genkit.
3. Usa cualquier nombre o código de idioma que conozcas, o bien déjalo como una cadena vacía.
4. Haz clic en Run.
5. Prueba con diferentes valores. Los modelos grandes de lenguaje son buenos para comprender instrucciones abreviadas, con errores ortográficos o incompletas en consultas simples como esta.

Define esquemas JSON

Pero ¿qué sucede si no quieres simplemente colocar una pared de texto en la IU de tu app? Es posible que quieras darle un poco de estilo agradable al texto generado.

Con Genkit, puedes especificar el esquema que deseas que genere la salida de un mensaje, y Genkit se encarga del resto. Revisa la siguiente instrucción:

1. En el editor de código, abre el archivo genkit-functions/prompts/2-simple-itinerary.prompt.
   Deberías ver que hay un esquema de entrada y uno de salida.
2. Abre dotprompt/2-simple-itinerary en la IU de Firebase Genkit.
3. Completa los campos de entrada place e interests:

   {
       "place": "paris",
       "interests": [
           "diner"
       ]
   }
   

4. Haz clic en Run.

Con solo definir un esquema, le instruiste al LLM con el resultado que necesitaba. Genkit validará automáticamente la salida y hasta se puede configurar para reintentar regenerar o corregir el resultado si el esquema no coincide.

Entrada multimodal

¿Y si quisieras que la aplicación componga destinos vacacionales personalizados e ideales basados en imágenes de inspiración proporcionadas por tus usuarios? Puedes hacerlo con Genkit junto con un modelo generativo multimodal.

1. En el editor de código, abre el archivo genkit-functions/prompts/imgDescription.prompt.
   Observa la sintaxis de las barras de control de {{media url=this}}.
2. Abre dotprompt/imgDescription en la IU de Firebase Genkit.
3. Usa una imagen en miniatura de Wikipedia en el campo de entrada imageUrls:

   {
       "imageUrls": [ "https://upload.wikimedia.org/wikipedia/commons/thumb/4/4b/La_Tour_Eiffel_vue_de_la_Tour_Saint-Jacques%2C_Paris_ao%C3%BBt_2014_%282%29.jpg/556px-La_Tour_Eiffel_vue_de_la_Tour_Saint-Jacques%2C_Paris_ao%C3%BBt_2014_%282%29.jpg" ]
   }
   

4. Haz clic en Run.

7. Implementa la recuperación

Todas estas generaciones de IA son geniales, pero hay un problema: tienes una base de datos de destinos (lugares y actividades) y quieres que el modelo de Gemini solo use esos para generar su resultado. Por lo tanto, debes asegurarte de que todas las respuestas proporcionadas estén vinculadas con los datos de la base de datos.

Cuando necesitas tomar una consulta no estructurada y encontrar contenido relevante, una de las técnicas más eficaces es la búsqueda de similitud de vectores en las incorporaciones generadas.

• Un vector es solo un array de números. Cada número en el vector es su valor en una dimensión. Entonces, se puede graficar un vector con dos dimensiones en un gráfico.
• Un modelo de incorporación es un tipo de modelo de IA que toma entradas como texto arbitrario y las traza en el grafo. Y la ubicación en el gráfico donde la traza es significativa: las entradas que son similares entre sí terminarán cerca unas de otras.

Búsqueda de similitud de vectores en Firestore

En Firestore, tienes una lista de lugares y cada uno tiene un campo de texto que indica lo que es más conocido de ese lugar.

Crearás un campo de vectores llamado embedding para cada lugar, con los datos del campo knownFor:

1. En tu terminal, ejecuta el siguiente comando para instalar el componente alpha más reciente. Necesitas la versión 2024.05.03 o una posterior:

   gcloud components install alpha
   

2. Crea el índice:

   gcloud alpha firestore indexes composite create --project=YOUR_PROJECT_ID --collection-group=places --query-scope=COLLECTION --field-config=vector-config='{"dimension":"768","flat": "{}"}',field-path=embedding
   

3. Abre placesRetriever en la IU de Firebase Genkit y, luego, ejecútalo.
   El resultado es un objeto andamiaje con texto TODO. Deberás implementar el retriever en los próximos pasos.
4. En el editor de código, abre el archivo genkit-functions/src/lib/placesRetriever.ts.
5. Desplázate hacia abajo y reemplaza el marcador de posición placesRetriever por lo siguiente:

   export const placesRetriever = defineFirestoreRetriever({
     name: 'placesRetriever',
     firestore,
     collection: 'places',
     contentField: 'knownFor',
     vectorField: 'embedding',
     embedder: textEmbeddingGecko,
     distanceMeasure: 'COSINE',
   });
   

Ahora, realiza una búsqueda de prueba:

1. Abre placesRetriever en la IU de Firebase Genkit.
2. Proporciona la siguiente consulta:

   {
       "content": [
           {
               "text": "new orleans"
           }
       ]
   }
   

3. De manera opcional, cambia algunas Opciones, como el límite.
4. Haz clic en Run.

Puedes realizar filtros adicionales en los datos más allá de la similitud si agregas cláusulas where a las Opciones.

8. Generación aumentada de recuperación (RAG)

En la app, tienes varias instrucciones que toman texto, JSON o imágenes para generar destinos vacacionales y otros elementos interesantes para tus usuarios.

Incluso tienes un mensaje que muestra destinos relevantes que están en la base de datos (Firestore).

Es hora de reunirlos en tu primer flujo de generación de aumento de recuperación (RAG):

1. En el editor de código, abre el archivo genkit-functions/prompts/itineraryGen.prompt.
2. Observa cómo evolucionó la instrucción de itinerario simple anterior para aceptar más entradas, incluidas las de activities que muestra el retriever.
3. En el editor de código, abre el archivo genkit-functions/src/lib/itineraryFlow.ts. Este archivo contiene una función de Firebase Genkit llamada flujos.
   
   • Los flujos son funciones con algunas características adicionales: se pueden transmitir, admiten llamadas de forma local y remota, y son totalmente observables. Genkit proporciona herramientas de CLI y de IU para desarrolladores para trabajar con flujos (ejecución, depuración, etc.).
   • Para ayudar con la depuración, los flujos largos deben dividirse en varios pasos.
4. Busca el valor TODO: 2 alrededor de la línea 70. Este es un ejemplo de cómo agregar un paso a un flujo existente. Aquí, reemplazarás el elemento imgDescription vacío por el resultado de la llamada que genera el mensaje imgDescription.
5. Abre itineraryFlow en la IU de Firebase Genkit.
6. Usa la siguiente entrada para probar la ejecución correcta de itineraryFlow con el paso que acabas de agregar:

   {
       "imageUrls": [ "https://upload.wikimedia.org/wikipedia/commons/thumb/4/4b/La_Tour_Eiffel_vue_de_la_Tour_Saint-Jacques%2C_Paris_ao%C3%BBt_2014_%282%29.jpg/556px-La_Tour_Eiffel_vue_de_la_Tour_Saint-Jacques%2C_Paris_ao%C3%BBt_2014_%282%29.jpg" ]
   }
   

7. Haz clic en Run.
8. Si encuentras algún error o comportamiento inesperado, consulta la pestaña Inspeccionar para obtener más detalles. También puedes usar esta pestaña para revisar el historial de ejecuciones de Trace Store.

RAG para tu aplicación web

Consulta la página de la app web Dream Your Vacation (http://localhost:3000/gemini) y su código fuente (src/app/gemini/page.tsx) para ver un ejemplo de integración de Next.js.

9. Implementa tu aplicación

Ahora el último paso es implementar tu aplicación web.

Para ello, puedes usar Firebase App Hosting, la solución de hosting web adaptada al framework que hace que la implementación de apps de Next.js y Angular en un backend sin servidores sea tan simple como confirmar, enviar y terminar.

1. Confirma los cambios en GitHub y envíalos.
2. En Firebase console, navega a App Hosting dentro de tu proyecto de Firebase.
3. Haz clic en Comenzar > Conectarse a GitHub.
4. Selecciona tu cuenta de GitHub y Repositorio. Haz clic en Siguiente.
5. En Configuración de la implementación > Directorio raíz, mantén el valor predeterminado.
6. En la rama Live, selecciona la rama main de tu repositorio de GitHub. Haz clic en Siguiente.
7. Ingresa un ID para tu backend (por ejemplo, compass).
8. Haz clic en Finish and Deploy.

La nueva implementación tardará unos minutos en estar lista. Puedes verificar el estado de la implementación en la sección Hosting de apps de Firebase console.

A partir de este momento, cada vez que envíes un cambio a tu repositorio de GitHub, Firebase App Hosting compilará e implementará tu app automáticamente.

10. Conclusión

¡Felicitaciones! Lograste mucho en este codelab.

Con Firebase Genkit, Firestore y Vertex AI, compilaste un “flujo” para vacaciones a medida que se recomiendan según las preferencias y la inspiración de los usuarios, y se basan en los datos de la app.

También aprendiste varios patrones importantes de ingeniería de software que necesitarás cuando compiles apps de IA generativa:

• Administración de mensajes
• Contenido multimodal
• Esquemas de entrada y salida
• Almacenes de vectores
• Recuperación de datos
• Generación aumentada de recuperación (RAG)
• Instrumentación de “flujo”

Ten en cuenta que Firebase Genkit incluye varias opciones de implementación que no se describieron en este codelab:

• Firebase Cloud Functions
• Cloud Run
• Next.js
• Cualquier entorno de Node.js

Solo tienes que elegir la que te resulte más conveniente ejecutando lo siguiente dentro de la carpeta de tu nodo (package.json):

npx genkit init

Próximos pasos

• Experimenta con instrucciones y aprovecha las ventanas de contexto grandes en Google AI Studio o Vertex AI Studio.
• Obtén más información sobre la búsqueda de generación de aumento de recuperación con IA (RAG).
• Consulta los documentos oficiales de Firebase Genkit.
• Obtén más información sobre las capacidades de búsqueda de similitud en Firestore y Cloud SQL para PostgreSQL.
• Profundiza en los flujos de la IA generativa con las llamadas a funciones.