O que é um construtor de dashboard do Kibana?

E se você pudesse descrever o dashboard que deseja em inglês simples e vê-lo aparecer completo, com gráficos interativos, um layout de arrastar e soltar e exportação para o Kibana com um clique?

É exatamente isso que o example-mcp-dashbuilder faz. É um aplicativo open source (Model Context Protocol (MCP)) que conecta assistentes de IA ao Elasticsearch, permitindo que você crie painéis completos do Kibana por meio de conversas. Sem precisar clicar nos menus. Sem escrever manualmente as configs de visualização. Basta descrever o que você precisa para que a IA explore seus dados, escreva as consultas Elasticsearch Query Language (ES|QL), crie os gráficos e forneça um dashboard interativo ao vivo, tudo dentro da janela de bate-papo do seu editor.

Do prompt ao dashboard em segundos

Veja como isso funciona na prática. Você digita algo como:

"Crie para mim um dashboard de tráfego da web a partir do logstash-* com total de solicitações, bytes transferidos ao longo do tempo, principais fontes geográficas e um detalhamento do código de resposta"

A IA então:

1. Descobre seus dados: lista índices e inspeciona mapeamentos de campos.

2. Escreve consultas ES|QL: adaptadas ao seu esquema, usando as agregações corretas.

3. Cria visualizações: gráficos de barras, gráficos de linhas, métricas com sparklines, mapas de calor, gráficos de pizza.

4. Organiza tudo: seções retráteis, títulos significativos, layout adequado.

5. Renderiza uma visualização interativa: diretamente no bate-papo, com dicas de ferramentas, um seletor de tempo e arrastar e soltar.

Cada gráfico aparece em linha conforme é criado, então você pode ver o progresso em tempo real. Depois, view_dashboard mostra o dashboard completo com todos os painéis dispostos na grade de 48 colunas de Kibana.

Prévia de gráfico único em linha.

Desenvolvido por ES|QL

Toda recuperação de dados utiliza ES|QL, a linguagem de consulta em pipeline do Elasticsearch. A IA não apenas passa por consultas brutas, ela também usa conhecimento integrado do ES|QL junto com informações sobre a estrutura dos seus dados para escrever consultas corretas e eficientes para cada tipo de visualização.

O servidor inclui uma referência abrangente de ES|QL como um recurso MCP. Antes de escrever qualquer consulta, a IA lê essa referência para entender os comandos, funções e padrões disponíveis. Em conjunto com um guia de **práticas recomendadas** de visualização de dados (que também serviu como recurso), a IA sabe não apenas como fazer consultas, mas o que torna uma visualização boa:

• Use BUCKET(@timestamp, 1 day) para séries temporais; sempre SORT pelo campo de tempo.

• Limite os gráficos de pizza a seis fatias com | SORT value DESC | LIMIT 6.

• Escolha gráficos de barras para comparações de categorias, gráficos de linhas para tendências, métricas para indicadores-chave de desempenho (KPIs).

Exploração de dados orientada por IA com análise aberta

Construir um dashboard que você já imaginou na cabeça é outra história. Perguntar "O que há de interessante nesse índice?" e obter uma resposta útil é mais difícil; isso exige que a IA saiba como explorar, não apenas como desenhar.

O example-mcp-dashbuilder envia um recurso analysis://guidelines que define um fluxo de exploração estruturado: faça o perfil dos dados, execute agregações direcionadas, identifique padrões que valem a pena investigar, crie gráficos para as descobertas mais interessantes e proponha consultas detalhadas que o usuário possa querer em seguida. Frases gatilho, como "analisar meus logs" ou "encontrar padrões neste índice", fazem a IA ler o manual antes de fazer qualquer outra coisa, então um prompt aberto produz uma investigação coerente em vez de uma pilha aleatória de gráficos.

O resultado: você pode entregar um índice não familiar à IA e receber de volta um ponto de partida: um dashboard mais uma pequena lista de prompts "Aqui estão minhas impressões, quer que eu investigue mais a fundo algum desses?"

Exportação e importação do dashboard do Kibana: a viagem completa de ida e volta

A viagem de ida e volta de exportação/importação é onde o example-mcp-dashbuilder se torna realmente útil para as equipes que já trabalham com o Kibana. O example-mcp-dashbuilder é algo próprio, uma superfície de dashboard de conversação que fica dentro do seu editor, mas não prende o seu trabalho lá. Dashboards construídos aqui podem ser movidos para o Kibana quando você quiser, e dashboards existentes do Kibana podem seguir o caminho inverso para edição assistida por IA.

Exportar para Kibana

Quando você estiver satisfeito com seu dashboard, um comando irá exportá-lo:

"Exportar este dashboard para o Kibana"

Cada painel é traduzido para uma visualização real do Kibana Lens. A tradução preserva:

• Consultas ES|QL: transferidas diretamente como fontes de dados ES|QL do Lens.

• Posições de grade: o mesmo sistema de 48 colunas que o Kibana usa, para que você tenha um layout idêntico.

• Cores personalizadas: paletas de séries, fundos métricos, rampas de cores de heatmap.

O resultado é um dashboard do Kibana totalmente funcional. Não é uma captura de tela. Não é uma incorporação. Um dashboard do Kibana que você pode compartilhar e continuar editando.

Dashboard do Kibana e dashboard no chat do Cursor lado a lado.

Importar do Kibana

A viagem de ida e volta também funciona na outra direção:

"Importar o dashboard do Kibana com o ID abc-123"

Isso busca um dashboard do Kibana existente, traduz suas visualizações do Lens para configurações de gráficos editáveis, preserva o layout e as seções da grade e carrega tudo no example-mcp-dashbuilder. A partir daí, você pode modificar com linguagem natural e reexportar.

Isso torna a IA uma colaboradora em seu fluxo de trabalho existente do Kibana, não uma substituta para ele.

Temas e cores personalizados

Quer um dashboard de marca? É só pedir:

"Crie um dashboard com tema rosa e cores personalizadas"

Todo tipo de visualização permite configuração de cor personalizada:

• Gráficos: palette aceita uma matriz de cores hexadecimais para séries e fatias.

• Métricas: color define a cor de plano de fundo.

• Mapas de calor: colorRamp define o gradiente, dos valores baixos aos altos.

A IA identifica os pedidos de tema naturalmente. Diga "tema do oceano", e ele vai escolher tons de azul e verde-azulado. Diga "Combine as cores da nossa marca" e forneça valores hexadecimais, e eles serão aplicados no Kibana na exportação.

Um dashboard temático com cores personalizadas.

Como funciona o example-mcp-dashbuilder: arquitetura MCP

O example-mcp-dashbuilder foi desenvolvido com base no MCP, o padrão aberto para conectar assistentes de IA a ferramentas e dados externos. Aqui está a arquitetura em alto nível:

O servidor MCP expõe 25 ferramentas que a IA pode chamar diretamente, desde a execução de consultas ES|QL até a exportação de painéis, além de algumas ferramentas internas "exclusivas do app" que a pré-visualização embutida usa para buscar dados, persistir alterações de layout e detectar campos de tempo. Ele oferece três recursos: um guia de **práticas recomendadas** de dataviz, uma referência ES|QL e um manual de análise aprofundada que entra em ação para prompts abertos ("analisar meus logs", "o que há de interessante neste índice"). E executa tanto em stdio quanto em HTTP; o transporte HTTP permite respostas em fluxo contínuo e gerenciamento de sessão, permitindo que vários clientes se conectem a um mesmo servidor.

O MCP App é uma pré-visualização interativa. Ele foi desenvolvido com React, Elastic Charts e Elastic UI, agrupados em um único arquivo HTML independente. Quando a IA chama view_dashboard ou cria um gráfico, o host renderiza este HTML em um iframe isolado. O aplicativo se comunica com o servidor inteiramente através do protocolo MCP Apps, usando callServerTool() sobre postMessage para buscar dados, salvar layouts e detectar campos de tempo. Não há servidor localhost, nenhuma porta para configurar, nenhuma dependência de rede externa.

Isso significa que funciona com qualquer cliente compatível com MCP: Cursor, Claude Desktop, Claude.ai, VS Code com Copilot e muito mais.

Quais tipos de gráficos o example-mcp-dashbuilder permite?

No momento desta publicação, são permitidos seis tipos de gráficos que cobrem os cenários de dashboard mais comuns:

Tipo

Melhor para

Exemplo

Barra

Comparando categorias

Solicitações por fonte geográfica

Linha

Tendências ao longo do tempo

Bytes transferidos por hora

Área

Volume ao longo do tempo

Volume de solicitações ao longo do tempo

Pizza

Parte do todo (máximo seis fatias)

Distribuição de código de resposta

Métrica

KPI único com sparkline

Total de solicitações com tendência horária

Heatmap

Padrões em duas dimensões

Solicitações por dia da semana e hora

Dashboards permitem seções recolhíveis para organização, um seletor de tempo com detecção automática de campos de tempo e a capacidade de salvar e alternar entre múltiplos dashboards; sessões paralelas de chat permanecem isoladas umas das outras por meio de um dashboardId que passa por cada chamada de ferramenta.

Como instalar e executar o example-mcp-dashbuilder

O example-mcp-dashbuilder é open source e está pronto para uso. Você vai precisar de Node.js 22+, uma instância Elasticsearch (local ou Elastic Cloud) e um cliente compatível com MCP.

Claude Desktop: baixe a versão mais recente .mcpb do GitHub Releases, e clique duas vezes nela. O Claude Desktop solicitará suas credenciais do Elasticsearch.

Cursor / Claude Code / VS Code Copilot: aponte sua configuração MCP para o tarball liberado; sem clone, sem npm install:

Configure ES_NODE, ES_API_KEY (ou ES_USERNAME / ES_PASSWORD) e KIBANA_URL como variáveis de ambiente. Se você preferir trabalhar a partir da fonte, clone o repositório e execute npm run setup para um assistente interativo que lida com o Elasticsearch local e o Elastic Cloud (Cloud ID + chave de API).

E comece a construir:

"Explore o índice de logs e construa o dashboard mais perspicaz que puder"

A partir daí, a IA assume o controle. 😉

Roadmap: o que está por vir para o example-mcp-dashbuilder

Este é um lançamento antecipado, e estamos em desenvolvimento ativo. Algumas áreas em que estamos focados:

• Mais tipos de gráficos: medidor, donut, treemap, tabela de dados e nuvem de tags para combinar com todas as capacidades da Lens.

• Envie dashboards para o Git: escreva configurações de dashboards em um repositório para fluxo de trabalho de controle de versões e revisão de código.

• Melhor UX de erro: feedback mais detalhado quando o ES|QL falha, com sugestões comuns de correções.

• Fluxos de análise mais ricos: estenda o manual de análise profunda para cobrir mais formas de dados (logs, métricas, rastreamentos).

Adoraríamos saber o que você cria com ele. Experimente, registre problemas e conte para a gente quais visualizações e fluxos de trabalho seriam mais úteis para sua equipe.

GitHub: elastic/example-mcp-dashbuilder

Agradecimentos

Agradecemos a Walter Rafelsberger e Tim Schnell por suas contribuições para a implementação.

Perguntas frequentes

O que é o example-mcp-dashbuilder? o example-mcp-dashbuilder é um aplicativo MCP (Model Context Protocol) open source que conecta assistentes de IA ao Elasticsearch. Ele permite que você descreva um dashboard do Kibana e automaticamente gera consultas ES|QL, cria visualizações e entrega um dashboard interativo ao vivo dentro da janela de chat do seu editor.

Qual linguagem de consulta o example-mcp-dashbuilder usa para recuperar dados? Toda recuperação de dados utiliza ES|QL, a linguagem de consulta com barras verticais do Elasticsearch. O servidor MCP inclui uma referência ES|QL integrada que a IA lê antes de escrever qualquer consulta, garantindo a sintaxe correta e agregações eficientes para cada tipo de visualização.

Posso exportar dashboards construídos com example-mcp-dashbuilder para Kibana? Sim. Executar "Exportar este dashboard para Kibana" traduz todos os painéis em uma visualização real do Kibana Lens, preservando as consultas ES|QL, o layout de grade de 48 colunas, cores personalizadas e paletas de séries. O resultado é um dashboard do Kibana totalmente funcional, não uma captura de tela ou incorporação.

Posso importar um dashboard do Kibana existente para o example-mcp-dashbuilder para edição assistida por IA? Sim. Fornecer um ID de dashboard do Kibana busca o dashboard existente, traduz suas visualizações do Lens em configurações de gráfico editáveis e as carrega no example-mcp-dashbuilder. Você pode então modificar o dashboard usando linguagem natural e reexportar para o Kibana.

Quais clientes MCP são compatíveis com o example-mcp-dashbuilder? O example-mcp-dashbuilder funciona com qualquer cliente compatível com MCP, incluindo Cursor, Claude Desktop, Claude.ai e VS Code com Copilot. Ele permite tanto transporte stdio quanto HTTP, sem necessidade de configuração de servidor localhost ou de porta.

Quais tipos de gráficos o example-mcp-dashbuilder permite? A versão atual permite seis tipos de gráficos: barra, linha, área, pizza, métrica (com sparkline) e heatmap. As adições planejadas incluem indicador, rosca, mapa de árvore, tabela de dados e nuvem de tags para combinar com todas as capacidades do Kibana Lens.

O que eu preciso para executar o example-mcp-dashbuilder? Você precisa do Node.js versão 22 ou superior, uma instância do Elasticsearch (local ou Elastic Cloud) e um cliente compatível com MCP. Defina as variáveis de ambiente ES_NODE, ES_API_KEY (ou ES_USERNAME/ES_PASSWORD) e KIBANA_URL. Para o Claude Desktop, baixe o arquivo .mcpb do GitHub Releases e clique duas vezes para instalar.

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.

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.

Métrica

Valor

Precisão

83,8%

Recall

62,6%

Pontuação F1

71,7%

Total de correspondências encontradas

344

Taxa de aceitação do LLM

44,8%

Taxa de erro

30,2%

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.

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

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.

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.

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

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.

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:

Para Descrição:

Para Configuração, insira a seguinte consulta na área de texto Mecanismo de consulta ES|QL:

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:

Na área de texto de Instruções personalizadas, insira as seguintes instruções:

Para o Nome de exibição, insira o texto abaixo:

Para a Descrição de exibição, insira o texto abaixo:

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:

Execute o seguinte cd comando para alterar o diretório para o diretório elasticsearch-labs:

Em seguida, execute o seguinte comando para abrir o repositório no Visual Studio 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:

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:

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:

Execute o seguinte comando para criar um ambiente virtual Python.

Dependendo do sistema operacional do seu computador local, execute o seguinte comando para ativar o ambiente virtual.

• MacOS/Linux

• Windows

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.

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:

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.

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.

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:

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

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

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.

Como mencionado anteriormente, o cliente LLM será usado para gerar os parâmetros de busca do Elasticsearch com base na pergunta do usuário.

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:

Com a consulta de agregação acima, temos os seguintes resultados:

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:

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

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.

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:

prepareMarketSearch: cria parâmetros orientados pelo mercado, focados em setores, geografias e modelos de negócios. Veja a consulta completa no arquivo elasticsearchSetup.ts :

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.

nó visualizeResults

Por fim, este nó exibe os resultados do Elasticsearch.

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

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:

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:

Resultados

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

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.

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.

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:

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:

Acesse o Kibana

Abra seu navegador e acesse:

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.

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

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.

Indexar com API em lote

Copie e cole o conjunto de dados nas suas Ferramentas de Desenvolvedor no Kibana e execute-o:

Verifique os dados

Execute uma consulta para verificar:

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:

Rótulos: Human Resources e GPT-OSS

Nome de exibição: HR Analytics Assistant

Descrição da tela:

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:

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.

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:

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:

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:

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:

O Agente de Arquivamento recebe dados históricos abrangentes do Agente A2A da Elastic e os retorna ao Reporter:

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:

Etapa 6: O pesquisador devolve os dados ao repórter.

O Agente de Pesquisa envia uma pesquisa completa de volta via A2A:

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:

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:

O pesquisador verifica a alegação usando servidores de checagem de fatos do MCP e retorna informações atualizadas:

Etapa 9: O repórter revisa e envia ao editor.

O repórter incorpora os fatos verificados e envia a versão finalizada ao editor por meio do sistema A2A:

Etapa 10: Revisão do editor usando as ferramentas MCP

O Agente de Edição utiliza vários servidores MCP para revisar o artigo:

O editor aprova o artigo e o encaminha:

Etapa 11: A editora publica via CI/CD

Por fim, o Agente de Impressão publica o artigo aprovado usando os servidores MCP para o pipeline CMS e CI/CD:

A editora confirma a publicação via A2A:

Segue abaixo a sequência completa do fluxo de trabalho A2A no repositório anexo, utilizando os mesmos agentes descritos acima.

#

De

Para

Ação

Protocolo

Descrição

1

Usuário

Chefe de Notícias

Atribuir história

HTTP POST

O usuário envia o tema e o enfoque da matéria.

2

Chefe de Notícias

Interno

Criar história

-

Cria um registro de história com um ID exclusivo.

3

Chefe de Notícias

Repórter

Atribuição de Delegado

A2A

Envia a atribuição da matéria através do protocolo A2A

4

Repórter

Interno

Aceitar tarefa

-

Atribuição de estoques internamente

5

Repórter

Servidor MCP

Gerar esboço

MCP/HTTP

Cria o esboço do artigo e as perguntas de pesquisa.

6a

Repórter

Pesquisador

Solicitar pesquisa

A2A

Envia perguntas (paralelo com 6b)

6b

Repórter

Arquivista

Pesquisar no arquivo

A2A JSONRPC

Pesquisa artigos históricos (paralelo com 6a)

7

Pesquisador

Servidor MCP

Questões de pesquisa

MCP/HTTP

Utiliza a abordagem antropogênica via MCP para responder a perguntas.

8

Pesquisador

Repórter

Retornar à pesquisa

A2A

Devolve respostas de pesquisa

9

Arquivista

Elasticsearch

Índice de pesquisa

API REST do ES

Consultas ao índice news_archive

10

Arquivista

Repórter

Retornar ao arquivo

A2A JSONRPC

Retorna resultados de pesquisa históricos

11

Repórter

Servidor MCP

Gerar artigo

MCP/HTTP

Cria artigo com contexto de pesquisa/arquivo

12

Repórter

Interno

Rascunho da loja

-

Salva o rascunho internamente

13

Repórter

Chefe de Notícias

Enviar rascunho

A2A

Entrega a versão finalizada

14

Chefe de Notícias

Interno

Atualização da história

-

Armazena o rascunho e atualiza o status para "rascunho_enviado".

15

Chefe de Notícias

Editor

Revisão do rascunho

A2A

Encaminha automaticamente para o Editor para revisão.

16

Editor

Servidor MCP

Artigo de revisão

MCP/HTTP

Analisa conteúdo usando Anthropic via MCP.

17

Editor

Chefe de Notícias

Revisão de retorno

A2A

Envia comentários e sugestões editoriais.

18

Chefe de Notícias

Interno

Avaliação da loja

-

Feedback do editor de lojas

19

Chefe de Notícias

Repórter

Aplicar edições

A2A

Feedback da revisão de rotas para o repórter

20

Repórter

Servidor MCP

Aplicar edições

MCP/HTTP

Revisa o artigo com base no feedback.

21

Repórter

Interno

Rascunho atualizado

-

Atualiza a versão preliminar com revisões.

22

Repórter

Chefe de Notícias

Devolução revisada

A2A

Devolve artigo revisado

23

Chefe de Notícias

Interno

Atualização da história

-

Lojas revisaram a versão preliminar, status para "revisado"

24

Chefe de Notícias

Editor

Publicar artigo

A2A

Rotas automáticas para o editor

25

Editor

Servidor MCP

Gerar etiquetas

MCP/HTTP

Cria etiquetas e categorias

26

Editor

Elasticsearch

Artigo de índice

API REST do ES

Indexa o artigo ao índice news_archive

27

Editor

Sistema de arquivos

Salvar Markdown

Entrada/Saída de Arquivos

Salva o artigo como .md arquivo em /artigos

28

Editor

Chefe de Notícias

Confirmar publicação

A2A

Retorna o status de sucesso

29

Chefe de Notícias

Interno

Atualização da história

-

Atualiza o status da matéria para "publicada".

Conclusão

Tanto o A2A quanto o MCP desempenham papéis importantes no paradigma moderno de infraestrutura de LLM aumentada. A tecnologia A2A oferece flexibilidade para sistemas multiagentes complexos, mas potencialmente menor portabilidade e maior complexidade operacional. O MCP oferece uma abordagem padronizada para integração de ferramentas que é mais simples de implementar e manter, embora não seja projetado para lidar com orquestração multiagente.

A escolha não é binária. Conforme demonstrado em nosso exemplo de redação, os sistemas mais sofisticados e eficazes baseados em LLM geralmente combinam ambas as abordagens: os agentes se coordenam e se especializam por meio de protocolos A2A, enquanto acessam suas ferramentas e recursos por meio de servidores MCP. Essa arquitetura híbrida proporciona os benefícios organizacionais dos sistemas multiagentes, juntamente com a padronização e as vantagens do ecossistema do MCP. Isso sugere que talvez não seja necessário escolher: basta usar ambos como abordagem padrão.

Cabe a você, como desenvolvedor ou arquiteto, testar e determinar a melhor combinação de ambas as soluções para obter o resultado adequado ao seu caso de uso específico. Compreender os pontos fortes, as limitações e as aplicações adequadas de cada abordagem permitirá que você construa sistemas de IA mais eficazes, fáceis de manter e escaláveis.

Seja para criar uma redação digital, uma plataforma de atendimento ao cliente, um assistente de pesquisa ou qualquer outro aplicativo baseado em LLM, considerar cuidadosamente suas necessidades de coordenação (A2A) e requisitos de acesso às ferramentas (MCP) o colocará no caminho do sucesso.

Recursos adicionais

• Construtor de Agentes do Elasticsearch: https://www.elastic.co/docs/solutions/search/elastic-agent-builder

• Especificação A2A: https://a2a-protocol.org/latest/specification/

• Integração A2A e MCP: https://a2a-protocol.org/latest/topics/a2a-and-mcp/

• Protocolo de Contexto do Modelo: https://modelcontextprotocol.io

Uma nova forma de interagir com dados

A IA generativa (genAI) e a IA agentiva funcionam de maneira diferente da busca tradicional. Enquanto antes começávamos a pesquisar informações por meio de uma busca ("deixe-me pesquisar isso no Google..."), a ação inicial tanto para a IA de geração de robôs quanto para os agentes geralmente se dá por meio da linguagem natural inserida em uma interface de bate-papo. A interface de bate-papo é uma discussão com um LLM (Literatura Liderada pelo Senhor da Moeda) que usa sua compreensão semântica para transformar nossa pergunta em uma resposta concisa, uma resposta resumida que parece vir de um oráculo com amplo conhecimento de todos os tipos de informação. O que realmente convence é a capacidade do LLM de gerar frases coerentes e ponderadas que conectam os fragmentos de conhecimento que ele apresenta — mesmo quando são imprecisos ou totalmente alucinatórios, há uma sensação de veracidade neles.

Aquela velha barra de pesquisa com a qual nos acostumamos tanto a interagir pode ser considerada o mecanismo RAG que usávamos quando nós mesmos éramos o agente de raciocínio. Hoje em dia, até mesmo os mecanismos de busca da internet estão transformando nossa tradicional experiência de busca lexical, baseada em "catar e digitar", em resumos gerados por inteligência artificial que respondem à consulta com um sumário dos resultados, ajudando os usuários a evitar a necessidade de clicar e avaliar cada resultado individualmente.

IA Generativa e RAG

A IA generativa tenta usar sua compreensão semântica do mundo para analisar a intenção subjetiva expressa em uma solicitação de bate-papo e, em seguida, usa suas habilidades de inferência para criar uma resposta especializada instantaneamente. Uma interação com IA generativa possui várias partes: começa com a entrada/consulta do usuário, conversas anteriores na sessão de bate-papo podem ser usadas como contexto adicional, e a instrução que informa ao LLM como raciocinar e quais procedimentos seguir na construção da resposta. As instruções evoluíram de orientações simples do tipo "explique isso para mim como se eu tivesse cinco anos de idade" para explicações detalhadas de como processar as solicitações. Essas análises geralmente incluem seções distintas que descrevem detalhes da personalidade/função da IA, raciocínio pré-geração/processo de pensamento interno, critérios objetivos, restrições, formato de saída, público-alvo, bem como exemplos para ajudar a demonstrar os resultados esperados.

Além da consulta do usuário e da mensagem do sistema, a geração aumentada de recuperação (RAG, na sigla em inglês) fornece informações contextuais adicionais no que é chamado de "janela de contexto". O RAG tem sido uma adição crucial à arquitetura; é o que usamos para informar o LLM sobre as peças que faltam em sua compreensão semântica do mundo.

As janelas de contexto podem ser um tanto exigentes em termos do que, onde e quanto você lhes fornece. O contexto selecionado é muito importante, obviamente, mas a relação sinal-ruído do contexto fornecido também importa, assim como o tamanho da janela.

Informação insuficiente

Fornecer pouca informação em uma consulta, prompt ou janela de contexto pode levar a alucinações, pois o LLM não consegue determinar com precisão o contexto semântico correto para gerar uma resposta. Existem também problemas com a similaridade vetorial dos tamanhos dos fragmentos de documentos — uma pergunta curta e simples pode não se alinhar semanticamente com os documentos ricos e detalhados encontrados em nossas bases de conhecimento vetorizadas. Foram desenvolvidas técnicas de expansão de consultas, como Hypothetical Document Embeddings (HyDE) , que utilizam LLMs para gerar uma resposta hipotética mais rica e expressiva do que a consulta curta. O perigo aqui, claro, é que o documento hipotético seja em si uma alucinação que afasta ainda mais o LLM do contexto correto.

Informação em excesso

Assim como acontece conosco, humanos, o excesso de informações em uma janela de contexto pode sobrecarregar e confundir um usuário de linguagem natural sobre quais são as partes importantes. O estouro de contexto (ou "deterioração de contexto ") afeta a qualidade e o desempenho das operações de IA generativa; ele impacta significativamente o "orçamento de atenção" do LLM (sua memória de trabalho) e dilui a relevância entre muitos tokens concorrentes. O conceito de "deterioração do contexto" também inclui a observação de que os autores de livros didáticos tendem a ter um viés posicional — eles preferem o conteúdo no início ou no final de uma janela de contexto em relação ao conteúdo na seção intermediária.

Informações que distraem ou são contraditórias

Quanto maior for a janela de contexto, maior será a probabilidade de incluir informações supérfluas ou conflitantes que podem distrair o usuário do LLM (Liderança em Aprendizagem) de selecionar e processar o contexto correto. De certa forma, isso se torna um problema de "lixo entra, lixo sai": simplesmente despejar um conjunto de resultados de documentos em uma janela de contexto fornece ao LLM muita informação para processar (potencialmente em excesso), mas dependendo de como o contexto foi selecionado, há uma possibilidade maior de informações conflitantes ou irrelevantes se infiltrarem.

IA Agêntica

Eu disse que havia muito o que abordar, mas conseguimos — finalmente estamos falando sobre tópicos de IA agente! A IA Agética é uma nova e empolgante aplicação das interfaces de chat do LLM que expande a capacidade da IA generativa (podemos já chamá-la de "legada"?) de sintetizar respostas com base em seu próprio conhecimento e nas informações contextuais fornecidas pelo usuário. À medida que a IA generativa amadureceu, percebemos que havia um certo nível de tarefas e automação que poderíamos delegar aos LLMs, inicialmente relegadas a atividades tediosas e de baixo risco que podem ser facilmente verificadas/validadas por um humano. Em um curto período de tempo, esse escopo inicial cresceu: uma janela de bate-papo do LLM agora pode ser a faísca que envia um agente de IA para planejar, executar e avaliar e adaptar seu plano de forma autônoma e iterativa para atingir o objetivo especificado. Os agentes têm acesso ao raciocínio dos seus LLMs, ao histórico de conversas e à memória cognitiva (na medida do possível), e também dispõem de ferramentas específicas que podem utilizar para atingir esse objetivo. Também estamos vendo agora arquiteturas que permitem que um agente de nível superior funcione como orquestrador de múltiplos subagentes, cada um com suas próprias cadeias lógicas, conjuntos de instruções, contexto e ferramentas.

Os agentes são o ponto de entrada para um fluxo de trabalho em grande parte automatizado: eles são autônomos, pois conseguem conversar com um usuário e, em seguida, usar a "lógica" para determinar quais ferramentas estão disponíveis para ajudar a responder à pergunta do usuário. As ferramentas são geralmente consideradas passivas em comparação com os agentes e são construídas para realizar um único tipo de tarefa. Os tipos de tarefas que uma ferramenta pode executar são praticamente ilimitados (o que é realmente empolgante!), mas uma das principais tarefas que as ferramentas realizam é coletar informações contextuais para que um agente as considere ao executar seu fluxo de trabalho.

Como tecnologia, a IA ativa ainda está em sua infância e propensa ao equivalente acadêmico do transtorno de déficit de atenção — ela facilmente esquece o que lhe foi pedido para fazer e, muitas vezes, sai fazendo outras coisas que não faziam parte do escopo da tarefa. Por trás da aparente magia, as habilidades de "raciocínio" dos LLMs ainda se baseiam em prever o próximo token mais provável em uma sequência. Para que o raciocínio (ou, um dia, a inteligência artificial geral (IAG)) se torne confiável e digno de confiança, precisamos ser capazes de verificar se, ao recebermos as informações corretas e mais atualizadas, elas raciocinarão da maneira que esperamos (e talvez nos forneçam aquela informação extra que não havíamos imaginado). Para que isso aconteça, as arquiteturas agentivas precisarão da capacidade de se comunicar claramente (protocolos), de aderir aos fluxos de trabalho e restrições que lhes impomos (diretrizes), de lembrar em que ponto da tarefa estão (estado), de gerenciar seu espaço de memória disponível e de validar se suas respostas são precisas e atendem aos critérios da tarefa.

Fale comigo em uma língua que eu possa entender.

Como é comum em novas áreas de desenvolvimento (especialmente no mundo dos LLMs), inicialmente existiram várias abordagens para a comunicação entre agentes e ferramentas, mas elas rapidamente convergiram para o Protocolo de Contexto do Modelo (MCP) como o padrão de facto. A definição de Protocolo de Contexto de Modelo está literalmente no nome: é o protocolo que um modelo usa para solicitar e receber informações contextuais . O MCP funciona como um adaptador universal para que os agentes LLM se conectem a ferramentas e fontes de dados externas; ele simplifica e padroniza as APIs para que diferentes estruturas e ferramentas LLM possam interoperar facilmente. Isso faz do MCP uma espécie de ponto de articulação entre a lógica de orquestração e os comandos do sistema dados a um agente para que ele execute tarefas de forma autônoma a serviço de seus objetivos, e as operações enviadas às ferramentas para que sejam executadas de maneira mais isolada (isolada, pelo menos, em relação ao agente iniciador).

Este ecossistema é tão novo que cada direção de expansão parece uma nova fronteira. Temos protocolos semelhantes para interações agente-a-agente (Agent2Agent (A2A) , claro!), bem como outros projetos para melhorar a memória de raciocínio do agente (ReasoningBank), para selecionar o melhor servidor MCP para a tarefa em questão (RAG-MCP) e usar análise semântica, como classificação zero-shot e detecção de padrões na entrada e saída, como Guardrails para controlar sobre o que um agente pode operar.

Você deve ter percebido que a intenção subjacente de cada um desses projetos é melhorar a qualidade e o controle das informações retornadas para uma janela de contexto do agente/genAI? Embora o ecossistema de IA agente continue a desenvolver a capacidade de lidar melhor com essas informações contextuais (para controlá-las, gerenciá-las e operá-las), sempre haverá a necessidade de recuperar as informações contextuais mais relevantes como matéria-prima para o agente processar.

Bem-vindo à engenharia de contexto!

Se você está familiarizado com os termos de IA generativa, provavelmente já ouviu falar de 'engenharia de prompts' - a essa altura, é quase uma pseudociência em si mesma. A engenharia de prompts é usada para encontrar as melhores e mais eficientes maneiras de descrever proativamente os comportamentos que você deseja que o LLM utilize ao gerar sua resposta. A " engenharia de contexto" estende as técnicas de "engenharia de prompts" além do lado do agente, abrangendo também as fontes e sistemas de contexto disponíveis no lado das ferramentas do protocolo MCP, e inclui os tópicos gerais de gerenciamento, processamento e geração de contexto:

• Gerenciamento de contexto - Relacionado à manutenção da eficiência de estado e contexto em fluxos de trabalho de agentes de longa duração e/ou mais complexos. Planejamento, acompanhamento e orquestração iterativos de tarefas e chamadas de ferramentas para atingir os objetivos do agente. Devido ao limitado "orçamento de atenção" com que os agentes têm que trabalhar, o gerenciamento de contexto se preocupa principalmente com técnicas que ajudam a refinar a janela de contexto para capturar tanto o escopo mais completo quanto os elementos mais importantes do contexto (sua precisão versus abrangência!). As técnicas incluem compressão, sumarização e persistência do contexto de etapas anteriores ou chamadas de ferramentas para liberar espaço na memória de trabalho para contexto adicional em etapas subsequentes.

• Processamento de contexto - Os passos lógicos e, idealmente, em sua maioria programáticos para integrar, normalizar ou refinar o contexto adquirido de fontes distintas, de modo que o agente possa raciocinar sobre todo o contexto de maneira relativamente uniforme. O objetivo principal é tornar o contexto de todas as fontes (sugestões, RAG, memória, etc.) o mais acessível possível ao agente.

• Geração de contexto - Se o processamento de contexto visa tornar o contexto recuperado utilizável para o agente, então a geração de contexto permite que o agente solicite e receba informações contextuais adicionais conforme desejar, mas também com restrições.

Os diversos elementos efêmeros dos aplicativos de bate-papo do LLM se relacionam diretamente (e às vezes de maneiras sobrepostas) com essas funções de alto nível da engenharia de contexto:

• Instruções / avisos do sistema - Os avisos servem de base para que a atividade de IA generativa (ou agentiva) direcione seu raciocínio para atingir o objetivo do usuário. Os prompts são um contexto por si só; não são apenas instruções de tom — frequentemente incluem lógica de execução da tarefa e regras para coisas como "pensar passo a passo" ou "respirar fundo" antes de responder, para validar se a resposta atende completamente à solicitação do usuário. Testes recentes demonstraram que as linguagens de marcação são muito eficazes para estruturar as diferentes partes de um enunciado, mas também é preciso ter cuidado para calibrar as instruções, encontrando um equilíbrio ideal entre serem vagas demais e específicas demais; queremos fornecer instruções suficientes para que o LLM encontre o contexto correto, mas não ser tão prescritivos a ponto de perder insights inesperados.

• Memória de curto prazo (estado/histórico) - A memória de curto prazo consiste essencialmente nas interações da sessão de bate-papo entre o usuário e o LLM. Essas informações são úteis para refinar o contexto em sessões ao vivo e podem ser salvas para consulta e continuação futuras.

• Memória de longo prazo - A memória de longo prazo deve consistir em informações que sejam úteis em múltiplas sessões. E não se trata apenas de bases de conhecimento específicas de domínio acessadas por meio do RAG; pesquisas recentes utilizam os resultados de solicitações anteriores de IA agentiva/generativa para aprender e referenciar em interações agentivas atuais. Algumas das inovações mais interessantes na área da memória de longo prazo estão relacionadas ao ajuste da forma como o estado é armazenado e vinculado, para que os agentes possam retomar de onde pararam.

• Saída estruturada - A cognição exige esforço, então provavelmente não é surpresa que, mesmo com capacidades de raciocínio, os LLMs (assim como os humanos) queiram despender menos esforço ao pensar e, na ausência de uma API ou protocolo definido, ter um mapa (um esquema) de como ler os dados retornados por uma chamada de ferramenta é extremamente útil. A inclusão de Saídas Estruturadas como parte da estrutura agentiva ajuda a tornar essas interações máquina a máquina mais rápidas e confiáveis, com menos necessidade de análise sintática guiada pelo pensamento.

• Ferramentas disponíveis - As ferramentas podem realizar todo tipo de tarefa, desde coletar informações adicionais (por exemplo, enviar consultas RAG para repositórios de dados corporativos ou por meio de APIs online) até executar ações automatizadas em nome do agente (como reservar um quarto de hotel com base nos critérios da solicitação do agente). As ferramentas também podem ser subagentes com suas próprias cadeias de processamento.

• Geração Aumentada por Recuperação (RAG) - Eu realmente gosto da descrição de RAG como "integração dinâmica de conhecimento". Conforme descrito anteriormente, RAG é a técnica para fornecer as informações adicionais às quais o LLM não teve acesso durante seu treinamento, ou seja, é uma reiteração das ideias que consideramos mais importantes para obter a resposta correta — aquela que é mais relevante para nossa pergunta subjetiva.

Poder cósmico fenomenal, espaço vital minúsculo!

A IA agente tem muitos novos domínios fascinantes e empolgantes para explorar! Ainda existem muitos dos antigos problemas tradicionais de recuperação e processamento de dados a serem resolvidos, mas também novas classes de desafios que só agora estão vindo à tona na nova era dos LLMs. Muitos dos problemas imediatos que estamos enfrentando hoje estão relacionados à engenharia de contexto, ou seja, a como fornecer aos LLMs (Learning Learning Machines - Máquinas de Memória de Longo Prazo) as informações contextuais adicionais de que precisam sem sobrecarregar seu espaço limitado de memória de trabalho.

A flexibilidade de agentes semiautônomos que têm acesso a uma variedade de ferramentas (e outros agentes) dá origem a tantas novas ideias para implementar IA que é difícil imaginar as diferentes maneiras pelas quais poderíamos juntar as peças. A maior parte da pesquisa atual se enquadra no campo da engenharia de contexto e está focada na construção de estruturas de gerenciamento de memória que possam lidar e rastrear quantidades maiores de contexto — isso porque os problemas de raciocínio profundo que realmente queremos que os LLMs resolvam apresentam maior complexidade e etapas de pensamento mais longas e multifásicas, onde a memorização é extremamente importante.

Grande parte da experimentação em curso na área visa encontrar a gestão de tarefas e as configurações de ferramentas ideais para alimentar a "boca" dos agentes. Cada chamada de ferramenta na cadeia de raciocínio de um agente acarreta um custo cumulativo, tanto em termos de computação necessária para executar a função dessa ferramenta quanto em termos do impacto na janela de contexto limitada. Algumas das técnicas mais recentes para gerenciar o contexto de agentes LLM causaram efeitos em cadeia indesejados, como o "colapso de contexto ", em que a compressão/resumo do contexto acumulado para tarefas de longa duração resulta em perda excessiva de dados. O objetivo é obter ferramentas que retornem um contexto conciso e preciso, sem que informações irrelevantes ocupem o valioso espaço de memória da janela de contexto.

Tantas possibilidades

Desejamos separação de funções com flexibilidade para reutilizar ferramentas/componentes, portanto, faz todo o sentido criar ferramentas dedicadas e automatizadas para conectar-se a fontes de dados específicas — cada ferramenta pode se especializar em consultar um tipo de repositório, um tipo de fluxo de dados ou até mesmo um caso de uso. Mas atenção: na ânsia de economizar tempo/dinheiro/provar que algo é possível, haverá uma forte tentação de usar os LLMs como ferramenta de federação… Tente não fazer isso, já passamos por essa situação antes! A consulta federada funciona como um "tradutor universal" que converte uma consulta recebida na sintaxe que o repositório remoto entende e, em seguida, precisa racionalizar os resultados de múltiplas fontes em uma resposta coerente. A federação como técnica funciona bem em pequenas escalas, mas em grandes escalas, e especialmente quando os dados são multimodais, a federação tenta preencher lacunas que são simplesmente muito grandes.

No mundo agentivo, o agente seria o federador e as ferramentas (através do MCP) seriam as conexões definidas manualmente com recursos distintos. Utilizar ferramentas específicas para acessar fontes de dados desconectadas pode parecer uma nova e poderosa maneira de unir dinamicamente diferentes fluxos de dados para cada consulta, mas usar essas ferramentas para fazer a mesma pergunta a várias fontes provavelmente acabará causando mais problemas do que soluções. Cada uma dessas fontes de dados provavelmente consiste em diferentes tipos de repositórios subjacentes, cada um com suas próprias capacidades de recuperar, classificar e proteger os dados neles contidos. Essas variações ou "incompatibilidades de impedância" entre os repositórios aumentam a carga de processamento, obviamente. Eles também podem introduzir informações ou sinais conflitantes, onde algo aparentemente inócuo como um desalinhamento na pontuação pode alterar drasticamente a importância atribuída a um trecho do contexto retornado e afetar a relevância da resposta gerada no final.

A troca de contexto também é difícil para os computadores.

Quando você envia um agente em uma missão, muitas vezes a primeira tarefa dele é encontrar todos os dados relevantes aos quais ele tem acesso. Assim como acontece com os humanos, se cada fonte de dados à qual o agente se conecta responde com informações diferentes e desagregadas, haverá uma carga cognitiva (embora não exatamente do mesmo tipo) associada à extração dos elementos contextuais relevantes do conteúdo recuperado. Isso requer tempo/computação, e cada pequeno detalhe se soma na cadeia lógica agentiva. Isso nos leva à conclusão de que, assim como está sendo discutido para o MCP, a maioria das ferramentas de agentes deveria se comportar mais como APIs — funções isoladas com entradas e saídas conhecidas, ajustadas para atender às necessidades de diferentes tipos de agentes. Aliás, estamos até percebendo que os LLMs precisam de contexto para contexto — eles se saem muito melhor em conectar os pontos semânticos, especialmente quando se trata de uma tarefa como traduzir linguagem natural para sintaxe estruturada, quando têm um esquema ao qual se referir (leia o manual, de fato!).

Intervalo da sétima entrada!

Já abordamos o impacto que os LLMs tiveram na recuperação e consulta de dados, bem como a forma como a janela de bate-papo está evoluindo para uma experiência de IA ativa. Vamos juntar os dois tópicos e ver como podemos usar nossos recursos modernos de busca e recuperação para melhorar nossos resultados em engenharia de contexto. Vamos para a Parte III: O poder da busca híbrida na engenharia de contexto!

Os sistemas atuais baseados em LLM estão evoluindo rapidamente, deixando de ser aplicações de modelo único e se tornando redes complexas onde agentes especializados trabalham juntos para realizar tarefas antes consideradas impossíveis pela computação moderna. À medida que esses sistemas se tornam mais complexos, a infraestrutura que permite a comunicação entre agentes e o acesso a ferramentas passa a ser o foco principal do desenvolvimento. Surgiram duas abordagens complementares para atender a essas necessidades: os protocolos Agent2Agent (A2A) para coordenação multiagente e o Model Context Protocol (MCP) para acesso padronizado a ferramentas e recursos.

Compreender quando usar cada um em harmonia com o outro e quando utilizá-los isoladamente pode impactar significativamente a escalabilidade, a facilidade de manutenção e a eficácia de suas aplicações. Este artigo explora os conceitos e implementações do modelo A2A (Application -to-Application) no exemplo prático de uma redação digital, onde agentes especializados em LLM (Legal Learning Management) colaboram para pesquisar, escrever, editar e publicar artigos de notícias.

Um repositório complementar pode ser encontrado aqui, e examinaremos exemplos concretos do A2A em ação perto do final do artigo, na Seção 5.

Pré-requisitos

O repositório consiste em implementações em Python dos agentes A2A. O Flask fornece um servidor de API, bem como um serviço de mensagens personalizado em Python chamado Event Hub, que encaminha mensagens para registro e atualizações da interface do usuário. Por fim, uma interface de usuário React é fornecida para uso independente dos recursos da sala de imprensa. Tudo está contido em uma imagem Docker para facilitar a implementação. Se você deseja executar os serviços diretamente em sua máquina, precisará garantir que tenha as seguintes tecnologias instaladas:

Linguagens e ambientes de execução

• Python 13.12 - Linguagem principal de backend

• Node.js 18+ - Interface de usuário React opcional

Frameworks principais e SDKs:

• SDK A2A 0.3.8 - Coordenação e comunicação de agentes

• SDK Antrópico - Integração com Claude para geração de IA

• Uvicorn - Servidor ASGI para executar agentes

• FastMCP 2.12.5+ - Implementação do servidor MCP

• React 18.2 - Framework de interface de usuário para front-end

Dados e pesquisa

• Elasticsearch 9.1.1+ - Indexação e pesquisa de artigos

Implantação do Docker (opcional, mas recomendada)

• Docker 28.5.1+

Seção 1: O que é Agent2Agent (A2A)?

Definição e conceitos fundamentais

Agent2Agent (A2A) é um protocolo padronizado para interação entre agentes LLM independentes. Em vez de um único sistema monolítico que lida com todas as tarefas, o A2A permite que vários agentes especializados se comuniquem, coordenem e colaborem para realizar fluxos de trabalho complexos que seriam difíceis, lentos ou simplesmente impossíveis de serem gerenciados com eficiência por um único agente.

Especificação oficial: https://a2a-protocol.org/latest/specification/

Origens e evolução

O conceito de comunicação Agente para Agente, ou sistemas multiagentes, tem raízes em sistemas distribuídos, microsserviços e pesquisas multiagentes que remontam a décadas. Os primeiros trabalhos em inteligência artificial distribuída lançaram as bases para agentes capazes de negociar, coordenar e colaborar. Esses primeiros sistemas eram dedicados a simulações sociais em larga escala, pesquisa acadêmica e gerenciamento de redes elétricas.

Com o surgimento da disponibilidade do LLM e a redução do custo de operação, os sistemas multiagentes tornaram-se acessíveis aos mercados "prosumidores", com o apoio do Google e da comunidade de pesquisa em IA em geral. Agora conhecidos como sistemas Agent2Agent, a adição do protocolo A2A evoluiu para um padrão moderno projetado especificamente para a era de múltiplos modelos de linguagem de grande porte coordenando esforços e tarefas.

O protocolo A2A garante comunicação e coordenação perfeitas entre os agentes, aplicando padrões e princípios consistentes aos pontos de interação onde os LLMs se conectam e se comunicam. Essa padronização permite que agentes de diferentes desenvolvedores — que utilizam diferentes modelos subjacentes — trabalhem juntos de forma eficaz.

Os protocolos de comunicação não são novidade e estão amplamente estabelecidos em praticamente todas as transações digitais realizadas na internet. Se você digitou https://www.elastic.co/search-labs Ao acessar este artigo por meio de um navegador, é muito provável que os protocolos TCP/IP, HTTP e de consulta DNS tenham sido executados, garantindo uma experiência de navegação consistente.

Características principais

Os sistemas A2A são construídos sobre diversos princípios fundamentais para garantir uma comunicação fluida. Com base nesses princípios, garante-se que diferentes agentes, utilizando diferentes LLMs, frameworks e linguagens de programação, interajam perfeitamente.

Eis os quatro princípios principais:

• Troca de mensagens: Os agentes comunicam-se por meio de mensagens estruturadas com propriedades e formatos bem definidos.

• Coordenação: Os agentes orquestram fluxos de trabalho complexos, delegando tarefas uns aos outros e gerenciando dependências sem bloquear outros agentes.

• Especialização: Cada agente se concentra em um domínio ou capacidade específica, tornando-se um especialista em sua área e oferecendo a conclusão de tarefas com base nessa habilidade.

• Estado distribuído: O estado e o conhecimento são distribuídos entre os agentes em vez de centralizados, sendo que os agentes têm a capacidade de atualizar uns aos outros sobre o progresso da tarefa, o estado e os retornos parciais (artefatos).

A redação: um exemplo prático

Imagine uma redação digital alimentada por agentes de IA, cada um especializado em um aspecto diferente do jornalismo:

• Chefe de Notícias (coordenador/cliente): Atribui pautas e supervisiona o fluxo de trabalho.

• Agente de reportagem: Redige artigos com base em pesquisas e entrevistas.

• Agente de Pesquisa: Reúne fatos, estatísticas e informações de contexto.

• Agente de Arquivo: Pesquisa artigos históricos e identifica tendências usando o Elasticsearch.

• Agente Editorial: Analisa artigos quanto à qualidade, estilo e otimização para SEO.

• Agente de Publicação: Publica artigos aprovados na plataforma do blog via CI/CD

Esses profissionais não trabalham isoladamente; quando o chefe de jornalismo atribui uma matéria sobre a adoção de energias renováveis, o repórter precisa do pesquisador para coletar as estatísticas, do editor para revisar o rascunho e do editor-chefe para publicar a versão final. Essa coordenação ocorre por meio de protocolos A2A.

Seção 2: Compreendendo a arquitetura A2A

Funções de Agente de Atendimento ao Cliente e Agente Remoto

Na arquitetura A2A, os agentes assumem dois papéis principais. O Agente Cliente é responsável por formular e comunicar tarefas a outros agentes no sistema. Identifica agentes remotos e suas capacidades, usando essas informações para tomar decisões fundamentadas sobre a delegação de tarefas. O agente do cliente coordena o fluxo de trabalho geral, garantindo que as tarefas sejam distribuídas adequadamente e que o sistema progrida em direção aos seus objetivos.

O Agente Remoto, por outro lado, executa tarefas delegadas pelos clientes. Ela fornece informações ou toma medidas específicas em resposta a solicitações, mas não inicia ações de forma independente. Os agentes remotos também podem se comunicar com outros agentes remotos conforme necessário para cumprir suas responsabilidades atribuídas, criando uma rede colaborativa de capacidades especializadas.

Em nossa redação, o Chefe de Notícias atua como agente do cliente, enquanto o Repórter, o Pesquisador, o Editor e o Diretor de Publicação são agentes remotos que respondem às solicitações e se coordenam entre si.

Principais funcionalidades A2A

Os protocolos A2A definem diversas capacidades que permitem a colaboração multiagente:

1. Descoberta

Os servidores A2A devem anunciar suas funcionalidades para que os clientes saibam quando e como utilizá-las para tarefas específicas. Isso é feito por meio de Cartões de Agente — documentos JSON que descrevem as habilidades, entradas e saídas de um agente. Os cartões de agente são disponibilizados em endpoints consistentes e conhecidos (como o endpoint recomendado /.well-known/agent-card.json ), permitindo que os clientes descubram e consultem as capacidades de um agente antes de iniciar a colaboração.

Abaixo, segue um exemplo de cartão de agente para o agente de arquivamento personalizado da Elastic, "Archie Archivist". Note que fornecedores de software como a Elastic hospedam seus agentes A2A e fornecem um URL para acesso:

Este cartão de agente revela vários aspectos importantes do agente de arquivamento da Elastic. O agente se identifica como "Archie Archivist" e declara claramente seu propósito: ajudar a encontrar documentos de notícias históricas em um índice do Elasticsearch. O cartão especifica o provedor (Elastic) e a versão do protocolo (0.3.0), garantindo a compatibilidade com outros agentes compatíveis com A2A. Mais importante ainda, a matriz skills enumera as capacidades específicas que este agente oferece, incluindo funcionalidades de pesquisa poderosas e exploração inteligente de índices. Cada habilidade define quais modos de entrada e saída ela suporta, permitindo que os clientes entendam exatamente como se comunicar com esse agente. Este agente deriva do serviço Agent Builder da Elastic, que fornece um conjunto de ferramentas nativas com suporte a LLM e endpoints de API para interagir com seu armazenamento de dados, e não apenas para recuperar dados dele. O acesso aos agentes A2A no Elasticsearch pode ser encontrado aqui.

2. Negociação

Clientes e agentes precisam concordar com os métodos de comunicação — sejam as interações realizadas por meio de texto, formulários, iframes ou até mesmo áudio/vídeo — para garantir a interação adequada do usuário e a troca de dados. Essa negociação ocorre no início da colaboração entre os agentes e estabelece os protocolos que irão reger sua interação ao longo do fluxo de trabalho. Por exemplo, um agente de atendimento ao cliente baseado em voz pode negociar para se comunicar por meio de fluxos de áudio, enquanto um agente de análise de dados pode preferir JSON estruturado. O processo de negociação garante que ambas as partes possam trocar informações de forma eficaz, num formato que se adeque às suas capacidades e às exigências da tarefa em questão.

As funcionalidades listadas no trecho JSON acima possuem esquemas de entrada e saída; estes definem uma expectativa de como outros agentes devem interagir com este agente.

3. Gestão de tarefas e estados

Clientes e agentes precisam de mecanismos para comunicar o status das tarefas, alterações e dependências ao longo da execução das mesmas. Isso inclui gerenciar todo o ciclo de vida de uma tarefa, desde a criação e atribuição até as atualizações de progresso e alterações de status. Os status típicos incluem pendente, em andamento, concluído ou reprovado. O sistema também deve rastrear as dependências entre as tarefas para garantir que o trabalho prévio seja concluído antes do início das tarefas dependentes. O tratamento de erros e a lógica de repetição também são componentes essenciais, permitindo que o sistema se recupere de forma adequada de falhas e continue progredindo em direção ao objetivo principal.

Exemplo de mensagem de tarefa:

Esta mensagem de tarefa de exemplo demonstra vários aspectos importantes da comunicação A2A.

• A estrutura da mensagem inclui metadados como um identificador único da mensagem, o tipo de mensagem que está sendo enviada, a identificação do remetente e do destinatário e um registro de data e hora para rastreamento e depuração.

• A carga útil contém as informações reais da tarefa, especificando qual funcionalidade está sendo invocada no agente remoto e fornecendo os parâmetros necessários para executar essa funcionalidade.

• A seção de contexto fornece informações adicionais que ajudam o agente receptor a entender o fluxo de trabalho mais amplo, incluindo prazos e níveis de prioridade que orientam a forma como o agente deve alocar seus recursos e programar seu trabalho.

4. Colaboração

Clientes e agentes devem dar suporte a uma interação dinâmica, porém estruturada, permitindo que os agentes solicitem esclarecimentos, informações ou subações do cliente, de outros agentes ou de usuários. Isso cria um ambiente colaborativo onde os agentes podem fazer perguntas de acompanhamento quando as instruções iniciais forem ambíguas, solicitar contexto adicional para tomar melhores decisões, delegar subtarefas a outros agentes com conhecimento mais adequado e fornecer resultados intermediários para feedback antes de prosseguir com a tarefa completa. Essa comunicação multidirecional garante que os agentes não trabalhem isoladamente, mas sim que estejam engajados em um diálogo contínuo que leva a melhores resultados.

Comunicação distribuída, ponto a ponto

A tecnologia A2A permite a comunicação distribuída, na qual os agentes podem ser hospedados por diferentes organizações, com alguns agentes mantidos internamente, enquanto outros são fornecidos por serviços de terceiros. Esses agentes podem ser executados em diferentes infraestruturas, abrangendo potencialmente vários provedores de nuvem ou centros de dados locais. Eles podem usar diferentes modelos de aprendizado de máquina subjacentes, com alguns agentes baseados em modelos GPT, outros em Claude e outros ainda em alternativas de código aberto. Os agentes podem até operar em diferentes regiões geográficas para cumprir os requisitos de soberania de dados ou reduzir a latência. Apesar dessa diversidade, todos os agentes concordam com um protocolo de comunicação comum para a troca de informações, garantindo a interoperabilidade independentemente dos detalhes de implementação. Essa arquitetura distribuída proporciona flexibilidade na forma como os sistemas são construídos e implantados, permitindo que as organizações combinem os melhores agentes e infraestrutura para suas necessidades específicas.

Esta é a arquitetura final do aplicativo da redação:

Seção 3: Protocolo de Contexto do Modelo (MCP)

Definição e propósito

O Protocolo de Contexto do Modelo (MCP) é um protocolo padronizado desenvolvido pela Anthropic para aprimorar e capacitar um LLM individual com ferramentas, recursos e instruções definidos pelo usuário, entre outras adições suplementares ao código-fonte. O MCP fornece uma interface universal entre modelos de linguagem e os recursos externos necessários para que eles concluam tarefas com eficácia. Este artigo descreve o estado atual do MCP com exemplos de casos de uso, tendências emergentes e a implementação da própria Elastic.

Conceitos básicos do MCP

O MCP opera em uma arquitetura cliente-servidor com três componentes principais:

• Clientes: aplicativos (como o Claude Desktop ou aplicativos de IA personalizados) que se conectam aos servidores MCP para acessar suas funcionalidades.

• Servidores: aplicações que expõem recursos, ferramentas e instruções para modelos de linguagem. Cada servidor é especializado em fornecer acesso a funcionalidades ou fontes de dados específicas.

  • Ferramentas: funções definidas pelo usuário que os modelos podem invocar para executar ações, como pesquisar bancos de dados, chamar APIs externas ou realizar transformações nos dados.

  • Recursos: fontes de dados que os modelos podem ler, fornecidas com dados dinâmicos ou estáticos e acessadas por meio de padrões de URI (semelhantes a rotas REST).

  • Instruções: modelos de instruções reutilizáveis com variáveis que orientam o modelo na realização de tarefas específicas.

Padrão de solicitação-resposta

O MCP segue um padrão de interação de solicitação-resposta familiar, semelhante às APIs REST. O cliente (LLM) solicita um recurso ou invoca uma ferramenta; em seguida, o servidor MCP processa a solicitação e retorna o resultado, que o LLM utiliza para continuar sua tarefa. Este modelo centralizado com servidores periféricos oferece um padrão de integração mais simples em comparação com a comunicação entre agentes ponto a ponto.

MCP na redação

Em nosso exemplo de redação, os agentes individuais usam servidores MCP para acessar as ferramentas e os dados de que precisam:

• O Agente de Pesquisa utiliza:

  • Servidor MCP da API de notícias (acesso a bancos de dados de notícias)

  • Servidor MCP de verificação de fatos (verifica alegações em fontes confiáveis)

  • Servidor MCP de base de dados académica (artigos académicos e investigação)

• O agente repórter utiliza:

  • Guia de Estilo do Servidor MCP (padrões de redação para redações)

  • Servidor MCP de modelos (modelos e formatos de artigos)

  • Servidor MCP da Biblioteca de Imagens (fotos e gráficos de banco de imagens)

• O Editor Agent utiliza:

  • Servidor MCP do Verificador Gramatical (ferramentas de qualidade linguística)

  • Servidor MCP de Detecção de Plágio (verificação de originalidade)

  • Servidor MCP de Análise de SEO (otimização de títulos e palavras-chave)

• O Publisher Agent utiliza:

  • Servidor CMS MCP (API do sistema de gerenciamento de conteúdo)

  • Servidor CI/CD MCP (pipeline de implantação)

  • Servidor MCP de análise (rastreamento e monitoramento)

Seção 4: comparação de arquiteturas

Quando usar o A2A

A arquitetura A2A se destaca em cenários que exigem colaboração multiagente genuína. Fluxos de trabalho com várias etapas que exigem coordenação se beneficiam muito do A2A, principalmente quando as tarefas envolvem várias etapas sequenciais ou paralelas, fluxos de trabalho que exigem iteração e refinamento, e processos com pontos de verificação e necessidades de validação. Em nosso exemplo de redação, o fluxo de trabalho da matéria exige que o Repórter escreva, mas pode precisar consultar o Pesquisador se a confiança em certos fatos for baixa, depois passar para o Editor e, finalmente, para o Editor-Chefe.

A especialização em domínios específicos em diversas áreas é outro caso de uso importante para o A2A. Quando vários especialistas em diversas áreas são necessários para realizar uma tarefa maior, com cada agente trazendo conhecimento profundo do domínio e capacidades de raciocínio especializadas para diferentes aspectos, o A2A fornece a estrutura de coordenação necessária para fazer essas conexões. A redação exemplifica isso perfeitamente: o pesquisador se especializa na coleta de informações, o repórter na redação e o editor no controle de qualidade — cada um com uma especialização distinta.

A necessidade de comportamento autônomo dos agentes torna o A2A particularmente valioso. Agentes capazes de tomar decisões independentes, demonstrar comportamento proativo com base em condições variáveis e se adaptar dinamicamente aos requisitos do fluxo de trabalho prosperam em uma arquitetura A2A. A escalabilidade horizontal de funções especializadas é outra vantagem fundamental: em vez de ter um único agente que domina todas as tarefas, vários agentes especializados trabalham em coordenação, e várias instâncias do mesmo agente podem lidar com subtarefas de forma assíncrona. Durante a cobertura de notícias de última hora em nossa redação, por exemplo, vários repórteres podem trabalhar simultaneamente em diferentes ângulos da mesma história.

Por fim, tarefas que exigem colaboração genuína entre múltiplos agentes são ideais para o A2A. Isso inclui mecanismos de avaliação do LLM como júri , sistemas de consenso e votação, e resolução colaborativa de problemas onde múltiplas perspectivas são necessárias para alcançar o melhor resultado.

Quando usar o MCP

O Protocolo de Contexto de Modelo é ideal para ampliar as capacidades de um único modelo de IA. Quando um único modelo de IA precisa acessar várias ferramentas e fontes de dados, o MCP oferece a solução perfeita, combinando raciocínio centralizado com ferramentas distribuídas e integração de ferramentas simplificada. Em nosso exemplo de redação, o Agente Pesquisador (um modelo) precisa de acesso a múltiplas fontes de dados, incluindo a API de Notícias, serviços de verificação de fatos e bases de dados acadêmicas — todas acessadas por meio de servidores MCP padronizados.

A integração de ferramentas padronizadas torna-se uma prioridade quando o amplo compartilhamento e a reutilização dessas integrações são importantes. O MCP se destaca aqui com seu ecossistema de servidores MCP pré-configurados, que reduzem significativamente o tempo de desenvolvimento para integrações comuns. Quando simplicidade e facilidade de manutenção são necessárias, os padrões de solicitação-resposta do MCP são familiares aos desenvolvedores, mais fáceis de entender e depurar do que sistemas distribuídos e apresentam menor complexidade operacional.

Por fim, o MCP costuma ser oferecido por fornecedores de software para facilitar a comunicação remota com seus sistemas. Esses servidores MCP oferecidos pelo provedor reduzem significativamente o tempo de integração e desenvolvimento, ao mesmo tempo que oferecem uma interface padronizada para sistemas proprietários, tornando a integração muito mais simples do que o desenvolvimento de APIs personalizadas.

Quando usar ambos (MCP da A2A ❤️)

Muitos sistemas sofisticados se beneficiam da combinação de A2A e MCP, conforme observado na documentação da A2A sobre integração com MCP. Sistemas que exigem tanto coordenação quanto padronização são candidatos ideais para uma abordagem híbrida. O A2A lida com a coordenação de agentes e a orquestração de fluxos de trabalho, enquanto o MCP fornece acesso a ferramentas para agentes individuais. Em nosso exemplo de redação, os agentes se coordenam por meio do sistema A2A (atendimento ao usuário), com o fluxo de trabalho indo do repórter para o pesquisador, para o editor e, finalmente, para o editor-chefe. No entanto, cada agente utiliza servidores MCP para suas ferramentas especializadas, criando uma clara separação arquitetural.

A presença de múltiplos agentes especializados, cada um utilizando o MCP para acesso a ferramentas, representa um padrão comum onde existe uma camada de coordenação de agentes gerenciada pelo A2A e uma camada de acesso a ferramentas gerenciada pelo MCP. Essa clara separação de responsabilidades torna os sistemas mais fáceis de entender e manter.

Os benefícios de combinar ambas as abordagens são substanciais. Você obtém os benefícios organizacionais dos sistemas multiagentes, incluindo especialização, autonomia e processamento paralelo, ao mesmo tempo que desfruta dos benefícios de padronização e ecossistema do MCP, como integração de ferramentas e acesso a recursos. Existe uma clara separação entre a coordenação de agentes (A2A) e o acesso a recursos (MCP) e, o que é importante, a A2A não é necessária para tarefas menores, como o acesso à API isoladamente — a MCP lida com essas tarefas de forma eficiente, sem a sobrecarga da orquestração multiagente.

FAQ: A2A vs. MCP - Casos de uso

Recurso

Agente para Agente (A2A)

Protocolo de Contexto do Modelo (MCP)

Híbrido (A2A + MCP)

Objetivo principal

Coordenação multiagente: Permite que uma equipe de agentes especializados trabalhe em conjunto em fluxos de trabalho complexos e com várias etapas.

Aprimoramento para agente único: Amplia a capacidade de um único LLM/Agente com ferramentas, recursos e dados externos.

Força combinada: A2A gerencia o fluxo de trabalho da equipe, enquanto a MCP fornece ferramentas para cada membro da equipe.

Exemplo de equipe de redação

A cadeia de fluxo de trabalho: Chefe de Notícias → Repórter → Pesquisador → Editor → Publicador. Esta é a camada de coordenação.

Ferramentas do agente individual: O Agente Repórter acessa o servidor de guia de estilo e o servidor de modelos (via MCP). Esta é a camada de acesso à ferramenta.

O sistema completo: o repórter coordena com o editor (A2A) e utiliza o servidor MCP da biblioteca de imagens para encontrar uma imagem para a matéria.

Quando usar qual

Quando você precisa de colaboração genuína, iteração e aprimoramento, ou de conhecimento especializado dividido entre vários agentes.

Quando um único agente precisa acessar várias ferramentas e fontes de dados ou requer integração padronizada com sistemas proprietários.

Quando você precisa dos benefícios organizacionais dos sistemas multiagentes e dos benefícios de padronização e ecossistema do MCP.

Benefício principal

Autonomia e escalabilidade: Os agentes podem tomar decisões independentes e o sistema permite a escalabilidade horizontal de funções especializadas.

Simplicidade e padronização: Mais fácil de depurar e manter devido ao raciocínio centralizado, além de fornecer uma interface universal para recursos.

Separação clara de responsabilidades: torna o sistema mais fácil de entender: A2A = trabalho em equipe, MCP = acesso à ferramenta.

Conclusão

Esta é a primeira parte de um artigo em duas seções que aborda a implementação de agentes baseados em A2A, reforçados com servidores MCP para fornecer suporte e acesso externo a dados e ferramentas. A próxima parte explorará o código real para demonstrar como eles funcionam em conjunto, simulando as atividades de uma redação online. Embora ambas as estruturas sejam extremamente capazes e flexíveis por si só, você verá o quanto elas se complementam quando trabalham em conjunto.

O que é fragmentação recursiva?

O particionamento recursivo percorrerá uma lista de seções fornecidas, separando padrões para dividir progressivamente um documento em segmentos menores até atingir o tamanho máximo desejado.

Como configuro o chunking recursivo?

A seguir, estão os valores configuráveis fornecidos pelo usuário para o particionamento recursivo:

• (obrigatório) max_chunk_size: O número máximo de palavras em um bloco.

• Qualquer uma das seguintes opções:

  • separatorsUma lista de padrões de strings de expressão regular que serão usados para dividir o documento em partes.

  • separator_group: Uma string que será mapeada para uma lista padrão de separadores definida pela Elastic para uso em tipos específicos de documentos. Atualmente, markdown e plaintext estão disponíveis.

Como funciona o particionamento recursivo?

O processo de fragmentação recursiva, dado um documento de entrada, um max_chunk_size (medido em palavras) e uma lista de strings separadoras, é o seguinte:

1. Se o documento de entrada já estiver dentro do tamanho máximo do bloco, retorne um único bloco que abranja toda a entrada.

2. Divida o texto em partes potenciais com base nas ocorrências do separador. Para cada bloco potencial:

   1. Se o fragmento em potencial estiver dentro do tamanho máximo permitido, adicione-o à lista de fragmentos a serem retornados ao usuário.

   2. Caso contrário, repita a partir do passo 2, usando apenas o texto do possível bloco e dividindo-o usando o próximo separador da lista. Se não houver mais separadores para tentar, recorra à segmentação baseada em frases.

Exemplos de configuração de fragmentação recursiva

Além do tamanho do bloco, a principal configuração para o particionamento recursivo é selecionar quais separadores devem ser usados para dividir seus documentos. Se você não sabe por onde começar, o Elasticsearch oferece alguns grupos de separadores padrão que podem ser usados para casos de uso comuns.

Utilizando grupos separadores

Para utilizar um grupo separador, basta fornecer o nome do grupo que você deseja usar ao configurar as opções de fragmentação. Por exemplo:

Isso lhe dará uma estratégia de fragmentação recursiva que utiliza a lista de separadores ["(?<!\\n)\\n\\n(?!\\n)", "(?<!\\n)\\n(?!\\n)")]. Isso funciona bem para aplicações genéricas de texto simples, dividindo o texto em dois caracteres de nova linha, seguidos por um caractere de nova linha.

Também oferecemos um grupo separador markdown que utilizará a lista de separadores:

Esta lista de separadores funcionará bem para casos de uso gerais de Markdown, dividindo o texto em cada um dos 6 níveis de título e nos caracteres de quebra de seção.

Ao criar um recurso (ponto de extremidade de inferência/campo de texto semântico), a lista de separadores correspondentes ao grupo de separadores no momento será armazenada em suas configurações. Se o grupo separador for atualizado posteriormente, isso não alterará o comportamento dos seus recursos já criados.

Utilizando uma lista separadora personalizada

Se um dos grupos de separadores predefinidos não for adequado ao seu caso de uso, você pode definir uma lista personalizada de separadores que atenda às suas necessidades. Observe que expressões regulares podem ser fornecidas dentro da lista de separadores. Segue abaixo um exemplo de configurações de fragmentação configuradas com separadores personalizados:

A estratégia de fragmentação acima dividirá em 2 caracteres de nova linha, seguidos por 1 caractere de nova linha e, por último, em uma string “<my-custom-separator>”.

Um exemplo de fragmentação recursiva em ação.

Vejamos um exemplo de fragmentação recursiva em ação. Neste exemplo, usaremos as seguintes configurações de fragmentação com uma lista personalizada de separadores que dividem um documento Markdown usando os dois níveis de cabeçalho superiores:

Vamos analisar um documento Markdown simples, sem divisões em partes (unchunked):

Agora vamos usar as configurações de fragmentação definidas acima para dividir o documento em partes:

Nota: A quebra de linha no final de cada bloco (exceto o Bloco 3) não está destacada, mas está incluída dentro dos limites reais do bloco.

Comece a usar o chunking recursivo hoje mesmo!

Para obter mais informações sobre como utilizar este recurso, consulte a documentação sobre como configurar as definições de fragmentação.

Para isso, utilizamos o SigLIP-2 do Google para gerar representações vetoriais tanto para imagens quanto para texto, e as armazenamos no banco de dados vetorial Elasticsearch. No momento da consulta, convertemos a entrada da pesquisa, seja texto ou imagem, em representações vetoriais (embeddings) e executamos buscas vetoriais kNN rápidas para recuperar os resultados. Essa configuração permite uma busca eficiente de texto para imagem e de imagem para imagem. A interface Streamlit UI dá vida a este projeto, fornecendo-nos um frontend que não só permite realizar buscas textuais para encontrar e visualizar as fotos correspondentes no álbum, como também nos permite identificar o pico da montanha na imagem carregada e visualizar outras fotos dessa montanha no álbum. Abordamos também as medidas que tomamos para melhorar a precisão da pesquisa, juntamente com dicas e truques práticos. Para uma exploração mais aprofundada, disponibilizamos um repositório no GitHub e um notebook no Colab.

Como tudo começou

Este post do blog foi inspirado por uma criança de 10 anos que me pediu para mostrar todas as fotos do Monte Ama Dablam que tirei na minha trilha até o Acampamento Base do Everest. Enquanto examinávamos o álbum de fotos, também me pediram para identificar vários outros picos de montanhas, alguns dos quais eu não sabia o nome.

Isso me deu a ideia de que este pode ser um projeto divertido de visão computacional. O que queríamos alcançar:

• Encontre fotos de um pico de montanha pelo nome.

• Adivinhe o nome do pico da montanha a partir de uma imagem e encontre picos semelhantes no álbum de fotos.

• Fazer com que as consultas de conceito funcionem (pessoa, rio, bandeiras de oração, etc.)

Montando a equipe dos sonhos: SigLIP-2, Elasticsearch e Streamlit

Rapidamente ficou claro que, para isso funcionar, precisaríamos transformar tanto o texto (“Ama Dablam”) quanto as imagens (fotos do meu álbum) em vetores que pudessem ser comparados de forma significativa, ou seja, no mesmo espaço vetorial. Uma vez feito isso, a busca se torna simplesmente "encontrar os vizinhos mais próximos".

Para gerar representações vetoriais de imagens, usamos um codificador multilíngue de visão e linguagem, de modo que uma foto de uma montanha e uma frase como "Ama Dablam" fiquem no mesmo espaço vetorial.

O SigLIP-2, lançado recentemente pelo Google, se encaixa bem aqui. Ele consegue gerar embeddings sem treinamento específico para a tarefa (uma configuração zero-shot ) e funciona bem para o nosso caso de uso: fotos não rotuladas e picos com nomes e idiomas diferentes. Como foi treinado para correspondência de texto ↔ imagem, uma foto da montanha tirada durante a trilha e um breve texto de exemplo resultam em representações vetoriais muito semelhantes, mesmo quando o idioma ou a ortografia da consulta variam.

O SigLIP-2 oferece um excelente equilíbrio entre qualidade e velocidade, suporta múltiplas resoluções de entrada e funciona tanto na CPU quanto na GPU. O SigLIP-2 foi projetado para ser mais resistente a fotos tiradas ao ar livre em comparação com modelos anteriores, como o CLIP original. Durante nossos testes, o SigLIP-2 gerou resultados confiáveis de forma consistente. Além disso, conta com amplo suporte, o que a torna a escolha óbvia para este projeto.

Em seguida, precisamos de um banco de dados vetorial para armazenar os embeddings e realizar buscas avançadas. Deveria suportar não apenas a busca kNN de cosseno em embeddings de imagem, mas também aplicar filtros de geolocalização e texto em uma única consulta. O Elasticsearch se encaixa bem aqui: ele lida muito bem com vetores (HNSW kNN em campos dense_vector), suporta busca híbrida que combina consultas de texto, vetores e geolocalização, e oferece filtragem e classificação prontas para uso. Ele também se adapta à escala horizontal, facilitando a expansão de um punhado de fotos para milhares. O cliente oficial do Elasticsearch para Python mantém a infraestrutura simples e se integra perfeitamente ao projeto. Por fim, precisamos de uma interface leve onde possamos inserir consultas de pesquisa e visualizar os resultados. Para uma demonstração rápida baseada em Python, o Streamlit é uma ótima opção. Ele fornece os recursos básicos de que precisamos: upload de arquivos, uma grade de imagens responsiva e menus suspensos para classificação e geolocalização. É fácil clonar e executar localmente, e também funciona em um notebook do Colab.

Implementação

Design e estratégia de indexação do Elasticsearch

Usaremos dois índices para este projeto: peaks_catalog e photos.

Índice do catálogo de picos

Este índice serve como um catálogo compacto dos picos de montanhas mais proeminentes que podem ser vistos durante a trilha até o Acampamento Base do Everest. Cada documento neste índice corresponde a um único pico de montanha, como o Monte Everest. Para cada documento de pico de montanha, armazenamos nomes/apelidos, coordenadas opcionais de latitude e longitude e um único vetor protótipo construído pela combinação de prompts de texto SigLIP-2 (e imagens de referência opcionais).

Mapeamento do índice:

Campo

Tipo

Exemplo

Objetivo/Observações

Vetor/Indexação

eu ia

palavra-chave

ama-dablam

Slug/ID estável

—

nomes

texto + subcampo de palavra-chave

["Ama Dablam","Amadablam"]

Aliases / nomes multilíngues; names.raw para filtros exatos

—

latlon

ponto_geográfico

{"lat":27.8617,"lon":86.8614}

Coordenadas GPS do pico como uma combinação de latitude/longitude (opcional)

—

elev_m

inteiro

6812

Elevação (opcional)

—

texto incorporado

dense_vector

768

Protótipo misto (com instruções e, opcionalmente, 1 a 3 imagens de referência) para este pico.

índice:true, similaridade:"cosseno", opções_de_índice:{type:"hnsw", m:16, ef_construction:128}

Este índice é usado principalmente para buscas de imagem para imagem, como identificar picos de montanhas a partir de imagens. Também utilizamos esse índice para aprimorar os resultados de busca de texto para imagem.

Em resumo, o peaks_catalog transforma a pergunta "Que montanha é esta?" em um problema de vizinho mais próximo focado, separando efetivamente a compreensão conceitual das complexidades dos dados da imagem.

Estratégia de indexação para o índice peaks_catalog: Começamos criando uma lista dos picos mais proeminentes visíveis durante a trilha do Campo Base do Everest. Para cada pico, armazenamos sua localização geográfica, nome, sinônimos e altitude em um arquivo YAML. O próximo passo é gerar o embedding para cada pico e armazená-lo no campo text_embed . Para gerar embeddings robustos, utilizamos a seguinte técnica:

• Crie um protótipo de texto usando:

  • nomes dos picos

  • Conjunto de prompts (usando vários prompts diferentes para tentar responder à mesma pergunta), por exemplo:

    • “uma foto natural do pico da montanha {name} no Himalaia, Nepal”

    • “{name} pico emblemático na região de Khumbu, paisagem alpina”

    • “{name} cume da montanha, neve, crista rochosa”

  • Anti-conceito opcional (indicando ao SigLIP-2 o que não deve ser correspondido): subtrair um pequeno vetor para "pintura, ilustração, pôster, mapa, logotipo" para que haja uma preferência por fotos reais.

• Opcionalmente, crie um protótipo de imagem se forem fornecidas imagens de referência do pico.

Em seguida, combinamos o texto e o protótipo da imagem para gerar a incorporação final. Finalmente, o documento é indexado com todos os campos necessários:

Documento de exemplo do índice peaks_catalog :

Índice de fotos

Este índice principal armazena informações detalhadas sobre todas as fotos do álbum. Cada documento representa uma única fotografia, contendo as seguintes informações:

• Caminho relativo até a foto no álbum de fotos. Isso pode ser usado para visualizar a imagem correspondente ou carregar a imagem na interface de pesquisa.

• Informações de GPS e horário da imagem.

• Vetor denso para codificação de imagem gerado por SigLIP-2.

• predicted_peaks Isso nos permite filtrar pelo nome do pico. Mapeamento de índice

Campo

Tipo

Exemplo

Objetivo/Observações

Vetor / Indexação

caminho

palavra-chave

dados/imagens/IMG_1234.HEIC

Como a interface do usuário abre a miniatura/imagem completa

—

imagem_recortada

dense_vector

768

Incorporação de imagem SigLIP-2

índice:true, similaridade:"cosseno", opções_de_índice:{type:"hnsw", m:16, ef_construction:128}

picos_previstos

palavra-chave

["ama-dablam","pumori"]

Top-K palpites no momento da indexação (filtro/faceta de UX barato)

—

GPS

ponto_geográfico

{"lat":27.96,"lon":86.83}

Ativa filtros geográficos

—

tempo_de_tiro

date

2023-10-18T09:41:00Z

Tempo de captura: classificar/filtrar

—

Estratégia de indexação para o índice de fotos: Para cada foto no álbum, fazemos o seguinte: Extrair informações das imagens shot_time e gps dos metadados da imagem.

• Incorporação de imagem SigLIP-2: passe a imagem pelo modelo e normalize o vetor usando a notação L2. Armazene o embedding no campo clip_image .

• Preveja os picos e armazene-os no campo predicted_peaks . Para fazer isso, primeiro pegamos o vetor de imagem da foto gerado na etapa anterior e, em seguida, executamos uma busca kNN rápida no campo text_embed no índice peaks_catalog . Mantemos os 3 ou 4 picos mais altos e ignoramos o resto.

• Calculamos o campo _id fazendo um hash no nome e caminho da imagem. Isso garante que não teremos duplicatas após várias execuções.

Após determinarmos todos os campos da foto, os documentos fotográficos são indexados em lotes usando indexação em massa :

Exemplo de documento do índice de fotos:

Em resumo, o índice de fotos é um armazenamento rápido, filtrável e compatível com kNN de todas as fotos do álbum. Seu mapeamento é propositalmente minimalista — apenas a estrutura necessária para recuperar rapidamente, exibir de forma clara e segmentar os resultados por espaço e tempo. Este índice serve para ambos os casos de uso de pesquisa. O script em Python para criar ambos os índices pode ser encontrado aqui.

A visualização do mapa Kibana abaixo exibe documentos do álbum de fotos como pontos verdes e picos de montanhas do índice peaks_catalog como triângulos vermelhos, com os pontos verdes alinhando-se bem com a trilha da caminhada até o Acampamento Base do Everest.

Pesquisar casos de uso

Busca por nome (texto para imagem): Este recurso permite que os usuários localizem fotos de picos de montanhas (e até mesmo conceitos abstratos como "bandeiras de oração") usando consultas de texto. Para isso, o texto de entrada é convertido em um vetor de texto usando o SigLIP-2. Para geração robusta de vetores de texto, empregamos a mesma estratégia usada para criar embeddings de texto no índice peaks_catalog : combinando a entrada de texto com um pequeno conjunto de prompts, subtraindo um vetor de anti-conceito menor e aplicando a normalização L2 para produzir o vetor de consulta final. Uma consulta kNN é então executada no campo photos.clip_image para recuperar os picos correspondentes principais, com base na similaridade de cosseno para encontrar as imagens mais próximas. Opcionalmente, os resultados da pesquisa podem ser tornados mais relevantes aplicando filtros geográficos e de data e/ou um filtro de termo photos.predicted_peaks como parte da consulta (veja exemplos de consulta abaixo). Isso ajuda a excluir picos semelhantes que, na verdade, não estão visíveis durante a trilha.

Consulta Elasticsearch com filtro geográfico:

Busca por imagem (imagem para imagem): Este recurso permite identificar uma montanha em uma imagem e encontrar outras imagens dessa mesma montanha no álbum de fotos. Quando uma imagem é carregada, ela é processada pelo codificador de imagens SigLIP-2 para gerar um vetor de imagem. Uma busca kNN é então realizada no campo peaks_catalog.text_embed para identificar os nomes de picos que melhor correspondem. Em seguida, um vetor de texto é gerado a partir desses nomes de picos correspondentes, e outra busca kNN é realizada no índice de fotos para localizar as imagens correspondentes.

Consulta do Elasticsearch:

Passo 1: Encontre os nomes de pico correspondentes.

Etapa 2: Realize uma busca no índice photos para encontrar as imagens correspondentes (mesma consulta mostrada no caso de uso de busca de texto para imagem):

Interface de usuário Streamlit

Para integrar tudo, criamos uma interface de usuário Streamlit simples que nos permite executar ambos os casos de uso de pesquisa. A barra lateral esquerda exibe uma lista rolável de picos (agregados de photos.predicted_peaks) com caixas de seleção e um minimapa/filtro geográfico. Na parte superior, há uma caixa de pesquisa por nome e um botão para identificar o usuário a partir de uma foto enviada. O painel central apresenta uma grade de miniaturas interativa que exibe as pontuações kNN, os indicadores de pico previsto e os horários de captura. Cada imagem inclui um botão "Ver imagem" para pré-visualizações em resolução total.

Pesquisa por upload de imagem: Prevemos o pico e encontramos picos correspondentes no álbum de fotos.

Pesquisa por texto: Encontre os picos correspondentes no álbum a partir do texto.

Conclusão

Tudo começou com uma pergunta: "Podemos ver as fotosdo Ama Dablam ?" transformou-se em um pequeno sistema de busca multimodal funcional. Capturamos fotos brutas da trilha, transformamos em embeddings SigLIP-2 e usamos o Elasticsearch para realizar uma rápida análise kNN sobre vetores, além de filtros geográficos/temporais simples para exibir as imagens relevantes. Ao longo do processo, separamos as preocupações com dois índices: um pequeno peaks_catalog de protótipos combinados (para identificação) e um índice escalável photos de vetores de imagem e EXIF (para recuperação). É prático, reproduzível e fácil de expandir.

Se você quiser ajustá-lo, existem algumas configurações que você pode modificar:

• Configurações de tempo de consulta: k (quantos vizinhos você deseja retornar) e num_candidates (quão ampla a pesquisa antes da pontuação final). Essas configurações são discutidas no blog aqui.

• Configurações de tempo de indexação: m (conectividade do grafo) e ef_construction (precisão do tempo de construção vs. memória). Para consultas, experimente também com ef_search — um valor maior geralmente significa melhor recuperação com alguma compensação de latência. Consulte este blog para obter mais detalhes sobre essas configurações.

Olhando para o futuro, modelos/reclassificadores nativos para busca multimodal e multilíngue chegarão em breve ao ecossistema Elastic, o que deverá tornar a recuperação de imagens/texto e a classificação híbrida ainda mais robustas e prontas para uso. ir.elastic.co+1

Se você quiser experimentar você mesmo:

• Repositório do GitHub: https://github.com/navneet83/multimodal-mountain-peak-search

• Guia rápido do Colab: https://github.com/navneet83/multimodal-mountain-peak-search/blob/main/notebooks/multimodal_mountain_peak_search.ipynb

Com isso, nossa jornada chegou ao fim e é hora de voltar para casa. Espero que isso tenha sido útil e, se você quebrar alguma coisa (ou melhorar alguma coisa), adoraria saber o que você mudou.

Mas a verdadeira mágica acontece quando você consegue integrar essas ferramentas personalizadas e orientadas a dados aos ambientes onde você passa a maior parte do tempo. E se o agente do seu editor de código pudesse acessar com segurança a base de conhecimento privada da sua organização?

É aí que entra o Protocolo de Contexto do Modelo (MCP) . O Elastic Agent Builder é fornecido com um servidor MCP integrado que dá acesso às ferramentas da plataforma.

Por que usar o servidor Elastic Agent Builder MCP?

Os agentes de IA são incrivelmente poderosos, mas seu conhecimento geralmente se limita aos dados com os quais foram treinados e às informações que podem pesquisar ativamente na internet pública. Eles não conhecem os documentos de design internos da sua empresa, os manuais de implantação específicos da sua equipe ou a estrutura exclusiva dos logs de seus aplicativos.

O desafio é fornecer ao seu assistente de IA o contexto especializado de que ele precisa. Este é precisamente o problema que o MCP foi projetado para resolver. MCP é um padrão aberto que permite que um modelo ou agente de IA descubra e utilize ferramentas externas.

Para tornar isso possível, o Elastic Agent Builder expõe nativamente suas ferramentas personalizadas por meio de um servidor MCP integrado. Isso significa que você pode conectar facilmente qualquer cliente compatível com MCP, como Cursor, VS Code ou Claude Desktop, com as ferramentas especializadas e com reconhecimento de dados que você criou com o Elastic Agent Builder.

Quando usar MCP (e quando não usar)

O Elastic Agent Builder inclui diversos protocolos para suportar diferentes padrões de integração. Escolher a opção certa é fundamental para criar fluxos de trabalho de IA eficazes.

• Use o MCP para aprimorar seu agente de IA (como no Cursor ou no VS Code) com ferramentas especializadas. Trata-se da abordagem "traga suas próprias ferramentas", que aprimora o assistente que você já usa com acesso seguro aos seus dados privados. Somente as ferramentas são expostas através do servidor MCP — os agentes da Elastic são independentes disso.

• Utilize o protocolo A2A para permitir que seu Elastic Agent totalmente personalizado colabore com outros agentes autônomos (como no Gemini Enterprise do Google). Isso se aplica à delegação entre agentes, onde cada agente trabalha em conjunto para resolver um problema.

• Utilize as APIs do Agent Builder para obter controle programático completo ao criar um aplicativo personalizado do zero.

Para um desenvolvedor que busca respostas em sua documentação interna sem sair do seu IDE, o MCP é a solução ideal.

Exemplo: suas ferramentas personalizadas no Cursor com o servidor Agent Builder MCP

Vamos analisar um exemplo prático que eu uso diariamente. Primeiro, rastreei e indexei nossa documentação interna de engenharia em um índice Elasticsearch chamado elastic-dev-docs. Embora pudéssemos usar as ferramentas genéricas e integradas disponíveis no Agent Builder, criaremos nossa própria ferramenta personalizada para consultar essa base de conhecimento específica.

O motivo para construir uma ferramenta personalizada é simples: controle e precisão. Essa abordagem nos dá o poder de executar uma consulta semântica rápida diretamente em nosso índice elastic-dev-docs . Temos controle total sobre qual índice é o alvo e como os dados são obtidos.

Agora, veja como podemos usar essa base de conhecimento personalizada em um editor de código com inteligência artificial, como o Cursor.

Etapa 1: Crie uma ferramenta de base de conhecimento personalizada no Agent Builder.

Primeiro, crie uma nova ferramenta no Construtor de Agentes. Uma descrição clara e específica da ferramenta é importante porque é assim que qualquer agente de IA, seja o Elastic Agent interno ou uma ferramenta externa como o Cursor, conectado via MCP, descobre e seleciona a ferramenta adequada para a tarefa correta.

Uma descrição precisa deve ser explícita. Por exemplo: “Realiza uma busca semântica no índice elastic-dev-docs para encontrar documentação interna de engenharia, manuais de operação e procedimentos de lançamento.”

Com isso configurado, a ferramenta está preparada para realizar uma busca semântica em nosso índice específico. Uma vez salvo, fica imediatamente disponível para ser servido.

Antes de conectar o dispositivo ao mundo exterior, você pode testá-lo diretamente na interface do usuário. Basta clicar no botão Testar para preencher manualmente os parâmetros, simulando o que o LLM fará, e inspecionar os resultados para confirmar se tudo está funcionando corretamente.

Etapa 2: Conecte o Cursor ao servidor Elastic MCP

O Elastic Agent Builder expõe automaticamente todas as ferramentas disponíveis por meio de um endpoint MCP seguro. Você pode encontrar o URL exclusivo do seu servidor na interface de Ferramentas do Kibana.

Para conectar ao Cursor, basta adicionar este URL ao seu arquivo de configuração, juntamente com uma chave de API Elastic para autenticação (saiba como criar uma chave de API ES). Utilizamos uma chave de API para autorização, pois isso garante que as ferramentas sejam executadas somente com as permissões que você concedeu, respeitando todas as suas regras de controle de acesso.

A configuração MCP em ~/.cursor/mcp.json do Cursor se parece com isto:

Após salvar a configuração, você deverá ver a ferramenta de servidor Elastic Agent Builder MCP disponível no Cursor.

Passo 3: pergunte à vontade!

Com a conexão estabelecida, os agentes do Cursor agora podem invocar suas ferramentas personalizadas para responder às suas perguntas ou orientar o processo de geração de código.

Vamos fazer uma pergunta específica:

“Consulte os passos para liberar o serviço de rastreamento na documentação interna de engenharia da organização do Elasticsearch”

Nos bastidores, a magia acontece:

1. O agente Cursor decide a melhor forma de responder à sua pergunta e, em seguida, decide ligar para o engineering_documentation_internal_search

2. Ela invoca a ferramenta com uma consulta em linguagem natural.

3. A ferramenta executa uma busca semântica no índice elastic-dev-docs e retorna os procedimentos mais relevantes e atualizados.

Obtemos uma resposta precisa e confiável com base em nossa documentação interna, tudo isso sem precisar sair do editor de código. A experiência é perfeita e impactante.

Sua vez de construir

Agora você viu como usar o servidor MCP integrado no Elastic Agent Builder para estender seus assistentes de IA com acesso seguro aos seus dados privados. Fundamentar os modelos em suas próprias informações é fundamental para torná-los verdadeiramente úteis.

Recapitulando, abordamos as etapas principais:

• Escolher o protocolo certo para as suas necessidades (MCP).

• Criação de uma ferramenta de base de conhecimento personalizada.

• Conectar essa ferramenta a um assistente de IDE como o Cursor.

Seus agentes e ferramentas não precisam mais estar desconectados de seu contexto mais valioso. Esperamos que este guia ajude você a criar fluxos de trabalho mais eficazes e orientados a dados. Boa construção!

No Elastic Stack, existem muitos aplicativos agentivos baseados em LLM, como o futuro Elastic AI Agent no Agent Builder (atualmente em versão de pré-visualização técnica) e o Attack Discovery (disponível para o público geral nas versões 8.18 e 9.0+), com mais em desenvolvimento. Durante o desenvolvimento, e mesmo após a implementação, é importante responder a estas perguntas:

• Como podemos estimar a qualidade das respostas dessas aplicações de IA?

• Se fizermos uma alteração, como podemos garantir que ela seja realmente uma melhoria e não cause deterioração na experiência do usuário?

• Como podemos testar esses resultados de forma fácil e repetível?

Diferentemente dos testes de software tradicionais, a avaliação de aplicações de IA generativa envolve métodos estatísticos, análises qualitativas minuciosas e uma compreensão profunda dos objetivos do usuário.

Este artigo detalha o processo que a equipe de desenvolvimento da Elastic utiliza para realizar avaliações, garantir a qualidade das alterações antes da implantação e monitorar o desempenho do sistema. Nosso objetivo é garantir que cada mudança seja respaldada por evidências, resultando em resultados confiáveis e verificáveis. Parte desse processo está integrada diretamente ao Kibana, refletindo nosso compromisso com a transparência como parte de nossa filosofia de código aberto. Ao compartilhar abertamente partes de nossos dados e métricas de avaliação, buscamos fomentar a confiança da comunidade e fornecer uma estrutura clara para qualquer pessoa que desenvolva agentes de IA ou utilize nossos produtos.

Exemplos de produtos

Os métodos utilizados neste documento serviram de base para a forma como iteramos e aprimoramos soluções como o Attack Discovery e o Elastic AI Agent. Uma breve introdução aos dois, respectivamente:

Descoberta de ataques da Elastic Security

A descoberta de ataques utiliza LLMs para identificar e resumir sequências de ataques no Elastic. Com base nos alertas do Elastic Security em um determinado período (padrão de 24 horas), o fluxo de trabalho automatizado do Attack Discovery identificará automaticamente se ocorreram ataques, além de informações importantes, como quais hosts ou usuários foram comprometidos e quais alertas contribuíram para essa conclusão.

O objetivo é que a solução baseada em LLM produza um resultado pelo menos tão bom quanto o de um ser humano.

Agente de IA Elástico

O Elastic Agent Builder é a nossa nova plataforma para criar agentes de IA sensíveis ao contexto que aproveitam todos os nossos recursos de busca. Ele vem com o Elastic AI Agent, um agente pré-construído de uso geral, projetado para ajudar os usuários a entender e obter respostas a partir de seus dados por meio de interação conversacional.

O agente consegue isso identificando automaticamente informações relevantes no Elasticsearch ou em bases de conhecimento conectadas e utilizando um conjunto de ferramentas pré-construídas para interagir com elas. Isso permite que o Elastic AI Agent responda a uma ampla gama de consultas de usuários, desde perguntas e respostas simples sobre um único documento até solicitações complexas que exigem agregação e buscas de uma ou várias etapas em diversos índices.

Medindo melhorias por meio de experimentos

No contexto de agentes de IA, um experimento é uma mudança estruturada e testável no sistema, projetada para melhorar o desempenho em dimensões bem definidas (por exemplo, utilidade, correção, latência). O objetivo é responder de forma definitiva: "Se incorporarmos essa alteração, podemos garantir que ela representa uma melhoria real e não prejudicará a experiência do usuário?"

A maioria dos experimentos que realizamos geralmente inclui:

• Uma hipótese: uma afirmação específica e falseável. Exemplo: “Adicionar acesso a uma ferramenta de descoberta de ataques melhora a precisão das consultas relacionadas à segurança.”

• Critérios de sucesso: Limiares claros que definem o que significa "sucesso". Exemplo: “Melhoria de 5% na pontuação de correção no conjunto de dados de segurança, sem degradação em outros locais.”

• Plano de avaliação: Como medimos o sucesso (métricas, conjuntos de dados, método de comparação)

Um experimento bem-sucedido é um processo sistemático de investigação. Toda alteração, desde um pequeno ajuste de um prompt até uma grande mudança arquitetônica, segue estes sete passos para garantir que os resultados sejam significativos e acionáveis:

• Etapa 1: Identificar o problema

• Etapa 2: Definir métricas

• Etapa 3: Formule uma hipótese clara

• Etapa 4: Preparar o conjunto de dados de avaliação

• Etapa 5: Execute o experimento

• Etapa 6: Analisar resultados + iterar

• Etapa 7: Tome uma decisão e documente-a.

Um exemplo dessas etapas é ilustrado na Figura 1. As subseções a seguir explicarão cada etapa, e detalharemos os aspectos técnicos de cada etapa em documentos futuros.

Passo a passo com exemplos reais do Elastic

Etapa 1: Identificar o problema

Qual é exatamente o problema que essa mudança visa resolver?

Exemplo de detecção de ataques: os resumos são ocasionalmente incompletos ou atividades benignas são erroneamente sinalizadas como ataques (falsos positivos).

Exemplo de agente de IA elástica: a seleção de ferramentas do agente, especialmente para consultas analíticas, é subótima e inconsistente, muitas vezes levando à escolha da ferramenta errada. Isso, por sua vez, aumenta os custos dos tokens e a latência.

Etapa 2: Definir métricas

Torne o problema mensurável, para que possamos comparar uma mudança com o estado atual.

As métricas comuns incluem precisão e revocação, similaridade semântica, factualidade, e assim por diante. Dependendo do caso de uso, utilizamos verificações de código para calcular as métricas, como a correspondência de IDs de alerta ou URLs recuperados corretamente, ou técnicas como LLM-as-judge para respostas mais livres.

Abaixo estão alguns exemplos (lista não exaustiva) de métricas usadas nos experimentos:

Descoberta de ataques

Métrica

Descrição

Precisão e memorização

Compare os IDs de alerta entre as saídas reais e esperadas para medir a precisão da detecção.

Semelhança

Utilize o BERTScore para comparar a similaridade semântica do texto de resposta.

Factualidade

Os principais indicadores de comprometimento (IOCs) estão presentes? As táticas MITRE (taxonomia de ataques do setor) estão corretamente representadas?

Consistência da cadeia de ataque

Compare o número de descobertas para verificar se houve superestimação ou subestimação da notificação do ataque.

Agente de IA Elástico

Métrica

Descrição

Precisão e memorização

Comparar os documentos/informações recuperados pelo agente para responder a uma consulta do usuário com as informações ou documentos realmente necessários para responder à consulta, a fim de medir a precisão da recuperação de informações.

Factualidade

Os principais fatos necessários para responder à consulta do usuário estão presentes? Os fatos estão na ordem correta para questões processuais?

Relevância da resposta

A resposta contém informações periféricas ou não relacionadas à consulta do usuário?

Completude da resposta

A resposta atende a todas as partes da consulta do usuário? A resposta contém todas as informações presentes na verdade fundamental?

Validação ES|QL

O código ES|QL gerado está sintaticamente correto? É funcionalmente idêntico ao ES|QL original?

Etapa 3: Formule uma hipótese clara

Estabeleça critérios de sucesso claros usando o problema e as métricas definidas acima.

Exemplo de agente de IA elástico:

1. Implementar alterações nas descrições das ferramentas relevance_search e nl_search para definir claramente suas funções e casos de uso específicos.

2. Prevemos que melhoraremos a precisão da invocação de nossa ferramenta em 25%.

3. Verificaremos se isso representa um saldo positivo, garantindo que não haja impacto negativo em outras métricas, por exemplo... factualidade e completude.

4. Acreditamos que isso funcionará porque descrições precisas das ferramentas ajudarão o agente a selecionar e aplicar com mais exatidão a ferramenta de busca mais adequada para diferentes tipos de consulta, reduzindo o uso incorreto e melhorando a eficácia geral da busca.

Etapa 4: Preparar o conjunto de dados de avaliação

Para medir o desempenho do sistema, utilizamos conjuntos de dados que capturam cenários do mundo real.

Dependendo do tipo de avaliação que estivermos realizando, podemos precisar de diferentes formatos de dados, como dados brutos inseridos em um LLM (por exemplo, cenários de ataque para descoberta de ataques) e resultados esperados. Se o aplicativo for um chatbot, as entradas podem ser consultas do usuário e as saídas podem ser respostas corretas do chatbot, links corretos que ele deveria ter recuperado e assim por diante.

Exemplo de descoberta de ataques:

10 novos cenários de ataque

8 episódios de Oh My Malware (ohmymalware.com)

4 cenários de múltiplos ataques (criados pela combinação de ataques nas duas primeiras categorias)

3 cenários benignos

Exemplo de conjunto de dados para avaliação de agentes de IA elástica (Link para o conjunto de dados do Kibana):

14 Índices que utilizam conjuntos de dados de código aberto para simular múltiplas fontes em KB.

5 tipos de consulta (analítica, recuperação de texto, híbrida…)

7 tipos de intenção de consulta (procedimental, factual - classificação, investigativa; …)

Etapa 5: Execute o experimento

Execute o experimento gerando respostas tanto do agente existente quanto da versão modificada em relação ao conjunto de dados de avaliação. Calcule métricas como a veracidade factual (ver passo 2).

Combinamos diversas avaliações com base nas métricas exigidas na Etapa 2:

• Avaliação baseada em regras (por exemplo, (Use Python/TypeScript para verificar se o arquivo .json é válido)

• LLM como juiz (consultar um LLM separado para verificar se uma resposta é factualmente consistente com um documento original)

• Revisão com intervenção humana para verificações de qualidade e nuances.

Etapa 6: Analisar resultados + iterar

Agora que temos as métricas, vamos analisar os resultados. Mesmo que os resultados atendam aos critérios de sucesso definidos na etapa 3, ainda faremos uma revisão humana antes de incorporar a alteração à produção; se os resultados não atenderem aos critérios, iteraremos e corrigiremos os problemas e, em seguida, executaremos as avaliações na nova alteração.

Prevemos que serão necessárias algumas iterações para encontrarmos a melhor alteração antes de a consolidarmos. Assim como é feito executar testes de software locais antes de enviar uma alteração, as avaliações offline podem ser executadas com alterações locais ou com várias alterações propostas. Automatizar o salvamento de resultados experimentais, pontuações compostas e visualizações é útil para agilizar a análise.

Etapa 7: Tome uma decisão e documente-a.

Com base em uma estrutura de decisão e critérios de aceitação, decida sobre a incorporação da alteração e documente o experimento. A tomada de decisões é multifacetada e pode considerar fatores que vão além do conjunto de dados de avaliação, como verificar cenários de regressão em outros conjuntos de dados ou ponderar o custo-benefício de uma mudança proposta.

Exemplo: Após testar e comparar algumas iterações, escolha a alteração com a melhor pontuação para enviar aos gerentes de produto e outras partes interessadas relevantes para aprovação. Anexe os resultados das etapas anteriores para auxiliar na tomada de decisão. Para mais exemplos sobre a descoberta de ataques, consulte Nos bastidores dos recursos de IA generativa do Elastic Security.

Conclusão

Neste blog, descrevemos o processo completo de um fluxo de trabalho de experimento, ilustrando como avaliamos e testamos as alterações em um sistema de agentes antes de disponibilizá-las aos usuários da Elastic. Também fornecemos alguns exemplos de como aprimorar fluxos de trabalho baseados em agentes no Elastic. Em publicações subsequentes no blog, detalharemos diferentes etapas, como criar um bom conjunto de dados, projetar métricas confiáveis e tomar decisões quando várias métricas estão envolvidas.

Mas e se você quiser usar seus agentes personalizados com os aplicativos e ferramentas de produtividade que você já utiliza?

É aí que entra o protocolo Agente-para-Agente (A2A) . A2A é um padrão aberto de interoperabilidade, permitindo que agentes de diferentes plataformas se comuniquem e colaborem. E nós o integramos diretamente ao Elastic Agent Builder.

Hoje, vamos mostrar como pegar um agente personalizado que você criou e expô-lo a outros serviços, especificamente, ao Gemini Enterprise (antigo Agentspace).

O poder dos padrões abertos: por que a abordagem A2A é importante

Na postagem do blog "Seu primeiro Elastic Agent", mostramos como criar agentes personalizados, como um agente de Assistente Financeiro com acesso seguro aos seus dados de mercado. Mas seu valor é limitado se você não puder disponibilizar suas informações em outros ambientes, como o Gemini Enterprise, sem refazer todo o seu trabalho.

Esse desafio de interoperabilidade é o que impede o avanço da IA ativa. Os agentes precisam de uma linguagem comum para se comunicarem entre plataformas, e essa é precisamente a função do protocolo A2A. Ela fornece uma camada de comunicação padrão que não só permite a interação direta com o agente, como também abre caminho para um futuro em que agentes especializados em toda a organização possam colaborar e compartilhar informações.

Para tornar isso possível, o Elastic Agent Builder oferece suporte nativo ao protocolo A2A por meio de dois endpoints padrão para todos os seus agentes:

1. O endpoint do cartão do agente (GET {your-kibana-url}/api/agent_builder/a2a/{agentId}.json) - Este funciona como o cartão de visita personalizado do seu agente. Ele fornece metadados sobre seu agente (nome, descrição, capacidades, etc.) para qualquer serviço compatível com A2A.

2. O ponto final do protocolo A2A (POST {your-kibana-url}/api/agent_builder/a2a/{agentId}) - Este é o canal de comunicação. Outros agentes enviam suas solicitações para cá, e seu agente as processa e retorna uma resposta, tudo seguindo a especificação do protocolo A2A.

Teste seu agente com o inspetor A2A.

Antes de conectar nosso agente a um sistema de produção, é bom verificar se a comunicação está funcionando corretamente. A maneira mais fácil de fazer isso é com o A2A Inspector, uma ferramenta projetada especificamente para testar e depurar integrações A2A.

Colocar o inspetor em funcionamento é simples. Você pode clonar o repositório a2a-inspector e seguir as instruções do arquivo README para executar o aplicativo. Uma vez iniciado, o UI está disponível por padrão em http://localhost:5001/.

Para conectar o A2A Inspector ao seu agente, você precisará fornecer duas informações essenciais:

• URL do Cartão do Agente: Este é o endpoint que descreve o seu agente. Para o agente Assistente Financeiro da nossa postagem anterior, este URL seria {your-kibana-url}/api/agent_builder/a2a/financial_assistant.json.

• Cabeçalho de autenticação: Usaremos uma chave de API padrão para autenticação.

Após inserir esses detalhes na interface do inspetor, você poderá se conectar e começar a conversar com seu agente imediatamente.

Essa validação simples nos dá a certeza de que nosso agente está configurado corretamente e pronto para a próxima etapa.

Entre ao vivo! Seu agente personalizado na Gemini Enterprise

Agora vem a parte emocionante: dar vida ao nosso agente de consultoria financeira personalizado dentro do Gemini Enterprise (antigo Agentspace). Essa integração é viabilizada pelo Elastic AI Agent, que está disponível no Google Cloud Marketplace.

Uma vez conectado, o Gemini Enterprise usa o protocolo A2A para se comunicar diretamente com seu agente. É aqui que o verdadeiro poder da interoperabilidade se destaca: os usuários agora podem acessar insights profundos e baseados em dados do seu agente Elasticsearch personalizado sem precisar sair do ambiente familiar. Você pode ver seu agente elástico personalizado na lista de agentes:

Imagine um usuário do Gemini Enterprise perguntando:

"Estou preocupado com o sentimento do mercado. Você pode me mostrar quais dos nossos clientes estão mais vulneráveis a notícias negativas?"

Nos bastidores, o Gemini Enterprise encaminha essa consulta por meio do protocolo A2A para o seu Elastic Agent personalizado. Seu agente então utiliza suas ferramentas especializadas para consultar seus dados, formular uma resposta e enviá-la de volta. Para o usuário final, a experiência é perfeita.

E não para por aqui! A resposta obtida com o agente elástico agora pode ser usada como contexto para suas próximas perguntas, que podem acionar um agente especializado diferente (por exemplo, seu agente de plataforma de investimentos para ajustar a exposição a empresas listadas). Tudo isso sem sair da sua barra de pesquisa.

Com seus agentes Elastic implantados no Gemini Enterprise com A2A, você pode unificar acesso, orquestração e fluxos de trabalho, eliminando atritos entre IA, pesquisa e sistemas corporativos, oferecendo uma interface de usuário única onde os usuários interagem com seus dados e ferramentas — tudo em contexto. Para os usuários, isso significa menos troca de ferramentas e assistentes de IA mais intuitivos e capazes. Para as organizações, isso significa governança coerente, escalabilidade e interoperabilidade integradas.

Sua vez de construir

Agora você tem as ferramentas para disponibilizar seus Agentes Elásticos em qualquer lugar. Ao aproveitar o protocolo aberto A2A, você pode ampliar o alcance de seus agentes personalizados e orientados a dados.

Neste post, apresentamos os principais passos:

• Exponha seu agente por meio do cartão de agente A2A e dos endpoints do protocolo.

• Testando a conexão com o A2A Inspector.

• Integrar seu agente em tempo real a um serviço externo como o Gemini Enterprise do Google.

Seus agentes não precisam mais ficar isolados. Estamos ansiosos para ver os sistemas poderosos e interconectados que vocês criarão. Boa construção!

A maneira mais fácil de começar é com sua avaliação gratuita do Elastic Cloud no Google Cloud Marketplace.

Imagine um gerente financeiro que precisa se atualizar antes de uma reunião com um cliente. Em vez de vasculhar manualmente os feeds de notícias e comparar painéis de portfólio, agora eles podem simplesmente fazer uma pergunta direta ao seu agente personalizado. Essa é a vantagem de uma abordagem que prioriza o bate-papo. O gestor tem acesso direto e conversacional aos seus dados, podendo fazer perguntas como: "Quais são as últimas notícias sobre a ACME Corp e como isso afeta os investimentos do meu cliente?" e obtendo uma resposta sintetizada e especializada em segundos.

Embora estejamos criando um especialista financeiro hoje, as aplicações são tão variadas quanto seus dados. O mesmo poder pode criar um analista de cibersegurança para procurar ameaças, um engenheiro de confiabilidade de sites para diagnosticar uma interrupção ou um gerente de marketing para otimizar uma campanha. Independentemente da área, a missão principal é a mesma: transformar seus dados em um especialista com quem você possa conversar.

Etapa 0: Nosso conjunto de dados

Nosso conjunto de dados hoje é um conjunto de dados sintético baseado em finanças, composto por contas financeiras, posições de ativos, notícias e relatórios financeiros. Embora sintética, ela replica uma versão simplificada de um conjunto de dados financeiro real.

financial_accountsPortfólios de clientes com perfis de risco

financial_holdingsPosições em ações/ETFs/títulos com histórico de compras

financial_asset_detailsDetalhes sobre a ação/ETF/título

financial_newsArtigos de mercado gerados por IA com análise de sentimento

financial_reportsResultados da empresa e notas dos analistas

Você pode carregar este conjunto de dados por conta própria seguindo as instruções do notebook que acompanha este documento, localizado aqui.

Etapa 1: A Base — Sua Lógica de Negócios em ES|QL

Toda habilidade de IA começa com uma base lógica sólida. Para o nosso agente de Gestão Financeira, precisamos ensiná-lo a responder a uma pergunta comum: "Estou preocupado com o sentimento do mercado." Você pode me mostrar quais dos nossos clientes correm maior risco em caso de más notícias? Essa questão vai além de uma simples pesquisa. Isso exige que correlacionemos o sentimento do mercado com as carteiras dos clientes.

Precisamos encontrar os ativos mencionados em artigos negativos, identificar todos os clientes que possuem esses ativos, calcular o valor de mercado atual da sua exposição e, em seguida, classificar os resultados para priorizar o maior risco. Essa análise complexa de múltiplas junções é a tarefa perfeita para nossa ferramenta avançada ES|QL.

Aqui está a consulta completa que usaremos. Parece impressionante, mas os conceitos são simples.

Analisando em detalhes: Junções e guarda-corpos

Nesta consulta, dois conceitos importantes entram em jogo e são essenciais para a criação do Agent Builder.

1. A junção de pesquisa

Durante anos, uma das funcionalidades mais solicitadas no Elasticsearch tem sido a capacidade de unir dados de diferentes índices com base em uma chave comum. Com ES|QL, isso agora é possível com LOOKUP JOIN.

Em nossa nova consulta, realizamos uma cadeia de três LOOKUP JOIN: primeiro conectando notícias negativas aos detalhes dos ativos, depois vinculando esses ativos às participações do cliente e, finalmente, unindo às informações da conta do cliente. Isso gera um resultado incrivelmente rico a partir de quatro índices diferentes em uma única consulta eficiente. Isso significa que podemos combinar conjuntos de dados distintos para criar uma resposta única e esclarecedora sem precisar desnormalizar todos os nossos dados em um único índice gigante antecipadamente.

2. Parâmetros como guarda-corpos LLM

Você notará que a consulta usa ?time_duration. Isso não é apenas uma variável; é uma proteção para a IA. Embora os Modelos de Linguagem de Grande Porte (LLMs, na sigla em inglês) sejam ótimos para gerar consultas, permitir que eles tenham livre acesso aos seus dados pode levar a consultas ineficientes ou até mesmo incorretas.

Ao criar uma consulta parametrizada, forçamos o LLM a funcionar dentro da lógica de negócios testada, eficiente e correta que um especialista humano já definiu. É semelhante à forma como os desenvolvedores usam modelos de pesquisa há anos para expor com segurança os recursos de consulta aos aplicativos. O agente pode interpretar a solicitação de um usuário como "esta semana" para preencher o parâmetro time_duration , mas deve usar nossa estrutura de consulta para obter a resposta. Isso nos proporciona o equilíbrio perfeito entre flexibilidade e controle.

Em última análise, essa consulta permite que um especialista que entende os dados incorpore seu conhecimento em uma ferramenta. Outras pessoas — e agentes de IA — podem então usar essa ferramenta para obter resultados correlacionados, fornecendo simplesmente um único parâmetro, sem precisar saber nada sobre a complexidade subjacente.

Etapa 2: A Habilidade — Transformar uma Consulta em uma Ferramenta Reutilizável

Uma consulta ES|QL é apenas texto até que a registremos como uma ferramenta. No Construtor de Agentes, uma ferramenta é mais do que apenas uma consulta salva; é uma "habilidade" que um agente de IA pode entender e optar por usar. A mágica está na descrição em linguagem natural que fornecemos. Essa descrição serve de ponte entre a pergunta do usuário e a lógica de consulta subjacente. Vamos registrar a consulta que acabamos de criar.

O Caminho da Interface do Usuário

Criar uma ferramenta no Kibana é um processo simples.

1. Navegue até Agentes

• Clique em Ferramentas ou Gerenciar Ferramentas e clique no botão Nova ferramenta .

2. Preencha o formulário com os seguintes dados:

• ID da ferramenta: find_client_exposure_to_negative_news

eu. Este é o ID exclusivo da ferramenta.

• Descrição: "Identifica a exposição da carteira de clientes a notícias negativas." Esta ferramenta analisa notícias e relatórios recentes em busca de sentimentos negativos, identifica o ativo associado e encontra todos os clientes que possuem esse ativo. Retorna uma lista ordenada pelo valor de mercado atual da posição para destacar o maior risco potencial."

eu. É isso que o LLM lê para decidir se essa ferramenta é a adequada para o trabalho.

• Rótulos: retrieval e risk-analysis

Etiquetas são usadas para ajudar a agrupar várias ferramentas.

• Configuração: Cole a consulta ES|QL completa da Etapa 1.

eu. Esta é a pesquisa que o agente usará.

3. Clique em Inferir parâmetros da consulta. A interface do usuário encontrará automaticamente ?time_duration e listará abaixo. Adicione uma descrição simples para cada um, para ajudar o agente (e outros usuários) a entender sua finalidade.

• time_durationO período de tempo para pesquisar notícias negativas. O formato é "X horas", com o valor padrão de 8760 horas.

4. Teste!

• Clique em Salvar e testar.

• Você verá um novo menu suspenso onde poderá testar a consulta para garantir que ela esteja funcionando conforme o esperado.

eu. Em time_duration insira o intervalo desejado; aqui, estamos usando “8760 horas”.

• Clique em “Enviar” e, se tudo correr bem, você verá uma resposta em formato JSON. Para garantir que funcione como esperado, role para baixo e observe o objeto values . É aí que os documentos correspondentes são devolvidos.

5. Clique no “X” no canto superior direito para fechar a janela de teste. Sua nova ferramenta agora aparecerá na lista, pronta para ser atribuída a um agente.

O caminho da API

Para desenvolvedores que preferem automação ou precisam gerenciar ferramentas programaticamente, é possível obter o mesmo resultado com uma única chamada de API. Basta enviar uma solicitação POST para o endpoint /api/agent_builder/tools com a definição da ferramenta.

Etapa 3: O Cérebro — Criando seu Agente Personalizado

Criamos uma habilidade reutilizável (a Ferramenta). Agora, precisamos criar o Agente, a persona que de fato irá utilizá-lo. Um Agente é a combinação de um LLM (Licença de Aprendizagem Baseada em Leis), um conjunto específico de ferramentas às quais você lhe concede acesso e, mais importante, um conjunto de Instruções Personalizadas que atuam como sua constituição, definindo sua personalidade, regras e propósito.

A Arte do Prompt

O aspecto mais importante na criação de um agente confiável e especializado é o prompt. Um conjunto de instruções bem elaborado é o que diferencia um chatbot genérico de um assistente profissional e focado. É aqui que você define as diretrizes, define a saída e atribui ao agente sua missão.

Para o nosso agente Financial Manager , usaremos o seguinte prompt.

Vamos analisar por que essa estratégia é tão eficaz:

• Define uma persona sofisticada: a primeira frase estabelece imediatamente o agente como um "Assistente de Inteligência de Dados especializado", definindo um tom profissional e competente.

• Isso fornece uma estrutura de raciocínio: ao dizer ao agente para "Compreender, Planejar, Executar e Sintetizar", estamos lhe dando um procedimento operacional padrão. Isso melhora sua capacidade de lidar com questões complexas e de várias etapas.

• Isso promove o diálogo interativo: a instrução para "fazer perguntas esclarecedoras" torna o agente mais robusto. Isso minimizará suposições incorretas sobre solicitações ambíguas, levando a respostas mais precisas.

O Caminho da Interface do Usuário

1. Navegue até Agentes.

• Clique em Ferramentas ou Gerenciar Ferramentas e clique no botão Nova ferramenta .

2. Preencha os dados básicos:

• ID do agente: financial_assistant.

• Instruções: Copie o enunciado acima.

• Rótulos: Finance.

• Nome de exibição: Financial Assistant.

• Descrição da exibição: An assistant for analyzing and understanding your financial data.

3. De volta ao topo, clique em Ferramentas.

• Marque a caixa ao lado da nossa ferramenta find_client_exposure_to_negative_news .

4. Clique em Salvar.

O caminho da API

Você pode criar o mesmo agente com uma solicitação POST para o endpoint /api/agent_builder/agents . O corpo da solicitação contém todas as mesmas informações: o ID, o nome, a descrição, o conjunto completo de instruções e uma lista das ferramentas que o agente tem permissão para usar.

Passo 4: A Recompensa — Ter uma Conversa

Temos nossa lógica de negócios encapsulada em uma ferramenta e um "cérebro" pronto para usá-la em nosso Agente. Chegou a hora de ver tudo se concretizar. Agora podemos começar a interagir com nossos dados usando um agente especializado.

O Caminho da Interface do Usuário

1. Navegue até Agentes no Kibana.

2. Utilizando o menu suspenso no canto inferior direito da janela de chat, alterne do agente padrão Elastic AI para o nosso novo agente Assistente Financeiro .

3. Faça uma pergunta que permita ao agente usar nossa ferramenta especializada:

   1. Estou preocupado com o sentimento do mercado. Você pode me mostrar quais dos nossos clientes correm maior risco em caso de más notícias?

Após alguns instantes, o agente retornará uma resposta completa e perfeitamente formatada. Devido à natureza dos LLMs, sua resposta pode ser formatada de maneira ligeiramente diferente, mas nesta execução, o agente retornou:

O que acabou de acontecer? O Raciocínio do Agente

O agente não apenas "sabia" a resposta. Executou um plano de várias etapas centrado na seleção da melhor ferramenta para o trabalho. Eis uma análise do seu processo de pensamento:

• Intenção identificada: Correspondeu a palavras-chave da sua pergunta, como "risco" e "notícias negativas", à descrição da ferramenta find_client_exposure_to_negative_news .

• Plano executado: o sistema extraiu o período de tempo da sua solicitação e fez uma única chamada para essa ferramenta especializada.

• Delegou o trabalho: a ferramenta então realizou todo o trabalho pesado: as junções encadeadas, os cálculos de valor e a classificação.

• Resultado Sintetizado: Por fim, o agente formatou os dados brutos da ferramenta em um resumo claro e legível para humanos, seguindo as regras do prompt.

E não precisamos apenas supor, se ampliarmos nosso pensamento e observarmos mais detalhes.

O caminho da API

Você pode iniciar essa mesma conversa programaticamente. Basta enviar a pergunta de entrada para o endpoint da API converse , certificando-se de especificar o agent_id do nosso financial_manager.

Para desenvolvedores: Integração com a API

Embora a interface do Kibana ofereça uma experiência fantástica e intuitiva para criar e gerenciar seus agentes, tudo o que você viu hoje também pode ser feito programaticamente. O Agent Builder é baseado em um conjunto de APIs, permitindo que você integre essa funcionalidade diretamente em seus próprios aplicativos, pipelines de CI/CD ou scripts de automação.

Os três principais endpoints com os quais você trabalhará são:

• /api/agent_builder/toolsO ponto de extremidade para criar, listar e gerenciar as habilidades reutilizáveis que seus agentes podem usar.

• /api/agent_builder/agentsO ponto final para definir as personas dos seus agentes, incluindo as importantíssimas instruções e atribuições de ferramentas.

• /api/agent_builder/converse: O ponto de acesso para interagir com seus agentes, iniciar conversas e obter respostas.

Para um passo a passo completo e prático de como usar essas APIs para executar cada etapa deste tutorial, confira o Jupyter Notebook que acompanha o tutorial, disponível aqui em nosso repositório do GitHub.

Conclusão: Sua vez de construir

Começamos por pegar numa consulta ES|QL e transformá-la numa habilidade reutilizável. Em seguida, criamos um agente de IA especializado, atribuindo-lhe uma missão e regras claras, e capacitando-o com essa habilidade. O resultado é um assistente sofisticado que consegue entender uma pergunta complexa e executar uma análise em várias etapas para fornecer uma resposta precisa e baseada em dados.

Esse fluxo de trabalho é fundamental para o novo Construtor de Agentes da Elastic. Ele foi projetado para ser simples o suficiente para que usuários sem conhecimento técnico possam criar agentes por meio da interface do usuário, mas também sofisticado o bastante para que desenvolvedores criem aplicativos personalizados com inteligência artificial utilizando nossas APIs. Mais importante ainda, permite que você conecte LLMs aos seus próprios dados de forma segura e protegida, regida pela lógica especializada que você define, e converse com seus dados.

Pronto para usar agentes para conversar com seus dados?

A melhor maneira de consolidar o que você aprendeu é colocar a mão na massa. Experimente tudo o que discutimos hoje em nossa oficina prática, gratuita e interativa. Você passará por todo esse processo e muito mais em um ambiente sandbox dedicado.

Em um post futuro do blog, mostraremos como usar um aplicativo independente que interage com nosso agente Financial Assistant e exploraremos o Protocolo de Contexto de Modelo (MCP) que torna tudo isso possível. E em um post separado, discutiremos o suporte do Agent Builder ao protocolo Agent2Agent, ou A2A, ainda em desenvolvimento.

Fiquem ligados e boas construções!

Construtor de Agentes: Uma Base para a Criação de Agentes de IA Orientados por Dados

A promessa de um agente de IA é simples: dê a ele um objetivo e ele realizará a tarefa. Mas para os desenvolvedores, a realidade é uma série de desafios complexos. Em primeiro lugar, um agente é tão bom quanto a sua percepção do ambiente e das ferramentas que lhe são fornecidas para atingir os objetivos do usuário. Além disso, fornecer o contexto correto em meio a um mar de dados empresariais diversos é um desafio enorme. Finalmente, tudo isso precisa ser orquestrado por um circuito de raciocínio confiável que possa planejar, executar e aprender.

Para resolver isso, os desenvolvedores precisam construir uma estrutura complexa e frágil do zero. A arquitetura de agentes atual exige a integração de várias peças distintas: um LLM (Modelo de Aprendizado de Liderança), um banco de dados vetorial, um repositório de metadados, sistemas separados para registro e rastreamento, e alguma forma de avaliar se tudo está funcionando corretamente. Isso não é apenas complexo; é caro, propenso a erros e dificulta a criação de sistemas de IA confiáveis e de alta qualidade que seus usuários exigem.

Por isso, queremos simplificar. Para isso, nossa abordagem consiste em pegar os elementos essenciais de um agente orientado ao contexto eficaz e integrá-los diretamente ao núcleo do Elasticsearch com um novo conjunto de recursos chamado Elastic AI Agent Builder. Essa nova camada fornece uma estrutura com todos os componentes essenciais para a criação de agentes de IA baseados no Elasticsearch: um conjunto aberto de primitivas, protocolos baseados em padrões e acesso seguro aos dados — para que você possa criar sistemas de agentes adaptados a dados e requisitos do mundo real:

Proporcionar experiências com IA: esse é o objetivo final. Com nossa Plataforma de IA de Busca e seus dados como base, você pode criar qualquer tipo de aplicativo de IA generativa: desde interfaces de bate-papo personalizadas até integrações com frameworks de agentes como o LangChain ou aplicativos de negócios como o Salesforce.

Com tecnologia Agents & Tools: sobre a plataforma, expomos uma camada de abstrações limpa e simples. Você interage diretamente com agentes e ferramentas, que podem ser personalizadas para atender às suas necessidades específicas. Você também pode acessar os recursos da plataforma por meio de APIs robustas e padrões abertos como MCP e A2A.

Habilitado pela Plataforma de IA de Busca: este é o mecanismo principal onde integramos os componentes. O banco de dados vetorial avançado, a lógica do agente, a construção de consultas, os recursos de segurança e o rastreamento para avaliação, tudo reside aqui, gerenciado e otimizado pela Elastic.

Desvendando o poder dos seus dados: a base de qualquer agente de sucesso são dados de alta qualidade. Nossa plataforma começa com a capacidade de ingerir ou federar o acesso a todos os dados da sua empresa.

Construção de Agentes na Plataforma

O Agent Builder, integrado à Plataforma de IA de Busca, fornece uma estrutura completa para o desenvolvimento de agentes. É construído sobre cinco pilares fundamentais, cada um projetado para abordar um aspecto crítico da construção e implantação de sistemas de IA de nível de produção. Vamos analisar como os agentes definem o objetivo, as ferramentas fornecem as capacidades, os padrões abertos garantem a interoperabilidade, a avaliação proporciona transparência e a segurança garante a confiança.

Agentes

Os agentes são o bloco de construção de nível mais alto nesta nova camada do Elasticsearch. Um agente define o objetivo a ser alcançado, o conjunto de ferramentas disponíveis para execução e as fontes de dados sobre as quais pode operar. Os agentes não se limitam a interações conversacionais; eles podem viabilizar fluxos de trabalho completos, automação de tarefas ou experiências voltadas para o usuário.

Quando uma consulta é direcionada a um agente, ela segue um ciclo estruturado:

1. Interprete sua contribuição e objetivo.

2. Selecione a ferramenta e os argumentos corretos para a execução.

3. Analise a resposta da ferramenta.

4. Decida se deseja retornar um resultado ou continuar com outras invocações da ferramenta.

A Elastic cuida da orquestração, do contexto e da execução desse ciclo. Os desenvolvedores se concentram em definir o que o agente deve fazer: objetivos, ferramentas e dados, enquanto o sistema gerencia como o raciocínio e os fluxos de trabalho são executados.

O Agente Padrão

Nosso primeiro agente desenvolvido nesta plataforma é um agente conversacional nativo do Kibana, que permite interagir imediatamente com seus dados. Proporciona uma experiência pronta a usar, mantendo-se totalmente extensível e permitindo que você comece a interagir com seus dados imediatamente, sem necessidade de configuração adicional.

Você pode interagir com essa experiência diretamente no Kibana por meio de uma nova experiência de chat ou via API.

Consultar o agente padrão por meio da API requer apenas uma única chamada:

Como as conversas mantêm estado, você pode continuar interagindo com um agente usando um `conversation_id` ou recuperar o histórico completo da conversa:

Agentes alfandegários

Os desenvolvedores também podem criar seus próprios agentes personalizados por meio de APIs simples. Os agentes encapsulam instruções, ferramentas e acesso a dados, criando mecanismos de raciocínio personalizados.

Criar um agente personalizado é tão simples quanto fazer uma única chamada à API. O exemplo abaixo ilustra isso. O campo "configuração" contém todos os detalhes importantes, como instruções ou ferramentas disponíveis:

Uma vez criado, o agente pode ser consultado diretamente:

Essa abordagem transforma o agente, de um sistema complexo a ser construído do zero, em uma unidade simples e declarativa de lógica de negócios, permitindo que você implemente automação inteligente mais rapidamente.

Para uma análise aprofundada sobre como construir um agente especializado do zero, consulte nosso guia detalhado, passo a passo: Seu primeiro agente elástico: de uma única consulta a um bate-papo com inteligência artificial.

Ferramentas

Se os agentes definem o que realizar, as ferramentas definem como.

As ferramentas expõem funcionalidades específicas do Elastic Core para que os agentes executem e recuperem informações ou realizem uma ação. As ferramentas podem incluir funcionalidades básicas como obter índices ou obter mapeamentos, ou funcionalidades mais avançadas como conversão de linguagem natural para ES|QL.

O Elasticsearch é fornecido com um conjunto de ferramentas padrão otimizadas para necessidades comuns. Mas a verdadeira flexibilidade vem de criar a sua própria. Ao definir as ferramentas, você decide exatamente quais consultas, índices e campos são expostos a um agente com ES|QL, proporcionando controle preciso sobre velocidade, exatidão e segurança.

O registro de uma nova ferramenta também é tão simples quanto uma única chamada de API. Você poderia criar uma ferramenta que utilizasse nossa linguagem ES|QL (Elasticsearch Query Language) para encontrar notícias sobre um ativo financeiro específico:

Após o registro, você pode atribuir a nova ferramenta aos seus agentes personalizados, oferecendo a eles um conjunto selecionado de habilidades para analisar e utilizar sempre que for adequado.

Oferecemos uma plataforma para criar ferramentas personalizadas para suas necessidades específicas, por exemplo, com ES|QL, que transforma o agente de um agente de propósito geral em um especialista em um domínio específico, fundamentado em seus dados e domínio de negócios exclusivos.

Padrões Abertos e Interoperabilidade

Os agentes e ferramentas do Elasticsearch são expostos por meio de APIs de padrão aberto, o que facilita sua integração como blocos fundamentais dentro do ecossistema mais amplo de frameworks de agentes. Nossa abordagem é simples: sem caixas pretas. Queremos que você possa aproveitar o principal ponto forte da Elastic em buscas e combiná-lo com recursos complementares e outros sistemas de agentes.

Para tornar isso possível, estamos disponibilizando nossas capacidades por meio de APIs, protocolos emergentes e padrões abertos.

Protocolo de Contexto do Modelo (MCP)

O Protocolo de Contexto de Modelo (MCP) está rapidamente se tornando o padrão aberto para conectar ferramentas em diferentes sistemas. Ao oferecer suporte ao MCP, o Elasticsearch pode conectar a IA conversacional aos seus bancos de dados, índices e APIs externas. Com um servidor MCP remoto integrado ao Elastic Stack, qualquer cliente compatível com MCP pode acessar as ferramentas da Elastic e usá-las como blocos de construção em seus fluxos de trabalho de agentes mais amplos.

Esta não é uma via de mão única. Você também poderá importar ferramentas de servidores MCP externos e disponibilizá-las dentro do Elasticsearch. Em breve, os servidores MCP provavelmente estarão disponíveis para quase tudo e serão muito mais abrangentes do que qualquer coisa que pudéssemos criar por conta própria. A Elastic oferece busca e recuperação em grande escala, e você pode combinar isso com recursos especializados de outras plataformas para criar agentes eficazes.

Agente para Agente (A2A)

Também estamos trabalhando no suporte de agente para agente (A2A). Enquanto o MCP se concentra em conectar ferramentas, o A2A se concentra em conectar agentes. Com um servidor A2A, os agentes Elastic que você criar poderão se comunicar diretamente com agentes de outros sistemas: compartilhando contexto, delegando tarefas e coordenando fluxos de trabalho.

Pense nisso como interoperabilidade na camada de raciocínio. Seu agente Elastic pode lidar com a busca e recuperação de dados, depois repassar a tarefa para um agente de suporte ou de TI especializado e obter o resultado de volta sem problemas. O resultado é um ecossistema de agentes cooperativos, cada um fazendo o que faz de melhor.

Em última análise, a adoção do MCP e do A2A reforça nosso compromisso com o papel do Elasticsearch como um elemento de primeira classe, garantindo a integração aberta em todo o ecossistema de agentes.

Rastreamento e Avaliação

À medida que a busca se integra aos agentes, o desafio da avaliação eficaz torna-se crucial. Para implantar agentes com segurança em ambientes empresariais reais, você precisa ter a garantia de que eles não sejam apenas precisos, mas também eficientes e confiáveis. Como você mede o desempenho, diagnostica uma resposta inadequada ou melhora o nível inicial? Tudo começa com a visibilidade.

É por isso que projetamos nossas APIs de agentes com foco na transparência desde o início. Considere esta interação simples entre agentes:

A resposta inclui não apenas a resposta final, mas também o rastreamento completo da execução, detalhando quais ferramentas o agente selecionou, os parâmetros que utilizou e os resultados de cada etapa.

O rastreamento e o registro abrangentes são essenciais para um ciclo de melhoria contínua e, em breve, você poderá armazenar e visualizar esses rastreamentos de agentes diretamente no Elasticsearch. Melhor ainda, esses rastreamentos são baseados no protocolo OpenTelemetry, garantindo que sejam padronizados e portáteis para integração com a plataforma de observabilidade de sua escolha.

Esse nível de detalhamento é a base para um verdadeiro ciclo de melhoria contínua. Ele permite que você crie um conjunto abrangente de testes, depure falhas, identifique modos de falha para evitar regressões e capture padrões de sucesso para otimizar o desempenho. Em última análise, essa abordagem orientada por dados é a chave para transformar um protótipo promissor em um sistema de IA confiável e pronto para produção.

Segurança

À medida que os agentes e as ferramentas se tornam mais capazes, a segurança deixa de ser opcional e passa a ser fundamental. Expor APIs, automatizar tarefas e fluxos de trabalho exige que os sistemas empresariais sejam confiáveis. Principalmente à medida que os agentes começam a automatizar mais fluxos de trabalho, a capacidade de protegê-los e garantir que atendam aos requisitos da empresa torna-se essencial.

Todas as funcionalidades acima herdam os controles já disponíveis no Elastic atualmente, incluindo o controle de acesso baseado em funções (RBAC) para chamadas de API e o gerenciamento de chaves de API. Também estamos estendendo os mesmos controles a novos protocolos como o MCP. Isso significa suporte para padrões como o OAuth, bem como a capacidade de integrar mecanismos de autenticação personalizados.

Nosso objetivo é oferecer a flexibilidade necessária para que você experimente agentes e ferramentas, mantendo o nível de segurança, conformidade e governança que sua organização exige.

O que vem a seguir

Não estamos apenas adicionando funcionalidades; estamos expandindo o Elasticsearch para engenharia de contexto agente. Planejamos desenvolver nosso trabalho daqui para frente com base nesses princípios:

1. Compromisso com o código aberto e os padrões

Nosso compromisso com o código aberto e os padrões abertos garante que essas funcionalidades permaneçam interoperáveis com estruturas de agentes externas. Você sempre poderá conectar, estender e compor agentes em todo o seu ecossistema, mantendo seus dados e fluxos de trabalho sob seu controle.

2. Valor do Contexto

O contexto é o maior trunfo de um agente de IA. Gerenciar o contexto enquanto os agentes realizam buscas e operações de fluxo de trabalho pode ser uma tarefa desafiadora. Estamos aproveitando os principais pontos fortes da Elastic para resolver a engenharia de contexto, garantindo que as informações mais relevantes estejam sempre disponíveis para o seu agente.

3. Foque em fluxos de dados agéticos

No futuro, os agentes serão uma fonte de dados cada vez maior, incluindo a saída dos agentes (documentos gerados, relatórios, visualizações) e o rastro de execução dos agentes (seu raciocínio, chamadas de ferramentas, memória/contexto). A Elastic é ideal para lidar com esse tipo de dados, e estamos trabalhando em pesquisas sobre como realizar análises, avaliações e melhorias automatizadas usando esses dados.

4. Segurança e proteção por design

Os agentes de IA introduzem um conjunto totalmente novo de desafios em termos de segurança e proteção. A Elastic sempre foi líder em soluções seguras e continuamos a incorporar proteções de nível empresarial, controles de acesso e princípios de "confiança zero".

5. Integrado à plataforma

Os recursos para criar agentes de IA estão integrados na plataforma Elasticsearch. Isso significa que funcionalidades de nível de plataforma, como rastreamento, avaliação, visualização e análise, são todas aplicáveis aos agentes. Deseja desenvolver painéis de controle com base nas execuções dos agentes? Isso já está integrado. Deseja avaliar o desempenho do agente de IA usando análise de sentimentos? A plataforma permite isso. Isso possibilita a criação de um ciclo de vida completo em torno de suas experiências com IA.

O objetivo da Elastic é fornecer interfaces para que você possa criar IA conversacional e fluxos de trabalho automatizados que sejam totalmente integrados, extensíveis e baseados em seus dados. Mais detalhes técnicos e informações sobre o progresso serão compartilhados em breve.

O Construtor de Agentes já está disponível em versão prévia privada. Entre em contato conosco para solicitar acesso. Tem perguntas ou comentários? Conecte-se com nossa comunidade de desenvolvedores em nosso espaço de trabalho no Slack ou em nosso fórum de discussão.

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

Passos:

1. Contexto e fluxo de trabalho do aplicativo

2. Preparar dados

3. Configuração LLM

4. Funções do aplicativo

Contexto e fluxo de trabalho do aplicativo

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

Experimentamos alguns modelos:

• Gemini 2.5 pro

• GPT o3 / o4-mini-high / 4.1

• Soneto 4 de Claude

• Grok 3

• Deepseek (Deepthink R1)

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

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

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

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

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

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

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

Pré-requisitos

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

1. Python 3.8 ou superior

2. Um ambiente Python Venv

3. Uma instância do Elasticsearch em execução, juntamente com seu endpoint e chave de API.

4. Uma chave de API da OpenAI armazenada na variável de ambiente com o nome OPENAI_API_KEY:

Preparar dados

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

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

Agora, vamos obter os mapeamentos do índice que acabamos de carregar, kibana_sample_data_logs:

Vamos passar os mapeamentos junto com a imagem que carregaremos posteriormente.

Configuração LLM

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

Instalamos as dependências:

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

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

Para a entrada de imagem, enviaremos um painel que acabei de desenhar:

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

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

Para converter a imagem para base64 e enviá-la como entrada, você pode usar um conversor online ou fazer isso por meio de código.

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

Vamos analisar a pergunta:

Seção

Razão

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

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

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

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

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

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

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

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

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

Processando a resposta do LLM

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

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

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

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

Em seguida, substituirá os valores do modelo e retornará a visualização JSON final.

Para simplificar, teremos coordenadas estáticas que atribuiremos aos painéis que o LLM decidir criar e produziremos um painel de controle em grade 2x2, como na imagem acima.

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

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

Para executar o script e gerar o painel de controle, execute o seguinte comando no console:

O resultado final será semelhante a este:

Conclusão

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

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

Neste artigo, exploraremos como construir um assistente RAG agente usando o Mastra e um aplicativo web JavaScript leve para interagir com ele. Ao conectar este agente ao Elasticsearch, damos a ele acesso a dados estruturados dos jogadores e a capacidade de executar agregações estatísticas em tempo real, para fornecer recomendações baseadas em estatísticas dos jogadores. Acesse o repositório do GitHub para acompanhar; o arquivo README fornece instruções sobre como clonar e executar o aplicativo por conta própria.

Eis como deverá ficar quando tudo estiver montado:

Nota: Este post do blog complementa o artigo “Criando agentes de IA com o SDK de IA e o Elastic”. Se você é iniciante no estudo de agentes de IA em geral e em suas possíveis aplicações, comece por aí.

Visão geral da arquitetura

No núcleo do sistema está um modelo de linguagem abrangente (LLM, na sigla em inglês), que atua como o motor de raciocínio do agente (o cérebro). Ele interpreta a entrada do usuário, decide quais ferramentas utilizar e orquestra as etapas necessárias para gerar uma resposta relevante.

O próprio agente é estruturado pelo Mastra, um framework de agentes no ecossistema JavaScript. O Mastra integra o LLM com infraestrutura de backend, expõe-no como um endpoint de API e fornece uma interface para definir ferramentas, prompts do sistema e comportamento do agente.

Na interface, usamos o Vite para criar rapidamente um aplicativo web React que fornece uma interface de chat para enviar perguntas ao agente e receber suas respostas.

Por fim, temos o Elasticsearch, que armazena estatísticas de jogadores e dados de confrontos que o agente pode consultar e agregar.

Histórico

Vamos revisar alguns conceitos fundamentais:

O que é RAG agentivo?

Os agentes de IA podem interagir com outros sistemas, operar de forma independente e executar ações com base em parâmetros definidos por eles. O Agentic RAG combina a autonomia de um agente de IA com os princípios da geração aumentada por recuperação, permitindo que um LLM escolha quais ferramentas utilizar e quais dados usar como contexto para gerar uma resposta. Leia mais sobre a RAG aqui.

Ao escolher uma estrutura, por que ir além do AI-SDK?

Existem muitas estruturas de agentes de IA disponíveis e você provavelmente já ouviu falar das mais populares, como CrewAI, AutoGen e LangGraph. A maioria dessas estruturas compartilha um conjunto comum de funcionalidades, incluindo suporte para diferentes modelos, uso de ferramentas e gerenciamento de memória.

Segue abaixo uma tabela comparativa de frameworks elaborada por Harrison Chase (CEO da LangChain).

O que despertou meu interesse no Mastra foi o fato de ser um framework que prioriza o JavaScript, criado para que desenvolvedores full-stack possam integrar agentes facilmente em seu ecossistema. O SDK de IA da Vercel também faz a maior parte disso, mas o grande diferencial do Mastra é quando seus projetos incluem fluxos de trabalho de agentes mais complexos. O Mastra aprimora os padrões básicos definidos pelo AI-SDK e, neste projeto, usaremos os dois em conjunto.

Considerações sobre estruturas e escolha de modelos

Embora essas estruturas possam ajudá-lo a criar agentes de IA rapidamente, existem algumas desvantagens a serem consideradas. Por exemplo, ao usar qualquer outra estrutura fora dos agentes de IA ou de qualquer camada de abstração em geral, você perde um pouco do controle. Se o LLM não usar as ferramentas corretamente ou fizer algo que você não deseja, a abstração dificulta a depuração. Ainda assim, na minha opinião, essa troca vale a pena pela facilidade e rapidez que se obtém ao construir, especialmente porque essas estruturas estão ganhando força e sendo constantemente aprimoradas.

Novamente, essas estruturas são agnósticas em relação ao modelo, o que significa que você pode usar diferentes modelos sem problemas. Lembre-se de que os modelos variam nos conjuntos de dados em que foram treinados e, consequentemente, variam nas respostas que fornecem. Alguns modelos sequer suportam a chamada de ferramentas. Portanto, é possível alternar e testar diferentes modelos para ver qual oferece as melhores respostas, mas lembre-se de que provavelmente você terá que reescrever o prompt do sistema para cada um deles. Por exemplo, usando Llama3.3 Em comparação com o GPT-40, é necessário muito mais estímulo e instruções específicas para obter a resposta desejada.

Basquete de fantasia da NBA

O basquete de fantasia envolve a criação de uma liga com um grupo de amigos (atenção: dependendo do nível de competitividade do grupo, isso pode afetar o status das suas amizades), geralmente com algum dinheiro em jogo. Cada um de vocês monta uma equipe de 10 jogadores para competir contra a equipe de 10 jogadores de um amigo, alternando semanalmente. Os pontos que contribuem para a sua pontuação geral são definidos pelo desempenho de cada um dos seus jogadores contra os adversários em uma determinada semana.

Se um jogador da sua equipe se lesionar, for suspenso, etc., existe uma lista de jogadores disponíveis no mercado para adicionar à sua equipe. É aqui que entra em jogo grande parte da estratégia complexa nos esportes de fantasia, porque você tem um número limitado de jogadores para escolher e todos estão constantemente em busca do melhor jogador.

É aqui que nosso assistente de IA da NBA brilhará, especialmente em situações em que você precisa decidir rapidamente qual jogador escolher. Em vez de ter que pesquisar manualmente o desempenho de um jogador contra um adversário específico, o assistente pode encontrar esses dados rapidamente e comparar as médias para fornecer uma recomendação precisa.

Agora que você já conhece alguns conceitos básicos sobre RAG agentivo e basquete fantasy da NBA, vamos ver como funciona na prática.

Construindo o projeto

Se você ficar preso em algum ponto ou não quiser construir tudo do zero, consulte o repositório.

O que abordaremos

1. Estruturando o projeto:

   1. Backend (Mastra): Use o comando `npx create mastra@latest` para criar a estrutura do backend e definir a lógica do agente.

   2. Frontend (Vite + React): Use o comando `npm create vite@latest` para criar a interface de chat do frontend para interação com o agente.

2. Configurando variáveis de ambiente

   1. Instale o dotenv para gerenciar variáveis de ambiente.

   2. Crie um arquivo .env arquive e forneça as variáveis necessárias.

3. Configurando o Elasticsearch

   1. Crie um cluster Elasticsearch (localmente ou na nuvem).

   2. Instale o cliente oficial do Elasticsearch.

   3. Garanta que as variáveis de ambiente estejam acessíveis.

   4. Estabelecer conexão com o cliente.

4. Ingestão em massa de dados da NBA no Elasticsearch

   1. Crie um índice com os mapeamentos apropriados para habilitar agregações.

   2. Importar em massa estatísticas de jogo de jogadores de um arquivo CSV para um índice do Elasticsearch.

5. Definir agregações do Elasticsearch

   1. Consulta para calcular as médias históricas contra um adversário específico.

   2. Consulta para calcular as médias da temporada contra um adversário específico.

6. Arquivo utilitário de comparação de jogadores

   1. Consolida funções auxiliares e agregações do Elasticsearch.

7. Construindo o agente

   1. Adicione a definição do agente e o prompt do sistema.

   2. Instale o Zod e defina as ferramentas.

   3. Adicionar configuração de middleware para lidar com CORS.

8. Integrando o frontend

   1. Utilizando o useChat do AI-SDK para interagir com o agente.

   2. Crie a interface do usuário para manter conversas formatadas adequadamente.

9. Executando o aplicativo

   1. Inicie tanto o backend (servidor Mastra) quanto o frontend (aplicativo React).

   2. Exemplos de consultas e uso.

10. O que vem a seguir: tornar o agente mais inteligente.

    1. Adicionando recursos de busca semântica para possibilitar recomendações mais relevantes.

    2. Habilite consultas dinâmicas movendo a lógica de busca para o servidor Elasticsearch MCP (Model Context Protocol).

Pré-requisitos

• Node.js e npm: Tanto o backend quanto o frontend são executados em Node. Certifique-se de ter o Node 18+ e o npm v9+ instalados (que já vêm incluídos no Node 18+).

• Cluster Elasticsearch: Um cluster Elasticsearch ativo, seja localmente ou na nuvem.

• Chave da API da OpenAI: Gere uma na página de chaves da API no portal de desenvolvedores da OpenAI.

Estrutura do projeto

Etapa 1: Estruturando o projeto

1. Primeiro, crie o diretório nba-ai-assistant-js e navegue até ele usando:

Backend:

1. Utilize a ferramenta de criação do Mastra com o comando:

2. Você deverá receber algumas mensagens no seu terminal. Para a primeira, vamos nomear o backend do projeto:

3. Em seguida, manteremos a estrutura padrão para armazenar os arquivos Mastra, então insira src/.

4. Em seguida, escolheremos a OpenAI como nosso provedor padrão de LLM.

5. Por fim, será solicitada a sua chave de API da OpenAI. Por agora, vamos escolher a opção de ignorar e fornecer isso mais tarde em um arquivo .env .

Front-end:

1. Volte ao diretório raiz e execute a ferramenta de criação do Vite usando este comando: npm create vite@latest frontend -- --template react

Isso deverá criar um aplicativo React leve chamado frontend com um modelo específico para React.

Se tudo correr bem, dentro do diretório do seu projeto, você deverá ver um diretório backend que contém o código Mastra e um diretório frontend com seu aplicativo React.

Etapa 2: Configurando as variáveis de ambiente

1. Para gerenciar chaves sensíveis, usaremos o pacote dotenv para carregar nossas variáveis de ambiente do arquivo .env. arquivo. Navegue até o diretório backend e instale dotenv:

2. No diretório backend, um arquivo example.env é fornecido com as variáveis apropriadas para preenchimento. Se você criar o seu próprio, certifique-se de incluir as seguintes variáveis:

Nota: Certifique-se de que este arquivo seja excluído do seu controle de versão adicionando .env a .gitignore.

Etapa 3: Configurando o Elasticsearch

Primeiro, você precisa de um cluster Elasticsearch ativo. Existem duas opções:

• Opção A: Usar o Elasticsearch Cloud

  • Inscreva-se no Elastic Cloud.

  • Criar uma nova implantação

  • Obtenha o URL do seu endpoint e a chave da API (codificada).

• Opção B: Executar o Elasticsearch localmente

  • Instale e execute o Elasticsearch localmente.

  • Use http://localhost:9200 como seu endpoint.

  • Gere uma chave de API

Instalando o cliente Elasticsearch no servidor:

1. Primeiro, instale o cliente oficial do Elasticsearch no diretório do seu backend:

2. Em seguida, crie um diretório chamado lib para armazenar funções reutilizáveis e navegue até ele:

3. Dentro da pasta, crie um novo arquivo chamado elasticClient.js. Este arquivo inicializará o cliente Elasticsearch e o disponibilizará para uso em todo o seu projeto.

4. Como estamos usando módulos ECMAScript (ESM), os nomes de arquivo __dirname and __não estão disponíveis. Para garantir que suas variáveis de ambiente sejam carregadas corretamente a partir do arquivo .env No arquivo localizado na pasta backend, adicione esta configuração ao início do seu arquivo:

5. Agora, inicialize o cliente Elasticsearch usando suas variáveis de ambiente e verifique a conexão:

Agora, podemos importar essa instância de cliente para qualquer arquivo que precise interagir com o seu cluster Elasticsearch.

Etapa 4: Ingestão em massa de dados da NBA no Elasticsearch

Conjunto de dados:

Para este projeto, utilizaremos como referência os conjuntos de dados disponíveis no diretório backend/data do repositório. Nosso assistente da NBA usará esses dados como base de conhecimento para realizar comparações estatísticas e gerar recomendações.

• sample_player_game_stats.csv - Estatísticas de jogo de jogadores (por exemplo, pontos, rebotes, roubos de bola, etc., por jogo, por jogador, ao longo de toda a sua carreira na NBA). Usaremos esse conjunto de dados para realizar agregações. (Observação: estes são dados fictícios, pré-gerados para fins de demonstração e não provenientes de fontes oficiais da NBA.)

• playerAndTeamInfo.js - Substitui os metadados de jogadores e equipes que normalmente seriam fornecidos por uma chamada de API, permitindo que o agente associe nomes de jogadores e equipes a IDs. Como estamos usando dados de exemplo, não queremos a sobrecarga de buscar dados em uma API externa, então definimos alguns valores fixos que o agente pode referenciar.

Implementação:

1. No diretório backend/lib , crie um arquivo chamado playerDataIngestion.js.

2. Configure as importações, resolva o caminho do arquivo CSV e configure a análise sintática. Novamente, como estamos usando ESM, precisamos reconstruir __dirname para resolver o caminho para o CSV de amostra. Além disso, importaremos o Node.js. módulos integrados, fs e readline, para analisar o arquivo CSV fornecido linha por linha.

Isso prepara você para ler e analisar o CSV de forma eficiente quando chegarmos à etapa de ingestão em massa.

3. Crie um índice com o mapeamento apropriado. Embora o Elasticsearch possa inferir automaticamente os tipos de campo com mapeamento dinâmico, queremos ser explícitos aqui para que cada estatística seja tratada como um campo numérico. Isso é importante porque usaremos esses campos para agregações mais tarde. Também queremos usar o tipo float para estatísticas como pontos, rebotes, etc., para garantir que incluamos valores decimais. Finalmente, queremos adicionar a propriedade de mapeamento dynamic: 'strict' para que o Elasticsearch não mapeie dinamicamente campos não reconhecidos. 

4. Adicione a função para ingerir em massa os dados CSV no seu índice Elasticsearch. Dentro do bloco de código, omitimos a linha de cabeçalho. Em seguida, separe cada item da linha por vírgula e insira-os no objeto do documento. Esta etapa também os limpa e garante que sejam do tipo correto. Em seguida, inserimos os documentos na matriz bulkBody juntamente com as informações do índice, que servirão como carga útil para a ingestão em massa no Elasticsearch.

5. Então, podemos usar a API Bulk do Elasticsearch com elasticClient.bulk() para ingerir vários documentos em uma única solicitação. O tratamento de erros abaixo está estruturado para fornecer uma contagem de quantos documentos não foram ingeridos e quantos foram ingeridos com sucesso.

6. Execute a função main() abaixo para executar sequencialmente as funções createIndex() e bulkIngestCsv() .

Se você vir um registro no console indicando que a ingestão em massa foi bem-sucedida, faça uma verificação rápida no seu índice do Elasticsearch para confirmar se os documentos foram realmente ingeridos com sucesso.

Etapa 5: Definindo e consolidando as agregações do Elasticsearch

Essas serão as principais funções que serão utilizadas quando definirmos as ferramentas para o Agente de IA, a fim de comparar as estatísticas dos jogadores entre si.

1. Navegue até o diretório backend/lib e crie um arquivo chamado elasticAggs.js.

2. Adicione a consulta abaixo para calcular as médias históricas de um jogador contra um adversário específico. Esta consulta usa um filtro bool com 2 condições: uma que corresponde player_id e outra que corresponde a opponent_team_id, para recuperar apenas os jogos relevantes. Não precisamos retornar nenhum documento, só nos interessam as agregações, então definimos size:0. No bloco aggs , executamos várias agregações de métricas em paralelo em campos como points, rebounds, assists, steals, blocks e fg_percentage para calcular seus valores médios. Os cálculos dos LLMs podem ser inconsistentes, e essa solução transfere esse processo para o Elasticsearch, garantindo que nosso assistente de IA da NBA tenha acesso a dados precisos.

3. Para calcular as médias da temporada de um jogador contra um adversário específico, usaremos praticamente a mesma consulta que a consulta histórica. A única diferença nesta consulta é que o filtro bool tem uma condição adicional para game_date. O campo game_date tem que estar dentro do intervalo da temporada atual da NBA. Neste caso, o intervalo está entre 2024-10-01 e 2025-06-30. Essa condição adicional abaixo garante que as agregações subsequentes isolarão apenas os jogos desta temporada.

Etapa 6: Ferramenta de comparação de jogadores

Para manter nosso código modular e de fácil manutenção, criaremos um arquivo utilitário que consolida funções auxiliares de metadados e agregações do Elasticsearch. Isso alimentará a principal ferramenta usada pelo agente. Mais sobre isso adiante:

1. Crie um novo arquivo comparePlayers.js no diretório backend/lib .

2. Adicione a função abaixo para consolidar os auxiliares de metadados e a lógica de agregação do Elasticsearch em uma única função que alimenta a ferramenta principal usada pelo agente.

Etapa 7: Construindo o agente

Agora que você criou a estrutura básica do frontend e do backend, importou os dados dos jogos da NBA e estabeleceu uma conexão com o Elasticsearch, podemos começar a juntar todas as peças para construir o agente.

Definindo o agente

1. Navegue até o arquivo index.ts dentro do diretório backend/src/mastra/agents e adicione a definição do agente. Você pode especificar campos como:

• Nome: Dê ao seu agente um nome que será usado como referência quando ele for chamado na interface.

• Instruções/mensagem do sistema: Uma mensagem do sistema fornece ao LLM o contexto inicial e as regras a seguir durante a interação. É semelhante à mensagem que os usuários enviam pelo chat, mas esta é exibida antes de qualquer interação do usuário. Novamente, isso irá variar dependendo do modelo que você escolher.

• Modelo: Qual modelo de aprendizagem de linguagem (LLM) usar (o Mastra suporta modelos OpenAI, antrópicos, locais, etc.).

• Ferramentas: Uma lista de funções de ferramentas que o agente pode chamar.

• Memória: (Opcional) se quisermos que o agente se lembre do histórico da conversa, etc. Para simplificar, podemos começar sem memória persistente, embora o Mastra a suporte.

Ferramentas de definição

1. Navegue até o arquivo index.ts dentro do diretório backend/src/mastra/tools .

2. Instale o Zod usando o comando:

3. Adicionar definições de ferramentas. Observe que importamos a função dentro do arquivo comparePlayers.js como a função principal que o agente usará ao chamar esta ferramenta. Usando a função createTool() do Mastra, vamos registrar nosso playerComparisonTool. Os campos incluem:

• idEsta é uma descrição em linguagem natural para ajudar o agente a entender o que a ferramenta faz.

• input schemaPara definir o formato da entrada para a ferramenta, o Mastra utiliza o esquema Zod , que é uma biblioteca de validação de esquemas TypeScript. Zod ajuda garantindo que o agente insira dados estruturados corretamente e impede que a ferramenta seja executada caso a estrutura de entrada não corresponda.

• descriptionEsta é uma descrição em linguagem natural para ajudar o agente a entender quando ligar e usar a ferramenta.

• executeA lógica que é executada quando a ferramenta é chamada. No nosso caso, estamos usando uma função auxiliar importada para retornar estatísticas de desempenho.

Adicionando middleware para lidar com CORS

Adicione um middleware no servidor Mastra para lidar com CORS. Dizem que existem três coisas na vida que você não pode evitar: a morte, os impostos e, para desenvolvedores web, o CORS. Em resumo, o Compartilhamento de Recursos de Origem Cruzada (CORS) é um recurso de segurança do navegador que impede que o frontend faça solicitações a um backend executado em um domínio ou porta diferente. Embora executemos tanto o backend quanto o frontend em localhost, eles usam portas diferentes, acionando a política CORS. Precisamos adicionar o middleware especificado na documentação do Mastra para que nosso backend permita essas solicitações do frontend.

1. Navegue até o arquivo index.ts dentro do diretório backend/src/mastra e adicione a configuração para CORS:

• origin: ['http://localhost:5173']

  • Permite solicitações somente deste endereço (endereço padrão do Vite)

• allowMethods: ["GET", "POST"]

  • Métodos HTTP permitidos. Na maioria das vezes, será utilizado o método POST.

• allowHeaders: ["Content-Type", "Authorization", "x-mastra-client-type, "x-highlight-request", "traceparent"],

  • Essas configurações definem quais cabeçalhos personalizados podem ser usados nas solicitações.

Etapa 8: Integrando o frontend

Este componente React fornece uma interface de chat simples que se conecta ao agente de IA Mastra usando o gancho useChat() de @ai-sdk/react. Também usaremos esse recurso para exibir o uso de tokens, chamadas de ferramentas e para renderizar a conversa. No prompt do sistema acima, também pedimos ao agente para exibir a resposta em markdown, então usaremos react-markdown para formatar a resposta corretamente.

1. No diretório frontend, instale o pacote @ai-sdk/react para usar o gancho useChat().

2. Ainda no mesmo diretório, instale o React Markdown para que possamos formatar corretamente a resposta gerada pelo agente.

3. Implemente useChat(). Este gancho gerenciará a interação entre seu frontend e o backend do seu agente de IA. Ele gerencia o estado das mensagens, a entrada do usuário, o status e fornece ganchos de ciclo de vida para fins de observabilidade. As opções que passamos incluem:

• api: Isso define o ponto final do seu agente Mastra AI. A porta padrão é a 4111 e também queremos adicionar a rota que suporta respostas em fluxo contínuo.

• onToolCallEste comando é executado sempre que o agente chama uma ferramenta; estamos usando-o para rastrear quais ferramentas nosso agente está chamando.

• onFinishEsta ação é executada depois que o agente conclui uma resposta completa. Mesmo que tenhamos habilitado o streaming, onFinish ainda será executado após o recebimento da mensagem completa e não após cada parte. Aqui, estamos usando isso para rastrear o uso de nossos tokens. Isso pode ser útil para monitorar e otimizar os custos do LLM.

4. Finalmente, acesse o componente ChatUI.jsx no diretório frontend/components para criar a interface do usuário para manter nossa conversa. Em seguida, envolva a resposta em um componente ReactMarkdown para formatar corretamente a resposta do agente.

Etapa 9: Executando o aplicativo

Parabéns! Agora você está pronto para executar o aplicativo. Siga estes passos para iniciar tanto o backend quanto o frontend.

1. Em uma janela de terminal, partindo do diretório raiz, navegue até o diretório de backend e inicie o servidor Mastra:

2. Em outra janela do terminal, partindo do diretório raiz, navegue até o diretório frontend e inicie o aplicativo React:

3. Acesse seu navegador e navegue até:

http://localhost:5173

Você deverá conseguir visualizar a interface de bate-papo. Experimente estas sugestões:

• "Compare LeBron James e Stephen Curry"

• "Quem devo escolher entre Jayson Tatum e Luka Doncic?"

O que vem a seguir: tornar o agente mais inteligente.

Para tornar o assistente mais proativo e as recomendações mais relevantes, adicionarei algumas melhorias importantes na próxima versão.

Busca semântica para notícias da NBA

Existem inúmeros fatores que podem afetar o desempenho do jogador, muitos dos quais não aparecem nas estatísticas brutas. Informações como relatórios de lesões, alterações na escalação ou até mesmo análises pós-jogo só podem ser encontradas em artigos de notícias. Para capturar esse contexto adicional, adicionarei recursos de busca semântica para que o agente possa recuperar artigos relevantes da NBA e incorporar essa narrativa em suas recomendações.

Pesquisa dinâmica com o servidor Elasticsearch MCP

O MCP (Model Context Protocol) está rapidamente se tornando o padrão para a forma como os agentes se conectam às fontes de dados. Vou migrar a lógica de busca para o servidor Elasticsearch MCP, o que permite que o agente construa consultas dinamicamente em vez de depender de funções de busca predefinidas que fornecemos. Isso nos permite usar fluxos de trabalho em linguagem mais natural e reduz a necessidade de escrever manualmente cada consulta de pesquisa. Saiba mais sobre o servidor Elasticsearch MCP e o estado atual do ecossistema aqui.

Essas mudanças já estão em andamento, fique ligado!

Conclusão

Neste blog, criamos um assistente RAG interativo que fornece recomendações personalizadas para o seu time de basquete de fantasia usando JavaScript, Mastra e Elasticsearch. Nós abordamos os seguintes tópicos:

• Fundamentos do RAG agético e como a combinação da autonomia de um agente de IA com as ferramentas para usar o RAG de forma eficaz pode levar a agentes mais dinâmicos e com nuances.

• Elasticsearch e como seus recursos de armazenamento de dados e poderosas agregações nativas o tornam um excelente parceiro como base de conhecimento para um mestrado em Direito (LLM).

• O framework Mastra e como ele simplifica a criação desses agentes para desenvolvedores no ecossistema JavaScript.

Seja você um fanático por basquete, esteja explorando como construir agentes de IA, ou ambos como eu, espero que este blog tenha lhe dado algumas bases para começar. O repositório completo está disponível no GitHub. Sinta-se à vontade para cloná-lo e fazer alterações. Agora, vá ganhar essa liga de fantasia!

Esta postagem do blog aborda o uso do Elasticsearch e do Azure Open AI para criar um aplicativo de exemplo que demonstra como encontrar resultados exatos ao pesquisar por propriedades imobiliárias muito específicas, ao mesmo tempo em que fornece resultados relevantes quando uma correspondência específica não está disponível. Percorreremos todas as etapas necessárias para criar um índice do Elasticsearch junto com um modelo de pesquisa. Em seguida, descreveremos todo o processo de como criar um aplicativo que usa o Azure OpenAI para receber consultas de usuários e transformá-las em consultas de modelo de pesquisa do Elasticsearch que podem produzir resultados incrivelmente personalizados.

Aqui está uma lista de todos os recursos que usaremos para criar nosso aplicativo de exemplo de busca de imóveis:

• Índice e modelo de pesquisa do Elasticsearch

• Azure OpenAI

• API do Azure Maps

• Caderno Jupyter de espaços de código

• Kernel Semântico

• Aplicativo C# com frontend Blazor

Fluxo de trabalho de consulta inteligente

Este fluxo de trabalho combina LLM, ferramentas LLM e pesquisa para transformar consultas de linguagem natural em resultados de pesquisa estruturados e relevantes:

• LLM (Large Language Model) - Interpreta consultas complexas do usuário e orquestra ferramentas para extrair intenção de pesquisa e enriquecer o contexto.

• Ferramentas LLM - Cada ferramenta LLM é um programa em C# que criamos para este post. Existem três ferramentas:

  • Ferramenta de extração de parâmetros: extrai atributos-chave como quartos, banheiros, recursos e preço da consulta.

  • Ferramenta GeoCode: converte nomes de locais em latitude/longitude para filtragem espacial.

  • Ferramenta de pesquisa: preenche um modelo de pesquisa do Elasticsearch com parâmetros de consulta e executa uma pesquisa. Pesquisa híbrida - Executa pesquisa híbrida (texto completo + vetor denso) com inferência de ML integrada. Essa abordagem em camadas garante experiências de consulta mais inteligentes e sensíveis ao contexto para o usuário final.

Arquitetura de aplicação

Aqui está um diagrama de arquitetura do sistema do aplicativo de exemplo. Usaremos um Jupyter Notebook do Codespaces para interagir com o Elastic Cloud.

Pré-requisitos

Você só precisará do seu navegador, porque usaremos o GitHub Codespaces para clonar o aplicativo de exemplo, configurá-lo e executá-lo. Para a parte elástica da solução, usaremos o Elastic Cloud para criar um projeto Elasticsearch Serverless. Usaremos o Portal do Azure para trabalhar com recursos do Azure.

Clonar repositório de aplicativo de exemplo no Codespaces

Comece clonando o código do aplicativo de exemplo. Você pode fazer isso no GitHub Codespaces, que fornece uma maneira de clonar e executar aplicativos. Clique em Novo Codespace.

Em seguida, selecione o repositório jwilliams-elastic/msbuild-intelligent-query-demo no menu suspenso Repositório e clique em Criar Codespace.

Criar .env arquivo

Usaremos um Python Jupyter Notebook para acessar e interagir com o Elastic Cloud, e ele faz isso usando os valores de configuração armazenados em um arquivo de configuração. O arquivo de configuração do Notebook deve ter o nome de arquivo .env e você irá criá-lo agora.

1. No GitHub Codespaces, clique no botão Novo arquivo e adicione um arquivo chamado .env

2. Adicione o seguinte conteúdo ao .env recém-criado arquivo

Como você pode ver, temos alguns valores ausentes, ELASTIC_URL e ELASTIC_API_KEY, que precisam ser adicionados ao .env arquivo. Vamos fazer isso agora criando um projeto sem servidor Elasticsearch para servir como backend que alimentará a funcionalidade de pesquisa do nosso aplicativo de exemplo.

Criar um projeto Elastic Serverless

1. Acesse cloud.elastic.co e clique em Criar novo projeto sem servidor

2. Clique em Avançar para a solução Elasticsearch

3. Selecione Otimizado para Vetores

4. Defina o Provedor de Nuvem como Azure

5. Clique em Criar projeto sem servidor

6. Clique em Introdução no menu de navegação principal e role para baixo para copiar os Detalhes da Conexão

7. Clique no botão Copiar para copiar o Endpoint do Elasticsearch dos Detalhes da Conexão

8. Atualizar .env arquivo para definir o ELASTIC_URL como o Elasticsearch Endpointcopiado

Criar uma chave de API elástica

1. Abra a página Introdução ao Elasticsearch, clique em Novo na seção Adicionar uma chave de API

2. Digite um nomede chave

3. Clique em Criar chave de API

4. Clique no botão Copiar para copiar o valor da chave da API

5. De volta ao Codespaces, onde temos o .envarquivo aberto para edição, cole o valor copiado para definir a ELASTIC_API_KEY

Abra o Codespaces Notebook e instale as dependências da biblioteca

No explorador de arquivos, selecione o arquivo VectorDBSetup.ipynb para abrir o Notebook. Após o carregamento do Notebook, localize a seção Notebook intitulada Instalar bibliotecas. Clique no botão de reprodução da seção.

Se esta for a primeira vez que você executa um Notebook no GitHub Codespaces, você será solicitado a selecionar um Kernel do Codespaces e configurar o ambiente Python.

Defina importações e carregue variáveis de ambiente usando o Codespaces Notebook

Vá para a próxima seção no Notebook intitulada Definir importações e carregar variáveis de ambiente. Clique no botão de reprodução da seção.

Este código importa as bibliotecas Python usadas pelo Notebook e carrega as variáveis de ambiente do .env que você criou anteriormente.

Crie um ponto de extremidade de inferência do Elastic ML usando o Codespaces Notebook

Vá para a próxima seção do Notebook intitulada Criar ponto de extremidade de inferência de ML. Clique no botão de reprodução da seção.

Isso criará um novo ponto de extremidade de inferência de ML no projeto Elasticsearch que usaremos para gerar incorporações de texto a partir dos nossos dados. Incorporações de texto são representações vetoriais de texto que serão armazenadas no Elasticsearch para potencializar a pesquisa semântica.

Crie um índice Elasticsearch usando o Codespaces Notebook

Vá para a próxima seção do Notebook intitulada Criar índice do Elasticsearch. Clique no botão de reprodução da seção.

Isso criará o índice do Elasticsearch que armazenará nossos dados de exemplo e quaisquer dados vetoriais associados gerados por meio do ponto de extremidade de inferência de ML.

Crie um modelo de pesquisa Elasticsearch usando o Codespaces Notebook

Continue para a próxima seção do Notebook intitulada Modelo de Pesquisa. Clique no botão de reprodução da seção.

Isso cria um modelo de pesquisa, que é o que nosso aplicativo de exemplo usará como modelo preenchido com as palavras analisadas da consulta de pesquisa de um usuário. Isso nos permite configurar e controlar o quão específicos somos ao consultar dados no índice do Elasticsearch.

Ingerir dados no índice do Elasticsearch usando o Codespaces Notebook

Vá para a próxima seção do Notebook intitulada Ingerir dados de propriedade. Clique no botão de execução da seção.

A execução desta seção de código carregará em massa os dados de exemplo contidos no arquivo properties.jsonl . Após alguns minutos, você verá uma confirmação de que o processo foi concluído com sucesso. Você pode confirmar se o índice contém o registro esperado acessando a seção Gerenciamento de Índice no Elastic Cloud.

Crie appsetting.json para configurar o aplicativo C#

Com nosso índice do Elasticsearch criado e preenchido com dados, agora estamos prontos para configurar o aplicativo de exemplo para funcionar com o Elastic e o Azure Cloud. O aplicativo de exemplo C# usa um arquivo chamado appsettings.json para armazenar e carregar suas informações de acesso, como chaves de API. Agora você criará o arquivo appsettings.json usando o editor no Codespaces.

1. Crie appsettings.json na pasta HomeFinderApp

2. Cole o seguinte código no arquivo appsettings.json

3. Encontre os valores Url e ApiKey na seção ElasticSettings . Defina-os para os mesmos valores que você definiu no .env arquivo em uma etapa anterior.

Criar serviço Azure OpenAI

Nosso aplicativo de exemplo usará o Azure OpenAI para analisar a consulta do usuário do aplicativo e, em seguida, enviar uma solicitação ao Elasticsearch preenchendo o modelo de Pesquisa para tentar comunicar de forma flexível o que o usuário está pesquisando.

1. Abra uma nova aba do navegador e acesse AI Foundry | Azure OpenAI no portal do Azure. Clique +Criar

2. No formulário de criação, escolha um Grupo de Recursos.

3. Digite um nome

4. Escolha um nível de preço

5. Clique em Avançar

6. Na guia Rede , clique em Avançar

7. Na aba Tags , clique em Avançar

8. Na guia Revisar e enviar , clique em Criar

9. Após a conclusão da criação, clique em Ir para o recurso

10. Selecione Chaves e Ponto de Extremidade no menu de navegação à esquerda

11. Copie o Endpoint e cole-o no arquivo appsettings.json que você criou na aba do seu navegador que tem o editor Codespaces aberto.

12. Em seguida, volte para a aba do navegador que contém a chave do Azure OpenAI e a página do ponto de extremidade. Clique no botão copiar para Chave 1 e cole o valor copiado no arquivo appsettings.json , de volta na aba do seu navegador que tem o editor Codespaces aberto.

Adicionar implantação do modelo gpt-4o ao serviço Azure Open AI

Ótimo, agora temos um serviço Azure OpenAI em execução, mas ele ainda precisa de uma implantação de modelo para nos dar os recursos de LLM que nosso aplicativo de exemplo requer. Há uma infinidade de modelos para você escolher. Vamos implantar o gpt-4o, pois ele já está especificado no arquivo appsettings.json que você criou.

1. Acesse o Azure AI Foundry e clique em Criar uma implantação

2. Pesquise por gpt-4o e selecione-o nos resultados

3. Clique em Confirmar para selecioná-lo

4. Clique em Implantar para implantar o modelo

Depois de implantar com sucesso o modelo gpt-4o , você pode selecionar Implantações no menu de navegação à esquerda e confirmar se a implantação do gpt-4o está listada com o Estado Succeeded.

Criar conta do Azure Maps

Queremos que os usuários do nosso aplicativo de exemplo possam pesquisar propriedades imobiliárias em áreas específicas, mas sem precisar ser muito específicos. Se alguém quiser procurar uma propriedade perto do mercado local de produtores rurais, o Azure Maps é um serviço que o OpenAI LLM pode usar para obter coordenadas de latitude e longitude do mercado. As coordenadas podem então ser incluídas nas solicitações baseadas em modelo de pesquisa enviadas ao Elasticsearch para consultas de usuários que incluem localizações específicas e considerações de distância geográfica.

1. Clique em Criar nas contas do Azure Maps

2. Selecione um grupo de recursos

3. Digite um nome

4. Concordo com a declaração de licença e privacidade

5. Clique em Revisar e criar

6. Clique em Criar

7. Após a criação da conta, clique em Ir para o recurso

8. Clique em Autenticação no menu de navegação à esquerda

9. Copie o valor da Chave Primária e cole-o para ser o valor da ApiKey na seção AzureMapsSettings do arquivo appsettings.json , de volta na guia do navegador que contém o editor Codespaces

Experimente o aplicativo de exemplo

Agora vem a parte divertida. É hora de executar o aplicativo de exemplo. Temos todos os detalhes de configuração prontos, juntamente com os recursos do Elastic Cloud e do Azure Cloud necessários para executar o aplicativo.

1. Abra uma janela do Terminal no editor Codespaces.

2. Use o seguinte comando para alterar o diretório ativo para ser a pasta do aplicativo de exemplo.

3. Use o seguinte comando dotnet para executar o aplicativo.

4. Clique no botão Abrir no navegador quando ele aparecer.

5. Teste a pesquisa padrão e depois experimente algumas de suas próprias pesquisas personalizadas. Se quiser ver mais detalhes sobre o que é executado no backend para gerar os resultados da pesquisa, clique no link Mostrar ao lado de Invocações de ferramentas.

Bônus: Se você realmente quiser testar o GPT-4o, tente a seguinte pesquisa: Estou procurando um imóvel perto da Disney World, Flórida, com mais de 30 quartos, mais de 20 banheiros, piscina, garagem e perto da praia por menos de 200 mil. Esta consulta retornará resultados após várias invocações da ferramenta de pesquisa.

Elastic é a sua solução para IA de pesquisa

O aplicativo em execução é um exemplo de pesquisa guiada do Gen AI LLM usando o Elasticsearch por meio de modelos de pesquisa como fonte de dados de base. Sinta-se à vontade para experimentar e personalizar o aplicativo de exemplo para criar uma experiência de pesquisa precisa e flexível, para ajudar seus usuários a encontrar o que procuram.

Obrigado pela leitura. Experimente o Elastic Cloud .

O que é o Protocolo de Contexto do Modelo (MCP)?

Para quem não conhece, o Model Context Protocol é um padrão aberto que oferece uma maneira estruturada e bidirecional de conectar modelos de IA a várias fontes de dados e ferramentas, permitindo que eles gerem respostas mais relevantes e informadas. É comumente chamada de “porta USB-C para aplicativos de IA”.

Aqui está um diagrama arquitetônico que destaca sua natureza bidirecional:

Esta é uma mudança significativa para os profissionais de IA, pois um dos principais desafios para dimensionar aplicativos de IA é ter que criar integrações personalizadas para cada nova fonte de dados. O MCP oferece uma arquitetura sustentável e reutilizável para gerenciar e fornecer contexto aos modelos. É independente de modelo, independente de servidor e totalmente de código aberto.

O MCP é a mais recente iteração de uma linhagem de especificações de API que buscam padronizar a integração entre aplicativos. No passado, tínhamos OpenAPI para serviços RESTful, GraphQL para consulta de dados e gRPC para comunicação de microsserviços. O MCP não apenas compartilha o rigor estruturado dessas especificações mais antigas, mas também as traz para um ambiente de IA generativo, facilitando a conexão de agentes em diferentes sistemas sem conectores personalizados. De muitas maneiras, o MCP pretende fazer pelos agentes de IA o que o HTTP fez pela web. Assim como o HTTP padronizou a comunicação entre navegadores e sites, o MCP busca padronizar como os agentes de IA interagem com o mundo de dados ao seu redor.

MCP vs. outros protocolos de agentes

O cenário de protocolos de agentes está se expandindo rapidamente, com mais de uma dúzia de padrões emergentes competindo para definir como os agentes interagem. Laurie Voss, do LlamaIndex, descreve como a maioria pode ser categorizada em dois tipos: protocolos interagentes, que se concentram em agentes conversando entre si, e protocolos orientados a contexto, como o MCP, que se concentram em fornecer contexto estruturado aos LLMs.

Outros protocolos populares, como o A2A (Agent to Agent) do Google, o ACP (Agent Communication Protocol) da Cisco e da IBM e o Agora, visam permitir negociações entre agentes, construção de coalizões e até mesmo sistemas de identidade descentralizados. O MCP adota uma abordagem um pouco mais pragmática, pois se concentra em como os agentes acessam ferramentas e dados e não necessariamente como eles se comunicam entre si (embora o MCP também possa permitir isso no futuro de diferentes maneiras).

Atualmente, o que diferencia o MCP é sua tração e impulso. Assim como o React nos primeiros dias dos frameworks de front-end, o MCP começou com um problema de nicho e agora é um dos protocolos de agente mais adotados e extensíveis na prática.

Recapitulação da cúpula: Prioridades em evolução para o MCP

A cúpula contou com palestrantes de colaboradores da Anthropic, Okta, OpenAI, AWS, GitHub e muitos outros. As palestras abrangeram desde melhorias no protocolo principal até implementações no mundo real e delinearam prioridades imediatas e de longo prazo. Essas palestras refletiram uma mudança da experimentação inicial e da simples chamada de ferramentas para a construção de sistemas de IA confiáveis, escaláveis e modulares usando o MCP como base.

Vários palestrantes sugeriram um futuro em que o MCP será mais do que apenas um protocolo de encanamento; ele poderá se tornar a base de uma web nativa de IA. Assim como o JavaScript permitiu que os usuários clicassem e interagissem com páginas da web, o MCP poderia permitir que agentes realizassem as mesmas ações em nosso nome. Por exemplo, no comércio eletrônico, em vez de os usuários navegarem manualmente até um site para comprar, eles poderiam simplesmente dizer a um agente para fazer login, encontrar um produto específico, adicioná-lo ao carrinho e finalizar a compra.

Isso não é apenas pura especulação e exagero; o PayPal apresentou seu novo kit de ferramentas para agentes e servidor MCP na cúpula, o que possibilita exatamente essa experiência de comércio com agentes. Com o MCP fornecendo acesso seguro e confiável a ferramentas e fontes de dados, os agentes não apenas lerão a web, mas também poderão agir com base nela. Hoje, o MCP já é um padrão poderoso e com muita força e, no futuro, pode se tornar o padrão de interações de usuários aprimoradas por IA na web.

Atualizações do projeto MCP: transporte, elicitação e ferramentas estruturadas

Jerome Swannack, um dos principais colaboradores do MCP, compartilhou algumas atualizações da especificação do protocolo dos últimos 6 meses. Os principais objetivos dessas mudanças são:

1. Para habilitar o MCP remoto com a adição do Streamable HTTP

2. Para permitir modelos de interação de agentes mais ricos com a adição de Elicitação e Esquemas de Saída de Ferramentas

Como o MCP é de código aberto, mudanças como o Streamable HTTP já estão disponíveis para os desenvolvedores implementarem. Os esquemas de elicitação e saída de ferramentas ainda não foram lançados; eles estão em fase de rascunho e podem evoluir.

HTTP transmissível (lançado em 26/03/2025): Uma atualização técnica impactante foi a introdução do HTTP transmissível como um novo mecanismo de transporte. Isso substitui eventos enviados pelo servidor (SSE) por um modelo bidirecional mais escalável que oferece suporte à codificação de transferência em blocos e à entrega progressiva de mensagens em uma única conexão HTTP. Isso permite que você implante servidores MCP em infraestrutura de nuvem como AWS Lambda e ofereça suporte a restrições de rede corporativa sem conexões de longa duração ou necessidade de sondagem.

Elicitação (lançado em 18/06/2025): a elicitação permite que os servidores definam um esquema de como eles querem que o contexto seja estruturado a partir de um cliente. Basicamente, o servidor pode descrever o que precisa e o tipo de entrada que espera. Isso tem algumas implicações: para os construtores de servidores, eles podem criar interações de agentes mais complexas. Para construtores de clientes, eles podem implementar interfaces de usuário dinâmicas que se adaptam a esses esquemas. No entanto, a elicitação não deve ser usada para extrair informações confidenciais ou pessoalmente identificáveis dos usuários. Os desenvolvedores devem seguir as melhores práticas para garantir que os prompts de elicitação permaneçam seguros e apropriados, especialmente à medida que o MCP amadurece. Isso está ligado a preocupações de segurança mais amplas que discutiremos mais adiante neste post.

Esquemas de saída de ferramentas (lançados em 18/06/2025): este conceito permite que o cliente e o LLM conheçam as formas de saída da ferramenta com antecedência. Os esquemas de saída da ferramenta permitem que os desenvolvedores descrevam o que se espera que uma ferramenta retorne. Esses esquemas abordam uma das principais limitações da chamada direta de ferramentas, que é o uso ineficiente da janela de contexto. A janela de contexto é considerada um dos recursos mais importantes ao trabalhar com LLMs e, quando você chama uma ferramenta diretamente, ela retorna conteúdo bruto que é totalmente inserido no contexto do LLM. Os esquemas de saída da ferramenta podem ajudar você a fazer melhor uso dos seus tokens e da janela de contexto, permitindo que o servidor MCP forneça dados estruturados. Aqui estão algumas práticas recomendadas sobre ferramentas em geral.

Juntas, essas novas atualizações e adições futuras ajudarão o MCP a se tornar um protocolo de agente mais modular, tipado e pronto para produção.

Recursos de energia subutilizados: amostragem e raízes

Embora não seja novidade na especificação MCP, tanto a amostragem quanto as raízes foram destacadas durante a palestra. Essas duas primitivas são atualmente negligenciadas e pouco exploradas, mas podem contribuir significativamente para interações mais ricas e seguras entre agentes.

Amostragem - Os servidores podem solicitar conclusões do cliente: A amostragem permite que os servidores MCP solicitem conclusões do LLM do lado do cliente. Isso aumenta a natureza bidirecional do protocolo, onde o servidor não está apenas respondendo às solicitações; ele pode solicitar e pedir ao modelo do cliente para gerar uma resposta. Isso permite que o cliente mantenha controle total sobre o custo, a segurança e qual modelo o servidor MCP usa. Portanto, no caso de usar um servidor MCP externo com um modelo pré-configurado, você não precisará fornecer suas próprias chaves de API ou configurar sua própria assinatura para esse modelo, pois o servidor pode simplesmente solicitar o modelo já conectado ao cliente. Isso permite comportamentos de agentes mais complexos e interativos.

Raízes - Acesso com escopo aos recursos: As raízes foram projetadas para fornecer uma maneira para os clientes informarem os servidores sobre recursos e espaços de trabalho relevantes nos quais se concentrar. Isso é útil para definir o escopo no qual os servidores operam. É importante observar que as raízes são “informativas e não estritamente obrigatórias”, o que significa que elas não definem direitos ou permissões para servidores ou agentes MCP. Em outras palavras, você não pode confiar apenas nas raízes para impedir que um servidor ou agente execute determinadas ferramentas ou realize ações de gravação. Com raízes, as permissões ainda devem ser manipuladas no lado do cliente com mecanismos para aprovação do usuário. Além disso, os desenvolvedores ainda devem estar atentos ao uso de servidores projetados para respeitar os limites definidos pelas raízes e usar as melhores práticas.

Autenticação para agentes: OAuth 2.1 e metadados protegidos

Esta seção se concentra no OAuth 2.1, que é a iteração mais recente do OAuth 2.0 que remove fluxos inseguros e consolida as melhores práticas.

O suporte ao OAuth era um tópico muito aguardado, especialmente porque a segurança e a escalabilidade são vistas como os principais obstáculos que impedem o MCP de se tornar o padrão para conectar agentes a ferramentas. Aaron Parecki (editor do OAuth 2.1 e especialista em padrões de identidade na Okta) discutiu como o MCP pode adotar um fluxo OAuth limpo e escalável que alivia a maior parte da complexidade dos desenvolvedores de servidores. A especificação oficial de autorização OAuth 2.1 foi publicada recentemente na última revisão do protocolo em 18/06/2025.

Nesta implementação, as responsabilidades do OAuth podem ser divididas entre o cliente MCP e o servidor. A maior parte do fluxo de autenticação é iniciada e gerenciada pelo cliente MCP, envolvendo apenas o servidor no final para receber e verificar o token seguro. Essa divisão ajuda a resolver um problema crítico de dimensionamento de como autenticar em muitas ferramentas sem exigir que os desenvolvedores configurem cada conexão e garante que os desenvolvedores do servidor MCP não precisem se tornar especialistas em OAuth.

Dois destaques principais da palestra:

1. Metadados de recursos protegidos: os servidores MCP podem publicar um arquivo JSON descrevendo sua finalidade, pontos de extremidade e métodos de autenticação. Isso permite que os clientes iniciem fluxos OAuth apenas com a URL do servidor, simplificando o processo de conexão. Saiba mais: Vamos corrigir o OAuth no MCP

2. Suporte para IDPs e SSO: as empresas podem integrar provedores de identidade para gerenciar o acesso centralmente. Isto é uma vitória tanto para a experiência do usuário quanto para a segurança. Os usuários não precisariam clicar em 10 telas de consentimento diferentes e as equipes de segurança poderiam ter visibilidade de cada conexão.

Ao enviar a lógica do OAuth para o cliente e confiar nos metadados dos servidores, o ecossistema MCP evita um grande gargalo. Isso alinha o MCP mais de perto com a forma como as APIs modernas são protegidas nos ambientes de produção atuais.

Leitura adicional: OAuth 2 simplificado.

Desafios de segurança em um ecossistema componível

Novos desenvolvimentos também trazem novas superfícies de ataque. Arjun Sambamoorthy, da Cisco, lista diversas ameaças importantes no cenário do MCP, incluindo:

Ameaça

Descrição

Remediação e melhores práticas

Injeção imediata e envenenamento por ferramentas

Uma maneira de injetar um prompt malicioso dentro do contexto do sistema LLM ou da descrição da ferramenta, fazendo com que o LLM execute ações não intencionais, como ler arquivos ou vazar dados.

Use ferramentas como o MCP Scan para realizar verificações nos metadados das ferramentas. Valide descrições e parâmetros antes de incluí-los nos prompts. Por fim, considere implementar aprovações de usuários para ferramentas de alto risco. Para mais detalhes, consulte o guia de injeção rápida do OWASP na lista de leitura adicional abaixo da tabela.

Ataques de amostragem

No contexto do MCP, a amostragem abre a porta para o servidor MCP realizar ataques de injeção rápida no LLM.

Desative a amostragem para servidores não confiáveis e considere adicionar aprovações humanas para solicitações de amostragem.

Servidores MCP maliciosos

Nas coleções atuais de servidores MCP, é difícil verificar cada um deles para garantir a segurança. Servidores invasores podem coletar e expor silenciosamente seus dados a agentes maliciosos.

Conecte-se somente a servidores MCP de registros confiáveis ou listas internas. Execute servidores de terceiros em contêineres com sandbox.

Ferramentas de instalação de MCP maliciosas

Instaladores de linha de comando e scripts são convenientes para implementar rapidamente servidores ou ferramentas MCP, mas você pode acabar instalando código comprometido e não verificado.

Instale em ambientes sandbox e valide assinaturas de pacotes. Nunca atualize automaticamente a partir de fontes não verificadas.

Para combater ainda mais isso, Arjun sugere um registro MCP confiável para lidar com todas as verificações (um tópico que estava em destaque — para mais detalhes, veja os dois principais itens na lista de leitura abaixo), bem como usar esta lista de verificação de segurança.

Leitura adicional:

• Melhores práticas oficiais de segurança do MCP

• Top 10 de inscrições para o OWASP LLM

• Pesquisa de ameaças HiddenLayer

• Varredura MCP

• Guia de injeção rápida OWASP

O que vem a seguir: Registros, governança e ecossistema

Um registro centralizado do MCP está em desenvolvimento e foi um dos tópicos mais consistentemente discutidos na cúpula. O ecossistema de servidores atual sofre de fragmentação, baixa confiança e capacidade de descoberta. É difícil para os desenvolvedores encontrar servidores MCP, verificar o que eles fazem e instalá-los com segurança, especialmente em um ecossistema descentralizado onde os metadados podem estar incompletos ou falsificados.

Um registro centralizado aborda esses pontos problemáticos diretamente, agindo como uma fonte confiável de verdade, melhorando a capacidade de descoberta, garantindo a integridade dos metadados do servidor e reduzindo o risco de instalação de ferramentas maliciosas.

Os objetivos do registro MCP são:

• Oferecendo uma única fonte de verdade para metadados do servidor (o que um servidor faz, como autenticar, instalá-lo e chamá-lo)

• Eliminar registros de terceiros incompletos e fragmentação para que, quando um servidor quiser ser registrado, ele não precise atualizar todos os outros registros na Internet.

• Fornecendo um fluxo de registro de servidor que inclui uma ferramenta CLI e um arquivo server.json que contém os metadados mencionados anteriormente.

A esperança mais ampla é que um registro confiável ajude a dimensionar o ecossistema com segurança, permitindo que os desenvolvedores criem e compartilhem novas ferramentas com confiança.

Governança foi outra questão prioritária para a Anthropic. Eles deixaram claro que o MCP deve permanecer aberto e orientado pela comunidade, mas dimensionar esse modelo de governança ainda é um trabalho em andamento. Atualmente, eles estão buscando ajuda nessa área e pedem que qualquer pessoa que tenha experiência com governança em protocolos de código aberto entre em contato. Isso nos leva ao outro tópico que eu queria mencionar. Durante o evento, os palestrantes enfatizaram que o ecossistema só pode crescer com contribuições dos desenvolvedores internos. É preciso haver um esforço concentrado para tornar o MCP o novo padrão da web e se destacar dos outros protocolos de agentes populares.

MCP no mundo real: estudos de caso e demonstrações

Várias organizações compartilharam como o MCP já está sendo usado em aplicações práticas:

• PayPal - Servidor MCP para comércio de agentes: o PayPal apresentou seu novo kit de ferramentas de agente e servidor MCP, que pode mudar fundamentalmente a experiência de compra do usuário. Em vez de vasculhar as redes sociais para encontrar itens, comparar preços e finalizar a compra, os usuários podem conversar com um agente que se conecta ao servidor MCP do PayPal para lidar com todas essas ações.

• EpicAI.pro - Jarvis: Os desenvolvimentos no MCP nos deixam cada vez mais perto de ter um assistente real do tipo Jarvis. Para quem não conhece os filmes do Homem de Ferro, Jarvis é um assistente de IA que usa linguagem natural, responde a entradas multimodais, tem latência zero ao responder, é proativo em antecipar as necessidades do usuário, gerencia integrações automaticamente e pode alternar o contexto entre dispositivos e locais. Se imaginarmos Jarvis como um assistente robótico físico, o MCP dá a Jarvis “mãos” ou a capacidade de lidar com tarefas complexas.

• Postman - Gerador de servidor MCP: fornece uma experiência de carrinho de compras para solicitações de API, onde você pode escolher diferentes solicitações de API, colocá-las em uma cesta e baixar a cesta inteira como um servidor MCP.

• Bloomberg - A Bloomberg resolveu um gargalo importante no desenvolvimento empresarial de GenAI. Com quase 10.000 engenheiros, eles precisavam de uma maneira padronizada de integrar ferramentas e agentes entre as equipes. Com o MCP, eles transformaram suas ferramentas internas em componentes modulares e remotos que os agentes podem facilmente chamar em uma interface unificada. Isso permitiu que seus engenheiros contribuíssem com ferramentas em toda a organização, enquanto as equipes de IA se concentravam na criação de agentes em vez de integrações personalizadas. A Bloomberg agora oferece suporte a fluxos de trabalho de agentes escaláveis e seguros que desbloqueiam total interoperabilidade com o ecossistema MCP. A Bloomberg não divulgou nenhum recurso público, mas foi isso que eles apresentaram publicamente na cúpula.

• Block - O Block usa o MCP para impulsionar o Goose, um agente de IA interno que permite aos funcionários automatizar tarefas de engenharia, vendas, marketing e muito mais. Eles criaram mais de 60 servidores MCP para ferramentas como Git, Snowflake, Jira e Google Workspace para permitir interação em linguagem natural com os sistemas que eles usam todos os dias. Os funcionários da Block agora usam o Goose para consultar dados, detectar fraudes, gerenciar incidentes, navegar em processos internos e muito mais, tudo isso sem precisar escrever código. O MCP ajudou a Block a escalar a adoção de IA em muitas funções de trabalho em apenas 2 meses.

• AWS - Servidores MCP da AWS: a AWS apresentou um divertido servidor MCP com tema de Dungeons and Dragons que simula o lançamento de dados, rastreia lançamentos anteriores e retorna resultados usando Streamable HTTP. Este exemplo simples destacou como é fácil construir e implantar servidores MCP usando ferramentas e infraestrutura da AWS, como Lambda e Fargate. Eles também introduziram o Strands SDK, um kit de ferramentas de código aberto para criar agentes multimodais que interagem com servidores MCP.

Suporte a MCP no Elastic Agent Builder

Você pode começar a experimentar o MCP hoje mesmo usando o Elastic Agent Builder, que é a maneira mais fácil de criar agentes diretamente sobre seus dados. O Agent Builder permite expor ferramentas baseadas em Elasticsearch para agentes compatíveis com MCP e já vem com algumas ferramentas integradas poderosas, incluindo:

• platform.core.search - Executa pesquisas usando a DSL de consulta completa do Elasticsearch

• platform.core.list_indices - Lista todos os índices disponíveis no Elasticsearch (ajuda os agentes a descobrir quais dados existem)

• platform.core.get_index_mapping - Recupera mapeamentos de campos para um índice específico (ajuda os agentes a entenderem o formato e os tipos dos seus dados)

• platform.core.get_document_by_id - Busca um documento específico por ID (para uma recuperação precisa)

Somente com essas ferramentas, você pode equipar seu agente com pesquisa e relevância de nível empresarial, o que é fundamental para a criação de agentes de IA confiáveis.

O que torna o Agent Builder ainda mais poderoso é a capacidade de definir e expor suas próprias ferramentas personalizadas, adaptadas às necessidades do seu aplicativo. Isso é especialmente útil para fluxos de trabalho repetitivos ou com critérios predefinidos, nos quais você deseja que o agente execute um tipo específico de pesquisa em um índice específico, sem precisar redescobrir essa lógica a cada vez. Em vez de gastar tokens em planejamento e raciocínio para chegar à mesma conclusão, você pode codificar essa intenção diretamente em uma ferramenta, tornando seus agentes mais rápidos, confiáveis e econômicos.

Na interface do usuário do Agent Builder, aqui está um exemplo de definição de ferramenta personalizada que usa ES|QL:

Depois de definir suas ferramentas personalizadas, você pode expô-las (além das ferramentas nativas integradas) usando o MCP clicando no menu suspenso para Manage MCP e copiando o URL do servidor MCP.

Agora você pode importar este endpoint MCP para qualquer cliente que utilize MCP, conectando-o ao Agent Builder e dando-lhe acesso a todas as ferramentas disponíveis. Para obter mais informações, leia esta introdução ao Agent Builder.

Conclusão

O MCP Dev Summit deixou claro que o MCP está moldando a maneira como esses agentes de IA interagem entre si e com o mundo de dados ao seu redor. Não importa se você está conectando um agente a dados corporativos ou projetando agentes totalmente autônomos, o MCP oferece uma maneira padronizada e combinável de integração que está rapidamente se tornando útil em escala. De protocolos de transporte e padrões de segurança a registros e governança, o ecossistema MCP está amadurecendo rapidamente. O MCP continuará aberto e orientado pela comunidade, para que os desenvolvedores de hoje tenham a chance de moldar sua evolução.

O que é Spring AI?

O Spring AI 1.0, uma solução abrangente para engenharia de IA em Java, já está disponível após um período significativo de desenvolvimento influenciado pelos rápidos avanços na área de IA. Esta versão inclui diversas novas funcionalidades essenciais para engenheiros de IA.

Java e Spring estão em uma posição privilegiada para aproveitar toda essa onda de IA. Inúmeras empresas estão executando seus sistemas com Spring Boot, o que torna extremamente fácil integrar IA ao que elas já fazem. Basicamente, você pode conectar sua lógica de negócios e seus dados diretamente a esses modelos de IA sem muita dificuldade.

O Spring AI oferece suporte a diversos modelos e tecnologias de IA, tais como:

• Modelos de imagem: geram imagens a partir de instruções de texto.

• Modelos de transcrição: pegam fontes de áudio e as convertem em texto.

• Modelos de incorporação: convertem dados arbitrários em vetores, que são tipos de dados otimizados para busca de similaridade semântica.

• Modelos de bate-papo: estesDeve ser familiar! Você sem dúvida já teve até mesmo uma breve conversa com um deles em algum lugar.

Os modelos de bate-papo parecem ser o foco da maior parte da atenção no campo da IA, e com razão, eles são incríveis! Você pode pedir a ajuda deles para corrigir um documento ou escrever um poema. (Só não peça para eles contarem uma piada... ainda.) Eles são incríveis, mas têm alguns problemas.

Soluções de IA da Spring para desafios de IA

Vamos analisar alguns desses problemas e suas soluções no Spring AI.

Problema

Solução

Consistência

Os modelos de bate-papo são de mente aberta e propensos a distrações.

Você pode fornecer a eles um comando do sistema para controlar sua forma e estrutura geral.

Memória

Os modelos de IA não têm memória, portanto não conseguem correlacionar uma mensagem de um determinado usuário com outra.

Você pode fornecer a eles um sistema de memória para armazenar as partes relevantes da conversa.

Isolamento

Os modelos de IA vivem em pequenos ambientes isolados, mas podem fazer coisas realmente incríveis se você lhes der acesso a ferramentas — funções que eles podem invocar quando julgarem necessário.

O Spring AI oferece suporte à chamada de ferramentas, o que permite informar ao modelo de IA sobre as ferramentas em seu ambiente, que ele poderá então solicitar que você as invoque. Essa interação de múltiplas etapas é gerenciada de forma transparente para você.

Dados privados

Os modelos de IA são inteligentes, mas não são oniscientes! Eles não sabem o que está contido em seus bancos de dados proprietários - e acreditamos que você também não gostaria que soubessem!

Você precisa influenciar as respostas inserindo texto nos prompts — basicamente, usando o poderoso operador de concatenação de strings para adicionar texto à requisição antes que o modelo analise a pergunta feita. Informações adicionais, se quiser. Como você decide o que deve ser enviado e o que não deve? Utilize um armazenamento vetorial para selecionar apenas os dados relevantes e enviá-los adiante. Isso é chamado de geração aumentada por recuperação, ou RAG.

Alucinação

Os modelos de bate-papo com IA gostam, bem, de conversar! E às vezes fazem isso com tanta confiança que chegam a inventar coisas.

É necessário usar a avaliação — utilizando um modelo para validar a saída de outro — para confirmar resultados razoáveis.

E, claro, nenhuma aplicação de IA é uma ilha. Atualmente, os sistemas e serviços de IA modernos funcionam melhor quando integrados a outros sistemas e serviços. Protocolo de Contexto do Modelo(MCP) possibilita conectar seus aplicativos de IA com outros serviços baseados em MCP, independentemente da linguagem em que foram escritos. Você pode reunir tudo isso em fluxos de trabalho orientados a agentes que conduzem a um objetivo maior.

A melhor parte? Você pode fazer tudo isso enquanto aproveita os padrões e abstrações familiares que qualquer desenvolvedor Spring Boot já espera: dependências iniciais convenientes para praticamente tudo estão disponíveis no Spring Initializr.

O Spring AI oferece configurações automáticas convenientes do Spring Boot, proporcionando a abordagem de convenção sobre configuração que você já conhece e espera. E o Spring AI oferece suporte à observabilidade com o Actuator do Spring Boot e o projeto Micrometer. Ele também funciona bem com o GraalVM e threads virtuais, permitindo que você crie aplicativos de IA super rápidos, eficientes e escaláveis.

Por que o Elasticsearch?

O Elasticsearch é um mecanismo de busca de texto completo, você provavelmente já sabe disso. Então, por que estamos usando isso para este projeto? Bem, também é uma loja de vetores! E uma muito boa, por sinal, onde os dados ficam lado a lado com o texto completo. Outras vantagens notáveis:

• Super fácil de configurar

• Código aberto

• Escalável horizontalmente

• A maior parte dos dados de formato livre da sua organização provavelmente já reside em um cluster Elasticsearch.

• Funcionalidade completa de mecanismo de busca

• Totalmente integrado ao Spring AI!

Considerando tudo, o Elasticsearch atende a todos os requisitos para ser um excelente banco de dados de vetores, então vamos configurá-lo e começar a construir nossa aplicação!

Introdução ao Elasticsearch

Precisaremos tanto do Elasticsearch quanto do Kibana, o console de interface do usuário que você usará para interagir com os dados hospedados no banco de dados.

Você pode experimentar tudo em sua máquina local graças aos recursos das imagens Docker e à página inicial da Elastic.co. Acesse essa página, role a tela para baixo até encontrar o comando curl , execute-o e redirecione a saída diretamente para o seu shell:

Isso simplesmente baixará e configurará as imagens Docker para Elasticsearch e Kibana e, após alguns minutos, você as terá em execução em sua máquina local, com as credenciais de conexão já definidas.

Você também tem duas URLs diferentes que pode usar para interagir com sua instância do Elasticsearch. Faça como indicado e acesse http://localhost:5601 pelo seu navegador.

Observe também o nome de usuário elastic e a senha impressos no console: você precisará deles para fazer login (no exemplo de saída acima, eles são respectivamente elastic e w1GB15uQ).

Reunindo o aplicativo

Acesse a página do Spring Initializr e gere um novo projeto Spring AI com as seguintes dependências:

• Elasticsearch Vector Store

• Spring Boot Actuator

• GraalVM

• OpenAI

• Web

Certifique-se de escolher a versão mais recente do Java (idealmente Java 24 - na data desta publicação - ou posterior) e a ferramenta de compilação de sua preferência. Neste exemplo, estamos usando o Apache Maven.

Clique em Generate e depois descompacte o projeto e importe-o para o seu IDE de escolha. (Estamos usando o IntelliJ IDEA.)

Em primeiro lugar, vamos especificar os detalhes de conexão para sua aplicação Spring Boot. Em application.properties, escreva o seguinte:

Também utilizaremos a capacidade de armazenamento vetorial do Spring AI para inicializar o que for necessário no lado do Elasticsearch em termos de estruturas de dados, portanto, especifique:

Nesta demonstração, usaremos o OpenAI , especificamente o Modelo de Incorporação e o Modelo de Chat (sinta-se à vontade para usar o serviço de sua preferência, desde que o Spring AI o suporte).

O modelo de incorporação é necessário para criar representações dos dados antes de armazená-los no Elasticsearch. Para que o OpenAI funcione, precisamos especificar o API key:

Você pode defini-la como uma variável de ambiente, como SPRING_AI_OPENAI_API_KEY para evitar armazenar a credencial no seu código-fonte.

Vamos enviar arquivos, então certifique-se de personalizar a quantidade de dados que pode ser enviada para o contêiner de servlet:

Estamos quase lá! Antes de começarmos a escrever o código, vamos ter uma prévia de como isso vai funcionar.

Em nossa máquina, baixamos o seguinte arquivo (uma lista de regras para um jogo de tabuleiro), renomeamos para test.pdf e o colocamos em ~/Downloads/test.pdf.

O arquivo será enviado para o endpoint /rag/ingest (substitua o caminho de acordo com sua configuração local):

Isso pode levar alguns segundos…

Nos bastidores, os dados são enviados para a OpenAI, que cria representações vetoriais (embeddings) dos dados; esses dados são então gravados no Elasticsearch, tanto os vetores quanto o texto original.

É nesses dados, juntamente com todos os elementos incorporados neles, que a mágica acontece. Podemos então consultar o Elasticsearch usando a interface VectorStore .

O fluxo completo se parece com isto:

• O cliente HTTP carrega o PDF de sua escolha para a aplicação Spring.

• O Spring AI se encarrega da extração de texto do nosso PDF e divide cada página em blocos de 800 caracteres.

• A OpenAI gera a representação vetorial para cada segmento.

• Tanto o texto fragmentado quanto o arquivo incorporado são armazenados no Elasticsearch.

Por fim, vamos fazer uma consulta:

E obteremos uma resposta relevante:

Que legal! Como tudo isso funciona?

• O cliente HTTP envia a pergunta para a aplicação Spring.

• O Spring AI obtém a representação vetorial da pergunta da OpenAI.

• Com essa incorporação, ele busca documentos semelhantes nos blocos armazenados do Elasticsearch e recupera os documentos mais similares.

• A Spring AI envia então a pergunta e o contexto obtido para a OpenAI para gerar uma resposta LLM.

• Por fim, retorna a resposta gerada e uma referência ao contexto recuperado.

Vamos analisar o código Java para ver como ele realmente funciona.

Primeiramente, a classe Main : é uma classe principal padrão para qualquer aplicação Spring Boot.

Nada para ver ali. Continuando…

Em seguida, um controlador HTTP básico:

O controlador está simplesmente chamando um serviço que criamos para lidar com a ingestão de arquivos e sua gravação no armazenamento vetorial do Elasticsearch, e então facilitar consultas nesse mesmo armazenamento vetorial.

Vamos analisar o serviço:

Este código lida com toda a ingestão: dado um Resource do Spring Framework, que é um contêiner em torno de bytes, lemos os dados do PDF (presumido ser um arquivo .PDF - certifique-se de validar isso antes de aceitar entradas arbitrárias!) usando o PagePdfDocumentReader do Spring AI e, em seguida, tokenizamos usando o TokenTextSplitter do Spring AI, finalmente adicionando os List<Document>resultantes à implementação do VectorStore , ElasticsearchVectorStore.

Você pode confirmar isso usando o Kibana: depois de enviar um arquivo para o endpoint /rag/ingest , abra seu navegador em localhost:5601 e no menu lateral à esquerda navegue até Dev Tools. Ali você pode enviar consultas para interagir com os dados na instância do Elasticsearch.

Faça uma consulta como esta:

Agora vem a parte divertida: como recuperamos esses dados em resposta às consultas dos usuários?

Aqui está uma primeira tentativa de implementação da consulta, em um método chamado directRag.

O código é bastante simples, mas vamos dividi-lo em várias etapas:

1. Use VectorStore para realizar uma pesquisa de similaridade.

2. Dados todos os resultados, obtenha os Documentsubjacentes do Spring AI e extraia seu texto, concatenando-os em um único resultado.

3. Envie os resultados de VectorStore para o modelo, juntamente com uma instrução para o modelo saber o que fazer com eles e a pergunta do usuário. Aguarde a resposta e retorne-a.

Isto é RAG - geração aumentada de recuperação. A ideia é usar dados de um repositório vetorial para orientar o processamento e a análise realizados pelo modelo. Agora que você já sabe como fazer, esperemos que nunca precise fazer! Não assim: os Advisors da Spring AI estão aqui para simplificar ainda mais esse processo.

O Advisors permite pré-processar e pós-processar uma solicitação para um determinado modelo, além de fornecer uma camada de abstração entre seu aplicativo e o armazenamento de vetores. Adicione a seguinte dependência à sua compilação:

Adicione outro método chamado advisedRag(String question) à classe:

Toda a lógica do padrão RAG está encapsulada em QuestionAnswerAdvisor. Todo o resto é exatamente como qualquer solicitação a um ChatModel seria! Legal!

E você pode obter o código completo no GitHub.

Conclusão

Nesta demonstração, usamos imagens Docker e fizemos tudo em nossa máquina local, mas o objetivo aqui é construir sistemas e serviços de IA prontos para produção. Existem várias coisas que você pode fazer para tornar isso realidade.

Em primeiro lugar, você pode adicionar o Spring Boot Actuator para monitorar o consumo de tokens. Os tokens são uma representação da complexidade (e, às vezes, do custo em dólares) de uma determinada solicitação ao modelo.

Você já tem o Spring Boot Actuator no classpath, então basta especificar as seguintes propriedades para exibir todas as métricas (capturadas pelo magnífico projeto Micrometer.io ):

Reinicie o aplicativo. Faça uma consulta e depois acesse: http://localhost:8080/actuator/metrics. Pesquise por “token” e você verá informações sobre os tokens que estão sendo usados pelo aplicativo. Fique de olho nisso. Você também pode usar a integração do Micrometer com o Elasticsearch para enviar essas métricas e fazer com que o Elasticsearch funcione como seu banco de dados de séries temporais preferido!

Você deve então considerar que, cada vez que fazemos uma solicitação a um armazenamento de dados como o Elasticsearch, ou ao OpenAI, ou a outros serviços de rede, estamos realizando operações de entrada/saída (E/S) e, frequentemente, essas operações de E/S bloqueiam os threads nos quais são executadas. O Java 21 e versões posteriores incluem threads virtuais não bloqueantes que melhoram drasticamente a escalabilidade. Ative-o com:

E, por fim, você vai querer hospedar seu aplicativo e seus dados em um local onde eles possam prosperar e ser escaláveis. Temos certeza de que você provavelmente já pensou em onde executar seu aplicativo, mas onde você hospedará seus dados? Podemos recomendar a Elastic Cloud? É seguro, privado, escalável e repleto de recursos. Nossa parte favorita? Se quiser, você pode adquirir a edição Serverless, onde o Elasticsearch é que controla o pager, e não você!

Este blog se concentra na execução e personalização do modelo do agente de recuperação LangChain usando o LangGraph Studio e o LangGraph CLI. O modelo fornece uma estrutura para a criação de aplicativos de geração aumentada de recuperação (RAG), aproveitando vários backends de recuperação, como o Elasticsearch.

Orientaremos você na configuração do ambiente e na execução eficiente do modelo com o Elastic, ao mesmo tempo em que personalizamos o fluxo do agente.

Pré-requisitos

Antes de prosseguir, certifique-se de ter o seguinte instalado:

• Implantação do Elasticsearch Cloud ou implantação do Elasticsearch no local (ou crie uma avaliação gratuita de 14 dias no Elastic Cloud) - Versão 8.0.0 ou superior

• Python 3.9+

• Acesso a um provedor de LLM como Cohere (usado neste guia), OpenAI ou Anthropic/Claude

Criando o aplicativo LangGraph

1. Instale o LangGraph CLI

2. Crie o aplicativo LangGraph a partir do modelo de agente de recuperação

Será apresentado um menu interativo que permitirá que você escolha entre uma lista de modelos disponíveis. Selecione 4 para Agente de Recuperação e 1 para Python, conforme mostrado abaixo:

• Solução de problemas: se você encontrar o erro “urllib.error.URLError: <erro urlopen [SSL: CERTIFICATE_VERIFY_FAILED] falha na verificação do certificado: não é possível obter o certificado do emissor local (_ssl.c:1000)> “

Execute o comando Instalar Certificado do Python para resolver o problema, conforme mostrado abaixo.

3. Instalar dependências

Na raiz do seu novo aplicativo LangGraph, crie um ambiente virtual e instale as dependências no modo edit para que suas alterações locais sejam usadas pelo servidor:

Configurando o ambiente

1. Crie um arquivo .environment arquivo

O arquivo .env contém chaves de API e configurações para que o aplicativo possa se conectar ao LLM e ao provedor de recuperação escolhidos. Gere um novo arquivo .env duplicando a configuração de exemplo:

2. Configure o arquivo .env arquivo

O arquivo .env vem com um conjunto de configurações padrão. Você pode atualizá-lo adicionando as chaves de API e os valores necessários com base na sua configuração. Quaisquer chaves que não sejam relevantes para seu caso de uso podem ser deixadas inalteradas ou removidas.

• Exemplo de arquivo .env (usando Elastic Cloud e Cohere)

Abaixo está um exemplo de configuração .env para usar o Elastic Cloud como provedor de recuperação e o Cohere como LLM, conforme demonstrado neste blog:

Observação: embora este guia utilize o Cohere para geração de respostas e incorporações, você pode usar outros provedores de LLM, como OpenAI, Claudeou até mesmo um modelo de LLM local, dependendo do seu caso de uso. Certifique-se de que cada chave que você pretende usar esteja presente e definida corretamente no arquivo.env.

3. Atualize o arquivo de configuração - configuration.py

Depois de configurar seu arquivo .env com as chaves de API apropriadas, a próxima etapa é atualizar a configuração do modelo padrão do seu aplicativo. Atualizar a configuração garante que o sistema use os serviços e modelos que você especificou no seu arquivo .env .

Navegue até o arquivo de configuração:

O arquivo configuration.py contém as configurações de modelo padrão usadas pelo agente de recuperação para três tarefas principais:

• Modelo de incorporação – converte documentos em representações vetoriais

• Modelo de consulta – processa a consulta do usuário em um vetor

• Modelo de resposta – gera a resposta final

Por padrão, o código usa modelos do OpenAI (por exemplo, openai/text-embedding-3-small) e do Anthropic (por exemplo, anthropic/claude-3-5-sonnet-20240620 and anthropic/claude-3-haiku-20240307). Neste blog, estamos mudando para o uso de modelos Cohere. Se você já estiver usando OpenAI ou Anthropic, nenhuma alteração será necessária.

Exemplos de alterações (usando Cohere):

Abra configuration.py e modifique os padrões do modelo conforme mostrado abaixo:

Executando o agente de recuperação com a CLI do LangGraph

1. Inicie o servidor LangGraph

Isso iniciará o servidor LangGraph API localmente. Se isso for executado com sucesso, você deverá ver algo como:

URL da interface do usuário do Open Studio.

Há dois gráficos disponíveis:

• Gráfico de recuperação: Recupera dados do Elasticsearch e responde à consulta usando um LLM (Language-Level Model).

• Gráfico do indexador: Indexa documentos no Elasticsearch e gera embeddings usando um LLM.

2. Configurando o gráfico do indexador

• Abra o gráfico do indexador.

• Clique em Gerenciar assistentes.

  • Clique em 'Adicionar novo assistente ', insira os dados do usuário conforme especificado e, em seguida, feche a janela.

3. Indexação de documentos de amostra

• Indexe os seguintes documentos de exemplo, que representam um relatório trimestral hipotético para a organização NoveTech:

Depois que os documentos forem indexados, você verá uma mensagem de exclusão no tópico, conforme mostrado abaixo.

4. Executando o grafo de recuperação

• Mude para o gráfico de recuperação.

• Digite a seguinte consulta de pesquisa:

O sistema retornará documentos relevantes e fornecerá uma resposta exata com base nos dados indexados.

Personalize o agente de recuperação.

Para melhorar a experiência do usuário, introduzimos uma etapa de personalização no grafo de recuperação para prever as próximas três perguntas que um usuário poderá fazer. Essa previsão se baseia em:

• Contexto dos documentos recuperados

• Interações anteriores do usuário

• Última consulta do usuário

As seguintes alterações de código são necessárias para implementar o recurso de Previsão de Consulta:

1. Atualize o arquivo graph.py

• Adicione a função predict_query :

• Modifique a função respond para retornar o objeto response , em vez da mensagem:

• Atualizar estrutura do gráfico para adicionar novo nó e aresta para predict_query:

2. Atualize o arquivo prompts.py

• Crie um prompt para previsão de guery em prompts.py:

3. Atualize o arquivo configuration.py

• Adicionar predict_next_question_prompt:

4. Atualize o arquivo state.py

• Adicione os seguintes atributos:

5. Execute novamente o grafo de recuperação.

• Digite a seguinte consulta de pesquisa novamente:

O sistema processará a entrada e preverá três perguntas relacionadas que os usuários podem fazer, conforme mostrado abaixo.

Conclusão

A integração do modelo do Retrieval Agent no LangGraph Studio e na CLI oferece vários benefícios importantes:

• Desenvolvimento acelerado: o modelo e as ferramentas de visualização simplificam a criação e a depuração de fluxos de trabalho de recuperação, reduzindo o tempo de desenvolvimento.

• Implantação perfeita: o suporte integrado para APIs e o dimensionamento automático garantem uma implantação tranquila em todos os ambientes.

• Atualizações fáceis: modificar fluxos de trabalho, adicionar novas funcionalidades e integrar nós adicionais é simples, facilitando o dimensionamento e o aprimoramento do processo de recuperação.

• Memória persistente: o sistema retém os estados e o conhecimento dos agentes, melhorando a consistência e a confiabilidade.

• Modelagem de fluxo de trabalho flexível: os desenvolvedores podem personalizar a lógica de recuperação e as regras de comunicação para casos de uso específicos.

• Interação e depuração em tempo real: a capacidade de interagir com agentes em execução permite testes eficientes e resolução de problemas.

Ao aproveitar esses recursos, as organizações podem criar sistemas de recuperação poderosos, eficientes e escaláveis que melhoram a acessibilidade dos dados e a experiência do usuário.

O código-fonte completo deste projeto está disponível no GitHub.

Sobre a Amazon Nova

O Amazon Nova é uma família de modelos de inteligência artificial da Amazon, disponível na plataforma Amazon Bedrock e projetada para oferecer alto desempenho e custo-benefício. Esses modelos operam com entradas de texto, imagem e vídeo, geram saídas textuais e são otimizados para diferentes necessidades de precisão, velocidade e custo.

Modelos principais do Amazon Nova

• Amazon Nova Micro: Focado exclusivamente em texto, este é um modelo rápido e econômico, ideal para tradução, raciocínio, preenchimento automático de código e resolução de problemas matemáticos. Sua geração ultrapassa 200 tokens por segundo, tornando-o ideal para aplicações que exigem respostas instantâneas.

• Amazon Nova Lite: modelo multimodal de baixo custo capaz de processar rapidamente imagens, vídeos e textos. Ele se destaca pela rapidez e precisão, sendo indicado para aplicações interativas e de alto volume onde o custo é um fator relevante.

• Amazon Nova Pro: A opção mais avançada, que combina alta precisão, velocidade e custo-benefício. Ideal para tarefas complexas como resumo de vídeos, perguntas e respostas, desenvolvimento de software e agentes de IA. Avaliações de especialistas atestam sua excelência na compreensão textual e visual, bem como sua capacidade de seguir instruções e executar fluxos de trabalho automatizados.

Os modelos Amazon Nova são adequados para uma variedade de aplicações, desde a criação de conteúdo e análise de dados até o desenvolvimento de software e a automação de processos com inteligência artificial.

A seguir, demonstraremos como usar os modelos do Amazon Nova em conjunto com o Elasticsearch para análise automatizada de avaliações de produtos.

O que faremos:

1. Crie um endpoint por meio da API de Inferência, integrando o Amazon Bedrock com o Elasticsearch.

2. Crie um pipeline usando o Processador de Inferência, que fará chamadas para o endpoint da API de Inferência.

3. Indexe as avaliações de produtos e gere automaticamente uma análise dessas avaliações usando o pipeline.

4. Analise os resultados da integração.

Criando um endpoint na API de inferência com Amazon Nova Lite

Primeiro, configuramos a API de Inferência para integrar o Amazon Bedrock com o Elasticsearch. Definimos o Amazon Nova Lite, id amazon.nova-lite-v1:0, como o modelo a ser utilizado, pois oferece um equilíbrio entre velocidade, precisão e custo.

Observação: você precisará de credenciais válidas para usar o Amazon Bedrock. Você pode consultar a documentação para obter as chaves de acesso aqui:

Criando o pipeline de análise de revisão

Agora, criamos um pipeline de processamento que usará o Processador de Inferência para executar uma solicitação de análise de revisão. Este comando enviará os dados da avaliação para o Amazon Nova Lite, que executará as seguintes ações:

• Classificação do sentimento (positivo, negativo ou neutro).

• Resumo da revisão.

• Geração de palavras-chave.

• Medição de autenticidade (autêntico | suspeito | genérico).

Avaliações de indexação

Agora, indexamos avaliações de produtos usando a API em lote. O pipeline criado anteriormente será aplicado automaticamente, adicionando a análise gerada pelo modelo Nova aos documentos indexados.

Consultar e analisar os resultados

Por fim, executamos uma consulta para ver como o modelo Amazon Nova Lite analisa e classifica as avaliações. Ao executar o comando GET products/_search, obtemos os documentos já enriquecidos com os campos gerados a partir do conteúdo da avaliação.

O modelo identifica o sentimento predominante (positivo, neutro ou negativo), gera resumos concisos, extrai palavras-chave relevantes e estima a autenticidade de cada avaliação. Esses campos ajudam a entender a opinião do cliente sem precisar ler o texto completo.

Para interpretar os resultados, analisamos:

• O sentimento indica a percepção geral do consumidor em relação ao produto.

• O resumo destaca os principais pontos mencionados.

• Palavras-chave, que podem ser usadas para agrupar avaliações semelhantes ou identificar padrões de feedback.

• Autenticidade, que indica se a avaliação parece confiável. Isso é útil para curadoria ou moderação.

Conclusão

A integração entre o Amazon Nova Lite e o Elasticsearch demonstrou como os modelos de linguagem podem transformar avaliações brutas em informações estruturadas e valiosas. Ao processar as avaliações por meio de um pipeline, conseguimos extrair automaticamente e de forma consistente informações sobre sentimento, autenticidade, resumos e palavras-chave.

Os resultados mostram que o modelo consegue compreender o contexto das avaliações, classificar as opiniões dos usuários e destacar os pontos mais relevantes de cada experiência. Isso cria um conjunto de dados muito mais rico que pode ser aproveitado para melhorar as capacidades de pesquisa.

O Model Context Protocol (MCP) torna isso possível. Ele conecta perfeitamente a IA conversacional com seus bancos de dados e APIs externas, transformando solicitações complexas em conversas naturais. Embora os LLMs modernos sejam ótimos para entender a linguagem, seu verdadeiro potencial é revelado quando integrados a sistemas do mundo real. O MCP preenche a lacuna entre eles, tornando a interação de dados mais intuitiva e eficiente.

Nesta postagem, exploraremos:

• Arquitetura MCP – Como funciona nos bastidores

• Benefícios de um servidor MCP conectado ao Elasticsearch

• Construindo um servidor MCP com tecnologia Elasticsearch

Tempos emocionantes estão por vir! A integração do MCP com sua pilha Elastic transforma a maneira como você interage com as informações, tornando consultas complexas tão intuitivas quanto conversas cotidianas.

Protocolo de Contexto do Modelo

O Model Context Protocol (MCP), desenvolvido pela Anthropic, é um padrão aberto que conecta modelos de IA a fontes de dados externas por meio de canais bidirecionais seguros. Ele resolve uma grande limitação da IA: acesso em tempo real a sistemas externos, preservando o contexto da conversa.

Arquitetura MCP

A arquitetura do Protocolo de Contexto do Modelo consiste em dois componentes principais:

• Clientes MCP – Assistentes de IA e chatbots que solicitam informações ou executam tarefas em nome dos usuários.

• Servidores MCP – Repositórios de dados, mecanismos de busca e APIs que recuperam informações relevantes ou executam ações solicitadas (por exemplo, chamar APIs externas).

Os servidores MCP expõem quatro funcionalidades principais aos clientes:

• Recursos - Dados estruturados, documentos e conteúdo que podem ser recuperados e usados como contexto para interações de LLM. Isso permite que assistentes de IA acessem informações relevantes de bancos de dados, índices de pesquisa ou outras fontes.

• Ferramentas - Funções executáveis que permitem que os LLMs interajam com sistemas externos, realizem cálculos ou tomem ações no mundo real. Essas ferramentas estendem os recursos de IA além da geração de texto, permitindo que os assistentes acionem fluxos de trabalho, chamem APIs ou manipulem dados dinamicamente.

• Prompts - Modelos de prompts e fluxos de trabalho reutilizáveis para padronizar e compartilhar interações comuns de LLM.

• Amostragem - Solicite conclusões de LLM por meio do cliente para permitir comportamentos de agente sofisticados, mantendo a segurança e a privacidade.

Servidor MCP + Elasticsearch

Os sistemas tradicionais de Recuperação-Geração Aumentada (RAG) recuperam documentos com base em consultas do usuário, mas o MCP vai um passo além: ele permite que agentes de IA construam e executem tarefas dinamicamente em tempo real. Isso permite que os usuários façam perguntas em linguagem natural como:

• "Mostre-me todos os pedidos acima de US$ 500 do mês passado."

• "Quais produtos receberam mais avaliações de 5 estrelas?"

E obtenha respostas instantâneas e precisas, sem precisar escrever uma única consulta.

O MCP consegue isso por meio de:

• Seleção dinâmica de ferramentas – Os agentes escolhem de forma inteligente as ferramentas certas expostas por meio de servidores MCP com base na intenção do usuário. LLMs “mais inteligentes” geralmente são melhores em selecionar as ferramentas certas com os argumentos apropriados com base no contexto.

• Comunicação bidirecional – Agentes e fontes de dados trocam informações fluidamente, refinando consultas conforme necessário (por exemplo, primeiro mapeie o índice de pesquisa e só então construa a consulta ES).

• Orquestração de múltiplas ferramentas – Os fluxos de trabalho podem aproveitar ferramentas de vários servidores MCP simultaneamente.

• Contexto persistente – Os agentes lembram interações anteriores, mantendo a continuidade entre as conversas.

Um servidor MCP conectado ao Elasticsearch desbloqueia uma poderosa arquitetura de recuperação em tempo real. Os agentes de IA podem explorar, consultar e analisar dados do Elasticsearch sob demanda. Seus dados podem ser pesquisados por meio de uma interface de bate-papo simples.

Além de apenas recuperar dados, o MCP possibilita ações. Ele se integra a outras ferramentas para acionar fluxos de trabalho, automatizar processos e fornecer insights aos sistemas de análise. Ao separar a pesquisa da execução, o MCP mantém os aplicativos com tecnologia de IA flexíveis, atualizados e perfeitamente integrados aos fluxos de trabalho do agente.

Prático: servidor MCP para conversar com seus dados do Elasticsearch

Para interagir com o Elasticsearch por meio de um servidor MCP, precisamos de pelo menos funções para:

• Recuperar índices

• Obter mapeamentos

• Realizar pesquisas usando o Query DSL do Elasticsearch

Nosso servidor é escrito em TypeScript e usaremos o SDK oficial do MCP TypeScript. Para configuração, recomendamos instalar o aplicativo Claude Desktop (a versão gratuita é suficiente), pois ele inclui um cliente MCP integrado. Nosso servidor MCP essencialmente expõe o cliente oficial do JavaScript Elasticsearch por meio de ferramentas MCP.

Vamos começar definindo o cliente Elasticsearch e o servidor MCP:

Usaremos as seguintes ferramentas de servidor MCP que podem interagir com o Elasticsearch:

• Listar índices (list_indices): esta ferramenta recupera todos os índices disponíveis do Elasticsearch, fornecendo detalhes como nome do índice, status de integridade e contagem de documentos.

• Obter mapeamentos (get_mappings): esta ferramenta busca os mapeamentos de campos para um índice especificado do Elasticsearch, ajudando os usuários a entender a estrutura e os tipos de dados dos documentos armazenados.

• Pesquisar (search): Esta ferramenta executa uma pesquisa no Elasticsearch usando um DSL de consulta fornecido. Ele habilita automaticamente destaques para campos de texto, facilitando a identificação de resultados de pesquisa relevantes.

A implementação completa do servidor Elasticsearch MCP está disponível no repositório elastic/mcp-server-elasticsearch .

Converse com seu índice

Vamos explorar como configurar o servidor Elasticsearch MCP para que você possa fazer perguntas em linguagem natural sobre seus dados, como "Encontrar todos os pedidos acima de US$ 500 do mês passado".

Configure seu aplicativo Claude Desktop

• Abra o aplicativo Claude Desktop

• Navegue até Configurações > Desenvolvedor > Servidores MCP

• Clique em "Editar configuração" e adicione esta configuração ao seu claude_desktop_config.json:

Observação: esta configuração utiliza o pacote npm @elastic/mcp-server-elasticsearch publicado pela Elastic. Se você quiser desenvolver localmente, poderá encontrar mais detalhes sobre como configurar o servidor Elasticsearch MCP aqui.

Preencha seu índice Elasticseach

• Você pode usar nossos dados de exemplo para preencher o índice de "pedidos" para esta demonstração

• Isso permitirá que você tente consultas como "Encontrar todos os pedidos acima de US$ 500 do mês passado"

Comece a usar

• Abra uma nova conversa no aplicativo Claude Desktop

• O servidor MCP se conectará automaticamente

• Comece a fazer perguntas sobre seus dados do Elasticsearch!

Confira esta demonstração para ver como é fácil consultar seus dados do Elasticsearch usando linguagem natural:

Como funciona?

Quando perguntado "Encontre todos os pedidos acima de US$ 500 do mês passado", o LLM reconhece a intenção de pesquisar o índice do Elasticsearch com restrições especificadas. Para realizar uma busca eficaz, o agente deve:

• Descubra o nome do índice: orders

• Entenda os mapeamentos do índice orders

• Crie o DSL de consulta compatível com mapeamentos de índice e, finalmente, execute a solicitação de pesquisa

Essa interação pode ser representada como:

Conclusão

O Model Context Protocol aprimora a maneira como você interage com os dados do Elasticsearch, permitindo conversas em linguagem natural em vez de consultas complexas. Ao unir recursos de IA com seus dados, o MCP cria um fluxo de trabalho mais intuitivo e eficiente que mantém o contexto em todas as suas interações.

O servidor Elasticsearch MCP está disponível como um pacote npm público (@elastic/mcp-server-elasticsearch), tornando a integração simples para desenvolvedores. Com configuração mínima, sua equipe pode começar a explorar dados, acionar fluxos de trabalho e obter insights por meio de conversas simples.

Pronto para experimentar isso você mesmo? Experimente o servidor Elasticsearch MCP hoje mesmo e comece a conversar com seus dados.

Como funciona o gasoduto multimodal RAG?

1. Coletando pistas → Imagens, áudio, textos e mapas de profundidade da cena do crime em Gotham.

2. Gerando embeddings → Cada arquivo é convertido em um vetor usando o modelo multimodal ImageBind.

3. Indexação no Elasticsearch → Os vetores são armazenados para recuperação eficiente.

4. Pesquisando por similaridade → Dada uma nova pista, os vetores mais semelhantes são recuperados.

5. O LLM analisa as evidências → Um modelo GPT-4 sintetiza a resposta e identifica o suspeito!

Tecnologias utilizadas

• ImageBind → Gera embeddings unificados para várias modalidades.

• Elasticsearch → Permite pesquisa vetorial rápida e eficiente.

• LLM (GPT-4, OpenAI) → Analisa as evidências e gera um relatório final.

Para quem é este blog?

• Usuários do Elastic interessados em pesquisa vetorial multimodal.

• Desenvolvedores que buscam entender o RAG Multimodal na prática.

• Qualquer pessoa em busca de soluções escaláveis para analisar dados de diversas fontes.

Pré-requisitos para RAG multimodal: Configurando o ambiente

Para resolver o crime em Gotham City, você precisa configurar seu ambiente tecnológico. Siga este guia passo a passo:

1. Requisitos técnicos

Componente

Especificação

Sistema Operacional

Linux, macOS ou Windows

Python

3.10 ou posterior

BATER

Mínimo de 8 GB (16 GB recomendado)

GPU

Opcional, mas recomendado para ImageBind

2. Configurando o projeto

Todos os materiais de investigação estão disponíveis no GitHub, e usaremos o Jupyter Notebook (Google Colab) para esta experiência interativa de resolução de crimes. Siga estes passos para começar:

Configurando com o Jupyter Notebook (Google Colab)

1. Acesse o notebook

• Abra nosso notebook Google Colab pronto para uso: Multimodal RAG com Elasticsearch.

• Este caderno contém todo o código e explicações que você precisa acompanhar.

2. Clone o repositório

3. Instalar dependências

4. Configurar credenciais

Observação: o modelo ImageBind (~2 GB) será baixado automaticamente na primeira execução.

Agora que tudo está pronto, vamos nos aprofundar nos detalhes e solucionar o crime!

Introdução: O crime em Gotham City

Em uma noite chuvosa em Gotham City, um crime chocante abala a cidade. O comissário Gordon precisa da sua ajuda para desvendar o mistério. As pistas estão espalhadas em diferentes formatos: imagens borradas, áudio misterioso, textos criptografados e até mapas de profundidade. Você está pronto para usar a tecnologia de IA mais avançada para resolver o caso?

Neste blog, você será guiado passo a passo pela construção de um sistema RAG (Recuperação-Geração Aumentada) multimodal que unifica diferentes tipos de dados (imagens, áudio, textos e mapas de profundidade) em um único espaço de busca. Usaremos o ImageBind para gerar embeddings multimodais, o Elasticsearch para armazenar e recuperar esses embeddings e um Large Language Model (LLM) para analisar as evidências e gerar um relatório final.

Fundamentos: Arquitetura RAG multimodal

O que é um RAG multimodal?

A ascensão da Geração Aumentada de Recuperação (RAG) Multimodal está revolucionando a maneira como interagimos com modelos de IA. Tradicionalmente, os sistemas RAG trabalham exclusivamente com texto, recuperando informações relevantes de bancos de dados antes de gerar respostas. No entanto, o mundo não se limita ao texto: imagens, vídeos e áudio também contêm conhecimento valioso. É por isso que as arquiteturas multimodais estão ganhando destaque, permitindo que os sistemas de IA combinem informações de diferentes formatos para respostas mais ricas e precisas.

Três abordagens principais para RAG multimodal

Para implementar um RAG multimodal, três estratégias são comumente usadas. Cada abordagem tem suas próprias vantagens e limitações, dependendo do caso de uso:

1. Espaço vetorial compartilhado

Dados de diferentes modalidades são mapeados em um espaço vetorial comum usando modelos multimodais como o ImageBind. Isso permite que consultas de texto recuperem imagens, vídeos e áudio sem conversão de formato explícita.

Vantagens:

• Permite recuperação multimodal sem exigir conversão de formato explícita.

• Fornece uma integração fluida entre diferentes modalidades, permitindo recuperação direta de texto, imagem, áudio e vídeo.

• Escalável para diversos tipos de dados, o que o torna útil para aplicações de recuperação em larga escala.

Desvantagens:

• O treinamento requer grandes conjuntos de dados multimodais, que podem nem sempre estar disponíveis.

• O espaço de incorporação compartilhado pode introduzir deriva semântica, onde as relações entre modalidades não são perfeitamente preservadas.

• O viés em modelos multimodais pode afetar a precisão da recuperação, dependendo da distribuição do conjunto de dados.

2. Modalidade de aterramento único

Todas as modalidades são convertidas em um único formato, geralmente texto, antes da recuperação. Por exemplo, as imagens são descritas por meio de legendas geradas automaticamente e o áudio é transcrito em texto.

Vantagens:

• Simplifica a recuperação, pois tudo é convertido em uma representação de texto uniforme.

• Funciona bem com mecanismos de busca baseados em texto existentes, eliminando a necessidade de infraestrutura multimodal especializada.

• Pode melhorar a interpretabilidade, pois os resultados recuperados estão em um formato legível por humanos.

Desvantagens:

• Perda de informações: certos detalhes (por exemplo, relações espaciais em imagens, tom em áudio) podem não ser totalmente capturados em descrições de texto.

• Depende da qualidade da legenda/transcrição: erros em anotações automáticas podem reduzir a eficácia da recuperação.

• Não é ideal para consultas puramente visuais ou auditivas, pois o processo de conversão pode remover contexto essencial.

3. Recuperação separada

Mantém modelos distintos para cada modalidade. O sistema realiza pesquisas separadas para cada tipo de dado e depois mescla os resultados.

Vantagens:

• Permite otimização personalizada por modalidade, melhorando a precisão da recuperação para cada tipo de dado.

• Menor dependência de modelos multimodais complexos, facilitando a integração de sistemas de recuperação existentes.

• Fornece controle refinado sobre classificação e reclassificação, pois resultados de diferentes modalidades podem ser combinados dinamicamente.

Desvantagens:

• Requer fusão de resultados, tornando o processo de recuperação e classificação mais complexo.

• Pode gerar respostas inconsistentes se modalidades diferentes retornarem informações conflitantes.

• Maior custo computacional , pois são realizadas buscas independentes para cada modalidade, aumentando o tempo de processamento.

Nossa escolha: Espaço vetorial compartilhado com ImageBind

Dentre essas abordagens, escolhemos o espaço vetorial compartilhado, uma estratégia que se alinha perfeitamente com a necessidade de buscas multimodais eficientes. Nossa implementação é baseada no ImageBind, um modelo capaz de representar múltiplas modalidades (texto, imagem, áudio e vídeo) em um espaço vetorial comum. Isso nos permite:

• Realize pesquisas multimodais entre diferentes formatos de mídia sem precisar converter tudo em texto.

• Use incorporações altamente expressivas para capturar relacionamentos entre diferentes modalidades.

• Garanta escalabilidade e eficiência, armazenando embeddings otimizados para recuperação rápida no Elasticsearch.

Ao adotar essa abordagem, construímos um pipeline de pesquisa multimodal robusto, onde uma consulta de texto pode recuperar imagens ou áudio diretamente sem pré-processamento adicional. Este método expande aplicações práticas de busca inteligente em grandes repositórios para sistemas avançados de recomendação multimodal.

A figura a seguir ilustra o fluxo de dados dentro do pipeline RAG multimodal, destacando o processo de indexação, recuperação e geração de resposta com base em dados multimodais:

Como funciona o espaço de incorporação?

Tradicionalmente, as incorporações de texto vêm de modelos de linguagem (por exemplo, BERT, GPT). Agora, com modelos multimodais nativos como o ImageBind da Meta AI, temos uma estrutura que gera vetores para múltiplas modalidades:

• Texto: Frases e parágrafos são transformados em vetores da mesma dimensão.

• Imagens (visão): Os pixels são mapeados no mesmo espaço dimensional usado para texto.

• Áudio: Os sinais sonoros são convertidos em incorporações comparáveis a imagens e texto.

• Mapas de profundidade: os dados de profundidade são processados e também resultam em vetores.

Assim, qualquer pista (texto, imagem, áudio, profundidade) pode ser comparada a qualquer outra usando métricas de similaridade vetorial, como similaridade de cosseno. Se uma amostra de áudio de riso e uma imagem do rosto de um suspeito estiverem “próximas” neste espaço, podemos inferir alguma correlação (por exemplo, a mesma identidade).

Etapa 1 - Coletando pistas da cena do crime

Antes de analisar as evidências, precisamos coletá-las. O crime em Gotham deixou rastros que podem estar escondidos em imagens, áudios, textos e até mesmo dados de profundidade. Vamos organizar essas pistas para alimentá-las em nosso sistema.

O que temos?

O Comissário Gordon nos enviou os seguintes arquivos contendo evidências coletadas na cena do crime em quatro modalidades diferentes:

Descrição e modalidade da pista

a) Imagens (2 fotos)

• crime_scene1.jpg, crime_scene2.jpg → Fotos tiradas da cena do crime. Mostra vestígios suspeitos no chão.

• suspect_spotted.jpg → Imagem de câmera de segurança mostrando uma silhueta fugindo do local.

b) Áudio (1 gravação)

• joker_laugh.wav → Um microfone perto da cena do crime captou uma risada sinistra.

c) Texto (1 mensagem)

• Riddle.txt, note2.txt → Algumas notas misteriosas foram encontradas no local, possivelmente deixadas pelo criminoso.

d) Profundidade (1 mapa de profundidade)

• depth_suspect.png → Uma câmera de segurança com sensor de profundidade capturou um suspeito em um beco próximo.

• jdancing-depth.png → Uma câmera de segurança com sensor de profundidade capturou um suspeito descendo a estação de metrô.

Essas evidências estão em formatos diferentes e não podem ser analisadas diretamente da mesma maneira. Precisamos transformá-los em embeddings — vetores numéricos que permitirão comparação entre modais.

Organização de arquivos

Antes de iniciar o processamento, precisamos garantir que todas as pistas estejam organizadas corretamente no diretório data/ para que o pipeline funcione sem problemas.

Estrutura de diretório esperada:

Código para verificar a organização da pista

Antes de prosseguir, vamos garantir que todos os arquivos necessários estejam no local correto.

Executando o arquivo

Saída esperada (se todos os arquivos estiverem corretos):

Saída esperada (se algum arquivo estiver faltando):

Este script ajuda a evitar erros antes de começarmos a gerar embeddings e indexá-los no Elasticsearch.

Etapa 2 - Organizando as evidências

Gerando embeddings com ImageBind

Para unificar as pistas, precisamos transformá-las em embeddings — representações vetoriais que capturam o significado de cada modalidade. Usaremos o ImageBind, um modelo da Meta AI que gera embeddings para diferentes tipos de dados (imagens, áudio, texto e mapas de profundidade) dentro de um espaço vetorial compartilhado.

Como o ImageBind funciona?

Para comparar diferentes tipos de evidências (imagens, áudio, texto e mapas de profundidade), precisamos transformá-los em vetores numéricos usando o ImageBind. Este modelo permite que qualquer tipo de entrada seja convertido no mesmo formato de incorporação, permitindo pesquisas entre modalidades.

Abaixo está um código otimizado (src/embedding_generator.py) para gerar embeddings para qualquer tipo de entrada usando os processadores apropriados para cada modalidade:

Um tensor é uma estrutura de dados fundamental em aprendizado de máquina e aprendizado profundo, especialmente ao trabalhar com modelos como o ImageBind. No nosso contexto:

Aqui, o tensor representa os dados de entrada (imagem, áudio ou texto) convertidos em um formato matemático que o modelo pode processar. Especificamente:

• Para imagens: O tensor representa a imagem como uma matriz multidimensional de valores numéricos (pixels organizados por altura, largura e canais de cor).

• Para áudio: O tensor representa ondas sonoras como uma sequência de amplitudes ao longo do tempo.

• Para texto: O tensor representa palavras ou tokens como vetores numéricos.

Testando a geração de incorporação:

Vamos testar nossa geração de incorporação com o código a seguir. Salve-o em 02-stage/test_embedding_generation.py e execute-o com este comando:

Saída esperada:

Agora, a imagem foi transformada em um vetor de 1024 dimensões.

Etapa 3 - Armazenamento e pesquisa no Elasticsearch

Agora que geramos os embeddings para as evidências, precisamos armazená-los em um banco de dados vetorial para permitir pesquisas eficientes. Para isso, usaremos o Elasticsearch, que suporta vetores densos (dense_vector) e permite buscas por similaridade.

Esta etapa consiste em dois processos principais:

• Indexando os embeddings → Armazena os vetores gerados no Elasticsearch.

• Pesquisa de similaridade → Recupera os registros mais semelhantes a uma nova evidência.

Indexando as evidências no Elasticsearch

Cada evidência processada pelo ImageBind (imagem, áudio, texto ou profundidade) é convertida em um vetor de 1024 dimensões. Precisamos armazenar esses vetores no Elasticsearch para permitir pesquisas futuras.

O código a seguir (src/elastic_manager.py) cria um índice no Elasticsearch e configura o mapeamento para armazenar os embeddings.

Executando a indexação

Agora, vamos indexar uma evidência para testar o processo.

Saída esperada no Elasticsearch (resumo do documento indexado):

Para indexar todas as evidências multimodais, execute o seguinte comando Python:

Agora, as evidências são armazenadas no Elasticsearch e estão prontas para serem recuperadas quando necessário.

Verificando o processo de indexação

Depois de executar o script de indexação, vamos verificar se todas as nossas evidências foram armazenadas corretamente no Elasticsearch. Você pode usar as ferramentas de desenvolvimento do Kibana para executar algumas consultas de verificação:

1. Primeiro, verifique se o índice foi criado:

2. Em seguida, verifique a contagem de documentos por modalidade:

3. Por fim, examine a estrutura do documento indexado:

Resultados esperados:

• Um índice chamado `multimodal_content` deve existir.

• Cerca de 7 documentos distribuídos em diferentes modalidades (visão, áudio, texto, profundidade).

• Cada documento deve conter: campos de incorporação, modalidade, descrição, metadados e content_path.

Esta etapa de verificação garante que nosso banco de dados de evidências esteja configurado corretamente antes de prosseguirmos com as pesquisas de similaridade.

Procurando evidências semelhantes no Elasticsearch

Agora que as evidências foram indexadas, podemos realizar pesquisas para encontrar os registros mais semelhantes a uma nova pista. Esta pesquisa usa similaridade vetorial para retornar os registros mais próximos no espaço de incorporação.

O código a seguir realiza essa pesquisa.

Testando a pesquisa - Usando áudio como consulta para resultados multimodais

Agora, vamos testar a busca por evidências usando um arquivo de áudio suspeito. Precisamos gerar um embedding para o arquivo da mesma maneira e procurar por embeddings semelhantes:

Saída esperada no terminal:

Agora, podemos analisar as evidências recuperadas e determinar sua relevância para o caso.

Além do áudio - Explorando pesquisas multimodais

Invertendo os papéis: Qualquer modalidade pode ser uma "pergunta"

Em nosso sistema RAG multimodal , cada modalidade é uma consulta de pesquisa potencial. Vamos além do exemplo de áudio e explorar como outros tipos de dados podem iniciar investigações.

1. Busca por texto (decifrando a nota do criminoso)

Cenário: Você encontrou uma mensagem de texto criptografada e quer encontrar evidências relacionadas.

Resultados esperados:

2. Busca de imagens (rastreamento da cena suspeita do crime)

Cenário: Uma nova cena de crime (crime_scene2.jpg) precisa ser comparada com outras evidências.

Saída:

3. Busca de mapa de profundidade (busca 3D)

Cenário: Um mapa de profundidade (jdancing-depth.png) revela padrões de escape de imagem.

Saída

Por que isso importa?

Cada modalidade revela conexões únicas:

• Texto → Padrões linguísticos do suspeito.

• Imagens → Reconhecimento de locais e objetos.

• Profundidade → Reconstrução de cena 3D.

Agora, temos um banco de dados de evidências estruturado no Elasticsearch, o que nos permite armazenar e recuperar evidências multimodais de forma eficiente.

Resumo do que fizemos:

• Embeddings multimodais armazenados no Elasticsearch.

• Realizou pesquisas de similaridade, encontrando evidências relacionadas a novas pistas.

• Testou a pesquisa usando um arquivo de áudio suspeito, garantindo que o sistema funcionasse corretamente.

Próximo passo: Usaremos um LLM (Large Language Model) para analisar as evidências recuperadas e gerar um relatório final.

Etapa 4 - Conectando os pontos com o LLM

Agora que as evidências foram indexadas no Elasticsearch e podem ser recuperadas por similaridade, precisamos de um LLM (Large Language Model) para analisá- las e gerar um relatório final para enviar ao Comissário Gordon. O LLM será responsável por identificar padrões, conectar pistas e sugerir um possível suspeito com base nas evidências recuperadas.

Para esta tarefa, usaremos o GPT-4 Turbo, formulando um prompt detalhado para que o modelo possa interpretar os resultados de forma eficiente.

Integração LLM

Para integrar o LLM em nosso sistema, criamos a classe LLMAnalyzer (src/llm_analyzer.py), que recebe as evidências recuperadas do Elasticsearch e gera um relatório forense usando essas evidências como contexto de prompt.

Configuração de temperatura na análise LLM:

Para nosso sistema de análise forense, usamos uma temperatura moderada de 0,5. Este cenário equilibrado foi escolhido porque:

• Representa um meio termo entre saídas determinísticas (muito rígidas) e altamente aleatórias;

• Em 0,5, o modelo mantém estrutura suficiente para fornecer conclusões forenses lógicas e justificáveis;

• Essa configuração permite que o modelo identifique padrões e faça conexões, permanecendo dentro de parâmetros razoáveis de análise forense;

• Ele equilibra a necessidade de resultados consistentes e confiáveis com a capacidade de gerar análises criteriosas.

Essa configuração de temperatura moderada ajuda a garantir que nossa análise forense seja confiável e criteriosa, evitando conclusões excessivamente rígidas e especulativas.

Executando a análise de evidências

Agora que temos a integração do LLM, precisamos de um script que conecte todos os componentes do sistema. Este script irá:

• Pesquise evidências semelhantes no Elasticsearch.

• Analise as evidências recuperadas usando o LLM para gerar um relatório final.

Código: Script de análise de evidências

Saída esperada do LLM

Conclusão: Caso resolvido

Com todas as pistas reunidas e analisadas, o sistema Multimodal RAG identificou um suspeito: o Coringa.

Ao combinar imagens, áudio, texto e mapas de profundidade em um espaço vetorial compartilhado usando o ImageBind, o sistema foi capaz de detectar conexões que seriam impossíveis de identificar manualmente. O Elasticsearch garantiu buscas rápidas e eficientes, enquanto o LLM sintetizou as evidências em um relatório claro e conclusivo.

No entanto, o verdadeiro poder deste sistema vai além de Gotham City. A arquitetura Multimodal RAG abre portas para inúmeras aplicações do mundo real:

• Vigilância urbana: Identificação de suspeitos com base em imagens, áudio e dados de sensores.

• Análise forense: Correlacionando evidências de múltiplas fontes para solucionar crimes complexos.

• Recomendação multimídia: Criação de sistemas de recomendação que entendam contextos multimodais (por exemplo, sugerir músicas com base em imagens ou texto).

• Tendências de mídia social: detectando tópicos de tendência em diferentes formatos de dados.

Agora que você aprendeu a construir um sistema RAG multimodal, por que não testá-lo com suas próprias dicas?

Compartilhe suas descobertas conosco e ajude a comunidade a avançar no campo da IA multimodal!

Agradecimentos especiais

Gostaria de agradecer a Adrian Cole por sua valiosa contribuição e revisão durante o processo de definição da arquitetura de implantação deste código.

Referências

• Construir um sistema de recuperação de imagens multimodal usando pesquisa KNN e incorporações CLIP

• Pesquisa de k-vizinho mais próximo (kNN)

• Documentação oficial do PyTorch sobre tensores

• ImageBind: uma nova maneira de 'conectar' a IA através dos sentidos

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

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

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

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

Pré-requisitos

1. Elasticsearch 8.17

2. Kibana 8.17

3. Python

Etapas

1. Configurando o servidor Ollama LLM

2. Criando mapeamentos

3. Indexação de dados

4. Fazendo perguntas usando o Playground

Configurando o servidor Ollama LLM

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

• Baixe e execute o Ollama.

• Use o ngrok para acessar seu servidor web local que hospeda o Ollama pela internet

Baixe e execute o Ollama

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

O que produzirá:

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

Vamos fazer uma pergunta:

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

Esta é a resposta que obtivemos:

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

Exponha o endpoint à internet usando o ngrok

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

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

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

Executar este comando retornará um link público que funcionará enquanto o ngrok e o servidor Ollama forem executados localmente.

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

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

A resposta deve ser semelhante à anterior.

Criando mapeamentos

Ponto final ELSER

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

Para este exemplo, vamos imaginar que você tem uma farmácia que vende dois tipos de medicamentos:

• Medicamentos que exigem receita médica.

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

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

O LLM deve interpretar esse campo, então estes são os mapeamentos de dados que usaremos:

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

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

Indexação de dados

Agora, vamos indexar os dados usando a API _bulk.

Resposta.

Fazendo perguntas usando o Playground

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

Conectando o LLM local ao Playground

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

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

Agora podemos começar a configurar o conector OpenAI.

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

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

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

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

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

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

Como esperado, obtivemos a resposta correta.

Próximas etapas

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

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

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

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

Para que funcione com o Ollama, você precisa alterar o cliente OpenAI para se conectar ao servidor Ollama em vez do servidor OpenAI. Você pode encontrar a lista completa de exemplos do OpenAI e endpoints compatíveis aqui.

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

Vamos adicionar nossa pergunta: Posso comprar Clonazepam sem receita? Para a consulta do Elasticsearch:

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

Agora vamos executar o comando

pip install -qU elasticsearch openai

python main.py

Você deverá ver algo assim:

Conclusão

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

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

Aqui está um diagrama do que configuraremos neste tutorial:

Configurando a inferência local com Ollama

Ollama é uma excelente maneira de testar rapidamente um conjunto selecionado de modelos open source para inferência local e é uma ferramenta popular entre desenvolvedores de IA.

Executando Ollama bare metal

Uma instalação local no Mac, Linux ou Windows é a maneira mais fácil de aproveitar qualquer capacidade de GPU local que você possa ter, principalmente para aqueles com chips Apple da série M. Depois de ter o Ollama instalado, você pode baixar e executar o DeepSeek R1 com o seguinte comando.

Talvez seja bom ajustar o tamanho do parâmetro para que ele se adeque ao seu hardware. Os tamanhos disponíveis podem ser encontrados aqui.

Você pode conversar com o modelo no terminal, mas o modelo permanece em execução quando você pressiona Ctrl+d para sair do comando ou digita "/bye". Para ver o modelo ainda em execução, digite:

Executando Ollama em um container

Como alternativa, a maneira mais rápida de executar o Ollama é utilizando um mecanismo de container como o Docker. Usar a GPU da sua máquina local nem sempre é tão simples, dependendo do seu ambiente, mas obter uma configuração de teste rápida não é difícil, desde que o container tenha a RAM e o armazenamento adequados aos modelos de vários GB.

Colocar o Ollama em execução no Docker é tão fácil quanto executar:

Isso cria um diretório chamado "ollama" no diretório atual e o monta dentro do container para armazenar a configuração do Ollama e também os modelos. Dependendo do número de parâmetros usados, eles podem variar de alguns GBs a dezenas de GBs. Portanto, certifique-se de escolher um volume com espaço livre suficiente.

Observação: se você tiver uma GPU Nvidia em sua máquina, certifique-se de instalar o Nvidia container toolkit e adicionar "--gpus=all" ao comando docker executar acima.

Assim que o container do Ollama estiver em execução na sua máquina, você pode puxar um modelo como o deepseek-r1 com:

Semelhante à abordagem de máquinas físicas, talvez você queira ajustar o tamanho do parâmetro para algo que se adeque ao seu hardware. Os tamanhos disponíveis podem ser encontrados em https://ollama.com/library/deepseek-r1.

Assim que o modelo terminar de ser puxado, você pode digitar “/bye” para sair das instruções. Para confirmar que o modelo ainda está em execução:

Testando nossa inferência local com um curl

Para testar a inferência local com curl, você pode executar o seguinte comando. Estamos usando stream:false para que possamos ler facilmente a resposta narrativa JSON:

Testando o Ollama “compatível com OpenAI” e instruções RAG

Convenientemente, o Ollama também oferece um endpoint REST que imita o comportamento do OpenAI para compatibilidade com uma ampla gama de ferramentas, incluindo o Kibana.

Testar essas instruções mais complexas resulta em um conteúdo que possui uma seção <think>, onde o modelo foi treinado para raciocinar sobre o problema.

Conectando Ollama ao Kibana

Uma excelente maneira de usar o Elasticsearch é o script de desenvolvimento "start-local".

Certifique-se de que seu Kibana e Elasticsearch consigam acessar seu Ollama na rede. Se você estiver usando uma configuração de container local do Elastic stack, isso pode significar substituir "localhost" por "host.docker.internal". ou “host.containers.internal” para obter um caminho de rede para a máquina hospedada.

No Kibana, navegue até Stack Management > Alerts and Insights > Connectors.

O que fazer se você vir que este é um aviso comum de configuração

Você precisará garantir que o xpack.encryptedSavedObjects.encryptionKey esteja configurado corretamente. Esta é uma etapa comumente esquecida ao executar uma instalação local do Docker do Kibana, então listarei as etapas para corrigir na sintaxe do Docker.

Certifique-se de persistir seu diretório kibana/config para que as alterações sejam salvas quando o container for encerrado. Meus volumes de container do Kibana se parecem com isso em docker-compose.yml:

Agora você pode criar o repositório de chaves e inserir um valor para que as chaves do Connector não sejam armazenadas em texto simples.

Reinicie completamente todo o cluster para que as alterações entrem em vigor.

Criando o Conector

Na tela de configuração do conector (no Kibana, navegue até Stack Management > Alerts and Insights > Connectors), crie um conector e selecione o tipo "OpenAI".

Configure o conector com as seguintes definições

• Nome do conector: Deepseek (Ollama)

• Selecione um provedor OpenAI: outro (Serviço Compatível com OpenAI)

• URL: http://localhost:11434/v1/chat/completions

  • Ajuste o caminho correto para o seu Ollama. Lembre-se de substituir host.docker.internal ou equivalente se estiver chamando de dentro de um container.

• Modelo padrão: deepseek-r1:7b

• Chave de API: invente algo, uma entrada é necessária, mas o valor não importa

Observe que testar um conector personalizado para Ollama na configuração do conector está atualmente com problemas na versão 8.17, mas foi corrigido na próxima versão 8.18 do Kibana.

Nosso conector é assim:

Inserindo dados de vetores incorporados no Elasticsearch

Se você já estiver familiarizado com o Playground e tiver os dados configurados, pode pular para a etapa do Playground abaixo. Mas, se precisar de alguns dados de teste rápidos, precisaremos garantir que nossas API de inferência estejam configuradas. A partir da versão 8.17, as alocações de machine learning são dinâmicas, portanto, para baixar e ativar o vetor denso multilíngue e5, precisaremos apenas executar o seguinte nas ferramentas de desenvolvimento do Kibana.

Se você ainda não o fez, isso acionará o download do modelo e5 dos repositórios de modelos da Elastic.

Em seguida, vamos carregar um livro de domínio público como nosso contexto RAG. Aqui está um lugar para baixar “Alice’s Adventures in Wonderland” do Projeto Gutenberg: link. Salve como arquivo .txt.

Navegue até Elasticsearch > Home > Carregar um arquivo

Selecione ou arraste e solte seu arquivo de texto e clique no botão "Importar".

Na tela “Import data” (Importar dados), selecione a guia “Advanced” (Avançado) e defina o nome do índice como “book_alice”.

Selecione a opção “Add additional campo” (Adicionar campo adicional), que fica logo abaixo de “Automatically created campos” (Campos criados automaticamente). Selecione “Adicionar campo de texto semântico” e altere o endpoint de inferência para “.multilingual-e5-small-elasticsearch”. Selecione Add e, em seguida, Import.

Quando o carregamento e a inferência estiverem concluídos, estaremos prontos para ir para o Playground.

Testando o RAG no Playground

Navegue até Elasticsearch > Playground no Kibana.

Na tela do playground, você verá uma marca de visto verde e “LLM Connected” para indicar que um conector existe. Este é o conector Ollama que acabamos de criar acima. Um guia mais longo para o Playground pode ser encontrado aqui.

Clique na opção azul Add data sources (Adicionar fontes de dados) e selecione o índice book_alice que já criamos ou outro índice que você já tenha configurado e que utilize API de inferência para embeddings.

O Deepseek é um modelo de cadeia de pensamento com características fortes de alinhamento. Isso é tanto bom quanto ruim do ponto de vista do RAG. O treinamento em cadeia de pensamento pode ajudar o Deepseek a racionalizar afirmações aparentemente contraditórias nas citações, mas o forte alinhamento com o conhecimento do treinamento pode fazer com que ele prefira sua própria versão dos fatos mundiais em vez da nossa base contextual. Embora bem-intencionado, esse forte alinhamento é conhecido por dificultar a instrução dos LLMs ao discutir tópicos em que nosso conhecimento particular é limitado ou não está bem representado no conjunto de dados de treinamento.

Na nossa configuração do Playground, inserimos as seguintes instruções do sistema: "Você é um assistente para tarefas de resposta a perguntas usando passagens de texto relevantes do livro Alice no País das Maravilhas" e aceitamos os outros padrões.

À pergunta “Quem estava na festa do chá?”, obtemos a resposta: “Resposta: A Lebre de Março, o Chapeleiro e o Arganaz estavam na festa do chá. [Citação: posições 1 e 2]", o que está correto.

Podemos ver nas tags <think> que o Deepseek definitivamente ponderou o conteúdo das citações para responder às perguntas.

Testando as limitações de alinhamento

Vamos criar um caso intelectualmente desafiador para o Deepseek como um teste. Criaremos um índice de teorias da conspiração que os dados de treinamento do Deepseek sabem que não são verdadeiras.

Nas Dev Tools do Kibana, vamos criar o seguinte índice e dados:

Essas teorias da conspiração serão nosso fundamento para o LLM. Apesar de inserir instruções agressivas no sistema, o Deepseek não aceitará nossa versão dos fatos. Se estivéssemos em uma situação em que soubéssemos que nossos dados privados eram mais confiáveis, fundamentados ou alinhados às necessidades de nossa organização, isso não seria aceitável:

Para a pergunta do teste "os pássaros são reais?" (explicação conheça seu meme) obtemos a resposta "No contexto fornecido, os pássaros não são considerados reais, mas na realidade, eles são animais reais." [Contexto: posição 1]. Este teste prova que o DeepSeek R1 é poderoso, mesmo no nível de parâmetro 7B... no entanto, pode não ser a melhor escolha para RAG, dependendo do nosso conjunto de dados.

Então, o que aprendemos?

Em resumo:

• Executar modelos localmente em ferramentas como o Ollama é uma ótima opção para dar uma olhada no comportamento do modelo.

• O DeepSeek R1 é um modelo de raciocínio, o que significa que tem vantagens e desvantagens para casos de uso como RAG.

• O Playground é capaz de se conectar a frameworks de hospedagem de inferência, como Ollama, por meio de uma REST API semelhante à OpenAI, que está se tornando um padrão de fato nesta era inicial da hospedagem de IA.

De modo geral, estamos impressionados com o quanto o RAG "air gapped" local evoluiu. As ferramentas do Elasticsearch, do Kibana e os modelos de pesos abertos disponíveis avançaram significativamente desde que escrevemos pela primeira vez sobre buscas com IA que priorizam privacidade, em 2023.

A busca facetada é uma ferramenta poderosa em plataformas de comércio eletrônico. Isso ajuda a organizar e refinar os resultados da pesquisa com base nas características dos itens exibidos. Embora frequentemente confundidos com filtros, os facets funcionam de maneira diferente. Os filtros são atributos fixos, definidos por informações sempre presentes no índice, como a categoria ou o formato de um produto. As facetas, por outro lado, são dinâmicas e geradas a partir dos resultados retornados pela pesquisa executada.

Imagine um catálogo de roupas: campos como "categoria" (por exemplo, camisetas, calças) ou "gênero" (por exemplo, masculino, feminino) são filtros que ajudam a refinar os resultados. As facetas, no entanto, refletem características específicas dos produtos que aparecem nos resultados, como cores comuns, tamanhos disponíveis ou materiais. Isso permite uma experiência de busca mais adaptável e contextual.

Abaixo, você encontrará uma imagem onde interagimos com uma faceta e podemos ver os resultados da pesquisa filtrados por ela.

Como a IA pode aprimorar a geração de facetas

A Inteligência Artificial é frequentemente associada à busca semântica e aos embeddings, mas e quanto às facetas? Como a IA pode ser utilizada para tornar os filtros mais úteis e específicos ao contexto de cada pesquisa?

Uma possibilidade intrigante é usar IA para criar novas categorizações que vão além das classificações tradicionais do índice. Ao analisar características específicas do conteúdo, essas novas categorias podem fornecer uma contextualização mais rica e precisa, tornando os aspectos mais relevantes e alinhados às necessidades dos usuários. Isso possibilita um refinamento mais significativo dos resultados em comparação com as categorias de documentos originais.

Como a IA pode refinar as classificações de filmes para melhores buscas

Vamos analisar os seguintes filmes, todos atualmente classificados no gênero Drama:

• Réquiem para um Sonho Resumo: As utopias induzidas por drogas de quatro pessoas de Coney Island são destruídas quando seus vícios se tornam profundos.

• Beleza Americana Resumo: Um pai suburbano sexualmente frustrado entra em crise de meia-idade após se apaixonar pela melhor amiga de sua filha.

• Good Will Hunting Resumo: Will Hunting, um zelador do MIT, tem um talento especial para matemática, mas precisa da ajuda de um psicólogo para encontrar um rumo na vida.

Essa classificação por gênero não capta as diferenças sutis ou os contextos únicos de cada filme. Ao utilizar inteligência artificial para analisar sinopses e temas centrais, podemos criar novas categorias que reflitam melhor o verdadeiro contexto de cada filme. Por exemplo:

• Réquiem para um Sonho - Nova categoria: "Vício e Dependência"

• Beleza Americana - Nova Categoria: "Crise da Meia-Idade"

• Gênio Indomável - Nova categoria: "Luta Intelectual"

Essas novas categorias tornam as buscas muito mais precisas, ao mesmo tempo que oferecem aos usuários filtros mais relevantes para refinar seus resultados. Essa abordagem é particularmente eficaz quando as categorias originais são muito genéricas, permitindo que os usuários encontrem exatamente o que procuram com maior facilidade.

Criando novas categorias com GPT-4: Exemplo de busca facetada

Neste exemplo, mostraremos como um modelo de IA pode ser usado para criar novas categorias de filmes que sejam mais precisas e alinhadas ao contexto de cada obra. Para demonstrar esse processo, utilizaremos o pipeline de simulação da Elastic juntamente com o serviço de inferência da OpenAI. Será criado um pipeline com vários processadores, incluindo o Processador de Scripts, que será responsável por criar o prompt a ser executado no Processador de Inferência, capaz de determinar as novas categorias. Os demais processadores serão utilizados para manipular os dados e os campos auxiliares gerados durante a execução do pipeline. Vale ressaltar que essa lógica também pode ser aplicada a outras ferramentas ou modelos semelhantes.

Primeiro, precisamos criar o endpoint de inferência, onde definimos o serviço como OpenAI, o token necessário para acessar o serviço e o modelo. Neste exemplo, estou usando gpt-4o-mini. Para obter mais detalhes sobre o serviço de inferência da OpenAI, clique aqui.

Com o endpoint criado, agora estamos prontos para usá-lo para criar as novas categorias. A seguir, apresentamos um fluxo de trabalho que gerencia todo o processo de manipulação de dados de documentos e geração de prompts. Explicarei detalhadamente a função de cada processador.

O primeiro processador será responsável por construir o prompt. É muito importante detalhar claramente as instruções para que a IA possa analisar e identificar os tópicos corretamente. Neste pedido, solicito dois tópicos com base na análise do título, da descrição e dos gêneros dos filmes.

O próximo pipeline é o pipeline de inferência, que receberá a solicitação e a enviará para o nosso endpoint generate_topics_ia . A resposta gerada pelo modelo será armazenada no campo de resultado.

Em seguida, temos 3 processadores usados para manipular a resposta e defini-la no campo de tópicos, além de remover os campos temporários que eu criei.

Ao executar esse pipeline, obteremos os seguintes resultados:

Note que temos novas categorias que estão mais relacionadas ao contexto dos filmes, embora algumas sejam inicialmente do mesmo gênero.

Agora podemos usar essas novas categorias e indexá-las juntamente com o documento. Dessa forma, ao gerar as facetas, além da categoria primária, temos subcategorias mais específicas que estão alinhadas com o contexto dos filmes.

Além disso, é possível vetorizar essas novas categorias e usá-las em buscas vetoriais. Isso significa que as novas categorias não servem apenas como filtros, mas também podem ser usadas para calcular similaridades semânticas com os termos de busca, aumentando ainda mais a relevância dos resultados apresentados.

Pipeline completo:

Conclusão

O uso de IA para aprimorar os filtros pode transformar a experiência de busca, tornando os resultados mais específicos e contextuais. Ao contrário das categorias fixas, que costumam ser amplas, as categorias geradas por IA podem refletir melhor o contexto. Por exemplo, ao reclassificar filmes, podemos capturar o contexto que as categorias primárias não abrangem, fornecendo agrupamentos muito mais relevantes.

Essas novas categorias podem ser adicionadas ao índice não apenas para aprimorar a filtragem por facetas, mas também para possibilitar buscas vetoriais. O resultado é uma experiência de busca mais eficiente, com filtros mais adequados ao contexto.

Referências

https://www.elastic.co/guide/en/elasticsearch/reference/current/infer-service-openai.html

https://www.elastic.co/guide/en/elasticsearch/reference/current/simulate-pipeline-api.html

https://www.elastic.co/guide/en/elasticsearch/reference/current/script-processor.html

O conector Semantic Kernel Elasticsearch Vector Store, pronto para uso, oferece suporte às abstrações de armazenamento vetorial do Semantic Kernel, o que facilita muito para os desenvolvedores a integração do Elasticsearch como um armazenamento vetorial durante a criação de agentes de IA.

O Elasticsearch possui uma base sólida na comunidade de código aberto e adotou recentemente a licença AGPL. Em conjunto com o Microsoft Semantic Kernel de código aberto, essas ferramentas oferecem uma solução poderosa e pronta para uso empresarial. Você pode começar localmente executando o Elasticsearch em poucos minutos executando este comando curl -fsSL https://elastic.co/start-local | sh (consulte start-local para obter detalhes) e migrar para versões hospedadas na nuvem ou auto-hospedadas à medida que coloca seus agentes de IA em produção.

Neste blog, veremos como usar o conector Elasticsearch Vector Store do Semantic Kernel ao utilizar o Semantic Kernel. Uma versão em Python do conector será disponibilizada futuramente.

Cenário geral: Construindo um aplicativo RAG com Semantic Kernel e Elasticsearch.

Na seção seguinte, analisaremos um exemplo. Em linhas gerais, estamos construindo um aplicativo RAG (Retrieval Augmented Generation) que recebe uma pergunta do usuário como entrada e retorna uma resposta. Usaremos o Azure OpenAI (também é possível usar um LLM local ) como LLM, o Elasticsearch como repositório de vetores e o Semantic Kernel (.NET) como framework para integrar todos os componentes.

Se você não estiver familiarizado com arquiteturas RAG, pode ter uma breve introdução com este artigo: https://www.elastic.co/search-labs/blog/retrieval-augmented-generation-rag.

A resposta é gerada pelo LLM, que é alimentado com contexto relevante para a pergunta, obtido do armazenamento de vetores do Elasticsearch. A resposta também inclui a fonte que foi usada como contexto pelo LLM.

Exemplo RAG

Neste exemplo específico, criamos um aplicativo que permite aos usuários fazer perguntas sobre hotéis armazenados em um banco de dados interno de hotéis. O usuário poderia, por exemplo... Pesquise um hotel específico com base em diferentes critérios ou solicite uma lista de hotéis.

Para o banco de dados de exemplo, geramos uma lista de hotéis contendo 100 entradas. O tamanho da amostra é intencionalmente pequeno para permitir que você experimente a demonstração do conector da maneira mais fácil possível. Em uma aplicação do mundo real, o conector Elasticsearch mostraria suas vantagens sobre outras opções, como a implementação de armazenamento vetorial `InMemory`, especialmente ao trabalhar com quantidades extremamente grandes de dados.

A aplicação de demonstração completa pode ser encontrada no repositório do conector de armazenamento vetorial do Elasticsearch.

Vamos começar adicionando os pacotes NuGet necessários e usando as diretivas ao nosso projeto:

Agora podemos criar nosso modelo de dados e fornecer a ele atributos específicos do Semantic Kernel para definir o esquema do modelo de armazenamento e algumas dicas para a pesquisa de texto:

Os atributos do esquema do modelo de armazenamento (`VectorStore*`) são os mais relevantes para o uso prático do conector Elasticsearch Vector Store, a saber:

• VectorStoreRecordKey Marcar uma propriedade em uma classe de registro como a chave sob a qual o registro é armazenado em um armazenamento vetorial.

• VectorStoreRecordData Marcar uma propriedade em uma classe de registro como 'dados'.

• VectorStoreRecordVector Para marcar uma propriedade em uma classe de registro como um vetor.

Todos esses atributos aceitam vários parâmetros opcionais que podem ser usados para personalizar ainda mais o modelo de armazenamento. No caso de VectorStoreRecordKey , por exemplo, é possível especificar uma função de distância diferente ou um tipo de índice diferente.

Os atributos de pesquisa de texto (TextSearch*) serão importantes na última etapa deste exemplo. Voltaremos a eles mais tarde.

Na próxima etapa, inicializamos o mecanismo do Kernel Semântico e obtemos referências aos serviços principais. Em uma aplicação do mundo real, a injeção de dependência deve ser usada em vez de acessar diretamente a coleção de serviços. O mesmo se aplica à configuração e aos segredos embutidos no código, que devem ser lidos usando um provedor de configuração :

O serviço vectorStoreCollection agora pode ser usado para criar a coleção e para inserir alguns registros de demonstração:

Isso demonstra como o Semantic Kernel reduz o uso de um armazenamento vetorial com toda a sua complexidade a algumas chamadas de método simples.

Nos bastidores, um novo índice é criado no Elasticsearch e todos os mapeamentos de propriedades necessários são criados. Nosso conjunto de dados é então mapeado de forma completamente transparente para o modelo de armazenamento e, finalmente, armazenado no índice. Abaixo, você pode ver como os mapeamentos aparecem no Elasticsearch.

As chamadas embeddings.GenerateEmbeddingsAsync() invocaram de forma transparente o serviço de geração de incorporações de IA do Azure configurado.

Ainda mais magia pode ser observada na última etapa desta demonstração.

Com apenas uma chamada para InvokePromptAsync, todas as seguintes operações são realizadas quando o usuário faz uma pergunta sobre os dados:

1. É gerado um elemento incorporado para a pergunta do usuário.

2. O repositório de vetores é pesquisado em busca de entradas relevantes.

3. Os resultados da consulta são inseridos em um modelo de prompt.

4. A consulta propriamente dita, na forma da mensagem final, é enviada ao serviço de autocompletar do chat por IA.

Lembra-se dos atributos TextSearch* que definimos anteriormente em nosso modelo de dados? Esses atributos nos permitem usar marcadores correspondentes em nosso modelo de prompt, que são preenchidos automaticamente com as informações de nossas entradas no repositório vetorial.

A resposta final à nossa pergunta "Por favor, mostre-me todos os hotéis que possuem um bar na cobertura" é a seguinte:

A resposta correta refere-se à seguinte entrada em nosso arquivo hotels.csv.

Este exemplo demonstra muito bem como a utilização do Microsoft Semantic Kernel permite uma redução significativa da complexidade através das suas abstrações bem concebidas, além de proporcionar um elevado nível de flexibilidade. Ao alterar uma única linha de código, por exemplo, o armazenamento de vetores ou os serviços de IA utilizados podem ser substituídos sem a necessidade de refatorar qualquer outra parte do código.

Ao mesmo tempo, a estrutura fornece um enorme conjunto de funcionalidades de alto nível, como a função `InvokePrompt`, ou o sistema de plugins de modelo ou de pesquisa.

A aplicação de demonstração completa pode ser encontrada no repositório do conector de armazenamento vetorial do Elasticsearch.

O que mais é possível fazer com o Elasticsearch?

• Novo mapeamento semantic_text do Elasticsearch: Simplificando a busca semântica

• Reclassificação semântica no Elasticsearch com retrievers

• Técnicas avançadas de RAG, parte 1: Processamento de dados

• Técnicas avançadas de RAG, parte 2: Consultas e testes

• Construindo o RAG com Llama 3 de código aberto e Elastic

• Um tutorial sobre como construir um agente local usando LangGraph, LLaMA3 e o armazenamento de vetores Elasticsearch do zero.

Elasticsearch e Semantic Kernel: O que vem a seguir?

• Mostramos como o armazenamento de vetores do Elasticsearch pode ser facilmente integrado ao Semantic Kernel durante a criação de aplicações GenAI em .NET. Fique atento para a integração com Python em breve.

• À medida que o Semantic Kernel cria abstrações para recursos de pesquisa avançados, como a pesquisa híbrida, a conexão com o Elasticsearch permitirá que os desenvolvedores .NET os implementem facilmente ao usar o Semantic Kernel.

• Inicie uma discussão com os LLMs implementando um ChatLanguageModel e um ChatMemory

• Manter o histórico do chat na memória para relembrar o contexto de uma discussão anterior com um LLM

Esta postagem do blog aborda como:

• Criar vetores incorporados a partir de exemplos de texto

• Armazene os vetores de incorporação no repositório de incorporações do Elasticsearch.

• Buscar vetores semelhantes

Criar incorporações

Para criar embeddings, precisamos definir um EmbeddingModel para usar. Por exemplo, podemos usar o mesmo modelo mistral que usamos na postagem anterior. Estava correndo com a lhama:

Um modelo é capaz de gerar vetores a partir de texto. Aqui podemos verificar o número de dimensões geradas pelo modelo:

Para gerar vetores a partir de um texto, podemos usar:

Ou, se também quisermos fornecer metadados para nos permitir filtrar por coisas como texto, preço, data de lançamento ou qualquer outra coisa, podemos usar Metadata.from(). Por exemplo, estamos adicionando aqui o nome do jogo como um campo de metadados:

Se você quiser executar este código, consulte a classe Step5EmbedddingsTest.java .

Adicionar o Elasticsearch para armazenar nossos vetores.

LangChain4j fornece um armazenamento de incorporação em memória. Isso é útil para executar testes simples:

Mas, obviamente, isso não funcionaria com conjuntos de dados muito maiores, porque esse armazenamento de dados guarda tudo na memória e não temos memória infinita em nossos servidores. Assim, poderíamos armazenar nossos embeddings no Elasticsearch, que é, por definição, "elástico" e pode ser dimensionado verticalmente e horizontalmente conforme a demanda de dados. Para isso, vamos adicionar o Elasticsearch ao nosso projeto:

Como você deve ter notado, também adicionamos o módulo Elasticsearch TestContainers ao projeto, para que possamos iniciar uma instância do Elasticsearch a partir de nossos testes:

Para usar o Elasticsearch como um armazenamento de dados incorporado, você "simplesmente" precisa trocar o armazenamento de dados em memória do LangChain4j pelo armazenamento de dados do Elasticsearch:

Isso armazenará seus vetores no Elasticsearch em um índice default . Você também pode alterar o nome do índice para algo mais significativo:

Se você quiser executar este código, consulte a classe Step6ElasticsearchEmbedddingsTest.java .

Buscar vetores semelhantes

Para buscar vetores semelhantes, primeiro precisamos transformar nossa pergunta em uma representação vetorial usando o mesmo modelo que usamos anteriormente. Já fizemos isso, então não é difícil fazer de novo. Note que, neste caso, não precisamos dos metadados:

Podemos construir uma solicitação de pesquisa com essa representação da nossa pergunta e pedir ao repositório de embeddings para encontrar os primeiros vetores principais:

Agora podemos iterar sobre os resultados e imprimir algumas informações, como o nome do jogo, que vem dos metadados, e a pontuação:

Como era de se esperar, isso nos dá "Out Run" como o primeiro sucesso:

Se você quiser executar este código, consulte a classe Step7SearchForVectorsTest.java .

Nos bastidores

A configuração padrão do Elasticsearch Embedding Store utiliza a consulta kNN aproximada nos bastidores.

Mas isso poderia ser alterado fornecendo uma configuração diferente (ElasticsearchConfigurationScript) da configuração padrão (ElasticsearchConfigurationKnn) para o armazenamento de incorporação:

A implementação ElasticsearchConfigurationScript executa em segundo plano uma consulta script_score usando uma função cosineSimilarity .

Basicamente, ao ligar:

Isto agora exige:

Nesse caso, o resultado não muda em termos de "ordem", apenas a pontuação é ajustada, pois a chamada cosineSimilarity não usa nenhuma aproximação, mas calcula o cosseno para cada um dos vetores correspondentes:

Se você quiser executar este código, consulte a classe Step7SearchForVectorsTest.java .

Conclusão

Já abordamos a facilidade com que você pode gerar embeddings a partir do seu texto e como você pode armazenar e pesquisar os vizinhos mais próximos no Elasticsearch usando duas abordagens diferentes:

• Usando a consulta aproximada e rápida knn com a opção padrão ElasticsearchConfigurationKnn

• Usando a consulta exata, porém mais lenta, script_score com a opção ElasticsearchConfigurationScript

O próximo passo será construir uma aplicação RAG completa, com base no que aprendemos aqui.

LangChain4j oferece uma maneira padronizada de:

• Criar representações vetoriais (embeddings) a partir de um determinado conteúdo, digamos, um texto, por exemplo.

• armazenar embeddings em um armazenamento de embeddings

• pesquisar vetores semelhantes no armazenamento de embeddings

• discutir com mestres em direito

• Use uma memória de bate-papo para lembrar o contexto de uma discussão com um mestre em Direito.

Esta lista não é exaustiva e a comunidade LangChain4j está sempre implementando novos recursos.

Esta postagem abordará as primeiras partes principais da estrutura.

Adicionando LangChain4j OpenAI ao nosso projeto

Como em todos os projetos Java, é apenas uma questão de dependências. Aqui usaremos o Maven, mas o mesmo resultado poderia ser obtido com qualquer outro gerenciador de dependências.

Como primeiro passo para o projeto que queremos construir aqui, usaremos o OpenAI, então precisamos apenas adicionar o artefato langchain4j-open-ai :

Para o restante do código, usaremos nossa própria chave de API, que você pode obter criando uma conta na OpenAI, ou a fornecida pelo projeto LangChain4j apenas para fins de demonstração:

Agora podemos criar uma instância do nosso ChatLanguageModel:

E, finalmente, podemos fazer uma pergunta simples e obter a resposta:

A resposta fornecida poderia ser algo como:

Se você quiser executar este código, consulte a classe Step1AiChatTest.java .

Fornecendo mais contexto com langchain4j

Vamos adicionar o artefato langchain4j :

Esta ferramenta oferece um conjunto de recursos que pode nos ajudar a construir uma integração LLM mais avançada para criar nosso assistente. Aqui, criaremos uma interface Assistant que fornece o método chat , o qual chamará automaticamente o ChatLanguageModel que definimos anteriormente:

Basta pedirmos à classe LangChain4j AiServices para construir uma instância para nós:

Em seguida, chame o método chat(String) :

Está apresentando o mesmo comportamento de antes. Então, por que alteramos o código? Em primeiro lugar, é mais elegante, mas além disso, agora você pode dar instruções ao LLM usando anotações simples:

Isso está resultando em:

Se você quiser executar este código, consulte a classe Step2AssistantTest.java .

Mudando para outro LLM: langchain4j-ollama

Podemos usar o excelente projeto Ollama. Executar um LLM localmente em sua máquina pode ser útil.

Vamos adicionar o artefato langchain4j-ollama :

Como estamos executando o código de exemplo usando testes, vamos adicionar Testcontainers ao nosso projeto:

Agora podemos iniciar/parar contêineres Docker:

Nós "apenas" precisamos mudar o objeto model para se tornar um OllamaChatModel em vez do OpenAiChatModel que usamos anteriormente:

Observe que pode levar algum tempo para obter a imagem com seu modelo, mas depois de um tempo, você poderá obter a resposta:

Melhor com memória

Se fizermos várias perguntas, por padrão o sistema não se lembrará das perguntas e respostas anteriores. Então, se perguntarmos depois da primeira pergunta "Quando ele nasceu?", Nosso aplicativo responderá:

O que é um absurdo. Em vez disso, devemos usar a Memória de Chat:

Executar as mesmas perguntas agora fornece uma resposta significativa:

Conclusão

Na próxima publicação, descobriremos como podemos fazer perguntas ao nosso conjunto de dados privado usando o Elasticsearch como repositório de embeddings. Isso nos dará uma maneira de elevar nossa busca de aplicativos a um novo patamar.

Bem-vindo(a) à Parte 2 do nosso artigo sobre Técnicas Avançadas de RAG! Na parte 1 desta série, configuramos, discutimos e implementamos os componentes de processamento de dados do pipeline RAG avançado:

Nesta parte, vamos prosseguir com a consulta e o teste da nossa implementação. Vamos direto ao assunto!

Índice

• Pesquisar e recuperar, gerar respostas

  • Enriquecendo as consultas com sinônimos

  • HyDE (Incorporação Hipotética de Documentos)

  • Busca híbrida

• Experimentos

  • Resumo dos resultados

  • Teste 1: Quem audita a Elastic?

    • RAG Avançado

    • SimpleRAG

  • Teste 2: receita total em 2023

    • RAG Avançado

    • SimpleRAG

  • Teste 3: De qual produto depende principalmente o crescimento? Quanto?

    • RAG Avançado

    • SimpleRAG

  • Teste 4: Descreva o plano de benefícios para funcionários

    • RAG Avançado

    • SimpleRAG

  • Teste 5: Quais empresas a Elastic adquiriu?

    • RAG Avançado

    • SimpleRAG

• Conclusão

• Apêndice

  • Prompts

    • Pergunta RAG para responder:

    • prompt do gerador de consultas elásticas

    • Possíveis perguntas para o gerador

    • prompt do gerador HyDE

  • Exemplo de consulta de pesquisa híbrida

Pesquisar e recuperar, gerar respostas

Vamos fazer nossa primeira pergunta, idealmente alguma informação encontrada principalmente no relatório anual. Que tal:

Agora, vamos aplicar algumas de nossas técnicas para aprimorar a consulta.

Enriquecendo as consultas com sinônimos

Em primeiro lugar, vamos aumentar a diversidade na formulação da consulta e transformá-la em um formato que possa ser facilmente processado em uma consulta do Elasticsearch. Vamos utilizar o GPT-4o para converter a consulta em uma lista de cláusulas OR. Vamos escrever esta pergunta:

Quando aplicado à nossa consulta, o GPT-4o gera sinônimos da consulta base e vocabulário relacionado.

Na classe ESQueryMaker , defini uma função para dividir a consulta:

Sua função é pegar essa sequência de cláusulas OR e dividi-las em uma lista de termos, permitindo-nos fazer uma correspondência múltipla em nossos campos-chave do documento:

Finalmente, cheguei a esta pergunta:

Isso abrange muito mais aspectos do que a consulta original, reduzindo, esperamos, o risco de perder um resultado de pesquisa por termos esquecido um sinônimo. Mas podemos fazer mais.

Voltar ao topo

HyDE (Incorporação Hipotética de Documentos)

Vamos recorrer ao GPT-4o novamente, desta vez para implementar o HyDE.

A premissa básica do HyDE é gerar um documento hipotético – o tipo de documento que provavelmente conteria a resposta à consulta original. A veracidade ou exatidão do documento não é uma preocupação. Com isso em mente, vamos escrever a seguinte pergunta:

Como a busca vetorial normalmente opera com base na similaridade de vetores de cosseno, a premissa do HyDE é que podemos obter melhores resultados combinando documentos com documentos em vez de consultas com documentos.

O que nos interessa é a estrutura, a fluidez e a terminologia. Não se trata tanto de factualidade. O GPT-4o gera um documento HyDE como este:

Parece bastante convincente, como o candidato ideal para os tipos de documentos que gostaríamos de indexar. Vamos incorporar isso e usar para busca híbrida.

Voltar ao topo

Busca híbrida

Este é o núcleo da nossa lógica de busca. Nosso componente de busca lexical serão as strings da cláusula OR geradas. Nosso componente vetorial denso será um documento HyDE incorporado (também conhecido como vetor de busca). Utilizamos o KNN para identificar de forma eficiente vários documentos candidatos mais próximos do nosso vetor de busca. Por padrão, denominamos nosso componente de busca lexical como "Pontuação com TF-IDF e BM25" . Finalmente, as pontuações lexicais e de vetor denso serão combinadas usando a proporção 30/70 recomendada por Wang et al.

Finalmente, podemos montar uma função RAG. Nosso processo RAG, da pergunta à resposta, seguirá este fluxo:

1. Converter consulta em cláusulas OR.

2. Gere o documento HyDE e incorpore-o.

3. Passe ambos como entradas para a Busca Híbrida.

4. Recuperar os n melhores resultados, inverter a ordem para que a pontuação mais relevante seja a "mais recente" na memória contextual do LLM (Empacotamento Inverso). Exemplo de Empacotamento Inverso: Consulta: "Técnicas de otimização de consultas do Elasticsearch". Documentos recuperados (ordenados por relevância): Ordem invertida para o contexto do LLM: Ao inverter a ordem, a informação mais relevante (1) aparece por último no contexto, potencialmente recebendo mais atenção do LLM durante a geração de respostas.

   1. "Use consultas booleanas para combinar vários critérios de pesquisa de forma eficiente."

   2. "Implementar estratégias de cache para melhorar os tempos de resposta das consultas."

   3. "Otimize os mapeamentos de índice para um desempenho de pesquisa mais rápido."

   4. "Otimize os mapeamentos de índice para um desempenho de pesquisa mais rápido."

   5. "Implementar estratégias de cache para melhorar os tempos de resposta das consultas."

   6. "Use consultas booleanas para combinar vários critérios de pesquisa de forma eficiente."

5. Passe o contexto para o LLM para geração.

Vamos executar nossa consulta e obter a resposta:

Legal. Isso mesmo.

Voltar ao topo

Experimentos

Há uma pergunta importante a ser respondida agora. O que ganhamos investindo tanto esforço e complexidade adicional nessas implementações?

Vamos fazer uma pequena comparação. O pipeline RAG que implementamos em comparação com a busca híbrida básica, sem nenhuma das melhorias que fizemos. Realizaremos uma pequena série de testes para verificar se notamos alguma diferença significativa. Vamos nos referir ao RAG que acabamos de implementar como AdvancedRAG e ao pipeline básico como SimpleRAG.

Resumo dos resultados

Esta tabela resume os resultados de cinco testes de ambos os pipelines RAG. Avaliei a superioridade relativa de cada método com base no detalhamento e na qualidade das respostas, mas essa é uma avaliação totalmente subjetiva. As respostas corretas estão reproduzidas abaixo desta tabela para sua análise. Dito isso, vamos dar uma olhada em como eles se saíram!

O SimpleRAG não conseguiu responder às perguntas 1 e 5. O AdvancedRAG, por sua vez, apresentou respostas muito mais detalhadas nas perguntas 2, 3 e 4. Com base nesse maior nível de detalhamento, considerei as respostas do AdvancedRAG de melhor qualidade.

Teste

Pergunta

Desempenho AdvancedRAG

Desempenho SimpleRAG

Latência RAG Avançada

Latência SimpleRAG

Ganhador

1

Quem audita a Elastic?

Identificou corretamente a PwC como auditora.

Não foi possível identificar o auditor.

11,6s

4,4s

RAG Avançado

2

Qual foi a receita total em 2023?

Forneceu o valor correto da receita. Incluímos contexto adicional com a receita de anos anteriores.

Forneceu o valor correto da receita.

13,3s

2,8s

RAG Avançado

3

De qual produto depende principalmente o crescimento? Quanto?

Identificamos corretamente o Elastic Cloud como o principal fator impulsionador. Inclui contexto geral de receita e detalhes adicionais.

Identificamos corretamente o Elastic Cloud como o principal fator impulsionador.

14,1s

12,8s

RAG Avançado

4

Descreva o plano de benefícios para funcionários.

Apresentou uma descrição completa dos planos de aposentadoria, programas de saúde e outros benefícios. Inclui valores de contribuição específicos para diferentes anos.

Apresentou uma boa visão geral dos benefícios, incluindo remuneração, planos de aposentadoria, ambiente de trabalho e o programa Elastic Cares.

26,6s

11,6s

RAG Avançado

5

Quais empresas a Elastic adquiriu?

As aquisições recentes mencionadas no relatório foram listadas corretamente (CmdWatch, Build Security, Optimyze). Foram fornecidas algumas datas de aquisição e preços de compra.

Não foi possível recuperar informações relevantes do contexto fornecido.

11,9s

2,7s

RAG Avançado

Teste 1: Quem audita a Elastic?

RAG Avançado

SimpleRAG

Resumo: A SimpleRAG não identificou a PwC como auditora.

Bem, isso é realmente surpreendente. Parece ser uma falha de busca por parte do SimpleRAG. Não foram recuperados documentos relacionados à auditoria. Vamos diminuir um pouco a dificuldade no próximo teste.

Teste 2: receita total em 2023

RAG Avançado

SimpleRAG

Resumo: Ambas as equipes RAG acertaram a resposta: receita total de US$ 1.068.989.000 em 2023.

Ambos estavam bem aqui. Parece que a AdvancedRAG pode ter adquirido uma gama mais ampla de documentos? Certamente a resposta é mais detalhada e incorpora informações de anos anteriores. Isso era de se esperar, considerando as melhorias que fizemos, mas ainda é muito cedo para afirmar algo com certeza.

Vamos aumentar a dificuldade.

Teste 3: De qual produto depende principalmente o crescimento? Quanto?

RAG Avançado

SimpleRAG

Resumo: Ambos os RAGs identificaram corretamente o Elastic Cloud como o principal motor de crescimento. No entanto, o AdvancedRAG inclui mais detalhes, levando em consideração as receitas de assinaturas e o crescimento da base de clientes, e menciona explicitamente outras ofertas da Elastic.

Teste 4: Descreva o plano de benefícios para funcionários

RAG Avançado

SimpleRAG

Resumo: A AdvancedRAG aborda o assunto com muito mais profundidade e detalhes, mencionando o plano 401K para funcionários baseados nos EUA, além de definir planos de contribuição fora dos EUA. O texto também menciona planos de saúde e bem-estar, mas omite o programa Elastic Cares, que é citado pela SimpleRAG.

Teste 5: Quais empresas a Elastic adquiriu?

RAG Avançado

SimpleRAG

Resumo: O SimpleRAG não recupera nenhuma informação relevante sobre aquisições, resultando em uma resposta incorreta. A AdvancedRAG lista corretamente a CmdWatch, a Build Security e a Optimyze, que foram as principais aquisições mencionadas no relatório.

Voltar ao topo

Conclusão

Com base em nossos testes, nossas técnicas avançadas parecem aumentar o alcance e a profundidade das informações apresentadas, potencialmente melhorando a qualidade das respostas RAG.

Além disso, pode haver melhorias na confiabilidade, já que perguntas formuladas de maneira ambígua, como Which companies did Elastic acquire? e Who audits Elastic foram respondidas corretamente pelo AdvancedRAG, mas não pelo SimpleRAG.

No entanto, vale a pena ter em mente que, em 3 de 5 casos, o pipeline RAG básico, incorporando a Busca Híbrida, mas nenhuma outra técnica, conseguiu produzir respostas que capturaram a maior parte das informações essenciais.

Devemos observar que, devido à incorporação de LLMs nas fases de preparação e consulta de dados, a latência do AdvancedRAG é geralmente de 2 a 5 vezes maior que a do SimpleRAG. Este é um custo significativo que pode tornar o AdvancedRAG adequado apenas para situações em que a qualidade da resposta é priorizada em detrimento da latência.

Os custos significativos de latência podem ser atenuados usando um modelo de linguagem latente (LLM) menor e mais barato, como o Claude Haiku ou o GPT-4o-mini, na fase de preparação dos dados. Salve os modelos avançados para geração de respostas.

Isso está de acordo com as conclusões de Wang et al. Conforme demonstram os resultados, quaisquer melhorias realizadas são relativamente incrementais. Resumindo, o método RAG básico e simples permite chegar a um produto final bastante satisfatório, sendo ainda mais barato e rápido. Para mim, é uma conclusão interessante. Para casos de uso em que velocidade e eficiência são essenciais, o SimpleRAG é a escolha sensata. Para casos de uso em que é necessário extrair o máximo desempenho possível, as técnicas incorporadas no AdvancedRAG podem oferecer uma solução.

Voltar ao topo

Apêndice

Prompts

Pergunta RAG para responder:

Solicitação para que o LLM gere respostas com base na consulta e no contexto.

prompt do gerador de consultas elásticas

Solicitação para enriquecer as consultas com sinônimos e convertê-las para o formato OU.

Possíveis perguntas para o gerador

Solicitação para gerar possíveis perguntas e enriquecer os metadados do documento.

prompt do gerador HyDE

Solicitação para gerar documentos hipotéticos usando o HyDE

Exemplo de consulta de pesquisa híbrida

O artigo recente "Searching for Best Practices in Retrieval-Augmented Generation" avalia empiricamente a eficácia de várias técnicas de aprimoramento de RAG (Geração Aumentada de Recuperação), com o objetivo de convergir para um conjunto de melhores práticas para RAG.

Implementaremos algumas dessas boas práticas propostas, principalmente aquelas que visam melhorar a qualidade da busca (Fragmentação de Sentenças, HyDE, Empacotamento Reverso).

Por uma questão de brevidade, omitiremos as técnicas focadas na melhoria da eficiência (Classificação e Sumarização de Consultas).

Implementaremos também algumas técnicas que não foram abordadas, mas que eu pessoalmente considero úteis e interessantes (Inclusão de Metadados, Incorporação Composta de Múltiplos Campos, Enriquecimento de Consultas).

Por fim, realizaremos um breve teste para verificar se a qualidade dos nossos resultados de pesquisa e das respostas geradas melhorou em comparação com a linha de base. Vamos lá!

Visão geral do RAG

O RAG visa aprimorar os LLMs (Modelos de Aprendizagem Baseados em Aprendizagem) recuperando informações de bases de conhecimento externas para enriquecer as respostas geradas. Ao fornecer informações específicas do domínio, os LLMs podem ser rapidamente adaptados para casos de uso fora do escopo de seus dados de treinamento; sendo significativamente mais baratos do que o ajuste fino e mais fáceis de manter atualizados.

As medidas para melhorar a qualidade do RAG normalmente se concentram em duas vertentes:

1. Aprimorar a qualidade e a clareza da base de conhecimento.

2. Melhorar a abrangência e a especificidade das consultas de pesquisa.

Essas duas medidas alcançarão o objetivo de aumentar as chances de o mestrando em Direito ter acesso a fatos e informações relevantes e, portanto, ser menos propenso a ter alucinações ou recorrer ao seu próprio conhecimento, que pode estar desatualizado ou ser irrelevante.

A diversidade de métodos é difícil de esclarecer em poucas frases. Vamos direto à implementação para que as coisas fiquem mais claras.

Índice

• Visão geral

  • Índice

• Configurar

• Ingestão, processamento e incorporação de documentos

  • Ingestão de dados

  • Segmentação por tokens e em nível de frase

  • Inclusão e geração de metadados

    • Palavras-chave extraídas pelo TextRank

    • Possíveis perguntas geradas pelo GPT-4o

    • Entidades extraídas pelo Spacy

  • Incorporações compostas de múltiplos campos

    • Indexação para Elastic

• Pausa para o gato

• Apêndice

  • Definições

Configurar

Todo o código pode ser encontrado no repositório Searchlabs.

Em primeiro lugar, o mais importante. Você precisará do seguinte:

1. Implantação na Nuvem Elástica

2. Uma API LLM - Neste notebook, estamos usando uma implantação do GPT-4o no Azure OpenAI.

3. Python versão 3.12.4 ou posterior

Executaremos todo o código do notebook main.ipynb.

Faça o clone do repositório usando o Git, navegue até supporting-blog-content/advanced-rag-techniques e execute os seguintes comandos:

Feito isso, crie um arquivo .env. Abra o arquivo e preencha os seguintes campos (Referenciado em .env.example). Agradecimentos ao meu coautor, Claude-3.5, pelos comentários úteis.

Em seguida, selecionaremos o documento a ser importado e o colocaremos na pasta de documentos. Para este artigo, usaremos o Relatório Anual da Elastic NV de 2023. É um documento bastante complexo e denso, perfeito para testar a resistência das nossas técnicas RAG.

Agora que está tudo pronto, vamos à ingestão. Abra o arquivo main.ipynb e execute as duas primeiras células para importar todos os pacotes e inicializar todos os serviços.

Voltar ao topo

Ingestão, processamento e incorporação de documentos

Ingestão de dados

• Nota pessoal: Estou impressionado com a praticidade do LlamaIndex. Antigamente, antes dos mestrados em direito e do LlamaIndex, importar documentos de vários formatos era um processo doloroso de coletar pacotes esotéricos de todos os cantos. Agora, tudo se resume a uma única chamada de função. Selvagem.

O SimpleDirectoryReader carregará todos os documentos em directory_path. Para arquivos .pdf , ele retorna uma lista de objetos de documento, que eu converto em dicionários Python porque acho mais fácil trabalhar com eles.

Cada dicionário contém o conteúdo da chave no campo text . Também contém metadados úteis, como número da página, nome do arquivo, tamanho do arquivo e tipo.

Voltar ao topo

Segmentação por tokens e em nível de frase

A primeira coisa a fazer é reduzir nossos documentos a blocos de tamanho padrão (para garantir consistência e facilidade de gerenciamento). Os modelos de incorporação possuem limites de token únicos (tamanho máximo de entrada que podem processar). Os tokens são as unidades básicas de texto que modelam o processo. Para evitar a perda de informações (truncamento ou omissão de conteúdo), devemos fornecer textos que não excedam esses limites (dividindo textos mais longos em segmentos menores).

O particionamento (chunking) tem um impacto significativo no desempenho. Idealmente, cada bloco representaria uma informação autossuficiente, capturando informações contextuais sobre um único tópico. Os métodos de fragmentação incluem a fragmentação ao nível da palavra, em que os documentos são divididos pela contagem de palavras, e a fragmentação semântica, que utiliza um modelo de lógica de divisão (LLM) para identificar pontos de quebra lógicos.

A segmentação em nível de palavra é barata, rápida e fácil, mas apresenta o risco de dividir frases e, assim, quebrar o contexto. A fragmentação semântica torna-se lenta e dispendiosa, especialmente se estivermos lidando com documentos como o Relatório Anual da Elastic, com 116 páginas.

Vamos optar por uma abordagem intermediária. A segmentação em nível de frase ainda é simples, mas pode preservar o contexto de forma mais eficaz do que a segmentação em nível de palavra, além de ser significativamente mais barata e rápida. Além disso, implementaremos uma janela deslizante para capturar parte do contexto circundante e atenuar o impacto da divisão de parágrafos.

A classe Chunker recebe o tokenizador do modelo de incorporação para codificar e decodificar o texto. Agora vamos construir blocos de 512 tokens cada, com uma sobreposição de 20 tokens. Para isso, vamos dividir o texto em frases, tokenizar essas frases e, em seguida, adicionar as frases tokenizadas ao nosso bloco atual até que não possamos adicionar mais sem ultrapassar nosso limite de tokens.

Finalmente, decodifique as frases de volta ao texto original para incorporação, armazenando-o em um campo chamado original_text. Os blocos são armazenados em um campo chamado chunk. Para reduzir o ruído (ou seja, documentos inúteis), descartaremos quaisquer documentos com menos de 50 tokens de comprimento.

Vamos executar o programa em nossos documentos:

E receba trechos de texto com a seguinte aparência:

Voltar ao topo

Inclusão e geração de metadados

Dividimos nossos documentos em partes menores. Agora é hora de enriquecer os dados. Desejo gerar ou extrair metadados adicionais. Esses metadados adicionais podem ser usados para influenciar e melhorar o desempenho da busca.

Vamos definir uma classe DocumentEnricher , cuja função é receber uma lista de documentos (dicionários Python) e uma lista de funções de processamento. Essas funções serão executadas na coluna original_text dos documentos e armazenarão suas saídas em novos campos.

Primeiro, extraímos as palavras-chave usando o TextRank. O TextRank é um algoritmo baseado em grafos que extrai frases e sentenças-chave de um texto, classificando sua importância com base nas relações entre as palavras.

Em seguida, vamos gerar perguntas potenciais usando o GPT-4o.

Por fim, vamos extrair as entidades usando o Spacy.

Como o código para cada um deles é bastante extenso e complexo, vou evitar reproduzi-lo aqui. Caso tenha interesse, os arquivos estão marcados nos exemplos de código abaixo.

Vamos executar o enriquecimento de dados:

E veja os resultados:

Palavras-chave extraídas pelo TextRank

Essas palavras-chave representam os tópicos principais do bloco. Se a consulta estiver relacionada à segurança cibernética, a pontuação desse segmento será aumentada.

Possíveis perguntas geradas pelo GPT-4o

Essas perguntas em potencial podem corresponder diretamente às consultas do usuário, oferecendo um aumento na pontuação. Solicitamos ao GPT-4o que gere perguntas que possam ser respondidas usando as informações encontradas no bloco atual.

Entidades extraídas pelo Spacy

Essas entidades têm uma finalidade semelhante à das palavras-chave, mas capturam os nomes de organizações e indivíduos, que a extração por palavras-chave pode não incluir.

Voltar ao topo

Incorporações compostas de múltiplos campos

Agora que enriquecemos nossos documentos com metadados adicionais, podemos aproveitar essas informações para criar representações vetoriais mais robustas e sensíveis ao contexto.

Vamos recapitular o ponto em que nos encontramos no processo. Cada documento contém quatro áreas de interesse.

Cada campo representa uma perspectiva diferente sobre o contexto do documento, podendo destacar uma área-chave para o mestrado em Direito (LLM) se concentrar.

O plano é incorporar cada um desses campos e, em seguida, criar uma soma ponderada das incorporações, conhecida como Incorporação Composta.

Com sorte, essa incorporação composta permitirá que o sistema se torne mais sensível ao contexto, além de introduzir mais um hiperparâmetro ajustável para controlar o comportamento de busca.

Primeiro, vamos incorporar cada campo e atualizar cada documento no local, usando nosso modelo de incorporação definido localmente e importado no início do notebook main.ipynb.

Cada função de incorporação retorna o campo da incorporação, que é simplesmente o campo de entrada original com um sufixo _embedding .

Vamos agora definir os pesos da nossa incorporação composta:

Os pesos permitem atribuir prioridades a cada componente, com base no seu caso de uso e na qualidade dos seus dados. Intuitivamente, a magnitude dessas ponderações depende do valor semântico de cada componente. Como o texto em si é de longe o mais rico, atribuo uma ponderação de 70%. Como as entidades são as menores, sendo apenas uma lista de nomes de organizações ou pessoas, atribuo a elas uma ponderação de 5%. A configuração precisa desses valores deve ser determinada empiricamente, caso a caso, para cada situação específica.

Finalmente, vamos escrever uma função para aplicar as ponderações e criar nossa representação composta. Também excluiremos todos os elementos incorporados dos componentes para economizar espaço.

Com isso, concluímos o processamento de nossos documentos. Agora temos uma lista de objetos de documento com a seguinte aparência:

Indexação para Elastic

Vamos fazer o upload em massa de nossos documentos para o Elastic Search. Para esse propósito, há muito tempo defini um conjunto de funções auxiliares elásticas em elastic_helpers.py. É um trecho de código muito extenso, então vamos nos ater à análise das chamadas de função.

es_bulk_indexer.bulk_upload_documents Funciona com qualquer lista de objetos de dicionário, aproveitando os convenientes mapeamentos dinâmicos do Elasticsearch.

Acesse o Kibana e verifique se todos os documentos foram indexados. Deveriam ser 224. Nada mal para um documento tão grande!

Voltar ao topo

Pausa para o gato

Vamos fazer uma pausa, o artigo está um pouco denso, eu sei. Vejam só o meu gato:

Adorável. O chapéu sumiu e eu suspeito que ela o roubou e escondeu em algum lugar :(

Parabéns por ter chegado até aqui :)

Junte-se a mim na Parte 2 para testes e avaliação do nosso pipeline RAG!

Apêndice

Definições

1. Segmentação de Frases

• Uma técnica de pré-processamento usada em sistemas RAG para dividir o texto em unidades menores e significativas.

• Processo:

  1. Entrada: Bloco grande de texto (ex.: documento, parágrafo)

  2. Saída: Segmentos de texto menores (normalmente frases ou pequenos grupos de frases)

• Propósito:

  • Cria segmentos de texto granulares e específicos ao contexto.

  • Permite uma indexação e recuperação mais precisas.

  • Melhora a relevância das informações recuperadas em sistemas RAG.

• Características:

  • Os segmentos têm significado semântico.

  • Podem ser indexados e recuperados independentemente.

  • Frequentemente preserva algum contexto para garantir a compreensibilidade de forma independente.

• Benefícios:

  • Aumenta a precisão de recuperação

  • Permite uma ampliação mais focada em pipelines RAG.

2. HyDE (Incorporação Hipotética de Documentos)

• Uma técnica que utiliza um modelo de lógica latente (LLM) para gerar um documento hipotético para expansão de consultas em sistemas RAG.

• Processo:

  1. Inserir consulta em um LLM

  2. O LLM gera um documento hipotético que responde à pergunta.

  3. Incorpore o documento gerado

  4. Use o embedding para busca vetorial

• Principal diferença:

  • RAG tradicional: relaciona a consulta aos documentos.

  • HyDE: Correspondência entre documentos.

• Propósito:

  • Melhorar o desempenho de recuperação de dados, especialmente para consultas complexas ou ambíguas.

  • Captura um contexto semântico mais rico do que uma consulta curta.

• Benefícios:

  • Aproveita o conhecimento do LLM para ampliar as consultas.

  • Pode potencialmente melhorar a relevância dos documentos recuperados.

• Desafios:

  • Requer inferência LLM adicional, aumentando a latência e o custo.

  • O desempenho depende da qualidade do documento hipotético gerado.

3. Reembalagem reversa

• Uma técnica utilizada em sistemas RAG para reordenar os resultados da pesquisa antes de passá-los para o LLM.

• Processo:

  1. O mecanismo de busca (por exemplo, Elasticsearch) retorna documentos em ordem decrescente de relevância.

  2. A ordem é invertida, colocando o documento mais relevante por último.

• Propósito:

  • Explora o viés de recência dos mestrados em direito, que tendem a se concentrar mais nas informações mais recentes em seu contexto.

  • Garante que as informações mais relevantes sejam as mais "atualizadas" na janela de contexto do LLM.

• Exemplo: Ordem original: [Mais relevante, Segundo mais relevante, Terceiro mais relevante, ...] Ordem inversa: [..., Terceiro mais relevante, Segundo mais relevante, Mais relevante]

4. Classificação de consultas

• Uma técnica para otimizar a eficiência do sistema RAG, determinando se uma consulta requer RAG ou se pode ser respondida diretamente pelo LLM.

• Processo:

  1. Desenvolver um conjunto de dados personalizado específico para o LLM em uso.

  2. Treinar um modelo de classificação especializado

  3. Utilize o modelo para categorizar as consultas recebidas.

• Propósito:

  • Melhore a eficiência do sistema evitando o processamento desnecessário de RAG (raiz, grafite e agregação).

  • Direcione as consultas para o mecanismo de resposta mais apropriado.

• Requisitos:

  • Conjunto de dados e modelo específicos para LLM

  • Aperfeiçoamento contínuo para manter a precisão.

• Benefícios:

  • Reduz a sobrecarga computacional para consultas simples.

  • Potencialmente melhora o tempo de resposta para consultas que não sejam RAG.

5. Resumo

• Uma técnica para condensar documentos recuperados em sistemas RAG.

• Processo:

  1. Recuperar documentos relevantes

  2. Gere resumos concisos de cada documento.

  3. Utilize resumos em vez de documentos completos no pipeline RAG.

• Propósito:

  • Melhore o desempenho RAG concentrando-se em informações essenciais.

  • Reduzir o ruído e a interferência de conteúdo menos relevante

• Benefícios:

  • Potencialmente melhora a relevância das respostas do LLM

  • Permite a inclusão de mais documentos dentro dos limites do contexto.

• Desafios:

  • Risco de perder detalhes importantes na sumarização.

  • Sobrecarga computacional adicional para geração de resumos.

6. Inclusão de Metadados

• Uma técnica para enriquecer documentos com informações contextuais adicionais.

• Tipos de metadados:

  • Palavras-chave

  • Títulos

  • Datas

  • Detalhes da autoria

  • Resumos

• Propósito:

  • Aumentar a informação contextual disponível para o sistema RAG

  • Proporcionar aos alunos de mestrado em Direito uma compreensão mais clara do conteúdo e da relevância dos documentos.

• Benefícios:

  • Potencialmente melhora a precisão da recuperação.

  • Aumenta a capacidade do LLM de avaliar a utilidade dos documentos.

• Implementação:

  • Pode ser feito durante o pré-processamento do documento.

  • Pode exigir etapas adicionais de extração ou geração de dados.

7. Incorporações compostas de múltiplos campos

• Uma técnica avançada de incorporação para sistemas RAG que cria incorporações separadas para diferentes componentes do documento.

• Processo:

  1. Identifique os campos relevantes (ex.: título, palavras-chave, sinopse, conteúdo principal).

  2. Gere embeddings separados para cada campo.

  3. Combine ou armazene esses embeddings para uso na recuperação de informações.

• Diferença em relação à abordagem padrão:

  • Tradicional: Incorporação única para todo o documento.

  • Composição: Incorporação múltipla para diferentes aspectos do documento

• Propósito:

  • Criar representações de documentos mais matizadas e sensíveis ao contexto.

  • Capturar informações de uma variedade maior de fontes em um documento.

• Benefícios:

  • Potencialmente melhora o desempenho em consultas ambíguas ou multifacetadas.

  • Permite uma ponderação mais flexível de diferentes aspectos do documento na recuperação.

• Desafios:

  • Aumento da complexidade na incorporação de processos de armazenamento e recuperação

  • Pode exigir algoritmos de correspondência mais sofisticados.

8. Enriquecimento de consultas

• Uma técnica para expandir a consulta original com termos relacionados, a fim de melhorar o alcance da pesquisa.

• Processo:

  1. Analise a consulta original

  2. Gere sinônimos e frases semanticamente relacionadas.

  3. Aprimore a consulta com estes termos adicionais.

• Propósito:

  • Aumentar o leque de correspondências potenciais no conjunto de documentos.

  • Melhorar o desempenho de recuperação de dados para consultas com linguagem específica ou técnica.

• Benefícios:

  • Pode recuperar documentos relevantes que não correspondam exatamente aos termos da consulta original.

  • Pode ajudar a superar a incompatibilidade de vocabulário entre consultas e documentos.

• Desafios:

  • Risco de desvio de consulta se não for implementado com cuidado.

  • Pode aumentar a sobrecarga computacional no processo de recuperação.

Voltar ao topo

Neste artigo, analisaremos maneiras de proteger informações de identificação pessoal (PII) e dados sensíveis ao usar LLMs públicos em um fluxo RAG (Retrieval Augmented Generation). Vamos explorar a mascaramento de informações pessoais identificáveis (PII) e dados sensíveis usando bibliotecas de código aberto e expressões regulares, bem como o uso de LLMs locais para mascarar dados antes de invocar um LLM público.

Antes de começarmos, vamos revisar alguns termos que usamos nesta postagem.

Terminologia

LlamaIndex é uma estrutura de dados líder para a construção de aplicações LLM (Large Language Model). O LlamaIndex fornece abstrações para vários estágios de construção de um aplicativo RAG (Retrieval Augmented Generation). Frameworks como LlamaIndex e LangChain fornecem abstrações para que os aplicativos não fiquem fortemente acoplados às APIs de nenhum LLM específico.

O Elasticsearch é oferecido pela Elastic. A Elastic é líder do setor e está por trás do Elasticsearch, um armazenamento de dados escalável e banco de dados vetorial que oferece suporte a pesquisa de texto completo para precisão, pesquisa vetorial para compreensão semântica e pesquisa híbrida para o melhor dos dois mundos. O Elasticsearch é um mecanismo de busca e análise distribuído e baseado em REST, um armazenamento de dados escalável e um banco de dados vetorial. Os recursos do Elasticsearch que usamos neste blog estão disponíveis na versão gratuita e de código aberto do Elasticsearch.

A Geração Aumentada por Recuperação (RAG, na sigla em inglês) é uma técnica/padrão de IA em que os Modelos de Aprendizagem Baseados em Aprendizagem (LLMs, na sigla em inglês) recebem conhecimento externo para gerar respostas às consultas do usuário. Isso permite que as respostas do LLM sejam adaptadas a um contexto específico e menos genéricas.

Os embeddings são representações numéricas do significado de um texto/mídia. São representações de menor dimensão de informações de alta dimensão.

RAG e Proteção de Dados

De modo geral, os Modelos de Linguagem de Grande Porte (LLMs, na sigla em inglês) são bons em gerar respostas com base nas informações disponíveis no modelo, que pode ser treinado com dados da internet. No entanto, para as consultas em que as informações não estão disponíveis no modelo, os LLMs precisam receber conhecimento externo ou detalhes específicos não contidos no modelo. Essas informações podem estar em seu banco de dados ou sistema de conhecimento interno. A Geração Aumentada por Recuperação (RAG, na sigla em inglês) é uma técnica na qual, para uma determinada consulta do usuário, você primeiro recupera o contexto/informação relevante de sistemas externos (aos LLMs), como seu banco de dados, e envia esse contexto juntamente com a consulta do usuário para o LLM para gerar uma resposta mais específica e relevante.

Isso torna a técnica RAG altamente eficaz para aplicações em perguntas e respostas, criação de conteúdo e em qualquer situação em que uma compreensão profunda do contexto e dos detalhes seja benéfica.

Consequentemente, em um pipeline RAG, você corre o risco de expor informações internas, como PII (Informações de Identificação Pessoal) e informações sensíveis (por exemplo, nomes, datas de nascimento, números de contas etc.) a servidores públicos.

Embora seus dados estejam seguros ao usar um banco de dados vetorial como o Elasticsearch (através de várias ferramentas como Controle de Acesso Baseado em Funções, Segurança em Nível de Documento etc.), é preciso ter cuidado ao enviar dados para um repositório público de dados.

A proteção de informações de identificação pessoal (PII) e dados sensíveis é crucial ao usar modelos de linguagem de grande porte (LLMs) por diversos motivos:

• Conformidade com a privacidade: Muitas regiões possuem regulamentações rigorosas, como o Regulamento Geral de Proteção de Dados (RGPD) na Europa ou a Lei de Privacidade do Consumidor da Califórnia (CCPA) nos Estados Unidos, que exigem a proteção de dados pessoais. O cumprimento dessas leis é necessário para evitar consequências legais e multas.

• Confiança do usuário: Garantir a confidencialidade e a integridade de informações sensíveis constrói a confiança do usuário. Os usuários tendem a usar e interagir mais com sistemas que acreditam proteger sua privacidade.

• Segurança de dados: a proteção contra violações de dados é essencial. Dados sensíveis expostos a sistemas de gestão de dados sem salvaguardas adequadas podem ficar suscetíveis a roubo ou uso indevido, levando a potenciais danos como roubo de identidade ou fraude financeira.

• Considerações éticas: Do ponto de vista ético, é importante respeitar a privacidade dos usuários e tratar seus dados de forma responsável. O manuseio inadequado de informações pessoais identificáveis pode levar à discriminação, estigmatização ou outros impactos sociais negativos.

• Reputação empresarial: Empresas que não protegem dados sensíveis podem sofrer danos à sua reputação, o que pode ter efeitos negativos a longo prazo em seus negócios, incluindo perda de clientes e receita.

• Redução dos riscos de abuso: O manuseio seguro de dados sensíveis ajuda a prevenir o uso malicioso dos dados ou do modelo, como o treinamento de modelos com dados tendenciosos ou o uso dos dados para manipular ou prejudicar indivíduos.

De modo geral, a proteção robusta de informações pessoais identificáveis e dados sensíveis é necessária para garantir a conformidade legal, manter a confiança do usuário, assegurar a segurança dos dados, defender os padrões éticos, proteger a reputação da empresa e reduzir o risco de abuso.

Resumo rápido

Na publicação anterior, discutimos como implementar uma experiência de perguntas e respostas usando a técnica RAG com o Elasticsearch como banco de dados vetorial, utilizando o LlamaIndex e um Mistral LLM executado localmente. Aqui, damos continuidade a isso.

A leitura da postagem anterior é opcional, pois agora vamos discutir/recapitular rapidamente o que fizemos na postagem anterior.

Tínhamos um conjunto de dados de amostra de conversas de call center entre agentes e clientes de uma empresa fictícia de seguros residenciais. Criamos um aplicativo RAG simples que respondia a perguntas como "Que tipo de problemas relacionados à água os clientes estão relatando?".

Em linhas gerais, o fluxo de trabalho se apresentava assim.

Durante a fase de indexação, carregamos e indexamos documentos usando o pipeline LlamaIndex. Os documentos foram divididos em partes e armazenados no banco de dados vetorial Elasticsearch juntamente com seus respectivos embeddings.

Durante a fase de consulta, quando o usuário fazia uma pergunta, o LlamaIndex recuperava os K documentos mais semelhantes e relevantes para a consulta. Esses K documentos mais relevantes, juntamente com a consulta, foram enviados ao Mistral LLM em execução localmente, que então gerou a resposta a ser enviada de volta ao usuário. Fique à vontade para ler a postagem anterior ou explorar o código.

Na postagem anterior, tínhamos o LLM rodando localmente. No entanto, em produção, você pode querer usar um LLM externo fornecido por várias empresas como OpenAI, Mistral, Anthropic etc. Isso pode ocorrer porque seu caso de uso exige um modelo fundamental maior ou porque a execução local não é uma opção devido a necessidades de produção corporativa, como escalabilidade, disponibilidade, desempenho etc.

A introdução de um LLM externo em seu pipeline RAG expõe você ao risco de vazamento inadvertido de informações sensíveis e PII para os LLMs. Neste post, exploraremos opções sobre como mascarar informações de identificação pessoal (PII) como parte do seu fluxo de trabalho RAG antes de enviar documentos para um LLM externo.

RAG com um mestrado em Direito público

Antes de discutirmos como proteger suas informações pessoais e sensíveis em um pipeline RAG, primeiro construiremos um aplicativo RAG simples usando LlamaIndex, banco de dados Elasticsearch Vector e OpenAI LLM.

Pré-requisitos

Precisaremos do seguinte:

• O Elasticsearch está configurado e funcionando como banco de dados vetorial para armazenar os embeddings. Siga as instruções da postagem anterior sobre como instalar o Elasticsearch.

• Chaves de API OpenAI.

Aplicação RAG simples

Para referência, o código completo pode ser encontrado neste repositório do Github(branch:protecting-pii). Clonar o repositório é opcional, pois analisaremos o código a seguir.

Em sua IDE favorita, crie uma nova aplicação Python com os 3 arquivos abaixo.

• index.py Onde fica o código relacionado à indexação de dados.

• query.py Onde fica o código relacionado a consultas e interação com o LLM.

• .env onde ficam as propriedades de configuração, como chaves de API.

Precisamos instalar alguns pacotes. Começamos criando um novo ambiente virtual Python na pasta raiz da sua aplicação.

Ative o ambiente virtual e instale os pacotes necessários listados abaixo.

Configure as propriedades de conexão do OpenAI e do Elasticsearch no arquivo .env. arquivo.

Dados de indexação

Baixe o arquivo conversations.json , que contém conversas entre clientes e atendentes do call center da nossa fictícia empresa de seguros residenciais. Coloque o arquivo no diretório raiz da aplicação, junto com os dois arquivos Python e o arquivo .env. arquivo que você criou anteriormente. Segue abaixo um exemplo do conteúdo do arquivo.

Cole o código abaixo em index.py que cuida da indexação dos dados.

Executar o código acima cria um índice no Elasticsearch, armazenando os embeddings no índice do Elasticsearch chamado convo_index.

Caso precise de explicações sobre o IngestionPipeline do LlamaIndex, consulte a publicação anterior na seção Criar IngestionPipeline.

Consultando

Na postagem anterior, usamos um LLM local para consulta.

Neste post, utilizamos o LLM público da OpenAI, conforme mostrado abaixo.

O código acima imprime a resposta da OpenAI conforme abaixo.

Os clientes apresentaram diversas reclamações relacionadas a problemas com água, incluindo danos causados por água em porões, canos estourados, danos causados por granizo em telhados e recusa de indenizações por motivos como falta de notificação em tempo hábil, problemas de manutenção, desgaste gradual e danos preexistentes. Em todos os casos, os clientes expressaram frustração com as negativas de seus pedidos e buscaram avaliações e decisões justas em relação às suas reivindicações.

Mascaramento de informações pessoais identificáveis (PII) em RAG

O que abordamos até agora envolve o envio de documentos tal como estão para a OpenAI, juntamente com a consulta do usuário.

No pipeline RAG, após a recuperação do contexto relevante de um repositório Vector, temos a oportunidade de mascarar informações pessoais identificáveis (PII) e informações sensíveis antes de enviar a consulta e o contexto para o LLM.

Existem várias maneiras de mascarar informações pessoais identificáveis (PII) antes de enviá-las a um LLM externo, cada uma com seus próprios méritos. Analisamos algumas das opções abaixo.

1. Utilizando bibliotecas de PNL como spacy.io ou Presidio (biblioteca de código aberto mantida pela Microsoft).

2. Utilizando o LlamaIndex sem nenhuma configuração adicional. NERPIINodePostprocessor.

3. Utilizando LLMs locais via PIINodePostprocessor

Após implementar a lógica de mascaramento usando qualquer um dos métodos acima, você pode configurar o IngestionPipeline do LlamaIndex com um PostProcessor (um personalizado ou qualquer um dos PostProcessors prontos para uso do LlamaIndex).

Utilizando bibliotecas de PNL

Como parte do pipeline RAG, poderíamos mascarar dados sensíveis usando bibliotecas de PNL (Processamento de Linguagem Natural). Nesta demonstração, usaremos o pacote spacy.io.

Crie um novo arquivo query_masking_nlp.py e adicione o código abaixo.

A resposta do LLM é apresentada abaixo.

No código acima, ao criar o Llama Index QueryEngine, fornecemos um CustomPostProcessor.

A lógica que é invocada pelo QueryEngine é definida no método _postprocess_nodes de CustomPostProcessor. Estamos utilizando a biblioteca SpaCy.io para detectar entidades nomeadas em nossos documentos e, em seguida, usamos expressões regulares para substituir esses nomes, bem como informações confidenciais, antes de enviá-los para o LLM.

Abaixo, seguem como exemplo trechos de conversas originais e da conversa mascarada criada pelo CustomPostProcessor.

Texto original:

Texto mascarado pelo CustomPostProcessor.

Observação:

Identificar e mascarar informações pessoais identificáveis e informações sensíveis não é uma tarefa simples. Lidar com os diversos formatos e semânticas de informações sensíveis exige um bom conhecimento do seu domínio e dos seus dados. Embora o código apresentado acima possa funcionar para alguns casos de uso, talvez seja necessário modificá-lo com base em suas necessidades e testes.

Utilizando o LlamaIndex sem nenhuma configuração adicional. NERPIINodePostprocessor

A LlamaIndex facilitou a proteção de informações de identificação pessoal (PII) em um pipeline RAG ao introduzir NERPIINodePostprocessor.

A resposta é a seguinte:

Utilizando LLMs locais via PIINodePostprocessor

Também poderíamos utilizar um LLM executado localmente ou em sua rede privada para realizar o trabalho de mascaramento antes de enviar os dados para um LLM público.

Usaremos o Mistral, executado no Ollama em sua máquina local, para fazer o mascaramento.

Execute o Mistral localmente

Baixe e instale o Ollama. Após instalar o Ollama, execute este comando para baixar e executar o mistral.

Pode levar alguns minutos para baixar e executar o modelo localmente pela primeira vez. Verifique se o mistral está ativo fazendo uma pergunta como a seguinte: "Escreva um poema sobre nuvens" e veja se você gostou do poema. Mantenha o Ollama em execução, pois precisaremos interagir com o modelo Mistral posteriormente por meio de código.

Crie um novo arquivo chamado query_masking_local_LLM.py e adicione o código abaixo.

A resposta será algo semelhante ao que é mostrado abaixo.

Conclusão

Neste post, mostramos como você pode proteger informações pessoais identificáveis (PII) e dados sensíveis ao usar LLMs públicos em um fluxo RAG. Demonstramos diversas maneiras de alcançar esse objetivo. É altamente recomendável testar essas abordagens com base em seu caso de uso e necessidades antes de adotá-las.

Antes de começarmos, vamos analisar alguns termos.

Terminologia

LlamaIndex é uma estrutura de dados líder para a construção de aplicações LLM (Large Language Model). O LlamaIndex fornece abstrações para vários estágios de construção de um aplicativo RAG (Retrieval Augmented Generation). Frameworks como LlamaIndex e LangChain fornecem abstrações para que os aplicativos não fiquem fortemente acoplados às APIs de nenhum LLM específico.

O Elasticsearch é oferecido pela Elastic. A Elastic é líder do setor e está por trás do Elasticsearch, um mecanismo de busca e análise que oferece suporte à busca de texto completo para precisão, busca vetorial para compreensão semântica e busca híbrida para o melhor dos dois mundos. O Elasticsearch é um banco de dados vetorial e um repositório de dados escalável. As funcionalidades do Elasticsearch que utilizamos neste blog estão disponíveis na versão gratuita e de código aberto do Elasticsearch.

A Geração Aumentada de Recuperação (RAG, na sigla em inglês) é uma técnica/padrão de IA em que os Modelos de Aprendizagem Baseados em Aprendizagem (LLMs, na sigla em inglês) recebem conhecimento externo para gerar respostas às consultas do usuário. Isso permite que as respostas do LLM sejam adaptadas a contextos específicos e sejam mais detalhadas.

A Mistral oferece modelos LLM de código aberto e modelos otimizados para uso empresarial. Neste tutorial, usaremos o modelo de código aberto mistral-7b , que funciona no seu computador portátil. Se você não quiser executar o modelo no seu laptop, como alternativa, pode usar a versão em nuvem. Nesse caso, você precisará modificar o código deste blog para usar as chaves de API e os pacotes corretos.

O Ollama ajuda a executar LLMs localmente no seu laptop. Usaremos o Ollama para executar o modelo de código aberto Mistral-7b localmente.

Os embeddings são representações numéricas do significado de um texto/mídia. São representações de menor dimensão de informações de alta dimensão.

Construindo uma aplicação RAG com LlamaIndex, Elasticsearch e Mistral: Visão geral do cenário

Cenário:

Temos um conjunto de dados de amostra (em formato JSON) de conversas de call center entre agentes e clientes de uma empresa fictícia de seguros residenciais. Vamos construir um aplicativo RAG simples que possa responder a perguntas como:

Give me summary of water related issues.

Fluxo de alto nível

Temos o Mistral LLM instalado e funcionando localmente usando o Ollama.

Em seguida, carregamos as conversas do arquivo JSON como Documents no ElasticsearchStore (que é um VectorStore com suporte do Elasticsearch). Ao carregar os documentos, criamos embeddings usando o modelo Mistral executado localmente. Armazenamos esses embeddings juntamente com as conversas no LlamaIndex Elasticsearch vector Store (ElasticsearchStore).

Configuramos um pipeline de ingestão LlamaIndex e o abastecemos com o LLM local que utilizamos, neste caso o Mistral executado via Ollama.

Quando fazemos uma pergunta como "Dê-me um resumo dos problemas relacionados à água", O Elasticsearch realiza uma busca semântica e retorna conversas relacionadas a questões hídricas. Essas conversas, juntamente com a pergunta original, são enviadas ao LLM local para gerar uma resposta.

Etapas para construir o aplicativo RAG

Execute o Mistral localmente

Baixe e instale o Ollama. Após instalar o Ollama, execute este comando para baixar e executar o mistral.

Pode levar alguns minutos para baixar e executar o modelo localmente pela primeira vez. Verifique se o mistral está ativo fazendo uma pergunta como a seguinte: "Escreva um poema sobre nuvens" e veja se você gostou do poema. Mantenha o Ollama em execução, pois precisaremos interagir com o modelo Mistral posteriormente por meio de código.

Instale o Elasticsearch

Instale e execute o Elasticsearch criando uma implantação na nuvem (instruções aqui) ou executando-o em um contêiner Docker (instruções aqui). Você também pode criar uma implantação auto-hospedada de nível de produção do Elasticsearch, começando aqui.

Supondo que você esteja usando a implantação em nuvem, obtenha a chave da API e o ID da nuvem para a implantação, conforme mencionado nas instruções. Vamos usá-los mais tarde.

aplicação RAG

Para referência, o código completo pode ser encontrado neste repositório do Github. Clonar o repositório é opcional, pois analisaremos o código a seguir.

Em sua IDE favorita, crie uma nova aplicação Python com os 3 arquivos abaixo.

• index.py Onde fica o código relacionado à indexação de dados.

• query.py Onde fica o código relacionado a consultas e interação com o LLM.

• .env onde ficam as propriedades de configuração, como chaves de API.

Precisamos instalar alguns pacotes. Começamos criando um novo ambiente virtual Python na pasta raiz da sua aplicação.

Ative o ambiente virtual e instale os pacotes necessários listados abaixo.

Dados de indexação

Baixe o arquivo conversations.json , que contém conversas entre clientes e atendentes de call center da nossa fictícia empresa de seguros residenciais. Coloque o arquivo no diretório raiz da aplicação, junto com os dois arquivos Python e o arquivo .env. arquivo que você criou anteriormente. Segue abaixo um exemplo do conteúdo do arquivo.

Definimos uma função chamada get_documents_from_file em index.py que lê o arquivo json e cria uma lista de Documentos. Os objetos de documento são a unidade básica de informação com a qual o LlamaIndex trabalha.

Criar Pipeline de Ingestão

Primeiramente, adicione o CloudID do Elasticsearch e as chaves de API que você obteve na seção Install Elasticsearch ao arquivo .env . Seu arquivo .env deve ter a aparência abaixo (com valores reais).

O LlamaIndex IngestionPipeline permite compor um pipeline usando vários componentes. Adicione o código abaixo ao arquivo index.py .

Conforme mencionado anteriormente, o LlamaIndex IngestPipeline pode ser composto por vários componentes. Estamos adicionando 3 componentes ao pipeline na linha pipeline = IngestionPipeline(....

• SentenceSplitter: Como pode ser visto na definição de get_documents_from_file(), cada Documento tem um campo de texto que contém a conversa encontrada no arquivo json. Este campo de texto contém um texto longo. Para que a busca semântica funcione bem, ela precisa ser dividida em blocos de texto menores. A classe SentenceSplitter faz isso por nós. Esses fragmentos são chamados de Nós na terminologia do LlamaIndex. Existem metadados nos nós que apontam de volta para o Documento ao qual pertencem. Alternativamente, você pode usar o Elasticsearch Ingestpipeline para fragmentação, conforme mostrado neste blog.

• OllamaEmbedding: Os modelos de incorporação convertem um texto em números (também chamados de vetores). A representação numérica nos permite realizar buscas semânticas, em que os resultados correspondem ao significado da palavra, em vez de apenas realizar uma busca textual. Fornecemos o IngestionPipeline com OllamaEmbedding("mistral"). Os trechos que dividimos usando o SentenceSplitter são enviados para o modelo Mistral que está sendo executado em sua máquina local por meio do Ollama. O Mistral então cria embeddings para esses trechos.

• ElasticsearchStore: O armazenamento vetorial LlamaIndex ElasticsearchStore faz backup dos embeddings que estão sendo criados em um índice do Elasticsearch. O ElasticsearchStore se encarrega de criar e preencher o conteúdo do índice Elasticsearch especificado. Ao criar o ElasticsearchStore (referenciado por es_vector_store) fornecemos o nome do índice Elasticsearch que queremos criar (calls no nosso caso ), o campo no índice onde queremos que os embeddings sejam armazenados (conversation_vector no nosso caso ) e o campo onde queremos armazenar o texto (conversation no nosso caso ). Em resumo, com base na nossa configuração ElasticsearchStore cria um novo índice no Elasticsearch com conversation_vector e conversation como campos (entre outros campos criados automaticamente).

Unindo tudo, executamos o pipeline chamando pipeline.run(documents=documents).

Execute o script index.py para iniciar o pipeline de ingestão:

Assim que a execução do pipeline for concluída, devemos ver um novo índice no Elasticsearch chamado calls. Ao executar uma consulta simples no Elasticsearch usando o Console do Desenvolvedor, você deverá conseguir ver os dados carregados juntamente com os embeddings.

Resumindo o que fizemos até agora, criamos documentos a partir de um arquivo JSON, dividimos esses documentos em partes, criamos embeddings para essas partes e armazenamos os embeddings (e a conversa de texto) em um armazenamento vetorial (ElasticsearchStore).

Consultando

O llamaIndex VectorStoreIndex permite recuperar documentos relevantes e consultar dados. Por padrão, o VectorStoreIndex armazena embeddings na memória em um SimpleVectorStore. No entanto, armazenamentos vetoriais externos (como o ElasticsearchStore) podem ser usados para tornar os embeddings persistentes.

Abra o query.py e cole o código abaixo.

Definimos um LLM local (local_llm) para apontar para o modelo Mistral em execução no Ollama. Em seguida, criamos um VectorStoreIndex (index) a partir do armazenamento de vetores ElasticssearchStore que criamos anteriormente e, em seguida, obtemos um mecanismo de consulta do índice. Ao criar o mecanismo de consulta, fazemos referência ao LLM local que deve ser usado para responder, também fornecemos (similarity_top_k=10) para configurar o número de documentos que devem ser recuperados do armazenamento de vetores e enviados ao LLM para obter uma resposta.

Execute o script query.py para executar o fluxo RAG:

Enviamos a consulta Give me summary of water related issues (sinta-se à vontade para personalizar o query) e a resposta do LLM, que é fornecida com os documentos relacionados, deve ser algo como o abaixo.

Algumas ressalvas:

Este post do blog é uma introdução para iniciantes à técnica RAG com Elasticsearch e, portanto, omite a configuração de recursos que permitirão que você leve este ponto de partida para um ambiente de produção. Ao desenvolver soluções para uso em produção, você deve considerar aspectos mais sofisticados, como a capacidade de proteger seus dados com Segurança em Nível de Documento, dividir seus dados em partes menores como parte de um pipeline de ingestão do Elasticsearch ou até mesmo executar outras tarefas de aprendizado de máquina nos mesmos dados usados para casos de uso de GenAI/Chat/Perguntas e Respostas.

Você também pode considerar a possibilidade de obter dados e criar embeddings a partir de várias fontes externas (por exemplo, Azure Blob Storage, Dropbox, Gmail etc.) usando Elastic Connectors.

A Elastic torna tudo isso e muito mais possível, oferecendo uma solução abrangente de nível empresarial para casos de uso de GenAI e além.

O que vem a seguir?

• Você deve ter notado que estamos enviando 10 conversas relacionadas, juntamente com a pergunta do usuário, para o LLM para que ele elabore uma resposta. Essas conversas podem conter informações de identificação pessoal (PII), como nome, data de nascimento, endereço etc. No nosso caso, o LLM é local, portanto o vazamento de dados não é um problema. No entanto, quando se deseja usar um LLM executado na nuvem (por exemplo, OpenAI), não é recomendável enviar textos que contenham informações de identificação pessoal. Em uma postagem de acompanhamento, veremos como realizar o mascaramento de informações PII antes de enviá-las a LLMs externos no fluxo RAG.

• Neste post, usamos um LLM local. No próximo post sobre mascaramento de dados PII no RAG, veremos como podemos migrar facilmente de um LLM local para um LLM público.