Skip to content

fix(index): pass PQ num_bits through distributed build#5215

Draft
ddupg wants to merge 1 commit into
lance-format:mainfrom
ddupg:fix/pq-num-bits
Draft

fix(index): pass PQ num_bits through distributed build#5215
ddupg wants to merge 1 commit into
lance-format:mainfrom
ddupg:fix/pq-num-bits

Conversation

@ddupg

@ddupg ddupg commented Jul 2, 2026

Copy link
Copy Markdown
Contributor

Background

While building vector indexes with Ray distributed indexing, we found that create_index(..., num_bits=4) did not apply the requested bit width to global PQ training. Segment builds could receive num_bits=4, but the shared global PQ codebook was still trained through the default 8-bit path.

The PQ codebook is parameterized by num_bits: 4-bit PQ should use 16 centroids per sub-vector, while 8-bit PQ uses 256. If global training and worker segment builds disagree, the distributed index can reuse PQ artifacts that do not match the requested build settings, which can hurt quantization/index quality.

This depends on lance-format/lance#7583, which adds the Python/PyO3 num_bits support needed by the global PQ training call. This PR should wait for that Lance change to land before moving forward.

Summary

  • add num_bits to distributed vector index creation and pass it to global PQ training
  • pass the same num_bits to worker segment builds for compressed vector indexes
  • update nested-vector PQ training and sample-size validation to use the configured PQ bit width

Tests

  • uv run --frozen pytest tests/test_vector_index_options.py::test_create_index_uses_sample_rate_and_num_bits_for_global_training
  • uv run --frozen pytest 'tests/test_distributed_indexing.py::test_build_distributed_vector_index[IVF_PQ]'
  • uv run --frozen ruff check lance_ray/index.py tests/test_distributed_indexing.py tests/test_vector_index_options.py
  • uv run --frozen ruff format --check lance_ray/index.py tests/test_distributed_indexing.py tests/test_vector_index_options.py

@github-actions github-actions Bot added the bug Something isn't working label Jul 2, 2026
@ddupg ddupg force-pushed the fix/pq-num-bits branch from 91922df to 7f08c80 Compare July 2, 2026 12:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant