[Refactor] Remove legacy --stage-configs-path from the serve CLI (#5647)

Signed-off-by: zwhzzz0821 <2831474076@qq.com>

tests/dfx/reliability/test_reliability_qwen3_omni.py

@@ -241,12 +241,12 @@ def _fault_keywords_match_response(*, status: int, body: bytes) -> bool:
     return any(key in text for key in body_fault_hints)
 
 
-def _stage_config_path_from_omni_server(omni_server: _HasServeArgs) -> str | None:
+def _deploy_config_path_from_omni_server(omni_server: _HasServeArgs) -> str | None:
     args: list[str] = omni_server.serve_args
     for i, arg in enumerate(args):
-        if arg == "--stage-configs-path" and i + 1 < len(args):
+        if arg == "--deploy-config" and i + 1 < len(args):
             return args[i + 1]
-        if arg.startswith("--stage-configs-path="):
+        if arg.startswith("--deploy-config="):
             return arg.split("=", 1)[1]
     return None
 
@@ -331,7 +331,7 @@ def test_reliability_fault_gpu_oom_error_contract_consistent_chat_speech(
     """
     device_spec = resolve_oom_device_spec(
         OOM_INJECTION_CONFIG,
-        _stage_config_path_from_omni_server(omni_server_function),
+        _deploy_config_path_from_omni_server(omni_server_function),
     )
     handle = inject_gpu_oom(
         device=device_spec,
@@ -394,7 +394,7 @@ def test_reliability_fault_gpu_oom_error_contract_consistent_chat_speech(
 def test_reliability_fault_gpu_oom_chat_large_payload_failure(omni_server_function, openai_client_function) -> None:
     device_spec = resolve_oom_device_spec(
         OOM_INJECTION_CONFIG,
-        _stage_config_path_from_omni_server(omni_server_function),
+        _deploy_config_path_from_omni_server(omni_server_function),
     )
     handle = inject_gpu_oom(
         device=device_spec,
@@ -437,7 +437,7 @@ def test_reliability_fault_gpu_oom_chat_large_payload_failure(omni_server_functi
 def test_reliability_fault_gpu_oom_concurrent_pressure_failure(omni_server_function, openai_client_function) -> None:
     device_spec = resolve_oom_device_spec(
         OOM_INJECTION_CONFIG,
-        _stage_config_path_from_omni_server(omni_server_function),
+        _deploy_config_path_from_omni_server(omni_server_function),
     )
     handle = inject_gpu_oom(
         device=device_spec,
@@ -791,7 +791,7 @@ def test_reliability_fault_gpu_oom_state_converges_after_fault_removed(
     """
     device_spec = resolve_oom_device_spec(
         OOM_RECOVER_INJECTION_CONFIG,
-        _stage_config_path_from_omni_server(omni_server_function),
+        _deploy_config_path_from_omni_server(omni_server_function),
     )
     handle = inject_gpu_oom(
         device=device_spec,

tests/e2e/accuracy/helpers.py

@@ -696,7 +696,7 @@ def _dreamzero_omni_server_from_params(params):
 
     server_args = list(params.server_args or [])
     if params.stage_config_path is not None:
-        server_args += ["--stage-configs-path", params.stage_config_path]
+        server_args += ["--deploy-config", params.stage_config_path]
     return OmniServer(
         params.model,
         server_args,

tests/e2e/accuracy/test_hunyuan_image3.py

@@ -359,12 +359,12 @@ def _run_offline(deploy_config_path: str, output_path: Path) -> tuple[Image.Imag
     return image, cot_text, elapsed
 
 
-def _run_online(stage_configs_path: str, output_path: Path) -> tuple[Image.Image, str, float]:
+def _run_online(deploy_config_path: str, output_path: Path) -> tuple[Image.Image, str, float]:
     from benchmarks.accuracy.common import decode_base64_image, pil_to_png_bytes
 
     server_args = [
-        "--stage-configs-path",
-        stage_configs_path,
+        "--deploy-config",
+        deploy_config_path,
         "--stage-init-timeout",
         "300",
         "--init-timeout",

tests/entrypoints/test_serve.py

@@ -46,6 +46,26 @@ def test_serve_parser_accepts_strategy_config() -> None:
     assert args.get_explicit_kwargs_dict()["strategy_config"] == "/tmp/strategy.yaml"
 
 
+def test_serve_parser_accepts_deploy_config() -> None:
+    parser = TrackingArgumentParser()
+    subparsers = parser.add_subparsers(dest="subcommand")
+    OmniServeCommand().subparser_init(subparsers)
+
+    args = parser.parse_args(["serve", "fake-model", "--omni", "--deploy-config", "/tmp/deploy.yaml"])
+
+    assert args.deploy_config == "/tmp/deploy.yaml"
+    assert args.get_explicit_kwargs_dict()["deploy_config"] == "/tmp/deploy.yaml"
+
+
+def test_serve_parser_rejects_stage_configs_path() -> None:
+    parser = TrackingArgumentParser()
+    subparsers = parser.add_subparsers(dest="subcommand")
+    OmniServeCommand().subparser_init(subparsers)
+
+    with pytest.raises(SystemExit):
+        parser.parse_args(["serve", "fake-model", "--omni", "--stage-configs-path", "/tmp/stages.yaml"])
+
+
 def test_serve_parser_accepts_four_way_cfg_parallelism() -> None:
     parser = TrackingArgumentParser()
     subparsers = parser.add_subparsers(dest="subcommand")
@@ -66,7 +86,6 @@ def _make_headless_args(**kwargs) -> TrackingNamespace:
         "omni_replica_address": None,
         "omni_dp_size_local": 1,
         "worker_backend": "multi_process",
-        "stage_configs_path": None,
         "deploy_config": None,
         "log_stats": False,
         "disable_log_stats": False,
@@ -154,6 +173,7 @@ def test_run_headless_parses_and_forwards_stage_overrides(mocker: MockerFixture)
     captured: dict = {}
 
     def _fake_resolve(*args, **kwargs):
+        captured["args"] = args
         captured.update(kwargs)
         # Return a stage that does NOT match stage_id=0 so run_headless stops
         # right after the resolver call (we only care about how it was called).
@@ -166,12 +186,15 @@ def test_run_headless_parses_and_forwards_stage_overrides(mocker: MockerFixture)
 
     args = _make_headless_args(
         stage_id=0,
+        deploy_config="/tmp/deploy.yaml",
         strategy_config="/tmp/strategy.yaml",
         stage_overrides='{"0": {"devices": "0,1"}, "1": {"devices": "2"}}',
     )
     with pytest.raises(ValueError, match="No stage config found for stage_id=0"):
         run_headless(args)
 
+    assert captured["args"][1] is None
+    assert captured["deploy_config_path"] == "/tmp/deploy.yaml"
     assert captured["stage_overrides"] == {"0": {"devices": "0,1"}, "1": {"devices": "2"}}
     assert captured["strategy_config_path"] == "/tmp/strategy.yaml"
 

tests/helpers/runtime.py

@@ -598,7 +598,7 @@ class OmniServerStageCli(OmniServer):
             "serve",
             self.model,
             "--omni",
-            "--stage-configs-path",
+            "--deploy-config",
             self.stage_config_path,
             "--stage-id",
             str(stage_id),
@@ -3135,7 +3135,7 @@ def iter_omni_server(
                 raise ValueError("omni_server with use_stage_cli=True requires use_omni=True")
             if stage_config_path is None:
                 raise ValueError("omni_server with use_stage_cli=True requires a stage_config_path")
-            server_args += ["--stage-configs-path", stage_config_path]
+            server_args += ["--deploy-config", stage_config_path]
 
             with OmniServerStageCli(
                 model,
@@ -3151,7 +3151,7 @@ def iter_omni_server(
                 print("OmniServer stopping...")
         else:
             if stage_config_path is not None:
-                server_args += ["--stage-configs-path", stage_config_path]
+                server_args += ["--deploy-config", stage_config_path]
 
             with (
                 OmniServer(

tests/helpers/tests/test_runtime_stage_cli.py

@@ -35,7 +35,7 @@ def test_stage_cli_builds_headless_replica_cmd(tmp_path: Path) -> None:
     assert "--headless" in cmd
     assert cmd[cmd.index("--stage-id") + 1] == "1"
     assert cmd[cmd.index("--replica-id") + 1] == "2"
-    assert cmd[cmd.index("--stage-configs-path") + 1] == server.stage_config_path
+    assert cmd[cmd.index("--deploy-config") + 1] == server.stage_config_path
 
 
 def test_stage_cli_splits_devices_per_replica(tmp_path: Path) -> None: