Materialize HNSW Layered Index to hnswlib Index

c/include/cuvs/neighbors/hnsw.h

@@ -35,7 +35,9 @@ enum cuvsHnswHierarchy {
   /* Full hierarchy is built using the CPU */
   CPU = 1,
   /* Full hierarchy is built using the GPU */
-  GPU = 2
+  GPU = 2,
+  /* GPU-built hierarchy stored as a layered on-disk topology artifact */
+  GPU_LAYERED_ON_DISK = 3
 };
 
 /**
@@ -130,6 +132,14 @@ struct cuvsHnswIndexParams {
    * Set to nullptr for default behavior (from_cagra conversion).
    */
   cuvsHnswAceParams_t ace_params;
+  /**
+   * Local dataset path used by layered HNSW deserialization.
+   *
+   * When `hierarchy == GPU_LAYERED_ON_DISK`, the index artifact stores graph topology only.
+   * `cuvsHnswDeserialize` loads the original-ID-ordered vectors from this local dataset path to
+   * reconstruct an in-memory HNSW index. Set to nullptr (default) for all other hierarchies.
+   */
+  const char* dataset_path;
 };
 
 typedef struct cuvsHnswIndexParams* cuvsHnswIndexParams_t;
@@ -601,6 +611,80 @@ CUVS_EXPORT cuvsError_t cuvsHnswDeserialize(cuvsResources_t res,
  * @}
  */
 
+/**
+ * @defgroup hnsw_c_index_materialize Materialize a layered HNSW artifact to an hnswlib index
+ * @{
+ */
+
+/**
+ * @brief Parameters for materializing a layered HNSW artifact into an hnswlib index on disk.
+ */
+struct cuvsHnswMaterializeParams {
+  /**
+   * Local dataset path holding the original-ID-ordered vectors used to build the artifact.
+   *
+   * Supported formats match layered deserialization: `.npy` and ANN benchmark `*.bin` files with a
+   * `[uint32 rows, uint32 cols]` header (`.fbin`, `.f16bin`, `.u8bin`, `.i8bin`).
+   */
+  const char* dataset_path;
+  /**
+   * Upper bound on host memory (in GiB) used for the base-topology reorder buffer.
+   *
+   * When `<= 0`, the whole base topology is reordered in a single in-memory pass (no temporary
+   * files). When set, the base topology is reordered through bucketed temporary files so that peak
+   * host memory stays close to this budget.
+   */
+  double max_host_memory_gb;
+  /** Number of host threads to use. When `0`, the maximum number of threads is used. */
+  int num_threads;
+};
+
+typedef struct cuvsHnswMaterializeParams* cuvsHnswMaterializeParams_t;
+
+/**
+ * @brief Allocate HNSW materialize params, and populate with default values
+ *
+ * @param[in] params cuvsHnswMaterializeParams_t to allocate
+ * @return cuvsError_t
+ */
+CUVS_EXPORT cuvsError_t cuvsHnswMaterializeParamsCreate(cuvsHnswMaterializeParams_t* params);
+
+/**
+ * @brief De-allocate HNSW materialize params
+ *
+ * @param[in] params cuvsHnswMaterializeParams_t to de-allocate
+ * @return cuvsError_t
+ */
+CUVS_EXPORT cuvsError_t cuvsHnswMaterializeParamsDestroy(cuvsHnswMaterializeParams_t params);
+
+/**
+ * @brief Materialize a layered HNSW artifact into a standard hnswlib index file on disk.
+ *
+ * Materializes a `GPU_LAYERED_ON_DISK` artifact (graph topology only, stored in ACE order) plus a
+ * local dataset into a standard hnswlib index file, without ever holding the full materialized
+ * index in host memory. The resulting file is compatible with the original hnswlib library and can
+ * be read back through `cuvsHnswDeserialize` with `hierarchy == CPU`. The element data type
+ * (`float`, `half`, `uint8_t` or `int8_t`) is read from the artifact header.
+ *
+ * @param[in] res cuvsResources_t opaque C handle
+ * @param[in] params cuvsHnswMaterializeParams_t materialization parameters
+ * @param[in] layered_artifact_path path to the layered HNSW artifact
+ * @param[in] output_path path to the hnswlib index file to write
+ * @param[in] dim the dimension of the vectors in the index
+ * @param[in] metric the distance metric used to build the index
+ * @return cuvsError_t
+ */
+CUVS_EXPORT cuvsError_t cuvsHnswMaterializeToHnswlib(cuvsResources_t res,
+                                                     cuvsHnswMaterializeParams_t params,
+                                                     const char* layered_artifact_path,
+                                                     const char* output_path,
+                                                     int dim,
+                                                     cuvsDistanceType metric);
+
+/**
+ * @}
+ */
+
 #ifdef __cplusplus
 }
 #endif

c/src/neighbors/hnsw.cpp

