AdryanAzul's picture
docs: configure static Space landing page (sdk: static) with full source code
b6eb13c verified
|
Raw History Blame Contribute Delete
6.26 kB
---
title: DocuMind AI
emoji: 📄
colorFrom: blue
colorTo: indigo
sdk: static
pinned: false
---
# 📄 DocuMind AI
Aplicação de **RAG (Retrieval-Augmented Generation)** com **embeddings locais** e arquitetura **BYOK (Bring Your Own Key)**, permitindo o envio de documentos PDF e perguntas em linguagem natural com respostas fundamentadas exclusivamente nos arquivos enviados e citação de fontes.
---
## 🧠 O que é RAG?
**Retrieval-Augmented Generation (Geração Aumentada por Recuperação)** combina **busca semântica em uma base vetorial** com **Modelos de Linguagem (LLMs)**:
1. **Indexação:** os documentos são convertidos em vetores numéricos (*embeddings*) e armazenados no ChromaDB.
2. **Recuperação:** apenas os trechos mais relevantes para a pergunta são recuperados.
3. **Geração:** os trechos recuperados são enviados à LLM como contexto fechado, reduzindo alucinações.
---
## 🏗️ Arquitetura e Fluxo de Dados
```text
[PDFs] ─▶ 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)
```
### Embeddings Locais (`sentence-transformers/all-MiniLM-L6-v2`)
- Os vetores são gerados **100% localmente na CPU** via `PyTorch` e `Sentence Transformers` (**nenhuma API Key é exigida para embeddings**).
- O mesmo modelo (`all-MiniLM-L6-v2`, 384 dimensões) é usado na indexação e nas consultas, garantindo compatibilidade dimensional.
- Em `app.py`, o modelo é carregado **uma única vez por processo** com `@st.cache_resource`. Os pesos (~90 MB) são baixados apenas na primeira inicialização e reaproveitados do cache local (`SENTENCE_TRANSFORMERS_HOME` ou cache padrão do Hugging Face).
### Modelos e APIs Utilizados
- **Embeddings:** `sentence-transformers/all-MiniLM-L6-v2` (local, sem chave).
- **LLM Primário:** Google Gemini API (`google-genai`, padrão `gemini-2.5-flash`, configurável via `GEMINI_MODEL`).
- **LLM Alternativo / Fallback:** Groq API via REST (`httpx`, padrão `openai/gpt-oss-120b`, configurável via `GROQ_MODEL`).
---
## 🔑 Modos de Autenticação (BYOK)
O visitante utiliza suas próprias credenciais diretamente na barra lateral, **sem depender de chaves do proprietário**:
1. **Modo Gemini:** solicita apenas `GEMINI_API_KEY` e utiliza a Google Gemini API.
2. **Modo Groq:** solicita apenas `GROQ_API_KEY` e utiliza a Groq API.
3. **Modo Gemini + fallback Groq:** solicita ambas as chaves; o Gemini atua como provedor primário e a Groq é acionada automaticamente em **falhas temporárias elegíveis** (`429`, `5xx`, *timeout* ou erro de rede), exibindo aviso visual na resposta quando o fallback ocorre.
---
## 🔒 Privacidade, Segurança e Isolamento
- **Credenciais em memória:** as chaves digitadas permanecem apenas na memória da sessão (`st.session_state`), nunca são gravadas em disco, no ChromaDB, em logs ou no histórico de chat, e podem ser removidas a qualquer momento pelo botão **Limpar credenciais**.
- **Sanitização de erros:** possíveis trechos de chaves ou headers `Bearer` são mascarados antes de qualquer exibição.
- **Isolamento multiusuário:** cada sessão recebe um identificador criptográfico (`secrets.token_urlsafe`) e sua própria coleção no ChromaDB (com diretório temporário dedicado quando executado no Hugging Face Spaces via `SPACE_ID`), evitando contenção de escrita e vazamento de documentos entre visitantes.
- **Proteção contra Prompt Injection:** os trechos recuperados são isolados entre tags `<documentos>...</documentos>` e o modelo é instruído a ignorar comandos embutidos nos PDFs.
---
## 📦 Instalação e Execução Local
1. Acesse a pasta do projeto:
```bash
cd documind-ai
```
2. Crie e ative um ambiente virtual:
```bash
python -m venv .venv
# Windows (PowerShell)
.venv\Scripts\Activate.ps1
# Linux / macOS
source .venv/bin/activate
```
3. Instale as dependências:
```bash
pip install -r requirements.txt
```
4. *(Opcional)* Copie `.env.example` para `.env` caso queira definir `GEMINI_MODEL`, `GROQ_MODEL` ou `CHROMA_PERSIST_DIR`:
```bash
cp .env.example .env
```
5. Execute a aplicação:
```bash
streamlit run app.py
```
---
## 🧪 Como Executar os Testes
A suíte utiliza `pytest` com *mocks* para os provedores externos e embeddings locais, validando carregamento de PDFs, chunking, modos BYOK, fallback, isolamento entre sessões, concorrência e sanitização de logs:
```bash
pytest -v
```
---
## 🚀 Publicação Estática no Hugging Face Spaces
- O repositório utiliza **`sdk: static`** no cabeçalho YAML para servir a página de apresentação (`index.html`) junto com todo o código-fonte em Python.
- **Aviso:** a demonstração interativa em Streamlit (`app.py`) **não** é executada no Space estático; para usar a interface interativa, siga as instruções de **Instalação e Execução Local** acima.
- **Arquitetura preparada para nuvem:** o código em `app.py` e `src/` já contempla isolamento por sessão (`SPACE_ID`), arquitetura BYOK em memória e limite de **20 MB por arquivo PDF**.
---
## 💬 Exemplos de Perguntas e Respostas
Supondo o envio de um PDF com o **Manual de Estágio** ou **Documentação Técnica**:
- **Pergunta:** *"Quais são os requisitos obrigatórios para o estágio?"*
- **Resposta:** *"De acordo com o documento enviado, é necessário estar regularmente matriculado, possuir conhecimentos em Python e disponibilidade de 30 horas semanais."*
- **Fontes consultadas:** `manual_estagio.pdf` — Página `2`
- **Pergunta:** *"Qual é a previsão do tempo para amanhã?"* *(informação ausente nos PDFs)*
- **Resposta:** *"Não encontrei informações suficientes nos documentos enviados para responder a essa pergunta."*