[Misc] Warn When vLLM / vLLM-Omni Have Mismatched Versions (#2691)

Signed-off-by: Alex Brooks <albrooks@redhat.com>
Co-authored-by: lengrongfu <lenronfu@gmail.com>

tests/test_version.py

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+"""Unit tests for version compatibility warnings."""
+
+import warnings
+from unittest import mock
+
+import pytest
+
+from vllm_omni.version import warn_if_misaligned_vllm_version
+
+
+@mock.patch("vllm_omni.version.__version_tuple__", (0, 19, 0))
+@mock.patch("vllm_omni.version.__version__", "0.19.0")
+@mock.patch("vllm.__version_tuple__", (0, 18, 0))
+@mock.patch("vllm.__version__", "0.18.0")
+def test_version_mismatch_warning():
+    """Ensure that we warn when vLLM and vLLM-Omni major/minor versions differ."""
+    with pytest.warns(RuntimeWarning, match="mismatched major/minor versions"):
+        warn_if_misaligned_vllm_version()
+
+
+@pytest.mark.parametrize(
+    "vllm_ver,vllm_tuple,omni_ver,omni_tuple",
+    [
+        ("0.19.0", (0, 19, 0), "0.19.5", (0, 19, 5)),  # Patch differs
+        ("0.18.0", (0, 18, 0), "dev", (0, 0, "dev")),  # Omni dev
+        ("dev", (0, 0, "dev"), "0.19.0", (0, 19, 0)),  # vLLM dev
+        # Ensure local identifies don't matter for the warning
+        ("0.19.0+foo", (0, 19, 0, "foo"), "0.19.5", (0, 19, 0)),
+        ("0.19.0", (0, 19, 0), "0.19.5+bar", (0, 19, 0, "bar")),
+        ("0.19.0+foo", (0, 19, 0, "foo"), "0.19.5+bar", (0, 19, 0, "bar")),
+    ],
+)
+def test_no_warning_cases(vllm_ver, vllm_tuple, omni_ver, omni_tuple):
+    """Ensure we don't warn when minor versions match or either is a dev build."""
+    with (
+        mock.patch.multiple("vllm", __version__=vllm_ver, __version_tuple__=vllm_tuple),
+        mock.patch.multiple("vllm_omni.version", __version__=omni_ver, __version_tuple__=omni_tuple),
+    ):
+        with warnings.catch_warnings():
+            warnings.simplefilter("error")
+            warn_if_misaligned_vllm_version()
+
+
+@mock.patch("vllm_omni.version.__version_tuple__", (0, 19, 0))
+@mock.patch("vllm_omni.version.__version__", "0.19.0rc2.dev21")
+@mock.patch("vllm.__version_tuple__", (0, 18, 0))
+@mock.patch("vllm.__version__", "0.18.0")
+def test_warning_contains_version_strings():
+    """Ensure that the warning contains the full version strings."""
+    with pytest.warns(RuntimeWarning) as record:
+        warn_if_misaligned_vllm_version()
+
+    assert len(record) == 1
+    msg = str(record[0].message)
+    assert "0.19.0rc2.dev21" in msg
+    assert "0.18.0" in msg

vllm_omni/__init__.py

@@ -12,6 +12,12 @@ Architecture:
   processing
 """
 
+# We import version early, because it will warn if vLLM / vLLM Omni
+# are not using the same major + minor version (if vLLM is installed).
+# We should do this before applying patch, because vLLM imports might
+# throw in patch if the versions differ.
+from .version import __version__, __version_tuple__  # isort:skip # noqa: F401
+
 try:
     from . import patch  # noqa: F401
 except ModuleNotFoundError as exc:  # pragma: no cover - optional dependency
@@ -25,8 +31,6 @@ from vllm_omni.transformers_utils import configs as _configs  # noqa: F401, E402
 
 from .config import OmniModelConfig
 
-from .version import __version__, __version_tuple__  # isort:skip
-
 
 def __getattr__(name: str):
     # Lazy import for AsyncOmni and Omni to avoid pulling in heavy

vllm_omni/version.py

@@ -5,12 +5,12 @@ The version is automatically generated from git tags via setuptools_scm
 and written to _version.py during package build.
 """
 
+import warnings
+
 try:
     # Import auto-generated version from _version.py (created by setuptools_scm)
     from ._version import __version__, __version_tuple__
 except ImportError as e:
-    import warnings
-
     warnings.warn(
         f"Failed to import version from _version.py: {e}\n"
         "This typically happens in development mode before building.\n"
@@ -22,4 +22,37 @@ except ImportError as e:
     __version__ = "dev"
     __version_tuple__ = (0, 0, "dev")
 
+
+def warn_if_misaligned_vllm_version():
+    """Warn if vLLM and vllm-omni versions don't match (major.minor)."""
+    # Import vllm lazily since import order may be sensitive with current monkeypatching,
+    # but we want to check this before potentially breaking imports run.
+    from vllm import __version__ as vllm_version
+    from vllm import __version_tuple__ as vllm_version_tuple
+
+    omni_ver: tuple[str | int, ...] = __version_tuple__[:2]
+    vllm_ver: tuple[str | int, ...] = vllm_version_tuple[:2]
+    # Skip if either version is dev (0, 0)
+    if omni_ver == (0, 0) or vllm_ver == (0, 0):
+        return
+
+    # Compare major.minor
+    if omni_ver != vllm_ver:
+        warnings.warn(
+            "vLLM and vLLM-Omni appear to have mismatched major/minor versions:\n"
+            f" --> vLLM-Omni version {__version__}\n"
+            f" --> vLLM version {vllm_version}\n"
+            "This will likely cause compatibility issues.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+
+
 __all__ = ["__version__", "__version_tuple__"]
+
+# Run version check automatically when this module is imported
+try:
+    warn_if_misaligned_vllm_version()
+except ModuleNotFoundError:
+    # vLLM not installed (e.g., documentation builds)
+    pass