docs/SPACES_LIMITATIONS.md

# Limitacoes do Hugging Face Spaces

Guia completo sobre limitacoes ao usar o RAG Template no Hugging Face Spaces.

---

## Hardware Spaces (Free Tier)

### CPU Basic

**Recursos**:
- 2 vCPU
- 16 GB RAM
- 50 GB disco

**Limitacoes**:
- Sem GPU (embeddings e inference via CPU)
- Cold start: 30-60 segundos
- Timeout: 60 segundos por request

---

## Limitacoes de Performance

### Embeddings

**Modelo**: `sentence-transformers/all-MiniLM-L6-v2`

**Performance**:
- Geracao: ~100-200ms por documento (CPU)
- Batch de 10 docs: ~1-2 segundos
- Upload de 100 docs: ~10-20 segundos

**Recomendacoes**:
- Limite uploads a 50-100 documentos por vez
- Use documentos menores (<10 paginas)
- Evite PDFs muito grandes (>5MB)

---

### Busca Vetorial

**Performance**:
- Query simples: 50-150ms
- Hybrid search: 100-300ms
- Com reranking: 200-500ms

**Recomendacoes**:
- Limite top_k a 10 ou menos
- Use reranking apenas quando necessario
- Considere indices otimizados (IVFFLAT)

---

### Geracao de Respostas

#### HuggingFace Inference API (Free)

**Limites**:
- ~30,000 tokens/hora
- Queue em horarios de pico
- Timeout de 60 segundos
- Modelos limitados

**Performance**:
- Geracao: 2-10 segundos
- Pode ter espera na queue
- Tokens/segundo: variavel

**Recomendacoes**:
- Use modelos menores (7B parameters)
- Limite max_tokens a 512
- Evite uso intensivo em pico

#### OpenAI / Anthropic

**Limites**:
- Baseado em creditos da conta
- Rate limits por tier
- Custos por token

**Performance**:
- GPT-3.5: ~1-3 segundos
- GPT-4: ~3-10 segundos
- Claude: ~2-5 segundos

---

## Limitacoes de Database

### Espaco de Armazenamento

O Space em si nao armazena dados persistentes. Voce precisa de banco externo:

#### Supabase Free
- **Storage**: 500MB
- **Documentos**: ~300,000 chunks pequenos
- **Embeddings (384d)**: ~1.5KB por documento
- **Estimativa**: 500MB = ~330k documentos

**Calculo**:
```
Documento medio: 1000 chars = 1 chunk
Embedding: 384 floats * 4 bytes = 1536 bytes
Metadata: ~100 bytes
Total: ~1.6KB por documento

500MB / 1.6KB = ~312,500 documentos
```

#### Neon Free
- **Storage**: 10GB
- **Documentos**: ~6M chunks pequenos
- **Compute**: 100 horas/mes

---

### Connection Limits

#### Supabase Free
- **Conexoes simultaneas**: ~50
- **Pooling**: Sim (pgBouncer)

#### Neon Free
- **Conexoes simultaneas**: 1000
- **Pooling**: Sim (integrado)

**Recomendacao**: Configure connection pooling no app.

---

## Cold Start

### O que e Cold Start?

Quando seu Space nao recebe requests por algum tempo, ele "dorme". No proximo acesso:

1. Container reinicia
2. Dependencias carregam
3. Modelos baixam
4. Banco conecta

**Tempo total**: 30-60 segundos

### Como Mitigar

1. **Keep-alive simples**:
   ```bash
   # Ping a cada 10 minutos (externamente)
   curl https://seu-space.hf.space
   ```

2. **Upgrade para persistente**:
   - Spaces Pro: Sem cold start
   - Custo: $5-20/mes

---

## Timeouts

### Request Timeout

**Limite**: 60 segundos

**Impacto**:
- Uploads muito grandes podem falhar
- Geracao longa pode timeout
- Processos pesados podem ser interrompidos

**Solucoes**:
1. Divida uploads grandes em batches
2. Limite max_tokens
3. Use modelos mais rapidos
4. Otimize queries

---

### Idle Timeout

**Free Tier**: Space pausa apos ~15 minutos sem uso

**Pro**: Sem pause

---

## Limites de Rede

### Bandwidth

**Free Tier**: Ilimitado (com fair use)

**Upload**:
- Limite pratico: ~100MB por arquivo
- Multiple uploads: OK

**Download**:
- Responses: Sem limite oficial
- Fair use aplicado

---

## Limitacoes de Features

### Nao Disponivel no Spaces Free

1. **GPU**: Apenas CPU (ou upgrade)
2. **Persistencia de dados**: Precisa banco externo
3. **Scheduled jobs**: Nao suportado
4. **WebSockets persistentes**: Limitado
5. **Custom domains**: Apenas em Pro

### Disponivel

1. **Gradio interface**: Totalmente suportado
2. **PostgreSQL externo**: Supabase/Neon/Railway
3. **API calls**: OpenAI, Anthropic, HF
4. **File uploads**: Temporarios (perdidos no restart)
5. **Secrets management**: Sim

---

## Comparacao: Free vs Pro

| Feature | Free | Pro ($5/mes) |
|---------|------|--------------|
| **CPU** | 2 vCPU | 4 vCPU |
| **RAM** | 16 GB | 32 GB |
| **Disco** | 50 GB | 100 GB |
| **Cold start** | Sim | Nao |
| **Timeout** | 60s | 120s |
| **Priority queue** | Nao | Sim |
| **Custom domain** | Nao | Sim |

---

## Recomendacoes de Uso

### Para Demo/Portfolio

**Configuracao ideal**:
- Supabase Free (500MB)
- HuggingFace Inference API
- ~100-1000 documentos
- Top_k: 3-5
- Max_tokens: 256-512

**Usuarios simultaneos**: 5-10

---

### Para Desenvolvimento

**Configuracao ideal**:
- Neon Free (10GB)
- Qualquer LLM provider
- ~1000-5000 documentos
- Testes de features

**Usuarios simultaneos**: 1-2 (voce)

---

### Para Producao

**Nao recomendado Free Tier**

**Upgrade necessario**:
- Spaces Pro ($5-20/mes)
- Supabase Pro ($25/mes)
- LLM provider pago

**Ou**:
- Deploy proprio (Railway, Render, VPS)
- Mais controle e recursos

---

## Otimizacoes Recomendadas

### 1. Cache Embeddings

Ja implementado no template:
```python
# Embeddings sao cacheados automaticamente
# Evita reprocessar mesmos documentos
```

### 2. Batch Processing

```python
# Processe multiplos documentos de uma vez
# Mais eficiente que um por um
```

### 3. Lazy Loading

```python
# Modelos carregam apenas quando necessario
# Reduz cold start
```

### 4. Connection Pooling

```python
# Reusa conexoes de banco
# Evita overhead de novas conexoes
```

---

## Monitoramento

### Metricas Disponiveis

1. **Logs**: Via interface do Space
2. **Usage**: Dashboard do HF
3. **Database**: Dashboard do provider

### O que Monitorar

- **Cold starts**: Frequencia
- **Timeouts**: Quantas requests falham
- **Database size**: Proximo do limite?
- **API usage**: LLM provider credits

---

## Troubleshooting

### "Application startup timeout"

**Causa**: Modelos muito grandes ou muitas dependencias

**Solucao**:
1. Reduza dependencias
2. Use modelos menores
3. Upgrade para Pro

---

### "Request timeout"

**Causa**: Operacao demora >60s

**Solucao**:
1. Divida em batches menores
2. Reduza max_tokens
3. Use modelo mais rapido

---

### "Out of memory"

**Causa**: Modelos ou dados muito grandes

**Solucao**:
1. Use modelo de embedding menor (384d)
2. Limite batch size
3. Upgrade para Pro

---

### "Database connection failed"

**Causa**: Banco pausado ou limites excedidos

**Solucao**:
1. Verifique se banco esta ativo
2. Verifique connection string
3. Verifique limites de conexao

---

## Alternativas ao Spaces

Se limitacoes sao problematicas:

### Railway
- $5/mes credito
- Mais controle
- Deployment completo

### Render
- Free tier generoso
- 750h/mes compute
- Hibernacao apos 15min

### VPS (DigitalOcean, Linode)
- $5-10/mes
- Controle total
- Requer setup manual

### Local
- Gratuito
- Sem limitacoes
- Apenas para voce

---

## Conclusao

Hugging Face Spaces Free e excelente para:
- Demos e portfolios
- Prototipos e MVPs
- Aprendizado e testes
- Projetos pessoais pequenos

**Nao recomendado para**:
- Producao em escala
- Aplicacoes criticas
- Multiplos usuarios simultaneos
- Processamento pesado continuo

Para producao, considere upgrade ou deploy proprio.

---

## Recursos Adicionais

- [Hugging Face Spaces Docs](https://huggingface.co/docs/hub/spaces)
- [Spaces Hardware](https://huggingface.co/docs/hub/spaces-overview#hardware-specs)
- [Deploy Alternatives](../DEPLOY.md)

---

**Feito com muito cafe**