Merge branch 'main' into rabitq-optim

mnorris11 · web-flow · commit 3506e9b90e61 · 2026-05-22T17:00:57.000-07:00
diff --git a/.github/workflows/build-pip.yml b/.github/workflows/build-pip.yml
@@ -57,6 +57,9 @@ jobs:
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc  # release/v1
+        with:
+          verbose: true
+          attestations: false
 
   publish-testpypi:
     name: Publish to TestPyPI
diff --git a/.github/workflows/index-io-backward-compatibility.yml b/.github/workflows/index-io-backward-compatibility.yml
@@ -52,7 +52,7 @@ jobs:
           eval "$(conda shell.bash hook)"
           conda create -n faiss_conda_read -y python=3.12
           conda activate faiss_conda_read
-          conda install -y -c pytorch -c conda-forge faiss-cpu=1.14.1 "mkl>=2024.2.2,<2026"
+          conda install -y -c pytorch -c conda-forge faiss-cpu=1.14.2 "mkl>=2024.2.2,<2026"
           conda list
 
       - name: Run Conda reader (read Faiss index and verify)
@@ -89,7 +89,7 @@ jobs:
           eval "$(conda shell.bash hook)"
           conda create -n faiss_conda_write -y python=3.12
           conda activate faiss_conda_write
-          conda install -y -c pytorch -c conda-forge faiss-cpu=1.14.1 "mkl>=2024.2.2,<2026"
+          conda install -y -c pytorch -c conda-forge faiss-cpu=1.14.2 "mkl>=2024.2.2,<2026"
           conda list
 
       - name: Create shared data directory
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -51,7 +51,7 @@ if(FAISS_ENABLE_CUVS)
 endif()
 
 project(faiss
-  VERSION 1.14.1
+  VERSION 1.14.2
   DESCRIPTION "A library for efficient similarity search and clustering of dense vectors."
   HOMEPAGE_URL "https://github.com/facebookresearch/faiss"
   LANGUAGES ${FAISS_LANGUAGES})
diff --git a/INSTALL.md b/INSTALL.md
@@ -12,13 +12,13 @@ To install the latest stable release:
 
 ``` shell
 # CPU-only version
-$ conda install -c pytorch -c conda-forge faiss-cpu=1.14.1
+$ conda install -c pytorch -c conda-forge faiss-cpu=1.14.2
 
 # GPU(+CPU) version
-$ conda install -c pytorch -c nvidia -c conda-forge faiss-gpu=1.14.1
+$ conda install -c pytorch -c nvidia -c conda-forge faiss-gpu=1.14.2
 
 # GPU(+CPU) version with NVIDIA cuVS
-$ conda install -c pytorch -c nvidia -c rapidsai -c conda-forge libnvjitlink faiss-gpu-cuvs=1.14.1
+$ conda install -c pytorch -c nvidia -c rapidsai -c conda-forge libnvjitlink faiss-gpu-cuvs=1.14.2
 
 # GPU(+CPU) version using AMD ROCm not yet available
 ```
@@ -34,15 +34,15 @@ If you prefer [Pixi](https://pixi.sh/latest/), you can use the same channels and
 ``` shell
 # CPU-only version
 $ pixi init -c pytorch -c conda-forge
-$ pixi add faiss-cpu=1.14.1
+$ pixi add faiss-cpu=1.14.2
 
 # GPU(+CPU) version
 $ pixi init -c pytorch -c nvidia -c conda-forge
-$ pixi add faiss-gpu=1.14.1
+$ pixi add faiss-gpu=1.14.2
 
 # GPU(+CPU) version with NVIDIA cuVS
 $ pixi init -c pytorch -c nvidia -c rapidsai -c conda-forge
-$ pixi add libnvjitlink faiss-gpu-cuvs=1.14.1
+$ pixi add libnvjitlink faiss-gpu-cuvs=1.14.2
 ```
 
 Pixi resolves packages from the listed Conda channels, so the same channel requirements described above still apply.
@@ -54,7 +54,7 @@ Nightly pre-release packages can be installed as follows:
 $ conda install -c pytorch/label/nightly -c conda-forge faiss-cpu
 
 # GPU(+CPU) version
-$ conda install -c pytorch/label/nightly -c nvidia -c conda-forge faiss-gpu=1.14.1
+$ conda install -c pytorch/label/nightly -c nvidia -c conda-forge faiss-gpu=1.14.2
 
 # GPU(+CPU) version with NVIDIA cuVS (package built with CUDA 13.2)
 conda install -c pytorch -c rapidsai -c rapidsai-nightly -c conda-forge -c nvidia pytorch/label/nightly::faiss-gpu-cuvs 'cuda-version=13.2'
diff --git a/faiss/Index.h b/faiss/Index.h
@@ -17,7 +17,7 @@
 
 #define FAISS_VERSION_MAJOR 1
 #define FAISS_VERSION_MINOR 14
-#define FAISS_VERSION_PATCH 1
+#define FAISS_VERSION_PATCH 2
 
 // Macro to combine the version components into a single string
 #ifndef FAISS_STRINGIFY
diff --git a/faiss/IndexFlat.cpp b/faiss/IndexFlat.cpp
@@ -627,7 +627,7 @@ inline void flat_pano_search_core(
     {
         SingleResultHandler res(handler);
 
-        std::vector<float> query_cum_norms(index.n_levels + 1);
+        std::vector<float> query_cum_norms(index.pano.n_levels + 1);
         std::vector<uint32_t> active_indices(index.batch_size);
         std::vector<uint8_t> active_byteset(index.batch_size);
         std::vector<float> exact_distances(index.batch_size);
@@ -698,7 +698,7 @@ void IndexFlatPanorama::add(idx_t n, const float* x) {
     size_t num_batches = (ntotal + batch_size - 1) / batch_size;
 
     codes.resize(num_batches * batch_size * code_size);
-    cum_sums.resize(num_batches * batch_size * (n_levels + 1));
+    cum_sums.resize(num_batches * batch_size * (pano.n_levels + 1));
 
     const uint8_t* code = reinterpret_cast<const uint8_t*>(x);
     pano.copy_codes_to_level_layout(codes.data(), offset, n, code);
@@ -771,7 +771,7 @@ size_t IndexFlatPanorama::remove_ids(const IDSelector& sel) {
         ntotal = j;
         size_t num_batches = (ntotal + batch_size - 1) / batch_size;
         codes.resize(num_batches * batch_size * code_size);
-        cum_sums.resize(num_batches * batch_size * (n_levels + 1));
+        cum_sums.resize(num_batches * batch_size * (pano.n_levels + 1));
     }
     return nremove;
 }
@@ -843,7 +843,7 @@ void IndexFlatPanorama::search_subset(
             {
                 SingleResultHandler res(handler);
 
-                std::vector<float> query_cum_norms(n_levels + 1);
+                std::vector<float> query_cum_norms(pano.n_levels + 1);
 
                 // Panorama's optimized point-wise refinement (Algorithm 2):
                 // Batch-wise Panorama, as implemented in Panorama.h, incurs
@@ -881,7 +881,7 @@ void IndexFlatPanorama::search_subset(
                             continue;
                         }
 
-                        size_t cum_sum_offset = (n_levels + 1) * idx;
+                        size_t cum_sum_offset = (pano.n_levels + 1) * idx;
                         float cum_sum = cum_sums[cum_sum_offset];
                         float exact_distance = 0.0f;
                         if constexpr (!is_sim) {
@@ -897,7 +897,7 @@ void IndexFlatPanorama::search_subset(
                         local_stats.total_dims += d;
 
                         bool pruned = false;
-                        for (size_t level = 0; level < n_levels; level++) {
+                        for (size_t level = 0; level < pano.n_levels; level++) {
                             local_stats.total_dims_scanned +=
                                     pano.level_width_floats;
 
diff --git a/faiss/IndexHNSW.cpp b/faiss/IndexHNSW.cpp
@@ -707,7 +707,10 @@ IndexHNSWFlat::IndexHNSWFlat(int d_in, int M, MetricType metric)
  **************************************************************/
 
 IndexHNSWFlatPanorama::IndexHNSWFlatPanorama()
-        : IndexHNSWFlat(), cum_sums(), pano(0, 1, 1), num_panorama_levels(0) {}
+        : IndexHNSWFlat(),
+          cum_sums(),
+          pano(sizeof(float), 1, 1),
+          num_panorama_levels(0) {}
 
 IndexHNSWFlatPanorama::IndexHNSWFlatPanorama(
         int d_in,
diff --git a/faiss/impl/Panorama.cpp b/faiss/impl/Panorama.cpp
@@ -67,8 +67,20 @@ Panorama::Panorama(
 void Panorama::set_derived_values() {
     FAISS_THROW_IF_NOT_MSG(n_levels > 0, "Panorama: n_levels must be > 0");
     this->d = code_size / sizeof(float);
+    FAISS_THROW_IF_NOT_MSG(n_levels <= d, "Panorama: n_levels must be <= d");
     this->level_width_floats = ((d + n_levels - 1) / n_levels);
     this->level_width = this->level_width_floats * sizeof(float);
+    size_t n_real_levels = d / level_width_floats;
+    if (d > n_real_levels * level_width_floats) {
+        n_real_levels++;
+    }
+    if (this->n_levels != n_real_levels) {
+        fprintf(stderr,
+                "WARNING truncating nlevels from %zu to %zu\n",
+                this->n_levels,
+                n_real_levels);
+        this->n_levels = n_real_levels;
+    }
 }
 
 /**
@@ -151,12 +163,12 @@ void Panorama::reconstruct(idx_t key, float* recons, const uint8_t* codes_base)
 
     for (size_t level = 0; level < n_levels; level++) {
         size_t level_offset = level * level_width * batch_size;
+        size_t actual_level_width =
+                std::min(level_width, code_size - level * level_width);
         const uint8_t* src = codes_base + batch_offset + level_offset +
-                pos_in_batch * level_width;
+                pos_in_batch * actual_level_width;
         uint8_t* dest = recons_buffer + level * level_width;
-        size_t copy_size =
-                std::min(level_width, code_size - level * level_width);
-        memcpy(dest, src, copy_size);
+        memcpy(dest, src, actual_level_width);
     }
 }
 
diff --git a/faiss/python/setup.py b/faiss/python/setup.py
@@ -114,7 +114,7 @@
 """
 setup(
     name="faiss",
-    version="1.14.1",
+    version="1.14.2",
     description="A library for efficient similarity search and clustering of dense vectors",
     long_description=long_description,
     long_description_content_type="text/plain",
diff --git a/tests/test_flat_panorama.py b/tests/test_flat_panorama.py
@@ -536,7 +536,7 @@ def test_add_search_add_search(self):
 
     def test_reconstruct(self):
         """Test reconstruct and reconstruct_n return original vectors"""
-        d, nb, nt, nq, nlevels = 128, 10000, 15000, 10, 8
+        d, nb, nt, nq, nlevels = 964, 1000, 15000, 10, 128
         _, xb, _ = self.generate_data(d, nt, nb, nq, seed=2025)
 
         for metric in self.METRICS:
@@ -558,7 +558,7 @@ def test_reconstruct(self):
 
     def test_remove_ids_then_add(self):
         """Test removing vectors with remove_ids() then adding more vectors"""
-        d, nb, nt, nq, nlevels, k = 128, 500000, 0, 10, 9, 15
+        d, nb, nt, nq, nlevels, k = 964, 50000, 0, 10, 128, 15
         _, xb, xq = self.generate_data(d, nt, nb, nq, seed=2026)
 
         xb1 = xb[:nb // 2]
@@ -603,7 +603,7 @@ def test_remove_ids_then_add(self):
 
     def test_merge_from(self):
         """Test merging indexes with merge_from()"""
-        d, nb, nt, nq, nlevels, k, batch_size = 128, 500000, 0, 10, 9, 15, 16
+        d, nb, nt, nq, nlevels, k, batch_size = 964, 50000, 0, 10, 128, 15, 16
         _, xb, xq = self.generate_data(d, nt, nb, nq, seed=2027)
 
         # Split data and create two separate indexes
@@ -637,7 +637,7 @@ def test_merge_from(self):
 
     def test_permute_entries(self):
         """Test permuting entries with permute_entries()"""
-        d, nb, nt, nq, nlevels, k = 128, 500000, 0, 10, 8, 15
+        d, nb, nt, nq, nlevels, k = 964, 50000, 0, 20, 128, 10
         _, xb, xq = self.generate_data(d, nt, nb, nq, seed=2028)
 
         for metric in self.METRICS:
@@ -664,7 +664,7 @@ def test_permute_entries(self):
 
     def test_serialization(self):
         """Test write/read Panorama indexes preserves search results"""
-        d, nb, nt, nq, nlevels, k = 128, 10000, 15000, 100, 8, 20
+        d, nb, nt, nq, nlevels, k = 964, 10000, 15000, 100, 128, 20
         _, xb, xq = self.generate_data(d, nt, nb, nq, seed=2024)
 
         for metric in self.METRICS:
diff --git a/tests/test_hnsw_panorama.py b/tests/test_hnsw_panorama.py
@@ -156,6 +156,31 @@ def test_different_panorama_levels(self):
                 # More levels should still maintain reasonable recall
                 self.assertGreaterEqual(recall, 0.80)
 
+    def test_uneven_dimension_division(self):
+        """Test when n_levels doesn't evenly divide dimension."""
+        test_cases = [(65, 4), (63, 8), (100, 7), (960, 128), (964, 128)]
+
+        nb, nt, nq, k = 1000, 700, 20, 5
+
+        for d, nlevels in test_cases:
+            with self.subTest(d=d, nlevels=nlevels):
+                _, xb, xq = self.generate_data(d, nt, nb, nq, seed=789)
+
+                index = faiss.IndexHNSWFlatPanorama(d, 32, nlevels)
+                index.hnsw.efSearch = 64
+                index.add(xb)
+
+                _, I = index.search(xq, k)
+
+                _, gt_I = self.compute_ground_truth(xb, xq, k)
+
+                recall = self.compute_recall(gt_I, I)
+                self.assertGreaterEqual(
+                    recall, 0.80,
+                    f"Recall too low for d={d}, nlevels={nlevels}: "
+                    f"{recall:.4f}",
+                )
+
     def test_consistency(self):
         """Test that search results are consistent across multiple searches."""
         d = 64
@@ -180,16 +205,17 @@ def test_consistency(self):
 
     def test_io(self):
         """Test serialization and deserialization."""
-        d = 64
+        d = 964
         nb = 500
         nt = 700
         nq = 10
         k = 5
+        nlevels = 128
 
         # Generate data
         _, xb, xq = self.generate_data(d, nt, nb, nq, seed=2024)
 
-        index = faiss.IndexHNSWFlatPanorama(d, 16, 8)
+        index = faiss.IndexHNSWFlatPanorama(d, 16, nlevels)
         index.add(xb)
 
         # Get search results before saving
@@ -204,7 +230,7 @@ def test_io(self):
             self.assertIsInstance(loaded_index, faiss.IndexHNSWFlatPanorama)
             self.assertEqual(loaded_index.d, d)
             self.assertEqual(loaded_index.ntotal, nb)
-            self.assertEqual(loaded_index.num_panorama_levels, 8)
+            self.assertEqual(loaded_index.num_panorama_levels, nlevels)
 
             # Search after loading
             D_after, I_after = loaded_index.search(xq, k)
diff --git a/tests/test_ivf_flat_panorama.py b/tests/test_ivf_flat_panorama.py
@@ -280,7 +280,7 @@ def test_different_n_levels(self):
 
     def test_uneven_dimension_division(self):
         """Test when n_levels doesn't evenly divide dimension"""
-        test_cases = [(65, 4), (63, 8), (100, 7)]
+        test_cases = [(65, 4), (63, 8), (100, 7), (960, 128), (964, 128)]
 
         # TODO(aknayar): Test functions like get_single_code().
 
diff --git a/tests/test_refine_panorama.py b/tests/test_refine_panorama.py
@@ -167,7 +167,7 @@ def test_different_n_levels(self):
 
     def test_uneven_dimension_division(self):
         """Test when n_levels doesn't evenly divide dimension"""
-        test_cases = [(65, 4), (63, 8), (100, 7)]
+        test_cases = [(65, 4), (63, 8), (100, 7), (960, 128), (964, 128)]
 
         for metric in self.METRICS:
             for d, nlevels in test_cases:
