[BUG] cuVS 26.08 CAGRA incompatibility with FAISS v1.14.3

[maestromadman]

Describe the bug

cuVS 26.08 changed the public cuvs::neighbors::cagra::build API: argument #3 changed from raft::device_matrix_view<const T, int64_t> (and the host equivalent) to cuvs::neighbors::dataset_view<...>. This is a source-breaking change that stops FAISS's cuVS integration from compiling.

Building FAISS v1.14.3 (unmodified upstream tag, commit 0ca9df47) with FAISS_ENABLE_CUVS=ON against libcuvs 26.08.00 fails to compile in faiss/gpu/impl/CuvsCagra.cu and faiss/gpu/impl/BinaryCuvsCagra.cu, because FAISS calls cagra::build(res, index_params, raft::device_matrix_view<const T>), an overload that no longer exists in 26.08. The same FAISS builds cleanly against libcuvs 26.06 (alas, 26.06 has other issues solved in 26.08, hence OS is upgrading to 26.08)

This blocks the OpenSearch RVIB, which pins FAISS v1.14.3.

Exact compiler output:

/tmp/faiss/faiss/gpu/impl/BinaryCuvsCagra.cu(178): error: no instance of overloaded function "cuvs::neighbors::cagra::build" matches the argument list
/tmp/faiss/faiss/gpu/impl/BinaryCuvsCagra.cu(185): error: no instance of overloaded function "cuvs::neighbors::cagra::build" matches the argument list
/tmp/faiss/faiss/gpu/impl/BinaryCuvsCagra.cu(226): error: no suitable user-defined conversion from "raft::device_matrix_view<const uint8_t, int64_t, raft::layout_c_contiguous>" to "cuvs::util::file_descriptor" exists
/tmp/faiss/faiss/gpu/impl/BinaryCuvsCagra.cu(230): error: no suitable user-defined conversion from "raft::host_matrix_view<const uint8_t, int64_t, raft::row_major>" to "cuvs::util::file_descriptor" exists
4 errors detected in the compilation of "/tmp/faiss/faiss/gpu/impl/BinaryCuvsCagra.cu".
make[3]: *** [.../impl/BinaryCuvsCagra.cu.o] Error 2

/tmp/faiss/faiss/gpu/impl/CuvsCagra.cu(206): error: no instance of overloaded function "cuvs::neighbors::cagra::build" matches the argument list
/tmp/faiss/faiss/gpu/impl/CuvsCagra.cu(213): error: no instance of overloaded function "cuvs::neighbors::cagra::build" matches the argument list
/tmp/faiss/faiss/gpu/impl/CuvsCagra.cu(252): error: no suitable user-defined conversion from "raft::device_matrix_view<const float, int64_t, raft::layout_c_contiguous>" to "cuvs::util:
/tmp/faiss/faiss/gpu/impl/CuvsCagra.cu(252): error: no suitable user-defined conversion from "raft::device_matrix_view<const half, ...>" to "cuvs::util::file_descriptor" exists
/tmp/faiss/faiss/gpu/impl/CuvsCagra.cu(252): error: no suitable user-defined conversion from "raft::device_matrix_view<const int8_t, ...>" to "cuvs::util::file_descriptor" exists
/tmp/faiss/faiss/gpu/impl/CuvsCagra.cu(256): error: no suitable user-defined conversion from "raft::host_matrix_view<const float, ...>" to "cuvs::util::file_descriptor" exists
/tmp/faiss/faiss/gpu/impl/CuvsCagra.cu(256): error: no suitable user-defined conversion from "raft::host_matrix_view<const half, ...>"
to "cuvs::util::file_descriptor" exists
/tmp/faiss/faiss/gpu/impl/CuvsCagra.cu(256): error: no suitable user-defined conversion from "raft::host_matrix_view<const int8_t,
...>" to "cuvs::util::file_descriptor" exists
12 errors detected in the compilation of "/tmp/faiss/faiss/gpu/impl/CuvsCagra.cu".
make[3]: *** [.../impl/CuvsCagra.cu.o] Error 2
make: *** [Makefile:543: faiss] Error 2

The compiler's candidate list shows the new (26.08) overloads it expects instead; argument #3 is now a dataset_view:

/opt/conda/include/cuvs/neighbors/cagra.hpp(959): note: function "cuvs::neighbors::cagra::build(
const raft::resources &,
const cuvs::neighbors::cagra::index_params &,
const cuvs::neighbors::dataset_view<cuvs::neighb, float, int64_t, ...> &)"
does not match because argument #3 does not match parameter

Steps/Code to reproduce bug

FAISS v1.14.3 calls (e.g. CuvsCagra.cu:206):

// dataset is a raft::device_matrix_view<const float, int64_t>
cuvs_index = std::make_shared<cuvs::neighbors::cagra::index<float, uint32_t>>(
    cuvs::neighbors::cagra::build(raft_handle, index_params_, dataset));   // compiles on 26.06, fails on 26.08

Minimal reproduction:

1. conda install -y libcuvs=26.08.00 cuda-nvcc=12.9 cuda-version=12.9 -c rapidsai -c conda-forge
2. Clone FAISS at tag v1.14.3: git clone https://github.com/facebookresearch/faiss && cd faiss && git checkout v1.14.3
3. Configure with cuVS enabled: cmake -B build -DFAISS_ENABLE_GPU=ON -DFAISS_ENABLE_CUVS=ON -DCMAKE_CUDA_ARCHITECTURES="120-real" .
4. make -C build faiss → fails compiling CuvsCagra.cu / BinaryCuvsCagra.cu with the errors above.

(Equivalently: build the opensearch-project/remote-vector-index-builder base image with libcuvs=26.08.00.)

Expected behavior

Either:

• the cagra::build(res, index_params, raft::device_matrix_view<const T>) overload remains available for source backward-compatibility, or
• the API change is documented with a clear migration path (how to construct/pass a cuvs::neighbors::dataset_view from a raft::device_matrix_view), so downstream consumers like FAISS can update.

A note on which cuVS release first changed this signature would also help downstreams pin correctly.

Environment details (please complete the following information):

• Environment location: Cloud (AWS EC2, RTX PRO 4500 Blackwell, sm_120). Note this is a compile-time failure and reproduces regardless of GPU.
• Method of cuVS install: conda, inside a Docker build.
  • Base image: nvidia/cuda:12.9.0-base-ubuntu24.04
  • conda install -y libcuvs=26.08.00 cuda-nvcc=12.9 cuda-version=12.9 cmake=4.0.3 "numpy>=2" gxx_linux-64=12.4 -c rapidsai -c conda-forge
  • libcuvs build: 26.08.00 cuda12_260805_6ba2ce28 (rapidsai). Same failure on 26.08.01 cuda12 and on the cuda13 builds.
• FAISS: v1.14.3 (facebookresearch/faiss @ 0ca9df47), FAISS_ENABLE_CUVS=ON
• CUDA 12.9 (nvcc 12.9.86), gcc/g++ 12.4, CMake 4.0.3, Ubuntu 24.04

Additional context

Motivation: we want to move OpenSearch RVIB to cuVS 26.08 because it appears to resolve an intermittent CUDA error 700 (illegal memory access) seen during CAGRA builds on Blackwell (sm_120) with cuVS 25.08/26.06. cuVS 26.08 installs cleanly and vanilla cuvs-bench FAISS-CAGRA builds run fine on the RTX 4500. The only blocker is that upstream FAISS v1.14.3 does not compile against 26.08's changed cagra::build API. We're trying to determine whether this API change is intended, and what the recommended FAISS version is.

[jrbourbeau]

Thanks @maestromadman. @tarang-jain I noticed this Faiss PR from you facebookresearch/faiss#5542 is updating to cuVS 26.10 nightly. I see some relevant looking changes in that PR -- @tarang-jain would facebookresearch/faiss#5542 address this issue? If so, I'm also wondering if it makes sense to pull cuVS compatibility updates into a separate PR

[tarang-jain]

correct! The break is expected. CAGRA cpp APIs are updated to accept new "dataset" objects. @jrbourbeau if it helps, what I can do is separate out the 26.10 migration into a different PR and get that merged sooner. The rabitq changes of #5542 can go in later.

[jrbourbeau]

That'd be great if you have bandwidth @tarang-jain. Updating to the latest cuVS 26.08.01 release would be great (should contain the dataset API changes)

[maestromadman]

opensearch-project/remote-vector-index-builder#153 by @jrbourbeau, checking now

[tarang-jain]

i am doing a complete revamp of the integration here: facebookresearch/faiss#5627
We want downstream consumers such as Faiss to rely on the stable C APIs due to ABI stability guarantees. This means that between *.08 and *.02 releases, libcuvs can be upgraded without changing Faiss code, the precise long term fix for issues such as this.

[maestromadman]

Tested the updated image; it works now. Thank you!