O que a compatibilidade com versões anteriores significa para a API do dashboard do Kibana

Durante a prévia técnica, a configuração da API pode mudar entre os lançamentos.[1] Esse não é mais o caso. Disponibilidade geral (GA) significa:

• Compatibilidade retrógrada completa. Novos campos e tipos de painel serão adicionados ao longo do tempo, mas os campos e comportamentos existentes permanecem inalterados. Quaisquer mudanças futuras que quebrem a compatibilidade seriam cuidadosamente consideradas e só seriam introduzidas em uma nova versão principal da pilha.

• Pronto para produção com suporte completo. A API oferece todas as garantias de compatibilidade da Elastic. Você pode usá-lo com segurança em ambientes de produção para implantações automatizadas, promoção de ambiente e gerenciamento programático do dashboard.

Novos endpoints da API Kibana para os painéis Tags, Markdown e Links

O Elastic 9.5 também introduz um novo  endpoint independente para Tags, que permite categorizar e filtrar painéis. Agora, você pode gerenciá-los programaticamente por meio de endpoints CRUD dedicados, facilitando a organização de painéis em escala entre ambientes.

Os novos endpoints para os painéis Markdown e Links já estão disponíveis no Serverless e serão lançados na próxima versão do stack (9.6).

Com quais tipos de painel a API do dashboard do Kibana é compatível?

A API do dashboard é compatível com todos os painéis definidos por valor na versão 9.5 (aqueles definidos diretamente em um dashboard, em oposição aos painéis da biblioteca salvos para reutilização). Cada tipo de painel compatível possui um esquema tipado e validado.

Tipo de painel

Status

Gráficos XY

Compatível

Métricas

Compatível

Pizza

Compatível

Medidor

Compatível

Heatmap

Compatível

Tabelas de dados

Compatível

Mapa de árvore

Compatível

Discover sessões

Compatível

Controles

Compatível

Markdown

Compatível

Links

Compatível

Painéis de ML

Compatível

Painéis de observabilidade

Compatível

Mapas

Em breve

Vega

Em breve

Como gerenciar dashboards do Kibana como código

A API de dashboards permite um fluxo de trabalho completo de dashboards como código: exportar um dashboard como JSON limpo e passível de comparação, enviá-lo ao Git como fonte de verdade, revisar mudanças em pull requests e implantar a mesma definição em desenvolvimento, staging e produção. Depois que um dashboard for gerenciado como código, trate o Git como a única fonte da verdade: as alterações feitas diretamente na UI serão substituídas na próxima vez que você implantar.

O principal desafio ao mover um dashboard entre espaços, clusters ou estágios é que os dashboards referenciam objetos como data view e visualizações da biblioteca por ID. Como esses IDs são gerados automaticamente e diferem entre ambientes, um dashboard exportado de um ambiente pode apontar para objetos que não existem em outro. Existem três maneiras de lidar com isso, listadas aqui da mais automatizada à menos automatizada:

• Use Terraform. O provedor Terraform do Elastic Stack acompanha cada recurso e mapeia os IDs automaticamente por ambiente, para que as referências permaneçam consistentes enquanto você promove um dashboard do desenvolvimento para a produção.

• Defina por-valor a Linguagem de Consulta Elasticsearch (ES|QL). A maneira mais portátil de construir um painel é definir sua visualização com o ES|QL diretamente no dashboard. Uma consulta ES|QL lê os índices que você especificar nela; portanto, o painel não contém referências externas a data views ou objetos de biblioteca. O resultado é um dashboard portátil e totalmente independente.

• Atribua IDs correspondentes. Se você fizer referência a objetos salvos, como visualizações de dados ou visualizações de bibliotecas, crie-os com um ID escolhido usando PUT (upsert) em vez de POST (que gera automaticamente um ID). Use IDs legíveis por humanos, como logs-prod, para que sejam fáceis de reutilizar e reconhecer em diferentes ambientes.

Para obter uma descrição detalhada desses padrões de portabilidade e do fluxo de trabalho completo de dashboards como código, consulte a documentação Gerenciar dashboards como código.

Crie um dashboard do Kibana com a API Dashboards usando PUT

Aqui está um exemplo rápido de criação de um dashboard com uma métrica usando PUT em vez de POST para atribuir um ID personalizado com o nome do dashboard (service-health-overview). A mesma lógica funciona para criar visualizações independentes salvas na biblioteca.

Roadmap da API do dashboard do Kibana: Maps, Vega e endpoints independentes

Estamos expandindo ativamente o escopo da API. Na sequência, compatibilidade com mapas e painéis Vega, adicionando esquemas tipados para eles. Também estamos construindo pontos finais CRUD independentes para sessões Discover (além do suporte existente como painéis de dashboard), Vega, maps e anotações, desacoplados do ciclo de vida do dashboard.

Para as definições completas de esquema, visite a documentação da API dos Dashboards. Para usuários do Terraform, o provedor Terraform do Elastic Stack é compatível com a API GA Dashboards.

Nota

1. Os endpoints núcleos permanecem inalterados em relação à prévia técnica. Se você construiu integrações contra a 9.4, elas funcionam na 9.5. As únicas alterações que quebram a compatibilidade são duas pequenas que afetam os formatos de listagem do dashboard e dos formatos da unidade de duração, documentadas aqui.

Os modelos de IA mais poderosos são executados em instalações remotas na nuvem com acesso por meio de uma API web, o que significa que você precisa confiar no seu provedor de serviços de IA para segurança, disponibilidade do serviço e preços estáveis. Você não consegue alinhar facilmente demandas razoáveis de confiabilidade, privacidade, custos gerenciáveis e boa governança de dados com o uso de IA cada vez mais poderoso, sofisticado e intensivo em recursos.

Regulamentações governamentais, decisões judiciais e considerações comerciais feitas no interesse de terceiros recentemente resultaram na restrição do acesso a serviços específicos. E mesmo que você possa alternar para outros serviços, os modelos de IA não são componentes que podem simplesmente ser trocados sempre que você quiser. Aplicações que usam embeddings semânticos dependem de ter acesso aos mesmos modelos no momento da consulta e no momento da ingestão de dados. Perder o acesso ao seu modelo de embedding significa que seu sistema de busca para completamente.

Os modelos de precificação de IA agravam esse risco. Divulgações financeiras recentes de grandes fornecedores de IA dão aos clientes bons motivos para se preocuparem com potenciais aumentos de preços. A dependência de produtos com custos imprevisíveis adiciona mais risco a investimentos em IA que exigem uso intensivo de capital e podem não produzir retornos claros.

O Jina On-Prem é a resposta da Elastic para esses desafios.

Quem precisa de IA no local?

A hospedagem local e o controle direto sobre seus modelos de IA são compatíveis com uma variedade de demandas técnicas, requisitos do setor e interesses de negócios.

A instalação local reduz o que você paga aos seus provedores de serviços de IA, mas transfere o custo de hardware e de acesso confiável para a sua organização. Dependendo do seu volume de uso, pode simplesmente ser mais barato. Mas há outras razões urgentes para considerar a execução da sua própria IA. Se algum dos problemas descritos abaixo afetar a sua empresa, considere uma solução de IA local como o Jina On-Prem. Esta lista não é exaustiva.

Caso de uso

Por que no local

Exemplo

Air-gapped / alta segurança

Sem transmissão de dados de saída; isolamento completo de rede

Defesa, inteligência, pesquisas classificadas

Conformidade regulatória

Soberania de dados; sem transmissão transfronteiriça ou exposição a terceiros

Saúde (Health Insurance Portability and Accountability Act [HIPAA]), finanças, empresas da UE (Regulamento Geral de Proteção de Dados [GDPR])

Crítico para a latência

Zero dependência de rede; nenhuma tolerância a falhas de conexão

Robótica, computação de borda, veículos, navios

Previsibilidade de custo

Custo fixo de infraestrutura vs. preço por token com taxas futuras incertas

Cargas de trabalho de inferência contínua de alto volume

Redução de passivos

Sem exposição de dados a terceiros; mantém o privilégio legal e o dever de cuidado

Escritórios de advocacia, agências governamentais

Por que sistemas air-gapped e com firewall precisam de IA no local

Sistemas air-gapped e com firewall não podem usar APIs de IA externas. O Jina On-Prem é executado inteiramente em sua infraestrutura, sem conexões de saída.

Para organizações que gerenciam dados especialmente sensíveis, as considerações de segurança e privacidade são fundamentais. Pouco adianta investir na proteção dos seus dados sensíveis se você os entrega prontamente a terceiros remotos que podem ter segurança insuficiente ou estar sujeitos às exigências de um governo estrangeiro.

Funcionários de organizações que lidam com dados sensíveis costumam receber algum treinamento sobre o tratamento seguro de dados, mas isso não é muito eficaz quando todos eles têm navegadores web que podem estar abertos em qualquer página da internet enquanto lidam com esses dados. O isolamento é a medida de segurança mais eficaz disponível, seja por meio de air-gapping ou de firewalls muito restritivos, mas isso dificulta o uso de serviços externos de qualquer tipo.

IA no local para sistemas sensíveis à latência e de alta disponibilidade

O software como serviço e a computação em nuvem representam um meio-termo entre o custo de oferecer serviços altamente acessíveis e confiáveis em seus próprios computadores e a terceirização do problema para outra pessoa. Mas eles vêm acompanhados de latência variável, interrupções e uma perda total de controle quando algo dá errado. Os serviços de IA não são exceção. Se o seu sistema de busca ficar offline quando você não puder acessar seu modelo de embedding, isso pode não parecer mais um bom meio-termo.

Além disso, confiar em IA externa sempre envolverá riscos que você não pode prever ou gerenciar facilmente. O acesso à internet e a latência da rede podem se deteriorar sem aviso prévio, como resultado de eventos políticos, mau tempo ou navios arrastando suas âncoras sobre cabos de fibra óptica submarinos. Os governos podem, e recentemente o fizeram, usar proibições de exportação para bloquear de repente o acesso a modelos de IA. Às vezes, os provedores de serviços de IA descontinuam modelos para induzir você a mudar para outros mais recentes. A flexibilidade e os custos gerenciados dos serviços externos precisam ser ponderados em relação aos riscos de dependência.

IA no local para conformidade com o GDPR, a HIPAA e a soberania dos dados

Organizações que coletam dados pessoais estão sujeitas a regulamentações cada vez mais rigorosas, que geralmente diferem entre as jurisdições e podem ter requisitos contraditórios. Notavelmente, as regras da HIPAA impõem proteções de dados muito rigorosas aos provedores de saúde norte-americanos, e leis gerais de proteção de dados fortes no Canadá, na União Europeia e em muitas jurisdições asiáticas exigem que todas as empresas que lidam com informações pessoais o façam de forma segura e limitem a transmissão desses dados a outras partes ou outras jurisdições. Essas regras podem até impor obrigações a entidades estrangeiras se elas tiverem clientes nessas jurisdições. As instituições financeiras estão frequentemente sujeitas a regras ainda mais rigorosas e possuem a mesma responsabilidade direta pela segurança da informação que têm para se protegerem contra outras formas de atividade criminosa.

A conformidade regulatória pode ser incompatível com serviços de IA de terceiros, especialmente se usá-los envolver a transmissão transfronteiriça de dados.

Além disso, eventos recentes mostram que regras que restringem a localização física dos armazenamentos de dados podem não ser uma fonte confiável de proteção quando operadores internacionais de nuvem estão sujeitos à pressão de governos estrangeiros. Leis locais podem entrar em conflito entre jurisdições, exigindo o armazenamento e processamento local de dados e tornando impossível o uso de serviços de terceiros. Em alguns casos, a única solução é internalizar todas as partes dos seus processos, incluindo seus sistemas de IA.

Riscos de responsabilidade por IA na transmissão de dados de terceiros

Leis de proteção de dados e deveres de cuidado reconhecidos em relação a dados sensíveis rotineiramente têm implicações de responsabilidade, às vezes muito severas. Você pode ser responsabilizado pelo tratamento dos seus dados por provedores de serviços terceirizados. Embora os tribunais e procedimentos legais possam fornecer algumas proteções retrospectivas contra provedores de serviços inseguros, esses recursos não estão disponíveis nem são geralmente eficazes contra agentes de segurança nacional, autoridades policiais ou hackers criminosos.

Para os governos, já houve casos em que provedores de serviços em nuvem internacionais liberaram informações estatais sensíveis para agentes estrangeiros.

Mas mesmo que você não se preocupe com governos estrangeiros ou hackers, e mesmo que seus provedores de serviços de IA externos sejam seguros, o simples fato de serem externos pode criar responsabilidades.

Por exemplo, na maioria das jurisdições, as comunicações dos advogados com seus clientes contam com proteções jurídicas especiais, e os escritórios de advocacia têm responsabilidades rígidas ao gravar ou armazenar essas informações. Nos Estados Unidos, esse "sigilo advogado-cliente" é tão famoso que é central nos enredos de filmes e séries de TV. Mas uma das maneiras pelas quais esse privilégio pode ser perdido é ao comunicar informações a alguém que não seja protegido por ele, e desenvolvimentos recentes sugerem que provedores externos de serviços de IA podem se enquadrar nisso.

É possível, pelo menos nos Estados Unidos, que o simples uso de serviços de IA de terceiros por meio de uma API de internet, como modelos de incorporação que oferecem serviços de indexação, viole regras críticas de confidencialidade. Um escritório de advocacia pode ser processado, punido disciplinarmente ou ter o registro cassado só por usar software hospedado externamente, mesmo que nenhuma violação de segurança ocorra.

IA no local para sistemas offline, de borda e fisicamente isolados

Os sistemas de computador não são isolados apenas por motivos de segurança. Por exemplo, veículos em movimento não podem depender do acesso à internet para nenhuma função essencial. Navios e aeronaves têm sistemas de computador de bordo muito extensos que precisam funcionar sem conexões com a internet e, portanto, não podem usar serviços de IA externos. Plataformas offshore, instalações remotas em áreas selvagens, serviços de computador no Ártico, na Antártida e em pequenas ilhas sem conexões físicas adequadas com redes globais são todos exemplos de instalações que se beneficiam ao hospedar localmente todos os serviços de que precisam. À medida que o papel da IA na computação empresarial cresce, torna-se mais importante abordar essas limitações.

Aplicações emergentes de IA em sistemas físicos (robótica e outros casos de uso delimitados espacialmente ou focados no mundo externo, como sistemas de gestão de logística ou até mesmo caixas de supermercado) podem estar conectadas à internet global, mas não têm tolerância a falhas de conexão ou picos de latência. Se elas dependem de um sistema de IA para operar, esse sistema de IA precisa ser o mais local e confiável possível.

Quem não precisa de IA em ambiente local?

Serviços de software remotos e IA fora do local têm benefícios. Executar modelos de IA pode exigir processadores caros, de alto consumo de energia e com vida útil notoriamente curta. O acesso a hardware de alta qualidade é particularmente difícil no momento devido a fatores de mercado e choques econômicos externos. Diante das circunstâncias, pode fazer sentido pagar por token para usar uma API externa em vez de arcar com os altos custos de capital da IA local.

APIs externas fazem mais sentido para usuários intermitentes. Se você usa modelos de IA principalmente para processar dados em lote para análise, em vez de executar um sistema de busca que precise ficar online o tempo todo, faz pouco sentido investir em hardware de alto custo de capital e instalações locais.

Além disso, quando o seu processamento de dados já é baseado na nuvem, por exemplo, um website de e-commerce hospedado na nuvem por motivos de confiabilidade e acessibilidade, usar serviços de IA localizados na mesma infraestrutura de nuvem pode proporcionar um melhor custo-benefício do que introduzir a sua própria implantação de modelo de IA licenciado. Você já depende do seu provedor de serviços em nuvem, então depender dos serviços de IA dele não adiciona muito risco.

Se o seu caso de uso se encaixa nessa descrição, os modelos Jina AI estão disponíveis no EIS, no AWS Marketplace e no Google Cloud Platform especificamente para atender às suas necessidades.

A tabela abaixo resume os principais fatores. Sua resposta depende dos seus dados, da sua infraestrutura e do seu padrão de uso.

Fator

No local preferido

API da Nuvem Preferida

Padrão de uso

Inferência contínua ou de alto volume

Processamento intermitente ou em lote

Sensibilidade dos dados

Regulado, soberano ou confidencial

Sem restrições transfronteiriças ou de terceiros

Ambiente de rede

Air-gapped, com firewall ou instáveis

Internet estável, sempre ativa

Infraestrutura existente

Possuir ou poder adquirir hardware de GPU

Já hospedado na nuvem com IA colocalizada

Modelo de custo

Hardware fixo + licença; previsível em escala

Por token; menor custo inicial, variável a longo prazo

Tolerância a latência

Nenhum (robótica, edge, tempo real)

A variabilidade da rede é aceitável

Responsabilidade operacional

Sua equipe gerencia o hardware e a disponibilidade

O provedor gerencia o hardware e as atualizações; você gerencia a integração

Você precisa considerar os custos e benefícios à luz de suas circunstâncias específicas e casos de uso, levando em consideração os problemas destacados na seção anterior que se aplicam a você. A análise de custo-benefício sem dúvida mudará ao longo do tempo. Não podemos prever o futuro do setor de IA ou os preços de hardware, mesmo no curto prazo.

Apresentando Jina no Local

Para usuários que podem se beneficiar de serviços de IA locais, estamos apresentando o Jina On-Prem, um conjunto de instalação totalmente independente para os modelos de alto desempenho da Jina AI.

Os modelos do Jina AI correspondem à precisão de modelos de embedding muitas vezes maiores que eles, reduzindo custos computacionais, uso de memória e requisitos de hardware. Isso os torna uma escolha ideal para usuários que desejam ou precisam manter sua IA no local. Licenças comerciais estão disponíveis com solutions escaláveis e de preços proporcionais para casos de uso de todos os tamanhos.

A quais esquemas de API o Jina no local oferece suporte?

• Disponível como uma coleção completa de dependências para instalação local ou como um container do Docker que você pode instalar e executar em minutos.

• Instalações Jina no local não fazem chamadas para sistemas externos.

  • Nenhuma chamada ao Hugging Face Hub ou a qualquer registro de modelo (HF_HUB_OFFLINE=1 e TRANSFORMERS_OFFLINE=1 estão embutidos).

  • Não há servidor de licença.

  • Não há endpoints de telemetria ou logging.

• Oferece suporte a hardware de CPU e GPU, com detecção automática de GPU.

• Todos os 28 modelos Jina AI disponíveis, incluindo os mais recentes modelos de embedding multimodal jina-embeddings-v5-omni e o jina-reranker-v3.

• Acesso via esquemas padrão de API de IA: Jina API, OpenAI, Cohere, Voyage AI e Gemini. O Jina On-Prem é uma solução de substituição direta para aplicações construídas com base nesses esquemas.

• Substituição direta para modelos servidos pelo EIS. O Jina On-Prem se integra diretamente com implantações da Elastic em ambientes isolados.

Requisitos de hardware para modelos Jina AI no local

Os requisitos de hardware variam para diferentes modelos Jina. A tabela abaixo mostra as recomendações para os modelos mais recentes usando configurações de GPU. Você não precisa de nada mais potente do que uma GPU NVIDIA L4, embora uma A100 seja recomendada para os modelos de embedding v5. Nosso modelo de embedding mais recente exige atualmente no mínimo 8 GB de VRAM.

Modelo

VRAM mínima

GPU Recomendada

jina-embeddings-v5-text-nano

2 GB

T4 / L4

jina-embeddings-v5-text-small

3 GB

L4 / A10G

jina-embeddings-v5-omni-small

8 GB

L4 / A10G / A100

jina-reranker-v3

3 GB

L4

jina-clip-v2

4 GB

L4

jina-code-embeddings-1.5b

4 GB

L4

ReaderLM-v2

4 GB

L4

Se você usar mais de um modelo por vez, os requisitos de VRAM aumentarão. Consulte a página de dimensionamento e hardware para obter mais informações.

Como Instalar o Jina no Local com o Docker

A maneira mais rápida de começar é instalar o Docker (se você ainda não o fez) e seguir as instruções na página do Guia rápido do Jina no local.

Há containers do Docker pré-compostos para todos os 28 modelos Jina. Baixe um e transfira-o para o seu destino de instalação, e você poderá ter os modelos Jina AI em execução em menos de cinco minutos.

Para compilações multimodais ou personalizadas, ou para baixar o conjunto completo de dependências para instalação fora de um container, siga as etapas descritas no guia de empacotamento.

Sua instalação Jina no local oferece suporte a todas as funcionalidades da Jina API e do EIS e à geração de embeddings por meio das APIs da OpenAI, Cohere, Voyage AI e Gemini, de modo que ela pode ser integrada a aplicativos preexistentes usando interfaces padrão. Consulte a documentação da API para obter mais informações.

Os modelos Jina, incluindo os modelos instalados com o Jina no local, estão disponíveis sob vários termos de licenciamento, sendo que os modelos mais recentes são gratuitos para uso não comercial sob uma licença CC BY-NC 4.0. Para licenciar o Jina no local para uso comercial, entre em contato com as vendas da Elastic.

Este post explica como os endpoints de consulta, descoberta e metadados se baseiam no trabalho anterior de ingestão e consulta para formar esse conjunto de APIs. Posts complementares aprofundam tópicos específicos:

• O suporte nativo ao PromQL no ES|QL abrange como as consultas PromQL são traduzidas em planos de execução do ES|QL.

• Enviar métricas do Prometheus para o Elasticsearch com Remote Write abrange a configuração da ingestão.

• Como funciona a ingestão de gravação remota do Prometheus no Elasticsearch aborda os aspectos internos da gravação remota.

Isso ainda está em desenvolvimento. As seções abaixo destacam o que é compatível atualmente e quais partes ainda estão evoluindo.

A superfície da API

Hoje, a interface de API compatível com Prometheus é dividida em três grupos.

Endpoints de consulta

Os endpoints de consulta permitem que clientes compatíveis com Prometheus avaliem expressões PromQL:

• GET /_prometheus/api/v1/query_range avalia uma expressão de PromQL ao longo de uma janela de tempo (resultados matriciais).

• GET /_prometheus/api/v1/query avalia em um único ponto no tempo (resultados vetoriais). Atualmente implementado como uma consulta de curto alcance que retorna a última amostra.

Atualmente, apenas GET é suportado para endpoints de consulta. Alguns clientes usam POST por padrão, então você pode precisar configurá-los para usar GET. A convenção POST do Prometheus usa payloads application/x-www-form-urlencoded, que a camada HTTP do Elasticsearch rejeita como uma proteção contra CSRF antes que a solicitação chegue ao manipulador.

Para o status completo de cobertura do PromQL, consulte a postagem complementar sobre PromQL em ES|QL.

Endpoints de metadados

Os endpoints de metadados fornecem as informações necessárias para descoberta de que os clientes precisam para autocompletar, menus suspensos de variáveis e navegação de métricas.

Os endpoints de séries, rótulos e valores de rótulos aceitam match[] seletores e um intervalo de tempo (start/end). O parâmetro match[] aceita um seletor de séries do Prometheus como http_requests_total{job="api"} e restringe a resposta às séries temporais correspondentes. Isso mantém as respostas rápidas e relevantes em clusters com grande número de métricas. Por exemplo:

O primeiro retorna todas as séries para http_requests_total onde job="api", com seus conjuntos de rótulos completos. O segundo retorna apenas os nomes dos rótulos que existem nas séries http_requests_total . O terceiro retorna apenas os valores instance que aparecem nas séries correspondentes.

GET /_prometheus/api/v1/metadata é diferente: ele retorna tipo e unidade para cada métrica, opcionalmente filtrada por nome via um parâmetro metric.

Não aceita match[] seletores nem um intervalo de tempo. No Prometheus, os metadados são coletados de alvos ativos de coleta (as linhas HELP, TYPE e UNIT que eles expõem), então a resposta não envolve uma varredura de dados. O Elasticsearch não possui um repositório de metadados dedicado como esse, então a implementação atual descobre os metadados das métricas acessando os dados de séries temporais das últimas 24 horas. Isso mantém a consulta rápida sem exigir uma varredura completa do índice. Esse período retrospectivo de 24 horas é fixo atualmente: a API de metadados do Prometheus não expõe os parâmetros start ou end que o Elasticsearch poderia usar para torná-la ajustável pelo usuário.

A seguir, você verá como funcionam os endpoints de metadados, inclusive os comandos TS_INFO e METRICS_INFO que os sustentam.

Pré-filtragem de índices

Todos os endpoints de consulta e metadados aceitam um segmento de caminho opcional {index} após /_prometheus/:

Isso restringe quais índices do Elasticsearch a consulta executa antes de qualquer avaliação de expressão começar. Em clusters com muitos fluxos de dados distribuídos entre equipes ou ambientes, isso evita a varredura de índices não relacionados e pode reduzir significativamente a latência da consulta. Você pode configurar fontes de dados separadas por padrão de indexação para fornecer às equipes acesso segmentado às suas próprias métricas.

Uma nota sobre a Escrita Remota

Para ingestão, o Elasticsearch também expõe o endpoint padrão Prometheus Remote Write:

• POST /_prometheus/api/v1/write ingere séries temporais por meio do protocolo Prometheus Remote Write v1. A versão 2 ainda não é suportada.

O Remote Write grava nos fluxos de dados de séries temporais (TSDS) existentes do Elasticsearch, não em uma camada de armazenamento separada específica do Prometheus. Os rótulos do Prometheus se tornam dimensões do TSDS e os nomes das métricas se tornam campos no mapeamento do índice. A publicação sobre a arquitetura de gravação remota aborda o mapeamento completo em detalhes, inclusive como os tipos de métricas são deduzidos e como os rótulos são armazenados com um prefixo labels..

Como funciona

Nos bastidores, todos os endpoints funcionam da mesma forma: analisam os parâmetros HTTP de entrada, constroem um plano de execução ES|QL, executam-no contra fluxos de dados de séries temporais e convertem o resultado colunar de volta para o formato JSON que os clientes do Prometheus esperam.

TS_INFO e METRICS_INFO

Os endpoints de metadados precisam responder a perguntas como "quais rótulos existem?" ou "quais tipos de métricas estão definidos?" em potencialmente milhões de séries temporais, sem varrer cada ponto de dados.

Internamente, os endpoints de metadados do Prometheus respondem a essas perguntas construindo planos ES|QL em torno de dois novos comandos de processamento: METRICS_INFO e TS_INFO. Você não precisa usar esses comandos diretamente para usar a API do Prometheus, mas eles são as primitivas centrais de execução por trás das respostas dos metadados. Ambos funcionam acessando apenas um documento por série temporal para extrair seus metadados, em vez de varrer todas as amostras. Isso significa que o custo deles escala de acordo com o número de séries temporais distintas, não com o número de pontos de dados.

METRICS_INFO retorna uma linha por métrica distinta com seu nome, tipo, unidade e campos de dimensão associados. TS_INFO é mais detalhado: uma linha por combinação de métrica e série temporal, incluindo os valores reais das dimensões como objeto JSON.

Um post do blog dedicado sobre TS_INFO e METRICS_INFO será publicado em breve, abordando o modelo de execução em duas fases, como eles escalam e como usá-los diretamente no ES|QL além da API do Prometheus.

Como os endpoints de metadados usam esses recursos

Cada endpoint de metadados constrói um plano ES|QL com um desses comandos em seu núcleo.

/api/v1/labels e /api/v1/series usam TS_INFO, já que precisam de detalhes por série temporal (quais rótulos existem, quais valores de dimensão identificam cada série). /api/v1/metadata e /api/v1/label/__name__/values usam METRICS_INFO, já que precisam apenas de informações por métrica (nomes de métricas, tipos, unidades).

/api/v1/label/{name}/values para rótulos normais (qualquer coisa diferente de __name__) não usa nenhum dos comandos. Rótulos regulares como job ou instance são campos de dimensão reais no índice, portanto o endpoint pode consultá-los diretamente com uma agregação group-by. Quando match[] seletores são fornecidos, eles são convertidos em uma cláusula WHERE que filtra as séries temporais antes que a agregação seja executada.

O rótulo __name__ precisa de uma estratégia diferente porque nem sempre está presente como um campo dimensional. O Prometheus Remote Write armazena labels.__name__, mas métricas ingeridas por meio de outros caminhos (OpenTelemetry, a Bulk API) não possuem isso. O nome da métrica é codificado no próprio nome do campo (por exemplo, metrics.http_requests_total). Você poderia olhar os mapeamentos de índice para enumerar nomes de campos, mas mapeamentos, por si só, não informam qual métrica tem quais dimensões, e eles não podem ser filtrados pelos valores de rótulos de um seletor match[]. METRICS_INFO pode fazer ambos: enumera nomes de métricas entre índices enquanto respeita os filtros upstream WHERE.

Em todos os casos, a camada da API lida com a tradução de volta para as convenções do Prometheus: removendo os prefixos de armazenamento labels. e metrics. e gerando automaticamente __name__ para métricas não-Prometheus que não o possuem.

Conclusão

O resultado: qualquer cliente compatível com o Prometheus pode consultar e explorar as métricas do Elasticsearch por meio de endpoints que ele já entende. As métricas de gravação remota, as métricas do OpenTelemetry e as métricas indexadas por outros caminhos aparecem por meio da mesma API, com suporte dos mesmos índices TSDS.

Todas as APIs do Prometheus mencionadas aqui estão disponíveis como prévia técnica no Elasticsearch Serverless hoje. Para clusters autogerenciados e implantações hospedadas no Elastic Cloud Hosted, as APIs estão disponíveis como prévia técnica no Elasticsearch 9.4, com exceção de GET /_prometheus/api/v1/metadata. Para experimentar localmente, use start-local.

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

Por que criar um servidor MCP do Elasticsearch personalizado?

A Elastic oferece algumas alternativas para servidores MCP:

• Servidor MCP do Elastic Agent Builder para Elasticsearch 9.2+

• Servidor MCP do Elasticsearch para versões mais antigas (Python)

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

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

Pré-requisitos:

• Node.js 20 +

• Elasticsearch

• Chave de API da OpenAI

• Claude Desktop

O que é MCP?

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

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

Clientes do MCP

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

Criando um servidor MCP do Elasticsearch

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

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

1. Configure o servidor MCP para o Elasticsearch.

2. Carregue o servidor MCP no Claude Desktop.

3. Faça o teste.

Configure o servidor MCP para o Elasticsearch

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

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

• @elastic/elasticsearch nos dará acesso à biblioteca Elasticsearch Node.js.

• @modelcontextprotocol/sdk fornece as ferramentas de núcleo para criar e gerenciar um servidor MCP, registrar ferramentas e lidar com a comunicação com clientes MCP.

• openai permite a interação com modelos OpenAI para gerar resumos ou respostas em linguagem natural.

• zodajuda a definir e validar esquemas estruturados para dados de entrada e saída em cada ferramenta.

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

Configurar o conjunto de dados

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

Para ingerir os dados, preparamos um script que cria um índice no Elasticsearch e carrega o conjunto de dados nele. Você pode encontrá-lo aqui.

Servidor MCP

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

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

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

Saiba mais sobre saídas estruturadas aqui.

Agora vamos inicializar o servidor MCP:

Definição das ferramentas MCP

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

• search_docs: Busca por documentos no Elasticsearch usando busca de texto completo.

• summarize_and_cite: Resume e sintetiza informações de documentos previamente recuperados para responder a uma pergunta do usuário. Essa ferramenta também adiciona citações que referenciam os documentos fonte.

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

Formato de resposta da ferramenta

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

• Conteúdo: esta é a resposta da ferramenta em um formato não estruturado. Este campo geralmente é usado para retornar texto, imagens, áudio, links ou embeddings. Para esta aplicação, ele será usado para retornar texto formatado com as informações geradas pelas ferramentas.

• structuredContent: Esse é um retorno opcional usado para fornecer os resultados de cada ferramenta em um formato estruturado. É útil para fins programáticos. Embora não seja usado neste servidor MCP, pode ser útil caso você queira desenvolver outras ferramentas ou processar os resultados programaticamente.

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

Ferramenta de Busca de Documentos

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

Configuramos fuzziness: “AUTO” para ter uma tolerância variável de erros de digitação com base no comprimento do token que está sendo analisado. Também definimos title^2 para aumentar a pontuação dos documentos onde a correspondência ocorre no campo de título.

Ferramenta summarize_and_cite

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

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

Agora compile o projeto usando o seguinte comando:

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

Carregue o servidor MCP no Claude Desktop

Siga este guia para configurar o servidor MCP com o Claude Desktop. No arquivo de configuração Claude, precisamos definir os seguintes valores:

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

Faça o teste

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

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

Para a pergunta “Buscar documentos sobre métodos de autenticação e controle de acesso por função”, a ferramenta search_docs é executada e retorna os seguintes resultados:

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

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

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

Neste caso, para a consulta “Quais são as principais recomendações para melhorar a autenticação e o controle de acesso em nossos sistemas? Inclua referências.”, obtivemos os seguintes resultados:

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

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

Conclusão

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

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

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

Pré-requisitos

• Elasticsearch 9.3 ou Elastic Cloud Serverless: você pode criar uma implantação na nuvem seguindo essas instruções, ou você pode usar o start-local quickstart.

• Python 3.12: baixe o Python aqui.

• Hugging Face Token de acesso.

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

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

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

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

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

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

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

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

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

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

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

Configurando o endpoint de inferência no Hugging Face

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

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

Vamos escolher o modelo SmolLM3-3B :

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

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

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

Gerando a Chave API do Hugging Face

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

Configurando o endpoint de inferência do Elasticsearch

Primeiro, vamos declarar um cliente Elasticsearch Python:

Em seguida, vamos criar um endpoint de inferência no Elasticsearch que use o modelo Hugging Face. Esse endpoint nos permitirá gerar respostas com base nos posts do blog e no prompt passado para o modelo.

Conjunto de dados

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

Mapeamento do Elasticsearch

Com o conjunto de dados definido, precisamos criar um esquema de dados que se ajuste adequadamente à estrutura do post do blog. Os seguintes mapeamentos de índice serão usados para armazenar os dados no Elasticsearch:

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

Ingestão de dados

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

Agora que os artigos já estão no Elasticsearch, precisamos criar uma função capaz de buscar no campo semantic_text:

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

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

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

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

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

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

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

Conclusão

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

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

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

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

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

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

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

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

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

Configurar o Elasticsearch

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

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

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

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

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

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

Instale a extensão do Elasticsearch

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

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

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

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

• Obtenha a URL do seu servidor MCP em Agents > View all tools > Manage MCP > Copy MCP Server URL (Agentes > Ver todas as ferramentas > Gerenciar MCP > Copiar URL do Servidor MCP).

• A URL ficará assim: https://your-kibana-instance/api/agent_builder/mcp

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

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

• No Kibana: Stack Management > Security > API Keys > Create API Key (Stack management > Segurança > Chaves de API > Criar chave de API) .

• Sugerimos definir apenas os privilégios de leitura para a chave API, habilitando o privilégio feature_agentBuilder.read conforme reportado aqui.

• Copie o valor da chave de API codificada.

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

Instale o conjunto de dados de exemplo

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

• Informações do cliente (nome, ID, data de nascimento, e-mail e mais).

• Data do pedido.

• ID do pedido.

• Produtos (lista de todos os produtos com preço, quantidade, ID, categoria, desconto e outros detalhes).

• SKU.

• Preço total (sem impostos, com impostos).

• Quantidade total.

• Informações geográficas (cidade, país, continente, localização, região).

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

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

Como usar o Elasticsearch MCP

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

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

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

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

• Give me the list of all the indexes available in Elasticsearch.

• How many customers are based in the USA in the kibana_sample_data_ecommerce index of Elasticsearch?

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

Os comandos /elastic

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

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

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

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

Como usar as habilidades do Elasticsearch

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

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

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

O que a habilidadeesqloferece:

• Descoberta de índices e esquemas: o agente pode usar as ferramentas integradas da habilidade para listar os índices disponíveis e buscar mapeamentos de campo. Por exemplo, antes de escrever uma consulta para o conjunto de dados de comércio eletrônico, o agente pode executar uma verificação de esquema em kibana_sample_data_ecommerce para entender os campos disponíveis, como taxful_total_price ou category.

• Tradução perfeita da linguagem natural: a habilidade dá ao agente mais do que um simples manual de referência; ela fornece um guia específico para interpretar a intenção do usuário. Quando você digita solicitações em linguagem natural, como "Mostrar tempo médio de resposta agrupado por serviço", o agente usa o padrão de correspondência da habilidade para traduzir instantaneamente suas palavras nas agregações, filtros e comandos ES|QL corretos.

• Autocorreção: Se uma consulta falhar (por exemplo, devido a uma incompatibilidade de tipo ou erro de sintaxe), a skill retorna a consulta gerada juntamente com a mensagem de erro exata do Elasticsearch, permitindo que o agente corrija instantaneamente a consulta e tente novamente sem que você precise intervir.

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

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

O agente irá:

• Reconheça a necessidade da habilidade esql .

• Verifique o esquema do kibana_sample_data_ecommerce.

• Crie uma consulta ES|QL, como: FROM kibana_sample_data_ecommerce | STATS total_revenue = SUM(taxful_total_price) BY category.keyword | SORT total_revenue DESC | LIMIT 5.

• Execute a consulta na API do Elasticsearch.

• Apresente a resposta final para você diretamente no terminal.

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

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

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

Conclusão

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

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

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

Os modelos Jina se enquadram em três grandes categorias, projetadas para dar suporte ao processamento, à organização e à recuperação de informações:

• Modelos de embedding semântico

• Modelos de reclassificação

• Modelos de linguagem generativos de pequeno porte

Modelos de embedding semântico

A ideia por trás dos embeddings semânticos é que um modelo de IA pode aprender a representar aspectos do significado de suas entradas em termos da geometria de espaços de alta dimensionalidade.

É possível pensar em um embedding semântico como um ponto (tecnicamente, um vetor) em um espaço de alta dimensionalidade. Um modelo de embedding é uma rede neural que recebe algum tipo de dado digital como entrada, potencialmente qualquer tipo, mas mais comumente texto ou imagem, e produz a localização de um ponto correspondente em um espaço de alta dimensionalidade, representada por um conjunto de coordenadas numéricas. Quando o modelo executa bem sua função, a distância entre dois embeddings semânticos é proporcional ao quanto os objetos digitais correspondentes compartilham o mesmo significado.

Para entender por que isso é importante para aplicações de busca, imagine um embedding para a palavra “cão” e outro para a palavra “gato” como pontos em um espaço.

Um bom modelo de embedding deve gerar um embedding para a palavra “felino” muito mais próximo de “gato” do que de “cão”, e “canino” deve ter um embedding muito mais próximo de “cão” do que de “gato”, porque essas palavras têm praticamente o mesmo significado.

Se um modelo for multilíngue, espera-se o mesmo comportamento para traduções de “gato” e “cão” em outros idiomas.

Modelos de embedding traduzem similaridade ou dissimilaridade de significado entre elementos em relações espaciais entre embeddings. As imagens acima têm apenas duas dimensões para que seja possível visualizá-las na tela, mas modelos de embedding produzem vetores com dezenas a milhares de dimensões. Isso permite codificar sutilezas de significado para textos inteiros, atribuindo um ponto em um espaço com centenas ou milhares de dimensões a documentos com milhares de palavras ou mais.

Embeddings multimodais

Modelos multimodais estendem o conceito de embeddings semânticos para além de textos, especialmente para imagens. Espera-se que o embedding de uma imagem fique próximo ao embedding de uma descrição fiel dessa imagem.

Embeddings semânticos têm muitos usos. Entre outras aplicações, é possível usá-los para criar classificadores eficientes, realizar clustering de dados e executar diversas tarefas, como deduplicação de dados e investigação da diversidade dos dados, ambas importantes para aplicações de big data que lidam com volumes de informação grandes demais para serem gerenciados manualmente.

O principal uso direto de embeddings está na recuperação de informações. O Elasticsearch pode armazenar objetos de recuperação com embeddings como chaves. As consultas são convertidas em vetores de embedding, e a busca retorna os objetos armazenados cujas chaves estão mais próximas do embedding da consulta.

Enquanto a recuperação tradicional baseada em vetores (às vezes chamada de recuperação por vetores esparsos) usa vetores baseados em palavras ou metadados presentes em documentos e consultas, a recuperação baseada em embeddings (também conhecida como recuperação por vetores densos) usa significados avaliados por IA em vez de palavras. Isso a torna, em geral, muito mais flexível e mais precisa do que métodos tradicionais de busca.

Aprendizado de representação Matryoshka

O número de dimensões de um embedding, assim como a precisão dos valores numéricos que o compõem, tem impactos significativos na performance. Espaços de dimensionalidade muito alta e números de precisão extremamente elevada podem representar informações altamente detalhadas e complexas, mas exigem modelos de IA maiores, mais caros para treinar e para executar. Os vetores que esses modelos geram requerem mais espaço de armazenamento, e são necessários mais ciclos de computação para calcular as distâncias entre eles. Usar modelos de embedding semântico envolve fazer concessões importantes entre precisão e consumo de recursos.

Para maximizar a flexibilidade para os usuários, os modelos Jina são treinados com uma técnica chamada Aprendizado de Representação Matryoshka. Essa abordagem faz com que os modelos concentrem as distinções semânticas mais importantes nas primeiras dimensões do vetor de embedding, de modo que seja possível descartar as dimensões mais altas e ainda assim obter bom desempenho.

Na prática, isso significa que usuários dos modelos Jina podem escolher quantas dimensões desejam que seus embeddings tenham. Escolher menos dimensões reduz a precisão, mas a degradação de performance é pequena. Na maioria das tarefas, as métricas de performance dos modelos Jina caem entre 1% e 2% sempre que o tamanho do embedding é reduzido em 50%, até uma redução total de cerca de 95% no tamanho.

Recuperação assimétrica

A similaridade semântica geralmente é medida de forma simétrica. O valor obtido ao comparar “gato” com “cão” é o mesmo que ao comparar “cão” com “gato”. No entanto, quando embeddings são usados para recuperação de informações, o desempenho melhora quando essa simetria é quebrada e as consultas são codificadas de forma diferente dos objetos de recuperação.

Isso ocorre por causa da forma como treinamos modelos de embedding. Os dados de treinamento contêm ocorrências dos mesmos elementos, como palavras, em muitos contextos diferentes, e os modelos aprendem semântica comparando similaridades e diferenças contextuais entre esses elementos.

Assim, por exemplo, pode acontecer de a palavra “animal” não aparecer em muitos dos mesmos contextos que “gato” ou “cão”, e, portanto, o embedding de “animal” não ficar particularmente próximo de “gato” ou “cão”.

Isso torna menos provável que uma consulta por “animal” recupere documentos sobre gatos e cães — justamente o oposto do nosso objetivo. Por isso, em vez disso, codificamos “animal” de forma diferente quando ele aparece como consulta do que quando é um alvo de recuperação.

Recuperação assimétrica significa usar um modelo diferente para consultas ou treinar especificamente um modelo de embedding para codificar os dados de uma forma quando são armazenados para recuperação e de outra forma quando são usados como consultas.

Embeddings multivetoriais

Embeddings únicos funcionam bem para recuperação de informações porque se encaixam no modelo básico de um banco de dados indexado: armazenamos objetos para recuperação usando um único vetor de embedding como chave de recuperação. Quando usuários consultam o repositório de documentos, suas consultas são traduzidas em vetores de embedding, e os documentos cujas chaves estão mais próximas do embedding da consulta, no espaço de embeddings de alta dimensionalidade, são recuperados como candidatos.

Embeddings multivetoriais funcionam de forma um pouco diferente. Em vez de gerar um vetor de comprimento fixo para representar uma consulta e um objeto armazenado inteiro, eles produzem uma sequência de embeddings que representam partes menores desses elementos. Essas partes geralmente são tokens ou palavras no caso de textos, e blocos de imagem no caso de dados visuais. Esses embeddings refletem o significado de cada parte dentro de seu contexto.

Por exemplo, considere estas frases:

• Ela tinha um coração de ouro.

• Ela fez das tripas coração.

• Ela teve um ataque do coração.

Superficialmente, essas frases parecem muito semelhantes, mas um modelo multivetorial provavelmente geraria embeddings bem diferentes para cada ocorrência de “coração”, representando como cada uma assume um significado distinto no contexto da frase como um todo.

Comparar dois objetos por meio de seus embeddings multivetoriais geralmente envolve medir a distância de Chamfer: comparar cada parte de um embedding multivetorial com cada parte de outro e somar as menores distâncias entre elas. Outros sistemas, incluindo os reclassificadores Jina descritos abaixo, usam esses embeddings como entrada para um modelo de IA treinado especificamente para avaliar sua similaridade. Ambas as abordagens normalmente apresentam maior precisão do que a simples comparação de embeddings de vetor único, porque embeddings multivetoriais contêm informações muito mais detalhadas do que embeddings de vetor único.

No entanto, embeddings multivetoriais não são adequados para indexação. Eles costumam ser usados em tarefas de reclassificação, conforme descrito para o modelo jina-colbert-v2 na próxima seção.

Modelos de embedding Jina

Jina embeddings v4

jina-embeddings-v4 é um modelo de embedding multilíngue e multimodal, com 3,8 bilhões (3,8 × 10⁹) de parâmetros, que oferece suporte a imagens e textos em diversos idiomas amplamente utilizados. Ele utiliza uma arquitetura inédita para aproveitar conhecimento visual e conhecimento linguístico, melhorando o desempenho em ambas as tarefas e permitindo que o modelo se destaque na recuperação de imagens e, especialmente, na recuperação de documentos visuais. Isso significa que ele lida bem com imagens como gráficos, slides, mapas, capturas de tela, digitalizações de páginas e diagramas — tipos comuns de imagens que muitas vezes contêm texto incorporado importante e que ficam fora do escopo de modelos de visão computacional treinados apenas com imagens de cenas do mundo real.

Otimizamos esse modelo para diversas tarefas diferentes usando adaptadores compactos de Low-Rank Adaptation (LoRA). Isso nos permite treinar um único modelo para se especializar em múltiplas tarefas, sem comprometer o desempenho em nenhuma delas, com um custo adicional mínimo de memória ou processamento.

Os principais recursos incluem:

• Desempenho de ponta na recuperação de documentos visuais, além de suporte a texto multilíngue e imagens comuns com resultados que superam significativamente modelos muito maiores.

• Suporte a grandes tamanhos de contexto de entrada: 32.768 tokens equivalem aproximadamente a 80 páginas de texto em inglês com espaçamento duplo, e 20 megapixels equivalem a uma imagem de 4.500 × 4.500 pixels.

• Tamanhos de embedding selecionáveis pelo usuário, de um máximo de 2.048 dimensões até 128 dimensões. Constatamos empiricamente que o desempenho se degrada de forma acentuada abaixo desse limite.

• Suporte tanto a embeddings únicos quanto a embeddings multivetoriais. Para textos, a saída multivetorial consiste em um embedding de 128 dimensões para cada token de entrada. Para imagens, é gerado um embedding de 128 dimensões para cada bloco de 28 × 28 pixels necessário para cobrir a imagem.

• Otimização para recuperação assimétrica por meio de um par de adaptadores LoRA treinados especificamente para esse propósito.

• Um adaptador LoRA otimizado para cálculo de similaridade semântica.

• Suporte especial a linguagens de programação e estruturas de TI, também por meio de um adaptador LoRA.

Desenvolvemos jina-embeddings-v4 para atuar como uma ferramenta geral e multifuncional para uma ampla gama de tarefas comuns de busca, compreensão de linguagem natural e análise com IA. Apesar de ser relativamente pequeno considerando suas capacidades, ainda exige recursos significativos para implantação e é mais adequado para uso por meio de uma API em nuvem ou em ambientes de alto volume.

Jina embeddings v3

jina-embeddings-V3 é um modelo de embedding compacto, multilíngue, somente para texto, com alto desempenho e menos de 600 milhões de parâmetros. Ele oferece suporte a até 8.192 tokens de texto de entrada e gera embeddings de vetor único com tamanhos escolhidos pelo usuário, desde o padrão de 1.024 dimensões até 64.

Treinamos jina-embeddings-v3 para uma variedade de tarefas de texto — não apenas recuperação de informações e similaridade semântica, mas também tarefas de classificação, como análise de sentimento e moderação de conteúdo, além de tarefas de clusterização, como agregação de notícias e recomendação. Assim como jina-embeddings-v4, esse modelo oferece adaptadores LoRA especializados para as seguintes categorias de uso:

• Recuperação assimétrica

• Similaridade semântica

• Classificação

• Clustering

jina-embeddings-v3 é um modelo muito menor do que jina-embeddings-v4 com um tamanho de contexto de entrada significativamente reduzido, mas com custo operacional mais baixo. Ainda assim, apresenta desempenho bastante competitivo, embora apenas para textos, e é uma escolha melhor para muitos casos de uso.

Incorporações de código Jina

Os modelos especializados de embedding de código da Jina — jina-code-embeddings (0.5b e 1.5b) — oferecem suporte a 15 esquemas de programação e estruturas, além de textos em inglês relacionados a computação e tecnologia da informação. São modelos compactos, com meio bilhão (0,5 × 10⁹) e um bilhão e meio (1,5 × 10⁹) de parâmetros, respectivamente. Ambos oferecem suporte a tamanhos de contexto de entrada de até 32.768 tokens e permitem que os usuários escolham os tamanhos dos embeddings de saída, de 896 a 64 dimensões no modelo menor e de 1.536 a 128 no modelo maior.

Esses modelos oferecem suporte a recuperação assimétrica para cinco especializações específicas de tarefa, usando ajuste de prefixo em vez de adaptadores LoRA:

• Código para código. Recuperar código semelhante entre diferentes linguagens de programação. Isso é usado para alinhamento de código, deduplicação de código e suporte a portabilidade e refatoração.

• Linguagem natural para código. Recuperar código que corresponda a consultas em linguagem natural, comentários, descrições e documentação.

• Código para linguagem natural. Associar código a documentação ou a outros textos em linguagem natural.

• Conclusão de código para código. Sugerir código relevante para completar ou aprimorar código existente.

• Perguntas e respostas técnicas. Identificar respostas em linguagem natural para perguntas sobre tecnologias da informação, sendo ideal para casos de uso de suporte técnico.

Esses modelos oferecem performance superior em tarefas que envolvem documentação técnica e materiais de programação, com um custo computacional relativamente baixo. Eles são bem adequados para integração em ambientes de desenvolvimento e assistentes de código.

Jina ColBERT v2

jina-colbert-v2 é um modelo de embedding de texto multivetorial com 560 milhões de parâmetros. Ele é multilíngue, treinado com materiais em 89 idiomas, e oferece suporte a tamanhos variáveis de embedding e recuperação assimétrica.

Como observado anteriormente, embeddings multivetoriais não são adequados para indexação, mas são muito úteis para aumentar a precisão dos resultados de outras estratégias de busca. Com jina-colbert-v2, é possível calcular embeddings multivetoriais antecipadamente e usá-los para reclassificar candidatos à recuperação no momento da consulta. Essa abordagem é menos precisa do que usar um dos modelos de reclassificação descritos na próxima seção, mas é muito mais eficiente, pois envolve apenas a comparação de embeddings multivetoriais armazenados, em vez de invocar todo o modelo de IA para cada consulta e cada correspondência candidata. Ela é especialmente adequada para casos de uso em que a latência e a sobrecarga computacional dos modelos de reclassificação são excessivas ou em que o número de candidatos a comparar é grande demais para esse tipo de modelo.

Esse modelo gera uma sequência de embeddings, um por token de entrada, e os usuários podem selecionar embeddings de tokens com 128, 96 ou 64 dimensões. As correspondências de texto candidatas são limitadas a 8.192 tokens. As consultas são codificadas de forma assimétrica, portanto é necessário especificar se um texto é uma consulta ou uma correspondência candidata, além de limitar consultas a 32 tokens.

Jina CLIP v2

jina-clip-v2 é um modelo de embedding multimodal com 900 milhões de parâmetros, treinado para que textos e imagens gerem embeddings próximos entre si quando o texto descreve o conteúdo da imagem. Seu uso principal é a recuperação de imagens com base em consultas textuais, mas ele também é um modelo somente de texto com alto desempenho, reduzindo custos para os usuários, já que não é necessário manter modelos separados para recuperação de texto para texto e de texto para imagem.

Esse modelo oferece suporte a um contexto de entrada de texto de 8.192 tokens, e as imagens são redimensionadas para 512 × 512 pixels antes da geração dos embeddings.

Arquiteturas de pré-treinamento contrastivo de linguagem e imagem (CLIP) são fáceis de treinar e operar e podem gerar modelos muito compactos, mas apresentam algumas limitações fundamentais. Eles não conseguem usar conhecimento de um meio para melhorar seu desempenho em outro. Ou seja, não conseguem aproveitar informações de um meio para aprimorar o desempenho em outro. Assim, embora um modelo possa saber que as palavras “cão” e “gato” são mais próximas em significado entre si do que qualquer uma delas em relação a “carro”, ele não necessariamente saberá que a imagem de um cão e a imagem de um gato são mais relacionadas entre si do que qualquer uma delas em relação à imagem de um carro.

Esses modelos também sofrem do que se chama de lacuna de modalidade: um embedding de um texto sobre cães tende a ficar mais próximo de um embedding de um texto sobre gatos do que de um embedding de uma imagem de cães. Por causa dessa limitação, recomendamos usar CLIP como um modelo de recuperação de texto para imagem ou como um modelo somente de texto, mas não misturar os dois em uma única consulta.

Modelos de reclassificação

Modelos de reclassificação recebem como entrada uma consulta e uma ou mais correspondências candidatas e as comparam diretamente, produzindo correspondências com precisão muito maior.

Em princípio, seria possível usar um reclassificador diretamente para recuperação de informações, comparando cada consulta com cada documento armazenado, mas isso seria computacionalmente muito caro e impraticável para qualquer coleção que não seja muito pequena. Por isso, reclassificadores tendem a ser usados para avaliar listas relativamente curtas de correspondências candidatas encontradas por outros meios, como busca baseada em embeddings ou outros algoritmos de recuperação. Modelos de reclassificação são ideais para esquemas de busca híbrida e federada, nos quais executar uma busca pode significar enviar consultas a sistemas de busca separados, com conjuntos de dados distintos, cada um retornando resultados diferentes. Eles funcionam muito bem para combinar resultados diversos em um único resultado de alta qualidade.

A busca baseada em embeddings pode exigir um grande investimento, envolvendo a reindexação de todos os dados armazenados e a mudança das expectativas dos usuários em relação aos resultados. Adicionar um reclassificador a um esquema de busca existente pode trazer muitos dos benefícios da IA sem a necessidade de reestruturar toda a solução de busca.

Modelos de reclassificação Jina

Jina Reranker m0

jina-reranker-m0 é um reclassificador multimodal com 2,4 bilhões (2,4 × 10⁹) de parâmetros, que oferece suporte a consultas textuais e a correspondências candidatas compostas por textos e/ou imagens. Ele é o principal modelo para recuperação de documentos visuais, o que o torna uma solução ideal para repositórios de PDFs, digitalizações de texto, capturas de tela e outras imagens geradas ou modificadas por computador que contêm texto ou outras informações semiestruturadas, bem como para dados mistos compostos por documentos de texto e imagens.

Esse modelo recebe uma única consulta e uma correspondência candidata e retorna uma pontuação. Quando a mesma consulta é usada com diferentes candidatos, as pontuações são comparáveis e podem ser usadas para ranqueá-los. Ele oferece suporte a um tamanho total de entrada de até 10.240 tokens, incluindo o texto da consulta e o texto ou imagem candidata. Cada bloco de 28 × 28 pixels necessário para cobrir uma imagem conta como um token no cálculo do tamanho de entrada.

Jina Reranker v3

jina-reranker-v3 é um reclassificador de texto com 600 milhões de parâmetros, com desempenho de ponta entre modelos de tamanho comparável. Ao contrário de jina-reranker-m0, ele recebe uma única consulta e uma lista de até 64 correspondências candidatas e retorna a ordem de ranqueamento. Ele tem um contexto de entrada de 131.000 tokens, incluindo a consulta e todos os candidatos de texto.

Jina Reranker v2

