Qué significa la compatibilidad con versiones anteriores para la API de Dashboards de Kibana

Durante la vista previa técnica, la forma de la API podría cambiar entre versiones.[1] Eso ya no es así. Disponibilidad general (GA) significa:

• Compatibilidad total con versiones anteriores. Con el tiempo, se agregarán nuevos campos y tipos de panel, pero los campos y el comportamiento actuales se mantendrán sin cambios. Cualquier cambio futuro que rompa la compatibilidad será considerado con mucho cuidado y solo se introducirá en una nueva versión principal del stack.

• Listo para producción con soporte completo. La API ofrece las garantías completas de soporte de Elastic. Puedes usarla de manera segura en entornos de producción para despliegues automatizados, promoción del entorno y administración programática del dashboard.

Nuevos endpoints de la API Kibana para los paneles de etiquetas, markdown y enlaces

Elastic 9.5 también introduce un nuevo endpoint independiente para etiquetas, que permite categorizar y filtrar paneles. Ahora puedes administrarlos mediante programación a través de endpoints CRUD dedicados, lo que facilita organizar paneles a gran escala en todos los entornos.

Los nuevos endpoints de paneles Markdown y Enlaces ya están disponibles en Serverless y llegarán en la próxima versión de la pila (9.6).

¿Qué tipos de paneles soporta la API de Kibana Dashboards?

La API de dashboards admite todos los paneles por valor en la versión 9.5 (los definidos directamente en un dashboard, a diferencia de los paneles de biblioteca guardados para su reutilización). Cada tipo de panel admitido tiene un esquema tipificado y validado.

Tipo de panel

Estado

Gráficos XY

Con soporte

Métricas

Con soporte

Circular

Con soporte

Calibre

Con soporte

Mapa de calor

Con soporte

Tablas de datos

Con soporte

Mapa de árbol

Con soporte

Sesiones de Discover

Con soporte

Controles

Con soporte

Markdown

Con soporte

Enlaces

Con soporte

Paneles de ML

Con soporte

Paneles de Observability

Con soporte

Mapas

Próximamente

Vega

Próximamente

Cómo gestionar los dashboards de Kibana como código

La API de dashboards permite un flujo de trabajo completo de dashboards como código: exportar un dashboard como JSON limpio y diferenciable, hacer commit en Git como fuente de verdad, revisar los cambios en pull requests, y desplegar la misma definición en desarrollo, staging y producción. Una vez que un dashboard se administra como código, trata a Git como la única fuente de verdad: los cambios efectuados directamente en la UI se sobrescriben la próxima vez que despliegues.

El principal desafío al mover un dashboard entre espacios, clústeres o etapas es que los dashboards hacen referencia a objetos como Data view y visualizaciones de biblioteca mediante un ID. Debido a que estos ID se generan automáticamente y difieren de un entorno a otro, un dashboard exportado desde un entorno puede apuntar a objetos que no existen en otro. Hay tres formas de manejarlo, enumeradas aquí de la más a la menos automatizada:

• Usa Terraform. El proveedor Elastic Stack Terraform rastrea cada recurso y mapea automáticamente los ID por entorno, por lo que las referencias se mantienen estables mientras promocionas un dashboard desde el desarrollo hasta la producción.

• Definir por valor Paneles de lenguaje de búsqueda de Elasticsearch (ES|QL). La forma más portátil de construir un panel es definir su visualización con ES|QL directamente en el dashboard. Una consulta ES|QL lee los índices que se especifican en ella, por lo que el panel no contiene referencias externas a vistas de datos ni a objetos de biblioteca. El resultado es un dashboard totalmente autónomo y portátil.

• Asigna ID coincidentes. Si haces referencia a objetos guardados, como Data view o visualizaciones de biblioteca, créalos con un ID elegido usando PUT (upsert) en lugar de POST (que genera automáticamente un ID). Emplea ID legibles por humanos, como logs-prod, para que sean fáciles de reutilizar y reconocer en diferentes entornos.

Para un recorrido detallado de estos patrones de portabilidad y del flujo de trabajo completo de dashboards como código, consulta la documentación de Gestionar dashboards como código.

Crea un dashboard de Kibana con la API de dashboards usando PUT

Aquí hay un ejemplo rápido de crear un dashboard con un panel métrico usando PUT en lugar de POST para asignar un ID personalizado usando el nombre del dashboard (service-health-overview). La misma lógica funciona para crear visualizaciones independientes guardadas en la biblioteca.

Roadmap de la API de paneles de Kibana: Maps, Vega y endpoints independientes

Estamos ampliando activamente el alcance de la API. El siguiente paso es agregar compatibilidad con mapas y paneles Vega, incluyendo esquemas tipados para ellos. También estamos creando endpoints CRUD independientes para las sesiones de Discover (más allá de su compatibilidad actual como paneles del dashboard), Vega, Maps y Anotaciones, desacoplados del ciclo de vida del dashboard.

Para las definiciones completas de esquemas, visita la documentación de la API de Dashboards. Para los usuarios de Terraform, el proveedor Terraform de Elastic Stack es compatible con la API GA Dashboards.

Nota

1. Los endpoints de núcleo no han cambiado desde la vista previa técnica. Si construiste integraciones contra 9.4, funcionan en 9.5. Los únicos cambios incompatibles son dos menores que afectan al listado del dashboard y a los formatos de unidades de duración, documentados aquí.

Los modelos de IA más potentes se ejecutan en instalaciones cloud remotas con acceso a través de una API web, lo que significa que tienes que confiar en tu proveedor de servicios de IA para la seguridad, la disponibilidad del servicio y los precios estables. No puedes alinear fácilmente las exigencias razonables de confiabilidad, privacidad, costos manejables y una buena gobernanza de datos con un uso de la IA cada vez más potente, sofisticado e intensivo en recursos.

