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

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.

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:

pg_dump $DATABASE_URL > backup_$(date +%Y%m%d).sql

Restore:

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
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 para detalhes.

Como executar testes?

# 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
• Tutorial 2: Otimizando RAG
• Tutorial 3: RAG em Producao
• Tutorial 4: RAG Avancado

Documentacao

• README Principal
• Guia de Deploy
• Comparacao de Databases
• Roadmap

Comunidade

• GitHub Issues: github.com/guifav/rag_template/issues
• Discussions: Use GitHub Discussions
• Pull Requests: Contribuicoes bem-vindas!

---

Nao encontrou sua duvida?

1. Procure em issues existentes
2. Abra nova issue com label "question"
3. Descreva sua duvida claramente
4. Comunidade ajudara!

---

Ultima atualizacao: Janeiro 2026