Adjust GPU graph building params (#137074)

cuvs 2025.12
https://github.com/rapidsai/cuvs/pull/1448/files
 will provide an API for converting HNSW CPU Params to Cagra params.

 But for current ES that uses 2025.10 version, we need to adjust params
 ourselves. This PR adjust params based on the code from the cuvs library.

Author: mayya-sharipova

docs/changelog/137074.yaml

@@ -0,0 +1,5 @@
+pr: 137074
+summary: Adjust GPU graph building params
+area: Search
+type: enhancement
+issues: []

x-pack/plugin/gpu/src/main/java/org/elasticsearch/xpack/gpu/GPUPlugin.java

@@ -7,7 +7,6 @@
 package org.elasticsearch.xpack.gpu;
 
 import org.apache.lucene.codecs.KnnVectorsFormat;
-import org.apache.lucene.util.hnsw.HnswGraphBuilder;
 import org.elasticsearch.common.settings.Setting;
 import org.elasticsearch.common.util.FeatureFlag;
 import org.elasticsearch.index.mapper.vectors.DenseVectorFieldMapper;
@@ -94,13 +93,14 @@ private static KnnVectorsFormat getVectorsFormat(
         DenseVectorFieldMapper.DenseVectorIndexOptions indexOptions,
         DenseVectorFieldMapper.VectorSimilarity similarity
     ) {
+        // TODO: cuvs 2025.12 will provide an API for converting HNSW CPU Params to Cagra params; use that instead
         if (indexOptions.getType() == DenseVectorFieldMapper.VectorIndexType.HNSW) {
             DenseVectorFieldMapper.HnswIndexOptions hnswIndexOptions = (DenseVectorFieldMapper.HnswIndexOptions) indexOptions;
             int efConstruction = hnswIndexOptions.efConstruction();
-            if (efConstruction == HnswGraphBuilder.DEFAULT_BEAM_WIDTH) {
-                efConstruction = ES92GpuHnswVectorsFormat.DEFAULT_BEAM_WIDTH; // default value for GPU graph construction is 128
-            }
-            return new ES92GpuHnswVectorsFormat(hnswIndexOptions.m(), efConstruction);
+            int m = hnswIndexOptions.m();
+            int gpuM = 2 + m * 2 / 3;
+            int gpuEfConstruction = m + m * efConstruction / 256;
+            return new ES92GpuHnswVectorsFormat(gpuM, gpuEfConstruction);
         } else if (indexOptions.getType() == DenseVectorFieldMapper.VectorIndexType.INT8_HNSW) {
             if (similarity == DenseVectorFieldMapper.VectorSimilarity.MAX_INNER_PRODUCT) {
                 throw new IllegalArgumentException(
@@ -115,16 +115,10 @@ private static KnnVectorsFormat getVectorsFormat(
             }
             DenseVectorFieldMapper.Int8HnswIndexOptions int8HnswIndexOptions = (DenseVectorFieldMapper.Int8HnswIndexOptions) indexOptions;
             int efConstruction = int8HnswIndexOptions.efConstruction();
-            if (efConstruction == HnswGraphBuilder.DEFAULT_BEAM_WIDTH) {
-                efConstruction = ES92GpuHnswVectorsFormat.DEFAULT_BEAM_WIDTH; // default value for GPU graph construction is 128
-            }
-            return new ES92GpuHnswSQVectorsFormat(
-                int8HnswIndexOptions.m(),
-                efConstruction,
-                int8HnswIndexOptions.confidenceInterval(),
-                7,
-                false
-            );
+            int m = int8HnswIndexOptions.m();
+            int gpuM = 2 + m * 2 / 3;
+            int gpuEfConstruction = m + m * efConstruction / 256;
+            return new ES92GpuHnswSQVectorsFormat(gpuM, gpuEfConstruction, int8HnswIndexOptions.confidenceInterval(), 7, false);
         } else {
             throw new IllegalArgumentException(
                 "GPU vector indexing is not supported on this vector type: [" + indexOptions.getType() + "]"

x-pack/plugin/gpu/src/main/java/org/elasticsearch/xpack/gpu/codec/ES92GpuHnswVectorsFormat.java

@@ -13,6 +13,7 @@
 import org.apache.lucene.codecs.hnsw.FlatVectorScorerUtil;
 import org.apache.lucene.codecs.hnsw.FlatVectorsFormat;
 import org.apache.lucene.codecs.lucene99.Lucene99FlatVectorsFormat;
+import org.apache.lucene.codecs.lucene99.Lucene99HnswVectorsFormat;
 import org.apache.lucene.codecs.lucene99.Lucene99HnswVectorsReader;
 import org.apache.lucene.index.SegmentReadState;
 import org.apache.lucene.index.SegmentWriteState;
@@ -36,8 +37,9 @@ public class ES92GpuHnswVectorsFormat extends KnnVectorsFormat {
     static final String LUCENE99_HNSW_VECTOR_INDEX_EXTENSION = "vex";
     static final int LUCENE99_VERSION_CURRENT = VERSION_GROUPVARINT;
 
-    static final int DEFAULT_MAX_CONN = 16; // graph degree
-    public static final int DEFAULT_BEAM_WIDTH = 128; // intermediate graph degree
+    public static final int DEFAULT_MAX_CONN = (2 + Lucene99HnswVectorsFormat.DEFAULT_MAX_CONN * 2 / 3); // graph degree
+    public static final int DEFAULT_BEAM_WIDTH = Lucene99HnswVectorsFormat.DEFAULT_MAX_CONN + Lucene99HnswVectorsFormat.DEFAULT_MAX_CONN
+        * Lucene99HnswVectorsFormat.DEFAULT_BEAM_WIDTH / 256; // intermediate graph degree
     static final int MIN_NUM_VECTORS_FOR_GPU_BUILD = 2;
 
     private static final FlatVectorsFormat flatVectorsFormat = new Lucene99FlatVectorsFormat(

x-pack/plugin/gpu/src/main/java/org/elasticsearch/xpack/gpu/codec/ES92GpuHnswVectorsWriter.java

@@ -332,6 +332,7 @@ private CagraIndex buildGPUIndex(
             .withCagraGraphBuildAlgo(CagraIndexParams.CagraGraphBuildAlgo.NN_DESCENT)
             .withGraphDegree(M)
             .withIntermediateGraphDegree(beamWidth)
+            .withNNDescentNumIterations(5)
             .withMetric(distanceType)
             .build();
 

x-pack/plugin/gpu/src/test/java/org/elasticsearch/xpack/gpu/codec/GPUDenseVectorFieldMapperTests.java

@@ -44,7 +44,7 @@ public void testKnnVectorsFormat() throws IOException {
         // TODO improve test with custom parameters
         KnnVectorsFormat knnVectorsFormat = getKnnVectorsFormat("hnsw");
         String expectedStr = "Lucene99HnswVectorsFormat(name=Lucene99HnswVectorsFormat, "
-            + "maxConn=16, beamWidth=128, flatVectorFormat=Lucene99FlatVectorsFormat)";
+            + "maxConn=12, beamWidth=22, flatVectorFormat=Lucene99FlatVectorsFormat)";
         assertEquals(expectedStr, knnVectorsFormat.toString());
     }
 
@@ -53,7 +53,7 @@ public void testKnnQuantizedHNSWVectorsFormat() throws IOException {
         // TOD improve the test with custom parameters
         KnnVectorsFormat knnVectorsFormat = getKnnVectorsFormat("int8_hnsw");
         String expectedStr = "Lucene99HnswVectorsFormat(name=Lucene99HnswVectorsFormat, "
-            + "maxConn=16, beamWidth=128, flatVectorFormat=ES814ScalarQuantizedVectorsFormat";
+            + "maxConn=12, beamWidth=22, flatVectorFormat=ES814ScalarQuantizedVectorsFormat";
         assertTrue(knnVectorsFormat.toString().startsWith(expectedStr));
     }