Skip to content

fix: correct distance-to-score conversion for l2 and inner_product metrics in SeekDBStore#8

Open
knqiufan wants to merge 1 commit intoob-labs:mainfrom
knqiufan:fix/seekdb-distance-score
Open

fix: correct distance-to-score conversion for l2 and inner_product metrics in SeekDBStore#8
knqiufan wants to merge 1 commit intoob-labs:mainfrom
knqiufan:fix/seekdb-distance-score

Conversation

@knqiufan
Copy link
Copy Markdown

@knqiufan knqiufan commented Apr 3, 2026

Summary

  • Problem: SeekDBStore.search() hardcoded Math.max(0, 1 - distance) for score conversion, which only works for cosine distance. When configured with l2 or inner_product, similarity scores are incorrect, causing unreliable search ranking and threshold filtering.
  • Fix: Store the configured distance metric in the instance and add a distanceToScore() method with metric-specific formulas, matching the Python OceanBase implementation:
    • cosine: max(0, 1 - d/2) — distance range [0, 2]
    • l2: 1 / (1 + d) — distance range [0, +∞)
    • inner_product: clamp((-d + 1) / 2, 0, 1) — negative distance convention
  • Add unit tests covering all three metrics plus null/edge cases.

Changed files

File Change
src/storage/seekdb/seekdb.ts Add distanceMetric field, distanceToScore() method, update search()
tests/unit/storage/seekdb.test.ts Add distanceToScore conversion test suite (5 cases)

Test plan

  • All 344 existing tests pass (32 files, 7 skipped)
  • New distanceToScore tests cover cosine, l2, inner_product, and null input
  • Cosine search behavior unchanged (existing score conversion tests still pass)

…trics in SeekDBStore

The search score calculation previously assumed cosine distance
(`Math.max(0, 1 - distance)`), producing incorrect similarity scores
when SeekDB is configured with l2 or inner_product distance metrics.

Add metric-aware `distanceToScore()` that matches the Python OceanBase
implementation:
- cosine:  max(0, 1 - d/2)
- l2:      1 / (1 + d)
- inner_product: clamp((-d + 1) / 2, 0, 1)
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