Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions .github/scripts/prefetch_notebook_models.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
"""Download the HuggingFace models that the user-guide notebooks load.

The Notebook Validation job runs this before nbval, so model downloads happen
outside nbval's per-cell timeout. The job's HF cache key hashes this file, so
editing either list below produces a new cache entry that includes the change.
nbval then runs with HF_HUB_OFFLINE=1, so a notebook that loads a model missing
from these lists fails immediately instead of downloading inside a cell.
"""

import time

from redisvl.utils.rerank import HFCrossEncoderReranker
from redisvl.utils.vectorize import HFTextVectorizer

EMBEDDING_MODELS = [
"redis/langcache-embed-v2",
"sentence-transformers/all-mpnet-base-v2", # HFTextVectorizer default
]

RERANKER_MODELS = [
"BAAI/bge-reranker-base",
]


def main() -> None:
# Load through the same classes the notebooks use, so exactly the files
# they need end up in the cache.
for loader, models in (
(HFTextVectorizer, EMBEDDING_MODELS),
(HFCrossEncoderReranker, RERANKER_MODELS),
):
for model in models:
start = time.monotonic()
loader(model=model)
print(f"{model}: {time.monotonic() - start:.1f}s", flush=True)


if __name__ == "__main__":
main()
41 changes: 34 additions & 7 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -39,9 +39,10 @@ jobs:

# The canary saves the PYTHON_VERSION uv cache and, when its tests pass, the
# HuggingFace model cache. It finishes before the matrix starts, so the
# matrix legs and notebooks restore what it saved and never save these
# themselves. When it is skipped (fork and Dependabot PRs) they restore
# from the base branch instead.
# matrix legs restore both and the notebooks restore the uv cache, and
# none of them save these themselves. (The notebooks keep a model cache
# of their own.) When it is skipped (fork and Dependabot PRs) they
# restore from the base branch instead.
- name: Run service tests
uses: ./.github/actions/run-service-tests
with:
Expand Down Expand Up @@ -454,7 +455,8 @@ jobs:
notebooks:
name: Notebook Validation
runs-on: ubuntu-24.04
# Ordered after the HF cache is primed, not gated on it; see the `test` job.
# Ordered after service-tests so it restores the uv cache that job saves;
# not gated on it; see the `test` job.
needs: service-tests
# Needs API-key secrets, unavailable to fork PRs and Dependabot. Keep in
# sync with service-tests.
Expand All @@ -465,12 +467,19 @@ jobs:
- name: Check out repository
uses: actions/checkout@v6

# Restore-only, like the uv cache below: service-tests saves both.
# Separate from the HF cache the test jobs share. service-tests saves that
# one under a static key after its tests, so it holds only the models the
# tests load, and models only the notebooks use were downloaded inside
# nbval cells on every run. This job is the only one that saves this key,
# and the key changes whenever the model list does. There is deliberately
# no restore-keys fallback: an older entry would still hold models since
# removed from the list, and nbval would pass offline on them.
- name: Restore HuggingFace models
id: hf-cache
uses: actions/cache/restore@v5
with:
path: hf_cache
key: ${{ runner.os }}-hf-cache-v2
key: ${{ runner.os }}-hf-notebooks-${{ hashFiles('.github/scripts/prefetch_notebook_models.py') }}

- name: Install Python
uses: actions/setup-python@v6
Expand All @@ -497,6 +506,21 @@ jobs:
run: |
uv sync --all-extras --frozen

- name: Download HuggingFace models
env:
HF_TOKEN: ${{ secrets.HF_TOKEN }}
run: |
uv run --no-sync python .github/scripts/prefetch_notebook_models.py

# Saved here rather than in a post-job step, so a failing notebook does
# not stop the models from being cached.
- name: Save HuggingFace models
if: steps.hf-cache.outputs.cache-hit != 'true'
uses: actions/cache/save@v5
with:
path: hf_cache
key: ${{ steps.hf-cache.outputs.cache-primary-key }}

- name: Start Redis
run: |
set -euo pipefail
Expand Down Expand Up @@ -544,7 +568,10 @@ jobs:
OPENAI_API_VERSION: ${{ secrets.OPENAI_API_VERSION }}
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
HF_TOKEN: ${{ secrets.HF_TOKEN }}
# Every model the notebooks load is downloaded above. A notebook that
# loads one not listed in .github/scripts/prefetch_notebook_models.py
# fails fast here rather than downloading against the cell timeout.
HF_HUB_OFFLINE: "1"
run: |
make test-notebooks

Expand Down
33 changes: 9 additions & 24 deletions docs/user_guide/03_llmcache.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -141,11 +141,14 @@
"from redisvl.extensions.cache.llm import SemanticCache\n",
"from redisvl.utils.vectorize import HFTextVectorizer\n",
"\n",
"# embedding model, shared by every cache in this guide\n",
"vectorizer = HFTextVectorizer(\"redis/langcache-embed-v2\")\n",
"\n",
"llmcache = SemanticCache(\n",
" name=\"llmcache\", # underlying search index name\n",
" redis_url=\"redis://localhost:6379\", # redis connection url string\n",
" distance_threshold=0.1, # semantic cache distance threshold (Redis COSINE [0-2], lower is stricter)\n",
" vectorizer=HFTextVectorizer(\"redis/langcache-embed-v2\"), # embedding model\n",
" name=\"llmcache\", # underlying search index name\n",
" redis_url=\"redis://localhost:6379\", # redis connection url string\n",
" distance_threshold=0.1, # semantic cache distance threshold (Redis COSINE [0-2], lower is stricter)\n",
" vectorizer=vectorizer,\n",
")"
]
},
Expand Down Expand Up @@ -1025,16 +1028,6 @@
}
},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"You try to use a model that was created with version 4.1.0, however, your version is 3.4.1. This might cause unexpected behavior or errors. In that case, try to update to the latest version.\n",
"\n",
"\n",
"\n"
]
},
{
"data": {
"text/plain": [
Expand All @@ -1049,6 +1042,7 @@
"source": [
"private_cache = SemanticCache(\n",
" name=\"private_cache\",\n",
" vectorizer=vectorizer,\n",
" filterable_fields=[{\"name\": \"user_id\", \"type\": \"tag\"}]\n",
")\n",
"\n",
Expand Down Expand Up @@ -1137,16 +1131,6 @@
}
},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"You try to use a model that was created with version 4.1.0, however, your version is 3.4.1. This might cause unexpected behavior or errors. In that case, try to update to the latest version.\n",
"\n",
"\n",
"\n"
]
},
{
"data": {
"text/plain": [
Expand All @@ -1162,6 +1146,7 @@
"\n",
"complex_cache = SemanticCache(\n",
" name='account_data',\n",
" vectorizer=vectorizer,\n",
" filterable_fields=[\n",
" {\"name\": \"user_id\", \"type\": \"tag\"},\n",
" {\"name\": \"account_type\", \"type\": \"tag\"},\n",
Expand Down
10 changes: 5 additions & 5 deletions docs/user_guide/10_embeddings_cache.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@
"source": [
"# Initialize the vectorizer\n",
"vectorizer = HFTextVectorizer(\n",
" model=\"redis/langcache-embed-v1\",\n",
" model=\"redis/langcache-embed-v2\",\n",
" cache_folder=os.getenv(\"SENTENCE_TRANSFORMERS_HOME\")\n",
")"
]
Expand Down Expand Up @@ -146,14 +146,14 @@
"name": "stdout",
"output_type": "stream",
"text": [
"Stored with key: embedcache:909f...\n"
"Stored with key: embedcache:7edf...\n"
]
}
],
"source": [
"# Text to embed\n",
"text = \"What is machine learning?\"\n",
"model_name = \"redis/langcache-embed-v1\"\n",
"model_name = \"redis/langcache-embed-v2\"\n",
"\n",
"# Generate the embedding\n",
"embedding = vectorizer.embed(text)\n",
Expand Down Expand Up @@ -198,7 +198,7 @@
"output_type": "stream",
"text": [
"Found in cache: What is machine learning?\n",
"Model: redis/langcache-embed-v1\n",
"Model: redis/langcache-embed-v2\n",
"Metadata: {'category': 'ai', 'source': 'user_query'}\n",
"Embedding shape: (768,)\n"
]
Expand Down Expand Up @@ -322,7 +322,7 @@
"name": "stdout",
"output_type": "stream",
"text": [
"Stored with key: embedcache:909f...\n",
"Stored with key: embedcache:7edf...\n",
"Exists by key: True\n",
"Retrieved by key: What is machine learning?\n"
]
Expand Down
Loading