docs/FAQ.md

# FAQ - Perguntas Frequentes

Respostas para as duvidas mais comuns sobre o RAG Template.

---

## Geral

### O que e RAG?

RAG (Retrieval-Augmented Generation) e uma tecnica que combina busca de informacao com geracao de texto por LLMs. Em vez do LLM gerar respostas apenas com seu conhecimento pre-treinado, ele primeiro busca informacao relevante em documentos e usa isso como contexto.

**Analogia**: E como fazer uma prova de consulta vs decorar tudo. Com RAG, o LLM pode "consultar" seus documentos.

### Quando usar RAG?

Use RAG quando:
- Precisa de respostas baseadas em documentos especificos
- Informacao muda frequentemente (docs atualizados)
- Quer citar fontes das respostas
- Precisa de conhecimento especializado/privado
- Quer reduzir alucinacoes do LLM

**Nao use RAG quando**:
- Precisa de conhecimento geral (use LLM direto)
- Tarefas criativas sem base documental
- Respostas muito curtas (busca simples e melhor)

### Qual a diferenca entre RAG e Fine-tuning?

| RAG | Fine-tuning |
|-----|-------------|
| Adiciona documentos externos | Retreina o modelo |
| Atualizacao instantanea | Requer re-treinamento |
| Menos recursos computacionais | Muito caro |
| Pode citar fontes | Conhecimento "embebido" |
| Melhor para docs especificos | Melhor para estilo/formato |

**Recomendacao**: Use RAG primeiro. Fine-tuning e para casos muito especificos.

---

## Ingestao de Documentos

### Por que meus resultados sao irrelevantes?

**Causas comuns**:

1. **Chunks muito grandes ou pequenos**
   - Muito grande: Contexto diluido
   - Muito pequeno: Perde contexto
   - **Solucao**: Teste 500-1500 caracteres

