[Config Refactor] Remove legacy Omni CLI arg helper and align tests with nullified parser defaults

[xiaohajiayou]

Purpose

Remove the legacy OmniBase.from_cli_args() path now that CLI precedence is handled by nullified parser defaults.

Before this change, parser-driven callers could rely on:

• Omni.from_cli_args(...)
• detect_explicit_cli_keys(...)

to distinguish user-typed values from argparse defaults.

After the sentinel-default refactor, that compatibility path is no longer needed:

• deploy-overriding parser defaults are set to None
• explicit CLI values remain concrete values like True / False
• direct Omni(**vars(args)) is the intended construction path

This PR removes the old helper path and updates entrypoint tests to cover the new mechanism directly.

Test Plan

1. Remove OmniBase.from_cli_args() from omni_base.py.
2. Remove the unused detect_explicit_cli_keys() helper from utils.py.
3. Replace the old entrypoint compatibility test with a new parser-nullify test in test_omni_entrypoints.py:
   nullify_stage_engine_defaults(parser) + Omni(**vars(args))
4. Update test_serve.py so it validates the new behavior without depending on the removed explicit-key helper.

Test Result

Executed in the project venv:

/home/hacode/vllm-omni/.venv/bin/python -m pytest tests/entrypoints/test_omni_entrypoints.py

Result:

• 37 passed

The new replacement test verifies:

• untyped deploy-override fields are nullified to None
• non-override parser defaults remain intact
• direct Omni(**vars(args)) works as intended with the new parser mechanism

TODO

This pr will be integrated after #2989. Make sure sentinel-default refactor covers all existing refractored models

---

Essential Elements of an Effective PR Description Checklist

• The purpose of the PR, such as "Fix some issue (link existing issues this PR will resolve)".
• The test plan. Please provide the test scripts & test commands. Please state the reasons if your codes don't require additional test scripts. For test file guidelines, please check the test style doc
• The test results. Please paste the results comparison before and after, or the e2e results.
• (Optional) The necessary documentation update, such as updating supported_models.md and examples for a new model. Please run mkdocs serve to sync the documentation editions to ./docs.
• (Optional) Release notes update. If your change is user-facing, please update the release notes draft.

BEFORE SUBMITTING, PLEASE READ https://github.com/vllm-project/vllm-omni/blob/main/CONTRIBUTING.md (anything written below this line will be removed by GitHub Actions)

[hsliuustc0106]

@lishunyang12

[hsliuustc0106]

Clean removal of the legacy OmniBase.from_cli_args() + detect_explicit_cli_keys() path, superseded by the sentinel-default refactor (RFC #3035). All internal callers migrated to Omni(**vars(args)) with pre-nullified parsers. The vllm serve path was already using direct AsyncOmni(model=..., **kwargs) and is unaffected. OmniEngineArgs.from_cli_args (a separate, unrelated class method) is untouched. Tests updated and passing.

[lishunyang12]

This PR's design was dissussed offline yesterday. Omni.from_cli_args(...) and detect_explicit_cli_keys(...) were introduced in #2383 to solve default params predecence issue but look confusing from user perspective. We decide to drop them to align with original API design.The params precedence issue has been solved by #3078 in a more clean way.

[lishunyang12]

@xiaohajiayou. This pr will be integrated after #2989. Please make sure sentinel-default refactor covers all existing refractored models, and has been/would cover rest of models. We should document our new design as model developers might find it useful for integration.

[lishunyang12]

Per the earlier comment, this depends on #2989 landing first — worth a TODO in the PR description so reviewers don't merge prematurely. Also: examples/offline_inference/bagel/end2end.py originally used from_cli_args and is updated here, but please sweep the rest of the ~14 examples for the same pattern before this lands.

[xiaohajiayou]

Good point. I restored OmniBase.from_cli_args(...) as a deprecated compatibility shim instead of hard-removing it.

What changed in this update:

• from_cli_args() is back and now emits a DeprecationWarning
• it remains a thin wrapper over direct construction and does not restore the old explicit-key handling path
• I added test coverage for the deprecation warning and for _cli_explicit_keys not being forwarded/consumed
• I also added comments at the omni_kwargs["model"] = model_name sites to make the intentional CLI --model override explicit
• Finally, I will keep tracking newly merged model migrations and samples, and ensure this PR remains compatible and covers those cases before final merge.

[hsliuustc0106]

Cross-PR Config Refactor Review

This is one of several coordinated config refactor PRs. Reviewed together with #3162, #3160, #3154, #3128, #3120, #3139.

What this PR does

• Converts 15 offline example scripts from Omni.from_cli_args(args) to Omni(**vars(args)) with nullify_stage_engine_defaults(parser) called explicitly in parse_args().
• Adds DeprecationWarning to from_cli_args().
• Updates tests to cover both the new direct path and the deprecated path.

Assessment

Good cleanup. The deprecation is properly gated with a DeprecationWarning.

One issue: merge order dependency with #3160

This PR adds imports of nullify_stage_engine_defaults from vllm_omni.engine.arg_utils in every offline example, but #3160 removes that function from arg_utils.py entirely. This PR must merge before #3160, or the offline scripts will break.

Recommendation: merge this PR before #3160, and have #3160 either keep a backward-compatible shim or remove the function only from production code while leaving it for offline examples until a follow-up cleans them up.

[xiaohajiayou]

This PR deprecates Omni.from_cli_args() and migrates all callers to Omni(**kwargs), with nullify_stage_engine_defaults(parser) ensuring correct deploy YAML precedence. Ready for review.
@lishunyang12 @hsliuustc0106

What changed

1. Omni.from_cli_args → deprecated shim

Restored with DeprecationWarning for backward compatibility. New code should call nullify_stage_engine_defaults(parser) before parse_args(), then construct Omni(**vars(args)) directly.

2. All examples migrated to direct construction

model	example	pattern
qwen3_omni	end2end.py / end2end_async_chunk.py	Omni(**kwargs) / AsyncOmni(**vars(args))
qwen2_5_omni	end2end.py	Omni(**omni_kwargs)
ming_flash_omni	end2end.py	Omni(**omni_kwargs)
ming_flash_omni_tts	end2end.py	Omni(**vars(args))
bagel	end2end.py	Omni(**omni_kwargs)
hunyuan_image3	end2end.py	Omni(**omni_kwargs)
qwen3_tts	end2end.py	Omni(**omni_kwargs) / AsyncOmni(**omni_kwargs)
fish_speech	end2end.py	Omni(...) / AsyncOmni(...)
voxcpm / voxcpm2	end2end.py	Omni(...)
voxtral_tts	end2end.py	Omni(...) / AsyncOmni(...)
dynin_omni	end2end.py	Omni(...)
omnivoice	end2end.py	Omni(...)
cosyvoice3	verify_e2e_cosyvoice.py	Omni(...)
mimo_audio	end2end.py	Omni(...)
mammothmodal2	run_mammothmoda2_*.py	Omni(...)

Pure diffusion examples (text_to_image, text_to_video) are excluded — no deploy YAML, no nullify needed.

3. nullify_stage_engine_defaults(parser)

• Added to all omni-model example parse_args() functions to ensure deploy YAML values take precedence over parser defaults.
• Models still on legacy stage_configs_path (e.g. mammothmodal2) also include the call as a forward safeguard, so it won't be missed when they migrate to deploy YAML later.

4. Tests

Deprecated from_cli_args tests preserved in test_omni_entrypoints.py; serve test updated for nullified defaults.

• cmd

pytest -v -s \
  tests/entrypoints/test_omni_entrypoints.py \
  tests/engine/test_arg_utils.py \
  -m "core_model and cpu"

• result

-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
--- Running Summary
=============================================================== 54 passed, 16 warnings in 15.28s ===============================================================

[xiaohajiayou]

This PR is ready for review.
@lishunyang12 @hsliuustc0106

[hsliuustc0106]

Review Summary

Validated: CI all green. The from_cli_args deprecation shim is correctly gated with DeprecationWarning. All 15 migrated examples already had nullify_stage_engine_defaults(parser) in their parse_args() — the mechanical switch from Omni.from_cli_args(args, ...) to Omni(**vars(args)) is consistent across them. Tests cover both the deprecated path (with warning assertion) and the new direct path.

Two items to address:

1. Dead code not removed. detect_explicit_cli_keys still lives in vllm_omni/entrypoints/utils.py:43 but its last caller (test_serve.py) is deleted by this PR. The PR description says "Remove the unused detect_explicit_cli_keys() helper from utils.py" — but utils.py isn't in the diff. After this lands, the function is dead code.

2. >10 files — recommend L3 tests. Per the test guide, 18 files changed exceeds the threshold for requesting L3 validation. Could you run the L3 integration tests locally and paste results here?

Not blocking. The approach has sign-off from prior maintainer reviews.

---

Reviewed by Claude Code with deepseek-v4-pro

[xiaohajiayou]

1. Dead code not removed. detect_explicit_cli_keys still lives in vllm_omni/entrypoints/utils.py:43 but its last caller (test_serve.py) is deleted by this PR. The PR description says "Remove the unused detect_explicit_cli_keys() helper from utils.py" — but utils.py isn't in the diff. After this lands, the function is dead code.

I think this helper is still used on the deprecated compatibility path. We intentionally did not hard-remove Omni.from_cli_args() because it is public-ish and downstream forks/example scripts may still call it.

• The prior review also suggested keeping at least one release with a DeprecationWarning before removal.

Given that, neither OmniBase.from_cli_args() nor detect_explicit_cli_keys() has been fully removed in this PR. This PR only adds the deprecation warning and migrates in-tree call sites to the direct constructor path, while keeping the compatibility shim working for external callers.