Skip to content

[26.12] Backport K-means allocations, norms compute, row batching (#3047) - #3077

Merged
rapids-bot[bot] merged 1 commit into
NVIDIA:release/26.12from
divyegala:backport-3047-release-26.12
Nov 17, 2026
Merged

rapids-bot[bot] merged 1 commit into
NVIDIA:release/26.12from
divyegala:backport-3047-release-26.12

Conversation

@divyegala

@divyegala divyegala commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Cherry-picks 471e6d7 from main into release/26.12. #3047 was intended for 26.12 and was merged into main by mistake.

Improve K-means performance towards r27.02

## Optimizations
- Scratch space to avoid re-allocations of the same space across calls / minibatches
- Row batching to improve L2 hit rate for cutile 1-NN
- Remove unnecessary weight compute when not given instead of filling with ones
- Compute just the norms needed by the backend (TF32, FP32, or None)

## Performance evaluation

### H200

<img width="1746" height="1409" alt="image" src="https://github.com/user-attachments/assets/b998061d-d326-4281-8198-0b2a6f8fbf6a" />

## B100

<img width="1742" height="1413" alt="image" src="https://github.com/user-attachments/assets/1de26a9d-3af5-451d-8eee-664d02eb7680" />

### A100

<img width="1750" height="1417" alt="image" src="https://github.com/user-attachments/assets/a87b4b3f-fd27-458e-b033-b3496cbaa30f" />

### RTX Pro 6000

<img width="1530" height="1227" alt="image" src="https://github.com/user-attachments/assets/87709360-d81e-42f8-8c33-58881c86cdf2" />

Authors:
  - https://github.com/huuanhhuyn

Approvers:
  - Divye Gala (https://github.com/divyegala)

URL: NVIDIA#3047
(cherry picked from commit 471e6d7)
@copy-pr-bot

copy-pr-bot Bot commented Nov 16, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

@divyegala divyegala added improvement Improves an existing functionality non-breaking Introduces a non-breaking change labels Nov 16, 2026
@divyegala

Copy link
Copy Markdown
Contributor Author

/ok to test e94bbe8

@coderabbitai

coderabbitai Bot commented Nov 16, 2026

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Summary

Summary by CodeRabbit

  • Performance Improvements
    • Improved clustering and prediction efficiency by reusing temporary resources and reducing unnecessary memory allocation.
    • Optimized nearest-centroid distance calculations and norm handling, including for TF32-enabled workloads.
    • Improved processing of large nearest-neighbor workloads through batching.

The changes update norm policies and row batching in fused 1-NN, revise norm and workspace handling in nearest-centroid computation, and update K-means fitting and prediction to use these paths. Balanced prediction now reuses scratch buffers across minibatches.

Changes: K-means nearest-neighbor flow

Layer / File(s) Summary
Backend norm policies and Cutile batching
cpp/src/distance/detail/fused_distance_nn.cuh, cpp/src/distance/fused_distance_nn-inl.cuh, cpp/src/distance/detail/fused_distance_nn/cutile/fused_1nn_tile.cu
Backend plans now identify when no norms are read. Cutile 1-NN launches query rows in batches based on candidate size and device L2 cache size.
Nearest-centroid norms and workspace
cpp/src/cluster/detail/kmeans_common.cuh, cpp/src/cluster/detail/minClusterDistanceCompute.cu
minClusterAndDistanceCompute accepts a distance-computation flag. The 1-NN path selects, computes, or skips norms according to the backend policy and places required buffers in aligned output storage. The row-norm implementation now uses a shared lane-group kernel.
K-means fitting and prediction integration
cpp/src/cluster/detail/kmeans.cuh, cpp/src/cluster/detail/kmeans_common.cuh
The inertia pass selects and forwards per-batch TF32 norms. Prediction avoids materializing weights when it can use the original or normalized weights, and delegates norm handling to nearest-centroid computation. A null weights pointer now represents unit weights.
Balanced prediction scratch reuse
cpp/src/cluster/detail/kmeans_balanced.cuh
Balanced prediction reuses distance, workspace, and output buffers across minibatches. Missing norms are prefilled for the specified packed-binary metrics; otherwise, prediction can pass a null norm pointer.

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Refactor

Suggested reviewers: tarang-jain, huuanhhuyn, cjnolet, howardhuang1

Merge Risk: Minimal · up to e94bb

This backport changes how K-means computes norms, reuses scratch buffers, and batches cuTile nearest-neighbor launches. No concrete defect was established in the reviewed changes. A very narrow floating-point precision question in the new norm kernel remains unverified and was not scored. Merging looks reasonable once the CI runs requested on this head pass.

Architecture risk: Medium · up to e94bb

The change affects 1 system.

Changed systems: cpp

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

  • observed — cpp (service) was modified; 7 changed files map to changed impact.

Before / after behavior

  • observed — Modified behavior in cpp/src/cluster/detail/kmeans.cuh: cluster_cost adds an optional TF32-norm view parameter, defaulting to std::nullopt.
  • observed — Modified behavior in cpp/src/cluster/detail/kmeans.cuh: cluster_cost forwards the TF32-norm view to distance computation instead of always passing std::nullopt.
  • observed — Modified behavior in cpp/src/cluster/detail/kmeans.cuh: The final inertia pass now determines whether each batch’s assignment plan uses TF32 norms. For host data, it computes norms with that choice; when TF32 norms are selected, it also passes the corresponding TF32 norm view to the cost calculation.
  • observed — Modified behavior in cpp/src/cluster/detail/kmeans.cuh: The final inertia calculation now passes the optional TF32 norm view to cluster_cost.

Reliability and maintainability

  • inferred — Risk-relevant change factors for cpp: blast_radius_2; blast_radius_4; direct_dependents_2
Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names a backport of a K-means change into release/26.12 and lists its three main themes: allocations, norms computation, and row batching. The raw summary shows changes in K-means scratch bu…
Description check Passed The description states that the change cherry-picks commit 471e6d7 from main into release/26.12 and explains that the original PR was merged into main by mistake. This…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names a backport of a K-means change into release/26.12 and lists its three main themes: allocations, norms computation, and row batching. The raw summary shows changes in K-means scratch buffers, norm selection, and cuTile 1-NN row batching, so the title matches the changeset. It does not name the release branch target in detail, but it identifies the main change and the PR it backports.

Full details: Description check

Explanation

The description states that the change cherry-picks commit 471e6d7 from main into release/26.12 and explains that the original PR was merged into main by mistake. This relates directly to the changeset, which is the backported K-means change, so it is not off-topic. It gives little technical detail about the code changes.

Finishing Touches

Generate unit tests (beta)

  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between bde90ed and e94bbe8.

Files selected for processing: 7

  • cpp/src/cluster/detail/kmeans.cuh
  • cpp/src/cluster/detail/kmeans_balanced.cuh
  • cpp/src/cluster/detail/kmeans_common.cuh
  • cpp/src/cluster/detail/minClusterDistanceCompute.cu
  • cpp/src/distance/detail/fused_distance_nn.cuh
  • cpp/src/distance/detail/fused_distance_nn/cutile/fused_1nn_tile.cu
  • cpp/src/distance/fused_distance_nn-inl.cuh

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

@divyegala

Copy link
Copy Markdown
Contributor Author

/merge

@rapids-bot
rapids-bot Bot merged commit d8119f6 into NVIDIA:release/26.12 Nov 17, 2026
121 checks passed
@github-project-automation github-project-automation Bot moved this from Approved to Done in Unstructured Data Processing Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

improvement Improves an existing functionality non-breaking Introduces a non-breaking change

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

3 participants