Enable Intel ScalableVectorSearch support #4548

dian-lun-lin · 2025-08-23T00:36:36Z

Pull Request resolved: #4450

This pull request introduces support for Intel ScalableVectorSearch, integrating Intel's proprietary LVQ and LeanVec technologies in binary form. The following index types are now supported: IndexSVSVamana, IndexSVSVamanaLVQ, IndexSVSVamanaLeanVec, and IndexSVSFlat. IndexSVSVamana and IndexSVSFlat utilizes SVS open-source float32/float16/int8 implementation.

Key features and enhancements include:

Implemented search, add, and remove_ids
Implemented filter search and range_search
Enabled SVS open-source fp16 and scalar quantization implementation
Enabled factory methods
Enabled save/load
Enabled Python bindings
Enable fallback mechanism that fallbacks to 8-bit scalar quantization if LVQ/LeanVec is used on non-intel hardware CPUs
Added examples in both Python and C++ under the tutorial/ directory
Added FAISS_ENABLE_SVS flag to allows users to optionally enable SVS

TODOs:

Support more indices such as IndexSVSIVF and IndexSVSFlat with LVQ and LeanVec
Documentation

Support LVQ/LeanVec runtime quantization level

Enable SVS LeanVec

Support SVS index factory

mnorris11 · 2025-10-08T17:52:37Z

