faiss 0.6.2 → 0.6.4

data/vendor/faiss/faiss/SuperKMeans.h

@@ -13,8 +13,9 @@
 //   "A Super Fast K-means for Indexing Vector Embeddings."
 //   arXiv preprint arXiv:2603.20009.
 //
-// Use when: L2 metric, k >= 1024, d >= 128, dense float embeddings.
-// Do not use for: IP/cosine (use Clustering with cp.spherical=true), small k,
+// Use when: L2 metric, or spherical inner-product clustering with
+// cp.spherical=true, k >= 1024, d >= 128, dense float embeddings.
+// Do not use for: small k,
 // binary data (use IndexBinaryIVF), or near-unit-sphere embeddings with
 // k < 4096 (chi-squared assumption breaks down).
 //
@@ -23,6 +24,7 @@
 
 #pragma once
 
+#include <cstdint>
 #include <vector>
 
 #include <faiss/Clustering.h>
@@ -94,4 +96,33 @@ struct SuperKMeans {
     void train(idx_t n, const float* x);
 };
 
+/// Reusable scratch for super_kmeans_assign_iteration; pass one instance across
+/// a loop of calls to avoid reallocating (buffers grow only as needed).
+struct SuperKMeansAssignScratch {
+    std::vector<float> Y_trail; // (k, d_trail) row-major, input to pdxify
+    std::vector<float> Y_pdx;   // PDX-laid-out trailing block
+    std::vector<float> x_norms_partial; // ||X[i, 0:d_prime]||^2
+    std::vector<float> y_norms_partial; // ||Y[j, 0:d_prime]||^2
+    std::vector<float> partial_ip;      // partial-GEMM tile buffer
+};
+
+/// One SuperKMeans iter-1+ assignment pass: partial GEMM over the front
+/// `d_prime` dims + ADSampling progressive pruning over the PDX-laid-out
+/// trailing block. Updates `tau` and `assignments` in place.
+void super_kmeans_assign_iteration(
+        const float* X_tilde, // (n, d) points, row-major, rotated space
+        int n,
+        int d,
+        const float* Y_tilde, // (k, d) centroids, row-major, rotated space
+        int k,
+        float* tau, // in/out, len n; entry = exact full-d L2 to assignment
+        int32_t* assignments,  // in/out, len n
+        int d_prime,           // GEMM/pruning split, 1 <= d_prime < d
+        const float* ad_coeff, // ADSampling threshold table, len d+1
+        const SuperKMeansParameters& cp,
+        int64_t* total_pairs = nullptr,    // optional out-counter
+        int64_t* pruned_at_gemm = nullptr, // optional out-counter
+        SuperKMeansAssignScratch* scratch =
+                nullptr); // optional, reuse across calls
+
 } // namespace faiss

data/vendor/faiss/faiss/VectorTransform.cpp

@@ -47,6 +47,19 @@ int sgemm_(
         float* c,
         FINTEGER* ldc);
 
+int sgemv_(
+        const char* trans,
+        FINTEGER* m,
+        FINTEGER* n,
+        float* alpha,
+        const float* a,
+        FINTEGER* lda,
+        const float* x,
+        FINTEGER* incx,
+        float* beta,
+        float* y,
+        FINTEGER* incy);
+
 int dgemm_(
         const char* transa,
         const char* transb,
@@ -192,6 +205,25 @@ void LinearTransform::apply_noalloc(idx_t n, const float* x, float* xt) const {
 
     float one = 1;
     FINTEGER nbiti = d_out, ni = static_cast<FINTEGER>(n), di = d_in;
+    if (n == 1) {
+        FINTEGER onei = 1;
+        // Avoid GEMM packing overhead for single-vector transforms. GEMV is
+        // mathematically equivalent but may not be bit-exact with GEMM because
+        // BLAS implementations can use different accumulation orders.
+        sgemv_("Transposed",
+               &di,
+               &nbiti,
+               &one,
+               A.data(),
+               &di,
+               x,
+               &onei,
+               &c_factor,
+               xt,
+               &onei);
+        return;
+    }
+
     sgemm_("Transposed",
            "Not transposed",
            &nbiti,
@@ -481,6 +513,44 @@ void HadamardRotation::apply_noalloc(idx_t n, const float* x, float* xt) const {
     }
 }
 
+void HadamardRotation::reverse_transform(idx_t n, const float* xt, float* x)
+        const {
+    FAISS_THROW_IF_NOT_MSG(is_trained, "Transformation not trained yet");
+    FAISS_THROW_IF_NOT_MSG(
+            d_in == d_out,
+            "HadamardRotation inverse requires equal input/output dimensions");
+
+    const size_t p = d_out;
+    // Reverse of apply_noalloc: three unnormalized FWHT rounds scale norms
+    // by (sqrt(p))^3 = p*sqrt(p); the forward pass cancels this with
+    // total_scale = 1/(p*sqrt(p)), so the inverse applies the same factor.
+    const float inverse_scale = 1.0f / (p * std::sqrt(static_cast<float>(p)));
+
+#pragma omp parallel for schedule(dynamic)
+    for (idx_t i = 0; i < n; i++) {
+        const float* xi = xt + i * p;
+        float* xo = x + i * p;
+
+        // The inverse reverses the three sign-flip/Hadamard factors.
+        std::memcpy(xo, xi, p * sizeof(float));
+        fwht_inplace(xo, p);
+
+        for (size_t j = 0; j < p; j++) {
+            xo[j] *= signs3[j];
+        }
+        fwht_inplace(xo, p);
+
+        for (size_t j = 0; j < p; j++) {
+            xo[j] *= signs2[j];
+        }
+        fwht_inplace(xo, p);
+
+        for (size_t j = 0; j < p; j++) {
+            xo[j] *= signs1[j] * inverse_scale;
+        }
+    }
+}
+
 void HadamardRotation::check_identical(const VectorTransform& other) const {
     auto* hr = dynamic_cast<const HadamardRotation*>(&other);
     FAISS_THROW_IF_NOT_MSG(hr, "failed to cast to HadamardRotation");
@@ -1064,8 +1134,7 @@ ITQTransform::ITQTransform(int din, int dout, bool do_pca_in)
 }
 
 void ITQTransform::train(idx_t n, const float* x_in) {
-    FAISS_THROW_IF_NOT_MSG(
-            !is_trained, "ITQTransform has already been trained");
+    FAISS_THROW_IF_MSG(is_trained, "ITQTransform has already been trained");
 
     size_t max_train_points = std::max(d_in * max_train_per_dim, 32768);
     const float* x =

data/vendor/faiss/faiss/VectorTransform.h

@@ -144,6 +144,9 @@ struct HadamardRotation : VectorTransform {
 
     void apply_noalloc(idx_t n, const float* x, float* xt) const override;
 
+    /// Apply the inverse transform when d_in == d_out.
+    void reverse_transform(idx_t n, const float* xt, float* x) const override;
+
     void check_identical(const VectorTransform& other) const override;
 
     HadamardRotation() {}

data/vendor/faiss/faiss/clone_index.cpp

@@ -18,10 +18,12 @@
 #include <faiss/IndexBinaryFlat.h>
 #include <faiss/IndexBinaryHNSW.h>
 #include <faiss/IndexBinaryIVF.h>
+#include <faiss/IndexEDEN.h>
 #include <faiss/IndexFlat.h>
 #include <faiss/IndexHNSW.h>
 #include <faiss/IndexIVF.h>
 #include <faiss/IndexIVFAdditiveQuantizerFastScan.h>
+#include <faiss/IndexIVFEDEN.h>
 #include <faiss/IndexIVFFlat.h>
 #include <faiss/IndexIVFFlatPanorama.h>
 #include <faiss/IndexIVFPQ.h>
@@ -36,6 +38,7 @@
 #include <faiss/IndexPQ.h>
 #include <faiss/IndexPQFastScan.h>
 #include <faiss/IndexPreTransform.h>
+#include <faiss/IndexRaBitQ.h>
 #include <faiss/IndexRefine.h>
 #include <faiss/IndexRowwiseMinMax.h>
 #include <faiss/IndexScalarQuantizer.h>
@@ -77,6 +80,7 @@ VectorTransform* Cloner::clone_VectorTransform(const VectorTransform* vt) {
     TRYCLONE(PCAMatrix, vt)
     TRYCLONE(ITQMatrix, vt)
     TRYCLONE(RandomRotationMatrix, vt)
+    TRYCLONE(HadamardRotation, vt)
     TRYCLONE(LinearTransform, vt) {
         FAISS_THROW_MSG("clone not supported for this type of VectorTransform");
     }
@@ -98,6 +102,7 @@ IndexIVF* Cloner::clone_IndexIVF(const IndexIVF* ivf) {
     TRYCLONE(IndexIVFResidualQuantizerFastScan, ivf)
     TRYCLONE(IndexIVFPQFastScan, ivf)
 
+    TRYCLONE(IndexIVFEDEN, ivf)
     TRYCLONE(IndexIVFRaBitQFastScan, ivf)
     TRYCLONE(IndexIVFRaBitQ, ivf)
 
@@ -135,6 +140,7 @@ IndexIDMap* clone_IndexIDMap(const IndexIDMap* im) {
 IndexHNSW* clone_IndexHNSW(const IndexHNSW* ihnsw) {
     TRYCLONE(IndexHNSW2Level, ihnsw)
     TRYCLONE(IndexHNSWFlatPanorama, ihnsw)
+    TRYCLONE(IndexHNSWRaBitQ, ihnsw)
     TRYCLONE(IndexHNSWFlat, ihnsw)
     TRYCLONE(IndexHNSWPQ, ihnsw)
     TRYCLONE(IndexHNSWSQ, ihnsw)
@@ -287,8 +293,10 @@ Index* Cloner::clone_Index(const Index* index) {
     TRYCLONE(IndexLattice, index)
     TRYCLONE(IndexRandom, index)
     TRYCLONE(IndexPQFastScan, index)
+    TRYCLONE(IndexEDEN, index)
 
     TRYCLONE(IndexScalarQuantizer, index)
+    TRYCLONE(IndexRaBitQ, index)
     TRYCLONE(MultiIndexQuantizer, index)
 
     if (const IndexIVF* ivf = dynamic_cast<const IndexIVF*>(index)) {

data/vendor/faiss/faiss/factory_tools.cpp

@@ -14,8 +14,10 @@
 #include <faiss/IndexBinaryFlat.h>
 #include <faiss/IndexBinaryHNSW.h>
 #include <faiss/IndexBinaryIVF.h>
+#include <faiss/IndexEDEN.h>
 #include <faiss/IndexHNSW.h>
 #include <faiss/IndexIDMap.h>
+#include <faiss/IndexIVFEDEN.h>
 #include <faiss/IndexIVFFlat.h>
 #include <faiss/IndexIVFPQFastScan.h>
 #include <faiss/IndexIVFRaBitQ.h>
@@ -33,11 +35,17 @@ namespace {
 const std::map<faiss::ScalarQuantizer::QuantizerType, std::string> sq_types = {
         {faiss::ScalarQuantizer::QT_8bit, "SQ8"},
         {faiss::ScalarQuantizer::QT_4bit, "SQ4"},
+        // QT_8bit_uniform and QT_4bit_uniform have no round-trippable
+        // index_factory string; the names below are synthetic identifiers used
+        // for telemetry logging only.
+        {faiss::ScalarQuantizer::QT_8bit_uniform, "SQ8u"},
+        {faiss::ScalarQuantizer::QT_4bit_uniform, "SQ4u"},
         {faiss::ScalarQuantizer::QT_6bit, "SQ6"},
         {faiss::ScalarQuantizer::QT_fp16, "SQfp16"},
         {faiss::ScalarQuantizer::QT_bf16, "SQbf16"},
         {faiss::ScalarQuantizer::QT_8bit_direct_signed, "SQ8_direct_signed"},
         {faiss::ScalarQuantizer::QT_8bit_direct, "SQ8_direct"},
+        {faiss::ScalarQuantizer::QT_0bit, "SQ0"},
         {faiss::ScalarQuantizer::QT_1bit_tqmse, "SQtqmse1"},
         {faiss::ScalarQuantizer::QT_2bit_tqmse, "SQtqmse2"},
         {faiss::ScalarQuantizer::QT_3bit_tqmse, "SQtqmse3"},
@@ -65,6 +73,19 @@ int get_hnsw_M(const faiss::IndexBinaryHNSW* index) {
     return 0;
 }
 
+std::string eden_factory_string(
+        const faiss::ScalarQuantizer& sq,
+        faiss::EDENScaleType scale_type) {
+    std::string result = "EDEN";
+    if (sq.bits != 1) {
+        result += std::to_string(sq.bits);
+    }
+    if (scale_type == faiss::EDENScaleType_BIASED) {
+        result += "BIASED";
+    }
+    return result;
+}
+
 } // namespace
 
 // Reference for reverse_index_factory:
@@ -114,8 +135,17 @@ std::string reverse_index_factory(const faiss::Index* index) {
                                 ivf_index)) {
             return prefix + ",PQ" + std::to_string(ivfpqfs_index->pq.M) + "x" +
                     std::to_string(ivfpqfs_index->pq.nbits) + "fs";
-        } else if (dynamic_cast<const faiss::IndexIVFRaBitQ*>(ivf_index)) {
-            return prefix + ",RaBitQ";
+        } else if (
+                const faiss::IndexIVFRaBitQ* ivfrabitq_index =
+                        dynamic_cast<const faiss::IndexIVFRaBitQ*>(ivf_index)) {
+            size_t nb_bits = ivfrabitq_index->rabitq.nb_bits;
+            return prefix + ",RaBitQ" +
+                    (nb_bits == 1 ? "" : std::to_string(nb_bits));
+        } else if (
+                const faiss::IndexIVFEDEN* ivf_eden =
+                        dynamic_cast<const faiss::IndexIVFEDEN*>(ivf_index)) {
+            return prefix + "," +
+                    eden_factory_string(ivf_eden->sq, ivf_eden->scale_type);
         }
     } else if (
             const faiss::IndexPreTransform* pretransform_index =
@@ -184,12 +214,25 @@ std::string reverse_index_factory(const faiss::Index* index) {
             const faiss::IndexScalarQuantizer* sq_index =
                     dynamic_cast<const faiss::IndexScalarQuantizer*>(index)) {
         return sq_types.at(sq_index->sq.qtype);
+    } else if (
+            // IndexIDMap2 inherits IndexIDMap — check subclass first.
+            const faiss::IndexIDMap2* idmap2 =
+                    dynamic_cast<const faiss::IndexIDMap2*>(index)) {
+        return std::string("IDMap2,") + reverse_index_factory(idmap2->index);
     } else if (
             const faiss::IndexIDMap* idmap =
                     dynamic_cast<const faiss::IndexIDMap*>(index)) {
         return std::string("IDMap,") + reverse_index_factory(idmap->index);
-    } else if (dynamic_cast<const faiss::IndexRaBitQ*>(index)) {
-        return "RaBitQ";
+    } else if (
+            const faiss::IndexRaBitQ* rabitq_index =
+                    dynamic_cast<const faiss::IndexRaBitQ*>(index)) {
+        size_t nb_bits = rabitq_index->rabitq.nb_bits;
+        return "RaBitQ" +
+                (nb_bits == 1 ? std::string() : std::to_string(nb_bits));
+    } else if (
+            const faiss::IndexEDEN* eden =
+                    dynamic_cast<const faiss::IndexEDEN*>(index)) {
+        return eden_factory_string(eden->sq, eden->scale_type);
     }
     // Avoid runtime error, just return empty string for logging.
     return "";

data/vendor/faiss/faiss/gpu/GpuCloner.cpp

@@ -14,7 +14,7 @@
 
 #include <faiss/IndexBinaryFlat.h>
 #include <faiss/IndexFlat.h>
-#if defined USE_NVIDIA_CUVS
+#if defined(USE_NVIDIA_CUVS) && !defined(FAISS_CUVS_NO_CAGRA)
 #include <faiss/IndexBinaryHNSW.h>
 #include <faiss/IndexHNSW.h>
 #endif
@@ -28,7 +28,7 @@
 #include <faiss/MetaIndexes.h>
 #include <faiss/gpu/GpuIndex.h>
 #include <faiss/gpu/GpuIndexBinaryFlat.h>
-#if defined USE_NVIDIA_CUVS
+#if defined(USE_NVIDIA_CUVS) && !defined(FAISS_CUVS_NO_CAGRA)
 #include <faiss/gpu/GpuIndexBinaryCagra.h>
 #include <faiss/gpu/GpuIndexCagra.h>
 #endif
@@ -92,7 +92,7 @@ Index* ToCPUCloner::clone_Index(const Index* index) {
         // (inverse op of ToGpuClonerMultiple)
 
     }
-#if defined USE_NVIDIA_CUVS
+#if defined(USE_NVIDIA_CUVS) && !defined(FAISS_CUVS_NO_CAGRA)
     else if (auto icg = dynamic_cast<const GpuIndexCagra*>(index)) {
         IndexHNSWCagra* res = new IndexHNSWCagra();
         if (icg->get_numeric_type() != faiss::NumericType::Float32) {
@@ -150,8 +150,8 @@ Index* ToGpuCloner::clone_Index(const Index* index) {
         GpuIndexFlatConfig config;
         config.device = device;
         config.useFloat16 = true;
-        FAISS_THROW_IF_NOT_MSG(
-                !use_cuvs, "this type of index is not implemented for cuVS");
+        FAISS_THROW_IF_MSG(
+                use_cuvs, "this type of index is not implemented for cuVS");
         GpuIndexFlat* gif = new GpuIndexFlat(
                 provider, index->d, index->metric_type, config);
         // transfer data by blocks
@@ -187,8 +187,8 @@ Index* ToGpuCloner::clone_Index(const Index* index) {
         config.device = device;
         config.indicesOptions = indicesOptions;
         config.flatConfig.useFloat16 = useFloat16CoarseQuantizer;
-        FAISS_THROW_IF_NOT_MSG(
-                !use_cuvs, "this type of index is not implemented for cuVS");
+        config.use_cuvs = use_cuvs;
+        config.allowCpuCoarseQuantizer = allowCpuCoarseQuantizer;
 
         GpuIndexIVFScalarQuantizer* res = new GpuIndexIVFScalarQuantizer(
                 provider,
@@ -233,7 +233,7 @@ Index* ToGpuCloner::clone_Index(const Index* index) {
 
         return res;
     }
-#if defined USE_NVIDIA_CUVS
+#if defined(USE_NVIDIA_CUVS) && !defined(FAISS_CUVS_NO_CAGRA)
     else if (auto icg = dynamic_cast<const faiss::IndexHNSWCagra*>(index)) {
         GpuIndexCagraConfig config;
         config.device = device;
@@ -533,7 +533,7 @@ faiss::IndexBinary* index_binary_gpu_to_cpu(
         ii->copyTo(ret);
         return ret;
     }
-#if defined USE_NVIDIA_CUVS
+#if defined(USE_NVIDIA_CUVS) && !defined(FAISS_CUVS_NO_CAGRA)
     else if (auto ii = dynamic_cast<const GpuIndexBinaryCagra*>(gpu_index)) {
         IndexBinaryHNSWCagra* ret = new IndexBinaryHNSWCagra();
         ii->copyTo(ret);
@@ -549,13 +549,13 @@ faiss::IndexBinary* index_binary_cpu_to_gpu(
         GpuResourcesProvider* provider,
         int device,
         const faiss::IndexBinary* index,
-        const GpuClonerOptions* options) {
+        const GpuClonerOptions* /*options*/) {
     if (auto ii = dynamic_cast<const IndexBinaryFlat*>(index)) {
         GpuIndexBinaryFlatConfig config;
         config.device = device;
         return new GpuIndexBinaryFlat(provider, ii, config);
     }
-#if defined USE_NVIDIA_CUVS
+#if defined(USE_NVIDIA_CUVS) && !defined(FAISS_CUVS_NO_CAGRA)
     else if (
             auto ii = dynamic_cast<const faiss::IndexBinaryHNSWCagra*>(index)) {
         GpuIndexCagraConfig config;

data/vendor/faiss/faiss/gpu/GpuClonerOptions.h

@@ -39,12 +39,8 @@ struct GpuClonerOptions {
     /// Set verbose options on the index
     bool verbose = false;
 
-    /// use the cuVS implementation
-#if defined USE_NVIDIA_CUVS
-    bool use_cuvs = true;
-#else
+    /// Use the cuVS implementation. Opt-in: see GpuIndexConfig::use_cuvs.
     bool use_cuvs = false;
-#endif
 
     /// This flag controls the CPU fallback logic for coarse quantizer
     /// component of the index. When set to false (default), the cloner will

data/vendor/faiss/faiss/gpu/GpuDistance.h

@@ -107,12 +107,9 @@ struct GpuDistanceParams {
     /// execution
     int device = -1;
 
-    /// Should the index dispatch down to cuVS?
-#if defined USE_NVIDIA_CUVS
-    bool use_cuvs = true;
-#else
+    /// Should the search dispatch down to cuVS? Opt-in: see
+    /// GpuIndexConfig::use_cuvs.
     bool use_cuvs = false;
-#endif
 };
 
 /// A function that determines whether cuVS should be used based on various

data/vendor/faiss/faiss/gpu/GpuIndex.h

@@ -38,12 +38,11 @@ struct GpuIndexConfig {
     /// more memory than is available on the GPU.
     MemorySpace memorySpace = MemorySpace::Device;
 
-    /// Should the index dispatch down to cuVS?
-#if defined USE_NVIDIA_CUVS
-    bool use_cuvs = true;
-#else
+    /// Should the index dispatch down to cuVS? Opt-in: dispatching to cuVS
+    /// selects a different implementation with its own numerical behaviour, so
+    /// it must be an explicit choice by the caller rather than a consequence of
+    /// how the binary happened to be built.
     bool use_cuvs = false;
-#endif
 };
 
 /// A centralized function that determines whether cuVS should
@@ -177,6 +176,33 @@ class GpuIndex : public faiss::Index {
         }
     };
 
+    virtual void addImplPrecomputed_(
+            idx_t n,
+            const float* x,
+            const idx_t* ids,
+            const idx_t* precomputed_idx);
+
+    virtual void addImplPrecomputed_ex_(
+            idx_t n,
+            const void* x,
+            NumericType numeric_type,
+            const idx_t* ids,
+            const idx_t* precomputed_idx);
+
+    /// Handles paged adds if the add set is too large, passes to
+    /// addImpl_ to actually perform the add for the current page
+    void addPaged_(
+            idx_t n,
+            const float* x,
+            const idx_t* ids,
+            const idx_t* precomputed_idx = nullptr);
+    void addPaged_ex_(
+            idx_t n,
+            const void* x,
+            NumericType numeric_type,
+            const idx_t* ids,
+            const idx_t* precomputed_idx = nullptr);
+
     /// Overridden to actually perform the search
     /// All data is guaranteed to be resident on our device
     virtual void searchImpl_(
@@ -209,22 +235,18 @@ class GpuIndex : public faiss::Index {
     }
 
    private:
-    /// Handles paged adds if the add set is too large, passes to
-    /// addImpl_ to actually perform the add for the current page
-    void addPaged_(idx_t n, const float* x, const idx_t* ids);
-    void addPaged_ex_(
-            idx_t n,
-            const void* x,
-            NumericType numeric_type,
-            const idx_t* ids);
-
     /// Calls addImpl_ for a single page of GPU-resident data
-    void addPage_(idx_t n, const float* x, const idx_t* ids);
+    void addPage_(
+            idx_t n,
+            const float* x,
+            const idx_t* ids,
+            const idx_t* precomputed_idx = nullptr);
     void addPage_ex_(
             idx_t n,
             const void* x,
             NumericType numeric_type,
-            const idx_t* ids);
+            const idx_t* ids,
+            const idx_t* precomputed_idx = nullptr);
 
     /// Calls searchImpl_ for a single page of GPU-resident data
     void searchNonPaged_(

data/vendor/faiss/faiss/gpu/GpuIndexCagra.h

@@ -47,7 +47,9 @@ enum class graph_build_algo {
     /// Use NN-Descent to build all-neighbors knn graph
     NN_DESCENT,
     /// Use iterative search to build knn graph
-    ITERATIVE_SEARCH
+    ITERATIVE_SEARCH,
+    /// Exact knn graph via tiled brute force
+    BRUTE_FORCE
 };
 
 /// A type for specifying how PQ codebooks are created.
@@ -173,6 +175,34 @@ struct IVFPQSearchCagraConfig {
     uint32_t max_internal_batch_size = 4096;
 };
 
+/// Knobs for the multi-GPU build path, selected by listing more than one
+/// device in GpuIndexCagraConfig::devices. Degrees, build_algo and metric
+/// still come from GpuIndexCagraConfig.
+struct AllNeighborsCagraConfig {
+    /// Number of overlapping clusters the dataset is partitioned into.
+    /// 0 selects max(2 * number of devices, 4).
+    size_t n_clusters = 0;
+
+    /// Clusters each vector is assigned to. Must be >= 2: with 1 there are no
+    /// cross-cluster edges and recall collapses. 0 selects 2.
+    size_t overlap_factor = 2;
+
+    /// Bounds IVF-PQ search memory during the knn build. cuVS's default can
+    /// exhaust device memory around 100M vectors; 8192 avoids that and does
+    /// not change recall. 0 keeps cuVS's default.
+    uint32_t ivf_pq_search_batch_size = 0;
+
+    /// IVF-PQ refinement multiplier. The refine pass runs on the CPU, so cost
+    /// scales with this. Raising it above 1.0 measured both slower and less
+    /// accurate, so it is separate from the shared refine_rate.
+    float refinement_rate = 1.0f;
+
+    /// Size the IVF-PQ index for one cluster rather than the whole dataset.
+    /// cuVS reuses these params for every cluster without rescaling, so
+    /// sizing from the full dataset badly over-partitions each one.
+    bool ivf_pq_size_from_cluster = true;
+};
+
 struct GpuIndexCagraConfig : public GpuIndexConfig {
     /// Degree of input graph for pruning.
     size_t intermediate_graph_degree = 128;
@@ -190,6 +220,27 @@ struct GpuIndexCagraConfig : public GpuIndexConfig {
 
     /// Whether to use MST optimization to guarantee graph connectivity.
     bool guarantee_connectivity = false;
+
+    /// Devices to build on. More than one selects the multi-GPU build in
+    /// train(); see AllNeighborsCagraConfig and train() for its restrictions.
+    /// Empty or one device uses GpuIndexConfig::device as usual.
+    std::vector<int> devices;
+
+    AllNeighborsCagraConfig all_neighbors_params;
+
+    /// Build the HNSW upper levels on the GPU during copyTo() instead of by
+    /// CPU insertion. Roughly 10x faster, but measured worse recall than
+    /// base_level_only, which is cheaper still. Off by default.
+    bool gpu_hnsw_upper_levels = false;
+
+    /// intermediate_graph_degree for the per-level subgraph builds.
+    /// 0 = twice the upper-level degree.
+    size_t gpu_hnsw_intermediate_degree = 0;
+
+    /// MST connectivity pass on the per-level subgraphs. On by default:
+    /// upper levels are walked greedily with no backtracking, so a
+    /// disconnected component is a trap the descent cannot escape.
+    bool gpu_hnsw_guarantee_connectivity = true;
 };
 
 enum class search_algo {
@@ -317,6 +368,20 @@ struct GpuIndexCagra : public GpuIndex {
             idx_t* labels,
             const SearchParameters* search_params) const override;
 
+    /// Multi-GPU build path taken by train() when cagraConfig_.devices lists
+    /// more than one device: cuVS `all_neighbors` knn graph construction over
+    /// overlapping clusters, followed by graph pruning. Leaves the result in
+    /// merged_knngraph_ for copyTo(); index_ stays empty.
+    void trainAllNeighbors_(idx_t n, const float* x);
+
+    /// Populate HNSW levels >= 1 of `index` by building a CAGRA graph over
+    /// each level's node subset on the GPU. Requires the level table to be
+    /// prepared and the storage populated. Returns the max level.
+    void buildHnswUpperLevelsGpu_(faiss::IndexHNSWCagra* index, int max_lvl)
+            const;
+
+    void copyToMultiGpu_(faiss::IndexHNSWCagra* index) const;
+
     /// Our configuration options
     const GpuIndexCagraConfig cagraConfig_;
 
@@ -329,6 +394,11 @@ struct GpuIndexCagra : public GpuIndex {
             std::shared_ptr<CuvsCagra<half>>,
             std::shared_ptr<CuvsCagra<int8_t>>>
             index_;
+
+    /// Multi-GPU state: populated by trainAllNeighbors_(), used by copyTo()
+    std::vector<idx_t> merged_knngraph_;
+    idx_t merged_knngraph_degree_ = 0;
+    const float* multi_gpu_dataset_ = nullptr;
 };
 
 } // namespace gpu

data/vendor/faiss/faiss/gpu/GpuIndexIVF.h

@@ -98,6 +98,17 @@ class GpuIndexIVF : public GpuIndex, public IndexIVFInterface {
     /// debugging purposes.
     virtual std::vector<idx_t> getListIndices(idx_t listId) const;
 
+    /// Add vectors with precomputed IVF list assignments.
+    /// Same naming and argument order as IndexIVF::add_core.
+    /// `x`, `xids`, and `precomputed_idx` can be resident on the CPU or any
+    /// GPU; copies are performed as needed.
+    void add_core(
+            idx_t n,
+            const float* x,
+            const idx_t* xids,
+            const idx_t* precomputed_idx,
+            void* inverted_list_context = nullptr);
+
     void search_preassigned(
             idx_t n,
             const float* x,
@@ -133,6 +144,12 @@ class GpuIndexIVF : public GpuIndex, public IndexIVFInterface {
     /// Called from GpuIndex for add/add_with_ids
     void addImpl_(idx_t n, const float* x, const idx_t* ids) override;
 
+    void addImplPrecomputed_(
+            idx_t n,
+            const float* x,
+            const idx_t* xids,
+            const idx_t* precomputed_idx) override;
+
     /// Called from GpuIndex for search
     void searchImpl_(
             idx_t n,

data/vendor/faiss/faiss/gpu/GpuIndexIVFScalarQuantizer.h

@@ -93,6 +93,22 @@ class GpuIndexIVFScalarQuantizer : public GpuIndexIVF {
     /// Validates index SQ parameters
     void verifySQSettings_() const;
 
+    /// Whether this index configuration can use cuVS IVF-SQ
+    bool shouldUseCuvs_() const;
+
+    /// Construct the backing IVF implementation
+    void setIndex_(
+            GpuResources* resources,
+            int dim,
+            idx_t nlist,
+            faiss::MetricType metric,
+            float metricArg,
+            bool useResidual,
+            faiss::ScalarQuantizer* scalarQ,
+            bool interleavedLayout,
+            IndicesOptions indicesOptions,
+            MemorySpace space);
+
     /// Called from train to handle SQ residual training
     void trainResiduals_(idx_t n, const float* x);