Skip to content

test(core): benchmark multilingual embeddings - #1392

Merged
phernandez merged 14 commits into
mainfrom
1372-multilingual-benchmark
Aug 30, 2026
Merged

test(core): benchmark multilingual embeddings#1392
phernandez merged 14 commits into
mainfrom
1372-multilingual-benchmark

Conversation

@phernandez

@phernandez phernandez commented Aug 30, 2026

Copy link
Copy Markdown
Member

Why

Basic Memory's default FastEmbed model, BAAI/bge-small-en-v1.5, is intentionally small and
English-focused. Issue #1372 asks us to evaluate multilingual alternatives from reproducible
evidence before changing any default or planning a Cloud-wide reindex.

This PR supplies the bounded Core evidence: a checked-in judged corpus, a production-path harness,
and baseline/candidate results across local and hosted storage adapters. BGE remains the default.

Advances #1372. Cloud capacity and development validation are tracked separately in
basic-memory-cloud#1898.

What Changed

  • Added multilingual-retrieval-v2: 17 notes and 23 judged queries covering English, Chinese,
    Japanese, Korean, Arabic, Russian, Spanish, Thai, mixed-language text, cross-language retrieval,
    chunk boundaries, and negative queries.
  • Added an isolated FastEmbed benchmark for SQLite/sqlite-vec, PostgreSQL/pgvector, and
    PostgreSQL/Milvus, with vector and hybrid retrieval modes.
  • Added comparison-compatible JSONL measurements for recall@5, MRR@10, threshold behavior,
    latency, model load, indexing throughput, RSS, cache size, and vector storage.
  • Documented the initial BGE versus multilingual MiniLM findings and the bounded Cloud follow-up.
  • Updated the user-facing semantic-search guide with exact MiniLM opt-in/reindex commands while
    explicitly retaining BGE as the default.

Implementation Details

  • Each model runs in a separate pytest process so cold-load and RSS measurements are not polluted
    by another ONNX model.
  • Ranking quality is measured with no cutoff, then the query is repeated at the configured
    production cutoff. This separates embedding/ranking failures from threshold-filtered empties.
  • The Milvus case is PostgreSQL metadata/FTS plus the production first-party Milvus adapter backed
    by an isolated Milvus Lite database. It is not modeled as a replacement SQL backend.
  • Model cases carry dimensions, prefixes, catalog artifact identity, and license metadata. E5's
    asymmetric passage:/query: prefixes are part of its explicit contract.
  • Jina embeddings v3 is excluded because the production provider does not yet express its distinct
    retrieval-query/retrieval-passage tasks and its license requires separate Cloud clearance.
  • SQLite storage measurements use dbstat to count only the vector manifest, its indexes,
    sqlite-vec shadow tables, and their schema-owned autoindexes; unrelated database and FTS pages
    are excluded.
  • The long Korean regression is split with the production chunker and only awards relevance when
    the returned matched chunk contains the later legal-hold passage.
  • Peak RSS uses the Windows process peak working set when resource.getrusage is unavailable.
  • The MiniLM opt-in steps explicitly clear model-specific prefixes before rebuilding embeddings.
  • Model-cache storage is measured from the effective benchmark configuration and follows
    FastEmbed's Hugging Face-first source order when its cataloged URL-fallback cache also exists.
  • Milvus storage includes both its vector database files and the required PostgreSQL chunk
    manifest.
  • The SQLite physical-storage contract checks for optional dbstat and loadable-extension
    capabilities and skips only that assertion when the platform SQLite build lacks either one.
  • The comparator now treats empty, false-positive, wrong-top, memory, cache, and storage metrics as
    lower-is-better.

Initial evidence favors multilingual MiniLM for further Cloud testing: it preserved the English
baseline, improved vector MRR@10 from 0.7684 to 0.8684, halved the wrong-top rate, and accepted
no negative queries. The result was identical across sqlite-vec, pgvector, and Milvus. It is not
selected as a new default because neither long-note boundary query retrieved the relevant later
passage as the highest-scoring chunk, the 0.55 cutoff hid three other correctly ranked positives,
and its cache/RSS cost needs Cloud-equivalent validation.

Testing

Automated

  • UV_PYTHON=3.12 just fast-check: passed.
  • UV_PYTHON=3.12 just typecheck: passed.
  • UV_PYTHON=3.12 BASIC_MEMORY_ENV=test LOGFIRE_IGNORE_NO_CONFIG=1 uv run --extra milvus pytest -p pytest_mock -q --no-cov --import-mode=importlib test-int/semantic/test_multilingual_benchmark_contract.py: 21 passed.
  • UV_PYTHON=3.12 BASIC_MEMORY_ENV=test LOGFIRE_IGNORE_NO_CONFIG=1 uv run --extra milvus pytest -p pytest_mock -q --no-cov --import-mode=importlib test-int/semantic/test_semantic_quality.py -k "sqlite-fastembed or postgres-fastembed": 2 passed, 3 deselected.

Benchmark runs

  • just benchmark-multilingual-compare sqlite vector 0.55: BGE and MiniLM passed.
  • just benchmark-multilingual-compare postgres vector 0.55: BGE and MiniLM passed.
  • just benchmark-multilingual-compare milvus vector 0.55: BGE and MiniLM passed.
  • just benchmark-multilingual-compare sqlite hybrid 0.55: BGE and MiniLM passed.
  • just benchmark-multilingual-compare postgres hybrid 0.55: BGE and MiniLM passed.
  • just benchmark-multilingual-compare milvus hybrid 0.55: BGE and MiniLM passed.
  • git diff --check: passed.

Generated .benchmarks/*.jsonl artifacts are intentionally ignored; the reviewed results and
machine context are recorded in docs/multilingual-embedding-benchmark.md.

Risks / Follow-ups

  • The corpus is deliberately small. It establishes directional quality and adapter parity, not a
    production latency SLO or HNSW capacity result.
  • MiniLM's model cache and observed RSS are materially larger than BGE's.
  • FastEmbed 0.8 reports a MiniLM pooling change relative to older releases, so any rollout must pin
    and record the exact provider/model behavior.
  • The model-specific similarity threshold still needs calibration on a larger judged set.
  • Cloud development testing against the existing Moby Dick project is scoped in
    basic-memory-cloud#1898; this PR makes no production, fleet-reindex, or default-model change.

Signed-off-by: phernandez <paul@basicmachines.co>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Aug 30, 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 Completed 2026-08-30T21:13:49.672880Z aafa096 Manual request
ℹ️ 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.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f7138d80c2

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread test-int/semantic/multilingual_benchmark.py Outdated
Comment thread test-int/semantic/multilingual_benchmark.py Outdated
Comment thread test-int/semantic/test_multilingual_embedding_benchmark.py Outdated
Signed-off-by: phernandez <paul@basicmachines.co>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7a6b7609b5

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread test-int/semantic/multilingual_corpus.py
Signed-off-by: phernandez <paul@basicmachines.co>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c703e56f1f

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/semantic-search.md
Comment thread test-int/semantic/multilingual_benchmark.py
Signed-off-by: phernandez <paul@basicmachines.co>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3aa520ca1a

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread test-int/semantic/multilingual_benchmark.py Outdated
Signed-off-by: phernandez <paul@basicmachines.co>
Signed-off-by: phernandez <paul@basicmachines.co>
@phernandez

Copy link
Copy Markdown
Member Author

Fixed the Windows SQLite integration failure in afd4dbb. This was not Milvus-related: the Windows Python SQLite build omits the optional dbstat virtual table used only for the benchmark physical-storage assertion. That single assertion now capability-skips when ENABLE_DBSTAT_VTAB is unavailable; the rest of the Windows SQLite integration suite remains enabled. Local evidence: 17 contract tests passed, just typecheck passed, and git diff --check passed.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: afd4dbb88a

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread test-int/semantic/multilingual_benchmark.py Outdated
Signed-off-by: phernandez <paul@basicmachines.co>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 55853e3846

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread test-int/semantic/test_multilingual_benchmark_contract.py Outdated
Signed-off-by: phernandez <paul@basicmachines.co>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a17d05d3f5

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread test-int/semantic/test_multilingual_benchmark_contract.py Outdated
Signed-off-by: phernandez <paul@basicmachines.co>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 70b555350d

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread test-int/semantic/multilingual_benchmark.py Outdated
Signed-off-by: phernandez <paul@basicmachines.co>
@phernandez

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ba26e78f87

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread test-int/semantic/multilingual_benchmark.py Outdated
Comment thread test-int/semantic/test_multilingual_embedding_benchmark.py Outdated
Comment thread test-int/semantic/multilingual_benchmark.py Outdated
Signed-off-by: phernandez <paul@basicmachines.co>
@phernandez

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 253183d499

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread test-int/semantic/multilingual_benchmark.py Outdated
Comment thread test-int/semantic/multilingual_corpus.py
Signed-off-by: phernandez <paul@basicmachines.co>
@phernandez

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4c9d11a4d1

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread test-int/semantic/multilingual_benchmark.py Outdated
Signed-off-by: phernandez <paul@basicmachines.co>
@phernandez

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d05ab12d79

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs/multilingual-embedding-benchmark.md Outdated
Signed-off-by: phernandez <paul@basicmachines.co>
@phernandez

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: aafa0967c2

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@phernandez
phernandez merged commit 8822b20 into main Aug 30, 2026
32 checks passed
@phernandez
phernandez deleted the 1372-multilingual-benchmark branch August 30, 2026 21:37
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