[Misc] Warn When vLLM / vLLM-Omni Have Mismatched Versions

[alex-jw-brooks]

Purpose

Mismatched vLLM Omni / vLLM versions are a very common source of errors for users. This PR adds a warning if the major / minor version for vLLM Omni & vLLM aren't the fallback for _version not being created (0.0) and are mismatched. This runs on import of the version module, which is now done before running monkeypatching on vLLM, because the imports in monkey patch will frequently break with incompatible versions.

Example (with my current omni build and vLLM 0.18 instead of 0.19), where it will warn before crashing due to patch issues:

>>> import vllm_omni

/home/alex-jw-brooks/vllm-omni/vllm_omni/version.py:55: RuntimeWarning: vLLM and vLLM-Omni appear to have mismatched major/minor versions:
 --> vLLM-Omni version 0.19.0rc2.dev21+gb30172916.d20260406
 --> vLLM version 0.18.0
This will likely cause compatibility issues.
  warn_if_misaligned_vllm_version()

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/alex-jw-brooks/vllm-omni/vllm_omni/__init__.py", line 22, in <module>
    from . import patch  # noqa: F401
    ^^^^^^^^^^^^^^^^^^^
  File "/home/alex-jw-brooks/vllm-omni/vllm_omni/patch.py", line 16, in <module>
    from vllm_omni.inputs.data import OmniTokensPrompt
  File "/home/alex-jw-brooks/vllm-omni/vllm_omni/inputs/data.py", line 19, in <module>
    from vllm.inputs import EmbedsPrompt, TextPrompt, TokensInput, TokensPrompt
ImportError: cannot import name 'TokensInput' from 'vllm.inputs' (/home/alex-jw-brooks/vllm-omni/.venv/lib/python3.12/site-packages/vllm/inputs/__init__.py). Did you mean: 'TokenInputs'?

This is a joint contribution with @lengrongfu

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[hsliuustc0106]

Nice utility. Two things:

1. No test for the warning logic — consider adding a quick unit test with mocked vllm.__version__ covering the three cases (match, mismatch, dev/0.0). Low effort, high value for a safety check that runs on every import.

2. The import order change in __init__.py (version before patch) — the comment explains why, but have you verified this doesn't break any existing import path where version.py might depend on monkeypatched vLLM? Looks safe from the diff since version.py only imports vllm.__version__, but worth confirming on a clean install.

[hsliuustc0106]

Clean utility. One suggestion: consider adding a test that verifies the warning fires when versions mismatch (mock __version_tuple__ to return different major.minor). Currently no test coverage for the core warn_if_misaligned_vllm_version logic.

[alex-jw-brooks]

Thank you for the reviews @lishunyang12 @hsliuustc0106 🙂

Added some small tests for when the warnings will fire. Also yes, moving the version check should be fine since the versioning of vllm omni / vllm are independent and shouldn't depend on any monkey patching.

For testing against a new install, you can do something like this as a quick check.

uv pip install vllm==0.18.0
uv pip install -e .
python3 -c "import vllm_omni"

/home/alex-jw-brooks/vllm-omni/vllm_omni/version.py:55: RuntimeWarning: vLLM and vLLM-Omni appear to have mismatched major/minor versions:
 --> vLLM-Omni version 0.19.0rc2.dev90+gecf2b451e
 --> vLLM version 0.18.0
This will likely cause compatibility issues.

[lengrongfu]

maybe we can look this pr #1941

[alex-jw-brooks]

Hi @hsliuustc0106, @lengrongfu and I chatted and have decided to move forward with this PR. We have added some of the additional tests from the other PR that were not covered explicitly in this one, and went ahead and squashed it to a coauthored commit. It's ready for another look when you have time, thanks 🙂

[hsliuustc0106]

Hi @hsliuustc0106, @lengrongfu and I chatted and have decided to move forward with this PR. We have added some of the additional tests from the other PR that were not covered explicitly in this one, and went ahead and squashed it to a coauthored commit. It's ready for another look when you have time, thanks 🙂

lgtm, I also met this problem before, thanks anyway