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
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):
- Indexação: os documentos são convertidos em vetores numéricos (embeddings) e armazenados no ChromaDB.
- Recuperação: apenas os trechos mais relevantes para a pergunta são recuperados.
- Geração: os trechos recuperados são enviados à LLM como contexto fechado, reduzindo alucinações.
🏗️ Arquitetura e Fluxo de Dados
[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
PyTorcheSentence 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_HOMEou 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ãogemini-2.5-flash, configurável viaGEMINI_MODEL). - LLM Alternativo / Fallback: Groq API via REST (
httpx, padrãoopenai/gpt-oss-120b, configurável viaGROQ_MODEL).
🔑 Modos de Autenticação (BYOK)
O visitante utiliza suas próprias credenciais diretamente na barra lateral, sem depender de chaves do proprietário:
- Modo Gemini: solicita apenas
GEMINI_API_KEYe utiliza a Google Gemini API. - Modo Groq: solicita apenas
GROQ_API_KEYe utiliza a Groq API. - 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
Bearersã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 viaSPACE_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
Acesse a pasta do projeto:
cd documind-aiCrie e ative um ambiente virtual:
python -m venv .venv # Windows (PowerShell) .venv\Scripts\Activate.ps1 # Linux / macOS source .venv/bin/activateInstale as dependências:
pip install -r requirements.txt(Opcional) Copie
.env.examplepara.envcaso queira definirGEMINI_MODEL,GROQ_MODELouCHROMA_PERSIST_DIR:cp .env.example .envExecute a aplicação:
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:
pytest -v
🚀 Publicação Estática no Hugging Face Spaces
- O repositório utiliza
sdk: staticno 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.pyesrc/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ágina2
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."