Skip to content
muhleggerPublic

About

Projeto de estudo em RAG: perguntas sobre PDFs locais, com fontes, contas isoladas e recusa sem contexto. FastAPI, React, Chroma e Ollama.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

34 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

ChatRAG · perguntas sobre PDFs locais

Aplicação de estudo para enviar PDFs e consultar seu conteúdo em português. Combina FastAPI, React, Chroma e Ollama, com contas locais, indexação por usuário e indicação dos documentos usados como contexto.

O projeto começou em outubro de 2025 como uma exploração prática de Retrieval-Augmented Generation. Em setembro de 2026, recebeu uma revisão focada em isolamento de dados, upload, rastreabilidade das fontes, testes e reprodução do ambiente. O histórico de desenvolvimento foi preservado.

Interface do ChatRAG com o PDF de exemplo indexado e uma pergunta sem resposta no documento

A captura mostra a recusa de uma pergunta sem evidência suficiente no PDF de demonstração. As fontes exibidas em outras respostas identificam o contexto fornecido ao modelo; não constituem validação automática de cada afirmação.

O que está implementado

  • Cadastro e login com senha armazenada como hash, JWT com expiração e contas em SQLite.
  • Armazenamento vetorial separado por identificador derivado do e-mail completo.
  • Upload de PDFs de até 20 MiB, com validação de nome/cabeçalho, gravação em blocos e nomes temporários aleatórios.
  • Extração de texto, divisão em trechos e indexação em segundo plano. O frontend acompanha o estado do processamento.
  • Recuperação semântica com embeddings multilíngues, deduplicação, seleção de contexto e reranking opcional.
  • Recusa antes da geração quando a recuperação não fornece contexto suficiente.
  • Cache de respostas por usuário e versão do índice, métricas por etapa e avaliação lexical de perguntas de exemplo.

Fluxo

flowchart LR
    UI[React] --> API[FastAPI + autenticação]
    API --> Accounts[(SQLite: contas)]
    API --> PDF[PDF: extração e divisão]
    PDF --> Vectors[(Chroma por usuário)]
    API --> Search[Recuperação e seleção de contexto]
    Vectors --> Search
    Search --> Gate{Contexto suficiente?}
    Gate -->|Não| Refuse[Resposta de recusa]
    Gate -->|Sim| LLM[Ollama local]
    LLM --> Answer[Resposta + fontes do contexto]
Loading

Os PDFs temporários são removidos após a tentativa de indexação. O texto extraído permanece na base vetorial local. Os modelos são carregados sob demanda; importar o backend ou executar os testes básicos não baixa modelos.

Executar localmente

Ambiente de referência: Linux/WSL, Python 3.12, Node.js 22.12+ e uv. Os arquivos de dependências do backend foram resolvidos para esse ambiente, com PyTorch em CPU. Windows nativo e outras versões de Python não foram validados nesta revisão.

1. Backend

Na raiz do repositório:

python3 backend/setup_dev.py
uv venv backend/.venv --python 3.12
uv pip install --python backend/.venv/bin/python -r backend/requirements.txt --torch-backend cpu

setup_dev.py cria backend/.env com uma chave aleatória e preserva arquivos existentes. O backend rejeita chaves com menos de 32 caracteres.

Instale o Ollama e prepare o modelo de geração:

ollama pull llama3.2:1b
# Em outro terminal, se o serviço ainda não estiver ativo:
ollama serve

Inicie a API:

backend/.venv/bin/uvicorn main:app --app-dir backend --host 127.0.0.1 --port 8000

O primeiro upload baixa o modelo de embeddings configurado e pode demorar mais. O modelo padrão é sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2; as operações sobre o texto acontecem localmente.

2. Frontend

Em outro terminal, na raiz:

npm --prefix frontend ci
npm --prefix frontend run dev

Abra http://localhost:5173. A documentação interativa da API fica em http://127.0.0.1:8000/docs.

3. Experimentar

  1. Cadastre uma conta.
  2. Envie docs/exemplo.pdf, um guia fictício de um clube de leitura.
  3. Aguarde o status finalizado.
  4. Pergunte “Em que dia e horário o clube se reúne?” ou “Até quantos livros posso levar para troca?”.
  5. Experimente “Qual é o telefone da biblioteca?”, uma informação ausente no documento.

O texto original do PDF está em docs/exemplo.txt. A qualidade e a latência das respostas dependem do modelo de geração, do equipamento e dos documentos enviados.

Configuração

Edite backend/.env. Os valores principais são:

