🚀 Guia Rápido - ML Pipeline

Guia prático para usar o pipeline de treinamento automatizado de modelos ML.

📋 Pré-requisitos

Docker e Docker Swarm configurados
ClickHouse rodando no stack 4c
Python 3.11+ (opcional, para execução local)

🎯 Quick Start

1. Verificar Dados Disponíveis

cd scripts/ml_pipeline
./quick_start.sh

Ou manualmente:

docker run --rm \
    --network superbot-swarm-network \
    -v $(pwd):/app -w /app \
    -e CLICKHOUSE_HOST=clickhouse \
    python:3.11-slim \
    sh -c "pip install clickhouse-connect -q && python check_data_availability.py"

2. Extrair Dados

# Via script helper
./run_extraction_docker.sh intent 2025-11-01 2025-12-01

# Ou manualmente
docker run --rm \
    --network superbot-swarm-network \
    -v $(pwd):/app -w /app \
    -e CLICKHOUSE_HOST=clickhouse \
    python:3.11-slim \
    sh -c "pip install clickhouse-connect pandas pyarrow -q && \
           python extract_training_data.py \
               --model intent \
               --start-date 2025-11-01 \
               --end-date 2025-12-01"

3. Treinar Modelo

python train_model.py \
    --model intent \
    --dataset data/training/intent_20251206.parquet \
    --output models/intent/v20251206_120000

4. Avaliar Modelo

python evaluate_model.py \
    --model-path models/intent/v20251206_120000 \
    --baseline models/intent/v20251201_100000 \
    --test-dataset data/training/intent_20251206.parquet

5. Deploy Modelo

# Deploy completo
python deploy_model.py \
    --model-path models/intent/v20251206_120000 \
    --strategy full

# Deploy canary (10%)
python deploy_model.py \
    --model-path models/intent/v20251206_120000 \
    --strategy canary \
    --percentage 10

📊 Modelos Disponíveis

intent - Modelo de intenção do cliente
offer - Modelo de oferta (Learning-to-Rank)
channel - Modelo de canal de comunicação
timing - Modelo de timing (hora certa)

🔧 Troubleshooting

Erro: "clickhouse-connect não instalado"

pip install -r requirements.txt

Erro: "Não foi possível conectar ao ClickHouse"

O script precisa rodar dentro da rede Docker Swarm. Use:

./run_extraction_docker.sh <modelo> <start-date> <end-date>

Ou execute via Docker:

docker run --rm --network superbot-swarm-network ...

Erro: "0 registros retornados"

Verifique se há dados no período:

python check_data_availability.py

Ajuste as datas para um período com dados disponíveis.

📁 Estrutura de Arquivos

scripts/ml_pipeline/
├── extract_training_data.py    # Extração de dados
├── train_model.py               # Treinamento
├── evaluate_model.py            # Avaliação
├── deploy_model.py              # Deploy
├── check_data_availability.py   # Verificar dados
├── run_extraction_docker.sh     # Helper Docker
├── quick_start.sh               # Quick start
└── data/
    └── training/                # Datasets extraídos

🎯 Pipeline Completo

Para executar o pipeline completo (todos os modelos):

python train_all.py \
    --start-date 2025-11-01 \
    --end-date 2025-12-01 \
    --auto-deploy

📚 Próximos Passos

Integrar com Model Registry - Registrar modelos automaticamente
Configurar S3 - Armazenar modelos e datasets no S3
Agendar Treinamento - Configurar cron job ou scheduler
Monitorar Drift - Configurar monitoramento contínuo

Ml Pipeline Guia Rapido