theuSil/semantic-search-engine

🔍 Semantic Search Engine

Motor de busca semântica que encontra documentos por significado, não por correspondência exata de palavras — construído para explorar o pipeline fundamental de recuperação de informação usado em sistemas de RAG.

Como funciona

1. Embeddings: cada documento é convertido em um vetor denso usando o modelo all-MiniLM-L6-v2 (sentence-transformers), que captura o significado semântico do texto, não apenas as palavras que ele contém.
2. Indexação vetorial: os vetores são armazenados no ChromaDB usando índice HNSW com similaridade por cosseno.
3. Busca: a query do usuário é embeddada com o mesmo modelo, e o ChromaDB retorna os k documentos mais próximos no espaço vetorial.
4. Visualização: os embeddings de alta dimensão (384 dimensões) são projetados em 2D com UMAP, permitindo visualizar como os documentos se agrupam por proximidade semântica — documentos de temas parecidos ficam visualmente próximos no mapa, mesmo sem compartilhar vocabulário.

Por que essas escolhas

• Cosseno em vez de distância euclidiana: para embeddings de texto, o que importa é a direção do vetor (o significado), não sua magnitude — cosseno é o padrão para esse caso de uso.
• UMAP em vez de PCA/t-SNE: preserva melhor tanto a estrutura local quanto global dos clusters, e escala bem para datasets maiores.
• Modelo multilingual: como o dataset de exemplo está em português, um modelo multilingual generaliza melhor do que um treinado só em inglês.

Rodando localmente

pip install -r requirements.txt
python app.py

Limitações conhecidas

• Índice em memória (chromadb.Client()) — reinicia a cada deploy. Para persistência entre sessões, trocar por chromadb.PersistentClient().
• UMAP com dataset pequeno (n_neighbors baixo) tende a formar clusters menos estáveis do que em datasets maiores — o parâmetro se ajusta automaticamente conforme o tamanho do dataset.

Próximos passos (evolução planejada)

Este é o primeiro de uma série de projetos sobre RAG e agentes de IA. Os próximos adicionam: RAG com citação de fonte, busca híbrida (vetorial + BM25) com re-ranking, e agentes com tool use.