README_FIX.md

🔧 FIX: Build FAISS Falhou

❌ Problema

{"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

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

Passo 2: Fazer backup dos arquivos atuais (opcional)

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

# 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

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

Passo 5: Commit e Push

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:

# 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:

{"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:

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:

{
  "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):

+ 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:

- 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:

- 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:

# 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:

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á! 🐝