faiss 0.6.0 → 0.6.1

data/vendor/faiss/faiss/gpu/StandardGpuResources.h

@@ -25,7 +25,8 @@
 
 #if defined USE_NVIDIA_CUVS
 #include <raft/core/device_resources.hpp>
-#include <rmm/mr/host/pinned_memory_resource.hpp>
+#include <rmm/mr/device_memory_resource.hpp>
+#include <rmm/mr/pinned_host_memory_resource.hpp>
 #endif
 
 #include <faiss/gpu/GpuResources.h>
@@ -172,8 +173,8 @@ class StandardGpuResourcesImpl : public GpuResources {
     // managed_memory_resource
     std::unique_ptr<rmm::mr::device_memory_resource> mmr_;
 
-    // pinned_memory_resource
-    std::unique_ptr<rmm::mr::host_memory_resource> pmr_;
+    // pinned_host_memory_resource
+    std::unique_ptr<rmm::mr::pinned_host_memory_resource> pmr_;
 #endif
 
     /// Pinned memory allocation for use with this GPU

data/vendor/faiss/faiss/gpu/test/TestGpuIndexFlat.cpp

@@ -11,6 +11,7 @@
 #include <faiss/gpu/impl/IndexUtils.h>
 #include <faiss/gpu/test/TestUtils.h>
 #include <faiss/gpu/utils/DeviceUtils.h>
+#include <faiss/impl/IDSelector.h>
 #include <gtest/gtest.h>
 #include <sstream>
 #include <unordered_map>
@@ -761,6 +762,51 @@ TEST(TestCuvsGpuIndexFlat, SearchAndReconstruct) {
 }
 #endif
 
+void testIDSelectorFlat(faiss::MetricType metricType) {
+    int numAdd = faiss::gpu::randVal(2000, 5000);
+    int dim = faiss::gpu::randVal(64, 200);
+    int numQuery = faiss::gpu::randVal(32, 100);
+    int k = faiss::gpu::randVal(10, 30);
+    int device = faiss::gpu::randVal(0, faiss::gpu::getNumDevices() - 1);
+
+    faiss::gpu::StandardGpuResources res;
+    res.noTempMemory();
+
+    auto queryVecs = faiss::gpu::randVecs(numQuery, dim);
+    faiss::gpu::GpuIndexFlatConfig config;
+    config.device = device;
+    config.use_cuvs = true;
+    for (bool useFloat16 : {false, true}) {
+        config.useFloat16 = useFloat16;
+        faiss::gpu::GpuIndexFlat gpuIndex(&res, dim, metricType, config);
+        std::vector<float> addVecs = faiss::gpu::randVecs(numAdd, dim);
+        gpuIndex.add(numAdd, addVecs.data());
+
+        faiss::gpu::TestIDSelectorStruct selector_struct(numAdd);
+        faiss::SearchParameters search_params;
+        for (auto& [selectorName, selector] : selector_struct.selector_map) {
+            search_params.sel = selector.get();
+            faiss::gpu::testIDSelectorSearch(
+                    &gpuIndex,
+                    &search_params,
+                    queryVecs,
+                    numQuery,
+                    k,
+                    selectorName);
+        }
+    }
+}
+
+#if defined USE_NVIDIA_CUVS
+TEST(TestCuvsGpuIndexFlat, IDSelector_L2) {
+    testIDSelectorFlat(faiss::METRIC_L2);
+}
+
+TEST(TestCuvsGpuIndexFlat, IDSelector_IP) {
+    testIDSelectorFlat(faiss::METRIC_INNER_PRODUCT);
+}
+#endif
+
 int main(int argc, char** argv) {
     testing::InitGoogleTest(&argc, argv);
 

data/vendor/faiss/faiss/gpu/test/TestGpuIndexIVFFlat.cpp

@@ -28,6 +28,8 @@
 #include <faiss/gpu/StandardGpuResources.h>
 #include <faiss/gpu/test/TestUtils.h>
 #include <faiss/gpu/utils/DeviceUtils.h>
+#include <faiss/impl/IDSelector.h>
+#include <faiss/utils/distances.h>
 #include <gtest/gtest.h>
 #include <cmath>
 #include <sstream>
@@ -354,6 +356,11 @@ TEST(TestGpuIndexIVFFlat, Float32_Query_IP) {
 }
 
 TEST(TestGpuIndexIVFFlat, LargeBatch) {
+    // With low-dim vectors, CPU will use non-BLAS. Force the CPU to use
+    // the BLAS for consistent comparison.
+    int saved_threshold = faiss::distance_compute_blas_threshold;
+    faiss::distance_compute_blas_threshold = 1;
+
     Options opt;
     opt.dim = 3;
     opt.numQuery = 100000;
@@ -364,6 +371,8 @@ TEST(TestGpuIndexIVFFlat, LargeBatch) {
     opt.indicesOpt = faiss::gpu::INDICES_64_BIT;
     queryTest(opt, faiss::METRIC_L2, false);
 #endif
+
+    faiss::distance_compute_blas_threshold = saved_threshold;
 }
 
 // float16 coarse quantizer
@@ -909,6 +918,53 @@ TEST(TestGpuIndexIVFFlat, Reconstruct_n) {
     EXPECT_EQ(gpuVals, cpuVals);
 }
 
+void testIDSelectorIVFFlat(faiss::MetricType metricType) {
+    Options opt;
+
+    std::vector<float> trainVecs = faiss::gpu::randVecs(opt.numTrain, opt.dim);
+    std::vector<float> addVecs = faiss::gpu::randVecs(opt.numAdd, opt.dim);
+
+    faiss::gpu::StandardGpuResources res;
+    res.noTempMemory();
+
+    faiss::gpu::GpuIndexIVFFlatConfig config;
+    config.device = opt.device;
+    config.indicesOptions = faiss::gpu::INDICES_64_BIT;
+    config.use_cuvs = true;
+
+    faiss::gpu::GpuIndexIVFFlat gpuIndex(
+            &res, opt.dim, opt.numCentroids, metricType, config);
+    gpuIndex.nprobe = opt.nprobe;
+
+    gpuIndex.train(opt.numTrain, trainVecs.data());
+    gpuIndex.add(opt.numAdd, addVecs.data());
+
+    auto queryVecs = faiss::gpu::randVecs(opt.numQuery, opt.dim);
+    faiss::gpu::TestIDSelectorStruct selector_struct(opt.numAdd);
+    faiss::SearchParametersIVF search_params;
+    search_params.nprobe = opt.nprobe;
+    for (auto& [selectorName, selector] : selector_struct.selector_map) {
+        search_params.sel = selector.get();
+        faiss::gpu::testIDSelectorSearch(
+                &gpuIndex,
+                &search_params,
+                queryVecs,
+                opt.numQuery,
+                opt.k,
+                selectorName);
+    }
+}
+
+#if defined USE_NVIDIA_CUVS
+TEST(TestCuvsGpuIndexIVFFlat, IDSelector_L2) {
+    testIDSelectorIVFFlat(faiss::METRIC_L2);
+}
+
+TEST(TestCuvsGpuIndexIVFFlat, IDSelector_IP) {
+    testIDSelectorIVFFlat(faiss::METRIC_INNER_PRODUCT);
+}
+#endif
+
 int main(int argc, char** argv) {
     testing::InitGoogleTest(&argc, argv);
 

data/vendor/faiss/faiss/gpu/test/TestGpuIndexIVFPQ.cpp

@@ -6,11 +6,14 @@
  */
 
 #include <faiss/IndexFlat.h>
+#include <faiss/IndexIVF.h>
 #include <faiss/IndexIVFPQ.h>
 #include <faiss/gpu/GpuIndexIVFPQ.h>
 #include <faiss/gpu/StandardGpuResources.h>
 #include <faiss/gpu/test/TestUtils.h>
 #include <faiss/gpu/utils/DeviceUtils.h>
+#include <faiss/impl/IDSelector.h>
+#include <faiss/utils/distances.h>
 #include <gtest/gtest.h>
 #include <cmath>
 #include <sstream>
@@ -101,7 +104,11 @@ struct Options {
     }
 
     float getCompareEpsilon() const {
-        return 0.035f;
+        // With very low dimensionality (e.g., dim=4, codes=2 giving
+        // dimPerSubQuantizer=2), L2 distances can be very small
+        // (near-zero), causing relative error comparisons to be
+        // unstable despite tiny absolute differences.
+        return (dim <= 8) ? 0.15f : 0.035f;
     }
 
     float getPctMaxDiff1() const {
@@ -190,6 +197,11 @@ TEST(TestGpuIndexIVFPQ, Query_IP) {
 
 // Large batch sizes (>= 65536) should also work
 TEST(TestGpuIndexIVFPQ, LargeBatch) {
+    // With low-dim vectors, CPU will use non-BLAS. Force the CPU to use
+    // the BLAS for consistent comparison.
+    int saved_threshold = faiss::distance_compute_blas_threshold;
+    faiss::distance_compute_blas_threshold = 1;
+
     for (bool usePrecomputed : {false, true}) {
         Options opt;
 
@@ -202,6 +214,8 @@ TEST(TestGpuIndexIVFPQ, LargeBatch) {
 
         queryTest(opt, faiss::MetricType::METRIC_L2);
     }
+
+    faiss::distance_compute_blas_threshold = saved_threshold;
 }
 
 void testMMCodeDistance(faiss::MetricType mt) {
@@ -697,6 +711,11 @@ TEST(TestGpuIndexIVFPQ, Query_IP_Cuvs) {
 
 // Large batch sizes (>= 65536) should also work
 TEST(TestGpuIndexIVFPQ, LargeBatch_Cuvs) {
+    // See LargeBatch comment: force CPU BLAS path to match GPU GEMM
+    // decomposition for consistent L2 distance computation.
+    int saved_threshold = faiss::distance_compute_blas_threshold;
+    faiss::distance_compute_blas_threshold = 1;
+
     Options opt;
 
     // override for large sizes
@@ -711,6 +730,8 @@ TEST(TestGpuIndexIVFPQ, LargeBatch_Cuvs) {
     opt.bitsPerCode = 8;
 
     queryTest(opt, faiss::MetricType::METRIC_L2);
+
+    faiss::distance_compute_blas_threshold = saved_threshold;
 }
 
 TEST(TestGpuIndexIVFPQ, CopyFrom_Cuvs) {
@@ -877,6 +898,62 @@ TEST(TestGpuIndexIVFPQ, UnifiedMemory) {
 #endif
 }
 
+void testIDSelectorIVFPQ(faiss::MetricType metricType) {
+    Options opt;
+
+    std::vector<float> trainVecs = faiss::gpu::randVecs(opt.numTrain, opt.dim);
+    std::vector<float> addVecs = faiss::gpu::randVecs(opt.numAdd, opt.dim);
+
+    faiss::IndexFlatL2 quantizerL2(opt.dim);
+    faiss::IndexFlatIP quantizerIP(opt.dim);
+    faiss::Index* quantizer = metricType == faiss::METRIC_L2
+            ? (faiss::Index*)&quantizerL2
+            : (faiss::Index*)&quantizerIP;
+
+    faiss::IndexIVFPQ cpuIndex(
+            quantizer, opt.dim, opt.numCentroids, opt.codes, opt.bitsPerCode);
+    cpuIndex.metric_type = metricType;
+    cpuIndex.train(opt.numTrain, trainVecs.data());
+    cpuIndex.add(opt.numAdd, addVecs.data());
+
+    faiss::gpu::StandardGpuResources res;
+    res.noTempMemory();
+
+    faiss::gpu::GpuIndexIVFPQConfig config;
+    config.device = opt.device;
+    config.indicesOptions = faiss::gpu::INDICES_64_BIT;
+    config.interleavedLayout = true;
+    config.use_cuvs = true;
+
+    faiss::gpu::GpuIndexIVFPQ gpuIndex(&res, &cpuIndex, config);
+    gpuIndex.nprobe = opt.nprobe;
+
+    auto queryVecs = faiss::gpu::randVecs(opt.numQuery, opt.dim);
+    faiss::gpu::TestIDSelectorStruct selector_struct(opt.numAdd);
+    faiss::SearchParametersIVF search_params;
+    search_params.nprobe = opt.nprobe;
+    for (auto& [selectorName, selector] : selector_struct.selector_map) {
+        search_params.sel = selector.get();
+        faiss::gpu::testIDSelectorSearch(
+                &gpuIndex,
+                &search_params,
+                queryVecs,
+                opt.numQuery,
+                opt.k,
+                selectorName);
+    }
+}
+
+#if defined USE_NVIDIA_CUVS
+TEST(TestCuvsGpuIndexIVFPQ, IDSelector_L2) {
+    testIDSelectorIVFPQ(faiss::METRIC_L2);
+}
+
+TEST(TestCuvsGpuIndexIVFPQ, IDSelector_IP) {
+    testIDSelectorIVFPQ(faiss::METRIC_INNER_PRODUCT);
+}
+#endif
+
 int main(int argc, char** argv) {
     testing::InitGoogleTest(&argc, argv);
 

data/vendor/faiss/faiss/gpu/test/TestUtils.cpp

@@ -6,6 +6,7 @@
  */
 
 #include <faiss/gpu/test/TestUtils.h>
+#include <faiss/impl/IDSelector.h>
 #include <faiss/utils/random.h>
 #include <gtest/gtest.h>
 #include <time.h>
@@ -429,5 +430,76 @@ void compareLists(
     }
 }
 
+TestIDSelectorStruct::TestIDSelectorStruct(int numAdd) {
+    // Range selector [20%, 80%] of the database
+    size_t min_id = numAdd / 5;
+    size_t max_id = numAdd * 4 / 5;
+    selector_map["Range"] =
+            std::make_unique<faiss::IDSelectorRange>(min_id, max_id);
+
+    // Array selector (every 3rd element)
+    array_ids.clear();
+    for (int i = 0; i < numAdd; i += 3) {
+        array_ids.push_back(i);
+    }
+    selector_map["Array"] = std::make_unique<faiss::IDSelectorArray>(
+            array_ids.size(), array_ids.data());
+
+    // Batch selector (every 5th element)
+    batch_ids.clear();
+    for (int i = 1; i < numAdd; i += 5) {
+        batch_ids.push_back(i);
+    }
+    selector_map["Batch"] = std::make_unique<faiss::IDSelectorBatch>(
+            batch_ids.size(), batch_ids.data());
+
+    // Bitmap selector (every 4th element selected)
+    size_t bitmap_size = (numAdd + 7) / 8;
+    bitmap.resize(bitmap_size, 0);
+    for (int i = 0; i < numAdd; i += 4) {
+        int byte_idx = i / 8;
+        int bit_idx = i % 8;
+        bitmap[byte_idx] |= (1 << bit_idx);
+    }
+    selector_map["Bitmap"] =
+            std::make_unique<faiss::IDSelectorBitmap>(numAdd, bitmap.data());
+
+    selector_map["Not"] =
+            std::make_unique<faiss::IDSelectorNot>(selector_map["Range"].get());
+    selector_map["And"] = std::make_unique<faiss::IDSelectorAnd>(
+            selector_map["Range"].get(), selector_map["Array"].get());
+    selector_map["Or"] = std::make_unique<faiss::IDSelectorOr>(
+            selector_map["Range"].get(), selector_map["Batch"].get());
+    selector_map["XOr"] = std::make_unique<faiss::IDSelectorXOr>(
+            selector_map["Not"].get(), selector_map["Array"].get());
+}
+
+void testIDSelectorSearch(
+        faiss::Index* index,
+        faiss::SearchParameters* search_params,
+        const std::vector<float>& queryVecs,
+        int numQuery,
+        int k,
+        const std::string& selectorName) {
+    FAISS_ASSERT(search_params && search_params->sel);
+    std::vector<float> distances(numQuery * k, 0);
+    std::vector<faiss::idx_t> labels(numQuery * k, -1);
+    index->search(
+            numQuery,
+            queryVecs.data(),
+            k,
+            distances.data(),
+            labels.data(),
+            search_params);
+    faiss::IDSelector* selector = search_params->sel;
+    for (int i = 0; i < numQuery * k; ++i) {
+        if (labels[i] >= 0) {
+            EXPECT_TRUE(selector->is_member(labels[i]))
+                    << "Label " << labels[i] << " @ " << i << " not in "
+                    << selectorName << " selector";
+        }
+    }
+}
+
 } // namespace gpu
 } // namespace faiss

data/vendor/faiss/faiss/gpu/test/TestUtils.h

@@ -13,6 +13,7 @@
 #include <gtest/gtest.h>
 #include <cstring>
 #include <initializer_list>
+#include <map>
 #include <memory>
 #include <string>
 #include <vector>
@@ -141,5 +142,27 @@ void testIVFEquality(A& cpuIndex, B& gpuIndex) {
     }
 }
 
+/// Run search with the given search_params and verify all returned labels are
+/// members of the selector. Works with any Index that supports search with
+/// SearchParameters.
+void testIDSelectorSearch(
+        faiss::Index* index,
+        faiss::SearchParameters* search_params,
+        const std::vector<float>& queryVecs,
+        int numQuery,
+        int k,
+        const std::string& selectorName);
+
+// Structure to hold all IDSelector instances
+struct TestIDSelectorStruct {
+    // Storage for selectors that need it
+    std::vector<faiss::idx_t> array_ids;
+    std::vector<faiss::idx_t> batch_ids;
+    std::vector<uint8_t> bitmap;
+    std::map<std::string, std::unique_ptr<faiss::IDSelector>> selector_map;
+
+    explicit TestIDSelectorStruct(int numAdd);
+};
+
 } // namespace gpu
 } // namespace faiss

data/vendor/faiss/faiss/gpu/utils/CuvsFilterConvert.h

@@ -36,6 +36,6 @@ namespace faiss::gpu {
 void convert_to_bitset(
         faiss::gpu::GpuResources* res,
         const faiss::IDSelector& selector,
-        cuvs::core::bitset_view<uint32_t, uint32_t> bitset,
+        cuvs::core::bitset_view<uint32_t, int64_t> bitset,
         int num_threads = 0);
 } // namespace faiss::gpu

data/vendor/faiss/faiss/gpu/utils/CuvsUtils.h

@@ -27,32 +27,32 @@
 #include <faiss/gpu/GpuResources.h>
 #include <faiss/gpu/utils/Tensor.cuh>
 
-#include <cuvs/distance/distance.h>
+#include <cuvs/distance/distance.hpp>
 
 #pragma GCC visibility push(default)
 namespace faiss {
 namespace gpu {
 
-inline cuvsDistanceType metricFaissToCuvs(
+inline cuvs::distance::DistanceType metricFaissToCuvs(
         MetricType metric,
         bool exactDistance) {
     switch (metric) {
         case MetricType::METRIC_INNER_PRODUCT:
-            return cuvsDistanceType::InnerProduct;
+            return cuvs::distance::DistanceType::InnerProduct;
         case MetricType::METRIC_L2:
-            return cuvsDistanceType::L2Expanded;
+            return cuvs::distance::DistanceType::L2Expanded;
         case MetricType::METRIC_L1:
-            return cuvsDistanceType::L1;
+            return cuvs::distance::DistanceType::L1;
         case MetricType::METRIC_Linf:
-            return cuvsDistanceType::Linf;
+            return cuvs::distance::DistanceType::Linf;
         case MetricType::METRIC_Lp:
-            return cuvsDistanceType::LpUnexpanded;
+            return cuvs::distance::DistanceType::LpUnexpanded;
         case MetricType::METRIC_Canberra:
-            return cuvsDistanceType::Canberra;
+            return cuvs::distance::DistanceType::Canberra;
         case MetricType::METRIC_BrayCurtis:
-            return cuvsDistanceType::BrayCurtis;
+            return cuvs::distance::DistanceType::BrayCurtis;
         case MetricType::METRIC_JensenShannon:
-            return cuvsDistanceType::JensenShannon;
+            return cuvs::distance::DistanceType::JensenShannon;
         default:
             RAFT_FAIL("Distance type not supported");
     }
@@ -71,6 +71,17 @@ idx_t inplaceGatherFilteredRows(
         GpuResources* res,
         Tensor<float, 2, true>& vecs,
         Tensor<idx_t, 1, true>& indices);
+
+/// Copy uint32_t indices to idx_t, replacing any index >= n with -1.
+/// cuVS CAGRA returns sentinel values (e.g. INT32_MAX) for result slots
+/// where filtered search couldn't find a valid neighbor.
+void sanitizeCuvsIndices(
+        GpuResources* res,
+        uint32_t* src,
+        idx_t* dst,
+        size_t count,
+        idx_t n);
+
 } // namespace gpu
 } // namespace faiss
 #pragma GCC visibility pop

data/vendor/faiss/faiss/gpu_metal/GpuIndexFlat.h

@@ -0,0 +1,22 @@
+// @lint-ignore-every LICENSELINT
+/**
+ * Copyright (c) Meta Platforms, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * Unified name for flat GPU index when Metal backend is built.
+ * Include this when using the Metal backend for API parity with
+ * faiss::gpu::GpuIndexFlat.
+ */
+
+#pragma once
+
+#include <faiss/gpu_metal/MetalIndexFlat.h>
+
+namespace faiss {
+
+/// When FAISS is built with Metal backend, GpuIndexFlat is MetalIndexFlat.
+using GpuIndexFlat = gpu_metal::MetalIndexFlat;
+
+} // namespace faiss

data/vendor/faiss/faiss/gpu_metal/MetalCloner.h

@@ -0,0 +1,35 @@
+// @lint-ignore-every LICENSELINT
+/**
+ * Copyright (c) Meta Platforms, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * Clone CPU <-> Metal GPU. Mirrors GpuCloner roles for Metal backend.
+ */
+
+#pragma once
+
+#include <faiss/Index.h>
+
+namespace faiss {
+namespace gpu_metal {
+
+class StandardMetalResources;
+
+/// Returns the number of Metal "devices" (1 if Metal is available, else 0).
+int get_num_gpus();
+
+/// Clone a CPU index to Metal GPU. Supports IndexFlat, IndexFlatL2,
+/// IndexFlatIP. device must be 0. Caller owns the returned index.
+faiss::Index* index_cpu_to_metal_gpu(
+        StandardMetalResources* res,
+        int device,
+        const faiss::Index* index);
+
+/// Copy a Metal index back to CPU. Supports MetalIndexFlat -> IndexFlat.
+/// Caller owns the returned index.
+faiss::Index* index_metal_gpu_to_cpu(const faiss::Index* index);
+
+} // namespace gpu_metal
+} // namespace faiss

data/vendor/faiss/faiss/gpu_metal/MetalFlatKernels.h

@@ -0,0 +1,40 @@
+// @lint-ignore-every LICENSELINT
+/**
+ * Copyright (c) Meta Platforms, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * Objective-C++ header. Runs L2/IP distance + top-k via Metal compute.
+ */
+
+#pragma once
+
+#import <Metal/Metal.h>
+
+#include <cstddef>
+
+namespace faiss {
+namespace gpu_metal {
+
+/// Runs GPU search: distance matrix (L2 or IP) then top-k. Uses shared buffers
+/// (queries, vectors, outDistances, outIndices). outIndices are int32
+/// (0..nb-1). Maximum k supported by the GPU top-k kernel (256).
+int getMetalFlatSearchMaxK();
+
+/// Returns true on success; false if pipeline creation failed.
+bool runFlatSearchGPU(
+        id<MTLDevice> device,
+        id<MTLCommandQueue> queue,
+        id<MTLBuffer> queries, // (nq * d) float, row-major
+        id<MTLBuffer> vectors, // (nb * d) float, row-major
+        int nq,
+        int nb,
+        int d,
+        int k,
+        bool isL2,                  // true = L2 squared, false = inner product
+        id<MTLBuffer> outDistances, // (nq * k) float
+        id<MTLBuffer> outIndices);  // (nq * k) int32
+
+} // namespace gpu_metal
+} // namespace faiss

data/vendor/faiss/faiss/gpu_metal/MetalIndex.h

@@ -0,0 +1,51 @@
+// @lint-ignore-every LICENSELINT
+/**
+ * Copyright (c) Meta Platforms, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * Objective-C++ header (uses MetalResources).
+ */
+
+#pragma once
+
+#include <faiss/Index.h>
+#include <faiss/gpu_metal/MetalResources.h>
+#include <memory>
+
+namespace faiss {
+namespace gpu_metal {
+
+/// Configuration for Metal index (mirrors GpuIndexConfig roles).
+struct MetalIndexConfig {
+    int device = 0;
+};
+
+/// Base class for Metal-backed indexes. Mirrors faiss::gpu::GpuIndex.
+class MetalIndex : public faiss::Index {
+   public:
+    MetalIndex(
+            std::shared_ptr<MetalResources> resources,
+            int dims,
+            faiss::MetricType metric,
+            float metricArg,
+            MetalIndexConfig config = MetalIndexConfig());
+
+    int getDevice() const {
+        return config_.device;
+    }
+    std::shared_ptr<MetalResources> getResources() {
+        return resources_;
+    }
+    std::shared_ptr<const MetalResources> getResources() const {
+        return resources_;
+    }
+
+   protected:
+    std::shared_ptr<MetalResources> resources_;
+    MetalIndexConfig config_;
+};
+
+} // namespace gpu_metal
+} // namespace faiss