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 24a022eae..22962e728 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 @@ -56,29 +56,73 @@ 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 + + @staticmethod + def _is_dimensions_unsupported(error: BadRequestError) -> bool: + 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", + "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]]: + embedding_dims = getattr(self.config, "embedding_dims", None) + kwargs = self._build_embedding_kwargs(model, texts, embedding_dims) + + try: + 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, + ) + 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]]: 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 +130,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..7d897ebb2 100644 --- a/tests/embedders/test_universal_api.py +++ b/tests/embedders/test_universal_api.py @@ -1,75 +1,251 @@ -import unittest +"""Tests for UniversalAPIEmbedder.""" +from types import SimpleNamespace 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 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) + + +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 * (dimension + 1) for dimension in range(dims)]) + for _ in range(vectors_per_text) + ] + return response + + +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) + 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: + 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 + + 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 + + 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) + mock_create = MagicMock(return_value=response) + mock_openai_client.return_value.embeddings.create = mock_create + + config = _make_config(embedding_dims=256) + embedder = UniversalAPIEmbedder(config) + 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 = MagicMock(return_value=response) + mock_openai_client.return_value.embeddings.create = mock_create + config = _make_config(embedding_dims=None) embedder = UniversalAPIEmbedder(config) - text = ["Test input for embedding."] - result = embedder.embed(text) + result = embedder.embed(["hello"]) - # 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 + _, 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 = MagicMock(side_effect=ValueError("down")) + backup_response = _mock_embedding_response(vectors_per_text=1, dims=2) + backup_create = MagicMock(return_value=backup_response) + backup_client = MagicMock() + backup_client.embeddings.create = backup_create + + 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", + 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 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 = MagicMock(side_effect=ValueError("primary failed")) + mock_openai_client.return_value = primary_client - # Assert embeddings.create called with correct params - embedder.client.embeddings.create.assert_called_once_with( - model="text-embedding-3-large", - input=text, + 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) + + ok_response = SimpleNamespace(data=[SimpleNamespace(embedding=[0.1, 0.2])]) + 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)) - self.assertEqual(len(result[0]), 4) + result = embedder._call_embeddings_api(mock_client, "text-embedding-3-large", ["hello"], 5) - @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]), - ] - 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", + 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_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) - texts = ["First text.", "Second text.", "Third text."] - result = embedder.embed(texts) + 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) - embedder.client.embeddings.create.assert_called_once_with( - model="text-embedding-3-large", - input=texts, + 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", + param="dimensions", + code="invalid_value", + ) ) + 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) - self.assertEqual(len(result), 3) - self.assertEqual(result[0], [0.1, 0.2]) + ok_response = SimpleNamespace(data=[SimpleNamespace(embedding=[0.1])]) + 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) -if __name__ == "__main__": - unittest.main() + assert "dimensions" not in mock_create.call_args.kwargs + assert mock_create.call_args.kwargs["timeout"] == 5 + assert result == [[0.1]]