[nw9663644-eng]

Change Type

• New feature
• Improvement/Refactor
• Documentation
• CI/Build/Infra

Linked Issue

Closes #2888.

What Changed

This PR provides a standalone VSAG Lite library for small-scale, lightweight vector-search deployments. It retains vector CRUD and persistence while avoiding the Full VSAG runtime dependency closure. The Lite API is separate from the existing Full API; enabling or building Lite does not replace Full's default behavior.

Index::Create(dim) starts with exact FP32 squared-L2 BruteForce search. Callers can explicitly build a single-layer approximate graph with FP32 or FP16 storage, or enable ENABLE_RABITQ_LITE_BACKEND and select VectorStorage::RABITQ8. RaBitQ support is disabled by default.

Supported functionality

Backend / storage	Search semantics	CRUD and persistence
BruteForce / FP32	Exact squared L2; default backend	Add, Update, physical Remove, filtered Search, Save/Load
Graph / FP32	Approximate graph search over FP32 vectors	Same lifecycle, plus per-query graph budget
Graph / FP16	Approximate graph search over stored FP16 values; FP32 inputs	Same lifecycle, plus per-query graph budget
Graph / RaBitQ8	Approximate routing and quantized L2 estimates; opt-in	Same lifecycle, plus per-query graph budget; fixed trained model

The same Add, Update, Remove, filtered Search, per-call SearchWithOptions, Save, and Load API remains available after graph construction. Fallible graph construction preserves the previous backend, and graph mutation transactions restore logical state on allocation failure.

Implementation and optimizations

• Runtime SIMD distance dispatch for FP32/FP16 and native kernel reuse for optional RaBitQ8, with generic fallbacks.
• Incoming-link metadata and local mutation journals for graph maintenance, including physical deletion and moved-slot reference repair.
• RaBitQ query-statistic caching, bounded result heaps and size-specialized visited workspace. Its public adapter enables cached incoming protection and safe link pruning; additional Add/Remove/displaced-target guards remain off. These policies do not guarantee global connectivity or recall.
• Owned graph topology transfer, block/stream snapshot I/O and direct FP16 serialization to reduce unnecessary copies and conversions.
• Regression tests, installed shared/static consumer examples, and synchronized English/Chinese architecture and usage documentation.

The memory layout uses owned records, external-ID-to-slot mappings and graph adjacency. Deletes compact slots and repair references; retained container capacity is not guaranteed to be returned to the OS. RaBitQ stores the model, codes and metadata rather than an exact FP32 copy of every input vector.

Persistence is versioned and separate from Full VSAG: VSAGLT01 v1 is FP32 BruteForce, v2 is FP32 graph, v3 is FP16 graph, and optional RaBitQ8 uses independent VSAGLQ01 v1. Existing floating snapshot paths remain available when RaBitQ is disabled.

Directory layout

Path	Role
include/vsag/lite/index.h	Public Lite API, filter, query-budget and storage contracts
src/lite/bruteforce_backend.cpp	Exact backend and CRUD
src/lite/graph_backend.cpp	FP32/FP16 graph construction, incoming-link repair, transactions and search
src/lite/fp16_distance*.cpp, src/lite/fp32_distance*.cpp	Standalone runtime distance dispatch
src/lite/rabitq_*.{h,cpp}	Optional RaBitQ8 codec, graph state, SIMD filtering and snapshot implementation
src/lite/query_heap.h, src/lite/query_visited.h	Query-owned heap and visited workspace
src/lite/*_test.cpp	Unit, scale, graph, filter, snapshot and allocation-failure regressions
lite/CMakeLists.txt, lite/example/	Independent builds, installation and consumer examples
lite/tools/, .github/workflows/lite.yml	Standalone lint, coverage and CI configuration
docs/docs/{en,zh}/src/development/lite_first.md, lite_rabitq_design.md	Current architecture, functionality, test mapping and limitations

Benchmark runners, probes, raw results and rejected experimental policies remain outside this feature branch. Detailed benchmarks, raw records and reproducibility evidence are maintained separately in PR #2926. This feature PR retains only the implementation and its documented limits.

Build and usage

# Default build: BruteForce and FP32/FP16 graphs; RaBitQ disabled
cmake -S lite -B build-lite -G Ninja \
  -DCMAKE_BUILD_TYPE=Release -DENABLE_TESTS=ON
cmake --build build-lite -j2
ctest --test-dir build-lite --output-on-failure

# Optional RaBitQ8 build
cmake -S lite -B build-lite-rabitq -G Ninja \
  -DCMAKE_BUILD_TYPE=Release -DENABLE_TESTS=ON \
  -DENABLE_RABITQ_LITE_BACKEND=ON
cmake --build build-lite-rabitq -j2
ctest --test-dir build-lite-rabitq --output-on-failure

The English guide and 中文说明 map supported functions to implementation, tests and project deliverables. The bilingual RaBitQ design explains its actual maintenance policy and fixed-model boundaries.

Validation

Validated implementation at 74e0b84f4ecb7ab15b71ac6fd1e3760088b8dc92 on Ubuntu 22.04 x86_64 with GCC 11.4.0:

• Default-off Release: 4/4 CTest suites passed.
• RaBitQ-enabled Release: 5/5 suites passed, including allocation-failure regressions.
• ASan/UBSan: 5/5 suites passed with leak detection and halt-on-error enabled.
• Instrumented Debug: 5/5 suites passed; production Lite source/header line union was 3072/3233 = 95.02%. This is not whole-Full or branch coverage.
• Coverage collector fixtures and the 90% CLI gate passed.
• clang-format 15 and clang-tidy 15 checks passed for configured Lite translation units and private/public Lite headers.
• Installed shared/static consumers and the installed RaBitQ lifecycle example passed.

Standalone CI now includes default-OFF, RaBitQ-ON, sanitizer and coverage configurations, a 90% scoped line-coverage gate, installation checks and retained diagnostics. Hosted CI results are separate from this local validation and are not claimed as passed until their checks finish.

Full CI regression checks

The MCI test is unchanged from upstream main. The remaining Full test adjustments replace sleep-based failed-cache-load coordination and validate legal short session pages against legacy IDs/distances. Production index algorithms and coverage thresholds are unchanged by these test fixes.

Local Circle-like (-O2, system OpenBLAS, native ASan/TSan OFF) aggregate results: 1267 unit cases passed / 1 skipped; 181 HGraph functional cases passed; 263 other functional cases passed. The final naming-only cleanup passed both 29-case session suites and had identical runtime-loaded ELF sections, except the build identifier. Hosted CI approval and platform validation remain separate.

Compatibility and Limits

The existing Full VSAG API and default behavior are retained. RaBitQ8 is opt-in and disabled by default. Same-instance Lite calls must be externally serialized. Graph search is approximate; RaBitQ distances are quantized estimates, and its trained model remains fixed during CRUD.

Filtered graph queries can return fewer than k results. Remove returns bool and cannot distinguish a missing ID from a failed graph allocation. Mutation rollback preserves logical contents, not allocator capacity; failed Save can leave a partial output stream.

Lite snapshots are owned-memory formats and are not compatible with Full VSAG serialization. Checksums, crash-safe file replacement, automatic retraining, exact FP32 RaBitQ reranking, SQ8, mmap, bindings, sparse vectors and automatic BruteForce-to-Graph switching remain outside this PR.

GIST maintenance recall, quality-matched native Full comparisons and hours-long permanent-change stability acceptance remain open. Historical performance results are tied to their measured versions; this PR does not claim universal speedups or complete project acceptance.

[vsag-bot]

/label status/waiting-for-review
/waiting-on reviewer
/request-review @jiaweizone
/request-review @wxyucs
/request-review @inabao
/request-review @LHT129

[mergify]

Merge Protections

🟢 All 3 merge protections satisfied — ready to merge.

Show 3 satisfied protections

🟢 Require kind label

• label~=^kind/

🟢 Require version label

• label~=^version/

🟢 Require linked issue for feature/bug PRs

• body~=(?im)(?:^|[\s\-\*])(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s*:?\s+(?:#\d+|[\w.\-]+/[\w.\-]+#\d+|https?://github\.com/[\w.\-]+/[\w.\-]+/issues/\d+)

[LHT129]

Code Review for PR #2904

This is a well-structured PR that introduces a clean, minimal VSAG Lite baseline. The code quality is high overall. Below are the review findings:

Suggestions

1. src/lite/index.cpp:1012 — Fragile slots.emplace ordering

The impl_->slots.emplace(id, Size()) call records the slot mapping before the vector data and ID are actually appended to their containers (lines 1014-1015). While the comment correctly notes that scalar insertion cannot allocate after the successful reserve calls, this ordering creates a fragile invariant: if any future code is inserted between the emplace and the push_back/insert, the slots map could become inconsistent with the actual data.

Consider moving impl_->slots.emplace(id, Size()) to after impl_->ids.push_back(id) so that the slot mapping is only published once the data is fully committed. The slot value would then be Size() - 1 instead of Size().

2. src/lite/index.cpp:1052 — Unchecked find() dereference

impl_->slots.find(impl_->ids[slot])->second = slot;

The result of find() is dereferenced without checking for end(). While this is safe under the current invariants (the moved ID must exist in the map), an assertion or check would make the invariant explicit and catch potential future regressions. Consider adding assert(found != impl_->slots.end()) or storing the iterator and checking it.

3. lite/CMakeLists.txt:353 — Static library target

The library is only built as SHARED. For embedded or offline use cases where shared library deployment is undesirable, consider also providing a static library target (e.g., add_library(vsag_lite_static STATIC ...)).

Positive Observations

• The snapshot format is well-designed with explicit little-endian byte encoding, versioning, and comprehensive validation (truncation, corruption, duplicate IDs, non-finite values, trailing bytes).
• The test coverage is thorough: CRUD correctness, independent reference comparison, malformed snapshot rejection, stream failure contracts, and a 100k-vector end-to-end smoke test.
• The last-record-to-hole removal strategy correctly reuses the proven Full BruteForce approach.
• Input validation is consistently applied across all API entry points.
• The CI workflow covers formatting, clang-tidy, debug/release builds, dependency isolation verification, and installed consumer validation.
• Error handling properly translates exceptions to tl::expected errors without leaking exceptions to callers.
• The documentation clearly communicates the experimental nature, limitations, and future extension points.

Overall this is a solid foundation for the VSAG Lite effort. The suggestions above are non-blocking improvements.

[LHT129]

Code Review for PR #2904

This is a well-structured PR that introduces a clean, minimal VSAG Lite baseline. The code quality is high overall. Below are the review findings:

Suggestions

1. src/lite/index.cpp:1012 — Fragile slots.emplace ordering

The impl_->slots.emplace(id, Size()) call records the slot mapping before the vector data and ID are actually appended to their containers (lines 1014-1015). While the comment correctly notes that scalar insertion cannot allocate after the successful reserve calls, this ordering creates a fragile invariant: if any future code is inserted between the emplace and the push_back/insert, the slots map could become inconsistent with the actual data.

Consider moving impl_->slots.emplace(id, Size()) to after impl_->ids.push_back(id) so that the slot mapping is only published once the data is fully committed. The slot value would then be Size() - 1 instead of Size().

2. src/lite/index.cpp:1052 — Unchecked find() dereference

impl_->slots.find(impl_->ids[slot])->second = slot;

The result of find() is dereferenced without checking for end(). While this is safe under the current invariants (the moved ID must exist in the map), an assertion or check would make the invariant explicit and catch potential future regressions. Consider adding assert(found != impl_->slots.end()) or storing the iterator and checking it.

3. lite/CMakeLists.txt:353 — Static library target

The library is only built as SHARED. For embedded or offline use cases where shared library deployment is undesirable, consider also providing a static library target (e.g., add_library(vsag_lite_static STATIC ...)).

Positive Observations

• The snapshot format is well-designed with explicit little-endian byte encoding, versioning, and comprehensive validation (truncation, corruption, duplicate IDs, non-finite values, trailing bytes).
• The test coverage is thorough: CRUD correctness, independent reference comparison, malformed snapshot rejection, stream failure contracts, and a 100k-vector end-to-end smoke test.
• The last-record-to-hole removal strategy correctly reuses the proven Full BruteForce approach.
• Input validation is consistently applied across all API entry points.
• The CI workflow covers formatting, clang-tidy, debug/release builds, dependency isolation verification, and installed consumer validation.
• Error handling properly translates exceptions to tl::expected errors without leaking exceptions to callers.
• The documentation clearly communicates the experimental nature, limitations, and future extension points.

Overall this is a solid foundation for the VSAG Lite effort. The suggestions above are non-blocking improvements.

[LHT129]

Code Review for PR #2904

This is a well-structured PR that introduces a clean, minimal VSAG Lite baseline.

Suggestions

1. src/lite/index.cpp:1012 - Fragile slots.emplace ordering

The slots.emplace(id, Size()) call records the slot mapping before the vector data and ID are actually appended. Consider moving it after push_back so the slot mapping is only published once the data is fully committed.

2. src/lite/index.cpp:1052 - Unchecked find() dereference

The result of find() is dereferenced without checking for end(). An assertion would make the invariant explicit.

3. lite/CMakeLists.txt - Static library target

Consider also providing a static library target for embedded use cases.

Positive Observations

Well-designed snapshot format, thorough test coverage, proper input validation, clean CI workflow, and clear documentation. Solid foundation for VSAG Lite.

[LHT129]

Detailed Review Notes

1. src/lite/index.cpp:1012 — Fragile slots.emplace ordering [suggestion]

impl_->slots.emplace(id, Size());  // slot recorded here
// ...
impl_->vectors.insert(impl_->vectors.end(), vector, vector + dim);  // data appended here
impl_->ids.push_back(id);  // ID appended here

The slot mapping is published via slots.emplace before the actual data is committed to vectors and ids. While the comment correctly notes that scalar insertion cannot allocate after successful reserve, this ordering creates a fragile invariant. If any future code is inserted between the emplace and the push_back/insert, the slots map could become inconsistent.

Suggested fix: Move impl_->slots.emplace(id, Size()) to after impl_->ids.push_back(id), using Size() - 1 as the slot value.

2. src/lite/index.cpp:1052 — Unchecked find() dereference [note]

impl_->slots.find(impl_->ids[slot])->second = slot;

The result of find() is dereferenced without checking for end(). While this is safe under the current invariants (the moved ID must exist in the map), an explicit assertion would make the invariant explicit and catch potential future regressions.

3. lite/CMakeLists.txt:353 — Static library target [suggestion]

The library is only built as SHARED. For embedded or offline use cases where shared library deployment is undesirable, consider also providing a static library target.

---

Note: Inline comments could not be posted due to GitHub API limitations with fork PRs (position/line resolution unavailable). The findings above reference specific source locations.

[LHT129]

I have completed a thorough review of this PR. The existing review comments from LHT129 have already covered the substantive issues, and the author has addressed most of them in the latest commits.

Summary of what has been reviewed and addressed:

1. Geometric growth in grow lambda (fixed: capacity == 0 ? 1 case added)
2. Priority queue comparator type (fixed: replaced function pointer with NeighborWorseFirst functor)
3. Unchecked find() dereference in Remove (fixed: now uses slots.at())
4. Two's-complement decoding in Load (fixed: replaced with std::memcpy)
5. Copy in Save ID loop (fixed: const auto& instead of const auto)
6. Float copy in Save vectors loop (noted: for (float value : ...) vs const auto&)

Overall assessment:

The code is well-structured, well-tested (21,844+ assertions, 90.37% line coverage, sanitizer-clean), and well-documented. The isolation from the Full VSAG build is clean, and the CI coverage (format, clang-tidy, debug/release builds, installation, dependency isolation, external consumer) is comprehensive. The API design is minimal and appropriate for a v0.1 baseline.

No blocking issues remain. The remaining [note] about for (float value : impl_->vectors) in Save is a minor consistency observation that does not affect correctness.

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request

[wxyucs]

/version 1.2

[Copilot]

🟡 Changes recommended

RaBitQ scoring and empty-result handling, Save allocation errors, and SIMD feature guards need correction.

5 open issues

• Require FMA for AVX512 FP16 dispatch · New
• Require FMA for AVX512 distance dispatch · New
• Handle FP16 Save allocation failures · New
• Handle empty searches before query normalization · New
• Preserve zero residual norms in RaBitQ scoring · New

What changed in this PR

Adds standalone VSAG Lite for lightweight vector search without Full VSAG runtime dependencies. Benchmark acceptance remains separate in PR #2926.

Changes:

• Adds exact BruteForce, FP32/FP16 graphs and optional RaBitQ8 with CRUD and persistence.
• Adds SIMD reuse, allocation-failure regressions, standalone builds and CI.
• Documents API boundaries and limitations in English and Chinese.

File	Description
tests/​test_search_session.cpp	Accepts legal short session pages.
tests/​scripts/​simd_coverage_test.py	Updates workflow contract assertions.
tests/​scripts/​pr_simd_merge_base_test.py	Tests merge-parent selection.
src/​simd/​rabitq_simd_test.cpp	Tests shared scalar kernel.
src/​simd/​kernels/​rabitq_compute.h	Extracts shared scalar computation.
src/​simd/​generic.cpp	Reuses shared scalar kernel.
src/​quantization/​scalar_quantization/​sq8_uniform_quantizer.cpp	Uses alignment-safe metadata access.
src/​quantization/​scalar_quantization/​sq8_uniform_quantizer_test.cpp	Tests unaligned code buffers.
src/​lite/​rabitq_snapshot.h	Implements encoded snapshots.
src/​lite/​rabitq_filter_ip.h	Declares RaBitQ distance kernels.
src/​lite/​rabitq_filter_ip.cpp	Adds scalar kernels and dispatch.
src/​lite/​rabitq_filter_ip_avx512.cpp	Adds AVX512 kernel adapters.
src/​lite/​rabitq_filter_ip_avx2.cpp	Adds AVX2 kernel adapters.
src/​lite/​rabitq_constants.h	Defines quantization parameters.
src/​lite/​rabitq_codec.h	Implements training and encoding.
src/​lite/​rabitq_backend.cpp	Connects RaBitQ to Lite API.
src/​lite/​query_visited.h	Adds query-owned visited storage.
src/​lite/​query_heap.h	Adds reusable result heap.
src/​lite/​index.cpp	Implements public API and persistence.
src/​lite/​index_test.cpp	Tests lifecycle and search contracts.
src/​lite/​graph_allocation_test.cpp	Tests mutation rollback.
src/​lite/​fp32_distance.h	Declares FP32 kernels.
src/​lite/​fp32_distance.cpp	Implements FP32 runtime dispatch.
src/​lite/​fp32_distance_sse.cpp	Adapts SSE distance kernel.
src/​lite/​fp32_distance_avx512.cpp	Adapts AVX512 distance kernel.
src/​lite/​fp32_distance_avx2.cpp	Adapts AVX2 distance kernel.
src/​lite/​fp16_distance.h	Declares FP16 kernels.
src/​lite/​fp16_distance.cpp	Implements FP16 runtime dispatch.
src/​lite/​fp16_distance_avx512.cpp	Adapts AVX512 half-distance kernel.
src/​lite/​fp16_distance_avx2.cpp	Adapts AVX2 half-distance kernel.
src/​lite/​fp16_distance_avx.cpp	Adapts AVX half-distance kernel.
src/​lite/​fp16_codec.h	Adds validated FP16 conversion.
src/​lite/​bruteforce_backend.cpp	Implements exact search and CRUD.
src/​lite/​backend.h	Defines backend interface.
src/​lite/​backend_utils.h	Shares validation and error helpers.
src/​io/​cache/​optional_page_cache_test.cpp	Replaces sleep-based coordination.
src/​datacell/​flatten_datacell.h	Handles empty query batches.
src/​datacell/​flatten_datacell_test.cpp	Tests empty-batch behavior.
lite/​tools/​test_collect_coverage.py	Tests coverage and CI contracts.
lite/​tools/​collect_coverage.py	Enforces scoped coverage threshold.
lite/​tools/​check_tidy.py	Checks configured Lite units.
lite/​README.md	Summarizes usage and limitations.
lite/​example/​rabitq_example.cpp	Demonstrates RaBitQ lifecycle.
lite/​example/​main.cpp	Demonstrates installed API usage.
lite/​example/​CMakeLists.txt	Configures installed consumer.
lite/​CMakeLists.txt	Builds and installs standalone libraries.
include/​vsag/​lite/​index.h	Defines public Lite API.
docs/​docs/​zh/​src/​SUMMARY.md	Links Chinese Lite guides.
docs/​docs/​zh/​src/​development/​lite_rabitq_design.md	Documents RaBitQ implementation boundaries.
docs/​docs/​zh/​src/​development/​lite_first.md	Documents Lite architecture and usage.
docs/​docs/​en/​src/​SUMMARY.md	Links English Lite guides.
docs/​docs/​en/​src/​development/​lite_rabitq_design.md	Documents RaBitQ implementation boundaries.
docs/​docs/​en/​src/​development/​lite_first.md	Documents Lite architecture and usage.
.github/​workflows/​pr-simd-coverage.yml	Compares actual merge parents.
.github/​workflows/​lite.yml	Adds standalone validation matrix.
.github/​codecov.yml	Adds Lite coverage component.

_{Review effort: Balanced}