En esta entrada, exploraremos cómo construir un asistente RAG agente usando Mastra y una aplicación sitio web ligero en JavaScript para interactuar con él. Al conectar este agente con Elasticsearch, le damos acceso a datos estructurados de jugadores y la capacidad de ejecutar agregaciones estadísticas en tiempo real, para ofrecerte recomendaciones basadas en estadísticas de jugadores. Visita el repositorio de GitHub para seguirle; el README proporciona instrucciones sobre cómo clonar y ejecutar la aplicación por tu cuenta.

Así debería ver cuando todo esté montado:

Nota: Esta entrada del blog se basa en "Construcción de agentes de IA con SDK de IA y Elastic". Si eres nuevo en los agentes de IA en general y en qué podrían servir, empieza por ahí.

Visión general de la arquitectura

En el núcleo del sistema se encuentra un gran modelo de lenguaje (LLM), que actúa como motor de razonamiento del agente (el cerebro). Interpreta la entrada del usuario, decide qué herramientas llamar y orquesta los pasos necesarios para generar una respuesta relevante.

El propio agente está estructurado por Mastra, un framework de agentes dentro del ecosistema JavaScript. Mastra envuelve el LLM con infraestructura backend, lo expone como un endpoint API y proporciona una interfaz para definir herramientas, indicaciones del sistema y comportamiento de agentes.

En el frontend, usamos Vite para andamiar rápidamente una aplicación sitio web React que proporciona una interfaz de chat para enviar consultas al agente y recibir sus respuestas.

Por último, tenemos Elasticsearch, que almacena estadísticas de jugadores y datos de emparejamientos que el agente puede consultar y agregar.

Fondo

Vamos a repasar algunos conceptos fundamentales:

¿Qué es el RAG agente?

Los agentes de IA pueden interactuar con otros sistemas, operar de forma independiente y realizar acciones basadas en sus parámetros definidos. El RAG agente combina la autonomía de un agente de IA con los principios de generación aumentada por recuperación, permitiendo a un LLM elegir qué herramientas llamar y qué datos usar como contexto para generar una respuesta. Lee más sobre RAG aquí.

Elegir un framework, ¿por qué ir más allá del SDK de IA?

Hay muchos frameworks de agentes de IA disponibles y probablemente oíste hablar de los más populares como CrewAI, AutoGen y LangGraph. La mayoría de estos frameworks comparten un conjunto común de funcionalidades, incluyendo soporte para diferentes modelos, uso de herramientas y gestión de memoria.

Aquí tienes una hoja comparativa de marcos de Harrison Chase (CEO de LangChain).

Lo que despertó mi interés con Mastra es que es un framework JavaScript-first diseñado para que desarrolladores full-stack integren fácilmente agentes en su ecosistema. El AI-SDK de Vercel también hace la mayoría de esto, pero donde Mastra destaca es cuando tus proyectos incluyen flujos de trabajo de agentes más complejos. Mastra mejora los patrones base establecido por el AI-SDK y en este proyecto los usaremos conjuntamente.

Marcos y consideraciones sobre la elección del modelo

Aunque estos frameworks pueden ayudarte a construir agentes de IA rápidamente, existen algunos inconvenientes a tener en cuenta. Por ejemplo, al usar cualquier otro framework fuera de agentes de IA o cualquier capa de abstracción en general, pierdes un poco de control. Si el LLM no emplea correctamente las herramientas o hace algo que no quieres, la abstracción dificulta la depuración. Aun así, en mi opinión, este equilibrio merece la facilidad y rapidez que obtienes al construir, especialmente porque estos frameworks están ganando impulso y se iteran constantemente.

De nuevo, estos frameworks son independientes de los modelos, lo que significa que puedes conectar y jugar diferentes modelos; recuerda que los modelos varían en los conjuntos de datos con los que fueron capacitados y, a su vez, varían en las respuestas que dan. Algunos modelos ni siquiera soportan la llamada de herramientas. Así que es posible cambiar y probar diferentes modelos para ver cuál te da las mejores respuestas, pero ten en cuenta que probablemente tendrás que reescribir el prompt del sistema para cada uno. Por ejemplo, usando Llama3.3 en comparación con GPT-4o, implica mucho más indicación e instrucciones específicas para obtener la respuesta que buscas.

Baloncesto de fantasía de la NBA

El baloncesto de fantasía consiste en empezar una liga con un grupo de colegas (advertencia, dependiendo de lo competitivo que sea tu grupo, esto podría afectar al estado de tus amistades), normalmente con algo de dinero en juego. Cada uno de vosotros selecciona un equipo de 10 jugadores para competir contra los 10 jugadores de otro amigo alternando semanalmente. Los puntos que contribuyen a tu puntaje global son cómo se desempeña cada uno de tus jugadores contra sus oponentes en una semana determinada.

Si un jugador de tu equipo se lesiona, es suspendido, etc., hay una lista de jugadores agentes libres disponibles para agregar a tu equipo. Aquí es donde ocurre gran parte de la dificultad en los deportes de fantasía, porque solo tienes un número limitado de fichas y todos están constantemente a la caza del mejor jugador.

Aquí es donde nuestro asistente de IA de la NBA brillará, especialmente en situaciones en las que tienes que decidir rápidamente qué jugador elegir. En lugar de tener que buscar manualmente cómo rinde un jugador contra un oponente específico, el asistente puede encontrar esos datos rápidamente y comparar promedios para darte una recomendación informada.

Ahora que ya sabes lo básico sobre el RAG agente y el baloncesto fantasy de la NBA, vamos a verlo en la práctica.

Construcción del proyecto

Si te quedas atascado en algún momento o no quieres montarlo desde cero, por favor consulta el repositorio.

Lo que vamos a cubrir

1. Andamiaje del proyecto:

   1. Backend (Mastra): Usa NPX Create mastra@latest para andamiar el backend y definir la lógica del agente.

   2. Frontend (Vite + React): Usa npm create vite@latest para construir la interfaz de chat del frontend y así interactuar con el agente.

2. Configuración de variables de entorno

   1. Instala dotenv para gestionar las variables del entorno.

   2. Crea un .env archiva y proporciona las variables requeridas.

3. Configuración de Elasticsearch

   1. Crea un clúster de Elasticsearch (ya sea localmente o en la nube).

   2. Instala el cliente oficial de Elasticsearch.

   3. Cerciórate de que las variables del entorno sean accesibles.

   4. Establece conexión con el cliente.

4. Ingiriendo en masa datos de la NBA en Elasticsearch

   1. Crea un índice con los mapeos apropiados para permitir agregaciones.

   2. Ingirir en masa las estadísticas de los jugadores de un archivo CSV en un índice de Elasticsearch.

5. Definir agregaciones de Elasticsearch

   1. Consulta para calcular promedios históricos contra un oponente específico.

   2. Consulta para calcular los promedios de temporada contra un rival específico.

6. Archivo utilitario de comparación de jugadores

   1. Consolida funciones auxiliares y agregaciones de Elasticsearch.

7. Construcción del agente

   1. Agrega la definición del agente y el prompt del sistema.

   2. Instala Zod y define herramientas.

   3. Agregar una configuración de middleware para manejar CORS.

8. Integración del frontend

   1. Usando el useChat de AI-SDK para interactuar con el agente.

   2. Crea la interfaz para mantener conversaciones bien formateadas.

9. Ejecutando la aplicación

   1. Inicia tanto el backend (servidor Mestra) como el frontend (app React).

   2. Ejemplos de consultas y uso.

10. Qué sigue: Hacer que el agente sea más inteligente

    1. Agregar capacidades de búsqueda semántica para permitir recomendaciones más profundas.

    2. Habilitar la consulta dinámica moviendo la lógica de búsqueda al servidor Elasticsearch MCP (Model Context Protocol).

Prerrequisitos

• Node.js y NPM: Tanto el backend como el frontend funcionan en Node. Cerciórate de tener instalados Node 18+ y npm v9+ (que vienen incluidos con Node 18+).

• Clúster de Elasticsearch: Un clúster activo de Elasticsearch, ya sea localmente o en la nube.

• Clave API de OpenAI: Genera una en la página de claves API del portal para desarrolladores de OpenAI.

Estructura del proyecto

Paso 1: Estructurar el proyecto

1. Primero, crea el directorio nba-ai-assistant-js y navega dentro usando:

Backend:

1. Usa la herramienta de creación de Mastra con el comando:

2. Deberías recibir algunos prompts en tu terminal; para el primero, llamaremos al backend del proyecto:

3. A continuación, mantendremos la estructura predeterminada para almacenar los archivos Mastra, así que introduzca src/.

4. Luego, elegiremos OpenAI como nuestro proveedor de LLM por defecto.

5. Finalmente, te pedirá la clave de la API de OpenAI. Por ahora, elegiremos la opción de saltarlo y proporcionarlo más adelante en un archivo .env .

Frontend:

1. Vuelve al directorio raíz y ejecuta la herramienta de creación de Vite usando este comando: npm create vite@latest frontend -- --template react

Esto debería crear una aplicación ligera de React llamada frontend con una plantilla específica para React.

Si todo va bien, dentro de tu directorio de proyecto, deberías estar mirando un directorio backend que contenga el código Mastra y un directorio frontend con tu app React.

Paso 2: Configuración de variables de entorno

1. Para gestionar claves sensibles, usaremos el paquete dotenv para cargar nuestras variables de entorno desde el .env archivo. Navega al directorio del backend e instala dotenv:

2. Mientras está en el directorio backend, se proporciona un archivo example.env con las variables adecuadas para rellenar. Si creas el tuyo propio, cerciórate de incluir las siguientes variables:

Nota: Cerciórate de que este archivo esté excluido de tu control de versiones agregando .env a .gitignore.

