.. _array_api:

================================
数组 API 支持（实验性）
================================

.. currentmodule:: sklearn

 `Array API <https://data-apis.org/array-api/latest/>`_    规范定义了一个标准 API，适用于所有具有类似 NumPy API 的数组操作库。Scikit-learn 的数组 API 支持需要安装 `array-api-compat <https://github.com/data-apis/array-api-compat>`__ 。

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

在这个阶段，此支持被视为 **实验性的**，必须显式启用，如下所述。

.. note::
    目前，只有 `cupy.array_api` 、 `array-api-strict` 、 `cupy` 和 `PyTorch` 已知可以与 scikit-learn 的估计器一起工作。

示例用法
=============

以下是一个代码片段示例，演示如何使用 `CuPy <https ://cupy.dev/>`_    在 GPU 上运行 :class:`~discriminant_analysis.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>

模型训练后，数组形式的拟合属性也将来自与训练数据相同的 Array 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'>

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'

.. _array_api_supported:

支持 `数组API` 兼容输入
======================

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

估计器
-------

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

元估计器
---------

接受数组API输入的元估计器，前提是基础估计器也支持：

- :class:`model_selection.GridSearchCV` 
- :class:`model_selection.RandomizedSearchCV` 
- :class:`model_selection.HalvingGridSearchCV` 
- :class:`model_selection.HalvingRandomSearchCV` 

指标
----

- :func:`sklearn.metrics.cluster.entropy` 
- :func:`sklearn.metrics.accuracy_score` 
- :func:`sklearn.metrics.d2_tweedie_score` 
- :func:`sklearn.metrics.max_error` 
- :func:`sklearn.metrics.mean_absolute_error` 
- :func:`sklearn.metrics.mean_gamma_deviance` 
- :func:`sklearn.metrics.mean_squared_error` 
- :func:`sklearn.metrics.mean_tweedie_deviance` 
- :func:`sklearn.metrics.pairwise.additive_chi2_kernel` 
- :func:`sklearn.metrics.pairwise.chi2_kernel` 
- :func:`sklearn.metrics.pairwise.cosine_similarity` 
- :func:`sklearn.metrics.pairwise.paired_cosine_distances` 
- :func:`sklearn.metrics.r2_score` 
- :func:`sklearn.metrics.zero_one_loss` 

工具
----

- :func:`model_selection.train_test_split` 

覆盖范围预计会随时间增长。请关注GitHub上的专门 `meta-issue <https://github.com/scikit-learn/scikit-learn/issues/22352>`_   以跟踪进展。

返回值类型和拟合属性
--------------------

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

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

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

常见估计器检查
==============

将 `array_api_support` 标签添加到估计器的标签集中，以表明它支持Array API。这将启用专门的检查作为常见测试的一部分，以验证在使用普通NumPy和Array API输入时估计器结果是否相同。
要运行这些检查，你需要在你的测试环境中安装
 `array_api_compat <https://github.com/data-apis/array-api-compat>`_  。要运行完整的检查集，你需要安装
 `PyTorch <https://pytorch.org/>`_    和 `CuPy <https://cupy.dev/>`_    并且拥有一个GPU。无法执行或缺少依赖项的检查将自动跳过。因此，使用 `-v` 标志运行测试以查看哪些检查被跳过是很重要的：

.. prompt:: bash $

    pip install array-api-compat  # 以及根据需要安装其他库
    pytest -k "array_api" -v

关于 MPS 设备支持的说明
--------------------------

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

- https://github.com/pytorch/pytorch/issues/77764

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

.. prompt:: bash $

    PYTORCH_ENABLE_MPS_FALLBACK=1 pytest -k "array_api" -v

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