TP2: O Oráculo RAG

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

Conteúdo de estudo sobre TP2: O Oráculo RAG para a disciplina de Inteligência Artificial II (Prof. Aléssio M. Jr).
Published

24/08/2026

Modified

24/08/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)

🧠 Modelo de Embedding (Definição)

Para converter textos em vetores, o grupo utilizará um dos modelos abaixo, conforme sorteio do professor:

Modelo Dimensões Custo Observação
all-MiniLM-L6-v2 (Sentence-Transformers) 384 🆓 Gratuito Modelo padrão. Roda localmente, sem API key.
text-embedding-3-small (OpenAI) 1536 💰 Pago API key fornecida pelo professor (cota compartilhada).
models/text-embedding-004 (Google) 768 💰 Pago API key fornecida pelo professor (cota compartilhada).

[!TIP] A variação experimental entre grupos (diferentes modelos de embedding) gerará dados comparativos ricos para o Draft 2. Documente qual modelo foi usado e justifique no artigo.

👥 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 (8 Pontos)

Nota Individual (4 pts)

Critério Pontos Detalhes
Commits individuais na branch correta 1 Avaliado via Git Blame
Módulo individual funciona isoladamente 2 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 (4 pts)

Critério Pontos Detalhes
docker-compose up sobe o banco e a API 1.5 O professor roda uma única linha e tudo funciona
Busca semântica retorna exercícios relevantes 0.5 Precision@3 ≥ 60% no Golden Test Set (ver abaixo)
Draft 2 com arquitetura RAG e métricas 2 Diagrama da arquitetura, latência P95, discussão de fidelidade

Métricas Obrigatórias no Draft 2

O grupo deve reportar, no mínimo, as seguintes métricas no Draft 2:

Métrica O que mede Como calcular
Precision@3 Dos 3 documentos retornados, quantos são relevantes? relevantes_no_top3 / 3
MRR (Mean Reciprocal Rank) Em que posição o documento mais relevante aparece? 1 / posição_do_primeiro_relevante
Latência P95 Tempo de resposta no percentil 95 Medir 100 queries, pegar o 95º valor
Total Indexado Quantos documentos estão no banco Retornado no JSON de resposta

🎯 Golden Test Set (Avaliação Objetiva)

O professor fornecerá um Golden Test Set — um conjunto de 10 queries com os exercícios esperados no Top-3. Exemplo:

golden_tests:
  - query: "divisão com casas decimais"
    expected: ["0003-divisao", "0012-media", "0045-combustivel"]
  - query: "maior elemento de um vetor"
    expected: ["0022-maior-valor", "0031-busca-linear", "0048-extremos"]
  - query: "verificar se número é primo"
    expected: ["0055-primo", "0067-crivo", "0071-divisores"]

O score de Precision@3 é calculado automaticamente contra este gabarito. Isso garante avaliação objetiva e reprodutível.

🧪 Testes de Integração Obrigatórios

# Teste O que verifica
1 test_compose_up docker-compose up sobe banco + API sem erros
2 test_ingest_documents Endpoint de ingestão insere documentos no VectorStore
3 test_search_returns_results GET /search?q=...&k=3 retorna exatamente 3 resultados
4 test_similarity_score_range Cada similarity_score está entre 0.0 e 1.0
5 test_golden_query Pelo menos 2 dos 3 resultados de uma query do Golden Test Set são corretos

📅 Cronograma Sugerido (4 Semanas)

Para não acumular trabalho e perder a data de entrega, sugerimos o seguinte ritmo para a equipe:

Período Foco da Equipe Meta da Semana
Semana 1 Pesquisa e Setup Leitura do artigo (Lewis 2020), setup do Docker (docker-compose com VectorDB) e criação do projeto Spring Boot.
Semana 2 Ingestão de Dados Script/endpoint de geração de embeddings e ingestão de todo o Corpus WOKDEX no banco vetorial.
Semana 3 RAG e Busca Construção do endpoint de busca semântica, integração com Spring AI e testes manuais de similaridade.
Semana 4 Qualidade e Escrita Testes de integração (Precision@3), refinamento dos resultados, redação do Draft 2 e Merge Request final.

✅ Checklist de Entrega — TP2

🔬 Adendo IC — Taxonomia de Erros e Infra de Agentes (Opcional)

Esta seção é exclusiva para equipes da Trilha IC. As equipes regulares podem ignorá-la. Se uma equipe IC desistir da trilha, o adendo já feito conta como +1 ponto bônus na nota regular do TP2.

Enquanto todas as equipes constroem o RAG, as equipes IC aproveitam para preparar a infraestrutura do TP3 Master em paralelo.

Parte A — Taxonomia de Erros (Pesquisa)

Antes de simular alunos errando (TP3 Master), é preciso saber que tipos de erro existem. A equipe IC documenta:

Nível Tipo de Erro Exemplo Subtipo WOKDEX
CS1 Tipo de dado inadequado int vs double na divisão TYPE
CS1 Formatação de saída Falta de \n, espaço extra FORMAT
CS2 Lógica off-by-one i <= n vs i < n no loop STRATEGY
CS2 Caso-base faltando Recursão sem if (n == 0) STRATEGY
CS3 Força bruta onde cabe DP O(2ⁿ) vs O(N²) STRATEGY

Entregável: Planilha com ≥ 15 tipos de erro catalogados, organizados por nível (CS1/CS2/CS3) e subtipo WOKDEX (TYPE/FORMAT/STRATEGY).

Parte B — Setup LangGraph e vLLM (Infraestrutura)

A equipe IC configura o ambiente que será usado no TP3 Master:

  1. Conectar ao vLLM na AWS (API key fornecida pelo professor).
  2. Instalar LangGraph e criar um grafo mínimo de teste:
    • Nó 1: recebe um enunciado
    • Nó 2: chama o LLM para classificar skills
    • Nó 3: retorna JSON formatado
  3. Documentar a arquitetura dos 3 Agents que serão construídos no TP3 Master (diagrama).

Entregável: Notebook Python (setup_langgraph.ipynb) com o grafo mínimo rodando + diagrama dos 3 Agents.

Checklist IC-TP2

[!TIP] Ao final do TP2, a equipe IC terá: (1) o RAG funcional (como todas), (2) a taxonomia de erros que alimenta o Agent Novice, e (3) o esqueleto do LangGraph pronto. No TP3 Master, é só plugar os agentes.

Back to top