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 GridSearchCV, train_test_split
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import OneHotEncoder, StandardScaler
 
df = pd.read_csv("customers.csv")  # colunas: age, tenure, region, plan, churned
X = df.drop(columns=["churned"])
y = df["churned"]
 
num_cols, cat_cols = ["age", "tenure"], ["region", "plan"]
preprocessor = ColumnTransformer([
    ("num", StandardScaler(), num_cols),
    ("cat", OneHotEncoder(handle_unknown="ignore"), cat_cols),
])
 
pipe = Pipeline([
    ("prep", preprocessor),
    ("clf", RandomForestClassifier(random_state=42)),
])
 
param_grid = {
    "clf__n_estimators": [100, 200],
    "clf__max_depth": [None, 10],
}
 
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, stratify=y, random_state=42)
search = GridSearchCV(pipe, param_grid, cv=5, scoring="f1")
search.fit(X_train, y_train)
 
best = search.best_estimator_
print("melhores parâmetros:", search.best_params_)
print("F1 de teste:", f1_score(y_test, best.predict(X_test)))
 
joblib.dump(best, "churn_pipeline.joblib")

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

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
pipe.named_steps["clf"].feature_importances_

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

FAQs

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

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 np.log1p(X)

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

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

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