pin LMCache to v0.3.9 or greater with vLLM v0.15.0

[Gregory-Pereira]

BugFix: Pin LMCache to v0.3.9 for API compatibility

Relevant links: llm-d/llm-d#663

Summary

This PR constrains the supported LMCache version for vLLM v0.15.0 to >= 0.3.9.

While LMCache 0.3.8 can import successfully, it is not fully compatible with the vLLM v0.15.0 LMCache connector API and leads to runtime issues when exercising the KV transfer path. Versions >= 0.3.9 include the necessary connector changes and work correctly with the v0.15.0 API.

Motivation

We ran into LMCache compatibility issues while upgrading to vLLM v0.15.0, specifically around the v1 LMCache KV connector (vllm.distributed.kv_transfer.kv_connector.v1.lmcache_connector).

LMCache’s public docs currently don’t reflect an accurate version compatibility matrix with recent vLLM releases, so it wasn’t clear which LMCache version should be used. In practice, installing LMCache without a constraint makes it easy to end up on a version that imports but does not actually work at runtime.

This PR encodes the minimum known-good LMCache version directly in vLLM to avoid that footgun.

What was tested

All testing was done inside the official vllm-openai/vllm:v0.15.0 container, using the in-image vLLM wheel (no local rebuilds).
The helper script I used to test this works by installing each LMCache version in the official vLLM image and confirming whether the LMCache v1 connector import succeeds, allowing us to identify the minimum compatible release.

Test Results:

=== Testing lmcache versions against vLLM in-image ===

--- lmcache==0.3.8 ---
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager, possibly rendering your system unusable. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv. Use the --root-user-action option if you know what you are doing and want to suppress this warning.
lmcache dist version: 0.3.8
lmcache import path: /usr/local/lib/python3.12/dist-packages/lmcache/__init__.py
FAIL: lmcache==0.3.8
---- LMCache adapter import error ----
W0130 09:54:31.725000 908 torch/utils/cpp_extension.py:117] No CUDA runtime is found, using CUDA_HOME='/usr/local/cuda'
Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "/usr/local/lib/python3.12/dist-packages/lmcache/integration/vllm/vllm_v1_adapter.py", line 21, in <module>
    from vllm.utils import cdiv
ImportError: cannot import name 'cdiv' from 'vllm.utils' (/usr/local/lib/python3.12/dist-packages/vllm/utils/__init__.py)
--------------------------------------

--- lmcache==0.3.9 ---
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager, possibly rendering your system unusable. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv. Use the --root-user-action option if you know what you are doing and want to suppress this warning.
lmcache dist version: 0.3.9
lmcache import path: /usr/local/lib/python3.12/dist-packages/lmcache/__init__.py
PASS: lmcache==0.3.9

--- lmcache==0.3.10 ---
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager, possibly rendering your system unusable. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv. Use the --root-user-action option if you know what you are doing and want to suppress this warning.
lmcache dist version: 0.3.10
lmcache import path: /usr/local/lib/python3.12/dist-packages/lmcache/__init__.py
PASS: lmcache==0.3.10

--- lmcache==0.3.11 ---
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager, possibly rendering your system unusable. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv. Use the --root-user-action option if you know what you are doing and want to suppress this warning.
lmcache dist version: 0.3.11
lmcache import path: /usr/local/lib/python3.12/dist-packages/lmcache/__init__.py
PASS: lmcache==0.3.11

--- lmcache==0.3.12 ---
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager, possibly rendering your system unusable. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv. Use the --root-user-action option if you know what you are doing and want to suppress this warning.
lmcache dist version: 0.3.12
lmcache import path: /usr/local/lib/python3.12/dist-packages/lmcache/__init__.py
PASS: lmcache==0.3.12

--- lmcache==0.3.13 ---
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager, possibly rendering your system unusable. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv. Use the --root-user-action option if you know what you are doing and want to suppress this warning.
lmcache dist version: 0.3.13
lmcache import path: /usr/local/lib/python3.12/dist-packages/lmcache/__init__.py
PASS: lmcache==0.3.13

=== Summary ===
VERSION    RESULT
-------    ------
0.3.8      FAIL(vllm_connector=1,adapter=0)
0.3.9      PASS
0.3.10     PASS
0.3.11     PASS
0.3.12     PASS
0.3.13     PASS

cc @wseaton @tlrmchlsmth @NickLucche

[github-actions]

👋 Hi! Thank you for contributing to the vLLM project.

💬 Join our developer Slack at https://slack.vllm.ai to discuss your PR in #pr-reviews, coordinate on features in #feat- channels, or join special interest groups in #sig- channels.

Just a reminder: PRs would not trigger full CI run by default. Instead, it would only run fastcheck CI which starts running only a small and essential subset of CI tests to quickly catch errors.

You ask your reviewers to trigger select CI tests on top of fastcheck CI.

Once the PR is approved and ready to go, your PR reviewer(s) can run CI to test the changes comprehensively before merging.

To run CI, PR reviewers can either: Add ready label to the PR or enable auto-merge.

If you have any questions, please reach out to us on Slack at https://slack.vllm.ai.

🚀

[gemini-code-assist]

Code Review

This pull request correctly pins the lmcache dependency to version 0.3.9 or greater to resolve an API incompatibility. My review includes a suggestion to add an upper bound to the version constraint to prevent similar issues with future lmcache releases.

[gemini-code-assist]

To prevent potential future breakages, it's safer to constrain the upper bound of the lmcache version. A new major release of lmcache (e.g., 0.4.0) could introduce backward-incompatible API changes, similar to the issue this PR is fixing. I suggest pinning the version to the current minor release series to improve dependency stability.

lmcache >= 0.3.9, < 0.4.0