Skip to content

feat: add HNSW RaBitQ with rotated storage and staged search - #1814

Draft
CLiqing wants to merge 6 commits into
zilliztech:mainfrom
CLiqing:feat/hnsw-rabitq
Draft

feat: add HNSW RaBitQ with rotated storage and staged search#1814
CLiqing wants to merge 6 commits into
zilliztech:mainfrom
CLiqing:feat/hnsw-rabitq

Conversation

@CLiqing

@CLiqing CLiqing commented Sep 10, 2026

Copy link
Copy Markdown
Collaborator

issue: #1747

Summary

Add HNSW_RABITQ to Knowhere with L2, inner product and cosine support.

  • Build the graph using FP32 distances, then populate random-rotated Faiss RaBitQ storage using bounded encoding batches.
  • Support database precision rbq_bits=1..9 (default 1) and request-local rbq_bits_query=0..8 (default 4) for search, range search and iteration.
  • Use a one-bit estimate followed by multi-bit scoring during graph traversal, with metric-aware distance adapters and optimized query-estimate/full-distance SIMD kernels. Batch four independent qb=4 estimates with query-plane reuse and prefetch.
  • Preserve original input data for cosine norm correction and optional refinement; support existing refine codecs and refine_k.
  • Cover filtering/brute-force fallback, serialization, distance-by-ID and index registration. Keep the common HNSW input conversion unchanged; RaBitQ-specific bounded encoding lives in the bundled Faiss contrib utility.

Faiss relationship and scope

This selectively adapts the standard RaBitQ layout and staged-search approach from facebookresearch/faiss#5526, reference d8a85956060c7567ff40dc1eb0a77578533d8bad, to Knowhere's bundled Faiss. FP32 graph construction, rotation, cosine, filtering, refinement and request-local query parameters are Knowhere integration responsibilities.

New index/adaptor classes are under faiss/cppcontrib/knowhere. Existing core RaBitQ changes add a batched estimate interface and optimize SIMD kernels and unaligned-load safety.

Current boundaries

  • Immutable after initial build; mmap, multi-vector and embedding-list support are not advertised.
  • The parent Knowhere index must outlive its iterators, consistent with the current common iterator ownership limitation.
  • ARM64, early AMD and native Sapphire Rapids hardware execution remain CI/platform follow-ups; local dispatch overrides and SPR syntax checks do not replace hardware coverage.

Signed-off-by: ChenLiqing <23721160+CLiqing@users.noreply.github.com>
@sre-ci-robot

Copy link
Copy Markdown
Collaborator

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: CLiqing

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

The pull request process is described here

Details Needs approval from an approver in each of these files:

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

@CLiqing

CLiqing commented Sep 10, 2026

Copy link
Copy Markdown
Collaborator Author

/kind feature

Move RaBitQ dispatch and staged evaluation out of generic HNSW code. Reuse the refinement predicate and count full refinements in search statistics.

Reject non-RaBitQ payloads before replacing a live index, retain filtered iterator bridges, and add targeted and SQ/PQ regression coverage. Remove unrelated serialization formatting changes.

Signed-off-by: ChenLiqing <23721160+CLiqing@users.noreply.github.com>
Remove the separate native RaBitQ traversal. Keep search state, queues and stopping rules in the existing Knowhere searcher, with RaBitQ-specific staged distance evaluation and qb4 SIMD/prefetch batching. Preserve candidate-order refinement and request-local query parameters.

Signed-off-by: ChenLiqing <23721160+CLiqing@users.noreply.github.com>
Signed-off-by: ChenLiqing <23721160+CLiqing@users.noreply.github.com>
Signed-off-by: ChenLiqing <23721160+CLiqing@users.noreply.github.com>
Signed-off-by: ChenLiqing <23721160+CLiqing@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants