Com essa integração, os usuários do Elasticsearch ganham uma nova opção de implantação que mantém os dados dentro do perímetro de segurança, entrega custos de infraestrutura previsíveis e roda de forma nativa no Google Cloud. Ao mesmo tempo, o ecossistema mais amplo do Google Cloud ganha acesso aos modelos de busca e recuperação de última geração desenvolvidos especificamente pelo Jina.

Esta é a primeira etapa de uma implementação mais ampla. Junto com os modelos que virão a seguir, a linha formará uma pilha completa de recuperação: incorpore seus dados, incorpore consultas, recupere e reclassifique candidatos, e estenda a busca para imagens com embeddings multimodais, tudo na infraestrutura que você controla. Você pode começar hoje com jina-embeddings-v3, o modelo que já alimenta pipelines de busca em produção em todo o ecossistema Elasticsearch via Elastic Inference Service (EIS).

Cada modelo roda em uma única placa NVIDIA L4 (24 GB), a camada de GPU mais econômica do Google Cloud. A maioria dos outros modelos de incorporação no Google Cloud Model Garden exige um A100 de 80 GB ou H100, aproximadamente três vezes o custo da instância por hora antes mesmo de você começar a contar os tokens.

Não é necessária licença comercial adicional quando implantada via Vertex AI.

Por que o Model Garden?

Por que implantar pelo Model Garden em vez de usar uma API? Tudo se resume a três coisas: controle, custo e contexto.

Seus dados nunca saem do ambiente seguro

O principal atrativo para a maioria dos desenvolvedores é a arquitetura de autoimplantação. Quando você implanta um modelo Jina pelo Model Garden, os pesos são executados em instâncias de GPU dentro do seu próprio projeto Google Cloud e da sua própria VPC. Isso é um divisor de águas para qualquer pessoa que trabalhe em setores com preocupações com segurança de dados, como finanças ou saúde. Como não há chamadas externas de API, seus dados sensíveis permanecem dentro do seu perímetro de segurança.

Redimensionamento com previsão

Em vez de pagar toda vez que você incorpora uma frase ou reclassifica um documento, você paga um custo fixo por hora de instância. E como todo modelo Jina pode rodar em uma única NVIDIA L4, a camada de GPU mais acessível do Google Cloud, a barreira de entrada é baixa. Seja processando mil solicitações ou um bilhão, sua conta de infraestrutura permanece previsível. Essa é uma configuração que realmente recompensa você por aumentar seu tráfego, em vez de te taxar por isso.

Tudo sob o mesmo teto

Se seus dados já estão no Elasticsearch na Google Cloud, BigQuery ou Cloud Storage, faz sentido manter seus mecanismos de inferência próximos. Ao serem implementados por meio do Model Garden, os modelos da base de pesquisa Jina herdam todos os recursos corporativos que você já utiliza: gerenciamento de identidade e acesso (IAM) para controle de acesso, faturamento unificado na fatura existente do Google Cloud e a capacidade de integração com o Vertex AI Pipelines para fluxos de trabalho de operações de aprendizado de máquina (MLOps).

Embora a API Jina AI Cloud e o Elastic Cloud ofereçam o caminho mais rápido para picos de tráfego ou fluxos de trabalho de busca existentes, o Model Garden é ideal para aplicações corporativas que exigem segurança de dados rigorosa e custos previsíveis em grande escala. A Elastic quer encontrar você onde você estiver.

Modelos Jina AI

jina-embeddings-v3

Nosso modelo comprovado de embedding multilíngue com 572 milhões de parâmetros e contexto de token 8K. Pontuação 65,5 no Massive Text Embedding Benchmark (MTEB) em inglês. Compatível com cinco adaptadores LoRA (Low-Rank Adaptation) específicos para tarefas (consulta/passagem de recuperação, correspondência de texto, classificação, agrupamento) e truncamento Matryoshka de 1024 para 64 dimensões. Já amplamente adotado em todo o ecossistema Elasticsearch via EIS.

Estamos priorizando a v3 porque muitos sistemas de produção já dependem dela. Se você está migrando um pipeline baseado em v3 para o Google Cloud, agora pode executar o mesmo modelo de forma nativa sem alterar as dimensões de embedding nem reindexar.

jina-embeddings-v5-text (pequeno e nano)

Nossos modelos de incorporação de texto de quinta geração, lançados em fevereiro de 2026, alcançam desempenho de alto nível, competindo com modelos muitas vezes maiores.

v5-text-small (677 milhões) pontua 67,0 no conjunto de benchmarks Multilingual MTEB (MMTEB), abrangendo 131 tarefas de nove tipos, e 71,7 no benchmark MTEB em inglês. É o modelo de incorporação multilíngue sub-1B mais forte no MTEB Leaderboard.

v5-text-nano (239 milhões) tem 65,5 pontos no MMTEB. Nenhum outro modelo com menos de 500 milhões de parâmetros atinge esse nível. Com menos da metade do tamanho da maioria dos modelos comparáveis, é a escolha natural para implantações sensíveis à latência.

Ambos os modelos oferecem suporte:

• Quatro adaptadores LoRA específicos para tarefas: recuperação, correspondência de texto, classificação e clustering. Selecionar um adaptador apropriado por meio do parâmetro task no momento da inferência.
• Truncamento da dimensão matrioshka: reduza as dimensões de embedding de 1024 (ou 768 para nano) para 32. A perda de qualidade é mínima em truncamento moderado (por exemplo, 256 dimensões). Ao reduzir as dimensões pela metade, você reduz o armazenamento pela metade.
• Quantização binária: comprima embeddings de 1024 dimensões de 2KB para 128 bytes com binarização. O treinamento especial faz com que esta compressão tenha perdas mínimas.
• Multilíngue: 119 idiomas (pequeno) e 93 (nano).

jina-reranker-v3

Um reclassificador de listas multilíngue com 0,6 bilhões de parâmetros, construído usando uma arquitetura de interação última, mas não tardia. A consulta e até 64 correspondências de candidatos são inseridas em uma única janela de contexto de 131 mil tokens, e o modelo realiza uma comparação cruzada de documentos antes da pontuação. O Jina Reranker v3 alcança 61,94 nDCG@10 no BEIR, superando o modelo por ser 6× menor em tamanho. Isso é fundamentalmente diferente dos reclassificadores pontuais, que pontuam cada documento isoladamente, produzindo melhores resultados, especialmente para recuperação de trechos a partir de documentos isolados.

jina-clip-v2

Um modelo de incorporação multimodal e multilíngue de 0,9B que mapeia texto e imagens em um espaço compartilhado de 1024 dimensões. Ele é compatível com:

• 89 idiomas para recuperação de texto-imagem.
• Resolução de imagem 512×512.
• Entrada de texto com token de 8 mil.
• Truncamento de Matryoshka de 1024 para 64 dimensões para ambas as modalidades.

Altamente competitivo em benchmarks de imagem para texto, incluindo tarefas multilíngues.

Para começar

Jina Embeddings v3 está disponível no Model Garden hoje. Veja como fazê-lo funcionar.

Você precisa de um projeto do Google Cloud com a API Vertex AI habilitada e cota de GPU suficiente para pelo menos uma instância g2-standard-8 (NVIDIA L4). Se você é novo no Google Cloud, comece pelo guia de configuração.

A página Model Garden para Jina Embeddings v3 guia você pelo fluxo completo: faça upload do modelo, crie um endpoint, escolha o tipo de máquina e implante. Abra-o em seu próprio projeto e siga as etapas guiadas. Máquinas A100 e H100 também estão disponíveis onde a região e a cota permitem, mas L4 é tudo que você precisa para começar.

Desde o clique até a primeira incorporação, todo o processo leva alguns minutos.

O que vem depois

Jina Embeddings v3 é o ponto de partida. Nas próximas semanas, traremos o restante do stack de recuperação Jina para o Model Garden: embeddings de texto v5 (pequeno e nano), jina-reranker-v3 e jina-clip-v2 para busca multimodal. Tudo será executado em uma única GPU L4 com o mesmo modelo de autoimplantação.

Os MCP Apps mudam a forma dessa resposta. Uma ferramenta agora pode retornar uma interface interativa junto com o resumo em texto, e o host (Claude Desktop, Claude.ai, VS Code Copilot, Cursor) o renderiza na conversa. O modelo mantém o texto compacto para raciocínio. O humano recebe uma interface ao vivo e clicável bem ao lado do chat.

Três propriedades tornam esta integração diferente de “um webhook que retorna uma URL”:

• Preservação de contexto. A UI fica dentro da conversa. Sem alternância de abas, sem transferências.
• Fluxo de dados bidirecional. A UI pode chamar ferramentas no servidor MCP para dados novos e o host pode enviar novos resultados do agente de volta para a UI. Sem camada de API separada ou infraestrutura de autenticação.
• Limite de confiança sandbox. Os MCP Apps são executados em um iframe controlado pelo host. Eles não podem acessar a página principal, ler cookies nem sair do container.

As operações de segurança são executadas com base em triagem, gráficos de investigação e descoberta de ataques, onde um agente de IA correlaciona centenas de alertas em algumas cadeias de ataque. A observabilidade significa rastreamento distribuído e análises detalhadas de séries temporais. Criar no Kibana significa ter uma grade de dashboards. Ao transformar qualquer uma dessas informações em texto simples, você perde o que a torna útil. Criamos MCP Apps para os três e estamos disponibilizando-os como open source juntos, para que a mesma conversa possa passar de uma fila de triagem para um gráfico de dependência e um dashboard em tempo real sem sair do chat.

Cada um dos três apps de referência é um servidor MCP que oferece muitas visões interativas, não um conjunto de produtos separados. Só o app de segurança exibe seis dashboards que compartilham o mesmo shell de servidor, o mesmo modelo de visibilidade de ferramentas e a mesma ponte host. O padrão é pequeno; a área de superfície é onde o valor se compõe.

Elastic Security MCP App

Por que isso é importante para o SOC

Quando um agente diz a um analista do SOC: "Há 47 alertas no host-314, aqui está um resumo", ele não fez nenhum trabalho. Ele apenas aponta para onde o trabalho começa. O trabalho real está na lista de alertas, na árvore de processos, no gráfico de investigação e no arquivo do caso. Você não pode fazer isso a partir de um parágrafo de texto.

O MCP App de segurança retorna o próprio fluxo de trabalho. O analista solicita informações ao agente, e o agente retorna um dashboard interativo no chat, onde o analista pode explorar alertas, executar buscas por ameaças, correlacionar cadeias de ataque e abrir chamados, tudo sem perder o fio da conversa. E como todas as descobertas, consultas e casos retornam ao Elasticsearch, a mesma investigação está à espera no Kibana, onde o analista pode retomar após o encerramento da conversa.

Seis dashboards interativos

O Elastic Security MCP App inclui seis elementos interativos, um para cada fluxo de trabalho principal do SOC. Cada um é uma UI React que renderiza quando o agente chama a ferramenta correspondente:

Cada ferramenta retorna um resumo em texto compacto sobre o qual o modelo pode raciocinar, junto com a UI que o analista usa. A UI também pode obter dados novos nos bastidores através da ponte de host MCP. O modelo completo da ferramenta e a API de ponte estão disponíveis no documento de arquitetura do repositório.

O app também é fornecido com habilidades do Claude Desktop, SKILL.md arquivos que ensinam ao agente quando e como usar cada ferramenta. Faça o download de zips de habilidades pré-criadas da versão mais recente.

Do alerta ao caso

Quatro habilidades abrangem o circuito do núcleo do SOC. Cada um capta um prompt, chama uma ferramenta e retorna um dashboard interativo junto com um resumo em texto que o modelo argumenta. O dia de um analista geralmente começa com uma fila de alertas.

Alertas de triagem. Peça ao agente para priorizar por host, regra, usuário ou intervalo de tempo. Peça ao agente para priorizar por host, regra, usuário ou intervalo de tempo. A habilidade de Triagem de Alertas retorna um painel de vereditos de IA acima da lista de alertas brutos, com um veredito para cada regra de detecção, classificando a atividade dessa regra como benigna, suspeita ou maliciosa, cada um com uma pontuação de confiança e uma ação recomendada. Clique em qualquer alerta para abrir uma visualização detalhada com uma árvore de processos, eventos de rede, alertas relacionados e tags MITRE ATT&CK. Não precisa alternar o contexto entre conversas de IA e seu dashboard de alertas dentro do Kibana, tudo acontece em tempo real dentro da sua conversa.

Procure ameaças. Peça ao agente para pesquisar nos seus índices. A funcionalidade Caça a ameaças retorna um workbench ES|QL com a consulta pré-preenchida e executada automaticamente, com cada entidade nos resultados clicável para detalhamento. O modelo escreve uma breve leitura abaixo da tabela: o que é incomum, o que está conectado, o que vale a pena conferir mais de perto. Em seguida, oferece a próxima opção: aprofundar-se na busca por ameaças ou iniciar uma nova habilidade no aplicativo MCP que complemente o trabalho realizado até o momento. O que combina muito bem com isso é o lançamento de uma descoberta de ataque para ter mais contexto sobre os alertas com os quais você se aprofundou e as ameaças que caçou até o momento. O que conecta tudo isso muito bem é o lançamento de um Attack Discovery para ter mais contexto sobre os alertas que você explorou e as ameaças que investigou até agora.

Execute a Descoberta de ataques. A habilidade Descoberta de Ataques ativa a API de descoberta de ataques e retorna uma lista ranqueada de descobertas. Cada descoberta é um conjunto de alertas relacionados agrupados em uma cadeia de ataque, com táticas MITRE, uma pontuação de risco, um rótulo de confiança e os hosts e usuários afetados apresentados de forma clara. O resumo do agente aparece abaixo das descobertas na mesma ordem de classificação, e a conversa agora contém tudo o que é necessário para agir: consultas de busca, decisões de triagem, cadeias correlacionadas, tudo preparado para a próxima etapa.

Abra casos sem sair do chat. Aprove resultados em lote ou solicite ao agente que abra casos para alertas específicos. A habilidade de Gerenciamento de Casos cria um caso para cada descoberta aprovada (alertas de origem anexados, táticas MITRE herdadas da cadeia de ataque) e exibe a lista de casos ativos diretamente no aplicativo. Clique em um caso para ver a visualização detalhada, que inclui uma linha de botões de ação de IA: resumir caso, sugerir próximas etapas, extrair IOCs e gerar linha do tempo. Cada um deixa um prompt estruturado de volta no chat, para que o agente possa pegar o contexto do caso sem precisar de uma reintrodução. O resumo do agente está abaixo da lista de casos e abrange toda a fila de IR, incluindo os casos recém-abertos e as descobertas anteriores que ainda precisam de uma análise.

Cada etapa deste passo a passo executa o mesmo ciclo: uma solicitação é recebida, a habilidade a processa, a ferramenta retorna um resumo de texto conciso para o modelo analisar, juntamente com uma UI que o analista usa. Ao combinar as habilidades, elas se integram em um fluxo SOC completo: busca, triagem, correlação, abertura de casos e direcionamento para a próxima etapa, tudo com o modelo carregando o contexto da sessão em cada passo. Invoque qualquer uma delas individualmente e ela ainda exibirá o dashboard completo, apontando para qualquer parte dos seus dados que você especificar. De qualquer forma, o trabalho se acumula dentro da conversa; sem troca de abas, sem copiar e colar, sem repasse de informações.

Duas outras funcionalidades complementam o app: um navegador de regras de detecção para ajustar regras ruidosas e um gerador de dados de amostra para simular eventos ECS realistas em um cluster novo. Um post de acompanhamento irá aprofundar todos os seis: gráfico de investigação, canvas de ataque e fluxo e guia de ponta a ponta.

"O MCP App do Elastic Security faz a ponte entre a detecção automatizada e a caça manual a ameaças. Ao levar nossos dados de segurança diretamente para uma única interface no Claude Desktop, identificamos ameaças “silenciosas” em menos de uma hora, riscos que não acionavam alertas padrão, mas exigiam ação imediata. É um multiplicador de força para nossos analistas". Mandy Andress: diretora de segurança da informação (CISO), Elastic.

Como funciona

Cada MCP App é um pequeno servidor Node.js cujas ferramentas retornam tanto um resumo em texto compacto do modelo quanto uma UI React que o host renderiza diretamente no aplicativo. Como ele foi desenvolvido com base na especificação aberta do MCP App, o mesmo servidor é executado em qualquer host compatível, consulte o documento de arquitetura do repositório para ver o projeto completo.

Experimente

Requer Elasticsearch 9.x com Security ativado, além do Kibana para casos, regras e Descoberta de Ataques. O caminho mais rápido é o pacote .mcpb com um clique da versão mais recente, clique duas vezes no Claude Desktop, e será solicitado que você insira sua URL e chave API do Elasticsearch. Os guias de configuração para Cursor, VS Code, Claude Code, Claude.ai e compilação a partir do código-fonte estão no repositório.

Elastic Search MCP App: dashboards criados a partir de conversas

Todo usuário do Kibana conhece o desvio do dashboard: interrompa o que está fazendo, abra o Kibana, escolha um índice, escolha campos, escolha uma visualização, ajuste e salve. São cinco mudanças de contexto antes de um único gráfico aparecer na tela.

O novo app de referência example-mcp-dashbuilder integra isso em um prompt. Peça ao agente para "criar um dashboard com métricas de receita, tendências de pedidos e detalhamento de categorias" e o dashboard voltará para a conversa sem a necessidade de alternar entre guias.

Por trás desse comando, o agente explora seus dados do Elasticsearch via ES|QL e seleciona tipos de gráficos adequados aos dados: barras para comparações, linhas para tendências, cards de métricas para KPIs e mapas de calor para padrões bidimensionais. Ele organiza os painéis na grade de 48 colunas do Kibana usando o tema Elastic UI Borealis, e o resultado é totalmente interativo: você pode arrastar, redimensionar e agrupar painéis em seções recolhíveis diretamente no chat. Quando o dashboard estiver configurado corretamente, uma única chamada de ferramenta o exporta para o Kibana, preservando as consultas ES|QL e as cores personalizadas. Você também pode importar dashboards existentes do Kibana de volta para o chat para editar com a ajuda de IA.

O princípio é o mesmo por trás do app Security: quando o artefato é o produto, retorná-lo dentro da conversa fecha o ciclo entre descrever o que você quer e vê-lo.

Sob o capô, ele segue o mesmo padrão do MCP App. Um servidor Node.js registra uma ferramenta view_dashboard voltada para o modelo junto com um conjunto de ferramentas exclusivas de app que a UI chama diretamente (busca de dados, persistência do layout, detecção de campo de tempo, exportação/importação). A visualização do dashboard em si é um único arquivo HTML autônomo incluído com vite-plugin-singlefile e oferecido como recurso do MCP App. Os desenvolvedores que criam um fork do repositório têm o mesmo shell de servidor e a mesma ponte de host que veem no aplicativo de segurança, apontando para uma tarefa diferente. O README example-mcp-dashbuilder tem a arquitetura completa e a referência do tipo de gráfico.

Elastic Observability MCP App

O terceiro app de referência, Elastic Observability MCP App, aborda a versão SRE do problema de mesmo formato. Quando algo interrompe a produção, a resposta que o engenheiro de plantão precisa não é um gráfico, mas sim um diagnóstico feito a partir das métricas K8, da topologia do APM, das anomalias de ML e da avaliação de risco. A forma da resposta é uma história causal: o que falhou, por quê, o que depende disso e o que fazer a seguir.

Seis ferramentas que suportam o fluxo de trabalho de investigação de observabilidade

Cluster health rollup

Pergunte "o que está com defeito?" ou "me dê um relatório de status" e receba uma orientação instantânea: indicador geral de integridade, serviços degradados com as respectivas causas, principais consumidores de memória dos pods, detalhamento da gravidade das anomalias e taxa de transferência do serviço, tudo em uma única visualização embutida. Este é o ponto de partida quando algo parece errado, mas você não sabe onde procurar. A visualização se adapta com base nos recursos compatíveis com a sua implantação. O APM fornece informações sobre a saúde do serviço. As métricas de Kubernetes adicionam contexto ao pod e ao nó. Os trabalhos de ML adicionam anomalias.

Gráfico das dependências dos serviços

Pergunte "o que aciona o checkout?" ou "mostre-me a topologia" e tenha um gráfico de dependências em camadas, autores de chamada upstream, dependências downstream, protocolos, volume de chamadas e latência por edge. Vamos pedir ao Claude para "mostrar as dependências de serviço do frontend":

Aumente o zoom, mova a câmera e passe o cursor sobre a imagem para ter todos os detalhes necessários para compreender as complexas relações de serviço:

Avalie o risco com um raio de explosão

Pergunte "o que acontece se meu nó do k8s cair?" e tenha um diagrama de impacto radial: o nó alvo no centro, implantações com interrupção total em vermelho, interrupções degradadas em cor âmbar e as não afetadas em cinza. Um cartão flutuante mostra os pods em risco e a viabilidade de reagendamento. Implantações de réplica única são sinalizadas como pontos únicos de falha. 

Observe

O primitivo de acesso primário do agente para Elastic — uma ferramenta, três modos para três necessidades diferentes. Diga "o que a CPU está fazendo agora?" e ele executa um ES|QL uma vez e retorna uma tabela. Diga "mostre a latência frontend dos próximos 60 segundos" e ele faz amostragem ao vivo da métrica, atualizando o gráfico no local. Fale "diga-me quando a memória ficar abaixo de 80 MB" ou "observe qualquer coisa incomum pelos próximos 10 minutos" e ela bloqueia até que a condição seja acionada ou a janela expire. A visualização se adapta ao modo: uma tabela de resultados para consultas one-shot, um gráfico de tendência ao vivo com estatísticas atuais/pico/base para amostragem e condições de limiar, e um cartão de gatilho pontuado por gravidade para o modo anomalia.

Como funciona

Mesmo padrão de MCP App que os apps do Security e Search: um servidor Node.js, seis ferramentas voltadas para modelos conectadas a seis recursos de visualização de arquivo único. As ferramentas são agrupadas por backend de implantação (Universal, dependente de APM, dependente de K8s, dependente de ML), para que o agente e o usuário saibam antecipadamente quais ferramentas se aplicam a uma determinada implantação, em vez de descobrir lacunas de capacidade no momento da chamada. O MCP App também inclui um exemplo de fluxo de trabalho do Agent Builder: k8s-crashloop-investigation-otel que pode ser acionado por um alerta do Kubernetes e retornar um resumo estruturado da causa raiz antes de você ter aberto um único dashboard.

A pilha agêntica, interativa

Três propriedades desse padrão merecem ser mencionadas diretamente. Primeiro, o resultado da ferramenta não é mais o fim do trabalho, mas o início: a conversa retorna uma interface na qual você pode agir, e não um resumo do qual você precisa partir. Segundo, o mesmo agente, o mesmo contexto do modelo e a mesma linha de conversa agora podem se mover por superfícies do Security, Search e do Observability sem sair da conversa. Terceiro, isso só funciona porque o Elasticsearch e o Kibana já expõem as APIs. O MCP App é uma camada interativa fina sobre as funcionalidades do produto que já enviamos.

O Attack Discovery já alimenta a visualização de descobertas correlacionadas dentro deste app. Dentro da pilha, o mesmo padrão agêntico vai além: o Elastic Workflows automatiza as etapas determinísticas (enriquecer entidades, criar casos, isolar hosts), enquanto o Agent Builder raciocina sobre os dados e invoca esses fluxos de trabalho como ferramentas. O MCP App traz essa mesma superfície de segurança para a conversa externa; o Workflows e o Agent Builder a aprofundam na pilha. Pontos de entrada diferentes, mesmas APIs da Elastic por trás de tudo.

Experimente:

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

Ainda não tem um cluster Elasticsearch? Inicie uma avaliação gratuita do Elastic Cloud. Para mais informações sobre os componentes básicos do aplicativo de segurança, consulte as postagens relacionadas do Security Labs sobre Elastic Workflows e Agent Builder, Habilidades de agentes e Descoberta de ataques.

Hoje, essa história fica muito mais simples. Chaves de API do Elastic Cloud agora podem ser usadas para autenticar diretamente em comparação a APIs do Elasticsearch e Kibana no Elastic Cloud Serverless. Agora você pode usar uma única credencial para gerenciar os recursos da sua organização e executar operações de dados, como a Elasticsearch Query Language (ES|QL), ingestão de dados e alertas.

Vamos ver por que construímos isso, como projetamos uma camada de identidade distribuída globalmente para possibilitar o recurso e como ele estabelece a base para a busca entre projetos.

O ônus da gestão de segredos

Construir pipelines confiáveis de CI/CD, fluxos de trabalho GitOps ou automação Terraform em plataformas de dados tem um custo oculto: a proliferação de segredos.

No modelo anterior, os desenvolvedores lidavam com uma história de autenticação desarticulada:

• Plano de controle (chaves da API do Elastic Cloud): chaves com escopo organizacional usadas para criar projetos, convidar usuários e gerenciar as cobranças via API do Elastic Cloud.
• Plano de dados (chaves da API do Elasticsearch): Chaves com escopo de projeto criadas dentro de um projeto Serverless específico para interagir com as APIs do Elasticsearch e do Kibana.

Nesse caso, seu script de implantação precisava se autenticar no Elastic Cloud, provisionar um projeto Serverless, extrair uma chave de API do Elasticsearch recém-criada desse projeto específico e, em seguida, inserir essa segunda chave na aplicação ou na ferramenta de automação mais adiante, o que resultava em pipelines complexos, logs de auditoria fragmentados e maior risco de vazamento de credenciais.

Autenticação unificada no Elastic Cloud Serverless

Com este lançamento, a separação para projetos Serverless foi eliminada. Agora você pode criar uma chave de API do Elastic Cloud explicitamente autorizada para nuvem, Elasticsearch e Kibana APIs.

• Antes: a chave de API do Elastic Cloud era estritamente um token do plano de controle. Ela podia criar projetos, gerenciar cobranças e convidar usuários, mas tinha um limite rígido; não podia ser usada para chamar as APIs do Elasticsearch nem Kibana dentro desses projetos. Você sempre precisava de uma segunda chave específica do projeto para operações de dados.
• Agora: ao ter acesso a nuvem, Elasticsearch e a API Kibana ao criar uma chave de API do Elastic Cloud, o limite rígido é retirado para o Serverless. Essa chave de API se torna uma credencial verdadeiramente unificada. Ela mantém a capacidade de gerenciar a infraestrutura da sua organização, ao mesmo tempo que ganha acesso nativo para consultar, ingerir e analisar dados em qualquer projeto Serverless autorizado.

Ao unificar tudo sob uma única chave de API do Elastic Cloud, você ganha uma única identidade que pode ter escopo definido, ser auditada, rotacionada e revogada como uma unidade. Cada chamada de API, seja para provisionar um novo projeto ou executar uma consulta ES|QL, aparece sob a mesma credencial nos seus logs de auditoria, fornecendo um único rastro a ser seguido durante investigações de incidentes ou revisões de conformidade. A rotação de credenciais agora é feita em uma etapa em vez de ser uma atualização coordenada em segredos separados do plano de controle e do plano de dados. E, como as alocações de função são por projeto, uma só chave pode abranger vários projetos, gerenciando a ingestão no seu projeto de observabilidade e executando consultas no seu projeto de segurança, sem precisar lidar com credenciais separadas para cada um.

Importante: unificado não significa todo-poderoso. Ao usar a carga útil role_assignments, você pode definir uma chave unificada estritamente para um único projeto e uma função específica (como somente leitura), garantindo que o raio de explosão continue totalmente contido caso uma credencial seja exposta. Se um desenvolvedor sair ou uma aplicação for desativada, você pode revogar uma única chave do console Elastic Cloud, encerrando imediatamente o acesso tanto no plano de controle quanto em todos os projetos Elasticsearch associados.

(Atenção: nas implantações Elastic Cloud Hosted/gerenciadas, as chaves da API da nuvem ainda gerenciam apenas o plano de controle. O suporte para estender isso às APIs de pilha hospedada está planejado para uma versão futura.)

Automatizando seus fluxos de trabalho

Começar é simples. Você pode configurar inteiramente no console Elastic Cloud ou automatizar usando a API do Elastic Cloud.

O processo da IU não muda, mas agora você pode selecionar Nuvem, Elasticsearch e API Kibana na alocação de função do projeto.

Veja como criar uma chave unificada programaticamente usando a API do Elastic Cloud. Observe o application_roles conjunto, pois é o que concede ao principal acesso nativo ao plano de dados do Elasticsearch:

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

Uma vez criado, você passa exatamente essa mesma chave no cabeçalho Authorization: ApiKey tanto para api.elastic-cloud.com quanto para seus endpoints específicos do Serverless Elasticsearch.

Nos bastidores: construindo uma camada de identidade distribuída

Fazer uma chave da API da nuvem funcionar tanto no plano de controle quanto no plano de dados não é tão simples como passar um token. É preciso resolver um desafio fundamental nos sistemas distribuídos.

Historicamente, as chaves de API da nuvem ficavam em um cluster de segurança global centralizado. Isso funciona nas operações de plano de controle cuja latência mais alta é aceitável. No entanto, requisições de dados do Elasticsearch exigem latência ultrabaixa. Não podemos viajar pelo globo até um plano de controle central para validar cada busca ou solicitação de ingestão.

Para resolver, introduzimos uma nova arquitetura de autenticação apoiada por um datastore distribuído globalmente. O diagrama sequencial a seguir mostra um cliente enviando uma consulta Elasticsearch, usando uma chave API do Elastic Cloud, ilustrando como a autenticação ocorre inteiramente dentro da região, sem a viagem por todo o plano de controle global. O Elasticsearch delega a autenticação ao Serviço IAM Regional, que valida a chave e resolve as alocações de função em uma réplica local do banco de dados distribuído globalmente. Uma vez autorizado, o Elasticsearch executa a consulta e retorna os resultados ao cliente.

Persistência distribuída globalmente

Em vez de depender exclusivamente de um cluster de segurança centralizado, as chaves de API do Elastic Cloud e as respectivas definições de função agora ficam em um banco de dados globalmente distribuído e de alta disponibilidade. Esse banco de dados sincroniza os dados de gerenciamento de identidade e acesso (IAM) no plano de controle global e nos planos de dados regionais onde seus projetos Serverless são executados.

Validação local com IAM regional

Quando seu cliente envia uma requisição para o Elasticsearch usando uma chave API do Elastic Cloud, a solicitação não retorna ao plano de controle global. Em vez disso, ela é encaminhada para o novo serviço regional IAM. Ele valida a chave em relação à réplica do banco de dados local, garantindo que a autenticação ocorra com latência quase zero e completamente isolada de interrupções no plano de controle global.

Mapeamento dinâmico de funções

A autenticação é metade do caminho; o sistema também precisa autorizar a solicitação. O serviço IAM regional traduz na hora suas alocações de função no nível da nuvem, por exemplo, application_roles), em privilégios nativos do Elasticsearch. O Elasticsearch pode então autorizar e executar a solicitação no local, sem precisar de um .security índice local.

A base para a busca entre projetos

Essa arquitetura de identidade distribuída é um elemento fundamental para o futuro da plataforma Elastic.

Como a identidade e o acesso agora estão unificados e sincronizados globalmente, temos o framework necessário para transmitir sua identidade com segurança entre diferentes projetos. Isso possibilita as futuras capacidades de Busca Cruzada por Projetos (CPS) para Serverless.

Com o CPS, você poderá consultar dados que abrangem vários projetos Serverless remotos, como combinar cargas de trabalho de segurança e observabilidade, como se fossem um único conjunto de dados. Ao depender de chaves de API unificadas, o sistema pode avaliar automaticamente suas permissões simultaneamente em todos os projetos, sem exigir que você configure relacionamentos de confiança complexos, certificados ou credenciais duplicadas em cada projeto-alvo.

Saiba mais

Pronto para simplificar sua pilha?

• Leia a documentação das chaves de API do Elastic Cloud para aprender como atribuir acesso ao stack.
• Confira a referência Criar chave de API (Elastic Cloud API) para automatizar a geração de chaves.
• Consulte Chaves de API Elastic para uma comparação completa dos tipos de chave em toda a plataforma Elastic.

Comece ou continue construindo no Elastic Cloud hoje.

Aviso de isenção

O lançamento e o tempo de amadurecimento de todos os recursos ou funcionalidades descritos neste artigo permanecem a exclusivo critério da Elastic. Os recursos ou funcionalidades não disponíveis no momento poderão não ser entregues ou não chegarem no prazo previsto.

As organizações acumulam grandes coleções de documentos, como chamados de suporte, processos judiciais, notícias, artigos de pesquisa, e precisam entender o que eles contêm antes de poderem fazer as perguntas certas. Sem rótulos nem dados de treinamento, revisar manualmente milhares de documentos é impraticável. A busca tradicional não ajuda quando você não sabe o que procurar.

Esta publicação tem uma abordagem nativa do Elasticsearch para clustering de documentos não supervisionados e rastreamento de histórias temporais que lida com esse problema de descoberta. Ao final, você poderá acompanhar arcos narrativos como este ao longo de vários dias:

O que você vai descobrir:

• Por que embeddings de clustering (e não embeddings de recuperação) são importantes quando se deseja descobrir tópicos sem uma consulta?
• Como a classificação de centroides sondada por densidade agrupa documentos por tópico usando Elasticsearch k-nearest neighbor (kNN) e processamento em lote msearch.
• Como significant_text pode automaticamente rotular clusters para que os temas sejam legíveis sem precisar treinar um modelo?
• Como as cadeias temporais de histórias conectam clusters diários para mostrar como os temas evoluem dia após dia.

O pipeline utiliza ~8.500 artigos de fevereiro de 2025 da BBC News e do The Guardian como um corpus de teste. As notícias são convenientes porque apresentam um comportamento temporal claro, mas esse padrão se aplica a qualquer situação em que a descoberta de documentos seja importante: revisão jurídica, monitoramento de conformidade, síntese de pesquisas, triagem de suporte ao cliente.

Stack:

• Jina v5 clustering embeddings: adaptadores LoRA (Low-Rank Adaptation) específicos para tarefas no agrupamento de tópicos. Jina ingressou na Elastic e os modelos estão disponíveis nativamente por meio do Elastic Inference Service (EIS).
• Elasticsearch: kNN escalável, rotulagem significant_text e armazenamento de vetores.
• DiskBBQ: um formato de índice vetorial baseado em disco que combina quantização binária aprimorada (BBQ) com particionamento hierárquico k-means para aceleração aproximada de vizinhos mais próximos (ANN). Essa partição de índice é interna à busca vetorial e separada do algoritmo de clustering baseado em densidade usado nesta postagem. bbq_disk armazena vetores quantizados em disco e mantém apenas metadados de partição no heap, reduzindo os requisitos de recursos, em comparação com bbq_hnsw, mantendo alta recuperação.
• Clustering global + vinculação temporal diária: descoberta e evolução da narrativa.

O que você precisará:

• Uma implementação do Elasticsearch (Elastic Cloud, Elasticsearch Serverless ou Elastic Self-Managed 8.18+/9.0+): bbq_disk requer a versão 8.18 ou posterior. A seção opcional do diversificador retriever exige 9.3+ ou serverless.
• Uma chave de API Jina: o nível gratuito inclui 10 milhões de tokens, o que cobre o pipeline principal de clusterização (aproximadamente 4,25 milhões de tokens). A comparação opcional entre recuperação e clustering usa uma segunda passagem de incorporação.
• Uma chave de API do Guardian (gratuita).

Configuração

Instale os pacotes necessários:

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

Opcional (somente se você executar ferramentas de scraping deste repositório):

pip install beautifulsoup4

Depois, configure chaves de API em um arquivo .env na raiz do projeto:

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

Este notebook chama load_dotenv(override=True), portanto os valores locais .env têm precedência.

Connected to Elasticsearch

Parte 1: clustering de descoberta – Por que fazer clustering de embeddings?

A maioria das buscas vetoriais utiliza embeddings de recuperação treinados para associar uma consulta a documentos relevantes. Isso é perfeito para buscas, mas não para descobertas. Quando você quer descobrir quais tópicos existem em um corpus sem qualquer consulta, precisa de embeddings que agrupem documentos semelhantes.

O Jina v5 resolve isso com adaptadores Low-Rank Adaptation (LoRA) específicos para cada tarefa. O LoRa adiciona pequenas atualizações de baixa classificação às camadas internas específicas, mantendo a maioria dos pesos do modelo base congelados, de modo que o comportamento do modelo se adapta a uma tarefa específica sem a necessidade de um novo treinamento completo. O mesmo modelo base produz embeddings diferentes dependendo do parâmetro task:

O adaptador de clustering é treinado para aproximar documentos sobre o mesmo tópico no espaço de incorporação e distanciar documentos sobre tópicos diferentes. A comparação visual abaixo torna a diferença concreta.

Recuperação vs. clustering: uma comparação visual

Para ver a diferença, uma amostra de documentos recebe embedding de ambos os tipos de tarefa. O clustering é realizado no espaço de incorporação original de 1024 dimensões; a aproximação e projeção uniforme de variedades (UMAP) é usada apenas para projetar essas incorporações em 2D para visualização. A UMAP preserva a estrutura local de vizinhança, tornando-a útil para comparar a separação de clusters.

Abaixo, o mesmo exemplo de 480 documentos é incorporado com ambos os tipos de tarefas e projetado para 2D com UMAP. Procure grupos de cores mais fechados e separados no painel de clustering.

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


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


    Clustering embeddings: 480
    Retrieval embeddings:  480


    UMAP projection complete

Os embeddings de recuperação (à esquerda) espalham amplamente os tópicos; os embeddings de clustering (à direita) produzem grupos mais coesos e separados a partir dos mesmos documentos.

Os embeddings de clustering produzem grupos mais compactos e visualmente distintos. Os embeddings de recuperação distribuem os tópicos de maneira mais uniforme, ideais para busca (similaridade refinada); mas, para descoberta, o que importa são os clusters temáticos compactos.

É por isso que o task="clustering" é usado no restante deste guia.

Carregando o conjunto de dados

O corpus combina duas fontes de notícias para fevereiro de 2025:

• BBC News através do conjunto de dados RealTimeData/bbc_news_alltime HuggingFace.
• The Guardian através da API da Guardian Open Platform.

Ter múltiplas fontes ajuda a validar se o clustering encontra tópicos em vez de estilos específicos de cada fonte.

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

Embedding com a tarefa de clustering

A API Jina v5 é chamada com task="clustering" para todos os documentos. Os embeddings são armazenados em cache no disco, portanto, as execuções subsequentes ignoram a API completamente.

A chamada da API é direta. O parâmetro task é a principal diferença em relação ao uso típico de embeddings:

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

O tempo abaixo reflete uma taxa de acerto do cache. A primeira execução contra a API demora mais, dependendo do tamanho do corpus.

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

Indexação em um único índice do Elasticsearch

Para clustering de descoberta, o mês inteiro é dedicado a um índice (docs-clustering-all). A partição diária vem depois para a ligação temporal da história.

O mapeamento do índice usa bbq_disk para o campo vetorial:

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

Um vetor float32 de dimensão 1024 tem 4 KB. bbq_disk utiliza k-means hierárquicos para particionar vetores em pequenos clusters, quantificá-los de forma binária e armazenar os vetores de precisão total no disco para repontuação. Apenas os metadados de partição permanecem no heap, então os requisitos de memória permanecem baixos mesmo para corpora grandes. Para cargas de trabalho que podem suportar mais heap, bbq_hnsw constrói um gráfico Hierarchical Navigable Small World (HNSW) para consultas mais rápidas com mais custo de recursos.

O tipo de campo dense_vector suporta múltiplas estratégias de quantização: bbq_disk e bbq_hnsw são os melhores ajustes para embeddings de alta dimensão como os vetores de dimensão 1024 usados aqui.

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

Clusteringo: classificação de centroides baseada em densidade

Algoritmos de clustering tradicionais, como o HDBSCAN, pressupõem que você possa manter a matriz vetorial completa de N×d na memória e executar atualizações de passagem completa repetidas. Para 8.495 documentos em 1024 dimensões, isso é administrável (aproximadamente 35 MB), mas a abordagem não é escalável para milhões de documentos sem infraestrutura adicional.

Este algoritmo é conceitualmente semelhante à inicialização do KMeans++ com atribuição de Voronoi e um nível de ruído, mas utiliza a busca kNN do Elasticsearch como primitiva de computação, mantendo quase todo o trabalho no lado do servidor:

1. Amostra de 5% de documentos como sondas de densidade (amostra aleatória, mínimo de 50).
2. Densidade da sonda por meio de lote msearch kNN. Cada sonda dispara uma consulta kNN e registra a semelhança média dos vizinhos. Alta similaridade média = região densa do espaço de embedding. msearch envia várias solicitações de pesquisa em uma única chamada HTTP, o que é fundamental aqui: a sondagem de densidade gera centenas de consultas kNN e processá-las em lote evita a sobrecarga por solicitação.
3. Selecione sementes de alta densidade com diversificação: os candidatos acima da densidade média são classificados por densidade decrescente e aceitos avidamente somente quando a semelhança de cosseno com cada semente existente estiver abaixo de um limite de separação. Este é o único processamento do lado do cliente (~0,01s para 8k documentos).
4. Classificar todos os documentos em relação aos centroides via msearch kNN: cada semente atua como um centroide; uma pesquisa kNN recupera documentos próximos acima de um limite de similaridade. Cada documento é atribuído ao centroide que o retornou com a maior pontuação. Pequenos clusters são dissolvidos em ruído.

O Elasticsearch cuida do trabalho pesado: msearch para sondas de densidade, msearch para classificação e significant_text para rotulagem. Para esse corpus (8.495 documentos), a amostra de sonda de densidade de 5% executa consultas de sonda de 425 kNN, que msearch agrupam lotes em nove chamadas HTTP (no tamanho de lote 50), evitando a sobrecarga de uma solicitação por sonda. Combinado com bbq_disk busca ANN, isso mantém a etapa de clustering rápida e escalável. As consultas kNN usam um valor mínimo de num_candidates para velocidade durante a passagem de clustering; consultas de busca em produção devem usar valores de num_candidates mais altos para melhorar a recordação, mas isso custa latência.

Clusters têm tamanhos naturais determinados pela densidade do espaço de embedding ao redor de cada centroide, não por um limite de k rígido. Regiões temáticas densas produzem clusters maiores; tópicos de nicho produzem agrupamentos menores.

Por que escolher KMeans ou HDBSCAN?

O algoritmo KMeans pressupõe clusters esféricos e requer a matriz completa N×d na memória. Para corpora que cabem na memória, HDBSCAN é uma excelente alternativa. Ele lida com formatos de cluster arbitrários e possui semântica de densidade bem compreendida.

A abordagem de centroide sondado por densidade mira em um nicho diferente: corpora onde você quer armazenamento, recuperação e clustering em um único sistema, ou onde a escala torna as operações matriciais do lado do cliente impraticáveis. Ele usa o Elasticsearch kNN como primitiva de computação, lida com tamanhos arbitrários de cluster e mantém quase toda a computação no lado do servidor.

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

Entendendo a taxa de ruído

A taxa de ruído de ~28% é intencional, não uma falha. Documentos que não cabem em nenhum cluster denso na similarity_threshold configurada ficam sem atribuição, em vez de serem forçados a uma correspondência ruim. Isso funciona como um filtro de qualidade: colunas de opinião, artigos curtos e reportagens isoladas naturalmente resistem ao clustering porque falta a densidade temática que define um grupo coerente.

O limiar é ajustável: reduzir similarity_threshold produz clusters mais abrangentes (mais documentos atribuídos, mas clusters menos coesos), enquanto aumentá-lo torna os clusters mais compactos e aumenta a fração de ruído. Para este corpus de conteúdo de notícias misto, ~30% de ruído é um ponto de operação razoável. Implantações em produção devem ajustar o limiar com base em critérios de qualidade específicos do domínio.

Rótulos automáticos com significant_text

Agora, cada cluster precisa de um rótulo de fácil compreensão. A agregação significant_text do Elasticsearch encontra termos que aparecem com frequência incomum em um conjunto em primeiro plano (o cluster) em comparação com um conjunto em segundo plano (o corpus completo).

Nos bastidores, ele usa uma heurística estatística (pontuação JLH por padrão) que equilibra mudanças de frequência absolutas e relativas, sem machine learning, sem chamadas de grandes modelo de linguagem (LLM). Um cluster sobre política do Reino Unido pode apresentar termos como starmer, labour, downing porque esses termos são desproporcionalmente comuns nesse cluster em comparação ao conjunto geral de notícias.

Para essa passagem global, os rótulos são calculados diretamente contra docs-clustering-all, então tanto o plano de frente quanto o plano de fundo são extraídos do mês inteiro. Na parte 2, a rotulagem utiliza o padrão de indexação diário (docs-clustering-*), um caractere curinga que permite que consultas abranjam todos os índices correspondentes simultaneamente, para dar significant_text um plano de fundo mais amplo e melhor contraste.

Um formato de consulta mínimo tem a seguinte aparência:

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

significant_text serve também como um filtro de qualidade: clusters que não produzem termos significativos não possuem vocabulário distintivo. São agrupamentos incoerentes que devem ser dissolvidos e reduzidos a ruído, em vez de receberem um rótulo enganoso.

Uma etapa de limpeza determinística e leve remove termos de rótulos irrelevantes (tokens numéricos, palavras genéricas) e recorre a um título representativo quando necessário. Isso mantém os rótulos nativos do Elasticsearch enquanto melhora a legibilidade.

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


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

Visualizando os clusters

As visualizações abaixo mostram o que a análise de clustering global descobriu: uma análise por data de documentos agrupados versus documentos de ruído, uma projeção UMAP para o mês inteiro e um gráfico de composição de fontes confirmando que os agrupamentos refletem tópicos em vez de fontes.

Distribuição diária de documentos agrupados versus ruídos ao longo de fevereiro de 2025.

Cada ilha colorida no UMAP representa um cluster: um grupo de artigos sobre o mesmo tema descobertos puramente por similaridade de incorporação. Os pontos de ruído cinza são artigos que não se encaixavam perfeitamente em nenhum cluster (artigos curtos, artigos de opinião ou histórias isoladas).

O gráfico de detalhamento da fonte confirma que os clusters contêm artigos de ambos BBC News e The Guardian. O clustering está encontrando tópicos, não fontes, exatamente o que a descoberta não supervisionada deve produzir.

Explorando a amplitude do cluster com o diversificador

O algoritmo kNN simples retorna os documentos mais semelhantes ao centroide de um cluster (o núcleo denso). Mas clusters reais abrangem subtópicos. O recuperador de diversificação usa a relevância marginal máxima (MMR) para destacar documentos que são relevantes para o centroide, mas também diferentes entre si.

O parâmetro chave é λ (lambda):

• λ = 1,0 → relevância pura (o mesmo que kNN simples).
• λ = 0,0 → diversidade pura (resultados de distribuição máxima).
• λ = 0,5 → equilibrado: relevante para o tópico, mas abordando diferentes perspectivas.

Uma forma mínima de solicitação de recuperador é assim:

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

Os parâmetros type, field, e query_vector são necessários no nível de diversificação: field informa à MMR qual campo dense_vector usar para similaridade entre resultados, e query_vector fornece o ponto de referência para a pontuação de relevância.

Isso permite que você responda: "O que esse cluster cobre de fato?" em vez de apenas "Qual é o ponto central?"

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


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

Os resultados simples kNN se agrupam em torno de um ângulo do tema: os documentos mais semelhantes ao centroide e entre si. O recurso de recuperação de diversidade revela diferentes facetas do mesmo cluster: subtópicos, fontes diversas e perspectivas variadas.

A métrica de diversidade confirma isso quantitativamente: a similaridade média entre pares é menor para os resultados do recuperador diversificado, o que significa que os documentos retornados abrangem um espectro mais amplo.

Isso é útil para você:

• Entender o que um cluster cobre, não apenas o centro, mas também as bordas.
• Geração de resumos. Documentos representativos diversos oferecem um material melhor para um LLM.
• Encontrar exemplos representativos para análise humana ou rotulagem posterior.
• Verificações de qualidade. Se os resultados diversos parecerem incoerentes, o cluster pode precisar ser dividido.

Parte 2: Cadeias de histórias temporais

Acompanhando histórias ao longo dos dias

A parte 1 fez o clustering de todo o mês global para descoberta de tópicos. Para o fluxo temporal, a mesma classificação de centroides sondados por densidade é executada independentemente por dia em índices diários, e depois os clusters são vinculados ao longo de dias consecutivos. Observe que os clusters diários são independentes dos clusters globais da parte 1; cada dia produz as próprias atribuições de agrupamento e rótulos ajustados ao conteúdo daquele dia.

A abordagem de vinculação: amostragem e consulta

Para cada cluster no dia A:

1. Você pode ver uma amostra de alguns documentos representativos.
2. Executar kNN contra o índice do dia B.
3. Conte quantos acessos caem em cada cluster B do dia.
4. Se a fração de acerto ultrapassar um limite (fração de kNN ≥ 0,4), registre um link.

Isso é rápido (apenas alguns documentos por cluster são consultados, nem todos) e usa o kNN nativo do Elasticsearch, sem necessidade de ferramentas externas.

Preparing daily indices for temporal linkage...


Indexed 8,495 docs into 28 daily indices


Temporal links found: 808 in 145.4s

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

Uma fração de kNN de 100% significa que todos os documentos mostrados do cluster de origem foram atribuídos ao mesmo cluster de destino, o vínculo mais forte possível entre os dias. A maioria dos links acima está relacionada ao futebol, o que faz sentido: a cobertura da Premier League é feita diariamente com alta consistência de tópicos.

O link score | operator | gedling → league | striker | season é um exemplo de um cluster de futebol local de nicho (Gedling é um clube fora da liga) sendo absorvido pelo cluster mais amplo da Premier League no dia seguinte, um efeito natural do clustering diário em diferentes granularidades.

Criar cadeias de histórias

Uma cadeia de histórias é uma sequência de clusters ligados ao longo de dias consecutivos.

Ligações pareadas individuais indicam que o cluster "política do Reino Unido" de segunda-feira está conectado ao de terça-feira. As cadeias revelam o arco completo: uma história que começa na segunda-feira, evolui durante a semana e encerra na sexta-feira.

As cadeias são construídas de forma ávida a partir de links com uma fração kNN ≥ 0,4, o que significa que pelo menos 40% dos documentos mostrados do cluster de origem chegaram a um único cluster de destino. A partir do cluster mais antigo, o algoritmo sempre segue o link de saída mais forte.

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

A rede mais longa acompanha a cobertura Ucrânia–Rússia por 19 dias consecutivos, o que não surpreende dada a intensidade geopolítica em fevereiro de 2025. O segundo mais longo acompanha o futebol da Premier League ao longo de 19 dias do mês. Cadeias mais curtas captam a temporada de premiações (filme/prêmios, seis dias), o rúgbi Six Nations (10 dias) e a cobertura da liderança política do Reino Unido (sete dias). Cada cadeia representa um arco narrativo que o algoritmo descobriu ao incorporar similaridade entre índices diários.

Sankey: Visualizando o fluxo da história

Um diagrama de Sankey é uma visualização de fluxo onde a largura da ligação representa a força da conexão. Aqui, cada faixa vertical representa um dia, cada nó é um cluster diário (dimensionado pela contagem de documentos), e cada caminho colorido traça uma cadeia de histórias ao longo do tempo. A largura do link codifica a força de sobreposição kNN: links mais espessos indicam que mais documentos mostrados caíram no cluster alvo. As cores são consistentes por cadeia, então um único caminho colorido da esquerda para a direita representa o progresso de uma história.

Por exemplo, a cadeia Ucrânia-Rússia (visível como um dos caminhos mais longos) flui continuamente desde o início de fevereiro até a terceira semana, com elos consistentemente espessos indicando forte continuidade temática ao longo dos dias.

Cadeias temporais de histórias que fluem ao longo de fevereiro de 2025. Cada caminho colorido representa uma história que persiste ao longo dos dias; com a largura indicando a força de sobreposição do kNN.

O que essa abordagem oferece

Esta análise abordou um pipeline completo de clustering de documentos não supervisionado construído no Elasticsearch:

1. Embeddings de clustering: os adaptadores específicos de tarefa do Jina v5 produzem embeddings otimizadas para agrupamento de tópicos, e não apenas para correspondência de consulta-documento.
2. Clustering de descoberta global: clustering o mês inteiro em um único índice maximiza a descoberta de tópicos ao longo dos dias.
3. Classificação de centroides com base na densidade: amostra 5%, sondar a densidade via msearch kNN, selecionar sementes diversas de alta densidade, classificar todos os documentos em relação aos centroides. O Elasticsearch cuida do processamento pesado; apenas a seleção de sementes executa do lado do cliente (~0,01s).
4. significant_text rotulagem: o teste de significância produz rótulos de cluster significativos sem qualquer modelo de ML ou anotação manual. Clusters que não produzem termos significativos são incoerentes e são rebaixados a ruído, uma porta de qualidade integrada.
5. Vinculação temporal de histórias: índices diários e kNN de índice cruzado entre amostra e consulta rastreiam como as histórias evoluem ao longo do tempo.

Principais conclusões:

• O tipo de tarefa de incorporação importa: embeddings de clustering produzem grupos tópicos mensuravelmente mais compactos.
• O Elasticsearch pode atuar tanto como camada de armazenamento quanto como motor de clustering por meio da busca kNN.
• A classificação de centroides baseada em densidade mantém quase toda a computação no lado do servidor e produz clusters com tamanhos naturais determinados pela densidade do espaço de incorporação.
• significant_text é rápido, compreensível e eficaz tanto para autorrotulagem quanto para controle de qualidade.

Quando essa abordagem é útil:

• Você tem texto com carimbo de data e hora e quer descobrir tópicos sem dados de treinamento rotulados.
• Você precisa de uma plataforma para armazenamento, busca vetorial, rotulagem e ligação temporal.

Extensões para explorar:

• Clustering por múltiplos períodos (semanal, pacotes mensais).
• Ingestão em tempo real com atribuição incremental de cluster.
• Resumos de cluster gerados pelo LLM usando os termos significant_text como sementes.
• Em escala maior, centroides KMeans mostrados podem servir como sementes de aquecimento para clustering baseado em densidade, reduzindo o custo da fase da sonda.

Experimente você mesmo

Troque seu próprio corpus de documentos com carimbo de data; qualquer coleção de texto com datas funciona com esse pipeline. O notebook completo e o código de suporte estão disponíveis no repositório complementar.

• Inicie uma avaliação gratuita do Elastic Cloud: instale um cluster gerenciado com suporte bbq_disk em questão de minutos.
• Experimente o Elasticsearch Serverless: sem gerenciamento de cluster, escala automática e com suporte.

Recuperação lexical (correspondência de texto), recuperação semântica (correspondência de conceitos) e recuperação híbrida (combinação de sinais lexicais e semânticos) não resolvem esses problemas por si só. A recuperação lexical pode retornar qualquer conteúdo que contenha a palavra "laranjas", enquanto a recuperação semântica pura, em uma consulta com alta intenção como "laranjas", pode ampliar o escopo para itens relacionados, como limões ou toranjas. A recuperação híbrida mescla esses sinais lexicais e semânticos, mas ainda não determina se essa consulta deve ser tratada como uma consulta de navegação, quais restrições devem ser impostas ou quais políticas de negócios se aplicam. A lacuna não está na tecnologia de recuperação em si; está na ausência de uma camada de governança que entenda que tipo de consulta é esta e quais restrições devem ser impostas antes de a recuperação começar.

Neste blog, exploramos a governança de busca para e-commerce, por que isso é importante e como uma camada de controle garante uma recuperação previsível e precisa.

O que significa governança na busca para e-commerce

Governança, neste contexto, significa introduzir uma camada de decisão entre a consulta do usuário e o mecanismo de recuperação de dados. Esta camada realiza as seguintes funções:

• Classifica a intenção da consulta: isso é navegação ("laranjas") ou descoberta ("presente para o avô")?
• Aplica restrições comerciais: Quais limites de categoria, regras de elegibilidade, restrições de disponibilidade ou políticas de comercialização se aplicam?
• Caminhos para a estratégia apropriada: deve-se usar recuperação lexical, semântica ou híbrida?

Uma camada de governança determina qual abordagem de recuperação deve ser usada para cada consulta, quais restrições devem ser aplicadas e quais políticas de negócios devem ser aplicadas antes do início da recuperação. É importante não confundir governança com recuperação híbrida: híbrida é uma estratégia de recuperação que combina sinais lexicais e semânticos, enquanto a governança é a camada inicial de decisão que determina se deve ser usada a recuperação lexical, semântica ou híbrida.

O status quo: a implementação da camada de aplicação "spaghetti"

Atualmente, muitos varejistas tentam resolver isso inserindo lógica diretamente na camada de aplicação. Isso geralmente resulta em código espaguete, ou seja, milhares de linhas de instruções if-then fixas no código, regex e templates de busca complexos.

Essa abordagem pode fornecer resultados de busca desejados, como mostrado acima; no entanto, ela cria atritos operacionais significativos:

• Dependência da engenharia: usuários da área de negócios e a equipe de merchandising não conseguem modificar o comportamento de busca sem abrir chamados para a engenharia e enfrentar longos ciclos de implantação, que muitas vezes levam várias semanas.
• Fragmentação: a lógica de busca fica dispersa entre o código da aplicação e os modelos de busca, sendo difícil de explicar ou auditar, tornando arriscado evoluir.

Mesmo quando as equipes reconhecem a necessidade de roteamento, o debate frequentemente se concentra na questão errada: qual método de recuperação escolher.

A falsa escolha: lexical vs. semântico vs. híbrido

As equipes de busca costumam enquadrar o desafio como uma escolha de estratégia de recuperação: lexical/BM25 versus semântica/vetores versus híbrida. Esse enquadramento é compreensível (os métodos de recuperação são importantes), mas ignora a falha mais comum em implantações reais: usar uma única abordagem de recuperação para todas as consultas gera resultados abaixo do ideal.

A busca de comércio é uma combinação de intenções fundamentalmente diferentes:

• Navegação determinística e de alta intenção ("laranjas", "leite", "chocolate sem amendoim", "azeite de oliva barato").
• Descoberta exploratória ("jaqueta para caminhar nas montanhas", "presente para uma criança de 12 anos que gosta de robótica").
• Restrições operacionais (disponibilidade, tamanho, preço, cor).
• Merchandising e campanhas (impulsionar, enterrar, campanhas sazonais).

Quando o sistema encaminha todos esses elementos pela mesma estratégia de recuperação, os resultados frequentemente apresentam erros sistemáticos e previsíveis, devido à falta de governança no modelo operacional. Quando as equipes não percebem isso como uma lacuna de governança, elas recorrem à única ferramenta que possuem: mais ajustes.

Por que o "ajuste de relevância" pode se tornar cíclico

Sem uma camada de roteamento, a "relevância" frequentemente se transforma em um amontoado interminável:

• Por que essa consulta mostra acessórios acima do produto núcleo?
• Por que essa consulta principal passou a exibir itens relacionados de repente?
• Por que os resultados mudaram depois que adicionamos sinônimos, ajustamos analisadores ou ativamos a funcionalidade híbrida?
• Por que a equipe de negócios precisa de um release de engenharia para corrigir uma única consulta?

As equipes respondem com mais ajustes: mais sinônimos, mais impulsos, mais experimentos de reclassificação, mais exceções no código da aplicação. Isso pode funcionar por um tempo, mas frequentemente produz um comportamento frágil, porque o sistema ainda não possui uma camada de decisão explícita para determinar o tipo de consulta e impor as restrições corretas antes da recuperação.

A anatomia da intenção do e-commerce: cabeça e cauda

Nesta seção, usamos "cabeça" e "cauda" como abreviações práticas para padrões comuns de navegação e exploração de consultas no comércio eletrônico. No mundo real, muitas consultas contêm aspectos de ambos:

Consultas principais (intenção determinística)

São consultas diretas e navegacionais onde o usuário sabe exatamente o que quer:

• Intenção de item único ("laranjas", "leite", "pão").
• Marcas exatas ou famílias de produtos ("iPhone 15 Pro", "Coca Coke").
• SKUs, números de modelo, tamanhos ("ABC123", "Air Max 270").

Para essas consultas, a recuperação lexical pode lidar com correspondência de tokens (palavras correspondentes), mas o negócio também espera respeitar restrições, devolver rankings previsíveis e ter resultados controláveis. Um profissional de merchandising precisa garantir que uma consulta seja resolvida dentro dos limites da categoria correta, respeite os critérios de elegibilidade e destaque as prioridades específicas do negócio.

A governança é necessária para fazer cumprir a resolução pretendida. Por exemplo, "laranjas" devem corresponder à categoria de hortifrúti, não a suco de laranja, geleia de laranja ou refrigerante de laranja.

Consultas de cauda (descoberta exploratória)

São consultas descritivas e ricas em intenção, nas quais os consumidores exploram:

• "Presente para o avô que adora doces"
• "Jaqueta para caminhadas nas montanhas"
• "Sapatos para ficar em pé o dia todo"

A recuperação lexical costuma apresentar dificuldades nesse caso. A recuperação semântica se destaca porque pode conectar o conceito de consulta ao produto, mesmo quando a redação não corresponde. Mas a recuperação semântica sozinha raramente é suficiente também. Consultas reais frequentemente exigem restrições para serem aplicadas, independentemente do método de recuperação usado.

As restrições são ortogonais ao método de recuperação

Aplicar restrições à recuperação semântica não significa busca híbrida. São conceitos ortogonais. Restrições, como filtros e boosts no Elasticsearch, podem ser aplicadas a qualquer recuperação lexical, semântica ou híbrida. O desafio é decidir como a consulta deve ser interpretada, quais restrições devem ser aplicadas e qual estratégia de recuperação deve ser utilizada.

Abaixo estão alguns exemplos de consultas que combinam recuperação com restrições rígidas:

• Laranjas: recuperação lexical para "laranjas" mais uma restrição de categoria, como "Frutas" ou "Produtos", eliminando geleia de laranja, suco de laranja e refrigerante de laranja.
• Frutas com alto teor de vitamina C por menos de US$ 4: recuperação semântica com foco em intenção nutricional, além de restrições que limitam os resultados à categoria de frutas e produtos por menos de US$ 4.
• Sapatos confortáveis para trabalhar: recuperação semântica para intenção contextual mais uma restrição de categoria que limita os resultados a sapatos.

Essas consultas não podem ser tratadas por uma única abordagem:

• A recuperação lexical pura geralmente é insuficiente aqui porque frases como "rico em vitamina C" ou "confortável" podem não existir como atributos bem definidos e estruturados. Talvez seja necessário inferi-las a partir de descrições, análises ou especificações do produto.
• A recuperação semântica pura também nem sempre é suficiente, pois, sem restrições explícitas, uma consulta como "frutas ricas em vitamina C" pode se expandir para suplementos vitamínicos, bebidas com sabor de frutas ou vegetais ricos em vitaminas fora da categoria e faixa de preço pretendidas.

Uma camada de governança determina se uma consulta precisa de recuperação lexical, compreensão semântica, aplicação de restrições ou alguma combinação dessas. Sem essa camada, as equipes de comércio eletrônico podem acabar:

• Excesso de restrições: usar a recuperação lexical para pedidos semânticos (por exemplo, "presente para o avô").
• Sub-restrição: utilizar consultas semânticas para consultas principais de alta intenção (por exemplo, "laranjas").

O desafio da governança é construir um sistema que possa tomar a decisão correta para cada classe de consulta.

O que acontece sem governança

O modo de falha mais comum é simples: as equipes pegam a consulta bruta do usuário e a encaminham diretamente para uma única estratégia de recuperação (lexical, semântica ou híbrida), sem uma camada intermediária de governança.

A recuperação lexical falha na resolução pretendida

Quando um usuário pesquisa por “laranjas”, uma estratégia de recuperação lexical pode retornar qualquer resultado que contenha esse token: suco de laranja, geleia de laranja ou refrigerante de laranja. O sistema encontrou o termo corretamente, mas, sem governança, pode não resolver o contexto de compra pretendido (a fruta).

A recuperação semântica se expande além das restrições pretendidas

Quando um usuário busca por "laranjas", um sistema semântico pode recuperar itens conceitualmente relacionados entre conceitos de produtos próximos. O sistema pode entender corretamente o domínio mais amplo (frutas ou produtos), mas, sem uma governança explícita, ele ainda pode se expandir além da restrição pretendida pelo usuário (especificamente laranjas).

A lacuna é a governança

O que é necessário é uma camada de decisão a montante que determine a intenção da consulta e impeça as restrições corretas antes do início da recuperação. Isso resolve questões como:

• Itens semelhantes ou relacionados aparecendo ao lado do que o usuário realmente queria.
• Limites de categorias desfocados ("bebidas" versus. "produtos").
• Incapacidade de implementar aumentos sazonais ou campanhas.
• Resultados imprevisíveis e inexplicáveis.

Compreensão e roteamento de intenções: o plano de controle necessário

Um sistema de busca governado introduz um plano de controle leve antes da recuperação (antes de executar uma consulta no Elasticsearch). O controle será discutido em detalhes nas partes 3 e 4 desta série de blog; por enquanto, discutiremos apenas o que ele pode fazer, mas não como funciona:

Um plano de controle pode detectar intenção, aplicar políticas de negócio e garantir a estratégia de recuperação apropriada da seguinte forma:

1. Detectar sinais de intenção

• Essa consulta é provavelmente navegação versus descoberta?
• É uma consulta conhecida como principal (leite, pão, bananas)?
• Existe uma interpretação conhecida de produto, marca ou categoria (por exemplo, "laranjas" deve ser interpretado como hortifrúti).
• A consulta segue um padrão semelhante ao SKU?
• A consulta se enquadra em uma campanha ativa ou em uma política sazonal (por exemplo, durante o Natal, aumentar os resultados relacionados a peru)?
• A consulta implica alguma restrição (categoria, atributos, exclusões, preço/tamanho/cor)?

2. Aplicar governança e políticas de negócios

• Aplique primeiro as restrições determinísticas (categoria/atributo/negação/disponibilidade).
• Aplique políticas de comercialização ativas (impulsionar/enterrar/fixar/substituir).
• Resolva conflitos com regras de precedência (por exemplo, substituições de campanhas versus políticas globais).

3. Encaminhar para a estratégia de recuperação apropriada

• Lexical (rápido, determinístico) para consultas de navegação/de alta intenção.
• Recuperação semântica para consultas verdadeiras de descoberta.
• Híbrido onde sinais lexicais e semânticos combinados agregam valor sob restrições explícitas de negócios.

Na prática, a saída do plano de controle não é simplesmente “usar híbrido” ou “usar semântico”. Trata-se de um plano de recuperação de compras controlado: uma interpretação da intenção do comprador, das restrições e políticas que devem ser aplicadas e da estratégia de recuperação que deve ser executada. Alguns exemplos simples tornam isso concreto:

Um plano de controle seleciona a política e a estratégia de recuperação adequadas para cada consulta de forma consistente, previsível e em escala. Isso torna os métodos avançados de recuperação mais previsíveis em produção porque as restrições alinhadas à intenção são aplicadas primeiro e as decisões de roteamento são explícitas, em vez de implícitas.

Como isso se relaciona com outras abordagens

Algumas equipes usam modelos de incorporação aprimorados para capturar melhor a semântica do produto, o que pode melhorar substancialmente a qualidade da recuperação semântica. Outros utilizam abordagens de reclassificação, como o Learning To Rank (LTR), para otimizar a ordenação dos resultados com base em engajamento ou sinais de negócio após a recuperação. Ambos são valiosos e frequentemente complementares. Embeddings melhores melhoram a correspondência de similaridade. A reclassificação melhora a ordem entre os candidatos recuperados.

A governança aborda uma camada diferente do problema: ela se situa antes da recuperação de dados. Ela decide qual estratégia de recuperação usar (por exemplo, lexical, semântica ou híbrida), quais restrições determinísticas são necessárias e quais consultas devem combinar várias políticas de negócios.

O que um plano de controle governado permite

Depois que uma camada de governança é implementada, o modelo operacional muda de forma fundamental. Consultas de busca críticas para a receita se tornam previsíveis. As equipes de negócios podem atualizar o comportamento de busca sem precisar esperar pelos ciclos de release da engenharia. E métodos avançados de recuperação, como a semântica e a híbrida, podem ser adotados de forma incremental, com roteamento e mecanismos de proteção, em vez de uma chave liga/desliga global.

O próximo post desta série explora como esse modelo operacional funciona na prática e por que ele pode ser tão importante quanto a tecnologia de retrieval que está por trás dele.

Se um comerciante precisar abrir um ticket do Jira e esperar por uma implantação para corrigir uma consulta crítica de receita, o gargalo não é o mecanismo; é o modelo operacional. A pesquisa moderna de comércio eletrônico precisa de uma forma de traduzir a intenção comercial em um comportamento de pesquisa controlado e auditável de forma rápida e segura, sem deixar de usar a recuperação avançada, que agrega valor mensurável.

O que vem a seguir nesta série

Os padrões explorados nesta série operam antes da recuperação: traduzindo a intenção comercial na estratégia de consulta correta antes do início da geração da consulta. No próximo post, passamos do problema técnico para o operacional: o que acontece quando equipes de negócios conseguem mudar o comportamento de busca sem uma implantação de engenharia, e por que a governança torna isso seguro.

Coloque em prática o buscar governado de comércio eletrônico

Gargalos de engenharia, lógica frágil da camada de aplicativos e resultados de busca imprevisíveis são problemas que a Elastic Services pode ajudar a resolver em contratos de serviços de comércio eletrônico corporativo. A arquitetura do plano de controle governado descrita nesta série foi construída pela Elastic Services Engineering.

Se sua equipe está gastando ciclos de engenharia traduzindo solicitações de merchandising em alterações de código, ou se o backlog de relevância de buscar nunca parece diminuir, podemos ajudá-lo a avaliar sua arquitetura atual e construir um caminho para uma buscar governada e editável pela área de negócios. Entre em contato com Elastic Services.

Participe da discussão

Tem dúvidas sobre governança de buscar, estratégias de recuperação ou arquitetura de buscar para e-commerce? Participe da conversa mais ampla da comunidade Elastic.

Recentemente, contribuímos para o projeto open source mastra-ai/mastra adicionando suporte ao Elasticsearch como banco de dados vetorial. Com esse novo recurso, você pode usar o Elasticsearch nativamente no Mastra para armazenar embeddings. Além dos vetores, o Elasticsearch oferece um conjunto de recursos avançados para atender a todos os seus requisitos de engenharia de contexto. (por exemplo, busca híbrida e reranking).

Este artigo detalha a criação de um agente para implementar uma arquitetura de retrieval augmented generation (RAG) usando o Elasticsearch. Vamos apresentar um projeto de demonstração onde uma abordagem agentiva é usada para interagir com um corpus de dados de filmes de ficção científica armazenados no Elasticsearch. O projeto está disponível em elastic/mastra-elasticsearch-example.

Mastra

Mastra é um framework TypeScript para criar aplicações de IA com agentes.

A estrutura do projeto em Mastra é a seguinte:

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

No Mastra, você pode criar agentes, ferramentas, fluxos de trabalho e métricas.

Um agente é uma classe que aceita uma mensagem na entrada e produz uma resposta como saída. Um agente pode usar ferramentas, grandes modelos de linguagem (LLMs) e uma memória (figura 1).

As ferramentas de um agente permitem que ele interaja com o "mundo externo", como se comunicar com uma API web ou realizar uma operação interna, como consultar o Elasticsearch. O componente de memória é essencial para armazenar o histórico das conversas, incluindo entradas e saídas anteriores. Esse contexto armazenado permite que o agente forneça respostas mais informadas e relevantes para futuras perguntas utilizando suas interações passadas.

Os fluxos de trabalho permitem que você defina sequências complexas de tarefas usando etapas claras e estruturadas, em vez de depender do raciocínio de um único agente (figura 2). Eles dão controle total sobre como as tarefas são divididas, como os dados circulam entre elas e o que é executado e quando. Os fluxos de trabalho são executados usando o mecanismo de execução integrado por padrão ou podem ser implantados em executores de fluxo de trabalho.

No Mastra, você também pode definir métricas, que são testes automatizados para avaliar as saídas dos agentes usando métodos baseados em modelos, regras e estatísticas. Os avaliadores retornam métricas: valores numéricos (normalmente entre 0 e 1) que quantificam o quanto uma saída atende aos seus critérios de avaliação. Essas métricas permitem que você acompanhe objetivamente o desempenho, compare diferentes abordagens e identifique áreas de melhoria em seus sistemas de IA. Os avaliadores podem ser personalizados com seus próprios prompts e funções de métrica.

Elasticsearch

Para executar o projeto de demonstração, precisamos ter uma instância do Elasticsearch em execução. Você pode ativar um teste gratuito no Elastic Cloud ou instalá-lo localmente usando o script start-local:

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

Isso instalará o Elasticsearch e o Kibana no seu computador e gerará uma chave API para ser usada na configuração da integração Mastra.

A chave API será mostrada como saída do comando anterior e armazenada em um arquivo .env na pasta elastic-start-local.

Instalar e configurar a demonstração

Criamos um repositório elastic/mastra-elasticsearch-example contendo o código-fonte do projeto de demonstração. O exemplo relatado no repositório ilustra como criar um agente no Mastra que implementa uma arquitetura RAG para recuperar documentos do Elasticsearch.

Fornecemos um conjunto de dados para a demonstração sobre filmes de ficção científica. Extraímos 500 filmes do conjunto de dados IMDb no Kaggle.

O primeiro passo é instalar as dependências do projeto com npm, usando o seguinte comando:

npm install

Então precisamos configurar o arquivo .env que conterá as configurações. Podemos gerar esse arquivo copiando a estrutura do arquivo .env.example, usando o seguinte comando:

cp .env.example .env

Agora podemos editar o arquivo .env, adicionando as informações que faltam:

OPENAI_API_KEY=
ELASTICSEARCH_URL=
ELASTICSEARCH_API_KEY=
ELASTICSEARCH_INDEX_NAME=scifi-movies

O nome do índice do Elasticsearch é scifi-movies. Se quiser, pode mudar usando a variável de ambiente ELASTICSEARCH_INDEX_NAME.

Usamos a OpenAI como serviço de embeddings, o que significa que você precisa fornecer uma chave de API para a OpenAI na variável de ambiente OPENAI_API_KEY.

O modelo de embedding usado no exemplo é openai/text-embedding-3-small, com uma dimensão de embedding de 1.536.

Para gerar a resposta final, utilizamos o modelo openai/gpt-5-nano para reduzir os custos.

A arquitetura RAG permite que você use um modelo LLM final menos potente (e normalmente mais barato) porque o trabalho pesado de fundamentar a resposta é feito pelo componente de recuperação (Elasticsearch, neste caso).

O LLM menor é responsável apenas por duas tarefas principais:

• Reformulação/embedding da consulta: conversão da pergunta do usuário em linguagem natural em um vetor de embedding para busca semântica.
• Sintetização da resposta: pegar os fragmentos de contexto recuperados e altamente relevantes (documentos/filmes) e sintetizá-los em uma resposta coerente, final e legível por humanos, seguindo as instruções do prompt fornecido.

Como o processo RAG fornece o contexto factual exato necessário para a resposta, o LLM final não precisa ser massivo ou altamente complexo, nem precisa possuir todo o conhecimento necessário dentro de seus próprios parâmetros (é aí que modelos grandes e caros se destacam). Basicamente, ele atua como um sofisticado resumidor e formatador de texto para o contexto fornecido pelo Elasticsearch, e não como uma base de conhecimento completa em si. Isso permite o uso de modelos como gpt-5-nano para otimização de custos e latência.

Após a configuração do arquivo .env, você pode fazer a ingestão dos filmes no Elasticsearch usando o seguinte comando:

npx tsx src/utility/store.ts

Você deve ver uma saída da seguinte forma:

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

O mapeamento do índice de filmes de ficção científica contém os seguintes campos:

• embedding, dense_vector com dimensão de 1.536, similaridade cosseno.
• description, texto contendo a descrição do filme.
• director, texto contendo o nome do diretor.
• título, texto contendo o título do filme.

Geramos os embeddings usando o título e a descrição. Como o título e a descrição são dois campos separados, a concatenação de ambos garante que o vetor de embedding resultante capture tanto a identidade específica e única (título) quanto o contexto rico e descritivo (descrição) do filme, resultando em buscas semânticas mais precisas e abrangentes. Essa entrada combinada oferece ao modelo de embedding uma representação mais adequada do conteúdo do documento para comparação de similaridade.

Execute a demonstração

Você pode executar a demonstração com o seguinte comando:

npm run dev

Esse comando iniciará uma aplicação web em localhost:4111 para acessar o Mastra Studio (Figura 3).

O Mastra Studio oferece uma interface de usuário interativa para criar e testar seus agentes, além de uma REST API que expõe seu aplicativo Mastra como um serviço local. Isso permite que você comece a trabalhar imediatamente, sem se preocupar com integração.

Fornecemos um Agente Elasticsearch que utiliza o createVectorQueryTool da Mastra como ferramenta para executar busca semântica usando Elasticsearch. Esse agente utiliza a abordagem RAG para buscar documentos relevantes (ou seja, filmes) para responder à pergunta do usuário.

Este agente usa o seguinte prompt:

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

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

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

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

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

Se você clicar no menu Mastra Studio > Agents e selecionar Agente Elasticsearch, pode testar o agente usando um sistema de chat. Por exemplo, você pode pedir informações sobre filmes de ficção científica com a seguinte pergunta:

Encontre 5 filmes ou séries de TV sobre OVNIs.

Você notará que o agente executará a ferramenta vectorQueryTool. Você pode clicar na ferramenta invocada para visualizar a entrada e a saída. Ao final da execução, o LLM responderá à sua pergunta, considerando o contexto do índice de filmes de ficção científica do Elasticsearch (figura 4).

O Mastra executa internamente os seguintes passos:

1. Conversão de vetor: A pergunta do usuário, Encontre 5 filmes ou séries de TV sobre OVNIs, é convertida em uma incorporação vetorial usando o modelo openai/text-embedding-3-small da OpenAI.
2. Busca vetorial: este embedding é então usado para consultar o Elasticsearch por meio de uma busca vetorial.
3. Recuperação do resultado: o Elasticsearch retorna um conjunto de 10 filmes altamente relevantes para a consulta (ou seja, aqueles cujos vetores estão mais próximos do vetor de consulta do usuário).
4. Geração de respostas: os filmes recuperados e a pergunta original do usuário são enviados para o LLM, especificamente openai/gpt-5-nano. O LLM processa essas informações e gera uma resposta final, garantindo que o pedido do usuário por cinco resultados seja atendido.

O Agente Elasticsearch

Aqui apresentamos o código-fonte do agente Elasticsearch.

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

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

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

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

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

O vectorQueryTool é a ferramenta que é invocada para implementar a parte de recuperação do exemplo RAG. Ele utiliza a implementação ElasticSearchVector que a Elastic contribuiu para o Mastra.

O agente é um objeto da classe agent que utiliza o vectorQueryTool, o prompt e uma memória. Como você pode ver, o código que precisamos colocar em prática para conectar o Elasticsearch a um agente é mínimo.

Conclusão

Este artigo demonstrou a simplicidade e o poder de integrar o Elasticsearch ao framework Mastra para criar aplicações sofisticadas de IA agentiva. Especificamente, detalhamos a criação de um agente RAG capaz de realizar busca semântica em um corpus de dados de filmes de ficção científica indexados no Elasticsearch.

O principal aprendizado é a contribuição direta da Elastic para o projeto open source Mastra, fornecendo suporte nativo para o Elasticsearch como um repositório vetorial. Essa integração reduz significativamente a barreira de entrada, como demonstra o código-fonte do Elasticsearch Agent. Usando o ElasticSearchVector e createVectorQueryTool, a configuração completa para conectar o Elasticsearch ao seu agente exige apenas algumas linhas de código de configuração.

O Elasticsearch oferece vários recursos avançados para aumentar a relevância dos resultados. Por exemplo, a busca híbrida aumenta significativamente a precisão ao combinar a busca lexical com a busca vetorial. Outro recurso interessante é a reclassificação usando os modelos Jina mais recentes, que podem ser aplicados ao final da busca híbrida. Para saber mais sobre essas técnicas, consulte os seguintes artigos do Elasticsearch Labs:

• Busca híbrida do Elasticsearch por Valentin Crettaz
• Uma introdução aos modelos Jina, sua funcionalidade e seus usos no Elasticsearch por Scott Martens

Também incentivamos você a explorar o exemplo fornecido e começar a construir seus próprios agentes baseados em dados com Mastra e Elasticsearch. Para mais informações sobre o Mastra, você pode consultar a documentação oficial aqui.

O Elastic Workflows é um mecanismo de automação integrado dentro do Kibana que permite definir processos de várias etapas usando uma simples configuração YAML. Cada fluxo de trabalho pode ser acionado em um cronograma ou evento ou como uma ferramenta no Elastic Agent Builder, e cada etapa pode chamar APIs do Kibana, consultar o Elasticsearch ou transformar dados.

Vamos usar as contagens de visualização de dashboards como um exemplo concreto, mas o mesmo padrão se aplica a qualquer métrica exposta pela API de objetos salvos do Kibana.

Pré-requisitos

• Elastic Cloud ou cluster autogerenciado executando a versão 9.3
• Fluxos de trabalho ativados (Configurações avançadas)

Antes de construir qualquer coisa, vamos entender quais dados temos. O Kibana armazena a maior parte de sua configuração e metadados como objetos salvos em um índice interno dedicado. Uma das coisas que o Kibana monitora dessa forma são as contagens de visualizações do dashboard, usando um tipo especial de objeto salvo chamado contadores de uso. Você pode consultá-los diretamente pelas Ferramentas de Desenvolvimento:

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

A resposta tem aparência semelhante a esta:

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

O campo counterName é o ID do dashboard, e count é a contagem cumulativa de visualizações para aquele dashboard naquele dia específico. Kibana cria um objeto contador por dashboard por dia; você pode ver o sufixo de data no ID do objeto (... visualizado:servidor:20260310). A contagem cresce ao longo do dia à medida que os usuários abrem o dashboard.

Em vez de replicar esse modelo de documento diário em nosso índice, criaremos um documento por execução de fluxo de trabalho. Cada documento registra quantas visualizações aquele dashboard acumulou no dia no momento da captura.

Passo 2: criar o índice de destino

Precisamos de um índice para armazenar os snapshots da vista do nosso dashboard. O comando a seguir cria com mapeamentos explícitos para que possamos agregar e visualizar depois. Execute isso nas ferramentas de desenvolvimento:

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

O uso de mapeamentos keyword para IDs e nomes permite agregações. Usar integer para view_count é um padrão seguro, já que o Kibana reinicia o contador diariamente e atingir o limite de 32 bits (mais de 2 bilhões de visualizações em um único dia) não é uma preocupação realista. Ainda permite operações numéricas, como max, avg e min, entre outras.

Passo 3: Crie o fluxo de trabalho

Acesse Stack Management > Fluxo de trabalho > Novo Fluxo de Trabalho e cole a seguinte configuração YAML do fluxo de trabalho:

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

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

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

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

Na próxima seção, vamos analisar o fluxo de trabalho passo a passo.

Como funciona o fluxo de trabalho

Gatilhos

O fluxo de trabalho é executado com um gatilho programado a cada 30 minutos. Isso nos fornece dados de séries temporais sem sobrecarregar a API.

buscar_visualizações_do_painel

Usa kibana.request para chamar a API de objetos salvos do Kibana. Não é necessário configurar autenticação: o motor de fluxo de trabalho anexa automaticamente os cabeçalhos corretos com base no contexto de execução.

index_each_dashboard (foreach)

Itera sobre o array saved_objects retornado pela etapa anterior. O item atual em cada iteração está disponível como foreach.item. Dentro do loop, executamos duas etapas aninhadas para cada dashboard.

1. fetch_dashboard_name:

Resolve o título do dashboard legível por humanos chamando GET /api/saved_objects/dashboard/{id}. Adicionamos on-failure: continue: true para que, se um dashboard for excluído mas ainda tiver contadores de visualização, o loop continue em vez de falhar toda a execução.

2. index_doc:

Indexa cada documento usando POST /dashboard-views/_doc (sem um ID explícito), o que permite que o Elasticsearch gere IDs automaticamente. Isso cria um novo documento a cada execução, construindo um histórico de contagens de visualizações ao longo do tempo, em vez de sobrescrever o snapshot anterior.

Duas coisas que valem a pena notar:

• O campo captured_at usa o filtro de data para formatar o carimbo de data/hora como ISO 8601. Sem isso, o valor aparece como uma string de data em JavaScript, como Tue Mar 10 2026 05:03:47 GMT+0000, que o Elasticsearch não mapeia como data.
• O view_count usa a sintaxe ${{ }} com | plus: 0 para preservar o tipo numérico. Usar {{ }} o renderizaria como uma string, o que impediria operações matemáticas no dashboard.

A UI permite que você depure cada uma das etapas do fluxo de trabalho.

Etapa 4: Crie o dashboard de estatísticas

Depois que o fluxo de trabalho for executado algumas vezes e os dados forem coletados, crie um novo dashboard no Kibana usando a Data view dashboard-views.

Alguns painéis para começar:

• Principais dashboards por visualizações: use um gráfico de barras com dashboard_name no eixo X e last_value(view_count) no eixo Y. Isso mostra a contagem diária atual de visualizações por dashboard.
• Visualizações ao longo do tempo: use um gráfico de linhas com captured_at no eixo X e last_value(view_count) no eixo Y, dividido por dashboard_name. Como cada execução adiciona um novo documento, use o último valor para obter a contagem de picos por buckets, em vez de somar duplicados.
• Snapshot atual: use uma tabela de dados com os captured_at mais recentes para mostrar as contagens de visualizações mais recentes em todos os dashboards.

Como cada fluxo de trabalho cria um novo documento, você pode filtrar por faixa de tempo para analisar a atividade em períodos específicos, comparar semana a semana ou criar alertas quando um dashboard cair abaixo de um limite de visualização.

Conclusão

O Elastic Workflows é uma boa opção para esse tipo de coleta periódica de dados porque tanto a fonte (Kibana API) quanto o destino (Elasticsearch) são nativos, o que significa zero gerenciamento de credenciais. O motor de fluxo de trabalho lida automaticamente com autenticação para kibana.request e elasticsearch.request etapas, então a única coisa que você escreve é a lógica.

Recursos

• Elastic Workflows
• API do Kibana

O Elasticsearch estava rejeitando métricas de chegada tardia. Essas rejeições fizeram o pipeline ficar atrasado, resultando em dados mais tardios, o que desencadeou ainda mais rejeições. Com o tempo, o pipeline parou completamente.

Tivemos que restaurar a partir do snapshot, reindexar os dados e redesenhar o pipeline de ingestão para recuperar.

A causa raiz não era a gestão de ciclo de vida de índices (ILM) em si. Tratava-se de fluxos de dados de séries temporais (TSDS) e como eles aplicam índices de apoio com limite temporal.

O TSDS pode reduzir os requisitos de armazenamento para métricas em 40–70%, mas as mudanças na arquitetura que tornam o TSDS eficiente também alteram a forma como os índices se comportam ao longo do tempo. Essas mudanças são importantes ao projetar políticas de ILM ou quando seus pipelines de ingestão podem produzir dados tardios.

TL;DR

Ao usar o TSDS:

• Índices de suporte aceitam apenas documentos dentro de uma janela de tempo específica.
• Se dados tardios chegarem após um índice se tornar frio ou congelado, o Elasticsearch rejeitará esses documentos ou os encaminhará para o armazenamento de falhas, caso esteja configurado.

Regra de design:

warm_min_age > rollover_max_age + maximum_expected_lateness

O que é um fluxo de dados de séries temporais?

Um fluxo de dados de série temporal (TSDS) é um fluxo de dados especializado otimizado para dados métricos. Os dados são roteados de modo que documentos relacionados fiquem localizados dentro dos mesmos fragmentos, otimizando-os para consulta e recuperação. Como o Elasticsearch faz isso:

Cada documento contém:

• Um registro de data e hora.
• Campos dimensionais que identificam a série de tempo.
• Campos métricos representando valores medidos.

Alguns exemplos:

• Uso da CPU por host.
• Solicitar latência por serviço.
• Leituras de temperatura por sensor.

As dimensões identificam o que queremos medir, enquanto as métricas representam valores que mudam com o tempo.

Dimensões

Dimensões descrevem a entidade medida.

Exemplos:

host.name
service.name
container.id

Definimos eles em mapeamentos com:

time_series_dimension: true

Métricas

Métricas representam valores numéricos e são definidas usando:

time_series_metric

Tipos comuns de métricas:

• Indicador: Valores que sobem e descem.
• Contador: valores que aumentam até serem reiniciados.

O Elastic Agent coleta principalmente métricas e dados de log. Mesmo que você não tenha habilitado manualmente nenhum índice TSDS, ainda pode tê-los no seu cluster.

O campo _tsid

O Elasticsearch gera internamente um valor _tsid a partir dos campos de dimensão. Isso permite que documentos com dimensões idênticas sejam roteados para o mesmo shard, melhorando:

• Compressão.
• Local da consulta.
• Desempenho de agregações.

A principal diferença: índices de apoio com prazo definido

Os fluxos de dados tradicionais sempre gravam no índice de suporte mais recente, chamado índice de gravação, mas o TSDS se comporta de maneira diferente.

Cada índice de apoio TSDS tem uma janela de tempo definida e aceita apenas documentos com @timestamp valores que se encaixam nessa janela:

GET _data_stream/my-metrics-data-stream


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

Quando um documento é indexado, o Elasticsearch encaminha o documento para o índice de suporte responsável por aquele timestamp, o que significa que, ao contrário dos índices tradicionais, um TSDS pode gravar em vários índices de suporte simultaneamente.

Por exemplo:

• Dados em tempo real → índice mais recente.
• Dados tardios → índice anterior cobrindo esse intervalo de tempo.

Projetando para dados tardios

Os pipelines de ingestão reais raramente entregam métricas perfeitamente no prazo. As métricas podem ser atrasadas por interrupções de rede, acúmulos no caminho, ingestão em lote e perda de dispositivos de borda, que se reconectam e começam a recuperar o atraso.

Índices tradicionais absorvem silenciosamente esses atrasos. O TSDS não.

Se o carimbo de data/hora de um documento estiver fora da faixa de índices de apoio graváveis, o Elasticsearch o rejeitará, o que significa que sua política de ILM deve considerar os dados tardios.

A restrição crítica

Os índices de suporte precisam permanecer com permissão de escrita por tempo suficiente para receber dados com atraso.

Em termos práticos:

time_until_readonly > maximum_expected_lateness

Como o ILM mede o tempo de existência a partir do rollover, a regra operacional passa a ser:

warm_or_cold_min_age > rollover_max_age + maximum_expected_lateness

Por exemplo, se as métricas podem chegar até seis horas atrasadas, os índices devem permanecer graváveis pelo menos seis horas após o rollover.

Desconsiderar essa restrição foi exatamente o que causou a falha de ingestão descrita anteriormente. Os dados tardios eram direcionados para um índice anterior, que já estava na camada cold e, portanto, era bloqueado para escrita.

Tratamento de documentos rejeitados

Quando o TSDS rejeita um documento, o Elasticsearch retorna um erro, indicando que o carimbo de data e hora não está dentro da faixa de índices graváveis. Como seu pipeline de ingestão lida com esse erro determina se você perde dados ou trava a ingestão de dados.

O principal mecanismo para lidar com documentos rejeitados é o armazenamento de falhas.

Repositório de falhas (recomendado no Elasticsearch 9.1+)

O Elasticsearch 9.1 introduziu o armazenamento de falhas, que captura automaticamente documentos rejeitados. Em vez de retornar erros aos clientes, o Elasticsearch grava documentos rejeitados em um índice dedicado de falhas dentro do fluxo de dados.

Você pode inspecionar falhas usando:

GET metrics-myapp::failures/_search

O uso do armazenamento de falhas impede que os pipelines de ingestão travem devido a erros de rejeição, enquanto preserva os dados com falha para análise ou reindexação.

Monitoramento de questões de rejeição

Os problemas de chegada tardia geralmente aparecem primeiro como anomalias de ingestão. Você pode notá-los primeiro como:

• Quedas repentinas na taxa de indexação.
• Picos nos documentos rejeitados.
• Um número crescente de entradas de lojas que falham.
• Diferenças de incompatibilidade entre entradas e saídas do pipeline contagem.

Alertas nesses sinais permitem que os operadores detectem problemas antes que os pipelines parem. Fluxos de trabalho, trabalhos de Machine Learning e outros mecanismos podem ser usados para automatizar a detecção e notificação.

Lista de verificação de migração para TSDS + ILM

Se você estiver migrando um cluster de métricas para o TSDS, introduzindo a hierarquização do ILM ou atualizando para uma versão do Elasticsearch em que as métricas são TSDS por padrão, revise esses itens primeiro.

1. Medir a latência de ingestão

Antes de mudar as políticas de ILM, determine:

• Atraso normal na ingestão de dados.
• Pior caso de atraso durante os incidentes.
• Atrasos causados por pipelines em lote.

O projeto do seu ILM deve acomodar o máximo de atraso realista.

2. Verificar as janelas de tempo do índice

Inspecione seus índices de respaldo de TSDS:

GET _data_stream/

Analise:

• time_series.start_time
• time_series.end_time

Esses limites determinam quais índices podem aceitar documentos. Entender essas janelas pode ajudar a determinar o quanto os dados podem estar atrasados antes de serem rejeitados.

3. Dimensione o nível hot para chegadas tardias

Garanta que os índices backing permaneçam graváveis por tempo suficiente para os dados tardios.

Regra operacional:

• warm_min_age > rollover_max_age + maximum_expected_lateness

Lembre-se, os índices devem permanecer graváveis por pelo menos seis horas se as métricas chegarem com seis horas de atraso.

4. Decida o que fazer com documentos rejeitados

Escolha uma estratégia antes de ativar o TSDS:

• Armazenamento de falhas (recomendado no Elasticsearch 9.1+).
• Fila de dead letter do Logstash.
• Índice de contingência para chegadas tardias.
• Aceitar a perda limitada de dados.

5. Monitorar a saúde da ingestão

Adicionar alertas para:

• A taxa de indexação cai.
• Documentos rejeitados.
• Crescimento do armazenamento de falhas.
• Desajustes de entrada/saída do pipeline.

Problemas de dados tardios geralmente aparecem primeiro como anomalias de ingestão.

Resumo

Fluxos de dados de séries temporais oferecem grandes melhorias de armazenamento e desempenho para cargas de trabalho de métricas, mas introduzem uma mudança arquitetônica importante: os índices de suporte têm limite temporal, o que afeta o comportamento do ILM.

Ao usar o TSDS:

• Os índices devem permanecer graváveis tempo suficiente para aceitar dados tardios.
• Os pipelines de ingestão devem lidar com documentos rejeitados com segurança.

A regra fundamental a lembrar é:

warm_min_age > rollover_max_age + maximum_expected_lateness

Se você projetar políticas de ILM em torno dessa restrição, o TSDS funcionará extremamente bem para cargas de trabalho de métricas.

Se ignorar isso, seu pipeline de ingestão pode descobrir esses limites de tempo da pior forma.

Sua primeira consulta

Comece definindo um objeto CLR simples (POCO) que mapeia para o seu índice Elasticsearch. Os nomes das propriedades são resolvidos para nomes de coluna ES|QL via atributos System.Text.Json padrão, como [JsonPropertyName], ou via JsonNamingPolicy configurado. As mesmas regras de serialização de origem que se aplicam ao restante do cliente também se aplicam aqui.

using System.Text.Json.Serialization;

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

    public string Name { get; set; }

    public string Brand { get; set; }

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

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

Com o tipo definido, uma consulta fica assim:

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

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

O provedor traduz isso para o seguinte ES|QL:

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

Há alguns detalhes a serem observados:

• Resolução do nome da propriedade: p.Price se torna price_usd por causa do atributo [JsonPropertyName], e p.Brand se torna brand seguindo a política de nomenclatura padrão camelCase.
• Captura de parâmetros: As variáveis C# minPrice e brand são capturadas como parâmetros nomeados (?minPrice, ?brand). Eles são enviados separadamente da string de consulta na carga JSON, o que evita injeções e permite o armazenamento em cache do plano de consulta no lado do servidor.
• Streaming: QueryAsync<T> retorna IAsyncEnumerable<T>. As linhas são materializadas uma de cada vez à medida que chegam do Elasticsearch.

Você também pode inspecionar a consulta gerada e seus parâmetros sem executá-la:

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

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

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

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

Como funciona? Uma breve revisão sobre o LINQ

O mecanismo que torna possíveis os provedores LINQ é a distinção entre IEnumerable<T> e IQueryable<T>.

Quando você chama .Where(p => p.Price > 100) em um IEnumerable<T>, o lambda compila para um Func<Product, bool>, um delegado regular que o runtime executa em processo. Isto é LINQ-to-Objects.

Quando você chama o mesmo método em um IQueryable<T>, o compilador C# envolve o lambda em um Expression<Func<Product, bool>> em vez disso. Essa é uma estrutura de dados que representa a estrutura do código em vez de sua forma executável. A árvore de expressões pode ser inspecionada, analisada e traduzida para outra linguagem em tempo de execução.

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

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

A interface IQueryProvider é o ponto de extensão. Qualquer provedor pode implementar CreateQuery<T> e Execute<T> para traduzir essas árvores de expressão para um idioma de destino. O Entity Framework usa isso para emitir SQL. O provedor LINQ to ES|QL o usa para emitir ES|QL.

A árvore de expressões para a consulta acima fica assim:

Árvore de expressões para a consulta de exemplo.

A árvore é aninhada do avesso: Take envolve OrderByDescending, que envolve Where, que envolve From, que envolve a raiz EsqlQueryable<Product> constante. O predicado Where é ele próprio uma subárvore de BinaryExpression nós para os operadores &&, >= e ==, com folhas MemberExpression para acessos a propriedades e capturas de fechamento para as variáveis minPrice e brand. Essa é a estrutura de dados que o provedor percorre para produzir o ES|QL final.

Nos bastidores: O pipeline de tradução

O caminho de uma expressão LINQ até os resultados da consulta segue um pipeline de seis estágios:

Visão geral do pipeline de tradução.

1. Captura da árvore de expressão

Quando você encadeia .Where(), .OrderBy(), .Take() e outros operadores em um IQueryable<T>, a infraestrutura padrão do LINQ constrói uma árvore de expressões. EsqlQueryable<T> implementa IQueryable<T> e delega para EsqlQueryProvider.

2. Tradução

Quando a consulta é executada (enumerando, chamando ToList() ou usando await foreach)), o EsqlExpressionVisitor percorre a árvore de expressões de dentro para fora. Ele despacha cada chamada de método LINQ para um visitante especializado:

Durante a tradução, as variáveis C# referenciadas em expressões são capturadas como parâmetros nomeados.

3. Modelo de consulta

Os visitantes não produzem diretamente as strings. Em vez disso, produzem QueryCommand objetos, uma representação intermediária imutável. Um FromCommand, um WhereCommand, um SortCommand, e um LimitCommand, cada um representando um comando de processamento ES|QL. Eles são coletados para um modelo EsqlQuery.

Modelo de consulta e padrão de comando.

Esse modelo intermediário é desacoplado tanto da árvore de expressão quanto do formato de saída. Ele pode ser inspecionado, interceptado (via IEsqlQueryInterceptor) ou modificado antes da formatação.

4. Formatação

EsqlFormatter visita cada QueryCommand em ordem e gera a string final do ES|QL. Cada comando se transforma em uma linha, separada pelo operador pipe (|), que o ES|QL utiliza para encadear comandos de processamento. Identificadores que contêm caracteres especiais são automaticamente escapados com backticks.

5. Execução

A string ES|QL formatada e os parâmetros capturados são enviados para o endpoint /_query do Elasticsearch no corpo da requisição, como JSON. A interface IEsqlQueryExecutor abstrai a camada de transporte, e é aí que a arquitetura de pacotes em camadas se aplica.

6. Materialização

EsqlResponseReader transmite a resposta JSON sem armazenar todo o conjunto de resultados na memória. Uma árvore ColumnLayout , pré-computada uma vez por consulta, mapeia ES|QL nomes de colunas (como address.street, address.city) para propriedades aninhadas do POCO. Cada linha é montada em uma instância T e gerada uma de cada vez via IEnumerable<T> ou IAsyncEnumerable<T>.

A arquitetura em camadas

A funcionalidade LINQ para ES|QL é dividida em três pacotes:

Arquitetura de pacotes.
Elastic.Esql é o motor de tradução puro. Ele não tem dependência HTTP e contém os visitantes de expressões, o modelo de consulta, o formatador e o leitor de resposta. Você pode usá-lo de forma independente para criar e inspecionar consultas ES|QL sem nenhuma conexão com o Elasticsearch. Isso é útil para testes, logging de consultas ou para criar a sua camada de execução.

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

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

Elastic.Clients.Esql é um cliente ES|QL leve e independente. Ele adiciona a execução HTTP além de Elastic.Esql via Elastic.Transport. Se sua aplicação só precisa do ES|QL e nenhuma das outras APIs do Elasticsearch, essa é a opção de dependência mínima.

Elastic.Clients.Elasticsearch é o cliente completo do Elasticsearch .NET. Também se baseia em Elastic.Esql e expõe o provedor LINQ via espaço de nome client.Esql. Esse é o ponto de entrada recomendado para a maioria das aplicações.

Ambos os pacotes da camada de execução fornecem a própria implementação do IEsqlQueryExecutor, a interface estratégica que conecta tradução e transporte.

Todos os três pacotes são compatíveis com o Native AOT quando usados com um JsonSerializerContext gerado por fonte. Para as informações completas sobre o cliente, consulte a documentação do Native AOT.

Além do básico

O exemplo acima abordou filtragem, classificação e paginação. O provedor aceita um conjunto mais amplo de operações.

Agregações

GroupBy, combinado com funções agregadas em Select, traduz-se em ES|QL STATS ... BY:

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

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

Projeções

Select, com tipos anônimos gera os comandos EVAL, KEEP e RENAME:

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

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

Biblioteca repleta de funções

Mais de 80 funções ES|QL estão disponíveis via classe EsqlFunctions, cobrindo data/hora, string, matemática, IP, correspondência de padrões e pontuação. Métodos Math.* padrão e string.* também são traduzidos:

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

PESQUISAR ENTRAR

Consultas cruzadas de índice traduzem-se para ES|QL LOOKUP JOIN:

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

Acesso direto ao ES|QL bruto

Para recursos do ES|QL que ainda não são cobertos pelo provedor LINQ, você pode adicionar fragmentos brutos:

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

Consultas assíncronas do lado do servidor

Para consultas de longa duração, envie-as para processamento em segundo plano no servidor:

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

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

Consultas assíncronas do lado do servidor são úteis principalmente em consultas analíticas de longa duração/processamento de grandes conjuntos de dados que podem exceder os tempos-limite típicos, ou em ambientes sensíveis a tempo-limite com balanceadores de carga, gateways de API ou proxies que impõem tempos-limite de HTTP rigorosos. Consultas assíncronas evitam quedas de conexão ao separar o envio da obtenção dos resultados.

Para começar

LINQ to ES|QL está disponível a partir de:

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

Instale do NuGet:

dotnet add package Elastic.Clients.Elasticsearch

Os pontos de entrada estão em client.Esql:

Para obter a referência completa de recursos, incluindo opções de consulta, acesso a vários campos, objetos aninhados e tratamento de campos de vários valores, consulte a documentação do LINQ to ES|QL.

Conclusão

Do LINQ para ES|QL traz toda a expressividade do C# LINQ para a linguagem de consulta ES|QL do Elasticsearch, para que você escreva consultas componíveis e com tipagem forte sem precisar criar manualmente as strings de consulta. Com captura automática de parâmetros, materialização em streaming e arquitetura de pacotes em camadas que se adapta de traduções independentes ao cliente completo do Elasticsearch, ele se integra naturalmente a aplicações .NET de qualquer tamanho. Instale o cliente mais recente, direcione suas expressões LINQ para um índice e deixe o provedor cuidar do resto.

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:

• Servidor MCP do Elastic Agent Builder para Elasticsearch 9.2+
• Servidor MCP do Elasticsearch para versões mais antigas (Python)

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:

1. Configure o servidor MCP para o Elasticsearch.
2. Carregue o servidor MCP no Claude Desktop.
3. Faça o teste.

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.
• zod ajuda 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.

É exatamente por isso que construímos dashboards de somente leitura. É o controle que você vinha pedindo. Compartilhe dashboards com confiança, sem se preocupar que a próxima pessoa com acesso de edição os altere ou danifique.

Observação: permissões de somente leitura estão disponíveis no Elastic Cloud Serverless e a partir da versão 9.3 para o Elastic Cloud Hosted e o Elastic Self-Managed.

Quando “todo mundo pode editar” atrapalha

No Kibana, compartilhamento geralmente significava permissões no nível do espaço. Se alguém pode criar dashboards em um espaço, também pode editar ou excluir os de qualquer outra pessoa. Isso é ótimo para colaboração até deixar de funcionar. Uma edição acidental pode levar a decisões erradas, perda de confiança e muito retrabalho.

Já ouvimos as soluções alternativas: "Colocamos 'somente leitura' no nome do dashboard e esperamos que as pessoas percebam." Ou: "Nós os marcamos e cruzamos os dedos." Esperança não é um modelo de permissão. Você precisava de uma forma real de bloquear o dashboard sem bloquear todo mundo do espaço.

O que realmente dá errado

Deb e Kevin têm acesso de edição ao dashboard de monitoramento de logs dentro do espaço Operações. Kevin faz algumas mudanças nos gráficos. Quando Deb volta, os números não correspondem ao que ela apresentou. Ela precisa rastrear o que mudou (muitas vezes de memória), consertar e se perguntar quantos relatórios foram enviados com dados ruins.

Dashboards de somente leitura: Propriedade e controle que fazem sentido

Dashboards de somente leitura corrigem isso ao dar a você controle para decidir se outros usuários podem editar o dashboard. Quando você compartilha um dashboard, escolhe: editar (padrão, igual a hoje) ou visualizar. No modo de visualização , somente você (e os administradores do Kibana) podem mudar ou excluir isso. Todos os outros usuários podem abrir, usar e confiar, mas não podem modificar.

O que você recebe

• Integridade do dashboard: no modo de visualização, outros usuários com acesso de edição no espaço não podem modificar ou excluir o dashboard. Se tentarem, são informados de que está bloqueado. Seus gráficos e sua lógica permanecem como você os deixou.
• Você mantém o controle: Você é o dono. Você sempre pode editar, refinar e atualizar. Compartilhar como somente visualização não bloqueia o acesso; ele fixa a versão que todos os outros veem.
• Ciclo de vida flexível: você pode voltar a colocar um dashboard em “Pode editar” a qualquer momento. E os administradores do Kibana ainda podem gerenciar todos os dashboards (por exemplo, se o proprietário sair). Sem impasses.

Você pode compartilhar amplamente dashboards finalizados e de alta importância estratégica e saber que eles permanecerão consistentes. Está disponível em todos os níveis e ofertas da Elastic, incluindo Serverless.

Quem pode fazer o quê?

Referência rápida por função:

• Proprietário do dashboard: você o criou; tem acesso total de edição.
• Administrador do Kibana: pode gerenciar todos os dashboards.
• Usuário com permissão de edição no espaço: pode criar e editar seus dashboards; não pode editar ou excluir dashboards de somente leitura.
• Usuário com permissão de visualização no espaço: só pode visualizar (e listar) dashboards.

Como ativar o modo somente leitura

Você pode configurar o modo somente leitura ao salvar um novo dashboard ou mais tarde no menu de compartilhamento.

Ao salvar um novo dashboard

• Crie seu dashboard e clique em Salvar.
• Na janela "Salvar como novo dashboard", encontre Permissões.
• Alterar de Pode editar para Pode visualizar.
• Clique em Salvar. Concluído. É somente leitura para todos os outros.

Para um dashboard que você já possui

• Abra o dashboard.
• Abra o menu Compartilhar dashboard.

• Na janela de compartilhamento, localize Permissões e alterne para Pode visualizar. A mudança se aplica imediatamente; outros usuários no espaço não podem mais editar ou excluir o dashboard.

• Você pode passar o mouse sobre a ação Compartilhar para ver que tipo de permissões um determinado dashboard tem.

Ver quais dashboards estão bloqueados

Na lista principal Dashboards, os dashboards que você não pode editar ou excluir têm uma caixa de seleção desativada. Isso oferece uma maneira fácil de identificar o que é somente leitura.

No dashboard, você também verá que a ação Editar está desativada e uma dica de ferramenta será exibida, explicando que o dashboard foi definido como somente leitura.

Experimente

Dashboards de somente leitura já estão disponíveis. Crie um dashboard, defina como Pode visualizar e compartilhe. Sua equipe recebe uma única fonte confiável, e você fica tranquilo. Não há mais “por favor, não edite” no título.

Queremos saber como você usa dashboards de somente leitura. Compartilhe seu feedback em nosso fórum comunitário.

Esta postagem volta a se concentrar na questão: quais são as interfaces de busca que um agente precisa para construir o próprio contexto? Primeiro, ele aborda as vantagens entre ferramentas de linha de comando e ferramentas dedicadas de banco de dados. A partir daí, oferece um framework prático para encontrar as interfaces certas para as necessidades do seu agente.

O que "construir contexto" realmente significa para um agente?

Nos primeiros pipelines de Retrieval-Augmented Generation (RAG), o desenvolvedor projetou um pipeline de recuperação fixo, e o modelo de linguagem grande (LLM) era um receptor passivo do contexto. Essa limitação era fundamental: o contexto era recuperado em cada consulta, fosse necessário ou não, sem checar se realmente ajudava.

Com a transição para o RAG agêntico, os agentes agora têm acesso a um conjunto de ferramentas de busca para criar o próprio contexto. Por exemplo, tanto o Claude Code [1] quanto o Cursor [2] permitem que o agente escolha diferentes ferramentas de busca e até as combine para consultas encadeadas, dependendo do que a tarefa realmente exige.

Quais interfaces de busca existem para engenharia de contexto?

O contexto pode estar em diferentes locais, como na web, em um sistema de arquivos local ou em um banco de dados. O agente pode interagir com cada uma dessas fontes de dados fora de contexto em diferentes ferramentas:

• As ferramentas de linha de comando podem executar comandos de linha de comando e ter acesso ao sistema de arquivos local. Alguns exemplos de ferramentas de linha de comando integradas são a ferramenta bash da API Claude, a ferramenta exec do OpenClaw e a ferramenta de linha de comando do LangChain.
• Ferramentas de banco de dados dedicadas, como ferramentas de um servidor Model Context Protocol (MCP) (por exemplo, o servidor MCP do Elastic Agent Builder) ou ferramentas personalizadas (por exemplo, run_esql(query) ou db_list_index()), podem consultar bancos de dados.
• Ferramentas dedicadas de busca de arquivos podem buscar e ler arquivos locais (ou carregados), sem acesso total à linha de comando. Alguns exemplos de ferramentas integradas de busca de arquivos são o File Search Tool da API do Gemini e o File Search Tool da OpenAI.
• Ferramentas de busca na web podem recuperar informações da web.
• Ferramentas de memória armazenam e recuperam da memória de longo prazo (independentemente de como esteja armazenada).

Como você pode ver, a ferramenta shell é versátil e pode ser usada para recuperar contexto de diferentes fontes de dados, incluindo:

• Sistema de arquivos: o agente explora a estrutura de diretórios (ls, find), busca conteúdo relevante (grep, cat) e repete o processo até obter contexto suficiente.
• Banco de dados: o agente pode usar ferramentas de linha de comando (CLI) para banco de dados (p. ex., elasticsearch-sql-cli), chamar APIs HTTP via curl ou executar scripts. Isso é útil principalmente em combinação com as habilidades do agente, que são exemplos reutilizáveis e documentados inseridos no contexto do agente para orientar o uso correto das ferramentas (p. ex., Elastic Agent Skills para Elasticsearch).
• Web: o agente pode executar buscas na web usando o comando curl via API de um provedor de busca.

No entanto, a ferramenta de linha de comando dá acesso direto ao sistema e, portanto, exige medidas de segurança, como execução em ambiente sandbox isolado e logging de todos os comandos executados.

Quando usar as diferentes interfaces de busca

A interface de busca certa depende dos seus dados, dos seus padrões de consulta e do seu caso de uso. Esta seção serve como um ponto de partida prático.

Sistemas de arquivos não tornam bancos de dados obsoletos

A discussão entre sistemas de arquivos e bancos de dados não envolve a camada de armazenamento. Por exemplo, o LangChain explica que seu sistema de memória na verdade não armazena memória em um sistema de arquivos real. Em vez disso, ele armazena a memória em um banco de dados e a representa como um conjunto de arquivos para o agente [3].

Sistemas de arquivos são uma escolha natural para casos de uso nativos de arquivos, como agentes de codificação. Eles também funcionam bem como bloco de notas temporário ou memória de trabalho e para casos de usuário único ou agente único em que a concorrência não é preocupação. Nesses casos, um sistema de arquivos físico ou a representação dos dados como sistema de arquivos dá flexibilidade antes de se comprometer com uma interface específica.

Porém, o armazenamento no sistema de arquivos tem desvantagens reais, como concorrência fraca, aplicação manual de esquemas e transações atômicas. Esses fatores ficam mais evidentes quando sua aplicação precisa redimensionar ou migrar para um panorama multi-agente. Qualquer pessoa que ignore essas desvantagens está condenada a reinventar penosamente bancos de dados piores, sem as décadas de engenharia por trás da segurança das transações ou do controle de acesso que os bancos de dados de produção já oferecem. Além disso, na maioria dos contextos de negócios, você não escolhe usar o banco de dados, já que ele já existe, armazenando dados críticos para a empresa.

Ferramenta de linha de comando e sistema de arquivos

Ferramenta de linha de comando é o ponto de partida natural para buscas no sistema de arquivos. Atualmente, os agentes de codificação estão gerando um grande avanço no campo. Como eles trabalham com código em arquivos locais, são naturalmente casos de uso que envolvem muitos arquivos. Portanto, os LLMs são ajustados na fase pós-treinamento nas tarefas de codificação. É por isso que muitos LLMs são bons não só em escrever código como em usar comandos de linha de comando e navegar por sistemas de arquivos.

Usar uma ferramenta de linha de comando com CLIs integradas, como ls e grep, para encontrar arquivos é eficaz. Com grep, uma consulta como "Encontre todos os arquivos que importam matplotlib" é rápida, precisa e barata. Mas, quando o agente precisa lidar com consultas conceituais, como "Como nosso app lida com falhas na autenticação?", a correspondência de padrões com o grep pode atingir um teto muito rápido. Várias alternativas que trazem capacidades de busca semântica para a linha de comando surgiram para preencher essa lacuna, incluindo jina-grep.

No entanto, grep e muitas das alternativas de busca semântica funcionam em O(n) sobre o corpus. Nos casos de uso em bases de código, isso pode ser suficiente. No entanto, se seus dados aumentarem, a latência será perceptível. Nesse caso, é necessário um datastore indexado para manter o desempenho.

Ferramenta Shell + banco de dados

Outra forma de incluir aos seus dados mais recursos de busca, como busca semântica ou híbrida, é armazená-los em um banco de dados, como o Cursor. Além disso, quando os dados exigem junções relacionais complexas ou agregações, é indispensável uma interface de banco de dados.

Quando os dados estão em um banco de dados em vez de no sistema de arquivos, uma ferramenta de linha de comando pode funcionar como uma interface leve para banco de dados em determinados casos de uso. Se suas consultas forem simples o suficiente para uma CLI ou uma chamada de curl, uma ferramenta dedicada de banco de dados pode adicionar complexidade desnecessária.

Essa abordagem também é adequada nas fases iniciais de exploração, quando você ainda não sabe quais padrões de consulta seu agente realmente desenvolverá. Nesse caso, as habilidades do agente podem fornecer ao agente estrutura suficiente para realizar consultas corretamente, sem precisar se comprometer com uma ferramenta desenvolvida especificamente para isso. No entanto, quando o agente precisa de várias iterações para encontrar a maneira correta de consultar o banco de dados para tarefas repetitivas, a sobrecarga de tokens ao usar uma ferramenta de linha de comando como interface deixa de justificar a simplicidade de evitar mais uma ferramenta.

Ferramenta dedicada de banco de dados

Principalmente quando padrões de consulta repetidos são estruturados ou analíticos, ferramentas dedicadas a banco de dados são necessárias. Um post do blog da Vercel e da Braintrust comparou agentes com diferentes conjuntos de ferramentas de busca para tarefas reais de recuperação em dados semiestruturados, como chamados de suporte ao cliente e transcrições de chamadas de vendas (por exemplo: "Quantos problemas abertos mencionam 'segurança'?" ou "Encontre problemas onde alguém relatou um bug e depois alguém enviou um PR alegando corrigir.") [4].

Agentes com ferramentas dedicadas de banco de dados usavam menos tokens, eram mais rápidos e cometiam menos erros do que agentes com apenas uma ferramenta de linha de comando e um sistema de arquivos. A lição é que ferramentas diretas de banco de dados são a opção certa quando a consulta exige raciocínio analítico sobre dados semiestruturados.

Combinando interfaces de busca

Nenhuma interface de busca única lida bem com todas as consultas. Por exemplo, o Cursor combina ferramentas de linha de comando (para buscas via grep) e ferramentas de busca semântica e permite que o agente selecione a ferramenta certa com base nas instruções do usuário. Eles relatam que o agente escolhe o grep para buscar símbolos ou strings específicos, a busca semântica para perguntas conceituais ou comportamentais e ambos para tarefas exploratórias.

O experimento Vercel relata o mesmo: seu agente híbrido, com acesso tanto a uma ferramenta de linha de comando quanto a uma ferramenta de banco de dados dedicada, obteve o melhor desempenho entre todos os agentes testados, usando primeiro as ferramentas de banco de dados dedicadas e, em seguida, confirmando os resultados via busca no sistema de arquivos. No entanto, essa abordagem usa mais tokens e tempo para raciocinar sobre a escolha e validação da ferramenta.

Em ambos os exemplos, o padrão é o mesmo: a composição supera qualquer interface única, mas tem como contrapartida o aumento no custo e da latência.

Recomendações práticas para encontrar o conjunto certo de ferramentas

O conjunto certo de interfaces de busca é pequeno, específico e adequado aos padrões reais de consulta do seu agente. A prática recomendada atual é ter um agente com o mínimo de ferramentas possível, em vez de ter um agente com centenas de ferramentas MCP. Isso ocorre porque a desvantagem de expor todas as ferramentas possíveis de antemão enche a janela de contexto e confunde o agente sobre qual ferramenta realmente usar. Por exemplo, o Claude Code supostamente tem apenas cerca de 20 ferramentas.

Em vez disso, a ideia da divulgação progressiva é começar com um conjunto mínimo de ferramentas e deixar o agente descobrir outros recursos somente quando necessário. Pesquisas da Anthropic [5] e da Cursor [6] mostraram que essa abordagem gera uma economia de tokens entre 47%–85%. O Claude Code, por exemplo, implementa isso diretamente, permitindo que o agente descubra de forma incremental como consultar uma API ou um banco de dados, sem que esse conhecimento consuma contexto em cada chamada LLM.

Após saber os padrões de consulta do agente, você pode revisitar o conjunto de ferramentas de busca às quais o agente tem acesso como padrão. Uma forma útil de pensar sobre essa troca é o princípio "piso baixo, teto alto" para decidir quais ferramentas devem ser selecionadas. Ferramentas "teto alto" não limitam o potencial do agente. Por exemplo, uma ferramenta de linha de comando versátil permite que o agente escreva consultas completas ao banco de dados, inclusive as ambíguas, mas ao custo de sobrecarga no raciocínio, maior latência e menor confiabilidade.

Ferramentas de baixo piso são o oposto. São ferramentas especializadas que abrangem consultas específicas e são imediatamente acessíveis ao agente com o mínimo de sobrecarga de raciocínio, gerando menor custo e maior confiabilidade. Mas eles precisam de engenharia inicial, não conseguem cobrir todas as possíveis consultas e podem dificultar para o agente escolher a ferramenta certa.

Pense em cada ferramenta como parte de um espectro: ferramentas com baixo limiar de uso são fáceis para o agente usar corretamente, mas têm escopo limitado. Já as ferramentas com alto teto (maior potencial) são versáteis, mas exigem mais raciocínio para serem usadas.

A maioria dos agentes precisa de uma combinação de diferentes ferramentas de busca. Porém, cada ferramenta precisa justificar sua inclusão. Recomendamos começar com uma ferramenta de busca versátil (por exemplo, uma ferramenta search_database() ou uma ferramenta de linha de comando). Em seguida, reutilize os registros de comando que você já mantém para fins de segurança, a fim de monitorar o que seu agente realmente faz, incluindo chamadas de ferramentas, tentativas repetidas e número de chamadas por consulta de usuário. E, quando você notar um padrão de consulta se repetindo ou falhando, é hora de criar uma ferramenta específica para ele.

Resumo

O debate entre sistema de arquivos e banco de dados está desviando a atenção da verdadeira questão que os engenheiros deveriam se fazer: quais são as interfaces de busca adequadas que o agente precisa para construir o próprio contexto? A resposta mais provável é: nenhuma.

A ferramenta de linha de comando é versátil para interagir com diferentes fontes fora do contexto e, portanto, é um bom ponto de partida. Por outro lado, é menos eficiente e preciso nos casos de uso com consultas analíticas estruturadas do que ferramentas dedicadas a bancos de dados.

O objetivo é encontrar o conjunto mínimo de ferramentas de busca que lide bem com os padrões de consulta reais do seu agente. Comece com uma ferramenta de linha de comando e registre em log o que seu agente realmente faz. Quando um padrão de consulta se repetir e falhar, é hora de projetar ferramentas especializadas.

Referências

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

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

3. Harrison Chase (LangChain). How we built Agent Builder’s memory system (2026).

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

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

6. Cursor. Dynamic context discovery (2026).

A festa está ficando cheia

Você está organizando uma festa da pizza. Você tem alguns amigos ajudando a servir, cada um em diferentes pontos da sala. Você dá uma pizza para cada amigo, e eles começam a distribuir fatias para os convidados famintos conforme chegam.

No começo, as coisas correm tranquilamente. Alguns convidados vão chegando, seus amigos servem as fatias, e todo mundo fica feliz. Mas então a notícia sobre suas pizzas de massa fermentada começa a se espalhar. A campainha continua tocando. Os convidados chegam em massa. Logo, uma multidão começa a se formar em torno de um de seus amigos, aquele que está segurando a pizza de pepperoni, que todo quer.

Seu amigo com a pizza de pepperoni está sobrecarregado. Os convidados estão esperando, ficando impacientes, e uma grande fila se formou. Enquanto isso, seu amigo segurando a pizza margherita está parado com quase ninguém pedindo uma fatia.

O que você faz?

Você pede mais algumas pizzas de pepperoni e as entrega para outros amigos. Agora, três amigos estão segurando fatias de pepperoni em vez de um. A multidão se espalha e, de repente, você pode servir três vezes mais convidados ao mesmo tempo.

Algumas coisas ficam claras conforme você organiza mais festas:

• Nem todas as pizzas são igualmente populares. Algumas têm alta demanda, enquanto outras têm menos interessados. Você não precisa de "cópias" extras das impopulares; você precisa de mais das que têm filas.
• Peça mais pizzas antes que a fila fique muito longa. Se esperar até que seu amigo esteja completamente sobrecarregado e os convidados estejam indo embora com raiva, você já esperou demais. Melhor pegar uma pizza extra quando você vê uma multidão se formando.
• Não jogue as pizzas fora muito rápido. Só porque a multidão ao redor do pepperoni diminuiu por cinco minutos não significa que a correria acabou. Talvez eles estejam apenas reabastecendo as bebidas, ou até conversando entre si (isso ainda existe?). Mantenha as pizzas extras prontas. Se a pausa continuar por um tempo, você pode guardá-las.
• Você só pode distribuir tantas pizzas quanto o número de amigos que estão ajudando. Se você só tem quatro amigos ajudando, dez pizzas não mudarão o resultado. Apenas quatro podem ser servidas de uma vez. Ajuste a quantidade de pizzas ao número de mãos disponíveis.
• Quando um amigo for embora, pegue a pizza dele. Se algum dos seus amigos precisar sair, pegue a pizza dele imediatamente. Você não pode deixar pizzas sem vigilância. Entregue para outra pessoa ou guarde.

De pizzas a réplicas

Vamos mapear isso de volta para o Elasticsearch.

Na nossa analogia, as pizzas são réplicas (cópias dos seus shards de índice), seus amigos ajudando a servir são nodes de busca, convidados famintos são consultas de busca e aquela pizza popular com uma multidão ao redor é um índice em alta com alta carga de busca.

Quando o tráfego de busca aumenta em um índice específico, criamos réplicas adicionais e as distribuir entre seus nodes de busca. Qualquer réplica pode atender a qualquer consulta para esse índice, assim como qualquer amigo com pepperoni pode distribuir fatias de pepperoni. Mais réplicas significam maior rendimento: três réplicas podem lidar com três vezes mais consultas por segundo de uma única réplica.

Medindo a fome

Antes de decidirmos quantas pizzas pedir, precisamos saber o quão faminta está a multidão.

O Elasticsearch rastreia a carga de busca para cada shard. É uma métrica que captura quanta atividade de busca um shard está gerenciando. Agregamos isso em todos os shards de um índice para entender a demanda total de busca.

O que mais importa é a carga relativa de busca: qual a proporção do tráfego total de busca do seu projeto está atingindo cada índice? Se um índice recebe 60% de todas as buscas enquanto outro recebe 5%, sabemos onde adicionar capacidade.

A matemática por trás das pizzas

Calculamos o número ótimo de réplicas seguindo esta fórmula:

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

Onde:

• L = a carga de pesquisa relativa do índice (entre 0 e 1).
• N = o número de nodes de busca desejados em seu projeto.
• S = o número de fragmentos no índice.
• X = um limite para evitar pontos em alta (padrão: 0,5).

Um exemplo: quatro nós de busca, um índice com dois shards principais recebendo 80% do tráfego de busca:

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

Este índice em alta possui quatro réplicas distribuídas pelos nodes de busca.

O limiar X (padrão para 0,5) é importante. Não esperamos até que uma réplica seja completamente sobrecarregada; redimensionamos quando está com metade da capacidade. Distribua a pizza extra quando vir a multidão se formando, não quando os convidados já estiverem saindo.

Aumente rápido, reduza devagar.

Quando a carga de busca aumenta, adicionamos réplicas imediatamente. Não há motivo para deixar os usuários esperando.

Quando a carga de busca diminui, esperamos um pouco antes de agir. Precisamos ver uma demanda consistentemente baixa por cerca de 30 minutos antes de reduzir as réplicas. (Isso é para lidar com o tráfego irregular, onde um momento de silêncio não significa que a festa acabou.)

Isso é importante porque adicionar uma réplica tem um custo. A nova réplica copia os dados e esquenta seus caches antes de atender as consultas de forma eficiente. Remover réplicas de forma precipitada significa pagar constantemente esse custo inicial, já que o tráfego naturalmente flutua.

Respeitando os limites da topologia

As réplicas nunca podem exceder o número de nós de busca. Ter mais réplicas do que nós não traz benefício (você só pode servir tantas pizzas quanto amigos ajudam a servir fatias).

Quando nós são removidos do seu projeto, reduzimos as réplicas imediatamente para acompanhar. Sem esperar o cooldown, já que você não pode ter réplicas não atribuídas. No momento em que um amigo vai embora, removemos a pizza dele.

O panorama maior do Serverless

As réplicas para balanceamento de carga de busca funcionam junto com outros sistemas de autoescalonamento:

• O autoescalonamento de busca ajusta o número de nós de busca (quantos amigos estão ajudando).
• Réplicas para balanceamento de carga em buscas distribuem o tráfego ajustando a quantidade de réplicas por índice (quantas "pizzas" de cada tipo precisamos).
• O particionamento automático de fluxo de dados otimiza a quantidade de shards para gravações (como dividir cada pizza, explicado na postagem anterior).

Um princípio importante de design: réplicas para balanceamento de carga não acionam diretamente o autoescalonamento da busca. Em vez disso, ao distribuir as requisições de busca entre mais réplicas, isso permite aumentar a utilização de recursos entre seus nós de busca. Essa maior utilização então ativa nossa lógica de autoescalonamento existente para aumentar a capacidade, se necessário. Réplicas para balanceamento de carga permitem que o autoescalonamento faça seu papel, garantindo que seus nós de busca estejam realmente sendo usados, em vez de ter todo o tráfego preso em uma única réplica enquanto outros nós ficam parados.

O que isso significa para você

Você não precisa prever quais índices serão populares. Você não precisa ajustar as réplicas manualmente quando os padrões de tráfego mudam. Você não precisa acordar às 3 da manhã porque um pico sobrecarregou seu índice mais ocupado.

O sistema observa onde as filas estão se formando e pede mais pizzas para esses lugares. Índices em baixa não desperdiçam recursos com réplicas desnecessárias. Os índices em alta recebem a capacidade necessária. Seu orçamento vai aonde realmente importa.

Conclusão

Na postagem sobre particionamento automático, garantimos que suas pizzas sejam cortadas corretamente. Agora, com réplicas para balanceamento de carga de busca, garantimos que você tenha pizzas suficientes, nas mãos certas, quando as multidões famintas chegarem.

Experimente Elastic Cloud Serverless e deixe a logística da pizza com a gente.

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 de combinar 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_completion tipo 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.

Para resolver isso, mecanismos de busca como o Elasticsearch utilizam duas estratégias principais de otimização:

1. Busca aproximada (mundo pequeno hierárquico navegável [HNSW]): em vez de analisar cada documento, construímos um grafo de navegação para acessar rapidamente a vizinhança provável da resposta.
2. Quantização: Compactamos os vetores (por exemplo, de floats de 32 bits para inteiros de 8 bits ou até mesmo valores binários de 1 bit) para reduzir o uso de memória e acelerar os cálculos.

Mas a otimização geralmente vem acompanhada de uma taxa: a precisão.

O medo é válido: "Se eu compactar meus dados e usar atalhos durante a busca, perderei os melhores resultados?" "Essa otimização degrada a relevância do meu mecanismo de busca?"

Para provar que a quantização do Elastic não degrada os resultados, criamos um ambiente de testes repetíveis usando o DBPedia-14 como conjunto de dados para calcular exatamente quanta precisão (especificamente, recall) sacrificamos em prol da velocidade ao usar as otimizações padrão do Elasticsearch.

Resumindo: é provavelmente muito menos do que você pensa. Confira o caderno aqui e teste você mesmo

As definições (para os não especialistas)

Antes de analisarmos o código, vamos definir alguns termos.

• Relevância versus recuperação: A relevância é subjetiva (encontrei informações úteis?). A recuperação é matemática. Se houver 10 documentos no banco de dados que correspondam perfeitamente à sua consulta, e o mecanismo de busca encontrar nove deles, sua recuperação será de 90% (ou 0,9).
• Busca exata (plana): às vezes chamada de método "força bruta". O mecanismo de busca analisa cada documento em um índice e calcula a distância.
  • Prós: recall perfeito de 100%.
  • Contras: computacionalmente caro e lento em larga escala.
• Busca aproximada (HNSW): O método do "atalho". O mecanismo de busca cria um HNSW gráfico e percorre o gráfico para encontrar os vizinhos mais próximos.
  • Prós: extremamente rápido e escalável.
  • Contras: Você pode perder um vizinho se a travessia do gráfico parar muito cedo.

O experimento: exato x aproximado

Para testar a recuperação, usamos o conjunto de dados DBPedia-14, um grande conjunto de dados de títulos e resumos em 14 classes de ontologia, muito usado para treinar e avaliar modelos de categorização de texto. Especificamente, vamos focar a categoria "Filme". Decidimos comparar as configurações otimizadas de produção com uma verdade matematicamente perfeita.

Neste experimento, estamos usando o modelo jina-embeddings-v5-text-small, um modelo multilíngue de última geração que lidera os benchmarks do setor de representação de textos. Escolhemos esse modelo porque ele define o padrão atual para embeddings de alto desempenho. Ao combinar a precisão de elite do Jina v5 com a quantização nativa do Elasticsearch, podemos demonstrar uma arquitetura de busca que é computacionalmente eficiente e sem prejudicar a qualidade da recuperação.

Configuramos um índice com mapeamento duplo. Ingerimos o mesmo texto em dois campos diferentes simultaneamente:

1. content.raw com tipo: flat. Isso força o Elasticsearch a realizar uma varredura de força bruta dos vetores Float32 completos. Isso retorna resultados de correspondência exatos e será usado na nossa linha de base.
2. content com o tipo semantic_text. Com padrões usando HNSW + melhor quantização binária (BBQ). Esse é o padrão otimizado de produção para correspondência aproximada.

O teste Recall@10

Para nossa métrica, usamos o Recall@10.

Escolhemos 50 filmes aleatórios e executamos a mesma consulta nos dois campos.

• Se a busca exata (plana) indicar que os 10 principais vizinhos são IDs [1, 2, 3... 10], você pode usar a busca exata.
• E a busca aproximada (HNSW) retorna IDs [1, 2, 3... 9, 99].
• Encontramos corretamente nove dos 10 principais. A pontuação é 0,9.

Aqui está o mapeamento que usamos:

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

Os resultados: a "estagnação" do sucesso

Realizamos um teste de escala, recarregando todo o conjunto de dados e testando com tamanhos de índice de 1.000 a 40.000 documentos.

Veja o que aconteceu com a pontuação de recall:

Os resultados foram incrivelmente estáveis. Mesmo com o aumento da escala, a busca aproximada coincidiu com a busca exata por força bruta em mais de 99% dos casos.

Por que funcionou tão bem?

Você poderia esperar que comprimir vetores em valores binários prejudicasse mais a precisão do que isso. A razão para isso não ocorrer está em como o Elasticsearch lida com a recuperação.

A maioria dos modelos de embedding hoje gera vetores Float32, que são volumosos. Para deixar a busca eficiente, o Elasticsearch usa quantização para vetores de alta dimensionalidade. Especificamente, desde a versão 9.2, ele usa BBQ como padrão.

O BBQ usa um mecanismo de reclassificação:

1. Percurso: o mecanismo de busca utiliza os vetores comprimidos (quantizados) para percorrer rapidamente o gráfico HNSW. Como os vetores são pequenos, ele pode superamostrar com eficiência, reunindo uma lista maior de candidatos (p. ex., os 100 principais documentos aproximadamente semelhantes) sem penalidade no desempenho.
2. Reclassificação: com esses candidatos, ele recupera os valores de precisão total apenas para esses poucos documentos para calcular a classificação final e precisa.

Ele oferece o melhor dos dois mundos: rapidez na quantização para o trabalho pesado e precisão dos números de ponto flutuante para a classificação final.

Podemos fazer melhor?

É importante notar que os resultados aqui usam configurações padrão e uma amostra aleatória de dados. Pense nisso como um ponto de partida de alto desempenho. Embora o Jina v5 seja excelente, essas pontuações de recall não são garantia de que funcione em todos os conjuntos de dados. Cada coleta de dados tem as próprias peculiaridades e, embora você possa definitivamente ajustar ainda mais as coisas para ter ainda mais desempenho, deve sempre comparar seus dados específicos para saber seu limite.

Conclusão

Este é um teste em pequena escala. Mas o objetivo do exercício não é medir especificamente o modelo de embeddings nem o BBQ, e sim mostrar como medir facilmente o recall do seu conjunto de dados com o mínimo de configuração.

Se você quiser executar esse teste com seus próprios dados, pode conferir o notebook aqui e tentar você mesmo.

A extensão está disponível como um projeto open source aqui.

O que é a Gemini CLI e como você a instala?

Gemini CLI é um agente de IA open source que traz os modelos Gemini do Google diretamente para a linha de comando. Ele permite que os desenvolvedores interajam com a IA a partir do terminal para realizar tarefas como gerar código, editar arquivos, executar comandos do shell e recuperar informações da web.

Diferentemente das interfaces típicas de chat, a Gemini CLI se integra ao seu ambiente local de desenvolvimento, o que significa que ela pode entender o contexto do projeto, modificar arquivos, executar builds ou testes e automatizar fluxos de trabalho diretamente no terminal. Isso a torna útil para desenvolvedores, engenheiros de confiabilidade de sites (SREs) e outros profissionais que desejam codificação e automação assistidas por IA sem sair do fluxo de trabalho da linha de comando.

Você pode instalar a Gemini CLI usando vários gerenciadores de pacotes. O método mais comum é usar o npm:

npm install -g @google/gemini-cli

Para conhecer opções alternativas de instalação, consulte a página oficial de instalação.

Após a instalação, inicie a CLI executando:

gemini

Você vê uma tela, conforme mostrado na Figura 1:

Configurar o Elasticsearch

Precisamos ter uma instância do Elasticsearch em execução. Se quiser usar o servidor MCP (Model Context Protocol), você também precisará ter o Kibana 9.3+ instalado. Para usar a habilidade da Elasticsearch linguagem de consulta (ES|QL) (esql) descrita abaixo, o Kibana não é necessário.

Você pode ativar um teste gratuito no Elastic Cloud ou instalá-lo localmente usando o script start-local :

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

Isso instalará o Elasticsearch e o Kibana no seu computador e gerará uma chave API para ser usada na configuração da Gemini CLI.

A chave API será mostrada como saída do comando anterior e armazenada em um .env arquivo na pasta elastic-start-local.

Se você está usando o Elasticsearch no local (por exemplo, usando start-local), e quer usar o Elastic Agent Builder com MCP, também precisa conectar um grande modelo de linguagem (LLM). Você pode ler esta página de documentação para entender as diferentes opções.

Se você estiver usando o Elastic Cloud (ou serverless), já tem uma conexão LLM pré-configurada.

Instale a extensão do Elasticsearch

Você pode instalar a extensão Elasticsearch para Gemini CLI com o seguinte comando:

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

Você pode verificar se as extensões foram instaladas com sucesso abrindo o Gemini e executando o seguinte comando:

/extensions list

Você deverá ver a extensão Elasticsearch disponível.

Se quiser usar a integração MCP, precisa ter uma versão do Elasticsearch 9.3+ instalada. Você precisa da URL do seu servidor MCP do Kibana:

• Obtenha a URL do seu servidor MCP em Agents > View all tools > Manage MCP > Copy MCP Server URL (Agentes > Ver todas as ferramentas > Gerenciar MCP > Copiar URL do Servidor MCP).
• A URL ficará assim: https://your-kibana-instance/api/agent_builder/mcp

Você precisa da URL do endpoint do Elasticsearch. Isso normalmente é relatado no topo da página do Kibana Elasticsearch. Se você está rodando o Elasticsearch com start-local, você já tem o endpoint na chave ES_LOCAL_URL no start-local .env. arquivo.

Também é necessário uma chave de API. Se estiver executando o Elasticsearch com start-local, você já tem a ES_LOCAL_API_KEY no arquivostart-local .env arquivo. Caso contrário, é possível criar uma chave de API usando a interface do Kibana, conforme indicado aqui:

• No Kibana: Stack Management > Security > API Keys > Create API Key (Stack management > Segurança > Chaves de API > Criar chave de API) .
• Sugerimos definir apenas os privilégios de leitura para a chave API, habilitando o privilégio feature_agentBuilder.read conforme reportado aqui.
• Copie o valor da chave de API codificada.

Defina as variáveis de ambiente necessárias no seu shell:

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

Instale o conjunto de dados de exemplo

Você pode instalar o conjunto de dados de pedidos de comércio eletrônico disponível no Kibana. Inclui um único índice chamado kibana_sample_data_ecommerce, contendo informações sobre 4.675 pedidos de um website. Para cada pedido, temos as seguintes informações:

• Informações do cliente (nome, ID, data de nascimento, e-mail e mais).
• Data do pedido.
• ID do pedido.
• Produtos (lista de todos os produtos com preço, quantidade, ID, categoria, desconto e outros detalhes).
• SKU.
• Preço total (sem impostos, com impostos).
• Quantidade total.
• Informações geográficas (cidade, país, continente, localização, região).

Para instalar os dados de exemplo, abra a página Integrações no Kibana (busque por “Integração” na barra de busca superior) e instale os Dados de Exemplo. Para mais detalhes, consulte a documentação aqui.

O objetivo deste artigo é mostrar como é fácil configurar o Gemini CLI para se conectar ao Elasticsearch e interagir com o índice kibana_sample_data_ecommerce.

Como usar o Elasticsearch MCP

Você pode verificar a conexão usando o seguinte comando no Gemini:

/mcp list

Você deve ver o elastic-agent-builder ativado, como mostrado na Figura 2:

O Elasticsearch fornece um conjunto padrão de ferramentas. Veja a descrição aqui.

Usando essas ferramentas, você pode interagir com o Elasticsearch, fazendo perguntas como:

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

Dependendo da pergunta, o Gemini usará uma ou mais ferramentas disponíveis para tentar respondê-la.

Os comandos /elastic

Na extensão Elasticsearch para Gemini CLI, também adicionamos /elastic comandos.

Se você executar o comando /help, verá todas as opções de /elastic disponíveis (Figura 3):

Esses comandos podem ser úteis se você quiser executar diretamente uma ferramenta específica do servidor MCP.elastic-agent-builder  Por exemplo, usando o seguinte comando, você pode obter o mapeamento do kibana_sample_data_ecommerce:

/elastic:get-mapping kibana_sample_data_ecommerce

Esses comandos são essencialmente atalhos para executar ferramentas específicas, em vez de depender do modelo Gemini para determinar qual ferramenta deve ser usada.

Como usar as habilidades do Elasticsearch

Essa extensão também inclui uma habilidade de agente para o ES|QL, a Linguagem de Consulta Elasticsearch disponível no Elasticsearch. Agent Skills é um formato aberto que fornece aos agentes de programação de IA, como o Gemini CLI, instruções personalizadas para tarefas específicas. Eles utilizam um conceito chamado divulgação progressiva, o que significa que apenas uma breve descrição da habilidade é adicionada ao prompt inicial do sistema. Quando você solicita que o agente execute uma tarefa, como consultar o Elasticsearch, ele associa a solicitação à habilidade relevante e carrega dinamicamente as instruções detalhadas. Essa é uma forma eficiente de gerenciar orçamentos de tokens enquanto fornece à IA exatamente o contexto que ela precisa.

A habilidade esqlfoi projetada para permitir que o Gemini CLI escreva e execute consultas ES|QL diretamente no seu cluster. ES|QL é uma poderosa linguagem de consulta encadeada que torna a exploração de dados, a análise de logs e as agregações altamente intuitivas. Com essa habilidade ativada, você não precisa pesquisar a sintaxe ES|QL; basta fazer perguntas em linguagem natural ao Gemini CLI sobre seus dados e o agente cuidará do resto.

As execuções são realizadas usando simples comandos curl executados em um terminal. Isso é possível porque o Elasticsearch oferece um conjunto abrangente de APIs REST que podem ser facilmente usadas para integrar o sistema a qualquer arquitetura.

O que a habilidadeesqloferece:

• Descoberta de índices e esquemas: o agente pode usar as ferramentas integradas da habilidade para listar os índices disponíveis e buscar mapeamentos de campo. Por exemplo, antes de escrever uma consulta para o conjunto de dados de comércio eletrônico, o agente pode executar uma verificação de esquema em kibana_sample_data_ecommerce para entender os campos disponíveis, como taxful_total_price ou category.
• Tradução perfeita da linguagem natural: a habilidade dá ao agente mais do que um simples manual de referência; ela fornece um guia específico para interpretar a intenção do usuário. Quando você digita solicitações em linguagem natural, como "Mostrar tempo médio de resposta agrupado por serviço", o agente usa o padrão de correspondência da habilidade para traduzir instantaneamente suas palavras nas agregações, filtros e comandos ES|QL corretos.
• Autocorreção: Se uma consulta falhar (por exemplo, devido a uma incompatibilidade de tipo ou erro de sintaxe), a skill retorna a consulta gerada juntamente com a mensagem de erro exata do Elasticsearch, permitindo que o agente corrija instantaneamente a consulta e tente novamente sem que você precise intervir.

Como a habilidade esql também está disponível como ferramenta no servidor MCP elastic-agent-builder, precisamos desativar esse servidor momentaneamente. Você pode usar o seguinte comando para desativá-lo:

/mcp disable elastic-agent-builder

Em seguida, você pode simplesmente digitar um prompt como esse em sua Gemini CLI:

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

O agente irá:

• Reconheça a necessidade da habilidade esql .
• Verifique o esquema do kibana_sample_data_ecommerce.
• Crie uma consulta ES|QL, como: FROM kibana_sample_data_ecommerce | STATS total_revenue = SUM(taxful_total_price) BY category.keyword | SORT total_revenue DESC | LIMIT 5.
• Execute a consulta na API do Elasticsearch.
• Apresente a resposta final para você diretamente no terminal.

Aqui, apresentamos um exemplo de resposta do Gemini ao prompt anterior:

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

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

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

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

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

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

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

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

 ✓  Shell 

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

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

É interessante notar como o modelo Gemini gera a resposta final mostrando todos os passos que ele segue. Aqui, você pode ver claramente a influência da habilidade no processo de raciocínio do modelo. Na primeira vez que o modelo reconhece que precisa usar uma habilidade ou executar um comando shell, ele solicita permissão usando a abordagem baseada em intervenção humana.

Ao lidar com o trabalho pesado de descoberta de esquema, geração de consultas e execução, a habilidade esql permite que você se concentre inteiramente nas respostas, em vez da mecânica de obtê-las. Você obterá os dados de que precisa, formatados corretamente e diretamente no seu terminal, tudo isso sem precisar escrever uma única linha de código ou alternar para outro aplicativo.

Conclusão

Neste artigo, apresentamos a extensão Elasticsearch para Gemini CLI que lançamos recentemente. Essa extensão oferece a você a capacidade de interagir com a instância do Elasticsearch usando o Gemini e o servidor Elasticsearch MCP fornecido pelo Elastic Agent Builder, disponível a partir da versão 9.3.0, bem como o comando /elastic.

Além disso, a extensão também inclui uma habilidade esql que converte a solicitação do usuário de linguagem natural em uma consulta ES|QL. Essa habilidade pode ser particularmente útil quando o servidor MCP não pode ser usado, pois a comunicação subjacente é conduzida por comandos curl simples executados em um terminal. O Elasticsearch oferece um conjunto abrangente de APIs REST que podem ser facilmente integradas a qualquer projeto. Isso é especialmente útil ao desenvolver aplicações de IA agêntica.

Para mais informações sobre nossa extensão Gemini CLI, acesse o repositório do projeto aqui.

Por isso, estamos tornando o Elastic Agent Skills open source: expertise nativa na plataforma para Elasticsearch, Kibana, Elastic observabilidade e Elastic Security. Adicione ao runtime do agente que você já usa e evolua seu agente de um "generalista" que precisa adivinhar muita sintaxe para um especialista com expertise real, como a capacidade de usar muitos dos padrões arquitetônicos das próprias equipes de engenharia da Elastic. Esta versão inicial de prévia técnica foca em habilidades com máxima compatibilidade com o Elastic Cloud Serverless, mas evoluirá logo para incluir suporte aprimorado para versões anteriores da plataforma.

Além disso, a Elastic está resolvendo esse problema dos dois lados. Para agentes na plataforma Elastic, o Elastic Agent Builder (agora disponível de forma geral) permite que você crie e converse com agentes de IA que herdam os controles de acesso aos seus dados, usem ferramentas integradas de busca e análise e trabalhem em contexto junto com seus dashboards, alertas e investigações. Estamos trabalhando muito para garantir experiências incríveis e agêntica na plataforma Elastic. Mas nem todo agente vive dentro da Elastic. Sua equipe já usa Cursor, Claude Code ou outros tempos de execução, e esses agentes também precisam usar a Elastic da maneira certa. É aí que entra o Agent Skills.

Por que os agentes enfrentam dificuldades com plataformas especializadas

Grandes modelos de linguagem (LLMs) são generalistas muito capazes. Eles podem escrever Python, explicar manifestos do Kubernetes e refatorar componentes do React porque os dados de treinamento são ricos em exemplos. Mas quando se trata de trabalho específico de plataforma, do tipo que envolve linguagens de consulta proprietárias, superfícies profundas de API e práticas recomendadas específicas do domínio, eles ficam aquém de maneiras previsíveis.

Para o Elasticsearch, a lacuna aparece concretamente:

• A linguagem de consulta do Elasticsearch (ES|QL) é um território novo. Os LLMs são treinados em SQL, mas o ES|QL é uma linguagem de consulta baseada em pipes com sintaxe diferente, funções distintas e semântica distinta. Os agentes escrevem consultas que parecem plausíveis, mas não são analisadas. Eles confundem WHERE com | WHERE, inventam funções que não existem e ignoram o modelo de composição baseado em pipes.
• As interfaces de API são amplas e abrangentes. Elasticsearch, Kibana e Elastic Security expõem centenas de APIs em busca, ingestão, alertas, regras de detecção, gerenciamento de casos, dashboards e muito mais. Um agente armado apenas com dados de treinamento gerais precisa adivinhar qual endpoint chamar, como é o corpo da solicitação e como lidar com a resposta. Ele erra com frequência suficiente para acabar com a confiança.
• Práticas recomendadas não estão nos dados de treinamento. Quando você deve usar semantic_text em vez de um pipeline de embedding personalizado? Como você deve estruturar um pipeline de ingestão para um CSV de 10GB? Qual é a sintaxe correta da regra de detecção para uma técnica MITRE ATT&CK®? Agentes de uso geral não têm conhecimento curado e estruturado de forma confiável e específico para Elastic, carregado por padrão. Eles teriam que procurar, e mesmo que encontrassem, documentos brutos nem sempre codificam as decisões e práticas recomendadas que profissionais habilidosos utilizam.

O resultado: os desenvolvedores passam mais tempo corrigindo a saída do agente do que passariam escrevendo o código eles mesmos. Essa é a experiência que ninguém esperava.

Habilidades de agentes: conhecimento de plataforma, empacotado para agentes

As habilidades do agente são diretórios independentes de instruções, scripts e material de referência que os tempos de execução do agente podem carregar de forma dinâmica. Quando uma habilidade está ativa, o agente tem acesso ao contexto certo na hora certa: sintaxe de consulta, padrões de API, lógica de validação, exemplos trabalhados, para que ele possa completar as tarefas corretamente na primeira tentativa.

Cada habilidade segue a especificação aberta do agentskills.io: uma pasta com um arquivo SKILL.md contendo metadados e instruções estruturadas. Nenhum formato proprietário, sem bloqueio. As habilidades funcionam em diferentes ambientes de execução de agentes, incluindo Cursor, Claude Code, GitHub Copilot, Windsurf, Gemini CLI, Cline, Codex e muitos outros.

O que há na versão inicial v0.1.0?

O primeiro conjunto de habilidades abrange cinco áreas do Elastic Stack:

• Interação com APIs do Elasticsearch (busca, indexação, clustering)
• Crie e gerencie conteúdo do Kibana, como dashboards, alertas, conectores e muito mais
• Especialização em Elastic Observability
• Conhecimento especializado para o Elastic Security
• Criando agentes eficazes no Agent Builder

As habilidades podem ser combinadas

Habilidades não são monolíticas. Eles são modulares por natureza. Seu agente carrega apenas as habilidades relevantes para a tarefa em questão. Trabalhando em uma consulta ES|QL? A habilidade ES|QL é ativada. Precisa criar um dashboard a partir desses resultados? A habilidade do dashboard melhora. Está avaliando a integridade do seu aplicativo? A habilidade de avaliação de serviço entra em jogo. Está investigando um alerta de segurança? A triagem se conecta às habilidades de gerenciamento de casos e resposta à medida que a investigação avança.

Essa capacidade de composição significa que você não precisa de um único e enorme prompt que tente cobrir tudo. Cada habilidade carrega exatamente o contexto que seu domínio exige, nada mais, nada menos.

Para desenvolvedores que criam aplicativos de pesquisa e IA

Se você está carregando dados no Elasticsearch, escrevendo consultas ou migrando índices, as habilidades reduzem o ciclo de geração de código, ocorrência de erros e busca nos documentos para descobrir o que deu errado.

Peça ao seu agente para carregar um arquivo CSV. Ele usará uma ferramenta de ingestão de streaming que gerencia a contrapressão e infere mapeamentos a partir dos dados. Não é um loop _bulk feito manualmente que executa e fica sem memória ao processar o primeiro arquivo grande. Peça para ele consultar o ES|QL e descobrir os nomes reais de índice e esquemas de campos, escrever consultas válidas com sintaxe correta, fazer agregações apropriadas e seleção de recursos compatível com a versão, em vez de dar um palpite no estilo SQL que exige três rodadas de depuração. Ao solicitar a reindexação em todos os clusters, o sistema segue todo o fluxo de trabalho operacional: cria o destino com mapeamentos explícitos, ajusta as configurações para otimizar a taxa de transferência, executa a tarefa de forma assíncrona e restaura as configurações de produção ao terminar, em vez de chamar o método _reindex, que omite metade das etapas que um operador experiente seguiria.

Em vez de um agente que te dá um ponto de partida plausível que você precisa corrigir, você tem um que codifica a disciplina operacional que faz a saída funcionar.

Exemplos de impactos do uso das Habilidades do Elastic Agent

Para equipes de segurança

As equipes de segurança repetem os mesmos fluxos de trabalho operacionais diariamente: triagem de alertas, ajuste de regras de detecção e gerenciamento de casos. As habilidades do agente codificam esse conhecimento processual para que seu agente de IA possa executar esses fluxos de trabalho corretamente, chamando as APIs certas na ordem certa com os nomes de campo corretos. Para um guia prático que leva você do zero a um ambiente de Elastic Security totalmente povoado sem sair do seu IDE, consulte Comece a usar o Elastic Security a partir do seu agente de IA.

Para equipes de observabilidade e operações

O novo Agent Skills for Elastic Observability reduz o trabalho operacional de instrumentar sistemas complexos, gerenciar SLOs, analisar dados complexos e avaliar a integridade dos serviços. A incorporação da expertise nativa da Elastic diretamente aos agentes de IA permite que as equipes executem fluxos de trabalho complexos de observabilidade usando uma linguagem natural simples. Isso permite que as equipes de SREs e operações resolvam incidentes com mais rapidez e mantenham sistemas confiáveis com mais facilidade. Saiba mais no blog.

Open source, especificações abertas, impulsionado pela comunidade

Estamos lançando o Agent Skills sob a licença Apache 2.0 porque acreditamos que o conhecimento dos agentes deve ser aberto. A especificação agentskills.io que as habilidades seguem é um padrão aberto, não um formato proprietário da Elastic. Queremos que as habilidades sejam um esforço comunitário e não um privilégio isolado.

Parte de um panorama maior

O Agent Skills é uma parte de uma iniciativa mais ampla para tornar o Elasticsearch a plataforma de dados mais amigável para agentes disponível. Para agentes que residem na plataforma Elasticsearch, o Agent Builder vai além, herdando os controles de acesso e permissões dos seus dados, fornecendo ferramentas integradas e personalizadas para pesquisa e análise, e permitindo que os usuários interajam com os agentes em contexto, juntamente com dashboards, alertas e investigações. Por fim, o suporte para habilidades chegará em breve ao Agent Builder, permitindo que o desenvolvedor tenha flexibilidade para aproveitar o Elastic Agent Skills, assim como as habilidades de qualquer outra fonte, para viabilizar chat seguro, com mais contexto e automação na plataforma Elasticsearch.

Para os agentes que residem em outros locais, estamos investindo no ecossistema aberto:

• Expansão do servidor Model Context Protocol (MCP): ampliação do endpoint MCP no Agent Builder com mais ferramentas além das operações atuais de busca, ES|QL e indexação.
• Melhorias na autenticação: facilitar a conexão segura dos agentes, com o objetivo de eliminar a necessidade de copiar e colar manualmente as chaves de API.
• Documentação legível por LLM: publicar arquivos llms.txt e AGENTS.md para que os agentes possam descobrir e entender as APIs da Elastic por conta própria.
• Uma interface de linha de comando (CLI) para fluxos de trabalho de agentes: ferramentas de linha de comando que facilitam o gerenciamento de conexões e as operações comuns dos agentes.

Habilidades são a camada que você pode usar hoje. O restante está chegando.

Começar

Antes de começar: os agentes de codificação de IA operam com credenciais reais, acesso real ao shell e com todas as permissões do usuário que os executa. Quando esses agentes são direcionados para fluxos de trabalho de segurança, os riscos são maiores: você está entregando a um sistema automatizado o acesso à lógica de detecção, ações de resposta e telemetria sensível. Cada perfil de risco de organização é diferente. Antes de habilitar fluxos de trabalho de segurança orientados por IA, avalie quais dados o agente pode acessar, quais ações ele pode realizar e o que acontece se ele se comportar de forma inesperada.

Instale o Elastic Agent Skills no tempo de execução do seu agente:

npx skills add elastic/agent-skills

Isso detecta automaticamente os runtimes instalados do agente e posiciona as habilidades no diretório de configuração correto. A partir daí, seu agente os coleta automaticamente.

Você também pode acessar diretamente o catálogo de habilidades e instalar habilidades individuais manualmente, copiando a pasta de habilidades para o diretório de configuração do agente.

Ainda não tem um cluster Elasticsearch? Inicie uma avaliação gratuita do Elastic Cloud. Leva cerca de um minuto para obter um ambiente totalmente configurado.

Explorar o projeto:

• Repositório de habilidades do agente
• Especificação agentskills.io
• Documentação do Elasticsearch
• Avaliação gratuita do Elastic Cloud

Como vimos na postagem anterior, a consistência proporcionada pela chamada de função não é apenas uma mera otimização; é essencial. Uma vez removidos os erros estruturais do ciclo de avaliação, os resultados em cenários padrão (como os do conjunto de dados de nível 4) melhoraram significativamente.

No entanto, há uma pergunta óbvia a ser respondida:

Essa abordagem ainda funciona quando as coisas realmente ficam confusas?

A resolução de entidades no mundo real raramente falha por causa de casos simples. Ela falha quando nomes cruzam línguas, culturas, sistemas de escrita, períodos de tempo e fronteiras organizacionais. Ela falha quando as pessoas são referenciadas por títulos em vez de nomes, quando as empresas mudam de nome, quando as transliterações não são consistentes e quando o contexto (não a ortografia) é a única coisa que vincula uma menção a uma entidade do mundo real.

Então, para o post final desta série, colocamos o sistema no que chamamos de desafio definitivo.

O que faz disso o desafio definitivo?

Em avaliações anteriores, testamos o sistema usando conjuntos de dados cada vez mais complexos. Quando chegamos ao nível 4, discutido no post anterior, já estávamos lidando com uma mistura de apelidos, títulos, nomes multilíngues e referências semânticas. Esses testes mostraram que a arquitetura em si era sólida, mas que problemas de confiabilidade, especialmente JSON malformado, estavam prejudicando o recall.

Com a chamada de função implementada, finalmente tivemos uma base estável. Isso nos deu a oportunidade de fazer uma pergunta mais interessante:

Um único pipeline unificado consegue lidar com vários tipos diferentes de problemas de resolução de entidades simultaneamente?

O conjunto de dados de desafio definitivo foi projetado para explorar precisamente essa dimensão.

Em vez de se concentrar em uma única dificuldade (como apelidos ou transliteração), este conjunto de dados combina mais de 50 tipos de desafios distintos, incluindo:

• Convenções culturais de nomeação.
• Referências baseadas em títulos.
• Relações comerciais e mudanças históricas de nome.
• Menções multilíngues e em diferentes sistemas de escrita.
• Desafios complexos que misturam vários dos itens acima.

O mais importante é que isso não se trata de otimizar para um caso de uso específico. Trata-se de testar se o padrão de design se sustenta quando as regras mudam de entidade para entidade.

Visão geral do conjunto de dados

O conjunto de dados de desafio definitivo consiste em:

• 50 entidades, abrangendo pessoas, organizações e instituições.
• Cerca de 60 artigos, com estrutura e complexidade linguística variadas.
• 51 categorias distintas de desafios, agrupadas de forma ampla em:
  • Convenções culturais de nomeação.
  • Títulos e o contexto profissional.
  • Relacionamentos empresariais e organizacionais.
  • Desafios multilíngues e de transliteração.
  • Cenários combinados e casos limite.

No início da série, vimos que usar IA generativa (GenAI) para criar conjuntos de dados pode ser uma faca de dois gumes. Sem ele, reunir dados de teste suficientemente grandes e diversos seria extremamente difícil. Mas, se não for controlado, o modelo tende a simplificar demais as coisas.

Em uma etapa inicial de geração, por exemplo, descobrimos que o modelo incluía frases como "o presidente russo" como apelidos explícitos para Vladimir Putin. Isso pode parecer razoável hoje, mas anula o propósito de testar a resolução contextual. O que acontece se o artigo estiver discutindo a Rússia nos anos 1990? O sistema deve inferir a entidade correta a partir do contexto, não depender de um alias fixo.

Por esse motivo, este conjunto de dados foi deliberadamente projetado para que os atalhos não funcionem. Os pseudônimos não são explicitamente listados quando se espera que o sistema deduza o significado. Frases descritivas não são vinculadas previamente a entidades. As correspondências corretas frequentemente dependem do contexto em nível de artigo, não apenas do texto local.

Observação importante: embora demonstremos os recursos do sistema em diversos cenários, este ainda é um protótipo educacional. Os sistemas de produção que lidam com o monitoramento real de entidades sob sanção exigiriam validação adicional, verificações de conformidade, trilhas de auditoria e tratamento especializado para casos de uso sensíveis.

Por que esses cenários são difíceis?

No primeiro post desta série, apresentamos um exemplo simples, mas ambíguo: "A nova atualização do Swift chegou!" O desafio é que "Swift" pode corresponder a múltiplas entidades do mundo real, dependendo do contexto. Esse exemplo captura uma verdade mais ampla: a linguagem natural é inerentemente ambígua.

A resolução de entidades, portanto, não é apenas um problema de correspondência de strings. As pessoas normalmente se baseiam normalmente em conhecimento compartilhado, normas culturais e contexto situacional para resolver referências, e raramente percebemos que estamos fazendo isso.

Considere alguns casos comuns:

• Um título como “o presidente” não tem significado sem contexto geopolítico e temporal.
• O nome de uma empresa pode se referir a uma controladora, uma subsidiária ou uma marca anterior, dependendo de quando o artigo foi escrito.
• O nome de uma pessoa pode aparecer em diferentes ordens, sistemas de escrita ou transliterações, dependendo da língua e da cultura.
• A mesma frase pode se referir legitimamente a diferentes entidades em diferentes contextos, e o sistema deve ser capaz de rejeitar correspondências com a mesma confiança com que as aceita.

Não existe um conjunto único de regras que lide com tudo isso de forma clara. É por isso que este protótipo separa as responsabilidades de forma tão clara:

• O Elasticsearch reduz o conjunto de candidatos de forma eficiente e transparente.
• O LLM é usado apenas quando o julgamento é necessário e é obrigado a se explicar.
• Recuperação e raciocínio continuam sendo etapas distintas.

Essa separação se torna ainda mais importante à medida que a diversidade de tipos de desafios aumenta.

Como o sistema lida com a diversidade sem exceções específicas

Um dos resultados mais interessantes desta avaliação é o que não mudou:

• Não adicionamos lógica especial para nomes japoneses.
• Não adicionamos regras personalizadas para patronímicos árabes.
• Não adicionamos mapeamentos fixos para nomes históricos de empresas.

Em vez disso, o sistema se baseou nos mesmos elementos centrais apresentados anteriormente na série:

• Entidades enriquecidas por contexto indexadas para busca semântica.
• Recuperação híbrida (exata, alias e semântica) no Elasticsearch.
• Um pequeno e bem definido conjunto de correspondências candidatas.
• Julgamento de LLM restrito por chamada de função e esquemas mínimos.

Isso sugere que a flexibilidade do sistema vem da representação e da arquitetura, não de uma coleção de regras em constante crescimento.

Quando o sistema tem sucesso, é porque os candidatos certos são recuperados e o LLM tem contexto suficiente para explicar por que uma referência corresponde (ou não) a uma entidade específica.

Resultados: Como foi o desempenho?

No conjunto de dados de desafio definitivo, o sistema produziu os seguintes resultados gerais:

• Precisão: ~91%
• Recall: ~86%
• Pontuação F1: ~89%
• Taxa de aceitação em LLM: ~72%

Desempenho em diferentes tipos de desafio

A análise dos resultados por tipo de desafio revela pontos fortes e limitações:

O desempenho mais forte (100% na pontuação F1) foi observado em áreas como:

• Correspondência de entidades entre sistemas de escrita (cirílico, coreano e chinês).
• Cenários hebraicos (patronímicos, títulos profissionais, títulos religiosos, transliteração).
• Hierarquias de negócios (aeroespacial, manufatura diversificada, corporações multidivisionais).
• Títulos profissionais (acadêmicos, militares, políticos, religiosos).
• Cenários combinados em japonês envolvendo múltiplos sistemas de escrita.

Forte desempenho (pontuação F1 de 80–99%) incluiu:

• Figuras políticas internacionais (98%).
• Alterações históricas de nome (90%).
• Hierarquias empresariais complexas (89%).
• Nomes de empresas japonesas (93%).
• Transliteração entre escrituras (86%).
• Patrônimos árabes (86%).

Áreas mais desafiadoras incluíram:

• Transliteração avançada (chinês, coreano): 0% de pontuação F1.
• Certos cenários japoneses (honoríficos, ordem dos nomes, variação do sistema de escrita): ~67% F1.
• Alguns cenários árabes (nomes de empresas, referências institucionais): ~40% F1.

O que é importante aqui é por que o sistema teve dificuldades nesses casos. As falhas não foram causadas por problemas na abordagem geral, mas por limitações em componentes específicos, especialmente o modelo vetorial denso usado para busca semântica em determinados cenários multilíngues.

Como recuperação e julgamento estão claramente separados, melhorar o desempenho não exige reescrever o sistema. A substituição por um modelo de embeddings multilíngue mais capaz, o enriquecimento do contexto da entidade ou o refinamento das estratégias de recuperação melhoraria os resultados nessas categorias sem alterar a arquitetura central.

Do ponto de vista arquitetônico, essa é a verdadeira métrica de sucesso.

O que isso nos diz sobre o design

Olhando para trás na série, alguns padrões se destacam:

• A preparação é mais importante do que a combinação inteligente. Enriquecer entidades com contexto desde o início reduz drasticamente a ambiguidade depois.
• Os LLMs são mais valiosos como juízes, não como recuperadores. Pedir que expliquem por que uma combinação faz sentido é muito mais poderoso do que pedir que busquem.
• A confiabilidade possibilita precisão. A chamada de funções não apenas limpou o JSON; ela revelou o recall que já estava latente na etapa de recuperação.
• A generalização supera a especialização. Um pequeno número de abstrações bem definidas lidou com dezenas de tipos de desafios sem lógica personalizada.

Por isso, o protótipo é intencionalmente nativo do Elasticsearch e conservador na forma como utiliza LLMs. O objetivo não é substituir a busca; é tornar a busca explicável em situações onde o significado importa.

Conclusão

O desafio final não era buscar métricas perfeitas; era sobre responder a uma pergunta mais fundamental:

Uma arquitetura transparente, orientada para busca e assistida por LLM, pode lidar com a ambiguidade de entidades no mundo real sem se limitar a regras ou caixas-pretas?

Para este protótipo educacional, a resposta é sim, com claras ressalvas sobre robustez para produção, conformidade, monitoramento e qualidade dos dados. Se você estiver criando sistemas que precisem justificar por que foi feita uma correspondência de entidade, vale a pena considerar seriamente esse padrão. Espero que esta série tenha mostrado que a resolução de entidades não precisa ser algo misterioso. Com a separação certa das preocupações, torna-se algo sobre o qual você pode refletir, medir e melhorar.

Este trabalho também sugere um padrão arquitetônico mais amplo. O que surge é uma leve, mas importante, evolução da Retrieval-Augmented Generation (RAG). Em vez de permitir que a recuperação alimente diretamente a geração, introduzimos uma etapa explícita de avaliação. O LLM é usado primeiro para avaliar e verificar a consistência dos candidatos recuperados, e apenas os resultados aprovados podem ampliar a geração. Você pode pensar nisso como Retrieval-Augmented Generation com Avaliação, ou GARAGE, porque quem não gosta de uma boa sigla.

Quais outros casos de uso poderiam se beneficiar desse padrão? Sistemas que exigem confiança, transparência e raciocínio defensável são candidatos naturais. Trabalhos futuros nessa área devem ser tão interessantes quanto os resultados que vimos aqui, e estou entusiasmado para ver para onde a comunidade vai levar isso a seguir.

Próximos passos: Experimente por conta própria

Quer ver o desafio definitivo em ação? Confira o Notebook do desafio definitivo para ver um passo a passo completo, com implementações reais, explicações detalhadas e exemplos práticos.

O pipeline completo de resolução de entidades demonstra os conceitos centrais e a arquitetura necessários para uso em produção. Você pode usá-lo como base para construir sistemas que monitorem artigos de notícias, rastreiem menções de entidades e respondam a perguntas sobre quais entidades aparecem em quais artigos, tudo isso mantendo transparência e explicabilidade.

No HNSW, a busca prossegue expandindo iterativamente os nós candidatos no gráfico, mantendo um conjunto limitado de vizinhos mais próximos descobertos até então. Cada expansão tem um custo (operações vetoriais, acessos aleatórios ao disco, e mais), e o benefício marginal desse custo tende a diminuir conforme a busca avança.

Uma forma de otimizar a travessia de gráficos HNSW é parar de buscar quando a probabilidade marginal de encontrar novos vizinhos verdadeiros não aumenta. Por essa razão, no Elasticsearch 9.2 introduzimos um novo mecanismo de terminação antecipada. Isso interrompe o processo de busca quando visitar nós do gráfico não fornece vizinhos novos mais próximos suficientes, consecutivamente, por um número fixo de vezes.

Este artigo mostra como aprimoramos o mecanismo de terminação antecipada mencionado no HNSW para torná-lo mais adequado para diferentes conjuntos de dados e distribuições de dados.

Terminação antecipada no HNSW

No HNSW, a busca prossegue expandindo iterativamente os nós candidatos no gráfico de proximidade, mantendo um conjunto limitado de vizinhos mais próximos descobertos até então, até que tenha visitado todo o gráfico ou atenda a alguns critérios iniciais de parada.

Portanto, a terminação antecipada nem sempre é necessariamente uma otimização, faz parte do próprio algoritmo de busca. O momento em que decidimos parar determina o equilíbrio entre eficiência e recall. No Elasticsearch, já existem várias maneiras de uma consulta no HNSW terminar antecipadamente:

• Um número máximo fixo de nós é visitado.
• Um tempo limite fixo é atingido.

Embora simples e previsíveis, essas regras são em grande parte agnósticas em relação ao que a busca realmente está fazendo. Além disso, elas são usadas principalmente para garantir que a consulta seja concluída em um tempo razoável para o usuário final.

Em uma postagem anterior do blog, apresentamos o conceito de redundância no HNSW. Em resumo, cálculos redundantes ocorrem quando o HNSW continua a avaliar novos nós candidatos que não resultam em encontrar mais vizinhos mais próximos.

Paciência: Medindo progresso em vez de esforço

A noção de paciência reformula a terminação antecipada, focando no progresso em vez do esforço.

Em vez de perguntar:

"Quantos passos já demos?"

A nova pergunta passa a ser:

“Qual é a quantidade de computação que aceitamos desperdiçar até perdermos a esperança?”

Durante a busca HNSW, a exploração precoce normalmente produz melhorias de pico no conjunto de candidatos top-k. Durante as primeiras etapas da exploração do gráfico HNSW, o conjunto de vizinhos é continuamente atualizado à medida que o algoritmo continua descobrindo vizinhos cada vez mais próximos do vetor de consulta. Com o tempo, essas melhorias se tornam mais raras à medida que a busca converge. A terminação antecipada baseada em paciência monitora esse padrão e finaliza a busca assim que as melhorias cessarem por um período prolongado.

Na prática, ao visitar o gráfico HNSW, também calculamos a razão de saturação da fila ao pular entre os nós candidatos. Isso mede a porcentagem de vizinhos mais próximos que permaneceram inalterados ao visitar o nó mais recente do gráfico (ou o inverso do número de novos vizinhos introduzidos na última iteração). Quando essa proporção se torna grande demais para muitas iterações consecutivas, paramos de visitar o gráfico.

Conceitualmente, a paciência trata a busca HNSW como um processo de retornos decrescentes. Quando os retornos se estabilizam, continuar explorando o gráfico traz pouco benefício.

Esse enquadramento é poderoso porque vincula a interrupção diretamente a resultados observáveis, e não a limites fixos arbitrários.

A vantagem de usar essa técnica inteligente de terminação antecipada é que as explorações do gráfico HNSW tendem a visitar um número menor de nós gráficos, mantendo uma taxa de recall quase perfeita.

Para visualizar isso, podemos visualizar em um gráfico a quantidade de recall por nó visitado que obtivemos com a terminação antecipada baseada em paciência (rotulada como et=static), quando comparada ao comportamento padrão do HNSW (rotulado como et=no) em alguns conjuntos de dados, FinancialQA e Quora, e modelos, JinaV3 e E5-small.

Limiares estáticos e dinâmicas do HNSW

Na prática, no Elasticsearch, isso é implementado usando limites estáticos. Um limite refere-se ao limite de saturação, ou seja, a proporção de saturação que consideramos abaixo do ideal. O outro limite refere-se ao número de nós de gráfico consecutivos que permitimos serem visitados enquanto ainda mantêm uma saturação de fila abaixo do ideal: ou seja, o limiar de paciência.

Quando introduzimos essa estratégia de terminação antecipada no Elasticsearch 9.2, decidimos optar por padrões conservadores, de modo a preservar o recall o máximo possível, enquanto ainda obtemos ganhos em termos de latência e consumo de memória. Por esse motivo, definimos o limiar de saturação para 100% e o limiar de paciência para ser definido como 30% (limitado) do num_candidates na consulta KNN.

Em muitos cenários, essas configurações funcionaram bem; no entanto, duas consultas que solicitam o mesmo número de vizinhos podem ter comportamentos de convergência radicalmente diferentes. Algumas consultas encontram vizinhanças locais densas e saturam rapidamente; outras precisam percorrer caminhos longos e esparsos antes de encontrar candidatos competitivos. Este último mostrou-se o mais difícil de lidar de forma eficaz.

Como resultado, por vezes notamos:

• Exploração excessiva para consultas fáceis.
• Encerramento prematuro para consultas complexas.

Portanto, descobrimos que valores de limite fixos codificam suposições globais sobre convergência, enquanto poderíamos fazer com que o HNSW se adaptasse melhor a diferentes dinâmicas.

Tornando o HNSW adaptativo à terminação antecipada

A terminação antecipada adaptativa aborda esse problema de um ângulo diferente. Em vez de impor limiares de parada pré-definidos, o algoritmo infere quando parar a partir da própria dinâmica da busca.

Então, em vez de comparar a taxa de saturação da fila entre dois candidatos consecutivos, decidimos introduzir uma taxa de descoberta instantânea suavizada  $d_{q,i} $ (quantos novos vizinhos foram introduzidos para uma consulta q,na última visita i) junto com a média móvel $\ mu_{q,i}$ e o desvio padrão $\sigma_{q,i}$ dessa taxa de descoberta durante a visita ao gráfico (usando o algoritmo de Welford). Essas estatísticas sobre a taxa de descoberta são calculadas por consulta, de modo que essas informações podem ser usadas para determinar diferentes níveis de paciência para cada consulta.

Os limites anteriormente estáticos se tornam adaptáveis às estatísticas da taxa de descoberta: o limite de saturação se torna a média contínua mais o desvio padrão; enquanto fazemos com que a paciência se adapte e redimensione inversamente com o desvio padrão.

As regras de saída antecipada permanecem as mesmas; a saturação ocorre quando a taxa de descoberta instantânea é menor que o limite de saturação adaptativa. A visita ao gráfico é interrompida se a saturação persistir por um número consecutivo de visitas candidatas maior que a paciência adaptativa.

Dessa forma, obtemos um comportamento que não depende do parâmetro num_candidates na consulta KNN (que pode estar sempre definido ou deixado como padrão, independentemente de sair cedo) e que se adapta melhor a cada consulta e distribuição vetorial de forma dinâmica.

O recall por nó visitado no FinancialQA e Quora com a estratégia adaptativa (rotulada como et=adaptive) apresenta um recall maior por nó visitado, quando comparado à estratégia estática (et=static) e ao comportamento padrão do HNSW (et=no).

A terminação antecipada adaptativa está ativada por padrão no Elasticsearch 9.3 para campos vetoriais densos HNSW (e pode ser desativada posteriormente por meio da mesma configuração no nível do índice).

Integrações configuram entradas do Filebeat para realizar a coleta de dados. Para coletar dados de APIs HTTP, usamos a entrada HTTP JSON. No entanto, mesmo APIs básicas de listagem podem diferir bastante nos detalhes, e o modelo de transformações configuradas em YAML da entrada HTTP JSON pode tornar difícil e, às vezes, impossível expressar a lógica de coleta necessária.

A entrada em linguagem de expressão comum (CEL) foi introduzida para permitir uma interação mais flexível com as APIs HTTP. A CEL é uma linguagem projetada para ser incorporada em aplicações que exigem uma maneira rápida, segura e extensível de expressar condições e transformações de dados. A entrada CEL permite que um desenvolvedor de integrações escreva uma expressão capaz de ler configurações, controlar o próprio estado, fazer solicitações, processar respostas e, por fim, retornar eventos prontos para serem ingeridos.

Neste artigo, vamos analisar como a CEL difere de outras linguagens de programação, como a estendemos para a entrada CEL, e a flexibilidade e o poder que isso oferece para expressar sua lógica de coleta de dados.

CEL e como funciona na entrada

A CEL é uma linguagem de expressões. Não possui instruções. Quando você escreve CEL, não indica o que fazer escrevendo instruções, mas sim qual valor produzir ao escrever uma expressão. Cada expressão CEL produz um valor, e expressões menores podem ser combinadas em uma expressão maior para produzir um resultado de acordo com regras mais complexas. Mais adiante, veremos como usar expressões para coisas que podem ser escritas com instruções em outras linguagens.

CEL é intencionalmente uma linguagem não Turing completa. Não permite loops ilimitados. Posteriormente, veremos como você pode processar listas e mapas usando macros, mas, ao evitar loops ilimitados, a linguagem garante um tempo de execução previsível e limitado para expressões individuais.

A entrada CEL é configurada com um programa CEL (uma expressão) e algum estado inicial. O estado será fornecido como entrada para o programa. O programa é avaliado para produzir um estado de saída. Se o estado de saída incluir uma lista de eventos, esses serão removidos e publicados. O restante do estado de saída será usado como entrada para a próxima avaliação. Se o estado de saída incluir um ou mais eventos e a bandeira want_more: true, a próxima avaliação será realizada imediatamente; caso contrário, ele irá hibernar pelo restante do intervalo configurado antes de continuar. Veja um diagrama simplificado do fluxo de controle da entrada:

A saída de cada avaliação será passada como entrada para a próxima avaliação, enquanto a entrada for executada. Os dados de saída com a chave "cursor" serão mantidos no disco e recarregados após a reinicialização da entrada, mas o restante do estado não será preservado durante as reinicializações.

A linguagem CEL em si tem funcionalidade limitada e evita efeitos colaterais, mas é extensível. A implementação do cel-go acrescenta algumas funcionalidades, como sintaxe e tipos opcionais. A biblioteca Mito se baseia no cel-go e adiciona mais funcionalidades, incluindo a capacidade de fazer solicitações HTTP. A entrada da CEL usa a versão da CEL do Mito.

Trabalhando com Mito

Para criar ou fazer debug de uma integração usando a entrada CEL, o mais importante é entender qual estado de saída o seu programa CEL produzirá para um determinado estado de entrada. Durante o desenvolvimento, pode ser complicado executar o seu programa CEL pela entrada, cercado pela stack completa do Elastic. Uma maneira de ter um ciclo de feedback mais rápido é usar a ferramenta de linha de comando do Mito, que permite executar diretamente um programa CEL e ver a saída que ele produz para uma entrada específica.

Mito é escrito em Go e pode ser instalado da seguinte forma:

go install github.com/elastic/mito/cmd/mito@latest

Quando você executa um programa CEL com o Mito, normalmente fornece a ele dois arquivos: um arquivo JSON com o estado de entrada inicial e outro arquivo com o código-fonte do seu programa CEL:

mito -data state.json src.cel

Para facilitar o copiar e colar, os exemplos neste artigo são escritos como comandos únicos que fazem com que o shell crie arquivos temporários em tempo real, agrupando o conteúdo de cada arquivo em <(echo '...content...'). No seu próprio desenvolvimento, trabalhar com arquivos reais será mais fácil.

Busca de dados de problemas do GitHub

O exemplo a seguir inclui um programa CEL completo que buscará dados sobre problemas na API do GitHub. Seu estado de entrada inicial tem uma URL para o endpoint da API e algumas informações sobre como se deve lidar com a paginação. O programa CEL usa os dados no estado de entrada para gerar uma solicitação. Ele decodificará a resposta, produzirá eventos a partir dela e os retornará como parte de seu estado de saída.

mito -data <(echo '
  {
    "url": "https://api.github.com/repos/elastic/integrations/issues",
    "per_page": 3,
    "max_pages": 3
  }
') <(echo '
  int(state.?cursor.page.orValue(1)).as(page,
    (
      state.url + "?" + {
        "state": ["all"],
        "sort": ["created"],
        "direction": ["asc"],
        "per_page": [string(state.per_page)],
        "page": [string(page)],
      }.format_query()
    ).as(full_url,
      request("GET", full_url).with({
        "Header": {
          "Accept": ["application/vnd.github+json"],
          "X-GitHub-Api-Version": ["2022-11-28"],
        }
      }).do_request().as(resp,
        resp.Body.decode_json().as(data,
          state.with({
            "events": data.map(i, {
              "html_url": i.html_url,
              "title": i.title,
              "created_at": i.created_at,
            }),
            "cursor": { "page": page + 1 },
            "want_more": size(data) == state.per_page && page < state.max_pages,
          })
        )
      )
    )
  )
')

Sua primeira avaliação produz a seguinte saída:

{
  "cursor": {
    "page": 2
  },
  "events": [
    {
      "created_at": "2018-09-14T09:47:35Z",
      "html_url": "https://github.com/elastic/integrations/issues/3250",
      "title": "Increase support of log formats in haproxy filebeat module"
    },
    {
      "created_at": "2019-02-06T12:37:37Z",
      "html_url": "https://github.com/elastic/integrations/issues/487",
      "title": "ETCD Metricbeat module needs polishing and grooming"
    },
    {
      "created_at": "2019-08-13T11:33:11Z",
      "html_url": "https://github.com/elastic/integrations/pull/1",
      "title": "Initial structure"
    }
  ],
  "max_pages": 3,
  "per_page": 3,
  "url": "https://api.github.com/repos/elastic/integrations/issues",
  "want_more": true
}

Os eventos serão removidos e, quando executados na entrada CEL, serão publicados para ingestão. O restante da saída será fornecido para a próxima avaliação do programa CEL como seu estado de entrada.

Para entender como esse programa CEL funciona, vamos analisar alguns exemplos menores de CEL e discutir mais detalhes sobre como a entrada CEL funciona.

Noções básicas do CEL

Na linguagem CEL, não há declarações; só existem expressões. Cada expressão CEL bem-sucedida é avaliada para um valor final. Aqui está uma das menores expressões de CEL que você pode escrever, junto com sua saída:

mito <(echo '
  "hello" + " " + "world"
')

"hello world"

Muitas expressões simples são intuitivas. Operações matemáticas são suportadas apenas em valores do mesmo tipo (por exemplo, int com int), então converta os tipos conforme necessário (aqui de int para double):

mito <(echo '
  double((1 + 2) * (3 + 4)) / 2.0
')

10.5

Não há variáveis na linguagem CEL, mas uma expressão pode receber um nome e ser usada em uma expressão maior com a ajuda da macro as de Mito. Neste exemplo, a expressão (1 + 1) avalia para o valor 2, e .as(n, ...) dá a esse valor o nome n para uso na expressão "one plus one is "+string(n):

mito <(echo '
  (1 + 1).as(n, "one plus one is "+string(n))
')

"one plus one is 2"

Também é possível acumular informações em um mapa e utilizá-las posteriormente na expressão, como demonstrado aqui usando with:

mito <(echo '
  { "key": "value" }.with({ "key2": "value2" }).as(data,
    {
      "data": data,
      "size": size(data),
    }
  )
')

{
  "data": {
    "key": "value",
    "key2": "value2"
  },
  "size": 2
}

Observe esse exemplo novamente. Note que a parte aninhada, ({ "data": data, "size": size(data), }), nos dá a forma do valor final. É um mapa com as chaves "data" e "size". Os valores dessas chaves dependem de data, que é definido pela parte externa da expressão. Ler as expressões da CEL de dentro para fora pode ajudar a ver o que elas vão retornar.

A CEL não possui instruções de fluxo de controle, como if, mas a ramificação condicional pode ser feita com o operador ternário:

mito <(echo '
  1 + 1 < 12 ? "few" : "many"
')

"few"

Ciclos ilimitados e recursão não são compatíveis, pois a CEL não é uma linguagem de Turing completa. Isso torna o tempo de execução previsível e proporcional ao tamanho dos dados de entrada e à complexidade da expressão.

Embora ciclos ilimitados não sejam possíveis em expressões CEL individuais, você pode processar listas e mapas usando macros como map:

mito <(echo '
  [1, 2, 3].map(x, x * 2)
')

[2, 4, 6]

Nesta seção, abordamos:

• Strings, números, listas e mapas.
• Concatenação de strings.
• Operações matemáticas.
• Conversão de tipo.
• Condicionais.
• Nomeando subexpressões.
• Processando coleções.

Em seguida, veremos como fazer solicitações HTTP.

Requisições

O Mito estende a CEL com a capacidade de fazer requisições HTTP:

mito <(echo '
  get("https://example.com").as(resp, string(resp.Body))
')

"..."

As requisições podem ser construídas explicitamente antes de serem executadas. Isso possibilita o uso de diferentes métodos HTTP e a adição de cabeçalhos e corpo da requisição.

Neste exemplo, criamos uma URL com a ajuda de format_query, adicionamos um cabeçalho à solicitação e analisamos o corpo da resposta com decode_json. Quando você receber a opção -log_requests, o Mito loga informações detalhadas no formato JSON sobre cada requisição e resposta.

mito -log_requests <(echo '
  request("GET",
    "https://postman-echo.com/get?" + {
        "q": ["query value"]
     }.format_query()
  ).with({
    "Header": { "Accept": ["application/json"] }
  }).do_request().as(resp, {
    "status": resp.StatusCode,
    "data": resp.Body.decode_json(),
  })
')

{"time":"...","level":"INFO","msg":"HTTP request",...}
{"time":"...","level":"INFO","msg":"HTTP response",...}
{
  "data": {
    "args": {
      "q": "query value"
    },
    "headers": {
      "accept": "application/json",
      "accept-encoding": "gzip, br",
      "host": "postman-echo.com",
      "user-agent": "Go-http-client/2.0",
      "x-forwarded-proto": "https"
    },
    "url": "https://postman-echo.com/get?q=query+value"
  },
  "status": 200
}

Gestão do estado e avaliações

Agora que abordamos como fazer requisições e os fundamentos da CEL necessários para produzir o estado de saída desejado, vamos dar uma olhada mais detalhada no que devemos colocar no estado de saída e como isso nos permite direcionar o processamento posterior.

O programa CEL de uma integração precisa garantir que o estado de saída seja adequado para uso como entrada na próxima avaliação. A configuração define o estado inicial, que deve ser repetido na saída com quaisquer mudanças apropriadas. Uma maneira fácil de fazer isso é usar state.with({ ... }), para repetir o mapa de estados com algumas sobrescrições. Um padrão comum para programas pequenos é envolver o programa inteiro em state.with(), para que a propagação de estados não precise ser repetida em cada ramo que gera dados de saída (por exemplo, sucesso, erros).

Quando há valores de estado inicializados por uma avaliação em vez de codificados fixamente no estado inicial de entrada, o programa precisará verificar um valor existente antes de definir o inicial. Isso é algo em que o suporte para sintaxe e tipos opcionais pode ajudar. Ao usar um ponto de interrogação antes do nome do campo em uma chave de mapa, o acesso torna-se opcional: pode ou não resolver para um valor, mas acessos opcionais adicionais são possíveis e é fácil fornecer um padrão se não houver valor presente:

mito -data <(echo '{}') <(echo '
  int(state.?counter.orValue(0)).as(counter,
    state.with({
      "counter": counter + 1,
      "want_more": counter + 1 < 3,
    })
  )
')

{ "counter": 1, "want_more": true }
{ "counter": 2, "want_more": true }
{ "counter": 3, "want_more": false }

Nesse exemplo, o valor contador lido do estado é convertido para int porque todos os números são serializados no estado como números de ponto flutuante, de acordo com as convenções estabelecidas pelo tipo de Number do JSON e JavaScript. Também deve ser notado que "want_more": true é respeitado aqui pelo Mito, mas quando executado na entrada CEL, a avaliação só será repetida se a saída também contiver eventos.

É uma exigência dos programas CEL executados pela entrada CEL que retornem uma chave "events" no mapa de saída. O valor pode ser uma lista de mapas de eventos, uma lista vazia ou um único mapa de eventos. O caso de evento único geralmente é usado para erros. O evento será publicado pela entrada, mas seu valor também será log, e se definir um valor error.message , ele será usado para atualizar o status de saúde da Fleet da integração. Se seu programa gerar um único evento que não seja erro, é melhor agrupá-lo em uma lista.

Confira novamente a saída anterior do nosso programa de problemas do GitHub:

{
  "url": "https://api.github.com/repos/elastic/integrations/issues",
  "per_page": 3,
  "max_pages": 3,
  "cursor": {
    "page": 2
  },
  "events": [
    { ... },
    { ... },
    { ... }
  ],
  "want_more": true
}

O programa gerenciou efetivamente o estado por:

• Repetindo valores de estado inicial em url, per_page e max_pages.
• Adicionando estados que devem ser mantidos durante reinícios em cursor.page.
• Eventos de retorno prontos para serem publicados na lista events.
• Solicitar reavaliação imediata com want_more: true.

Agora que você entende o acesso opcional e o gerenciamento de estado, bem como os conceitos básicos da CEL e as solicitações HTTP, o programa completo de problemas do GitHub deve estar legível. Tente executar o programa com o Mito e experimente algumas alterações.

Revisão e recursos

Neste artigo, analisamos o que é a CEL e como ela foi estendida na biblioteca Mito para uso na entrada CEL. Observamos a flexibilidade da CEL em um programa de exemplo que busca informações de problemas na API do GitHub e analisamos todos os detalhes necessários para entender esse programa, abrangendo o acesso às configurações no estado inicial, a interação com APIs HTTP, o retorno de eventos a serem ingeridos e o gerenciamento do estado para execuções posteriores do programa.

Para aprender mais e construir integrações usando a entrada da CEL, há vários recursos que valem a pena explorar:

• Entrada CEL - Documentação do Filebeat
• Documentação Mito
• Linguagem de expressão comum - website cel.dev
• Crie uma Integração - Documentação Elastic

E talvez o recurso mais valioso para criar integrações com a entrada CEL seja o código CEL das integrações existentes do Elastic, que pode ser encontrado no GitHub:

cel.yml.hbs arquivos no repositório de integrações Elastic - GitHub

1. A nova atualização do Swift chegou! Os desenvolvedores estão ansiosos para experimentar os novos recursos.
2. A nova atualização do Swift chegou! O novo álbum será lançado no próximo mês.

Com esse contexto adicional, devemos conseguir resolver o nome "Swift" para a entidade correta.

Na postagem anterior, configuramos nossa lista de observação e enriquecemos as entidades com contexto adicional. Olhando nossos exemplos acima, precisamos ter pelo menos as seguintes duas entidades na lista: Taylor Swift e Swift Programming Language. Também abordamos como extraímos menções a entidades do texto. Ambos os exemplos extrairiam "Swift". Com esses ingredientes prontos, a lista de observação enriquecida e as entidades extraídas, finalmente estamos prontos para apresentar a estrela do show: a correspondência de entidades.

Lembre-se: este é um protótipo educacional projetado para ensinar conceitos de correspondência de entidades. Os sistemas de produção podem usar diferentes modelos de linguagem grande (LLMs), regras de correspondência personalizadas, pipelines de julgamento especializados ou abordagens de conjunto que combinam várias estratégias de correspondência.

O problema: por que a correspondência é difícil

A linguagem humana é algo extraordinário. Uma das propriedades mais interessantes é sua criatividade infinita. Podemos gerar e entender um número infinito de novas frases. Será que é de se estranhar, então, que correspondências exatas na resolução das entidades sejam raras? Autores se esforçam para ser criativos quando podem. Ficaria bastante cansativo se tivéssemos que escrever e ler nomes completos sempre que uma entidade fosse mencionada. Portanto, embora as correspondências exatas sejam fáceis, a realidade é que precisamos de uma abordagem mais sofisticada para a resolução de entidades: uma que seja robusta o suficiente para lidar com pelo menos parte da criatividade ilimitada de autores humanos. Por isso, dividimos o problema em duas etapas: usar o Elasticsearch para recuperar candidatos plausíveis em larga escala, e depois usar um LLM para julgar se esses candidatos realmente se referem à mesma entidade do mundo real.

A solução: correspondência em três etapas com julgamento transparente do LLM

Estamos no meio de uma mudança de paradigma na forma como usamos computadores. Assim como a ascensão da Internet nos levou da computação localizada para uma rede conectada globalmente, a IA generativa (GenAI) está mudando fundamentalmente a forma como o conteúdo, o código e as informações são criados. Na verdade, o protótipo educacional que acompanha essa série foi quase exclusivamente "codificado por vibração" usando um LLM, com orientação cuidadosa do autor. Isso não quer dizer que os LLMs tenham ou que alcançarão o tipo de produtividade inerente à linguagem humana, mas significa que agora temos um recurso poderoso para ajudar na resolução de entidades.

Um padrão comum que usamos com GenAI é a retrieval augmented generation (RAG). Aqui, retrieval significa recuperar entidades candidatas (não gerar respostas), e o LLM é usado estritamente para avaliação e explicação da correspondência. Embora pudéssemos pedir a um LLM para nos ajudar com a resolução de entidades de ponta a ponta, essa abordagem é dispendiosa, tanto em termos de tempo quanto de dinheiro. A RAG ajuda os LLMs a realizar seu trabalho usando maneiras mais eficientes de fornecer contexto ao LLM, capacitando-o a auxiliar de forma eficiente na resolução de entidades.

Para a parte de recuperação do RAG, voltamos novamente ao Elasticsearch. Primeiro, encontramos possíveis correspondências usando uma combinação de correspondência exata, correspondência com aliases e busca híbrida, que combina busca semântica e por palavra-chave. Assim que encontramos essas possíveis correspondências, as enviamos para um LLM para julgamento. O LLM atua como avaliador final de correspondência. Também fazemos o LLM explicar seu raciocínio, um diferenciador importante em relação a outros sistemas de resolução de entidades. Sem essas explicações, a resolução de entidades é uma caixa preta; com elas, podemos ver por nós mesmos por que uma correspondência faz sentido.

Conceitos-chave: correspondência em três etapas, busca híbrida e julgamento transparente de LLM

O que é a correspondência em três etapas? No início deste projeto, hipotetizamos que a busca semântica será uma parte crucial do sistema, mas nem toda correspondência exige uma busca tão sofisticada. Para encontrar correspondências de forma eficiente, adotamos uma abordagem progressiva ao problema. Primeiro, verificamos correspondências exatas usando busca por palavras-chave. Se encontrarmos essa correspondência, nosso trabalho estará feito e poderemos seguir em frente. Se a correspondência exata falhar, recorremos à correspondência de alias. No protótipo, a correspondência de alias também é feita usando correspondência exata com palavras-chave, para simplificar. Na produção, você pode expandir essa etapa com normalização, regras de transliteração, correspondência fuzzy ou tabelas de alias curadas. Se ainda não encontramos uma possível correspondência nas duas primeiras etapas, é hora de introduzir a busca semântica por meio da busca híbrida do Elasticsearch com fusão recíproca de classificação (RRF).

O que é busca híbrida? No Elasticsearch, podemos usar a busca semântica para encontrar correspondências significativas que levem em conta o contexto. O Elasticsearch é amplamente utilizado para busca vetorial e recuperação híbrida. A semelhança semântica é poderosa para o significado, mas não substitui a filtragem estruturada (por exemplo, por intervalos de tempo, locais ou identificadores) e geralmente é desnecessária quando uma correspondência exata está disponível. O Elasticsearch se destacou com a busca lexical, que é ótima em tarefas onde a busca semântica não se encaixa. Para aproveitar ao máximo ambas as abordagens, usamos a busca lexical junto com a busca semântica em uma única consulta híbrida. Depois, juntamos os resultados para encontrar as correspondências mais prováveis usando o RRF. No protótipo, os dois melhores resultados tornam-se correspondências potenciais que podem ser enviadas para avaliação do LLM.

Por que julgamento de LLM? Julgamentos e explicações de LLM permitem que nosso sistema trate ambiguidade e contexto de forma transparente. Isso é vital para casos como "o presidente", que pode se referir a múltiplas entidades, dependendo do contexto, mas também faz com que apelidos e variações culturais funcionem bem no sistema. Finalmente, quando consideramos tarefas de missão crítica, como identificar entidades a partir de listas de sanções, precisamos saber por que uma combinação foi aceita para confiar no sistema. Crucialmente, o LLM não busca o corpus completo; ele avalia apenas o pequeno conjunto de candidatos retornados pelo Elasticsearch.

Resultados do mundo real: correspondência com raciocínio de LLM

Um dos principais desafios de qualquer tarefa de processamento de linguagem natural é a criação de um documento de referência, um "gabarito" que nos diga quais são os resultados esperados. Sem isso, é praticamente impossível avaliar o desempenho de um sistema em uma tarefa, mas criar um documento desse tipo pode ser um processo trabalhoso. Para o protótipo de resolução de entidades, recorremos novamente à GenAI para nos ajudar a configurar os dados que pudéssemos usar para os testes.

Primeiro, definimos vários tipos de desafios, como apelidos e transliteração, e então pedimos ao LLM para criar uma coleção em camadas de conjuntos de dados que se tornariam progressivamente maiores e mais desafiadores para o sistema. A criação dos conjuntos de dados foi menos simples do que se esperava. O LLM tinha uma forte propensão para "trapacear" ao tornar muito fácil obter a resposta certa. Por exemplo, um dos tipos de desafio focou no contexto semântico. Este tipo incluiu coisas como resolver "autor russo" para "Liev Tolstói". O LLM incorretamente colocou "autor russo" como um alias para "Leo Tolstoy", o que negou a necessidade de uma busca híbrida para encontrar a correspondência.

Após várias refatorações para corrigir problemas como esse, tínhamos cinco níveis de conjunto de dados para trabalhar. Os níveis 1 a 4 eram progressivamente maiores, com mais tipos de desafio. O Tier 5 era o conjunto de dados do "desafio supremo", composto pelos exemplos mais difíceis de todos os tipos de desafio. Todos os dados dos testes estão disponíveis no diretório de avaliação completo.

Para avaliar nossa abordagem de resolução de entidades baseada em prompts, focamos nossa atenção no conjunto de dados de nível 4. Um ponto importante é que a avaliação foi realizada como um experimento controlado para que pudéssemos focar na qualidade da correspondência de entidades. Os dados da lista de observação foram pré-enriquecidos com contexto, e as entidades foram extraídas do artigo antecipadamente. Isso garantiu que a avaliação fosse focada em correspondência, e não na precisão da extração. Isso isola a qualidade da correspondência; o desempenho de ponta a ponta também dependeria da qualidade do recall e do enriquecimento da extração.

Conjunto de dados de avaliação

O conjunto de dados de avaliação de nível 4 fornece um teste abrangente das capacidades do sistema:[1]

• Entidades da lista de observação: 66 entidades de diversos tipos (pessoas, organizações, locais).
• Artigos de teste: 69 artigos que abrangem cenários reais de resolução de entidades.
• Correspondências esperadas: 206 correspondências de entidades esperadas em todos os artigos.
• Tipos de desafio: 15 tipos diferentes de desafio que testam vários aspectos da resolução de entidades.

Os tipos de desafios incluídos no conjunto de dados são:

• Apelidos: "Bob Smith" → "Robert Smith" (sete artigos).
• Títulos e honoríficos: "Dr. Sarah Williams" → "Sarah Williams" (cinco artigos).
• Contexto semântico: "autor russo" → "Liev Tolstói" (oito artigos).
• Nomes multilíngues: manuseio de nomes em diferentes scripts (seis artigos).
• Entidades empresariais: variações de nome corporativo (sete artigos).
• Referências executivas: "CEO da Microsoft" → "Satya Nadella" (cinco artigos).
• Líderes políticos: referências baseadas em títulos (cinco artigos).
• Iniciais: "J. Smith" → "John Smith" (três artigos).
• Variações na ordem dos nomes: diferentes convenções de ordenação de nomes (três artigos).
• Nomes truncados: correspondências parciais de nomes (três artigos).
• Divisão de nomes: nomes divididos no texto (três artigos).
• Falta de espaços/hífens: variações de formatação (dois artigos).
• Transliteração: correspondência de nomes entre escrituras (dois artigos).
• Desafios combinados: Vários desafios em um único artigo (seis artigos).
• Negócios complexos: relações comerciais hierárquicas (cinco artigos).

Vamos ver como a resolução de entidades baseada em prompts foi realizada.

Desempenho geral

Os resultados mostram que a avaliação de correspondência baseada no LLM é muito promissora, mas também revelam um problema significativo de confiabilidade. Como cada par de candidatos deve ser avaliado pelo LLM, falhas na saída estruturada podem suprimir a aceitação e a recuperação, mesmo quando a recuperação está funcionando bem.

O problema da taxa de erro

Lembre-se de que o primeiro passo que damos no protótipo é criar potenciais pares de correspondência usando o Elasticsearch. Cada uma dessas possíveis correspondências precisa ser avaliada pelo LLM. Para processar eficientemente todas essas correspondências, agrupamos as chamadas de LLM em lote. Isso reduz os custos da API e a latência, mas também há um risco aumentado de obter JSON malformado na saída. À medida que o tamanho do lote aumenta, o JSON se torna mais longo e complexo, tornando mais provável que o LLM gere JSON inválido. É daí que decorre a taxa de erro de 30%. Na avaliação, usamos um tamanho de lote de cinco correspondências por solicitação. Mesmo com este tamanho de lote conservador, ainda vemos falhas na análise JSON, o que distorce significativamente os resultados da avaliação.

O que vem a seguir: otimização da integração com LLMs

Agora que combinamos entidades usando busca semântica e julgamento de LLM, temos um pipeline completo de resolução de entidades. Essa abordagem introduz um novo modo de falha, no entanto, quando o julgamento do modelo está correto, mas sua saída não é utilizável. Podemos otimizar a integração do LLM para maior confiabilidade e eficiência de custos. No próximo post, exploraremos como usar o chamado de função para saída estruturada, que garante estrutura e segurança de tipos, ao mesmo tempo em que reduz erros e custos.

Experimente você mesmo

Quer ver a correspondência de entidades em ação? Confira o notebook do Entity Matching para ver um passo a passo completo com implementações reais, explicações detalhadas e exemplos práticos. O caderno mostra exatamente como combinar entidades usando busca em três etapas, busca híbrida com RRF e julgamento baseado em LLM com raciocínio.

Lembre-se: este é um protótipo educacional projetado para ensinar os conceitos. Ao construir sistemas de produção, considere fatores adicionais, como seleção de modelos, otimização de custos, requisitos de latência, validação de qualidade, tratamento de erros e monitoramento, que não são abordados neste protótipo focado em aprendizado.

Notas

1. Esses conjuntos de dados são sintéticos e projetados para educação; eles se aproximam de desafios reais, mas não representam nenhum domínio de produção específico.

Nossos benchmarks em um corpus de 20 milhões de documentos mostram que o Elasticsearch entrega uma taxa de transferência até 8 vezes maior que o OpenSearch para busca vetorial filtrada, além de alcançar um Recall@100 superior nas configurações que testamos. A engenharia de contexto depende de mais do que apenas uma recuperação vetorial rápida. As equipes também precisam de fortes controles de relevância, como busca e filtragem híbridas, simplicidade operacional e desempenho previsível, à medida que os fluxos de trabalho evoluem. Mas como os agentes geralmente executam loops de recuperação, raciocínio e recuperação várias vezes por solicitação, a latência de recuperação se torna um multiplicador, então as melhorias aqui se traduzem diretamente em melhor capacidade de resposta de ponta a ponta e menor custo.

Para engenharia de contexto, recuperação não é um passo único. Agentes e aplicativos executam repetidamente loops, como recuperar → raciocinar → recuperar, para refinar consultas, verificar fatos, reunir contexto fundamentado e concluir tarefas. Esse padrão é comum em fluxos de trabalho agentivos e Retrieval-Augmented Generation iterativa (RAG). Como a recuperação pode ser invocada muitas vezes por solicitação do usuário, ela adiciona atraso à resposta e/ou aumenta os custos de infraestrutura.

Por que o desempenho da busca vetorial é crítico?

Imagine um assistente de compras respondendo à pergunta: “Preciso de uma mochila de mão por menos de R$ 300 que comporte um laptop de 15 polegadas, seja resistente à água e possa chegar até sexta-feira.”

Em produção, o assistente raramente emite uma consulta vetorial e para. Ele executa um ciclo de recuperação para criar o contexto certo, e cada etapa normalmente é limitada por filtros, como disponibilidade, região, promessa de envio, regras de marca e elegibilidade de políticas.

Passo 1: Interprete a intenção e traduza para restrições.

O agente transforma a solicitação em filtros estruturados e uma consulta semântica, como:

• Filtros: em estoque, disponível para entrega no CEP do usuário, entrega até sexta-feira, preço abaixo de R$ 300, listagem válida
• Consulta vetorial: “Mochila de bordo resistente à água para notebook de 15 polegadas”

Passo 2: Recuperar candidatos e, em seguida, refinar.

Frequentemente, repete a recuperação com variações para evitar perder boas correspondências:

• "Mochila de viagem com compartimento para laptop"
• "Mochila urbana resistente à água 15 polegadas"
• "Mochila leve para cabine"

Cada consulta usa os mesmos filtros de elegibilidade, porque recuperar itens irrelevantes ou indisponíveis é contexto desperdiçado.

Passo 3: Expanda para confirmar detalhes e reduzir riscos.

O agente então recupera novamente para verificar os atributos-chave que afetam a resposta final:

• Texto sobre materiais e resistência à água
• Dimensões e ajuste do compartimento para laptop
• Política de devolução ou restrições de garantia
• Opções alternativas se o estoque estiver baixo

Isso é engenharia de contexto multietapas: recuperar, raciocinar, recuperar, montar.

Por que latência e recall importam para a engenharia de contexto

Essas interações podem envolver dezenas de chamadas de recuperação filtradas por sessão de usuário. Isso faz com que a latência por chamada seja um multiplicador direto no tempo de resposta de ponta a ponta, e o baixo recall força tentativas extras ou faz com que o agente perca itens elegíveis, degradando a qualidade da resposta.

Conclusão: em sistemas de engenharia de contexto, os vizinhos mais próximos aproximados (ANN) filtrados não são uma pesquisa única. É uma operação repetida sob restrições, portanto, o desempenho da busca vetorial aparece imediatamente em latência, taxa de transferência e custo, mesmo quando o modelo de linguagem de grande porte (LLM) é o componente mais visível.

Benchmark

Resultados

No gráfico 2, cada ponto representa uma configuração de teste. Os melhores resultados aparecem no canto superior esquerdo, o que significa maior recall com menor latência. Os resultados do Elasticsearch estão consistentemente mais próximos do canto superior esquerdo do que os do OpenSearch, indicando melhor velocidade e precisão sob as mesmas configurações de carga de trabalho.

Alguns insights importantes

• s_n_r_value: Abreviação de size_numCandidates_rescoreOversample (k e numCandidates=500 definidos como numCandidates nesses testes), por exemplo, 100_500_1 significa size=100, numCandidates=500 e k=500, rescore oversample=1
• Recall: Recall@100 medido para essa configuração
• Latência média (ms): latência média de ponta a ponta por consulta
• Taxa de transferência: consultas por segundo
• Recall (%): elevação relativa do recall do Elasticsearch x OpenSearch (Elasticsearch menos OpenSearch)/OpenSearch
• Latência Xs: a latência média do OpenSearch dividida pela latência média do Elasticsearch
• Throughput Xs: Throughput do Elasticsearch dividido pelo throughput do OpenSearch

Por exemplo, em 100_9000_1, o OpenSearch tem uma média de 687 milissegundos por recuperação contra 90 milissegundos no Elasticsearch, e em um ciclo de recuperação de 10 etapas, isso equivale a cerca de 10 x (687 - 90) = seis segundos de tempo adicional de espera.

Veja os resultados completos.

Metodologia

Usando Python para enviar as consultas e acompanhar o tempo de resposta e outras estatísticas, enviamos as seguintes consultas para os motores. Lembre-se de que o desempenho de qualquer mecanismo de busca vetorial depende de como você ajusta seus parâmetros principais: quantos candidatos considerar, quão agressivamente reclassificar e quanto contexto devolver. Essas configurações afetam diretamente tanto o recall (a probabilidade de encontrar a resposta certa) quanto a latência (a rapidez com que você obtém resultados).

Em nossos benchmarks, usamos as mesmas configurações de candidato, reclassificação e tamanho do resultado que você normalmente ajusta em um ciclo de recuperação orientado por agente, e medimos o desempenho do Elasticsearch sob essa carga de trabalho. Depois, executamos o OpenSearch com as mesmas configurações como referência.

OpenSearch

GET /_search
{
  "query": {
    "knn": {
      "": {
        "vector": [...],
        "k": ,
        "method_parameters": {
          "ef_search": 
        },
        "rescore": {
          "oversample_factor": 
        },
        "filter": {
          
        }
      }
    }
  },
  "size": ,
  "_source": {
    "excludes": [
      ""
    ]
  }
}

• "size": <RESULT_SIZE>: Número de resultados retornados ao cliente. Neste benchmark, o tamanho do resultado é 100 para calcular o Recall@100.
• "k": <NUMBER_OF_CANDIDATES>: O número de candidatos a vizinhos mais próximos.
• "ef_search": <NUMBER_OF_CANDIDATES>: O número de vetores a examinar.
• "oversample_factor": <OVERSAMPLE>: Quantos vetores candidatos são recuperados antes da reclassificação.

Elasticsearch

GET /_search
{
  "query": {
    "knn": {
      "field": "",
      "query_vector": [...],
      "k": ,
      "num_candidates": ,
      "rescore_vector": {
        "oversample": 
      },
      "filter": {
        
      }
    }
  },
  "size": ,
  "_source": {
    "excludes": [
      ""
    ]
  }
}

• "size": <RESULT_SIZE>: Número de resultados retornados ao cliente. Neste benchmark, o tamanho do resultado é 100 para calcular o Recall@100.
• "k": <NUMBER_OF_CANDIDATES>: Número de vizinhos mais próximos a retornar de cada shard.
• "num_candidates": <NUMBER_OF_CANDIDATES>: Número de candidatos a vizinhos mais próximos a serem considerados por shard durante a busca knn.
• "oversample": <OVERSAMPLE>: Quantos vetores candidatos são recuperados antes da reclassificação.

Exemplo

Knn consulta, (100_500_1), seria a seguinte:

OpenSearch

GET search_catalog_128/_search
{
  "query": {
    "knn": {
      "search_catalog_embedding": {
        "vector": [...],
        "k": 500,
        "method_parameters": {
          "ef_search": 500
        },
        "rescore": {
          "oversample_factor": 1
        },
        "filter": {
          "term": {
            "valid": true
          }
        }
      }
    }
  },
  "size": 100,
  "_source": {
    "excludes": [
      "search_catalog_embedding"
    ]
  }
}

Elasticsearch

GET search_catalog_128/_search
{
  "query": {
    "knn": {
      "field": "search_catalog_embedding",
      "query_vector": [...],
      "k": 500,
      "num_candidates": 500,
      "rescore_vector": {
        "oversample": 1
      },
      "filter": {
        "term": {
          "valid": true
        }
      }
    }
  },
  "size": 100,
  "_source": {
    "excludes": [
      "search_catalog_embedding"
    ]
  }
}

A configuração completa, juntamente com os scripts do Terraform, os manifestos do Kubernetes e o código de benchmark, está disponível neste repositório na pasta es-9.3-vs-os-3.5-vector-search.

Configuração do Cluster

Executamos nossos testes em seis servidores em nuvem e2-standard-16, cada um com 16 vCPUs e 64 GB de RAM. Em cada servidor, alocamos 15 vCPUs e 56 GB de RAM para cada pod Kubernetes executando o Node do mecanismo de busca, com 28 GB reservados para o heap da JVM.

Os clusters executavam Elasticsearch 9.3.0 e OpenSearch 3.5.0 (Lucene 10.3.2). Como ambos os sistemas usam a mesma versão do Lucene neste teste de desempenho, as diferenças de taxa de transferência e latência que observamos não podem ser atribuídas apenas ao Lucene, mas sim refletem diferenças na forma como cada mecanismo integra e executa a recuperação e reavaliação filtrada do algoritmo k-vizinhos mais próximos (kNN). Usamos um único índice com três shards principais e uma réplica (ou seja, 6 shards no total, 1 por nó).

Também usamos um servidor separado na mesma região para executar o cliente de benchmark e coletar estatísticas de tempo.

O conjunto de dados

Para este benchmark, usamos um catálogo em grande escala no estilo de comércio eletrônico com conjuntos de dados de 20 milhões de documentos, projetado para refletir a recuperação vetorial filtrada do mundo real em escala.

Cada documento representa um item do catálogo e inclui:

• Um embedding vetorial denso de 128 dimensões utilizado para recuperação aproximada de kNN.
• Campos de metadados estruturados usados para filtragem (por exemplo, validade e disponibilidade do item, além de outras restrições do catálogo), permitindo o padrão comum de produção de recuperar os vizinhos mais próximos, mas somente dentro de um subconjunto elegível.

Escolhemos este conjunto de dados porque ele captura o principal desafio de desempenho que observamos em sistemas agentivos e do tipo RAG em produção: a similaridade vetorial por si só não é suficiente, a recuperação é frequentemente limitada por filtros, e o sistema deve manter um alto índice de recall enquanto mantém a latência baixa sob essas restrições. Comparado a conjuntos de dados menores no estilo QA, um corpus de 20 milhões de documentos também reflete melhor a escala e a pressão dos candidatos que sistemas ANN filtrados enfrentam na prática.

Conclusão

Nas arquiteturas modernas de IA, especialmente aquelas construídas baseadas em engenharia de contexto, a velocidade da busca vetorial não é um pequeno detalhe de implementação. É um multiplicador. Quando agentes e fluxos de trabalho iteram por meio de recuperar → raciocinar → recuperar, o desempenho da recuperação molda diretamente a latência de ponta a ponta, a taxa de transferência e a qualidade do contexto inserido no modelo.

Em nossos benchmarks, o Elasticsearch consistentemente entregou um recall maior com menor latência do que o OpenSearch em cenários onde a correção depende de recuperar o documento correto, e não apenas de um vetor semelhante. Em um conjunto de dados controlado, a diferença é clara, e na produção esses ganhos se acumulam em grandes volumes de chamadas de recuperação, melhorando a capacidade de resposta, aumentando a margem de capacidade e reduzindo custos de infraestrutura.

Para ler mais

1. O que é engenharia de contexto?
2. A evolução da busca híbrida e da engenharia de contexto
3. O impacto da relevância na engenharia de contexto para agentes de IA

A família inclui dois modelos:

• jina-embeddings-v5-text-small
• jina-embeddings-v5-text-nano

Esses modelos são o resultado bem-sucedido de uma nova receita inovadora de treinamento para incorporação de modelos. Ambos superam modelos muitas vezes maiores que eles, gerando economia de memória e recursos computacionais e respondendo mais rápido a solicitações.

O modelo jina-embeddings-v5-text-small possui 677 milhões de parâmetros, é compatível com uma janela de contexto de entrada de 32.768 tokens e gera embeddings de 1.024 dimensões por padrão.

jina-embeddings-v5-text-nano Pesa cerca de um terço do tamanho da nova versão, com 239 milhões de parâmetros e uma janela de contexto de entrada de 8.192 tokens, resultando em embeddings de dimensão 768 compactos.

Esses dois modelos são os melhores da categoria para o desempenho geral do benchmark MMTEB (Multilingual MTEB). Entre os modelos com menos de 500M, jina-embeddings-v5-text-nano é o de melhor desempenho, apesar de ter menos de 250M, e o modelo jina-embeddings-v5-text-small é o líder entre os modelos de embedding multilíngue com menos de 750M.

Esses modelos estão disponíveis por meio do Elastic Inference Service (EIS), de uma API online e para hospedagem local. Para instruções sobre como acessar os modelos jina-embeddings-v5-text, veja a seção "Começar" abaixo.

Modelos de incorporação e indexação semântica aumentam muito a precisão dos algoritmos de busca, mas também têm uma variedade de outros usos para tarefas envolvendo similaridade semântica e extração de significado, por exemplo:

• Encontrando textos duplicados.
• Reconhecendo paráfrases e traduções.
• Descoberta de tópicos.
• Mecanismos de recomendação.
• Análise de sentimentos e intenções.
• Filtragem de spam.
• E muitos outros.

Recursos

Essa nova família de modelos possui uma série de recursos projetados para aumentar a relevância e reduzir custos.

Otimização de tarefas

Otimizamos os modelos jina-embeddings-v5-text para quatro tipos amplos de tarefas:

Otimizar para uma tarefa geralmente significa ter que ceder em outra, então a maioria dos modelos de embedding só tem desempenho competitivo para um tipo de tarefa. Mas os modelos jina-embeddings-v5-text são capazes de se especializar em todas as quatro áreas sem comprometer o desempenho, treinando adaptadores compactos de Low-Rank Adaptation (LoRA) específicos para cada tarefa.

Adaptadores LoRA são uma espécie de plugin para um modelo de IA que muda o comportamento, aumentando ligeiramente o tamanho total. Em vez de ter um modelo inteiro para cada tarefa, cada um com centenas de milhões de parâmetros, a família de modelos jina-embeddings-v5-text permite que você use um modelo com um adaptador compacto LoRA para cada tarefa. Isso economiza memória, espaço de armazenamento e custos de inferência.

Truncando embeddings

Treinamos os modelos jina-embeddings-v5-text usando o Aprendizado de representação Matryoshka, que permite reduzir seus embeddings para tamanhos menores com um custo mínimo para a qualidade deles.

Por padrão, jina-embeddings-v5-text-small gera vetores de embedding de 1024 dimensões, cada um representado por um número de 16 bits, fazendo com que cada embedding tenha 2KB de tamanho. Para um grande conjunto de documentos, isso pode representar uma grande quantidade de dados para armazenar, e a busca em um banco de dados vetorial repleto de embeddings é proporcional tanto ao tamanho do banco de dados quanto ao número de dimensões que cada vetor armazenado possui.

Mas você pode reduzir pela metade o tamanho dos embeddings (descartar 512 das 1024 dimensões) e ocupar metade do espaço enquanto dobra a velocidade das buscas. Isso tem um impacto no desempenho. Descartar informações reduz a precisão. Mas, como mostra o gráfico abaixo, mesmo ao eliminar metade do embedding, a redução de desempenho é mínima:

Desde que suas embeddings tenham pelo menos 256 dimensões, a perda de precisão deve permanecer relativamente pequena. Abaixo desse nível, porém, a relevância e a precisão se deterioram rapidamente.

Truncar embeddings como esse permite aos usuários gerenciar as próprias trocas entre precisão e custos computacionais. Ela oferece ferramentas para ter grandes ganhos de eficiência e grandes economias de custos com a IA de busca.

Quantização robusta

Quantização é outra forma de reduzir o tamanho das embeddings. Em vez de descartar parte de cada incorporação, a quantização reduz a precisão dos números na embedding. Os modelos jina-embeddings-v5-text geram embeddings com números de 16 bits, mas podemos arredondar esses números, reduzindo a precisão e o número de bits necessários para armazená-los. No caso mais extremo, podemos reduzir cada número a um bit (0 ou 1), comprimindo as embeddings padrão de 1024 dimensões de jina-embeddings-v5-textde 2 kilobytes para 128 bytes, uma redução de 94% apenas com a quantização binária. Assim como para a truncagem, isso produz grandes economias em memória e custos computacionais. No entanto, assim como a truncagem, a quantização torna as embeddings menos precisas.

Treinamos os modelos jina-embeddings-v5-text para funcionar com a Better Binary Quantization (BBQ) do Elasticsearch, minimizando a perda de precisão. Os testes de benchmark de embeddings binarizados desses modelos mostram desempenho quase igual aos equivalentes não binarizados. Consulte o relatório técnico para estudos detalhados de ablação sobre o desempenho da binarização.

Desempenho multilíngue

Muitos modelos de embedding são multilíngues porque foram treinados com materiais que incluem um grande número de linguagens. Mas isso não significa que todos tenham o mesmo desempenho em todas as linguagens disponíveis.

Identificamos 211 linguagens no benchmark multilíngue MMTEB e os separamos para que pudéssemos comparar nossos modelos com modelos semelhantes linguagem por linguagem. A imagem abaixo resume nossos resultados como um mapa de calor. Cada patch é uma linguagem (identificada pelo código ISO-639), e quanto mais verde ela é, melhor o modelo teve desempenho em comparação com a média de modelos similares:

Embora a precisão varie entre as linguagens, os modelos jina-embeddings-v5-text são de ponta ou quase isso na maioria das linguagens do mundo.

Para saber detalhes sobre o desempenho multilíngue, consulte o jina-embeddings-v5-text relatório técnico.

Jina no Elastic: IA nativa de última geração para busca

Com jina-embeddings-v5-text modelos no EIS, você pode executar modelos de embedding multilíngue de alto desempenho de forma nativa no Elasticsearch, com inferência totalmente gerenciada e acelerada por GPU, sem infraestrutura para provisão ou redimensionamento. jina-embeddings-v5-text modelos ampliam o catálogo cada vez maior de modelos EIS com modelos compactos e multilíngues, impulsionados pelos mais recentes avanços em IA. Esses modelos têm desempenho de ponta em recuperação de informações e benchmarks padrão de análise de dados, além de oferecer suporte multilíngue incomparável e global.

Com dois modelos de tamanhos muito diferentes, os usuários podem definir qual é o mais adequado para as aplicações e orçamentos. Além disso, com embeddings robustas que mantêm o desempenho quando truncadas para tamanhos menores ou quantizadas com menor precisão, jina-embeddings-v5-text modelos oferecem oportunidades para economias concretas adicionais em custos de armazenamento e computação, bem como na latência de processamento.

Com a família jina-embeddings-v5-text , Jina Reranker e a busca vetorial rápida e BM25 da Elastic, os usuários agora têm acesso à busca híbrida de ponta a ponta e de última geração da Elastic. Quando você precisa dos resultados mais relevantes, seja para pipelines de Retrieval-Augmented Generation (RAG), aplicações de busca ou análise de dados, a Elastic com modelos de IA de busca Jina oferece qualidade sólida e econômica.

Para começar

Os modelos jina-embeddings-v5-text estão totalmente integrados ao EIS e você pode usá-los definindo o type campo para semantic_text ao criar seu índice e especificar o modelo (jina-embeddings-v5-text-small ou jina-embeddings-v5-text-nano) no inference_id campo, como neste exemplo:

PUT multilingual-semantic-index
{
  "mappings": {
    "properties": {
      "content": {
        "type": "semantic_text",
        "inference_id": ".jina-embeddings-v5-text-small"
      }
    }
  }
}

# Ingest data about France
POST multilingual-semantic-index/_doc
{
  "content": "The capital of France is Paris"}

GET multilingual-semantic-index/_search
{
  "query": {
    "semantic": {
      "field": "content",
      "query": "What is the French capital?"
    }
  }
}

O Elasticsearch seleciona automaticamente o adaptador LoRA apropriado durante a indexação e a recuperação. As dimensões de embedding (veja a seção "Truncando embeddings ", acima) podem ser definidas ao criar um endpoint de inferência personalizado.

Consulte a documentação do Elasticsearch para saber mais informações sobre como usar os modelos jina-embeddings-v5-text .

Mais informações

Para saber mais sobre os modelos jina-embeddings-v5-text , leia as notas de lançamento no blog da Jina AI e o relatório técnico, que contém informações técnicas mais detalhadas sobre o desempenho e o novo procedimento de treinamento inovador da Jina AI. Para saber informações sobre como fazer download e executar esses modelos de forma local, acesse a página da coleção jina-embeddings-v5-textna Hugging Face.

Os modelos de Jina AI estão disponíveis sob a licença CC-BY-NC-4.0, portanto, você pode baixá-los e experimentá-los de forma livre, mas para uso comercial, entre em contato com a equipe de vendas da Elastic.

Neste artigo, você aprenderá como usar o parâmetro de pontuação mínima para aumentar a precisão dos seus resultados de busca semânticos. Se você quiser testar os exemplos fornecidos neste post do blog, acesse o caderno Jupyter associado.

Contexto: Precisão e recall

Na relevância da pesquisa, a precisão e a recall são conceitos-chave. Qualquer leitor que ainda não esteja familiarizado é altamente incentivado a pesquisar sobre eles. Segue abaixo um resumo.

• Precisão: a fração dos resultados de busca retornados que são relevantes para o usuário.
• Recall: a fração de todos os documentos relevantes no corpus que estão incluídos no conjunto de resultados de busca.

Ou, em outras palavras, a precisão retorna apenas resultados relevantes e o recall retorna todos os resultados relevantes. Como você pode imaginar, esses são requisitos frequentemente concorrentes. A busca semântica tende a ter uma memória muito alta, mas pode ter dificuldades com precisão. Continue lendo para saber como se locomover por esta propriedade.

Apresentando o parâmetro de pontuação mínima

O parâmetro ‘min_score’ nos permite melhorar a precisão ao definir uma pontuação mínima, que truncará o conjunto de resultados removendo quaisquer correspondências com uma pontuação inferior ao limite definido. Aqui está um exemplo simples:

GET search-movies/_search
{
  "retriever": {
    "linear": {
      "min_score": 4,
      "retrievers": [
        ...
      ]
    }
  }
}

Normalização da pontuação

Definir uma pontuação mínima é muito bom; no entanto, nem todos os modelos semânticos retornam uma pontuação adequada para um limite estático. ELSER, por exemplo, retorna uma pontuação que é ilimitada. Algumas pontuações de modelos densos estão fortemente agrupadas e só fazem sentido no contexto da consulta específica.

Para a maioria dos casos de busca semântica, recomendamos usar uma abordagem de normalização antes de aplicar o 'min_score'. A normalização garante que a pontuação do documento esteja dentro de um intervalo definido. Os recuperadores Elasticsearch fornecem dois desses normalizadores, 'l2_norm' e 'minmax'. O mais comumente usado é o 'minmax', pois é fácil de entender e funciona bem em muitos cenários. As principais propriedades do 'minmax' incluem:

• As pontuações dos documentos são distribuídas entre 0 e 1.
• O documento com maior pontuação é sempre pontuado como 1.
• O documento com menor pontuação sempre é pontuado como 0.
  • Isso pode torná-lo menos adequado para buscar palavras-chave. Consulte a seção “Busca híbrida” para uma discussão mais aprofundada.

A seguir está um exemplo de consulta semântica normalizada com min_score. O tamanho da janela de classificação foi aumentado para 500 para permitir que possamos retornar uma lista maior de resultados de busca, começando em 100.

GET search-movies/_search
{
  "size": 100,
  "_source": [
    "title", "overview"
  ],
  "retriever": {
    "linear": {
      "rank_window_size": 500,
      "min_score": 0.25,
      "retrievers": [
        {
          "normalizer": "minmax",
          "retriever": {
            "standard": {
              "query": {
                "semantic": {
                  "field": "overview_vector",
                  "query": "superhero movie"
                }
              }
            }
          }
        }
      ]
    }
  }
}

O tamanho foi ajustado para um valor maior do que o normalmente visto na produção. Isso é para que possamos inspecionar a qualidade dos resultados de busca e ajustar os resultados.

Busca híbrida usando o recuperador linear

Para busca híbrida, a abordagem mais simples é normalizar todas as pontuações, atribuir pesos e aplicar uma pontuação mínima. Note que, ao escolher pesos cuja soma seja 1, você mantém a pontuação total dentro de um intervalo de 0 a 1. Isso facilita entender as pontuações finais e afinar min_score. A seguir está um exemplo:

GET search-movies/_search
{
  "size": 100,
  "_source": ["title", "overview","keywords"],
  "retriever": {
    "linear": {
      "rank_window_size": 500,
      "min_score": 0.25,
      "retrievers": [
        {
          "weight": 0.6,
          "normalizer": "minmax",
          "retriever": {
            "standard": {
              "query": {
                "semantic": {
                  "field": "overview_vector",
                  "query": "superhero movie"
                }
              }
            }
          }
        },
        {
          "weight": 0.4,
          "normalizer": "minmax",
          "retriever": {
            "standard": {
              "query": {
                "multi_match": {
                  "query": "superhero movie",
                  "fields": ["overview","keywords", "title"],
                  "type": "cross_fields",
                  "minimum_should_match": "2"
                }
              }
            }
          }
        }
      ]
    }
  }
}

Busca híbrida usando o RRF

Com o BM25, muitas vezes controlamos a precisão por outros meios, como usando o operador AND ou minimum_should_match. Além disso, consultas compostas por termos únicos, precisos e raros naturalmente causam resultados de busca com poucos resultados, muitas vezes todos altamente relevantes. Isso pode resultar em:

• Os resultados mais distantes na lista recebem uma pontuação normalizada baixa no recuperador BM25, mesmo que a pontuação absoluta do BM25 esteja próxima das pontuações mais altas.
• Ao adicionar uma pontuação BM25 muito baixa à pontuação semântica, o total pode ser aproximado como a pontuação semântica.
• A falta de contribuição da pontuação BM25 pode fazer com que o documento seja descartado pelo min_score threshold.

Como solução, podemos usar a fusão de classificação recíproca (RRF) para combinar os resultados BM25 e semânticos. O RRF contorna o desafio de comparar pontuações de diferentes algoritmos de busca focando na posição em cada conjunto de resultados. Nesse cenário, o min_score é aplicado apenas ao recuperador semântico.

GET search-movies/_search
{
  "_source": ["title", "overview","keywords"],
  "retriever": {
    "rrf": {
      "rank_window_size": 500,
      "retrievers": [
        {
          "linear": {
            "rank_window_size": 500,
            "min_score": 0.25,
            "retrievers": [
              {
                "normalizer": "minmax",
                "retriever": {
                  "standard": {
                    "query": {
                      "semantic": {
                        "field": "overview_vector",
                        "query": "superhero movie"
                      }
                    }
                  }
                }
              }
            ]
          }
        },
        {
          "standard": {
            "query": {
              "multi_match": {
                "query": "superhero movie",
                "fields": ["overview", "keywords","title"],
                "type": "cross_fields",
                "minimum_should_match": "2"
              }
            }
          }
        }
      ]
    }
  }
}

Conclusão

Usando min_score, mostramos como podemos reduzir o número de falsos positivos em nossos conjuntos de resultados causados pela alta recordação de algoritmos de busca semântica. Para saber mais sobre recuperadores, consulte este post do blog e a documentação do Elasticsearch.

Gerenciamento de dependências no Elastic

Na Elastic, precisamos gerenciar centenas ou até milhares de repositórios, tanto privados quanto públicos. Quando um CVE crítico é descoberto, precisamos de respostas e ações imediatas: quais repositórios são vulneráveis? Com que rapidez podemos corrigir os problemas? Além da segurança, também surgem questões de produtividade: como podemos propagar de forma rápida o lançamento de uma nova versão do pacote em todos os repositórios que dependem dela sem gastar muito tempo em tarefas manuais?

O gatilho inicial para pesquisar maneiras de fazer o gerenciamento de dependências foi a necessidade de estabelecer uma base segura com atualizações automatizadas para reduzir os CVEs. Após considerar cuidadosamente soluções para gerenciamento de dependências, começamos a trabalhar em uma infraestrutura auto-hospedada. Estávamos usando nosso próprio cluster Kubernetes para executar o Mend Renovate Community Self-Hosted. A ideia era fornecer uma plataforma de gerenciamento de dependências que nossos usuários pudessem acessar de forma autônoma.

O experimento inicial foi bem-sucedido, então mais e mais equipes começaram a integrar nossa plataforma e usá-la no ciclo de vida diário dos repositórios para atualizações e patches de CVE. Isso aconteceu tão rápido que logo chegamos ao limite da nossa instalação auto-hospedada.

O desafio: como podemos redimensionar uma plataforma de gerenciamento de dependências em uma grande organização com um número significativo de repositórios?

Nossa plataforma de gerenciamento de dependências estava processando um repositório por vez e o modelo de processamento sequencial não conseguia acompanhar, devido ao grande número de repositórios que possuímos. Já havíamos identificado que o problema residia no conceito de que uma única instância de nossa ferramenta de gerenciamento de dependências poderia processar nossa grande e crescente lista de repositórios. Repositórios aguardavam em uma fila, às vezes por muitas horas. Mais de 50% dos nossos repositórios nem sequer eram processados diariamente. Isso significa que mais de 50% dos nossos repositórios esperaram mais de 24 horas entre as varreduras.

Repositórios grandes criavam gargalos maiores, devido às bases de código consideráveis e aos múltiplos PRs abertos. Eventos do webhook do GitHub interromperam a sequência. O Automerge tornou-se não confiável porque o tempo de varredura era imprevisível. Fizemos uma promessa aos nossos usuários sobre a frequência dos escaneamentos, mas não conseguimos cumpri-la.

A decisão de criar internamente: atendendo às necessidades únicas de escala e segurança da Elastic

Enquanto considerávamos opções comerciais, incluindo a edição Mend's Renovate Self-Hosted Enterprise Self-Hosted, internamente na Elastic tivemos algumas iniciativas-chave em desenvolvimento.

Nossa decisão de criar uma plataforma interna foi motivada pelo reconhecimento de que somente uma solução personalizada poderia atender aos requisitos específicos e inegociáveis da Elastic:

1. Investindo em nossa plataforma interna de desenvolvedores: naquela época, já tínhamos começado a investir fortemente em nossa plataforma interna de desenvolvedores. Estávamos discutindo e projetando formas de como cada um dos nossos serviços poderia se encaixar nisso. Isso significava que queríamos testar nossas próprias regras e práticas para nossa plataforma de gerenciamento de dependências. Além disso, novas diretrizes estavam entrando em ação e queríamos projetar a plataforma antes dos eventos.
2. Integração nativa e personalização do fluxo de trabalho: precisávamos de uma integração direta com nossas ferramentas e processos internos. Por exemplo, queríamos centralizar a configuração como código com nosso Catálogo de serviços (Backstage). Temos necessidades específicas relacionadas ao uso do Backstage que queríamos tornar compatíveis com nossa plataforma. Portanto, embora fosse possível usar as APIs Renovate Self-Hosted junto com nossa automação Backstage, isso não cobriria totalmente nossos processos internos.
3. Segurança de defesa em profundidade específica da Elastic: nossa rigorosa conformidade de segurança exigiu mecanismos de segurança personalizados, adaptados ao nosso ecossistema. Estávamos trabalhando para fortalecer nosso uso de "identidades não humanas". A forma como esse reforço de acesso funcionava significava que os métodos não padronizados de autenticação no GitHub não funcionariam com uma ferramenta comercial que não suportasse essa implementação interna. Nosso fluxo de trabalho incluía a implementação de um padrão de criptografia secreta de fluxo de trabalho pai-filho e o uso de tokens transitórios e de uso único do GitHub. Criar internamente foi a única maneira prática de incorporar essas camadas de segurança exclusivas e minimizar a superfície de ataque em nosso complexo ambiente multinuvem.

A solução: orquestração de fluxo de trabalho para gerenciamento de dependências

Nossa solução começou com o fato de queríamos criar sobre a ferramenta de gerenciamento de dependências que já usávamos e não substituí-la, buscando outras soluções. Ela já demonstrava sinais de potencial, e a flexibilidade é importante para diferentes necessidades em toda a organização. Consideramos diferentes soluções, e o que nos ajudou a decidir foram as necessidades, às vezes grandes e especiais, que precisamos cobrir. Decidimos criar uma plataforma de gerenciamento de dependências confiável e escalável, na qual cada repositório será processado por conta própria, removendo gargalos e nos preparando para o crescimento.

Projetamos a plataforma seguindo três princípios fundamentais:

1. Processamento paralelo

Cada repositório recebe o próprio ambiente de processamento de gerenciamento de dependências. Não há mais filas. Nossa concorrência é limitada apenas pelo número de recursos que gastamos. Também aplicamos o agendamento distribuído inteligente para evitar que o GitHub limite a taxa.

2. Autoatendimento

Usamos nosso Catálogo de serviços (Backstage) para integrar e gerenciar automaticamente qualquer novo repositório. Usamos nossa própria definição de recursos para dar ao usuário final a opção de selecionar com que frequência um repositório será processado, quantos recursos deseja alocar para os cronogramas e se deseja desligar ou reativar o processamento por qualquer motivo. Planejamos adicionar mais opções assim conforme as necessidades dos nossos usuários evoluem e eles se familiarizam com a nova instalação.

3. Redução do escopo secreto e isolamento do espaço de nome

Para mais segurança, fornecemos aos nossos pods de gerenciamento de dependências tokens efêmeros do GitHub que são gerados no início de cada fluxo de trabalho. Além disso, isolamos nossas cargas de trabalho em espaços de nome específicos para que possam receber apenas os segredos necessários. Controlamos quais segredos podem ser acessados em cada fluxo de trabalho de gerenciamento de dependências usando o Kubernetes RBAC. Também usamos criptografia para propagar o token do GitHub do fluxo de trabalho pai para o filho.

Reconstruímos nossa plataforma usando e aproveitando o melhor de Kubernetes, do Argo Workflows que alimenta a lógica dos nossos processos, e a CLI do Renovate que está configurado para escanear e processar um repositório de cada vez.

A beleza: estamos utilizando projetos open source testados de forma inovadora, fornecendo novos exemplos práticos para todos esses projetos e, ao mesmo tempo, ampliando a velocidade de desenvolvimento e consolidando a redução de CVE para nossas equipes.

Arquitetura de gerenciamento de dependências: quatro microsserviços

A plataforma é composta por quatro componentes personalizados:

Operador de fluxos de trabalho (Go/Kubebuilder)

Um operador do Kubernetes gerenciando o ciclo de vida do fluxo de trabalho por meio de três definições de recursos personalizadas (CRDs):

• RepoConfig CRD: fonte única de verdade para configuração de repositórios.

É assim que o RepoConfig é definido no operador:

// RepoConfig is the Schema for the repoconfigs API
type RepoConfig struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty,omitzero"`

	// spec defines the desired state of RepoConfig
	// +required
	Spec RepoConfigSpec `json:"spec"`

	// status defines the observed state of RepoConfig
	// +optional
	Status RepoConfigStatus `json:"status,omitempty,omitzero"`
}

E essa é a aparência de uma instância do RepoConfig:

apiVersion: workflows.elastic.co/v1
kind: RepoConfig
metadata:
  generation: 3
  name: elastic-test-repo
  namespace: dependency-management-operator
spec:
  owner: group:my-team
  renovate:
    config:
      resourceGroup: SMALL
      runFrequency: 4h
    enabled: true
  repository: elastic/test-repo

• CRD pai: gerencia os fluxos de trabalho do CronWorkflows para varreduras agendadas.

Dentro do loop de reconciliação do controlador principal, garantimos que as configurações de fluxo de trabalho sejam criadas e mantidas atualizadas ou até mesmo excluídas, se necessário.

Primeiro, ele recebe algumas configurações globalmente configuradas para fluxos de trabalho:

func (r *ParentReconciler) reconcileSubResources(ctx context.Context, req ctrl.Request, parent *workflowsv1.Parent) error {
	logger := logf.FromContext(ctx)
	logger.Info("Reconcile SubResources for Parent", "name", req.NamespacedName)
	wfSet := workflowsettings.WorkflowSettings{
		RunFrequency:   parent.Spec.RunFrequency,
		ResourceGroups: "parent",
	}

Ele garante que um mutex configmap esteja atualizado para evitar fluxos de trabalho semelhantes rodando juntos:

	cfMngr := resources.NewConfigMapManager(r.Client, r.Scheme, r.OperatorConfig.ParentNamespace)
	err := cfMngr.CreateOrUpdateSyncMutexConfigmap(ctx, fmt.Sprintf("%s%s", r.OperatorConfig.ResourcesPrefix, r.OperatorConfig.SyncMutexCfgMapName), strings.TrimPrefix(parent.Spec.Repository, "elastic/"), r.OperatorConfig.SemaphoreConcurrencyLimit)

Depois, cria um Gerenciador de fluxo de trabalho que é a estrutura que criará ou atualizará os CronWorkflows e os Modelos de fluxo de trabalho:

	wfMngr := resources.NewArgoWorkflowManager(r.Client,
		r.Scheme,
		curateResourceName(
			strings.ReplaceAll(parent.Spec.Repository, "/", "-"),
		),
		parent.Namespace,
		"parent-workflow",
		false).
		WithOrganization(r.OperatorConfig.GitHubOrg).
		WithRepoName(parent.Spec.Repository).
		Init(true, true).
		WithPrefix(r.OperatorConfig.ResourcesPrefix).
		WithWfTemplateName(r.OperatorConfig.ParentWorkflowTemplate).
		WithResources(wfSet.GetResourceCategory()).
		WithSchedule(wfSet.GetCronSchedule()).
		WithImagePullSecrets([]corev1.LocalObjectReference{{
			Name: r.OperatorConfig.WorkflowImagePullSecrets,
		}}).
		AddArgument(true, true, "extra_cli_args").
		SetArgument(true, false, "extra_cli_args", "none").
		AddTemplate(resources.NewParentDAGTemplateInstance()).
		AddTemplate(resources.NewWorkflowsTemplateInstance("check-child-workflows", r.OperatorConfig.WorkflowImagePullPolicy, r.OperatorConfig.WorkflowNodeSelector)).
		AddTemplate(resources.NewWorkflowsTemplateInstance("security", r.OperatorConfig.WorkflowImagePullPolicy, r.OperatorConfig.WorkflowNodeSelector)).
		AddTemplate(resources.NewWorkflowsTemplateInstance("submit-child-workflow", r.OperatorConfig.WorkflowImagePullPolicy, r.OperatorConfig.WorkflowNodeSelector))
	wfMngr.OverWriteCommand("submit-child-workflow", r.OperatorConfig.ChildNamespace)
	wfMngr.OverwriteWfTemplateName("parent-wftmpl")
	wfMngr.AddSynchronization(fmt.Sprintf("%s%s", r.OperatorConfig.ResourcesPrefix, r.OperatorConfig.SyncMutexCfgMapName), "{{workflow.parameters.repo_name}}")
	err = wfMngr.CreateOrUpdateCronWorkflow(ctx)
	if err != nil {
		return fmt.Errorf("failed to create or update cron workflow: %w", err)
	}
	err = wfMngr.CreateOrUpdateWorkflowTemplate(ctx)
	if err != nil {
		return fmt.Errorf("failed to create or update workflow template: %w", err)
	}
	return nil

• Child CRD: gerencia WorkflowTemplates com recursos por repositório.

O controlador filho tem uma função de reconciliação semelhante à do controlador pai, mas desta vez é responsável pelos modelos de fluxo de trabalho no espaço de nome filho que serão acionados pelos fluxos de trabalho pai.

func (r *ChildReconciler) reconcileSubResources(ctx context.Context, req ctrl.Request, child *workflowsv1.Child) error {
	logger := logf.FromContext(ctx)
	logger.Info("Reconcile SubResources for Child", "name", req.NamespacedName)
	wfSet := workflowsettings.WorkflowSettings{
		ResourceGroups: child.Spec.ResourceCategory,
	}
	wfMngr := resources.NewArgoWorkflowManager(r.Client,
		r.Scheme,
		curateResourceName(
			strings.ReplaceAll(child.Spec.Repository, "/", "-"),
		),
		child.Namespace,
		"runner",
		true).
		Init(false, true). // only manage workflow template
		WithPrefix(r.OperatorConfig.ResourcesPrefix).
		WithSuffix("-child-wftmpl").
		WithRepoName(child.Spec.Repository).
		WithOrganization(r.OperatorConfig.GitHubOrg).
		WithResources(wfSet.GetResourceCategory()). // will override resources of presets if set
		WithImagePullSecrets([]corev1.LocalObjectReference{{
			Name: r.OperatorConfig.WorkflowImagePullSecrets,
		}}).
		AddTemplate(resources.NewWorkflowsTemplateInstance("runner", r.OperatorConfig.WorkflowImagePullPolicy, r.OperatorConfig.WorkflowNodeSelector)).
		AddArgument(false, true, "repo_full_name").
		AddArgument(false, true, "repo_name").
		AddArgument(false, true, "encrypted_token").
		AddArgument(false, true, "extra_cli_args")
	wfMngr.OverWriteCommand("runner", r.OperatorConfig.ChildNamespace)
	err := wfMngr.CreateOrUpdateWorkflowTemplate(ctx)
	if err != nil {
		return fmt.Errorf("failed to create or update workflow template: %w", err)
	}
	return nil
}

O padrão multicontrolador proporciona separação clara: o RepoConfig Controller cuida do onboarding/offboarding, o Parent Controller gerencia o escalonamento e o Child Controller gerencia os templates de execução.

GitHub Events Gateway (Go)

Um proxy seguro de webhook que recebe webhooks do GitHub, verifica assinaturas, filtra por organização/repositório e direciona para os eventos do Argo. Criamos 10 sensores distintos que respondem a interações com dashboards de dependência, eventos de PR e atualizações de pacotes.

Esse gateway permite a integração com os apps do GitHub por meio de:

• Verificação de assinaturas de webhooks do GitHub recebidas para fins de segurança.
• Encaminhando eventos válidos para o Argo Events EventSource com todos os cabeçalhos e autenticação relevantes.
• Nós também configuramos um authSecret no EventSource e fornecemos isso como um cabeçalho Bearer nas requisições encaminhadas.
• Fornecer loggings, métricas e lógica de repetição.

Ele realiza diversas validações em cada solicitação de evento do GitHub.

Ele garante que alguns atributos HTTP estejam presentes:

// ValidateRequestMethod checks if the request method is POST.
func ValidateRequestMethod(r *http.Request) error {
	if r.Method != http.MethodPost {
		return fmt.Errorf("method not allowed, only POST is accepted")
	}
	return nil
}

// ValidateRequiredHeaders checks for required GitHub headers.
func ValidateRequiredHeaders(r *http.Request) error {
	eventType := r.Header.Get("X-GitHub-Event")
	deliveryID := r.Header.Get("X-GitHub-Delivery")
	signature := r.Header.Get("X-Hub-Signature-256")
	if eventType == "" || deliveryID == "" || signature == "" {
		return fmt.Errorf("missing required GitHub headers")
	}
	return nil
}

// ValidateUserAgent checks that the User-Agent header starts with GitHub-Hookshot/
func ValidateUserAgent(r *http.Request) error {
	userAgent := r.Header.Get("User-Agent")
	if !strings.HasPrefix(userAgent, "GitHub-Hookshot/") {
		return fmt.Errorf("invalid User-Agent")
	}
	return nil
}

Embora também valide a assinatura de cada solicitação e da organização.

// ValidateSignature verifies the GitHub webhook signature.
func ValidateSignature(r *http.Request, secret string) ([]byte, error) {
	payload, err := GitHub.ValidatePayload(r, []byte(secret))
	if err != nil {
		return nil, fmt.Errorf("invalid GitHub signature: %w", err)
	}
	return payload, nil
}

// ValidateAllowedOwner checks if the organization login is in the allowed organizations list.
func ValidateAllowedOwner(payload []byte, allowedGitHubOrganizations []string) (string, error) {
	var orgLogin string
	var payloadMap map[string]any
	if err := json.Unmarshal(payload, &payloadMap); err == nil {
		if orgObj, ok := payloadMap["organization"].(map[string]any); ok {
			if login, ok := orgObj["login"].(string); ok {
				orgLogin = login
			} else if name, ok := orgObj["name"].(string); ok {
				orgLogin = name
			}
		}
	}
	if !slices.Contains(allowedGitHubOrganizations, orgLogin) {
		return orgLogin, fmt.Errorf("organization login not allowed")
	}
	return orgLogin, nil
}

Por fim, ele direciona para Argo Events com base no tipo de evento:

	// Map eventType to Argo `EventSource` path
	var endpoint string
	switch eventType {
	case "push":
		endpoint = "/push"
	case "issues":
		endpoint = "/issues"
	case "pull_request":
		endpoint = "/pull-requests"
	default:
		slog.Info("Ignoring unhandled event type", "event_type", eventType, "delivery_id", deliveryID)
		w.WriteHeader(http.StatusOK)
		_, _ = w.Write([]byte("ok"))
		return
	}
	forwardURL := h.config.ArgoEventSourceForwardURL + endpoint

Do lado da Argo Events, 10 sensores observam o Argo Events EventBus para novos eventos:

apiVersion: argoproj.io/v1alpha1
kind: Sensor
metadata:
  name: {{ .Values.sensors.packageUpdateOnDefaultBranch.name }}
  namespace: {{ .Release.Namespace }}
spec:
  eventBusName: {{ .Values.eventBus.name }}

Então, o script aplica a lógica de cada sensor:

script: |
          local e = event
          if not e or not e.body or not e.body.repository then
            return false
          end

          -- e.g., "refs/heads/main"
          local ref = e.body.ref
          local default_branch = e.body.repository.default_branch
          if not ref or not default_branch then
            return false
          end

          local expected = "refs/heads/" .. default_branch
          if ref ~= expected then
            return false
          end

        {{- if .Values.sensors.packageUpdateOnDefaultBranch.packageFiles }}
          patterns = { {{- range $i, $f := .Values.sensors.packageUpdateOnDefaultBranch.packageFiles }}{{ if $i }}, {{ end }}"{{ $f }}"{{- end }} }
        {{- end }}

          local function anyMatch(path)
            if type(path) ~= "string" then return false end
            for _, pat in ipairs(patterns) do
              -- match filename at repo root, or anywhere under subdirs
              if path:match(pat) or path:match(".+/" .. pat) then
                return true
              end
            end
            return false
          end

          local function filesContainPackage(paths)
            if type(paths) ~= "table" then return false end
            for _, p in ipairs(paths) do
              if anyMatch(p) then return true end
            end
            return false
          end

          -- Inspect all commits (GitHub includes added/modified/removed lists)
          local commits = e.body.commits
          if type(commits) ~= "table" then
            -- Fallback: some payloads include only head_commit
            commits = {}
            if type(e.body.head_commit) == "table" then
              table.insert(commits, e.body.head_commit)
            end
          end

          for _, c in ipairs(commits) do
            if filesContainPackage(c.added) or filesContainPackage(c.modified) or filesContainPackage(c.removed) then
              return true
            end
          end

          return false

Sincronizador de Backstage (Go)

Este procedimento consulta nosso Catálogo de serviços (Backstage) em busca de Entidades de recursos reais do repositório, transforma-as em CRDs do RepoConfig e mantém a plataforma sincronizada com as alterações de configuração. As alterações são aplicadas em três minutos.

repoMap := make(map[string]map[string]interface{})
			for i := range entities {
				entity := &entities[i]
				if entity.Spec.Type != "GitHub-repository" {
					continue
				}

				implRaw, err := json.Marshal(entity.Spec.Implementation)
				if err != nil {
					logger.Error("Failed to marshal implementation", "error", err)
					continue
				}

				var implMap map[string]interface{}
				err = json.Unmarshal(implRaw, &implMap)
				if err != nil {
					logger.Error("Failed to unmarshal implementation map", "error", err)
					continue
				}
				var repoName string
				if specMap, ok := implMap["spec"].(map[string]interface{}); ok {
					if repo, ok := specMap["repository"].(string); ok {
						repoName = repo
					}
				}
				if repoName == "" {
					continue
				}

				var workflowsRaw []byte
				if v, ok := implMap["spec"].(map[string]interface{}); ok {
					if r, ok := v["renovate"]; ok {
						workflowsRaw, _ = json.Marshal(r)
					} else {
						workflowsRaw = []byte(`{}`)
					}
				} else {
					workflowsRaw = []byte(`{}`)
				}

				var workflowsWithDefaults schema.WorkflowsMetadata
				err = json.Unmarshal(workflowsRaw, &rworkflowsWithDefaults)
				if err != nil {
					logger.Error("Failed to unmarshal workflows config", "error", err)
					continue
				}

				workflowsMap := map[string]interface{}{
					"enabled":        workflowsWithDefaults.Enabled,
					"require_pr":     workflowsWithDefaults.RequirePr,
					"resource_group": string(workflowsWithDefaults.ResourceGroup),
					"run_frequency":  string(workflowsWithDefaults.RunFrequency),
				}
				repoMap[repoName] = map[string]interface{}{
					"renovate": workflowsMap,
					"owner":    entity.Spec.Owner,
				}
			}
			logger.Info("Fetched GitHub Repository data from Backstage", "repository_count", len(repoMap), "status_code", resp.StatusCode)

Por fim, ele grava esses dados nas instâncias do RepoConfig.

Base de fluxos de trabalho (Misto: JavaScript, Go, Helm)

A camada fundamental contém gráficos Helm, configurações JavaScript, um wrapper Go para a CLI do Renovate com suporte a criptografia e um indexador de APK personalizado para pacotes Alpine.

Configuração de autoatendimento

As equipes configuram os repositórios de forma declarativa através do Backstage:

spec:
  renovate:
    enabled: true
    config:
      resourceGroup: LARGE      # SMALL | MEDIUM | LARGE  
      runFrequency: "0 */4 * * *"  # Every 4 hours

Grupos de recursos alocam CPU e memória com base no tamanho do repositório:

• PEQUENA: CPU de 500m, memória de 1Gi.
• MÉDIA: CPU de 1000m, memória 2Gi.
• GRANDE: CPU de 2000 m, memória de 4Gi.

A configuração é controlada por versão, auditável e aplicada automaticamente.

O padrão pai-filho

O modelo de execução utiliza um padrão de fluxo de trabalho pai-filho:

• Fluxo de trabalho pai: CronWorkflow leve executando conforme programado. Criptografa segredos, determina se uma verificação deve ser executada, passa a configuração para o filho.
• Fluxo de trabalho filho: pod efêmero onde a CLI do Renovate executa. Recursos alocados dinamicamente, descriptografam segredos isoladamente, encerram após a conclusão.

Essa separação oferece segurança (segredos criptografados no nível dos pais), otimização de recursos (os pais utilizam recursos mínimos) e escalabilidade (os filhos executam em paralelo).

Os resultados

Transformação de desempenho

• Antes: um repositório por vez, alguns repositórios não seriam processados, possivelmente nem mesmo por um dia ou mais, menos de 1.000 digitalizações por dia.
• Após: mais de 100 varreduras simultâneas, geralmente 8.000 varreduras e até 10.000 varreduras registradas por dia, limitadas apenas pela quantidade de recursos que estamos dispostos a investir e por como lidamos com os limites de taxa do GitHub.

Eficiência de custos

Por mais estranho que pareça, rodar 8.000 pods por dia pode te dar o mesmo resultado muito mais barato do que ter um pod de longa duração tentando alcançar os mesmos resultados.

Na configuração anterior, estávamos executando uma única instância que, em um bom dia, realizaria de 500 a 600 verificações. Ao mesmo tempo, devido ao fato de que diferentes tipos de repositórios seriam executados no mesmo pod, precisávamos dimensionar o pod para os maiores. Esse tamanho seria muito maior do que nossa oferta extra grande atual, usando 8 CPUs para o pod e 16G de memória.

Para atender à saída diária atual, o pod único precisaria executar por 12 dias. Então, comparando o custo desse único pod funcionando por 12 dias com 8.000 pods do nosso tamanho “MÉDIO” funcionando todos os dias, nosso novo design é muito mais eficiente para a mesma saída de escaneamentos:

No entanto, vamos levar em consideração que nossa configuração padrão para nossas cargas de trabalho está definida como "PEQUENA", com a grande maioria funcionando com sucesso com 0,5 CPU e 1 GB de RAM, e apenas algumas precisam ser alteradas para média ou grande. Vamos ver o que acontece se 60% das nossas cargas de trabalho rodarem em "PEQUENA", 30% em "MÉDIA" e 10% em "GRANDE", o que está mais próximo da verdade.

Podemos ver que, para a mesma saída, somos muito mais econômicos em nosso sistema atual.

Segurança aprimorada

• Tokens efêmeros do GitHub (minutos de exposição versus dias).
• Isolamento de espaço de nome com limites de Controle de acesso por função (RBAC).
• Criptografia de segredos em repouso nos fluxos de trabalho principais.
• Acesso direto ao cofre removido.

Desempenho previsível

Com frequência de varredura garantida, finalmente podemos definir Objetivos de nível de serviço (SLOs). A automerge funciona de forma confiável. As equipes confiam que a plataforma vai entregar o que é prometido.

Principais decisões arquitetônicas

Aqui estão algumas das principais decisões de design que moldaram a aparência da plataforma.

• Por que fluxos de trabalho pai-filho?

Adotamos esse padrão para implementar uma estratégia de defesa em profundidade. Ao restringir credenciais de alto valor (como segredos de app GitHub) a um espaço de nome dedicado e bloqueado, utilizamos RBAC para garantir que pods de execução efêmeros não possam acessar arbitrariamente dados sensíveis. Vulnerabilidades recentes na cadeia de suprimentos (por exemplo, os ataques de integração contínua/entrega contínua [CI/CD] "Shai Hulud") demonstraram a importância crítica de isolar os ambientes de execução que executam scripts dinâmicos do repositório de credenciais.

Ao mesmo tempo, essa dissociação permite a otimização granular de recursos. Os fluxos de trabalho "pai" atuam como orquestradores leves com um espaço mínimo, enquanto os fluxos de trabalho "filho" lidam com a verificação de dependências com uso intensivo de computação. Essa separação simplifica gestão de ciclo de vida, permitindo aplicar uma lógica de reconciliação distinta a cada camada, concedendo aos usuários controle sobre os parâmetros de execução (camada filha) e, ao mesmo tempo, mantendo o controle administrativo sobre a infraestrutura de agendamento e segurança (camada pai).

• Por que é do tipo autoatendimento?

Eliminar nossa equipe como gargalo para a configuração do repositório era uma exigência crítica. Nossa missão era arquitetar uma plataforma escalável e de autoatendimento compatível com diversos casos de uso. Reconhecemos que atuar como guardiões de cada alteração de configuração era insustentável, dado o grande volume de repositórios. Em vez disso, adotamos uma filosofia de capacitação: fornecer os "trilhos" (infraestrutura e proteções) e capacitar os usuários a conduzir os "trens" (execução e personalização). Acreditamos que essa mudança em direção à autonomia da equipe aumenta significativamente a produtividade, permitindo que os usuários adaptem o sistema às suas necessidades operacionais específicas.

• Por que o padrão Operator do Kubernetes?

Como mencionado acima, um princípio fundamental de design era garantir que a plataforma fosse totalmente autoatendida. Precisávamos de um mecanismo automatizado para capturar a intenção do usuário (como alternar varreduras, ajustar a frequência de agendamento ou ajustar limites de recursos em tempo de execução) e propagar instantaneamente essas mudanças para os fluxos de trabalho subjacentes. Antecipando requisitos futuros, o sistema também precisava ser facilmente extensível.

Para alcançar esse objetivo, desenvolvemos um operador Kubernetes personalizado para gerenciamento de dependências. Ao usar CRDs como interface de configuração, estabelecemos um ciclo de reconciliação nativo do Kubernetes. Este operador monitora continuamente o estado desejado definido pelo usuário e orquestra automaticamente as atualizações necessárias na infraestrutura do fluxo de trabalho. Isso garante uma operação perfeita e orientada a eventos, onde a lógica da plataforma lida com toda a complexidade nos bastidores.

• Por que projetar um GitHub Events Gateway?

Adotar uma arquitetura orientada a eventos (EDA) foi essencial para a capacidade de resposta da plataforma. Embora os fluxos de trabalho do CronWorkflows fornecessem uma programação de linha de base confiável, precisávamos de agilidade para lidar com execuções ad hoc, como usuários acionando varreduras manualmente por meio do dashboard. Para isso, precisávamos de um gateway de ingestão dedicado para validar a integridade da carga útil e rotear as solicitações de forma inteligente.

Avaliamos as soluções existentes, incluindo o EventSource nativo do GitHub para Argo, mas identificamos riscos significativos relacionados à sobrecarga operacional e às rígidas cotas da API do GitHub (por exemplo, limites de webhook por repositório). Consequentemente, construímos um gateway personalizado para desacoplar nossa infraestrutura dessas limitações.

Fundamentalmente, esse gateway serviu como um ponto estratégico de controle de tráfego durante nossa migração. Ele funcionou como um switch, permitindo que realizássemos uma implementação gradual e granular (mudança de tráfego) do sistema legado para a nova infraestrutura. Isso garantiu que a integração de milhares de repositórios fosse um processo controlado e sem riscos, e não uma transição de "big bang".

Lições aprendidas

Algumas lições que aprendemos andam de mãos dadas com o Elastic Source Code:

1. O cliente em primeiro lugar: as plataformas são criadas para os usuários. Por isso, é importante ter as necessidades dos usuários como prioridade. Isso molda a plataforma em infraestrutura e aplicativos projetados de forma eficiente, que reduzem o atrito com os usuários, simplificam a escalabilidade da plataforma e facilitam a adoção.
2. Espaço, tempo: às vezes, o caminho de menor resistência leva a areias movediças. Inicialmente, tentamos otimizar o modelo de processamento sequencial existente, mas isso não resolveu nossos problemas; na verdade, ele apenas introduziu mais complexidade e pontas soltas. A ousada decisão de reestruturar a plataforma com processamento paralelo exigiu um esforço inicial significativo. No entanto, isso acabou abrindo caminho para um crescimento sustentável da plataforma e praticamente eliminou o trabalho administrativo diário tedioso.
3. TI, depende: uma plataforma não pode operar isoladamente; o sucesso depende de quão bem ela se integra ao ecossistema mais amplo. Em nosso caso, a integração com o Backstage foi fundamental, pois ele serve como a fonte da verdade para a integração perfeita de serviços. Da mesma forma, a conexão com o Artifactory nos permitiu gerenciar com eficiência as atualizações de pacotes privados, e a lista de integrações essenciais continua.
4. Progresso, perfeição SIMPLES: durante toda a implementação, testamos constantemente nossas suposições iniciais e nos adaptamos a novas barreiras à medida que elas surgiam. Em vez de ficarmos paralisados pelo perfeccionismo, adotamos uma abordagem iterativa, enfrentando desafios um a um e ajustando nossa estratégia migratória para atender às condições do mundo real.

O que vem a seguir

A entrega da plataforma nos permite realizar trabalhos mais significativos que ajudarão a melhorar a experiência do usuário e a eficiência da nossa plataforma. Alguns exemplos são:

• Aumentar e colocar proteções na adoção do auto-merge

O recurso de auto-merge acelera significativamente a velocidade da equipe ao eliminar tarefas manuais tediosas. No entanto, precisamos nos certificar de que existam proteções rígidas para garantir que esse aumento de velocidade não prejudique a segurança.

• Melhorar a observabilidade da experiência do usuário final

Uma prioridade crítica para nosso roadmap é aprimorar a observabilidade, não apenas no nível da plataforma, mas também especificamente da perspectiva do usuário final. Embora a captura de métricas de infraestrutura seja simples, entender a experiência real do usuário exige insights mais profundos. Estamos trabalhando para definir os indicadores-chave de desempenho centrados no usuário do núcleo (KPIs) para que nossa telemetria possa detectar pontos de atrito e problemas de desempenho antes que eles se transformem em reclamações dos usuários.

• Remova obstáculos para a adoção

Vislumbrando o futuro, nossa prioridade é identificar e remover quaisquer barreiras que dificultem a adoção da plataforma. Seja desenvolvendo novas integrações ou implantando conjuntos específicos de recursos, estamos comprometidos com o planejamento orientado por dados. Criamos uma plataforma projetada para escalabilidade; nosso foco agora se volta para maximizar o potencial.

O panorama maior

O projeto de fluxos de trabalho de gerenciamento de dependências demonstra um princípio mais amplo: quando você precisa redimensionar ferramentas open source além do modelo de implantação padrão, os padrões nativos do Kubernetes fornecem um caminho a seguir.

Ao adotar:

• CRDs para configuração.
• Operadores para gestão de ciclo de vida.
• Arquitetura orientada por eventos para capacidade de resposta
• GitOps para implantação.

Criamos uma orquestração que se redimensiona independentemente do número de repositórios que gerencia. O desempenho da varredura de um repositório é o mesmo, independentemente de estarmos gerenciando 100 ou 1.000.

Quando um CVE crítico é anunciado, agora temos respostas em minutos, não em horas. Essa é a diferença entre um gargalo e uma vantagem competitiva.

Agradecimentos

Esta plataforma utiliza excelentes ferramentas open source:

• Kubebuilder: o framework open source que usamos para iniciar nossos operadores Kubernetes que inicializam e orquestram nossos fluxos de trabalho. [1][2]
• Backstage: o open source framework no qual construímos nosso Catálogo de serviços e que usamos como nossa versão final. [1][2]
• Argo Workflows e Argo Events: a open source suíte que usamos para orquestrar processos complexos e adicionar processamento dinâmico baseado em eventos. [1][2][3][4]
• CLI do Renovate: a ferramenta de gerenciamento de dependências de open source que processa nossos repositórios. [1][2]

* O modelo de preços do AWS Fargate foi usado como referência para o custo de um único pod, embora nossas cargas de trabalho não estejam necessariamente sendo executadas na AWS, mas sim em clusters Kubernetes completos.

Ao ajustar o Elasticsearch para cargas de trabalho de alta simultaneidade, a abordagem padrão é maximizar a RAM para manter o conjunto de documentos em memória e alcançar baixa latência de busca. Consequentemente, best_compression raramente é considerado para cargas de trabalho de busca, pois é visto principalmente como uma medida de economia de armazenamento para casos de uso do Elastic Observability e Elastic Security, onde a eficiência do armazenamento tem prioridade.

Neste blog, demonstramos que, quando o tamanho do conjunto de dados excede significativamente o cache de páginas do SO, best_compression melhora o desempenho da busca e a eficiência dos recursos, reduzindo o gargalo de E/S.

A configuração

Nosso caso de uso é um aplicativo de busca de alta concorrência executado em instâncias otimizadas para CPU no Elastic Cloud.

• Volume de dados: ~500 milhões de documentos
• Infraestrutura: 6 instâncias Elastic Cloud (Elasticsearch Service) (cada instância: 1,76 TB de armazenamento | 60 GB de RAM | 31,9 vCPU)
• Relação memória-armazenamento: ~5% do conjunto de dados total cabe na RAM

Os sintomas: alta latência

Observamos que quando o número de solicitações atuais aumentou drasticamente por volta das 19:00, a latência na busca se deteriorou significativamente. Como mostrado na Figura 1 e na Figura 2, enquanto o tráfego atingiu o pico em torno de 400 solicitações por minuto por instância do Elasticsearch, o tempo médio de serviço de consulta se degradou para mais de 60 ms.

O uso da CPU permaneceu relativamente baixo após o tratamento inicial das conexões, indicando que o processamento não era o gargalo.

Uma forte correlação surgiu entre volume de consultas e falhas de página. À medida que os pedidos aumentavam, observamos um aumento proporcional nas falhas de página, atingindo o pico em torno de 400 mil por minuto. Isso indicava que o conjunto de dados ativo não cabia no cache da página.

Simultaneamente, o uso do heap da JVM parecia normal e saudável. Isso descartou problemas de coleta de lixo e confirmou que o gargalo era de E/S.

O diagnóstico: limitado por E/S

O sistema estava limitado por E/S. O Elasticsearch depende do cache de páginas do sistema operacional para fornecer dados de índice a partir da memória. Quando o índice é grande demais para o cache, consultas acionam leituras de disco caras. Embora a solução típica seja redimensionar horizontalmente (adicionar nodes/RAM), queríamos primeiro esgotar as melhorias de eficiência em nossos recursos existentes.

A correção

Como padrão, o Elasticsearch usa a compressão LZ4 para seus segmentos de índice, buscando um equilíbrio entre velocidade e tamanho. Hipotetizamos que mudar para best_compression (que usa zstd) reduziria o tamanho dos índices. Um espaço menor permite que uma porcentagem maior do índice caiba no cache da página, trocando um aumento insignificante na CPU (por descompressão) por uma redução na E/S do disco.

Para habilitar best_compression, reindexamos os dados com a configuração de índice index.codec: best_compression. O mesmo resultado poderia ser alcançado fechando o índice, resetando o codec do índice para best_compression, e então realizando uma fusão de segmentos.

POST my-index/_close
PUT my-index/_settings
{
    "codec": "best_compression"
}
  
POST my-index/_open  
POST my-index/_forcemerge?max_num_segments=1

Os resultados

Os resultados confirmaram nossa hipótese: a eficiência aprimorada do armazenamento se traduziu diretamente em um aumento substancial no desempenho da busca, sem nenhum aumento na utilização da CPU.

A aplicação de best_compression reduziu o tamanho do índice em aproximadamente 25%. Embora menor do que a redução observada em dados de log repetitivos, essa redução de 25% aumentou efetivamente nossa capacidade de cache de páginas pela mesma margem.

Durante o próximo teste de carga (começando às 17:00), o tráfego foi ainda maior, atingindo o pico de 500 solicitações por minuto por nó Elasticsearch.

Apesar da maior carga, a utilização da CPU foi menor do que na execução anterior. O uso elevado no teste anterior provavelmente se deveu à sobrecarga do tratamento excessivo de falhas de página e gerenciamento de E/S de disco.

Crucialmente, as falhas de página caíram significativamente. Mesmo em maior débito, as falhas ficaram em torno de <200 mil por minuto, comparado a >300 mil no teste inicial.

Embora os resultados de falha na página ainda não tenham sido ideais, o tempo de serviço de consulta foi reduzido em cerca de 50%, pairando abaixo de 30 ms, mesmo sob carga mais pesada.

A conclusão: best_compression para busca

Para casos de uso de busca em que o volume de dados excede a memória física disponível, best_compression é uma poderosa alavanca de ajuste de desempenho.

A solução convencional para falhas de cache é redimensionar para aumentar a RAM. No entanto, ao reduzir a pegada do índice, alcançamos o mesmo objetivo: maximizar a contagem de documentos no cache da página. Nosso próximo passo é explorar a classificação de índices para otimizar ainda mais o armazenamento e extrair ainda mais desempenho de nossos recursos existentes.

Os agentes estão ganhando força, impulsionados pelo potencial de entregar ganhos de eficiência e melhores experiências para os clientes. Mas, na prática, fornecer aos agentes o contexto correto é difícil, principalmente quando se trabalha com dados empresariais desorganizados e não estruturados. Os desenvolvedores precisam gerenciar ferramentas, prompts, estado, lógica de raciocínio, modelos e, principalmente, recuperar o contexto relevante das fontes comerciais para fornecer resultados e ações precisos. O Elastic Agent Builder oferece esses componentes essenciais para desenvolver agentes seguros, confiáveis e orientados ao contexto.

Principais funcionalidades do Agent Builder

O Agent Builder aproveita os investimentos de longo prazo da Elastic na relevância de busca e retrieval-augmented generation, e trabalha para tornar o Elasticsearch o melhor banco de dados vetorial para simplificar o desenvolvimento de agentes de IA contextuais e focados em dados.

O Agent Builder permite que você:

• Comece com um agente conversacional integrado que pode responder a perguntas, realizar análises e conduzir investigações sobre quaisquer dados no Elasticsearch.
• Passe de dados complexos não estruturados para um agente personalizado com uma experiência de desenvolvimento baseada em configuração.
• Aproveite a relevância de pesquisa híbrida de ponta por meio do ES|QL integrado ou de ferramentas personalizadas para melhorar a qualidade do contexto e a confiabilidade do agente.
• Execute fluxos de trabalho complexos (pré-visualização) como ferramentas reutilizáveis para enriquecer dados, atualizar registros, enviar mensagens e muito mais para automação baseada em regras.
• Conecte-se a fontes de dados fora do Elasticsearch usando fluxos de trabalho e MCP para correlacionar e combinar o contexto dos agentes.
• Integre-se a qualquer framework agêntico ou aplicação usando ferramentas integradas e personalizadas expostas via MCP, além da capacidade de conectar-se a MCPs externos (em pré-visualização), suporte para A2A e suporte completo à API.
• Amplie os recursos do Agent Builder com integração a soluções de terceiros, como o LlamaIndex para processamento complexo de documentos ou o Arcade.dev para acesso seguro e estruturado a ferramentas.

Para ampliar ainda mais a funcionalidade do Agent Builder, apresentamos o Elastic Workflows, nossos novos recursos de automação baseados em regras, agora em versão prévia técnica. Para tarefas organizacionais, os agentes às vezes precisam de certeza e confiabilidade de ações baseadas em regras, que geralmente são necessárias para implementar uma lógica comercial específica. O Elastic Workflows oferece aos agentes uma maneira simples e declarativa de orquestrar sistemas internos e externos para executar ações, coletar e transformar dados e contexto. Os fluxos de trabalho são totalmente componíveis, orientados a eventos e flexíveis, e podem ser expostos como ferramentas a um agente via MCP.

De dados a agentes em questão de minutos

Os agentes de desenvolvimento podem levar semanas de trabalho inicial para consolidar armazenamentos de dados separados, criar pipelines manuais, ajustar consultas e gerenciar orquestrações complexas. O Agent Builder reduz o tempo de desenvolvimento para os agentes, acabando com a necessidade de armazenamentos de dados separados, bancos de dados vetoriais, pipelines RAG, camadas de pesquisa, tradutores de consultas e orquestradores de ferramentas, permitindo que você se concentre na lógica do agente e na entrega do aplicativo.

O Agent Builder integra de forma nativa primitivas da plataforma Elasticsearch para agilizar o desenvolvimento de agentes.

• Comece com um agente conversacional integrado que pode conversar e raciocinar imediatamente com seus dados indexados.
• Integre agentes em aplicações, dashboards ou sistemas de CI/CD com acesso interativo via Kibana, APIs ou MCP e A2A.
• Crie com as ferramentas padrão para entender a estrutura dos seus dados, selecionar o índice apropriado, gerar consultas híbridas, semânticas e estruturadas otimizadas e criar visualizações configuráveis usando ES|QL com base em comandos em linguagem natural.

Para se aprofundar, veja um passo a passo prático e completo.

Crie com o Elasticsearch, uma plataforma de dados completa para engenharia de contexto

Para agentes de IA, a qualidade do contexto é essencial para fornecer raciocínio eficaz e reduzir os riscos de alucinação. Para muitos agentes de IA corporativa, os dados de negócios necessários para realizar uma tarefa são a peça fundamental de contexto. Como um armazenamento de dados altamente escalável, banco de dados vetorial e líder em relevância, o Elasticsearch já oferece muitas primitivas fortes de engenharia de contexto. A engenharia de contexto vai além da simples retrieval-augmented generation, permitindo que você personalize e redimensione como os dados são obtidos, ranqueados, filtrados e apresentados aos agentes, ajudando a reduzir ruído e ambiguidade.

O Elasticsearch oferece um mecanismo de contexto que combina busca lexical, busca vetorial e filtragem estruturada para recuperação de dados, o que melhora o desempenho do LLM ao garantir que o modelo opere em um contexto relevante e preciso. Essa capacidade é suportada por recuperação agêntica, juntamente com ferramentas integradas e lógica de busca que selecionam automaticamente os índices corretos e transformam a linguagem natural em consultas otimizadas para o contexto.

Com o Agent Builder, você garante que os agentes recebam primeiro o contexto mais útil com controles de relevância e classificação, permitindo que você ajuste a lógica de pontuação, classificação e filtragem. O Elasticsearch permite que você controle o que importa, por que importa e como é priorizado, em vez de depender de um comportamento opaco de recuperação. Tudo isso é sustentado pelo Elasticsearch como uma plataforma de dados escalável para armazenar e escalar todos os seus dados de texto, vetores, metadados, logs e muito mais em uma plataforma, facilitando o gerenciamento do contexto para os agentes.

Executar fluxos de trabalho complexos como ferramentas reutilizáveis

Enquanto agentes de IA permitem o raciocínio para tarefas complexas, grande parte da automação depende da execução confiável de ações baseadas em regras que aplicam lógica de negócios específica. O Elastic Workflows oferece uma maneira simples e declarativa de orquestrar sistemas internos e externos para realizar ações, coletar contexto ou dados e integrá-los como parte dos agentes. Definidos em YAML, os fluxos de trabalho são totalmente componíveis, permitindo que sejam tão simples ou complexos quanto o trabalho exigir. Isso oferece aos agentes uma maneira eficiente de agir em toda a plataforma e nas soluções do Elasticsearch, bem como com aplicativos de terceiros.

A integração de um fluxo de trabalho com o Agent Builder pode ser feita em três etapas (pré-requisito: habilitar fluxos de trabalho com detalhes fornecidos aqui)

1. Criar e salvar um novo fluxo de trabalho usando o editor simples baseado em YAML com autopreenchimento e testes integrados.

2. Crie uma nova ferramenta no Agent Builder com o tipo “Fluxo de trabalho” e informe uma descrição para ajudar o agente a determinar quando usar a ferramenta de fluxo de trabalho.

3. Adicione a ferramenta de fluxo de trabalho ao seu agente personalizado.

4. É isso aí! Agora o agente pode chamar o fluxo de trabalho dentro de uma conversa.

Seu agente, suas regras

O Agent Builder não te prende a um único paradigma de desenvolvimento. Em vez disso, ele foi projetado para permitir abordagens de desenvolvimento abertas e flexíveis para agentes com controle total de dados, relevância, modelos, interoperabilidade, security e design de agentes.

As definições de agentes personalizados permitem que você escolha exatamente quais ferramentas um agente pode acessar, incorpore avisos de sistema personalizados, adapte as instruções do agente e defina limites de segurança. Os agentes permanecem independentes do modelo, permitindo que você configure com flexibilidade um LLM preferido, tanto nativo quanto em todo o ecossistema, sem ficar preso a um único provedor.

Crie ferramentas extensíveis que encapsulem lógica específica do domínio (por exemplo, filtros de índice específicos, junções ES|QL, pipelines analíticos) e restrinja-as para uso seguro em produção. O suporte completo à API permite a interoperabilidade com outras frameworks de agentes, com suporte nativo ao Protocolo de Contexto do Modelo (MCP). A integração A2A significa que você pode expor seus agentes Elastic a outros frameworks, serviços e apps clientes, reutilizando a mesma lógica de engenharia de dados e contexto em todas as integrações.

O Agent Builder suporta desenvolvimento flexível e aberto e foi projetado para se integrar com frameworks e plataformas populares de agentes. Essas integrações podem ser essenciais para entregar agentes eficazes. Como descreve Sam Partee, cofundador da Arcade.dev,

"Sistemas agênticos falham hoje porque conectar IA a ferramentas e dados é algo complexo. O Elastic Agent Builder com Arcade.dev oferece aos desenvolvedores uma maneira estruturada e segura de lidar com a forma como os agentes recuperam o contexto, raciocinam e agem, levando os agentes da demonstração ao nível de produção."

O Agent Builder também aproveita a extensibilidade do Elasticsearch para lidar com dados complexos. Como descreve Jerry Liu, CEO da LlamaIndex ,

“Extrair o contexto empresarial de fontes de dados não estruturadas é fundamental para a criação de agentes eficazes. O Elastic Agent Builder combinado com o processamento de documentos complexos do LlamaIndex fortalece a camada fundamental de contexto, ajudando as equipes a recuperar, processar e preparar dados para que os agentes possam raciocinar com mais precisão e oferecer melhores resultados."

O que você pode construir?

O Agent Builder já está sendo usado para vários casos de uso. Abaixo estão alguns exemplos e arquiteturas de referência para começar a usar agentes:

• Automatizar infraestrutura: em cenários de suporte, os agentes têm sido usados para ler, pensar e conversar, mas até o momento, eles não conseguem acessar e tocar a infraestrutura que possam precisar gerenciar. A equipe de engenharia da Elastic criou um agente para gerenciamento automatizado de infraestrutura como parte de um hackathon. O agente investiga ativamente problemas com a infraestrutura da aplicação e age de forma automatizada. Ele usa fluxos de trabalho para otimizar configurações, responder a problemas e redimensionar recursos, tudo com base em uma compreensão inteligente dos logs de infraestrutura.
• Análise de ameaças à segurança: um agente de vulnerabilidade de segurança foi desenvolvido com Elastic Agent Builder, MCP e Elasticsearch. Ele automatiza a análise de ameaças correlacionando dados de segurança internos com inteligência de ameaças externa. O agente realiza buscas semânticas em incidentes e configurações históricas, amplia os resultados com dados da internet em tempo real e aplica o raciocínio LLM para avaliar a relevância ambiental, priorizar riscos e produzir medidas corretivas viáveis. Consulte a arquitetura de referência.
• Suporte técnico ao cliente: os agentes podem executar diversas tarefas de suporte, incluindo resumo de casos, identificação e criação de problemas duplicados e investigação técnica aprofundada. O Agent Builder permite isso com uma pesquisa híbrida de várias etapas para encontrar somente os problemas, soluções e procedimentos relacionados mais relevantes e formular hipóteses de causa raiz e planos de remediação. O Agent Builder pode simplificar a arquitetura de sistemas de suporte complexos e acelerar o tempo de entrega.
• Descoberta de produtos e conteúdo: o Agent Builder simplifica o processo de expor catálogos complexos de produtos para experiências conversacionais, ao mesmo tempo em que permite que as organizações mantenham flexibilidade para incluir a própria lógica e requisitos de negócios.
• Crie você mesmo: participe do Hackathon do Agent Builder, que ocorrerá de 22 de janeiro a 27 de fevereiro de 2026. Trabalhe com a comunidade para criar agentes de IA orientados por contexto e em várias etapas que combinem buscar, fluxos de trabalho, ferramentas e raciocínio para automatizar tarefas do mundo real*

Comece a criar agentes personalizados agora

Comece com um teste do Elastic Cloud e confira a documentação aqui. Para clientes existentes, o Agent Builder está disponível no Cloud Serverless e no nível Empresarial no Elastic Cloud Hosted e autogerenciado.

* Clique aqui para ver os termos, condições e requisitos de elegibilidade para o hackathon

Uma das maneiras pelas quais o vidro será quebrado é pela adoção de agentes de voz, que são agentes de IA que reconhecem a fala humana e sintetizam áudio gerado por computador. Com o crescimento das transcrições de baixa latência, modelos de linguagem grandes e rápidos (LLMs) e modelos de texto para fala que soam humanos, isso se tornou possível.

Os agentes de voz também precisam ter acesso a dados empresariais para se tornarem realmente valiosos. Neste artigo, aprenderemos como funcionam os agentes de voz e criaremos um para a ElasticSport, uma loja fictícia de equipamentos esportivos para atividades ao ar livre, usando LiveKit e Elastic Agent Builder. Nosso agente de voz será sensível ao contexto e funcionará com nossos dados.

Como funciona

Existem dois paradigmas no mundo dos agentes de voz: o primeiro usa modelos de fala para fala, e o segundo usa um pipeline de voz que consiste em fala para texto, LLM e texto para fala. Modelos de fala para fala têm os próprios benefícios, mas os pipelines de voz oferecem muito mais personalização das tecnologias usadas e de como o contexto é gerenciado, além de controle sobre o comportamento do agente. Vamos focar o modelo de pipeline de voz.

Principais componentes

Transcrição (fala para texto)

A transcrição é o ponto de entrada no pipeline de voz. O componente de transcrição recebe como entrada quadros de áudio brutos, transcreve a fala em texto e gera esse texto como saída. O texto transcrito é armazenado em buffer até que o sistema detecte que a fala do usuário terminou, momento em que a geração do LLM é iniciada. Diversos fornecedores terceirizados oferecem transcrições de baixa latência. Ao selecionar um, leve em consideração a latência e a precisão da transcrição, e certifique-se de que ele suporte transcrições em fluxo contínuo.

Exemplos de APIs de terceiros: AssemblyAI, Deepgram, OpenAI, ElevenLabs

Detecção de curva

A detecção de turno é o componente do pipeline que detecta quando o falante termina de falar e a geração deve começar. Uma maneira comum de fazer isso é por meio de um modelo de detecção de atividade de voz (VAD), como o Silero VAD. O VAD utiliza níveis de energia do áudio para detectar quando o áudio contém fala e quando a fala terminou. No entanto, o VAD sozinho não consegue identificar a diferença entre pausa e fim da fala. Por isso, muitas vezes é combinado com um modelo de fim de enunciado que prevê se o falante terminou de falar, com base na transcrição intermediária ou no áudio bruto.

Exemplos (Hugging Face): livekit/turn-detector, pipecat-ai/smart-turn-v3

Agente

O agente é o núcleo de um pipeline de voz. É responsável por entender a intenção, reunir o contexto certo e formular uma resposta em formato de texto. O Elastic Agent Builder, com suas capacidades integradas de raciocínio, biblioteca de ferramentas e integração de fluxos de trabalho, é um agente capaz de trabalhar sobre seus dados e interagir com serviços externos.

LLM (texto para texto)

Ao selecionar um LLM para o Elastic Agent Builder, há duas características principais a considerar: benchmarks de raciocínio de LLM e tempo até o primeiro token (TTFT).

Benchmarks de raciocínio indicam quão bem o LLM consegue gerar respostas corretas. Os benchmarks a serem considerados são aqueles que avaliam a adesão à conversa em múltiplos turnos e os benchmarks de inteligência, como o MT-Bench e o conjunto de dados Humanity's Last Exam, respectivamente.

Os benchmarks TTFT avaliam a rapidez com que o modelo produz seu primeiro token de saída. Existem outros tipos de benchmarks de latência, mas a TTFT é particularmente importante para agentes de voz, pois a síntese de áudio pode começar assim que o primeiro token é recebido, resultando em menor latência entre os turnos, uma conversa com sensação natural.

Normalmente, é preciso fazer uma troca entre essas duas características porque modelos mais rápidos geralmente têm um desempenho pior em benchmarks de raciocínio.

Exemplos (Hugging Face): openai/gpt-oss-20b, openai/gpt-oss-120b

Síntese (texto para fala)

A parte final do pipeline é o modelo de conversão de texto em fala. Esse componente é responsável por converter a saída de texto do LLM em fala audível. Semelhante ao LLM, a latência é uma característica a ser observada ao selecionar um provedor de texto para fala. A latência de texto para fala é medida pelo tempo até o primeiro byte (TTFB). Esse é o tempo que leva para receber o primeiro byte de áudio. Menor TTFB também reduz a latência de giro.

Exemplos: ElevenLabs, Cartesia, Rime

Construção do pipeline de voz

O Elastic Agent Builder pode ser integrado a um pipeline de voz em vários níveis diferentes:

1. Ferramentas apenas do Agent Builder: fala para texto → LLM (com ferramentas Agent Builder) → texto para fala
2. Agent Builder como MCP: fala para texto → LLM (com acesso ao Agent Builder via MCP) → texto para fala
3. Agent Builder como núcleo: conversão de fala em texto → Agent Builder → conversão de texto em fala

Para este projeto, escolhi o Agent Builder como abordagem núcleo. Com essa abordagem, toda a funcionalidade do Agent Builder e dos fluxos de trabalho pode ser utilizada. O projeto usa o LiveKit para orquestrar a conversão de fala em texto, detecção de turnos e conversão de texto em fala, e implementa um node LLM personalizado que se integra diretamente ao Agent Builder.

Agente de voz do suporte da Elastic

Criaremos um agente de voz de suporte personalizado para uma loja de esportes fictícia chamada ElasticSport. Os clientes poderão ligar para a linha de ajuda, solicitar recomendações de produtos, encontrar detalhes do produto, verificar o status do pedido e receber as informações do pedido por mensagem de texto. Para isso, primeiro precisamos configurar um agente personalizado e criar ferramentas para executar a Elasticsearch linguagem de consulta (ES|QL) e fluxos de trabalho.

Configurando o agente

Prompt

O prompt orienta o agente qual a personalidade que deve ter e como responder. É importante ressaltar que há alguns prompts específicos de voz que garantem que as respostas sejam sintetizadas em áudio adequadamente e que os mal-entendidos sejam recuperados de forma graciosa.

You are a Sales Assistant at ElasticSport, an outdoor sport shop specialized in hiking and winter equipment. 

[Profile]
- name: Iva
- company: ElasticSport
- role: Sales Assistant
- language: en-GB
- description: ElasticSport virtual sales assistant

[Context]
- Ask clarifying questions to understand the context.
- Use available tools to answer the user's question.
- Use the knowledge base to retrieve general information

[Style]
- Be informative and comprehensive.
- Maintain a professional, friendly and polite tone.
- Mimic human behavior and speech patterns.
- Be concise. Do not over explain initially

[Response Guideline]
- Present dates in spelled-out month date format (e.g., January fifteenth, two thousand and twenty-four).
- Avoid the use of unpronounceable punctuation such as bullet points, tables, emojis.
- Respond in plain text, avoid any formatting.
- Spell out numbers as words for more natural-sounding speech.
- Respond in short and concise sentences. Responses should be 1 or 2 sentences long.

[ERROR RECOVERY]
### Misunderstanding Protocol
1. Acknowledge potential misunderstanding
2. Request specific clarification

Fluxos de trabalho

Vamos adicionar um pequeno fluxo de trabalho para enviar um SMS pela API de mensagens do Twilio. O fluxo de trabalho será exposto ao agente personalizado como uma ferramenta, resultando em uma experiência de usuário em que o agente poderá enviar um SMS ao chamador durante a chamada. Isso permite que o autor da chamada, por exemplo, pergunte: "Você pode enviar os detalhes sobre X por texto?"

name: send sms
enabled: true
triggers:
  - type: manual
inputs:
  - name: message
    type: string
    description: The message to send to the phone number.

  - name: phone_number
    type: string
    description: The phone number to send the message to.

consts:
  TWILIO_ACCOUNT: "****"
  BASIC_AUTH: "****"
  FROM_PHONE_NNUMBER: "****"
steps:
  - name: http_step
    type: http
    with:
      url: https://api.twilio.com/2010-04-01/Accounts/{{consts.TWILIO_ACCOUNT}}/Messages.json
      method: POST
      headers:
        Content-Type: application/x-www-form-urlencoded
        Authorization: Basic {{consts.BASIC_AUTH | base64_encode}}
      body: From={{consts.FROM_PHONE_NNUMBER}}&To={{inputs.phone_number}}&Body={{inputs.message}}
      timeout: 30s

Ferramentas ES|QL

As ferramentas a seguir permitem que o agente forneça respostas relevantes fundamentadas em dados reais. O repositório de exemplo contém um script de configuração para iniciar o Kibana com conjuntos de dados de produtos, pedidos e base de conhecimento.

• Product.search

O conjunto de dados de produtos contém 65 produtos fictícios. Este é um documento de exemplo:

{
      "sku": "ort3M7k",
      "name": "Ortovox Free Rider 26 Backpack",
      "price": 189,
      "currency": "USD",
      "image": "https://via.placeholder.com/150",
      "description": "The Ortovox Free Rider 26 is a technical freeride backpack with a dedicated safety compartment and diagonal ski carry system. Perfect for backcountry missions.\n\nKey Features:\n- 26L capacity\n- Diagonal ski carry system\n- Safety equipment compartment\n- Helmet holder\n- Hydration system compatible",
      "category": "Accessories",
      "subCategory": "Backpacks",
      "brand": "Ortovox",
      "sizes": ["One Size"],
      "colors": ["Black", "Blue", "Orange"],
      "materials": ["Nylon", "Polyester"]
    }

Os campos de nome e descrição são mapeados como semantic_text, permitindo que o LLM use busca semântica via ES|QL para recuperar produtos relevantes. A consulta de busca híbrida realiza correspondência semântica em ambos os campos, com um peso um pouco maior aplicado às correspondências no campo do nome usando um boost.

A consulta primeiro recupera os 20 melhores resultados classificados pela pontuação inicial de relevância. Esses resultados são então reclassificados com base no campo de descrição usando o modelo de inferência .rerank-v1-elasticsearch e, finalmente, reduzidos para os cinco produtos mais relevantes.

type: ES|QL
toolId: products.search
description: Use this tool to search through the product catalogue by keywords.
query: |
    FROM products
        METADATA _score
      | WHERE
          MATCH(name, ?query, {"boost": 0.6}) OR
            MATCH(description, ?query, {"boost": 0.4})
      | SORT _score DESC
      | LIMIT 20
      | RERANK ?query
            ON description
            WITH {"inference_id": ".rerank-v1-elasticsearch"}
      | LIMIT 5

parameters:
    query: space separated keywords to search for in catalogue

• Knowledgebase.search

Os conjuntos de dados da base de conhecimento contêm documentos do seguinte formato, onde os campos de título e conteúdo são armazenados como texto semântico:

{
        id: "8273645",
        createdAt: "2025-11-14",
        title: "International Orders",
        content: `International orders are processed through our international shipping partner. Below are the countries we ship to and average delivery times.
        Germany: 3-5 working days
        France: 3-5 working days
        Italy: 3-5 working days
        Spain: 3-5 working days
        United Kingdom: 3-5 working days
        United States: 3-5 working days
        Canada: 3-5 working days
        Australia: 3-5 working days
        New Zealand: 3-5 working days
        `
}

E a ferramenta usa uma consulta semelhante à ferramentaproduct.search:

type: "ES|QL"
toolId: knowledgebase.search
description: Use this tool to search the knowledgebase.
query: |
  FROM knowledge_base
    METADATA _score
  | WHERE
      MATCH(title, ?query, {"boost": 0.6}) OR
      MATCH(content, ?query, {"boost": 0.4})
  | SORT _score DESC
  | LIMIT 20
  | RERANK ?query
      ON content
      WITH {"inference_id": ".rerank-v1-elasticsearch"}
  | LIMIT 5

parameters:
  query: space separated keywords or natural language phrase to semantically search for in the knowledge base

• Orders.search

A última ferramenta que adicionaremos é aquela usada para recuperar pedidos por order_id:

type: "ES|QL"
toolId: order.search
description: Use this tool to retrieve an order by its ID.
query: |
  FROM orders
    METADATA _score
  | WHERE order_id == ?order_id
  | SORT _score DESC
  | LIMIT 1

parameters:
  order_id: "the ID of the order"

Após configurar o agente e anexar esses fluxos de trabalho e ES|QL para o agente, o agente pode ser testado dentro do Kibana.

Além de construir um agente de suporte ElasticSport, o agente, fluxos de trabalho e ferramentas podem ser adaptados a outros casos de uso, como um agente de vendas que qualifica leads, um agente de serviço para reparos residenciais, reservas para um restaurante ou um agente de agendamento de consultas.

A parte final é conectar o agente que acabamos de criar com modelos LiveKit, texto para fala e fala para texto. O repositório (link no fim do artigo) contém um node personalizado do LLM Elastic Agent Builder que pode ser usado com o LiveKit. Basta trocar o AGENT_ID pelo seu e vinculá-lo com sua instância Kibana.

Para começar

Confira o código e experimente você mesmo aqui.

Todos nós já vimos o crescimento dos agentes de IA. Eles são fantásticos em resumir textos, escrever trechos de código e responder perguntas baseadas em documentação. Mas, para nós que trabalhamos com DevOps e engenharia de confiabilidade de sites (SRE), houve uma limitação frustrante. A maioria dos agentes está presa ao paradigma do call center, o que significa que eles podem ler, pensar e conversar, mas não conseguem entrar em contato e tocar na infraestrutura que deveriam estar gerenciando.

Para nosso último projeto de hackathon, decidimos eliminar essa limitação.

Nós construímos Infraestrutura ampliada: um copiloto de infraestrutura que não apenas dá conselhos, mas também cria, implanta, monitora e corrige seu ambiente em tempo real.

O problema: copiar, formatar, colar

Os agentes padrão operam em um vácuo. Se o seu app for desativado e custar US$ 5 milhões para a empresa, um agente padrão poderá ler para você o manual de instruções para corrigi-lo. Mas você ainda precisa fazer o trabalho. Você terá que copiar o código, reformatá-lo para o seu ambiente e colá-lo no terminal.

Queríamos um agente que entendesse a diferença entre falar sobre o Kubernetes e configurar o Kubernetes.

O motor: o que é o Elastic Agent Builder?

Para construir isso, não começamos do zero. Construímos sobre o Elastic Agent Builder. Para quem não conhece, o Elastic Agent Builder é um framework projetado para desenvolver agentes rapidamente, e atua como a ponte entre um grande modelo de linguagem (LLM) (em nossa demonstração, usamos o Google Gemini) e dados privados armazenados no Elasticsearch.

O Agent Builder pode ser usado para IA conversacional, baseando-o em dados internos, como documentos ou registros. Mas seu recurso mais avançado é a capacidade de atribuir ferramentas. Essas ferramentas permitem que o LLM saia da interface de bate-papo para realizar tarefas específicas. Percebemos que, se levássemos esse recurso ao limite, poderíamos transformar o Agent Builder em uma potência de automação.

Fazendo funcionar: construindo a primeira versão

Quando começamos o projeto, sabíamos que queríamos que os agentes fossem capazes de mudar o mundo exterior. Tivemos uma ideia: e se construíssemos algum software "runner" (para executar qualquer comando que o agente pudesse imaginar no host)? E depois: e se os runners, o Elastic Agent Builder e o usuário estivessem em uma chamada tripla?

Começamos desenvolvendo um projeto em Python, os Runners de Infraestrutura Ampliada, que era essencialmente um loop while(true) que consultava a API de conversas do Elastic Agent Builder a cada segundo e verificava uma sintaxe especial que havíamos criado:

{
	"tool_name": "my_tool",
       "tool_arguments": "\{stringified json arguments\}"
}

Depois, atualizamos o prompt para ensiná-lo nossa nova sintaxe de chamada de ferramenta. Bill é o mantenedor do FastMCP, o framework mais popular para a criação de servidores MCP (Model Context Protocol) em Python. Ele começou a trabalhar usando o cliente FastMCP com este novo software de runner para montar servidores MCP e disponibilizar suas ferramentas ao runner. Quando o agente via isso, executava a chamada de ferramenta e POST os resultados de volta para a conversa como se o usuário tivesse enviado os resultados. Isso acionou o LLM para responder ao resultado, e seguimos em frente!

Isso foi ótimo, mas houve dois problemas principais:

1. O agente despejaria todo esse JSON diretamente na conversa com o usuário.
2. O momento mais antigo em que mensagens eram visíveis pela API de conversas foi quando uma rodada de conversa foi concluída (ou seja, quando o LLM respondeu).

Então, começamos a descobrir como colocar isso em segundo plano.

Depois, passamos a dar ao agente uma ferramenta chamada call_external_tool com dois argumentos: o argumento tool_name e o argumento da ferramenta JSON stringified. Essa chamada de ferramenta externa não retornaria nada, mas, mais importante, seria visível na requisição GET para a API de conversas. Em seguida, demos permissão aos runners para escrever documentos diretamente no Elasticsearch, que o agente do Elastic Agent Builder poderia recuperar conforme necessário. O agente está sempre operando em resposta a uma mensagem do usuário, então precisamos iniciar o agente com uma mensagem de usuário para que ele busque os resultados e continue o processamento. Então pedimos aos agentes que inserissem uma pequena mensagem no chat para retomar a conversa:

Então, agora tínhamos chamadas de ferramentas externas. No entanto, devido ao segundo problema mencionado acima, tivemos que eliminar a parte final do pontapé inicial. Caso contrário, cada chamada de ferramenta externa exigiria uma rodada completa de conversas para recuperar os resultados!

Aprimorando: introduzindo fluxos de trabalho

Além das chamadas da linguagem de consulta Elasticsearch (ES|QL) e da ferramenta de busca de índice, os agentes do Agent Builder podem chamar ferramentas baseadas em fluxo de trabalho da Elastic. Fluxos de trabalho da Elastic oferecem uma forma flexível e fácil de gerenciar para executar uma sequência arbitrária e uma lógica de ações. Para nossos propósitos, tudo o que precisamos é que o fluxo de trabalho armazene uma solicitação de ferramenta externa para o Elasticsearch e retorne uma ID para pesquisar os resultados. Isso resulta na seguinte definição simples de fluxo de trabalho:

name: ai-tool-call
enabled: true
triggers:
  - type: manual
inputs:
  - name: runner_id
    type: string
  - name: tool_calls
    type: string

steps:
  - name: store_request
    type: elasticsearch.create
    with:
      index: distributed-tool-requests
      id: "{{inputs.runner_id}}_{{ execution.id }}"
      document:
        request_id: "{{ execution.id }}"
        runner_id: "{{inputs.runner_id}}"
        tool_call: "{{inputs.tool_calls}}"
        status: "unhandled"

  - name: output_result
    type: console
    with:
      message: "Called tool, with execution id: {{ execution.id }}. Use this ID to poll the results."

Com isso, em vez de depender do pedido de chamada de ferramenta registrado na conversa, os runners podem simplesmente consultar o índice distributed-tool-requests do Elasticsearch para novas solicitações de ferramentas externas e registrar os resultados em outro índice do Elasticsearch com o execution.id fornecido.

Isso elimina os dois principais problemas mencionados acima:

1. O histórico de conversas não está mais saturado com a carga útil das chamadas de ferramentas externas.
2. Como os runners estão consultando o índice do Elasticsearch em vez do histórico de conversas, eles não são bloqueados pela rodada de conversa a ser concluída para que os pedidos externos de ferramentas fiquem visíveis.

O segundo ponto tem a grande vantagem de que o processamento das chamadas de ferramentas externas começa dentro da fase de pensamento do agente (e não quando a rodada de conversação é concluída). Isso nos permite instruir o LLM no prompt do sistema para sondar os resultados da ferramenta externa até que os resultados estejam disponíveis e elimina a necessidade da mensagem de inicialização. De modo geral, isso tem o efeito positivo de tornar a conversa mais natural: o LLM consegue processar várias solicitações de ferramentas externas em uma única rodada de conversa (em vez de exigir uma rodada de conversa para cada solicitação de ferramenta) e, portanto, consegue atender a solicitações de usuários mais complexas de uma só vez.

Juntando tudo

Para preencher a lacuna entre o LLM e o rack de servidores, desenvolvemos uma arquitetura específica usando as capacidades da ferramenta do Agent Builder:

1. Runners de Infraestrutura Ampliada: nós implantamos executantes leves dentro dos ambientes de destino (servidores, clusters Kubernetes, contas de nuvem). Esses executores são conectados diretamente à Elastic, usando endpoints seguros e segredos disponíveis apenas para cada um dos executores.
2. Recuperação ES|QL: o copiloto usa o ES|QL da Elastic para realizar buscar híbridas. Não busca apenas conhecimento; busca capacidades. Ele consulta os executores runners para ver quais ferramentas estão disponíveis (por exemplo, list_ec2_instances, install_helm_chart).
3. Execução do fluxo de trabalho: Quando o agente decide sobre um curso de ação, ele cria um fluxo de trabalho estruturado.
4. Ciclo de feedback: os runners executam o comando localmente e enviam os resultados de volta ao Elasticsearch. O copiloto lê o resultado do índice e decide o próximo passo.

A demonstração: da interrupção à observabilidade

No vídeo, apresentamos dois cenários distintos que demonstram como essa arquitetura pode melhorar.

Cenário 1: Resgate DevOps

Começamos com um usuário entrando em pânico por causa de uma queda de 5 milhões de dólares causada por um ponto cego no cluster Kubernetes deles.

• O pedido: "como faço para garantir que isso não aconteça de novo?"
• A ação: o agente não se limitou a oferecer um tutorial. Ele identificou o cluster, criou os espaços de nome necessários, gerou secrets do Kubernetes, instalou o OpenTelemetry Operator e forneceu instantaneamente um link para um dashboard de APM em tempo real.
• O resultado: total observabilidade do Kubernetes e insights do aplicativo sem que o usuário escreva uma única linha de YAML.

Cenário 2: transferência de segurança

Uma regra fundamental da segurança da infraestrutura é que você não pode proteger o que não pode ver. Ao realizar nosso resgate de DevOps, o agente vê uma oportunidade de melhorar a segurança do ambiente.

Com um alerta iniciado a partir de uma investigação anterior relacionada ao Elastic Observability, demonstramos como um profissional de segurança pode interagir diretamente com sua infraestrutura: primeiro, para enumerar os ativos e recursos em seu ambiente de nuvem; e, segundo, para implantar as ferramentas necessárias para garantir que o ambiente esteja seguro.

• Descoberta: o copiloto enumerou os recursos da AWS para o profissional de segurança e identificou uma lacuna crítica: uma instância do Amazon Elastic Compute Cloud (EC2) e um cluster do Amazon Elastic Kubernetes Service (EKS) com endpoints públicos sem proteção de endpoint.
• Remediação: com uma simples aprovação, o copiloto implantou Elastic Security detecção estendida e resposta (XDR) e detecção e resposta na nuvem (CDR) nos ativos vulneráveis, protegendo o ambiente em tempo real.
• Resultado: proteção dos ativos e recursos AWS implantados com segurança completa em tempo de execução.

O futuro: tudo ampliado

Este projeto prova que o Elastic Agent Builder pode ser o cérebro central para operações distribuídas. Não estamos limitados apenas à infraestrutura. Nossa tecnologia de runners pode melhorar:

• Synthetics ampliados: diagnosticando erros TLS em executores globais.
• Desenvolvimento ampliado: criando pull requests e implementando CAPTCHAs em serviços frontend.
• Operações aprimoradas: Reconfiguração automática de resolvedores de DNS durante uma interrupção.

Experimente você mesmo

Acreditamos que o futuro da IA não se resume apenas ao suporte por chat; trata-se de Infraestrutura Ampliada. Trata-se de ter um parceiro que possa implantar, consertar, Observe e Protect ao seu lado.

Confira o código e experimente você mesmo com executores distribuídos (GitHub) e o Elastic Agent Builder no Elastic Cloud Serverless hoje mesmo!

• Crie um projeto serverless no Elastic Cloud.
• Implante o código em um executor.
• Prepare o runner.
• Configure seu mcp.json.
• Execute o runner, que criará seu agente e suas ferramentas automaticamente.
• Converse com um agente que pode raciocinar, planejar e executar ações nos seus runners distribuídos!

A equipe: Alex, Bill, Gil, Graham e Norrie

Por que isso é importante

A maioria dos fluxos de trabalho analíticos típicos acaba se resumindo ao agrupamento de dados. Seja calculando a média de bytes por host, contando eventos por usuário ou agregando métricas entre dimensões, a operação principal é a mesma: mapear chaves para grupos e atualizar agregados em execução.

Em pequena escala, praticamente qualquer tabela hash razoável funciona bem. Em grande escala (centenas de milhões de documentos e milhões de grupos distintos), os detalhes começam a importar. Fatores de carregamento, estratégia de sondagem, layout da memória e comportamento do cache podem fazer a diferença entre um desempenho linear e uma série de falhas de cache.

O Elasticsearch oferece suporte a essas cargas de trabalho há anos, mas estamos sempre buscando oportunidades para modernizar os algoritmos principais. Assim, avaliamos uma abordagem mais recente inspirada nas Swiss Tables e a aplicamos à maneira como o ES|QL calcula as estatísticas.

Afinal, o que são Swiss Tables?

As Swiss Tables são uma família de tabelas de hash modernas popularizadas pelo SwissTable do Google e posteriormente adotadas na Abseil e em outras bibliotecas.

Tabelas hash tradicionais gastam muito tempo atrás de ponteiros ou carregando chaves apenas para descobrir que não correspondem. O principal recurso das Swiss Tables é a capacidade de rejeitar a maioria das sondagens usando uma pequena estrutura de matriz residente em cache, armazenada separadamente das chaves e valores, chamada de bytes de controle, para reduzir drasticamente o tráfego de memória.

Cada byte de controle representa um único slot e, em nosso caso, codifica duas coisas: se o slot está vazio e uma pequena impressão digital derivada do hash. Esses bytes de controle são dispostos de maneira contígua na memória, geralmente em grupos de 16, tornando-os ideais para processamento de instrução única e dados múltiplos (SIMD).

Em vez de sondar um slot de cada vez, as Swiss Tables analisam um bloco inteiro de controle de bytes usando instruções vetoriais. Em uma única operação, a CPU compara a impressão digital da chave de entrada com 16 slots e retira as entradas vazias. Somente os poucos candidatos que sobrevivem a esse processo rápido precisam ser carregados e comparados às chaves reais.

Esse design troca uma pequena quantidade extra de metadados por uma melhor localidade de cache e muito menos carregamentos aleatórios. À medida que a tabela cresce e as cadeias de sondagem se alongam, essas propriedades tornam-se cada vez mais valiosas.

SIMD no centro

A verdadeira estrela do espetáculo é o SIMD.

Bytes de controle não são apenas compactos, eles também são explicitamente projetados para serem processados com instruções vetoriais. Uma única comparação SIMD pode verificar 16 impressões digitais de uma vez, transformando o que normalmente seria um loop em algumas operações amplas. Por exemplo:

Na prática, isso significa:

• Menos ramificações.
• Cadeias de sondagem mais curtas.
• Menos carregamentos da memória de chave e valor.
• Utilização muito melhor das unidades de execução da CPU.

A maioria das pesquisas nunca passa da verificação do byte de controle. Quando isso acontece, o restante do trabalho é focado e previsível. Esse é exatamente o tipo de carga de trabalho que CPUs modernas fazem bem.

SIMD nos bastidores

Para os leitores que gostam de espiar os bastidores, aqui está o que acontece ao inserir uma nova chave na tabela. Usamos a Panama Vector API com vetores de 128 bits, operando assim em 16 bytes de controle em paralelo.

O trecho a seguir mostra o código gerado em um Intel Rocket Lake com AVX-512. Embora as instruções reflitam esse ambiente, o design não depende do AVX-512. As mesmas operações vetoriais de alto nível são emitidas em outras plataformas usando instruções equivalentes (por exemplo, AVX2, SSE ou NEON).

; Load 16 control bytes from the control block
vmovdqu xmm0, XMMWORD PTR [r9+r10*1+0x10]

; Broadcast the 7-bit fingerprint of the new key across the vector
vpbroadcastb xmm1, r11d

; Compare all 16 control bytes to the new fingerprint
vpcmpeqb k7, xmm0, xmm1
kmovq rbx, k7

; Check if any matches were found
test rbx, rbx
jne 

Cada instrução tem um papel claro no processo de inserção:

• vmovdqu: Carrega 16 bytes de controle consecutivos no registrador xmm0 de 128 bits.
• vpbroadcastb: Replica a impressão digital de 7 bits da nova chave em todas as faixas do registrador xmm1.
• vpcmpeqb: Compara cada byte de controle com a impressão digital transmitida, produzindo uma máscara de possíveis correspondências.
• kmovq + test: Move a máscara para um registrador de uso geral e verifica rapidamente se existe uma correspondência.

Finalmente, decidimos sondar grupos de 16 bytes de controle por vez, pois o benchmarking mostrou que a expansão para 32 ou 64 bytes com registros mais amplos não oferecia nenhum benefício mensurável de desempenho.

Integração em ES|QL

Adotar o hashing com a técnica de Swiss Tables no Elasticsearch não foi uma simples substituição. O ES|QL tem requisitos rigorosos em relação à contabilidade de memória, segurança e integração com o restante do motor de computação.

Integramos a nova tabela hash de maneira precisa com o gerenciamento de memória do Elasticsearch, incluindo o reciclador de páginas e a contabilização de mecanismos de interrupção, garantindo que as alocações permaneçam visíveis e limitadas. As agregações do Elasticsearch são armazenadas densamente e indexadas por uma ID de grupo, mantendo o layout da memória compacto e rápido para iterações, além de possibilitar certas otimizações de desempenho ao permitir acesso aleatório.

Para chaves de bytes de comprimento variável, armazenamos em cache o hash completo junto com a ID do grupo. Isso evita o recálculo de códigos hash caros durante a sondagem e melhora a localidade do cache ao manter os metadados relacionados próximos uns dos outros. Durante o rehashing, podemos confiar no hash e bytes de controle em cache sem inspecionar os próprios valores, mantendo os custos de redimensionamento baixos.

Uma simplificação importante em nossa implementação é que as entradas nunca são excluídas. Isso elimina a necessidade de lápides (marcadores para identificar slots ocupados anteriormente) e permite que os slots vazios permaneçam realmente vazios, o que melhora ainda mais o comportamento da sondagem e mantém a eficiência das varreduras dos bytes de controle.

O resultado é um design que se encaixa naturalmente no modelo de execução do Elasticsearch, preservando as características de desempenho que tornam as Swiss Tables interessantes.

Qual é o desempenho?

Em pequenas cardinalidades, as Swiss Tables apresentam desempenho aproximadamente equivalente à implementação existente. Isso é esperado: quando as tabelas são pequenas, os efeitos de cache dominam menos e há pouca sondagem para otimizar.

À medida que a cardinalidade aumenta, o cenário logo muda.

O heatmap acima mostra fatores de melhoria de tempo para diferentes tamanhos de chave (8, 32, 64 e 128 bytes) entre cardinalidades de 1.000 a 10.000.000 de grupos. À medida que a cardinalidade aumenta, o fator de melhoria aumenta constantemente, chegando a 2 a 3 vezes para distribuições uniformes.

Essa tendência é exatamente o que o design prevê. Uma maior cardinalidade leva a cadeias de sondagem mais longas em tabelas hash tradicionais, enquanto a sondagem com a técnica Swiss Tables continua resolvendo a maioria das pesquisas em blocos de bytes de controle compatíveis com SIMD.

O comportamento do cache conta a história

Para entender melhor as acelerações, executamos os mesmos benchmarks JMH sob o Linux perf e capturamos cache e estatísticas do TLB.

Em comparação com a implementação original, a versão Swiss Tables realiza cerca de 60% menos referências de cache no geral. Os carregamentos de cache no último nível caem mais de 4 vezes, e as falhas de carregamento da LLC caem mais de 6 vezes. Como as falhas de LLC costumam se traduzir diretamente em acessos à memória principal, essa redução sozinha explica grande parte da melhoria de ponta a ponta.

Mais próximo da CPU, observamos menos falhas de cache de dados L1 e quase 6 vezes menos falhas de dados TLB, indicando uma localidade espacial mais precisa e padrões de acesso à memória mais previsíveis.

Esse é o benefício prático dos bytes de controle compatíveis com SIMD. Em vez de carregar repetidamente chaves e valores de locais de memória dispersos, a maioria das sondagens é resolvida analisando uma estrutura compacta residente no cache. Menos memória acessada significa menos falhas, e menos falhas significam consultas mais rápidas.

Conclusão

Ao adotar um design de tabela hash com a técnica Swiss Tables e apostar fortemente na sondagem compatível com SIMD, alcançamos uma aceleração de 2 a 3 vezes para cargas de trabalho de estatísticas ES|QL de alta cardinalidade, além de um desempenho mais estável e previsível.

Este trabalho destaca como estruturas de dados modernas conscientes da CPU podem desbloquear ganhos substanciais, mesmo para problemas já conhecidos, como tabelas hash. Há mais espaço para explorar aqui, como especializações adicionais de tipos primitivos e uso em outros caminhos de alta cardinalidade, como joins, todos eles apenas parte do esforço mais amplo e contínuo para modernizar continuamente os internos do Elasticsearch.

Se você tiver interesse nos detalhes ou quiser acompanhar o trabalho, confira o rastreamento de progresso de pull request e meta issue no Github.

Boa sorte com o hashing!

Afinal, tudo no contexto influencia as respostas da IA. O princípio Lixo entra, lixo saí continua válido.

Neste artigo, vamos apresentar o que as memórias de curto e longo prazo significam para agentes de IA, especificamente:

• A diferença entre memória de curto e longo prazo.
• Como elas se relacionam com as técnicas de Retrieval-Augmented Generation (RAG) com bancos de dados vetoriais, como o Elasticsearch, e por que é necessário um gerenciamento cuidadoso da memória.
• Os riscos de negligenciar a memória, incluindo transbordamento de contexto e envenenamento do contexto.
• Boas práticas, como a eliminação do contexto, o resumo e a recuperação apenas do que é relevante, visam manter a memória de um agente útil e segura.
• Por fim, vamos abordar como a memória pode ser compartilhada e propagada em sistemas multiagente para permitir que agentes colaborem sem confusão usando o Elasticsearch.

Memória de curto prazo versus memória de longo prazo em agentes de IA

Memória de curto prazo em um agente de IA geralmente se refere ao contexto conversacional imediato ou estado — essencialmente, o histórico atual da conversa ou mensagens recentes na sessão ativa. Isso inclui a consulta mais recente do usuário e as trocas de mensagens recentes. É muito semelhante à informação que uma pessoa mantém em mente durante uma conversa em andamento.

Frameworks de IA frequentemente mantêm essa memória transitória como parte do estado do agente (por exemplo, usando um mecanismo de ponto de verificação para armazenar o estado da conversa, conforme abordado por este exemplo do LangGraph). A memória de curto prazo tem escopo de sessão, ou seja, existe em uma única conversa ou tarefa e é redefinida ou apagada quando a sessão termina, a menos que seja explicitamente salva em outro lugar. Um exemplo de memória de curto prazo ligada a sessões seria o chat temporário disponível no ChatGPT.

A memória de longo prazo, por outro lado, refere-se a informações que persistem ao longo de conversas ou sessões. Este é o conhecimento que um agente retém ao longo do tempo, fatos que aprendeu anteriormente, preferências do usuário ou quaisquer dados que pedimos para ele lembrar permanentemente.

A memória de longo prazo geralmente é implementada armazenando e recuperando dados de uma fonte externa, como um arquivo ou banco de dados vetorial fora do contexto imediato da janela. Diferentemente do histórico de chats de curto prazo, a memória de longo prazo não é incluída automaticamente em todas as solicitações. Em vez disso, com base em um determinado cenário, o agente deve recordá-lo ou recuperá-lo quando as ferramentas relevantes forem invocadas. Na prática, a memória de longo prazo pode incluir informações de perfil do usuário, respostas ou análises anteriores produzidas pelo agente, ou uma base de conhecimento que o agente pode consultar.

Por exemplo, se você tiver um agente de planejamento de viagens, a memória de curto prazo conterá detalhes da consulta de viagem atual (datas, destino, orçamento) e quaisquer perguntas subsequentes feitas durante o chat; enquanto a memória de longo prazo poderá armazenar as preferências gerais de viagem do usuário, itinerários anteriores e outros dados compartilhados em sessões anteriores. Quando o usuário retornar posteriormente, o agente poderá recorrer a esse histórico (por exemplo, o usuário adora praias e montanhas, tem um orçamento médio de 100.000 rúpias indianas, possui uma lista de lugares para visitar antes de morrer e prefere vivenciar história e cultura em vez de atrações voltadas para crianças), de modo que não trate o usuário como uma folha em branco a cada vez.

A memória de curto prazo (histórico de chats) fornece contexto e continuidade imediatos, enquanto a memória de longo prazo fornece um contexto mais amplo que o agente pode usar quando necessário. Os frameworks de agentes de IA mais avançados permitem ambas as coisas: mantêm o controle dos diálogos recentes para manter o contexto e oferecem mecanismos para consultar ou armazenar informações em um repositório de longo prazo. O gerenciamento da memória de curto prazo garante que ela permaneça dentro da janela de contexto, enquanto o gerenciamento da memória de longo prazo ajuda o agente a basear as respostas com base em interações e personalidades anteriores.

Memória e RAG na engenharia de contexto

Como damos a um agente de IA uma memória útil de longo prazo na prática?

Uma abordagem proeminente para a memória de longo prazo é a memória semântica, frequentemente implementada por meio de retrieval-augmented generation (RAG). Isso envolve acoplar o LLM a um armazenamento de conhecimento externo ou a um datastore habilitado por vetor, como o Elasticsearch. Quando o LLM precisa de informações além do que está no prompt ou em seu treinamento integrado, ele realiza uma recuperação semântica contra o Elasticsearch e injeta os resultados mais relevantes no prompt como contexto. Dessa forma, o contexto efetivo do modelo inclui não apenas a conversa recente (memória de curto prazo), mas também fatos pertinentes de longo prazo obtidos em tempo real. O LLM então fundamenta sua resposta tanto em seu próprio raciocínio quanto nas informações recuperadas, combinando efetivamente memória de curto prazo e memória de longo prazo para produzir uma resposta mais precisa e consciente do contexto.

O Elasticsearch pode ser usado para implementar memória de longo prazo para agentes de IA. Aqui está um exemplo de alto nível de como o contexto pode ser recuperado do Elasticsearch para memória de longo prazo.

Dessa forma, o agente "se lembra" pesquisando dados relevantes em vez de armazenar tudo em seu prompt limitado, onde isso leva a diferentes riscos.

Usar RAG com o Elasticsearch ou qualquer armazenamento vetorial oferece múltiplos benefícios:

Primeiro, ele amplia o conhecimento do modelo além do limite de treinamento. O agente pode recuperar informações atualizadas ou dados específicos do domínio que o LLM talvez não conheça. Isso é crucial para perguntas sobre eventos recentes ou tópicos especializados.

Em segundo lugar, recuperar o contexto sob demanda ajuda a reduzir alucinações, especialmente porque os LLMs não são treinados com dados proprietários ou altamente especializados relativos ao seu caso de uso específico, o que é muito provável que os exponha a alucinações. Em vez de o LLM adivinhar ou inventar novas informações, como tem sido incentivado pela avaliação, conforme destacado em um artigo recente da OpenAI (Why Language Models Hallucinate), o modelo pode ser fundamentado em referências factuais do Elasticsearch. Naturalmente, o LLM depende da confiabilidade dos dados no armazenamento vetorial para realmente evitar desinformação e os dados relevantes são recuperados de acordo com as medidas de relevância do núcleo.

Terceiro, o RAG permite que um agente trabalhe com bases de conhecimento muito maiores do que qualquer coisa que você poderia encaixar em um prompt. Em vez de inserir documentos inteiros, como longos artigos de pesquisa ou documentos de políticas, na janela de contexto e correr o risco de sobrecarga ou de informações irrelevantes contaminarem o raciocínio do modelo, o RAG se baseia em fragmentação. Documentos grandes são divididos em partes menores e semanticamente significativas, e o sistema recupera apenas os poucos trechos mais relevantes para a consulta. Dessa forma, o modelo não precisa de um contexto de um milhão de tokens para parecer conhecedor; ele só precisa de acesso aos pedaços certos de um corpus muito maior.

Vale ressaltar que, com o aumento das janelas de contexto do LLM (alguns modelos agora suportam centenas de milhares ou até milhões de tokens), surgiu um debate sobre se o RAG está "morto". Por que não enviar todos os dados para o prompt? Se você pensa da mesma forma, consulte este maravilhoso artigo de meus colegas Jeffrey Rengifo e Eduard Martin, Longer context ≠ better: Why RAG still matters. Isso evita o problema de "lixo entra, lixo sai": o LLM fica focado nos poucos pedaços que importam, em vez de passar por meio de ruído.

Dito isso, integrar o Elasticsearch ou qualquer armazenamento vetorial em uma arquitetura de agente de IA fornece memória de longo prazo. O agente armazena conhecimento externamente e o recolhe como contexto de memória quando necessário. Isso poderia ser implementado como uma arquitetura, onde, após cada consulta do usuário, o agente realiza uma busca no Elasticsearch por informações relevantes e então adiciona os principais resultados ao prompt antes de chamar o LLM. A resposta também pode ser salva de volta no armazenamento de longo prazo se contiver informações novas úteis (criando um ciclo de retroalimentação de aprendizado). Ao usar essa memória baseada em recuperação, o agente permanece informado e atualizado, sem precisar condensar tudo o que sabe em cada prompt, mesmo que a janela de contexto suporte um milhão de tokens. Essa técnica é uma pedra angular da engenharia de contexto, combinando os pontos fortes da recuperação de informação e da IA generativa.

Aqui está um exemplo de um estado gerenciado de conversa em memória usando o sistema de ponto de verificação do LangGraph para memória de curto prazo durante a sessão. (Consulte nosso app de engenharia de contexto de suporte).

# Initialize chat memory (Note: This is in-memory only, not persistent)
memory = MemorySaver()

# Create a LangGraph agent
langgraph_agent = create_react_agent(model=llm, tools=tools, checkpointer=memory)

...
...
# Only process and display checkpoints if verbose mode is enabled
if args.verbose:
    # List all checkpoints that match a given configuration
    checkpoints = memory.list({"configurable": {"thread_id": "1"}})
    # Process the checkpoints
    process_checkpoints(checkpoints)

Veja como ele armazena pontos de verificação:

Checkpoint:
Timestamp: 2025-12-30T09:19:41.691087+00:00
Checkpoint ID: 1f0e560a-c2fa-69ec-8001-14ee5373f9cf
User: Hi I'm Som, how are you? (Message ID: ad0a8415-5392-4a58-85ad-84154875bbf2)
Agent: Hi Som! I'm doing well, thank you! How about you? (Message ID: 
56d31efb-14e3-4148-806e-24a839799ece)
Agent:  (Message ID: lc_run--019b6e8e-553f-7b52-8796-a8b1fbb206a4-0)

Checkpoint:
Timestamp: 2025-12-30T09:19:40.350507+00:00
Checkpoint ID: 1f0e560a-b631-6a08-8000-7796d108109a
User: Hi I'm Som, how are you? (Message ID: ad0a8415-5392-4a58-85ad-84154875bbf2)
Agent: Hi Som! I'm doing well, thank you! How about you? (Message ID: 
56d31efb-14e3-4148-806e-24a839799ece)

Checkpoint:
Timestamp: 2025-12-30T09:19:40.349027+00:00
Checkpoint ID: 1f0e560a-b62e-6010-bfff-cbebe1d865f6

Para a memória de longo prazo, veja como realizamos a busca semântica no Elasticsearch para recuperar conversas anteriores relevantes usando embeddings de vetor após resumir e a indexar pontos de verificação no Elasticsearch.

Functions: 
retrieve_from_elasticsearch() 

# Enhanced Elasticsearch retrieval with rank_window and verbose display
def retrieve_from_elasticsearch(query: str, k: int = 5, rank_window: int = None) -> tuple[List[Dict[str, Any]], str]:
    """
    Retrieve context from Elasticsearch with score-based ranking
    
    Args:
        query: Search query
        k: Number of results to return
        rank_window: Number of candidates to retrieve before ranking (default: args.rank_window)
        
    Returns:
        Tuple of (retrieved_documents, formatted_context_string)
    """
    if not es_client or not es_index_name:
        return [], "Elasticsearch is not available. Cannot search long-term memory."
    
    if rank_window is None:
        rank_window = args.rank_window
    
    try:
        # Check if index exists and has documents
        if not es_client.indices.exists(index=es_index_name):
            return [], "No previous conversations stored in long-term memory yet."
        
        # Get document count
        try:
            doc_count = es_client.count(index=es_index_name)["count"]
            if doc_count == 0:
                return [], "Long-term memory is empty. No previous conversations to search."
        except Exception as e:
            return [], f"Error checking memory: {str(e)}"
        
        # Generate embedding for the query
        try:
            query_embedding = embeddings.embed_query(query)
        except Exception as e:
            return [], f"Error generating embedding: {str(e)}"
        
        # Perform semantic search using kNN with rank_window
        try:
            search_body = {
                "knn": {
                    "field": "vector",
                    "query_vector": query_embedding,
                    "k": k,
                    "num_candidates": rank_window  # Retrieve more candidates, then rank top k
                },
                "_source": ["text", "content", "message_type", "timestamp", "thread_id"],
                "size": k
            }
            
            response = es_client.search(index=es_index_name, body=search_body)
            
            if not response.get("hits") or len(response["hits"]["hits"]) == 0:
                return [], "No relevant previous conversations found in long-term memory."
            
            # Extract documents with scores
            retrieved_docs = []
            for hit in response["hits"]["hits"]:
                source = hit["_source"]
                score = hit["_score"]
                retrieved_docs.append({
                    "content": source.get("content", source.get("text", "")),
                    "message_type": source.get("message_type", "unknown"),
                    "timestamp": source.get("timestamp", "unknown"),
                    "thread_id": source.get("thread_id", "unknown"),
                    "score": score
                })
            
            # Format context string
            context_parts = []
            for i, doc in enumerate(retrieved_docs, 1):
                context_parts.append(doc["content"])
            
            context_string = "\n\n".join(context_parts)
            
            # Verbose display
            if args.verbose:
                rich.print(f"\n[bold yellow]🔍 RETRIEVAL ANALYSIS[/bold yellow]")
                rich.print("="*80)
                rich.print(f"[blue]Query:[/blue] {query}")
                rich.print(f"[blue]Retrieved:[/blue] {len(retrieved_docs)} documents (from {rank_window} candidates)")
                rich.print(f"[blue]Total context length:[/blue] {len(context_string)} characters\n")
                
                for i, doc in enumerate(retrieved_docs, 1):
                    rich.print(f"[cyan]📄 Document {i} | Score: {doc['score']:.4f} | Type: {doc['message_type']}[/cyan]")
                    rich.print(f"[cyan]   Timestamp: {doc['timestamp']} | Thread: {doc['thread_id']}[/cyan]")
                    content_preview = doc['content'][:200] + "..." if len(doc['content']) > 200 else doc['content']
                    rich.print(f"[cyan]   Content: {content_preview}[/cyan]")
                    rich.print("-" * 80)
            
            return retrieved_docs, context_string
            
        except Exception as e:
            return [], f"Error searching memory: {str(e)}"
            
    except Exception as e:
        return [], f"Error accessing long-term memory: {str(e)}"

Agora que exploramos como a memória de curto prazo e a memória de longo prazo são indexadas e buscadas usando os pontos de verificação do LangGraph no Elasticsearch, vamos tirar um tempo para entender por que a indexação e o despejo das conversas completas podem ser arriscados.

Riscos de não gerenciar a memória de contexto

Como estamos falando muito sobre engenharia de contexto, junto com memória de curto e longo prazo, vamos entender o que acontece se não gerenciarmos bem a memória e o contexto de um agente.

Infelizmente, muitas coisas podem dar errado quando o contexto de uma IA se torna extremamente longo ou contém informações erradas. À medida que as janelas de contexto aumentam, surgem novos modos de falha, como:

• Envenenamento de contexto
• Distração contextual
• Confusão de contexto
• Conflito de contexto
• Vazamento de contexto e conflitos de conhecimento
• Alucinações e desinformação

Vamos analisar esses problemas e outros riscos que surgem do gerenciamento inadequado de contexto:

Envenenamento de contexto

O envenenamento do contexto refere-se a quando informações incorretas ou prejudiciais acabam no contexto e "envenenam" as saídas subsequentes do modelo. Um exemplo comum é uma alucinação do modelo que é tratada como fato e inserida no histórico da conversa. O modelo pode então construir sobre esse erro em respostas posteriores, agravando o erro. Em ciclos iterativos de agentes, uma vez que uma informação falsa entra no contexto compartilhado (por exemplo, em um resumo das notas de trabalho do agente), ela pode ser reforçada repetidamente.

Pesquisadores da DeepMind, no lançamento do relatório Gemini 2.5 (TL;DR, veja aqui), observaram o seguinte em um agente que jogava Pokémon: se o agente alucinasse um estado incorreto de jogo e isso fosse registrado em seu contexto (a memória de objetivos), o agente criaria estratégias sem sentido em torno de um objetivo impossível e ficaria preso. Em outras palavras, uma memória envenenada pode levar o agente pelo caminho errado indefinidamente.

O envenenamento de contexto pode acontecer inocentemente (por engano) ou até mesmo de forma mal-intencionada, por exemplo, por meio de ataques de injeção de prompt, onde um usuário ou terceiro introduz uma instrução oculta ou um fato falso que o agente então lembra e segue.

Contramedidas recomendadas:

Com base nos insights de Wiz, Zerlo e Anthropic, as contramedidas para envenenamento de contexto se concentram em evitar que informações ruins ou enganosas entrem no prompt, na janela de contexto ou no pipeline de recuperação de um LLM. Os principais passos incluem:

• Verifique o contexto constantemente: monitore a conversa ou o texto recuperado para qualquer coisa suspeita ou prejudicial, não apenas o prompt inicial.
• Use fontes confiáveis: pontue ou rotule documentos com base na credibilidade para que o sistema prefira informações confiáveis e ignore dados com pontuação baixa.
• Identifique dados incomuns: use ferramentas que detectem conteúdo estranho, fora de lugar ou manipulado, e remova-o antes que o modelo os utilize.
• Filtre entradas e saídas: adicione proteções de segurança para que textos prejudiciais ou enganosos não possam entrar facilmente no sistema ou ser repetidos pelo modelo.
• Mantenha o modelo atualizado com dados limpos: atualize regularmente o sistema com informações verificadas para combater qualquer dado errado que tenha escapado.
• Com supervisão humana: peça para as pessoas revisarem as saídas importantes ou compará-las com fontes conhecidas e confiáveis.

Hábitos simples do usuário também ajudam, como redefinir chats longos, compartilhar apenas informações relevantes, dividir tarefas complexas em etapas menores e manter anotações claras fora do modelo.

Juntas, essas medidas criam uma defesa em camadas que protege os LLMs contra envenenamento do contexto e mantém as saídas precisas e confiáveis.

Sem contramedidas mencionadas aqui, um agente pode lembrar-se de instruções, como ignorar diretrizes anteriores ou fatos triviais inseridos por um invasor, levando a saídas prejudiciais.

Distração contextual

A distração de contexto ocorre quando um contexto se alonga tanto que o modelo foca demais no contexto, negligenciando o que aprendeu durante o treinamento. Em casos extremos, isso se assemelha ao esquecimento catastrófico; ou seja, o modelo efetivamente "esquece" seu conhecimento subjacente e fica excessivamente apegado à informação que lhe é apresentada. Estudos anteriores mostraram que LLMs frequentemente perdem o foco quando o prompt é extremamente longo.

O agente Gemini 2.5, por exemplo, suportava uma janela de um milhão de tokens, mas quando seu contexto crescia além de um certo ponto (na ordem de 100.000 tokens em um experimento), ele começava a se fixar em repetir suas ações passadas em vez de apresentar novas soluções. De certa forma, o agente tornou-se prisioneiro de sua extensa história. Ele continuava observando seu longo log de movimentos anteriores (o contexto) e imitando-os, em vez de usar seu conhecimento de treinamento subjacente para criar estratégias novas e inovadoras.

Isso é contraproducente. Queremos que o modelo use o contexto relevante para ajudar no raciocínio, não para sobrepor sua capacidade de pensar. Notavelmente, mesmo modelos com janelas enormes exibem essa deterioração de contexto: seu desempenho se degrada de forma não uniforme à medida que mais tokens são adicionados. Parece haver um orçamento de atenção. Como humanos com memória de trabalho limitada, um LLM tem uma capacidade finita para atender a tokens, e à medida que esse orçamento é esticado, sua precisão e foco caem.

Como mitigação, você pode evitar distração do contexto usando fragmentação, engenharia das informações corretas, resumo regular do contexto e técnicas de avaliação e monitoramento para medir a precisão da resposta usando pontuação.

Esses métodos mantêm o modelo baseado no contexto relevante e em seu treinamento subjacente, reduzindo o risco de distração e melhorando a qualidade geral do raciocínio.

Confusão de contexto

A confusão de contexto ocorre quando o conteúdo supérfluo no contexto é usado pelo modelo para gerar uma resposta de baixa qualidade. Um ótimo exemplo é fornecer a um agente um grande conjunto de ferramentas ou definições de API que ele pode usar. Se muitas dessas ferramentas não estiverem relacionadas à tarefa atual, o modelo ainda pode tentar usá-las de forma inadequada, simplesmente porque elas estão presentes no contexto. Experimentos descobriram que fornecer mais ferramentas ou documentos pode prejudicar o desempenho se não forem todos necessários. O agente começa a cometer erros, como chamar a função errada ou fazer referência a um texto irrelevante.

Em um caso, um pequeno modelo Llama 3.1 8B falhou em uma tarefa ao receber 46 ferramentas para considerar, mas teve sucesso quando recebeu apenas 19 ferramentas. As ferramentas extras criaram confusão, mesmo que o contexto estivesse dentro dos limites de duração. A questão subjacente é que qualquer informação no prompt será atendida pelo modelo. Se não souber ignorar algo, esse algo pode influenciar sua saída de maneiras indesejadas. Pedaços irrelevantes podem “roubar” parte da atenção do modelo e desviá-lo (por exemplo, um documento irrelevante pode fazer com que o agente responda a uma pergunta diferente da feita). A confusão de contexto frequentemente se manifesta como o modelo produzindo uma resposta de baixa qualidade que integra contextos não relacionados. Consulte o trabalho de pesquisa: Menos é mais: otimizando a chamada de funções para execução LLM em dispositivos de borda.

Isso nos lembra que mais contexto nem sempre é melhor, especialmente se não for selecionado para ser relevante.

Conflito de contexto

O conflito de contexto ocorre quando partes do contexto se contradizem, causando inconsistências internas que comprometem o raciocínio do modelo. Um conflito pode acontecer se o agente acumular várias informações que estão em conflito.

Por exemplo, imagine um agente que obteve dados de duas fontes: uma diz que o voo A parte às 17h, e a outra diz que o voo A parte às 18h. Se ambos os fatos estiverem presentes no contexto, o modelo inadequado não terá como saber qual está correto; poderá ficar confuso ou produzir uma resposta incorreta ou não similar.

O conflito de contexto também ocorre com frequência em conversas com várias interações, em que as tentativas anteriores de resposta do modelo ainda permanecem no contexto junto com informações refinadas posteriormente.

Um estudo realizado pela Microsoft e pela Salesforce mostra que, ao dividir uma consulta complexa em várias interações com o chatbot (adicionando detalhes gradualmente), a precisão final cai significativamente em comparação com a apresentação de todos os detalhes em uma única solicitação. Por quê? Porque as primeiras interações contêm respostas intermediárias parciais ou incorretas do modelo, e essas permanecem no contexto. Quando o modelo tenta responder posteriormente com todas as informações, sua memória ainda inclui as tentativas erradas, que entram em conflito com as informações corrigidas e o desviam do caminho. Basicamente, o contexto da conversa entra em conflito consigo mesmo. O modelo pode, sem querer, usar um contexto desatualizado (de uma interação anterior) que não se aplica depois que novas informações são adicionadas.

Em sistemas de agentes, o choque de contexto é especialmente perigoso, pois um agente pode combinar saídas de diferentes ferramentas ou subagentes. Se essas saídas discordarem, o contexto agregado será inconsistente. O agente pode, então, ficar travado ou produzir resultados sem sentido ao tentar conciliar as contradições. Evitar conflitos de contexto envolve garantir que o contexto seja novo e consistente, por exemplo, limpar ou atualizar qualquer informação desatualizada e não misturar fontes que não tenham sido verificadas quanto à consistência.

Vazamento de contexto e conflitos de conhecimento

Em sistemas onde múltiplos agentes ou usuários compartilham um estoque de memória, há o risco de informações transbordarem entre os contextos.

Por exemplo, se os dados de embeddings de dois usuários diferentes residirem no mesmo banco de dados vetorial sem o devido controle de acesso, um agente que responde à consulta do Usuário A pode, acidentalmente, recuperar parte da memória do Usuário B. Esse vazamento entre contextos pode expor informações privadas ou apenas criar confusão nas respostas.

De acordo com o OWASP Top 10 for LLM Applications, os bancos de dados vetoriais multilocatários devem se proteger contra esse tipo de vazamento:

De acordo com LLM08:2025 — Fraquezas em Vetores e Embeddings, um dos riscos comuns é o vazamento de contexto:

Em ambientes multi-inquilinos onde várias classes de usuários ou aplicativos compartilham o mesmo banco de dados vetorial, existe o risco de vazamento de contexto entre usuários ou consultas. Erros de conflito de conhecimento na federação de dados podem ocorrer quando dados de múltiplas fontes se contradizem. Isso também pode ocorrer quando um LLM não consegue substituir o conhecimento antigo que aprendeu durante o treinamento pelos novos dados do Retrieval Augmentation.

Outro aspecto é que um LLM pode ter dificuldade em substituir seu conhecimento integrado por novas informações da memória. Se o modelo foi treinado em algum fato e o contexto recuperado diz o oposto, o modelo pode ficar confuso sobre qual confiar. Sem um design adequado, o agente pode misturar contextos ou não conseguir atualizar o conhecimento antigo com novas evidências, levando a respostas desatualizadas ou incorretas.

Alucinações e desinformação

Embora a alucinação (o LLM inventando informações plausíveis, mas falsas) seja um problema conhecido, mesmo sem contextos longos, o gerenciamento inadequado da memória pode amplificá-lo. Você pode ter que se preocupar com o fato de que o LLM não está preparado para isso.

Se faltar um fato crucial na memória do agente, o modelo pode simplesmente preencher a lacuna com um palpite e, se esse palpite entrar no contexto (envenenando-o), o erro persistirá.

O relatório de segurança OWASP LLM (LLM09:2025 — Desinformação) destaca a desinformação como uma vulnerabilidade central: os modelos de aprendizagem de linguagem (LLMs) podem produzir respostas confiantes, porém fabricadas, e os usuários podem confiar excessivamente nelas. Um agente com uma memória de longo prazo ruim ou desatualizada pode citar com segurança algo que era verdadeiro no ano passado, mas é falso agora, a menos que sua memória seja mantida atualizada.

A dependência excessiva da saída da IA (seja pelo usuário ou pelo próprio agente em um loop) pode piorar isso. Se ninguém nunca conferir as informações na memória, o agente pode acumular falsidades. É por isso que o RAG é frequentemente usado para reduzir alucinações: ao recuperar uma fonte autoritativa, o modelo não precisa inventar fatos. Mas se sua recuperação extrair o documento errado (digamos, um que contenha informações erradas) ou se uma alucinação precoce não for eliminada, o sistema poderá propagar essa desinformação por meio de suas ações.

O resultado final: deixar de gerenciar a memória pode levar a saídas incorretas e enganosas, o que pode ser prejudicial, especialmente se os riscos forem altos (por exemplo, conselhos ruins em um domínio financeiro ou médico). Um agente precisa de mecanismos para verificar ou corrigir seu conteúdo de memória, não apenas confiar incondicionalmente em qualquer coisa que esteja no contexto.

Em resumo, dar a um agente de IA uma memória infinitamente longa ou despejar todas as coisas possíveis em seu contexto não é uma receita para o sucesso.

Práticas recomendadas para o gerenciamento de memória em aplicações LLM

Para evitar as armadilhas acima, os desenvolvedores e pesquisadores criaram uma série de práticas recomendadas para gerenciar o contexto e a memória nos sistemas de IA. Essas práticas visam manter o contexto de trabalho da IA enxuto, relevante e atualizado. Aqui estão algumas das principais estratégias, além de exemplos de como elas ajudam.

RAG: use contexto direcionado

Grande parte do conceito RAG já foi abordada na seção anterior, portanto, este texto serve como um conjunto conciso de lembretes práticos:

• Use recuperação direcionada, não carregamento em massa: recupere apenas os trechos mais relevantes em vez de enviar documentos inteiros ou históricos completos de conversas para o prompt.
• Considere o RAG como uma recuperação de memória sob demanda: busque o contexto apenas quando necessário, em vez de carregar tudo adiante entre as interações.
• Prefira estratégias de recuperação com base na relevância: abordagens como busca semântica top k, fusão de classificação recíproca ou filtragem de carga de ferramentas ajudam a reduzir o ruído e melhorar o aterramento.
• Janelas de contexto maiores não eliminam a necessidade do RAG: dois parágrafos altamente relevantes quase sempre são mais eficazes do que 20 páginas vagamente relacionadas.

Dito isso, o RAG não se trata de adicionar mais contexto; trata-se de adicionar o contexto certo.

Configuração de ferramentas

O carregamento de ferramentas consiste em fornecer a um modelo apenas as ferramentas de que ele realmente precisa para uma tarefa. O termo vem de jogos: você escolhe um carregamento que se adequa à situação. Muitas ferramentas atrasam você; as erradas causam falhas. LLMs se comportam da mesma forma, segundo o artigo Menos é mais. Depois que você passa por ~30 ferramentas, as descrições começam a se sobrepor e o modelo fica confuso. Depois de ~100 ferramentas, o fracasso é quase garantido. Isso não é um problema de janela de contexto, é confusão de contexto.

Uma solução simples e eficaz é o RAG-MCP. Em vez de inserir todas as ferramentas no prompt, as descrições das ferramentas são armazenadas em um banco de dados vetorial e somente as mais relevantes são recuperadas por solicitação. Na prática, isso mantém o carregamento pequeno e focado, encurta drasticamente os prompts e pode melhorar a precisão da seleção de ferramentas em até 3 vezes.

Modelos menores batem nessa barreira ainda mais cedo. A pesquisa mostra que um modelo 8B falha com dezenas de ferramentas, mas tem sucesso assim que o equipamento é cortado. Selecionar ferramentas dinamicamente, às vezes primeiro com um LLM, raciocinar sobre o que ele acha que precisa, pode aumentar o desempenho em 44%, além de reduzir o consumo de energia e a latência. A conclusão é que a maioria dos agentes precisa apenas de algumas ferramentas, mas à medida que seu sistema cresce, o carregamento de ferramentas e o RAG-MCP se tornam decisões de design de primeira ordem.

Eliminação de contexto: limite o tempo do histórico de chat

Se uma conversa continuar por várias interações, o histórico de chat acumulado pode ficar muito extenso, causando um excesso de contexto ou distraindo demais o modelo.

Aparar significa remover ou encurtar programaticamente as partes menos importantes do diálogo à medida que ele cresce. Uma forma simples é eliminar as interações mais antigas da conversa quando você atingir um determinado limite, mantendo apenas as N mensagens mais recentes. Uma eliminação mais sofisticada pode remover digressões irrelevantes ou instruções anteriores que não são mais necessárias. O objetivo é manter a janela de contexto desobstruída de notícias antigas.

Por exemplo, se o agente resolveu um subproblema há 10 interações e nós seguimos em frente desde então, podemos excluir essa parte do histórico do contexto (assumindo que não será mais necessário). Muitas implementações baseadas em chat fazem isso: elas mantêm uma janela móvel de mensagens recentes.

Aparar pode ser tão simples quanto "esquecer" as partes mais iniciais de uma conversa depois que elas foram resumidas ou consideradas irrelevantes. Ao fazer isso, reduzimos o risco de erros de excesso de contexto e também diminuímos a distração do contexto, para que o modelo não veja e se distraia com conteúdo antigo ou fora do tema. Essa abordagem é muito parecida com como os humanos podem não lembrar cada palavra de uma conversa de uma hora, mas manterão os destaques.

Se você está confuso sobre a eliminação de contexto, como destacado pelo autor Drew Breunig aqui, o uso do modelo Provence (`naver/provence-reranker-debertav3-v1`), um eliminador de contexto leve (1,75 GB), eficiente e preciso para resposta a perguntas, pode fazer a diferença. Ele pode reduzir documentos grandes apenas para o texto mais relevante para uma determinada consulta. Você pode chamá-lo em intervalos específicos.

Veja como invocamos o modelo 'provence-reranker' em nosso código para eliminar o contexto:

# Context pruning with Provence
def prune_with_provence(query: str, context: str, threshold: Optional[float] = None) -> str:
    """
    Prune context using Provence reranker model
    
    Args:
        query: User's query/question
        context: Original context to prune
        threshold: Relevance threshold (0-1) for Provence reranker.
                   If None, uses args.pruning_threshold.
                   0.1 = conservative (recommended, no performance drop)
                   0.3-0.5 = moderate to aggressive pruning
    
    Returns:
        Pruned context with only relevant sentences
    """
    if provence_model is None:
        return context
    
    if threshold is None:
        threshold = args.pruning_threshold
    
    try:
        # Use Provence's process method
        provence_output = provence_model.process(
            question=query,
            context=context,
            threshold=threshold,
            always_select_title=False,
            enable_warnings=False
        )
        
        # Extract pruned context from output
        pruned_context = provence_output.get('pruned_context', context)
        reranking_score = provence_output.get('reranking_score', 0.0)
        
        # Log statistics
        original_length = len(context)
        pruned_length = len(pruned_context)
        reduction_pct = ((original_length - pruned_length) / original_length * 100) if original_length > 0 else 0
        
        if args.verbose:
            rich.print(f"[cyan]📊 Pruning stats: {pruned_length}/{original_length} chars ({reduction_pct:.1f}% reduction, threshold={threshold:.2f}, rerank_score={reranking_score:.3f})[/cyan]")
        
        return pruned_context if pruned_context else context
        
    except Exception as e:
        rich.print(f"[yellow]⚠️ Error in Provence pruning: {str(e)}[/yellow]")
        rich.print(f"[yellow]⚠️ Falling back to original context[/yellow]")
        return context

Usamos o modelo Provence reranker (`naver/provence-reranker-debertav3-v1`) para pontuar a relevância da frase. A filtragem baseada em limiar mantém as sentenças acima do limiar de relevância. Além disso, introduzimos um mecanismo de fallback, no qual retornamos ao contexto original se a eliminação falhar. Por fim, o logging de estatísticas acompanha a porcentagem de redução em modo detalhado.

Resumo do contexto: condense informações antigas em vez de descartá-las completamente

O resumo é um complemento para redução. Quando a história ou a base de conhecimento se tornar muito grande, você pode usar o LLM para gerar um breve resumo dos pontos importantes e usar esse resumo no lugar do conteúdo completo daqui para frente, como fizemos no código acima.

Por exemplo, se um assistente de IA tiver tido uma conversa de 50 interações, em vez de enviar todas as 50 interações para o modelo na interação 51 (o que provavelmente não caberia), o sistema poderia pegar as interações de 1 a 40, fazer com que o modelo as resumisse em um parágrafo e, em seguida, fornecer apenas esse resumo mais as 10 últimas interações na próxima solicitação. Dessa forma, o modelo ainda sabe o que foi discutido sem precisar de todos os detalhes. Os primeiros usuários de chatbots faziam isso manualmente perguntando: "Você pode resumir o que discutimos até agora?" e então continuando em uma nova sessão com o resumo. Agora isso pode ser automatizado. O resumo não apenas economiza espaço na janela de contexto, mas também pode reduzir a confusão/distração do contexto ao eliminar detalhes extras e reter apenas os fatos mais importantes.

Veja como usamos modelos OpenAI (você pode usar qualquer LLMs) para condensar o contexto preservando todas as informações relevantes, eliminando redundância e duplicação.

# Context summarization
def summarize_context(query: str, context: str) -> str:
    """
    Summarize context using LLM to reduce duplication and focus on relevant information
    
    Args:
        query: User's query/question
        context: Context to summarize
        
    Returns:
        Summarized context
    """
    try:
        summary_prompt = f"""You are an expert at summarizing conversation context.

Your task: Analyze the provided conversation context and produce a condensed summary that fully answers or supports the user's specific question.

The summary must:
1. Preserve every fact, detail, and information that directly relates to the question
2. Eliminate redundancy and duplicate information
3. Maintain chronological flow when relevant
4. Focus on information that helps answer: "{query}"

Context to summarize:
{context}

Provide a concise summary that preserves all relevant information:"""

        summary = llm.invoke(summary_prompt).content
        
        if args.verbose:
            original_length = len(context)
            summary_length = len(summary)
            reduction_pct = ((original_length - summary_length) / original_length * 100) if original_length > 0 else 0
            rich.print(f"[cyan]📝 Summarization stats: {summary_length}/{original_length} chars ({reduction_pct:.1f}% reduction)[/cyan]")
        
        return summary
        
    except Exception as e:
        rich.print(f"[yellow]⚠️ Error in context summarization: {str(e)}[/yellow]")
        rich.print(f"[yellow]⚠️ Falling back to original context[/yellow]")
        return context

É importante ressaltar que, quando o contexto é resumido, o modelo tem menos probabilidade de ser sobrecarregado por detalhes triviais ou erros passados (presumindo que o resumo seja preciso).

No entanto, o resumo deve ser feito com cuidado. Um resumo ruim pode omitir um detalhe crucial ou até mesmo introduzir um erro. É basicamente mais um prompt para o modelo ("resuma isso"), então ele pode alucinar ou perder nuances. A melhor prática é resumir de forma incremental e talvez manter alguns fatos canônicos sem resumo.

Ainda assim, tem se mostrado muito útil. No cenário do agente Gemini, resumir o contexto a cada ~100k tokens era uma forma de combater a tendência do modelo de se repetir. O resumo funciona como uma memória comprimida da conversa ou dos dados. Como desenvolvedores, podemos implementar isso fazendo com que um agente chame periodicamente uma função de resumo (talvez um LLM menor ou uma rotina dedicada) no histórico de conversas ou em um documento longo. O resumo resultante substitui o conteúdo original no prompt. Essa tática é amplamente usada para manter os contextos dentro de limites e destilar as informações.

Quarentena de contexto: isole contextos sempre que possível

Isso é mais relevante em sistemas de agentes complexos ou fluxos de trabalho de múltiplas etapas. A ideia da segmentação de contexto é dividir uma grande tarefa em tarefas menores e isoladas, cada uma com seu próprio contexto, de modo que você nunca acumule um contexto enorme que contenha tudo. Cada subagente ou subtarefa trabalha em uma parte do problema com um contexto focado e, em seguida, um agente, supervisor ou coordenador de nível superior integra os resultados.

A estratégia de pesquisa da Anthropic utiliza múltiplos subagentes, cada um investigando um aspecto diferente de uma questão, com suas próprias janelas de contexto, e um agente líder que lê os resultados sintetizados desses subagentes. Essa abordagem paralela e modular significa que nenhuma janela de contexto única fica excessivamente inchada. Também reduz a chance de mistura de informações irrelevantes, cada tópico permanece no tópico (sem confusão de contexto) e não carrega bagagem desnecessária ao responder sua subpergunta específica. De certa forma, é como seguir fios de pensamento separados que só compartilham seus resultados, não todo o processo de pensamento.

Em sistemas multiagente, essa abordagem é essencial. Se o Agente A estiver lidando com a tarefa A e o Agente B estiver lidando com a tarefa B, não há motivo para que um dos agentes consuma o contexto completo do outro, a menos que seja realmente necessário. Em vez disso, os agentes podem trocar apenas as informações necessárias. Por exemplo, o Agente A pode passar um resumo consolidado de suas descobertas para o Agente B por meio de um agente supervisor, enquanto cada subagente mantém seu próprio thread de contexto dedicado. Essa configuração não exige supervisão; ela depende de um agente supervisor com ferramentas habilitadas e compartilhamento de contexto mínimo e controlado.

No entanto, projetar seu sistema de modo que agentes ou ferramentas operem com a sobreposição mínima necessária de contexto pode aumentar muito a clareza e o desempenho. Pense nisso como microsserviços para IA, cada componente lida com seu contexto e você passa mensagens entre eles de forma controlada, em vez de um contexto monolítico. Essas práticas recomendadas são frequentemente usadas em combinação. Além disso, isso dá a você a flexibilidade de cortar histórico trivial, resumir mensagens ou conversas antigas importantes, transferir os logs detalhados para o Elasticsearch para contexto de longo prazo e usar a recuperação para trazer de volta qualquer coisa relevante quando necessário.

Como mencionado aqui, o princípio orientador é que o contexto é um recurso limitado e precioso. Você quer que cada token do prompt ganhe seu valor, ou seja, ele deve contribuir para a qualidade da saída. Se algo na memória não está fazendo sua parte (ou pior, causando confusão ativamente), então deve ser eliminado, resumido ou mantido fora.

Como desenvolvedores, agora podemos programar o contexto da mesma forma que programamos o código, decidindo quais informações incluir, como formatá-las e quando omiti-las ou atualizá-las. Seguindo essas práticas, podemos fornecer aos agentes LLM o contexto necessário para executar tarefas sem incorrer nas falhas descritas anteriormente. O resultado são agentes que lembram do que deveriam, esquecem o que não precisam e recuperam o que precisam a tempo.

Conclusão

Memória não é algo que você adiciona a um agente; é algo que você projeta. A memória de curto prazo é o bloco de trabalho do agente, e a memória de longo prazo é seu armazenamento de conhecimento duradouro. O RAG serve de ponte entre os dois, transformando um armazenamento de dados passivo, como o Elasticsearch, em um mecanismo de recuperação ativo que pode ancorar as saídas e manter o agente atualizado.

Mas a memória é uma faca de dois gumes. No momento em que você deixa o contexto crescer sem controle, você gera envenenamento, distração, confusão e conflitos e, em sistemas compartilhados, até mesmo vazamento de dados. Por isso, o trabalho mais importante com a memória não é "armazenar mais", mas sim "selecionar melhor": recuperar seletivamente, eliminar agressivamente, resumir cuidadosamente e evitar misturar contextos não relacionados, a menos que a tarefa realmente o exija.

Na prática, uma boa engenharia de contexto se assemelha a um bom projeto de sistemas: contextos menores e suficientes, interfaces controladas entre os componentes e uma clara separação entre o estado bruto e o estado refinado que você realmente deseja que o modelo veja. Se feito corretamente, você não acaba com um agente que lembra de tudo — você acaba com um agente que lembra das coisas certas, na hora certa, pelo motivo certo.

Concluímos um grande upgrade na infraestrutura de todos os projetos Elastic Cloud Serverless executados na AWS, migrando para hardware mais novo e mais rápido. Essa mudança foi implementada automaticamente em todos os projetos sem servidor. Ele oferece maior taxa de transferência e menor latência em projetos sem servidor com Elasticsearch, Elastic Observability e Elastic Security na AWS.

Principais benefícios de desempenho para desenvolvedores

A nova infraestrutura de hardware da AWS sustenta tudo o que você faz com o Elastic Cloud Serverless, traduzindo-se em benefícios tangíveis para a velocidade e a capacidade de resposta das suas aplicações.

Latência reduzida nas consultas… aumento no rendimento

O hardware aprimorado aumenta drasticamente a velocidade dos recursos de computação, o que significa que suas consultas de busca são processadas mais rápido do que nunca.

• Busca e busca vetorial: seja executando consultas de texto completo tradicionais ou usando a busca vetorial de ponta para suas aplicações de IA generativa e retrieval-augmented generation (RAG), você verá uma redução significativa na latência. O benchmarking interno mostrou uma redução média de 35% na latência de busca.
• Indexação mais rápida: as taxas de ingestão de dados são otimizadas, permitindo que você indexe volumes massivos de dados e documentos complexos com maior taxa de throughput. Isso é crucial para aplicações que exigem visibilidade de dados em quase tempo real. Benchmarking interno mostrou um aumento médio de 26% na taxa de throughput de indexação.

Desempenho consistente sob carga

O Elastic Cloud Serverless foi projetado para escalar automaticamente de forma dinâmica em tempo real para atender à demanda, minimizando a latência, independentemente da sua carga de trabalho. Com esse upgrade no hardware, esse redimensionamento agora é mais eficiente e responsivo.

• Lidando com picos com facilidade: seja enfrentando um aumento repentino no tráfego de usuários ou uma ingestão massiva de dados em lote, a nova infraestrutura garante que seus recursos de busca e indexação sejam redimensionados de forma mais eficiente para manter uma latência consistentemente baixa.
• Desacoplamento otimizado de computação e armazenamento: a arquitetura sem servidor separa computação e armazenamento, permitindo que cargas de trabalho sejam redimensionadas de forma independente para desempenho ideal e eficiência de custos. O hardware mais rápido aprimora a camada de computação, maximizando a eficiência desse design desacoplado.

Por trás do capô: resultados internos de benchmarking

Para quantificar o impacto do nosso upgrade de infraestrutura da AWS, a equipe de engenharia da Elastic realizou um benchmarking interno abrangente em relação a uma variedade de cargas de trabalho sem servidor. Essas cargas de trabalho forneceram evidências empíricas de melhorias no desempenho que você pode esperar em todas as suas aplicações, independentemente do seu caso de uso.

A abordagem de benchmarking

Concentramos nossos testes nas principais métricas que afetam diretamente a experiência do desenvolvedor e a capacidade de resposta da aplicação: tempo de resposta (ou seja, latência) e taxa de transferência em operações de busca e indexação.

• Cargas de trabalho testadas: os testes incluíram operações de busca de alta concorrência típicas de aplicações voltados para o usuário, consultas de busca vetorial complexas e ingestão/indexação de dados de alto volume para casos de uso de observabilidade e segurança. Em particular, nossa metodologia de teste usou publicamente conjuntos de dados disponíveis para o Rally, a ferramenta de benchmarking da Elastic.
  • wikipedia: Um conjunto de dados derivado de um snapshot do conteúdo textual da Wikipédia, para medir o desempenho em busca de texto de uso geral.
  • MSMARCO-Passage-Ranking: Um conjunto de dados derivado do Machine Reading Comprehension (MS MARCO) da Microsoft, para medir o desempenho da busca em campos vetoriais esparsos.
  • OpenAI_Vector: Um conjunto de dados derivado do NQ do BEIR e enriquecido com embeddings gerados pelo modelo text-embedding-ada-002 da OpenAI, para medir o desempenho da busca em campos vetoriais densos.
• Medição: comparamos o desempenho na infraestrutura antiga e na nova, medindo a latência no 99º percentil (P99) para capturar o pior caso, o desempenho da latência de cauda e as operações por segundo. Cada pista era executada cinco vezes em cada perfil de hardware para garantir consistência nos resultados.
• A meta: nosso objetivo era validar a capacidade da infraestrutura de fornecer um desempenho consistentemente mais rápido e previsível em todos os aspectos, mesmo durante períodos de rápida expansão automática.

Resumo de dados de desempenho

Os resultados confirmam ganhos significativos em eficiência e velocidade. Essas melhorias se traduzem diretamente em tempos de resposta mais baixos para os seus usuários e custos operacionais mais baixos, como resultado da capacidade de concluir a mesma quantidade de trabalho com menos recursos computacionais.

As tabelas a seguir detalham as melhorias quantitativas. Valores mais altos são melhores para a throughput; valores mais baixos são melhores para a latência.

Procurando resultados de benchmarks:

Resultados de benchmarks de indexação:

O bônus adicional: redução de custos

Embora nosso foco seja entregar desempenho de baixa latência, a eficiência do novo hardware também tem um impacto direto e positivo nos custos dos projetos Elasticsearch.

O preço do Elasticsearch Serverless é baseado no uso, o que significa que você paga apenas pelos recursos de ingestão e buscas que você consumir. Como o hardware mais novo e mais rápido é mais eficiente, suas cargas de trabalho geralmente concluem tarefas usando menos recursos, levando a uma redução de custo inerente à maioria dos projetos. Você recebe um aumento de desempenho premium sem o preço premium — a definição de eficiência otimizada.

O que isso significa para você, o desenvolvedor?

Esse upgrade na infraestrutura é totalmente gerenciado pela Elastic, então você não precisa mexer um dedo — sem migrações e sem mudanças de configuração. A melhoria é imediata e automática em todos os seus projetos sem servidor baseados na AWS.

Esse upgrade permite que você:

• Construa aplicações mais rápidas: foque a agilidade no desenvolvimento de recursos, sabendo que sua plataforma de busca está entregando a velocidade que seus usuários exigem.
• Inove com confiança: implante novos recursos de busca, observabilidade e segurança, incluindo recursos complexos de IA, como busca vetorial e classificação por relevância, com a garantia de que a plataforma possa lidar com a carga em desempenho máximo.
• Simplifique sua pilha: use um serviço totalmente gerenciado que lide com o gerenciamento da infraestrutura, o planejamento da capacidade e o redimensionamento, para que você possa se concentrar no código e nos dados.
  

Requisitos

• NodeJS versão 18 ou mais recente
• Chave de API da OpenAI
• Implantação do Elasticsearch 8.x+

Por que usar o LangGraph para sistemas HITL de produção

Em um artigo anterior, apresentamos o LangGraph e os benefícios para a construção de um sistema RAG usando LLMs e bordas condicionais para tomar decisões automaticamente e exibir resultados. Às vezes, não queremos que o sistema atue de forma autônoma de ponta a ponta, mas queremos que os usuários selecionem opções e tomem decisões dentro do ciclo de execução. Esse conceito é chamado de "Human in the loop" ou interação humana.

Intervenção humana

Esse é um conceito de IA que permite que uma pessoa real interaja com sistemas de IA para fornecer mais contexto, avaliar respostas, editar respostas, solicitar mais informações etc. Isso é muito útil em cenários de baixa tolerância a erros, como conformidade, tomada de decisões ou geração de conteúdo, ajudando a melhorar a confiabilidade das saídas do LLM.

Um exemplo comum é quando seu assistente de programação pede permissão para executar um determinado comando no terminal ou mostra o processo de pensamento passo a passo para você aprovar antes de começar a programar.

Elasticsearch + LangGraph: Como eles interagem

O LangChain permite usar o Elasticsearch como um repositório de vetores e executar consultas em aplicações LangGraph, o que é útil para realizar buscas de texto completo ou semânticas, enquanto o LangGraph é usado para definir o fluxo de trabalho, as ferramentas e as interações específicas. Além disso, adiciona a HITL (interação humana) como uma camada adicional de interação com o usuário.

Implementação prática: intervenção humana

Vamos imaginar que um advogado tenha uma pergunta sobre um caso que ele assumiu recentemente. Sem as ferramentas certas, ele precisaria buscar manualmente artigos legais e precedentes, ler tudo na íntegra e interpretar como eles se aplicam à situação. Com o LangGraph e o Elasticsearch, no entanto, podemos criar um sistema que busca em um banco de dados precedentes legais e gera uma análise do caso que incorpora os detalhes específicos e o contexto fornecido pelo advogado.

O fluxo de trabalho começa quando o advogado envia uma dúvida jurídica. O sistema realiza uma busca vetorial no Elasticsearch, recupera os precedentes mais relevantes e os apresenta para o advogado escolher usando linguagem natural. Após a seleção, o LLM gera um rascunho de análise e verifica se as informações estão completas. Nesse ponto, o fluxo de trabalho pode seguir dois caminhos: se tudo estiver claro, ele prossegue diretamente para gerar uma análise final; caso contrário, ele faz uma pausa para solicitar esclarecimentos ao advogado. Assim que o contexto em falta for fornecido, o sistema completa a análise e a retorna, levando em consideração os esclarecimentos.

A seguir, você verá um gráfico elaborado pelo LangGraph que mostra como o app ficará no final do desenvolvimento. Cada nó representa uma ferramenta ou funcionalidade:

Conjunto de dados

Aqui está o conjunto de dados que será usado para este exemplo. Este conjunto de dados contém uma coleção de precedentes legais, cada um descrevendo um caso envolvendo atrasos no serviço, o raciocínio do tribunal e o resultado.

[
  {
    "pageContent": "Legal precedent: Case B - Service delay not considered breach. A consulting contract used term 'timely delivery' without specific dates. A three-week delay occurred but contract lacked explicit schedule. Court ruled no breach as parties had not defined concrete timeline and delay did not cause demonstrable harm.",
    "metadata": {
      "caseId": "CASE-B-2022",
      "contractType": "consulting agreement",
      "delayPeriod": "three weeks",
      "outcome": "no breach found",
      "reasoning": "no explicit deadline defined, no demonstrable harm",
      "keyTerms": "timely delivery, open terms, schedule definition",
      "title": "Case B: Delay Without Explicit Schedule"
    }
  },
  ...
]

Ingestão e configuração do índice

A configuração do índice e a lógica de ingestão de dados são definidas no arquivo dataIngestion.ts, onde declaramos funções para lidar com a criação do índice. Essa configuração é compatível com a interface de armazenamento vetorial LangChain para Elasticsearch.

Atenção: a configuração do mapeamento também está incluída no arquivo dataIngestion.ts.

Instale pacotes e configure variáveis de ambiente

Vamos iniciar um projeto Node.js com as configurações padrão:

• @elastic/elasticsearch: cliente Elasticsearch para Node.js. Usado para conectar, criar índices e executar consultas.
• @langchain/community: oferece integrações para ferramentas compatíveis com a comunidade, incluindo o ElasticVectorSearch.
• @langchain/core: blocos núcleo do LangChain, como chains, prompts e utilitários.
• @langchain/langgraph: adiciona orquestração baseada em gráficos, permitindo fluxos de trabalho com nós, bordas e gerenciamento de estados.
• @langchain/openai: oferece acesso aos modelos da OpenAI (LLMs e integrações) por meio do LangChain.
• dotenv: carrega variáveis de ambiente de um arquivo .env em process.env.
• tsx: é uma ferramenta útil para executar código TypeScript.

Execute o seguinte comando no console para instalar todos eles:

npm install @elastic/elasticsearch @langchain/community @langchain/core @langchain/langgraph @langchain/openai dotenv --legacy-peer-deps && npm install --save-dev tsx

Crie um arquivo .env para configurar as variáveis de ambiente:

ELASTICSEARCH_ENDPOINT=
ELASTICSEARCH_API_KEY=
OPENAI_API_KEY=

Usaremos o TypeScript para escrever o código porque ele oferece uma camada de segurança de tipos e uma melhor experiência para o desenvolvedor. Crie um arquivo TypeScript chamado main.ts e insira o código da próxima seção.

Importações de pacotes

No arquivo main.ts, começamos importando os módulos necessários e inicializando a configuração da variável de ambiente. Isso inclui os componentes do núcleo do LangGraph, as integrações do modelo OpenAI e o cliente Elasticsearch.

Também importamos o seguinte do arquivo dataIngestion.ts:

• ingestData: uma função que cria o índice e ingere os dados.
• Document e DocumentMetadata: interfaces que definem a estrutura do documento do conjunto de dados.

Cliente de armazenamento vetorial Elasticsearch, cliente de interações e cliente OpenAI

Esse código inicializará o armazenamento vetorial, o cliente de integrações e um cliente OpenAI.

const VECTOR_INDEX = "legal-precedents";

const llm = new ChatOpenAI({ model: "gpt-4o-mini" });
const embeddings = new OpenAIEmbeddings({
  model: "text-embedding-3-small",
});

const esClient = new Client({
  node: process.env.ELASTICSEARCH_ENDPOINT,
  auth: {
    apiKey: process.env.ELASTICSEARCH_API_KEY ?? "",
  },
});

const vectorStore = new ElasticVectorSearch(embeddings, {
  client: esClient,
  indexName: VECTOR_INDEX,
});

O esquema de estado do fluxo de trabalho da aplicação ajudará na comunicação entre os nós:

const LegalResearchState = Annotation.Root({
  query: Annotation(),
  analyzedConcepts: Annotation(),
  precedents: Annotation(),
  selectedPrecedent: Annotation(),
  draftAnalysis: Annotation(),
  ambiguityDetected: Annotation(),
  userClarification: Annotation(),
  finalAnalysis: Annotation(),
});

No objeto de estado, passaremos a consulta do usuário, os conceitos extraídos dela, os precedentes legais recuperados e qualquer ambiguidade detectada sempre pelos nós. O estado também rastreia o precedente selecionado pelo usuário, o rascunho de análise gerado ao longo do caminho e a análise final quando todos os esclarecimentos forem concluídos.

Nós

searchPrecedents: Este nó realiza uma busca por similaridade no armazenar vetorial do Elasticsearch baseada na entrada do usuário Ele recupera até 5 documentos correspondentes e os imprime para que possam ser revisados pelo usuário.

async function searchPrecedents(state: typeof LegalResearchState.State) {
  console.log(
    "📚 Searching for relevant legal precedents with query:\n",
    state.query
  );

  const results = await vectorStore.similaritySearch(state.query, 5);
  const precedents = results.map((d) => d as Document);

  console.log(`Found ${precedents.length} relevant precedents:\n`);

  for (let i = 0; i < precedents.length; i++) {
    const p = precedents[i];
    const m = p.metadata;
    console.log(
      `${i + 1}. ${m.title} (${m.caseId})\n` +
        `   Type: ${m.contractType}\n` +
        `   Outcome: ${m.outcome}\n` +
        `   Key reasoning: ${m.reasoning}\n` +
        `   Delay period: ${m.delayPeriod}\n`
    );
  }

  return { precedents };
}

precedentSelection: este nó permite ao usuário selecionar, usando linguagem natural, o caso de uso recuperado pela pesquisa com a proximidade que melhor corresponde à pergunta. Nesse ponto, o aplicativo interrompe o fluxo de trabalho e aguarda a entrada do usuário.

function precedentSelection(state: typeof LegalResearchState.State) {
  console.log("\n⚖️  HITL #1: Human input needed\n");
  const question = "👨‍⚖️  Which precedent is most similar to your case? ";
  const userChoice = interrupt({ question });

  return { userChoice };
}

selectPrecedent: este no envia a entrada do usuário, juntamente com os documentos recuperados, para serem interpretados de forma que um deles possa ser selecionado. O LLM realiza essa tarefa retornando um número que representa o documento que ele infere a partir da entrada em linguagem natural do usuário.

async function selectPrecedent(state: typeof LegalResearchState.State) {
  const precedents = state.precedents || [];
  const userInput = (state as any).userChoice || "";

  const precedentsList = precedents
    .map((p, i) => {
      const m = p.metadata;
      return `${i + 1}. ${m.caseId}: ${m.title} - ${m.outcome}`;
    })
    .join("\n");

  const structuredLlm = llm.withStructuredOutput({
    name: "precedent_selection",
    schema: {
      type: "object",
      properties: {
        selected_number: {
          type: "number",
          description:
            "The precedent number selected by the lawyer (1-based index)",
          minimum: 1,
          maximum: precedents.length,
        },
      },
      required: ["selected_number"],
    },
  });

  const prompt = `
    The lawyer said: "${userInput}"

    Available precedents:
    ${precedentsList}

    Which precedent number (1-${precedents.length}) matches their selection?
  `;

  const response = await structuredLlm.invoke([
    {
      role: "system",
      content:
        "You are an assistant that interprets lawyer's selection and returns the corresponding precedent number.",
    },
    { role: "user", content: prompt },
  ]);

  const selectedIndex = response.selected_number - 1;
  const selectedPrecedent = precedents[selectedIndex] || precedents[0];

  console.log(`✅ Selected: ${selectedPrecedent.metadata.title}\n`);
  return { selectedPrecedent };
}

createDraft: este nó gera a análise legal inicial com base no precedente selecionado pelo usuário. Ele usa um LLM para avaliar como o precedente escolhido se aplica à pergunta do advogado e determina se o sistema tem informações suficientes para prosseguir.

Se o precedente puder ser aplicado diretamente, o nó produz uma análise preliminar e, seguindo o caminho correto, salta para o nó final. Se o LLM detectar ambiguidades, como termos contratuais indefinidos, detalhes do cronograma ausentes ou condições pouco claras, ele retorna com uma bandeira indicando que é necessário esclarecimento, junto com uma lista das informações específicas que devem ser fornecidas. Neste caso, a ambiguidade desencadeia o caminho à esquerda do gráfico.

async function createDraft(state: typeof LegalResearchState.State) {
  console.log("📝 Drafting initial legal analysis...\n");

  const precedent = state.selectedPrecedent;
  if (!precedent) return { draftAnalysis: "" };

  const m = precedent.metadata;

  const structuredLlm = llm.withStructuredOutput({
    name: "draft_analysis",
    schema: {
      type: "object",
      properties: {
        needs_clarification: {
          type: "boolean",
          description:
            "Whether the analysis requires clarification about contract terms or context",
        },
        analysis_text: {
          type: "string",
          description: "The draft legal analysis or the ambiguity explanation",
        },
        missing_information: {
          type: "array",
          items: { type: "string" },
          description:
            "List of specific information needed if clarification is required (empty if no clarification needed)",
        },
      },
      required: ["needs_clarification", "analysis_text", "missing_information"],
    },
  });

  const prompt = `
    Based on this precedent:
    Case: ${m.title}
    Outcome: ${m.outcome}
    Reasoning: ${m.reasoning}
    Key terms: ${m.keyTerms}

    And the lawyer's question: "${state.query}"

    Draft a legal analysis applying this precedent to the question.
    
    If you need more context about the specific contract terms, timeline details, 
    or other critical information to provide accurate analysis, set needs_clarification 
    to true and list what information is missing.
    
    Otherwise, provide the legal analysis directly.
  `;

  const response = await structuredLlm.invoke([
    {
      role: "system",
      content:
        "You are a legal research assistant that analyzes cases and identifies when additional context is needed.",
    },
    { role: "user", content: prompt },
  ]);

  let displayText: string;
  if (response.needs_clarification) {
    const missingInfoList = response.missing_information
      .map((info: string, i: number) => `${i + 1}. ${info}`)
      .join("\n");
    displayText = `AMBIGUITY DETECTED:\n${response.analysis_text}\n\nMissing information:\n${missingInfoList}`;
  } else {
    displayText = `ANALYSIS:\n${response.analysis_text}`;
  }

  console.log(displayText + "\n");

  return {
    draftAnalysis: displayText,
    ambiguityDetected: response.needs_clarification,
  };
}

Os dois caminhos que o gráfico pode seguir são os seguintes:

O caminho à esquerda inclui um nó adicional que cuida da clarificação.

requestClarification: este nó aciona a segunda etapa de intervenção humana quando o sistema identifica que a análise preliminar precisa de contexto essencial. O fluxo de trabalho é interrompido e é solicitado o usuário que ele esclareça os detalhes do contrato ausentes detectados pelo nó anterior.

function requestClarification(state: typeof LegalResearchState.State) {
  console.log("\n⚖️  HITL #2: Additional context needed\n");
  const userClarification = interrupt({
    question: "👨‍⚖️  Please provide clarification about your contract terms:",
  });
  return { userClarification };
}

generateFinalAnalysis: este nó gera a análise jurídica final combinando o precedente selecionado com o contexto adicional fornecido pelo usuário, se necessário. Utilizando os esclarecimentos obtidos na etapa HITL anterior, o LLM sintetiza o raciocínio do precedente, os detalhes do contrato fornecidos pelo usuário e as condições que determinam se pode ter ocorrido uma violação.

O nó gera uma análise completa que integra interpretação jurídica e recomendações práticas.

async function generateFinalAnalysis(state: typeof LegalResearchState.State) {
  console.log("📋 Generating final legal analysis...\n");

  const precedent = state.selectedPrecedent;
  if (!precedent) return { finalAnalysis: "" };

  const m = precedent.metadata;

  const prompt = `
    Original question: "${state.query}"
    
    Selected precedent: ${m.title}
    Outcome: ${m.outcome}
    Reasoning: ${m.reasoning}
    
    Lawyer's clarification: "${state.userClarification}"
    
    Provide a comprehensive legal analysis integrating:
    1. The selected precedent's reasoning
    2. The lawyer's specific contract context
    3. Conditions for breach vs. no breach
    4. Practical recommendations
  `;

  const response = await llm.invoke([
    {
      role: "system",
      content:
        "You are a legal research assistant providing comprehensive analysis.",
    },
    { role: "user", content: prompt },
  ]);

  const finalAnalysis = response.content as string;

  console.log(
    "\n" +
      "=".repeat(80) +
      "\n" +
      "⚖️  FINAL LEGAL ANALYSIS\n" +
      "=".repeat(80) +
      "\n\n" +
      finalAnalysis +
      "\n\n" +
      "=".repeat(80) +
      "\n"
  );

  return { finalAnalysis };
}

Construindo um gráfico:

const workflow = new StateGraph(LegalResearchState)
  .addNode("analyzeQuery", analyzeQuery)
  .addNode("searchPrecedents", searchPrecedents)
  .addNode("precedentSelection", precedentSelection)
  .addNode("selectPrecedent", selectPrecedent)
  .addNode("createDraft", createDraft)
  .addNode("requestClarification", requestClarification)
  .addNode("generateFinalAnalysis", generateFinalAnalysis)
  .addEdge("__start__", "analyzeQuery")
  .addEdge("analyzeQuery", "searchPrecedents")
  .addEdge("searchPrecedents", "precedentSelection") // HITL #1
  .addEdge("precedentSelection", "selectPrecedent")
  .addEdge("selectPrecedent", "createDraft")
  .addConditionalEdges(
    "createDraft",
    (state: typeof LegalResearchState.State) => {
      // If ambiguity detected, request clarification (HITL #2)
      if (state.ambiguityDetected) return "needsClarification";
      // Otherwise, generate final analysis
      return "final";
    },
    {
      needsClarification: "requestClarification",
      final: "generateFinalAnalysis",
    }
  )
  .addEdge("requestClarification", "generateFinalAnalysis") // HITL #2
  .addEdge("generateFinalAnalysis", "__end__");

No gráfico, podemos ver que a borda condicional define a condição para a escolha do caminho "final". Conforme demonstrado, a decisão agora depende do fato de a análise preliminar ter detectado ambiguidade que exija esclarecimentos adicionais.

Junte tudo para ser executado:

await ingestData();

// Compile workflow
const app = workflow.compile({ checkpointer: new MemorySaver() });
const config = { configurable: { thread_id: "hitl-circular-thread" } };

await saveGraphImage(app);

// Execute workflow
const legalQuestion =
    "Does a pattern of repeated delays constitute breach even if each individual delay is minor?"; 

console.log(`⚖️  LEGAL QUESTION: "${legalQuestion}"\n`);

let currentState = await app.invoke({ query: legalQuestion }, config);

// Handle all interruptions in a loop
while ((currentState as any).__interrupt__?.length > 0) {
  console.log("\n💭 APPLICATION PAUSED WAITING FOR USER INPUT...");

  const interruptQuestion = (currentState as any).__interrupt__[0]?.value
    ?.question;
  const userChoice = await getUserInput(
    interruptQuestion || "👤 YOUR CHOICE: "
  );

  currentState = await app.invoke(
    new Command({ resume: userChoice }),
    config
  );
}

Execute o script:

Com todo o código alocado, vamos executar o arquivo main.ts escrevendo o seguinte comando no terminal:

tsx main.ts

Após a execução do script, a pergunta "Um padrão de atrasos repetidos constitui uma violação, mesmo que cada atraso individual seja pequeno?" será enviada ao Elasticsearch para realizar uma busca por proximidade e os resultados recuperados do índice serão exibidos. O app detecta que vários precedentes relevantes correspondem à consulta, então ele pausa a execução e pede que o usuário ajude a fazer a desambiguação de qual precedente legal for mais aplicável:

📚 Searching for relevant legal precedents with query:
 Does a pattern of repeated delays constitute breach even if each individual delay is minor?
Found 5 relevant precedents:

1. Case H: Pattern of Repeated Delays (CASE-H-2021)
   Type: ongoing service agreement
   Outcome: breach found
   Key reasoning: pattern demonstrated failure to perform, cumulative effect
   Delay period: multiple instances

2. Case E: Minor Delay Quality Maintained (CASE-E-2022)
   Type: service agreement
   Outcome: minor breach only
   Key reasoning: delay minimal, quality maintained, termination unjustified
   Delay period: five days

3. Case A: Delay Breach with Operational Impact (CASE-A-2023)
   Type: service agreement
   Outcome: breach found
   Key reasoning: delay affected operations and caused financial harm
   Delay period: two weeks

4. Case B: Delay Without Explicit Schedule (CASE-B-2022)
   Type: consulting agreement
   Outcome: no breach found
   Key reasoning: no explicit deadline defined, no demonstrable harm
   Delay period: three weeks

5. Case C: Justified Delay External Factors (CASE-C-2023)
   Type: construction service
   Outcome: no breach found
   Key reasoning: external factors beyond control, force majeure applied
   Delay period: one month

⚖️  HITL #1: Human input needed

💭 APPLICATION PAUSED WAITING FOR USER INPUT...
👨‍⚖️  Which precedent is most similar to your case? 

O interessante sobre este aplicativo é que podemos usar linguagem natural para escolher uma opção, permitindo que o LLM interprete a entrada do usuário para determinar a escolha correta. Vamos ver o que acontece se inserirmos o texto: “Caso H”

💭 APPLICATION PAUSED WAITING FOR USER INPUT...
👨‍⚖️  Which precedent is most similar to your case? Case H

✅ Selected: Case H: Pattern of Repeated Delays

📝 Drafting initial legal analysis...

AMBIGUITY DETECTED:
Based on Case H, a pattern of repeated delays can indeed constitute a breach of contract, even if each individual delay is minor. The outcome in Case H indicates that the cumulative effect of these minor delays led to a significant failure to perform the contractual obligations adequately. The reasoning emphasizes that consistent performance is critical in fulfilling the terms of a contract. Therefore, if the repeated delays create a situation where the overall performance is hindered, this pattern could be interpreted as a breach. However, the interpretation may depend on the specific terms of the contract at issue, as well as the expectations of performance set forth in that contract.

Missing information:
1. Specific contract terms regarding performance timelines
2. Details on the individual delays (duration, frequency)
3. Context on consequences of delays stated in the contract
4. Other parties' expectations or agreements related to performance


⚖️  HITL #2: Additional context needed


💭 APPLICATION PAUSED WAITING FOR USER INPUT...
👨‍⚖️  Please provide clarification about your contract terms:

O modelo pega o esclarecimento do usuário e o integra ao fluxo de trabalho, prosseguindo com a análise final quando o contexto suficiente for fornecido. Nesta etapa, o sistema também utiliza a ambiguidade previamente detectada: a análise preliminar destacou detalhes contratuais ausentes que poderiam afetar e muito a interpretação jurídica. Esses itens de “informações ausentes” orientam o modelo na determinação de quais esclarecimentos são essenciais para resolver a incerteza antes de produzir uma opinião final confiável.

O usuário deve incluir na próxima entrada as solicitações de esclarecimentos. Vamos tentar com "O contrato exige 'pronta entrega' sem cronogramas. 8 atrasos de 2 a 4 dias em 6 meses. US$ 50 mil em perdas devido a 3 prazos não cumpridos pelo cliente. O fornecedor foi notificado, mas o padrão continuou."

💭 APPLICATION PAUSED WAITING FOR USER INPUT...
👨‍⚖️  Please provide clarification about your contract terms: Contract requires "prompt delivery" without timelines. 8 delays of 2-4 days over 6 months. $50K in losses from 3 missed client deadlines. Vendor notified but pattern continued.

📋 Generating final legal analysis...

================================================================================
⚖️  FINAL LEGAL ANALYSIS
================================================================================

To analyze the question of whether a pattern of repeated minor delays constitutes a breach of contract, we need to combine insights from the selected precedent, the specifics of the lawyer's contract situation, conditions that typically govern breach versus non-breach, and practical recommendations for the lawyer moving forward.

### 1. Selected Precedent's Reasoning

The precedent case, referred to as Case H, found that a pattern of repeated delays amounted to a breach of contract. The court reasoned that even minor individual delays, when considered cumulatively, demonstrated a failure to perform as stipulated in the contract. The underlying rationale was that the cumulative effect of these minor delays could significantly undermine the purpose of the contract, which typically aims for timely performance and reliable delivery.

### 2. Lawyer's Specific Contract Context

In the lawyer's situation, the contract specified "prompt delivery" but did not provide a strict timeline. The vendor experienced 8 delays ranging from 2 to 4 days over a period of 6 months. These delays culminated in $50,000 in losses due to three missed client deadlines. The vendor was notified regarding these delays; however, the pattern of delays persisted.

Key considerations include:
- **Nature of the Obligations**: While “prompt delivery” does not define a strict timeline, it does imply an expectation for timely performance.
- **Material Impact**: The missed client deadlines indicate that these delays had a material adverse effect on the lawyer's ability to fulfill contractual obligations to third parties, likely triggering damages.

### 3. Conditions for Breach vs. No Breach

**Conditions for Breach**:
- **Pattern and Cumulative Effect**: Similar to the reasoning in Case H, evidence of a habitual pattern of delays can amount to a breach. Even if individual delays are minor, when combined, they may show a lack of diligence or reliability by the vendor.
- **Materiality**: The impact of these delays is crucial. If the cumulative delays adversely affect the contract's purpose or cause significant losses, this reinforces the case for a breach.
- **Notification and Opportunity to Cure**: The fact that the vendor was notified of the delays and failed to rectify the behavior can often be interpreted as a further indication of breach.

**Conditions for No Breach**:
- **Non-Material Delays**: If the delays did not affect the overall contractual performance or client obligations, this may lessen the likelihood of establishing a breach. However, given the risks and losses involved, this seems less relevant in this scenario.
- **Force Majeure or Justifiable Delays**: If the vendor could show that these delays were due to justify circumstances not within their control, it may potentially provide a defense against breach claims.

### 4. Practical Recommendations

1. **Assess Damages**: Document the exact nature of the financial losses incurred due to the missed deadlines to substantiate claims of damages.
  
2. **Gather Evidence**: Collect all communication regarding the delays, including any notifications sent to the vendor about the issues.

3. **Consider Breach of Contract Action**: Based on the precedent and accumulated delays, consider formalized communication to the vendor regarding a breach of contract claim, highlighting both the pattern and the impact of these repeated delays.

4. **Evaluate Remedies**: Depending upon the contract specifics, the lawyer may wish to pursue several remedies, including:
   - **Compensatory Damages**: For the financial losses due to missed deadlines.
   - **Specific Performance**: If timely delivery is critical and can still be enforced.
   - **Contract Termination**: Depending on the severity, terminating the contract and seeking replacements may be warranted.

5. **Negotiate Terms**: If continuing to work with the current vendor is strategic, the lawyer should consider renegotiating terms for performance guarantees or penalties for further delays.

6. **Future Contracts**: In future contracts, consider including explicit timelines and conditions for prompt delivery, as well as specified damages for delays to better safeguard against this issue.

By integrating the legal principles from the precedent with the specific context and conditions outlined, the lawyer can formulate a solid plan to address the repeated delays by the vendor effectively.

Essa saída mostra a etapa final do fluxo de trabalho, em que o modelo integra o precedente selecionado (Caso H) e os esclarecimentos do advogado para gerar uma análise jurídica completa. O sistema explica por que o padrão de atrasos provavelmente constitui uma violação, destaca os fatores que sustentam essa interpretação e fornece recomendações práticas. No geral, a saída demonstra como os esclarecimentos do HITL resolvem a ambiguidade e permitem que o modelo produza uma opinião jurídica bem fundamentada e específica do contexto.

Outros cenários do mundo real

Esse tipo de aplicação, usando Elasticsearch, LangGraph e humanos, pode ser útil em outros tipos de apps como:

• Revisando ferramentas de chamadas antes da execução, por exemplo, em negociações financeiras, um humano aprova pedidos de compra/venda antes que eles sejam feitos.
• Forneça parâmetros adicionais quando necessário, por exemplo, na triagem de suporte ao cliente, onde um agente humano seleciona a categoria correta de problema quando a IA encontra múltiplas possíveis interpretações do problema do cliente.

E há muitos casos de uso que precisam ser descobertos em que a intervenção humana será um divisor de águas.

Conclusão

Com o LangGraph e o Elasticsearch, podemos criar agentes que tomem as próprias decisões e atuem como fluxos de trabalho lineares ou tenham condições de seguir um caminho ou outro. Com a intervenção humana, os agentes podem envolver o usuário real no processo de tomada de decisão para preencher lacunas contextuais e solicitar confirmações em sistemas em que a tolerância a falhas é fundamental.

Uma das vantagens dessa abordagem é que você pode filtrar um grande conjunto de dados usando os recursos do Elasticsearch e usar um LLM para ter um único documento como seleção do usuário. Essa última etapa seria muito mais complicada se você usasse apenas o Elasticsearch, pois há muitas maneiras de um ser humano se referir a um resultado usando linguagem natural.

Essa abordagem mantém o sistema rápido e eficiente em termos de tokens, pois enviamos ao LLM apenas o necessário para tomar a decisão final e não o conjunto de dados completo. Ao mesmo tempo, isso mantém a precisão na detecção da intenção do usuário e permite iterar até que a opção desejada seja escolhida.

Nosso objetivo era fazer a transição para uma abordagem automatizada e adaptativa capaz de lidar com a análise de logs (extração de campos) e o particionamento de logs (identificação da fonte). Nossa hipótese é que os grandes modelos de linguagem (LLMs), com a compreensão inerente da sintaxe do código e dos padrões semânticos, poderiam automatizar essas tarefas com o mínimo de intervenção humana.

Temos o prazer de anunciar que esse recurso já está disponível no Streams!

Descrição do conjunto de dados

Escolhemos uma coleção de logs do Loghub para fins de PoC. Para nossa investigação, selecionamos amostras representativas das seguintes áreas-chave:

• Sistemas distribuídos: utilizamos os conjuntos de dados HDFS (Hadoop Distributed File System) e Spark. Esses contêm uma mistura de informações, mensagens de debug e erros típicos das plataformas de big data.
• Servidores e aplicações web: logs dos servidores web Apache e do OpenSSH forneceram uma fonte valiosa de acesso, erro e eventos relevantes para a segurança. Esses são fundamentais para monitorar o tráfego web e detectar ameaças potenciais.
• Sistemas operacionais: incluímos logs do Linux e do Windows. Esses conjuntos de dados representam os eventos comuns e semiestruturados em nível de sistema que as equipes de operações enfrentam diariamente.
• Sistemas móveis: para garantir que nosso modelo pudesse lidar com logs de ambientes móveis, incluímos o conjunto de dados Android. Esses logs costumam ser extensos e captam uma ampla gama de atividades em nível de aplicação e sistema em dispositivos móveis.
• Supercomputadores: para testar o desempenho em ambientes de computação de alto desempenho (HPC), incorporamos o conjunto de dados BGL (Blue Gene/L), que apresenta logs altamente estruturados com terminologia específica de domínio.

Uma das principais vantagens da coleção Loghub é que os logs são, em grande parte, não higienizados e não rotulados, espelhando um ambiente de produção real e ruidoso com arquitetura de microsserviços.

Exemplos de logs:

[Sun Dec 04 20:34:21 2005] [notice] jk2_init() Found child 2008 in scoreboard slot 6
[Sun Dec 04 20:34:25 2005] [notice] workerEnv.init() ok /etc/httpd/conf/workers2.properties
[Mon Dec 05 11:06:51 2005] [notice] workerEnv.init() ok /etc/httpd/conf/workers2.properties
17/06/09 20:10:58 INFO output.FileOutputCommitter: Saved output of task 'attempt_201706092018_0024_m_000083_1138' to hdfs://10.10.34.11:9000/pjhe/test/1/_temporary/0/task_201706092018_0024_m_000083
17/06/09 20:10:58 INFO mapred.SparkHadoopMapRedUtil: attempt_201706092018_0024_m_000083_1138: Committed

Além disso, criamos um cluster Kubernetes com uma configuração típica de aplicação web + banco de dados para minerar logs extras no domínio mais comum.

Exemplo de campos de log comuns: carimbo de tempo, nível de log (INFO, AVISO, ERRO), origem, mensagem.

Análise de logs com poucos exemplos usando um LLM

Nosso primeiro conjunto de experimentos concentrou-se em uma questão fundamental: Um LLM pode identificar áreas-chave de forma confiável e gerar regras consistentes de análise para extraí-las?

Solicitamos a um modelo que analisasse amostras de registros brutos e gerasse regras de análise sintática de log nos formatos de expressão regular (regex) e Grok. Nossos resultados mostraram que essa abordagem tem muito potencial, mas também apresenta desafios significativos de implementação.

Alto nível de confiança e consciência contextual

Os resultados iniciais foram promissores. O LLM demonstrou uma forte habilidade de gerar regras de análise sintática que correspondiam aos exemplos de poucos disparos fornecidos com alta confiança. Além da simples correspondência de padrões, o modelo demonstrou capacidade de compreensão de logs, pois ele conseguiu identificar e nomear corretamente a fonte do log (por exemplo, aplicativo de monitoramento de saúde, aplicativo web Nginx, banco de dados MongoDB).

O dilema "Cachinhos Dourados" das amostras de entrada

Nossos experimentos logo revelaram uma falta significativa de robustez devido à extrema sensibilidade à amostra de entrada. O desempenho do modelo varia muito com base nos exemplos específicos de logs incluídos no prompt. Observamos um problema de similaridade de log, onde a amostra de logs precisa incluir logs diversos:

• Homogeneidade excessiva (sobreajuste): se os logs de entrada forem muito semelhantes, o LLM tende a superespecificar. Ele trata dados de variáveis, como nomes específicos de classes Java em um rastreio de pilha, como partes estáticas do template. Isso resulta em regras frágeis que cobrem uma proporção minúscula de logs e extraem campos inutilizáveis.
• Muito heterogêneo (confusão): por outro lado, se a amostra contiver uma variação significativa de formatação, ou pior, "registros de lixo" como barras de progresso, tabelas de memória ou arte ASCII, o modelo terá dificuldades para encontrar um denominador comum. Geralmente, ele recorre à geração de expressões regulares complexas e quebradas ou à generalização lenta de toda a linha em um único campo blob de mensagem.

A restrição da janela de contexto

Também encontramos um gargalo na janela de contexto. Quando os registros de entrada eram longos, heterogêneos ou ricos em campos extraíveis, a saída do modelo geralmente se deteriorava, tornando-se "confusa" ou muito longa para caber na janela de contexto de saída. Naturalmente, a fragmentação ajuda nesse caso. Ao dividir os logs usando delimitadores baseados em caracteres e em entidades, podemos ajudar o modelo a se concentrar na extração dos campos principais sem ser sobrecarregado por ruídos.

A lacuna de consistência e padronização

Mesmo quando o modelo gerou regras com sucesso, notamos pequenas inconsistências:

• Variações de nomenclatura de serviço: o modelo propõe diferentes nomes para a mesma entidade (por exemplo, rotulando a fonte como "Spark", "Apache Spark" e "Spark Log Analytics" em diferentes execuções).
• Variações na nomenclatura dos campos: os nomes dos campos não tinham padronização (por exemplo, id X service.id X device.id). Normalizamos os nomes usando uma nomenclatura de campo padronizada do Elastic.
• Variância de resolução: a resolução da extração de campo variava dependendo de o quão semelhantes eram os logs de entrada entre si.

Formato de log impressão digital

Para enfrentar o desafio da similaridade de log, apresentamos uma heurística de alto desempenho: impressão digital de formato de log (LFF).

Em vez de inserir logs brutos e ruidosos diretamente em um LLM, primeiro aplicamos uma transformação determinística para revelar a estrutura subjacente de cada mensagem. Essa etapa de pré-processamento abstrai os dados das variáveis, gerando uma "impressão digital" simplificada que nos permite agrupar logs relacionados.

A lógica de mapeamento é simples para garantir velocidade e consistência:

1. Abstração de dígitos: qualquer sequência de dígitos (0-9) é substituída por um único "0".
2. Abstração de texto: qualquer sequência de caracteres alfabéticos com espaço em branco é substituída por um único "a".
3. Normalização de espaço em branco: todas as sequências de espaço em branco (espaços, tabulações, novas linhas) são reduzidos a um único espaço.
4. Preservação de símbolos: pontuação e caracteres especiais (por exemplo, :, [, ], /) são preservados, pois normalmente são os indicadores mais fortes da estrutura log.

Apresentamos a abordagem de mapeamento de log. Os padrões básicos de mapeamento incluem os seguintes:

• Dígitos de 0 a 9 de qualquer comprimento -> até "0".
• Texto (caracteres alfabéticos com espaços) de qualquer comprimento -> para "a".
• Espaços em branco, abas e novas linhas -> para um único espaço.

Vamos ver um exemplo de como esse mapeamento nos permite transformar os logs.

Como resultado, obtemos as seguintes máscaras de log:

Observe as impressões digitais dos dois primeiros logs. Apesar dos diferentes carimbos de data e hora, classes de origem e conteúdo da mensagem, os prefixos (0/0/0 0:0:0 a a.a:) são idênticos. Esse alinhamento estrutural nos permite colocar automaticamente esses logs em buckets no mesmo cluster.

O terceiro log, no entanto, produz uma impressão digital completamente divergente (0-0-0...). Isso nos permite separá-lo algoritmicamente do primeiro grupo antes mesmo de invocarmos um LLM.

Parte bônus: Implementação instantânea com ES|QL

É tão simples quanto passar essa consulta no Discover.

FROM loghub |
EVAL pattern = REPLACE(REPLACE(REPLACE(REPLACE(raw_message, "[ \t\n]+", " "), "[A-Za-z]+", "a"), "[0-9]+", "0"), "a( a)+", "a") |
STATS total_count = COUNT(), ratio = COUNT() / 2000.0, datasources=VALUES(filename), example=TOP(raw_message, 3, "desc") BY SUBSTRING(pattern, 0, 15) |
SORT total_count DESC |
LIMIT 100

Detalhamento da consulta:

DE loghub: direcionado para nosso índice contendo os dados de registro bruto.

Padrão EVAL = ...: a lógica de mapeamento do núcleo. Encadeamos funções REPLACE para realizar a abstração (por exemplo, dígitos para '0', texto para 'a', etc.) e salvamos o resultado em um campo "padrão".

STATS [column1 =] expression1, … POR SUBSTRING(pattern, 0, 15):

Esta é uma etapa de clustering. Agrupamos logs que compartilham os primeiros 15 caracteres de seu padrão e criamos campos agregados, como contagem total de log por grupo, lista de fontes de dados de log, prefixo do padrão, 3 exemplos de log

SORT total_count DESC | LIMITE 100: destaca os 100 padrões de log mais frequentes

Os resultados das consultas no LogHub estão exibidos abaixo:

Como demonstrado na visualização, essa abordagem "livre de LLM" particiona logs com alta precisão. Ela agrupou com sucesso 10 das 16 fontes de dados (com base nos rótulos do LogHub) (>90%) e alcançou clustering majoritário em 13 das 16 fontes (>60%), tudo isso sem necessidade de limpeza adicional, pré-processamento nem ajuste fino.

A impressão digital do formato de Log oferece uma alternativa pragmática e de alto impacto, além de ser um complemento para soluções sofisticadas de ML, como a análise de padrões de log. Ele fornece insights imediatos sobre relacionamentos de logs e gerencia efetivamente grandes clusters de logs.

• Versatilidade como primitiva

Graças à implementação do ES|QL, o LFF funciona tanto como uma ferramenta independente para diagnósticos/visualizações de dados rápidos, quanto como um componente essencial em pipelines de análise de logs para casos de uso de alto volume.

• Flexibilidade

O LFF é fácil de personalizar e estender para captar padrões específicos, ou seja, números hexadecimais e endereços IP.

• Estabilidade determinística

Ao contrário dos algoritmos de clustering baseados em ML, a lógica LFF é direta e determinística. Novos logs recebidos não afetam retroativamente os clusters de logs existentes.

• Desempenho e memória

Requer memória mínima, sem treinamento nem GPU, tornando-o ideal para ambientes de alta taxa em tempo real.

Combinando a impressão digital do formato de log com um LLM

Para validar a arquitetura híbrida proposta, cada experimento continha um subconjunto aleatório de 20% dos registros de cada fonte de dados. Essa restrição simula um ambiente de produção real onde os logs são processados em lotes, em vez de um despejo histórico monolítico.

O objetivo era demonstrar que o LFF atua como uma camada de compressão eficaz. Nosso objetivo era provar que regras de análise de alta cobertura poderiam ser geradas a partir de amostras pequenas e selecionadas e generalizadas com sucesso para todo o conjunto de dados.

Pipeline de execução

Implementamos um pipeline de múltiplas etapas que filtra, agrupa e aplica amostragem estratificada aos dados antes que cheguem ao LLM.

1. Clustering hierárquico em dois estágios

• Subclasses (correspondência exata): os logs são agregados por impressões digitais idênticas. Todo log em uma subclasse compartilha exatamente a mesma estrutura de formato.
• Limpeza de discrepâncias. Nós descartamos quaisquer subclasses que representam menos de 5% do volume total de log. Isso garante que o LLM se concentre no sinal dominante e não seja desviado por ruído ou logs malformados.
• Metaclasses (correspondência de prefixo): as subclasses restantes são agrupadas em metaclasses pelos primeiros N caracteres da correspondência da impressão digital do formato. Essa estratégia de agrupamento divide efetivamente formatos lexicalmente semelhantes sob uma mesma categoria. Escolhemos N=5 para análise de log e N=15 para particionamento de log quando as fontes de dados são desconhecidas.

2. Amostragem estratificada. Após a construção da árvore hierárquica, construímos a amostra de log para o LLM. O objetivo estratégico é maximizar a cobertura de variações enquanto minimiza o uso de tokens.

• Selecionamos logs representativos de cada subclasse válida dentro da metaclasse mais ampla.
• Para gerenciar um caso extremo de subclasses muito numerosas, aplicamos subamostragem aleatória para ajustar ao tamanho da janela alvo.

3. Geração de regras Final, solicitamos ao LLM que gere uma regra de análise regex que se encaixe em todos os logs da amostra fornecida para cada metaclasse. Para nossa PoC, usamos o modelo mini GPT-4o.

Resultados experimentais e observações

Alcançamos 94% de precisão de análise sintática e 91% de precisão de particionamento no conjunto de dados do Loghub.

A matriz de confusão acima ilustra os resultados da partição log. O eixo vertical representa as fontes de dados reais e o eixo horizontal representa as fontes de dados previstas. A intensidade do heatmap corresponde ao volume do log, com blocos mais claros indicando uma contagem maior. O alinhamento diagonal demonstra a alta fidelidade do modelo na atribuição da fonte, com espalhamento mínimo.

Nossos insights sobre benchmarks de desempenho:

• Linha de base ideal: uma janela de contexto de 30 a 40 amostras de log por categoria provou ser o ponto ideal, produzindo consistentemente uma análise robusta com padrões Regex e Grok.
• Minimização da entrada: aumentamos o tamanho da entrada para 10 registros por categoria para padrões Regex e observamos uma queda de apenas 2% no desempenho da análise, confirmando que a amostragem baseada na diversidade é mais importante do que o volume bruto.

Os modelos Jina se enquadram em três grandes categorias, projetadas para dar suporte ao processamento, à organização e à recuperação de informações:

• Modelos de embedding semântico
• Modelos de reclassificação
• Modelos de linguagem generativos de pequeno porte

Modelos de embedding semântico

A ideia por trás dos embeddings semânticos é que um modelo de IA pode aprender a representar aspectos do significado de suas entradas em termos da geometria de espaços de alta dimensionalidade.

É possível pensar em um embedding semântico como um ponto (tecnicamente, um vetor) em um espaço de alta dimensionalidade. Um modelo de embedding é uma rede neural que recebe algum tipo de dado digital como entrada, potencialmente qualquer tipo, mas mais comumente texto ou imagem, e produz a localização de um ponto correspondente em um espaço de alta dimensionalidade, representada por um conjunto de coordenadas numéricas. Quando o modelo executa bem sua função, a distância entre dois embeddings semânticos é proporcional ao quanto os objetos digitais correspondentes compartilham o mesmo significado.

Para entender por que isso é importante para aplicações de busca, imagine um embedding para a palavra “cão” e outro para a palavra “gato” como pontos em um espaço.

Um bom modelo de embedding deve gerar um embedding para a palavra “felino” muito mais próximo de “gato” do que de “cão”, e “canino” deve ter um embedding muito mais próximo de “cão” do que de “gato”, porque essas palavras têm praticamente o mesmo significado.

Se um modelo for multilíngue, espera-se o mesmo comportamento para traduções de “gato” e “cão” em outros idiomas.

Modelos de embedding traduzem similaridade ou dissimilaridade de significado entre elementos em relações espaciais entre embeddings. As imagens acima têm apenas duas dimensões para que seja possível visualizá-las na tela, mas modelos de embedding produzem vetores com dezenas a milhares de dimensões. Isso permite codificar sutilezas de significado para textos inteiros, atribuindo um ponto em um espaço com centenas ou milhares de dimensões a documentos com milhares de palavras ou mais.

Embeddings multimodais

Modelos multimodais estendem o conceito de embeddings semânticos para além de textos, especialmente para imagens. Espera-se que o embedding de uma imagem fique próximo ao embedding de uma descrição fiel dessa imagem.

Embeddings semânticos têm muitos usos. Entre outras aplicações, é possível usá-los para criar classificadores eficientes, realizar clustering de dados e executar diversas tarefas, como deduplicação de dados e investigação da diversidade dos dados, ambas importantes para aplicações de big data que lidam com volumes de informação grandes demais para serem gerenciados manualmente.

O principal uso direto de embeddings está na recuperação de informações. O Elasticsearch pode armazenar objetos de recuperação com embeddings como chaves. As consultas são convertidas em vetores de embedding, e a busca retorna os objetos armazenados cujas chaves estão mais próximas do embedding da consulta.

Enquanto a recuperação tradicional baseada em vetores (às vezes chamada de recuperação por vetores esparsos) usa vetores baseados em palavras ou metadados presentes em documentos e consultas, a recuperação baseada em embeddings (também conhecida como recuperação por vetores densos) usa significados avaliados por IA em vez de palavras. Isso a torna, em geral, muito mais flexível e mais precisa do que métodos tradicionais de busca.

Aprendizado de representação Matryoshka

O número de dimensões de um embedding, assim como a precisão dos valores numéricos que o compõem, tem impactos significativos na performance. Espaços de dimensionalidade muito alta e números de precisão extremamente elevada podem representar informações altamente detalhadas e complexas, mas exigem modelos de IA maiores, mais caros para treinar e para executar. Os vetores que esses modelos geram requerem mais espaço de armazenamento, e são necessários mais ciclos de computação para calcular as distâncias entre eles. Usar modelos de embedding semântico envolve fazer concessões importantes entre precisão e consumo de recursos.

Para maximizar a flexibilidade para os usuários, os modelos Jina são treinados com uma técnica chamada Aprendizado de Representação Matryoshka. Essa abordagem faz com que os modelos concentrem as distinções semânticas mais importantes nas primeiras dimensões do vetor de embedding, de modo que seja possível descartar as dimensões mais altas e ainda assim obter bom desempenho.

Na prática, isso significa que usuários dos modelos Jina podem escolher quantas dimensões desejam que seus embeddings tenham. Escolher menos dimensões reduz a precisão, mas a degradação de performance é pequena. Na maioria das tarefas, as métricas de performance dos modelos Jina caem entre 1% e 2% sempre que o tamanho do embedding é reduzido em 50%, até uma redução total de cerca de 95% no tamanho.

Recuperação assimétrica

A similaridade semântica geralmente é medida de forma simétrica. O valor obtido ao comparar “gato” com “cão” é o mesmo que ao comparar “cão” com “gato”. No entanto, quando embeddings são usados para recuperação de informações, o desempenho melhora quando essa simetria é quebrada e as consultas são codificadas de forma diferente dos objetos de recuperação.

Isso ocorre por causa da forma como treinamos modelos de embedding. Os dados de treinamento contêm ocorrências dos mesmos elementos, como palavras, em muitos contextos diferentes, e os modelos aprendem semântica comparando similaridades e diferenças contextuais entre esses elementos.

Assim, por exemplo, pode acontecer de a palavra “animal” não aparecer em muitos dos mesmos contextos que “gato” ou “cão”, e, portanto, o embedding de “animal” não ficar particularmente próximo de “gato” ou “cão”.

Isso torna menos provável que uma consulta por “animal” recupere documentos sobre gatos e cães — justamente o oposto do nosso objetivo. Por isso, em vez disso, codificamos “animal” de forma diferente quando ele aparece como consulta do que quando é um alvo de recuperação.

Recuperação assimétrica significa usar um modelo diferente para consultas ou treinar especificamente um modelo de embedding para codificar os dados de uma forma quando são armazenados para recuperação e de outra forma quando são usados como consultas.

Embeddings multivetoriais

Embeddings únicos funcionam bem para recuperação de informações porque se encaixam no modelo básico de um banco de dados indexado: armazenamos objetos para recuperação usando um único vetor de embedding como chave de recuperação. Quando usuários consultam o repositório de documentos, suas consultas são traduzidas em vetores de embedding, e os documentos cujas chaves estão mais próximas do embedding da consulta, no espaço de embeddings de alta dimensionalidade, são recuperados como candidatos.

Embeddings multivetoriais funcionam de forma um pouco diferente. Em vez de gerar um vetor de comprimento fixo para representar uma consulta e um objeto armazenado inteiro, eles produzem uma sequência de embeddings que representam partes menores desses elementos. Essas partes geralmente são tokens ou palavras no caso de textos, e blocos de imagem no caso de dados visuais. Esses embeddings refletem o significado de cada parte dentro de seu contexto.

Por exemplo, considere estas frases:

• Ela tinha um coração de ouro.
• Ela fez das tripas coração.
• Ela teve um ataque do coração.

Superficialmente, essas frases parecem muito semelhantes, mas um modelo multivetorial provavelmente geraria embeddings bem diferentes para cada ocorrência de “coração”, representando como cada uma assume um significado distinto no contexto da frase como um todo.

Comparar dois objetos por meio de seus embeddings multivetoriais geralmente envolve medir a distância de Chamfer: comparar cada parte de um embedding multivetorial com cada parte de outro e somar as menores distâncias entre elas. Outros sistemas, incluindo os reclassificadores Jina descritos abaixo, usam esses embeddings como entrada para um modelo de IA treinado especificamente para avaliar sua similaridade. Ambas as abordagens normalmente apresentam maior precisão do que a simples comparação de embeddings de vetor único, porque embeddings multivetoriais contêm informações muito mais detalhadas do que embeddings de vetor único.

No entanto, embeddings multivetoriais não são adequados para indexação. Eles costumam ser usados em tarefas de reclassificação, conforme descrito para o modelo jina-colbert-v2 na próxima seção.

Modelos de embedding Jina

Jina embeddings v4

jina-embeddings-v4 é um modelo de embedding multilíngue e multimodal, com 3,8 bilhões (3,8 × 10⁹) de parâmetros, que oferece suporte a imagens e textos em diversos idiomas amplamente utilizados. Ele utiliza uma arquitetura inédita para aproveitar conhecimento visual e conhecimento linguístico, melhorando o desempenho em ambas as tarefas e permitindo que o modelo se destaque na recuperação de imagens e, especialmente, na recuperação de documentos visuais. Isso significa que ele lida bem com imagens como gráficos, slides, mapas, capturas de tela, digitalizações de páginas e diagramas — tipos comuns de imagens que muitas vezes contêm texto incorporado importante e que ficam fora do escopo de modelos de visão computacional treinados apenas com imagens de cenas do mundo real.

Otimizamos esse modelo para diversas tarefas diferentes usando adaptadores compactos de Low-Rank Adaptation (LoRA). Isso nos permite treinar um único modelo para se especializar em múltiplas tarefas, sem comprometer o desempenho em nenhuma delas, com um custo adicional mínimo de memória ou processamento.

Os principais recursos incluem:

• Desempenho de ponta na recuperação de documentos visuais, além de suporte a texto multilíngue e imagens comuns com resultados que superam significativamente modelos muito maiores.
• Suporte a grandes tamanhos de contexto de entrada: 32.768 tokens equivalem aproximadamente a 80 páginas de texto em inglês com espaçamento duplo, e 20 megapixels equivalem a uma imagem de 4.500 × 4.500 pixels.
• Tamanhos de embedding selecionáveis pelo usuário, de um máximo de 2.048 dimensões até 128 dimensões. Constatamos empiricamente que o desempenho se degrada de forma acentuada abaixo desse limite.
• Suporte tanto a embeddings únicos quanto a embeddings multivetoriais. Para textos, a saída multivetorial consiste em um embedding de 128 dimensões para cada token de entrada. Para imagens, é gerado um embedding de 128 dimensões para cada bloco de 28 × 28 pixels necessário para cobrir a imagem.
• Otimização para recuperação assimétrica por meio de um par de adaptadores LoRA treinados especificamente para esse propósito.
• Um adaptador LoRA otimizado para cálculo de similaridade semântica.
• Suporte especial a linguagens de programação e estruturas de TI, também por meio de um adaptador LoRA.

Desenvolvemos jina-embeddings-v4 para atuar como uma ferramenta geral e multifuncional para uma ampla gama de tarefas comuns de busca, compreensão de linguagem natural e análise com IA. Apesar de ser relativamente pequeno considerando suas capacidades, ainda exige recursos significativos para implantação e é mais adequado para uso por meio de uma API em nuvem ou em ambientes de alto volume.

Jina embeddings v3

jina-embeddings-V3 é um modelo de embedding compacto, multilíngue, somente para texto, com alto desempenho e menos de 600 milhões de parâmetros. Ele oferece suporte a até 8.192 tokens de texto de entrada e gera embeddings de vetor único com tamanhos escolhidos pelo usuário, desde o padrão de 1.024 dimensões até 64.

Treinamos jina-embeddings-v3 para uma variedade de tarefas de texto — não apenas recuperação de informações e similaridade semântica, mas também tarefas de classificação, como análise de sentimento e moderação de conteúdo, além de tarefas de clusterização, como agregação de notícias e recomendação. Assim como jina-embeddings-v4, esse modelo oferece adaptadores LoRA especializados para as seguintes categorias de uso:

• Recuperação assimétrica
• Similaridade semântica
• Classificação
• Clustering

jina-embeddings-v3 é um modelo muito menor do que jina-embeddings-v4 com um tamanho de contexto de entrada significativamente reduzido, mas com custo operacional mais baixo. Ainda assim, apresenta desempenho bastante competitivo, embora apenas para textos, e é uma escolha melhor para muitos casos de uso.

Incorporações de código Jina

Os modelos especializados de embedding de código da Jina — jina-code-embeddings (0.5b e 1.5b) — oferecem suporte a 15 esquemas de programação e estruturas, além de textos em inglês relacionados a computação e tecnologia da informação. São modelos compactos, com meio bilhão (0,5 × 10⁹) e um bilhão e meio (1,5 × 10⁹) de parâmetros, respectivamente. Ambos oferecem suporte a tamanhos de contexto de entrada de até 32.768 tokens e permitem que os usuários escolham os tamanhos dos embeddings de saída, de 896 a 64 dimensões no modelo menor e de 1.536 a 128 no modelo maior.

Esses modelos oferecem suporte a recuperação assimétrica para cinco especializações específicas de tarefa, usando ajuste de prefixo em vez de adaptadores LoRA:

• Código para código. Recuperar código semelhante entre diferentes linguagens de programação. Isso é usado para alinhamento de código, deduplicação de código e suporte a portabilidade e refatoração.
• Linguagem natural para código. Recuperar código que corresponda a consultas em linguagem natural, comentários, descrições e documentação.
• Código para linguagem natural. Associar código a documentação ou a outros textos em linguagem natural.
• Conclusão de código para código. Sugerir código relevante para completar ou aprimorar código existente.
• Perguntas e respostas técnicas. Identificar respostas em linguagem natural para perguntas sobre tecnologias da informação, sendo ideal para casos de uso de suporte técnico.

Esses modelos oferecem performance superior em tarefas que envolvem documentação técnica e materiais de programação, com um custo computacional relativamente baixo. Eles são bem adequados para integração em ambientes de desenvolvimento e assistentes de código.

Jina ColBERT v2

jina-colbert-v2 é um modelo de embedding de texto multivetorial com 560 milhões de parâmetros. Ele é multilíngue, treinado com materiais em 89 idiomas, e oferece suporte a tamanhos variáveis de embedding e recuperação assimétrica.

Como observado anteriormente, embeddings multivetoriais não são adequados para indexação, mas são muito úteis para aumentar a precisão dos resultados de outras estratégias de busca. Com jina-colbert-v2, é possível calcular embeddings multivetoriais antecipadamente e usá-los para reclassificar candidatos à recuperação no momento da consulta. Essa abordagem é menos precisa do que usar um dos modelos de reclassificação descritos na próxima seção, mas é muito mais eficiente, pois envolve apenas a comparação de embeddings multivetoriais armazenados, em vez de invocar todo o modelo de IA para cada consulta e cada correspondência candidata. Ela é especialmente adequada para casos de uso em que a latência e a sobrecarga computacional dos modelos de reclassificação são excessivas ou em que o número de candidatos a comparar é grande demais para esse tipo de modelo.

Esse modelo gera uma sequência de embeddings, um por token de entrada, e os usuários podem selecionar embeddings de tokens com 128, 96 ou 64 dimensões. As correspondências de texto candidatas são limitadas a 8.192 tokens. As consultas são codificadas de forma assimétrica, portanto é necessário especificar se um texto é uma consulta ou uma correspondência candidata, além de limitar consultas a 32 tokens.

Jina CLIP v2

jina-clip-v2 é um modelo de embedding multimodal com 900 milhões de parâmetros, treinado para que textos e imagens gerem embeddings próximos entre si quando o texto descreve o conteúdo da imagem. Seu uso principal é a recuperação de imagens com base em consultas textuais, mas ele também é um modelo somente de texto com alto desempenho, reduzindo custos para os usuários, já que não é necessário manter modelos separados para recuperação de texto para texto e de texto para imagem.

Esse modelo oferece suporte a um contexto de entrada de texto de 8.192 tokens, e as imagens são redimensionadas para 512 × 512 pixels antes da geração dos embeddings.

Arquiteturas de pré-treinamento contrastivo de linguagem e imagem (CLIP) são fáceis de treinar e operar e podem gerar modelos muito compactos, mas apresentam algumas limitações fundamentais. Eles não conseguem usar conhecimento de um meio para melhorar seu desempenho em outro. Ou seja, não conseguem aproveitar informações de um meio para aprimorar o desempenho em outro. Assim, embora um modelo possa saber que as palavras “cão” e “gato” são mais próximas em significado entre si do que qualquer uma delas em relação a “carro”, ele não necessariamente saberá que a imagem de um cão e a imagem de um gato são mais relacionadas entre si do que qualquer uma delas em relação à imagem de um carro.

Esses modelos também sofrem do que se chama de lacuna de modalidade: um embedding de um texto sobre cães tende a ficar mais próximo de um embedding de um texto sobre gatos do que de um embedding de uma imagem de cães. Por causa dessa limitação, recomendamos usar CLIP como um modelo de recuperação de texto para imagem ou como um modelo somente de texto, mas não misturar os dois em uma única consulta.

Modelos de reclassificação

Modelos de reclassificação recebem como entrada uma consulta e uma ou mais correspondências candidatas e as comparam diretamente, produzindo correspondências com precisão muito maior.

Em princípio, seria possível usar um reclassificador diretamente para recuperação de informações, comparando cada consulta com cada documento armazenado, mas isso seria computacionalmente muito caro e impraticável para qualquer coleção que não seja muito pequena. Por isso, reclassificadores tendem a ser usados para avaliar listas relativamente curtas de correspondências candidatas encontradas por outros meios, como busca baseada em embeddings ou outros algoritmos de recuperação. Modelos de reclassificação são ideais para esquemas de busca híbrida e federada, nos quais executar uma busca pode significar enviar consultas a sistemas de busca separados, com conjuntos de dados distintos, cada um retornando resultados diferentes. Eles funcionam muito bem para combinar resultados diversos em um único resultado de alta qualidade.

A busca baseada em embeddings pode exigir um grande investimento, envolvendo a reindexação de todos os dados armazenados e a mudança das expectativas dos usuários em relação aos resultados. Adicionar um reclassificador a um esquema de busca existente pode trazer muitos dos benefícios da IA sem a necessidade de reestruturar toda a solução de busca.

Modelos de reclassificação Jina

Jina Reranker m0

jina-reranker-m0 é um reclassificador multimodal com 2,4 bilhões (2,4 × 10⁹) de parâmetros, que oferece suporte a consultas textuais e a correspondências candidatas compostas por textos e/ou imagens. Ele é o principal modelo para recuperação de documentos visuais, o que o torna uma solução ideal para repositórios de PDFs, digitalizações de texto, capturas de tela e outras imagens geradas ou modificadas por computador que contêm texto ou outras informações semiestruturadas, bem como para dados mistos compostos por documentos de texto e imagens.

Esse modelo recebe uma única consulta e uma correspondência candidata e retorna uma pontuação. Quando a mesma consulta é usada com diferentes candidatos, as pontuações são comparáveis e podem ser usadas para ranqueá-los. Ele oferece suporte a um tamanho total de entrada de até 10.240 tokens, incluindo o texto da consulta e o texto ou imagem candidata. Cada bloco de 28 × 28 pixels necessário para cobrir uma imagem conta como um token no cálculo do tamanho de entrada.

Jina Reranker v3

jina-reranker-v3 é um reclassificador de texto com 600 milhões de parâmetros, com desempenho de ponta entre modelos de tamanho comparável. Ao contrário de jina-reranker-m0, ele recebe uma única consulta e uma lista de até 64 correspondências candidatas e retorna a ordem de ranqueamento. Ele tem um contexto de entrada de 131.000 tokens, incluindo a consulta e todos os candidatos de texto.

Jina Reranker v2

jina-reranker-v2-base-multilingual é um reclassificador multifuncional, de uso geral, muito compacto, com recursos adicionais projetados para oferecer suporte a chamadas de função e consultas SQL. Com menos de 300 milhões de parâmetros, ele fornece reclassificação de texto multilíngue rápida, eficiente e precisa, com suporte adicional para selecionar tabelas SQL e funções externas que correspondam a consultas de texto, o que o torna adequado para casos de uso com IA agêntica.

Modelos de linguagem generativos de pequeno porte

Modelos de linguagem generativos são modelos como o ChatGPT da OpenAI, o Google Gemini e o Claude, da Anthropic, que recebem entradas em texto ou multimídia e respondem com saídas em texto. Não existe um limite bem definido que separe modelos de linguagem grandes (LLMs) de modelos de linguagem pequenos (SLMs), mas os desafios práticos de desenvolver, operar e usar LLMs de ponta são bem conhecidos. Os modelos mais conhecidos não são distribuídos publicamente, portanto só é possível estimar seu tamanho, mas espera-se que ChatGPT, Gemini e Claude estejam na faixa de 1 a 3 trilhões (1–3 × 10¹²) de parâmetros.

Executar esses modelos, mesmo quando estão disponíveis publicamente, está muito além do alcance de hardware convencional, exigindo os chips mais avançados organizados em grandes arranjos paralelos. É possível acessar LLMs por meio de APIs pagas, mas isso envolve custos significativos, alta latência e dificuldades para atender a exigências de proteção de dados, soberania digital e repatriação de nuvem. Além disso, os custos relacionados ao treinamento e à personalização de modelos desse porte podem ser consideráveis.

Consequentemente, uma grande quantidade de pesquisa tem se concentrado no desenvolvimento de modelos menores que, embora não tenham todas as capacidades dos maiores LLMs, conseguem executar tipos específicos de tarefas com a mesma qualidade, a um custo reduzido. Empresas normalmente implantam software para resolver problemas específicos, e com software de IA não é diferente; por isso, soluções baseadas em SLMs costumam ser preferíveis às baseadas em LLMs. Elas geralmente podem ser executadas em hardware comum, são mais rápidas, consomem menos energia e são muito mais fáceis de personalizar.

As ofertas de SLM da Jina estão crescendo à medida que nos concentramos em como levar IA da melhor forma possível a soluções práticas de busca.

Jina SLMs

ReaderLM v2

ReaderLM-v2 é um modelo de linguagem generativo que converte HTML em Markdown ou em JSON, de acordo com esquemas JSON fornecidos pelo usuário e instruções em linguagem natural.

O pré-processamento e a normalização de dados são uma parte essencial do desenvolvimento de boas soluções de busca para dados digitais, mas dados do mundo real, especialmente informações derivadas da web, costumam ser caóticos, e estratégias simples de conversão frequentemente se mostram frágeis. Em vez disso, ReaderLM-v2 oferece uma solução inteligente baseada em modelo de IA, capaz de entender o caos de um dump de árvore DOM de uma página da web e identificar, de forma robusta, elementos úteis.

Com 1,5 bilhão (1,5 × 10⁹) de parâmetros, esse modelo é três ordens de magnitude mais compacto do que LLMs de última geração, mas apresenta desempenho equivalente a eles nessa tarefa específica e bastante restrita.

Jina VLM

jina-VLC é um modelo de linguagem generativo com 2,4 bilhões (2,4 × 10⁹) de parâmetros, treinado para responder a perguntas em linguagem natural sobre imagens. Ele oferece suporte muito robusto a análise de documentos visuais, isto é, responder a perguntas sobre digitalizações, capturas de tela, slides, diagramas e dados de imagem semelhantes que não são naturais.

Por exemplo:

Ele também é muito eficiente na leitura de texto em imagens:

Mas é na compreensão do conteúdo de imagens informativas e produzidas pelo ser humano que jina-vlm realmente se destaca:

Ou:

jina-vlm é especialmente adequado para geração automática de legendas, descrições de produtos, texto alternativo de imagens e aplicações de acessibilidade para pessoas com deficiência visual. Além disso, cria novas possibilidades para sistemas de geração aumentada por recuperação (RAG) utilizarem informações visuais e para agentes de IA processarem imagens sem assistência humana.

O Elastic Agent Builder facilita a criação de agentes de IA conectados a dados. Mostraremos como fazer isso neste post do blog. Vamos passar por todos os passos necessários para criar um agente com uma ferramenta MCP que acesse os dados armazenados no Elastic. Depois, usaremos o Strands Agents SDK e os recursos Agent2Agent (A2A) para operar o agente. O Strands Agents SDK é uma plataforma de desenvolvimento de IA multiagente que você pode usar para criar apps agentes com código suficiente para garantir o resultado desejado.

Vamos construir um agente de IA que jogue RPS+, uma versão do clássico jogo Pedra, Papel e Tesoura com um diferencial: oferece aos jogadores algumas opções extras.

Pré-requisitos

Aqui está o que é necessário para seguir as etapas deste post do blog:

• Um editor de texto rodando no seu computador local
  • Visual Studio Code é o que usaremos para as instruções de exemplo neste post do blog
• Python 3.10 ou superior rodando no seu computador local

Crie um projeto serverless

A primeira coisa de que precisamos é de um projeto Elasticsearch Serverless, que inclua o Elastic Agent Builder.

Acesse cloud.elastic.co e crie um novo projeto Elasticsearch Serverless.

Crie um índice e adicione dados

Em seguida, adicionaremos alguns dados ao nosso projeto Elasticsearch. Abra as Ferramentas de desenvolvedor, onde podemos executar comandos para criar um novo índice e inserir alguns dados. Selecione Ferramentas de desenvolvedor no menu de navegação de nível superior.

Copie e cole o seguinte comando PUT na área de entrada de solicitações do console Ferramentas de desenvolvedor. Essa declaração cria um índice Elasticsearch chamado "game-docs".

PUT /game-docs
{
  "mappings": {
    "properties": {
      "title": { "type": "text" },
      "content": { 
        "type": "text"
      },
      "filename": { "type": "keyword" },
      "last_modified": { "type": "date" }
    }
  }
}

Clique no botão Enviar solicitação que aparece no lado direito da declaração em Ferramentas de desenvolvedor. Você deve ver uma notificação confirmando que o índice game-docs foi criado na área de resposta das Ferramentas de desenvolvedor.

Um índice chamado game-docs é um ótimo lugar para armazenar os dados do jogo que estamos criando. Vamos colocar um documento chamado rps+-md nesse índice que contém todos os dados que nosso jogo requer. Copie e cole o seguinte comando PUT no console Ferramentas de desenvolvedor.

PUT /game-docs/_doc/rps+-md
{
  "title": "Rock Paper Scissors +",
  "content": "
# Game Name
RPS+

# Starting Prompt
Let's play RPS+ !
---
What do you choose?

# Game Objects
1. Rock 🪨 👊
2. Paper 📜 🖐
3. Scissors ✄ ✌️
4. Light ☼ 👍
5. Dark Energy ☄ 🫱

# Judgement of Victory
* Rock beats Scissors
  * because rocks break scissors
* Paper beats Rock
  * because paper covers rock
* Scissors beat Paper
  * because scissors cut paper
* Rock beats Light
  * because you can build a rock structure to block out light
* Paper beats Light
  * because knowledge stored in files and paper books helps us understand light
* Light beats Dark Energy
  * because light enables humans to lighten up and laugh in the face of dark energy as it causes the eventual heat death of the universe
* Light beats Scissors
  * because light is needed to use scissors safely
* Dark Energy beats Rock
  * because dark energy rocks more than rocks. It rocks rocks and everything else in its expansion of the universe
* Dark Energy beats Paper
  * because humans, with their knowledge stored in files and paper books, can't explain dark energy 
* Scissors beat Dark Energy
  * because a human running with scissors is darker than dark energy

# Invalid Input
I was hoping for an worthy opponent
  - but alas it appears that time has past
  - but alas there's little time for your todo list when [todo:fix this] is so vast

# Cancel Game
The future belongs to the bold. Goodbye..
",
  "filename": "RPS+.md",
  "last_modified": "2025-11-25T12:00:00Z"
}

Clique no botão Enviar solicitação ao lado da declaração para executá-la e adicionar o documento rps+-md ao índice game-docs.

Agora devemos ter alguns dados para consultar e, com o Agent Builder, isso está mais simples do que nunca.

Selecione Agentes no menu de navegação principal.

Agora, é preciso perguntar ao Elastic AI Agent padrão: "Quais dados eu tenho?"

O Elastic AI Agent avalia os dados e retorna uma explicação concisa sobre os dados que possuímos.

Crie uma ferramenta

Ok, agora temos alguns dados no Elastic, vamos utilizá-los. O Agent Builder inclui suporte integrado para criar ferramentas MCP que ajudam os agentes a acessar os dados necessários para ter o contexto correto para a tarefa. Vamos criar uma ferramenta simples que recupere os dados do nosso jogo.

Clique no menu de ações do Agent Builder.

Selecione Ver todas as ferramentas nas opções do menu.

Clique + Nova Ferramenta.

No formulário Criar Ferramenta, selecione ES|QL. Selecione a ferramenta Tipo e insira os valores a seguir.

Para o ID da Ferramenta:

example.get_game_docs

Para Descrição:

Get RPS+ doc from Elasticsearch game-docs index.

Para Configuração, insira a seguinte consulta na área de texto Mecanismo de consulta ES|QL:

FROM game-docs | WHERE filename == "RPS+.md"

O formulário Criar ferramenta que você preencheu deve ter esta aparência: Clique em Salvar para criar a ferramenta.

Temos uma ferramenta nova no suporte de ferramentas. As ferramentas não devem ficar num suporte; elas devem ser usadas. Vamos criar um agente que possa usar nossa nova ferramenta personalizada.

Crie um agente e atribua uma ferramenta a ele.

Criar um agente é muito simples com o Agent Builder. Você só precisa digitar as instruções do agente com alguns detalhes. Vamos criar um agente agora.

Clique no botão Gerenciar agentes.

Clique + Novo agente.

Insira as informações a seguir no formulário Novo Agente.

Para o ID do Agente, insira o texto abaixo:

rps_plus_agent

Na área de texto de Instruções personalizadas, insira as seguintes instruções:

When prompted, if the prompt contains an integer, then select the corresponding numbered item in the list of "Game Objects" from your documents. Otherwise select a random game object. This is your chosen game object for a single round of the game.

# General Game Rules
* 2 players
    - the user: the person playing the game
    - you: the agent playing the game and serving as the game master
* Each player chooses a game object which will be compared and cause them to tie, win or lose.

# Start the game
1. This is the way each new game always starts. You make the first line of your response only the name of your chosen game object. 

2. The remainder of your response should be the "Starting Prompt" text from your documents and generate a list of "Game Objects" for the person playing the game to choose a game object from.  

# End of Game: The game ends in one of the following three outcomes:
1. Invalid Input: If the player responds with an invalid game object choice, respond with variations of the "Invalid Input" text from your documents and then end the game.

2. Tie: The game ends in a tie if the user chooses the same game object as your game object choice.

3. Win or Lose: The game winner is decided based on the "Judgement of Victory" conditions from your documents. Compare the user's game object choice and your game object choice and determine who chose the winning game object.

# Game conclusion
Respond with a declaration of the winner of the game by outputting the corresponding text in the "Judgement of Victory" section of your documents.

Para o Nome de exibição, insira o texto abaixo:

RPS+ Agent

Para a Descrição de exibição, insira o texto abaixo:

An agent that plays the game RPS+

Dê ao agente a ferramenta personalizada que criamos anteriormente, clicando na guia Ferramentas.

Selecione somente a ferramenta example.get_game_docs que criamos anteriormente.

Clique em Salvar para criar o novo agente.

Vamos testar nosso novo agente. Há um link prático para iniciar um bate-papo com qualquer agente da lista de agentes.

Basta digitar “iniciar jogo” e o jogo começará. Funciona!

O agente exibe a escolha de objeto de jogo na parte superior da resposta. Isso é útil porque podemos ver a escolha do agente e confirmar que o jogo está funcionando conforme o esperado. No entanto, saber a escolha do oponente antes de escolher não torna o jogo de Pedra, Papel e Tesoura muito divertido. Para aperfeiçoar e aprimorar o jogo até a forma final, podemos usar uma plataforma de orquestração de agentes que pode controlar agentes com código.

Agora é a hora do Strands Agents SDK.

Strands Agents SDK

Se você tem curiosidade em experimentar novas estruturas de desenvolvimento de agentes, então vale a pena dar uma chance ao Strands Agents SDK. O Strands Agents SDK foi lançado pela AWS (maio de 2025) como uma implementação open source em Python, e agora também existe uma versão em Typescript.

Começando com o Strands Agents SDK em Python

Preparem seus motores de programação, pois agora vamos percorrer o processo de clonagem e execução de um aplicativo de exemplo que usa Strands Agents para controlar o agente RPS+ por meio do protocolo A2A. Vamos criar uma versão aperfeiçoada do jogo RPS+ para que a escolha do agente seja revelada depois que você fizer a sua escolha, pois, afinal, é a adivinhação e o resultado surpreendente que tornam divertidos jogos como o Pedra, Papel e Tesoura.

No seu computador local, abra o Visual Studio Code e abra um novo terminal.

No terminal recém-aberto, execute o seguinte comando para clonar o repositório Elasticsearch Labs:

git clone https://github.com/elastic/elasticsearch-labs

Execute o seguinte cd comando para alterar o diretório para o diretório elasticsearch-labs:

cd elasticsearch-labs

Em seguida, execute o seguinte comando para abrir o repositório no Visual Studio Code:

code .

No Visual Studio File Explorer, expanda as pastas contenting-blog-content e agent-builder-a2a-strands-agents e abra o arquivo elastic_agent_builder_a2a_rps+.py. Veja a aparência do arquivo aberto no Visual Studio Code:

Aqui está o conteúdo de elastic_agent_builder_a2a_rps+.py que você deve ver no seu editor de texto:

import asyncio
from dotenv import load_dotenv
from uuid import uuid4
import httpx
import os
import random
from a2a.client import A2ACardResolver, ClientConfig, ClientFactory
from a2a.types import Message, Part, Role, TextPart

DEFAULT_TIMEOUT = 60  # set request timeout to 1 minute


def create_message(*, role: Role = Role.user, text: str, context_id=None) -> Message:
    return Message(
        kind="message",
        role="user",
        parts=[Part(TextPart(kind="text", text=text))],
        message_id=uuid4().hex,
        context_id=context_id,
    )


async def main():
    load_dotenv()
    a2a_agent_host = os.getenv("ES_AGENT_URL")
    a2a_agent_key = os.getenv("ES_API_KEY")
    custom_headers = {"Authorization": f"ApiKey {a2a_agent_key}"}

    async with httpx.AsyncClient(
        timeout=DEFAULT_TIMEOUT, headers=custom_headers
    ) as httpx_client:
        # Get agent card
        resolver = A2ACardResolver(httpx_client=httpx_client, base_url=a2a_agent_host)
        agent_card = await resolver.get_agent_card(
            relative_card_path="/rps_plus_agent.json"
        )
        # Create client using factory
        config = ClientConfig(
            httpx_client=httpx_client,
            streaming=True,
        )
        factory = ClientFactory(config)
        client = factory.create(agent_card)
        # Use the client to communicate with the agent
        print("\nSending 'start game' message to Elastic A2A agent...")
        random_game_object = random.randint(1, 5)
        msg = create_message(text=f"start with game object {random_game_object}")
        async for event in client.send_message(msg):
            if isinstance(event, Message):
                context_id = event.context_id
                response_complete = event.parts[0].root.text
                # Get agent choice from the first line of the response
                parsed_response = response_complete.split("\n", 1)
                agent_choice = parsed_response[0]
                print(parsed_response[1])
        # User choice sent for game results from the agent
        prompt = input("Your Choice  : ")
        msg = create_message(text=prompt, context_id=context_id)
        async for event in client.send_message(msg):
            if isinstance(event, Message):
                print(f"Agent Choice : {agent_choice}")
                print(event.parts[0].root.text)


if __name__ == "__main__":
    asyncio.run(main())

Vamos revisar o que está acontecendo nesse código. Começando pelo método main(), o código começa acessando as variáveis de ambiente para a URL do agente e a Chave da API. Depois, usamos esses valores para criar um httpx client que podemos usar para obter o cartão de agente para o agente. O cliente então usa os detalhes do cartão do agente para enviar uma solicitação "iniciar jogo" ao agente. Uma coisa interessante a notar aqui é que incluímos um valor random_game_object como parte do pedido "start game". Esse valor é um número aleatório gerado com o módulo aleatório da biblioteca padrão do Python. A razão para fazer isso é que os poderosos LLMs (que possibilitam agentes de IA) não são bons em aleatoriedade. Não tema, Python vem pra salvar.

Continuando com o código, quando o agente responde à solicitação "iniciar jogo", o código remove a seleção de objeto de jogo do agente e a salva na variável agent_choice. O restante da resposta é exibido como texto para o usuário final. Em seguida, o usuário é solicitado a fornecer a entrada da sua escolha de objeto de jogo, que é enviada ao agente. O código então exibe a escolha do objeto de jogo do agente junto com a determinação final do agente sobre o resultado do jogo.

Definindo a URL do seu agente e a chave de API como variáveis de ambiente

Como o app de exemplo estará rodando no seu computador local, para nos comunicarmos com nosso agente Agent Builder, precisamos fornecer ao Strands Agents SDK uma URL A2A e uma chave API para o agente. O exemplo de app usa um arquivo chamado .env para armazenar esses valores.

Faça uma cópia do arquivo env.example e nomeie o novo arquivo como .env

Volte para o Elastic Agent Builder, onde podemos obter os dois valores que precisamos.

Selecione Exibir todas as ferramentas no menu de ação do Agent Builder no canto superior direito da página.

Clique no menu suspenso Servidor MCP na parte superior da página Ferramentas e selecione Copiar URL do Servidor MCP.

Cole o URL do servidor MCP no arquivo .env como um substituto para o valor do espaço reservado <YOUR-ELASTIC-AGENT-BUILDER-URL> . Agora precisamos fazer uma atualização no URL, ou seja, substituir o texto final “mcp” por “a2a”, pois o protocolo A2A é o que o Agent Strands SDK usará para se comunicar com o agente em execução no Elastic Agent Builder.

A URL editada deve ficar assim:

https://rps-game-project-12345a.kb.us-east-1.aws.elastic.cloud/api/agent_builder/a2a

Outro valor que precisamos obter enquanto estamos aqui no Elastic Cloud é uma chave API. Clique em Elasticsearch na navegação de nível superior.

Clique no botão Copiar chave API para copiar a chave API.

Agora, de volta ao Visual Studio Code, cole a chave API no .env para substituir o texto provisório <YOUR-ELASTIC-API-KEY> . Seu arquivo .env deve ficar assim:

Execute o app de exemplo

Abra um novo terminal no Visual Studio Code.

Comece executando o seguinte comando cd no terminal:

cd elasticsearch-labs/supporting-blog-content/agent-builder-a2a-strands-agents

Execute o seguinte comando para criar um ambiente virtual Python.

python -m venv .venv

Dependendo do sistema operacional do seu computador local, execute o seguinte comando para ativar o ambiente virtual.

• MacOS/Linux

source .venv/bin/activate

• Windows

.venv\Scripts\activate

O app de exemplo usa o Strands Agents SDK e agora estamos no ponto em que precisamos instalá-lo. Execute o seguinte comando para instalar o Strands Agents SDK junto com todas as dependências necessárias da biblioteca Python.

pip install -r requirements.txt

Hora de liberar a plataforma de lançamento e começar a contagem regressiva. Estamos prontos para executar este app. Afastem-se. Vamos executá-lo usando o seguinte comando:

python elastic_agent_builder_a2a_rps+.py

Você deve ser desafiado com uma partida de RPS+. Parabéns e boa sorte!

Crie seus aplicativos de IA com contexto relevante

Construir um Agente de IA agora é uma habilidade disponível na sua caixa de ferramentas. E você já viu como é fácil usar agentes Elastic Agent Builder via A2A em frameworks de desenvolvimento de agentes como o Strands Agents SDK. Experimente a Elastic para criar agentes de IA conectados ao contexto relevante em seus dados personalizados.

Recentemente, contribuímos para o projeto open source Google MCP Toolbox for Databases, adicionando suporte ao Elasticsearch como banco de dados.

Com esse novo recurso, agora você pode usar o Google MCP Toolbox para se conectar ao Elasticsearch e "conversar" diretamente com seus dados.

Elasticsearch

Precisamos ter uma instância do Elasticsearch em execução. Você pode ativar uma avaliação gratuita no Elastic Cloud ou instalá-lo localmente usando o script start-local:

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

Isso instalará o Elasticsearch e o Kibana no seu computador e gerará uma chave API para ser usada na configuração do Google MCP Toolbox.

A chave API será mostrada como saída do comando anterior e armazenada em um arquivo .env na pasta elastic-start-local.

Instale o conjunto de dados de exemplo

Após a instalação, você pode fazer login no Kibana usando o nome do usuário elastic e a senha gerada pelo script start-local (armazenada em um arquivo .env).

Você pode instalar o conjunto de dados de pedidos de comércio eletrônico disponível no Kibana. Inclui um único índice chamado kibana_sample_data_ecommerce contendo informações sobre 4.675 pedidos de um website de comércio eletrônico. Para cada pedido, temos as seguintes informações:

• Informações do cliente (nome, ID, data de nascimento, e-mail, etc.)
• Data do pedido
• ID do pedido
• Produtos (lista de todos os produtos com preço, quantidade, ID, categoria, desconto, etc.)
• SKU
• Preço total (sem impostos, com impostos)
• Quantidade total
• Informações geográficas (cidade, país, continente, localização, região)

Para instalar os dados de exemplo, abra a página Integrações no Kibana (busque por “Integração” na barra de busca superior) e instale os “Dados de Exemplo”. Confira os detalhes na documentação aqui: https://www.elastic.co/docs/explore-analyze/#gs-get-data-into-kibana.

O objetivo deste artigo é mostrar como é fácil configurar o Google MCP Toolbox para se conectar ao Elasticsearch e interagir com o índice kibana_sample_data_ecommerce usando linguagem natural.

Google MCP Toolbox

O Google MCP Toolbox é um servidor MCP open source projetado para facilitar a interação de aplicações e agentes de IA com bancos de dados de forma segura e eficiente. Antes chamado de "GenAI Toolbox for Databases", o projeto foi renomeado após adotar total compatibilidade com o Protocolo de Contexto de Modelo (MCP). Seu objetivo é eliminar o trabalho pesado tradicionalmente exigido ao conectar agentes a bancos de dados, lidando com agrupamento de conexões, autenticação, observabilidade e outras preocupações operacionais nos bastidores.

Essencialmente, o Toolbox permite que desenvolvedores definam ferramentas reutilizáveis e de alto nível que encapsulam interações com bancos de dados. Essas ferramentas podem então ser invocadas por qualquer cliente que cumpra o MCP — como um agente de IA — sem exigir que o cliente implemente consultas SQL de baixo nível ou gerencie conexões de banco de dados. Essa abordagem reduz drasticamente a quantidade de código padrão necessário para construir agentes conscientes de banco de dados, tornando possível integrar operações avançadas de dados em apenas algumas linhas de lógica de aplicação. Uma vez definida uma ferramenta, ela pode ser compartilhada entre vários agentes, frameworks ou linguagens (Figura 1).

Uma grande vantagem de usar o Toolbox é o modelo de segurança integrado. Fluxos de autenticação, como OAuth2 e OIDC, são aceitos de forma nativa, permitindo que os desenvolvedores evitem manipular ou armazenar credenciais confidenciais de bancos de dados em agentes. A plataforma também fornece recursos de observabilidade, incluindo métricas e rastreamento, no OpenTelemetry, que é essencial para depuração, monitoramento e implantações de produção. No geral, o MCP Toolbox serve como uma interface unificada, segura e extensível para interagir com seus dados de qualquer sistema habilitado pelo MCP.

Como instalar o MCP Toolbox

Você pode instalar o servidor MCP Toolbox no Linux usando o seguinte comando:

export VERSION=0.21.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

Para instalá-lo no macOS ou Windows, siga as instruções detalhadas aqui.

Configure o Toolbox para Elasticsearch

Para configurar o MCP Toolbox para Elasticsearch, precisamos criar um arquivo tools.yaml , conforme segue:

sources:
  my-cluster:
    kind: elasticsearch
    addresses:
      - http://localhost:9200
    apikey: 

tools:
  customer-orders:
    kind: elasticsearch-esql
    source: my-cluster
    description: Get the orders made by a customer identified by name.
    query: |
    	FROM kibana_sample_data_ecommerce | WHERE MATCH(customer_full_name, ?name, {"operator": "AND"})
    parameters:
      - name: name
        type: string
        description: The customer name.

toolsets:
  elasticsearch-tools:
    - customer-orders

Você precisa trocar o valor <insert-here-api-key> por uma chave API válida do Elasticsearch. Se você estiver rodando o Elasticsearch localmente usando o start-local, pode encontrar a chave API no arquivo .env gerado pelo start-local, sob a variável ES_LOCAL_API_KEY . Se você estiver usando o Elastic Cloud, poderá gerar uma chave de API seguindo o procedimento descrito aqui.

As ferramentas anteriores contêm a seguinte consulta ES|QL para Elasticsearch:

FROM kibana_sample_data_ecommerce | WHERE MATCH(customer_full_name, ?name)

Se você não conhece o ES|QL, é uma linguagem de consulta desenvolvida pela Elastic, semelhante ao SQL, que pode ser usada para buscar em um ou mais índices. Saiba mais sobre ES|QL na documentação oficial aqui.

A consulta acima busca todos os pedidos armazenados no índice kibana_sample_data_ecommerce que contêm o nome do cliente especificado, usando o parâmetro ?name (o ponto de interrogação indica um parâmetro).

O nome do cliente é definido na configuração YAML anterior usando a string de tipo e a descrição "O nome do cliente".

Essa ferramenta pode ser usada para responder a perguntas sobre os pedidos de um cliente - por exemplo: Quantos pedidos o cliente Foo fez em outubro de 2025?

As descrições das ferramentas e seus parâmetros são essenciais para extrair as informações relevantes da solicitação em linguagem natural do usuário. Essa extração é realizada usando o recurso de chamada de função de um modelo de linguagem grande (LLM). Na prática, um LLM pode determinar qual função (ferramenta) precisa ser executada para obter as informações necessárias, juntamente com os parâmetros apropriados para essa função.

Para saber mais sobre chamadas de função, sugerimos o artigo Chamadas de função do OpenAI com Elasticsearch, de Ashish Tiwari.

Execute o servidor Toolbox

Você pode executar o MCP Toolbox usando o arquivo tools.yaml anterior com o seguinte comando:

./toolbox --tools-file tools.yaml --ui

O parâmetro –ui executa uma aplicação web em http://127.0.0.1:5000/ui (Figura 2).

Você pode selecionar Ferramentas > customer-orders e inserir o nome do cliente no campo Nome do parâmetro (por exemplo, Gwen Sanders) e clicar no botão Executar. Você deve ver uma resposta JSON conforme a Figura 3.

A configuração está concluída, e o MCP Toolbox pode executar a ferramenta customer-orders para se comunicar com o Elasticsearch, rodando o ES|QL.

Usando o MCP Toolbox com Gemini CLI

Podemos usar qualquer cliente MCP para nos comunicar com o MCP Toolbox for Databases. Por exemplo, podemos usar o Gemini CLI, uma ferramenta de linha de comando, para usar o Gemini. Você pode instalar o Gemini CLI seguindo as instruções descritas aqui.

Gemini CLI oferece uma extensão pré-configurada para MCP Toolbox, disponível em gemini-cli-extensions/mcp-toolbox. Você pode instalar esta extensão executando o seguinte comando:

gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

Após a instalação, você precisa ir para o diretório em que armazenou o arquivo de configuração tools.yaml do MCP Toolbox e executar a CLI do Gemini da seguinte forma (essa etapa é necessária para que a CLI do Gemini seja configurada automaticamente com o MCP Toolbox):

gemini

Você deve ver uma saída conforme a Figura 4.

Você pode verificar se a MCP Toolbox está conectada usando o seguinte comando:

/mcp list

Você deve ver a mcp_toolbox com as ferramentas de pedidos de clientes listadas (Figura 5).

Se o MCP Toolbox estiver conectado à interface de comando Gemini, agora podemos tentar fazer algumas perguntas, como: "Me dê os pedidos da cliente Gwen Sanders." A CLI Gemini então solicitará permissão para executar a ferramenta de pedidos do cliente ao servidor mcp_toolbox (veja a Figura 6).

Após a confirmação, a CLI Gemini executará a solicitação para a MCP Toolbox, recebendo uma resposta JSON como resultado e usando para formatar a resposta (Figura 7).

A resposta da Gemini CLI emitirá um relatório indicando que Gewn Sanders fez apenas um pedido de 2 produtos, totalizando 132 euros.

SDKs do MCP Toolbox

O Google MCP Toolbox também oferece um SDK para acessar todas as funcionalidades de um programa escrito em Go, Python e Javascript.

Por exemplo, o Python SDK está disponível no Github na seguinte página: https://github.com/googleapis/mcp-toolbox-sdk-python.

Precisamos criar um agente simples para conectar à MCP Toolbox. Precisamos instalar os seguintes pacotes:

pip install toolbox-core
pip install google-adk

E crie um novo projeto de agente usando o comando a seguir:

adk create my_agent

Isso criará um novo diretório chamado my_agent com um arquivo agent.py.

Atualize my_agent/agent.py com o seguinte conteúdo para conectar ao Toolbox:

from google.adk import Agent
from google.adk.apps import App
from toolbox_core import ToolboxSyncClient

client = ToolboxSyncClient("http://127.0.0.1:5000")

root_agent = Agent(
    name='root_agent',
    model='gemini-2.5-flash',
    instruction="You are a helpful AI assistant designed to search information about a dataset of ecommerce orders.",
    tools=client.load_toolset(),
)

app = App(root_agent=root_agent, name="my_agent")

Crie um arquivo .env com sua chave API do Google:

echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > my_agent/.env

Por fim, podemos executar o agente e observar os resultados. Para executar o agente, você pode executar o seguinte comando:

adk run my_agent

Ou pode servi-lo por meio de uma interface web:

adk web --port 8000

Em ambos os casos, você pode interagir com a MCP Toolbox usando uma interface de perguntas e respostas. Por exemplo, você pode fazer a pergunta anterior: Me dê os pedidos da cliente Gwen Sanders.

Para saber mais sobre os diferentes SDKs, consulte esta página de documentação.

Conclusão

Neste artigo, demonstramos a integração com o Elasticsearch para o Google MCP Toolbox for Databases. Usando um arquivo de configuração YAML simples, podemos definir um conjunto de ferramentas que traduzem perguntas de linguagem natural em consultas do Elasticsearch usando a linguagem ES|QL.

Mostramos como interagir com os conjuntos de dados kibana_sample_data_ecommerce, que contém pedidos de um website de e-commerce. Com esse arquivo de configuração, basta executar o servidor MCP Toolbox e conectar a ele a partir de qualquer cliente MCP.

Por fim, demonstramos como usar o Gemini CLI como cliente para conectar-se ao MCP Toolbox for Databases e consultar os dados de comércio eletrônico armazenados no Elasticsearch. Executamos uma consulta em linguagem natural para obter informações sobre pedidos de um cliente específico identificado pelo nome.

À medida que o ecossistema MCP continua crescendo, esse padrão — definições leves de ferramentas apoiadas por uma infraestrutura segura e pronta para produção — gera novas oportunidades para criar agentes cada vez mais capazes e com reconhecimento de dados com o mínimo esforço. Seja experimentando localmente com os conjuntos de dados de amostra da Elastic ou integrando capacidades de buscar em uma aplicação maior, o MCP Toolbox tem uma base confiável e extensível para interagir com os dados do Elasticsearch usando linguagem natural.

Para saber mais sobre o desenvolvimento de aplicações de IA agêntica, leia o artigo Criando fluxos de trabalho de IA agêntica com Elasticsearch, de Anish Mathur e Dana Juratoni.

Para saber mais informações sobre o Google MCP Toolbox, visite https://googleapis.github.io/genai-toolbox/getting-started/introduction/.

No entanto, quando você resolve esse problema, acaba com outras consultas porque não pôde testar todos os casos manualmente. Mas como você ou sua equipe de QA podem testar se uma mudança em uma consulta tem efeito dominó em outras? Ou, mais importante ainda, como você pode ter certeza de que suas mudanças realmente melhoraram uma consulta?

Rumo a uma avaliação sistemática

É aqui que as listas de julgamento se tornam úteis. Em vez de depender de testes manuais e subjetivos toda vez que você faz uma alteração, você pode definir um conjunto fixo de consultas relevantes para seu caso de negócio, juntamente com os resultados relevantes.

Esse conjunto se torna sua referência. Toda vez que você implementa uma mudança, você a usa para avaliar se você buscou uma melhoria ou não.

O valor dessa abordagem é:

• Elimina a incerteza: você não precisa mais se perguntar se suas alterações afetam outras consultas; os dados dirão isso a você.
• Interrompe os testes manuais: assim que os conjuntos de julgamento são registrados, o teste é automático.
• Dá suporte à mudanças: você pode apresentar métricas claras que sustentam os benefícios de uma mudança.

Como começar a construir sua lista de julgamentos

Uma das formas mais fáceis de começar é pegar uma consulta representativa e selecionar manualmente os documentos relevantes. Existem duas maneiras de fazer esta lista:

• Julgamentos binários: cada documento associado a uma consulta recebe uma marcação simples: relevante (geralmente com uma pontuação de “1”) e não-relevante (“0”).
• Julgamentos graduados: aqui, cada documento recebe uma pontuação com diferentes níveis. Por exemplo: definir uma escala de 0 a 4, semelhante à Escala Likert, onde 0 = "nada relevante" e 4 = "totalmente relevante", com variações como "relevante", "um pouco relevante" etc.

Julgamentos binários funcionam bem quando a intenção de buscar tem limites claros: esse documento deve estar nos resultados ou não?

Julgamentos graduados são mais úteis quando há áreas cinzentas: alguns resultados são melhores que outros, então você pode ter resultados "muito bons", "bons" e "inúteis" e usar métricas que valorizam a ordem dos resultados e o feedback do usuário. No entanto, as escalas graduadas também introduzem desvantagens: diferentes avaliadores podem usar os níveis de pontuação de maneira diferente, o que torna os julgamentos menos consistentes. E porque as métricas graduadas dão mais peso às pontuações mais altas, mesmo uma pequena mudança (como classificar algo com 3 em vez de 4) pode criar uma mudança muito maior na métrica do que o avaliador pretendia. Essa subjetividade adicional torna os julgamentos graduados mais complicados e difíceis de gerenciar ao longo do tempo.

Preciso classificar os documentos eu mesmo?

Não necessariamente, pois existem diferentes maneiras de criar sua lista de julgamentos, cada uma com suas próprias vantagens e desvantagens:

• Julgamentos explícitos: aqui, os SMEs analisam cada consulta/documento e decidem manualmente se é relevante e qual a dimensão da relevância. Embora isso ofereça qualidade e controle, tem menos escalabilidade.
• Julgamentos implícitos: com esse método, você infere os documentos relevantes com base no comportamento real dos usuários, como cliques, taxa de rejeição e compras, entre outros. Essa abordagem permite coletar dados automaticamente, mas pode ser tendenciosa. Por exemplo, os usuários tendem a clicar mais vezes nos resultados principais, mesmo que não sejam relevantes.
• Julgamentos gerados por IA: essa última opção utiliza modelos (como LLMs) para avaliar automaticamente consultas e documentos, chamados LLM como juiz. É rápido e fácil de redimensionar, mas a qualidade dos dados depende da qualidade do modelo que você está usando e de como os dados de treinamento do LLM se alinham aos seus interesses comerciais. Assim como acontece com as notas humanas, os LLMs como juiz podem apresentar os próprios preconceitos ou inconsistências, por isso é importante validar o resultado em relação a um conjunto menor de julgamentos confiáveis. Modelos LLM são probabilísticos por natureza, então não é incomum ver um modelo LLM dando diferentes graus ao mesmo resultado, independentemente de definir o parâmetro de temperatura como 0.

A seguir, apresentamos algumas recomendações para escolher o melhor método para criar seu conjunto de julgamentos:

• Decida a importância de alguns recursos que somente os usuários possam avaliar de forma adequada (como preço, marca, idioma, estilo e detalhes do produto). Se eles forem importantes, você precisará de julgamentos explícitos para pelo menos uma parte da sua lista de julgamentos.
• Use julgamentos implícitos quando seu mecanismo de busca já tiver tráfego suficiente para que você possa usar cliques, conversões e métricas de tempo persistentes para detectar tendências de uso. Você ainda deve interpretá-los com cuidado, comparando-os com seus conjuntos de julgamento explícitos para evitar qualquer viés (por exemplo: os usuários tendem a clicar nos resultados mais bem classificados com mais frequência, mesmo que os resultados com classificação inferior sejam mais relevantes)

Para resolver isso, técnicas de posicionamento de debiasing ajustam ou reponderam os dados de cliques para refletir melhor o verdadeiro interesse do usuário. Algumas abordagens incluem:

• Reorganização de resultados: altere a ordem dos resultados de busca para um subconjunto de usuários a fim de estimar como a posição afeta os cliques.
• Os modelos de clique incluem Rede bayesiana dinâmica DBN, Modelo de Navegação do Usuário UBM. Esses modelos estatísticos estimam que a probabilidade de um clique reflete o interesse real em vez de apenas posição, usando padrões como rolagem, tempo de espera, sequência de cliques e retorno à página de resultados.

Exemplo: app de avaliação de filmes

Pré-requisitos

Para executar este exemplo, você precisa de um cluster Elasticsearch 8.x em execução, localmente ou no Elastic Cloud (hospedado ou sem servidor), e acesso à REST API ou ao Kibana.

Pense em um app no qual os usuários possam carregar as opiniões sobre filmes e também buscar filmes para assistir. Como os textos são escritos pelos próprios usuários, eles podem ter erros de digitação e muitas variações em termos de expressão. Portanto, é fundamental que o mecanismo de busca seja capaz de interpretar essa diversidade e fornecer resultados úteis para os usuários.

Para poder iterar consultas sem impactar o comportamento geral de busca, a equipe de negócios da sua empresa criou o seguinte conjunto de julgamento binário, baseado nas buscas mais frequentes:

Criando o índice:

PUT movies
{
  "mappings": {
    "properties": {
      "text": {
        "type": "text"
      }
    }
  }
}

SOLICITAÇÃO em massa:

POST /movies/_bulk
{ "index": { "_id": "doc1" } }
{ "text": "DiCaprio performance in The Revenant was breathtaking." }
{ "index": { "_id": "doc2" } }
{ "text": "Inception shows Leonardo DiCaprio in one of his most iconic roles." }
{ "index": { "_id": "doc3" } }
{ "text": "Brad Pitt delivers a solid performance in this crime thriller." }
{ "index": { "_id": "doc4" } }
{ "text": "An action-packed adventure with stunning visual effects." }
{ "index": { "_id": "doc5" } }
{ "text": "A heartbreaking story of love and loss that made me cry for hours." }
{ "index": { "_id": "doc6" } }
{ "text": "One of the saddest movies ever made -- bring tissues!" }
{ "index": { "_id": "doc7" } }
{ "text": "A lighthearted comedy that will make you laugh." }
{ "index": { "_id": "doc8" } }
{ "text": "A science-fiction epic full of action and excitement." }

Abaixo está a consulta Elasticsearch que o aplicativo está usando:

GET movies/_search
{
 "query": {
   "match": {
     "text": {
       "query": "DiCaprio performance",
       "minimum_should_match": "100%"
     }
   }
 }
}

Do julgamento às métricas

Sozinho, as listas de julgamento não fornecem muitas informações; eles são apenas uma expectativa dos resultados das nossas consultas. O momento importante deles é quando os usamos para calcular métricas objetivas para medir nosso desempenho na busca.

Hoje em dia, a maioria das métricas populares inclui

• Precisão: mede a proporção de resultados relevantes em todos os resultados de busca.
• Recall: mede a proporção de resultados relevantes que o mecanismo de busca encontrou entre x resultados.
• Ganho cumulativo descontado (DCG): mede a qualidade do ranking do resultado, considerando que os resultados mais relevantes devem estar no topo.
• Classificação Recíproca Média (MRR): mede a posição do primeiro resultado relevante. Quanto mais alto na lista, maior a pontuação.

Usando o mesmo app de avaliação de filmes como exemplo, calcularemos a métrica de recordação para ver se há alguma informação que está sendo omitida em nossas consultas.

No Elasticsearch, podemos usar as listas de julgamentos para calcular métricas via API de avaliação de classificação. Essa API recebe como entrada a lista de julgamentos, a consulta e a métrica que você deseja avaliar e retorna um valor, que é uma comparação do resultado da consulta com a lista de julgamentos.

Vamos executar a lista de julgamento para as duas consultas que temos:

POST /movies/_rank_eval
{
 "requests": [
   {
     "id": "dicaprio-performance",
     "request": {
       "query": {
         "match": {
           "text": {
             "query": "DiCaprio performance",
             "minimum_should_match": "100%"
           }
         }
       }
     },
     "ratings": [
       {
         "_index": "movies",
         "_id": "doc1",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc2",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc3",
         "rating": 0
       },
       {
         "_index": "movies",
         "_id": "doc4",
         "rating": 0
       }
     ]
   },
   {
     "id": "sad-movies",
     "request": {
       "query": {
         "match": {
           "text": {
             "query": "sad movies that make you cry",
             "minimum_should_match": "100%"
           }
         }
       }
     },
     "ratings": [
       {
         "_index": "movies",
         "_id": "doc5",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc6",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc7",
         "rating": 0
       },
       {
         "_index": "movies",
         "_id": "doc8",
         "rating": 0
       }
     ]
   }
 ],
 "metric": {
   "recall": {
     "k": 10,
     "relevant_rating_threshold": 1
     }
 }
}

Vamos usar dois pedidos para _rank_eval: um para a consulta do DiCaprio e outro para filmes tristes. Cada solicitação inclui uma consulta e a lista de julgamento (avaliações). Não precisamos classificar todos os documentos, pois aqueles que não estão incluídos nas classificações são considerados sem julgamento. Para realizar os cálculos, o sistema considera apenas o "conjunto relevante", ou seja, os documentos que são considerados relevantes na avaliação.

Nesse caso, a consulta do DiCaprio tem resultado de 1, enquanto os filmes tristes receberam 0 resultados. Isso significa que na primeira consulta, conseguimos obter todos os resultados relevantes, enquanto na segunda consulta, não obtivemos nenhum resultado. Portanto, a média de recall é de 0,5.

{
 "metric_score": 0.5,
 "details": {
   "dicaprio-performance": {
     "metric_score": 1,
     "unrated_docs": [],
     "hits": [
       {
         "hit": {
           "_index": "movies",
           "_id": "doc1",
           "_score": 2.4826927
         },
         "rating": 1
       },
       {
         "hit": {
           "_index": "movies",
           "_id": "doc2",
           "_score": 2.0780432
         },
         "rating": 1
       }
     ],
     "metric_details": {
       "recall": {
         "relevant_docs_retrieved": 2,
         "relevant_docs": 2
       }
     }
   },
   "sad-movies": {
     "metric_score": 0,
     "unrated_docs": [],
     "hits": [],
     "metric_details": {
       "recall": {
         "relevant_docs_retrieved": 0,
         "relevant_docs": 2
       }
     }
   }
 },
 "failures": {}
}

Talvez estejamos sendo muito rigorosos com o parâmetro minimum_should_match , já que ao exigir que 100% das palavras da consulta estejam nos documentos, provavelmente estamos deixando de fora os resultados relevantes. Vamos remover o parâmetro minimum_should_match para que um documento seja considerado relevante se apenas uma palavra na consulta seja encontrada nele.

POST /movies/_rank_eval
{
 "requests": [
   {
     "id": "dicaprio-performance",
     "request": {
       "query": {
         "match": {
           "text": {
             "query": "DiCaprio performance"
           }
         }
       }
     },
     "ratings": [
       {
         "_index": "movies",
         "_id": "doc1",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc2",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc3",
         "rating": 0
       },
       {
         "_index": "movies",
         "_id": "doc4",
         "rating": 0
       }
     ]
   },
   {
     "id": "sad-movies",
     "request": {
       "query": {
         "match": {
           "text": {
             "query": "sad movies that make you cry"
           }
         }
       }
     },
     "ratings": [
       {
         "_index": "movies",
         "_id": "doc5",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc6",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc7",
         "rating": 0
       },
       {
         "_index": "movies",
         "_id": "doc8",
         "rating": 0
       }
     ]
   }
 ],
 "metric": {
   "recall": {
     "k": 10,
     "relevant_rating_threshold": 1
     }
 }
}

Como você pode ver, ao remover o parâmetro minimum_should_match em uma das duas consultas, agora obtemos uma taxa de acerto média de 1 em ambas.

{
  "metric_score": 1,
  "details": {
    "dicaprio-performance": {
      "metric_score": 1,
      "unrated_docs": [],
      "hits": [
        {
          "hit": {
            "_index": "movies",
            "_id": "doc1",
            "_score": 2.0661702
          },
          "rating": 1
        },
        {
          "hit": {
            "_index": "movies",
            "_id": "doc3",
            "_score": 0.732218
          },
          "rating": 0
        },
        {
          "hit": {
            "_index": "movies",
            "_id": "doc2",
            "_score": 0.6271719
          },
          "rating": 1
        }
      ],
      "metric_details": {
        "recall": {
          "relevant_docs_retrieved": 2,
          "relevant_docs": 2
        }
      }
    },
    "sad-movies": {
      "metric_score": 1,
      "unrated_docs": [],
      "hits": [
        {
          "hit": {
            "_index": "movies",
            "_id": "doc7",
            "_score": 2.1307156
          },
          "rating": 0
        },
        {
          "hit": {
            "_index": "movies",
            "_id": "doc5",
            "_score": 1.3160692
          },
          "rating": 1
        },
        {
          "hit": {
            "_index": "movies",
            "_id": "doc6",
            "_score": 1.190063
          },
          "rating": 1
        }
      ],
      "metric_details": {
        "recall": {
          "relevant_docs_retrieved": 2,
          "relevant_docs": 2
        }
      }
    }
  },
  "failures": {}
}

Em resumo, remover a cláusula minimum_should_match: 100% nos permite ter um recall perfeito para ambas as consultas.

Conseguimos! Certo?

Não tão depressa!

Ao melhorar o recall, abrimos as portas para uma gama maior de resultados. No entanto, cada ajuste implica uma contrapartida. É por isso que definimos casos de teste completos, usando diferentes métricas para avaliar as mudanças.

Usar listas de julgamento e métricas evita que você fique às cegas ao fazer alterações, pois agora você tem dados para respaldá-las. A validação não é mais manual e repetitiva, e você pode testar as mudanças em mais de um caso de uso. Além disso, o teste A/B permite que você teste ao vivo qual configuração funciona melhor para seus usuários e seu caso de negócios, completando assim as métricas técnicas e as métricas do mundo real.

Recomendações finais para o uso de listas de julgamento

Trabalhar com listas de julgamento não é apenas medir, mas também criar um framework que permita iterar com confiança. Para atingir isso, você pode seguir estas recomendações:

1. Comece pequeno, mas comece de algum lugar. Você não precisa ter 10.000 consultas com 50 listas de julgamento cada. Você só precisa identificar de 5 a 10 consultas mais importantes para seu case de negócios e definir quais documentos espera ver no topo dos resultados. Isso já te dá uma base. Normalmente, você quer começar com as principais consultas mais as que não obtiveram resultados. Você também pode começar a testar com uma métrica fácil de configurar, como Precision, e depois ir aumentando a complexidade.
2. Validar com os usuários. Complemente os números com testes A/B em produção. Dessa forma, você saberá se mudanças que parecem boas nas métricas também estão gerando um impacto real.
3. Mantenha a lista atualizada. Seu caso de negócio vai evoluir, assim como suas consultas importantes. Atualize seu julgamento periodicamente para refletir novas necessidades.
4. Faça disso parte do fluxo. Integre listas de julgamento aos seus pipelines de desenvolvimento. Certifique-se de que cada alteração de configuração, sinônimo ou análise de texto seja automaticamente validada em relação à sua lista base.
5. Conecte conhecimento técnico com estratégia. Não se limite a medir métricas técnicas como a precisão ou o recall. Use os resultados da sua avaliação para informar os resultados do negócio.

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.

O que são controles de variáveis?

Se você já usou dashboards do Kibana, provavelmente conhece nossos controles clássicos de dashboards: aqueles menus suspensos úteis que mostram os valores dos seus dados para que você possa filtrar informações com alguns cliques.

Os controles de variáveis parecem semelhantes à primeira vista, mas têm um diferencial inteligente: em vez de filtrar automaticamente todos os painéis do seu dashboard, eles podem ser inseridos diretamente em consultas ES|QL dentro de visualizações específicas.

Isso significa que você pode decidir onde cada controle se aplica. Melhor ainda, você pode usá-los para todos os tipos de truques criativos, como ajustar intervalos, alternar campos de detalhamento ou alterar parâmetros de visualização em tempo real. Basicamente, eles proporcionam aos dashboards uma experiência verdadeiramente interativa, permitindo que você obtenha insights com mais rapidez e facilidade.

Casos de uso para controles de variáveis

Certo, os controles variáveis parecem úteis, mas o que você pode realmente fazer com eles? Aqui estão alguns exemplos de como eles elevam o nível de seu dashboard:

Filtrar visualizações selecionadas

Deseja filtrar algumas visualizações, mas não mexer em outras? Os controles de variáveis permitem exatamente isso. Escolha os painéis aos quais deseja responder e conecte-os nas consultas ES|QL por trás das suas visualizações.

Selecionar diferentes intervalos

Permita que seus usuários escolham entre "5 minutos", "1 hora", "1 dia" ou quaisquer buckets que façam sentido. Crie um controle de variáveis com intervalos predefinidos e conecte-o à sua consulta de séries temporais.

Funções de alteração

Em vez de criar vários gráficos para cada operação, permita que os usuários do dashboard escolham se desejam ver o máximo, a média, diferentes percentis ou qualquer outro agregador.

Agrupe por diferentes campos

Às vezes, é necessário dividir os dados conforme diferentes dimensões durante uma investigação. Com controles de variáveis, você pode definir múltiplos campos "agrupar por" e permitir que os usuários do dashboard escolham aquele que os ajude a descobrir seus insights.

Como você pode criá-los?

A maneira mais fácil (e provavelmente mais agradável) de criar um controle de variável é diretamente pelo editor de consultas ES|QL na sua visualização. Basta começar a digitar sua consulta, usar o menu de preenchimento automático, e o Kibana vai ajudar a estruturar o controle para você.

Mas, se preferir começar pela própria variável, você também pode ir para: Adicionar painel → Controles → Controle de variável e adicionar a variável às suas visualizações após criar o controle.

Exemplo 1: Controle de filtragem com seleção de múltiplos valores

1. Escolha uma visualização atrelada a uma consulta ES|QL e clique em "Criar controle" dentro da instrução WHERE

2. Você será redirecionado automaticamente para o submenu de criação de variáveis, onde o tipo "Valores de uma consulta" será selecionado para você e o nome da variável já estará pré-preenchido. Lembre-se de que o nome de um controle sempre precisa começar com "?...". para ser usado na consulta de visualização.

Normalmente, você precisará de uma consulta como esta para obter os valores de um campo e atualizá-los de acordo com o intervalo de tempo selecionado no dashboard:

FROM 
| WHERE @timestamp <=?_tend and @timestamp >?_tstart
| STATS BY 

3. Ao salvar o controle, ele será exibido na parte superior do painel, e sua consulta de visualização será atualizada com o nome do controle da variável.

4. Se você quiser adicionar seleção multi-valor ao controle, precisa usar a função MV_CONTAINS na consulta e selecionar "Permitir múltiplas seleções" durante a criação do controle na etapa 2 (disponível a partir da 9.3).

Exemplo 2: Controle de intervalo de tempo

Se estiver montando uma série temporal, você poderá facilmente adicionar um controle de variável para o intervalo do histograma de data:

1. Ao escrever uma consulta ES|QL para sua série temporal, clique em "Criar controle". Ao criar uma variável para intervalos, é melhor usar TBUCKET em vez de BUCKET para que aceite intervalos mais legíveis como "1 hora", "1 dia" etc. Também haverá uma opção automática para TBUCKET em breve, para que possa se adaptar automaticamente aos intervalos.

2. Defina os intervalos para preencher as opções no menu suspenso.

3. Selecione diferentes intervalos no menu suspenso e veja como sua visualização muda.

Exemplo 3: variáveis para funções

1. Crie uma variável usando o tipo de controle "Valores estáticos" e adicione nomes de funções aos seus valores suspensos. É importante usar um nome para sua variável que comece com “??...” para substituir funções.

2. Inclua o nome da variável na sua consulta ES|QL.

Exemplo 4: variáveis para campos

1. Você pode usar o tipo de controle "Valores estáticos" e anotar os nomes dos campos que quiser. É importante usar um nome de variável que comece com "??..." para aplicá-lo aos campos.

2. Faça referência à variável onde quiser na consulta de visualização.

Controles de variáveis no Discover

Controles variáveis não são apenas um recurso do dashboard — eles também estão disponíveis diretamente no editor ES|QL no Discover. Você pode construir controles para uma experiência de exploração de dados mais rápida no Discover, trazê-los para o dashboard e vice-versa.

Detalhes técnicos

A esta altura, você provavelmente já percebeu que os controles de variáveis vêm com algumas regras — como quais partes de uma consulta eles podem referenciar e os prefixos de nomeação que você precisa usar ("?..." para valores e "?? ...” para campos ou funções). O motivo disso é que variáveis não são apenas simples substituições de string no cliente. Elas são, na verdade, cidadãos de primeira classe na própria linguagem de consulta (conhecidos como parâmetros no ES|QL).

Este design traz grandes vantagens. Por exemplo, o Kibana consegue entender o contexto de cada variável, o que nos permite gerar e preencher automaticamente sua configuração para você. Também é muito mais seguro: como a linguagem valida rigorosamente entradas variáveis, ela impede injeções nocivas e erros se algo parece errado. Além disso, melhora o desempenho e a estabilidade ao transferir validações complexas e tratamento de erros para o servidor em vez do cliente. Uma observação sobre desempenho: uma prática recomendada é criar variáveis que incluam consultas rápidas, pois elas são carregadas antes do dashboard, portanto, consultas lentas podem afetar todo o desempenho do dashboard.

É claro, essa arquitetura também vem com algumas limitações—por enquanto. Variáveis ainda não permitem uma opção “Qualquer” para filtragem, e elas não podem ser usadas atualmente com certos operadores como LIKE ou FROM (para alternar fontes de dados). A boa notícia? Estamos trabalhando ativamente para adicionar essas funcionalidades.

O que o futuro reserva para os controles

Não vamos parar aqui! Algumas das melhorias no nosso radar incluem:

✨ A capacidade de posicionar controles em qualquer lugar do painel

✨ Encadeando seus controles — ou seja, a saída de um controle se torna a entrada do próximo

✨ Melhores opções de seleção como seleção "Qualquer" para variáveis

✨ Novos tipos de controle (controle de buscar e variáveis para suas fontes de dados)

✨ E mais melhorias de qualidade de vida que vocês pediram, como pré-filtrar controles normais.

Se você tiver ideias ou feedback, adoraríamos saber.

Resumo

Primeiro, vamos atualizá-lo. O Elasticsearch se estabeleceu como um poderoso banco de dados vetorial, oferecendo um rico conjunto de recursos e um forte desempenho para buscas por similaridade em larga escala. Com recursos como quantização escalar, Better Binary Quantization (BBQ), operações vetoriais SIMD e algoritmos mais eficientes em termos de disco, como DiskBBQ, ele já oferece opções eficientes e flexíveis para o gerenciamento de cargas de trabalho vetoriais.

Ao integrar o NVIDIA cuVS como um módulo chamável para tarefas de busca vetorial, buscamos entregar ganhos significativos no desempenho e eficiência da indexação vetorial para melhor suportar cargas de trabalho vetoriais em grande escala.

O desafio

Um dos maiores desafios na construção de um banco de dados vetorial de alto desempenho é a construção do índice vetorial - o gráfico HNSW. Rapidamente, a construção de índices se torna dominada por milhões ou até bilhões de operações aritméticas, à medida que cada vetor é comparado com muitos outros. Além disso, operações do ciclo de vida do índice, como compactação e fusões, podem aumentar ainda mais a sobrecarga total de processamento da indexação. À medida que os volumes de dados e os embeddings vetoriais associados crescem exponencialmente, GPUs de computação acelerada, construídas para paralelismo massivo e matemática de alto rendimento, estão idealmente posicionadas para lidar com essas cargas de trabalho.

Apresentando o plugin Elasticsearch-GPU

NVIDIA cuVS é uma biblioteca open source CUDA-X para busca vetorial acelerada por GPU e clustering de dados que permite a construção rápida de índices e recuperação de embeddings para cargas de trabalho de IA e recomendação.

O Elasticsearch utiliza o cuVS através do cuvs-java, uma biblioteca de open source desenvolvida pela comunidade e mantida pela NVIDIA. A biblioteca cuvs-java é leve e se baseia na API C do cuVS, utilizando a função estrangeira Panama para expor os recursos do cuVS de uma maneira idiomática em Java, mantendo-se moderna e eficiente.

A biblioteca cuvs-java está integrada a um novo plugin do Elasticsearch; portanto, a indexação na GPU pode ocorrer no mesmo node e processo do Elasticsearch, sem a necessidade de provisionar qualquer código ou hardware externo. Durante a criação do índice, se a biblioteca cuVS estiver instalada e uma GPU estiver presente e configurada, o Elasticsearch usará a GPU para acelerar o processo de indexação vetorial. Os vetores são fornecidos à GPU, que constrói um gráfico CAGRA. Esse gráfico é então convertido para o formato HNSW, tornando-o imediatamente disponível para busca vetorial na CPU. O formato final do gráfico construído é o mesmo que seria construído na CPU; isso permite que o Elasticsearch utilize GPUs para indexação de alto desempenho quando o hardware subjacente a suporta, liberando poder de processamento da CPU para outras tarefas (buscar, processamento de dados, etc.).

Aceleração de construção de índice

Como parte da integração da aceleração de GPU no Elasticsearch, várias melhorias foram feitas no cuvs-java, focando na entrada/saída eficiente de dados e na invocação de funções. Uma melhoria importante é o uso de cuVSMatrix para modelar vetores de forma transparente, independentemente de estarem na heap do Java, fora da heap ou na memória da GPU. Isso permite que os dados se movam eficientemente entre a memória e a GPU, evitando cópias desnecessárias de potencialmente bilhões de vetores.

Graças a essa abstração subjacente de cópia zero, tanto a transferência para a memória da GPU quanto a recuperação do gráfico podem ocorrer diretamente. Durante a indexação, os vetores são primeiro armazenados em buffer na memória do heap Java e depois enviados para a GPU para construir o gráfico CAGRA. O gráfico é posteriormente recuperado da GPU, convertido para o formato HNSW e persistido no disco.

No momento da fusão, os vetores já estão armazenar no disco, ignorando completamente o heap Java. Os arquivos de índice são mapeados em memória, e os dados são transferidos diretamente para a memória da GPU. O projeto também acomoda facilmente diferentes larguras de bits, como float32 ou int8, e se estende naturalmente a outros esquemas de quantização.

Drumroll... então, como funciona?

Antes de entrarmos nos números, um pouco de contexto é útil. A fusão de segmentos no Elasticsearch normalmente é executada de forma automática em segundo plano durante a indexação, o que dificulta a realização de testes de desempenho isoladamente. Para obter resultados reprodutíveis, usamos a fusão forçada para desencadear explicitamente a fusão de segmentos em um experimento controlado. Como a fusão forçada realiza as mesmas operações subjacentes de fusão que a fusão em segundo plano, seu desempenho serve como um indicador útil das melhorias esperadas, mesmo que os ganhos exatos possam diferir nas cargas de trabalho de indexação do mundo real.

Agora, vamos ver os números.

Nossos resultados iniciais de benchmark são muito promissores. Executamos o benchmark em uma instância AWS g6.4xlarge com armazenamento NVMe conectado localmente. Um único node do Elasticsearch foi configurado para usar o número padrão e ideal de threads de indexação (8 - uma para cada núcleo físico) e para desativar a limitação de mesclagem (o que é menos aplicável com discos NVMe rápidos).

Para o conjunto de dados, usamos 2,6 milhões de vetores com 1.536 dimensões da trilha vetorial do OpenAI Rally, codificados como strings base64 e indexados como float32 hnsw. Em todos os cenários, os gráficos construídos atingem níveis de recall de até 95%. Veja o que descobrimos:

• Taxa de transferência de indexação: ao transferir a construção de gráficos para a GPU durante as descargas de buffer na memória, aumentamos a taxa de transferência em cerca de 12 vezes.
• Fusão forçada: após a conclusão da indexação, a GPU continua acelerando a fusão de segmentos, acelerando a fase de mesclagem forçada em aproximadamente 7x.

• Uso da CPU: o descarregamento da construção de gráficos para a GPU reduz significativamente a utilização média e de pico da CPU. Os gráficos abaixo ilustram o uso da CPU durante a indexação e a fusão, destacando o quanto é menor quando essas operações são executadas na GPU. Menor utilização da CPU durante a indexação da GPU libera ciclos de CPU que podem ser redirecionados para melhorar o desempenho da busca.

• Lembrete: a precisão permanece efetivamente a mesma entre as execuções de CPU e GPU, com o gráfico construído por GPU alcançando um recall marginalmente mais alto.

Comparando em outra dimensão: Preço

A comparação anterior usava intencionalmente hardware idêntico, com a única diferença sendo se a GPU era usada durante a indexação. Essa configuração é útil para isolar efeitos brutos de computação, mas também podemos olhar para a comparação dos custos.

Por aproximadamente o mesmo preço por hora da configuração acelerada por GPU, é possível provisionar uma configuração apenas CPU com aproximadamente o dobro dos recursos comparáveis de CPU e memória: 32 vCPUs (AMD EPYC) e 64 GB de RAM, permitindo dobrar o número de threads de indexação para 16.

Para manter a comparação justa e consistente, executamos esse experimento apenas com CPU em uma instância AWS g6.8xlarge, com a GPU explicitamente desativada. Isso nos permitiu manter todas as outras características de hardware constantes ao avaliar a relação custo-desempenho da aceleração da GPU em comparação  com a indexação somente da CPU.

A instância mais potente da CPU mostra desempenho melhor em comparação com os benchmarks da seção acima, como era de se esperar. No entanto, ao compararmos essa instância de CPU mais potente com os resultados originais acelerados por GPU, a GPU ainda oferece ganhos de desempenho substanciais: melhoria de aproximadamente 5 vezes na taxa de transferência de indexação e aproximadamente 6 vezes na fusão forçada, tudo isso enquanto constrói gráficos que atingem níveis de recall de até 95%.

Conclusão

Em cenários de ponta a ponta, a aceleração de GPU com NVIDIA cuVS proporciona quase 12x de melhoria na taxa de indexação e uma redução de 7x na latência de fusão forçada, com uma utilização significativamente menor da CPU. Isso mostra que a indexação vetorial e as cargas de trabalho de fusão se beneficiam significativamente da aceleração da GPU. Em uma comparação ajustada ao custo, a aceleração da GPU continua a gerar ganhos substanciais de desempenho, com taxa de transferência de indexação aproximadamente 5 vezes maior e operações de fusão forçada 6 vezes mais rápidas.

A indexação de vetores acelerada por GPU está atualmente planejada para Prévia Técnica no Elasticsearch 9.3, que está programada para ser lançada no início de 2026.

Fique ligado para mais.

Aqui está uma visão dos recursos do Elasticsearch 9.2 que transformarão seus fluxos de trabalho de análise de dados com o ES|QL.

Revolucionando a correlação de dados: um Lookup Join mais inteligente, rápido e flexível

O comando LOOKUP JOIN no ES|QL passou por uma transformação significativa no Elasticsearch 9.2, tornando-se dramaticamente mais eficiente e versátil. O comando LOOKUP JOIN combina dados da sua tabela de resultados da consulta ES|QL com registros correspondentes de um índice de modo de consulta especificado. Ele adiciona campos do índice de pesquisa como novas colunas à sua tabela de resultados com base em valores correspondentes no campo de join. Anteriormente, a junção de dados estava limitada a um único campo e igualdade simples. Não mais! Essas melhorias capacitam você a lidar com cenários complexos de correlação de dados de forma fácil.

Os principais aprimoramentos do Lookup Join incluem:

• Joins de múltiplos campos: crie joins facilmente em múltiplos campos. Por exemplo, para unir application_logs com service_registry em service_name, environment e version:

FROM application_logs
| LOOKUP JOIN service_registry ON service_name, environment, version

• Liberando predicados de joins complexos com expressões (prévia técnica):

Você não está mais limitado à simples igualdade. O LOOKUP JOIN agora permite especificar múltiplos critérios para correlação e incorporar uma variedade de operadores binários, incluindo ==, !=, <, >, <=, e >=. Isso significa que você pode criar condições de join altamente nuançadas, permitindo que você faça perguntas muito mais sofisticadas sobre seus dados.

Exemplo 1: encontrando métricas de aplicação com limite de SLA por serviço

FROM application_metrics
| LOOKUP JOIN sla_thresholds
      ON service_name == sla_service AND response_time > sla_response_time

Exemplo 2: esta consulta calcula o valor devido com base em políticas regionais de precificação que mudam ao longo do tempo. Ele une três conjuntos de dados baseados em condições complexas de intervalo de datas e igualdade para calcular um due_amount final. A segunda busca usa o campo measurement_date do índice meter_readings e o campo region_id do índice customers para se juntar ao índice pricing_policies e encontrar a política de precificação correta para o region e measurement_date específicos.

FROM meter_readings
| LOOKUP JOIN customers
      ON meter_id
| LOOKUP JOIN pricing_policies
      ON
        region_id == region AND
          measurement_date >= policy_begin_date AND
          measurement_date < policy_end_date
| EVAL due_amount = (kwh_consumed * rate_per_kwh + base_charge) * (1 + tax_rate)
| EVAL period = policy_name
| KEEP customer_name, period, due_amount, measurement_date, kwh_consumed,
    rate_per_kwh, base_charge, tax_rate
| SORT measurement_date

• Ganhos massivos de desempenho para joins filtrados:

Melhoramos o desempenho para "joins expansivos" que são filtrados usando condições de tabela de consulta. Os joins expansivos produzem múltiplas correspondências por linha de entrada, o que pode criar grandes conjuntos intermediários de resultados. Isso piora quando muitas dessas linhas são descartadas por um filtro subsequente. Na versão 9.2, otimizamos esses joins filtrando linhas desnecessárias quando um filtro é aplicado aos dados de consulta, evitando processar linhas que seriam descartadas. Em alguns cenários, esses joins podem ser até 1000 vezes mais rápidos!

Essa otimização é crucial ao lidar com joins em expansão, onde uma pesquisa pode inicialmente gerar muitas correspondências potenciais. Ao aplicar filtros de forma inteligente, apenas os dados relevantes são processados, reduzindo drasticamente o tempo de execução da consulta e permitindo a análise em tempo real em grandes conjuntos de dados. Isso significa que você obtém seus insights muito mais rapidamente, mesmo com operações de join muito grandes ou complexas.

Compatibilidade do Lookup Join Cross-Cluster Search (CCS):

Quando o Lookup Join foi lançado como GA nas versões 8.19 e 9.1, ele não era compatível com Pesquisa entre clusters (CCS). Para organizações que operam em vários clusters, o LOOKUP JOIN agora se integra perfeitamente ao CCS na versão 9.2. Basta colocar seu índice de pesquisa em todos os clusters remotos onde você deseja realizar um join, e o ES|QL aproveitará automaticamente esses índices de pesquisa remota para unir seus dados remotos. Isso simplifica a análise distribuída de dados e garante um enriquecimento consistente em toda a sua implantação do Elasticsearch.

Essas melhorias significam que você pode correlacionar conjuntos de dados diversos com precisão, rapidez e facilidade sem precedentes, revelando insights mais profundos e acionáveis sem soluções complexas ou etapas de pré-processamento.

Enriqueça seus dados com facilidade: Kibana Discover UX para Lookup Indices

O enriquecimento de dados deve ser simples, não um obstáculo. Introduzimos uma experiência fantástica de usuário no Discover do Kibana para criar e gerenciar índices de lookup.

Fluxo de trabalho intuitivo: o preenchimento automático abrangente do Discover guiará você pelo processo, sugerindo índices de pesquisa e campos de união no editor ES|QL, tornando incrivelmente fácil conectar seus dados carregados aos índices existentes. Digite o nome de um índice de consulta que não exista e obtenha acesso direto ao editor de pesquisa com um clique para criar o índice. Digite o nome de um índice de consulta existente e sugeriremos uma opção para editá-lo:

Gestão em linha (CRUD): mantenha seus conjuntos de dados de referência atualizados com capacidades de edição em linha (Criar, Ler, Atualizar, Excluir) diretamente no Discover.

Upload de arquivos sem esforço: Agora você pode carregar arquivos diretamente, como CSVs, no Discover e usá-los instantaneamente nos seus LOOKUP JOIN. Chega de alternar entre diferentes áreas do Kibana!

Seja no mapeamento de IDs de usuário a nomes, adicionando metadados empresariais ou unindo arquivos de referência estáticos, este recurso democratiza o enriquecimento de dados, colocando a capacidade de melhorar com os joins diretamente nas mãos de cada usuário – rápido, simples e tudo em um só lugar.

Mantenha seu contexto: Apresentando INLINE STATS (prévia técnica)

Agregar dados é fundamental, mas às vezes você precisa ver os agregados junto com os dados originais. Temos o prazer de apresentar INLINE STATS como um recurso de visualização técnica.

Ao contrário do comando STATS, que substitui seus campos de entrada pela saída agregada, INLINE STATS preserva todos os campos de entrada originais e simplesmente adiciona os novos campos agregados. Isso permite que você execute outras operações nos campos de entrada originais após a agregação, proporcionando um fluxo de trabalho de análise mais contínuo e flexível.

Por exemplo, para calcular a distância média de voo mantendo as linhas individuais de voo:

FROM kibana_sample_data_flights
 | KEEP Carrier, Dest, DistanceMiles
 | INLINE STATS avgDist = ROUND(AVG(DistanceMiles))
       BY Dest
 | WHERE DistanceMiles > avgDist

Nessa consulta, avgDist é adicionado a cada linha com a Dest(inação) correspondente pela qual agrupamos e, como ainda temos as colunas de informações do voo, podemos filtrar os resultados para os voos com uma distância maior que a média.

Compatível com séries temporais no ES|QL (prévia técnica)

O Elasticsearch utiliza fluxos de dados de séries temporais para armazenar métricas. Estamos adicionando suporte para agregações de séries temporais no ES|QL, através do comando TS source. Isso está disponível no Elastic Cloud Serverless e na versão 9.2 básica como uma prévia técnica.

A análise de séries temporais é amplamente baseada em consultas de agregação que resumem os valores das métricas em buckets de tempo, divididos por uma ou mais dimensões de filtragem. A maioria das consultas de agregação depende do processamento em duas etapas, com (a) uma função de agregação interna resumindo valores por série temporal e (b) uma função de agregação externa, combinando os resultados de (a) em todas as séries temporais.

O comando TS source, combinado com STATS, fornece uma forma concisa, porém eficaz, de expressar tais consultas ao longo de séries temporais. Mais concretamente, considere o seguinte exemplo para calcular a taxa total de solicitações por host e por hora:

TS my_metrics
| WHERE @timestamp > NOW() - 1 day
| STATS SUM(RATE(requests))
      BY host, TBUCKET(1h)

Nesse caso, a função de agregação de séries temporais RATE é avaliada primeiro por série temporal e hora. Os agregados parciais produzidos são então combinados usando SUM para calcular os valores agregados finais por hospedado e por hora.

Você pode conferir a lista de funções de agregação de séries temporais disponíveis aqui. A taxa de contador agora é compatível, provavelmente a função de agregação mais importante para processar contadores.

O comando TS source é projetado para ser combinado com STATS, com execução ajustada para ser compatível com agregações de séries temporais de forma eficiente. Por exemplo, os dados são ordenados antes de serem inseridos no STATS. Comandos de processamento que possam enriquecer ou alterar os dados de série temporal ou sua ordem, como FORK ou INLINE STATS, atualmente não são permitidos entre TS e STATS. Essa limitação pode ser eliminada no futuro.

A saída tabular STATS pode ser processada ainda com qualquer comando aplicável. Por exemplo, a consulta a seguir calcula a razão entre a média cpu_usage por host e hora para o valor máximo por host:

TS my_metrics
| STATS avg_usage = AVG(AVG_OVER_TIME(cpu_usage))
      BY host, time_bucket = TBUCKET(1h)
| INLINE STATS max_avg_usage = MAX(avg_usage)
      BY host
| EVAL ratio = avg_usage / max_avg_usage
| KEEP host, time_bucket, ratio
| SORT host, time_bucket DESC

Os dados de série temporal são armazenados em nosso mecanismo de armazenamento colunar subjacente, que é alimentado pelos valores de documento do Lucene. O comando TS adiciona execução vetorizada de consultas através do mecanismo de computação ES|QL. O desempenho das consultas geralmente é melhorado em mais de uma ordem de magnitude, em comparação com consultas DSL equivalentes, e está em pé de igualdade com sistemas estabelecidos e específicos para métricas. No futuro, forneceremos uma análise detalhada de arquitetura e desempenho, então fique ligado.

Expandindo seu conjunto de ferramentas: novas funções ES|QL

Manipulação de string: CONTAINS, MV_CONTAINS, URL_ENCODE, URL_ENCODE_COMPONENT, URL_DECODE para processamento mais robusto de texto e URL.

Séries temporais e geoespaciais: TBUCKET para buckets flexíveis de tempo, TO_DENSE_VECTOR para operações vetoriais e um conjunto abrangente de funções geoespaciais como ST_GEOHASH, ST_GEOTILE, ST_GEOHEX, TO_GEOHASH, TO_GEOTILE, TO_GEOHEX para análise avançada baseada em localização.

Formatação de datas: DAY_NAME, MONTH_NAME para representações de data mais legíveis.

Essas funções oferecem um conjunto mais rico de ferramentas para manipular e analisar seus dados diretamente dentro do ES|QL.

Sob o capô: mais desempenho e eficiência

Além dos recursos destacados, o Elasticsearch 9.2 inclui diversas otimizações de desempenho em todo o ES|QL. Aceleramos RLIKE (LIST) com pushdown nos casos em que a função substitui várias consultas RLIKE semelhantes. Com RLIKE (LIST), podemos unir essas consultas em um único autômato e aplicar um autômato em vez de vários. Também temos carregamento mais rápido dos campos de palavras-chave com ordenação de índice e otimizações gerais de consultas – essas melhorias garantem que suas consultas ES|QL sejam executadas de forma mais eficiente do que nunca.

Comece hoje mesmo!

Elasticsearch 9.2 representa um salto significativo para o ES|QL, trazendo uma melhoria e flexibilidade sem precedentes para seus fluxos de trabalho de análise de dados. Incentivamos você a explorar esses novos recursos e experimentar a diferença que eles fazem.

Para uma lista abrangente de todas as mudanças e aprimoramentos no Elasticsearch 9.2, consulte as notas de lançamento oficiais. Boas consultas!

Os conectores personalizados permitem que você combine seus conectores ChatGPT existentes com fontes adicionais de dados, como o Elasticsearch, para obter respostas abrangentes.

Neste artigo, criaremos um servidor MCP que conecta o ChatGPT a um índice Elasticsearch contendo informações sobre problemas internos e solicitações de pull do GitHub. Isso permite que consultas em linguagem natural sejam respondidas usando os dados do seu Elasticsearch.

Implantaremos o servidor MCP usando o FastMCP no Google Colab com ngrok para obter um URL público ao qual o ChatGPT possa se conectar, eliminando a necessidade de uma configuração de infraestrutura complexa.

Para uma visão geral do MCP e seu ecossistema, consulte O Estado Atual do MCP.

Pré-requisitos

Antes de começar, você precisará de:

• Cluster do Elasticsearch (8.X ou superior)
• Chave de API do Elasticsearch com acesso de leitura ao seu índice
• Conta do Google (para o Google Colab)
• Conta Ngrok (versão gratuita funciona)
• Conta do ChatGPT com plano Pro/Empresarial/Business ou Edu

Entendendo os requisitos do conector MCP do ChatGPT

Os conectores MCP do ChatGPT exigem a implementação de duas ferramentas: search e fetch. Para mais detalhes, consulte OpenAI Docs.

Ferramenta de busca

Retorna uma lista de resultados relevantes do seu índice Elasticsearch com base em uma consulta do usuário.

O que ele recebe:

• Uma única string com a consulta de linguagem natural do usuário.
• Exemplo: "Encontre problemas relacionados à migração do Elasticsearch."

O que ele retorna: 

• Um objeto com uma chave result contendo um array de objetos de resultado. Cada resultado inclui:
  • id - Identificador único do documento
  • title - Título da issue ou do PR
  • url - Link para o problema/PR

Na nossa implementação:

return {
    "results": [
        {
            "id": "PR-612",
            "title": "Fix memory leak in WebSocket notification service",
            "url": "https://internal-git.techcorp.com/pulls/612"
        },
        # ... more results
    ]
}

Ferramenta de recuperação

Recupera o conteúdo completo de um documento específico.

O que ele recebe:

• Uma única string com o ID do documento Elasticsearch do resultado de busca
• Exemplo: "Me dê os detalhes do PR-578."

O que ele retorna:

• Um objeto de documento completo com:
  • id - Identificador único do documento
  • title - Título da issue ou do PR
  • text - Complete a descrição e os detalhes do problema/PR
  • url - Link para o problema/PR
  • type - Tipo de documento (issue, pull_request)
  • status - Status atual (aberto, em_andamento, resolvido)
  • priority - Nível de prioridade (baixo, médio, alto, crítico)
  • assignee - Pessoa designada para o problema/PR
  • created_date - Quando foi criado
  • resolved_date - Quando foi resolvido (se aplicável)
  • labels - Tags associadas ao documento
  • related_pr - ID de pull request relacionado

return {
    "id": "PR-578",
    "title": "Security hotfix: Patch SQL injection vulnerabilities",
    "text": "Description: CRITICAL SECURITY FIX for ISSUE-1889. Patches SQL...",
    "url": "https://internal-git.techcorp.com/pulls/578",
    "type": "pull_request",
    "status": "closed",
    "priority": "critical",
    "assignee": "sarah_dev",
    "created_date": "2025-09-19",
    "resolved_date": "2025-09-19",
    "labels": "security, hotfix, sql",
    "related_pr": null
}

Observação: este exemplo usa uma estrutura plana onde todos os campos estão no nível raiz. Os requisitos do OpenAI são flexíveis e também permitem objetos de metadados aninhados.

Questões do GitHub e conjunto de dados PRs

Para este tutorial, vamos usar um conjunto de dados interno do GitHub contendo problemas e solicitações de pull. Isso representa um cenário em que você deseja consultar dados privados e internos por meio do ChatGPT.

O conjunto de dados pode ser encontrado aqui. E atualizaremos o índice dos dados usando a bulk API.

Esse conjunto de dados inclui:

• Problemas com descrições, status, prioridade e responsáveis
• Solicitações de pull com alterações de código, revisões e informações de implantação
• Relações entre problemas e PRs (por exemplo, PR-578 corrige o ISSUE-1889)
• Rótulos, datas e outros metadados

Mapeamentos de índice

O índice usa os seguintes mapeamentos para permitir a pesquisa híbrida com o ELSER. A text_semantic é usada para busca semântica, enquanto outros campos permitem a busca por palavras-chave.

{
  "mappings": {
    "properties": {
      "id": {
        "type": "keyword"
      },
      "title": {
        "type": "text"
      },
      "text": {
        "type": "text"
      },
      "text_semantic": {
        "type": "semantic_text",
        "inference_id": ".elser-2-elasticsearch"
      },
      "url": {
        "type": "keyword"
      },
      "type": {
        "type": "keyword"
      },
      "status": {
        "type": "keyword"
      },
      "priority": {
        "type": "keyword"
      },
      "assignee": {
        "type": "keyword"
      },
      "created_date": {
        "type": "date",
        "format": "iso8601"
      },
      "resolved_date": {
        "type": "date",
        "format": "iso8601"
      },
      "labels": {
        "type": "keyword"
      },
      "related_pr": {
        "type": "keyword"
      }
    }
  }
}

Construa o servidor MCP

Nosso servidor MCP implementa duas ferramentas seguindo as especificações da OpenAI, usando busca híbrida para combinar correspondência semântica e de texto para obter melhores resultados.

Ferramenta de busca

Utiliza busca híbrida com RRF (Reciprocal Rank Fusion), combinando buscar semântica com correspondência de texto:

@mcp.tool()
    async def search(query: str) -> Dict[str, List[Dict[str, Any]]]:
        """
        Search for internal issues and PRs using hybrid search (semantic + text with RRF).
        Returns list with id, title, and url per OpenAI spec.
        """
        if not query or not query.strip():
            return {"results": []}

        logger.info(f"Searching for: '{query}'")

        try:
            # Hybrid search with RRF (Reciprocal Rank Fusion)
            response = es_client.search(
                index=ELASTICSEARCH_INDEX,
                size=10,
                source=["id", "title", "url", "type", "priority"],
                retriever={
                    "rrf": {
                        "retrievers": [
                            {
                                # Semantic search with ELSER
                                "standard": {
                                    "query": {
                                        "semantic": {
                                            "field": "text_semantic",
                                            "query": query
                                        }
                                    }
                                }
                            },
                            {
                                # Text search (BM25) for keyword matching
                                "standard": {
                                    "query": {
                                        "multi_match": {
                                            "query": query,
                                            "fields": [
                                                "title^3",
                                                "text^2",
                                                "assignee^2",
                                                "type",
                                                "labels",
                                                "priority"
                                            ],
                                            "type": "best_fields",
                                            "fuzziness": "AUTO"
                                        }
                                    }
                                }
                            }
                        ],
                        "rank_window_size": 50,
                        "rank_constant": 60
                    }
                }
            )

            results = []
            if response and 'hits' in response:
                for hit in response['hits']['hits']:
                    source = hit['_source']
                    results.append({
                        "id": source.get('id', hit['_id']),
                        "title": source.get('title', 'Unknown'),
                        "url": source.get('url', '')
                    })

            logger.info(f"Found {len(results)} results")
            return {"results": results}

        except Exception as e:
            logger.error(f"Search error: {e}")
            raise ValueError(f"Search failed: {str(e)}")

Pontos principais:

• Busca híbrida com RRF: combina busca semântica (ELSER) e busca por texto (BM25) para melhores resultados.
• Consulta multi-correspondência: busca em múltiplos campos com aumento de relevância (title^3, text^2, assignee^2). O símbolo de caret (^) multiplica as pontuações de relevância, priorizando as correspondências nos títulos em detrimento do conteúdo.
• Correspondência inexata: fuzziness: AUTO lida com erros de digitação e ortografia, permitindo correspondências aproximadas.
• Ajuste dos parâmetros do RRF:
  • rank_window_size: 50 - Especifica quantos resultados principais de cada recuperador (semântico e textual) são considerados antes da mesclagem.
  • rank_constant: 60 - Esse valor determina quanta influência os documentos em conjuntos de resultados individuais têm sobre o resultado final classificado.
• Retorna somente os campos obrigatórios: id, title, url de acordo com a especificação da OpenAI e evita a exposição desnecessária de campos adicionais.

Ferramenta de recuperação

Recupera detalhes do documento pelo ID do documento, quando existe:

@mcp.tool()
    async def fetch(id: str) -> Dict[str, Any]:
        """
        Retrieve complete issue/PR details by ID.
        Returns id, title, text, url.
        """
        if not id:
            raise ValueError("ID is required")

        logger.info(f"Fetching: {id}")

        try:
            # Search by the 'id' field (not _id) since IDs are stored as a field
            response = es_client.search(
                index=ELASTICSEARCH_INDEX,
                body={
                    "query": {
                        "term": {
                            "id": id  # Search by your custom 'id' field
                        }
                    },
                    "size": 1
                }
            )

            if not response or not response['hits']['hits']:
                raise ValueError(f"Document with id '{id}' not found")

            hit = response['hits']['hits'][0]
            source = hit['_source']

            result = {
                "id": source.get('id', id),
                "title": source.get('title', 'Unknown'),
                "text": source.get('text', ''),
                "url": source.get('url', ''),
                "type": source.get('type', ''),
                "status": source.get('status', ''),
                "priority": source.get('priority', ''),
                "assignee": source.get('assignee', ''),
                "created_date": source.get('created_date', ''),
                "resolved_date": source.get('resolved_date', ''),
                "labels": source.get('labels', ''),
                "related_pr": source.get('related_pr', '')
            }

            logger.info(f"Fetched: {result['title']}")
            return result

        except Exception as e:
            logger.error(f"Fetch error: {e}")
            raise ValueError(f"Failed to fetch '{id}': {str(e)}")

Pontos principais:

• Buscar por campo de ID do documento: Utiliza consulta de termo no campo personalizado id
• Retorna o documento completo: inclui o campo text completo com todo o conteúdo
• Estrutura plana: Todos os campos no nível da raiz, correspondendo à estrutura de documentos do Elasticsearch.

Implantar no Google Colab

Usaremos o Google Colab para executar nosso servidor MCP e o ngrok para expô-lo publicamente, permitindo que o ChatGPT se conecte a ele.

Etapa 1: Abra o notebook do Google Colab

Acesse nosso notebook pré-configurado Elasticsearch MCP para ChatGPT.

Etapa 2: Configure suas credenciais

Você precisará de três informações:

• URL do Elasticsearch: seu URL do cluster do Elasticsearch.
• Chave da API do Elasticsearch: Chave da API com permissão de leitura do seu índice.
• Token de autenticação Ngrok: token grátis do ngrok. Vamos usar o ngrok para expor a URL do MCP à internet para que o ChatGPT possa se conectar a ela.

Obter seu token ngrok

1. Cadastre-se para uma conta gratuita em ngrok
2. Acesse seu painel do ngrok
3. Copie seu token de autenticação.

Adicionando segredos ao Google Colab

No notebook do Google Colab:

1. Clique no ícone de chave na barra lateral esquerda para abrir Secrets.
2. Adicione estes três segredos:

ELASTICSEARCH_URL=https://your-cluster.elastic.com:443
ELASTICSEARCH_API_KEY=your-api-key
NGROK_TOKEN=your-ngrok-token

3. Habilitar o acesso ao notebook para cada segredo

Passo 3: Execute o notebook

1. Clique em Runtime e depois em Executar tudo para executar todas as células
2. Aguarde o servidor iniciar (cerca de 30 segundos)
3. Procure a saída mostrando seu URL público do ngrok

4. A saída exibirá algo como:

Conectar-se ao ChatGPT

Agora vamos conectar o servidor MCP à sua conta do ChatGPT.

1. Abra o ChatGPT e vá para Configurações.
2. Navegue até Conectores. Se você estiver usando uma conta Pro, precisará ativar o modo de desenvolvedor nos conectores.

Se você está usando o ChatGPT em empresas ou negócios, precisa disponibilizar o conector para seu local de trabalho.

3. Clique em Criar.

Observação: nos espaços de trabalho Business, Empresarial e Edu, somente os proprietários, administradores e usuários com a respectiva configuração ativada (para Empresarial/Edu) podem adicionar conectores personalizados. Usuários com a função de membro padrão não têm permissão para adicionar conectores personalizados.

Após um conector ser adicionado e habilitado por um proprietário ou usuário administrador, ele fica disponível para todos os membros do espaço de trabalho.

4. Insira as informações necessárias e sua URL ngrok que termina em /sse/. Repare no "/" após "sse". Não vai funcionar sem ele:

• Nome: Elasticsearch MCP
• Descrição: MCP personalizado para pesquisar e recuperar informações internas do GitHub.

5. Pressione Criar para salvar o MCP personalizado.

A conexão será instantânea se seu servidor estiver em execução. Não é necessária autenticação adicional, pois a chave da API do Elasticsearch está configurada no seu servidor.

Teste o servidor MCP

Antes de fazer perguntas, você precisa selecionar qual conector o ChatGPT deve usar.

Prompt 1: Buscar por problemas

Pergunte: "Encontre problemas relacionados à migração do Elasticsearch" e confirme a chamada da ferramenta de ações.

O ChatGPT chamará a ferramenta search com sua consulta. Você pode ver que ele está procurando as ferramentas disponíveis, se preparando para chamar a ferramenta Elasticsearch e confirma com o usuário antes de tomar qualquer medida em relação à ferramenta.

Solicitação de chamada de ferramenta:

{
  "query": "Elasticsearch migration issues"
}

Resposta da ferramenta:

{
  "results": [
    {
      "id": "PR-598",
      "title": "Elasticsearch 8.x migration - Application code changes",
      "url": "https://internal-git.techcorp.com/pulls/598"
    },
    {
      "id": "ISSUE-1712",
      "title": "Migrate from Elasticsearch 7.x to 8.x",
      "url": "https://internal-git.techcorp.com/issues/1712"
    },
    {
      "id": "RFC-045",
      "title": "Design Proposal: Microservices Migration Architecture",
      "url": "https://internal-git.techcorp.com/rfcs/045"
    }
    // ... 7 more results
  ]
}

O ChatGPT processa os resultados e os apresenta em um formato natural e conversacional.

Nos bastidores

Prompt: "Encontrar problemas relacionados à migração do Elasticsearch"

1. Chamadas do ChatGPT search(“Elasticsearch migration”)

2. O Elasticsearch realiza uma busca híbrida

• A busca semântica compreende conceitos como "atualização" e "compatibilidade de versões".
• A busca de texto encontra correspondências exatas para "Elasticsearch" e "migração".
• O RRF combina e classifica os resultados de ambas as abordagens

3. Retorna os 10 melhores eventos de correspondência com id, title, url

4. O ChatGPT identifica "ISSUE-1712: migrar do Elasticsearch 7.x para o 8.x" como o resultado mais relevante

Prompt 2: Obter todos os detalhes

Perguntar: "Informe detalhes sobre o ISSUE-1889"

O ChatGPT reconhece que você quer informações detalhadas sobre um problema específico e aciona a ferramenta fetch, confirmando com o usuário antes de tomar qualquer medida em relação à ferramenta.

Solicitação de chamada de ferramenta:

{
  "id": "ISSUE-1889"
}

Resposta da ferramenta:

{
  "id": "ISSUE-1889",
  "title": "SQL injection vulnerability in search endpoint",
  "text": "Description: Security audit identified SQL injection vulnerability in /api/v1/search endpoint. User input from query parameter is not properly sanitized before being used in raw SQL query. Severity: HIGH - Immediate action required Affected Code: - File: services/search/query_builder.py - Line: 145-152 - Issue: String concatenation used instead of parameterized queries Investigation: - @security_team_alice: Confirmed exploitable with UNION-based injection - @sarah_dev: Checking all other endpoints for similar patterns - @john_backend: Found 3 more instances in legacy codebase Remediation: - Rewrite using SQLAlchemy ORM or parameterized queries - Add input validation and sanitization - Implement WAF rules as additional layer - Security regression tests Comments: - @tech_lead_mike: Stop all other work, this is P0 - @sarah_dev: PR-578 ready with fixes for all 4 vulnerable endpoints - @alex_devops: Deployed hotfix to production 2025-09-19 at 14:30 UTC - @security_team_alice: Verified fix, conducting full pentest next week Resolution: All vulnerable endpoints patched. Added pre-commit hooks to catch raw SQL queries. Security training scheduled for team.",
  "url": "https://internal-git.techcorp.com/issues/1889",
  "type": "issue",
  "status": "closed",
  "priority": "critical",
  "assignee": "sarah_dev",
  "created_date": "2025-09-18",
  "resolved_date": "2025-09-19",
  "labels": "security, vulnerability, bug, sql",
  "related_pr": "PR-578"
}

O ChatGPT sintetiza as informações e as apresenta claramente.

Nos bastidores

Prompt: “Informe mais detalhes sobre ISSUE-1889”

1. Chamadas do ChatGPT fetch(“ISSUE-1889”)
2. O Elasticsearch recupera o documento completo
3. Retorna um documento completo com todos os campos no nível raiz
4. O ChatGPT sintetiza as informações e responde com citações adequadas.

Conclusão

Neste artigo, criamos um servidor MCP personalizado que conecta o ChatGPT ao Elasticsearch usando ferramentas MCP dedicadas de busca e recuperação, permitindo consultas em linguagem natural sobre dados privados.

Este padrão MCP funciona para qualquer índice Elasticsearch, documentação, produtos, log ou quaisquer outros dados que você queira consultar por meio de linguagem natural.

Introdução ao RAG agentivo

A Geração Aumentada por Recuperação (RAG, na sigla em inglês) tornou-se um pilar fundamental em aplicações baseadas em Modelos de Aprendizagem Baseados em Aprendizagem (LLM, na sigla em inglês), permitindo que os modelos forneçam respostas otimizadas ao recuperar o contexto relevante com base nas consultas do usuário. Os sistemas RAG aprimoram a precisão e o contexto das respostas do LLM (Modelo de Aprendizagem Baseado em Aprendizagem) ao utilizar informações externas provenientes de APIs ou bancos de dados, em vez de se limitarem ao conhecimento pré-treinado do LLM. Por outro lado, os agentes de IA operam de forma autônoma, tomando decisões e executando ações para atingir seus objetivos designados.

O RAG Agentic é uma estrutura que unifica os pontos fortes da geração aumentada por recuperação e do raciocínio agentivo. Ele integra o RAG ao processo de tomada de decisão do agente, permitindo que o sistema escolha dinamicamente fontes de dados, refine consultas para melhor recuperação de contexto, gere respostas mais precisas e aplique um ciclo de feedback para melhorar continuamente a qualidade da saída.

Principais características do RAG agentivo

A estrutura RAG agentiva representa um grande avanço em relação aos sistemas RAG tradicionais. Em vez de seguir um processo de recuperação fixo, utiliza agentes dinâmicos capazes de planejar, executar e otimizar resultados em tempo real.

Vamos analisar algumas das principais características que distinguem os pipelines RAG agentivos:

• Tomada de decisão dinâmica: o Agentic RAG utiliza um mecanismo de raciocínio para compreender a intenção do usuário e direcionar cada consulta para a fonte de dados mais relevante, produzindo respostas precisas e contextualizadas.
• Análise abrangente de consultas: o Agentic RAG analisa profundamente as consultas dos usuários, incluindo subperguntas e sua intenção geral. Ele avalia a complexidade da consulta e seleciona dinamicamente as fontes de dados mais relevantes para recuperar informações, garantindo respostas precisas e completas.
• Colaboração em múltiplas etapas: Esta estrutura permite a colaboração em múltiplas etapas através de uma rede de agentes especializados. Cada agente lida com uma parte específica de um objetivo maior, trabalhando sequencialmente ou simultaneamente para alcançar um resultado coeso.
• Mecanismos de autoavaliação: O pipeline RAG agentivo utiliza a autorreflexão para avaliar os documentos recuperados e as respostas geradas. Ele pode verificar se as informações recuperadas respondem completamente à consulta e, em seguida, revisar a saída quanto à precisão, integridade e consistência factual.
• Integração com ferramentas externas: Este fluxo de trabalho pode interagir com APIs externas, bancos de dados e fontes de informação em tempo real, incorporando informações atualizadas e adaptando-se dinamicamente à evolução dos dados.

Padrões de fluxo de trabalho do RAG agente

Os padrões de fluxo de trabalho definem como a IA agente estrutura, gerencia e orquestra aplicações baseadas em LLM de maneira confiável e eficiente. Diversas estruturas e plataformas, como LangChain, LangGraph, CrewAI e LlamaIndex, podem ser usadas para implementar esses fluxos de trabalho com agentes.

1. Cadeia de recuperação sequencial: Os fluxos de trabalho sequenciais dividem tarefas complexas em etapas simples e ordenadas. Cada etapa melhora a entrada para a próxima, levando a melhores resultados. Por exemplo, ao criar um perfil de cliente, um agente pode extrair detalhes básicos de um CRM, outro recupera o histórico de compras de um banco de dados de transações e um agente final combina essas informações para gerar um perfil completo para recomendações ou relatórios.
2. Cadeia de roteamento e recuperação: Neste padrão de fluxo de trabalho, um agente de roteamento analisa a entrada e a direciona para o processo ou fonte de dados mais apropriada. Essa abordagem é particularmente eficaz quando existem múltiplas fontes de dados distintas com sobreposição mínima. Por exemplo, em um sistema de atendimento ao cliente, o agente de roteamento categoriza as solicitações recebidas, como problemas técnicos, reembolsos ou reclamações, e as encaminha para o departamento apropriado para um tratamento eficiente.
3. Cadeia de recuperação paralela: Neste padrão de fluxo de trabalho, várias subtarefas independentes são executadas simultaneamente e suas saídas são posteriormente agregadas para gerar uma resposta final. Essa abordagem reduz significativamente o tempo de processamento e aumenta a eficiência do fluxo de trabalho. Por exemplo, em um fluxo de trabalho paralelo de atendimento ao cliente, um agente recupera solicitações anteriores semelhantes, enquanto outro consulta artigos relevantes da base de conhecimento. Um agregador combina então esses resultados para gerar uma resolução abrangente.
4. Cadeia de trabalho do Orchestrator: Este fluxo de trabalho compartilha semelhanças com a paralelização devido à sua utilização de subtarefas independentes. No entanto, uma distinção fundamental reside na integração de um agente orquestrador. Este agente é responsável por analisar as consultas do usuário, segmentá-las dinamicamente em subtarefas durante a execução e identificar os processos ou ferramentas apropriados necessários para formular uma resposta precisa.

Construindo um pipeline RAG agético do zero.

Para ilustrar os princípios do RAG agentivo, vamos projetar um fluxo de trabalho usando LangChain e Elasticsearch. Este fluxo de trabalho adota uma arquitetura baseada em roteamento, onde múltiplos agentes colaboram para analisar consultas, recuperar informações relevantes, avaliar resultados e gerar respostas coerentes. Você pode consultar este notebook Jupyter para acompanhar este exemplo.

O fluxo de trabalho começa com o agente de roteamento, que analisa a consulta do usuário para selecionar o método de recuperação ideal, ou seja, uma abordagem vectorstore, websearch ou composite . O vectorstore lida com a recuperação tradicional de documentos baseada em RAG, a pesquisa na web busca as informações mais recentes que não estão armazenadas no vectorstore, e a abordagem composta combina ambas quando são necessárias informações de múltiplas fontes.

Se os documentos forem considerados adequados, o agente de sumarização gera uma resposta clara e contextualizada. No entanto, se os documentos forem insuficientes ou irrelevantes, o agente de reescrita de consultas reformula a consulta para melhorar a pesquisa. Essa consulta revisada reinicia o processo de roteamento, permitindo que o sistema refine sua busca e aprimore o resultado final.

Pré-requisitos

Este fluxo de trabalho depende dos seguintes componentes principais para executar o exemplo de forma eficaz:

• Python 3.10
• Notebook Jupyter
• Azure OpenAI
• Elasticsearch
• LangChain

Antes de prosseguir, você será solicitado a configurar o seguinte conjunto de variáveis de ambiente obrigatórias para este exemplo.

AZURE_OPENAI_ENDPOINT="Add your azure openai endpoint"
AZURE_OPENAI_KEY="Add your azure openai key"
AZURE_OPENAI_DEPLOYMENT="gpt-4.1"
AZURE_OPENAI_API_VERSION="Add your azure openai api version"

ES_ENDPOINT = "Add your Elasticsearch ENDPOINT"
ES_API_KEY = "Add your Elasticsearch API KEY"

Fontes de dados

Este fluxo de trabalho é ilustrado usando um subconjunto do conjunto de dados da AG News. O conjunto de dados inclui artigos de notícias de diversas categorias, como Internacional, Esportes, Negócios e Ciência/Tecnologia.

dataset = load_dataset("ag_news", split="train[:1000]")
docs = [
    Document(
        page_content=sample["text"],
        metadata={"category": sample["label"]}
    )
    for sample in dataset
]

O módulo ElasticsearchStore é utilizado a partir do langchain_elasticsearch como nosso armazenamento de vetores. Para a recuperação de dados, implementamos a SparseVectorStrategy, utilizando o ELSER, o modelo de incorporação proprietário da Elastic. É essencial confirmar se o modelo ELSER está instalado e implantado corretamente em seu ambiente Elasticsearch antes de iniciar o armazenamento de vetores.

elastic_vectorstore = ElasticsearchStore.from_documents(
    docs,
    es_url=ES_ENDPOINT,
    es_api_key=ES_API_KEY,
    index_name=index_name,
    strategy=SparseVectorStrategy(model_id=".elser_model_2"),
)

elastic_vectorstore.client.indices.refresh(index=index_name)

A funcionalidade de busca na web é implementada usando o DuckDuckGoSearchRun das ferramentas da comunidade LangChain, o que permite que o sistema recupere informações em tempo real da web de forma eficiente. Você também pode considerar o uso de outras APIs de busca que podem fornecer resultados mais relevantes. Essa ferramenta foi escolhida por permitir buscas sem a necessidade de uma chave de API.

duckduckgo = DuckDuckGoSearchRun(description= "A custom DuckDuckGo search tool for finding latest news stories.", verbose=True)
def websearch_retriever(query):
    results = duckduckgo.run(f"{query}")
    return results

O recuperador composto foi projetado para consultas que exigem uma combinação de fontes. É utilizado para fornecer uma resposta abrangente e contextualizada, recuperando simultaneamente dados em tempo real da web e consultando notícias históricas do banco de dados vetorial.

def composite_retriever(query):
    related_docs = vectorstore_retriever(query)
    related_docs += websearch_retriever(query)
    return related_docs

Configurar os agentes

Na etapa seguinte, os agentes LLM são definidos para fornecer capacidades de raciocínio e tomada de decisão dentro desse fluxo de trabalho. As cadeias LLM que criaremos incluem: router_chain, grade_docs_chain, rewrite_query_chain e summary_chain.

O agente de roteamento utiliza um assistente LLM para determinar a fonte de dados mais apropriada para uma determinada consulta em tempo de execução. O agente de classificação avalia os documentos recuperados quanto à sua relevância. Se os documentos forem considerados relevantes, eles são encaminhados ao agente de resumo para gerar um resumo. Caso contrário, o agente de reescrita de consultas reformula a consulta e a envia de volta ao processo de roteamento para uma nova tentativa de recuperação. Você pode encontrar as instruções para todos os agentes na seção Cadeias LLM do caderno.

class RouteQuery(BaseModel):
    datasource: Literal["vectorstore", "websearch", "composite"] = Field(
        ...,
        description="Choose to route the query to web search, vectorstore or composite."
    )

router_prompt = ChatPromptTemplate.from_template("""You are an assistant that decides the best data source for questions based on news articles.
Choose one of the following options:
- 'vectorstore': for general, background, or historical news articles.
- 'websearch': for recent discoveries, 'latest', 'current', or '2025' type queries.
- 'composite': when the question needs both historical and current knowledge on news articles.

Question: {query}

Return one word: 'vectorstore', 'websearch', or 'composite'.
""")
router_structured = llm.with_structured_output(RouteQuery)
router_chain: RunnableSequence = router_prompt | router_structured

O llm.with_structured_output restringe a saída do modelo a seguir um esquema predefinido definido pelo BaseModel sob a classe RouteQuery , garantindo a consistência dos resultados. A segunda linha compõe um RunnableSequence conectando router_prompt com router_structured, formando um pipeline no qual o prompt de entrada é processado pelo modelo de linguagem para produzir resultados estruturados e compatíveis com o esquema.

Defina os nós do grafo.

Esta parte envolve a definição dos estados do grafo, que representam os dados que fluem entre os diferentes componentes do sistema. Uma especificação clara desses estados garante que cada nó no fluxo de trabalho saiba quais informações ele pode acessar e atualizar.

class RAGState(TypedDict):
    query: str
    docs: List[Document]
    router: str
    summary: str
    self_reflection: bool
    retry_count: int = 0

Uma vez definidos os estados, o próximo passo é definir os nós do grafo. Os nós são como as unidades funcionais do grafo que executam operações específicas sobre os dados. Nosso pipeline possui 7 nós diferentes.

def router(state: RAGState):
   router = router_chain.invoke({'query': state["query"]})
   logger.info(f"Router selected the datasource: {router.datasource}")
   logger.info(f"User query: {state['query']}")
   return {"router": router.datasource}

def vectorstore(state: RAGState):
   return {"docs": vectorstore_retriever(state["query"])}

def websearch(state: RAGState):
   return {"docs": websearch_retriever(state["query"])}

def composite(state: RAGState):
   return {"docs": composite_retriever(state["query"])}

def self_reflection(state: RAGState):
   evaluation = grade_docs_chain.invoke(
       {"query": state["query"], "docs": state["docs"]}
   )
   if evaluation.binary_score:
       logger.info(f"Self-reflection passed -- binary_score={evaluation.binary_score}")
   else:
       logger.info(f"Self-reflection failed -- binary_score={evaluation.binary_score}")

   return {
       "self_reflection": evaluation.binary_score,
   }

def query_rewriter(state: RAGState):
   retry_count = state.get("retry_count", 0) + 1
   new_query = rewrite_query_chain.invoke({"query": state["query"]})
   logger.info(f"Query rewritten: {new_query}, retry_count: {retry_count}")
   return {
       "query": new_query,
       "retry_count": retry_count,
   }

def summarize(state: RAGState):
   summary = summarize_chain.run(
       query=state["query"],
       docs=state["docs"],
   )
   return {"summary": summary}

O nó query_rewriter serve a dois propósitos no fluxo de trabalho. Primeiro, ele reescreve a consulta do usuário usando o rewrite_query_chain para melhorar a recuperação quando os documentos avaliados pelo agente de autorreflexão são considerados insuficientes ou irrelevantes. Em segundo lugar, funciona como um contador que registra quantas vezes a consulta foi reescrita.

Cada vez que o nó é invocado, ele incrementa o retry_count armazenado no estado do fluxo de trabalho. Esse mecanismo impede que o fluxo de trabalho entre em um loop infinito. Se o retry_count exceder um limite predefinido, o sistema pode recorrer a um estado de erro, uma resposta padrão ou qualquer outra condição predefinida que você escolher.

Compilando o gráfico

O último passo é definir as arestas do grafo e adicionar quaisquer condições necessárias antes de compilá-lo. Cada grafo deve começar a partir de um nó inicial designado, que serve como ponto de entrada para o fluxo de trabalho. As arestas no grafo representam o fluxo de dados entre os nós e podem ser de dois tipos:

• Arestas retas: Estas definem um fluxo direto e incondicional de um nó para outro. Sempre que o primeiro nó conclui sua tarefa, o fluxo de trabalho avança automaticamente para o próximo nó ao longo da aresta reta.
• Arestas condicionais: Permitem que o fluxo de trabalho se ramifique com base no estado atual ou nos resultados da computação de um nó. O próximo nó é selecionado dinamicamente, dependendo de condições como resultados de avaliação, decisões de roteamento ou número de tentativas.

graph.add_edge(START, "router")

def after_router(state: RAGState):
   route = state.get("router", None)
   if route == "vectorstore":
       return "vectorstore"
   elif route == "websearch":
       return "websearch"
   else:
       return "composite"

def after_self_reflection(state: RAGState):
   if state["self_reflection"]:
           return "summarize"
   return "query_rewriter"

def after_query_rewriter(state: RAGState):
   while state['retry_count'] <= 3:
           return "router"
   raise RuntimeError("Maximum retries (3) reached -- evaluation failed.")

graph.add_conditional_edges(
   "router",
   after_router,
   {
       "vectorstore": "vectorstore",
       "websearch": "websearch",
       "composite": "composite"
   }
)

graph.add_edge("vectorstore", "self_reflection")
graph.add_edge("websearch", "self_reflection")
graph.add_edge("composite", "self_reflection")
graph.add_conditional_edges(
   "self_reflection",
   after_self_reflection,
   {
       "summarize": "summarize",
       "query_rewriter": "query_rewriter"
   }
)
graph.add_conditional_edges("query_rewriter", after_query_rewriter, {"router": "router"})
graph.add_edge("summarize", END)
agent=graph.compile()

Com isso, seu primeiro pipeline RAG agentivo está pronto e pode ser testado usando o agente compilado.

result = agent.invoke({"query": query1})
logger.info(f"\nFinal Summary:\n: {result['summary']}")

Testando o pipeline RAG agentivo

Agora vamos testar esse pipeline usando três tipos distintos de consultas, conforme descrito abaixo. Note que os resultados podem variar, e os exemplos mostrados abaixo ilustram apenas um resultado possível.

query1="What are the latest AI models released this month?"
query2="What technological innovations are discussed in Sci/Tech news?"
query3="Compare a Sci/Tech article from the dataset with a current web article about AI trends."

Para a primeira consulta, o roteador seleciona websearch como fonte de dados. A consulta falha na avaliação de autorreflexão e, consequentemente, é redirecionada para a etapa de reescrita da consulta, conforme mostrado na saída.

INFO     | __main__:router:11 - Router selected the datasource: websearch
INFO     | __main__:router:12 - User query: What are the latest AI models released this month?
Latest Singapore news, including the city state's relationships with Malaysia and Mahathir, China and Xi Jinping, and the rest of Southeast Asia. 3 days ago · The latest military news, insights and analysis from China. All the latest news, opinions and analysis on Hong Kong, China, Asia and around the world Latest news, in-depth features and opinion on Malaysia, covering politics, economy, society and the Asean member-nation's relationships with China, Singapore, and other Southeast Asian ... Oct 12, 2025 · Brics (an acronym for Brazil, Russia, India, China and South Africa) refers to an association of 10 leading emerging markets. The other member states are Egypt, Ethiopia, ...
INFO     | __main__:self_reflection:31 - Self-reflection failed -- binary_score=False
INFO     | __main__:query_rewriter:40 - Query rewritten: query='Which AI models have been officially released in June 2024?', retry_count: 1
INFO     | __main__:router:11 - Router selected the datasource: websearch
INFO     | __main__:router:12 - User query: query='Which AI models have been officially released in June 2024?'
Dream Machine is a text-to-video model created by Luma Labs and launched in June 2024 . It generates video output based on user prompts or still images. Dream Machine has been noted for its ability to realistically capture motion... Released in June 2023. In June 2024 , Baidu announced Ernie 4.0 Turbo. In April 2025, Ernie 4.5 Turbo and X1 Turbo were released . These models are optimized for faster response times and lower operational costs.[28][29]. The meaning of QUERY is question, inquiry. How to use query in a sentence. Synonym Discussion of Query. QUERY definition: 1. a question, often expressing doubt about something or looking for an answer from an authority.... Learn more. Query definition: a question; an inquiry.. See examples of QUERY used in a sentence.
INFO     | __main__:self_reflection:29 - Self-reflection passed -- binary_score=True
INFO     | __main__::2 - 
Final Summary:
: In June 2024, two AI models were officially released: Dream Machine, a text-to-video model launched by Luma Labs, and Ernie 4.0 Turbo, announced by Baidu, which is optimized for faster response times and lower operational costs.

Em seguida, examinamos um exemplo onde a recuperação vectorstore é usada, demonstrado com a segunda consulta.

INFO     | __main__:router:11 - Router selected the datasource: vectorstore
INFO     | __main__:router:12 - User query: What technological innovations are discussed in Sci/Tech news?
INFO     | __main__:self_reflection:29 - Self-reflection passed -- binary_score=True
INFO     | __main__::2 - 
Final Summary:
: Recent Sci/Tech news highlights several technological innovations: NASA is collaborating with Silicon Valley firms to build a powerful Linux-based supercomputer to support theoretical research and shuttle engineering; new chromatin transfer techniques have enabled the cloning of cats; cybersecurity advancements are being discussed in relation to protecting personal technology; Princeton University scientists assert that existing technologies can be used immediately to stabilize global warming; and a set of GameBoy micro-games has been recognized for innovation in game design.

A consulta final é direcionada à recuperação composta, que utiliza tanto o armazenamento vetorial quanto a pesquisa na web.

INFO     | __main__:router:11 - Router selected the datasource: composite
INFO     | __main__:router:12 - User query: Compare a Sci/Tech article from the dataset with a current web article about AI trends.
Atlas currently only available on macOS, built on Chromium with planned features like ad-blocking still in development. OpenAI's Atlas browser launched with bold promises of AI -powered web browsing, but early real-world testing reveals a different story. Career-long data are updated to end-of-2024 and single recent year data pertain to citations received during calendar year 2024. The selection is based on the top 100,000 scientists by c-score (with and without self-citations) or a percentile rank of 2% or above in the sub-field. In this article I list 45 AI tools across 21 different categories. After exploring all the available options in each category, I've carefully selected the best tools based on my personal experience. Reading a complex technical article ? Simply highlight confusing terminology and ask "what's this?" to receive instant explanations. compare browsers. Comparison showing traditional browser navigation versus OpenAI Atlas AI -powered workflows. After putting Gemini, ChatGPT, Grok, and DeepSeek through rigorous testing in October 2025, it's clear that there isn't one AI that reigns supreme across all categories.
INFO     | __main__:self_reflection:29 - Self-reflection passed -- binary_score=True
INFO     | __main__::2 - 
Final Summary:
: A Sci/Tech article from the dataset highlights NASA's development of robust artificial intelligence software for planetary rovers, aiming to make them more self-reliant and capable of decision-making during missions. In contrast, a current web article about AI trends focuses on the proliferation of AI-powered tools across various categories, including browsers like OpenAI Atlas, and compares leading models such as Gemini, ChatGPT, Grok, and DeepSeek, noting that no single AI currently excels in all areas. While the NASA article emphasizes specialized AI applications for autonomous robotics in space exploration, the current trends article showcases the broadening impact of AI across consumer and professional technologies, with ongoing competition and rapid innovation among major AI platforms.

No fluxo de trabalho acima, o RAG agente determina de forma inteligente qual fonte de dados usar ao recuperar informações para uma consulta do usuário, melhorando assim a precisão e a relevância da resposta. Você pode criar exemplos adicionais para testar o agente e analisar os resultados para verificar se eles produzem algum resultado interessante.

Melhores práticas para a construção de fluxos de trabalho RAG com agentes

Agora que entendemos como o RAG agético funciona, vamos analisar algumas práticas recomendadas para a construção desses fluxos de trabalho. Seguir estas diretrizes ajudará a manter o sistema eficiente e de fácil manutenção.

• Prepare-se para planos de contingência: Planeje estratégias alternativas com antecedência para cenários em que qualquer etapa do fluxo de trabalho falhe. Isso pode incluir retornar respostas padrão, acionar estados de erro ou usar ferramentas alternativas. Isso garante que o sistema lide com as falhas de forma adequada, sem interromper o fluxo de trabalho geral.
• Implemente um registro abrangente: tente implementar o registro em cada etapa do fluxo de trabalho, como novas tentativas, saídas geradas, opções de roteamento e reescritas de consultas. Esses registros ajudam a melhorar a transparência, facilitam a depuração e auxiliam no aprimoramento de prompts, comportamento do agente e estratégias de recuperação ao longo do tempo.
• Selecione o padrão de fluxo de trabalho apropriado: Analise seu caso de uso e selecione o padrão de fluxo de trabalho que melhor atenda às suas necessidades. Utilize fluxos de trabalho sequenciais para raciocínio passo a passo, fluxos de trabalho paralelos para fontes de dados independentes e padrões de orquestrador-trabalhador para consultas complexas ou que envolvam múltiplas ferramentas.
• Incorporar estratégias de avaliação: Integrar mecanismos de avaliação em diferentes etapas do fluxo de trabalho. Isso pode incluir agentes de autorreflexão, classificação de documentos recuperados ou verificações de qualidade automatizadas. A avaliação ajuda a verificar se os documentos recuperados são relevantes, se as respostas são precisas e se todas as partes de uma consulta complexa foram abordadas.

Desafios

Embora os sistemas RAG agentivos ofereçam vantagens significativas em termos de adaptabilidade, precisão e raciocínio dinâmico, eles também apresentam certos desafios que devem ser abordados durante as fases de projeto e implementação. Alguns dos principais desafios incluem:

• Fluxos de trabalho complexos: À medida que mais agentes e pontos de decisão são adicionados, o fluxo de trabalho geral torna-se cada vez mais complexo. Isso pode levar a uma maior probabilidade de erros ou falhas em tempo de execução. Sempre que possível, priorize fluxos de trabalho simplificados, eliminando agentes redundantes e pontos de decisão desnecessários.
• Escalabilidade: Pode ser desafiador dimensionar sistemas RAG com agentes para lidar com grandes conjuntos de dados e altos volumes de consultas. Incorpore estratégias eficientes de indexação, armazenamento em cache e processamento distribuído para manter o desempenho em grande escala.
• Orquestração e sobrecarga computacional: A execução de fluxos de trabalho com múltiplos agentes requer orquestração avançada. Isso inclui um planejamento cuidadoso, gerenciamento de dependências e coordenação de agentes para evitar gargalos e conflitos, fatores que contribuem para a complexidade geral do sistema.
• Complexidade da avaliação: A avaliação desses fluxos de trabalho apresenta desafios inerentes, uma vez que cada etapa requer uma estratégia de avaliação distinta. Por exemplo, a etapa RAG deve ser avaliada quanto à relevância e completude dos documentos recuperados, enquanto os resumos gerados precisam ser verificados quanto à qualidade e precisão. Da mesma forma, a eficácia da reformulação de consultas requer uma lógica de avaliação separada para determinar se a consulta reescrita melhora os resultados da recuperação.

Conclusão

Neste post do blog, apresentamos o conceito de RAG agente e destacamos como ele aprimora a estrutura tradicional de RAG, incorporando capacidades autônomas da IA agente. Exploramos as principais funcionalidades do RAG agentivo e demonstramos essas funcionalidades por meio de um exemplo prático, construindo um assistente de notícias usando o Elasticsearch como repositório de vetores e o LangChain para criar a estrutura agentiva.

Além disso, discutimos as melhores práticas e os principais desafios a serem considerados ao projetar e implementar um pipeline RAG com agentes. Essas informações têm como objetivo orientar os desenvolvedores na criação de sistemas de agentes robustos, escaláveis e eficientes que combinem efetivamente recuperação de dados, raciocínio e tomada de decisões.

O que vem a seguir

O fluxo de trabalho que desenvolvemos é simples, deixando bastante espaço para melhorias e experimentação. Podemos melhorar isso experimentando com vários modelos de incorporação e refinando as estratégias de recuperação. Além disso, a integração de um agente de reclassificação para priorizar os documentos recuperados pode ser benéfica. Outra área a ser explorada envolve o desenvolvimento de estratégias de avaliação para estruturas de agentes, especificamente a identificação de abordagens comuns e reutilizáveis aplicáveis a diferentes tipos de estruturas. Por fim, experimentar essas estruturas em conjuntos de dados grandes e mais complexos.

Entretanto, se você tiver experiências semelhantes para compartilhar, adoraríamos saber mais sobre elas! Fique à vontade para enviar seus comentários ou entrar em contato conosco por meio do nosso canal da comunidade no Slack ou dos fóruns de discussão.

Recursos

• Auto-RAG: Aprendendo a Recuperar, Gerar e Criticar por meio da Autorreflexão
• Geração Aumentada por Recuperação Agencial: Uma Análise sobre RAG Agencial

O problema da amplitude de pontuação

Para contextualizar, vamos analisar um dos principais motivos pelos quais a busca híbrida pode ser difícil: a variação nos intervalos de pontuação. Nosso velho amigo BM25 produz pontuações ilimitadas. Em outras palavras, o BM25 pode gerar pontuações que variam de perto de 0 até (teoricamente) o infinito. Em contraste, as consultas aos campos dense_vector produzirão pontuações limitadas entre 0 e 1. Exacerbando este problema, semantic_text ofusca o tipo de campo usado para indexar embeddings, portanto, a menos que você tenha conhecimento detalhado sobre a configuração do seu índice e endpoint de inferência, pode ser difícil dizer qual será o intervalo de pontuação da sua consulta. Isso representa um problema ao tentar intercalar resultados de busca lexical e semântica, já que os resultados lexicais podem ter precedência sobre os semânticos, mesmo que os resultados semânticos sejam mais relevantes. A solução geralmente aceita para esse problema é normalizar as pontuações antes de intercalar os resultados. O Elasticsearch possui duas ferramentas para isso: os recuperadores lineares e RRF .

O recuperador RRF aplica o algoritmo RRF, usando a classificação do documento como medida de relevância e descartando a pontuação. Como a pontuação não é considerada, as discrepâncias na faixa de pontuação não representam um problema.

O recuperador linear utiliza uma combinação linear para determinar a pontuação final de um documento. Isso envolve pegar a pontuação de cada consulta de componente para o documento, normalizá-la e somá-las para gerar a pontuação total. Matematicamente, a operação pode ser expressa como:

Total Score = 𝚺(N(Sx))

Onde N é a função de normalização e SX é a pontuação para a consulta X. A função de normalização é fundamental aqui, pois transforma a pontuação de cada consulta para usar o mesmo intervalo. Você pode aprender mais sobre o recuperador linear aqui.

Analisando detalhadamente

Os usuários podem implementar uma busca híbrida eficaz com essas ferramentas, mas isso requer algum conhecimento sobre o seu índice. Vejamos um exemplo com o recuperador linear, onde consultaremos um índice com dois campos:

PUT linear_retriever_example
{
  "mappings": {
    "properties": {
      "semantic_text_field": { <1>
        "type": "semantic_text",
        "inference_id": ".multilingual-e5-small-elasticsearch"
      },
      "text_field": { <2>
        "type": "text"
      }
    }
  }
}

1. semantic_text_field é um campo semantic_text que usa E5, um modelo de incorporação de texto.

2. text_field é um campo text padrão

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "retrievers": [
        {
          "retriever": {
            "standard": {
              "query": {
                "match": { <1>
                  "semantic_text_field": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        },
        {
          "retriever": {
            "standard": {
              "query": {
                "match": {
                  "text_field": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        }
      ]
    }
  }
}

1. Usamos uma consulta match em nosso campo semantic_text , para o qual adicionamos suporte no Elasticsearch 8.18/9.0

Ao construir a consulta, precisamos ter em mente que semantic_text_field usa um modelo de incorporação de texto, portanto, quaisquer consultas sobre ele gerarão uma pontuação entre 0 e 1. Precisamos também saber que text_field é um campo text padrão e, portanto, as consultas nele gerarão uma pontuação ilimitada. Para criar um conjunto de resultados com a relevância adequada, precisamos usar um mecanismo de recuperação que normalize as pontuações das consultas antes de combiná-las. Neste exemplo, usamos o recuperador linear com normalização minmax , que normaliza a pontuação de cada consulta para um valor entre 0 e 1.

A construção da consulta neste exemplo é bastante simples, pois envolve apenas dois campos. No entanto, a situação pode se complicar rapidamente à medida que mais campos, e de tipos variados, são adicionados. Isso demonstra como escrever uma consulta de pesquisa híbrida eficaz geralmente requer um conhecimento mais profundo do índice consultado, para que as pontuações das consultas componentes sejam devidamente normalizadas antes da combinação. Isso representa uma barreira para a adoção mais ampla da busca híbrida.

Agrupamento de consultas

Vamos expandir o exemplo: E se quiséssemos consultar um campo text e dois campos semantic_text ? Poderíamos construir uma consulta como esta:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "retrievers": [
        {
          "retriever": {
            "standard": {
              "query": {
                "semantic": {
                  "field": "semantic_text_field_1",
                  "query": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        },
        {
          "retriever": {
            "standard": {
              "query": {
                "semantic": {
                  "field": "semantic_text_field_2",
                  "query": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        },
        {
          "retriever": {
            "standard": {
              "query": {
                "match": {
                  "text_field": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        }
      ]
    }
  }
}

Isso parece bom à primeira vista, mas existe um problema em potencial. Agora, as correspondências do campo semantic_text representam ⅔ da pontuação total:

Total Score = N(semantic_text_field_1 score) + N(semantic_text_field_2 score) + N(text_field score)

Provavelmente não é isso que você deseja, pois cria uma pontuação desequilibrada. Os efeitos podem não ser tão perceptíveis em um exemplo como este, com apenas 3 campos, mas tornam-se problemáticos quando mais campos são consultados. Por exemplo, a maioria dos índices contém muito mais campos lexicais do que semânticos (ou seja, dense_vector, sparse_vector ou semantic_text). E se estivéssemos consultando um índice com 9 campos lexicais e 1 campo semântico usando o padrão acima? As correspondências lexicais representariam 90% da pontuação, diminuindo a eficácia da busca semântica.

Uma forma comum de resolver isso é agrupar as consultas em categorias lexicais e semânticas e atribuir pesos iguais a ambas. Isso impede que qualquer uma das categorias domine a pontuação total.

Vamos colocar isso em prática. Como seria essa abordagem de consultas agrupadas neste exemplo ao usar o recuperador linear?

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "retrievers": [
        {
          "retriever": {
            "linear": {
              "retrievers": [
                {
                  "retriever": {
                    "standard": {
                      "query": {
                        "semantic": {
                          "field": "semantic_text_field_1",
                          "query": "foo"
                        }
                      }
                    }
                  },
                  "normalizer": "minmax"
                },
                {
                  "retriever": {
                    "standard": {
                      "query": {
                        "semantic": {
                          "field": "semantic_text_field_2",
                          "query": "foo"
                        }
                      }
                    }
                  },
                  "normalizer": "minmax"
                }
              ]
            }
          },
          "normalizer": "minmax"
        },
        {
          "retriever": {
            "standard": {
              "query": {
                "match": {
                  "text_field": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        }
      ]
    }
  }
}

Uau, isso está ficando prolixo! Você pode até ter precisado rolar a página para cima e para baixo várias vezes para examinar toda a consulta! Aqui, utilizamos dois níveis de normalização para criar os grupos de consulta. Matematicamente, pode ser expresso como:

Total Score = N(N(semantic_text_field_1 score) + N(semantic_text_field_2 score)) + N(text_field score)

Este segundo nível de normalização garante que as consultas aos campos semantic_text e text sejam ponderadas igualmente. Observe que omitimos a normalização de segundo nível para text_field neste exemplo, uma vez que há apenas um campo lexical, poupando-o de ainda mais verbosidade.

Essa estrutura de consulta já é complexa demais, e estamos consultando apenas três campos. À medida que se consultam mais campos, a tarefa torna-se cada vez mais difícil de gerir, mesmo para profissionais de pesquisa experientes.

O formato de consulta com vários campos

Adicionamos o formato de consulta com vários campos para os recuperadores lineares e RRF no Elasticsearch 8.19, 9.1 e serverless para simplificar tudo isso. Agora você pode realizar a mesma consulta acima apenas com:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_1", "semantic_text_field_2", "text_field" ],
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

O que reduz a consulta de 55 linhas para apenas 9! O Elasticsearch usa automaticamente os mapeamentos de índice para:

• Determine o tipo de cada campo consultado.
• Agrupe cada campo em uma categoria lexical ou semântica.
• Dê o mesmo peso a cada categoria na pontuação final.

Isso permite que qualquer pessoa execute uma consulta de pesquisa híbrida eficaz sem precisar saber detalhes sobre o índice ou os endpoints de inferência utilizados.

Ao usar o RRF, você pode omitir o normalizer, já que a classificação é usada como um indicador de relevância:

GET rrf_retriever_example/_search
{
  "retriever": {
    "rrf": {
      "fields": [ "semantic_text_field_1", "semantic_text_field_2", "text_field" ],
      "query": "foo"
    }
  }
}

Aumento por campo

Ao usar o recuperador linear, você pode aplicar um reforço por campo para ajustar a importância das correspondências em determinados campos. Por exemplo, digamos que você esteja consultando quatro campos: dois campos semantic_text e dois campos text :

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_1", "semantic_text_field_2", "text_field_1", "text_field_2" ],
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

Por padrão, cada campo tem o mesmo peso em seu grupo (lexical ou semântico). A distribuição da pontuação é a seguinte:

Em outras palavras, cada área corresponde a 25% da pontuação total.

Podemos usar a sintaxe field^boost para adicionar um aumento por campo a qualquer campo. Vamos aplicar um aumento de 2 a semantic_text_field_1 e text_field_1:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_1^2", "semantic_text_field_2", "text_field_1^2", "text_field_2" ]
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

Agora a distribuição da pontuação é a seguinte:

Cada grupo de consultas ainda tem o mesmo peso, mas agora o peso dos campos dentro dos grupos foi alterado:

• semantic_text_field_1 representa 66% da pontuação do grupo de consultas semânticas e 33% da pontuação total.
• text_field_1 representa 66% da pontuação do grupo de consulta lexical e 33% da pontuação total.

Resolução curinga

Você pode usar o caractere curinga * no parâmetro fields para corresponder a vários campos. Continuando o exemplo acima, esta consulta é funcionalmente equivalente a consultar explicitamente semantic_text_field_1, semantic_text_field_2 e text_field_1 :

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_*", "*_field_1" ],
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

É interessante notar que o padrão *_field_1 corresponde tanto text_field_1 quanto a semantic_text_field_1. Isso é tratado automaticamente; a consulta será executada como se cada um dos campos tivesse sido consultado explicitamente. Também não há problema em que semantic_text_field_1 corresponda a ambos os padrões; todas as correspondências de nomes de campos são desduplicadas antes da execução da consulta.

Você pode usar o caractere curinga de diversas maneiras:

• Correspondência de prefixo (ex: *_text_field)
• Correspondência em linha (ex: semantic_*_field)
• Correspondência de sufixo (ex: semantic_text_field_*)

Você também pode usar vários curingas para aplicar uma combinação do acima, como *_text_field_*.

Campos de consulta padrão

O formato de consulta com vários campos também permite consultar um índice sobre o qual você não sabe nada. Se você omitir o parâmetro fields , a consulta abrangerá todos os campos especificados pela configuração de índice index.query.default_field:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

Por padrão, index.query.default_field é definido como *. Este caractere curinga será resolvido para todos os tipos de campo no índice que suportam consultas por termo, que são a maioria. As exceções são:

• dense_vector campos
• rank_vector campos
• Campos geométricos: geo_point, shape

Essa funcionalidade é especialmente útil quando você deseja realizar uma consulta de pesquisa híbrida em um índice fornecido por terceiros. O formato de consulta com vários campos permite executar uma consulta adequada de forma simples. Basta excluir o parâmetro fields e todos os campos aplicáveis serão consultados.

Conclusão

O problema do intervalo de pontuação pode tornar a implementação de uma busca híbrida eficaz bastante complexa, especialmente quando há pouca informação sobre o índice consultado ou os endpoints de inferência em uso. O formato de consulta com múltiplos campos para os mecanismos de recuperação linear e RRF atenua esse problema, integrando uma abordagem de busca híbrida automatizada, baseada em agrupamento de consultas, em uma API simples e acessível. Funcionalidades adicionais, como reforço por campo, resolução de curingas e campos de consulta padrão, ampliam a funcionalidade para abranger diversos casos de uso.

Experimente o formato de consulta com vários campos hoje mesmo.

Você pode conferir os mecanismos de recuperação linear e RRF com o formato de consulta de múltiplos campos em projetos Elasticsearch Serverless totalmente gerenciados, com um período de avaliação gratuito. Também está disponível em versões de pilha a partir das versões 8.19 e 9.1.

Comece em minutos no seu ambiente local com um único comando:

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

Este artigo mostrará como criar um agente de IA para RH usando GPT-OSS e Elastic Agent Builder. O agente pode responder às suas perguntas sem enviar dados para a OpenAI, Anthropic ou qualquer serviço externo.

Usaremos o LM Studio para disponibilizar o GPT-OSS localmente e conectá-lo ao Elastic Agent Builder.

Ao final deste artigo, você terá um agente de IA personalizado capaz de responder a perguntas em linguagem natural sobre os dados de seus funcionários, mantendo o controle total sobre suas informações e modelo.

Pré-requisitos

Para ler este artigo, você precisa de:

• Elastic Cloud hospedado na versão 9.2, implantação local ou sem servidor.
• Recomenda-se máquina com 32 GB de RAM (mínimo de 16 GB para GPT-OSS 20B).
• LM Studio instalado
• Docker Desktop instalado

Por que usar GPT-OSS?

Com um LLM local, você tem o controle para implantá-lo em sua própria infraestrutura e ajustá-lo para atender às suas necessidades específicas. Tudo isso mantendo o controle sobre os dados que você compartilha com o modelo e, claro, sem precisar pagar nenhuma taxa de licença a um fornecedor externo.

A OpenAI lançou o GPT-OSS em 5 de agosto de 2025, como parte de seu compromisso com o ecossistema de modelos abertos.

O modelo de parâmetros 20B oferece:

• capacidades de utilização da ferramenta
• Inferência eficiente
• Compatível com o SDK OpenAI
• Compatível com fluxos de trabalho agentes

Comparação de referência:

Arquitetura da solução

A arquitetura é executada inteiramente em sua máquina local. O Elastic (executado em um contêiner Docker) se comunica diretamente com seu LLM local por meio do LM Studio, e o Elastic Agent Builder usa essa conexão para criar agentes de IA personalizados que podem consultar os dados de seus funcionários.

Para obter mais detalhes, consulte esta documentação.

Construindo um agente de IA para RH: Etapas

Dividiremos a implementação em 5 etapas:

1. Configure o LM Studio com um modelo local.
2. Implante o Elastic local com o Docker.
3. Crie o conector OpenAI no Elastic
4. Carregar dados de funcionários no Elasticsearch
5. Crie e teste seu agente de IA.

Etapa 1: Configurar o LM Studio com GPT-OSS 20B

O LM Studio é um aplicativo fácil de usar que permite executar grandes modelos de linguagem localmente em seu computador. Ele fornece um servidor de API compatível com OpenAI, facilitando a integração com ferramentas como o Elastic, sem um processo de configuração complexo. Para obter mais detalhes, consulte a documentação do LM Studio.

Primeiro, baixe e instale o LM Studio a partir do site oficial. Após a instalação, abra o aplicativo.

Na interface do LM Studio:

1. Acesse a aba de pesquisa e procure por “GPT-OSS”.
2. Selecione o openai/gpt-oss-20b da OpenAI
3. Clique em baixar

O tamanho deste modelo deverá ser de aproximadamente 12,10 GB. O download pode demorar alguns minutos, dependendo da sua conexão com a internet.

Após o download do modelo:

1. Acesse a aba do servidor local.
2. Selecione o openai/gpt-oss-20b
3. Use a porta padrão 1234
4. No painel direito, acesse Carregar e defina o Comprimento do Contexto para 40K ou mais.

5. Clique em Iniciar servidor

Você deverá ver isso se o servidor estiver em execução.

[LM STUDIO SERVER] Success! HTTP server listening on port 1234
[LM STUDIO SERVER] Supported endpoints:
[LM STUDIO SERVER] ->	GET  http://localhost:1234/v1/models
[LM STUDIO SERVER] ->	POST http://localhost:1234/v1/responses
[LM STUDIO SERVER] ->	POST http://localhost:1234/v1/chat/completions
[LM STUDIO SERVER] ->	POST http://localhost:1234/v1/completions
[LM STUDIO SERVER] ->	POST http://localhost:1234/v1/embeddings
Server started.

Etapa 2: Implante o Elastic local com o Docker

Agora vamos configurar o Elasticsearch e o Kibana localmente usando o Docker. A Elastic fornece um script prático que lida com todo o processo de configuração. Para obter mais detalhes, consulte a documentação oficial.

Execute o script start-local

Execute o seguinte comando no seu terminal:

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

Este script irá:

• Baixe e configure o Elasticsearch e o Kibana.
• Inicie ambos os serviços usando o Docker Compose.
• Ative automaticamente uma licença de avaliação Platinum de 30 dias.

Resultado esperado

Aguarde a seguinte mensagem e salve a senha e a chave da API exibidas; você precisará delas para acessar o Kibana:

🎉 Congrats, Elasticsearch and Kibana are installed and running in Docker!
🌐 Open your browser at http://localhost:5601
   Username: elastic
   Password: KSUlOMNr
🔌 Elasticsearch API endpoint: http://localhost:9200
🔑 API key: cnJGX0pwb0JhOG00cmNJVklUNXg6cnNJdXZWMnM4bncwMllpQlFlUTlWdw==
Learn more at https://github.com/elastic/start-local

Acesse o Kibana

Abra seu navegador e acesse:

http://localhost:5601

Faça login utilizando as credenciais obtidas na saída do terminal.

Habilitar o Construtor de Agentes

Após fazer login no Kibana, navegue até Gerenciamento > IA > Construtor de Agentes e ative o Construtor de Agentes.

Etapa 3: Crie o conector OpenAI no Elastic

Agora vamos configurar o Elastic para usar seu LLM local.

Conectores de acesso

1. Em Kibana
2. Acesse Configurações do projeto > Gerenciamento
3. Em Alertas e insights, selecione Conectores.
4. Clique em Criar conector

Configure o conector

Selecione OpenAI na lista de conectores. O LM Studio utiliza o SDK da OpenAI, o que o torna compatível.

Preencha os campos com estes valores:

• Nome do conector: LM Studio - GPT-OSS 20B
• Selecione um provedor OpenAI: Outro (Serviço compatível com OpenAI)
• URL: http://host.docker.internal:1234/v1/chat/completions
• Modelo padrão: openai/gpt-oss-20b
• Chave da API: testkey-123 (qualquer texto funciona, pois o LM Studio Server não requer autenticação).

Para finalizar a configuração, clique em Salvar e testar.

Importante: Ative a opção “Habilitar chamada de função nativa”; isso é necessário para que o Construtor de Agentes funcione corretamente. Se você não habilitar isso, você receberá um erro No tool calls found in the response .

Teste a conexão

O Elastic deve testar a conexão automaticamente. Se tudo estiver configurado corretamente, você verá uma mensagem de sucesso como esta:

Resposta.

{
  "status": "ok",
  "data": {
    "id": "chatcmpl-flj9h0hy4wcx4bfson00an",
    "object": "chat.completion",
    "created": 1761189456,
    "model": "openai/gpt-oss-20b",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "Hello! 👋 How can I assist you today?",
          "reasoning": "Just greet.",
          "tool_calls": []
        },
        "logprobs": null,
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 69,
      "completion_tokens": 23,
      "total_tokens": 92
    },
    "stats": {},
    "system_fingerprint": "openai/gpt-oss-20b"
  },
  "actionId": "ee1c3aaf-bad0-4ada-8149-118f52dad757"
}

Etapa 4: Carregar os dados dos funcionários no Elasticsearch

Agora vamos carregar o conjunto de dados de funcionários de RH para demonstrar como o agente trabalha com dados confidenciais. Eu gerei um conjunto de dados fictício com essa estrutura.

Estrutura do conjunto de dados

{
  "employee_id": "0f4dce68-2a09-4cb1-b2af-6bcb4821539b",
  "full_name": "Daffi Stiebler",
  "email": "lscutchings0@huffingtonpost.com",
  "date_of_birth": "1975-06-20T15:39:36Z",
  "hire_date": "2025-07-28T00:10:45Z",
  "job_title": "Physical Therapy Assistant",
  "department": "HR",
  "salary": "108455",
  "performance_rating": "Needs Improvement",
  "years_of_experience": 2,
  "skills": "Java",
  "education_level": "Master's Degree",
  "manager": "Carl MacGibbon",
  "emergency_contact": "Leigha Scutchings",
  "home_address": "5571 6th Park"
}

Criar o índice com mapeamentos

Primeiro, crie o índice com os mapeamentos adequados. Observe que estamos usando campos semantic_text para alguns campos-chave; isso possibilita recursos de busca semântica em nosso índice.

​​PUT hr-employees
{
  "mappings": {
    "properties": {
      "@timestamp": {
        "type": "date"
      },
      "employee_id": {
        "type": "keyword"
      },
      "full_name": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "email": {
        "type": "keyword"
      },
      "date_of_birth": {
        "type": "date",
        "format": "iso8601"
      },
      "hire_date": {
        "type": "date",
        "format": "iso8601"
      },
      "job_title": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "department": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "salary": {
        "type": "double"
      },
      "performance_rating": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "years_of_experience": {
        "type": "long"
      },
      "skills": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "education_level": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "manager": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "emergency_contact": {
        "type": "keyword"
      },
      "home_address": {
        "type": "keyword"
      },
      "employee_semantic": {
        "type": "semantic_text"
      }
    }
  }
}

Indexar com API em lote

Copie e cole o conjunto de dados nas suas Ferramentas de Desenvolvedor no Kibana e execute-o:

POST hr-employees/_bulk
{"index": {}}
{"employee_id": "57728b91-e5d7-4fa8-954a-2384040d3886", "full_name": "Filide Gane", "email": "vhallahan1@booking.com", "job_title": "Business Systems Development Analyst", "department": "Marketing", "salary": "$52330.27", "performance_rating": "Meets Expectations", "years_of_experience": 12, "skills": "Java", "education_level": "Bachelor's Degree", "date_of_birth": "2000-02-07T16:49:32Z", "hire_date": "2023-11-07T13:03:16Z", "manager": "Freedman Kings", "emergency_contact": "Vilhelmina Hallahan", "home_address": "75 Dennis Junction"}
{"index": {}}
{"employee_id": "...", ...}

Verifique os dados

Execute uma consulta para verificar:

GET hr-employees/_search

Etapa 5: Crie e teste seu agente de IA

Com tudo configurado, é hora de criar um agente de IA personalizado usando o Elastic Agent Builder. Para obter mais detalhes, consulte a documentação da Elastic.

Adicione o conector

Antes de podermos criar nosso novo agente, precisamos configurar nosso construtor de agentes para usar nosso conector personalizado chamado LM Studio - GPT-OSS 20B , porque o padrão é o Elastic Managed LLM. Para isso, precisamos acessar Configurações do Projeto > Gerenciamento > Configurações do GenAI; agora selecionamos a que criamos e clicamos em Salvar.

Construtor de Agentes de Acesso

1. Acesse a seção de Agentes.
2. Clique em Criar um novo agente

Configure o agente

Para criar um novo agente, os campos obrigatórios são o ID do Agente, o Nome de Exibição e as Instruções de Exibição.

Mas existem mais opções de personalização, como as Instruções Personalizadas, que orientam o comportamento do seu agente e a forma como ele interagirá com as suas ferramentas, de forma semelhante a um prompt do sistema, mas para o nosso agente personalizado. As etiquetas ajudam a organizar seus agentes, a cor do avatar e o símbolo do avatar.

Os agentes que escolhi para o nosso agente, com base no conjunto de dados, são:

ID do agente: hr_assistant

Instruções personalizadas:

You are an HR Analytics Assistant that helps answer questions about employee data.
When responding to queries:
- Provide clear, concise answers
- Include relevant employee details (name, department, salary, skills)
- Format monetary values with currency symbols
- Be professional and maintain data confidentiality

Rótulos: Human Resources e GPT-OSS

Nome de exibição: HR Analytics Assistant

Descrição da tela:

A specialized AI assistant for Human Resources that helps analyze employee data, compensation, performance metrics, and talent management. Ask questions about employees, departments, salaries, or performance analytics.

Com todos os dados inseridos, podemos clicar em Salvar nosso novo agente.

Teste o agente

Agora você pode fazer perguntas em linguagem natural sobre os dados de seus funcionários, e o GPT-OSS 20B entenderá a intenção e gerará uma resposta apropriada.

Incitar:

Which employee is the one with the highest salary in the hr-employees index?

Responder:

O processo do Agente foi o seguinte:

1. Compreenda sua pergunta usando o conector GPT-OSS.

2. Gere a consulta Elasticsearch apropriada (usando as ferramentas integradas ou ES|QL personalizado).

3. Recuperar registros de funcionários correspondentes

4. Apresentar os resultados em linguagem natural com formatação adequada.

Diferentemente da busca lexical tradicional, o agente baseado em GPT-OSS entende a intenção e o contexto, facilitando a localização de informações sem a necessidade de conhecer os nomes exatos dos campos ou a sintaxe da consulta. Para obter mais detalhes sobre o processo de pensamento do agente, consulte este artigo.

Conclusão

Neste artigo, criamos um agente de IA personalizado usando o Agent Builder da Elastic para conectar-se ao modelo GPT-OSS da OpenAI em execução localmente. Ao implantar o Elastic e o LLM em sua máquina local, essa arquitetura permite que você aproveite os recursos de IA generativa, mantendo o controle total sobre seus dados, tudo isso sem enviar informações para serviços externos.

Utilizamos o GPT-OSS 20B como experimento, mas os modelos oficialmente recomendados para o Elastic Agent Builder podem ser consultados aqui. Se você precisar de recursos de raciocínio mais avançados, existe também a variante com 120 parâmetros , que apresenta melhor desempenho em cenários complexos, embora exija uma máquina com especificações mais altas para ser executada localmente. Para obter mais detalhes, consulte a documentação oficial da OpenAI.

Há algumas semanas, tivemos a incrível oportunidade de patrocinar o Cal Hacks 12.0, um dos maiores hackathons presenciais, com mais de 2.000 participantes vindos de todo o mundo. Oferecemos uma categoria de prêmios dedicada ao melhor uso do Elastic Agent Builder em Serverless, e a resposta foi fenomenal. Em apenas 36 horas, recebemos 29 projetos que utilizaram o Agent Builder de maneiras criativas, desde a criação de ferramentas de inteligência contra incêndios florestais até validadores do StackOverflow.

Além dos projetos impressionantes, a experiência no Cal Hacks 12.0 também nos proporcionou algo igualmente valioso: feedback rápido e direto de desenvolvedores que estavam tendo contato com nossa Stack pela primeira vez. Hackathons são testes de pressão únicos, com prazos apertados, zero familiaridade prévia e obstáculos imprevisíveis (como as infames quedas de Wi-Fi). Eles revelam exatamente onde a experiência do desenvolvedor se destaca e onde ainda precisa ser aprimorada. Isso é ainda mais importante agora, à medida que os desenvolvedores interagem com o Elastic Stack de novas maneiras, cada vez mais por meio de fluxos de trabalho orientados por LLM. Neste post do blog, vamos explorar mais a fundo o que os participantes criaram com o Agent Builder e o que aprendemos durante o processo.

Os projetos vencedores

Primeiro lugar: AgentOverflow

Stack Overflow reconstruído para a era do LLM e dos agentes.

Leia mais sobre AgentOverflow aqui.

O AgentOverflow resolve um problema que a maioria dos desenvolvedores de IA enfrenta: os LLMs (Learning Learning Machines) têm alucinações, o histórico de bate-papo desaparece e os desenvolvedores perdem tempo resolvendo os mesmos problemas repetidamente.

O AgentOverflow captura, valida e reapresenta pares reais de problema-solução, para que os desenvolvedores possam quebrar o ciclo de ilusão e lançar produtos mais rapidamente.

Como funciona:

1. Compartilhar JSON - o "Esquema da Solução".

Um clique em um compartilhamento do Claude irá coletar, extrair e montar um JSON de Solução de Compartilhamento, que é um formato estruturado contendo:

• Problema
• Contexto
• Código
• Tags
• Etapas da solução verificadas.

Um validador (LAVA) verifica e impõe a estrutura; o usuário adiciona uma linha de contexto extra, que então é armazenada e indexada no Elasticsearch.

2. Encontre a solução

Quando você ficar preso, clique em Find Solution e o AgentOverflow irá extrair informações da sua conversa atual, usá-las para construir uma consulta e executar uma pesquisa híbrida no Elasticsearch para exibir os resultados:

• Correções classificadas e validadas pela comunidade
• As mesmas instruções que originalmente resolveram o problema.

Isso permite que os desenvolvedores copiem, colem e desbloqueiem sua sessão atual rapidamente.

3. MCP - Injeção de contexto para LLMs

Ao conectar-se às soluções estruturadas armazenadas no Elasticsearch por meio do MCP (Model Context Protocol), os LLMs recebem um contexto de alta qualidade (código, logs, configurações, correções anteriores) em tempo de execução, sem ruído adicional.

O AgentOverflow utiliza o Agent Builder com o Elasticsearch como uma camada de memória estruturada que injeta contexto relevante nos LLMs. Isso os transforma de chatbots passivos em solucionadores de problemas sensíveis ao contexto.

Segundo lugar: MarketMind

Uma visão interpretável e em tempo real da energia de mercado, alimentada por seis Agentes Elásticos.

Leia mais sobre a MarketMind aqui.

A MarketMind conquistou seu espaço ao oferecer aos traders iniciantes uma plataforma que converte dados de mercado fragmentados em sinais claros e em tempo real. Em vez de lidar com a ação do preço, os fundamentos, o sentimento e a volatilidade em diferentes ferramentas, o MarketMind consolida todas essas informações em uma única plataforma, ajudando os traders a obter insights acionáveis. Este projeto também utilizou algumas consultas ES|QL complexas na construção de seus agentes.

Como funciona:

1. Coletar dados de mercado em tempo real

O MarketMind extrai métricas de ação de preço, fundamentos, sentimento, volatilidade e risco do Yahoo Finance. Esses dados são ingeridos e organizados em múltiplos índices do Elasticsearch.

2. Seis agentes especializados analisam o mercado.

Cada agente, criado com o Agent Builder, concentra-se em uma camada diferente do mercado. Eles leem dados de um índice do Elasticsearch, calculam suas próprias métricas específicas do domínio e geram uma saída JSON padronizada com pontuações e justificativas.

3. Agregar sinais em um modelo unificado de “energia de mercado”

Os resultados combinados aparecem como pulsos brilhantes ao redor de cada ação, ilustrando se o ímpeto está aumentando, o risco está crescendo ou o sentimento está mudando.

4. Visualize insights

A interface foi desenvolvida com React e Next.js, utilizando TypeScript, recursos visuais baseados em física SVG e Chart.js para gráficos de velas em tempo real. Isso transforma análises brutas em feedback acionável em tempo real.

Outros projetos interessantes:

Aqui estão alguns outros fortes concorrentes que usaram o Elastic em diferentes partes de sua infraestrutura:

Encontre aqui a lista completa dos projetos submetidos à nossa trilha.

O que aprendemos com os desenvolvedores

• O Construtor de Agentes é fácil de usar:

A maioria das equipes nunca havia usado o Elastic antes e, mesmo assim, conseguiu criar agentes rapidamente com pouco suporte. Realizamos um workshop para aqueles que precisavam de mais orientação, mas a maioria conseguiu importar seus dados e construir um agente para executar ações com base nesses dados.

• Os LLMs se destacam em consultaskNN, mas ainda precisam de orientação na geração de ES|QL:

Ao solicitar que o ChatGPT-5 gerasse consultas ES|QL, foram retornadas informações incorretas, frequentemente misturando ES|QL e SQL. Fornecer os documentos ao LLM em um arquivo Markdown pareceu ser uma solução viável.

• Funções ES|QL exclusivas de snapshots vazaram para a documentação:

As próximas funções de agregação FIRST e LAST foram acidentalmente incluídas em nossa documentação ES|QL. Como fornecemos esses documentos ao ChatGPT, o modelo usou essas funções corretamente, mesmo que elas ainda não estejam disponíveis no Serverless. Graças ao feedback do grupo, a equipe de engenharia rapidamente abriu e incorporou uma correção para remover as funções da documentação publicada (PR #137341).

• Ausência de orientações específicas para Serverless:

Uma equipe tentou habilitar LOOKUP JOIN em um índice que não foi criado no modo de pesquisa. A mensagem de erro os levou a seguir comandos que não existem no Serverless. Repassamos isso para a equipe de produto, que imediatamente abriu uma solicitação de correção para uma mensagem acionável específica para Serverless. A longo prazo, a visão é ocultar completamente a complexidade da reindexação (Problema nº 4838).

• Valor dos eventos presenciais:

Hackathons online são ótimos, mas nada se compara ao feedback rápido que você obtém ao depurar código lado a lado com os desenvolvedores. Acompanhamos as equipes integrando o Agent Builder em diferentes casos de uso, identificamos pontos em que a experiência do desenvolvedor com ES|QL poderia ser aprimorada e corrigimos problemas muito mais rapidamente do que se tivéssemos tentado fazê-lo por meio de canais assíncronos.

Conclusão

O Cal Hacks 12.0 nos proporcionou mais do que um fim de semana repleto de demonstrações incríveis; também nos deu uma visão de como os novos desenvolvedores estão interagindo com o Elastic Stack. Em apenas 36 horas, vimos equipes começarem a usar o Agent Builder, ingerir dados no Elasticsearch, projetar sistemas multiagentes e testar nossos recursos de diversas maneiras. O evento também nos lembrou por que os eventos presenciais são importantes. Os ciclos de feedback rápidos, as conversas reais e a depuração prática nos ajudaram a entender as necessidades atuais dos desenvolvedores. Estamos entusiasmados em trazer de volta para a equipe de engenharia o que aprendemos. Nos vemos no próximo hackathon.

Este artigo é um complemento ao artigo "Criando uma sala de imprensa com o agente LLM usando os protocolos A2A e MCP no Elasticsearch!", que explicou os benefícios de implementar as arquiteturas A2A e MCP no mesmo agente para aproveitar ao máximo as vantagens exclusivas de ambas as estruturas. Um repositório está disponível caso você queira executar a demonstração por conta própria.

Vamos analisar como nossos agentes de redação colaboram usando tanto o A2A quanto o MCP para produzir um artigo jornalístico. O repositório que acompanha o projeto, onde é possível ver os agentes em ação, pode ser encontrado aqui.

Etapa 1: Atribuição da história

O chefe de jornalismo (atuando como cliente) designa uma pauta:

{
  "message_type": "task_request",
  "sender": "news_chief",
  "receiver": "reporter_agent",
  "payload": {
    "task_id": "story_renewable_energy_2024",
    "assignment": {
      "topic": "Renewable Energy Adoption in Europe",
      "angle": "Policy changes driving solar and wind expansion",
      "target_length": 1200,
      "deadline": "2025-09-30T18:00:00Z"
    }
  }
}

Etapa 2: O repórter solicita pesquisa.

O Agente Repórter reconhece que precisa de informações básicas e delega essa tarefa ao Agente Pesquisador por meio do método A2A:

{
  "message_type": "task_request",
  "sender": "reporter_agent",
  "receiver": "researcher_agent",
  "payload": {
    "task_id": "research_eu_renewable_2024",
    "parent_task_id": "story_renewable_energy_2024",
    "capability": "fact_gathering",
    "parameters": {
      "queries": [
        "EU renewable energy capacity 2024",
        "Solar installations growth Europe",
        "Wind energy policy changes 2024"
      ],
      "depth": "comprehensive"
    }
  }
}

Etapa 3: O repórter solicita contexto histórico ao Agente de Arquivo.

O agente repórter reconhece que o contexto histórico fortaleceria a matéria. Ele delega ao Agente de Arquivo (com tecnologia A2A do Elastic) via A2A a busca no arquivo de artigos da sala de notícias, que utiliza o Elasticsearch:

{
  "message_type": "task_request",
  "sender": "reporter_agent",
  "receiver": "archive_agent",
  "payload": {
    "task_id": "archive_search_renewable_2024",
    "parent_task_id": "story_renewable_energy_2024",
    "capability": "search_archive",
    "parameters": {
      "query": "European renewable energy policy changes and adoption trends over past 5 years",
      "focus_areas": ["solar", "wind", "policy", "Germany", "France"],
      "time_range": "2019-2024",
      "result_count": 10
    }
  }
}

Etapa 4: O Agente de Arquivamento usa o Agente A2A Elástico com MCP

O Agente de Arquivamento utiliza o Agente A2A da Elastic, que por sua vez usa o MCP para acessar as ferramentas do Elasticsearch. Isso demonstra a arquitetura híbrida onde o A2A permite a colaboração entre agentes enquanto o MCP fornece acesso às ferramentas:

# Archive Agent using Elastic A2A Agent
async def search_historical_articles(self, query_params):
    # The Archive Agent sends a request to Elastic's A2A Agent
    elastic_response = await self.a2a_client.send_request(
        agent="elastic_agent",
        capability="search_and_analyze",
        parameters={
            "natural_language_query": query_params["query"],
            "index_pattern": "newsroom-articles-*",
            "filters": {
                "topics": query_params["focus_areas"],
                "date_range": query_params["time_range"]
            },
            "analysis_type": "trend_analysis"
        }
    )
    
    # Elastic's A2A Agent internally uses MCP tools:
    # - platform.core.search (to find relevant articles)
    # - platform.core.generate_esql (to analyze trends)
    # - platform.core.index_explorer (to identify relevant indices)
    
    return elastic_response

O Agente de Arquivamento recebe dados históricos abrangentes do Agente A2A da Elastic e os retorna ao Reporter:

{
  "message_type": "task_response",
  "sender": "archive_agent",
  "receiver": "reporter_agent",
  "payload": {
    "task_id": "archive_search_renewable_2024",
    "status": "completed",
    "archive_data": {
      "historical_articles": [
        {
          "title": "Germany's Energiewende: Five Years of Solar Growth",
          "published": "2022-06-15",
          "key_points": [
            "Germany added 7 GW annually 2020-2022",
            "Policy subsidies drove 60% of growth"
          ],
          "relevance_score": 0.94
        },
        {
          "title": "France Balances Nuclear and Renewables",
          "published": "2023-03-20",
          "key_points": [
            "France increased renewable target to 40% by 2030",
            "Solar capacity doubled 2021-2023"
          ],
          "relevance_score": 0.89
        }
      ],
      "trend_analysis": {
        "coverage_frequency": "EU renewable stories increased 150% since 2019",
        "emerging_themes": ["policy incentives", "grid modernization", "battery storage"],
        "coverage_gaps": ["Small member states", "offshore wind permitting"]
      },
      "total_articles_found": 47,
      "search_confidence": 0.91
    }
  }
}

Esta etapa demonstra como o agente A2A da Elastic se integra ao fluxo de trabalho da redação. O Agente de Arquivo (um agente específico para redações) trabalha em conjunto com o Agente A2A da Elastic (um especialista terceirizado) para aproveitar os poderosos recursos de busca e análise do Elasticsearch. O agente da Elastic usa o MCP internamente para acessar as ferramentas do Elasticsearch, demonstrando a clara separação entre a coordenação do agente (A2A) e o acesso às ferramentas (MCP).

Etapa 5: O pesquisador utiliza servidores MCP

O Agente Pesquisador acessa vários servidores MCP para coletar informações:

# Researcher Agent using MCP to access tools
async def gather_facts(self, queries):
    results = []
    
    # Use News API MCP Server
    news_data = await self.mcp_client.invoke_tool(
        server="news_api_mcp",
        tool="search_articles",
        parameters={
            "query": queries[0],
            "date_range": "2024-01-01 to 2024-09-30",
            "sources": ["reuters", "bloomberg", "euractiv"]
        }
    )
    
    # Use Statistics MCP Server
    stats_data = await self.mcp_client.invoke_tool(
        server="eurostat_mcp",
        tool="get_energy_statistics",
        parameters={
            "metrics": ["solar_capacity_mw", "wind_capacity_mw"],
            "countries": ["EU27"],
            "year": 2024
        }
    )
    
    # Use Fact-Checking MCP Server
    verified_facts = await self.mcp_client.invoke_tool(
        server="factcheck_mcp",
        tool="verify_claims",
        parameters={
            "claims": [
                "EU solar capacity increased 40% in 2024",
                "Germany leads in wind installations"
            ]
        }
    )
    
    return self._synthesize_research(news_data, stats_data, verified_facts)

Etapa 6: O pesquisador devolve os dados ao repórter.

O Agente de Pesquisa envia uma pesquisa completa de volta via A2A:

{
  "message_type": "task_response",
  "sender": "researcher_agent",
  "receiver": "reporter_agent",
  "payload": {
    "task_id": "research_eu_renewable_2024",
    "status": "completed",
    "research_data": {
      "key_facts": [
        {
          "claim": "EU solar capacity reached 260 GW in 2024",
          "source": "Eurostat Q3 2024 Report",
          "confidence": 0.95,
          "verified": true
        },
        {
          "claim": "Germany installed 12 GW of wind capacity in 2024",
          "source": "German Federal Network Agency",
          "confidence": 0.92,
          "verified": true
        }
      ],
      "statistics": {
        "solar_growth_rate": "35%",
        "wind_growth_rate": "28%"
      },
      "sources_count": 15
    }
  }
}

Etapa 7: O repórter escreve o artigo

O Repórter Agente utiliza os dados da pesquisa e suas próprias capacidades de mestrado em Direito (LLM) para redigir o artigo. Durante a escrita, o Repórter utiliza os servidores MCP para estilo e modelos:

# Reporter Agent writing with MCP assistance
async def write_article(self, research_data, assignment):
    # Get style guidelines via MCP
    style_guide = await self.mcp_client.get_resource(
        server="newsroom_mcp",
        resource="style://editorial/ap_style_guide"
    )
    
    # Get article template via MCP
    template = await self.mcp_client.get_resource(
        server="newsroom_mcp",
        resource="template://articles/news_story"
    )
    
    # Generate article using LLM + research + style
    draft = await self.llm.generate(
        prompt=f"""
        Write a news article following these guidelines:
        {style_guide}
        
        Using this template:
        {template}
        
        Based on this research:
        {research_data}
        
        Assignment: {assignment}
        """
    )
    
    # Self-evaluate confidence in claims
    confidence_check = await self._evaluate_confidence(draft)
    
    return draft, confidence_check

Etapa 8: baixa confiança desencadeia nova pesquisa

O agente repórter avalia sua versão preliminar e constata que uma das afirmações apresenta baixo nível de confiança. Envia outra solicitação ao Agente Pesquisador:

{
  "message_type": "collaboration_request",
  "sender": "reporter_agent",
  "receiver": "researcher_agent",
  "payload": {
    "request_type": "fact_verification",
    "claims": [
      {
        "text": "France's nuclear phase-down contributed to 15% increase in renewable capacity",
        "context": "Discussing policy drivers for renewable growth",
        "current_confidence": 0.45,
        "required_confidence": 0.80
      }
    ],
    "urgency": "high"
  }
}

O pesquisador verifica a alegação usando servidores de checagem de fatos do MCP e retorna informações atualizadas:

{
  "message_type": "collaboration_response",
  "sender": "researcher_agent",
  "receiver": "reporter_agent",
  "payload": {
    "verified_claims": [
      {
        "original_claim": "France's nuclear phase-down contributed to 15% increase...",
        "verified_claim": "France's renewable capacity increased 18% in 2024, partially offsetting reduced nuclear output",
        "confidence": 0.88,
        "corrections": "Percentage was 18%, not 15%; nuclear phase-down is gradual, not primary driver",
        "sources": ["RTE France", "French Energy Ministry Report 2024"]
      }
    ]
  }
}