[Router][Feat] Add semantic cache to the vLLM router

[rootfs]

[Router][Feat] Add semantic cache to the vLLM router

This PR adds a semantic caching feature to the vLLM router, allowing it to cache LLM responses based on the semantic similarity of requests. When a new request comes in, the cache checks if there's a semantically similar request already in the cache. If a match is found, the cached response is returned instead of routing the request to a backend LLM service.

The semantic cache is implemented as an experimental feature under a feature gate, so it's disabled by default and must be explicitly enabled.

Features:

• Semantic similarity matching using sentence transformers
• Configurable similarity threshold (global and per-request)
• Vector database storage using FAISS
• Prometheus metrics for cache performance monitoring
• Persistent storage of cache entries
• Feature gate control for enabling/disabling

Usage:

To enable the semantic cache:

python -m vllm_router.router --feature-gates=SemanticCache=true --semantic-cache-model=all-MiniLM-L6-v2 --semantic-cache-dir=/path/to/cache --semantic-cache-threshold=0.95

Clients can control caching behavior with these parameters:

• skip_cache: Set to true to bypass the cache for a specific request

• cache_similarity_threshold: Override the default similarity threshold for a specific request

• Make sure the code changes pass the pre-commit checks.

• Sign-off your commit by using -s when doing git commit

• Try to classify PRs for easy understanding of the type of changes, such as [Bugfix], [Feat], and [CI].

Detailed Checklist (Click to Expand)

Thank you for your contribution to production-stack! Before submitting the pull request, please ensure the PR meets the following criteria. This helps us maintain the code quality and improve the efficiency of the review process.

PR Title and Classification

Please try to classify PRs for easy understanding of the type of changes. The PR title is prefixed appropriately to indicate the type of change. Please use one of the following:

• [Bugfix] for bug fixes.
• [CI/Build] for build or continuous integration improvements.
• [Doc] for documentation fixes and improvements.
• [Feat] for new features in the cluster (e.g., autoscaling, disaggregated prefill, etc.).
• [Router] for changes to the vllm_router (e.g., routing algorithm, router observability, etc.).
• [Misc] for PRs that do not fit the above categories. Please use this sparingly.

Note: If the PR spans more than one category, please include all relevant prefixes.

Code Quality

The PR need to meet the following code quality standards:

• Pass all linter checks. Please use pre-commit to format your code. See README.md for installation.
• The code need to be well-documented to ensure future contributors can easily understand the code.
• Please include sufficient tests to ensure the change is stay correct and robust. This includes both unit tests and integration tests.

DCO and Signed-off-by

When contributing changes to this project, you must agree to the DCO. Commits must include a Signed-off-by: header which certifies agreement with the terms of the DCO.

Using -s with git commit will automatically add this header.

What to Expect for the Reviews

We aim to address all PRs in a timely manner. If no one reviews your PR within 5 days, please @-mention one of YuhanLiu11
, Shaoting-Feng or ApostaC.

[rootfs]

The demo is here. In this demo, the backend is ollama running phi4 model. In the console, the top pane is vllm_router, the bottom pane is the test program (included in this PR). One the first run, the test time used 15s, the 2nd run took less than 1s.

@YuhanLiu11 @Hanchenli @ApostaC PTAL, thanks

[rootfs]

Please refer to the complete file here

production-stack/src/vllm_router/router.py

Line 307 in b9b4134

@app.post("/v1/batches")

.

These functions are not deleted, the diff is very weird.

[rootfs]

@YuhanLiu11 fixed the pre-commit issue, can you run the CI again? Thanks

[YuhanLiu11]

@YuhanLiu11 fixed the pre-commit issue, can you run the CI again? Thanks

Thanks! Rerunning it now

[ApostaC]

@rootfs Thanks for your contribution! In order to avoid conflicts with #207 , let's get the modifications router.py in next PR?

[rootfs]

@rootfs Thanks for your contribution! In order to avoid conflicts with #207 , let's get the modifications router.py in next PR?

understood, let me revert the router change

[rootfs]

@YuhanLiu11 @ApostaC router.py changes reverted in this PR. The complete change can be found in another branch

[ApostaC]

LGTM! Thanks for the contribution!