Con esta integración, los usuarios de Elasticsearch obtienen una nueva opción de despliegue que mantiene los datos dentro de su perímetro de seguridad, ofrece costos previsibles de infraestructura y se ejecuta de forma nativa en Google Cloud. Al mismo tiempo, el ecosistema más amplio de Google Cloud obtiene acceso a los modelos de búsqueda y recuperación de última generación de Jina, diseñados específicamente para este fin.

Esta es la primera fase de una implementación más amplia. Junto con los modelos que vienen después, la selección formará una pila de recuperación completa: incrusta tus datos, incrusta búsquedas, recupera y reclasifica candidatos, y extiende la búsqueda a imágenes con incrustaciones multimodales, todo en la infraestructura que controles. Puedes empezar hoy mismo con jina-embeddings-v3, el modelo que ya impulsa las pipelines de búsqueda de producción en todo el ecosistema de Elasticsearch a través de Elastic Inference Service (EIS).

Todos los modelos se ejecutan en una sola NVIDIA L4 (24 GB), el nivel de GPU más rentable de Google Cloud. La mayoría de los otros modelos de incrustación en Model Garden de Google Cloud requieren un A100 80 GB o H100, aproximadamente tres veces el costo de instancia por hora incluso antes de comenzar a contar tokens.

No se requiere licencia comercial adicional cuando se despliega a través de Vertex AI.

¿Por qué Model Garden?

¿Por qué desplegar a través de Model Garden en lugar de usar una API? Se reduce a tres cosas: control, costo y contexto.

Tus datos nunca salen de casa

Lo que más atrae a la mayoría de los desarrolladores es la arquitectura de autodespliegue. Cuando despliegas un modelo de Jina a través de Model Garden, los pesos se ejecutan en instancias de GPU dentro de tu propio proyecto de Google Cloud y tu propia VPC. Esto supone un cambio revolucionario para cualquiera que trabaje en sectores donde la seguridad de los datos es una preocupación, como las finanzas o la salud. Como no hay llamadas externas a API, tus datos confidenciales permanecen dentro de tu perímetro de seguridad.

Escalado con predicción

En lugar de pagar cada vez que incrustas una oración o reclasificas un documento, pagas un costo fijo por hora de instancia. Y dado que todos los modelos de Jina pueden ejecutarse en una sola NVIDIA L4, el nivel de GPU más asequible de Google Cloud, la barrera de entrada es baja. Tanto si procesas mil solicitudes como mil millones, tu factura de infraestructura se mantiene previsible. Este sistema te recompensa por aumentar tu tráfico en lugar de cobrarte impuestos por ello.

Todo bajo un mismo techo

Si tus datos ya están en Elasticsearch en Google Cloud, BigQuery o almacenamiento en el cloud, tiene sentido mantener tus motores de inferencia cerca. Al desplegar a través de Model Garden, los modelos de búsqueda de Jina heredan todas las características empresariales que ya estás utilizando: gestión de identidad y acceso (IAM) para el control de acceso, facturación unificada en tu factura existente de Google Cloud, y la capacidad de conectarse a las pipelines de Vertex AI para flujos de trabajo de operaciones de machine learning (MLOps).

Si bien la API de Jina AI Cloud y Elastic Cloud permiten escalar rápidamente ante picos de tráfico o integrarse con flujos de búsqueda ya existentes, Model Garden resulta la mejor opción para aplicaciones empresariales que exigen altos estándares de seguridad de datos y costos predecibles a gran escala. Elastic quiere adaptarse a tus necesidades.

Modelos de Jina AI

jina-embeddings-v3

Nuestro probado modelo de incrustación multilingüe con 572 millones de parámetros y 8000 de contexto de tokens. Obtiene una puntuación de 65,5 en el Massive Text Embedding Benchmark (MTEB) en inglés. Admite cinco adaptadores de adaptación de rango bajo (LoRA) específicos de la tarea (consulta de recuperación/pasaje, coincidencia de texto, clasificación, agrupar) y truncamiento de Matryoshka de 1024 a 64 dimensiones. Ya está ampliamente adoptado en todo el ecosistema de Elasticsearch a través de EIS.

Estamos liderando con la v3 porque muchos sistemas de producción ya dependen de ella. Si estás migrando una pipeline basado en la v3 a Google Cloud, ahora puedes ejecutar el mismo modelo de forma nativa sin tener que cambiar las dimensiones de incrustación ni volver a indexar.

jina-embeddings-v5-text (pequeño y nano)

Nuestros modelos de incrustación de texto de quinta generación, lanzados en febrero de 2026, logran un rendimiento de primer nivel, y compiten con modelos muchas veces más grandes.

v5-text-small (677 millones) obtiene una puntuación de 67,0 en el conjunto de pruebas MTEB multilingües (MMTEB), que abarca 131 tareas de nueve tipos de tareas, y 71,7 en el MTEB en inglés. Es el modelo de incrustación multilingüe sub-1B más potente en la tabla de clasificación de MTEB.

v5-text-nano (239 millones) obtiene una puntuación de 65,5 en MMTEB. Ningún otro modelo con menos de 500 millones de parámetros alcanza este nivel. Con menos de la mitad del tamaño que la mayoría de modelos comparables, es la elección natural para despliegues en el edge y sensibles a la latencia.

Ambos modelos son compatibles con:

• Cuatro adaptadores LoRA específicos para cada tarea: recuperación, coincidencia de texto, clasificación, agrupación. Se selecciona un adaptador apropiado a través del parámetro task en el momento de la inferencia.
• Truncamiento de dimensiones de Matryoshka: reduce las dimensiones de incrustación de 1024 (o 768 para nano) a 32. La pérdida de calidad es mínima con un truncamiento moderado (p. ej., 256 dimensiones). Reducir las dimensiones a la mitad supone, aproximadamente, reducir el espacio de almacenamiento a la mitad.
• Cuantización binaria: comprime incrustaciones de 1024 dimensiones de 2 KB a 128 bytes mediante binarización. Un entrenamiento especial hace que esta compresión tenga pérdidas mínimas.
• Multilingüe: 119 idiomas (pequeño) y 93 (nano).

jina-reranker-v3

Un reclasificador multilingüe de listas de 0,6 mil millones de parámetros construido con una arquitectura de interacción de vanguardia. La consulta y hasta 64 coincidencias candidatas se ingresan en una única ventana de contexto de 131 000 tokens, y el modelo realiza una comparación entre documentos antes de la puntuación. El reclasificador v3 de Jina alcanza un nDCG@10 de 61,94 en BEIR, lo que supera al modelo que tiene un tamaño seis veces menor. Esto difiere fundamentalmente de los reclasificadores puntuales, que puntúan cada documento de forma aislada, lo que produce mejores resultados, especialmente para la recuperación de pasajes de documentos individuales.

jina-clip-v2

Un modelo de incrustación multimodal y multilingüe de 0,9 mil millones que mapea texto e imágenes en un espacio compartido de 1024 dimensiones. Es compatible con:

• 89 idiomas para la recuperación de imágenes de texto.
• Resolución de imagen de 512 × 512.
• Entrada de texto de 8000 tokens.
• Truncamiento Matryoshka de 1024 a 64 dimensiones para ambas modalidades.

Altamente competitivo en pruebas comparativas de conversión de imagen a texto, incluidas las tareas multilingües.

Primeros pasos

Jina Embeddings v3 está disponible en Model Garden hoy. Aquí te explicamos cómo ponerlo en marcha.

Necesitas un proyecto de Google Cloud con la API de Vertex AI habilitada y suficiente cuota de GPU para al menos una instancia g2-standard-8 (NVIDIA L4). Si eres nuevo en Google Cloud, empieza por la guía de configuración.

La página Model Garden para las incrustaciones v3 de Jina te guía por todo el flujo: sube el modelo, crea un endpoint, elige el tipo de máquina y despliega. Ábrela en tu propio proyecto y sigue los pasos guiados. Las máquinas A100 y H100 también están disponibles donde la región y la cuota lo permitan, pero L4 es todo lo que necesitas para comenzar.

Desde el clic hasta la primera incrustación, todo el proceso toma unos minutos.

Lo que viene después

Las incrustaciones v3 de Jina son el punto de partida. En las próximas semanas, llevaremos el resto de la pila de recuperación de Jina a Model Garden: incrustaciones de texto v5 (pequeñas y nano), jina-reranker-v3 y jina-clip-v2 para búsqueda multimodal. Todos se ejecutarán en una sola GPU L4 con el mismo modelo de autodespliegue.

Las MCP Apps cambian la forma de esa respuesta. Una herramienta puede ahora devolver una UI interactiva junto a su resumen de texto, y el host (Claude Desktop, Claude.ai, VS Code Copilot, Cursor) lo muestra en línea en la conversación. El modelo mantiene el texto compacto para razonar. El usuario obtiene una interfaz interactiva en tiempo real justo al lado del chat.

Tres propiedades hacen que esta sea una integración diferente de "un webhook que devuelve una URL":

• Preservación del contexto. La UI reside dentro de la conversación. Sin cambiar de pestaña, sin traspasos.
• Flujo de datos bidireccional. La UI puede llamar a las herramientas del servidor MCP para obtener datos nuevos, y el host puede devolver nuevos resultados del agente a la UI. No hay una capa de API independiente ni lógica de autenticación adicional.
• Límite de confianza en un entorno de prueba. Las MCP Apps se ejecutan en un iframe controlado por el host. No pueden acceder a la página principal, leer cookies ni salir de su contenedor.

Las operaciones de seguridad se basan en la clasificación, los grafos de investigación y la detección de ataques, donde un agente de AI correlaciona cientos de alertas en unas pocas cadenas de ataque. Observability significa trazas distribuidas y análisis en profundidad de series temporales. Desarrollar en Kibana significa una cuadrícula de dashboard. Si conviertes todo eso en texto, pierdes lo que lo hace útil. Desarrollamos MCP Apps para las tres áreas y las lanzamos juntas como open source, de modo que la misma conversación pueda pasar de una cola de clasificación a un grafo de dependencias o a un dashboard en tiempo real, sin abandonar nunca el chat.

Cada una de las tres apps de referencia es un servidor MCP que ofrece muchas vistas interactivas, no un conjunto de productos separados. La app de seguridad por sí sola presenta seis dashboards que comparten el mismo contenedor de servidor, el mismo modelo de visibilidad de herramientas y el mismo puente de host. El patrón es pequeño; el área de superficie es donde el valor se acumula.

Elastic Security MCP App

Por qué es importante para el SOC

Cuando un agente le dice a un analista de SOC: “Hay 47 alertas en el host-314, aquí hay un resumen”, no ha hecho ningún trabajo. Simplemente indica dónde comienza el trabajo. El trabajo real se encuentra en la lista de alertas, el árbol de procesos, el grafo de investigación y el archivo del caso. No puedes hacerlo a partir de un párrafo de texto.

La MCP App de seguridad devuelve el flujo de trabajo en sí. El analista consulta al agente, y este devuelve un dashboard interactivo en el chat donde el analista puede profundizar en alertas, ejecutar búsquedas de amenazas, correlacionar cadenas de ataques y abrir casos, todo sin perder el hilo de la conversación. Y debido a que los hallazgos, las consultas y los casos llegan a Elasticsearch, la misma investigación está esperando en Kibana, donde el analista puede retomar una vez que se haya cerrado la conversación.

Seis dashboards interactivos

La Elastic Security MCP App incluye seis elementos interactivos, uno por cada flujo de trabajo principal del SOC. Cada una es una UI de React que se renderiza en línea cuando el agente llama a la herramienta correspondiente:

Cada herramienta devuelve un resumen textual compacto sobre el que el modelo puede razonar, junto con la UI interactiva en la que actúa el analista. La UI también puede obtener datos actualizados en segundo plano a través del puente MCP del host. El modelo completo de la herramienta y la API del puente se encuentran en la documentación de arquitectura del repositorio.

La app también incluye habilidades de Claude Desktop, SKILL.md archivos que enseñan al agente cuándo y cómo usar cada herramienta. Descarga los archivos ZIP de habilidades preconfiguradas desde la última versión.

De la alerta al caso

Cuatro capacidades cubren el ciclo central del SOC. Cada una recibe un mensaje, llama a una herramienta y devuelve un dashboard interactivo junto con un resumen de texto que el modelo analiza. El día de un analista generalmente comienza con una cola de alertas.

Clasificación de alertas. Pídele al agente que clasifique los datos por host, regla, usuario o intervalo de tiempo. Pídele al agente que clasifique los datos por host, regla, usuario o intervalo de tiempo. La habilidad de Clasificación de alertas devuelve un dashboard de veredictos de AI sobre la lista de alertas sin procesar, con un veredicto por regla de detección que clasifica la actividad de esa regla como benigna, sospechosa o maliciosa, cada uno con una puntuación de confianza y una acción recomendada. Haz clic en cualquier alerta para abrir una vista detallada con un árbol de procesos, eventos de red, alertas relacionadas y etiquetas MITRE ATT&CK. No es necesario cambiar de contexto entre la conversación con la AI y tu dashboard dentro de Kibana, todo sucede en tiempo real dentro de tu conversación.

Busca amenazas. Pide al agente que busque en tus índices. La habilidad de Búsqueda de amenazas devuelve un banco de trabajo ES|QL con la búsqueda precompletada y ejecutada automáticamente, con todas las entidades de los resultados en las que se puede hacer clic para profundizar. El modelo escribe una breve lectura debajo de la tabla: qué es inusual, qué está conectado, qué vale la pena observar más de cerca. Luego propone el siguiente paso: profundizar en la investigación de amenazas o iniciar una nueva habilidad dentro de la MCP App que complemente el trabajo realizado hasta el momento. Lo que complementa muy bien esto es iniciar una detección de ataques para recopilar más contexto sobre las alertas que ya has analizado en profundidad y las amenazas que has investigado hasta ahora. Lo que articula muy bien todo esto es lanzar una detección de ataques para obtener más contexto sobre las alertas en las que has profundizado y las amenazas que has explorado hasta el momento.

Ejecuta una detección de ataques. La habilidad de Detección de ataques activa la API de detección de ataques y devuelve una lista clasificada de hallazgos. Cada hallazgo es un conjunto de alertas relacionadas que se unen en una cadena de ataque, en la que se muestran de inmediato las tácticas de MITRE, una puntuación de riesgo, un indicador de confianza y los hosts y usuarios afectados. El resumen del agente se ubica debajo de los hallazgos en el mismo orden de clasificación, y la conversación ahora contiene todo lo necesario para actuar: consultas de búsqueda, decisiones de clasificación, cadenas correlacionadas, todo preparado para el siguiente paso.

Abrir casos sin salir del chat. Aprueba hallazgos en bloque o pide al agente que abra casos para alertas específicas. La habilidad de Gestión de casos crea un caso por hallazgo aprobado (alertas de origen adjuntas, tácticas MITRE heredadas de la cadena de ataque) y muestra la lista de casos en vivo en línea. Haz clic en un caso para ver su vista de detalles, que incluye una fila de botones de acción de AI: Resumir caso, Sugerir próximos pasos, Extraer IOC y Generar cronología. Cada uno devuelve un prompt estructurado al chat, para que el agente capte el contexto del caso sin necesidad de reintroducirlo. El resumen del agente se encuentra debajo de la lista de casos y cubre toda la cola de IR, lo que incluye los casos recién abiertos y hallazgos anteriores que aún necesitan uno.

Cada paso de esta guía ejecuta el mismo ciclo: llega un aviso, la habilidad lo detecta, la herramienta devuelve un resumen de texto compacto para que el modelo razone, junto con una interfaz interactiva sobre la que actúa el analista. Encadena las habilidades y se componen en un flujo integral de SOC: búsqueda, clasificación, correlación, apertura de casos y el impulso del siguiente pivote, todo esto con el modelo preservando el contexto de la sesión en cada paso. Si invocas cualquiera de ellas de forma individual, seguirá siendo el dashboard completo, que apunta a la porción de datos que especifiques. De cualquier manera, el trabajo se acumula dentro de la conversación; sin cambiar de pestaña, sin copiar y pegar, sin transferencias.

Dos habilidades más completan la app: un navegador de reglas de detección para ajustar reglas ruidosas y un generador de datos de muestra para generar eventos ECS realistas contra un cluster nuevo. En una próxima publicación hablaremos en detalle de los seis: el grafo de investigación, el canvas del flujo de ataque y el recorrido paso a paso.

“La Elastic Security MCP App acorta la brecha entre la detección automatizada y la búsqueda manual. Al llevar nuestros datos de seguridad directamente a una única interfaz dentro de Claude Desktop, detectamos amenazas “silenciosas” en menos de una hora, riesgos que no activaban alertas estándar, pero que requerían una acción inmediata. Es un multiplicador de fuerza para nuestros analistas”. Mandy Andress: directora de seguridad de la información (CISO), Elastic.

Cómo funciona

Cada MCP App es un pequeño servidor de Node.js cuyas herramientas devuelven tanto un resumen de texto compacto para el modelo como una UI de React que el host renderiza en línea. Como está basado en la especificación abierta de la MCP App, el mismo servidor se ejecuta en cualquier host compatible; consulta el documento de arquitectura del repositorio para conocer el diseño completo.

Pruébalo

Requiere Elasticsearch 9.x con Security activada, además de Kibana para casos, reglas y descubrimiento de ataques. El camino más rápido es el paquete .mcpb de un solo clic de la última versión. Haz doble clic en Claude Desktop y te pedirán la URL de Elasticsearch y la clave API. Las guías de configuración para Cursor, VS Code, Claude Code, Claude.ai y la compilación desde el código fuente se encuentran en el repositorio.

Elastic Search MCP App: dashboards creados a partir de conversaciones

Cada usuario de Kibana conoce el desvío del dashboard: deja lo que estás trabajando, abre Kibana, elige un índice, elige campos, elige una visualización, retoca y guarda. Son cinco cambios de contexto antes de que aparezca un solo gráfico en pantalla.

La nueva app de referencia example-mcp-dashbuilder lo integra en un prompt. Pídele al agente: “créame un dashboard con métricas de ingresos, tendencias de pedidos y desgloses por categoría” y el dashboard aparece dentro de la conversación, sin necesidad de cambiar de pestaña.

Detrás de ese prompt, el agente explora tus datos de Elasticsearch a través de ES|QL y selecciona tipos de gráficos que coincidan con los datos: barras para comparaciones, líneas para tendencias, tarjetas métricas para KPI y mapas de calor para patrones bidimensionales. Coloca paneles sobre la cuadrícula de 48 columnas de Kibana usando el tema Elastic UI Borealis, y el resultado es totalmente interactivo: puedes arrastrar, redimensionar y agrupar paneles en secciones plegables directamente en el chat. Cuando el dashboard se ve bien, una sola llamada de herramienta lo exporta a Kibana, y preserva las búsquedas ES|QL y los colores personalizados. También puedes importar los paneles de Kibana existentes al chat para la edición asistida por IA.

El principio es el mismo detrás de la app de Security: cuando el artefacto es el producto, devolverlo dentro de la conversación cierra el ciclo entre describir lo que quieres y verlo.

Internamente, sigue el mismo patrón que MCP App. Un servidor Node.js registra una herramienta view_dashboard orientada al modelo junto a un conjunto de herramientas exclusivas para aplicaciones que la UI llama directamente (obtención de datos, persistencia del diseño, detección de campos de tiempo, exportación/importación). La vista del dashboard en sí es un único archivo HTML autocontenido, empaquetado con vite-plugin-singlefile y servido como un recurso de MCP App. Los desarrolladores que hacen un fork del repositorio obtienen el mismo contenedor de servidor y el mismo puente de host que ven en la aplicación Security, pero apuntando a un trabajo diferente. El README de example-mcp-dashbuilder incluye la arquitectura completa y la referencia de tipos de gráficos.

Elastic Observability MCP App

La tercera app de referencia, Elastic Observability MCP App, aborda la versión SRE del mismo problema de forma. Cuando algo falla en producción, lo que necesita el ingeniero de guardia no es un gráfico, sino un diagnóstico construido a partir de métricas de K8s, la topología de APM, anomalías de ML y una evaluación de riesgos. La forma de la respuesta es una narrativa causal: qué falló, por qué, de qué depende y qué hacer a continuación.

Seis herramientas que apoyan el flujo de trabajo de investigación de observabilidad

Agregación del estado del cluster

Haz preguntas como “¿qué está fallando?” o “dame un informe de estado” y obtén una vista de orientación en una sola ejecución: indicador general de salud, servicios degradados con sus causas, principales consumidores de memoria por pod, desglose de la severidad de anomalías y rendimiento de los servicios, todo en una única vista integrada. Este es el punto de partida cuando algo no parece estar bien, pero no sabes dónde buscar. La vista se adapta en función de lo que soporta tu despliegue. APM te ofrece información sobre el estado de los servicios. Las métricas de Kubernetes agregan contexto de pod y nodo. Capa de trabajos de ML en anomalías.

Grafo de dependencia de servicios

Haz preguntas como “¿qué llama a finalizar la compra?” o “muéstrame la topología” y obtén un grafo de dependencias por capas: llamadas upstream, dependencias downstream, protocolos, volumen de llamadas y latencia por cada enlace. Pidámosle a Claude que “me muestre las dependencias de servicio del frontend”:

Haz zoom, desplázate y pasa el cursor por encima para ver todos los detalles que necesitas para entender las complejas relaciones entre los servicios:

Evaluar el riesgo con un radio de impacto

Haz preguntas como “¿qué pasa si se cae mi nodo de K8s?” y obtén un diagrama radial de impacto: el nodo objetivo en el centro, los despliegues con interrupción total en rojo, los degradados en ámbar y los no afectados en gris. Una tarjeta de resumen flotante muestra los pods en riesgo y la viabilidad de su reprogramación. Los despliegues de una sola réplica se señalan como puntos únicos de falla. 

Observe

La primitiva de acceso principal del agente para Elastic: una sola herramienta, tres modos para tres necesidades distintas. Di “¿qué está pasando con la CPU ahora mismo?” y ejecuta una consulta ES|QL una vez y devuelve una tabla. Di “muéstrame la latencia del frontend durante los próximos 60 segundos” y toma muestras en vivo de la métrica, actualizando el gráfico en el momento. Di “avísame cuando la memoria baje de 80 MB” o “vigila cualquier anomalía durante los próximos 10 minutos” y bloquea la ejecución hasta que se cumpla la condición o expire la ventana. La vista se adapta al modo: una tabla de resultados para búsquedas puntuales, un gráfico de tendencia en vivo con estadísticas actuales/pico/línea base para el muestreo y condiciones de umbral, y una tarjeta de activación con severidad para el modo de anomalías.

Cómo funciona

El mismo patrón de MCP App que las apps de Security y Search: un servidor Node.js y seis herramientas orientadas al modelo conectadas a seis recursos de vista en archivos individuales. Las herramientas se agrupan según el backend de despliegue (universal, dependiente de APM, dependiente de K8s, dependiente de ML), de modo que tanto el agente como el usuario saben desde el inicio qué herramientas aplican a un despliegue determinado, en lugar de descubrir limitaciones de capacidad en el momento de la ejecución. MCP App también incluye un flujo de trabajo de ejemplo de Agent Builder: k8s-crashloop-investigation-otel, que puede activarse ante una alerta de Kubernetes y devolver un resumen estructurado de la causa raíz antes de que hayas abierto un solo panel.

El stack agéntico, interactivo

Hay tres propiedades de este patrón que vale la pena mencionar directamente. Primero, el resultado de la herramienta ya no es el final del trabajo, es el comienzo de este: la conversación devuelve una interfaz en la que puedes actuar, no un resumen desde el que tienes que actuar. Segundo, el mismo agente, el mismo contexto de modelo y el mismo hilo de conversación ahora pueden moverse entre las superficies de Security, Search y Observability sin abandonar la conversación. En tercer lugar, esto solo funciona porque Elasticsearch y Kibana ya ofrecen las API. La MCP App es una capa interactiva delgada sobre las capacidades del producto que ya enviamos.

Attack Discovery ya potencia la vista de hallazgos correlacionados dentro de esta app. Dentro del stack, el mismo patrón agente va más allá: Elastic Workflows automatiza los pasos deterministas (enriquecer entidades, crear casos, aislar hosts), mientras que Agent Builder razona sobre los datos e invoca esos flujos de trabajo como herramientas. La MCP App trae esa misma superficie de seguridad a la conversación externa; Workflows y Agent Builder la profundizan dentro del stack. Diferentes puntos de acceso, pero las mismas API de Elastic.

Pruébalo:

• Security: example-mcp-app-security
• Search y dashboards: example-mcp-dashbuilder
• Observability: example-mcp-observability

¿Aún no tienes un cluster de Elasticsearch? Comienza una prueba gratuita de Elastic Cloud. Para obtener más información sobre los componentes básicos detrás de la app de seguridad, consulta las publicaciones relacionadas de Security Labs en Elastic Workflows y Agent Builder, Habilidades de agentes y Detección de ataques.

Hoy, esa historia se vuelve mucho más sencilla. Ahora puedes usar las claves de API de Elastic Cloud para autenticarte directamente contra las API de Elasticsearch y Kibana en Elastic Cloud Serverless. Ahora puedes usar una sola credencial para gestionar los recursos de tu organización y ejecutar operaciones de datos, como consultas de ES|QL (lenguaje de búsqueda de Elasticsearch), ingesta de datos y generación de alertas.

Veamos por qué lo creamos, cómo diseñamos una capa de identidad distribuida en todo el mundo para hacerlo posible y cómo sienta las bases para la búsqueda entre proyectos.

La carga secreta de la gestión

Construir pipelines fiables de CI/CD, flujos de trabajo de GitOps o automatización de Terraform alrededor de plataformas de datos conlleva un costo oculto: la proliferación de secretos.

En el modelo anterior, los desarrolladores se enfrentaban a un proceso de autenticación fragmentado:

• Plano de control (claves de la API de Elastic Cloud): Claves con ámbito de organización que se emplean para crear proyectos, invitar a usuarios y gestionar la facturación a través de la API de Elastic Cloud.
• Plano de datos (claves de la API de Elasticsearch): Claves con alcance de proyecto creadas dentro de un proyecto Serverless específico para interactuar con las API de Elasticsearch y Kibana.

Esto significaba que tu script de despliegue tenía que autenticarse en Elastic Cloud, aprovisionar un proyecto Serverless, extraer una clave de API de Elasticsearch recién creada de ese proyecto específico y luego inyectar esa segunda clave en la aplicación o herramienta de automatización downstream, lo que resultaba en pipelines complejos, logs de auditoría fragmentados y un mayor riesgo de fugas de credenciales.

Autenticación unificada en Elastic Cloud Serverless

Con este lanzamiento, la división ha desaparecido para los proyectos Serverless. Ahora puedes crear una clave de la API de Elastic Cloud que esté explícitamente autorizada para las API de Cloud, Elasticsearch y Kibana.

• Antes: Una clave de API de Elastic Cloud era estrictamente un token del plano de control. Podía crear proyectos, gestionar la facturación e invitar a usuarios, pero tenía una limitación importante: no se podía usar para llamar a las API de Elasticsearch o Kibana dentro de esos proyectos. Siempre necesitabas una segunda clave específica del proyecto para las operaciones con datos.
• Ahora: Al optar por el acceso a la API de Cloud, Elasticsearch y Kibana cuando creas una clave de la API de Elastic Cloud, se elimina el límite rígido para Serverless. Esa clave de la API se convierte en una credencial verdaderamente unificada. Mantiene su capacidad para gestionar la infraestructura de tu organización, mientras obtiene acceso nativo para consultar, ingerir y analizar datos en cualquier proyecto Serverless autorizado.

Al unificarlo bajo una única clave de API de Elastic Cloud, obtienes una única identidad que puede ser delimitada, sometida a auditoría, rotada y revocada como una sola unidad. Cada llamada a la API, ya sea que aprovisione un nuevo proyecto o ejecute un ES|QL, aparece bajo la misma credencial en tus logs de auditoría, dándote un único rastro a seguir durante investigaciones de incidentes o revisiones de cumplimiento. La rotación de credenciales se convierte en una operación de un solo paso en lugar de una actualización coordinada a través de secretos separados del plano de control y del plano de datos. Y dado que las asignaciones de roles son por proyecto, una única clave puede abarcar varios proyectos, gestionando la ingesta en tu proyecto de observabilidad y ejecutando consultas en tu proyecto de seguridad, sin tener que gestionar credenciales separadas para cada uno.

Es importante destacar que unificado no significa todopoderoso. Al usar la carga útil role_assignments, puedes asignar una clave unificada estrictamente a un solo proyecto y a un rol específico (como solo lectura), cerciorando que el radio de alcance permanezca completamente contenido si alguna vez se expone una credencial. Si un desarrollador se marcha o una aplicación es desactivada, puedes revocar una sola clave de la Consola de Elastic Cloud, terminando inmediatamente el acceso tanto en el plano de control como en todos los proyectos asociados de Elasticsearch.

(Nota: Para despliegues gestionados/alojados en Elastic Cloud Hosted, las claves de API de la cloud siguen gestionando solo el plano de control. La función para extenderlo a las API de pila alojadas está previsto para una versión futura).

Automatiza tus flujos de trabajo

Los primeros pasos son simples. Puedes configurarlo completamente a través de la consola de Elastic Cloud o automatizarlo empleando la API de Elastic Cloud.

El proceso de la UI sigue igual, pero ahora puedes seleccionar acceso a la API de Cloud, Elasticsearch y Kibana bajo la asignación de rol del proyecto.

Aquí te mostramos cómo crear una clave unificada mediante programación empleando la API de Elastic Cloud. Fíjate en el array application_roles, ya que es el que otorga acceso nativo al plano de datos de Elasticsearch:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $EC_API_KEY" \
  "https://api.elastic-cloud.com/api/v1/users/auth/keys" \
  -d '{
    "description": "unified-automation-key",
    "expiration": "90d",
    "role_assignments": {
      "project": {
        "elasticsearch": [
          {
            "role_id": "elasticsearch-admin",
            "organization_id": "YOUR_ORG_ID",
            "all": false,
            "project_ids": ["YOUR_PROJECT_ID"],
            "application_roles": ["admin"]
          }
        ]
      }
    }
  }'

Una vez creada, simplemente pasas esta misma clave en el encabezado Authorization: ApiKey tanto a api.elastic-cloud.com como a tus puntos finales específicos de Serverless Elasticsearch.

Bajo el capó: construyendo una capa de identidad distribuida

Hacer que una clave API de Cloud funcione tanto en el plano de control como en el plano de datos no es tan simple como pasar un token. Implica resolver un reto fundamental de los sistemas distribuidos.

Históricamente, las claves de API de Cloud residían en un clúster de seguridad global centralizado. Esto funciona bien para las operaciones del plano de control donde una latencia más alta es aceptable. Sin embargo, las solicitudes de datos de Elasticsearch requieren una latencia ultrabaja. No podemos permitirnos un viaje de ida y vuelta alrededor del mundo hasta un plano de control central para validar cada consulta de búsqueda o solicitud de ingesta.

Para resolverlo, implementamos una nueva arquitectura de autenticación respaldada por un almacén de datos distribuido a nivel mundial. El siguiente diagrama de secuencia muestra a un cliente enviando una consulta a Elasticsearch con una clave de API de Elastic Cloud, lo que ilustra cómo la autenticación se lleva a cabo íntegramente dentro de la región local, sin necesidad de un viaje de ida y vuelta al plano de control global. Elasticsearch delega la autenticación al servicio regional de IAM, que valida la clave y comprueba las asignaciones de roles en una réplica local de la base de datos distribuida en todo el mundo. Una vez autorizado, Elasticsearch ejecuta la consulta y devuelve los resultados al cliente.

Persistencia distribuida a nivel global

En lugar de depender únicamente de un clúster de seguridad centralizado, las claves de la API de Elastic Cloud y las definiciones de roles asociadas ahora se almacenan permanentemente en una base de datos distribuida en todo el mundo y de alta disponibilidad. Esta base de datos sincroniza los datos de administración de identidad y acceso (IAM) a través del plano de control global y los planos de datos regionales donde realmente se ejecutan tus proyectos sin servidor.

Validación local con IAM regional

Cuando tu cliente envía una solicitud a Elasticsearch usando una clave de API de Elastic Cloud, la solicitud no se remite al plano de control mundial. En su lugar, es redirigido al nuevo servicio regional de IAM. Valida la clave contra la réplica de la base de datos local, asegurando que la autenticación ocurra con una latencia cercana a cero y esté completamente aislada de las interrupciones del plano de control mundial.

Mapping dinámico de roles

La autenticación es solo la mitad del camino; el sistema también tiene que autorizar la solicitud. El servicio regional de IAM traduce instantáneamente tus asignaciones de rol a nivel de cloud (por ejemplo, application_roles) en privilegios nativos de Elasticsearch. Elasticsearch puede entonces autorizar y ejecutar la solicitud localmente, sin necesidad de un índice .security local.

La base para la búsqueda entre proyectos

Esta arquitectura de identidad distribuida es un pilar fundamental para el futuro de la plataforma Elastic.

Como la identidad y el acceso ahora están unificados y sincronizados globalmente, contamos con el marco de trabajo necesario para transferir tu identidad de forma segura entre diferentes proyectos. Esto permite las próximas funcionalidades de búsqueda entre proyectos (CPS) para Serverless.

Con CPS, podrás consultar datos que abarcan varios proyectos serverless remotos, como combinar cargas de trabajo de seguridad y observabilidad, tan fácilmente como si fueran un solo set de datos. Al utilizar claves API unificadas, el sistema puede evaluar automáticamente tus permisos en todos los proyectos a la vez, sin que tengas que configurar relaciones de confianza complejas, certificados ni duplicar credenciales en cada proyecto de destino.

Más información

¿Listo para simplificar tu stack?

• Lee la documentación sobre las claves de la API de Elastic Cloud para saber cómo asignar acceso a la pila.
• Consulta la referencia Crear clave de la API (Elastic Cloud API) para automatizar la generación de claves.
• Consulta las claves de API de Elastic para ver una comparación completa de los tipos de claves disponibles en toda la Platform de Elastic.

Empieza o continúa construyendo en Elastic Cloud hoy mismo.

Descargo de responsabilidad

El lanzamiento y el momento de cualquier característica o funcionalidad descrita en esta publicación quedan a exclusivo criterio de Elastic. Es posible que alguna característica o funcionalidad que no esté disponible en este momento no se lance a tiempo o no se lance en absoluto.

Las organizaciones acumulan grandes colecciones de documentos, como tickets de soporte, presentaciones legales, feeds de noticias y trabajos de investigación, pero para poder hacer las preguntas correctas, primero necesitan entender lo que contienen. Sin etiquetas o datos de entrenamiento, revisar manualmente miles de documentos es poco práctico. La búsqueda tradicional no es útil cuando no sabes qué buscar.

Esta publicación describe un enfoque nativo de Elasticsearch para la agrupación no supervisada de documentos y el seguimiento temporal de temas que aborda este problema de descubrimiento. Después de leerla, podrás seguir la evolución de distintos temas a lo largo de varios días:

Lo que descubrirás:

• Por qué las incrustaciones de agrupación (y no las incrustaciones de recuperación) son fundamentales para descubrir temas sin una consulta.
• Cómo la clasificación de centroides con sonda de densidad agrupa documentos por tema usando Elasticsearch k vecinos más cercanos (kNN) y lotes de msearch.
• ¿Cómo puede significant_text autoetiquetar clústeres para que los temas sean legibles sin entrenar un modelo?
• De qué forma las cadenas temporales de temas conectan los clústeres de datos diarios para mostrar la evolución de los temas día a día.

El pipeline utiliza unos 8500 artículos de febrero de 2025 de BBC News y The Guardian como corpus de prueba. Si bien las noticias son convenientes porque tienen un comportamiento temporal claro, el patrón es aplicable si el descubrimiento de documentos es importante: revisión legal, monitoreo del cumplimiento normativo, síntesis de investigación, triage de atención al cliente.

Stack:

• Jina v5 incrustaciones de agrupación: adaptadores específicos de Low-Rank Adaptation (LoRA) para la agrupación de temas. Jina se unió a Elastic, y sus modelos están disponibles de forma nativa a través del Elastic Inference Service (EIS).
• Elasticsearch: kNN escalable, etiquetado significant_text y almacenamiento de vectores.
• DiskBBQ: un formato de índice vectorial basado en disco que combina Better Binary Quantization (BBQ) con una partición jerárquica k-medios para la aceleración aproximada de los vecinos más cercanos (ANN). Esta partición de índice es interna a la búsqueda vectorial y separada del algoritmo de agrupación con sonda de densidad utilizado en esta publicación. bbq_disk almacena vectores cuantificados en el disco y mantiene solo los metadatos de partición en el heap, lo que reduce drásticamente los requisitos de recursos en comparación con bbq_hnsw, mientras mantiene un alto nivel de recuperación.
• Agrupación global + vinculación temporal diaria: descubrimiento y evolución del tema.

Lo que necesitarás:

• Un despliegue de Elasticsearch (Elastic Cloud, Elasticsearch Serverless o Elastic Self-Managed 8.18+/9.0+): bbq_disk requiere la versión 8.18 o posterior. La sección opcional de recuperación diversificada requiere 9.3+ o sin servidor.
• Una clave de API de Jina: la capa gratuita incluye 10 millones de tokens, lo que cubre la pipeline de agrupación del núcleo (~4.25 millones de tokens). La comparación opcional entre recuperación y agrupación usa una segunda pasada de incrustación.
• Una clave API de Guardian (gratis).

Configuración

Instala los paquetes requeridos:

pip install elasticsearch pandas numpy plotly umap-learn python-dotenv pydantic-settings datasets requests

Opcional (solo si ejecutas los asistentes de raspado desde este repositorio):

pip install beautifulsoup4

Luego configura las claves API en un archivo .env en la raíz del proyecto:

ELASTIC_CLOUD_ID=your-cloud-id        # or ELASTIC_HOST=https://...
ELASTIC_API_KEY=your-api-key
JINA_API_KEY=your-jina-key
GUARDIAN_API_KEY=your-guardian-key

Este cuaderno llama a load_dotenv(override=True), por lo que los valores locales .env tienen prioridad.

Connected to Elasticsearch

Parte 1: agrupación de descubrimiento - ¿Por qué agrupar incrustaciones?

La mayoría de las búsquedas vectoriales usan incrustaciones de recuperación entrenadas para hacer coincidir una consulta con documentos relevantes. Eso es ideal para la búsqueda, pero no para el descubrimiento. Cuando quieras encontrar qué temas existen en un corpus sin ninguna consulta, necesitas incrustaciones que agrupen documentos similares.

Jina v5 resuelve esto con adaptadores de Low-Rank Adaptation (LoRA) específicos para cada tarea. LoRA agrega pequeñas actualizaciones de bajo rango a las capas internas específicas mientras mantiene la mayoría de los pesos del modelo base congelados, por lo que el comportamiento del modelo se desplaza hacia una tarea específica sin repetir el entrenamiento completo. El mismo modelo base produce diferentes incrustaciones según el parámetro task:

El adaptador de agrupación está entrenado para hacer que los documentos sobre el mismo tema estén más cerca en el espacio de incrustaciones y que los documentos sobre temas diferentes estén más separados. La comparación visual a continuación muestra la diferencia de forma concreta.

Recuperación frente a agrupación: una comparación visual

Para ver la diferencia, se incrusta una muestra de documentos con ambos tipos de tareas. La agrupación se realiza en el espacio de incrustación original de 1024 dimensiones; Uniform Manifold Approximation and Projection (UMAP) se usa solo para proyectar esas incrustaciones en 2D para su visualización. UMAP preserva la estructura de vecindad local, por lo cual es útil para comparar la separación entre clústeres.

A continuación, se muestra la misma muestra de 480 documentos con ambos tipos de tareas y proyectada en 2D con UMAP. Busca grupos de colores más compactos y mejor diferenciados en el panel de agrupación.

    Full dataset: 8,495 articles
    Sources: guardian: 5749, bbc: 2746
    Date range: 2025-02-01 to 2025-02-28


    Sample: 480 docs across 8 sections
    section
    Film              60
    World news        60
    Australia news    60
    Opinion           60
    Football          60
    US news           60
    Sport             60
    Business          60


    Clustering embeddings: 480
    Retrieval embeddings:  480


    UMAP projection complete

Las incrustaciones de recuperación (izquierda) distribuyen los temas ampliamente; las incrustaciones de agrupación (derecha) producen grupos más ajustados y separados de los mismos documentos.

Las incrustaciones de agrupación producen grupos más compactos y visualmente más distintivos. Las incrustaciones de recuperación distribuyen los temas de manera más uniforme, ideales para la búsqueda (similitud de grano fino); pero para el descubrimiento, los clústeres temáticos compactos son lo que importa.

Esta es la razón por la que task="clustering" se usa para el resto de este recorrido.

Carga de los sets de datos

El corpus combina dos fuentes de noticias para febrero de 2025:

• BBC News a través del set de datos RealTimeData/BBC_News_AllTime HuggingFace.
• The Guardian a través de la API de Guardian Open Platform.

Tener varias fuentes permite validar que la agrupación encuentra temas en lugar de estilo específico de la fuente.

    Total articles:  8,495
    
    Source breakdown:
    source
    guardian    5749
    bbc         2746
    
    Date range: 2025-02-01 → 2025-02-28
    Days covered: 28
    
    Sample article:
      Source:  guardian
      Title:   Carbon monoxide poisoning ruled out in death of Gene Hackman and wife, police sa
      Section: Film
      Text:    Authorities have ruled out that Gene Hackman and his wife, Betsy Arakawa, died from carbon monoxide poisoning earlier this week in their home in Santa Fe, New Mexico. The Santa Fe county sheriff, Adan...

Incrustar con la tarea de agrupación

La API de Jina v5 se llama con task="clustering" para todos los documentos. Las incrustaciones se almacenan en caché en disco, por lo que las ejecuciones posteriores se saltan la API por completo.

La llamada a la API es muy sencilla. El parámetro task es la diferencia clave con respecto al uso típico de incrustación:

payload = {
    "model": "jina-embeddings-v5-text-small",
    "input": texts,
    "task": "clustering",  # ← This selects the clustering LoRA adapter
}

El tiempo que se muestra a continuación refleja un acierto de caché. La primera ejecución contra la API lleva más tiempo, según el tamaño del corpus.

    Embeddings ready: 8,495 vectors of dimension 1024
    Time: 0.6s

Indexar un índice único de Elasticsearch

Para la agrupación por descubrimiento, el mes completo se destina a un índice (docs-clustering-all). La partición diaria se realiza más tarde para la vinculación temporal de temas.

El mapeo de índices emplea bbq_disk para el campo vectorial:

{
  "embedding": {
    "type": "dense_vector",
    "dims": 1024,
    "index": true,
    "similarity": "cosine",
    "index_options": {
      "type": "bbq_disk"        // hierarchical k-means partitioning for ANN index lookup; separate from this post's clustering algorithm
    }
  }
}

Un vector float32 de 1024 dimensiones es de 4 KB. bbq_disk usa k-medios jerárquicos para particionar vectores en pequeños clústeres, los cuantifica en binario y almacena los vectores de precisión completa en el disco para volver a guardarlos. Solo los metadatos de partición permanecen en el heap, por lo que los requisitos de memoria permanecen bajos incluso para corpus grandes. Para las cargas de trabajo que pueden permitirse más memoria dinámica, bbq_hnsw crea un grafo HNSW (Hierarchical Navigable Small World) para agilizar las búsquedas, aunque a costa de un mayor consumo de recursos.

El tipo de campo dense_vector brinda soporte para múltiples estrategias de cuantización: bbq_disk y bbq_hnsw son las más adecuadas para embeddings de alta dimensión, como los vectores de 1024 dimensiones usados aquí.

    Indexed 8,495 documents into docs-clustering-all
    Time: 57.5s

Agrupación: clasificación del centroide sondeada por densidad

Los algoritmos de agrupación tradicionales como HDBSCAN asumen que puedes mantener la matriz de vectores N × d completa en memoria y ejecutar actualizaciones de pasada completa repetidas. Para 8495 documentos con 1024 dimensiones, esto es manejable (~35 MB), pero el enfoque no escala a millones de documentos sin infraestructura adicional.

Este algoritmo es conceptualmente similar a la inicialización de KMedios++ con asignación de Voronoi y un nivel de ruido, pero emplea la búsqueda kNN de Elasticsearch como primitiva de cálculo, manteniendo casi todo el trabajo en el servidor:

1. Muestrea el 5 % de los documentos como sondas de densidad (muestra aleatoria, mínimo 50).
2. Densidad de sondas vía lotes de msearch kNN. Cada sonda dispara una búsqueda kNN y registra la similitud media de sus vecinos. Alta similitud media = región densa del espacio de incrustación. msearch envía múltiples solicitudes de búsqueda en una sola llamada HTTP, lo cual es fundamental en este caso: el sondeo de densidad genera cientos de consultas kNN, y agruparlas evita la sobrecarga por solicitud.
3. Seleccione semillas de alta densidad con diversificación: los candidatos por encima de la densidad mediana se ordenan por densidad descendente y se aceptan de manera ávida solo cuando su similitud del coseno con cada semilla existente está por debajo de un umbral de separación. Este es el único cómputo del lado del cliente (~0.01s para 8k docs).
4. Clasifica todos los documentos frente a los centroides mediante msearch kNN: cada semilla actúa como un centroide; una búsqueda kNN recupera documentos cercanos por encima de un umbral de similitud. Cada documento se asigna al centroide que lo devolvió con la puntuación más alta. Los clústeres pequeños se disuelven en ruido.

Elasticsearch se encarga del trabajo pesado: msearch para sondas de densidad, msearch para clasificación y significant_text para etiquetado. Para este corpus (8495 documentos), la muestra del 5 % de sondeo de densidad lanza 425 consultas kNN de sondeo, que msearch agrupa en nueve llamadas HTTP (con lotes de 50), lo que evita la sobrecarga de una solicitud por sondeo. Combinado con la búsqueda ANN de bbq_disk, esto mantiene la etapa de agrupación rápida y escalable. Las consultas kNN usan un valor mínimo de num_candidates para mayor velocidad durante la pasada de agrupación; las consultas de búsqueda de producción deben usar valores más altos de num_candidates para mejorar la recuperación a costa de la latencia.

Los clústeres tienen tamaños naturales determinados por la densidad del espacio de incrustación alrededor de cada centroide, no por un límite rígido de k. Las regiones temáticas densas producen clústeres más grandes; los temas de nicho producen clústeres más pequeños.

¿Por qué no KMeans o HDBSCAN?

KMedios asume clústeres esféricos y requiere la matriz N×d completa en memoria. Para corpus que caben en memoria, HDBSCAN es una alternativa estable. Maneja formas arbitrarias de clústeres y tiene una semántica de densidad bien entendida.

El enfoque de centroides con sondeo de densidad apunta a un nicho diferente: corpus con almacenamiento, recuperación y agrupación en un solo sistema, o en los que la escala hace que las operaciones matriciales del lado del cliente sean poco prácticas. Usa Elasticsearch kNN como primitiva de cómputo, maneja tamaños de clúster arbitrarios y mantiene casi todo el procesamiento del lado del servidor.

    Clustered global index in 31.6s
      Total clusters: 82
      Total noise:    2420 (28.5%)
      Density probes: 425 kNN queries via 9 _msearch HTTP calls

Comprender la tasa de ruido

La tasa de ruido de ~28 % es intencional, no un modo de falla. Los documentos que no encajan en ningún clúster denso en el similarity_threshold configurado quedan sin asignar en vez de ser forzados a una coincidencia deficiente. Esto actúa como un control de calidad: las columnas de opinión, los artículos cortos y las historias aisladas resisten naturalmente la acción de agrupar porque carecen de la densidad temática que define un grupo coherente.

El umbral es ajustable: reducir similarity_threshold produce una agrupación más agresiva (más documentos asignados, pero clústeres más dispersos), mientras que aumentarlo ajusta los clústeres e incrementa la fracción de ruido. Para este corpus de contenido de noticias mixtas, ~30 % de ruido es un punto de operación razonable. Los despliegues de producción deben ajustar el umbral según criterios de calidad específicos del dominio.

Etiquetas automáticas con significant_text

Ahora cada clúster necesita una etiqueta legible para humanos. La agregación significant_text de Elasticsearch encuentra términos que aparecen inusualmente a menudo en un conjunto en primer plano (el clúster) en comparación con un conjunto de fondo (el corpus completo).

En el fondo, utiliza una heurística estadística (puntuación JLH de forma predeterminada) que equilibra los cambios de frecuencia absoluta y relativa, sin machine learning, sin llamadas a modelos de lenguaje grandes (LLM). Un clúster sobre política del Reino Unido podría mostrar términos como starmer, labour, downing porque esos términos son desproporcionadamente comunes en ese clúster en comparación con el corpus de noticias general.

Para esta pasada global, las etiquetas se calculan directamente con respecto a docs-clustering-all, por lo que tanto el primer plano como el fondo se extraen del mes completo. En la parte 2, el etiquetado usa el patrón de índice diario (docs-clustering-*), un comodín que permite que las búsquedas abarquen todos los índices coincidentes simultáneamente, para darle a significant_text un fondo más amplio y lograr un mejor contraste.

Una forma mínima de consulta se ve así:

{
  "size": 0,
  "query": { "term": { "cluster_id": "72" } },
  "aggs": {
    "label_terms": {
      "significant_text": {
        "field": "text",
        "size": 5,
        "filter_duplicate_text": true
      }
    }
  }
}

significant_text también sirve como control de calidad: los clústeres que no producen términos importantes no tienen vocabulario distintivo. Son agrupaciones incoherentes que deberían disolverse de nuevo en ruido en lugar de recibir una etiqueta engañosa.

Un paso de limpieza determinista y ligero elimina los términos de etiqueta ruidosos (tokens numéricos, palabras genéricas) y recurre a un titular representativo cuando es necesario. Esto mantiene las etiquetas nativas de Elasticsearch y, al mismo tiempo, mejora la legibilidad.

    Sample cluster labels:
      cluster   3  (200 docs)  arsenal | mikel | villa
      cluster   1  (198 docs)  volodymyr | ukrainian | kyiv
      cluster   0  (196 docs)  hostages | hamas | israeli
      cluster   4  (187 docs)  scrum | rugby | borthwick
      cluster  52  (185 docs)  fossil | renewable | renewables
      cluster  10  (156 docs)  labour | gwynne | mps
      cluster  40  (151 docs)  novel | novels | literary
      cluster  11  (149 docs)  mewis | sarina | wiegman
      cluster  44  (143 docs)  flooding | rainfall | rain
      cluster  13  (131 docs)  doge | musk | elon
      cluster  12  (128 docs)  murder | insp | knockholt
      cluster   5  (124 docs)  putin | backstop | starmer


    Reassigned 35 docs from incoherent clusters to noise
    Total docs: 8,495
    Clustered:  6,040 (71.1%)
    Noise:      2,455 (28.9%)

Visualizar los clústeres

Las visualizaciones a continuación muestran lo que descubrió la pasada global de agrupación: un desglose por fecha de los documentos agrupados frente a los documentos de ruido, una proyección UMAP del mes completo y un gráfico de combinación de fuentes que confirma que los clústeres reflejan temas en lugar de fuentes.

Distribución diaria de documentos agrupados frente a documentos de ruido a lo largo de febrero de 2025.

Cada isla coloreada en el UMAP representa un clúster: un grupo de artículos sobre el mismo tema descubiertos únicamente a partir de la similitud de incrustación. Los puntos de ruido gris son artículos que no encajaban perfectamente en ningún clúster (a menudo artículos cortos, artículos de opinión o historias únicas).

El gráfico de desglose de fuentes confirma que los clústeres contienen artículos de ambas BBC News y The Guardian. La agrupación está encontrando temas, no fuentes: exactamente lo que el descubrimiento no supervisado debería arrojar.

Explorar la amplitud del clúster con el recuperador diversificado

El kNN simple devuelve los documentos más similares al centroide de un clúster (el núcleo compacto). Pero los clústeres reales cubren subtemas. El recuperador diversificado utiliza Maximal Marginal Relevance (MMR) para mostrar documentos que son relevantes para el centroide pero también diferentes entre sí.

El parámetro clave es λ (lambda):

• λ = 1.0 → pura relevancia (igual que kNN simple).
• λ = 0.0 → diversidad pura (resultados de máxima distribución).
• λ = 0.5 → equilibrado: es relevante para el tema, pero cubre diferentes ángulos.

Una solicitud mínima de recuperador tiene el siguiente aspecto:

{
  "size": 8,
  "retriever": {
    "diversify": {
      "type": "mmr",
      "field": "embedding",
      "lambda": 0.5,
      "query_vector": "",
      "retriever": {
        "knn": {
          "field": "embedding",
          "query_vector": "",
          "k": 50,
          "num_candidates": 100
        }
      }
    }
  }
}

Los parámetros type, field y query_vector son necesarios a nivel de diversificación: field indica al MMR qué campo dense_vector usar para la similitud entre resultados, y query_vector proporciona el punto de referencia para el puntaje de relevancia.

Esto te permite responder: “¿Qué abarca realmente este clúster?” en vez de solo “¿Qué hay en su centro?”

    Exploring cluster 52 (185 docs)
    Label: fossil | renewable | renewables
    Centroid computed (dim=1024)


    ========================================================================
    Plain kNN (closest to centroid)
    ========================================================================
      1. [0.9738] Green campaigners fear ministers are poised to award billions of pounds in fresh subsidies to Drax power station, despite strong concerns...
      2. [0.9710] Thirteen more oil and gas licences could be cancelled as ministers decide new guidance for fossil fuel extraction after a landmark court...
      3. [0.9699] Experts have accused the fossil fuel industry of seeking special treatment after lobbyists argued greenhouse gas emissions from oilfields...
      4. [0.9681] Burning wood is a terrible way of producing electricity . Chopping down trees destroys habitats for wildlife, and growing new trees cannot...
      5. [0.9649] Keir Starmer will do huge damage to the global fight against climate change if he gives in to political pressure and allows the development...
      6. [0.9641] Labour will next week be confronted with stark policy choices that threaten to expose the fault lines between the Treasury and the...
      7. [0.9638] The Drax power station near Selby in north Yorkshire burns imported wood pellets  The government has agreed a new funding arrangement with...
      8. [0.9581] If you care about the world we are handing on to future generations, the news on Thursday morning was dramatic. This January was the...
    
    ========================================================================
    Diversify retriever (MMR, lambda=0.5)
    ========================================================================
      1. [0.9738] Green campaigners fear ministers are poised to award billions of pounds in fresh subsidies to Drax power station, despite strong concerns...
      2. [0.9434] Oil and gas interests have waged a coordinated campaign to kill pro-electrification policies that ban gas connections in new buildings ,...
      3. [0.9303] It was interesting to read that new licences for oil and gas production in the North Sea are being delayed by legal action ( Thirteen more...
      4. [0.9139] The US energy secretary, Chris Wright, has said he “would love to see Australia get in the game of supplying uranium and maybe going down...
      5. [0.9077] Rachel Reeves was facing criticism on Saturday night as it was confirmed that a report she cited as evidence that a third ­runway at...
      6. [0.8996] When Margaret Thatcher opened the Hadley Centre for Climate Change in 1990 journalists suggested she was attempting to appear to be doing...
      7. [0.8993] The vast majority of governments are likely to miss a looming deadline to file vital plans that will determine whether or not the world has...
      8. [0.8987] European imports of seaborne gas shipments fell by a fifth last year to their lowest level since the pandemic, according to a new report,...
    
    Overlap: 1/8 documents appear in both result sets
    
    Avg pairwise similarity (lower = more diverse):
      Plain kNN:          0.9057
      Diversify retriever: 0.6965

Los resultados simples de kNN se agrupan en torno a un ángulo del tema: los documentos más similares al centroide y entre sí. El recuperador diversificado muestra diferentes facetas del mismo clúster: subtemas, fuentes diferentes y perspectivas variadas.

La métrica de diversidad confirma esto cuantitativamente: la similitud promedio por pares es menor en los resultados del recuperador diversificado, lo que significa que los documentos arrojados tienen mayor alcance.

Esto es útil para:

• Comprender el alcance real de un clúster: no solo su centro, sino también sus bordes.
• Generar resúmenes. Los documentos diversos y representativos le dan a un LLM mejor material.
• Encontrar ejemplos representativos para revisión humana o etiquetado posterior.
• Controles de calidad. Si los diversos resultados parecen incoherentes, es posible que el clúster deba dividirse.

Parte 2: cadenas temáticas temporales

Seguimiento de temas con el paso de los días

La parte 1 agrupó todo el mes a nivel global para el descubrimiento de temas. Para el flujo temporal, la misma clasificación de centroides con sonda de densidad se ejecuta independientemente por día en los índices diarios, y luego los clústeres se vinculan en días adyacentes. Tenga en cuenta que los clústeres diarios son independientes de los clústeres globales de la parte 1; cada día produce sus propias asignaciones y etiquetas de clúster ajustadas al contenido de ese día.

El enfoque de enlazado: muestra y consulta

Para cada clúster el día A:

1. Muestra algunos documentos representativos.
2. Ejecuta kNN contra el índice del día B.
3. Cuenta cuántas coincidencias se registran en cada clúster del día B.
4. Si la fracción de aciertos excede un umbral (fracción kNN ≥ 0.4), registra un enlace.

Esto es rápido (solo se consultan unos pocos documentos por clúster, no todos) y usa el kNN nativo de Elasticsearch, sin necesidad de herramientas externas.

Preparing daily indices for temporal linkage...


Indexed 8,495 docs into 28 daily indices


Temporal links found: 808 in 145.4s

Strongest links:
  2025.02.01 'league | arsenal | premier' -> 2025.02.02 'league | season | striker'  (100%)
  2025.02.03 'league | striker | loan' -> 2025.02.04 'league | striker | season'  (100%)
  2025.02.03 'score | operator | gedling' -> 2025.02.04 'league | striker | season'  (100%)
  2025.02.12 'playoff | leg | bayern' -> 2025.02.13 'league | players | injury'  (100%)
  2025.02.14 'league | injury | football' -> 2025.02.15 'league | premier | football'  (100%)
  2025.02.18 'russia | ukraine | talks' -> 2025.02.19 'saudi | russia | arabia'  (100%)
  2025.02.18 'football | league | bayern' -> 2025.02.19 'league | manchester | players'  (100%)
  2025.02.21 'league | premier | manchester' -> 2025.02.22 'game | players | defeat'  (100%)
  2025.02.21 'rugby | calcutta | brilliant' -> 2025.02.22 'game | players | defeat'  (100%)
  2025.02.26 'metals | kyiv | ukrainian' -> 2025.02.27 'ukraine | russia | talks'  (100%)

Una fracción kNN del 100 % significa que cada documento muestreado del clúster de origen llegó al mismo clúster de destino, el vínculo entre días más fuerte posible. La mayoría de los vínculos anteriores están relacionados con el fútbol, lo que tiene sentido: la cobertura de la Premier League se ejecuta a diario con alta consistencia temática.

El enlace score | operator | gedling → league | striker | season es un ejemplo de un clúster de fútbol local de nicho (Gedling es un club de liga no profesional) que se integra en el clúster más amplio de la Premier League al día siguiente, una consecuencia natural de la reagrupación diaria a diferentes niveles de granularidad.

Construyendo cadenas de historias

Una cadena de temas es una secuencia de agrupaciones vinculadas en días consecutivos.

Los enlaces individuales por pares indican que el clúster "Política del Reino Unido" del lunes se conecta con el del martes. Las cadenas revelan la evolución completa: una historia que comienza el lunes, evoluciona a lo largo de la semana y se desvanece el viernes.

Las cadenas se construyen de forma voraz a partir de enlaces con una fracción kNN ≥ 0.4, lo que significa que al menos el 40 % de los documentos muestreados del clúster de origen terminaron en un único clúster de destino. Comenzando desde el clúster más antiguo, el algoritmo siempre sigue el enlace saliente más fuerte.

    Strong links (kNN fraction >= 0.4): 244
    Story chains spanning 3+ days: 18
      Chain 1: 'ukrainian | kyiv | eastern' (19 days: Feb 3 → Feb 21)
      Chain 2: 'playing | opposition' (19 days: Feb 10 → Feb 28)
      Chain 3: 'tadhg | maro | cadan' (10 days: Feb 1 → Feb 10)
      Chain 4: 'invade | china | putin' (8 days: Feb 21 → Feb 28)
      Chain 5: 'elected | labour | leader' (7 days: Feb 12 → Feb 18)
      Chain 6: 'film | swift | awards' (6 days: Feb 2 → Feb 7)
      Chain 7: 'amendment | termination | reporting' (6 days: Feb 12 → Feb 17)
      Chain 8: 'officers | scene | police' (5 days: Feb 1 → Feb 5)

La cadena más larga rastrea la cobertura Ucrania-Rusia durante 19 días consecutivos, lo cual no es sorprendente dado el sostenido nivel de intensidad geopolítica en febrero de 2025. El segundo más largo sigue al fútbol de la Premier League durante 19 días del mes. Las cadenas más cortas capturan la temporada de premios (cine/premios, seis días), el rugby de las Seis Naciones (10 días) y la cobertura del liderazgo político del Reino Unido (siete días). Cada cadena representa una evolución temática que el algoritmo descubrió puramente a partir de la similitud de incrustaciones a través de índices diarios.

Sankey: visualizando el flujo de la historia

Un diagrama de Sankey es una visualización de un flujo en la que el grosor de los enlaces indica la intensidad de la conexión. Aquí, cada banda vertical es un día, cada nodo es un clúster diario (dimensionado por el recuento de documentos) y cada ruta de color traza una cadena de temas a lo largo del tiempo. El ancho del enlace codifica la fuerza de superposición de kNN: los enlaces más gruesos significan que más documentos muestreados llegaron al clúster de destino. Los colores son consistentes por cadena, así que una sola ruta de color de izquierda a derecha se lee como la progresión de un tema.

Por ejemplo, la cadena Ucrania-Rusia (que se ve como una de las rutas más largas) fluye de manera continua desde principios de febrero hasta la tercera semana, con enlaces que se mantienen gruesos, lo que indica una fuerte continuidad temática a lo largo de los días.

Cadenas temporales de temas que se desarrollan a lo largo de febrero de 2025. Cada camino coloreado es un tema que persiste a lo largo de los días; el ancho del enlace indica la fuerza de superposición kNN.

Qué ofrece este enfoque

Esta guía cubrió una pipeline completa de agrupación de documentos sin supervisión desarrollada sobre Elasticsearch:

1. Agrupar incrustaciones: los adaptadores específicos de la tarea de Jina v5 producen incrustaciones optimizadas para la agrupación por temas, no solo para la coincidencia entre consulta y documento.
2. Agrupación de descubrimiento global: agrupar el mes completo en un índice maximiza el descubrimiento de temas entre días.
3. Clasificación de centroides con densidad probada: muestrea el 5 %, sondea densidad vía msearch kNN, selecciona semillas diversas de alta densidad, clasifica todos los documentos contra los centroides. Elasticsearch maneja el cómputo pesado; solo la selección de semillas se ejecuta del lado del cliente (~0.01 s).
4. significant_text etiquetado: las pruebas de significancia producen etiquetas de clúster significativas sin ningún modelo de ML o anotación manual. Los clústeres que no producen términos significativos son incoherentes y se degradan a ruido: una barrera de calidad integrada.
5. Vinculación temporal de temas: los índices diarios y el rastreo de muestras y consultas de kNN entre índices permiten rastrear cómo evolucionan los temas a lo largo del tiempo.

Conclusiones clave:

• El tipo de tarea de incrustación es importante: las incrustaciones de agrupación producen grupos temáticos notablemente más compactos.
• Elasticsearch puede funcionar tanto como capa de almacenamiento como motor de agrupación mediante búsqueda kNN.
• La clasificación de centroides con sonda de densidad mantiene casi todos los datos del lado del servidor y produce clústeres con tamaños naturales determinados por la densidad de espacio de incrustaciones.
• significant_text es rápido, interpretable y efectivo tanto para el etiquetado automático como para el control de calidad.

Este enfoque es útil en los siguientes casos:

• Tienes texto con fecha y quieres descubrir un tema sin datos de entrenamiento etiquetados.
• Deseas una pila para almacenamiento, búsqueda de vectores, etiquetado y vinculación temporal.

Extensiones para explorar:

• Agrupación de varios períodos (resúmenes semanales y mensuales).
• Ingesta en tiempo real con asignación incremental de clúster.
• Resúmenes de clústeres generados por LLM usando los términos de significant_text como semillas.
• A mayor escala, los centroides de K-Medios obtenidos mediante muestreo pueden servir como semillas de inicio rápido para la agrupación basada en densidad, lo que reduce el costo de la fase de exploración.

Pruébalo tú mismo

Sustituye el corpus de documentos con marcas de tiempo por el tuyo; cualquier colección de texto con fechas funciona con este pipeline. El cuaderno completo y el código de soporte están disponibles en el repositorio complementario.

• Activa una prueba gratuita de Elastic Cloud: crea un clúster administrado con soporte para bbq_disk en cuestión de minutos.
• Prueba Elasticsearch Serverless: sin gestión de clústeres, escala automáticamente y brinda soporte para todo en este tutorial.

La recuperación léxica (coincidencia de texto), la recuperación semántica (coincidencia de conceptos) ni la recuperación híbrida (combinación de señales léxicas y semánticas) resuelven estos problemas por sí solas. La recuperación léxica puede arrojar cualquier resultado que contenga la palabra “naranjas”, mientras que la recuperación semántica pura en una consulta de alta intención como “naranjas” puede ampliarse hacia elementos relacionados como limones o toronjas. La recuperación híbrida combina estas señales léxicas y semánticas, pero aún no determina si esta consulta debe considerarse navegacional, qué restricciones deben aplicarse o qué políticas comerciales deben implementarse. La brecha no es la tecnología de recuperación en sí; es la ausencia de una capa de gobernanza que entienda de qué tipo de consulta se trata y qué restricciones deben implementarse antes de que comience la recuperación.

En este blog, abordamos la gobernanza de la búsqueda en el comercio electrónico, su relevancia y cómo garantizar una recuperación predecible y precisa con una capa de control.

Qué significa la gobernanza en la búsqueda en el comercio electrónico

Gobernanza, en este contexto, significa introducir una capa de decisión entre la consulta del usuario y el motor de recuperación. Esta capa realiza las siguientes funciones:

• Clasifica la intención de la consulta: ¿se trata de navegación ("naranjas") o descubrimiento ("regalo para el abuelo")?
• Aplica restricciones comerciales: ¿qué límites de categoría, reglas de elegibilidad, restricciones de disponibilidad o políticas de comercialización se aplican?
• Apunta hacia la estrategia adecuada: ¿debería usar recuperación léxica, recuperación semántica o híbrida?

Una capa de gobernanza determina qué método de recuperación debe emplearse para cada consulta, qué restricciones deben aplicarse y qué políticas empresariales deben implementarse antes de que comience la recuperación. Es importante no confundir la gobernanza con la recuperación híbrida: la recuperación híbrida es una estrategia que combina señales léxicas y semánticas, mientras que la gobernanza es la capa de decisión previa que determina si deben usarse señales léxicas, semánticas o híbridas.

Situación actual: la implementación "espagueti" de la capa de aplicación

Hoy en día, muchos minoristas intentan resolver esto agregando lógica directamente en la capa de aplicación. A menudo resulta en código espagueti, es decir, miles de líneas de afirmaciones “si-entonces” codificadas de forma rígida, regex y plantillas de búsqueda complejas.

Este enfoque puede proporcionar los resultados de búsqueda deseados como se muestra arriba; sin embargo, crea una fricción operativa significativa:

• Dependencia de ingeniería: los usuarios empresariales y los comercializadores no pueden modificar el comportamiento de búsqueda sin tickets de ingeniería y largos ciclos de despliegue que a menudo abarcan varias semanas.
• Fragmentación: la lógica de búsqueda queda dispersa entre el código de la aplicación y las plantillas de búsqueda, y es difícil de explicar o auditar, lo que vuelve su evolución arriesgada.

Incluso cuando los equipos reconocen la necesidad de enrutamiento, el debate a menudo se centra en la pregunta equivocada: qué método de recuperación elegir.

La falsa elección: léxico vs. semántico vs. híbrido

Los equipos de búsqueda suelen enmarcar el desafío como una elección estratégica de recuperación: léxico/BM25 frente a semántico/vectores frente a híbrido. Ese encuadre es comprensible (los métodos de recuperación importan), pero pasa por alto el modo de fallo más común en despliegues reales: usar un único enfoque de recuperación para todas las consultas dará resultados subóptimos.

La búsqueda comercial es una mezcla de intenciones fundamentalmente diferentes:

• Navegación determinista y de alta intención ("naranjas", "leche", "chocolate sin maní", "aceite de oliva barato").
• Descubrimiento exploratorio ("chaqueta para hacer senderismo en las montañas", "regalo para una niña o niño de 12 años a quien le gusta la robótica").
• Restricciones operativas (disponibilidad, tamaño, precio, color).
• Merchandising y campañas (impulsar, relegar, campañas estacionales).

Cuando el sistema enruta todo esto a través de la misma estrategia de recuperación, los resultados a menudo son sistemáticamente incorrectos de manera predecible porque el modelo operativo carece de gobernanza. Cuando los equipos no se dan cuenta de que esto es una falla en la gobernanza, responden con la única herramienta que tienen: ajustar más el sistema.

Por qué “afinar la relevancia” puede volverse algo cíclico

Sin una capa de enrutamiento, la "relevancia" suele convertirse en una lista de pendientes interminable:

• ¿Por qué esta búsqueda muestra accesorios por encima del producto núcleo?
• ¿Por qué esta búsqueda principal de repente comenzó a mostrar elementos relacionados?
• ¿Por qué cambiaron los resultados después de que agregamos sinónimos, ajustamos los analizadores o habilitamos el híbrido?
• ¿Por qué el equipo de negocios necesita un lanzamiento de ingeniería para arreglar una consulta única?

Los equipos responden con más ajustes: más sinónimos, más mejoras, más experimentos de reordenamiento, más excepciones en el código de la aplicación. Esto puede funcionar por un tiempo, pero a menudo produce un comportamiento frágil porque el sistema aún carece de una capa de decisión explícita para determinar el tipo de consulta y aplicar las restricciones adecuadas antes de la recuperación.

La anatomía de la intención del comercio electrónico: cabeza y cola

En esta sección, usamos “cabeza” y “cola” como una notación práctica para patrones comunes de búsqueda navegacional y exploratoria en el comercio electrónico. En el mundo real, muchas búsquedas contienen aspectos de ambos:

Consultas de cabeza (intención determinista)

Estas son consultas directas y de navegación en las que el usuario sabe exactamente lo que quiere:

• Intención de un solo artículo ("naranjas", "leche", "pan").
• Marcas exactas o familias de productos ("iPhone 15 Pro", "Coca Light").
• Referencias, números de modelo, tallas ("ABC123", "air max 270").

Para estas consultas, la recuperación léxica puede ocuparse de la correspondencia de tokens (palabras coincidentes), pero la empresa también espera respetar las restricciones, arrojar clasificaciones predecibles y tener resultados controlables. Un comerciante necesita asegurarse de que una consulta se resuelva dentro de los límites correctos de la categoría, respete la elegibilidad y muestre prioridades específicas del negocio.

Se necesita una estructura de gobernanza para garantizar el cumplimiento de la resolución prevista. Por ejemplo, las “naranjas” deben mapearse a la categoría de productos, no a jugo de naranja, mermelada de naranja o soda de naranja.

Consultas de cola (descubrimiento exploratorio)

Estas son búsquedas descriptivas y ricas en intención donde los compradores están explorando:

• "Regalo para el abuelo que tiene debilidad por lo dulce"
• "Chaqueta para senderismo en la montaña"
• "Zapatos para estar de pie todo el día"

La recuperación léxica a menudo tiene dificultades en este punto. La búsqueda semántica destaca porque puede conectar el concepto de la consulta con el producto, incluso cuando las palabras no coinciden. Pero la recuperación semántica por sí sola no suele ser suficiente. Las consultas reales a menudo requieren que se apliquen restricciones, independientemente del método de recuperación que se utilice.

Las restricciones son ortogonales al método de recuperación

Aplicar restricciones a la recuperación semántica no significa que sea una búsqueda híbrida. Son conceptos ortogonales. Las restricciones, como los filtros y las mejoras (boosts) en Elasticsearch, se pueden aplicar a cualquier recuperación léxica, semántica o híbrida. El desafío es decidir cómo interpretar la consulta, qué restricciones se deben aplicar y qué estrategia de recuperación se debe usar.

A continuación se muestran algunos ejemplos de consultas que combinan la recuperación con restricciones rígidas:

• Naranjas: recuperación léxica para “naranjas” más una restricción de categoría, como “frutas” o “productos”, eliminando mermelada de naranja, jugo de naranja y soda de naranja.
• Frutas ricas en vitamina C por menos de $4: búsqueda semántica basada en la intención nutricional, además de filtros que limitan los resultados a la categoría de frutas y a productos por menos de $4.
• Zapatos cómodos para el trabajo: búsqueda semántica basada en la intención contextual, además de una restricción de categoría que limita los resultados a los zapatos.

Estas consultas no se pueden manejar con un solo enfoque:

• La recuperación léxica pura a menudo es insuficiente en este caso porque frases como “alto contenido de vitamina C” o “cómodo” pueden no existir como atributos limpios y estructurados. Puede que sea necesario inferirlos a partir de descripciones de productos, reseñas o especificaciones.
• La recuperación semántica pura tampoco es suficiente porque, sin restricciones explícitas, una consulta como “frutas con alto contenido de vitamina C” podría ampliarse hacia suplementos vitamínicos, bebidas con sabor a fruta o vegetales con alto contenido de vitaminas fuera de la categoría y el rango de precios previstos.

Una capa de gobernanza determina si una consulta necesita recuperación léxica, comprensión semántica, aplicación de restricciones o alguna combinación de estas. Sin esta capa, los equipos de comercio electrónico pueden caer en lo siguiente:

• Restricción excesiva: uso de recuperación léxica para solicitudes semánticas (por ejemplo, "regalo para el abuelo").
• Restricción insuficiente: emplear consultas semánticas para consultas de cabeza con alta intención (por ejemplo, "naranjas").

El desafío de la gobernanza es construir un sistema que pueda tomar la decisión correcta para cada clase de consulta.

Qué sucede sin gobernanza

El modo de falla más común es sencillo: los equipos toman la consulta del usuario sin procesar y la pasan directamente a una única estrategia de recuperación (léxica, semántica o híbrida), sin una capa de gobernanza intermedia.

La búsqueda léxica no da el resultado esperado

Cuando un usuario busca “naranjas”, una estrategia de recuperación léxica puede devolver cualquier cosa que contenga ese token: jugo de naranja, mermelada de naranja o soda de naranja. El sistema hizo coincidir el término correctamente, pero sin gobernanza es posible que no resuelva el contexto de compra previsto (la fruta).

La recuperación semántica se amplía más allá de las limitaciones previstas

Cuando un usuario busca “naranjas”, un sistema semántico puede recuperar elementos conceptualmente relacionados a través de conceptos de productos cercanos. El sistema puede comprender correctamente el dominio más amplio (fruta o productos), pero sin gobernanza explícita aún puede ampliarse más allá de la restricción intencionada del usuario (específicamente naranjas).

La brecha es la gobernanza

Lo que se requiere es una capa de decisión previa que determine la intención de la consulta y aplique las restricciones adecuadas antes de que comience la recuperación. Esto soluciona problemas como los siguientes:

• Elementos similares o relacionados que aparecen junto a lo que el usuario realmente quería.
• Límites difusos de categorías ("bebidas" en vez de "frutas").
• Incapacidad para implementar mejoras o campañas estacionales.
• Resultados impredecibles e inexplicables.

Comprensión de intenciones y enrutamiento: el plano de control necesario

Un sistema de búsqueda gestionada incorpora un plano de control ligero antes de la recuperación (antes de ejecutar una consulta en Elasticsearch). El control se explicará en detalle en las partes 3 y 4 de esta serie de blogs; por ahora, solo abarcaremos lo que puede hacer pero no cómo funciona:

Un plano de control puede detectar la intención, aplicar políticas comerciales y garantizar la estrategia de recuperación apropiada de la siguiente manera:

1. Detectar señales de intención

• ¿Es probable que esta búsqueda sea de navegación en vez de descubrimiento?
• ¿Es una búsqueda principal conocida (leche, pan, bananas)?
• Existe una interpretación conocida de producto, marca o categoría (por ejemplo, “naranjas” debería resolverse como fruta).
• ¿La consulta tiene un patrón tipo SKU?
• ¿La consulta se enmarca dentro de una campaña activa o una política estacional (por ejemplo, durante la Navidad, mejorar los resultados relacionados con el pavo)?
• ¿La consulta implica restricciones (categoría, atributos, exclusiones, precio, tamaño o color)?

2. Aplicar políticas empresariales y de gobernanza

• Primero aplica restricciones deterministas (categoría, atributo, negación, disponibilidad).
• Aplicar políticas activas de merchandising (mejorar/enterrar/fijar/anular).
• Resuelve los conflictos con reglas de precedencia (por ejemplo, anulaciones de campaña frente a políticas globales).

3. Dirige a la estrategia de recuperación adecuada

• Léxico (rápido, determinista) para consultas de navegación o de alta intención.
• Recuperación semántica para búsquedas de descubrimiento real.
• Híbrido en el que la combinación de señales léxicas y semánticas aporta valor añadido dentro de unos límites empresariales explícitos.

En la práctica, la salida del plano de control no es simplemente “usar híbrido” o “usar semántico”. Es un plan de recuperación regulado: una interpretación de la intención del comprador, las restricciones y políticas que deben aplicar, y la estrategia de recuperación que debe ejecutar. Unos pocos ejemplos sencillos lo demuestran:

Un plano de control selecciona la política y la estrategia de recuperación correctas para cada búsqueda de forma consistente, predecible y a escala. Esto hace que los métodos de recuperación avanzados sean más predecibles en producción porque las restricciones alineadas con la intención se aplican primero y las decisiones de enrutamiento son explícitas en lugar de implícitas.

Cómo esto se relaciona con otros enfoques

Algunos equipos usan modelos de incrustación mejorados para captar mejor la semántica de los productos, lo que puede mejorar de forma considerable la calidad de la búsqueda semántica. Otros utilizan enfoques de reclasificación, como Learning To Rank (LTR), para optimizar el orden de los resultados basado en la participación o señales de negocio después de la recuperación. Ambos son valiosos y a menudo complementarios. Las incrustaciones superiores mejoran la coincidencia de similitudes. La reclasificación mejora el ordenamiento entre los candidatos recuperados.

La gobernanza aborda un aspecto diferente del problema: se sitúa en una etapa previa a la recuperación. Decide qué estrategia de recuperación utilizar (por ejemplo, léxica, semántica o híbrida), qué restricciones deterministas se requieren y qué consultas deben combinar varias políticas de negocio.

Qué aporta un plano de control gestionado

Una vez que se establece una capa de gobernanza, el modelo operativo cambia de forma rotunda. Las consultas críticas para los ingresos se vuelven predecibles. Los equipos de negocio pueden actualizar el comportamiento de búsqueda sin esperar los ciclos de lanzamiento de ingeniería. Y los métodos de recuperación avanzados (como los semánticos y los híbridos) pueden adoptarse de forma gradual, con mecanismos de enrutamiento y controles de seguridad, en vez de como un interruptor global de encendido o apagado.

La siguiente publicación de esta serie explora cómo se ve ese modelo operativo en la práctica y por qué puede ser tan importante como la tecnología de recuperación subyacente.

Si un comerciante tiene que abrir un ticket de Jira y esperar un despliegue para corregir una búsqueda crítica para los ingresos, el cuello de botella no es el motor; es el modelo operativo. La búsqueda moderna de comercio electrónico necesita una manera de traducir la intención comercial en un comportamiento de búsqueda controlado y auditable de manera rápida y segura, sin dejar de usar recuperación avanzada cuando aporta un valor medible.

Lo que se viene

Los patrones explorados en esta serie operan río arriba de la recuperación: traduciendo la intención del negocio en la estrategia de búsqueda correcta antes de que comience la generación de la consulta. En la siguiente publicación, pasamos del problema técnico al operativo: qué ocurre cuando los equipos de negocio pueden cambiar el comportamiento de búsqueda sin un despliegue de ingeniería, y por qué la gobernanza hace que eso sea seguro.

Pon en práctica la búsqueda gobernada de comercio electrónico

Los cuellos de botella de ingeniería, la lógica frágil de la capa de aplicación y los resultados de búsqueda impredecibles son problemas que Elastic Services puede ayudarte a resolver en los proyectos de servicios de comercio electrónico empresarial. La arquitectura del plano de control gobernado que se describe en esta serie fue desarrollada por Elastic Services Engineering.

Si tu equipo está dedicando recursos de ingeniería a convertir las solicitudes de merchandising en cambios de código, o si la lista de tareas pendientes relacionadas con la relevancia de las búsquedas parece no reducirse nunca, podemos ayudarte a evaluar tu arquitectura actual y a trazar un plan para lograr un sistema de búsqueda controlado y editable por el equipo de negocios. Ponte en contacto con Elastic Services.

Únete a la discusión

¿Tienes preguntas sobre la gestión de búsquedas, las estrategias de recuperación o la arquitectura de búsqueda en el comercio electrónico? Únete a la conversación general de la comunidad de Elastic.

Recientemente, contribuimos al proyecto de mastra-ai/mastra open source agregando soporte para Elasticsearch como base de datos vectorial. Con esta nueva característica, puedes usar Elasticsearch de forma nativa en Mastra para almacenar incrustaciones. Además de los vectores, Elasticsearch ofrece un conjunto de funciones avanzadas para satisfacer todas tus necesidades de ingeniería de contexto (por ejemplo, búsqueda híbrida y reordenamiento).

En este artículo, se detalla la creación de un agente para implementar una arquitectura de Retrieval-Augmented Generation (RAG) con Elasticsearch. Te mostraremos un proyecto de demostración en el que se utiliza un enfoque agéntico para interactuar con un corpus de datos de películas de ciencia ficción almacenados en Elasticsearch. El proyecto está disponible en elastic/mastra-elasticsearch-example.

Mastra

Mastra es un marco de trabajo de TypeScript para crear aplicaciones de IA agéntica.

Una estructura de proyecto en Mastra se ve así:

src/
├── mastra/
│   ├── agents/
│   │   └── weather-agent.ts
│   ├── tools/
│   │   └── weather-tool.ts
│   ├── workflows/
│   │   └── weather-workflow.ts
│   ├── scorers/
│   │   └── weather-scorer.ts
│   └── index.ts
├── .env.example
├── package.json
└── tsconfig.json

En Mastra, puedes crear agentes, herramientas, flujos de trabajo y puntajes.

Un agente es una clase que acepta un mensaje como entrada y produce una respuesta como salida. Un agente puede usar herramientas, modelos de lenguaje a gran escala (LLM) y una memoria (figura 1).

Las herramientas de un agente le permiten interactuar con el "mundo externo", como comunicarse con una API web o hacer una operación interna, como consultar Elasticsearch. El componente de memoria es crucial para almacenar el historial de conversaciones, incluidas las entradas y salidas pasadas. Este contexto almacenado permite que el agente proporcione respuestas más informadas y relevantes a preguntas futuras mediante el uso de sus interacciones pasadas.

Los flujos de trabajo te permiten definir secuencias complejas de tareas mediante pasos claros y estructurados, en lugar de depender del razonamiento de un solo agente (figura 2). Te brindan control total sobre cómo se desglosan las tareas, cómo se mueven los datos entre ellas y qué se ejecuta y cuándo. Los flujos de trabajo se ejecutan con el motor de ejecución integrado de forma predeterminada o se pueden desplegar en ejecutores de flujos de trabajo.

En Mastra, también puedes definir puntuaciones, que son pruebas automatizadas que evalúan las salidas de los agentes mediante métodos calificados por modelos, basados en reglas y estadísticos. Los evaluadores devuelven puntuaciones: valores numéricos (normalmente entre 0 y 1) que cuantifican qué tan bien una salida cumple con tus criterios de evaluación. Estas puntuaciones te permiten hacer un seguimiento objetivo del rendimiento, comparar diferentes enfoques e identificar áreas de mejora en tus sistemas de IA. Los evaluadores pueden personalizarse con tus propias solicitudes y funciones de puntuación.

Elasticsearch

Para ejecutar el proyecto de demostración, necesitamos tener una instancia de Elasticsearch en ejecución. Puedes activar una prueba gratis en Elastic Cloud o instalarlo localmente usando el script start-local:

curl -fsSL https://elastic.co/start-local | sh

Se instalarán Elasticsearch y Kibana en tu computadora y se generará una clave API que se utilizará para configurar la integración de Mastra.

La clave de API se mostrará como salida del comando anterior y se almacenará en un archivo .env en la carpeta elastic-start-local.

Instalar y configurar la demo

Creamos un repositorio elastic/mastra-elasticsearch-example que contiene el código fuente del proyecto de demostración. El ejemplo reportado en el repositorio ilustra cómo crear un agente en Mastra que implemente una arquitectura RAG para recuperar documentos de Elasticsearch.

Proporcionamos un set de datos para la demostración sobre películas de ciencia ficción. Extrajimos 500 películas de los sets de datos de IMDb en Kaggle.

El primer paso es instalar las dependencias del proyecto con npm, usando el siguiente comando:

npm install

Luego tenemos que configurar el archivo .env que contendrá la configuración. Podemos generar este archivo copiando la estructura del archivo .env.example , usando el siguiente comando:

cp .env.example .env

Ahora podemos editar el archivo .env, agregando la información faltante:

OPENAI_API_KEY=
ELASTICSEARCH_URL=
ELASTICSEARCH_API_KEY=
ELASTICSEARCH_INDEX_NAME=scifi-movies

El nombre del índice de Elasticsearch es scifi-movies. Si quieres, puedes cambiarlo usando la variable de entorno ELASTICSEARCH_INDEX_NAME.

Usamos OpenAI como servicio de incrustación, lo que significa que necesitas proporcionar una clave API para OpenAI en la variable OPENAI_API_KEY .env.

El modelo de incrustación empleado en el ejemplo es openai/text-embedding-3-small, con una dimensión de incrustación de 1536.

Para generar la respuesta final, empleamos el modelo openai/gpt-5-nano para reducir costos.

La arquitectura RAG te permite usar un modelo LLM final menos potente (y generalmente menos costoso) porque el trabajo pesado de fundamentar la respuesta está a cargo del componente de recuperación (Elasticsearch en este caso).

El LLM más pequeño solo se encarga de dos tareas principales:

• Reformulación/incrustación de la consulta: Convertir la pregunta en lenguaje natural del usuario en una incrustación de vectores para la búsqueda semántica.
• Sintetizar la respuesta: Se toman los fragmentos de contexto muy relevantes y recuperados (documentos/películas) y se los sintetiza en una respuesta coherente, final y legible por seres humanos, siguiendo las instrucciones del prompt proporcionado.

Dado que el proceso RAG proporciona el contexto fáctico exacto necesario para la respuesta, el LLM final no necesita ser masivo o muy complejo y no necesita poseer todo el conocimiento requerido dentro de sus propios parámetros (que es donde sobresalen los modelos grandes y caros). Esencialmente actúa como un sofisticado resumidor y formateador de texto para el contexto proporcionado por Elasticsearch, en lugar de ser una base de conocimientos completa en sí mismo. Esto permite el uso de modelos como gpt-5-nano para optimizar costos y latencia.

Después de la configuración del archivo .env, puedes ingestar las películas a Elasticsearch usando el siguiente comando:

npx tsx src/utility/store.ts

Deberías ver una salida como la siguiente:

🚀 Starting ingestion of 500 movies from 500_scifi_movies.jsonl...
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 1/500 (0%) | ok:1 | fail:0 | chunks:1 | eta:19m 33s | current:Capricorn One
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 2/500 (0%) | ok:2 | fail:0 | chunks:2 | eta:10m 32s | current:Doghouse
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 3/500 (1%) | ok:3 | fail:0 | chunks:3 | eta:7m 33s | current:Dinocroc
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 4/500 (1%) | ok:4 | fail:0 | chunks:7 | eta:6m 10s | current:Back to the Future           
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 5/500 (1%) | ok:5 | fail:0 | chunks:9 | eta:5m 14s | current:The Projected Man            
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 6/500 (1%) | ok:6 | fail:0 | chunks:11 | eta:4m 41s | current:I, Robot
...
✅ Ingestion complete in 1m 46s. Success: 500, Failed: 0, Chunks: 693.

El mapping del índice de películas de ciencia ficción contiene los siguientes campos:

• incrustación, dense_vector con 1536 dimensiones, similitud del coseno.
• descripción, texto que contiene la descripción de la película.
• director, texto que contiene el nombre del director.
• título, texto que contiene el título de la película.

Generamos las incrustaciones usando el título + la descripción. Como el título y la descripción son dos campos separados, la concatenación de ambos asegura que el vector de incrustación resultante capture tanto la identidad única y específica (título) como el contexto rico y descriptivo (descripción) de la película, lo que lleva a resultados de búsqueda semántica más precisos y completos. Esta entrada combinada le brinda al modelo de incrustación una mejor representación del contenido del documento para la búsqueda por similitud.

Ejecuta la demostración

Puedes ejecutar la demo con el siguiente comando:

npm run dev

Este comando iniciará una aplicación web en localhost:4111 para acceder a Mastra Studio (figura 3).

Mastra Studio ofrece una UI interactiva para crear y probar tus agentes, junto con una API REST que expone tu aplicación Mastra como un servicio local. Esto te permite comenzar a construir de inmediato sin preocuparte por la integración.

Proporcionamos un Agente Elasticsearch que emplea createVectorQueryTool de Mastra como herramienta para ejecutar búsqueda semántica usando Elasticsearch. Este agente emplea el enfoque RAG para buscar documentos relevantes (es decir, películas) que respondan a la pregunta del usuario.

Este agente usa el siguiente prompt:

You are a helpful assistant that answers questions based on the provided context.
Follow these steps for each response:

1. First, carefully analyze the retrieved context chunks and identify key information.
2. Break down your thinking process about how the retrieved information relates to the query.
3. Draw conclusions based only on the evidence in the retrieved context.
4. If the retrieved chunks don't contain enough information, explicitly state what's missing.

Format your response as:
THOUGHT PROCESS:
- Step 1: [Initial analysis of retrieved chunks]
- Step 2: [Reasoning based on chunks]

FINAL ANSWER:
[Your concise answer based on the retrieved context]

Important: When asked to answer a question, please base your answer only on the context provided in the tool. 
If the context doesn't contain enough information to fully answer the question, please state that explicitly and stop it.
Do not add more information than what is present in the retrieved chunks.
Remember: Explain how you're using the retrieved information to reach your conclusions.

Si haces clic en el menú Mastra Studio > Agents y seleccionas Agente de Elasticsearch, puedes probar el agente usando un sistema de chat. Por ejemplo, puedes pedir información sobre películas de ciencia ficción con una pregunta como esta:

Encuentra 5 películas o series de TV sobre ovnis.

Notarás que el agente ejecutará el vectorQueryTool. Puedes hacer clic en la herramienta invocada para ver la entrada y la salida. Al final de la ejecución, el LLM responderá tu pregunta, dado el contexto que proviene del índice de películas de ciencia ficción de Elasticsearch (figura 4).

Mastra ejecuta los siguientes pasos internamente:

1. Conversión en vectores: La pregunta del usuario, Encuentra 5 películas o series de televisión sobre ovnis, se convierte en una incrustación de vectores mediante el modelo openai/text-embedding-3-small de OpenAI.
2. Búsqueda de vectores: Esta incrustación se usa luego para hacer una búsqueda en Elasticsearch mediante una búsqueda de vectores.
3. Recuperación de resultados: Elasticsearch devuelve una serie de 10 películas muy relevantes para la consulta (es decir, aquellas con vectores más cercanos al vector de consulta del usuario).
4. Generación de respuestas: Las películas recuperadas y la pregunta original del usuario se envían al LLM, específicamente openai/gpt-5-nano. El LLM procesa esta información y genera una respuesta final, asegurando que se cumpla la solicitud del usuario para cinco resultados.

El agente de Elasticsearch

Aquí presentamos el código fuente del agente de Elasticsearch.

import { Agent } from "@mastra/core/agent";
import { ElasticSearchVector } from '@mastra/elasticsearch';
import { createVectorQueryTool } from '@mastra/rag';
import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
import { Memory } from "@mastra/memory";

const es_url = process.env.ELASTICSEARCH_URL;
const es_apikey = process.env.ELASTICSEARCH_API_KEY;
const es_index_name = process.env.ELASTICSEARCH_INDEX_NAME;
const prompt = 'insert here the previous prompt';

const esVector = new ElasticSearchVector({
  id: 'elasticsearch-vector',
  url: es_url,
  auth: {
    apiKey : es_apikey
  }
});

const vectorQueryTool = createVectorQueryTool({
  vectorStore: esVector,
  indexName: es_index_name,
  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small")
});

export const elasticsearchAgent = new Agent({
  id: "elasticsearch-agent",
  name: "Elasticsearch Agent",
  instructions: prompt,
  model: 'openai/gpt-5-nano',
  tools: { vectorQueryTool },
  memory: new Memory(),
});

El vectorQueryTool es la herramienta que se invoca para implementar la parte de recuperación del ejemplo de RAG. Emplea la implementación de ElasticSearchVector que Elastic aportó a Mastra.

El agente es un objeto de la clase agente que utiliza la herramienta vectorQueryTool, el prompt y una memoria. Como puedes ver, el código que necesitamos implementar para conectar Elasticsearch a un agente es muy sencillo.

Conclusión

En este artículo, se demostró la simplicidad y el poder de integrar Elasticsearch con el marco de trabajo Mastra para construir sofisticadas aplicaciones de IA agéntica. En concreto, te mostramos cómo crear un agente RAG capaz de efectuar búsquedas semánticas sobre un corpus de datos de películas de ciencia ficción indexados en Elasticsearch.

Una de las principales conclusiones es la contribución directa de Elastic al proyecto de código abierto Mastra, que ofrece compatibilidad nativa con Elasticsearch como almacén de vectores. Esta integración reduce considerablemente las barreras de acceso, como se puede ver en el código fuente del agente de Elasticsearch. Usando el ElasticSearchVector y createVectorQueryTool, la configuración completa para conectar Elasticsearch a tu agente requiere solo un número mínimo de líneas de código de configuración.

Elasticsearch ofrece varias características avanzadas para mejorar la relevancia de los resultados. Por ejemplo, la búsqueda híbrida aumenta significativamente la precisión combinando la búsqueda léxica con la búsqueda de vectores. Otra característica interesante es la reclasificación con los últimos modelos de Jina, que puede aplicarse al final de la búsqueda híbrida. Para obtener más información sobre estas técnicas, consulta los siguientes artículos de Elasticsearch Labs:

• Búsqueda híbrida Elasticsearch de Valentin Crettaz
• Introducción a los modelos de Jina, su funcionalidad y usos en Elasticsearch de Scott Martens

También te animamos a consultar el ejemplo proporcionado y comenzar a crear tus propios agentes basados en datos con Mastra y Elasticsearch. Para más información sobre Mastra, puedes consultar la documentación oficial aquí.

Los flujos de trabajo de Elastic son un motor de automatización integrado dentro de Kibana que te permite definir procesos multipaso usando una configuración sencilla de YAML. Cada flujo de trabajo puede activarse según una programación o un evento, o como una herramienta en Elastic Agent Builder, y cada paso puede llamar a las API de Kibana, consultar Elasticsearch o transformar datos.

Usaremos los recuentos de vistas del dashboard como ejemplo concreto, pero el mismo patrón aplica a cualquier métrica expuesta a través de la API de objetos guardados de Kibana.

Requisitos previos

• Elastic Cloud o un clúster autogestionado ejecutando la versión 9.3
• Flujos de trabajo activados (Configuración avanzada)

Antes de crear cualquier cosa, entendamos qué datos tenemos. Kibana almacena la mayor parte de su configuración y metadatos como objetos guardados en un índice interno dedicado. Una de las cosas que Kibana rastrea de esta manera es el número de vistas del dashboard, mediante un tipo especial de objeto guardado llamado contadores de uso. Puedes consultarlas directamente desde las Herramientas de desarrollo:

GET kbn:/api/saved_objects/_find?type=usage-counter&filter=usage-counter.attributes.domainId:"dashboard"%20and%20usage-counter.attributes.counterType:"viewed"&per_page=10000

La respuesta tiene el siguiente aspecto:

{
  "page": 1,
  "per_page": 10000,
  "total": 1,
  "saved_objects": [
    {
      "type": "usage-counter",
      "id": "dashboard:346f3c64-ebca-484d-9d57-ec600067d596:viewed:server:20260310",
      "attributes": {
        "domainId": "dashboard",
        "counterName": "346f3c64-ebca-484d-9d57-ec600067d596",
        "counterType": "viewed",
        "source": "server",
        "count": 1
      },
      ...
    }
  ]

El campo counterName es el ID del dashboard y count es el recuento acumulado de vistas para ese dashboard en ese día específico. Kibana crea un objeto de contador por dashboard al día; puedes ver el sufijo de fecha en el ID del objeto (...viewed:server:20260310). El conteo aumenta a lo largo del día a medida que los usuarios abren el dashboard.

En lugar de replicar este modelo de documento diario en nuestro índice, crearemos un documento por cada ejecución del flujo de trabajo. Cada documento registra cuántas vistas había acumulado ese dashboard durante el día en el momento de la captura.

Paso 2: Crear el índice de destino

Necesitamos un índice para almacenar las snapshots de la vista del dashboard. El siguiente comando lo crea con mapeos explícitos para que podamos agregar y visualizar más tarde. Ejecuta esto en herramientas de desarrollo:

PUT dashboard-views
{
  "mappings": {
    "properties": {
      "captured_at": {
        "type": "date"
      },
      "dashboard_id": {
        "type": "keyword"
      },
      "dashboard_name": {
        "type": "keyword"
      },
      "view_count": {
        "type": "integer"
      }
    }
  }
}

Usarkeyword mapeos para ID y nombres permite agregaciones. Usar integer para view_count es un valor predeterminado seguro, ya que Kibana restablece el contador diariamente, por lo que alcanzar el límite de 32 bits (más de 2 mil millones de vistas en un solo día) no es una preocupación realista. Todavía admite operaciones numéricas, como max, avg y min, entre otras.

Paso 3: Crear el flujo de trabajo

Ve a Stack Management > Flujos de trabajo > Nuevo flujo de trabajo, y pega la siguiente configuración YAML del flujo de trabajo:

name: dashboard-views-ingestion
triggers:
  - type: scheduled
    with:
      every: 30m

steps:
  - name: fetch_dashboard_views
    type: kibana.request
    with:
      method: GET
      path: >-
        /api/saved_objects/_find?type=usage-counter&per_page=10000&filter=usage-counter.attributes.domainId:"dashboard"%20and%20usage-counter.attributes.counterType:"viewed"

  - name: index_each_dashboard
    type: foreach
    foreach: "{{ steps.fetch_dashboard_views.output.saved_objects }}"
    steps:
      - name: fetch_dashboard_name
        type: kibana.request
        with:
          method: GET
          path: /api/saved_objects/dashboard/{{ foreach.item.attributes.counterName }}
        on-failure:
          continue: true

      - name: index_doc
        type: elasticsearch.request
        with:
          method: POST
          path: /dashboard-views/_doc
          body:
            dashboard_id: "{{ foreach.item.attributes.counterName }}"
            dashboard_name: "{{ steps.fetch_dashboard_name.output.attributes.title }}"
            view_count: "${{ foreach.item.attributes.count | plus: 0 }}"
            captured_at: "{{ execution.startedAt | date: '%Y-%m-%dT%H:%M:%SZ' }}"

En la próxima sección, hagamos un desglose del flujo de trabajo paso a paso.

Cómo funciona el flujo de trabajo

Desencadenantes

El flujo de trabajo se ejecuta mediante un desencadenante programado cada 30 minutos. Esto nos proporciona datos temporales sin saturar la API.

fetch_dashboard_views

Usakibana.request para llamar a la API de objetos guardados de Kibana. No hace falta configurar la autenticación: el motor de flujos de trabajo añade automáticamente los encabezados correctos según el contexto de ejecución.

index_each_dashboard (foreach)

Itera sobre la matrizsaved_objects devuelta por el paso anterior. El elemento actual en cada iteración está disponible como foreach.item. Dentro del bucle, ejecutamos dos pasos anidados para cada dashboard.

1. fetch_dashboard_name:

Resuelve el título legible para los humanos del dashboard al llamar a GET /api/saved_objects/dashboard/{id}. Agregamos on-failure: continue: true para que, si un dashboard se eliminó pero aún tiene contadores de vistas, el bucle continúe en lugar de fallar toda la ejecución.

2. index_doc:

Indexa cada documento usando POST /dashboard-views/_doc (sin un ID explícito), lo que permite que Elasticsearch genere automáticamente los ID. Esto crea un nuevo documento en cada ejecución, lo que crea un historial del número de vistas a lo largo del tiempo en lugar de sobreescribir el snapshot anterior.

Dos cosas que vale la pena destacar:

• El campo captured_at usa el filtro de fecha para formatear la marca de tiempo como ISO 8601. Sin ella, el valor sale como un texto de fechas en JavaScript, como Tue Mar 10 2026 05:03:47 GMT+0000, que Elasticsearch no asigna como fecha.
• El view_count usa la sintaxis ${{ }} con | plus: 0 para preservar el tipo numérico. Usar {{ }} lo mostraría como un texto, lo que impediría realizar operaciones matemáticas en el dashboard.

La UI te permite depurar fácilmente cada uno de los pasos del flujo de trabajo.

Paso 4: Crea el dashboard de estadísticas

Una vez que el flujo de trabajo se haya ejecutado varias veces y se hayan recopilado los datos, crea un nuevo dashboard en Kibana usando la Data view de vistas del dashboard.

Algunos paneles para empezar:

• Los dashboards más vistos: Usa un Gráfico de barras con dashboard_name en el eje X y last_value(view_count) en el eje Y. Aquí se muestra el número actual de vistas diarias por dashboard.
• Vistas a lo largo del tiempo: usa un gráfico de líneas con captured_at en el eje X y last_value(view_count) en el eje Y, desglosado por dashboard_name. Dado que cada ejecución agrega un nuevo documento, usa el último valor para obtener el recuento máximo por cubetas de tiempo en lugar de sumar duplicados.
• Snapshot actual: usa una tabla de datos con el captured_at más reciente para mostrar los recuentos de vistas más recientes en todos los dashboards.

Dado que cada flujo de trabajo crea un nuevo documento, puedes filtrar por intervalo de tiempo para analizar la actividad en períodos específicos, comparar semana a semana o configurar alertas cuando un dashboard caiga por debajo de un umbral de visitas.

Conclusión

Elastic Flujos de trabajo es una buena opción para este tipo de recopilación periódica de datos porque tanto el origen (API de Kibana) como el destino (Elasticsearch) son nativos, lo que significa cero gestión de credenciales. El motor de flujo de trabajo maneja la autenticación automáticamente para los pasos kibana.request y elasticsearch.request, por lo que lo único que escribes es la lógica.

Recursos

• Flujos de trabajo de Elastic
• API de Kibana

Elasticsearch rechazaba métricas que llegaban con retraso. Esos rechazos hicieron que el pipeline se retrasara, lo que dio como resultado más datos tardíos, lo que desencadenó aún más rechazos. Finalmente, el pipeline se detuvo por completo.

Tuvimos que restaurar desde un snapshot, reindexar los datos y rediseñar el pipeline de ingesta para recuperarnos.

La causa raíz no era la gestión del ciclo de vida de los índices (ILM) en sí. Eran los flujos de datos temporales (TSDS) y cómo imponen índices de respaldo acotados en el tiempo.

TSDS puede reducir las necesidades de almacenamiento para las métricas en un 40–70 %, pero los cambios de arquitectura que hacen que TSDS sea eficiente también alteran el comportamiento de los índices con el tiempo. Esos cambios importan al diseñar políticas de ILM o cuando tus Pipelines de ingesta pueden generar datos que llegan con retraso.

TL;DR

Al usar TSDS:

• Los índices de respaldo solo aceptan documentos dentro de una ventana de tiempo específica.
• Si llegan datos tardíos después de que un índice pasa a frío o congelado, Elasticsearch rechaza esos documentos o los envía al almacén de fallas, si está configurado.

Regla de diseño:

warm_min_age > rollover_max_age + maximum_expected_lateness

¿Qué es un flujo de datos temporales?

Un flujo de datos temporales (TSDS) es un flujo de datos especializado optimizado para datos de métricas. Los datos se distribuyen de manera que los documentos relacionados se encuentren dentro de los mismos fragmentos, lo que optimiza su búsqueda y recuperación. Así es como lo hace Elasticsearch:

Cada documento contiene:

• Una marca de tiempo.
• Campos de dimensión que identifican las series temporales.
• Campos métricos que representan valores medidos.

Entre los ejemplos, se incluyen los siguientes:

• Uso de CPU por host.
• Latencia de las solicitudes por servicio.
• Lecturas de temperatura por sensor.

Las dimensiones identifican lo que queremos medir, mientras que las métricas representan valores que cambian con el tiempo.

Dimensiones

Las dimensiones describen la entidad medida.

Ejemplos:

host.name
service.name
container.id

Los definimos en mapeos con:

time_series_dimension: true

Métricas

Las métricas representan valores numéricos y se definen mediante:

time_series_metric

Tipos comunes de métricas:

• Indicador: valores que suben y bajan.
• Contador: valores que aumentan hasta que se reinician.

Elastic Agent recopila principalmente métricas y datos de logs, por lo que, incluso si no has habilitado ningún índice TSDS manualmente, puedes tenerlos aún en tu clúster.

El campo _tsid

Elasticsearch genera internamente un valor _tsid a partir de campos dimensionales. Esto permite que los documentos con dimensiones idénticas se dirijan al mismo shard, lo que mejora:

• Compresión.
• Localidad de búsqueda.
• Rendimiento de agregación.

La diferencia clave: índices de respaldo limitados en el tiempo

Los flujos de datos tradicionales siempre escriben en el índice de respaldo más reciente, llamado índice de escritura, pero TSDS se comporta de manera diferente.

Cada índice de respaldo TSDS tiene una ventana de tiempo definida y solo acepta documentos con @timestamp valores que se encuentren en esa ventana:

GET _data_stream/my-metrics-data-stream


     "index_mode": "time_series",
     "time_series": {
       "temporal_ranges": [
         {
           "start": "2026-01-15T14:35:50.000Z",
           "end": "2026-03-16T11:34:40.000Z"
         }
       ]
     }

Cuando se indexa un documento, Elasticsearch lo dirige al índice de respaldo responsable de esa marca de tiempo, lo que significa que, a diferencia de los índices tradicionales, un TSDS puede escribir en varios índices de respaldo al mismo tiempo.

Por ejemplo:

• Datos en tiempo real → índice más reciente.
• Datos tardíos → índice anterior que abarca ese intervalo de tiempo.

Diseño para datos con retraso

Las pipelines de ingesta reales rara vez entregan métricas perfectamente a tiempo. Las métricas pueden retrasarse por interrupciones de la red, retrasos en el camino, ingesta por batch y pérdida de dispositivos periféricos, que se vuelven a conectar y comienzan a ponerse al día.

Los índices tradicionales absorben silenciosamente esos retrasos. TSDS no lo hace.

Si la marca de tiempo de un documento queda fuera del intervalo de índices de respaldo con capacidad de escritura, Elasticsearch lo rechaza, lo que significa que tu política de ILM debe tener en cuenta los datos que llegan con retraso.

La restricción crítica

Los índices de respaldo deben mantenerse con permisos de escritura el tiempo suficiente para aceptar datos tardíos.

En términos prácticos:

time_until_readonly > maximum_expected_lateness

Debido a que ILM mide las antigüedades desde el desplazamiento, la regla operativa se convierte en:

warm_or_cold_min_age > rollover_max_age + maximum_expected_lateness

Por ejemplo, si las métricas pueden llegar con hasta seis horas de retraso, los índices deben permanecer editables al menos seis horas después de la transferencia.

No tener en cuenta esta restricción fue exactamente lo que causó la falla de ingesta descrita anteriormente. Los datos que llegaban tarde se dirigieron a un índice anterior, que ya estaba en el nivel frío y, por tanto, bloqueaba la escritura.

Gestión de documentos rechazados

Cuando TSDS rechaza un documento, Elasticsearch devuelve un error, lo que indica que la marca de tiempo no está dentro del rango de índices de escritura. La forma en que tu pipeline de ingesta maneja ese error determina si pierdes datos o si la ingesta se detiene.

El mecanismo principal para manejar documentos rechazados es el almacén de fallas.

Almacén de fallas (recomendado en Elasticsearch 9.1+)

Elasticsearch 9.1 introdujo el almacén de fallas, que captura automáticamente los documentos rechazados. En lugar de devolver errores a los clientes, Elasticsearch escribe los documentos rechazados en un índice de fallas dedicado dentro del flujo de datos.

Puedes inspeccionar las fallas usando:

GET metrics-myapp::failures/_search

Usar el almacén de fallas evita que los pipelines de ingesta se bloqueen por errores de rechazo, a la vez que conserva los datos fallidos para analizarlos o reindexarlos.

Monitoreo de problemas de rechazo

Los problemas de retraso suelen aparecer primero como anomalías de ingesta. Puedes notarlos primero como:

• Caídas repentinas en la tasa de indexación.
• Aumentos repentinos en el número de documentos rechazados.
• Una cantidad cada vez mayor de entradas del almacén de fallas.
• Discrepancias entre el número de entradas y salidas del pipeline.

Alertar sobre estas señales permite a los operadores detectar problemas antes de que los pipelines se detengan. Se pueden utilizar flujos de trabajo, tareas de machine learning y otros mecanismos para automatizar la detección y la notificación.

Lista de verificación de migración para TSDS + ILM

Si estás migrando un cluster de métricas a TSDS, introduciendo la organización en niveles con ILM o actualizando a una versión de Elasticsearch en la que las métricas son TSDS por defecto, revisa primero estos elementos.

1. Mide la latencia de la ingesta

Antes de cambiar las políticas de ILM, determina:

• Retraso normal de ingesta.
• Retraso en el peor de los casos durante incidentes.
• Retrasos causados por pipelines de batch.

Tu diseño de ILM debe contemplar el retraso máximo realista.

2. Verifica las ventanas de tiempo de indexación

Inspecciona tus índices de respaldo TSDS:

GET _data_stream/

Busca:

• time_series.start_time
• time_series.end_time

Estos límites determinan qué índices pueden aceptar documentos. Entender estas ventanas puede ayudarte a determinar cuán tarde pueden llegar los datos antes de que se rechacen.

3. Dimensiona el nivel caliente para llegadas tardías

Garantiza que los índices de respaldo permanezcan con permisos de escritura el tiempo suficiente para los datos retrasados.

Regla operativa:

• warm_min_age > rollover_max_age + maximum_expected_lateness

Recuerda, los índices deben permanecer en modo de escritura durante al menos seis horas si las métricas pueden llegar con seis horas de retraso.

4. Decide cómo manejar los documentos rechazados

Elige una estrategia antes de habilitar TSDS:

• Almacén de fallas (recomendado en Elasticsearch 9.1+).
• Cola de mensajes no procesados de Logstash.
• Índice de respaldo para retrasos.
• Aceptar la pérdida de datos limitada.

5. Monitorea el estado de la ingesta

Agrega alertas para:

• La tasa de indexación disminuye.
• Documentos rechazados.
• Crecimiento del almacén de fallas.
• Desajustes de entrada/salida en la pipeline.

Los problemas de datos tardíos a menudo aparecen primero como anomalías de ingesta.

Resumen

Los flujos de datos temporales ofrecen importantes mejoras de almacenamiento y rendimiento para las cargas de trabajo de métricas, pero introducen un cambio arquitectónico importante: los índices de respaldo están acotados en el tiempo, lo que afecta el comportamiento de ILM.

Al usar TSDS:

• Los índices deben mantenerse con permisos de escritura el tiempo suficiente para aceptar datos tardíos.
• Los pipelines de ingesta deben gestionar los documentos rechazados de forma segura.

La regla clave a recordar es:

warm_min_age > rollover_max_age + maximum_expected_lateness

Si diseñas políticas de ILM teniendo en cuenta esa limitación, TSDS funciona muy bien para cargas de trabajo de métricas.

Sin embargo, si lo ignoras, tu pipeline de ingesta puede descubrir esos límites de tiempo de la manera difícil.

Tu primera búsqueda

Comienza por definir un objeto CLR (POCO) simple que se mapea a tu índice de Elasticsearch. Los nombres de las propiedades se resuelven a nombres de columnas ES|QL a través de atributos System.Text.Json estándar, como [JsonPropertyName], o a través de un JsonNamingPolicy configurado. Las mismas reglas de serialización de origen que se aplican en el resto del cliente también se aplican aquí.

using System.Text.Json.Serialization;

public class Product
{
    [JsonPropertyName("product_id")]
    public string Id { get; set; }

    public string Name { get; set; }

    public string Brand { get; set; }

    [JsonPropertyName("price_usd")]
    public double Price { get; set; }

    [JsonPropertyName("in_stock")]
    public bool InStock { get; set; }
}

Con el tipo ya definido, una consulta se ve así:

var minPrice = 100.0;
var brand = "TechCorp";

await foreach (var product in client.Esql.QueryAsync(q => q
    .From("products")
    .Where(p => p.InStock && p.Price >= minPrice && p.Brand == brand)
    .OrderByDescending(p => p.Price)
    .Take(10)))
{
    Console.WriteLine($"{product.Name}: ${product.Price}");
}

El proveedor traduce esto al siguiente ES|QL:

FROM products
| WHERE (in_stock == true AND price_usd >= ?minPrice AND brand == ?brand)
| SORT price_usd DESC
| LIMIT 10

Algunos detalles a tener en cuenta:

• Resolución de nombres de propiedades: p.Price se vuelve price_usd debido al atributo [JsonPropertyName], y p.Brand se convierte en brand siguiendo la política predeterminada de nombres camelCase.
• Captura de parámetros: Las variables C# minPrice y brand se capturan como parámetros nombrados (?minPrice, ?brand). Se envían por separado del texto de búsqueda en la carga útil JSON, lo que previene la inyección y habilita el almacenamiento en caché del plan de búsqueda del lado del servidor.
• Streaming: QueryAsync<T> devuelve IAsyncEnumerable<T>. Las filas se materializan una a la vez a medida que llegan desde Elasticsearch.

También puedes inspeccionar la búsqueda generada y sus parámetros sin ejecutarla:

var query = client.Esql.CreateQuery()
    .Where(p => p.InStock && p.Price >= minPrice && p.Brand == brand)
    .OrderByDescending(p => p.Price)
    .Take(10);

Console.WriteLine(query.ToEsqlString());
// FROM products | WHERE (in_stock == true AND price_usd >= 100) | SORT price_usd DESC | LIMIT 10

Console.WriteLine(query.ToEsqlString(inlineParameters: false));
// FROM products | WHERE (in_stock == true AND price_usd >= ?minPrice AND brand == ?brand) | SORT price_usd DESC | LIMIT 10

var parameters = query.GetParameters();
// { "minPrice": 100.0, "brand": "TechCorp" }

¿Cómo funciona esto? Un repaso rápido de LINQ

El mecanismo que hace posibles los proveedores LINQ es la distinción entre IEnumerable<T> y IQueryable<T>.

Cuando llamas a .Where(p => p.Price > 100) en un IEnumerable<T>, la lambda se compila en un Func<Product, bool>, un delegado común que el runtime ejecuta en proceso. Esto es LINQ a objetos.

Cuando llamas al mismo método en un IQueryable<T>, el compilador de C# encapsula la expresión lambda en un Expression<Func<Product, bool>> en su lugar. Esta es una estructura de datos que representa la estructura del código en lugar de su forma ejecutable. El árbol de expresión puede inspeccionarse, analizarse y traducirse a otro idioma en tiempo de ejecución.

// IEnumerable: the lambda is a compiled delegate
IEnumerable local = products.Where(p => p.Price > 100);

// IQueryable: the lambda is an expression tree, a data structure
IQueryable remote = queryable.Where(p => p.Price > 100);

La interfaz IQueryProvider es el punto de extensión. Cualquier proveedor puede implementar CreateQuery<T> y Execute<T> para traducir estos árboles de expresiones a un idioma destino. Entity Framework usa esto para emitir SQL. El proveedor de LINQ a ES|QL lo usa para emitir ES|QL.

El árbol de expresión para la búsqueda anterior se ve así:

Árbol de expresiones para la búsqueda de ejemplo.

El árbol está anidado al revés: Take envuelve OrderByDescending, que envuelve Where, que envuelve From, que envuelve la constante raíz EsqlQueryable<Product>. El predicado Where es en sí mismo un subárbol de BinaryExpression nodos para los operadores &&, >= y ==, con MemberExpression hojas para accesos a propiedades y capturas de cierre para las variables minPrice y brand. Esta es la estructura de datos que el proveedor recorre para producir el ES|QL final.

En detalle: el pipeline de traducción

La ruta de una expresión LINQ a los resultados de la búsqueda sigue un pipeline de seis etapas:

Visión general del pipeline de traducción.

1. Captura del árbol de expresiones

Cuando se encadenan .Where(), .OrderBy(), .Take() y otros operadores en un IQueryable<T>, la infraestructura LINQ estándar crea un árbol de expresiones. EsqlQueryable<T> implementa IQueryable<T> y delega a EsqlQueryProvider.

2. Traducción

Cuando se ejecuta la búsqueda (al enumerar, llamar a ToList() o usar await foreach), EsqlExpressionVisitor recorre el árbol de expresiones de adentro hacia afuera. Envía cada llamada al método LINQ a un visitante especializado:

Durante la traducción, las variables de C# a las que se hace referencia en las expresiones se capturan como parámetros con nombre.

3. Modelo de búsqueda

Los visitantes no producen textos directamente. En cambio, producen objetos QueryCommand, una representación intermedia inmutable. Un FromCommand, un WhereCommand, un SortCommand y un LimitCommand, cada uno representa un comando de procesamiento de ES|QL. Estos se recopilan en un modelo EsqlQuery.

Modelo de búsqueda y patrón de comandos.

Este modelo intermedio está desacoplado tanto del árbol de expresiones como del formato de salida. Se puede inspeccionar, interceptar (vía IEsqlQueryInterceptor) o modificar antes de dar formato.

4. Formato

EsqlFormatter visita cada QueryCommand en orden y produce el texto final de ES|QL. Cada comando se convierte en una línea, separada por el operador de barra vertical (|) que ES|QL usa para encadenar comandos de procesamiento. Los identificadores que contienen caracteres especiales se escapan automáticamente con comillas invertidas.

5. Ejecución

El texto ES|QL formateado y los parámetros capturados se envían al endpoint /_query de Elasticsearch como carga útil JSON. La interfaz IEsqlQueryExecutor abstrae la capa de transporte, que es donde entra en juego la arquitectura de paquetes en capas.

6. Materialización

EsqlResponseReader transmite la respuesta JSON sin almacenar en memoria todo el conjunto de resultados. Un árbol ColumnLayout, precomputado una vez por búsqueda, mapea nombres de columnas planas de ES|QL (como address.street, address.city) a propiedades anidadas de POCO. Cada fila se ensambla en una instancia T y se genera una a la vez a través de IEnumerable<T> o IAsyncEnumerable<T>.

La arquitectura en capas

La funcionalidad de LINQ a ES|QL se divide en tres paquetes:

Arquitectura de paquetes.
Elastic.Esql es el motor puro de traducción. No tiene dependencias HTTP y contiene los visitantes de expresiones, el modelo de búsqueda, el formateador y el lector de respuestas. Puedes usarlo de forma independiente para crear e inspeccionar búsquedas de ES|QL sin una conexión de Elasticsearch, lo que es útil para pruebas, logging de búsquedas o para crear tu propia capa de ejecución.

// Translation-only: no Elasticsearch connection needed
var provider = new EsqlQueryProvider();
var query = new EsqlQueryable(provider)
    .From("products")
    .Where(p => p.InStock)
    .OrderByDescending(p => p.Price);

Console.WriteLine(query.ToEsqlString());
// FROM products | WHERE in_stock == true | SORT price_usd DESC

Elastic.Clients.Esql es un cliente ES|QL ligero e independiente. Añade ejecución HTTP sobre Elastic.Esql a través de Elastic.Transport. Si tu aplicación solo necesita ES|QL y ninguna de las otras API de Elasticsearch, esta es la opción de dependencia mínima.

Elastic.Clients.Elasticsearch es el cliente completo de Elasticsearch .NET. También se basa en Elastic.Esql y expone al proveedor LINQ a través del espacio de nombres client.Esql. Este es el punto de entrada recomendado para la mayoría de las aplicaciones.

Ambos paquetes de capa de ejecución proporcionan su propia implementación de IEsqlQueryExecutor, la interfaz estratégica que une la traducción y el transporte.

Los tres paquetes son compatibles con Native AOT cuando se usan con un JsonSerializerContext generado por el código fuente. Para el cliente completo, consulta la documentación de Native AOT.

Mas allá de los conceptos básicos

El ejemplo anterior cubrió el filtrado, la clasificación y la paginación. El proveedor admite un conjunto más amplio de operaciones.

Agregaciones

GroupBy, combinado con funciones agregadas en Select, se traduce a ES|QL STATS ... BY:

var stats = client.Esql.Query(q => q
    .GroupBy(p => p.Brand)
    .Select(g => new
    {
        Brand = g.Key,
        Count = g.Count(),
        AvgPrice = g.Average(p => p.Price),
        MaxPrice = g.Max(p => p.Price)
    }));

// -> FROM products | STATS COUNT(*), AVG(price_usd), MAX(price_usd) BY brand

Proyecciones

Select, con tipos anónimos genera comandos EVAL, KEEP, y RENAME:

var query = client.Esql.CreateQuery()
    .Select(p => new { ProductName = p.Name, p.Price, p.InStock });

// -> FROM products | KEEP name, price_usd, in_stock | RENAME name AS ProductName

Biblioteca de funciones enriquecida

Hay más de 80 funciones ES|QL disponibles a través de la clase EsqlFunctions, que abarcan fecha/hora, texto, matemáticas, IP, coincidencia de patrones y puntuación. También se traducen los métodos estándar Math.* y string.*:

.Where(p => p.Name.Contains("Pro"))       // -> WHERE name LIKE "*Pro*"
.Where(p => EsqlFunctions.CidrMatch(      // -> WHERE CIDR_MATCH(ip, "10.0.0.0/8")
    p.IpAddress, "10.0.0.0/8"))

LOOKUP JOIN

Las consultas cruzadas de índices se traducen a ES|QL LOOKUP JOIN:

var enriched = client.Esql.Query(q => q
    .LookupJoin(
        "category-lookup-index",
        product => product.Id,
        category => category.CategoryId,
        (product, category) => new { product.Name, category!.CategoryLabel }));

Acceso directo a ES|QL sin procesar

Para las características de ES|QL que aún no están cubiertas por el proveedor de LINQ, puedes anexar fragmentos sin procesar:

var results = client.Esql.Query(q => q
    .Where(p => p.InStock)
    .RawEsql("| EVAL discounted = price_usd * 0.9"));

Búsquedas asíncronas del lado del servidor

Para búsquedas de ejecución prolongada, envíalas para procesamiento en segundo plano en el servidor:

await using var asyncQuery = await client.Esql.SubmitAsyncQueryAsync(
    q => q.Where(p => p.InStock),
    asyncQueryOptions: new EsqlAsyncQueryOptions
    {
        WaitForCompletionTimeout = TimeSpan.FromSeconds(5),
        KeepAlive = TimeSpan.FromMinutes(10)
    });

await asyncQuery.WaitForCompletionAsync();
await foreach (var product in asyncQuery.AsAsyncEnumerable())
    Console.WriteLine(product.Name);

Las búsquedas asíncronas del lado del servidor son especialmente útiles para búsquedas analíticas de larga duración/procesamiento de grandes sets de datos que pueden superar los umbrales típicos de tiempo de espera, o en entornos sensibles al tiempo de espera con balanceadores de carga, gateways API o proxies que imponen tiempos de espera HTTP estrictos. Las búsquedas asíncronas evitan las caídas de conexión al separar el envío de la solicitud de la recuperación de los resultados.

Primeros pasos

LINQ a ES|QL está disponible a partir de:

• Elastic.Clients.Elasticsearch v9.3.4 (rama 9.x)
• Elastic.Clients.Elasticsearch v8.19.18 (rama 8.x)

Instalar desde NuGet:

dotnet add package Elastic.Clients.Elasticsearch

Los puntos de entrada están en client.Esql:

Para consultar la referencia completa de características, incluidas las opciones de búsqueda, el acceso a múltiples campos, los objetos anidados y el manejo de campos de valores múltiples, consulta la documentación de LINQ a ES|QL.

Conclusión

LINQ a ES|QL aporta toda la expresividad de LINQ de C# al lenguaje de búsqueda ES|QL de Elasticsearch, lo que te permite realizar búsquedas con tipado fuerte y combinables sin crear manualmente cadenas de texto. Con captura automática de parámetros, materialización de streaming y una arquitectura de paquetes en capas que escala desde el paquete de traducción autónomo hasta el cliente completo de Elasticsearch, se adapta naturalmente a aplicaciones .NET de cualquier tamaño. Instala el cliente más reciente, dirige tus expresiones LINQ a un índice y deja que el proveedor se encargue del resto.

En este artículo, exploraremos las ventajas de construir un servidor MCP personalizado de Elasticsearch y mostraremos cómo crear uno en TypeScript que conecte Elasticsearch con aplicaciones impulsadas por LLM.

¿Por qué construir un servidor MCP personalizado de Elasticsearch?

Elastic ofrece algunas alternativas para los servidores MCP:

• Servidor MCP de Elastic Agent Builder para Elasticsearch 9.2+
• Servidor MCP de Elasticsearch para versiones anteriores (Python)

Si necesitas más control sobre cómo tu servidor MCP interactúa con Elasticsearch, construir tu propio servidor personalizado te da la flexibilidad de adaptarlo exactamente a tus necesidades. Por ejemplo, el endpoint MCP de Agent Builder está limitado a las consultas de lenguaje de búsqueda (ES|QL) de Elasticsearch, mientras que un servidor personalizado te permite usar el DSL de consulta completo. También obtienes control sobre cómo se formatean los resultados antes de pasarlos al LLM y puedes integrar pasos de procesamiento adicionales, como el resumen impulsado por OpenAI que implementaremos en este tutorial.

Al final de este artículo, tendrás un servidor MCP en TypeScript que busca información almacenada en un índice de Elasticsearch, la resume y proporciona citas. Usaremos Elasticsearch para la recuperación, el modelo gpt-4o-mini de OpenAI para resumir y generar citas, y Claude Desktop como cliente MCP y UI para recibir las búsquedas de los usuarios y dar respuestas. El resultado final es un asistente de conocimiento interno que ayuda a los ingenieros a descubrir y sintetizar las mejores prácticas en los documentos técnicos de su organización.

Requisitos previos:

• Node.js 20 +
• Elasticsearch
• Clave de API de OpenAI
• Claude Desktop

¿Qué es MCP?

MCP es un estándar abierto, creado por Anthropic, que ofrece conexiones seguras y bidireccionales entre los modelos de lenguaje grande (LLM) y sistemas externos, como Elasticsearch. Puedes leer más sobre el estado actual del MCP en este artículo.

El panorama de MCP evoluciona cada día, con servidores disponibles para una amplia gama de casos de uso. Además de eso, desarrollar tu propio servidor MCP personalizado es fácil, como te mostraremos en este artículo.

Clientes del MCP

Hay una larga lista de clientes del MCP disponibles, cada uno con sus propias características y limitaciones. Por su sencillez y popularidad, usaremos Claude Desktop como nuestro cliente MCP. Servirá como interfaz de chat en la que los usuarios podrán hacer preguntas en lenguaje natural e invocar automáticamente las herramientas expuestas por nuestro servidor MCP para buscar documentos y generar resúmenes.

Cómo crear un servidor MCP de Elasticsearch

Con el SDK de TypeScript, podemos crear fácilmente un servidor que entiende cómo hacer búsquedas en nuestros datos de Elasticsearch con base en la entrada de búsqueda del usuario.

Estos son los pasos en este artículo para integrar el servidor MCP de Elasticsearch con el cliente Claude Desktop:

1. Configurar el servidor MCP para Elasticsearch.
2. Carga el servidor MCP en Claude Desktop.
3. Pruébalo.

Configurar el servidor MCP para Elasticsearch

Para comenzar, inicialicemos una aplicación de nodo:

npm init -y

Esto creará un archivo package.json y, con él, podremos empezar a instalar las dependencias necesarias para esta aplicación.

npm install @elastic/elasticsearch @modelcontextprotocol/sdk openai zod && npm install --save-dev ts-node @types/node typescript

• @elastic/elasticsearch nos dará acceso a la biblioteca de Elasticsearch para Node.js.
• @modelcontextprotocol/sdk proporciona las herramientas básicas para crear y administrar un servidor MCP, registrar herramientas y manejar la comunicación con los clientes de MCP.
• openAI permite la interacción con modelos OpenAI para generar resúmenes o respuestas en lenguaje natural.
• zod ayuda a definir y validar esquemas estructurados para los datos de entrada y salida en cada herramienta.

ts-node, @types/node y typescript se usarán durante el desarrollo para escribir el código y compilar los scripts.

Configura los sets de datos

Para proporcionar los datos que Claude Desktop puede consultar con nuestro servidor de MCP, utilizaremos un conjunto de datos de base de conocimiento interna simulado. Así es como se verá un documento de este sets de datos:

{
    "id": 5,
    "title": "Logging Standards for Microservices",
    "content": "Consistent logging across microservices helps with debugging and tracing. Use structured JSON logs and include request IDs and timestamps. Avoid logging sensitive information. Centralize logs in Elasticsearch or a similar system. Configure log rotation to prevent storage issues and ensure logs are searchable for at least 30 days.",
    "tags": ["logging", "microservices", "standards"]
}

Para cargar los datos, preparamos un script que cree un índice en Elasticsearch y cargue el set de datos en él. Puedes encontrarlo aquí.

Servidor MCP

Crea un archivo llamado index.ts y agrega el siguiente código para importar las dependencias y gestionar las variables de entorno:

// index.ts
import { z } from "zod";
import { Client } from "@elastic/elasticsearch";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import OpenAI from "openai";

const ELASTICSEARCH_ENDPOINT =
  process.env.ELASTICSEARCH_ENDPOINT ?? "http://localhost:9200";
const ELASTICSEARCH_API_KEY = process.env.ELASTICSEARCH_API_KEY ?? "";
const OPENAI_API_KEY = process.env.OPENAI_API_KEY ?? "";
const INDEX = "documents";

Además, preparemos a los clientes para que gestionen las llamadas a Elasticsearch y OpenAI:

const openai = new OpenAI({
  apiKey: OPENAI_API_KEY,
});

const _client = new Client({
  node: ELASTICSEARCH_ENDPOINT,
  auth: {
    apiKey: ELASTICSEARCH_API_KEY,
  },
});

Para hacer nuestra implementación más robusta y asegurar entradas y salidas estructuradas, definiremos esquemas usando zod. Esto nos permite validar los datos en tiempo de ejecución, detectar errores a tiempo y facilitar el procesamiento de las respuestas de la herramienta mediante código:

const DocumentSchema = z.object({
  id: z.number(),
  title: z.string(),
  content: z.string(),
  tags: z.array(z.string()),
});

const SearchResultSchema = z.object({
  id: z.number(),
  title: z.string(),
  content: z.string(),
  tags: z.array(z.string()),
  score: z.number(),
});

type Document = z.infer;
type SearchResult = z.infer;

Descubre más sobre las salidas estructuradas aquí.

Ahora vamos a inicializar el servidor MCP:

const server = new McpServer({
  name: "Elasticsearch RAG MCP",
  description:
    "A RAG server using Elasticsearch. Provides tools for document search, result summarization, and source citation.",
  version: "1.0.0",
});

Definición de las herramientas MCP

Ahora que ya tenemos todo configurado, podemos empezar a desarrollar las herramientas que ofrecerá nuestro servidor MCP. Este servidor ofrece dos herramientas:

• search_docs: Búsquedas de documentos en Elasticsearch mediante la búsqueda de texto.
• summarize_and_cite: Resume y sintetiza información de documentos previamente recuperados para responder a una pregunta del usuario. Esta herramienta también agrega citas que hacen referencia a los documentos originales.

Juntas, estas herramientas forman un flujo de trabajo simple de “recuperación y resumen”, donde una herramienta busca documentos relevantes y la otra usa esos documentos para generar una respuesta resumida y citada.

Formato de respuesta de herramienta

Cada herramienta puede aceptar parámetros de entrada arbitrarios, pero debe responder con la siguiente estructura:

• Contenido: esta es la respuesta de la herramienta en un formato no estructurado. Este campo se suele usar para mostrar texto, imágenes, audio, enlaces o contenido incrustado. Para esta aplicación, se utilizará para devolver texto formateado con la información generada por las herramientas.
• structuredContent: este es un retorno opcional que se usa para proporcionar los resultados de cada herramienta en un formato estructurado. Esto es útil para fines programáticos. Aunque no se usa en este servidor de MCP, puede ser útil si quieres desarrollar otras herramientas o procesar los resultados mediante programación.

Con esa estructura en mente, comencemos con cada herramienta en detalle.

Herramienta Search_docs

Esta herramienta realiza una búsqueda de texto completo en el índice de Elasticsearch para recuperar los documentos más relevantes según la consulta del usuario. Destaca los resultados clave y ofrece una visión general rápida con puntuaciones de relevancia.

server.registerTool(
  "search_docs",
  {
    title: "Search Documents",
    description:
      "Search for documents in Elasticsearch using full-text search. Returns the most relevant documents with their content, title, tags, and relevance score.",
    inputSchema: {
      query: z
        .string()
        .describe("The search query terms to find relevant documents"),
      max_results: z
        .number()
        .optional()
        .default(5)
        .describe("Maximum number of results to return"),
    },
    outputSchema: {
      results: z.array(SearchResultSchema),
      total: z.number(),
    },
  },
  async ({ query, max_results }) => {
    if (!query) {
      return {
        content: [
          {
            type: "text",
            text: "Query parameter is required",
          },
        ],
        isError: true,
      };
    }

    try {
      const response = await _client.search({
        index: INDEX,
        size: max_results,
        query: {
          bool: {
            must: [
              {
                multi_match: {
                  query: query,
                  fields: ["title^2", "content", "tags"],
                  fuzziness: "AUTO",
                },
              },
            ],
            should: [
              {
                match_phrase: {
                  title: {
                    query: query,
                    boost: 2,
                  },
                },
              },
            ],
          },
        },
        highlight: {
          fields: {
            title: {},
            content: {},
          },
        },
      });

      const results: SearchResult[] = response.hits.hits.map((hit: any) => {
        const source = hit._source as Document;

        return {
          id: source.id,
          title: source.title,
          content: source.content,
          tags: source.tags,
          score: hit._score ?? 0,
        };
      });

      const contentText = results
        .map(
          (r, i) =>
            `[${i + 1}] ${r.title} (score: ${r.score.toFixed(
              2,
            )})\n${r.content.substring(0, 200)}...`,
        )
        .join("\n\n");

      const totalHits =
        typeof response.hits.total === "number"
          ? response.hits.total
          : (response.hits.total?.value ?? 0);

      return {
        content: [
          {
            type: "text",
            text: `Found ${results.length} relevant documents:\n\n${contentText}`,
          },
        ],
        structuredContent: {
          results: results,
          total: totalHits,
        },
      };
    } catch (error: any) {
      console.log("Error during search:", error);

      return {
        content: [
          {
            type: "text",
            text: `Error searching documents: ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }
);

Configuramos fuzziness: “AUTO” para que tenga una tolerancia tipográfica variable basada en la longitud del token que se está analizando. También establecemos title^2 para aumentar la puntuación de los documentos donde se produce la coincidencia en el campo de título.

herramienta de resumen y cita: summarize_and_cite

Esta herramienta genera un resumen basado en los documentos recuperados en la búsqueda anterior. Usa el modelo gpt-4o-mini de OpenAI para sintetizar la información más relevante y responder a la pregunta del usuario para obtener respuestas derivadas directamente de los resultados de búsqueda. Además del resumen, también devuelve metadatos de citas para los documentos fuente utilizados.

server.registerTool(
  "summarize_and_cite",
  {
    title: "Summarize and Cite",
    description:
      "Summarize the provided search results to answer a question and return citation metadata for the sources used.",
    inputSchema: {
      results: z
        .array(SearchResultSchema)
        .describe("Array of search results from search_docs"),
      question: z.string().describe("The question to answer"),
      max_length: z
        .number()
        .optional()
        .default(500)
        .describe("Maximum length of the summary in characters"),
      max_docs: z
        .number()
        .optional()
        .default(5)
        .describe("Maximum number of documents to include in the context"),
    },
    outputSchema: {
      summary: z.string(),
      sources_used: z.number(),
      citations: z.array(
        z.object({
          id: z.number(),
          title: z.string(),
          tags: z.array(z.string()),
          relevance_score: z.number(),
        })
      ),
    },
  },
  async ({ results, question, max_length, max_docs }) => {
    if (!results || results.length === 0 || !question) {
      return {
        content: [
          {
            type: "text",
            text: "Both results and question parameters are required, and results must not be empty",
          },
        ],
        isError: true,
      };
    }

    try {
      const used = results.slice(0, max_docs);

      const context = used
        .map(
          (r: SearchResult, i: number) =>
            `[Document ${i + 1}: ${r.title}]\\n${r.content}`
        )
        .join("\n\n---\n\n");

      // Generate summary with OpenAI
      const completion = await openai.chat.completions.create({
        model: "gpt-4o-mini",
        messages: [
          {
            role: "system",
            content:
              "You are a helpful assistant that answers questions based on provided documents. Synthesize information from the documents to answer the user's question accurately and concisely. If the documents don't contain relevant information, say so.",
          },
          {
            role: "user",
            content: `Question: ${question}\\n\\nRelevant Documents:\\n${context}`,
          },
        ],
        max_tokens: Math.min(Math.ceil(max_length / 4), 1000),
        temperature: 0.3,
      });

      const summaryText =
        completion.choices[0]?.message?.content ?? "No summary generated.";

      const citations = used.map((r: SearchResult) => ({
        id: r.id,
        title: r.title,
        tags: r.tags,
        relevance_score: r.score,
      }));

      const citationText = citations
        .map(
          (c: any, i: number) =>
            `[${i + 1}] ID: ${c.id}, Title: "${c.title}", Tags: ${c.tags.join(
              ", ",
            )}, Score: ${c.relevance_score.toFixed(2)}`,
        )
        .join("\n");

      const combinedText = `Summary:\\n\\n${summaryText}\\n\\nSources used (${citations.length}):\\n\\n${citationText}`;

      return {
        content: [
          {
            type: "text",
            text: combinedText,
          },
        ],
        structuredContent: {
          summary: summaryText,
          sources_used: citations.length,
          citations: citations,
        },
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: "text",
            text: `Error generating summary and citations: ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }
);

Finalmente, necesitamos iniciar el servidor a través de stdio. Esto significa que el cliente MCP se comunicará con nuestro servidor leyendo y escribiendo en sus flujos estándar de entrada y salida. stdio es la opción de transporte más sencilla y funciona bien para servidores MCP locales lanzados como subprocesos por el cliente. Agrega el siguiente código al final del archivo:

const transport = new StdioServerTransport();
server.connect(transport);

Ahora compila el proyecto usando el siguiente comando:

npx tsc index.ts --target ES2022 --module node16 --moduleResolution node16 --outDir ./dist --strict --esModuleInterop

Esto creará una carpeta dist y, dentro de ella, un archivo index.js.

Carga el servidor MCP en Claude Desktop

Sigue esta guía para configurar el servidor MCP con Claude Desktop. En el archivo de configuración de Claude, tienes que establecer los siguientes valores:

{
  "mcpServers": {
    "elasticsearch-rag-mcp": {
      "command": "node",
      "args": [   "/Users/user-name/app-dir/dist/index.js"
      ],
      "env": {
        "ELASTICSEARCH_ENDPOINT": "your-endpoint-here",
        "ELASTICSEARCH_API_KEY": "your-api-key-here",
        "OPENAI_API_KEY": "your-openai-key-here"
      }
    }
  }
}

El valor args debe apuntar al archivo compilado en la carpeta dist. También es necesario configurar las variables de entorno en el archivo de configuración con los mismos nombres exactos definidos en el código.

Pruébalo

Antes de ejecutar cada herramienta, haz clic en Búsqueda y herramientas para asegurarte de que las herramientas estén habilitadas. Aquí también puedes habilitar o deshabilitar cada una de ellas:

Finalmente, probemos el servidor MCP desde el chat de Claude Desktop y comencemos a hacer preguntas:

Para la consulta"Buscar documentos sobre métodos de autenticación y control de acceso basado en roles", se ejecuta la herramienta search_docs y arroja los siguientes resultados:

Most Relevant Documents:
Access Control and Role Management (highest relevance) - This document covers role-based access control (RBAC) principles, including ensuring users only have necessary permissions, regular auditing of user roles, revoking inactive accounts, and implementing just-in-time access for sensitive operations.
User Authentication with OAuth 2.0 - This document explains OAuth 2.0 authentication, which enables secure delegated access without credential sharing. It covers configuring identity providers, token management with limited scope and lifetime, and secure storage of refresh tokens.
Container Security Guidelines - While primarily about container security, this document touches on access control aspects like running containers as non-root users and avoiding embedded credentials.
Incident Response Playbook - This mentions role assignment during incidents (incident commander, communications lead, etc.), which relates to access control in emergency scenarios.
Logging Standards for Microservices - This document includes guidance on avoiding logging sensitive information, which is relevant to authentication security.

La respuesta es: “¡Genial! Encontré 5 documentos relevantes sobre métodos de autenticación y control de acceso basado en roles. Esto es lo que se encontró:”

La llamada a la herramienta devuelve los documentos de origen como parte de su carga útil de respuesta, que luego se utilizan para generar citas.

También es posible encadenar varias herramientas en una sola interacción. En este caso, Claude Desktop analiza la pregunta del usuario y determina que primero debe llamar a search_docs para recuperar documentos relevantes y luego pasar esos resultados a summarize_and_cite para generar la respuesta final, todo eso sin requerir indicaciones separadas del usuario:

En este caso, para la búsqueda: "¿Cuáles son las principales recomendaciones para mejorar la autenticación y el control de acceso en todos nuestros sistemas? Incluye referencias.", obtuvimos los siguientes resultados:

Based on the documentation, here are the main recommendations to improve authentication and access control across your systems:

Key Recommendations

1. Implement Role-Based Access Control (RBAC)
Ensure users have only the permissions necessary for their job functions. This principle of least privilege minimizes security risks by limiting access to what's truly needed. [1]

2. Regular Access Audits
Conduct regular audits of user roles and promptly revoke access for inactive accounts. This helps prevent unauthorized access from dormant or compromised accounts. [1]

3. Just-in-Time (JIT) Access
Implement just-in-time access for sensitive operations, where permissions are granted only when needed and for a limited duration. This reduces the attack surface by minimizing standing privileges. [1]

4. OAuth 2.0 for Secure Authentication
Use OAuth 2.0 to enable secure delegated access without sharing user credentials. This protocol allows third-party applications to access resources on behalf of users without exposing passwords. [2]

5. Token Security and Management
Configure your identity provider to issue tokens with limited scope and lifetime

Store refresh tokens securely
Validate access tokens consistently to maintain security [2]
References

Access Control and Role Management (Tags: security, access-control)
User Authentication with OAuth 2.0 (Tags: authentication, oauth)
These recommendations work together to create a defense-in-depth approach, where multiple security layers protect your systems from unauthorized access.

Al igual que en el paso anterior, podemos ver la respuesta de cada herramienta a esta pregunta:

Nota: si aparece un submenú que pregunta si apruebas el uso de cada herramienta, selecciona Permitir siempre o Permitir una vez.

Conclusión

Los servidores MCP representan un paso significativo hacia la estandarización de las herramientas LLM para aplicaciones tanto locales como remotas. Aunque la compatibilidad total todavía está en proceso, nos estamos moviendo rápido en esa dirección.

En este artículo, aprendimos cómo construir un servidor MCP personalizado en TypeScript que conecta Elasticsearch con aplicaciones impulsadas por modelos LLM. Nuestro servidor expone dos herramientas: search_docs para recuperar documentos relevantes con Query DSL y summarize_and_cite para generar resúmenes con citas a través de modelos de OpenAI y Claude Desktop como client UI.

El futuro de la compatibilidad entre los distintos proveedores de clientes y servidores parece prometedor. Los próximos pasos consisten en agregar más funcionalidades y flexibilidad a tu agente. Hay un artículo práctico sobre cómo puedes agregar parámetros a tus consultas a través de plantillas de búsqueda para ganar precisión y flexibilidad.

Esa es exactamente la razón por la que construimos dashboards de solo lectura. Es el control que estabas pidiendo. Comparte dashboards con confianza, sin preocuparte de que la próxima persona con acceso de edición los cambie o rompa.

Nota: los permisos de solo lectura están disponibles en Elastic Cloud Serverless y, a partir de la versión 9.3, en Elastic Cloud Hosted y Elastic Cloud Self-Managed.

Cuando "todos pueden editar" se interpone en el camino

En Kibana, compartir generalmente ha significado permisos a nivel de espacio. Si alguien puede crear dashboards en un espacio, también puede editar o eliminar los de cualquier otro. Eso es excelente para la colaboración hasta que deja de serlo. Un solo error accidental puede propagarse en decisiones equivocadas, pérdida de confianza y mucho trabajo de limpieza.

Hemos escuchado las soluciones alternativas: "Ponemos 'solo lectura' en el nombre del dashboard y esperamos que la gente lo note". O: "Los etiquetamos y cruzamos los dedos". Hope no es un modelo de permiso. Necesitabas una manera real de bloquear un dashboard sin bloquear a todos y dejarlos fuera del espacio.

¿Qué sale mal realmente?

Tanto Deb como Kevin tienen acceso de edición al dashboard de monitoreo de logs dentro del espacio de Operaciones. Kevin realiza algunos cambios en los gráficos. Cuando Deb vuelve, los números no coinciden con lo que ella presentó. Tiene que rastrear qué cambió (a menudo de memoria), corregirlo y preguntarse cuántos reportes se enviaron con datos incorrectos.

Dashboards de solo lectura: propiedad y control que tienen sentido

Los dashboards de solo lectura resuelven esto dándote el control para decidir si otros usuarios pueden editar el dashboard. Al compartir un dashboard, eliges: edit (editar, predeterminado, igual que hoy) o view (ver). En el modo view (ver), solo tú (y los administradores de Kibana) pueden cambiarlo o eliminarlo. Todos los demás pueden abrirlo, usarlo y confiar en él, pero no pueden modificarlo.

Lo que obtienes

• Dashboard integrity: En el modo de visualización, los demás usuarios con acceso de edición en el espacio no pueden modificar ni eliminar el dashboard. Si lo intentan, se les indica que está bloqueado. Tus gráficos y lógica se mantienen tal como los dejaste.
• Mantienes el control: Tú eres el propietario. Siempre puedes editar, refinar y actualizar. Compartir en modo de solo lectura no te impide el acceso; restringe la versión que ven los demás.
• Ciclo de vida flexible: puedes volver a cambiar un dashboard a "puedes editar" en cualquier momento. Y los administradores de Kibana aún pueden gestionar todos los dashboards (por ejemplo, si el propietario se va). No hay callejón sin salida.

Puedes compartir ampliamente los dashboards finales críticos para la misión y saber que se mantendrán coherentes. Esto está disponible en todos los niveles y ofertas de Elastic, incluido Serverless.

¿Quién puede hacer qué?

Guía rápida por rol:

• Dashboard owner: Propietario del Dashboard. Tú lo creaste; tienes acceso completo de edición.
• Kibana admin: Administrador de Kibana. Puede administrar todos los dashboards.
• User with space edit: Usuario con edición de espacio. Puede crear y editar sus dashboards; no puede editar o eliminar dashboards de solo visualización.
• User with space view: Usuario con vista de espacio. Solo puede ver (y enumerar) dashboards.

Cómo activar el modo de solo lectura

Puedes configurar solo lectura cuando guardas un dashboard nuevo o más tarde desde el menú para compartir.

Al guardar un nuevo dashboard

• Construye tu dashboard y haz clic en Guardar.
• En el modal “Guardar como nuevo dashboard”, busca Permisos.
• Cambia de Can edit (Puede editar) a Can view (Puede ver).
• Haz clic en Save (Guardar). Listo. Es de solo lectura para todos los demás.

Para un dashboard que ya posees

• Abre el dashboard.
• Abre el menú Compartir dashboard.

• En el modal de compartir, ve a Permissions (Permisos) y cambia a Can view (Puede ver). El cambio entra en vigor de inmediato; los demás usuarios del espacio ya no podrán editarlo ni borrarlo.

• Puedes pasar el ratón sobre la acción Compartir para ver qué tipo de permisos tiene un dashboard determinado.

Ver qué dashboards están bloqueados

En la lista principal de dashboards, los dashboards que no puedes editar ni eliminar tienen una casilla de verificación de selección deshabilitada. Esto proporciona una forma sencilla de detectar lo que es solo de visualización.

En el dashboard, también encontrarás que la acción Editar está deshabilitada y aparecerá un mensaje emergente que explica que el dashboard se configuró como solo lectura.

Pruébalo

Los dashboards de solo lectura están disponibles ahora. Crea un dashboard, cambia a Can view (Puede ver) y compártelo. Tu equipo obtiene una única fuente de verdad, y tú obtienes tranquilidad. No más "por favor, no editar" en el título.

Nos encantaría saber cómo usas los dashboards de solo lectura. Comparte tus comentarios en nuestro foro de la comunidad.

Esta publicación vuelve a centrarse en la pregunta:¿Cuáles son las interfaces de búsqueda adecuadas que necesita un agente para construir su propio contexto? Primero, cubre las disyuntivas entre las herramientas de shell y las herramientas de base de datos especiales. A partir de ahí, te ofrece un marco de trabajo práctico para encontrar las interfaces adecuadas a las necesidades de tu agente.

¿Qué significa realmente "construir contexto" para un agente?

En las primeras pipelines de retrieval augmented generation (RAG), el desarrollador diseñó un pipeline de recuperación fija y el modelo de lenguaje grande (LLM) era un receptor pasivo del contexto. Esta era una limitación fundamental: el contexto se recuperaba en cada consulta, fuera o no necesario, sin verificar que realmente ayudara.

Con el cambio a la RAG agéntica, los agentes ahora tienen acceso a un conjunto de herramientas de búsqueda para crear su propio contexto. Por ejemplo, tanto Claude Code [1] como Cursor [2] permiten que el agente elija entre diferentes herramientas de búsqueda e incluso las combine para consultas encadenadas, dependiendo de lo que la tarea realmente requiera.

¿Qué interfaces de búsqueda existen para la ingeniería del contexto?

El contexto puede estar en diferentes lugares, como en la web, en un sistema de archivos local o en una base de datos. Un agente puede interactuar con cada una de estas fuentes de datos fuera de contexto mediante diferentes herramientas:

• Las herramientas de shell pueden ejecutar comandos de shell y tener acceso al sistema de archivos local. Algunos ejemplos de herramientas de shell integradas son la herramienta bash de Claude API, la herramienta ejecutiva de OpenClaw y la herramienta de shell de LangChain.
• Las herramientas de base de datos especiales, como las herramientas de un servidor Model Context Protocol (MCP) (p. ej., el servidor MCP de Elastic Agent Builder) o las herramientas personalizadas (p. ej., run_esql(query) o db_list_index()), pueden consultar bases de datos.
• Las herramientas especiales de búsqueda de archivos pueden buscar y leer archivos locales (o subidos) (sin acceso completo al shell). Algunos ejemplos de herramientas de búsqueda de archivos integradas son Herramienta de búsqueda de archivos de Gemini API o Herramienta de búsqueda de archivos de OpenAI.
• Las herramientas de búsqueda web pueden recuperar información de la web.
• Las herramientas de memoria almacenan y recuperan de la memoria a largo plazo (independientemente de cómo se almacene).

Como puedes ver, la herramienta shell es versátil y se puede usar para recuperar contexto de diferentes fuentes de datos, incluyendo:

• Sistema de archivos: el agente explora la estructura de directorios (ls, find), busca contenido relevante (grep, cat) y repite hasta que ha construido suficiente contexto.
• Base de datos: el agente puede usar herramientas de interfaz de línea de comandos (CLI) para bases de datos (por ejemplo, elasticsearch-sql-cli), llamar al HTTP de la API mediante curl o ejecutar scripts, lo cual resulta especialmente útil en combinación con las habilidades del agente, que son ejemplos reutilizables y documentados que se incorporan al contexto del agente para guiar el uso correcto de las herramientas (por ejemplo, Elastic Agent Skills para Elasticsearch).
• Web: el agente puede ejecutar búsquedas web mediante un comando curl a través de la API de un proveedor de búsqueda.

Sin embargo, la herramienta de shell proporciona acceso directo al sistema y, por lo tanto, requiere medidas de seguridad, como ejecutarse en un entorno sandbox aislado y el logging de todos los comandos ejecutados.

Cuándo deberías usar ciertas interfaces de búsqueda

La interfaz de búsqueda adecuada depende de tus datos, tus patrones de consulta y tu caso de uso. Esta sección sirve como un punto de partida práctico.

Los sistemas de archivos no hacen que las bases de datos sean obsoletas.

La discusión entre sistemas de archivos y bases de datos no es sobre la capa de almacenamiento. Por ejemplo, LangChain explica que su sistema de memoria en realidad no almacena la memoria en un verdadero sistema de archivos. En su lugar, almacena la memoria en una base de datos y la representa como un conjunto de archivos para el agente [3].

Los sistemas de archivos son una opción natural para casos de uso nativos de archivos, como los agentes de codificación. También funcionan bien como bloc de notas temporal o memoria de trabajo, y en situaciones con un solo usuario o un solo agente en las que la concurrencia no es un problema. En estos casos, un sistema de archivos físico o representar los datos como un sistema de archivos te da flexibilidad antes de comprometerte con una interfaz diseñada específicamente para ello.

Pero el almacenamiento en sistemas de archivos tiene desventajas reales, como una concurrencia limitada, la aplicación manual de esquemas y las transacciones atómicas. Estos se vuelven más evidentes cuando tu aplicación necesita escalar o pasar a un escenario de múltiples agentes. Cualquiera que ignore estas desventajas está condenado a reinventar dolorosamente bases de datos peores sin las décadas de ingeniería detrás de la seguridad de transacciones o el control de acceso que las bases de datos de producción ya proporcionan. Además, en la mayoría de contextos empresariales, no eliges si usar una base de datos porque ya está ahí, almacenando datos críticos para el negocio.

Herramienta de shell + sistema de archivos

Una herramienta shell es el punto de partida natural para la búsqueda en sistemas de archivos. En la actualidad, los agentes de codificación están impulsando muchos avances en este campo. Como trabajan con código en archivos locales, son, por naturaleza, casos de uso que implican un gran volumen de archivos. Por lo tanto, los LLM se ajustan en la etapa posterior al entrenamiento para tareas de codificación. Es por eso que muchos LLMs no solo son buenos para escribir código, sino también para usar comandos de shell y navegar por sistemas de archivos.

Usar una herramienta de shell con CLI integradas, como ls y grep, para encontrar archivos es efectivo. Con grep, una consulta como "Encontrar todos los archivos que importan matplotlib" es rápida, precisa y económica. Pero cuando el agente necesita manejar consultas conceptuales, como "¿Cómo maneja nuestra app la falla de autenticación?", la coincidencia de patrones con grep puede alcanzar un límite rápidamente. Han surgido varias alternativas que incorporan capacidades de búsqueda semántica a la línea de comandos para cubrir esta carencia, incluidas jina-grep.

Sin embargo, grep y muchas de sus alternativas de búsqueda semántica se ejecutan en O(n) sobre el corpus. Para casos de uso sobre bases de código, esto podría estar bien. Sin embargo, si tus datos crecen, la latencia se notará. En este caso, un almacén de datos indexado se vuelve necesario para mantener el rendimiento.

Herramienta de shell + base de datos

Otra forma de agregar más capacidades de búsqueda, como la búsqueda semántica o híbrida, a tus datos es almacenarlos en una base de datos, como hace Cursor, por ejemplo. Además, cuando los datos requieren uniones relacionales o agregaciones complejas, una interfaz de base de datos es imprescindible.

Cuando los datos se almacenan en una base de datos en lugar de en el sistema de archivos, una herramienta de shell puede servir como una interfaz ligera de base de datos para ciertos casos de uso. Si tus consultas son lo suficientemente simples para una CLI o una llamada curl, una herramienta de base de datos especial podría añadir una complejidad innecesaria.

Este enfoque también es adecuado en las etapas iniciales de exploración, cuando aún no sabes qué patrones de consulta desarrollará tu agente. En este caso, Agent Skills puede darle al agente suficiente estructura para consultar correctamente sin comprometerse con una herramienta específica. Sin embargo, cuando el agente requiere muchas iteraciones para encontrar la forma correcta de consultar en la base de datos para tareas repetidas, la sobrecarga de tokens de usar una herramienta de línea de comandos como interfaz ya no justifica el beneficio de la simplicidad de evitar una herramienta adicional.

Herramienta especial de base de datos

Especialmente cuando los patrones de consulta repetidos son estructurados o analíticos, se hacen necesarias herramientas de base de datos especiales. Una publicación de blog de Vercel y Braintrust comparó a los agentes con diferentes conjuntos de herramientas de búsqueda para tareas de recuperación del mundo real en lugar de datos estructurados, como tickets de atención al cliente y transcripciones de llamadas de ventas (por ejemplo, “¿Cuántos problemas abiertos mencionan 'seguridad'?" o "¿Encontraste problemas en los que alguien reportó un error y luego alguien envió un PR diciendo que lo había arreglado?") [4].

Los agentes con herramientas de base de datos especiales utilizaron menos tokens, fueron más rápidos y cometieron menos errores que los agentes con solo una herramienta de shell y un sistema de archivos. La conclusión es que las herramientas de bases de datos directas son la opción correcta cuando la consulta requiere razonamiento analítico sobre datos semiestructurados.

Combinar interfaces de búsqueda

Ninguna interfaz de búsqueda gestiona bien todas las consultas. Por ejemplo, Cursor combina herramientas de shell (para búsquedas con grep) y herramientas de búsqueda semántica, y permite que el agente seleccione la herramienta correcta según el mensaje del usuario. Informa que el agente elige grep para hacer coincidir símbolos o textos específicos, búsqueda semántica para preguntas conceptuales o de comportamiento, y ambos para tareas exploratorias.

El experimento de Vercel presenta el mismo reporte: su agente híbrido con acceso tanto a una herramienta de shell como a una herramienta dedicada para bases de datos logró el mejor rendimiento de todos los agentes probados al usar primero las herramientas dedicadas para bases de datos y luego verificar los resultados mediante búsquedas con grep en el sistema de archivos. Sin embargo, este enfoque utiliza más tokens y tiempo para razonar sobre la elección de herramientas y la verificación.

El patrón en ambos ejemplos es el mismo: La combinación es superior a cualquier interfaz individual, pero conlleva un costo y una latencia adicionales.

Recomendaciones prácticas para encontrar el conjunto adecuado de herramientas

El conjunto adecuado de interfaces de búsqueda es pequeño, intencionado y específico para los patrones de consulta reales de tu agente. Las mejores prácticas actuales son tener un agente con la menor cantidad de herramientas posible en lugar de tener un agente con cientos de herramientas MCP. Esto se debe a que la desventaja de exponer todas las herramientas posibles de antemano es que infla la ventana de contexto y confunde al agente sobre qué herramienta usar realmente. Por ejemplo, se dice que Claude Code solo tiene unas 20 herramientas.

En cambio, la idea de la divulgación progresiva es comenzar con un conjunto mínimo de herramientas y dejar que el agente descubra capacidades adicionales solo cuando sea necesario. Investigaciones de Anthropic [5] y Cursor [6] demostraron que este enfoque genera un ahorro de tokens entre el 47%–85%. Claude Code, por ejemplo, implementa esto directamente, lo que permite al agente descubrir de forma incremental cómo consultar una API o una base de datos, sin que ese conocimiento consuma contexto en cada llamada al LLM.

Una vez que te familiarices con los patrones de búsqueda del agente, puedes volver a revisar el conjunto de herramientas de búsqueda a las que el agente tiene acceso de forma predeterminada. Una forma útil de pensar en este compromiso es el "principio de piso bajo, techo alto" para decidir qué herramientas son las adecuadas. Las herramientas de alto nivel no limitan el potencial del agente. Por ejemplo, una herramienta de shell versátil permite al agente escribir consultas de base de datos completas, incluidas las ambiguas, pero a costa de una mayor sobrecarga de razonamiento, latencia más alta y menor confiabilidad.

Las herramientas de bajo umbral son todo lo contrario. Son herramientas especializadas que encapsulan búsquedas específicas y son inmediatamente accesibles para el agente con una mínima sobrecarga de razonamiento, ofreciendo menor costo y mayor confiabilidad. No obstante, requieren ingeniería previa, no pueden cubrir cada posible consulta y pueden dificultar que el agente elija la herramienta correcta.

Piensa en cada herramienta en un espectro: las herramientas de bajo nivel son fáciles de usar correctamente para el agente, pero tienen un alcance limitado. Las herramientas de alto potencial son versátiles pero requieren más razonamiento para usarlas bien.

La mayoría de los agentes necesitan una combinación de diferentes herramientas de búsqueda. Pero cada herramienta necesita aportar algo. Recomendamos comenzar con una herramienta de búsqueda multiuso (por ejemplo, una herramienta search_database() o una herramienta de shell). Luego, reutiliza los registros de comandos que ya conservas por motivos de seguridad para rastrear lo que realmente hace tu agente, incluidas las llamadas a herramientas, los reintentos y el número de llamadas por consulta de usuario. Y, cuando ves que un patrón de consulta se repite o falla, esa es la señal para construir una herramienta especialmente diseñada para ello.

Resumen

El debate entre sistema de archivos y base de datos distrae de la pregunta real que los ingenieros deben hacerse: ¿Cuáles son las interfaces de búsqueda adecuadas que un agente necesita para construir su propio contexto? La respuesta es muy probable, no una sola.

Una herramienta de shell es una herramienta versátil para interactuar con diferentes fuentes fuera de contexto y, por lo tanto, un buen punto de partida. Sin embargo, resulta menos eficiente y precisa para casos de uso con consultas analíticas estructuradas que las herramientas de bases de datos especializadas.

El objetivo es encontrar el conjunto mínimo de herramientas de búsqueda que manejen bien los patrones reales de consulta de tu agente. Empieza con una herramienta de shell y registra lo que realmente hace tu agente. Cuando veas un patrón de consulta que se repite y falla, es momento de diseñar herramientas especializadas.

Referencias

1. Thariq (Anthropic). Lessons from Building Claude Code: Seeing like an Agent (2026).

2. Cursor: Documentation. Semantic & agentic search (2026).

3. Harrison Chase (LangChain). Cómo construimos el sistema de memoria de Agent Builder (2026).

4. Ankur Goyal (Braintrust) y Andrew Qu (Vercel). Testing if "bash is all you need" (2026).

5. Anthropic. Introducing advanced tool use on the Claude Developer Platform (2025).

6. Cursor. Dynamic context discovery (2026).

La fiesta se está llenando de gente

Organizas una fiesta de pizzas. Tienes a unos cuantos amigos que te ayudan a servirlas, cada uno en un lugar distinto de la sala. Le das a cada amigo una pizza y ellos empiezan a repartir rebanadas a los invitados hambrientos a medida que llegan.

Al principio, todo marcha sin problemas. Unos cuantos invitados van llegando de a poco, tus amigos sirven porciones y todos están contentos. Pero entonces se corre la voz sobre tus pizzas de masa madre. El timbre sigue sonando. Los invitados siguen llegando en masa. Pronto se forma una multitud alrededor de uno de tus amigos, el que lleva la pizza de pepperoni, que parece ser la que quieren todos.

Tu amigo con la pizza de pepperoni está abrumado. Los invitados están esperando, se ponen impacientes y se formó una larga cola. Mientras tanto, tu amiga que sostiene la pizza margherita está de pie con casi nadie pidiéndole una porción.

¿Qué haces?

Pides un par de pizzas de pepperoni más y se las das a otros amigos. Ahora tres amigos tienen pepperoni en lugar de uno. La multitud se dispersa y, de repente, puedes atender a tres veces más invitados a la vez.

A medida que organizas más fiestas, hay algunas cosas que se vuelven claras:

• No todas las pizzas son igual de populares. Algunas tienen mucha demanda; otras tienen menos interesados. No necesitas "copias" adicionales de las menos populares. Necesitas más de las que todos esperan en cola.
• Pide más pizzas antes de que la fila se haga demasiado larga. Si esperas hasta que tu amigo esté completamente abrumado y los invitados se estén yendo enojados, esperaste demasiado tiempo. Es mejor pedir una pizza más cuando ves que se está formando una multitud.
• No deseches las pizzas demasiado rápido. Solo porque la multitud alrededor del pepperoni se redujo durante cinco minutos no significa que la avalancha haya terminado. Tal vez solo están sirviéndose bebidas, o incluso hablando entre ellos (¿eso todavía se hace?). Mantén las pizzas adicionales listas. Si la calma se mantiene por un rato, entonces puedes guardarlas.
• Solo puedes repartir tantas pizzas como amigos tengas que te estén ayudando. Si solo tienes cuatro amigos ayudándote, diez pizzas no cambiarán el resultado. Solo se pueden servir cuatro a la vez. Haz coincidir tu cantidad de pizzas con tus manos disponibles.
• Cuando un amigo se vaya, llévate su pizza. Si uno de tus amigos necesita salir, toma su pizza inmediatamente. No puedes dejar las pizzas sin supervisión. Dásela a otra persona, o guárdala.

Desde pizzas hasta réplicas

Vamos a mapear esto de vuelta a Elasticsearch.

En nuestra analogía, las pizzas son réplicas (copias de tus fragmentos de índice), tus colegas ayudando a servir son nodos de búsqueda, los invitados hambrientos son consultas de búsqueda, y esa pizza popular con mucha gente alrededor es un índice caliente con alta carga de búsqueda.

Cuando el tráfico de búsqueda aumenta en un índice en particular, creamos réplicas adicionales y las distribuimos en tus nodos de búsqueda. Cualquier réplica puede responder a cualquier consulta sobre ese índice, igual que cualquier amigo que tenga pepperoni puede repartir rebanadas de pepperoni. Más réplicas significan un mayor rendimiento: tres réplicas pueden manejar tres veces las consultas por segundo de una sola réplica.

Medir el hambre

Antes de decidir cuántas pizzas pedir, necesitamos saber qué tan hambrienta está la multitud.

Elasticsearch rastrea la carga de búsqueda de cada fragmento. Es una métrica que mide el volumen de actividad de búsqueda que gestiona un fragmento. Sumamos estos datos de todos los fragmentos de un índice para conocer la demanda total de búsquedas.

Lo que más importa es la carga de búsqueda relativa: ¿qué proporción del tráfico de búsqueda total de tu proyecto está llegando a cada índice? Si un índice recibe el 60 % de todas las búsquedas mientras que otro recibe el 5 %, sabemos dónde debemos aumentar la capacidad.

La matemática detrás de las pizzas

Calculamos el número óptimo de réplicas siguiendo esta fórmula:

desired_replicas = min(ceil(L × N / (S × X)), N)

Dónde:

• L = la carga de búsqueda relativa del índice (entre 0 y 1).
• N = el número de nodos de búsqueda deseados en tu proyecto.
• S = la cantidad de fragmentos en el índice.
• X = un umbral para evitar puntos calientes (predeterminado: 0,5).

Un ejemplo: cuatro nodos de búsqueda, un índice con dos fragmentos primarios que reciben el 80 % del tráfico de búsqueda:

desired_replicas = min(ceil(0.8 × 4 / (2 × 0.5)), 4)
                 = min(4, 4)
                 = 4

Este índice activo tiene cuatro réplicas distribuidas entre los nodos de búsqueda.

El umbral X (con un valor predeterminado de 0,5) es importante. No esperamos hasta que una réplica esté completamente saturada, sino que escalamos cuando está a la mitad de su capacidad. Reparte la pizza adicional cuando veas que la multitud empieza a formarse, no cuando los invitados ya se están yendo.

Escala rápido, reduce la escala lentamente

Cuando aumenta la carga de búsqueda, agregamos réplicas inmediatamente. No hay razón para hacer esperar a los usuarios.

Cuando la carga de búsqueda disminuye, esperamos un poco antes de tomar alguna acción. Necesitamos ver una demanda baja constante durante unos 30 minutos antes de reducir las réplicas. (Esto es para manejar el tráfico irregular donde un momento de calma no significa que la fiesta haya terminado.)

Esto importa porque agregar una réplica tiene un costo. La réplica nueva copia datos y calienta sus cachés antes de servir las consultas de manera eficiente. Si eliminas las réplicas con demasiada prisa, terminarás pagando este costo inicial constantemente, ya que el tráfico fluctúa de forma natural.

Respetando los límites de la topología

Las réplicas nunca pueden superar el número de nodos de búsqueda. Tener más réplicas que nodos no aporta ningún beneficio (solo puedes servir tantas pizzas como colegas que ayuden a servir las porciones).

Cuando se eliminan nodos de tu proyecto, reducimos las réplicas inmediatamente para que coincidan. Sin esperar el enfriamiento, ya que no puedes tener réplicas sin asignar. En cuanto un usuario se va, le quitamos la pizza.

El panorama general de Elastic Cloud Serverless

Las réplicas para el balanceo de carga de búsqueda funcionan junto con otros sistemas de autoescalado:

• El escalado automático de búsqueda ajusta el número de nodos de búsqueda (cuántos amigos están ayudando).
• Las réplicas para el balanceo de carga de búsqueda distribuyen el tráfico al ajustar la cantidad de réplicas por índice (cuántas pizzas de cada tipo necesitamos).
• La fragmentación automática de flujos de datos optimiza el número de particiones para las operaciones de escritura (cómo cortar cada pizza, como se explicó en la publicación anterior).

Un principio de diseño importante: las réplicas para el equilibrio de carga no activan directamente el escalado automático de búsqueda. En cambio, distribuir las consultas de búsqueda entre más réplicas permite aumentar la utilización de recursos en todos tus nodos de búsqueda. Este mayor uso luego activa nuestra lógica de escalado automático existente para agregar capacidad si es necesario. Las réplicas para el balanceo de carga permiten que el autoescalado haga su trabajo, lo que asegura que tus nodos de búsqueda realmente se estén utilizando, en lugar de que todo el tráfico esté bloqueado en una sola réplica mientras otros nodos permanecen inactivos.

Qué significa esto para ti

No necesitas predecir qué índices serán populares. No necesitas ajustar manualmente las réplicas cuando cambian los patrones de tráfico. No necesitas despertarte a las 3 a. m. porque un aumento repentino sobrecargó tu índice más ocupado.

El sistema observa dónde se están formando colas y pide más pizzas para esos lugares. Los índices fríos no desperdician recursos en réplicas innecesarias. Los índices calientes obtienen la capacidad que necesitan. Tu presupuesto se destina a donde importa.

Conclusión

En la publicación sobre la autofragmentación (autosharding) nos aseguramos de que tus pizzas estén cortadas correctamente. Ahora, con réplicas para el equilibrio de carga de búsqueda, nos aseguramos de que tengas suficientes pizzas, en las manos adecuadas, cuando llegue la multitud hambrienta.

Prueba Elastic Cloud Serverless y déjanos encargarnos de la logística de la pizza.

Requisitos previos

• Elasticsearch 9.3 o Elastic Cloud Serverless: puedes crear un despliegue en la cloud siguiendo estas instrucciones, o bien puedes utilizar la guía de inicio rápido de start-local.
• Python 3.12: Descarga Python aquí.
• Token de acceso Hugging Face.

Finalización de chat usando un endpoint de inferencia de Hugging Face

Primero, vamos a crear un ejemplo práctico que conecte Elasticsearch con un endpoint de inferencia de Hugging Face para generar recomendaciones basadas en IA a partir de una colección de publicaciones de blog. Para la base de conocimientos de la app, usaremos un set de datos de artículos del blog de la compañía, que contiene información valiosa pero a menudo difícil de navegar.

Con este endpoint, la búsqueda semántica recupera los artículos más relevantes para una consulta dada, y un LLM de Hugging Face genera recomendaciones breves y contextuales basadas en esos resultados.

Echemos un vistazo a una visión general de alto nivel del flujo de información que vamos a construir:

En este artículo, probaremos la capacidad de SmolLM3-3B para combinar su tamaño compacto con fuertes capacidades multilingües de razonamiento y llamadas a herramientas. A partir de una búsqueda, enviaremos todo el contenido correspondiente (en inglés y español) al LLM para generar una lista de artículos recomendados con una descripción personalizada basada en la búsqueda y los resultados.

Así podría ser la UI de un sitio web de artículos con un sistema de generación de recomendaciones basado en inteligencia artificial.

Puedes encontrar la implementación completa de esta aplicación en el cuaderno adjunto.

Configurar endpoints de inferencia de Elasticsearch

Para usar el endpoint de inferencia Elasticsearch Hugging Face, necesitamos dos elementos importantes: una clave API de Hugging Face y una URL del endpoint de Hugging Face en funcionamiento. Debería verse así:

PUT _inference/chat_completions/hugging-face-smollm3-3b
{
    "service": "hugging_face",
    "service_settings": {
        "api_key": "hugging-face-access-token", 
        "url": "url-endpoint" 
    }
}

El endpoint de inferencia Hugging Face en Elasticsearch admite diferentes tipos de tareas: text_embedding, completion, chat_completion y rerank. En esta publicación de blog, usamos chat_completion porque necesitamos que el modelo genere recomendaciones conversacionales basadas en los resultados de búsqueda y una solicitud del sistema. Este endpoint nos permite realizar finalizaciones de chat directamente desde Elasticsearch de una manera sencilla empleando la API de Elasticsearch:

POST _inference/chat_completion/hugging-face-smollm3-3b/_stream
{
  "messages": [
      { "role": "user", "content": "" }
  ]
}

Esto servirá como núcleo de la aplicación, recibirá la indicación y los resultados de búsqueda que pasarán por el modelo. Ya abordamos la teoría, ahora comencemos a implementar la aplicación.

Configuración de un endpoint de inferencia en Hugging Face

Para desplegar el modelo de Hugging Face, vamos a usar despliegues con un clic de Hugging Face, un servicio fácil y rápido para desplegar endpoints de modelos. Ten en cuenta que este es un servicio de pago y que su uso puede generar costos adicionales. En este paso se creará la instancia del modelo que se usará para generar las recomendaciones de artículos.

Puedes elegir un modelo del catálogo de un clic:

Vamos a elegir el modelo SmolLM3-3B:

Desde aquí, copia la URL del endpoint de Hugging Face:

Como se menciona en la documentación de endpoints de inferencia Hugging Face de Elasticsearch, la generación de texto requiere un modelo compatible con la API de OpenAI. Por esa razón, necesitamos anexar la ruta secundaria /v1/chat/completions a la URL del endpoint de Hugging Face. El resultado final se verá así:

https://j2g31h0futopfkli.us-east-1.aws.endpoints.huggingface.cloud/v1/chat/completions

Ahora que está todo listo, podemos empezar a programar en un cuaderno de Python.

Generando clave API de Hugging Face

Crea una cuenta en Hugging Face y obtén un token de API siguiendo estas instrucciones. Puedes elegir entre tres tipos de token: detallado (recomendado para producción, ya que proporciona acceso solo a recursos específicos); lectura (para acceso de solo lectura); o escritura (para acceso de lectura y escritura). Para este tutorial, un token de lectura es suficiente, ya que solo necesitamos llamar al endpoint de inferencia. Guarda esta clave para el siguiente paso.

Configuración del endpoint de inferencia de Elasticsearch

Primero, declaremos un cliente de Python para Elasticsearch:

os.environ["ELASTICSEARCH_API_KEY"] = "your-elasticsearch-api-key"
os.environ["ELASTICSEARCH_URL"] = "https://xxxx.us-central1.gcp.cloud.es.io:443"

es_client = Elasticsearch(
    os.environ["ELASTICSEARCH_URL"], api_key=os.environ["ELASTICSEARCH_API_KEY"]
)

A continuación, vamos a crear un endpoint de inferencia de Elasticsearch que use el modelo Hugging Face. Este endpoint nos permitirá generar respuestas basadas en las entradas del blog y en el prompt que se pasó al modelo.

INFERENCE_ENDPOINT_ID = "smollm3-3b-pnz"

os.environ["HUGGING_FACE_INFERENCE_ENDPOINT_URL"] = (
 "https://j2g31h0futopfkli.us-east-1.aws.endpoints.huggingface.cloud/v1/chat/completions"
)
os.environ["HUGGING_FACE_API_KEY"] = "hf_xxxxx"

resp = es_client.inference.put(
        task_type="chat_completion",
        inference_id=INFERENCE_ENDPOINT_ID,
        body={
            "service": "hugging_face",
            "service_settings": {
                "api_key": os.environ["HUGGING_FACE_API_KEY"],
                "url": os.environ["HUGGING_FACE_INFERENCE_ENDPOINT_URL"],
            },
        },
    )

Set de datos

El conjunto de datos contiene las publicaciones de blog que se consultarán, representando un conjunto de contenido multilingüe utilizado a lo largo del flujo de trabajo:

// Articles dataset document example: 
{
    "id": "6",
    "title": "Complete guide to the new API: Endpoints and examples",
    "author": "Tomas Hernandez",
    "date": "2025-11-06",
    "category": "tutorial",
    "content": "This guide describes in detail all endpoints of the new API v2. It includes code examples in Python, JavaScript, and cURL for each endpoint. We cover authentication, resource creation, queries, updates, and deletion. We also explain error handling, rate limiting, and best practices. Complete documentation is available on our developer portal."
  }

Mappings de Elasticsearch

Una vez definido el set de datos, necesitamos crear un esquema de datos que se ajuste correctamente a la estructura de la publicación de blog. Se emplearán las siguientes mappings de índices para almacenar los datos en Elasticsearch:

INDEX_NAME = "blog-posts"

mapping = {
    "mappings": {
        "properties": {
            "id": {"type": "keyword"},
            "title": {
                "type": "object",
                "properties": {
                    "original": {
                        "type": "text",
                        "copy_to": "semantic_field",
                        "fields": {"keyword": {"type": "keyword"}},
                    },
                    "translated_title": {
                        "type": "text",
                        "fields": {"keyword": {"type": "keyword"}},
                    },
                },
            },
            "author": {"type": "keyword", "copy_to": "semantic_field"},
            "category": {"type": "keyword", "copy_to": "semantic_field"},
            "content": {"type": "text", "copy_to": "semantic_field"},
            "date": {"type": "date"},
            "semantic_field": {"type": "semantic_text"},
        }
    }
}


es_client.indices.create(index=INDEX_NAME, body=mapping)

Aquí, podemos ver mejor cómo se estructuran los datos. Usaremos la búsqueda semántica para recuperar resultados basados en lenguaje natural, junto con la propiedad copy_to para copiar el contenido del campo en el campo semantic_text. Además, el campo title contiene dos subcampos: el subcampo original almacena el título en inglés o español, dependiendo del idioma original del artículo; y el subcampo translated_title está presente solo para artículos en español y contiene la traducción al inglés del título original.

Ingesta de datos

El siguiente fragmento de código ingesta el conjunto de datos de las publicaciones de blog en Elasticsearch mediante la API de bulk:

def build_data(json_file, index_name):
    with open(json_file, "r") as f:
        data = json.load(f)

    for doc in data:
        action = {"_index": index_name, "_source": doc}
        yield action


try:
    success, failed = helpers.bulk(
        es_client,
        build_data("dataset.json", INDEX_NAME),
    )
    print(f"{success} documents indexed successfully")

    if failed:
        print(f"Errors: {failed}")
except Exception as e:
    print(f"Error: {str(e)}")

Ahora que tenemos los artículos ingeridos en Elasticsearch, necesitamos crear una función capaz de buscar en el campo semantic_text :

def perform_semantic_search(query_text, index_name=INDEX_NAME, size=5):
    try:
        query = {
            "query": {
                "match": {
                    "semantic_field": {
                        "query": query_text,
                    }
                }
            },
            "size": size,
        }

        response = es_client.search(index=index_name, body=query)
        hits = response["hits"]["hits"]

        return hits
    except Exception as e:
        print(f"Semantic search error: {str(e)}")
        return []

También necesitamos una función que llame al endpoint de inferencia. En este caso, llamaremos al endpoint usando el tipo de tarea chat_completion para obtener respuestas de transmisión:

def stream_chat_completion(messages: list, inference_id: str = INFERENCE_ENDPOINT_ID):
    url = f"{ELASTICSEARCH_URL}/_inference/chat_completion/{inference_id}/_stream"
    payload = {"messages": messages}
    headers = {
        "Authorization": f"ApiKey {ELASTICSEARCH_API_KEY}",
        "Content-Type": "application/json",
    }

    try:
        response = requests.post(url, json=payload, headers=headers, stream=True)
        response.raise_for_status()

        for line in response.iter_lines(decode_unicode=True):
            if line:
                line = line.strip()

                if line.startswith("event:"):
                    continue

                if line.startswith("data: "):
                    data_content = line[6:]

                    if not data_content.strip() or data_content.strip() == "[DONE]":
                        continue

                    try:
                        chunk_data = json.loads(data_content)

                        if "choices" in chunk_data and len(chunk_data["choices"]) > 0:
                            choice = chunk_data["choices"][0]
                            if "delta" in choice and "content" in choice["delta"]:
                                content = choice["delta"]["content"]
                                if content:
                                    yield content

                    except json.JSONDecodeError as json_err:
                        print(f"\nJSON decode error: {json_err}")
                        print(f"Problematic data: {data_content}")
                        continue

    except requests.exceptions.RequestException as e:
        yield f"Error: {str(e)}"

Ahora podemos escribir una función que llame a la función de búsqueda semántica, junto con el endpoint de inferencia chat_completions y el endpoint de recomendaciones, para generar los datos que se asignarán en las tarjetas:

def recommend_articles(search_query, index_name=INDEX_NAME, max_articles=5):
    print(f"\n{'='*80}")
    print(f"🔍 Search Query: {search_query}")
    print(f"{'='*80}\n")

    articles = perform_semantic_search(search_query, index_name, size=max_articles)

    if not articles:
        print("❌ No relevant articles found.")
        return None, None

    print(f"✅ Found {len(articles)} relevant articles\n")

    # Build context with found articles
    context = "Available blog articles:\n\n"
    for i, article in enumerate(articles, 1):
        source = article.get("_source", article)
        context += f"Article {i}:\n"
        context += f"- Title: {source.get('title', 'N/A')}\n"
        context += f"- Author: {source.get('author', 'N/A')}\n"
        context += f"- Category: {source.get('category', 'N/A')}\n"
        context += f"- Date: {source.get('date', 'N/A')}\n"
        context += f"- Content: {source.get('content', 'N/A')}\n\n"

    system_prompt = """You are an expert content curator that recommends blog articles.

    Write recommendations in a conversational style starting with phrases like:
    - "If you're interested in [topic], this article..."
    - "This post complements your search with..."
    - "For those looking into [topic], this article provides..."


    FORMAT REQUIREMENTS:
    - Return ONLY a JSON array
    - Each element must have EXACTLY these three fields: "article_number", "title", "recommendation"
    - If the original title is in spanish, use the "translated_title" subfield in the "title" field

    Keep each recommendation concise (2-3 sentences max) and focused on VALUE to the reader.

    EXAMPLE OF CORRECT FORMAT:
    [
        {"article_number": 1, "title": "Article title in english", "recommendation": "If you are interested in [topic], this article provides..."},
        {"article_number": 2, "title": "Article title in english", "recommendation": " for those looking into [topic], this article provides..."}
    ]

    Return ONLY the JSON array following this exact structure."""

    user_prompt = f"""Search query: "{search_query}"

    Generate recommendations for the following articles: {context}
    """

    messages = [
        {"role": "system", "content": "/no_think"},
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": user_prompt},
    ]

    # LLM generation
    print(f"{'='*80}")
    print("🤖 Generating personalized recommendations...\n")

    full_response = ""

    for chunk in stream_chat_completion(messages):
        print(chunk, end="", flush=True)
        full_response += chunk

    return context, articles, full_response

Por último, extrae la información y dale formato para imprimirla:

def display_recommendation_cards(articles, recommendations_text):
    print("\n" + "=" * 100)
    print("📇 RECOMMENDED ARTICLES".center(100))
    print("=" * 100 + "\n")

    # Parse JSON recommendations - clean tags and extract JSON
    recommendations_list = []
    try:

        # Clean up  tags
        cleaned_text = re.sub(
            r".*?", "", recommendations_text, flags=re.DOTALL
        )
        # Remove markdown code blocks ( ... ``` or ``` ... ```)
        cleaned_text = re.sub(r"```(?:json)?", "", cleaned_text)
        cleaned_text = cleaned_text.strip()

        parsed = json.loads(cleaned_text)

        # Extract recommendations from list format
        for item in parsed:
            article_number = item.get("article_number")
            title = item.get("title", "")
            rec_text = item.get("recommendation", "")

            if article_number and rec_text:
                recommendations_list.append(
                    {
                        "article_number": article_number,
                        "title": title,
                        "recommendation": rec_text,
                    }
                )
    except json.JSONDecodeError as e:
        print(f"⚠️  Could not parse recommendations as JSON: {e}")
        return

    for i, article in enumerate(articles, 1):
        source = article.get("_source", article)

        # Card border
        print("┌" + "─" * 98 + "┐")

        # Find recommendation and title for this article number
        recommendation = None
        title = None
        for rec in recommendations_list:
            if rec.get("article_number") == i:
                recommendation = rec.get("recommendation")
                title = rec.get("title")
                break

        # Print title
        title_lines = textwrap.wrap(f"📌 {title}", width=94)
        for line in title_lines:
            print(f"│  {line}".ljust(99) + "│")

        # Card border
        print("├" + "─" * 98 + "┤")

        # Print recommendation
        if recommendation:
            recommendation_lines = textwrap.wrap(recommendation, width=94)
            for line in recommendation_lines:
                print(f"│  {line}".ljust(99) + "│")

        # Card bottom
        print("└" + "─" * 98 + "┘")

Pongámoslo a prueba haciendo una pregunta sobre las publicaciones de blog de seguridad:

search_query = "Security and vulnerabilities"

context, articles, recommendations = recommend_articles(search_query)

print("\nElasticsearch context:\n", context)

# Display visual cards
display_recommendation_cards(articles, recommendations)

Aquí podemos ver las tarjetas de la consola generadas por el flujo de trabajo:

Puedes ver los resultados completos, incluso todas las coincidencias y la respuesta del LLM, en este archivo.

Estamos solicitando artículos relacionados con: “Seguridad y vulnerabilidades”. Esta pregunta se emplea como consulta de búsqueda en los documentos almacenados en Elasticsearch. Los resultados obtenidos se pasan al modelo, el cual genera recomendaciones basadas en su contenido. Como podemos ver, el modelo hizo un excelente trabajo generando textos cortos y atractivos que pueden motivar al lector a hacer clic en ellos.

Conclusión

Este ejemplo muestra cómo se pueden combinar Elasticsearch y Hugging Face para crear un sistema centralizado rápido y eficiente para aplicaciones de IA. Este enfoque reduce el esfuerzo manual y proporciona flexibilidad, gracias al extenso catálogo de modelos de Hugging Face. El uso de SmolLM3-3B, en particular, muestra cómo los modelos compactos y multilingües aún pueden ofrecer razonamiento significativo y generación de contenido cuando se combinan con la búsqueda semántica. En conjunto, estas herramientas ofrecen una base escalable y eficaz para construir análisis de contenidos inteligentes y aplicaciones multilingües.

Para resolver esto, los motores de búsqueda como Elasticsearch usan dos estrategias principales de optimización:

1. Búsqueda aproximada (mundo pequeño jerárquico navegable [HNSW]): en lugar de examinar cada documento, construimos un grafo de navegación para saltar rápidamente al vecindario probable de la respuesta.
2. Cuantización: Comprimimos los vectores (por ejemplo, de flotantes de 32 bits a enteros de 8 bits o incluso valores binarios de 1 bit) para reducir el uso de memoria y acelerar los cálculos.

Pero la optimización a menudo tiene un precio: la precisión.

El miedo es válido: "Si comprimo mis datos y tomo atajos durante la búsqueda, ¿me perderé los mejores resultados?". "¿Esta optimización degrada la relevancia de mi motor de búsqueda?".

Para demostrar que la cuantificación de Elastic no degrada los resultados, construimos un marco de pruebas repetible mediante el conjunto de datos de DBPedia-14 para calcular exactamente cuánta precisión intercambiamos (específicamente, la recuperación) por velocidad al usar las optimizaciones predeterminadas en Elasticsearch.

Resumen: es probable que sea mucho menos de lo que piensas. Echa un vistazo al cuaderno aquí e inténtalo por tu cuenta

Las definiciones (para los no expertos)

Antes de ver el código, establezcamos algunos términos.

• Relevancia versus recuperación: La relevancia es subjetiva (¿encontré cosas buenas?). La recuperación es matemática. Si hay 10 documentos en la base de datos que son las coincidencias matemáticas perfectas para tu consulta, y el motor de búsqueda encuentra nueve de ellos, tu recuperación es del 90 % (o 0,9).
• Búsqueda exacta (plana): A veces denominado el método de "fuerza bruta". El motor de búsqueda analiza cada uno de los documentos de un índice y calcula la distancia.
  • Pros: 100 % de recuperación perfecta.
  • Contras: computacionalmente caro y lento en escala.
• Búsqueda aproximada (HNSW): El método del "atajo". El motor de búsqueda crea un grafo HNSW. Recorre el grafo para encontrar a los vecinos más cercanos.
  • Ventajas: extremadamente rápido y escalable.
  • Desventajas: podrías perderte algún vecino si el recorrido del grafo se detiene demasiado pronto.

El experimento: exactitud versus aproximación

Para probar la recuperación, usamos el conjunto de datos DBPedia-14, un gran set de datos de títulos y resúmenes de 14 clases de ontología que normalmente se utilizan para entrenar y evaluar modelos de categorización de texto. En concreto, nos centraremos en la categoría de "Cine". Queríamos comparar los ajustes de producción optimizados con una verdad de base matemáticamente perfecta.

Para este experimento, utilizamos el modelo jina-embeddings-v5-text-small, un modelo multilingüe de última generación que lidera los estándares de la industria para la representación de texto. Elegimos este modelo porque define el estándar actual para embeddings de alto rendimiento. Al combinar la precisión de élite de Jina v5 con la cuantización nativa de Elasticsearch, podemos demostrar una arquitectura de búsqueda que es tanto computacionalmente eficiente como intransigente en la calidad de la recuperación.

Configuramos un índice con un mapeo doble. Ingerimos el mismo texto en dos campos diferentes de forma simultánea:

1. content.raw con el tipo: flat. Esto obliga a Elasticsearch a realizar un escaneo por fuerza bruta de los vectores Float32 completos. Esto devuelve resultados de coincidencia exacta y se utilizará para nuestra línea de base.
2. content con tipo semantic_text. Con valores predeterminados que utilizan HNSW + la mejor cuantificación binaria (BBQ). Esta es la configuración de producción estándar y optimizada para una coincidencia aproximada.

La prueba de recall@10

Para nuestra métrica, usamos Recall@10.

Elegimos 50 películas aleatorias y ejecutamos la misma consulta en ambos campos.

• Si la búsqueda exacta (plana) indica que los 10 vecinos más cercanos son los ID [1, 2, 3... 10].
• Y la búsqueda aproximada (HNSW) devuelve los ID [1, 2, 3... 9, 99].
• Encontramos nueve de los 10 principales correctamente. La puntuación es 0,9.

Este es el mapeo que utilizamos:

# The "Control Group": Forces exact brute-force scan
"raw": {
    "type": "semantic_text",
    "inference_id": ".jina-embeddings-v5-text-small",
    "index_options": {
        "dense_vector": {
            "type": "flat"
        }
    }
}

Los resultados: la "línea plana" del éxito

Realizamos una prueba de escala, recargando el conjunto de datos completo y probando con tamaños de índice de entre 1000 y 40 000 documentos.

Esto es lo que sucedió con la puntuación de recuperación:

Los resultados fueron increíblemente estables. Incluso a medida que escalábamos, la búsqueda aproximada coincidió con la búsqueda exacta de fuerza bruta >99 % del tiempo.

¿Por qué funcionó tan bien?

Podrías esperar que comprimir vectores a valores binarios perjudicaría más la precisión. La razón por la que esto no ocurre está en la forma en que Elasticsearch gestiona la recuperación.

La mayoría de los modelos de incrustación actuales dan como salida vectores Float32, que son grandes. Para hacer la búsqueda eficiente, Elasticsearch emplea cuantización para vectores de alta dimensión. Concretamente, desde la versión 9.2, usa BBQ por defecto.

BBQ usa un mecanismo de recalificación:

1. Recorrido: el motor de búsqueda utiliza los vectores comprimidos (cuantificados) para recorrer rápidamente el grafo HNSW. Como los vectores son pequeños, puedes realizar un sobremuestreo de manera eficiente, recopilando una lista más amplia de candidatos (por ejemplo, los 100 documentos más parecidos) sin que afecte al rendimiento.
2. Recálculo de la puntuación: una vez que obtiene esos candidatos, recupera los valores de precisión completa solo para esos pocos documentos para calcular la clasificación final y precisa.

Esto te brinda lo mejor de ambos mundos, la velocidad de la cuantización para el trabajo pesado y la precisión de los flotantes para la ordenación final.

¿Podemos hacerlo mejor?

Cabe destacar que los resultados que vemos aquí utilizan la configuración predeterminada y una muestra aleatoria de datos. Piensa en esto como un punto de partida de alto rendimiento. Aunque Jina v5 es una bestia, estas puntuaciones de recuperación no son una garantía de "talla única" para todos los conjuntos de datos. Cada conjunto de datos tiene sus propias peculiaridades, y aunque sin duda puedes seguir ajustando los parámetros para obtener un mejor rendimiento, siempre debes realizar pruebas con tus propios datos específicos para ver cuál es tu límite.

Conclusión

Esta es una prueba a muy pequeña escala. Pero el punto del ejercicio no es medir el modelo de incrustación o BBQ específicamente, sino demostrar cómo puedes medir fácilmente la recuperación de tu conjunto de datos con una configuración mínima.

Si quieres ejecutar esta prueba con tus propios datos, puedes consultar el cuaderno aquí e intentarlo por tu cuenta.

La extensión está disponible como proyecto de open source aquí.

¿Qué es Gemini CLI y cómo lo instalas?

Gemini CLI es un agente open source de IA que lleva los modelos Gemini de Google directamente a la línea de comando. Permite a los desarrolladores interactuar con la IA desde la terminal para hacer tareas como generar código, editar archivos, ejecutar comandos de shell y obtener información de la web.

A diferencia de las interfaces de chat típicas, Gemini CLI se integra con tu entorno local de desarrollo, lo que significa que puede entender el contexto del proyecto, modificar archivos, ejecutar compilaciones o pruebas, y automatizar flujos de trabajo directamente dentro de la terminal. Esto lo hace útil para desarrolladores, ingenieros de confiabilidad del sitio (SRE) e ingenieros que buscan codificación y automatización asistidas por IA sin salir de su flujo de trabajo de línea de comandos.

Gemini CLI puede instalarse usando diversos gestores de paquetes. El método más común es a través de npm:

npm install -g @google/gemini-cli

Si quieres conocer opciones de instalación alternativas, consulta la página de instalación oficial.

Luego de la instalación, inicia la CLI ejecutando:

gemini

Verás una pantalla, como se muestra en la Figura 1:

Configurar Elasticsearch

Es necesario tener una instancia de Elasticsearch en funcionamiento. Si quieres usar el servidor Model Context Protocol (MCP), también necesitas instalar Kibana 9.3+. Para emplear la habilidad del lenguaje de búsqueda Elasticsearch (ES|QL) (esql) descrito más abajo, Kibana no es obligatorio.

Puedes activar una prueba gratis en Elastic Cloud o instalarlo localmente usando el script start-local:

curl -fsSL https://elastic.co/start-local | sh

Se instalarán Elasticsearch y Kibana en tu computadora y se generará una clave API que se utilizará para configurar Gemini CLI.

La clave de API se mostrará como salida del comando anterior y se almacenará en un archivo .env en la carpeta elastic-start-local.

Si usas Elasticsearch local (por ejemplo, usar start-local), y quieres usar Elastic Agent Builder con MCP, también necesitas conectar un modelo de lenguaje grande (LLM). Puedes leer esta página de documentación para entender las diferentes opciones.

Si usas Elastic Cloud (o sin servidor), ya tienes una conexión con el LLM preconstruida.

Instala la extensión de Elasticsearch

Puedes instalar la extensión de Elasticsearch para Gemini CLI con el siguiente comando:

gemini extensions install https://github.com/elastic/gemini-cli-elasticsearch

Puedes verificar que las extensiones se hayan instalado correctamente abriendo Gemini y ejecutando el siguiente comando:

/extensions list

Deberías ver la extensión de Elasticsearch disponible.

Si quieres usar la integración de MCP, necesitas tener instalada una versión de Elasticsearch 9.3 o superior. Necesitas la URL de tu servidor MCP de Kibana:

• Obtén la URL del servidor MCP desde Agentes > Ver todas las herramientas > Administrar MCP > Copiar URL del servidor MCP.
• La URL tendrá este formato: https://your-kibana-instance/api/agent_builder/mcp

Necesitas la URL del endpoint de Elasticsearch. Esta generalmente se informa en la parte superior de la página de Kibana Elasticsearch. Si estás ejecutando Elasticsearch con start-local, ya tienes el endpoint en la clave ES_LOCAL_URLen el archivo start-local.env .

También necesitas una clave API. Si estás ejecutando Elasticsearch con start-local, ya tienes ES_LOCAL_API_KEY en el archivo start-local .env . De lo contrario, puedes crear una clave API desde la interfaz de Kibana, como se indica aquí:

• En Kibana: Stack Management > Seguridad > Claves de API > Crear clave de API.
• Sugerimos establecer solo los privilegios de lectura para la clave API, habilitando el privilegio feature_agentBuilder.read como se informa aquí.
• Copia el valor de la clave API codificada.

Configura las variables de entorno requeridas en tu shell:

export ELASTIC_URL="your-elasticsearch-url"
export ELASTIC_MCP_URL="your-elasticsearch-mcp-url"
export ELASTIC_API_KEY="your-encoded-api-key"

Instala el set de datos de ejemplo

Puedes instalar el set de datos de pedidos de comercio electrónico disponible desde Kibana. Incluye un único índice llamado kibana_sample_data_ecommerce, que contiene información sobre 4,675 pedidos de un sitio web de comercio electrónico. Para cada pedido, tenemos la siguiente información:

• Información del cliente (nombre, identificación, fecha de nacimiento, correo electrónico y más).
• Fecha del pedido.
• ID de pedido.
• Productos (lista de todos los productos con precio, cantidad, identificación, categoría, descuento y otros detalles).
• SKU.
• Precio total (sin impuestos, con impuestos).
• Cantidad total.
• Información geográfica (ciudad, país, continente, ubicación, región).

Para instalar los datos de muestra, abre la página Integraciones en Kibana (busca "Integración" en la barra superior de búsqueda) e instala los Datos de muestra. Para más detalles, consulta la documentación aquí.

El objetivo de este artículo es mostrar lo fácil que es configurar la CLI Gemini para conectarse a Elasticsearch e interactuar con el índice kibana_sample_data_ecommerce .

Cómo usar el MCP de Elasticsearch

Puedes comprobar la conexión usando el siguiente comando en Gemini:

/mcp list

Deberías ver el elastic-agent-builder activado, como se muestra en la Figura 2:

Elasticsearch proporciona un conjunto predeterminado de herramientas. Ve la descripción aquí.

Con estas herramientas, puedes interactuar con Elasticsearch y hacer preguntas como:

• Give me the list of all the indexes available in Elasticsearch.
• How many customers are based in the USA in the kibana_sample_data_ecommerce index of Elasticsearch?

Dependiendo de la pregunta, Gemini usará una o varias de las herramientas disponibles para intentar responderla.

Los comandos /elastic

En la extensión Elasticsearch para Gemini CLI, también agregamos comandos/elastic.

Si ejecutas el comando /help, verás todas las opciones /elastic disponibles (Figura 3):

Estos comandos pueden ser útiles si quieres ejecutar directamente una herramienta específica del servidor MCP elastic-agent-builder. Por ejemplo, usando el siguiente comando, puedes obtener el mapping del kibana_sample_data_ecommerce:

/elastic:get-mapping kibana_sample_data_ecommerce

Estos comandos son esencialmente atajos para ejecutar herramientas específicas, en lugar de depender del modelo Gemini para determinar qué herramienta debe invocarse.

Cómo usar las habilidades de Elasticsearch

Esta extensión también incluye una habilidad de agente para ES|QL, el lenguaje de búsqueda Elasticsearch disponible en Elasticsearch. Habilidades del Agente es un formato abierto que proporciona a los agentes de codificación de IA, como Gemini CLI, instrucciones personalizadas para tareas específicas. Utilizan un concepto llamado revelación progresiva, lo que significa que solo se agrega una breve descripción de la habilidad a la indicación inicial del sistema. Cuando le pides al agente que haga una tarea, como consultar Elasticsearch, hace coincidir la solicitud con la habilidad relevante y carga dinámicamente las instrucciones detalladas. Esta es una forma eficaz de gestionar los presupuestos de tokens y, al mismo tiempo, proporcionar a la IA exactamente el contexto que necesita.

La habilidadesql está diseñada para permitir que la CLI de Gemini escriba y ejecute consultas en ES|QL directamente en tu cluster. ES|QL es un poderoso lenguaje de búsqueda con barras verticales que hace que la exploración de datos, el análisis de logs y las agregaciones sean sumamente intuitivas. Con esta habilidad activada, no necesitas buscar la sintaxis de ES|QL; simplemente puedes hacer preguntas en lenguaje natural a la CLI de Gemini sobre tus datos, y el agente se encargará del resto.

Las ejecuciones se efectúan mediante comandos curl sencillos ejecutados en una terminal. Esto es posible porque Elasticsearch ofrece un amplio conjunto de API REST que se pueden utilizar fácilmente para integrar el sistema en cualquier arquitectura.

Lo que la habilidadesql ofrece:

• Detección de índices y esquemas: El agente puede usar las herramientas integradas de la habilidad para mostrar los índices disponibles y obtener el mapping de campos. Por ejemplo, antes de escribir una consulta para el set de datos de comercio electrónico, el agente puede ejecutar una verificación de esquema en kibana_sample_data_ecommerce para comprender los campos disponibles, como taxful_total_price o category.
• Traducción perfecta al lenguaje natural: la habilidad le da al agente algo más que un simple manual de referencia; proporciona una guía específica para interpretar la intención del usuario. Cuando escribes solicitudes en lenguaje natural, como "Mostrar el tiempo de respuesta promedio agrupado por servicio", el agente utiliza la función de coincidencia de patrones integrada en la habilidad para traducir al instante tus palabras en las agregaciones, filtros y comandos en ES|QL correctos.
• Autocorrección: Si una consulta falla (por ejemplo, debido a una incompatibilidad de tipos o un error de sintaxis), la habilidad devuelve la consulta generada junto con el mensaje de error exacto de Elasticsearch, lo que permite al agente corregirla al instante y volver a intentarlo sin que tengas que intervenir.

Dado que la habilidad esql también está disponible como una herramienta en el servidor MCP elastic-agent-builder, necesitamos deshabilitar este servidor momentáneamente. Puedes usar el siguiente comando para desactivarlo:

/mcp disable elastic-agent-builder

Entonces puedes simplemente escribir un mensaje como este en tu CLI de Gemini:

Find the top 5 product categories by total sales revenue in the kibana_sample_data_ecommerce index

El agente deberá:

• Reconoce la necesidad de la habilidad esql .
• Verifica el esquema de kibana_sample_data_ecommerce.
• Construye una consulta en ES|QL, como: FROM kibana_sample_data_ecommerce | STATS total_revenue = SUM(taxful_total_price) BY category.keyword | SORT total_revenue DESC | LIMIT 5.
• Ejecutar la consulta en la API de Elasticsearch.
• Presentar la respuesta final directamente en la terminal.

Aquí, presentamos un ejemplo de respuesta de Gemini al mensaje anterior:

───────────────────────────────────────────────────────────
> Find the top 5 product categories by total sales revenue in the kibana_sample_data_ecommerce index   ───────────────────────────────────────────────────────────
✓  Activate Skill "esql": Interact with Elasticsearch using ES|QL and curl. Use when querying, managing indices,  …
Skill esql activated. Resources loaded from /home/user/.gemini/extensions/elasticsearch/skills/esql: 
Showing up to 200 items (files + folders).                                                                     /home/user/.gemini/extensions/elasticsearch/skills/esql/                                                            ├───SKILL.md 
└───references/
├───esql-reference.md 
├───generation-tips.md 
└───query-patterns.md

✦ I will start by exploring the mapping of the kibana_sample_data_ecommerce index to identify the fields for product category and sales revenue. Then, I will construct and execute an ES|QL query to determine the top 5 product categories by total sales revenue.

✓  Shell curl -s "${ELASTIC_URL%/}/kibana_sample_data_ecommerce/_mapping" -H "Authorization: ApiKey $(printenv ELAS…                                                                                                                       {  
   "kibana_sample_data_ecommerce": { 
     "mappings": { 
       "properties": {
         "category": { 
           "type": "text", 
           "fields": {
             "keyword": {
               "type": "keyword"
             }
           }
         }, 
         "currency": {
           "type": "keyword"
         }, 

✦ Okay, I have the mapping. The category is products.category.keyword and sales revenue is taxful_total_price. I'll now execute the ES|QL query to get the top 5 categories by revenue.

✓  Shell curl -s -X POST "${ELASTIC_URL%/}/_query" \  -H "Authorization: ApiKey $(printenv ELASTIC_API_KEY)" \  -H …
{ 
   "took": 62,
   "is_partial": false, 
   "completion_time_in_millis": 1772805644164,
   "documents_found": 4675,
   "values_loaded": 12084, 
   "start_time_in_millis": 1772805644102, 
   "expiration_time_in_millis": 1773237644087,  
   "columns": [ 
     { 
       "name": "total_revenue",    
       "type": "double"  
     }, 
     {   
       "name": "products.category.keyword",

✦ The query for top 5 product categories by revenue was successful. I'll format the returned JSON values into a   user-friendly list.

 ✓  Shell 
                             
 Top 5 product categories by total sales revenue: 
 1. Men's Clothing: 149393.91
 2. Women's Clothing: 135099.91
 3. Women's Shoes: 105479.17
 4. Men's Shoes: 91797.92
 5. Women's Accessories: 60830.31 

✦ I've found the answer; now I'll format it for clarity.

 ✓  Shell 

 Here are the top 5 product categories by total sales revenue:                                                        
                                                                      
 | Rank | Category              | Total Revenue | 
 |------|-----------------------|---------------| 
 | 1    | Men's Clothing        | 149,393.91    |
 | 2    | Women's Clothing      | 135,099.91    |
 | 3    | Women's Shoes         | 105,479.17    |
 | 4    | Men's Shoes           | 91,797.92     | 
 | 5    | Women's Accessories   | 60,830.31     | 

✦ I've formatted and presented the answer. I'm finished.
 ───────────────────────────────────────────────────────────

Es interesante ver cómo el modelo Gemini genera la respuesta final mostrando todos los pasos que sigue. Aquí, puedes ver claramente la influencia de la habilidad en el proceso de razonamiento del modelo. La primera vez que el modelo reconoce que necesita usar una habilidad o ejecutar un comando de shell, pide permiso empleando el enfoque de intervención humana.

Al manejar el trabajo pesado de descubrimiento de esquemas, generación de consultas y ejecución, la habilidad esql te permite concentrarte completamente en las respuestas en lugar de en la mecánica para obtenerlas. Obtendrás los datos que necesitas, correctamente formateados y directamente en tu terminal, todo sin escribir una sola línea de sintaxis o cambiar de contexto a otra aplicación.

Conclusión

En este artículo, presentamos la extensión Elasticsearch para Gemini CLI que lanzamos recientemente. Esta extensión te permite interactuar con tu instancia de Elasticsearch mediante Gemini y el servidor MCP de Elasticsearch que ofrece Elastic Agent Builder, disponible a partir de la versión 9.3.0, así como el comando /elastic .

Además, la extensión también incluye una habilidad esql que convierte la solicitud del usuario de lenguaje natural en una consulta en ES|QL. Esta habilidad puede resultar especialmente útil cuando no se puede usar el servidor MCP, ya que la comunicación subyacente se gestiona mediante simples comandos curl ejecutados en una terminal. Elasticsearch ofrece un amplio conjunto de API REST que se pueden integrar fácilmente en cualquier proyecto. Esto es especialmente útil cuando se desarrollan aplicaciones de AI agéntica.

Para más información sobre nuestra extensión Gemini CLI, visita el repositorio del proyecto aquí.

Por eso estamos liberando el código de Elastic Agent Skills como open-source: experiencia nativa en plataformas para Elasticsearch, Kibana, Elastic Observability y Elastic Security. Insértalo en el tiempo de ejecución del agente que ya usas y cambia a tu agente de “generalista” que adivina mucha de la sintaxis a darle experiencia, como, por ejemplo, poder usar muchos de los estándares arquitectónicos como los propios equipos de ingeniería de Elastic. Esta versión inicial de vista previa técnica se centra en las habilidades con máxima compatibilidad para Elastic Cloud Serverless, pero evolucionará rápidamente para incluir un mejor soporte para versiones anteriores del stack.

Además, Elastic está abordando este problema desde ambos frentes. Para los agentes en la plataforma de Elastic, Elastic Agent Builder (ahora disponible en general) te permite crear y chatear con agentes de IA que heredan los controles de acceso de tus datos, usan herramientas integradas de búsqueda y análisis, y trabajan en contexto junto a tus dashboards, alertas e investigaciones. Estamos trabajando intensamente para asegurar experiencias agénticas increíbles en la plataforma de Elastic. Pero no todos los agentes están dentro de Elastic. Tu equipo ya usa Cursor, Claude Code u otros entornos de ejecución, y esos agentes también necesitan que Elastic funcione bien. Ahí es donde entra en juego Agent Skills.

Por qué los agentes tienen dificultades con plataformas especializadas

Los modelos de lenguaje grandes (LLM) son generalistas con capacidades extraordinarias. Pueden escribir Python, explicar los manifiestos de Kubernetes y refactorizar los componentes de React porque sus datos de entrenamiento están llenos de ejemplos. Pero cuando se trata de trabajo específico de la plataforma, del tipo que implica lenguajes de búsqueda patentados, superficies de API profundas y mejores prácticas específicas del dominio, muestran limitaciones previsibles.

En el caso de Elasticsearch, la diferencia se nota claramente:

• El lenguaje de búsqueda de Elasticsearch (ES|QL) es un nuevo territorio. Los LLM están muy entrenados en SQL, pero ES|QL es un lenguaje de búsquedas con barras verticales, con sintaxis, funciones y semántica diferentes. Los agentes suelen escribir búsquedas que parecen razonables, pero no se pueden parsear. Confunden WHERE con | WHERE, inventan funciones que no existen y pierden por completo el modelo de composición basado en barras verticales.
• Las superficies de API son anchas y profundas. Elasticsearch, Kibana y Elastic Security ofrecen cientos de API para búsqueda, ingesta, alertas, reglas de detección, gestión de casos, dashboards y mucho más. Un agente que solo cuenta con datos de entrenamiento generales tiene que adivinar a qué endpoint debe enviar la solicitud, cómo es el cuerpo de la solicitud y cómo gestionar la respuesta. Sus suposiciones son incorrectas con demasiada frecuencia como para erosionar la confianza.
• Las mejores prácticas no están en los datos de entrenamiento. ¿Cuándo deberías usar semantic_text frente a una pipeline de incrustación personalizada? ¿Cómo deberías estructurar una pipeline de ingesta para un CSV de 10GB? ¿Cuál es la sintaxis correcta de reglas de detección para una técnica MITRE ATT&CK®? Los agentes de uso general no tienen, por defecto, conocimientos específicos de Elastic seleccionados y estructurados de forma confiable. Tendrían que buscarlo, y aunque lo hicieran, la documentación sin procesar no siempre codifica los juicios y mejores prácticas que ofrecen los profesionales calificados.

El resultado: los desarrolladores pasan más tiempo corrigiendo el resultado del agente que el que habrían dedicado a escribir el código ellos mismos. Esa es la experiencia para la que nadie se registró.

Agent Skills: conocimiento de la plataforma, empaquetado para los agentes

Agent Skills son directorios independientes que contienen instrucciones, scripts y material de referencia que los entornos de ejecución de agentes pueden cargar dinámicamente. Cuando una habilidad está activa, el agente tiene acceso al contexto adecuado en el momento oportuno: sintaxis de búsqueda, patrones de API, lógica de validación y ejemplos prácticos, lo que le permite completar las tareas correctamente desde el primer intento.

Cada habilidad sigue la especificación abierta agentskills.io: una carpeta con un archivo SKILL.md que contiene metadatos e instrucciones estructuradas. Sin formato propietario, sin dependencia del proveedor. Las habilidades funcionan en diferentes entornos de ejecución de agentes; esto incluye Cursor, Claude Code, GitHub Copilot, Windsurf, Gemini CLI, Cline, Codex y muchos más.

¿Qué hay en la versión inicial v0.1.0?

El primer conjunto de habilidades abarca cinco áreas del Elastic Stack:

• Interactuar con las API de Elasticsearch (búsqueda, indexación, gestión de clústeres)
• Crear y gestionar contenido de Kibana como dashboards, alertas, conectores y más
• Especialización en el dominio para Elastic Observability
• Pericia en la materia para Elastic Security
• Cómo crear agentes eficaces en Agent Builder

Las habilidades son componibles

Las habilidades no son homogéneas. Son modulares por diseño. Tu agente carga solo las habilidades relevantes para la tarea en cuestión. ¿Estás trabajando en una búsqueda ES|QL? Se activa la habilidad ES|QL. ¿Necesitas crear un dashboard a partir de esos resultados? Aparece la habilidad de dashboard. ¿Estás evaluando el estado de tu aplicación? La habilidad de estado del servicio entra en juego. ¿Estás investigando una alerta de seguridad? La habilidad de triaje se asocia con habilidades de gestión de casos y respuesta a medida que avanza la investigación.

Esta capacidad de composición significa que no necesitas un único aviso masivo que intente cubrir todo. Cada habilidad lleva exactamente el contexto que tu dominio requiere, nada más, nada menos.

Para desarrolladores que crean aplicaciones de búsqueda e IA

Si estás cargando datos en Elasticsearch, escribiendo búsquedas o migrando índices, las habilidades reducen el ciclo de generación de código, errores y búsqueda de documentos a partir de los errores.

Pídele a tu agente que cargue un archivo CSV, y este utilizará una herramienta de ingesta en tiempo real que gestiona la contrapresión y deduce el mapping a partir de los datos. No es un bucle _bulk a medida que se queda sin memoria con el primer archivo grande. Pídele que realice búsquedas con ES|QL, y detectará los nombres reales de tus índices y los esquemas de los campos; luego generará búsquedas con barras verticales válidas, con la sintaxis correcta, las agregaciones adecuadas y una selección de características que tiene en cuenta la versión, en lugar de una conjetura al estilo SQL que requiere tres rondas de depuración. Si le pides que vuelva a indexar los clusters, sigue todo el flujo de trabajo operativo: crea el destino con mapping explícitos, configura los ajustes para el rendimiento, ejecuta el trabajo de forma asincrónica y restaura la configuración de producción cuando termina, no una llamada de _reindex que omite la mitad de los pasos que seguiría un operador experimentado.

En lugar de un agente que te da un punto de partida razonable que tienes que arreglar, obtienes uno que codifica la disciplina operativa que hace que el resultado realmente funcione.

Ejemplos de impactos del uso de Elastic Agent Skills

Para equipos de seguridad

Los equipos de seguridad repiten los mismos flujos de trabajo operativos a diario: clasificación de alertas, ajuste de reglas de detección, gestión de casos. Las habilidades del agente codifican ese conocimiento de procesos para que tu agente de IA pueda ejecutar estos flujos de trabajo correctamente al llamar a las API adecuadas en el orden correcto con los nombres de campo correctos. Para una guía práctica que te lleva de cero a un entorno de Elastic Security completamente configurado sin salir de tu IDE, consulta Empieza con Elastic Security desde tu agente de IA.

Para equipos de observabilidad y operaciones

Las nuevas funciones de los agentes de Elastic Observability reducen la carga operativa que supone instrumentar sistemas complejos, gestionar los SLO, analizar datos complejos y evaluar el estado de los servicios. Incorporar la experiencia nativa de Elastic directamente en los agentes de IA permite a los equipos ejecutar flujos de trabajo complejos de observabilidad utilizando un lenguaje natural sencillo. Esto permite a los SRE y equipos de operaciones resolver incidentes más rápido y mantener sistemas fiables con mayor facilidad. Obtén más información en este blog.

Open source, especificación abierta, impulsado por la comunidad

Estamos lanzando Agent Skills bajo la licencia Apache 2.0 porque creemos que el conocimiento de los agentes debe ser abierto. La especificación agentskills.io que siguen las habilidades es un estándar abierto, no un formato propietario de Elastic. Queremos que las habilidades sean un esfuerzo comunitario, no un entorno cerrado.

Parte de un panorama más amplio

Agent Skills es una parte de una iniciativa más amplia para hacer de Elasticsearch la plataforma de datos disponible más preparada para los agentes. Para los agentes que están en la plataforma Elasticsearch, Agent Builder va más allá al heredar los controles de acceso y permisos de tus datos, ofrecer herramientas integradas y personalizadas para búsqueda y análisis, y permitir que los usuarios interactúen con los agentes en contexto junto con sus dashboards, alertas e investigaciones. Finalmente, el soporte para habilidades llegará pronto a Agent Builder, lo que permitirá a los desarrolladores la flexibilidad de aprovechar las habilidades de Elastic Agent, así como habilidades de cualquier otra fuente para habilitar chats y automatizaciones seguras y mejoradas por contexto en la plataforma Elasticsearch.

Para los agentes que viven en cualquier otro lugar, estamos invirtiendo en el ecosistema abierto:

• Expansión del servidor del Model Context Protocol (MCP): Ampliando el endpoint MCP en Agent Builder con más herramientas, más allá de la búsqueda actual, ES|QL y operaciones de índice.
• Mejoras en la autenticación: Facilitar a los agentes la conexión segura, con el objetivo de eliminar la necesidad de copiar y pegar manualmente las claves de API.
• Documentación legible en LLM: publicar archivos llms.txt y AGENTS.md para que los agentes puedan descubrir y entender las API de Elastic por sí mismos.
• Una interfaz de línea de comandos (CLI) para los flujos de trabajo de los agentes: Herramientas de línea de comandos que facilitan la gestión de conexiones y las operaciones comunes para los agentes.

Las habilidades son la capa que puedes usar hoy. El resto llegará más adelante.

Comenzar

Antes de que empieces: los agentes de programación con IA operan con credenciales reales, acceso real a la shell y, a menudo, con todos los permisos del usuario que los ejecuta. Cuando esos agentes se orientan a flujos de trabajo de seguridad, hay más en juego: le estás dando a un sistema automatizado acceso a la lógica de detección, las acciones de respuesta y la telemetría sensible. El perfil de riesgo de cada organización es diferente. Antes de habilitar los flujos de trabajo de seguridad impulsados por IA, evalúa a qué datos puede acceder el agente, qué acciones puede realizar y qué pasa si se comporta de forma inesperada.

Instala Elastic Agent Skills en el tiempo de ejecución de tu agente:

npx skills add elastic/agent-skills

Esto detecta automáticamente tus tiempos de ejecución del agente instalado y coloca las habilidades en el directorio de configuración correcto. Desde allí, tu agente los recoge automáticamente.

También puedes navegar directamente en el catálogo de habilidades e instalar habilidades individuales manualmente si copias la carpeta de la habilidad en el directorio de configuración de tu agente.

¿Aún no tienes un clúster de Elasticsearch? Comienza una prueba gratis de Elastic Cloud. Lleva aproximadamente un minuto obtener un entorno completamente configurado.

Explora el proyecto:

• Repositorio de habilidades de agentes
• especificación de agentskills.io
• Documentación de Elasticsearch
• Prueba gratuita de Elastic Cloud

Como vimos en la entrada anterior, la consistencia que aportan las llamadas a funciones no es solo una optimización interesante; es esencial. Una vez que eliminamos los errores estructurales del ciclo de evaluación, los resultados en escenarios estándar (como los de los sets de datos de nivel 4) mejoraron significativamente.

Sin embargo, queda una pregunta obvia por responder:

¿Funciona de igual manera este enfoque cuando todo se complica realmente?

La resolución de entidades del mundo real rara vez falla debido a casos simples. Falla cuando los nombres atraviesan idiomas, culturas, sistemas de escritura, períodos de tiempo y límites organizacionales. Falla cuando las personas se mencionan por sus cargos en lugar de por sus nombres, cuando las empresas cambian de nombre, cuando las transliteraciones no son consistentes y cuando el contexto (no la ortografía) es lo único que vincula una mención a una entidad del mundo real.

Así que, para la publicación final de esta serie, sometimos el sistema a lo que llamamos el desafío definitivo.

¿Qué hace que esto sea el desafío definitivo?

En evaluaciones anteriores, probamos el sistema con sets de datos cada vez más complejos. Para cuando llegamos al nivel 4, analizado en la publicación anterior, ya estábamos lidiando con una mezcla de apodos, cargos, nombres multilingües y referencias semánticas. Esas pruebas demostraron que la arquitectura en sí era estable, pero que los problemas de confiabilidad, especialmente el JSON mal formado, estaban reduciendo la capacidad de recuperación.

Con la llamada a funciones implementada, finalmente conseguimos una base estable. Eso nos dio la oportunidad de hacer una pregunta más interesante:

¿Puede una única pipeline unificada gestionar muchos tipos diferentes de problemas de resolución de entidades al mismo tiempo?

El set de datos del desafío final se diseñó precisamente para poner a prueba esa dimensión.

En lugar de centrarse en una sola dificultad (como apodos o transliteración), este sets de datos combina más de 50 tipos distintos de desafíos, incluyendo:

• Convenciones de nomenclatura cultural.
• Referencias basadas en cargos.
• Relaciones comerciales y cambios históricos de nombre.
• Menciones multilingües y entre sistemas de escritura.
• Desafíos compuestos que mezclan varios de los anteriores.

Lo importante es que no se trata de optimizar para un solo caso de uso concreto. Se trata de probar si el patrón de diseño se mantiene cuando las reglas cambian de entidad a entidad.

Resumen del set de datos

El set de datos del desafío final consta de:

• 50 entidades, que abarcan personas, organizaciones e instituciones.
• ~60 artículos, con estructuras y complejidad lingüísticas variables.
• 51 categorías distintas de desafíos, agrupadas en términos generales en:
  • Convenciones de nomenclatura cultural.
  • Títulos y contexto profesional.
  • Relaciones empresariales y organizacionales.
  • Desafíos multilingües y de transliteración.
  • Escenarios combinados y de casos límite.

Al principio de la serie, vimos que usar IA generativa (GenAI) para crear sets de datos puede tener pros y contras. Sin eso, sería muy difícil reunir datos de prueba lo suficientemente amplios y variados. Pero si no se controla, el modelo tiende a facilitar demasiado todo.

En una fase inicial de generación, por ejemplo, descubrimos que el modelo había incluido frases como «el presidente ruso» como alias explícitos para Vladimir Putin. Eso podría parecer razonable hoy en día, pero anula el propósito de probar la resolución contextual. ¿Qué pasa si el artículo habla de Rusia en la década de 1990? El sistema debería deducir la entidad correcta a partir del contexto, en lugar de basarse en un alias predefinido.

Por esa razón, este set de datos fue diseñado deliberadamente para que los atajos no funcionen. Los alias no se enumeran explícitamente cuando se espera que el sistema deduzca su significado. Las frases descriptivas no están previnculadas a entidades. Las coincidencias correctas suelen depender del contexto del artículo, no solo del texto local.

Nota importante: Aunque demostramos las capacidades del sistema en diversos escenarios, este sigue siendo un prototipo educativo. Los sistemas de producción que manejan el monitoreo de entidades sancionadas en el mundo real requerirían validación adicional, verificaciones de cumplimiento, pistas de auditoría y manejo especializado para casos de uso confidenciales.

¿Por qué estos escenarios son difíciles?

¡En la primera publicación de esta serie, presentamos un ejemplo simple pero ambiguo: “¡La nueva actualización de Swift está aquí!”! El desafío es que “Swift” puede resolverse en múltiples entidades del mundo real, dependiendo del contexto. Ese ejemplo refleja una verdad más amplia: el lenguaje natural es inherentemente ambiguo.

La resolución de entidades, por lo tanto, no es solo un problema de coincidencia de texto. Los humanos solemos basarnos en el conocimiento compartido, las normas culturales y el contexto de cada situación para interpretar las referencias, y casi nunca nos damos cuenta de que lo estamos haciendo.

Considera algunos casos comunes:

• Un título como “el presidente” no tiene sentido sin contexto geopolítico y temporal.
• El nombre de una empresa puede referirse a la empresa matriz, a una filial o a una marca anterior, dependiendo de cuándo se escribió el artículo.
• El nombre de una persona puede aparecer en diferentes órdenes, sistemas de escritura o transcripciones, dependiendo del idioma y la cultura.
• La misma frase puede referirse legítimamente a diferentes entidades en diferentes contextos, y el sistema debe ser capaz de rechazar coincidencias con la misma confianza con la que las acepta.

No existe un único conjunto de reglas que maneje todo esto de manera clara. Por eso este prototipo separa las responsabilidades de forma tan marcada:

• Elasticsearch reduce el espacio de candidatos de manera eficiente y transparente.
• El LLM se usa solo donde se requiere juicio y está obligado a explicarse a sí mismo.
• La recuperación y el razonamiento siguen siendo pasos distintos.

Esta distinción cobra aún más importancia a medida que aumenta la variedad de tipos de desafíos.

Cómo el sistema gestiona la diversidad sin casos especiales

Uno de los resultados más interesantes de esta evaluación es lo que no cambió:

• No agregamos lógica especial para nombres japoneses.
• No agregamos reglas personalizadas para patronímicos árabes.
• No agregamos mapeos codificados para nombres históricos de compañías.

En cambio, el sistema se basó en los mismos elementos principales presentados anteriormente en la serie:

• Entidades enriquecidas con contexto indexadas para búsqueda semántica.
• Recuperación híbrida (exacta, alias y semántica) en Elasticsearch.
• Un conjunto pequeño y bien definido de posibles coincidencias.
• El juicio del LLM está limitado por las llamadas a funciones y los esquemas mínimos.

Esto sugiere que la flexibilidad del sistema proviene de la representación y arquitectura, no de una colección cada vez mayor de reglas.

Cuando el sistema tiene éxito, es porque se recuperan los candidatos adecuados y el LLM tiene suficiente contexto para explicar por qué una referencia mapea (o no) a una entidad específica.

Resultados: ¿cómo funcionó?

En los sets de datos del desafío final, el sistema obtuvo los siguientes resultados generales:

• Precisión: ~91 %
• Recuperación: ~86 %
• Puntuación F1: ~89 %
• Tasa de aceptación en LLM: ~72 %

Rendimiento en los tipos de desafíos

El desglose de resultados por tipo de desafío revela fortalezas y limitaciones:

El mejor desempeño (100 % de puntuación F1) se observó en áreas como:

• Coincidencia entre diferentes sistemas de escritura (entidades comerciales en cirílico, coreano y chino).
• Escenarios hebreos (patronímicos, títulos profesionales, títulos religiosos, transliteración).
• Jerarquías empresariales (aeroespacial, producción diversificada, corporaciones multidivisionales).
• Títulos profesionales (académicos, militares, políticos, religiosos).
• Escenarios japoneses combinados que involucran múltiples sistemas de escritura.

Fuerte rendimiento (80-99 % de puntuación F1) incluido:

• Figuras políticas internacionales (98%).
• Cambios de nombre históricos (90 %).
• Jerarquías empresariales complejas (89 %).
• Nombres de empresas japonesas (93 %).
• Transliteración entre alfabetos (86 %).
• Patronímicos árabes (86 %).

Las áreas más desafiantes fueron:

• Transliteración avanzada (chino, coreano): 0 % F1.
• Ciertos escenarios japoneses (honoríficos, orden de los nombres, variación del sistema de escritura): ~67 % F1.
• Algunos escenarios árabes (nombres de empresas, referencias institucionales): ~40% F1.

Lo importante aquí es por qué el sistema tuvo dificultades en estos casos. Las fallas no se debieron a la ruptura del enfoque general, sino a limitaciones en componentes específicos, sobre todo el modelo vectorial denso utilizado para la búsqueda semántica en ciertos escenarios multilingües.

Como la recuperación y la evaluación están claramente separadas, para mejorar el rendimiento no hace falta reescribir el sistema. Si se sustituyera por un modelo de incrustación multilingüe más potente, se enriquecería el contexto de las entidades o se perfeccionarían las estrategias de recuperación, se mejorarían los resultados en todas estas categorías sin cambiar la arquitectura central.

Desde el punto de vista arquitectónico, esa es la verdadera medida del éxito.

Qué nos dice esto sobre el diseño

Si vemos nuevamente las series, se observan algunas tendencias:

• La preparación importa más que la coincidencia inteligente. El enriquecimiento de entidades con contexto de antemano reduce drásticamente la ambigüedad posteriormente.
• Los LLM son más valiosos como jueces, no como recuperadores. Pedirles que expliquen por qué una coincidencia tiene sentido es mucho más poderoso que pedirles que realicen una búsqueda.
• La fiabilidad permite la precisión. La llamada a funciones no solo limpió el JSON; desbloqueó la memoria que ya estaba latente en el paso de recuperación.
• La generalización supera a la especialización. Un pequeño número de abstracciones bien seleccionadas manejó decenas de tipos de desafío sin lógica personalizada.

Esta es la razón por la que el prototipo es intencionalmente nativo de Elasticsearch y es intencionalmente conservador en cómo utiliza los LLM. El objetivo no es reemplazar la búsqueda; es hacer que la búsqueda sea explicable en situaciones donde el significado importa.

Reflexiones finales

El desafío final no se trataba de perseguir métricas perfectas; se trataba de responder una pregunta más fundamental:

¿Puede una arquitectura transparente, centrada en la búsqueda y asistida por LLM, manejar la ambigüedad de entidades en el mundo real sin colapsar en reglas o cajas negras?

Para este prototipo educativo, la respuesta es sí, con claras advertencias sobre el fortalecimiento de la producción, el cumplimiento, el monitoreo y la calidad de los datos. Si estás creando sistemas que necesitan justificar por qué se hizo una coincidencia de entidades, este patrón merece ser considerado seriamente. Espero que esta serie haya demostrado que la resolución de entidades no tiene que ser misteriosa. Con una correcta separación de responsabilidades, se convierte en algo sobre lo que puedes razonar, medir y mejorar.

Este trabajo también sugiere un patrón arquitectónico más amplio. Lo que surge es una ligera pero importante evolución de la clásica Retrieval-Augmented Generation (RAG). En lugar de permitir que la recuperación alimente directamente la generación, introducimos un paso de evaluación explícito. El LLM se usa primero para juzgar y verificar el estado de los candidatos recuperados, y solo los resultados aprobados pueden incrementar la generación. Se puede pensar en esto como Generation-Augmented Retrieval-Augmented Generation with Evaluation, o GARAGE, porque a quién no le gusta un buen acrónimo.

¿Qué otros casos de uso podrían beneficiarse de este patrón? Los sistemas que requieren confianza, transparencia y razonamiento justificable son candidatos naturales. Los trabajos futuros en este ámbito deberían ser tan convincentes como los resultados que hemos visto aquí, y tengo muchas ganas de ver hacia dónde lo lleva la comunidad.

Próximos pasos: Pruébalo tú mismo

¿Quieres ver el desafío final en acción? Mira el cuaderno de desafío final para obtener una guía completa con implementaciones reales, explicaciones detalladas y ejemplos prácticos.

El pipeline completo de resolución de entidades demuestra los conceptos del núcleo y la arquitectura necesarios para uso en producción. Se puede usar como base para construir sistemas que monitoreen los artículos de noticias, rastreen las menciones de entidades y respondan preguntas sobre qué entidades aparecen en qué artículos, al tiempo que se mantiene la transparencia y la explicabilidad.

En HNSW, la búsqueda avanza expandiendo iterativamente los nodos candidatos en el grafo, lo que mantiene un conjunto acotado de vecinos más cercanos descubiertos hasta ahora. Cada expansión tiene un costo (operaciones vectoriales, búsquedas aleatorias en el disco y más), y el beneficio marginal de ese costo tiende a disminuir a medida que avanza la búsqueda.

Una forma de optimizar el recorrido de grafos de HNSW es dejar de buscar cuando la probabilidad marginal de encontrar nuevos vecinos verdaderos no aumenta. Por esta razón, en Elasticsearch 9.2, introdujimos un nuevo mecanismo de terminación temprana. Esto detiene el proceso de búsqueda cuando visitar nodos del grafo no proporciona suficientes vecinos más cercanos nuevos, consecutivamente, para un número fijo de veces.

En este artículo, te orientamos sobre cómo mejoramos el mecanismo de terminación temprana mencionado en HNSW para hacerlo más adecuado para diferentes sets de datos y distribuciones de datos.

Terminación temprana en HNSW

En HNSW, la búsqueda avanza expandiendo iterativamente nodos candidatos en el grafo de proximidad, lo que mantiene un conjunto limitado de vecinos más cercanos descubiertos hasta el momento, hasta que haya visitado todo el grafo o cumpla con algunos criterios de terminación temprana.

Por lo tanto, la terminación temprana no siempre es necesariamente una optimización, sino que es parte del algoritmo de búsqueda en sí. El momento en que decidimos detenernos determina el equilibrio entre eficiencia y recuperación. En Elasticsearch, ya hay varias formas en que una consulta en HNSW puede terminar de forma temprana:

• Se visita una cantidad máxima fija de nodos.
• Se alcanza un tiempo de espera fijo.

Si bien son simples y previsibles, estas reglas son, en gran medida, independientes de lo que realmente está haciendo la búsqueda. También se emplean, principalmente, para garantizar que la búsqueda finalice en un tiempo razonable para el usuario final.

En una entrada anterior del blog, presentamos el concepto de redundancia en HNSW. En resumen, los cálculos redundantes ocurren cuando HNSW continúa evaluando nuevos nodos candidatos que no dan como resultado la búsqueda de más vecinos más cercanos.

Paciencia: medir el progreso en lugar del esfuerzo

La noción de paciencia replantea la terminación temprana en torno al progreso, en lugar del esfuerzo.

En lugar de preguntar:

“¿Cuántos pasos hemos dado?”

La nueva pregunta es:

“¿Qué cantidad de cómputo aceptamos desperdiciar hasta que perdemos la esperanza?”

Durante la búsqueda de HNSW, por lo general, la exploración temprana produce mejoras máximas en el conjunto de candidatos top-k. Durante los primeros pasos de la exploración de grafos de HNSW, el conjunto de vecinos se actualiza continuamente a medida que el algoritmo sigue descubriendo vecinos cada vez más cercanos al vector de búsqueda. Con el tiempo, estas mejoras se vuelven más raras a medida que la búsqueda converge. La terminación basada en la paciencia monitorea este patrón y finaliza la búsqueda una vez que las mejoras han cesado durante un período prolongado.

En la práctica, al visitar el grafo de HNSW, también calculamos la relación de saturación de la cola al saltar entre nodos candidatos. Esto mide el porcentaje de vecinos más cercanos que se dejaron sin cambios al visitar el nodo del grafo más reciente (o el inverso del número de nuevos vecinos introducidos durante la última iteración). Cuando esa proporción se vuelve demasiado grande para demasiadas iteraciones consecutivas, dejamos de visitar el grafo.

Conceptualmente, la paciencia trata la búsqueda de HNSW como un proceso de rendimientos decrecientes. Cuando los rendimientos se estabilizan, seguir analizando el grafo aporta pocos beneficios.

Esta estructura es poderosa porque vincula la terminación directamente a resultados observables, en lugar de a límites fijos arbitrarios.

El beneficio de usar esta técnica inteligente de terminación temprana es que las exploraciones del grafo de HNSW tienden a visitar un número menor de nodos del grafo, mientras mantienen una recuperación relativa casi perfecta.

Para visualizar esto, podemos graficar la cantidad de recuperación por nodo visitado que obtuvimos con la terminación temprana basada en la paciencia (etiquetada como et=static), en comparación con el comportamiento predeterminado de HNSW (etiquetado como et=no) en un par de sets de datos, FinancialQA y Quora, y modelos, JinaV3 y E5-small.

Umbrales estáticos y dinámicas de HNSW

En la práctica, en Elasticsearch esto se implementa utilizando umbrales estáticos. Un umbral se refiere al umbral de saturación, es decir, la proporción de saturación que consideramos subóptima. El otro umbral se refiere al número de nodos del grafo consecutivos que permitimos que se visiten sin dejar de tener una saturación de cola subóptima: es decir, el umbral de paciencia.

Cuando introdujimos esta estrategia de terminación temprana en Elasticsearch 9.2, decidimos optar por valores predeterminados conservadores, para permitir la recuperación tanto como fuera posible, mientras se mejora la latencia y el consumo de memoria. Por esta razón, establecemos el umbral de saturación al 100 % y el umbral de paciencia se establece como un 30 % (limitado) del num_candidates en la búsqueda de KNN.

En muchas situaciones, estas configuraciones resultaron funcionar bien; sin embargo, dos búsquedas que solicitan el mismo número de vecinos podrían tener comportamientos de convergencia radicalmente diferentes. Algunas búsquedas encuentran vecindarios locales densos y se saturan rápidamente; otras deben atravesar caminos largos y dispersos antes de encontrar candidatos competitivos. Estas últimas resultaron ser las más difíciles de manejar con eficacia.

Como resultado, a veces notamos lo siguiente:

• Sobreexploración para búsquedas sencillas.
• Terminación prematura para búsquedas difíciles.

Por lo tanto, consideramos que los valores de umbral fijos codifican suposiciones globales sobre la convergencia, mientras que podríamos hacer que HNSW se adapte mejor a diferentes dinámicas.

Hacer que la terminación temprana de HNSW sea adaptativa

La terminación temprana adaptativa aborda este problema desde otro ángulo. En lugar de imponer umbrales de parada predefinidos, el algoritmo infiere cuándo detenerse de la propia dinámica de búsqueda.

Entonces, en lugar de comparar la proporción de saturación de cola entre dos candidatos consecutivos, decidimos introducir una tasa de descubrimiento suavizada instantánea $d_{q,i} $ (cuántos vecinos nuevos se introdujeron para una búsqueda q en la última visita i) junto con el promedio móvil $\mu_{q,i}$ y la desviación estándar $\sigma_{q,i}$ de tal tasa de descubrimiento durante la visita del grafo (usando el algoritmo de Welford). Estas estadísticas sobre la tasa de descubrimiento se calculan por búsqueda, de modo que esta información pueda utilizarse para decidir diferentes grados de paciencia para cada búsqueda.

Los umbrales anteriormente estáticos se vuelven adaptativos a las estadísticas de tasa de descubrimiento: el umbral de saturación se convierte en el promedio móvil más la desviación estándar; mientras tanto, hacemos que la paciencia se adapte y escale inversamente con la desviación estándar.

Las reglas de salida anticipada siguen siendo las mismas; la saturación se produce cuando la tasa de descubrimiento instantáneo es menor que el umbral de saturación adaptativa. La visita al grafo se detiene si la saturación persiste durante un número de visitas consecutivas de candidatos que es mayor que la paciencia adaptativa.

De este modo, obtenemos un comportamiento que no depende del parámetro num_candidates en la búsqueda de KNN (que puede estar siempre establecido o dejado como predeterminado, independientemente de si sale pronto) y que se adapta mejor dinámicamente a cada consulta y distribución vectorial.

La recuperación por nodo visitado en FinancialQA y Quora con la estrategia adaptativa (etiquetada como et=adaptive) reporta una mayor recuperación por nodo visitado, en comparación con la estrategia estática (et=static) y el comportamiento predeterminado de HNSW (et=no).

La terminación temprana adaptativa está activada de manera predeterminada en Elasticsearch 9.3 para los campos vectoriales densos de HNSW (y, eventualmente, se puede desactivar a través de la misma configuración de nivel de índice).

Las integraciones configuran las entradas de Filebeat para realizar la recopilación de datos. Para recopilar datos de APIs HTTP, a menudo utilizamos la entrada HTTP JSON. Sin embargo, incluso las APIs básicas de listado pueden diferir mucho en los detalles, y el modelo de transformaciones configuradas en YAML de la entrada HTTP JSON puede hacer que sea engorroso y a veces imposible expresar la lógica de recopilación requerida.

Se introdujo la entrada del lenguaje de expresión común (CEL) para permitir una interacción más flexible con las APIs HTTP. CEL es un lenguaje diseñado para integrarse en aplicaciones que requieren una forma rápida, segura y extensible de expresar condiciones y transformaciones de datos. La entrada CEL permite a un creador de integraciones escribir una expresión que puede leer configuraciones, realizar un seguimiento de su propio estado, realizar solicitudes, procesar respuestas y, en última instancia, devolver eventos listos para su ingesta.

En este artículo, veremos cómo se diferencia el lenguaje de expresión común de otros lenguajes de programación, cómo lo ampliamos para la entrada del CEL, y la flexibilidad y el poder que te da para expresar tu lógica de recopilación de datos.

CEL y cómo funciona en la entrada

CEL es un lenguaje de expresión. No tiene declaraciones. Cuando escribes CEL, no le dices qué hacer al escribir declaraciones, sino que le dices qué valor producir al escribir una expresión. Cada expresión CEL produce un valor, y las expresiones más pequeñas pueden combinarse en una expresión mayor para producir un resultado según reglas más complejas. Más adelante veremos cómo usar expresiones que se pueden escribir con declaraciones en otros idiomas.

CEL es intencionadamente un lenguaje completo no Turing. No permite bucles ilimitados. Más adelante, veremos cómo puedes procesar listas y mapas mediante macros, pero al evitar bucles sin límites, el lenguaje garantiza un tiempo de ejecución predecible y limitado para expresiones individuales.

La entrada CEL está configurada con un programa CEL (una expresión) y un estado inicial. El estado se proporcionará como entrada al programa. El programa se evalúa para producir un estado de salida. Si el estado de salida incluye una lista de eventos, estos se eliminarán y se publicarán. El resto del estado de salida se usará como entrada para la próxima evaluación. Si el estado de salida incluye uno o más eventos y la advertencia want_more: true, la siguiente evaluación se realizará inmediatamente. De lo contrario, permanecerá en suspensión durante el resto del intervalo configurado antes de continuar. Aquí tienes un diagrama simplificado del flujo de control de la entrada:

La salida de cada evaluación se pasará como entrada a la siguiente evaluación, mientras se ejecute la entrada. Los datos de salida bajo la clave "cursor" se mantendrán en el disco y se volverán a cargar después de que la entrada se reinicie, pero el resto del estado no se conservará entre los reinicios.

El lenguaje CEL en sí tiene funcionalidades limitadas y evita efectos secundarios, pero es extensible. La implementación cel-go agrega algunas funcionalidades, como sintaxis y tipos opcionales. La biblioteca Mito se basa en cel-go y agrega más funcionalidades, como la capacidad de hacer solicitudes HTTP. La entrada CEL usa la versión de CEL de Mito.

Trabajando con Mito

Para construir o depurar una integración mediante una entrada CEL, lo más importante que debes entender es qué estado de salida producirá tu programa CEL para un estado de entrada dado. Durante el desarrollo, puede ser engorroso que tu programa CEL la ejecute la entrada, rodeada por toda la pila de Elastic Stack. Una forma de lograr un ciclo de retroalimentación más rápido es usar la herramienta de línea de comando de Mito, que te permitirá ejecutar un programa CEL directamente y ver la salida que produce para una entrada dada.

Mito está escrito en Go y se puede instalar de la siguiente manera:

go install github.com/elastic/mito/cmd/mito@latest

Cuando ejecutas un programa CEL con Mito, normalmente le asignas dos archivos: un archivo JSON con el estado inicial de entrada y otro archivo con el código fuente de tu programa CEL:

mito -data state.json src.cel

Para facilitar la copia y el pegado, los ejemplos en este artículo están escritos como comandos únicos que hacen que el shell cree archivos temporales al instante al envolver el contenido de cada archivo en <(echo '...content...'). En tu propio desarrollo, trabajar con archivos reales será más fácil.

Obtención de datos de incidencias desde GitHub

El siguiente ejemplo incluye un programa CEL completo que obtendrá datos sobre los problemas de la API de GitHub. Su estado de entrada inicial tiene una URL para el endpoint de la API y cierta información sobre cómo debe manejar la paginación. El programa CEL utiliza los datos del estado de entrada para generar una solicitud. Decodificará la respuesta, generará eventos a partir de ella y los devolverá como parte de su estado de salida.

mito -data <(echo '
  {
    "url": "https://api.github.com/repos/elastic/integrations/issues",
    "per_page": 3,
    "max_pages": 3
  }
') <(echo '
  int(state.?cursor.page.orValue(1)).as(page,
    (
      state.url + "?" + {
        "state": ["all"],
        "sort": ["created"],
        "direction": ["asc"],
        "per_page": [string(state.per_page)],
        "page": [string(page)],
      }.format_query()
    ).as(full_url,
      request("GET", full_url).with({
        "Header": {
          "Accept": ["application/vnd.github+json"],
          "X-GitHub-Api-Version": ["2022-11-28"],
        }
      }).do_request().as(resp,
        resp.Body.decode_json().as(data,
          state.with({
            "events": data.map(i, {
              "html_url": i.html_url,
              "title": i.title,
              "created_at": i.created_at,
            }),
            "cursor": { "page": page + 1 },
            "want_more": size(data) == state.per_page && page < state.max_pages,
          })
        )
      )
    )
  )
')

Su primera evaluación produce la siguiente salida:

{
  "cursor": {
    "page": 2
  },
  "events": [
    {
      "created_at": "2018-09-14T09:47:35Z",
      "html_url": "https://github.com/elastic/integrations/issues/3250",
      "title": "Increase support of log formats in haproxy filebeat module"
    },
    {
      "created_at": "2019-02-06T12:37:37Z",
      "html_url": "https://github.com/elastic/integrations/issues/487",
      "title": "ETCD Metricbeat module needs polishing and grooming"
    },
    {
      "created_at": "2019-08-13T11:33:11Z",
      "html_url": "https://github.com/elastic/integrations/pull/1",
      "title": "Initial structure"
    }
  ],
  "max_pages": 3,
  "per_page": 3,
  "url": "https://api.github.com/repos/elastic/integrations/issues",
  "want_more": true
}

Los eventos se eliminarán y, cuando se ejecuten en la entrada CEL, se publicarán para su ingesta. El resto de la salida se proporcionará a la siguiente evaluación del programa CEL como estado de entrada.

Para entender cómo funciona ese programa CEL, veremos algunos ejemplos más pequeños de CEL y hablaremos con más detalle sobre cómo funciona la entrada de CEL.

Conceptos básicos de CEL

En el lenguaje CEL, no hay declaraciones, solo hay expresiones. Cada expresión CEL exitosa se evalúa hasta un valor final. Esta es una de las expresiones CEL más pequeñas que puedes escribir, junto con su salida:

mito <(echo '
  "hello" + " " + "world"
')

"hello world"

Muchas expresiones simples son intuitivas. Las operaciones matemáticas solo se admiten en valores del mismo tipo (por ejemplo, int con int), así que convierte los tipos según necesites (aquí de int a double):

mito <(echo '
  double((1 + 2) * (3 + 4)) / 2.0
')

10.5

No existen variables en el lenguaje CEL, pero una expresión puede recibir un nombre y usarse en una expresión más amplia con la ayuda de la macro as de Mito. En este ejemplo, la expresión (1 + 1) evalúa al valor 2 y .as(n, ...) da a ese valor el nombre n para su uso en la expresión "one plus one is "+string(n):

mito <(echo '
  (1 + 1).as(n, "one plus one is "+string(n))
')

"one plus one is 2"

También es posible acumular información en un mapa y usarla más tarde en la expresión, como se demuestra aquí al usar with:

mito <(echo '
  { "key": "value" }.with({ "key2": "value2" }).as(data,
    {
      "data": data,
      "size": size(data),
    }
  )
')

{
  "data": {
    "key": "value",
    "key2": "value2"
  },
  "size": 2
}

Mira ese ejemplo otra vez. Observa que la parte anidada, ({ "data": data, "size": size(data), }), nos da la forma del valor final. Es un mapa con las claves "data" y "size". Los valores de esas claves dependen de data, que la define la parte exterior de la expresión. Leer las expresiones de CEL desde adentro hacia afuera puede ayudar a ver rápidamente qué devolverán.

CEL no tiene declaraciones de flujo de control, como if, pero la ramificación condicional se puede hacer con el operador ternario:

mito <(echo '
  1 + 1 < 12 ? "few" : "many"
')

"few"

Los bucles ilimitados y la recursión no son compatibles, ya que CEL no es un lenguaje de Turing completo. Esto hace que el tiempo de ejecución sea predecible y proporcional al tamaño de los datos de entrada y a la complejidad de la expresión.

Aunque los bucles sin límites no son posibles en expresiones CEL individuales, puedes procesar listas y mapas con macros como map:

mito <(echo '
  [1, 2, 3].map(x, x * 2)
')

[2, 4, 6]

En esta sección, abordamos los siguientes temas:

• Textos, números, listas y mapas.
• Concatenación de texto.
• Operaciones matemáticas.
• Conversión de tipos.
• Condicionales.
• Nombrando subexpresiones.
• Procesando colecciones.

A continuación, veremos cómo hacer solicitudes HTTP.

Solicitudes

Mito extiende el CEL con la capacidad de realizar solicitudes HTTP:

mito <(echo '
  get("https://example.com").as(resp, string(resp.Body))
')

"..."

Las solicitudes se pueden construir explícitamente antes de que se ejecuten. Esto permite utilizar diferentes métodos HTTP y agregar encabezados y un cuerpo.

En este ejemplo, construimos una URL con la ayuda de format_query, agregamos un encabezado a la solicitud y parseamos el cuerpo de la respuesta con decode_json. Cuando se te da la opción -log_requests, Mito registra información detallada en formato JSON sobre cada solicitud y respuesta.

mito -log_requests <(echo '
  request("GET",
    "https://postman-echo.com/get?" + {
        "q": ["query value"]
     }.format_query()
  ).with({
    "Header": { "Accept": ["application/json"] }
  }).do_request().as(resp, {
    "status": resp.StatusCode,
    "data": resp.Body.decode_json(),
  })
')

{"time":"...","level":"INFO","msg":"HTTP request",...}
{"time":"...","level":"INFO","msg":"HTTP response",...}
{
  "data": {
    "args": {
      "q": "query value"
    },
    "headers": {
      "accept": "application/json",
      "accept-encoding": "gzip, br",
      "host": "postman-echo.com",
      "user-agent": "Go-http-client/2.0",
      "x-forwarded-proto": "https"
    },
    "url": "https://postman-echo.com/get?q=query+value"
  },
  "status": 200
}

Gestión del estado y evaluaciones

Ahora que ya vimos cómo realizar solicitudes y los conceptos básicos de CEL necesarios para producir el estado de salida deseado, veamos más de cerca qué debemos incluir en el estado de salida y cómo eso nos permite dirigir el procesamiento posterior.

El programa CEL de una integración debe asegurarse de que su estado de salida sea adecuado para su uso como entrada de la siguiente evaluación. La configuración establece el estado inicial, y eso debe repetirse en la salida con los cambios apropiados. Una forma sencilla de hacerlo es usar state.with({ ... }), para repetir el mapa de estado con algunas sobrescrituras. Un patrón común para programas pequeños es envolver todo el programa en state.with(), para que la propagación de estados no tenga que repetirse en cada rama que genere datos de salida (por ejemplo: éxito, errores).

Cuando hay valores de estado que se inicializan mediante una evaluación en lugar de estar codificados de forma fija en el estado de entrada inicial, el programa tendrá que comprobar si existe un valor antes de establecer el inicial. Eso es algo en lo que el soporte para sintaxis y tipos opcionales puede ayudar. Al usar un signo de interrogación antes del nombre del campo en una clave de mapa, el acceso se vuelve opcional: puede o no resolver a un valor, pero son posibles accesos opcionales adicionales y es fácil proporcionar un valor por defecto si no hay un valor presente:

mito -data <(echo '{}') <(echo '
  int(state.?counter.orValue(0)).as(counter,
    state.with({
      "counter": counter + 1,
      "want_more": counter + 1 < 3,
    })
  )
')

{ "counter": 1, "want_more": true }
{ "counter": 2, "want_more": true }
{ "counter": 3, "want_more": false }

En ese ejemplo, el valor del contador leído desde el estado se convierte en int porque todos los números se serializan en el estado como números de coma flotante, de acuerdo con las convenciones establecidas por el tipo Number de JSON y JavaScript. También debe tenerse en cuenta que Mito honra "want_more": true, pero cuando se ejecuta en la entrada CEL, la evaluación solo se repetiría si la salida también contiene eventos.

Es un requisito de los programas CEL ejecutados por la entrada CEL que devuelvan una clave "events" en su mapa de salida. Su valor puede ser una lista de mapas de eventos, una lista vacía o un solo mapa de eventos. El caso de evento único generalmente se utiliza para errores. El evento se publicará mediante la entrada, pero su valor también se registrará y, si estableces un valor de error.message, se usará para actualizar el estado de salud de la Fleet de la integración. Si tu programa produce un solo evento sin error, es mejor envolverlo en una lista.

Echa otro vistazo a la salida de nuestro programa de problemas de GitHub de antes:

{
  "url": "https://api.github.com/repos/elastic/integrations/issues",
  "per_page": 3,
  "max_pages": 3,
  "cursor": {
    "page": 2
  },
  "events": [
    { ... },
    { ... },
    { ... }
  ],
  "want_more": true
}

El programa gestionó eficazmente su estado, mediante:

• Valores de estado iniciales repetidos en url, per_pagey max_pages.
• Agregar un estado que debería persistir durante los reinicios en cursor.page.
• Devolver eventos listos para publicar en la lista events.
• Solicito una reevaluación inmediata con want_more: true.

Ahora que entiendes el acceso opcional y la gestión de estados, así como los conceptos básicos de CEL y las solicitudes HTTP, deberías poder leer el programa completo de incidencias de GitHub. Intenta ejecutarlo con Mito y experimentar con algunos cambios.

Revisión y recursos

En este artículo, analizamos qué es el lenguaje CEL y cómo se ha extendido en la biblioteca Mito para su uso en la entrada CEL. Vimos la flexibilidad de CEL en un programa de ejemplo que obtiene información de incidencias de la API de GitHub, y repasamos todos los detalles necesarios para comprender ese programa, incluidos el acceso a la configuración en el estado inicial, la interacción con las API HTTP, el retorno de eventos para su ingesta y la gestión del estado para ejecuciones posteriores del programa.

Para aprender más y construir integraciones mediante la entrada CEL, hay varios recursos que valen la pena explorar:

• Entrada CEL - documentación de Filebeat
• Documentación de Mito
• Lenguaje de expresión común - sitio web cel.dev
• Crear una integración - Documentación de Elastic

Y quizás el recurso más valioso para crear integraciones con la entrada CEL sea el código CEL de las integraciones existentes de Elastic, que se puede encontrar en GitHub:

cel.yml.hbs archivos en el repositorio de integraciones de Elastic - GitHub

1. ¡La nueva actualización de Swift está aquí! Los desarrolladores están ansiosos por probar las nuevas características.
2. ¡La nueva actualización de Swift está aquí! El nuevo álbum se lanzará el próximo mes.

Con este contexto añadido, deberíamos ser capaces de resolver el nombre "Swift" a la entidad correcta.

En la publicación anterior, configuramos nuestra lista de seguimiento y enriquecimos las entidades con contexto adicional. Al ver nuestros ejemplos anteriores, necesitamos tener, al menos, las siguientes dos entidades en la lista: Taylor Swift y Swift Programming Language. También explicamos cómo extraemos las menciones de entidades del texto. Ambos ejemplos extraerían "Swift". Con estos ingredientes en su lugar, la lista de vigilancia enriquecida y las entidades extraídas, finalmente estamos listos para presentar la estrella del espectáculo: la coincidencia de entidades.

Recuerda: Este es un prototipo didáctico diseñado para enseñar conceptos de emparejar entidades. Los sistemas de producción pueden usar diferentes modelos de lenguaje grandes (LLM), reglas de coincidencia personalizadas, pipelines de evaluación especializados o enfoques conjuntos que combinan varias estrategias de coincidencia.

El problema: Por qué la coincidencia es difícil

El lenguaje humano es algo extraordinario. Una de sus propiedades más interesantes es su creatividad infinita. Podemos generar y entender un número infinito de frases nuevas. ¿Es de extrañar, entonces, que las coincidencias exactas en la resolución de entidades sean raras? Los autores se esfuerzan por ser creativos cuando pueden. Sería bastante tedioso si tuviéramos que escribir y leer nombres completos cada vez que se menciona una entidad. Entonces, si bien las coincidencias exactas son fáciles, la realidad es que necesitamos un enfoque más sofisticado para la resolución de entidades: uno que sea lo suficientemente robusto para manejar al menos parte de la creatividad ilimitada de los autores humanos. Por eso dividimos el problema en dos pasos: usar Elasticsearch para recuperar candidatos plausibles a escala, y luego usar un LLM para evaluar si esos candidatos realmente se refieren a la misma entidad del mundo real.

La solución: Emparejamiento en tres pasos con evaluaciones transparentes de LLM

Estamos en medio de un cambio de paradigma en la forma en que usamos las computadoras. Así como el auge de internet nos llevó de la computación localizada a una red globalmente conectada, la IA generativa (GenAI) está cambiando fundamentalmente la forma en que se crean el contenido, el código y la información. De hecho, el prototipo educativo que acompaña a esta serie fue casi exclusivamente "codificado con onda" usando un LLM con indicaciones cuidadosas del autor. Esto no quiere decir que los LLM tengan o incluso alcancen el tipo de productividad inherente al lenguaje humano, pero sí significa que ahora tenemos un recurso poderoso para ayudar con la resolución de entidades.

Un patrón común que usamos con GenAI es Retrieval-Augmented Generation (RAG). Aquí, recuperación significa recuperar candidatos de entidades (no generar respuestas), y el LLM se utiliza estrictamente para la evaluación y explicación de coincidencias. Si bien podríamos pedirle a un LLM que nos ayude con la resolución de entidades de extremo a extremo, ese es un enfoque costoso, tanto en términos de tiempo como de dinero. La RAG ayuda a los LLM a hacer su trabajo mediante el uso de formas más eficientes de proporcionar contexto al LLM, lo que permite que el LLM ayude de manera eficiente con la resolución de la entidad.

Para la parte de recuperación de RAG, volvemos a Elasticsearch. Primero encontramos posibles coincidencias usando una combinación de coincidencia exacta, coincidencia con alias y búsqueda híbrida, que combina búsqueda por palabras clave y búsqueda semántica. Una vez que encontramos estas posibles coincidencias, las enviamos a un LLM para su evaluación. El LLM actúa como el evaluador final de coincidencias. También hacemos que el LLM explique su razonamiento, un diferenciador importante con otros sistemas de resolución de entidades. Sin estas explicaciones, la resolución de entidades es una caja negra; con ellas, podemos ver por nosotros mismos por qué una coincidencia tiene sentido.

Conceptos clave: Coincidencia de tres pasos, búsqueda híbrida y evaluación transparente del LLM

¿Qué es la coincidencia de tres pasos? Al inicio de este proyecto, planteamos la hipótesis de que la búsqueda semántica sería una parte crucial del sistema, pero no todas las coincidencias requieren una búsqueda tan sofisticada. Para encontrar coincidencias de manera eficiente, adoptamos un enfoque progresivo para solucionar el problema. Primero, buscamos coincidencias exactas mediante la búsqueda por palabra clave. Si encontramos dicha coincidencia, nuestro trabajo está terminado y podemos seguir adelante. Si falla la coincidencia exacta, recurrimos a la coincidencia de alias. En el prototipo, la coincidencia de alias también se efectúa usando la coincidencia exacta con palabras clave, para simplificar. En producción, puedes ampliar este paso con normalización, reglas de transliteración, coincidencia difusa o tablas de alias seleccionadas. Si aún no hemos encontrado una posible coincidencia en los dos primeros pasos, entonces es hora de incorporar la búsqueda semántica a través de la búsqueda híbrida de Elasticsearch con fusión de rango recíproco (RRF, por sus siglas en inglés).

¿Qué es la búsqueda híbrida? En Elasticsearch, puedes utilizar la búsqueda semántica para encontrar coincidencias significativas que tengan en cuenta el contexto. Elasticsearch se emplea ampliamente para la búsqueda vectorial y la recuperación híbrida. La similitud semántica es muy útil para el significado, pero no sustituye al filtrado estructurado (por ejemplo, por rangos de tiempo, ubicaciones o identificadores), y a menudo es innecesaria cuando se dispone de una coincidencia exacta. Elasticsearch hizo su marca con la búsqueda léxica, que es excelente en tareas donde la búsqueda semántica no encaja. Para aprovechar al máximo ambos enfoques, utilizamos la búsqueda léxica junto con la búsqueda semántica en una única consulta híbrida. Luego combinamos los resultados para encontrar las coincidencias más probables usando RRF. En el prototipo, los dos primeros resultados se convierten en posibles coincidencias que pueden enviarse para la evaluación del LLM.

¿Por qué una evaluación del LLM? Las evaluaciones y explicaciones del LLM permiten que nuestro sistema maneje la ambigüedad y el contexto de manera transparente. Esto es vital para casos como "el presidente", que podría referirse a múltiples entidades, dependiendo del contexto, pero también hace que cosas como los apodos y las variaciones culturales funcionen bien en el sistema. Por último, cuando consideramos tareas de misión crítica, como identificar entidades de listas de sanciones, necesitamos saber por qué se aceptó una coincidencia para poder confiar en el sistema. Fundamentalmente, el LLM no busca en todo el corpus; evalúa solo el pequeño conjunto de candidatos devuelto por Elasticsearch.

Resultados del mundo real: Coincidencia con el razonamiento del LLM

Un gran desafío para cualquier tarea de procesamiento de lenguaje natural es la creación de un documento de referencia, una "clave de respuestas" que nos dice cuáles son los resultados previstos. Sin esto, es casi imposible evaluar el rendimiento de un sistema en una tarea, pero crear un documento de este tipo puede ser un proceso laborioso. Para el prototipo de resolución de entidades, volvimos a recurrir a la GenAI para ayudar a configurar datos contra los que pudiéramos probar.

Primero definimos varios tipos de desafíos, como apodos y transliteraciones, y luego pedimos al LLM que creara una colección escalonada de sets de datos que se hiciera progresivamente más grande y desafiante para el sistema. La creación de los sets de datos fue menos sencilla de lo que cabría esperar. El LLM tenía una fuerte tendencia a "hacer trampa" al hacer demasiado fácil obtener la respuesta correcta. Por ejemplo, uno de los tipos de desafíos se centró en el contexto semántico. Este tipo incluyó cosas como resolver "autor ruso" a "León Tolstói". El LLM colocó incorrectamente "autor ruso", como alias de "León Tolstói", lo que eliminó la necesidad de hacer una búsqueda híbrida para encontrar la coincidencia.

Después de varias refactorizaciones para solucionar problemas como este, teníamos cinco niveles de sets de datos con los que trabajar. Los niveles 1 a 4 eran progresivamente más amplios y presentaban más tipos de desafíos. El Nivel 5 fue el "desafío definitivo" de sets de datos, compuesto por los ejemplos más complicados de todos los tipos de desafíos. Todos los datos de las pruebas están disponibles en el directorio de evaluación exhaustiva.

Para evaluar nuestro enfoque de resolución de entidades basado en indicaciones, centramos nuestra atención en los sets de datos de nivel 4. Una nota importante es que la evaluación se hizo como un experimento controlado para que pudiéramos concentrarnos en la calidad de la coincidencia de entidades. Los datos de la lista de vigilancia se enriquecieron previamente con contexto y las entidades se extrajeron del artículo antes de tiempo. Así se garantizó que la evaluación se centrara en la coincidencia y no en la precisión de la extracción. Esto aísla la calidad de la coincidencia; el rendimiento de extremo a extremo dependería adicionalmente de la recuperación de la extracción y la calidad del enriquecimiento.

Sets de datos de evaluación

El set de datos de evaluación de nivel 4 proporciona una prueba integral de las capacidades del sistema:[1]

• Entidades de la lista de vigilancia: 66 entidades de diversos tipos (personas, organizaciones, ubicaciones).
• Artículos de prueba: 69 artículos que abarcan casos de resolución de entidades del mundo real.
• Coincidencias esperadas: 206 coincidencias de entidades esperadas en todos los artículos.
• Tipos de desafíos: 15 tipos diferentes de desafíos que evalúan varios aspectos de la resolución de entidades.

Los tipos de desafíos incluidos en los sets de datos son:

• Apodos: "Bob Smith" → "Robert Smith" (siete artículos).
• Títulos y honoríficos: "Dr. Sarah Williams" → "Sarah Williams" (cinco artículos).
• Contexto semántico: "Autor ruso" → "León Tolstói" (ocho artículos).
• Nombres multilingües: Manejo de nombres en diferentes escrituras (seis artículos).
• Entidades comerciales: Variaciones del nombre corporativo (siete artículos).
• Referencias ejecutivas: "CEO de Microsoft" → "Satya Nadella" (cinco artículos).
• Líderes políticos: Referencias basadas en títulos (cinco artículos).
• Iniciales: "J. Smith " → "John Smith" (tres artículos).
• Variaciones en el orden de los nombres: Diferentes convenciones de ordenamiento de nombres (tres artículos).
• Nombres truncados: Coincidencias parciales de nombres (tres artículos).
• División de nombres: Nombres divididos en el texto (tres artículos).
• Espacios/guiones faltantes: Variaciones de formato (dos artículos).
• Transliteración: Coincidencia de nombres entre sistemas de escritura (dos artículos).
• Desafíos combinados: Varios desafíos en un artículo (seis artículos).
• Negocios complejos: Relaciones comerciales jerárquicas (cinco artículos).

Veamos cómo se desempeñó la resolución de entidades basada en indicaciones.

Rendimiento general

Los resultados muestran que la evaluación de coincidencias basada en LLM es muy prometedora, pero también revelan un importante problema de confiabilidad. Debido a que cada par de candidatos debe ser evaluado por el LLM, las fallas en la salida estructurada pueden suprimir la aceptación y la recuperación incluso cuando la recuperación está funcionando bien.

El problema de la tasa de error

Recuerda que el primer paso que damos en el prototipo es crear posibles pares de coincidencia usando Elasticsearch. Cada una de estas posibles coincidencias necesita ser evaluada por el LLM. Para procesar eficientemente todas esas coincidencias, agrupamos las llamadas a los LLM en batches. Esto reduce los costos y la latencia de la API, pero también aumenta el riesgo de obtener JSON malformado en la salida. A medida que aumenta el tamaño del batch, el JSON se vuelve más largo y complejo, lo que aumenta la probabilidad de que el LLM genere un JSON no válido. De aquí proviene la tasa de error del 30 %. En la evaluación, usamos un tamaño de batch de cinco coincidencias por solicitud. Incluso con este tamaño de batch conservador, seguimos viendo fallos en el análisis de JSON, lo que distorsiona significativamente los resultados de la evaluación.

Lo que sigue: Optimización de la integración del LLM

Ahora que hemos emparejado entidades usando la búsqueda semántica y la evaluación a cargo del LLM, tenemos un pipeline completo de resolución de entidades. Sin embargo, este enfoque introduce un nuevo modo de fallo cuando la evaluación del modelo es correcta, pero su salida no es utilizable. Podemos optimizar la integración de los LLM para mejorar la fiabilidad y la eficiencia de costos. En la próxima publicación, analizaremos cómo usar la llamada de funciones para una salida estructurada, que proporciona una estructura y seguridad de tipo garantizadas a la vez que reduce errores y costos.

Pruébalo tú mismo

¿Quieres ver la coincidencia de entidades en acción? Mira el cuaderno de Entity Matching para obtener una guía completa con implementaciones reales, explicaciones detalladas y ejemplos prácticos. El cuaderno te muestra exactamente cómo hacer coincidir entidades empleando la búsqueda de tres pasos, la búsqueda híbrida con RRF y la evaluación impulsada por LLM con razonamiento.

Recuerda: Este es un prototipo didáctico diseñado para enseñar los conceptos. Al construir sistemas de producción, considera factores adicionales, como la selección del modelo, la optimización de costos, los requisitos de latencia, la validación de calidad, el manejo de errores y la monitorización, que no están cubiertos en este prototipo orientado al aprendizaje.

Notas

1. Estos sets de datos son sintéticos y están diseñados con fines didácticos; se aproximan a desafíos reales pero no son representativos de ningún dominio de producción específico.

Nuestros benchmarks en un corpus de documentos de 20M muestran que Elasticsearch ofrece hasta 8 veces más rendimiento que OpenSearch para búsqueda vectorial filtrada, además de lograr mayores Recall@100 en las configuraciones que probamos. La ingeniería de contexto depende de más que la rápida recuperación de vectores. Los equipos también necesitan fuertes controles de relevancia, como búsqueda y filtrado híbridos, simplicidad operativa y rendimiento predecible, a medida que los flujos de trabajo se repiten. Pero como los agentes suelen ejecutar bucles de recuperación y razonamiento muchas veces por cada solicitud, la latencia de la recuperación se convierte en un factor multiplicador, por lo que las mejoras en este aspecto se traducen directamente en una mejor capacidad de respuesta de extremo a extremo y en un menor costo.

En la ingeniería de contexto, la recuperación no es un paso único. Los agentes y las aplicaciones ejecutan bucles repetidamente, como recuperar → razonar → recuperar, para refinar consultas, verificar hechos, reunir contexto fundamentado y completar tareas. Este patrón es común en los flujos de trabajo agénticos y en la Retrieval-Augmented Generation (RAG) iterativa. Como la recuperación puede invocarse muchas veces por cada consulta del usuario, agrega demora a la respuesta o aumenta los costos de infraestructura.

¿Por qué es crítico el rendimiento de la búsqueda de vectores?

Imagina un asistente de compras respondiendo la pregunta: "Necesito una mochila de equipaje de mano de menos de $60 que quepa una laptop de 15 pulgadas, sea resistente al agua y pueda llegar para el viernes".

En producción, el asistente rara vez emite una consulta vectorial y se detiene ahí. Ejecuta un ciclo de recuperación para crear el contexto correcto, y cada paso suele estar limitado por filtros, como disponibilidad, región, promesa de envío, reglas de marca y elegibilidad de políticas.

Paso 1: Interpretar la intención y traducirla a restricciones.

El agente convierte la solicitud en filtros estructurados y una consulta semántica, tales como:

• Filtros: En stock, entregable al código postal del usuario, entrega antes del viernes, precio inferior a $60, listado válido
• Consulta vectorial: "Mochila de equipaje de mano computadora portátil de 15 pulgadas resistente al agua"

Paso 2: Recuperar candidatos y luego refinar la selección.

A menudo repite la recuperación con variaciones para evitar perder buenas coincidencias:

• "mochila de viaje de equipaje de mano con funda para computadora portátil"
• "mochila de viaje resistente al agua de 15 pulgadas"
• “mochila de cabina ligera”

Cada consulta utiliza los mismos filtros de elegibilidad, porque recuperar elementos irrelevantes o no disponibles es un desperdicio de contexto.

Paso 3: Expandir para confirmar detalles y reducir el riesgo.

A continuación, el agente vuelve a consultar para verificar los atributos clave que influyen en la respuesta final:

• Palabras utilizadas para describir los materiales y la resistencia al agua
• Dimensiones y ajuste del compartimento de la computadora portátil
• Restricciones de la garantía o política de devolución
• Opciones alternativas si hay poco inventario

Esto es ingeniería de contexto en múltiples pasos: recuperar, razonar, recuperar, ensamblar.

¿Por qué la latencia y la recuperación son importantes para la ingeniería de contexto?

Estas interacciones pueden implicar decenas de llamadas de recuperación filtradas por sesión de usuario. Eso hace que la latencia por llamada sea un multiplicador directo en el tiempo de respuesta de extremo a extremo, y la baja recuperación obliga a reintentos adicionales o hace que el agente pierda elementos elegibles, lo que degrada la calidad de la respuesta.

Conclusión: En sistemas diseñados con contexto, los vecinos más cercanos aproximados (ANN, por su sigla en inglés) filtrados no son una sola consulta. Es una operación repetida bajo restricciones, por lo que el rendimiento de la búsqueda vectorial se nota enseguida en la latencia, la capacidad de procesamiento y el costo, incluso cuando el modelo de lenguaje grande (LLM) es el componente más visible.

Evaluación comparativa

Resultados

En el grafo 2, cada punto representa una configuración de prueba. Los mejores resultados aparecen hacia la parte superior izquierda, lo que significa una mayor recuperación con menor latencia. Los resultados de Elasticsearch se sitúan sistemáticamente más cerca de la esquina superior izquierda que los de OpenSearch, lo que indica una mayor velocidad y precisión con los mismos ajustes de carga de trabajo.

Algunas ideas clave

• s_n_r_value: La abreviatura de size_numCandidates_rescoreOversample (k y numCandidates iguales a numCandidates en estas pruebas), por ejemplo, 100_500_1 significa tamaño=100, numCandidates=500 y k=500, rescore oversample=1
• Recuperación: Mide Recall@100 para esa configuración
• Latencia promedio (ms): Latencia de extremo a extremo promedio por consulta
• Rendimiento: Búsquedas por segundo
• Recall %: Mejora relativa de recuperación de Elasticsearch frente a OpenSearch (Elasticsearch menos OpenSearch)/OpenSearch
• Latencia Xs: Latencia promedio de OpenSearch dividida por la latencia media de Elasticsearch
• Rendimiento Xs: rendimiento de Elasticsearch dividido por el rendimiento de OpenSearch

Por ejemplo, en 100_9000_1, OpenSearch tiene un promedio de 687 milisegundos por recuperación frente a 90 milisegundos en Elasticsearch, y en un bucle de recuperación de 10 pasos eso equivale a aproximadamente 10 × (687 - 90) = seis segundos de tiempo de espera adicional.

Consulta los resultados completos.

Metodología

Al usar Python para enviar las consultas y rastrear el tiempo de respuesta y otras estadísticas, enviamos las siguientes consultas a los motores. Ten en cuenta que el rendimiento de cualquier motor de búsqueda vectorial depende de cómo ajustes sus parámetros núcleo: cuántos candidatos considerar, cuán agresivamente volver a puntuar y cuánto contexto devolver. Estos ajustes afectan directamente tanto la exhaustividad (la probabilidad de encontrar la respuesta correcta) como la latencia (la rapidez con la que obtienes los resultados).

En nuestras pruebas comparativas, empleamos la misma configuración de candidatos, repuntuación y tamaño de resultados que normalmente ajustarías en un bucle de recuperación basado en agentes, y medimos el rendimiento de Elasticsearch bajo esa carga de trabajo. Luego ejecutamos OpenSearch con la misma configuración como referencia.

OpenSearch

GET /_search
{
  "query": {
    "knn": {
      "": {
        "vector": [...],
        "k": ,
        "method_parameters": {
          "ef_search": 
        },
        "rescore": {
          "oversample_factor": 
        },
        "filter": {
          
        }
      }
    }
  },
  "size": ,
  "_source": {
    "excludes": [
      ""
    ]
  }
}

• "size": <RESULT_SIZE>: Número de resultados devueltos al cliente. En esta prueba de rendimiento, el tamaño del conjunto de datos es 100 para calcular el Recall@100.
• "k": <NUMBER_OF_CANDIDATES>: El número de candidatos a vecinos más cercanos.
• "ef_search": <NUMBER_OF_CANDIDATES>: El número de vectores a examinar.
• "oversample_factor": <OVERSAMPLE>: ¿Cuántos vectores candidatos se recuperan antes de volver a calcular la puntuación?

Elasticsearch

GET /_search
{
  "query": {
    "knn": {
      "field": "",
      "query_vector": [...],
      "k": ,
      "num_candidates": ,
      "rescore_vector": {
        "oversample": 
      },
      "filter": {
        
      }
    }
  },
  "size": ,
  "_source": {
    "excludes": [
      ""
    ]
  }
}

• "size": <RESULT_SIZE>: Número de resultados devueltos al cliente. En esta prueba de rendimiento, el tamaño del conjunto de datos es 100 para calcular el Recall@100.
• "k": <NUMBER_OF_CANDIDATES>: Número de vecinos más cercanos que se debe devolver desde cada shard.
• "num_candidates": <NUMBER_OF_CANDIDATES>: Número de candidatos de vecinos más cercanos a considerar por shard mientras se realiza la búsqueda de knn.
• "oversample": <OVERSAMPLE>: ¿Cuántos vectores candidatos se recuperan antes de volver a calcular la puntuación?

Ejemplo

Knn la búsqueda, (100_500_1), sería de la siguiente manera:

OpenSearch

GET search_catalog_128/_search
{
  "query": {
    "knn": {
      "search_catalog_embedding": {
        "vector": [...],
        "k": 500,
        "method_parameters": {
          "ef_search": 500
        },
        "rescore": {
          "oversample_factor": 1
        },
        "filter": {
          "term": {
            "valid": true
          }
        }
      }
    }
  },
  "size": 100,
  "_source": {
    "excludes": [
      "search_catalog_embedding"
    ]
  }
}

Elasticsearch

GET search_catalog_128/_search
{
  "query": {
    "knn": {
      "field": "search_catalog_embedding",
      "query_vector": [...],
      "k": 500,
      "num_candidates": 500,
      "rescore_vector": {
        "oversample": 1
      },
      "filter": {
        "term": {
          "valid": true
        }
      }
    }
  },
  "size": 100,
  "_source": {
    "excludes": [
      "search_catalog_embedding"
    ]
  }
}

La configuración completa, junto con scripts de Terraform, manifiestos de Kubernetes y el código de benchmarking, está disponible en este repositorio en la carpeta es-9.3-vs-os-3.5-vector-search.

La configuración del cluster

Ejecutamos nuestras pruebas en seis servidores cloud e2-standard-16, cada uno con 16 vCPUs y 64 GB de RAM. En cada servidor, asignamos 15 vCPUs y 56 GB de RAM a cada pod de Kubernetes que ejecutaba el nodo del motor de búsqueda, con 28 GB reservados para el heap de JVM.

Los clústeres ejecutaban Elasticsearch 9.3.0 y OpenSearch 3.5.0 (Lucene 10.3.2). Dado que ambos sistemas emplean la misma versión de Lucene en esta prueba comparativa, las diferencias de rendimiento y latencia que observamos no pueden atribuirse únicamente a Lucene, sino que reflejan diferencias en la forma en que cada motor integra y ejecuta la recuperación y recalculación filtradas del algoritmo k-vecinos más cercanos (kNN). Usamos un único índice con tres shards primarios y una réplica (es decir, 6 shards en total, 1 por nodo).

También usamos un servidor independiente en la misma región para ejecutar el cliente de pruebas de rendimiento y recopilar estadísticas de tiempos.

El set de datos

Para este benchmark, empleamos un set de datos de incrustación de catálogos de tipo comercio electrónico a gran escala con 20 millones de documentos, diseñado para reflejar la recuperación vectorial filtrada a escala del mundo real.

Cada documento representa un artículo del catálogo e incluye:

• Un vector denso incrustado de 128 dimensiones utilizado para la recuperación aproximada de kNN.
• Campos estructurados de metadatos usados para filtrar (por ejemplo, validez y disponibilidad de artículos más otras restricciones del catálogo) que permiten el patrón común de producción de recuperar a los vecinos más cercanos, pero solo dentro de un subconjunto elegible.

Elegimos este set de datos porque captura el núcleo del desafío principal de rendimiento que vemos en sistemas agentes y de estilo RAG en producción: la similitud vectorial por sí sola no es suficiente, la recuperación está frecuentemente limitada por filtros y el sistema debe mantener una alta recuperación a la vez que mantiene baja la latencia bajo esas restricciones. En comparación con sets de datos más pequeños de estilo QA, un corpus de 20M de documentos también refleja mejor la escala y la presión de los candidatos que enfrentan los sistemas de ANN filtrados en la práctica.

Conclusión

En las arquitecturas de IA modernas, especialmente aquellas construidas alrededor de la ingeniería de contexto, la velocidad de búsqueda vectorial no es un detalle de implementación menor. Es un multiplicador. Cuando los agentes y los flujos de trabajo iteran a través de recuperar → razonar → recuperar, el rendimiento de la recuperación da forma directamente a la latencia de extremo a extremo, al rendimiento y a la calidad del contexto que se introduce en el modelo.

En nuestras pruebas de referencia, Elasticsearch ofreció consistentemente una mayor recuperación con menor latencia que OpenSearch en escenarios donde la corrección depende de recuperar el documento correcto, no solo de un vector similar. En un set de datos controlado, la diferencia es clara, y en producción esos avances se acumulan a lo largo de grandes volúmenes de llamadas de recuperación, lo que mejora la capacidad de respuesta, aumenta el margen de capacidad y reduce los costos de infraestructura.

Lecturas adicionales

1. ¿Qué es la ingeniería de contexto?
2. La evolución de la búsqueda híbrida y la ingeniería de contexto
3. El impacto de la relevancia en la ingeniería de contexto para agentes de IA

La familia incluye dos modelos:

• jina-embeddings-v5-text-small
• jina-embeddings-v5-text-nano

Estos modelos son el resultado exitoso de una receta de entrenamiento innovadora para modelos de incrustación. Ambos superan a modelos varias veces más grandes, lo que genera ahorros en memoria y recursos informáticos y responde más rápido a las solicitudes.

El modelo jina-embeddings-v5-text-small tiene 677 millones de parámetros, admite una ventana de contexto de entrada de 32 768 tokens y produce incrustaciones de 1024 dimensiones por defecto.

jina-embeddings-v5-text-nano Pesa aproximadamente un tercio del tamaño de su hermano, con 239 millones de parámetros y una ventana de contexto de entrada de 8192 tokens, lo que produce incrustaciones compactas de 768 dimensiones.

Estos dos modelos son los mejores en su categoría en cuanto al rendimiento general en la evaluación comparativa MMTEB (MTEB multilingüe). Entre los modelos con menos de 500 millones de parámetros, jina-embeddings-v5-text-nano es el de mejor rendimiento, a pesar de tener menos de 250 millones de parámetros, y el modelo jina-embeddings-v5-text-small es el líder entre los modelos de incrustación multilingüe con menos de 750 millones de parámetros.

Estos modelos están disponibles a través del Elastic Inference Service (EIS), mediante una API en línea y están disponibles para alojamiento local. Para obtener instrucciones sobre cómo acceder a los modelos jina-embeddings-v5-text, consulta la sección “Primeros pasos” a continuación.

Los modelos de incrustación y la indexación semántica aumentan considerablemente la precisión de los algoritmos de búsqueda, pero también tienen otros usos para tareas relacionadas con la similitud semántica y la extracción de significado, por ejemplo:

• Búsqueda de textos duplicados.
• Reconocimiento de paráfrasis y traducciones.
• Descubrimiento de temas.
• Motores de recomendación.
• Análisis de sentimiento e intención.
• Filtrado de spam.
• Y muchos otros.

Características

Esta nueva familia de modelos cuenta con varias características diseñadas para mejorar la relevancia y reducir costos.

Optimización de tareas

Optimizamos los modelos jina-embeddings-v5-text para cuatro tipos generales de tareas:

La optimización para una tarea suele implicar tener que renunciar a otra, por lo que la mayoría de los modelos de incrustación solo tienen un rendimiento competitivo para un tipo de tarea. Pero los modelos jina-embeddings-v5-text pueden especializarse en las cuatro áreas sin comprometer el entrenamiento de adaptadores de Low-Rank Adaptation (LoRA) específicos para cada tarea.

Los adaptadores de LoRA son un tipo de plugin para un modelo de AI que cambia drásticamente su comportamiento y solo aumenta ligeramente el tamaño total. En lugar de tener un modelo completo para cada tarea, cada uno con cientos de millones de parámetros, la familia de modelos jina-embeddings-v5-text te permite usar solo un modelo con un adaptador de LoRA compacto para cada tarea. Esto ahorra memoria, espacio de almacenamiento y costos de inferencia.

Incrustaciones truncadas

Entrenamos los modelos jina-embeddings-v5-text utilizando Aprendizaje de representación de Matryoshka, que te permite reducir tus incrustaciones a tamaños más pequeños con un costo mínimo para su calidad.

Por defecto, jina-embeddings-v5-text-small genera vectores de incrustación de 1024 dimensiones, cada uno representado por un número de 16 bits, lo que hace que cada incrustación tenga 2 KB de tamaño. En el caso de una gran colección de documentos, esto puede suponer una gran cantidad de datos que almacenar, y la búsqueda en una base de datos vectorial llena de incrustaciones es proporcional tanto al tamaño de la base de datos como al número de dimensiones que tiene cada vector almacenado.

Pero puedes simplemente reducir a la mitad el tamaño de las incrustaciones (desechar 512 de las 1024 dimensiones) y ocupar la mitad del espacio mientras duplicas las velocidades de búsqueda. Esto tiene un impacto en el rendimiento. Eliminar parte de la información reduce la precisión. Sin embargo, como muestra el grafo siguiente, incluso al eliminar la mitad de la incrustación, el rendimiento solo se reduce ligeramente:

Siempre y cuando tus incrustaciones tengan al menos 256 dimensiones, la pérdida de precisión debería ser bastante pequeña. Sin embargo, por debajo de ese nivel, la relevancia y la precisión se deterioran rápidamente.

Las incrustaciones truncadas como esta permiten a los usuarios gestionar sus propias compensaciones entre precisión y costos de computación. Te dan las herramientas para obtener grandes ganancias de eficiencia y grandes ahorros de costos de tu AI de búsqueda.

Cuantización robusta

La cuantización es otra forma de reducir el tamaño de las incrustaciones. En lugar de desechar parte de cada incrustación, la cuantización reduce la precisión de los números en la incrustación. Los modelos jina-embeddings-v5-text generan incrustaciones con números de 16 bits, pero podemos redondear esos números, reduciendo su precisión y la cantidad de bits necesarios para almacenarlos. En el caso más extremo, podemos reducir cada número a un bit (0 o 1), comprimiendo las incrustaciones predeterminadas de 1024 dimensiones jina-embeddings-v5-textde 2 kilobytes a 128 bytes, una reducción del 94 % solo por cuantización binaria. Al igual que para el truncamiento, esto produce grandes ahorros en memoria y costos de computación. Sin embargo, al igual que el truncamiento, la cuantización reduce la precisión de las incrustaciones.

Entrenamos los modelos de jina-embeddings-v5-text para que funcionen con Better Binary Quantization de Elasticsearch al minimizar esa pérdida de precisión, y las pruebas de evaluación comparativa de incrustaciones binarizadas de estos modelos muestran un rendimiento casi igual al de sus equivalentes no binarizados. Consulta el reporte técnico para obtener estudios detallados sobre el rendimiento de la binarización.

Rendimiento multilingüe

Muchos modelos de incrustación son multilingües porque se entrenaron con materiales que incluyen un gran número de idiomas. Pero eso no significa que todos funcionen igual de bien en todos los idiomas compatibles.

Identificamos 211 idiomas en la evaluación comparativa multilingüe MMTEB y los separamos para poder comparar nuestros modelos con modelos similares idioma por idioma. La imagen de abajo resume nuestros resultados como un mapa de calor. Cada parche es un idioma (identificado por su código ISO-639), y cuanto más verde sea, mejor rendimiento tuvo el modelo en comparación con el promedio de modelos similares:

Aunque la precisión varía entre idiomas, los modelos jina-embeddings-v5-text son de última generación o casi lo son en la mayoría de los idiomas del mundo.

Para obtener detalles sobre el rendimiento multilingüe, consulta el reporte técnico jina-embeddings-v5-text.

Jina en Elastic: IA nativa de última generación para búsqueda

Con los modelos jina-embeddings-v5-text en EIS, puedes ejecutar modelos de incrustación multilingüe de alto rendimiento de forma nativa en Elasticsearch, con inferencia totalmente gestionada y acelerada por GPU y sin infraestructura para aprovisionar o escalar. Los modelos jina-embeddings-v5-text amplían el creciente catálogo de modelos EIS con modelos compactos y multilingües impulsados por los últimos desarrollos en AI. Estos modelos tienen un rendimiento de última generación en recuperación de información y análisis de datos estándar, y ofrecen un soporte multilingüe inigualable que abarca todo el globo.

Con dos modelos de tamaños muy diferentes, los usuarios pueden determinar cuál es el más adecuado para sus aplicaciones y presupuestos. Además, con incrustaciones sólidas que siguen siendo eficientes cuando se truncan a tamaños más pequeños o se cuantifican con menor precisión, los modelos jina-embeddings-v5-text ofrecen oportunidades para ahorros concretos adicionales en costos de almacenamiento y computación, así como en latencia de procesamiento.

Con la familia jina-embeddings-v5-text , Jina Reranker y la rápida búsqueda vectorial y BM25 de Elastic, los usuarios ahora tienen acceso a la búsqueda híbrida de última generación de extremo a extremo de Elastic. Cuando necesitas los resultados más relevantes, ya sea para pipelines de Retrieval-Augmented Generation (RAG), aplicaciones de búsqueda o análisis de datos, Elastic con modelos de AI de búsqueda Jina ofrece una calidad estable y rentable.

Primeros pasos

Los modelos jina-embeddings-v5-text están completamente integrados en EIS y puedes usarlos al configurar el campotype en semantic_text al crear tu índice y especificar el modelo (jina-embeddings-v5-text-small o jina-embeddings-v5-text-nano) en el campo inference_id , como en este ejemplo:

PUT multilingual-semantic-index
{
  "mappings": {
    "properties": {
      "content": {
        "type": "semantic_text",
        "inference_id": ".jina-embeddings-v5-text-small"
      }
    }
  }
}

# Ingest data about France
POST multilingual-semantic-index/_doc
{
  "content": "The capital of France is Paris"}

GET multilingual-semantic-index/_search
{
  "query": {
    "semantic": {
      "field": "content",
      "query": "What is the French capital?"
    }
  }
}

Elasticsearch selecciona automáticamente el adaptador de LoRA adecuado durante la indexación y la recuperación. Las dimensiones de incrustación (consulta la sección “Incrustaciones truncadas” anterior) se pueden establecer al crear un endpoint de inferencia personalizado.

Consulta la documentación de Elasticsearch para obtener más información sobre el uso de modelos jina-embeddings-v5-text .

Más información

Para obtener más información sobre los modelos jina-embeddings-v5-text, lee las notas de lanzamiento en el blog de Jina AI y el reporte técnico, con información técnica más detallada sobre el rendimiento y el nuevo procedimiento de entrenamiento innovador de Jina AI. Para obtener información sobre cómo descargar y ejecutar estos modelos localmente, visita la jina-embeddings-v5-text página de la colección en Hugging Face.

Los modelos de Jina AI están disponibles bajo una licencia CC-BY-NC-4.0, así que puedes descargarlos y probarlos libremente, pero para uso comercial, ponte en contacto con Ventas de Elastic.

En este artículo, aprenderás cómo puedes utilizar el parámetro de puntuación mínima para aumentar la precisión de tus resultados de búsqueda semántica. Si deseas probar los ejemplos en esta publicación de blog, ve al cuaderno de Jupyter asociado.

Antecedentes: Precisión y recuperación

En la búsqueda, la relevancia, la precisión y la recuperación son conceptos clave. Se recomienda encarecidamente a todo lector que no esté familiarizado que se interiorice sobre estos conceptos. A continuación se presenta un resumen.

• Precisión: La fracción de resultados de búsqueda devueltos que son relevantes para el usuario.
• Recuerda: La fracción de todos los documentos relevantes del corpus que se incluyen en el conjunto de resultados de búsqueda.

O, en otras palabras, la precisión está devolviendo solo resultados relevantes; y la recuperación está devolviendo todos los resultados relevantes. Como puedes imaginar, estos son, a menudo, requisitos contradictorios. La búsqueda semántica tiende a tener una recuperación muy alta, pero puede tener dificultades con la precisión. Continúa leyendo para saber cómo moverte por esta propiedad.

Introducción del parámetro de puntaje mínimo

El parámetro "min_score" nos permite mejorar la precisión al establecer una puntuación mínima, lo que truncará el conjunto de resultados y eliminará cualquier coincidencia con una puntuación inferior al umbral definido. A continuación se muestra un ejemplo sencillo:

GET search-movies/_search
{
  "retriever": {
    "linear": {
      "min_score": 4,
      "retrievers": [
        ...
      ]
    }
  }
}

Normalizando la puntuación.

Establecer una puntuación mínima está bien; sin embargo, no todos los modelos semánticos devuelven una puntuación adecuada para un umbral estático. ELSER, por ejemplo, devuelve una puntuación que no tiene límite. Algunas puntuaciones de un modelo denso están estrechamente agrupadas y solo tienen sentido en el contexto de la consulta específica.

Para la mayoría de los casos de búsqueda semántica, recomendamos usar un enfoque de normalización antes de aplicar el "min_score". La normalización garantiza que la puntuación del documento esté dentro de un intervalo definido. Elasticsearch ofrece dos normalizadores, "l2_norm" y "minmax". El más comúnmente usado es "minmax", ya que es fácil de entender y funciona bien en muchos escenarios. Las propiedades clave de "minmax" incluyen:

• Las puntuaciones de los documentos se distribuyen entre 0 y 1.
• El documento con la puntuación más alta siempre tiene una puntuación de 1.
• El documento con la puntuación más baja siempre tiene una puntuación de 0.
  • Esto puede hacer que sea menos adecuado para la búsqueda por palabras clave. Consulta la sección “Búsqueda híbrida” para más información.

A continuación se muestra un ejemplo de una consulta semántica normalizada con min_score. El tamaño de la ventana de clasificación se ha aumentado a 500 para permitirnos devolver una lista más larga de resultados de búsqueda, comenzando en 100.

GET search-movies/_search
{
  "size": 100,
  "_source": [
    "title", "overview"
  ],
  "retriever": {
    "linear": {
      "rank_window_size": 500,
      "min_score": 0.25,
      "retrievers": [
        {
          "normalizer": "minmax",
          "retriever": {
            "standard": {
              "query": {
                "semantic": {
                  "field": "overview_vector",
                  "query": "superhero movie"
                }
              }
            }
          }
        }
      ]
    }
  }
}

El tamaño se ha establecido en un valor más alto de lo que normalmente se ve en producción. Esto es para que podamos inspeccionar la calidad de los resultados de búsqueda y ajustar los resultados.

Búsqueda híbrida usando el retriever lineal

Para la búsqueda híbrida, el enfoque más sencillo es normalizar todos las puntuaciones, asignar ponderaciones y aplicar una puntuación mínima. Ten en cuenta que al elegir ponderaciones con una suma de 1, mantienes la puntuación total dentro de un rango de 0–1. Esto hace que sea más fácil entender las puntuaciones finales y afinar min_score. A continuación se muestra un ejemplo:

GET search-movies/_search
{
  "size": 100,
  "_source": ["title", "overview","keywords"],
  "retriever": {
    "linear": {
      "rank_window_size": 500,
      "min_score": 0.25,
      "retrievers": [
        {
          "weight": 0.6,
          "normalizer": "minmax",
          "retriever": {
            "standard": {
              "query": {
                "semantic": {
                  "field": "overview_vector",
                  "query": "superhero movie"
                }
              }
            }
          }
        },
        {
          "weight": 0.4,
          "normalizer": "minmax",
          "retriever": {
            "standard": {
              "query": {
                "multi_match": {
                  "query": "superhero movie",
                  "fields": ["overview","keywords", "title"],
                  "type": "cross_fields",
                  "minimum_should_match": "2"
                }
              }
            }
          }
        }
      ]
    }
  }
}

Búsqueda híbrida usando RRF.

Con BM25, a menudo controlamos la precisión por otros medios, usando, por ejemplo, el operador de AND o minimum_should_match. Además, las consultas que consisten en términos únicos, precisos y poco frecuentes naturalmente generarán resultados con pocos resultados de búsqueda, a menudo todos muy relevantes. Esto puede llevar a:

• Los resultados más lejanos en el resultado reciben una puntuación normalizada baja en el recuperador BM25, incluso si la puntuación absoluta de BM25 está cerca de las puntuaciones más altas.
• Al agregar una puntuación BM25 muy baja a la puntuación semántica, el total puede aproximarse a la puntuación semántica.
• La falta de contribución de la puntuación BM25 puede hacer que el documento sea descartado por el min_score threshold.

Como solución, podemos utilizar la fusión de rangos recíprocos (RRF) para combinar BM25 y los resultados semánticos. RRF consigue sortear el desafío de comparar puntuaciones de diferentes algoritmos de búsqueda al colocar el foco en la posición en cada conjunto de resultados. En este escenario, la min_score solo se aplica al recuperador semántico.

GET search-movies/_search
{
  "_source": ["title", "overview","keywords"],
  "retriever": {
    "rrf": {
      "rank_window_size": 500,
      "retrievers": [
        {
          "linear": {
            "rank_window_size": 500,
            "min_score": 0.25,
            "retrievers": [
              {
                "normalizer": "minmax",
                "retriever": {
                  "standard": {
                    "query": {
                      "semantic": {
                        "field": "overview_vector",
                        "query": "superhero movie"
                      }
                    }
                  }
                }
              }
            ]
          }
        },
        {
          "standard": {
            "query": {
              "multi_match": {
                "query": "superhero movie",
                "fields": ["overview", "keywords","title"],
                "type": "cross_fields",
                "minimum_should_match": "2"
              }
            }
          }
        }
      ]
    }
  }
}

Conclusión

Al usar min_score, hemos demostrado cómo podemos reducir el número de falsos positivos en nuestros conjuntos de resultados causados por la alta recuperación de algoritmos de búsqueda semántica. Para saber más sobre los recuperadores, consulta esta publicación de blog y la documentación de Elasticsearch.

Gestión de dependencias en Elastic

En Elastic, tenemos que gestionar cientos o incluso miles de repositorios, tanto privados como públicos. Cuando se descubre una CVE crítica, necesitamos respuestas y acciones inmediatas: ¿qué repositorios son vulnerables? ¿Con qué rapidez podemos solucionarlos? Además de la seguridad, surgen cuestiones relacionadas con la productividad: ¿cómo podemos propagar rápidamente el lanzamiento de una nueva versión de un paquete a todos los repositorios que dependen de él, sin dedicar demasiado tiempo a tareas manuales?

El disparador inicial para buscar formas de hacer la gestión de dependencias fue la necesidad de establecer una base segura con actualizaciones automatizadas para reducir los CVEs. Después de considerar cuidadosamente las soluciones para la gestión de dependencias, empezamos a trabajar en una infraestructura autohospedada. Usábamos nuestro propio clúster de Kubernetes para ejecutar Mend Renovate Community Self-Hosted. La idea era poder ofrecer una plataforma de gestión de dependencias a la que nuestros usuarios pudieran acceder de forma autónoma.

El experimento inicial tuvo éxito, así que cada vez más equipos comenzaron a implementar nuestra plataforma y usarla en el ciclo de vida de sus repositorios diarios para actualizaciones y parches CVE. Esto sucedió tan rápido que pronto alcanzamos el límite de nuestra instalación autohospedada.

El reto: ¿Cómo podemos escalar una plataforma de gestión de dependencias en una gran organización con una cantidad significativa de repositorios?

Nuestra plataforma de gestión de dependencias procesaba un repositorio a la vez, entonces el modelo de procesamiento secuencial no podía seguir el ritmo debido a la gran cantidad de repositorios que tenemos. Ya habíamos identificado que el problema residía en el concepto de que una sola instancia de nuestra herramienta de gestión de dependencias podría procesar nuestra gran y siempre creciente lista de repositorios. Los repositorios esperaban en una cola, a veces durante muchas horas. Más del 50 % de nuestros repositorios ni siquiera se procesaban diariamente. Eso significa que más del 50 % de nuestros repositorios esperaron más de 24 horas entre los escaneos.

Los grandes repositorios creaban cuellos de botella mayores, debido a sus grandes bases de código y a sus múltiples PRs abiertas. Los eventos de webhook de GitHub interrumpieron la secuencia. Automerge se volvió poco confiable debido a que el tiempo de escaneo era impredecible. Habíamos hecho una promesa a nuestros usuarios sobre la frecuencia de los escaneos y no pudimos cumplirla.

La decisión de integrarnos internamente: satisfacer las necesidades únicas de escalabilidad y seguridad de Elastic

Aunque considerábamos opciones comerciales, como la edición Renovate autohospedada empresarial de Mend, internamente en Elastic teníamos algunas iniciativas clave en marcha.

Nuestra decisión de crear una plataforma interna se basó en el reconocimiento de que solo una solución altamente personalizada podría satisfacer los requisitos específicos e innegociables de Elastic:

1. Inversión en nuestra plataforma interna para desarrolladores: en ese momento, ya habíamos comenzado a invertir considerablemente en nuestra plataforma interna para desarrolladores. Estábamos discutiendo y diseñando formas en las que cada uno de nuestros servicios pudiera encajar. Esto significaba que queríamos probar nuestras propias reglas y prácticas para nuestra plataforma de gestión de dependencias. Además de eso, entraban en juego nuevas pautas y queríamos diseñar la plataforma antes de los eventos.
2. Integración nativa y personalización del flujo de trabajo: requeríamos una integración directa con nuestras herramientas y procesos internos. Por ejemplo, queríamos centralizar la configuración como código con nuestro Catálogo de servicios (Backstage). Tenemos necesidades específicas sobre el uso de Backstage con las que queríamos que nuestra plataforma fuera compatible. Así que, aunque fuera posible usar las API de Renovate autohospedadas junto con nuestra automatización de Backstage, esto no cubriría completamente nuestros procesos internos.
3. Seguridad en profundidad específica de Elastic: nuestro cumplimiento de seguridad estricto requería mecanismos personalizados adaptados a nuestro ecosistema. Estábamos trabajando para fortalecer nuestro uso de “identidades no humanas”. Las medidas de seguridad implementadas implicaban que los métodos no estándar de autenticación en GitHub no funcionarían con una herramienta comercial que no fuera compatible con esta implementación interna. Nuestro flujo de trabajo incluía la implementación de un patrón de cifrado secreto de flujo de trabajo principal-secundario y el uso de tokens de GitHub transitorios y de un solo uso. La creación interna era la única forma práctica de integrar estas capas de seguridad únicas y minimizar la superficie de ataque en nuestro complejo entorno multinube.

La solución: Orquestación de flujo de trabajo para la gestión de dependencias

Nuestra solución partió del hecho de que queríamos basarnos en la herramienta de gestión de dependencias que ya usábamos, no reemplazarla y buscar otras soluciones. Había mostrado signos de su potencial, y su flexibilidad es importante para las distintas necesidades de toda nuestra organización. Consideramos diferentes soluciones, y lo que nos ayudó a decidir fueron las necesidades grandes y a veces especiales que tenemos que cubrir. Decidimos crear una plataforma de gestión de dependencias fiable y escalable, donde cada repositorio se procesa por sí mismo, lo que eliminaría los cuellos de botella y nos prepararía para crecer.

Diseñamos la plataforma mediante tres principios fundamentales:

1. Procesamiento en paralelo

Cada repositorio tiene su propio entorno de procesamiento de gestión de dependencias. No más colas. Nuestra concurrencia solo está limitada por la cantidad de recursos que gastamos. También aplicamos una programación distribuida inteligente para evitar que GitHub limite la velocidad.

2. Autoservicio

Usamos nuestro Catálogo de servicios (Backstage) para incorporar y gestionar automáticamente cualquier repositorio nuevo. Usamos nuestra propia definición de recursos para darle al usuario final la opción de seleccionar con qué frecuencia se procesará un repositorio, cuántos recursos quiere asignar a sus programaciones y si quiere desactivar o volver a activar el procesamiento por cualquier motivo. Planeamos agregar más opciones así a medida que las necesidades de nuestros usuarios evolucionen y se adapten mejor a la nueva instalación.

3. Alcance secreto reducido y aislamiento del espacio de nombres

Para aumentar la seguridad, suministramos a nuestros pods de gestión de dependencias tokens efímeros de GitHub que se generan al inicio de cada flujo de trabajo. Además, aislamos nuestras cargas de trabajo en espacios de nombres específicos para que solo se les proporcionen los secretos necesarios. Controlamos a qué secretos puede acceder cada uno de los flujos de trabajo de gestión de dependencias mediante Kubernetes RBAC. También utilizamos el cifrado para propagar el token de GitHub desde los flujos de trabajo principales a los secundarios.

Reconstruimos nuestra plataforma mediante Kubernetes y, al aprovechar el poder de Kubernetes, Argo Workflows impulsa la lógica de nuestros procesos, y Renovate CLI está configurado para escanear y procesar un repositorio a la vez.

La belleza: estamos utilizando proyectos de código abierto probados en batalla de una manera original, lo que ofrece nuevos ejemplos de trabajo para todos esos proyectos y, al mismo tiempo, aumenta la velocidad de desarrollo y consolida la reducción de CVE para nuestros equipos.

Arquitectura de gestión de dependencias: Cuatro microservicios

La plataforma cuenta con cuatro componentes personalizados:

Operador de los flujos de trabajo (Go/Kubebuilder)

Un operador de Kubernetes que gestiona el ciclo de vida del flujo de trabajo a través de tres definiciones de recursos personalizados (CRD):

• CRD de RepoConfig: Única fuente de verdad para la configuración de repositorios.

Así es como se define RepoConfig en el operador:

// RepoConfig is the Schema for the repoconfigs API
type RepoConfig struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty,omitzero"`

	// spec defines the desired state of RepoConfig
	// +required
	Spec RepoConfigSpec `json:"spec"`

	// status defines the observed state of RepoConfig
	// +optional
	Status RepoConfigStatus `json:"status,omitempty,omitzero"`
}

Y así es como se vería una instancia de RepoConfig:

apiVersion: workflows.elastic.co/v1
kind: RepoConfig
metadata:
  generation: 3
  name: elastic-test-repo
  namespace: dependency-management-operator
spec:
  owner: group:my-team
  renovate:
    config:
      resourceGroup: SMALL
      runFrequency: 4h
    enabled: true
  repository: elastic/test-repo

• CRD principal: Gestiona CronWorkflows para escaneos programados.

Dentro del bucle de reconciliación del controlador principal, nos aseguramos de que los flujos de trabajo se creen y se mantengan actualizados o incluso se eliminen si es necesario.

En primer lugar, obtienes algunos ajustes configurados globalmente para los flujos de trabajo:

func (r *ParentReconciler) reconcileSubResources(ctx context.Context, req ctrl.Request, parent *workflowsv1.Parent) error {
	logger := logf.FromContext(ctx)
	logger.Info("Reconcile SubResources for Parent", "name", req.NamespacedName)
	wfSet := workflowsettings.WorkflowSettings{
		RunFrequency:   parent.Spec.RunFrequency,
		ResourceGroups: "parent",
	}

Se asegura de que un configmap de mutex esté actualizado para evitar que flujos de trabajo similares se ejecuten juntos:

	cfMngr := resources.NewConfigMapManager(r.Client, r.Scheme, r.OperatorConfig.ParentNamespace)
	err := cfMngr.CreateOrUpdateSyncMutexConfigmap(ctx, fmt.Sprintf("%s%s", r.OperatorConfig.ResourcesPrefix, r.OperatorConfig.SyncMutexCfgMapName), strings.TrimPrefix(parent.Spec.Repository, "elastic/"), r.OperatorConfig.SemaphoreConcurrencyLimit)

Luego crea un gestor de flujo de trabajo que es la estructura que creará o actualizará los CronWorkflows y las plantillas de flujo de trabajo:

	wfMngr := resources.NewArgoWorkflowManager(r.Client,
		r.Scheme,
		curateResourceName(
			strings.ReplaceAll(parent.Spec.Repository, "/", "-"),
		),
		parent.Namespace,
		"parent-workflow",
		false).
		WithOrganization(r.OperatorConfig.GitHubOrg).
		WithRepoName(parent.Spec.Repository).
		Init(true, true).
		WithPrefix(r.OperatorConfig.ResourcesPrefix).
		WithWfTemplateName(r.OperatorConfig.ParentWorkflowTemplate).
		WithResources(wfSet.GetResourceCategory()).
		WithSchedule(wfSet.GetCronSchedule()).
		WithImagePullSecrets([]corev1.LocalObjectReference{{
			Name: r.OperatorConfig.WorkflowImagePullSecrets,
		}}).
		AddArgument(true, true, "extra_cli_args").
		SetArgument(true, false, "extra_cli_args", "none").
		AddTemplate(resources.NewParentDAGTemplateInstance()).
		AddTemplate(resources.NewWorkflowsTemplateInstance("check-child-workflows", r.OperatorConfig.WorkflowImagePullPolicy, r.OperatorConfig.WorkflowNodeSelector)).
		AddTemplate(resources.NewWorkflowsTemplateInstance("security", r.OperatorConfig.WorkflowImagePullPolicy, r.OperatorConfig.WorkflowNodeSelector)).
		AddTemplate(resources.NewWorkflowsTemplateInstance("submit-child-workflow", r.OperatorConfig.WorkflowImagePullPolicy, r.OperatorConfig.WorkflowNodeSelector))
	wfMngr.OverWriteCommand("submit-child-workflow", r.OperatorConfig.ChildNamespace)
	wfMngr.OverwriteWfTemplateName("parent-wftmpl")
	wfMngr.AddSynchronization(fmt.Sprintf("%s%s", r.OperatorConfig.ResourcesPrefix, r.OperatorConfig.SyncMutexCfgMapName), "{{workflow.parameters.repo_name}}")
	err = wfMngr.CreateOrUpdateCronWorkflow(ctx)
	if err != nil {
		return fmt.Errorf("failed to create or update cron workflow: %w", err)
	}
	err = wfMngr.CreateOrUpdateWorkflowTemplate(ctx)
	if err != nil {
		return fmt.Errorf("failed to create or update workflow template: %w", err)
	}
	return nil

• CRD infantil: Gestiona las plantillas de flujo de trabajo con recursos por repositorio.

El controlador secundario tiene un deber de reconciliación similar al del padre, pero esta vez es responsable de las plantillas de flujo de trabajo en el espacio de nombres secundario que se activarán por los flujos de trabajo principales.

func (r *ChildReconciler) reconcileSubResources(ctx context.Context, req ctrl.Request, child *workflowsv1.Child) error {
	logger := logf.FromContext(ctx)
	logger.Info("Reconcile SubResources for Child", "name", req.NamespacedName)
	wfSet := workflowsettings.WorkflowSettings{
		ResourceGroups: child.Spec.ResourceCategory,
	}
	wfMngr := resources.NewArgoWorkflowManager(r.Client,
		r.Scheme,
		curateResourceName(
			strings.ReplaceAll(child.Spec.Repository, "/", "-"),
		),
		child.Namespace,
		"runner",
		true).
		Init(false, true). // only manage workflow template
		WithPrefix(r.OperatorConfig.ResourcesPrefix).
		WithSuffix("-child-wftmpl").
		WithRepoName(child.Spec.Repository).
		WithOrganization(r.OperatorConfig.GitHubOrg).
		WithResources(wfSet.GetResourceCategory()). // will override resources of presets if set
		WithImagePullSecrets([]corev1.LocalObjectReference{{
			Name: r.OperatorConfig.WorkflowImagePullSecrets,
		}}).
		AddTemplate(resources.NewWorkflowsTemplateInstance("runner", r.OperatorConfig.WorkflowImagePullPolicy, r.OperatorConfig.WorkflowNodeSelector)).
		AddArgument(false, true, "repo_full_name").
		AddArgument(false, true, "repo_name").
		AddArgument(false, true, "encrypted_token").
		AddArgument(false, true, "extra_cli_args")
	wfMngr.OverWriteCommand("runner", r.OperatorConfig.ChildNamespace)
	err := wfMngr.CreateOrUpdateWorkflowTemplate(ctx)
	if err != nil {
		return fmt.Errorf("failed to create or update workflow template: %w", err)
	}
	return nil
}

El patrón de controlador múltiple proporciona una clara separación: el controlador RepoConfig maneja la incorporación/eliminación, el controlador principal administra la programación y el controlador secundario maneja las plantillas de ejecución.

Puerta de enlace de eventos de GitHub (Go)

Un proxy de webhook seguro que recibe webhooks de GitHub, verifica firmas, filtra por organización/repositorio y los redirige a Argo Events. Creamos 10 sensores distintos que respondían a interacciones en paneles de dependencias, eventos de relaciones públicas y actualizaciones de paquetes.

Este gateway permite la integración con las aplicaciones de GitHub de la siguiente manera:

• Verifica las firmas entrantes de webhook de GitHub para mayor seguridad.
• Reenvía eventos válidos al EventSource de Argo Events con todos los encabezados relevantes y la autenticación.
• También configuramos un AuthSecret en EventSource y lo proporcionamos como un encabezado Bearer en las solicitudes reenviadas.
• Proporcionamos logging, métricas y lógica de reintentos.

Realiza varias validaciones en cada solicitud de evento de GitHub.

Se asegura de que algunos atributos HTTP estén presentes:

// ValidateRequestMethod checks if the request method is POST.
func ValidateRequestMethod(r *http.Request) error {
	if r.Method != http.MethodPost {
		return fmt.Errorf("method not allowed, only POST is accepted")
	}
	return nil
}

// ValidateRequiredHeaders checks for required GitHub headers.
func ValidateRequiredHeaders(r *http.Request) error {
	eventType := r.Header.Get("X-GitHub-Event")
	deliveryID := r.Header.Get("X-GitHub-Delivery")
	signature := r.Header.Get("X-Hub-Signature-256")
	if eventType == "" || deliveryID == "" || signature == "" {
		return fmt.Errorf("missing required GitHub headers")
	}
	return nil
}

// ValidateUserAgent checks that the User-Agent header starts with GitHub-Hookshot/
func ValidateUserAgent(r *http.Request) error {
	userAgent := r.Header.Get("User-Agent")
	if !strings.HasPrefix(userAgent, "GitHub-Hookshot/") {
		return fmt.Errorf("invalid User-Agent")
	}
	return nil
}

Al mismo tiempo que valida la firma de cada solicitud y su organización:

// ValidateSignature verifies the GitHub webhook signature.
func ValidateSignature(r *http.Request, secret string) ([]byte, error) {
	payload, err := GitHub.ValidatePayload(r, []byte(secret))
	if err != nil {
		return nil, fmt.Errorf("invalid GitHub signature: %w", err)
	}
	return payload, nil
}

// ValidateAllowedOwner checks if the organization login is in the allowed organizations list.
func ValidateAllowedOwner(payload []byte, allowedGitHubOrganizations []string) (string, error) {
	var orgLogin string
	var payloadMap map[string]any
	if err := json.Unmarshal(payload, &payloadMap); err == nil {
		if orgObj, ok := payloadMap["organization"].(map[string]any); ok {
			if login, ok := orgObj["login"].(string); ok {
				orgLogin = login
			} else if name, ok := orgObj["name"].(string); ok {
				orgLogin = name
			}
		}
	}
	if !slices.Contains(allowedGitHubOrganizations, orgLogin) {
		return orgLogin, fmt.Errorf("organization login not allowed")
	}
	return orgLogin, nil
}

Por último, se redirige a Argo Events según el tipo de evento:

	// Map eventType to Argo `EventSource` path
	var endpoint string
	switch eventType {
	case "push":
		endpoint = "/push"
	case "issues":
		endpoint = "/issues"
	case "pull_request":
		endpoint = "/pull-requests"
	default:
		slog.Info("Ignoring unhandled event type", "event_type", eventType, "delivery_id", deliveryID)
		w.WriteHeader(http.StatusOK)
		_, _ = w.Write([]byte("ok"))
		return
	}
	forwardURL := h.config.ArgoEventSourceForwardURL + endpoint

En lo que respecta a Argo Events, 10 sensores vigilan el EventBus de Argo Events en busca de nuevos eventos.

apiVersion: argoproj.io/v1alpha1
kind: Sensor
metadata:
  name: {{ .Values.sensors.packageUpdateOnDefaultBranch.name }}
  namespace: {{ .Release.Namespace }}
spec:
  eventBusName: {{ .Values.eventBus.name }}

Luego, el script aplica la lógica de cada sensor:

script: |
          local e = event
          if not e or not e.body or not e.body.repository then
            return false
          end

          -- e.g., "refs/heads/main"
          local ref = e.body.ref
          local default_branch = e.body.repository.default_branch
          if not ref or not default_branch then
            return false
          end

          local expected = "refs/heads/" .. default_branch
          if ref ~= expected then
            return false
          end

        {{- if .Values.sensors.packageUpdateOnDefaultBranch.packageFiles }}
          patterns = { {{- range $i, $f := .Values.sensors.packageUpdateOnDefaultBranch.packageFiles }}{{ if $i }}, {{ end }}"{{ $f }}"{{- end }} }
        {{- end }}

          local function anyMatch(path)
            if type(path) ~= "string" then return false end
            for _, pat in ipairs(patterns) do
              -- match filename at repo root, or anywhere under subdirs
              if path:match(pat) or path:match(".+/" .. pat) then
                return true
              end
            end
            return false
          end

          local function filesContainPackage(paths)
            if type(paths) ~= "table" then return false end
            for _, p in ipairs(paths) do
              if anyMatch(p) then return true end
            end
            return false
          end

          -- Inspect all commits (GitHub includes added/modified/removed lists)
          local commits = e.body.commits
          if type(commits) ~= "table" then
            -- Fallback: some payloads include only head_commit
            commits = {}
            if type(e.body.head_commit) == "table" then
              table.insert(commits, e.body.head_commit)
            end
          end

          for _, c in ipairs(commits) do
            if filesContainPackage(c.added) or filesContainPackage(c.modified) or filesContainPackage(c.removed) then
              return true
            end
          end

          return false

Backstage Syncer (Go)

Esto sondea nuestro catálogo de servicios (Backstage) para las entidades de recursos reales del repositorio, las transforma en CRD de RepoConfig y mantiene la Platform sincronizada con los cambios de configuración. Los cambios se aplican en tres minutos.

repoMap := make(map[string]map[string]interface{})
			for i := range entities {
				entity := &entities[i]
				if entity.Spec.Type != "GitHub-repository" {
					continue
				}

				implRaw, err := json.Marshal(entity.Spec.Implementation)
				if err != nil {
					logger.Error("Failed to marshal implementation", "error", err)
					continue
				}

				var implMap map[string]interface{}
				err = json.Unmarshal(implRaw, &implMap)
				if err != nil {
					logger.Error("Failed to unmarshal implementation map", "error", err)
					continue
				}
				var repoName string
				if specMap, ok := implMap["spec"].(map[string]interface{}); ok {
					if repo, ok := specMap["repository"].(string); ok {
						repoName = repo
					}
				}
				if repoName == "" {
					continue
				}

				var workflowsRaw []byte
				if v, ok := implMap["spec"].(map[string]interface{}); ok {
					if r, ok := v["renovate"]; ok {
						workflowsRaw, _ = json.Marshal(r)
					} else {
						workflowsRaw = []byte(`{}`)
					}
				} else {
					workflowsRaw = []byte(`{}`)
				}

				var workflowsWithDefaults schema.WorkflowsMetadata
				err = json.Unmarshal(workflowsRaw, &rworkflowsWithDefaults)
				if err != nil {
					logger.Error("Failed to unmarshal workflows config", "error", err)
					continue
				}

				workflowsMap := map[string]interface{}{
					"enabled":        workflowsWithDefaults.Enabled,
					"require_pr":     workflowsWithDefaults.RequirePr,
					"resource_group": string(workflowsWithDefaults.ResourceGroup),
					"run_frequency":  string(workflowsWithDefaults.RunFrequency),
				}
				repoMap[repoName] = map[string]interface{}{
					"renovate": workflowsMap,
					"owner":    entity.Spec.Owner,
				}
			}
			logger.Info("Fetched GitHub Repository data from Backstage", "repository_count", len(repoMap), "status_code", resp.StatusCode)

Por último, escribe esos datos en instancias de RepoConfig.

Base de flujos de trabajo (mixta: JavaScript, Go, Helm)

La capa base contiene gráficos de Helm, configuraciones de JavaScript, un contenedor Go para Renovate CLI con soporte de cifrado y un indexador APK personalizado para paquetes Alpine.

Configuración de autoservicio

Los equipos configuran sus repositorios de manera declarativa a través de Backstage:

spec:
  renovate:
    enabled: true
    config:
      resourceGroup: LARGE      # SMALL | MEDIUM | LARGE  
      runFrequency: "0 */4 * * *"  # Every 4 hours

Los grupos de recursos asignan CPU y memoria en función del tamaño del repositorio:

• PEQUEÑO: CPU de 500m, memoria 1Gi.
• MEDIO: CPU 1000m, memoria 2Gi.
• GRANDE: CPU de 2000 m, memoria de 4 Gi.

La configuración está bajo control de versiones, es auditable y se aplica automáticamente.

El patrón padre-hijo

El modelo de ejecución usa un patrón de flujo de trabajo primario y secundario:

• Flujo de trabajo principal: CronWorkflow ligero que se ejecuta según lo programado. Cifra los secretos, determina si se debe ejecutar un escaneo y pasa la configuración al secundario.
• Flujo de trabajo infantil: pod efímero donde se ejecuta Renovate CLI. Asigna recursos de forma dinámica, descifra secretos de forma aislada y se cierra al completar la tarea.

Esta separación proporciona seguridad (los secretos se cifran en el nivel superior), optimización de recursos (los niveles superiores utilizan recursos mínimos) y escalabilidad (los niveles inferiores se ejecutan en paralelo).

Los resultados

Transformación del rendimiento

• Antes: Un repositorio a la vez, algunos repositorios no se procesaban posiblemente incluso por un día o más, menos de 1000 escaneos por día.
• Después: más de 100 escaneos simultáneos, normalmente 8000 escaneos y hasta 10 000 escaneos registrados al día, limitados únicamente por la cantidad de recursos que estamos dispuestos a invertir y cómo gestionamos los límites de GitHub.

Rentabilidad

Sin embargo, por extraño que parezca, ejecutar 8000 pods al día puede darte el mismo resultado de forma mucho más económica que tener un pod de larga duración que intenta lograr los mismos resultados.

En la configuración anterior, ejecutábamos una sola instancia que, en un buen día, realizaba entre 500 y 600 escaneos. Al mismo tiempo, debido al hecho de que se ejecutarían diferentes tipos de repositorios en el mismo pod, necesitábamos dimensionar el pod para los más grandes. Ese tamaño sería mucho mayor que nuestra oferta extra grande actual, que usa 8 CPU para el pod y 16 GB de memoria.

Para cumplir con la salida diaria actual, el pod único tendría que ejecutarse durante 12 días. Entonces, al comparar el costo de un solo pod que funciona durante 12 días con 8000 pods de nuestro tamaño “MEDIO” funcionando cada día, nuestro nuevo diseño es mucho más eficiente para la misma salida de escaneos:

Sin embargo, tomemos en consideración que nuestro valor predeterminado para nuestras cargas de trabajo está configurado en “PEQUEÑO”, con la gran mayoría ejecutándose con éxito con 0.5 CPU y 1 G de RAM, y solo unos pocos necesitan cambiar a mediano y grande. Veamos qué sucede si el 60 % de nuestras cargas de trabajo se ejecutan en “PEQUEÑO”, el 30 % en “MEDIANO” y el 10 % en “GRANDE”, lo cual está más cerca de la realidad.

Podemos ver que, con la misma salida, somos mucho más rentables en nuestra configuración actual.

Seguridad mejorada

• Tokens efímeros de GitHub (minutos de exposición versus días).
• Aislamiento del espacio de nombres con límites de control de acceso basado en roles (RBAC).
• Cifrado secreto en reposo en flujos de trabajo principales.
• Acceso directo a Vault eliminado.

Rendimiento previsible

Con una frecuencia de escaneo garantizada, finalmente podemos establecer Objetivos de nivel de servicio (SLO). La autofusión funciona de forma confiable. Los equipos confían en la plataforma para cumplir lo prometido.

Decisiones arquitectónicas clave

Aquí tienes algunas de las decisiones clave de diseño que moldearon el aspecto de la plataforma.

• ¿Por qué flujos de trabajo padre-hijo?

Adoptamos este patrón para aplicar una estrategia de defensa en profundidad. Al restringir las credenciales de alto valor (como los secretos de GitHub App) a un espacio de nombres dedicado y bloqueado, usamos RBAC para asegurarnos de que los pods de ejecución efímeros no puedan acceder arbitrariamente a datos confidenciales. Las vulnerabilidades recientes de la cadena de suministro (por ejemplo, los ataques "Shai Hulud" de integración continua/entrega continua [CI/CD]) han demostrado la importancia de aislar entornos de ejecución que ejecutan scripts dinámicos desde el almacén de credenciales.

Simultáneamente, este desacoplamiento permite una optimización granular de recursos. Los flujos de trabajo "primarios" actúan como orquestadores ligeros con una huella mínima, mientras que los flujos de trabajo "secundarios" manejan el escaneo de dependencia con uso intensivo de computación. Esta separación simplifica la gestión de ciclo de vida al permitirnos aplicar una lógica de reconciliación distinta a cada capa, lo que brinda a los usuarios control sobre los parámetros de ejecución (hijo) mientras conservamos el control administrativo sobre la programación y la infraestructura de seguridad (principal).

• ¿Por qué es de autoservicio?

Eliminar a nuestro equipo como un cuello de botella para la configuración del repositorio fue un requisito crítico. Nuestra misión era diseñar una plataforma escalable y de autoservicio capaz de admitir diversos casos de uso. Nos dimos cuenta de que actuar como filtros para cada cambio de configuración era insostenible, dado el gran volumen de repositorios. En su lugar, adoptamos una filosofía de habilitación: proporcionar los “rieles” (infraestructura y barandillas) mientras capacitamos a los usuarios para conducir los “trenes” (ejecución y personalización). Creemos que este cambio hacia la autonomía del equipo mejora significativamente la productividad al permitir a los usuarios adaptar el sistema a sus necesidades operativas específicas.

• ¿Por qué el patrón de Kubernetes Operator?

Como se mencionó anteriormente, un principio de diseño fundamental era garantizar que la plataforma fuera completamente de autoservicio. Necesitábamos un mecanismo automatizado para capturar la intención de los usuarios (como alternar escaneos, ajustar la frecuencia de programación o ajustar los límites de recursos de tiempo de ejecución) y propagar instantáneamente esos cambios a los flujos de trabajo subyacentes. Al anticipar los requisitos futuros, el sistema también necesitaba ser fácilmente extensible.

Para lograr esto, desarrollamos un Operador de Kubernetes para la gestión de dependencias personalizado. Al utilizar CRD como interfaz para la configuración, establecimos un bucle de reconciliación nativo de Kubernetes. Este operador monitoriza continuamente el estado deseado definido por el usuario y orquesta automáticamente las actualizaciones necesarias en la infraestructura del flujo de trabajo. Esto asegura una operación fluida y basada en eventos, donde la lógica de la plataforma maneja toda la complejidad detrás de escena.

• ¿Para qué sirve diseñar una puerta de enlace de eventos de GitHub?

Adoptar una arquitectura impulsada por eventos (EDA) fue esencial para la capacidad de respuesta de la plataforma. Aunque CronWorkflows proporcionaba un calendario de referencia fiable, requeríamos la agilidad para gestionar ejecuciones ad hoc, como que los usuarios activaran escaneos manualmente a través del panel. Para lograr esto, necesitábamos una puerta de enlace de ingestión dedicada para validar la integridad de la carga útil y enrutar las solicitudes de manera inteligente.

Evaluamos las soluciones existentes, incluido el GitHub EventSource nativo para Argo, pero identificamos riesgos significativos en cuanto a la sobrecarga operativa y las estrictas cuotas de la API de GitHub (por ejemplo, los límites de webhook por repositorio). En consecuencia, creamos una puerta de enlace personalizada para desacoplar nuestra infraestructura de estas limitaciones.

Crucialmente, esta puerta de enlace sirvió como un punto de control de tráfico estratégico durante nuestra migración. Actuó como un interruptor, lo que nos permitió realizar una implementación gradual y granular (cambio de tráfico) del sistema heredado a la nueva infraestructura. Esto garantizó que la incorporación de miles de repositorios fuera un proceso controlado y sin riesgos, en lugar de un cambio radical.

Lecciones aprendidas

Algunas lecciones que hemos aprendido van de la mano con el código fuente de Elastic:

1. El cliente primero: las plataformas están diseñadas para los usuarios. Por eso es importante tener las necesidades de los usuarios como prioridad número uno. Esto moldea la plataforma en una infraestructura y aplicaciones diseñadas de manera eficiente que reducen la fricción con los usuarios, simplifican el escalado de la plataforma y facilitan la adopción.
2. Espacio-tiempo: a veces el camino de menor resistencia lleva a arenas movedizas. Inicialmente, intentamos optimizar el modelo de procesamiento secuencial existente, pero esto no resolvió nuestros problemas. De hecho, solo introdujo más complejidad y cabos sueltos. La audaz decisión de rediseñar la plataforma con procesamiento paralelo requirió un esfuerzo inicial significativo. Sin embargo, finalmente allanó el camino para un crecimiento sostenible de la plataforma y prácticamente eliminó el tedioso trabajo administrativo diario.
3. Depende: una plataforma no puede operar de forma aislada. Su éxito depende de qué tan bien se integre con el ecosistema más amplio. En nuestro caso, la integración con Backstage fue crítica, ya que sirve como la única fuente de verdad para la incorporación fluida de servicios. Del mismo modo, conectarnos a Artifactory nos permitió gestionar las actualizaciones de paquetes privados de manera eficiente, y la lista de integraciones esenciales continúa.
4. Progreso, perfección simple: a lo largo de la implementación, sometimos constantemente a prueba nuestras hipótesis iniciales y nos adaptamos a los nuevos obstáculos que iban surgiendo. En lugar de quedar paralizados por el perfeccionismo, adoptamos un enfoque iterativo, abordamos los desafíos uno por uno y ajustamos nuestra estrategia de migración para cumplir con las condiciones del mundo real.

Lo que se viene

La entrega de la plataforma nos permite realizar un trabajo más significativo que nos ayudará a mejorar la UX y la eficiencia de nuestra plataforma. Algunos ejemplos son:

• Aumento y protección de la adopción de la fusión automática

La característica de fusión automática acelera significativamente la velocidad del equipo al eliminar las tareas manuales tediosas. Sin embargo, tenemos que asegurarnos de que haya barreras estrictas para garantizar que este aumento de velocidad no se haga a expensas de la seguridad.

• Mejora la observabilidad en torno a la experiencia del usuario final

Una prioridad fundamental de nuestra hoja de ruta es mejorar la observabilidad, no solo a nivel de plataforma, sino también específicamente desde la perspectiva del usuario final. Aunque capturar métricas de infraestructura es sencillo, comprender la experiencia real del usuario requiere conocimientos más profundos. Estamos trabajando para definir los indicadores de rendimiento (KPI) centrados en el usuario de núcleo para que nuestra telemetría pueda detectar los puntos de fricción y los problemas de rendimiento antes de que se conviertan en quejas de los usuarios.

• Elimina obstáculos para una mayor adopción

De cara al futuro, nuestra prioridad es identificar y eliminar cualquier barrera que dificulte la adopción de plataformas. Ya sea que esto requiera desarrollar nuevas integraciones o desplegar conjuntos de características específicas, estamos comprometidos con la planificación basada en datos. Construimos con éxito una plataforma diseñada para escalar; nuestro enfoque ahora cambia a maximizar su potencial.

El panorama general

El proyecto de flujos de trabajo de gestión de dependencias demuestra un principio más amplio: cuando necesites escalar herramientas de código abierto más allá de su modelo de despliegue predeterminado, los patrones nativos de Kubernetes proporcionan un camino a seguir.

Al adoptar:

• CRDs para configuración.
• Operadores para la gestión de ciclo de vida.
• Arquitectura basada en eventos para mayor capacidad de respuesta.
• GitOps para el despliegue.

Creamos una orquestación que escala independientemente de la cantidad de repositorios que gestiona. El rendimiento de escanear un solo repositorio es el mismo tanto si gestionamos 100 como si gestionamos 1000.

Cuando se anuncia un CVE crítico, ahora tenemos respuestas en minutos, no en horas. Esa es la diferencia entre un cuello de botella y una ventaja competitiva.

Agradecimientos

Esta plataforma se basa en excelentes herramientas de código abierto:

• Kubebuilder: el marco de trabajo de código abierto que usamos para poner en marcha nuestros operadores Kubernetes que inician y orquestan nuestros flujos de trabajo. [1][2]
• Backstage: el marco de trabajo de código abierto sobre el cual hemos construido nuestro catálogo de servicios y que utilizamos como nuestra fuente de la verdad. [1][2]
• Argo Workflows y Argo Events: la suite de código abierto que usábamos para orquestar procesos complejos y agregar procesamiento dinámico basado en eventos. [1][2][3][4]
• Renovate CLI: la herramienta de gestión de dependencias de código abierto que procesa nuestros repositorios. [1][2]

* El modelo de precios de AWS Fargate se usó como referencia para el costo de un solo pod, aunque nuestras cargas de trabajo no se ejecutan necesariamente en AWS y se ejecutan en clústeres de Kubernetes completos.

Al ajustar Elasticsearch para cargas de trabajo de alta concurrencia, el enfoque estándar es maximizar la RAM para mantener el conjunto de documentos en la memoria y lograr una baja latencia de búsqueda. En consecuencia, best_compression rara vez se considera para cargas de trabajo de búsqueda, ya que se ve principalmente como una medida de ahorro de almacenamiento para casos de uso de Elastic Observability y Elastic Security donde la eficiencia del almacenamiento tiene prioridad.

En este blog, demostramos que cuando el tamaño de los sets de datos supera significativamente la caché de la página del sistema operativo, best_compression mejora el rendimiento de búsqueda y la eficiencia de los recursos al reducir el cuello de botella de las E/S.

La configuración

Nuestro caso de uso es una aplicación de búsqueda de alta concurrencia que se ejecuta en instancias optimizadas para CPU de Elastic Cloud.

• Volumen de datos: ~500 millones de documentos
• Infraestructura: 6 instancias de Elastic Cloud (Elasticsearch Service) (cada instancia: 1,76 TB de almacenamiento | 60 GB de RAM | 31,9 vCPU).
• Proporción de memoria a almacenamiento: ~5 % del total de sets de datos que cabe en la RAM

Los síntomas: alta latencia

Observamos que cuando el número de solicitudes actuales aumenta alrededor de las 19:00, la latencia de búsqueda se deteriora significativamente. Como se muestra en la figura 1 y la figura 2, mientras que el tráfico alcanza un máximo de 400 solicitudes por minuto por instancia de Elasticsearch, el tiempo promedio del servicio de consulta se degrada a más de 60 ms.

El uso de la CPU seguía siendo relativamente bajo tras el manejo inicial de las conexiones, lo que indica que el cálculo no era el cuello de botella.

Surgió una fuerte correlación entre el volumen de búsquedas y los errores de página. A medida que aumentaban las solicitudes, observamos un incremento proporcional en los errores de página, que alcanzaron un pico de alrededor de 400k/minuto. Esto indicaba que el set de datos activo no podía caber en la caché de la página.

Al mismo tiempo, el uso del heap de JVM parecía ser normal y saludable. Esto descartó problemas de recolección de basura y confirmó que el cuello de botella era de E/S.

El diagnóstico: limitado por E/S

El sistema estaba vinculado a E/S. Elasticsearch se basa en la caché de páginas del sistema operativo para servir datos de índice desde la memoria. Cuando el índice es demasiado grande para la caché, las consultas desencadenan lecturas de disco costosas. Aunque la solución habitual es escalar horizontalmente (agregar nodos/RAM), quisimos agotar primero las mejoras de eficiencia de nuestros recursos existentes.

La solución

De forma predeterminada, Elasticsearch utiliza la compresión LZ4 para sus segmentos de índice, que logra un equilibrio entre la velocidad y el tamaño. Planteamos la hipótesis de que cambiarse a best_compression (que usa zstd) reduciría el tamaño de los índices. Un espacio más pequeño permite que un mayor porcentaje del índice encaje en la caché de páginas, lo que cambia un aumento insignificante en la CPU (para la descompresión) por una reducción en la E/S del disco.

Para habilitar best_compression, reindexamos los datos con la configuración de índice index.codec: best_compression. Alternativamente, el mismo resultado podría lograrse al cerrar el índice, que restablece el códec de índice a best_compression, y luego realiza una fusión de segmentos.

POST my-index/_close
PUT my-index/_settings
{
    "codec": "best_compression"
}
  
POST my-index/_open  
POST my-index/_forcemerge?max_num_segments=1

Los resultados

Los resultados confirmaron nuestra hipótesis: la eficiencia mejorada del almacenamiento se tradujo directamente en un aumento sustancial en el rendimiento de búsqueda sin un aumento asociado en la utilización de la CPU.

La aplicación de best_compression redujo el tamaño del índice en aproximadamente un 25 %. Aunque es menor que la reducción observada en los datos de log repetitivos, esta reducción del 25 % aumentó efectivamente nuestra capacidad de caché de página en el mismo margen.

Durante la siguiente prueba de carga (que comenzó a las 17:00), el tráfico fue aún mayor, y alcanzó un pico de 500 solicitudes por minuto por nodo de Elasticsearch.

A pesar de la mayor carga, la utilización de la CPU fue menor que en la ejecución anterior. El uso elevado en la prueba anterior probablemente se debió a la sobrecarga del manejo excesivo de errores de página y la gestión de E/S del disco.

Lo más importante es que los errores de página disminuyeron significativamente. Incluso a un rendimiento más alto, los errores rondaron los <200k por minuto, en comparación con >300k en la prueba de referencia.

Aunque los resultados del error de página aún fueron menos que óptimos, el tiempo de servicio de consulta se redujo en aproximadamente un 50 %, y se mantuvo por debajo de los 30 ms incluso bajo una carga más pesada.

La conclusión: best_compression para la búsqueda

Para casos de uso donde el volumen de datos supera la memoria física disponible, best_compression es una palanca poderosa para ajustar el rendimiento.

La solución convencional a los errores de caché es escalar para aumentar la RAM. Sin embargo, al reducir la huella del índice, logramos el mismo objetivo: maximizar el recuento de documentos en la memoria caché de páginas. Nuestro siguiente paso es explorar la clasificación de índices para optimizar aún más el almacenamiento y obtener más rendimiento de los recursos existentes.

Los agentes están ganando terreno impulsados por su potencial para ofrecer aumentos en la eficiencia y mejores experiencias del cliente. Pero en la práctica, ofrecer a los agentes el contexto adecuado es difícil, especialmente cuando se opera sobre datos empresariales desordenados y no estructurados. Los desarrolladores deben gestionar herramientas, indicaciones, estados, lógica de razonamiento, modelos y, lo que es más importante, recuperar el contexto relevante de las fuentes empresariales para ofrecer resultados y acciones precisos. Elastic Agent Builder ofrece estos componentes centrales para desarrollar agentes seguros, confiables y basados en el contexto.

Capacidades centrales de Agent Builder

Agent Builder aprovecha las inversiones a largo plazo de Elastic en relevancia de búsqueda y retrieval-augmented generation, y trabaja para convertir a Elasticsearch en la mejor base de datos vectorial que simplifique el desarrollo de agentes de IA contextuales y centrados en datos.

Agent Builder te permite:

• Comienza inmediatamente con un agente conversacional integrado que pueda responder preguntas, realizar análisis e impulsar investigaciones sobre cualquier dato en Elasticsearch.
• Pasa rápidamente de datos complejos y datos no estructurados a un agente personalizado con una experiencia de desarrollo basada en la configuración.
• Aprovecha la mejor relevancia de búsqueda híbrida de su clase mediante ES|QL integrado o herramientas personalizadas para mejorar la calidad del contexto y la confiabilidad del agente.
• Ejecuta flujos de trabajo complejos (vista previa) como herramientas reutilizables para enriquecer datos, actualizar registros, enviar mensajes y mucho más para la automatización basada en reglas.
• Conéctate a fuentes de datos fuera de Elasticsearch usando flujos de trabajo y MCP para correlacionar y combinar el contexto para los agentes.
• Integra con cualquier marco de trabajo de aplicación o agente utilizando herramientas integradas y personalizadas expuestas a través de MCP, y la capacidad de conectarte a MCP externo (vista previa), soporte para A2A y soporte completo de API.
• Amplía las capacidades de Agent Builder con la integración de soluciones de terceros, como LlamaIndex para el procesamiento de documentos complejos, o Arcade.dev para un acceso seguro y estructurado a las herramientas.

Para ampliar aún más la funcionalidad de Agent Builder, presentamos Elastic Workflows, nuestras nuevas capacidades de automatización basadas en reglas, ahora en versión preliminar técnica. Para las tareas organizacionales, los agentes a veces necesitan certeza y confiabilidad en las acciones basadas en reglas, que a menudo son necesarias para implementar una lógica de negocio específica. Elastic Workflows ofrece a los agentes una forma sencilla y declarativa de orquestar sistemas internos y externos para realizar acciones, recopilar y transformar datos y contexto. Los flujos de trabajo son totalmente componibles, orientados a eventos y flexibles, y pueden exponerse como herramientas a un agente mediante MCP.

De los datos al agente en minutos

El desarrollo de agentes puede llevar semanas de trabajo previo para consolidar almacenes de datos separados, construir pipelines manuales, ajustar búsquedas y gestionar una orquestación compleja. Agent Builder reduce el tiempo de desarrollo de agentes al eliminar la necesidad de almacenes de datos separados, bases de datos vectoriales, pipelines RAG, capas de búsqueda, traductores de búsquedas y orquestadores de herramientas, lo que te permite centrarte en la lógica de agentes y la entrega de aplicaciones.

Agent Builder integra de forma nativa las primitivas de la plataforma Elasticsearch para que el desarrollo de agentes sea rápido.

• Comienza con un agente conversacional integrado que pueda chatear inmediatamente y razonar con tus datos indexados.
• Integra agentes en aplicaciones, dashboards o sistemas CI/CD con acceso interactivo a través de Kibana, API o MCP y A2A.
• Construye con herramientas predeterminadas para entender tu estructura de datos, selecciona el índice adecuado, genera búsquedas híbridas, semánticas y estructuradas optimizadas, y crea visualizaciones configurables usando ES|QL basado en prompts de lenguaje natural.

Para profundizar más, prueba un recorrido práctico completo.

Desarrolla sobre Elasticsearch, una plataforma de datos completa para la ingeniería de contexto

Para los agentes de IA, la calidad del contexto es esencial para brindar un razonamiento eficaz y reducir los riesgos de alucinación. Para muchos agentes de IA empresarial, los datos comerciales necesarios para realizar una tarea son el contexto más decisivo. Como almacén de datos masivamente escalable, base de datos vectorial y líder en relevancia, Elasticsearch ya ofrece muchas primitivas sólidas de ingeniería de contexto. La ingeniería de contexto va más allá de la simple retrieval-augmented generation, ya que te permite adaptar y escalar la forma en que los datos se recuperan, se clasifican, se filtran y se presentan a los agentes, lo que ayuda a reducir el ruido y la ambigüedad.

Elasticsearch ofrece un motor de contexto que combina búsqueda léxica, búsqueda vectorial y filtrado estructurado para la recuperación, lo cual mejora sustancialmente el rendimiento de los LLM al garantizar que el modelo opere en un contexto relevante y preciso. Esta capacidad está respaldada por recuperación agente, junto con herramientas integradas y lógica de búsqueda que seleccionan automáticamente los índices correctos y transforman el lenguaje natural en búsquedas optimizadas para el contexto.

Con Agent Builder, puedes asegurarte de que los agentes reciban primero el contexto más útil con controles de relevancia y clasificación, lo que te permite ajustar la lógica de calificación, clasificación y filtrado. Elasticsearch te permite controlar qué importa, por qué importa y cómo se prioriza, en lugar de depender de un comportamiento de recuperación opaco. Todo esto está respaldado por Elasticsearch como una plataforma de datos escalable para almacenar y escalar todos tus datos, desde texto, vectores, metadatos, logs y más en una plataforma, lo que facilita la gestión del contexto para los agentes.

Ejecutar flujos de trabajo complejos como herramientas reutilizables

Aunque los agentes de IA permiten razonar tareas complejas, gran parte de la automatización depende de ejecutar de forma confiable acciones basadas en reglas que impongan una lógica de negocio específica. Elastic Workflows ofrece una forma sencilla y declarativa de orquestar sistemas internos y externos para realizar acciones, recopilar contexto o datos e integrarlos como parte de los agentes. Definidos en YAML, los flujos de trabajo son totalmente componibles, lo que permite que sean tan simples o complejos como requiera el trabajo. Esto ofrece a los agentes una forma eficiente de actuar en toda la plataforma y soluciones de Elasticsearch, así como con aplicaciones de terceros.

La integración de un flujo de trabajo con Agent Builder se puede realizar en tres pasos (requisito previo: habilitar los flujos de trabajo con los detalles que aparecen aquí).

1. Crea y guarda un nuevo flujo de trabajo usando el sencillo editor basado en YAML con función de autocompletado y pruebas integradas.

2. Crea una nueva herramienta en Agent Builder con el tipo “flujo de trabajo” e ingresa una descripción para ayudar al agente a determinar cuándo usar la herramienta de flujo de trabajo.

3. Agrega la herramienta de flujo de trabajo a tu agente personalizado.

4. ¡Eso es todo! Ahora el agente puede llamar al flujo de trabajo desde una conversación.

Tu agente, tus reglas

Agent Builder no te limita a un solo paradigma de desarrollo. En cambio, está diseñado para permitir enfoques de desarrollo abiertos y flexibles para los agentes, con control total sobre los datos, la relevancia, los modelos, la interoperabilidad, la seguridad y el diseño de los agentes.

Las definiciones personalizadas de agentes te permiten elegir exactamente a qué herramientas puede acceder un agente, incorporar avisos personalizados del sistema, adaptar las instrucciones del agente y definir los límites de seguridad. Los agentes siguen siendo independientes del modelo, lo que te permite configurar de manera flexible un LLM de preferencia, tanto nativo como en todo el ecosistema más amplio, sin estar limitado a un solo proveedor.

Desarrolla herramientas extensibles que encapsulen lógica específica de dominio (por ejemplo, filtros de índice específicos, ES|QL joins, pipelines analíticas), y aplica limitaciones para un uso seguro en producción. El soporte completo de API permite la interoperabilidad con otros marcos de trabajo agentes, con soporte nativo para Model Context Protocol (MCP). La integración A2A significa que puedes exponer tus Elastic Agent a otros marcos de trabajo, servicios y apps de clientes, reutilizando los mismos datos y la lógica de ingeniería de contexto a través de las integraciones.

Agent Builder permite un desarrollo flexible y abierto y está diseñado para integrarse fácilmente con marcos de trabajo y plataformas populares de agentes. Estas integraciones pueden ser esenciales para ofrecer agentes efectivos. Como describe Sam Partee, cofundador de Arcade.dev,

“Los sistemas agénticos fallan hoy porque conectar la IA a herramientas y datos es complejo. Elastic Agent Builder con Arcade.dev ofrece a los desarrolladores una forma estructurada y segura de manejar cómo los agentes recuperan el contexto, la razón y la acción, lo que lleva a los agentes de la demostración al grado de producción".

Agent Builder también aprovecha la extensibilidad de Elasticsearch para manejar datos complejos. Como describe Jerry Liu, CEO de LlamaIndex,

“Desbloquear el contexto empresarial de las fuentes de datos no estructurados es clave para construir agentes efectivos. El procesamiento de documentos complejos de Elastic Agent Builder combinado de LlamaIndex fortalece la capa de contexto crítico, lo que ayuda a los equipos a recuperar, procesar y preparar datos para que los agentes puedan razonar con mayor precisión y ofrecer mejores resultados”.

¿Qué puedes construir?

Agent Builder ya se está utilizando para una variedad de casos de uso. A continuación, se muestran algunos ejemplos y arquitecturas de referencia para empezar a utilizar los agentes:

• Automatizar la infraestructura: En escenarios de soporte, los agentes se han utilizado para leer, pensar y chatear, pero hasta la fecha, no pueden comunicarse y contactarse con la infraestructura que puede que sea necesario administrar. El equipo de ingeniería de Elastic creó un agente para la gestión automatizada de la infraestructura como parte de un hackatón. El agente investiga activamente los problemas relacionados con la infraestructura de la aplicación y toma medidas automatizadas. Utiliza flujos de trabajo para optimizar configuraciones, responder a problemas y escalar recursos, todo ello basado en una comprensión inteligente de los logs de infraestructura.
• Análisis de amenazas a la seguridad: Se desarrolló un agente de vulnerabilidad de seguridad con Elastic Agent Builder, MCP y Elasticsearch. Automatiza el análisis de amenazas correlacionando datos de seguridad interna con inteligencia de amenazas externas. El agente realiza búsquedas semánticas sobre incidentes y configuraciones históricas, incrementa los resultados con datos en tiempo real de Internet y aplica razonamientos LLM para evaluar la relevancia ambiental, priorizar riesgos y producir remediaciones accionables. Consulta la arquitectura de referencia.
• Soporte técnico al cliente: Los agentes pueden realizar múltiples tareas de soporte, incluyendo resumen de casos, desduplicación y creación de problemas, e investigación técnica profunda. Agent Builder permite esto mediante una búsqueda híbrida de varios pasos para encontrar solo los problemas, soluciones y procedimientos relacionados más relevantes, y formular hipótesis de causa raíz y planes de remediación. Agent Builder puede simplificar la arquitectura de sistemas de soporte complejos y acelerar el tiempo de entrega.
• Descubrimiento de productos y contenido: Agent Builder simplifica el proceso de exponer catálogos de productos complejos para experiencias conversacionales, al tiempo que permite a las organizaciones mantener la flexibilidad para incluir sus propios requisitos y lógica de negocio.
• Haz tu propio desarrollo: Únete al Agent Builder Hackathon, que se celebrará del 22 de enero al 27 de febrero de 2026. Trabaja con la comunidad para crear agentes de IA basados en el contexto y en varios pasos que combinen búsqueda, flujos de trabajo, herramientas y razonamiento para automatizar tareas del mundo real*

Comienza a construir agentes personalizados ahora

Comienza con una prueba de Elastic Cloud y revisa la documentación aquí. Para los clientes existentes, Agent Builder está disponible en Cloud Serverless y en el nivel Empresarial en Elastic Cloud Hosted y es autoadministrado.

* Haz clic aquí para conocer los términos, condiciones y requisitos de elegibilidad completos para la hackatón

Una de las formas en que se romperá el “cristal” es mediante la adopción de agentes de voz, que son agentes de AI que reconocen el habla humana y sintetizan audio generado por computadora. Esto se ha vuelto posible gracias al auge de las transcripciones de baja latencia, los modelos de lenguaje grandes (LLM) rápidos y los modelos de texto a voz que suenan humanos.

Los agentes de voz también necesitan acceso a los datos empresariales para ser realmente valiosos. En este blog, aprenderemos cómo funcionan los agentes de voz y diseñaremos uno para ElasticSport, una tienda ficticia de equipamiento deportivo al aire libre, con LiveKit y Elastic Agent Builder. Nuestro agente de voz será consciente del contexto y trabajará con nuestros datos.

Cómo funciona

Existen dos paradigmas en el mundo de los agentes de voz: el primero usa modelos de voz a voz, y el segundo usa un pipeline de voz compuesto por voz a texto, LLM y texto a voz. Los modelos de voz a voz tienen sus propios beneficios, pero los pipelines de voz ofrecen mucha más personalización sobre las tecnologías utilizadas y cómo se gestiona el contexto, además de un mayor control sobre el comportamiento del agente. Nos enfocaremos en el modelo de pipeline de voz.

Componentes clave

Transcripción (voz a texto)

La transcripción es el punto de entrada del pipeline de voz. El componente de transcripción toma como entrada fragmentos de audio sin procesar, transcribe el habla en texto y entrega ese texto como salida. El texto transcrito se almacena en un búfer hasta que el sistema detecta que el habla del usuario ha terminado; en ese momento, se inicia la generación del LLM. Varios proveedores externos ofrecen transcripciones de baja latencia. Al seleccionar uno, considera la latencia y la precisión de la transcripción, y asegúrate de que soporten transcripciones en streaming.

Ejemplos de API de terceros: AssemblyAI, Deepgram, OpenAI, ElevenLabs

Detección de turnos

La detección de turnos es el componente del pipeline que detecta cuándo el hablante ha terminado de hablar y la generación debería comenzar. Una forma común de hacer esto es mediante un modelo de detección de actividad vocal (VAD), como Silero VAD. El VAD utiliza los niveles de energía del audio para detectar cuándo contiene habla y cuándo ha terminado. Sin embargo, el VAD por sí solo no puede identificar la diferencia entre una pausa y el final del discurso. Por eso, a menudo se combina con un modelo de fin de enunciado que predice si el hablante ha terminado de hablar, basándose en la transcripción provisional o el audio sin procesar.

Ejemplos (Hugging Face): livekit/turn-detector, pipecat-ai/smart-turn-v3

Agente

El agente es el núcleo de un pipeline de voz. Es responsable de entender la intención, reunir el contexto adecuado y formular una respuesta en formato de texto. Elastic Agent Builder, con sus capacidades de razonamiento integradas, su biblioteca de herramientas y la integración de flujos de trabajo, permite crear un agente que puede trabajar sobre tus datos e interactuar con servicios externos.

LLM (texto a texto)

Al seleccionar un LLM para Elastic Agent Builder, hay dos características principales a considerar: las evaluaciones de razonamiento del LLM y el tiempo hasta el primer token (TTFT).

Las evaluaciones de razonamiento indican qué tan bien el LLM es capaz de generar respuestas correctas. Las evaluaciones que considerar son aquellas que evalúan la adherencia a las conversaciones de varios turnos y las de inteligencia, como MT-Bench y el set de datos Humanity's Last Exam, respectivamente.

Las evaluaciones de TTFT evalúan qué tan rápido produce el modelo su primer token de salida. Existen otros tipos de evaluaciones de latencia, pero el TTFT es particularmente importante para los agentes de voz, ya que la síntesis de audio puede comenzar tan pronto como se recibe el primer token, lo que resulta en una menor latencia entre turnos y una conversación que se siente natural.

Por lo general, hay que elegir un equilibrio entre estas dos características, ya que los modelos más rápidos suelen tener un peor desempeño en las evaluaciones de razonamiento.

Ejemplos (Hugging Face): openai/gpt-oss-20b, openai/gpt-oss-120b

Síntesis (texto a voz)

La parte final del pipeline es el modelo de texto a voz. Este componente es responsable de convertir la salida de texto del LLM en audio audible. Al igual que con el LLM, la latencia es una característica para tener en cuenta al momento de seleccionar un proveedor de texto a voz. La latencia de texto a voz se mide por el tiempo hasta el primer byte (TTFB). Es el tiempo que tarda en recibirse el primer byte de audio. Un TTFB más bajo también reduce la latencia entre turnos.

Ejemplos: ElevenLabs, Cartesia, Rime

Desarrollar el pipeline de voz

Elastic Agent Builder puede integrarse en un pipeline de voz en varios niveles diferentes:

1. Solo herramientas de Agent Builder: voz a texto → LLM (con herramientas de Agent Builder) → texto a voz
2. Agent Builder como MCP: conversión de voz a texto → LLM (con acceso a Agent Builder a través de MCP) → conversión de texto a voz
3. Agent Builder como núcleo: voz a texto → Agent Builder → texto a voz

Para este proyecto, elegí Agent Builder como el enfoque núcleo. Con este enfoque, se puede usar toda la funcionalidad de Agent Builder y los flujos de trabajo. El proyecto usa LiveKit para orquestar voz a texto, detección de turnos y texto a voz, e implementa un nodo LLM personalizado que se integra directamente con Agent Builder.

Agente de voz de soporte de Elastic

Vamos a construir un agente de voz de soporte personalizado para una tienda de deportes ficticia llamada ElasticSport. Los clientes podrán llamar a la línea de ayuda, pedir recomendaciones de productos, buscar detalles de artículos, consultar el estado de sus pedidos y pedir que se les envíe la información del pedido por mensaje de texto. Para lograr esto, primero necesitamos configurar un agente personalizado y crear herramientas para ejecutar consultas y flujos de trabajo en el lenguaje de búsqueda de Elasticsearch (ES|QL).

Configurar el agente

Indicación

La indicación le señala al agente qué personalidad debe adoptar y cómo responder. Es importante destacar que hay algunas indicaciones específicas para voz que garantizan que las respuestas se sinteticen correctamente en audio y que los malentendidos se resuelvan con elegancia.

You are a Sales Assistant at ElasticSport, an outdoor sport shop specialized in hiking and winter equipment. 

[Profile]
- name: Iva
- company: ElasticSport
- role: Sales Assistant
- language: en-GB
- description: ElasticSport virtual sales assistant

[Context]
- Ask clarifying questions to understand the context.
- Use available tools to answer the user's question.
- Use the knowledge base to retrieve general information

[Style]
- Be informative and comprehensive.
- Maintain a professional, friendly and polite tone.
- Mimic human behavior and speech patterns.
- Be concise. Do not over explain initially

[Response Guideline]
- Present dates in spelled-out month date format (e.g., January fifteenth, two thousand and twenty-four).
- Avoid the use of unpronounceable punctuation such as bullet points, tables, emojis.
- Respond in plain text, avoid any formatting.
- Spell out numbers as words for more natural-sounding speech.
- Respond in short and concise sentences. Responses should be 1 or 2 sentences long.

[ERROR RECOVERY]
### Misunderstanding Protocol
1. Acknowledge potential misunderstanding
2. Request specific clarification

Flujos de trabajo

Agregaremos un pequeño flujo de trabajo para enviar un SMS a través de la API de mensajería de Twilio. El flujo de trabajo se expondrá al agente personalizado como una herramienta, lo que dará como resultado una experiencia de usuario donde el agente puede enviar al usuario un SMS mientras está en la llamada. Esto permite que quien llama pueda decir, por ejemplo: “¿Puedes enviarme más detalles sobre X por mensaje de texto?”.

name: send sms
enabled: true
triggers:
  - type: manual
inputs:
  - name: message
    type: string
    description: The message to send to the phone number.

  - name: phone_number
    type: string
    description: The phone number to send the message to.

consts:
  TWILIO_ACCOUNT: "****"
  BASIC_AUTH: "****"
  FROM_PHONE_NNUMBER: "****"
steps:
  - name: http_step
    type: http
    with:
      url: https://api.twilio.com/2010-04-01/Accounts/{{consts.TWILIO_ACCOUNT}}/Messages.json
      method: POST
      headers:
        Content-Type: application/x-www-form-urlencoded
        Authorization: Basic {{consts.BASIC_AUTH | base64_encode}}
      body: From={{consts.FROM_PHONE_NNUMBER}}&To={{inputs.phone_number}}&Body={{inputs.message}}
      timeout: 30s

Herramientas ES|QL

Las siguientes herramientas permiten que el agente proporcione respuestas relevantes basadas en datos reales. El repositorio de ejemplo contiene un script de configuración para inicializar Kibana con sets de datos de productos, pedidos y base de conocimientos.

• Product.search

El set de datos de productos contiene 65 productos ficticios. Este es un documento de ejemplo:

{
      "sku": "ort3M7k",
      "name": "Ortovox Free Rider 26 Backpack",
      "price": 189,
      "currency": "USD",
      "image": "https://via.placeholder.com/150",
      "description": "The Ortovox Free Rider 26 is a technical freeride backpack with a dedicated safety compartment and diagonal ski carry system. Perfect for backcountry missions.\n\nKey Features:\n- 26L capacity\n- Diagonal ski carry system\n- Safety equipment compartment\n- Helmet holder\n- Hydration system compatible",
      "category": "Accessories",
      "subCategory": "Backpacks",
      "brand": "Ortovox",
      "sizes": ["One Size"],
      "colors": ["Black", "Blue", "Orange"],
      "materials": ["Nylon", "Polyester"]
    }

Los campos de nombre y descripción se mapean como semantic_text, lo que permite al LLM usar la búsqueda semántica a través de ES|QL para recuperar productos relevantes. La consulta de búsqueda híbrida realiza una coincidencia semántica en ambos campos, aplicando un peso ligeramente mayor a las coincidencias en el campo de nombre mediante un refuerzo.

La búsqueda primero recupera los 20 mejores resultados clasificados por su puntuación de relevancia inicial. Luego, estos resultados se reclasifican basándose en su campo de descripción utilizando el modelo de inferencia .rerank-v1-elasticsearch y, finalmente, se reducen a los cinco productos más relevantes.

type: ES|QL
toolId: products.search
description: Use this tool to search through the product catalogue by keywords.
query: |
    FROM products
        METADATA _score
      | WHERE
          MATCH(name, ?query, {"boost": 0.6}) OR
            MATCH(description, ?query, {"boost": 0.4})
      | SORT _score DESC
      | LIMIT 20
      | RERANK ?query
            ON description
            WITH {"inference_id": ".rerank-v1-elasticsearch"}
      | LIMIT 5

parameters:
    query: space separated keywords to search for in catalogue

• Knowledgebase.search

Los sets de datos de la base de conocimientos contienen documentos con la siguiente estructura, en los que los campos de título y contenido se almacenan como texto semántico:

{
        id: "8273645",
        createdAt: "2025-11-14",
        title: "International Orders",
        content: `International orders are processed through our international shipping partner. Below are the countries we ship to and average delivery times.
        Germany: 3-5 working days
        France: 3-5 working days
        Italy: 3-5 working days
        Spain: 3-5 working days
        United Kingdom: 3-5 working days
        United States: 3-5 working days
        Canada: 3-5 working days
        Australia: 3-5 working days
        New Zealand: 3-5 working days
        `
}

Y la herramienta usa una búsqueda similar a la herramienta product.search:

type: "ES|QL"
toolId: knowledgebase.search
description: Use this tool to search the knowledgebase.
query: |
  FROM knowledge_base
    METADATA _score
  | WHERE
      MATCH(title, ?query, {"boost": 0.6}) OR
      MATCH(content, ?query, {"boost": 0.4})
  | SORT _score DESC
  | LIMIT 20
  | RERANK ?query
      ON content
      WITH {"inference_id": ".rerank-v1-elasticsearch"}
  | LIMIT 5

parameters:
  query: space separated keywords or natural language phrase to semantically search for in the knowledge base

• Orders.search

La herramienta final que agregaremos es la que se usa para recuperar pedidos por order_id:

type: "ES|QL"
toolId: order.search
description: Use this tool to retrieve an order by its ID.
query: |
  FROM orders
    METADATA _score
  | WHERE order_id == ?order_id
  | SORT _score DESC
  | LIMIT 1

parameters:
  order_id: "the ID of the order"

Después de configurar el agente y vincular estos flujos de trabajo y herramientas ES|QL, puedes probar al agente dentro de Kibana.

Además de desarrollar un agente de soporte para ElasticSport, el agente, los flujos de trabajo y las herramientas pueden adaptarse a otros casos de uso, como un agente de ventas que califica clientes potenciales, un agente de servicio para reparaciones del hogar, reservas para un restaurante o un agente para agendar citas.

La parte final es conectar el agente que acabamos de crear con LiveKit, los modelos de texto a voz y de voz a texto. El repositorio enlazado al final de este blog contiene un nodo de LLM personalizado de Elastic Agent Builder que se puede usar con LiveKit. Solo hay que sustituir el AGENT_ID por el tuyo propio y enlazarlo con tu instancia de Kibana.

Primeros pasos

Echa un vistazo al código, y pruébalo tú mismo aquí.

Todos somos testigos del auge de los agentes de IA. Son fantásticos para resumir texto, escribir fragmentos de código y responder preguntas basadas en la documentación. Pero para quienes trabajamos en DevOps y en ingeniería de confiabilidad de sitios (SRE), existe una limitación frustrante. La mayoría de los agentes están atrapados en el paradigma del centro de llamadas, lo que significa que pueden leer, pensar y chatear, pero no pueden interactuar con la infraestructura que se supone que deben administrar.

Para nuestro último proyecto de hackathon, decidimos superar esa limitación.

Desarrollamos infraestructura aumentada: un copiloto de infraestructura que no solo te da consejos, sino que también crea, despliega, monitorea y corrige el entorno en vivo.

El problema: copiar, reformatear, pegar

Los agentes estándar operan en el vacío. Si una app se cae y le cuesta a la compañía $5 millones, un agente estándar puede leerte el libro de apuntes sobre cómo arreglarlo. Pero sigue siendo tu responsabilidad hacer el trabajo. Ahora solo tienes que copiar el código, adaptarlo al entorno y pegarlo en tu terminal.

Queríamos crear un agente que entendiera la diferencia entre hablar de Kubernetes y configurar Kubernetes.

El motor: ¿Qué es Elastic Agent Builder?

Para desarrollarlo no empezamos desde cero. Partimos de Elastic Agent Builder. Para quienes no lo conozcan, Elastic Agent Builder es un marco de trabajo diseñado para desarrollar agentes de forma rápida, y actúa como puente entre un gran modelo de lenguaje (LLM) (en nuestra demo usamos Google Gemini) y los datos privados almacenados en Elasticsearch.

Agent Builder se puede usar para la IA conversacional si se lo basa en datos internos, como documentos o registros. Pero su característica más poderosa es la capacidad de asignar herramientas. Estas herramientas permiten al LLM salir de la interfaz de chat para realizar tareas específicas. Nos dimos cuenta de que si llevábamos esta característica al límite, podíamos transformar Agent Builder en una potencia de automatización.

Cómo hacerlo funcionar: desarrollo de la primera versión

Cuando empezamos el proyecto, sabíamos que queríamos que los agentes pudieran cambiar el mundo exterior. Pensamos lo siguiente: ¿y si construimos algún software “runner” (para ejecutar cualquier comando que el agente pueda pensar en el host)? Y luego: ¿qué pasaría si los runners, Elastic Agent Builder y el usuario estuvieran en una llamada los tres?

Empezamos desarrollando un proyecto en Python, Augmented Infrastructure Runners, que era esencialmente un bucle de while(true) que consultaba la API de conversaciones de Elastic Agent Builder cada segundo y verificaba una sintaxis especial que habíamos creado:

{
	"tool_name": "my_tool",
       "tool_arguments": "\{stringified json arguments\}"
}

Luego actualizamos la indicación para enseñarle sobre nuestra nueva sintaxis de llamada de herramienta. Bill es uno de los mantenedores de FastMCP, el marco de trabajo más popular para crear servidores del Protocolo de Contexto de Modelo (MCP) en Python. Se propuso trabajar usando el cliente FastMCP con este nuevo software runner para montar servidores MCP y poner sus herramientas a disposición del runner. Cuando el agente veía esto, ejecutaba la llamada a la herramienta y POST enviaba los resultados de vuelta a la conversación como si el usuario hubiera enviado los resultados. Esto hizo que el LLM respondiera al resultado, ¡y seguimos adelante!

Fue genial, pero tuvo dos problemas principales:

1. El agente soltaba todo este JSON directamente a la conversación con el usuario.
2. El primer momento en el que los mensajes se podían ver a través de la API de conversaciones era cuando se completaba una ronda de conversación (es decir, cuando el LLM respondía).

Así que nos propusimos descubrir cómo llevarlo a segundo plano.

Luego probamos darle al agente una herramienta llamada call_external_tool con dos argumentos: el argumento de la herramienta tool_name y la herramienta JSON en strings. Esta llamada a la herramienta externa no devolvía nada, pero lo importante es que era visible en la solicitud GET a la API de conversaciones. Luego dimos licencia a los runners para escribir documentos directamente en Elasticsearch, los cuales el agente de Elastic Agent Builder podía recuperar según fuera necesario. El agente siempre está operando en respuesta a un mensaje del usuario, por lo que necesitamos iniciar el agente con un mensaje del usuario para que busque resultados y continúe con el procesamiento. Así que hicimos que los agentes insertaran un pequeño mensaje en el chat para reanudar la conversación:

Así que ya teníamos llamadas a herramientas externas. Sin embargo, debido al segundo problema mencionado anteriormente, tuvimos que deshacernos de esa parte final de arranque. De lo contrario, ¡cada llamada a una herramienta externa requería una ronda completa de conversación para recuperar los resultados!

Llevarlo a otro nivel: introducción a los flujos de trabajo

Además de las llamadas al lenguaje de búsqueda de Elasticsearch (ES|QL) y a las herramientas de búsqueda de índices, los agentes de Agent Builder pueden llamar a herramientas basadas en flujo de trabajo de Elastic. Los flujos de trabajo de Elastic ofrecen una forma flexible y fácil de gestionar para ejecutar una secuencia y una lógica de acciones arbitrarias. Para nuestros objetivos, todo lo que necesitamos que haga el flujo de trabajo es almacenar una solicitud externa de herramienta en Elasticsearch y devolver un ID para consultar los resultados. Esto da lugar a la siguiente definición sencilla de flujo de trabajo:

name: ai-tool-call
enabled: true
triggers:
  - type: manual
inputs:
  - name: runner_id
    type: string
  - name: tool_calls
    type: string

steps:
  - name: store_request
    type: elasticsearch.create
    with:
      index: distributed-tool-requests
      id: "{{inputs.runner_id}}_{{ execution.id }}"
      document:
        request_id: "{{ execution.id }}"
        runner_id: "{{inputs.runner_id}}"
        tool_call: "{{inputs.tool_calls}}"
        status: "unhandled"

  - name: output_result
    type: console
    with:
      message: "Called tool, with execution id: {{ execution.id }}. Use this ID to poll the results."

Con eso, en lugar de depender de que la solicitud de llamada a la herramienta se escriba en la conversación, los runners pueden simplemente consultar el índice de distributed-tool-requests de Elasticsearch para nuevas solicitudes externas de herramienta y hacer el reporte de los resultados en otro índice de Elasticsearch con la execution.id proporcionada.

Esto elimina los dos problemas principales mencionados anteriormente:

1. El historial de conversaciones ya no está lleno de datos de las llamadas a herramientas externas.
2. Como los runners consultan el índice de Elasticsearch en lugar del historial de conversaciones, no están bloqueados por la ronda de conversación que debe completarse para que las solicitudes de herramientas externas se hagan visibles.

El segundo punto tiene la gran ventaja de que el procesamiento de las llamadas a herramientas externas comienza dentro de la fase de pensamiento del agente (y no cuando se ha completado la ronda de conversación). Esto nos permite indicarle al modelo de lenguaje grande (LLM) en la indicación del sistema que consulte los resultados de la herramienta externa hasta que estén disponibles, lo que elimina la necesidad del mensaje de inicio. En general, esto tiene el efecto positivo de que la conversación se siente más natural: el LLM puede procesar varias solicitudes de herramienta externa dentro de una sola ronda de conversación (en vez de requerir una ronda de conversación por cada solicitud de herramienta) y, por tanto, puede realizar solicitudes de usuario más complejas de una sola vez.

Todo integrado

Para cerrar la brecha entre el LLM y el rack de servidores, desarrollamos una arquitectura específica empleando las capacidades de la herramienta de Agent Builder:

1. Runners de infraestructura aumentada: desplegamos runners ligeros dentro de los entornos de destino (servidores, clústeres de Kubernetes, cuentas en la cloud). Estos runners se conectan directamente a Elastic, utilizando endpoints seguros y secretos solo disponibles para cada uno de los runners.
2. ES|QL retrieval: el copiloto utiliza ES|QL de Elastic para realizar búsquedas híbridas. No solo realiza una búsqueda en base de conocimientos sino también de capacidades. Consulta a los runners conectados para ver qué herramientas están disponibles (por ejemplo, list_ec2_instances, install_helm_chart).
3. Ejecución del flujo de trabajo: una vez que el agente decide un curso de acción, crea un flujo de trabajo estructurado.
4. Ciclo de retroalimentación: los runners ejecutan el comando de forma local y envían los resultados de vuelta a Elasticsearch. El copiloto lee el resultado del índice y decide el siguiente paso.

La demo: de interrupción a observabilidad

En el video, mostramos dos casos distintos que demuestran la potencia de esta arquitectura.

Escenario 1: Rescate de DevOps

Empezamos con un usuario que estaba preocupado por una interrupción de 5 millones de dólares causada por un punto ciego en su clúster de Kubernetes.

• La solicitud: "¿Cómo me aseguro de que esto no vuelva a suceder?"
• La acción: el agente no solo proporcionó un tutorial. Identificó el clúster, creó los espacios de nombres necesarios, generó secretos de Kubernetes, instaló el operador OpenTelemetry e instantáneamente proporcionó un enlace a un dashboard APM en vivo.
• El resultado: observabilidad completa de Kubernetes e información de aplicación sin que el usuario escriba ni una sola línea de YAML.

Caso 2: entrega de Security

Una regla fundamental de la seguridad de infraestructuras es que no puedes proteger lo que no puedes ver. Mientras llevamos a cabo nuestra intervención de DevOps, el agente ve una oportunidad para mejorar la seguridad del entorno.

Con una alerta iniciada tras una investigación previa relacionada con Elastic Observability, demostramos cómo un profesional de seguridad puede comunicarse directamente con su infraestructura: primero, para enumerar los activos y recursos en su entorno cloud; y segundo, para desplegar las herramientas necesarias para asegurarse de que el entorno esté protegido.

• Descubrimiento: el copiloto enumeró los recursos de AWS para el profesional de la seguridad e identificó una brecha crítica: una instancia de Amazon Elastic Compute Cloud (EC2) y un clúster de Amazon Elastic Kubernetes Service (EKS) con terminales públicos que no tienen protección para endpoints.
• Remediación: con una simple aprobación, el copiloto desplegó Elastic Security detección y respuesta extendida (XDR) y detección y respuesta en el cloud (CDR) a los activos vulnerables, asegurando el entorno en tiempo real.
• El resultado: protección de los activos y recursos de AWS desplegados con seguridad en tiempo de ejecución completa.

El futuro: todo aumentado

Este proyecto demuestra que Elastic Agent Builder puede ser el cerebro central de las operaciones distribuidas. No nos limitamos solo a infraestructura. Nuestra tecnología runner puede impulsar:

• Synthetics aumentados: diagnosticar errores de TLS en runners globales.
• Desarrollo aumentado: crear pull requests e implementar CAPTCHAs en servicios frontend.
• Operaciones aumentadas: reconfiguración automática de los servidores DNS durante una interrupción.

Pruébalo tú mismo

Creemos que el futuro de la IA no se trata solo de soporte por chat; se trata de infraestructura aumentada. Se trata de tener un socio que pueda desplegar, arreglar, observar y proteger a la par tuya.

¡Descubre el código y pruébalo tú mismo con runners distribuidos (GitHub) más Elastic Agent Builder en Elastic Cloud Serverless hoy mismo!

• Crea un proyecto serverless en Elastic Cloud.
• Despliega el código en un ejecutor.
• Configura el runner.
• Configura tu archivo mcp.json.
• Inicia el runner, el cual creará de forma automática tu agente y sus herramientas.
• ¡Chatea con un agente que puede razonar, planificar y ejecutar acciones en tus runners distribuidos!

El equipo: Alex, Bill, Gil, Graham, & Norrie

¿Por qué importa esto?

La mayoría de los flujos de trabajo analíticos típicos acaban reduciéndose a agrupar datos. Ya sea para calcular el promedio de bytes por host, contar eventos por usuario o agregar métricas en diferentes dimensiones, la operación de núcleo es la misma: asignar claves a grupos y actualizar los agregados en ejecución.

A pequeña escala, casi cualquier tabla hash razonable funciona bien. A gran escala (cientos de millones de documentos y millones de grupos distintos), los detalles empiezan a importar. Los factores de carga, la estrategia de sondeo, el diseño de la memoria y el comportamiento de la memoria caché pueden marcar la diferencia entre un rendimiento lineal y una barrera de fallos de caché.

Elasticsearch ha soportado estas cargas de trabajo durante años, pero siempre estamos buscando oportunidades para modernizar los algoritmos de núcleo. Por lo tanto, evaluamos un enfoque más reciente inspirado en las tablas suizas y lo aplicamos a cómo ES|QL calcula las estadísticas.

¿Qué son realmente las tablas suizas?

Las tablas suizas son una familia de tablas hash modernas popularizadas por la SwissTable de Google y posteriormente adoptadas en Abseil y otras bibliotecas.

Las tablas hash tradicionales pasan mucho tiempo persiguiendo punteros o cargando claves solo para descubrir que no coinciden. La característica definitoria de las tablas suizas es la capacidad de rechazar la mayoría de las sondas usando una pequeña estructura de matriz residente en caché, almacenada separadamente de las claves y valores, llamadas bytes de control, para reducir significativamente el tráfico de memoria.

Cada byte de control representa un solo slot y, en nuestro caso, codifica dos cosas: si el slot está vacío y una huella corta derivada del hash. Estos bytes de control están dispuestos de forma continua en la memoria, típicamente en grupos de 16, lo que los hace ideales para el procesamiento de una sola instrucción y múltiples datos (SIMD).

En lugar de sondear una ranura a la vez, las tablas suizas escanean todo un bloque de bytes de control utilizando instrucciones vectoriales. En una sola operación, la CPU compara la huella digital de la clave entrante con 16 ranuras y filtra las entradas vacías. Solo los pocos candidatos que sobreviven a esta ruta rápida requieren cargar y comparar las claves reales.

Este diseño intercambia una pequeña cantidad de metadatos adicionales por una mejor localización de caché y muchas menos cargas aleatorias. A medida que la tabla crece y las cadenas de sonda se alargan, esas propiedades se vuelven cada vez más valiosas.

SIMD en el centro

La verdadera estrella del espectáculo es SIMD.

Los bytes de control no solo son compactos, sino que también están diseñados explícitamente para ser procesados con instrucciones vectoriales. Una sola comparación SIMD puede verificar 16 huellas dactilares a la vez, lo que convierte lo que normalmente sería un bucle en un puñado de operaciones amplias. Por ejemplo:

En la práctica, esto significa:

• Menos ramas.
• Cadenas de sondeo más cortas.
• Menos cargas de la memoria de claves y valores.
• Mucho mejor utilización de las unidades de ejecución de la CPU.

La mayoría de las búsquedas nunca pasan del escaneo de bytes de control. Cuando lo hacen, el trabajo restante es enfocado y previsible. Este es precisamente el tipo de carga de trabajo en el que destacan las CPU modernas.

SIMD bajo el capó

Para los lectores a quienes les gusta echar un vistazo por dentro, aquí está lo que sucede al insertar una nueva clave en la tabla. Utilizamos la API Panama Vector con vectores de 128 bits, por lo que opera en 16 bytes de control en paralelo.

El siguiente fragmento muestra el código generado en un Intel Rocket Lake con AVX-512. Aunque las instrucciones reflejan ese entorno, el diseño no depende de AVX-512. Las mismas operaciones vectoriales de alto nivel se emiten en otras plataformas usando instrucciones equivalentes (por ejemplo, AVX2, SSE o NEON).

; Load 16 control bytes from the control block
vmovdqu xmm0, XMMWORD PTR [r9+r10*1+0x10]

; Broadcast the 7-bit fingerprint of the new key across the vector
vpbroadcastb xmm1, r11d

; Compare all 16 control bytes to the new fingerprint
vpcmpeqb k7, xmm0, xmm1
kmovq rbx, k7

; Check if any matches were found
test rbx, rbx
jne 

Cada instrucción tiene una función clara en el proceso de inserción:

• vmovdqu: Carga 16 bytes de control consecutivos en el registro xmm0 de 128 bits.
• vpbroadcastb:Replica la huella digital de 7 bits de la nueva clave en todos los carriles del registro xmm1.
• vpcmpeqb: Compara cada byte de control con la huella digital transmitida, lo que genera una máscara de posibles coincidencias.
• kmovq + test: Mueve la máscara a un registro de propósito general y comprueba rápidamente si existe una coincidencia.

Finalmente, decidimos sondear grupos de 16 bytes de control a la vez, ya que las pruebas de rendimiento mostraron que expandirse a 32 o 64 bytes con registros más amplios no proporcionaba ningún beneficio de rendimiento medible.

Integración en ES|QL

Adoptar el hash al estilo suizo en Elasticsearch no fue solo un reemplazo inmediato. ES|QL tiene exigencias estrictas en cuanto a contabilidad de memoria, seguridad e integración con el resto del motor de cálculo.

Integramos la nueva tabla hash estrechamente con la gestión de memoria de Elasticsearch, que incluye el reciclador de páginas y la contabilidad del interruptor de circuito, lo que garantiza que las asignaciones permanezcan visibles y limitadas. Las agregaciones de Elasticsearch se almacenan densamente y se indexan por un ID de grupo, lo que mantiene el diseño de memoria compacto y rápido para la iteración, además de habilitar ciertas optimizaciones de rendimiento al permitir el acceso aleatorio.

Para las claves de bytes de longitud variable, almacenamos en caché el hash completo junto con el ID del grupo. Esto evita la recomputación de costosos códigos hash durante el sondeo y mejora la localidad de la caché al mantener los metadatos relacionados juntos. Durante el reprocesamiento, podemos confiar en el hash en caché y en los bytes de control sin inspeccionar los valores en sí, lo que mantiene bajos los costos de redimensionamiento.

Una simplificación importante en nuestra implementación es que las entradas nunca se eliminan. Esto elimina la necesidad de marcadores (marcadores para identificar ranuras previamente ocupadas) y permite que las ranuras vacías permanezcan verdaderamente vacías, lo que mejora aún más el comportamiento de la sonda y mantiene eficientes los escaneos de bytes de control.

El resultado es un diseño que se ajusta naturalmente al modelo de ejecución de Elasticsearch a la vez que preserva las características de rendimiento que hacen atractivas a las tablas suizas.

¿Cómo funciona?

En cardinalidades pequeñas, las tablas suizas rinden aproximadamente al mismo nivel que la implementación existente. Esto es lo que se espera: cuando las tablas son pequeñas, los efectos de la caché tienen menos importancia y hay poco que optimizar.

A medida que aumenta la cardinalidad, la imagen cambia rápidamente.

El mapa de calor anterior traza los factores de mejora del tiempo para diferentes tamaños de clave (8, 32, 64 y 128 bytes) en cardinalidades desde 1,000 hasta 10,000,000 de grupos. A medida que aumenta la cardinalidad, el factor de mejora aumenta constantemente, y llega a hasta 2–3x para distribuciones uniformes.

Esta tendencia es exactamente lo que predice el diseño. Una cardinalidad más alta conduce a cadenas de sondeo más largas en las tablas hash tradicionales, mientras que el sondeo de estilo suizo continúa resolviendo la mayoría de las búsquedas dentro de los bloques de bytes de control amigables con SIMD.

El comportamiento de la caché cuenta la historia

Para comprender mejor las aceleraciones, ejecutamos el mismo JMH benchmarks en Linux perf y capturamos estadísticas de caché y TLB.

En comparación con la implementación original, la versión suiza realiza aproximadamente un 60% menos de referencias de caché en general. Las cargas de la caché de último nivel disminuyen más de 4 veces, y los fallos de carga de la LLC caen en más de 6 veces. Dado que las omisiones de LLC a menudo se traducen directamente en accesos a la memoria principal, esta reducción por sí sola explica una gran parte de la mejora de extremo a extremo.

Más cerca de la CPU, vemos menos pérdidas de caché de datos L1 y casi 6 veces menos pérdidas TLB de datos, lo que apunta a una localidad espacial más estrecha y patrones de acceso a la memoria más predecibles.

Esta es la recompensa práctica de los bytes de control compatibles con SIMD. En lugar de cargar repetidamente claves y valores desde ubicaciones de memoria dispersas, la mayoría de las pruebas se resuelven escaneando una estructura compacta residente en la caché. Menos memoria afectada significa menos fallos, y menos fallos significan consultas más rápidas.

Resumen

Al adoptar un diseño de tabla hash al estilo suizo y al inclinarnos por el sondeo amigable con SIMD, logramos una velocidad de 2 a 3 veces mayor para cargas de trabajo de estadísticas ES|QL de alta cardinalidad, junto con un rendimiento más estable y predecible.

Este trabajo destaca cómo las estructuras de datos modernas con conocimiento de CPU pueden desbloquear ganancias sustanciales, incluso para problemas bien conocidos, como las tablas hash. Hay más para explorar aquí, como especializaciones adicionales de tipo primitivo y el uso en otras rutas de alta cardinalidad, como las uniones, que son solo parte del esfuerzo más amplio y continuo para modernizar continuamente los internos de Elasticsearch.

Si te interesan los detalles o quieres seguir el trabajo, echa un vistazo a esta solicitud de extracción y problema meta en Github.

¡Feliz hash!

Después de todo, todo en el contexto influye en las respuestas de la IA. Es cierto lo que dicen: "Lo que das es lo que recibes".

En este artículo, presentaremos lo que significan la memoria a corto y a largo plazo para los agentes de IA, específicamente:

• La diferencia entre la memoria a corto y a largo plazo.
• Cómo se relacionan con las técnicas de RAG con bases de datos vectoriales, como Elasticsearch, y por qué es necesaria una gestión cuidadosa de la memoria.
• Los riesgos de descuidar la memoria, como el desbordamiento de contexto y el envenenamiento por contexto.
• Las mejores prácticas, como podar el contexto, resumir y recuperar solo lo relevante, para mantener la memoria de un agente útil y segura.
• Finalmente, hablaremos sobre cómo compartir y propagar la memoria en sistemas multiagente para que los agentes colaboren sin confusión mediante Elasticsearch.

Memoria a corto plazo frente a memoria a largo plazo en los agentes de IA

La memoria a corto plazo en un agente de IA suele referirse al contexto o estado conversacional inmediato, es decir, al historial de chat actual o a los mensajes recientes de la sesión activa. Esto incluye la última consulta del usuario y los intercambios recientes. Es muy similar a la información que una persona tiene en mente durante una conversación.

Los marcos de trabajo de IA suelen mantener esta memoria transitoria como parte del estado del agente (por ejemplo, al utilizar un checkpointer para almacenar el estado de la conversación, como se muestra en este ejemplo de LangGraph). La memoria a corto plazo es de sesión; es decir, existe dentro de una sola conversación o tarea y se restablece o borra cuando esa sesión termina, a menos que se guarde explícitamente en otro lugar. Un ejemplo de memoria a corto plazo limitada a sesiones sería el chat temporal disponible en ChatGPT.

Memoria a largo plazo, por otro lado, se refiere a la información que persiste a través de conversaciones o sesiones. Este es el conocimiento que un agente conserva a lo largo del tiempo, los datos que aprendió antes, las preferencias del usuario o cualquier dato que le hayamos dicho que recuerde permanentemente.

La memoria a largo plazo generalmente se implementa almacenándola y recuperándola de una fuente externa, como un archivo o una base de datos vectorial que está fuera de la ventana de contexto inmediata. A diferencia de la memoria de chat a corto plazo, la memoria a largo plazo no se incluye automáticamente en cada solicitud. En cambio, basado en un escenario dado, el agente debe recuperarla u obtenerla cuando se invocan las herramientas relevantes. En la práctica, la memoria a largo plazo puede incluir la información del perfil del usuario, respuestas o análisis previos realizados por el agente, o una base de conocimientos que el agente puede consultar.

Por ejemplo, si tienes un agente planificador de viajes, la memoria a corto plazo contendría detalles de la consulta actual del viaje (fechas, destino, presupuesto) y cualquier pregunta de seguimiento en esa conversación; mientras que la memoria a largo plazo podría almacenar las preferencias generales de viaje del usuario, itinerarios pasados y otros datos compartidos en sesiones anteriores. Cuando el usuario regresa más tarde, el agente puede extraer de este almacenamiento a largo plazo (por ejemplo, al usuario le encantan las playas y las montañas, tiene un presupuesto promedio de 100 000 INR, tiene una lista de deseos de lugares para visitar y prefiere experimentar la historia y la cultura en lugar de atracciones para niños) de modo que no trate al usuario como una pizarra en blanco todo el tiempo.

La memoria a corto plazo (historial de chat) proporciona un contexto inmediato y continuidad, mientras que la memoria a largo plazo proporciona un contexto más amplio del que el agente puede extraer cuando sea necesario. La mayoría de los marcos de trabajo de agentes de IA avanzados permiten ambas posibilidades: realizan un seguimiento de los diálogos recientes para mantener el contexto y ofrecen mecanismos para buscar o almacenar información en un repositorio a más largo plazo. La gestión de la memoria a corto plazo garantiza que se mantenga dentro de la ventana de contexto, mientras que la gestión de la memoria a largo plazo ayuda al agente a fundamentar las respuestas basadas en interacciones previas y personalidades.

Memoria y RAG en ingeniería de contexto

¿Cómo le damos a un agente de IA una memoria útil a largo plazo en la práctica?

Un enfoque destacado para la memoria a largo plazo es la memoria semántica, que a menudo se implementa mediante generación aumentada de recuperación (RAG). Esto implica acoplar el LLM con una tienda de conocimiento externa o un almacén de datos habilitado para vectores, como Elasticsearch. Cuando el LLM necesita información más allá de lo que aparece en el prompt o en su entrenamiento integrado, realiza una recuperación semántica contra Elasticsearch e inyecta los resultados más relevantes en el prompt como contexto. De esta manera, el contexto efectivo del modelo incluye no solo la conversación reciente (memoria a corto plazo), sino también datos pertinentes a largo plazo que se obtienen sobre la marcha. A continuación, el LLM basa su respuesta tanto en su propio razonamiento como en la información recuperada, combinando eficazmente la memoria a corto plazo y la memoria a largo plazo para producir una respuesta más precisa y consciente del contexto.

Elasticsearch puede emplearse para implementar memoria a largo plazo para agentes de IA. Aquí hay un ejemplo de alto nivel de cómo se puede recuperar el contexto de Elasticsearch para la memoria a largo plazo.

De esta manera, el agente "recuerda" al buscar datos relevantes en lugar de almacenar todo en su limitado prompt, lo que conduce a diferentes riesgos.

Usar RAG con Elasticsearch o cualquier almacén vectorial ofrece múltiples beneficios:

Primero, amplía el conocimiento del modelo más allá de su límite de entrenamiento. El agente puede recuperar información actualizada o datos específicos del dominio que el LLM podría desconocer. Esto es crucial para preguntas sobre eventos recientes o temas especializados.

Segundo, obtener contexto bajo demanda ayuda a reducir las alucinaciones, especialmente porque los LLM no están capacitados con datos propietarios o altamente especializados en relación con tu caso de uso específico, lo que probablemente los exponga a alucinaciones. En lugar de que el LLM adivine o invente nueva información como se incentivó mediante la evaluación, como se destaca en un reciente artículo de OpenAI (Por qué alucinan los modelos de lenguaje), el modelo puede basarse en referencias factuales de Elasticsearch. Naturalmente, el LLM depende de la fiabilidad de los datos almacenados en el vector para realmente prevenir la desinformación, y los datos relevantes se recuperan según las medidas de relevancia de núcleo.

Tercero, la RAG permite que un agente trabaje con bases de conocimientos mucho más grandes de lo que podrías incluir en un prompt. En lugar de enviar documentos completos, como largos trabajos de investigación o documentos de políticas, a la ventana de contexto y correr el riesgo de que la sobrecarga o el contexto de información irrelevante envenene el razonamiento del modelo, la RAG se basa en la fragmentación. Los documentos grandes se dividen en piezas más pequeñas y semánticamente significativas, y el sistema recupera solo los fragmentos más relevantes para la consulta. De esta manera, el modelo no necesita un contexto de un millón de tokens para parecer conocedor; solo necesita acceso a los fragmentos correctos de un corpus mucho más grande.

Vale la pena señalar que, a medida que las ventanas de contexto de LLM crecieron (algunos modelos ahora admiten cientos de miles o incluso millones de tokens), surgió un debate sobre si la RAG está "muerta". ¿Por qué no enviar todos los datos al prompt? Si te preguntas lo mismo, consulta este maravilloso artículo de mis colegas, Jeffrey Rengifo y Eduard Martin, Contexto más largo ≠ mejor: Por qué la RAG sigue siendo importante. Esto evita el problema de la "Lo que das es lo que recibes": El LLM se mantiene enfocado en los pocos fragmentos que importan, en lugar de ejecutarse a través del ruido.

Dicho esto, integrar Elasticsearch o cualquier almacén vectorial en una arquitectura de agente de IA proporciona memoria a largo plazo. El agente almacena el conocimiento externamente y lo recupera como contexto de memoria cuando es necesario. Esto se podría implementar como una arquitectura, en la que, tras cada consulta de usuario, el agente realiza una búsqueda en Elasticsearch para obtener información relevante y luego agrega los primeros resultados al prompt antes de llamar al LLM. La respuesta también podría guardarse en el almacén a largo plazo si contiene nueva información útil (lo que crea un bucle de retroalimentación de aprendizaje). Al usar una memoria basada en recuperación, el agente se mantiene informado y actualizado, sin tener que abarrotar todo lo que sabe en cada solicitud, a pesar de que la ventana de contexto admite un millón de tokens. Esta técnica es una piedra angular de la ingeniería de contexto, ya que combina las ventajas de la recuperación de información y la IA generativa.

Aquí hay un ejemplo de un estado de conversación gestionado en memoria usando el sistema de puntos de control de LangGraph para la memoria a corto plazo durante la sesión. (Consulta nuestra app de ingeniería de contexto de apoyo).

# Initialize chat memory (Note: This is in-memory only, not persistent)
memory = MemorySaver()

# Create a LangGraph agent
langgraph_agent = create_react_agent(model=llm, tools=tools, checkpointer=memory)

...
...
# Only process and display checkpoints if verbose mode is enabled
if args.verbose:
    # List all checkpoints that match a given configuration
    checkpoints = memory.list({"configurable": {"thread_id": "1"}})
    # Process the checkpoints
    process_checkpoints(checkpoints)

Así es como almacena los puntos de control:

Checkpoint:
Timestamp: 2025-12-30T09:19:41.691087+00:00
Checkpoint ID: 1f0e560a-c2fa-69ec-8001-14ee5373f9cf
User: Hi I'm Som, how are you? (Message ID: ad0a8415-5392-4a58-85ad-84154875bbf2)
Agent: Hi Som! I'm doing well, thank you! How about you? (Message ID: 
56d31efb-14e3-4148-806e-24a839799ece)
Agent:  (Message ID: lc_run--019b6e8e-553f-7b52-8796-a8b1fbb206a4-0)

Checkpoint:
Timestamp: 2025-12-30T09:19:40.350507+00:00
Checkpoint ID: 1f0e560a-b631-6a08-8000-7796d108109a
User: Hi I'm Som, how are you? (Message ID: ad0a8415-5392-4a58-85ad-84154875bbf2)
Agent: Hi Som! I'm doing well, thank you! How about you? (Message ID: 
56d31efb-14e3-4148-806e-24a839799ece)

Checkpoint:
Timestamp: 2025-12-30T09:19:40.349027+00:00
Checkpoint ID: 1f0e560a-b62e-6010-bfff-cbebe1d865f6

Para la memoria a largo plazo, así es como realizamos la búsqueda semántica en Elasticsearch para recuperar conversaciones previas relevantes usando embeddings vectoriales tras resumir e indexar los puntos de control en Elasticsearch.

Functions: 
retrieve_from_elasticsearch() 

# Enhanced Elasticsearch retrieval with rank_window and verbose display
def retrieve_from_elasticsearch(query: str, k: int = 5, rank_window: int = None) -> tuple[List[Dict[str, Any]], str]:
    """
    Retrieve context from Elasticsearch with score-based ranking
    
    Args:
        query: Search query
        k: Number of results to return
        rank_window: Number of candidates to retrieve before ranking (default: args.rank_window)
        
    Returns:
        Tuple of (retrieved_documents, formatted_context_string)
    """
    if not es_client or not es_index_name:
        return [], "Elasticsearch is not available. Cannot search long-term memory."
    
    if rank_window is None:
        rank_window = args.rank_window
    
    try:
        # Check if index exists and has documents
        if not es_client.indices.exists(index=es_index_name):
            return [], "No previous conversations stored in long-term memory yet."
        
        # Get document count
        try:
            doc_count = es_client.count(index=es_index_name)["count"]
            if doc_count == 0:
                return [], "Long-term memory is empty. No previous conversations to search."
        except Exception as e:
            return [], f"Error checking memory: {str(e)}"
        
        # Generate embedding for the query
        try:
            query_embedding = embeddings.embed_query(query)
        except Exception as e:
            return [], f"Error generating embedding: {str(e)}"
        
        # Perform semantic search using kNN with rank_window
        try:
            search_body = {
                "knn": {
                    "field": "vector",
                    "query_vector": query_embedding,
                    "k": k,
                    "num_candidates": rank_window  # Retrieve more candidates, then rank top k
                },
                "_source": ["text", "content", "message_type", "timestamp", "thread_id"],
                "size": k
            }
            
            response = es_client.search(index=es_index_name, body=search_body)
            
            if not response.get("hits") or len(response["hits"]["hits"]) == 0:
                return [], "No relevant previous conversations found in long-term memory."
            
            # Extract documents with scores
            retrieved_docs = []
            for hit in response["hits"]["hits"]:
                source = hit["_source"]
                score = hit["_score"]
                retrieved_docs.append({
                    "content": source.get("content", source.get("text", "")),
                    "message_type": source.get("message_type", "unknown"),
                    "timestamp": source.get("timestamp", "unknown"),
                    "thread_id": source.get("thread_id", "unknown"),
                    "score": score
                })
            
            # Format context string
            context_parts = []
            for i, doc in enumerate(retrieved_docs, 1):
                context_parts.append(doc["content"])
            
            context_string = "\n\n".join(context_parts)
            
            # Verbose display
            if args.verbose:
                rich.print(f"\n[bold yellow]🔍 RETRIEVAL ANALYSIS[/bold yellow]")
                rich.print("="*80)
                rich.print(f"[blue]Query:[/blue] {query}")
                rich.print(f"[blue]Retrieved:[/blue] {len(retrieved_docs)} documents (from {rank_window} candidates)")
                rich.print(f"[blue]Total context length:[/blue] {len(context_string)} characters\n")
                
                for i, doc in enumerate(retrieved_docs, 1):
                    rich.print(f"[cyan]📄 Document {i} | Score: {doc['score']:.4f} | Type: {doc['message_type']}[/cyan]")
                    rich.print(f"[cyan]   Timestamp: {doc['timestamp']} | Thread: {doc['thread_id']}[/cyan]")
                    content_preview = doc['content'][:200] + "..." if len(doc['content']) > 200 else doc['content']
                    rich.print(f"[cyan]   Content: {content_preview}[/cyan]")
                    rich.print("-" * 80)
            
            return retrieved_docs, context_string
            
        except Exception as e:
            return [], f"Error searching memory: {str(e)}"
            
    except Exception as e:
        return [], f"Error accessing long-term memory: {str(e)}"

Ahora que hemos explorado cómo se indexan y recuperan la memoria a corto y largo plazo usando los puntos de control de LangGraph en Elasticsearch, tomemos un momento para entender por qué indexar y eliminar las conversaciones completas puede ser riesgoso.

Riesgos de no gestionar la memoria de contexto

Como hablamos mucho sobre ingeniería de contexto, junto con la memoria a corto y largo plazo, entendamos qué sucede si no gestionamos bien la memoria y el contexto de un agente.

Desafortunadamente, muchas cosas pueden salir mal cuando el contexto de una IA se vuelve extremadamente largo o contiene información errónea. A medida que las ventanas de contexto se agrandan, surgen nuevos tipos de falla, como:

• Envenenamiento por contexto
• Distracción del contexto
• Confusión de contexto
• Choque de contexto
• Fuga de contexto y conflictos de conocimiento
• Alucinaciones e información errónea

Hagamos un desglose de estos problemas y otros riesgos que surgen de una mala gestión del contexto:

Envenenamiento por contexto

El envenenamiento por contexto se refiere a cuando la información incorrecta o dañina termina en el contexto y "envenena" las salidas posteriores del modelo. Un ejemplo común es una alucinación del modelo que se trata como un hecho y se inserta en el historial de conversaciones. El modelo podría entonces aprovechar ese error en respuestas posteriores, lo que agravaría el error. En los bucles iterativos de agentes, una vez que una información falsa se introduce en el contexto compartido (por ejemplo, en un resumen de las notas de trabajo del agente), puede reforzarse una y otra vez.

Los investigadores de DeepMind, en la publicación del reporte Gemini 2.5 (TL;DR, consulta aquí), observaron esto en un agente que jugaba a Pokémondesde hacía mucho tiempo: si el agente alucinaba un estado de juego erróneo y eso quedaba registrado en su contexto (su memoria de objetivos), el agente formaba estrategias sin sentido en torno a un objetivo imposible y se quedaba atascado. En otras palabras, un recuerdo contaminado puede llevar al agente por el camino equivocado de forma indefinida.

El envenenamiento del contexto puede ocurrir de forma inocente (por error) o incluso maliciosa, por ejemplo, mediante ataques de inyección de prompt donde un usuario o un tercero introduce una instrucción oculta o un hecho falso que el agente luego recuerda y sigue.

Contramedidas recomendadas:

Basándose en la información de Wiz, Zerlo y Anthropic, las contramedidas para el envenenamiento del contexto se centran en prevenir que la información errónea o engañosa entre en la ventana de contexto, el pipeline de recuperación o la ventana de contexto de un LLM. Los pasos clave incluyen:

• Revisa el contexto constantemente: monitoriza la conversación o el texto recuperado para detectar cualquier cosa sospechosa o dañina, no solo el prompt inicial.
• Utiliza fuentes confiables: Puntúa o etiqueta los documentos según su credibilidad para que el sistema prefiera la información confiable e ignore los datos con baja puntuación.
• Detecta datos inusuales: usa herramientas que detecten contenido extraño, fuera de lugar o manipulado, y elimínalo antes de que el modelo lo use.
• Filtra entradas y salidas: Añade salvaguardas para que el texto dañino o engañoso no pueda entrar fácilmente en el sistema ni ser repetido por el modelo.
• Mantén el modelo actualizado con datos limpios: actualiza regularmente el sistema con información verificada para contrarrestar cualquier dato incorrecto que haya pasado desapercibido.
• Intervención humana: Haz que las personas revisen las salidas importantes o las comparen con fuentes conocidas y confiables.

Los hábitos sencillos de los usuarios también ayudan, como restablecer los chats largos, compartir solo información relevante, dividir las tareas complejas en pasos más pequeños y mantener notas claras fuera del modelo.

En conjunto, estas medidas crean una defensa en capas que protege a los LLMs del envenenamiento del contexto y mantiene las salidas precisas y fiables.

Sin contramedidas como las mencionadas aquí, un agente podría recordar instrucciones, como ignorar directrices previas o datos triviales que un atacante introdujo, lo que podría provocar salidas dañinas.

Distracción del contexto

Distracción por contexto es cuando un contexto crece tanto que el modelo se sobreenfoca en el contexto, y descuida lo que aprendió durante el entrenamiento. En casos extremos, esto se asemeja al olvido catastrófico; es decir, el modelo efectivamente "olvida" su conocimiento subyacente y se apega demasiado a la información colocada frente a él. Estudios previos han demostrado que los LLM a menudo pierden el enfoque cuando la solicitud es extremadamente larga.

El agente Gemini 2.5, por ejemplo, admitía una ventana de un millón de tokens, pero una vez que su contexto creció más allá de cierto punto (del orden de 100 000 tokens en un experimento), comenzó a fijarse en repetir sus acciones pasadas en lugar de encontrar nuevas soluciones. En cierto sentido, el agente se convirtió en prisionero de su extensa historia. Siguió mirando su largo log de movimientos anteriores (el contexto) e imitándolos, en lugar de usar su conocimiento de entrenamiento subyacente para diseñar estrategias nuevas y novedosas.

Esto es contraproducente. Queremos que el modelo emplee el contexto relevante para ayudar al razonamiento, no para anular su capacidad de pensamiento. Cabe destacar que incluso los modelos con ventanas enormes presentan esta podredumbre contextual: su rendimiento se degrada de forma no uniforme a medida que se agregan más tokens. Parece haber un presupuesto de atención. Al igual que los humanos con memoria de trabajo limitada, un LLM tiene una capacidad finita para atender a los tokens, y a medida que ese presupuesto se estira, su precisión y enfoque disminuyen.

Como medida de mitigación, puedes prevenir la distracción del contexto usando fragmentación, ingeniería de la información correcta, resumen regular del contexto y técnicas de evaluación y seguimiento para medir la precisión de la respuesta mediante puntaje.

Estos métodos mantienen el modelo basado tanto en el contexto relevante como en su entrenamiento subyacente, lo que reduce el riesgo de distracción y mejora la calidad general del razonamiento.

Confusión de contexto

La confusión de contexto ocurre cuando el modelo emplea contenido superfluo en el contexto para generar una respuesta de baja calidad. Un ejemplo claro es dar a un agente un gran conjunto de herramientas o definiciones de API que podría emplear. Si muchas de esas herramientas no están relacionadas con la tarea actual, el modelo puede intentar usarlas de forma inapropiada, simplemente porque están presentes en contexto. Los experimentos demostraron que proporcionar más herramientas o documentos puede perjudicar el rendimiento si no se necesitan todos. El agente empieza a cometer errores, como llamar a la función equivocada o referenciar texto irrelevante.

En un caso, un pequeño modelo Llama 3.1 8B falló en una tarea cuando se le dieron 46 herramientas para considerar, pero tuvo éxito cuando se le dieron solo 19 herramientas. Las herramientas adicionales crearon confusión, a pesar de que el contexto se ajustaba a los límites de longitud. El problema subyacente es que cualquier información en el mensaje será atendida por el modelo. Si no sabe ignorar algo, ese algo podría influir en su salida de maneras no deseadas. Los elementos irrelevantes pueden "robar" parte de la atención del modelo y llevarlo por el camino equivocado (por ejemplo, un documento irrelevante podría hacer que el agente responda a una pregunta diferente a la que se le hizo). La confusión contextual a menudo se manifiesta cuando el modelo produce una respuesta de baja calidad que integra contextos no relacionados. Consulta el artículo de investigación: Menos es más: optimización de la llamada de funciones para la ejecución de LLM en dispositivos periféricos.

Nos recuerda que más contexto no siempre es mejor, especialmente si no está curado para que sea relevante.

Choque de contexto

Choque de contexto ocurre cuando partes del contexto se contradicen entre sí, lo que causa inconsistencias internas que desvían el razonamiento del modelo. Puede producir un choque si el agente acumula múltiples piezas de información que están en conflicto.

Por ejemplo, imagina un agente que obtuvo datos de dos fuentes: una dice que el vuelo A sale a las 5 p. m. y la otra dice que el vuelo A sale a las 6 p. m. Si ambos hechos terminan en el contexto, el pobre modelo no tiene forma de saber cuál es el correcto; puede confundirse o producir una respuesta incorrecta o no similar.

El choque de contexto también ocurre frecuentemente en conversaciones de múltiples turnos donde los intentos anteriores del modelo de responder todavía persisten en el contexto junto con información refinada posterior.

Un estudio de investigación realizado por Microsoft y Salesforce muestra que si divides una consulta compleja en múltiples turnos de chatbot (agregando detalles gradualmente), la precisión final disminuye significativamente, en comparación con dar todos los detalles en un solo mensaje. ¿Por qué? Porque las primeras vueltas contienen respuestas intermedias parciales o incorrectas del modelo, y estas permanecen en el contexto. Cuando el modelo luego intenta responder con toda la información, su memoria aún incluye esos intentos incorrectos, que entran en conflicto con la información corregida y lo desvían del camino. Básicamente, el contexto de la conversación entra en conflicto consigo mismo. El modelo puede usar inadvertidamente una pieza de contexto desactualizada (de un turno anterior) que no se aplica después de que se agrega nueva información.

En los sistemas de agentes, el choque de contexto es especialmente peligroso porque un agente puede combinar las salidas de diferentes herramientas o subagentes. Si esas salidas no coinciden, el contexto agregado es inconsistente. El agente podría entonces quedarse atascado o producir resultados absurdos al tratar de conciliar las contradicciones. La prevención del choque de contexto implica asegurarse de que el contexto sea fresco y consistente, por ejemplo, borrar o actualizar cualquier información obsoleta y no mezclar fuentes que no hayan sido objeto de un estudio de consistencia.

Fuga de contexto y conflictos de conocimiento

En los sistemas en los que varios agentes o usuarios comparten un almacén de memoria, existe el riesgo de que la información se filtre entre contextos.

Por ejemplo, si las incrustaciones de datos de dos usuarios distintos residen en la misma base de datos vectorial sin un control de acceso adecuado, un agente que responda a la consulta del usuario A podría recuperar accidentalmente parte de la memoria del usuario B. Esta fuga entre contextos puede exponer información privada o simplemente crear confusión en las respuestas.

Según el Top 10 de OWASP para aplicaciones LLM, las bases de datos vectoriales de usuarios múltiples deben protegerse contra este tipo de fugas:

Según LLM08:2025 Debilidades de Vectores y Embedding, uno de los riesgos comunes es la fuga de contexto:

En entornos de múltiples usuarios donde varias clases de usuarios o aplicaciones comparten la misma base de datos vectorial, existe el riesgo de pérdida de contexto entre usuarios o consultas. Los errores de conflicto de conocimiento en la federación de datos pueden ocurrir cuando los datos de múltiples fuentes se contradicen entre sí. Esto también puede suceder cuando un LLM no puede reemplazar el conocimiento antiguo que aprendió durante el entrenamiento con los nuevos datos de generación aumentada.

Otro aspecto es que un LLM podría tener problemas para anular su conocimiento integrado con nueva información de memoria. Si el modelo fue entrenado con algún hecho y el contexto recuperado dice lo contrario, el modelo puede confundirse sobre cuál confiar. Sin un diseño adecuado, el agente podría confundir contextos o no actualizar el conocimiento antiguo con nueva evidencia, lo que llevaría a respuestas obsoletas o incorrectas.

Alucinaciones e información errónea

Mientras que una alucinación (el LLM inventa información plausible pero falsa) es un problema conocido incluso sin contextos largos, una mala gestión de la memoria puede amplificarlo.

Si la memoria del agente carece de un hecho crucial, el modelo puede llenar el vacío con una suposición, y si esa suposición entra en el contexto (envenenándolo), el error persiste.

El informe de seguridad de los LLM OWASP (LLM09:2025 Desinformación) destaca la desinformación como una vulnerabilidad de núcleo: los LLM pueden ofrecer respuestas seguras pero fabricadas, y los usuarios pueden confiar demasiado en ellos. Un agente con una memoria a largo plazo deficiente o desactualizada podría citar con confianza algo que era cierto el año pasado pero que ahora es falso, a menos que su memoria se mantenga actualizada.

La dependencia excesiva en la salida de la IA (ya sea por parte de los usuarios o del propio agente en un bucle) puede empeorar esta situación. Si nadie revisa nunca la información almacenada en la memoria, el agente puede acumular falsedades. Esta es la razón por la que la RAG se usa a menudo para reducir las alucinaciones: al recuperar una fuente autorizada, el modelo no tiene que inventar hechos. Pero si tu recuperación trae el documento incorrecto (digamos, uno que contiene información errónea) o si una alucinación temprana no se poda, el sistema puede propagar esa información errónea a través de sus acciones.

La conclusión: no administrar la memoria puede conducir a salidas incorrectas y engañosas, lo que puede ser perjudicial, especialmente si hay mucho en juego (por ejemplo, malos consejos en un dominio financiero o médico). Un agente necesita mecanismos para verificar o corregir su contenido de memoria, no solo confiar incondicionalmente en lo que esté en el contexto.

En resumen, darle a un agente de IA una memoria infinitamente larga o volcar cada cosa posible en su contexto no es una receta para el éxito.

Mejores prácticas para la gestión de memoria en aplicaciones LLM

Para evitar las trampas anteriores, los desarrolladores e investigadores idearon una serie de mejores prácticas para administrar el contexto y la memoria en sistemas de IA. Estas prácticas tienen como objetivo mantener el contexto de trabajo de la IA ágil, relevante y actualizado. Aquí hay algunas de las estrategias clave, junto con ejemplos de cómo ayudan.

RAG: Utiliza un contexto específico.

Gran parte de la RAG ya se ha cubierto en la sección anterior, así que esto sirve como un conjunto conciso de recordatorios prácticos:

• Usa la recuperación dirigida, no la carga masiva: Recupera solo los fragmentos más relevantes en lugar de insertar documentos enteros o historiales de conversación completos en el prompt.
• Trata la RAG como una recuperación de memoria justo a tiempo: Obtén el contexto solo cuando sea necesario, en lugar de traer todo en cada turno.
• Prefiere estrategias de recuperación conscientes de la relevancia: enfoques como la búsqueda semántica top-k, la fusión de rango recíproco o el filtrado de carga de herramientas ayudan a reducir el ruido y mejorar la conexión a tierra.
• Las ventanas de contexto más grandes no eliminan la necesidad de RAG: dos párrafos muy relevantes son casi siempre más efectivos que 20 páginas poco relacionadas.

Dicho esto, la RAG no se trata de agregar más contexto; se trata de agregar el contexto adecuado.

Carga de herramientas

Configuración de herramientas se trata de darle a un modelo solo las herramientas que realmente necesita para una tarea. El término proviene de los juegos: Eliges un equipo que se ajuste a la situación. Demasiadas herramientas te ralentizan; las incorrectas causan fallas. Los LLM se comportan de la misma manera, según el documento de investigación Menos es más. Una vez que pasas de unas 30 herramientas, las descripciones empiezan a solaparse y el modelo se confunde. Después de ~100 herramientas, el fracaso está casi garantizado. Esto no es un problema de ventana de contexto, es confusión de contexto.

Una solución simple y efectiva es RAG-MCP. En lugar de poner todas las herramientas en el mensaje, las descripciones de las herramientas se almacenan en una base de datos vectorial y solo se recuperan las más relevantes por solicitud. En la práctica, esto permite mantener un equipamiento reducido y específico, acorta considerablemente los tiempos de respuesta y puede mejorar hasta tres veces la precisión en la selección de herramientas.

Los modelos más pequeños alcanzan este límite incluso antes. La investigación muestra que un modelo 8B falla con docenas de herramientas, pero tiene éxito una vez que se reduce la carga. La selección dinámica de herramientas, a veces con un LLM primero, razonando sobre lo que cree que necesita, puede aumentar el rendimiento en un 44%, al tiempo que reduce el uso de poder y la latencia. La clave es que la mayoría de los agentes solo necesitan unas pocas herramientas, pero a medida que tu sistema crece, la carga de herramientas y el RAG-MCP se convierten en decisiones de diseño de primer orden.

Poda de contexto: limita la duración del historial de chat

Si una conversación se prolonga durante muchos turnos, el historial de chat acumulado puede llegar a ser demasiado grande para caber, lo que provoca un desbordamiento del contexto o distrae demasiado al modelo.

Recortar significa eliminar o acortar programáticamente las partes menos importantes del diálogo a medida que crece. Una forma simple es descartar los turnos más antiguos de la conversación cuando alcanzas un cierto límite, manteniendo solo los últimos N mensajes. Una poda más sofisticada podría eliminar digresiones irrelevantes o instrucciones previas que ya no son necesarias. El objetivo es mantener la ventana de contexto despejada de noticias antiguas.

Por ejemplo, si el agente resolvió un subproblema hace 10 turnos y hemos seguido adelante desde entonces, podríamos eliminar esa parte del historial del contexto (asumiendo que ya no será necesaria). Muchas implementaciones basadas en chat hacen esto: mantienen una ventana móvil con los mensajes recientes.

Recortar puede ser tan simple como "olvidar" las primeras partes de una conversación una vez que se han resumido o se consideran irrelevantes. De esta manera, reducimos el riesgo de errores por exceso de contexto y también reducimos la distracción del contexto, por lo que el modelo no verá contenido antiguo o fuera de tema ni se distraerá con él. Este enfoque es muy similar a cómo los humanos podrían no recordar cada palabra de una charla de una hora, pero retendrán los puntos destacados.

Si tienes dudas acerca de la poda de contexto, como lo destaca el autor Drew Breunig aquí, el uso del modelo Provence (`naver/provence-reranker-debertav3-v1`), un podador de contexto ligero (1.75 GB), eficiente y preciso para la respuesta a preguntas, puede marcar la diferencia. Puedes reducir documentos grandes a solo el texto más relevante para una búsqueda determinada. Puedes llamarlo en intervalos específicos.

Así es como invocamos el modelo `provence-reranker` en nuestro código para podar el contexto:

# Context pruning with Provence
def prune_with_provence(query: str, context: str, threshold: Optional[float] = None) -> str:
    """
    Prune context using Provence reranker model
    
    Args:
        query: User's query/question
        context: Original context to prune
        threshold: Relevance threshold (0-1) for Provence reranker.
                   If None, uses args.pruning_threshold.
                   0.1 = conservative (recommended, no performance drop)
                   0.3-0.5 = moderate to aggressive pruning
    
    Returns:
        Pruned context with only relevant sentences
    """
    if provence_model is None:
        return context
    
    if threshold is None:
        threshold = args.pruning_threshold
    
    try:
        # Use Provence's process method
        provence_output = provence_model.process(
            question=query,
            context=context,
            threshold=threshold,
            always_select_title=False,
            enable_warnings=False
        )
        
        # Extract pruned context from output
        pruned_context = provence_output.get('pruned_context', context)
        reranking_score = provence_output.get('reranking_score', 0.0)
        
        # Log statistics
        original_length = len(context)
        pruned_length = len(pruned_context)
        reduction_pct = ((original_length - pruned_length) / original_length * 100) if original_length > 0 else 0
        
        if args.verbose:
            rich.print(f"[cyan]📊 Pruning stats: {pruned_length}/{original_length} chars ({reduction_pct:.1f}% reduction, threshold={threshold:.2f}, rerank_score={reranking_score:.3f})[/cyan]")
        
        return pruned_context if pruned_context else context
        
    except Exception as e:
        rich.print(f"[yellow]⚠️ Error in Provence pruning: {str(e)}[/yellow]")
        rich.print(f"[yellow]⚠️ Falling back to original context[/yellow]")
        return context

Empleamos el modelo de reranking de Provenza (`naver/provence-reranker-debertav3-v1`) para calificar la relevancia de las oraciones. El filtrado basado en umbrales mantiene las oraciones por encima del umbral de relevancia. Además, introducimos un mecanismo de respaldo, donde volvemos al contexto original si la poda falla. Finalmente, el logging de estadísticas rastrea el porcentaje de reducción en el modo detallado.

Resumen de contexto: Condensa la información antigua en lugar de eliminarla por completo

El resumen es un complemento al recorte. Cuando la historia o la base de conocimientos se vuelve demasiado grande, puedes emplear el LLM para generar un breve resumen de los puntos importantes y usar ese resumen en lugar del contenido completo en el futuro, como realizamos en nuestro código anterior.

Por ejemplo, si un asistente de IA tuvo una conversación de 50 turnos, en lugar de enviar los 50 turnos al modelo en el turno 51 (que probablemente no encaje), el sistema podría tomar los turnos 1 a 40, hacer que el modelo los resuma en un párrafo y luego solo proporcionar ese resumen más los últimos 10 turnos en el siguiente mensaje. De esta manera, el modelo aún sabe lo que se discutió sin necesidad de conocer todos los detalles. Los primeros usuarios del chatbot lo hacían manualmente preguntando: "¿Puedes resumir lo que hablamos hasta ahora?" y luego continuaban en una nueva sesión con el resumen. Ahora se puede automatizar. El resumen no solo ahorra espacio en la ventana de contexto, sino que también puede reducir la confusión y distracción del contexto al eliminar detalles adicionales y conservar solo los hechos más importantes.

Aquí es cómo usamos los modelos de OpenAI (puedes usar cualquier LLM) para condensar el contexto a la vez que preservamos toda la información relevante, lo que elimina la redundancia y la duplicación.

# Context summarization
def summarize_context(query: str, context: str) -> str:
    """
    Summarize context using LLM to reduce duplication and focus on relevant information
    
    Args:
        query: User's query/question
        context: Context to summarize
        
    Returns:
        Summarized context
    """
    try:
        summary_prompt = f"""You are an expert at summarizing conversation context.

Your task: Analyze the provided conversation context and produce a condensed summary that fully answers or supports the user's specific question.

The summary must:
1. Preserve every fact, detail, and information that directly relates to the question
2. Eliminate redundancy and duplicate information
3. Maintain chronological flow when relevant
4. Focus on information that helps answer: "{query}"

Context to summarize:
{context}

Provide a concise summary that preserves all relevant information:"""

        summary = llm.invoke(summary_prompt).content
        
        if args.verbose:
            original_length = len(context)
            summary_length = len(summary)
            reduction_pct = ((original_length - summary_length) / original_length * 100) if original_length > 0 else 0
            rich.print(f"[cyan]📝 Summarization stats: {summary_length}/{original_length} chars ({reduction_pct:.1f}% reduction)[/cyan]")
        
        return summary
        
    except Exception as e:
        rich.print(f"[yellow]⚠️ Error in context summarization: {str(e)}[/yellow]")
        rich.print(f"[yellow]⚠️ Falling back to original context[/yellow]")
        return context

Es importante destacar que cuando se resume el contexto, es menos probable que el modelo se vea abrumado por detalles triviales o errores pasados (suponiendo que el resumen sea exacto).

Sin embargo, el resumen debe hacerse con cuidado. Un mal resumen puede omitir un detalle crucial o incluso provocar un error. Es esencialmente otro mensaje para el modelo ("resume esto"), por lo que puede alucinar o perder matices. La mejor práctica es resumir de forma incremental y quizás mantener algunos hechos canónicos sin resumir.

No obstante, ha demostrado ser muy útil. En el escenario del agente Gemini, resumir el contexto cada ~100k tokens era una forma de contrarrestar la tendencia del modelo a repetir. El resumen actúa como una memoria comprimida de la conversación o los datos. Como desarrolladores, podemos implementar esto haciendo que un agente llame periódicamente a una función de resumen (tal vez un LLM más pequeño o una rutina dedicada) en el historial de la conversación o en un documento largo. El resumen resultante reemplaza el contenido original en el prompt. Esta táctica se utiliza ampliamente para mantener los contextos dentro de unos límites y sintetizar la información.

Cuarentena de contexto: aislar los contextos cuando sea posible

Esto es más relevante en sistemas de agentes complejos o flujos de trabajo de varios pasos. La idea de la segmentación del contexto es dividir una tarea grande en tareas más pequeñas e independientes, cada una con su propio contexto, para que nunca acumules un contexto enorme que lo contenga todo. Cada subagente o subtarea trabaja en una parte del problema con un contexto enfocado, y luego un agente de nivel superior, o supervisor o coordinador integra los resultados.

La estrategia de investigación de Anthropic emplea múltiples subagentes, cada uno investigando un aspecto diferente de una pregunta, con sus propias ventanas de contexto, y un agente principal que lee los resultados destilados de esos subagentes. Este enfoque paralelo y modular significa que ninguna ventana de contexto individual se vuelve demasiado voluminosa. También reduce la posibilidad de que se mezcle información irrelevante, cada hilo se mantiene en el tema (sin confusión de contexto) y no lleva equipaje innecesario al responder su subpregunta específica. En cierto sentido, es como ejecutar hilos separados de pensamiento que solo comparten sus resultados, no todo su proceso de pensamiento.

En sistemas multiagente, este enfoque es esencial. Si el agente A se encarga de la tarea A y el agente B se encarga de la tarea B, no hay razón para que ninguno de los dos consuma todo el contexto del otro, a menos que sea realmente necesario. En cambio, los agentes pueden intercambiar solo la información necesaria. Por ejemplo, el agente A puede pasar un resumen consolidado de sus hallazgos al agente B a través de un agente supervisor, mientras que cada subagente mantiene su propio hilo de contexto dedicado. Esta configuración no requiere intervención humana; se basa en un agente supervisor con herramientas habilitadas y con un intercambio de contexto mínimo y controlado.

No obstante, diseñar tu sistema de manera que los agentes o herramientas operen con la mínima superposición de contexto necesaria puede mejorar considerablemente la claridad y el rendimiento. Piensa en ello como microservicios para IA, cada componente se ocupa de su contexto y pasa mensajes entre ellos de una manera controlada, en lugar de un contexto monolítico. Estas mejores prácticas a menudo se usan en combinación. Además, esto te da la flexibilidad de recortar historiales triviales, resumir mensajes o conversaciones antiguas importantes, transferir los registros detallados a Elasticsearch para contexto a largo plazo y usar la recuperación para recuperar cualquier cosa relevante cuando sea necesario.

Como se mencionó aquí, el principio rector es que el contexto es un recurso limitado y valioso. Quieres que cada token del prompt se gane su conservación, lo que significa que debería contribuir a la calidad de la salida. Si algo en la memoria no está cumpliendo con su función (o peor aún, está causando confusión), entonces debe ser eliminado, resumido o descartado.

Como desarrolladores, ahora podemos programar el contexto igual que programamos el código, decidiendo qué información incluir, cómo formatearla y cuándo omitirla o actualizarla. Siguiendo estas prácticas, podemos proporcionar a los agentes LLM el contexto necesario para realizar tareas sin caer en los modos de fallo descritos anteriormente. El resultado son agentes que recuerdan lo que deben, olvidan lo que no necesitan y recuperan lo que requieren justo a tiempo.

Conclusión

La memoria no es algo que añades a un agente; es algo que diseñas. La memoria a corto plazo es el bloc de notas de trabajo del agente, y la memoria a largo plazo es su almacén duradero de conocimiento. La RAG es el puente entre los dos, ya que convierte un almacén de datos pasivo, como Elasticsearch, en un mecanismo de recuperación activo que puede conectar a tierra las salidas y mantener el agente actualizado.

Pero la memoria es un arma de doble filo. En el momento en que dejas que el contexto crezca sin control, invitas al envenenamiento, la distracción, la confusión y los choques, y en los sistemas compartidos, incluso la fuga de datos. Por eso, el trabajo de memoria más importante no es "almacenar más", sino "seleccionar mejor": recuperar selectivamente, podar agresivamente, resumir cuidadosamente y evitar mezclar contextos no relacionados a menos que la tarea realmente lo demande.

En la práctica, una buena ingeniería de contexto parece un buen diseño de sistemas: contextos más pequeños y suficientes, interfaces controladas entre componentes y una clara separación entre el estado crudo y el estado destilado que realmente quieres que vea el modelo. Si se hace correctamente, no terminas con un agente que lo recuerda todo, sino con un agente que recuerda las cosas adecuadas, en el momento adecuado, por la razón correcta.

Completamos una importante actualización de infraestructura para todos los proyectos de Elastic Cloud Serverless que funcionan en AWS, al migrar a hardware más nuevo y rápido. Este cambio se ha implementado automáticamente en todos los proyectos sin servidor. Ofrece mayor rendimiento y menor latencia para proyectos serverless de Elasticsearch, Elastic Observability y Elastic Security en AWS.

Beneficios clave de rendimiento para desarrolladores

La nueva infraestructura de hardware de AWS sustenta todo lo que haces con Elastic Cloud Serverless, lo que se traduce en beneficios tangibles para la velocidad y la capacidad de respuesta de tus aplicaciones.

Latencia de consulta reducida… rendimiento aumentado.

El hardware mejorado aumenta drásticamente la velocidad de los recursos informáticos, lo que significa que tus consultas de búsqueda se procesan más rápido que nunca.

• Búsqueda y búsqueda vectorial: ya sea que estés ejecutando búsquedas de texto tradicionales o empleando una búsqueda vectorial de vanguardia para tus aplicaciones de inteligencia artificial generativa y RAG, verás una marcada disminución en la latencia. La evaluación interna mostró una disminución promedio del 35% en la latencia de búsqueda.
• Indexación más rápida: Las tasas de ingesta de datos están optimizadas, lo que te permite indexar volúmenes masivos de datos y documentos complejos con mayor rendimiento. Esto es crucial para las aplicaciones que requieren visibilidad de datos casi en tiempo real. La evaluación comparativa interna mostró un aumento promedio del 26% en el rendimiento al indexar.

Rendimiento constante bajo carga

Elastic Cloud Serverless está diseñado para escalar dinámicamente en tiempo real y satisfacer la demanda, lo que minimiza la latencia, independientemente de tu carga de trabajo. Gracias a esta actualización de hardware, ahora el escalado es más eficaz y ofrece una mayor capacidad de respuesta.

• Manejar los picos con facilidad: ya sea que te enfrentes a un aumento repentino en el tráfico de usuarios o a una ingesta masiva de datos batch, la nueva infraestructura garantiza que tus recursos de búsqueda e indexación se escalen de manera más eficiente para mantener una latencia constantemente baja.
• Desacoplamiento optimizado de computación y almacenamiento: La arquitectura serverless separa computación y almacenamiento, lo que permite que las cargas de trabajo escalen de forma independiente para lograr un rendimiento óptimo y eficiencia de costos. El hardware más rápido mejora la capa de cómputo, lo que maximiza la eficiencia de este diseño desacoplado.

Por dentro: Resultados de evaluación comparativa interna

Para cuantificar el impacto de la actualización de nuestra infraestructura de AWS, el equipo de ingeniería de Elastic llevó a cabo una exhaustiva evaluación comparativa interna con una serie de cargas de trabajo sin servidor. Estas cargas de trabajo proporcionaron evidencia empírica de mejoras de rendimiento que puedes esperar en todas tus aplicaciones, independientemente de tu caso de uso.

El enfoque comparativo

Centramos nuestras pruebas en las métricas clave que afectan directamente a la experiencia de los desarrolladores y a la capacidad de respuesta de las aplicaciones: el tiempo de respuesta (es decir, la latencia) y el rendimiento en las operaciones de búsqueda e indexación.

• Cargas de trabajo probadas: Las pruebas incluyeron operaciones de búsqueda de alta concurrencia típicas de las aplicaciones orientadas al usuario, consultas de búsqueda vectorial complejas y la ingesta/indexación de grandes volúmenes de datos para casos de uso de observabilidad y seguridad. En concreto, nuestra metodología de pruebas utilizó sets de datos disponibles públicamente para Rally, la herramienta de evaluación comparativa de Elastic.
  • wikipedia: Un conjunto de datos derivado de un snapshot del contenido textual de Wikipedia, para medir el rendimiento de la búsqueda de texto de propósito general.
  • MSMARCO-Passage-Ranking: Un conjunto de datos derivado de la comprensión de lectura automática de Microsoft (MS MARCO), para medir el rendimiento de búsqueda en campos vectoriales dispersos.
  • OpenAI_Vector: Un set de datos derivado del NQ de BEIR y enriquecido con incrustaciones generadas por el modelo text-embedding-ada-002 de OpenAI, para medir el rendimiento de búsqueda en campos vectoriales densos.
• Medición: Comparamos el rendimiento en la infraestructura antigua y nueva, al medir la latencia en el percentil 99 (P99) para capturar el peor de los casos, el rendimiento de latencia en la cola y las operaciones por segundo. Cada pista se ejecutó cinco veces para cada perfil de hardware para garantizar la consistencia en los resultados.
• El objetivo: nuestro objetivo era validar la capacidad de la infraestructura para ofrecer un rendimiento más rápido y predecible de forma constante en todos los ámbitos, incluso durante los periodos de autoescalado rápido.

Resumen de datos de rendimiento

Los resultados confirman un aumento significativo en la eficiencia y la velocidad. Estas ganancias se traducen directamente en tiempos de respuesta más bajos para tus usuarios y menores costos operativos como resultado de la capacidad de completar la misma cantidad de trabajo con menos recursos de cómputo.

Las siguientes tablas detallan las mejoras cuantitativas. Los valores más altos son mejores para el rendimiento; los valores más bajos son mejores para la latencia.

Búsqueda de resultados del índice de referencia:

Resultados de referencia de indexación:

La ventaja adicional: reducción de costos

Aunque nuestro objetivo es ofrecer un rendimiento de baja latencia, la eficiencia del nuevo hardware también tiene un impacto directo y positivo en los costos de los proyectos de Elasticsearch.

El precio de Elasticsearch Serverless se basa en el uso, lo que significa que solo pagas por los recursos de ingesta y búsqueda que consumes. Debido a que el hardware más nuevo y rápido es más eficiente, tus cargas de trabajo a menudo completarán tareas empleando menos recursos, lo que genera una reducción de costos inherente para la mayoría de los proyectos. Obtendrás un aumento de rendimiento superior sin un precio premium: la definición de eficiencia optimizada.

¿Qué significa esto para ti, el desarrollador?

Esta actualización de infraestructura está gestionada íntegramente por Elastic, así que no tienes que mover un dedo: no hay migraciones ni cambios de configuración. La mejora es inmediata y automática en todos tus proyectos serverless basados en AWS.

Esta actualización te permite:

• Crea aplicaciones más rápidas: concéntrate en la velocidad de las características, sabiendo que tu plataforma de búsqueda subyacente ofrece la velocidad que exigen tus usuarios.
• Innova con confianza: despliega nuevas características de búsqueda, observabilidad y seguridad, incluidas capacidades complejas de IA, como búsqueda vectorial y clasificación de relevancia, con la seguridad de que la Platform puede manejar la carga al máximo rendimiento.
• Simplifica tu stack: Usa un servicio totalmente gestionado que gestione la infraestructura, la planificación de la capacidad y el escalado, para que puedas centrarte en tu código y datos.
  

Nuestro objetivo era pasar a un enfoque automatizado y adaptable capaz de gestionar tanto el análisis de logs (extracción de campos) como la partición de logs (identificación de las fuentes). Planteamos la hipótesis de que los modelos de lenguaje grandes (LLMs), con su comprensión inherente de la sintaxis del código y los patrones semánticos, podrían automatizar estas tareas con una intervención humana mínima.

¡Nos complace anunciar que esta característica ya está disponible en Streams!

Descripción de los sets de datos

Elegimos un conjunto de logs Loghub para fines de prueba de concepto (POC). Para nuestra investigación, seleccionamos muestras representativas de las siguientes áreas clave:

• Sistemas distribuidos: utilizamos los sets de datos HDFS (Hadoop Distributed File System) y Spark. Estas contienen una mezcla de mensajes de información, depuración y error típicos de las plataformas de big data.
• Aplicaciones de servidor y web: los logs de los servidores web Apache y OpenSSH proporcionaron una fuente de acceso, error y eventos relevantes para la seguridad. Son fundamentales para supervisar el tráfico web y detectar posibles amenazas.
• Sistemas operativos: incluimos logs de Linux y Windows. Estos sets de datos representan los eventos comunes y semiestructurados a nivel de sistema que los equipos de operaciones encuentran a diario.
• Sistemas móviles: para asegurarnos de que nuestro modelo pueda manejar logs de entornos móviles, incluimos los sets de datos de Android. Estos logs suelen ser muy detallados y recogen una amplia gama de actividades a nivel de aplicación y de sistema en los dispositivos móviles.
• Supercomputadoras: para probar el rendimiento en entornos de computación de alto rendimiento (HPC), incorporamos el conjunto de datos BGL (Blue Gene/L), que presenta logs altamente estructurados con terminología específica de dominio.

Una ventaja clave de la colección Loghub es que los logs están en gran medida sin depurar y sin etiquetar, lo que refleja un entorno de producción en vivo ruidoso con arquitectura de microservicios.

Ejemplos de logs:

[Sun Dec 04 20:34:21 2005] [notice] jk2_init() Found child 2008 in scoreboard slot 6
[Sun Dec 04 20:34:25 2005] [notice] workerEnv.init() ok /etc/httpd/conf/workers2.properties
[Mon Dec 05 11:06:51 2005] [notice] workerEnv.init() ok /etc/httpd/conf/workers2.properties
17/06/09 20:10:58 INFO output.FileOutputCommitter: Saved output of task 'attempt_201706092018_0024_m_000083_1138' to hdfs://10.10.34.11:9000/pjhe/test/1/_temporary/0/task_201706092018_0024_m_000083
17/06/09 20:10:58 INFO mapred.SparkHadoopMapRedUtil: attempt_201706092018_0024_m_000083_1138: Committed

Además, creamos un clúster Kubernetes con una aplicación web típica y una base de datos configurada para extraer logs adicionales en el dominio más común.

Ejemplo de campos comunes de log: marca de tiempo, nivel de log (INFO, WARN, ERROR), fuente, mensaje.

Análisis de logs con pocos ejemplos con un LLM

Nuestro primer conjunto de experimentos se centró en una pregunta fundamental: ¿puede un LLM identificar de manera confiable los campos clave y generar reglas de análisis consistentes para extraerlos?

Pedimos a un modelo que analizara muestras de log sin procesar y generara reglas de análisis de log en formatos de expresión regular (regex) y Grok. Nuestros resultados demostraron que este enfoque tiene un gran potencial, pero también plantea desafíos importantes de implementación.

Alta confianza y conciencia del contexto

Los resultados iniciales fueron prometedores. El LLM demostró una gran capacidad para generar reglas de análisis sintáctico que coincidieran con los pocos ejemplos proporcionados con un alto grado de confianza. Además de la simple comparación de patrones, el modelo demostró su capacidad para comprender los logs: podía identificar y nombrar correctamente la fuente del log (por ejemplo, la aplicación de seguimiento de salud, la aplicación web Nginx, la base de datos Mongo).

El dilema "Goldilocks" de las muestras de entrada

Nuestros experimentos revelaron rápidamente una falta significativa de solidez debido a la extrema sensibilidad a la muestra de entrada. El rendimiento del modelo fluctúa drásticamente en función de los ejemplos específicos de logs que se incluyan en el prompt. Observamos un problema similar de log en el que la muestra debe incluir logs lo suficientemente diversos :

• Demasiado homogéneo (sobreajuste): si los registros de entrada son demasiado similares, el LLM tiende a sobreespecificar. Trata datos variables (como nombres de clases Java específicas en un seguimiento de pila) como partes estáticas de la plantilla. Esto genera reglas frágiles que cubren una proporción pequeña de logs y extraen campos inutilizables.
• Demasiado heterogéneo (confusión): por el contrario, si la muestra contiene una variación significativa de formato, o peor aún, "trash logs" como barras de progreso, tablas de memoria o arte ASCII, el modelo tendrá dificultades para encontrar un denominador común. Suele recurrir a generar regexes complejos y rotos o a generalizar descuidadamente toda la línea en un solo campo de mensajes.

La restricción de la ventana de contexto

También encontramos un cuello de botella en la ventana de contexto. Cuando los logs de entrada eran largos, heterogéneos o ricos en campos extraíbles, la salida del modelo solía deteriorarse, y se "desordenaba" o era demasiado larga para caber en la ventana de contexto de salida. Naturalmente, la fragmentación (chunking) ayuda en este caso. Al dividir los logs mediante delimitadores basados en caracteres y entidades, podríamos ayudar al modelo a centrarse en extraer los campos principales sin sentirse abrumado por el ruido.

La brecha de consistencia y estandarización

Incluso cuando el modelo genera reglas correctamente, notamos ligeras inconsistencias:

• Variaciones en la denominación de servicios: el modelo propone diferentes nombres para la misma entidad (por ejemplo, etiquetar la fuente como "Spark", "Apache Spark" y "Spark Log Analytics" en diferentes ejecuciones).
• Variaciones en los nombres de los campos: los nombres de los campos carecían de estandarización (p. ej.: id vs. service.id vs. device.id). Normalizamos los nombres al utilizar una nomenclatura de campos de Elastic estandarizada.
• Variación de la resolución: la resolución de la extracción de campos variaba en función del grado de similitud entre los logs de entrada.

Huella digital en formato de log

Para abordar el reto de la similitud de logs, presentamos una heurística de alto rendimiento: la huella digital en formato de log (LFF).

En lugar de alimentar logs crudos y ruidosos directamente a un LLM, primero aplicamos una transformación determinista para revelar la estructura subyacente de cada mensaje. Este paso de preprocesamiento abstrae los datos de las variables y genera una "huella digital" simplificada que nos permite agrupar logs relacionados.

La lógica de mapping es sencilla para garantizar la velocidad y la consistencia:

1. Abstracción de dígitos: cualquier secuencia de dígitos (0-9) se reemplaza por un solo "0".
2. Abstracción de texto: cualquier secuencia de caracteres alfabéticos con espacios en blanco se reemplaza por una sola "a".
3. Normalización de espacios en blanco: todas las secuencias de espacios en blanco (espacios, tabulaciones, saltos de línea) se colapsan en un solo espacio.
4. Conservación de símbolos: se conservan los signos de puntuación y los caracteres especiales (por ejemplo: :, [, ], /), ya que suelen ser los indicadores más claros de la estructura del log.

Presentamos el enfoque de mapping de logs. Los patrones básicos de mapping incluyen lo siguiente:

• Dígitos de 0-9 de cualquier longitud -> a "0".
• Texto (caracteres alfabéticos con espacios) de cualquier longitud -> a "a".
• Espacios en blanco, tabulaciones y líneas nuevas -> a un solo espacio.

Veamos un ejemplo de cómo este mapping nos permite transformar los logs.

Como resultado, obtenemos las siguientes máscaras de log:

Mira las huellas dactilares de los dos primeros logs. A pesar de las diferentes marcas de tiempo, clases de origen y contenido de mensajes, sus prefijos (0/0/0 0:0:0 a a.a:) son idénticos. Esta alineación estructural nos permite agrupar automáticamente estos logs en el mismo clúster.

Sin embargo, el tercer log produce una huella digital completamente divergente (0-0-0...). Esto nos permite separarlo algorítmicamente del primer grupo antes de que invoquemos un LLM.

Parte adicional: Implementación instantánea con ES|QL

Es tan fácil como ingresar esta búsqueda en Discover.

FROM loghub |
EVAL pattern = REPLACE(REPLACE(REPLACE(REPLACE(raw_message, "[ \t\n]+", " "), "[A-Za-z]+", "a"), "[0-9]+", "0"), "a( a)+", "a") |
STATS total_count = COUNT(), ratio = COUNT() / 2000.0, datasources=VALUES(filename), example=TOP(raw_message, 3, "desc") BY SUBSTRING(pattern, 0, 15) |
SORT total_count DESC |
LIMIT 100

Desglose de la búsqueda:

DE loghub: Se dirige a nuestro índice que contiene los datos de log sin procesar.

EVAL pattern = …: La lógica de mapping del núcleo. Encadenamos las funciones REPLACE para realizar la abstracción (por ejemplo, dígitos a '0', texto a 'a', etc.) y guardamos el resultado en un campo de “patrón”.

STATS[columna1 =] expresión1, … POR SUBSTRING(patrón, 0, 15):

Este es un paso de agrupación. Agrupamos logs que comparten los primeros 15 caracteres de su patrón y creamos campos agregados como recuento total de logs por grupo, lista de fuentes de datos de log, prefijo de patrón, 3 ejemplos de log

SORT total_count DESC | LIMIT 100: Destaca los 100 patrones log más frecuentes

A continuación, se muestran los resultados de la búsqueda en LogHub:

Como aparece en la visualización, este enfoque “sin LLM” particiona los logs con alta precisión. Agrupó con éxito 10 de las 16 fuentes de datos (basadas en etiquetas de LogHub) por completo (>90 %) y logró un agrupamiento mayoritario en 13 de 16 fuentes (>60 %), todo ello sin necesidad de realizar una limpieza, preprocesamiento o ajustes finos adicionales.

El formato de huella de log ofrece una alternativa pragmática y de alto impacto, además de soluciones sofisticadas de ML como el Análisis de patrones de log. Aporta información inmediata sobre las relaciones entre los log y gestiona de forma eficaz grandes grupos de logs.

• Versatilidad como primitiva

Gracias a la implementación de ES|QL, LFF sirve como una herramienta independiente para diagnósticos y visualizaciones de datos rápidos y como un componente básico en los pipelines de análisis de registros para casos de uso de gran volumen.

• Flexibilidad

LFF es fácil de personalizar y ampliar para capturar patrones específicos, es decir, números hexadecimales y direcciones IP.

• Estabilidad determinista

A diferencia de los algoritmos de agrupamiento basados en ML, la lógica LFF es sencilla y determinista. Los nuevos logs entrantes no afectan retroactivamente a los grupos de logs existentes.

• Rendimiento y mMemory

Requiere memoria mínima, sin entrenamiento ni GPU, lo que lo hace ideal para entornos de alto rendimiento en tiempo real.

Combinación de la huella digital del formato de log con un LLM

Para validar la arquitectura híbrida propuesta, cada experimento contenía un subconjunto aleatorio del 20 % de los logs de cada fuente de datos. Esta restricción simula un entorno de producción real donde los logs se procesan en lotes en lugar de como un vertido histórico monolítico.

El objetivo era demostrar que el LFF actúa como una capa de compresión eficaz. Nuestro objetivo fue demostrar que las reglas de análisis de alta cobertura podrían generarse a partir de muestras pequeñas y seleccionadas, y generalizarse con éxito a todo el set de datos.

Pipeline de ejecución

Implementamos un pipeline de varias etapas que filtra, agrupa y aplica un muestreo estratificado a los datos antes de que lleguen al LLM.

1. Agrupamiento jerárquico en dos etapas

• Subclases (coincidencia exacta): los logs se agregan por huellas idénticas. Cada log en una subclase comparte exactamente la misma estructura de formato.
• Limpieza de valores atípicos. Descartamos cualquier subclase que represente menos del 5 % del volumen total del log. Esto asegura que el LLM se centre en la señal dominante y no se desvíe por ruido o logs mal formados.
• Metaclases (coincidencia de prefijo): las subclases restantes se agrupan en metaclases por los primeros caracteres N del formato de coincidencia de huellas dactilares. Esta estrategia de agrupación divide efectivamente formatos léxicamente similares bajo un mismo paraguas. Elegimos N=5 para el análisis de log y N=15 para la partición de log cuando las fuentes de datos son desconocidas.

2. Muestreo estratificado. Una vez construido el árbol jerárquico, construimos la muestra de log para el LLM. El objetivo estratégico es maximizar la cobertura de las variaciones y minimizar el uso de tokens.

• Seleccionamos logs representativos de cada subclase válida dentro de la metaclase más amplia.
• Para gestionar un caso extremo de demasiadas subclases, aplicamos un muestreo aleatorio reducido para ajustarse al tamaño de la ventana objetivo.

3. Generación de reglas. Finalmente, le pedimos al LLM que genere una regla de análisis de regex que se ajuste a todos los logs de la muestra proporcionada para cada metaclase. Para nuestra prueba de concepto, utilizamos el modelo GPT-4o mini.

Resultados experimentales y observaciones

Logramos una precisión de análisis del 94 % y una precisión de partición del 91 % en los sets de datos de Loghub.

La matriz de confusión anterior ilustra los resultados de la partición de logs. El eje vertical representa las fuentes de datos reales, y el eje horizontal representa las fuentes de datos previstas. La intensidad del mapa de calor corresponde al volumen de logs, con mosaicos más ligeros que indican un recuento más alto. La alineación diagonal demuestra la alta fidelidad del modelo en la atribución de fuentes, con una dispersión mínima.

Nuestra información sobre los parámetros de rendimiento:

• Línea de base óptima: una ventana de contexto de 30–40 muestras de log por categoría demostró ser el "punto óptimo", que produce consistentemente un análisis robusto con patrones tanto de Regex como de Grok.
• Minimización de entrada: pusimos el tamaño de entrada a 10 logs por categoría para los patrones Regex y observamos solo una caída del 2 % en el rendimiento de análisis, lo que confirma que el muestreo basado en la diversidad es más crítico que el volumen bruto.

Los modelos de Jina se dividen en tres amplias categorías diseñadas para apoyar el procesamiento, la organización y la recuperación de información:

• Modelos de incrustación semántica
• Modelos de reordenamiento
• Pequeños modelos de lenguaje generativo

Modelos de incrustación semántica

La idea detrás de las incrustaciones semánticas es que un modelo de IA puede aprender a representar aspectos del significado de sus entradas en términos de la geometría de espacios de alta dimensión.

Puedes pensar en una incrustación semántica como un punto (técnicamente un vector) en un espacio de alta dimensión. Un modelo de incrustación es una red neuronal que toma algunos datos digitales como entrada (potencialmente cualquier cosa, pero con mayor frecuencia un texto o una imagen) y genera la ubicación de un punto de alta dimensión correspondiente como un conjunto de coordenadas numéricas. Si el modelo funciona bien, la distancia entre dos incrustaciones semánticas es proporcional a la medida en que sus objetos digitales correspondientes significan lo mismo.

Para entender cómo esto es importante para las aplicaciones de búsqueda, imagina una incrustación para la palabra “perro” y una para la palabra “gato” como puntos en el espacio:

Un buen modelo de incrustación debe generar una para la palabra “felino” que esté mucho más cerca de “gato” que de “perro”, y “canino” debe tener una incrustación mucho más cercana a “perro” que de “gato”, porque esas palabras significan casi lo mismo:

Si un modelo es multilingüe, esperaríamos lo mismo para las traducciones de “gato” y “perro”:

Los modelos de incrustación traducen la similitud o diferencia en el significado entre las cosas en relaciones espaciales entre incrustaciones. Las imágenes anteriores solo tienen dos dimensiones para que puedas verlas en una pantalla, pero los modelos de incrustación producen vectores con docenas o miles de dimensiones. Esto les permite codificar sutilezas de significado para textos completos y asignar un punto en un espacio que tenga cientos o miles de dimensiones para documentos de miles de palabras o más.

Incrustaciones multimodales

Los modelos multimodales amplían el concepto de incrustaciones semánticas a otros elementos, además de los textos, especialmente a las imágenes. Esperaríamos que una incrustación para una imagen esté cerca de una incrustación de una descripción fiel de la imagen:

Las incrustaciones semánticas tienen muchos usos. Entre otras cosas, puedes utilizarlos para crear clasificadores eficientes, agrupar datos y llevar a cabo una variedad de tareas, como la deduplicación de datos y la investigación de la diversidad de datos, ambas importantes para aplicaciones de big data que implican trabajar con demasiados datos para gestionarlos manualmente.

El mayor uso directo de las incrustaciones es en la recuperación de información. Elasticsearch puede almacenar objetos de recuperación con incrustaciones como claves. Las consultas se convierten en vectores de incrustación y una búsqueda devuelve los objetos almacenados cuyas claves son las más cercanas a la incrustación de la consulta.

Donde la recuperación tradicional basada en vectores (a veces llamada recuperación de vectores dispersos) utiliza vectores basados en palabras o metadatos en documentos y búsquedas, la recuperación basada en incrustaciones (también conocida como recuperación de vectores densos) utiliza significados evaluados por la IA en lugar de palabras. Esto los hace, en general, mucho más flexibles y precisos que los métodos de búsqueda tradicionales.

Aprendizaje de representación de Matryoshka

El número de dimensiones que tiene una incrustación y la precisión de los números que contiene tienen un impacto significativo en el rendimiento. Los espacios de muy alta dimensión y los números extremadamente de alta precisión pueden representar información muy detallada y compleja, pero exigen modelos de IA más grandes que sean más caros de entrenar y de ejecutar. Los vectores que generan requieren más espacio de almacenamiento y se necesitan más ciclos de computación para calcular las distancias entre ellos. El uso de modelos de incrustación semántica implica hacer compensaciones importantes entre la precisión y el consumo de recursos.

Para maximizar la flexibilidad para los usuarios, los modelos de Jina se entrenan con una técnica llamada Aprendizaje de representación de Matryoshka. Esto hace que los modelos carguen las distinciones semánticas más importantes en las primeras dimensiones del vector de incrustación para que simplemente puedas cortar las dimensiones superiores y aún obtener un buen rendimiento.

En la práctica, esto significa que los usuarios de los modelos de Jina pueden elegir cuántas dimensiones desean que tengan sus incrustaciones. Elegir menos dimensiones reduce la precisión, pero la degradación en el rendimiento es menor. En la mayoría de las tareas, las métricas de rendimiento de los modelos de Jina disminuyen entre un 1 % y un 2 % cada vez que reduces el tamaño de la incrustación en un 50 %, hasta aproximadamente una reducción del 95 % en el tamaño.

Recuperación asimétrica

La similitud semántica usualmente se mide de manera simétrica. El valor que obtienes al comparar “gato” con “perro” es el mismo que el valor que obtendrías al comparar “perro” con “gato”. Pero cuando usas incrustaciones para la recuperación de información, funcionan mejor si rompes la simetría y codificas las búsquedas de manera diferente a como codificas los objetos de recuperación.

Esto se debe a la forma en que entrenamos los modelos de incrustación. Los datos de entrenamiento contienen ejemplos de los mismos elementos, como palabras, en muchos contextos diferentes, y los modelos aprenden semántica al comparar las similitudes y diferencias contextuales entre los elementos.

Entonces, por ejemplo, podríamos encontrar que la palabra “animal” no aparece en muchos de los mismos contextos que “gato” o “perro”, y por lo tanto, la incrustación para “animal” podría no estar particularmente cerca de “gato” o “perro”:

Esto hace que sea menos probable que una búsqueda de "animal" recupere documentos sobre gatos y perros, lo cual es lo opuesto a nuestro objetivo. Así que, en su lugar, codificamos "animal" de forma diferente cuando es una consulta que cuando es un objetivo para la recuperación:

La recuperación asimétrica significa usar un modelo diferente para las búsquedas o entrenar especialmente un modelo de incrustación para codificar cosas de una manera cuando se almacenan para su recuperación y para codificar consultas de otra manera.

Incrustaciones multivectoriales

Las incrustaciones únicas son buenas para la recuperación de información porque se ajustan al marco de trabajo básico de una base de datos indexada: almacenamos objetos para su recuperación con un único vector de incrustación como clave de recuperación. Cuando los usuarios consultan el almacén de documentos, sus búsquedas se traducen en vectores de incrustación y los documentos cuyas claves están más cercanas a la incrustación de búsquedas (en el espacio de incrustación de alta dimensión) se recuperan como posibles coincidencias.

Las incrustaciones multivectoriales funcionan un poco diferente. En lugar de generar un vector de longitud fija para representar una búsqueda y un objeto almacenado completo, producen una secuencia de incrustaciones que representan partes más pequeñas de ellos. Las partes suelen ser tokens o palabras para textos y son mosaicos de imagen para datos visuales. Estas incrustaciones reflejan el significado de la parte en su contexto.

Por ejemplo, considera estas oraciones:

• Ella tenía un corazón de oro.
• Ella cambió de opinión con el corazón.
• Ella tuvo un ataque al corazón.

Superficialmente, se ven muy similares, pero un modelo multivectorial probablemente generaría incrustaciones muy diferentes para cada instancia de "corazón", representando cómo cada una significa algo diferente en el contexto de la oración completa:

La comparación de dos objetos a través de sus incrustaciones multivectoriales a menudo implica medir su distancia de chaflán: comparar cada parte de una incrustación multivectorial con cada parte de otra y sumar las distancias mínimas entre ellas. Otros sistemas, incluidos los Jina Rerankers que se describen a continuación, los incluyen en un modelo de IA entrenado específicamente para evaluar su similitud. Ambos enfoques suelen tener mayor precisión que la simple comparación de incrustaciones de un solo vector, ya que las incrustaciones multivectoriales contienen información mucho más detallada que las de un solo vector.

Sin embargo, las incrustaciones multivectoriales no son adecuadas para indexar. A menudo se utilizan en tareas de reclasificación, como se describe para el modelo de jina-colbert-v2 en la siguiente sección.

Modelos de incrustación de Jina

Jina embeddings v4

jina-embeddings-v4 es un modelo de incrustación multilingüe y multimodal de 3.8 mil millones (3.8×10⁹) de parámetros que admite imágenes y textos en una variedad de idiomas ampliamente utilizados. Utiliza una arquitectura novedosa para aprovechar el conocimiento visual y el conocimiento del lenguaje para mejorar el rendimiento en ambas tareas, lo que le permite sobresalir en la recuperación de imágenes y especialmente en la recuperación visual de documentos. Esto significa que maneja imágenes como gráficos, diapositivas, mapas, capturas de pantalla, escaneos de páginas y diagramas, tipos comunes de imágenes que a menudo contienen texto importante incrustado y que quedan fuera del alcance de los modelos de visión artificial entrenados con imágenes de escenas del mundo real.

Hemos optimizado este modelo para varias tareas diferentes a través de adaptadores de Low-Rank Adaptation (LoRA) compactos. Esto nos permite entrenar un único modelo para que se especialice en varias tareas, sin comprometer el rendimiento en ninguna de ellas, con un costo adicional mínimo en memoria o procesamiento.

Las características principales incluyen las siguientes:

• Rendimiento de vanguardia en la recuperación visual de documentos, junto con texto multilingüe e imágenes regulares que superan significativamente a modelos mucho más grandes.
• El soporte para un gran tamaño de contexto de entrada: 32.768 tokens equivale aproximadamente a 80 páginas de texto en inglés a doble espacio, y 20 megapíxeles equivalen a una imagen de 4.500 x 4.500 píxeles.
• Tamaños de incrustación seleccionados por el usuario, desde un máximo de 2048 dimensiones hasta 128 dimensiones. Descubrimos empíricamente que el rendimiento se degrada significativamente por debajo de ese umbral.
• Soporte para ambas incrustaciones simples y multivector. En el caso de los textos, la salida multivectorial consiste en una incrustación de 128 dimensiones para cada token de entrada. Para las imágenes, produce una incrustación de 128 dimensiones para cada mosaico de 28x28 píxeles necesario para cubrir la imagen.
• Optimización para la recuperación asimétrica mediante un par de adaptadores LoRA entrenados específicamente para tal fin.
• Un adaptador LoRA optimizado para el cálculo de similitud semántica.
• Soporte especial para lenguajes de programación informática y marcos de trabajo de TI, también a través de un adaptador LoRA.

Desarrollamos jina-embeddings-v4 para servir como una herramienta general y multipropósito para una amplia variedad de tareas de búsqueda común, comprensión del lenguaje natural y análisis de IA. Es un modelo relativamente pequeño teniendo en cuenta sus capacidades, pero su despliegue requiere recursos considerables y es más adecuado para su uso a través de una API en la nube o en un entorno de gran volumen.

Jina embeddings v3

jina-embeddings-v3 es un modelo de incrustación compacto, de alto rendimiento, multilingüe y solo de texto con menos de 600 millones de parámetros. Admite hasta 8192 tokens de entrada de texto y genera incrustaciones de vector único con tamaños elegidos por el usuario, desde un valor predeterminado de 1024 dimensiones hasta 64.

Capacitamos a jina-embeddings-v3 para una variedad de tareas de texto. No solo para la recuperación de información y la similitud semántica, sino también para tareas de clasificación, como análisis de sentimiento y moderación de contenido, así como tareas de agrupar, como agregación de noticias y recomendaciones. Al igual que jina-embeddings-v4, este modelo proporciona adaptadores LoRA especializados para las siguientes categorías de uso:

• Recuperación asimétrica
• Similitud semántica
• Clasificación
• Agrupación

jina-embeddings-v3 es un modelo mucho más pequeño que jina-embeddings-v4 con un tamaño de contexto de entrada significativamente reducido, pero su funcionamiento cuesta menos. No obstante, tiene un rendimiento muy competitivo, aunque solo para textos, y es una mejor opción para muchos casos de uso.

Inmercaciones del código Jina

Los modelos especializados de incrustación de código de Jina, jina-code-embeddings (0.5b y 1.5b), admiten 15 esquemas y marcos de trabajo de programación, así como textos en inglés relacionados con la informática y la tecnología de la información. Son modelos compactos con quinientos millones (0.5x10⁹) y mil quinientos millones (1.5x10⁹) de parámetros, respectivamente. Ambos modelos admiten tamaños de contexto de entrada de hasta 32.768 tokens y permiten a los usuarios seleccionar los tamaños de su incrustación de salida, desde 896 hasta 64 dimensiones para el modelo más pequeño y 1536 hasta 128 para el modelo más grande.

Estos modelos admiten la recuperación asimétrica para cinco especializaciones específicas de tareas, mediante el ajuste de prefijos en lugar de adaptadores LoRA:

• Código a código. Recupera un código similar en todos los lenguajes de programación. Esto se utiliza para la alineación de códigos, deduplicación de códigos y soporte para la traslación y refactorización.
• Lenguaje natural para programar. Recupera códigos para hacer coincidir consultas, comentarios, descripciones y documentación en lenguaje natural.
• Código a lenguaje natural. Haz coincidir el código con la documentación u otros textos en lenguaje natural.
• Finalización de código a código. Sugiere un código relevante para completar o mejorar el código existente.
• Preguntas y respuestas técnicas. Identifica las respuestas en lenguaje natural a las preguntas sobre tecnologías de la información, que son ideales para casos de uso de soporte técnico.

Estos modelos ofrecen un rendimiento superior para tareas relacionadas con documentación informática y materiales de programación con un costo computacional relativamente bajo. Son muy adecuados para integrarse en entornos de desarrollo y asistentes de código.

Jina ColBERT v2

jina-colbert-v2 es un modelo de incrustación de texto multivectorial de 560 millones de parámetros. Es multilingüe, entrenado con materiales en 89 idiomas, y soporta tamaños de incrustación variables y recuperación asimétrica.

Como se ha señalado anteriormente, las incrustaciones multivectoriales no son adecuadas para la indexación, pero resultan muy útiles para aumentar la precisión de los resultados de otras estrategias de búsqueda. Mediante jina-colbert-v2, puedes calcular incrustaciones multivector de antemano y luego usarlas para reclasificar candidatos de recuperación al momento de la búsqueda. Este enfoque es menos preciso que usar uno de los modelos de reclasificación en la siguiente sección, pero es mucho más eficiente porque simplemente implica comparar incrustaciones multivectoriales almacenadas en lugar de invocar todo el modelo de IA para cada búsqueda y coincidencia posible. Es ideal para casos de uso en los que la latencia y la sobrecarga computacional que supone el uso de modelos de reclasificación son demasiado grandes, o cuando el número de candidatos que comparar es demasiado elevado para los modelos de reclasificación.

Este modelo genera una secuencia de incrustaciones, una por token de entrada, y los usuarios pueden seleccionar incrustaciones de token de 128, 96 o 64 dimensiones. Las coincidencias de texto de candidatos están limitadas a 8,192 tokens. Las búsquedas se codifican de manera asimétrica, por lo que los usuarios deben especificar si un texto es una búsqueda o una coincidencia candidata y deben limitar las búsquedas a 32 tokens.

Jina CLIP v2

Jina-Clip-V2 es un modelo de incrustación multimodal de 900 millones de parámetros, y está capacitado para que los textos e imágenes produzcan incrustaciones muy cercanas si el texto describe el contenido de la imagen. Su uso principal es para recuperar imágenes basadas en consultas de textura, pero también es un modelo de solo texto de alto rendimiento, lo que reduce los costos de usuario porque no necesitas modelos separados para la recuperación de texto a texto y de texto a imagen.

Este modelo admite un contexto de entrada de texto de 8,192 tokens, y las imágenes se escalan a 512x512 píxeles antes de generar incrustaciones.

Las arquitecturas de preentrenamiento de lenguaje-imagen contrastivo (CLIP) son fáciles de entrenar y operar y pueden producir modelos muy compactos, pero tienen algunas limitaciones fundamentales. No pueden utilizar los conocimientos adquiridos en un medio para mejorar su rendimiento en otro. No pueden usar un medio para mejorar su rendimiento en otro. Así que, aunque pueda saber que las palabras "perro" y "gato" están más cercanas en significado que a "auto", no necesariamente sabrá que una foto de un perro y una de un gato están más relacionadas que cualquiera de las dos con una foto de un auto.

También sufren de lo que se llama la brecha de modalidad: es probable que una incrustación de un texto sobre perros esté más cerca de una incrustación de un texto sobre gatos que de una incrustación de una imagen de perros. Debido a esta limitación, te recomendamos utilizar CLIP como modelo de recuperación de texto a imagen o como modelo de solo texto, pero sin mezclar los dos en una sola búsqueda.

Modelos de reordenamiento

Los modelos de reclasificación toman una o más coincidencias candidatas, junto con una consulta como entrada al modelo, y las comparan directamente, produciendo coincidencias de mucha mayor precisión.

En principio, podrías usar un reranker directamente para la recuperación de información al comparar cada búsqueda con cada documento almacenado, pero esto sería muy costoso desde el punto de vista computacional y no es práctico para cualquier colección excepto para las más pequeñas. Como resultado, los rerankers tienden a usarse para evaluar listas relativamente cortas de coincidencias de candidatos encontradas por otros medios, como la búsqueda basada en incrustaciones u otros algoritmos de recuperación. Los modelos de reclasificación son ideales para esquemas de búsqueda híbridos y federados, donde realizar una búsqueda puede significar que las consultas se envían a sistemas de búsqueda separadas con conjuntos de datos distintos, cada una devolviendo resultados distintos. Funcionan muy bien al combinar resultados diversos en un único resultado de alta calidad.

La búsqueda basada en incrustaciones puede ser un gran compromiso, ya que implica reindexar todos tus datos almacenados y cambiar las expectativas del usuario sobre los resultados. Agregar un reranker a un esquema de búsqueda existente puede sumar muchos de los beneficios de la IA sin necesidad de rediseñar toda tu solución de búsqueda.

Modelos de reordenación de Jina

Jina Reranker m0

jina-reranker-m0 es un reranker multimodal de 2.4 mil millones (2.4x10⁹) de parámetros que admite consultas textuales y coincidencias candidatas que consisten en textos y/o imágenes. Es el modelo líder en recuperación visual de documentos, lo que lo convierte en una solución ideal para almacenar archivos PDF, escaneos de texto, capturas de pantalla y otras imágenes generadas o modificadas por computadora que contengan texto u otra información semiestructurada, así como datos mixtos que consistan en documentos de texto e imágenes.

Este modelo toma una búsqueda única y una coincidencia candidata y devuelve una puntuación. Cuando la misma consulta se usa con diferentes candidatos, las puntuaciones son comparables y pueden usarse para clasificarlas. Soporta un tamaño total de entrada de hasta 10 240 tokens, incluido el texto de la consulta y el texto o imagen candidata. Cada mosaico de 28x28 píxeles necesario para cubrir una imagen cuenta como un token para calcular el tamaño de entrada.

Jina Reranker v3

jina-reranker-v3 es un reranker de texto de 600 millones de parámetros con rendimiento de vanguardia para modelos de tamaño comparable. A diferencia de jina-reranker-m0, toma una sola búsqueda y una lista de hasta 64 candidatos coincidentes y devuelve el orden de clasificación. Tiene un contexto de entrada de 131 000 tokens, incluida la consulta y todos los candidatos de texto.

Jina Reranker v2

jina-reranker-v2-base-multilingual es un reranker muy compacto y de uso general con características adicionales diseñadas para admitir llamadas a funciones y consultas SQL. Con un peso inferior a 300 millones de parámetros, proporciona una reclasificación de texto multilingüe rápido, eficiente y preciso, con soporte adicional para seleccionar tablas SQL y funciones externas que coincidan con consultas de texto, lo que lo hace adecuado para casos de uso de agentes.

Pequeños modelos de lenguaje generativo

Los modelos de lenguaje generativo son modelos como ChatGPT de OpenAI, Google Gemini y Claude de Anthropic que toman entradas de texto o multimedia y responden con salidas de texto. No existe una línea bien definida que separe los modelos de lenguaje grandes (LLM) de los modelos de lenguaje pequeños (SLM), pero los problemas prácticos de desarrollar, operar y utilizar LLM de primera línea son bien conocidos. Los más conocidos no se distribuyen públicamente, por lo que solo podemos estimar su tamaño, pero se espera que ChatGPT, Gemini y Claude estén en el rango de parámetros de 1 a 3 billones (1–3x10¹²).

Ejecutar estos modelos, incluso si están disponibles públicamente, está muy lejos del alcance del hardware convencional, que requiere los chips más avanzados dispuestos en grandes matrices paralelas. Puedes acceder a LLMs a través de API pagas, pero esto conlleva costos significativos, tiene una gran latencia y es difícil de alinear con las demandas de protección de datos, la soberanía digital y la repatriación en la nube. Además, los costos relacionados con la capacitación y la personalización de modelos de ese tamaño pueden ser considerables.

En consecuencia, se han realizado numerosas investigaciones para desarrollar modelos más pequeños que, aunque carecen de todas las capacidades de los LLM más grandes, pueden realizar determinados tipos de tareas con la misma eficacia y a un menor costo. Las empresas generalmente despliegan software para abordar problemas específicos, y el software de IA no es diferente, por lo que las soluciones basadas en SLM se suelen preferir a las de LLM. Por lo general, pueden ejecutarse en hardware básico, son más rápidos y consumen menos energía para ejecutarse, y son mucho más fáciles de personalizar.

Las ofertas de SLM de Jina están creciendo a medida que nos enfocamos en la mejor manera de llevar la IA a soluciones de búsqueda prácticas.

Jina SLM

ReaderLM v2

ReaderLM-v2 es un modelo de lenguaje generativo que convierte HTML en Markdown o JSON, según los esquemas JSON proporcionados por el usuario y las instrucciones en lenguaje natural.

El preprocesamiento y la normalización de datos son una parte esencial del desarrollo de buenas soluciones de búsqueda para datos digitales, pero los datos del mundo real, especialmente la información derivada de la web, suelen ser caóticos, y las estrategias de conversión simples a menudo resultan ser muy frágiles. En cambio, ReaderLM-v2 ofrece una solución de modelo de IA inteligente que puede entender el caos de un volcado de árbol DOM de una página web e identificar de manera segura elementos útiles.

Con 1500 millones (1,5 x 10⁹) de parámetros, es tres órdenes de magnitud más compacto que los LLM de última generación, pero su rendimiento es similar al de estos en esta tarea específica.

Jina VLM

jina-vlm es un modelo de lenguaje generativo con 2400 millones (2,4 x 10⁹) de parámetros que está entrenado para responder preguntas en lenguaje natural sobre imágenes. Tiene un fuerte soporte para el análisis visual de documentos, es decir, responder preguntas sobre escaneos, capturas de pantalla, diapositivas, diagramas y datos similares de imágenes no naturales.

Por ejemplo:

También es muy bueno para leer texto en imágenes:

Pero donde jina-vlm realmente se destaca es en entender el contenido de las imágenes informativas y creadas por el hombre:

O:

jina-vlm es adecuado para la generación automática de subtítulos, descripciones de productos, texto alternativo de imágenes y aplicaciones de accesibilidad para personas con discapacidad visual. También crea posibilidades para que los sistemas de generación aumentada por recuperación (RAG) utilicen información visual y para que los agentes de IA procesen imágenes sin ayuda humana.

Elastic Agent Builder facilita la creación de agentes de IA conectados a datos. Te mostraremos cómo hacerlo en esta publicación de blog. Veamos todos los pasos necesarios para crear un agente con una herramienta MCP que acceda a los datos almacenados en Elastic. Luego usaremos el SDK de Strands Agents y sus capacidades Agent2Agent (A2A) para operar el agente. El SDK de Strands Agents es una plataforma de desarrollo de IA multiagente que puedes usar para crear apps de agentes con el código justo para asegurarte de obtener el resultado que quieres.

Construyamos un agente de IA que juegue el juego de RPS+, que es una versión del clásico juego de "Piedra, papel o tijeras" con un toque adicional; les da a los jugadores del juego un par de opciones adicionales.

Requisitos previos

Aquí está lo que se requiere para seguir los pasos en esta publicación de blog:

• Un editor de texto ejecutándose en tu computadora local
  • Visual Studio Code es lo que usaremos para las instrucciones de ejemplo en esta publicación de blog
• Python 3.10 o superior funcionando en tu computadora local

Crea un proyecto Serverless

Lo primero que necesitamos es un proyecto Elasticsearch Serverless, que incluye Elastic Agent Builder.

Ve a cloud.elastic.co y crea un nuevo proyecto de Elasticsearch Serverless.

Crea un índice y agrega datos

A continuación, vamos a agregar algunos datos a nuestro proyecto de Elasticsearch. Abre Developer Tools, donde podemos ejecutar comandos para crear un nuevo índice e insertar algunos datos en él. Selecciona Herramientas para desarrolladores en el menú de navegación de nivel superior.

Copia y pega el siguiente comando PUT en el área de entrada de solicitud de la consola de Developer Tools. Esta declaración crea un índice de Elasticsearch llamado “game-docs”.

PUT /game-docs
{
  "mappings": {
    "properties": {
      "title": { "type": "text" },
      "content": { 
        "type": "text"
      },
      "filename": { "type": "keyword" },
      "last_modified": { "type": "date" }
    }
  }
}

Haz clic en el botón Enviar solicitud que aparece en el lado derecho de la declaración en Herramientas para desarrolladores. Deberías ver una notificación que confirme que el índice game-docs se creó en el área de respuesta de Herramientas para desarrolladores.

Un índice llamado game-docs es el lugar ideal para almacenar los datos del juego que estamos creando. Pongamos un documento llamado rps+-md en este índice que contiene todos los datos que requiere nuestro juego. Copia y pega el siguiente comando PUT en la consola de Herramientas para desarrolladores.

PUT /game-docs/_doc/rps+-md
{
  "title": "Rock Paper Scissors +",
  "content": "
# Game Name
RPS+

# Starting Prompt
Let's play RPS+ !
---
What do you choose?

# Game Objects
1. Rock 🪨 👊
2. Paper 📜 🖐
3. Scissors ✄ ✌️
4. Light ☼ 👍
5. Dark Energy ☄ 🫱

# Judgement of Victory
* Rock beats Scissors
  * because rocks break scissors
* Paper beats Rock
  * because paper covers rock
* Scissors beat Paper
  * because scissors cut paper
* Rock beats Light
  * because you can build a rock structure to block out light
* Paper beats Light
  * because knowledge stored in files and paper books helps us understand light
* Light beats Dark Energy
  * because light enables humans to lighten up and laugh in the face of dark energy as it causes the eventual heat death of the universe
* Light beats Scissors
  * because light is needed to use scissors safely
* Dark Energy beats Rock
  * because dark energy rocks more than rocks. It rocks rocks and everything else in its expansion of the universe
* Dark Energy beats Paper
  * because humans, with their knowledge stored in files and paper books, can't explain dark energy 
* Scissors beat Dark Energy
  * because a human running with scissors is darker than dark energy

# Invalid Input
I was hoping for an worthy opponent
  - but alas it appears that time has past
  - but alas there's little time for your todo list when [todo:fix this] is so vast

# Cancel Game
The future belongs to the bold. Goodbye..
",
  "filename": "RPS+.md",
  "last_modified": "2025-11-25T12:00:00Z"
}

Haz clic en el botón Enviar solicitud junto a la instrucción para ejecutarlo y agregar el documento rps+-md al índice de documentación del juego.

Ahora deberíamos tener algunos datos para consultar, y con Agent Builder, eso es más simple que nunca.

Selecciona Agentes en el menú de navegación superior.

Luego, todo lo que tienes que hacer es preguntarle al agente de Elastic AI predeterminado: "¿Qué datos tengo?".

El agente de Elastic AI evalúa los datos y devuelve una explicación concisa de los datos que tenemos.

Crear una herramienta

Listo, ahora tenemos algunos datos en Elastic; vamos a ponerlos en práctica. Agent Builder incluye soporte integrado para crear herramientas MCP que ayudan a los agentes a acceder a los datos que necesitan para tener el contexto adecuado para su tarea. Vamos a crear una herramienta sencilla que recupere los datos de nuestro juego.

Haz clic en el menú de acciones de Agent Builder.

Selecciona Ver todas las herramientas en las opciones del menú.

Haz clic en + Nueva herramienta.

En el formulario Crear herramienta, selecciona ES|QL como Tipo de herramienta e ingresa los siguientes valores.

Para el ID de la herramienta:

example.get_game_docs

Para la Descripción:

Get RPS+ doc from Elasticsearch game-docs index.

Para la configuración, ingresa la siguiente consulta en el área de texto Consulta ES|QL :

FROM game-docs | WHERE filename == "RPS+.md"

Tu formulario completado de Crear herramienta debería verse así. Haz clic en Guardar para crear la herramienta.

Tenemos una nueva herramienta disponible en el estante de herramientas. Las herramientas no deberían estar colgadas perpetuamente en un estante; hay que darles un uso digno. Creemos un agente que pueda emplear nuestra nueva herramienta personalizada.

Crea un agente y asígnale una herramienta

Crear un agente es sorprendentemente sencillo con Agent Builder. Solo tienes que ingresar las instrucciones del agente con algunos detalles y eso es todo lo que necesitas. Vamos a crear un agente ahora.

Haz clic en Gestionar agentes.

Haz clic en + Nuevo agente.

Introduce la siguiente información en el formulario Nuevo agente.

Para ID de agente, ingresa el texto a continuación:

rps_plus_agent

En el área de texto de Instrucciones personalizadas , ingresa las siguientes instrucciones:

When prompted, if the prompt contains an integer, then select the corresponding numbered item in the list of "Game Objects" from your documents. Otherwise select a random game object. This is your chosen game object for a single round of the game.

# General Game Rules
* 2 players
    - the user: the person playing the game
    - you: the agent playing the game and serving as the game master
* Each player chooses a game object which will be compared and cause them to tie, win or lose.

# Start the game
1. This is the way each new game always starts. You make the first line of your response only the name of your chosen game object. 

2. The remainder of your response should be the "Starting Prompt" text from your documents and generate a list of "Game Objects" for the person playing the game to choose a game object from.  

# End of Game: The game ends in one of the following three outcomes:
1. Invalid Input: If the player responds with an invalid game object choice, respond with variations of the "Invalid Input" text from your documents and then end the game.

2. Tie: The game ends in a tie if the user chooses the same game object as your game object choice.

3. Win or Lose: The game winner is decided based on the "Judgement of Victory" conditions from your documents. Compare the user's game object choice and your game object choice and determine who chose the winning game object.

# Game conclusion
Respond with a declaration of the winner of the game by outputting the corresponding text in the "Judgement of Victory" section of your documents.

Para el Nombre de visualización, ingresa el texto a continuación:

RPS+ Agent

Para la Descripción de la pantalla, ingresa el texto a continuación:

An agent that plays the game RPS+

Brinda al agente la herramienta personalizada que creamos previamente al hacer clic en la pestaña Herramientas.

Selecciona solo la herramienta example.get_game_docs que creamos anteriormente.

Haz clic en Guardar para crear el nuevo agente.

Probemos nuestro nuevo agente. Hay un enlace útil para iniciar un chat con cualquier agente de la lista de agentes.

Simplemente ingresa “iniciar juego” y el juego comenzará. ¡Funciona!

Puedes ver que el agente muestra su elección de objeto de juego en la parte superior de su respuesta. Esto es útil porque podemos ver la elección del agente y confirmar que el juego funciona como se espera. Sin embargo, conocer la elección de tu oponente antes de elegir no lo convierte en un juego muy divertido de "Piedra, papel o tijeras". Para pulir y perfeccionar el juego hasta su forma final, podemos usar una plataforma de orquestación de agentes que pueda controlar a los agentes con código.

El SDK de Strands Agents entra al chat.

SDK de agentes de Strands

Si tienes curiosidad por probar nuevos marcos de trabajo de desarrollo de agentes, entonces vale la pena probar el SDK de Strands Agents. El SDK de Strands Agents fue lanzado por AWS (mayo de 2025) como una implementación de open source Python, y ahora también hay una versión en Typescript.

Introducción al SDK de Strands Agents en Python

Enciende tus motores de programación, ahora vamos a pasar rápidamente por el proceso de clonación y ejecución de una app de ejemplo que usa Strands Agents para controlar el agente de RPS+ mediante el protocolo A2A. Vamos a crear una versión ajustada del juego RPS+ para que la elección del agente se revele después de que hagas tu elección, porque, después de todo, es la adivinación y el resultado sorpresa lo que hace que juegos como "Piedra, papel o tijeras" sean divertidos.

En tu computadora local, abre Visual Studio Code y abre una nueva terminal.

En la terminal recién abierta, ejecuta el siguiente comando para clonar el repositorio de Elasticsearch Labs:

git clone https://github.com/elastic/elasticsearch-labs

Ejecuta el siguiente comando cd para cambiar el directorio al directorio elasticsearch-labs:

cd elasticsearch-labs

A continuación, ejecuta el siguiente comando para abrir el repositorio en Visual Studio Code:

code .

En el Explorador de archivos de Visual Studio, expande las carpetas supporting-blog-content y agent-builder-a2a-strands-agents y luego abre el archivo elastic_agent_builder_a2a_rps+.py. Así es como se ve el archivo abierto en Visual Studio Code:

Aquí tienes el contenido de elastic_agent_builder_a2a_rps+.py que deberías ver en tu editor de texto:

import asyncio
from dotenv import load_dotenv
from uuid import uuid4
import httpx
import os
import random
from a2a.client import A2ACardResolver, ClientConfig, ClientFactory
from a2a.types import Message, Part, Role, TextPart

DEFAULT_TIMEOUT = 60  # set request timeout to 1 minute


def create_message(*, role: Role = Role.user, text: str, context_id=None) -> Message:
    return Message(
        kind="message",
        role="user",
        parts=[Part(TextPart(kind="text", text=text))],
        message_id=uuid4().hex,
        context_id=context_id,
    )


async def main():
    load_dotenv()
    a2a_agent_host = os.getenv("ES_AGENT_URL")
    a2a_agent_key = os.getenv("ES_API_KEY")
    custom_headers = {"Authorization": f"ApiKey {a2a_agent_key}"}

    async with httpx.AsyncClient(
        timeout=DEFAULT_TIMEOUT, headers=custom_headers
    ) as httpx_client:
        # Get agent card
        resolver = A2ACardResolver(httpx_client=httpx_client, base_url=a2a_agent_host)
        agent_card = await resolver.get_agent_card(
            relative_card_path="/rps_plus_agent.json"
        )
        # Create client using factory
        config = ClientConfig(
            httpx_client=httpx_client,
            streaming=True,
        )
        factory = ClientFactory(config)
        client = factory.create(agent_card)
        # Use the client to communicate with the agent
        print("\nSending 'start game' message to Elastic A2A agent...")
        random_game_object = random.randint(1, 5)
        msg = create_message(text=f"start with game object {random_game_object}")
        async for event in client.send_message(msg):
            if isinstance(event, Message):
                context_id = event.context_id
                response_complete = event.parts[0].root.text
                # Get agent choice from the first line of the response
                parsed_response = response_complete.split("\n", 1)
                agent_choice = parsed_response[0]
                print(parsed_response[1])
        # User choice sent for game results from the agent
        prompt = input("Your Choice  : ")
        msg = create_message(text=prompt, context_id=context_id)
        async for event in client.send_message(msg):
            if isinstance(event, Message):
                print(f"Agent Choice : {agent_choice}")
                print(event.parts[0].root.text)


if __name__ == "__main__":
    asyncio.run(main())

Repasemos qué está pasando en este código. A partir del método main() , el código comienza accediendo a las variables de entorno para la URL del agente y la clave de API. Luego, usamos esos valores para crear un httpx client que podamos usar para obtener la tarjeta de agente para el agente. El cliente luego usa los detalles de la tarjeta del agente para enviar una solicitud de "iniciar juego" al agente. Un aspecto interesante a tener en cuenta aquí es que incluimos un valor random_game_object como parte de la solicitud "start game". Este valor es un número aleatorio generado con el módulo aleatorio de la biblioteca estándar de Python. La razón para hacerlo es que resulta que los poderosos LLM (que hacen posibles a los agentes de IA) no son muy buenos en la aleatoriedad. No hay problema, Python viene al rescate.

Continuando con la programación, una vez que el agente responde a la solicitud de "iniciar juego", el código elimina la selección del objeto de juego del agente y lo guarda en la variable agent_choice. El resto de la respuesta se muestra como texto para el usuario final. Luego, se le solicita al usuario su entrada de elección de objeto de juego, la cual se envía al agente. El código muestra la elección del objeto del juego del agente junto con la determinación final del agente sobre el resultado del juego.

Establecer la URL de tu agente y la clave de API como variables de entorno

Dado que la app de ejemplo se ejecutará en tu computadora local, para comunicarla con nuestro agente Agent Builder, debemos proporcionar al SDK de Strands Agents una URL A2A y una clave API para el agente. La app de ejemplo emplea un archivo llamado .env para almacenar estos valores.

Haz una copia del archivo env.example y nombra el nuevo archivo .env

Vuelve a Elastic Agent Builder, donde podrás obtener los dos valores que necesitas.

Selecciona Ver todas las herramientas en el menú de acciones de Agent Builder en la parte superior derecha de la página.

Haz clic en el menú desplegable servidor MCP en la parte superior de la página Herramientas y selecciona Copiar URL del servidor MCP.

Pega la URL del servidor MCP en el archivo .env como reemplazo para el valor de marcador de posición <YOUR-ELASTIC-AGENT-BUILDER-URL> . Ahora necesitamos hacer una actualización a la URL, es decir, reemplazar el texto final “mcp” con “a2a” porque el protocolo A2A es lo que usará el Agent Strands SDK para comunicarse con el agente que se ejecuta en Elastic Agent Builder.

La URL editada debería verse así:

https://rps-game-project-12345a.kb.us-east-1.aws.elastic.cloud/api/agent_builder/a2a

El otro valor que necesitamos obtener mientras estamos aquí en Elastic Cloud es una clave API. Haz clic en Elasticsearch en el menú de navegación superior.

Haz clic en el botón Copiar clave API para copiar la clave API.

Ahora, de vuelta en Visual Studio Code, pega la clave API en el archivo .env para reemplazar el texto del marcador de posición <YOUR-ELASTIC-API-KEY> . Tu archivo .env debería verse algo así:

Ejecuta la app de ejemplo

Abre una nueva terminal en Visual Studio Code.

Empieza ejecutando el siguiente comando cd en la terminal:

cd elasticsearch-labs/supporting-blog-content/agent-builder-a2a-strands-agents

Ejecuta el siguiente comando para crear un entorno virtual en Python.

python -m venv .venv

Dependiendo del sistema operativo de tu computadora local, ejecuta el siguiente comando para activar el entorno virtual.

• MacOS/Linux

source .venv/bin/activate

• Windows

.venv\Scripts\activate

La app de ejemplo utiliza Strands Agents SDK, y ahora nos encontramos en el punto de este tutorial en el que debes instalarlo. Ejecuta el siguiente comando para instalar el SDK de Strands Agents junto con todas tus dependencias requeridas de la biblioteca de Python.

pip install -r requirements.txt

Es hora de limpiar la plataforma de lanzamiento y comenzar la cuenta regresiva. Estamos listos para lanzar esta app. Retírate. Vamos a ejecutarla usando el siguiente comando:

python elastic_agent_builder_a2a_rps+.py

Deberías desafiarte con un juego de RPS+. ¡Bien hecho y mucha suerte!

Crea tus apps de IA con contexto relevante

Crear un agente con IA es ahora una habilidad en tu caja de herramientas. Y has visto lo fácil que es usar agentes de Elastic Agent Builder a través de A2A en marcos de trabajo de agentes como Strands Agents SDK. Prueba Elastic para crear agentes de IA conectados al contexto relevante en tus datos personalizados.

Recientemente contribuimos al proyecto open source Google MCP Toolbox for Databases agregando soporte para Elasticsearch como base de datos.

Con esta nueva característica, ahora puedes usar Google MCP Toolbox para conectarte a Elasticsearch y “conversar” directamente con tus datos.

Elasticsearch

Es necesario tener una instancia de Elasticsearch en funcionamiento. Puedes activar una prueba gratuita en Elastic Cloud o instalarla localmente utilizando el script start-local:

curl -fsSL https://elastic.co/start-local | sh

Esto instalará Elasticsearch y Kibana en tu computadora y generará una clave API que se utilizará para configurar Google MCP Toolbox.

La clave de API se mostrará como salida del comando anterior y se almacenará en un archivo .env. en la carpeta elastic-start-local.

Instala el set de datos de ejemplo

Tras la instalación, puedes iniciar sesión en Kibana con el nombre de usuario elastic y la contraseña generada por el script start-local (almacenada en un archivo .env).

Puedes instalar el conjunto de datos de pedidos de comercio electrónico disponible desde Kibana. Incluye un único índice llamado kibana_sample_data_ecommerce que contiene información sobre 4675 pedidos de un sitio web de comercio electrónico. Para cada pedido, tenemos la siguiente información:

• Información del cliente (nombre, identificación, fecha de nacimiento, correo electrónico, etc.)
• Fecha del pedido
• ID de pedido
• Productos (lista de todos los productos con precio, cantidad, identificación, categoría, descuento, etc.)
• SKU
• Precio total (sin impuestos, con impuestos)
• Cantidad total
• Información geográfica (ciudad, país, continente, ubicación, región)

Para instalar los datos de muestra, abre la página Integraciones en Kibana (busca “Integración” en la barra superior de búsqueda) e instala los “Datos de muestra”. Para obtener más detalles, consulta la documentación aquí: https://www.elastic.co/docs/explore-analyze/#gs-get-data-into-kibana.

El objetivo de este artículo es mostrar lo fácil que es configurar Google MCP Toolbox para conectarse a Elasticsearch e interactuar con el índice de kibana_sample_data_ecommerce usando lenguaje natural.

Google MCP Toolbox

Google MCP Toolbox es un servidor MCP open source diseñado para facilitar la interacción segura y eficiente de aplicaciones y agentes de IA con bases de datos. El proyecto, anteriormente conocido como el “GenAI Toolbox for Databases”, cambió su denominación después de adoptar la compatibilidad total con el Protocolo de contexto de modelo (MCP). Su propósito es eliminar el trabajo pesado que tradicionalmente se requiere al conectar agentes con bases de datos, gestionando la agrupación de conexiones, autenticación, observabilidad y otras preocupaciones operativas en segundo plano.

Esencialmente, Toolbox permite a los desarrolladores definir herramientas reutilizables de alto nivel que encapsulan las interacciones con la base de datos. Estas herramientas pueden ser invocadas por cualquier cliente compatible con MCP (como un agente de IA) sin requerir que el cliente implemente consultas SQL de bajo nivel o administre conexiones de base de datos. Este enfoque reduce drásticamente la cantidad de código repetitivo necesario para crear agentes compatibles con bases de datos, lo que permite integrar operaciones de datos avanzadas en solo unas pocas líneas de lógica de aplicación. Una vez definida una herramienta, se puede compartir entre varios agentes, marcos de trabajo o lenguajes (Figura 1).

Una de las ventajas principales de usar la Toolbox es el modelo de seguridad integrado. Los flujos de autenticación como OAuth2 y OIDC son compatibles de forma nativa, lo que permite a los desarrolladores evitar manejar o almacenar credenciales confidenciales de bases de datos en agentes. La plataforma también ofrece características de observabilidad (como métricas y rastreo) a través de OpenTelemetry, que es esencial para la depuración, la supervisión y los despliegues de producción. En conjunto, MCP Toolbox sirve como una interfaz unificada, segura y extensible para interactuar con tus datos desde cualquier sistema compatible con MCP.

Cómo instalar MCP Toolbox

Puedes instalar el servidor MCP Toolbox en Linux usando el siguiente comando:

export VERSION=0.21.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

Si quieres instalarlo en macOS o Windows, puedes seguir las instrucciones detalladas aquí.

Configura la Toolbox para Elasticsearch

Para configurar el MCP Toolbox para Elasticsearch, necesitamos crear un archivo tools.yaml, de la siguiente manera:

sources:
  my-cluster:
    kind: elasticsearch
    addresses:
      - http://localhost:9200
    apikey: 

tools:
  customer-orders:
    kind: elasticsearch-esql
    source: my-cluster
    description: Get the orders made by a customer identified by name.
    query: |
    	FROM kibana_sample_data_ecommerce | WHERE MATCH(customer_full_name, ?name, {"operator": "AND"})
    parameters:
      - name: name
        type: string
        description: The customer name.

toolsets:
  elasticsearch-tools:
    - customer-orders

Debes reemplazar el valor <insert-here-api-key> por una clave API válida de Elasticsearch. Si estás ejecutando Elasticsearch localmente usando start-local, puedes encontrar la clave de API en el archivo.env generado por start-local, bajo la variable ES_LOCAL_API_KEY . Si usas Elastic Cloud, puedes generar una clave API siguiendo el procedimiento descrito aquí.

Las herramientas anteriores contienen la siguiente consulta ES|QL para Elasticsearch:

FROM kibana_sample_data_ecommerce | WHERE MATCH(customer_full_name, ?name)

Si no estás familiarizado con ES|QL, es un lenguaje de búsqueda desarrollado por Elastic, similar a SQL, que puedes usar para buscar en uno o más índices. Puedes leer más sobre ES|QL en la documentación oficial aquí.

La búsqueda anterior busca todos los pedidos almacenados en el índice kibana_sample_data_ecommerce que contienen el nombre del cliente especificado, usando el parámetro ?name (el signo de interrogación indica un parámetro).

El nombre del cliente se define en la configuración YAML anterior empleando el texto de tipo y la descripción "El nombre del cliente".

Esta herramienta se puede usar para responder preguntas sobre los pedidos de un cliente, por ejemplo: ¿Cuántos pedidos realizó el cliente Foo en octubre de 2025?

Las descripciones de las herramientas y sus parámetros son esenciales para extraer la información relevante de la solicitud en lenguaje natural del usuario. Esta extracción se realiza utilizando la capacidad de llamada de función de un modelo de lenguaje grande (LLM). En la práctica, un LLM puede determinar qué función (herramienta) debe ejecutar para obtener la información necesaria, junto con los parámetros apropiados para esa función.

Para más información sobre las llamadas a funciones, sugerimos leer el artículo de OpenAI sobre llamadas a funciones con Elasticsearch de Ashish Tiwari.

Ejecuta el servidor de Toolbox

Puedes ejecutar la MCP Toolbox usando el archivo tools.yaml anterior con el siguiente comando:

./toolbox --tools-file tools.yaml --ui

El parámetro –ui ejecuta una aplicación sitio web en http://127.0.0.1:5000/ui (Figura 2).

Puedes seleccionar la Herramientas > pedidos-clientes e insertar un nombre de cliente en el parámetro nombre (por ejemplo, Gwen Sanders) y haz clic en el botón Ejecutar herramienta. Deberías ver una respuesta JSON como se indica en la Figura 3.

La configuración se ha completado y MCP Toolbox puede ejecutar la herramienta de pedidos de clientes para comunicarse con Elasticsearch, ejecutando la consulta ES|QL.

Usar la herramienta MCP Toolbox con Gemini CLI

Podemos usar cualquier cliente del MCP para comunicarnos con MCP Toolbox for Database. Por ejemplo, podemos usar Gemini CLI, una herramienta de línea de comandos, para usar Gemini. Puedes instalar Gemini CLI siguiendo las instrucciones indicadas aquí.

Gemini CLI ofrece una extensión preconfigurada para MCP Toolbox, disponible en gemini-cli-extensions/mcp-toolbox. Puedes instalar esta extensión ejecutando el comando siguiente:

gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

Tras la instalación, debes ir al directorio donde almacenaste el archivo de configuración tools.yaml para MCP Toolbox y ejecutar la CLI Gemini de la siguiente manera (este paso es necesario para que la CLI Gemini se configure automáticamente con MCP Toolbox):

gemini

Deberías ver un anuncio de salida como el que se muestra en la Figura 4.

Puedes comprobar si MCP Toolbox está conectada usando el siguiente comando:

/mcp list

Deberías ver el mcp_toolbox con las herramientas de customer-orders listadas (Figura 5).

Si el MCP Toolbox está conectado a la CLI de Gemini, ahora podemos intentar hacer algunas preguntas, como: “Dame los pedidos del cliente Gwen Sanders”. La CLI de Gemini solicitará entonces permiso para ejecutar la herramienta de pedidos de clientes desde el servidor mcp_toolbox (ver Figura 6).

Tras la confirmación, Gemini CLI ejecutará la solicitud a MCP Toolbox, obteniendo una respuesta JSON como resultado y utilizándola para dar formato a la respuesta (Figura 7).

La respuesta de Gemini CLI será un reporte que indica que Gwen Sanders hizo solo un pedido de 2 productos, por un precio total de 132 euros.

SDK de MCP Toolbox

Google MCP Toolbox también ofrece un SDK para acceder a todas las funcionalidades desde un programa escrito en Go, Python y Javascript.

Por ejemplo, el SDK de Python está disponible en Github en la siguiente página: https://github.com/googleapis/mcp-toolbox-sdk-python.

Es necesario crear un agente simple para conectarnos a MCP Toolbox. Debemos instalar los siguientes paquetes:

pip install toolbox-core
pip install google-adk

Además, crear un nuevo proyecto de agente usando los siguientes comandos:

adk create my_agent

Esto creará un nuevo directorio llamado my_agent con un archivo agent.py.

Actualiza my_agent/agent.py con el siguiente contenido para conectar con Toolbox:

from google.adk import Agent
from google.adk.apps import App
from toolbox_core import ToolboxSyncClient

client = ToolboxSyncClient("http://127.0.0.1:5000")

root_agent = Agent(
    name='root_agent',
    model='gemini-2.5-flash',
    instruction="You are a helpful AI assistant designed to search information about a dataset of ecommerce orders.",
    tools=client.load_toolset(),
)

app = App(root_agent=root_agent, name="my_agent")

Crea un archivo .env con tu clave de API de Google:

echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > my_agent/.env

Finalmente, podemos ejecutar el agente y observar los resultados. Para ejecutar el agente, puedes ejecutar el siguiente comando:

adk run my_agent

O bien, puedes servirlo a través de una interfaz web:

adk web --port 8000

En ambos casos, puedes interactuar con MCP Toolbox usando una interfaz de preguntas frecuentes. Por ejemplo, puedes hacer la pregunta anterior: Dame las órdenes de la cliente Gwen Sanders.

Para más información sobre los diferentes SDK, puedes consultar esta página de documentación.

Conclusión

En este artículo, hemos mostrado la integración de Elasticsearch con Google MCP Toolbox for Databases. Mediante un sencillo archivo de configuración YAML, podemos definir un conjunto de herramientas que traducen preguntas en lenguaje natural a consultas de Elasticsearch utilizando el lenguaje ES|QL.

Mostramos cómo interactuar con el set de datos kibana_sample_data_ecommerce, que contiene pedidos de un sitio web de comercio electrónico. Con este archivo de configuración, podemos simplemente ejecutar el servidor MCP Toolbox y conectarnos a él desde cualquier cliente MCP.

Por último, mostramos cómo utilizar la CLI de Gemini como cliente para conectarse a MCP Toolbox for Databases y consultar los datos de comercio electrónico almacenados en Elasticsearch. Ejecutamos una consulta en lenguaje natural para recuperar información sobre pedidos para un cliente específico identificado por su nombre.

A medida que el ecosistema MCP sigue creciendo, este patrón (definiciones ligeras de herramientas respaldadas por infraestructuras seguras y listas para producción) crea nuevas oportunidades para construir agentes cada vez más capaces y conscientes de los datos con un esfuerzo mínimo. Ya sea que experimentes localmente con los sets de datos de muestra de Elastic o integres capacidades de búsqueda en una aplicación más amplia, MCP Toolbox ofrece una base fiable y extensible para interactuar con tus datos de Elasticsearch usando lenguaje natural.

Para obtener más información sobre el desarrollo de aplicaciones de IA agentic, puedes leer el artículo Creación de flujos de trabajo de IA agentic con Elasticsearch de Anish Mathur y Dana Juratoni.

Para obtener más información sobre Google MCP Toolbox, puedes visitar https://googleapis.github.io/genai-toolbox/getting-started/introduction/.

Sin embargo, cuando solucionas este problema, accidentalmente rompes otras consultas porque no pudiste probar todos los casos manualmente. Pero, ¿cómo puedes tú o tu equipo de control de calidad comprobar si un cambio en una consulta tiene un efecto dominó en otras consultas? O aún más importante, ¿cómo puedes estar seguro de que tus cambios realmente mejoraron una consulta?

Hacia una evaluación sistemática

Aquí es donde las listas de evaluación resultan útiles. En lugar de depender de pruebas manuales y subjetivas cada vez que realices un cambio, puedes definir un conjunto fijo de búsquedas que sean relevantes para tu caso de negocio, junto con sus resultados relevantes.

Este conjunto se convierte en tu referencia. Cada vez que implementas un cambio, lo utilizas para evaluar si tu búsqueda realmente mejoró o no.

El valor de este enfoque radica en que:

• Elimina la incertidumbre: ya no necesitas preguntarte si tus cambios afectan a otras consultas; los datos te lo dirán.
• Detiene las pruebas manuales: una vez que se registran los conjuntos de evaluación, la prueba es automática.
• Soporta cambios: puedes mostrar métricas claras que respaldan los beneficios de un cambio.

Cómo empezar a crear tu lista de evaluaciones

Una de las maneras más fáciles de comenzar es tomar una búsqueda representativa y seleccionar manualmente los documentos relevantes. Hay dos formas de hacer esta lista:

• Evaluaciones binarias: cada documento asociado con una búsqueda recibe una etiqueta simple: relevante (generalmente con una puntuación de “1”) y no relevante (“0”).
• Evaluaciones graduadas: aquí, cada documento obtiene una puntuación con diferentes niveles. Por ejemplo: establecer un escala de 0 a 4, similar a un escala Likert, donde 0 = “nada relevante” y 4 = “totalmente relevante”, con variaciones como “relevante”, “algo relevante”, etc.

Los juicios binarios funcionan bien cuando la intención de búsqueda tiene límites claros: ¿Debería este documento estar en los resultados o no?

Las evaluaciones graduadas son más útiles cuando hay áreas grises: algunos resultados son mejores que otros, así que puedes obtener resultados “muy buenos”, “buenos” e “inútiles” y usar métricas que valoren el orden de los resultados y los comentarios del usuario. Sin embargo, las escalas graduadas también presentan inconvenientes: diferentes revisores pueden usar los niveles de puntuación de manera diferente, lo que hace que las evaluaciones sean menos consistentes. Y debido a que las métricas graduadas dan más peso a las puntuaciones más altas, incluso un pequeño cambio (como calificar algo con un 3 en lugar de un 4) puede crear un cambio mucho mayor en la métrica de lo que el revisor pretendía. Esta subjetividad añadida hace que las evaluaciones graduadas sean más complicadas y difíciles de manejar con el tiempo.

¿Necesito clasificar los documentos por mi cuenta?

No necesariamente, ya que hay diferentes formas de crear tu lista de evaluaciones, cada una con sus propias ventajas y desventajas:

• Evaluaciones explícitas: aquí, los expertos revisan cada búsqueda/documento y deciden manualmente si es relevante (o qué tan relevante es). Si bien esto proporciona calidad y control, tiene menos escalabilidad.
• Evaluaciones implícitas: con este método, infieres los documentos relevantes en función del comportamiento real del usuario, como clics, tasa de rebote y compras, entre otros. Este enfoque te permite recopilar datos automáticamente, aunque puede estar sesgado. Por ejemplo, los usuarios tienden a hacer clic en los primeros resultados con más frecuencia, incluso si no son relevantes.
• Evaluaciones generadas por IA: esta última opción utiliza modelos (como LLM) para evaluar automáticamente consultas y documentos, a menudo referidos como jurados de LLM. Es rápido y fácil de escalar, pero la calidad de los datos depende de la calidad del modelo que estés utilizando y de qué tan bien los datos de entrenamiento de LLM se alinean con tus intereses comerciales. Al igual que con las calificaciones humanas, los jurados LLM pueden introducir sus propios sesgos o inconsistencias, por lo que es importante validar su salida contra un conjunto más pequeño de evaluaciones confiables. Los modelos LLM son probabilísticos por naturaleza, por lo que no es raro ver un modelo LLM dando diferentes calificaciones al mismo resultado independientemente de que el parámetro de temperatura sea 0.

A continuación, se incluyen algunas recomendaciones para elegir el mejor método para crear tu conjunto de evaluaciones:

• Decide cuán importantes son para ti algunas características que solo los usuarios puedan juzgar correctamente (como precio, marca, idioma, estilo y detalles del producto). Si esos son críticos, necesitas evaluaciones explícitas para al menos alguna parte de tu lista de evaluaciones.
• Usa evaluaciones implícitas cuando tu motor de búsqueda ya tenga suficiente tráfico para que puedas usar clics, conversiones y métricas de tiempo persistente para detectar tendencias de uso. Aun así, deberías interpretarlos con cuidado, contrastándolos con tus evaluaciones explícitas para prevenir sesgos (por ejemplo: los usuarios tienden a hacer clic más a menudo en los resultados mejor clasificados, incluso si los de menor rango son más relevantes)

Para abordar esto, las técnicas de eliminación del sesgo de posición ajustan o reponderan los datos de clics para reflejar mejor el verdadero interés del usuario. Algunos enfoques incluyen:

• Reordenación de resultados: cambia el orden de los resultados de búsqueda para un subconjunto de usuarios con el fin de estimar cómo afecta la posición a los clics.
• Los modelos de clics incluyen la red bayesiana dinámica (DBN) y el modelo de navegación del usuario (UBM). Estos modelos estadísticos estiman la probabilidad de que un clic refleje un interés real en lugar de solo la posición, utilizando patrones como el desplazamiento, el tiempo de permanencia, la secuencia de clics y el retorno a la página de resultados.

Ejemplo: app de valoración de películas

Requisitos previos

Para ejecutar este ejemplo, necesitas un cluster Elasticsearch 8.x en funcionamiento, localmente o Elastic Cloud Hosted (alojado o sin servidor), y acceso a la API REST o Kibana.

Imagina una app en la que los usuarios puedan realizar el monitoreo de tiempo de actividad de sus opiniones sobre películas y también hacer una búsqueda de películas para ver. Como los textos son escritos por los propios usuarios, pueden contener errores tipográficos y muchas variaciones en cuanto a la expresión. Por eso es fundamental que el motor de búsqueda sea capaz de interpretar esa diversidad y ofrecer resultados útiles para los usuarios.

Para poder repetir consultas sin afectar el comportamiento general de búsqueda, el equipo de negocios de tu empresa creó el siguiente conjunto de evaluaciones binarias, basado en las búsquedas más frecuentes:

Creación del índice:

PUT movies
{
  "mappings": {
    "properties": {
      "text": {
        "type": "text"
      }
    }
  }
}

Solicitud en masa:

POST /movies/_bulk
{ "index": { "_id": "doc1" } }
{ "text": "DiCaprio performance in The Revenant was breathtaking." }
{ "index": { "_id": "doc2" } }
{ "text": "Inception shows Leonardo DiCaprio in one of his most iconic roles." }
{ "index": { "_id": "doc3" } }
{ "text": "Brad Pitt delivers a solid performance in this crime thriller." }
{ "index": { "_id": "doc4" } }
{ "text": "An action-packed adventure with stunning visual effects." }
{ "index": { "_id": "doc5" } }
{ "text": "A heartbreaking story of love and loss that made me cry for hours." }
{ "index": { "_id": "doc6" } }
{ "text": "One of the saddest movies ever made -- bring tissues!" }
{ "index": { "_id": "doc7" } }
{ "text": "A lighthearted comedy that will make you laugh." }
{ "index": { "_id": "doc8" } }
{ "text": "A science-fiction epic full of action and excitement." }

A continuación se muestra la consulta Elasticsearch que emplea la app:

GET movies/_search
{
 "query": {
   "match": {
     "text": {
       "query": "DiCaprio performance",
       "minimum_should_match": "100%"
     }
   }
 }
}

De juicio a métricas

Por sí solas, las listas de evaluaciones no proporcionan mucha información; son solo una expectativa de los resultados de nuestras consultas. Donde realmente destacan es cuando los usamos para calcular métricas objetivo que midan nuestro rendimiento en búsqueda.

Actualmente, la mayoría de las métricas populares incluyen

• Precisión: mide la proporción de resultados que son realmente relevantes dentro de todos los resultados de búsqueda.
• Recuperación: mide la proporción de resultados relevantes que el motor de búsqueda encontró entre x resultados.
• Ganancia acumulada descontada (DCG): mide la calidad de la clasificación del resultado, considerando que los resultados más relevantes deben estar en la parte superior.
• Rango recíproco medio (MRR): mide la posición del primer resultado relevante. Cuanto más alto estés en la lista, mayor será tu puntuación.

Usando la misma app de clasificación de películas como ejemplo, calcularemos la métrica de recuperación para ver si hay alguna información que se esté excluyendo de nuestras consultas.

En Elasticsearch, podemos usar las listas de evaluaciones para calcular métricas mediante la API de Evaluación de Rankings. Esta API recibe como entrada la lista de evaluaciones, la consulta y la métrica que deseas evaluar, y devuelve un valor, que es una comparación del resultado de la consulta con la lista de evaluaciones.

Vamos a ejecutar la lista de evaluaciones para las dos consultas que tenemos:

POST /movies/_rank_eval
{
 "requests": [
   {
     "id": "dicaprio-performance",
     "request": {
       "query": {
         "match": {
           "text": {
             "query": "DiCaprio performance",
             "minimum_should_match": "100%"
           }
         }
       }
     },
     "ratings": [
       {
         "_index": "movies",
         "_id": "doc1",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc2",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc3",
         "rating": 0
       },
       {
         "_index": "movies",
         "_id": "doc4",
         "rating": 0
       }
     ]
   },
   {
     "id": "sad-movies",
     "request": {
       "query": {
         "match": {
           "text": {
             "query": "sad movies that make you cry",
             "minimum_should_match": "100%"
           }
         }
       }
     },
     "ratings": [
       {
         "_index": "movies",
         "_id": "doc5",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc6",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc7",
         "rating": 0
       },
       {
         "_index": "movies",
         "_id": "doc8",
         "rating": 0
       }
     ]
   }
 ],
 "metric": {
   "recall": {
     "k": 10,
     "relevant_rating_threshold": 1
     }
 }
}

Usaremos dos solicitudes para _rank_eval: una para la búsqueda de DiCaprio y otra para películas tristes. Cada solicitud incluye una búsqueda y su lista de evaluaciones (calificaciones). No necesitamos calificar todos los documentos ya que los que no se incluyen en las calificaciones se consideran sin evaluación. Para realizar los cálculos, recuerda que la recuperación solo considera “el conjunto relevante”, los documentos que se consideran relevantes en la clasificación.

En este caso, la búsqueda de DiCaprio tiene una recuperación de 1, mientras que las películas tristes obtuvieron 0. Esto significa que para la primera búsqueda, pudimos obtener todos los resultados relevantes, mientras que en la segunda búsqueda, no obtuvimos ninguno. Por tanto, la recuperación medio es de 0,5.

{
 "metric_score": 0.5,
 "details": {
   "dicaprio-performance": {
     "metric_score": 1,
     "unrated_docs": [],
     "hits": [
       {
         "hit": {
           "_index": "movies",
           "_id": "doc1",
           "_score": 2.4826927
         },
         "rating": 1
       },
       {
         "hit": {
           "_index": "movies",
           "_id": "doc2",
           "_score": 2.0780432
         },
         "rating": 1
       }
     ],
     "metric_details": {
       "recall": {
         "relevant_docs_retrieved": 2,
         "relevant_docs": 2
       }
     }
   },
   "sad-movies": {
     "metric_score": 0,
     "unrated_docs": [],
     "hits": [],
     "metric_details": {
       "recall": {
         "relevant_docs_retrieved": 0,
         "relevant_docs": 2
       }
     }
   }
 },
 "failures": {}
}

Tal vez estamos siendo demasiado estrictos con el parámetro minimum_should_match ya que al exigir que el 100 % de las palabras en la consulta se encuentren en los documentos, probablemente estamos excluyendo resultados relevantes. Eliminemos el parámetro minimum_should_match para que un documento se considere relevante si solo se encuentra una palabra de la consulta en él.

POST /movies/_rank_eval
{
 "requests": [
   {
     "id": "dicaprio-performance",
     "request": {
       "query": {
         "match": {
           "text": {
             "query": "DiCaprio performance"
           }
         }
       }
     },
     "ratings": [
       {
         "_index": "movies",
         "_id": "doc1",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc2",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc3",
         "rating": 0
       },
       {
         "_index": "movies",
         "_id": "doc4",
         "rating": 0
       }
     ]
   },
   {
     "id": "sad-movies",
     "request": {
       "query": {
         "match": {
           "text": {
             "query": "sad movies that make you cry"
           }
         }
       }
     },
     "ratings": [
       {
         "_index": "movies",
         "_id": "doc5",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc6",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc7",
         "rating": 0
       },
       {
         "_index": "movies",
         "_id": "doc8",
         "rating": 0
       }
     ]
   }
 ],
 "metric": {
   "recall": {
     "k": 10,
     "relevant_rating_threshold": 1
     }
 }
}

Como puedes ver, al eliminar el parámetro minimum_should_match en una de las dos consultas, ahora obtenemos una recuperación promedio de 1 en ambas.

{
  "metric_score": 1,
  "details": {
    "dicaprio-performance": {
      "metric_score": 1,
      "unrated_docs": [],
      "hits": [
        {
          "hit": {
            "_index": "movies",
            "_id": "doc1",
            "_score": 2.0661702
          },
          "rating": 1
        },
        {
          "hit": {
            "_index": "movies",
            "_id": "doc3",
            "_score": 0.732218
          },
          "rating": 0
        },
        {
          "hit": {
            "_index": "movies",
            "_id": "doc2",
            "_score": 0.6271719
          },
          "rating": 1
        }
      ],
      "metric_details": {
        "recall": {
          "relevant_docs_retrieved": 2,
          "relevant_docs": 2
        }
      }
    },
    "sad-movies": {
      "metric_score": 1,
      "unrated_docs": [],
      "hits": [
        {
          "hit": {
            "_index": "movies",
            "_id": "doc7",
            "_score": 2.1307156
          },
          "rating": 0
        },
        {
          "hit": {
            "_index": "movies",
            "_id": "doc5",
            "_score": 1.3160692
          },
          "rating": 1
        },
        {
          "hit": {
            "_index": "movies",
            "_id": "doc6",
            "_score": 1.190063
          },
          "rating": 1
        }
      ],
      "metric_details": {
        "recall": {
          "relevant_docs_retrieved": 2,
          "relevant_docs": 2
        }
      }
    }
  },
  "failures": {}
}

En resumen, al eliminar la cláusula minimum_should_match: 100%, podemos obtener una recuperación perfecta para ambas búsquedas.

¡Lo logramos! ¿Cierto?

¡No tan rápido!

Al mejorar la memoria, abrimos la puerta a un rango más amplio de resultados. Sin embargo, cada ajuste implica una compensación. Por esto es importante definir casos de prueba completos, utilizando diferentes métricas para evaluar los cambios.

El uso de listas de evaluaciones y métricas previene que hagas cambios a ciegas, ya que ahora tienes datos para respaldarlos. La validación ya no es manual y repetitiva, y puedes probar tus cambios en más de un caso de uso. Además, las pruebas A/B te permiten probar en tiempo real qué configuración funciona mejor para tus usuarios y tu caso de negocio, cerrando así la brecha entre métricas técnicas y métricas reales.

Recomendaciones finales para el uso de listas de evaluaciones

Trabajar con listas de evaluaciones no solo consiste en medir, sino también en crear un marco de trabajo que te permita iterar con confianza. Para lograr esto, puedes seguir estas recomendaciones:

1. Empieza poco a poco, pero empieza. No es necesario que tengas 10 000 consultas con 50 listas de evaluaciones cada una. Solo necesitas identificar las 5 a 10 consultas más críticas para tu caso de negocio y definir qué documentos esperas ver en la parte superior de los resultados. Esto ya te da una base. Por lo general, te conviene comenzar con las consultas principales y las consultas sin resultados. También puedes comenzar a probar con una métrica fácil de configurar como Precisión y luego ir aumentando la complejidad.
2. Valida con los usuarios. Complementa los números con pruebas A/B en producción. De esta manera, sabrás si los cambios que se ven bien en las métricas también están generando un impacto real.
3. Haz un mantenimiento de la lista. Tu caso de negocio evolucionará, y también lo harán tus consultas críticas. Actualiza tu evaluación de forma periódica para reflejar las necesidades nuevas.
4. Haz que sea parte del flujo. Integra listas de evaluaciones en tus pipelines de desarrollo. Asegúrate de que cada cambio de configuración, sinónimo o análisis de texto se valide automáticamente contra tu lista base.
5. Conecta conocimientos técnicos con estrategia. No te limites a medir parámetros técnicos como la precisión o la recuperación. Usa tus resultados de la evaluación para influir en los resultados comerciales.

¿Qué es LangGraph?

LangGraph es un marco de trabajo para construir agentes de IA y orquestarlos en un flujo de trabajo para crear aplicaciones asistidas por IA. LangGraph tiene una arquitectura de nodes donde podemos declarar funciones que representan tareas y asignarlas como nodes del flujo de trabajo. El resultado de la interacción de varios nodes será un grafo. LangGraph es parte del ecosistema más amplio LangChain, que proporciona herramientas para construir sistemas de IA modulares y componibles.

Para explicar mejor por qué LangGraph es útil, vamos a usarlo para resolver una situación problemática.

Visión general de la solución

En una firma de capital de riesgo, los inversores tienen acceso a una gran base de datos con muchas opciones de filtrado, pero cuando uno quiere combinar criterios, se vuelve difícil y lento. Esto puede hacer que algunas iniciativas relevantes no se encuentren para la inversión. Además, implica pasar muchas horas intentando identificar a los mejores candidatos, o incluso perder oportunidades.

Con LangGraph y Elasticsearch, podemos realizar búsquedas filtradas utilizando lenguaje natural, eliminando la necesidad de que los usuarios construyan manualmente solicitudes complejas con docenas de filtros. Para hacerlo más flexible, el flujo de trabajo decide automáticamente (basándose en la entrada del usuario) entre dos tipos de consulta:

• Consultas centradas en la inversión: estas se dirigen a aspectos financieros y de financiación de las startups, como rondas de financiación, valoración o ingresos. Ejemplo: “Encuentra startups con financiamiento Serie A o Serie B entre $8M y $25M e ingresos mensuales superiores a $500K”.
• Consultas centradas en el mercado: estas se concentran en verticales de la industria, mercados geográficos o modelos de negocio, ayudando a identificar oportunidades en sectores o regiones específicos. Ejemplo: “Encuentra startups de fintech y salud en San Francisco, Nueva York o Boston”.

Para mantener la solidez de las consultas, haremos que el LLM cree plantillas de búsqueda en lugar de consultas DSL completas. De esta manera, siempre obtienes la consulta que deseas, y el LLM solo tiene que completar los espacios en blanco y no cargar con la responsabilidad de construir la consulta que necesitas cada vez.

Lo que necesitas para comenzar

• Clave de API de Elasticsearch
• Clave de API de OpenAPI
• Node 18 o más reciente

Instrucciones paso a paso

En esta sección, mostramos cómo se verá la app. Para ello, emplearemos TypeScript, un superconjunto de JavaScript que agrega tipos estáticos para hacer el código más fiable, fácil de mantener y seguro, detectando errores pronto mientras se mantiene totalmente compatible con el JavaScript existente.

El flujo de los nodos será el siguiente:

La imagen de arriba es generada por LangGraph y representa el flujo de trabajo que define el orden de ejecución y la lógica condicional entre nodos:

• decideStrategy: utiliza un LLM para analizar la consulta del usuario y decidir entre dos estrategias de búsqueda especializadas, como centrada en la inversión u orientada al mercado.
• prepareInvestmentSearch: extrae valores de filtro de la consulta y construye una plantilla predefinida que destaca los parámetros financieros y de financiación.
• prepareMarketSearch: extrae también los valores del filtro, pero construye dinámicamente parámetros que enfatizan el mercado, la industria y el contexto geográfico.
• executeSearch: envía la consulta construida a Elasticsearch usando una plantilla de búsqueda y recupera los documentos de startups correspondientes.
• visualizarResultados: formatea los resultados finales en un resumen claro y legible que muestre atributos clave de la startup, como financiación, industria e ingresos.

Este flujo incluye una ramificación condicional, que funciona como una declaración “si” que determina si se debe usar la ruta de búsqueda de inversión o de mercado según la entrada del usuario. Esta lógica de decisión, impulsada por el LLM, hace que el flujo de trabajo sea adaptativo y consciente del contexto, un mecanismo que exploraremos con más detalle en las siguientes secciones.

Estado de LangGraph

Antes de ver cada node individualmente, necesitamos entender cómo se comunican y comparten datos. Para ello, LangGraph nos permite definir el estado del flujo de trabajo. Esto define el estado compartido que se pasará entre los nodes.

El estado actúa como un contenedor compartido que almacena datos intermedios a lo largo del flujo de trabajo: comienza con la consulta en lenguaje natural del usuario, luego guarda la estrategia de búsqueda seleccionada, los parámetros preparados para Elasticsearch, los resultados de búsqueda recuperados y, finalmente, la salida formateada.

Esta estructura permite que cada node lea y actualice el estado, asegurando un flujo coherente de información desde la entrada del usuario hasta la visualización final.

const VCState = Annotation.Root({
  input: Annotation(), // User's natural language query
  searchStrategy: Annotation(), // Search strategy chosen by LLM
  searchParams: Annotation(), // Prepared search parameters
  results: Annotation(), // Search results
  final: Annotation(), // Final formatted response
});

Configure la aplicación

Todo el código de esta sección se puede encontrar en el repositorio elasticsearch-labs.

Abra un terminal en la carpeta donde estará la app e inicialice una aplicación Node.js con el comando:

npm init -y

Ahora podemos instalar las dependencias necesarias para este proyecto:

npm install @elastic/elasticsearch @langchain/langgraph @langchain/openai @langchain/core dotenv zod && npm install --save-dev @types/node tsx typescript

• @elastic/elasticsearch: nos ayuda a gestionar las solicitudes de Elasticsearch, como la ingesta y la recuperación de datos.
• @langchain/langgraph: Dependencia de JS para proporcionar todas las herramientas de LangGraph.
• @langchain/openai: cliente de OpenAI LLM para LangChain.
• @langchain/core: proporciona los bloques fundamentales del núcleo para las apps de LangChain, incluidas las plantillas de prompts.
• dotenv: dependencia necesaria para usar variables de entorno en JavaScript.
• zod: dependencia para escribir datos.

@types/node tsx typescript nos permite escribir y ejecutar código TypeScript.

Ahora crea los siguientes archivos:

• elasticsearchSetup.ts: creará los mapping de índice, cargará el conjunto de datos desde un archivo JSON e ingerirá los datos en Elasticsearch.
• main.ts: incluirá la aplicación LangGraph.
• .env: archivo para almacenar las variables de entorno

En el archivo .env, agreguemos las siguientes variables de entorno:

ELASTICSEARCH_ENDPOINT="your-endpoint-here"
ELASTICSEARCH_API_KEY="your-key-here"
OPENAI_API_KEY="your-key-here"

La clave API de OpenAPI no se usará directamente en el código; en su lugar, se usará internamente por la biblioteca @langchain/openai.

Toda la lógica relacionada con la creación de mapping, la creación de plantillas de búsqueda y la ingesta de sets de datos se encuentra en el archivo elasticsearchSetup.ts. En los próximos pasos, nos centraremos en el archivo main.ts . Además, puedes consultar los sets de datos para entender mejor cómo se ven los datos en el dataset.json.

Aplicación LangGraph

En el archivo main.ts, vamos a importar algunas dependencias necesarias para consolidar la aplicación LangGraph. En este archivo, también debes incluir las funciones del node y la declaración de estado. La declaración del grafo se realizará en un método main en los siguientes pasos. El archivo elasticsearchSetup.ts contendrá ayudantes de Elasticsearch que vamos a usar dentro de los nodes en los próximos pasos.

import { writeFileSync } from "node:fs";
import { StateGraph, Annotation, START, END } from "@langchain/langgraph";
import { ChatOpenAI } from "@langchain/openai";
import { z } from "zod";
import {
  esClient,
  ingestDocuments,
  createSearchTemplates,
  INDEX_NAME,
  INVESTMENT_FOCUSED_TEMPLATE,
  MARKET_FOCUSED_TEMPLATE,
  createIndex,
} from "./elasticsearchSetup.js";

const llm = new ChatOpenAI({ model: "gpt-4o-mini" });

Como se mencionó anteriormente, el cliente LLM se utilizará para generar los parámetros de la plantilla de búsqueda de Elasticsearch basados en la pregunta del usuario.

async function saveGraphImage(app: any): Promise {
  try {
    const drawableGraph = app.getGraph();
    const image = await drawableGraph.drawMermaidPng();
    const arrayBuffer = await image.arrayBuffer();

    const filePath = "./workflow_graph.png";
    writeFileSync(filePath, new Uint8Array(arrayBuffer));
    console.log(`📊 Workflow graph saved as: ${filePath}`);
  } catch (error: any) {
    console.log("⚠️  Could not save graph image:", error.message);
  }
}

El método anterior genera la imagen del grafo en formato png y utiliza la API de Mermaid.INK en segundo plano. Esto es útil si deseas ver cómo interactúan los nodes de la app con una visualización estilizada.

Nodes LangGraph

Ahora veamos cada node en detalle:

node decideSearchStrategy

El decideSearchStrategy node analiza la entrada del usuario y determina si realizar una búsqueda centrada en la inversión o en el mercado. Utiliza un LLM con un esquema de salida estructurado (definido con Zod) para clasificar el tipo de consulta. Antes de tomar la decisión, recupera los filtros disponibles del índice mediante una agregación, lo que garantiza que el modelo cuente con información actualizada sobre sectores, ubicaciones y datos de financiación.

Para extraer los posibles valores de los filtros y enviarlos al LLM, usemos una consulta de agregación para obtenerlos directamente del índice de Elasticsearch. Esta lógica se encuentra en un método llamado getAvailableFilters:

async function getAvailableFilters() {
  try {
    const response = await esClient.search({
      index: INDEX_NAME,
      size: 0,
      aggs: {
        industries: {
          terms: { field: "industry", size: 100 },
        },
        locations: {
          terms: { field: "location", size: 100 },
        },
        funding_stages: {
          terms: { field: "funding_stage", size: 20 },
        },
        business_models: {
          terms: { field: "business_model", size: 10 },
        },
        lead_investors: {
          terms: { field: "lead_investor", size: 100 },
        },
        funding_amount_stats: {
          stats: { field: "funding_amount" },
        },
      },
    });

    return response.aggregations;
  } catch (error) {
    console.error("❌ Error getting available filters:", error);
    return {};
  }
}

Con la consulta de agregación anterior, tenemos los siguientes resultados:

{
  "industries": {
    "doc_count_error_upper_bound": 0,
    "sum_other_doc_count": 0,
    "buckets": [
      {
        "key": "logistics",
        "doc_count": 5
      },
      ...
    ]
  },
  "locations": {
    "doc_count_error_upper_bound": 0,
    "sum_other_doc_count": 0,
    "buckets": [
      {
        "key": "San Francisco, CA",
        "doc_count": 4
      },
      {
        "key": "New York, NY",
        "doc_count": 3
      },
      ...
    ]
  },
  "funding_stages": {
    "doc_count_error_upper_bound": 0,
    "sum_other_doc_count": 0,
    "buckets": [
      {
        "key": "Series A",
        "doc_count": 8
      },
      ...
    ]
  },
  "business_models": {
    "doc_count_error_upper_bound": 0,
    "sum_other_doc_count": 0,
    "buckets": [
      {
        "key": "B2B",
        "doc_count": 13
      },
      ...
    ]
  },
  "lead_investors": {
    "doc_count_error_upper_bound": 0,
    "sum_other_doc_count": 0,
    "buckets": [
      {
        "key": "Battery Ventures",
        "doc_count": 1
      },
      {
        "key": "Benchmark Capital",
        "doc_count": 1
      },
      ...
    ]
  },
  "funding_amount_stats": {
    "count": 20,
    "min": 4500000,
    "max": 35000000,
    "avg": 14075000,
    "sum": 281500000
  }
}

Vea todos los resultados aquí.

Para ambas estrategias, utilizaremos la búsqueda híbrida para detectar tanto la parte estructurada de la pregunta (filtros) como las partes más subjetivas (semántica). A continuación se muestra un ejemplo de ambas consultas utilizando plantillas de búsqueda:

await esClient.putScript({
      id: INVESTMENT_FOCUSED_TEMPLATE,
      script: {
        lang: "mustache",
        source: `{
          "size": 5,
          "retriever": {
            "rrf": {
              "retrievers": [
                {
                  "standard": {
                    "query": {
                      "semantic": {
                        "field": "semantic_field",
                        "query": "{{query_text}}"
                      }
                    }
                  }
                },
                {
                  "standard": {
                    "query": {
                      "bool": {
                        "filter": [
                          {"terms": {"funding_stage": {{#join}}{{#toJson}}funding_stage{{/toJson}}{{/join}}}},
                          {"range": {"funding_amount": {"gte": {{funding_amount_gte}}{{#funding_amount_lte}},"lte": {{funding_amount_lte}}{{/funding_amount_lte}}}}},
                          {"terms": {"lead_investor": {{#join}}{{#toJson}}lead_investor{{/toJson}}{{/join}}}},
                          {"range": {"monthly_revenue": {"gte": {{monthly_revenue_gte}}{{#monthly_revenue_lte}},"lte": {{monthly_revenue_lte}}{{/monthly_revenue_lte}}}}}
                        ]
                      }
                    }
                  }
                }
              ],
              "rank_window_size": 100,
              "rank_constant": 20
            }
          }
        }`,
      },
    });

Vea las consultas detalladas en el archivo elasticsearchSetup.ts . En el siguiente node, se decidirá cuál de las dos consultas se empleará:

// Node 1: Decide search strategy using LLM
async function decideSearchStrategy(state: typeof VCState.State) {
  // Zod schema for specialized search strategy decision
  const SearchDecisionSchema = z.object({
    search_type: z
      .enum(["investment_focused", "market_focused"])
      .describe("Type of specialized search strategy to use"),
    reasoning: z
      .string()
      .describe("Brief explanation of why this search strategy was chosen"),
  });

  const decisionLLM = llm.withStructuredOutput(SearchDecisionSchema);

  // Get dynamic filters from Elasticsearch
  const availableFilters = await getAvailableFilters();

  const prompt = `Query: "${state.input}"
    Available filters: ${JSON.stringify(availableFilters, null, 2)}

    Choose between two specialized search strategies:
    
    - investment_focused: For queries about funding stages, funding amounts, monthly revenue, lead investors, financial performance
    
    - market_focused: For queries about industries, locations, business models, market segments, geographic markets
    
    Analyze the query intent and choose the most appropriate strategy.
  `;

  try {
    const result = await decisionLLM.invoke(prompt);
    console.log(
      `🤔 Search strategy: ${result.search_type} - ${result.reasoning}`
    );

    return {
      searchStrategy: result.search_type,
    };
  } catch (error: any) {
    console.error("❌ Error in decideSearchStrategy:", error.message);
    return {
      searchStrategy: "investment_focused",
    };
  }
}

Nodes prepareInvestmentSearch y prepareMarketSearch

Ambos nodos emplean una función auxiliar compartida, extractFilterValues, que aprovecha el LLM para identificar los filtros relevantes mencionados en la entrada del usuario, como la industria, la ubicación, la etapa de financiación, el modelo de negocio, etc. Estamos utilizando este esquema para crear nuestra plantilla de búsqueda.

// Extract all possible filter values from user input
async function extractFilterValues(input: string) {
  const FilterValuesSchema = z.object({
    // Investment-focused filters
    funding_stage: z
      .array(z.string())
      .default([])
      .describe("Funding stage values mentioned in query"),
    funding_amount_gte: z
      .number()
      .default(0)
      .describe("Minimum funding amount in USD"),
    funding_amount_lte: z
      .number()
      .default(100000000)
      .describe("Maximum funding amount in USD"),
    lead_investor: z
      .array(z.string())
      .default([])
      .describe("Lead investor values mentioned in query"),
    monthly_revenue_gte: z
      .number()
      .default(0)
      .describe("Minimum monthly revenue in USD"),
    monthly_revenue_lte: z
      .number()
      .default(10000000)
      .describe("Maximum monthly revenue in USD"),
    industry: z
      .array(z.string())
      .default([])
      .describe("Industry values mentioned in query"),
    location: z
      .array(z.string())
      .default([])
      .describe("Location values mentioned in query"),
    business_model: z
      .array(z.string())
      .default([])
      .describe("Business model values mentioned in query"),
  });

  const extractorLLM = llm.withStructuredOutput(FilterValuesSchema);
  const availableFilters = await getAvailableFilters();

  const extractPrompt = `Extract ALL relevant filter values from: "${input}"
    Available options: ${JSON.stringify(availableFilters, null, 2)}
    Extract only values explicitly mentioned in the query. Leave fields empty if not mentioned.`;

  return await extractorLLM.invoke(extractPrompt);
}

Según de la intención detectada, el flujo de trabajo selecciona una de dos rutas:

prepareInvestmentSearch: desarrolla parámetros de búsqueda orientados a la financiación, incluyendo la etapa de financiación, el importe de la inversión, el inversionista y la información de renovación. Puedes encontrar la plantilla completa de consulta en el archivo elasticsearchSetup.ts :

// Node 2A: Prepare Investment-Focused Search Parameters 
async function prepareInvestmentSearch(state: typeof VCState.State) {
  console.log(
    "💰 Preparing INVESTMENT-FOCUSED search parameters with financial emphasis..."
  );

  try {
    // Extract all filter values from input
    const values = await extractFilterValues(state.input);

    let searchParams: any = {
      template_id: INVESTMENT_FOCUSED_TEMPLATE,
      query_text: state.input,
      ...values,
    };

    return { searchParams };
  } catch (error) {
    console.error("❌ Error preparing investment-focused params:", error);
    return {
      searchParams: {},
    };
  }
}

prepareMarketSearch: crea parámetros orientados al mercado centrados en industrias, geografías y modelos de negocio. Ver la consulta completa en el archivo elasticsearchSetup.ts:

// Node 2B: Prepare Market-Focused Search Parameters
async function prepareMarketSearch(state: typeof VCState.State) {
  console.log(
    "🔍 Preparing MARKET-FOCUSED search parameters with market emphasis..."
  );

  try {
    // Extract all filter values from input
    const values = await extractFilterValues(state.input);

    let searchParams: any = {
      template_id: MARKET_FOCUSED_TEMPLATE,
      query_text: state.input,
      ...values,
    };

    return { searchParams };
  } catch (error) {
    console.error("❌ Error preparing market-focused params:", error);
    return {};
  }
}

Node executeSearch

Este node toma los parámetros de búsqueda generados del estado y los envía primero a Elasticsearch, usando la _render API para visualizar la consulta con fines de depuración, y luego envía una petición para recuperar los resultados.

// Node 3: Execute Search
async function executeSearch(state: typeof VCState.State) {
  const { searchParams } = state;

  try {
    // getting formed query from template for debugging
    const renderedTemplate = await esClient.renderSearchTemplate({
      id: searchParams.template_id,
      params: searchParams,
    });

    console.log(
      "📋 Complete query:",
      JSON.stringify(renderedTemplate.template_output, null, 2)
    );

    const results = await esClient.searchTemplate({
      index: INDEX_NAME,
      id: searchParams.template_id,
      params: searchParams,
    });

    return {
      results: results.hits.hits.map((hit: any) => hit._source),
    };
  } catch (error: any) {
    console.error(`❌ ${state.searchParams.search_type} search error:`, error);
    return { results: [] };
  }
}

node visualizarResultados

Finalmente, este nodo muestra los resultados de Elasticsearch.

// Node 4: Visualize results
async function visualizeResults(state: typeof VCState.State) {
  const results = state.results || [];

  let formattedResults = `🎯 Found ${results.length} startups matching your criteria:\n\n`;

  results.forEach((startup: any, index: number) => {
    formattedResults += `${index + 1}. **${startup.company_name}**\n`;
    formattedResults += `   📍 ${startup.location} | 🏢 ${startup.industry} | 💼 ${startup.business_model}\n`;
    formattedResults += `   💰 ${startup.funding_stage} - $${(
      startup.funding_amount / 1000000
    ).toFixed(1)}M\n`;
    formattedResults += `   👥 ${startup.employee_count} employees | 📈 $${(
      startup.monthly_revenue / 1000
    ).toFixed(0)}K MRR\n`;
    formattedResults += `   🏦 Lead: ${startup.lead_investor}\n`;
    formattedResults += `   📝 ${startup.description}\n\n`;
  });

  return {
    final: formattedResults,
  };
}

Programáticamente, todo el grafo se ve así:

  const workflow = new StateGraph(VCState)
    // Register nodes - these are the processing functions
    .addNode("decideStrategy", decideSearchStrategy)
    .addNode("prepareInvestment", prepareInvestmentSearch)
    .addNode("prepareMarket", prepareMarketSearch)
    .addNode("executeSearch", executeSearch)
    .addNode("visualizeResults", visualizeResults)
    // Define execution flow with conditional branching
    .addEdge(START, "decideStrategy") // Start with strategy decision
    .addConditionalEdges(
      "decideStrategy",
      (state: typeof VCState.State) => state.searchStrategy, // Conditional function
      {
        investment_focused: "prepareInvestment", // If investment focused -> RRF template preparation
        market_focused: "prepareMarket", // If market focused -> dynamic query preparation
      }
    )
    .addEdge("prepareInvestment", "executeSearch") // Investment prep -> execute
    .addEdge("prepareMarket", "executeSearch") // Market prep -> execute
    .addEdge("executeSearch", "visualizeResults") // Execute -> visualize
    .addEdge("visualizeResults", END); // End workflow

Como puede ver, tenemos una aplicación condicional donde la aplicación decide qué “ruta” o node ejecutar a continuación. Esta característica es útil cuando los flujos de trabajo necesitan lógica de ramificación, como elegir entre múltiples herramientas o incluir un paso con intervención de una persona.

Con las características básicas del núcleo de LangGraph entendidas, podemos configurar la aplicación donde se ejecutará el código:

Juntando todo en un flujo de trabajo main, aquí declaramos el grafo con todos los elementos bajo la variable flujo de trabajo:

async function main() {
  await createIndex();
  await createSearchTemplates();
  await ingestDocuments();

  // Create the workflow graph with shared state
  const workflow = new StateGraph(VCState)
    // Register nodes - these are the processing functions
    .addNode("decideStrategy", decideSearchStrategy)
    .addNode("prepareInvestment", prepareInvestmentSearch)
    .addNode("prepareMarket", prepareMarketSearch)
    .addNode("executeSearch", executeSearch)
    .addNode("visualizeResults", visualizeResults)
    // Define execution flow with conditional branching
    .addEdge(START, "decideStrategy") // Start with strategy decision
    .addConditionalEdges(
      "decideStrategy",
      (state: typeof VCState.State) => state.searchStrategy, // Conditional function
      {
        investment_focused: "prepareInvestment", // If investment focused -> RRF template preparation
        market_focused: "prepareMarket", // If market focused -> dynamic query preparation
      }
    )
    .addEdge("prepareInvestment", "executeSearch") // Investment prep -> execute
    .addEdge("prepareMarket", "executeSearch") // Market prep -> execute
    .addEdge("executeSearch", "visualizeResults") // Execute -> visualize
    .addEdge("visualizeResults", END); // End workflow


  const app = workflow.compile();

  await saveGraphImage(app);

  const query =
    "Find startups with Series A or Series B funding between $8M-$25M and monthly revenue above $500K";

  const marketResult = await app.invoke({ input: query });
  console.log(marketResult.final);
}

La variable de consulta simula la entrada del usuario introducida en una barra de búsqueda hipotética:

De la frase en lenguaje natural “Encuentra startups con financiamiento de Serie A o Serie B entre $8M y $25M, e ingresos mensuales superiores a $500K” se extraerán todos los filtros.

Finalmente, invoca el método principal:

main().catch(console.error);

Resultados

🔍 Checking if index exists...
🏗️ Creating index...
✅ Index created successfully!
Ingesting documents...
✅ Documents ingested successfully!
✅ Investment-focused template created successfully!
✅ Market-focused template created successfully!

📊 Workflow graph saved as: ./workflow_graph.png

🔍 Query: "Find startups with Series A or Series B funding between $8M-$25M and monthly revenue above $500K"

🤔 Search strategy: investment_focused - The query specifically seeks profitable fintech startups with defined funding amounts and high monthly revenue, which aligns closely with financial performance metrics and investment-related criteria.

💰 Preparing INVESTMENT-FOCUSED search parameters with financial emphasis...

📋 Complete query: {
  "size": 5,
  "retriever": {
    "rrf": {
      "retrievers": [
        {
          "standard": {
            "query": {
              "semantic": {
                "field": "semantic_field",
                "query": "Find startups with Series A or Series B funding between $8M-$25M and monthly revenue above $500K"
              }
            }
          }
        },
        {
          "standard": {
            "query": {
              "bool": {
                "filter": [
                  {
                    "terms": {
                      "funding_stage": [
                        "Series A",
                        "Series B"
                      ]
                    }
                  },
                  {
                    "range": {
                      "funding_amount": {
                        "gte": 8000000,
                        "lte": 25000000
                      }
                    }
                  },
                  {
                    "terms": {
                      "lead_investor": []
                    }
                  },
                  {
                    "range": {
                      "monthly_revenue": {
                        "gte": 500000,
                        "lte": 0
                      }
                    }
                  }
                ]
              }
            }
          }
        }
      ],
      "rank_window_size": 100,
      "rank_constant": 20
    }
  }
}
🎯 Found 5 startups matching your criteria:

1. **TechFlow**
   📍 San Francisco, CA | 🏢 logistics | 💼 B2B
   💰 Series A - $8.0M
   👥 45 employees | 📈 $500K MRR
   🏦 Lead: Sequoia Capital
   📝 TechFlow optimizes supply chain operations using AI-powered route optimization and real-time tracking. Founded in 2023, shows remarkable growth with $500K monthly revenue.

2. **DataViz**
   📍 New York, NY | 🏢 enterprise software | 💼 B2B
   💰 Series A - $10.0M
   👥 42 employees | 📈 $450K MRR
   🏦 Lead: Battery Ventures
   📝 DataViz creates intuitive data visualization tools for enterprise customers. No-code platform allows business users to create dashboards without technical expertise.

3. **FinanceAI**
   📍 San Francisco, CA | 🏢 fintech | 💼 B2C
   💰 Series C - $25.0M
   👥 120 employees | 📈 $1200K MRR
   🏦 Lead: Tiger Global Management
   📝 FinanceAI provides AI-powered investment advisory services to retail investors. Uses machine learning to analyze market trends with over 100,000 active users.

4. **UrbanMobility**
   📍 New York, NY | 🏢 logistics | 💼 B2B2C
   💰 Series B - $15.0M
   👥 78 employees | 📈 $750K MRR
   🏦 Lead: Kleiner Perkins
   📝 UrbanMobility revolutionizes urban transportation through autonomous delivery drones and smart logistics hubs. Partners with major retailers for same-day delivery across Manhattan and Brooklyn.

5. **HealthTech Solutions**
   📍 Boston, MA | 🏢 healthcare | 💼 B2B
   💰 Series B - $18.0M
   👥 95 employees | 📈 $900K MRR
   🏦 Lead: General Catalyst
   📝 HealthTech Solutions develops medical devices and software for remote patient monitoring. Comprehensive telehealth platform reducing hospital readmissions by 30%.

✨  Done in 18.80s.

Para la entrada enviada, la aplicación elige la ruta centrada en la inversión y, como resultado, podemos ver la consulta de Elasticsearch generada por el flujo de trabajo de LangGraph, que extrae los valores y los rangos de la entrada del usuario. También podemos ver la consulta enviada a Elasticsearch con los valores extraídos aplicados y, finalmente, los resultados formateados por el node visualizeResults con los resultados.

Ahora vamos a probar el node centrado en el mercado usando la consulta “Encuentre startups de fintech y salud en San Francisco, Nueva York o Boston”:

...

🔍 Query: Find fintech and healthcare startups in San Francisco, New York, or Boston

🤔 Search strategy: market_focused - The query is focused on finding fintech startups in San Francisco that are disrupting traditional banking and payment systems, which pertains to specific industries (fintech) and locations (San Francisco). Thus, a market-focused strategy is more appropriate.

🔍 Preparing MARKET-FOCUSED search parameters with market emphasis...

📋 Complete query: {
  "size": 5,
  "retriever": {
    "rrf": {
      "retrievers": [
        {
          "standard": {
            "query": {
              "semantic": {
                "field": "semantic_field",
                "query": "Find fintech and healthcare startups in San Francisco, New York, or Boston"
              }
            }
          }
        },
        {
          "standard": {
            "query": {
              "bool": {
                "filter": [
                  {
                    "terms": {
                      "industry": [
                        "fintech",
                        "healthcare"
                      ]
                    }
                  },
                  {
                    "terms": {
                      "location": [
                        "San Francisco, CA",
                        "New York, NY",
                        "Boston, MA"
                      ]
                    }
                  },
                  {
                    "terms": {
                      "business_model": []
                    }
                  }
                ]
              }
            }
          }
        }
      ],
      "rank_window_size": 50,
      "rank_constant": 10
    }
  }
}
🎯 Found 5 startups matching your criteria:

1. **FinanceAI**
   📍 San Francisco, CA | 🏢 fintech | 💼 B2C
   💰 Series C - $25.0M
   👥 120 employees | 📈 $1200K MRR
   🏦 Lead: Tiger Global Management
   📝 FinanceAI provides AI-powered investment advisory services to retail investors. Uses machine learning to analyze market trends with over 100,000 active users.

2. **CryptoWallet**
   📍 Miami, FL | 🏢 fintech | 💼 B2C
   💰 Series B - $16.0M
   👥 73 employees | 📈 $820K MRR
   🏦 Lead: Coinbase Ventures
   📝 CryptoWallet provides secure digital wallet solutions for cryptocurrency trading and storage. Multi-chain support with enterprise-grade security features.

...

✨  Done in 7.41s.

Aprendizajes

Durante el proceso de escritura aprendí:

• Debemos mostrar al LLM los valores exactos de los filtros; de lo contrario, dependemos de que el usuario escriba los valores exactos de las cosas. Para baja cardinalidad, este enfoque está bien, pero cuando la cardinalidad es alta, necesitamos algún mecanismo para filtrar los resultados.
• El uso de plantillas de búsqueda hace que los resultados sean mucho más consistentes que dejar que el LLM escriba la consulta de Elasticsearch, y también es más rápido.
• Los bordes condicionales son un mecanismo potente para crear aplicaciones con múltiples variantes y rutas de ramificación.
• La salida estructurada es extremadamente útil cuando se genera información con LLM porque impone respuestas predecibles y de tipo seguro. Esto mejora la confiabilidad y reduce las interpretaciones incorrectas de los prompts.

La combinación de búsqueda semántica y estructurada a través de la recuperación híbrida produce resultados mejores y más relevantes, equilibrando la precisión y la comprensión del contexto.

Conclusión

En este ejemplo, combinamos LangGraph.js con Elasticsearch para crear un flujo de trabajo dinámico capaz de interpretar consultas en lenguaje natural y decidir entre estrategias de búsqueda financieras u orientadas al mercado. Este enfoque reduce la complejidad de la creación de consultas manuales, al tiempo que mejora la flexibilidad y la precisión para los analistas de capital de riesgo.

¿Qué son los controles variables?

Si has trabajado antes con los dashboards de Kibana, probablemente conozcas nuestros controles clásicos de dashboard: esos prácticos menús desplegables que muestran valores de tus datos para que puedas aplicar filtros con un par de clics.

A simple vista, los controles variables son parecidos , pero tienen un giro ingenioso: en lugar de filtrar automáticamente cada panel en tu dashboard, pueden conectarse directamente a búsquedas ES|QL dentro de visualizaciones individuales.

Eso significa que tú decides dónde se aplica cada control. Y aún más, puedes usarlos para todo tipo de trucos creativos, como ajustar intervalos de tiempo, cambiar campos de desglose o modificar parámetros de visualización en el momento. Básicamente, ofrecen a tus dashboards una experiencia realmente interactiva, lo que permite obtener tu información de manera más rápida y fácil.

Casos de uso para controles variables

Muy bien, los controles variables parecen útiles, pero ¿para qué sirven realmente? A continuación se muestran algunos ejemplos de cómo mejorar tus dashboards:

Filtrar visualizaciones seleccionadas.

¿Quieres filtrar algunas visualizaciones sin cambiar otras? Los controles de variables te permiten hacer exactamente eso. Selecciona los paneles a los que deseas responder y conéctalos en las búsquedas de ES|QL detrás de tus visualizaciones.

Selecciona diferentes intervalos de tiempo

Otorga a tus usuarios el poder de cambiar entre “5 minutos”, “1 hora”, “1 día” o cualquier cubeta de tiempo que tenga sentido. Crea un control variable con intervalos predefinidos y conéctalo a tu búsqueda de series temporales.

Cambiar funciones

En lugar de crear múltiples gráficos para cada operación, permite que los usuarios del dashboard elijan si quieren ver el máximo, el promedio, diferentes percentiles o cualquier otro agregador.

Agrupar por diferentes campos

A veces necesitas desglosar los datos por diferentes dimensiones durante una investigación. Con controles variables, puedes definir múltiples campos “agrupar por” y permitir que los usuarios del dashboard elijan cuál les permite descubrir su información.

¿Cómo puedes crearlos?

La manera más sencilla (y probablemente más amena) de crear un control de variable es directamente desde el editor de búsquedas ES|QL en tu visualización. Simplemente comienza a escribir tu búsqueda, usa el menú de autocompletado y Kibana configurará el control de una manera que te resulte útil.

Pero si prefieres empezar desde la variable en sí, también puedes ir a: Agregar panel → Controles → Control de variables y agregar la variable a tus visualizaciones después de crear el control.

Ejemplo 1: Control de filtrado con selección de múltiples valores.

1. Elija una visualización que se realice a partir de una búsqueda ES|QL y haga clic en “Crear control” dentro de la cláusula WHERE.

2. Serás redirigido automáticamente al elemento flotante de creación de variables, donde se seleccionará el tipo “Valores de una búsqueda” para ti, y el nombre de la variable ya estará previamente completado. Recuerda que el nombre de un control siempre debe comenzar con “?...” para que funcione en la búsqueda de visualización.

Normalmente necesitarás una búsqueda como esta para obtener los valores de un campo y actualizarlos según el rango de tiempo seleccionado en el dashboard:

FROM 
| WHERE @timestamp <=?_tend and @timestamp >?_tstart
| STATS BY 

3. Al guardar el control, lo verás aparecer en la parte superior del dashboard y tu búsqueda de visualización se actualizará con el nombre del control variable.

4. Si deseas agregar una selección de valores múltiples al control, debes usar la función MV_CONTAINS en la búsqueda y seleccionar “Permitir selecciones múltiples” durante la creación del control en el paso 2 (disponible desde la versión 9.3).

Ejemplo 2: Control de intervalos de tiempo.

Si estás creando una serie temporal, puedes agregar fácilmente un control variable en el intervalo de histograma de fecha:

1. Cuando escribas una búsqueda ES|QL para tu serie temporal, haz clic en “Crear control”. Al construir una variable para intervalos, es mejor usar TBUCKET en lugar de BUCKET para que acepte intervalos más legibles como “1 hora”, “1 día”, etc. Pronto habrá una opción automática para TBUCKET que se adaptará automáticamente a los intervalos de tiempo.

2. Define los intervalos para completar las opciones en el menú desplegable.

3. Selecciona diferentes intervalos en el menú desplegable y observa cómo cambia tu visualización.

Ejemplo 3: variables para funciones

1. Crea una variable usando el tipo de control “Valores estáticos” y agrega nombres de funciones a los valores de tu menú desplegable. Es importante usar un nombre para la variable que comience con “??...” para reemplazar funciones.

2. Incluye el nombre de la variable en la búsqueda ES|QL.

Ejemplo 4: variables para campos

1. Puedes usar el tipo de control “Valores estáticos” y escribir los nombres de los campos que desees. Es importante usar un nombre de variable que comience con “??...” para que funcione en los campos.

2. Crea una referencia a la variable donde la necesites en la búsqueda de la visualización.

Controles de variables en Discover

Los controles variables no son solo una característica del dashboard: también están disponibles directamente en el editor de ES|QL en Discover. Puede crear controles para obtener una experiencia de exploración de datos más rápida en Discover, llevarlos al dashboard y viceversa.

Detalles técnicos

A estas alturas, probablemente hayas notado que los controles de variables incluyen algunas reglas, como a qué partes de una búsqueda pueden hacer referencia y los prefijos de nombres que necesitas usar (“?...” para valores y “??...” para campos o funciones). Eso se debe a que las variables no son simplemente reemplazos de texto que ocurren en el cliente. En realidad, son ciudadanos de primera clase en el propio lenguaje de búsquedas (conocidos como parámetros en ES|QL).

Este diseño ofrece grandes ventajas. Por un lado, Kibana puede entender el contexto de cada variable, lo que nos permite generar y completar previamente, de manera automática, su configuración. Además, es mucho más seguro: debido a que el lenguaje valida estrictamente las entradas de variables, previene las inyecciones maliciosas y genera errores fácilmente, si algo parece incorrecto. Asimismo, mejora el rendimiento y la estabilidad al trasladar la compleja validación y el manejo de errores al servidor en lugar de al cliente. Recordatorio sobre el rendimiento: una de las mejores prácticas es crear variables que incluyan búsquedas rápidas, ya que se cargan antes que el dashboard, por lo que las búsquedas lentas pueden afectar al rendimiento de todo el dashboard.

Por supuesto, esta arquitectura también tiene algunas limitaciones—por ahora. Las variables aún no admiten una opción “Cualquiera” para filtrar, y actualmente no se pueden usar con ciertos operadores como LIKE o FROM (para cambiar fuentes de datos). ¿La buena noticia? Estamos trabajando activamente para agregar estas funciones.

Qué depara el futuro para los controles

¡Este no es el final! Algunas de las mejoras importantes incluyen:

✨ La capacidad de colocar controles en cualquier lugar del dashboard

✨ Encadenar tus controles, lo que significa que la salida de un control se convierte en la entrada para el siguiente

✨ Mejores opciones de selección como la opción “Cualquiera” para variables.

✨ Nuevos tipos de control (control de tipo búsqueda y variables para tus fuentes de datos)

✨ Y otras mejoras en la experiencia del usuario que han estado solicitando, como el filtro previo de controles normales.

Si tienes ideas o comentarios, nos encantaría saber de ti.

Resumen

Primero, pongámonos al día. Elasticsearch se consolidó como una poderosa base de datos vectorial, que ofrece un amplio conjunto de características y un sólido rendimiento para la búsqueda de similitudes a gran escala. Con capacidades como la cuantificación escalar, Better Binary Quantization (BBQ), operaciones vectoriales SIMD y algoritmos más eficientes en disco como DiskBBQ, ya ofrece opciones eficientes y flexibles para gestionar cargas de trabajo vectoriales.

Al integrar NVIDIA cuVS como un módulo invocable para tareas de búsqueda vectorial, nuestro objetivo es ofrecer beneficios significativos en el rendimiento y la eficiencia de la indexación vectorial para soportar mejor las cargas de trabajo vectoriales a gran escala.

El desafío

Uno de los mayores desafíos al construir una base de datos vectorial de alto rendimiento es construir el índice vectorial: el grafo HNSW. La construcción de índices se ve dominada con rapidez por millones o incluso miles de millones de operaciones aritméticas a medida que cada vector se compara con muchos otros. Además, las operaciones del ciclo de vida del índice, como la compactación y las fusiones, pueden aumentar aún más la sobrecarga total de cálculo de la indexación. A medida que los volúmenes de datos y las incrustaciones vectoriales asociadas crecen de manera exponencial, las GPU de cómputo acelerado, diseñadas para el paralelismo masivo y las matemáticas de alto rendimiento, se posicionan idealmente para manejar estas cargas de trabajo.

Ingresa al plugin Elasticsearch-GPU

NVIDIA cuVS es una biblioteca open source de CUDA-X para la búsqueda vectorial acelerada por GPU y la agrupación de datos, que permite una rápida construcción de índices y recuperación de incrustaciones para cargas de trabajo de AI y de sistemas de recomendación.

Elasticsearch utiliza cuVS a través de cuvs-java, una biblioteca open source desarrollada por la comunidad y que mantiene NVIDIA. La biblioteca cuvs-java es ligera, se basa en la API C de cuVS y usa la función externa del Proyecto Panamá para exponer las características de cuVS de una manera idiomática en Java, al tiempo que es moderna y presenta un alto rendimiento.

La biblioteca cuvs-java está integrada en un nuevo plugin de Elasticsearch; por lo tanto, la indexación vectorial en la GPU puede ocurrir en el mismo nodo y proceso de Elasticsearch, sin la necesidad de provisionar ningún código o hardware externo. Durante la construcción del índice, si se instala la biblioteca cuVS y hay una GPU presente y configurada, Elasticsearch usará la GPU para acelerar el proceso de indexación vectorial. Los vectores se asignan a la GPU, que construye un grafo CAGRA. Este grafo se convierte entonces al formato HNSW, y hace que esté disponible de inmediato para la búsqueda vectorial en la CPU. El formato final del grafo construido es el mismo que el que se construiría en la CPU; esto permite a Elasticsearch aprovechar las GPU para indexar vectores de alto rendimiento cuando el hardware subyacente lo admite, al tiempo que libera poder de la CPU para otras tareas (búsqueda simultánea, procesamiento de datos, etc.).

Aceleración en la generación de índices

Como parte de la integración de la aceleración de GPU en Elasticsearch, se realizaron varias mejoras en cuvs-java, centradas en la entrada/salida eficiente de datos y la invocación de funciones. Una mejora clave es el uso de cuVSMatrix para modelar vectores de forma transparente, ya sea que residan en la memoria heap de Java, fuera de la memoria heap o en la memoria de la GPU. Esto permite que los datos se muevan de manera eficiente entre la memoria y la GPU, lo que evita copias innecesarias de potencialmente miles de millones de vectores.

Gracias a esta abstracción subyacente de copia cero, tanto la transferencia a la memoria de la GPU como la recuperación del grafo se pueden realizar directamente. Durante la indexación, los vectores se almacenan primero en búfer en la memoria heap de Java, y luego se envían a la GPU para construir el grafo CAGRA. Después, el grafo se recupera de la GPU, se convierte al formato HNSW y se mantiene en el disco.

En el momento de la fusión, los vectores ya están almacenados en disco, sin pasar por la memoria heap de Java. Los archivos de índice se mapean en memoria, y los datos se transfieren directamente a la memoria de la GPU. El diseño también se adapta fácilmente a diferentes anchos de bits, como float32 o int8, y se extiende de forma natural a otros esquemas de cuantificación.

Redoble de tambores… entonces, ¿cómo se funciona?

Antes de entrar en los números, un poco de contexto es útil. La fusión de segmentos en Elasticsearch suele ejecutarse automáticamente en segundo plano durante la indexación, lo que dificulta hacer benchmarks de forma aislada. Para obtener resultados reproducibles, utilizamos la fusión forzosa para activar explícitamente la combinación de segmentos en un experimento controlado. Dado que la fusión forzosa hace las mismas operaciones de fusión subyacentes que la fusión en segundo plano, su rendimiento sirve como un indicador útil de las mejoras esperadas, aunque las ganancias exactas pueden diferir en las cargas de trabajo de indexación del mundo real.

Ahora, veamos los números.

Nuestros resultados iniciales de evaluaciones comparativas son muy prometedores. Ejecutamos la evaluación comparativa en una instancia de AWS g6.4xlarge con almacenamiento NVMe conectado a nivel local. Se configuró un único nodo de Elasticsearch para que use el número predeterminado y óptimo de subprocesos de indexación (8, uno por cada núcleo físico) y deshabilite la limitación de la fusión (que es menos aplicable con discos NVMe rápidos).

Para el conjunto de datos, utilizamos 2,6 millones de vectores con 1536 dimensiones del vector de pista de Rally de OpenAI, codificados como cadenas de texto base64 e indexados como float32 hnsw. En todos los escenarios, los grafos construidos alcanzan niveles de recuperación de hasta el 95 %. A continuación, presentamos nuestros hallazgos:

• Rendimiento de indexación: al trasladar la construcción de grafos a la GPU durante los vaciados de búferes en memoria, aumentamos el rendimiento en aproximadamente 12 veces.
• Fusión forzada: una vez que finaliza la indexación, la GPU continúa acelerando la fusión de segmentos, lo que acelera la fase de fusión forzada en alrededor de 7 veces.

• Uso de la CPU: descargar la construcción de grafos a la GPU reduce de manera significativa el uso promedio y máximo de la CPU. Los grafos a continuación ilustran el uso de la CPU durante la indexación y la fusión, y permiten ver cuánto menor es cuando estas operaciones se ejecutan en la GPU. Un menor uso de la CPU durante la indexación por GPU libera ciclos de CPU que pueden redirigirse para mejorar el rendimiento de la búsqueda.

• Recuperación: la precisión se mantiene prácticamente igual entre las ejecuciones de CPU y GPU, y el grafo construido por la GPU alcanza una recuperación un poco mayor.

Comparación en otra dimensión: el precio

La comparación anterior utilizaba intencionalmente hardware idéntico, y la única diferencia era si se usaba la GPU durante la indexación o no. Esa configuración es útil para aislar los efectos de la computación en bruto, pero también podemos analizar la comparación desde una perspectiva de costos.

A un precio horario similar al de la configuración acelerada por GPU, se puede provisionar una configuración de solo CPU con aproximadamente el doble de recursos comparables de CPU y memoria: 32 vCPUs (AMD EPYC) y 64 GB de RAM, lo que permite duplicar el número de hilos de indexación a 16.

Para mantener la comparación justa y consistente, ejecutamos este experimento solo de CPU en una instancia AWS g6.8xlarge, con la GPU explícitamente desactivada. Esto nos permitió mantener constantes todas las demás características del hardware mientras evaluábamos la compensación entre costo y rendimiento de la aceleración de GPU frente al indexado solo con CPU.

Como era de esperar, la instancia de CPU más potente sí muestra un mejor rendimiento en comparación con las evaluaciones comparativas de la sección anterior. Sin embargo, cuando comparamos esta instancia de CPU más potente con los resultados acelerados por GPU originales, la GPU aún ofrece beneficios sustanciales en cuanto al rendimiento: ~ 5 veces de mejora en el rendimiento de indexación y ~ 6 veces en la fusión forzada, todo ello mientras se construyen grafos que alcanzan niveles de recuperación de hasta un 95 %.

Conclusión

En escenarios completos, la aceleración por GPU con NVIDIA cuVS ofrece una mejora de casi 12 veces en el rendimiento de la indexación y una disminución de 7 veces en la latencia de fusión forzada, con un uso de CPU significativamente menor. Esto demuestra que la indexación vectorial y las cargas de trabajo de fusión se benefician de manera significativa de la aceleración por GPU. En una comparación ajustada por costos, la aceleración por GPU continúa mostrando beneficios sustanciales en cuanto al rendimiento, con alrededor de 5 veces más rendimiento de indexación y 6 veces más rapidez en las operaciones de fusión forzada.

La indexación vectorial acelerada por GPU tiene planificada hoy en día una vista previa técnica en Elasticsearch 9.3, cuyo lanzamiento está programado para principios de 2026.

Mantente atento a lo que viene.

A continuación, se muestran las características de Elasticsearch 9.2 que transformarán tus flujos de trabajo de análisis de datos con ES|QL.

Revolucionando la correlación de datos: Lookup Join más inteligente, rápido y flexible

El comando LOOKUP JOIN en ES|QL experimentó una transformación significativa en Elasticsearch 9.2, y se volvió mucho más eficiente y versátil. Lookup JOIN combina datos de la tabla de resultados de búsquedas ES|QL con registros coincidentes de un índice de modo de consulta especificado. Agrega campos del índice de búsqueda como nuevas columnas a la tabla de resultados en función de los valores coincidentes en el campo de combinación. Anteriormente, la unión de datos se limitaba a un solo campo y a una igualdad simple. ¡Ya no! Estas mejoras te permiten abordar escenarios complejos de correlación de datos con facilidad.

Las mejoras clave de Lookup Join incluyen:

• Uniones de múltiples campos: únete fácilmente a varios campos. Por ejemplo, para unir application_logs con service_registry en service_name, environment y version:

FROM application_logs
| LOOKUP JOIN service_registry ON service_name, environment, version

• Utilización de predicados de unión complejos con expresiones (vista previa técnica):

Ya no estás limitado a la igualdad simple. LOOKUP JOIN ahora permite especificar múltiples criterios de correlación e incorporar una variedad de operadores binarios, como ==, !=, <, >, <= y >=. Esto significa que puedes crear condiciones de unión muy matizadas, lo que te permite plantear preguntas mucho más complejas sobre tus datos.

Ejemplo 1: Búsqueda de métricas de aplicaciones con umbrales de SLA por servicio

FROM application_metrics
| LOOKUP JOIN sla_thresholds
      ON service_name == sla_service AND response_time > sla_response_time

Ejemplo 2: Esta búsqueda calcula el monto adeudado, basado en políticas de precios regionales que cambian con el tiempo. Une tres sets de datos basados en condiciones complejas de rango de fechas e igualdad para calcular un due_amount final. La segunda unión de búsqueda utiliza el campo measurement_date del índice de meter_readings y el campo region_id del índice de customers para unirse al índice de pricing_policies y encontrar la política de precios correcta según la region y la measurement_dateparticular.

FROM meter_readings
| LOOKUP JOIN customers
      ON meter_id
| LOOKUP JOIN pricing_policies
      ON
        region_id == region AND
          measurement_date >= policy_begin_date AND
          measurement_date < policy_end_date
| EVAL due_amount = (kwh_consumed * rate_per_kwh + base_charge) * (1 + tax_rate)
| EVAL period = policy_name
| KEEP customer_name, period, due_amount, measurement_date, kwh_consumed,
    rate_per_kwh, base_charge, tax_rate
| SORT measurement_date

• Grandes ganancias de rendimiento para uniones filtradas:

Hemos mejorado el rendimiento de las "uniones en expansión" que se filtran al utilizar condiciones de tabla de búsqueda. Las uniones expansivas producen múltiples coincidencias por fila de entrada, lo que puede generar grandes conjuntos de resultados intermedios. Esto empeora cuando muchas de esas filas se descartan mediante un filtro posterior. En la versión 9.2, optimizamos estas uniones al filtrar las filas innecesarias cuando se aplica un filtro a los datos de búsqueda, lo que evita procesar filas que se descartarían. ¡En algunos casos, estas uniones pueden ser hasta 1000 veces más rápidas!

Esta optimización es crucial cuando se trata de "uniones en expansión", en las que una búsqueda podría generar inicialmente muchas coincidencias potenciales. Al aplicar filtros de forma inteligente, solo se procesan los datos relevantes, lo que reduce drásticamente el tiempo de ejecución de las consultas y permite realizar análisis en tiempo real en sets de datos masivos. Esto significa que obtienes tu información mucho más rápido, incluso con operaciones de unión muy grandes o complejas.

Compatibilidad de la búsqueda de agrupación con Cross-Cluster Search (CCS):

Cuando Lookup Join se lanzó al mercado en las versiones 8.19 y 9.1, carecía de compatibilidad con Cross-Cluster Search (CCS). Para organizaciones que operan en múltiples agrupaciones, LOOKUP JOIN ahora se integra perfectamente con CCS en la versión 9.2. Simplemente coloca tu índice de búsqueda en todos los clústeres remotos donde desees realizar una unión, y ES|QL aprovechará automáticamente estos índices de búsqueda para unirse a sus datos remotos. Esto simplifica el análisis distribuido de datos y garantiza un enriquecimiento consistente en todo el despliegue de Elasticsearch.

Estas mejoras permiten correlacionar diversos conjuntos de datos con una precisión, velocidad y facilidad sin precedentes, lo que permite obtener información más profunda y útil sin necesidad de soluciones alternativas complejas ni pasos de preprocesamiento.

Enriquece tus datos con facilidad: Kibana Discover UX para índices de búsqueda

El enriquecimiento de datos debe ser sencillo, no un obstáculo. Introdujimos una experiencia de usuario fantástica en Discover de Kibana para crear y gestionar índices de búsqueda.

Flujo de trabajo intuitivo: el autocompletado integral de Discover te guiará a través del proceso y te sugerirá índices de búsqueda y campos de unión en el editor ES|QL, lo que hace que sea increíblemente fácil conectar tus datos de monitoreo del tiempo de actividad con índices existentes. Escribe el nombre de un índice de búsqueda que no exista y obtén acceso directo al editor de búsqueda con un clic para crear el índice. Escribe el nombre de un índice de búsqueda existente y te sugeriremos una opción para editarlo:

Gestión en línea (CRUD): mantén actualizados tus sets de datos de referencia con las funciones de edición en línea (crear, leer, actualizar, eliminar) directamente en Discover.

Carga de archivos sin esfuerzo: ahora puedes subir archivos directamente, como CSVs, dentro de Discover y usarlos instantáneamente en LOOKUP JOIN. ¡Ya no es necesario cambiar de contexto al saltar de un área a otra de Kibana!

Ya sea que estés usando mapping de IDs de usuario a nombres, agregando metadatos empresariales o uniendo archivos de referencia estáticos, esta característica democratiza el enriquecimiento de datos, lo que pone el poder de las uniones directamente en manos de cada usuario de forma rápida, sencilla y en un solo lugar.

Preserva tu contexto: presentación de INLINE STATS (versión preliminar de tecnología)

La agregación de datos es crucial, pero a veces necesitas ver los agregados junto a tus datos originales. Nos complace presentar INLINE STATS como una característica de vista previa técnica.

A diferencia del comando STATS, que reemplaza tus campos de entrada por una salida agregada, INLINE STATS conserva todos tus campos de entrada originales y simplemente agrega los nuevos campos agregados. Esto te permite realizar más operaciones en tus campos de entrada originales después de la agregación, lo que genera un flujo de trabajo de análisis más continuo y flexible.

Por ejemplo, para calcular la distancia promedio de vuelo mientras se mantienen las filas de vuelo individuales:

FROM kibana_sample_data_flights
 | KEEP Carrier, Dest, DistanceMiles
 | INLINE STATS avgDist = ROUND(AVG(DistanceMiles))
       BY Dest
 | WHERE DistanceMiles > avgDist

En esta consulta, se agrega avgDist a cada fila con el Destcorrespondiente (ination) por el que agrupamos y, como aún tenemos las columnas de información de vuelo, podemos filtrar los resultados a los vuelos con una distancia mayor que la media.

Compatibilidad con series temporales en ES|QL (vista previa técnica)

Elasticsearch usa flujos de datos temporales para almacenar métricas. Estamos agregando soporte para agregaciones de series temporales en ES|QL, a través del comando fuente TS. Esto está disponible en Elastic Cloud Serverless y la versión 9.2 básica como vista previa técnica.

El análisis de series temporales se basa en gran medida en consultas de agregación que resumen los valores métricos a lo largo de las cubetas de tiempo, divididos por una o más dimensiones de filtrado. La mayoría de las consultas de agregación se basan en un procesamiento de dos pasos, con (a) una función de agregación interna que resume los valores por serie temporal y (b) una función de agregación externa, que combina los resultados de (a) en todas las series temporales.

El comando de origen TS, combinado con STATS, proporciona una forma concisa, pero efectiva de expresar tales consultas sobre series temporales. Más concretamente, considera el siguiente ejemplo para calcular la tasa total de solicitudes por host y hora:

TS my_metrics
| WHERE @timestamp > NOW() - 1 day
| STATS SUM(RATE(requests))
      BY host, TBUCKET(1h)

En este caso, la función de agregación de seriales temporales RATE se evalúa primero por series temporales y hora. Los agregados parciales producidos se combinan luego al usar SUM para calcular los valores agregados finales por host y por hora.

Puedes consultar la lista de funciones de agregación de series temporales disponibles aquí. Ahora se admite la tasa de contador, posiblemente la función de agregación más importante para procesar contadores.

El comando fuente TS está diseñado para combinarse con STATS, con ejecución ajustada para soportar eficientemente agregaciones de series temporales. Por ejemplo, los datos se ordenan antes de pasar a las STATS. Actualmente, no se permiten comandos de procesamiento que puedan enriquecer o alterar los datos temporales o su orden, como FORK o INLINE STATS, entre TS y STATS. Esta limitación podría eliminarse en el futuro.

La salida tabular STATS se puede procesar aún más con cualquier comando aplicable. Por ejemplo, la siguiente búsqueda calcula la relación del promedio de cpu_usage por host hospedado y hora con el valor máximo por host:

TS my_metrics
| STATS avg_usage = AVG(AVG_OVER_TIME(cpu_usage))
      BY host, time_bucket = TBUCKET(1h)
| INLINE STATS max_avg_usage = MAX(avg_usage)
      BY host
| EVAL ratio = avg_usage / max_avg_usage
| KEEP host, time_bucket, ratio
| SORT host, time_bucket DESC

Los datos temporales se almacenan en nuestro motor de almacenamiento columnar subyacente que funciona con los valores de documentos de Lucene. El comando TS agrega ejecución de consultas vectorizadas a través del motor de cómputo ES|QL. El rendimiento de las búsquedas a menudo se mejora en más de un orden de magnitud, en comparación con las consultas DSL equivalentes, y está a la par con los sistemas establecidos específicos de métricas. En el futuro ofreceremos un análisis detallado de arquitectura y rendimiento, así que mantente alerta.

Ampliación de tu conjunto de herramientas: funciones nuevas de ES|QL

Manipulación de cadenas: CONTAINS, MV_CONTAINS, URL_ENCODE, URL_ENCODE_COMPONENT, URL_DECODE para un procesamiento más robusto de texto y URL.

Serie temporal y geoespacial: TBUCKET para cubetas de tiempo flexibles, TO_DENSE_VECTOR para operaciones vectoriales y un conjunto completo de funciones geoespaciales como ST_GEOHASH, ST_GEOTILE, ST_GEOHEX, TO_GEOHASH, TO_GEOTILE, TO_GEOHEX para un análisis avanzado basado en la ubicación.

Formato de fechas: DAY_NAME, MONTH_NAME para representaciones de fechas más legibles.

Estas funciones te proporcionan un conjunto más completo de herramientas para manipular y analizar tus datos directamente dentro de ES|QL.

Bajo el capó: Más rendimiento y eficiencia

Más allá de las características destacadas, Elasticsearch 9.2 incluye varias optimizaciones de rendimiento en ES|QL. Aceleramos RLIKE (LIST) con pushdown en casos en los que la función reemplaza múltiples consultas RLIKE similares. Con RLIKE (LIST), podemos fusionar esas búsquedas en un único autómata y aplicar un autómata en vez de varios. También tenemos una carga más rápida de los campos de palabras clave con ordenamientos de índice y optimizaciones generales de consultas; estas mejoras aseguran que tus consultas ES|QL se ejecuten más eficientemente que nunca.

¡Comienza hoy mismo!

Elasticsearch 9.2 representa un avance significativo para ES|QL, ya que brinda un poder y flexibilidad sin precedentes a sus flujos de trabajo de análisis de datos. Te invitamos a explorar estas funciones nuevas y a experimentar la diferencia que generan.

Para obtener una lista completa de todos los cambios y mejoras de Elasticsearch 9.2, consulte las notas de lanzamiento oficiales. ¡Feliz búsqueda!

Los conectores personalizados te permiten combinar tus conectores de ChatGPT existentes con otras fuentes de datos como Elasticsearch para obtener respuestas integrales.

En este artículo, crearemos un servidor MCP que conecta ChatGPT a un índice de Elasticsearch que contiene información sobre incidencias internas de GitHub y solicitudes de extracción. Esto permite responder a búsquedas en lenguaje natural mediante los datos de Elasticsearch.

Desplegaremos el servidor MCP utilizando FastMCP en Google Colab con ngrok para obtener una URL pública a la que ChatGPT pueda conectarse, lo que eliminará la necesidad de una infraestructura compleja.

Para una visión general del MCP y su ecosistema, consulta El estado actual de MCP.

Prerrequisitos

Antes de comenzar, necesitarás:

• Clúster de Elasticsearch (8.X o superior).
• Clave API de Elasticsearch con acceso de lectura a tu índice.
• Cuenta de Google (para Google Colab)
• Cuenta de Ngrok (el nivel gratuito funciona)
• Cuenta de ChatGPT con plan Pro/Enterprise/Business o Edu.

Comprensión de los requisitos del conector MCP de ChatGPT.

Los conectores MCP de ChatGPT requieren la implementación de dos herramientas: search y fetch. Para más detalles, consulta OpenAI Docs.

Herramienta de búsqueda

Devuelve una lista de resultados relevantes de tu índice de Elasticsearch según la búsqueda del usuario.

Lo que recibe:

• Un solo texto con la búsqueda de lenguaje natural del usuario.
• Ejemplo: “Encuentra incidencias relacionadas con la migración de Elasticsearch”.

Lo que devuelve: 

• Un objeto con una clave result que contiene un arreglo de objetos de resultado. Cada resultado incluye:
  • id - Identificador único de documentos.
  • title - Título de la incidencia o PR.
  • url - Enlace a la incidencia o PR.

En nuestra implementación:

return {
    "results": [
        {
            "id": "PR-612",
            "title": "Fix memory leak in WebSocket notification service",
            "url": "https://internal-git.techcorp.com/pulls/612"
        },
        # ... more results
    ]
}

Herramienta de extracción

Recupera el contenido completo de un documento específico.

Lo que recibe:

• Una sola cadena de texto con el ID del documento de Elasticsearch del resultado de la búsqueda.
• Ejemplo: “Consígueme los detalles de PR-578”.

Lo que devuelve:

• Un objeto de documento completo con:
  • id - Identificador único de documentos.
  • title - Título de la incidencia o PR.
  • text - Descripción completa del problema/PR y sus detalles
  • url - Enlace a la incidencia o PR.
  • type - Tipo de documento (incidencia, pull_request).
  • status - Estado actual (abierto, en progreso, resuelto)
  • priority - Nivel de prioridad (bajo, medio, alto, crítico)
  • assignee - Persona asignada al problema/PR
  • created_date - Fecha de creación.
  • resolved_date - Cuando se resolvió (si procede)
  • labels - Etiquetas asociadas al documento
  • related_pr - ID de solicitud de extracción relacionado

return {
    "id": "PR-578",
    "title": "Security hotfix: Patch SQL injection vulnerabilities",
    "text": "Description: CRITICAL SECURITY FIX for ISSUE-1889. Patches SQL...",
    "url": "https://internal-git.techcorp.com/pulls/578",
    "type": "pull_request",
    "status": "closed",
    "priority": "critical",
    "assignee": "sarah_dev",
    "created_date": "2025-09-19",
    "resolved_date": "2025-09-19",
    "labels": "security, hotfix, sql",
    "related_pr": null
}

Nota: Este ejemplo usa una estructura plana donde todos los campos están en el nivel raíz. Los requisitos de OpenAI son flexibles y también admiten objetos de metadatos anidados.

Sets de datos de incidencias y PR de GitHub

Para este tutorial, vamos a usar un set de datos interno de GitHub que contenga incidencias y solicitudes de extracción. Esto representa un escenario en el que deseas buscar datos internos privados a través de ChatGPT.

Los sets de datos se pueden encontrar aquí. Y actualizaremos el índice de los datos mediante la API de bulk.

Este sets de datos incluye:

• Problemas con descripciones, estado, prioridad y responsables.
• Solicitudes de extracción con cambios de código, revisiones e información de despliegue.
• Relaciones entre incidencias y PR (p. ej., PR-578 soluciona ISSUE-1889).
• Etiquetas, fechas y otros metadatos

Mappings de índices

El índice utiliza los siguientes mappings para brindar soporte a la búsqueda híbrida con ELSER. El campo text_semantic se utiliza para la búsqueda semántica, mientras que los demás campos permiten la búsqueda por palabras clave.

{
  "mappings": {
    "properties": {
      "id": {
        "type": "keyword"
      },
      "title": {
        "type": "text"
      },
      "text": {
        "type": "text"
      },
      "text_semantic": {
        "type": "semantic_text",
        "inference_id": ".elser-2-elasticsearch"
      },
      "url": {
        "type": "keyword"
      },
      "type": {
        "type": "keyword"
      },
      "status": {
        "type": "keyword"
      },
      "priority": {
        "type": "keyword"
      },
      "assignee": {
        "type": "keyword"
      },
      "created_date": {
        "type": "date",
        "format": "iso8601"
      },
      "resolved_date": {
        "type": "date",
        "format": "iso8601"
      },
      "labels": {
        "type": "keyword"
      },
      "related_pr": {
        "type": "keyword"
      }
    }
  }
}

Construye el servidor MCP

Nuestro servidor MCP implementa dos herramientas que siguen las especificaciones de OpenAI, y utilizan búsquedas híbridas para combinar coincidencia semántica y textual para obtener mejores resultados.

Herramienta de búsqueda

Usa la búsqueda híbrida con RRF (Fusión de Rango Recíproco), combinando la búsqueda semántica con la coincidencia de texto:

@mcp.tool()
    async def search(query: str) -> Dict[str, List[Dict[str, Any]]]:
        """
        Search for internal issues and PRs using hybrid search (semantic + text with RRF).
        Returns list with id, title, and url per OpenAI spec.
        """
        if not query or not query.strip():
            return {"results": []}

        logger.info(f"Searching for: '{query}'")

        try:
            # Hybrid search with RRF (Reciprocal Rank Fusion)
            response = es_client.search(
                index=ELASTICSEARCH_INDEX,
                size=10,
                source=["id", "title", "url", "type", "priority"],
                retriever={
                    "rrf": {
                        "retrievers": [
                            {
                                # Semantic search with ELSER
                                "standard": {
                                    "query": {
                                        "semantic": {
                                            "field": "text_semantic",
                                            "query": query
                                        }
                                    }
                                }
                            },
                            {
                                # Text search (BM25) for keyword matching
                                "standard": {
                                    "query": {
                                        "multi_match": {
                                            "query": query,
                                            "fields": [
                                                "title^3",
                                                "text^2",
                                                "assignee^2",
                                                "type",
                                                "labels",
                                                "priority"
                                            ],
                                            "type": "best_fields",
                                            "fuzziness": "AUTO"
                                        }
                                    }
                                }
                            }
                        ],
                        "rank_window_size": 50,
                        "rank_constant": 60
                    }
                }
            )

            results = []
            if response and 'hits' in response:
                for hit in response['hits']['hits']:
                    source = hit['_source']
                    results.append({
                        "id": source.get('id', hit['_id']),
                        "title": source.get('title', 'Unknown'),
                        "url": source.get('url', '')
                    })

            logger.info(f"Found {len(results)} results")
            return {"results": results}

        except Exception as e:
            logger.error(f"Search error: {e}")
            raise ValueError(f"Search failed: {str(e)}")

Puntos clave:

• Búsqueda híbrida con RRF: Combina búsqueda semántica (ELSER) y búsqueda por texto (BM25) para mejores resultados.
• Búsqueda de múltiples coincidencias: Busca en múltiples campos con mejores ponderaciones (título^3, texto^2, responsable^2). El símbolo de intercalación (^) multiplica las puntuaciones de relevancia, y prioriza las coincidencias en los títulos sobre el contenido.
• Correspondencia aproximada: fuzziness: AUTO maneja los errores tipográficos y ortográficos al permitir coincidencias aproximadas.
• Ajuste de parámetros de RRF:
  • rank_window_size: 50 - Especifica cuántos resultados principales de cada recuperador (semántico y textual) se consideran antes de combinarlos.
  • rank_constant: 60 - Este valor determina cuánta influencia tienen los documentos en los conjuntos de resultados individuales sobre el resultado final clasificado.
• Solo devuelve los campos obligatorios: id, title, url según la especificación de OpenAI, y evita exponer otros campos innecesariamente.

Herramienta de extracción

Recupera los detalles del documento por ID de documento, si existe:

@mcp.tool()
    async def fetch(id: str) -> Dict[str, Any]:
        """
        Retrieve complete issue/PR details by ID.
        Returns id, title, text, url.
        """
        if not id:
            raise ValueError("ID is required")

        logger.info(f"Fetching: {id}")

        try:
            # Search by the 'id' field (not _id) since IDs are stored as a field
            response = es_client.search(
                index=ELASTICSEARCH_INDEX,
                body={
                    "query": {
                        "term": {
                            "id": id  # Search by your custom 'id' field
                        }
                    },
                    "size": 1
                }
            )

            if not response or not response['hits']['hits']:
                raise ValueError(f"Document with id '{id}' not found")

            hit = response['hits']['hits'][0]
            source = hit['_source']

            result = {
                "id": source.get('id', id),
                "title": source.get('title', 'Unknown'),
                "text": source.get('text', ''),
                "url": source.get('url', ''),
                "type": source.get('type', ''),
                "status": source.get('status', ''),
                "priority": source.get('priority', ''),
                "assignee": source.get('assignee', ''),
                "created_date": source.get('created_date', ''),
                "resolved_date": source.get('resolved_date', ''),
                "labels": source.get('labels', ''),
                "related_pr": source.get('related_pr', '')
            }

            logger.info(f"Fetched: {result['title']}")
            return result

        except Exception as e:
            logger.error(f"Fetch error: {e}")
            raise ValueError(f"Failed to fetch '{id}': {str(e)}")

Puntos clave:

• Búsqueda por campo de ID de documento: usa la búsqueda de término en el campo personalizado id.
• Devuelve el documento completo: incluye el campo completo text con todo el contenido.
• Estructura plana: todos los campos en el nivel raíz, coincidiendo con la estructura de documentos de Elasticsearch.

Desplegar en Google Colab

Usaremos Google Colab para ejecutar nuestro servidor MCP y ngrok para exponerlo públicamente de forma tal que ChatGPT pueda conectarse.

Paso 1: Abre el cuaderno de Google Colab.

Accede a nuestro cuaderno preconfigurado Elasticsearch MCP para ChatGPT.

Paso 2: Configura tus credenciales

Necesitarás tres datos:

• URL de Elasticsearch: Tu URL del cluster de Elasticsearch.
• Clave API de Elasticsearch: Clave API con acceso de lectura a tu índice.
• Token de autenticación ngrok: Token gratis de ngrok. Usaremos ngrok para exponer la URL de MCP a internet y así ChatGPT pueda conectarse.

Obtener tu token ngrok

1. Regístrate para una cuenta gratis en ngrok
2. Ve a tu dashboard de ngrok
3. Copia tu token de autenticación

Agregar secretos a Google Colab

En el cuaderno de Google Colab:

1. Haz clic en el icono de llave en la barra lateral izquierda para abrir Secretos.
2. Añade estos tres secretos:

ELASTICSEARCH_URL=https://your-cluster.elastic.com:443
ELASTICSEARCH_API_KEY=your-api-key
NGROK_TOKEN=your-ngrok-token

3.   Habilitar el acceso al cuaderno para cada secreto

Paso 3: Ejecutar el cuaderno

1. Haz clic en Tiempo de ejecución y, a continuación, en Ejecutar todo para ejecutar todas las celdas.
2. Espera que el servidor se inicie (aproximadamente 30 segundos).
3. Busque la salida que muestre su URL pública de ngrok

4. La salida mostrará algo como:

Conéctate a ChatGPT.

Ahora conectaremos el servidor MCP a tu cuenta de ChatGPT.

1. Abre ChatGPT y ve a Configuración.
2. Navega a Conectores.Si estás usando una cuenta Pro, debes activar el modo de desarrollador en los conectores.

Si estás usando la versión Enterprise o Business de ChatGPT, debes publicar el conector en tu lugar de trabajo.

3. Haz clic en Crear.

Nota: En los espacios de trabajo Business, Enterprise y Edu, solo los propietarios, administradores y usuarios que tengan habilitada la correspondiente configuración (para Enterprise/Edu) pueden agregar conectores personalizados. Los usuarios con un rol de miembro común no tienen la capacidad de agregar conectores personalizados por su cuenta.

Una vez que un propietario o usuario administrador agrega un conector y lo habilita, estará disponible para que lo usen todos los miembros del espacio de trabajo.

4. Introduce la información requerida y la URL de tu ngrok que termina en /sse/. Recuerda la “/” después de “sse”. No funcionará si no la agregas:

• Nombre: Elasticsearch MCP
• Descripción: MCP personalizado para buscar y extraer información interna de GitHub.

5. Presione Crear para guardar el MCP personalizado.

La conexión es instantánea si tu servidor está en funcionamiento. No se necesita ninguna otra autenticación, ya que la clave API de Elasticsearch está configurada en tu servidor.

Prueba el servidor MCP

Antes de hacer preguntas, necesitas seleccionar qué conector ChatGPT debe usar.

Indicación 1: Buscar incidencias

Pregunta: “Encuentre incidencias relacionadas con la migración de Elasticsearch” y confirma la llamada a la herramienta de acciones.

ChatGPT llamará a la herramienta search con tu búsqueda. Puedes ver que está buscando herramientas disponibles y preparándose para llamar a la herramienta Elasticsearch y confirma con el usuario antes de tomar cualquier acción en relación con la herramienta.

Solicitud de llamada a la herramienta:

{
  "query": "Elasticsearch migration issues"
}

Respuesta de la herramienta:

{
  "results": [
    {
      "id": "PR-598",
      "title": "Elasticsearch 8.x migration - Application code changes",
      "url": "https://internal-git.techcorp.com/pulls/598"
    },
    {
      "id": "ISSUE-1712",
      "title": "Migrate from Elasticsearch 7.x to 8.x",
      "url": "https://internal-git.techcorp.com/issues/1712"
    },
    {
      "id": "RFC-045",
      "title": "Design Proposal: Microservices Migration Architecture",
      "url": "https://internal-git.techcorp.com/rfcs/045"
    }
    // ... 7 more results
  ]
}

ChatGPT procesa los resultados y los presenta en un formato natural y conocido.

Entre bastidores

Indicación: “Busca incidencias relacionadas con la migración de Elasticsearch”

1. Llamadas de ChatGPT search(“Elasticsearch migration”)

2. Elasticsearch realiza una búsqueda híbrida

• La búsqueda semántica entiende conceptos como “actualización” y “compatibilidad de versiones”.
• La búsqueda de texto encuentra coincidencias exactas de "Elasticsearch" y "migración".
• RRF combina y clasifica los resultados de ambos enfoques

3. Devuelve los 10 mejores eventos que coinciden con id, title, url

4. ChatGPT identifica “ISSUE-1712: migrar de Elasticsearch 7.x a 8.x” como el resultado más relevante.

Indicación 2: Obtén los detalles completos

Pregunta: “Obtén detalles de ISSUE-1889”

ChatGPT reconoce que deseas información detallada sobre una incidencia específica, llama a la herramienta fetch y confirma con el usuario antes de tomar cualquier acción con la herramienta.

Solicitud de llamada a la herramienta:

{
  "id": "ISSUE-1889"
}

Respuesta de la herramienta:

{
  "id": "ISSUE-1889",
  "title": "SQL injection vulnerability in search endpoint",
  "text": "Description: Security audit identified SQL injection vulnerability in /api/v1/search endpoint. User input from query parameter is not properly sanitized before being used in raw SQL query. Severity: HIGH - Immediate action required Affected Code: - File: services/search/query_builder.py - Line: 145-152 - Issue: String concatenation used instead of parameterized queries Investigation: - @security_team_alice: Confirmed exploitable with UNION-based injection - @sarah_dev: Checking all other endpoints for similar patterns - @john_backend: Found 3 more instances in legacy codebase Remediation: - Rewrite using SQLAlchemy ORM or parameterized queries - Add input validation and sanitization - Implement WAF rules as additional layer - Security regression tests Comments: - @tech_lead_mike: Stop all other work, this is P0 - @sarah_dev: PR-578 ready with fixes for all 4 vulnerable endpoints - @alex_devops: Deployed hotfix to production 2025-09-19 at 14:30 UTC - @security_team_alice: Verified fix, conducting full pentest next week Resolution: All vulnerable endpoints patched. Added pre-commit hooks to catch raw SQL queries. Security training scheduled for team.",
  "url": "https://internal-git.techcorp.com/issues/1889",
  "type": "issue",
  "status": "closed",
  "priority": "critical",
  "assignee": "sarah_dev",
  "created_date": "2025-09-18",
  "resolved_date": "2025-09-19",
  "labels": "security, vulnerability, bug, sql",
  "related_pr": "PR-578"
}

ChatGPT sintetiza la información y la presenta de manera clara.

Entre bastidores

Indicación: «Obtén los detalles de ISSUE-1889»

1. Llamadas de ChatGPT fetch(“ISSUE-1889”)
2. Elasticsearch recupera el documento completo
3. Devuelve un documento completo con todos los campos a nivel raíz.
4. ChatGPT sintetiza la información y responde con citas adecuadas.

Conclusión

En este artículo, creamos un servidor MCP personalizado que conecta ChatGPT a Elasticsearch con herramientas MCP dedicadas de búsqueda y extracción, lo cual permite realizar búsquedas en lenguaje natural sobre datos privados.

Este patrón MCP funciona para cualquier índice, documentación, productos, logs o cualquier otro dato de Elasticsearch que quieras buscar mediante lenguaje natural.

Introducción al RAG agente

La Generación Aumentada por Recuperación (RAG) se convirtió en una piedra angular en aplicaciones basadas en LLM, permitiendo a los modelos proporcionar respuestas óptimas al recuperar el contexto relevante basado en las consultas de los usuarios. Los sistemas RAG mejoran la precisión y el contexto de las respuestas de los LLM al aprovechar información externa de APIs o almacenes de datos, en lugar de limitar al conocimiento preentrenado de los LLM. Por otro lado, los agentes de IA operan de forma autónoma, tomando decisiones y tomando medidas para alcanzar sus objetivos designados.

El RAG agente es un marco que unifica las fortalezas tanto de la generación aumentada por recuperación como del razonamiento agentivo. Integra RAG en el proceso de toma de decisiones del agente, permitiendo al sistema elegir dinámicamente fuentes de datos, refinar consultas para una mejor recuperación de contexto, generar respuestas más precisas y aplicar un bucle de retroalimentación para mejorar continuamente la calidad de la salida.

Características clave del RAG agente

El marco RAG agente supone un avance importante respecto a los sistemas RAG tradicionales. En lugar de seguir un proceso de recuperación fijo, aprovecha agentes dinámicos capaces de planear, ejecutar y optimizar resultados en tiempo real.

Veamos algunas de las características clave que distinguen a las pipelines RAG agenticas:

• Toma de decisiones dinámica: El RAG agente emplea un mecanismo de razonamiento para entender la intención del usuario y enrutar cada consulta a la fuente de datos más relevante, produciendo respuestas precisas y conscientes del contexto.
• Análisis exhaustivo de consultas: Agentic RAG analiza en profundidad las consultas de los usuarios, incluyendo subpreguntas y su intención general. Evalúa la complejidad de las consultas y selecciona dinámicamente las fuentes de datos más relevantes para obtener información, cerciorando respuestas precisas y completas.
• Colaboración en varias etapas: Este marco permite la colaboración en varias etapas a través de una red de agentes especializados. Cada agente gestiona una parte específica de un objetivo mayor, trabajando de forma secuencial o simultánea para lograr un resultado coherente.
• Mecanismos de autoevaluación: La cadena agente RAG emplea la autorreflexión para evaluar documentos recuperados y respuestas generadas. Puede comprobar si la información recuperada responde completamente a la consulta y luego revisar la salida para comprobar su exactitud, completitud y consistencia fáctica.
• Integración con herramientas externas: Este flujo de trabajo puede interactuar con APIs externas, bases de datos y fuentes de información en tiempo real, incorporando información actualizada y adaptar dinámicamente a los datos en evolución.

Patrones de flujo de trabajo del RAG agente

Los patrones de flujo de trabajo definen cómo la IA agente estructura, gestiona y orquesta aplicaciones basadas en LLM de manera fiable y eficiente. Varios frameworks y plataformas, como LangChain, LangGraph, CrewAI y LlamaIndex, pueden emplear para implementar estos flujos de trabajo agentes.

1. Cadena de recuperación secuencial: Los flujos de trabajo secuenciales dividen tareas complejas en pasos simples y ordenados. Cada paso mejora la entrada para el siguiente, lo que conduce a mejores resultados. Por ejemplo, al crear un perfil de cliente, un agente puede extraer datos básicos de un CRM, otro obtener el historial de compras de una base de datos de transacciones y un agente final combinar esta información para generar un perfil completo de recomendaciones o reportes.
2. Cadena de recuperación de enrutamiento: En este patrón de flujo de trabajo, un agente router analiza la entrada y la dirige al proceso o fuente de datos más adecuada. Este enfoque es especialmente eficaz cuando existen múltiples fuentes de datos distintas con una superposición mínima. Por ejemplo, en un sistema de atención al cliente, el agente del router categoriza las solicitudes entrantes, como problemas técnicos, reembolsos o reclamaciones, y las encamina al departamento correspondiente para su gestión eficiente.
3. Cadena de recuperación paralela: En este patrón de flujo de trabajo, se ejecutan simultáneamente múltiples subtareas independientes y sus salidas se agregan posteriormente para generar una respuesta final. Este enfoque reduce significativamente el tiempo de procesamiento y aumenta la eficiencia del flujo de trabajo. Por ejemplo, en un flujo de trabajo paralelo de atención al cliente, un agente recupera solicitudes pasadas similares y otro consulta artículos relevantes de la base de conocimiento. Un agregador combina entonces estas salidas para generar una resolución completa.
4. Cadena de trabajadores Orchestrator: Este flujo de trabajo comparte similitudes con la paralelización debido a su utilización de subtareas independientes. Sin embargo, una distinción clave radica en la integración de un agente orquestador. Este agente es responsable de analizar las consultas de los usuarios, segmentarlas dinámicamente en subtareas durante la ejecución e identificar los procesos o herramientas adecuadas necesarias para formular una respuesta precisa.

Construyendo una pipeline RAG agentica desde cero

Para ilustrar los principios del RAG agente, diseñemos un flujo de trabajo usando LangChain y Elasticsearch. Este flujo de trabajo adopta una arquitectura basada en enrutamiento, donde varios agentes colaboran para analizar consultas, recuperar información relevante, evaluar resultados y generar respuestas coherentes. Podrías consultar este cuaderno Jupyter para seguir este ejemplo.

El flujo de trabajo comienza con el agente router, que analiza la consulta del usuario para seleccionar el método óptimo de recuperación, es decir, un enfoque vectorstore, websearcho composite . La vectorstore se encarga de la recuperación tradicional de documentos basada en RAG, la búsqueda sitio web obtiene la información más reciente que no está almacenada en la vectorstore, y el enfoque compuesto combina ambas cuando se necesita información de múltiples fuentes.

Si los documentos se consideran adecuados, el agente de resumen genera una respuesta clara y contextualmente adecuada. Sin embargo, si los documentos son insuficientes o irrelevantes, el agente de reescritura de la consulta reformula la consulta para mejorar la búsqueda. Esta consulta revisada resetear entonces el proceso de enrutamiento, permitiendo al sistema refinar su búsqueda y mejorar la salida final.

Prerrequisitos

Este flujo de trabajo se basa en los siguientes componentes clave para ejecutar el ejemplo de forma eficaz:

• Python 3.10
• Cuaderno Jupyter
• Azure OpenAI
• Elasticsearch
• LangChain

Antes de continuar, se te pedirá que configures el siguiente conjunto de variables de entorno requeridas para este ejemplo.

AZURE_OPENAI_ENDPOINT="Add your azure openai endpoint"
AZURE_OPENAI_KEY="Add your azure openai key"
AZURE_OPENAI_DEPLOYMENT="gpt-4.1"
AZURE_OPENAI_API_VERSION="Add your azure openai api version"

ES_ENDPOINT = "Add your Elasticsearch ENDPOINT"
ES_API_KEY = "Add your Elasticsearch API KEY"

Fuentes de datos

Este flujo de trabajo se ilustra empleando un subconjunto del conjunto de datos de AG News. El conjunto de datos comprende artículos de noticias en diversas categorías, como Internacional, Deportes, Negocios y Ciencia/Tecnología.

dataset = load_dataset("ag_news", split="train[:1000]")
docs = [
    Document(
        page_content=sample["text"],
        metadata={"category": sample["label"]}
    )
    for sample in dataset
]

El módulo ElasticsearchStore se emplea desde el langchain_elasticsearch como nuestro almacén vectorial. Para la recuperación, implementamos SparseVectorStrategy, empleando ELSER, el modelo propietario de incrustación de Elastic. Es esencial confirmar que el modelo ELSER está correctamente instalado y desplegado en tu entorno Elasticsearch antes de iniciar el almacén vectorial.

elastic_vectorstore = ElasticsearchStore.from_documents(
    docs,
    es_url=ES_ENDPOINT,
    es_api_key=ES_API_KEY,
    index_name=index_name,
    strategy=SparseVectorStrategy(model_id=".elser_model_2"),
)

elastic_vectorstore.client.indices.refresh(index=index_name)

La funcionalidad de búsqueda sitio web se implementa usando DuckDuckGoSearchRun de las herramientas comunitarias LangChain, lo que permite al sistema recuperar información en tiempo real de la web de forma eficiente. También puedes considerar usar otras APIs de búsqueda que puedan ofrecer resultados más relevantes. Esta herramienta fue elegida porque permite búsquedas sin necesidad de clave API.

duckduckgo = DuckDuckGoSearchRun(description= "A custom DuckDuckGo search tool for finding latest news stories.", verbose=True)
def websearch_retriever(query):
    results = duckduckgo.run(f"{query}")
    return results

El retriever compuesto está diseñado para consultas que requieren una combinación de fuentes. Se emplea para proporcionar una respuesta completa y contextualmente precisa al recuperar datos en tiempo real de la web y consultar noticias históricas del almacén vectorial.

def composite_retriever(query):
    related_docs = vectorstore_retriever(query)
    related_docs += websearch_retriever(query)
    return related_docs

Preparando a los agentes

En el siguiente paso, los agentes LLM se definen para proporcionar capacidades de razonamiento y toma de decisiones dentro de este flujo de trabajo. Las cadenas de LLM que crearemos incluyen: router_chain, grade_docs_chain, rewrite_query_chainy summary_chain.

El agente router emplea un asistente LLM para determinar la fuente de datos más adecuada para una consulta determinada en tiempo de ejecución. El agente evaluador evalúa la relevancia de los documentos recuperados. Si los documentos se consideran relevantes, se entregan al agente de resumen para que genere un resumen. De lo contrario, el agente de consulta de reescritura reformula la consulta y la envía de vuelta al proceso de enrutamiento para otro intento de recuperación. Puedes encontrar las instrucciones de todos los agentes en la sección de cadenas de LLM del cuaderno.

class RouteQuery(BaseModel):
    datasource: Literal["vectorstore", "websearch", "composite"] = Field(
        ...,
        description="Choose to route the query to web search, vectorstore or composite."
    )

router_prompt = ChatPromptTemplate.from_template("""You are an assistant that decides the best data source for questions based on news articles.
Choose one of the following options:
- 'vectorstore': for general, background, or historical news articles.
- 'websearch': for recent discoveries, 'latest', 'current', or '2025' type queries.
- 'composite': when the question needs both historical and current knowledge on news articles.

Question: {query}

Return one word: 'vectorstore', 'websearch', or 'composite'.
""")
router_structured = llm.with_structured_output(RouteQuery)
router_chain: RunnableSequence = router_prompt | router_structured

La llm.with_structured_output limita la salida del modelo para seguir un esquema predefinido definido por el BaseModel bajo la clase RouteQuery , cerciorando la consistencia de los resultados. La segunda línea compone una RunnableSequence conectando router_prompt con router_structured, formando una tubería en la que el modelo de lenguaje procesa el prompt de entrada para producir resultados estructurados y compatibles con el esquema.

Definir nodos de grafo

Esta parte implica definir los estados del grafo, que representan los datos que fluyen entre los diferentes componentes del sistema. Una especificación clara de estos estados cerciora que cada nodo del flujo de trabajo sepa qué información puede acceder y actualizar.

class RAGState(TypedDict):
    query: str
    docs: List[Document]
    router: str
    summary: str
    self_reflection: bool
    retry_count: int = 0

Una vez definidos los estados, el siguiente paso es definir los nodos del grafo. Los nodos son como las unidades funcionales del grafo que realizan operaciones específicas sobre los datos. Hay 7 nodos diferentes en nuestra pipeline.

def router(state: RAGState):
   router = router_chain.invoke({'query': state["query"]})
   logger.info(f"Router selected the datasource: {router.datasource}")
   logger.info(f"User query: {state['query']}")
   return {"router": router.datasource}

def vectorstore(state: RAGState):
   return {"docs": vectorstore_retriever(state["query"])}

def websearch(state: RAGState):
   return {"docs": websearch_retriever(state["query"])}

def composite(state: RAGState):
   return {"docs": composite_retriever(state["query"])}

def self_reflection(state: RAGState):
   evaluation = grade_docs_chain.invoke(
       {"query": state["query"], "docs": state["docs"]}
   )
   if evaluation.binary_score:
       logger.info(f"Self-reflection passed -- binary_score={evaluation.binary_score}")
   else:
       logger.info(f"Self-reflection failed -- binary_score={evaluation.binary_score}")

   return {
       "self_reflection": evaluation.binary_score,
   }

def query_rewriter(state: RAGState):
   retry_count = state.get("retry_count", 0) + 1
   new_query = rewrite_query_chain.invoke({"query": state["query"]})
   logger.info(f"Query rewritten: {new_query}, retry_count: {retry_count}")
   return {
       "query": new_query,
       "retry_count": retry_count,
   }

def summarize(state: RAGState):
   summary = summarize_chain.run(
       query=state["query"],
       docs=state["docs"],
   )
   return {"summary": summary}

El nodo query_rewriter cumple dos funciones en el flujo de trabajo. Primero, reescribe la consulta del usuario usando el rewrite_query_chain para mejorar la recuperación cuando los documentos evaluados por el agente autorreflexivo se consideran insuficientes o irrelevantes. Segundo, actúa como un contador que registra cuántas veces se reescribió la consulta.

Cada vez que se invoca el nodo, incrementa la retry_count almacenada en el estado del flujo de trabajo. Este mecanismo impide que el flujo de trabajo entre en un bucle infinito. Si el retry_count supera un umbral predefinido, el sistema puede recurrir a un estado de error, una respuesta por defecto o cualquier otra condición predefinida que elijas.

Compilación del grafo

El último paso es definir las aristas del grafo y agregar las condiciones necesarias antes de compilarlo. Cada grafo debe comenzar desde un nodo inicial designado, que sirve como punto de entrada para el flujo de trabajo. Las aristas en el gráfico representan el flujo de datos entre nodos y pueden ser de dos tipos:

• Aristas rectas: Estas definen un flujo directo e incondicional de un nodo a otro. Cada vez que el primer nodo completa su tarea, el flujo de trabajo avanza automáticamente al siguiente nodo a lo largo de la arista recta.
• Aristas condicionales: Estas permiten que el flujo de trabajo se ramifice según el estado actual o los resultados del cálculo de un nodo. El siguiente nodo se selecciona dinámicamente en función de condiciones como resultados de evaluación, decisiones de enrutamiento o recuentos de intentos.

graph.add_edge(START, "router")

def after_router(state: RAGState):
   route = state.get("router", None)
   if route == "vectorstore":
       return "vectorstore"
   elif route == "websearch":
       return "websearch"
   else:
       return "composite"

def after_self_reflection(state: RAGState):
   if state["self_reflection"]:
           return "summarize"
   return "query_rewriter"

def after_query_rewriter(state: RAGState):
   while state['retry_count'] <= 3:
           return "router"
   raise RuntimeError("Maximum retries (3) reached -- evaluation failed.")

graph.add_conditional_edges(
   "router",
   after_router,
   {
       "vectorstore": "vectorstore",
       "websearch": "websearch",
       "composite": "composite"
   }
)

graph.add_edge("vectorstore", "self_reflection")
graph.add_edge("websearch", "self_reflection")
graph.add_edge("composite", "self_reflection")
graph.add_conditional_edges(
   "self_reflection",
   after_self_reflection,
   {
       "summarize": "summarize",
       "query_rewriter": "query_rewriter"
   }
)
graph.add_conditional_edges("query_rewriter", after_query_rewriter, {"router": "router"})
graph.add_edge("summarize", END)
agent=graph.compile()

Con eso, tu primera pipeline de RAG agente está lista y puede probar usando el agente compilado.

result = agent.invoke({"query": query1})
logger.info(f"\nFinal Summary:\n: {result['summary']}")

Prueba de la tubería agente RAG

Ahora probaremos esta canalización usando tres tipos distintos de consultas como se indica a continuación. Ten en cuenta que los resultados pueden variar, y los ejemplos que se muestran a continuación ilustran solo un posible resultado.

query1="What are the latest AI models released this month?"
query2="What technological innovations are discussed in Sci/Tech news?"
query3="Compare a Sci/Tech article from the dataset with a current web article about AI trends."

Para la primera consulta, el router selecciona websearch como fuente de datos. La consulta no supera la evaluación de autorreflexión y posteriormente se redirige a la etapa de reescritura de la consulta, como se muestra en el resultado.

INFO     | __main__:router:11 - Router selected the datasource: websearch
INFO     | __main__:router:12 - User query: What are the latest AI models released this month?
Latest Singapore news, including the city state's relationships with Malaysia and Mahathir, China and Xi Jinping, and the rest of Southeast Asia. 3 days ago · The latest military news, insights and analysis from China. All the latest news, opinions and analysis on Hong Kong, China, Asia and around the world Latest news, in-depth features and opinion on Malaysia, covering politics, economy, society and the Asean member-nation's relationships with China, Singapore, and other Southeast Asian ... Oct 12, 2025 · Brics (an acronym for Brazil, Russia, India, China and South Africa) refers to an association of 10 leading emerging markets. The other member states are Egypt, Ethiopia, ...
INFO     | __main__:self_reflection:31 - Self-reflection failed -- binary_score=False
INFO     | __main__:query_rewriter:40 - Query rewritten: query='Which AI models have been officially released in June 2024?', retry_count: 1
INFO     | __main__:router:11 - Router selected the datasource: websearch
INFO     | __main__:router:12 - User query: query='Which AI models have been officially released in June 2024?'
Dream Machine is a text-to-video model created by Luma Labs and launched in June 2024 . It generates video output based on user prompts or still images. Dream Machine has been noted for its ability to realistically capture motion... Released in June 2023. In June 2024 , Baidu announced Ernie 4.0 Turbo. In April 2025, Ernie 4.5 Turbo and X1 Turbo were released . These models are optimized for faster response times and lower operational costs.[28][29]. The meaning of QUERY is question, inquiry. How to use query in a sentence. Synonym Discussion of Query. QUERY definition: 1. a question, often expressing doubt about something or looking for an answer from an authority.... Learn more. Query definition: a question; an inquiry.. See examples of QUERY used in a sentence.
INFO     | __main__:self_reflection:29 - Self-reflection passed -- binary_score=True
INFO     | __main__::2 - 
Final Summary:
: In June 2024, two AI models were officially released: Dream Machine, a text-to-video model launched by Luma Labs, and Ernie 4.0 Turbo, announced by Baidu, which is optimized for faster response times and lower operational costs.

A continuación, examinamos un ejemplo en el que se emplea vectorstore recuperación, demostrado con la segunda consulta.

INFO     | __main__:router:11 - Router selected the datasource: vectorstore
INFO     | __main__:router:12 - User query: What technological innovations are discussed in Sci/Tech news?
INFO     | __main__:self_reflection:29 - Self-reflection passed -- binary_score=True
INFO     | __main__::2 - 
Final Summary:
: Recent Sci/Tech news highlights several technological innovations: NASA is collaborating with Silicon Valley firms to build a powerful Linux-based supercomputer to support theoretical research and shuttle engineering; new chromatin transfer techniques have enabled the cloning of cats; cybersecurity advancements are being discussed in relation to protecting personal technology; Princeton University scientists assert that existing technologies can be used immediately to stabilize global warming; and a set of GameBoy micro-games has been recognized for innovation in game design.

La consulta final se dirige a la recuperación compuesta, que emplea tanto la vectorstore como la búsqueda sitio web.

INFO     | __main__:router:11 - Router selected the datasource: composite
INFO     | __main__:router:12 - User query: Compare a Sci/Tech article from the dataset with a current web article about AI trends.
Atlas currently only available on macOS, built on Chromium with planned features like ad-blocking still in development. OpenAI's Atlas browser launched with bold promises of AI -powered web browsing, but early real-world testing reveals a different story. Career-long data are updated to end-of-2024 and single recent year data pertain to citations received during calendar year 2024. The selection is based on the top 100,000 scientists by c-score (with and without self-citations) or a percentile rank of 2% or above in the sub-field. In this article I list 45 AI tools across 21 different categories. After exploring all the available options in each category, I've carefully selected the best tools based on my personal experience. Reading a complex technical article ? Simply highlight confusing terminology and ask "what's this?" to receive instant explanations. compare browsers. Comparison showing traditional browser navigation versus OpenAI Atlas AI -powered workflows. After putting Gemini, ChatGPT, Grok, and DeepSeek through rigorous testing in October 2025, it's clear that there isn't one AI that reigns supreme across all categories.
INFO     | __main__:self_reflection:29 - Self-reflection passed -- binary_score=True
INFO     | __main__::2 - 
Final Summary:
: A Sci/Tech article from the dataset highlights NASA's development of robust artificial intelligence software for planetary rovers, aiming to make them more self-reliant and capable of decision-making during missions. In contrast, a current web article about AI trends focuses on the proliferation of AI-powered tools across various categories, including browsers like OpenAI Atlas, and compares leading models such as Gemini, ChatGPT, Grok, and DeepSeek, noting that no single AI currently excels in all areas. While the NASA article emphasizes specialized AI applications for autonomous robotics in space exploration, the current trends article showcases the broadening impact of AI across consumer and professional technologies, with ongoing competition and rapid innovation among major AI platforms.

En el flujo de trabajo anterior, el RAG agente determina de forma inteligente qué fuente de datos emplear al recuperar información para una consulta de usuario, mejorando así la precisión y relevancia de la respuesta. Puedes crear ejemplos adicionales para probar al agente y revisar los resultados para ver si dan resultados interesantes.

Mejores prácticas para construir flujos de trabajo agenticos RAG

Ahora que entendemos cómo funciona el RAG agente, veamos algunas buenas prácticas para construir estos flujos de trabajo. Seguir estas directrices ayudará a mantener el sistema eficiente y fácil de mantener.

• Prepárate para los recursos de respaldo: Planea estrategias de respaldo con antelación para escenarios en los que algún paso del flujo de trabajo falle. Estos pueden incluir devolver respuestas por defecto, activar estados de error o emplear herramientas alternativas. Esto garantiza que el sistema gestione los fallos con elegancia sin romper el flujo de trabajo global.
• Implementa registros completos: Prueba a implementar registros en cada etapa del flujo de trabajo, como intentos, salidas generadas, elecciones de enrutamiento y reescrituras de consultas. Estos registros ayudan a mejorar la transparencia, facilitan la depuración y ayudan a refinar los prompts, el comportamiento de los agentes y las estrategias de recuperación con el tiempo.
• Selecciona el patrón de flujo de trabajo adecuado: Examina tu caso de uso y selecciona el patrón que mejor se adapte a tus necesidades. Emplea flujos de trabajo secuenciales para razonamiento paso a paso, flujos de trabajo paralelos para fuentes de datos independientes y patrones orquestador-trabajador para consultas multiherramienta o complejas.
• Incorpora estrategias de evaluación: Integra mecanismos de evaluación en diferentes etapas del flujo de trabajo. Estos pueden incluir agentes de autorreflexión, calificación de documentos recuperados o controles automáticos de calidad. La evaluación ayuda a verificar que los documentos recuperados son relevantes, que las respuestas son precisas y que todas las partes de una consulta compleja están abordadas.

Desafíos

Aunque los sistemas RAG agenticos ofrecen beneficios significativos en términos de adaptabilidad, precisión y razonamiento dinámico, también presentan ciertos desafíos que deben abordar durante sus etapas de diseño e implementación. Algunos de los principales retos incluyen:

• Flujos de trabajo complejos: A medida que se agregan más agentes y puntos de decisión, el flujo de trabajo global se vuelve cada vez más complejo. Esto puede llevar a mayores probabilidades de errores o fallos en tiempo de ejecución. Siempre que sea posible, prioriza flujos de trabajo optimizados eliminando agentes redundantes y puntos de decisión innecesarios.
• Escalabilidad: Puede ser complicado escalar sistemas RAG agentes para manejar grandes conjuntos de datos y grandes volúmenes de consultas. Incorpora estrategias eficientes de indexación, caché y procesamiento distribuido para mantener el rendimiento a gran escala.
• Orquestación y sobrecarga computacional: La ejecución de flujos de trabajo con múltiples agentes requiere orquestación avanzada. Esto incluye una planeación cuidadosa, gestión de dependencias y coordinación de agentes para evitar cuellos de botella y conflictos, todo lo cual contribuye a la complejidad general del sistema.
• Complejidad de la evaluación: La evaluación de estos flujos de trabajo presenta desafíos inherentes, ya que cada etapa requiere una estrategia de evaluación distinta. Por ejemplo, la etapa RAG debe evaluar para verificar la relevancia y completitud de los documentos recuperados, mientras que los resúmenes generados deben verificar para garantizar su calidad y precisión. Del mismo modo, la efectividad de la reformulación de consultas requiere una lógica de evaluación separada para determinar si la consulta reescrita mejora los resultados de recuperación.

Conclusión

En esta entrada de blog, presentamos el concepto de RAG agente y destacamos cómo mejora el marco tradicional de RAG al incorporar capacidades autónomas de la IA agente. Exploramos las características principales de RAG agente y demostramos estas características mediante un ejemplo práctico, construyendo un asistente de noticias usando Elasticsearch como almacén vectorial y LangChain para crear el marco agente.

Además, discutimos las mejores prácticas y los principales retos a considerar al diseñar e implementar una pipeline agentica RAG. Estos conocimientos están destinados a guiar a los desarrolladores en la creación de sistemas agentivos robustos, escalables y eficientes que combinen eficazmente la recuperación, el razonamiento y la toma de decisiones.

¿Qué sigue ahora?

El flujo de trabajo que creamos es sencillo, dejando amplio margen para mejoras y experimentación. Podemos mejorar esto experimentando con varios modelos de incrustación y refinando estrategias de recuperación. Además, integrar a un agente de reclasificación para priorizar los documentos recuperados podría ser beneficioso. Otra área de exploración implica desarrollar estrategias de evaluación para marcos agentivos, identificando específicamente enfoques comunes y reutilizables aplicables a diferentes tipos de marcos. Por último, experimentar con estos marcos en conjuntos de datos grandes y más complejos.

Mientras tanto, si tienes experimentos similares que compartir, ¡nos encantaría saberlos! No dudes en dar tus opiniones o conectar con nosotros a través de nuestro canal comunitario de Slack o foros de discusión.

Recursos

• Auto-RAG: Aprender a recuperar, generar y criticar a través de la autorreflexión
• Generación aumentada por recuperación agentica: una encuesta sobre el RAG agente

El problema del rango de puntaje

Para contextualizar, repasemos una de las principales razones por las que la búsqueda híbrida puede ser difícil: los rangos de puntaje variables. Nuestro viejo amigo BM25 produce puntajes ilimitados. En otras palabras, BM25 puede generar puntajes que van desde cerca de 0 hasta (teóricamente) infinitas. En cambio, las consultas contra dense_vector campos producirán puntajes acotados entre 0 y 1. Para empeorar este problema, semantic_text ofusca el tipo de campo empleado para indexar incrustaciones, así que a menos que tengas un conocimiento detallado sobre tu configuración de índices y endpoints de inferencia, puede ser difícil saber cuál será el rango de puntaje de tu consulta. Esto presenta un problema al intentar entrecalar resultados de búsqueda léxica y semántica, ya que los resultados léxicos pueden tener prioridad sobre los semánticos incluso si los resultados semánticos son más relevantes. La solución generalmente aceptada para este problema es normalizar los puntajes antes de entrelazar los resultados. Elasticsearch dispone de dos herramientas para esto: los retrievers lineales y RRF .

El recuperador RRF aplica el algoritmo RRF, usando el rango del documento como medida de relevancia y descartando el puntaje. Como el puntaje no se tiene en cuenta, las discrepancias en el rango de puntaje no son un problema.

El retriever lineal emplea una combinación lineal para determinar el puntaje final de un documento. Esto implica tomar el puntaje de cada consulta componente para el documento, normalizarla y sumarla para generar el puntaje total. Matemáticamente, la operación puede expresar como:

Total Score = 𝚺(N(Sx))

Donde N es la función de normalización, y SX es el puntaje para la consulta X. La función de normalización es clave aquí, ya que transforma el puntaje de cada consulta para usar el mismo rango. Puedes aprender más sobre el retriever lineal aquí.

Desglosándolo

Los usuarios pueden implementar una búsqueda híbrida eficaz con estas herramientas, pero requiere cierto conocimiento sobre tu índice. Veamos un ejemplo con el retriever lineal, donde consultaremos un índice con dos campos:

PUT linear_retriever_example
{
  "mappings": {
    "properties": {
      "semantic_text_field": { <1>
        "type": "semantic_text",
        "inference_id": ".multilingual-e5-small-elasticsearch"
      },
      "text_field": { <2>
        "type": "text"
      }
    }
  }
}

1. semantic_text_field es un campo semantic_text que emplea E5, un modelo de incrustación de texto

2. text_field es un campo estándar de text

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "retrievers": [
        {
          "retriever": {
            "standard": {
              "query": {
                "match": { <1>
                  "semantic_text_field": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        },
        {
          "retriever": {
            "standard": {
              "query": {
                "match": {
                  "text_field": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        }
      ]
    }
  }
}

1. Usamos una consulta match en nuestro campo semantic_text , para la que agregamos soporte en Elasticsearch 8.18/9.0

Al construir la consulta, debemos tener en cuenta que semantic_text_field emplea un modelo de incrustación de texto, por lo que cualquier consulta generará un puntaje entre 0 y 1. También necesitamos saber que text_field es un campo de text estándar y, por tanto, las consultas sobre él generarán un puntaje no acotada. Para crear un conjunto de resultados con la relevancia adecuada, necesitamos usar un retriever que normalice los puntajes de consulta antes de combinarlas. En este ejemplo, usamos el retriever lineal con minmax normalización, que normaliza el puntaje de cada consulta a un valor entre 0 y 1.

La construcción de la consulta en este ejemplo es bastante sencilla porque solo están involucrados dos campos. Sin embargo, puede complicar muy rápido a medida que se agregan más campos, y de diferentes tipos. Esto demuestra cómo escribir una consulta híbrida eficaz suele requerir un conocimiento más profundo del índice que se consulta, de modo que los puntajes de los componentes se normalicen correctamente antes de la combinación. Esto supone una barrera para la adopción más amplia de la búsqueda híbrida.

Agrupación de consultas

Ampliemos el ejemplo: ¿Y si quisiéramos consultar un campo text y dos campos semantic_text ? Podríamos construir una consulta así:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "retrievers": [
        {
          "retriever": {
            "standard": {
              "query": {
                "semantic": {
                  "field": "semantic_text_field_1",
                  "query": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        },
        {
          "retriever": {
            "standard": {
              "query": {
                "semantic": {
                  "field": "semantic_text_field_2",
                  "query": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        },
        {
          "retriever": {
            "standard": {
              "query": {
                "match": {
                  "text_field": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        }
      ]
    }
  }
}

Eso parece bueno a simple vista, pero hay un posible problema. Ahora los semantic_text partidos de campo representan dos tercios del total del puntaje:

Total Score = N(semantic_text_field_1 score) + N(semantic_text_field_2 score) + N(text_field score)

Probablemente esto no es lo que buscas porque crea un puntaje desequilibrado. Los efectos pueden no ser tan evidentes en un ejemplo como este con solo 3 campos, pero se vuelve problemático cuando se consultan más campos. Por ejemplo, la mayoría de los índices contienen muchos más cuerpos léxicos que la semántica (es decir, dense_vector, sparse_vector, o semantic_text). ¿Y si consultáramos un índice con 9 campos léxicos y 1 campo semántico usando el patrón anterior? Las coincidencias léxicas representarían el 90% del puntaje, lo que reduce la efectividad de la búsqueda semántica.

Una forma común de abordar esto es agrupar las consultas en categorías léxicas y semánticas y ponderar ambas de forma uniforme. Esto impide que cualquiera de las dos categorías domine el puntaje total.

Pongámoslo en práctica. ¿Cómo sería este enfoque de consultas agrupadas en este ejemplo al usar el retriever lineal?

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "retrievers": [
        {
          "retriever": {
            "linear": {
              "retrievers": [
                {
                  "retriever": {
                    "standard": {
                      "query": {
                        "semantic": {
                          "field": "semantic_text_field_1",
                          "query": "foo"
                        }
                      }
                    }
                  },
                  "normalizer": "minmax"
                },
                {
                  "retriever": {
                    "standard": {
                      "query": {
                        "semantic": {
                          "field": "semantic_text_field_2",
                          "query": "foo"
                        }
                      }
                    }
                  },
                  "normalizer": "minmax"
                }
              ]
            }
          },
          "normalizer": "minmax"
        },
        {
          "retriever": {
            "standard": {
              "query": {
                "match": {
                  "text_field": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        }
      ]
    }
  }
}

¡Vaya, esto se está poniendo muy extenso! ¡Puede que incluso tuviste que desplazarte arriba y abajo varias veces para revisar toda la consulta! Aquí, usamos dos niveles de normalización para crear los grupos de consultas. Matemáticamente, puede expresar como:

Total Score = N(N(semantic_text_field_1 score) + N(semantic_text_field_2 score)) + N(text_field score)

Este segundo nivel de normalización garantiza que las consultas contra los campos semantic_text y text campo tengan un peso uniforme. Ten en cuenta que en este ejemplo omitimos la normalización de segundo nivel para text_field ya que solo hay un cuerpo léxico, lo que te ahorra aún más verbosidad.

Esta estructura de consulta ya es engorrosa y solo estamos consultando tres campos. Se vuelve cada vez más inmanejable, incluso para los profesionales experimentados en búsqueda, a medida que consultas más campos.

El formato de consulta multicampo

Agregamos el formato de consulta multicampo para los retrievers lineales y RRF en Elasticsearch 8.19, 9.1 y serverless para simplificar todo esto. Ahora puedes realizar la misma consulta que antes con simplemente:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_1", "semantic_text_field_2", "text_field" ],
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

¡Lo que reduce la consulta de 55 líneas a solo 9! Elasticsearch emplea automáticamente los mapeos de índice para:

• Determinar el tipo de cada campo consultado
• Agrupa cada cuerpo en una categoría léxica o semántica
• Pondera cada categoría de forma equitativa en el puntaje final

Esto permite a cualquiera ejecutar una consulta híbrida eficaz sin necesidad de conocer detalles sobre el índice o los endpoints de inferencia empleados.

Al usar RRF, puedes omitir la normalizer, ya que rango se usa como indicador de relevancia:

GET rrf_retriever_example/_search
{
  "retriever": {
    "rrf": {
      "fields": [ "semantic_text_field_1", "semantic_text_field_2", "text_field" ],
      "query": "foo"
    }
  }
}

Impulso por campo

Al usar el retriever lineal, puedes aplicar un aumento por campo para ajustar la importancia de los combates en ciertos campos. Por ejemplo, supongamos que consultas cuatro campos: dos campos semantic_text y dos campos text :

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_1", "semantic_text_field_2", "text_field_1", "text_field_2" ],
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

Por defecto, cada cuerpo tiene un peso igual en su grupo (léxico o semántico). El desglose del puntaje es el siguiente:

En otras palabras, cada campo representa el 25% del puntaje total.

Podemos usar la sintaxis field^boost para agregar un impulso por campo a cualquier campo. Vamos a aplicar un aumento de 2 a semantic_text_field_1 y text_field_1:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_1^2", "semantic_text_field_2", "text_field_1^2", "text_field_2" ]
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

Ahora el desglose del puntaje es así:

Cada grupo de consulta sigue teniendo un peso igual, pero ahora el peso del campo dentro de los grupos cambió:

• semantic_text_field_1 es el 66% del puntaje del grupo de consultas semánticas, 33% del puntaje total
• text_field_1 es el 66% del puntaje del grupo de consultas léxicas, 33% del puntaje total

Resolución comodín

Puedes usar el comodín * en el parámetro fields para que coincida con varios campos. Continuando con el ejemplo anterior, esta consulta es funcionalmente equivalente a consultar semantic_text_field_1, semantic_text_field_2, y text_field_1 explícitamente:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_*", "*_field_1" ],
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

Es interesante notar que el patrón de *_field_1 coincide tanto con text_field_1 como con semantic_text_field_1. Esto se gestiona automáticamente; La consulta se ejecutará como si cada uno de los campos fuera consultado explícitamente. También está bien que el semantic_text_field_1 coincida con ambos patrones; Todas las coincidencias de nombres de campo se deduplican antes de la ejecución de la consulta.

Puedes usar el comodín de varias maneras:

• Coincidencia de prefijos (ej: *_text_field)
• Emparejamiento en línea (ej: semantic_*_field)
• Coincidencia de sufijos (ej: semantic_text_field_*)

También puedes usar varios comodines para aplicar una combinación de lo anterior, como *_text_field_*.

Campos de consulta predeterminados

El formato de consulta multicampo también te permite consultar un índice del que no sabes nada. Si omites el parámetro fields , consultará todos los campos especificados por la configuración de índice index.query.default_field:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

Por defecto, index.query.default_field está configurado como *. Este comodín se resolverá a todos los tipos de campo del índice que admitan consultas de término, que es la mayoría. Las excepciones son:

• dense_vector Campos
• rank_vector Campos
• Campos geométricos: geo_point, shape

Esta funcionalidad es especialmente útil cuando se quiere realizar una consulta de búsqueda híbrida sobre un índice proporcionado por un tercero. El formato de consulta multicampo permite ejecutar una consulta adecuada de forma sencilla. Simplemente excluye el parámetro fields y se consultarán todos los campos aplicables.

Conclusión

El problema del rango de puntaje puede hacer que la búsqueda híbrida efectiva sea un dolor de cabeza de implementar, especialmente cuando hay poca comprensión del índice que se consulta o de los endpoints de inferencia empleados. El formato de consulta multicampo para los retrievers lineales y RRF alivia este problema al empaquetar un enfoque automatizado de búsqueda híbrida basado en agrupación de consultas en una API simple y accesible. Funcionalidades adicionales, como el aumento por campo, la resolución de comodines y los campos de consulta por defecto, amplían la funcionalidad para cubrir muchos casos de uso.

Prueba hoy el formato de consulta multicampo

Puedes consultar los retrievers lineales y RRF con el formato de consulta multicampo en proyectos Serverless totalmente gestionados de Elasticsearch con una prueba gratis. También está disponible en versiones de pila a partir de la 8.19 y 9.1.

Empieza en minutos en tu entorno local con un solo comando:

curl -fsSL https://elastic.co/start-local | sh

Este artículo te mostrará cómo construir un agente de IA para RRHH usando GPT-OSS y Elastic Agent Builder. El agente puede responder a tus preguntas sin enviar datos a OpenAI, Anthropic ni ningún servicio externo.

Usaremos LM Studio para servir GPT-OSS localmente y lo conectaremos a Elastic Agent Builder.

Al final de este artículo, tendrás un agente de IA personalizado que podrá responder preguntas en lenguaje natural sobre los datos de tus empleados manteniendo el control total sobre tu información y modelo.

Prerrequisitos

Para este artículo, necesitas:

• Elastic Cloud alojaba la versión 9.2, despliegue serverless o local
• Máquina con 32GB de RAM recomendada (mínimo 16GB para GPT-OSS 20B)
• LM Studio instalado
• Escritorio Docker Instalado

¿Por qué usar GPT-OSS?

Con un LLM local tienes el control para desplegarlo en tu propia infraestructura y ajustarlo para adaptarlo a tus propias necesidades. Todo esto manteniendo el control sobre los datos que compartes con el modelo y, por supuesto, no tienes que pagar una tasa de licencia a un proveedor externo.

OpenAI lanzó GPT-OSS el 5 de agosto de 2025, como parte de su compromiso con el ecosistema del modelo abierto.

El modelo de parámetros 20B ofrece:

• Capacidades de uso de herramientas
• Inferencia eficiente
• Compatible con SDK OpenAI
• Compatible con flujos de trabajo agentes

Comparación de referencias:

Arquitectura de soluciones

La arquitectura funciona completamente en tu máquina local. Elastic (que funciona en Docker) se comunica directamente con tu LLM local a través de LM Studio, y Elastic Agent Builder emplea esta conexión para crear agentes de IA personalizados que pueden consultar los datos de tus empleados.

Para más detalles, consulte esta documentación.

Construir un agente de IA para RRHH: Pasos

Dividiremos la implementación en 5 pasos:

1. Configurar LM Studio con un modelo local
2. Despliega Elastic Local con Docker
3. Crea el conector OpenAI en Elastic
4. Sube los datos de los empleados a Elasticsearch
5. Construye y prueba tu agente de IA

Paso 1: Configurar LM Studio con GPT-OSS 20B

LM Studio es una aplicación fácil de usar que te permite ejecutar grandes modelos de lenguaje localmente en tu computadora. Proporciona un servidor API compatible con OpenAI, lo que facilita su integración con herramientas como Elastic sin un proceso de configuración complejo. Para más detalles, consulta la documentación de LM Studio.

Primero, descarga e instala LM Studio desde el sitio web oficial. Una vez instalado, abre la aplicación.

En la interfaz de LM Studio:

1. Ve a la pestaña de búsqueda y busca "GPT-OSS"
2. Selecciona el openai/gpt-oss-20b de OpenAI
3. Haz clic en descargar

El tamaño de este modelo debería ser aproximadamente 12,10GB. La descarga puede tardar unos minutos, dependiendo de tu conexión a Internet.

Una vez descargado el modelo:

1. Ve a la pestaña del servidor local
2. Selecciona el openai/gpt-oss-20b
3. Usa el puerto predeterminado 1234
4. En el panel derecho, ve a Cargar y establece la longitud de contexto en 40K o más

5. Haz clic en iniciar servidor

Deberías ver esto si el servidor está funcionando.

[LM STUDIO SERVER] Success! HTTP server listening on port 1234
[LM STUDIO SERVER] Supported endpoints:
[LM STUDIO SERVER] ->	GET  http://localhost:1234/v1/models
[LM STUDIO SERVER] ->	POST http://localhost:1234/v1/responses
[LM STUDIO SERVER] ->	POST http://localhost:1234/v1/chat/completions
[LM STUDIO SERVER] ->	POST http://localhost:1234/v1/completions
[LM STUDIO SERVER] ->	POST http://localhost:1234/v1/embeddings
Server started.

Paso 2: Desplegar Elastic Local con Docker

Ahora configuraremos Elasticsearch y Kibana localmente usando Docker. Elastic proporciona un script conveniente que gestiona todo el proceso de configuración. Para más detalles, consulte la documentación oficial.

Ejecuta el script de inicio local

Ejecuta el siguiente comando en tu terminal:

curl -fsSL https://elastic.co/start-local | sh

Este guion será:

• Descargar y configurar Elasticsearch y Kibana
• Inicia ambos servicios usando Docker Compose
• Activa automáticamente una licencia de prueba Platinum de 30 días

Producción esperada

Solo espera el siguiente mensaje y almacena la contraseña y la clave API que se muestra; los necesitarás para acceder a Kibana:

🎉 Congrats, Elasticsearch and Kibana are installed and running in Docker!
🌐 Open your browser at http://localhost:5601
   Username: elastic
   Password: KSUlOMNr
🔌 Elasticsearch API endpoint: http://localhost:9200
🔑 API key: cnJGX0pwb0JhOG00cmNJVklUNXg6cnNJdXZWMnM4bncwMllpQlFlUTlWdw==
Learn more at https://github.com/elastic/start-local

Acceso a Kibana

Abre tu navegador y navega a:

http://localhost:5601

Inicia sesión usando las credenciales obtenidas en la salida del terminal.

Habilitar Agent Builder

Una vez iniciado sesión en Kibana, navega a Management > AI > Agent Builder y activa el Agent Builder.

Paso 3: Crea el conector OpenAI en Elastic

Ahora configuraremos Elastic para que use tu LLM local.

Conectores de acceso

1. En Kibana
2. Ve a Configuración > Gestión del Proyecto
3. En Alertas e Información, selecciona Conectores
4. Haz clic en Crear conector

Configurar el conector

Selecciona OpenAI de la lista de conectores. LM Studio emplea el SDK OpenAI, lo que lo hace compatible.

Diligencia el espacio con estos valores:

• Nombre del conector: LM Studio - GPT-OSS 20B
• Selecciona un proveedor de OpenAI: Otros (Servicio compatible con OpenAI)
• URL: http://host.docker.internal:1234/v1/chat/completions
• Modelo por defecto: openai/gpt-oss-20b
• API Key: testkey-123 (cualquier texto funciona, porque LM Studio Server no requiere autenticación.)

Para terminar la configuración, haz clic en Almacenar y probar.

Importante: Activa la opción "Habilitar la llamada a funciones nativas"; esto es necesario para que el Constructor de Agentes funcione correctamente. Si no activas esto, te aparecerá un error de No tool calls found in the response .

Prueba la conexión

El elástico debería probar automáticamente la conexión. Si todo está configurado correctamente, verás un mensaje de éxito como este:

Respuesta:

{
  "status": "ok",
  "data": {
    "id": "chatcmpl-flj9h0hy4wcx4bfson00an",
    "object": "chat.completion",
    "created": 1761189456,
    "model": "openai/gpt-oss-20b",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "Hello! 👋 How can I assist you today?",
          "reasoning": "Just greet.",
          "tool_calls": []
        },
        "logprobs": null,
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 69,
      "completion_tokens": 23,
      "total_tokens": 92
    },
    "stats": {},
    "system_fingerprint": "openai/gpt-oss-20b"
  },
  "actionId": "ee1c3aaf-bad0-4ada-8149-118f52dad757"
}

Paso 4: Subir los datos de los empleados a Elasticsearch

Ahora subiremos el conjunto de datos de empleados de RRHH para demostrar cómo el agente trabaja con datos sensibles. Generé un conjunto de datos ficticio con esta estructura.

Estructura del conjunto de datos

{
  "employee_id": "0f4dce68-2a09-4cb1-b2af-6bcb4821539b",
  "full_name": "Daffi Stiebler",
  "email": "lscutchings0@huffingtonpost.com",
  "date_of_birth": "1975-06-20T15:39:36Z",
  "hire_date": "2025-07-28T00:10:45Z",
  "job_title": "Physical Therapy Assistant",
  "department": "HR",
  "salary": "108455",
  "performance_rating": "Needs Improvement",
  "years_of_experience": 2,
  "skills": "Java",
  "education_level": "Master's Degree",
  "manager": "Carl MacGibbon",
  "emergency_contact": "Leigha Scutchings",
  "home_address": "5571 6th Park"
}

Crea el índice con mapeos

Primero, crea el índice con mapeos adecuados. Ten en cuenta que estamos usando semantic_text campos para algunos campos clave; Esto permite capacidades de búsqueda semántica para nuestro índice.

​​PUT hr-employees
{
  "mappings": {
    "properties": {
      "@timestamp": {
        "type": "date"
      },
      "employee_id": {
        "type": "keyword"
      },
      "full_name": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "email": {
        "type": "keyword"
      },
      "date_of_birth": {
        "type": "date",
        "format": "iso8601"
      },
      "hire_date": {
        "type": "date",
        "format": "iso8601"
      },
      "job_title": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "department": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "salary": {
        "type": "double"
      },
      "performance_rating": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "years_of_experience": {
        "type": "long"
      },
      "skills": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "education_level": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "manager": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "emergency_contact": {
        "type": "keyword"
      },
      "home_address": {
        "type": "keyword"
      },
      "employee_semantic": {
        "type": "semantic_text"
      }
    }
  }
}

Índice con API Bulk

Copia y pega el conjunto de datos en tus Dev Tools en Kibana y ejecutalo:

POST hr-employees/_bulk
{"index": {}}
{"employee_id": "57728b91-e5d7-4fa8-954a-2384040d3886", "full_name": "Filide Gane", "email": "vhallahan1@booking.com", "job_title": "Business Systems Development Analyst", "department": "Marketing", "salary": "$52330.27", "performance_rating": "Meets Expectations", "years_of_experience": 12, "skills": "Java", "education_level": "Bachelor's Degree", "date_of_birth": "2000-02-07T16:49:32Z", "hire_date": "2023-11-07T13:03:16Z", "manager": "Freedman Kings", "emergency_contact": "Vilhelmina Hallahan", "home_address": "75 Dennis Junction"}
{"index": {}}
{"employee_id": "...", ...}

Verifica los datos

Realiza una consulta para verificar:

GET hr-employees/_search

Paso 5: Construye y prueba tu agente de IA

Con todo configurado, es hora de crear un agente de IA personalizado usando Elastic Agent Builder. Para más detalles, consulte la documentación de Elastic.

Agregar el conector

Antes de poder crear nuestro nuevo agente, tenemos que configurar nuestro constructor de agentes para usar nuestro conector personalizado llamado LM Studio - GPT-OSS 20B porque el predeterminado es el Elastic Managed LLM. Para eso, necesitamos ir a Configuración > Gestión de Proyectos > Configuración de GenAI; ahora seleccionamos la que creamos y hacemos clic en Almacenar.

Constructor de Agentes de Acceso

1. Ir a Agentes
2. Haz clic en Crear un nuevo agente

Configurar el agente

Para crear un nuevo agente, los campos requeridos son el ID del agente, el nombre de visualización y las instrucciones de visualización.

Pero hay más opciones de personalización, como las Instrucciones Personalizadas que guían cómo se comportará tu agente e interactuará con tus herramientas, similar a una indicación del sistema, pero para nuestro agente personalizado. Las etiquetas ayudan a organizar tus agentes, el color del avatar y el símbolo del avatar.

Los que elegí para nuestro agente basándome en el conjunto de datos son:

ID del agente: hr_assistant

Instrucciones personalizadas:

You are an HR Analytics Assistant that helps answer questions about employee data.
When responding to queries:
- Provide clear, concise answers
- Include relevant employee details (name, department, salary, skills)
- Format monetary values with currency symbols
- Be professional and maintain data confidentiality

Etiquetas: Human Resources y GPT-OSS

Nombre de visualización: HR Analytics Assistant

Descripción de la exposición:

A specialized AI assistant for Human Resources that helps analyze employee data, compensation, performance metrics, and talent management. Ask questions about employees, departments, salaries, or performance analytics.

Con todos los datos ahí, podemos hacer clic en Almacenar a nuestro nuevo agente.

Prueba al agente

Ahora puedes hacer preguntas en lenguaje natural sobre los datos de tus empleados, y GPT-OSS 20B entenderá la intención y generará una respuesta adecuada.

Pronto:

Which employee is the one with the highest salary in the hr-employees index?

Respuesta:

El proceso de Agente fue:

1. Entiende tu pregunta usando el conector GPT-OSS

2. Generar la consulta Elasticsearch adecuada (usando las herramientas integradas o ES| personalizadoQL)

3. Recuperar los registros de empleados coincidentes

4. Presentar resultados en lenguaje natural con un formato adecuado

A diferencia de la búsqueda léxica tradicional, el agente impulsado por GPT-OSS entiende la intención y el contexto, facilitando encontrar información sin conocer los nombres exactos de los campos o la sintaxis de la consulta. Para más detalles sobre el proceso de pensamiento del agente, consulta este artículo.

Conclusión

En este artículo, creamos un agente de IA personalizado usando el Agent Builder de Elastic para conectarse al modelo OpenAI GPT-OSS que se ejecuta localmente. Al desplegar tanto Elastic como el LLM en tu máquina local, esta arquitectura te permite aprovechar las capacidades de IA generativa manteniendo el control total sobre tus datos, todo ello sin enviar información a servicios externos.

Usamos GPT-OSS 20B como experimento, pero aquí se hacen referencia a los modelos oficialmente recomendados para Elastic Agent Builder. Si necesitas capacidades de razonamiento más avanzadas, también está la variante de parámetros 120B que rinde mejor para escenarios complejos, aunque requiere una máquina de especificaciones más altas para ejecutar localmente. Para más detalles, consulte la documentación oficial de OpenAI.

Hace unas semanas, tuvimos la asombrosa oportunidad de patrocinar Cal Hacks 12.0, uno de los hackatones presenciales más grandes con más de 2000 participantes de todo el mundo. Ofrecimos una pista dedicada al mejor uso de Elastic Agent Builder en Serverless, y la respuesta fue fenomenal. En solo 36 horas, recibimos 29 envíos que usaban Agent Builder de formas creativas, desde la creación de herramientas de inteligencia contra incendios forestales hasta validadores StackOverflow.

Más allá de los impresionantes proyectos, la experiencia en Cal Hacks 12.0 también nos dio algo igualmente valioso: comentarios rápidos y sin filtros de desarrolladores que se encuentran con nuestra Stack por primera vez. Los hackathons son pruebas de presión únicas con plazos ajustados, cero familiaridad previa y obstáculos impredecibles (como los famosos cortes de WiFi). Exponen exactamente dónde brilla la experiencia del desarrollador y dónde aún necesita mejoras. Esto importa aún más ahora, ya que los desarrolladores interactúan con el Elastic Stack de nuevas maneras, cada vez más a través de flujos de trabajo impulsados por LLM. En esta entrada del blog, profundizaremos en lo que los participantes construyeron con Agent Builder y lo que aprendimos en el proceso.

Los proyectos ganadores

Primer puesto: AgentOverflow

Stack Overflow reconstruido para la era de los LLM y los agentes.

Lee más sobre AgentOverflow aquí.

AgentOverflow aborda un problema que la mayoría de los desarrolladores de IA enfrentan: los LLMs alucinan, los historiales de chat desaparecen y los desarrolladores pierden tiempo resolviendo los mismos problemas.

AgentOverflow captura, valida y reactiva pares reales problema-solución, para que los desarrolladores puedan romper la espiral de alucinaciones y enviar más rápido.

Cómo funciona:

1. Compartir JSON - el "Esquema de Solución".

Un clic desde un recurso compartido de Claude extraerá, extrae y ensamblará un JSON de Solución de Compartir, que es un formato estructurado que contiene:

• Problema
• Contexto
• Código
• Etiquetas
• Pasos verificados de la solución.

Un validador (LAVA) comprueba y aplica la estructura, el usuario agrega una línea de contexto extra y luego se almacena e indexa dentro de Elasticsearch.

2. Encontrar solución

Cuando te quedes atascado, haz clic en Find Solution y AgentOverflow extraerá tu conversación actual, la usará para crear una consulta y ejecutará una búsqueda híbrida en Elasticsearch para que aparezca:

• Arreglos clasificados y validados por la comunidad
• Los exactos prompts que originalmente resolvieron el problema

Esto permite a los desarrolladores copiar, pegar y desbloquear rápidamente su sesión actual.

3. MCP - inyección de contexto para LLMs

Al conectarse a las soluciones estructuradas almacenadas dentro de Elasticsearch a través de MCP (Model Context Protocol), los LLM reciben un contexto de alta señal (código, registros, configuraciones, correcciones previas) en tiempo de ejecución sin ruido adicional.

AgentOverflow emplea Agent Builder con Elasticsearch como una capa de memoria estructurada que inyecta el contexto relevante en los LLMs. Esto los transforma de chatbots pasivos en solucionadores de problemas conscientes del contexto.

Segundo puesto: MarketMind

Una visión interpretable en tiempo real de la energía del mercado, impulsada por seis Agentes Elásticos.

Lee más sobre MarketMind aquí.

MarketMind consiguió su spot al ofrecer a los traders novatos una plataforma que convierte datos de mercado fragmentados en señales claras y en tiempo real. En lugar de compaginar la acción del precio, los fundamentos, el sentimiento y la volatilidad entre diferentes herramientas, MarketMind consolida toda esta información en una sola plataforma, ayudando a los traders a obtener información útil. Este proyecto también empleó algunos complejos ES|QL consulta al construir sus agentes.

Cómo funciona:

1. Recopilar datos de mercado en tiempo real

MarketMind extrae métricas de precio-acción, fundamentos, sentimiento, volatilidad y riesgo de Yahoo Finance. Estos datos se ingieren y organizan en múltiples índices de Elasticsearch.

2. Seis agentes especializados analizan el mercado

Cada agente, construido con Agent Builder, se centra en una capa diferente del mercado. Leen desde un índice de Elasticsearch, calculan sus propias métricas específicas de dominio y generan una salida JSON estandarizada con puntajes y razonamientos.

3. Agregar señales en un modelo unificado de "energía de mercado"

Las salidas combinadas aparecen como pulsos brillantes alrededor de cada acción, ilustrando si el impulso está creciendo, el riesgo está aumentando o el sentimiento está cambiando.

4. Visualizar percepciones

El frontend se construyó con React y Next.js, usando TypeScript, gráficos basados en física SVG y Chart.js para gráficos en tiempo real con candelabros. Esto convierte el análisis en bruto en feedback accionable en tiempo real.

Otros proyectos interesantes:

Aquí tienes otros candidatos fuertes que usaron Elastic en diferentes partes de su stack:

Encuentra aquí la lista completa de proyectos que se presentaron a nuestra especialidad.

Lo que aprendimos de los desarrolladores

• Agent Builder es fácil de usar:

La mayoría de los equipos nunca usaron Elastic antes y aún así podían crear agentes rápidamente con poco apoyo. Organizamos un taller para quienes necesitaban más orientación, pero la mayoría pudo absorber sus datos y crear un agente para realizar acciones sobre esos datos.

• Los LLMs son excelentes en kNN consultas, pero aún necesitan orientación para generar ES|QL:

Pidiendo a ChatGPT-5 que genere ES|Las consultas QL devolvían información incorrecta, a menudo mezclando ES|QL y SQL. Alimentar al LLM la documentación en un archivo de markdown parecía una solución viable.

• ES| solo para instantáneasFunciones QL filtradas en documentos:

Las próximas funciones de agregación FIRST y LAST pasaron sin querer a nuestro ES|Documentos de QL. Como enviamos esa documentación a ChatGPT, el modelo empleó fielmente estas funciones, aunque aún no estén disponibles en Serverless. Gracias a los comentarios del grupo, ingeniería abrió y fusionó rápidamente una corrección para eliminar las funciones de la documentación publicada (PR #137341).

• Falta orientación específica para Serverless:

Un equipo intentó activar LOOKUP JOIN en un índice que no se creó en modo búsqueda. El mensaje de error les hizo perseguir comandos que no existen en Serverless. Transmitimos esto al equipo de producto, que inmediatamente abrió una corrección para un mensaje específico y accionable para Serverless. A largo plazo, la visión es ocultar por completo la complejidad del reindexado (Número #4838).

• Valor de los eventos presenciales:

Los hackathons online son geniales, pero nada iguala el bucle de retroalimentación rápida que tienes cuando depuras codo a codo con los constructores. Vimos cómo los equipos integraban Agent Builder en diferentes casos de uso, y detectamos la experiencia de los desarrolladores con ES|QL podría mejorar y solucionar los problemas mucho más rápido que intentar hacerlo por canales asincrónicos.

Conclusión

Cal Hacks 12.0 nos ofreció más que un fin de semana de demos chulas; también nos dio una visión de cómo los nuevos desarrolladores interactúan con el Elastic Stack. En tan solo 36 horas, vimos a los equipos adquirir Agent Builder, incorporar datos en Elasticsearch, diseñar sistemas multiagente y probar nuestras funcionalidades de diversas maneras. El evento también nos recordó por qué son importantes los eventos presenciales. Los rápidos bucles de retroalimentación, las conversaciones reales y la depuración práctica nos ayudaron a entender las necesidades actuales de los desarrolladores. Estamos entusiasmados por devolver lo aprendido al equipo de ingeniería. Nos vemos en el próximo hackathon.

Este es el artículo complementario al artículo "¡Creando una redacción para agentes LLM con protocolo A2A y MCP en Elasticsearch!", que explicaba los beneficios de implementar tanto las arquitecturas A2A como MCP dentro del mismo agente para aprovechar realmente los beneficios únicos de ambos frameworks. Hay un repositorio disponible si deseas ejecutar la demo por tu cuenta.

Vamos a repasar cómo colaboran nuestros agentes de redacción empleando tanto A2A como MCP para producir un artículo de noticias. El repositorio adjunto para ver a los agentes en acción se puede encontrar aquí.

Paso 1: Asignación de la historia

El Jefe de Noticias (actuando como cliente) asigna una noticia:

{
  "message_type": "task_request",
  "sender": "news_chief",
  "receiver": "reporter_agent",
  "payload": {
    "task_id": "story_renewable_energy_2024",
    "assignment": {
      "topic": "Renewable Energy Adoption in Europe",
      "angle": "Policy changes driving solar and wind expansion",
      "target_length": 1200,
      "deadline": "2025-09-30T18:00:00Z"
    }
  }
}

Paso 2: El reportero aplicar investigación

El Agente Reportero reconoce que necesita información de fondo y delega al Agente Investigador mediante A2A:

{
  "message_type": "task_request",
  "sender": "reporter_agent",
  "receiver": "researcher_agent",
  "payload": {
    "task_id": "research_eu_renewable_2024",
    "parent_task_id": "story_renewable_energy_2024",
    "capability": "fact_gathering",
    "parameters": {
      "queries": [
        "EU renewable energy capacity 2024",
        "Solar installations growth Europe",
        "Wind energy policy changes 2024"
      ],
      "depth": "comprehensive"
    }
  }
}

Paso 3: El reportero aplicar contexto histórico al Agente de Archivo

El Reporter Agent reconoce que el contexto histórico fortalecería la historia. Delega al Agente de Archivo (impulsado por el Agente A2A de Elastic) a través de A2A para buscar en el archivo de artículos impulsado por Elasticsearch de la redacción:

{
  "message_type": "task_request",
  "sender": "reporter_agent",
  "receiver": "archive_agent",
  "payload": {
    "task_id": "archive_search_renewable_2024",
    "parent_task_id": "story_renewable_energy_2024",
    "capability": "search_archive",
    "parameters": {
      "query": "European renewable energy policy changes and adoption trends over past 5 years",
      "focus_areas": ["solar", "wind", "policy", "Germany", "France"],
      "time_range": "2019-2024",
      "result_count": 10
    }
  }
}

Paso 4: El Agente de Archivo emplea el Agente Elastic A2A con MCP

El Archive Agent emplea el A2A Agent de Elastic, que a su vez emplea MCP para acceder a las herramientas de Elasticsearch. Esto demuestra la arquitectura híbrida donde A2A permite la colaboración entre agentes mientras que MCP proporciona acceso a herramientas:

# Archive Agent using Elastic A2A Agent
async def search_historical_articles(self, query_params):
    # The Archive Agent sends a request to Elastic's A2A Agent
    elastic_response = await self.a2a_client.send_request(
        agent="elastic_agent",
        capability="search_and_analyze",
        parameters={
            "natural_language_query": query_params["query"],
            "index_pattern": "newsroom-articles-*",
            "filters": {
                "topics": query_params["focus_areas"],
                "date_range": query_params["time_range"]
            },
            "analysis_type": "trend_analysis"
        }
    )
    
    # Elastic's A2A Agent internally uses MCP tools:
    # - platform.core.search (to find relevant articles)
    # - platform.core.generate_esql (to analyze trends)
    # - platform.core.index_explorer (to identify relevant indices)
    
    return elastic_response

El Agente de Archivo recibe datos históricos completos del Agente A2A de Elastic y los devuelve al Reportero:

{
  "message_type": "task_response",
  "sender": "archive_agent",
  "receiver": "reporter_agent",
  "payload": {
    "task_id": "archive_search_renewable_2024",
    "status": "completed",
    "archive_data": {
      "historical_articles": [
        {
          "title": "Germany's Energiewende: Five Years of Solar Growth",
          "published": "2022-06-15",
          "key_points": [
            "Germany added 7 GW annually 2020-2022",
            "Policy subsidies drove 60% of growth"
          ],
          "relevance_score": 0.94
        },
        {
          "title": "France Balances Nuclear and Renewables",
          "published": "2023-03-20",
          "key_points": [
            "France increased renewable target to 40% by 2030",
            "Solar capacity doubled 2021-2023"
          ],
          "relevance_score": 0.89
        }
      ],
      "trend_analysis": {
        "coverage_frequency": "EU renewable stories increased 150% since 2019",
        "emerging_themes": ["policy incentives", "grid modernization", "battery storage"],
        "coverage_gaps": ["Small member states", "offshore wind permitting"]
      },
      "total_articles_found": 47,
      "search_confidence": 0.91
    }
  }
}

Este paso demuestra cómo el Agente A2A de Elastic se integra en el flujo de trabajo de la redacción. El Agente de Archivo (un agente específico de redacción) coordina con el Agente A2A de Elastic (un especialista externo) para aprovechar las poderosas capacidades de búsqueda y análisis de Elasticsearch. El agente de Elastic emplea MCP internamente para acceder a las herramientas de Elasticsearch, mostrando la separación limpia entre la coordinación del agente (A2A) y el acceso a la herramienta (MCP).

Paso 5: El investigador emplea servidores MCP

El Agente Investigador accede a múltiples servidores MCP para recopilar información:

# Researcher Agent using MCP to access tools
async def gather_facts(self, queries):
    results = []
    
    # Use News API MCP Server
    news_data = await self.mcp_client.invoke_tool(
        server="news_api_mcp",
        tool="search_articles",
        parameters={
            "query": queries[0],
            "date_range": "2024-01-01 to 2024-09-30",
            "sources": ["reuters", "bloomberg", "euractiv"]
        }
    )
    
    # Use Statistics MCP Server
    stats_data = await self.mcp_client.invoke_tool(
        server="eurostat_mcp",
        tool="get_energy_statistics",
        parameters={
            "metrics": ["solar_capacity_mw", "wind_capacity_mw"],
            "countries": ["EU27"],
            "year": 2024
        }
    )
    
    # Use Fact-Checking MCP Server
    verified_facts = await self.mcp_client.invoke_tool(
        server="factcheck_mcp",
        tool="verify_claims",
        parameters={
            "claims": [
                "EU solar capacity increased 40% in 2024",
                "Germany leads in wind installations"
            ]
        }
    )
    
    return self._synthesize_research(news_data, stats_data, verified_facts)

Paso 6: El investigador devuelve los datos al Reportero

El Agente Investigador envía una investigación exhaustiva de vuelta a través de A2A:

{
  "message_type": "task_response",
  "sender": "researcher_agent",
  "receiver": "reporter_agent",
  "payload": {
    "task_id": "research_eu_renewable_2024",
    "status": "completed",
    "research_data": {
      "key_facts": [
        {
          "claim": "EU solar capacity reached 260 GW in 2024",
          "source": "Eurostat Q3 2024 Report",
          "confidence": 0.95,
          "verified": true
        },
        {
          "claim": "Germany installed 12 GW of wind capacity in 2024",
          "source": "German Federal Network Agency",
          "confidence": 0.92,
          "verified": true
        }
      ],
      "statistics": {
        "solar_growth_rate": "35%",
        "wind_growth_rate": "28%"
      },
      "sources_count": 15
    }
  }
}

Paso 7: Reportero escribe artículo

El Reporter Agent emplea los datos de investigación y sus propias capacidades de LLM para redactar el artículo. Durante la redacción, el Reportero emplea los servidores MCP para el estilo y las plantillas:

# Reporter Agent writing with MCP assistance
async def write_article(self, research_data, assignment):
    # Get style guidelines via MCP
    style_guide = await self.mcp_client.get_resource(
        server="newsroom_mcp",
        resource="style://editorial/ap_style_guide"
    )
    
    # Get article template via MCP
    template = await self.mcp_client.get_resource(
        server="newsroom_mcp",
        resource="template://articles/news_story"
    )
    
    # Generate article using LLM + research + style
    draft = await self.llm.generate(
        prompt=f"""
        Write a news article following these guidelines:
        {style_guide}
        
        Using this template:
        {template}
        
        Based on this research:
        {research_data}
        
        Assignment: {assignment}
        """
    )
    
    # Self-evaluate confidence in claims
    confidence_check = await self._evaluate_confidence(draft)
    
    return draft, confidence_check

Paso 8: la baja confianza desencadena la re-investigación

El Agente Reportero evalúa su borrador y encuentra que una afirmación tiene baja confianza. Envía otra solicitud al Agente Investigador:

{
  "message_type": "collaboration_request",
  "sender": "reporter_agent",
  "receiver": "researcher_agent",
  "payload": {
    "request_type": "fact_verification",
    "claims": [
      {
        "text": "France's nuclear phase-down contributed to 15% increase in renewable capacity",
        "context": "Discussing policy drivers for renewable growth",
        "current_confidence": 0.45,
        "required_confidence": 0.80
      }
    ],
    "urgency": "high"
  }
}

El investigador verifica la afirmación empleando servidores MCP de verificación de hechos y devuelve información actualizada:

{
  "message_type": "collaboration_response",
  "sender": "researcher_agent",
  "receiver": "reporter_agent",
  "payload": {
    "verified_claims": [
      {
        "original_claim": "France's nuclear phase-down contributed to 15% increase...",
        "verified_claim": "France's renewable capacity increased 18% in 2024, partially offsetting reduced nuclear output",
        "confidence": 0.88,
        "corrections": "Percentage was 18%, not 15%; nuclear phase-down is gradual, not primary driver",
        "sources": ["RTE France", "French Energy Ministry Report 2024"]
      }
    ]
  }
}

Paso 9: El reportero revisa y envía al editor

El Reportero incorpora los hechos verificados y envía el borrador completo al Agente Editor a través de A2A:

{
  "message_type": "task_request",
  "sender": "reporter_agent",
  "receiver": "editor_agent",
  "payload": {
    "task_id": "edit_renewable_story",
    "parent_task_id": "story_renewable_energy_2024",
    "content": {
      "headline": "Europe's Renewable Revolution: Solar and Wind Surge 30% in 2024",
      "body": "[Full article text...]",
      "word_count": 1185,
      "sources": [/* array of sources */]
    },
    "editing_requirements": {
      "check_style": true,
      "check_facts": true,
      "check_seo": true
    }
  }
}

Paso 10: Revisiones del editor usando herramientas MCP

El Editor Agent emplea múltiples servidores MCP para revisar el artículo:

# Editor Agent using MCP for quality checks
async def review_article(self, content):
    # Grammar and style check
    grammar_issues = await self.mcp_client.invoke_tool(
        server="grammarly_mcp",
        tool="check_document",
        parameters={"text": content["body"]}
    )
    
    # SEO optimization check
    seo_analysis = await self.mcp_client.invoke_tool(
        server="seo_mcp",
        tool="analyze_content",
        parameters={
            "headline": content["headline"],
            "body": content["body"],
            "target_keywords": ["renewable energy", "Europe", "solar", "wind"]
        }
    )
    
    # Plagiarism check
    originality = await self.mcp_client.invoke_tool(
        server="plagiarism_mcp",
        tool="check_originality",
        parameters={"text": content["body"]}
    )
    
    # Generate editorial feedback
    feedback = await self._generate_feedback(
        grammar_issues, 
        seo_analysis, 
        originality
    )
    
    return feedback

El editor aprueba el artículo y lo envía hacia adelante:

{
  "message_type": "task_response",
  "sender": "editor_agent",
  "receiver": "reporter_agent",
  "payload": {
    "status": "approved",
    "quality_score": 9.2,
    "minor_edits": [
      "Changed 'surge' to 'increased' in paragraph 3 for AP style consistency",
      "Added Oxford comma in list of countries"
    ],
    "approved_content": "[Final edited article]"
  }
}

Paso 11: El editor publica vía CI/CD

Finalmente, el Agente de Impresora publica el artículo aprobado empleando los servidores MCP para la tubería CMS y CI/CD:

# Publisher Agent publishing via MCP
async def publish_article(self, content, metadata):
    # Upload to CMS via MCP
    cms_result = await self.mcp_client.invoke_tool(
        server="wordpress_mcp",
        tool="create_post",
        parameters={
            "title": content["headline"],
            "body": content["body"],
            "status": "draft",
            "categories": metadata["categories"],
            "tags": metadata["tags"],
            "featured_image_url": metadata["image_url"]
        }
    )
    
    post_id = cms_result["post_id"]
    
    # Trigger CI/CD deployment via MCP
    deploy_result = await self.mcp_client.invoke_tool(
        server="cicd_mcp",
        tool="trigger_deployment",
        parameters={
            "pipeline": "publish_article",
            "environment": "production",
            "post_id": post_id,
            "schedule": "immediate"
        }
    )
    
    # Track analytics
    await self.mcp_client.invoke_tool(
        server="analytics_mcp",
        tool="register_publication",
        parameters={
            "post_id": post_id,
            "publish_time": datetime.now().isoformat(),
            "story_id": metadata["story_id"]
        }
    )
    
    return {
        "status": "published",
        "post_id": post_id,
        "url": f"https://newsroom.example.com/articles/{post_id}",
        "deployment_id": deploy_result["deployment_id"]
    }

El editor confirma la publicación a través de A2A:

{
  "message_type": "task_complete",
  "sender": "printer_agent",
  "receiver": "news_chief",
  "payload": {
    "task_id": "story_renewable_energy_2024",
    "status": "published",
    "publication": {
      "url": "https://newsroom.example.com/articles/renewable-europe-2024",
      "published_at": "2025-09-30T17:45:00Z",
      "post_id": "12345"
    },
    "workflow_metrics": {
      "total_time_minutes": 45,
      "agents_involved": ["reporter", "researcher", "archive", "editor", "printer"],
      "iterations": 2,
      "mcp_calls": 12
    }
  }
}

Aquí está la secuencia completa del flujo de trabajo A2A en el repositorio adjunto usando los mismos Agentes descritos anteriormente.