diff --git a/docs/concepts/extensions.md b/docs/concepts/extensions.md index 54c54eb5..6251efc7 100644 --- a/docs/concepts/extensions.md +++ b/docs/concepts/extensions.md @@ -11,6 +11,26 @@ 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. +## Choosing a Vectorizer + +`SemanticCache`, `SemanticMessageHistory` and `SemanticRouter` embed text, so each needs a {doc}`vectorizer `. Pass one 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-v2"), +) +``` + +`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 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 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. diff --git a/docs/user_guide/07_message_history.ipynb b/docs/user_guide/07_message_history.ipynb index 6f112c47..3e7953ba 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 9705415a..c36f6fb1 100644 --- a/docs/user_guide/how_to_guides/observability.md +++ b/docs/user_guide/how_to_guides/observability.md @@ -39,6 +39,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())) @@ -48,7 +49,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?") ``` diff --git a/docs/user_guide/installation.md b/docs/user_guide/installation.md index 9c8f7a26..bdbfce72 100644 --- a/docs/user_guide/installation.md +++ b/docs/user_guide/installation.md @@ -251,6 +251,9 @@ 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 844a0a46..1b07462c 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 @@ -21,6 +22,7 @@ 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 @@ -40,17 +42,9 @@ logger = get_logger("[RedisVL]") -# 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. -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')" -) +# 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): @@ -86,7 +80,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. + 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. @@ -122,14 +120,23 @@ 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 + # 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, redis_url="redis://localhost:6379", create_index=False, ) @@ -164,14 +171,20 @@ def __init__( ) self._vectorizer = vectorizer else: - # Create the default vectorizer + warn( + implicit_vectorizer_deprecation( + "SemanticCache", DEFAULT_VECTORIZER_MODEL, dtype + ), + DeprecationWarning, + stacklevel=3, + ) vectorizer_kwargs = kwargs if dtype: vectorizer_kwargs.update(dtype=dtype) self._vectorizer = HFTextVectorizer( - model="redis/langcache-embed-v1", + model=DEFAULT_VECTORIZER_MODEL, **vectorizer_kwargs, ) @@ -209,9 +222,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 ) @@ -224,11 +234,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 2271be35..40b31ac5 100644 --- a/redisvl/extensions/constants.py +++ b/redisvl/extensions/constants.py @@ -50,3 +50,25 @@ "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. 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 {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 75784ad8..9637cc14 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 @@ -13,6 +14,7 @@ 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 ( @@ -34,6 +36,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): @@ -66,6 +72,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, in Redis COSINE units [0-2]. Defaults to 0.3. @@ -115,13 +126,20 @@ def __init__( f"Provided dtype {dtype} does not match vectorizer dtype {vectorizer.dtype}" ) else: + warn( + implicit_vectorizer_deprecation( + "SemanticMessageHistory", DEFAULT_VECTORIZER_MODEL, dtype + ), + 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 441b1761..f2500260 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, Self +from warnings import warn import redis.commands.search.reducers as reducers import yaml @@ -12,6 +13,7 @@ CREATE_INDEX_OVERWRITE_CONFLICT, EXTERNAL_INDEX_DROP_CONFLICT, ROUTE_VECTOR_FIELD_NAME, + implicit_vectorizer_deprecation, ) from redisvl.extensions.router.schema import ( DistanceAggregationMethod, @@ -40,6 +42,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" + _DISTANCE_THRESHOLD_ADAPTER = TypeAdapter(DistanceThreshold) @@ -82,7 +88,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. @@ -121,13 +132,20 @@ def __init__( f"Provided dtype {dtype} does not match vectorizer dtype {vectorizer.dtype}" ) else: + warn( + implicit_vectorizer_deprecation( + "SemanticRouter", DEFAULT_VECTORIZER_MODEL, dtype + ), + 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, ) @@ -994,7 +1012,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 { @@ -1058,10 +1085,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/integration/test_llmcache.py b/tests/integration/test_llmcache.py index e43c0e6a..17f5b254 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 @@ -897,9 +897,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" @@ -923,7 +927,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_implicit_vectorizer_deprecation.py b/tests/unit/test_implicit_vectorizer_deprecation.py new file mode 100644 index 00000000..b7ce5e8f --- /dev/null +++ b/tests/unit/test_implicit_vectorizer_deprecation.py @@ -0,0 +1,113 @@ +""" +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) == [] + + +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)