4. 元数据路由#

注意

元数据路由 API 仍处于实验阶段，尚未为所有估计器实现。有关更多信息，请参阅支持和不支持的模型列表。它可能会在没有通常的弃用周期的情况下发生变化。默认情况下，此功能未启用。您可以通过将 enable_metadata_routing 标志设置为 True 来启用它。

>>> import sklearn
>>> sklearn.set_config(enable_metadata_routing=True)

请注意，本文档中介绍的方法和要求仅在您希望将元数据（例如 sample_weight）传递给某个方法时才相关。如果您只传递 X 和 y，并且没有其他参数/元数据传递给诸如 fit、transform 等方法，则无需进行任何设置。

本指南演示了如何在 scikit-learn 中的对象之间路由和传递元数据。如果您正在开发 scikit-learn 兼容的估计器或元估计器，您可以查看我们的相关开发者指南：元数据路由。

元数据是估计器、评分器或交叉验证（CV）分割器在用户明确将其作为参数传递时所考虑的数据。例如，KMeans 在其 fit() 方法中接受 sample_weight 并将其用于计算其质心。classes 被某些分类器使用，groups 用于某些分割器，但除了 X 和 y 之外，传递给对象方法的任何数据都可以被视为元数据。在 scikit-learn 1.3 版本之前，如果这些对象与其它对象（例如 GridSearchCV 中接受 sample_weight 的评分器）结合使用，则没有单一的 API 来传递此类元数据。

借助元数据路由 API，我们可以使用元估计器（如 Pipeline 或 GridSearchCV）或诸如 cross_validate 等将数据路由到其他对象的函数，将元数据传输到估计器、评分器和 CV 分割器。为了将元数据传递给诸如 fit 或 score 的方法，使用元数据的对象必须请求它。这是通过 set_{method}_request() 方法完成的，其中 {method} 被替换为请求元数据的方法名称。例如，在其 fit() 方法中使用元数据的估计器将使用 set_fit_request()，而评分器将使用 set_score_request()。这些方法允许我们指定要请求哪些元数据，例如 set_fit_request(sample_weight=True)。

对于分组分割器，例如 GroupKFold，默认会请求一个 groups 参数。以下示例对此进行了最佳演示。

4.1. 使用示例#

在这里，我们提供一些示例来展示一些常见用例。我们的目标是通过 cross_validate 传递 sample_weight 和 groups，它将元数据路由到 LogisticRegressionCV 以及使用 make_scorer 创建的自定义评分器，这两者都可以在其方法中使用元数据。在这些示例中，我们希望单独设置是否在不同的消费者中使用元数据。

本节中的示例需要以下导入和数据

>>> import numpy as np
>>> from sklearn.metrics import make_scorer, accuracy_score
>>> from sklearn.linear_model import LogisticRegressionCV, LogisticRegression
>>> from sklearn.model_selection import cross_validate, GridSearchCV, GroupKFold
>>> from sklearn.feature_selection import SelectKBest
>>> from sklearn.pipeline import make_pipeline
>>> n_samples, n_features = 100, 4
>>> rng = np.random.RandomState(42)
>>> X = rng.rand(n_samples, n_features)
>>> y = rng.randint(0, 2, size=n_samples)
>>> my_groups = rng.randint(0, 10, size=n_samples)
>>> my_weights = rng.rand(n_samples)
>>> my_other_weights = rng.rand(n_samples)

4.1.1. 加权评分和拟合#

LogisticRegressionCV 内部使用的分割器 GroupKFold 默认请求 groups。然而，我们需要通过在 LogisticRegressionCV 的 set_fit_request() 方法和 make_scorer 的 set_score_request() 方法中指定 sample_weight=True 来显式请求 sample_weight 以供其和我们的自定义评分器使用。这两个消费者都知道如何在它们的 fit() 或 score() 方法中使用 sample_weight。然后我们可以在 cross_validate 中传递元数据，它会将其路由到任何活动的消费者。

>>> weighted_acc = make_scorer(accuracy_score).set_score_request(sample_weight=True)
>>> lr = LogisticRegressionCV(
...     cv=GroupKFold(),
...     scoring=weighted_acc
... ).set_fit_request(sample_weight=True)
>>> cv_results = cross_validate(
...     lr,
...     X,
...     y,
...     params={"sample_weight": my_weights, "groups": my_groups},
...     cv=GroupKFold(),
...     scoring=weighted_acc,
... )

请注意，在此示例中，cross_validate 将 my_weights 路由到评分器和 LogisticRegressionCV。

如果我们在 cross_validate 的参数中传递 sample_weight，但没有设置任何对象来请求它，就会抛出 UnsetMetadataPassedError，提示我们需要明确设置路由位置。如果传递 params={"sample_weights": my_weights, ...}（请注意拼写错误，即 weights 而不是 weight），也会发生同样的情况，因为 sample_weights 未被其任何底层对象请求。

4.1.2. 加权评分和非加权拟合#

当将诸如 sample_weight 的元数据传递给路由器（元估计器或路由函数）时，所有 sample_weight 消费者都要求显式请求或显式不请求（即 True 或 False）权重。因此，要执行非加权拟合，我们需要将 LogisticRegressionCV 配置为不请求样本权重，以便 cross_validate 不传递权重。

>>> weighted_acc = make_scorer(accuracy_score).set_score_request(sample_weight=True)
>>> lr = LogisticRegressionCV(
...     cv=GroupKFold(), scoring=weighted_acc,
... ).set_fit_request(sample_weight=False)
>>> cv_results = cross_validate(
...     lr,
...     X,
...     y,
...     cv=GroupKFold(),
...     params={"sample_weight": my_weights, "groups": my_groups},
...     scoring=weighted_acc,
... )

如果未调用 linear_model.LogisticRegressionCV.set_fit_request，cross_validate 将引发错误，因为传递了 sample_weight，但 LogisticRegressionCV 未明确配置为识别权重。

4.1.3. 非加权特征选择#

只有当对象的方法知道如何使用元数据时，才能路由元数据，这在大多数情况下意味着它们将其作为显式参数。只有这样，我们才能使用例如 set_fit_request(sample_weight=True) 来设置元数据的请求值。这使得该对象成为消费者。

与 LogisticRegressionCV 不同，SelectKBest 无法使用权重，因此其实例上没有为 sample_weight 设置任何请求值，并且 sample_weight 不会被路由到它。

>>> weighted_acc = make_scorer(accuracy_score).set_score_request(sample_weight=True)
>>> lr = LogisticRegressionCV(
...     cv=GroupKFold(), scoring=weighted_acc,
... ).set_fit_request(sample_weight=True)
>>> sel = SelectKBest(k=2)
>>> pipe = make_pipeline(sel, lr)
>>> cv_results = cross_validate(
...     pipe,
...     X,
...     y,
...     cv=GroupKFold(),
...     params={"sample_weight": my_weights, "groups": my_groups},
...     scoring=weighted_acc,
... )

4.1.4. 不同的评分和拟合权重#

尽管 make_scorer 和 LogisticRegressionCV 都期望键 sample_weight，但我们可以使用别名将不同的权重传递给不同的消费者。在此示例中，我们将 scoring_weight 传递给评分器，将 fitting_weight 传递给 LogisticRegressionCV。

>>> weighted_acc = make_scorer(accuracy_score).set_score_request(
...    sample_weight="scoring_weight"
... )
>>> lr = LogisticRegressionCV(
...     cv=GroupKFold(), scoring=weighted_acc,
... ).set_fit_request(sample_weight="fitting_weight")
>>> cv_results = cross_validate(
...     lr,
...     X,
...     y,
...     cv=GroupKFold(),
...     params={
...         "scoring_weight": my_weights,
...         "fitting_weight": my_other_weights,
...         "groups": my_groups,
...     },
...     scoring=weighted_acc,
... )

4.2. API 接口#

一个消费者是接受并在其至少一个方法（例如 fit、predict、inverse_transform、transform、score、split）中使用某些元数据的对象（估计器、元估计器、评分器、分割器）。仅将元数据转发给其他对象（子估计器、评分器或分割器）而不自身使用元数据的元估计器不是消费者。将元数据路由到其他对象的（元）估计器是路由器。（元）估计器可以同时是消费者和路由器。（元）估计器和分割器为其接受至少一个元数据的每个方法都公开一个 set_{method}_request 方法。例如，如果一个估计器在 fit 和 score 中支持 sample_weight，它会公开 estimator.set_fit_request(sample_weight=value) 和 estimator.set_score_request(sample_weight=value)。这里的 value 可以是：

  • True：方法请求 sample_weight。这意味着如果提供了元数据，它将被使用，否则不会引发错误。

  • False：方法不请求 sample_weight。

  • None：如果传递了 sample_weight，路由器将引发错误。这在几乎所有情况下都是对象实例化时的默认值，并确保在传递元数据时用户明确设置元数据请求。唯一的例外是 Group*Fold 分割器。

  • "param_name"：如果我们要将不同的权重传递给不同的消费者，则为 sample_weight 的别名。如果使用别名，元估计器不应将 "param_name" 转发给消费者，而应转发 sample_weight，因为消费者将期望一个名为 sample_weight 的参数。这意味着对象所需的元数据（例如 sample_weight）与用户提供的变量名（例如 my_weights）之间的映射是在路由器级别完成的，而不是由消费对象本身完成的。

评分器使用 set_score_request 以相同的方式请求元数据。

如果用户传递了元数据（例如 sample_weight），则用户应为所有可能使用 sample_weight 的对象设置元数据请求，否则路由器对象将引发错误。例如，以下代码会引发错误，因为它没有明确指定是否应该将 sample_weight 传递给估计器的评分器。

>>> param_grid = {"C": [0.1, 1]}
>>> lr = LogisticRegression().set_fit_request(sample_weight=True)
>>> try:
...     GridSearchCV(
...         estimator=lr, param_grid=param_grid
...     ).fit(X, y, sample_weight=my_weights)
... except ValueError as e:
...     print(e)
[sample_weight] are passed but are not explicitly set as requested or not
requested for LogisticRegression.score, which is used within GridSearchCV.fit.
Call `LogisticRegression.set_score_request({metadata}=True/False)` for each metadata
you want to request/ignore. See the Metadata Routing User guide
<https://scikit-learn.cn/stable/metadata_routing.html> for more information.

可以通过显式设置请求值来解决此问题

>>> lr = LogisticRegression().set_fit_request(
...     sample_weight=True
... ).set_score_request(sample_weight=False)

在使用示例部分的末尾，我们禁用元数据路由的配置标志。

>>> sklearn.set_config(enable_metadata_routing=False)

4.3. 元数据路由支持状态#

所有消费者（即仅使用元数据而不路由元数据的简单估计器）都支持元数据路由，这意味着它们可以在支持元数据路由的元估计器内部使用。然而，元估计器对元数据路由的支持仍在开发中，以下是支持和尚未支持元数据路由的元估计器和工具列表。

支持元数据路由的元估计器和函数

尚未支持元数据路由的元估计器和工具