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
metadata
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

[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:

    cd documind-ai
    
  2. Crie e ative um ambiente virtual:

    python -m venv .venv
    # Windows (PowerShell)
    .venv\Scripts\Activate.ps1
    # Linux / macOS
    source .venv/bin/activate
    
  3. Instale as dependências:

    pip install -r requirements.txt
    
  4. (Opcional) Copie .env.example para .env caso queira definir GEMINI_MODEL, GROQ_MODEL ou CHROMA_PERSIST_DIR:

    cp .env.example .env
    
  5. Execute 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: 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."