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