11.1. 数组API支持（实验性）#

数组API规范定义了所有具有类似NumPy API的数组操作库的标准API。Scikit-learn的数组API支持需要安装array-api-compat。

一些主要依赖于NumPy（而不是使用Cython）来实现其fit、predict或transform方法算法逻辑的scikit-learn估计器，可以配置为接受任何与数组API兼容的输入数据结构，并自动将操作分派到底层命名空间，而不是依赖于NumPy。

在这个阶段，此支持**被认为是实验性的**，必须像以下解释的那样明确启用。

注意

目前，只有array-api-strict、cupy和PyTorch已知可与scikit-learn的估计器一起使用。

11.1.1. 示例用法#

这是一个示例代码片段，演示如何使用CuPy在GPU上运行LinearDiscriminantAnalysis

>>> from sklearn.datasets import make_classification
>>> from sklearn import config_context
>>> from sklearn.discriminant_analysis import LinearDiscriminantAnalysis
>>> import cupy

>>> X_np, y_np = make_classification(random_state=0)
>>> X_cu = cupy.asarray(X_np)
>>> y_cu = cupy.asarray(y_np)
>>> X_cu.device
<CUDA Device 0>

>>> with config_context(array_api_dispatch=True):
...     lda = LinearDiscriminantAnalysis()
...     X_trans = lda.fit_transform(X_cu, y_cu)
>>> X_trans.device
<CUDA Device 0>

模型训练完成后，作为数组的拟合属性也将来自与训练数据相同的数组API命名空间。例如，如果使用CuPy的数组API命名空间进行训练，则拟合属性将位于GPU上。我们提供了一个实验性的_estimator_with_converted_arrays实用程序，该程序将估计器的属性从数组API传输到ndarray。

>>> from sklearn.utils._array_api import _estimator_with_converted_arrays
>>> cupy_to_ndarray = lambda array : array.get()
>>> lda_np = _estimator_with_converted_arrays(lda, cupy_to_ndarray)
>>> X_trans = lda_np.transform(X_np)
>>> type(X_trans)
<class 'numpy.ndarray'>

11.1.1.1. PyTorch支持#

通过设置array_api_dispatch=True并直接传入张量来支持PyTorch张量。

>>> import torch
>>> X_torch = torch.asarray(X_np, device="cuda", dtype=torch.float32)
>>> y_torch = torch.asarray(y_np, device="cuda", dtype=torch.float32)

>>> with config_context(array_api_dispatch=True):
...     lda = LinearDiscriminantAnalysis()
...     X_trans = lda.fit_transform(X_torch, y_torch)
>>> type(X_trans)
<class 'torch.Tensor'>
>>> X_trans.device.type
'cuda'

11.1.2. 对`Array API`兼容输入的支持#

scikit-learn中支持与数组API兼容输入的估计器和其他工具。

11.1.2.1. 估计器#

decomposition.PCA（使用svd_solver="full"、svd_solver="randomized"和power_iteration_normalizer="QR"）
linear_model.Ridge（使用solver="svd"）
discriminant_analysis.LinearDiscriminantAnalysis（使用solver="svd"）
preprocessing.KernelCenterer
preprocessing.LabelEncoder
preprocessing.MaxAbsScaler
preprocessing.MinMaxScaler
preprocessing.Normalizer

11.1.2.2. 元估计器#

接受数组API输入的元估计器，前提是基础估计器也这样做。

11.1.2.3. 度量#

11.1.2.4. 工具#

model_selection.train_test_split

覆盖范围预计会随着时间推移而增长。请关注专门的 GitHub上的元问题以跟踪进度。

11.1.2.5. 返回值和拟合属性的类型#

当使用兼容Array API的输入调用函数或方法时，惯例是返回与输入数据具有相同数组容器类型和设备的数组值。

同样，当使用兼容Array API的输入拟合估计器时，拟合属性将是来自与输入相同库的数组，并存储在相同的设备上。predict 和 transform 方法随后需要与传递给 fit 方法的数据相同的数组库和设备的输入。

但是请注意，返回标量值的评分函数返回Python标量（通常是 float 实例），而不是数组标量值。

11.1.3. 常见的估计器检查#

将 array_api_support 标签添加到估计器的标签集中，以表明它支持Array API。这将启用作为通用测试一部分的专用检查，以验证当使用普通NumPy和Array API输入时，估计器的结果是否相同。

要运行这些检查，您需要在测试环境中安装 array_api_compat。要运行完整的检查集，您需要同时安装 PyTorch 和 CuPy 并拥有GPU。无法执行或缺少依赖项的检查将自动跳过。因此，使用 -v 标志运行测试以查看哪些检查被跳过非常重要。

pip install array-api-compat  # and other libraries as needed
pytest -k "array_api" -v

11.1.3.1. 关于MPS设备支持的说明#

在macOS上，PyTorch可以使用Metal Performance Shaders (MPS)来访问硬件加速器（例如，M1或M2芯片的内部GPU组件）。但是，在撰写本文时，PyTorch对MPS设备的支持尚不完整。有关更多详细信息，请参见以下GitHub问题：

pytorch/pytorch#77764

要在PyTorch中启用MPS支持，请在运行测试之前设置环境变量 PYTORCH_ENABLE_MPS_FALLBACK=1。

PYTORCH_ENABLE_MPS_FALLBACK=1 pytest -k "array_api" -v

在撰写本文时，所有scikit-learn测试都应该通过，但是，计算速度不一定比CPU设备更好。

11.1.3.2. 关于`float64`的设备支持说明#

scikit-learn中的某些操作将自动对float64精度的浮点值执行操作，以防止溢出并确保正确性（例如，metrics.pairwise.euclidean_distances）。但是，某些数组命名空间和设备的组合，例如PyTorch on MPS（参见关于MPS设备支持的说明）不支持float64数据类型。在这些情况下，scikit-learn将改用float32数据类型。这可能会导致与不使用数组API调度或使用支持float64的设备相比不同的行为（通常是数值不稳定的结果）。