README_SPACES.md

metadata

title: RAG Template - Production Ready
emoji: 📚
colorFrom: yellow
colorTo: red
sdk: gradio
sdk_version: 4.36.0
app_file: app.py
pinned: false
license: mit
tags:
  - rag
  - retrieval-augmented-generation
  - pgvector
  - embeddings
  - llm
  - chatbot
  - semantic-search
  - reranking
  - hybrid-search
  - education

RAG Template - Production Ready

Template completo e educativo de Retrieval-Augmented Generation (RAG) com PostgreSQL + pgvector.

O que e RAG?

RAG (Retrieval-Augmented Generation) combina busca semantica com LLMs para gerar respostas baseadas em documentos especificos. E como dar "memoria" e "conhecimento" especializado para uma IA.

Funcionalidades Principais

Ingestao de Documentos

• Upload de PDFs e TXTs
• 4 estrategias de chunking (fixo, sentencas, semantico, recursivo)
• Geracao e cache de embeddings
• Visualizacao do processo completo

Busca Avancada

• Busca semantica com pgvector
• Hybrid search (vetorial + BM25)
• Reranking com cross-encoder
• Query expansion automatica

Chat Interativo

• Suporte a 4 LLM providers (HuggingFace, OpenAI, Anthropic, Ollama)
• Contextos recuperados visiveis
• Metricas em tempo real
• Parametros ajustaveis

Visualizacoes

• Reducao dimensional (PCA, t-SNE, UMAP)
• Clusters de documentos
• Analise de similaridade
• Metricas de qualidade

Monitoramento

• Dashboard de estatisticas
• Historico de queries
• Metricas de performance
• Logging estruturado

Como Usar

1. Configurar Banco de Dados

Este app requer PostgreSQL com pgvector. Opcoes gratuitas:

Supabase (Recomendado):

• Crie conta em supabase.com
• Crie novo projeto
• Habilite extensao vector no SQL Editor
• Copie connection string

Neon:

• Crie conta em neon.tech
• Crie projeto e habilite extensao vector
• Copie connection string

2. Configurar Secrets

Configure os seguintes secrets neste Space:

Obrigatorio:

• DATABASE_URL: Connection string do PostgreSQL

Opcional (pelo menos um):

• HF_TOKEN: Token HuggingFace (para inference API)
• OPENAI_API_KEY: Chave OpenAI
• ANTHROPIC_API_KEY: Chave Anthropic
• OLLAMA_BASE_URL: URL servidor Ollama

3. Aguardar Inicializacao

Na primeira execucao, o app:

1. Conecta ao banco de dados
2. Cria tabelas necessarias
3. Baixa modelos de embedding
4. Inicializa interface

Isso pode levar 1-2 minutos.

4. Ingerir Documentos

1. Va na aba "Ingestao de Documentos"
2. Faca upload de PDFs ou TXTs
3. Escolha estrategia de chunking
4. Aguarde processamento

5. Conversar com Seus Documentos

1. Va na aba "Chat RAG"
2. Selecione LLM provider
3. Ajuste parametros (top_k, temperature)
4. Faca perguntas sobre os documentos

Limitacoes do Free Tier

Supabase Free

• 500MB storage (~300k documentos pequenos)
• Pausa apos 1 semana de inatividade
• 2GB bandwidth/mes

Neon Free

• 10GB storage (~6M documentos pequenos)
• 100 compute hours/mes
• Pausa apos 5min de inatividade

Hugging Face Spaces

• 16GB RAM
• 2 vCPU
• Ideal para demonstracao, nao producao em escala

Recomendacao: Limite a ~1000 documentos para demo estavel.

Tecnologias

• Gradio: Interface interativa
• PostgreSQL + pgvector: Armazenamento vetorial
• Sentence Transformers: Embeddings
• Multiple LLMs: HuggingFace, OpenAI, Anthropic, Ollama
• BM25: Busca lexica
• Plotly: Visualizacoes

Arquitetura

Usuario
  |
  v
Gradio UI
  |
  v
RAG Pipeline
  |
  +-- Chunking
  +-- Embeddings
  +-- Retrieval (Hybrid + Rerank)
  +-- Generation (LLM)
  |
  v
PostgreSQL + pgvector

Deploy Proprio

Local

git clone https://github.com/guifav/rag_template
cd rag_template
pip install -r requirements.txt
cp .env.example .env
# Configure .env
python app.py

Docker

docker compose up

Railway

railway up

Documentacao Completa

• README completo
• Setup Supabase
• Setup Neon
• Comparacao de Bancos

Performance

Metricas tipicas (depende do hardware):

• Ingestao: ~5-10 docs/segundo
• Busca vetorial: 50-150ms
• Geracao: 2-5 segundos
• Embeddings: ~100ms por documento

Casos de Uso

• Chatbots especializados
• Sistemas de busca semantica
• Analise de documentos
• QA sobre base de conhecimento
• Pesquisa academica
• Documentacao tecnica interativa

Roadmap

• Suporte a mais formatos (DOCX, HTML)
• Multi-tenancy
• API REST
• Autenticacao de usuarios
• Suporte a imagens (vision models)
• Grafos de conhecimento

Contribuir

Contribuicoes sao bem-vindas!

1. Fork o repositorio
2. Crie uma branch
3. Commit suas mudancas
4. Abra um Pull Request

Veja CONTRIBUTING.md

Licenca

MIT License - veja LICENSE

Contato

• GitHub: @guifav
• Issues: github.com/guifav/rag_template/issues

Agradecimentos

Construido com:

• PostgreSQL + pgvector
• Sentence Transformers
• Hugging Face
• Gradio
• Supabase / Neon

---

Feito com muito cafe para a comunidade de IA