From 961cd38afba591902bb014b0dc6f702a6ddccb4f Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Wed, 4 Nov 2026 14:42:53 +0100 Subject: [PATCH 1/4] ci: prefetch notebook HF models into their own cache The notebook job shared the fixed `Linux-hf-cache` key with the test jobs. Whichever test job misses first saves that entry, so it holds only the models the tests load, and actions/cache never re-saves after an exact hit. redis/langcache-embed-v2 and BAAI/bge-reranker-base are loaded only by notebooks, so they were downloaded inside nbval cells on every run; PR run 41813891110 timed out at 60s in huggingface_hub's xet_get right after an exact cache hit. The notebook job now restores a cache keyed on the hash of .github/scripts/prefetch_notebook_models.py, downloads the listed models before nbval, and saves straight after that step, so a failing notebook cannot stop the save. nbval runs with HF_HUB_OFFLINE=1, so a notebook that loads an unlisted model fails at once instead of downloading against the cell timeout. The `needs: service-tests` ordering existed only to wait for the shared cache, so it is dropped. --- .github/scripts/prefetch_notebook_models.py | 40 +++++++++++++++++++++ .github/workflows/test.yml | 38 ++++++++++++++++---- 2 files changed, 71 insertions(+), 7 deletions(-) create mode 100644 .github/scripts/prefetch_notebook_models.py diff --git a/.github/scripts/prefetch_notebook_models.py b/.github/scripts/prefetch_notebook_models.py new file mode 100644 index 000000000..5681628de --- /dev/null +++ b/.github/scripts/prefetch_notebook_models.py @@ -0,0 +1,40 @@ +"""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-v1", # SemanticCache default + "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() diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index c95f7a7e7..49892541b 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -145,22 +145,28 @@ jobs: notebooks: name: Notebook Validation runs-on: ubuntu-latest - # Ordered after the HF cache is primed, 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. - if: ${{ !cancelled() && (github.event_name != 'pull_request' || (github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]')) }} + if: github.event_name != 'pull_request' || (github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]') env: HF_HOME: ${{ github.workspace }}/hf_cache steps: - name: Check out repository uses: actions/checkout@v6 - - name: Cache HuggingFace Models - uses: actions/cache@v4 + # Separate from the `Linux-hf-cache` entry the test jobs share. That one + # is saved by whichever test job misses first and holds only the models + # the tests load, and actions/cache never re-saves after an exact hit, so + # models only the notebooks use were downloaded inside nbval cells on + # every run. This key changes whenever the model list does. + - name: Restore HuggingFace models + id: hf-cache + uses: actions/cache/restore@v4 with: path: hf_cache - key: ${{ runner.os }}-hf-cache + key: ${{ runner.os }}-hf-notebooks-${{ hashFiles('.github/scripts/prefetch_notebook_models.py') }} + restore-keys: | + ${{ runner.os }}-hf-notebooks- - name: Install Python uses: actions/setup-python@v5 @@ -181,6 +187,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@v4 + with: + path: hf_cache + key: ${{ steps.hf-cache.outputs.cache-primary-key }} + - name: Start Redis run: | set -euo pipefail @@ -228,7 +249,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 From 877094df49c45c443afd4b0b1157704cadc038cd Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Wed, 4 Nov 2026 16:04:19 +0100 Subject: [PATCH 2/4] docs: use langcache-embed-v2 throughout the user guide 03_llmcache loaded v2 for its first cache but fell back to the SemanticCache default, v1, for the private and multi-field caches, and 10_embeddings_cache named v1 explicitly. The notebook job therefore downloaded and cached two 572 MB models where one does. 03 now builds one v2 vectorizer and passes it to all three caches, and 10 uses v2. The prefetch list drops v1. Outputs that depend on the model were refreshed by re-running those cells; the filtered check() results in 03 are unchanged under v2. The library default stays v1. --- .github/scripts/prefetch_notebook_models.py | 1 - docs/user_guide/03_llmcache.ipynb | 33 ++++++--------------- docs/user_guide/10_embeddings_cache.ipynb | 10 +++---- 3 files changed, 14 insertions(+), 30 deletions(-) diff --git a/.github/scripts/prefetch_notebook_models.py b/.github/scripts/prefetch_notebook_models.py index 5681628de..cde476a59 100644 --- a/.github/scripts/prefetch_notebook_models.py +++ b/.github/scripts/prefetch_notebook_models.py @@ -13,7 +13,6 @@ from redisvl.utils.vectorize import HFTextVectorizer EMBEDDING_MODELS = [ - "redis/langcache-embed-v1", # SemanticCache default "redis/langcache-embed-v2", "sentence-transformers/all-mpnet-base-v2", # HFTextVectorizer default ] diff --git a/docs/user_guide/03_llmcache.ipynb b/docs/user_guide/03_llmcache.ipynb index ab431aad5..11f027625 100644 --- a/docs/user_guide/03_llmcache.ipynb +++ b/docs/user_guide/03_llmcache.ipynb @@ -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", ")" ] }, @@ -1020,16 +1023,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": [ @@ -1044,6 +1037,7 @@ "source": [ "private_cache = SemanticCache(\n", " name=\"private_cache\",\n", + " vectorizer=vectorizer,\n", " filterable_fields=[{\"name\": \"user_id\", \"type\": \"tag\"}]\n", ")\n", "\n", @@ -1132,16 +1126,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": [ @@ -1157,6 +1141,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", diff --git a/docs/user_guide/10_embeddings_cache.ipynb b/docs/user_guide/10_embeddings_cache.ipynb index ddf9b9e1a..e85e22b1e 100644 --- a/docs/user_guide/10_embeddings_cache.ipynb +++ b/docs/user_guide/10_embeddings_cache.ipynb @@ -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", ")" ] @@ -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", @@ -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" ] @@ -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" ] From b52a76d46db803f2e4833146a8e670598a3651c3 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Mon, 9 Nov 2026 17:13:12 +0100 Subject: [PATCH 3/4] ci: keep notebooks ordered after service-tests; use cache@v5 Dropping `needs: service-tests` was wrong: besides the shared HF cache, it orders the notebook job after the job that saves the Python 3.11 uv cache, which the notebook job restores. Restore it with the same `!cancelled()` guard the test matrix uses. Move the notebook HF restore and save steps to actions/cache@v5, the version the service-tests action already uses. --- .github/workflows/test.yml | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 49892541b..43e10ddcb 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -145,23 +145,26 @@ jobs: notebooks: name: Notebook Validation runs-on: ubuntu-latest + # 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. - if: github.event_name != 'pull_request' || (github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]') + if: ${{ !cancelled() && (github.event_name != 'pull_request' || (github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]')) }} env: HF_HOME: ${{ github.workspace }}/hf_cache steps: - name: Check out repository uses: actions/checkout@v6 - # Separate from the `Linux-hf-cache` entry the test jobs share. That one - # is saved by whichever test job misses first and holds only the models - # the tests load, and actions/cache never re-saves after an exact hit, so + # Separate from the HF cache the test jobs share, which holds only the + # models the tests load and is never re-saved after an exact hit, so # models only the notebooks use were downloaded inside nbval cells on - # every run. This key changes whenever the model list does. + # every run. This job is the only one that saves this key, and the key + # changes whenever the model list does. - name: Restore HuggingFace models id: hf-cache - uses: actions/cache/restore@v4 + uses: actions/cache/restore@v5 with: path: hf_cache key: ${{ runner.os }}-hf-notebooks-${{ hashFiles('.github/scripts/prefetch_notebook_models.py') }} @@ -197,7 +200,7 @@ jobs: # not stop the models from being cached. - name: Save HuggingFace models if: steps.hf-cache.outputs.cache-hit != 'true' - uses: actions/cache/save@v4 + uses: actions/cache/save@v5 with: path: hf_cache key: ${{ steps.hf-cache.outputs.cache-primary-key }} From 9439e87ab617cb5f5dd02c9f39686f4a76732fa6 Mon Sep 17 00:00:00 2001 From: Vishal Bala Date: Mon, 9 Nov 2026 17:29:50 +0100 Subject: [PATCH 4/4] ci: drop the notebook HF cache's restore-keys fallback A prefix restore brought back the previous entry whole, so a model removed from prefetch_notebook_models.py stayed in every later entry. A notebook still loading it would pass nbval offline until the chain of entries was evicted, which hid exactly the drift HF_HUB_OFFLINE=1 is there to catch. A model-list change now costs one cold download in the prefetch step, outside nbval's per-cell timeout. --- .github/workflows/test.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 248e1fb48..bd206ca6a 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -213,15 +213,15 @@ jobs: # 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. + # 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-notebooks-${{ hashFiles('.github/scripts/prefetch_notebook_models.py') }} - restore-keys: | - ${{ runner.os }}-hf-notebooks- - name: Install Python uses: actions/setup-python@v6