Skip to content

feat(extensions): deprecate the implicit default vectorizer - #839

Open
vishal-bala wants to merge 11 commits into
fix/semantic-cache-uniform-distance-thresholdfrom
feat/deprecate-implicit-vectorizer
Open

vishal-bala wants to merge 11 commits into
fix/semantic-cache-uniform-distance-thresholdfrom
feat/deprecate-implicit-vectorizer

Conversation

@vishal-bala

@vishal-bala vishal-bala commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

Motivation

SemanticCache, SemanticMessageHistory and SemanticRouter fall back to a local Hugging Face model when no vectorizer is passed. The fallback costs more than it saves:

  • It needs the optional sentence-transformers extra, so on a plain pip install redisvl it raises ImportError.
  • It downloads a model of several hundred megabytes when the object is constructed.
  • It hides a choice that ends up in stored data. The model is baked into every stored vector, so changing the default would silently break existing caches. redis/langcache-embed-v1 and -v2 have 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, including dtype when the caller set one, so it can be pasted in to keep matching stored data. The fallbacks are unchanged: redis/langcache-embed-v1 for the cache, and sentence-transformers/all-mpnet-base-v2 for the history and the router. The message is built by implicit_vectorizer_deprecation() in redisvl/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.md gains 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, and overwrite=True does not work because it keeps the stored vectors.

  • Docstring examples, the create_index=False snippet in installation.md, the observability guide and the semantic message history section of 07_message_history.ipynb now pass a vectorizer. The notebook uses the same all-mpnet-base-v2 model as the fallback, so its threshold and saved outputs stay valid.
  • tests/unit/test_implicit_vectorizer_deprecation.py covers all three classes:
    • the warning, its attribution to the caller and the unchanged fallback;
    • no warning when a vectorizer is passed;
    • dtype carried into the suggested replacement.
  • The tests/integration/test_llmcache.py fixture uses redis/langcache-embed-v2, the model the docs recommend. test_cache_filtering passes 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 changes SemanticCache and 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 dtype passthrough 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, SemanticMessageHistory or SemanticRouter without a vectorizer is deprecated and now emits a DeprecationWarning; 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 example vectorizer=HFTextVectorizer(model="redis/langcache-embed-v1") for SemanticCache.

Reviewer Brief

Start here: implicit_vectorizer_deprecation() in redisvl/extensions/constants.py and 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

  • The 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.
  • The suggested call carries model and dtype only. Other HFTextVectorizer kwargs that reach the fallback through **kwargs are 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_llmcache and 10_embeddings_cache change on a separate branch); sentence-transformers at the 5.2.0 floor (runs used 5.7.0).

Beyond CI: after merging main, tests/unit and the llmcache, router, message-history, SemanticCache metrics and tracing integration tests passed locally with Docker on Python 3.13, and 07_message_history.ipynb passed under nbval.

Since the last brief: merged main at 14d5f501 (an import-line conflict in redisvl/extensions/router/semantic.py, resolved by keeping both imports) and the uniform distance threshold fix's branch at b8808d03 (no conflicts); the unit, llmcache, router, message-history and SemanticCache telemetry tests passed again on top. Merged the base branch again at 7f6d9854, which now validates thresholds before any default model is built. In redisvl/extensions/router/semantic.py, the base's _DISTANCE_THRESHOLD_ADAPTER and this PR's DEFAULT_VECTORIZER_MODEL were added in the same spot; I kept both. The same tests passed again.

Reviewed 1d281d4c (merged with main at 14d5f501), fixes in bf16e3fd, 04c5b461 · Claude Code (claude-opus-5-5) · lenses: correctness, tests, design, docs


Note

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, or SemanticRouter without a vectorizer is now deprecated. Each constructor still uses the same implicit Hugging Face fallback as before, but emits a DeprecationWarning (via implicit_vectorizer_deprecation() in redisvl/extensions/constants.py) that names the exact HFTextVectorizer(...) call to pass—including dtype when set—so existing stored vectors keep matching.

SemanticCache drops 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 to redis/langcache-embed-v2 and 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.

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
@vishal-bala vishal-bala added the auto:minor Increment the minor version when merged label Nov 19, 2026
…nce-threshold' into feat/deprecate-implicit-vectorizer
@vishal-bala
vishal-bala changed the base branch from main to fix/semantic-cache-uniform-distance-threshold November 19, 2026 15:16
@vishal-bala
vishal-bala added this pull request to stack #858 November 19, 2026 15:16
@vishal-bala
vishal-bala marked this pull request as ready for review November 20, 2026 09:21
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-20T09:24:48.990374Z b403263 Draft marked ready
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread README.md Resolved
…://github.com/redis/redis-vl-python into feat/deprecate-implicit-vectorizer

# Conflicts:
#	redisvl/extensions/router/semantic.py
@codecov-commenter

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.72%. Comparing base (7f6d985) to head (fa284e0).

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     
Flag Coverage Δ
cluster ?
core 78.88% <100.00%> (+0.02%) ⬆️
service 79.55% <100.00%> (+0.02%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

auto:minor Increment the minor version when merged

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants