DEV Community: Alberto Luiz Souza

Detecção de anomalias: do sensor ao dashboard

Alberto Luiz Souza — Mon, 30 Mar 2026 01:11:49 +0000

Disclaimer

Este texto foi inicialmente concebido pela IA Generativa em função da transcrição de um vídeo do canal de Daniel Romero (a pessoa que lidera nossa especialização em Engenharia de IA). Se preferir acompanhar por vídeo, é só dar o play.

Introdução

Detecção de anomalias é uma técnica de Machine Learning usada para encontrar padrões em dados que não estão de acordo com o comportamento esperado. Empresas de cartão de crédito e fintechs usam esse tipo de abordagem no combate a fraudes, mas a aplicação vai muito além do mundo financeiro. Neste post, vamos construir um sistema completo de detecção de anomalias para monitorar vibração em maquinário industrial, passando por coleta de dados com sensor, treinamento de modelo e inferência em tempo real.

A inspiração vem de empresas reais que fornecem sistemas de monitoramento preditivo para indústria, usando sensores que coletam dados de vibração e modelos de Machine Learning que analisam esses dados para prever problemas antes que eles aconteçam.

O plano geral do projeto

O projeto percorre toda a cadeia de um sistema de detecção de anomalias:

Montar um protótipo com sensor acelerômetro conectado a um microcontrolador ESP32
Coletar dados de vibração de um ar-condicionado em operação normal e com anomalia simulada
Analisar os dados coletados e extrair features relevantes
Treinar um modelo de Machine Learning para classificar operação normal versus anomalia
Criar uma API para inferência em tempo real
Construir um dashboard para monitorar o estado do sistema

Coleta de dados com acelerômetro e ESP32

Para coletar dados de vibração, o projeto usa um acelerômetro de 3 eixos (MPU6050) conectado a um ESP32 via protocolo I2C.

Como funciona um acelerômetro

Um acelerômetro detecta aceleração linear ao longo de um eixo. O sensor utilizado é uma IMU (unidade de medição inercial), que combina acelerômetros, giroscópios e magnetômetros em um chip microscópico, usando tecnologia MEMS (sistemas microeletromecânicos).

Internamente, o sensor possui uma massa sísmica em forma de H com extremidades sensoriais. Essa massa fica presa ao substrato nas extremidades, permitindo um movimento de vai e vem. Durante a movimentação, os dedos sensoriais se aproximam dos eletrodos, gerando detecção capacitiva. A mudança na capacitância entre os eletrodos fixos e a massa sísmica é usada para determinar a aceleração. Em termos práticos, o sensor detecta tanto forças estáticas como a gravidade quanto forças dinâmicas como vibrações.

Configuração do microcontrolador

O ESP32 conecta-se ao Wi-Fi e envia os dados do acelerômetro para uma API Python via requisições HTTP POST. O fluxo funciona assim:

O ESP32 faz uma requisição GET para verificar se o servidor está pronto
Se recebe resposta positiva, coleta 200 amostras por segundo (uma amostra a cada 5 milissegundos)
Os valores X, Y e Z da aceleração são organizados em JSON e enviados via POST
O servidor Python recebe os dados e salva em arquivos CSV

Na configuração do sensor, o range do acelerômetro fica em mais ou menos 4G (podendo medir até 16G) e a largura de banda do filtro em 260 Hz. O range define o tamanho da força que o sensor pode medir, enquanto a largura de banda determina o quão rápido ele consegue registrar mudanças de movimento. A combinação dos dois funciona quase como um ajuste de sensibilidade.

Introduzindo a anomalia

Para simular uma falha mecânica, um imã é fixado no cilindro metálico que faz o ar circular no ar-condicionado. Isso causa uma descalibragem proposital, fazendo o cilindro trepidar. Os dados são coletados em diferentes condições: operação normal em várias velocidades e operação com a anomalia inserida.

Análise exploratória dos dados

Com os dados coletados, a análise revela diferenças claras entre operação normal e anomalia.

Dados brutos

Na operação normal, o eixo Z mantém um nível constante em torno de 10g, enquanto os eixos X e Y ficam próximos de zero com linhas suaves. Na operação com anomalia, aparecem oscilações mais intensas em todos os eixos, com um padrão mais irregular.

Features estatísticas

Três características se destacam na separação entre normal e anomalia:

Média: mostra o valor central das medições ao longo do tempo. Há uma separação clara, indicando que o nível médio de vibração durante anomalias é consistentemente diferente
Variância: mede como os dados se dispersam em relação à média. As anomalias apresentam valores muito maiores, indicando vibrações mais intensas e irregulares
Curtose: indica o quanto os dados se concentram em torno da média. Valores mais altos sugerem picos de vibração mais intensos e frequentes

Cada feature fornece uma perspectiva diferente. A média entrega uma visão geral de vibração, a variância revela a intensidade das oscilações e a curtose indica a presença de eventos extremos.

Transformada rápida de Fourier (FFT)

A FFT decompõe um sinal em suas frequências constituintes. Diferentes problemas mecânicos geram padrões de vibração em frequências específicas. Um rolamento com defeito pode gerar vibrações em uma frequência, enquanto um desbalanceamento pode gerar outra.

Nos dados coletados, a operação normal mostra um perfil de frequência suave e com baixa magnitude. A anomalia mostra picos em certas frequências, especialmente no eixo Z, onde a magnitude chega a 16 vezes o valor normal.

Treinamento do modelo

Preparação dos dados

O processo de preparação inclui:

Carregar os CSVs de cada tipo de operação (normal e anomalia)
Remover o DC (valor médio do sinal) para centralizar os dados em torno de zero, eliminando viés constante e efeitos da gravidade
Adicionar ruído aleatório para aumentar a robustez durante o treino

Extração de features

Para cada eixo, cinco features são extraídas:

Desvio padrão: variabilidade do sinal
Curtose: formato da distribuição
Amplitude máxima absoluta: maior valor registrado
RMS (média quadrática): medida de energia do sinal
Range: diferença entre valores máximos e mínimos

Distância de Mahalanobis e threshold

O algoritmo escolhido usa a distância de Mahalanobis para calcular o quão distante um ponto está da distribuição normal dos dados. Essa distância produz uma medida de quão estranho é um ponto em relação ao comportamento esperado.

Uma função complementar encontra o melhor limiar (threshold) para separar normal de anomalia usando validação cruzada. A abordagem é conservadora: falsos positivos são penalizados 5 vezes mais que falsos negativos, priorizando evitar alarmes falsos.

Resultados do modelo

A distribuição das distâncias de Mahalanobis mostra:

Casos normais concentrados entre 2 e 6, com pico próximo a 3,5
Anomalias concentradas entre 8,5 e 14, com pico em torno de 10
Threshold definido em 5,71

Na matriz de confusão, o modelo acertou 86 de 100 predições: 47 verdadeiros normais, 39 verdadeiras anomalias, 3 falsos positivos e 11 falsos negativos. O modelo tende a ser mais conservador, preferindo classificar como normal os casos duvidosos.

No relatório de classificação:

Normal: precisão de 81%, recall de 94%, F1 de 87%
Anomalia: precisão de 93%, recall de 78%, F1 de 85%
Acurácia geral: 86%
AUC Score: 0,87

Inferência em tempo real

Atualização do sensor

Para a fase de inferência, o software do ESP32 é atualizado. A coleta passa para 100 amostras, organizadas como uma matriz 2D que corresponde ao formato de input esperado pelo modelo. Os dados são enviados para uma API de detecção de anomalias.

API com FastAPI

A API recebe os dados do acelerômetro, carrega o modelo treinado (contendo média, covariância e threshold) e executa o pipeline:

Pré-processamento dos novos dados e remoção do DC
Cálculo das features estatísticas por eixo
Cálculo da distância de Mahalanobis para a nova amostra
Cálculo de confiança considerando histórico recente
Classificação como normal ou anomalia

Vale destacar que a distância de Mahalanobis aparece tanto no treino quanto na inferência, mas com propósitos diferentes. No treino, ela é usada para definir o threshold com dados rotulados. Na inferência, é calculada para cada nova amostra e comparada com o threshold já definido. No treino se calibra o sistema; na inferência se usa essa calibração para classificar.

Dashboard de monitoramento

Uma aplicação em React exibe o status da classificação em tempo real, com três métricas:

Confidence: confiança do modelo na classificação atual
Distância de Mahalanobis: calculada para os dados recebidos
Threshold: limite constante que define quando algo é considerado anomalia

O gráfico mostra a evolução temporal dessas métricas, permitindo acompanhar o comportamento do sistema.

Possibilidades de evolução

O projeto demonstra um fluxo completo, mas várias evoluções são possíveis:

Treinar uma rede neural com mais dados para maior sofisticação
Mapear peças internas do equipamento para identificar a origem da anomalia
Combinar dados do acelerômetro com giroscópio para aumentar a precisão
Projetar hardware dedicado com PCB customizada
Separar os componentes da API de forma mais organizada

Conclusão

Um projeto assim não garante uma vaga de trabalho, mas funciona como treino e pode chamar a atenção em meio a milhares de candidaturas. O diferencial está em cobrir toda a cadeia do problema: desde o entendimento do hardware e coleta de dados, passando pela análise exploratória e treinamento do modelo, até a inferência em tempo real com dashboard de monitoramento.

Dev + Eficiente

Desenvolva software de alta qualidade e domine Engenharia de IA com o Dev + Eficiente. Cursos práticos, acesso vitalício, comunidade ativa e acesso a vagas remotas exclusivas em diversas empresas de tecnologia. Sua jornada para se tornar um dev mais eficiente pode começar agora.

Skills para agentes de código fazem diferença?

Alberto Luiz Souza — Sun, 22 Mar 2026 23:41:08 +0000

Disclaimer

Este texto foi inicialmente concebido pela IA Generativa em função da transcrição de um vídeo do canal Dev Mais Eficiente. Se preferir acompanhar por vídeo, é só dar o play.

Introdução

Existe uma discussão recorrente sobre o quanto configurar skills (no Claude Code), rules (no Cursor) ou arquivos semelhantes realmente melhora o resultado dos agentes de código. Para tentar responder isso com dados, um estudo chamado SkillBench montou um benchmark com 84 tarefas de domínios variados e testou múltiplos modelos em três cenários: sem skill nenhuma, com skills geradas pelo próprio agente e com skills escritas com participação humana.

Neste post, vamos analisar os principais achados do estudo, incluindo dados do apêndice sobre taxa de falha dos modelos que costumam passar despercebidos nas discussões.

O achado principal: skills escritas por humanos fazem diferença

O gráfico central do estudo compara a taxa de resolução de tarefas em três condições: sem skill, com skill auto-gerada pelo agente e com skill escrita em conjunto com um ser humano que domina o assunto.

O resultado mais relevante: skills escritas com participação humana consistentemente melhoram a taxa de resolução em relação às outras duas condições. Os modelos testados incluem Haiku 4.5, Sonnet 4.5, Opus 4.5, Gemini 3 Pro, GPT 5.2, Opus 4.6 e Gemini 3 Flash, e o padrão se repete em praticamente todos.

Já as skills geradas pelo próprio agente tiveram efeito quase nulo comparadas a trabalhar sem skill nenhuma. Em alguns casos, como GPT 5.2 e Sonnet 4.5, o agente sem skill teve resultado levemente melhor do que com skill auto-gerada.

Isso reforça algo que segue sendo verdade: o nível de expertise de quem direciona o agente continua fazendo diferença significativa.

Como o estudo foi montado

O repositório do SkillBench contém 84 tarefas de naturezas diversas. Cada tarefa tem a instrução para o agente, metadados, timeout, testes automatizados para verificar o output e uma proposta de solução determinística.

A execução funcionava assim: subia uma imagem Docker com o agente instalado (Claude Code, Codex, Gemini CLI), configurava com ou sem skill, apontava para a pasta com as instruções e deixava o agente trabalhar. Depois verificava o resultado contra os testes.

A variação por domínio e o que ela revela

O estudo traz uma tabela com a taxa de resolução por domínio. Alguns números:

Saúde: 86% com skill, 34% sem skill
Engenharia de software: 38,9% com skill, 34,4% sem skill

A diferença entre esses dois domínios é reveladora, mas precisa de contexto. Primeiro, o volume de tarefas era diferente: saúde tinha poucas tarefas, engenharia de software tinha mais de vinte. Segundo, e talvez mais importante, os modelos são muito mais bem treinados para engenharia de software do que para domínios como saúde.

Isso leva a uma conclusão prática: quanto menos treinado o modelo é para um domínio específico, maior o gap que o conhecimento humano precisa preencher. Em domínios onde o modelo já tem bastante conhecimento nos dados de treino, a diferença que uma skill faz tende a ser menor.

O esforço de setup pode não compensar

Existe uma tendência a montar setups elaborados para trabalhar com agentes de código: engenharia de contexto detalhada, troca de modelos por tipo de tarefa, controle granular de consumo de tokens. O estudo sugere que, pelo menos para tarefas mais padronizadas, esse esforço pode gerar diferença marginal.

Se a tarefa é de conhecimento relativamente público e o modelo já é bem treinado naquele domínio, a diferença entre um setup sofisticado e um prompt direto pode ser pequena. Isso não significa que skills são inúteis, mas que vale avaliar se o esforço de configuração está gerando retorno proporcional.

Para práticas de engenharia de software que são bastante padronizadas (separação de controllers e casos de uso, cálculos comuns, estilo funcional com imutabilidade), o modelo provavelmente já consegue operar bem sem instruções adicionais. A skill faz mais diferença quando o domínio é específico e não tão bem representado nos dados de treino.

A taxa de falha que ninguém comenta

O apêndice do estudo traz uma tabela com as tentativas e taxas de falha de cada modelo. Alguns números:

Opus 4.6: 1.245 tentativas, 67,1% de falha
Gemini 3 Pro: 61% de falha
Haiku e Sonnet: acima de 80% de falha

Esses números consideram todas as condições (com skill auto-gerada, com skill humana, sem skill). A maioria das tentativas falhou, mesmo em tarefas que envolvem conhecimento de domínio público.

Isso tem uma implicação direta para o fluxo de trabalho do dia a dia. Se a taxa de falha é essa em tarefas padronizadas, imagine dentro do contexto de negócio específico da sua empresa, com domínio que não é público e conexões que o modelo não tem como inferir. A taxa de falha provavelmente seria ainda maior.

Na prática, isso significa que o ciclo de gerar, revisar, direcionar e gerar novamente continua sendo o fluxo normal. Quanto mais aberta e ambígua a tarefa, maior a chance do modelo produzir algo diferente do esperado. A participação humana no direcionamento segue sendo importante para reduzir esse ciclo.

Analogia com VMs e otimização prematura

Uma maneira útil de pensar sobre isso é a analogia com máquinas virtuais. A JVM, por exemplo, faz otimizações sofisticadas em runtime. Na maioria dos casos, tentar micro-otimizar manualmente sem dados concretos pode até atrapalhar o trabalho da VM.

Com agentes de código pode estar acontecendo algo parecido. Em algum momento, tentar ajustar finamente o comportamento do agente com muitas regras e configurações pode ser contra-produtivo. Para a maioria das tarefas, apostar no comportamento padrão do modelo e iterar a partir do resultado pode ser mais eficiente do que montar um setup elaborado antes de começar.

Quando você tem dados concretos de que um ajuste específico faz diferença no seu contexto, aí sim vale configurar. Mas sem essa evidência, o default tende a funcionar razoavelmente bem.

Conclusão

O SkillBench traz dados úteis para calibrar expectativas. Skills escritas com participação de quem domina o assunto fazem diferença mensurável. Skills auto-geradas pelo agente praticamente não ajudam. A taxa de falha dos modelos ainda é alta mesmo em tarefas padronizadas, o que reforça que o direcionamento humano continua sendo parte essencial do fluxo.

Para quem trabalha com agentes de código no dia a dia, o ponto prático é: invista seu tempo no que você sabe sobre o problema, não na engenharia de contexto genérica. O conhecimento de domínio que você traz para a skill é o que faz a diferença, não a sofisticação do setup.

Dev + Eficiente

Estudo da Anthropic sobre IA e aprendizagem: o modo de uso importa mais do que a ferramenta

Alberto Luiz Souza — Mon, 16 Mar 2026 12:14:54 +0000

Este texto foi inicialmente concebido pelo Agente Marketing Dev + Eficiente em função da transcrição de um vídeo do canal Dev Eficiente. Se preferir acompanhar por vídeo, é só dar o play.

Introdução

A Anthropic publicou um estudo chamado "How AI Impacts Skill Formation". O experimento colocou pessoas para implementar funcionalidades usando uma biblioteca Python, dividindo-as em dois grupos: um com acesso a assistentes baseados em LLM e outro sem. Depois, aplicaram um quiz sobre os conhecimentos adquiridos durante a tarefa. O grupo que não usou IA tirou notas melhores.

O resultado gerou bastante repercussão -- posts no LinkedIn dizendo que IA "emburrece" e alertas sobre o futuro da profissão. Mas quando olhamos os dados com mais cuidado, a história é mais nuançada do que o título sugere.

O que o estudo de fato mostra

O experimento usou uma biblioteca Python chamada Trio, que permite operações assíncronas com composição de tarefas. Os participantes tinham 35 minutos para completar a implementação.

Dois resultados chamam atenção:

Sobre produtividade: a diferença de tempo entre quem usou IA e quem não usou não foi tão expressiva quanto se poderia imaginar. A pessoa mais rápida com IA completou em aproximadamente 18 minutos, enquanto a mais rápida sem IA demorou cerca de 21. Para essa tarefa específica, o ganho de produtividade não foi marcante.

Sobre aprendizado: aqui a diferença foi significativa. A pior nota de quem não usou IA foi melhor do que a melhor nota de quem usou. Quem não teve a opção de delegar precisou ler a documentação, entender os conceitos e resolver os problemas por conta própria -- e esse esforço se refletiu no quiz.

Os padrões de uso que explicam a diferença

O estudo identificou diferentes padrões de interação com a IA, e nem todos levaram ao mesmo resultado:

Delegação total: a pessoa simplesmente pediu para a IA resolver e colou o resultado. Completou rápido (cerca de 19 minutos), mas ficou com média de 39% no quiz. É o padrão mais intuitivo quando o objetivo é apenas terminar.

Delegação do debugging: quando apareceu um bug, a pessoa delegou a resolução completa para a IA. Esse foi o pior cenário -- demorou mais para terminar e ainda resultou em notas baixas. A oportunidade de entender o que deu errado, e se prevenir na próxima vez, se perdeu.

Geração seguida de compreensão: a pessoa usou a IA para gerar o código, mas depois leu e tentou entender o que foi produzido. Esse grupo demorou um pouco mais, mas tirou notas na casa dos 60% -- não tão boas quanto quem não usou IA, mas com um trade-off possivelmente aceitável entre velocidade e aprendizado.

O que isso significa na prática

O estudo é honesto sobre suas limitações. As tarefas do experimento são isoladas e curtas, bem diferentes de tarefas reais de desenvolvimento, onde existe contexto acumulado, interação com outras equipes, análise de código existente e decisões arquiteturais.

Um exemplo prático: ao precisar salvar currículos em um bucket da Cloudflare usando o R2, é perfeitamente razoável pedir para um agente gerar o código de integração. Se alguém perguntar depois como a API do R2 funciona em detalhe, a resposta honesta pode ser "não sei de cabeça". Isso não diz nada sobre a capacidade da pessoa como engenheira -- é um componente pontual, mapeado, que pode ser consultado quando necessário.

Agora, o estudo evidencia algo que vale a atenção: quando a prioridade é só terminar, o impulso natural é parar de refletir. E falta de reflexão afeta o entendimento, a capacidade de pensar em alternativas e de se preparar para problemas futuros.

Sensação de produtividade versus produtividade real

Escrever mais código não significa produzir mais valor. Se alguém fala mil palavras por minuto e outra pessoa fala trezentas, isso não diz nada sobre a qualidade do que foi dito.

Com ferramentas de IA, é fácil colocar mais tarefas no pipeline simplesmente porque agora é possível gerar mais código. Mas o número de tarefas entregues que de fato geram valor pode não ter mudado.

Existem cenários onde o ganho de produtividade é óbvio e não faz sentido questionar: quando a pessoa não sabia fazer aquilo antes. Se alguém que nunca escreveu Swift consegue entregar uma funcionalidade com ajuda de IA, é claro que ficou "mais produtiva" -- antes não fazia nada.

O cenário que ainda carece de evidências mais robustas é quando a pessoa já sabe fazer o trabalho, delega para a IA e depois confere o resultado. Estudos mais longitudinais seriam necessários para entender o impacto real nessa situação.

O papel de quem usa o agente

Enquanto não existirem agentes operando sem humanos no loop, a responsabilidade pelo resultado é de quem abre o PR. Se o agente entregou algo, você aprovou, e depois não consegue explicar o que aquele código faz, o problema é seu.

Usar ferramentas de IA para estudar e trabalhar faz sentido -- é uma tecnologia que fornece feedback como se houvesse alguém acompanhando o que você está fazendo. Mas o modo de uso importa. Gerar e entender é diferente de gerar e ignorar.

Conclusão

O estudo da Anthropic não traz uma revelação surpreendente: menos reflexão leva a menos entendimento. Mas quantifica isso de forma controlada e identifica padrões de uso que podem orientar como cada pessoa decide interagir com ferramentas de IA no dia a dia.

A decisão prática é sobre quando vale abrir mão de entendimento profundo (componentes pontuais, integrações que não são o core do sistema) e quando vale investir o tempo de compreender o que foi gerado (lógica de negócio, componentes críticos, áreas onde um bug futuro pode puxar seu pé).

Dev + Eficiente

Como o RAG está sendo usado na indústria de software: o que dizem 26 estudos

Alberto Luiz Souza — Mon, 09 Mar 2026 11:49:23 +0000

Disclaimer

Este texto foi gerado pelo Agente Marketing Dev + Eficiente a partir de um relatório técnico de revisão sistemática sobre RAG na Engenharia de Software, conduzido com análise assistida por IA. O conteúdo abaixo sintetiza as principais evidências encontradas na literatura e em relatos industriais.

Introdução

RAG (Retrieval-Augmented Generation) combina mecanismos de recuperação de informação com modelos generativos. Na prática, o sistema consulta bases de conhecimento externas -- documentação técnica, logs operacionais, código-fonte, histórico de incidentes -- antes de produzir uma resposta. O modelo passa a fundamentar suas saídas em evidências recuperadas, reduzindo alucinações e aumentando a precisão.

Uma revisão sistemática recente analisou 26 estudos (entre 2021 e 2025) para entender como o RAG está sendo aplicado na indústria de software. Os resultados mostram que a tecnologia já ultrapassou o estágio experimental e está presente em ambientes de produção em diversos setores.

Onde o RAG está sendo usado

A distribuição por indústria revela três padrões:

Estudos transversais dominam. A maior parte dos trabalhos (7 estudos) discute arquiteturas, técnicas e desafios de forma independente do domínio. Isso indica que a comunidade está consolidando padrões de engenharia de RAG que podem ser aplicados em diferentes contextos.

Cloud/DevOps e empresas de tecnologia concentram as aplicações mais maduras. Computação em nuvem e tecnologia da internet aparecem com 2 estudos cada, com foco em observabilidade, detecção de anomalias em logs e revisão automática de código. São cenários onde documentação operacional, logs e conhecimento histórico estão naturalmente dispersos -- exatamente o tipo de problema que o RAG resolve.

Segurança e testes estão crescendo. A necessidade de rastreabilidade, redução de alucinação e reutilização de conhecimento histórico torna o RAG atrativo para detecção de vulnerabilidades e automação de artefatos de teste.

Além desses, o RAG aparece em setores como automotiva, telecomunicações, construção naval, energia e PMEs, demonstrando versatilidade.

Em quais etapas do desenvolvimento

A etapa de desenvolvimento e testes concentra a maior parte das evidências (14 dos 26 estudos). Dentro dela, o RAG é usado para:

Complemento de código em repositórios fechados, como no caso do WeChat, onde o modelo recebe contexto do repositório interno antes de sugerir complementos.
Revisão automática de código, fornecendo contexto de chamadas entre arquivos para gerar comentários mais relevantes e reduzir sugestões inválidas
Geração de testes, incluindo scripts de teste de integração na indústria automotiva e automação de casos de teste em sistemas ERP com orquestração multiagente
Operacionalização do RAG em produção, incluindo governança, trade-offs de latência versus qualidade e avaliação contínua

Fora de desenvolvimento e testes, o RAG aparece em resolução de incidentes (redução de MTTR com troubleshooting baseado em evidências), CI/CD (diagnóstico de falhas em pipelines) e cibersegurança (detecção de vulnerabilidades ancorada em bases como CWE/MITRE).

Quais LLMs estão sendo usadas

A escolha do modelo depende do contexto:

Família GPT aparece com maior frequência, por maturidade de ecossistema e capacidade de seguir instruções ancoradas em evidências. É a escolha predominante em sistemas de gestão do conhecimento e diagnóstico de incidentes em tempo real.

Família LLaMA se destaca quando a prioridade é implantação on-premises, custo e governança. O caso da Ericsson é ilustrativo: um chatbot RAG para CI/CD usando Llama2-chat, onde até o custo de trocar de LLM por diferenças de estilo de prompt foi avaliado.

Família Qwen aparece associada a operações de nuvem, equilibrando capacidade e custo. Também é usada em indústria tradicional (construção naval), indicando que modelos open-weight entram como escolha por viabilidade.

Modelos especializados em código (CodeLlama, DeepSeek-Coder, Yi-Coder, Codestral) competem com modelos gerais quando o domínio é programação. Vários estudos comparam múltiplos modelos para equilibrar custo e desempenho.

Embeddings: o que a indústria está escolhendo

A família BGE (BAAI) foi a mais recorrente. Aparece em cenários que exigem alta precisão de recuperação, frequentemente combinada com rerankers para refinar os resultados antes de enviar ao LLM.

Sentence-Transformers (all-MiniLM-L6-v2, all-distilroberta-v1) aparecem como opção pragmática para implantação rápida e pipelines leves.

Embeddings da OpenAI (text-embedding-3-large) são usados quando o pipeline já está acoplado ao ecossistema OpenAI.

Para código, embeddings especializados como CodeBERT e UniXcoder tendem a superar embeddings genéricos em tarefas de similaridade de código.

Arquiteturas que estão emergindo

Além do pipeline RAG clássico (ingestão, chunking, vetorização, recuperação, geração), a revisão identificou padrões arquiteturais mais sofisticados:

RAG híbrido (lexical + semântico). A combinação de BM25 com recuperação semântica aparece consistentemente como a configuração mais efetiva. Reciprocal Rank Fusion (RRF) é uma técnica recorrente para fundir os sinais.

Recuperação em dois estágios (Retrieve + Rerank). Primeiro recupera um conjunto maior com alta revocação, depois aplica um reranker (tipicamente cross-encoder) para alta precisão. Esse padrão aparece em múltiplos estudos industriais.

RAG guiado por intenção. Classificação da consulta do usuário, extração de metadados e reescrita de query antes da recuperação. Resolve o problema de consultas incompletas ou ambíguas em ambientes operacionais.

RAG com grafos e Agentic RAG. Para tarefas com dependências estruturais (chamadas entre arquivos, rastreabilidade), a combinação de banco vetorial com banco em grafo e orquestração multiagente. Alguns estudos já incorporam aprendizado por reforço para melhoria contínua baseada em feedback.

RAG com base de conhecimento dinâmica. A base de conhecimento evolui via active learning: logs com baixa incerteza são incorporados automaticamente, casos incertos vão para rotulagem humana. Adequado para cenários onde os dados mudam rapidamente.

Conclusão

As evidências indicam que o RAG já é uma tecnologia em uso industrial, não apenas experimental. Seu principal valor está em permitir que LLMs utilizem conhecimento corporativo -- documentação, código, histórico de incidentes -- fundamentando respostas em evidências concretas.

A eficácia depende menos do modelo de linguagem escolhido e mais da qualidade do pipeline de recuperação: estratégia de chunking, escolha de embeddings, mecanismos de reranking e integração com os fluxos de trabalho existentes. Quem está implementando RAG em produção precisa tratar o pipeline de recuperação com o mesmo rigor que trata qualquer outro componente crítico do sistema.

Artigo completo

O artigo completo pode ser lido aqui

Especialização em Engenharia de IA

Na Especialização em Engenharia de IA, uma parceria com a Dev + Eficiente, abordamos RAG na prática: desde a construção do pipeline de recuperação até estratégias de avaliação e operacionalização em produção. O curso inclui Vector Search, Busca Híbrida, Agentes, Tools e muito mais, sempre com aulas 100% práticas.

Faça sua inscrição em https://deveficiente.com/especializacao-engenharia-ia .

CDD: como tornar a avaliação de complexidade de código mensurável

Alberto Luiz Souza — Tue, 03 Mar 2026 12:43:47 +0000

Disclaimer

Este texto foi inicialmente concebido por um Agente Dev + Eficiente especializado nos conteúdos da Jornada e foi revisado por Alberto

Introdução

Uma classe que começa com 40 linhas e termina o ano com 400. Acontece em praticamente todo projeto. O problema não é a classe ter crescido. É que ninguém percebeu quando ela começou a ficar difícil de entender.

Não existe um ponto de ruptura claro -- ela vai acumulando responsabilidades, condicionais e dependências até que qualquer alteração começa a pesar muito mais do que deveria. E aí você tem um time inteiro olhando para o mesmo arquivo e cada pessoa avaliando a dificuldade de um jeito diferente.

A maioria das práticas que tentam resolver isso são baseadas em princípios qualitativos. "Responsabilidade única", "código limpo", "baixo acoplamento". Importantes, mas difíceis de aplicar de forma consistente entre pessoas diferentes de um mesmo time. O que é "responsabilidade única" para uma pessoa pode não ser para outra.

O Cognitive Driven Development (CDD) parte de uma premissa diferente: é possível tornar a avaliação de complexidade de código algo mensurável e compartilhado.

Para não causar confusão: não estamos falando de sustituição de práticas e sim de trazer uma prática que pode facilitar o uso das outras.

O fundamento: carga cognitiva aplicada a código

A teoria da carga cognitiva vem da psicologia educacional. A ideia central é que seres humanos possuem um limite restrito de capacidade de absorção de informação em um determinado intervalo de tempo. Uma referência clássica é o trabalho de Miller (1956), que estabelece que uma pessoa consegue manter aproximadamente 7 itens simultâneos na mente.

O insight do CDD é tratar código como material de consumo cognitivo -- assim como um slide, uma apostila ou um vídeo. Se existe um limite para o que uma pessoa consegue processar, então faz sentido que unidades de código também respeitem esse limite.

A partir daí, o CDD sugere que a complexidade de uma unidade de código (um arquivo, por exemplo) tenha um limite definido. Passou deste limite? A complexidade está maior do que queremos, precisamos ajustar.

Como funciona na prática

O processo é direto. A equipe decide quais elementos de código ela julga que mais pesam na mente das pessoas. Não existe resposta certa -- isso varia de time para time e de projeto para projeto.

Por exemplo, em um projeto com Java, a equipe pode definir (apenas um exemplo) os seguintes elementos:

Condicionais
Acoplamentos com classes do projeto
Funções como argumento

Cada elemento desse, dentro do CDD, é chamado de Intrinsic Complex Point (ICP). Num projeto usando Clojure, os elementos vão mudar. Num projeto usando Python, podem mudar de novo. A teoria é agnóstica de linguagem -- o que muda é quais construções da linguagem a equipe considera relevantes para o entendimento.

Pode-se definir que cada elemento contabiliza um ponto e, a partir disso, já fica bem mais fácil avaliar a complexidade. Supondo que o limite é 10, basta contar.

Por que isso funciona melhor do que princípios qualitativos

Três ganhos práticos:

Uniformidade de avaliação. Quando todo mundo conta os mesmos elementos e usa o mesmo limite, a discussão sobre complexidade sai do campo não determinístico e vai para o campo determinístico. Pessoas com níveis de experiência diferentes passam a analisar complexidade sob a mesma ótica.

Automação. Algo que se resume a contar elementos e comparar com um limite é completamente entendível por um programa. Isso pode entrar no CI, num linter, ou até ser delegado a um LLM (aceitando as variações nas respostas). Não depende de julgamento humano subjetivo no momento da verificação.

Adaptabilidade. Nada é fixo. A equipe, depois de iterar, pode querer trocar os ICPs, aumentar o limite, reduzir. A métrica evolui junto com o contexto do time. Se os acoplamentos com classes do projeto pararam de ser um problema porque todo mundo já domina, a equipe pode remover esse item e adicionar outro que passe a ser mais relevante.

O experimento

Já há alguns anos, foi feito um experimento com mais de 20 pessoas, comparando refatoração convencional com refatoração guiada pelo CDD. O grupo que usou a métrica chegou a resultados mais uniformes e com complexidade menor -- independente do nível de experiência de quem refatorou.

O ponto mais interessante: pessoas menos experientes entregaram código menos complexo do que pessoas mais experientes que refatoraram sem a métrica. Quando existe um limite claro e uma forma objetiva de medir, a experiência deixa de ser o único fator determinante para a qualidade do resultado. Métodos bons fazem diferença para diminuir diferenças de experiência.

O que muda no dia a dia

Na prática, adotar o CDD significa que o code review ganha um critério a mais -- e um critério que não depende de quem está revisando. Se o arquivo passou do limite, precisa ser dividido. Se não passou, está dentro do aceitável.

Isso não substitui a análise qualitativa. Você ainda vai discutir naming, coesão, decisões de design. Mas a questão "esse arquivo está complexo demais?" deixa de ser uma discussão sem fim.

Para projetos novos, a sugestão é começar com um limite mais restritivo e ajustar conforme a equipe ganha experiência com a métrica. Para projetos existentes, o caminho é contabilizar primeiro e aplicar o limite apenas para código novo -- sem sair refatorando tudo de uma vez.

CDD dentro da Jornada Dev + Eficiente

CDD é um dos mais de 20 cursos da Jornada Dev + Eficiente. E não é um curso isolado: o controle de complexidade de código se conecta diretamente com os cursos de design de código, engenharia de requisitos e DDD. A complexidade do código que você escreve é consequência de como você refinou o requisito, modelou o domínio e organizou as responsabilidades.

A Jornada cobre de controle de complexidade de código até operação de sistemas em produção. Acesso vitalício, todas as perguntas respondidas pelos instrutores e comunidade no Discord.

Acesse https://deveficiente.com/oferta-10-por-cento para conhecer tudo que oferecemos.

O que acontece dentro do pipeline da sua aplicação LLM?

Alberto Luiz Souza — Mon, 23 Feb 2026 00:07:42 +0000

Disclaimer

Este texto foi inicialmente concebido pela IA Generativa em função da transcrição de um vídeo do canal de Daniel Romero (a pessoa que lidera nossa Especialização em Engenharia de IA). Se preferir acompanhar por vídeo, é só dar o play.

Introdução

Quando colocamos uma aplicação LLM em produção, entender o que está acontecendo internamente deixa de ser opcional. Qual prompt foi montado? Quantos tokens foram consumidos? Onde exatamente uma chamada falhou? LangSmith é uma plataforma de observabilidade do ecossistema LangChain projetada para responder essas perguntas em todos os estágios do ciclo de vida de uma aplicação LLM, da prototipagem à produção.

Um ponto relevante: apesar de fazer parte do ecossistema LangChain, o LangSmith funciona de maneira independente. Isso significa que você pode monitorar chains e agentes desenvolvidos com qualquer framework, incluindo DSPy, LlamaIndex, CrewAI, LangGraph e outros.

Configuração inicial

Para começar a utilizar o LangSmith, o processo é direto. Você cria uma conta em smith.langchain.com e, uma vez logado, tem acesso às principais seções da plataforma:

Projetos: coleções de rastreamento organizadas por aplicação
Annotations: para anotar e revisar execuções
Playground: ambiente para testes rápidos
Datasets: conjuntos de dados para avaliação de qualidade
Hub: funciona como um repositório compartilhado de prompts, ferramentas e chains, similar ao Docker Hub

A configuração no código também é simples. Você gera uma chave de API nas configurações da plataforma e define algumas variáveis de ambiente:

LANGCHAIN_TRACING_V2=true
LANGCHAIN_ENDPOINT=https://api.smith.langchain.com
LANGCHAIN_PROJECT=default
LANGSMITH_API_KEY=sua-chave-aqui

Com essas variáveis configuradas, toda a telemetria da sua aplicação é enviada automaticamente para o LangSmith. Se você já utiliza o LangChain, não precisa instalar nenhuma biblioteca adicional. O suporte ao LangSmith já vem embutido no pacote.

Exemplo 1: Monitorando uma chain do LangChain

No primeiro exemplo, temos uma chain simples que simula o comportamento de um RAG. Um system prompt orienta o assistente a responder com base apenas no contexto fornecido, e a pergunta do usuário recebe esse contexto como parâmetro.

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

prompt = ChatPromptTemplate.from_messages([
    ("system", "Você é um assistente útil. Responda a solicitação do usuário com base apenas no contexto fornecido."),
    ("user", "{question}\n\nContexto: {context}")
])

model = ChatOpenAI(model="gpt-4o-mini")
chain = prompt | model | StrOutputParser()

chain.invoke({"question": "Resuma o texto", "context": texto})

Ao executar essa chain, o LangSmith captura automaticamente todo o fluxo. No painel da plataforma, podemos ver:

RunnableSequence: um resumo completo da execução, com todo o input enviado ao LLM
ChatOpenAI: detalhes do modelo utilizado, parâmetros como temperatura (0.7 por padrão, quando não configurada explicitamente), provider e nome do modelo
Metadata: versão do LangChain, sistema operacional de origem, versão do Python e outros dados de contexto

Na lateral, o LangSmith exibe informações operacionais importantes: timestamp, latência da chamada, quantidade de tokens consumidos e um cálculo estimado de custo.

Rastreamento por etapas

Um dos recursos mais úteis é a visualização passo a passo de cada etapa da execução. Você consegue acompanhar desde a montagem do prompt com o ChatPromptTemplate, passando pelo envio para a OpenAI, até o retorno formatado pelo StrOutputParser. Cada etapa aparece separada, o que facilita a identificação de gargalos ou comportamentos inesperados.

Captura de erros

Para demonstrar a captura de erros, basta trocar o modelo para um que não existe, como "gpt-5". O LangSmith registra o erro e permite investigar exatamente em qual etapa a execução falhou. Nesse caso, o ChatPromptTemplate foi montado corretamente, mas a chamada para a OpenAI retornou um erro informando que o modelo não foi encontrado. A mensagem aparece de forma clara e direta no painel.

Exemplo 2: Monitorando aplicações sem LangChain

E se a sua aplicação LLM não utiliza o LangChain? O LangSmith também funciona nesse cenário, com algumas configurações adicionais.

No segundo exemplo, temos uma aplicação que usa diretamente o client da OpenAI, com uma função Retriever que simula a recuperação de contexto de um banco vetorial. Para habilitar o rastreamento, são necessários dois passos.

Passo 1: Wrapper do client OpenAI

O LangSmith oferece um wrapper para o client da OpenAI que habilita a coleta de métricas:

from langsmith.wrappers import wrap_openai
from openai import OpenAI

client = wrap_openai(OpenAI())

Com essa configuração, o LangSmith passa a rastrear as chamadas ao ChatOpenAI. Porém, como não há as abstrações do LangChain, o rastreamento mostra apenas a chamada ao LLM como um bloco único.

Passo 2: Rastreamento granular com @traceable

Para obter mais detalhes sobre o pipeline completo, o LangSmith fornece o decorator @traceable:

from langsmith import traceable

@traceable
def retriever(query):
    # Simula recuperação de contexto
    return "LangSmith serve para observabilidade"

@traceable
def rag(query):
    context = retriever(query)
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": f"Responda com base no contexto: {context}"},
            {"role": "user", "content": query}
        ]
    )
    return response.choices[0].message.content

Com o @traceable aplicado nas funções, o LangSmith passa a rastrear cada etapa individualmente. No painel, a execução aparece hierarquicamente: a função RAG contém a chamada ao Retriever e, dentro dela, a chamada ao ChatOpenAI. A progressão fica visível: primeiro apenas o ChatOpenAI, depois a função RAG com o ChatOpenAI dentro, e por fim a cadeia completa com Retriever e ChatOpenAI.

Monitoramento e métricas

Em projetos com maior volume de execuções, a seção Monitor do LangSmith oferece gráficos com métricas operacionais:

Contagem de erros
Quantidade de chamadas ao LLM
Taxa de sucesso nas chamadas
Métricas de latência (p50, p95)
Tokens por segundo

Essas métricas ajudam a acompanhar a saúde da aplicação em produção e identificar degradações de performance ao longo do tempo.

Avaliação de qualidade com datasets

Além do monitoramento em tempo real, o LangSmith oferece recursos para avaliar a qualidade das respostas geradas pela sua aplicação. O fluxo funciona assim:

Você cria um dataset com pares de perguntas e respostas esperadas
Carrega o dataset na plataforma
Executa a avaliação contra diferentes versões da aplicação ou diferentes modelos

No exemplo apresentado, uma comparação entre GPT-4o Mini e GPT-3.5 Turbo mostra diferenças de verbosidade, consumo de tokens, latência e custo. É possível definir um baseline e comparar o desempenho de cada modelo contra ele. Na prática, isso permite implementar testes A/B entre versões da aplicação ou entre modelos diferentes, com dados concretos para embasar a decisão.

Conclusão

LangSmith resolve um problema prático de quem desenvolve aplicações LLM: saber o que está acontecendo dentro do pipeline. A configuração é simples, funciona com ou sem LangChain, e oferece desde rastreamento básico de chamadas até avaliação comparativa de modelos. Para quem está colocando aplicações LLM em produção, ter esse nível de visibilidade sobre o comportamento do sistema pode ser a diferença entre resolver um problema em minutos ou passar horas investigando logs.

Especialização em Engenharia de IA

Conheça a Especialização em Engenharia de IA Dev + Eficiente. O curso aborda RAG, Vector Search, Busca Híbrida, Agentes, Tools e muito mais, sempre com aulas 100% práticas e com exemplos reais.

Acesse https://deveficiente.com/especializacao-engenharia-ia .

Como expor sua API REST para um agente de código sem criar servidor MCP

Alberto Luiz Souza — Mon, 16 Feb 2026 11:48:37 +0000

Disclaimer

Este texto foi inicialmente concebido pela IA Generativa em função da transcrição de um vídeo do Dev Eficiente. Se preferir acompanhar por vídeo, é só dar o play.

Introdução

Servidores MCP se tornaram a maneira padronizada de expor APIs e funcionalidades para agentes de código como Claude Code, Cursor, Codex e outros. Mas existe uma discussão relevante no mercado sobre a complexidade que eles trazem. No fundo, em muitos casos, você está criando um wrapper da sua API que já existe para expor ela para o agente. E se existisse uma alternativa mais leve, que não exigisse criar um servidor novo em cima de algo que já funciona?

Neste post, mostro como usei a funcionalidade de Agent Skills do Claude Code para expor uma API REST existente para o agente, sem alterar nenhum código da API e sem construir um servidor MCP.

O contexto: MCP, complexidade e alternativas

Na Dev + Eficiente temos essa discussão internamente. Daniel Romero tem uma visão crítica de que o MCP nasceu inchado, trazendo complexidade desnecessária em cenários onde você já tem uma API funcionando. Do outro lado, existe o argumento de que o MCP é a maneira padrão de expor coisas para agentes, o que facilita a integração do ponto de vista de quem consome.

Existem alternativas mais leves surgindo, como o UTCP (Universal Tool Calling Protocol). Mas o caminho que explorei aqui foi diferente: usar a funcionalidade de Skills do Claude Code como ponte entre o agente e a API REST existente.

O que são Agent Skills

Agent Skills é uma funcionalidade do Claude Code que permite carregar instruções e scripts localmente. A própria Anthropic posiciona as Skills como algo mais local, que direciona o agente e pode inclusive orientar o consumo de serviços expostos via MCP ou qualquer outra fonte.

A estrutura é simples. Dentro da pasta .claude/skills/, você cria uma pasta com a sua skill contendo:

Um arquivo skill.md com nome, descrição e documentação dos endpoints
Scripts que o agente pode executar para consumir a API

Se você já criou uma tool para integrar com um agente, vai reconhecer a semelhança: a skill tem um nome e uma descrição que o LLM carrega no contexto. Quando você faz um pedido, o agente verifica se existe uma skill que pode ajudar a resolver e, se houver, carrega e executa.

O experimento: Contrate um Dev Eficiente

Para testar essa abordagem, usei a plataforma Contrate um Dev Eficiente, que conecta o mercado com as pessoas que estudam conosco. O objetivo era expor o módulo de analytics da plataforma para o Claude Code sem mexer em nada no código existente.

Estrutura do arquivo de skill

O arquivo skill.md segue um formato sugerido pela Anthropic:

Nome: analytics-contrate-dev-eficiente
Descrição: Fornece acesso aos endpoints de analytics...

Autenticação:
- Token deve ser configurado
- Header de autenticação: Bearer {token}

Endpoints disponíveis:
- /api/analytics - Análise geral (parâmetros: período)
- /api/analytics/empresas - Contatos de empresas
- /api/analytics/candidatos - Candidatos com currículo
- /api/analytics/ranking - Rankings de vagas e empresas

Além da documentação dos endpoints, o arquivo referencia um bash script que o agente pode executar para consumir a API.

O bash script

O script foi gerado pelo próprio Claude Code. Subi o agente no projeto do Contrate um Dev Eficiente, passei o link da documentação de Agent Skills da Anthropic, pedi para ele ler os endpoints do módulo de analytics e gerar tanto o arquivo de skill quanto o script de consumo autenticado.

#!/bin/bash
# Verifica token, faz a requisição autenticada e retorna o resultado

O LLM carrega a skill, vê que existe um script referenciado, executa o script passando os parâmetros necessários (que estão documentados no arquivo de skill), recebe a resposta da API e trabalha em cima disso.

Na prática: como funcionou

Consultas simples

Ao pedir "quero listar as empresas cadastradas", o Claude Code identificou a skill de analytics, carregou, verificou o token de autenticação e executou a consulta. Quando passei um token expirado por engano, ele recebeu 403, tentou outro endpoint, recebeu 403 novamente e me pediu um novo token. Com o token correto, retornou os dados reais da plataforma.

Análise composta

Ao pedir "quero uma análise geral", o agente decidiu por conta própria passar o parâmetro de período como seis meses. Consultou o endpoint, recebeu os dados e construiu uma análise com funil de conversão: empresas cadastradas, empresas com vagas, vagas com candidaturas, taxas de conversão e insights sobre a atividade da plataforma.

Cruzamento entre endpoints

Essa foi a parte mais interessante. Ao pedir "quero saber os nomes de pessoas que têm currículo e o perfil tech delas", o agente precisou combinar informações de endpoints diferentes. Primeiro consultou o endpoint que retorna currículos com perfil tech, depois identificou que não tinha os nomes, foi buscar no endpoint de candidatos com currículo e cruzou os dados.

A conexão com o nível 3 de maturidade REST

Esse comportamento lembrou o modelo de maturidade REST de Richardson. No nível 3, o conceito de HATEOAS (Hypermedia as the Engine of Application State) propõe que o protocolo seja autodocumentado, com links que guiam o cliente sobre o que fazer em seguida.

Na prática, poucos clientes HTTP implementam isso de verdade. Os clientes que construímos nas empresas são determinísticos: fazem chamadas pré-definidas, não seguem links dinamicamente. O navegador é o que mais se aproxima desse nível, por respeitar a semântica dos status codes e executar código que o servidor envia.

Mas quando um LLM consome uma API documentada via skill, algo parecido acontece. Ele consulta um endpoint, percebe que a informação que precisa não está ali, identifica outro endpoint que pode complementar e faz a segunda chamada. Não é exatamente HATEOAS, mas é uma forma de navegação dinâmica entre endpoints que até então era muito difícil de implementar em clientes tradicionais.

Uma pesquisa que fiz usando Deep Research do Claude encontrou um texto da Nord KPIs citando um arquiteto da Microsoft que argumenta que HATEOAS "chegou muito antes do que era possível, mas talvez agora seja mais possível". Concordo com essa visão.

Vantagens dessa abordagem

Nenhuma alteração no código existente: a API continua funcionando como antes
Sem servidor novo para manter: não é mais uma coisa para cuidar
Localidade: a skill é local, você expõe só o que quer, da partezinha que precisa
Flexibilidade: você pode editar o arquivo de skill para o seu contexto, limitar endpoints, adicionar instruções específicas
Replicável para qualquer API REST: qualquer endpoint HTTP autenticado pode ser exposto dessa maneira

Aplicações possíveis

A mesma lógica se aplica a outros cenários. Se você tem um serviço de logs, métricas ou observabilidade com API HTTP, pode gerar um arquivo de skill e acessar tudo via terminal com um agente no momento de troubleshooting. Se quer consumir a API pública do GitHub sem instalar o servidor MCP do GitHub, pode criar uma skill que documente os endpoints que você precisa e um script de acesso autenticado.

O repositório público de skills do Claude Code no GitHub já tem exemplos homologados pela Anthropic, como manipulação de PDF com scripts em Python, branding e outros. Servem como referência para construir as suas.

Conclusão

Agent Skills do Claude Code oferecem uma alternativa pragmática para expor APIs REST para agentes de código. Não é uma substituição do MCP -- são coisas diferentes, para contextos diferentes. O MCP continua sendo o padrão para integração ampla e distribuída. Mas quando o que você precisa é algo local, leve, sem adicionar mais uma camada de infraestrutura sobre algo que já funciona, as Skills resolvem bem.

O ponto central é: se você tem uma API REST funcionando, não precisa necessariamente criar um servidor MCP por cima dela. Um arquivo Markdown descrevendo os endpoints e um script de acesso podem ser suficientes para que o agente faça o trabalho.

Dev + Eficiente

Evidence Briefing – Monólito vs Microsserviços

Alberto Luiz Souza — Mon, 09 Feb 2026 09:35:17 +0000

Monólito ou microsserviços: por onde começar?

Decidir a arquitetura inicial de um sistema de software é uma das escolhas mais consequentes — e mais debatidas — no desenvolvimento de produtos digitais. Monólitos prometem simplicidade e velocidade; microsserviços prometem escala e autonomia. Mas em que contexto cada caminho faz mais sentido? Para ir além de opiniões e modismos, conduzimos uma revisão rápida de 23 estudos acadêmicos e aplicados, sintetizando evidências sobre vantagens, desvantagens e critérios de decisão de cada abordagem. O que encontramos reforça uma ideia central: não existe arquitetura universalmente superior — existe a arquitetura mais adequada ao problema, à equipe e ao momento do produto. Neste post, compartilhamos os principais achados e os trade-offs que toda equipe deveria considerar antes de tomar essa decisão.

1.Contexto

A consolidação da Internet como principal meio de oferta de serviços digitais impulsionou o desenvolvimento de sistemas distribuídos, capazes de atender grandes volumes de usuários, operar continuamente e evoluir de forma incremental. Nesse contexto, a arquitetura de software passou a exercer papel central na sustentação de atributos como escalabilidade, confiabilidade, desempenho e capacidade de evolução, tornando as decisões arquiteturais elementos estruturantes no ciclo de vida dos sistemas (BASS; CLEMENTS; KAZMAN, 2013).

A decisão entre iniciar um sistema como monólito ou como microsserviços constitui uma das escolhas arquiteturais mais críticas no desenvolvimento de software, podendo influenciar atributos não funcionais relevantes, como escalabilidade, confiabilidade e custo de manutenção ao longo do tempo. Arquiteturas monolíticas são tradicionalmente associadas à simplicidade estrutural e à centralização do controle, enquanto arquiteturas de microsserviços propõem a decomposição do sistema em serviços pequenos e implantáveis de forma independente, frequentemente alinhados a capacidades de negócio (LEWIS; FOWLER, 2014; DRAGONI et al., 2017).

Embora o debate sobre microsserviços tenha se intensificado tanto na indústria quanto na academia, estudos apontam que os resultados associados a esse estilo arquitetural variam significativamente conforme o contexto de aplicação. Aspectos como tamanho do sistema, organização das equipes, práticas de desenvolvimento e requisitos não funcionais influenciam de forma decisiva a adequação de cada abordagem arquitetural (DI FRANCESCO; LAGO; MALAVOLTA, 2019). Ainda assim, observa-se uma lacuna de entendimento prático e acadêmico sobre como iniciar sistemas de software, especialmente nos estágios iniciais, quando decisões arquiteturais precisam ser tomadas diante de incertezas quanto à evolução futura do produto e da organização.

Essa lacuna se manifesta na dificuldade de estabelecer critérios claros para a escolha da arquitetura inicial, bem como na ausência de consensos consolidados na literatura sobre quais fatores devem ser priorizados nesse momento. Como resultado, arquiteturas monolíticas e de microsserviços são frequentemente discutidas de forma comparativa, mas sem diretrizes suficientemente explícitas sobre em quais contextos cada alternativa tende a ser mais adequada (DI FRANCESCO et al., 2018; TAIBI; LENARDUZZI; PAHL, 2017).

Diante desse contexto, este trabalho tem como objetivo analisar e sintetizar evidências existentes sobre arquiteturas monolíticas e de microsserviços, buscando responder às seguintes questões:

Quais são as vantagens e desvantagens de optar por uma arquitetura monolítica e por uma arquitetura de microsserviços?
Quais requisitos não funcionais influenciam decisões relacionadas às arquiteturas monolítica e de microsserviços?
Em quais contextos é mais adequado selecionar uma arquitetura monolítica ou uma arquitetura de microsserviços?

2. Método

Para a realização desta pesquisa foi utilizado a metodologia de Revisão Rápida. Uma revisão rápida é uma forma estruturada e transparente de reunir e resumir evidências sobre uma pergunta específica para apoiar decisões (CARTAXO et al. 2018). Isso quer dizer que, em vez de depender só de opinião ou experiências isoladas, a equipe segue um processo organizado para identificar o que já foi estudado na literatura acadêmica e transformar esses achados em insights acionáveis.

2.1 Condução da pesquisa

Inicialmente, foi realizada uma busca manual no Google Scholar para gerar conhecimento da área para os pesquisadores e aperfeiçoar as questões de pesquisa. Nesta etapa o objeto era entender as pesquisas da área e sair com background suficiente para gerar uma boa string de busca. Essa etapa resultou na seleção de 3 estudos, os quais compuseram o chamado Golden Set. Esses trabalhos foram utilizados como base de referência para validar a estratégia de busca automatizada, garantindo que os principais estudos do domínio fossem recuperados.

Em seguida, foi conduzida uma busca automatizada no IEEE, utilizando uma string de busca definida a partir dos termos-chave identificados no Golden Set. Essa busca retornou um total de 61 estudos

Na etapa seguinte, foi realizada a leitura dos resumos dos artigos encontrados, com aplicação dos critérios de inclusão e exclusão definidos no protocolo da revisão. Como resultado dessa triagem inicial, 13 estudos foram considerados aptos para a próxima fase.

Em seguida, esses estudos passaram por uma leitura completa, permitindo uma avaliação ao objetivo da pesquisa. Ao final dessa etapa, 6 estudos atenderam os critérios estabelecidos e foram selecionados a partir da busca automatizada.

Por fim, foi realizada uma busca manual no Google Scholar por artigos que citaram os 6 estudos da etapa anterior, na qual foram selecionados 14 estudos adicionais considerados relevantes para o escopo da pesquisa. Essa etapa teve como objetivo complementar a busca automatizada, garantindo a inclusão de trabalhos potencialmente relevantes que não foram recuperados pelas strings de busca definidas ou pela base selecionada. Totalizando 23 estudos identificados. Para mais informações sobre o processo, como string de busca, críterios de inclusão e exclusão, analisar o relatório de evidências.

3 Resultados

A análise dos estudos selecionados permitiu identificar um conjunto de achados relacionados à adoção da arquitetura monolítica, organizados segundo três dimensões principais: organizacional, arquitetural e relacionada às pessoas. Os resultados foram extraídos de estudos aplicados e revisões, conforme indicado nos identificadores associados a cada aspecto.

3.1 Monolito

3.1.1 Dimensão Organizacional

No que se refere à dimensão organizacional, os estudos indicaram que a arquitetura monolítica apresentou vantagens em contextos caracterizados por equipes menores e projetos de pequeno porte (GRAVANIS; KAKARONTZAS; GEROGIANNIS, 2022; VELEPUCHA; FLORES, 2023). Esses cenários foram associados a uma maior simplicidade de coordenação e menor sobrecarga organizacional, favorecendo a adoção do monolito em fases iniciais de desenvolvimento. Por outro lado, os resultados também evidenciaram que mudanças estruturais em sistemas monolíticos estiveram associadas a custos elevados, especialmente à medida que o sistema evoluiu e se tornou mais complexo (VELEPUCHA; FLORES, 2023). Esses custos foram relacionados à necessidade de modificações amplas no código e à dependência entre componentes, dificultando a adaptação organizacional ao longo do tempo.

3.1.2 Dimensão Arquitetural

Na dimensão arquitetural, os achados revelaram tanto vantagens quanto desvantagens associadas à arquitetura monolítica. Entre as vantagens, destacaram-se o desenvolvimento inicial mais simples, a centralização do código-fonte e a maior facilidade para atividades de depuração (VELEPUCHA; FLORES, 2023; MENARD, 2020; BAŠKARADA; NGUYEN; KORONIOS, 2020; CHATURVEDI et al., 2024 ). Os estudos também indicaram que os testes de construção simples, como testes de unidade, foram mais facilmente implementados nesse tipo de arquitetura, em comparação com arquiteturas distribuídas (MENARD, 2020; CHATURVEDI et al., 2024; VELEPUCHA; FLORES, 2021).

Entretanto, os resultados apontaram um conjunto consistente de desvantagens. A complexidade do sistema foi reportada como um problema recorrente, especialmente em aplicações de médio e grande porte (GRAVANIS; KAKARONTZAS; GEROGIANNIS, 2022; VELEPUCHA; FLORES, 2023; VELEPUCHA; FLORES, 2021). Questões relacionadas à escalabilidade foram frequentemente associadas à estrutura monolítica, limitando a capacidade de evolução independente dos componentes (GRAVANIS; KAKARONTZAS; GEROGIANNIS, 2022; MENARD, 2020; BAŠKARADA; NGUYEN; KORONIOS, 2020; SEEDAT; ABBAS; AHMAD, 2023). Além disso, os estudos relataram dificuldades relacionadas à manutenibilidade, alto acoplamento entre módulos e limitações na tolerância a falhas, uma vez que falhas em partes específicas do sistema puderam comprometer o funcionamento da aplicação como um todo (GRAVANIS; KAKARONTZAS; GEROGIANNIS, 2022; SEEDAT; ABBAS; AHMAD, 2023; VELEPUCHA; FLORES, 2021; CHATURVEDI et al., 2024). Outro achado relevante foi a dificuldade na realização de testes end-to-end, atribuída à dependência entre os componentes e à necessidade de execução integrada do sistema (VELEPUCHA; FLORES, 2023; BAŠKARADA; NGUYEN; KORONIOS, 2020; SEEDAT; ABBAS; AHMAD, 2023).

3.1.3 Dimensão Relacionada às Pessoas

No que diz respeito à dimensão relacionada às pessoas, o estudo indica que a adoção e manutenção de sistemas monolíticos estiveram associadas a desenvolvimento com conhecimento técnico da arquitetura, tornando a necessidade um profissional não tão especializado (MENARD, 2020).

3.2 Microserviços

3.2.1 Dimensão Organizacional

Na dimensão organizacional, a entrega mais rápida de software foi reportada como uma vantagem em dois estudos, indicando que arquiteturas de microsserviços estiveram associadas à redução do tempo de entrega em determinados contextos (MENARD, 2020; KÖNÖNEN, 2018). Em contraste, a percepção de que essa arquitetura não representou uma resposta para todos os problemas organizacionais foi identificada em um estudo (MENARD, 2020), assim como a constatação de que sua adoção foi ineficaz para software de pequeno porte, também reportada em um estudo (MENARD, 2020).

Problemas relacionados ao gerenciamento dos serviços foram reportados em dois estudos (KRUG; CHANIN; SALES, 2024; CHATURVEDI et al., 2024), evidenciando desafios associados à coordenação, monitoramento e operação de múltiplos serviços. Além disso, a falta de autonomia para deploys foi identificada em um estudo (KRUG; CHANIN; SALES, 2024), indicando limitações organizacionais em contextos específicos. Por outro lado, a autonomia de equipes foi apontada como uma vantagem em três estudos (MENARD, 2020, KÖNÖNEN, 2018; CHATURVEDI et al., 2024), sugerindo que a descentralização promovida pelos microsserviços favoreceu a independência das equipes de desenvolvimento em determinados cenários.

3.2.2 Dimensão Arquitetural

No âmbito arquitetural, a escalabilidade foi o aspecto mais frequentemente reportado, sendo identificada como vantagem em dezesseis estudos (KALSKE; MÄKITALO; MIKKONEN, 2017; GRAVANIS; KAKARONTZAS; GEROGIANNIS, 2022; NOGUEIRA et al., 2024; VELEPUCHA; FLORES, 2023; AUER et al., 2021; HMUE; PHYU; PAING, 2024; MENARD, 2020; KÖNÖNEN, 2018; HONCHARUK, 2025; BAŠKARADA; NGUYEN; KORONIOS, 2020; CHATURVEDI et al., 2024; SEEDAT; ABBAS; AHMAD, 2023; VELEPUCHA; FLORES, 2021), o que indica forte recorrência desse tema na literatura analisada. A diversidade de stacks para programar foi mencionada como vantagem em um estudo (BAŠKARADA; NGUYEN; KORONIOS, 2020), assim como a redução de código redundante, também reportada em um estudo (KÖNÖNEN, 2018). A flexibilidade na construção dos módulos foi identificada como vantagem em um estudo (KALSKE; MÄKITALO; MIKKONEN, 2017), associando a arquitetura de microsserviços à possibilidade de evolução independente dos componentes.

Por outro lado, a ambiguidade na definição e compreensão dos microsserviços foi reportada como desvantagem em um estudo(MENARD, 2020), indicando dificuldades conceituais ou de escopo. Questões relacionadas à tolerância a falhas foram identificadas como vantagem em quatro estudos (KÖNÖNEN, 2018; CHATURVEDI et al., 2024; SEEDAT; ABBAS; AHMAD, 2023; VELEPUCHA; FLORES, 2021), sugerindo que a arquitetura favoreceu o isolamento de falhas em determinados contextos. Em contrapartida, dificuldades relacionadas à realização de testes foram reportadas em três estudos (KÖNÖNEN, 2018; KRUG; CHANIN; SALES, 2024; AUER et al., 2021), indicando que a testabilidade representou um desafio recorrente em ambientes baseados em microsserviços.

3.2.3 Dimensão Relacionada às Pessoas

No que se refere à dimensão relacionada às pessoas, a falta de conhecimento técnico da equipe foi identificada como desvantagem em três estudos (MENARD, 2020; KÖNÖNEN, 2018; KRUG; CHANIN; SALES, 2024), indicando que a adoção de microsserviços esteve associada à necessidade de competências técnicas mais avançadas, tanto no desenvolvimento quanto na operação dos sistemas.

3.3 Requisitos Não Funcionais em Arquiteturas de Microsserviços

A análise dos estudos selecionados permitiu identificar um conjunto de requisitos não funcionais associados à adoção de arquiteturas baseadas em microsserviços. Esses requisitos foram extraídos de estudos aplicados e revisões, sendo classificados de acordo com sua recorrência na literatura analisada.

A escalabilidade foi o requisito não funcional mais frequentemente reportado, estando presente em 16 estudos (KALSKE; MÄKITALO; MIKKONEN, 2017; GRAVANIS; KAKARONTZAS; GEROGIANNIS, 2022; NOGUEIRA et al., 2024; VELEPUCHA; FLORES, 2023; AUER et al., 2021; HMUE; PHYU; PAING, 2024; MENARD, 2020; KÖNÖNEN, 2018; HONCHARUK, 2025; BAŠKARADA; NGUYEN; KORONIOS, 2020; CHATURVEDI et al., 2024; SEEDAT; ABBAS; AHMAD, 2023; VELEPUCHA; FLORES, 2021), o que indica forte consenso na literatura quanto à capacidade dessa arquitetura de suportar crescimento e variações de carga por meio da decomposição e escalonamento independente dos serviços. A orquestração foi identificada em dois estudos (HMUE; PHYU; PAING, 2024; BAŠKARADA; NGUYEN; KORONIOS, 2020), refletindo a necessidade de mecanismos específicos para coordenação e gerenciamento dos serviços distribuídos.

A disponibilidade foi reportada em um estudo (VELEPUCHA; FLORES, 2023), enquanto a tolerância a falhas foi identificada em quatro estudos (KÖNÖNEN, 2018; CHATURVEDI et al., 2024; SEEDAT; ABBAS; AHMAD, 2023; VELEPUCHA; FLORES, 2021 ), indicando que o isolamento de serviços contribuiu para a resiliência do sistema em determinados contextos. O reuso foi associado aos microsserviços em cinco estudos (NOGUEIRA et al., 2024; VELEPUCHA; FLORES, 2023; CARVALHO et al., 2019; HONCHARUK, 2025; GOUIGOUX; TAMZALIT, 2017), sugerindo que a modularização favoreceu a reutilização de componentes e funcionalidades. A segurança distribuída foi mencionada em dois estudos (HMUE; PHYU; PAING, 2024; VELEPUCHA; FLORES, 2021), evidenciando preocupações relacionadas à proteção de dados, autenticação e autorização em ambientes distribuídos.

O requisito de performance foi reportado em sete estudos (KALSKE; MÄKITALO; MIKKONEN, 2017; GRAVANIS; KAKARONTZAS; GEROGIANNIS, 2022; CARVALHO et al., 2019; BAŠKARADA; NGUYEN; KORONIOS, 2020; VELEPUCHA; FLORES, 2021; GOUIGOUX; TAMZALIT, 2017; BERRY et al., 2024), indicando que o impacto no desempenho foi um aspecto recorrente nas avaliações de microsserviços, tanto em termos de benefícios quanto de desafios decorrentes da comunicação entre serviços.

A refatoração foi reportada em dois estudos (KALSKE; MÄKITALO; MIKKONEN, 2017; GRAVANIS; KAKARONTZAS; GEROGIANNIS, 2022), sugerindo a necessidade de reestruturação do código durante a adoção ou evolução da arquitetura. O deploy contínuo (CI/CD) foi identificado em sete estudos (GRAVANIS; KAKARONTZAS; GEROGIANNIS, 2022; NOGUEIRA et al., 2024; VELEPUCHA; FLORES, 2023; AUER et al., 2021; HONCHARUK, 2025; BAŠKARADA; NGUYEN; KORONIOS, 2020; CHATURVEDI et al., 2024; GOUIGOUX; TAMZALIT, 2017), indicando forte associação entre microsserviços e práticas de automação de entrega. A manutenibilidade foi reportada em cinco estudos (NOGUEIRA et al., 2024; AUER et al., 2021; CHATURVEDI et al., 2024; SEEDAT; ABBAS; AHMAD, 2023; FRITZSCH et al., 2019), refletindo benefícios e desafios relacionados à evolução do sistema ao longo do tempo.

Aspectos relacionados às pessoas e à agilidade foram identificados em nove estudos (GRAVANIS; KAKARONTZAS; GEROGIANNIS, 2022; NOGUEIRA et al., 2024; AUER et al., 2021; MENARD, 2020; KÖNÖNEN, 2018; HONCHARUK, 2025; CHATURVEDI et al., 2024; SEEDAT; ABBAS; AHMAD, 2023; VELEPUCHA; FLORES, 2021), indicando que a arquitetura de microsserviços está frequentemente associada a mudanças organizacionais, maior autonomia de equipes e necessidade de adaptação de processos. Por fim, testes foram reportados em quatro estudos (VELEPUCHA; FLORES, 2023; HMUE; PHYU; PAING, 2024; BAŠKARADA; NGUYEN; KORONIOS, 2020; SEEDAT; ABBAS; AHMAD, 2023), evidenciando desafios específicos na validação de sistemas distribuídos, especialmente no que se refere a testes de integração e ponta a ponta.

3.4 Síntese dos Critérios para Seleção entre Arquitetura Monolítica e Microsserviços

A análise dos estudos selecionados permitiu sintetizar um conjunto de critérios decisórios associados à escolha entre arquitetura monolítica e arquitetura de microsserviços, considerando o tipo de problema a ser resolvido, o contexto organizacional e o estágio de maturidade da empresa. Os resultados indicaram que a decisão arquitetural esteve diretamente relacionada às características do negócio, da equipe e dos objetivos do sistema.

No caso da arquitetura monolítica, os estudos indicaram que sua adoção esteve associada a cenários nos quais o objetivo principal foi a validação de ideias, o desenvolvimento de projetos pequenos e a redução do tempo de entrada no mercado. Esses contextos foram caracterizados por equipes menores, estrutura técnica mais simples e custos iniciais reduzidos. A literatura analisada apontou que tais características tornaram a arquitetura monolítica particularmente adequada para startups e organizações em estágio inicial, especialmente quando houve necessidade de construção rápida de produtos mínimos viáveis (MVPs) com baixo investimento inicial.

Em contraste, a arquitetura de microsserviços foi associada a contextos nos quais requisitos como segurança, testes contínuos, crescimento do negócio, resiliência, observabilidade e escalabilidade organizacional e técnica foram mais relevantes. Os estudos indicaram que essa arquitetura foi mais frequentemente adotada por empresas consolidadas, caracterizadas por operações em larga escala, múltiplos domínios de negócio e disponibilidade de investimento para sustentar a complexidade arquitetural. Nesses cenários, a adoção de microsserviços esteve associada a custos mais elevados, tanto em termos técnicos quanto organizacionais, compensados pela capacidade de evolução independente dos serviços.

Os resultados também indicaram que, independentemente da arquitetura adotada, a decisão impactou a organização como um todo, exigindo alinhamento entre estrutura organizacional, processos de desenvolvimento e capacidades técnicas. A literatura destacou que a arquitetura selecionada demandou dinâmicas organizacionais específicas para que seus benefícios fossem efetivamente alcançados, incluindo adequações na forma de trabalho das equipes, nos processos de entrega e na governança técnica.

De modo geral, a síntese dos estudos analisados indicou que a escolha entre arquitetura monolítica e microsserviços não esteve associada exclusivamente a critérios técnicos, mas resultou de uma combinação de fatores organizacionais, estratégicos e humanos, os quais influenciaram diretamente a sustentabilidade da arquitetura ao longo do tempo.

4. Discussão

Os resultados deste briefing reforçam que a escolha entre monólito e microsserviços é, sobretudo, dependente de contexto e do “momento” do produto. No conjunto analisado (23 estudos), o monólito aparece mais associado a cenários de menor complexidade organizacional e técnica, com equipes menores e projetos pequenos, destacando benefícios como simplicidade de desenvolvimento, centralização do código, facilidade de depuração e testes mais simples quando comparados a cenários distribuídos.

Ao mesmo tempo, a literatura indica que, à medida que o sistema cresce, tendem a emergir limitações ligadas a complexidade, acoplamento, manutenaibilidade e escalabilidade, além do custo de mudanças que podem exigir reconstrução/redeploy de toda a aplicação.

Já os microsserviços são descritos principalmente como resposta a demandas de escalabilidade e evolução independente (desenvolver, implantar e escalar serviços separadamente), com benefícios adicionais frequentemente citados como isolamento de falhas e flexibilidade evolutiva.

Contudo, essa arquitetura introduz um custo de coordenação e operação: surgem desafios como definir e delimitar serviços (onde “cortar”), testes mais difíceis, gerência/observabilidade e maior dependência de expertise técnica para lidar com a complexidade distribuída.

Do ponto de vista de requisitos não funcionais e critérios de decisão, há uma diferença importante: para microsserviços, a síntese destaca concentração em escalabilidade e em capacidades organizacionais ligadas a entrega (agilidade, CI/CD e governança de deploy), enquanto no monólito aparecem com mais ênfase testes, arquitetura simples, time-to-market, custo, deploy fácil e depuração como critérios recorrentes.

Esse contraste sugere que “iniciar” com microsserviços tende a fazer mais sentido quando o problema já nasce com demandas claras de escala/resiliência e trabalho paralelo entre equipes, enquanto o monólito tende a favorecer fases de maior incerteza, validação (MVP) e foco em velocidade/custo.

Por fim, há um alerta metodológico relevante: a evidência utilizada é heterogênea e o relatório-base não inclui avaliação detalhada de qualidade metodológica por artigo; portanto, este briefing deve ser usado como apoio à decisão, não como regra universal.

Além disso, a própria revisão foi conduzida como revisão rápida, isto é, um processo estruturado e transparente para sintetizar evidências visando apoiar decisões, o que reforça a necessidade de interpretar os achados com pragmatismo e cautela. Vale salientar também que devido a escolha desse método, é possível que existam outros artigos que não foram capturados na busca. Para minimizar o impacto, foi realizado uma busca manual nas citações.

5. Conclusão

Com base na síntese dos 23 estudos, a decisão entre monólito e microsserviços deve ser orientada por (i) tipo de problema, (ii) requisitos não funcionais, (iii) contexto organizacional e (iv) Capacidade técnica da equipe, evitando adoção por “moda” e priorizando a capacidade real de operação e entrega.

Em estágios iniciais e contextos com equipes menores, alta incerteza e prioridade em simplicidade, velocidade e custo, o monólito tende a ser uma alternativa mais adequada, com ganhos em desenvolvimento, testes e depuração, ainda que possa exigir revisão arquitetural conforme o sistema cresce.

Quando o sistema já enfrenta (ou claramente enfrentará) demandas fortes de escalabilidade/resiliência, necessidade de deploy independente e trabalho paralelo entre equipes, os microsserviços tendem a ser mais adequados, desde que a organização consiga sustentar a complexidade adicional (delimitação de serviços, testes distribuídos e operação/observabilidade).

Por se tratar de uma revisão rápida e por a evidência ser heterogênea, recomenda-se usar este briefing como base para uma decisão consciente, complementando com análise do contexto local (produto, equipe e operação) e registrando explicitamente os trade-offs assumidos

Apêndice A – Estudos analisados (títulos e IDs)

Lista do relatório-base:

Referências

BASS, Len; CLEMENTS, Paul; KAZMAN, Rick. Software Architecture in Practice. 3. ed. Boston: Addison-Wesley, 2013.

DI FRANCESCO, Paolo; LAGO, Patricia; MALAVOLTA, Ivano. Architecting with microservices: A systematic mapping study. Journal of Systems and Software, v. 150, p. 77–97, 2019.

DI FRANCESCO, Paolo et al. Migrating towards microservices: An industrial survey. In: Proceedings of the IEEE International Conference on Software Architecture (ICSA). 2018.

DRAGONI, Nicola et al. Microservices: Yesterday, today, and tomorrow. In: Present and Ulterior Software Engineering. Cham: Springer, 2017. p. 195–216.

LEWIS, James; FOWLER, Martin. Microservices. 2014. Disponível em: https://martinfowler.com/articles/microservices.html.

TAIBI, Davide; LENARDUZZI, Valentina; PAHL, Claus. Processes, motivations, and issues for migrating to microservices architectures: An empirical investigation. IEEE Cloud Computing, v. 4, n. 5, p. 22–32, 2017.

Cartaxo, B.; Pinto, G.; Soares, S. The Role of Rapid Reviews in Supporting Decision-Making in Software Engineering Practice. In: Proceedings of the 22nd International Conference on Evaluation and Assessment in Software Engineering (EASE’18). 2018. p. 24–34. DOI: 10.1145/3210459.3210462.

GRAVANIS, Dimitrios; KAKARONTZAS, George; GEROGIANNIS, Vassilis. You don’t need a Microservices Architecture (yet): Monoliths may do the trick. In: Proceedings of the 2021 European Symposium on Software Engineering (ESSE ’21). New York, NY, EUA: ACM, 2022. p. 39–44. DOI: 10.1145/3501774.3501780.

VELEPUCHA, Victor; FLORES, Pamela. A survey on microservices architecture: Principles, patterns and migration challenges. IEEE Access, v. 11, p. 88339–88358, 2023.

VELEPUCHA, Victor; FLORES, Pamela. Monoliths to microservices: Migration problems and challenges: A SMS. In: 2021 Second International Conference on Information Systems and Software Technologies (ICI2ST). IEEE, 2021.

MENARD, Niklas. Decision criteria between microservice and monolithic architecture. 2020.

BAŠKARADA, Saša; NGUYEN, Vivian; KORONIOS, Andy. Microservices architecture: opportunities and practical challenges. Journal of Computer Information Systems, 2020.

CHATURVEDI, Mayank et al. From monolith to microservices: A systematic literature review. In: 2024 IEEE 3rd International Conference on Data, Decision and Systems (ICDDS). IEEE, 2024. p. 1–6.

KALSKE, Miika; MÄKITALO, Niko; MIKKONEN, Tommi. Challenges when moving from monolith to microservice architecture. Cham: Springer International Publishing, 2017. p. 32–47.

NOGUEIRA, Vinicius L. et al. Insights on microservice architecture through the eyes of industry practitioners. In: 2024 IEEE International Conference on Software Maintenance and Evolution (ICSME). IEEE, 2024. p. 765–777.

AUER, Florian et al. From monolithic systems to microservices: An assessment framework. Information and Software Technology, v. 137, p. 106600, 2021.

CARVALHO, Luiz et al. Analysis of the criteria adopted in industry to extract microservices. In: 2019 IEEE/ACM CESI & SER&IP. IEEE, 2019. p. 22–29.

HMUE, Khant; PHYU, Myat Pwint; PAING, Aye Myat Myat. Microservices vs monolith: A comparative analysis and problem-solving approach in web development area. In: 2024 IEEE ICAIT. IEEE, 2024. p. 1–5.

BLINOWSKI, Grzegorz; OJDOWSKA, Anna; PRZYBYŁEK, Adam. Monolithic vs. microservice architecture: A performance and scalability evaluation. IEEE Access, v. 10, p. 20357–20374, 2022.

MENDONÇA, Nabor C. et al. The monolith strikes back: Why Istio migrated from microservices to a monolithic architecture. IEEE Software, v. 38, n. 5, p. 17–22, 2021.

KÖNÖNEN, Heini. Microservices: Considerations before implementation. 2018.

HONCHARUK, Vitalii. Do you really need microservices architecture? 2025.

KRUG, Daniel dos Santos; CHANIN, Rafael; SALES, Afonso. Exploring the pros and cons of monolithic applications versus microservices. In: ICEIS 2024 – Volume 2. 2024.

WANG, Yingying; KADIYALA, Harshavardhan; RUBIN, Julia. Promises and challenges of microservices: An exploratory study. Empirical Software Engineering, v. 26, n. 4, p. 63, 2021.

DI FRANCESCO, Paolo; LAGO, Patricia; MALAVOLTA, Ivano. Migrating towards microservice architectures: An industrial survey. In: 2018 IEEE ICSA. IEEE, 2018. p. 29–2909.

SEEDAT, Momil; ABBAS, Qaisar; AHMAD, Nadeem. Systematic mapping of monolithic applications to microservices architecture. arXiv:2309.03796, 2023.

FRITZSCH, Jonas et al. Microservices migration in industry: Intentions, strategies, and challenges. In: 2019 IEEE ICSME. IEEE, 2019. p. 481–490.

GOUIGOUX, Jean-Philippe; TAMZALIT, Dalila. From monolith to microservices: Lessons learned on an industrial migration to a web oriented architecture. In: 2017 IEEE ICSAW. IEEE, 2017. p. 62–65.

BERRY, Vincent et al. Is it worth migrating a monolith to microservices? An experience report on performance, availability and energy usage. In: 2024 IEEE ICWS. IEEE, 2024. p. 944–954.

HABIB, Pamungkas Imam et al. Architecture migration from monolithic to microservices: Developing readiness criteria. IEEE Access, v. 12, p. 194630–194645, 2024.

CHATURVEDI, Mayank et al. From Monolith to Microservices: A Systematic Literature Survey. In: 2024 IEEE 3rd International Conference on Data, Decision and Systems (ICDDS). IEEE, 2024. p. 1-6.

BAŠKARADA, Saša; NGUYEN, Vivian; KORONIOS, Andy. Architecting microservices: Practical opportunities and challenges. Journal of Computer Information Systems, 2020.

GOUIGOUX, Jean-Philippe; TAMZALIT, Dalila. From monolith to microservices: Lessons learned on an industrial migration to a web oriented architecture. In: 2017 IEEE international conference on software architecture workshops (ICSAW). IEEE, 2017. p. 62-65.

O que 70 especificações me ensinaram sobre agentes de código

Alberto Luiz Souza — Mon, 12 Jan 2026 10:55:51 +0000

Disclaimer

Este texto foi inicialmente concebido pela IA Generativa em função da transcrição de um vídeo do Dev Eficiente. Se preferir acompanhar por vídeo, é só dar o play.

Introdução

Depois de escrever quase 70 especificações para construir um projeto de ponta a ponta, quero compartilhar o que aprendi sobre Spec Driven Development. Esse tema tem ganhado tração por conta da capacidade de descrever o que você quer em linguagem natural e deixar um agente de código gerar o necessário para você.

O projeto em questão foi a plataforma Contrato Dev Eficiente, que conecta nossa comunidade de pessoas que estudam conosco com empresas que precisam de profissionais com vontade de aprender. Não foi um experimento pontual - foram muitas especificações, tanto para backend quanto para frontend, e o resultado está no ar sendo usado.

O contexto atual do Spec Driven Development

Recentemente, saiu um post no blog de Martin Fowler escrito por Birgitta Bockler, Distinguished Engineer e AI Assisted Delivery Expert na ThoughtWorks. Ela testou três ferramentas: Kiro (da Amazon), SpecKit e Tessel. O texto discute diferentes abordagens.

Eu olhei o Kiro quando a Amazon lançou e uma pessoa da comunidade Dev Eficiente me indicou o SpecKit. Confesso que quando olhei, não me interessou no sentido de ser o caminho mais promissor para mim. A maioria dessas ferramentas trabalha com a ideia de você escrever a feature inteira e deixar que a especificação seja fonte para quebra de tarefas, para que o LLM planeje as tarefas necessárias.

O que funcionou para mim não foi bem do jeito que está descrito nesses textos.

A evolução das minhas especificações

O começo: linguagem natural detalhada

Na minha primeira especificação, eu queria importar pessoas alunas da plataforma de cursos para o novo sistema. Era um código de importação e eu estava menos preocupado com design naquele momento.

O template inicial tinha:

Objetivo
Pacote/pasta onde o código deveria ser gerado
Referências importantes (como links de documentação)
Detalhes de implementação em linguagem natural

Eu dava detalhes bem granulares: "cria o controller que seja capaz de importar todos os membros que ainda não foram importados anteriormente", "quando fizer a primeira chamada, já verifica se existe o primeiro email", "a chamada deve ser feita pelo cliente X que deve vir do application properties e deve obrigatoriamente ser definida como variável de ambiente".

O problema? Percebi que estava investindo muito tempo escrevendo parágrafos em linguagem natural explicando o que eu queria.

O problema do código gerado por LLMs

A média do código que vem do LLM, para o tipo de design que eu queria construir, não era suficiente. Mesmo tendo um arquivo CLAUDE.md com guidelines, as decisões de design vinham com características que me incomodavam:

Código pouco coeso: O LLM é bom quando você quer generalização, mas quando você pensa em coesão e separação de responsabilidades, o código gerado geralmente não atende às expectativas.

Eu ficava olhando e pensando: "não é por esse caminho que eu quero". E aí comecei a refatorar bastante código, o que me fez questionar se essa era a melhor abordagem.

A virada: contratos de código ao invés de linguagem natural

A minha versão final das especificações é bem diferente. Ao invés de tentar descrever o código em linguagem natural, o que mais funcionou foi:

Pensar nas classes e arquivos necessários para fazer determinado fluxo
Investir tempo nos métodos públicos - as assinaturas, os parâmetros, o retorno
Não pensar na implementação, apenas nos contratos

Por exemplo, numa especificação recente eu tinha:

Referências:
- Classe RecuperaAnaliseArquivoCurriculo (já declarada com métodos e parâmetros)
- ArquivoCurriculoRepository (estrutura já definida)

Eu declarava os métodos, os parâmetros, escrevia a classe que representava a resposta. Aí eu olhava e falava: "acho que o controller está bom, preciso desses parâmetros, com esses parâmetros eu consigo fazer o que quero fazer".

Exemplo prático: sistema de agentes

Numa especificação para criar agentes de análise, eu escrevi as classes antes:

// No arquivo prepara.ts
class AgenteAnalisadorDeFormacoes { }
class AgenteAnalisadorDeExperiencias { }
class AgenteAnalisadorDeHabilidadesTecnicas { }
class AnalisadorAgregado { } // junta tudo
class AgenteAnaliseCompleta { } // chama todos e retorna análise final

A explicação de alto nível foi apenas: "a partir de um ID de arquivo de currículo, precisamos analisar o currículo, criando um feedback e uma sugestão de versão atualizada".

As referências que eu quero que o agente use, e pronto.

O que delego vs. o que eu defino

A combinação que funcionou para mim foi:

Delego para o agente:

Coisas que quero fazer e não sei direito como (detalhes de implementação de bibliotecas específicas)
Coisas que simplesmente não ligo para o como

Por exemplo, numa especificação eu precisava:

Código que utilizasse o Cloudflare R2 (S3 compatível) - não sabia usar a biblioteca
Storage genérico para ter versão local e remota para desenvolvimento
Usar Apache Tika para extrair texto de currículos (doc, pdf, texto)

Eu falei: "coda isso pra mim", porque não sabia os detalhes, mas sabia que precisava.

Eu defino:

As interfaces (assinaturas dos métodos)
Como uma coisa se conecta com a outra
O fluxo de alto nível

Spec Driven Development no Frontend

O mesmo padrão funcionou no frontend. Uma especificação para tela de candidaturas ficou assim:

Objetivo: Possibilitar que o contato de empresa logada visualize
os candidatos para uma determinada vaga.

Referências:
- A tela de listagem de candidaturas é essa: [componente]
- O endpoint que deve ser acessado é esse: [endpoint]
- Retorno do endpoint: [exemplo JSON]

Explicação de alto nível:
- Essa tela deve ser só para pessoa logada
- Os links de GitHub e LinkedIn apontam para endereços internos
  que retornam [formato X] - lidar com isso
- Fazer o link de visualizar candidaturas ir para essa nova tela

Eu entregava o endpoint, o retorno do endpoint, e pedia para codar a tela em função desse limite estabelecido.

A granularidade que funciona

Esse é um tema importante citado no texto da ThoughtWorks. Minha observação não indica que pegar uma ideia de feature e investir tempo para o LLM planejar as tarefas seja o jeito mais eficiente.

A granularidade que funciona para mim é a de Task.

Pensando nas nomenclaturas: se você tem Épico > História > Task (como no Jira), o que tem funcionado é pegar a Task e usar Spec Driven Development para ela. Não a feature inteira, não o épico - a task.

Sobre ferramentas específicas

Não usei nenhuma ferramenta dedicada a Spec Driven Development. Olhando as ferramentas, sinceramente não acho que precisa - mas não vou falar muito fortemente porque não usei a fundo. Os agentes de código que já existem (Claude Code, Codex, Gemini CLI) com um template minimamente razoável já fazem muito bem o trabalho.

Parei de pedir testes de início

Outra mudança: parei de pedir para escrever testes logo de cara. Prefiro primeiro ver o código gerado, e depois escrever os testes automatizados. Isso me deu mais controle sobre a qualidade final.

Além de código: documentação

A mesma ideia funcionou para construir documentações. Spec Driven Development para gerar documentação significa: delinear o que preciso na documentação, como escrevo, meus padrões de escrita, o template - e deixar o agente gerar.

Conclusão

O padrão que funcionou para mim em Spec Driven Development foi:

Pensar na tarefa (não na feature inteira)
Definir os contratos de código - classes, interfaces, assinaturas de métodos, parâmetros, retornos
Escrever explicação de alto nível - apenas o suficiente para contextualizar
Delegar detalhes de implementação que não sei ou não me importo como são feitos
Limitar a autonomia do agente para o fluxo já delineado

Não foi tentar fazer tudo em linguagem natural. Foi uma união entre estrutura de código que limita a autonomia e contexto em linguagem natural para o que precisa de explicação.

É experiência de campo, de um projeto real que está no ar. Fiz muitas vezes - não foi uma nem duas - e esse é o setup que tem funcionado mais para mim quando penso em engenharia de contexto para agentes de código.

Dev + Eficiente

Semantic Cache: Como Otimizar Aplicações RAG com Cache Semântico

Alberto Luiz Souza — Mon, 05 Jan 2026 10:00:15 +0000

Disclaimer

Este texto foi inicialmente concebido pela IA Generativa em função da transcrição de um vídeo do canal de Daniel Romero(a pessoa que lidera nossa especialização em Engenharia de IA). Se preferir acompanhar por vídeo, é só dar o play.

Introdução

Ao trabalhar com aplicações baseadas em RAG (Retrieval-Augmented Generation), um dos desafios é lidar com o custo e a latência de processar perguntas repetidas. Cada vez que um usuário faz uma pergunta, todo o pipeline precisa ser executado novamente, mesmo que a resposta já tenha sido gerada anteriormente. Neste post, vamos explorar como o Semantic Cache pode resolver esse problema de forma elegante e eficiente.

O que é Cache?

Um cache é uma memória de alta velocidade que armazena de forma eficiente os dados acessados com frequência. A ideia é simples: em vez de recalcular ou buscar uma informação toda vez que ela é solicitada, armazenamos o resultado para uso futuro.

O Pipeline RAG Tradicional

Em um RAG tradicional, quando um usuário faz uma pergunta, o sistema executa várias etapas: faz o embedding da pergunta, pesquisa em um vector database (podendo realizar busca por palavra-chave, semântica ou híbrida), recupera os documentos relevantes, envia o contexto junto com o prompt e a pergunta original para o LLM, e finalmente retorna a resposta gerada ao usuário.

Se o usuário fizer a mesma pergunta repetidamente, todo esse processo ocorre a cada requisição. Como você pode imaginar, isso é custoso tanto em termos de tempo quanto de dinheiro.

O Problema do Cache Tradicional

Para evitar gerar a mesma resposta várias vezes para uma pergunta frequente, podemos armazenar as perguntas e suas respectivas respostas em um cache. Por exemplo, se o usuário perguntar "Qual é a capital do Brasil?" pela primeira vez, geramos a resposta seguindo o pipeline de RAG e salvamos no cache. Na próxima vez que a mesma pergunta for feita, recuperamos a resposta do cache.

Esse tipo de cache é bastante comum e funciona com um mecanismo de chave-valor: a pergunta é a chave e a resposta é o valor. Porém, há um problema importante.

Ao trabalhar com um cache do tipo key-value, pequenas variações na formulação de uma pergunta podem resultar em um valor de hash diferente. Por exemplo, "Qual é a capital do Brasil?" e "Você pode me dizer a capital do Brasil?" são essencialmente a mesma pergunta, mas sua formulação literal é diferente. Se usarmos uma abordagem simples para procurar a resposta no cache, provavelmente não vamos conseguir encontrar, porque a versão hash da pergunta é diferente.

A Solução: Semantic Cache

Para melhorar a precisão dos resultados da busca, podemos usar um cache semântico em vez de confiar em um mecanismo de combinação exata (Exact Match). Isso envolve armazenar as perguntas, respostas e seus embeddings em um mecanismo de chave-valor.

Quando um usuário faz uma pergunta, podemos realizar uma busca semântica em todas as perguntas no cache para encontrar a mais semelhante. Se o score de similaridade entre a pergunta do usuário e a pergunta mais similar no cache estiver acima de um determinado limite, podemos assumir que a pergunta é essencialmente a mesma e fornecer a resposta correspondente.

O cache tradicional opera com base em combinação exata: quando você procura uma chave, ele verifica se ela existe no cache. Já o cache semântico funciona de maneira diferente: ele pesquisa semanticamente, procurando o significado da chave em vez de uma combinação exata. Por exemplo, "Qual é a capital do Brasil?" versus "Me diga o nome da capital do Brasil" terão o mesmo resultado em um cache semântico, pois a formulação é diferente, mas o significado é o mesmo. Em contraste, um cache tradicional falharia para a segunda pergunta.

Vantagens e Considerações

Se você estiver utilizando um LLM em um sistema de perguntas e respostas e tiver que fazer muitas chamadas para a API, essa operação vai custar caro. É aqui que uma solução de cache semântico se destaca, porque será extremamente eficiente e rápida, economizando tempo e dinheiro do projeto.

Usar cache também é uma ótima maneira de otimizar o desempenho de chatbots, armazenando dados acessados com frequência. Uma abordagem interessante é criar patches ad-hoc para diálogos de chatbots, identificando perguntas feitas com frequência e preparando respostas pré-escritas. O chatbot pode recuperar rapidamente as respostas do cache e responder instantaneamente, sem acessar um LLM. Isso garante consistência nas respostas para perguntas como "Qual é o endereço da loja?".

Por outro lado, usar cache pode não ser uma boa ideia se você quiser diferentes variações para a mesma consulta. No entanto, em um sistema de perguntas e respostas, a variação geralmente não importa.

Implementação Prática

Em uma implementação prática, é possível utilizar o mesmo vector database tanto para armazenamento dos documentos quanto para o cache semântico. Por exemplo, utilizando Qdrant: o armazenamento vetorial com dados em cloud para busca semântica, e o cache com persistência em memória.

Quando o usuário faz uma pergunta, é necessário fazer o embedding da pergunta. Essa parte deve ser feita independentemente de utilizar cache ou não, porque para fazer uma busca, tanto no vector database quanto no cache, são necessários embeddings. Lembrando que esse custo está bem reduzido se comparado com os LLMs.

A função de cache verifica se a pergunta já foi respondida, buscando através de todos os embeddings e comparando com o embedding da pergunta. Se estiver no cache, retorna a resposta armazenada. É importante definir um limite adequado baseado na métrica utilizada. Por exemplo, com distância euclidiana, quanto menor o valor, melhor (mais próximo de zero significa maior similaridade). Se fosse similaridade do cosseno, números maiores significariam maior semelhança.

Se a pergunta não existir no cache, o sistema passa pelo processo normal de RAG: busca semântica no vector database, encontra os chunks mais similares, envia como contexto junto com a consulta do usuário e o prompt para o LLM. Ao final, gera uma nova resposta e a salva no cache para uso futuro.

Conclusão

O Semantic Cache é uma técnica poderosa para otimizar aplicações RAG, permitindo economia significativa de tempo e custos ao evitar processamentos redundantes. A chave está em entender que perguntas semanticamente equivalentes devem retornar a mesma resposta, mesmo quando formuladas de maneiras diferentes.

Dev+ Eficiente

Este conteúdo é parte do ecossistema Dev+ Eficiente, mantido por Alberto junto com Maurício Aniche e Rafael Ponte, que inclui um canal e dois treinamentos. O primeiro é a Jornada Dev+ Eficiente, cujo foco é fazer com que você seja capaz de entregar software que de fato gera valor com o máximo de qualidade e eficiência.

O segundo é a especialização em Engenharia de IA, uma parceria com Daniel Romero, cuja ideia é habilitar você para entregar software de excelência, integrando sistemas com LLMs.

Conheça mais em https://deveficiente.com/interesse-especializacao-engenharia-ia

Como Criar um Chatbot com RAG do Zero: Guia Prático com OpenAI e Qdrant

Alberto Luiz Souza — Mon, 29 Dec 2025 18:29:00 +0000

Disclaimer

Este texto foi inicialmente concebido pela IA Generativa em função da transcrição de um vídeo do canal de Daniel Romero(a pessoa que lidera nossa especialização em Engenharia de IA). Se preferir acompanhar por vídeo, é só dar o play.

Um detalhe importante é que o vídeo exemplifica com LangChain e aqui nós preferimos deixar apenas com o suficiente.

Introdução

Retrieval-Augmented Generation, ou simplesmente RAG, é uma técnica que tem revolucionado a forma como construímos aplicações de inteligência artificial. Neste post, vamos criar um chatbot do zero usando essa técnica — sem frameworks intermediários, direto nos SDKs. Ao final, você será capaz de criar um chatbot usando modelos GPT da OpenAI (ou alternativas como Groq) integrado a um banco de dados vetorial. Esse chatbot poderá responder perguntas relacionadas a qualquer documentação interna de uma empresa, por exemplo.

O Problema: Por Que LLMs Alucinam?

Antes de colocar a mão na massa, vale entender por que precisamos do RAG em primeiro lugar.

Aplicações mais simples fazem uma consulta direta em um LLM para obter respostas. Isso funciona bem para conhecimento geral ou informações que o modelo viu durante a fase de treino. O problema? Muitos LLMs simplesmente não viram informações suficientes sobre tópicos que gostaríamos de entender.

Se você perguntar ao GPT-3.5 Turbo o que tem de tão especial no modelo Mistral 7B, provavelmente não vai receber uma boa resposta. O Mistral é um modelo de linguagem recente que não foi incluído nos dados de treino da maioria dos LLMs. Resultado: eles fornecem informações incorretas ou simplesmente inventam algo.

Outro exemplo interessante: o Qdrant é um sistema de banco de dados que indexa e recupera dados vetoriais em alta dimensão. Porém, ao perguntar ao GPT-4 o que é Qdrant, ele pode dizer que não encontra informações sobre o termo e sugerir que você errou a digitação. Isso indica claramente que o modelo não tem ideia do que é Qdrant. O conhecimento de um LLM é limitado ao que foi aprendido durante o treinamento — ele não tem acesso ao mundo exterior.

E sim, o termo técnico para esse comportamento é alucinação.

Por Que Isso Acontece?

LLMs alucinam porque dependem exclusivamente do conhecimento aprendido durante o processo de treino. O modelo não aprende explorando o mundo. Se algo não estiver em seus dados de treino, ele não vai saber — e mesmo que esteja, pode não ser preciso, levando a ambiguidades.

O propósito de um LLM é comprimir as informações dos dados de treino em um modelo interno do mundo. Esse tipo de conhecimento é chamado de conhecimento paramétrico, porque é armazenado nos parâmetros do modelo. E esses parâmetros são congelados após o treinamento, ou seja, o LLM não pode aprender coisas novas ou se adaptar a novas situações.

A Solução: RAG

É aqui que entra o RAG(Retrieval Augmented Generation) para apoiar na resolução desse problema. A ideia é adicionar um componente intermediário — que pode ser um Pipeline RAG, uma busca no Google, ou uma comunicação com uma fonte externa como um banco de dados SQL.

Com o RAG, adicionamos um componente de memória externa que pode ser modificado e atualizado: uma espécie de memória de longo prazo. Isso permite que o sistema se adapte a novas situações, indo além do que o modelo aprendeu originalmente.

No caso do RAG, é comum usar um banco de dados vetorial como memória externa. A vantagem? Podemos adicionar, excluir e gerenciar a memória e o conhecimento da aplicação. É quase como gerenciar ou atualizar informações no cérebro de uma pessoa — uma analogia um pouco distópica, mas que ilustra bem o conceito.

Esse método é chamado de Source Knowledge, diferente do conhecimento paramétrico, porque o conhecimento não é armazenado nos parâmetros do modelo.

Construindo um Chatbot Básico

Vamos à prática. Primeiro, instalamos os pacotes necessários:

pip install openai qdrant-client

Para trabalhar com a API da OpenAI, o chatlog é representado como uma lista de dicionários. Cada dicionário contém uma role (que pode ser system, user ou assistant) e o content com o texto correspondente:

from openai import OpenAI

client = OpenAI()  # usa a variável de ambiente OPENAI_API_KEY

messages = [
    {"role": "system", "content": "Você é um assistente útil que responde a perguntas."},
    {"role": "user", "content": "Olá, bot, como você está hoje?"},
    {"role": "assistant", "content": "Estou bem, obrigado! Como posso ajudar?"},
    {"role": "user", "content": "Gostaria de entender o que é Machine Learning."}
]

response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=messages
)

Para ver o texto da resposta:

print(response.choices[0].message.content)

A resposta pode ser adicionada ao histórico para continuar a conversa:

messages.append({
    "role": "assistant", 
    "content": response.choices[0].message.content
})

Agora, se fizermos uma nova pergunta sobre "a diferença entre supervisionado e não supervisionado" — sem mencionar a palavra "aprendizado" — o modelo consegue manter o contexto e responder sobre "aprendizado supervisionado e não supervisionado". Isso mostra que o histórico de conversação está funcionando corretamente.

Montar esse chatbot básico é relativamente fácil. Não tem nada complicado acontecendo aqui.

Preparando os Dados para o RAG

Para adicionar conhecimento externo ao chatbot, precisamos de uma base de conhecimento. Neste exemplo, usamos um dataset do Hugging Face que contém o paper do Mistral 7B já dividido em chunks — ou seja, o texto do artigo já foi pré-processado e separado em pedaços menores, prontos para serem indexados.

O dataset tem várias colunas (como id, title, summary), mas para esse exemplo só precisamos de duas: chunk (o pedaço de texto) e source (a fonte de onde veio):

import pandas as pd

# Carrega o dataset e isola as colunas relevantes
df = df[["chunk", "source"]]

# Cada registro contém o texto e sua origem
chunks = df["chunk"].tolist()
sources = df["source"].tolist()

Gerando Embeddings

Para indexar os chunks no banco de dados vetorial, precisamos transformá-los em vetores (embeddings). Usamos a API de embeddings da OpenAI:

def get_embedding(text):
    response = client.embeddings.create(
        model="text-embedding-ada-002",
        input=text
    )
    return response.data[0].embedding

Integrando o Banco de Dados Vetorial

Agora vamos adicionar tudo isso ao banco de dados vetorial. Usaremos o Qdrant diretamente:

from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams, PointStruct

# Inicializa o cliente (em memória para este exemplo)
qdrant = QdrantClient(":memory:")

# Cria a coleção
qdrant.create_collection(
    collection_name="chatbot",
    vectors_config=VectorParams(size=1536, distance=Distance.COSINE)
)

Agora indexamos os chunks. Para cada chunk, geramos o embedding e inserimos no banco:

points = []
for i, (chunk, source) in enumerate(zip(chunks, sources)):
    embedding = get_embedding(chunk)
    points.append(PointStruct(
        id=i,
        vector=embedding,
        payload={"text": chunk, "source": source}
    ))

qdrant.upsert(collection_name="chatbot", points=points)

Conectando a Base de Conhecimento ao LLM

Estamos quase terminando. Falta conectar a base de conhecimento ao nosso LLM.

Podemos testar a comunicação com o banco de dados vetorial executando uma consulta:

query = "O que tem de tão especial no Mistral 7B?"

results = qdrant.search(
    collection_name="chatbot",
    query_vector=get_embedding(query),
    limit=3
)

Isso retorna os três chunks mais similares semanticamente à pergunta. Lembra que antes o LLM não conseguia responder essa pergunta? Agora é diferente — estamos obtendo chunks diretamente do artigo sobre o Mistral 7B.

O resultado é útil, mas um pouco difícil de ler. Para resolver isso, deixamos o LLM processar essa informação.

Criando o Prompt com RAG

Configuramos uma função que recupera os itens mais relevantes do banco de dados vetorial e monta o prompt com contexto:

def augmented_prompt(query):
    # Recupera os chunks relevantes
    results = qdrant.search(
        collection_name="chatbot",
        query_vector=get_embedding(query),
        limit=3
    )

    # Extrai o texto dos resultados
    source_knowledge = "\n".join([r.payload["text"] for r in results])

    # Monta o prompt com contexto
    prompt = f"""Use o contexto abaixo para responder a pergunta.

Contexto:
{source_knowledge}

Pergunta: {query}"""

    return prompt

Agora, no System Prompt, informamos ao LLM para utilizar o contexto para responder:

query = "O que tem de tão especial no Mistral 7B?"

messages = [
    {"role": "system", "content": "Use o contexto abaixo para responder a pergunta."},
    {"role": "user", "content": augmented_prompt(query)}
]

response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=messages
)

print(response.choices[0].message.content)

E agora temos uma resposta baseada no conteúdo do paper: "Mistral 7B é um modelo de linguagem com 7 bilhões de parâmetros, projetado para oferecer desempenho superior e eficiência." Pelo menos ele não está dizendo que é um vinho!

Considerações Sobre o RAG

Implementar o RAG de forma ingênua — assumindo que toda consulta exige uma busca na base de conhecimento — nem sempre é necessário. Se um usuário cumprimentar o chatbot com "Oi, tudo bem? Como você está?", não faz sentido consultar uma base externa para responder.

Além disso, o tempo de inferência pode ser lento dependendo do modelo e da API escolhida. Essa é uma desvantagem, mas os benefícios compensam:

Melhor desempenho de retrieval
Maior precisão nas respostas
Possibilidade de fornecer citações das fontes
Mais rápido e eficiente que outras abordagens, como Agents
Controle sobre o número de tokens

Alternativa com Groq para Inferência Rápida

Pensando em aplicações reais, usar apenas a OpenAI pode trazer dois problemas: custo (que sobe rapidamente) e tempo de inferência (às vezes crítico).

Uma alternativa com inferência muito mais rápida é o Groq, capaz de gerar cerca de 800 tokens por segundo. Para usá-lo, basta instalar o pacote:

pip install groq

O SDK do Groq segue a mesma estrutura da OpenAI, então a migração é simples:

from groq import Groq

groq_client = Groq()  # usa a variável de ambiente GROQ_API_KEY

response = groq_client.chat.completions.create(
    model="llama-3.1-70b-versatile",
    messages=messages,
    temperature=0
)

print(response.choices[0].message.content)

A execução é muito mais rápida que o GPT. E como ambos os SDKs seguem a mesma interface, podemos reutilizar exatamente a mesma estrutura de mensagens e a função augmented_prompt que criamos antes — basta trocar o cliente.

Conclusão

Um pipeline RAG basicamente recupera informações, utiliza essas informações como contexto e gera respostas. Essa abordagem resolve o problema fundamental das alucinações em LLMs ao adicionar uma fonte de conhecimento externa que pode ser atualizada e gerenciada independentemente do modelo.

Os pontos principais:

LLMs têm conhecimento limitado ao que foi aprendido durante o treinamento (conhecimento paramétrico)
O RAG adiciona uma "memória de longo prazo" que pode ser modificada (Source Knowledge)
Bancos de dados vetoriais são a escolha comum para armazenar esse conhecimento
Os SDKs da OpenAI e Groq seguem interfaces similares, facilitando a troca entre provedores

Especialização em Engenharia de IA

Este conteúdo é um trecho de uma das aulas da Especialização em Engenharia de IA, uma parceria com a Dev Mais Eficiente. O curso aborda RAG, Vector Search, Busca Híbrida, Agents, Tools e muito mais, sempre com aulas 100% práticas e com exemplos reais.

Faça sua inscrição em https://deveficiente.com/especializacao-engenharia-ia .

Como Implementar um Sistema RAG do Zero em Python

Alberto Luiz Souza — Mon, 22 Dec 2025 18:15:40 +0000

Disclaimer

Este texto foi inicialmente concebido pela IA Generativa em função da transcrição de um vídeo do canal de Daniel Romero(a pessoa que lidera nossa especialização em Engenharia de IA). Se preferir acompanhar por vídeo, é só dar o play.

Introdução

RAG (Retrieval-Augmented Generation) é uma técnica que combina busca por similaridade com geração de texto por LLMs para criar respostas mais precisas e contextualizadas. Neste post, vamos implementar um sistema RAG simples do zero, usando apenas três bibliotecas: NumPy, Sentence Transformers e Grok.

O que vamos construir

Nosso sistema RAG terá três componentes principais: geração de embeddings para os documentos, busca por similaridade usando similaridade do cosseno e geração de resposta usando um LLM.

Configuração inicial

Para este exemplo, precisamos instalar apenas três bibliotecas:

pip install numpy sentence-transformers grok

Vamos trabalhar com o básico, sem banco vetorial por enquanto. NumPy será usado para os cálculos, Sentence Transformers para os embeddings e Grok para o LLM.

Começamos com os imports:

import numpy as np
from sentence_transformers import SentenceTransformer
from grok import Grok

Carregando o modelo e gerando embeddings

O modelo que vamos utilizar é o all-MiniLM-L6-v2. Ele é pequeno, rápido e muito eficiente. Vale destacar que esse modelo funciona bem apenas para o idioma inglês, então para produção com conteúdo em português seria necessário trocar de modelo.

Um detalhe importante: esses modelos de embeddings são treinados olhando para milhões de pares de textos. Alguns pares são positivos, como duas frases que querem dizer a mesma coisa, ou uma pergunta com a resposta certa. Outros pares são negativos, com duas frases sem relação nenhuma. O treino funciona basicamente dizendo para o modelo: "esses dois aqui têm que ficar perto, e esses outros aqui têm que ficar distantes". Depois de repetir isso milhares de vezes, o modelo aprende a transformar qualquer texto em um vetor de números que preserva o sentido.

model = SentenceTransformer('all-MiniLM-L6-v2')
client = Grok()

# Seus documentos (fonte de conhecimento)
documents = [
    # Lista de documentos sobre machine learning
]

# Gerar embeddings de todos os documentos
doc_embeddings = model.encode(documents)

Com essa única linha, todos os documentos se transformam em vetores numéricos. No caso do all-MiniLM-L6-v2, cada documento tem 384 dimensões do tipo float32. Como não temos um banco vetorial neste momento, esses vetores ficam guardados na memória.

Entendendo a similaridade do cosseno

Uma das partes mais importantes é como medir a distância entre dois textos. Para resolver isso, implementamos a similaridade do cosseno.

A fórmula da similaridade do cosseno é expressa como:

similarity(A, B) = cos(θ) = (A · B) / (||A|| × ||B||)

O numerador A · B representa o produto escalar dos vetores A e B, calculado multiplicando cada elemento de A pelo elemento correspondente de B e somando todos esses produtos. No denominador, temos o produto das normas euclidianas dos dois vetores.

Geometricamente, essa fórmula calcula o cosseno do ângulo θ entre os dois vetores no espaço n-dimensional. Quando θ é igual a zero graus, os vetores apontam na mesma direção e o cosseno vale 1, indicando máxima similaridade. Quando θ é igual a 90 graus, os vetores são perpendiculares e o cosseno vale zero, indicando nenhuma similaridade.

Veja um exemplo prático:

v1 = np.array([1, 2, 3])
v2 = np.array([4, 5, 6])

# Produto escalar
dot_product = np.dot(v1, v2)  # Resultado: 32

# Magnitude (norma euclidiana)
magnitude = np.linalg.norm(v1) * np.linalg.norm(v2)

# Similaridade do cosseno
similarity = dot_product / magnitude  # Resultado: 0.97 (97% de similaridade)

Essa etapa final mede o quanto os vetores v1 e v2 estão na mesma direção.

Implementando as funções do RAG

Função de similaridade do cosseno

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

Função de recuperação de documentos

def retrieve(query, top_k=3):
    # Gera o embedding da query
    query_embedding = model.encode(query)

    # Calcula similaridade com todos os documentos
    similarities = []
    for i, doc_embedding in enumerate(doc_embeddings):
        sim = cosine_similarity(query_embedding, doc_embedding)
        similarities.append((i, sim))

    # Ordena pela similaridade (maior primeiro)
    similarities.sort(key=lambda x: x[1], reverse=True)

    # Retorna os top_k documentos mais relevantes
    return [(documents[idx], sim) for idx, sim in similarities[:top_k]]

Função de geração de resposta

def generate_answer(query, retrieved_docs):
    # Junta os documentos em um contexto único
    context = "\n".join([doc for doc, _ in retrieved_docs])

    response = client.chat.completions.create(
        model="llama-3.1-8b-instant",
        messages=[
            {
                "role": "system",
                "content": "Você é um especialista em machine learning. Use apenas o contexto fornecido para responder as perguntas."
            },
            {
                "role": "user",
                "content": f"Contexto fornecido:\n{context}\n\nPergunta do usuário: {query}"
            }
        ],
        temperature=0
    )

    return response.choices[0].message.content

A temperatura zero garante que as respostas sejam mais determinísticas e focadas no contexto.

Função principal RAG

def rag(query, top_k=3):
    # Recupera os documentos mais relevantes
    retrieved = retrieve(query, top_k)

    # Gera a resposta com o LLM
    answer = generate_answer(query, retrieved)

    return answer, retrieved

Testando o sistema

answer, docs = rag("O que é machine learning?")

print(answer)

# Mostra os documentos recuperados com suas similaridades
for doc, similarity in docs:
    print(f"- {similarity:.3f}: {doc}")

Próximos passos

Em projetos mais complexos, temos ainda mais desafios. Teríamos um banco de dados vetorial, estratégia de extração de conteúdo, chunking, filtros, metadados e muito mais. Mas essa é a base, e agora você entende como o RAG funciona na prática.

Especialização em Engenharia de IA

Faça sua inscrição em https://deveficiente.com/especializacao-engenharia-ia .