@@ -143,6 +143,8 @@ void* _deserialize(cuvsResources_t res,
   cuvs::neighbors::hnsw::index<T>* index = nullptr;
   auto cpp_params                        = cuvs::neighbors::hnsw::index_params();
   cpp_params.hierarchy = static_cast<cuvs::neighbors::hnsw::HnswHierarchy>(params->hierarchy);
+  // Required by GPU_LAYERED_ON_DISK deserialization to locate the original-ID-ordered vectors.
+  if (params->dataset_path != nullptr) { cpp_params.dataset_path = std::string(params->dataset_path); }
   auto metric_type     = static_cast<cuvs::distance::DistanceType>(metric);
   cuvs::neighbors::hnsw::deserialize(
     *res_ptr, cpp_params, std::string(filename), dim, metric_type, &index);
@@ -174,7 +176,8 @@ extern "C" cuvsError_t cuvsHnswIndexParamsCreate(cuvsHnswIndexParams_t* params)
                                       .num_threads     = 0,
                                       .M               = 32,
                                       .metric          = L2Expanded,
-                                      .ace_params      = nullptr};
+                                      .ace_params      = nullptr,
+                                      .dataset_path    = nullptr};
   });
 }
 
@@ -404,3 +407,41 @@ extern "C" cuvsError_t cuvsHnswDeserialize(cuvsResources_t res,
     }
   });
 }
+
+extern "C" cuvsError_t cuvsHnswMaterializeParamsCreate(cuvsHnswMaterializeParams_t* params)
+{
+  return cuvs::core::translate_exceptions([=] {
+    *params = new cuvsHnswMaterializeParams{
+      .dataset_path = nullptr, .max_host_memory_gb = 0, .num_threads = 0};
+  });
+}
+
+extern "C" cuvsError_t cuvsHnswMaterializeParamsDestroy(cuvsHnswMaterializeParams_t params)
+{
+  return cuvs::core::translate_exceptions([=] { delete params; });
+}
+
+extern "C" cuvsError_t cuvsHnswMaterializeToHnswlib(cuvsResources_t res,
+                                                    cuvsHnswMaterializeParams_t params,
+                                                    const char* layered_artifact_path,
+                                                    const char* output_path,
+                                                    int dim,
+                                                    cuvsDistanceType metric)
+{
+  return cuvs::core::translate_exceptions([=] {
+    auto res_ptr    = reinterpret_cast<raft::resources*>(res);
+    auto cpp_params = cuvs::neighbors::hnsw::materialize_params();
+    if (params->dataset_path != nullptr) {
+      cpp_params.dataset_path = std::string(params->dataset_path);
+    }
+    cpp_params.max_host_memory_gb = params->max_host_memory_gb;
+    cpp_params.num_threads        = params->num_threads;
+    auto metric_type              = static_cast<cuvs::distance::DistanceType>(metric);
+    cuvs::neighbors::hnsw::materialize_to_hnswlib(*res_ptr,
+                                                  cpp_params,
+                                                  std::string(layered_artifact_path),
+                                                  std::string(output_path),
+                                                  dim,
+                                                  metric_type);
+  });
+}

cpp/bench/ann/src/cuvs/cuvs_cagra_hnswlib.cu

@@ -1,9 +1,10 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2023-2025, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2023-2026, NVIDIA CORPORATION.
  * SPDX-License-Identifier: Apache-2.0
  */
 
 #include "../common/ann_types.hpp"
+#include "../common/conf.hpp"
 #include "cuvs_ann_bench_param_parser.h"
 #include "cuvs_cagra_hnswlib_wrapper.h"
 
@@ -27,6 +28,8 @@ auto parse_build_param(const nlohmann::json& conf) ->
       hnsw_params.hierarchy = cuvs::neighbors::hnsw::HnswHierarchy::CPU;
     } else if (conf.at("hierarchy") == "gpu") {
       hnsw_params.hierarchy = cuvs::neighbors::hnsw::HnswHierarchy::GPU;
+    } else if (conf.at("hierarchy") == "gpu_layered_on_disk") {
+      hnsw_params.hierarchy = cuvs::neighbors::hnsw::HnswHierarchy::GPU_LAYERED_ON_DISK;
     } else {
       THROW("Invalid value for hierarchy: %s", conf.at("hierarchy").get<std::string>().c_str());
     }
@@ -36,6 +39,11 @@ auto parse_build_param(const nlohmann::json& conf) ->
   if (conf.contains("ef_construction")) {
     hnsw_params.ef_construction = conf.at("ef_construction");
   }
+  if (conf.contains("dataset_path")) {
+    hnsw_params.dataset_path = conf.at("dataset_path");
+  } else if (hnsw_params.hierarchy == cuvs::neighbors::hnsw::HnswHierarchy::GPU_LAYERED_ON_DISK) {
+    hnsw_params.dataset_path = configuration::singleton().get_dataset_conf().base_file;
+  }
   if (conf.contains("num_threads")) { hnsw_params.num_threads = conf.at("num_threads"); }
 
   // Reuse the CAGRA wrapper params parser
@@ -55,16 +63,18 @@ auto parse_build_param(const nlohmann::json& conf) ->
         cuvs::neighbors::cagra::hnsw_heuristic_type::SAME_GRAPH_FOOTPRINT,
         dist_type);
       ps.metric = dist_type;
-      // Parse ACE parameters if provided
-      if (conf.contains("npartitions") || conf.contains("build_dir") ||
-          conf.contains("ef_construction") || conf.contains("use_disk")) {
+      // Parse ACE parameters if provided.
+      auto ace_conf = collect_conf_with_prefix(conf, "ace_");
+      if (!ace_conf.empty()) {
         auto ace_params = cuvs::neighbors::cagra::graph_build_params::ace_params();
-        if (conf.contains("npartitions")) { ace_params.npartitions = conf.at("npartitions"); }
-        if (conf.contains("build_dir")) { ace_params.build_dir = conf.at("build_dir"); }
-        if (conf.contains("ef_construction")) {
-          ace_params.ef_construction = conf.at("ef_construction");
+        if (ace_conf.contains("npartitions")) {
+          ace_params.npartitions = ace_conf.at("npartitions");
+        }
+        if (ace_conf.contains("build_dir")) { ace_params.build_dir = ace_conf.at("build_dir"); }
+        if (ace_conf.contains("ef_construction")) {
+          ace_params.ef_construction = ace_conf.at("ef_construction");
         }
-        if (conf.contains("use_disk")) { ace_params.use_disk = conf.at("use_disk"); }
+        if (ace_conf.contains("use_disk")) { ace_params.use_disk = ace_conf.at("use_disk"); }
         ps.graph_build_params = ace_params;
       }
       // NB: above, we only provide the defaults. Below we parse the explicit parameters as usual.

cpp/bench/ann/src/cuvs/cuvs_cagra_hnswlib_wrapper.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2023-2025, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2023-2026, NVIDIA CORPORATION.
  * SPDX-License-Identifier: Apache-2.0
  */
 #pragma once
@@ -9,10 +9,33 @@
 #include <raft/core/logger.hpp>
 
 #include <chrono>
+#include <filesystem>
 #include <memory>
 
 namespace cuvs::bench {
 
+inline void move_file_overwrite(const std::filesystem::path& src, const std::filesystem::path& dst)
+{
+  std::error_code ec;
+  if (src == dst ||
+      (std::filesystem::exists(dst, ec) && std::filesystem::equivalent(src, dst, ec))) {
+    return;
+  }
+  if (!dst.parent_path().empty()) { std::filesystem::create_directories(dst.parent_path()); }
+  if (std::filesystem::exists(dst, ec)) { std::filesystem::remove(dst, ec); }
+
+  std::filesystem::rename(src, dst, ec);
+  if (ec) {
+    // Rename fails across filesystems. Fall back to copy followed by removal of the source.
+    ec.clear();
+    std::filesystem::copy_file(src, dst, std::filesystem::copy_options::overwrite_existing, ec);
+    const auto src_str = src.string();
+    const auto dst_str = dst.string();
+    RAFT_EXPECTS(!ec, "Failed to move '%s' to '%s'.", src_str.c_str(), dst_str.c_str());
+    std::filesystem::remove(src, ec);
+  }
+}
+
 template <typename T, typename IdxT>
 class cuvs_cagra_hnswlib : public algo<T>, public algo_gpu {
  public:
@@ -130,18 +153,25 @@ void cuvs_cagra_hnswlib<T, IdxT>::set_search_param(const search_param_base& para
 template <typename T, typename IdxT>
 void cuvs_cagra_hnswlib<T, IdxT>::save(const std::string& file) const
 {
+  if (build_param_.hnsw_index_params.hierarchy ==
+      cuvs::neighbors::hnsw::HnswHierarchy::GPU_LAYERED_ON_DISK) {
+    const auto src_artifact = std::filesystem::path(hnsw_index_->file_path());
+    RAFT_EXPECTS(!src_artifact.empty(), "Layered HNSW artifact path is not available.");
+    RAFT_EXPECTS(std::filesystem::exists(src_artifact),
+                 "Layered HNSW artifact '%s' does not exist.",
+                 src_artifact.c_str());
+
+    move_file_overwrite(src_artifact, std::filesystem::path(file));
+    return;
+  }
+
   if (cagra_ace_build_) {
     std::string index_filename = hnsw_index_->file_path();
     RAFT_EXPECTS(!index_filename.empty(), "HNSW index file path is not available.");
     RAFT_EXPECTS(std::filesystem::exists(index_filename),
                  "Index file '%s' does not exist.",
                  index_filename.c_str());
-    if (std::filesystem::exists(file)) { std::filesystem::remove(file); }
-    // might fail when using 2 different filesystems
-    std::error_code ec;
-    std::filesystem::rename(index_filename, file, ec);
-    RAFT_EXPECTS(
-      !ec, "Failed to rename index file '%s' to '%s'.", index_filename.c_str(), file.c_str());
+    move_file_overwrite(std::filesystem::path(index_filename), std::filesystem::path(file));
   } else {
     cuvs::neighbors::hnsw::serialize(handle_, file, *(hnsw_index_.get()));
   }