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

Qual é o erro de ML mais comum?

Treinar pré-processadores no conjunto de dados completo antes de dividir.
Infla as pontuações da CV e do teste; o modelo falha em produção com novos dados.
Corrija com Pipeline e ordem de divisão adequada.

Quando posso tocar no conjunto de teste?

Uma vez, após todas as decisões de modelagem estarem finais.
Para uma única estimativa de generalização imparcial.
Se você o ajustou, obtenha um novo conjunto de teste.

Eu sempre preciso de validação cruzada?

Sim para comparação de modelos e busca de hiperparâmetros em conjuntos de dados com menos de 100 mil linhas.
Divisão única é aceitável para dados muito grandes com métricas estáveis.

Modelos de árvore devem usar escalonamento?

Não - random forest e boosting são invariantes à escala.
Ainda codifique categorias e lide com valores ausentes.

Como evito que experimentos em notebooks divirjam?

Mova o código de treinamento para scripts ou módulos.
Use random_state, dependências fixadas e rastreamento de experimentos.
Revise notebooks em busca de células que processam todos os dados.

O que deve constar em um model card?

Descrição dos dados de treinamento, métricas, limitações e riscos de viés.
Lista de features, etapas de pré-processamento e casos de uso pretendidos.
Versão do sklearn e hash do snapshot dos dados.

Quando o SMOTE é seguro?

Dentro do imblearn.pipeline.Pipeline após a divisão de treino.
Em features numéricas densas com desbalanceamento moderado.
Nunca no conjunto de teste.

Como reviso o PR de ML de um colega?

Verifique a ordem da divisão, o uso do pipeline e a escolha da métrica.
Verifique se o conjunto de teste não é usado no ajuste.
Execute o script de treinamento dele e compare as métricas.

Qual é a estrutura mínima viável de um projeto de ML?

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

Quando devo passar de sklearn para deep learning?

Quando os dados são imagens, áudio, texto ou sequências longas.
Dados tabulares com menos de 100 mil linhas raramente se beneficiam de redes neurais.
Tente gradient boosting primeiro em dados estruturados.

Com que frequência devo retreinar?

Quando o monitoramento detecta drift de dados ou degradação de métricas.
Em um cronograma que corresponda à velocidade com que o mundo muda.
Não a cada nova linha - o retreinamento em lote geralmente é suficiente.

Que testes o código de inferência deve ter?

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

Teste de fumaça com um par de entrada-saída conhecido.
Afirme que os nomes das colunas correspondem ao esquema de treinamento.

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

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

Qual é o erro de ML mais comum?

Treinar pré-processadores no conjunto de dados completo antes de dividir.
Infla as pontuações da CV e do teste; o modelo falha em produção com novos dados.
Corrija com Pipeline e ordem de divisão adequada.

Quando posso tocar no conjunto de teste?

Uma vez, após todas as decisões de modelagem estarem finais.
Para uma única estimativa de generalização imparcial.
Se você o ajustou, obtenha um novo conjunto de teste.

Eu sempre preciso de validação cruzada?

Sim para comparação de modelos e busca de hiperparâmetros em conjuntos de dados com menos de 100 mil linhas.
Divisão única é aceitável para dados muito grandes com métricas estáveis.

Modelos de árvore devem usar escalonamento?

Não - random forest e boosting são invariantes à escala.
Ainda codifique categorias e lide com valores ausentes.

Como evito que experimentos em notebooks divirjam?

Mova o código de treinamento para scripts ou módulos.
Use random_state, dependências fixadas e rastreamento de experimentos.
Revise notebooks em busca de células que processam todos os dados.

O que deve constar em um model card?

Descrição dos dados de treinamento, métricas, limitações e riscos de viés.
Lista de features, etapas de pré-processamento e casos de uso pretendidos.
Versão do sklearn e hash do snapshot dos dados.

Quando o SMOTE é seguro?

Dentro do imblearn.pipeline.Pipeline após a divisão de treino.
Em features numéricas densas com desbalanceamento moderado.
Nunca no conjunto de teste.

Como reviso o PR de ML de um colega?

Verifique a ordem da divisão, o uso do pipeline e a escolha da métrica.
Verifique se o conjunto de teste não é usado no ajuste.
Execute o script de treinamento dele e compare as métricas.

Qual é a estrutura mínima viável de um projeto de ML?

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

Quando devo passar de sklearn para deep learning?

Quando os dados são imagens, áudio, texto ou sequências longas.
Dados tabulares com menos de 100 mil linhas raramente se beneficiam de redes neurais.
Tente gradient boosting primeiro em dados estruturados.

Com que frequência devo retreinar?

Quando o monitoramento detecta drift de dados ou degradação de métricas.
Em um cronograma que corresponda à velocidade com que o mundo muda.
Não a cada nova linha - o retreinamento em lote geralmente é suficiente.

Que testes o código de inferência deve ter?

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

Teste de fumaça com um par de entrada-saída conhecido.
Afirme que os nomes das colunas correspondem ao esquema de treinamento.

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

Boas Práticas de Machine Learning

Buscar na documentação

Boas Práticas de Machine Learning