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. 傳回值和擬合屬性的類型#

當使用與陣列 API 相容的輸入呼叫函式或方法時，慣例是傳回與輸入資料相同的陣列容器類型和裝置的陣列值。

同樣地，當使用與陣列 API 相容的輸入擬合估計器時，擬合屬性將是來自與輸入相同的函式庫，並儲存在相同的裝置上的陣列。predict 和 transform 方法隨後會期望來自與傳遞至 fit 方法的資料相同的陣列函式庫和裝置的輸入。

但請注意，傳回純量值的評分函式會傳回 Python 純量（通常是 float 實例），而不是陣列純量值。

11.1.3. 常見的估計器檢查#

將 array_api_support 標籤新增至估計器的標籤集中，以表明它支援陣列 API。這將啟用專用檢查，作為常見測試的一部分，以驗證在使用原始 NumPy 和陣列 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 在 MPS 上 (請參閱關於 MPS 裝置支援的注意事項)，不支援 float64 資料類型。在這些情況下，scikit-learn 將會改為使用 float32 資料類型。這可能會導致與不使用陣列 API 調度或使用支援 float64 的裝置相比，出現不同的行為（通常是數值不穩定的結果）。