TP2: O Oráculo RAG

Bancos Vetoriais, Busca Semântica e Spring AI (Fase 3 do Pipeline)

Published

25/07/2026

Modified

25/07/2026

🧭 Por que este TP existe?

No TP1, vocês construíram um classificador que prevê as skills de um exercício. Mas prever skills é apenas a Fase 2 do Pipeline WOKDEX. Na Fase 4, o Agente de I.A. vai precisar gerar cenários de teste do tipo MISCONCEPTION — e ele não pode inventar esses cenários do nada, senão ele alucina (produz informações plausíveis mas incorretas).

Para evitar alucinações, o agente precisa de memória: um banco de dados de exercícios reais que ele possa consultar antes de criar algo novo. Quando o agente recebe um exercício sobre “divisão”, ele precisa poder perguntar: “Quais exercícios parecidos com este já existem no corpus? Quais misconceptions já foram mapeadas para problemas de divisão?”

Essa técnica se chama RAG (Retrieval-Augmented Generation) — Geração Aumentada por Recuperação. É a técnica mais utilizada pela indústria atualmente para fazer I.A. Generativa funcionar com dados reais sem alucinar.

A missão do TP2 é construir o Oráculo: um microsserviço em Java + Spring Boot que armazena o corpus WOKDEX num Banco de Dados Vetorial e devolve exercícios similares via busca semântica.

📖 Leitura Obrigatória (Fundamentação)

Antes de programar, vocês precisam ler e entender estes dois artigos científicos. Eles serão a base do Draft 2 na seção de Trabalhos Relacionados.

Artigo 1: Lewis, P. et al. (2020). “Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks”. arXiv:2005.11401

Por que ler: Este é O paper que inventou o RAG. Publicado pelo Facebook AI Research, ele demonstra formalmente que buscar documentos relevantes antes de gerar texto reduz drasticamente as alucinações de LLMs. É leitura obrigatória para qualquer engenheiro de I.A. em 2026. O conceito de “Retrieve → Augment → Generate” que vocês implementarão no Spring AI vem diretamente deste paper.

Artigo 2: Mikolov, T. et al. (2013). “Efficient Estimation of Word Representations in Vector Space”. arXiv:1301.3781

Por que ler: Este é o paper do Word2Vec, a pesquisa do Google que revolucionou o NLP ao mostrar que palavras podem ser representadas como vetores numéricos em um espaço geométrico. Sem entender esse conceito, você não sabe o que está sendo salvo no Banco Vetorial. Quando o Spring AI converte um enunciado em um vetor de 1536 dimensões, ele está usando uma evolução direta do Word2Vec.

🔄 O que é RAG? (Retrieval-Augmented Generation)

RAG é um padrão arquitetural que funciona em 4 passos:

  1. Ingestão: Os documentos (os arquivos .md do corpus WOKDEX) são lidos e “quebrados” em pedaços menores (chunks).
  2. Embedding: Cada chunk é convertido num vetor numérico de alta dimensão (ex: 1536 dimensões) usando um modelo de embeddings (como o OpenAI ADA-002 ou similar).
  3. Armazenamento: Os vetores são salvos num Banco de Dados Vetorial (como ChromaDB, PGVector ou Neo4j) que permite busca por similaridade geométrica (KNN — K vizinhos mais próximos).
  4. Recuperação (Retrieve): Quando chega uma pergunta (“exercícios sobre divisão”), o sistema converte a pergunta em vetor e busca os K vetores mais próximos no banco. Os documentos correspondentes são injetados como contexto no prompt do LLM.

[!NOTE] O nome “Oráculo” vem do fato de que este serviço sabe a resposta antes de perguntar ao LLM: ele recupera documentos reais verificados. O LLM então raciocina sobre esses documentos, não sobre seu conhecimento genérico.

📦 O que você vai indexar?

O mesmo Corpus de exercícios que o professor forneceu no TP1 será ingerido no banco vetorial. Cada arquivo .md vira um “documento” indexado. A busca semântica vai recuperar exercícios por similaridade de enunciado, não por palavra-chave exata.

Exemplo: se o agente buscar “divisão de números com casas decimais”, o banco pode retornar o exercício “Divisão” (que trata de int vs double) mesmo que a frase exata não apareça no enunciado — porque os vetores de embedding capturam o significado semântico, não apenas as palavras.

Data Limite de Entrega (Checkpoint 2): 26/10 (Segunda-feira)

Valor: 10 Pontos (5 em Grupo, 5 Individual)

👥 A Divisão de Tarefas na Equipe (4 Alunos)

Sua equipe deverá se dividir em duas grandes forças-tarefa.

📚 Dupla 1: Ingestão e Vetorização (O Dado)

Essa dupla foca na extração e na modelagem estrutural do Banco de Dados Vetorial.

  • Aluno A (Engenheiro de Ingestão e Chunking):
    • Trabalho Individual: O Calcanhar de Aquiles do RAG é a ingestão de texto muito grande. O Aluno A criará a lógica de Ingestão (ETL) que lê o material base do WOKDEX (seja PDFs ou grandes bancos de dados) e programa os Splitters para aplicar técnicas precisas de Chunking (Overlap) sem perder o contexto de um problema.
  • Aluno B (Arquiteto de VectorDB):
    • Trabalho Individual: Sobe e administra o servidor nativo do Banco de Dados Vetorial (VectorDB, ex: ChromaDB, PGVector ou Neo4j). Configura a persistência em disco, mapeia as coleções vetoriais e é o responsável pela eficiência da indexação de alta dimensão (HNSW).

☕ Dupla 2: Spring Boot e IA (O Servidor)

Essa dupla constrói o wrapper corporativo, a API robusta que serve os dados para consumo final.

  • Aluno C (Desenvolvedor Spring MVC):
    • Trabalho Individual: Constrói a espinha dorsal web da aplicação em Java. Configura as Injeções de Dependência (@Service, @RestController), define o DTO (Data Transfer Object) de saída para quem chama a API, e constrói o robusto ControllerAdvice para capturar falhas globais.
  • Aluno D (Engenheiro Spring AI / Orquestrador RAG):
    • Trabalho Individual: Utilizando a biblioteca Spring AI, liga todas as peças. Conecta-se ao modelo de Embeddings (ex: OpenAI ADA-002), dispara o texto de busca, realiza o Retrieve (Busca Vetorial) no banco do Aluno B, processa os Prompts restritos de contexto (Augment) e devolve o pacote formatado para a camada Web.

🔌 A API que você vai construir

O produto final de engenharia do TP2 é uma API REST que recebe uma consulta textual e retorna os exercícios mais similares do corpus. Abaixo está o contrato exato:

Requisição: GET /search?q=divisao+com+casas+decimais&k=3

Resposta esperada:

{
  "query": "divisao com casas decimais",
  "results": [
    {
      "exercise_id": "0003",
      "title": "Divisão",
      "similarity_score": 0.94,
      "skills": ["matematica", "io"],
      "snippet": "O algoritmo deve ler dois números e dividi-los..."
    },
    {
      "exercise_id": "0012",
      "title": "Média Aritmética",
      "similarity_score": 0.78,
      "skills": ["matematica", "io", "arredondamento"],
      "snippet": "Calcule a média de 3 valores reais..."
    },
    {
      "exercise_id": "0045",
      "title": "Preço do Combustível",
      "similarity_score": 0.65,
      "skills": ["matematica", "condicionais"],
      "snippet": "Calcule o custo por litro..."
    }
  ],
  "total_indexed": 500,
  "search_time_ms": 42
}

[!IMPORTANT] No TP3, o Agente Autônomo vai chamar esta API como uma ferramenta (search_similar_cases()). Se o seu Spring Boot não estiver de pé e respondendo neste formato, o agente não tem contexto e vai alucinar.

📝 A Entrega Global (O Grupo)

1. O Código Unificado

Os alunos entregam o projeto Java completo no repositório. O fundamental da Engenharia de Software será avaliado pelo uso do docker-compose.yml. * Auditoria: O professor rodará o Compose do grupo. Esse script precisa subir simultaneamente o Banco Vetorial e o Servidor Spring Boot. Um script de teste (uma rota /search) será acionada para garantir que problemas similares do WOKDEX estão sendo recuperados.

2. O Rascunho Científico (Draft 2)

O grupo integrará mais 2 a 3 páginas ao rascunho anterior (SBC). O escopo deste documento para o TP2 compreende: * Arquitetura RAG: Explicação e ilustração de como o Pipeline foi montado, desde a ingestão da base até a injeção do contexto. * Métricas de Recuperação: Avaliação empírica do sistema. Qual o Latency (tempo de resposta) do banco de dados? Na busca semântica, o sistema obteve alta Fidelidade ou trouxe documentos irrelevantes para o Prompt? (A biblioteca Ragas pode ser utilizada aqui para gerar os gráficos).

(Diferentes bancos vetoriais serão alocados aos grupos para enriquecer a discussão empírica no artigo).

📊 Rubrica de Avaliação Detalhada (10 Pontos)

Nota Individual (5 pts)

Critério Pontos Detalhes
Commits individuais na branch correta 1 Avaliado via Git Blame
Módulo individual funciona isoladamente 3 Ingestão OK (A) OU VectorDB sobe (B) OU Spring MVC responde (C) OU RAG retorna resultados (D)
Qualidade e organização do código 1 Clean Code, DTOs, nomes descritivos

Nota do Grupo (5 pts)

Critério Pontos Detalhes
docker-compose up sobe o banco e a API 2 O professor roda uma única linha e tudo funciona
Busca semântica retorna exercícios relevantes 1 Top-3 resultados são semanticamente coerentes com a query
Draft 2 com arquitetura RAG e métricas 2 Diagrama da arquitetura, latência, discussão de fidelidade
Back to top