Arquitetura do AetherMap
Este documento descreve o desenho técnico do AetherMap como sistema de cartografia semântica e RAG híbrido.
Visão Geral
O AetherMap tem duas capacidades principais:
- Cartografia semântica: transformar um corpus em um mapa 3D navegável, com clusters, métricas textuais, duplicados e entidades.
- RAG híbrido: responder perguntas usando documentos recuperados por busca semântica e lexical, com reranking e citações.
O backend fica concentrado em ../app.py. Ele expõe uma API FastAPI, mantém jobs em cache de memória e usa modelos locais para embeddings/reranking, além de APIs externas para geração e busca web.
Fluxo de Ingestão
Upload TXT/CSV
-> leitura inteligente do arquivo
-> seleção da coluna textual, quando CSV
-> lista de textos
-> embeddings SentenceTransformer
-> UMAP ou PCA para 3D
-> HDBSCAN para clusters
-> normalização dos embeddings
-> índice FAISS
-> índice BM25
-> métricas globais
-> análise de duplicados
-> análise TF-IDF por cluster
-> cache em memória por job_id
O endpoint responsável é /process/.
Saídas principais de /process/
| Campo | Significado |
|---|---|
job_id |
Identificador do processamento salvo em cache |
metadata.num_documents_processed |
Total de documentos processados |
metadata.num_clusters_found |
Número de clusters HDBSCAN sem contar ruído |
metadata.num_noise_points |
Pontos classificados como ruído (-1) |
metrics.riqueza_lexical |
Tamanho do vocabulário filtrado |
metrics.top_tfidf_palavras |
Palavras mais relevantes por TF-IDF global |
metrics.entropia |
Entropia de Shannon das contagens de termos |
duplicates |
Duplicados exatos e pares semanticamente muito similares |
cluster_analysis |
Top termos por cluster |
plot_data |
Coordenadas 3D, cluster e texto para visualização |
Fluxo de Busca RAG
Query + job_id
-> validação do job em cache
-> expansão opcional da query via LLM
-> embedding da query
-> busca FAISS
-> busca BM25
-> fusão RRF quando híbrido
-> reranking CrossEncoder quando habilitado
-> top documentos como contexto
-> prompt de resposta com regras de citação e honestidade
-> resposta via OpenRouter
O endpoint responsável é /search/.
Modos de Ablação
| Modo | Uso |
|---|---|
faiss_only |
Mede a força da recuperação semântica pura |
bm25_only |
Mede a força da busca lexical pura |
hybrid |
Mede o ganho da fusão FAISS + BM25 por RRF |
hybrid_rerank |
Mede o ganho do CrossEncoder sem expansão de query |
full |
Mede o pipeline completo |
Esses modos são valiosos porque permitem responder a uma pergunta de engenharia importante: cada componente está pagando seu custo de latência com ganho real de qualidade?
Escolhas Técnicas
FAISS + BM25
FAISS cobre similaridade semântica: bom para sinônimos, paráfrases e linguagem natural. BM25 cobre correspondência lexical: bom para nomes próprios, termos raros, códigos, siglas e consultas onde a palavra exata importa. A fusão por RRF reduz a dependência de uma única fonte de ranking.
Reranker CrossEncoder
O reranker avalia pares (query, documento) diretamente. Isso custa mais que cosine similarity, mas tende a melhorar precisão nos top resultados, que são justamente os documentos que entram no prompt do LLM.
UMAP/PCA + HDBSCAN
UMAP cria uma projeção 3D mais fiel para exploração visual, mas pode ser caro em datasets grandes. O fast_mode troca UMAP por PCA para reduzir o custo. HDBSCAN encontra clusters por densidade sem exigir um número fixo de grupos.
Cache em Memória
O cache global guarda df, embeddings, índices FAISS/BM25 e dados auxiliares por job_id. Isso simplifica o MVP e acelera buscas depois do upload, mas não é persistente. Em produção, uma evolução natural seria persistir os artefatos em disco, Redis, Postgres/pgvector, Qdrant, Milvus ou outro banco vetorial.
Dependências Externas
| Serviço | Onde entra |
|---|---|
| OpenRouter | Geração de resposta, expansão de query e descrição de clusters |
| Tavily | Busca web em /search_web/ |
| Hugging Face / SentenceTransformers | Download/carregamento dos modelos locais |
| spaCy | NER PT/EN para grafo de entidades |