[torch.compile] refactor config hashing to compile_factors and unify factor collection

tests/compile/fullgraph/test_toy_llama.py

@@ -45,7 +45,7 @@ class LlamaConfig:
     tractable_init: bool = False
     random_seed: int = 0
 
-    def compute_hash(self) -> str:
+    def compile_factors(self) -> str:
         factors: list[Any] = []
         for k, v in self.__dict__.items():
             if k == "random_seed":

tests/config/test_config_utils.py

@@ -6,7 +6,7 @@
 
 import pytest
 
-from vllm.config.utils import get_hash_factors, hash_factors, normalize_value
+from vllm.config.utils import get_compile_factors, hash_factors, normalize_value
 
 # Helpers
 
@@ -25,7 +25,7 @@ def expected_path(p_str: str = ".") -> str:
     return p.expanduser().resolve().as_posix()
 
 
-# Minimal dataclass to test get_hash_factors.
+# Minimal dataclass to test get_compile_factors.
 # Avoid importing heavy vLLM configs.
 @dataclass
 class SimpleConfig:
@@ -136,8 +136,8 @@ def test_enum_vs_int_disambiguation():
     assert enum_val == "raw_logits"
 
     # Build factor dicts from configs with int vs enum
-    f_int = get_hash_factors(SimpleConfig(1), set())
-    f_enum = get_hash_factors(SimpleConfig(DummyLogprobsMode.RAW_LOGITS), set())
+    f_int = get_compile_factors(SimpleConfig(1), set())
+    f_enum = get_compile_factors(SimpleConfig(DummyLogprobsMode.RAW_LOGITS), set())
     # The int case remains a primitive value
     assert f_int["a"] == 1
     # The enum case becomes a tagged tuple ("module.QualName", "raw_logits")

tests/config/test_multimodal_config.py

@@ -18,8 +18,8 @@ def test_mm_encoder_attn_backend_invalid():
 
 
 def test_mm_encoder_attn_backend_hash_updates():
-    base_hash = MultiModalConfig().compute_hash()
+    base_hash = MultiModalConfig().compile_factors()
     overridden_hash = MultiModalConfig(
         mm_encoder_attn_backend=AttentionBackendEnum.FLASH_ATTN
-    ).compute_hash()
+    ).compile_factors()
     assert base_hash != overridden_hash

vllm/compilation/backends.py

@@ -93,8 +93,8 @@ def __init__(self, compilation_config: CompilationConfig):
         self.compilation_config = compilation_config
         self.compiler = make_compiler(compilation_config)
 
-    def compute_hash(self, vllm_config: VllmConfig) -> str:
-        return self.compiler.compute_hash(vllm_config)
+    def compile_factors(self, vllm_config: VllmConfig) -> str:
+        return self.compiler.compile_factors(vllm_config)
 
     @contextmanager
     def compile_context(self, runtime_shape: int | None = None):
@@ -590,8 +590,8 @@ def __call__(
         env_factors = envs.compile_factors()
         env_hash = hash_factors(env_factors)
         # Compute config/compiler/code hashes once and reuse
-        config_hash = vllm_config.compute_hash()
-        compiler_hash = self.compiler_manager.compute_hash(vllm_config)
+        config_hash = vllm_config.compile_factors()
+        compiler_hash = self.compiler_manager.compile_factors(vllm_config)
         forward_code_files = list(sorted(self.compilation_config.traced_files))
 
         logger.debug(
@@ -621,7 +621,7 @@ def __call__(
             # graph.
             factors = [env_hash, config_hash, code_hash, compiler_hash]
             # Use SHA-256 for cache key hashing to be consistent across
-            # compute_hash functions. Truncate for a short cache dir name.
+            # compile_factors functions. Truncate for a short cache dir name.
             hash_key = hashlib.sha256(str(factors).encode()).hexdigest()[:10]
             cache_dir = os.path.join(
                 envs.VLLM_CACHE_ROOT, "torch_compile_cache", hash_key

vllm/compilation/caching.py

@@ -138,12 +138,12 @@ def compilation_config_hash_factors(vllm_config: VllmConfig) -> list[str]:
     factors = []
     # 0. factors come from the env, for example, The values of
     # VLLM_PP_LAYER_PARTITION will affect the computation graph.
-    env_hash = envs.compute_hash()
+    env_hash = envs.compile_factors()
     factors.append(env_hash)
 
     # 1. factors come from the vllm_config (it mainly summarizes how the
     #    model is created)
-    config_hash = vllm_config.compute_hash()
+    config_hash = vllm_config.compile_factors()
     factors.append(config_hash)
     return factors
 

vllm/compilation/compiler_interface.py

@@ -46,12 +46,12 @@ def initialize_cache(
         """
         pass
 
-    def compute_hash(self, vllm_config: VllmConfig) -> str:
+    def compile_factors(self, vllm_config: VllmConfig) -> str:
         """
         Gather all the relevant information from the vLLM config,
         to compute a hash so that we can cache the compiled model.
 
-        See [`VllmConfig.compute_hash`][vllm.config.VllmConfig.compute_hash]
+        See [`VllmConfig.compile_factors`][vllm.config.VllmConfig.compile_factors]
         to check what information
         is already considered by default. This function should only
         consider the information that is specific to the compiler.
@@ -195,7 +195,7 @@ class InductorStandaloneAdaptor(CompilerInterface):
     def __init__(self, save_format: Literal["binary", "unpacked"]):
         self.save_format = save_format
 
-    def compute_hash(self, vllm_config: VllmConfig) -> str:
+    def compile_factors(self, vllm_config: VllmConfig) -> str:
         factors = get_inductor_factors()
         hash_str = hashlib.md5(
             str(factors).encode(), usedforsecurity=False
@@ -284,7 +284,7 @@ class InductorAdaptor(CompilerInterface):
 
     name = "inductor"
 
-    def compute_hash(self, vllm_config: VllmConfig) -> str:
+    def compile_factors(self, vllm_config: VllmConfig) -> str:
         factors = get_inductor_factors()
         hash_str = hashlib.md5(
             str(factors).encode(), usedforsecurity=False

vllm/compilation/pass_manager.py

@@ -127,7 +127,7 @@ def uuid(self):
         affects compilation caching. Its uuid depends on the UUIDs of all
         dependent passes and the pass config. See InductorPass for more info.
         """
-        state = {"pass_config": self.pass_config.compute_hash(), "passes": []}
+        state = {"pass_config": self.pass_config.compile_factors(), "passes": []}
         for pass_ in self.passes:
             state["passes"].append(pass_.uuid())
         state["passes"].append(self.fix_functionalization.uuid())

vllm/config/cache.py

@@ -7,7 +7,7 @@
 from pydantic import Field, SkipValidation, field_validator
 from pydantic.dataclasses import dataclass
 
-from vllm.config.utils import config
+from vllm.config.utils import HashResult, config, get_compile_factors, hash_factors
 from vllm.logger import init_logger
 from vllm.utils.mem_constants import GiB_bytes
 from vllm.utils.mem_utils import get_cpu_memory
@@ -147,17 +147,20 @@ class CacheConfig:
     'native' (vLLM native CPU offloading), 'lmcache' This option must be used 
     together with kv_offloading_size."""
 
-    def compute_hash(self) -> str:
+    def compile_factors(self, *, return_factors: bool = False) -> HashResult:
         """
-        WARNING: Whenever a new field is added to this config,
-        ensure that it is included in the factors list if
-        it affects the computation graph.
+        WARNING: Whenever a new field is added to this config, review
+        `ignored_factors` to decide whether the field should be excluded.
+        All other dataclass fields participate in the hash automatically.
 
         Provide a hash that uniquely identifies all the configs
         that affect the structure of the computation
         graph from input ids/embeddings to the final hidden states,
         excluding anything before input ids/embeddings and after
         the final hidden states.
+
+        This config uses an opt-out hash: start from every dataclass field and
+        then drop the `ignored_factors` below.
         """
         ignored_factors = {
             # Runtime/derived knobs that don't affect compiled graph shape
@@ -178,9 +181,9 @@ def compute_hash(self) -> str:
             "kv_sharing_fast_prefill",
         }
 
-        from vllm.config.utils import get_hash_factors, hash_factors
-
-        factors = get_hash_factors(self, ignored_factors)
+        factors = get_compile_factors(self, ignored_factors)
+        if return_factors:
+            return factors or None
         return hash_factors(factors)
 
     def metrics_info(self):

vllm/config/compilation.py

@@ -13,7 +13,7 @@
 
 import vllm.envs as envs
 from vllm.compilation.inductor_pass import CallableInductorPass, InductorPass
-from vllm.config.utils import config
+from vllm.config.utils import HashResult, config, get_compile_factors, hash_factors
 from vllm.logger import init_logger
 from vllm.platforms import current_platform
 from vllm.utils.import_utils import resolve_obj_by_qualname
@@ -159,13 +159,16 @@ def default_fi_allreduce_fusion_max_size_mb() -> dict[int, float]:
             current_platform.get_device_capability().to_int(), {}
         )
 
-    def compute_hash(self) -> str:
+    def compile_factors(self, *, return_factors: bool = False) -> HashResult:
         """
         Produces a hash unique to the pass configuration.
         Any new fields that affect compilation should be added to the hash.
         Any future fields that don't affect compilation should be excluded.
         """
-        return InductorPass.hash_dict(asdict(self))
+        factors = asdict(self)
+        if return_factors:
+            return factors or None
+        return InductorPass.hash_dict(factors)
 
     def __post_init__(self) -> None:
         if not self.enable_noop:
@@ -503,18 +506,17 @@ class CompilationConfig:
         "vllm::sparse_attn_indexer",
     ]
 
-    def compute_hash(self) -> str:
+    def compile_factors(self, *, return_factors: bool = False) -> HashResult:
         """
         Provide a hash that uniquely identifies all the configs
         that affect the structure of the computation
         graph from input ids/embeddings to the final hidden states,
         excluding anything before input ids/embeddings and after
         the final hidden states.
-        """
-        # Opt-out: default-include declared fields; keep a tiny exclude set;
-        # normalize types; keep SHA-256. For nested opaque configs, include a
-        # stable identifier (e.g., pass_config.compute_hash()) instead of object id.
 
+        This config follows the opt-out hashing pattern: start from every
+        dataclass field and remove the `ignored_factors` list below.
+        """
         ignored_factors = {
             # Paths/dirs and runtime/metrics that don’t affect compiled graph
             "debug_dump_path",
@@ -524,13 +526,11 @@ def compute_hash(self) -> str:
             "traced_files",
             "compilation_time",
             "static_forward_context",
-            "pass_config",  # handled separately below
         }
 
-        from vllm.config.utils import get_hash_factors, hash_factors
-
-        factors = get_hash_factors(self, ignored_factors)
-        factors["pass_config"] = self.pass_config.compute_hash()
+        factors = get_compile_factors(self, ignored_factors)
+        if return_factors:
+            return factors or None
         return hash_factors(factors)
 
     def __repr__(self) -> str:

vllm/config/device.py

@@ -1,15 +1,14 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
 
-import hashlib
 from dataclasses import field
 from typing import Any, Literal
 
 import torch
 from pydantic import ConfigDict, SkipValidation
 from pydantic.dataclasses import dataclass
 
-from vllm.config.utils import config
+from vllm.config.utils import HashResult, config, hash_factors, normalize_value
 
 Device = Literal["auto", "cuda", "cpu", "tpu", "xpu"]
 
@@ -29,7 +28,7 @@ class DeviceConfig:
     """Device type from the current platform. This is set in
     `__post_init__`."""
 
-    def compute_hash(self) -> str:
+    def compile_factors(self, *, return_factors: bool = False) -> HashResult:
         """
         WARNING: Whenever a new field is added to this config,
         ensure that it is included in the factors list if
@@ -45,8 +44,9 @@ def compute_hash(self) -> str:
         # the device/platform information will be summarized
         # by torch/vllm automatically.
         factors: list[Any] = []
-        hash_str = hashlib.md5(str(factors).encode(), usedforsecurity=False).hexdigest()
-        return hash_str
+        if return_factors:
+            return factors or None
+        return hash_factors({"factors": normalize_value(factors)})
 
     def __post_init__(self):
         if self.device == "auto":

vllm/config/ec_transfer.py

@@ -1,13 +1,12 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
-import hashlib
 import uuid
 from dataclasses import field
 from typing import Any, Literal, get_args
 
 from pydantic.dataclasses import dataclass
 
-from vllm.config.utils import config
+from vllm.config.utils import HashResult, config, hash_factors, normalize_value
 
 ECProducer = Literal["ec_producer"]
 ECConsumer = Literal["ec_consumer"]
@@ -60,7 +59,7 @@ class ECTransferConfig:
     """The Python module path to dynamically load the EC connector from.
     Only supported in V1."""
 
-    def compute_hash(self) -> str:
+    def compile_factors(self, *, return_factors: bool = False) -> HashResult:
         """
         WARNING: Whenever a new field is added to this config,
         ensure that it is included in the factors list if
@@ -75,8 +74,9 @@ def compute_hash(self) -> str:
         # no factors to consider.
         # this config will not affect the computation graph.
         factors: list[Any] = []
-        hash_str = hashlib.md5(str(factors).encode(), usedforsecurity=False).hexdigest()
-        return hash_str
+        if return_factors:
+            return factors or None
+        return hash_factors({"factors": normalize_value(factors)})
 
     def __post_init__(self) -> None:
         if self.engine_id is None:

vllm/config/kv_transfer.py

@@ -1,14 +1,13 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
 
-import hashlib
 import uuid
 from dataclasses import field
 from typing import Any, Literal, get_args
 
 from pydantic.dataclasses import dataclass
 
-from vllm.config.utils import config
+from vllm.config.utils import HashResult, config, hash_factors, normalize_value
 
 KVProducer = Literal["kv_producer", "kv_both"]
 KVConsumer = Literal["kv_consumer", "kv_both"]
@@ -64,7 +63,7 @@ class KVTransferConfig:
     enable_permute_local_kv: bool = False
     """Experiment feature flag to enable HND to NHD KV Transfer"""
 
-    def compute_hash(self) -> str:
+    def compile_factors(self, *, return_factors: bool = False) -> HashResult:
         """
         WARNING: Whenever a new field is added to this config,
         ensure that it is included in the factors list if
@@ -79,8 +78,9 @@ def compute_hash(self) -> str:
         # no factors to consider.
         # this config will not affect the computation graph.
         factors: list[Any] = []
-        hash_str = hashlib.md5(str(factors).encode(), usedforsecurity=False).hexdigest()
-        return hash_str
+        if return_factors:
+            return factors or None
+        return hash_factors({"factors": normalize_value(factors)})
 
     def __post_init__(self) -> None:
         if self.engine_id is None:

vllm/config/load.py

@@ -1,13 +1,12 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
 
-import hashlib
 from typing import TYPE_CHECKING, Any
 
 from pydantic import Field, field_validator
 from pydantic.dataclasses import dataclass
 
-from vllm.config.utils import config
+from vllm.config.utils import HashResult, config, hash_factors, normalize_value
 from vllm.logger import init_logger
 
 if TYPE_CHECKING:
@@ -89,7 +88,7 @@ class LoadConfig:
     see original doc for `map_location` in https://pytorch.org/docs/stable/generated/torch.load.html
     """
 
-    def compute_hash(self) -> str:
+    def compile_factors(self, *, return_factors: bool = False) -> HashResult:
         """
         WARNING: Whenever a new field is added to this config,
         ensure that it is included in the factors list if
@@ -104,8 +103,9 @@ def compute_hash(self) -> str:
         # no factors to consider.
         # this config will not affect the computation graph.
         factors: list[Any] = []
-        hash_str = hashlib.md5(str(factors).encode(), usedforsecurity=False).hexdigest()
-        return hash_str
+        if return_factors:
+            return factors or None
+        return hash_factors({"factors": normalize_value(factors)})
 
     @field_validator("load_format", mode="after")
     def _lowercase_load_format(cls, load_format: str) -> str: