Pipelines

O Pipeline do sklearn encadeia etapas de pré-processamento e estimadores em um único objeto que se ajusta, prevê e serializa em conjunto. Pipelines são a maneira padrão de manter o treinamento e a inferência reproduzíveis e sem vazamentos.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.linear_model import LogisticRegression
 
pipe = Pipeline([
    ("scaler", StandardScaler()),
    ("clf", LogisticRegression(max_iter=1000)),
])
pipe.fit(X_train, y_train)
preds = pipe.predict(X_test)

Quando usar isso:

Qualquer projeto com pré-processamento mais um modelo (escalonamento, codificação, imputação).
Validação cruzada ou busca em grade onde as transformações devem ser reajustadas por dobra.
Implantação de modelos onde a inferência deve aplicar o mesmo pré-processamento do treinamento.
Combinação de múltiplos ramos de transformação com FeatureUnion.

Exemplo de Trabalho

"""pipelines.py - pipeline de ponta a ponta com ColumnTransformer e busca em grade."""
from __future__ import annotations
 
import joblib
import pandas as pd
from sklearn.compose import ColumnTransformer
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import f1_score
from sklearn.model_selection import

O que isso demonstra:

Pré-processamento e classificador como um único objeto estimável.
Busca de hiperparâmetros com parâmetros prefixados pela etapa (clf__n_estimators).
CV reajusta o pré-processador dentro de cada dobra automaticamente.
Pipeline completo persistido para pré-processamento de inferência idêntico.

Mergulho Profundo

Como Funciona

Cada etapa é uma tupla (nome, transformador); a etapa final deve ser um estimador.
fit chama fit_transform em etapas intermediárias e fit na última etapa.
predict executa transform em todas as etapas, exceto a última, e depois predict.
Pipeline implementa a interface de estimador do sklearn - funciona com CV, busca em grade e ensembles.
Pipelines aninhados (por exemplo, sub-pipeline numérico dentro de ColumnTransformer) compõem-se de forma limpa.

Pipeline vs. Etapas Manuais

Abordagem	Risco de Vazamento	Implantação	Compatível com CV
`fit`/`transform` manual	Alto	Propenso a erros	Não
`Pipeline`	Baixo	Artefato único	Sim
Células de Notebook	Alto	Não reproduzível	Não

Notas de Python

from sklearn.pipeline import FeatureUnion
 
combined = FeatureUnion([
    ("pca", PCA(n_components=10)),
    ("raw", "passthrough"),
])
pipe = Pipeline([("features", combined), ("clf", SVC())])
 
# Acessa etapas por nome

Armadilhas

Esquecer de pipeline o pré-processamento - scaler.fit(X_train) manual e depois model.fit(X_train_scaled) quebra sob CV. Correção: envolva ambos em Pipeline.
Prefixo incorreto de parâmetro de etapa - n_estimators em vez de clf__n_estimators na busca em grade ignora silenciosamente os parâmetros. Correção: use pipe.get_params().keys() para verificar os nomes.
Salvar apenas o modelo - carregar um classificador nu sem o escalonador produz previsões incorretas. Correção: joblib.dump(pipe, ...) o pipeline completo.
Padrão mutável em FunctionTransformer - lambdas e closures podem não ser serializáveis. Correção: use funções em nível de módulo ou sklearn.preprocessing.FunctionTransformer.
Última etapa não é um estimador - pipelines que terminam em um transformador não podem predict. Correção: termine com um classificador/regressor ou use TransformedTargetRegressor.
Incompatibilidade da ordem das colunas na inferência - colunas do pandas reordenadas entre treinamento e implantação. Correção: force a ordem das colunas com X[expected_cols] antes de predict.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
`Pipeline`	Fluxos de trabalho padrão do sklearn	Loops personalizados de deep learning (use módulos PyTorch)
`imblearn.pipeline.Pipeline`	Reamostragem dentro do CV	Ausência de desequilíbrio de classes
`fit`/`transform` manual do sklearn	Ensino/depuração de uma etapa	Fluxos de trabalho de produção ou CV
`sklearn.set_output(transform="pandas")`	Necessidade de saída DataFrame de transformações	Puro numpy downstream

FAQs

Por que não posso simplesmente escalar os dados uma vez antes do CV?

O escalonamento global usa estatísticas das linhas da dobra de validação.
O Pipeline reajusta o escalonador em cada dobra de treinamento apenas.
Esta é a fonte mais comum de pontuações infladas de CV.

Como acesso o modelo ajustado dentro de um pipeline?

fitted_clf = pipe.named_steps["clf"]
importances = fitted_clf.feature_importances_

named_steps é um dicionário indexado pelo nome da etapa.

Pipelines podem lidar com pesos de amostra?

Passe pipe.fit(X, y, clf__sample_weight=weights).
O prefixo corresponde ao nome da etapa do estimador.
Nem todos os transformadores suportam pesos de amostra.

Como adiciono etapas de transformação personalizadas?

from sklearn.base import BaseEstimator, TransformerMixin
 
class Log1pTransformer(BaseEstimator, TransformerMixin):
    def fit(self, X, y=None):
        return self
    def transform(self, X):
        import numpy as np
        return

O que é FeatureUnion?

Executa múltiplas transformações em paralelo e concatena as saídas.
Útil para combinar características de texto TF-IDF com características numéricas.
Diferente de ColumnTransformer, que seleciona colunas por ramo.

Como depuro uma etapa de pipeline?

Xt = pipe.named_steps["prep"].transform(X_train[:5])
print(Xt.shape, Xt[:2])

Inspecione a saída intermediária chamando transform em etapas individuais após o ajuste.

Pipelines funcionam com DataFrames do pandas?

Sim, quando os transformadores aceitam DataFrames (ColumnTransformer, versões recentes do sklearn).
Defina transform_output="pandas" em ColumnTransformer para colunas nomeadas.

Como versiono artefatos de pipeline?

Salve com joblib.dump incluindo metadados JSON (data de treinamento, hash de dados, métricas).
Registre no MLflow ou em um registro de modelos para fluxos de trabalho de promoção.
Veja Rastreamento de Experimentos.

Posso usar pipelines com XGBoost ou LightGBM?

Sim - envolva xgboost.XGBClassifier como a etapa final do pipeline.
As etapas de pré-processamento permanecem transformadores do sklearn.
Use o pipeline imblearn se combinar com SMOTE.

E a transformação do alvo?

from sklearn.compose import TransformedTargetRegressor
model = TransformedTargetRegressor(regressor=pipe, func=np.log1p, inverse_func=np.expm1)

Transforma logaritmicamente alvos distorcidos, mantendo as previsões na escala original.

Como excluo uma etapa durante a previsão?

Use Pipeline(memory=...) para cache de transformações caras durante a busca em grade.
Para etapas condicionais, considere pipelines separados por caso de uso.

Como os pipelines interagem com a exportação ONNX?

Pipelines do sklearn convertem via skl2onnx quando todas as etapas são suportadas.
Transformadores personalizados complexos podem bloquear a conversão - teste cedo.

Relacionados

Engenharia de Features - Padrões de ColumnTransformer
Datasets e Divisões - CV com pipelines
Ajuste de Hiperparâmetros - prefixos de parâmetros de busca em grade
Implantação com FastAPI - carregando artefatos de pipeline
Melhores Práticas de Machine Learning - regras de reprodutibilidade

Versões da Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 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+.

Buscar na documentação

Pipelines