Skip to content

Feat: blockwise quantization recall restore#80

Merged
dev07060 merged 8 commits into
mainfrom
feat/blockwise-quantization-recall-restore
Jul 3, 2026
Merged

Feat: blockwise quantization recall restore#80
dev07060 merged 8 commits into
mainfrom
feat/blockwise-quantization-recall-restore

Conversation

@dev07060

@dev07060 dev07060 commented Jul 3, 2026

Copy link
Copy Markdown
Owner

PR Description: Restore HNSW Index Recall & Implement Block-wise Quantization

This PR restores the semantic search recall on the balanced wiki evaluation dataset (recovering from a degraded state back to 1.000) and integrates a backward-compatible, block-wise scalar quantization (Q8_0 style) pipeline.


1. Core Problem & Resolution

A. Compound Distortion Loop (HNSW Recall Recovery)

  • Issue: When the vector_quant_i8 feature was active, index rebuilding fetched the lossy i8 quantized vectors and dequantized them in memory to construct the $f32$ HNSW graph. This caused cumulative quantization distortion in HNSW's topology, damaging search paths.
  • Resolution: Re-routed HNSW index rebuilding in both source_rag.rs and simple_rag.rs to load the original high-precision $f32$ embeddings (chunks.embedding) directly from the database.

B. Outlier Vulnerability (Block-wise Quantization)

  • Issue: Uniform 8-bit scalar quantization calculated a single scale factor across all 768 dimensions. Global outliers compressed the dynamic range of all other dimensions, flattening meaningful vector resolutions.
  • Resolution: Implemented Block-wise Quantization (GGML Q8_0 style). Vectors are partitioned into 24 blocks of 32 elements, each with an independent scale factor.

C. Zero-Schema Database Migration & Backward Compatibility

  • Issue: Adding database columns for block scales would lock sqlite databases on mobile clients or break existing setups.
  • Resolution: Packed scales directly into the existing chunks.embedding_i8 blob (864 bytes for a 768-dim vector). The similarity kernel checks the blob's size at runtime:
    • 768 bytes: Fallback to legacy uniform cosine math using the legacy scale.
    • 864 bytes: Parses packed scales per block for block-wise cosine dot products.

2. File-by-File Changes

Rust Core (rag_engine_flutter / rust_builder)

  • vector_quant.rs:
    • Redefined quantize_f32_to_u8_blob under #[cfg(feature = "vector_quant_i8")] to output the 864-byte packed block-wise format.
    • Added QueryQ8 struct for precomputing block-wise quantized representations of search queries.
    • Added cosine_similarity_q8 similarity kernel featuring the backward compatibility gate.
    • Added test_blockwise_cosine_similarity unit test verifying mathematical parity ($err < 0.005$ vs $f32$).
  • source_rag.rs:
    • Updated HNSW rebuild to bypass embedding_i8 dequantization.
    • Integrated QueryQ8 and cosine_similarity_q8 inside the exact-scan pipeline.
  • simple_rag.rs:
    • Updated HNSW rebuild to bypass embedding_i8 dequantization.
    • Integrated QueryQ8 and cosine_similarity_q8 inside simple search paths.
  • hybrid_search.rs:
    • Integrated QueryQ8 and cosine_similarity_q8 inside the hybrid exact-scan loop.
  • runtime_info.rs:
    • Added dynamic feature mapping for hnsw_streaming_rebuild.

Packaging & Release

  • rust_builder/pubspec.yaml: Version bumped to 0.19.2.
  • pubspec.yaml (root): Version bumped to 0.20.0 and updated rag_engine_flutter constraint to ^0.19.2.
  • CHANGELOGs: Documented the release notes.
  • README.md & docs/guides/quick_start.md: Updated to show extended platform support (Windows & Linux).

3. Verification & Benchmark Status

Core Unit Tests

All 154 Rust cargo unit tests pass:

cargo test --lib -- --test-threads=1

On-Device Relevance Test (Flutter Drive macOS Profile)

All relevance tests pass:

  • default_hybrid Profile: Semantic class passage_recall@10 is restored to 1.000 (100% recall parity).
  • vector_only Profile: Semantic class passage_recall@10 is restored to 0.750 (up from degraded 0.625 in the uniform quantization build).

dev07060 added 5 commits June 29, 2026 10:49
… (Q8_0)

- Re-route HNSW rebuilds in simple/source RAG to original f32 embeddings, recovering semantic search recall to 1.000 (resolving compound distortion loop).
- Implement block-wise quantization (GGML Q8_0 style, 24 blocks of 32 elements) to reduce outlier sensitivity.
- dynamic cosine similarity kernel supporting dynamic fallback for legacy 768-byte uniform and 864-byte block-wise blobs.
- Platform-gate HNSW streaming rebuild for macOS default, opt-in elsewhere.
- Bump versions to 0.20.0 (root) and 0.19.2 (rust_builder).
- Add support for Windows/Linux platforms.
@dev07060 dev07060 self-assigned this Jul 3, 2026
@dev07060 dev07060 merged commit 5cd6fd7 into main Jul 3, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant