feat(vector): complete vector search engine — SIMD, TurboQuant, HNSW, MVCC, IVF, GPU

[TinDang97]

Summary

Full vector search engine for moon, implementing Redis-compatible FT.CREATE, FT.SEARCH, FT.DROPINDEX, and FT.INFO commands with a high-performance custom backend.

25,273 lines added across 94 files, 146 commits, 14 phases (59–72).

Core Architecture

• SIMD distance engine — L2, cosine, dot-product with AVX2/AVX-512/NEON kernels + scalar fallback, VPSHUFB FastScan for IVF
• TurboQuant 4-bit encoder — Lloyd-Max codebook, FWHT (scalar + AVX2 + NEON), nibble packing, multi-bit (1/2/3-bit) ADC, sub-centroid LUT scoring
• HNSW index — layered navigable small-world graph with BFS reorder, dual prefetch, beam search, Light/Exact build modes
• Segment architecture — mutable (brute-force f32) → immutable (HNSW + TQ) compaction pipeline with recall verification
• MVCC — snapshot isolation with TransactionManager, visibility checks, dirty-set merge
• Filtered search — Roaring bitmap PayloadIndex, ACORN 2-hop expansion, cost-based strategy selection
• IVF + FastScan — inverted file index with k-means clustering, FAISS-interleaved posting lists
• Persistence — WAL records with CRC32 framing, segment disk I/O with checksums, crash recovery
• GPU scaffold — gpu-cuda feature flag, CAGRA build kernel, batch FWHT, GPU-aware compaction (CPU fallback)

Redis Integration

• FT.CREATE / FT.DROPINDEX / FT.INFO / FT.SEARCH wired through command dispatch + shard routing
• HSET auto-indexing hook + DEL/HDEL/UNLINK auto-delete
• Multi-shard scatter-gather search coordinator
• Per-index configurable EF_RUNTIME and COMPACT_THRESHOLD

Performance Highlights

• 2.4× Redis QPS and 17× Qdrant QPS in fair TCP benchmarks (server-mode, 384d vectors)
• 31K inserts/s on real MiniLM-L6 768d embeddings
• 92% recall@10 with TQ 4-bit compression (vs 95% Redis HNSW, 96% Qdrant)
• Sub-centroid LUT scoring eliminates f32 reranking → +23% QPS
• Light build mode: 5× less memory, faster compaction

Bug Fixes (7 critical)

• BitVec indexing bug causing HNSW recall collapse
• Dimension-adaptive codebook (σ=1/√dim, not hardcoded)
• DashTable get_mut-after-insert panic
• SPSC self-send crash in FT.* routing
• f32 reranking restore (recall 0.18 → 0.99)
• Dense Gaussian QJL restore (recall 88% → 94.5%)
• Mutable segment uses f32 brute-force, not TQ-ADC

Testing

• Unit tests for all SIMD paths (scalar, AVX2, AVX-512, NEON)
• Edge case + stress tests (10K interleaved ops + compaction)
• Memory audit validating per-vector overhead budget
• Recall benchmarks (f32 baseline + TQ compressed)
• Criterion benchmarks for distance kernels, HNSW build/search, FWHT
• Competitive benchmark scripts vs Redis 8.6.1 and Qdrant

Test plan

• cargo test --no-default-features --features runtime-tokio,jemalloc passes
• cargo clippy -- -D warnings clean
• Vector edge case tests pass (tests/vector_edge_cases.rs)
• Vector stress tests pass (tests/vector_stress.rs)
• Memory audit passes (tests/vector_memory_audit.rs)
• Recall benchmark validates >85% recall@10 (tests/vector_recall_benchmark.rs)
• Server-mode FT.CREATE → HSET → FT.SEARCH pipeline works end-to-end
• Multi-shard vector search returns merged results

Summary by CodeRabbit

• New Features

  • Interactive vector search (FT.*): index lifecycle, KNN queries (HNSW/IVF), TurboQuant compression, payload filters, MVCC snapshots, auto-indexing on HSET, cross-shard scatter/merge, optional GPU helpers, persistent segments, compaction/vacuum, and vector metrics in INFO.

• Bug Fixes

  • Prevented panic during hash creation and improved lookup robustness.

• Documentation

  • Added a comprehensive vector-search user guide with quick start, tuning, and examples.

• Chores

  • Added extensive benchmarks, profiling and competitor-comparison scripts.