Boas Práticas de Machine Learning

Uma lista de verificação de regras para construir modelos clássicos de ML reproduzíveis e livres de vazamentos. Revise-a antes de cada execução de treinamento e durante a revisão de código.

Como Usar Esta Lista

• Aplique as regras A-C antes de escrever o código de treinamento.
• As regras D-F regem a avaliação e a seleção do modelo.
• As regras G-H cobrem a implantação e a manutenção.
• Revise após cada alteração no esquema de dados ou nova fonte de features.

A - Higiene de Dados

• Divida os dados antes do pré-processamento. Ajuste escaladores, codificadores e seletores de features apenas nos folds de treinamento - nunca no conjunto de dados completo ou no conjunto de teste.
• Bloqueie um conjunto de teste reservado. Toque nele uma vez para avaliação final após todas as decisões de modelo e hiperparâmetros terem sido tomadas.
• Use divisões estratificadas para classificação. Preserve as proporções de classes quando qualquer classe for inferior a 10% das linhas.
• Divida por grupo para entidades repetidas. Use GroupKFold quando várias linhas compartilham um ID de usuário, paciente ou sessão.
• Documente a proveniência dos dados. Registre a fonte, data de extração, filtros aplicados e contagens de linhas em um log de experimentos.

B - Engenharia de Features

• Exclua colunas pós-resultado. Remova features que só são conhecidas após o alvo da previsão (vazamento).
• Empacote transformações em um Pipeline. Agrupe o pré-processamento com o modelo para que a CV e a implantação apliquem etapas idênticas.
• Lide com categorias desconhecidas na inferência. Use OneHotEncoder(handle_unknown="ignore") ou suporte categórico nativo em bibliotecas de boosting.
• Impute antes de escalar. Valores ausentes devem ser preenchidos antes de StandardScaler ou modelos baseados em distância.
• Forçe a ordem das colunas na inferência. Passe X[colunas_esperadas] antes de predict para evitar desalinhamento silencioso.

C - Modelagem

• Comece com um baseline simples. Regressão logística ou random forest antes de gradient boosting ou deep learning.
• Defina seeds aleatórias em todos os lugares. random_state=42 em divisões, modelos e buscas para experimentos reproduzíveis.
• Combine algoritmos com o tipo de problema. Métricas de regressão para alvos contínuos; métricas de classificação para categorias.
• Use pesos de classe ou SMOTE para desbalanceamento. Não confie na acurácia quando a classe positiva é rara.
• Serialize o pipeline completo. joblib.dump(pipe, ...) - não apenas a etapa do classificador.

D - Avaliação

• Escolha métricas alinhadas com o custo de negócio. PR-AUC para positivos raros; MAE para erros de regressão interpretáveis.
• Ajuste limiares nos dados de validação. O padrão 0.5 raramente é ótimo para classificação desbalanceada.
• Relate métricas por classe. Um único F1 ou acurácia esconde falhas em classes minoritárias.
• Compare com o baseline. Todo novo modelo deve superar o benchmark simples para justificar a complexidade.
• Verifique a lacuna entre treino e teste. Uma grande lacuna sinaliza overfitting - reduza a capacidade ou adicione regularização.

E - Ajuste de Hiperparâmetros

• Busque dentro da validação cruzada. Nunca escolha hiperparâmetros usando o desempenho do conjunto de teste.
• Combine a pontuação com a métrica de implantação. Otimize f1, roc_auc ou neg_mean_absolute_error - não a acurácia padrão.
• Limite o orçamento de busca. Use poda do Optuna ou busca aleatória em vez de grids exaustivos em 5+ parâmetros.
• Registre cada tentativa. Grave parâmetros, pontuação da CV, duração e versão dos dados para auditabilidade.

F - Reprodutibilidade

• Fixe as versões dos pacotes. Registre as versões do scikit-learn, pandas e bibliotecas de boosting nos metadados do artefato.
• Versionamento dos dados de treinamento. Crie um hash do conjunto de treinamento ou use DVC para vincular modelos a snapshots exatos dos dados.
• Rastreie experimentos. Registre parâmetros, métricas e artefatos em MLflow, W&B ou um sistema equivalente.
• Escreva testes para inferência. Afirme que pipe.predict(sample) retorna a forma e o dtype esperados.

FAQs

projeto/
  data/           # raw e processado (gitignored ou DVC)
  src/train.py    # script de treinamento
  src/predict.py  # ponto de entrada de inferência
  models/         # pipelines serializados
  tests/          # testes de fumaça de inferência

def test_pipeline_predicts(sample_row):
    pred = pipe.predict(sample_row)
    assert pred.shape == (1,)

Relacionados

• Pipelines - pré-processamento livre de vazamentos
• Datasets & Splits - estratégias adequadas de divisão
• Avaliação de Modelos - seleção de métricas
• Rastreamento de Experimentos - registro de execuções
• Monitoramento e Drift - saúde em produção

Versões da Stack: Esta página foi escrita para Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ e uv 0.6+.