Workflow:Rapidsai Cuml GPU Clustering
| Knowledge Sources | |
|---|---|
| Domains | Machine_Learning, Clustering, GPU_Computing |
| Last Updated | 2026-02-08 12:00 GMT |
Overview
End-to-end process for GPU-accelerated clustering of tabular data using cuML's KMeans, DBSCAN, and HDBSCAN algorithms with scikit-learn-compatible APIs.
Description
This workflow covers the standard procedure for performing unsupervised clustering on NVIDIA GPUs using the RAPIDS cuML library. It leverages GPU parallelism to achieve 10-50x speedups over CPU-based scikit-learn equivalents on large datasets. The workflow covers data loading into GPU memory, algorithm selection and configuration, model fitting, label assignment, and result evaluation. cuML clustering algorithms accept cuDF DataFrames, CuPy arrays, and NumPy arrays as input, automatically handling host-to-device transfers when needed.
Usage
Execute this workflow when you have a tabular dataset and need to discover natural groupings or segment data points into clusters. Typical use cases include customer segmentation, anomaly detection (via DBSCAN noise labels), image compression (via KMeans quantization), and exploratory data analysis. Choose KMeans when the number of clusters is known, DBSCAN when clusters have arbitrary shapes and density-based separation is appropriate, or HDBSCAN for hierarchical density-based clustering without requiring a fixed epsilon parameter.
Execution Steps
Step 1: Data Preparation
Load the dataset into GPU memory using cuDF or CuPy. Convert from host arrays (NumPy, pandas) if necessary. Ensure features are numeric and handle missing values before clustering. Optionally apply feature scaling (e.g., StandardScaler) since distance-based algorithms like KMeans and DBSCAN are sensitive to feature magnitudes.
Key considerations:
- cuML accepts cuDF DataFrames, CuPy arrays, NumPy arrays, and pandas DataFrames
- Automatic host-to-device transfer occurs for CPU arrays but explicit GPU data avoids overhead
- Feature scaling is recommended for KMeans and DBSCAN but not required for all algorithms
Step 2: Algorithm Selection and Configuration
Choose the clustering algorithm based on the problem characteristics. Configure hyperparameters appropriate to the algorithm:
KMeans: Specify `n_clusters`, `max_iter`, `tol`, and initialization method (`scalable-k-means++` recommended for GPU). Set `n_init` for multiple random starts.
DBSCAN: Specify `eps` (maximum neighborhood distance), `min_samples` (minimum points for a core sample), and `metric` (euclidean, cosine, or precomputed). Choose `algorithm` as `brute` or `rbc` (random ball cover).
HDBSCAN: Specify `min_cluster_size`, `min_samples`, and `cluster_selection_method` (eom or leaf). HDBSCAN automatically determines the number of clusters.
Step 3: Model Fitting
Call the `fit()` method on the chosen estimator with the prepared data. The GPU kernel executes the iterative clustering algorithm. For KMeans, this involves alternating centroid assignment and update steps. For DBSCAN, this involves computing pairwise distances in batches and propagating cluster labels through core points. For HDBSCAN, this builds a hierarchical tree and extracts flat clusters.
Key considerations:
- KMeans supports `sample_weight` for weighted clustering
- DBSCAN's `max_mbytes_per_batch` controls GPU memory usage for large datasets
- HDBSCAN returns `probabilities_` indicating cluster membership confidence
Step 4: Label Assignment and Prediction
Retrieve cluster labels from the fitted model's `labels_` attribute. For KMeans, use `predict()` to assign new data points to existing clusters. DBSCAN labels noise points as -1. HDBSCAN provides both hard labels and soft membership probabilities.
What happens:
- KMeans: `labels_` contains cluster IDs (0 to n_clusters-1), `predict()` assigns new points
- DBSCAN: `labels_` contains cluster IDs with -1 for noise, `core_sample_indices_` lists core points
- HDBSCAN: `labels_` contains cluster IDs with -1 for noise, `probabilities_` gives confidence scores
Step 5: Result Evaluation
Evaluate clustering quality using cuML's metrics module. Compute inertia (for KMeans), silhouette score, adjusted Rand index (if ground truth available), or other relevant metrics. Optionally transform data to cluster-distance space using KMeans `transform()` for downstream tasks.
Key considerations:
- KMeans provides `inertia_` (sum of squared distances to centroids) and `score()` method
- Use `adjusted_rand_score` from `cuml.metrics` when ground truth labels are available
- Silhouette analysis helps determine optimal number of clusters