Delegate CAGRA build heuristics to cuVS instead of hardcoding them by imotov · Pull Request #177 · NVIDIA/cuvs-lucene

imotov · 2026-07-20T18:14:34Z

Replace the hand-rolled IVF-PQ parameter derivation and the 5M-vector algorithm switch in CagraIndexParamsFactory with cuVS's own heuristics: the GPU-native path now uses AUTO_SELECT, and the accelerated-HNSW path uses CagraIndexParams.fromHnswParams(), derived from maxConn/beamWidth. Algorithm selection now differs per path: accelerated-HNSW keeps a dataset-size crossover but at cuVS's 1M vectors rather than our 5M, while the GPU-native path's AUTO_SELECT chooses on available device memory instead of size, using each algorithm's default parameters.

Expose the cuVS HNSW heuristic type on AcceleratedHNSWParams, defaulting to SAME_GRAPH_FOOTPRINT.

Fixes #149

copy-pr-bot · 2026-07-20T18:14:37Z

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

imotov · 2026-07-20T18:19:39Z

/ok to test f320ada

imotov · 2026-07-20T19:33:00Z

/ok to test 6d7fc62

imotov · 2026-07-21T00:02:47Z

/ok to test f9fd999

achirkin · 2026-07-22T08:57:35Z

Let's get NVIDIA/cuvs#2345 merged and then use cagra::index_params::from_dataset for constructing CAGRA parameters independently from HNSW. The reason for this is that we will soon introduce a variable-degree graph building for HNSW by default (NVIDIA/cuvs#2031); the feature is useful for HNSW but detrimental for CAGRA GPU search.

paul-aiyedun

Changes overall look good to me. I just had a few questions.

cjnolet

LGTM!

imotov · 2026-07-23T19:09:26Z

Let's get NVIDIA/cuvs#2345 merged and then use cagra::index_params::from_dataset for constructing CAGRA parameters independently from HNSW. The reason for this is that we will soon introduce a variable-degree graph building for HNSW by default (NVIDIA/cuvs#2031); the feature is useful for HNSW but detrimental for CAGRA GPU search.

@achirkin, it looks like your PR keeps the fromHnswParams signature intact and only refactors its internal implementation. Because of that, I'm not entirely sure why this PR needs to wait for yours. Wouldn't this PR automatically benefit from your changes once your PR is merged? As far as I can tell, there doesn't appear to be a direct dependency between the two. What am I missing?

imotov · 2026-07-24T20:32:27Z

/ok to test 692229e

imotov · 2026-07-24T21:26:41Z

/ok to test 87e16ac

achirkin · 2026-07-27T04:41:57Z

@imotov there are two things:

from_hnsw_params means you need to introduce hnsw params that are foreign to cagra and lead weird artifacts like rounding down the graph degree
(More important) next PR CAGRA: variable graph degree for CPU-based algorithm cuvs#2031 changes the behavior of from_hnsw_params to produce a variable degree graph that degrades CAGRA GPU search - without compile-time error or any warning to a user.
In general, we split the heuristics in two because depending on whether you search via CAGRA on GPU or via HNSW on CPU, the optimal parameters are different and I expect the heuristics to slightly diverge.

imotov · 2026-07-28T01:50:20Z

/ok to test e8167e2

imotov · 2026-07-28T02:33:24Z

/ok to test 1b0fd04

imotov · 2026-07-28T02:50:56Z

/ok to test 3e7c48d

imotov · 2026-07-28T04:23:28Z

/ok to test 8e6ebe3

imotov · 2026-07-28T04:45:27Z

/ok to test ca62402

imotov · 2026-07-28T05:05:42Z

/ok to test 6132d5f

imotov · 2026-07-28T05:25:07Z

/ok to test 1ce03b4

imotov · 2026-07-28T15:58:12Z

/ok to test 7b31187

imotov · 2026-08-03T22:37:40Z

/ok to test 9ab46b1

imotov · 2026-08-03T22:54:17Z

@achirkin based on our recent discussion, could you take another look and let me know what you think and how it fits into your recent change in NVIDIA/cuvs#2345.

achirkin · 2026-08-04T15:27:20Z

@imotov thanks for the updates! Do I understand it right, that the current PR only covers the HNSW heuristics (take beamWidth as argument and produce optimal config for CAGRA build, export and HNSW search), but doesn't yet support CAGRA heuristics (take build quality as argument and produce optimal config for CAGRA build and CAGRA search)?

achirkin · 2026-08-04T15:30:17Z

