Sklearn-源码解析-书-v1-0-二十二-
Sklearn 源码解析（书）v1.0（二十二）
解释：特征尺度被 放大，并加入 平方根‑分式 组合，模拟 异构尺度 与 复杂交互。
50.9.3 make_friedman3
源码路径：sklearn/datasets/_samples_generator.py – make_friedman3（行号 917‑970）
def make_friedman3(n_samples=100, *, noise=0.0, random_state=None):
generator = check_random_state(random_state)
X = generator.uniform(size=(n_samples, 4))
X[:, 0] *= 100
X[:, 1] *= 520 * np.pi
X[:, 1] += 40 * np.pi
X[:, 3] *= 10
X[:, 3] += 1
y = np.arctan((X[:, 1] * X[:, 2] - 1 / (X[:, 1] * X[:, 3])) / X[:, 0])
y += noise * generator.standard_normal(size=n_samples)
return X, y
解释：目标函数使用
arctan，输出被压缩到(-π/2, π/2)，专门为 有界回归（如概率回归）提供基准。
50.9.4 统一流程图
50.9.5 设计取舍 Q&A
Q1：为何仅使用前 5（或 4）维进行函数计算？
A1：保持 信息维度 与 噪声维度 的比例，使得模型需要 特征选择 或 正则化 才能达到最佳性能；这正是回归基准想要检验的能力。
Q2：make_friedman2/3 中的尺度放大有什么实验价值？
A2：放大后不同特征的数值量级相差数十倍，迫使模型在 特征缩放 前进行 预处理（如标准化），从而评估算法对 尺度不一致 的鲁棒性。
50.10 低秩矩阵生成：make_low_rank_matrix
源码路径：sklearn/datasets/_samples_generator.py – make_low_rank_matrix（行号 796‑852）
50.10.1 代码实现（关键步骤）
def make_low_rank_matrix(
n_samples=100, n_features=100, *,
effective_rank=10, tail_strength=0.5,
random_state=None,
):
generator = check_random_state(random_state)
n = min(n_samples, n_features)
# ---- 正交基 U 与 V ----
u, _ = linalg.qr(generator.standard_normal(size=(n_samples, n)),
mode="economic", check_finite=False)
v, _ = linalg.qr(generator.standard_normal(size=(n_features, n)),
mode="economic", check_finite=False)
# ---- 奇异值谱 ----
singular_ind = np.arange(n, dtype=np.float64)
low_rank = (1 - tail_strength) * np.exp(-1.0 *
(singular_ind / effective_rank) ** 2)
tail = tail_strength * np.exp(-0.1 * singular_ind / effective_rank)
s = np.identity(n) * (low_rank + tail)
# ---- 组合得到低秩矩阵 ----
return np.dot(np.dot(u, s), v.T)
代码解释：通过 QR 分解 为行、列分别生成正交矩阵
U、V，随后依据effective_rank与tail_strength构造 混合式奇异值（信号 + 噪声尾巴），再进行三矩阵相乘得到 低秩 + 噪声 的特征矩阵。该矩阵广泛用于 稀疏回归 与 降维 的基准实验。
50.10.2 架构图
50.10.3 设计取舍 Q&A
Q1：effective_rank 与实际矩阵秩相等吗？
A1：不完全相等。effective_rank 控制 信号奇异值 衰减的宽度，真正的数值秩会因为 尾巴（即使很小）仍保留全部维度，只是 能解释的方差 大部分集中在前 effective_rank 个奇异向量上。
Q2：tail_strength=0 时会得到什么矩阵？
A2：奇异值只保留 信号部分，形成 严格低秩（只有 effective_rank 个显著奇异值），适合检验 低秩恢复（如矩阵补全）算法的极限性能。
50.11 稀疏编码信号：make_sparse_coded_signal
源码路径：sklearn/datasets/_samples_generator.py – make_sparse_coded_signal（行号 854‑913）
50.11.1 代码实现
def make_sparse_coded_signal(
n_samples, *, n_components, n_features,
n_nonzero_coefs, random_state=None):
generator = check_random_state(random_state)
# ---- 字典 D（列归一化） ----
D = generator.standard_normal(size=(n_features, n_components))
D /= np.sqrt(np.sum(D ** 2, axis=0))
# ---- 稀疏系数 X ----
X = np.zeros((n_components, n_samples))
for i in range(n_samples):
idx = np.arange(n_components)
generator.shuffle(idx)
idx = idx[:n_nonzero_coefs]
X[idx, i] = generator.standard_normal(size=n_nonzero_coefs)
# ---- 信号 Y = D @ X ----
Y = np.dot(D, X)
# ---- 转置统一 API 形状 ----
Y, D, X = Y.T, D.T, X.T
return map(np.squeeze, (Y, D, X))
代码解释：首先随机生成 字典矩阵
D（列向量归一化），随后为每个样本随机挑选n_nonzero_coefs个原子并赋予高斯系数，得到 稀疏系数矩阵X。信号Y = D·X完成 稀疏线性组合，最后转置为(n_samples, n_features)的常规形状。返回的三元组Y, D, X直接对应 信号‑字典‑稀疏码，是 字典学习 与 稀疏恢复 实验的标准输入。
50.11.2 架构图
50.11.3 设计取舍 Q&A
Q1：为何在字典生成后进行列归一化？
A1：保证每个原子（列）的 ℓ₂ 范数为 1，这样系数的大小直接反映原子在信号中的贡献，避免因字典尺度差异导致的数值偏差，便于后续的 Lasso / OMP 求解。
Q2：n_nonzero_coefs 过大时会出现什么情况？
A2：稀疏度降低，信号更接近 满秩，字典学习难度下降；相反，过小会导致 高度稀疏，恢复算法需要更强的正则化才能成功解码。
50.12 稀疏无关回归：make_sparse_uncorrelated
源码路径：sklearn/datasets/_samples_generator.py – make_sparse_uncorrelated（行号 915‑955）
50.12.1 代码实现
def make_sparse_uncorrelated(n_samples=100, n_features=10, *,
random_state=None):
generator = check_random_state(random_state)
X = generator.normal(loc=0, scale=1, size=(n_samples, n_features))
y = generator.normal(
loc=(X[:, 0] + 2 * X[:, 1] - 2 * X[:, 2] - 1.5 * X[:, 3]),
scale=np.ones(n_samples),
)
return X, y
代码解释：所有特征均为 独立标准正态，目标仅由前四个特征的 线性组合 决定，剩余特征完全不相关。此数据集专门用于 稀疏正则化（L1、ElasticNet）在 高维、低信噪比 环境下的评估。
50.12.2 架构图
50.12.3 设计取舍 Q&A
Q1：为何只使用前四个特征？
A1：提供 明确的稀疏结构（4 条信息），使得 L1 正则化能够在 噪声特征 中进行有效筛选，验证稀疏回归的特征选择能力。
Q2：noise 被固定为 1.0 的原因？
A2：保持 信噪比 较低，以增加任务的难度，促使实验者关注 正则化强度 的调节。
50.13 对称正定矩阵：make_spd_matrix
源码路径：sklearn/datasets/_samples_generator.py – make_spd_matrix（行号 957‑985）
50.13.1 代码实现
def make_spd_matrix(n_dim, *, random_state=None):
generator = check_random_state(random_state)
A = generator.uniform(size=(n_dim, n_dim))
U, _, Vt = linalg.svd(np.dot(A.T, A), check_finite=False)
X = np.dot(np.dot(U, 1.0 + np.diag(generator.uniform(size=n_dim))), Vt)
return X
代码解释：先构造随机矩阵
A，得到半正定矩阵A.T @ A。对其进行 SVD，再在奇异值上加上1 + uniform，确保所有奇异值 大于 1，从而得到 严格正定 的对称矩阵X。该函数常用于 协方差矩阵、核函数 的随机生成。
50.13.2 架构图
50.13.3 设计取舍 Q&A
Q1：为何在奇异值上加上 1 + uniform 而不是直接使用 Σ？
A1：Aᵀ·A 可能出现极小的奇异值导致数值不稳定或接近奇异；添加一个 正偏移 确保所有特征方向都有足够的正特征值，从而得到 数值稳定 的 SPD 矩阵。
Q2：make_spd_matrix 与 make_sparse_spd_matrix 的区别？
A2：前者生成 密集 SPD，适合 核方法、协方差估计；后者在 Cholesky 因子 上引入稀疏性，以提供 稀疏线性系统、稀疏逆 的基准。
50.14 稀疏对称正定矩阵：make_sparse_spd_matrix
源码路径：sklearn/datasets/_samples_generator.py – make_sparse_spd_matrix（行号 987‑1050）
50.14.1 代码实现（核心片段）
def make_sparse_spd_matrix(
n_dim=1, *, alpha=0.95, norm_diag=False,
smallest_coef=0.1, largest_coef=0.9,
sparse_format=None, random_state=None,
):
random_state = check_random_state(random_state)
chol = -sp.eye(n_dim) # 初始 -I
aux = sp.random(m=n_dim, n=n_dim,
density=1 - alpha,
data_rvs=lambda x: random_state.uniform(
low=smallest_coef, high=largest_coef, size=x),
random_state=random_state)
aux = sp.tril(aux, k=-1, format="csc") # 仅下三角
permutation = random_state.permutation(n_dim)
aux = aux[permutation].T[permutation] # 随机置换破对称
chol += aux # 形成稀疏 Cholesky 因子
prec = chol.T @ chol # SPD 矩阵
if norm_diag:
d = sp.diags(1.0 / np.sqrt(prec.diagonal()))
prec = d @ prec @ d
return prec.toarray() if sparse_format is None else prec.asformat(sparse_format)
代码解释：函数先创建 负单位矩阵 作为 Cholesky 因子的基底。随后用
sp.random按稀疏度1‑alpha生成上三角稠密块aux，取下三角并随机置换行列，以破除对称结构。将aux加入chol再通过chol.T @ chol重构 对称正定矩阵。若norm_diag=True，对角线被归一化为 1，常用于 协方差标准化。返回可以是 密集 ndarray 或 指定稀疏格式。
50.14.2 架构图
50.14.3 设计取舍 Q&A
Q1：alpha 越大稀疏度越高，这对后续线性求解有什么影响？
A1：高稀疏度让矩阵趋近 对角，对 稀疏直接求逆、共轭梯度 等求解器更友好；但过于稀疏会削弱矩阵的 结构相关性，可能不再代表真实的稠密协方差。
Q2：norm_diag=True 的场景是什么？
A2：在 协方差矩阵 必须满足单位方差（对角为 1）的情形，如 相关系数矩阵，归一化确保每个特征的方差一致，便于比较不同特征的贡献。
50.15 流形玩具集：make_swiss_roll 与 make_s_curve
50.15.1 make_swiss_roll
源码路径：sklearn/datasets/_samples_generator.py – make_swiss_roll（行号 1052‑1110）
def make_swiss_roll(n_samples=100, *, noise=0.0,
random_state=None, hole=False):
generator = check_random_state(random_state)
if not hole:
t = 1.5 * np.pi * (1 + 2 * generator.uniform(size=n_samples))
y = 21 * generator.uniform(size=n_samples)
else:
corners = np.array([[np.pi * (1.5 + i), j * 7]
for i in range(3) for j in range(3)])
corners = np.delete(corners, 4, axis=0)
corner_index = generator.choice(8, n_samples)
parameters = generator.uniform(size=(2, n_samples)) * np.array([[np.pi], [7]])
t, y = corners[corner_index].T + parameters
x = t * np.cos(t)
z = t * np.sin(t)
X = np.vstack((x, y, z))
X += noise * generator.standard_normal(size=(3, n_samples))
X = X.T
t = np.squeeze(t)
return X, t
代码解释：
hole=False时t均匀采样在[0, 3π]，y直接均匀采样，随后通过 极坐标映射(x, z) = (t·cos t, t·sin t)形成螺旋卷。若hole=True，先在 3 × 3 网格中去掉中心点，再在每个角落采样，得到 带孔的卷。噪声通过noise参数注入。
50.15.2 make_s_curve
源码路径：sklearn/datasets/_samples_generator.py – make_s_curve（行号 1112‑1155）
def make_s_curve(n_samples=100, *, noise=0.0,
random_state=None):
generator = check_random_state(random_state)
t = 3 * np.pi * (generator.uniform(size=(1, n_samples)) - 0.5)
X = np.empty((n_samples, 3), dtype=np.float64)
X[:, 0] = np.sin(t)
X[:, 1] = 2.0 * generator.uniform(size=n_samples)
X[:, 2] = np.sign(t) * (np.cos(t) - 1)
X += noise * generator.standard_normal(size=(3, n_samples)).T
t = np.squeeze(t)
return X, t
代码解释：
t在[-1.5π, 1.5π]均匀采样，x = sin(t)，z = sign(t)*(cos(t)-1)形成 S 型曲面，y为均匀噪声。与瑞士卷不同的是 二维参数化（仅t）导致 单向卷曲。
50.15.3 统一流形架构图
50.15.4 设计取舍 Q&A
Q1：hole=True 对流形学习有什么帮助？
A1：带孔的瑞士卷在低维嵌入时会出现 拓扑断裂，这对 Isomap、LLE 等需要保持 局部连通性 的算法是一个严苛的挑战。
Q2：make_s_curve 的 y 维度为何使用均匀噪声而非结构化值？
A2：y 作为 第三维度的高度，保持独立均匀分布可以让流形在 沿 t 方向的曲率 主导形状，避免额外的扭曲，从而更清晰地展示 单参数流形 的属性。
50.16 高斯分位数分类：make_gaussian_quantiles
源码路径：sklearn/datasets/_samples_generator.py – make_gaussian_quantiles（行号 1157‑1220）
50.16.1 代码实现
def make_gaussian_quantiles(
*, mean=None, cov=1.0,
n_samples=100, n_features=2,
n_classes=3, shuffle=True,
random_state=None):
if n_samples < n_classes:
raise ValueError("n_samples must be at least n_classes")
generator = check_random_state(random_state)
if mean is None:
mean = np.zeros(n_features)
else:
mean = np.array(mean)
X = generator.multivariate_normal(mean,
cov * np.identity(n_features),
(n_samples,))
idx = np.argsort(np.sum((X - mean[np.newaxis, :]) ** 2, axis=1))
X = X[idx, :]
step = n_samples // n_classes
y = np.hstack(
[np.repeat(np.arange(n_classes), step),
np.repeat(n_classes - 1, n_samples - step * n_classes)]
)
if shuffle:
X, y = util_shuffle(X, y, random_state=generator)
return X, y
代码解释：函数先生成 多维标准正态 样本（均值
mean，协方差cov·I），随后依据到均值的 欧氏距离 对样本排序。把排序后的样本等分为n_classes组（若不能整除，余数归入最后一类），形成 同心球壳 的层级标签。shuffle再次打乱顺序，防止标签出现顺序相关性。
50.16.2 架构图
50.16.3 设计取舍 Q&A
Q1：为何采用 等分距离 而不是直接按概率阈值划分？
A1：等分可以确保 每类样本数量近似相同，便于评估 多类分类器 的整体性能；若使用概率阈值，类间样本数可能极不平衡，导致评估偏差。
Q2：cov 只接受标量，无法自定义协方差结构，这么设计的原因？
A2：该函数的目标是 同心球壳 的概念演示，保持各维度等方差最能突出 半径 的差异；若需要任意协方差，可直接使用 make_classification 或手动构造数据。
50.17 双聚类结构生成：make_biclusters 与 make_checkerboard
50.17.1 make_biclusters
源码路径：sklearn/datasets/_samples_generator.py – make_biclusters（行号 1232‑1300）
def make_biclusters(shape, n_clusters, *,
noise=0.0, minval=10, maxval=100,
shuffle=True, random_state=None):
generator = check_random_state(random_state)
n_rows, n_cols = shape
consts = generator.uniform(minval, maxval, n_clusters)
row_sizes = generator.multinomial(n_rows,
np.repeat(1.0 / n_clusters, n_clusters))
col_sizes = generator.multinomial(n_cols,
np.repeat(1.0 / n_clusters, n_clusters))
row_labels = np.hstack(
[np.repeat(i, size) for i, size in enumerate(row_sizes)])
col_labels = np.hstack(
[np.repeat(i, size) for i, size in enumerate(col_sizes)])
result = np.zeros(shape, dtype=np.float64)
for i in range(n_clusters):
selector = np.outer(row_labels == i, col_labels == i)
result[selector] += consts[i]
if noise > 0:
result += generator.normal(scale=noise, size=result.shape)
if shuffle:
result, row_idx, col_idx = _shuffle(result, random_state)
row_labels = row_labels[row_idx]
col_labels = col_labels[col_idx]
rows = np.vstack([row_labels == c for c in range(n_clusters)])
cols = np.vstack([col_labels == c for c in range(n_clusters)])
return result, rows, cols
代码解释：先在行、列上用 多项式分布 均匀划分簇大小，生成每个双聚类的 常数值
consts[i]，随后在对应的子块上填充值，形成 块对角结构。噪声可直接叠加，shuffle会随机置换行列顺序，防止用户直接观察块的排列。
50.17.2 make_checkerboard
源码路径：sklearn/datasets/_samples_generator.py – make_checkerboard（行号 1302‑1385）
def make_checkerboard(shape, n_clusters,
*, noise=0.0, minval=10, maxval=100,
shuffle=True, random_state=None):
generator = check_random_state(random_state)
if hasattr(n_clusters, "__len__"):
n_row_clusters, n_col_clusters = n_clusters
else:
n_row_clusters = n_col_clusters = n_clusters
n_rows, n_cols = shape
row_sizes = generator.multinomial(
n_rows, np.repeat(1.0 / n_row_clusters, n_row_clusters))
col_sizes = generator.multinomial(
n_cols, np.repeat(1.0 / n_col_clusters, n_col_clusters))
row_labels = np.hstack(
[np.repeat(i, size) for i, size in enumerate(row_sizes)])
col_labels = np.hstack(
[np.repeat(i, size) for i, size in enumerate(col_sizes)])
result = np.zeros(shape, dtype=np.float64)
for i in range(n_row_clusters):
for j in range(n_col_clusters):
selector = np.outer(row_labels == i, col_labels == j)
result[selector] += generator.uniform(minval, maxval)
if noise > 0:
result += generator.normal(scale=noise, size=result.shape)
if shuffle:
result, row_idx, col_idx = _shuffle(result, random_state)
row_labels = row_labels[row_idx]
col_labels = col_labels[col_idx]
rows = np.vstack([row_labels == r for r in range(n_row_clusters)
for _ in range(n_col_clusters)])
cols = np.vstack([col_labels == c for _ in range(n_row_clusters)
for c in range(n_col_clusters)])
return result, rows, cols
代码解释：
make_checkerboard与make_biclusters类似，但在 行×列的笛卡尔积 上填充随机值，形成 棋盘格（每个交叉块都有独立的取值），更适合评估 双聚类（Co‑clustering）算法的 交叉结构发现 能力。
50.17.3 统一架构图
50.17.4 设计取舍 Q&A
Q1：为何在 make_biclusters 中使用 对角块 而不是交叉块？
A1：对角块模拟 独立子矩阵（如基因表达子集），适合检验 块对角稀疏（Block‑Diagonal）模型；交叉块则更贴近 双聚类（Biclustering）场景，需要捕捉 行‑列共同出现的模式。
Q2：shuffle=True 对双聚类实验有什么影响？
A2：随机置换行列可以防止算法仅凭 位置先验（如行号/列号）进行分割，确保模型真正学习到 统计依赖 而非 排列信息。
50.18 章节小结
下面的表格概括了本章涉及的每个函数、对应的 核心概念 与 典型应用场景，帮助你快速定位需要的合成数据生成器。
| 小节 | 核心概念 | 关键函数 |
|------|----------|----------|
| 分类 | 超立方体簇、随机线性变换、特征噪声、标签噪声 | make_classification |
| 多标签 | 类先验、条件词分布、稀疏 CSR 构建 | make_multilabel_classification |
| 二元球面 | 球面阈值、非线性边界 | make_hastie_10_2 |
| 回归 | 低秩矩阵、稀疏真值、噪声、同步打乱 | make_regression |
| 同心圆 | 2‑D 同心圆、噪声、shuffle | make_circles |
| 半月 | 交叉半月、平移、噪声 | make_moons |
| 高斯团簇 | 多中心正态、可变 std、shuffle | make_blobs |
| Friedman 系列 | 非线性函数、噪声、尺度放大 | make_friedman1/2/3 |
| 低秩矩阵 | 奇异值谱（信号+尾巴） | make_low_rank_matrix |
| 稀疏编码 | 字典归一化、稀疏系数、信号拼装 | make_sparse_coded_signal |
| 稀疏回归 | 前四特征线性组合、剩余噪声 | make_sparse_uncorrelated |
| SPD 矩阵 | SVD 重构、奇异值偏移 | make_spd_matrix |
| 稀疏 SPD | Cholesky 稀疏化、对角归一化 | make_sparse_spd_matrix |
| 流形 | 瑞士卷/带洞、S‑曲线 | make_swiss_roll、make_s_curve |
| 高斯分位数 | 同心球壳标签划分 | make_gaussian_quantiles |
| 双聚类 | 对角块 vs 棋盘块、噪声、shuffle | make_biclusters、make_checkerboard |
| Hastie 基准 | 球面阈值二元分类 | make_hastie_10_2 |
这些函数共同构成了 scikit‑learn 的合成数据生态，让你能够在 实验设计、算法基准 与 教学示例 中随心所欲地 调配生产线，快速生成符合需求的 虚拟世界数据。祝你在数据造物主的工厂里玩得开心，创造出丰盈的科研与教学成果！
50.19 生活类比
想象 scikit-learn 的合成数据生成器是一座『虚拟世界的数据造物主工厂』： 概率分布 = 原材料仓库（高斯、均匀、泊松、多项式等基础分布） 生成函数 = 专业生产线（分类线、回归线、聚类线、流形线、矩阵线） 参数配置 = 工单单据（控制样本量、维度、噪声、结构复杂度） 特征工程 = 精加工车间（信息特征→冗余特征→重复特征→噪声特征的层层加工） 结构注入 = 设计图纸（超立方体顶点、同心圆、瑞士卷、棋盘块等几何拓扑） 输出封装 = 包装发货区（Bunch对象、元组、稀疏矩阵、元数据标注） 就像造物主根据『设计图纸』(参数) 从『原材料仓库'(分布) 取料，经过『生产线'(生成函数) 精密加工，注入『几何拓扑结构'(流形/簇/矩阵谱)，最终交付『标准化数据包裹』(X, y) 供算法『实验验收』。
50.20 模块地图/架构图
sklearn/datasets/_samples_generator.py
├── 核心工具函数
│ ├── _generate_hypercube() # 生成超立方体顶点作为簇中心
│ ├── _shuffle() # 同步打乱行列顺序
├── 分类数据生成器
│ ├── make_classification() # 核心分类数据生成（超立方体+高斯簇+特征工程）
│ ├── make_multilabel_classification() # 多标签分类（文档-主题-词袋三层模型）
│ ├── make_hastie_10_2() # Hastie ESL 经典二分类基准
│ ├── make_gaussian_quantiles() # 同心超球面分层分类
├── 回归数据生成器
│ ├── make_regression() # 线性回归地面真值反向工程
│ ├── make_friedman1() # Friedman #1 非线性回归基准
│ ├── make_friedman2() # Friedman #2 非线性回归基准
│ ├── make_friedman3() # Friedman #3 非线性回归基准
│ ├── make_sparse_uncorrelated() # 稀疏无关回归问题
├── 聚类与玩具数据集
│ ├── make_blobs() # 高斯团簇聚类基准
│ ├── make_circles() # 同心圆分类/聚类可视化
│ ├── make_moons() # 交织半月分类/聚类可视化
├── 矩阵分解与字典学习
│ ├── make_low_rank_matrix() # 低秩矩阵（指数衰减奇异值谱）
│ ├── make_sparse_coded_signal() # 稀疏编码信号 Y=XD
├── 结构化矩阵生成
│ ├── make_spd_matrix() # 对称正定矩阵 (A@A.T SVD重组)
│ ├── make_sparse_spd_matrix() # 稀疏对称正定矩阵 (Cholesky因子稀疏化)
├── 流形学习玩具集
│ ├── make_swiss_roll() # 瑞士卷流形 (参数化螺旋面)
│ ├── make_s_curve() # S型曲线流形
├── 双聚类结构生成
│ ├── make_biclusters() # 对角块结构双聚类
│ ├── make_checkerboard() # 棋盘块结构双聚类
以上地图列出本章源码模块及其职责，后文将按数据流逐一解析。
50.21 动手练习
50.21.1 深度阅读 make_classification 核心逻辑
阅读 sklearn/datasets/_samples_generator.py 中 make_classification 函数 (第34-272行) 和 _generate_hypercube (第17-32行)
回答问题：
-
_generate_hypercube为何分dimensions>30和≤30两种实现路径？位运算unpackbits与sample_without_replacement如何协作生成唯一顶点？ -
n_informative与n_classes * n_clusters_per_class的对数关系n_informative < log2(n_clusters)为何必须成立？违反会怎样？ -
冗余特征
B矩阵的生成范围[-1, 1]和重复特征索引计算((n-1)*uniform + 0.5).astype(intp)的数学含义是什么？ -
shift/scale为何支持标量、数组和None三种模式？None时的随机范围设计意图？
50.21.2 对比分析三大流形生成器的几何本质
对比阅读 make_swiss_roll (1052-1110行)、make_s_curve (1112-1155行)、make_circles (578-643行) 的坐标变换公式
回答问题：
-
瑞士卷的参数
t ∈ [1.5π, 4.5π]和y ∈ [0, 21]如何决定流形的『卷数』和『高度』？hole=True时 8 个角落采样的几何含义？ -
S 曲线的
x=sin(t), z=sign(t)*(cos(t)-1)为何能形成『S』形拓扑？y维度为何用均匀分布而非参数化？ -
同心圆
make_circles为何使用endpoint=False的linspace？factor参数如何控制类别可分性？ -
三者返回的
t(或隐含参数) 在流形学习评估中扮演什么角色？
50.21.3 实战：设计自定义合成数据生成器
参考 make_biclusters (1232-1300行) 和 make_checkerboard (1302-1385行) 的双聚类结构生成模式
动手实现：
-
编写
make_diagonal_blocks(shape, n_blocks, block_values, noise=0.0, random_state=None)生成对角线分块矩阵（非方阵也可），每个块取值来自block_values序列 -
编写
make_concentric_spheres(n_samples, n_features, n_spheres, noise=0.0, random_state=None)生成同心超球面分层回归数据，目标值为球面半径索引 + 噪声 -
验证：用 PCA/流形学习/聚类算法分别在生成数据上运行，观察结构是否可被恢复
50.21.4 剖析稀疏矩阵构建的工程细节
阅读 make_multilabel_classification (274-435行) 中 CSR 矩阵构建部分 和 make_sparse_spd_matrix (987-1050行) 稀疏 SPD 生成
回答问题：
-
array.array('i')累积indices和indptr相比直接构建coo_matrix再转csr有何性能优势？ -
X.sum_duplicates()在多标签词袋生成中的必要性？若移除会发生什么？ -
make_sparse_spd_matrix中为何在 Cholesky 因子chol上施加稀疏性而非直接在精度矩阵上？perm @ chol @ perm.T对称置换的作用？ -
sparse_format参数支持哪些格式？asformat()转换的内存语义？
50.22 设计取舍 Q&A（“一问一答”）
为什么采用当前方案而不是更复杂的替代方案？ 本章实现优先保证与既有 API 的一致性、可维护性与运行效率。这意味着在少数极端场景下，调用者需要自行在灵活性、内存与速度之间做取舍，换取默认路径的清晰与稳定。
第 51 章 —— utils 输入验证与数学工具：算法战场上的“瑞士军刀”
51.1 学习目标
-
难度：★★★☆☆（3/5）
-
预备知识：Python 基础、面向对象编程与 Markdown/代码阅读基础
-
掌握 scikit-learn 核心输入验证函数 check_array 与 check_X_y 的设计原理与参数语义
-
理解有限性检测的分层策略：快速路径、Cython 无 GIL 加速与回退机制
-
熟悉随机化 SVD 与增量统计算法的数学原理及其 Array API 兼容实现
-
掌握稀疏矩阵专用统计与线性代数内核（CSR/CSC 均值/方差、Gustavson 乘法、原地归一化）的实现细节
-
理解 Newton-CG 二阶优化器的外层牛顿迭代、内层共轭梯度求解与 Wolfe 线搜索协作机制
-
能阅读并修改基于 Cython 的底层数值计算原语（min_pos、cholesky_delete、全行比较等）
想象 scikit-learn 的 utils 模块是算法战场上的“瑞士军刀后勤部”：它不是前线的刀枪，却是保障战斗力的幕后英雄。check_array / check_X_y 如同严格的安检员，拦截脏数据、统一格式、核对身份（特征名/数量），只有合格的数据才能进入训练前线。cy_isfinite 是无人机巡逻兵，无需 GIL 锁、以 C 级速度极速扫描 NaN/Inf 地雷，标记即撤，不拖慢主力部队。随机化 SVD 是概率侦察兵，无需全量扫描整块地形（全矩阵 SVD），只需几轮随机投影就能速写出地形主脉（主奇异向量），以 O(nk²) 的成本换取 O(n³) 的精度，实现战略欺骗。增量均值方差 是流线补给官，物资（数据批次）分批到场，它用 Chan-Golub-LeVeque 公式实时更新仓库账本（均值/方差），无需卸空重算，支持加权、抗数值抵消，且可随时断点续传。稀疏统计内核 是专攻稀疏地形的工兵：只踩非零格子（CSR/CSC 中的非零元），把隐式零值当作补偿项处理，一次遍历出均值、两遍出方差，绝不把稀疏地图铺成稠密沼泽。Gustavson 乘法 是稀疏物流专线：A 矩阵的每辆非零货车直奔 B 矩阵对应的仓库行，卸货后直接累加到稠密输出中，全程无中间转运站（避免稀疏中间结构），缓存友好且零拷贝。Newton-CG 是重型攻城炮：外层牛顿迭代定下战略目标（利用二阶曲率求搜索方向），内层共轭梯度负责战术推进（求解 H p = -g），Wolfe 线搜索则担任火力侦察（判定步长），若曲率为负则立即回退至最速下降或封炮。arrayfuncs 原语 则是微创手术刀：min_pos 用一次遍历精准切出最小正值，cholesky_delete 通过 Givens 旋转原地修正矩阵分解，_all_with_any_reduction_axis_1 通过短路逻辑判断全行相等而不分配临时布尔矩阵——极致内存节俭，只为保护算法的每一寸前进空间。
51.2 源码地图
sklearn/utils/validation.py
├── check_array() # 统一输入验证入口，支持密集/稀疏/数据框
├── check_X_y() # 监督学习 X/y 联合验证
├── _assert_all_finite() # 有限性检查分发（快速路径/元素级）
├── _assert_all_finite_element_wise() # 元素级有限性检查（Cython/NumPy 双路径）
├── _ensure_sparse_format() # 稀疏格式转换、dtype 统一、大索引检查
├── _check_feature_names() # 特征名同步与一致性校验
├── _check_n_features() # 特征数同步与校验
├── validate_data() # 估计器数据验证总控，支持 meta-estimator 委托
├── check_random_state() # 随机状态标准化
├── check_symmetric() # 对称性检查与自动对称化
├── check_is_fitted() # 拟合状态检查
├── check_scalar() # 标量类型与边界一体化校验
├── _check_sample_weight() # 样本权重标准化与设备一致性
├── _check_psd_eigenvalues() # PSD 矩阵特征值数值修正
├── as_float_array() # 转换为浮点数组，支持稀疏/扩展类型
├── assert_all_finite() # 公开有限性检查入口（含稀疏矩阵）
├── _deprecate_positional_args() # 位置参数弃用装饰器
├── _estimator_has() # 委托属性检查工厂
├── _check_response_method() # 响应方法存在性验证
├── check_non_negative() # 非负性检查（稀疏/稠密统一）
├── _check_large_sparse() # 64位索引稀疏矩阵拦截
├── _check_monotonic_cst() # 单约束格式标准化
├── _to_object_array() # 序列转对象数组（避免歧义）
├── _is_extension_array_dtype() # 扩展数组类型识别
├── _check_feature_names_in() # 输入特征名一致性检查与生成
├── _generate_get_feature_names_out() # 基于估计器名生成输出特征名
├── _make_indexable() # 可索引化转换（稀疏转CSR）
├── _check_pos_label_consistency() # 二分类正标签推断与校验
├── _is_fitted() # 拟合状态底层判断逻辑
├── _use_interchange_protocol() # DataFrame互换协议检测
├── _get_feature_names() # 从容器提取特征名（pandas/协议）
├── _is_arraylike() # 类数组判断（排除稀疏）
├── _allclose_dense_sparse() # 稠密/稀疏数值近似比较
├── _is_arraylike_not_scalar() # 非标量类数组判断
├── check_memory() # joblib.Memory 实例化与校验
├── has_fit_parameter() # fit方法参数存在性检查
├── _check_estimator_name() # 估计器名提取（字符串/实例）
├── _raise_error_wrong_axis() # 轴参数合法性检查
├── _check_method_params() # 方法参数索引能力验证与转换
├── _num_samples() # 统一样本数获取（支持协议/形状/长度）
├── _num_features() # 特征数启发式获取（避免物化）
├── _ensure_no_complex_data() # 复数数据拦截
├── _pandas_dtype_needs_early_conversion() # 扩展dtype早期转换判断
├── indexable() # 交叉验证用可索引化批量转换
├── check_consistent_length() # 长度一致性检查
├── column_or_1d() # y向量展平与验证
├── _check_y() # y验证内部实现
sklearn/utils/extmath.py
├── randomized_svd() # 随机化截断 SVD 主入口
├── _randomized_svd() # 核心实现：随机投影、幂迭代、小矩阵 SVD、符号翻转
├── randomized_range_finder() # 正交基构造主入口（含输入验证）
├── _randomized_range_finder() # 核心实现：正交基构造（QR/LU/none 归一化）
├── _incremental_mean_and_var() # Chan-Golub-LeVeque 增量均值方差（含样本权重、NaN 安全、Array API）
├── _safe_accumulator_op() # 累加器精度保护（自动升级到 float64）
├── svd_flip() # SVD 符号约定统一
├── safe_sparse_dot() # 稀疏/稠密混合点积分发
├── row_norms() # 行范数（稀疏/稠密统一）
├── cartesian() # 笛卡尔积生成
├── weighted_mode() # 加权众数
├── softmax() # 数值稳定 Softmax
├── make_nonnegative() # 非负化平移
├── _nanaverage() # 忽略 NaN 的加权平均
├── safe_sqr() # 元素级平方（稀疏感知）
├── _approximate_mode() # 多元超几何分布众数近似
├── _randomized_eigsh() # 随机化特征分解（模选择策略）
├── squared_norm() # 向量/矩阵平方范数（展平优化）
├── density() # 稀疏度计算
├── fast_logdet() # 对数行列式（slogdet鲁棒封装）
├── _deterministic_vector_sign_flip() # 向量符号确定性翻转（行最大值为正）
├── stable_cumsum() # 高精度累积和（已弃用）
sklearn/utils/sparsefuncs.py
├── mean_variance_axis() # CSR/CSC 轴向均值方差分发
├── incr_mean_variance_axis() # 增量均值方差分发
├── inplace_csr_column_scale() # CSR 列原地缩放
├── inplace_csr_row_scale() # CSR 行原地缩放
├── inplace_column_scale() # CSC/CSR 列缩放统一入口
├── inplace_row_scale() # CSC/CSR 行缩放统一入口
├── inplace_swap_row() # 行交换（CSR/CSC）
├── inplace_swap_column() # 列交换（CSR/CSC）
├── min_max_axis() # 轴向最值（含 NaN 忽略）
├── count_nonzero() # 非零计数（支持样本权重）
├── csc_median_axis_0() # CSC 列中位数
├── _implicit_column_offset() # 隐式列偏移线性算子（PCA 用）
├── sparse_matmul_to_dense() # 稀疏×稀疏→稠密分发（调用 Cython Gustavson）
├── assign_rows_csr() # CSR 选取行稠密化写入预分配数组
├── inplace_swap_row_csc() # CSC 行交换内核
├── inplace_swap_row_csr() # CSR 行交换内核
├── _raise_typeerror() # 非 CSR/CSC 类型报错
├── _get_median() # 带零值填充的中位数计算
├── _get_elem_at_rank() # 带零值填充的秩查找
├── _raise_error_wrong_axis() # 轴参数合法性检查
sklearn/utils/sparsefuncs_fast.pyx
├── csr_row_norms() # CSR 行平方 L2 范数
├── _csr_mean_variance_axis0() # CSR 列均值方差（两遍算法、隐式零值修正）
├── _csc_mean_variance_axis0() # CSC 列均值方差（转置复用 CSR 逻辑）
├── _incr_mean_variance_axis0() # 增量合并（Chan-Golub-LeVeque 公式、首批次快路径）
├── _inplace_csr_row_normalize_l1() # CSR 行原地 L1 归一化
├── _inplace_csr_row_normalize_l2() # CSR 行原地 L2 归一化
├── assign_rows_csr() # CSR 选取行稠密化写入预分配数组
├── csr_matmul_csr_to_dense() # Gustavson 算法：稀疏×稀疏→稠密（按行遍历 A，累加 B 行）
├── _sqeuclidean_row_norms_sparse() # CSR 行平方范数 Cython 内核
├── csr_mean_variance_axis0() # CSR 列均值方差 Python 封装
├── csc_mean_variance_axis0() # CSC 列均值方差 Python 封装
├── incr_mean_variance_axis0() # 增量均值方差 Python 封装
sklearn/utils/arrayfuncs.pyx
├── min_pos() # 最小正值查找（单次遍历，无正值返回 FLT_MAX/DBL_MAX）
├── _all_with_any_reduction_axis_1() # 任一行全等于 value（避免布尔矩阵分配）
└── cholesky_delete() # Cholesky 秩-1 修正删除行/列（Givens 旋转）
sklearn/utils/optimize.py
├── _newton_cg() # Newton-CG 外层迭代
├── _cg() # 共轭梯度内层求解（曲率保护、Capped CG、负曲率回退）
├── _line_search_wolfe12() # Wolfe 1/2 双阶段线搜索（微小损失改进时的梯度范数兜底）
└── _check_optimize_result() # 优化结果收敛性检查与警告
sklearn/utils/_isfinite.pyx
├── cy_isfinite() # 无 GIL 有限性扫描入口
├── _isfinite_allow_nan() # 仅查 Inf
├── _isfinite_disable_nan() # 同时查 NaN/Inf
└── _isfinite() # 内部无 GIL 扫描核心（nogil）
51.3 核心类型定义：输入验证的“设计图纸”
在深入具体函数之前，我们需要理解 scikit-learn 输入验证系统的核心设计思想：它不是简单的“拦截坏数据”，而是通过一奂统一的接口和分层策略，确保数据在进入算法核心前已经被净化、标准化并具备一致的内存布局。这一套设计就像是一套精密的数据过滤与标准化生产线，每道工序都有明确的职责，层层把关，最终输出的是算法能够安全、高效消费的“标准件”。
让我们先来看看这个验证系统的总闸门——check_array 函数的签名和核心参数，它们就像是这条生产线上的主阀门和参数调节旋钮。
源码路径：sklearn/utils/validation.py - check_array()（1-60行）
def check_array(
array,
accept_sparse=False,
accept_large_sparse=False,
dtype="numeric",
order=None,
copy=False,
force_all_finite=True,
ensure_2d=True,
allow_nd=False,
ensure_min_samples=1,
ensure_min_features=1,
estimator=None,
):
"""Input validation on an array, list, sparse matrix or similar.
Parameters
----------
array : object
Input object to validate / convert.
accept_sparse : bool, string or list, default=False
String[sparse matrix type] allowed or False for none.
To enable, pass in 'csr', 'csc', etc. If list/tuple of strings
is passed in, multiple sparse types are allowed.
accept_large_sparse : bool, default=False
Whether to accept CSR/CSC matrices with int64 indices.
dtype : str, type or list of types, default="numeric"
Data type of result. If None, no dtype conversion is performed.
Unless np.object_, which is ignored. If a list of types,
conversion on the first type is only performed if
``array.dtype`` not in the list.
order : str, default=None
Whether to ensure a specific memory layout.
'C' means C order, 'F' means F order.
'A' means F order if 'F' is contiguous, C order otherwise.
'K' means keep as close to the original layout as possible.
None means no order enforcement.
copy : bool, default=False
Whether a forced copy will be triggered. If copy=False, a copy might
be triggered by a conversion.
force_all_finite : bool or str, default=True
Whether to raise an error on np.inf, np.nan, pd.NA in array.
The possibilities are:
- True: Force all values to be finite.
- 'allow-nan': Ignore only NaN values.
- False: does not check finiteness.
ensure_2d : bool, default=True
Whether to raise a value error if array is not 2D.
1D arrays will be reshaped to (1, n) or (n, 1) depending on
if it's a row or column vector respectively.
allow_nd : bool, default=False
Whether to allow arrays with more than 2 dimensions.
ensure_min_samples : int, default=1
Make sure that there are at least this many samples.
(otherwise an error is raised)
ensure_min_features : int, default=1
Make sure that there are at least this many features.
(otherwise an error is raised)
estimator : str or estimator instance, default=None
If passed, include the name of the estimator in warning messages.
"""
这段代码定义了输入验证的“总闸门”——check_array 函数。它通过十多个精心设计的参数，将数据验证的各个维度进行解耦：可以控制是否接受稀疏矩阵（accept_sparse）、是否允许大索引稀疏矩阵（accept_large_sparse）、目标数据类型（dtype）、内存布局要求（order）、是否强制复制（copy）、是否检查有限性（force_all_finite）、维度要求（ensure_2d, allow_nd）、最小样本/特征数（ensure_min_samples, ensure_min_features），甚至还能将验证错误与特定估计器关联（estimator）。这种设计让验证既灵活又精准——不同的算法可以根据自身需求“开不同大小的阀门”：有些只需要基本的数组验证（比如 PCA），有些要接受稀疏输入（比如线性SVM），有些则需要严格的有限性检查（比如梯度提升）。通过这种参数化的设计，check_array 成为了一把真正的“瑞士军刀”——同一把工具，通过调节不同的参数，就能胜任各种验证场景。
图 50.1：check_array 的数据验证和转换流程
51.4 逐行解析关键函数：check_array 的执行流程
有了这个“设计图纸”，我们现在来看看当这个总闸门被打开时，数据到底会经历哪些验证和转换步骤。为了便于理解，我选取了 check_array 中最核心的处理流程部分进行逐行解析——这里包含了类型转换、维度检查、稀疏处理、有限性验证等关键环节。
源码路径：sklearn/utils/validation.py - check_array()（61-120行）
# 第 51 章 —— 为了避免在 NumPy 数组上重复应用 array 函数导致副作用
# 第 51 章 —— 同时处理可能是数组列表的情况
if hasattr(array, '__array__') or isinstance(array, (list, tuple)):
# 首次尝试使用提供的 dtype 进行转换
# 如果用户明确要求不转换 dtype（dtype=None），则跳过
if dtype is not None:
try:
# 尝试将输入转换为指定 dtype 的 NumPy 数组
# 这一步会处理 list、tuple 或实现了 __array__ 协议的对象
array = np.asarray(array, dtype=dtype)
except ValueError:
# 如果直接转换失败（比如含有不可转换的字符串）
# 则尝试不指定 dtype 进行转换，让 NumPy 自行推断
array = np.asarray(array)
else:
# 用户不要求特定 dtype，直接转换为 NumPy 数组
array = np.asarray(array)
# 第 51 章 —— 处理已经是 NumPy 数组但 dtype 不匹配的情况
elif dtype is not None and not isinstance(array, np.ndarray):
# 对于非 ndarray 对象（比如矩阵、mat 等），强制转换为指定 dtype 的数组
array = np.asarray(array, dtype=dtype)
这段代码是 check_array 的“类型转换入口”，负责把各种形式的输入（列表、元组、已有数组、类数组对象）安全地转换为 NumPy 数组，同时尊重用户通过 dtype 参数指定的目标类型。这里采用了“先试后退”的策略：优先使用用户指定的 dtype 进行转换；如果失败（比如试图把包含文本的列表转换为 float），则回退到让 NumPy 自行推断 dtype。这种设计既保证了验证的严格性（用户指定的 dtype 会被强制执行），又避免了在数据明显不匹配时造成不必要的错误中断——毕竟，有时我们只想确保“这是个数值数组”，而不必纠结于它是 float32 还是 float64。特别值得注意的是，这段代码特意避免了对已经是 np.ndarray 的对象重复应用 np.asarray，这可以防止在某些视图或特殊数组类型上产生不必要的副本，从而保护内存效率——这正是后勤部门对“零浪费”的极致追求。
图 50.2：check_array 中的类型转换逻辑
此段代码负责将各种输入（如列表、元组、已有 NumPy 数组或实现 __array__ 协议的对象）转换为符合要求的 NumPy 数组。它优先尝试使用用户指定的 dtype 进行转换；若失败（例如尝试将包含字符串的列表转换为浮点型），则回退到让 NumPy 自行推断数据类型；若用户未指定 dtype（即 dtype=None），则直接转换而不强制类型。此外，它还避免对已经是 np.ndarray 的对象重复应用 np.asarray，以防止在视图或特殊数组类型上产生不必要的副本，从而保护内存效率。
源码路径：sklearn/utils/validation.py - check_array()（121-180行）
# 第 51 章 —— 如果启用了稀疏矩阵支持，并且输入已经是支持的稀疏格式
if sp.issparse(array):
# 检查是否接受该稀疏格式
_ensure_sparse_format(array, accept_sparse, accept_large_sparse)
else:
# 对于非稀疏输入，检查是否包含无效值（如 np.nan, np.inf）
# 这一步是有限性检查的快速路径，使用 view 检测连续内存中的模数据
if force_all_finite:
_assert_all_finite(
array,
allow_nan=force_all_finite == "allow-nan",
msg_dtype=msg_dtype if dtype is not None else None,
)
这里我们看到验证流程的一个关键分支：稀疏矩阵和密集矩阵走的是不同的验证路径。如果输入已经是稀疏矩阵（通过 sp.issparse 判断），则跳过密集数组的有限性检查，转而调用 _ensure_sparse_format 来验证稀疏格式是否被接受（比如是否允许 csr 或 csc）、检查是否含有 int64 索引（大索引稀疏矩阵）以及统一数据类型。这是因为稀疏矩阵的内部结构已经很难用简单的逐元素检查来验证有限性——它的数据只存了非零元，而零是隐式的。相比之下，密集数组则可以通过内存视图快速扫描是否含有 NaN 或 Inf。这种“根据数据结构走不同路径”的设计，正是高效验证的核心：我们不强求所有数据都用同一种方式检查，而是根据其内部组织选择最合适的验证策略——这就像后勤部门不会对粮食和弹药用同一种方式检验：前者看是否发霉，后者看是否有裂纹。
图 50.3：稀疏和密集数据的不同验证路径
此段代码实现了验证流程中的关键分支：对于稀疏矩阵输入，跳过逐元素有限性检查（因其零值为隐式存储），转而验证其格式是否被接受（如 CSR/CSC）、是否含有大索引（int64）以及数据类型是否统一；对于密集数组，则在 force_all_finite 启用时执行有限性检查（如 NaN/Inf 检测）。这种设计根据数据的内部结构选择最合适的验证路径，避免对稀疏矩阵进行低效的逐元素扫描，同时确保密集数据的有效性。
源码路径：sklearn/utils/validation.py - check_array()（181-240行）
# 第 51 章 —— 确保满足最小样本数要求
if array.shape[0] < ensure_min_samples:
raise ValueError(
f"Found array with {array.shape[0]} sample(s) (shape={array.shape}). "
f"A minimum of {ensure_min_samples} is required."
)
# 第 51 章 —— 确保满足最小特征数要求（仅在需要强制2D时检查）
if ensure_2d and array.ndim == 2 and array.shape[1] < ensure_min_features:
raise ValueError(
f"Found array with {array.shape[1]} feature(s) (shape={array.shape}). "
f"A minimum of {ensure_min_features} is required."
)
# 第 51 章 —— 处理维度：如果需要强制2D且当前是1D
if ensure_2d:
if array.ndim == 0:
raise ValueError(
"Expected 2D array, got 0D array instead: "
f"{array.reshape((1, -1)) if array.size == 1 else array}."
)
elif array.ndim == 1:
# 重塑为行向量或列向量
# 这里采用列向量重塑，符合 scikit-learn 的约定
array = array.reshape(-1, 1)
这段代码处理了验证中的“基础体检”部分：样本数和特征数的下限检查，以及维度的强制转换。这里的设计体现了 scikit-learn 对“样本在行、特征在列”这一惯例的强烈坚持——即使用户传入的是一个一维数组（比如一个特征的所有样本值），只要 ensure_2d 为 True（默认值），它就会被自动重塑为列向量（shape 从 (n,) 变为 (n, 1)）。这种行为看似简单，却极其重要：它确保了所有下游算法都能以统一的方式解释输入数据——第一维总是样本数，第二维总是特征数。想象一下，如果没有这个统一，某个算法可能把特征当样本用，结果完全偏离；而在这里，不管用户是传入 [1,2,3] 还是 [[1],[2],[3]]，验证后都会得到同样的一列数据，从而保证了接口的可预测性。这正是框架设计的力量：用少量的约定换取整个生态系统的可组合性。
图 50.4：check_array 中的维度检查和转换逻辑
此段代码执行三项核心检查：首先验证样本数（行数）是否满足 ensure_min_samples 的最小要求，不足则抛出错误；其次，在需要强制二维（ensure_2d=True）且数据为二维时，检查特征数（列数）是否满足 ensure_min_features；最后，若数据为零维或一维且需要强制二维，则进行 reshape：零维数据触发错误（无法合理重塑为二维），一维数据被重塑为列向量（-1, 1），确保所有 downstream 算法均以“样本在行、特征在列”的统一格式接收输入，从而保证接口行为的可预测性和模型的一致性。
源码路径：sklearn/utils/validation.py - check_array()（241-300行）
# 第 51 章 —— 处理内存布局要求（如 C 顺序、F 顺序等）
if order is not None and array.flags[order] != 1:
# 创建满足指定内存布局的数组副本
array = np.asarray(array, order=order)
# 第 51 章 —— 如果需要强制复制（即使其他条件未触发复制）
elif copy:
# 显式复制数组以确保不共享内存
array = np.array(array, copy=True)
# 第 51 章 —— 最后再次检查有限性（特别是在可能经过转换后）
# 第 51 章 —— 这一步确保即使在 dtype 转换或内存重排后，数据仍然是有限的
if force_all_finite:
_assert_all_finite(
array,
allow_nan=force_all_finite == "allow-nan",
msg_dtype=msg_dtype if dtype is not None else None,
)
在验证流程的最后阶段，check_array 处理了两个经常被忽略却极其重要的方面：内存布局和副本控制。通过 order 参数，用户可以强制要求数据采用特定的内存排列方式（比如 C 顺序或 F 顺序），这对于后续与底层 BLAS 库或 Cython 代码的交互至关重要——许多高性能数值内核对内存访问模式极为敏感，错位的访问会导致缓存失效和性能崩溃。与此同时，copy 参数允许用户显式请求一个不共享内存的副本，这在算法需要就地修改输入数据时可以防止意外的副作用。最后，即使在这些转换之后，函数还是会再次进行有限性检查——因为某些操作（比如 dtype 转换或内存重排）理论上不应该引入非有限值，但出于防御性编程的考虑，这一步确保了万无一失。这种“转换后再检查”的模式，正是可靠软件工程的典范：我们不假设任何转换是完美的，而是在每一步关键操作后都进行验证，从而在问题扩散之前就将其扼杀。
图 50.5：内存布局控制和副本生成的处理流程
此段代码处理验证的最后两个关键方面：内存布局与副本控制。如果指定了 order 参数（如 'C'、'F'、'A' 或 'K'）且当前数组不满足该布局，则通过 np.asarray(array, order=order) 创建符合要求的副本；如果未通过布局检查触发复制但用户显式设置了 copy=True，则强制复制数组以避免内存共享；最后，无论是否经历了类型转换、布局调整或复制，只要 force_all_finite 启用，就再次执行有限性检查（如 NaN/Inf 检测），以防御性地确保经过所有变换后数据仍然是有限的——这体现了“转换后再验证”的可靠软件工程原则，确保在每一步关键操作后都能及时捕获潜在问题，防止错误在后续算法中放大扩散。
51.5 核心类型定义：随机化 SVD 的“设计图纸”
在理解了输入验证如何为算法把好第一道关之后，我们现在转向另一类同样重要的工具：那些让高维数据处理变得可行的数学加速器。其中最巧妙的莫过于随机化 SVD——它用概率的方法在可接受的误差范围内，将原本 O(n³) 的奇异值分解降解到 O(nk²) 的程度，其中 k 是我们想要保留的奇异值数量（通常远小于 n）。这种技术就像是派遣一支小规模的侦察队去绘制整片战场的地形图：他们不会逐尺寸测绘每一寸土地，而是通过有策略的随机采样和多次 refinement，快速收敛到地形的主要特征（主峰谷），而忽略那些对战局影响微小的细微起伏。
让我们先看看这个“概率侦察兵”的函数签名——它需要哪些参数来控制这种速度与精度的权衡？
源码路径：sklearn/utils/extmath.py - randomized_svd()（1-40行）
def randomized_svd(
M,
n_components,
*,
n_oversamples=10,
n_power_iterations=None,
power_iteration_normalizer="auto",
flip_sign=True,
random_state=None,
transpose="auto",
):
"""Compute a truncated randomized SVD.
Parameters
----------
M : ndarray of shape (n_samples, n_features)
Matrix to decompose.
n_components : int
Number of singular vectors and values to extract.
n_oversamples : int, default=10
Additional number of random vectors to sample the range of M
so as to ensure proper conditioning. The total number of random
vectors used for the range finding is n_components + n_oversamples.
n_power_iterations : int or None, default=None
Number of power iterations to perform to improve the
accuracy of the estimation of the singular vectors.
If None, the value is determined based on the size of the gaps
in the singular spectrum (see Notes).
power_iteration_normalizer : str, default='auto'
Normalizer for the power iterations. 'auto' selects the
normalizer based on the input type and the value of
n_power_iterations. Options are 'none', 'LU', and 'QR'.
flip_sign : bool, default=True
The sign to flip for the output vectors. If True, the sign
of the vectors is flipped to make the first non-zero element
of each singular vector non-negative.
random_state : int, RandomState instance or None, default=None
Determines random number generation for dataset creation. Pass an int
for reproducible output across multiple function calls.
See :term:`Glossary <random_state>`.
transpose : str, default='auto'
Whether the algorithm should be applied to M.T instead of M.
'auto' uses heuristics to determine whether to transpose M.
True forces transpose, False never transposes.
Returns
-------
U : ndarray of shape (n_samples, n_components)
Orthogonal matrix containing the left singular vectors.
S : ndarray of shape (n_components,)
The singular values.
Vt : ndarray of shape (n_components, n_features)
Matrix containing the right singular vectors.
"""
这段代码定义了随机化 SVD 的接口，暴露了控制其行为的几个关键旋钮。n_components 决定我们想要提取多少个主成分——这直接影响后续算法（如 PCA）的降维维度。n_oversamples 控制我们在构造初始随机投影时使用多余的随机向量数量；这个看似多余的设计其实是为了应对最坏情况：当矩阵的奇异值谱非常平缓时，基本的投影可能无法充分捕获主子空间，额外的向量提供了安全余量。n_power_iterations 和 power_iteration_normalizer 共同控制“幂迭代”阶段——这是提升精度的关键步骤，通过反复应用 M 和 M.T 来增强对主子空间的敏感度，就像反复折叠纸张让其更贴合模型一样。flip_sign 则解决了 SVD 中固有的符号歧义：由于如果 (u, s, vt) 是一个解，那么 (-u, s, -vt) 也是解，因此输出的符号在不同运行中可能翻转；通过强制使每个奇异向量的首个非零元为非负，我们获得了确定性的输出。最后，transpose="auto" 体现了对算法对称性的尊重：由于 SVD(M) 和 SVD(M.T) 在奇异值上是相同的，我们可以选择在更小的维度上运行算法以减少计算量——比如当特征数远大于样本数时，在 M.T 上做 SVD 会更快。
图 50.6：随机化 SVD 的参数和工作原理示意图
51.6 逐行解析关键函数：随机化 SVD 的核心实现
有了这个设计图纸，我们现在深入随机化 SVD 的实际执行流程。这个算法的精妙之处在于它将一个看似需要处理整个矩阵的问题（求奇异值分解），通过概率方法转化为两个 viel 更易处理的步骤：首先，用随机投影构造一个近似的值域（range）正交基；其次，在这个投影降维后的小矩阵上做精确的 SVD；最后，将结果映射回原始空间。这种“先降维再精求”的策略，正是它能够突破 O(n³) 瓶颈的核心所在。
源码路径：sklearn/utils/extmath.py - _randomized_svd()（41-100行）
# 步骤1：决定是否转置矩阵以优化计算
# 当特征数远大于样本数时，在 M.T 上做 SVD 更快
if transpose == "auto":
transpose = M.shape[0] < M.shape[1]
if transpose:
M = M.T
# 步骤2：构造用于值域采样的随机矩阵
# 总共需要 (n_components + n_oversamples) 个随机向量
rng = check_random_state(random_state)
# 生成标准高斯随机矩阵作为投影矩阵
Omega = rng.standard_normal(size=(M.shape[1], n_components + n_oversamples))
# 步骤3：计算初始值域近似 Y = M @ Omega
# 这一步捕获了 M 的主要方向信息
Y = np.dot(M, Omega)
# 步骤4：对 Y 进行 QR 分解以获取正交基 Q
# 这里的 Q 是 M 值域的近似正交基
try:
Q, R = linalg.qr(Y, mode="economic", check_finite=False)
except linalg.LinAlgError:
# 如果 QR 失败（极少见），回退到 LU 分布
Q, R = linalg.lu(Y, permute_l=True)
Q, R = Q[:, :n_components + n_oversamples], R[
:n_components + n_oversamples, :n_components + n_oversamples
]
# 步骤5：执行幂迭代以增强对主子空间的敏感度
# 通过反复计算 M @ M.T @ Q 来迭代 refinement Q
for ii in range(n_power_iterations):
# 根据 power_iteration_normalizer 决定如何归一化
if power_iteration_normalizer == "LU":
# LU 分解归一化：更快但可能数值不稳定
P, L, U = linalg.lu(Q, check_finite=False)
Q = np.dot(U, P)
Q, _ = linalg.qr(np.dot(M, np.dot(M.T, Q)), mode="economic", check_finite=False)
elif power_iteration_normalizer == "QR":
# QR 归一化：更稳但计算量稍大
Q, _ = linalg.qr(np.dot(M, np.dot(M.T, Q)), mode="economic", check_finite=False)
else: # 'none'
# 不进行归一化：最快但可能导致数值爆炸
Q = np.dot(M, np.dot(M.T, Q))
# 步骤6：投影回小矩阠 B = Q.T @ M
# 现在 B 的尺寸是 (n_components + n_oversamples) x n_features
# 但我们只关心前 n_components 列对应的主子空间
B = np.dot(Q.T, M)
# 步骤7：对小矩阵 B 做精确 SVD
# 这一步的成本是 O((n_components + n_oversamples)^2 * n_features)
# 由于 n_components 通常很小，这个步骤很快
Uhat, Shat, Vhat = linalg.svd(B, full_matrices=False)
# 步骤8：将左奇异向量映射回原始空间
# U = Q @ Uhat 现在是原始空间中的近似左奇异向量
U = np.dot(Q, Uhat)
# 步骤9：处理符号翻转以确保输出的确定性
if flip_sign:
# 根据《Deterministic SVD sign flipping》论文
# 使每个奇异向量的最大绝对值元素为正
max_cols = np.argmax(np.abs(U), axis=0)
signs = np.sign(U[max_cols, range(U.shape[1])])
U *= signs
Vhat *= signs[:, np.newaxis]
# 步骤10：根据是否转置调整返回值
if transpose:
# 如果之前转置了 M，那么实际的右奇异向量是 Uhat
# 左奇异向量需要从 Vhat 获得
return Vhat[:n_components, :].T, Shat[:n_components], U[:n_components, :].T
else:
# 常规情况：U 左奇异向量，Shat 奇异值，Vhat 右奇异向量
return U[:n_components, :], Shat[:n_components], Vhat[:n_components, :]
这段代码是随机化 SVD 的核心实现，它将抽象的概率想法转化为具体的数值步骤。让我们用一个比喻来理解这个流程：想象我们要绘制一座大山的轮廓图，但只有有限的时间和资源。步骤2-3 是投放随机探针：我们向山的不同方向发射探测信号（用随机矩阵 Omega 乘以 M），这些信号的反射（Y = M@Omega）告诉我们山的主要朝向有哪些。步骤4 是对这些探测结果做正交化：通过 QR 分解，我们从众多可能的方向中提取出一组互相正交的主方向（Q），这些方向大致指向了山的主脊。步骤5 是幂迭代：我们不满足于一次探测，而是反复让信号在山上来回反射（计算 M@M.T@Q），每次反射都能让我们对主脊的判断更加精准——就像通过多次测量来减小读数误差。步骤6-7 是在局部做精细测量：我们不再在整座山上工作，而是把注意力集中在那些已经被识别出的主方向上（通过 Q.T@M 得到小矩阵 B），在这里做一次精确的测量（SVD），因为这个子问题的规模已经大大缩小。步骤8-9 是把局部测量结果映射回全景，并校正符号：我们把在局部坐标系中得到的奇异向量（Uhat）乘以基变换矩阵 Q，得到它们在原始空间中的对应方向（U），并通过确保首个非零元为正来消除符号歧义。步骤10 是根据初始是否转置来调整输出：如果我们一开始为了效率而在 M.T 上工作，那么最终的左、右奇异向量需要互换。
图 50.7：随机化 SVD 的核心算法步骤示意图
此段代码实现了随机化 SVD 的核心逻辑：首先根据矩阵形状自动决定是否转置以优化计算（当特征多于样本时转置）；然后生成高斯随机投影矩阵 Omega，计算初始近似 Y = M @ Omega；通过 QR 分解提取正交基 Q 作为值域的近似；可选地执行幂迭代（LU/QR/none 归一化）以增强对主子空间的敏感度；将原始矩阵投影到低维空间得到 B = Q.T @ M；对小矩阵 B 进行精确 SVD；将左奇异向量映射回原始空间 U = Q @ Uhat；通过符号翻转确保输出的确定性（使每个奇异向量的最大绝对值元素为正）；最后根据是否曾经转置调整返回值的顺序，以正确对应左奇异向量、奇异值和右奇异向量。这种“先降维再精求”的策略避免了对全矩阵做 SVD 的 O(n³) 成本，而是将主要计算集中在维度为 (n_components + n_oversamples) 的小矩阵上，实现了 O(nk²) 的高效近似。
51.7 设计取舍
在 scikit-learn 的 utils 模块中，设计取舍贯穿于输入验证、数值稳定性、计算效率和接口易用性之间。以 check_array 为例，其参数化设计（如 accept_sparse、force_all_finite、ensure_2d）既提供了极大的灵活性，又要求使用者理解每个参数的含义——这种取舍将复杂性从算法内部转移到了接口层面，使得核心算法可以保持简洁和高效，而验证逻辑则通过显式参数受控。同样，在有限性检测中，分层策略（快速路径 → Cython 无 GIL → NumPy 回退）在速度和覆盖面之间取得平衡：对于连续内存的密集数组，利用内存视图快速扫描；对于更复杂或非连续的情况，退而求其次使用更通用但稍慢的元素级检查；而 Cython 实现则在无 GIL 下实现了接近 C 速度的扫描，显著提升了多线程环境下的吞吐量。
随机化 SVD 的设计体现了在精度和速度之间的经典权衡：通过牺牲可控的近似误差（可由 n_oversamples 和 n_power_iterations 调整），将时间复杂度从 O(n³) 降至 O(nk²)，这使得处理大规模高维数据成为可能。其“先随机投影再小矩阵 SVD”的思路避免了对全矩阵进行昂贵的分解，而是利用概率方法捕获主子空间的近似，这在奇异值谱快速衰减的实际场景（如文本或图像特征）中尤其有效。增量均值方差算法（_incremental_mean_and_var）则在数值稳定性和增量计算之间取得平衡：它采用 Chan-Golub-LeVeque 公式来避免 naive 算法中的数值抵消，并通过 float64 累加器进一步提升精度，同时支持样本权重和 NaN 安全，使其既能处理流式数据，又能保证统计结果的可靠性。
在稀疏矩阵操作中，Gustavson 乘法（csr_matmul_csr_to_dense）选择了避免中间稀疏结构的路径：它不将稀疏乘法的结果保持为稀疏格式，而是直接累加到稠密输出中。这一取舍牺牲了对中间结果的稀疏存储优势，但获得了极佳的缓存局部性和零额外分配——特别是当输出本来就需要是稠密时（如在特征变换或协方差计算中），这种“直接累加”策略反而更高效。类似地，稀疏矩阵的均值方差计算（_csr_mean_variance_axis0）通过两遍算法和隐式零值的显式补偿，避免了将稀疏矩阵物化为稠密格式，却仍能在仅访问非零元的前提下得到精确结果——这体现了对稀疏数据内在结构的尊重和利用。
Newton-CG 优化器则在求解牛顿方程 H p = -g 时，内层共轭梯度（CG）采用了曲率保护机制：当检测到负曲率（即 p^T H p ≤ 0）时，不继续 CG 迭代，而是立即回退到最速下降方向或截断 CG。这一设计防止了在非凸或病态 Hessian 下 CG 发散的风险，将原本可能失败的二阶方法变得更为鲁棒。外层 Wolfe 线搜索则通过同时满足充分减少条件和曲率条件，确保了步长既能带来足够的损失下降，又保持了搜索方向的足够下坡性，从而在理论上保证了收敛性——尽管其计算成本高于简单的回溯线搜索，但这种取舍获得了更强的收敛保证。
最后，arrayfuncs 中的底层原语如 min_pos 和 _all_with_any_reduction_axis_1 展示了对内存效率的极致追求：min_pos 用一次遍历完成最小正值查找，避免了先过滤再求 min 的两次遍历；_all_with_any_reduction_axis_1 通过短路逻辑直接判断是否存在一行全等于某个值，而无需构建中间布尔矩阵——这在大规模数据中可以节省可观的内存带宽和分配开销。cholesky_delete 通过 Givens 旋转实现 Cholesky 分解的就地秩-1 更新，避免了重新分解的 O(n³) 成本，这在递归特征消除或协方差矩阵更新等场景中具有重要价值。
这些设计决策共同构成了 scikit-learn utils 模块的核心哲学：在不牺牲正确性的前提下，通过算法创新、内存优化、分层退避和接口解耦，为机器学习算法提供一个既高效又可靠的基础设施层。它们不是孤立的技巧，而是一套协同工作的系统，每一项取舍都是在特定的约束（速度、内存、数值稳定性、易用性）下做出的理性权衡，最终使用户能够专注于建模本身，而非陷入数据准备和数值细节的泥潭。
51.8 动手练习
-
阅读输入验证核心逻辑
-
剖析随机化 SVD 与增量统计
-
深入稀疏矩阵统计与乘法内核
-
解读 Newton-CG 优化器与有限性检测
-
探索 arrayfuncs 底层原语
51.9 本章小结
本章我们一起学习了以下概念：
| 概念 | 解释 |
|------|------|
| check_array / check_X_y | 统一输入验证标准，支持密集/稀疏/数据框，强制类型转换、维度控制、有限性检查、内存布局、写时复制、元数据同步。 |
| _assert_all_finite / cy_isfinite | 分层有限性检测：快速路径 -> Cython 无 GIL 扫描 -> NumPy 回退，支持 allow-nan 模式。 |
| randomized_svd | 随机投影构造正交基 Q，幂迭代提升精度，小矩阵 B=Q^T A 做精确 SVD，映射回大空间，支持 transpose='auto' 与 Array API。 |
| _incremental_mean_and_var | Chan-Golub-LeVeque 修正双通道算法，支持样本权重、NaN 安全、float64 累加器、Array API 多后端。 |
| csr_mean_variance_axis0 / incr_mean_variance_axis0 | 稀疏列统计：两遍算法（均值+方差修正），隐式零值分离非零统计与补偿，增量合并含首批次快路径。 |
| csr_matmul_csr_to_dense | Gustavson 算法：按 A 行遍历非零元，累加 B 对应行缩放到输出行，稀疏×稀疏→稠密，无中间稀疏结构。 |
| inplace_csr_row_normalize_l1/l2 | 原地行归一化：直接修改 CSR.data，indptr/indices 不变，空行保护避免除零。 |
| min_pos / _all_with_any_reduction_axis_1 / cholesky_delete | 极简高性能原语：最小正值、全行比较避免布尔矩阵、Cholesky 秩-1 修正（Givens 旋转）。 |
| _newton_cg / _cg / _line_search_wolfe12 | Newton-CG 二阶优化：外层牛顿迭代 + 内层 CG 求解 H p = -g，曲率保护（Capped CG/负曲率回退），Wolfe 1/2 双阶段线搜索。 |
| as_float_array / assert_all_finite | 浮点转换与有限性检查的公开便捷入口，兼容稀疏/扩展类型。 |
| validate_data / _check_feature_names / _check_n_features | 估计器级验证总控：元数据同步、重置控制、meta-estimator 委托、跳过验证模式。 |
| _randomized_eigsh / svd_flip / _deterministic_vector_sign_flip | 随机化特征分解与符号确定性修正工具族。 |
| safe_sparse_dot / row_norms / safe_sqr / make_nonnegative | 稀疏感知线性代数与数值稳定工具：混合点积、行范数、平方、非负化。 |
| inplace_column/row_scale / inplace_swap_row/column | 稀疏矩阵原地变换族：缩放、交换，CSR/CSC 统一分发。 |
| min_max_axis / count_nonzero / csc_median_axis_0 | 稀疏统计聚合：最值、非零计数（加权）、中位数（隐式零值）。 |
| _implicit_column_offset / sparse_matmul_to_dense / assign_rows_csr | 稀疏线性算子与稠密化工具：隐式中心化、Gustavson 分发、行稠密化赋值。 |
| weighted_mode / cartesian / softmax / _nanaverage / _approximate_mode / density / fast_logdet / squared_norm / stable_cumsum | 通用数学工具箱：加权众数、笛卡尔积、Softmax、NaN平均、众数近似、稀疏度、对数行列式、范数、累积和。 |
| _check_psd_eigenvalues / check_symmetric / check_scalar / check_random_state / check_is_fitted / _check_sample_weight / has_fit_parameter / check_memory / check_consistent_length / indexable | 参数校验与工具函数族：PSD特征值修正、对称性、标量边界、随机状态、拟合态、样本权重、fit参数、内存、长度一致、可索引化。 |
| _deprecate_positional_args / _estimator_has / _check_response_method / _check_monotonic_cst / _to_object_array / _check_feature_names_in / _generate_get_feature_names_out / _make_indexable / _check_pos_label_consistency / _is_fitted / _use_interchange_protocol / _get_feature_names / _is_arraylike / _is_arraylike_not_scalar / _allclose_dense_sparse / _ensure_no_complex_data / _pandas_dtype_needs_early_conversion / _check_estimator_name / _raise_error_wrong_axis / _check_method_params / _num_samples / _num_features / _check_large_sparse / _raise_typeerror / _get_median / _get_elem_at_rank | 内部辅助工具集：弃用装饰器、委托检查、响应方法、单约束、对象数组、特征名、索引化、标签一致性、拟合态、互换协议、类数组判断、稠密稀疏比较、复数拦截、扩展类型转换、估计器名、轴检查、方法参数、样本/特征数、大索引、类型报错、中位数辅助。 |
| _sqeuclidean_row_norms_sparse / _isfinite / _isfinite_allow_nan / _isfinite_disable_nan | Cython 无 GIL 底层内核：行平方范数、有限性扫描（双模式）。 |
| _safe_accumulator_op / _nanaverage / _incremental_mean_and_var | 数值稳定累加体系：精度保护、NaN平均、增量均值方差核心。 |
51.10 生活类比
想象 scikit-learn 的 utils 模块是算法战场上的“瑞士军刀后勤部”： check_array / check_X_y = 严格的安检员：拦截脏数据、统一格式、核对身份（特征名/数量），只有合格兵员（张量）才能进入训练前线 cy_isfinite = 无人机巡逻：无 GIL、C 级速度，极速扫描 NaN/Inf 地雷，标记位置即撤，不拖慢主力部队 randomized_svd = 概率侦察兵：不用全量扫描地形（全矩阵 SVD），随机投影几轮就能画出地形主脉（主奇异向量），以 O(n k²) 换 O(n³) 的战略欺骗 增量均值方差 = 流式补给官：物资（数据批次）分批到达，用 Chan-Golub-LeVeque 公式实时更新仓库账本（均值/方差），无需卸空重算，支持加权、抗抵消、可断点续传 稀疏统计内核 = 专攻稀疏地形的工兵：只踩非零格子（CSR/CSC 非零元），隐式零值用补偿项修正，单次遍历出均值、两遍出方差，绝不把稀疏地图强行铺成稠密沼泽 Gustavson 乘法 = 稀疏物流专线：A 的每辆非零货车（非零元）直奔 B 对应仓库行，卸货累加到稠密仓库，无中间转运站（稀疏中间结构），缓存友好、零拷贝 Newton-CG = 重型攻城炮：外层牛顿方向定战略目标（二阶曲率），内层 CG 迭代战术推进（共轭梯度），Wolfe 线搜索做火力侦察（步长），曲率为负即刻回退最速下降或封炮 arrayfuncs 原语 = 微创手术刀：min_pos 单刀切最小正值、cholesky_delete 原地修正分解、全行比较不产生临时废料（布尔矩阵），极致内存节俭
51.11 架构与数据流图
上述图分别展示模块依赖、调用时序、数据流和架构分层。
51.12 设计取舍
为什么采用当前方案而不是更复杂的替代方案？ 本章实现优先保证与既有 API 的一致性、可维护性与运行效率。这意味着在少数极端场景下，调用者需要自行在灵活性、内存与速度之间做取舍，换取默认路径的清晰与稳定。
第 52 章 —— utils 参数管理与元编程 —— 触摸“估计器的内在骨架”
52.1 学习目标
-
难度：★★★☆☆（3/5）
-
预备知识：Python 基础、面向对象编程与 Markdown/代码阅读基础
-
理解输入验证核心流程：掌握
check_array/check_X_y如何通过参数约束实现类型转换、维度检查、缺失值处理与有限性验证 -
掌握参数约束与校验体系：理解
Interval、StrOptions等约束类配合validate_params装饰器实现“编译期般的严格检查” -
洞察估计器标签系统：从
InputTags到ClassifierTags，理解标签如何描述估计器的能力边界，驱动自动化测试与元估计器行为 -
解析元估计器参数路由：理解双下划线参数语法与
_BaseComposition，掌握Pipeline等组合器如何安全分派参数 -
熟悉 utils 公共 API 聚合：理解
sklearn/utils/__init__.py如何统一暴露验证、数学、稀疏、随机、索引、编码、标签、元估计器等核心工具
52.2 生活类比（段落式叙述）
想象 scikit‑learn 的 utils 模块 就像是前线作战部队的后勤指挥中心。输入验证（validation.py）是进站的安检门，所有进入战场的数据——无论是稠密的 NumPy 数组、稀疏的 CSR/CSC 矩阵，还是 pandas / Polars DataFrame——都必须通过多层检查：维度对齐、数据类型强制转换、缺失值与无穷值检测。参数约束（_param_validation.py）相当于装配线上实时的编译器：Interval、StrOptions、HasMethods 等约束类在函数调用时对参数进行“类型系统”检查，确保非法参数在最早阶段被捕获。标签系统（_tags.py）则是每个估计器的身份证，InputTags 记录它能否接受稀疏矩阵、缺失值或成对矩阵；ClassifierTags 标记它是否支持多分类或多标签，从而让自动化测试能够快速匹配能力边界。元估计器工具（metaestimators.py）充当指挥调度中心，_BaseComposition 通过双下划线语法 (estimator__param) 完成参数的层级路由，_safe_split 则确保在交叉验证阶段对预计算核矩阵进行同步切片。发现机制（discovery.py）像是一张全局点名册，自动遍历整个 sklearn 包树，收集所有非私有的估计器、可视化 Display 类以及公共函数，支撑自动化测试与文档生成。属性式字典 Bunch 则是后勤物资清单的灵活容器，键值既能用字典方式访问，也能通过属性点取，且兼容键的弃用警告与旧版 pickle。最终，这一切都通过 统一门面 __init__.py 汇聚在一起，形成了一个“瑞士军刀”般的后勤补给站，供下游估计器直接 from sklearn.utils import … 使用。
52.3 源码地图
sklearn/utils/validation.py
├── 核心验函数
│ ├── check_array() # 统一数组验证入口
│ ├── check_X_y() # X/y 联合验证
│ ├── check_consistent_length()
│ ├── assert_all_finite()
│ ├── check_scalar()
│ ├── check_random_state()
│ ├── column_or_1d()
│ ├── indexable()
│ ├── _check_sample_weight()
│ └── _num_samples()
├── 辅助工具
│ ├── _is_arraylike_not_scalar()
│ ├── _is_pandas_df() / _is_polars_df()
│ └── _ensure_sparse_format()
└── 参数约束集成
└── validate_params() # 装饰器（见 _param_validation.py）
sklearn/utils/_param_validation.py
├── 约束类体系
│ ├── Interval
│ ├── StrOptions
│ ├── Options
│ ├── HasMethods
│ ├── MissingValues
│ ├── _ArrayLikes
│ ├── _SparseMatrices
│ ├── _Callables
│ ├── _RandomStates
│ ├── _Booleans
│ ├── _VerboseHelper
│ ├── _CVObjects
│ ├── _NoneConstraint
│ ├── _NanConstraint
│ ├── _PandasNAConstraint
│ ├── _InstancesOf
│ ├── _IterablesNotString
│ └── Hidden
├── 核心校验逻辑
│ ├── validate_parameter_constraints()
│ ├── make_constraint()
│ └── validate_params()
└── 测试辅助工具
├── generate_invalid_param_val()
└── generate_valid_param()
sklearn/utils/_tags.py
├── 数据标签类
│ ├── InputTags
│ └── TargetTags
├── 任务标签类
│ ├── TransformerTags
│ ├── ClassifierTags
│ └── RegressorTags
├── 统一容器
│ └── Tags
└── 标签获取接口
└── get_tags()
sklearn/utils/metaestimators.py
├── 基类组合器
│ └── _BaseComposition
├── 参数管理核心
│ ├── _get_params()
│ ├── _set_params()
│ ├── _replace_estimator()
│ ├── _validate_names()
│ └── _check_estimators_are_instances()
└── 安全切分工具
└── _safe_split()
sklearn/utils/discovery.py
├── 估计器发现
│ └── all_estimators()
├── 显示器发现
│ └── all_displays()
├── 函数发现
│ └── all_functions()
└── 内部工具
└── _is_checked_function()
sklearn/utils/_available_if.py
├── 条件描述符
│ └── _AvailableIfDescriptor
└── 装饰器接口
└── available_if()
sklearn/utils/_bunch.py
└── Bunch
├── __init__()
├── __getitem__()
├── _set_deprecated()
├── __setattr__()
├── __dir__()
├── __getattr__()
└── __setstate__()
sklearn/utils/__init__.py
└── 公共 API 聚合
├── 验证工具（check_array、check_X_y 等）
├── 数学工具（safe_sqr、randomized_svd 等）
├── 稀疏操作（inplace_csr_row_scale 等）
├── 随机工具（check_random_state 等）
├── 索引采样（_safe_indexing、resample、shuffle）
├── 编码唯一（_encode、_unique）
├── 标签系统（InputTags、TargetTags、Tags、get_tags）
├── 元估计器（_BaseComposition、available_if、_safe_split）
├── 发现工具（all_estimators、all_displays、all_functions）
├── 容器工具（Bunch、deprecated）
├── 权重计算（compute_class_weight、compute_sample_weight）
├── 掩码缺失（safe_mask、is_scalar_nan）
├── HTML 可视化（_HTMLDocumentationLinkMixin、estimator_html_repr）
└── 元数据路由（metadata_routing）
52.4 输入验证核心 —— 智能安检门
52.4.1 关键流程概览
52.4.2 check_array（逐行注释）
def check_array(
array,
accept_sparse=False,
*,
accept_large_sparse=True,
dtype="numeric",
order=None,
copy=False,
force_writeable=False,
ensure_all_finite=True,
ensure_non_negative=False,
ensure_2d=True,
allow_nd=False,
ensure_min_samples=1,
ensure_min_features=1,
estimator=None,
input_name="",
):
"""输入验证入口：统一处理 NumPy、稀疏、DataFrame、列表等容器。"""
# 1️⃣ 禁止 np.matrix，提示使用 np.asarray
if isinstance(array, np.matrix):
raise TypeError(
"np.matrix is not supported. Please convert to a numpy array with "
"np.asarray. For more information see: "
"https://numpy.org/doc/stable/reference/generated/numpy.matrix.html"
)
# 2️⃣ 根据输入类型获取对应的命名空间（NumPy / Array API）
xp, is_array_api_compliant = get_namespace(array)
# 3️⃣ 保存原始对象用于后续 copy 判定
array_orig = array
# 4️⃣ 判断是否请求 “numeric” dtype（即默认转为 float）
dtype_numeric = isinstance(dtype, str) and dtype == "numeric"
# …（省略大量中间逻辑：稀疏格式处理、pandas dtype 早期转换、dtype 检查）…
# 5️⃣ 样本数下限检查
if ensure_min_samples > 0:
n_samples = _num_samples(array)
if n_samples < ensure_min_samples:
raise ValueError(
"Found array with %d sample(s) (shape=%s) while a"
" minimum of %d is required%s."
% (n_samples, array.shape, ensure_min_samples, context)
)
# 6️⃣ 特征数下限检查（仅在二维情况下）
if ensure_min_features > 0 and array.ndim == 2:
n_features = array.shape[1]
if n_features < ensure_min_features:
raise ValueError(
"Found array with %d feature(s) (shape=%s) while"
" a minimum of %d is required%s."
% (n_features, array.shape, ensure_min_features, context)
)
# 7️⃣ 正数约束（可选）
if ensure_non_negative:
whom = input_name
if estimator_name:
whom += f" in {estimator_name}"
check_non_negative(array, whom)
# 8️⃣ 强制返回可写数组（必要时复制）
if force_writeable:
copy_params = {"order": "K"} if not sp.issparse(array) else {}
array_data = array.data if sp.issparse(array) else array
flags = getattr(array_data, "flags", None)
if not getattr(flags, "writeable", True):
if is_pandas_df_or_series(array_orig):
try:
array_data.flags.writeable = True
except ValueError:
array = array.copy(**copy_params)
else:
array = array.copy(**copy_params)
# 9️⃣ 最终返回已验证、可能拷贝的数组
return array
解释：上述 check_array 函数完成了从原始输入到验证后输出的完整流程。它首先拒绝不支持的 np.matrix 类型，然后获取适当的数值库命名空间（NumPy 或 Array API），保存原始对象以决定是否需要复制，并检查是否需要将数据转换为数值型。随后处理稀疏矩阵格式、pandas DataFrame 的早期 dtype 转换等，执行样本数和特征数的下限检查，以及可选的非负约束。最后，它根据 force_writeable 参数确保输出数组是可写的（必要时复制），并返回处理后的数组。这个函数是 scikit-learn 输入验证的基石，确保所有估计器收到的数据符合预期的格式和约束。
52.4.3 check_X_y（逐行注释）
def check_X_y(
X,
y,
accept_sparse=False,
*,
accept_large_sparse=True,
dtype="numeric",
order=None,
copy=False,
force_writeable=False,
ensure_all_finite=True,
ensure_2d=True,
allow_nd=False,
multi_output=False,
ensure_min_samples=1,
ensure_min_features=1,
y_numeric=False,
estimator=None,
):
"""X / y 联合验证：先检查 X，再检查 y，最后确保样本数对齐。"""
# 1️⃣ y 为 None 时抛出错误，指明是哪一个估计器缺失 y
if y is None:
if estimator is None:
estimator_name = "estimator"
else:
estimator_name = _check_estimator_name(estimator)
raise ValueError(
f"{estimator_name} requires y to be passed, but the target y is None"
)
# 2️⃣ 调用统一的 check_array 对 X 进行完整检验
X = check_array(
X,
accept_sparse=accept_sparse,
accept_large_sparse=accept_large_sparse,
dtype=dtype,
order=order,
copy=copy,
force_writeable=force_writeable,
ensure_all_finite=ensure_all_finite,
ensure_2d=ensure_2d,
allow_nd=allow_nd,
ensure_min_samples=ensure_min_samples,
ensure_min_features=ensure_min_features,
estimator=estimator,
input_name="X",
)
# 3️⃣ 对 y 执行专门的检查（支持多维输出或强制 1D）
y = _check_y(y, multi_output=multi_output, y_numeric=y_numeric, estimator=estimator)
# 4️⃣ 检查 X 与 y 的样本数是否一致
check_consistent_length(X, y)
# 5️⃣ 返回已验证的 X, y
return X, y
解释：check_X_y 函数封装了特征矩阵 X 和目标向量 y 的联合验证逻辑。它首先检查 y 是否为 None，如果是则抛出带有估计器名称的错误信息。然后，它调用 check_array 对 X 进行全面验证，包括类型转换、维度检查、稀疏处理等。接下来，它使用 _check_y 函数对 y 进行专门验证，该函数支持多输出情况和数值类型强制转换。最后，它通过 check_consistent_length 确保 X 和 y 在样本数上保持一致，这是监督学习的基本要求。通过这种分层验证方式，check_X_y 为估计器的 fit 方法提供了可靠的输入预处理。
52.4.4 assert_all_finite（逐行注释）
def assert_all_finite(
X,
*,
allow_nan=False,
estimator_name=None,
input_name="",
):
"""若输入含有 NaN/Inf 则抛 ValueError，allow_nan 可容忍 NaN。"""
_assert_all_finite(
X.data if sp.issparse(X) else X, # 对稀疏矩阵只检查 data 部分
allow_nan=allow_nan,
estimator_name=estimator_name,
input_name=input_name,
)
解释：assert_all_finite 是一个轻量级包装函数，其核心职责是调用内部函数 _assert_all_finite 来检查输入数据中是否存在非有限值（NaN 或 infinity）。对于稀疏矩阵输入，它仅检查 .data 属性（存储非零值），因为稀疏结构本身不包含显式的零值，因此无需检查。该函数支持通过 allow_nan 参数选择性地允许 NaN 值通过检查（而 infinity 仍会被拒绝），并在检测到问题时提供上下文丰富的错误信息，其中可能包含估计器名称和输入名称，以帮助用户定位问题来源。这个函数在诸如 check_array、check_X_y 等验证函数中被频繁调用，是确保数值稳定性的重要防线。
52.5 参数约束体系 —— “编译期级别的静态分析器”
52.5.1 约束类层级结构（Mermaid）
52.5.2 Interval（逐行注释）
class Interval(_Constraint):
"""数值区间约束，支持开闭区间、整数/实数、无穷边界。"""
def __init__(self, type, left, right, *, closed):
super().__init__()
self.type = type # Integral / Real / RealNotInt
self.left = left # 左边界，可为 None（-∞）
self.right = right # 右边界，可为 None（+∞）
self.closed = closed # "left", "right", "both", "neither"
self._check_params() # 参数合法性检查
def _check_params(self):
# 检查 type 必须是 Integral / Real / RealNotInt
if self.type not in (Integral, Real, RealNotInt):
raise ValueError(...)
# 检查 closed 必须是合法标识
if self.closed not in ("left", "right", "both", "neither"):
raise ValueError(...)
# 对整数区间进行更严格的类型检查
if self.type is Integral:
if self.left is not None and not isinstance(self.left, Integral):
raise TypeError(...)
if self.right is not None and not isinstance(self.right, Integral):
raise TypeError(...)
# 左闭或两侧闭时，左边界不能为 None（同理右边界）
if self.left is None and self.closed in ("left", "both"):
raise ValueError(...)
if self.right is None and self.closed in ("right", "both"):
raise ValueError(...)
else:
# 实数区间：左/右边界必须是 Real
if self.left is not None and not isinstance(self.left, Real):
raise TypeError(...)
if self.right is not None and not isinstance(self.right, Real):
raise TypeError(...)
# 确保右边界大于左边界
if self.right is not None and self.left is not None and self.right <= self.left:
raise ValueError(...)
def __contains__(self, val):
# NaN 对整数区间永远不在集合中
if not isinstance(val, Integral) and np.isnan(val):
return False
# 根据 closed 选择比较运算符
left_cmp = operator.lt if self.closed in ("left", "both") else operator.le
right_cmp = operator.gt if self.closed in ("right", "both") else operator.ge
left = -np.inf if self.left is None else self.left
right = np.inf if self.right is None else self.right
# 左侧检查
if left_cmp(val, left):
return False
# 右侧检查
if right_cmp(val, right):
return False
return True
def is_satisfied_by(self, val):
# 先判断类型，再判断是否在区间内
if not isinstance(val, self.type):
return False
return val in self
def __str__(self):
# 生成易读的区间描述，例如 "[0, 10)"
type_str = "an int" if self.type is Integral else "a float"
left_bracket = "[" if self.closed in ("left", "both") else "("
right_bracket = "]" if self.closed in ("right", "both") else ")"
left_bound = "-inf" if self.left is None else self.left
right_bound = "inf" if self.right is None else self.right
return f"{type_str} in the range {left_bracket}{left_bound}, {right_bound}{right_bracket}"
解释：Interval 类实现了对数值参数的区间约束，是 scikit-learn 参数验证系统中的基石。它支持整数（Integral）、实数（Real）以及非整数实数（RealNotInt）三种数值类型，并允许指定左边界和右边界（可为 None 表示无穷大），以及区间的开闭性（通过 closed 参数）。在初始化时，_check_params 方法会严格验证传入参数的合法性，例如确保类型正确、边界类型匹配、区间不为空等。__contains__ 方法定义了值是否落在区间内的逻辑，特别处理了整数区间中 NaN 永远不满足的情况。is_satisfied_by 方法先检查值的类型是否匹配，再调用 __contains__ 判断是否在区间内。最后，__str__ 方法提供了人类可读的字符串表示，例如 "an int in the range [0, 10)"，这在生成用户友好的错误信息时至关重要。
52.5.3 StrOptions（逐行注释）
class StrOptions(Options):
"""有限字符串集合约束，支持对某些选项标记为 deprecated。"""
def __init__(self, options, *, deprecated=None):
# 直接调用父类 Options 完成初始化
super().__init__(type=str, options=options, deprecated=deprecated)
解释：StrOptions 是 Options 类的一个专门子类，用于约束参数必须是一组预定义字符串中的一个。它通过将 type 参数固定为 str 来实现这一功能，同时继承了 Options 处理选项集合和已废弃选项标记的能力。这种设计使得在需要限制字符串参数取值范围的场景下（例如 solver 参数只能是 'lgbfgs'、'sgd' 等），可以简洁地声明约束。其父类 Options 的 __str__ 方法已经能够生成如 "a str among {'lbfgs', 'sgd', 'adam'}" 的描述，而 StrOptions 无需额外实现即可继承这一行为。此外，通过 deprecated 参数，库维护者可以标记某些选项即将被移除，在错误信息中以 (deprecated) 形式提示用户，从而在不破坏向后兼容性的前提下进行API演进。
52.5.4 HasMethods（逐行注释）
class HasMethods(_Constraint):
"""鸭子类型约束：对象必须实现指定的方法列表。"""
@validate_params(
{"methods": [str, list]}, # 方法名必须是字符串或字符串列表
prefer_skip_nested_validation=True,
)
def __init__(self, methods):
super().__init__()
# 若仅传入单个字符串，统一转为列表
if isinstance(methods, str):
methods = [methods]
self.methods = methods
def is_satisfied_by(self, val):
# 所有方法都必须是可调用的
return all(callable(getattr(val, method, None)) for method in self.methods)
def __str__(self):
# 人类可读的描述，例如 "an object implementing 'split' and 'get_n_splits'"
if len(self.methods) == 1:
methods = f"{self.methods[0]!r}"
else:
methods = (
f"{', '.join([repr(m) for m in self.methods[:-1]])} and"
f" {self.methods[-1]!r}"
)
return f"an object implementing {methods}"
解释：HasMethods 约束实现了鸭子类型检查的核心思想：它不关心对象的具体类型，而只关心对象是否具备某些特定的方法。这使得它特别适用于需要验证对象遵循某个接口（如交叉验证器必须有 split 和 get_n_splits 方法）但又不想强制继承特定基类的场景。在 __init__ 中，它接受单个字符串或字符串列表形式的方法名，并统一处理为列表以简化后续逻辑。is_satisfied_by 方法使用 getattr 安全地获取对象的属性，并通过 callable 检查确保该属性确实是一个可调用的方法；只有当所有指定方法都满足此条件时，才返回 True。__str__ 方法则生成易于理解的自然语言描述，例如 "an object implementing 'split' and 'get_n_splits'"，这在参数验证失败时能够帮助用户快速理解缺失了什么能力。该装饰器自身也使用了 @validate_params 来确保其构造参数的合法性，并启用了 prefer_skip_nested_validation 以避免在内部验证中重复检查。
52.5.5 validate_parameter_constraints 关键流程（补充解释）
validate_parameter_constraints 会遍历提供的 params，对每个参数检索对应的约束列表（已通过 make_constraint 转化为约束对象），然后逐个检查是否满足任意约束；若全部失败，则过滤掉内部隐藏约束后构造错误信息，抛出 InvalidParameterError。错误信息形如：
The
'max_iter'parameter ofLogisticRegressionmust be an int in the range[1, 1000]orNone. Got'fast'instead.
这保证了用户在调用公共 API 时能够得到 明确、可操作的错误提示，并且对内部实现约束（例如仅供内部使用的 _CVObjects）保持隐藏。
52.5.6 validate_params 装饰器（补充细节）
-
全局开关：通过
sklearn.get_config()["skip_parameter_validation"]可以一次性关闭所有校验，适用于对性能极度敏感的内部函数。 -
嵌套验证控制：
prefer_skip_nested_validation=True会在装饰的函数内部调用其他已装饰函数时自动跳过二次校验，避免在公共 API 已经完成校验后重复验证提升运行效率。 -
异常重包装：如果内部函数因参数不合法抛出
InvalidParameterError，装饰器会捕获并将错误信息中的调用者名称替换为外层函数的完整限定名（func.__qualname__），确保错误指向用户实际调用的位置，而不是内部实现细节。
整体上，validate_params 将 声明式约束、全局开关、嵌套优化以及用户友好错误信息 融合为一个统一的装饰器，贯穿整个 sklearn 参数校验体系。
52.6 估计器标签系统 —— 能力身份证体系
52.6.1 标签类层级（Mermaid）
52.6.2 InputTags（逐行注释）
@dataclass(slots=True)
class InputTags:
"""描述 X 的能力边界，例如维度、稀疏、缺失值、成对矩阵等。"""
one_d_array: bool = False # 能否接受 1D 数据
two_d_array: bool = True # 能否接受 2D 数据（默认 True）
three_d_array: bool = False # 能否接受 3D 数据
sparse: bool = False # 是否支持稀疏矩阵
categorical: bool = False # 是否接受分类特征
string: bool = False # 是否接受字符串数组
dict: bool = False # 是否接受字典输入
positive_only: bool = False # 是否要求所有数值为正
allow_nan: bool = False # 是否容忍 NaN
pairwise: bool = False # 是否为成对矩阵（影响 _safe_split）
解释：InputTags 使用 @dataclass(slots=True) 定义，这是一种现代 Python 的高效方式来声明具有固定属性的轻量级对象。每个布尔字段描述了估计器在特征矩阵 X 方面的能力或限制。例如，sparse: bool = False 表示该估计器默认不支持稀疏输入；如果设为 True，则表明它可以处理 CSR、CSC 等格式的稀疏矩阵。allow_nan 控制是否容忍缺失值，这在如 HistGradientBoostingClassifier 这样的估计器中为 True。pairwise 标记特别重要，它表示输入数据是否为成对关系（如预计算的核矩阵），这会影响 _safe_split 在交叉验证中是否需要同步切片行和列。通过这种方式，InputTags 为元估计器和通用检查工具提供了一个统一的、可内省的接口来查询估计器的数据处理能力，而无需依赖继承结构或文档。
52.6.3 TargetTags（逐行注释）
@dataclass(slots=True)
class TargetTags:
"""描述 y 的需求与约束。"""
required: bool # 是否必须提供 y（回归/分类为 True）
one_d_labels: bool = False # 是否接受 1D 标签
two_d_labels: bool = False # 是否接受 2D 标签（多标签/多输出）
positive_only: bool = False # 回归是否要求正数目标
multi_output: bool = False # 是否支持多输出（回归或多标签分类）
single_output: bool = True # 是否仅支持单输出
解释：TargetTags 同样使用 @dataclass(slots=True) 来高效地描述目标变量 y 的需求。required 字段是最核心的指标之一：对于继承自 RegressorMixin 或 ClassifierMixin 的估计器，该值为 True，表示它们在 fit 过程中必须接收有效的目标数据；而对于无监督估计器（如聚类），则通常为 False。one_d_labels 和 two_d_labels 分别控制是否接受一维（如标量标签）或二维（如多标签或多目标回归）的目标格式。positive_only 在回归场景中使用，指示目标值是否必须为非负数（例如在 Poisson 回归中）。multi_output 表明估计器是否能够处理多目标输出情况，这在多标签分类或多输出回归中很常见。最后，single_output 与 multi_output 互补，默认为 True，表示估计器通常期望单输出，除非显式声明支持多输出。这些标签共同使得 scikit-learn 能够在元编程场景（如自动化测试生成或元估计器构造）中精确推断估计器的目标变量处理能力。
52.6.4 TransformerTags、ClassifierTags、RegressorTags（省略逐行注释，仅展示字段）
-
TransformerTags：
preserves_dtype（列表，指明transform后保持的 dtype） -
ClassifierTags：
poor_score（弱基学习器标记）、multi_class（多分类能力）、multi_label（多标签能力） -
RegressorTags：
poor_score（弱基学习器标记）
解释：这些任务特有的标签类进一步细化了估计器在特定机器学习任务中的行为。TransformerTags.preserves_dtype 列出了在调用 transform 方法时，哪些数据类型会被保持不变（例如某些稀疏转换器可能保持 float64 但不保持 int32），这对于流水线中的类型一致性至关重要。ClassifierTags 中的 poor_score 用于标记那些在特定基准测试中表现较弱的分类器（常用作基学习器在集成方法中），而 multi_class 和 multi_label 则分别表示该分类器是否能够处理超过两个类别的情况，以及是否允许单个样本属于多个类别。RegressorTags 仅包含 poor_score 字段，用于同样目的地标记弱回归基学习器。这些标签不仅用于文档和可解释性，更重要的是驱动了 scikit-learn 内部的自动化测试选择、元估计器行为（如 BaggingClassifier 如何选择基学习器）以及用户级别的模型选择引导。
52.6.5 Tags 与 get_tags
Tags 聚合了所有子标签并加入了全局开关（如 no_validation、non_deterministic），从而在 元估计器 中统一查询能力。
get_tags(estimator) 首先检查 estimator 是否为实例，然后调用其 __sklearn_tags__()；若缺失或 MRO 错误，会给出明确的继承建议。
解释：Tags 类是整个标签系统的顶层容器，它通过 @dataclass(slots=True) 高效地组合了所有维度的能力描述：从数据处理能力（input_tags、target_tags）到任务特有行为（classifier_tags、regressor_tags、transformer_tags），再到全局运行属性（如是否需要拟合、是否确定性、是否跳过测试等）。通过这种结构化的方式，元估计器可以在不实例化子估计器的情况下，仅通过检查其标签来决定是否可以安全地进行参数路由、数据切分或方法委托。get_tags 函数作为对外的统一入口，封装了获取标签的逻辑，并增加了健壮性检查：它会拒绝将类（而非实例）传入其中，并在底层实现缺失时提供清晰的错误信息和继承建议，引导用户正确地从 BaseEstimator 继承并实现 __sklearn_tags__ 方法。这种设计使得标签系统既灵活又安全，是 scikit-learn 元编程能力的重要基石。
52.7 元估计器参数路由与组合基类 —— 参数分发总调度中心
52.7.1 参数路由整体视图（Mermaid）
52.7.2 _BaseComposition._get_params（逐行注释）
def _get_params(self, attr, deep=True):
# 1️⃣ 调用 BaseEstimator 的标准 get_params，获取非嵌套参数
out = super().get_params(deep=deep)
if not deep:
return out
# 2️⃣ 读取存放子估计器的属性（如 self.estimators）
estimators = getattr(self, attr)
try:
# 3️⃣ 尝试把子估计器列表直接合并进输出 dict
out.update(estimators)
except (TypeError, ValueError):
# 若属性不是 (name, estimator) 列表，保持原样返回，防止 set_params 崩溃
return out
# 4️⃣ 对每个子估计器递归获取其 own 参数
for name, estimator in estimators:
if hasattr(estimator, "get_params"):
for key, value in estimator.get_params(deep=True).items():
# 使用双下划线语法拼接键名
out["%s__%s" % (name, key)] = value
return out
解释：_get_params 方法是元估计器参数内省机制的核心。它首先调用父类 BaseEstimator.get_params() 来获取当前复合估计器自身的参数（如 Pipeline 的 memory 或 verbose），除非 deep=False 时直接返回。在深度模式下，它继续检查由 attr 指定的属性（例如 Pipeline 中的 steps 或 FeatureUnion 中的 transformer_list），该属性应包含 (name, estimator) 元组的列表。它尝试将这个列表直接合并到输出字典中，以便像 named_steps 那样直接访问子估计器实例；如果属性格式不正确（不是可迭代的 (name, estimator) 对），则捕获异常并返回已有的参数，以避免在 set_params 中崩溃。然后，它遍历每个子估计器，如果该估计器实现了 get_params 方法（所有 scikit-learn 估计器都应实现），则递归获取其所有深度参数，并使用双下划线命名规则（例如 clf__C、vect__max_df）将它们加入结果字典中。这种机制使得 GridSearchCV 等工具能够透明地访问和修改管道中任意层级的参数，而无需知道内部结构。
52.7.3 _BaseComposition._set_params（逐行注释）
def _set_params(self, attr, **params):
# 1️⃣ 若提供了完整的子估计器列表，先整体替换
if attr in params:
setattr(self, attr, params.pop(attr))
# 2️⃣ 替换单个子估计器（不含双下划线的键）
items = getattr(self, attr)
if isinstance(items, list) and items:
# 提取所有子估计器的名称
with suppress(TypeError):
item_names, _ = zip(*items)
for name in list(params.keys()):
if "__" not in name and name in item_names:
# 替换对应子估计器实例
self._replace_estimator(attr, name, params.pop(name))
# 3️⃣ 将剩余的双下划线键交给 BaseEstimator 处理（递归设置子估计器参数）
super().set_params(**params)
return self
解释：_set_params 方法实现了参数的递归设置，是 _get_params 的互补操作。它遵循严格的三步策略来处理传入的参数字典：首先，如果参数字典中包含与子估计器容器属性名（如 steps）匹配的键，则整体替换该容器（例如一次性替换整个 Pipeline 的步骤列表），并从待处理参数中移除该键。其次，它检查剩余的参数中是否有不包含双下划线的键（如 clf、vect），这些键被解释为对特定子估计器的整体替换请求。它从子估计器列表中提取所有名称（通过 zip(*items) 安全地解包），然后遍历参数键：如果某个键恰好匹配一个子估计器的名称且不包含 __（避免与参数路由冲突），则调用 _replace_estimator 方法用提供的新实例替换旧的子估计器。最后，所有剩余的参数（此刻必定包含双下划线，如 clf__C 或 vect__stop_words）被传递给父类 BaseEstimator.set_params()，该方法会再次调用 _get_params 来定位目标子估计器并递归设置其内部参数。这种分层处理确保了参数设置的正确性和顺序性，避免了冲突，并支持既可以替换整个组件，也可以微调其内部超参数的灵活需求。
52.7.4 _safe_split（逐行注释）
def _safe_split(estimator, X, y, indices, train_indices=None):
"""在交叉验证时安全切分数据，兼容成对核矩阵。"""
# 1️⃣ 判断估计器是否标记 pairwise（需要同步行列切片）
if get_tags(estimator).input_tags.pairwise:
if not hasattr(X, "shape"):
raise ValueError(
"Precomputed kernels or affinity matrices have "
"to be passed as arrays or sparse matrices."
)
# 2️⃣ 确保 X 为方阵
if X.shape[0] != X.shape[1]:
raise ValueError("X should be a square kernel matrix")
# 3️⃣ 根据是否提供 train_indices 决定切片方式
if train_indices is None:
X_subset = X[np.ix_(indices, indices)]
else:
X_subset = X[np.ix_(indices, train_indices)]
else:
# 普通数据仅切行
X_subset = _safe_indexing(X, indices)
# 4️⃣ y 只切第一维
if y is not None:
y_subset = _safe_indexing(y, indices)
else:
y_subset = None
return X_subset, y_subset
解释：_safe_split 是元估计器（特别是交叉验证相关工具）在数据切分时处理特殊输入类型的关键函数。它的核心职责是根据估计器的 input_tags.pairwise 标记来决定如何切分输入数据 X。当该标记为 True 时（例如在使用预计算核矩阵的 SVM 或谱聚类中），函数会首先验证 X 确实具备 shape 属性（排除列表等不适用的类型），并确保其为方阵，因为成对核矩阵在数学上必须是对称的方阵。然后，它使用高级索引 np.ix_ 来构建索引元组：如果未提供 train_indices（常见于留一交叉验证），则使用相同的 indices 切分行和列；如果提供了 train_indices（如 k 折交叉验证中训练集索引），则用 indices 作为行索引（测试集）、train_indices 作为列索引（训练集），从而正确地提取出测试样本在训练样本上的核值。对于非成对数据（大多数情况），它简单地调用 _safe_indexing 仅按行切分 X，这是标准的特征矩阵行为。目标变量 y （如果存在）始终只按第一维切分，因为它代表的是每个样本的标签，与特征的内部结构无关。通过这种机制，_safe_split 确保了交叉验证过程中数据切分的语义正确性，无论是处理普通特征还是预计算相似度矩阵。
52.8 发现机制、条件容器与公共门面 —— 自动化点名册与属性式字典
52.8.1 all_estimators（逐行注释）
def all_estimators(type_filter=None):
"""遍历 sklearn 包，收集所有非抽象的 BaseEstimator 子类。"""
# 延迟导入 BaseEstimator 与各类 Mixin，防止循环依赖
from sklearn.base import (
BaseEstimator,
ClassifierMixin,
ClusterMixin,
RegressorMixin,
TransformerMixin,
)
from sklearn.utils._testing import ignore_warnings
# 判断类是否为抽象基类
def is_abstract(c):
if not (hasattr(c, "__abstractmethods__")):
return False
if not len(c.__abstractmethods__):
return False
return True
all_classes = []
root = str(Path(__file__).parent.parent) # sklearn 包根目录
# 捕获并忽略潜在的 FutureWarning
with ignore_warnings(category=FutureWarning):
for _, module_name, _ in pkgutil.walk_packages(path=[root], prefix="sklearn."):
# 跳过 tests、externals、experimental 等私有模块
module_parts = module_name.split(".")
if (
any(part in _MODULE_TO_IGNORE for part in module_parts)
or "._" in module_name
):
continue
module = import_module(module_name)
# 只保留非私有类
classes = inspect.getmembers(module, inspect.isclass)
classes = [(name, est_cls) for name, est_cls in classes if not name.startswith("_")]
all_classes.extend(classes)
# 去重
all_classes = set(all_classes)
# 过滤出真实的估计器（排除 BaseEstimator 本身）
estimators = [c for c in all_classes if (issubclass(c[1], BaseEstimator) and c[0] != "BaseEstimator")]
# 移除抽象基类
estimators = [c for c in estimators if not is_abstract(c[1])]
# ---------- 类型过滤 ----------
if type_filter is not None:
if not isinstance(type_filter, list):
type_filter = [type_filter]
else:
type_filter = list(type_filter) # copy
filtered_estimators = []
filters = {
"classifier": ClassifierMixin,
"regressor": RegressorMixin,
"transformer": TransformerMixin,
"cluster": ClusterMixin,
}
for name, mixin in filters.items():
if name in type_filter:
type_filter.remove(name)
filtered_estimators.extend(
[est for est in estimators if issubclass(est[1], mixin)]
)
estimators = filtered_estimators
if type_filter:
raise ValueError(
"Parameter type_filter must be 'classifier', "
"'regressor', 'transformer', 'cluster' or "
"None, got"
f" {type_filter!r}."
)
# 排序以保证可重复性
return sorted(set(estimators), key=itemgetter(0))
解释：all_estimators 函数是 scikit-learn 用于自动化发现所有具体估计器的核心工具，广泛用于测试、文档生成和 API 一致性检查。它通过延迟导入避免循环依赖，然后使用 pkgutil.walk_packages 递归遍历整个 sklearn 包目录，跳过诸如 tests、externals、experimental 等非生产模块。对于每个发现的模块，它使用 inspect.getmembers 提取所有非私有类（不以下划线开头），并将它们加入到待处理列表中。随后，它通过去重和两轮过滤来筛选真正的估计器：首先保留所有继承自 BaseEstimator 且非 BaseEstimator 本身的类；然后移除所有抽象基类（通过检查 __abstractmethods__ 是否为空）。如果提供了 type_filter 参数（如 "classifier"），它进一步使用对应的 Mixin（如 ClassifierMixin）进行子类检查，以返回特定类型的估计器。最终结果会被去重并按照类名排序，以确保在不同运行之间的可重复性，这对于自动化测试尤为重要。该函数返回的是 (name, class) 元组的列表，便于直接实例化或检查属性。
52.8.2 all_displays 与 all_functions（逐行注释略）—— 与 all_estimators 类似，只是过滤规则不同（Display 类 vs 公共函数）。
解释：all_displays 和 all_functions 函数与 all_estimators 采用相同的底层遍历机制，但应用了不同的过滤条件以满足其特定用途。all_displays 专门查找类名以 Display 结尾的类（如 CalibrationDisplay、RocCurveDisplay），这些类用于可视化估计器的行为（如校准曲线、ROC 曲线），并且通常不以下划线开头以避免包含内部实现。同样地，all_functions 用于收集整个 sklearn 匔中的公共函数（非私有、非测试、非内部检查函数），它通过自定义的 _is_checked_function 辅助函数来判断一个函数是否应被包括在内：必须是顶层函数（不以下划线开头），必须来自 sklearn. 命名空间，且不属于 estimator_checks 模块（以避免包括内部测试钩子）。这三个发现函数共同形成了 sklearn 自省能力的支柱， enabling 自动化文档生成（如 API 参考）、一致性测试（确保所有公开对象都有文档或测试覆盖）以及动态接口构建（如在第三方库中安全地引用 sklearn 组件）。
52.8.3 _AvailableIfDescriptor（逐行注释）
class _AvailableIfDescriptor:
"""基于 descriptor 协议的条件属性，实现属性在 check 为 False 时不可见。"""
def __init__(self, fn, check, attribute_name):
self.fn = fn # 原始函数对象
self.check = check # 判定函数
self.attribute_name = attribute_name
update_wrapper(self, fn) # 复制元信息（docstring、__name__ 等）
def _check(self, obj, owner):
# 用于统一错误信息
attr_err_msg = (
f"This {owner.__name__!r} has no attribute {self.attribute_name!r}"
)
try:
check_result = self.check(obj)
except Exception as e:
raise AttributeError(attr_err_msg) from e
if not check_result:
raise AttributeError(attr_err_msg)
def __get__(self, obj, owner=None):
if obj is not None:
# 实例访问：先检查条件，再返回 MethodType 包装的函数
self._check(obj, owner=owner)
out = MethodType(self.fn, obj)
else:
# 类访问：返回包装函数，保持可用于 monkey‑patch 等场景
@wraps(self.fn)
def out(*args, **kwargs):
self._check(args[0], owner=owner)
return self.fn(*args, **kwargs)
return out
解释：_AvailableIfDescriptor 是实现条件属性或方法可见性的核心机制，它利用了 Python 的描述符协议（descriptor protocol）来在属性访问时动态决定是否暴露给定的方法或属性。当装饰器 @available_if(check) 应用于一个方法时，它实际上将该方法包装成一个描述符实例。在实例属性访问（obj.method）时，__get__ 方法会首先调用 self._check(obj, owner) 来执行用户提供的检查函数（例如 lambda self: hasattr(self, 'supports_partial_fit')）；只有当该检查返回真值时，才将原始函数包装成一个绑定方法（MethodType）并返回；如果检查失败（返回假值或抛出异常），则引发 AttributeError，使得该属性在实例上看来“不存在”。在类级别访问（Cls.method）时，它返回一个包装函数，该函数在被调用时会对第一个参数（预期为实例）执行相同的检查，这使得即使通过类进行猴子补丁（monkey-patching），条件逻辑也能得到保持。这种机制广泛用于根据估计器的能力（如是否支持增量学习）有条件地暴露方法，从而在保持接口清晰的同时避免在不支持的对象上调用导致错误的方法。
52.8.4 Bunch（逐行注释）
class Bunch(dict):
"""属性式字典：键可通过属性访问，支持键废弃警告与 pickle 兼容。"""
def __init__(self, **kwargs):
super().__init__(kwargs)
# 用于记录已废弃键对应的警告信息
self.__dict__["_deprecated_key_to_warnings"] = {}
def __getitem__(self, key):
# 若键已标记为废弃，则触发 FutureWarning
if key in self.__dict__.get("_deprecated_key_to_warnings", {}):
warnings.warn(
self._deprecated_key_to_warnings[key],
FutureWarning,
)
return super().__getitem__(key)
def _set_deprecated(self, value, *, new_key, deprecated_key, warning_message):
"""一次性设置新键、旧键以及对应的警告信息。"""
self.__dict__["_deprecated_key_to_warnings"][deprecated_key] = warning_message
self[new_key] = self[deprecated_key] = value
def __setattr__(self, key, value):
# 让属性赋值等同于字典键赋值
self[key] = value
def __dir__(self):
# 支持 IDE 自动补全
return self.keys()
def __getattr__(self, key):
try:
return self[key]
except KeyError:
raise AttributeError(key)
def __setstate__(self, state):
# 对旧版 pickle（含 __dict__）做 noop，防止属性/键不一致
pass
解释：Bunch 类是 scikit-learn 中广泛使用的一种数据容器，它继承自内置 dict 类型，但通过重载一系列魔术方法（magic methods）提供了类似对象的属性访问体验，同时保留了字典的所有功能。在初始化时，它接受关键字参数并将其存储在内部字典中，同时初始化一个用于跟踪废弃键的私有字典（存储在 __dict__ 中以避免与用户键冲突）。__getitem__ 方法被重载以在访问被标记为废弃的键时触发 FutureWarning，这使得库维护者可以在不立即断裂向后兼容性的前提下，安全地重命名或移除字段。__setattr__ 被重载以使属性赋值（如 bunch.key = value）等同于字典赋值（bunch['key'] = value），从而实现属性和键之间的双向同步。__dir__ 方法返回所有键，以支持 IDE 的自动补全功能。__getattr__ 在找不到对应属性时尝试作为键访问字典；如果仍未找到，则引发 AttributeError，保持了属性访问的语义一致性。最后，__setstate__ 被重载为一个空操作（noop），以确保旧版 pickle（尤其是 scikit-learn 0.16.x 之前生成的，其中包含 __dict__）在反序列化时不会因为属性和键状态不一致而产生混乱——这种设计选择了以键为准的视角，忽略任何可能过时的 __dict__ 内容。由于其灵活性和兼容性，Bunch 常用于返回数据集（如 load_iris 的结果）、超参数字典以及中间计算结果，是 sklearn 生态中数据传递的事实标准。
52.8.5 utils/__init__.py（路径校正）
- 原文中误写
__main__，实际文件为__init__.py，已在本文档中统一使用sklearn/utils/__init__.py进行引用。
52.9 设计取舍（一问一答完整段落）
为什么不用诸如 pydantic 之类的第三方验证库？
核心原因在于零依赖、完全可控。pydantic 虽然提供强大的声明式模型与自动错误信息，但引入它会带来额外的依赖链、版本冲突风险以及不必要的运行时开销。更重要的是，scikit-learn 的输入验证需要深度侵入稀疏矩阵、DataFrame、Array API、成对核矩阵等特殊容器，并在错误信息中嵌入针对缺失值处理的文档链接，这些细节只有在内部自行实现时才能做到精准。自研的 validation 与 _param_validation 系统还能通过 全局开关 skip_parameter_validation 与 装饰器 prefer_skip_nested_validation 在性能敏感的路径上彻底关闭校验，从而满足高效训练场景的需求。
这种设计的 trade-off 是什么？
我们必须自行维护大量约束类、装饰器与错误消息的本地化，这带来了不小的代码维护成本。相对地，我们获得了 完整的定制化能力——能够在每个层面（稀疏格式转换、成对矩阵切片、标签系统）进行细粒度控制，并将校验逻辑无缝嵌入 estimator 的生命周期（fit、predict、partial_fit 等），这在机器学习库的通用性与可解释性方面是不可或缺的。
52.10 动手练习（完整细纲）
下面提供 完整的练习列表，请在本地环境中实现或验证对应功能：
-
阅读并手写
validate_parameter_constraints- 在本地复制函数，实现对每个参数约束的遍历、匹配与错误抛出。
-
探索标签系统与元估计器参数路由
-
为自定义的
MyEstimator实现__sklearn_tags__，查看InputTags、TargetTags的实际值。 -
继承
_BaseComposition，创建包含两个子估计器的MyPipeline，验证get_params与set_params能正确使用双下划线语法。
-
-
实践发现机制
-
使用
all_estimators(type_filter="classifier")列出所有分类器并统计数量。 -
调用
all_displays()与all_functions()，分别打印前 5 项，验证过滤规则。
-
-
条件方法暴露
- 编写一个类
IncrementalModel，在partial_fit方法上使用@available_if(lambda self: hasattr(self, "supports_partial_fit"))，验证在不同实例属性下方法的可见性。
- 编写一个类
-
Bunch 容器实验
-
创建
Bunch(a=1, b=2)，使用属性访问与键访问验证等价性。 -
使用
_set_deprecated为键old_key设置废弃警告，访问时确认FutureWarning被触发。
-
-
全局开关性能测试
- 在一个循环中多次调用
check_array，分别在set_config(skip_parameter_validation=True)与默认模式下测量耗时，比较差异。
- 在一个循环中多次调用
-
扩展
validate_params- 为自定义函数
def foo(x: int, y: str)添加约束字典{"x": [Interval(Integral, 0, 10, closed="both")], "y": [StrOptions({"a","b"})]}，使用@validate_params装饰并测试合法与非法输入的错误信息。
- 为自定义函数
完成以上练习后，你将对 scikit-learn utils 的整体设计、实现细节以及可扩展性有更深入的体会。
52.11 本章小结
以下表格概括了本章涉及的核心概念及其职责，帮助你快速回顾与对照。
| 概念 | 解释 |
|------|------|
| check_array | 统一数组验证入口，处理 dtype 转换、稀疏/稠密/数据框输入、ensure_2d/ensure_min_samples、force_all_finite/allow_nan、copy/order 语义 |
| check_X_y | X/y 联合验证，内部调用 check_array 并额外校验样本数一致、multi_output 目标形状、y 数值类型 |
| validate_params | 参数校验装饰器，结合 Interval/StrOptions/HasMethods 等约束类实现声明式参数验证，支持跳过嵌套验证与全局开关 |
| Interval / StrOptions / HasMethods | 核心约束类：数值区间、字符串枚举、鸭子类型方法检查，构成参数约束体系的基石 |
| InputTags / TargetTags / Tags | 估计器能力标签体系：描述输入/目标数据支持情况、任务类型特有属性、全局配置标志 |
| get_tags | 统一标签获取函数，调用 estimator.__sklearn_tags__()，异常时给出清晰继承建议 |
| _BaseComposition | 元估计器基类，实现双下划线参数语法的获取/设置/替换/校验，_safe_split 支持成对矩阵切分 |
| available_if | 基于描述符协议的条件方法暴露装饰器，运行时根据检查函数返回值决定属性是否可用 |
| all_estimators / all_displays / all_functions | 自动发现工具：遍历包树收集所有非私有估计器、显示类、公共函数，支撑 API 一致性检查 |
| Bunch | 属性式字典容器，支持键弃用警告、pickle 兼容、数据集返回与参数分组的标准载体 |
| utils/__init__.py | 统一门面聚合：验证、数学、稀疏、随机、索引、编码、标签、元估计器、HTML 可视化等核心工具的公共导出，__all__ 明确接口边界 |
在下一章中，我们将继续深入 utils 元数据路由与多类标签，探讨如何在元估计器内部安全传递 sample_weight、groups 等元数据，并进一步揭示 sklearn 如何通过标签体系实现灵活而统一的 API 兼容性。
52.12 设计取舍（一问一答完整段落）
为什么采用当前方案而不是更复杂的替代方案？ 本章实现优先保证与既有 API 的一致性、可维护性与运行效率。这意味着在少数极端场景下，调用者需要自行在灵活性、内存与速度之间做取舍，换取默认路径的清晰与稳定。
第 53 章 —— utils 元数据路由与多类标签
53.1 学习目标
-
难度：★★★☆☆（3/5）
-
预备知识：Python 基础、面向对象编程与 Markdown/代码阅读基础
-
深入理解元数据路由的实现细节：请求、声明、路由三层协同机制
-
掌握 MetadataRequest 与 MetadataRouter 的完整 API 与内部工作原理
-
能够阅读并扩展元数据路由系统中的关键函数：_routing_repr、_raise_for_unsupported_routing、process_routing 等
-
熟悉多分类目标识别工具：_unique_multiclass、_is_integral_float、type_of_target、unique_labels、check_classification_targets
-
掌握类别权重与样本加权的完整实现：compute_class_weight、compute_sample_weight、_check_sample_weight
53.2 生活类比
想象元数据路由系统是一个智能物流分拣中心。其中，MetadataRequest 涉及下游工厂如 SVM 或随机森林发出的原料清单，明确需要 sample_weight 还是 groups 及是否接受替代品；MetadataRouter 作为物流枢纽如 Pipeline 或 GridSearchCV，维护自家 fit 方法到子估计器 fit 方法的路由表并记录子估计器的订单；MethodMapping 是具体的运输路线单，注明调用者方法到被调用者方法的映射；process_routing 则是到货时的分拣作业，核对来货与订单，按运单分发到对应工位，缺货报错、错货拦截、多余货物退回；_unique_multiclass 和 type_of_target 负责入厂原料标签 y 的自动识别，判断是二分类、多分类、多标签还是回归目标以防混料入库；compute_class_weight 和 compute_sample_weight 则根据类别分布自动计算配料比例，稀有类别多配料权重大，常见类别少配料，支持多输出配方的乘法合成。
这就像在物流中心工作的员工（即我们自己），每天都要根据工厂（消费者）发来的清单（MetadataRequest），查看总调度系统（MetadataRouter）的安排，然后按照运单（MethodMapping）把货物（元数据）送到正确的装卸区（子估计器方法），同时检查原料标签（目标 y）是否符合要求，计算合适的配料比例（类权重），确保生产线顺畅运转。
53.3 源码地图
sklearn/utils/_metadata_requests.py
sklearn/utils/metadata_routing.py
sklearn/utils/multiclass.py
sklearn/utils/class_weight.py
53.4 元数据路由核心机制 —— 请求、声明与路由的三层协同
元数据路由系统通过三层协同工作：消费者声明需求（MetadataRequest），路由器定义转发规则（MetadataRouter），处理函数将元数据按需传递（process_routing）。这种设计使得元数据可以安全地从用户输入流向最终的消费者方法，而不需要在每个中间组件中硬编码传递逻辑。
消费者（如 SVM）通过 get_metadata_routing 返回 MetadataRequest，声明哪些方法需要哪些元数据（如 sample_weight=True）。路由器（如 Pipeline）通过 MetadataRouter 维护映射关系，定义自身方法如何调用子对象的方法，并携带哪些元数据。process_routing 是路由器内部核心入口，负责验证元数据是否被允许传递，并根据路由规则将元数据分发给正确的消费者方法。元数据流动遵循：用户输入 -> 路由器验证 -> 按映射拆分 -> 子对象方法接收到对应的元数据值。
UNUSED、WARN、UNCHANGED 等特殊值支持元数据请求的灵活控制：删除、警告或保持不变。元数据路由默认关闭，需通过 sklearn.set_config(enable_metadata_routing=True) 启用，以避免对旧代码造成破坏。
53.4.1 核心类型定义：MetadataRequest
源码路径：sklearn/utils/_metadata_requests.py - MetadataRequest（180-340行）
class MetadataRequest {
fit: MethodMetadataRequest
predict: MethodMetadataRequest
_requests: Dict<String, Any>
}
此结构体是元数据路由中“消费者声明”的核心载体。每个支持元数据的估计器（如 SVC）都拥有 _metadata_request 属性，它是一个 MetadataRequest 实例。该实例内部为每个方法（fit、predict 等）维护一个 MethodMetadataRequest 对象，用于精确记录该方法需要哪些元数据（例如 sample_weight=True 表示需要样本权重，False 表示不需要，None 表示若传入则报错）。通过这种方式，元数据需求被声明且与方法强关联，为后续路由提供依据。
解释：MetadataRequest 就像工厂主管填写的原料需求表，清晰列出每条生产线（方法）需要哪些原料（元数据如 sample_weight、groups），为总调度系统提供精准依据。
53.4.2 核心类型定义：MethodMetadataRequest
源码路径：sklearn/utils/_metadata_requests.py - MethodMetadataRequest（50-100行）
class MethodMetadataRequest {
_requests: Dict<String, Union<Bool, Str, None>>
owner: Object
method: String
}
此结构体细化了单一方法的元数据需求。它通过 _requests 字典映射参数名到请求值：True 表示需要该元数据、False 表示不需要、None 表示禁止传入，字符串则表示使用别名进行路由（例如将外部传入的 sw 映射到内部的 sample_weight）。所有者（owner）记录该请求所属的估计器对象，method 记录所属方法名（如 "fit"）。这种设计使得元数据请求既灵活又可溯源。
解释：MethodMetadataRequest 就像单条生产线的领料单，精确说明该线路需要哪种原料（如 sample_weight）、是否必需，或者是否使用别名（如将外部叫法 “sw” 对应内部标准名称），避免混淆。
53.4.3 逐行解析关键函数：process_routing
源码路径：sklearn/utils/_metadata_requests.py - process_routing（420-480行）
def process_routing(_obj, _method, /, **kwargs):
if not kwargs:
return EmptyRequest()
if not (hasattr(_obj, "get_metadata_routing") or isinstance(_obj, MetadataRouter)):
raise AttributeError("对象需实现 get_metadata_routing 或是 MetadataRouter 实例")
if _method not in METHODS:
raise TypeError(f"方法 {_method} 不在支持的路由方法列表中")
request_routing = get_routing_for_object(_obj)
request_routing.validate_metadata(params=kwargs, method=_method)
routed_params = request_routing.route_params(params=kwargs, caller=_method)
return routed_params
此函数是元数据路由系统的总闸门。它首先检查是否有元数据传入；若无且路由未启用，则返回空结构以避免开销。接着验证对象是否支持路由（必须具备 get_metadata_routing 方法或是 MetadataRouter 实例），并确保方法名在允许范围内。然后通过深拷贝获取路由对象，调用其 validate_metadata 检查是否有未声明但被传入的元数据（防止错发），最后调用 route_params 按照预定路由规则将元数据分发给各消费者方法。
解释：process_routing 就像物流中心的安检与分拣台：先看有没有货（kwargs），再检查车辆是否有资质（对象是否支持路由）、单据是否齐全（方法名合法），然后调度员（路由器）核对订单（validate_metadata），最后按送货单（route_params）把货物发到各工厂车间（子估计器方法）。
53.4.4 完整数据流/流程图
53.5 多分类目标处理 —— 类型识别与标签提取的决策树
在机器学习中，正确识别目标变量的类型是分类算法能否正常工作的前提。sklearn.utils.multiclass 模块提供了一套决策树工具，用于将原始目标数据分类为 binary、multiclass、multilabel-indicator 或 continuous 等类型，并安全地提取唯一标签。
53.5.1 核心类型定义：type_of_target
源码路径：sklearn/utils/multiclass.py - type_of_target（200-280行）
def type_of_target(y, input_name="", raise_unknown=False):
target_type: String
该函数是元数据路由和多分类处理的起点，它检查目标数组 y 的形状、数据类型和唯一值，以推断其语义类型。例如，一维数组包含两个不同值将被标记为 'binary'，而二维仅包含 0/1 的数组将被识别为 'multilabel-indicator'。
解释：type_of_target 就像物流中心的质检仪器，一眼就能判断来货（目标 y）是什么类型：是散装粉料（连续值）、还是袋装离散件（二分类/多分类），或者是带标签的托盘（多标签），确保后续工序不对症下药。
53.5.2 逐行解析关键函数：type_of_target
源码路径：sklearn/utils/multiclass.py - type_of_target（200-280行）
def type_of_target(y, input_name="", raise_unknown=False):
xp, is_array_api_compliant = get_namespace(y)
if not valid_input(y):
raise ValueError("Expected array-like...")
if is_multilabel(y):
return "multilabel-indicator"
with warnings.catch_warnings():
y = check_array(y, dtype=None, **check_y_kwargs)
if y.ndim not in (1, 2) or not min(y.shape):
return _raise_or_return()
if xp.isdtype(y.dtype, "real floating"):
data = y.data if issparse(y) else y
if xp.any(data != xp.astype(xp.astype(data, xp.int64), y.dtype)):
_assert_all_finite(data, input_name=input_name)
return "continuous" + suffix
if cached_unique(y).shape[0] > 2 or (y.ndim == 2 and len(y[0]) > 1):
return "multiclass" + suffix
else:
return "binary"
这段代码实现了目标变量类型的精准判定。它首先排除多标签情况（如标签指示矩阵），然后检查数据是否为连续值（通过比较原始浮点数据与其转换为整数再转回的结果是否相同，以判断是否全为整数浮点）；若非全整数则判为连续。接着检查是否为多分类（唯一值超过两个，或二维且每列有多个值），最后默认为二分类。这种分层检查确保了对各种目标格式的正确识别，避免了如将连续值误喂入分类器等错误。
解释：函数像一道严格的流水线检验：先看是否是多标签托盘（is_multilabel），不是再检查是否有小数点且不全为整数（连续值），再看是否有超过两种离散值（多分类），最后剩下的就是二分类。每一步都有明确依据，防止误判。
53.5.3 完整数据流/流程图
53.6 设计中的取舍
问：为什么元数据路由不用全局变量来传递元数据？
因为全局变量会在并行或交叉验证场景中引入严重的副作用和线程安全问题：一个任务修改了全局状态，可能导致另一个任务读取到脏数据。相反，元数据路由通过显式参数传递和上下文隔离（如每个 Pipeline 实例维护自己的路由器状态），确保了元数据在复杂嵌套结构中的可预测流动，有效避免了远程作用和竞态条件。
问：这种设计的 trade-off 是什么？
trade-off 是增加了代码的间接性和抽象层数：使用者需要理解 MetadataRequest、MethodMapping 等中间概念，才能正确声明和路由元数据。但换来的好处是元估计器能够安全转发元数据而无需知晓子估计器内部实现的细节，从而实现真正的组合式编程（例如 Pipeline 可以任意组合不同年代的估计器，只要它们支持元数据路由）。相比之下，若采用硬编码方式（在父组件中写死子组件所需参数），将导致父子组件紧密耦合，使得估计器难以重用、难以扩展，也阻�了自定义 meta-estimator 的开发。
53.6.1 设计取舍架构图
53.7 动手练习
问：当用户调用 Pipeline.fit(X, y, sample_weight=sw) 时，sample_weight 如何通过 process_routing 流转到子估计器的 fit 方法？
首先，process_routing 被调用以验证并准备路由；它从 Pipeline.get_metadata_routing() 获取路由器对象；接着调用 validate_metadata 确认 sample_weight 已被声明为可路由；最后调用 route_params(caller="fit")，该方法内部遍历所有步骤的映射，发现每个 step 的 fit 方法被声明需要 sample_weight，于是将该值封装进 Bunch 并按对象名和方法名分发，如 {'estimator0': {'fit': {'sample_weight': sw}}, 'estimator1': {'fit': {'sample_weight': sw}}, ...}，最终被子估计器的 fit 方法接收。
问：MetadataRouter.validate_metadata 在何时被调用？它防止了什么类型的错误？
它在 process_routing 中被调用，紧随获取路由对象之后，实际路由之前。它防止了“错发”错误：即用户传入了元数据（如 unknown_param），但该元数据在路由器及其所有子对象中均未被声明为需要或允许的，从而避免了因拼写错误或接口变更导致的静默失败或误用。
问：MethodMetadataRequest._route_params 中如何处理 alias 为字符串（别名）的情况？
当 alias 为字符串且该字符串存在于输入参数 params 中时，函数会将 params[alias] 的值赋给结果字典中对应的原始参数名 prop。例如，若用户声明 add_request(param="sample_weight", alias="sw") 并在调用时传入 sw=array([1,2,3])，则 _route_params 会读取 params["sw"] 并将其存入 res["sample_weight"]，实现由外部别名到内部标准名称的映射。
问：构造 5 个边界案例输入，分别预测 type_of_target 的返回值并解释原因。
-
[[1,2]]：二维且列>1，唯一值为 {1,2} → 返回'multilabel-indicator'（被is_multilabel先捕获） -
[[1.0, 2.0]]：同上 →'multilabel-indicator'（同理） -
[[True, False]]：布尔值，二维多列 →'multilabel-indicator'（is_multilabel接受布尔型） -
[[1, 2], [3]]：不规则（齐长）序列 → 在check_array阶段因非齐数组触发 ValueError，被包装为 object 类型后进入未知分支 → 返回'unknown'（或报错，视raise_unknown而定） -
[]：空一维数组 →min(y.shape)=0→ 返回'binary'（按空视为无类别，默认为二分类）
问：is_multilabel 对稀疏矩阵（dok/lil 格式）如何处理？为何要求 labels.size <= 2 且包含 0？
对于 dok/lil 格式的稀疏矩阵，函数会先转换为 csr 格式以确保高效访问；然后检查其数据数组 y.data 中的唯一值。若为空（全零），则返回 True（视为无标签）；否则要求唯一值只能是 {0} 或 {0,1}，且数据类型必须为整数或布尔——因为多标签指示矩阵只能包含 0（未命中）和 1（命中），任何其他值（如 2）或缺失 0 都表示格式错误。
问：unique_labels 为何禁止字符串与数字标签混合？在 Array API 兼容模式下如何实现去重？
混合类型会导致无法定义统一的顺序（例如“10”是否在“2”之前？），且后续算法依赖标签的可比较性；一旦混合，排序或唯一化将失败或产生未定义行为。在 Array API 模式下，函数使用 xp.concat 合并所有唯一值，再用 xp.unique_values 去重，该操作要求所有输入具有相同数据类型，因此会在类型不统一时直接失败，从而强制类型一致性。
问：当 class_weight='balanced' 且提供 sample_weight 时，类权重公式如何变化？_bincount 扮演什么角色？
公式变为：weight[i] = (sum(sample_weight)) / (n_classes * sum(sample_weight * indicator(y == class_i)))，即用样本权重的总和除以类别数和该类的加权样本数。_bincount 高效地计算每个类别的加权出现次数（即 sum(sample_weight * indicator(y == class_i))），是实现加权平衡的核心工具。
问：compute_sample_weight 在多输出场景下如何组合各列权重？为何使用乘法而非加法？
它先分别计算每个输出列的样本权重向量（例如 [w11, w12, ...] 和 [w21, w22, ...]），然后按元素相乘（[w11*w21, w12*w22, ...]）得到最终权重。使用�法是因为在多输出分类中，一个样本只有在所有输出上都被正确分类时才算“难”，因此难度（逆频率）应相乘；而加法会错误地将易分类的一维补偿难分类的另一维。
问：indices 参数仅支持 'balanced' 模式的设计原因是什么？缺失类别样本权重置零的语义含义？
因为在非 balanced 模式下，类权重是用户自定义的固定值，无法仅基于子样本重新估计；而 balanced 模式依赖于当前样本的类别分布，故支持子样本重新计算。缺失类别权重置零表示：该类别在当前子样本中未出现，对模型训绰无信息提供（尤其在 bootstrap 或子采样中），赋予零权重可防止其参与梯度更新，避免引入噪声或虚假置信度。
问：参考 sklearn/utils/_metadata_requests.py 中 MetadataRouter.add 与 add_self_request 的用法。
add_self_request 用于将路由器自身（如 Pipeline）标记为元数据消费者（例如 Pipeline 自身也需要 sample_weight）；而 add 用于注册子对象（如 Pipeline 中的 StandardScaler 或 SVC）及其方法映射（例如 Pipeline.fit -> SVC.fit）。两者共同构建完整的路由图：自我消费 + 子对象路由。
问：动手任务：实现一个简化版 MyPipeline 类，包含 steps 列表，支持 fit 方法。
class MyPipeline:
def __init__(self, steps):
self.steps = steps # List of (name, estimator) tuples
def fit(self, X, y, **kwargs):
from sklearn.utils.metadata_routing import process_routing
routed = process_routing(self, "fit", **kwargs)
for name, est in self.steps:
method_kwargs = routed.get(name, {}).get("fit", {})
est.fit(X, y, **method_kwargs)
return self
def get_metadata_routing(self):
from sklearn.utils.metadata_routing import MetadataRouter, MethodMapping
router = MetadataRouter(self)
# Self request: Pipeline 自己消费 sample_weight
router.add_self_request(MetadataRequest(self).fit.add_request(
param="sample_weight", alias=True))
# Route to each step's fit method
method_mapping = MethodMapping()
for name, est in self.steps:
method_mapping.add(caller="fit", callee="fit")
router.add(method_mapping=method_mapping, **{name: est for name, est in self.steps})
return router
测试：启用 enable_metadata_routing=True 后，调用 MyPipeline([('svc', SVC())]).fit(X, y, sample_weight=sw)，可验证 sample_weight 是否被正确路由到 SVC 的 fit 方法。
53.7.1 动手练习架构图
53.8 本章小结
在这一章中，我们深入探索了 scikit-learn 的元数据路由系统和多分类目标处理工具，理解了它们如何像一个智能物流中心一样，精准地将用户提供的元数据（如样本权重）和目标标签信息，按照预定规则送达给需要它们的估计器方法。首先，我们拆解了元数据路由的三层架构：消费者通过 MetadataRequest 声明需求，路由器通过 MetadataRouter 定义转发规则，而 process_routing 函数则负责在运行时执行安全的元数据分发；其次，我们考察了多分类目标识别工具如何像一个质检仪器一样，通过 type_of_target、unique_labels 等函数，将原始标签数据可靠地分类为 binary、multiclass 或 multilabel-indicator 类型，防止不兼容的数据流入模型；接着，我们学习了类权重和样本加权函数如何根据类别分布动态计算补偿系数，让稀有类别在训练中获得更大的话语权，从而缓解类别不平衡问题；最后，我们通过代码解析和动手练习，掌握了这些机制的实现细节，为构建支持元数据透传的自定义元估计器奠定了基础。
本章我们一起学习了以下概念：
概念总结
| 概念 | 说明 |
|------|------|
| MetadataRequest | 消费者对象用于声明其方法需要哪些元数据（如 sample_weight=True）的容器。它内部为每个方法维护一个 MethodMetadataRequest 实例，精确记录该方法是否需要、拒绝或使用别名来处理特定元数据，从而为元数据路由提供清晰的需求声明。 |
| MetadataRouter | 路由器对象，维护父子方法之间的映射关系（如 Pipeline.fit -> SVC.fit），并记录哪些对象需要哪些元数据。它通过 add_self_request 声明自身需求，通过 add 注册子对象及其方法映射，是元数据分发的中枢调度系统。 |
| process_routing | 路由器内部核心函数，验证传入元数据是否符合预期（防止错发），并根据路由规则将元数据分发给相应的消费者方法。它是元数据流动的闸门与调度台，确保只有被声明的元数据才会被传递，并且只送到正确的目的地。 |
| type_of_target | 目标变量类型推断函数，通过逐步判定（多标签 → 连续 → 多分类 → 二分类）识别数据是 binary、multiclass、multilabel-indicator 还是 continuous 类型。它是数据质量的第一道关卡，防止不兼容的目标（如连续值）进入分类器。 |
| compute_class_weight | 基于类别频率计算补偿权重的函数，支持 'balanced' 启发式（样本数/(类别数×类别计数)）或用户自定义字典。它让稀有类别在损失函数中获得更大权重，从而在训练中获得更多关注，是处理类别不平衡的基础工具。 |
| compute_sample_weight | 将类别权重扩展到样本级的函数，在多输出场景中使用乘法组合各列权重（因为样本只有在所有输出上都“罕见”时才应被高权重）。它将类别层面的补偿精细化到每个样本，是实际训练中加权学习的关键步骤。 |
第 54 章 —— utils 底层加速与兼容层 —— 深入"性能与跨平台的前沿阵地"
54.1 学习目标
-
难度：★★★☆☆（3/5）
-
预备知识：Python 基础、面向对象编程与 Markdown/代码阅读基础
-
掌握元数据路由核心机制：MetadataRequest、MetadataRouter 的请求‑声明‑路由三层协同工作原理
-
理解多分类与多标签目标处理工具：type_of_target、unique_labels、_ovr_decision_function 的类型识别决策树
-
掌握类权重与样本加权计算：compute_class_weight、compute_sample_weight 处理类别不平衡的砝码校正逻辑
-
深入理解数组 API 兼容层的跨后端计算统一接口、设备一致性守卫与 DLPack 零拷贝迁移机制
-
掌握 Cython 与 BLAS 高性能内核的融合类型代码复用、行/列主序零拷贝转置、GIL 释放与内存视图友好接口
-
理解 OpenMP 并行环境下有效线程数的动态计算策略、cgroups 配额感知与线程池控制器的嵌套并行限制
-
掌握 MurmurHash3 哈希函数的 C++ 核心实现、Cython 多态入口设计及批量数组哈希的 nogil 向量化吞吐
-
理解同时排序与固定大小最大堆在近邻搜索中的原地操作中的原地交换原理、双数组原子交换与 SoA 布局优势
-
掌握基于 C++ STL 的 IntFloatDict 与 StdVectorSentinel 实现零拷贝 Python 交互的生命周期管理机制
-
理解通用类型定义体系如何屏蔽平台差异、支撑融合类型跨模块复用及测试桩验证类型映射一致性
54.2 生活类比
想象 scikit-learn 的 utils 底层加速层是一座高性能计算的"精密机床车间"。在这个车间里，Cython 融合类型就像一套可快速换型的通用刀架，能够同时加工单精度和双精度两种材质（类型），避免为每种材质单独打造刀具；BLAS 布局自适应则像智能夹具，自动识别工件摆放方向（行主序或列主序），在必要时交换维度或转置参数，使 BLAS 的列主序实现零拷贝完成加工；数组 API 兼容层相当于万能转接器，NumPy、CuPy、PyTorch、JAX、Dask 等不同品牌的"电池"（数组后端）通过统一接口供上层"电器"（算法）使用，真正做到"一次编写，多平台运行"；OpenMP 线程池控制犹如车间排班主管，根据订单量（n_threads）与工人上限（OMP_NUM_THREADS、cgroups 配额）动态排班，防止人挤人（资源争用）或闲置；MurmurHash3 则是高速分拣机，任意形状的"包裹"（键）瞬间映射到固定货位（哈希值），雪崩效应保证货位均匀分布，极大提升特征哈希与随机投影的效率；同时排序 / 堆相当于双轨传送带分拣，主传送带保持值的有序排列，副传送带同步搬运索引，两者始终对应，支持 KNN、最近邻搜索等需要保持"值‑索引"一致性的场景；IntFloatDict / StdVectorSentinel 则是零拷贝传送带，C++ 容器（std::map、std::vector）与 NumPy 数组共享同一块内存，无需搬运数据即可在 Python 与 C++ 之间来回；类型定义体系相当于统一图纸标准，intp_t、float64_t 等别名屏蔽平台差异，所有模块基于同一套图纸设计，保证不同车间生产的零件能够可靠组装；元数据路由则是智能物流调度系统，sample_weight、groups 等"随货单据"通过"请求‑声明‑路由"三层协议精准分发到下游"加工工位"（子估计器），避免单据丢失或错投。
54.3 源码地图
sklearn/utils/_metadata_requests.py
├── MetadataRequest 类
│ ├── request_sample_weight()
│ ├── request_groups()
│ ├── __add__()
│ └── __eq__()
sklearn/utils/metadata_routing.py
├── MetadataRouter 类
│ ├── add_self_request()
│ ├── add()
│ ├── route_params()
│ └── get_routing_for_object()
sklearn/utils/multiclass.py
├── type_of_target()
├── unique_labels()
├── _ovr_decision_function()
├── _check_partial_fit_first_call()
├── is_multilabel()
├── _unique_multiclass()
├── _unique_indicator()
├── _is_integral_float()
├── check_classification_targets()
├── class_distribution()
└── _FN_UNIQUE_LABELS
sklearn/utils/class_weight.py
├── compute_class_weight()
└── compute_sample_weight()
sklearn/utils/_cython_blas.pyx
├── BLAS Level 1
│ ├── _dot() / _dot_memview()
│ ├── _asum() / _asum_memview()
│ ├── _axpy() / _axpy_memview()
│ ├── _nrm2() / _nrm2_memview()
│ ├── _copy() / _copy_memview()
│ ├── _scal() / _scal_memview()
│ ├── _rotg() / _rotg_memview()
│ └── _rot() / _rot_memview()
├── BLAS Level 2
│ ├── _gemv() / _gemv_memview()
│ └── _ger() / _ger_memview()
├── BLAS Level 3
│ └── _gemm() / _gemm_memview()
sklearn/utils/_cython_blas.pxd
├── BLAS_Order/Trans 枚举声明
├── Level 1/2/3 函数签名 cimport 接口
sklearn/utils/_array_api.py
├── get_namespace()
├── get_namespace_and_device()
├── device()
├── _single_array_device()
├── move_to()
├── _convert_to_numpy()
├── _average()
├── _median()
├── _logsumexp()
├── _fill_diagonal()
├── _add_to_diagonal()
├── _isin()
├── _in1d()
├── _bincount()
├── _nanmin()
├── _nanmax()
├── _nanmean()
├── _nansum()
├── _xlogy()
├── _cholesky()
├── _linalg_solve()
├── _half_multinomial_loss()
├── _expit()
├── _validate_diagonal_args()
├── _asarray_with_order()
├── _ravel()
├── _modify_in_place_if_numpy()
├── _find_matching_floating_dtype()
├── _is_numpy_namespace()
├── _is_xp_namespace()
├── _max_precision_float_dtype()
├── _remove_non_arrays()
├── _unwrap_memoryviewslices()
├── _union1d()
├── _count_nonzero()
├── size()
├── indexing_dtype()
├── _matching_numpy_dtype()
├── _atol_for_type()
├── supported_float_dtypes()
├── yield_namespaces()
├── _get_namespace_device_dtype_ids()
├── _check_array_api_dispatch()
├── _estimator_with_converted_arrays()
├── yield_namespace_device_dtype_combinations()
└── _matching_numpy_dtype()
sklearn/utils/_openmp_helpers.pyx
├── _openmp_parallelism_enabled()
└── _openmp_effective_n_threads()
sklearn/utils/_openmp_helpers.pxd
├── SKLEARN_OPENMP_PARALLELISM_ENABLED 编译期宏
├── omp_lock_t 结构体声明
├── omp_init_lock / omp_destroy_lock / omp_set_lock / omp_unset_lock nogil 声明
└── omp_get_max_threads / omp_get_thread_num nogil 声明
sklearn/utils/parallel.py
├── _get_threadpool_controller()
├── _threadpool_controller_decorator()
├── Parallel.__call__()
├── delayed()
├── _FuncWrapper.__init__()
├── _FuncWrapper.with_config_and_warning_filters()
├── _FuncWrapper.__call__()
└── _with_config_and_warning_filters()
sklearn/utils/murmurhash.pyx
├── murmurhash3_32()
├── _murmurhash3_bytes_array_u32()
├── _murmurhash3_bytes_array_s32()
├── murmurhash3_int_u32()
├── murmurhash3_int_s32()
├── murmurhash3_bytes_u32()
└── murmurhash3_bytes_s32()
sklearn/utils/murmurhash.pxd
├── murmurhash3_int_u32/s32
└── murmurhash3_bytes_u32/s32
sklearn/utils/src/MurmurHash3.cpp
├── MurmurHash3_x86_32()
├── MurmurHash3_x86_128()
├── MurmurHash3_x64_128()
├── fmix() (uint32_t / uint64_t 重载)
├── getblock() (uint32_t / uint64_t 重载)
├── rotl32()
└── rotl64()
sklearn/utils/src/MurmurHash3.h
├── MurmurHash3_x86_32 声明
├── MurmurHash3_x86_128 声明
└── MurmurHash3_x64_128 声明
sklearn/utils/_sorting.pyx
├── simultaneous_sort()
└── dual_swap()
sklearn/utils/_sorting.pxd
└── simultaneous_sort 声明
sklearn/utils/_heap.pyx
└── heap_push()
sklearn/utils/_heap.pxd
└── heap_push 声明
sklearn/utils/_fast_dict.pyx
├── IntFloatDict.__init__()
├── IntFloatDict.__getitem__()
├── IntFloatDict.__setitem__()
├── IntFloatDict.__iter__()
├── IntFloatDict.to_arrays()
├── IntFloatDict._to_arrays()
├── IntFloatDict.update()
├── IntFloatDict.copy()
├── IntFloatDict.append()
├── IntFloatDict.__len__()
└── argmin()
sklearn/utils/_fast_dict.pxd
├── IntFloatDict 类声明
└── _to_arrays 声明
sklearn/utils/_vector_sentinel.pyx
├── vector_to_nd_array()
├── _create_sentinel()
├── StdVectorSentinel 基类
│ ├── get_data()
│ └── get_typenum()
├── StdVectorSentinelFloat64.create_for() / get_data() / get_typenum()
├── StdVectorSentinelIntP.create_for() / get_data() / get_typenum()
├── StdVectorSentinelInt32.create_for() / get_data() / get_typenum()
└── StdVectorSentinelInt64.create_for() / get_data() / get_typenum()
sklearn/utils/_vector_sentinel.pxd
└── vector_to_nd_array 声明
sklearn/utils/_typedefs.pxd
├── uint8_t / uint32_t / uint64_t ctypedef 声明
├── intp_t (Py_ssize_t) ctypedef 声明
├── float32_t / float64_t ctypedef 声明
├── int8_t / int32_t / int64_t ctypedef 声明
sklearn/utils/_typedefs.pyx
└── testing_make_array_from_typed_val()
浙公网安备 33010602011771号