Skip to content

fix(core): L2-normalize OpenAI-compatible embedding vectors - #1869

Open
MbappeWU wants to merge 1 commit into
basicmachines-co:mainfrom
MbappeWU:fix/1862-openai-embed-l2-normalize
Open

MbappeWU wants to merge 1 commit into
basicmachines-co:mainfrom
MbappeWU:fix/1862-openai-embed-l2-normalize

Conversation

@MbappeWU

Copy link
Copy Markdown
Contributor

Summary

OpenAIEmbeddingProvider.embed_documents returned API vectors as-is. Against api.openai.com that is invisible (OpenAI returns unit vectors), but OpenAI-compatible endpoints such as Volcengine Ark / doubao can return unnormalized vectors. The sqlite distance→similarity formula (1 - L²/2) then scores every neighbor near zero, so semantic/hybrid search silently returns no hits.

This is the same contract FastEmbed (#1023) and LiteLLM already honor.

Fixes #1862

Changes

  • L2-normalize each vector in OpenAIEmbeddingProvider.embed_documents after batches are assembled and before the dimension check (mirror LiteLLMEmbeddingProvider).
  • Zero vectors stay zero; positive norms become unit vectors.
  • Regression tests: unnormalized [3,4,0] → [0.6,0.8,0]; already-unit and zero vectors unchanged; concurrent batch order still preserved.

Test plan

  • uv run pytest tests/repository/test_openai_provider.py -q → 35 passed
  • uv run ruff check / ruff format --check on touched files → clean
  • CI

Notes

  • Red→green: the new L2 test failed before the production edit (provider returned raw [3,4,0]), then the full file suite passed.

OpenAIEmbeddingProvider now unit-normalizes embeddings so non-OpenAI
OpenAI-compatible endpoints (e.g. Ark/doubao) satisfy the sqlite
distance-to-similarity contract (same as FastEmbed/LiteLLM).

Fixes basicmachines-co#1862

Signed-off-by: MbappeWU <MbappeWU@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@MbappeWU

Copy link
Copy Markdown
Contributor Author

I have read the CLA Document and I hereby sign the CLA

@MbappeWU

Copy link
Copy Markdown
Contributor Author

@CLAassistant check

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 25, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ⚠️ Failed 2026-10-25T19:20:10.478616Z
We couldn’t complete this review. Comment @codex review to try again.
3ee05e8 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@CLAassistant

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

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.

OpenAI-compatible embedding provider: unnormalized vectors from non-OpenAI endpoints (Ark/doubao) silently break semantic search

2 participants