Las regulaciones gubernamentales, los fallos judiciales y las consideraciones comerciales efectuadas en interés de terceros han dado como recientemente derivaron en la restricción del acceso a servicios específicos. Y, aunque puedas cambiar a otros servicios, los modelos de IA no son componentes que se puedan intercambiar simplemente cuando quieras. Las aplicaciones que usan incrustaciones semánticas dependen de tener acceso a los mismos modelos al momento de la búsqueda que al momento de la ingesta de datos. Perder el acceso a tu modelo de incrustación significa que tu sistema de búsqueda se detiene.

Los modelos de precios de AI agravan ese riesgo. Las declaraciones financieras recientes de los principales proveedores de IA dan a los clientes buenas razones para preocuparse por los posibles aumentos de precios. La dependencia de productos con costos impredecibles suma más riesgo a las inversiones en IA intensivas en capital que tal vez no generen retornos claros.

Jina On-Prem es la respuesta de Elastic a estos desafíos.

¿Quién necesita IA local?

El alojamiento local y el control directo sobre tus modelos de IA brindan soporte a una variedad de demandas técnicas, requisitos de la industria e intereses comerciales.

La instalación local reduce lo que pagas a tus proveedores de servicios de IA, pero traslada el costo del hardware y del acceso confiable a tu organización. Dependiendo de tu volumen de uso, simplemente puede ser más económico. Pero hay razones adicionales y apremiantes para considerar ejecutar tu propia IA. Si alguno de los problemas descritos a continuación afecta a tu empresa, considera una solución de IA local como Jina On-Prem. Esta lista no es exhaustiva.

Caso de uso

¿Por qué local?

Ejemplo

Aislado/alta seguridad

Sin transmisión de datos salientes; aislamiento completo de la red

Defensa, inteligencia, investigación clasificada

Cumplimiento normativo

Soberanía de datos; sin transmisión transfronteriza ni exposición a terceros

Atención médica (Ley de Portabilidad y Responsabilidad de los Seguros Médicos [HIPAA]), finanzas, empresas de la UE (Reglamento General de Protección de Datos [RGPD])

Crítico para la latencia

Cero dependencia de red; ninguna tolerancia a las fallas de conexión

Robótica, computación perimetral, vehículos, buques

Previsibilidad de costos

Costo fijo de infraestructura frente a precios por token con tarifas futuras inciertas

Cargas de trabajo de inferencia continua de alto volumen

Reducción de responsabilidad

Sin exposición de datos a terceros; mantiene el privilegio legal y el deber de cuidado

Firmas de abogados, agencias gubernamentales

Por qué los sistemas aislados y protegidos por firewall necesitan IA local

Los sistemas aislados de la red y protegidos por firewall no pueden usar API de IA externas. Jina On-Prem se ejecuta por completo dentro de tu infraestructura sin conexiones salientes.

Para las organizaciones que gestionan datos especialmente confidenciales, las consideraciones de seguridad y privacidad son primordiales. De poco sirve invertir en proteger tus datos confidenciales si inmediatamente se los entregas a un tercero remoto que puede tener una seguridad insuficiente o que podría estar sujeto a las exigencias de un gobierno extranjero.

Los empleados de organizaciones que manejan datos confidenciales suelen recibir cierta capacitación sobre el manejo seguro de datos, pero esto no es muy efectivo cuando todos tienen navegadores web que pueden estar abiertos en cualquier página de Internet mientras manejan esos datos. El aislamiento es la medida de seguridad más efectiva disponible, ya sea mediante aislamiento de red o firewalls muy restrictivos, pero eso dificulta el uso de servicios externos de cualquier tipo.

IA local para sistemas sensibles a la latencia y de alta disponibilidad

El software como servicio y la computación en la nube representan una solución intermedia entre el costo de ofrecer servicios muy accesibles y confiables en tus propias computadoras y delegar el problema a un tercero. Pero vienen con latencia variable, interrupciones y una pérdida total de control cuando las cosas salen mal. Los servicios de IA no son la excepción. Si tu sistema de búsqueda queda fuera de línea cuando no puedes acceder a tu modelo de embedding, es posible que ya no parezca una buena solución intermedia.

Además, confiar en la IA externa siempre implica riesgos que no puedes prever ni gestionar fácilmente. El acceso a internet y la latencia de red pueden degradarse sin previo aviso como resultado de acontecimientos políticos, mal tiempo o barcos que arrastran sus anclas sobre cables de fibra óptica submarinos. Los gobiernos pueden usar prohibiciones de exportación para bloquear repentinamente el acceso a los modelos de IA, y recientemente lo han hecho. Los proveedores de servicios de IA a veces retiran modelos para inducirte a cambiar a otros más nuevos. La flexibilidad y los costos gestionados de los servicios externos deben equilibrarse con los riesgos de la dependencia.

IA local para el cumplimiento del RGPD, la HIPAA y la soberanía de datos

Las organizaciones que recopilan datos están sujetas a normativas cada vez más estrictas que a menudo difieren entre jurisdicciones y pueden imponer requisitos contradictorios. En particular, las reglas de la HIPAA imponen protecciones de datos muy estrictas a los proveedores de salud estadounidenses, y las sólidas leyes generales de protección de datos en Canadá, la Unión Europea y muchas jurisdicciones asiáticas exigen que todas las empresas que manejan información personal lo hagan de manera segura y limiten la transmisión de dichos datos a otras partes u otras jurisdicciones. Estas reglas pueden incluso imponer obligaciones a entidades extranjeras si tienen algún cliente en esas jurisdicciones. Las instituciones financieras suelen estar sujetas a reglas aún más estrictas y asumen la misma responsabilidad directa en cuanto a la seguridad de la información que las que aplican para protegerse contra otras formas de actividad criminal.

El cumplimiento normativo puede ser incompatible con los servicios de IA externos, especialmente si usarlos implica la transmisión transfronteriza de datos.

