README_FIX.md

# 🔧 FIX: Build FAISS Falhou

## ❌ Problema

```json
{"status": "error", "message": "Build FAISS falhou", "progress": 0}
```

## ✅ Solução

Este pacote contém 3 arquivos corrigidos para resolver o erro.

---

## 📦 Arquivos Incluídos

1. **requirements.txt** - Versão COMPLETA com todas as dependências
2. **config.yaml** - Otimizado (batch_size reduzido, prefixo no modelo)
3. **rag_builder.py** - Com logging detalhado para debug

---

## 🚀 Como Aplicar (Passo-a-Passo)

### Passo 1: Localizar seu repositório local do Space

```bash
cd /caminho/para/para_ai_rag_langchain
# (ou o nome do diretório do seu Space)
```

### Passo 2: Fazer backup dos arquivos atuais (opcional)

```bash
cp requirements.txt requirements.txt.BAK
cp config.yaml config.yaml.BAK
cp rag_builder.py rag_builder.py.BAK
```

### Passo 3: Copiar arquivos corrigidos

```bash
# Extrair o ZIP que você baixou
unzip para_ai_rag_FIX.zip

# Copiar arquivos
cp para_ai_rag_FIX_v2/requirements.txt .
cp para_ai_rag_FIX_v2/config.yaml .
cp para_ai_rag_FIX_v2/rag_builder.py .
```

### Passo 4: Verificar mudanças

```bash
git status
# Deve mostrar:
#   modified:   requirements.txt
#   modified:   config.yaml
#   modified:   rag_builder.py
```

### Passo 5: Commit e Push

```bash
git add requirements.txt config.yaml rag_builder.py
git commit -m "fix: Adicionar dependências faltando + otimizações (torch, transformers, tokenizers)"
git push origin main
```

### Passo 6: Monitorar Rebuild

Aguardar ~8-10 minutos para rebuild e depois monitorar setup:

```bash
# Opção 1: Com watch (atualiza automaticamente)
watch -n 10 'curl -s https://caarleexx-paraai-rag.hf.space/setup/status | jq'

# Opção 2: Manual
curl https://caarleexx-paraai-rag.hf.space/setup/status | jq
```

**Progresso esperado:**

```json
{"status": "cloning", "progress": 10, "message": "Clonando chunks..."}
{"status": "extracting", "progress": 30, "message": "Descompactando..."}
{"status": "building", "progress": 70, "message": "Construindo FAISS..."}
{"status": "ready", "progress": 100, "message": "FAISS pronto!"}
```

### Passo 7: Testar quando pronto

Quando `status` = `"ready"`, testar busca:

```bash
curl -X POST https://caarleexx-paraai-rag.hf.space/search/embedding \
  -H "Content-Type: application/json" \
  -d '{"query": "FGTS correção monetária TR", "top_k": 3}' | jq
```

**Resposta esperada:**

```json
{
  "cluster_id": "RAG-0301",
  "query": "FGTS correção monetária TR",
  "total_results": 3,
  "results": [
    {
      "id": "12345",
      "ementa": "...",
      "score": 0.87,
      "metadata": {...}
    }
  ],
  "query_time_ms": 142.35
}
```

---

## 📊 O Que Foi Corrigido?

### requirements.txt

**ADICIONADO (estava faltando):**

```diff
+ torch==2.2.0
+ transformers==4.37.2
+ tokenizers==0.15.2
+ safetensors==0.4.2
+ huggingface-hub==0.20.3
```

**Por quê?**

- `torch` → Backend para sentence-transformers
- `transformers` → Carregar modelos HuggingFace
- `tokenizers` → Processar texto antes de embeddings
- `safetensors` → Formato seguro para pesos do modelo
- `huggingface-hub` → Baixar modelos do Hub

### config.yaml

**ALTERADO:**

```diff
- embedding_model: "all-MiniLM-L6-v2"
+ embedding_model: "sentence-transformers/all-MiniLM-L6-v2"
```

**Por quê?** HuggingFaceEmbeddings precisa do prefixo `sentence-transformers/` para encontrar o modelo no Hub.

**REDUZIDO:**

```diff
- embedding_batch_size: 64
+ embedding_batch_size: 16
```

**Por quê?** Batch 64 pode causar OOM (Out of Memory) no HF Spaces free tier (16GB RAM). Batch 16 é mais seguro.

### rag_builder.py

**ADICIONADO:**

- ✅ Logging detalhado em cada passo (1/5, 2/5, etc)
- ✅ Try/except específico para ImportError (mostra deps faltando)
- ✅ Try/except específico para FileNotFoundError
- ✅ Traceback completo em caso de erro
- ✅ Medição de tempo e velocidade
- ✅ Verificação de tamanho do index salvo

---

## ⚠️ Troubleshooting

### Erro: "No module named 'torch'"

**Causa:** requirements.txt não foi atualizado corretamente

**Solução:**
1. Verificar se push foi bem-sucedido: `git log -1`
2. Verificar no HF Space se requirements.txt tem `torch==2.2.0`
3. Se não, fazer push novamente

### Erro: "Killed" ou "Exit code 137"

**Causa:** OOM (Out of Memory)

**Solução:** Reduzir ainda mais o batch_size:

```yaml
# Em config.yaml
embedding_batch_size: 8  # ou até 4
```

### Erro: "Model not found: all-MiniLM-L6-v2"

**Causa:** Nome do modelo sem prefixo

**Solução:** Verificar config.yaml tem:

```yaml
embedding_model: "sentence-transformers/all-MiniLM-L6-v2"
                  ^^^^^^^^^^^^^^^^^^^^^^^^
                  Prefixo obrigatório!
```

### Build ainda falha?

1. **Acessar logs do Space:**
   https://huggingface.co/spaces/caarleexx/paraai-rag/logs

2. **Procurar por:**
   - "ModuleNotFoundError"
   - "ImportError"
   - "MemoryError"
   - "Traceback"
   - Última exceção antes de "Build FAISS falhou"

3. **Me enviar:**
   - Todo o log de erro
   - Output de `pip list` do Space (se conseguir acessar)
   - Arquivo requirements.txt atual

---

## 📊 Estimativas

**Rebuild:** ~8-10 minutos

**Setup:** ~15-18 minutos para 300 chunks
- Clone: ~3min
- Extract: ~2min
- Concat/Filter: ~2min
- Build FAISS: ~8-10min (batch_size=16, CPU)

**RAM:** ~2GB durante build

**Disco:** ~150MB (FAISS index persistente)

---

## ✅ Checklist Final

Antes de fazer push, verificar:

- [ ] `requirements.txt` inclui `torch==2.2.0`
- [ ] `requirements.txt` inclui `transformers==4.37.2`
- [ ] `requirements.txt` inclui `tokenizers==0.15.2`
- [ ] `requirements.txt` inclui `safetensors==0.4.2`
- [ ] `requirements.txt` inclui `huggingface-hub==0.20.3`
- [ ] `config.yaml` tem `embedding_model: "sentence-transformers/all-MiniLM-L6-v2"`
- [ ] `config.yaml` tem `embedding_batch_size: 16` (ou menos)

---

## 📞 Suporte

Se problema persistir após aplicar fix:

1. Acessar logs: https://huggingface.co/spaces/caarleexx/paraai-rag/logs
2. Copiar **TODA** a exceção/traceback
3. Me enviar para análise detalhada

---

⚖️ **InJustiça não para o Paraná!** 🐝