jina-reranker-v2-base-multilingual é um reclassificador multifuncional, de uso geral, muito compacto, com recursos adicionais projetados para oferecer suporte a chamadas de função e consultas SQL. Com menos de 300 milhões de parâmetros, ele fornece reclassificação de texto multilíngue rápida, eficiente e precisa, com suporte adicional para selecionar tabelas SQL e funções externas que correspondam a consultas de texto, o que o torna adequado para casos de uso com IA agêntica.

Modelos de linguagem generativos de pequeno porte

Modelos de linguagem generativos são modelos como o ChatGPT da OpenAI, o Google Gemini e o Claude, da Anthropic, que recebem entradas em texto ou multimídia e respondem com saídas em texto. Não existe um limite bem definido que separe modelos de linguagem grandes (LLMs) de modelos de linguagem pequenos (SLMs), mas os desafios práticos de desenvolver, operar e usar LLMs de ponta são bem conhecidos. Os modelos mais conhecidos não são distribuídos publicamente, portanto só é possível estimar seu tamanho, mas espera-se que ChatGPT, Gemini e Claude estejam na faixa de 1 a 3 trilhões (1–3 × 10¹²) de parâmetros.

Executar esses modelos, mesmo quando estão disponíveis publicamente, está muito além do alcance de hardware convencional, exigindo os chips mais avançados organizados em grandes arranjos paralelos. É possível acessar LLMs por meio de APIs pagas, mas isso envolve custos significativos, alta latência e dificuldades para atender a exigências de proteção de dados, soberania digital e repatriação de nuvem. Além disso, os custos relacionados ao treinamento e à personalização de modelos desse porte podem ser consideráveis.

Consequentemente, uma grande quantidade de pesquisa tem se concentrado no desenvolvimento de modelos menores que, embora não tenham todas as capacidades dos maiores LLMs, conseguem executar tipos específicos de tarefas com a mesma qualidade, a um custo reduzido. Empresas normalmente implantam software para resolver problemas específicos, e com software de IA não é diferente; por isso, soluções baseadas em SLMs costumam ser preferíveis às baseadas em LLMs. Elas geralmente podem ser executadas em hardware comum, são mais rápidas, consomem menos energia e são muito mais fáceis de personalizar.

As ofertas de SLM da Jina estão crescendo à medida que nos concentramos em como levar IA da melhor forma possível a soluções práticas de busca.

Jina SLMs

ReaderLM v2

ReaderLM-v2 é um modelo de linguagem generativo que converte HTML em Markdown ou em JSON, de acordo com esquemas JSON fornecidos pelo usuário e instruções em linguagem natural.

O pré-processamento e a normalização de dados são uma parte essencial do desenvolvimento de boas soluções de busca para dados digitais, mas dados do mundo real, especialmente informações derivadas da web, costumam ser caóticos, e estratégias simples de conversão frequentemente se mostram frágeis. Em vez disso, ReaderLM-v2 oferece uma solução inteligente baseada em modelo de IA, capaz de entender o caos de um dump de árvore DOM de uma página da web e identificar, de forma robusta, elementos úteis.

Com 1,5 bilhão (1,5 × 10⁹) de parâmetros, esse modelo é três ordens de magnitude mais compacto do que LLMs de última geração, mas apresenta desempenho equivalente a eles nessa tarefa específica e bastante restrita.

Jina VLM

jina-VLC é um modelo de linguagem generativo com 2,4 bilhões (2,4 × 10⁹) de parâmetros, treinado para responder a perguntas em linguagem natural sobre imagens. Ele oferece suporte muito robusto a análise de documentos visuais, isto é, responder a perguntas sobre digitalizações, capturas de tela, slides, diagramas e dados de imagem semelhantes que não são naturais.

Por exemplo:

Ele também é muito eficiente na leitura de texto em imagens:

Mas é na compreensão do conteúdo de imagens informativas e produzidas pelo ser humano que jina-vlm realmente se destaca:

Ou:

jina-vlm é especialmente adequado para geração automática de legendas, descrições de produtos, texto alternativo de imagens e aplicações de acessibilidade para pessoas com deficiência visual. Além disso, cria novas possibilidades para sistemas de geração aumentada por recuperação (RAG) utilizarem informações visuais e para agentes de IA processarem imagens sem assistência humana.

Neste blog, usaremos o Mastra para construir um agente de conhecimento que memoriza o que os usuários dizem e consegue recuperar informações relevantes posteriormente, utilizando o Elasticsearch como backend de memória e recuperação. Você pode facilmente estender esse mesmo conceito a casos de uso do mundo real, como agentes de suporte que conseguem se lembrar de conversas e soluções anteriores, permitindo que eles personalizem as respostas para usuários específicos ou apresentem soluções mais rapidamente com base no contexto prévio.

Acompanhe aqui como construir isso passo a passo. Se você se perder ou simplesmente quiser executar um exemplo finalizado, confira o repositório aqui.

O que é Mastra?

Mastra é um framework TypeScript de código aberto para a construção de agentes de IA com componentes intercambiáveis para raciocínio, memória e ferramentas. Seu recurso de recuperação semântica permite que os agentes se lembrem e recuperem interações passadas, armazenando mensagens como representações vetoriais em um banco de dados vetorial. Isso permite que os agentes mantenham o contexto e a continuidade da conversa a longo prazo. O Elasticsearch é um excelente armazenamento de vetores para habilitar esse recurso, pois oferece suporte a buscas vetoriais densas e eficientes. Quando a recuperação semântica é acionada, o agente extrai mensagens relevantes do passado para a janela de contexto do modelo, permitindo que o modelo use esse contexto recuperado como base para seu raciocínio e respostas.

O que você precisa para começar

• Node v18+

• Elasticsearch (versão 8.15 ou mais recente)

• Chave da API do Elasticsearch

• Chave da API OpenAI

Observação: você precisará disso porque a demonstração usa o provedor OpenAI, mas o Mastra é compatível com outros SDKs de IA e provedores de modelos da comunidade, então você pode facilmente trocá-lo dependendo da sua configuração.

Construindo um projeto Mastra

Usaremos a CLI integrada do Mastra para fornecer a estrutura básica do nosso projeto. Execute o comando:

Você receberá uma série de instruções, começando com:

1. Dê um nome ao seu projeto.

2. Podemos manter esta opção padrão; fique à vontade para deixar este campo em branco.

3. Para este projeto, usaremos um modelo fornecido pela OpenAI.

4. Selecione a opção “Ignorar por enquanto”, pois armazenaremos todas as nossas variáveis de ambiente em um arquivo `.env` que configuraremos em uma etapa posterior.

5. Também podemos ignorar esta opção.

Assim que a inicialização estiver concluída, podemos passar para a próxima etapa.

Instalando dependências

Em seguida, precisamos instalar algumas dependências:

• ai - Pacote Core AI SDK que fornece ferramentas para gerenciar modelos de IA, prompts e fluxos de trabalho em JavaScript/TypeScript. O Mastra é construído sobre o SDK de IA da Vercel, portanto, precisamos dessa dependência para permitir as interações do modelo com o seu agente.

• @ai-sdk/openai - Plugin que conecta o SDK de IA aos modelos da OpenAI (como GPT-4, GPT-4o, etc.), permitindo chamadas à API usando sua chave de API da OpenAI.

• @elastic/elasticsearch - Cliente oficial do Elasticsearch para Node.js, Utilizado para conectar-se ao seu Elastic Cloud ou cluster local para indexação, pesquisa e operações vetoriais.

• dotenv - Carrega variáveis de ambiente de um arquivo .env arquivo em process.env, permitindo que você insira credenciais com segurança, como chaves de API e endpoints do Elasticsearch.

Configurando variáveis de ambiente

Crie um arquivo .env no diretório raiz do seu projeto, caso ainda não exista um. Alternativamente, você pode copiar e renomear o exemplo .env que eu forneci no repositório. Neste arquivo, podemos adicionar as seguintes variáveis:

Isso conclui a configuração básica. A partir daqui, você já pode começar a construir e orquestrar agentes. Vamos dar um passo além e adicionar o Elasticsearch como camada de armazenamento e busca vetorial.

Adicionando o Elasticsearch como armazenamento vetorial.

Crie uma nova pasta chamada stores e, dentro dela, adicione este arquivo. Antes que a Mastra e a Elastic lancem uma integração oficial de armazenamento vetorial do Elasticsearch, Abhi Aiyer(CTO da Mastra) compartilhou esta classe protótipo inicial chamada ElasticVector. Em termos simples, ele conecta a abstração de memória do Mastra aos recursos de vetores densos do Elasticsearch, permitindo que os desenvolvedores utilizem o Elasticsearch como banco de dados de vetores para seus agentes.

Vamos analisar mais detalhadamente as partes importantes da integração:

Ingestão do cliente Elasticsearch

Esta seção define a classe ElasticVector e configura a conexão do cliente Elasticsearch com suporte para implantações padrão e sem servidor.

• ElasticVectorConfig extends ClientOptionsIsso cria uma nova interface de configuração que herda todas as opções do cliente Elasticsearch (como node, auth, requestTimeout) e adiciona nossas propriedades personalizadas. Isso significa que os usuários podem passar qualquer configuração válida do Elasticsearch juntamente com nossas opções específicas para ambientes sem servidor.

• extends MastraVectorIsso permite que ElasticVector herde da classe base MastraVector do Mastra, que é uma interface comum à qual todas as integrações de armazenamento vetorial estão em conformidade. Isso garante que o Elasticsearch se comporte como qualquer outro backend vetorial do Mastra da perspectiva do agente.

• private client: ClientEsta é uma propriedade privada que contém uma instância do cliente JavaScript do Elasticsearch. Isso permite que a classe se comunique diretamente com o seu cluster.

• isServerless e deploymentChecked: Essas propriedades funcionam em conjunto para detectar e armazenar em cache se estamos conectados a uma implantação do Elasticsearch sem servidor ou padrão. Essa detecção ocorre automaticamente no primeiro uso ou pode ser configurada explicitamente.

• constructor(config: ClientOptions): Este construtor recebe um objeto de configuração (contendo suas credenciais do Elasticsearch e configurações opcionais sem servidor) e o usa para inicializar o cliente na linha this.client = new Client(config).

• super()Isso chama o construtor base do Mastra, portanto, ele herda o registro de logs, os auxiliares de validação e outros recursos internos.

Neste ponto, Mastra sabe que existe uma nova loja de vetores chamada ElasticVector

Detecção do tipo de implantação

Antes de criar os índices, o adaptador detecta automaticamente se você está usando o Elasticsearch padrão ou o Elasticsearch Serverless. Isso é importante porque as implantações sem servidor não permitem a configuração manual de shards.

O que está acontecendo:

• Primeiro verifica se você definiu explicitamente isServerless na configuração (ignora a detecção automática).

• Chama a API info() do Elasticsearch para obter informações do cluster.

• Verifica o build_flavor field (implantações sem servidor retornam serverless)

• Se a opção de build não estiver disponível, a solução é verificar a descrição da versão.

• Armazena o resultado em cache para evitar chamadas repetidas à API.

• Se a detecção falhar, a implantação padrão será utilizada por padrão.

Exemplo de uso:

Criando o armazenamento de “memória” no Elasticsearch

A função abaixo configura um índice Elasticsearch para armazenar embeddings. Verifica se o índice já existe. Caso contrário, cria um com o mapeamento abaixo que contém um campo dense_vector para armazenar embeddings e métricas de similaridade personalizadas.

Algumas coisas a ter em conta:

• O parâmetro dimension representa o comprimento de cada vetor de incorporação, que depende do modelo de incorporação que você está usando. Em nosso caso, geraremos embeddings usando o modelo text-embedding-3-small da OpenAI, que produz vetores de tamanho 1536. Usaremos esse valor como padrão.

• A variável similarity usada no mapeamento abaixo é definida pela função auxiliar const similarity = this.mapMetricToSimilarity(metric), que recebe o valor do parâmetro metric e o converte em uma palavra-chave compatível com o Elasticsearch para a métrica de distância escolhida.

  • Por exemplo: Mastra usa termos gerais para similaridade de vetores como cosine, euclidean e dotproduct. Se passássemos a métrica euclidean diretamente para o mapeamento do Elasticsearch, ele geraria um erro porque o Elasticsearch espera que a palavra-chave l2_norm represente a distância euclidiana.

• Compatibilidade com ambientes sem servidor: o código omite automaticamente as configurações de shard e réplica para implantações sem servidor, pois estas são gerenciadas automaticamente pelo Elasticsearch Serverless.

Armazenar uma nova memória ou anotação após uma interação.

Esta função recebe novos embeddings gerados após cada interação, juntamente com os metadados, e os insere ou atualiza no índice usando a API bulk do Elastic. A API bulk agrupa várias operações de gravação em uma única solicitação; essa melhoria no desempenho de indexação garante que as atualizações permaneçam eficientes à medida que a memória do nosso agente continua a crescer.

Consultar vetores semelhantes para recuperação semântica

Essa função é o núcleo do recurso de recuperação semântica. O agente utiliza a busca vetorial para encontrar incorporações armazenadas semelhantes em nosso índice.

Por dentro do capô:

• Executa uma consulta kNN (k-vizinhos mais próximos) usando a API knn no Elasticsearch.

• Recupera os K vetores mais semelhantes ao vetor de consulta de entrada.

• Opcionalmente, aplica filtros de metadados para refinar os resultados (por exemplo, pesquisar apenas dentro de uma categoria ou intervalo de tempo específico).

• Retorna resultados estruturados, incluindo o ID do documento, a pontuação de similaridade e os metadados armazenados.

Criando o agente de conhecimento

Agora que vimos a conexão entre Mastra e Elasticsearch por meio da integração ElasticVector , vamos criar o próprio Agente de Conhecimento.

Dentro da pasta agents, crie um arquivo chamado knowledge-agent.ts. Podemos começar conectando nossas variáveis de ambiente e inicializando o cliente Elasticsearch.

Aqui, nós:

• Use dotenv para carregar nossas variáveis do nosso arquivo .env .

• Verifique se as credenciais do Elasticsearch estão sendo inseridas corretamente e, em seguida, poderemos estabelecer uma conexão bem-sucedida com o cliente.

• Passe o endpoint do Elasticsearch e a chave da API para o construtor ElasticVector para criar uma instância do nosso armazenamento de vetores que definimos anteriormente.

• Opcionalmente, especifique isServerless: true se estiver usando o Elasticsearch Serverless. Isso elimina a etapa de detecção automática e melhora o tempo de inicialização. Caso seja omitido, o adaptador detectará automaticamente o seu tipo de implantação na primeira utilização.

Em seguida, podemos definir o agente usando a classe Agent do Mastra.

Os campos que podemos definir são:

• name e instructions: Dê a ele uma identidade e uma função primária.

• modelEstamos usando o gpt-4o da OpenAI por meio do pacote @ai-sdk/openai .

• memory:

  • vector: Aponta para o nosso armazenamento Elasticsearch, de onde os embeddings são armazenados e recuperados.

  • embedderQual modelo usar para gerar embeddings?

  • semanticRecall As opções definem como funciona o recall:

    • topKQuantas mensagens semanticamente semelhantes devem ser recuperadas?

    • messageRange: Qual a extensão da conversa a ser incluída em cada interação?

    • scopeDefine o limite da memória.

Quase pronto. Basta adicionarmos esse agente recém-criado à nossa configuração do Mastra. No arquivo chamado index.ts, importe o agente de conhecimento e insira-o no campo agents .

Os outros campos incluem:

• storageEste é o repositório de dados interno do Mastra para histórico de execuções, métricas de observabilidade, pontuações e caches. Para obter mais informações sobre o sistema de armazenamento Mastra, visite aqui.

• loggerO Mastra utiliza o Pino, que é um registrador JSON estruturado e leve. Ele registra eventos como início e término de agentes, chamadas e resultados de ferramentas, erros e tempos de resposta do LLM.

• observabilityControla o rastreamento de IA e a visibilidade da execução de agentes. Ele rastreia:

  • Início/fim de cada etapa de raciocínio.

  • Qual modelo ou ferramenta foi utilizada?

  • Entradas e saídas.

  • Pontuações e avaliações

Testando o agente com o Mastra Studio

Parabéns! Se você chegou até aqui, está pronto para executar este agente e testar suas capacidades de recuperação semântica. Felizmente, o Mastra oferece uma interface de chat integrada, então não precisamos criar a nossa própria.

Para iniciar o servidor de desenvolvimento do Mastra, abra um terminal e execute o seguinte comando:

Após a inicialização e o empacotamento iniciais do servidor, você deverá receber um endereço para o Playground.

Cole este endereço no seu navegador e você será direcionado para o Mastra Studio.

Selecione a opção knowledgeAgent e comece a conversar.

Para um teste rápido para verificar se tudo está conectado corretamente, forneça algumas informações como: "A equipe anunciou que o desempenho de vendas em outubro aumentou 12%, impulsionado principalmente por renovações de contratos corporativos." O próximo passo é expandir o alcance aos clientes de médio porte.” Em seguida, inicie um novo bate-papo e faça uma pergunta como: "Em qual segmento de clientes dissemos que precisamos nos concentrar a seguir?" O agente de conhecimento deve ser capaz de recordar as informações que você lhe forneceu na primeira conversa. Você deverá ver uma resposta semelhante a esta:

Ao recebermos uma resposta como essa, significa que o agente armazenou com sucesso nossa mensagem anterior como embeddings no Elasticsearch e a recuperou posteriormente usando a busca vetorial.

Inspecionando o armazenamento de memória de longo prazo do agente.

Acesse a aba memory na configuração do seu agente no Mastra Studio. Isso permite que você veja o que seu agente aprendeu ao longo do tempo. Cada mensagem, resposta e interação que é incorporada e armazenada no Elasticsearch passa a fazer parte dessa memória de longo prazo. Você pode realizar buscas semânticas em interações passadas para encontrar rapidamente informações ou contextos que o agente aprendeu anteriormente. Este é essencialmente o mesmo mecanismo que o agente usa durante a recuperação semântica, mas aqui você pode inspecioná-lo diretamente. No exemplo abaixo, estamos pesquisando o termo "vendas" e obtendo como resultado todas as interações que incluíram algo relacionado a vendas.

Conclusão

Ao conectar o Mastra e o Elasticsearch, podemos fornecer memória aos nossos agentes, o que é uma camada fundamental na engenharia de contexto. Com a recuperação semântica, os agentes podem construir contexto ao longo do tempo, fundamentando suas respostas no que aprenderam. Isso significa interações mais precisas, confiáveis e naturais.

Essa integração inicial é apenas o ponto de partida. O mesmo padrão pode permitir que agentes de suporte se lembrem de chamados anteriores, bots internos recuperem documentação relevante ou assistentes de IA consigam recordar detalhes do cliente no meio da conversa. Também estamos trabalhando para uma integração oficial com o Mastra, tornando essa combinação ainda mais perfeita em um futuro próximo.

Estamos ansiosos para ver o que você vai construir em seguida. Experimente, explore o Mastra e seus recursos de memória e sinta-se à vontade para compartilhar suas descobertas com a comunidade.