Python 3.12+ RAG Modular Embeddings Locais (CPU) Arquitetura BYOK

📄 DocuMind AI

Aplicação de Retrieval-Augmented Generation (RAG) para indexação de documentos PDF e perguntas em linguagem natural com respostas fundamentadas exclusivamente no conteúdo enviado e citação de documento e página.

Aviso sobre esta hospedagem: Este Space utiliza sdk: static para apresentar a documentação e disponibilizar o código-fonte público. A demonstração interativa em Streamlit não está hospedada nesta versão — siga as instruções abaixo para executar a aplicação localmente.

Arquitetura e Fluxo RAG

[Upload PDF] ─▶ document_loader.py ─▶ text_splitter.py ─▶ embeddings.py (local) ─▶ vector_store.py (ChromaDB) │ [Pergunta] ───▶ embeddings.py (local) ───────────────────────▶ retriever.py (Top 3-5) ──────────┘ │ ▼ [Resposta + Fontes] ◀── app.py (Streamlit) ◀── rag_pipeline.py ◀── llm.py (BYOK: Gemini / Groq)

Componentes Principais

Embeddings Locais (Sentence Transformers)

Utiliza sentence-transformers/all-MiniLM-L6-v2 localmente na CPU via PyTorch (384 dimensões). O mesmo modelo é usado na indexação e nas consultas, carregado uma única vez por processo com cache local e sem necessidade de API Key.

Banco Vetorial (ChromaDB)

Armazena textos, vetores e metadados (source, page, chunk_index) com similaridade de cosseno, filtro de distância máxima (max_distance=0.85), remoção de chunks órfãos na reindexação e isolamento por coleção/sessão.

Integração Gemini e Groq

Geração via Google Gemini API (google-genai) e Groq API via REST (httpx). Os trechos recuperados são enviados como contexto fechado para reduzir alucinações e citar documento e página.

Funcionamento do BYOK (Bring Your Own Key)

Modo Gemini

Solicita apenas GEMINI_API_KEY na barra lateral e utiliza a Google Gemini API.

Modo Groq

Solicita apenas GROQ_API_KEY e realiza a geração diretamente pela Groq API.

Modo Gemini + Fallback Groq

Usa Gemini como primário e aciona Groq automaticamente apenas em falhas temporárias elegíveis (429, 5xx, timeout ou erro de rede), avisando na interface.

Segurança e Privacidade

  • Credenciais apenas em memória: chaves BYOK ficam somente em st.session_state, nunca são gravadas em disco, no ChromaDB, em logs ou no histórico de chat, e podem ser limpas pelo botão Limpar credenciais.
  • Sanitização de erros: padrões de chaves e headers Bearer são mascarados antes de exibição ou log.
  • Isolamento por sessão: cada sessão usa token aleatório (secrets.token_urlsafe) e coleção isolada no ChromaDB.
  • Proteção contra Prompt Injection e DoS: trechos delimitados em <documentos>, instrução de sistema restritiva e limite de 20 MB por PDF.

Tecnologias Utilizadas

Python 3.12+ Streamlit ChromaDB Sentence Transformers PyTorch (CPU) Google Gemini API Groq API (httpx) PyPDF python-dotenv Pytest

Como Executar Localmente

Clone o repositório do Space, crie um ambiente virtual, instale as dependências e inicie o Streamlit:

git clone https://huggingface.co/spaces/AdryanAzul/DocuMindAI_RAG_Application
cd DocuMindAI_RAG_Application
python -m venv .venv
# Windows (PowerShell): .venv\Scripts\Activate.ps1
# Linux / macOS: source .venv/bin/activate
pip install -r requirements.txt
streamlit run app.py

Para executar a suíte de testes automatizados:

pytest -v