scikit-learn 1.9 版本指南：Callback 新 API、sparse_interface 配置与跨模块增强全解析

scikit-learn 1.9 版本指南Callback 新 API、sparse_interface 配置与跨模块增强全解析【免费下载链接】scikit-learnscikit-learn: machine learning in Python项目地址: https://gitcode.com/gh_mirrors/sc/scikit-learn导读本文基于 scikit-learn 仓库中 v1.9 版本发布说明系统梳理 1.9.02026 年 6 月与补丁版本 1.9.12026 年 9 月带来的全部变更包括全新的 Callback API、sparse_interface全局配置、metric_at_thresholds等新函数以及 Array API 支持、Metadata routing、树模型缺失值处理等横跨多个模块的增强与修复。读完本文你将掌握 1.9 版本中最值得迁移使用的特性、各模块行为变化的具体影响以及如何在升级后调整代码以适配新行为如 SVCprobability弃用、GradientBoostingcriterion弃用等。一、版本概览版本发布时间定位1.9.02026 年 6 月主特性版本引入 Callback API、sparse_interface等重大特性1.9.12026 年 9 月补丁版本修复 Array API、Metadata routing、并行回调等缺陷官方为 1.9 提供了专门的发布亮点示例见 examples/release_highlights/plot_release_highlights_1_9_0.py。发布说明中的变更条目按类型标记来自 changelog 图例|MajorFeature|重大新特性|Feature|新功能|Enhancement|增强|Efficiency|性能提升|Fix|缺陷修复|API|API 变更多为弃用二、三大重大新特性MajorFeature2.1 新增全局配置sparse_interface这是 1.9 最受关注的配置变更之一新增配置键sparse_interface用于控制 scikit-learn 返回稀疏对象时使用 SciPy sparse matrix 还是 sparse array。from sklearn import set_config # 返回 SciPy sparse matrix1.9 默认行为 set_config(sparse_interfacespmatrix) # 返回 SciPy sparse array未来版本默认目标 set_config(sparse_interfacesparray)在 sklearn/_config.py 中对该配置的说明如下sparray以 SciPy sparse array 形式返回稀疏对象spmatrix以 SciPy sparse matrix 形式返回稀疏对象该配置的默认值为spmatrixscikit-learn 计划在数个版本后将默认值切换为sparray。迁移细节可参考 SciPy 官方的 Sparse Migration Guide。由于默认值在未来会变化如果你的代码依赖spmatrix类型建议显式设置sparse_interfacespmatrix以锁定行为。2.2 全新的 Callback API1.9 引入了面向拟合过程的新 Callback API用于在支持回调的估计器拟合期间调用用户回调。它内置两个开箱即用的回调sklearn.callback.ProgressBar显示进度条sklearn.callback.ScoringMonitor在每个迭代结束时计算并记录评分指标在 sklearn/callback/init.py 中公共 API 导出为ProgressBar、ScoringMonitor、ScoringMonitorLog、FitCallback、AutoPropagatedCallback、CallbackContext、CallbackSupportMixin和with_callbacks。该模块由 sklearn/callback/ 下的_base.py、_callback_context.py、_callback_support.py、_progressbar.py、_scoring_monitor.py和_transport.py等实现文件构成。支持回调的估计器包括linear_model.LogisticRegression仅solverlbfgs时model_selection.GridSearchCVmodel_selection.HalvingGridSearchCVmodel_selection.HalvingRandomSearchCVmodel_selection.RandomizedSearchCVpipeline.Pipelinepreprocessing.StandardScalerScoringMonitor 使用示例基于 sklearn/callback/_scoring_monitor.py 的源码语义from sklearn.callback import ScoringMonitor from sklearn.linear_model import LogisticRegression from sklearn.datasets import make_classification from sklearn.model_selection import train_test_split X, y make_classification(n_samples1000, n_features20, random_state0) X_train, X_test, y_train, y_test train_test_split(X, y, random_state0) monitor ScoringMonitor(scoring[accuracy, neg_log_loss]) clf LogisticRegression(solverlbfgs, max_iter100, callbacks[monitor]) clf.fit(X_train, y_train) # 获取最近一次拟合的评分日志支持 selectall 取全部 run log monitor.get_logs(selectmost_recent) print(log.data) # 每条记录含 task_id_path、estimator_name、task_name 及各评分列 print(log.data_as_pandas) # 也可作为 Pandas DataFrame 查看从源码看ScoringMonitor的scoring参数接受字符串、可调用对象、列表/元组或字典多指标评分内部通过check_scoring统一处理见 sklearn/callback/_scoring_monitor.py。get_logs支持select{all, most_recent}与include_lineage参数sklearn/callback/_scoring_monitor.py。ScoringMonitorLog以datadict 列表和data_as_pandasPandas DataFrame两种形式暴露记录列结构包括task_id_path、parent_task_id_path、estimator_name、task_name、task_id、sequential_subtasks以及每个评分名对应的一列。需要说明的是该 API 目前仍处于实验阶段未来可能不经常规弃用周期直接变更。实现自定义回调或为自定义估计器接入回调的开发者指南见 doc/developers/callbacks.rst。2.3 新函数metrics.metric_at_thresholds新增函数 metric_at_thresholds用于在所有可能的阈值下计算某个二分类指标的值帮助用户在调优决策阈值时可视化指标随阈值的变化。import numpy as np from sklearn.metrics import accuracy_score, metric_at_thresholds y_true np.array([0, 0, 1, 1]) y_score np.array([0.1, 0.4, 0.35, 0.8]) metric_values, thresholds metric_at_thresholds(y_true, y_score, accuracy_score) print(thresholds) # [0.8, 0.4, 0.35, 0.1] print(metric_values) # [0.75, 0.5, 0.75, 0.5]参数说明见 sklearn/metrics/_ranking.py参数说明y_true真实标签形状(n_samples,)y_score连续预测分数可为正类估计概率或decision_function输出metric_func指标函数内部以metric_func(y_true, y_pred, **metric_params)调用其中y_pred (y_score threshold)sample_weight样本权重非 None 时传给metric_funcmetric_params传给metric_func的额外参数字典返回值为metric_values形状(n_thresholds,)或(n_thresholds, *n_outputs)若metric_func返回集合则为二维和thresholds形状(n_thresholds,)。配套函数confusion_matrix_at_thresholds用于计算每个阈值下的混淆矩阵。相关测试见 sklearn/metrics/tests/test_ranking.py覆盖样本权重、metric_params、pos_label、y_score顺序及重复分数等边界情况。三、数据框架支持引入 narwhals 依赖1.9 新增了一个轻量级库依赖narwhals用于简化 DataFrame 输入X与set_outputAPI 规定的 DataFrame 输出支持如 pandas、polars。采纳它的另一个原因是 polars 弃用了 dataframe interchange 协议__dataframe__而此前 scikit-learn 对非 pandas DataFrame 一直依赖该协议。此次变更使 polars DataFrame 的代码路径不再依赖__dataframe__见下文 utils 部分同时也为支持更多 DataFrame 库铺平了道路。四、Array API 支持更新1.9 继续扩大 Array API 兼容输入的支持范围。新增支持的函数/估计器metrics.d2_absolute_error_score、metrics.d2_pinball_score同时改为始终使用averaged_inverted_cdf分位数方法见 metrics 部分linear_model.LogisticRegressionsolverlbfgsmetrics.average_precision_scoremetrics.pairwise.paired_manhattan_distancesmetrics.pairwise_distances_argminpipeline.FeatureUnion当所有 transformer 均支持 Array API 时linear_model.PoissonRegressorsolverlbfgskernel_approximation.Nystroemlinear_model.RidgeCVgcv_mode为auto或eigen时关键修复与增强Cython 实现的估计器在sklearn.set_config(array_api_dispatchTrue)下拟合 NumPy 输入时不再报错LinearRegression、Ridge、RidgeClassifier、LogisticRegression、LinearDiscriminantAnalysis在拟合与预测时若传入不同 namespace 或不同 device 的数组会给出更明确的错误信息新增工具函数sklearn.utils._array_api.move_estimator_to用于将已拟合估计器的数组属性迁移到其他 namespace 与 device内部 NumPy CPU 转换统一优先走通用的 DLPack 转移仅在必要时回退到库特定方法MinMaxScaler、MaxAbsScaler、KernelCenterer、normalize、randomized_range_finder等在不支持float64的设备上正确处理整数输入RidgeClassifier/RidgeClassifierCV的classes_现在存储在与y相同的 namespace 和设备上NumPy 拟合的估计器在array_api_dispatchTrue下用 array-like 或稀疏输入预测或拟合属性为稀疏时如LogisticRegression.sparsify之后不再报错负步幅negative-strideNumPy 数组在通过 DLPack 转移到 PyTorch 前会被先转为连续数组避免torch.from_dlpack中触发 Python 进程中止。五、Metadata routing 更新Metadata routing 的详细机制参见 Metadata Routing 用户指南。1.9 的变更包括preprocessing.TargetEncoder的fit_transform现在将groups路由给内部用于交叉拟合的 CV splitterScorer 现在能正确请求元数据其set_score_request方法能正确检测score_func签名中可用的元数据LogisticRegressionCV.score(...)也会正确将元数据路由到底层 scorer若类显式定义了set_{method}_request方法元数据路由机制不会再覆盖它元数据路由对象MetadataRequest、MetadataRouter及逐方法请求不再深拷贝其所属估计器修复了get_routing_for_object与MetadataRouter.add_self_request引发的整树深拷贝失败与低效问题model_selection.learning_curve在exploit_incremental_learningTrue时现在会把sample_weight正确路由到子估计器的partial_fit方法。1.9.1 补丁中的相关修复SelectFromModel、RFE、RFECV、SequentialFeatureSelector、IterativeImputer作为Pipeline中间步骤、且其组合式fit_transform成为路由目标时元数据如sample_weight不再被静默丢弃BaggingClassifier现在通过predict与predict_proba将元数据动态路由到子估计器的对应方法Pipeline.fit_transform与fit_predict现在与fit一致地对路由到中间步骤的元数据应用transform_inputTransformedTargetRegressor在启用元数据路由后能把sample_weight等元数据正确路由到默认回归器LinearRegression。六、各模块变更详解6.1 sklearn.clusterAgglomerativeClustering与FeatureAgglomeration现在接受metricl2搭配linkagewardl2等价于euclideanMiniBatchKMeans修复了样本权重的处理当sample_weight非 None 时小批量索引通过以归一化样本权重为概率的有放回子采样生成BisectingKMeans修复了n_clusters 2时使用自定义 callableinit的缺陷。1.9.1DBSCAN/dbscan与OPTICS在输入预计算稀疏距离矩阵时不再误报EfficiencyWarning。6.2 sklearn.compose修复ColumnTransformerHTML 展示中的虚线框仅包含其元素并修正了使用remainder时的行为修复ColumnTransformer.fit_transform在元数据路由与remainderpassthrough同时使用时抛出KeyError的回归。6.3 sklearn.datasets重新启用fetch_kddcup99的压缩缓存在不改变公共 API 的前提下减小磁盘缓存体积fetch_openml改为向https://www.openml.org/api/v1/发起 API 请求原api.openml.org域名已无法正确解析或重定向。1.9.1fetch_openml能自动重试损坏的下载fetch_file在local_filename为路径而非纯文件名时抛出ValueError。6.4 sklearn.decompositionFastICAalgorithmdeflation、funlogcosh提速约一个数量级修复TruncatedSVD的power_iteration_normalizer允许值列表中的笔误OR→QR。6.5 sklearn.ensembleHistGradientBoostingClassifier/Regressor修复了 bin edges 的计算逻辑以正确处理sample_weight当sample_weightNone且特征去重值数量小于max_bins时edges 取相邻特征值的中间点否则使用基于平均逆 CDF 的加权分位数若n_samples大于subsample则用权重有放回子采样数据并基于未加权分位数设置 edgesRandomForestClassifier/Regressor、ExtraTreesClassifier/Regressor现在用sample_weight直接抽样而非转发给底层估计器max_samples为浮点数时解释为sample_weight.sum()的比例而非X.shape[0]因抽样有放回浮点max_samples 1.0及整数max_samples X.shape[0]现在都允许默认max_samplesNone仍抽取X.shape[0]个样本GradientBoostingRegressor/Classifier默认friedman_mse此前存在杂质值缩放错误现内部改用与friedman_mse在浮点误差内等价的squared_error弃用GradientBoostingRegressor与GradientBoostingClassifier的criterion参数弃用两个选项结果等价。6.6 sklearn.feature_extraction修复image.reconstruct_from_patches_2d在 patch 维度等于图像对应维度时的结果。6.7 sklearn.feature_selectionSelectFromModel与RFE支持特征重要性为稀疏矩阵/数组的估计器可通过importance_getter传入自定义 callableRFE改用稳定排序保证特征重要性并列时特征选择结果跨运行确定一致。6.8 sklearn.gaussian_process高斯过程核的构造器签名被缓存中小数据集性能提升默认核ConstantKernel() * RBF()的超参数现在在optimizer非 None 时会被优化即GaussianProcessRegressor().fit(X, y)会使用优化后的核超参数。6.9 sklearn.inspectionDecisionBoundaryDisplaymulticlass_colors默认改用更易访问的 Petroff 颜色序列面向不超过 10 类的多分类问题multiclass_colors在response_methodpredict的多分类绘制中同样生效n_classes推断更稳健自定义估计器失败时给出详尽错误plot_methodcontour下对所有 response_method 显示全部类边界contourfpredict时所有类以不同颜色显示多分类contour下predict_proba与decision_function也显示类专属轮廓线多分类边界轮廓线默认以黑色显示传入颜色数少于类别数的 colormap 时抛出ValueErrormulticlass_colors_始终以 NumPy 数组存储。6.10 sklearn.linear_model新特性/增强MultiTaskElasticNet、MultiTaskElasticNetCV、MultiTaskLasso、MultiTaskLassoCV支持稀疏X拟合及sample_weightLogisticRegressionsolverlbfgs以float32数据拟合时损失梯度在float32精度下估计提升训练速度与内存效率此前会隐式转为float64如需复现旧行为可显式转换数据LinearRegression、Ridge、Lasso、LassoCV、ElasticNet、ElasticNetCV、BayesianRidge在copy_XFalse且提供sample_weight时不再对稠密X, y做多余复制LogisticRegressionCV在设置scoring且 CV 折内缺失某些类别标签时能正确处理ElasticNet/ElasticNetCV/enet_path支持l1_ratio0的纯 Ridge 拟合改用替代的对偶间隙公式减少警告噪声L1 惩罚强、特征多时gap safe screening 中系数为 0 的特征不再更新残差ElasticNet家族与lasso_path/enet_path提速。关键修复LassoCV/ElasticNetCV计算全零系数时的最大alpha时考虑positive参数SGDOneClassSVM的alpha修正为alpha nu原为nu / 2coef_、offset_及预测值可能变化enet_path在check_inputFalse时正确处理precomputeRidgeCV/RidgeClassifierCV在cvNone时小alpha区间的留一误差与模型参数数值稳定auto现等价于eigen且选择更廉价路径n_features n_samples时分解协方差矩阵否则分解 Gram 矩阵cv_results_在X为整数数组时不再被错误强转为整数 dtypeSGDClassifier多分类下decision_function极大负值不再产生 NaN此时各类等概率RidgeClassifier无符号整数输入下修复无符号整数溢出LinearRegression的tol参数现作为scipy.linalg.lstsq的cond参数传入LogisticRegressionCV在refitFalseuse_legacy_attributesFalse 非 elasticnet 惩罚时不再抛TypeErrorBayesianRidge/ARDRegression在predict时对测试特征做中心化以正确计算预测方差。API 变更/弃用LogisticRegressionCV.score以位置参数传sample_weight弃用1.11 移除请改用关键字参数LogisticRegressionCV的scoring默认值将在 1.11 从Noneaccuracy改为neg_log_loss显式传值可消除警告lasso_path/enet_path的n_alphas弃用alphas现在同时接受整数自动生成的 alpha 个数与数组正则化路径取值。6.11 sklearn.manifoldSpectralEmbedding与SpectralClustering的 ARPACK 特征求解器调用方式改进运行更快修复MDS.fit_transform在initclassical_mds时返回正确数量的分量。6.12 sklearn.metricsPrecisionRecallDisplay新增类方法from_cv_results可从 cross_validate 的结果直接绘制多条 precision-recall 曲线。其签名要求cv_results是使用return_estimatorTrue与return_indicesTrue的cross_validate返回字典含estimator与indices键并支持sample_weight、drop_intermediate、response_method、pos_label、name、ax、plot_chance_level等参数见 sklearn/metrics/_plot/precision_recall_curve.pycohen_kappa_score新增replace_undefined_by参数定义指标未定义除零时的返回值accuracy_score、hamming_loss、zero_one_loss、matthews_corrcoef、confusion_matrixlabels非 None 时在y_true为字符串、y_pred为数值时对所有 array-like 输入均报错上述指标对尺寸不一致的标签指示矩阵输入也会报错confusion_matrix不接受标签指示矩阵输入pairwise_distances_argmin/pairwise_distances_argmin_min与邻居搜索内部的simultaneous_sort修复了大量距离相同时的二次时间复杂度路径此前可能导致严重变慢甚至栈溢出PrecisionRecallDisplay.from_estimator/from_predictions在y_true为 PyTorch tensor 时正确绘制 chance level 线log_loss与d2_log_loss_score的y_pred参数弃用改用y_proba因为期望的是预测概率而非标签pairwise_distances在 euclidean 度量下配合Y_norm_squared与n_jobs 1不再报错在 Array API 输入下不再产生跨库 dtype 比较的误报警告confusion_matrix_at_thresholds的pos_label与sample_weight以位置参数传入弃用1.11 移除。1.9.1启用 Array API dispatch 且预测来自不同 namespace/device 时分类指标接受 pandas 标签。6.13 sklearn.model_selectionGroupKFold分组时使用稳定排序保证跨运行一致StratifiedGroupKFold在n_splits大于唯一组数时抛出ValueError防止产生退化折修复GridSearchCV/cross_validate等工具对多分类分类器使用scoringaverage_precision时误报ValueErrorpos_label仅对二分类相关不应在多分类问题上校验。6.14 sklearn.neighborsKNeighborsClassifier、RadiusNeighborsClassifier在algorithmbrute下支持字符串标签BallTree/KDTree查询修复距离大量相同时的二次时间路径与栈溢出风险。1.9.1NearestNeighbors.radius_neighbors在n_jobs 1配合ball_tree/kd_tree时正确处理 array-like 的radius。6.15 sklearn.neural_networkMLPClassifier在early_stoppingTrue且y为字符串等非数值标签时不再抛TypeError验证评分只对浮点预测做有限性检查。6.16 sklearn.pipeline修复FeatureUnion搭配set_output(transformpolars)且 transformer 产生重复列名时的缺陷空Pipeline访问属性时抛AttributeError因此可以对空 pipeline 调用dir。6.17 sklearn.preprocessingPowerTransformermethodyeo-johnson的transform改用数值更稳定的scipy.stats.yeojohnson边缘数值场景下结果可能有浮点精度内的偏差PowerTransformer/QuantileTransformer在带特征名数据上fit后调用inverse_transform不再警告特征名问题弃用TargetEncoder的shuffle与random_state参数弃用1.11 移除请改用cv参数传入交叉验证生成器以控制打乱行为。1.9.1修复QuantileTransformer在稀疏数据 ignore_implicit_zerosTrue 子采样组合下某些特征计算退化分位数的问题。6.18 sklearn.svm全零样本权重拟合NuSVR时给出更明确错误弃用SVC/NuSVC的probability参数弃用非线程安全1.11 移除改用CalibratedClassifierCV配合相应估计器与ensembleFalseprobA_/probB_属性随之一并弃用。1.9.1修复LinearSVR.fit的内存泄漏修复LinearSVC在multi_classcrammer_singer下的越界写入。6.19 sklearn.treeDecisionTreeRegressor/RandomForestRegressor的criterionabsolute_error以及所有 criterion 选项支持稠密训练数据X中的缺失值8 个树/集成估计器DecisionTree*、ExtraTree*、RandomForest*、ExtraTrees*支持monotonic_cst与稠密数据缺失值组合使用修复 Poisson criterion 在缺失值存在时的节点杂质计算此前会返回含负值的无效杂质修复逐特征 NaN 检测某些边界模式下特征可能被误判为无 NaN导致 NaN 分到左节点的分裂不被考虑修复树导出中的颜色转换零通道 RGB 值正确转为两位十六进制分量如(0, 255, 0)→#00ff00弃用criterionfriedman_mse弃用原本为梯度提升设计但在树中实现有误、实际与squared_error行为相同改用criterionsquared_error。6.20 sklearn.discriminant_analysis1.9.1LinearDiscriminantAnalysis/QuadraticDiscriminantAnalysis在solversvd与solvereigen下结果一致svd的归一化改为1/n_samples原来分别为1/(n_samples - n_classes)与1/(n_samples - 1)与最大似然协方差估计器及eigen默认一致。6.21 sklearn.utilsget_tags传入类而非估计器实例时给出更清晰错误HTML 表示中的参数表 tooltip 最后一格不再被部分遮挡修复_weighted_percentileaverageTrue对数组末尾零权重样本的处理可能影响KBinsDiscretizerstrategyquantileaveraged_inverted_cdf及median_absolute_error、d2_pinball_score、d2_absolute_error_scorecheck_array在请求dtypenumeric时正确拒绝 pandasStringDtype列pandas 3 中字符串列不再使用objectdtypepolars DataFrame 在validate_data中的代码路径不再依赖__dataframe__交换协议适配 polars 1.40 起对该协议的弃用unique_labels新增ys_types参数避免重复调用type_of_target。1.9.1估计器 HTML 表示将输出特征列表截断至 100 条以提升渲染性能混合输入 namespace 的 Array API 函数/估计器在通过 DLPack 转移负步幅 NumPy 数组前先转为连续数组避免torch.from_dlpack中止进程HTML 表示中的复制按钮改为带aria-label与可见焦点轮廓的button元素支持键盘与屏幕阅读器访问set_output(transformpolars)使用howhorizontal_extend拼接 polars DataFrame不再在polars1.42.1下触发DeprecationWarning。七、行为变化与迁移提示升级到 1.9 后以下行为变化最值得关注全零sample_weight报错所有支持sample_weight的估计器及校验样本权重的指标在sample_weight全为零时抛出ValueError防止无意义拟合GBM 杂质计算修正GradientBoosting*的friedman_mse不再有缩放错误且criterion参数已弃用直接改用默认值即可随机森林抽样语义变化max_samples为浮点数时以sample_weight.sum()为基数且允许max_samples 1.0涉及有放回抽样语义依赖旧行为的结果可能变化SGDOneClassSVM的 alpha 修正alpha nu会改变coef_、offset_与预测SVC/NuSVCprobability弃用若依赖 Platt 缩放概率请迁移到CalibratedClassifierCV(estimator, ensembleFalse)RidgeCV 默认auto语义更新现等价于eigen并自动选择更廉价路径小alpha数值稳定性提升LogisticRegressionfloat32 加速solverlbfgs下 float32 输入不再隐式转 float64追求数值一致性可显式转float64。八、1.9.1 补丁版其余修复除上述各节已并入的内容外1.9.1 还包括修复ScoringMonitor与多进程并行后端组合使用时 Could not pickle the task to send it to the workers 的报错见 sklearn/callback/tests/test_pickle.py 相关测试make_scorer创建的 Scorer 不再在每次调用时深拷贝元数据 kwargs降低模型选择与交叉验证时的内存占用。九、总结scikit-learn 1.9 是一次以「新基础设施 大规模质量修复」为特征的版本sparse_interface为 SciPy sparse array 迁移铺路Callback API 提供了实验性的拟合过程观测能力metric_at_thresholds与PrecisionRecallDisplay.from_cv_results强化了阈值调优与交叉验证可视化的工具链Array API、Metadata routing 与 DataFrame 生态narwhals的支持则持续推进。同时大量 Fix 条目树模型缺失值、距离并列时的性能退化、内存泄漏与越界写入等显著提升了数值稳定性与边界情况下的鲁棒性。升级前请特别关注本文第七章列出的行为变化与弃用项以便平滑迁移。关于本次发布说明的完整原始内容与所有贡献者名单可查阅 doc/whats_new/v1.9.rst新特性示例见 examples/release_highlights/plot_release_highlights_1_9_0.py。【免费下载链接】scikit-learnscikit-learn: machine learning in Python项目地址: https://gitcode.com/gh_mirrors/sc/scikit-learn创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考