Note

Go to the end to download the full example code.

KNeighbors: choosing between CDist and standard ONNX#

yobx.sklearn.to_onnx() converts a fitted sklearn.neighbors.KNeighborsClassifier or sklearn.neighbors.KNeighborsRegressor into an onnx.ModelProto.

Two implementations are available, selected automatically at conversion time based on the target_opset argument:

Standard ONNX (default) — uses built-in ONNX operators only (Mul, ReduceSum, MatMul, TopK, …). Runs on any ONNX-compatible runtime. Requires at least opset 13 for the classifier (ReduceSum with axes-as-input) and opset 18 for the regressor (ReduceMean with axes-as-input).
CDist path (opt-in) — delegates pairwise distance computation to the com.microsoft.CDist custom operator, which is natively accelerated by ONNX Runtime. Enable it by passing target_opset={"": <n>, "com.microsoft": 1}.

When to prefer CDist#

Use the CDist path when all of the following are true:

You are deploying to ONNX Runtime (which ships with CDist).
The training set is large (many rows M in _fit_X). CDist is fused at the C++ level and avoids materialising the full (N, M) intermediate matrix in Python.
You are comfortable with a model that cannot run on runtimes that do not implement the com.microsoft custom domain.

Use the standard ONNX path when you need maximum portability.

import numpy as np
import onnxruntime
from sklearn.neighbors import KNeighborsClassifier, KNeighborsRegressor
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from yobx.sklearn import to_onnx

1. Train a KNeighborsClassifier#

rng = np.random.default_rng(0)
X = rng.standard_normal((80, 4)).astype(np.float32)
y = (X[:, 0] > 0).astype(np.int64)

clf = KNeighborsClassifier(n_neighbors=5)
clf.fit(X, y)

KNeighborsClassifier()

In a Jupyter environment, please rerun this cell to show the HTML representation or trust the notebook.
On GitHub, the HTML representation is unable to render, please try loading this page with nbviewer.org.

Standard ONNX path (default)#

Pass a plain integer opset (or omit target_opset entirely). The converter uses built-in ONNX operators only and the resulting model is portable across any ONNX runtime.

onx_std = to_onnx(clf, (X,))
op_types_std = {(n.op_type, n.domain or "") for n in onx_std.graph.node}
print("Standard path nodes:", sorted({t for t, _ in op_types_std}))
assert ("CDist", "com.microsoft") not in op_types_std
assert ("TopK", "") in op_types_std

ref_std = onnxruntime.InferenceSession(
    onx_std.SerializeToString(), providers=["CPUExecutionProvider"]
)
labels_std = ref_std.run(None, {"X": X})[0]
assert (labels_std == clf.predict(X).astype(np.int64)).all()
print("Standard path labels match sklearn ✓")

Standard path nodes: ['Add', 'ArgMax', 'Div', 'Gather', 'MatMul', 'Max', 'Mul', 'OneHot', 'ReduceSum', 'Reshape', 'Sqrt', 'Sub', 'TopK']
Standard path labels match sklearn ✓

CDist path (com.microsoft)#

Pass a dict target opset that includes "com.microsoft": 1. The converter inserts a single com.microsoft.CDist node for distance computation, which ONNX Runtime executes via a fused C++ kernel.

onx_cd = to_onnx(clf, (X,), target_opset={"": 18, "com.microsoft": 1})
op_types_cd = {(n.op_type, n.domain or "") for n in onx_cd.graph.node}
print("CDist path nodes:", sorted({t for t, _ in op_types_cd}))
assert ("CDist", "com.microsoft") in op_types_cd

ref_cd = onnxruntime.InferenceSession(
    onx_cd.SerializeToString(), providers=["CPUExecutionProvider"]
)
labels_cd = ref_cd.run(None, {"X": X})[0]
assert (labels_cd == clf.predict(X).astype(np.int64)).all()
print("CDist path labels match sklearn ✓")

CDist path nodes: ['ArgMax', 'CDist', 'Div', 'Gather', 'Max', 'OneHot', 'ReduceSum', 'Reshape', 'TopK']
CDist path labels match sklearn ✓

Both paths produce identical predictions#

assert (labels_std == labels_cd).all(), "Paths produce different labels!"
print("Both paths agree ✓")

Both paths agree ✓

2. KNeighborsRegressor — standard ONNX path#

The regressor uses ReduceMean with axes as an input, which requires at least opset 18.

X_r = rng.standard_normal((60, 3)).astype(np.float32)
y_r = (X_r[:, 0] * 3 + X_r[:, 1]).astype(np.float32)