Paso 3: Configuración de Elasticsearch

Primero, necesitas un clúster activo de Elasticsearch. Hay dos opciones:

• Opción A: Usar Elasticsearch Cloud

  • Apúntate a Elastic Cloud

  • Crear un nuevo despliegue

  • Obtén la URL de tu endpoint y la clave API (codificada)

• Opción B: Ejecutar Elasticsearch localmente

  • Instala y ejecuta Elasticsearch localmente

  • Usa http://localhost:9200 como punto final

  • Generar una clave API

Instalación del cliente Elasticsearch en el backend:

1. Primero, instala el cliente oficial de Elasticsearch en tu directorio backend:

2. Luego crea una lib de directorios para almacenar funciones reutilizables y navega hacia ella:

3. Dentro, crea un nuevo archivo llamado elasticClient.js. Este archivo inicializará el cliente Elasticsearch y lo expondrá para su uso en todo tu proyecto.

4. Como usamos módulos ECMAScript (ESM), __dirname and __nombre de archivo no están disponibles. Para cerciorarte de que tus variables de entorno se carguen correctamente desde el archivo .env Archivo en la carpeta de backend, agrega esta configuración en la parte superior de tu archivo:

5. Ahora, inicializa el cliente Elasticsearch usando tus variables de entorno y comprueba la conexión:

Ahora, podemos importar esta instancia cliente a cualquier archivo que necesite interactuar con tu clúster de Elasticsearch.

Paso 4: Ingirir en masa datos de la NBA en Elasticsearch

Conjunto de datos:

Para este proyecto, consultaremos los conjuntos de datos disponibles en el directorio de backend/datos del repositorio. Nuestro asistente de la NBA empleará estos datos como base de conocimiento para realizar comparaciones estadísticas y generar recomendaciones.

• sample_player_game_stats.csv - Estadísticas de juego de un jugador (por ejemplo, puntos, rebotes, robos, etc., por partido por jugador a lo largo de toda su carrera en la NBA). Emplearemos este conjunto de datos para realizar agregaciones. (Nota: Estos son datos simulados, pregenerados para fines demo y no provenientes de fuentes oficiales de la NBA.)

• playerAndTeamInfo.js - Sustituye los metadatos de jugadores y equipos que normalmente proporcionaría una llamada a la API para que el agente pueda relacionar los nombres de jugadores y equipos con IDs. Como usamos datos de muestra, no queremos la sobrecarga de buscar desde una API externa, así que codificamos de forma fija algunos valores que el agente puede referenciar.

Implementación:

1. Mientras estés en el directorio backend/lib , crea un archivo llamado playerDataIngestion.js.

2. Configura las importaciones, resuelve la ruta del archivo CSV y configura el análisis sintáctico. De nuevo, como estamos usando ESM, necesitamos reconstruir __dirname para resolver el camino hacia el CSV de muestra. Además, importaremos Node.js módulos incorporados, fs y readline, para analizar el archivo CSV dado línea por línea.

Esto te prepara para leer y analizar eficientemente el CSV cuando lleguemos al paso de la ingestión masiva.

3. Crear un índice con el mapeo adecuado. Aunque Elasticsearch puede inferir automáticamente los tipos de campos con mapeo dinámico, queremos ser explícitos aquí para que cada estadística se trate como un campo numérico. Esto es importante porque usaremos estos campos para agregaciones más adelante. También queremos usar el tipo float para estadísticas como puntos, rebotes, etc., para cerciorarnos de incluir valores decimales. Finalmente, queremos agregar la propiedad de mapeo dynamic: 'strict' para que Elasticsearch no mapee dinámicamente campos no reconocidos. 

4. Agregar la función para ingirte en masa los datos CSV en tu índice de Elasticsearch. Dentro del bloque de código, saltamos la línea de cabecera. Luego, divide cada elemento de línea por una coma y empújalos en el objeto documento. Este paso también los limpia y cerciora que sean del tipo adecuado. A continuación, enviamos los documentos al array bulkBody junto con la información del índice, que servirá como carga útil para la ingestión masiva en Elasticsearch.

5. Luego, podemos usar la API Bulk de Elasticsearch con elasticClient.bulk() para ingirse varios documentos en una sola solicitud. La gestión de errores a continuación está estructurada para darte un recuento de cuántos documentos no se ingirieron y cuántos fueron exitosos.

6. Ejecuta la función main() a continuación para ejecutar secuencialmente las funciones createIndex() y bulkIngestCsv() .

Si ves un registro de consola que indique que la ingesta masiva fue exitosa, realiza una comprobación rápida en tu índice de Elasticsearch para ver si los documentos realmente se ingirieron con éxito.

Paso 5: Definición de agregaciones de Elasticsearch y consolidación

Estas serán las funciones principales que se emplearán cuando definamos las herramientas para el Agente de IA para comparar las estadísticas de los jugadores entre sí.

1. Navega al directorio backend/lib y crea un archivo llamado elasticAggs.js.