Además, los eventos recientes muestran que las reglas que restringen la ubicación física de los almacenes de datos pueden no ser una fuente confiable de protección cuando los proveedores de servicios de nube internacionales están sujetos a la presión de gobiernos extranjeros. Las leyes locales pueden entrar en conflicto entre jurisdicciones, lo que exige el almacenamiento y procesamiento local de datos e imposibilita el uso de servicios de terceros. En algunos casos, la única solución es llevar todas las partes de tus procesos de forma interna, incluidos tus sistemas de IA.

Riesgos de responsabilidad de la IA por la transmisión de datos de terceros

Las leyes de protección de datos y los deberes de cuidado reconocidos respecto de los datos confidenciales suelen tener implicaciones de responsabilidad, a veces muy graves. Puedes ser responsable del manejo de tus datos por parte de terceros proveedores de servicios. Si bien los tribunales y los procedimientos legales pueden brindar algunas protecciones retrospectivas frente a proveedores de servicios que no cumplen los requisitos de seguridad, esos recursos no están disponibles ni son generalmente efectivos contra actores de seguridad nacional, las fuerzas de orden público o hackers criminales.

Para los gobiernos, ya ha habido casos de proveedores de servicios de nube transfronterizos que revelan información estatal confidencial a actores extranjeros.

Pero, aunque no te preocupen los gobiernos extranjeros o los hackers, y aunque tus proveedores de servicios de IA externos sean seguros en sí mismos, el solo hecho de que sean externos puede generar responsabilidades.

Por ejemplo, en la mayoría de las jurisdicciones, las comunicaciones de los abogados con sus clientes gozan de protecciones legales especiales, y los despachos de abogados tienen responsabilidades estrictas al grabar o almacenar esta información. En Estados Unidos, este “privilegio abogado-cliente” es tan famoso que es un elemento central en las tramas de películas y series de TV. Pero una de las formas en que ese privilegio se puede perder es comunicando información a alguien que no tiene este privilegio, y los avances recientes sugieren que los proveedores externos de servicios de IA podrían calificar.

Es posible, al menos en Estados Unidos, que el solo uso de servicios de IA de terceros a través de una API de internet, como modelos de incrustaciones que ofrecen servicios para indexar, infrinja reglas críticas de confidencialidad. Un bufete de abogados podría ser demandado, sancionado o inhabilitado tan solo por usar software hospedado externamente, incluso si no ocurre ninguna brecha de seguridad.

IA local para sistemas offline, de borde y aislados físicamente

Los sistemas informáticos no solo se aíslan por razones de seguridad. Por ejemplo, los vehículos en movimiento no pueden depender del acceso a Internet para ninguna función esencial. Los barcos y las aeronaves cuentan con sistemas informáticos a bordo muy amplios que deben funcionar sin conexiones a Internet y, por lo tanto, no pueden usar servicios de IA externos. Las plataformas marítimas, las instalaciones remotas en zonas silvestres y los servicios informáticos en el Ártico, la Antártida y pequeñas islas sin conexiones físicas adecuadas a las redes globales son ejemplos de instalaciones que se benefician de hospedar localmente todos los servicios que necesitan. A medida que aumenta el rol de la IA en la informática empresarial, resulta más importante abordar estas limitaciones.

Las aplicaciones emergentes de la IA a sistemas físicos (robótica y otros casos de uso espacialmente delimitados u orientados al mundo exterior, como sistemas de gestión logística o incluso cajas de supermercado) pueden estar conectadas a la internet global, pero no tienen tolerancia a las fallas de conexión o los picos de latencia. Si dependen de un sistema de IA para funcionar, ese sistema de IA debe ser lo más local y confiable posible.

¿Quién no necesita IA local?

Los servicios de software remotos y la IA fuera de las instalaciones sí tienen beneficios. Ejecutar modelos de IA puede requerir procesadores costosos y de alto consumo de energía con una vida útil notoriamente corta. El acceso a hardware de alta calidad es particularmente difícil en este momento debido a factores del mercado e impactos económicos externos. Dadas las circunstancias, puede tener sentido pagar por token para usar una API externa en lugar de asumir los elevados costos de capital de la IA local.

Las API externas son más útiles para los usuarios intermitentes. Si usas modelos de IA principalmente para procesar datos en batch para análisis, en lugar de ejecutar un sistema de búsqueda que tenga que estar en línea todo el tiempo, tiene poco sentido invertir en hardware con uso intensivo de capital e instalaciones locales.

Además, cuando el procesamiento de tus datos ya en la nube por razones de confiabilidad y accesibilidad, usar servicios de IA ubicados en la misma infraestructura de nube puede ofrecer una mejor relación precio-calidad que introducir tu propio despliegue de modelo de IA con licencia. Ya dependes de tu proveedor de servicios en la nube, por lo que depender de sus servicios de IA no añade mucho riesgo.

Si tu caso de uso se ajusta a esa descripción, los modelos de Jina AI están disponibles en EIS, AWS Marketplace y Google Cloud Platform específicamente para satisfacer tus necesidades.

La tabla a continuación resume los factores clave. La respuesta que obtengas depende de tus datos, infraestructura y patrón de uso.

Factor

Preferentemente local

API de nube preferida

Patrón de uso

Inferencia continua o de alto volumen

Procesamiento intermitente o por batch

Sensibilidad de los datos

Regulado, soberano o clasificado

Sin restricciones transfronterizas ni de terceros

Entorno de red

Aislado, protegido por firewall o poco confiable

Internet estable y siempre activa

Infraestructura actual

Tienes o puedes adquirir hardware de GPU

Ya hospedada en la nube con IA coubicada

Modelo de costos

Hardware fijo + licencia; predecible a escala

Por token; menor costo inicial, variable a largo plazo

Tolerancia a la latencia

Ninguna (robótica, borde, tiempo real)

La variabilidad de la red es aceptable

Responsabilidad operativa

Tu equipo administra el hardware y la disponibilidad

El proveedor gestiona el hardware y las actualizaciones; tú gestionas la integración

Tienes que considerar los costos y beneficios a la luz de tus circunstancias particulares y de tus casos de uso, teniendo en cuenta los problemas destacados en la sección anterior que se apliquen a ti. El análisis costo-beneficio sin duda cambiará con el tiempo. No podemos predecir el futuro de la industria de la IA o los precios del hardware incluso a corto plazo.

Presentamos Jina On-Prem

Para los usuarios que pueden beneficiarse de los servicios de IA locales, presentamos Jina On-Prem, una suite de instalación totalmente independiente para los modelos de alto rendimiento de Jina AI.

Los modelos de Jina AI igualan la precisión de los modelos de incrustación varias veces más grandes, lo que reduce los costos informáticos, la huella de memoria y los requisitos de hardware. Esto los convierte en una opción ideal para los usuarios que quieren o necesitan mantener su IA de forma local. Las licencias comerciales están disponibles con soluciones escalables y de precio proporcional para casos de uso de todas las envergaduras.

¿Qué esquemas de API soporta Jina On-Prem?

• Disponible como una colección completa de dependencias para instalación local o como un contenedor docker que puedes instalar y ejecutar en minutos.

• Las instalaciones de Jina On-Prem no hacen llamadas a sistemas externos.

  • Sin llamadas a Hugging Face Hub ni a ningún registro de modelos (HF_HUB_OFFLINE=1 y TRANSFORMERS_OFFLINE=1 están integrados).

  • No hay un servidor de licencias.

  • No hay endpoints de telemetría o de logging.

• Soporta hardware de CPU y GPU, con autodetección de GPU.

• Todos los 28 modelos de Jina AI disponibles, incluidos los últimos modelos de incrustación multimodal jina-embeddings-v5-omni y jina-reranker-v3.

• Acceso mediante esquemas estándar de API de IA: API de Jina, OpenAI, Cohere, Voyage AI y Gemini. Jina On-Prem es una solución directa para las aplicaciones creadas sobre esos esquemas.

• Reemplazo directo para modelos servidos por el EIS. Jina On-Prem se integra directamente con despliegues de Elastic aislados de la red.

Requisitos de hardware para los modelos locales de Jina AI

Los requisitos de hardware varían para los diferentes modelos de Jina. La tabla de abajo muestra las recomendaciones para los modelos más recientes usando la configuración de GPU. No necesitas nada más potente que una GPU NVIDIA L4, aunque se recomienda una A100 para los modelos de incrustación v5. Nuestro modelo de incrustación más reciente requiere actualmente un mínimo de 8 GB de VRAM.

Modelo

VRAM mínima

GPU recomendada

jina-embeddings-v5-text-nano

2 GB

T4 / L4

jina-embeddings-v5-text-small

3 GB

L4 / A10G

jina-embeddings-v5-omni-small

8 GB

L4 / A10G / A100

jina-reranker-v3

3 GB

L4

jina-clip-v2

4 GB

L4

jina-code-embeddings-1.5b

4 GB

L4

ReaderLM-v2

4 GB

L4

Si usas más de un modelo a la vez, los requisitos de VRAM aumentarán. Consulta la página de Dimensionamiento y hardware para obtener más información.

Cómo instalar Jina On-Prem con docker

La forma más rápida de dar los primeros pasos es instalar docker (si aún no lo has hecho) y seguir las instrucciones de la página Inicio rápido de Jina On-Prem.

Hay contenedores docker preconfigurados para los 28 modelos de Jina. Descarga uno y transfiérelo a tu destino de instalación, y podrás tener modelos de Jina AI ejecutándose en menos de cinco minutos.

Para compilaciones multimodales o personalizadas, o para descargar el conjunto completo de dependencias para la instalación fuera de un contenedor, sigue los pasos descritos en la guía de empaquetado.

Tu instalación de Jina On-Prem brinda soporte para toda la funcionalidad de la API de Jina y de EIS, y para la generación de incrustaciones mediante las API de OpenAI, Cohere, Voyage AI y Gemini, por lo que puede integrarse en aplicaciones preexistentes que usen interfaces estándar. Consulta la documentación de la API para obtener más información.

Los modelos de Jina, incluidos los modelos instalados con Jina On-Prem, están disponibles bajo diversos términos de licencia, y los últimos modelos son gratuitos para uso no comercial bajo una licencia CC BY-NC 4.0. Para adquirir la licencia de Jina On-Prem para uso comercial, ponte en contacto con Ventas de Elastic.

Esta publicación explica cómo los endpoints de búsqueda, descubrimiento y metadatos se basan en el trabajo anterior de ingesta y búsqueda para formar esa superficie de API. Las publicaciones complementarias profundizan en las piezas individuales:

• La compatibilidad nativa con PromQL en ES|QL explica cómo se traducen las consultas PromQL en planes de ejecución de ES|QL.

• Envía métricas de Prometheus a Elasticsearch con Remote Write cubre la configuración de ingesta.

• El artículo “Cómo funciona la ingesta de escritura remota de Prometheus en Elasticsearch” explica los detalles internos de la escritura remota.

Esto aún está en desarrollo. En las secciones siguientes se indica qué es lo que ya está disponible y qué partes aún están en desarrollo.

La superficie de la API

Hoy en día, la interfaz de programación de aplicaciones (API) compatible con Prometheus se divide en tres grupos.

Endpoints de consulta

Los endpoints de consulta permiten a los clientes compatibles con Prometheus evaluar expresiones PromQL:

• GET /_prometheus/api/v1/query_range evalúa una expresión PromQL en un intervalo de tiempo (resultados en forma de matriz).

• GET /_prometheus/api/v1/query evalúa en un solo punto en el tiempo (resultados vectoriales). Actualmente implementado como una búsqueda de alcance corto que devuelve la última muestra.

Hoy en día, solo GET es compatible con los puntos de consulta. Algunos clientes usan POST de forma predeterminada, así que es posible que tengas que configurarlos para que usen GET. La convención POST de Prometheus emplea application/x-www-form-urlencoded cuerpos, que la capa HTTP de Elasticsearch rechaza como salvaguarda CSRF antes de que la solicitud llegue al controlador.

Para ver el estado completo de la cobertura de PromQL, consulta la publicación complementaria sobre PromQL en ES|QL.

Endpoints de metadatos

Los endpoints de metadatos proporcionan la información de descubrimiento que los clientes necesitan para el autocompletado, los desplegables de variables y la navegación de métricas.

La serie, las etiquetas y los puntos finales de valores de etiqueta aceptan selectores match[] y un rango de tiempo (start/end). El parámetro match[] toma un selector de serie de Prometheus como http_requests_total{job="api"} y restringe la respuesta a series temporales que coinciden. Esto garantiza que las respuestas sean rápidas y pertinentes en clústeres con una gran cantidad de métricas. Por ejemplo:

La primera devuelve todas las series para http_requests_total donde job="api", con sus conjuntos de etiquetas completos. La segunda devuelve solo los nombres de las etiquetas que existen en las series de http_requests_total. El tercero solo devuelve los valores de instance que aparecen en las series coincidentes.

GET /_prometheus/api/v1/metadata es diferente: devuelve el tipo y la unidad para cada métrica, opcionalmente filtrados por nombre mediante un parámetro metric.

No acepta match[] selectores ni un intervalo de tiempo. En Prometheus, los metadatos se recogen de objetivos activos de extracción (las líneas HELP, TYPE y UNIT que exponen), por lo que la respuesta no implica un escaneo de datos. Elasticsearch no tiene un almacén de metadatos dedicado como ese, por lo que la implementación actual descubre metadatos de métricas visitando datos temporales de las últimas 24 horas. Esto mantiene la consulta rápida sin requerir un escaneo completo del índice. Ese retroceso de 24 horas está corregido hoy: la API de metadatos de Prometheus no expone los parámetros start o end que Elasticsearch podría usar para que sean ajustables por el usuario.

Cómo funcionan los endpoints de metadatos de forma interna, incluidos los comandos TS_INFO y METRICS_INFO que los potencian, se explica a continuación.

Pre-filtrado de índices

Todos los endpoints de consulta y metadato aceptan un segmento de ruta {index} opcional después de /_prometheus/:

Esto limita los índices de Elasticsearch contra los que se ejecuta la consulta antes de que comience la evaluación de cualquier expresión. En clústeres con muchos flujos de datos entre equipos o entornos, esto evita escanear índices no relacionados y puede reducir en gran medida la latencia de las consultas. Puedes configurar fuentes de datos independientes por patrón de índice para dar a los equipos acceso limitado a sus propias métricas.

Una nota sobre Remote Write

Para la ingesta, Elasticsearch también expone el endpoint estándar de escritura remota de Prometheus:

• POST /_prometheus/api/v1/write ingiere series temporales a través del protocolo Prometheus Remote Write v1. v2 aún no es compatible.

La escritura remota escribe en los flujos de datos temporales existentes (TSDS) de Elasticsearch, no en una capa de almacenamiento específica de Prometheus separada. Las etiquetas de Prometheus se convierten en dimensiones de TSDS, y los nombres de las métricas se convierten en campos en el mapeo del índice. La publicación de arquitectura de escritura remota abarca todo el mapeo en detalle, incluso explica cómo se infieren los tipos de métricas y cómo se almacenan las etiquetas con un prefijo labels..

Cómo funciona

Detrás de escena, todos los endpoints funcionan de la misma manera: parsean los parámetros HTTP entrantes, construyen un plan de consulta ES|QL, lo ejecutan contra los flujos de datos de series temporales y convierten el resultado columnar de vuelta al formato JSON que esperan los clientes de Prometheus.

TS_INFO y METRICS_INFO

Los endpoints de metadatos deben responder preguntas como "¿qué etiquetas existen?" o "¿qué tipos de métricas están definidos?" a través de lo que podrían ser millones de series temporales, sin tener que analizar cada punto de datos.

A nivel interno, los endpoints de metadatos de Prometheus responden a esas preguntas construyendo planes de ES|QL basados en dos nuevos comandos de procesamiento: METRICS_INFO y TS_INFO. No es necesario usar estos comandos directamente para usar la API de Prometheus, pero son las primitivas de ejecución del núcleo detrás de las respuestas de metadatos. Ambos funcionan visitando solo un documento por serie temporal para extraer su metadato, en vez de escanear todas las muestras. Esto significa que su costo varía en función de la cantidad de series temporales distintas, no de la cantidad de puntos de datos.

METRICS_INFO devuelve una fila por cada métrica distinta, con su nombre, tipo, unidad y los campos de dimensión asociados. TS_INFO es más granular: una fila por combinación (métrica, serie temporal), incluyendo los valores de dimensión reales como un objeto JSON.

Muy pronto llegará una publicación de blog especial sobre TS_INFO y METRICS_INFO que cubrirá el modelo de ejecución en dos fases, cómo escalan y cómo usarlos directamente en consultas de ES|QL por fuera de la API de Prometheus.

Cómo los endpoints de metadatos los emplean

Cada endpoint de metadatos construye un ES|QL plan con uno de estos comandos como núcleo.

/api/v1/labels y /api/v1/series usan TS_INFO, ya que necesitan detalles por serie temporal (qué etiquetas existen, qué valores de dimensión identifican cada serie). /api/v1/metadata y /api/v1/label/__name__/values usan METRICS_INFO, ya que solo necesitan información por métrica (nombres de métricas, tipos, unidades).

/api/v1/label/{name}/values para etiquetas normales (cualquier otra cosa que no sea __name__), no se usa ninguno de los dos comandos. Algunas etiquetas regulares como job o instance son campos dimensionales reales en el índice, por lo que el endpoint puede consultarlos directamente mediante una agregación según grupo. Cuando se proporcionan selectores match[], se traducen en una cláusula WHERE que filtra la serie temporal antes de que se ejecute la agregación.

La etiqueta __name__ necesita una estrategia diferente porque no siempre está presente como un campo dimensional. Prometheus Remote Write sí almacena labels.__name__, pero las métricas ingeridas por otros caminos (OpenTelemetry, la API de bulk) no la tienen. El nombre de la métrica está codificado en el propio nombre del campo (por ejemplo, metrics.http_requests_total). Podrías consultar las asignaciones de índices para enumerar los nombres de los campos, pero las asignaciones por sí solas no te dicen qué métrica tiene qué dimensiones, y no se pueden filtrar por valores de etiquetas de un selector match[]. METRICS_INFO puede hacer ambas cosas: enumera los nombres de las métricas en los índices mientras respeta los filtros WHERE upstream.

En todos los casos, la capa API gestiona la traducción de vuelta a las convenciones de Prometheus: eliminando los prefijos de almacenamiento labels. y metrics. y sintetizando __name__ para métricas no Prometheus que carecen de ellas.

En conclusión

El resultado: cualquier cliente compatible con Prometheus puede buscar y explorar métricas de Elasticsearch a través de endpoints que ya entiende. Las métricas de Remote Write así como las de OpenTelemetry y las métricas indexadas a través de otras rutas aparecen todas a través de la misma API, respaldadas por los mismos índices TSDS.

Todas las API de Prometheus que se mencionan aquí ya están disponibles como versión preliminar técnica en Elasticsearch Serverless. Para clústeres autogestionados y despliegues alojados de Elastic Cloud Hosted, disponibles como vista previa técnica en Elasticsearch 9.4, con la excepción de GET /_prometheus/api/v1/metadata. Para probarlo a nivel local, usa start-local.

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:

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

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

• zodayuda 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:

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:

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

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:

Descubre más sobre las salidas estructuradas aquí.

Ahora vamos a inicializar el servidor MCP:

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.

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.

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:

Ahora compila el proyecto usando el siguiente comando:

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:

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:

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:

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.

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 paracombinar 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í:

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:

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í:

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:

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.

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:

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:

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:

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

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

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:

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

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

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.

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:

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:

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:

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:

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

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:

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:

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:

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:

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

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:

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

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.

En este blog, emplearemos Mastra para construir un agente de conocimiento que recuerda lo que dicen los usuarios y puede recuperar información relevante más adelante, empleando Elasticsearch como backend de memoria y recuperación. Puedes extender fácilmente este mismo concepto a casos de uso reales, piensa en agentes de soporte que puedan recordar conversaciones y resoluciones pasadas, permitiéndoles adaptar las respuestas a usuarios específicos o a soluciones superficiales más rápido basar en contextos previos.

Sigue aquí para ver cómo construirlo paso a paso. Si te pierdes o simplemente quieres ejecutar un ejemplo terminado, echa un vistazo al repositorio aquí.

¿Qué es Mastra?

Mastra es un framework TypeScript de código abierto para construir agentes de IA con partes intercambiables para razonamiento, memoria y herramientas. Su función de recuperación semántica permite a los agentes recordar y recuperar interacciones pasadas almacenando mensajes como incrustaciones en una base de datos vectorial. Esto permite a los agentes mantener el contexto y la continuidad de la conversación a largo plazo. Elasticsearch es un excelente almacén vectorial para habilitar esta función, ya que soporta una búsqueda vectorial densa eficiente. Cuando se activa la recuperación semántica, el agente extrae mensajes pasados relevantes en la ventana de contexto del modelo, permitiendo que el modelo emplee ese contexto recuperado como base para su razonamiento y respuestas.

Lo que necesitas para empezar

• Nodo v18+

• Elasticsearch (versión 8.15 o posterior)

• Clave API de Elasticsearch

• Clave API de OpenAI

Nota: Necesitarás esto porque la demo usa el proveedor OpenAI, pero Mastra soporta otros SDKs de IA y proveedores de modelos comunitarios, así que puedes cambiarlo fácilmente según tu configuración.

Construyendo un proyecto de Mastra

Emplearemos la CLI integrada de Mamra para proporcionar el andamiaje de nuestro proyecto. Ejecuta el comando:

Recibirás un conjunto de indicaciones, que empiezan por:

1. Pon un nombre a tu proyecto.

2. Podemos mantener este valor predeterminado; No dudes en dejar esto en blanco.

3. Para este proyecto, emplearemos un modelo proporcionado por OpenAI.

4. Selecciona la opción "Saltar por ahora" porque almacenaremos todas nuestras variables de entorno en un archivo '.env' que configuraremos en un paso posterior.

5. También podemos saltar esta opción.

Una vez que termines de inicializar, podemos pasar al siguiente paso.

Instalación de dependencias

A continuación, necesitamos instalar algunas dependencias:

• ai - Paquete básico de SDK de IA que proporciona herramientas para gestionar modelos de IA, prompts y flujos de trabajo en JavaScript/TypeScript. Mastra está construido sobre el SDK de IA por Vercel, así que necesitamos esta dependencia para permitir la interacción del modelo con tu agente.

• @ai-sdk/openai - Plugin que conecta el SDK de IA con modelos OpenAI (como GPT-4, GPT-4o, etc.), habilitando llamadas API usando tu clave API OpenAI.

• @elastic/elasticsearch - Cliente oficial de Elasticsearch para Node.js, se emplea para conectarse a tu Elastic Cloud o a un clúster local para operaciones de indexación, búsqueda y vectores.

• dotenv - Carga variables de entorno desde un .env archivar en process.env, permitiendo inyectar de forma segura credenciales como claves API y endpoints Elasticsearch.

Configuración de variables de entorno

Crea un archivo .env en el directorio raíz de tu proyecto si aún no ves uno. Alternativamente, puedes copiar y renombrar el ejemplo .env que proporcioné en el repositorio. En este archivo, podemos agregar las siguientes variables:

Eso concluye la configuración básica. Desde aquí, ya puedes empezar a construir y orquestar agentes. Vamos un paso más allá y agregaremos Elasticsearch como la capa de almacenamiento y búsqueda vectorial.

Agregar Elasticsearch como almacenamiento vectorial

Crea una nueva carpeta llamada stores y dentro, agrega este archivo. Antes de que Mastra y Elastic lanzaran una integración oficial de almacenamiento vectorial de Elasticsearch, Abhi Aiyer(CTO de Mestra) compartió esta clase prototipo temprana llamada ElasticVector. Simplemente, conecta la abstracción de memoria de Mamra con las densas capacidades vectoriales de Elasticsearch, para que los desarrolladores puedan incluir Elasticsearch como base de datos vectorial para sus agentes.

Echemos un vistazo más profundo a las partes importantes de la integración:

Ingestión del cliente Elasticsearch

Esta sección define la clase ElasticVector y configura la conexión cliente de Elasticsearch con soporte tanto para despliegues estándar como serverless.

• ElasticVectorConfig extends ClientOptions: Esto crea una nueva interfaz de configuración que hereda todas las opciones del cliente de Elasticsearch (como node, auth, requestTimeout) y agrega nuestras propiedades personalizadas. Esto significa que los usuarios pueden pasar cualquier configuración válida de Elasticsearch junto con nuestras opciones específicas para serverless.

• extends MastraVector: Esto permite ElasticVector heredar de la clase base de MastraVector de Mastra, que es una interfaz común a la que se ajustan todas las integraciones de almacenamiento vectorial. Esto garantiza que Elasticsearch se comporte como cualquier otro backend de vectores Mastra desde la perspectiva del agente.

• private client: Client: Esta es una propiedad privada que contiene una instancia del cliente JavaScript Elasticsearch. Esto permite que la clase hable directamente con tu grupo.

• isServerless y deploymentChecked: Estas propiedades trabajan juntas para detectar y almacenar en caché si estamos conectados a un despliegue serverless o estándar de Elasticsearch. Esta detección ocurre automáticamente en el primer uso, o puede configurar explícitamente.

• constructor(config: ClientOptions): Este constructor toma un objeto de configuración (que contiene tus credenciales de Elasticsearch y configuraciones opcionales de serverless) y lo emplea para inicializar el cliente en la línea this.client = new Client(config).

• super(): Esto llama constructor base de Mastra, por lo que hereda el registro, los asistentes de validación y otros ganchos internos.

En este punto, Mastra sabe que hay un nuevo almacén vectorial llamado ElasticVector

Detección del tipo de despliegue

Antes de crear índices, el adaptador detecta automáticamente si estás usando Elasticsearch estándar o Elasticsearch Serverless. Esto es importante porque los despliegues serverless no permiten la configuración manual de shards.

Qué pasa:

• Primero comprueba si pusiste explícitamente isServerless en la configuración (se salta la auto-detección).

• Llama a la API info() de Elasticsearch para obtener información del clúster

• Comprueba el build_flavor field (los despliegues serverless devuelven serverless)

• Vuelve a revisar el lema si no hay variedad de build disponible

• Almacena en caché el resultado para evitar llamadas repetidas a la API

• Por defecto se aplica al despliegue estándar si falla la detección

Ejemplo de uso:

Creación del almacén de "memoria" en Elasticsearch

La función siguiente establece un índice Elasticsearch para almacenar incrustaciones. Comprueba si el índice ya existe. Si no, crea uno con el mapeo que aparece abajo y contiene un campo dense_vector para almacenar incrustaciones y métricas de similitud personalizadas.

Algunas cosas a tener en cuenta:

• El parámetro dimension es la longitud de cada vector de incrustación, que depende del modelo de incrustación que estés usando. En nuestro caso, generaremos incrustaciones usando el modelo text-embedding-3-small de OpenAI, que genera vectores de tamaño 1536. Usaremos esto como nuestro valor por defecto.

• La variable similarity empleada en el mapeo a continuación se define a partir de la función auxiliar const similarity = this.mapMetricToSimilarity(metric), que toma el valor del parámetro metric y lo convierte en una palabra clave compatible con Elasticsearch para la métrica de distancia elegida.

  • Por ejemplo: Mastra emplea términos generales para similitud vectorial como cosine, euclidean, y dotproduct. Si pasáramos la métrica euclidean directamente al mapeo de Elasticsearch, generaría un error porque Elasticsearch espera que la palabra clave l2_norm represente la distancia euclidiana.

• Compatibilidad sin servidor: El código omite automáticamente los ajustes de shard y réplica para despliegues sin servidor, ya que estos son gestionados automáticamente por Elasticsearch Serverless.

Almacenar una nueva recordación o nota tras una interacción

Esta función toma nuevas incrustaciones generadas tras cada interacción, junto con los metadatos, y luego las inserta o actualiza en el índice usando la API bulk de Elastic. La API bulk agrupa múltiples operaciones de escritura en una sola solicitud; Esta mejora en nuestro rendimiento de indexación garantiza que las actualizaciones se mantengan eficientes a medida que la memoria de nuestro agente sigue creciendo.

Consulta de vectores similares para la recuperación semántica

Esta función es el núcleo de la característica de recuperación semántica. El agente emplea búsqueda vectorial para encontrar incrustaciones almacenadas similares dentro de nuestro índice.

Bajo el capó:

• Ejecuta una consulta kNN (k-vecinos más cercanos) usando la API knn en Elasticsearch.

• Recupera los vectores top-K similares al vector de consulta de entrada.

• Opcionalmente, aplica filtros de metadatos para reducir resultados (por ejemplo, buscar solo dentro de una categoría o rango de tiempo específico)

• Devuelve resultados estructurados que incluyen el ID del documento, el puntaje de similitud y los metadatos almacenados.

Creación del agente del conocimiento

Ahora que vimos la conexión entre Mastra y Elasticsearch a través de la integración ElasticVector , creemos el propio Knowledge Agent.

Dentro de la carpeta agents, crea un archivo llamado knowledge-agent.ts. Podemos empezar conectando nuestras variables de entorno e inicializando el cliente Elasticsearch.

Aquí, nosotros:

• Usa dotenv para cargar nuestras variables desde nuestro archivo .env .

• Comprueba si las credenciales de Elasticsearch se están inyectando correctamente y podemos establecer una conexión exitosa con el cliente.

• Pasa el endpoint de Elasticsearch y la clave API al constructor ElasticVector para crear una instancia de nuestro almacén vectorial que definimos antes.

• Opcionalmente, especifica isServerless: true si usas Elasticsearch Serverless. Esto omite el paso de detección automática y mejora el tiempo de arranque. Si se omite, el adaptador detectará automáticamente el tipo de despliegue en el primer uso.

A continuación, podemos definir el agente usando la clase Agent de Mastra.

Los campos que podemos definir son:

• name y instructions: Darle una identidad y función primaria.

• model: Estamos usando la gpt-4o de OpenAI a través del paquete @ai-sdk/openai .

• memory:

  • vector: Apunta a nuestra tienda Elasticsearch, así que los embeddings se almacenan y recuperan desde allí.

  • embedder: Qué modelo usar para generar incrustaciones

  • semanticRecall Las opciones deciden cómo funciona la retirada:

    • topK: Cuántos mensajes semánticamente similares recuperar.

    • messageRange: Cuánto de la conversación incluir en cada partido.

    • scope: Define el límite de la memoria.

Casi termino. Solo tenemos que agregar este agente recién creado a nuestra configuración de Mestra. En el archivo llamado index.ts, importa el agente de conocimiento e insértalo en el campo agents .

Los otros campos incluyen:

• storage: Este es el almacén interno de datos de Mamra para historial de ejecuciones, métricas de observabilidad, puntajes y cachés. Para más información sobre el almacenamiento de mastras, visita aquí.

• logger: Mastra emplea Pino, que es un registrador JSON estructurado y ligero. Captura eventos como inicios y atajada de agentes, llamadas y resultados de herramientas, errores y tiempos de respuesta de los LLM.

• observability: Controla el rastreo de IA y la visibilidad de ejecución de los agentes. Sigue lo siguiente:

  • Inicio/final de cada paso de razonamiento.

  • Qué modelo o herramienta se empleó.

  • Entradas y salidas.

  • Puntajes y evaluaciones

Probando al agente con Mastra Studio

¡Felicidades! Si llegaste hasta aquí, estás listo para ejecutar este agente y probar sus capacidades semánticas de recuperación. Por suerte, Mastra ofrece una interfaz de chat integrada para que no tengamos que crear la nuestra.

Para iniciar el servidor de desarrollo de Mestra, abre un terminal y ejecuta el siguiente comando:

Tras el empaquetado y el arranque inicial del servidor, debería proporcionarte una dirección del Playground.

Pega esta dirección en tu navegador y te recibirás con Mastra Studio.

Selecciona la opción de knowledgeAgent y charla sin parar.

Para una prueba rápida y ver si todo está correctamente cableado, dale información como: "El equipo anunció que el rendimiento de ventas en octubre subió un 12%, impulsado principalmente por renovaciones empresariales. El siguiente paso es ampliar su alcance a clientes de gama media." Después, inicia un nuevo chat y haz una pregunta como: "¿En qué segmento de clientes dijimos que debemos centrarnos a continuación?" El agente de conocimiento debería ser capaz de recordar la información que le diste en el primer chat. Deberías ver una respuesta como:

Ver una respuesta así significa que el agente almacenó con éxito nuestro mensaje anterior como incrustaciones en Elasticsearch y lo recuperó después usando búsqueda vectorial.

Inspección del almacenamiento de memoria a largo plazo del agente

Ve a la pestaña memory en la configuración de tu agente en Mastra Studio. Esto te permite ver lo que tu agente aprendió con el tiempo. Cada mensaje, respuesta e interacción que se incrusta y almacena en Elasticsearch pasa a formar parte de esta memoria a largo plazo. Puedes buscar semánticamente en interacciones pasadas para encontrar rápidamente información o contexto recordado que el agente aprendió antes. Este es esencialmente el mismo mecanismo que emplea el agente durante la recuperación semántica, pero aquí puedes inspeccionarlo directamente. En nuestro ejemplo a continuación, buscamos el término "ventas" y recibimos cada interacción que incluyera algo relacionado con las ventas.

Conclusión

Al conectar Mastra y Elasticsearch, podemos dar memoria a nuestros agentes, que es una capa clave en la ingeniería de contexto. Con la memoria semántica, los agentes pueden construir contexto con el tiempo, basando sus respuestas en lo que aprendieron. Eso significa interacciones más precisas, fiables y naturales.

Esta integración temprana es solo el punto de partida. El mismo patrón aquí puede permitir que los agentes de soporte recuerden tiquetes anteriores, bots internos que recuperen la documentación relevante o asistentes de IA que puedan recuperar detalles de los clientes en medio de una conversación. También estamos trabajando en una integración oficial de Mestra, haciendo que esta pareja sea aún más fluida en un futuro próximo.

Estamos deseando ver qué construyes a continuación. Pruébalo, explora Mastra y sus funciones de memoria, y siéntete libre de compartir lo que descubras con la comunidad.