From 015491f95f6ad3f8d1062670772455bb33e588a2 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Wed, 4 Nov 2026 16:01:07 +0100 Subject: [PATCH 1/6] feat(cache): default SemanticCache to redis/langcache-embed-v2 SemanticCache without a vectorizer now embeds with langcache-embed-v2 instead of v1. Both models emit 768-dimension vectors, so an existing v1 index accepts v2 lookups silently; the warning for an existing index now names the change and how to keep v1, replacing the 0.6.0 wording. The llmcache integration fixture moves to v2, and test_cache_filtering gets explicit thresholds: 'test prompt 0' sits at 0.241 from 'test prompt 1' under v2 (0.180 under v1), outside the fixture's 0.2. --- docs/concepts/extensions.md | 18 ++++ redisvl/extensions/cache/llm/semantic.py | 29 +++--- tests/integration/test_llmcache.py | 15 +++- .../test_semantic_cache_default_vectorizer.py | 90 +++++++++++++++++++ 4 files changed, 138 insertions(+), 14 deletions(-) create mode 100644 tests/unit/test_semantic_cache_default_vectorizer.py diff --git a/docs/concepts/extensions.md b/docs/concepts/extensions.md index 54c54eb57..d3df67d41 100644 --- a/docs/concepts/extensions.md +++ b/docs/concepts/extensions.md @@ -21,6 +21,24 @@ When a prompt arrives, the cache embeds it and searches for similar cached promp The key insight is "similar" rather than "identical." Traditional caching requires exact matches. Semantic caching matches by meaning, so "What's the capital of France?" and "Tell me France's capital city" can hit the same cache entry. +### Embedding Model + +Without a `vectorizer` argument, `SemanticCache` embeds prompts with `HFTextVectorizer(model="redis/langcache-embed-v2")`, a model trained for cache matching. Earlier releases defaulted to `redis/langcache-embed-v1`. + +A cache must be read with the model that wrote it. The two models produce vectors of the same size, so a v1 cache accepts v2 lookups without an error and returns the wrong hits and misses. RedisVL logs a warning whenever it opens an existing cache without an explicit vectorizer. To keep a v1 cache working, pass the model explicitly: + +```python +from redisvl.extensions.cache.llm import SemanticCache +from redisvl.utils.vectorize import HFTextVectorizer + +cache = SemanticCache( + name="llmcache", + vectorizer=HFTextVectorizer(model="redis/langcache-embed-v1"), +) +``` + +To move an existing cache to v2, call `clear()` on it or recreate it with `overwrite=True`, then let it refill. Distances differ between models, so check your `distance_threshold` after switching. + ### Threshold Tuning The distance threshold controls how similar prompts must be to match. A strict threshold (low value, like 0.05) requires near-identical prompts. A loose threshold (higher value, like 0.3) matches more liberally. diff --git a/redisvl/extensions/cache/llm/semantic.py b/redisvl/extensions/cache/llm/semantic.py index 781731df3..efa94ef47 100644 --- a/redisvl/extensions/cache/llm/semantic.py +++ b/redisvl/extensions/cache/llm/semantic.py @@ -37,16 +37,21 @@ logger = get_logger("[RedisVL]") +DEFAULT_VECTORIZER_MODEL = "redis/langcache-embed-v2" + # Emitted when the caller did not choose a vectorizer and the index predates this -# call, so its vectors may have been written with the old default model. Remove -# this warning in future releases. +# call, so its vectors may have been written with the previous default model. +# Both models emit 768-dimension vectors, so the schema check below cannot tell +# them apart and a mismatch shows up only as wrong hits and misses. DEFAULT_VECTORIZER_CHANGED_WARNING = ( - "The default vectorizer has changed from `sentence-transformers/all-mpnet-base-v2` " - "to `redis/langcache-embed-v1` in version 0.6.0 of RedisVL. " - "For more information about this model, please refer to https://arxiv.org/abs/2504.02268 " - "or visit https://huggingface.co/redis/langcache-embed-v1. " - "To continue using the old vectorizer, please specify it explicitly in the constructor as: " - "vectorizer=HFTextVectorizer(model='sentence-transformers/all-mpnet-base-v2')" + "The default SemanticCache vectorizer is now `redis/langcache-embed-v2`; it " + "was `redis/langcache-embed-v1`. This cache's index already exists, and if its " + "entries were embedded with v1, lookups embedded with v2 return wrong hits and " + "misses without raising an error. To keep using v1, pass " + "vectorizer=HFTextVectorizer(model='redis/langcache-embed-v1'). To move to v2, " + "clear the cache or recreate it with overwrite=True. Pass a vectorizer " + "explicitly to silence this warning. " + "See https://huggingface.co/redis/langcache-embed-v2." ) @@ -82,7 +87,11 @@ def __init__( ttl (Optional[int], optional): The time-to-live for records cached in Redis. Defaults to None. vectorizer (Optional[BaseVectorizer], optional): The vectorizer for the cache. - Defaults to HFTextVectorizer. + Defaults to ``HFTextVectorizer(model="redis/langcache-embed-v2")``. + Before this default changed it was ``redis/langcache-embed-v1``; + an existing cache written with v1 must pass that model explicitly + or be rebuilt, since v2 query vectors fit a v1 index without error + but match the wrong entries. filterable_fields (Optional[List[Dict[str, Any]]]): An optional list of RedisVL fields that can be used to customize cache retrieval with filters. redis_client(Optional[Redis], optional): A redis client connection instance. @@ -159,7 +168,7 @@ def __init__( vectorizer_kwargs.update(dtype=dtype) self._vectorizer = HFTextVectorizer( - model="redis/langcache-embed-v1", + model=DEFAULT_VECTORIZER_MODEL, **vectorizer_kwargs, ) diff --git a/tests/integration/test_llmcache.py b/tests/integration/test_llmcache.py index 9aae294ed..31f8761d5 100644 --- a/tests/integration/test_llmcache.py +++ b/tests/integration/test_llmcache.py @@ -20,7 +20,7 @@ @pytest.fixture(scope="session") def vectorizer(): - return HFTextVectorizer("redis/langcache-embed-v1") + return HFTextVectorizer("redis/langcache-embed-v2") @pytest.fixture @@ -851,9 +851,13 @@ def test_cache_filtering(cache_with_filters): response = f"test response {i}" cache_with_filters.store(prompt, response, filters={"label": tags[i]}) - # test we can specify one specific tag + # test we can specify one specific tag. The threshold is loose so that only + # the filter, not the embedding model's distances, decides what comes back. results = cache_with_filters.check( - "test prompt 1", filter_expression=filter_1, num_results=5 + "test prompt 1", + filter_expression=filter_1, + num_results=5, + distance_threshold=0.5, ) assert len(results) == 1 assert results[0]["prompt"] == "test prompt 0" @@ -877,7 +881,10 @@ def test_cache_filtering(cache_with_filters): # test no results are returned if we pass a nonexistent tag bad_filter = Tag("label") == "bad tag" results = cache_with_filters.check( - "test prompt 1", filter_expression=bad_filter, num_results=5 + "test prompt 1", + filter_expression=bad_filter, + num_results=5, + distance_threshold=0.6, ) assert len(results) == 0 diff --git a/tests/unit/test_semantic_cache_default_vectorizer.py b/tests/unit/test_semantic_cache_default_vectorizer.py new file mode 100644 index 000000000..30f818fb4 --- /dev/null +++ b/tests/unit/test_semantic_cache_default_vectorizer.py @@ -0,0 +1,90 @@ +""" +The default SemanticCache vectorizer, and the warning for caches that predate it. + +`redis/langcache-embed-v1` and `-v2` both emit 768-dimension vectors, so a v1 +index accepts v2 query vectors and the schema check cannot catch the mismatch. +The warning is the only signal a caller gets, so these tests pin when it fires +and that it names the way to keep v1. The vectorizer is stubbed so no model is +downloaded, and the Redis client is a mock so no server is needed. +""" + +import logging +from unittest.mock import ANY, MagicMock + +import pytest +from redis import Redis + +from redisvl.extensions.cache.llm import semantic +from redisvl.extensions.cache.llm.semantic import ( + DEFAULT_VECTORIZER_CHANGED_WARNING, + SemanticCache, +) +from redisvl.index import SearchIndex +from redisvl.utils.vectorize import CustomVectorizer + + +@pytest.fixture +def default_models(monkeypatch): + """Record the model each default vectorizer is built with.""" + models = [] + + def fake_hf_vectorizer(model, **kwargs): + models.append(model) + return CustomVectorizer(lambda text: [0.1] * 768) + + monkeypatch.setattr(semantic, "HFTextVectorizer", fake_hf_vectorizer) + return models + + +def _warned(caplog): + return DEFAULT_VECTORIZER_CHANGED_WARNING in caplog.messages + + +def test_default_vectorizer_is_langcache_embed_v2(default_models): + SemanticCache(redis_client=MagicMock(spec=Redis), create_index=False) + + assert default_models == ["redis/langcache-embed-v2"] + + +def test_warning_names_how_to_keep_v1(): + assert ( + "vectorizer=HFTextVectorizer(model='redis/langcache-embed-v1')" + in DEFAULT_VECTORIZER_CHANGED_WARNING + ) + + +@pytest.mark.parametrize("explicit_vectorizer", [False, True]) +def test_warns_on_existing_index_only_without_a_vectorizer( + default_models, monkeypatch, caplog, explicit_vectorizer +): + monkeypatch.setattr(SearchIndex, "exists", lambda self: True) + monkeypatch.setattr(SearchIndex, "create", lambda self, **kwargs: None) + # The live schema matches, exactly as a v1-era cache's would: same dims. + existing = MagicMock() + existing.schema.to_dict.return_value = ANY + monkeypatch.setattr(SearchIndex, "from_existing", lambda name, **kw: existing) + kwargs = {} + if explicit_vectorizer: + kwargs["vectorizer"] = CustomVectorizer(lambda text: [0.1] * 768) + + with caplog.at_level(logging.WARNING): + SemanticCache(redis_client=MagicMock(spec=Redis), **kwargs) + + assert _warned(caplog) is not explicit_vectorizer + + +def test_no_warning_when_the_index_is_new(default_models, monkeypatch, caplog): + monkeypatch.setattr(SearchIndex, "exists", lambda self: False) + monkeypatch.setattr(SearchIndex, "create", lambda self, **kwargs: None) + + with caplog.at_level(logging.WARNING): + SemanticCache(redis_client=MagicMock(spec=Redis)) + + assert not _warned(caplog) + + +def test_warns_when_index_is_asserted_to_exist(default_models, caplog): + with caplog.at_level(logging.WARNING): + SemanticCache(redis_client=MagicMock(spec=Redis), create_index=False) + + assert _warned(caplog) From 80e974531c1da2eafea658bafd5e73becadfea27 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Wed, 4 Nov 2026 16:04:52 +0100 Subject: [PATCH 2/6] docs(cache): migrate a v1 cache with clear(), not overwrite=True overwrite=True rebuilds the index with drop=False, so the stored v1 entries are re-indexed and keep matching v2 lookups. Point the warning, docstring and concepts page at clear() instead, and tell users to pass the vectorizer explicitly afterwards to stop the warning. --- docs/concepts/extensions.md | 2 +- redisvl/extensions/cache/llm/semantic.py | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/concepts/extensions.md b/docs/concepts/extensions.md index d3df67d41..64710d131 100644 --- a/docs/concepts/extensions.md +++ b/docs/concepts/extensions.md @@ -37,7 +37,7 @@ cache = SemanticCache( ) ``` -To move an existing cache to v2, call `clear()` on it or recreate it with `overwrite=True`, then let it refill. Distances differ between models, so check your `distance_threshold` after switching. +To move an existing cache to v2, call `clear()` on it and let it refill. `overwrite=True` is not enough: it rebuilds the index but keeps the stored entries, which are then indexed again with their v1 vectors. From then on, pass `vectorizer=HFTextVectorizer(model="redis/langcache-embed-v2")` explicitly, since the warning fires for any existing cache opened without one. Distances differ between models, so check your `distance_threshold` after switching. ### Threshold Tuning diff --git a/redisvl/extensions/cache/llm/semantic.py b/redisvl/extensions/cache/llm/semantic.py index efa94ef47..cb6f2b38b 100644 --- a/redisvl/extensions/cache/llm/semantic.py +++ b/redisvl/extensions/cache/llm/semantic.py @@ -43,14 +43,15 @@ # call, so its vectors may have been written with the previous default model. # Both models emit 768-dimension vectors, so the schema check below cannot tell # them apart and a mismatch shows up only as wrong hits and misses. +# Remove this warning once v1-era caches are no longer expected. DEFAULT_VECTORIZER_CHANGED_WARNING = ( "The default SemanticCache vectorizer is now `redis/langcache-embed-v2`; it " "was `redis/langcache-embed-v1`. This cache's index already exists, and if its " "entries were embedded with v1, lookups embedded with v2 return wrong hits and " "misses without raising an error. To keep using v1, pass " "vectorizer=HFTextVectorizer(model='redis/langcache-embed-v1'). To move to v2, " - "clear the cache or recreate it with overwrite=True. Pass a vectorizer " - "explicitly to silence this warning. " + "call clear() and let the cache refill; overwrite=True keeps the old entries. " + "Pass a vectorizer explicitly to silence this warning. " "See https://huggingface.co/redis/langcache-embed-v2." ) @@ -90,7 +91,7 @@ def __init__( Defaults to ``HFTextVectorizer(model="redis/langcache-embed-v2")``. Before this default changed it was ``redis/langcache-embed-v1``; an existing cache written with v1 must pass that model explicitly - or be rebuilt, since v2 query vectors fit a v1 index without error + or be emptied with ``clear()``, since v2 query vectors fit a v1 index without error but match the wrong entries. filterable_fields (Optional[List[Dict[str, Any]]]): An optional list of RedisVL fields that can be used to customize cache retrieval with filters. From f3b0f307a772d68c7bc84fb1f0da5df08b514655 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Wed, 4 Nov 2026 16:26:23 +0100 Subject: [PATCH 3/6] docs(cache): note that v2 distances run wider than v1's --- docs/concepts/extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/extensions.md b/docs/concepts/extensions.md index 64710d131..33ba190ae 100644 --- a/docs/concepts/extensions.md +++ b/docs/concepts/extensions.md @@ -37,7 +37,7 @@ cache = SemanticCache( ) ``` -To move an existing cache to v2, call `clear()` on it and let it refill. `overwrite=True` is not enough: it rebuilds the index but keeps the stored entries, which are then indexed again with their v1 vectors. From then on, pass `vectorizer=HFTextVectorizer(model="redis/langcache-embed-v2")` explicitly, since the warning fires for any existing cache opened without one. Distances differ between models, so check your `distance_threshold` after switching. +To move an existing cache to v2, call `clear()` on it and let it refill. `overwrite=True` is not enough: it rebuilds the index but keeps the stored entries, which are then indexed again with their v1 vectors. From then on, pass `vectorizer=HFTextVectorizer(model="redis/langcache-embed-v2")` explicitly, since the warning fires for any existing cache opened without one. Distances differ between models: v2 places the same pair of prompts slightly further apart than v1 does, so at an unchanged `distance_threshold` it matches somewhat fewer paraphrases. Check your threshold after switching. ### Threshold Tuning From 1d281d4cffe9cf557ac97d4aa596e95a73be5012 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Wed, 4 Nov 2026 16:42:04 +0100 Subject: [PATCH 4/6] feat(extensions): deprecate the implicit default vectorizer SemanticCache, SemanticMessageHistory and SemanticRouter no longer change their fallback model: constructing one without a vectorizer now emits a DeprecationWarning naming the fallback, which stays at redis/langcache-embed-v1 (cache) and all-mpnet-base-v2 (history, router) until a future major release makes the argument required. The fallback pulls in the optional sentence-transformers extra and downloads a model at construction time, and because the model is baked into stored vectors, changing it silently breaks existing data. This replaces the earlier v1->v2 swap on this branch and the existing-index logger warning, which the deprecation warning subsumes. Docs gain a 'Choosing a Vectorizer' section, and docstring and installation examples pass a vectorizer explicitly. --- docs/concepts/extensions.md | 34 ++++--- docs/user_guide/installation.md | 1 + redisvl/extensions/cache/llm/semantic.py | 58 +++++------ redisvl/extensions/constants.py | 12 +++ .../message_history/semantic_history.py | 20 +++- redisvl/extensions/router/semantic.py | 40 +++++++- .../test_implicit_vectorizer_deprecation.py | 99 +++++++++++++++++++ .../test_semantic_cache_default_vectorizer.py | 90 ----------------- 8 files changed, 211 insertions(+), 143 deletions(-) create mode 100644 tests/unit/test_implicit_vectorizer_deprecation.py delete mode 100644 tests/unit/test_semantic_cache_default_vectorizer.py diff --git a/docs/concepts/extensions.md b/docs/concepts/extensions.md index 33ba190ae..0fb0fba3c 100644 --- a/docs/concepts/extensions.md +++ b/docs/concepts/extensions.md @@ -11,21 +11,9 @@ Extensions are opinionated, higher-level abstractions built on RedisVL's core pr You don't need to understand schemas, indexes, or queries to use extensions—they handle that complexity for you. -## Semantic Cache - -LLM API calls are expensive and slow. If users ask similar questions, you're paying to generate similar answers repeatedly. Semantic caching solves this by storing responses and returning cached answers when similar prompts are seen again. - -### How It Works - -When a prompt arrives, the cache embeds it and searches for similar cached prompts. If a match is found within the configured distance threshold, the cached response is returned immediately—no LLM call needed. If no match is found, you call the LLM, store the prompt-response pair, and return the response. - -The key insight is "similar" rather than "identical." Traditional caching requires exact matches. Semantic caching matches by meaning, so "What's the capital of France?" and "Tell me France's capital city" can hit the same cache entry. +## Choosing a Vectorizer -### Embedding Model - -Without a `vectorizer` argument, `SemanticCache` embeds prompts with `HFTextVectorizer(model="redis/langcache-embed-v2")`, a model trained for cache matching. Earlier releases defaulted to `redis/langcache-embed-v1`. - -A cache must be read with the model that wrote it. The two models produce vectors of the same size, so a v1 cache accepts v2 lookups without an error and returns the wrong hits and misses. RedisVL logs a warning whenever it opens an existing cache without an explicit vectorizer. To keep a v1 cache working, pass the model explicitly: +`SemanticCache`, `SemanticMessageHistory` and `SemanticRouter` embed text, so each needs a {doc}`vectorizer `. Pass one explicitly: ```python from redisvl.extensions.cache.llm import SemanticCache @@ -33,11 +21,25 @@ from redisvl.utils.vectorize import HFTextVectorizer cache = SemanticCache( name="llmcache", - vectorizer=HFTextVectorizer(model="redis/langcache-embed-v1"), + vectorizer=HFTextVectorizer(model="redis/langcache-embed-v2"), ) ``` -To move an existing cache to v2, call `clear()` on it and let it refill. `overwrite=True` is not enough: it rebuilds the index but keeps the stored entries, which are then indexed again with their v1 vectors. From then on, pass `vectorizer=HFTextVectorizer(model="redis/langcache-embed-v2")` explicitly, since the warning fires for any existing cache opened without one. Distances differ between models: v2 places the same pair of prompts slightly further apart than v1 does, so at an unchanged `distance_threshold` it matches somewhat fewer paraphrases. Check your threshold after switching. +`redis/langcache-embed-v2` is trained for matching cache prompts. Any vectorizer works, including hosted providers that need no local model. + +Leaving the argument out is deprecated. The extension still falls back to a local Hugging Face model, which needs the `sentence-transformers` extra and downloads the model on first use: `redis/langcache-embed-v1` for `SemanticCache`, and `sentence-transformers/all-mpnet-base-v2` for the other two. It also emits a `DeprecationWarning` naming the model. A future major release will require the argument. + +Stored data only matches queries embedded with the model that wrote it. If you relied on the fallback, pass that same model explicitly to keep using what you have stored. Two models with the same output size, such as `langcache-embed-v1` and `-v2`, fit the same index without an error, so a mismatch shows up only as wrong matches. To move a cache to a different model, call `clear()` and let it refill. `overwrite=True` rebuilds the index but keeps the stored entries and their old vectors. Distances also differ between models, so check your distance threshold after switching. + +## Semantic Cache + +LLM API calls are expensive and slow. If users ask similar questions, you're paying to generate similar answers repeatedly. Semantic caching solves this by storing responses and returning cached answers when similar prompts are seen again. + +### How It Works + +When a prompt arrives, the cache embeds it and searches for similar cached prompts. If a match is found within the configured distance threshold, the cached response is returned immediately—no LLM call needed. If no match is found, you call the LLM, store the prompt-response pair, and return the response. + +The key insight is "similar" rather than "identical." Traditional caching requires exact matches. Semantic caching matches by meaning, so "What's the capital of France?" and "Tell me France's capital city" can hit the same cache entry. ### Threshold Tuning diff --git a/docs/user_guide/installation.md b/docs/user_guide/installation.md index 30a0ccc22..05394b17d 100644 --- a/docs/user_guide/installation.md +++ b/docs/user_guide/installation.md @@ -250,6 +250,7 @@ RedisVL does not guess its way around this. A credential that cannot ask whether ```python cache = SemanticCache( name="llmcache", + vectorizer=HFTextVectorizer(model="redis/langcache-embed-v2"), redis_url="redis://localhost:6379", create_index=False, ) diff --git a/redisvl/extensions/cache/llm/semantic.py b/redisvl/extensions/cache/llm/semantic.py index cb6f2b38b..f93c63d01 100644 --- a/redisvl/extensions/cache/llm/semantic.py +++ b/redisvl/extensions/cache/llm/semantic.py @@ -1,4 +1,5 @@ from typing import Any +from warnings import warn from pydantic import ValidationError from redis import Redis @@ -14,6 +15,7 @@ CREATE_INDEX_OVERWRITE_CONFLICT, ENTRY_ID_FIELD_NAME, EXTERNAL_INDEX_DROP_CONFLICT, + IMPLICIT_VECTORIZER_DEPRECATED, INSERTED_AT_FIELD_NAME, METADATA_FIELD_NAME, PROMPT_FIELD_NAME, @@ -37,23 +39,9 @@ logger = get_logger("[RedisVL]") -DEFAULT_VECTORIZER_MODEL = "redis/langcache-embed-v2" - -# Emitted when the caller did not choose a vectorizer and the index predates this -# call, so its vectors may have been written with the previous default model. -# Both models emit 768-dimension vectors, so the schema check below cannot tell -# them apart and a mismatch shows up only as wrong hits and misses. -# Remove this warning once v1-era caches are no longer expected. -DEFAULT_VECTORIZER_CHANGED_WARNING = ( - "The default SemanticCache vectorizer is now `redis/langcache-embed-v2`; it " - "was `redis/langcache-embed-v1`. This cache's index already exists, and if its " - "entries were embedded with v1, lookups embedded with v2 return wrong hits and " - "misses without raising an error. To keep using v1, pass " - "vectorizer=HFTextVectorizer(model='redis/langcache-embed-v1'). To move to v2, " - "call clear() and let the cache refill; overwrite=True keeps the old entries. " - "Pass a vectorizer explicitly to silence this warning. " - "See https://huggingface.co/redis/langcache-embed-v2." -) +# Used only when the caller passes no vectorizer, which is deprecated. It stays +# at the model existing caches were written with until the fallback is removed. +DEFAULT_VECTORIZER_MODEL = "redis/langcache-embed-v1" class SemanticCache(BaseLLMCache): @@ -88,11 +76,11 @@ def __init__( ttl (Optional[int], optional): The time-to-live for records cached in Redis. Defaults to None. vectorizer (Optional[BaseVectorizer], optional): The vectorizer for the cache. - Defaults to ``HFTextVectorizer(model="redis/langcache-embed-v2")``. - Before this default changed it was ``redis/langcache-embed-v1``; - an existing cache written with v1 must pass that model explicitly - or be emptied with ``clear()``, since v2 query vectors fit a v1 index without error - but match the wrong entries. + Pass one explicitly. Omitting it is deprecated: it falls back to + ``HFTextVectorizer(model="redis/langcache-embed-v1")`` + with a ``DeprecationWarning``, and a future major release will make it + required. Data already stored under the fallback only matches queries + embedded with that same model. filterable_fields (Optional[List[Dict[str, Any]]]): An optional list of RedisVL fields that can be used to customize cache retrieval with filters. redis_client(Optional[Redis], optional): A redis client connection instance. @@ -124,14 +112,22 @@ def __init__( .. code-block:: python from redisvl.extensions.cache.llm import SemanticCache + from redisvl.utils.vectorize import HFTextVectorizer + + vectorizer = HFTextVectorizer(model="redis/langcache-embed-v2") # RedisVL creates the index if it is missing - cache = SemanticCache(name="llmcache", redis_url="redis://localhost:6379") + cache = SemanticCache( + name="llmcache", + vectorizer=vectorizer, + redis_url="redis://localhost:6379", + ) # the index is managed externally, or this credential cannot run # FT.INFO -- assume the index exists and issue no index command cache = SemanticCache( name="llmcache", + vectorizer=vectorizer, redis_url="redis://localhost:6379", create_index=False, ) @@ -162,7 +158,13 @@ def __init__( ) self._vectorizer = vectorizer else: - # Create the default vectorizer + warn( + IMPLICIT_VECTORIZER_DEPRECATED.format( + owner="SemanticCache", model=DEFAULT_VECTORIZER_MODEL + ), + DeprecationWarning, + stacklevel=3, + ) vectorizer_kwargs = kwargs if dtype: @@ -207,9 +209,6 @@ def __init__( if create_index: if not self.overwrite and self._index.exists(): - if not vectorizer: - logger.warning(DEFAULT_VECTORIZER_CHANGED_WARNING) - existing_index = SearchIndex.from_existing( name, redis_client=self._index._redis_client ) @@ -222,11 +221,6 @@ def __init__( # Create the search index in Redis self._index.create(overwrite=self.overwrite, drop=False) else: - # The flag asserts the index already exists, which is exactly this - # warning's precondition -- so it still applies here. - if not vectorizer: - logger.warning(DEFAULT_VECTORIZER_CHANGED_WARNING) - logger.debug( f"create_index=False: assuming index {name!r} exists over prefix " f"{schema.index.prefix!r} with {self._vectorizer.dims} vector " diff --git a/redisvl/extensions/constants.py b/redisvl/extensions/constants.py index 2271be35b..e1101675f 100644 --- a/redisvl/extensions/constants.py +++ b/redisvl/extensions/constants.py @@ -50,3 +50,15 @@ "path to drop it. To remove every entry while leaving the index in place, " "use clear()." ) + +# Warned by SemanticCache, SemanticMessageHistory and SemanticRouter when the +# caller passes no vectorizer. Format with ``owner`` (the class name) and +# ``model`` (the fallback model). The fallback stays unchanged until it is +# removed, so data stored under it keeps matching. +IMPLICIT_VECTORIZER_DEPRECATED: str = ( + "{owner} was created without a vectorizer, so it fell back to " + "HFTextVectorizer(model='{model}'). This fallback is deprecated, and a future " + "major release will require the vectorizer argument. Pass a vectorizer " + "explicitly; to keep matching data already stored under the fallback, pass " + "the same model: vectorizer=HFTextVectorizer(model='{model}')." +) diff --git a/redisvl/extensions/message_history/semantic_history.py b/redisvl/extensions/message_history/semantic_history.py index dc02c70bb..9c034245f 100644 --- a/redisvl/extensions/message_history/semantic_history.py +++ b/redisvl/extensions/message_history/semantic_history.py @@ -1,4 +1,5 @@ from typing import Any +from warnings import warn from redis import Redis @@ -7,6 +8,7 @@ CREATE_INDEX_OVERWRITE_CONFLICT, EXTERNAL_INDEX_DROP_CONFLICT, ID_FIELD_NAME, + IMPLICIT_VECTORIZER_DEPRECATED, MESSAGE_VECTOR_FIELD_NAME, METADATA_FIELD_NAME, ROLE_FIELD_NAME, @@ -28,6 +30,10 @@ logger = get_logger(__name__) +# Used only when the caller passes no vectorizer, which is deprecated. It stays +# at the model existing data was written with until the fallback is removed. +DEFAULT_VECTORIZER_MODEL = "sentence-transformers/all-mpnet-base-v2" + class SemanticMessageHistory(BaseMessageHistory): @@ -60,6 +66,11 @@ def __init__( prefix (Optional[str]): Prefix for the keys for this message data. Defaults to None and will be replaced with the index name. vectorizer (Optional[BaseVectorizer]): The vectorizer used to create embeddings. + Pass one explicitly. Omitting it is deprecated: it falls back to + ``HFTextVectorizer(model="sentence-transformers/all-mpnet-base-v2")`` + with a ``DeprecationWarning``, and a future major release will make it + required. Data already stored under the fallback only matches queries + embedded with that same model. distance_threshold (float): The maximum semantic distance to be included in the context. Defaults to 0.3. redis_client (Optional[Redis]): A Redis client instance. Defaults to @@ -102,13 +113,20 @@ def __init__( f"Provided dtype {dtype} does not match vectorizer dtype {vectorizer.dtype}" ) else: + warn( + IMPLICIT_VECTORIZER_DEPRECATED.format( + owner="SemanticMessageHistory", model=DEFAULT_VECTORIZER_MODEL + ), + DeprecationWarning, + stacklevel=3, + ) vectorizer_kwargs = kwargs if dtype: vectorizer_kwargs.update(**{"dtype": dtype}) vectorizer = HFTextVectorizer( - model="sentence-transformers/all-mpnet-base-v2", + model=DEFAULT_VECTORIZER_MODEL, **vectorizer_kwargs, ) diff --git a/redisvl/extensions/router/semantic.py b/redisvl/extensions/router/semantic.py index 5e600562d..db5d554dc 100644 --- a/redisvl/extensions/router/semantic.py +++ b/redisvl/extensions/router/semantic.py @@ -1,5 +1,6 @@ from pathlib import Path from typing import Any, NoReturn +from warnings import warn import redis.commands.search.reducers as reducers import yaml @@ -11,6 +12,7 @@ from redisvl.extensions.constants import ( CREATE_INDEX_OVERWRITE_CONFLICT, EXTERNAL_INDEX_DROP_CONFLICT, + IMPLICIT_VECTORIZER_DEPRECATED, ROUTE_VECTOR_FIELD_NAME, ) from redisvl.extensions.router.schema import ( @@ -38,6 +40,10 @@ logger = get_logger(__name__) +# Used only when the caller passes no vectorizer, which is deprecated. It stays +# at the model existing data was written with until the fallback is removed. +DEFAULT_VECTORIZER_MODEL = "sentence-transformers/all-mpnet-base-v2" + class SemanticRouter(BaseModel): """Semantic Router for managing and querying route vectors.""" @@ -78,7 +84,12 @@ def __init__( Args: name (str): The name of the semantic router. routes (List[Route]): List of Route objects. - vectorizer (BaseVectorizer, optional): The vectorizer used to embed route references. Defaults to default HFTextVectorizer. + vectorizer (BaseVectorizer, optional): The vectorizer used to embed route references. + Pass one explicitly. Omitting it is deprecated: it falls back to + ``HFTextVectorizer(model="sentence-transformers/all-mpnet-base-v2")`` + with a ``DeprecationWarning``, and a future major release will make it + required. Data already stored under the fallback only matches queries + embedded with that same model. routing_config (RoutingConfig, optional): Configuration for routing behavior. Defaults to the default RoutingConfig. redis_client (Optional[SyncRedisClient], optional): Redis client for connection. Defaults to None. redis_url (str, optional): The redis url. Defaults to redis://localhost:6379. @@ -117,13 +128,20 @@ def __init__( f"Provided dtype {dtype} does not match vectorizer dtype {vectorizer.dtype}" ) else: + warn( + IMPLICIT_VECTORIZER_DEPRECATED.format( + owner="SemanticRouter", model=DEFAULT_VECTORIZER_MODEL + ), + DeprecationWarning, + stacklevel=3, + ) vectorizer_kwargs = kwargs if dtype: vectorizer_kwargs.update(**{"dtype": dtype}) vectorizer = HFTextVectorizer( - model="sentence-transformers/all-mpnet-base-v2", + model=DEFAULT_VECTORIZER_MODEL, **vectorizer_kwargs, ) @@ -973,7 +991,16 @@ def to_dict(self) -> dict[str, Any]: .. code-block:: python from redisvl.extensions.router import SemanticRouter - router = SemanticRouter(name="example_router", routes=[], redis_url="redis://localhost:6379") + from redisvl.utils.vectorize import HFTextVectorizer + + router = SemanticRouter( + name="example_router", + routes=[], + vectorizer=HFTextVectorizer( + model="sentence-transformers/all-mpnet-base-v2" + ), + redis_url="redis://localhost:6379", + ) router_dict = router.to_dict() """ return { @@ -1037,10 +1064,15 @@ def to_yaml(self, file_path: str, overwrite: bool = True) -> None: .. code-block:: python from redisvl.extensions.router import SemanticRouter + from redisvl.utils.vectorize import HFTextVectorizer + router = SemanticRouter( name="example_router", routes=[], - redis_url="redis://localhost:6379" + vectorizer=HFTextVectorizer( + model="sentence-transformers/all-mpnet-base-v2" + ), + redis_url="redis://localhost:6379", ) router.to_yaml("router.yaml") """ diff --git a/tests/unit/test_implicit_vectorizer_deprecation.py b/tests/unit/test_implicit_vectorizer_deprecation.py new file mode 100644 index 000000000..95a5617eb --- /dev/null +++ b/tests/unit/test_implicit_vectorizer_deprecation.py @@ -0,0 +1,99 @@ +""" +Constructing SemanticCache, SemanticMessageHistory or SemanticRouter without a +vectorizer is deprecated. + +The fallback model is baked into every stored vector, so these tests pin that +it stays unchanged while deprecated, and that the warning names it so callers +can pass it explicitly. The vectorizer is stubbed so no model is downloaded, +and `create_index=False` with a mock client keeps Redis out of it. +""" + +import warnings +from unittest.mock import MagicMock + +import pytest +from redis import Redis + +from redisvl.extensions.cache.llm import semantic as cache_module +from redisvl.extensions.cache.llm.semantic import SemanticCache +from redisvl.extensions.message_history import semantic_history as history_module +from redisvl.extensions.message_history.semantic_history import SemanticMessageHistory +from redisvl.extensions.router import semantic as router_module +from redisvl.extensions.router.schema import Route +from redisvl.extensions.router.semantic import SemanticRouter +from redisvl.utils.vectorize import CustomVectorizer + +ROUTE = Route(name="greeting", references=["hello"], distance_threshold=0.5) + +CASES = { + "SemanticCache": (cache_module, "redis/langcache-embed-v1", SemanticCache, {}), + "SemanticMessageHistory": ( + history_module, + "sentence-transformers/all-mpnet-base-v2", + SemanticMessageHistory, + {"name": "history"}, + ), + "SemanticRouter": ( + router_module, + "sentence-transformers/all-mpnet-base-v2", + SemanticRouter, + {"name": "router", "routes": [ROUTE]}, + ), +} + + +def _stub_vectorizer(): + return CustomVectorizer(lambda text: [0.1, 0.2, 0.3]) + + +@pytest.fixture(params=list(CASES)) +def case(request, monkeypatch): + module, model, cls, kwargs = CASES[request.param] + built_with = [] + + def fake_hf_vectorizer(model, **kwargs): + built_with.append(model) + return _stub_vectorizer() + + monkeypatch.setattr(module, "HFTextVectorizer", fake_hf_vectorizer) + + def build(**extra): + return cls( + redis_client=MagicMock(spec=Redis), + create_index=False, + **kwargs, + **extra, + ) + + return request.param, model, build, built_with + + +def _deprecations(caught): + return [w for w in caught if issubclass(w.category, DeprecationWarning)] + + +def test_omitting_the_vectorizer_warns_and_keeps_the_fallback(case): + owner, model, build, built_with = case + + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter("always") + build() + + assert built_with == [model] + [warning] = _deprecations(caught) + message = str(warning.message) + assert owner in message + assert f"vectorizer=HFTextVectorizer(model='{model}')" in message + # Attributed to the caller, not to RedisVL's own frames. + assert warning.filename == __file__ + + +def test_an_explicit_vectorizer_does_not_warn(case): + _, _, build, built_with = case + + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter("always") + build(vectorizer=_stub_vectorizer()) + + assert built_with == [] + assert _deprecations(caught) == [] diff --git a/tests/unit/test_semantic_cache_default_vectorizer.py b/tests/unit/test_semantic_cache_default_vectorizer.py deleted file mode 100644 index 30f818fb4..000000000 --- a/tests/unit/test_semantic_cache_default_vectorizer.py +++ /dev/null @@ -1,90 +0,0 @@ -""" -The default SemanticCache vectorizer, and the warning for caches that predate it. - -`redis/langcache-embed-v1` and `-v2` both emit 768-dimension vectors, so a v1 -index accepts v2 query vectors and the schema check cannot catch the mismatch. -The warning is the only signal a caller gets, so these tests pin when it fires -and that it names the way to keep v1. The vectorizer is stubbed so no model is -downloaded, and the Redis client is a mock so no server is needed. -""" - -import logging -from unittest.mock import ANY, MagicMock - -import pytest -from redis import Redis - -from redisvl.extensions.cache.llm import semantic -from redisvl.extensions.cache.llm.semantic import ( - DEFAULT_VECTORIZER_CHANGED_WARNING, - SemanticCache, -) -from redisvl.index import SearchIndex -from redisvl.utils.vectorize import CustomVectorizer - - -@pytest.fixture -def default_models(monkeypatch): - """Record the model each default vectorizer is built with.""" - models = [] - - def fake_hf_vectorizer(model, **kwargs): - models.append(model) - return CustomVectorizer(lambda text: [0.1] * 768) - - monkeypatch.setattr(semantic, "HFTextVectorizer", fake_hf_vectorizer) - return models - - -def _warned(caplog): - return DEFAULT_VECTORIZER_CHANGED_WARNING in caplog.messages - - -def test_default_vectorizer_is_langcache_embed_v2(default_models): - SemanticCache(redis_client=MagicMock(spec=Redis), create_index=False) - - assert default_models == ["redis/langcache-embed-v2"] - - -def test_warning_names_how_to_keep_v1(): - assert ( - "vectorizer=HFTextVectorizer(model='redis/langcache-embed-v1')" - in DEFAULT_VECTORIZER_CHANGED_WARNING - ) - - -@pytest.mark.parametrize("explicit_vectorizer", [False, True]) -def test_warns_on_existing_index_only_without_a_vectorizer( - default_models, monkeypatch, caplog, explicit_vectorizer -): - monkeypatch.setattr(SearchIndex, "exists", lambda self: True) - monkeypatch.setattr(SearchIndex, "create", lambda self, **kwargs: None) - # The live schema matches, exactly as a v1-era cache's would: same dims. - existing = MagicMock() - existing.schema.to_dict.return_value = ANY - monkeypatch.setattr(SearchIndex, "from_existing", lambda name, **kw: existing) - kwargs = {} - if explicit_vectorizer: - kwargs["vectorizer"] = CustomVectorizer(lambda text: [0.1] * 768) - - with caplog.at_level(logging.WARNING): - SemanticCache(redis_client=MagicMock(spec=Redis), **kwargs) - - assert _warned(caplog) is not explicit_vectorizer - - -def test_no_warning_when_the_index_is_new(default_models, monkeypatch, caplog): - monkeypatch.setattr(SearchIndex, "exists", lambda self: False) - monkeypatch.setattr(SearchIndex, "create", lambda self, **kwargs: None) - - with caplog.at_level(logging.WARNING): - SemanticCache(redis_client=MagicMock(spec=Redis)) - - assert not _warned(caplog) - - -def test_warns_when_index_is_asserted_to_exist(default_models, caplog): - with caplog.at_level(logging.WARNING): - SemanticCache(redis_client=MagicMock(spec=Redis), create_index=False) - - assert _warned(caplog) From bf16e3fddec25e144ad434bad3796a6eae959f15 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Wed, 4 Nov 2026 16:46:56 +0100 Subject: [PATCH 5/6] fix(extensions): keep dtype in the suggested vectorizer; doc model-matching caveats The deprecation warning's suggested replacement dropped a dtype the caller had set, which would embed at a different width than the stored data. Also note that create_index=False examples must use the model that wrote the index, and that clear() only migrates between models of the same output size. --- docs/concepts/extensions.md | 2 +- docs/user_guide/installation.md | 2 ++ redisvl/extensions/cache/llm/semantic.py | 9 ++++--- redisvl/extensions/constants.py | 26 +++++++++++++------ .../message_history/semantic_history.py | 6 ++--- redisvl/extensions/router/semantic.py | 6 ++--- .../test_implicit_vectorizer_deprecation.py | 14 ++++++++++ 7 files changed, 46 insertions(+), 19 deletions(-) diff --git a/docs/concepts/extensions.md b/docs/concepts/extensions.md index 0fb0fba3c..6251efc75 100644 --- a/docs/concepts/extensions.md +++ b/docs/concepts/extensions.md @@ -29,7 +29,7 @@ cache = SemanticCache( Leaving the argument out is deprecated. The extension still falls back to a local Hugging Face model, which needs the `sentence-transformers` extra and downloads the model on first use: `redis/langcache-embed-v1` for `SemanticCache`, and `sentence-transformers/all-mpnet-base-v2` for the other two. It also emits a `DeprecationWarning` naming the model. A future major release will require the argument. -Stored data only matches queries embedded with the model that wrote it. If you relied on the fallback, pass that same model explicitly to keep using what you have stored. Two models with the same output size, such as `langcache-embed-v1` and `-v2`, fit the same index without an error, so a mismatch shows up only as wrong matches. To move a cache to a different model, call `clear()` and let it refill. `overwrite=True` rebuilds the index but keeps the stored entries and their old vectors. Distances also differ between models, so check your distance threshold after switching. +Stored data only matches queries embedded with the model that wrote it. If you relied on the fallback, pass that same model explicitly to keep using what you have stored. Two models with the same output size, such as `langcache-embed-v1` and `-v2`, fit the same index without an error, so a mismatch shows up only as wrong matches. To move a cache to a different model of the same output size, call `clear()` and let it refill; if the size differs, call `delete()` and construct the cache again with the new vectorizer. `overwrite=True` rebuilds the index but keeps the stored entries and their old vectors. Distances also differ between models, so check your distance threshold after switching. ## Semantic Cache diff --git a/docs/user_guide/installation.md b/docs/user_guide/installation.md index 05394b17d..eced7c933 100644 --- a/docs/user_guide/installation.md +++ b/docs/user_guide/installation.md @@ -250,6 +250,8 @@ RedisVL does not guess its way around this. A credential that cannot ask whether ```python cache = SemanticCache( name="llmcache", + # Use the model that wrote the cache: the schema check is skipped, so a + # different model of the same size matches the wrong entries silently. vectorizer=HFTextVectorizer(model="redis/langcache-embed-v2"), redis_url="redis://localhost:6379", create_index=False, diff --git a/redisvl/extensions/cache/llm/semantic.py b/redisvl/extensions/cache/llm/semantic.py index f93c63d01..c1c9270d6 100644 --- a/redisvl/extensions/cache/llm/semantic.py +++ b/redisvl/extensions/cache/llm/semantic.py @@ -15,13 +15,13 @@ CREATE_INDEX_OVERWRITE_CONFLICT, ENTRY_ID_FIELD_NAME, EXTERNAL_INDEX_DROP_CONFLICT, - IMPLICIT_VECTORIZER_DEPRECATED, INSERTED_AT_FIELD_NAME, METADATA_FIELD_NAME, PROMPT_FIELD_NAME, REDIS_KEY_FIELD_NAME, RESPONSE_FIELD_NAME, UPDATED_AT_FIELD_NAME, + implicit_vectorizer_deprecation, ) from redisvl.index import AsyncSearchIndex, SearchIndex from redisvl.query import VectorQuery @@ -124,7 +124,8 @@ def __init__( ) # the index is managed externally, or this credential cannot run - # FT.INFO -- assume the index exists and issue no index command + # FT.INFO -- assume the index exists and issue no index command. + # The vectorizer must be the model that populated the index. cache = SemanticCache( name="llmcache", vectorizer=vectorizer, @@ -159,8 +160,8 @@ def __init__( self._vectorizer = vectorizer else: warn( - IMPLICIT_VECTORIZER_DEPRECATED.format( - owner="SemanticCache", model=DEFAULT_VECTORIZER_MODEL + implicit_vectorizer_deprecation( + "SemanticCache", DEFAULT_VECTORIZER_MODEL, dtype ), DeprecationWarning, stacklevel=3, diff --git a/redisvl/extensions/constants.py b/redisvl/extensions/constants.py index e1101675f..40b31ac54 100644 --- a/redisvl/extensions/constants.py +++ b/redisvl/extensions/constants.py @@ -52,13 +52,23 @@ ) # Warned by SemanticCache, SemanticMessageHistory and SemanticRouter when the -# caller passes no vectorizer. Format with ``owner`` (the class name) and -# ``model`` (the fallback model). The fallback stays unchanged until it is -# removed, so data stored under it keeps matching. +# caller passes no vectorizer. The fallback stays unchanged until it is removed, +# so data stored under it keeps matching. IMPLICIT_VECTORIZER_DEPRECATED: str = ( - "{owner} was created without a vectorizer, so it fell back to " - "HFTextVectorizer(model='{model}'). This fallback is deprecated, and a future " - "major release will require the vectorizer argument. Pass a vectorizer " - "explicitly; to keep matching data already stored under the fallback, pass " - "the same model: vectorizer=HFTextVectorizer(model='{model}')." + "{owner} was created without a vectorizer, so it fell back to {call}. This " + "fallback is deprecated, and a future major release will require the " + "vectorizer argument. Pass a vectorizer explicitly; to keep matching data " + "already stored under the fallback, pass the same one: vectorizer={call}." ) + + +def implicit_vectorizer_deprecation(owner: str, model: str, dtype: str | None) -> str: + """Format IMPLICIT_VECTORIZER_DEPRECATED with the exact fallback call. + + ``dtype`` is included when the caller set it, because a replacement that + drops it embeds at a different width than the data already stored. + """ + args = f"model='{model}'" + (f", dtype='{dtype}'" if dtype else "") + return IMPLICIT_VECTORIZER_DEPRECATED.format( + owner=owner, call=f"HFTextVectorizer({args})" + ) diff --git a/redisvl/extensions/message_history/semantic_history.py b/redisvl/extensions/message_history/semantic_history.py index 9c034245f..8d75d348e 100644 --- a/redisvl/extensions/message_history/semantic_history.py +++ b/redisvl/extensions/message_history/semantic_history.py @@ -8,13 +8,13 @@ CREATE_INDEX_OVERWRITE_CONFLICT, EXTERNAL_INDEX_DROP_CONFLICT, ID_FIELD_NAME, - IMPLICIT_VECTORIZER_DEPRECATED, MESSAGE_VECTOR_FIELD_NAME, METADATA_FIELD_NAME, ROLE_FIELD_NAME, SESSION_FIELD_NAME, TIMESTAMP_FIELD_NAME, TOOL_FIELD_NAME, + implicit_vectorizer_deprecation, ) from redisvl.extensions.message_history import BaseMessageHistory from redisvl.extensions.message_history.schema import ( @@ -114,8 +114,8 @@ def __init__( ) else: warn( - IMPLICIT_VECTORIZER_DEPRECATED.format( - owner="SemanticMessageHistory", model=DEFAULT_VECTORIZER_MODEL + implicit_vectorizer_deprecation( + "SemanticMessageHistory", DEFAULT_VECTORIZER_MODEL, dtype ), DeprecationWarning, stacklevel=3, diff --git a/redisvl/extensions/router/semantic.py b/redisvl/extensions/router/semantic.py index db5d554dc..3d5ae352a 100644 --- a/redisvl/extensions/router/semantic.py +++ b/redisvl/extensions/router/semantic.py @@ -12,8 +12,8 @@ from redisvl.extensions.constants import ( CREATE_INDEX_OVERWRITE_CONFLICT, EXTERNAL_INDEX_DROP_CONFLICT, - IMPLICIT_VECTORIZER_DEPRECATED, ROUTE_VECTOR_FIELD_NAME, + implicit_vectorizer_deprecation, ) from redisvl.extensions.router.schema import ( DistanceAggregationMethod, @@ -129,8 +129,8 @@ def __init__( ) else: warn( - IMPLICIT_VECTORIZER_DEPRECATED.format( - owner="SemanticRouter", model=DEFAULT_VECTORIZER_MODEL + implicit_vectorizer_deprecation( + "SemanticRouter", DEFAULT_VECTORIZER_MODEL, dtype ), DeprecationWarning, stacklevel=3, diff --git a/tests/unit/test_implicit_vectorizer_deprecation.py b/tests/unit/test_implicit_vectorizer_deprecation.py index 95a5617eb..b7ce5e8f9 100644 --- a/tests/unit/test_implicit_vectorizer_deprecation.py +++ b/tests/unit/test_implicit_vectorizer_deprecation.py @@ -97,3 +97,17 @@ def test_an_explicit_vectorizer_does_not_warn(case): assert built_with == [] assert _deprecations(caught) == [] + + +def test_the_suggested_replacement_keeps_the_dtype(case): + # A replacement that drops dtype embeds at a different width than the + # data already stored, so the warning must carry it over. + _, model, build, _ = case + + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter("always") + build(dtype="float16") + + messages = [str(w.message) for w in _deprecations(caught)] + expected = f"vectorizer=HFTextVectorizer(model='{model}', dtype='float16')" + assert any(expected in message for message in messages) From 04c5b46171a9bd94b125c2eba96f3e26ed0ce115 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Mon, 9 Nov 2026 17:29:01 +0100 Subject: [PATCH 6/6] docs: pass an explicit vectorizer in the observability and message history guides Both examples relied on the deprecated fallback and would now print a DeprecationWarning. The message history guide passes the same all-mpnet-base-v2 model the fallback used, so its threshold and saved outputs stay valid. --- docs/user_guide/07_message_history.ipynb | 7 ++++++- docs/user_guide/how_to_guides/observability.md | 7 ++++++- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/user_guide/07_message_history.ipynb b/docs/user_guide/07_message_history.ipynb index 6f112c47b..3e7953ba8 100644 --- a/docs/user_guide/07_message_history.ipynb +++ b/docs/user_guide/07_message_history.ipynb @@ -247,7 +247,12 @@ "outputs": [], "source": [ "from redisvl.extensions.message_history import SemanticMessageHistory\n", - "semantic_history = SemanticMessageHistory(name='tutor')\n", + "from redisvl.utils.vectorize import HFTextVectorizer\n", + "\n", + "semantic_history = SemanticMessageHistory(\n", + " name='tutor',\n", + " vectorizer=HFTextVectorizer(model='sentence-transformers/all-mpnet-base-v2'),\n", + ")\n", "\n", "semantic_history.add_messages(chat_history.get_recent(top_k=8))" ] diff --git a/docs/user_guide/how_to_guides/observability.md b/docs/user_guide/how_to_guides/observability.md index 67e6fd9db..017880fc4 100644 --- a/docs/user_guide/how_to_guides/observability.md +++ b/docs/user_guide/how_to_guides/observability.md @@ -37,6 +37,7 @@ from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor from redisvl.extensions.cache.llm import SemanticCache +from redisvl.utils.vectorize import HFTextVectorizer tracer_provider = TracerProvider() tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter())) @@ -46,7 +47,11 @@ metrics.set_meter_provider( MeterProvider(metric_readers=[PeriodicExportingMetricReader(OTLPMetricExporter())]) ) -cache = SemanticCache(name="llmcache", redis_url="redis://localhost:6379") +cache = SemanticCache( + name="llmcache", + vectorizer=HFTextVectorizer(model="redis/langcache-embed-v2"), + redis_url="redis://localhost:6379", +) cache.store(prompt="What is the capital of France?", response="Paris") cache.check(prompt="What's the capital of France?") ```