reg = KNeighborsRegressor(n_neighbors=5)
reg.fit(X_r, y_r)

onx_reg = to_onnx(reg, (X_r,))  # uses opset 18 by default

ref_reg = onnxruntime.InferenceSession(
    onx_reg.SerializeToString(), providers=["CPUExecutionProvider"]
)
preds_onnx = ref_reg.run(None, {"X": X_r})[0]
preds_sk = reg.predict(X_r).astype(np.float32)
assert np.allclose(preds_onnx, preds_sk, atol=1e-5), "Regressor predictions differ!"
print("Regressor predictions match sklearn ✓")

Regressor predictions match sklearn ✓

3. Inside a Pipeline#

Both implementations work transparently inside a scikit-learn Pipeline.

pipe = Pipeline([("scaler", StandardScaler()), ("clf", KNeighborsClassifier(n_neighbors=5))])
pipe.fit(X, y)

onx_pipe = to_onnx(pipe, (X,))
ref_pipe = onnxruntime.InferenceSession(
    onx_pipe.SerializeToString(), providers=["CPUExecutionProvider"]
)
labels_pipe = ref_pipe.run(None, {"X": X})[0]
assert (labels_pipe == pipe.predict(X).astype(np.int64)).all()
print("Pipeline labels match sklearn ✓")

Pipeline labels match sklearn ✓

Total running time of the script: (0 minutes 0.274 seconds)

Related examples

Converting sksurv IPCRidge to ONNX

Using sklearn-onnx to convert any scikit-learn estimator

Converting a scikit-learn KMeans to ONNX

Gallery generated by Sphinx-Gallery

	n_neighbors n_neighbors: int, default=5 Number of neighbors to use by default for :meth:`kneighbors` queries.	5
	weights weights: {'uniform', 'distance'}, callable or None, default='uniform' Weight function used in prediction. Possible values: - 'uniform' : uniform weights. All points in each neighborhood are weighted equally. - 'distance' : weight points by the inverse of their distance. in this case, closer neighbors of a query point will have a greater influence than neighbors which are further away. - [callable] : a user-defined function which accepts an array of distances, and returns an array of the same shape containing the weights. Refer to the example entitled :ref:`sphx_glr_auto_examples_neighbors_plot_classification.py` showing the impact of the `weights` parameter on the decision boundary.	'uniform'
	algorithm algorithm: {'auto', 'ball_tree', 'kd_tree', 'brute'}, default='auto' Algorithm used to compute the nearest neighbors: - 'ball_tree' will use :class:`BallTree` - 'kd_tree' will use :class:`KDTree` - 'brute' will use a brute-force search. - 'auto' will attempt to decide the most appropriate algorithm based on the values passed to :meth:`fit` method. Note: fitting on sparse input will override the setting of this parameter, using brute force.	'auto'
	leaf_size leaf_size: int, default=30 Leaf size passed to BallTree or KDTree. This can affect the speed of the construction and query, as well as the memory required to store the tree. The optimal value depends on the nature of the problem.	30
	p p: float, default=2 Power parameter for the Minkowski metric. When p = 1, this is equivalent to using manhattan_distance (l1), and euclidean_distance (l2) for p = 2. For arbitrary p, minkowski_distance (l_p) is used. This parameter is expected to be positive.	2
	metric metric: str or callable, default='minkowski' Metric to use for distance computation. Default is "minkowski", which results in the standard Euclidean distance when p = 2. See the documentation of `scipy.spatial.distance `_ and the metrics listed in :class:`~sklearn.metrics.pairwise.distance_metrics` for valid metric values. If metric is "precomputed", X is assumed to be a distance matrix and must be square during fit. X may be a :term:`sparse graph`, in which case only "nonzero" elements may be considered neighbors. If metric is a callable function, it takes two arrays representing 1D vectors as inputs and must return one value indicating the distance between those vectors. This works for Scipy's metrics, but is less efficient than passing the metric name as a string.	'minkowski'
	metric_params metric_params: dict, default=None Additional keyword arguments for the metric function.	None
	n_jobs n_jobs: int, default=None The number of parallel jobs to run for neighbors search. ``None`` means 1 unless in a :obj:`joblib.parallel_backend` context. ``-1`` means using all processors. See :term:`Glossary ` for more details. Doesn't affect :meth:`fit` method.	None

KNeighbors: choosing between CDist and standard ONNX#

When to prefer CDist#

1. Train a KNeighborsClassifier#

Standard ONNX path (default)#

CDist path (com.microsoft)#

Both paths produce identical predictions#

2. KNeighborsRegressor — standard ONNX path#

3. Inside a Pipeline#

This Page