docs/tutorials/01_getting_started.md

# RAG do Zero - Primeiros Passos

Guia completo para iniciar com o RAG Template em 15 minutos.

**Tempo estimado**: 15-20 minutos
**Nivel**: Iniciante
**Pre-requisitos**: Python 3.10+ instalado

---

## O que e RAG?

**RAG (Retrieval-Augmented Generation)** combina:
- **Retrieval** (Recuperacao): Buscar informacao relevante em documentos
- **Augmented** (Aumentada): Enriquecer o contexto da IA
- **Generation** (Geracao): LLM gera resposta baseada no contexto

**Em termos simples**: E como dar "memoria" e conhecimento especializado para uma IA.

**Exemplo pratico**:
- Sem RAG: "Qual e a politica de ferias da empresa?" → IA chuta ou diz "nao sei"
- Com RAG: IA busca no manual RH → "Segundo o manual, sao 30 dias apos 1 ano"

---

## Passo 1: Instalacao

### 1.1 Clonar o Repositorio

```bash
git clone https://github.com/guifav/rag_template.git
cd rag_template
```

### 1.2 Criar Ambiente Virtual

```bash
# Linux/Mac
python -m venv .venv
source .venv/bin/activate

# Windows
python -m venv .venv
.venv\Scripts\activate
```

### 1.3 Instalar Dependencias

```bash
pip install -r requirements.txt
```

Isso instala:
- Gradio (interface web)
- PostgreSQL driver (banco de dados)
- Sentence Transformers (embeddings)
- E outras dependencias

**Tempo**: ~2-3 minutos

---

## Passo 2: Configurar Banco de Dados

Voce tem 3 opcoes. Recomendamos Neon para iniciantes (10GB gratis).

### Opcao A: Neon.tech (Recomendado)

1. Crie conta em [neon.tech](https://neon.tech)
2. Crie novo projeto
3. No SQL Editor, execute:
```sql
CREATE EXTENSION vector;
```
4. Copie a connection string
5. Use o script de setup:
```bash
python scripts/setup_neon.py
```

**Tempo**: ~3-5 minutos

### Opcao B: Supabase

```bash
python scripts/setup_supabase.py
```

### Opcao C: Docker Local

```bash
docker-compose up -d
```

Veja guias completos:
- [Neon Setup](../NEON_SETUP.md)
- [Supabase Setup](../SUPABASE_SETUP.md)
- [Comparacao de Providers](../DATABASE_COMPARISON.md)

---

## Passo 3: Configurar Variave is de Ambiente

### 3.1 Criar arquivo .env

```bash
cp .env.example .env
```

### 3.2 Editar .env

Abra `.env` e configure:

```env
# Banco de dados (use a connection string do passo 2)
DATABASE_URL=postgresql://user:pass@host:port/db

# Hugging Face (obrigatorio para LLM)
HF_TOKEN=seu_token_aqui

# Opcional: outros providers
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
```

**Como obter HF_TOKEN**:
1. Crie conta em [huggingface.co](https://huggingface.co)
2. Va para Settings → Access Tokens
3. Crie novo token (permissao "read")
4. Copie e cole no .env

**Tempo**: ~2 minutos

---

## Passo 4: Executar a Aplicacao

```bash
python app.py
```

Voce vera:

```
Running on local URL:  http://127.0.0.1:7860
```

Abra esse link no navegador!

**Tempo de inicio**: 10-30 segundos (baixa modelos na primeira vez)

---

## Passo 5: Primeira Ingestao de Documentos

Agora vamos adicionar documentos ao sistema.

### 5.1 Preparar Documento

Crie um arquivo `teste.txt` com algum conteudo:

```
A empresa XYZ foi fundada em 2020.
Nossa missao e tornar a tecnologia acessivel.
Oferecemos 30 dias de ferias apos 1 ano de empresa.
O horario de trabalho e das 9h as 18h.
Temos escritorios em Sao Paulo e Rio de Janeiro.
```

### 5.2 Fazer Upload

1. Na interface, va para aba **"Ingestao de Documentos"**
2. Clique em "Browse" e selecione `teste.txt`
3. Deixe configuracoes padrao:
   - Estrategia: Tamanho Fixo
   - Chunk Size: 1000
   - Overlap: 200
4. Clique em **"Iniciar Ingestao"**

Voce vera o processo:
1. Extraindo texto (instantaneo para TXT)
2. Dividindo em chunks (1 chunk para texto pequeno)
3. Gerando embeddings (~1-2 segundos)
4. Salvando no banco (instantaneo)

**Resultado**: "Ingestao concluida! 1 documento(s) processado(s)"

---

## Passo 6: Primeira Consulta

Agora vamos buscar informacao nos documentos.

### 6.1 Busca Simples

1. Va para aba **"Exploracao da Base"**
2. Digite uma query: `ferias da empresa`
3. Clique em **"Buscar"**

Voce vera:
- Documento encontrado
- Score de similaridade (~0.7-0.9)
- Conteudo: "Oferecemos 30 dias de ferias..."

**O que aconteceu**:
1. Sua query foi transformada em embedding
2. Sistema buscou embeddings similares no banco
3. Retornou documentos mais relevantes

---

## Passo 7: Primeiro Chat com RAG

Hora de conversar com seus documentos!

### 7.1 Configurar Chat

1. Va para aba **"Chat RAG"**
2. Configuracoes:
   - LLM Provider: HuggingFace
   - Top K: 3
   - Temperature: 0.3
   - Max Tokens: 256

### 7.2 Fazer Pergunta

Digite: `Quantos dias de ferias a empresa oferece?`

Clique em **"Enviar"**

**Resposta esperada**:
```
A empresa oferece 30 dias de ferias apos 1 ano de trabalho.

Contextos recuperados:
1. "Oferecemos 30 dias de ferias apos 1 ano de empresa." (score: 0.85)
```

**O que aconteceu**:
1. Sistema buscou contextos relevantes (top 3)
2. Montou um prompt com contexto + pergunta
3. Enviou para LLM (HuggingFace API)
4. LLM gerou resposta baseada no contexto

**Tempo de resposta**: 2-5 segundos (dependendo da API)

---

## Passo 8: Experimentar Parametros

Agora vamos entender o impacto dos parametros.

### 8.1 Testar Top K

1. Va para aba **"Playground de Parametros"**
2. Config A: top_k = 1
3. Config B: top_k = 5
4. Query: `horario de trabalho`
5. Compare resultados

**Observacao**: Mais contexto (top_k maior) pode ajudar, mas tambem pode trazer ruido.

### 8.2 Testar Temperature

1. Config A: temperature = 0.1 (deterministico)
2. Config B: temperature = 0.9 (criativo)
3. Mesma query
4. Compare

**Observacao**: Temperature baixa = respostas mais precisas. Temperature alta = respostas mais variadas/criativas.

---

## Passo 9: Monitorar Uso

1. Va para aba **"Monitoramento"**
2. Veja estatisticas:
   - Documentos no banco: 1
   - Queries realizadas: ~3
   - Latencias medias

---

## Proximos Passos

Parabens! Voce criou seu primeiro sistema RAG. Agora:

1. **Adicione mais documentos**: PDFs, mais TXTs
2. **Teste estrategias de chunking**: Veja [Tutorial 2](02_optimizing_rag.md)
3. **Experimente features avancadas**: Hybrid search, reranking
4. **Deploy**: [Tutorial 3](03_production_deployment.md)

---

## Troubleshooting

### "Unable to connect to database"

**Problema**: DATABASE_URL incorreto

**Solucao**:
1. Verifique .env
2. Teste conexao: `python scripts/setup_neon.py`
3. Certifique-se que banco esta ativo

### "HF_TOKEN invalid"

**Problema**: Token HuggingFace invalido

**Solucao**:
1. Gere novo token em huggingface.co/settings/tokens
2. Certifique-se de copiar token completo
3. Atualize .env

### "Model download failed"

**Problema**: Erro ao baixar modelo de embedding

**Solucao**:
1. Verifique conexao com internet
2. Aguarde alguns minutos e tente novamente
3. Modelos sao baixados apenas na primeira vez

### App muito lento

**Causas comuns**:
- HuggingFace API em horario de pico
- Database remoto com latencia alta
- Modelo de embedding ainda baixando

**Solucao**:
- Use modelo de embedding menor (384d)
- Configure connection pooling
- Considere usar OpenAI/Anthropic para LLM

---

## Recursos Adicionais

- [Tutorial 2: Otimizando seu RAG](02_optimizing_rag.md)
- [Tutorial 3: RAG em Producao](03_production_deployment.md)
- [Tutorial 4: RAG Avancado](04_advanced_rag.md)
- [FAQ](../FAQ.md)
- [Documentacao Completa](../../README.md)

---

## Resumo

Neste tutorial voce:
- Instalou o RAG Template
- Configurou banco de dados (Neon/Supabase)
- Fez primeira ingestao de documento
- Realizou primeira busca semantica
- Conversou com seus documentos usando LLM
- Experimentou com parametros

**Tempo total**: ~15-20 minutos

**Proximo**: [Otimizando seu RAG](02_optimizing_rag.md)