Jeffrey Rengifo - Elasticsearch Labs

Como medir e melhorar o recall das buscas no Elasticsearch: de 0,43 a 0,75 com a busca híbrida

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

A busca lexical usando o algoritmo de classificação BM25 é barata, rápida e muito eficaz para uma ampla gama de consultas. Mas ela tem um ponto cego: consultas que não compartilham tokens com seus documentos. Neste artigo, você vai medir exatamente onde a BM25 falha. Usaremos a API de avaliação de classificação do Elasticsearch (rank_eval) e preencheremos essa lacuna adicionando Jina AI embeddings via Elastic Inference Service (EIS). Você verá a pontuação de recall variar de 0.43 para 0.75 e saberá o porquê.

O que é recall?

O recall mede em uma escala de 0 a 1 quantos dos documentos que seus usuários realmente querem aparecem em algum lugar dos seus resultados de busca. Se uma consulta aparecer em três produtos e sua busca devolver apenas dois deles entre os 10 primeiros, recall@10 = 0.67 nessa consulta. É uma métrica baseada em conjuntos: ela não se importa com a posição dos documentos relevantes dentro desses k resultados. Um documento relevante na posição 10 conta o mesmo que um na posição 1. Ter um recall alto significa que você não está perdendo resultados relevantes.

O diagrama mostra dois conjuntos: todos os documentos relevantes (à esquerda) e o que o BM25 realmente recuperou (top 10, à direita). Apenas a interseção conta para a recuperação, prod_1 e prod_2 foram encontrados, enquanto prod_3, prod_4 e prod_6 foram completamente perdidos. Resultado: Recall@10 = 2/5 = 0.40.

Pré-requisitos

Vamos direto ao ponto para entender melhor como o recall funciona. Esta demonstração usa Python. Você pode acompanhar no notebook complementar (notebook.ipynb), onde cada bloco de código é uma célula pronta para ser executada.

O código fornecido utiliza o seguinte:

Elasticsearch 9.3+
Python 3.10+

pip install elasticsearch pandas plotly python-dotenv

Um arquivo .env com suas credenciais do Elasticsearch

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

O conjunto de dados

Usaremos um catálogo de produtos com 1.000 produtos, abrangendo categorias como calçados, eletrônicos, ferramentas e outros.

Cada documento tem quatro campos:

Campo

Tipo

`title`

texto

`description`

texto

`marca`

palavra-chave

`category`

palavra-chave

O conjunto de dados é carregado a partir de dataset.csv.

O poder e os limites da busca lexical

BM25 é o algoritmo padrão de ranqueamento no Elasticsearch e na maioria dos mecanismos de busca. Ele classifica os documentos de acordo com a frequência com que seus termos de consulta aparecem neles, ajustados ao tamanho do documento e à frequência desses termos em todo o índice. Você tem analisadores na parte superior: normalização de letras minúsculas, stemming e retirada de stopwords. Uma busca por "tênis de corrida" retornará resultados como "Tênis de corrida" e provavelmente também "correr".

Isso funciona bem para uma grande classe de consultas:

"tênis de corrida" faz a correspondência imediata dos produtos com esses tokens exatos no título.
"alto-falante Bluetooth" destaca produtos de áudio portáteis porque os tokens aparecem literalmente.

Os resultados são determinísticos e explicáveis: um documento tem classificação alta porque os termos de consulta aparecem nele. Depurar a relevância é simples.

Onde ocorre a falha

Agora, vamos testar essas consultas no mesmo catálogo:

"rotina de cuidados com a pele": a palavra "rotina" não aparece em nenhum título de produto. O BM25 pode corresponder parcialmente com "cuidados com a pele", mas séruns faciais, óleos corporais e hidratantes são descritos usando termos como "vitamina C", "retinol" ou "iluminador", nenhum dos quais se sobrepõe à consulta. Produtos que formam uma rotina completa de cuidados com a pele ficam espalhados pelo índice, sem nenhum token compartilhado para ancorá-los.

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

"acessórios de viagem para pets": é um agrupamento de casos de uso, não uma categoria de produto. Um sling para cães, uma cadeirinha para pets e uma caixa de viagem são todos relevantes, mas as descrições falam sobre portabilidade, segurança e conforto, em vez de "acessórios de viagem". O BM25 corresponde amplamente a palavra "pet", mas não tem sinal para distinguir produtos específicos para viagens do restante do catálogo de pets.

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

Esse é um problema de recall. Os documentos relevantes existem no seu índice. O BM25 simplesmente não os encontra porque as palavras do usuário e as do documento não coincidem o suficiente.

Adicionar sinônimos ajuda em casos conhecidos. Mas não dá para enumerar todas as formas como o usuário pode expressar uma intenção. É aí que entram os vetores.

Por que medir o recall

Antes de corrigir um problema, você precisa quantificá-lo.

Recall@k mede quantos documentos que seus usuários realmente desejam aparecem nos resultados de busca. Formalmente:

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

Precision@k mede os k principais resultados e quantos são realmente relevantes:

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

Alta precisão mostra que os resultados que você retorna são bons. No comércio eletrônico, perder um produto relevante (baixo recall) geralmente é pior do que mostrar um resultado um pouco imperfeito (menor precisão), porque o produto oculto é venda perdida.

A API rank_eval do Elasticsearch permite medir os dois de forma sistemática. Você fornece uma lista de consultas, cada uma com um conjunto de documentos avaliados, e o Elasticsearch calcula as métricas para você em todas elas.

Configuração da avaliação

A API rank_eval precisa de um conjunto de dados de avaliações: um mapeamento das consultas para os documentos relevantes para cada um, junto com uma nota de relevância (0 = não relevante, 1 = relevante, 2 = altamente relevante).

No bloco de notas, esta é a lista de julgamentos:

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"}, ]

A combinação é intencional: q1 é uma consulta que o BM25 lida bem (tokens exatos nos títulos dos produtos), enquanto q2, q3 e q4 são consultas orientadas à intenção, nas quais a intenção do usuário é expressa como um conceito, não como palavras-chave específicas de produto.

Medindo o recall de base do BM25

Primeiro, configure o cliente do Elasticsearch e indexe os dados de texto bruto:

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"

Agora, crie a solicitação rank_eval para o BM25. Cada solicitação na lista combina uma consulta com as classificações correspondentes:

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, em todas as quatro consultas, o BM25 encontra apenas 43% dos documentos que deveria. A deficiência se concentra nas consultas baseadas na intenção: "rotina de cuidados com a pele" não inclui séruns faciais e óleos corporais, pois "rotina" nunca aparece nos títulos dos produtos. Já "acessórios de viagem para pets" retorna produtos para pets fora do tópico, enquanto não inclui transportadoras e caixas de transporte descritas em termos de portabilidade e segurança, em vez de "acessórios de viagem".

Esta é a nossa linha de base. Agora, temos um número a superar.

Adicionando busca vetorial com embeddings do Jina

Vector search codifica documentos e consultas como vetores de alta dimensão, tipo de vetor composto por centenas ou milhares de valores numéricos, cada um codificando um recurso específico dos dados que representa. Documentos com significado semelhante acabam próximos uns dos outros no espaço vetorial, mesmo que não compartilhem palavras. "Equipamento de ginástica" e "conjunto de halteres" ficam próximos porque os conceitos estão relacionados. Escolhi o Elasticsearch como meu banco de dados vetorial porque ele faz busca híbrida, oferecendo compreensão semântica e precisão de palavras-chave prontas para uso.

EIS inclui suporte pronto para uso de modelos via API de inferência.

Passo 1: usando embeddings Jina v5 como endpoint de inferência

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

Se seu cluster tem recursos de GPU (disponíveis no Elastic Cloud e Elasticsearch 9.3+), as incorporações são geradas na GPU, o que é bem mais rápido do que a inferência da CPU e elimina o tradeoff de desempenho que historicamente encarecia os vetores em larga escala.

Por que as incorporações Jina especificamente? jina-embeddings-v5-text é um modelo multilíngue (mais de 119 idiomas) com uma janela de contexto de 32 mil tokens e suporte para adaptadores de Adaptação de Baixa Ordem (LoRA) específicos para cada tarefa. Ele funciona bem para descrições curtas de produtos, prontamente utilizável. Saiba mais sobre o modelo jina-embeddings-v5-text aqui.

Passo 2: criar o índice com um 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}")

O tipo de campo semantic_text é essencial aqui. É uma abstração de nível mais alto sobre dense_vector: você aponta para um endpoint de inferência, e o Elasticsearch cuida de gerar automaticamente os embeddings.

A propriedade copy_to em title e description significa que o conteúdo de ambos os campos flui para semantic_field para incorporação, de modo que um único vetor captura a representação completa do produto.

Passo 3: indexar os produtos

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)

No momento do índice, o Elasticsearch chama o endpoint de inferência para cada documento e armazena a incorporação resultante em semantic_field. Sem código extra do seu lado.

Busca híbrida: combinando BM25 e vetores com RRF

Adicionar vetores melhora a recuperação, mas usar vetores sozinhos pode prejudicar a precisão em consultas de correspondência exata; "tênis de corrida" ainda deve priorizar correspondências exatas. A busca híbrida mantém o componente léxico especificamente para preservar essa precisão.

A busca híbrida com Fusão de Classificação Recíproca (RRF) mantém o melhor dos dois mundos:

O BM25 lida com consultas exatas e quase exatas com alta precisão.
A busca semântica processa consultas baseadas em intenção e multilíngues com alta precisão.
O RRF combina as duas listas classificadas em uma única classificação.

A fórmula RRF atribui a cada documento uma pontuação baseada em sua classificação em cada lista de resultados:

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

Um documento bem classificado em ambas as listas recebe uma pontuação combinada maior. O rank_constant controla quanto peso documentos de menor classificação recebem.

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

O Hybrid melhora substancialmente em relação ao BM25 (0.43) e preserva a precisão para consultas de correspondência exata como "tênis de corrida".

Resultados: Antes e depois

Eis a comparação completa entre as três abordagens:

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 (Léxico)

0,43

Híbrido (BM25 + Vetores)

0,75

Analisando por consulta:

Conclusão

Ao longo deste artigo, vimos que a busca léxica do BM25 é confiável quando os usuários digitam consultas exatas, mas perde a capacidade de recuperação quando buscam por intenção em vez de palavras-chave. Usando rank_eval, estabelecemos uma linha base reprodutível para medir essa lacuna com números reais. A partir daí, adicionamos um campo semantic_text alimentado por embeddings Jina e rodamos a avaliação novamente. O resultado: a buscar híbrida melhorou a capacidade de recuperação de 0.43 para 0.75 enquanto preservava a precisão nas consultas de correspondência exata, embora a margem real dependa da sua mistura de consultas.

O padrão se estende além deste exemplo: colete julgamentos das consultas reais de seus usuários, execute rank_eval como linha de base, adicione semantic_text e meça novamente. Você saberá exatamente o que melhorou e em quanto.

Próximas etapas

Aprofunde-se no recall e na busca vetorial: quantização de busca vetorial e recall, de Jeff Vestal
Adicione o reranking para melhorar ainda mais a precisão nos resultados principais
Consulte a documentação de busca híbrida do Elasticsearch
Leia mais sobre a rank_eval API

Criando um servidor MCP do Elasticsearch com TypeScript

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

Ao trabalhar com grandes bases de conhecimento no Elasticsearch, encontrar informações é apenas metade da batalha. Engenheiros precisam sintetizar resultados de múltiplos documentos, gerar resumos e rastrear respostas até as fontes. Para isso, o Protocolo de Contexto do Modelo (MCP) oferece uma maneira padronizada de conectar o Elasticsearch a aplicativos baseados em grandes modelos de linguagem (LLM). Embora a Elastic ofereça soluções oficiais, como o Elastic Agent Builder (que inclui um endpoint MCP entre os recursos), a criação de um servidor MCP personalizado oferece controle total sobre a lógica de busca, a formatação dos resultados e como o conteúdo recuperado é passado para um LLM para síntese, resumos e citações.

Neste artigo, exploraremos os benefícios de criar um servidor MCP do Elasticsearch personalizado e mostraremos como criar um servidor em TypeScript que conecte o Elasticsearch a aplicativos com LLM.

Por que criar um servidor MCP do Elasticsearch personalizado?

A Elastic oferece algumas alternativas para servidores MCP:

Se você precisar de mais controle sobre como o servidor MCP interage com o Elasticsearch, a criação do seu próprio servidor personalizado oferece a flexibilidade de adaptá-lo exatamente às suas necessidades. Por exemplo, o endpoint MCP do Agent Builder é limitado a consultas em Elasticsearch Query Language (ES|QL), enquanto um servidor personalizado permite usar o Query DSL completo. Você também tem controle sobre como os resultados são formatados antes de serem passados para o LLM e pode integrar etapas adicionais de processamento, como o resumo com tecnologia OpenAI que implementaremos neste tutorial.

Ao final deste artigo, você terá um servidor MCP no TypeScript que busca informações armazenadas em um índice do Elasticsearch, resume essas informações e fornece citações. Usaremos o Elasticsearch para recuperação, o modelo gpt-4o-mini da OpenAI para resumir e gerar citações, e o Claude Desktop como cliente MCP e UI para receber consultas dos usuários e dar respostas. O resultado é um assistente de conhecimento interno que ajuda os engenheiros a entender e sintetizar as práticas recomendadas nos documentos técnicos de sua organização.

Pré-requisitos:

Node.js 20 +
Elasticsearch
Chave de API da OpenAI
Claude Desktop

O que é MCP?

O MCP é um padrão aberto, criado pela Anthropic, que oferece conexões seguras e bidirecionais entre LLMs e sistemas externos, como o Elasticsearch. Você pode ler mais sobre a situação atual do MCP neste artigo.

O cenário de MCP está em constante evolução, com servidores disponíveis para uma ampla gama de casos de uso. Além disso, é fácil criar seu próprio servidor MCP personalizado, como mostraremos neste artigo.

Clientes do MCP

Há uma longa lista de clientes MCP disponíveis, cada um com as próprias características e limitações. Por simplicidade e popularidade, usaremos o Claude Desktop como nosso cliente MCP. Ele servirá como interface de chat na qual os usuários poderão fazer perguntas em linguagem natural e que invocará automaticamente as ferramentas expostas pelo nosso servidor MCP para buscar documentos e gerar resumos.

Criando um servidor MCP do Elasticsearch

Usando o TypeScript SDK, podemos criar um servidor que entende como consultar nossos dados do Elasticsearch com base em uma entrada de consulta do usuário.

Aqui estão os passos deste artigo para integrar o servidor MCP do Elasticsearch com o cliente Claude Desktop:

Configure o servidor MCP para o Elasticsearch

Para começar, vamos iniciar uma aplicação de nó:

npm init -y

Isso criará um arquivo package.json e, com ele, poderemos começar a instalar as dependências necessárias para essa aplicação.

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

@elastic/elasticsearch nos dará acesso à biblioteca Elasticsearch Node.js.
@modelcontextprotocol/sdk fornece as ferramentas de núcleo para criar e gerenciar um servidor MCP, registrar ferramentas e lidar com a comunicação com clientes MCP.
openai permite a interação com modelos OpenAI para gerar resumos ou respostas em linguagem natural.
zodajuda a definir e validar esquemas estruturados para dados de entrada e saída em cada ferramenta.

ts-node, @types/node, e typescript serão usados durante o desenvolvimento para digitar o código e compilar os scripts.

Configurar o conjunto de dados

Para fornecer os dados que o Claude Desktop pode consultar usando nosso servidor MCP, usaremos um conjunto de dados fictício de base de conhecimento interna. Veja como será um documento desse conjunto de dados:

{ "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 ingerir os dados, preparamos um script que cria um índice no Elasticsearch e carrega o conjunto de dados nele. Você pode encontrá-lo aqui.

Servidor MCP

Crie um arquivo chamado index.ts e adicione o seguinte código para importar as dependências e lidar com as variáveis de ambiente:

// 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";

Além disso, vamos inicializar os clientes para lidar com as chamadas do Elasticsearch e do OpenAI:

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

Para tornar nossa implementação mais robusta e garantir entrada e saída estruturadas, definiremos esquemas usando zod. Isso nos permite validar dados em tempo de execução, detectar erros com antecedência e facilitar o processamento de forma programática das respostas da ferramenta:

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;

Saiba mais sobre saídas estruturadas aqui.

Agora vamos inicializar o 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", });

Definição das ferramentas MCP

Com tudo configurado, podemos começar a escrever as ferramentas que serão expostas pelo nosso servidor MCP. Esse servidor expõe duas ferramentas:

search_docs: Busca por documentos no Elasticsearch usando busca de texto completo.
summarize_and_cite: Resume e sintetiza informações de documentos previamente recuperados para responder a uma pergunta do usuário. Essa ferramenta também adiciona citações que referenciam os documentos fonte.

Juntas, essas ferramentas formam um fluxo de trabalho simples de "recuperar e resumir", em que uma ferramenta busca documentos relevantes e a outra usa esses documentos para gerar uma resposta resumida e citada.

Formato de resposta da ferramenta

Cada ferramenta pode aceitar parâmetros de entrada arbitrários, mas deve responder com a seguinte estrutura:

Conteúdo: esta é a resposta da ferramenta em um formato não estruturado. Este campo geralmente é usado para retornar texto, imagens, áudio, links ou embeddings. Para esta aplicação, ele será usado para retornar texto formatado com as informações geradas pelas ferramentas.
structuredContent: Esse é um retorno opcional usado para fornecer os resultados de cada ferramenta em um formato estruturado. É útil para fins programáticos. Embora não seja usado neste servidor MCP, pode ser útil caso você queira desenvolver outras ferramentas ou processar os resultados programaticamente.

Com essa estrutura em mente, vamos nos aprofundar em cada ferramenta em detalhes.

Ferramenta de Busca de Documentos

Esta ferramenta realiza uma busca de texto completo no índice do Elasticsearch para recuperar os documentos mais relevantes com base na consulta do usuário. Ele destaca correspondências-chave e oferece uma visão geral rápida com pontuações de relevância.

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 ter uma tolerância variável de erros de digitação com base no comprimento do token que está sendo analisado. Também definimos title^2 para aumentar a pontuação dos documentos onde a correspondência ocorre no campo de título.

Ferramenta summarize_and_cite

Esta ferramenta gera um resumo baseado em documentos recuperados na busca anterior. Usa o modelo gpt-4o-mini da OpenAI para sintetizar as informações mais relevantes e responder à pergunta do usuário, fornecendo respostas derivadas diretamente dos resultados da busca. Além do resumo, também retorna metadados de citação para os documentos de origem usados.

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, }; } } );

Por fim, precisamos iniciar o servidor usando stdio. Isso significa que o cliente MCP se comunicará com nosso servidor lendo e escrevendo nos fluxos padrão de entrada e saída. Stdio é a opção de transporte mais simples e funciona bem para servidores MCP locais lançados como subprocessos pelo cliente. Adicione o seguinte código ao final do arquivo:

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

Agora compile o projeto usando o seguinte comando:

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

Isso criará uma pasta dist e, dentro dela, um arquivo index.js.

Carregue o servidor MCP no Claude Desktop

Siga este guia para configurar o servidor MCP com o Claude Desktop. No arquivo de configuração Claude, precisamos definir os seguintes 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" } } } }

O valor args deve apontar para o arquivo compilado na pasta dist. Você também precisa definir as variáveis de ambiente no arquivo de configuração com exatamente os mesmos nomes definidos no código.

Faça o teste

Antes de executar cada ferramenta, clique em Busca e Ferramentas para garantir que as ferramentas estejam ativadas. Aqui você também pode ativar ou desativar cada uma delas:

Por fim, vamos testar o servidor MCP no chat do Claude Desktop e começar a fazer perguntas:

Para a pergunta “Buscar documentos sobre métodos de autenticação e controle de acesso por função”, a ferramenta search_docs é executada e retorna os seguintes 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.

A resposta é: "Ótimo! Encontrei 5 documentos relevantes sobre métodos de autenticação e controle de acesso por função. Eis o que foi encontrado:"

A chamada de ferramenta retorna os documentos fonte como parte da carga útil de resposta, que são posteriormente usados para gerar citações.

Também é possível encadear várias ferramentas em uma única interação. Neste caso, o Claude Desktop analisa a pergunta do usuário e determina que precisa primeiro chamar search_docs para recuperar documentos relevantes e depois passar esses resultados para summarize_and_cite para gerar a resposta final, tudo isso sem exigir prompts separados do usuário:

Neste caso, para a consulta “Quais são as principais recomendações para melhorar a autenticação e o controle de acesso em nossos sistemas? Inclua referências.”, obtivemos os seguintes 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.

Como na etapa anterior, podemos ver a resposta de cada ferramenta para esta pergunta:

Nota: Se aparecer um submenu perguntando se você aprova o uso de cada ferramenta, selecione Permitir sempre ou Permitir uma vez.

Conclusão

Os servidores MCP representam um passo significativo rumo à padronização das ferramentas LLM para aplicações locais e remotas. Embora a compatibilidade total ainda esteja em andamento, estamos avançando nessa direção.

Neste artigo, aprendemos como criar um servidor MCP personalizado em TypeScript que conecta o Elasticsearch a aplicações baseadas em LLM. Nosso servidor expõe duas ferramentas: search_docs para recuperar documentos relevantes usando Query DSL; e summarize_and_cite para gerar resumos com citações via modelos OpenAI e Claude Desktop como UI.

O futuro da compatibilidade entre diferentes provedores de clientes e servidores parece promissor. As próximas etapas incluem adicionar mais funcionalidades e flexibilidade ao seu agente. Existe um artigo prático sobre como parametrizar suas consultas usando modelos de pesquisa para ter precisão e flexibilidade.

Usando a API de Inferência Elasticsearch junto com modelos de Hugging Face

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

Em atualizações recentes, o Elasticsearch introduziu uma integração nativa para conectar a modelos hospedados no Hugging Face Inference Service. Neste post, vamos explorar como configurar essa integração e realizar inferência por meio de chamadas simples de API usando um grande modelo de linguagem (LLM). Vamos usar SmolLM3-3B, um modelo leve de uso geral com bom equilíbrio entre uso de recursos e qualidade da resposta.

Pré-requisitos

Elasticsearch 9.3 ou Elastic Cloud Serverless: você pode criar uma implantação na nuvem seguindo essas instruções, ou você pode usar o start-local quickstart.
Python 3.12: baixe o Python aqui.
Hugging Face Token de acesso.

Chat completions usando um endpoint de inferência do Hugging Face

Primeiro, vamos construir um exemplo prático que conecta o Elasticsearch a um endpoint de inferência Hugging Face para gerar recomendações baseadas em IA a partir de uma coleção de artigos de blog. Para a base de conhecimento do app, usaremos um conjunto de dados de artigos de blog da empresa, que contém informações valiosas, mas frequentemente difíceis de navegar.

Com este endpoint, a busca semântica recupera os artigos mais relevantes para uma consulta específica, e um Hugging Face LLM gera recomendações curtas e contextuais com base nesses resultados.

Vamos dar uma olhada em uma visão geral do fluxo de informações que vamos criar:

Neste artigo, testaremos a capacidade do SmolLM3-3B decombinar seu tamanho compacto com fortes capacidades de raciocínio multíngue e chamada de ferramentas. Com base em uma consulta de busca, enviaremos todo o conteúdo correspondente (em inglês e espanhol) para o LLM para gerar uma lista de artigos recomendados com uma descrição personalizada com base na consulta de busca e nos resultados.

Veja como poderia ser a UI de um site de artigos com um sistema de geração de recomendações por IA.

Você pode encontrar a implementação completa desta aplicação no notebook vinculado.

Configuração de endpoints de inferência do Elasticsearch

Para usar o endpoint de inferência do Hugging Face no Elasticsearch, precisamos de dois elementos importantes: uma chave de API do Hugging Face e uma URL de endpoint do Hugging Face em execução. Ela deverá ficar assim:

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

O endpoint de inferência Hugging Face no Elasticsearch permite diferentes tipos de tarefas: text_embedding, completion, chat_completion, e rerank. Neste post do blog, usamos chat_completion porque precisamos que o modelo gere recomendações conversacionais baseadas nos resultados de busca e em um prompt do sistema. Esse endpoint nos permite realizar preenchimentos de chat diretamente do Elasticsearch de forma simples usando a API do Elasticsearch:

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

Isso servirá como o núcleo da aplicação, recebendo o prompt e os resultados de busca que passarão pelo modelo. Com a teoria explicada, vamos começar a implementar a aplicação.

Configurando o endpoint de inferência no Hugging Face

Para implantar o modelo Hugging Face, vamos usar implantações Hugging Face One-Click, um serviço fácil e rápido para implantar endpoints de modelos. Lembre-se de que este é um serviço pago, e seu uso pode incorrer em custos adicionais. Esta etapa criará a instância do modelo que será usada para gerar as recomendações dos artigos.

Você pode escolher um modelo do catálogo de um clique.

Vamos escolher o modelo SmolLM3-3B :

A partir daqui, pegue o URL do endpoint do Hugging Face:

Como mencionado na documentação de endpoints de inferência Hugging Face do Elasticsearch, a geração de texto requer um modelo compatível com a API OpenAI. Por esse motivo, precisamos anexar o subcaminho /v1/chat/completions à URL do endpoint Hugging Face. O resultado final ficará assim:

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

Com isso pronto, podemos começar a programar em um notebook Python.

Gerando a Chave API do Hugging Face

Crie uma conta Hugging Face e obtenha um token de API seguindo estas instruções. Você pode escolher entre três tipos de token: detalhado (recomendado para produção, pois fornece acesso apenas a recursos específicos); de leitura (para acesso somente leitura); ou de gravação (para acesso de leitura e gravação). Para este tutorial, um token de leitura é suficiente, já que só precisamos chamar o endpoint de inferência. Guarde esta chave para o próximo passo.

Configurando o endpoint de inferência do Elasticsearch

Primeiro, vamos declarar um cliente Elasticsearch Python:

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"] )

Em seguida, vamos criar um endpoint de inferência no Elasticsearch que use o modelo Hugging Face. Esse endpoint nos permitirá gerar respostas com base nos posts do blog e no prompt passado para o 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"], }, }, )

Conjunto de dados

O conjunto de dados contém os posts do blog que serão consultados, representando um conjunto de conteúdo multilíngue usado em todo o fluxo de trabalho:

// 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." }

Mapeamento do Elasticsearch

Com o conjunto de dados definido, precisamos criar um esquema de dados que se ajuste adequadamente à estrutura do post do blog. Os seguintes mapeamentos de índice serão usados para armazenar os dados no 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)

Aqui, podemos ver com mais clareza como os dados são estruturados. Usaremos busca semântica para recuperar resultados baseados em linguagem natural, junto com a propriedade copy_to para copiar o conteúdo do campo para o campo semantic_text. Além disso, o campo title contém dois subcampos: o subcampo original armazena o título em inglês ou espanhol, dependendo do idioma original do artigo; e o subcampo translated_title está presente apenas para artigos em espanhol e contém a tradução para o inglês do título original.

Ingestão de dados

O seguinte trecho de código ingere o conjunto de dados de postagens do blog no Elasticsearch usando a bulk API:

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)}")

Agora que os artigos já estão no Elasticsearch, precisamos criar uma função capaz de buscar no 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 []

Precisamos também de uma função que chame o endpoint de inferência. Neste caso, chamaremos o endpoint usando chat_completiontipo de tarefa para obter respostas de streaming:

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)}"

Agora podemos escrever uma função que chama a função de busca semântica, junto com o endpoint de inferência chat_completions e o endpoint de recomendações, para gerar os dados que serão alocados nos cartões:

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

Finalmente, precisamos extrair as informações e formatá-las para serem impressas:

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 + "┘")

Vamos testar isso fazendo uma pergunta sobre as postagens do blog de segurança:

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)

Aqui podemos ver os cartões no console gerados pelo fluxo de trabalho:

Você pode ver os resultados completos, incluindo todos os acertos e a resposta do LLM, neste arquivo.

Estamos pedindo artigos relacionados a: "Segurança e vulnerabilidades." Esta pergunta é usada como consulta de busca nos documentos armazenados no Elasticsearch. Os resultados recuperados são então passados para o modelo, que gera recomendações com base em seu conteúdo. Como podemos ver, o modelo fez um ótimo trabalho criando textos curtos envolventes que podem motivar o leitor a clicar.

Conclusão

Este exemplo mostra como Elasticsearch e Hugging Face podem ser combinados para criar um sistema centralizado rápido e eficiente para aplicações de IA. Essa abordagem reduz o esforço manual e oferece flexibilidade, graças ao extenso catálogo de modelos da Hugging Face. O uso do SmolLM3-3B, em particular, demonstra como modelos compactos e multilíngues ainda podem fornecer raciocínio significativo e geração de conteúdo quando combinados com busca semântica. Juntas, essas ferramentas oferecem uma base escalável e eficaz para construir análises inteligentes de conteúdo e aplicações multilíngues.

Crie um fluxo de trabalho de busca por IA financeira usando LangGraph.js e Elasticsearch

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

A criação de aplicativos de busca com IA geralmente envolve a coordenação de múltiplas tarefas, recuperação e extração de dados em um fluxo de trabalho integrado. O LangGraph simplifica esse processo ao permitir que os desenvolvedores orquestrem agentes de IA usando uma estrutura baseada em nós. Neste artigo, vamos construir uma solução financeira usando LangGraph.js

O que é LangGraph

LangGraph é um framework para construir agentes de IA e orquestrá-los em um fluxo de trabalho para criar aplicações assistidas por IA. O LangGraph possui uma arquitetura de nós onde podemos declarar funções que representam tarefas e atribuí-las como nós do fluxo de trabalho. O resultado de múltiplos nós interagindo será um gráfico. O LangGraph faz parte do ecossistema mais amplo LangChain, que oferece ferramentas para construir sistemas de IA modulares e componíveis.

Para entender melhor por que o LangGraph é útil, vamos resolver uma situação problemática usando-o.

Visão geral da solução

Em uma empresa de capital de risco, os investidores têm acesso a um grande banco de dados com muitas opções de filtragem, mas quando se deseja combinar critérios, o processo se torna difícil e lento. Isso pode fazer com que algumas startups relevantes não sejam encontradas para investimento. Isso resulta em gastar muitas horas tentando identificar os melhores candidatos, ou até mesmo em perder oportunidades.

Com o LangGraph e o Elasticsearch, podemos realizar buscar filtradas utilizando linguagem natural, eliminando a necessidade de os usuários construírem manualmente solicitações complexas com dezenas de filtros. Para torná-lo mais flexível, o fluxo de trabalho decide automaticamente com base na entrada do usuário entre dois tipos de consultas:

Consultas focadas em investimento: essas consultas visam aspectos financeiros e de financiamento de startups, como rodadas de financiamento, avaliação ou receita. Exemplo: "Encontre startups com financiamento Série A ou Série B entre US$ 8 milhões e US$ 25 milhões e receita mensal acima de US$ 500 mil."
Consultas focadas no mercado: essas consultas concentram-se em verticais da indústria, mercados geográficos ou modelos de negócios, ajudando a identificar oportunidades em setores ou regiões específicos. Exemplo: “Encontre startups de fintech e saúde em São Francisco, Nova York ou Boston.”

Para manter a robustez das consultas, faremos com que o LLM crie modelos de busca em vez de consultas DSL completas. Assim, você sempre recebe a consulta que quer, e o LLM só precisa preencher as lacunas e não carregar a responsabilidade de construir a consulta que você precisa toda vez.

O que você precisa para começar

APIKey do Elasticsearch
APIKey do OpenAPI
Node 18 ou mais recente

Instruções passo a passo

Nesta seção, vamos ver como o app ficará. Para isso, usaremos o TypeScript, um superconjunto do JavaScript que adiciona tipos estáticos para tornar o código mais confiável, fácil de manter e mais seguro, detectando erros precocemente e, ao mesmo tempo, permanecendo totalmente compatível com o JavaScript existente.

O fluxo dos nós terá a seguinte aparência:

A imagem acima é gerada pelo LangGraph e representa o fluxo de trabalho que define a ordem de execução e a lógica condicional entre nós:

decideStrategy: utiliza um LLM para analisar a consulta do usuário e decidir entre duas estratégias de busca especializadas: focada em investimento ou focada no mercado.
prepareInvestSearch: extrai valores de filtro da consulta e constrói um modelo pré-definido enfatizando parâmetros financeiros e relacionados ao financiamento.
prepareMarketSearch: também extrai valores de filtro, mas constrói parâmetros dinamicamente enfatizando o mercado, o setor e o contexto geográfico.
executeSearch: envia a consulta construída para o Elasticsearch usando um modelo de busca e recupera os documentos correspondentes de inicialização.
visualizeResults: formata os resultados finais em um resumo claro e legível que mostra atributos-chave da startup, como financiamento, setor e receita.

Esse fluxo inclui uma ramificação condicional, funcionando como uma instrução “if”, que determina se deve usar o caminho de busca de investimentos ou de mercado com base na entrada do usuário. Essa lógica de decisão, conduzida pelo LLM, torna o fluxo de trabalho adaptável e sensível ao contexto, um mecanismo que exploraremos com mais detalhes nas próximas seções.

Estado do LangGraph

Antes de ver cada nó individualmente, precisamos entender como os nós se comunicam e compartilham dados. Para isso, o LangGraph nos permite definir o estado do fluxo de trabalho. Isso define o estado compartilhado que será passado entre os nós.

O estado funciona como um container compartilhado que armazena dados intermediários ao longo do fluxo de trabalho: começa com a consulta em linguagem natural do usuário, depois mantém a estratégia de busca selecionada, os parâmetros preparados para o Elasticsearch, os resultados de busca recuperados e, finalmente, a saída formatada.

Essa estrutura permite que cada nó leia e atualize o estado, garantindo um fluxo consistente de informações desde a entrada do usuário até a visualização 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 o aplicativo

Todo o código desta seção pode ser encontrado no repositório elasticsearch-labs.

Abra um terminal na pasta em que o app estará localizado e inicialize um app Node.js com o comando:

npm init -y

Agora podemos instalar as dependências necessárias para este projeto:

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

@elastic/elasticsearch: Nos ajuda a lidar com requisições do Elasticsearch, como ingestão e recuperação de dados.
@langchain/langgraph: dependência de JS para fornecer todas as ferramentas LangGraph.
@langchain/openaiCliente OpenAI LLM para LangChain.
@langchain/núcleo: fornece os blocos de construção fundamentais para apps LangChain, incluindo modelos de prompt.
dotenv: Dependência necessária para usar variáveis de ambiente em JavaScript.
zod: Dependência para digitar dados.

@types/node tsx typescript nos permite escrever e executar o código TypeScript.

Agora, crie os seguintes arquivos:

elasticsearchSetup.ts: Criará os mapeamentos de índice, carregará o conjunto de dados de um arquivo JSON e fará a ingestão dos dados no Elasticsearch.
main.ts: incluirá o aplicativo LangGraph.
.env: arquivo para armazenar as variáveis de ambiente

No arquivo .env, vamos adicionar as seguintes variáveis de ambiente:

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

O APIKey da OpenAPI não será usado diretamente no código; em vez disso, será usado internamente pela biblioteca @langchain/openai.

Toda a lógica relacionada à criação de mapeamentos, modelos de busca e ingestão de conjuntos de dados pode ser encontrada no arquivo elasticsearchSetup.ts. Nos próximos passos, vamos focar no arquivo main.ts . Além disso, você pode verificar o conjunto de dados para entender melhor como os dados aparecem no dataset.json.

Aplicativo LangGraph

No arquivo main.ts, vamos importar algumas dependências necessárias para consolidar a aplicação LangGraph. Neste arquivo, você também deve incluir as funções de nós e a declaração de estado. A declaração do gráfico será feita em um método main nos próximos passos. O arquivo elasticsearchSetup.ts conterá ajudantes Elasticsearch que vamos usar dentro dos nós em etapas futuras.

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 mencionado anteriormente, o cliente LLM será usado para gerar os parâmetros de busca do Elasticsearch com base na pergunta do usuário.

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); } }

O método acima gera a imagem do gráfico em formato PNG e usa a API Mermaid.INK nos bastidores. Isso é útil se você quiser ver como os nós do app interagem entre si com uma visualização estilizada.

Nós do LangGraph

Agora vamos analisar cada nó em detalhes:

nó decideSearchStrategy

O node decideSearchStrategy analisa a entrada do usuário e determina se realiza uma buscar focada em investimento ou no mercado. Ele utiliza um LLM com um esquema de saída estruturado (definido com Zod) para classificar o tipo de consulta. Antes de tomar a decisão, o sistema recupera os filtros disponíveis do índice por meio de uma agregação, garantindo que o modelo tenha um contexto atualizado sobre setores, locais e dados de financiamento.

Para extrair os valores possíveis dos filtros e enviá-los ao LLM, vamos usar uma consulta de agregação para recuperá-los diretamente do índice do Elasticsearch. Essa lógica é alocada em um método chamado 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 {}; } }

Com a consulta de agregação acima, temos os seguintes 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 } }

Veja todos os resultados aqui.

Para ambas as estratégias, usaremos busca híbrida para detectar tanto a parte estruturada da pergunta (filtros) quanto as partes mais subjetivas (semântica). Aqui está um exemplo de ambas as consultas usando templates de busca:

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 } } }`, }, });

Veja as consultas detalhadas no arquivo elasticsearchSetup.ts . No nó a seguir, será decidido qual das duas consultas será usada:

// 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", }; } }

nós prepareInvestmentSearch e prepareMarketSearch

Ambos os nós usam uma função auxiliar compartilhada, extractFilterValues, que utiliza o LLM para identificar filtros relevantes mencionados na entrada do usuário, como setor, localização, estágio de financiamento, modelo de negócios, etc. Estamos usando este esquema para construir nosso modelo de busca.

// 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); }

Dependendo da intenção detectada, o fluxo de trabalho seleciona um de dois caminhos:

prepareInvestmentSearch: desenvolve parâmetros de busca orientados financeiramente, incluindo estágio de financiamento, valor do investimento, investidor e informações de renovação. Você pode encontrar o modelo completo de consulta no arquivo 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: cria parâmetros orientados pelo mercado, focados em setores, geografias e modelos de negócios. Veja a consulta completa no arquivo 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 {}; } }

nó executeSearch

Este nó pega os parâmetros de busca gerados do estado e os envia primeiro para o Elasticsearch, usando a API _render para visualizar a consulta para fins de depuração, e então envia uma solicitação para buscar os 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: [] }; } }

nó visualizeResults

Por fim, este nó exibe os resultados do 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, }; }

Programaticamente, o gráfico completo tem a seguinte aparência:

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 você pode ver, temos uma aresta condicional onde o app decide qual "caminho" ou nó será executado em seguida. Esse recurso é útil quando fluxos de trabalho precisam de lógica de ramificação, como escolher entre várias ferramentas ou incluir uma etapa com uma pessoa no ciclo.

Com os recursos do núcleo do LangGraph entendidos, podemos configurar o aplicativo onde o código será executado:

Junte tudo em um método main; aqui declaramos o gráfico com todos os elementos sob a variável fluxo de trabalho:

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); }

A variável de consulta simula a entrada do usuário inserida em uma barra de busca hipotética:

A partir da frase em linguagem natural "Encontre startups com financiamento Série A ou Série B entre US$ 8M–US$ 25M e receita mensal acima de US$ 500K", todos os filtros serão extraídos.

Finalmente, invoque o 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 a entrada enviada, a aplicação escolhe o caminho focado no investimento e, como resultado, podemos ver a consulta Elasticsearch gerada pelo fluxo de trabalho LangGraph, que extrai os valores e intervalos a partir da entrada do usuário. Também podemos ver a consulta enviada para o Elasticsearch com os valores extraídos aplicados e, finalmente, os resultados formatados pelo node visualizeResults com os resultados.

Agora vamos testar o nó focado no mercado usando a consulta "Encontre startups de fintech e saúde em São Francisco, Nova York ou 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.

Aprendizados

Durante o processo de escrita, aprendi:

Devemos mostrar ao LLM os valores exatos dos filtros; caso contrário, dependemos de o usuário digitar os valores exatos das coisas. Para baixa cardinalidade, essa abordagem é válida; mas, quando a cardinalidade é alta, precisamos de algum mecanismo para filtrar os resultados.
Usar templates para busca torna os resultados muito mais consistentes do que deixar o LLM escrever a consulta Elasticsearch, e também é mais rápido
Arestas condicionais são um mecanismo poderoso para construir aplicações com múltiplas variantes e caminhos ramificados.
A saída estruturada é extremamente útil ao gerar informações com LLMs porque impõe respostas previsíveis e seguras para tipos. Isso melhora a confiabilidade e reduz as interpretações errôneas imediatas.

Combinar busca semântica e estruturada por meio da recuperação híbrida produz resultados melhores e mais relevantes, equilibrando precisão e compreensão do contexto.

Conclusão

Neste exemplo, combinamos LangGraph.js com o Elasticsearch para criar um fluxo de trabalho dinâmico capaz de interpretar consultas em linguagem natural e decidir entre estratégias de busca voltadas para finanças ou para o mercado. Essa abordagem reduz a complexidade de elaborar consultas manuais, ao mesmo tempo em que melhora a flexibilidade e a precisão para analistas de capital de risco.

Painéis de controle com inteligência artificial: da visão ao Kibana

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

O Kibana Lens torna o arrastar e soltar de dashboards muito simples, mas quando você precisa de dezenas de painéis, o número de cliques aumenta. E se você pudesse esboçar um painel de controle, tirar uma captura de tela e deixar um profissional de Direito concluir todo o processo para você?

Neste artigo, vamos fazer isso acontecer. Criaremos um aplicativo que captura uma imagem de um painel, analisa nossos mapeamentos e, em seguida, gera um painel sem que precisemos usar o Kibana!

Passos:

Contexto e fluxo de trabalho do aplicativo

A primeira ideia que me veio à mente foi deixar o LLM gerar todo o formato NDJSON dos objetos salvos pelo Kibana e, em seguida, importá-los para o Kibana.

Experimentamos alguns modelos:

Gemini 2.5 pro
GPT o3 / o4-mini-high / 4.1
Soneto 4 de Claude
Grok 3
Deepseek (Deepthink R1)

E para as sugestões, começamos com algo tão simples quanto:

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

Apesar de termos analisado poucos exemplos e explicações detalhadas sobre como construir cada visualização, não tivemos sucesso. Se você estiver interessado nessa experiência, pode encontrar detalhes aqui.

O resultado com essa abordagem foi a visualização dessas mensagens ao tentar carregar os arquivos produzidos pelo LLM no Kibana:

Isso significa que o JSON gerado é inválido ou está mal formatado. Os problemas mais comuns foram o LLM produzir NDJSON incompleto, apresentar parâmetros incorretos ou retornar JSON comum em vez de NDJSON, independentemente de quanto nos esforçássemos para forçar o contrário.

Inspirados por este artigo – onde os modelos de pesquisa funcionaram melhor do que o método freestyle do LLM – decidimos fornecer modelos ao LLM em vez de solicitar a geração do arquivo NDJSON completo e, em seguida, usar os parâmetros fornecidos pelo LLM no código para criar as visualizações adequadas. Essa abordagem não decepcionou, além de ser previsível e extensível, já que agora o código realiza o trabalho pesado, e não o LLM.

O fluxo de trabalho da aplicação será o seguinte:

Para simplificar, omitiremos parte do código, mas você pode encontrar o código funcional da aplicação completa neste notebook.

Pré-requisitos

Antes de começar o desenvolvimento, você precisará do seguinte:

Python 3.8 ou superior
Um ambiente Python Venv
Uma instância do Elasticsearch em execução, juntamente com seu endpoint e chave de API.
Uma chave de API da OpenAI armazenada na variável de ambiente com o nome OPENAI_API_KEY:

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

Preparar dados

Para os dados, vamos manter a simplicidade e usar os logs de amostra da Elastic. Você pode aprender como importar esses dados para o seu cluster aqui.

Cada documento inclui detalhes sobre o host que enviou as solicitações ao aplicativo, juntamente com informações sobre a própria solicitação e seu status de resposta. Segue abaixo um exemplo de documento:

{ "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 }

Agora, vamos obter os mapeamentos do índice que acabamos de carregar, 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 passar os mapeamentos junto com a imagem que carregaremos posteriormente.

Configuração LLM

Vamos configurar o LLM para usar saída estruturada para receber uma imagem como entrada e obter um JSON com as informações necessárias para passar à nossa função e gerar os objetos JSON.

Instalamos as dependências:

pip install elasticsearch pydantic langchain langchain-openai -q

O Elasticsearch nos ajudará a recuperar os mapeamentos de índice. Pydantic permite definir esquemas em Python para depois solicitar que o LLM os siga, e LangChain é a estrutura que facilita a chamada de LLMs e ferramentas de IA.

Criaremos um esquema Pydantic para definir a saída desejada do LLM. O que precisamos saber da imagem é o tipo de gráfico, campo, título da visualização e título do painel:

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 a entrada de imagem, enviaremos um painel que acabei de desenhar:

Agora declaramos a chamada do modelo LLM e o carregamento da imagem. Essa função receberá os mapeamentos do índice do Elasticsearch e uma imagem do painel que desejamos gerar.

Com with_structured_output podemos usar nosso esquema Pydantic Dashboard como o objeto de resposta que o LLM produzirá. Com o Pydantic, podemos definir modelos de dados com validação, o que garante que a saída do modelo linear linear (LLM) corresponda à estrutura esperada.

Para converter a imagem para base64 e enviá-la como entrada, você pode usar um conversor online ou fazer isso por meio de 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)}")

O LLM já possui contexto sobre os dashboards do Kibana, então não precisamos explicar tudo no prompt, apenas alguns detalhes para garantir que ele não se esqueça de que está trabalhando com o Elasticsearch e o Kibana.

Vamos analisar a pergunta:

Seção

Razão

Você é especialista em analisar dashboards do Kibana a partir de imagens para a versão 9.0.0 do Kibana.

Ao reforçar isso no Elasticsearch e na versão do Elasticsearch, reduzimos a probabilidade de o LLM gerar parâmetros antigos/inválidos.

Você receberá uma imagem do painel de controle e um mapeamento do índice do Elasticsearch.

Explicamos que a imagem se refere a painéis de controle para evitar quaisquer interpretações errôneas por parte do LLM.

Abaixo estão os mapeamentos de índice para o índice no qual o painel se baseia. Use-os para ajudá-lo a entender os dados e os campos disponíveis. Mapeamentos de índice: {index_mappings}

É crucial fornecer os mapeamentos para que o LLM possa selecionar campos válidos dinamicamente. Caso contrário, poderíamos codificar os mapeamentos diretamente aqui, o que é muito rígido, ou confiar na imagem que contém os nomes de campo corretos, o que não é confiável.

Inclua apenas os campos relevantes para cada visualização, com base no que está visível na imagem.

Precisávamos adicionar esse reforço porque, às vezes, o programa tenta adicionar campos que não são relevantes para a imagem.

Isso retornará um objeto com uma matriz de visualizações para exibir:

"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"")" ]

Processando a resposta do LLM

NósCriamos um painel de exemplo 2x2 e o exportamos em JSON usando a API "Obter um painel". Em seguida, armazenamos os painéis como modelos de visualização (pizza, barra, métrica), onde podemos substituir alguns parâmetros para criar novas visualizações com campos diferentes, dependendo da pergunta.

Você pode ver os arquivos JSON do modelo aqui. Observe como alteramos os valores dos objetos que queremos substituir posteriormente por {variable_name}

Com as informações fornecidas pelo LLM, podemos decidir qual modelo usar e quais valores substituir.

fill_template_with_analysis receberão os parâmetros para um único painel, incluindo o modelo JSON da visualização, um título, um campo e as coordenadas da visualização na grade.

Em seguida, substituirá os valores do modelo e retornará a visualização 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, teremos coordenadas estáticas que atribuiremos aos painéis que o LLM decidir criar e produziremos um painel de controle em grade 2x2, como na imagem acima.

# 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

Dependendo do tipo de visualização decidido pelo LLM, escolheremos um modelo de arquivo JSON e substituiremos as informações relevantes usando fill_template_with_analysis , depois adicionaremos o novo painel a uma matriz que usaremos posteriormente para criar o painel de controle.

Quando o painel estiver pronto, usaremos a API Criar um painel para enviar o novo arquivo JSON ao Kibana e gerar o painel:

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 executar o script e gerar o painel de controle, execute o seguinte comando no console:

python .py

O resultado final será semelhante a este:

Conclusão

Os profissionais com formação em Letras demonstram suas fortes habilidades visuais ao realizar tarefas de conversão de texto em código ou ao transformar imagens em código. A API de dashboards também permite transformar arquivos JSON em dashboards e, com um LLM e algum código, podemos transformar imagens em um dashboard do Kibana.

O próximo passo é melhorar a flexibilidade dos elementos visuais do painel de controle, utilizando diferentes configurações de grade, tamanhos e posições do painel. Além disso, oferecer suporte a visualizações e tipos de visualização mais complexos seria uma adição útil a este aplicativo.

Elasticsearch em JavaScript da maneira correta, parte II

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

Esta é a segunda parte da nossa série sobre Elasticsearch em JavaScript. Na primeira parte, aprendemos como configurar nosso ambiente corretamente, configurar o cliente Node.js, indexar dados e realizar buscas. Nesta segunda parte, aprenderemos como implementar as melhores práticas de produção e executar o cliente Elasticsearch Node.js em ambientes Serverless.

Analisaremos:

Você pode conferir o código-fonte com os exemplos aqui.

Melhores práticas de produção

Tratamento de erros no Elasticsearch

Uma funcionalidade útil do cliente Elasticsearch em Node.js é que ele expõe objetos para os possíveis erros no Elasticsearch, permitindo que você os valide e trate de diferentes maneiras.

Para ver todos, execute o seguinte comando:

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

Vamos voltar ao exemplo de pesquisa e tratar de alguns dos possíveis erros:

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 em particular, ocorrerá quando a resposta for 4xx ou 5xx, o que significa que a solicitação está incorreta ou o servidor não está disponível.

Podemos testar esse tipo de erro gerando consultas incorretas, como tentar fazer uma consulta de termo em um campo do tipo texto:

Erro padrão:

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

Erro personalizado:

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

Também podemos capturar e lidar com cada tipo de erro de uma determinada maneira. Por exemplo, podemos adicionar lógica de repetição em um 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.", }); } } });

Teste

Os testes são essenciais para garantir a estabilidade do aplicativo. Para testar o código de forma isolada do Elasticsearch, podemos usar a biblioteca elasticsearch-js-mock ao criar nosso cluster.

Esta biblioteca permite instanciar um cliente muito semelhante ao real, mas que responderá à nossa configuração substituindo apenas a camada HTTP do cliente por uma camada simulada, mantendo o restante igual ao original.

Vamos instalar a biblioteca mocks e o AVA para testes automatizados.

npm install @elastic/elasticsearch-mock

npm install --save-dev ava

Vamos configurar o arquivo package.json para executar os testes. Certifique-se de que esteja assim:

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

Vamos agora criar um arquivo test.js e instalar nosso cliente de simulação:

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() })

Agora, adicione uma simulação para pesquisa 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.", }, }, ], }, }; } ); }

Agora podemos criar um teste para o nosso código, garantindo que a parte do Elasticsearch sempre retorne os mesmos 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" ); } });

Vamos executar os testes.

npm run test

Pronto! A partir de agora, podemos testar nosso aplicativo focando 100% no código e não em fatores externos.

Ambientes sem servidor

Como executar o cliente no Elastic Serverless

Já abordamos a execução do Elasticsearch na nuvem ou em infraestrutura local; no entanto, o cliente Node.js também oferece suporte a conexões com o Elastic Cloud Serverless.

O Elastic Cloud Serverless permite que você crie um projeto onde não precisa se preocupar com a infraestrutura, já que a Elastic cuida disso internamente, e você só precisa se preocupar com os dados que deseja indexar e por quanto tempo deseja ter acesso a eles.

Do ponto de vista da utilização, o Serverless separa o processamento do armazenamento, proporcionando recursos de escalonamento automático tanto para pesquisa quanto para indexação. Isso permite que você cultive apenas os recursos de que realmente precisa.

O cliente realiza as seguintes adaptações para se conectar ao Serverless:

Desativa a detecção de pacotes e ignora quaisquer opções relacionadas a ela.
Ignora todos os nós passados na configuração, exceto o primeiro, e ignora quaisquer opções de filtragem e seleção de nós.
Habilita a compressão e o método `TLSv1_2_method` (igual à configuração para o Elastic Cloud).
Adiciona um cabeçalho HTTP `elastic-api-version` a todas as requisições.
Utiliza `CloudConnectionPool` por padrão em vez de `WeightedConnectionPool`.
Desativa os cabeçalhos `content-type` e `accept` fornecidos pelo fornecedor, em favor dos tipos MIME padrão.

Para conectar seu projeto sem servidor, você precisa usar o parâmetro serverMode: serverless.

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

Como executar o cliente em um ambiente de função como serviço

No exemplo, usamos um servidor Node.js, mas você também pode se conectar usando um ambiente de função como serviço com funções 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 }

Outro exemplo é conectar-se a serviços como o Vercel, que também é serverless. Você pode conferir este exemplo completo de como fazer isso, mas a parte mais relevante do endpoint de pesquisa se parece com isto:

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 na pasta /api e é executado a partir do lado do servidor, de forma que o cliente só tenha controle sobre o parâmetro “texto” que corresponde ao termo de pesquisa.

A implicação de usar a função como serviço é que, ao contrário de um servidor que funciona 24 horas por dia, 7 dias por semana, as funções apenas ativam a máquina que executa a função e, assim que ela termina, a máquina entra em modo de repouso para consumir menos recursos.

Essa configuração pode ser conveniente se o aplicativo não receber muitas solicitações; caso contrário, os custos podem ser elevados. Você também precisa levar em consideração o ciclo de vida das funções e os tempos de execução (que, em alguns casos, podem ser de apenas alguns segundos).

Conclusão

Neste artigo, aprendemos como lidar com erros, o que é crucial em ambientes de produção. Também abordamos os testes da nossa aplicação enquanto simulávamos o serviço Elasticsearch, o que proporciona testes confiáveis independentemente do estado do cluster e nos permite focar no nosso código.

Por fim, demonstramos como criar uma infraestrutura totalmente sem servidor, provisionando tanto o Elastic Cloud Serverless quanto um aplicativo Vercel.

Elasticsearch em JavaScript da maneira correta, parte I

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

Este é o primeiro artigo de uma série que aborda como usar o Elasticsearch com JavaScript. Nesta série, você aprenderá o básico de como usar o Elasticsearch em um ambiente JavaScript e revisará os recursos mais relevantes e as melhores práticas para criar um aplicativo de busca. Ao final, você saberá tudo o que precisa para executar o Elasticsearch usando JavaScript.

Nesta primeira parte, vamos analisar:

Você pode conferir o código-fonte com os exemplos aqui.

O que é o cliente Elasticsearch para Node.js?

O cliente Elasticsearch para Node.js é uma biblioteca JavaScript que converte as chamadas HTTP REST da API do Elasticsearch em código JavaScript. Isso facilita o manuseio e permite o uso de ferramentas auxiliares que simplificam tarefas como a indexação de documentos em lotes.

Ambiente

Frontend, backend ou serverless?

Para criar nosso aplicativo de busca usando o cliente JavaScript, precisamos de pelo menos dois componentes: um cluster Elasticsearch e um ambiente de execução JavaScript para executar o cliente.

O cliente JavaScript é compatível com todas as soluções Elasticsearch (Cloud, on-premise e Serverless), e não há grandes diferenças entre elas, já que o cliente lida com todas as variações internamente, então você não precisa se preocupar com qual usar.

O ambiente de execução JavaScript, no entanto, deve ser executado a partir do servidor e não diretamente do navegador.

Isso ocorre porque, ao acessar o Elasticsearch pelo navegador, o usuário pode obter informações confidenciais, como a chave da API do cluster, o host ou a própria consulta. A Elasticsearch recomenda nunca expor o cluster diretamente à internet e usar uma camada intermediária que abstraia todas essas informações, de forma que o usuário possa ver apenas os parâmetros. Você pode ler mais sobre este tópico aqui.

Sugerimos usar um esquema como este:

Nesse caso, o cliente envia apenas os termos de pesquisa e uma chave de autenticação para o seu servidor, enquanto o seu servidor mantém o controle total da consulta e da comunicação com o Elasticsearch.

Conectando o cliente

Comece criando uma chave de API seguindo estes passos.

Seguindo o exemplo anterior, criaremos um servidor Express simples e nos conectaremos a ele usando um cliente de um servidor Node.js.

Vamos inicializar o projeto com o NPM e instalar o cliente Elasticsearch e o Express. Esta última é uma biblioteca para iniciar servidores em Node.js. Usando o Express, podemos interagir com nosso backend via HTTP.

Vamos inicializar o projeto:

npm init -y

Instalar dependências:

npm install @elastic/elasticsearch express split2 dotenv

Deixe-me explicar melhor:

@elastic/elasticsearch: É o cliente oficial do Node.js.
Express: Isso nos permitirá criar um servidor Node.js leve para expor o Elasticsearch.
split2: Divide linhas de texto em um fluxo. Útil para processar nossos arquivos ndjson linha por linha.
dotenv: Permite gerenciar variáveis de ambiente usando um arquivo .env. arquivo

Crie um arquivo .env Abra o arquivo na raiz do projeto e adicione as seguintes linhas:

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

Dessa forma, podemos importar essas variáveis usando o pacote dotenv .

Crie um arquivo server.js :

Este código configura um servidor Express.js básico que escuta na porta 3000 e se conecta a um cluster Elasticsearch usando uma chave de API para autenticação. Inclui um endpoint /ping que, quando acessado por meio de uma solicitação GET, consulta o cluster Elasticsearch para obter informações básicas usando o método .info() do cliente Elasticsearch.

Se a consulta for bem-sucedida, ela retorna as informações do cluster em formato JSON; caso contrário, retorna uma mensagem de erro. O servidor também utiliza o middleware body-parser para lidar com os corpos das requisições JSON.

Execute o arquivo para iniciar o servidor:

node server.js

A resposta deve ser semelhante a esta:

Server running on port 3000

E agora, vamos consultar o endpoint /ping para verificar o status do nosso cluster 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" } }

Documentos de indexação

Uma vez conectados, podemos indexar documentos usando mapeamentos como semantic_text para pesquisa semântica e text para consultas de texto completo. Com esses dois tipos de campo, também podemos fazer buscas híbridas.

Criaremos um novo arquivo load.js para gerar os mapeamentos e carregar os documentos.

Cliente Elasticsearch

Primeiro precisamos instanciar e autenticar o 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 }, });

Mapeamentos semânticos

Criaremos um índice com dados sobre um hospital veterinário. Armazenaremos as informações do dono, do animal de estimação e os detalhes da visita.

Os dados nos quais desejamos realizar uma busca de texto completo, como nomes e descrições, serão armazenados como texto. Os dados das categorias, como a espécie ou raça do animal, serão armazenados como palavras-chave.

Além disso, copiaremos os valores de todos os campos para um campo semantic_text para podermos executar também uma pesquisa semântica nessas informações.

Auxiliar em massa

Outra vantagem do cliente é que podemos usar a função auxiliar de indexação em lotes. A função auxiliar de processamento em lote nos permite lidar facilmente com aspectos como concorrência, novas tentativas e o que fazer com cada documento que passa pela função, seja com sucesso ou com falha.

Uma característica interessante dessa ferramenta auxiliar é a possibilidade de trabalhar com fluxos de dados. Essa função permite enviar um arquivo linha por linha, em vez de armazenar o arquivo inteiro na memória e enviá-lo para o Elasticsearch de uma só vez.

Para enviar os dados para o Elasticsearch, crie um arquivo chamado data.ndjson na raiz do projeto e adicione as informações abaixo (alternativamente, você pode baixar o arquivo com o conjunto de dados aqui):

{"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 o split2 para transmitir as linhas do arquivo enquanto o auxiliar de processamento em lote as envia para o 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);

O código acima lê um arquivo .ndjson. indexa cada objeto JSON em um índice Elasticsearch especificado usando o método helpers.bulk . Ele transmite o arquivo usando createReadStream e split2, configura metadados de indexação para cada documento e registra quaisquer documentos que não puderem ser processados. Após a conclusão, registra o número de itens indexados com sucesso.

Alternativamente à função indexData , você pode fazer o upload do arquivo diretamente pela interface do usuário usando o Kibana e usar a interface de upload de arquivos de dados.

Executamos o arquivo para enviar os documentos para o nosso cluster 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

Buscando dados no Elasticsearch

Voltando ao nosso arquivo server.js , criaremos diferentes endpoints para realizar buscas lexicais, semânticas ou híbridas.

Em resumo, esses tipos de pesquisa não são mutuamente exclusivos, mas dependerão do tipo de pergunta que você precisa responder.

Tipo de consulta

Caso de uso

Exemplo de pergunta

Consulta lexical

As palavras ou radicais presentes na pergunta provavelmente aparecerão nos documentos indexados. Similaridade entre tokens na pergunta e nos documentos.

Estou procurando uma camiseta esportiva azul.

Consulta semântica

É improvável que as palavras da pergunta apareçam nos documentos. Similaridade conceitual entre a pergunta e os documentos.

Estou procurando roupas para clima frio.

Busca híbrida

A questão contém componentes lexicais e/ou semânticos. Similaridade semântica e de tokens entre a pergunta e os documentos.

Estou procurando um vestido tamanho P para um casamento na praia.

As partes lexicais da pergunta provavelmente fazem parte de títulos e descrições, ou nomes de categorias, enquanto as partes semânticas são conceitos relacionados a esses campos. "Azul" provavelmente será o nome de uma categoria ou parte de uma descrição, e "casamento na praia" provavelmente não será, mas pode estar semanticamente relacionado a roupas de linho.

Consulta lexical (/search/lexic?q=)

A busca lexical, também chamada de busca de texto completo, significa pesquisar com base na similaridade de tokens; ou seja, após uma análise, os documentos que incluem os tokens da busca serão retornados.

Você pode conferir nosso tutorial prático de busca lexical aqui.

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, }); } });

Testamos com: corte de unhas

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

Responder:

{ "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=)

A busca semântica, diferentemente da busca lexical, encontra resultados que são semelhantes ao significado dos termos de busca por meio de busca vetorial.

Você pode conferir nosso tutorial prático de busca semântica aqui.

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, }); } });

Fizemos o teste com a seguinte pergunta: Quem fez pedicure?

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

Responder:

{ "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=)

A busca híbrida permite combinar a busca semântica e a busca lexical, obtendo assim o melhor dos dois mundos: a precisão da busca por token, juntamente com a proximidade de significado da busca 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, }); } });

Fizemos o teste com a pergunta: “Quem fez pedicure ou tratamento dentário?”

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

Resposta.

{ "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" ] } } ] }

Conclusão

Nesta primeira parte da nossa série, explicamos como configurar nosso ambiente e criar um servidor com diferentes endpoints de pesquisa para consultar os documentos do Elasticsearch, seguindo as melhores práticas de cliente/servidor. Confira a segunda parte da nossa série, na qual você aprenderá as melhores práticas de produção e como executar o cliente Elasticsearch Node.js em ambientes Serverless.

Usando Ollama com a API de Inferência

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

Neste artigo, aprenderemos como conectar modelos locais ao modelo de inferência do Elasticsearch usando o Ollama e, em seguida, fazer perguntas aos seus documentos usando o Playground.

O Elasticsearch permite que os usuários se conectem a LLMs usando a Open Inference API, oferecendo suporte a provedores como Amazon Bedrock, Cohere, Google AI, Azure AI Studio, HuggingFace - como serviço, entre outros.

Ollama é uma ferramenta que permite baixar e executar modelos LLM usando sua própria infraestrutura (sua máquina/servidor local). Aqui você encontra uma lista dos modelos disponíveis que são compatíveis com o Ollama.

O Ollama é uma ótima opção se você deseja hospedar e testar diferentes modelos de código aberto sem ter que se preocupar com as diferentes maneiras como cada um dos modelos pode ter que ser configurado ou sobre como criar uma API para acessar as funções do modelo, pois o Ollama cuida de tudo.

Como a API Ollama é compatível com a API OpenAI, podemos integrar facilmente o modelo de inferência e criar um aplicativo RAG usando o Playground.

Pré-requisitos

Elasticsearch 8.17
Kibana 8.17
Python

Etapas

Configurando o servidor Ollama LLM

Vamos configurar um servidor LLM para conectá-lo à nossa instância do Playground usando o Ollama. Precisaremos:

Baixe e execute o Ollama.
Use o ngrok para acessar seu servidor web local que hospeda o Ollama pela internet

Baixe e execute o Ollama

Para usar o Ollama, primeiro precisamos baixá-lo. O Ollama oferece suporte para Linux, Windows e macOS, então basta baixar a versão do Ollama compatível com seu sistema operacional aqui. Depois que o Ollama estiver instalado, podemos escolher um modelo desta lista de LLMs suportados. Neste exemplo, usaremos o modelo llama3.2, um modelo multilíngue geral. No processo de configuração, você habilitará a ferramenta de linha de comando do Ollama. Depois que o download for concluído, você pode executar a seguinte linha:

ollama pull llama3.2

O que produzirá:

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

Uma vez instalado, você pode testá-lo com este comando:

ollama run llama3.2

Vamos fazer uma pergunta:

Com o modelo em execução, o Ollama habilita uma API que seria executada por padrão na porta "11434". Vamos fazer uma requisição para essa API, seguindo a documentação oficial:

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

Esta é a resposta que obtivemos:

{"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}

Observe que a resposta específica para esse ponto de extremidade é um streaming.

Exponha o endpoint à internet usando o ngrok

Como nosso endpoint funciona em um ambiente local, ele não pode ser acessado de outro ponto, como nossa instância do Elastic Cloud, pela Internet. O ngrok nos permite expor uma porta que oferece um IP público. Crie uma conta no ngrok e siga o guia oficial de configuração.

Depois que o agente ngrok for instalado e configurado, podemos expor a porta que o Ollama está usando:

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

Observação: o cabeçalho --host-header="localhost:11434" garante que o cabeçalho "Host" nas solicitações corresponda a "localhost:11434"

Executar este comando retornará um link público que funcionará enquanto o ngrok e o servidor Ollama forem executados 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 ```

Em "Encaminhamento" podemos ver que o ngrok gerou uma URL. Guarde para mais tarde.

Vamos tentar fazer uma solicitação HTTP para o endpoint novamente, agora usando a URL gerada pelo ngrok:

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

A resposta deve ser semelhante à anterior.

Criando mapeamentos

Ponto final ELSER

Neste exemplo, criaremos um ponto de extremidade de inferência usando a API de inferência do Elasticsearch. Além disso, usaremos o ELSER para gerar os embeddings.

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 exemplo, vamos imaginar que você tem uma farmácia que vende dois tipos de medicamentos:

Medicamentos que exigem receita médica.
Medicamentos que NÃO exigem receita médica.

Essas informações seriam incluídas no campo de descrição de cada medicamento.

O LLM deve interpretar esse campo, então estes são os mapeamentos de dados 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" } } } }

O campo text_description armazenará o texto simples das descrições, enquanto semantic_field, que é um tipo de campo semantic_text , armazenará os embeddings gerados pelo ELSER.

A propriedade copy_to copiará o conteúdo dos campos name e text_description para o campo semântico para que os embeddings para esses campos sejam gerados.

Indexação de dados

Agora, vamos indexar os dados usando a API _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."}

Resposta.

{ "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 } } ] }

Fazendo perguntas usando o Playground

Playground é uma ferramenta do Kibana que permite criar rapidamente um sistema RAG usando índices do Elasticsearch e um provedor LLM. Você pode ler este artigo para saber mais sobre isso.

Conectando o LLM local ao Playground

Primeiro, precisamos criar um conector que use a URL pública que acabamos de criar. No Kibana, vá em Pesquisar>Playground e depois clique em "Conectar a um LLM".

Esta ação revelará um menu no lado esquerdo da interface do Kibana. Lá, clique em "OpenAI".

Agora podemos começar a configurar o conector OpenAI.

Vá para "Configurações do conector" e, para o provedor OpenAI, selecione "Outro (Serviço compatível com OpenAI)":

Agora, vamos configurar os outros campos. Para este exemplo, vamos nomear nosso modelo como "medicines-llm". No campo URL, use o gerado pelo ngrok (/v1/chat/completions). No campo "Modelo padrão", selecione "llama3.2". Não usaremos uma chave de API, então digite qualquer texto aleatório para prosseguir:

Clique em "Salvar" e adicione os medicamentos de índice clicando em "Adicionar fontes de dados":

Ótimo! Agora temos acesso ao Playground usando o LLM que estamos executando localmente como mecanismo RAG.

Antes de testar, vamos adicionar instruções mais específicas ao agente e aumentar o número de documentos enviados ao modelo para 10, para que a resposta tenha o maior número possível de documentos disponíveis. O campo de contexto será semantic_field, que inclui o nome e a descrição dos medicamentos, graças à propriedade copy_to.

Agora vamos fazer a pergunta: Posso comprar Clonazepam sem receita? e veja o que acontece:

Como esperado, obtivemos a resposta correta.

Próximas etapas

O próximo passo é criar seu próprio aplicativo! O Playground fornece um script de código em Python que você pode executar em sua máquina e personalizá-lo para atender às suas necessidades. Por exemplo, colocando-o atrás de um servidor FastAPI para criar um chatbot de medicamentos de controle de qualidade consumido pela sua interface de usuário.

Você pode encontrar esse código clicando no botão Exibir código na seção superior direita do Playground:

E você usa os Endpoints e as chaves de API para gerar a variável de ambiente ES_API_KEY necessária no código.

Para este exemplo específico, o código é o seguinte:

## 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 com o Ollama, você precisa alterar o cliente OpenAI para se conectar ao servidor Ollama em vez do servidor OpenAI. Você pode encontrar a lista completa de exemplos do OpenAI e endpoints compatíveis aqui.

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', )

E também altere o modelo para llama3.2 ao chamar o método de conclusão:

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

Vamos adicionar nossa pergunta: Posso comprar Clonazepam sem receita? Para a consulta do 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"]

E também para a chamada de conclusão com algumas impressões, para que possamos confirmar que estamos enviando os resultados do Elasticsearch como parte do contexto da pergunta:

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 ==========")

Agora vamos executar o comando

pip install -qU elasticsearch openai

python main.py

Você deverá ver algo assim:

========== 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 ==========

Conclusão

Neste artigo, podemos ver o poder e a versatilidade de ferramentas como o Ollama quando as usamos em conjunto com a API de inferência do Elasticsearch e o Playground.

Após alguns passos simples, tínhamos um aplicativo RAG funcional com um chat que usava um LLM em execução em nossa própria infraestrutura a custo zero. Isso também nos permite ter mais controle sobre recursos e informações confidenciais, além de nos dar acesso a uma variedade de modelos para diferentes tarefas.