feat: Remote text embeddings compute

[mattkjames7]

Add remote embedding providers to the embeddings query module

Adds support for any embedding provider supported by LiteLLM — OpenAI, Azure OpenAI, Ollama, Cohere, Voyage, Mistral, Jina, Bedrock, Vertex AI, Hugging Face, and any OpenAI‑compatible endpoint — while keeping the local sentence-transformers path unchanged.

Summary

• Routing decided by model_name: a LiteLLM provider prefix (e.g. openai/text-embedding-3-small, ollama/nomic-embed-text) routes remote; bare names and HF paths (e.g. BAAI/bge-small-en-v1.5) stay local.
• New config keys (only used on the remote path): api_base, input_type, dimensions, timeout, num_retries, normalize, remote_batch_size, concurrency.
• Credentials read from the Memgraph process environment only (matches llm.py — OPENAI_API_KEY, COHERE_API_KEY, etc.); no api_key config key exists, so secrets cannot leak into Cypher or query logs.
• Remote calls chunked and fanned out with a per-call ThreadPoolExecutor (default concurrency=4), L2-normalized client-side by default to match local behavior.
• dimension return field is now Nullable[int] — procs surface success=false, dimension=null on failure rather than throwing.
• embeddings.model_info probes remote providers once for their dimension, cached per (model_name, api_base).
• Zero new dependencies — litellm is already pinned in mage/python/requirements*.txt (used by llm.py).

Backwards compatibility

Zero Cypher changes required. CALL embeddings.node_sentence(null, {}) and CALL embeddings.text([...], {}) keep the local path with the same default model and return shape.

Tests

• Two new YAML e2e tests that exercise the remote route without network egress (api_base: "http://127.0.0.1:1" → ECONNREFUSED → graceful success=false). These run in CI.
• Two opt-in pytest files for real providers, skipped unless OPENAI_API_KEY / MAGE_E2E_OLLAMA=1 are set. Not run in CI; intended for local verification.

[mattkjames7]

Tracking

• [Link to Epic/Issue]

Standard development

• Update unit/E2E tests
• Compare the benchmarking results between the master branch this branch

CI Testing Labels

• Select the appropriate CI test labels (CI -build=build-name -test=test-suite)

Documentation checklist

• Add the documentation label
• Add the bug / feature label
• Add the milestone for which this feature is intended
  • If not known, set for a later milestone
• Write a release note, including added/changed clauses
  • Added the ability to request text embeddings from remote APIs using litellm. Users should export the relevant key(s) for the API(s) that they intend to request embeddings from when launching the memgraph/memgraph-mage container, e.g. -e OPENAI_API_KEY=$OPENAI_API_KEY, then set model_name in the format "{provider}/{model-name}" (see here for valid providers and their models) #4064
• feat: Add remote embedding computation to the embeddings module documentation#1598
  • Is back linked to this development PR

[Copilot]

Pull request overview

Adds LiteLLM-backed remote embedding providers to the embeddings query module while preserving the existing local sentence-transformers execution path, plus CI-safe tests for remote failure behavior.

Changes:

• Route embedding computation to LiteLLM remote providers based on model_name prefixes; keep bare/HF-style names local.
• Add remote-only configuration options (e.g., api_base, timeout, num_retries, remote_batch_size, concurrency, normalize) and remote model dimension probing with caching.
• Add e2e tests for graceful remote failures and opt-in pytest e2e tests for real OpenAI/Ollama providers.

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
release/package/mgbuild.sh	Ensures build deps are installed in the container before building the gssapi wheel.
mage/python/embeddings.py	Implements LiteLLM remote routing, batching/concurrency, client-side normalization, nullable dimension, and remote model-info probing/cache.
mage/tests/e2e/embeddings_test/test_remote_text_failure/test.yml	CI-safe e2e test verifying remote embeddings.text failure returns success=false with null outputs.
mage/tests/e2e/embeddings_test/test_remote_node_sentence_failure/test.yml	CI-safe e2e test verifying remote embeddings.node_sentence failure doesn’t write embeddings.
mage/tests/e2e/embeddings_test/test_remote_node_sentence_failure/input.cyp	Fixture graph data for the remote node_sentence failure test.
mage/tests/e2e/embeddings_test/test_remote_openai.py	Opt-in real-provider e2e tests for OpenAI embeddings/model_info/node_sentence.
mage/tests/e2e/embeddings_test/test_remote_ollama.py	Opt-in real-provider e2e tests for Ollama embeddings/model_info/node_sentence.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[antejavor]

A few comments.

[sonarqubecloud]

Quality Gate failed

Failed conditions
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE