| # 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: |
|
|
| 1. Cartografia semântica: transformar um corpus em um mapa 3D navegável, com clusters, métricas textuais, duplicados e entidades. |
| 2. 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](../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 |
|
|
| ```text |
| 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 |
|
|
| ```text |
| 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 | |
|
|
|
|
