Skip to content

Delegate CAGRA build heuristics to cuVS instead of hardcoding them - #177

Open
imotov wants to merge 1 commit into
NVIDIA:mainfrom
imotov:issue-149/use-cuvs-heuristics-in-cuvs-lucene
Open

Delegate CAGRA build heuristics to cuVS instead of hardcoding them#177
imotov wants to merge 1 commit into
NVIDIA:mainfrom
imotov:issue-149/use-cuvs-heuristics-in-cuvs-lucene

Conversation

@imotov

@imotov imotov commented Jul 20, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

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

copy-pr-bot Bot commented Jul 20, 2026

Copy link
Copy Markdown

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 imotov added improvement Improves an existing functionality non-breaking Introduces a non-breaking change labels Jul 20, 2026
@imotov

imotov commented Jul 20, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test f320ada

@imotov

imotov commented Jul 20, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test 6d7fc62

@imotov

imotov commented Jul 21, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test f9fd999

@imotov
imotov marked this pull request as ready for review July 21, 2026 01:06
@imotov
imotov requested a review from a team as a code owner July 21, 2026 01:06
@achirkin

achirkin commented Jul 22, 2026

Copy link
Copy Markdown

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
paul-aiyedun reviewed Jul 23, 2026
View reviewed changes

@paul-aiyedun paul-aiyedun left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread src/main/java/com/nvidia/cuvs/lucene/GPUSearchParams.java Outdated
Comment thread src/main/java/com/nvidia/cuvs/lucene/CagraIndexParamsFactory.java Outdated
Comment thread src/main/java/com/nvidia/cuvs/lucene/CagraIndexParamsFactory.java
Comment thread src/test/java/com/nvidia/cuvs/lucene/TestCagraIndexParamsFactory.java
cjnolet
cjnolet approved these changes Jul 23, 2026
View reviewed changes

@cjnolet cjnolet left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

@imotov

imotov commented Jul 23, 2026

Copy link
Copy Markdown
Contributor Author

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
imotov force-pushed the issue-149/use-cuvs-heuristics-in-cuvs-lucene branch from a3df879 to 2b55668 Compare July 24, 2026 20:24
@imotov
imotov requested a review from a team as a code owner July 24, 2026 20:24
@imotov
imotov changed the base branch from main to release/26.08 July 24, 2026 20:31
@imotov

imotov commented Jul 24, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test 692229e

@imotov
imotov requested review from a team as code owners July 24, 2026 21:21
@imotov
imotov requested a review from jameslamb July 24, 2026 21:21
@imotov
imotov marked this pull request as draft July 24, 2026 21:23
@imotov

imotov commented Jul 24, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test 87e16ac

@achirkin

achirkin commented Jul 27, 2026

Copy link
Copy Markdown

@imotov there are two things:

  1. 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
  2. (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

imotov commented Jul 28, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test e8167e2

@imotov

imotov commented Jul 28, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test 1b0fd04

@imotov

imotov commented Jul 28, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test 3e7c48d

@imotov

imotov commented Jul 28, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test 8e6ebe3

@imotov

imotov commented Jul 28, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test ca62402

@imotov

imotov commented Jul 28, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test 6132d5f

@imotov

imotov commented Jul 28, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test 1ce03b4

@imotov

imotov commented Jul 28, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test 7b31187

@imotov

imotov commented Jul 28, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test 1161c7d

@imotov

imotov commented Jul 28, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test df35c3f

@imotov

imotov commented Jul 28, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test a6d6b94

@imotov

imotov commented Jul 28, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test eb77f70

@imotov

imotov commented Jul 28, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test 73c5828

@imotov

imotov commented Jul 28, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test 1a19fdd

@imotov
Delegate CAGRA build heuristics to cuVS
9ab46b1 
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.
The build-algorithm crossover consequently moves from 5M to 1M vectors,
which is where cuVS switches from NN-descent to IVF-PQ.

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

Derive the HNSW M written to segment metadata from the graph actually
built rather than from the configured graph degree, as ceil(degree / 2).
cuVS may truncate the degree for small datasets, and under HEURISTIC it
ignores the configured value entirely; an odd degree previously produced
an M one arc too small for the reader to accept.

Fixes NVIDIA#149
@imotov
imotov force-pushed the issue-149/use-cuvs-heuristics-in-cuvs-lucene branch from 1a19fdd to 9ab46b1 Compare August 3, 2026 22:34
@copy-pr-bot

copy-pr-bot Bot commented Aug 3, 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.

@imotov
imotov changed the base branch from release/26.08 to main August 3, 2026 22:35
@imotov

imotov commented Aug 3, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test 9ab46b1

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

imotov commented Aug 3, 2026

Copy link
Copy Markdown
Contributor Author

@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.

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

achirkin commented Aug 4, 2026

Copy link
Copy Markdown

@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
achirkin reviewed Aug 4, 2026
View reviewed changes
Comment thread src/main/java/com/nvidia/cuvs/lucene/CagraIndexParamsFactory.java
.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

@achirkin achirkin Aug 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

@imotov

imotov commented Aug 4, 2026

Copy link
Copy Markdown
Contributor Author

@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

achirkin commented Aug 4, 2026

Copy link
Copy Markdown

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@cjnolet cjnolet cjnolet approved these changes
@jameslamb jameslamb Awaiting requested review from jameslamb jameslamb was automatically assigned from NVIDIA/adi-packaging-codeowners
+2 more reviewers
@achirkin achirkin achirkin left review comments
@paul-aiyedun paul-aiyedun paul-aiyedun left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

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

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Heuristics in cuvs-lucene are being directly hardcoded based on cuVS heuristics instead of using cuVS heuristics.

4 participants

@imotov @achirkin @cjnolet @paul-aiyedun