diff --git a/.github/scripts/prefetch_notebook_models.py b/.github/scripts/prefetch_notebook_models.py new file mode 100644 index 00000000..cde476a5 --- /dev/null +++ b/.github/scripts/prefetch_notebook_models.py @@ -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() diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index a24b1472..1637f309 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -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: @@ -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. @@ -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 @@ -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 @@ -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 diff --git a/docs/user_guide/03_llmcache.ipynb b/docs/user_guide/03_llmcache.ipynb index fc6183b6..3c9d145a 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", ")" ] }, @@ -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": [ @@ -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", @@ -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": [ @@ -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", diff --git a/docs/user_guide/10_embeddings_cache.ipynb b/docs/user_guide/10_embeddings_cache.ipynb index ddf9b9e1..e85e22b1 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" ]