README_SPACES.md

---
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](https://supabase.com)
- Crie novo projeto
- Habilite extensao `vector` no SQL Editor
- Copie connection string

**Neon**:
- Crie conta em [neon.tech](https://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

```bash
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

```bash
docker compose up
```

### Railway

```bash
railway up
```

## Documentacao Completa

- [README completo](https://github.com/guifav/rag_template/blob/main/README.md)
- [Setup Supabase](https://github.com/guifav/rag_template/blob/main/docs/SUPABASE_SETUP.md)
- [Setup Neon](https://github.com/guifav/rag_template/blob/main/docs/NEON_SETUP.md)
- [Comparacao de Bancos](https://github.com/guifav/rag_template/blob/main/docs/DATABASE_COMPARISON.md)

## 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](https://github.com/guifav/rag_template)
2. Crie uma branch
3. Commit suas mudancas
4. Abra um Pull Request

Veja [CONTRIBUTING.md](https://github.com/guifav/rag_template/blob/main/CONTRIBUTING.md)

## Licenca

MIT License - veja [LICENSE](https://github.com/guifav/rag_template/blob/main/LICENSE)

## Contato

- GitHub: [@guifav](https://github.com/guifav)
- Issues: [github.com/guifav/rag_template/issues](https://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**