Spaces:

guifav
/

rag_template

Sleeping

App Files Files Community

rag_template / README.md

Guilherme Favaron

Fix: Add missing emoji to README metadata for HF Space validation

d7ebb1a 25 days ago

preview code

raw

history blame contribute delete

16.2 kB

A newer version of the Gradio SDK is available: 6.6.0

Upgrade

metadata

title: RAG Template
emoji: 📚
colorFrom: yellow
colorTo: red
sdk: gradio
sdk_version: 4.36.0
app_file: app.py
pinned: false
license: mit

RAG Template Educativo

Template interativo de Retrieval-Augmented Generation com PostgreSQL + pgvector

Uma aplicação educativa completa que demonstra cada etapa do processo RAG de forma visual e interativa.

Funcionalidades

Ingestão de Documentos

Upload de arquivos PDF e TXT
Visualização do texto extraído
4 estratégias de chunking (tamanho fixo, por sentenças, semântico, recursivo)
Preview de embeddings gerados
Estatísticas detalhadas do processo
Cache automático de embeddings para performance

Exploração da Base de Conhecimento

Busca semântica interativa
Visualização de scores de similaridade
Listagem de todos os documentos armazenados
Análise de relevância dos resultados

Chat RAG Interativo

Interface de chat com IA
Suporte a 4 LLM providers (HuggingFace, OpenAI, Anthropic, Ollama)
Painel lateral mostrando contextos recuperados
Visualização do prompt construído
Métricas de performance em tempo real
Controles de parâmetros (top_k, temperature, max_tokens)

Playground de Parâmetros

Comparação lado a lado de configurações
Experimente com diferentes top_k, temperature, max_tokens
Análise comparativa de resultados
Entenda o impacto de cada parâmetro

Comparação de Chunking (NOVO)

Teste 4 estratégias de chunking no mesmo texto
Visualização lado a lado dos resultados
Estatísticas comparativas detalhadas
Entenda o impacto de cada abordagem

Monitoramento e Métricas

Dashboard de estatísticas gerais
Métricas de performance (latências)
Histórico de queries
Análise de uso do sistema
Logging estruturado em JSON

Sistema de Filtros e Metadados (NOVO)

Metadados extensiveis em JSONB
8 tipos de filtros (tipo, tags, autor, departamento, security_level, datas)
Busca vetorial combinada com filtros SQL
Performance otimizada com indices GIN
Controle de acesso por nivel de seguranca
Multi-tenancy basico

Avaliacao de Qualidade RAG (NOVO)

Framework RAGAS com 4 metricas principais
Faithfulness, Answer Relevancy, Context Precision, Context Recall
Fallback para metricas simplificadas (sem RAGAS)
Sistema de benchmarking automatizado
Relatorios HTML com visualizacoes
Comparacao de multiplas configuracoes

Arquitetura

┌─────────────────────────────────────────────────────────────┐
│                    Interface Gradio                          │
│  (Ingestão | Exploração | Chat | Playground | Métricas)    │
└────────────────────┬────────────────────────────────────────┘
                     │
          ┌──────────┴───────────┐
          │   App Controller     │
          └──────────┬───────────┘
                     │
      ┌──────────────┼──────────────┐
      │              │              │
┌─────▼─────┐  ┌────▼────┐  ┌─────▼──────┐
│ Embedding │  │  RAG    │  │ Generation │
│  Manager  │  │ Pipeline│  │  Manager   │
└─────┬─────┘  └────┬────┘  └─────┬──────┘
      │             │              │
      └─────────────┼──────────────┘
                    │
         ┌──────────▼───────────┐
         │  Database Manager    │
         │  (PostgreSQL +       │
         │   pgvector)          │
         └──────────────────────┘

Início Rápido

Pré-requisitos

Python 3.10+
PostgreSQL com extensão pgvector
Token da Hugging Face (para geração de texto)

Opção 1: Docker Compose (Recomendado para desenvolvimento)

# Clone o repositório
git clone https://github.com/guifav/rag_template.git
cd rag_template

# Inicie o PostgreSQL com pgvector
docker compose up -d

# Crie ambiente virtual e instale dependências
python -m venv .venv
source .venv/bin/activate  # No Windows: .venv\Scripts\activate
pip install -r requirements.txt

# Configure variáveis de ambiente
cp .env.example .env
# Edite .env e adicione seu HF_TOKEN

# Execute a aplicação
python app.py

Acesse: http://localhost:7860

Opção 2: Supabase (Recomendado para produção)

Crie uma conta no Supabase
Crie um novo projeto
Habilite a extensão vector em Database > Extensions
Copie a string de conexão em Project Settings > Database
Configure no .env:

DATABASE_URL=postgresql://postgres:[PASSWORD]@db.[PROJECT_REF].supabase.co:5432/postgres
HF_TOKEN=seu_token_aqui

Execute o app:

python app.py

Guia completo de setup Supabase

Estrutura do Projeto

rag_template/
├── app.py                      # Aplicação principal
├── requirements.txt            # Dependências Python
├── docker-compose.yml          # PostgreSQL local
├── .env.example                # Template de configuração
│
├── src/                        # Módulos principais
│   ├── config.py              # Configurações centralizadas
│   ├── database.py            # Gerenciamento do banco
│   ├── embeddings.py          # Geração de embeddings
│   ├── chunking.py            # Estratégias de chunking
│   ├── document_processing.py # Extração de texto
│   └── generation.py          # Geração de respostas
│
├── ui/                         # Componentes da interface
│   ├── ingestion_tab.py       # Aba de ingestão
│   ├── exploration_tab.py     # Aba de exploração
│   ├── chat_tab.py            # Aba de chat
│   ├── playground_tab.py      # Aba de playground
│   └── monitoring_tab.py      # Aba de monitoramento
│
├── docs/                       # Documentação
│   └── SUPABASE_SETUP.md      # Guia de setup Supabase
│
├── db/init/                    # Scripts de inicialização
│   ├── 01_init.sql            # Extensão pgvector
│   └── 02_indexes.sql         # Índices otimizados
│
└── tests/                      # Testes automatizados
    ├── test_units.py
    └── test_integration_db.py

Configuração

Variáveis de Ambiente

# Banco de Dados
DATABASE_URL=postgresql://postgres:postgres@localhost:5433/ragdb

# Hugging Face
HF_TOKEN=seu_token_aqui
HF_MODEL_ID=HuggingFaceH4/zephyr-7b-beta

# Embeddings
EMBEDDING_MODEL_ID=sentence-transformers/all-MiniLM-L6-v2
EMBEDDING_DIM=384

# Retrieval
TOP_K=4
IVFFLAT_LISTS=100

# Chunking
CHUNK_SIZE=1000
CHUNK_OVERLAP=200

# Geração
TEMPERATURE=0.3
MAX_TOKENS=512

# App
PORT=7860

Modelos Alternativos

LLMs:

mistralai/Mistral-7B-Instruct-v0.2
meta-llama/Llama-2-7b-chat-hf
google/flan-t5-large

Embeddings:

sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 (multilíngue)
sentence-transformers/all-mpnet-base-v2 (melhor qualidade, 768d)
BAAI/bge-small-en-v1.5 (eficiente)

Como Usar

1. Ingerir Documentos

Vá na aba ** Ingestão de Documentos**
Faça upload de arquivos PDF ou TXT
Escolha a estratégia de chunking
Ajuste o tamanho dos chunks
Clique em Iniciar Ingestão
Acompanhe cada etapa do processo

2. Explorar a Base

Vá na aba ** Exploração da Base**
Visualize estatísticas do banco
Digite uma query de busca
Veja os resultados ranqueados por similaridade
Analise os scores de relevância

3. Conversar com RAG

Vá na aba ** Chat RAG**
Ajuste os parâmetros (top_k, temperature, max_tokens)
Digite sua pergunta
Veja os contextos recuperados no painel lateral
Analise o prompt construído
Receba resposta com fontes

4. Experimentar Parâmetros

Vá na aba ** Playground de Parâmetros**
Configure duas configurações diferentes
Execute ambas com a mesma query
Compare os resultados lado a lado
Entenda o impacto de cada parâmetro

5. Monitorar Uso

Vá na aba ** Monitoramento**
Veja estatísticas gerais do sistema
Analise métricas de performance
Visualize histórico de queries

Desenvolvimento

Instalação para Desenvolvimento

# Clone e entre no diretório
git clone https://github.com/guifav/rag_template.git
cd rag_template

# Ambiente virtual
python -m venv .venv
source .venv/bin/activate

# Dependências
pip install -r requirements.txt

# Iniciar banco local
docker compose up -d

# Configurar .env
cp .env.example .env
# Edite .env com suas credenciais

# Executar testes
pytest tests/

# Executar app
python app.py

Adicionar Nova Funcionalidade

Crie um módulo em src/ se necessário
Crie uma aba em ui/ se for componente de UI
Integre no app.py
Adicione testes em tests/
Atualize documentação

Deploy

O projeto oferece múltiplas opções de deploy documentadas:

Hugging Face Spaces (Recomendado para Demo)

Deploy com um clique
Free tier com 16GB RAM
Documentação completa em README_SPACES.md
Guia de secrets: docs/SPACES_SECRETS.md

Railway (Full-Stack Deployment)

App + PostgreSQL juntos
CI/CD integrado com GitHub
Guia completo: docs/RAILWAY_SETUP.md

Docker (Produção Local)

Stack completa com docker-compose
Multi-stage build otimizado
Guia: DEPLOY.md

VPS/Cloud (AWS, DigitalOcean, etc)

Controle total
Setup com Docker
Guia: DEPLOY.md

Veja o Guia Completo de Deploy para instruções detalhadas.

Performance e Escalabilidade

Otimizações Implementadas

DONE Índice IVFFLAT para busca vetorial eficiente
DONE Connection pooling (Supabase)
DONE Lazy loading de modelos
DONE Embeddings normalizados (cosine similarity)
DONE Batch processing na ingestão

Limites Recomendados

Documentos: Até 100k chunks no free tier Supabase (500MB)
Chunk size: 500-1500 caracteres (depende do domínio)
Top K: 3-10 para maioria dos casos
Embedding model: 384d para velocidade, 768d para qualidade

Contribuindo

Contribuições são bem-vindas! Este projeto aceita contribuições via Pull Requests.

Como Contribuir

Fork o projeto
Crie uma branch (git checkout -b feature/MinhaFeature)
Commit suas mudanças (git commit -m 'Add: MinhaFeature')
Push para a branch (git push origin feature/MinhaFeature)
Abra um Pull Request

Guias

Leia o CONTRIBUTING.md para detalhes sobre setup de desenvolvimento
Use os issue templates para reportar bugs ou sugerir features
Siga o estilo de código (black + ruff)
Adicione testes para novas funcionalidades

Reportando Bugs

Use o Bug Report template e inclua:

Descrição clara do problema
Passos para reproduzir
Ambiente (OS, Python version, etc)
Logs relevantes

Roadmap

Completo (Janeiro 2026)

Fase 1: Interface Educativa (8 abas interativas)
Fase 2: Melhorias Tecnicas (Multi-LLM, Chunking Avancado, Cache, Logging)
Fase 3: RAG Avancado (Reranking, Hybrid Search, Visualizacoes, Query Expansion)
Fase 4: Deploy e Distribuicao (HF Spaces, CI/CD, Docker, Railway, Neon)
Fase 5: Recursos Educativos (Tutoriais, FAQ, Notebooks, Diagramas)
Fase 6: Funcionalidades Avancadas e Producao - 100% COMPLETO
- Sistema de filtros e metadados (Completo)
- Avaliacao automatica com RAGAS (Completo)
- API REST + SDK Python (Completo)
- Observabilidade (Prometheus, OpenTelemetry) (Completo)
- Melhorias de UX (dark mode, shortcuts, export) (Completo)
- Testes abrangentes (>85% cobertura) (Completo)

Versao Atual: 2.0.0 - Production-Ready Enterprise System

O RAG Template agora e um sistema completo production-ready enterprise com:

API REST completa para integracao
Python SDK para desenvolvimento rapido
Monitoring com Prometheus e OpenTelemetry
Testes abrangentes (>85% cobertura)
UX moderna com dark mode e shortcuts
Sistema de export completo
Documentacao completa (3000+ linhas)

Veja o ROADMAP completo, Plano da Fase 6 e Resumo Final da Fase 6 para detalhes.

Problemas Conhecidos

Conexão Supabase pode demorar alguns segundos no cold start
Modelos grandes de embedding podem consumir muita RAM
Algumas queries podem ter latência alta (>5s) dependendo do modelo LLM

Reporte bugs em: https://github.com/guifav/rag_template/issues

Recursos Adicionais

Tutoriais e Aprendizado

Tutorial: Getting Started - Primeiros passos (15-20min)
FAQ - 40+ perguntas frequentes
Use Case: Technical Docs Chatbot - Caso pratico
Notebooks Jupyter - Aprendizado interativo hands-on
- 01_rag_basics.ipynb - Fundamentos de RAG
- 02_advanced_rag.ipynb - Tecnicas avancadas
Diagramas Arquiteturais - 7 diagramas mermaid

Documentação do Projeto

CONTRIBUTING.md - Guia de contribuição
CHANGELOG.md - Histórico de versões
ROADMAP.md - Planejamento futuro
DEPLOY.md - Guia completo de deploy
PROJECT_STATUS.md - Status completo do projeto
PHASE_6_PLAN.md - Plano detalhado da Fase 6
FASE_6_RESUMO_FINAL.md - Resumo da implementacao Fase 6
METADATA_GUIDE.md - Guia completo de metadados e filtros

Guias de Database

Documentação Externa

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

Créditos

Desenvolvido com:

Dúvidas?

📖 Leia a documentação completa
Abra uma issue
🌟 Dê uma estrela se este projeto foi útil!

Feito com para a comunidade de IA