The format step is requesting these changes (let me know if you can see logs, then I won't paste a huge block in the future):

diff --git a/faiss/svs/IndexSVSFlat.cpp b/faiss/svs/IndexSVSFlat.cpp
index d33ff3b..5bfd00a 100644
--- a/faiss/svs/IndexSVSFlat.cpp
+++ b/faiss/svs/IndexSVSFlat.cpp
@@ -127,14 +127,12 @@ void IndexSVSFlat::deserialize_impl(std::istream& in) {
 
     switch (metric_type) {
         case METRIC_INNER_PRODUCT:
-            impl = new svs::Flat(
-                    svs::Flat::assemble<float, storage_type>(
-                            in, svs::DistanceIP(), std::move(threadpool)));
+            impl = new svs::Flat(svs::Flat::assemble<float, storage_type>(
+                    in, svs::DistanceIP(), std::move(threadpool)));
             break;
         case METRIC_L2:
-            impl = new svs::Flat(
-                    svs::Flat::assemble<float, storage_type>(
-                            in, svs::DistanceL2(), std::move(threadpool)));
+            impl = new svs::Flat(svs::Flat::assemble<float, storage_type>(
+                    in, svs::DistanceL2(), std::move(threadpool)));
             break;
         default:
             FAISS_ASSERT(!"not supported SVS distance");
diff --git a/faiss/svs/IndexSVSVamana.cpp b/faiss/svs/IndexSVSVamana.cpp
index 2465c2c..4d94f53 100644
--- a/faiss/svs/IndexSVSVamana.cpp
+++ b/faiss/svs/IndexSVSVamana.cpp
@@ -74,10 +74,10 @@ template <
         typename Alloc = svs::data::Blocked<svs::lib::Allocator<T>>,
         svs::data::ImmutableMemoryDataset Dataset,
         svs::threads::ThreadPool Pool>
-requires std::is_floating_point_v<T> || std::is_same_v<T, svs::Float16>
-        svs::data::SimpleData<T, svs::Dynamic, Alloc> make_storage(
-                const Dataset& data,
-                Pool& pool) {
+    requires std::is_floating_point_v<T> || std::is_same_v<T, svs::Float16>
+svs::data::SimpleData<T, svs::Dynamic, Alloc> make_storage(
+        const Dataset& data,
+        Pool& pool) {
     svs::data::SimpleData<T, svs::Dynamic, Alloc> result(
             data.size(), data.dimensions(), Alloc{});
     svs::threads::parallel_for(
@@ -96,9 +96,10 @@ template <
         typename Alloc = svs::data::Blocked<svs::lib::Allocator<T>>,
         svs::data::ImmutableMemoryDataset Dataset,
         svs::threads::ThreadPool Pool>
-requires std::is_integral_v<T> svs::quantization::scalar::
-        SQDataset<T, svs::Dynamic, Alloc>
-        make_storage(const Dataset& data, Pool& pool) {
+    requires std::is_integral_v<T>
+svs::quantization::scalar::SQDataset<T, svs::Dynamic, Alloc> make_storage(
+        const Dataset& data,
+        Pool& pool) {
     return svs::quantization::scalar::SQDataset<T, svs::Dynamic, Alloc>::
             compress(data, pool, Alloc{});
 }
@@ -165,12 +166,10 @@ svs::DynamicVamana* deserialize_impl_t(
 
     return std::visit(
             [&](auto&& distance) {
-                return new svs::DynamicVamana(
-                        svs::DynamicVamana::
-                                assemble<float, storage_type_t<ElementType>>(
-                                        stream,
-                                        std::move(distance),
-                                        std::move(threadpool)));
+                return new svs::DynamicVamana(svs::DynamicVamana::assemble<
+                                              float,
+                                              storage_type_t<ElementType>>(
+                        stream, std::move(distance), std::move(threadpool)));
             },
             get_svs_distance(metric));
 }
diff --git a/faiss/svs/IndexSVSVamanaLVQ.cpp b/faiss/svs/IndexSVSVamanaLVQ.cpp
index 1a1b3ed..c4d6610 100644
--- a/faiss/svs/IndexSVSVamanaLVQ.cpp
+++ b/faiss/svs/IndexSVSVamanaLVQ.cpp
@@ -181,12 +181,10 @@ void IndexSVSVamanaLVQ::deserialize_impl(std::istream& in) {
                             FAISS_ASSERT(!"not supported SVS LVQ level");
                     }
                 } else {
-                    impl = new svs::DynamicVamana(
-                            svs::DynamicVamana::
-                                    assemble<float, storage_type_sq>(
-                                            in,
-                                            svs_distance,
-                                            std::move(threadpool)));
+                    impl = new svs::DynamicVamana(svs::DynamicVamana::assemble<
+                                                  float,
+                                                  storage_type_sq>(
+                            in, svs_distance, std::move(threadpool)));
                 }
             },
             svs_distance);
diff --git a/faiss/svs/IndexSVSVamanaLeanVec.cpp b/faiss/svs/IndexSVSVamanaLeanVec.cpp
index 3f95adb..992470c 100644
--- a/faiss/svs/IndexSVSVamanaLeanVec.cpp
+++ b/faiss/svs/IndexSVSVamanaLeanVec.cpp
@@ -228,12 +228,10 @@ void IndexSVSVamanaLeanVec::deserialize_impl(std::istream& in) {
                             FAISS_ASSERT(!"not supported SVS LeanVec level");
                     }
                 } else {
-                    impl = new svs::DynamicVamana(
-                            svs::DynamicVamana::
-                                    assemble<float, storage_type_sq>(
-                                            in,
-                                            svs_distance,
-                                            std::move(threadpool)));
+                    impl = new svs::DynamicVamana(svs::DynamicVamana::assemble<
+                                                  float,
+                                                  storage_type_sq>(
+                            in, svs_distance, std::move(threadpool)));
                 }
             },
             svs_distance);
diff --git a/tests/test_svs.cpp b/tests/test_svs.cpp
index ff72fd8..f5556ab 100644
--- a/tests/test_svs.cpp
+++ b/tests/test_svs.cpp
@@ -21,13 +21,13 @@
  */
 
 #include <faiss/Index.h>
+#include <faiss/impl/AuxIndexStructures.h>
+#include <faiss/impl/IDSelector.h>
+#include <faiss/index_io.h>
 #include <faiss/svs/IndexSVSFlat.h>
 #include <faiss/svs/IndexSVSVamana.h>
 #include <faiss/svs/IndexSVSVamanaLVQ.h>
 #include <faiss/svs/IndexSVSVamanaLeanVec.h>
-#include <faiss/impl/AuxIndexStructures.h>
-#include <faiss/impl/IDSelector.h>
-#include <faiss/index_io.h>
 #include <gtest/gtest.h>
 #include <type_traits>

SVS clang format

dian-lun-lin · 2025-10-09T18:01:52Z

The format step is requesting these changes (let me know if you can see logs, then I won't paste a huge block in the future):

diff --git a/faiss/svs/IndexSVSFlat.cpp b/faiss/svs/IndexSVSFlat.cpp
index d33ff3b..5bfd00a 100644
--- a/faiss/svs/IndexSVSFlat.cpp
+++ b/faiss/svs/IndexSVSFlat.cpp
@@ -127,14 +127,12 @@ void IndexSVSFlat::deserialize_impl(std::istream& in) {
 
     switch (metric_type) {
         case METRIC_INNER_PRODUCT:
-            impl = new svs::Flat(
-                    svs::Flat::assemble<float, storage_type>(
-                            in, svs::DistanceIP(), std::move(threadpool)));
+            impl = new svs::Flat(svs::Flat::assemble<float, storage_type>(
+                    in, svs::DistanceIP(), std::move(threadpool)));
             break;
         case METRIC_L2:
-            impl = new svs::Flat(
-                    svs::Flat::assemble<float, storage_type>(
-                            in, svs::DistanceL2(), std::move(threadpool)));
+            impl = new svs::Flat(svs::Flat::assemble<float, storage_type>(
+                    in, svs::DistanceL2(), std::move(threadpool)));
             break;
         default:
             FAISS_ASSERT(!"not supported SVS distance");
diff --git a/faiss/svs/IndexSVSVamana.cpp b/faiss/svs/IndexSVSVamana.cpp
index 2465c2c..4d94f53 100644
--- a/faiss/svs/IndexSVSVamana.cpp
+++ b/faiss/svs/IndexSVSVamana.cpp
@@ -74,10 +74,10 @@ template <
         typename Alloc = svs::data::Blocked<svs::lib::Allocator<T>>,
         svs::data::ImmutableMemoryDataset Dataset,
         svs::threads::ThreadPool Pool>
-requires std::is_floating_point_v<T> || std::is_same_v<T, svs::Float16>
-        svs::data::SimpleData<T, svs::Dynamic, Alloc> make_storage(
-                const Dataset& data,
-                Pool& pool) {
+    requires std::is_floating_point_v<T> || std::is_same_v<T, svs::Float16>
+svs::data::SimpleData<T, svs::Dynamic, Alloc> make_storage(
+        const Dataset& data,
+        Pool& pool) {
     svs::data::SimpleData<T, svs::Dynamic, Alloc> result(
             data.size(), data.dimensions(), Alloc{});
     svs::threads::parallel_for(
@@ -96,9 +96,10 @@ template <
         typename Alloc = svs::data::Blocked<svs::lib::Allocator<T>>,
         svs::data::ImmutableMemoryDataset Dataset,
         svs::threads::ThreadPool Pool>
-requires std::is_integral_v<T> svs::quantization::scalar::
-        SQDataset<T, svs::Dynamic, Alloc>
-        make_storage(const Dataset& data, Pool& pool) {
+    requires std::is_integral_v<T>
+svs::quantization::scalar::SQDataset<T, svs::Dynamic, Alloc> make_storage(
+        const Dataset& data,
+        Pool& pool) {
     return svs::quantization::scalar::SQDataset<T, svs::Dynamic, Alloc>::
             compress(data, pool, Alloc{});
 }
@@ -165,12 +166,10 @@ svs::DynamicVamana* deserialize_impl_t(
 
     return std::visit(
             [&](auto&& distance) {
-                return new svs::DynamicVamana(
-                        svs::DynamicVamana::
-                                assemble<float, storage_type_t<ElementType>>(
-                                        stream,
-                                        std::move(distance),
-                                        std::move(threadpool)));
+                return new svs::DynamicVamana(svs::DynamicVamana::assemble<
+                                              float,
+                                              storage_type_t<ElementType>>(
+                        stream, std::move(distance), std::move(threadpool)));
             },
             get_svs_distance(metric));
 }
diff --git a/faiss/svs/IndexSVSVamanaLVQ.cpp b/faiss/svs/IndexSVSVamanaLVQ.cpp
index 1a1b3ed..c4d6610 100644
--- a/faiss/svs/IndexSVSVamanaLVQ.cpp
+++ b/faiss/svs/IndexSVSVamanaLVQ.cpp
@@ -181,12 +181,10 @@ void IndexSVSVamanaLVQ::deserialize_impl(std::istream& in) {
                             FAISS_ASSERT(!"not supported SVS LVQ level");
                     }
                 } else {
-                    impl = new svs::DynamicVamana(
-                            svs::DynamicVamana::
-                                    assemble<float, storage_type_sq>(
-                                            in,
-                                            svs_distance,
-                                            std::move(threadpool)));
+                    impl = new svs::DynamicVamana(svs::DynamicVamana::assemble<
+                                                  float,
+                                                  storage_type_sq>(
+                            in, svs_distance, std::move(threadpool)));
                 }
             },
             svs_distance);
diff --git a/faiss/svs/IndexSVSVamanaLeanVec.cpp b/faiss/svs/IndexSVSVamanaLeanVec.cpp
index 3f95adb..992470c 100644
--- a/faiss/svs/IndexSVSVamanaLeanVec.cpp
+++ b/faiss/svs/IndexSVSVamanaLeanVec.cpp
@@ -228,12 +228,10 @@ void IndexSVSVamanaLeanVec::deserialize_impl(std::istream& in) {
                             FAISS_ASSERT(!"not supported SVS LeanVec level");
                     }
                 } else {
-                    impl = new svs::DynamicVamana(
-                            svs::DynamicVamana::
-                                    assemble<float, storage_type_sq>(
-                                            in,
-                                            svs_distance,
-                                            std::move(threadpool)));
+                    impl = new svs::DynamicVamana(svs::DynamicVamana::assemble<
+                                                  float,
+                                                  storage_type_sq>(
+                            in, svs_distance, std::move(threadpool)));
                 }
             },
             svs_distance);
diff --git a/tests/test_svs.cpp b/tests/test_svs.cpp
index ff72fd8..f5556ab 100644
--- a/tests/test_svs.cpp
+++ b/tests/test_svs.cpp
@@ -21,13 +21,13 @@
  */
 
 #include <faiss/Index.h>
+#include <faiss/impl/AuxIndexStructures.h>
+#include <faiss/impl/IDSelector.h>
+#include <faiss/index_io.h>
 #include <faiss/svs/IndexSVSFlat.h>
 #include <faiss/svs/IndexSVSVamana.h>
 #include <faiss/svs/IndexSVSVamanaLVQ.h>
 #include <faiss/svs/IndexSVSVamanaLeanVec.h>
-#include <faiss/impl/AuxIndexStructures.h>
-#include <faiss/impl/IDSelector.h>
-#include <faiss/index_io.h>
 #include <gtest/gtest.h>
 #include <type_traits>

solved. Thanks!

meta-codesync · 2025-10-15T15:28:03Z

@mnorris11 has imported this pull request. If you are a Meta employee, you can view this in D84713772.

faiss/index_factory.cpp

mnorris11 · 2025-10-15T15:40:58Z

faiss/impl/svs_io.cpp

@@ -0,0 +1,72 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.


Our internal linter is flagging that this copyright has 2 headers (which is OK), but we should prepend "Portions", so it should just read as "Portions Copyright ...etc" instead of starting with just "Copyright". I think this would be applicable to any new file added.

mnorris11 · 2025-10-15T16:07:15Z

tests/CMakeLists.txt

+if(FAISS_ENABLE_SVS)
+  list(APPEND FAISS_TEST_SRC test_svs.cpp)
+endif()
+


For some reason the build is failing, even though there is a condition here for including test_svs.cpp. (Ideally no build will change from this PR, and we can add a CI for SVS enabled in a second PR.)

[100%] Building CXX object tests/CMakeFiles/faiss_test.dir/test_svs.cpp.o

https://github.com/facebookresearch/faiss/actions/runs/18384740136/job/52824514737?pr=4548

mnorris11 · 2025-10-15T16:31:20Z

CMakeLists.txt

 option(FAISS_ENABLE_C_API "Build C API." OFF)
 option(FAISS_ENABLE_EXTRAS "Build extras like benchmarks and demos" ON)
 option(FAISS_USE_LTO "Enable Link-Time optimization" OFF)
+option(FAISS_ENABLE_SVS "Enable SVS (Intel(R) Scalable Vector Search) integration." ON)


Is the build failure due to this by default being ON?

by default do we want to keep it ON or we want o keep it OFF? (concern stems from whether we are confident that SVS works on all platforms that we care to support, with the expected performance levels)

Yeah after discussion, we plan to set OFF by default, and we will create a new CI which will enable it. If it does not break other platforms, eventually we can set ON by default, but that can be a separate PR.

update SVS lib to support gcc14

subhadeepkaran · 2025-10-20T17:41:08Z

faiss/impl/index_read.cpp

+        svs->deserialize_impl(is);
+        idx = svs;
+    } else if (h == fourcc("ISVF")) {
+        // SVS Flat


nit: comment needed?

subhadeepkaran · 2025-10-20T17:44:50Z

faiss/CMakeLists.txt

+  find_package(svs REQUIRED)
+  target_compile_options(svs::svs INTERFACE "-DSVS_ENABLE_OMP=1")
+
+  target_link_libraries(faiss PUBLIC svs::svs svs::svs_shared_library)


nit: maybe we can use a loop?

fix(io): don't read too many bytes from IOReader

fix(svsio): allow writing/reading of non-initialized index

… without data

…-fixup fix store/load for vamana & leanvec

dian-lun-lin and others added 30 commits July 2, 2025 18:02

init SVS uncompressed data support

8fd27d6

Merge branch 'facebookresearch:main' into svs-init

c499b93

initial naive additional of SVS i/o

0bd1fdd

use Tempfilename

6885f30

Add I/O to example

0215940

revise, add LVQ, and python bindings

d4d1226

on going work

48904f3

cleanup after cherry-picking aaron's latest commits

b4c768a

First implementation of IndexSVSFlat

5cf26a9

implement first feedback

11b44f7

Merge remote-tracking branch 'origin/main' into svs-io

9854e82

Fix tests for LVQ4x4

0df0771

add LVQ4x8

014960d

initial set of SVS python tests

09c0db5

fix some tests

969d595

support LVQ/LeanVec runtime quantization level

9e3c48e

Merge pull request #2 from ahuber21/svs-lvq-leanvec-run-params

a585e9d

Support LVQ/LeanVec runtime quantization level

Fix LVQ in test_svs.cpp

7eb6289

clang-format

6dbb96f

fix impl cleanup in destructor

90b15b6

continue work on C++ & py tests

38b7eea

enable SVS LeanVec

4f36df5

Merge pull request #3 from ahuber21/svs-leanvec

713cc36

Enable SVS LeanVec

I/O support for LeanVec

8f16863

support SVS index factory

034320b

enable clang format

c7c3577

Merge pull request #4 from ahuber21/svs-factory

9ff7b53

Support SVS index factory

streaming write to disk

b2b9819

change how files are streamed

d31bcb1

Update SVS version

483193a

Merge branch 'facebookresearch:main' into svs-io

3ce665a

dian-lun-lin marked this pull request as ready for review October 7, 2025 23:37

mnorris11 self-assigned this Oct 8, 2025

dian-lun-lin added 3 commits October 9, 2025 10:50

enable clang format

c85c538

clang format for conecpt

13e3897

Merge pull request #32 from ahuber21/svs-clang-format

3537df7

SVS clang format

mnorris11 reviewed Oct 15, 2025

View reviewed changes

faiss/index_factory.cpp Show resolved Hide resolved

mnorris11 reviewed Oct 15, 2025

View reviewed changes

dian-lun-lin added 3 commits October 15, 2025 15:02

update submodule to support gcc14

4c3c82e

Merge pull request #33 from ahuber21/svs-update

c14ab71

update SVS lib to support gcc14

Merge branch 'main' into svs-io

6da649f

subhadeepkaran reviewed Oct 20, 2025

View reviewed changes

faiss/impl/index_read.cpp

svs->deserialize_impl(is);

idx = svs;

} else if (h == fourcc("ISVF")) {

// SVS Flat

Copy link

subhadeepkaran Oct 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: comment needed?

subhadeepkaran reviewed Oct 20, 2025

View reviewed changes

ahuber21 and others added 5 commits October 21, 2025 11:48

fix(io): don't read too many bytes from IOReader

95e8f66

Merge pull request #36 from ahuber21/svs-io-fix-buffering

63ba062

fix(io): don't read too many bytes from IOReader

fix(svsio): allow writing/reading of non-initialized index

2dce7f4

Merge pull request #38 from ahuber21/svs-io-fix-noninit-serialization

a5800d4

fix(svsio): allow writing/reading of non-initialized index

fix nulllptr return

01ab8df

mnorris11 added enhancement Implementation labels Oct 27, 2025

ahuber21 and others added 5 commits October 28, 2025 08:21

add test cases for saving/loading uninitialized index & trained index…

f71cf1e

… without data

store leanvec matrix

230d202

store leanvec matrix

27b1b9d

update svs release

edbe9cd

Merge pull request #39 from ahuber21/svs-io-fix-noninit-serialization…

b709fa1

…-fixup fix store/load for vamana & leanvec

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Enable Intel ScalableVectorSearch support #4548

Enable Intel ScalableVectorSearch support #4548

dian-lun-lin commented Aug 23, 2025 •

edited

Loading

Uh oh!

mnorris11 commented Oct 8, 2025

Uh oh!

dian-lun-lin commented Oct 9, 2025

Uh oh!

meta-codesync bot commented Oct 15, 2025

Uh oh!

Uh oh!

mnorris11 Oct 15, 2025

Uh oh!

mnorris11 Oct 15, 2025

Uh oh!

mnorris11 Oct 15, 2025

Uh oh!

subhadeepkaran Oct 20, 2025 •

edited

Loading

Uh oh!

mnorris11 Oct 27, 2025

Uh oh!

subhadeepkaran Oct 20, 2025

Uh oh!

subhadeepkaran Oct 20, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

		@@ -0,0 +1,72 @@
		/*
		* Copyright (c) Meta Platforms, Inc. and affiliates.

Enable Intel ScalableVectorSearch support #4548

Are you sure you want to change the base?

Enable Intel ScalableVectorSearch support #4548

Conversation

dian-lun-lin commented Aug 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mnorris11 commented Oct 8, 2025

Uh oh!

dian-lun-lin commented Oct 9, 2025

Uh oh!

meta-codesync bot commented Oct 15, 2025

Uh oh!

Uh oh!

mnorris11 Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

mnorris11 Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

mnorris11 Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

subhadeepkaran Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mnorris11 Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

subhadeepkaran Oct 20, 2025

Choose a reason for hiding this comment

Uh oh!

subhadeepkaran Oct 20, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

dian-lun-lin commented Aug 23, 2025 •

edited

Loading

subhadeepkaran Oct 20, 2025 •

edited

Loading