Skip to content

refactor(hnsw): use turbo for distance calculation - #735

Open
richyreachy wants to merge 24 commits into
alibaba:mainfrom
richyreachy:refactor/hnsw_on_turbo
Open

richyreachy wants to merge 24 commits into
alibaba:mainfrom
richyreachy:refactor/hnsw_on_turbo

Conversation

@richyreachy

@richyreachy richyreachy commented Sep 9, 2026

Copy link
Copy Markdown
Collaborator

Summary

This PR starts migrating HNSW distance calculation from the legacy IndexMetric callback mechanism to the Turbo quantizer interface.

The goal is to make quantizers own vector encoding, query preprocessing, distance dispatch, and dequantization, allowing the old converter/reformer and direct metric invocation paths to be removed as the remaining quantizers are migrated.

What changed

  • Extend HNSW to accept a Turbo quantizer as its distance provider.
  • Route all relevant HNSW distance operations through the quantizer interface:
    • data-to-data distance during graph construction
    • data-to-query distance during search
    • batch data-to-query distance
    • brute-force search distance
  • Let the quantizer manage vector and query encoding instead of invoking the legacy converter/reformer pipeline.
  • Use the quantizer to dequantize fetched vectors and search results.
  • Refresh quantizer-backed distance functions when pooled HNSW contexts are reused.
  • Carry quantizers through HNSW merge and reducer operations.
  • Persist quantizer metadata so reopened indexes restore the correct distance implementation.
  • Detect legacy HNSW indexes without quantizer metadata and reopen them using the old pipeline for backward compatibility.
  • Force-link Turbo into the Python extension on Linux, macOS, and Windows so factory registrations are retained.

Current migration scope

The new quantizer-owned distance path is currently enabled for dense FP32 HNSW indexes using:

  • L2 or cosine distance
  • rotation disabled
  • internal vector storage

Other configurations temporarily continue to use the legacy distance path until their Turbo quantizers are integrated.

Motivation

Previously, HNSW distance calculation was spread across converters, reformers, IndexMetric, and streamer-level function callbacks. This made encoding and distance dispatch separate concerns and required HNSW to understand implementation-specific details.

Moving distance calculation behind the Turbo quantizer interface provides one owner for:

  • vector representation
  • query preprocessing
  • single and batch distance kernels
  • runtime SIMD dispatch
  • vector reconstruction

This simplifies HNSW and establishes a common path for removing the old distance invocation mechanism.

Compatibility

  • Existing HNSW indexes without Turbo quantizer metadata continue to open through the legacy converter/reformer path.
  • Newly created eligible indexes persist their quantizer metadata and restore the Turbo distance path after reopening.
  • Unsupported configurations retain their existing behavior during the migration.

@richyreachy richyreachy changed the title refactor(hnsw): use turbo quantizer for distance calculation refactor(hnsw): use turbo for distance calculation Sep 9, 2026
case QuantizerType::kInt8:
return "Int8Quantizer";
case QuantizerType::kInt4:
return "Int4Quantizer";

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

将 INT4 内积 HNSW 合并到 INT4 L2 Flat 时,MixedStreamerReducer 根据量化器名称和记录尺寸判定可直接复制,但两种度量的 INT4 尾部字段含义不同。切换到 Turbo 后,这条路径会跳过必要的重新编码。
实测 36 维向量 [1, 0, …] 合并后与自身的距离为 −10.1733,直接构建及旧实现对照均约为 0。建议合并兼容性判断增加度量检查,不一致时解码并重新编码。

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

已修复。兼容性判断增加了 metric 一致性检查,跨 metric 合并时会先用源量化器解码,再用目标量化器重新编码;同 metric 的直接复制路径保留。

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.

2 participants