1. 元数据路由#

注意

元数据路由 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 参数。以下示例可以更好地说明这一点。

1.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)

1.1.1. 加权评分和拟合#

LogisticRegressionCV 内部使用的分割器 GroupKFold 默认情况下会请求 groups。但是，我们需要为它和我们的自定义评分器显式请求 sample_weight，在 LogisticRegressionCV`s `set_fit_request() 方法和 make_scorer`s `set_score_request 方法中指定 sample_weight=True。两个消费者都知道如何在它们的 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 的 params 中传递 sample_weight，但没有设置任何对象来请求它，则会引发 UnsetMetadataPassedError，提示我们需要显式设置路由位置。如果传递了 params={"sample_weights": my_weights, ...}（注意拼写错误，即 weights 而不是 weight），也会出现这种情况，因为 sample_weights 没有被其任何底层对象请求。

1.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 没有被明确配置为识别权重。

1.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,
... )

1.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,
... )

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

可以通过明确设置请求值来解决此问题。

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

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

>>> sklearn.set_config(enable_metadata_routing=False)

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

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

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

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