[vLLM IR] Deprecate ir_op_priority ahead of vLLM IR removal (#63371)

Signed-off-by: Woosuk Kwon <woosuk@inferact.ai>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

docs/design/vllm_ir.md

@@ -1,5 +1,10 @@
 # vLLM IR: Functional Intermediate Representation
 
+!!! warning "Deprecated"
+    vLLM IR is deprecated and is being removed. `--ir-op-priority`
+    (`KernelConfig.ir_op_priority`) still works but logs a warning, and it will be
+    removed in v0.34.0. Do not port new ops to vLLM IR.
+
 ## Motivation
 
 vLLM IR is a **functional intermediate representation (IR)** that fills the gap between

tests/engine/test_arg_utils.py

@@ -4,6 +4,7 @@
 import json
 from argparse import ArgumentError
 from contextlib import AbstractContextManager, nullcontext
+from dataclasses import replace
 from typing import Annotated, Literal
 
 import pytest
@@ -821,6 +822,27 @@ def test_ir_op_priority():
         ).create_engine_config()
 
 
+def test_ir_op_priority_deprecation_warning(caplog_vllm, disable_log_dedup):
+    """Setting ir_op_priority warns users because vLLM IR is being removed."""
+    from vllm.config.kernel import IrOpPriorityConfig, KernelConfig
+
+    msg = "ir_op_priority (--ir-op-priority) is deprecated"
+
+    # Platform defaults fill ir_op_priority; copying the config must not warn.
+    cfg = EngineArgs().create_engine_config()
+    replace(cfg.kernel_config, moe_backend="triton")
+    assert msg not in caplog_vllm.text
+
+    ir_op_priority = IrOpPriorityConfig(rms_norm=["vllm_c"])
+    EngineArgs(ir_op_priority=ir_op_priority).create_engine_config()
+    assert msg in caplog_vllm.text
+
+    caplog_vllm.clear()
+    kernel_config = KernelConfig(ir_op_priority=ir_op_priority)
+    EngineArgs(kernel_config=kernel_config).create_engine_config()
+    assert msg in caplog_vllm.text
+
+
 @pytest.mark.parametrize(
     ("input_json", "expected_json"),
     [

vllm/config/kernel.py

@@ -275,6 +275,9 @@ class KernelConfig:
     """
     vLLM IR op priority for dispatching/lowering during the forward pass.
     Platform defaults appended automatically during VllmConfig.__post_init__.
+
+    Deprecated: vLLM IR is being removed, and this option will be removed in
+    v0.34.0. Kernels will be selected by the platform, as for other custom ops.
     """
 
     enable_flashinfer_autotune: bool = None  # type: ignore[assignment]

vllm/engine/arg_utils.py

@@ -465,6 +465,12 @@ _MAMBA_CACHE_MODE_DEPRECATION_MESSAGE = (
 )
 
 
+_IR_OP_PRIORITY_DEPRECATION_MESSAGE = (
+    "ir_op_priority (--ir-op-priority) is deprecated because vLLM IR is being "
+    "removed. It will be removed in v0.34.0."
+)
+
+
 _DISABLE_CASCADE_ATTN_DEPRECATION_MESSAGE = (
     "--disable-cascade-attn is deprecated and has no effect since cascade "
     "attention has been removed. It will be removed in v0.33.0."
@@ -2813,6 +2819,8 @@ class EngineArgs:
 
             # Set the attribute
             setattr(kernel_config.ir_op_priority, op_name, op_priority)
+        if any(asdict(kernel_config.ir_op_priority).values()):
+            logger.warning_once(_IR_OP_PRIORITY_DEPRECATION_MESSAGE)
 
         load_config = self.create_load_config()