+            .withIntermediateGraphDegree(gpuSearchParams.getIntermediateGraphDegree())
+            .withNumWriterThreads(gpuSearchParams.getWriterThreads());
+    if (gpuSearchParams.getStrategy().equals(GPUSearchParams.Strategy.HEURISTIC)) {
+      // AUTO_SELECT: cuVS picks the build algorithm and derives its parameters at build time, so


I would assume here we'd go similar to the HNSW code below, i.e.:

CagraIndexParams derived = CagraIndexParams.fromDataset(... gpuSearchParams.build_quality()); ...

imotov · 2026-08-04T15:41:42Z

@achirkin the only way I see how it could support build quality as argument is by switching from AUTO_SELECT algo seclection to using CagraIndexParams.fromDataset, which, as far as I understand, will switch the process from considering device memory to fully relying on dataset and will have a few other differences. Is this what we want to do?

achirkin · 2026-08-04T18:54:06Z

It is arguably different from otherwise default CAGRA settings, but the logic at the moment is exactly the same as in HSNW path: we just use the dataset dimensions to choose the optimal parameters / select graph algo.

imotov · 2026-08-06T00:17:13Z

/ok to test 186a629

imotov · 2026-08-06T01:31:05Z

/ok to test bf38b05

imotov · 2026-08-06T01:44:03Z

/ok to test 27e2a75

imotov · 2026-08-06T02:55:13Z

@achirkin could you take another look?

achirkin

Thanks, @imotov, for the updates! Overall looks good from my perspective, but we need to keep the intermediate graph degree parameter from the heuristics (see below).

imotov · 2026-08-06T17:10:04Z

/ok to test 8305a87

achirkin

Great, thanks for the updates!

jameslamb · 2026-08-07T19:08:58Z

This had at one time required adi-packaging-codeowners approval but no longer does. Anyone with Write access is welcome to merge this when you're ready.

imotov · 2026-08-07T22:21:32Z

/ok to test 3411fac

imotov · 2026-08-07T23:43:41Z

/merge

imotov added improvement Improves an existing functionality non-breaking Introduces a non-breaking change labels Jul 20, 2026

imotov marked this pull request as ready for review July 21, 2026 01:06

imotov requested a review from a team as a code owner July 21, 2026 01:06

paul-aiyedun reviewed Jul 23, 2026

View reviewed changes

cjnolet approved these changes Jul 23, 2026

View reviewed changes

imotov force-pushed the issue-149/use-cuvs-heuristics-in-cuvs-lucene branch from a3df879 to 2b55668 Compare July 24, 2026 20:24

imotov requested a review from a team as a code owner July 24, 2026 20:24

imotov changed the base branch from main to release/26.08 July 24, 2026 20:31

imotov requested review from a team as code owners July 24, 2026 21:21

imotov requested a review from jameslamb July 24, 2026 21:21

imotov marked this pull request as draft July 24, 2026 21:23

imotov marked this pull request as ready for review August 3, 2026 22:43

cjnolet removed request for a team August 4, 2026 02:49

achirkin reviewed Aug 4, 2026

View reviewed changes

Swtich from AUTO_SELECT to fromDataset

186a629

imotov added 2 commits August 5, 2026 15:15

Fix metric setting that got lost in refactoring

520a4be

Fix tests that fail without GPU

bf38b05

Fix copyright

27e2a75

achirkin suggested changes Aug 6, 2026

View reviewed changes

Comment thread src/main/java/com/nvidia/cuvs/lucene/GPUSearchParams.java Outdated

Comment thread src/main/java/com/nvidia/cuvs/lucene/CagraIndexParamsFactory.java Outdated

imotov added 2 commits August 6, 2026 06:15

Remove upper bound for build quality

70e8247

Don't override IntermediateGraphDegree

8305a87

imotov requested a review from achirkin August 7, 2026 04:22

achirkin approved these changes Aug 7, 2026

View reviewed changes

jameslamb removed their request for review August 7, 2026 19:08

Merge branch 'main' into issue-149/use-cuvs-heuristics-in-cuvs-lucene

3411fac

rapids-bot Bot merged commit 61431aa into NVIDIA:main Aug 7, 2026
14 checks passed

Uh oh!

Conversation

imotov commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

copy-pr-bot Bot commented Jul 20, 2026

Uh oh!

imotov commented Jul 20, 2026

Uh oh!

imotov commented Jul 20, 2026

Uh oh!

imotov commented Jul 21, 2026

Uh oh!

achirkin commented Jul 22, 2026

Uh oh!

paul-aiyedun left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cjnolet left a comment

Choose a reason for hiding this comment

Uh oh!

imotov commented Jul 23, 2026

Uh oh!

imotov commented Jul 24, 2026

Uh oh!

imotov commented Jul 24, 2026

Uh oh!

achirkin commented Jul 27, 2026

Uh oh!

imotov commented Jul 28, 2026

Uh oh!

imotov commented Jul 28, 2026

Uh oh!

imotov commented Jul 28, 2026

Uh oh!

imotov commented Jul 28, 2026

Uh oh!

imotov commented Jul 28, 2026

Uh oh!

imotov commented Jul 28, 2026

Uh oh!

imotov commented Jul 28, 2026

Uh oh!

imotov commented Jul 28, 2026

Uh oh!

imotov commented Aug 3, 2026

Uh oh!

imotov commented Aug 3, 2026

Uh oh!

achirkin commented Aug 4, 2026

Uh oh!

achirkin Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

imotov commented Aug 4, 2026

Uh oh!

achirkin commented Aug 4, 2026

Uh oh!

imotov commented Aug 6, 2026

Uh oh!

imotov commented Aug 6, 2026

Uh oh!

imotov commented Aug 6, 2026

Uh oh!

imotov commented Aug 6, 2026

Uh oh!

achirkin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

imotov commented Aug 6, 2026

Uh oh!

achirkin left a comment

Choose a reason for hiding this comment

Uh oh!

imotov commented Jul 20, 2026 •

edited

Loading