add tuning guide for cagra, modify build param

rapidsai · Aug 25, 2023 · 617c60f · 617c60f
1 parent 0cf1c6f
commit 617c60f
Show file tree

Hide file tree

Showing 14 changed files with 37 additions and 28 deletions.
diff --git a/bench/ann/conf/bigann-100M.json b/bench/ann/conf/bigann-100M.json
@@ -172,7 +172,7 @@
       "name": "raft_cagra.dim32",
       "algo": "raft_cagra",
       "dataset_memtype": "host",
-      "build_param": {"index_dim": 32},
+      "build_param": {"graph_degree": 32},
       "file": "bigann-100M/raft_cagra/dim32",
       "search_params": [
         {"itopk": 32},
@@ -184,7 +184,7 @@
       "name": "raft_cagra.dim64",
       "algo": "raft_cagra",
       "dataset_memtype":"host",
-      "build_param": {"index_dim": 64},
+      "build_param": {"graph_degree": 64},
       "file": "bigann-100M/raft_cagra/dim64",
       "search_params": [
         {"itopk": 32},

diff --git a/bench/ann/conf/deep-100M.json b/bench/ann/conf/deep-100M.json
@@ -220,7 +220,7 @@
       "name": "raft_cagra.dim32",
       "algo": "raft_cagra",
       "dataset_memtype":"host",
-      "build_param": {"index_dim": 32, "intermediate_graph_degree": 48},
+      "build_param": {"graph_degree": 32, "intermediate_graph_degree": 48},
       "file": "deep-100M/raft_cagra/dim32",
       "search_params": [
         {"itopk": 32, "search_width": 1, "max_iterations": 0, "algo": "single_cta"},
@@ -241,7 +241,7 @@
       "name": "raft_cagra.dim32.multi_cta",
       "algo": "raft_cagra",
       "dataset_memtype":"host",
-      "build_param": {"index_dim": 32, "intermediate_graph_degree": 48},
+      "build_param": {"graph_degree": 32, "intermediate_graph_degree": 48},
       "file": "deep-100M/raft_cagra/dim32",
       "search_params": [
         {"itopk": 32, "search_width": 1, "max_iterations": 0, "algo": "multi_cta"},
@@ -262,7 +262,7 @@
       "name": "raft_cagra.dim32.multi_kernel",
       "algo": "raft_cagra",
       "dataset_memtype":"host",
-      "build_param": {"index_dim": 32, "intermediate_graph_degree": 48},
+      "build_param": {"graph_degree": 32, "intermediate_graph_degree": 48},
       "file": "deep-100M/raft_cagra/dim32",
       "search_params": [
         {"itopk": 32, "search_width": 1, "max_iterations": 0, "algo": "multi_kernel"},
@@ -283,7 +283,7 @@
       "name": "raft_cagra.dim64",
       "algo": "raft_cagra",
       "dataset_memtype":"host",
-      "build_param": {"index_dim": 64},
+      "build_param": {"graph_degree": 64},
       "file": "deep-100M/raft_cagra/dim64",
       "search_params": [
         {"itopk": 32, "search_width": 1, "max_iterations": 0},

diff --git a/bench/ann/conf/deep-image-96-angular.json b/bench/ann/conf/deep-image-96-angular.json
@@ -992,7 +992,7 @@
       "algo" : "raft_cagra",
       "dataset_memtype": "device",
       "build_param": {
-        "index_dim" : 32
+        "graph_degree" : 32
       },
       "file" : "index/deep-image-96-angular/raft_cagra/dim32",
       "search_params" : [
@@ -1008,7 +1008,7 @@
       "algo" : "raft_cagra",
       "dataset_memtype": "device",
       "build_param": {
-        "index_dim" : 64
+        "graph_degree" : 64
       },
       "file" : "index/deep-image-96-angular/raft_cagra/dim64",
       "search_params" : [

diff --git a/bench/ann/conf/fashion-mnist-784-euclidean.json b/bench/ann/conf/fashion-mnist-784-euclidean.json
@@ -1336,7 +1336,7 @@
       "algo" : "raft_cagra",
       "dataset_memtype": "device",
       "build_param": {
-        "index_dim" : 32
+        "graph_degree" : 32
       },
       "file" : "index/fashion-mnist-784-euclidean/raft_cagra/dim32",
       "search_params" : [
@@ -1352,7 +1352,7 @@
       "algo" : "raft_cagra",
       "dataset_memtype": "device",
       "build_param": {
-        "index_dim" : 64
+        "graph_degree" : 64
       },
       "file" : "index/fashion-mnist-784-euclidean/raft_cagra/dim64",
       "search_params" : [

diff --git a/bench/ann/conf/gist-960-euclidean.json b/bench/ann/conf/gist-960-euclidean.json
@@ -1322,7 +1322,7 @@
       "name" : "raft_cagra.dim32",
       "algo" : "raft_cagra",
       "build_param": {
-        "index_dim" : 32
+        "graph_degree" : 32
       },
       "file" : "index/gist-960-euclidean/raft_cagra/dim32",
       "search_params" : [
@@ -1337,7 +1337,7 @@
       "name" : "raft_cagra.dim64",
       "algo" : "raft_cagra",
       "build_param": {
-        "index_dim" : 64
+        "graph_degree" : 64
       },
       "file" : "index/gist-960-euclidean/raft_cagra/dim64",
       "search_params" : [

diff --git a/bench/ann/conf/glove-100-angular.json b/bench/ann/conf/glove-100-angular.json
@@ -1322,7 +1322,7 @@
       "name" : "raft_cagra.dim32",
       "algo" : "raft_cagra",
       "build_param": {
-        "index_dim" : 32
+        "graph_degree" : 32
       },
       "file" : "index/glove-100-angular/raft_cagra/dim32",
       "search_params" : [
@@ -1337,7 +1337,7 @@
       "name" : "raft_cagra.dim64",
       "algo" : "raft_cagra",
       "build_param": {
-        "index_dim" : 64
+        "graph_degree" : 64
       },
       "file" : "index/glove-100-angular/raft_cagra/dim64",
       "search_params" : [

diff --git a/bench/ann/conf/glove-50-angular.json b/bench/ann/conf/glove-50-angular.json
@@ -1322,7 +1322,7 @@
       "name" : "raft_cagra.dim32",
       "algo" : "raft_cagra",
       "build_param": {
-        "index_dim" : 32
+        "graph_degree" : 32
       },
       "file" : "index/glove-50-angular/raft_cagra/dim32",
       "search_params" : [
@@ -1337,7 +1337,7 @@
       "name" : "raft_cagra.dim64",
       "algo" : "raft_cagra",
       "build_param": {
-        "index_dim" : 64
+        "graph_degree" : 64
       },
       "file" : "index/glove-50-angular/raft_cagra/dim64",
       "search_params" : [

diff --git a/bench/ann/conf/lastfm-65-angular.json b/bench/ann/conf/lastfm-65-angular.json
@@ -1322,7 +1322,7 @@
       "name" : "raft_cagra.dim32",
       "algo" : "raft_cagra",
       "build_param": {
-        "index_dim" : 32
+        "graph_degree" : 32
       },
       "file" : "index/lastfm-65-angular/raft_cagra/dim32",
       "search_params" : [
@@ -1337,7 +1337,7 @@
       "name" : "raft_cagra.dim64",
       "algo" : "raft_cagra",
       "build_param": {
-        "index_dim" : 64
+        "graph_degree" : 64
       },
       "file" : "index/lastfm-65-angular/raft_cagra/dim64",
       "search_params" : [

diff --git a/bench/ann/conf/mnist-784-euclidean.json b/bench/ann/conf/mnist-784-euclidean.json
@@ -1322,7 +1322,7 @@
       "name" : "raft_cagra.dim32",
       "algo" : "raft_cagra",
       "build_param": {
-        "index_dim" : 32
+        "graph_degree" : 32
       },
       "file" : "index/mnist-784-euclidean/raft_cagra/dim32",
       "search_params" : [
@@ -1337,7 +1337,7 @@
       "name" : "raft_cagra.dim64",
       "algo" : "raft_cagra",
       "build_param": {
-        "index_dim" : 64
+        "graph_degree" : 64
       },
       "file" : "index/mnist-784-euclidean/raft_cagra/dim64",
       "search_params" : [

diff --git a/bench/ann/conf/nytimes-256-angular.json b/bench/ann/conf/nytimes-256-angular.json
@@ -1322,7 +1322,7 @@
       "name" : "raft_cagra.dim32",
       "algo" : "raft_cagra",
       "build_param": {
-        "index_dim" : 32
+        "graph_degree" : 32
       },
       "file" : "index/nytimes-256-angular/raft_cagra/dim32",
       "search_params" : [
@@ -1337,7 +1337,7 @@
       "name" : "raft_cagra.dim64",
       "algo" : "raft_cagra",
       "build_param": {
-        "index_dim" : 64
+        "graph_degree" : 64
       },
       "file" : "index/nytimes-256-angular/raft_cagra/dim64",
       "search_params" : [

diff --git a/bench/ann/conf/sift-128-euclidean.json b/bench/ann/conf/sift-128-euclidean.json
@@ -475,7 +475,7 @@
     {
       "name": "raft_cagra.dim32",
       "algo": "raft_cagra",
-      "build_param": {"index_dim": 32},
+      "build_param": {"graph_degree": 32},
       "file": "sift-128-euclidean/raft_cagra/dim32",
       "search_params": [
         {"itopk": 32},
@@ -486,7 +486,7 @@
     {
       "name": "raft_cagra.dim64",
       "algo": "raft_cagra",
-      "build_param": {"index_dim": 64},
+      "build_param": {"graph_degree": 64},
       "file": "sift-128-euclidean/raft_cagra/dim64",
       "search_params": [
         {"itopk": 32},

diff --git a/cpp/bench/ann/src/raft/raft_benchmark.cu b/cpp/bench/ann/src/raft/raft_benchmark.cu
@@ -132,8 +132,8 @@ template <typename T, typename IdxT>
 void parse_build_param(const nlohmann::json& conf,
                        typename raft::bench::ann::RaftCagra<T, IdxT>::BuildParam& param)
 {
-  if (conf.contains("index_dim")) {
-    param.graph_degree              = conf.at("index_dim");
+  if (conf.contains("graph_degree")) {
+    param.graph_degree              = conf.at("graph_degree");
     param.intermediate_graph_degree = param.graph_degree * 2;
   }
   if (conf.contains("intermediate_graph_degree")) {

diff --git a/docs/source/ann_benchmarks_param_tuning.md b/docs/source/ann_benchmarks_param_tuning.md
@@ -36,6 +36,16 @@ IVF-pq is an inverted-file index, which partitions the vectors into a series of
 
 
 ### `raft_cagra`
+CAGRA uses a graph-based index, which creates an intermediate, approximate kNN graph using IVF-PQ and then further refining and optimizing to create a final kNN graph. This kNN graph is used by CAGRA as an index for search.
+
+| Parameter | Type           | Required | Data Type           | Default | Description                                                                                                                                                                       |
+|-----------|----------------|----------|---------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `graph_degree`  | `build_param`  | N        | Positive Integer >0 | 64 | Degree of the final kNN graph index. |
+| `intermediate_graph_degree`  | `build_param`  | N        | Positive Integer >0 | 128 | Degree of the intermediate kNN graph. |
+| `itopk`  | `search_wdith`  | N        | Positive Integer >0 | 64 | Number of intermediate search results retained during the search. Higher values improve search accuracy at the cost of speed. |
+| `search_width`  | `search_param`  | N        | Positive Integer >0 | 1 | Number of graph nodes to select as the starting point for the search in each iteration. |
+| `max_iterations`  | `search_param`  | N        | Integer >=0 | 0 | Upper limit of search iterations. Auto select when 0. |
+| `algo`  | `search_param`  | N        | string | "auto" | Algorithm to use for search. Possible values: {"auto", "single_cta", "multi_cta", "multi_kernel"} |
 
 
 ## FAISS Indexes

diff --git a/docs/source/raft_ann_benchmarks.md b/docs/source/raft_ann_benchmarks.md
@@ -118,11 +118,10 @@ options:
   --dataset-path DATASET_PATH
                         path to download dataset (default: ${RAFT_HOME}/bench/ann/data)
   --normalize           normalize cosine distance to inner product (default: False)
-
+```
 When option `normalize` is provided to the script, any dataset that has cosine distances
 will be normalized to inner product. So, for example, the dataset `glove-100-angular` 
 will be written at location `${RAFT_HOME}/bench/ann/data/glove-100-inner/`.
-```
 
 #### Step 2: Build and Search Index
 The script `bench/ann/run.py` will build and search indices for a given dataset and its