Hugging Face's logo

Spaces:
guifav
/
rag_template
Sleeping

App Files Community
rag_template / README.md
Guilherme Favaron
Fix: Add missing emoji to README metadata for HF Space validation
d7ebb1a
preview code
|
raw
history blame contribute delete
16.2 kB
 ---
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.
[![CI](https://github.com/guifav/rag_template/workflows/CI/badge.svg)](https://github.com/guifav/rag_template/actions)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-pgvector-336791.svg)](https://github.com/pgvector/pgvector)
[![Gradio](https://img.shields.io/badge/Gradio-UI-orange.svg)](https://gradio.app/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
---
## 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)
```bash
# 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)
1. Crie uma conta no [Supabase](https://supabase.com)
2. Crie um novo projeto
3. Habilite a extensão `vector` em Database > Extensions
4. Copie a string de conexão em Project Settings > Database
5. Configure no `.env`:
```bash
DATABASE_URL=postgresql://postgres:[PASSWORD]@db.[PROJECT_REF].supabase.co:5432/postgres
HF_TOKEN=seu_token_aqui
```
6. Execute o app:
```bash
python app.py
```
[Guia completo de setup Supabase](docs/SUPABASE_SETUP.md)
---
## 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
```bash
# 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
1. Vá na aba ** Ingestão de Documentos**
2. Faça upload de arquivos PDF ou TXT
3. Escolha a estratégia de chunking
4. Ajuste o tamanho dos chunks
5. Clique em **Iniciar Ingestão**
6. Acompanhe cada etapa do processo
### 2. Explorar a Base
1. Vá na aba ** Exploração da Base**
2. Visualize estatísticas do banco
3. Digite uma query de busca
4. Veja os resultados ranqueados por similaridade
5. Analise os scores de relevância
### 3. Conversar com RAG
1. Vá na aba ** Chat RAG**
2. Ajuste os parâmetros (top_k, temperature, max_tokens)
3. Digite sua pergunta
4. Veja os contextos recuperados no painel lateral
5. Analise o prompt construído
6. Receba resposta com fontes
### 4. Experimentar Parâmetros
1. Vá na aba ** Playground de Parâmetros**
2. Configure duas configurações diferentes
3. Execute ambas com a mesma query
4. Compare os resultados lado a lado
5. Entenda o impacto de cada parâmetro
### 5. Monitorar Uso
1. Vá na aba ** Monitoramento**
2. Veja estatísticas gerais do sistema
3. Analise métricas de performance
4. Visualize histórico de queries
---
## Desenvolvimento
### Instalação para Desenvolvimento
```bash
# 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
1. Crie um módulo em `src/` se necessário
2. Crie uma aba em `ui/` se for componente de UI
3. Integre no `app.py`
4. Adicione testes em `tests/`
5. 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](README_SPACES.md)
- Guia de secrets: [docs/SPACES_SECRETS.md](docs/SPACES_SECRETS.md)
### Railway (Full-Stack Deployment)
- App + PostgreSQL juntos
- CI/CD integrado com GitHub
- Guia completo: [docs/RAILWAY_SETUP.md](docs/RAILWAY_SETUP.md)
### Docker (Produção Local)
- Stack completa com docker-compose
- Multi-stage build otimizado
- Guia: [DEPLOY.md](DEPLOY.md#3-docker-localproducao)
### VPS/Cloud (AWS, DigitalOcean, etc)
- Controle total
- Setup com Docker
- Guia: [DEPLOY.md](DEPLOY.md#4-vpscloud-digitalocean-aws-etc)
Veja o [Guia Completo de Deploy](DEPLOY.md) 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
1. Fork o projeto
2. Crie uma branch (`git checkout -b feature/MinhaFeature`)
3. Commit suas mudanças (`git commit -m 'Add: MinhaFeature'`)
4. Push para a branch (`git push origin feature/MinhaFeature`)
5. Abra um Pull Request
### Guias
- Leia o [CONTRIBUTING.md](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](.github/ISSUE_TEMPLATE/bug_report.md) 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](docs/ROADMAP.md), [Plano da Fase 6](docs/PHASE_6_PLAN.md) e [Resumo Final da Fase 6](docs/FASE_6_RESUMO_FINAL.md) 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](docs/tutorials/01_getting_started.md) - Primeiros passos (15-20min)
- [FAQ](docs/FAQ.md) - 40+ perguntas frequentes
- [Use Case: Technical Docs Chatbot](docs/tutorials/use_cases/technical_docs_chatbot.md) - Caso pratico
- [Notebooks Jupyter](notebooks/) - Aprendizado interativo hands-on
- [01_rag_basics.ipynb](notebooks/01_rag_basics.ipynb) - Fundamentos de RAG
- [02_advanced_rag.ipynb](notebooks/02_advanced_rag.ipynb) - Tecnicas avancadas
- [Diagramas Arquiteturais](docs/diagrams/rag_flow.md) - 7 diagramas mermaid
### Documentação do Projeto
- [CONTRIBUTING.md](CONTRIBUTING.md) - Guia de contribuição
- [CHANGELOG.md](CHANGELOG.md) - Histórico de versões
- [ROADMAP.md](docs/ROADMAP.md) - Planejamento futuro
- [DEPLOY.md](DEPLOY.md) - Guia completo de deploy
- [PROJECT_STATUS.md](docs/PROJECT_STATUS.md) - Status completo do projeto
- [PHASE_6_PLAN.md](docs/PHASE_6_PLAN.md) - Plano detalhado da Fase 6
- [FASE_6_RESUMO_FINAL.md](docs/FASE_6_RESUMO_FINAL.md) - Resumo da implementacao Fase 6
- [METADATA_GUIDE.md](docs/METADATA_GUIDE.md) - Guia completo de metadados e filtros
### Guias de Database
- [Supabase Setup](docs/SUPABASE_SETUP.md)
- [Neon Setup](docs/NEON_SETUP.md)
- [Railway Setup](docs/RAILWAY_SETUP.md)
- [Comparação de Providers](docs/DATABASE_COMPARISON.md)
### Documentação Externa
- [Documentação pgvector](https://github.com/pgvector/pgvector)
- [Sentence Transformers](https://www.sbert.net/)
- [Hugging Face Inference API](https://huggingface.co/docs/api-inference/index)
- [Gradio Docs](https://www.gradio.app/docs/)
---
## 📄 Licença
Este projeto está sob a licença MIT. Veja o arquivo [LICENSE](LICENSE) para mais detalhes.
---
## Créditos
Desenvolvido com:
- [PostgreSQL](https://www.postgresql.org/) + [pgvector](https://github.com/pgvector/pgvector)
- [Sentence Transformers](https://www.sbert.net/)
- [Hugging Face](https://huggingface.co/)
- [Gradio](https://gradio.app/)
- [Supabase](https://supabase.com/)
---
## Dúvidas?
- 📖 Leia a [documentação completa](docs/)
- Abra uma [issue](https://github.com/guifav/rag_template/issues)
- 🌟 Dê uma estrela se este projeto foi útil!
---
**Feito com para a comunidade de IA**