Skip to content

Harden parallel HNSW graph processing #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nvzm123 merged 2 commits into from
Sep 30, 2026
Merged

Harden parallel HNSW graph processing #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f72e26d
Harden parallel HNSW graph processing
nvzm123 Sep 29, 2026
03d28e1
Verify parallel HNSW graph processing paths
nvzm123 Sep 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions ci/test_lucene.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,9 @@ set +e
rapids-logger "Check GPU usage"
nvidia-smi

# This GPU lane must execute the real cuVS writer-path sentinel rather than skip it.
export CUVS_TESTS_REQUIRE_GPU=1

rapids-logger "Run cuvs-lucene build and tests"

RAPIDS_CUDA_MAJOR="${RAPIDS_CUDA_VERSION%%.*}"
Expand Down
3 changes: 3 additions & 0 deletions ci/test_lucene_prebuilt.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,9 @@ fi
rapids-logger "Check GPU usage"
nvidia-smi

# This GPU lane must execute the real cuVS writer-path sentinel rather than skip it.
export CUVS_TESTS_REQUIRE_GPU=1

rapids-logger "Configuring conda strict channel priority"
conda config --set channel_priority strict

Expand Down
103 changes: 69 additions & 34 deletions fern/pages/lucene_api/lucene-api-com-nvidia-cuvs-lucene-acceleratedhnswparams.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,28 @@ public class AcceleratedHNSWParams
public int getWriterThreads()
```

Get the maximum thread count for cuVS writes and accelerated-HNSW graph materialization and
serialization.
Get the native cuVS writer threads parameter.

**Returns**

maximum writer and graph-processing thread count
cuVS writer threads parameter

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:148`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:154`_

### getGraphThreads

```java
public int getGraphThreads()
```

Get the maximum threads per HNSW graph materialization or serialization operation. The count
includes the calling thread; shared helper capacity may reduce actual concurrency.

**Returns**

HNSW graph processing threads parameter

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:164`_

### getIntermediateGraphDegree

Expand All @@ -39,7 +53,7 @@ Get the intermediate graph degree

the graph degree parameter

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:157`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:173`_

### getGraphdegree

Expand All @@ -53,7 +67,7 @@ Get the graph degree

the graph degree parameter

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:166`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:182`_

### getHnswLayers

Expand All @@ -67,7 +81,7 @@ Get the number of HNSW layers

the number of HNSW layers

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:175`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:191`_

### getMaxConn

Expand All @@ -81,7 +95,7 @@ Get the max connection parameter

the max connection parameter

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:184`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:200`_

### getBeamWidth

Expand All @@ -95,7 +109,7 @@ Get the beam width parameter

the beam width parameter

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:193`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:209`_

### getCagraGraphBuildAlgo

Expand All @@ -109,7 +123,7 @@ Get the CAGRA graph build algorithm

the CAGRA graph build algorithm

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:202`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:218`_

### getCuVSIvfPqParams

Expand All @@ -123,7 +137,7 @@ Get the instance of `CuVSIvfPqParams`

the instance of `CuVSIvfPqParams`

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:211`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:227`_

### getNumMergeWorkers

Expand All @@ -137,7 +151,7 @@ Get the number of merge workers set to be used in the fallback mechanism

the number of merge workers

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:220`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:236`_

### getMergeExec

Expand All @@ -151,7 +165,7 @@ Get the instance of the `ExecutorService` to be used in the fallback mechanism

the instance of the `ExecutorService`

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:229`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:245`_

### getStrategy

Expand All @@ -168,7 +182,7 @@ When CUSTOM is chosen, the build algorithm and its parameters (either defaults o

get the chosen `Strategy`

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:241`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:257`_

### getCuvsDistanceType

Expand All @@ -182,7 +196,7 @@ Get the cuvs distance type

the distance type

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:250`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:266`_

### getNNDescentNumIterations

Expand All @@ -196,7 +210,7 @@ get the number of Iterations to run if building with NN_DESCENT

the number of iterations for NN_DESCENT

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:259`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:275`_

### getHnswHeuristicType

Expand All @@ -211,16 +225,15 @@ beamWidth. Only consulted under the `Strategy#HEURISTIC` strategy.

the `HnswHeuristicType` to hand to cuVS

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:269`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:285`_

### withWriterThreads

```java
public Builder withWriterThreads(int writerThreads)
```

Set the maximum number of threads used for cuVS writes and accelerated-HNSW graph
materialization and serialization.
Set the number of native cuVS writer threads while building the index.
Valid range - Minimum: \{@value MIN_WRITER_THREADS\}, Maximum: \{@value MAX_WRITER_THREADS\}
Default value - \{@value DEFAULT_WRITER_THREADS\}

Expand All @@ -234,7 +247,29 @@ Default value - \{@value DEFAULT_WRITER_THREADS\}

instance of `Builder`

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:335`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:353`_

### withGraphThreads

```java
public Builder withGraphThreads(int graphThreads)
```

Set the maximum threads per HNSW graph materialization or serialization operation. The count
includes the calling thread. Valid range - Minimum: \{@value MIN_GRAPH_THREADS\}, Maximum:
\{@value MAX_GRAPH_THREADS\}. Default value - \{@value DEFAULT_GRAPH_THREADS\}.

**Parameters**

| Name | Description |
| --- | --- |
| `graphThreads` | maximum graph-processing threads per operation |

**Returns**

instance of `Builder`

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:366`_

### withIntermediateGraphDegree

Expand All @@ -256,7 +291,7 @@ Default value - \{@value DEFAULT_INT_GRAPH_DEGREE\}

instance of `Builder`

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:348`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:379`_

### withGraphDegree

Expand All @@ -278,7 +313,7 @@ Default value - \{@value DEFAULT_GRAPH_DEGREE\}

instance of `Builder`

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:361`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:392`_

### withHNSWLayer

Expand All @@ -300,7 +335,7 @@ Default value - \{@value DEFAULT_HNSW_LAYERS\}

instance of `Builder`

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:374`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:405`_

### withMaxConn

Expand All @@ -322,7 +357,7 @@ Default value - \{@value DEFAULT_MAX_CONN\}

instance of `Builder`

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:387`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:418`_

### withBeamWidth

Expand All @@ -344,7 +379,7 @@ Default value - \{@value DEFAULT_BEAM_WIDTH\}

instance of `Builder`

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:400`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:431`_

### withCagraGraphBuildAlgo

Expand All @@ -365,7 +400,7 @@ Default value - NN_DESCENT

instance of `Builder`

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:412`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:443`_

### withCuVSIvfPqParams

Expand All @@ -385,7 +420,7 @@ Set the instance of `CuVSIvfPqParams`

instance of `Builder`

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:423`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:454`_

### withNumMergeWorkers

Expand All @@ -406,7 +441,7 @@ Default value - \{@value DEFAULT_NUM_MERGE_WORKERS\}

instance of `Builder`

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:435`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:466`_

### withMergeExecutorService

Expand All @@ -427,7 +462,7 @@ Default value an instance with one thread

instance of `Builder`

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:447`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:478`_

### withStrategy

Expand All @@ -453,7 +488,7 @@ Default value - HEURISTIC

instance of `Builder`

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:464`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:495`_

### withCuvsDistanceType

Expand All @@ -473,7 +508,7 @@ Set the CuvsDistanceType

instance of `Builder`

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:475`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:506`_

### withNNDescentNumIterations

Expand All @@ -496,7 +531,7 @@ Default value - \{@value DEFAULT_NN_DESCENT_NUM_ITERATIONS\}

instance of `Builder`

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:489`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:520`_

### withHnswHeuristicType

Expand All @@ -520,7 +555,7 @@ the equivalent HNSW graph (graph degree = 2 * maxConn).

instance of `Builder`

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:504`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:535`_

### build

Expand All @@ -534,6 +569,6 @@ Create an instance of `AcceleratedHNSWParams`

instance of `AcceleratedHNSWParams`

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:549`_
_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:582`_

_Source: `java/cuvs-lucene/src/main/java/com/nvidia/cuvs/lucene/AcceleratedHNSWParams.java:17`_
Loading
Loading