2. Agregar la consulta siguiente para calcular los promedios históricos de un jugador frente a un oponente específico. Esta consulta emplea un filtro bool con 2 condiciones: una que coincide con player_id y otra que coincide con la opponent_team_id, para recuperar solo los juegos relevantes. No necesitamos devolver ningún documento, solo nos importan las agregaciones, así que establecemos size:0. Bajo el bloque aggs , ejecutamos múltiples agregaciones métricas en paralelo en campos como points, rebounds, assists, steals, blocks y fg_percentage para calcular sus valores medios. Los LLMs pueden ser impredecibles con los cálculos y esto transfiere ese proceso a Elasticsearch, cerciorando que nuestro asistente de IA de la NBA tenga acceso a datos precisos.

3. Para calcular los promedios de temporada de un jugador frente a un oponente específico, usaremos prácticamente la misma consulta que la histórica. La única diferencia en esta consulta es que el filtro bool tiene una condición adicional para game_date. El game_date del campo tiene que estar dentro del rango de la temporada actual de la NBA. En este caso, el rango está entre 2024-10-01 y 2025-06-30. Esta condición adicional a continuación garantiza que las agregaciones que sigan aislarán solo los partidos de esta temporada.

Paso 6: Utilidad de comparación de jugadores

Para mantener nuestro código modular y mantenible, crearemos un archivo de utilidad que consolide las funciones auxiliares de metadatos y las agregaciones de Elasticsearch. Esto alimentará la herramienta principal que emplea el agente. Más sobre eso más adelante:

1. Crear un nuevo archivo comparePlayers.js en el directorio backend/lib .

2. Agregar la función siguiente para consolidar los asistentes de metadatos y la lógica de agregación de Elasticsearch en una única función que alimente la herramienta principal empleada por el agente.

Paso 7: Construir el agente

Ahora que creaste el frontend y el backend de estructura, absorbiste datos de los partidos de la NBA y establecido una conexión con Elasticsearch, podemos empezar a juntar todas las piezas para construir el agente.

Definición del agente

1. Navega al archivo index.ts dentro del directorio backend/src/mastra/agents y agrega la definición del agente. Puedes especificar campos como:

• Nombre: Dale a tu agente un nombre que se use como referencia cuando te llamen en el frontend.

• Instrucciones/prompt del sistema: Un prompt del sistema proporciona al LLM el contexto inicial y las reglas a seguir durante la interacción. Es similar al prompt que los usuarios envían a través del cuadro de chat, pero este se da antes de cualquier entrada del usuario. De nuevo, esto cambiará según el modelo que elijas.

• Modelo: ¿Qué LLM usar (Mastra soporta OpenAI, Anthropic, modelos locales, etc.).

• Herramientas: Una lista de funciones de la herramienta que el agente puede llamar.

• Memoria: (Opcional) si queremos que el agente recuerde el historial de conversaciones, etc. Para simplificar, podemos empezar sin memoria persistente, aunque Mastra la admite.

Definición de herramientas

1. Navega al archivo index.ts dentro del directorio backend/src/mastra/tools .

2. Instala Zod usando el comando:

3. Agregar definiciones de herramientas. Ten en cuenta que importamos la función dentro del archivo comparePlayers.js como la función principal que el agente usará al llamar a esta herramienta. Usando la función createTool() de Mastra, registraremos nuestro playerComparisonTool. Los campos incluyen:

• id: Esta es una descripción en lenguaje natural para ayudar al agente a entender qué hace la herramienta.

• input schema: Para definir la forma de la entrada de la herramienta, Mastra emplea el esquema Zod , que es una biblioteca de validación de esquema TypeScript. Zod ayuda cerciorar de que el agente reciba entradas estructuradas correctamente y evita que la herramienta se ejecute si la estructura de entrada no coincide.

• description: Esta es una descripción en lenguaje natural para ayudar al agente a entender cuándo llamar y usar la herramienta.

• execute: La lógica que se ejecuta cuando se llama a la herramienta. En nuestro caso, estamos usando una función auxiliar importada para devolver estadísticas de rendimiento.

Adición de middleware para manejar CORS

Agregar middleware en el servidor Mastra para manejar CORS. Dicen que hay tres cosas en la vida que no puedes evitar: la muerte, los impuestos, y para los desarrolladores web es el CORS. En resumen, el Intercambio de Recursos entre Orígenes es una función de seguridad en el navegador que bloquea al frontend para que no haga peticiones a un backend que se ejecuta en otro dominio o puerto. Aunque ejecutamos tanto el backend como el frontend en localhost, usan puertos diferentes, lo que activa la política CORS. Necesitamos agregar el middleware especificado en la documentación de Mastra para que nuestro backend permita esas peticiones desde el frontend.

1. Navega al archivo index.ts dentro del directorio backend/src/mastra y agrega la configuración para CORS:

• origin: ['http://localhost:5173']

  • Permite solicitudes solo desde esta dirección (dirección predeterminada de Vite)

• allowMethods: ["GET", "POST"]

  • Métodos HTTP que están permitidos. La mayoría de las veces, será usando POST.

• allowHeaders: ["Content-Type", "Authorization", "x-mastra-client-type, "x-highlight-request", "traceparent"],

  • Estos deciden qué encabezados personalizados pueden usar en las solicitudes

Paso 8: Integración del frontend

Este componente React proporciona una interfaz de chat sencilla que se conecta al agente Mastra AI usando el gancho useChat() de @ai-sdk/react. También vamos a usar este gancho para mostrar el uso de tokens, llamadas a herramientas y para renderizar la conversación. En el prompt del sistema anterior, también pedimos al agente que genere la respuesta en markdown, así que usaremos react-markdown para formatear correctamente la respuesta.

1. Mientras estés en el directorio frontend, instala el paquete @ai-sdk/react para usar el hook useChat().

2. Mientras estés en el mismo directorio, instala React Markdown para que podamos formatear correctamente la respuesta que genera el agente.

3. Implementar useChat(). Este gancho gestionará la interacción entre tu frontend y el backend de tu agente de IA. Gestiona el estado del mensaje, la entrada del usuario, el estado y te proporciona ganchos de ciclo de vida para fines de observabilidad. Las opciones que descartamos incluyen:

• api: Esto define el punto final de tu Mastra AI Agent. Por defecto se pone en el puerto 4111 y también queremos agregar la ruta que soporta respuestas en streaming.

• onToolCall: Esto se ejecuta cada vez que el agente llama a una herramienta; Lo estamos usando para rastrear qué herramientas está llamando nuestro agente.

• onFinish: Esto se ejecuta después de que el agente complete una respuesta completa. Aunque activamos el streaming, onFinish seguirá ejecutar luego de recibir el mensaje completo y no luego de cada chunk. Aquí, lo estamos usando para rastrear nuestro uso de tokens. Esto puede ser útil para monitorizar los costos de los LLM y optimizarlos.

4. Por último, ve al componente ChatUI.jsx en el directorio frontend/components para crear la interfaz que mantenga nuestra conversación. A continuación, envuelve la respuesta en un componente ReactMarkdown para formatear correctamente la respuesta del agente.

Paso 9: Ejecutar la aplicación

¡Felicidades! Ahora estás listo para ejecutar la aplicación. Sigue estos pasos para empezar tanto el backend como el frontend.

1. En una ventana de terminal, empezando desde el directorio raíz, navega hasta el directorio backend e inicia el servidor Mestra:

2. En otra ventana de terminal, empezando desde el directorio raíz, navega hasta el directorio frontend e inicia la aplicación React:

3. Ve a tu navegador y navega a:

http://localhost:5173

Deberías poder ver la interfaz del chat. Prueba estos ejemplos de prompts:

• "Compara a LeBron James y Stephen Curry"

• "¿A quién debería elegir entre Jayson Tatum y Luka Doncic?"

Qué sigue: Hacer que el agente sea más inteligente

Para que el asistente sea más agenciado y las recomendaciones más perspicaces, agregaré algunas mejoras clave en la próxima iteración.

Búsqueda semántica de noticias de la NBA

Hay un montón de factores que pueden afectar al rendimiento de los jugadores, muchos de los cuales no aparecen en las estadísticas brutas. Cosas como reportes de lesiones, cambios en la alineación o incluso análisis postpartido, solo se pueden encontrar en artículos de prensa. Para captar este contexto adicional, agregaré capacidades de búsqueda semántica para que el agente pueda recuperar artículos relevantes de la NBA e incluir esa narrativa en sus recomendaciones.

Búsqueda dinámica con el servidor MCP de Elasticsearch

MCP (Model Context Protocol) se está convirtiendo rápidamente en el estándar para cómo los agentes se conectan a fuentes de datos. Migraré la lógica de búsqueda al servidor Elasticsearch MCP, que permite al agente construir consultas dinámicamente en lugar de depender de funciones de búsqueda predefinidas que proporcionamos. Esto nos permite emplear más flujos de trabajo en lenguaje natural y reduce la necesidad de escribir manualmente cada consulta de búsqueda. Descubre más sobre el servidor MCP de Elasticsearch y el estado actual del ecosistema aquí.

Estos cambios ya están en marcha, ¡estad atentos!

Conclusión

En este blog, creamos un asistente RAG agente que ofrece recomendaciones personalizadas para tu equipo de baloncesto de fantasía usando JavaScript, Mastra y Elasticsearch. Cubrimos lo siguiente:

• Fundamentos del RAG agente y cómo combinar la autonomía de un agente de IA con las herramientas para usar RAG de forma eficaz puede conducir a agentes más matizados y dinámicos.

• Elasticsearch y cómo sus capacidades de almacenamiento de datos y poderosas agregaciones nativas lo convierten en un gran socio como base de conocimiento para un LLM.

• El framework Mastra y cómo simplifica la construcción de estos agentes para desarrolladores en el ecosistema javaScript.

Tanto si eres un fanático del baloncesto, explorando cómo crear agentes de IA, o ambos como yo, espero que este blog te dio algunos cimientos para empezar. El repositorio completo está disponible en GitHub, siéntete libre de clonar y trastear. ¡Ahora, gana esa liga de fantasía!

Revisaremos:

• Mejores prácticas de producción

  • Manejo de errores

  • Pruebas

• Entornos sin servidor

  • Ejecutando el cliente en Elastic Serverless

  • Ejecutando el cliente en un entorno de función como servicio

Puedes consultar el código fuente con los ejemplos aquí.

Mejores prácticas de producción

Manejo de errores en Elasticsearch

Una característica útil del cliente Elasticsearch en Node.js es que expone objetos para los posibles errores en Elasticsearch, de modo que puedes validarlos y manejarlos de diferentes maneras.

Para verlos todos, pon esto: 

Volvamos al ejemplo de búsqueda y tratemos algunos de los posibles errores:

ResponseError en individuo, ocurrirá cuando la respuesta sea 4xx o 5xx, lo que significa que la solicitud es incorrecta o el servidor no está disponible.

Podemos probar este tipo de error generando consultas erróneas, como intentar hacer una consulta de términos en un campo de tipo texto:

Error por defecto:

Error personalizado:

También podemos capturar y manejar cada tipo de error de una manera determinada. Por ejemplo, podemos agregar lógica de reintentos en un TimeoutError.

Pruebas

Las pruebas son clave para garantizar la estabilidad de la aplicación. Para probar el código de forma aislada de Elasticsearch, podemos usar la biblioteca elasticsearch-js-mock al crear nuestro clúster.

Esta biblioteca nos permite instanciar un cliente muy similar al real, pero que responderá a nuestra configuración reemplazando solo la capa HTTP del cliente por una mock, manteniendo el resto igual que el original.

Instalaremos la biblioteca de simulacros y AVA para los exámenes automatizados.

npm install @elastic/elasticsearch-mock

npm install --save-dev ava

Configuraremos el archivo package.json para ejecutar las pruebas. Cerciórate de que se vea así:

Ahora creemos un archivo test.js e instalemos nuestro cliente simulado:

Ahora, agrega un simulacro para la búsqueda semántica:

Ahora podemos crear una prueba para nuestro código, cerciorándonos de que la parte de Elasticsearch siempre devolverá los mismos resultados:

Hagamos las pruebas.

npm run test

¡Hecho! A partir de ahora, podemos probar nuestra app centrándonos al 100% en el código y no en factores externos.

Entornos sin servidor

Cómo ejecutar el cliente en Elastic Serverless

Cubrimos la ejecución de Elasticsearch en la nube o local; sin embargo, el cliente Node.js también soporta conexiones a Elastic Cloud Serverless.

Elastic Cloud Serverless te permite crear un proyecto donde no tienes que preocuparte por la infraestructura, ya que Elastic se encarga de eso internamente, y solo tienes que preocuparte por los datos que quieres indexar y cuánto tiempo quieres tener acceso a ellos.

Desde la perspectiva del uso, los servidores sin servidor desacoplan el cálculo del almacenamiento, proporcionando funciones de escalado automático tanto para búsqueda como para indexación. Esto te permite solo hacer crecer los recursos que realmente necesitas.

El cliente realiza las siguientes adaptaciones para conectarse a Serverless:

• Apaga el olfateo e ignora cualquier opción relacionada con el olfateo

• Ignora todos los nodos que pasan en la configuración excepto el primero, e ignora cualquier filtrado de nodos y seleccionando opciones

• Activa la compresión y el 'TLSv1_2_method' (igual que cuando se configura para Elastic Cloud)

• Agrega un encabezado HTTP 'elastic-api-version' a todas las solicitudes

• Emplea 'CloudConnectionPool' por defecto en lugar de 'WeightedConnectionPool'

• Desactiva los encabezados 'content-type' y 'accept' que venden en favor de los tipos MIME estándar

Para conectar tu proyecto serverless, necesitas usar el parámetro serverMode: serverless.

Cómo ejecutar el cliente en un entorno de función como servicio

En el ejemplo, usamos un servidor Node.js, pero también puedes conectarte usando un entorno de función como servicio con funciones como AWS Lambda, GCP Run, etc.

Otro ejemplo es conectarse a servicios como Vercel, que también es sin servidor. Puedes consultar este ejemplo completo de cómo hacerlo, pero la parte más relevante del endpoint de búsqueda es la siguiente:

Este endpoint reside en la carpeta /api y se ejecuta desde el lado del servidor, de modo que el cliente solo tiene control sobre el parámetro "texto" que corresponde al término de búsqueda.

La participación de usar función como servicio es que, a diferencia de un servidor que funciona 24/7, las funciones solo activan la máquina que ejecuta la función y, una vez terminada, la máquina entra en modo reposo para consumir menos recursos.

Esta configuración puede ser conveniente si la aplicación no recibe demasiadas solicitudes; De lo contrario, los costos pueden ser elevados. También tienes que considerar el ciclo de vida de las funciones y los tiempos de ejecución (que en algunos casos pueden ser solo segundos).

Conclusión

En este artículo, aprendimos a manejar errores, algo crucial en entornos de producción. También cubrimos pruebas de nuestra aplicación simulando el servicio Elasticsearch, que proporciona pruebas fiables independientemente del estado del clúster y nos permite centrarnos en nuestro código.

Finalmente, demostramos cómo crear una pila totalmente serverless aprovisionando tanto Elastic Cloud Serverless como una aplicación Vercel.

En esta primera parte, repasaremos:

• Medio ambiente

  • ¿Frontend, backend o serverless?

  • Conexión del cliente

• Indexación de documentos

  • Cliente Elasticsearch

  • Aplicaciones semánticas

  • Ayudante a granel

• Búsqueda de datos

  • Consulta léxica

  • Consulta semántica

  • Consulta híbrida

Puedes consultar el código fuente con los ejemplos aquí.

¿Qué es el cliente de Node.js Elasticsearch?

El cliente Elasticsearch Node.js es una biblioteca de JavaScript que introduce las llamadas HTTP REST de la API Elasticsearch a JavaScript. Esto facilita la gestión y cuenta con ayudas que simplifican tareas como indexar documentos en lotes.

Medio ambiente

¿Frontend, backend o serverless?

Para crear nuestra aplicación de búsqueda usando el cliente JavaScript, necesitamos al menos dos componentes: un clúster Elasticsearch y un entorno de ejecución en JavaScript para ejecutar el cliente.

El cliente JavaScript soporta todas las soluciones Elasticsearch (Cloud, local y Serverless), y no hay diferencias importantes entre ellas ya que el cliente gestiona todas las variaciones internamente, así que no tienes que preocuparte por cuál usar.

Sin embargo, el tiempo de ejecución de JavaScript debe ejecutar desde el servidor y no directamente desde el navegador.

Esto se debe a que, al llamar a Elasticsearch desde el navegador, el usuario puede obtener información sensible como la clave de la API del clúster, el host o la propia consulta. Elasticsearch recomienda no exponer nunca el clúster directamente a Internet y usar una capa intermedia que abstraiga toda esta información para que el usuario solo pueda ver los parámetros. Puedes leer más sobre este tema aquí.

Sugerimos usar un esquema como este:

En este caso, el cliente solo envía los términos de búsqueda y una clave de autenticación para tu servidor mientras este tiene el control total de la consulta y la comunicación con Elasticsearch.

Conexión del cliente

Empieza creando una clave API siguiendo estos pasos.

Siguiendo el ejemplo anterior, crearemos un servidor Express sencillo y nos conectaremos a él usando un cliente de un servidor Node.JS.

Inicializaremos el proyecto con NPM e instalaremos el cliente Elasticsearch y Express. Esta última es una biblioteca para abrir servidores en Node.js. Usando Express, podemos interactuar con nuestro backend vía HTTP.

Inicialemos el proyecto:

npm init -y

Dependencias de instalación:

npm install @elastic/elasticsearch express split2 dotenv

Déjame explicártelo:

• @elastic/elasticsearch: Es el cliente oficial de Node.js

• express: Nos permitirá montar un servidor nodejs ligero para exponer Elasticsearch

• split2: Divide líneas de texto en un flujo. Útil para procesar nuestros archivos de ndjson línea a línea

• dotenv: Permítenos gestionar variables de entorno usando un .env archivo

Crea un .env archiva en la raíz del proyecto y agrega las siguientes líneas:

De esta manera, podemos importar esas variables usando el paquete dotenv .

Crea un archivo server.js :

Este código configura un servidor de Express.js básico que escucha en el puerto 3000 y se conecta a un clúster Elasticsearch usando una clave API para autenticación. Incluye un punto final /ping que, al acceder mediante una solicitud GET, consulta al clúster de Elasticsearch información básica empleando el método .info() del cliente Elasticsearch. 

Si la consulta tiene éxito, devuelve la información del clúster en formato JSON; de lo contrario, devuelve un mensaje de error. El servidor también emplea middleware de parser corporal para gestionar los cuerpos de las solicitudes JSON.

Ejecuta el archivo para abrir el servidor:

node server.js

La respuesta debería ser la siguiente:

Y ahora, consultemos el /ping endpoint para comprobar el estado de nuestro clúster de Elasticsearch.

Indexación de documentos

Una vez conectados, podemos indexar documentos usando mapeos como semantic_text para búsqueda semántica y texto para consultas de texto completo. Con estos dos tipos de campos, también podemos hacer búsqueda híbrida.

Crearemos un nuevo archivo load.js para generar los mapeos y subir los documentos.

Cliente Elasticsearch

Primero necesitamos instanciar y autenticar al cliente:

Aplicaciones semánticas

Crearemos un índice con datos sobre un hospital veterinario. Almacenaremos la información del dueño, la mascota y los detalles de la visita.

Los datos sobre los que queremos realizar la búsqueda en texto completo, como nombres y descripciones, se almacenarán como texto. Los datos de categorías, como la especie o raza del animal, se almacenarán como palabras clave.

Además, copiaremos los valores de todos los campos en un campo semantic_text para poder ejecutar una búsqueda semántica también con esa información.

Ayudante a granel

Otro beneficio del cliente es que podemos usar el helper de mayor volumen para indexar en lotes. El helper en bulk nos permite gestionar fácilmente cosas como la concurrencia, los intentos y qué hacer con cada documento que pasa por la función y que tiene éxito o fracasa.

Una característica atractiva de este asistente es que puedes trabajar con streams. Esta función te permite enviar un archivo línea por línea en lugar de almacenar el archivo completo en la memoria y enviarlo a Elasticsearch de una sola vez.

Para subir los datos a Elasticsearch, crea un archivo llamado data.ndjson en la raíz del proyecto y agrega la información que aparece a continuación (alternativamente, puedes descargar el archivo con el conjunto de datos desde aquí):

Usamos split2 para transmitir las líneas de archivo mientras el asistente masivo las envía a Elasticsearch.

El código anterior dice un .ndjson archivo línea por línea y en volumen indexa cada objeto JSON en un índice Elasticsearch especificado usando el método helpers.bulk . Transmite el archivo usando createReadStream y split2, establece metadatos de indexación para cada documento y registra cualquier documento que no se procese. Una vez completado, registra el número de elementos indexados con éxito.

Alternativamente a la función indexData , puedes subir el archivo directamente a través de la interfaz usando Kibana y usar la interfaz de archivos de datos de subida.

Ejecutamos el archivo para subir los documentos a nuestro clúster de Elasticsearch.

node load.js

Búsqueda de datos en Elasticsearch

Volviendo a nuestro archivo server.js , crearemos diferentes endpoints para realizar búsquedas léxicas, semánticas o híbridas.

En resumen, este tipo de búsquedas no son mutuamente excluyentes, sino que dependerán del tipo de pregunta que necesites responder.

Tipo de consulta

Caso de uso

Pregunta de ejemplo

Consulta léxica

Las palabras o raíces de palabras en la pregunta probablemente aparecerán en los documentos del índice. Similitud de token entre la pregunta y los documentos.

Busco una camiseta deportiva azul.

Consulta semántica

Las palabras de la pregunta probablemente no aparecerán en los documentos. Similitud conceptual entre la pregunta y los documentos.

Busco ropa para el frío.

Búsqueda híbrida

La pregunta contiene componentes léxicos y/o semánticos. Similitud de tokens y semántica entre la pregunta y los documentos.

Estoy buscando un vestido talla S para una boda en la playa.

Las partes léxicas de la pregunta probablemente formarán parte de títulos y descripciones, o nombres de categorías, mientras que las partes semánticas son conceptos relacionados con esos campos. El azul probablemente será un nombre de categoría o parte de una descripción, y la boda en la playa probablemente no lo sea, pero puede estar semánticamente relacionada con la ropa de lino.

Consulta léxica (/search/lexic?q=<query_term>)

La búsqueda léxica, también llamada búsqueda de texto completo, significa búsqueda basada en la similitud de los tokens; es decir, tras un análisis, se devolverán los documentos que incluyan los tokens en la búsqueda.

Puedes consultar nuestro tutorial práctico de búsqueda léxica aquí.

Probamos con: corte de uñas

Respuesta:

Consulta semántica (/search/semantic?q=<query_term>)

La búsqueda semántica, a diferencia de la búsqueda léxica, encuentra resultados similares al significado de los términos de búsqueda mediante la búsqueda vectorial.

Puedes consultar nuestro tutorial práctico de búsqueda semántica aquí.

Hacemos la prueba con: ¿Quién se hizo una pedicura?

Respuesta:

Consulta híbrida (/search/hybrid?q=<query_term>)

La búsqueda híbrida nos permite combinar la búsqueda semántica y léxica, obteniendo así lo mejor de ambos mundos: se obtiene la precisión de buscar por token, junto con la proximidad de significado de la búsqueda semántica.

Hacemos pruebas con "¿Quién se hizo pedicura o tratamiento dental?"

Respuesta:

Conclusión

En esta primera parte de nuestro serial, explicamos cómo configurar nuestro entorno y crear un servidor con diferentes endpoints de búsqueda para consultar los documentos de Elasticsearch siguiendo las mejores prácticas cliente/servidor. Consulta la segunda parte de nuestro serial, en la que aprenderás las mejores prácticas de producción y cómo ejecutar el cliente de Node.js Elasticsearch en entornos serverless.