diff --git a/java/README.md b/java/README.md index e5676146a2..3df2600459 100644 --- a/java/README.md +++ b/java/README.md @@ -1,14 +1,42 @@ -Prerequisites -------------- +# CuVS Java API -* JDK 22 -* Maven 3.9.6 or later +CuVS Java API provides 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] +> cuVS 25.02 contains an experimental version and updates to this API are expected in the coming release. -Alternatively, please build libcuvs (`./build.sh libcuvs` from top level directory) before building the Java API with `./build.sh` from this directory. -Building --------- +## Prerequisites -`./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. +- 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/) + + +## 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 + +A few starter examples of CAGRA, HNSW, and Bruteforce index are provided 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` diff --git a/java/examples/README.md b/java/examples/README.md index d05d7b9117..13d7471723 100644 --- a/java/examples/README.md +++ b/java/examples/README.md @@ -1,8 +1,55 @@ -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 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 +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 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 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 +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 (with different timestamps): +``` +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 @@ - - - - - - - - - - - - - -