From 8e5224f25a382bb3ada28e610dd07766f496f252 Mon Sep 17 00:00:00 2001 From: Vivek Narang Date: Fri, 7 Feb 2025 08:59:10 -0500 Subject: [PATCH 1/6] update readme --- java/README.md | 43 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 34 insertions(+), 9 deletions(-) diff --git a/java/README.md b/java/README.md index e5676146a2..75a64d6691 100644 --- a/java/README.md +++ b/java/README.md @@ -1,14 +1,39 @@ -Prerequisites -------------- +# CuVS Java API -* JDK 22 -* Maven 3.9.6 or later +CuVS Java API attempts to provide a Java based simple, efficient, and a robust vector search API. -To build this API, please do `./build.sh java` in the top level directory. Since this API is dependent on `libcuvs` it must be noted that `libcuvs` gets built automatically before building this API. +> [!CAUTION] +> This is an experimental release and updates to this API should be expected in the coming days. -Alternatively, please build libcuvs (`./build.sh libcuvs` from top level directory) before building the Java API with `./build.sh` from this directory. +## Prerequisites -Building --------- +- gcc 11.4 +- [nvcc 12.4 or above](https://developer.nvidia.com/cuda-downloads) +- [cmake 3.28 or above](https://cmake.org/download/) +- [maven 3.9.6 or above](https://maven.apache.org/download.cgi) +- [JDK 22](https://openjdk.org/projects/jdk/22/) +- [Ubuntu 22.04](https://releases.ubuntu.com/jammy/) -`./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. + +## Building + +libcuvs libraries are needed for this API. If libcuvs libraries are already not built please do `./build.sh libcuvs java` in the top level directory to build this API. + +Alternatively, if libcuvs libraries are already built and you just want to build this API, please +do `./build.sh java` in the top level directory or just do `./build.sh` in this directory. + +:warning: If you notice the tests failing please replace `mvn verify` with `mvn clean package` in the `build.sh` script found in this directory and try again. This should build the API (and skip the tests). + +## Examples + +For easy understanding we have provided starter examples for CAGRA, HNSW, and Bruteforce and these can be found in the `examples` directory. + +## Javadocs + +To generate javadocs, in this directory (after building the API) please do: + +``` +cd cuvs-java && mvn javadoc:javadoc +``` + +The generated javadocs can be found in `cuvs-java/target/apidocs` From 81f065ef6a84aff17297be721940c3238911e559 Mon Sep 17 00:00:00 2001 From: Vivek Narang Date: Fri, 7 Feb 2025 11:13:42 -0500 Subject: [PATCH 2/6] Update examples readme --- java/examples/README.md | 53 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 48 insertions(+), 5 deletions(-) diff --git a/java/examples/README.md b/java/examples/README.md index d05d7b9117..b11f7ae724 100644 --- a/java/examples/README.md +++ b/java/examples/README.md @@ -1,8 +1,51 @@ -Building and Running --------------------- +# CuVS Java API Examples -Make sure to have JDK 22 and Maven 3.9.6+. +This maven project contains simple examples for CAGRA, HNSW, and Bruteforce algorithms. - mvn clean compile assembly:single +## Prerequisites +- All the prerequisites in the CuVS Java API readme +- libcuvs libraries and Java API should already be built +- In this directory do `mvn package` - java --enable-native-access=ALL-UNNAMED -jar ./target/cagra-sample-1.0-SNAPSHOT-jar-with-dependencies.jar +## Run Examples + +### CAGRA Example +Doing the following in the current directory: +``` +java --enable-native-access=ALL-UNNAMED -cp target/cuvs-java-examples-25.02.0.jar:$HOME/.m2/repository/com/nvidia/cuvs/cuvs-java/25.02.0/cuvs-java-25.02.0.jar com.nvidia.cuvs.examples.CagraExample +``` +Should output the following (with different timestamps): +``` +[2025-02-07 10:18:26.660] [RAFT] [info] optimizing graph +[2025-02-07 10:18:26.660] [RAFT] [info] Graph optimized, creating index +[2025-02-07 10:18:26.670] [RAFT] [info] Saving CAGRA index with dataset +[{3=0.038782578, 2=0.3590463, 0=0.83774555}, {0=0.12472608, 2=0.21700792, 1=0.31918612}, {3=0.047766715, 2=0.20332818, 0=0.48305473}, {1=0.15224178, 0=0.59063464, 3=0.5986642}] +[{3=0.038782578, 2=0.3590463, 0=0.83774555}, {0=0.12472608, 2=0.21700792, 1=0.31918612}, {3=0.047766715, 2=0.20332818, 0=0.48305473}, {1=0.15224178, 0=0.59063464, 3=0.5986642}] + +``` + +### HNSW Example +Doing the following in the current directory: +``` +java --enable-native-access=ALL-UNNAMED -cp target/cuvs-java-examples-25.02.0.jar:$HOME/.m2/repository/com/nvidia/cuvs/cuvs-java/25.02.0/cuvs-java-25.02.0.jar com.nvidia.cuvs.examples.HnswExample +``` +Should output the following (with different timestamps): +``` +[2025-02-07 10:43:20.917] [RAFT] [warning] Intermediate graph degree cannot be larger than dataset size, reducing it to 4 +[2025-02-07 10:43:20.917] [RAFT] [warning] Graph degree (64) cannot be larger than intermediate graph degree (3), reducing graph_degree. +using ivf_pq::index_params nrows 4, dim 2, n_lists 4, pq_dim 8 +[2025-02-07 10:43:21.015] [RAFT] [info] optimizing graph +[2025-02-07 10:43:21.016] [RAFT] [info] Graph optimized, creating index +[{3=0.038782578, 2=0.35904628, 0=0.8377455}, {0=0.12472608, 2=0.21700794, 1=0.31918612}, {3=0.047766715, 2=0.20332818, 0=0.48305473}, {1=0.15224178, 0=0.59063464, 3=0.59866416}] +``` + +### Bruteforce Example +Doing the following in the current directory: +``` +java --enable-native-access=ALL-UNNAMED -cp target/cuvs-java-examples-25.02.0.jar:$HOME/.m2/repository/com/nvidia/cuvs/cuvs-java/25.02.0/cuvs-java-25.02.0.jar com.nvidia.cuvs.examples.BruteForceExample +``` +Should output the following: +``` +[{3=0.038782537, 2=0.35904616, 0=0.83774555}, {0=0.12472606, 2=0.21700788, 1=0.3191862}, {3=0.047766685, 2=0.20332813, 0=0.48305476}, {1=0.15224183, 0=0.5906347, 3=0.5986643}] +[{3=0.038782537, 2=0.35904616, 0=0.83774555}, {0=0.12472606, 2=0.21700788, 1=0.3191862}, {3=0.047766685, 2=0.20332813, 0=0.48305476}, {1=0.15224183, 0=0.5906347, 3=0.5986643}] +``` From c6da45c41a91885ba985760b22a1bf97b0be80ca Mon Sep 17 00:00:00 2001 From: Vivek Narang Date: Fri, 7 Feb 2025 13:22:28 -0500 Subject: [PATCH 3/6] update logging for examples --- java/README.md | 3 ++ java/examples/README.md | 32 +++++++++++-------- java/examples/pom.xml | 11 ------- .../cuvs/examples/BruteForceExample.java | 6 ++-- .../nvidia/cuvs/examples/CagraExample.java | 6 ++-- .../com/nvidia/cuvs/examples/HnswExample.java | 10 +++--- java/examples/src/main/resources/.gitkeep | 0 java/examples/src/main/resources/log4j2.xml | 14 -------- 8 files changed, 29 insertions(+), 53 deletions(-) create mode 100644 java/examples/src/main/resources/.gitkeep delete mode 100644 java/examples/src/main/resources/log4j2.xml diff --git a/java/README.md b/java/README.md index 75a64d6691..5e92f59876 100644 --- a/java/README.md +++ b/java/README.md @@ -5,6 +5,7 @@ CuVS Java API attempts to provide a Java based simple, efficient, and a robust v > [!CAUTION] > This is an experimental release and updates to this API should be expected in the coming days. + ## Prerequisites - gcc 11.4 @@ -24,10 +25,12 @@ do `./build.sh java` in the top level directory or just do `./build.sh` in this :warning: If you notice the tests failing please replace `mvn verify` with `mvn clean package` in the `build.sh` script found in this directory and try again. This should build the API (and skip the tests). + ## Examples For easy understanding we have provided starter examples for CAGRA, HNSW, and Bruteforce and these can be found in the `examples` directory. + ## Javadocs To generate javadocs, in this directory (after building the API) please do: diff --git a/java/examples/README.md b/java/examples/README.md index b11f7ae724..13d7471723 100644 --- a/java/examples/README.md +++ b/java/examples/README.md @@ -16,12 +16,13 @@ java --enable-native-access=ALL-UNNAMED -cp target/cuvs-java-examples-25.02.0.ja ``` Should output the following (with different timestamps): ``` -[2025-02-07 10:18:26.660] [RAFT] [info] optimizing graph -[2025-02-07 10:18:26.660] [RAFT] [info] Graph optimized, creating index -[2025-02-07 10:18:26.670] [RAFT] [info] Saving CAGRA index with dataset -[{3=0.038782578, 2=0.3590463, 0=0.83774555}, {0=0.12472608, 2=0.21700792, 1=0.31918612}, {3=0.047766715, 2=0.20332818, 0=0.48305473}, {1=0.15224178, 0=0.59063464, 3=0.5986642}] -[{3=0.038782578, 2=0.3590463, 0=0.83774555}, {0=0.12472608, 2=0.21700792, 1=0.31918612}, {3=0.047766715, 2=0.20332818, 0=0.48305473}, {1=0.15224178, 0=0.59063464, 3=0.5986642}] - +[2025-02-07 13:08:45.640] [RAFT] [info] optimizing graph +[2025-02-07 13:08:45.641] [RAFT] [info] Graph optimized, creating index +[2025-02-07 13:08:45.650] [RAFT] [info] Saving CAGRA index with dataset +Feb 07, 2025 1:08:45 PM com.nvidia.cuvs.examples.CagraExample main +INFO: [{3=0.038782578, 2=0.3590463, 0=0.83774555}, {0=0.12472608, 2=0.21700792, 1=0.31918612}, {3=0.047766715, 2=0.20332818, 0=0.48305473}, {1=0.15224178, 0=0.59063464, 3=0.5986642}] +Feb 07, 2025 1:08:45 PM com.nvidia.cuvs.examples.CagraExample main +INFO: [{3=0.038782578, 2=0.3590463, 0=0.83774555}, {0=0.12472608, 2=0.21700792, 1=0.31918612}, {3=0.047766715, 2=0.20332818, 0=0.48305473}, {1=0.15224178, 0=0.59063464, 3=0.5986642}] ``` ### HNSW Example @@ -31,12 +32,13 @@ java --enable-native-access=ALL-UNNAMED -cp target/cuvs-java-examples-25.02.0.ja ``` Should output the following (with different timestamps): ``` -[2025-02-07 10:43:20.917] [RAFT] [warning] Intermediate graph degree cannot be larger than dataset size, reducing it to 4 -[2025-02-07 10:43:20.917] [RAFT] [warning] Graph degree (64) cannot be larger than intermediate graph degree (3), reducing graph_degree. +[2025-02-07 13:09:51.443] [RAFT] [warning] Intermediate graph degree cannot be larger than dataset size, reducing it to 4 +[2025-02-07 13:09:51.443] [RAFT] [warning] Graph degree (64) cannot be larger than intermediate graph degree (3), reducing graph_degree. using ivf_pq::index_params nrows 4, dim 2, n_lists 4, pq_dim 8 -[2025-02-07 10:43:21.015] [RAFT] [info] optimizing graph -[2025-02-07 10:43:21.016] [RAFT] [info] Graph optimized, creating index -[{3=0.038782578, 2=0.35904628, 0=0.8377455}, {0=0.12472608, 2=0.21700794, 1=0.31918612}, {3=0.047766715, 2=0.20332818, 0=0.48305473}, {1=0.15224178, 0=0.59063464, 3=0.59866416}] +[2025-02-07 13:09:51.524] [RAFT] [info] optimizing graph +[2025-02-07 13:09:51.525] [RAFT] [info] Graph optimized, creating index +Feb 07, 2025 1:09:51 PM com.nvidia.cuvs.examples.HnswExample main +INFO: [{3=0.038782578, 2=0.35904628, 0=0.8377455}, {0=0.12472608, 2=0.21700794, 1=0.31918612}, {3=0.047766715, 2=0.20332818, 0=0.48305473}, {1=0.15224178, 0=0.59063464, 3=0.59866416}] ``` ### Bruteforce Example @@ -44,8 +46,10 @@ Doing the following in the current directory: ``` java --enable-native-access=ALL-UNNAMED -cp target/cuvs-java-examples-25.02.0.jar:$HOME/.m2/repository/com/nvidia/cuvs/cuvs-java/25.02.0/cuvs-java-25.02.0.jar com.nvidia.cuvs.examples.BruteForceExample ``` -Should output the following: +Should output the following (with different timestamps): ``` -[{3=0.038782537, 2=0.35904616, 0=0.83774555}, {0=0.12472606, 2=0.21700788, 1=0.3191862}, {3=0.047766685, 2=0.20332813, 0=0.48305476}, {1=0.15224183, 0=0.5906347, 3=0.5986643}] -[{3=0.038782537, 2=0.35904616, 0=0.83774555}, {0=0.12472606, 2=0.21700788, 1=0.3191862}, {3=0.047766685, 2=0.20332813, 0=0.48305476}, {1=0.15224183, 0=0.5906347, 3=0.5986643}] +Feb 07, 2025 1:10:33 PM com.nvidia.cuvs.examples.BruteForceExample main +INFO: [{3=0.038782537, 2=0.35904616, 0=0.83774555}, {0=0.12472606, 2=0.21700788, 1=0.3191862}, {3=0.047766685, 2=0.20332813, 0=0.48305476}, {1=0.15224183, 0=0.5906347, 3=0.5986643}] +Feb 07, 2025 1:10:33 PM com.nvidia.cuvs.examples.BruteForceExample main +INFO: [{3=0.038782537, 2=0.35904616, 0=0.83774555}, {0=0.12472606, 2=0.21700788, 1=0.3191862}, {3=0.047766685, 2=0.20332813, 0=0.48305476}, {1=0.15224183, 0=0.5906347, 3=0.5986643}] ``` diff --git a/java/examples/pom.xml b/java/examples/pom.xml index 90b51743c1..9d726bafd0 100644 --- a/java/examples/pom.xml +++ b/java/examples/pom.xml @@ -20,17 +20,6 @@ 25.02.0 - - org.slf4j - slf4j-api - 2.0.13 - - - org.slf4j - slf4j-simple - 2.0.13 - runtime - diff --git a/java/examples/src/main/java/com/nvidia/cuvs/examples/BruteForceExample.java b/java/examples/src/main/java/com/nvidia/cuvs/examples/BruteForceExample.java index c859129418..9fc4bb2ed4 100644 --- a/java/examples/src/main/java/com/nvidia/cuvs/examples/BruteForceExample.java +++ b/java/examples/src/main/java/com/nvidia/cuvs/examples/BruteForceExample.java @@ -4,12 +4,10 @@ import java.io.FileInputStream; import java.io.FileOutputStream; import java.io.InputStream; -import java.lang.invoke.MethodHandles; import java.util.UUID; +import java.util.logging.Logger; import com.nvidia.cuvs.SearchResults; -import org.slf4j.Logger; -import org.slf4j.LoggerFactory; import com.nvidia.cuvs.BruteForceIndex; import com.nvidia.cuvs.BruteForceIndexParams; @@ -18,7 +16,7 @@ public class BruteForceExample { - private static final Logger log = LoggerFactory.getLogger(MethodHandles.lookup().lookupClass()); + private static final Logger log = Logger.getLogger(BruteForceExample.class.getName()); public static void main(String[] args) throws Throwable { diff --git a/java/examples/src/main/java/com/nvidia/cuvs/examples/CagraExample.java b/java/examples/src/main/java/com/nvidia/cuvs/examples/CagraExample.java index 9dabcc6bca..bcd3c7d245 100644 --- a/java/examples/src/main/java/com/nvidia/cuvs/examples/CagraExample.java +++ b/java/examples/src/main/java/com/nvidia/cuvs/examples/CagraExample.java @@ -4,12 +4,10 @@ import java.io.FileInputStream; import java.io.FileOutputStream; import java.io.InputStream; -import java.lang.invoke.MethodHandles; import java.util.UUID; +import java.util.logging.Logger; import com.nvidia.cuvs.SearchResults; -import org.slf4j.Logger; -import org.slf4j.LoggerFactory; import com.nvidia.cuvs.CagraIndex; import com.nvidia.cuvs.CagraIndexParams; @@ -21,7 +19,7 @@ public class CagraExample { - private static final Logger log = LoggerFactory.getLogger(MethodHandles.lookup().lookupClass()); + private static final Logger log = Logger.getLogger(CagraExample.class.getName()); public static void main(String[] args) throws Throwable { diff --git a/java/examples/src/main/java/com/nvidia/cuvs/examples/HnswExample.java b/java/examples/src/main/java/com/nvidia/cuvs/examples/HnswExample.java index 7fbbccf643..eaf0edf56b 100644 --- a/java/examples/src/main/java/com/nvidia/cuvs/examples/HnswExample.java +++ b/java/examples/src/main/java/com/nvidia/cuvs/examples/HnswExample.java @@ -4,12 +4,8 @@ import java.io.FileInputStream; import java.io.FileOutputStream; import java.io.InputStream; -import java.lang.invoke.MethodHandles; import java.util.UUID; - -import com.nvidia.cuvs.SearchResults; -import org.slf4j.Logger; -import org.slf4j.LoggerFactory; +import java.util.logging.Logger; import com.nvidia.cuvs.CagraIndex; import com.nvidia.cuvs.CagraIndexParams; @@ -20,10 +16,12 @@ import com.nvidia.cuvs.HnswIndexParams; import com.nvidia.cuvs.HnswQuery; import com.nvidia.cuvs.HnswSearchParams; +import com.nvidia.cuvs.SearchResults; + public class HnswExample { - private static final Logger log = LoggerFactory.getLogger(MethodHandles.lookup().lookupClass()); + private static final Logger log = Logger.getLogger(HnswExample.class.getName()); public static void main(String[] args) throws Throwable { diff --git a/java/examples/src/main/resources/.gitkeep b/java/examples/src/main/resources/.gitkeep new file mode 100644 index 0000000000..e69de29bb2 diff --git a/java/examples/src/main/resources/log4j2.xml b/java/examples/src/main/resources/log4j2.xml deleted file mode 100644 index bf0eb598c1..0000000000 --- a/java/examples/src/main/resources/log4j2.xml +++ /dev/null @@ -1,14 +0,0 @@ - - - - - - - - - - - - - - From aade5eef904b8d2ce74585d92b27a3d587d92160 Mon Sep 17 00:00:00 2001 From: Vivek Narang <123010842+narangvivek10@users.noreply.github.com> Date: Fri, 7 Feb 2025 13:54:18 -0500 Subject: [PATCH 4/6] Update java/README.md Co-authored-by: Corey J. Nolet --- java/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/java/README.md b/java/README.md index 5e92f59876..3d33c86888 100644 --- a/java/README.md +++ b/java/README.md @@ -1,6 +1,6 @@ # CuVS Java API -CuVS Java API attempts to provide a Java based simple, efficient, and a robust vector search API. +CuVS Java API provides a Java based simple, efficient, and a robust vector search API. > [!CAUTION] > This is an experimental release and updates to this API should be expected in the coming days. From bbf78c8209461fbe5e3f11fd3d47f29e12b37399 Mon Sep 17 00:00:00 2001 From: Vivek Narang <123010842+narangvivek10@users.noreply.github.com> Date: Fri, 7 Feb 2025 13:55:09 -0500 Subject: [PATCH 5/6] Update java/README.md Co-authored-by: Corey J. Nolet --- java/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/java/README.md b/java/README.md index 3d33c86888..9e814aaee4 100644 --- a/java/README.md +++ b/java/README.md @@ -3,7 +3,7 @@ CuVS Java API provides a Java based simple, efficient, and a robust vector search API. > [!CAUTION] -> This is an experimental release and updates to this API should be expected in the coming days. +> cuVS 25.02 contains an experimental version and updates to this API are expected in the coming release. ## Prerequisites From 32cc434c98da49b657695aa60189b66f30d2002b Mon Sep 17 00:00:00 2001 From: Vivek Narang <123010842+narangvivek10@users.noreply.github.com> Date: Fri, 7 Feb 2025 14:01:29 -0500 Subject: [PATCH 6/6] Update java/README.md Co-authored-by: Corey J. Nolet --- java/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/java/README.md b/java/README.md index 9e814aaee4..3df2600459 100644 --- a/java/README.md +++ b/java/README.md @@ -28,7 +28,7 @@ do `./build.sh java` in the top level directory or just do `./build.sh` in this ## Examples -For easy understanding we have provided starter examples for CAGRA, HNSW, and Bruteforce and these can be found in the `examples` directory. +A few starter examples of CAGRA, HNSW, and Bruteforce index are provided in the `examples` directory. ## Javadocs