Variável Padrão / finalidade
SECRET_KEY Gerada por setup_dev.py; assina os tokens de acesso
OLLAMA_MODEL llama3.2:1b
OLLAMA_BASE_URL http://127.0.0.1:11434
EMBEDDING_MODEL sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
FRONTEND_ORIGINS http://localhost:5173
MAX_UPLOAD_BYTES 20971520 (20 MiB)
RAG_SCORE_FLOOR / RAG_SCORE_THRESHOLD 0.35; limiares heurísticos, não probabilidades de acerto
RAG_RERANK_MODEL Vazio: reranker desativado
USERS_DB_PATH backend/local/users.sqlite3
UPLOAD_DIRECTORY / CHROMA_DB_DIRECTORY backend/local/uploads / backend/local/vectors

O diretório backend/local/ e os arquivos .env ficam fora do versionamento. Se trocar a porta da API, crie frontend/.env.local com VITE_API_URL=http://127.0.0.1:NOVA_PORTA. Ao trocar o modelo de embeddings, use uma base vetorial nova e indexe os PDFs novamente.

Instalações antigas: a revisão substituiu users.json por SQLite e mudou os identificadores das bases. Cadastre as contas novamente e reenvie os PDFs. As bases antigas não são importadas automaticamente, pois os identificadores anteriores podiam representar mais de um e-mail.

Verificação

Testes rápidos, sem Ollama, modelos de embeddings ou banco externo:

uv pip install --python backend/.venv/bin/python -r backend/requirements-test.txt
backend/.venv/bin/python -m pytest backend
backend/.venv/bin/python backend/_localrag_smoke.py
backend/.venv/bin/python backend/_evaluation_smoke.py
npm --prefix frontend run build

A suíte cobre autenticação, cadastro concorrente, separação de contas e caches, upload, atendimento concorrente, recusa de contexto fraco e correspondência entre fontes e contexto. Com as dependências completas instaladas, também executa a integração de PDF + Chroma, incluindo reenvio idempotente; esse teste usa embeddings determinísticos. O CI executa os testes leves e o build TypeScript/Vite.

Para executar a avaliação com o modelo real, use uma conta que já tenha indexado o PDF de exemplo:

backend/.venv/bin/python backend/run_evaluation.py \
  --user seu_email@exemplo.com \
  --dataset backend/eval_samples/sample_questions.json \
  --output backend/local/avaliacao.json

Essa avaliação mede presença de termos e existência de fontes. Ela não mede factualidade, precisão das citações nem qualidade geral do RAG. O conjunto pequeno é uma demonstração reproduzível, não um benchmark representativo. A exportação inclui perguntas, respostas e metadados das fontes para inspeção manual.

Decisões e limites

  • Execução local: permite explorar recuperação e geração sem enviar os PDFs a uma API de LLM. Exige recursos para executar os modelos.
  • SQLite e um processo de API: simplificam o ambiente de estudo. Caches e estados dos jobs ficam em memória; não há coordenação entre múltiplos workers nem retomada de jobs após reinício.
  • Rastreabilidade: as fontes correspondem aos trechos enviados ao modelo. Uma resposta ainda pode interpretar mal esses trechos ou conter informações incorretas.
  • Recuperação: os scores absolutos são preservados. Os limiares precisam ser avaliados com o corpus escolhido; a revisão verificou a recuperação no pequeno documento de exemplo, sem estabelecer uma calibração universal.
  • Escopo da interface: o histórico visual não é enviado ao modelo e se perde ao recarregar a página. Não há listagem/exclusão de documentos, OCR, streaming ou recuperação de senha.
  • Disponibilização: o projeto continua sendo um protótipo local. Rate limiting, quotas, gestão de contas e operação em produção permanecem fora do escopo desta revisão.

A revisão validou extração, embeddings, Chroma, recusa por falta de contexto e testes com geração simulada. Não inclui uma avaliação de qualidade com o modelo Ollama real.

Estrutura

backend/
  main.py                 API e pipeline RAG
  auth_store.py           Contas em SQLite
  evaluation.py           Avaliação lexical
  tests/                  Testes de regressão e integração local
  requirements*.in/.txt   Dependências declaradas e versões resolvidas
frontend/src/             Interface React/TypeScript
docs/                     PDF fictício, texto e captura da interface
.github/workflows/        Testes e build

About

Projeto de estudo em RAG: perguntas sobre PDFs locais, com fontes, contas isoladas e recusa sem contexto. FastAPI, React, Chroma e Ollama.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages