[Config Refactor] sentinel default precedence (#3078)

Signed-off-by: lishunyang <lishunyang12@163.com>
Signed-off-by: xiaohajiayou <923390377@qq.com>
Co-authored-by: lishunyang <lishunyang12@163.com>

vllm_omni/entrypoints/utils.py

@@ -21,6 +21,18 @@ PROJECT_ROOT = Path(__file__).parent.parent.parent
 
 logger = init_logger(__name__)
 
+
+def _warn_deprecated_explicit_keys(kwargs: dict[str, Any]) -> None:
+    if "cli_explicit_keys" in kwargs:
+        import warnings
+
+        warnings.warn(
+            "cli_explicit_keys= is deprecated and ignored. Remove the kwarg.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+
+
 _DIFFUSERS_CLASS_TO_CONFIG: dict[str, str] = {
     "GlmImagePipeline": "glm_image",
 }
@@ -343,7 +355,7 @@ def load_stage_configs_from_model(
     base_engine_args: dict | None = None,
     deploy_config_path: str | None = None,
     stage_overrides: dict[str, dict[str, Any]] | None = None,
-    cli_explicit_keys: set[str] | None = None,
+    **deprecated_kwargs: Any,
 ) -> list:
     """Load stage configurations from model's default config file.
 
@@ -358,33 +370,25 @@ def load_stage_configs_from_model(
         base_engine_args: Base engine args to merge as CLI overrides.
         deploy_config_path: Optional explicit deploy config path.
         stage_overrides: Per-stage overrides from --stage-overrides.
-        cli_explicit_keys: Set of CLI keys the user actually typed. When
-            provided, only these keys override deploy YAML; argparse defaults
-            stay subordinate to YAML. ``None`` means treat every kwarg as
-            explicit (programmatic ``Omni()`` calls).
 
     Returns:
         List of stage configuration dictionaries
     """
+    _warn_deprecated_explicit_keys(deprecated_kwargs)
+
     if base_engine_args is None:
         base_engine_args = {}
 
     cli_overrides = _convert_dataclasses_to_dict(dict(base_engine_args))
-    # Per-stage JSON overrides are always explicit (the user typed --stage-overrides).
-    explicit = set(cli_explicit_keys) if cli_explicit_keys is not None else None
     if stage_overrides:
         for stage_id_str, overrides in stage_overrides.items():
             for key, val in overrides.items():
-                stage_key = f"stage_{stage_id_str}_{key}"
-                cli_overrides[stage_key] = val
-                if explicit is not None:
-                    explicit.add(stage_key)
+                cli_overrides[f"stage_{stage_id_str}_{key}"] = val
 
     stages = StageConfigFactory.create_from_model(
         model,
         cli_overrides=cli_overrides,
         deploy_config_path=deploy_config_path,
-        cli_explicit_keys=explicit,
     )
     if stages is not None:
         # Convert StageConfig objects to OmegaConf for backward compat
@@ -545,7 +549,7 @@ def load_and_resolve_stage_configs(
     default_stage_cfg_factory: Any = None,
     deploy_config_path: str | None = None,
     stage_overrides: dict[str, dict[str, Any]] | None = None,
-    cli_explicit_keys: set[str] | None = None,
+    **deprecated_kwargs: Any,
 ) -> tuple[str, list]:
     """Load stage configurations from model or YAML file with fallback to defaults.
 
@@ -589,6 +593,8 @@ def load_and_resolve_stage_configs(
                 stage_configs_path,
             )
 
+    _warn_deprecated_explicit_keys(deprecated_kwargs)
+
     if deploy_config_path is not None:
         config_path = deploy_config_path
         stage_configs = load_stage_configs_from_model(
@@ -596,7 +602,6 @@ def load_and_resolve_stage_configs(
             base_engine_args=kwargs,
             deploy_config_path=deploy_config_path,
             stage_overrides=stage_overrides,
-            cli_explicit_keys=cli_explicit_keys,
         )
         if not stage_configs:
             if default_stage_cfg_factory is not None:
@@ -610,7 +615,6 @@ def load_and_resolve_stage_configs(
             model,
             base_engine_args=kwargs,
             stage_overrides=stage_overrides,
-            cli_explicit_keys=cli_explicit_keys,
         )
         if not stage_configs:
             if default_stage_cfg_factory is not None: