feat: GPU HNSW

[premal]

Summary

Adds GPU HNSW to knowhere: GPU_HNSW / GPU_HNSW_SQ index types that build a normal CPU faiss::IndexHNSW and search it on the GPU via the faiss-native faiss::gpu::GpuIndexHNSW (standard index_cpu_to_gpu cloner). There is no GPU build path — the CPU-built graph is uploaded as-is (zero rebuild cost) and beam search runs on the device to exploit GPU memory bandwidth.

Pairs with the faiss PR that adds GpuIndexHNSW (facebookresearch/faiss#5459). This PR re-vendors that faiss GPU tree under thirdparty/faiss/faiss/gpu/ and wires it into the knowhere index layer.

Motivation: on our workload (INT8_VECTOR, dim 384, COSINE, ~500M+ rows) CPU HNSW plateaus at ~1,600 vec/s per node (DRAM-bandwidth bound) and GPU CAGRA returned 0% recall, so neither was usable. This gives the existing HNSW graph a GPU search path with recall parity to CPU HNSW.

What's in this PR

Index layer (src/index/hnsw/faiss_hnsw.cc, index_table.h, index_param.h)

• Registers GPU_HNSW / GPU_HNSW_SQ. On load, a vanilla faiss::IndexHNSW (IndexHNSWFlat / IndexHNSWSQ) is cloned to GpuIndexHNSW and searched on device.
• GetVectorByIds / raw-data retrieval unsupported (vectors kept on GPU); StaticHasRawData=false.

Storage — native low precision (no decode-to-fp32)

Mirrors the faiss GpuIndexHNSW storage matrix — fp32 (4 B), int8 QT_8bit_direct_signed (1 B, DP4A), fp16 / bf16 (2 B). Vectors stay in their native device layout, up-converted to fp32 only inside the distance kernel, preserving the VRAM advantage at scale.

Accurate int8 cosine (ToVanillaHnsw)

QT_8bit_direct_signed is a fixed code = x + 128 map, so L2-normalized (cosine) vectors — components ~1/sqrt(d) — collapse onto a few of 256 levels, destroying recall. int8-cosine is therefore re-encoded to fp16 at load; int8 L2/IP keep direct_signed + DP4A (no re-encode):

auto* l2 = dynamic_cast<const HasInverseL2Norms*>(index_hnsw->storage);
bool is_cosine = (l2 != nullptr);
ToVanillaHnsw(src, is_cosine);   // is_cosine -> fp16 re-encode; else borrow int8 storage

Bounded host transient memory

Cosine re-encode reconstructs vectors in ~256 MiB chunks rather than materializing the full fp32 matrix, so concurrent segment loads don't spike host RAM.

Resource estimation (include/knowhere/index/index_static.h)

Resource reports host and device memory separately so the caller can admit GPU loads against VRAM, not host RAM:

struct Resource {
    uint64_t memoryCost;
    uint64_t diskCost;
    uint64_t maxMemoryCost = 0;   // host transient staging peak
    uint64_t gpuMemoryCost = 0;   // device-resident VRAM estimate
};

Measured int8-cosine device footprint ≈ 1.7× file size (fp16 codes + unchanged HNSW graph); gpuMemoryCost reserves a conservative 2× file size.

Vendored faiss GPU HNSW (thirdparty/faiss/faiss/gpu/)

Unified layer-0 kernel (native int8 DP4A, warp-cooperative coalesced loads), native fp16/bf16 device storage, parallel bitonic-sort + merge-path merge, CPU-parity filtered search (deletes/TTL/partition bitset), nq-chunked visited-bitmap VRAM bounding, on-device id→label conversion, and the DP4A-path-selection fix.

Build (cmake/libs/libfaiss.cmake)

Builds faiss_gpu_hnsw with POSITION_INDEPENDENT_CODE ON (fixes an R_X86_64_PC32 relocation error when linking the GPU kernel into the shared object).

Tests (tests/ut/test_gpu_search.cc)

• Per-dtype/metric recall gates: fp32 / fp16 / bf16 / int8 × L2 / IP / COSINE vs a brute-force oracle (fp16/bf16 track fp32; int8-cosine tracks the fp16 re-encode).
• [gpu_hnsw_load_mem]: asserts int8-cosine load host-RAM peak is bounded and measures per-segment VRAM footprint (host ratio ≈ 3.9×, device ratio ≈ 1.70×).
• CUDA upload fault-injection.

Design notes

1. Search-only — the CPU-built graph is uploaded; no reconstructable CPU copy retained on device.
2. Cosine = normalize + IP, consistent with the rest of faiss/gpu; int8-cosine re-encodes to fp16 for recall.
3. Native precision storage — preserves the VRAM advantage rather than decoding SQ codes to fp32 at upload.
4. Depends on faiss#5459 — the vendored thirdparty/faiss GPU tree carries GpuIndexHNSW; upstream would repoint to the faiss release once it lands.

Hardware / build

• NVIDIA GPU compute capability 7.0+ (Volta+), CUDA 12.x+.

[sre-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: premal
To complete the pull request process, please assign cqy123456 after the PR has been reviewed.
You can assign the PR to them by writing /assign @cqy123456 in a comment when ready.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[mergify]

@premal 🔍 Important: PR Classification Needed!

For efficient project management and a seamless review process, it's essential to classify your PR correctly. Here's how:

1. If you're fixing a bug, label it as kind/bug.
2. For small tweaks (less than 20 lines without altering any functionality), please use kind/improvement.
3. Significant changes that don't modify existing functionalities should be tagged as kind/enhancement.
4. Adjusting APIs or changing functionality? Go with kind/feature.

For any PR outside the kind/improvement category, ensure you link to the associated issue using the format: “issue: #”.

Thanks for your efforts and contribution to the community!.

[foxspy]

facebookresearch/faiss#5459
Please wait for the Faiss PR to be merged. Knowhere will subsequently integrate this index through Vanilla Faiss, so no code changes are required. Knowhere only needs to sync to the latest Faiss version.

/hold

[alexanderguzhva]

@premal Hi Premal, is there anything we can help you with your use case? Basically, we know that cuVS provides an excellent GPU performance, so it is somewhat unclear why it's needed to create an alternative implementation