faiss 0.6.4 → 0.6.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a22f4ad8f3c626f1d6571c4cefcb8292965e52eb3b0b77c354f39ed117570c5
-  data.tar.gz: b848af534bebc2ecfdfa5fe7eaa270b530d17d5fe5381aea350451aa03c22d9f
+  metadata.gz: f7ff5a38fc140c730f7dfca4bbbfa2e2e4980fd63bf9f069ebbb9eb8deb4d50c
+  data.tar.gz: 919723a22c26f62267c9be7e34250ef7a30a5da682679634dd64471eef5187c4
 SHA512:
-  metadata.gz: 4c5083b9733f589fc30c93f429ed4da74fbb4bbdbe2bde17787506cafb178e2715d114e04ed17bd21a1161a096df66a0c502ae6dc245455c1e221737e80a1f3e
-  data.tar.gz: 41eb8ce7434c4408fccf238893468e8c808b1961966a9fc495f960d27ff950d5d6a9cafff18a11e14287f5fedc77f83db9118c47c60e06fdc9f86d9987592c7c
+  metadata.gz: 28e32877ea44804c5f73fcae9b8df462a024c56198156c0928a7ac2405d8cb4263e266bcc1fba2f88c41e3d62ba626fc55a4a228fe06e2d4e24421bb6e02b61b
+  data.tar.gz: 56cfa780d1d5361e3b43937c1b392a26528e4f3bd8166b0945c9cda63b32942e7001b7703e5705ba158a70ed92da69ef6983d1bbacd94362a9167403874aeb1e

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.6.5 (2026-11-10)
+
+- Updated Faiss to 1.16.0
+
 ## 0.6.4 (2026-09-17)
 
 - Updated Faiss to 1.15.1

data/ext/faiss/extconf.rb

@@ -33,7 +33,7 @@ ext = File.expand_path(".", __dir__)
 vendor = File.expand_path("../../vendor/faiss", __dir__)
 
 $srcs = Dir["{#{ext},#{vendor}/faiss,#{vendor}/faiss/{impl,invlists,utils}/**}/*.{cpp}"]
-$srcs -= ["avx2", "avx512", "aarch64", "arm_sve"].map { |v| "#{vendor}/faiss/utils/simd_impl/distances_#{v}.cpp" }
+$srcs.reject! { |v| v.match?(/avx2|avx512|neon|sve|rvv|simdlib_based|distances_aarch64/) }
 $objs = $srcs.map { |v| v.sub(/cpp\z/, "o") }
 abort "Faiss not found" unless find_header("faiss/Index.h", vendor)
 $VPATH << vendor

data/lib/faiss/version.rb

@@ -1,3 +1,3 @@
 module Faiss
-  VERSION = "0.6.4"
+  VERSION = "0.6.5"
 end

data/vendor/faiss/faiss/AutoTune.cpp

@@ -14,6 +14,7 @@
 #include <faiss/AutoTune.h>
 
 #include <cinttypes>
+#include <cmath>
 
 #include <faiss/impl/FaissAssert.h>
 #include <faiss/utils/random.h>
@@ -31,6 +32,11 @@
 #include <faiss/IndexRefine.h>
 #include <faiss/IndexShardsIVF.h>
 
+#ifdef FAISS_ENABLE_SVS
+#include <faiss/svs/IndexSVSVamana.h>
+#include <faiss/svs/IndexSVSVamanaLeanVec.h>
+#endif
+
 namespace faiss {
 
 AutoTuneCriterion::AutoTuneCriterion(idx_t nq_in, idx_t nnn_in)
@@ -484,6 +490,166 @@ void ParameterSpace::set_index_parameters(
             });
 }
 
+#ifdef FAISS_ENABLE_SVS
+
+namespace {
+
+size_t svs_size_param(const std::string& name, double val) {
+    FAISS_THROW_IF_NOT_FMT(
+            std::isfinite(val) && val >= 0,
+            "ParameterSpace::set_index_parameter: %s cannot be negative (%g)",
+            name.c_str(),
+            val);
+    FAISS_THROW_IF_NOT_FMT(
+            val == std::floor(val),
+            "ParameterSpace::set_index_parameter: %s must be an integer (%g)",
+            name.c_str(),
+            val);
+    // The double -> size_t cast below is undefined behavior on overflow.
+    // 2^(8*sizeof(size_t)) is exact in double, so a value below it always
+    // fits.
+    FAISS_THROW_IF_NOT_FMT(
+            val < std::ldexp(1.0, static_cast<int>(8 * sizeof(size_t))),
+            "ParameterSpace::set_index_parameter: %s is too large (%g)",
+            name.c_str(),
+            val);
+    return size_t(val);
+}
+
+/* Checks to make sure ix->impl is null. The SVS build parameters are consumed
+   when the backend index is created on the first add() (ix->impl != nullptr
+   afterwards), so setting them later would be silently ignored. For LeanVec,
+   train() only builds training_data (consuming leanvec_d); the remaining build
+   parameters are still consumed at the first add(), hence remain settable after
+   train() but before add(). */
+void check_svs_not_built(const IndexSVSVamana* ix, const std::string& name) {
+    FAISS_THROW_IF_NOT_FMT(
+            ix->impl == nullptr,
+            "ParameterSpace::set_index_parameter: %s is a build-time "
+            "parameter, it cannot be changed after the SVS index is built",
+            name.c_str());
+}
+
+/* Sets a parameter of IndexSVSVamana or of its LVQ / LeanVec subclasses.
+   Returns false if the name is not an SVS Vamana parameter. */
+bool set_svs_vamana_parameter(
+        IndexSVSVamana* ix,
+        const std::string& name,
+        double val) {
+    // Search parameters: re-read on every search(), hence tunable at any point
+    // in the index lifetime.
+    if (name == "search_window_size") {
+        ix->search_window_size = svs_size_param(name, val);
+        return true;
+    }
+    if (name == "search_buffer_capacity") {
+        ix->search_buffer_capacity = svs_size_param(name, val);
+        return true;
+    }
+
+    // Graph build parameters.
+    if (name == "graph_max_degree") {
+        check_svs_not_built(ix, name);
+        ix->graph_max_degree = svs_size_param(name, val);
+        return true;
+    }
+    if (name == "prune_to") {
+        check_svs_not_built(ix, name);
+        ix->prune_to = svs_size_param(name, val);
+        return true;
+    }
+    if (name == "alpha") {
+        check_svs_not_built(ix, name);
+        ix->alpha = float(val);
+        return true;
+    }
+    if (name == "construction_window_size") {
+        check_svs_not_built(ix, name);
+        ix->construction_window_size = svs_size_param(name, val);
+        return true;
+    }
+    if (name == "max_candidate_pool_size") {
+        check_svs_not_built(ix, name);
+        ix->max_candidate_pool_size = svs_size_param(name, val);
+        return true;
+    }
+    if (name == "use_full_search_history") {
+        check_svs_not_built(ix, name);
+        ix->use_full_search_history = val != 0;
+        return true;
+    }
+
+    // Vector storage, which includes the LVQ and LeanVec compression levels.
+    if (name == "storage_kind") {
+        check_svs_not_built(ix, name);
+        size_t kind_idx = svs_size_param(name, val);
+        FAISS_THROW_IF_NOT_FMT(
+                kind_idx < static_cast<size_t>(SVS_count),
+                "ParameterSpace::set_index_parameter: %g is not a valid "
+                "SVSStorageKind",
+                val);
+        auto kind = static_cast<SVSStorageKind>(kind_idx);
+        // Reject a kind that this build or machine does not support here
+        // rather than at build time, like the IndexSVSVamana constructor does.
+        // Both backends are accepted because storage_kind and is_static are
+        // build-time parameters that can be set in any order; the backend
+        // selected by is_static re-checks the kind at build time.
+        auto svs_kind = to_svs_storage_kind(kind);
+        auto status_static =
+                svs_runtime::VamanaIndex::check_storage_kind(svs_kind);
+        auto status_dynamic =
+                svs_runtime::DynamicVamanaIndex::check_storage_kind(svs_kind);
+        if (!status_static.ok() && !status_dynamic.ok()) {
+            FAISS_THROW_FMT(
+                    "ParameterSpace::set_index_parameter: %s value %g is not "
+                    "supported (static: %s; dynamic: %s)",
+                    name.c_str(),
+                    val,
+                    status_static.message(),
+                    status_dynamic.message());
+        }
+        ix->storage_kind = kind;
+        return true;
+    }
+    if (name == "is_static") {
+        check_svs_not_built(ix, name);
+        ix->is_static = val != 0;
+        return true;
+    }
+    if (name == "store_vectors") {
+        // Dropping the copy of the added vectors is always possible, but it
+        // cannot be undone: the copy left would not line up with the ids.
+        FAISS_THROW_IF_MSG(
+                val != 0 && !ix->stored_vectors_valid,
+                "ParameterSpace::set_index_parameter: store_vectors cannot be "
+                "re-enabled once the stored vectors have been dropped");
+        ix->store_vectors = val != 0;
+        return true;
+    }
+
+    // LeanVec only: dimensionality of the reduced (primary) vectors.
+    if (name == "leanvec_d") {
+        auto* lv = dynamic_cast<IndexSVSVamanaLeanVec*>(ix);
+        FAISS_THROW_IF_NOT_MSG(
+                lv,
+                "ParameterSpace::set_index_parameter: leanvec_d only applies "
+                "to IndexSVSVamanaLeanVec");
+        check_svs_not_built(lv, name);
+        FAISS_THROW_IF_MSG(
+                lv->training_data,
+                "ParameterSpace::set_index_parameter: leanvec_d cannot be "
+                "changed after the LeanVec index has been trained");
+        lv->leanvec_d = svs_size_param(name, val);
+        return true;
+    }
+
+    return false;
+}
+
+} // anonymous namespace
+
+#endif // FAISS_ENABLE_SVS
+
 // non-const version
 // Do not use this macro if ix will be unused
 #define DC(classname) classname* ix_ = dynamic_cast<classname*>(index)
@@ -613,6 +779,15 @@ void ParameterSpace::set_index_parameter(
         }
     }
 
+#ifdef FAISS_ENABLE_SVS
+    // Covers IndexSVSVamanaLVQ and IndexSVSVamanaLeanVec as well
+    if (DC(IndexSVSVamana)) {
+        if (set_svs_vamana_parameter(ix_, name, val)) {
+            return;
+        }
+    }
+#endif
+
     if (name.find("quantizer_") == 0) {
         if (DC(IndexIVF)) {
             std::string sub_name = name.substr(strlen("quantizer_"));

data/vendor/faiss/faiss/Clustering.cpp

@@ -11,6 +11,7 @@
 #include <faiss/VectorTransform.h>
 #include <faiss/impl/AuxIndexStructures.h>
 
+#include <algorithm>
 #include <cinttypes>
 #include <cmath>
 #include <cstdio>
@@ -63,6 +64,47 @@ void Clustering::train_encoded(
         const Index* codec,
         Index& index,
         const float* weights) {
+    train_impl(nx, x_in, codec, NumericType::Float32, index, weights);
+}
+
+void Clustering::train_ex(
+        idx_t nx,
+        const void* x_in,
+        NumericType numeric_type,
+        Index& index,
+        const float* weights) {
+    if (numeric_type == NumericType::Float32) {
+        train(nx, static_cast<const float*>(x_in), index, weights);
+        return;
+    }
+    FAISS_THROW_IF_NOT_MSG(
+            numeric_type == NumericType::Float16,
+            "Clustering::train_ex: unsupported numeric type");
+    train_impl(
+            nx,
+            static_cast<const uint8_t*>(x_in),
+            nullptr,
+            numeric_type,
+            index,
+            weights);
+}
+
+void Clustering::train_impl(
+        idx_t nx,
+        const uint8_t* x_in,
+        const Index* codec,
+        NumericType numeric_type,
+        Index& index,
+        const float* weights) {
+    FAISS_THROW_IF_NOT_MSG(
+            codec || numeric_type == NumericType::Float32 ||
+                    numeric_type == NumericType::Float16,
+            "unsupported numeric type for clustering");
+    // packed IEEE binary16 rows, consumed without a codec
+    const bool fp16 = !codec && numeric_type == NumericType::Float16;
+    // rows that are not fp32 are widened by blocks for the assignment index
+    const bool encoded = codec || fp16;
+
     FAISS_THROW_IF_NOT_FMT(
             nx >= static_cast<idx_t>(k),
             "Number of training points (%" PRId64
@@ -70,6 +112,7 @@ void Clustering::train_encoded(
             "as large as number of clusters (%zd)",
             nx,
             k);
+    FAISS_THROW_IF_NOT_MSG(x_in, "training data must not be null");
 
     FAISS_THROW_IF_NOT_FMT(
             (!codec || static_cast<size_t>(codec->d) == d),
@@ -83,23 +126,46 @@ void Clustering::train_encoded(
             int(index.d),
             int(d));
 
+    FAISS_THROW_IF_NOT_MSG(
+            !encoded || decode_block_size > 0,
+            "decode_block_size must be positive");
+
     double t0 = getmillisecs();
 
     if (!codec && check_input_data_for_NaNs) {
         // Check for NaNs in input data. Normally it is the user's
-        // responsibility, but it may spare us some hard-to-debug
-        // reports.
-        const float* x = reinterpret_cast<const float*>(x_in);
-        for (size_t i = 0; i < nx * d; i++) {
+        // responsibility, but it may spare us some hard-to-debug reports.
+        if (fp16) {
             FAISS_THROW_IF_NOT_MSG(
-                    std::isfinite(x[i]), "input contains NaN's or Inf's");
+                    detail::fp16_all_finite(
+                            nx * d, reinterpret_cast<const uint16_t*>(x_in)),
+                    "input contains NaN's or Inf's");
+        } else {
+            const float* x = reinterpret_cast<const float*>(x_in);
+            for (size_t i = 0; i < nx * d; i++) {
+                FAISS_THROW_IF_NOT_MSG(
+                        std::isfinite(x[i]), "input contains NaN's or Inf's");
+            }
         }
     }
 
     const uint8_t* x = x_in;
     std::unique_ptr<uint8_t[]> del1;
     std::unique_ptr<float[]> del3;
-    size_t line_size = codec ? codec->sa_code_size() : sizeof(float) * d;
+    size_t line_size = codec ? codec->sa_code_size()
+            : fp16           ? sizeof(uint16_t) * d
+                             : sizeof(float) * d;
+
+    // widen n consecutive training rows to fp32
+    auto decode_rows = [&](size_t n, const uint8_t* rows, float* out) {
+        if (codec) {
+            codec->sa_decode(n, rows, out);
+        } else if (fp16) {
+            fp16_to_fp32(n * d, reinterpret_cast<const uint16_t*>(rows), out);
+        } else {
+            memcpy(out, rows, n * line_size);
+        }
+    };
 
     if (static_cast<size_t>(nx) > k * max_points_per_centroid) {
         uint8_t* x_new;
@@ -129,11 +195,7 @@ void Clustering::train_encoded(
                    nx);
         }
         centroids.resize(d * k);
-        if (!codec) {
-            memcpy(centroids.data(), x_in, sizeof(float) * d * k);
-        } else {
-            codec->sa_decode(nx, x_in, centroids.data());
-        }
+        decode_rows(k, x_in, centroids.data());
 
         // one fake iteration...
         ClusteringIterationStats stats = {0.0, 0.0, 0.0, 1.0, 0};
@@ -153,9 +215,8 @@ void Clustering::train_encoded(
                k,
                nredo,
                niter);
-        if (codec) {
-            printf("Input data encoded in %zd bytes per vector\n",
-                   codec->sa_code_size());
+        if (encoded) {
+            printf("Input data encoded in %zd bytes per vector\n", line_size);
         }
     }
 
@@ -191,8 +252,10 @@ void Clustering::train_encoded(
     // initialize seed
     const uint64_t actual_seed = detail::get_actual_rng_seed(seed);
 
-    // temporary buffer to decode vectors during the optimization
-    std::vector<float> decode_buffer(codec ? d * decode_block_size : 0);
+    // temporary buffer to decode codec-encoded vectors during the optimization
+    std::vector<float> decode_buffer(
+            codec ? d * std::min(static_cast<size_t>(nx), decode_block_size)
+                  : 0);
 
     for (int redo = 0; redo < nredo; redo++) {
         if (verbose && nredo > 1) {
@@ -210,41 +273,44 @@ void Clustering::train_encoded(
                 std::vector<int> perm(nx);
                 rand_perm(perm.data(), nx, actual_seed + 1 + redo * 15486557L);
                 for (size_t i = 0; i < k_to_init; i++) {
-                    if (!codec) {
-                        memcpy(centroids.data() + (n_input_centroids + i) * d,
-                               x + perm[n_input_centroids + i] * line_size,
-                               line_size);
-                    } else {
-                        codec->sa_decode(
-                                1,
-                                x + perm[n_input_centroids + i] * line_size,
-                                centroids.data() + (n_input_centroids + i) * d);
-                    }
+                    decode_rows(
+                            1,
+                            x + perm[n_input_centroids + i] * line_size,
+                            centroids.data() + (n_input_centroids + i) * d);
                 }
             } else {
-                // For k-means++ and AFK-MC², we need all vectors decoded
-                const float* x_float = nullptr;
-                std::vector<float> x_decoded;
-
-                if (!codec) {
-                    x_float = reinterpret_cast<const float*>(x);
-                } else {
-                    // Decode all vectors for initialization
-                    x_decoded.resize(nx * d);
-                    codec->sa_decode(nx, x, x_decoded.data());
-                    x_float = x_decoded.data();
-                }
-
                 ClusteringInitialization initializer(d, k_to_init);
                 initializer.method = init_method;
                 initializer.seed = actual_seed + 1 + redo * 15486557L;
                 initializer.afkmc2_chain_length = afkmc2_chain_length;
-                initializer.init_centroids(
-                        nx,
-                        x_float,
-                        centroids.data() + n_input_centroids * d,
-                        n_input_centroids,
-                        n_input_centroids > 0 ? centroids.data() : nullptr);
+
+                if (fp16) {
+                    detail::init_centroids_fp16(
+                            initializer,
+                            nx,
+                            reinterpret_cast<const uint16_t*>(x),
+                            centroids.data() + n_input_centroids * d,
+                            n_input_centroids,
+                            n_input_centroids > 0 ? centroids.data() : nullptr);
+                } else {
+                    const float* x_float = nullptr;
+                    std::vector<float> x_decoded;
+
+                    if (!encoded) {
+                        x_float = reinterpret_cast<const float*>(x);
+                    } else {
+                        x_decoded.resize(nx * d);
+                        decode_rows(nx, x, x_decoded.data());
+                        x_float = x_decoded.data();
+                    }
+
+                    initializer.init_centroids(
+                            nx,
+                            x_float,
+                            centroids.data() + n_input_centroids * d,
+                            n_input_centroids,
+                            n_input_centroids > 0 ? centroids.data() : nullptr);
+                }
             }
         }
 
@@ -268,7 +334,7 @@ void Clustering::train_encoded(
         for (int i = 0; i < niter; i++) {
             double t0s = getmillisecs();
 
-            if (!codec) {
+            if (!encoded) {
                 index.search(
                         nx,
                         reinterpret_cast<const float*>(x),
@@ -277,15 +343,26 @@ void Clustering::train_encoded(
                         assign.get());
             } else {
                 // search by blocks of decode_block_size vectors
-                size_t code_size = codec->sa_code_size();
                 for (size_t i0 = 0; i0 < static_cast<size_t>(nx);
                      i0 += decode_block_size) {
                     size_t i1 = i0 + decode_block_size;
                     if (i1 > static_cast<size_t>(nx)) {
                         i1 = nx;
                     }
-                    codec->sa_decode(
-                            i1 - i0, x + code_size * i0, decode_buffer.data());
+                    if (fp16) {
+                        // the index consumes fp16 queries itself (natively
+                        // if it can, see Index::search_ex)
+                        index.search_ex(
+                                i1 - i0,
+                                x + line_size * i0,
+                                NumericType::Float16,
+                                1,
+                                dis.get() + i0,
+                                assign.get() + i0);
+                        continue;
+                    }
+                    decode_rows(
+                            i1 - i0, x + line_size * i0, decode_buffer.data());
                     index.search(
                             i1 - i0,
                             decode_buffer.data(),
@@ -308,17 +385,30 @@ void Clustering::train_encoded(
             std::vector<float> hassign(k);
 
             size_t k_frozen = frozen_centroids ? n_input_centroids : 0;
-            detail::compute_centroids(
-                    d,
-                    k,
-                    nx,
-                    k_frozen,
-                    x,
-                    codec,
-                    assign.get(),
-                    weights,
-                    hassign.data(),
-                    centroids.data());
+            if (fp16) {
+                detail::compute_centroids_fp16(
+                        d,
+                        k,
+                        nx,
+                        k_frozen,
+                        reinterpret_cast<const uint16_t*>(x),
+                        assign.get(),
+                        weights,
+                        hassign.data(),
+                        centroids.data());
+            } else {
+                detail::compute_centroids(
+                        d,
+                        k,
+                        nx,
+                        k_frozen,
+                        x,
+                        codec,
+                        assign.get(),
+                        weights,
+                        hassign.data(),
+                        centroids.data());
+            }
 
             int nsplit = detail::split_clusters(
                     d, k, nx, k_frozen, hassign.data(), centroids.data());

data/vendor/faiss/faiss/Clustering.h

@@ -148,11 +148,40 @@ struct Clustering : ClusteringParameters {
             Index& index,
             const float* weights = nullptr);
 
+    /** run k-means on vectors of the given numeric type
+     *
+     * Float32 is the same as train(). Float16 takes packed IEEE binary16
+     * vectors (n * d uint16_t) and runs k-means natively on them: the NaN
+     * check, subsampling, initialization and centroid updates read the fp16
+     * rows directly, and the assignment step passes blocks of at most
+     * decode_block_size fp16 rows to index.search_ex(Float16). Indexes with a
+     * native fp16 search consume them directly; the Index::search_ex default
+     * widens them block by block. There is no fp32 copy of the training set,
+     * unless init_method needs one. Centroids are fp32.
+     */
+    void train_ex(
+            idx_t n,
+            const void* x,
+            NumericType numeric_type,
+            Index& index,
+            const float* weights = nullptr);
+
     /// Post-process the centroids after each centroid update.
     /// includes optional L2 normalization and nearest integer rounding
     void post_process_centroids();
 
     virtual ~Clustering() {}
+
+   protected:
+    /// k-means on rows encoded by `codec` or, if codec is null, stored as
+    /// `numeric_type` (Float32 or Float16)
+    void train_impl(
+            idx_t nx,
+            const uint8_t* x_in,
+            const Index* codec,
+            NumericType numeric_type,
+            Index& index,
+            const float* weights);
 };
 
 /** Exact 1D clustering algorithm