scikit-learn 完全指南

官方文档：https://scikit-learn.org/stable/
适用版本：scikit-learn 1.8.0（2026-05-07 核实）

概述

scikit-learn 是 Python 最成熟的机器学习库，提供监督学习、无监督学习、模型选择与评估的完整工具链，所有算法遵循统一的 fit/predict/transform 接口。

与其他框架的对比：

适合场景：结构化（表格）数据的分类、回归、聚类；需要快速建立 baseline；特征工程 Pipeline 构建；模型选择与超参调优。

不适合场景：图像/音频/文本深度学习（用 PyTorch完全指南 或 HuggingFace Transformers完全指南）；超大规模分布式训练。

安装

pip install scikit-learn

核心设计：Estimator 接口

所有 scikit-learn 对象实现统一接口：

数据预处理（sklearn.preprocessing）

StandardScaler

零均值、单位方差标准化（Z-score）。

from sklearn.preprocessing import StandardScaler

scaler = StandardScaler(copy=True, with_mean=True, with_std=True)

from sklearn.preprocessing import StandardScaler

X_train = [[0, 0], [0, 0], [1, 1], [1, 1]]
scaler = StandardScaler()
scaler.fit(X_train)
# 务必只在训练集上 fit，测试集只做 transform
X_test = scaler.transform([[2, 2], [-1, -1]])
print(scaler.mean_)    # [0.5 0.5]
print(scaler.scale_)   # [0.5 0.5]

MinMaxScaler

将特征缩放到指定范围 [feature_range[0], feature_range[1]]。

from sklearn.preprocessing import MinMaxScaler

scaler = MinMaxScaler(feature_range=(0, 1), copy=True, clip=False)

OneHotEncoder

将类别特征编码为 one-hot 矩阵。

from sklearn.preprocessing import OneHotEncoder

enc = OneHotEncoder(
    categories='auto',
    drop=None,
    sparse_output=True,
    dtype=float,
    handle_unknown='error',
    min_frequency=None,
    max_categories=None,
)

from sklearn.preprocessing import OneHotEncoder
import numpy as np

enc = OneHotEncoder(sparse_output=False, handle_unknown='ignore')
X = [['cat'], ['dog'], ['fish']]
enc.fit(X)

# 测试集有未见类别 'bird'，handle_unknown='ignore' 输出全零
print(enc.transform([['dog'], ['bird']]))
# [[0. 1. 0.]
#  [0. 0. 0.]]

LabelEncoder

对目标变量（y）的类别进行整数编码。

from sklearn.preprocessing import LabelEncoder

le = LabelEncoder()
le.fit(['cat', 'dog', 'fish'])
print(le.transform(['dog', 'cat']))  # [1 0]
print(le.inverse_transform([2]))     # ['fish']

LabelEncoder 无超参数，不应用于输入特征（用 OrdinalEncoder 代替）。

PolynomialFeatures

生成多项式特征，用于线性模型捕捉非线性关系。

from sklearn.preprocessing import PolynomialFeatures

poly = PolynomialFeatures(degree=2, interaction_only=False, include_bias=True, order='C')

线性模型（sklearn.linear_model）

LogisticRegression

逻辑回归分类器，适合线性可分的二分类和多分类问题。

from sklearn.linear_model import LogisticRegression

clf = LogisticRegression(
    penalty='l2',
    dual=False,
    tol=1e-4,
    C=1.0,
    fit_intercept=True,
    intercept_scaling=1,
    class_weight=None,
    random_state=None,
    solver='lbfgs',
    max_iter=100,
    multi_class='deprecated',
    verbose=0,
    warm_start=False,
    n_jobs=None,
    l1_ratio=None,
)

from sklearn.linear_model import LogisticRegression
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split

X, y = load_iris(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

clf = LogisticRegression(max_iter=1000, C=0.1)
clf.fit(X_train, y_train)
print(clf.score(X_test, y_test))        # accuracy
print(clf.predict_proba(X_test[:2]))   # 概率矩阵

LinearRegression

最小二乘线性回归。

from sklearn.linear_model import LinearRegression

reg = LinearRegression(fit_intercept=True, copy_X=True, n_jobs=None, positive=False)

Ridge

L2 正则化线性回归（岭回归）。

from sklearn.linear_model import Ridge

reg = Ridge(alpha=1.0, fit_intercept=True, copy_X=True, max_iter=None,
            tol=1e-4, solver='auto', positive=False, random_state=None)

Lasso

L1 正则化线性回归（Lasso），产生稀疏解（特征选择）。

from sklearn.linear_model import Lasso

reg = Lasso(alpha=1.0, fit_intercept=True, precompute=False, copy_X=True,
            max_iter=1000, tol=1e-4, warm_start=False, positive=False,
            random_state=None, selection='cyclic')

集成方法（sklearn.ensemble）

RandomForestClassifier

随机森林：并行训练多棵决策树，以投票方式聚合结果。

from sklearn.ensemble import RandomForestClassifier

clf = RandomForestClassifier(
    n_estimators=100,
    criterion='gini',
    max_depth=None,
    min_samples_split=2,
    min_samples_leaf=1,
    min_weight_fraction_leaf=0.0,
    max_features='sqrt',
    max_leaf_nodes=None,
    min_impurity_decrease=0.0,
    bootstrap=True,
    oob_score=False,
    n_jobs=None,
    random_state=None,
    verbose=0,
    warm_start=False,
    class_weight=None,
    ccp_alpha=0.0,
    max_samples=None,
    monotonic_cst=None,
)

GradientBoostingClassifier

梯度提升：顺序训练，每棵树拟合前一棵的残差。准确率通常高于随机森林，但训练慢。

from sklearn.ensemble import GradientBoostingClassifier

clf = GradientBoostingClassifier(
    loss='log_loss',
    learning_rate=0.1,
    n_estimators=100,
    subsample=1.0,
    criterion='friedman_mse',
    min_samples_split=2,
    min_samples_leaf=1,
    min_weight_fraction_leaf=0.0,
    max_depth=3,
    min_impurity_decrease=0.0,
    init=None,
    random_state=None,
    max_features=None,
    verbose=0,
    max_leaf_nodes=None,
    warm_start=False,
    validation_fraction=0.1,
    n_iter_no_change=None,
    tol=1e-4,
    ccp_alpha=0.0,
)

支持向量机（sklearn.svm）

SVC

支持向量机分类，适合高维、小数据集的分类问题。

from sklearn.svm import SVC

clf = SVC(
    C=1.0,
    kernel='rbf',
    degree=3,
    gamma='scale',
    coef0=0.0,
    shrinking=True,
    probability=False,
    tol=1e-3,
    cache_size=200,
    class_weight=None,
    verbose=False,
    max_iter=-1,
    decision_function_shape='ovr',
    break_ties=False,
    random_state=None,
)

聚类（sklearn.cluster）

KMeans

K-均值聚类，将数据分为 K 个簇。

from sklearn.cluster import KMeans

km = KMeans(
    n_clusters=8,
    init='k-means++',
    n_init='auto',
    max_iter=300,
    tol=1e-4,
    verbose=0,
    random_state=None,
    copy_x=True,
    algorithm='lloyd',
)

from sklearn.cluster import KMeans
import numpy as np

X = np.array([[1, 2], [1, 4], [1, 0], [10, 2], [10, 4], [10, 0]])
km = KMeans(n_clusters=2, random_state=42, n_init=10)
km.fit(X)
print(km.labels_)         # 每个样本的簇标签
print(km.cluster_centers_) # 簇中心坐标
print(km.inertia_)         # 误差平方和（越小越好）

DBSCAN

基于密度的聚类，不需要预先指定 K，能发现任意形状的簇并识别噪声点。

from sklearn.cluster import DBSCAN

db = DBSCAN(
    eps=0.5,
    min_samples=5,
    metric='euclidean',
    metric_params=None,
    algorithm='auto',
    leaf_size=30,
    p=None,
    n_jobs=None,
)

DBSCAN 的标签中 -1 表示噪声点（不属于任何簇）。

模型选择（sklearn.model_selection）

train_test_split

将数组或矩阵按比例随机分为训练集和测试集。

from sklearn.model_selection import train_test_split

X_train, X_test, y_train, y_test = train_test_split(
    *arrays,
    test_size=None,
    train_size=None,
    random_state=None,
    shuffle=True,
    stratify=None,
)

cross_val_score

K 折交叉验证，返回每折的评分数组。

from sklearn.model_selection import cross_val_score

scores = cross_val_score(
    estimator,
    X,
    y=None,
    groups=None,
    scoring=None,
    cv=5,
    n_jobs=None,
    verbose=0,
    fit_params=None,
    params=None,
    pre_dispatch='2*n_jobs',
    error_score=nan,
)

from sklearn.model_selection import cross_val_score
from sklearn.linear_model import LogisticRegression
from sklearn.datasets import load_iris

X, y = load_iris(return_X_y=True)
clf = LogisticRegression(max_iter=1000)
scores = cross_val_score(clf, X, y, cv=5, scoring='accuracy')
print(f"Accuracy: {scores.mean():.3f} ± {scores.std():.3f}")

GridSearchCV

穷举超参数网格，用交叉验证选最优参数组合。

from sklearn.model_selection import GridSearchCV

search = GridSearchCV(
    estimator,
    param_grid,
    scoring=None,
    n_jobs=None,
    refit=True,
    cv=5,
    verbose=0,
    pre_dispatch='2*n_jobs',
    error_score=nan,
    return_train_score=False,
)

from sklearn.model_selection import GridSearchCV
from sklearn.ensemble import RandomForestClassifier
from sklearn.datasets import load_iris

X, y = load_iris(return_X_y=True)
param_grid = {
    'n_estimators': [50, 100, 200],
    'max_depth': [None, 3, 5],
}
search = GridSearchCV(
    RandomForestClassifier(random_state=42),
    param_grid,
    cv=5,
    scoring='accuracy',
    n_jobs=-1,
)
search.fit(X, y)
print(search.best_params_)   # {'max_depth': None, 'n_estimators': 100}
print(search.best_score_)    # 0.973...
# search.best_estimator_ 是已用全量数据重训的最优模型

RandomizedSearchCV

随机采样超参数空间，比 GridSearchCV 更高效（适合大参数空间）。

from sklearn.model_selection import RandomizedSearchCV

search = RandomizedSearchCV(
    estimator,
    param_distributions,
    n_iter=10,
    scoring=None,
    n_jobs=None,
    refit=True,
    cv=5,
    verbose=0,
    pre_dispatch='2*n_jobs',
    random_state=None,
    error_score=nan,
    return_train_score=False,
)

Pipeline（sklearn.pipeline）

Pipeline

将多个预处理步骤和最终估计器串联，避免数据泄漏（fit_transform 仅在训练集执行）。

from sklearn.pipeline import Pipeline

pipe = Pipeline(steps, memory=None, verbose=False)

访问步骤：pipe['scaler'] 或 pipe.named_steps['scaler']。

超参数路径：pipe.set_params(classifier__C=0.1)（stepname__param 格式）。

from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import GridSearchCV
from sklearn.datasets import load_breast_cancer

X, y = load_breast_cancer(return_X_y=True)

# Pipeline 防止数据泄漏：Scaler 只在训练折 fit
pipe = Pipeline([
    ('scaler', StandardScaler()),
    ('clf', LogisticRegression(max_iter=1000)),
])

# 通过 __ 分隔符访问 Pipeline 内的超参数
param_grid = {
    'clf__C': [0.01, 0.1, 1, 10],
    'clf__penalty': ['l2'],
}
grid = GridSearchCV(pipe, param_grid, cv=5, n_jobs=-1)
grid.fit(X, y)
print(grid.best_params_)

评估指标（sklearn.metrics）

分类指标

from sklearn.metrics import (
    accuracy_score, precision_score, recall_score, f1_score,
    confusion_matrix, classification_report, roc_auc_score
)

# 二分类
y_true = [0, 1, 1, 0, 1]
y_pred = [0, 1, 0, 0, 1]

print(accuracy_score(y_true, y_pred))                    # 0.8
print(precision_score(y_true, y_pred))                   # 1.0
print(recall_score(y_true, y_pred))                      # 0.667
print(f1_score(y_true, y_pred))                          # 0.8
print(confusion_matrix(y_true, y_pred))
# [[2 0]
#  [1 2]]
print(classification_report(y_true, y_pred))             # 多指标汇总

average 参数说明（多分类时必须指定）：

回归指标

from sklearn.metrics import mean_squared_error, mean_absolute_error, r2_score

y_true = [3, -0.5, 2, 7]
y_pred = [2.5, 0.0, 2, 8]

print(mean_squared_error(y_true, y_pred))        # MSE = 0.375
print(mean_absolute_error(y_true, y_pred))       # MAE = 0.5
print(r2_score(y_true, y_pred))                  # R² = 0.948

完整示例：端到端 ML 工作流

import numpy as np
from sklearn.datasets import load_breast_cancer
from sklearn.model_selection import train_test_split, GridSearchCV
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import classification_report, roc_auc_score

# 加载数据
X, y = load_breast_cancer(return_X_y=True)
print(f"Samples: {X.shape[0]}, Features: {X.shape[1]}, Classes: {np.unique(y)}")

# 分层划分训练/测试集（保证类别比例相同）
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=42, stratify=y
)

# 构建 Pipeline（Scaler 只在训练折 fit，防止数据泄漏）
pipe = Pipeline([
    ('scaler', StandardScaler()),
    ('clf', RandomForestClassifier(random_state=42)),
])

# 超参数搜索
param_grid = {
    'clf__n_estimators': [100, 200],
    'clf__max_depth': [None, 5, 10],
    'clf__min_samples_leaf': [1, 2],
}
grid = GridSearchCV(pipe, param_grid, cv=5, scoring='roc_auc', n_jobs=-1, verbose=1)
grid.fit(X_train, y_train)

print(f"Best params: {grid.best_params_}")
print(f"CV ROC AUC: {grid.best_score_:.4f}")

# 测试集评估
y_pred = grid.predict(X_test)
y_prob = grid.predict_proba(X_test)[:, 1]

print(classification_report(y_test, y_pred, target_names=['malignant', 'benign']))
print(f"Test ROC AUC: {roc_auc_score(y_test, y_prob):.4f}")

# 特征重要性（从 Pipeline 中取出 clf）
importances = grid.best_estimator_['clf'].feature_importances_
top_features = np.argsort(importances)[-5:][::-1]
print("Top 5 features:", top_features)

最佳实践

始终在 Pipeline 内做预处理，而非手动拆分： 在 Pipeline 外对整个数据集做 fit_transform，再分训练测试集，会导致测试集信息泄漏到 Scaler 中，使评估结果过于乐观。

# 错误：先 fit scaler 再分割，测试集信息泄漏
scaler = StandardScaler()
X_scaled = scaler.fit_transform(X)  # 使用了测试集的均值/方差
X_train, X_test = train_test_split(X_scaled)

# 正确：先分割，再在 Pipeline 内 fit
X_train, X_test = train_test_split(X)
pipe = Pipeline([('scaler', StandardScaler()), ('clf', clf)])
pipe.fit(X_train, y_train)
pipe.predict(X_test)

固定 random_state 保证可复现性： 所有带随机性的操作（分割、模型初始化）都传入 random_state=42，确保实验结果可复现和对比。

类别不平衡时用分层抽样和合适指标： 不平衡数据集上 accuracy 是误导性指标，应用 ROC AUC、F1-macro 或 PR AUC；train_test_split(stratify=y) 保证训练/测试集类别比例一致。

用 cross_val_score 代替单次 train/test 分割评估： 单次分割结果受随机种子影响大，K 折交叉验证的均值 ± 标准差更可靠。

超参数调优优先用 RandomizedSearchCV 再细化： 参数空间大时（>30 个组合），先用 RandomizedSearchCV 找到大致区间，再用 GridSearchCV 在小范围精调，比直接全网格搜索节省 90% 时间。

使用 joblib.dump/load 持久化 Pipeline： 保存的 Pipeline 含 Scaler 参数，部署时直接 load 即可预测，无需重新 fit。

import joblib

joblib.dump(grid.best_estimator_, 'model.pkl')
model = joblib.load('model.pkl')
model.predict(X_test)

常见陷阱

陷阱：测试集泄漏到预处理步骤

现象： 交叉验证或测试集分数比实际部署效果好得多。

原因： 在 Pipeline 外对全量数据做了 fit_transform，导致 Scaler 的统计量包含了测试集的信息，测试集相当于被"见过"了。

解决： 所有预处理必须放进 Pipeline，只调用 Pipeline.fit(X_train) 和 Pipeline.transform(X_test)。

陷阱：GridSearchCV 内外套了不必要的 Scaler

现象： Pipeline 内已有 Scaler，外部又手动对全量数据做了归一化，导致双重标准化（零均值数据再次标准化后变形）。

原因： 不清楚 Pipeline 内部已经做了预处理。

解决： 检查 Pipeline 内已有的步骤，外部不要再做重复预处理。

陷阱：类别特征使用了 LabelEncoder

现象： 模型对类别特征赋予了大小关系（如 cat=0 < dog=1 < fish=2），线性模型或神经网络效果差。

原因： LabelEncoder 产生有序整数，暗示了不存在的大小关系；它只应用于目标变量 y，不应用于输入特征 X。

解决： 输入特征的类别编码使用 OneHotEncoder 或 OrdinalEncoder（仅当类别本身有序时）。

from sklearn.preprocessing import OrdinalEncoder, OneHotEncoder

# 错误：对类别特征用 LabelEncoder（产生错误的有序关系）
le = LabelEncoder()
X[:, 0] = le.fit_transform(X[:, 0])

# 正确：用 OneHotEncoder 在 Pipeline 内处理
pipe = Pipeline([
    ('enc', OneHotEncoder(handle_unknown='ignore')),
    ('clf', LogisticRegression()),
])

陷阱：max_iter 不足导致 ConvergenceWarning

现象： 输出 ConvergenceWarning: Lbfgs failed to converge，但模型看起来还能用。

原因： 求解器在 max_iter 次迭代内没有达到收敛条件，参数优化未完成，模型是次优解。

解决： 增大 max_iter（从 100 → 1000 → 10000），或先对数据做 StandardScaler 加速收敛，或换 solver。

参见

• PyTorch完全指南 — 深度学习，处理图像/文本/序列数据
• HuggingFace Transformers完全指南 — 预训练模型微调与推理
• Pandas完全指南 — 特征工程的数据处理基础
• 数据库设计规范 — 训练数据的存储与查询