|
Download README.md from AdryanAzul/DocuMindAI_RAG_Application: direct link, hf CLI and curl.
- Browser
- Download file 6.26 kB
-
https://huggingface.co/spaces/AdryanAzul/DocuMindAI_RAG_Application/resolve/main/README.md
- Command line
-
hf download hf://spaces/AdryanAzul/DocuMindAI_RAG_Application/README.md
-
curl -L -o README.md https://huggingface.co/spaces/AdryanAzul/DocuMindAI_RAG_Application/resolve/main/README.md
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."* | |