Integrate hnsw_with_vectors

xzfc · xzfc · commit 394f2345fc6d · 2025-09-18T15:13:09.000Z
diff --git a/docs/grpc/docs.md b/docs/grpc/docs.md
@@ -978,6 +978,7 @@
 | max_indexing_threads | [uint64](#uint64) | optional | Number of parallel threads used for background index building. If 0 - automatically select from 8 to 16. Best to keep between 8 and 16 to prevent likelihood of building broken/inefficient HNSW graphs. On small CPUs, less threads are used. |
 | on_disk | [bool](#bool) | optional | Store HNSW index on disk. If set to false, the index will be stored in RAM. |
 | payload_m | [uint64](#uint64) | optional | Number of additional payload-aware links per node in the index graph. If not set - regular M parameter will be used. |
+| copy_vectors | [bool](#bool) | optional | Store copies of original and quantized vectors within the HNSW index file. Default: false. Enabling this option will trade the search speed for disk usage by reducing amount of random seeks during the search. Requires quantized vectors to be enabled. Multi-vectors are not supported. |
 
 
 
diff --git a/docs/redoc/master/openapi.json b/docs/redoc/master/openapi.json
@@ -6929,6 +6929,11 @@
             "format": "uint",
             "minimum": 0,
             "nullable": true
+          },
+          "copy_vectors": {
+            "description": "Store copies of original and quantized vectors within the HNSW index file. Default: false. Enabling this option will trade the search speed for disk usage by reducing amount of random seeks during the search. Requires quantized vectors to be enabled. Multi-vectors are not supported.",
+            "type": "boolean",
+            "nullable": true
           }
         }
       },
@@ -7222,6 +7227,11 @@
             "format": "uint",
             "minimum": 0,
             "nullable": true
+          },
+          "copy_vectors": {
+            "description": "Store copies of original and quantized vectors within the HNSW index file. Default: false. Enabling this option will trade the search speed for disk usage by reducing amount of random seeks during the search. Requires quantized vectors to be enabled. Multi-vectors are not supported.",
+            "type": "boolean",
+            "nullable": true
           }
         }
       },
diff --git a/lib/api/src/grpc/conversions.rs b/lib/api/src/grpc/conversions.rs
@@ -2126,6 +2126,7 @@ impl From<HnswConfigDiff> for segment::types::HnswConfig {
             max_indexing_threads,
             on_disk,
             payload_m,
+            copy_vectors,
         } = hnsw_config;
         Self {
             m: m.unwrap_or_default() as usize,
@@ -2134,6 +2135,7 @@ impl From<HnswConfigDiff> for segment::types::HnswConfig {
             max_indexing_threads: max_indexing_threads.unwrap_or_default() as usize,
             on_disk,
             payload_m: payload_m.map(|x| x as usize),
+            copy_vectors,
         }
     }
 }
diff --git a/lib/api/src/grpc/proto/collections.proto b/lib/api/src/grpc/proto/collections.proto
@@ -195,6 +195,13 @@ message HnswConfigDiff {
      Number of additional payload-aware links per node in the index graph. If not set - regular M parameter will be used.
   */
   optional uint64 payload_m = 6;
+  /*
+     Store copies of original and quantized vectors within the HNSW index file. Default: false.
+     Enabling this option will trade the search speed for disk usage by reducing amount of
+     random seeks during the search.
+     Requires quantized vectors to be enabled. Multi-vectors are not supported.
+  */
+  optional bool copy_vectors = 7;
 }
 
 message SparseIndexConfig {
diff --git a/lib/api/src/grpc/qdrant.rs b/lib/api/src/grpc/qdrant.rs
@@ -407,6 +407,12 @@ pub struct HnswConfigDiff {
     /// Number of additional payload-aware links per node in the index graph. If not set - regular M parameter will be used.
     #[prost(uint64, optional, tag = "6")]
     pub payload_m: ::core::option::Option<u64>,
+    /// Store copies of original and quantized vectors within the HNSW index file. Default: false.
+    /// Enabling this option will trade the search speed for disk usage by reducing amount of
+    /// random seeks during the search.
+    /// Requires quantized vectors to be enabled. Multi-vectors are not supported.
+    #[prost(bool, optional, tag = "7")]
+    pub copy_vectors: ::core::option::Option<bool>,
 }
 #[derive(serde::Serialize)]
 #[allow(clippy::derive_partial_eq_without_eq)]
diff --git a/lib/collection/src/collection_manager/optimizers/config_mismatch_optimizer.rs b/lib/collection/src/collection_manager/optimizers/config_mismatch_optimizer.rs
@@ -348,6 +348,7 @@ mod tests {
             max_indexing_threads: 0,
             on_disk: None,
             payload_m: None,
+            copy_vectors: None,
         };
 
         // Optimizers used in test
@@ -508,6 +509,7 @@ mod tests {
             max_indexing_threads: 0,
             on_disk: None,
             payload_m: None,
+            copy_vectors: None,
         };
 
         let permit_cpu_count = num_rayon_threads(hnsw_config_collection.max_indexing_threads);
diff --git a/lib/collection/src/collection_manager/optimizers/indexing_optimizer.rs b/lib/collection/src/collection_manager/optimizers/indexing_optimizer.rs
@@ -877,6 +877,7 @@ mod tests {
             max_indexing_threads: 0,
             on_disk: None,
             payload_m: None,
+            copy_vectors: None,
         };
 
         {
diff --git a/lib/collection/src/collection_manager/optimizers/vacuum_optimizer.rs b/lib/collection/src/collection_manager/optimizers/vacuum_optimizer.rs
@@ -468,6 +468,7 @@ mod tests {
             max_indexing_threads: 0,
             on_disk: None,
             payload_m: None,
+            copy_vectors: None,
         };
 
         let permit_cpu_count = num_rayon_threads(hnsw_config.max_indexing_threads);
diff --git a/lib/collection/src/operations/config_diff.rs b/lib/collection/src/operations/config_diff.rs
@@ -90,6 +90,12 @@ pub struct HnswConfigDiff {
     /// Custom M param for additional payload-aware HNSW links. If not set, default M will be used.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub payload_m: Option<usize>,
+    /// Store copies of original and quantized vectors within the HNSW index file. Default: false.
+    /// Enabling this option will trade the search speed for disk usage by reducing amount of
+    /// random seeks during the search.
+    /// Requires quantized vectors to be enabled. Multi-vectors are not supported.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub copy_vectors: Option<bool>,
 }
 
 #[derive(
diff --git a/lib/collection/src/operations/conversions.rs b/lib/collection/src/operations/conversions.rs
@@ -240,6 +240,7 @@ impl From<api::grpc::qdrant::HnswConfigDiff> for HnswConfigDiff {
             max_indexing_threads,
             on_disk,
             payload_m,
+            copy_vectors,
         } = value;
         Self {
             m: m.map(|v| v as usize),
@@ -248,6 +249,7 @@ impl From<api::grpc::qdrant::HnswConfigDiff> for HnswConfigDiff {
             max_indexing_threads: max_indexing_threads.map(|v| v as usize),
             on_disk,
             payload_m: payload_m.map(|v| v as usize),
+            copy_vectors,
         }
     }
 }
@@ -261,6 +263,7 @@ impl From<HnswConfigDiff> for api::grpc::qdrant::HnswConfigDiff {
             max_indexing_threads,
             on_disk,
             payload_m,
+            copy_vectors,
         } = value;
         Self {
             m: m.map(|v| v as u64),
@@ -269,6 +272,7 @@ impl From<HnswConfigDiff> for api::grpc::qdrant::HnswConfigDiff {
             max_indexing_threads: max_indexing_threads.map(|v| v as u64),
             on_disk,
             payload_m: payload_m.map(|v| v as u64),
+            copy_vectors,
         }
     }
 }
@@ -412,6 +416,7 @@ impl From<CollectionInfo> for api::grpc::qdrant::CollectionInfo {
             max_indexing_threads,
             on_disk,
             payload_m,
+            copy_vectors,
         } = hnsw_config;
 
         let CollectionParams {
@@ -493,6 +498,7 @@ impl From<CollectionInfo> for api::grpc::qdrant::CollectionInfo {
                     max_indexing_threads: Some(max_indexing_threads as u64),
                     on_disk,
                     payload_m: payload_m.map(|v| v as u64),
+                    copy_vectors,
                 }),
                 optimizer_config: Some(api::grpc::qdrant::OptimizersConfigDiff {
                     deleted_threshold: Some(deleted_threshold),
diff --git a/lib/segment/benches/hnsw_incremental_build.rs b/lib/segment/benches/hnsw_incremental_build.rs
@@ -363,6 +363,7 @@ fn build_hnsw_index<R: Rng + ?Sized>(
         max_indexing_threads: 0,
         on_disk: Some(false),
         payload_m: None,
+        copy_vectors: None,
     };
 
     let open_args = HnswIndexOpenArgs {
diff --git a/lib/segment/benches/multi_vector_search.rs b/lib/segment/benches/multi_vector_search.rs
@@ -108,6 +108,7 @@ fn make_segment_index<R: Rng + ?Sized>(rng: &mut R, distance: Distance) -> HNSWI
         max_indexing_threads: 0,
         on_disk: None,
         payload_m: None,
+        copy_vectors: None,
     };
     let permit_cpu_count = num_rayon_threads(hnsw_config.max_indexing_threads);
     let permit = Arc::new(ResourcePermit::dummy(permit_cpu_count as u32));
diff --git a/lib/segment/src/compat.rs b/lib/segment/src/compat.rs
@@ -156,6 +156,7 @@ mod tests {
                             max_indexing_threads: 0,
                             on_disk: None,
                             payload_m: Some(10),
+                            copy_vectors: None,
                         }),
                         quantization_config: None,
                         on_disk: None,
@@ -187,6 +188,7 @@ mod tests {
                 max_indexing_threads: 0,
                 on_disk: None,
                 payload_m: None,
+                copy_vectors: None,
             }),
             storage_type: StorageTypeV5::InMemory,
             payload_storage_type: PayloadStorageType::default(),
@@ -262,6 +264,7 @@ mod tests {
                 max_indexing_threads: 0,
                 on_disk: None,
                 payload_m: None,
+                copy_vectors: None,
             }),
             storage_type: StorageTypeV5::InMemory,
             payload_storage_type: PayloadStorageType::default(),
diff --git a/lib/segment/src/index/hnsw_index/graph_layers.rs b/lib/segment/src/index/hnsw_index/graph_layers.rs
@@ -706,14 +706,15 @@ mod tests {
             M,
             dim,
             false,
-            initial_format.is_with_vectors(),
+            true,
             distance,
             &mut rng,
         );
+        let graph_links_vectors = vector_holder.graph_links_vectors();
         let graph1 = graph_layers_builder
             .into_graph_layers(
                 dir.path(),
-                initial_format.with_param_for_tests(vector_holder.graph_links_vectors().as_ref()),
+                initial_format.with_param_for_tests(graph_links_vectors.as_ref()),
                 true,
             )
             .unwrap();
diff --git a/lib/segment/src/index/hnsw_index/graph_links.rs b/lib/segment/src/index/hnsw_index/graph_links.rs
@@ -184,7 +184,7 @@ impl GraphLinksFormat {
     }
 }
 
-impl GraphLinksFormatParam<'_> {
+impl<'a> GraphLinksFormatParam<'a> {
     pub fn as_format(&self) -> GraphLinksFormat {
         match self {
             GraphLinksFormatParam::Plain => GraphLinksFormat::Plain,
diff --git a/lib/segment/src/index/hnsw_index/hnsw.rs b/lib/segment/src/index/hnsw_index/hnsw.rs
@@ -28,7 +28,6 @@ use super::gpu::gpu_devices_manager::LockedGpuDevice;
 use super::gpu::gpu_insert_context::GpuInsertContext;
 #[cfg(feature = "gpu")]
 use super::gpu::gpu_vector_storage::GpuVectorStorage;
-use super::graph_links::GraphLinksFormat;
 use crate::common::BYTES_IN_KB;
 use crate::common::operation_error::{OperationError, OperationResult, check_process_stopped};
 use crate::common::operation_time_statistics::{
@@ -47,7 +46,7 @@ use crate::index::hnsw_index::gpu::{get_gpu_groups_count, gpu_graph_builder::bui
 use crate::index::hnsw_index::graph_layers::{GraphLayers, GraphLayersWithVectors};
 use crate::index::hnsw_index::graph_layers_builder::GraphLayersBuilder;
 use crate::index::hnsw_index::graph_layers_healer::GraphLayersHealer;
-use crate::index::hnsw_index::graph_links::StorageGraphLinksVectors;
+use crate::index::hnsw_index::graph_links::{GraphLinksFormatParam, StorageGraphLinksVectors};
 use crate::index::hnsw_index::point_scorer::FilteredScorer;
 use crate::index::query_estimator::adjust_to_available_vectors;
 use crate::index::sample_estimation::sample_check_cardinality;
@@ -78,7 +77,6 @@ pub const SINGLE_THREADED_HNSW_BUILD_THRESHOLD: usize = 32;
 #[cfg(not(debug_assertions))]
 pub const SINGLE_THREADED_HNSW_BUILD_THRESHOLD: usize = 256;
 
-const LINK_COMPRESSION_FORMAT: GraphLinksFormat = GraphLinksFormat::Compressed;
 const LINK_COMPRESSION_CONVERT_EXISTING: bool = false;
 
 #[derive(Debug)]
@@ -614,9 +612,21 @@ impl HNSWIndex {
         // as it will be discarded anyway
         let is_on_disk = true;
 
-        let graph_links_vectors =
-            StorageGraphLinksVectors::try_new(&vector_storage_ref, quantized_vectors_ref.as_ref());
-        let format_param = LINK_COMPRESSION_FORMAT.with_param(graph_links_vectors.as_ref());
+        let graph_links_vectors = hnsw_config
+            .copy_vectors
+            .unwrap_or_default()
+            .then(|| {
+                // NOTE: the configuration is silently ignored if try_new fails.
+                StorageGraphLinksVectors::try_new(
+                    &vector_storage_ref,
+                    quantized_vectors_ref.as_ref(),
+                )
+            })
+            .flatten();
+        let format_param = match graph_links_vectors.as_ref() {
+            Some(v) => GraphLinksFormatParam::CompressedWithVectors(v),
+            None => GraphLinksFormatParam::Compressed,
+        };
 
         let graph: GraphLayers =
             graph_layers_builder.into_graph_layers(path, format_param, is_on_disk)?;
diff --git a/lib/segment/src/index/hnsw_index/tests/test_graph_connectivity.rs b/lib/segment/src/index/hnsw_index/tests/test_graph_connectivity.rs
@@ -59,6 +59,7 @@ fn test_graph_connectivity() {
         max_indexing_threads: 4,
         on_disk: Some(false),
         payload_m: None,
+        copy_vectors: None,
     };
 
     let permit_cpu_count = num_rayon_threads(hnsw_config.max_indexing_threads);
diff --git a/lib/segment/src/types.rs b/lib/segment/src/types.rs
@@ -590,6 +590,12 @@ pub struct HnswConfig {
     /// Custom M param for hnsw graph built for payload index. If not set, default M will be used.
     #[serde(default, skip_serializing_if = "Option::is_none")] // Better backward compatibility
     pub payload_m: Option<usize>,
+    /// Store copies of original and quantized vectors within the HNSW index file. Default: false.
+    /// Enabling this option will trade the search speed for disk usage by reducing amount of
+    /// random seeks during the search.
+    /// Requires quantized vectors to be enabled. Multi-vectors are not supported.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub copy_vectors: Option<bool>,
 }
 
 impl HnswConfig {
@@ -602,14 +608,25 @@ impl HnswConfig {
     /// For example, a change in `max_indexing_threads` will not require rebuilding because it
     /// doesn't affect the final index, and thus this would return false.
     pub fn mismatch_requires_rebuild(&self, other: &Self) -> bool {
-        self.m != other.m
-            || self.ef_construct != other.ef_construct
-            || self.full_scan_threshold != other.full_scan_threshold
-            || self.payload_m != other.payload_m
+        let HnswConfig {
+            m,
+            ef_construct,
+            full_scan_threshold,
+            max_indexing_threads: _,
+            payload_m,
+            on_disk,
+            copy_vectors,
+        } = self.clone();
+
+        m != other.m
+            || ef_construct != other.ef_construct
+            || full_scan_threshold != other.full_scan_threshold
+            || payload_m != other.payload_m
             // Data on disk is the same, we have a unit test for that. We can eventually optimize
             // this to just reload the collection rather than optimizing it again as a whole just
             // to flip this flag
-            || self.on_disk != other.on_disk
+            || on_disk != other.on_disk
+            || copy_vectors != other.copy_vectors
     }
 }
 
@@ -1222,6 +1239,7 @@ impl Default for HnswConfig {
             max_indexing_threads: 0,
             on_disk: Some(false),
             payload_m: None,
+            copy_vectors: None,
         }
     }
 }
diff --git a/lib/segment/src/vector_storage/quantized/quantized_vectors.rs b/lib/segment/src/vector_storage/quantized/quantized_vectors.rs
@@ -220,6 +220,10 @@ impl QuantizedVectors {
         }
     }
 
+    pub fn is_on_disk(&self) -> bool {
+        self.storage_impl.is_on_disk()
+    }
+
     /// Get layout for a single quantized vector.
     ///
     /// I.e. the size of a single vector in bytes, and the required alignment.
diff --git a/lib/segment/tests/integration/batch_search_test.rs b/lib/segment/tests/integration/batch_search_test.rs
@@ -142,6 +142,7 @@ fn test_batch_and_single_request_equivalency() {
         max_indexing_threads: 2,
         on_disk: Some(false),
         payload_m: None,
+        copy_vectors: None,
     };
 
     let permit_cpu_count = num_rayon_threads(hnsw_config.max_indexing_threads);
diff --git a/lib/segment/tests/integration/byte_storage_hnsw_test.rs b/lib/segment/tests/integration/byte_storage_hnsw_test.rs
@@ -178,6 +178,7 @@ fn test_byte_storage_hnsw(
         max_indexing_threads: 2,
         on_disk: Some(false),
         payload_m: None,
+        copy_vectors: None,
     };
 
     let permit_cpu_count = 1; // single-threaded for deterministic build
diff --git a/lib/segment/tests/integration/byte_storage_quantization_test.rs b/lib/segment/tests/integration/byte_storage_quantization_test.rs
@@ -331,6 +331,7 @@ fn test_byte_storage_binary_quantization_hnsw(
         max_indexing_threads: 2,
         on_disk: Some(false),
         payload_m: None,
+        copy_vectors: None,
     };
 
     let permit_cpu_count = 1; // single-threaded for deterministic build
diff --git a/lib/segment/tests/integration/exact_search_test.rs b/lib/segment/tests/integration/exact_search_test.rs
@@ -78,6 +78,7 @@ fn exact_search_test() {
         max_indexing_threads: 2,
         on_disk: Some(false),
         payload_m: None,
+        copy_vectors: None,
     };
 
     payload_index_ptr
diff --git a/lib/segment/tests/integration/filtrable_hnsw_test.rs b/lib/segment/tests/integration/filtrable_hnsw_test.rs
@@ -99,6 +99,7 @@ fn _test_filterable_hnsw(
         max_indexing_threads: 2,
         on_disk: Some(false),
         payload_m: None,
+        copy_vectors: None,
     };
 
     let vector_storage = &segment.vector_data[DEFAULT_VECTOR_NAME].vector_storage;
diff --git a/lib/segment/tests/integration/gpu_hnsw_test.rs b/lib/segment/tests/integration/gpu_hnsw_test.rs
diff --git a/lib/segment/tests/integration/hnsw_discover_test.rs b/lib/segment/tests/integration/hnsw_discover_test.rs
diff --git a/lib/segment/tests/integration/hnsw_incremental_build.rs b/lib/segment/tests/integration/hnsw_incremental_build.rs
diff --git a/lib/segment/tests/integration/hnsw_quantized_search_test.rs b/lib/segment/tests/integration/hnsw_quantized_search_test.rs
diff --git a/lib/segment/tests/integration/multivector_filtrable_hnsw_test.rs b/lib/segment/tests/integration/multivector_filtrable_hnsw_test.rs
diff --git a/lib/segment/tests/integration/multivector_hnsw_test.rs b/lib/segment/tests/integration/multivector_hnsw_test.rs
diff --git a/lib/segment/tests/integration/multivector_quantization_test.rs b/lib/segment/tests/integration/multivector_quantization_test.rs
diff --git a/lib/segment/tests/integration/segment_on_disk_snapshot.rs b/lib/segment/tests/integration/segment_on_disk_snapshot.rs

Original file line number	Diff line number	Diff line change
`@@ -6929,6 +6929,11 @@`
`6929`	`6929`	`"format": "uint",`
`6930`	`6930`	`"minimum": 0,`
`6931`	`6931`	`"nullable": true`
	`6932`	`+ },`
	`6933`	`+ "copy_vectors": {`
	`6934`	`+ "description": "Store copies of original and quantized vectors within the HNSW index file. Default: false. Enabling this option will trade the search speed for disk usage by reducing amount of random seeks during the search. Requires quantized vectors to be enabled. Multi-vectors are not supported.",`
	`6935`	`+ "type": "boolean",`
	`6936`	`+ "nullable": true`
`6932`	`6937`	`}`
`6933`	`6938`	`}`
`6934`	`6939`	`},`
`@@ -7222,6 +7227,11 @@`
`7222`	`7227`	`"format": "uint",`
`7223`	`7228`	`"minimum": 0,`
`7224`	`7229`	`"nullable": true`
	`7230`	`+ },`
	`7231`	`+ "copy_vectors": {`
	`7232`	`+ "description": "Store copies of original and quantized vectors within the HNSW index file. Default: false. Enabling this option will trade the search speed for disk usage by reducing amount of random seeks during the search. Requires quantized vectors to be enabled. Multi-vectors are not supported.",`
	`7233`	`+ "type": "boolean",`
	`7234`	`+ "nullable": true`
`7225`	`7235`	`}`
`7226`	`7236`	`}`
`7227`	`7237`	`},`
Original file line number	Diff line number	Diff line change
`@@ -2126,6 +2126,7 @@ impl From<HnswConfigDiff> for segment::types::HnswConfig {`
`2126`	`2126`	`max_indexing_threads,`
`2127`	`2127`	`on_disk,`
`2128`	`2128`	`payload_m,`
	`2129`	`+ copy_vectors,`
`2129`	`2130`	`} = hnsw_config;`
`2130`	`2131`	`Self {`
`2131`	`2132`	`m: m.unwrap_or_default() as usize,`
`@@ -2134,6 +2135,7 @@ impl From<HnswConfigDiff> for segment::types::HnswConfig {`
`2134`	`2135`	`max_indexing_threads: max_indexing_threads.unwrap_or_default() as usize,`
`2135`	`2136`	`on_disk,`
`2136`	`2137`	`payload_m: payload_m.map(\|x\| x as usize),`
	`2138`	`+ copy_vectors,`
`2137`	`2139`	`}`
`2138`	`2140`	`}`
`2139`	`2141`	`}`
Original file line number	Diff line number	Diff line change
`@@ -877,6 +877,7 @@ mod tests {`
`877`	`877`	`max_indexing_threads: 0,`
`878`	`878`	`on_disk: None,`
`879`	`879`	`payload_m: None,`
	`880`	`+ copy_vectors: None,`
`880`	`881`	`};`
`881`	`882`
`882`	`883`	`{`