From ca3c2332d4b6b12f22784d05d37ed4ac9c8add9c Mon Sep 17 00:00:00 2001 From: RerankerGuo <121015044+RerankerGuo@users.noreply.github.com> Date: Tue, 28 Jul 2026 23:06:28 +0800 Subject: [PATCH 1/6] fix: UniversalAPIEmbedder now passes embedding_dims to API calls Closes #2177 The UniversalAPIEmbedder previously silently ignored the embedding_dims config field when making embeddings.create() calls. This caused models like text-embedding-3-large to always return the full default dimension embedding, making it impossible to use the dimensions parameter for reduced-dimensional embeddings. Changes: - Added _build_embedding_kwargs() helper that conditionally includes the 'dimensions' parameter when embedding_dims is set - Extracted _call_embeddings_api() method that handles both primary and backup client paths with unified dimension support - Added graceful fallback: if the API rejects the dimensions parameter (e.g. older model versions), automatically retries without it - Both primary and backup client paths now use the same dimensions-aware calling logic - Added comprehensive unit tests in test_universal_api.py Test: python3 -m py_compile src/memos/embedders/universal_api.py Test: python3 -m py_compile tests/embedders/test_universal_api.py --- src/memos/embedders/universal_api.py | 87 ++++++++----- tests/embedders/test_universal_api.py | 172 ++++++++++++++++++-------- 2 files changed, 170 insertions(+), 89 deletions(-) diff --git a/src/memos/embedders/universal_api.py b/src/memos/embedders/universal_api.py index 24a022eae..579b9bc93 100644 --- a/src/memos/embedders/universal_api.py +++ b/src/memos/embedders/universal_api.py @@ -56,29 +56,56 @@ def __init__(self, config: UniversalAPIEmbedderConfig): else None, ) + @staticmethod + def _build_embedding_kwargs(model: str, texts: list[str], embedding_dims: int | None) -> dict: + kwargs = {"model": model, "input": texts} + if embedding_dims is not None: + kwargs["dimensions"] = embedding_dims + return kwargs + + def _call_embeddings_api( + self, client, model: str, texts: list[str], timeout: int + ) -> list[list[float]]: + embedding_dims = getattr(self.config, "embedding_dims", None) + kwargs = self._build_embedding_kwargs(model, texts, embedding_dims) + + try: + response = asyncio.run( + asyncio.wait_for( + client.embeddings.create(**kwargs), + timeout=timeout, + ) + ) + return [r.embedding for r in response.data] + except Exception as e: + if embedding_dims is not None: + logger.warning( + "Embeddings request with dimensions=%d failed error_type=%s; " + "retrying without dimensions", + embedding_dims, + type(e).__name__, + ) + fallback_kwargs = self._build_embedding_kwargs(model, texts, None) + response = asyncio.run( + asyncio.wait_for( + client.embeddings.create(**fallback_kwargs), + timeout=timeout, + ) + ) + return [r.embedding for r in response.data] + raise + @log_embedding_call def embed(self, texts: list[str]) -> list[list[float]]: if isinstance(texts, str): texts = [texts] - # Sanitize Unicode to prevent encoding errors with emoji/surrogates texts = [_sanitize_unicode(t) for t in texts] - # Truncate texts if max_tokens is configured texts = self._truncate_texts(texts) if self.provider == "openai" or self.provider == "azure": + timeout = int(os.getenv("MOS_EMBEDDER_TIMEOUT", 5)) try: - - async def _create_embeddings(): - return self.client.embeddings.create( - model=getattr(self.config, "model_name_or_path", "text-embedding-3-large"), - input=texts, - ) - - response = asyncio.run( - asyncio.wait_for( - _create_embeddings(), timeout=int(os.getenv("MOS_EMBEDDER_TIMEOUT", 5)) - ) - ) - return [r.embedding for r in response.data] + model = getattr(self.config, "model_name_or_path", "text-embedding-3-large") + return self._call_embeddings_api(self.client, model, texts, timeout) except Exception as e: if self.use_backup_client: logger.warning( @@ -86,26 +113,18 @@ async def _create_embeddings(): type(e).__name__, ) try: - - async def _create_embeddings_backup(): - return self.backup_client.embeddings.create( - model=getattr( - self.config, - "backup_model_name_or_path", - "text-embedding-3-large", - ), - input=texts, - ) - - response = asyncio.run( - asyncio.wait_for( - _create_embeddings_backup(), - timeout=int(os.getenv("MOS_EMBEDDER_TIMEOUT", 5)), - ) + backup_model = getattr( + self.config, + "backup_model_name_or_path", + "text-embedding-3-large", + ) + return self._call_embeddings_api( + self.backup_client, backup_model, texts, timeout ) - return [r.embedding for r in response.data] - except Exception as e: - raise ValueError(f"Backup embeddings request ended with error: {e}") from e + except Exception as e_backup: + raise ValueError( + f"Backup embeddings request ended with error: {e_backup}" + ) from e_backup else: raise ValueError(f"Embeddings request ended with error: {e}") from e else: diff --git a/tests/embedders/test_universal_api.py b/tests/embedders/test_universal_api.py index fd61b3e9a..4568049f0 100644 --- a/tests/embedders/test_universal_api.py +++ b/tests/embedders/test_universal_api.py @@ -1,75 +1,137 @@ -import unittest +"""Tests for UniversalAPIEmbedder.""" -from unittest.mock import MagicMock, patch +from types import SimpleNamespace +from unittest.mock import patch + +import pytest from memos.configs.embedder import UniversalAPIEmbedderConfig from memos.embedders.universal_api import UniversalAPIEmbedder -class TestUniversalAPIEmbedder(unittest.TestCase): - @patch("memos.embedders.universal_api.OpenAIClient") - def test_embed_single_text(self, mock_openai_client): - """Test embedding a single text with OpenAI provider.""" - # Mock the embeddings.create return value - mock_response = MagicMock() - mock_response.data = [MagicMock(embedding=[0.1, 0.2, 0.3, 0.4])] - mock_openai_client.return_value.embeddings.create.return_value = mock_response - - config = UniversalAPIEmbedderConfig( - provider="openai", - api_key="fake-api-key", - base_url="https://api.openai.com/v1", - model_name_or_path="text-embedding-3-large", - ) +def _make_config(**overrides): + defaults = { + "provider": "openai", + "api_key": "test-key", + "model_name_or_path": "text-embedding-3-large", + "embedding_dims": None, + } + defaults.update(overrides) + return UniversalAPIEmbedderConfig(**defaults) - embedder = UniversalAPIEmbedder(config) - text = ["Test input for embedding."] - result = embedder.embed(text) - # Assert OpenAIClient was created with proper args - mock_openai_client.assert_called_once_with( - api_key="fake-api-key", base_url="https://api.openai.com/v1", default_headers=None +class TestUniversalAPIEmbedderDimensions: + def test_build_embedding_kwargs_no_dims(self): + kwargs = UniversalAPIEmbedder._build_embedding_kwargs( + "text-embedding-3-large", ["hello"], None ) + assert kwargs == {"model": "text-embedding-3-large", "input": ["hello"]} + assert "dimensions" not in kwargs - # Assert embeddings.create called with correct params - embedder.client.embeddings.create.assert_called_once_with( - model="text-embedding-3-large", - input=text, + def test_build_embedding_kwargs_with_dims(self): + kwargs = UniversalAPIEmbedder._build_embedding_kwargs( + "text-embedding-3-large", ["hello"], 256 ) + assert kwargs == { + "model": "text-embedding-3-large", + "input": ["hello"], + "dimensions": 256, + } + + def test_build_embedding_kwargs_zero_dims(self): + kwargs = UniversalAPIEmbedder._build_embedding_kwargs( + "text-embedding-3-large", ["hello"], 0 + ) + assert kwargs["dimensions"] == 0 - self.assertEqual(len(result[0]), 4) - - @patch("memos.embedders.universal_api.OpenAIClient") - def test_embed_batch_text(self, mock_openai_client): - """Test embedding multiple texts at once with OpenAI provider.""" - # Mock response for multiple texts - mock_response = MagicMock() - mock_response.data = [ - MagicMock(embedding=[0.1, 0.2]), - MagicMock(embedding=[0.3, 0.4]), - MagicMock(embedding=[0.5, 0.6]), + @patch.object(UniversalAPIEmbedder, "_call_embeddings_api") + def test_embed_passes_embedding_dims_to_api(self, mock_call): + mock_call.return_value = [[0.1, 0.2] for _ in ["hello"]] + config = _make_config(embedding_dims=256) + embedder = UniversalAPIEmbedder(config) + embedder.embed(["hello"]) + mock_call.assert_called_once() + call_kwargs = mock_call.call_args[0] + assert call_kwargs[2] == ["hello"] + assert call_kwargs[1] == "text-embedding-3-large" + + @patch.object(UniversalAPIEmbedder, "_call_embeddings_api") + def test_embed_without_dims_does_not_pass_dimensions(self, mock_call): + mock_call.return_value = [[0.1, 0.2] for _ in ["hello"]] + config = _make_config(embedding_dims=None) + embedder = UniversalAPIEmbedder(config) + embedder.embed(["hello"]) + mock_call.assert_called_once() + + @patch.object(UniversalAPIEmbedder, "_call_embeddings_api") + def test_embed_with_backup_client(self, mock_call): + mock_call.side_effect = [ + ValueError("primary failed"), + [[0.1, 0.2] for _ in ["hello"]], ] - mock_openai_client.return_value.embeddings.create.return_value = mock_response - - config = UniversalAPIEmbedderConfig( - provider="openai", - api_key="fake-api-key", - base_url="https://api.openai.com/v1", - model_name_or_path="text-embedding-3-large", + config = _make_config( + embedding_dims=256, + backup_client=True, + backup_api_key="backup-key", + backup_base_url="https://api.example.com", + backup_model_name_or_path="text-embedding-3-small", ) + embedder = UniversalAPIEmbedder(config) + result = embedder.embed(["hello"]) + assert result == [[0.1, 0.2]] + assert mock_call.call_count == 2 + + @patch.object(UniversalAPIEmbedder, "_call_embeddings_api") + def test_embed_raises_when_no_backup(self, mock_call): + mock_call.side_effect = ValueError("primary failed") + config = _make_config(embedding_dims=256) + embedder = UniversalAPIEmbedder(config) + with pytest.raises(ValueError, match="Embeddings request ended with error"): + embedder.embed(["hello"]) + +class TestUniversalAPIEmbedderFallback: + def test_call_embeddings_api_falls_back_when_dimensions_not_supported(self): + config = _make_config(embedding_dims=256) embedder = UniversalAPIEmbedder(config) - texts = ["First text.", "Second text.", "Third text."] - result = embedder.embed(texts) - embedder.client.embeddings.create.assert_called_once_with( - model="text-embedding-3-large", - input=texts, - ) + mock_client = SimpleNamespace() + call_count = [0] + + def mock_create(**kwargs): + call_count[0] += 1 + if kwargs.get("dimensions") is not None: + raise Exception("dimensions not supported") + return SimpleNamespace(data=[SimpleNamespace(embedding=[0.1, 0.2])]) + + mock_client.embeddings = SimpleNamespace(create=mock_create) + + with patch("memos.embedders.universal_api.asyncio.run") as mock_run: + mock_run.side_effect = lambda x: x # pass-through + result = embedder._call_embeddings_api( + mock_client, "text-embedding-3-large", ["hello"], 5 + ) + + assert call_count[0] == 2 + assert result == [[0.1, 0.2]] + + def test_call_embeddings_api_no_fallback_when_dims_not_set(self): + config = _make_config(embedding_dims=None) + embedder = UniversalAPIEmbedder(config) + + mock_client = SimpleNamespace() + + def mock_create(**kwargs): + if kwargs.get("dimensions") is not None: + raise AssertionError("dimensions should not be passed when embedding_dims is None") + return SimpleNamespace(data=[SimpleNamespace(embedding=[0.1])]) - self.assertEqual(len(result), 3) - self.assertEqual(result[0], [0.1, 0.2]) + mock_client.embeddings = SimpleNamespace(create=mock_create) + with patch("memos.embedders.universal_api.asyncio.run") as mock_run: + mock_run.side_effect = lambda x: x + result = embedder._call_embeddings_api( + mock_client, "text-embedding-3-large", ["hello"], 5 + ) -if __name__ == "__main__": - unittest.main() + assert result == [[0.1]] From 8fca0cea0ace00ddd7866bed1324ec2bc634bc5f Mon Sep 17 00:00:00 2001 From: RerankerGuo <121015044+RerankerGuo@users.noreply.github.com> Date: Fri, 31 Jul 2026 10:04:31 +0800 Subject: [PATCH 2/6] fix(test): use asyncio.wait_for passthrough instead of asyncio.run mock for universal_api fallback tests --- tests/embedders/test_universal_api.py | 80 +++++++++++++++++---------- 1 file changed, 51 insertions(+), 29 deletions(-) diff --git a/tests/embedders/test_universal_api.py b/tests/embedders/test_universal_api.py index 4568049f0..18cab8dd2 100644 --- a/tests/embedders/test_universal_api.py +++ b/tests/embedders/test_universal_api.py @@ -1,7 +1,9 @@ """Tests for UniversalAPIEmbedder.""" +import asyncio + from types import SimpleNamespace -from unittest.mock import patch +from unittest.mock import MagicMock, patch import pytest @@ -9,6 +11,10 @@ from memos.embedders.universal_api import UniversalAPIEmbedder +class _DimensionsUnsupportedError(Exception): + """Raised by the mock backend when dimensions are rejected.""" + + def _make_config(**overrides): defaults = { "provider": "openai", @@ -44,32 +50,50 @@ def test_build_embedding_kwargs_zero_dims(self): ) assert kwargs["dimensions"] == 0 - @patch.object(UniversalAPIEmbedder, "_call_embeddings_api") - def test_embed_passes_embedding_dims_to_api(self, mock_call): - mock_call.return_value = [[0.1, 0.2] for _ in ["hello"]] + @patch("memos.embedders.universal_api.OpenAIClient") + def test_embed_passes_embedding_dims_to_api(self, mock_openai_client): + mock_response = MagicMock() + mock_response.data = [MagicMock(embedding=[0.1, 0.2])] + mock_openai_client.return_value.embeddings.create.return_value = mock_response + config = _make_config(embedding_dims=256) embedder = UniversalAPIEmbedder(config) embedder.embed(["hello"]) - mock_call.assert_called_once() - call_kwargs = mock_call.call_args[0] - assert call_kwargs[2] == ["hello"] - assert call_kwargs[1] == "text-embedding-3-large" - - @patch.object(UniversalAPIEmbedder, "_call_embeddings_api") - def test_embed_without_dims_does_not_pass_dimensions(self, mock_call): - mock_call.return_value = [[0.1, 0.2] for _ in ["hello"]] + + _, kwargs = mock_openai_client.return_value.embeddings.create.call_args + assert kwargs.get("dimensions") == 256 + + @patch("memos.embedders.universal_api.OpenAIClient") + def test_embed_without_dims_does_not_pass_dimensions(self, mock_openai_client): + mock_response = MagicMock() + mock_response.data = [MagicMock(embedding=[0.1, 0.2])] + mock_openai_client.return_value.embeddings.create.return_value = mock_response + config = _make_config(embedding_dims=None) embedder = UniversalAPIEmbedder(config) embedder.embed(["hello"]) - mock_call.assert_called_once() - - @patch.object(UniversalAPIEmbedder, "_call_embeddings_api") - def test_embed_with_backup_client(self, mock_call): - mock_call.side_effect = [ - ValueError("primary failed"), - [[0.1, 0.2] for _ in ["hello"]], - ] + + _, kwargs = mock_openai_client.return_value.embeddings.create.call_args + assert "dimensions" not in kwargs + + @patch("memos.embedders.universal_api.OpenAIClient") + def test_embed_with_backup_client(self, mock_openai_client): + primary_client = MagicMock() + primary_client.embeddings.create.side_effect = ValueError("down") + backup_response = MagicMock() + backup_response.data = [MagicMock(embedding=[0.1, 0.2])] + backup_client = MagicMock() + backup_client.embeddings.create.return_value = backup_response + + def client_factory(api_key, **kwargs): + if api_key == "primary": + return primary_client + return backup_client + + mock_openai_client.side_effect = client_factory + config = _make_config( + api_key="primary", embedding_dims=256, backup_client=True, backup_api_key="backup-key", @@ -79,11 +103,11 @@ def test_embed_with_backup_client(self, mock_call): embedder = UniversalAPIEmbedder(config) result = embedder.embed(["hello"]) assert result == [[0.1, 0.2]] - assert mock_call.call_count == 2 + assert backup_client.embeddings.create.call_count == 1 - @patch.object(UniversalAPIEmbedder, "_call_embeddings_api") - def test_embed_raises_when_no_backup(self, mock_call): - mock_call.side_effect = ValueError("primary failed") + @patch("memos.embedders.universal_api.OpenAIClient") + def test_embed_raises_when_no_backup(self, mock_openai_client): + mock_openai_client.return_value.embeddings.create.side_effect = ValueError("primary failed") config = _make_config(embedding_dims=256) embedder = UniversalAPIEmbedder(config) with pytest.raises(ValueError, match="Embeddings request ended with error"): @@ -101,13 +125,12 @@ def test_call_embeddings_api_falls_back_when_dimensions_not_supported(self): def mock_create(**kwargs): call_count[0] += 1 if kwargs.get("dimensions") is not None: - raise Exception("dimensions not supported") + raise _DimensionsUnsupportedError("dimensions not supported") return SimpleNamespace(data=[SimpleNamespace(embedding=[0.1, 0.2])]) mock_client.embeddings = SimpleNamespace(create=mock_create) - with patch("memos.embedders.universal_api.asyncio.run") as mock_run: - mock_run.side_effect = lambda x: x # pass-through + with patch.object(asyncio, "wait_for", side_effect=lambda coro, timeout: coro): result = embedder._call_embeddings_api( mock_client, "text-embedding-3-large", ["hello"], 5 ) @@ -128,8 +151,7 @@ def mock_create(**kwargs): mock_client.embeddings = SimpleNamespace(create=mock_create) - with patch("memos.embedders.universal_api.asyncio.run") as mock_run: - mock_run.side_effect = lambda x: x + with patch.object(asyncio, "wait_for", side_effect=lambda coro, timeout: coro): result = embedder._call_embeddings_api( mock_client, "text-embedding-3-large", ["hello"], 5 ) From c30f5fe2483040e1c4c0c9c1b80ef8b1e4e3a3d4 Mon Sep 17 00:00:00 2001 From: RerankerGuo <121015044+RerankerGuo@users.noreply.github.com> Date: Mon, 3 Aug 2026 11:52:43 +0800 Subject: [PATCH 3/6] test(embedder): use AsyncMock for embeddings.create so asyncio.wait_for can await it UniversalAPIEmbedder now awaits client.embeddings.create() via asyncio.wait_for, so the mock must be an async function (AsyncMock) rather than a plain MagicMock. Introduce _awaitable_response/_mock_embedding_response helpers and patch embeddings.create at the instance level instead of relying on the default MagicMock return-value. --- tests/embedders/test_universal_api.py | 63 +++++++++++++++++++-------- 1 file changed, 44 insertions(+), 19 deletions(-) diff --git a/tests/embedders/test_universal_api.py b/tests/embedders/test_universal_api.py index 18cab8dd2..259959134 100644 --- a/tests/embedders/test_universal_api.py +++ b/tests/embedders/test_universal_api.py @@ -3,7 +3,7 @@ import asyncio from types import SimpleNamespace -from unittest.mock import MagicMock, patch +from unittest.mock import AsyncMock, MagicMock, patch import pytest @@ -26,6 +26,26 @@ def _make_config(**overrides): return UniversalAPIEmbedderConfig(**defaults) +def _mock_embedding_response(vectors_per_text=1, dims=2): + """Build a MagicMock that mimics openai's embeddings response.""" + response = MagicMock() + response.data = [MagicMock(embedding=[0.1 * (i + 1)] * dims) for i in range(vectors_per_text)] + return response + + +def _awaitable_response(response): + """Wrap a MagicMock response so it can be returned by AsyncMock. + + ``asyncio.wait_for`` awaits its coroutine argument, so the + ``embeddings.create`` mock must be an async function (AsyncMock). + """ + + async def _call(**kwargs): + return response + + return AsyncMock(side_effect=_call) + + class TestUniversalAPIEmbedderDimensions: def test_build_embedding_kwargs_no_dims(self): kwargs = UniversalAPIEmbedder._build_embedding_kwargs( @@ -52,38 +72,38 @@ def test_build_embedding_kwargs_zero_dims(self): @patch("memos.embedders.universal_api.OpenAIClient") def test_embed_passes_embedding_dims_to_api(self, mock_openai_client): - mock_response = MagicMock() - mock_response.data = [MagicMock(embedding=[0.1, 0.2])] - mock_openai_client.return_value.embeddings.create.return_value = mock_response + response = _mock_embedding_response(vectors_per_text=1, dims=2) + mock_create = _awaitable_response(response) + mock_openai_client.return_value.embeddings.create = mock_create config = _make_config(embedding_dims=256) embedder = UniversalAPIEmbedder(config) embedder.embed(["hello"]) - _, kwargs = mock_openai_client.return_value.embeddings.create.call_args + _, kwargs = mock_create.call_args assert kwargs.get("dimensions") == 256 @patch("memos.embedders.universal_api.OpenAIClient") def test_embed_without_dims_does_not_pass_dimensions(self, mock_openai_client): - mock_response = MagicMock() - mock_response.data = [MagicMock(embedding=[0.1, 0.2])] - mock_openai_client.return_value.embeddings.create.return_value = mock_response + response = _mock_embedding_response(vectors_per_text=1, dims=2) + mock_create = _awaitable_response(response) + mock_openai_client.return_value.embeddings.create = mock_create config = _make_config(embedding_dims=None) embedder = UniversalAPIEmbedder(config) embedder.embed(["hello"]) - _, kwargs = mock_openai_client.return_value.embeddings.create.call_args + _, kwargs = mock_create.call_args assert "dimensions" not in kwargs @patch("memos.embedders.universal_api.OpenAIClient") def test_embed_with_backup_client(self, mock_openai_client): primary_client = MagicMock() - primary_client.embeddings.create.side_effect = ValueError("down") - backup_response = MagicMock() - backup_response.data = [MagicMock(embedding=[0.1, 0.2])] + primary_client.embeddings.create = AsyncMock(side_effect=ValueError("down")) + backup_response = _mock_embedding_response(vectors_per_text=1, dims=2) + backup_create = _awaitable_response(backup_response) backup_client = MagicMock() - backup_client.embeddings.create.return_value = backup_response + backup_client.embeddings.create = backup_create def client_factory(api_key, **kwargs): if api_key == "primary": @@ -103,11 +123,14 @@ def client_factory(api_key, **kwargs): embedder = UniversalAPIEmbedder(config) result = embedder.embed(["hello"]) assert result == [[0.1, 0.2]] - assert backup_client.embeddings.create.call_count == 1 + assert backup_create.await_count == 1 @patch("memos.embedders.universal_api.OpenAIClient") def test_embed_raises_when_no_backup(self, mock_openai_client): - mock_openai_client.return_value.embeddings.create.side_effect = ValueError("primary failed") + primary_client = MagicMock() + primary_client.embeddings.create = AsyncMock(side_effect=ValueError("primary failed")) + mock_openai_client.return_value = primary_client + config = _make_config(embedding_dims=256) embedder = UniversalAPIEmbedder(config) with pytest.raises(ValueError, match="Embeddings request ended with error"): @@ -121,12 +144,13 @@ def test_call_embeddings_api_falls_back_when_dimensions_not_supported(self): mock_client = SimpleNamespace() call_count = [0] + ok_response = SimpleNamespace(data=[SimpleNamespace(embedding=[0.1, 0.2])]) - def mock_create(**kwargs): + async def mock_create(**kwargs): call_count[0] += 1 if kwargs.get("dimensions") is not None: raise _DimensionsUnsupportedError("dimensions not supported") - return SimpleNamespace(data=[SimpleNamespace(embedding=[0.1, 0.2])]) + return ok_response mock_client.embeddings = SimpleNamespace(create=mock_create) @@ -143,11 +167,12 @@ def test_call_embeddings_api_no_fallback_when_dims_not_set(self): embedder = UniversalAPIEmbedder(config) mock_client = SimpleNamespace() + ok_response = SimpleNamespace(data=[SimpleNamespace(embedding=[0.1])]) - def mock_create(**kwargs): + async def mock_create(**kwargs): if kwargs.get("dimensions") is not None: raise AssertionError("dimensions should not be passed when embedding_dims is None") - return SimpleNamespace(data=[SimpleNamespace(embedding=[0.1])]) + return ok_response mock_client.embeddings = SimpleNamespace(create=mock_create) From b98b8e02d1603944ae9d0cc6f48a8094dfefc6b6 Mon Sep 17 00:00:00 2001 From: RerankerGuo <121015044+RerankerGuo@users.noreply.github.com> Date: Wed, 5 Aug 2026 13:26:19 +0800 Subject: [PATCH 4/6] test(embedder): await fallback API mocks correctly --- tests/embedders/test_universal_api.py | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/tests/embedders/test_universal_api.py b/tests/embedders/test_universal_api.py index 259959134..e0fb53f39 100644 --- a/tests/embedders/test_universal_api.py +++ b/tests/embedders/test_universal_api.py @@ -1,7 +1,5 @@ """Tests for UniversalAPIEmbedder.""" -import asyncio - from types import SimpleNamespace from unittest.mock import AsyncMock, MagicMock, patch @@ -29,7 +27,10 @@ def _make_config(**overrides): def _mock_embedding_response(vectors_per_text=1, dims=2): """Build a MagicMock that mimics openai's embeddings response.""" response = MagicMock() - response.data = [MagicMock(embedding=[0.1 * (i + 1)] * dims) for i in range(vectors_per_text)] + response.data = [ + MagicMock(embedding=[0.1 * (dimension + 1) for dimension in range(dims)]) + for _ in range(vectors_per_text) + ] return response @@ -154,10 +155,7 @@ async def mock_create(**kwargs): mock_client.embeddings = SimpleNamespace(create=mock_create) - with patch.object(asyncio, "wait_for", side_effect=lambda coro, timeout: coro): - result = embedder._call_embeddings_api( - mock_client, "text-embedding-3-large", ["hello"], 5 - ) + result = embedder._call_embeddings_api(mock_client, "text-embedding-3-large", ["hello"], 5) assert call_count[0] == 2 assert result == [[0.1, 0.2]] @@ -176,9 +174,6 @@ async def mock_create(**kwargs): mock_client.embeddings = SimpleNamespace(create=mock_create) - with patch.object(asyncio, "wait_for", side_effect=lambda coro, timeout: coro): - result = embedder._call_embeddings_api( - mock_client, "text-embedding-3-large", ["hello"], 5 - ) + result = embedder._call_embeddings_api(mock_client, "text-embedding-3-large", ["hello"], 5) assert result == [[0.1]] From 0f5ed1b17f3672915da3bc65bd4ee24f5353cdc3 Mon Sep 17 00:00:00 2001 From: Wenqiang Wei <46308778+endxxxx@users.noreply.github.com> Date: Tue, 11 Aug 2026 14:43:02 +0800 Subject: [PATCH 5/6] fix: handle embedding dimensions with sync client --- src/memos/api/config.py | 1 + src/memos/embedders/universal_api.py | 52 ++++++------ tests/embedders/test_universal_api.py | 115 ++++++++++++++++---------- 3 files changed, 101 insertions(+), 67 deletions(-) diff --git a/src/memos/api/config.py b/src/memos/api/config.py index 43ad586dd..7b450181a 100644 --- a/src/memos/api/config.py +++ b/src/memos/api/config.py @@ -622,6 +622,7 @@ def get_embedder_config() -> dict[str, Any]: "provider": os.getenv("MOS_EMBEDDER_PROVIDER", "openai"), "api_key": os.getenv("MOS_EMBEDDER_API_KEY", "sk-xxxx"), "model_name_or_path": os.getenv("MOS_EMBEDDER_MODEL", "text-embedding-3-large"), + "embedding_dims": int(os.getenv("EMBEDDING_DIMENSION", "1024")), "headers_extra": json.loads(os.getenv("MOS_EMBEDDER_HEADERS_EXTRA", "{}")), "base_url": os.getenv("MOS_EMBEDDER_API_BASE", "http://openai.com"), "backup_client": os.getenv("MOS_EMBEDDER_BACKUP_CLIENT", "false").lower() diff --git a/src/memos/embedders/universal_api.py b/src/memos/embedders/universal_api.py index 579b9bc93..44cc1e3cb 100644 --- a/src/memos/embedders/universal_api.py +++ b/src/memos/embedders/universal_api.py @@ -1,7 +1,7 @@ -import asyncio import os from openai import AzureOpenAI as AzureClient +from openai import BadRequestError from openai import OpenAI as OpenAIClient from memos.configs.embedder import UniversalAPIEmbedderConfig @@ -63,6 +63,21 @@ def _build_embedding_kwargs(model: str, texts: list[str], embedding_dims: int | kwargs["dimensions"] = embedding_dims return kwargs + @staticmethod + def _is_dimensions_unsupported(error: BadRequestError) -> bool: + message = str(error).lower() + unsupported_markers = ( + "dimensions is not supported", + "dimensions not supported", + "does not support dimensions", + "unsupported parameter: dimensions", + "unknown parameter: dimensions", + "does not support matryoshka", + "changing output dimensions is unsupported", + "changing output dimensions will lead", + ) + return any(marker in message for marker in unsupported_markers) + def _call_embeddings_api( self, client, model: str, texts: list[str], timeout: int ) -> list[list[float]]: @@ -70,30 +85,19 @@ def _call_embeddings_api( kwargs = self._build_embedding_kwargs(model, texts, embedding_dims) try: - response = asyncio.run( - asyncio.wait_for( - client.embeddings.create(**kwargs), - timeout=timeout, - ) + response = client.embeddings.create(**kwargs, timeout=timeout) + except BadRequestError as error: + if embedding_dims is None or not self._is_dimensions_unsupported(error): + raise + + logger.warning( + "Embedding provider rejected dimensions=%d; retrying without dimensions", + embedding_dims, ) - return [r.embedding for r in response.data] - except Exception as e: - if embedding_dims is not None: - logger.warning( - "Embeddings request with dimensions=%d failed error_type=%s; " - "retrying without dimensions", - embedding_dims, - type(e).__name__, - ) - fallback_kwargs = self._build_embedding_kwargs(model, texts, None) - response = asyncio.run( - asyncio.wait_for( - client.embeddings.create(**fallback_kwargs), - timeout=timeout, - ) - ) - return [r.embedding for r in response.data] - raise + fallback_kwargs = self._build_embedding_kwargs(model, texts, None) + response = client.embeddings.create(**fallback_kwargs, timeout=timeout) + + return [item.embedding for item in response.data] @log_embedding_call def embed(self, texts: list[str]) -> list[list[float]]: diff --git a/tests/embedders/test_universal_api.py b/tests/embedders/test_universal_api.py index e0fb53f39..394770787 100644 --- a/tests/embedders/test_universal_api.py +++ b/tests/embedders/test_universal_api.py @@ -1,18 +1,17 @@ """Tests for UniversalAPIEmbedder.""" from types import SimpleNamespace -from unittest.mock import AsyncMock, MagicMock, patch +from unittest.mock import MagicMock, patch +import httpx import pytest +from openai import APITimeoutError, BadRequestError + from memos.configs.embedder import UniversalAPIEmbedderConfig from memos.embedders.universal_api import UniversalAPIEmbedder -class _DimensionsUnsupportedError(Exception): - """Raised by the mock backend when dimensions are rejected.""" - - def _make_config(**overrides): defaults = { "provider": "openai", @@ -34,17 +33,10 @@ def _mock_embedding_response(vectors_per_text=1, dims=2): return response -def _awaitable_response(response): - """Wrap a MagicMock response so it can be returned by AsyncMock. - - ``asyncio.wait_for`` awaits its coroutine argument, so the - ``embeddings.create`` mock must be an async function (AsyncMock). - """ - - async def _call(**kwargs): - return response - - return AsyncMock(side_effect=_call) +def _bad_request_error(message: str) -> BadRequestError: + request = httpx.Request("POST", "https://api.example.com/v1/embeddings") + response = httpx.Response(400, request=request) + return BadRequestError(message, response=response, body={"error": {"message": message}}) class TestUniversalAPIEmbedderDimensions: @@ -74,35 +66,39 @@ def test_build_embedding_kwargs_zero_dims(self): @patch("memos.embedders.universal_api.OpenAIClient") def test_embed_passes_embedding_dims_to_api(self, mock_openai_client): response = _mock_embedding_response(vectors_per_text=1, dims=2) - mock_create = _awaitable_response(response) + mock_create = MagicMock(return_value=response) mock_openai_client.return_value.embeddings.create = mock_create config = _make_config(embedding_dims=256) embedder = UniversalAPIEmbedder(config) - embedder.embed(["hello"]) + result = embedder.embed(["hello"]) _, kwargs = mock_create.call_args assert kwargs.get("dimensions") == 256 + assert kwargs.get("timeout") == 5 + assert result == [[0.1, 0.2]] @patch("memos.embedders.universal_api.OpenAIClient") def test_embed_without_dims_does_not_pass_dimensions(self, mock_openai_client): response = _mock_embedding_response(vectors_per_text=1, dims=2) - mock_create = _awaitable_response(response) + mock_create = MagicMock(return_value=response) mock_openai_client.return_value.embeddings.create = mock_create config = _make_config(embedding_dims=None) embedder = UniversalAPIEmbedder(config) - embedder.embed(["hello"]) + result = embedder.embed(["hello"]) _, kwargs = mock_create.call_args assert "dimensions" not in kwargs + assert kwargs.get("timeout") == 5 + assert result == [[0.1, 0.2]] @patch("memos.embedders.universal_api.OpenAIClient") def test_embed_with_backup_client(self, mock_openai_client): primary_client = MagicMock() - primary_client.embeddings.create = AsyncMock(side_effect=ValueError("down")) + primary_client.embeddings.create = MagicMock(side_effect=ValueError("down")) backup_response = _mock_embedding_response(vectors_per_text=1, dims=2) - backup_create = _awaitable_response(backup_response) + backup_create = MagicMock(return_value=backup_response) backup_client = MagicMock() backup_client.embeddings.create = backup_create @@ -124,12 +120,13 @@ def client_factory(api_key, **kwargs): embedder = UniversalAPIEmbedder(config) result = embedder.embed(["hello"]) assert result == [[0.1, 0.2]] - assert backup_create.await_count == 1 + assert primary_client.embeddings.create.call_count == 1 + assert backup_create.call_count == 1 @patch("memos.embedders.universal_api.OpenAIClient") def test_embed_raises_when_no_backup(self, mock_openai_client): primary_client = MagicMock() - primary_client.embeddings.create = AsyncMock(side_effect=ValueError("primary failed")) + primary_client.embeddings.create = MagicMock(side_effect=ValueError("primary failed")) mock_openai_client.return_value = primary_client config = _make_config(embedding_dims=256) @@ -143,37 +140,69 @@ def test_call_embeddings_api_falls_back_when_dimensions_not_supported(self): config = _make_config(embedding_dims=256) embedder = UniversalAPIEmbedder(config) - mock_client = SimpleNamespace() - call_count = [0] ok_response = SimpleNamespace(data=[SimpleNamespace(embedding=[0.1, 0.2])]) - - async def mock_create(**kwargs): - call_count[0] += 1 - if kwargs.get("dimensions") is not None: - raise _DimensionsUnsupportedError("dimensions not supported") - return ok_response - - mock_client.embeddings = SimpleNamespace(create=mock_create) + mock_create = MagicMock( + side_effect=[ + _bad_request_error("dimensions is not supported by this model"), + ok_response, + ] + ) + mock_client = SimpleNamespace(embeddings=SimpleNamespace(create=mock_create)) result = embedder._call_embeddings_api(mock_client, "text-embedding-3-large", ["hello"], 5) - assert call_count[0] == 2 + assert mock_create.call_count == 2 + assert mock_create.call_args_list[0].kwargs["dimensions"] == 256 + assert "dimensions" not in mock_create.call_args_list[1].kwargs + assert all(call.kwargs["timeout"] == 5 for call in mock_create.call_args_list) assert result == [[0.1, 0.2]] + def test_call_embeddings_api_does_not_fallback_on_timeout(self): + config = _make_config(embedding_dims=256) + embedder = UniversalAPIEmbedder(config) + request = httpx.Request("POST", "https://api.example.com/v1/embeddings") + mock_create = MagicMock(side_effect=APITimeoutError(request=request)) + mock_client = SimpleNamespace(embeddings=SimpleNamespace(create=mock_create)) + + with pytest.raises(APITimeoutError): + embedder._call_embeddings_api(mock_client, "text-embedding-3-large", ["hello"], 5) + + assert mock_create.call_count == 1 + + def test_call_embeddings_api_does_not_fallback_on_unrelated_bad_request(self): + config = _make_config(embedding_dims=256) + embedder = UniversalAPIEmbedder(config) + mock_create = MagicMock(side_effect=_bad_request_error("input must not be empty")) + mock_client = SimpleNamespace(embeddings=SimpleNamespace(create=mock_create)) + + with pytest.raises(BadRequestError, match="input must not be empty"): + embedder._call_embeddings_api(mock_client, "text-embedding-3-large", ["hello"], 5) + + assert mock_create.call_count == 1 + + def test_call_embeddings_api_does_not_fallback_on_invalid_dimensions(self): + config = _make_config(embedding_dims=0) + embedder = UniversalAPIEmbedder(config) + mock_create = MagicMock( + side_effect=_bad_request_error("dimensions must be greater than zero") + ) + mock_client = SimpleNamespace(embeddings=SimpleNamespace(create=mock_create)) + + with pytest.raises(BadRequestError, match="dimensions must be greater than zero"): + embedder._call_embeddings_api(mock_client, "text-embedding-3-large", ["hello"], 5) + + assert mock_create.call_count == 1 + def test_call_embeddings_api_no_fallback_when_dims_not_set(self): config = _make_config(embedding_dims=None) embedder = UniversalAPIEmbedder(config) - mock_client = SimpleNamespace() ok_response = SimpleNamespace(data=[SimpleNamespace(embedding=[0.1])]) - - async def mock_create(**kwargs): - if kwargs.get("dimensions") is not None: - raise AssertionError("dimensions should not be passed when embedding_dims is None") - return ok_response - - mock_client.embeddings = SimpleNamespace(create=mock_create) + mock_create = MagicMock(return_value=ok_response) + mock_client = SimpleNamespace(embeddings=SimpleNamespace(create=mock_create)) result = embedder._call_embeddings_api(mock_client, "text-embedding-3-large", ["hello"], 5) + assert "dimensions" not in mock_create.call_args.kwargs + assert mock_create.call_args.kwargs["timeout"] == 5 assert result == [[0.1]] From 88a515aaea5ff2ee1623e5f3093631b0e219f322 Mon Sep 17 00:00:00 2001 From: RerankerGuo <121015044+RerankerGuo@users.noreply.github.com> Date: Wed, 12 Aug 2026 10:00:27 +0800 Subject: [PATCH 6/6] fix(embedder): detect structured dimensions errors Recognize provider errors that identify an unsupported dimensions parameter through structured param/code fields while preserving invalid-value failures. Add regression coverage for structured fallback and API dimension configuration. Test: .venv/bin/python -m pytest tests/embedders/test_universal_api.py -q\nTest: .venv/bin/python -m pytest tests/api -q\nTest: .venv/bin/python -m pytest tests/embedders -q --ignore=tests/embedders/test_ark.py --- src/memos/embedders/universal_api.py | 15 +++++++- tests/embedders/test_universal_api.py | 49 +++++++++++++++++++++++++-- 2 files changed, 60 insertions(+), 4 deletions(-) diff --git a/src/memos/embedders/universal_api.py b/src/memos/embedders/universal_api.py index 44cc1e3cb..22962e728 100644 --- a/src/memos/embedders/universal_api.py +++ b/src/memos/embedders/universal_api.py @@ -65,7 +65,20 @@ def _build_embedding_kwargs(model: str, texts: list[str], embedding_dims: int | @staticmethod def _is_dimensions_unsupported(error: BadRequestError) -> bool: - message = str(error).lower() + body = getattr(error, "body", None) + details = body.get("error", body) if isinstance(body, dict) else {} + if isinstance(details, dict): + param = str(details.get("param") or "").lower() + code = str(details.get("code") or "").lower() + if param == "dimensions" and any( + marker in code for marker in ("unsupported", "unknown", "unrecognized") + ): + return True + + messages = [str(error)] + if isinstance(details, dict) and isinstance(details.get("message"), str): + messages.append(details["message"]) + message = " ".join(messages).lower() unsupported_markers = ( "dimensions is not supported", "dimensions not supported", diff --git a/tests/embedders/test_universal_api.py b/tests/embedders/test_universal_api.py index 394770787..7d897ebb2 100644 --- a/tests/embedders/test_universal_api.py +++ b/tests/embedders/test_universal_api.py @@ -33,10 +33,17 @@ def _mock_embedding_response(vectors_per_text=1, dims=2): return response -def _bad_request_error(message: str) -> BadRequestError: +def _bad_request_error( + message: str, *, param: str | None = None, code: str | None = None +) -> BadRequestError: request = httpx.Request("POST", "https://api.example.com/v1/embeddings") response = httpx.Response(400, request=request) - return BadRequestError(message, response=response, body={"error": {"message": message}}) + details = {"message": message} + if param is not None: + details["param"] = param + if code is not None: + details["code"] = code + return BadRequestError(message, response=response, body={"error": details}) class TestUniversalAPIEmbedderDimensions: @@ -63,6 +70,16 @@ def test_build_embedding_kwargs_zero_dims(self): ) assert kwargs["dimensions"] == 0 + def test_api_config_maps_embedding_dimension(self, monkeypatch): + from memos.api.config import APIConfig + + monkeypatch.setenv("MOS_EMBEDDER_BACKEND", "universal_api") + monkeypatch.setenv("EMBEDDING_DIMENSION", "1536") + + config = APIConfig.get_embedder_config() + + assert config["config"]["embedding_dims"] == 1536 + @patch("memos.embedders.universal_api.OpenAIClient") def test_embed_passes_embedding_dims_to_api(self, mock_openai_client): response = _mock_embedding_response(vectors_per_text=1, dims=2) @@ -157,6 +174,28 @@ def test_call_embeddings_api_falls_back_when_dimensions_not_supported(self): assert all(call.kwargs["timeout"] == 5 for call in mock_create.call_args_list) assert result == [[0.1, 0.2]] + def test_call_embeddings_api_falls_back_on_structured_dimensions_error(self): + config = _make_config(embedding_dims=256) + embedder = UniversalAPIEmbedder(config) + ok_response = SimpleNamespace(data=[SimpleNamespace(embedding=[0.1, 0.2])]) + mock_create = MagicMock( + side_effect=[ + _bad_request_error( + "Bad request", + param="dimensions", + code="unsupported_parameter", + ), + ok_response, + ] + ) + mock_client = SimpleNamespace(embeddings=SimpleNamespace(create=mock_create)) + + result = embedder._call_embeddings_api(mock_client, "text-embedding-3-large", ["hello"], 5) + + assert mock_create.call_count == 2 + assert "dimensions" not in mock_create.call_args_list[1].kwargs + assert result == [[0.1, 0.2]] + def test_call_embeddings_api_does_not_fallback_on_timeout(self): config = _make_config(embedding_dims=256) embedder = UniversalAPIEmbedder(config) @@ -184,7 +223,11 @@ def test_call_embeddings_api_does_not_fallback_on_invalid_dimensions(self): config = _make_config(embedding_dims=0) embedder = UniversalAPIEmbedder(config) mock_create = MagicMock( - side_effect=_bad_request_error("dimensions must be greater than zero") + side_effect=_bad_request_error( + "dimensions must be greater than zero", + param="dimensions", + code="invalid_value", + ) ) mock_client = SimpleNamespace(embeddings=SimpleNamespace(create=mock_create))