Initial cut for a cuVS Java API #450

chatman · 2024-11-08T14:05:47Z

A Java API for cuVS for easy integration into Apache Lucene or other Java based projects.

Try:

./build.sh libcuvs
./build.sh java

For generating docs, mvn javadoc:javadoc

Prerequisites:

JDK 22
Maven 3.9.6+

Todo:

Generate project panama classes using jextract on every build
Algorithms other than Cagra
Prefiltering in cagra

Co-authored-by: Vivek Narang <[email protected]>

copy-pr-bot · 2024-11-08T14:05:51Z

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.

chatman · 2024-11-08T14:07:30Z

FYI @cjnolet ^
An ExampleApp.java is added as a starting point for the review.

cjnolet · 2024-11-08T16:06:56Z

/ok to test

chatman · 2024-11-18T02:56:53Z

@naramgvivek10 Let's move CuVSResources to the cuvs package instead of common? That way we can abstract out the internals of Panama out of sight of the users.

cjnolet · 2025-01-16T01:30:04Z

java/cuvs-java/src/main/java/com/nvidia/cuvs/panama/CuVSCagraIndexParams.java

@@ -0,0 +1,354 @@
+/*
+ * Copyright (c) 2025, NVIDIA CORPORATION.


Just a small nitpick: I notice this file is prefixed with "CuVS" while most of the other files are prefixed with "Cuvs". I personally prefer "CuVS" (or even "cuVS" if that doesn't break convention too badly) but I would at least make it consistent.

Thanks for this note. I will fix this soon.

ChrisHegarty · 2025-01-20T11:57:09Z

java/cuvs-java/src/main/java/com/nvidia/cuvs/BruteForceIndex.java

+  private MethodHandle searchMethodHandle;
+  private MethodHandle destroyIndexMethodHandle;
+  private MethodHandle serializeMethodHandle;
+  private MethodHandle deserializeMethodHandle;


Can we make these MethodHandles static final - since they optimise much nicer by the JVM? I'm happy to rework some of the code flow here, if possible (and it that would be helpful) - though I'm not overly familiar with the development environment.

Thanks for your valuable feedback. I will try to incorporate this change. Please don't hesitate to suggest and commit to this branch. @chatman please send the invitation. Thanks!

The dev environment is as follows:

Nvidia GPU RTX 2080 or above

Ubuntu 22.04

JDK 22+

Install CUDA 12.6

Install cmake 3.26+

apt install libnccl-dev ninja-build

clone this repository and this branch

./build.sh libcuvs # To build the libcuvs C library

cd java && ./build.sh # To build the java API (cuvs-java)

@chatman @narangvivek10 I'm getting compile errors. Before trying to describe them, lemme explain a little the environment that I'm using. I thought it might be most straightforward to use an AWS cloud instance, g4dn.xlarge, which has Tesla T4, then install the relevant dev tools. Should that instance be suitable to use, or is there another cloud instance or similar that would be more appropriate?

compile errors: https://gist.github.com/ChrisHegarty/35ab79b3ebb8ce80f0861ec9c58b0975

Any advise on emulation, setup, environment, configuration, etc, would be gratefully appreciated.

We use local workstations with NVIDIA GPUs. One thing we realized is that gcc 11 works out of the box for compiling libcuvs (./build.sh libcuvs). Since it comes out of the box with Ubuntu 22.04 LTS, it is our development environment of choice. I got things to work on Fedora 39 as well, but with a lot of trickery to make CUDA pick up an older version of GCC (11), since it comes with GCC 14, which doesn't work in my experience. @cjnolet FYI.

In your case, I don't see which GCC is being used. However, there's a step where HNSWLib patch is applied, which is failing for some reason. Can you try to "build.sh libcuvs" on branch-25.02? If that doesn't work at the same step (patch apply for HNSWLib), there's maybe something broken in the build.

* update ci release script to update the version in build.sh * class name updates --------- Co-authored-by: Vivek Narang <[email protected]>

Co-authored-by: Vivek Narang <[email protected]>

cjnolet · 2025-01-24T00:25:22Z

/ok to test

cjnolet · 2025-01-24T01:10:05Z

/ok to test

…s it is not compiling without it

* Update CI script to update version in pom.xml files * Add and update examples * Add GPU info API methods --------- Co-authored-by: Vivek Narang <[email protected]>

cjnolet · 2025-01-24T23:41:58Z

/ok to test

bdice

I skimmed the packaging details at @cjnolet's request. There are some merge conflicts with #593. ~~I will push a couple small packaging-related changes to this PR to help it move along.~~ I do not have power to push to this fork, so I can't help here. Please merge in branch-25.02 and run pre-commit.

The biggest work item needed on the packaging side is to clarify what versioning should look like. I think a patch version (25.02.0) is important to add here, as we often publish patch releases. Currently the update-version.sh script uses a full tag like 25.02.00 but that doesn't correspond to what the version strings look like right now. Also, we should probably normalize it to 25.02.0 (drop the extra leading zero), as we do for several packaging systems (all Python wheels are normalized, as is cuDF's Java layer). I would look at how cuDF versions its Java layer for more inspiration, which I linked in a comment.

bdice · 2025-01-26T05:02:41Z

ci/release/update-version.sh

+# Update Java API version
+sed_runner "s/VERSION=\".*\"/VERSION=\"${NEXT_FULL_TAG}\"/g" java/build.sh
+for FILE in java/*/pom.xml; do
+  sed_runner "/<!--CUVS_JAVA#VERSION_UPDATE_MARKER_START-->.*<!--CUVS_JAVA#VERSION_UPDATE_MARKER_END-->/s//<!--CUVS_JAVA#VERSION_UPDATE_MARKER_START--><version>${NEXT_FULL_TAG}<\/version><!--CUVS_JAVA#VERSION_UPDATE_MARKER_END-->/g" "${FILE}"


This is currently inconsistent with our normal use of the script. We usually run ./ci/release/update-version.sh 25.02.00 which would assign a value of 25.02.00. However, the pom.xml files use 25.02 without the patch version. I would guess that we do want to have a patch version here, but perhaps we want to normalize it to 25.02.0. That's close to what we do in cuDF's Java code.

Please look at https://github.com/rapidsai/cudf/blob/133e0c869531af94474e0bbb66cb22c5f8ba80f2/ci/release/update-version.sh#L87-L91 and https://github.com/rapidsai/cudf/blob/133e0c869531af94474e0bbb66cb22c5f8ba80f2/java/pom.xml#L24 and see whether we should adopt the same patterns here.

Thanks Bradley, I've updated the version number format to include a patch number also. This should be better for Java artifacts.

Do you think we should normalize it to 25.02.0 instead of 25.02.00? That would align with what we do for Java code elsewhere in RAPIDS, including cuDF and KvikIO.

Hey @bdice I will update the versioning following your suggestion above and push this change soon.

bdice · 2025-01-26T05:03:41Z

java/README.md

+Building
+--------
+
+`./build.sh` will generate the libcuvs_java.so file in internal/ directory, and then build the final jar file for the cuVS Java API in cuvs-java/ directory.


Suggested change

`./build.sh` will generate the libcuvs_java.so file in internal/ directory, and then build the final jar file for the cuVS Java API in cuvs-java/ directory.

`./build.sh` will generate the `libcuvs_java.so` file in the `internal/` directory, and then build the final jar file for the cuVS Java API in the `cuvs-java/` directory.

java/build.sh

java/cuvs-java/pom.xml

java/examples/pom.xml

rapids_config.cmake

… making version include a patch number, ability for .so to be loaded off env var

chatman · 2025-01-27T12:30:08Z

I updated the branch by merging latest branch-25.02 changes. Needed to add a filter param to cagra search (#452).
However, now tests don't work and I see the following (followed by JVM crash):
free(): double free detected in tcache 2

FYI @narangvivek10, please take a look.

chatman · 2025-01-27T14:24:39Z

(FYI @ChrisHegarty, @narangvivek10), Last working commit in this branch is:

Author: Vivek Narang <[email protected]>
Date:   Fri Jan 24 14:45:44 2025 -0500

    Add examples, update GPU info API methods, and update CI script
    
    * Update CI script to update version in pom.xml files
    * Add and update examples
    * Add GPU info API methods
    ---------
    Co-authored-by: Vivek Narang <[email protected]>

cjnolet · 2025-01-28T00:14:17Z

/ok to test

cjnolet · 2025-01-28T00:38:46Z

/ok to test

bdice · 2025-01-28T00:49:31Z

build.sh

+# Build the cuvs Java bindings
+if (( ${NUMARGS} == 0 )) || hasArg java; then
+    # build libcuvs first as the Java API depends on it
+    ./$0 libcuvs


I'm not sure if it is good practice to call this script recursively to build the C++ code. It seems like it will lead to unexpected behavior. For example, how do you ensure that the CLI arguments such as --allgpuarch or --no-mg are being passed through?

I would recommend removing this line, and users must call ./build.sh libcuvs java if the C++ has not yet been built. Perhaps a warning can be issued if hasArg libcuvs is false. I believe this is how we handle the Python builds, which also depend on C++ libraries being built.

Suggested change

./$0 libcuvs

bdice · 2025-01-28T00:50:37Z

cpp/cmake/thirdparty/get_dlpack.cmake

Please revert any files with only copyright changes.

bdice · 2025-01-28T00:52:43Z

ci/release/update-version.sh

+# Update Java API version
+sed_runner "s/VERSION=\".*\"/VERSION=\"${NEXT_FULL_TAG}\"/g" java/build.sh
+for FILE in java/*/pom.xml; do
+  sed_runner "/<!--CUVS_JAVA#VERSION_UPDATE_MARKER_START-->.*<!--CUVS_JAVA#VERSION_UPDATE_MARKER_END-->/s//<!--CUVS_JAVA#VERSION_UPDATE_MARKER_START--><version>${NEXT_FULL_TAG}<\/version><!--CUVS_JAVA#VERSION_UPDATE_MARKER_END-->/g" "${FILE}"


Do you think we should normalize it to 25.02.0 instead of 25.02.00? That would align with what we do for Java code elsewhere in RAPIDS, including cuDF and KvikIO.

…nd bruteforce

…date readme

Initial cut for a cuVS Java API

c777924

Co-authored-by: Vivek Narang <[email protected]>

chatman requested review from a team as code owners November 8, 2024 14:05

chatman requested a review from msarahan November 8, 2024 14:05

github-actions bot added the CMake label Nov 8, 2024

cjnolet added improvement Improves an existing functionality non-breaking Introduces a non-breaking change labels Nov 8, 2024

cjnolet assigned chatman Nov 8, 2024

cjnolet changed the base branch from branch-24.10 to branch-24.12 November 8, 2024 16:06

Vivek Narang added 2 commits November 9, 2024 07:11

API changes, serialize optional tmpFile param + other changes

f9c2df7

make topK configurable

1597158

narangvivek10 force-pushed the java-api branch from 2cfab29 to 1597158 Compare November 11, 2024 15:07

Vivek Narang and others added 10 commits November 14, 2024 05:39

multiple fixes

6f405e9

pom file update

8531be2

sample test

c9b8891

sample test update + other changes

9bb865a

sample test update + use logging

d40b3d0

variable name updates + other

1e03585

Javadoc draft 1

3222536

Fixes for Javadocs, reducing visibility of internals, other refactorings

c5536b6

Loading the .so file from the jar instead of a hardcoded path

2d79580

package renaming and formatting

84c6121

chatman changed the title ~~[WIP] Initial cut for a cuVS Java API~~ Initial cut for a cuVS Java API Nov 18, 2024

Vivek Narang added 3 commits November 18, 2024 00:14

moving CuVSResources + other updates

20562ee

code refactoring

ad11369

javadoc maven config update and bug fixes

6a851ef

cjnolet reviewed Jan 16, 2025

View reviewed changes

ChrisHegarty reviewed Jan 20, 2025

View reviewed changes

Review feedback updates

bc280e4

* update ci release script to update the version in build.sh * class name updates --------- Co-authored-by: Vivek Narang <[email protected]>

narangvivek10 requested a review from a team as a code owner January 22, 2025 22:29

github-actions bot added the ci label Jan 22, 2025

narangvivek10 and others added 2 commits January 23, 2025 08:36

Feature: get GPU information

392d0ff

Co-authored-by: Vivek Narang <[email protected]>

Merge branch 'branch-25.02' into java-api

a0dba4a

fix cmake format and update year

bfd355b

Ishan Chattopadhyaya and others added 3 commits January 24, 2025 18:17

Adding CMAKE_PREFIX_PATH variable back to the Java build.sh script, a…

ab1c53f

…s it is not compiling without it

Add examples, update GPU info API methods, and update CI script

a197d52

* Update CI script to update version in pom.xml files * Add and update examples * Add GPU info API methods --------- Co-authored-by: Vivek Narang <[email protected]>

Merge branch 'branch-25.02' into java-api

69ef479

cjnolet approved these changes Jan 25, 2025

View reviewed changes

bdice reviewed Jan 26, 2025

View reviewed changes

ChrisHegarty and others added 3 commits January 27, 2025 09:37

Ensure Arena is closed when resources is closed

7eb00d5

Merge remote-tracking branch 'rapidsai/branch-25.02' into java-api

fd5e1c1

Fixing compile error due to additional filter param for cagra search,…

a24b3df

… making version include a patch number, ability for .so to be loaded off env var

narangvivek10 and others added 2 commits January 27, 2025 12:13

Merge branch 'branch-25.02' into java-api

daedfcd

close arena only if not alive, update version in pom.xml and cleanup

cf6efdd

bdice reviewed Jan 28, 2025

View reviewed changes

narangvivek10 added 4 commits January 27, 2025 21:42

Refactor GPU info API, search results and simplify mapping for hnsw a…

704d8d6

…nd bruteforce

Update Java versioning in the CI script

37c5dba

Merge branch 'branch-25.02' into java-api

c0d146b

Build script update, revert files with only copyright changes, and up…

8e42da0

…date readme

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Initial cut for a cuVS Java API #450

Initial cut for a cuVS Java API #450

chatman commented Nov 8, 2024 •

edited

Loading

copy-pr-bot bot commented Nov 8, 2024

chatman commented Nov 8, 2024

cjnolet commented Nov 8, 2024

chatman commented Nov 18, 2024

cjnolet Jan 16, 2025

narangvivek10 Jan 16, 2025

ChrisHegarty Jan 20, 2025

narangvivek10 Jan 24, 2025

ChrisHegarty Jan 25, 2025 •

edited

Loading

ChrisHegarty Jan 27, 2025

chatman Jan 27, 2025

cjnolet commented Jan 24, 2025

cjnolet commented Jan 24, 2025

cjnolet commented Jan 24, 2025

bdice left a comment •

edited

Loading

bdice Jan 26, 2025

chatman Jan 27, 2025

bdice Jan 28, 2025

narangvivek10 Jan 28, 2025

bdice Jan 26, 2025

chatman commented Jan 27, 2025

chatman commented Jan 27, 2025

cjnolet commented Jan 28, 2025

cjnolet commented Jan 28, 2025

bdice Jan 28, 2025

bdice Jan 28, 2025

bdice Jan 28, 2025

		@@ -0,0 +1,354 @@
		/*
		* Copyright (c) 2025, NVIDIA CORPORATION.

	`./build.sh` will generate the libcuvs_java.so file in internal/ directory, and then build the final jar file for the cuVS Java API in cuvs-java/ directory.
	`./build.sh` will generate the `libcuvs_java.so` file in the `internal/` directory, and then build the final jar file for the cuVS Java API in the `cuvs-java/` directory.

Initial cut for a cuVS Java API #450

Are you sure you want to change the base?

Initial cut for a cuVS Java API #450

Conversation

chatman commented Nov 8, 2024 • edited Loading

copy-pr-bot bot commented Nov 8, 2024

chatman commented Nov 8, 2024

cjnolet commented Nov 8, 2024

chatman commented Nov 18, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ChrisHegarty Jan 25, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cjnolet commented Jan 24, 2025

cjnolet commented Jan 24, 2025

cjnolet commented Jan 24, 2025

bdice left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chatman commented Jan 27, 2025

chatman commented Jan 27, 2025

cjnolet commented Jan 28, 2025

cjnolet commented Jan 28, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chatman commented Nov 8, 2024 •

edited

Loading

ChrisHegarty Jan 25, 2025 •

edited

Loading

bdice left a comment •

edited

Loading