2. **Estrategia de chunking inadequada**
   - Documentos tecnicos: Use recursivo
   - Textos narrativos: Use por sentencas
   - **Solucao**: [Veja comparacao de chunking](tutorials/02_optimizing_rag.md#estrategias-de-chunking)

3. **Modelo de embedding nao adequado**
   - Documentos tecnicos em ingles: `all-MiniLM-L6-v2`
   - Documentos multilingues: `paraphrase-multilingual`
   - **Solucao**: Teste diferentes modelos

4. **Query muito diferente dos documentos**
   - Use query expansion
   - Reformule a pergunta
   - **Solucao**: Aba "Chat RAG" → Ativar query expansion

### Como escolher o tamanho de chunk?

**Regra geral**:
- Documentos tecnicos/codigo: 500-800 caracteres
- Documentos narrativos: 1000-1500 caracteres
- Perguntas/respostas: 200-500 caracteres

**Dica**: Use a aba "Comparacao de Chunking" para testar!

**Considere**:
- Modelo de embedding: Limite de tokens (geralmente 512)
- Contexto do LLM: Quantos chunks cabem (top_k * chunk_size)
- Semantica: Chunks devem ter sentido completo

### Posso usar imagens e PDFs?

- **PDFs**: Sim, suportado nativamente
- **Imagens**: Nao no momento (planejado para futuro)
- **DOCX**: Nao (planejado para futuro)
- **HTML/Markdown**: Nao (planejado para futuro)

### Quanto tempo demora a ingestao?

**Depende de**:
- Tamanho dos documentos
- Numero de chunks gerados
- Modelo de embedding usado

**Benchmarks tipicos** (CPU):
- Documento de 10 paginas: ~5-10 segundos
- Documento de 100 paginas: ~30-60 segundos
- 100 documentos pequenos: ~2-5 minutos

**Otimizacoes**:
- Use cache de embeddings (ja ativo)
- Batch processing (ja ativo)
- GPU para embeddings (requer config manual)

---

## Busca e Recuperacao

### O que e top_k e como escolher?

**Top_k** e o numero de documentos recuperados na busca.

**Guidelines**:
- Perguntas simples: top_k = 3-5
- Perguntas complexas: top_k = 5-10
- Analise comparativa: top_k = 10-20

**Trade-offs**:
- Muito baixo: Pode perder contexto relevante
- Muito alto: Ruido, latencia maior, custo maior

**Dica**: Use Playground para testar diferentes valores!

### Quando usar hybrid search?

**Use hybrid search (BM25 + vetorial) quando**:
- Busca por termos exatos e importantes (nomes, datas, numeros)
- Documentos tecnicos com terminologia especifica
- Mix de busca lexica e semantica

**Nao use quando**:
- Busca puramente semantica e suficiente
- Performance e critica (hybrid e ~2x mais lento)
- Documentos muito curtos

**Alpha recomendado**:
- 0.3-0.4: Enfase em BM25 (termos exatos)
- 0.5: Balanceado
- 0.6-0.7: Enfase em vetorial (semantica)

### O que e reranking e quando usar?

**Reranking** usa um modelo cross-encoder para re-ordenar resultados.

**Use quando**:
- Qualidade e mais importante que velocidade
- Top_k inicial e grande (ex: recupera 20, rerank para 5)
- Queries complexas

**Nao use quando**:
- Latencia e critica (<1s resposta)
- Hardware limitado (reranking e pesado)
- Resultados iniciais ja sao bons

**Performance**:
- Melhoria tipica: +10-15% precision
- Custo: +200-500ms de latencia

---

## LLMs e Geracao

### Qual LLM devo usar?

Depende de prioridades:

| Provider | Melhor para | Custo | Qualidade | Latencia |
|----------|-------------|-------|-----------|----------|
| **HuggingFace** | Testes, MVP | Gratis* | Media | Alta |
| **OpenAI GPT-3.5** | Producao rapida | Baixo | Boa | Baixa |
| **OpenAI GPT-4** | Melhor qualidade | Alto | Excelente | Media |
| **Anthropic Claude** | Textos longos | Medio | Excelente | Baixa |
| **Ollama** | Privacidade | Gratis** | Variavel | Variavel |

*Gratis mas com rate limits
**Requer servidor proprio

**Recomendacao**:
- Desenvolvimento: HuggingFace
- Producao: GPT-3.5 ou Claude

### Como melhorar a qualidade das respostas?

1. **Melhore a recuperacao**
   - Ajuste chunk size
   - Teste hybrid search
   - Use reranking
   - Aumente top_k

2. **Ajuste parametros do LLM**
   - Temperature baixa (0.1-0.3): Respostas precisas
   - Temperature media (0.4-0.6): Respostas naturais
   - Temperature alta (0.7-1.0): Respostas criativas

3. **Melhore o prompt**
   - Instrucoes claras
   - Exemplos de formato desejado
   - Restricoes explicitas

4. **Use modelo melhor**
   - GPT-4 > GPT-3.5 > Modelos open-source

### Por que o LLM alucina mesmo com RAG?

**Causas**:
1. Contexto recuperado nao tem a resposta
2. Contexto e ambiguo ou contraditorio
3. LLM ignora o contexto
4. Temperature muito alta

**Solucoes**:
1. Verifique contextos recuperados (painel lateral)
2. Melhore a busca (hybrid search, reranking)
3. Use prompt mais restritivo: "RESPONDA APENAS com base no contexto"
4. Reduza temperature para 0.1-0.2
5. Use modelo mais capaz (GPT-4, Claude)

---

## Performance e Escalabilidade

### Como melhorar a velocidade?

**Ingestao**:
- Use modelo de embedding menor (384d vs 768d)
- Batch processing (ja ativo)
- Cache (ja ativo)

**Busca**:
- Limite top_k
- Use indices otimizados (IVFFLAT ja configurado)
- Connection pooling (configure no provider)

**Geracao**:
- Use LLM mais rapido (GPT-3.5 vs GPT-4)
- Reduza max_tokens
- Use streaming (nao implementado ainda)

### Quantos documentos posso armazenar?

**Depende do database**:
- Supabase free: 500MB = ~300k chunks pequenos
- Neon free: 10GB = ~6M chunks pequenos
- Railway: Baseado em credito
- Local: Ilimitado (ate disco encher)

**Calculo**:
```
Chunk medio: 1000 chars = 1KB
Embedding (384d): 1.5KB
Metadata: 0.5KB
Total: ~3KB por chunk

1GB = ~330k chunks
10GB = ~3.3M chunks
```

### O sistema escala?

**Ate 100k documentos**: Sim, sem problemas
**100k-1M documentos**: Requer otimizacoes
**1M+ documentos**: Requer arquitetura distribuida

**Otimizacoes para escala**:
- Indices IVFFLAT (ja implementado)
- Connection pooling
- Cache distribuido (Redis)
- Sharding de database
- Load balancing

---

## Banco de Dados

### Qual provider de banco escolher?

Veja [comparacao completa](DATABASE_COMPARISON.md).

**TL;DR**:
- **Desenvolvimento**: Neon (10GB free)
- **MVP/Demo**: Supabase (infraestrutura robusta)
- **Producao**: Supabase Pro ou database dedicado
- **Full-stack**: Railway (app + banco junto)

### Posso trocar de provider depois?

**Sim!** O codigo e 100% portatil (PostgreSQL padrao).

**Para migrar**:
1. Backup: `pg_dump $DATABASE_URL_OLD > backup.sql`
2. Setup novo provider
3. Restore: `psql $DATABASE_URL_NEW < backup.sql`
4. Atualize .env com novo DATABASE_URL
5. Reinicie app

**Tempo**: ~5-10 minutos

### Como fazer backup?

**Manual**:
```bash
pg_dump $DATABASE_URL > backup_$(date +%Y%m%d).sql
```

**Restore**:
```bash
psql $DATABASE_URL < backup_20260123.sql
```

**Automatico**:
- Supabase Pro: Backups diarios automaticos
- Neon: Point-in-time recovery
- Railway: Manual ou configure script

---

## Deploy e Producao

### Qual opcao de deploy e melhor?

Depende do caso:

| Opcao | Melhor para | Custo | Facilidade |
|-------|-------------|-------|------------|
| **HF Spaces** | Demo, Portfolio | Gratis | Muito facil |
| **Railway** | MVP, Startup | $5-20/mes | Facil |
| **Docker VPS** | Controle total | $5-50/mes | Medio |
| **Local** | Desenvolvimento | Gratis | Facil |

**Recomendacao**: Comece com HF Spaces para demo, migre para Railway/VPS para producao.

### Como monitorar em producao?

**Ja implementado**:
- Aba "Monitoramento"
- Logging estruturado (JSON)
- Metricas de latencia

**Adicional (recomendado)**:
- Prometheus + Grafana para metricas
- Sentry para erros
- CloudWatch/DataDog para logs

### Como lidar com picos de trafego?

**Opcoes**:
1. **Horizontal scaling**: Multiplas instancias do app
2. **Rate limiting**: Limitar requests por usuario
3. **Caching**: Cache de respostas frequentes
4. **Queue system**: Processar requests em fila

**Nao implementado** no template atual, mas pode adicionar facilmente.

---

## Desenvolvimento

### Como contribuir?

1. Leia [CONTRIBUTING.md](../CONTRIBUTING.md)
2. Fork o repositorio
3. Crie uma branch
4. Faca suas mudancas
5. Abra um Pull Request

### Como adicionar novo provider de LLM?

1. Crie arquivo em `src/llms/seu_provider.py`
2. Herde de `BaseLLM`
3. Implemente metodo `generate()`
4. Adicione ao factory em `src/llms/__init__.py`
5. Adicione testes

Veja [Arquitetura](../PROJECT_STRUCTURE.md) para detalhes.

### Como executar testes?

```bash
# Todos os testes
pytest tests/ -v

# Com cobertura
pytest tests/ --cov=src --cov=ui --cov-report=html

# Testes especificos
pytest tests/test_units.py -v
```

---

## Recursos Adicionais

### Tutoriais
- [Tutorial 1: Primeiros Passos](tutorials/01_getting_started.md)
- [Tutorial 2: Otimizando RAG](tutorials/02_optimizing_rag.md)
- [Tutorial 3: RAG em Producao](tutorials/03_production_deployment.md)
- [Tutorial 4: RAG Avancado](tutorials/04_advanced_rag.md)

### Documentacao
- [README Principal](../README.md)
- [Guia de Deploy](../DEPLOY.md)
- [Comparacao de Databases](DATABASE_COMPARISON.md)
- [Roadmap](ROADMAP.md)

### Comunidade
- GitHub Issues: [github.com/guifav/rag_template/issues](https://github.com/guifav/rag_template/issues)
- Discussions: Use GitHub Discussions
- Pull Requests: Contribuicoes bem-vindas!

---

## Nao encontrou sua duvida?

1. Procure em [issues existentes](https://github.com/guifav/rag_template/issues)
2. Abra nova issue com label "question"
3. Descreva sua duvida claramente
4. Comunidade ajudara!

---

**Ultima atualizacao**: Janeiro 2026