Repository navigation
feat(extensions): deprecate the implicit default vectorizer - #839
vishal-bala wants to merge 11 commits into
Conversation
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.
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.
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.
…tching 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.
…story 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.
…it-vectorizer # Conflicts: # redisvl/extensions/router/semantic.py
…nce-threshold' into feat/deprecate-implicit-vectorizer
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b40326310b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…://github.com/redis/redis-vl-python into feat/deprecate-implicit-vectorizer # Conflicts: # redisvl/extensions/router/semantic.py
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## fix/semantic-cache-uniform-distance-threshold #839 +/- ##
=================================================================================
- Coverage 80.16% 79.72% -0.45%
=================================================================================
Files 121 121
Lines 14947 14877 -70
Branches 2618 2598 -20
=================================================================================
- Hits 11982 11860 -122
+ Misses 2344 2321 -23
- Partials 621 696 +75
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
Motivation
SemanticCache,SemanticMessageHistoryandSemanticRouterfall back to a local Hugging Face model when no vectorizer is passed. The fallback costs more than it saves:sentence-transformersextra, so on a plainpip install redisvlit raisesImportError.redis/langcache-embed-v1and-v2have the same output size, so a v1 cache would accept v2 lookups and return the wrong matches.Requiring the argument makes every model change the caller's explicit decision.
Changes
Deprecation warning
Constructing any of the three classes without a vectorizer now emits a
DeprecationWarning, attributed to the caller's line. The warning names the exact fallback call, includingdtypewhen the caller set one, so it can be pasted in to keep matching stored data. The fallbacks are unchanged:redis/langcache-embed-v1for the cache, andsentence-transformers/all-mpnet-base-v2for the history and the router. The message is built byimplicit_vectorizer_deprecation()inredisvl/extensions/constants.py.SemanticCache's old logger warning, the one that fired for an existing index and described the 0.6.0 change of default, has been removed. The deprecation warning covers that case.Docs
docs/concepts/extensions.mdgains a "Choosing a Vectorizer" section. It covers passing one explicitly, what the fallback does, keeping stored data matching, and moving to another model:clear()works for a model of the same output size,delete()for a different size, andoverwrite=Truedoes not work because it keeps the stored vectors.create_index=Falsesnippet ininstallation.md, the observability guide and the semantic message history section of07_message_history.ipynbnow pass a vectorizer. The notebook uses the sameall-mpnet-base-v2model as the fallback, so its threshold and saved outputs stay valid.tests/unit/test_implicit_vectorizer_deprecation.pycovers all three classes:dtypecarried into the suggested replacement.tests/integration/test_llmcache.pyfixture usesredis/langcache-embed-v2, the model the docs recommend.test_cache_filteringpasses explicit thresholds, because "test prompt 0" sits 0.241 from "test prompt 1" under v2, outside the fixture's 0.2.Notes
This PR is stacked on the SemanticCache uniform distance threshold fix (branch
fix/semantic-cache-uniform-distance-threshold), which also changesSemanticCacheand merges first. This branch includes that fix's branch through a merge commit. The two changes don't overlap: the fix touches threshold validation, and this PR touches vectorizer construction.The fallback models stay as they are while deprecated, so nobody's stored data changes meaning before the argument becomes required. Moving the fallback to v2 first would have broken users twice.
Existing integration tests that construct these classes without a vectorizer, chiefly the
dtypepassthrough tests, are left as they are. They exercise the deprecated path on purpose, and they go when the fallback is removed.Release Notes
Constructing
SemanticCache,SemanticMessageHistoryorSemanticRouterwithout avectorizeris deprecated and now emits aDeprecationWarning; a future release will require the argument. The fallback models are unchanged. To keep matching data you already stored, pass the model named in the warning, for examplevectorizer=HFTextVectorizer(model="redis/langcache-embed-v1")forSemanticCache.Reviewer Brief
Start here:
implicit_vectorizer_deprecation()inredisvl/extensions/constants.pyand its three callers in the constructors. The warning's suggested call is what users will paste in, so it must reproduce the fallback exactly.Where it could fail
warn(..., stacklevel=3)calls in the three constructors assume exactly one wrapper frame from@deprecated_argument. If that decorator gains or loses a frame, the warning points into RedisVL instead of the caller, and Python's default filters then hide it. The unit test asserts the attributed filename.modelanddtypeonly. OtherHFTextVectorizerkwargs that reach the fallback through**kwargsare not repeated in it. None of those kwargs changes the vectors' width.Not verified: API-gated tests; cluster mode; notebooks other than
07_message_history(03_llmcacheand10_embeddings_cachechange on a separate branch); sentence-transformers at the 5.2.0 floor (runs used 5.7.0).Beyond CI: after merging
main,tests/unitand the llmcache, router, message-history, SemanticCache metrics and tracing integration tests passed locally with Docker on Python 3.13, and07_message_history.ipynbpassed under nbval.Since the last brief: merged
mainat14d5f501(an import-line conflict inredisvl/extensions/router/semantic.py, resolved by keeping both imports) and the uniform distance threshold fix's branch atb8808d03(no conflicts); the unit, llmcache, router, message-history and SemanticCache telemetry tests passed again on top. Merged the base branch again at7f6d9854, which now validates thresholds before any default model is built. Inredisvl/extensions/router/semantic.py, the base's_DISTANCE_THRESHOLD_ADAPTERand this PR'sDEFAULT_VECTORIZER_MODELwere added in the same spot; I kept both. The same tests passed again.Reviewed
1d281d4c(merged withmainat14d5f501), fixes inbf16e3fd,04c5b461· Claude Code (claude-opus-5-5) · lenses: correctness, tests, design, docsNote
Medium Risk
Deprecation changes constructor behavior (warnings) for three widely used extensions and documents model/index compatibility pitfalls; fallback embeddings are unchanged so data is not rewritten, but ignoring the warning risks silent wrong matches after a model switch.
Overview
Constructing
SemanticCache,SemanticMessageHistory, orSemanticRouterwithout avectorizeris now deprecated. Each constructor still uses the same implicit Hugging Face fallback as before, but emits aDeprecationWarning(viaimplicit_vectorizer_deprecation()inredisvl/extensions/constants.py) that names the exactHFTextVectorizer(...)call to pass—includingdtypewhen set—so existing stored vectors keep matching.SemanticCachedrops the old logger warning about the 0.6.0 default model change; the deprecation path covers that case. Docs and examples (extensions guide, installation, observability, message-history notebook) now show explicit vectorizers and guidance on model mismatches and cache migration. New unit tests pin warning text, caller attribution, and unchanged fallback models; llmcache integration tests move toredis/langcache-embed-v2and loosen per-check distance thresholds where embedding distances shifted.Reviewed by Cursor Bugbot for commit fa284e0. Bugbot is set up for automated code reviews on this repo. Configure here.