v0.1.10-0: Upgrade CacheRoute Serving Baseline to vLLM 0.25.1 and LMCache 0.5.2

[rickisba]

Background

CacheRoute's current environment and integration documentation still describe a vLLM 0.13.x / LMCache 0.3.x serving stack, including the older LMCache remote_url configuration and the older vLLM KV-offloading startup path.

CacheRoute should track the current stable vLLM and LMCache capabilities instead of keeping an old stack as the primary development baseline. This is especially important because the revised v0.2.0 roadmap depends on LMCache MP mode, public connector/plugin contracts, remote-cache serving, observability, cache events, and compatibility profiles that are more complete in current releases.

This Issue establishes a new serving-environment baseline before the remaining v0.1.10 contract Issues are implemented.

Version Decision

Primary target baseline

The target CacheRoute serving stack is:

Component	Target
Python	3.12.x
CUDA	13.0
PyTorch	2.11.0
vLLM	0.25.1
LMCache	0.5.2
torchvision	0.26.0
Transformers	>=5.5.3,<6.0
sentence-transformers	>=5.6,<6.0
huggingface-hub	>=1.5,<2.0
FastAPI	>=0.133,<0.137
Starlette	>=1.0.1
aiohttp	>=3.13.3,<4.0
Pydantic	>=2.12,<3.0
NumPy	>=1.26,<2.3
setuptools	>=77,<81

LMCache 0.5.2 and vLLM 0.25.1 both align their build stack with PyTorch 2.11.0. LMCache 0.5.2 publishes CUDA 13.0 build settings. The exact LMCache 0.5.2 + vLLM 0.25.1 pair is the CacheRoute target and must pass the acceptance suite in this Issue before being documented as a supported CacheRoute baseline.

Officially validated reference / rollback baseline

LMCache's official clean-environment example has directly validated:

• Python 3.12;
• LMCache 0.5.1;
• vLLM 0.25.1;
• LMCache MP server mode;
• vLLM LMCacheMPConnector;
• matching cold and cache-hit output with observed LMCache reads.

This combination is the initial rollback/reference profile while CacheRoute validates LMCache 0.5.2.

Python support policy

The package-level overlap permits Python 3.10 through 3.13, but CacheRoute should use Python 3.12 as the primary reproducible serving and CI lane for this upgrade. Set CacheRoute package metadata to requires-python = ">=3.10,<3.14" unless validation identifies a narrower requirement.

Current Dependency Conflicts

The current CacheRoute requirements.txt cannot coexist with the target serving stack without adjustment:

• sentence-transformers~=5.1.2 requires Transformers <5.0, while vLLM 0.25.1 requires Transformers >=5.5.3 and LMCache 0.5.2 requires Transformers >=5.4;
• transformers~=4.57.3 is below both current serving requirements;
• huggingface-hub~=0.36.0 is below LMCache's >=1.5.0 requirement;
• fastapi~=0.124.0 is below vLLM's >=0.133,<0.137 range;
• starlette~=0.50.0 is below vLLM's >=1.0.1 requirement;
• aiohttp~=3.13.2 is below vLLM's >=3.13.3 requirement.

The current NumPy 1.26.4 and setuptools 78.1.x are within the target constraints and do not need to be upgraded merely for this baseline.

Dependency Management Strategy

• Keep PyTorch, vLLM, and LMCache out of the generic application requirements.txt; installing CacheRoute application dependencies must not overwrite the CUDA/ABI-compatible serving stack.
• Add an exact serving-stack constraints file, for example:
  • env/constraints/vllm-0.25.1-lmcache-0.5.2-cu130.txt.
• The serving constraints must pin at least PyTorch, torchvision, torchaudio, vLLM, LMCache, and binary-sensitive CUDA packages required by vLLM.
• Update the application dependency set so it cannot downgrade packages required by the serving stack:
  • upgrade sentence-transformers to a Transformers-5-compatible release;
  • align Transformers, Hugging Face Hub, FastAPI, Starlette, aiohttp, and Pydantic ranges;
  • retain narrower CacheRoute pins only when they remain inside both vLLM and LMCache constraints.
• Align pyproject.toml with requirements.txt; the lightweight package install surface must not declare conflicting ranges.
• Use a clean resolver environment and run both pip check and a second resolver path such as uv pip to detect hidden conflicts.
• Record the complete resolved package set used by the validated image.

Runtime Migration Scope

• Replace the current vLLM 0.13.x / LMCache 0.3.x environment documentation as the primary supported baseline.
• Update source-build and container instructions for Python 3.12, PyTorch 2.11.0, CUDA 13.0, vLLM 0.25.1, and LMCache 0.5.2.
• Replace old LMCache remote_url and vLLM --kv-offloading-backend lmcache examples with the current LMCache MP server and vLLM LMCacheMPConnector flow.
• Update doc/integrations/lmcache.md, env/README.md, root documentation, environment sanity checks, and image/tag examples.
• Ensure Instance capability reporting includes the exact vLLM, LMCache, PyTorch, Python, CUDA, connector, and integration-profile versions.
• Add startup validation that rejects known-incompatible combinations with a structured message rather than failing later during cache reuse.
• Use LMCache and vLLM public interfaces; do not make CacheRoute depend on private classes or one source-tree layout.

Deliverables

1. A dependency conflict and compatibility report.
2. An exact CUDA 13 serving-stack constraints/lock file.
3. Updated requirements.txt and pyproject.toml with compatible ranges.
4. Updated Docker/source-build/environment documentation.
5. Updated LMCache MP and vLLM connector configuration examples.
6. Runtime version/capability validation and debug output.
7. CPU-only dependency and startup contract tests.
8. A GPU end-to-end cache reuse smoke test.
9. An updated compatibility matrix recording target, validated, rollback, and unsupported combinations.

Acceptance Criteria

Dependency resolution

• A fresh Python 3.12 environment resolves the target stack without manual package replacement.
• python3 -m pip check succeeds.
• Installing CacheRoute's generic requirements after the serving stack does not downgrade or replace PyTorch, vLLM, LMCache, Transformers, FastAPI, Starlette, or aiohttp with incompatible versions.
• requirements.txt, pyproject.toml, the serving constraints file, and documentation describe consistent ranges.
• Runtime diagnostics print the exact Python, CUDA, PyTorch, vLLM, LMCache, Transformers, connector, and compatibility-profile versions.

Current-stack integration

• LMCache starts in MP server mode.
• vLLM starts with LMCacheMPConnector using public configuration.
• A cache-isolated request reports no LMCache cache read.
• A warm/cache-hit request reports one or more LMCache reads.
• Cold and cache-hit deterministic outputs match.
• Cache identity remains stable only when model revision, tokenizer, tensor parallelism, KV dtype/layout, block/chunk size, and relevant profiles match.

CacheRoute regression

• Scheduler, KDN, Proxy, and Instance start with the target environment.
• Instance registration exposes the exact target runtime versions through the existing capability contract.
• Text-only and explicit fallback requests remain functional.
• Legacy Redis behavior remains available only as a documented compatibility path.
• Generic pytest collection performs no external request at module-import time.
• CPU-only tests do not require a GPU, live vLLM endpoint, LMCache daemon, or Redis service.

Documentation and support status

• vLLM 0.13.x / LMCache 0.3.x is no longer presented as the current primary baseline.
• The target pair vLLM 0.25.1 + LMCache 0.5.2 is marked supported only after the complete acceptance suite passes.
• The reference pair vLLM 0.25.1 + LMCache 0.5.1 is documented as the initial known-good rollback profile.
• Known unsupported combinations and limitations are explicit.

Non-Goals

• Tracking nightly or unreleased main branches.
• Supporting every CUDA/PyTorch build in this Issue.
• Implementing the KDN Remote Cache Serving Plane or a new storage Provider.
• Changing routing, placement, queue, or maintenance policy.
• Claiming performance improvements before separate benchmarks are run.

Relationships

• Parent roadmap Epic: v0.1.10 Epic: KDN Contracts, LMCache Compatibility, and Observability Baseline #137
• Completed capability foundation: v0.1.10-1: Add Instance Capability Fingerprints and Compatibility-Aware Registration #138
• This Issue should be completed before implementing v0.1.10-2: Define Storage-Neutral KDN, Cache Observation, Serving Task, and Queue State Models #139, v0.1.10-3: Define Versioned KDN Server Contracts and LMCache Compatibility Profiles #140, v0.1.10-4: Add Unified KDN, LMCache, Provider, and Queue-Stage Observability #141, and v0.1.10-5: Add Cross-Profile Regression and Backward-Compatibility Validation #142 against the new runtime baseline.