Jeffrey Rengifo - Elasticsearch Labs

Cómo medir y mejorar la recuperación de búsqueda de Elasticsearch: de 0,43 a 0,75 con búsqueda híbrida

Jeffrey Rengifo — Mon, 04 May 2026 00:00:00 GMT

La búsqueda léxica mediante el algoritmo de clasificación BM25 es económica, rápida y muy eficaz para una amplia gama de consultas. Sin embargo, tiene un punto ciego: las consultas que no comparten tokens con tus documentos. En este artículo, mencionaremos con precisión en qué aspectos se queda corto el BM25. Emplearemos la API de evaluación de clasificación (rank_eval) de Elasticsearch y cerraremos esa brecha agregando incrustaciones de Jina AI mediante Elastic Inference Service (EIS). Verás cómo la puntuación de recuperación pasa de 0.43 a 0.75 y entenderás por qué.

¿Qué es la recuperación?

La recuperación mide en una escala de 0 a 1 cuántos de los documentos que realmente quieren tus usuarios aparecen en algún lugar de los resultados de búsqueda. Si una consulta debe mostrar tres productos y la búsqueda solo arroja dos de ellos en los 10 principales, recall@10 = 0.67 para esa consulta. Es una métrica basada en conjuntos: no le importa la posición de los documentos relevantes dentro de esos k resultados. Un documento relevante en la posición 10 cuenta igual que uno en la posición 1. Tener una recuperación alta significa que no estás perdiendo resultados relevantes.

El diagrama muestra dos conjuntos: todos los documentos relevantes (izquierda) y lo que BM25 realmente recuperó (10 principales, derecha). Solo la intersección cuenta para la recuperación, se encontraron prod_1 y prod_2, mientras que prod_3, prod_4 y prod_6 se perdieron por completo. Resultado: Recall@10 = 2/5 = 0.40.

Requisitos previos

Pongamos manos a la obra para comprender mejor cómo funciona la recuperación. Esta demostración utiliza Python. Puedes seguirlo en el cuaderno complementario (notebook.ipynb), donde cada bloque de código es una celda lista para ejecutarse.

El código proporcionado utiliza lo siguiente:

Elasticsearch 9.3+
Python 3.10+

pip install elasticsearch pandas plotly python-dotenv

Un archivo .env con tus credenciales de Elasticsearch

ELASTICSEARCH_URL=https://your-cluster-url ELASTICSEARCH_API_KEY=your-api-key

El set de datos

Emplearemos un catálogo con 1000 productos, que abarcan categorías como calzado, electrónica, herramientas y más.

Cada documento tiene cuatro campos:

Campo

Tipo

`título`

texto

'descripción'

texto

`marca`

palabra clave

'categoría'

palabra clave

El set de datos se carga desde dataset.csv.

El poder y los límites de la búsqueda léxica

BM25 es el algoritmo de clasificación predeterminado en Elasticsearch y en la mayoría de los motores de búsqueda. Califica los documentos según la frecuencia con la que aparecen tus términos de consulta en ellos, ajustado por la longitud del documento y la frecuencia de esos términos en todo el índice. Los analizadores aparecen en la parte superior: normalización de minúsculas, derivación y eliminación de palabras vacías. Una búsqueda de "zapatillas para correr" coincidirá con "Zapatillas para correr" y probablemente también con "correr".

Esto funciona bien para una amplia clase de consultas:

"zapatillas de correr" muestra de inmediato los productos que contienen exactamente esas palabras en el título.
"parlante con bluetooth" muestra productos de audio portátiles porque los tokens aparecen textualmente.

Los resultados son deterministas y explicables: un documento se clasifica alto porque los términos de la consulta aparecen en él. Depurar la relevancia es sencillo.

Cuándo falla

Ahora probemos estas búsquedas en el mismo catálogo:

"rutina de skincare": la palabra "rutina" no aparece en ningún título de producto. BM25 puede hacer una coincidencia parcial con "skincare", pero los sueros faciales, aceites corporales y humectantes se describen utilizando términos como "vitamina C", "retinol" o "aclarante", ninguno de los cuales se superpone con la consulta. Los productos que forman una rutina completa de skincare están dispersos en el índice sin ningún token compartido para anclarlos.

ID: B06XX6DS3P, Score: 9.0552, Title: Replenix Retinol Smooth + Tighten Body Lotion - Collagen-Boosting, Regenerating Anti-Aging Body Cream, Reduces Appearance of Stretch Marks, 6.7 oz. ID: B08XMPKJ1L, Score: 5.2699, Title: Bio-Oil Skincare Body Oil (Natural) Serum for Scars and Stretchmarks, Face and Body Moisturizer Hydrates Skin, with Organic Jojoba Oil and Vitamin E, For All Skin Types, 6.7 oz ID: B01CY764KQ, Score: 5.0057, Title: Nike Up Or Down Men Deodorant - Pack of 2 | Long-Lasting Fragrance, Body Spray Combo for Men | Deodorant for Active Living | Nike Men's Deo Set | Ultimate Odor Protection | Grooming Essentials | Signature Nike Scent | High-Performance Men's Deodorant

"accesorios de viaje para mascotas": esta es una agrupación de casos de uso, no una categoría de producto. Un transportín para perros, un asiento para mascotas en el automóvil y una jaula de viaje son todos relevantes, pero sus descripciones hablan sobre portabilidad, seguridad y comodidad en vez de "accesorios de viaje". BM25 coincide con "mascota" de manera amplia, pero no tiene ninguna señal para distinguir los productos específicos de viaje del resto del catálogo de mascotas.

ID: B0BVV7BKTW, Score: 7.4371, Title: Large Foldable Travel Duffel Bag with Shoes Compartment ID: B07TNPHYNV, Score: 6.6455, Title: 40 Pieces Christmas Bronze Jingle Bells Craft Small Bells ID: B08R8FRW53, Score: 6.6335, Title: CUBY Dog and Cat Sling Carrier ID: B08QMCQYGM, Score: 6.5259, Title: YTFGGY Whiteboard Pinstripe Tape 6 Rolls 1/8" ID: B0CP3LQSWM, Score: 6.2994, Title: Portable Dog Water Bottle 32 Oz

Este es un problema de recuperación. Los documentos relevantes están en tu índice. BM25 simplemente no puede encontrarlos porque las palabras del usuario y las del documento no coinciden lo suficiente.

Agregar sinónimos es útil en casos conocidos. Pero no se puede enumerar todas las formas en que un usuario podría expresar una intención. Ahí es donde entran los vectores.

Por qué deberías medir el recall

Antes de solucionar un problema, necesitas cuantificarlo.

Recall@k mide cuántos de los documentos que realmente buscan tus usuarios aparecen en algún lugar de los resultados de búsqueda. Es decir:

Recall@k = (relevant documents found in top k) / (total relevant documents)

Precision@k mide los mejores k resultados y cuántos son realmente relevantes:

Precision@k = (relevant documents in top k) / k

La alta precisión significa que los resultados que se devuelven son buenos. En el comercio electrónico, no mostrar un producto relevante (baja recuperación) suele ser peor que mostrar un resultado ligeramente imperfecto (menor precisión), porque un producto oculto es una venta perdida.

La API rank_eval de Elasticsearch te permite medir ambos de forma sistemática. Proporcionas una lista de consultas, cada una con un conjunto de documentos calificados, y Elasticsearch calcula las métricas por ti en todas las consultas.

Configuración de la evaluación

La API rank_eval necesita un set de datos de calificaciones: un mapeo de consultas a los documentos que son relevantes para cada uno, junto con un grado de relevancia (0 = no relevante, 1 = relevante, 2 = altamente relevante).

En el cuaderno, esta es la lista de evaluaciones:

judgments = [ # Query 1: "running shoes" BM25 handles well (tokens appear in product titles) {"query_id": "q1", "doc_id": "B09NQJFRW6", "grade": 2, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B08JMD4LMM", "grade": 2, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B08VRJ6F2Q", "grade": 2, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B07S8NRRWR", "grade": 2, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B01HD620I8", "grade": 2, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B07DX86321", "grade": 2, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B0968YVLQ8", "grade": 1, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B093QJ39ZS", "grade": 1, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B096FGSC39", "grade": 1, "query": "running shoes"}, {"query_id": "q1", "doc_id": "B01GVQWVV2", "grade": 1, "query": "running shoes"}, # Query 2: "skincare routine" intent-based, "routine" never appears in product titles {"query_id": "q2", "doc_id": "B08XMPKJ1L", "grade": 2, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B0BN3WQB92", "grade": 2, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B0BT7B7P5T", "grade": 2, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B00NPA2WEY", "grade": 2, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B06XX6DS3P", "grade": 1, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B07PDRD1KT", "grade": 1, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B074J7869B", "grade": 1, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B08JV31QW4", "grade": 1, "query": "skincare routine"}, {"query_id": "q2", "doc_id": "B00K3TVJMQ", "grade": 1, "query": "skincare routine"}, # Query 3: "study desk setup" intent-based, products are desks/stands/organizers {"query_id": "q3", "doc_id": "B08CS35J2T", "grade": 2, "query": "study desk setup"}, {"query_id": "q3", "doc_id": "B09B3LFDXJ", "grade": 2, "query": "study desk setup"}, {"query_id": "q3", "doc_id": "B07W58LMND", "grade": 1, "query": "study desk setup"}, {"query_id": "q3", "doc_id": "B0CHYDX91L", "grade": 1, "query": "study desk setup"}, # Query 4: "pet travel accessories" use-case grouping, products are carriers/crates/seats {"query_id": "q4", "doc_id": "B08R8FRW53", "grade": 2, "query": "pet travel accessories"}, {"query_id": "q4", "doc_id": "B01MYUYX33", "grade": 2, "query": "pet travel accessories"}, {"query_id": "q4", "doc_id": "B003C5RKE4", "grade": 2, "query": "pet travel accessories"}, {"query_id": "q4", "doc_id": "B09GF8GBF6", "grade": 1, "query": "pet travel accessories"}, {"query_id": "q4", "doc_id": "B0CP3LQSWM", "grade": 1, "query": "pet travel accessories"}, ]

La combinación es intencionada: q1 es una consulta que BM25 maneja bien (tokens exactos en los títulos de productos), mientras que q2, q3 y q4 son consultas basadas en la intención donde la intención del usuario se expresa como un concepto en lugar de palabras clave específicas de producto.

Medición de la recuperación basal de BM25

Primero, configura el cliente de Elasticsearch e indexa los datos de texto sin procesar:

import os import json import pandas as pd import plotly.graph_objects as go from elasticsearch import Elasticsearch, helpers from dotenv import load_dotenv load_dotenv() es = Elasticsearch( os.getenv("ELASTICSEARCH_URL"), api_key=os.getenv("ELASTICSEARCH_API_KEY") ) INDEX_NAME = "ecommerce-products"

Ahora crea la solicitud rank_eval para BM25. Cada solicitud en la lista combina una consulta con sus calificaciones:

judgments_df = pd.DataFrame(judgments) bm25_requests = [] for query_id, query_text in ( judgments_df[["query_id", "query"]].drop_duplicates().values ): relevant_docs = judgments_df[judgments_df["query_id"] == query_id] ratings = [ {"_index": INDEX_NAME, "_id": row["doc_id"], "rating": row["grade"]} for _, row in relevant_docs.iterrows() ] bm25_requests.append({ "id": query_id, "request": { "query": { "multi_match": { "query": query_text, "fields": ["title", "description"] } } }, "ratings": ratings, }) bm25_eval = { "requests": bm25_requests, "metric": {"recall": {"k": 10, "relevant_rating_threshold": 1}}, } bm25_result = es.rank_eval(index=INDEX_NAME, body=bm25_eval) print("BM25 Recall@10:", bm25_result.body["metric_score"])

Resultado:

BM25 Recall@10: 0.43

0.43 significa que en las cuatro consultas, BM25 encuentra solo el 43 % de los documentos que debería encontrar. La deficiencia se concentra en las consultas basadas en la intención: "rutina de skincare" no encuentra sueros faciales ni aceites corporales porque la palabra "rutina" nunca aparece en los títulos de los productos, y "accesorios de viaje para mascotas" recupera productos para mascotas que no tienen relación con el tema, mientras que no encuentra transportines ni jaulas descritos en términos de portabilidad y seguridad en vez de "accesorios de viaje".

Esta es nuestra referencia base. Ahora tenemos un número que superar.

Agregar búsqueda vectorial con embeddings de Jina

Vector search Codifica documentos y consultas como vectores de alta dimensión, un tipo de vector compuesto por cientos o miles de valores numéricos, cada uno de los cuales codifica una característica específica de los datos que representa. Los documentos con significado similar terminan cerca unos de otros en el espacio vectorial, incluso si no comparten palabras. "Equipo de gimnasio" y "conjunto de mancuernas" estarán cerca porque los conceptos están relacionados. Elegí Elasticsearch como mi base de datos vectorial porque admite la búsqueda híbrida, lo que me brinda comprensión semántica y precisión de palabras clave de inmediato.

EIS incluye soporte integrado para la incorporación de modelos a través de su API de inferencia.

Paso 1: usar las incrustaciones de Jina v5 como endpoint de inferencia

INFERENCE_ENDPOINT_ID = ".jina-embeddings-v5-text-small"

Si tu clúster tiene recursos de GPU (disponibles en Elastic Cloud y Elasticsearch 9.3+), las incrustaciones se generan en GPU, lo cual es mucho más rápido que la inferencia de CPU y elimina el compromiso de rendimiento que históricamente hacía que los vectores fueran caros a gran escala.

¿Por qué las incrustaciones de Jina en particular? jina-embeddings-v5-text es un modelo multilingüe (más de 119 idiomas) con una ventana de contexto de 32 000 tokens y soporte para adaptadores de Adaptación de Rango Bajo (LoRA) específicos para tareas. Funciona bien para descripciones cortas de productos que están listas para usar. Lee más sobre el modelo jina-embeddings-v5-text aquí.

Paso 2: Crear el índice con un campo semántico

index_mappings = { "mappings": { "properties": { "title": {"type": "text", "copy_to": "semantic_field"}, "description": {"type": "text", "copy_to": "semantic_field"}, "brand": {"type": "keyword"}, "category": {"type": "keyword"}, "semantic_field": { "type": "semantic_text", "inference_id": INFERENCE_ENDPOINT_ID, }, } } } if not es.indices.exists(index=INDEX_NAME): es.indices.create(index=INDEX_NAME, body=index_mappings) print(f"Created index: {INDEX_NAME}")

El tipo de campo semantic_text es la clave aquí. Es una abstracción de mayor nivel sobre dense_vector: la apuntas a un endpoint de inferencia, y Elasticsearch se encarga de generar incrustaciones de forma automática.

La propiedad copy_to en title y description significa que el contenido de ambos campos fluye hacia semantic_field para su incrustación, por lo que un solo vector captura la representación completa del producto.

Paso 3: Indexar los productos

def bulk_index(products, index_name): actions = [] for product in products: doc_id = product.get("_id") source = {k: v for k, v in product.items() if k != "_id"} action = {"_index": index_name, "_source": source} if doc_id: action["_id"] = doc_id actions.append(action) success, failed = helpers.bulk(es, actions, raise_on_error=False) if failed: for error in failed: print(f"Error: {error}") else: print(f"Successfully indexed {success} documents") bulk_index(products, INDEX_NAME)

En tiempo de indexación, Elasticsearch llama al endpoint de inferencia para cada documento y almacena la incrustación resultante en semantic_field. No necesitas agregar ningún código adicional.

Búsqueda híbrida: combinación de BM25 y vectores con RRF

Agregar vectores mejora la recuperación, pero usar solo vectores corre el riesgo de perder precisión en las consultas de coincidencia exacta; "zapatillas para correr" aún debe clasificar primero las coincidencias literales. La búsqueda híbrida retiene el componente léxico específicamente para preservar esa precisión.

La búsqueda híbrida con Reciprocal Rank Fusion (RRF) combina lo mejor de ambos:

BM25 se ocupa de consultas exactas y casi exactas con alta precisión.
La búsqueda semántica gestiona consultas basadas en la intención y multilingües con alto nivel de recuperación.
RRF combina las dos listas clasificadas en una sola clasificación.

La fórmula RRF asigna a cada documento una puntuación basada en su clasificación en cada lista de resultados:

score = sum(1 / (rank_constant + rank))

Un documento que se clasifica en una posición alta en ambas listas obtiene una puntuación combinada más alta. El rank_constant controla cuánto peso reciben los documentos de menor rango.

hybrid_requests = [] for query_id, query_text in ( judgments_df[["query_id", "query"]].drop_duplicates().values ): relevant_docs = judgments_df[judgments_df["query_id"] == query_id] ratings = [ {"_index": INDEX_NAME, "_id": row["doc_id"], "rating": row["grade"]} for _, row in relevant_docs.iterrows() ] hybrid_requests.append({ "id": query_id, "request": { "retriever": { "rrf": { "retrievers": [ { "standard": { "query": { "multi_match": { "query": query_text, "fields": ["title", "description"], } } } }, { "standard": { "query": { "match": { "semantic_field": {"query": query_text} } } } }, ], "rank_window_size": 50, "rank_constant": 5, } } }, "ratings": ratings, }) hybrid_eval = { "requests": hybrid_requests, "metric": {"recall": {"k": 10, "relevant_rating_threshold": 1}}, } hybrid_result = es.rank_eval(index=INDEX_NAME, body=hybrid_eval) print("Hybrid Recall@10:", hybrid_result.body["metric_score"])

Resultado:

Hybrid Recall@10: 0.75

La búsqueda híbrida mejora sustancialmente sobre BM25 (0.43) y preserva la precisión para consultas de coincidencia exacta como "zapatillas para correr".

Resultados: Antes y después

Aquí está la comparación completa entre los tres enfoques:

methods = { "BM25 (Lexical)": bm25_requests, "Hybrid (BM25 + Vectors)": hybrid_requests, } recall_metric = {"recall": {"k": 10, "relevant_rating_threshold": 1}} comparison_data = [] for method_name, requests in methods.items(): result = es.rank_eval( index=INDEX_NAME, body={"requests": requests, "metric": recall_metric} ) comparison_data.append({ "method": method_name, "recall@10": result.body["metric_score"] }) comparison_df = pd.DataFrame(comparison_data) print(comparison_df.to_string(index=False))

Resultado:

Método

Recall@10

BM25 (Lexical)

0,43

Híbrido (BM25 + Vectores)

0,75

Desglose por consulta:

Conclusión

A lo largo de esta publicación, vimos que la búsqueda léxica BM25 es confiable cuando los usuarios teclean consultas exactas, pero pierde recuperación cuando buscan por intención en lugar de palabras clave. Usando rank_eval, establecimos una línea de base reproducible para medir esa brecha con números reales. A partir de ahí, agregamos un semantic_text campo impulsado por incrustaciones de Jina y volvimos a ejecutar la evaluación. El resultado: la búsqueda híbrida mejoró la recuperación de 0.43 a 0.75 a la vez que conservó la precisión en las consultas de coincidencia exacta, aunque el margen real dependerá de tu combinación de consultas.

El patrón escala más allá de este ejemplo: recopila juicios de las consultas reales de tus usuarios, ejecuta rank_eval como línea de base, agrega semantic_text y vuelve a medir. Sabrás exactamente qué mejoró y en qué medida.

Pasos siguientes

Aprende más sobre la recuperación y la búsqueda de vectores: Recuperación y cuantización de la búsqueda de vectores por Jeff Vestal
Añade reclasificación para una precisión aún mejor en los resultados principales
Explora la documentación de búsqueda híbrida de Elasticsearch
Lee más sobre la API rank_eval

Cómo crear un servidor MCP de Elasticsearch con TypeScript

Jeffrey Rengifo — Fri, 27 Mar 2026 00:00:00 GMT

Cuando se trabaja con grandes bases de conocimiento en Elasticsearch, encontrar información es solo la mitad de la batalla. Los ingenieros suelen necesitar sintetizar resultados de varios documentos, generar resúmenes y rastrear las respuestas hasta sus fuentes. El protocolo de contexto de modelo (MCP) proporciona una manera estandarizada de conectar Elasticsearch con aplicaciones basadas en modelos de lenguaje grande (LLM) para lograr esto. Mientras que Elastic ofrece soluciones oficiales, como Elastic Agent Builder (que incluye un endpoint MCP entre sus características), construir un servidor MCP personalizado te brinda control total sobre la lógica de búsqueda, el formato de resultados y cómo se pasa el contenido recuperado a un LLM para síntesis, resúmenes y citas.

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:

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:

Configurar el servidor MCP para Elasticsearch

Para comenzar, inicialicemos una aplicación de nodo:

npm init -y

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

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

@elastic/elasticsearch nos dará acceso a la biblioteca de Elasticsearch para Node.js.
@modelcontextprotocol/sdk proporciona las herramientas básicas para crear y administrar un servidor MCP, registrar herramientas y manejar la comunicación con los clientes de MCP.
openAI permite la interacción con modelos OpenAI para generar resúmenes o respuestas en lenguaje natural.
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:

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

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

Servidor MCP

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

// index.ts import { z } from "zod"; import { Client } from "@elastic/elasticsearch"; import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import OpenAI from "openai"; const ELASTICSEARCH_ENDPOINT = process.env.ELASTICSEARCH_ENDPOINT ?? "http://localhost:9200"; const ELASTICSEARCH_API_KEY = process.env.ELASTICSEARCH_API_KEY ?? ""; const OPENAI_API_KEY = process.env.OPENAI_API_KEY ?? ""; const INDEX = "documents";

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

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

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

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

Descubre más sobre las salidas estructuradas aquí.

Ahora vamos a inicializar el servidor MCP:

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

Definición de las herramientas MCP

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

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

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

Formato de respuesta de herramienta

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

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

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

Herramienta Search_docs

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

server.registerTool( "search_docs", { title: "Search Documents", description: "Search for documents in Elasticsearch using full-text search. Returns the most relevant documents with their content, title, tags, and relevance score.", inputSchema: { query: z .string() .describe("The search query terms to find relevant documents"), max_results: z .number() .optional() .default(5) .describe("Maximum number of results to return"), }, outputSchema: { results: z.array(SearchResultSchema), total: z.number(), }, }, async ({ query, max_results }) => { if (!query) { return { content: [ { type: "text", text: "Query parameter is required", }, ], isError: true, }; } try { const response = await _client.search({ index: INDEX, size: max_results, query: { bool: { must: [ { multi_match: { query: query, fields: ["title^2", "content", "tags"], fuzziness: "AUTO", }, }, ], should: [ { match_phrase: { title: { query: query, boost: 2, }, }, }, ], }, }, highlight: { fields: { title: {}, content: {}, }, }, }); const results: SearchResult[] = response.hits.hits.map((hit: any) => { const source = hit._source as Document; return { id: source.id, title: source.title, content: source.content, tags: source.tags, score: hit._score ?? 0, }; }); const contentText = results .map( (r, i) => `[${i + 1}] ${r.title} (score: ${r.score.toFixed( 2, )})\n${r.content.substring(0, 200)}...`, ) .join("\n\n"); const totalHits = typeof response.hits.total === "number" ? response.hits.total : (response.hits.total?.value ?? 0); return { content: [ { type: "text", text: `Found ${results.length} relevant documents:\n\n${contentText}`, }, ], structuredContent: { results: results, total: totalHits, }, }; } catch (error: any) { console.log("Error during search:", error); return { content: [ { type: "text", text: `Error searching documents: ${error.message}`, }, ], isError: true, }; } } );

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

herramienta de resumen y cita: summarize_and_cite

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

server.registerTool( "summarize_and_cite", { title: "Summarize and Cite", description: "Summarize the provided search results to answer a question and return citation metadata for the sources used.", inputSchema: { results: z .array(SearchResultSchema) .describe("Array of search results from search_docs"), question: z.string().describe("The question to answer"), max_length: z .number() .optional() .default(500) .describe("Maximum length of the summary in characters"), max_docs: z .number() .optional() .default(5) .describe("Maximum number of documents to include in the context"), }, outputSchema: { summary: z.string(), sources_used: z.number(), citations: z.array( z.object({ id: z.number(), title: z.string(), tags: z.array(z.string()), relevance_score: z.number(), }) ), }, }, async ({ results, question, max_length, max_docs }) => { if (!results || results.length === 0 || !question) { return { content: [ { type: "text", text: "Both results and question parameters are required, and results must not be empty", }, ], isError: true, }; } try { const used = results.slice(0, max_docs); const context = used .map( (r: SearchResult, i: number) => `[Document ${i + 1}: ${r.title}]\\n${r.content}` ) .join("\n\n---\n\n"); // Generate summary with OpenAI const completion = await openai.chat.completions.create({ model: "gpt-4o-mini", messages: [ { role: "system", content: "You are a helpful assistant that answers questions based on provided documents. Synthesize information from the documents to answer the user's question accurately and concisely. If the documents don't contain relevant information, say so.", }, { role: "user", content: `Question: ${question}\\n\\nRelevant Documents:\\n${context}`, }, ], max_tokens: Math.min(Math.ceil(max_length / 4), 1000), temperature: 0.3, }); const summaryText = completion.choices[0]?.message?.content ?? "No summary generated."; const citations = used.map((r: SearchResult) => ({ id: r.id, title: r.title, tags: r.tags, relevance_score: r.score, })); const citationText = citations .map( (c: any, i: number) => `[${i + 1}] ID: ${c.id}, Title: "${c.title}", Tags: ${c.tags.join( ", ", )}, Score: ${c.relevance_score.toFixed(2)}`, ) .join("\n"); const combinedText = `Summary:\\n\\n${summaryText}\\n\\nSources used (${citations.length}):\\n\\n${citationText}`; return { content: [ { type: "text", text: combinedText, }, ], structuredContent: { summary: summaryText, sources_used: citations.length, citations: citations, }, }; } catch (error: any) { return { content: [ { type: "text", text: `Error generating summary and citations: ${error.message}`, }, ], isError: true, }; } } );

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

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

Ahora compila el proyecto usando el siguiente comando:

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

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

Carga el servidor MCP en Claude Desktop

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

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

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

Pruébalo

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

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

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

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

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

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

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

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

Based on the documentation, here are the main recommendations to improve authentication and access control across your systems: Key Recommendations 1. Implement Role-Based Access Control (RBAC) Ensure users have only the permissions necessary for their job functions. This principle of least privilege minimizes security risks by limiting access to what's truly needed. [1] 2. Regular Access Audits Conduct regular audits of user roles and promptly revoke access for inactive accounts. This helps prevent unauthorized access from dormant or compromised accounts. [1] 3. Just-in-Time (JIT) Access Implement just-in-time access for sensitive operations, where permissions are granted only when needed and for a limited duration. This reduces the attack surface by minimizing standing privileges. [1] 4. OAuth 2.0 for Secure Authentication Use OAuth 2.0 to enable secure delegated access without sharing user credentials. This protocol allows third-party applications to access resources on behalf of users without exposing passwords. [2] 5. Token Security and Management Configure your identity provider to issue tokens with limited scope and lifetime Store refresh tokens securely Validate access tokens consistently to maintain security [2] References Access Control and Role Management (Tags: security, access-control) User Authentication with OAuth 2.0 (Tags: authentication, oauth) These recommendations work together to create a defense-in-depth approach, where multiple security layers protect your systems from unauthorized access.

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

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

Conclusión

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

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

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

Uso de la API de inferencia de Elasticsearch junto con modelos de Hugging Face

Jeffrey Rengifo — Mon, 23 Mar 2026 00:00:00 GMT

En actualizaciones recientes, Elasticsearch introdujo una integración nativa para conectar a modelos hospedados en el servicio de inferencia Hugging Face. En esta publicación, veremos cómo configurar esta integración y realizar inferencias mediante llamadas a la API sencillas utilizando un modelo de lenguaje grande (LLM). Usaremos SmolLM3-3B, un modelo ligero de propósito general con un buen equilibrio entre el uso de recursos y la calidad de las respuestas.

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

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

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

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

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

Configuración de un endpoint de inferencia en Hugging Face

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

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

Vamos a elegir el modelo SmolLM3-3B:

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

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

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

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

Generando clave API de Hugging Face

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

Configuración del endpoint de inferencia de Elasticsearch

Primero, declaremos un cliente de Python para Elasticsearch:

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

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

INFERENCE_ENDPOINT_ID = "smollm3-3b-pnz" os.environ["HUGGING_FACE_INFERENCE_ENDPOINT_URL"] = ( "https://j2g31h0futopfkli.us-east-1.aws.endpoints.huggingface.cloud/v1/chat/completions" ) os.environ["HUGGING_FACE_API_KEY"] = "hf_xxxxx" resp = es_client.inference.put( task_type="chat_completion", inference_id=INFERENCE_ENDPOINT_ID, body={ "service": "hugging_face", "service_settings": { "api_key": os.environ["HUGGING_FACE_API_KEY"], "url": os.environ["HUGGING_FACE_INFERENCE_ENDPOINT_URL"], }, }, )

Set de datos

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

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

Mappings de Elasticsearch

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

INDEX_NAME = "blog-posts" mapping = { "mappings": { "properties": { "id": {"type": "keyword"}, "title": { "type": "object", "properties": { "original": { "type": "text", "copy_to": "semantic_field", "fields": {"keyword": {"type": "keyword"}}, }, "translated_title": { "type": "text", "fields": {"keyword": {"type": "keyword"}}, }, }, }, "author": {"type": "keyword", "copy_to": "semantic_field"}, "category": {"type": "keyword", "copy_to": "semantic_field"}, "content": {"type": "text", "copy_to": "semantic_field"}, "date": {"type": "date"}, "semantic_field": {"type": "semantic_text"}, } } } es_client.indices.create(index=INDEX_NAME, body=mapping)

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

Ingesta de datos

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

def build_data(json_file, index_name): with open(json_file, "r") as f: data = json.load(f) for doc in data: action = {"_index": index_name, "_source": doc} yield action try: success, failed = helpers.bulk( es_client, build_data("dataset.json", INDEX_NAME), ) print(f"{success} documents indexed successfully") if failed: print(f"Errors: {failed}") except Exception as e: print(f"Error: {str(e)}")

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

def perform_semantic_search(query_text, index_name=INDEX_NAME, size=5): try: query = { "query": { "match": { "semantic_field": { "query": query_text, } } }, "size": size, } response = es_client.search(index=index_name, body=query) hits = response["hits"]["hits"] return hits except Exception as e: print(f"Semantic search error: {str(e)}") return []

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

def stream_chat_completion(messages: list, inference_id: str = INFERENCE_ENDPOINT_ID): url = f"{ELASTICSEARCH_URL}/_inference/chat_completion/{inference_id}/_stream" payload = {"messages": messages} headers = { "Authorization": f"ApiKey {ELASTICSEARCH_API_KEY}", "Content-Type": "application/json", } try: response = requests.post(url, json=payload, headers=headers, stream=True) response.raise_for_status() for line in response.iter_lines(decode_unicode=True): if line: line = line.strip() if line.startswith("event:"): continue if line.startswith("data: "): data_content = line[6:] if not data_content.strip() or data_content.strip() == "[DONE]": continue try: chunk_data = json.loads(data_content) if "choices" in chunk_data and len(chunk_data["choices"]) > 0: choice = chunk_data["choices"][0] if "delta" in choice and "content" in choice["delta"]: content = choice["delta"]["content"] if content: yield content except json.JSONDecodeError as json_err: print(f"\nJSON decode error: {json_err}") print(f"Problematic data: {data_content}") continue except requests.exceptions.RequestException as e: yield f"Error: {str(e)}"

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

def recommend_articles(search_query, index_name=INDEX_NAME, max_articles=5): print(f"\n{'='*80}") print(f"🔍 Search Query: {search_query}") print(f"{'='*80}\n") articles = perform_semantic_search(search_query, index_name, size=max_articles) if not articles: print("❌ No relevant articles found.") return None, None print(f"✅ Found {len(articles)} relevant articles\n") # Build context with found articles context = "Available blog articles:\n\n" for i, article in enumerate(articles, 1): source = article.get("_source", article) context += f"Article {i}:\n" context += f"- Title: {source.get('title', 'N/A')}\n" context += f"- Author: {source.get('author', 'N/A')}\n" context += f"- Category: {source.get('category', 'N/A')}\n" context += f"- Date: {source.get('date', 'N/A')}\n" context += f"- Content: {source.get('content', 'N/A')}\n\n" system_prompt = """You are an expert content curator that recommends blog articles. Write recommendations in a conversational style starting with phrases like: - "If you're interested in [topic], this article..." - "This post complements your search with..." - "For those looking into [topic], this article provides..." FORMAT REQUIREMENTS: - Return ONLY a JSON array - Each element must have EXACTLY these three fields: "article_number", "title", "recommendation" - If the original title is in spanish, use the "translated_title" subfield in the "title" field Keep each recommendation concise (2-3 sentences max) and focused on VALUE to the reader. EXAMPLE OF CORRECT FORMAT: [ {"article_number": 1, "title": "Article title in english", "recommendation": "If you are interested in [topic], this article provides..."}, {"article_number": 2, "title": "Article title in english", "recommendation": " for those looking into [topic], this article provides..."} ] Return ONLY the JSON array following this exact structure.""" user_prompt = f"""Search query: "{search_query}" Generate recommendations for the following articles: {context} """ messages = [ {"role": "system", "content": "/no_think"}, {"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt}, ] # LLM generation print(f"{'='*80}") print("🤖 Generating personalized recommendations...\n") full_response = "" for chunk in stream_chat_completion(messages): print(chunk, end="", flush=True) full_response += chunk return context, articles, full_response

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

def display_recommendation_cards(articles, recommendations_text): print("\n" + "=" * 100) print("📇 RECOMMENDED ARTICLES".center(100)) print("=" * 100 + "\n") # Parse JSON recommendations - clean tags and extract JSON recommendations_list = [] try: # Clean up tags cleaned_text = re.sub( r".*?", "", recommendations_text, flags=re.DOTALL ) # Remove markdown code blocks ( ... ``` or ``` ... ```) cleaned_text = re.sub(r"```(?:json)?", "", cleaned_text) cleaned_text = cleaned_text.strip() parsed = json.loads(cleaned_text) # Extract recommendations from list format for item in parsed: article_number = item.get("article_number") title = item.get("title", "") rec_text = item.get("recommendation", "") if article_number and rec_text: recommendations_list.append( { "article_number": article_number, "title": title, "recommendation": rec_text, } ) except json.JSONDecodeError as e: print(f"⚠️ Could not parse recommendations as JSON: {e}") return for i, article in enumerate(articles, 1): source = article.get("_source", article) # Card border print("┌" + "─" * 98 + "┐") # Find recommendation and title for this article number recommendation = None title = None for rec in recommendations_list: if rec.get("article_number") == i: recommendation = rec.get("recommendation") title = rec.get("title") break # Print title title_lines = textwrap.wrap(f"📌 {title}", width=94) for line in title_lines: print(f"│ {line}".ljust(99) + "│") # Card border print("├" + "─" * 98 + "┤") # Print recommendation if recommendation: recommendation_lines = textwrap.wrap(recommendation, width=94) for line in recommendation_lines: print(f"│ {line}".ljust(99) + "│") # Card bottom print("└" + "─" * 98 + "┘")

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

search_query = "Security and vulnerabilities" context, articles, recommendations = recommend_articles(search_query) print("\nElasticsearch context:\n", context) # Display visual cards display_recommendation_cards(articles, recommendations)

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

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

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

Conclusión

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

Construye un flujo de trabajo de búsqueda de IA financiera utilizando LangGraph.js y Elasticsearch

Jeffrey Rengifo — Fri, 05 Dec 2025 00:00:00 GMT

Construir aplicaciones de búsqueda con IA suele implicar la coordinación de múltiples tareas, la recuperación de datos y la extracción de datos en un flujo de trabajo sin problemas. LangGraph simplifica este proceso permitiendo a los desarrolladores orquestar agentes de IA mediante una estructura basada en nodes. En este artículo, explicaremos cómo construir una solución financiera usando LangGraph.js

¿Qué es LangGraph?

LangGraph es un marco de trabajo para construir agentes de IA y orquestarlos en un flujo de trabajo para crear aplicaciones asistidas por IA. LangGraph tiene una arquitectura de nodes donde podemos declarar funciones que representan tareas y asignarlas como nodes del flujo de trabajo. El resultado de la interacción de varios nodes será un grafo. LangGraph es parte del ecosistema más amplio LangChain, que proporciona herramientas para construir sistemas de IA modulares y componibles.

Para explicar mejor por qué LangGraph es útil, vamos a usarlo para resolver una situación problemática.

Visión general de la solución

En una firma de capital de riesgo, los inversores tienen acceso a una gran base de datos con muchas opciones de filtrado, pero cuando uno quiere combinar criterios, se vuelve difícil y lento. Esto puede hacer que algunas iniciativas relevantes no se encuentren para la inversión. Además, implica pasar muchas horas intentando identificar a los mejores candidatos, o incluso perder oportunidades.

Con LangGraph y Elasticsearch, podemos realizar búsquedas filtradas utilizando lenguaje natural, eliminando la necesidad de que los usuarios construyan manualmente solicitudes complejas con docenas de filtros. Para hacerlo más flexible, el flujo de trabajo decide automáticamente (basándose en la entrada del usuario) entre dos tipos de consulta:

Consultas centradas en la inversión: estas se dirigen a aspectos financieros y de financiación de las startups, como rondas de financiación, valoración o ingresos. Ejemplo: “Encuentra startups con financiamiento Serie A o Serie B entre $8M y $25M e ingresos mensuales superiores a $500K”.
Consultas centradas en el mercado: estas se concentran en verticales de la industria, mercados geográficos o modelos de negocio, ayudando a identificar oportunidades en sectores o regiones específicos. Ejemplo: “Encuentra startups de fintech y salud en San Francisco, Nueva York o Boston”.

Para mantener la solidez de las consultas, haremos que el LLM cree plantillas de búsqueda en lugar de consultas DSL completas. De esta manera, siempre obtienes la consulta que deseas, y el LLM solo tiene que completar los espacios en blanco y no cargar con la responsabilidad de construir la consulta que necesitas cada vez.

Lo que necesitas para comenzar

Clave de API de Elasticsearch
Clave de API de OpenAPI
Node 18 o más reciente

Instrucciones paso a paso

En esta sección, mostramos cómo se verá la app. Para ello, emplearemos TypeScript, un superconjunto de JavaScript que agrega tipos estáticos para hacer el código más fiable, fácil de mantener y seguro, detectando errores pronto mientras se mantiene totalmente compatible con el JavaScript existente.

El flujo de los nodos será el siguiente:

La imagen de arriba es generada por LangGraph y representa el flujo de trabajo que define el orden de ejecución y la lógica condicional entre nodos:

decideStrategy: utiliza un LLM para analizar la consulta del usuario y decidir entre dos estrategias de búsqueda especializadas, como centrada en la inversión u orientada al mercado.
prepareInvestmentSearch: extrae valores de filtro de la consulta y construye una plantilla predefinida que destaca los parámetros financieros y de financiación.
prepareMarketSearch: extrae también los valores del filtro, pero construye dinámicamente parámetros que enfatizan el mercado, la industria y el contexto geográfico.
executeSearch: envía la consulta construida a Elasticsearch usando una plantilla de búsqueda y recupera los documentos de startups correspondientes.
visualizarResultados: formatea los resultados finales en un resumen claro y legible que muestre atributos clave de la startup, como financiación, industria e ingresos.

Este flujo incluye una ramificación condicional, que funciona como una declaración “si” que determina si se debe usar la ruta de búsqueda de inversión o de mercado según la entrada del usuario. Esta lógica de decisión, impulsada por el LLM, hace que el flujo de trabajo sea adaptativo y consciente del contexto, un mecanismo que exploraremos con más detalle en las siguientes secciones.

Estado de LangGraph

Antes de ver cada node individualmente, necesitamos entender cómo se comunican y comparten datos. Para ello, LangGraph nos permite definir el estado del flujo de trabajo. Esto define el estado compartido que se pasará entre los nodes.

El estado actúa como un contenedor compartido que almacena datos intermedios a lo largo del flujo de trabajo: comienza con la consulta en lenguaje natural del usuario, luego guarda la estrategia de búsqueda seleccionada, los parámetros preparados para Elasticsearch, los resultados de búsqueda recuperados y, finalmente, la salida formateada.

Esta estructura permite que cada node lea y actualice el estado, asegurando un flujo coherente de información desde la entrada del usuario hasta la visualización final.

const VCState = Annotation.Root({ input: Annotation(), // User's natural language query searchStrategy: Annotation(), // Search strategy chosen by LLM searchParams: Annotation(), // Prepared search parameters results: Annotation(), // Search results final: Annotation(), // Final formatted response });

Configure la aplicación

Todo el código de esta sección se puede encontrar en el repositorio elasticsearch-labs.

Abra un terminal en la carpeta donde estará la app e inicialice una aplicación Node.js con el comando:

npm init -y

Ahora podemos instalar las dependencias necesarias para este proyecto:

npm install @elastic/elasticsearch @langchain/langgraph @langchain/openai @langchain/core dotenv zod && npm install --save-dev @types/node tsx typescript

@elastic/elasticsearch: nos ayuda a gestionar las solicitudes de Elasticsearch, como la ingesta y la recuperación de datos.
@langchain/langgraph: Dependencia de JS para proporcionar todas las herramientas de LangGraph.
@langchain/openai: cliente de OpenAI LLM para LangChain.
@langchain/core: proporciona los bloques fundamentales del núcleo para las apps de LangChain, incluidas las plantillas de prompts.
dotenv: dependencia necesaria para usar variables de entorno en JavaScript.
zod: dependencia para escribir datos.

@types/node tsx typescript nos permite escribir y ejecutar código TypeScript.

Ahora crea los siguientes archivos:

elasticsearchSetup.ts: creará los mapping de índice, cargará el conjunto de datos desde un archivo JSON e ingerirá los datos en Elasticsearch.
main.ts: incluirá la aplicación LangGraph.
.env: archivo para almacenar las variables de entorno

En el archivo .env, agreguemos las siguientes variables de entorno:

ELASTICSEARCH_ENDPOINT="your-endpoint-here" ELASTICSEARCH_API_KEY="your-key-here" OPENAI_API_KEY="your-key-here"

La clave API de OpenAPI no se usará directamente en el código; en su lugar, se usará internamente por la biblioteca @langchain/openai.

Toda la lógica relacionada con la creación de mapping, la creación de plantillas de búsqueda y la ingesta de sets de datos se encuentra en el archivo elasticsearchSetup.ts. En los próximos pasos, nos centraremos en el archivo main.ts . Además, puedes consultar los sets de datos para entender mejor cómo se ven los datos en el dataset.json.

Aplicación LangGraph

En el archivo main.ts, vamos a importar algunas dependencias necesarias para consolidar la aplicación LangGraph. En este archivo, también debes incluir las funciones del node y la declaración de estado. La declaración del grafo se realizará en un método main en los siguientes pasos. El archivo elasticsearchSetup.ts contendrá ayudantes de Elasticsearch que vamos a usar dentro de los nodes en los próximos pasos.

import { writeFileSync } from "node:fs"; import { StateGraph, Annotation, START, END } from "@langchain/langgraph"; import { ChatOpenAI } from "@langchain/openai"; import { z } from "zod"; import { esClient, ingestDocuments, createSearchTemplates, INDEX_NAME, INVESTMENT_FOCUSED_TEMPLATE, MARKET_FOCUSED_TEMPLATE, createIndex, } from "./elasticsearchSetup.js"; const llm = new ChatOpenAI({ model: "gpt-4o-mini" });

Como se mencionó anteriormente, el cliente LLM se utilizará para generar los parámetros de la plantilla de búsqueda de Elasticsearch basados en la pregunta del usuario.

async function saveGraphImage(app: any): Promise { try { const drawableGraph = app.getGraph(); const image = await drawableGraph.drawMermaidPng(); const arrayBuffer = await image.arrayBuffer(); const filePath = "./workflow_graph.png"; writeFileSync(filePath, new Uint8Array(arrayBuffer)); console.log(`📊 Workflow graph saved as: ${filePath}`); } catch (error: any) { console.log("⚠️ Could not save graph image:", error.message); } }

El método anterior genera la imagen del grafo en formato png y utiliza la API de Mermaid.INK en segundo plano. Esto es útil si deseas ver cómo interactúan los nodes de la app con una visualización estilizada.

Nodes LangGraph

Ahora veamos cada node en detalle:

node decideSearchStrategy

El decideSearchStrategy node analiza la entrada del usuario y determina si realizar una búsqueda centrada en la inversión o en el mercado. Utiliza un LLM con un esquema de salida estructurado (definido con Zod) para clasificar el tipo de consulta. Antes de tomar la decisión, recupera los filtros disponibles del índice mediante una agregación, lo que garantiza que el modelo cuente con información actualizada sobre sectores, ubicaciones y datos de financiación.

Para extraer los posibles valores de los filtros y enviarlos al LLM, usemos una consulta de agregación para obtenerlos directamente del índice de Elasticsearch. Esta lógica se encuentra en un método llamado getAvailableFilters:

async function getAvailableFilters() { try { const response = await esClient.search({ index: INDEX_NAME, size: 0, aggs: { industries: { terms: { field: "industry", size: 100 }, }, locations: { terms: { field: "location", size: 100 }, }, funding_stages: { terms: { field: "funding_stage", size: 20 }, }, business_models: { terms: { field: "business_model", size: 10 }, }, lead_investors: { terms: { field: "lead_investor", size: 100 }, }, funding_amount_stats: { stats: { field: "funding_amount" }, }, }, }); return response.aggregations; } catch (error) { console.error("❌ Error getting available filters:", error); return {}; } }

Con la consulta de agregación anterior, tenemos los siguientes resultados:

{ "industries": { "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0, "buckets": [ { "key": "logistics", "doc_count": 5 }, ... ] }, "locations": { "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0, "buckets": [ { "key": "San Francisco, CA", "doc_count": 4 }, { "key": "New York, NY", "doc_count": 3 }, ... ] }, "funding_stages": { "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0, "buckets": [ { "key": "Series A", "doc_count": 8 }, ... ] }, "business_models": { "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0, "buckets": [ { "key": "B2B", "doc_count": 13 }, ... ] }, "lead_investors": { "doc_count_error_upper_bound": 0, "sum_other_doc_count": 0, "buckets": [ { "key": "Battery Ventures", "doc_count": 1 }, { "key": "Benchmark Capital", "doc_count": 1 }, ... ] }, "funding_amount_stats": { "count": 20, "min": 4500000, "max": 35000000, "avg": 14075000, "sum": 281500000 } }

Vea todos los resultados aquí.

Para ambas estrategias, utilizaremos la búsqueda híbrida para detectar tanto la parte estructurada de la pregunta (filtros) como las partes más subjetivas (semántica). A continuación se muestra un ejemplo de ambas consultas utilizando plantillas de búsqueda:

await esClient.putScript({ id: INVESTMENT_FOCUSED_TEMPLATE, script: { lang: "mustache", source: `{ "size": 5, "retriever": { "rrf": { "retrievers": [ { "standard": { "query": { "semantic": { "field": "semantic_field", "query": "{{query_text}}" } } } }, { "standard": { "query": { "bool": { "filter": [ {"terms": {"funding_stage": {{#join}}{{#toJson}}funding_stage{{/toJson}}{{/join}}}}, {"range": {"funding_amount": {"gte": {{funding_amount_gte}}{{#funding_amount_lte}},"lte": {{funding_amount_lte}}{{/funding_amount_lte}}}}}, {"terms": {"lead_investor": {{#join}}{{#toJson}}lead_investor{{/toJson}}{{/join}}}}, {"range": {"monthly_revenue": {"gte": {{monthly_revenue_gte}}{{#monthly_revenue_lte}},"lte": {{monthly_revenue_lte}}{{/monthly_revenue_lte}}}}} ] } } } } ], "rank_window_size": 100, "rank_constant": 20 } } }`, }, });

Vea las consultas detalladas en el archivo elasticsearchSetup.ts . En el siguiente node, se decidirá cuál de las dos consultas se empleará:

// Node 1: Decide search strategy using LLM async function decideSearchStrategy(state: typeof VCState.State) { // Zod schema for specialized search strategy decision const SearchDecisionSchema = z.object({ search_type: z .enum(["investment_focused", "market_focused"]) .describe("Type of specialized search strategy to use"), reasoning: z .string() .describe("Brief explanation of why this search strategy was chosen"), }); const decisionLLM = llm.withStructuredOutput(SearchDecisionSchema); // Get dynamic filters from Elasticsearch const availableFilters = await getAvailableFilters(); const prompt = `Query: "${state.input}" Available filters: ${JSON.stringify(availableFilters, null, 2)} Choose between two specialized search strategies: - investment_focused: For queries about funding stages, funding amounts, monthly revenue, lead investors, financial performance - market_focused: For queries about industries, locations, business models, market segments, geographic markets Analyze the query intent and choose the most appropriate strategy. `; try { const result = await decisionLLM.invoke(prompt); console.log( `🤔 Search strategy: ${result.search_type} - ${result.reasoning}` ); return { searchStrategy: result.search_type, }; } catch (error: any) { console.error("❌ Error in decideSearchStrategy:", error.message); return { searchStrategy: "investment_focused", }; } }

Nodes prepareInvestmentSearch y prepareMarketSearch

Ambos nodos emplean una función auxiliar compartida, extractFilterValues, que aprovecha el LLM para identificar los filtros relevantes mencionados en la entrada del usuario, como la industria, la ubicación, la etapa de financiación, el modelo de negocio, etc. Estamos utilizando este esquema para crear nuestra plantilla de búsqueda.

// Extract all possible filter values from user input async function extractFilterValues(input: string) { const FilterValuesSchema = z.object({ // Investment-focused filters funding_stage: z .array(z.string()) .default([]) .describe("Funding stage values mentioned in query"), funding_amount_gte: z .number() .default(0) .describe("Minimum funding amount in USD"), funding_amount_lte: z .number() .default(100000000) .describe("Maximum funding amount in USD"), lead_investor: z .array(z.string()) .default([]) .describe("Lead investor values mentioned in query"), monthly_revenue_gte: z .number() .default(0) .describe("Minimum monthly revenue in USD"), monthly_revenue_lte: z .number() .default(10000000) .describe("Maximum monthly revenue in USD"), industry: z .array(z.string()) .default([]) .describe("Industry values mentioned in query"), location: z .array(z.string()) .default([]) .describe("Location values mentioned in query"), business_model: z .array(z.string()) .default([]) .describe("Business model values mentioned in query"), }); const extractorLLM = llm.withStructuredOutput(FilterValuesSchema); const availableFilters = await getAvailableFilters(); const extractPrompt = `Extract ALL relevant filter values from: "${input}" Available options: ${JSON.stringify(availableFilters, null, 2)} Extract only values explicitly mentioned in the query. Leave fields empty if not mentioned.`; return await extractorLLM.invoke(extractPrompt); }

Según de la intención detectada, el flujo de trabajo selecciona una de dos rutas:

prepareInvestmentSearch: desarrolla parámetros de búsqueda orientados a la financiación, incluyendo la etapa de financiación, el importe de la inversión, el inversionista y la información de renovación. Puedes encontrar la plantilla completa de consulta en el archivo elasticsearchSetup.ts :

// Node 2A: Prepare Investment-Focused Search Parameters async function prepareInvestmentSearch(state: typeof VCState.State) { console.log( "💰 Preparing INVESTMENT-FOCUSED search parameters with financial emphasis..." ); try { // Extract all filter values from input const values = await extractFilterValues(state.input); let searchParams: any = { template_id: INVESTMENT_FOCUSED_TEMPLATE, query_text: state.input, ...values, }; return { searchParams }; } catch (error) { console.error("❌ Error preparing investment-focused params:", error); return { searchParams: {}, }; } }

prepareMarketSearch: crea parámetros orientados al mercado centrados en industrias, geografías y modelos de negocio. Ver la consulta completa en el archivo elasticsearchSetup.ts:

// Node 2B: Prepare Market-Focused Search Parameters async function prepareMarketSearch(state: typeof VCState.State) { console.log( "🔍 Preparing MARKET-FOCUSED search parameters with market emphasis..." ); try { // Extract all filter values from input const values = await extractFilterValues(state.input); let searchParams: any = { template_id: MARKET_FOCUSED_TEMPLATE, query_text: state.input, ...values, }; return { searchParams }; } catch (error) { console.error("❌ Error preparing market-focused params:", error); return {}; } }

Node executeSearch

Este node toma los parámetros de búsqueda generados del estado y los envía primero a Elasticsearch, usando la _render API para visualizar la consulta con fines de depuración, y luego envía una petición para recuperar los resultados.

// Node 3: Execute Search async function executeSearch(state: typeof VCState.State) { const { searchParams } = state; try { // getting formed query from template for debugging const renderedTemplate = await esClient.renderSearchTemplate({ id: searchParams.template_id, params: searchParams, }); console.log( "📋 Complete query:", JSON.stringify(renderedTemplate.template_output, null, 2) ); const results = await esClient.searchTemplate({ index: INDEX_NAME, id: searchParams.template_id, params: searchParams, }); return { results: results.hits.hits.map((hit: any) => hit._source), }; } catch (error: any) { console.error(`❌ ${state.searchParams.search_type} search error:`, error); return { results: [] }; } }

node visualizarResultados

Finalmente, este nodo muestra los resultados de Elasticsearch.

// Node 4: Visualize results async function visualizeResults(state: typeof VCState.State) { const results = state.results || []; let formattedResults = `🎯 Found ${results.length} startups matching your criteria:\n\n`; results.forEach((startup: any, index: number) => { formattedResults += `${index + 1}. **${startup.company_name}**\n`; formattedResults += ` 📍 ${startup.location} | 🏢 ${startup.industry} | 💼 ${startup.business_model}\n`; formattedResults += ` 💰 ${startup.funding_stage} - $${( startup.funding_amount / 1000000 ).toFixed(1)}M\n`; formattedResults += ` 👥 ${startup.employee_count} employees | 📈 $${( startup.monthly_revenue / 1000 ).toFixed(0)}K MRR\n`; formattedResults += ` 🏦 Lead: ${startup.lead_investor}\n`; formattedResults += ` 📝 ${startup.description}\n\n`; }); return { final: formattedResults, }; }

Programáticamente, todo el grafo se ve así:

const workflow = new StateGraph(VCState) // Register nodes - these are the processing functions .addNode("decideStrategy", decideSearchStrategy) .addNode("prepareInvestment", prepareInvestmentSearch) .addNode("prepareMarket", prepareMarketSearch) .addNode("executeSearch", executeSearch) .addNode("visualizeResults", visualizeResults) // Define execution flow with conditional branching .addEdge(START, "decideStrategy") // Start with strategy decision .addConditionalEdges( "decideStrategy", (state: typeof VCState.State) => state.searchStrategy, // Conditional function { investment_focused: "prepareInvestment", // If investment focused -> RRF template preparation market_focused: "prepareMarket", // If market focused -> dynamic query preparation } ) .addEdge("prepareInvestment", "executeSearch") // Investment prep -> execute .addEdge("prepareMarket", "executeSearch") // Market prep -> execute .addEdge("executeSearch", "visualizeResults") // Execute -> visualize .addEdge("visualizeResults", END); // End workflow

Como puede ver, tenemos una aplicación condicional donde la aplicación decide qué “ruta” o node ejecutar a continuación. Esta característica es útil cuando los flujos de trabajo necesitan lógica de ramificación, como elegir entre múltiples herramientas o incluir un paso con intervención de una persona.

Con las características básicas del núcleo de LangGraph entendidas, podemos configurar la aplicación donde se ejecutará el código:

Juntando todo en un flujo de trabajo main, aquí declaramos el grafo con todos los elementos bajo la variable flujo de trabajo:

async function main() { await createIndex(); await createSearchTemplates(); await ingestDocuments(); // Create the workflow graph with shared state const workflow = new StateGraph(VCState) // Register nodes - these are the processing functions .addNode("decideStrategy", decideSearchStrategy) .addNode("prepareInvestment", prepareInvestmentSearch) .addNode("prepareMarket", prepareMarketSearch) .addNode("executeSearch", executeSearch) .addNode("visualizeResults", visualizeResults) // Define execution flow with conditional branching .addEdge(START, "decideStrategy") // Start with strategy decision .addConditionalEdges( "decideStrategy", (state: typeof VCState.State) => state.searchStrategy, // Conditional function { investment_focused: "prepareInvestment", // If investment focused -> RRF template preparation market_focused: "prepareMarket", // If market focused -> dynamic query preparation } ) .addEdge("prepareInvestment", "executeSearch") // Investment prep -> execute .addEdge("prepareMarket", "executeSearch") // Market prep -> execute .addEdge("executeSearch", "visualizeResults") // Execute -> visualize .addEdge("visualizeResults", END); // End workflow const app = workflow.compile(); await saveGraphImage(app); const query = "Find startups with Series A or Series B funding between $8M-$25M and monthly revenue above $500K"; const marketResult = await app.invoke({ input: query }); console.log(marketResult.final); }

La variable de consulta simula la entrada del usuario introducida en una barra de búsqueda hipotética:

De la frase en lenguaje natural “Encuentra startups con financiamiento de Serie A o Serie B entre $8M y $25M, e ingresos mensuales superiores a $500K” se extraerán todos los filtros.

Finalmente, invoca el método principal:

main().catch(console.error);

Resultados

🔍 Checking if index exists... 🏗️ Creating index... ✅ Index created successfully! Ingesting documents... ✅ Documents ingested successfully! ✅ Investment-focused template created successfully! ✅ Market-focused template created successfully! 📊 Workflow graph saved as: ./workflow_graph.png 🔍 Query: "Find startups with Series A or Series B funding between $8M-$25M and monthly revenue above $500K" 🤔 Search strategy: investment_focused - The query specifically seeks profitable fintech startups with defined funding amounts and high monthly revenue, which aligns closely with financial performance metrics and investment-related criteria. 💰 Preparing INVESTMENT-FOCUSED search parameters with financial emphasis... 📋 Complete query: { "size": 5, "retriever": { "rrf": { "retrievers": [ { "standard": { "query": { "semantic": { "field": "semantic_field", "query": "Find startups with Series A or Series B funding between $8M-$25M and monthly revenue above $500K" } } } }, { "standard": { "query": { "bool": { "filter": [ { "terms": { "funding_stage": [ "Series A", "Series B" ] } }, { "range": { "funding_amount": { "gte": 8000000, "lte": 25000000 } } }, { "terms": { "lead_investor": [] } }, { "range": { "monthly_revenue": { "gte": 500000, "lte": 0 } } } ] } } } } ], "rank_window_size": 100, "rank_constant": 20 } } } 🎯 Found 5 startups matching your criteria: 1. **TechFlow** 📍 San Francisco, CA | 🏢 logistics | 💼 B2B 💰 Series A - $8.0M 👥 45 employees | 📈 $500K MRR 🏦 Lead: Sequoia Capital 📝 TechFlow optimizes supply chain operations using AI-powered route optimization and real-time tracking. Founded in 2023, shows remarkable growth with $500K monthly revenue. 2. **DataViz** 📍 New York, NY | 🏢 enterprise software | 💼 B2B 💰 Series A - $10.0M 👥 42 employees | 📈 $450K MRR 🏦 Lead: Battery Ventures 📝 DataViz creates intuitive data visualization tools for enterprise customers. No-code platform allows business users to create dashboards without technical expertise. 3. **FinanceAI** 📍 San Francisco, CA | 🏢 fintech | 💼 B2C 💰 Series C - $25.0M 👥 120 employees | 📈 $1200K MRR 🏦 Lead: Tiger Global Management 📝 FinanceAI provides AI-powered investment advisory services to retail investors. Uses machine learning to analyze market trends with over 100,000 active users. 4. **UrbanMobility** 📍 New York, NY | 🏢 logistics | 💼 B2B2C 💰 Series B - $15.0M 👥 78 employees | 📈 $750K MRR 🏦 Lead: Kleiner Perkins 📝 UrbanMobility revolutionizes urban transportation through autonomous delivery drones and smart logistics hubs. Partners with major retailers for same-day delivery across Manhattan and Brooklyn. 5. **HealthTech Solutions** 📍 Boston, MA | 🏢 healthcare | 💼 B2B 💰 Series B - $18.0M 👥 95 employees | 📈 $900K MRR 🏦 Lead: General Catalyst 📝 HealthTech Solutions develops medical devices and software for remote patient monitoring. Comprehensive telehealth platform reducing hospital readmissions by 30%. ✨ Done in 18.80s.

Para la entrada enviada, la aplicación elige la ruta centrada en la inversión y, como resultado, podemos ver la consulta de Elasticsearch generada por el flujo de trabajo de LangGraph, que extrae los valores y los rangos de la entrada del usuario. También podemos ver la consulta enviada a Elasticsearch con los valores extraídos aplicados y, finalmente, los resultados formateados por el node visualizeResults con los resultados.

Ahora vamos a probar el node centrado en el mercado usando la consulta “Encuentre startups de fintech y salud en San Francisco, Nueva York o Boston”:

... 🔍 Query: Find fintech and healthcare startups in San Francisco, New York, or Boston 🤔 Search strategy: market_focused - The query is focused on finding fintech startups in San Francisco that are disrupting traditional banking and payment systems, which pertains to specific industries (fintech) and locations (San Francisco). Thus, a market-focused strategy is more appropriate. 🔍 Preparing MARKET-FOCUSED search parameters with market emphasis... 📋 Complete query: { "size": 5, "retriever": { "rrf": { "retrievers": [ { "standard": { "query": { "semantic": { "field": "semantic_field", "query": "Find fintech and healthcare startups in San Francisco, New York, or Boston" } } } }, { "standard": { "query": { "bool": { "filter": [ { "terms": { "industry": [ "fintech", "healthcare" ] } }, { "terms": { "location": [ "San Francisco, CA", "New York, NY", "Boston, MA" ] } }, { "terms": { "business_model": [] } } ] } } } } ], "rank_window_size": 50, "rank_constant": 10 } } } 🎯 Found 5 startups matching your criteria: 1. **FinanceAI** 📍 San Francisco, CA | 🏢 fintech | 💼 B2C 💰 Series C - $25.0M 👥 120 employees | 📈 $1200K MRR 🏦 Lead: Tiger Global Management 📝 FinanceAI provides AI-powered investment advisory services to retail investors. Uses machine learning to analyze market trends with over 100,000 active users. 2. **CryptoWallet** 📍 Miami, FL | 🏢 fintech | 💼 B2C 💰 Series B - $16.0M 👥 73 employees | 📈 $820K MRR 🏦 Lead: Coinbase Ventures 📝 CryptoWallet provides secure digital wallet solutions for cryptocurrency trading and storage. Multi-chain support with enterprise-grade security features. ... ✨ Done in 7.41s.

Aprendizajes

Durante el proceso de escritura aprendí:

Debemos mostrar al LLM los valores exactos de los filtros; de lo contrario, dependemos de que el usuario escriba los valores exactos de las cosas. Para baja cardinalidad, este enfoque está bien, pero cuando la cardinalidad es alta, necesitamos algún mecanismo para filtrar los resultados.
El uso de plantillas de búsqueda hace que los resultados sean mucho más consistentes que dejar que el LLM escriba la consulta de Elasticsearch, y también es más rápido.
Los bordes condicionales son un mecanismo potente para crear aplicaciones con múltiples variantes y rutas de ramificación.
La salida estructurada es extremadamente útil cuando se genera información con LLM porque impone respuestas predecibles y de tipo seguro. Esto mejora la confiabilidad y reduce las interpretaciones incorrectas de los prompts.

La combinación de búsqueda semántica y estructurada a través de la recuperación híbrida produce resultados mejores y más relevantes, equilibrando la precisión y la comprensión del contexto.

Conclusión

En este ejemplo, combinamos LangGraph.js con Elasticsearch para crear un flujo de trabajo dinámico capaz de interpretar consultas en lenguaje natural y decidir entre estrategias de búsqueda financieras u orientadas al mercado. Este enfoque reduce la complejidad de la creación de consultas manuales, al tiempo que mejora la flexibilidad y la precisión para los analistas de capital de riesgo.

Paneles impulsados por IA: de una visión a Kibana

Jeffrey Rengifo,Tomás Murúa — Wed, 16 Jul 2025 00:00:00 GMT

Kibana Lens hace que los paneles de control sean muy sencillos, pero cuando necesitas decenas de paneles, los clics se acumulan. ¿Y si pudieras hacer un boceto de un panel de control, hacer capturas de pantalla y dejar que un LLM termine todo el proceso por ti?

En este artículo, haremos que eso suceda. Crearemos una aplicación que tome una imagen de un panel de control, analice nuestros mapeos y luego genere un panel sin que tengamos que tocar Kibana en absoluto.

Pasos:

Antecedentes y flujo de trabajo de la aplicación

La primera idea que se me ocurrió fue dejar que el LLM generara todo el formato NDJSON de los objetos almacenados de Kibana y luego los importara a Kibana.

Probamos algunos modelos:

Gemini 2.5 pro
GPT o3 / o4-mini-alto / 4,1
Claude 4 soneto
Grok 3
Deepseek (Deepthink R1)

Y para los prompts, empezamos tan sencillos como:

You are an Elasticsearch Saved-Object generator (Kibana 9.0). INPUTS ===== 1. PNG screenshot of a 4-panel dashboard (attached). 2. Index mapping (below) – trimmed down to only the fields present in the screenshot. 3. Example NDJSON of *one* metric visualization (below) for reference. TASK ==== Return **only** a valid NDJSON array that recreates the dashboard exactly: * 2 metric panels (Visits, Unique Visitors) * 1 pie chart (Most used OS) * 1 vertical bar chart (State Geo Dest) * Use index pattern `kibana_sample_data_logs`. * Preserve roughly the same layout (2×2 grid). * Use `panelIndex` values 1-4 and random `id` strings. * Kibana version: 9.0

A pesar de repasar algunos ejemplos de planos y explicaciones detalladas sobre cómo construir cada visualización, no tuvimos suerte. Si te interesa esta experimentación, puedes encontrar detalles aquí.

El resultado de este enfoque fue ver estos mensajes al intentar subir a Kibana los archivos producidos por el LLM:

Esto significa que el JSON generado es inválido o está mal formateado. Los problemas más comunes eran que el LLM producía NDJSON incompleto, alucinaban parámetros o devolvían JSON normal en lugar de NDJSON, por mucho que intentáramos hacer cumplir lo contrario.

Inspirados por este artículo —donde las plantillas de búsqueda funcionaban mejor que el estilo libre de un LLM— decidimos dar plantillas al LLM en lugar de pedir generar el archivo NDJSON completo y luego, en código, usar los parámetros dados por el LLM para crear las visualizaciones adecuadas. Este enfoque no decepcionó, y es previsible y ampliable, ya que ahora el código hace el trabajo duro y no el LLM.

El flujo de trabajo de la aplicación será el siguiente:

Omitiremos algo de código para simplificar, pero puedes encontrar el código funcional de la aplicación completa en este cuaderno.

Prerrequisitos

Antes de empezar a desarrollar, necesitarás lo siguiente:

Python 3.8 o superior
Un entorno Venv Python
Una instancia de Elasticsearch en ejecución, junto con su endpoint y clave API
Una clave de API de OpenAI almacenada bajo el nombre de la variable de entorno OPENAI_API_KEY:

export OPENAI_API_KEY="your-openai-api-key"

Preparar datos

Para los datos, lo mantendremos sencillo y usaremos registros sitio web de muestra de Elastic. Puedes aprender cómo importar esos datos a tu clúster aquí.

Cada documento incluye detalles sobre el anfitrión que emitió las solicitudes a la aplicación, junto con información sobre la propia solicitud y su estado de respuesta. A continuación se muestra un documento de ejemplo:

{ "agent": "Mozilla/5.0 (X11; Linux i686) AppleWebKit/534.24 (KHTML, like Gecko) Chrome/11.0.696.50 Safari/534.24", "bytes": 8509, "clientip": "70.133.115.149", "extension": "css", "geo": { "srcdest": "US:IT", "src": "US", "dest": "IT", "coordinates": { "lat": 38.05134111, "lon": -103.5106908 } }, "host": "cdn.elastic-elastic-elastic.org", "index": "kibana_sample_data_logs", "ip": "70.133.115.149", "machine": { "ram": 5368709120, "os": "osx" }, "memory": null, "message": "70.133.115.149 - - [2018-08-30T23:35:31.492Z] \"GET /styles/semantic-ui.css HTTP/1.1\" 200 8509 \"-\" \"Mozilla/5.0 (X11; Linux i686) AppleWebKit/534.24 (KHTML, like Gecko) Chrome/11.0.696.50 Safari/534.24\"", "phpmemory": null, "referer": "http://twitter.com/error/john-phillips", "request": "/styles/semantic-ui.css", "response": 200, "tags": [ "success", "info" ], "@timestamp": "2025-07-03T23:35:31.492Z", "url": "https://cdn.elastic-elastic-elastic.org/styles/semantic-ui.css", "utc_time": "2025-07-03T23:35:31.492Z", "event": { "dataset": "sample_web_logs" }, "bytes_gauge": 8509, "bytes_counter": 51201128 }

Ahora, vamos a tomar los mapeos del índice que acabamos de cargar, kibana_sample_data_logs:

INDEX_NAME = "kibana_sample_data_logs" es_client = Elasticsearch( [os.getenv("ELASTICSEARCH_URL")], api_key=os.getenv("ELASTICSEARCH_API_KEY"), ) result = es_client.indices.get_mapping(index=INDEX_NAME) index_mappings = result[list(result.keys())[0]]["mappings"]["properties"]

Vamos a pasar los mapeos junto con la imagen que cargaremos más adelante.

Configuración de LLM

Configuremos el LLM para que use una salida estructurada para introducir una imagen y recibir un JSON con la información que necesitamos pasar a nuestra función para producir los objetos JSON.

Instalamos las dependencias:

pip install elasticsearch pydantic langchain langchain-openai -q

Elasticsearch nos ayudará a recuperar los mapeos de índice. Pydantic nos permite definir esquemas en Python para luego pedir al LLM que lo siga, y LangChain es el framework que facilita la llamada a LLMs y herramientas de IA.

Crearemos un esquema Pydantic para definir la salida que queremos del LLM. Lo que necesitamos saber de la imagen es el tipo de gráfico, campo, título de visualización y título del panel de control:

class Visualization(BaseModel): title: str = Field(description="The dashboard title") type: List[Literal["pie", "bar", "metric"]] field: str = Field( description="The field that this visualization use based on the provided mappings" ) class Dashboard(BaseModel): title: str = Field(description="The dashboard title") visualizations: List[Visualization]

Para la entrada de imagen enviaremos un panel de control que acabo de dibujar:

Ahora declaramos la llamada al modelo LLM y la carga de imagen. Esta función recibirá los mapeos del índice de Elasticsearch y una imagen del panel de control que queremos generar.

Con with_structured_output podemos usar nuestro esquema de Dashboard Pydantic como objeto de respuesta que producirá el LLM. Con Pydantic, podemos definir modelos de datos con validación, lo que garantiza que la salida del LLM coincida con la estructura esperada.

Para convertir la imagen a base64 y enviarla como entrada, puedes usar un convertidor online o hacerlo en código.

prompt = f""" You are an expert in analyzing Kibana dashboards from images for the version 9.0.0 of Kibana. You will be given a dashboard image and an Elasticsearch index mapping. Below are the index mappings for the index that the dashboard is based on. Use this to help you understand the data and the fields that are available. Index Mappings: {index_mappings} Only include the fields that are relevant for each visualization, based on what is visible in the image. """ message = [ { "role": "user", "content": [ {"type": "text", "text": prompt}, { "type": "image", "source_type": "base64", "data": image_base64, "mime_type": "image/png", }, ], } ] try: llm = init_chat_model("gpt-4.1-mini") llm = llm.with_structured_output(Dashboard) dashboard_values = llm.invoke(message) print("Dashboard values generated by the LLM successfully") print(dashboard_values) except Exception as e: print(f"Failed to analyze image and match fields: {str(e)}")

El LLM ya tiene contexto sobre los paneles Kibana, así que no necesitamos explicar todo en el prompt, solo algunos detalles para cerciorarnos de que no olvide que está funcionando con Elasticsearch y Kibana.

Vamos a desglosar el prompt:

Sección

Razón

Eres un experto en analizar paneles de Kibana a partir de imágenes para la versión 9.0.0 de Kibana.

Al reforzar esto es Elasticsearch, y la versión de Elasticsearch reducimos la probabilidad de que el LLM alucine parámetros antiguos o inválidos.

Se te dará una imagen del panel de control y un mapeo de índice de Elasticsearch.

Explicamos que la imagen trata sobre paneles para evitar interpretaciones erróneas por parte del LLM.

A continuación se muestran los mapeos de índices del índice en el que se basa el panel de control. Emplea esto para ayudarte a entender los datos y los campos disponibles. Mapeos de índice: {index_mappings}

Es crucial proporcionar los mapeos para que el LLM pueda seleccionar campos válidos dinámicamente. De lo contrario, podríamos codificar los mapeos aquí, lo cual es demasiado rígido, o confiar en la imagen que contiene los nombres de campo correctos, lo cual no es fiable.

Incluye solo los campos relevantes para cada visualización, basándote en lo que sea visible en la imagen.

Tuvimos que agregar este refuerzo porque a veces intenta agregar campos que no son relevantes para la imagen.

Esto devolverá un objeto con un serial de visualizaciones para mostrar:

"Dashboard values generated by the LLM successfully title=""Client, Extension, OS, and Response Keyword Analysis""visualizations="[ "Visualization(title=""Count of Client IP", "type="[ "metric" ], "field=""clientip"")", "Visualization(title=""Extension Keyword Distribution", "type="[ "pie" ], "field=""extension.keyword"")", "Visualization(title=""Most Used OS", "type="[ "bar" ], "field=""machine.os.keyword"")", "Visualization(title=""Response Keyword Distribution", "type="[ "bar" ], "field=""response.keyword"")" ]

Procesamiento de la respuesta de los LLM

Creamosun panel de panel de muestra 2x2 y luego lo exportamos en JSON usando la API Get a dashboard, y después almacenamos los paneles como plantillas de visualización (pastel, barra, métrica) donde podemos reemplazar algunos parámetros para crear nuevas visualizaciones con diferentes campos según la pregunta.

Puedes ver los archivos JSON de plantilla aquí. Fíjate en cómo cambiamos los valores de los objetos que queremos reemplazar más adelante por {variable_name}

Con la información que nos proporcionó el LLM, podemos decidir qué plantilla usar y qué valores reemplazar.

fill_template_with_analysis recibirá los parámetros de un único panel, incluyendo la plantilla JSON de la visualización, un título, un campo y las coordenadas de la visualización en la cuadrícula.

Luego, reemplazará los valores de la plantilla y devolverá la visualización JSON final.

def fill_template_with_analysis( template: Dict[str, Any], visualization: Visualization, grid_data: Dict[str, Any], ): template_str = json.dumps(template) replacements = { "{visualization_id}": str(uuid.uuid4()), "{title}": visualization.title, "{x}": grid_data["x"], "{y}": grid_data["y"], } if visualization.field: replacements["{field}"] = visualization.field for placeholder, value in replacements.items(): template_str = template_str.replace(placeholder, str(value)) return json.loads(template_str)

Para simplificar, tendremos coordenadas estáticas que asignaremos a los paneles que el LLM decida crear y produciremos un panel de cuadrícula 2x2 como en la imagen anterior.

# Filling templates fields panels = [] grid_data = [ {"x": 0, "y": 0}, {"x": 12, "y": 0}, {"x": 0, "y": 12}, {"x": 12, "y": 12}, ] i = 0 for vis in dashboard_values.visualizations: for vis_type in vis.type: template = templates.get(vis_type, templates.get("bar", {})) filled_panel = fill_template_with_analysis(template, vis, grid_data[i]) panels.append(filled_panel) i += 1

Dependiendo del tipo de visualización decidido por el LLM, elegiremos una plantilla de archivo JSON y reemplazaremos la información relevante usando fill_template_with_analysis , luego agregaremos el nuevo panel a un array que usaremos más adelante para crear el panel de control.

Cuando el panel esté listo, usaremos la API Crear un panel para enviar el nuevo archivo JSON a Kibana y generar el panel:

try: dashboard_id = str(uuid.uuid4()) # post request to create the dashboard endpoint url = f"{os.getenv('KIBANA_URL')}/api/dashboards/dashboard/{dashboard_id}" dashboard_config = { "attributes": { "title": dashboard_values.title, "description": "Generated by AI", "timeRestore": True, "panels": panels, # Visualizations with the values generated by the LLM "timeFrom": "now-7d/d", "timeTo": "now", }, } headers = { "Content-Type": "application/json", "kbn-xsrf": "true", "Authorization": f"ApiKey {os.getenv('ELASTICSEARCH_API_KEY')}", } requests.post( url, headers=headers, json=dashboard_config, ) # Url to the generated dashboard dashboard_url = f"{os.getenv('KIBANA_URL')}/app/dashboards#/view/{dashboard_id}" print("Dashboard URL: ", dashboard_url) print("Dashboard ID: ", dashboard_id) except Exception as e: print(f"Failed to create dashboard: {str(e)}")

Para ejecutar el script y generar el panel de control, ejecuta el siguiente comando en la consola:

python .py

El resultado final será el siguiente:

Conclusión

Los LLMs muestran sus fuertes capacidades visuales al hacer texto a código o convertir imágenes en código. La API de los paneles también permite convertir archivos JSON en paneles, y con un LLM y algo de código, podemos convertir imágenes en un panel Kibana.

El siguiente paso es mejorar la flexibilidad de los gráficos del salpicadero empleando diferentes configuraciones de cuadra, tamaños y posiciones de tablero. Además, ofrecer soporte para visualizaciones y tipos de visualización más complejos sería una adición útil a esta aplicación.

Elasticsearch en JavaScript de la manera correcta, parte II

Jeffrey Rengifo — Mon, 19 May 2025 00:00:00 GMT

Esta es la segunda parte de nuestro serial Elasticsearch en JavaScript. En la primera parte, aprendimos a configurar correctamente nuestro entorno, configurar el cliente Node.js, indexar datos y buscar. En esta segunda parte, aprenderemos a implementar las mejores prácticas de producción y a ejecutar el cliente de Node.js Elasticsearch en entornos sin servidor.

Revisaremos:

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

Mejores prácticas de producción

Manejo de errores en Elasticsearch

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

Para verlos todos, pon esto:

const { errors } = require('@elastic/elasticsearch') console.log(errors)

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

app.get("/search/lexic", async (req, res) => { .... } catch (error) { if (error instanceof errors.ResponseError) { let errorMessage = "Response error!, query malformed or server down, contact the administrator!"; if (error.body.error.type === "parsing_exception") { errorMessage = "Query malformed, make sure mappings are set correctly"; } res.status(error.meta.statusCode).json({ erroStatus: error.meta.statusCode, success: false, results: null, error: errorMessage, }); } res.status(500).json({ success: false, results: null, error: error.message, }); } });

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

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

Error por defecto:

{ "success": false, "results": null, "error": "parsing_exception\n\tRoot causes:\n\t\tparsing_exception: [terms] query does not support [visit_details]" }

Error personalizado:

{ "erroStatus": 400, "success": false, "results": null, "error": "Response error!, query malformed or server down; contact the administrator!" }

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

app.get("/search/semantic", async (req, res) => { try { ... } catch (error) { if (error instanceof errors.TimeoutError) { // Retry logic... res.status(error.meta.statusCode).json({ erroStatus: error.meta.statusCode, success: false, results: null, error: "The request took more than 10s after 3 retries. Try again later.", }); } } });

Pruebas

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

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

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

npm install @elastic/elasticsearch-mock

npm install --save-dev ava

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

"type": "module", "scripts": { "test": "ava" }, "devDependencies": { "ava": "^5.0.0" }

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

const { Client } = require('@elastic/elasticsearch') const Mock = require('@elastic/elasticsearch-mock') const mock = new Mock() const client = new Client({ node: 'http://localhost:9200', Connection: mock.getConnection() })

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

function createSemanticSearchMock(query, indexName) { mock.add( { method: "POST", path: `/${indexName}/_search`, body: { query: { semantic: { field: "semantic_field", query: query, }, }, }, }, () => { return { hits: { total: { value: 2, relation: "eq" }, hits: [ { _id: "1", _score: 0.9, _source: { owner_name: "Alice Johnson", pet_name: "Buddy", species: "Dog", breed: "Golden Retriever", vaccination_history: ["Rabies", "Parvovirus", "Distemper"], visit_details: "Annual check-up and nail trimming. Healthy and active.", }, }, { _id: "2", _score: 0.7, _source: { owner_name: "Daniel Kim", pet_name: "Mochi", species: "Rabbit", breed: "Mixed", vaccination_history: [], visit_details: "Nail trimming and general health check. No issues.", }, }, ], }, }; } ); }

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

import test from 'ava'; test("performSemanticSearch must return formatted results correctly", async (t) => { const indexName = "vet-visits"; const query = "Which pets had nail trimming?"; createSemanticSearchMock(query, indexName); async function performSemanticSearch(esClient, q, indexName = "vet-visits") { try { const result = await esClient.search({ index: indexName, body: { query: { semantic: { field: "semantic_field", query: q, }, }, }, }); return { success: true, results: result.hits.hits, }; } catch (error) { if (error instanceof errors.TimeoutError) { return { success: false, results: null, error: error.body.error.reason, }; } return { success: false, results: null, error: error.message, }; } } const result = await performSemanticSearch(esClient, query, indexName); t.true(result.success, "The search must be successful"); t.true(Array.isArray(result.results), "The results must be an array"); if (result.results.length > 0) { t.true( "_source" in result.results[0], "Each result must have a _source property" ); t.true( "pet_name" in result.results[0]._source, "Results must include the pet_name field" ); t.true( "visit_details" in result.results[0]._source, "Results must include the visit_details field" ); } });

Hagamos las pruebas.

npm run test

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

Entornos sin servidor

Cómo ejecutar el cliente en Elastic Serverless

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

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

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

El cliente realiza las siguientes adaptaciones para conectarse a Serverless:

Apaga el olfateo e ignora cualquier opción relacionada con el olfateo
Ignora todos los nodos que pasan en la configuración excepto el primero, e ignora cualquier filtrado de nodos y seleccionando opciones
Activa la compresión y el 'TLSv1_2_method' (igual que cuando se configura para Elastic Cloud)
Agrega un encabezado HTTP 'elastic-api-version' a todas las solicitudes
Emplea 'CloudConnectionPool' por defecto en lugar de 'WeightedConnectionPool'
Desactiva los encabezados 'content-type' y 'accept' que venden en favor de los tipos MIME estándar

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

const { Client } = require('@elastic/elasticsearch') const client = new Client({ node: 'ELASTICSEARCH_ENDPOINT', auth: { apiKey: 'ELASTICSEARCH_API_KEY' }, serverMode: "serverless", });

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

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

'use strict' const { Client } = require('@elastic/elasticsearch') const client = new Client({ // client initialisation }) exports.handler = async function (event, context) { // use the client }

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

const response = await client.search( { index: INDEX, // You could directly send from the browser // the Elasticsearch's query DSL, but it will // expose you to the risk that a malicious user // could overload your cluster by crafting // expensive queries. query: { match: { field: req.body.text }, }, }, { headers: { Authorization: `ApiKey ${token}`, }, } );

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

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

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

Conclusión

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

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

Elasticsearch en JavaScript de la manera correcta, parte I

Jeffrey Rengifo — Thu, 15 May 2025 00:00:00 GMT

Este es el primer artículo de un serial que explica cómo usar Elasticsearch con JavaScript. En este serial, aprenderás lo básico sobre cómo usar Elasticsearch en un entorno JavaScript y revisarás las características y mejores prácticas más relevantes para crear una aplicación de búsqueda. Al final, sabrás todo lo necesario para ejecutar Elasticsearch usando JavaScript.

En esta primera parte, repasaremos:

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

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

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

Medio ambiente

¿Frontend, backend o serverless?

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

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

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

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

Sugerimos usar un esquema como este:

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

Conexión del cliente

Empieza creando una clave API siguiendo estos pasos.

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

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

Inicialemos el proyecto:

npm init -y

Dependencias de instalación:

npm install @elastic/elasticsearch express split2 dotenv

Déjame explicártelo:

@elastic/elasticsearch: Es el cliente oficial de Node.js
express: Nos permitirá montar un servidor nodejs ligero para exponer Elasticsearch
split2: Divide líneas de texto en un flujo. Útil para procesar nuestros archivos de ndjson línea a línea
dotenv: Permítenos gestionar variables de entorno usando un .env archivo

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

ELASTICSEARCH_ENDPOINT="Your Elasticsearch endpoint" ELASTICSEARCH_API_KEY="Your Elasticssearch API"

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

Crea un archivo server.js :

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

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

Ejecuta el archivo para abrir el servidor:

node server.js

La respuesta debería ser la siguiente:

Server running on port 3000

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

curl http://localhost:3000/ping { "success": true, "clusterInfo": { "name": "instance-0000000000", "cluster_name": "61b7e19eec204d59855f5e019acd2689", "cluster_uuid": "BIfvfLM0RJWRK_bDCY5ldg", "version": { "number": "9.0.0", "build_flavor": "default", "build_type": "docker", "build_hash": "112859b85d50de2a7e63f73c8fc70b99eea24291", "build_date": "2025-04-08T15:13:46.049795831Z", "build_snapshot": false, "lucene_version": "10.1.0", "minimum_wire_compatibility_version": "8.18.0", "minimum_index_compatibility_version": "8.0.0" }, "tagline": "You Know, for Search" } }

Indexación de documentos

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

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

Cliente Elasticsearch

Primero necesitamos instanciar y autenticar al cliente:

const { Client } = require("@elastic/elasticsearch"); const ELASTICSEARCH_ENDPOINT = "cluster/project_endpoint"; const ELASTICSEARCH_API_KEY = "apiKey"; const esClient = new Client({ node: ELASTICSEARCH_ENDPOINT, auth: { apiKey: ELASTICSEARCH_API_KEY }, });

Aplicaciones semánticas

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

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

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

Ayudante a granel

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

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

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

{"owner_name":"Alice Johnson","pet_name":"Buddy","species":"Dog","breed":"Golden Retriever","vaccination_history":["Rabies","Parvovirus","Distemper"],"visit_details":"Annual check-up and nail trimming. Healthy and active."} {"owner_name":"Marco Rivera","pet_name":"Milo","species":"Cat","breed":"Siamese","vaccination_history":["Rabies","Feline Leukemia"],"visit_details":"Slight eye irritation, prescribed eye drops."} {"owner_name":"Sandra Lee","pet_name":"Pickles","species":"Guinea Pig","breed":"Mixed","vaccination_history":[],"visit_details":"Loss of appetite, recommended dietary changes."} {"owner_name":"Jake Thompson","pet_name":"Luna","species":"Dog","breed":"Labrador Mix","vaccination_history":["Rabies","Bordetella"],"visit_details":"Mild ear infection, cleaning and antibiotics given."} {"owner_name":"Emily Chen","pet_name":"Ziggy","species":"Cat","breed":"Mixed","vaccination_history":["Rabies","Feline Calicivirus"],"visit_details":"Vaccination update and routine physical."} {"owner_name":"Tomás Herrera","pet_name":"Rex","species":"Dog","breed":"German Shepherd","vaccination_history":["Rabies","Parvovirus","Leptospirosis"],"visit_details":"Follow-up for previous leg strain, improving well."} {"owner_name":"Nina Park","pet_name":"Coco","species":"Ferret","breed":"Mixed","vaccination_history":["Rabies"],"visit_details":"Slight weight loss; advised new diet."} {"owner_name":"Leo Martínez","pet_name":"Simba","species":"Cat","breed":"Maine Coon","vaccination_history":["Rabies","Feline Panleukopenia"],"visit_details":"Dental cleaning. Minor tartar buildup removed."} {"owner_name":"Rachel Green","pet_name":"Rocky","species":"Dog","breed":"Bulldog Mix","vaccination_history":["Rabies","Parvovirus"],"visit_details":"Skin rash, antihistamines prescribed."} {"owner_name":"Daniel Kim","pet_name":"Mochi","species":"Rabbit","breed":"Mixed","vaccination_history":[],"visit_details":"Nail trimming and general health check. No issues."}

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

const { createReadStream } = require("fs"); const split = require("split2"); const indexData = async (filePath, indexName) => { try { console.log(`Indexing data from ${filePath} into ${indexName}...`); const result = await esClient.helpers.bulk({ datasource: createReadStream(filePath).pipe(split()), onDocument: () => { return { index: { _index: indexName }, }; }, onDrop(doc) { console.error("Error processing document:", doc); }, }); console.log("Bulk indexing successful elements:", result.items.length); } catch (error) { console.error("Error indexing data:", error); throw error; } }; await indexData("./data.ndjson", INDEX_NAME);

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

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

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

node load.js

Creating mappings for index vet-visits... Index created successfully: { acknowledged: true, shards_acknowledged: true, index: 'vet-visits' } Indexing data from ./data.ndjson into vet-visits... Bulk indexing completed. Total documents: 10, Failed: 0

Búsqueda de datos en Elasticsearch

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

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

Tipo de consulta

Caso de uso

Pregunta de ejemplo

Consulta léxica

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

Busco una camiseta deportiva azul.

Consulta semántica

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

Busco ropa para el frío.

Búsqueda híbrida

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

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

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

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

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

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

app.get("/search/lexic", async (req, res) => { const { q } = req.query; const INDEX_NAME = "vet-visits"; try { const result = await esClient.search({ index: INDEX_NAME, size: 5, body: { query: { multi_match: { query: q, fields: ["owner_name", "pet_name", "visit_details"], }, }, }, }); res.status(200).json({ success: true, results: result.hits.hits }); } catch (error) { console.error("Error performing search:", error); res.status(500).json({ success: false, results: null, error: error.message, }); } });

Probamos con: corte de uñas

curl http://localhost:3000/search/lexic?q=nail%20trimming

Respuesta:

{ "success": true, "results": [ { "_index": "vet-visits", "_id": "-RY6RJYBLe2GoFQ6-9n9", "_score": 2.7075968, "_source": { "pet_name": "Mochi", "owner_name": "Daniel Kim", "species": "Rabbit", "visit_details": "Nail trimming and general health check. No issues.", "breed": "Mixed", "vaccination_history": [] } }, { "_index": "vet-visits", "_id": "8BY6RJYBLe2GoFQ6-9n9", "_score": 2.560356, "_source": { "pet_name": "Buddy", "owner_name": "Alice Johnson", "species": "Dog", "visit_details": "Annual check-up and nail trimming. Healthy and active.", "breed": "Golden Retriever", "vaccination_history": [ "Rabies", "Parvovirus", "Distemper" ] } } ] }

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

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

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

app.get("/search/semantic", async (req, res) => { const { q } = req.query; const INDEX_NAME = "vet-visits"; try { const result = await esClient.search({ index: INDEX_NAME, size: 5, body: { query: { semantic: { field: "semantic_field", query: q }, }, }, }); res.status(200).json({ success: true, results: result.hits.hits, }); } catch (error) { console.error("Error performing search:", error); res.status(500).json({ success: false, results: null, error: error.message, }); } });

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

curl http://localhost:3000/search/semantic?q=Who%20got%20a%20pedicure?

Respuesta:

{ "success": true, "results": [ { "_index": "vet-visits", "_id": "-RY6RJYBLe2GoFQ6-9n9", "_score": 4.861466, "_source": { "owner_name": "Daniel Kim", "pet_name": "Mochi", "species": "Rabbit", "breed": "Mixed", "vaccination_history": [], "visit_details": "Nail trimming and general health check. No issues." } }, { "_index": "vet-visits", "_id": "8BY6RJYBLe2GoFQ6-9n9", "_score": 4.7152824, "_source": { "pet_name": "Buddy", "owner_name": "Alice Johnson", "species": "Dog", "visit_details": "Annual check-up and nail trimming. Healthy and active.", "breed": "Golden Retriever", "vaccination_history": [ "Rabies", "Parvovirus", "Distemper" ] } }, { "_index": "vet-visits", "_id": "9RY6RJYBLe2GoFQ6-9n9", "_score": 1.6717153, "_source": { "pet_name": "Rex", "owner_name": "Tomás Herrera", "species": "Dog", "visit_details": "Follow-up for previous leg strain, improving well.", "breed": "German Shepherd", "vaccination_history": [ "Rabies", "Parvovirus", "Leptospirosis" ] } }, { "_index": "vet-visits", "_id": "9xY6RJYBLe2GoFQ6-9n9", "_score": 1.5600781, "_source": { "pet_name": "Simba", "owner_name": "Leo Martínez", "species": "Cat", "visit_details": "Dental cleaning. Minor tartar buildup removed.", "breed": "Maine Coon", "vaccination_history": [ "Rabies", "Feline Panleukopenia" ] } }, { "_index": "vet-visits", "_id": "-BY6RJYBLe2GoFQ6-9n9", "_score": 1.2696637, "_source": { "pet_name": "Rocky", "owner_name": "Rachel Green", "species": "Dog", "visit_details": "Skin rash, antihistamines prescribed.", "breed": "Bulldog Mix", "vaccination_history": [ "Rabies", "Parvovirus" ] } } ] }

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

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

app.get("/search/hybrid", async (req, res) => { const { q } = req.query; const INDEX_NAME = "vet-visits"; try { const result = await esClient.search({ index: INDEX_NAME, body: { retriever: { rrf: { retrievers: [ { standard: { query: { bool: { must: { multi_match: { query: q, fields: ["owner_name", "pet_name", "visit_details"], }, }, }, }, }, }, { standard: { query: { bool: { must: { semantic: { field: "semantic_field", query: q, }, }, }, }, }, }, ], }, }, size: 5, }, }); res.status(200).json({ success: true, results: result.hits.hits, }); } catch (error) { console.error("Error performing search:", error); res.status(500).json({ success: false, results: null, error: error.message, }); } });

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

curl http://localhost:3000/search/hybrid?q=who%20got%20a%20pedicure%20or%20dental%20treatment

Respuesta:

{ "success": true, "results": [ { "_index": "vet-visits", "_id": "9xY6RJYBLe2GoFQ6-9n9", "_score": 0.032522473, "_source": { "pet_name": "Simba", "owner_name": "Leo Martínez", "species": "Cat", "visit_details": "Dental cleaning. Minor tartar buildup removed.", "breed": "Maine Coon", "vaccination_history": [ "Rabies", "Feline Panleukopenia" ] } }, { "_index": "vet-visits", "_id": "-RY6RJYBLe2GoFQ6-9n9", "_score": 0.016393442, "_source": { "pet_name": "Mochi", "owner_name": "Daniel Kim", "species": "Rabbit", "visit_details": "Nail trimming and general health check. No issues.", "breed": "Mixed", "vaccination_history": [] } }, { "_index": "vet-visits", "_id": "8BY6RJYBLe2GoFQ6-9n9", "_score": 0.015873017, "_source": { "pet_name": "Buddy", "owner_name": "Alice Johnson", "species": "Dog", "visit_details": "Annual check-up and nail trimming. Healthy and active.", "breed": "Golden Retriever", "vaccination_history": [ "Rabies", "Parvovirus", "Distemper" ] } }, { "_index": "vet-visits", "_id": "9RY6RJYBLe2GoFQ6-9n9", "_score": 0.015625, "_source": { "pet_name": "Rex", "owner_name": "Tomás Herrera", "species": "Dog", "visit_details": "Follow-up for previous leg strain, improving well.", "breed": "German Shepherd", "vaccination_history": [ "Rabies", "Parvovirus", "Leptospirosis" ] } }, { "_index": "vet-visits", "_id": "8xY6RJYBLe2GoFQ6-9n9", "_score": 0.015384615, "_source": { "pet_name": "Luna", "owner_name": "Jake Thompson", "species": "Dog", "visit_details": "Mild ear infection, cleaning and antibiotics given.", "breed": "Labrador Mix", "vaccination_history": [ "Rabies", "Bordetella" ] } } ] }

Conclusión

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

Uso de Ollama con la API de inferencia

Jeffrey Rengifo — Fri, 14 Feb 2025 00:00:00 GMT

En este artículo, aprenderemos cómo conectar modelos locales al modelo de inferencia de Elasticsearch usando Ollama y luego hacer preguntas a tus documentos usando Playground.

Elasticsearch permite a los usuarios conectarse a LLM empleando la API de Open Inference, compatible con proveedores como Amazon Bedrock, Cohere, Google AI, Azure AI Studio, HuggingFace, como servicio, entre otros.

Ollama es una herramienta que le permite descargar y ejecutar modelos LLM empleando su propia infraestructura (su máquina/servidor local). Aquí puedes encontrar una lista de los modelos disponibles que son compatibles con Ollama.

Ollama es una gran opción si quieres alojar y probar diferentes modelos de código abierto sin tener que preocuparte por las diferentes formas en que se podría tener que configurar cada uno de los modelos, o por cómo crear una API para acceder a las funciones del modelo, ya que Ollama se encarga de todo.

Dado que la API de Ollama es compatible con la API de OpenAI, podemos integrar fácilmente el modelo de inferencia y crear una aplicación RAG empleando Playground.

Prerrequisitos

Elasticsearch 8.17
Kibana 8.17
Python

Pasos

Configuración del servidor Ollama LLM

Vamos a configurar un servidor LLM para conectarlo a nuestra instancia de Playground usando Ollama. Necesitaremos:

Descargue y ejecute Ollama.
Use ngrok para acceder al servidor sitio web local que hospeda Ollama a través de Internet

Descarga y ejecuta Ollama

Para usar Ollama, primero debemos descargarlo. Ollama ofrece soporte para Linux, Windows y macOS, así que simplemente descargue la versión de Ollama compatible con su sistema operativo aquí. Una vez instalado Ollama, podemos elegir un modelo de esta lista de LLM compatibles. En este ejemplo, usaremos el modelo llama3.2, un modelo general multilingüe. En el proceso de configuración, habilitará la herramienta de línea de comandos para Ollama. Una vez descargado, puede ejecutar la siguiente línea:

ollama pull llama3.2

Lo que dará como resultado:

pulling manifest pulling dde5aa3fc5ff... 100% ▕█████████████████████████████████████████████████████████████████████████████████████████▏ 2.0 GB pulling 966de95ca8a6... 100% ▕█████████████████████████████████████████████████████████████████████████████████████████▏ 1.4 KB pulling fcc5a6bec9da... 100% ▕█████████████████████████████████████████████████████████████████████████████████████████▏ 7.7 KB pulling a70ff7e570d9... 100% ▕█████████████████████████████████████████████████████████████████████████████████████████▏ 6.0 KB pulling 56bb8bd477a5... 100% ▕█████████████████████████████████████████████████████████████████████████████████████████▏ 96 B pulling 34bb5ab01051... 100% ▕█████████████████████████████████████████████████████████████████████████████████████████▏ 561 B verifying sha256 digest writing manifest success

Una vez instalado, puede probarlo con este comando:

ollama run llama3.2

Hagamos una pregunta:

Con el modelo en ejecución, Ollama habilita una API que se ejecutaría de forma predeterminada en el puerto "11434". Hagamos una solicitud a esa API, siguiendo la documentación oficial:

curl http://localhost:11434/api/generate -d '{ "model": "llama3.2", "prompt": "What is the capital of France?" }'

Esta es la respuesta que obtuvimos:

{"model":"llama3.2","created_at":"2024-11-28T21:48:42.152817532Z","response":"The","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.251884485Z","response":" capital","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.347365913Z","response":" of","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.446837322Z","response":" France","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.542367394Z","response":" is","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.644580384Z","response":" Paris","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.739865362Z","response":".","done":false} {"model":"llama3.2","created_at":"2024-11-28T21:48:42.834347518Z","response":"","done":true,"done_reason":"stop","context":[128006,9125,128007,271,38766,1303,33025,2696,25,6790,220,2366,18,271,128009,128006,882,128007,271,3923,374,279,6864,315,9822,30,128009,128006,78191,128007,271,791,6864,315,9822,374,12366,13],"total_duration":6948567145,"load_duration":4386106503,"prompt_eval_count":32,"prompt_eval_duration":1872000000,"eval_count":8,"eval_duration":684000000}

Tenga en cuenta que la respuesta específica para este punto de conexión es una transmisión.

Exponer el punto de conexión a Internet mediante ngrok

Dado que nuestro endpoint funciona en un entorno local, no se puede acceder a él desde otro punto, como nuestra instancia de Elastic Cloud, a través de Internet. ngrok nos permite exponer un puerto que ofrece una IP pública. Cree una cuenta en ngrok y siga la guía de configuración oficial.

Una vez instalado y configurado el agente ngrok, podemos exponer el puerto que usa Ollama:

ngrok http 11434 --host-header="localhost:11434"

Nota: El encabezado --host-header="localhost:11434" garantiza que el encabezado "Host" de las solicitudes coincida con "localhost:11434"

La ejecución de este comando devolverá un vínculo público que funcionará siempre que ngrok y el servidor de Ollama se ejecuten localmente.

Session Status online Account xxxx@yourEmailProvider.com (Plan: Free) Version 3.18.4 Region United States (us) Latency 561ms Web Interface http://127.0.0.1:4040 Forwarding https://your-ngrok-url.ngrok-free.app -> http://localhost:11434 Connections ttl opn rt1 rt5 p50 p90 0 0 0.00 0.00 0.00 0.00 ```

En "Reenvío" podemos ver que ngrok generó una dirección URL. Almacénalo para más tarde.

Intentemos realizar una solicitud HTTP al punto de conexión de nuevo, ahora con la dirección URL generada por ngrok:

curl https://your-ngrok-endpoint.ngrok-free.app/api/generate -d '{ "model": "llama3.2", "prompt": "What is the capital of France?" }'

La respuesta debe ser similar a la anterior.

Creación de asignaciones

Punto final ELSER

Para este ejemplo, crearemos un punto final de inferencia mediante la API de inferencia de Elasticsearch. Además, usaremos ELSER para generar las incrustaciones.

PUT _inference/sparse_embedding/medicines-inference { "service": "elasticsearch", "service_settings": { "num_allocations": 1, "num_threads": 1, "model_id": ".elser_model_2_linux-x86_64" } }

Para este ejemplo, imaginemos que tiene una farmacia que vende dos tipos de medicamentos:

Medicamentos que requieren receta médica.
Medicamentos que NO requieren receta médica.

Esta información se incluiría en el campo de descripción de cada medicamento.

El LLM debe interpretar este campo, por lo que estas son las asignaciones de datos que usaremos:

PUT medicines { "mappings": { "properties": { "name": { "type": "text", "copy_to": "semantic_field" }, "semantic_field": { "type": "semantic_text", "inference_id": "medicines-inference" }, "text_description": { "type": "text", "copy_to": "semantic_field" } } } }

El campo text_description almacenará el texto sin formato de las descripciones, mientras que semantic_field, que es un tipo de campo semantic_text , almacenará las incrustaciones generadas por ELSER.

La propiedad copy_to copiará el contenido del nombre y la text_description de los campos en el campo semántico para que se generen las incrustaciones de esos campos.

Indexación de datos

Ahora, indexemos los datos usando la API de _bulk.

POST _bulk {"index":{"_index":"medicines"}} {"id":1,"name":"Paracetamol","text_description":"An analgesic and antipyretic that does NOT require a prescription."} {"index":{"_index":"medicines"}} {"id":2,"name":"Ibuprofen","text_description":"A nonsteroidal anti-inflammatory drug (NSAID) available WITHOUT a prescription."} {"index":{"_index":"medicines"}} {"id":3,"name":"Amoxicillin","text_description":"An antibiotic that requires a prescription."} {"index":{"_index":"medicines"}} {"id":4,"name":"Lorazepam","text_description":"An anxiolytic medication that strictly requires a prescription."} {"index":{"_index":"medicines"}} {"id":5,"name":"Omeprazole","text_description":"A medication for stomach acidity that does NOT require a prescription."} {"index":{"_index":"medicines"}} {"id":6,"name":"Insulin","text_description":"A hormone used in diabetes treatment that requires a prescription."} {"index":{"_index":"medicines"}} {"id":7,"name":"Cold Medicine","text_description":"A compound formula to relieve flu symptoms available WITHOUT a prescription."} {"index":{"_index":"medicines"}} {"id":8,"name":"Clonazepam","text_description":"An antiepileptic medication that requires a prescription."} {"index":{"_index":"medicines"}} {"id":9,"name":"Vitamin C","text_description":"A dietary supplement that does NOT require a prescription."} {"index":{"_index":"medicines"}} {"id":10,"name":"Metformin","text_description":"A medication used for type 2 diabetes that requires a prescription."}

Respuesta:

{ "errors": false, "took": 34732020848, "items": [ { "index": { "_index": "medicines", "_id": "mYoeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 0, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "mooeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 1, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "m4oeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 2, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "nIoeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 3, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "nYoeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 4, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "nooeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 5, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "n4oeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 6, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "oIoeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 7, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "oYoeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 8, "_primary_term": 1, "status": 201 } }, { "index": { "_index": "medicines", "_id": "oooeMpQBF7lnCNFTfdn2", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 2, "failed": 0 }, "_seq_no": 9, "_primary_term": 1, "status": 201 } } ] }

Hacer preguntas con Playground

Playground es una herramienta de Kibana que te permite crear rápidamente un sistema RAG empleando índices de Elasticsearch y un proveedor de LLM. Puedes leer este artículo para saber más al respecto.

Conectando el LLM local con Playground

Primero debemos crear un conector que use la dirección URL pública que acabamos de crear. En Kibana, ve a Buscar>Playground y luego haz clic en "Conectar a un LLM".

Esta acción revelará un menú en el lado izquierdo de la interfaz de Kibana. Allí, haga clic en "OpenAI".

Ahora podemos comenzar a configurar el conector OpenAI.

Vaya a "Configuración del conector" y para el proveedor de OpenAI, seleccione "Otro (servicio compatible con OpenAI)":

Ahora, configuremos los otros campos. Para este ejemplo, llamaremos a nuestro modelo "medicines-llm". En el campo URL, usa la que genera ngrok (/v1/chat/completions). En el campo "Modelo predeterminado", selecciona "llama3.2". No usaremos una clave API, así que simplemente pon cualquier texto aleatorio para continuar:

Haga clic en "Almacenar" y agregue los medicamentos índice haciendo clic en "Agregar fuentes de datos":

¡Bien! Ahora tenemos acceso a Playground usando el LLM que estamos ejecutando localmente como motor RAG.

Antes de probarlo, agreguemos instrucciones más específicas al agente y aumentemos el número de documentos enviados al modelo a 10, para que la respuesta tenga la mayor cantidad de documentos posibles disponibles. El campo de contexto será semantic_field, que incluye el nombre y la descripción de los medicamentos, gracias a la propiedad copy_to.

Ahora hagamos la pregunta: ¿Puedo comprar clonazepam sin receta? y vea qué sucede:

Como era de esperar, obtuvimos la respuesta correcta.

Pasos siguientes

¡El siguiente paso es crear su propia aplicación! Playground proporciona un script de código en Python que puede ejecutar en su máquina y personalizarlo para satisfacer sus necesidades. Por ejemplo, colocándolo detrás de un servidor FastAPI para crear un chatbot de medicamentos de control de calidad consumido por su interfaz de usuario.

Puedes encontrar este código haciendo clic en el botón Ver código en la sección superior derecha de Playground:

Y usa los puntos finales y las claves API para generar la variable de entorno ES_API_KEY requerida en el código.

Para este ejemplo en individuo, el código es el siguiente:

## Install the required packages ## pip install -qU elasticsearch openai import os from elasticsearch import Elasticsearch from openai import OpenAI es_client = Elasticsearch( "https://your-deployment.us-central1.gcp.cloud.es.io:443", api_key=os.environ["ES_API_KEY"] ) openai_client = OpenAI( api_key=os.environ["OPENAI_API_KEY"], ) index_source_fields = { "medicines": [ "semantic_field" ] } def get_elasticsearch_results(): es_query = { "retriever": { "standard": { "query": { "nested": { "path": "semantic_field.inference.chunks", "query": { "sparse_vector": { "inference_id": "medicines-inference", "field": "semantic_field.inference.chunks.embeddings", "query": query } }, "inner_hits": { "size": 2, "name": "medicines.semantic_field", "_source": [ "semantic_field.inference.chunks.text" ] } } } } }, "size": 3 } result = es_client.search(index="medicines", body=es_query) return result["hits"]["hits"] def create_openai_prompt(results): context = "" for hit in results: inner_hit_path = f"{hit['_index']}.{index_source_fields.get(hit['_index'])[0]}" ## For semantic_text matches, we need to extract the text from the inner_hits if 'inner_hits' in hit and inner_hit_path in hit['inner_hits']: context += '\n --- \n'.join(inner_hit['_source']['text'] for inner_hit in hit['inner_hits'][inner_hit_path]['hits']['hits']) else: source_field = index_source_fields.get(hit["_index"])[0] hit_context = hit["_source"][source_field] context += f"{hit_context}\n" prompt = f""" Instructions: - You are an assistant specializing in answering questions about the sale of medicines. - Answer questions truthfully and factually using only the context presented. - If you don't know the answer, just say that you don't know, don't make up an answer. - You must always cite the document where the answer was extracted using inline academic citation style [], using the position. - Use markdown format for code examples. - You are correct, factual, precise, and reliable. Context: {context} """ return prompt def generate_openai_completion(user_prompt, question): response = openai_client.chat.completions.create( model="gpt-3.5-turbo", messages=[ {"role": "system", "content": user_prompt}, {"role": "user", "content": question}, ] ) return response.choices[0].message.content if __name__ == "__main__": question = "my question" elasticsearch_results = get_elasticsearch_results() context_prompt = create_openai_prompt(elasticsearch_results) openai_completion = generate_openai_completion(context_prompt, question) print(openai_completion)

Para que funcione con Ollama, debe cambiar el cliente OpenAI para conectarse al servidor Ollama en lugar del servidor OpenAI. Puede encontrar la lista completa de ejemplos de OpenAI y puntos finales compatibles aquí.

openai_client = OpenAI( # you can use http://localhost:11434/v1/ if running this code locally. base_url='https://your-ngrok-url.ngrok-free.app/v1/', # required but ignored api_key='ollama', )

Y también cambie el modelo a llama3.2 al llamar al método de finalización:

def generate_openai_completion(user_prompt, question): response = openai_client.chat.completions.create( model="llama3.2", messages=[ {"role": "system", "content": user_prompt}, {"role": "user", "content": question}, ] ) return response.choices[0].message.content

Agreguemos nuestra pregunta: ¿Puedo comprar Clonazepam sin receta? A la consulta de Elasticsearch:

def get_elasticsearch_results(): es_query = { "retriever": { "standard": { "query": { "nested": { "path": "semantic_field.inference.chunks", "query": { "sparse_vector": { "inference_id": "medicines-inference", "field": "semantic_field.inference.chunks.embeddings", "query": "Can I buy Clonazepam without a prescription?" } }, "inner_hits": { "size": 2, "name": "medicines.semantic_field", "_source": [ "semantic_field.inference.chunks.text" ] } } } } }, "size": 3 } result = es_client.search(index="medicines", body=es_query) return result["hits"]["hits"]

Y también a la llamada de finalización con un par de impresiones, para que podamos confirmar que estamos enviando los resultados de Elasticsearch como parte del contexto de la pregunta:

if __name__ == "__main__": question = "Can I buy Clonazepam without a prescription?" elasticsearch_results = get_elasticsearch_results() context_prompt = create_openai_prompt(elasticsearch_results) print("========== Context Prompt START ==========") print(context_prompt) print("========== Context Prompt END ==========") print("========== Ollama Completion START ==========") openai_completion = generate_openai_completion(context_prompt, question) print(openai_completion) print("========== Ollama Completion END ==========")

Ahora ejecutemos el comando

pip install -qU elasticsearch openai

python main.py

Deberías ver algo como esto:

========== Context Prompt START ========== Instructions: - You are an assistant specializing in answering questions about the sale of medicines. - Answer questions truthfully and factually using only the context presented. - If you don't know the answer, just say that you don't know, don't make up an answer. - You must always cite the document where the answer was extracted using inline academic citation style [], using the position. - Use markdown format for code examples. - You are correct, factual, precise, and reliable. Context: Clonazepam --- An antiepileptic medication that requires a prescription.A nonsteroidal anti-inflammatory drug (NSAID) available WITHOUT a prescription. --- IbuprofenAn anxiolytic medication that strictly requires a prescription. --- Lorazepam ========== Context Prompt END ========== ========== Ollama Completion START ========== No, you cannot buy Clonazepam over-the-counter (OTC) without a prescription [1]. It is classified as a controlled substance in the United States due to its potential for dependence and abuse. Therefore, it can only be obtained from a licensed healthcare provider who will issue a prescription for this medication. ========== Ollama Completion END ==========

Conclusión

En este artículo, podemos ver el poder y la versatilidad de herramientas como Ollama cuando las usamos junto con la API de inferencia de Elasticsearch y Playground.

Luego de algunos pasos simples, teníamos una aplicación RAG en funcionamiento con un chat que usaba un LLM que se ejecutaba en nuestra propia infraestructura sin costo alguno. Esto también nos permite tener más control sobre los recursos y la información sensible, además de darnos acceso a una variedad de modelos para diferentes tareas.