diff --git a/redisvl/extensions/cache/embeddings/embeddings.py b/redisvl/extensions/cache/embeddings/embeddings.py index 31f73220..2049ce94 100644 --- a/redisvl/extensions/cache/embeddings/embeddings.py +++ b/redisvl/extensions/cache/embeddings/embeddings.py @@ -14,6 +14,8 @@ class EmbeddingsCache(BaseCache): """Embeddings Cache for storing embedding vectors with exact key matching.""" + _warning_shown: bool = False # Class-level flag to prevent warning spam + def __init__( self, name: str = "embedcache", @@ -124,6 +126,14 @@ def _process_cache_data( cache_hit = CacheEntry(**convert_bytes(data)) return cache_hit.model_dump(exclude_none=True) + def _should_warn_for_async_only(self) -> bool: + """Check if only async client is available (no sync client). + + Returns: + bool: True if only async client is available (no sync client). + """ + return self._owns_redis_client is False and self._redis_client is None + def get( self, text: str, @@ -167,6 +177,14 @@ def get_by_key(self, key: str) -> Optional[Dict[str, Any]]: embedding_data = cache.get_by_key("embedcache:1234567890abcdef") """ + if self._should_warn_for_async_only(): + if not EmbeddingsCache._warning_shown: + logger.warning( + "EmbeddingsCache initialized with async_redis_client only. " + "Use async methods (aget_by_key) instead of sync methods (get_by_key)." + ) + EmbeddingsCache._warning_shown = True + client = self._get_redis_client() # Get all fields @@ -202,6 +220,14 @@ def mget_by_keys(self, keys: List[str]) -> List[Optional[Dict[str, Any]]]: if not keys: return [] + if self._should_warn_for_async_only(): + if not EmbeddingsCache._warning_shown: + logger.warning( + "EmbeddingsCache initialized with async_redis_client only. " + "Use async methods (amget_by_keys) instead of sync methods (mget_by_keys)." + ) + EmbeddingsCache._warning_shown = True + client = self._get_redis_client() with client.pipeline(transaction=False) as pipeline: @@ -283,6 +309,14 @@ def set( text, model_name, embedding, metadata ) + if self._should_warn_for_async_only(): + if not EmbeddingsCache._warning_shown: + logger.warning( + "EmbeddingsCache initialized with async_redis_client only. " + "Use async methods (aset) instead of sync methods (set)." + ) + EmbeddingsCache._warning_shown = True + # Store in Redis client = self._get_redis_client() client.hset(name=key, mapping=cache_entry) # type: ignore @@ -333,6 +367,14 @@ def mset( if not items: return [] + if self._should_warn_for_async_only(): + if not EmbeddingsCache._warning_shown: + logger.warning( + "EmbeddingsCache initialized with async_redis_client only. " + "Use async methods (amset) instead of sync methods (mset)." + ) + EmbeddingsCache._warning_shown = True + client = self._get_redis_client() keys = [] diff --git a/tests/integration/test_embedcache_warnings.py b/tests/integration/test_embedcache_warnings.py new file mode 100644 index 00000000..059d6c4c --- /dev/null +++ b/tests/integration/test_embedcache_warnings.py @@ -0,0 +1,88 @@ +"""Test warning behavior when using sync methods with async-only client.""" + +import logging +from unittest.mock import patch + +import pytest +from redis import Redis + +from redisvl.extensions.cache.embeddings import EmbeddingsCache + + +@pytest.fixture(autouse=True) +def reset_warning_flag(): + """Reset the warning flag before each test to ensure test isolation.""" + EmbeddingsCache._warning_shown = False + yield + # Optionally reset after test as well for cleanup + EmbeddingsCache._warning_shown = False + + +@pytest.mark.asyncio +async def test_sync_methods_warn_with_async_only_client(async_client, caplog): + """Test that sync methods warn when only async client is provided.""" + # Initialize EmbeddingsCache with only async_redis_client + cache = EmbeddingsCache(name="test_cache", async_redis_client=async_client) + + # Mock _get_redis_client to prevent actual connection attempt + with patch.object(cache, "_get_redis_client") as mock_get_client: + # Mock the Redis client methods that would be called + mock_client = mock_get_client.return_value + mock_client.hgetall.return_value = {} # Empty result for get_by_key + mock_client.hset.return_value = 1 # Success for set + + # Capture log warnings + with caplog.at_level(logging.WARNING): + # First sync method call should warn + _ = cache.get_by_key("test_key") + + # Check warning was logged + assert len(caplog.records) == 1 + assert ( + "initialized with async_redis_client only" in caplog.records[0].message + ) + assert "Use async methods" in caplog.records[0].message + + # Clear captured logs + caplog.clear() + + # Second sync method call should NOT warn (flag prevents spam) + _ = cache.set(text="test", model_name="model", embedding=[0.1, 0.2]) + + # Should not have logged another warning + assert len(caplog.records) == 0 + + +def test_no_warning_with_sync_client(redis_url): + """Test that no warning is shown when sync client is provided.""" + # Create sync redis client from redis_url + sync_client = Redis.from_url(redis_url) + + try: + # Initialize EmbeddingsCache with sync_redis_client + cache = EmbeddingsCache(name="test_cache", redis_client=sync_client) + + with patch("redisvl.utils.log.get_logger") as mock_logger: + # Sync methods should not warn + _ = cache.get_by_key("test_key") + _ = cache.set(text="test", model_name="model", embedding=[0.1, 0.2]) + + # No warnings should have been logged + mock_logger.return_value.warning.assert_not_called() + finally: + sync_client.close() + + +@pytest.mark.asyncio +async def test_async_methods_no_warning(async_client): + """Test that async methods don't trigger warnings.""" + # Initialize EmbeddingsCache with only async_redis_client + cache = EmbeddingsCache(name="test_cache", async_redis_client=async_client) + + with patch("redisvl.utils.log.get_logger") as mock_logger: + # Async methods should not warn + _ = await cache.aget_by_key("test_key") + _ = await cache.aset(text="test", model_name="model", embedding=[0.1, 0.2]) + + # No warnings should have been logged + mock_logger.return_value.warning.assert_not_called()