[Bugfix] Require a model for vllm serve --omni (fixes #4158)

[abinggo]

Purpose

Fixes #4158.

vllm serve --omni invoked without a model does not error. It inherits vLLM's ModelConfig.model default (Qwen/Qwen3-0.6B) and brings it up as an Omni stage, so a text LLM (Qwen3ForCausalLM) is routed into the diffusion stage and startup crashes deep in the diffusion worker:

ValueError: Model class Qwen3ForCausalLM not found in diffusion model registry.

The real cause — "no model was provided" — is never surfaced; the user only sees the diffusion-registry crash plus a cascade of secondary tracebacks.

Fix

Fail fast in OmniServeCommand.validate(). As the reporter noted, the subtlety is that args.model always carries vLLM's default, so the validation must distinguish an explicitly-provided model from the inherited default. A model is considered provided when any of these is present:

• the positional model_tag (vllm serve <model> --omni)
• the --model flag (tracked via args.explicit_keys)
• per-stage models from --deploy-config / --stage-configs-path

The guard raises only when none of these is present, so the legitimate multi-stage YAML path is unaffected.

Test Plan

New CPU unit tests in tests/entrypoints/test_serve.py (following the existing parser-based harness, pytest.mark.cpu):

• test_omni_serve_requires_model_when_none_provided — ["serve", "--omni"] raises a clear "requires a model" error.
• test_omni_serve_accepts_model_or_stage_yaml (parametrized) — positional model, --model, --stage-configs-path, and --deploy-config all pass the guard (downstream validation mocked so only the new guard is exercised).

ruff check and ruff format --check pass on the changed files.

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[Gaohan123]

@tzhouam PTAL

[Gaohan123]

Checking only whether a stage/deploy config path was provided is not sufficient to establish that a model was provided. The new-format DeployConfig files are primarily deployment overrides, and built-in configs such as vllm_omni/deploy/qwen2_5_omni.yaml do not contain a model checkpoint. Therefore, vllm serve --omni --deploy-config vllm_omni/deploy/qwen2_5_omni.yaml bypasses this guard while args.model still contains vLLM's default Qwen/Qwen3-0.6B, potentially reproducing the same downstream diffusion-registry failure this PR is intended to prevent.

The same issue applies when --stage-configs-path points to a new-format stages: YAML, because it is later promoted to a deploy config.

Could we require an explicit positional/--model value for new-format deploy configs, or inspect the YAML and only treat it as a model source when it actually defines valid per-stage models? The tests should also include a negative case using a deploy config without a model; the current positive test mocks downstream validation and therefore cannot detect this failure mode.

[abinggo]

Good catch — you're right, and I verified the deploy/stage YAML is never a model source: load_and_resolve_stage_configs takes model as its first arg and threads it through every path, and none of the in-tree deploy/*.yaml or legacy stage_configs/*.yaml define a checkpoint (they carry per-stage engine args only). So the mere presence of --deploy-config/--stage-configs-path never established that a model was provided.

Rather than inspect the YAML, I dropped that branch entirely and now require an explicit model from the CLI (positional or --model). This also fixes the --stage-configs-path-promoted-to-deploy case you mentioned, since the check no longer depends on the config path at all. I also reject empty/whitespace values (e.g. --model "$MODEL" with the var unset) so that footgun fails fast too.

Added the requested negative tests: --deploy-config/--stage-configs-path without a model, plus empty/whitespace --model, all assert the guard fires; positive cases pair a model with the YAML. Updated in 045ea714.

[vllm-omni-review-bot]

Omni ReviewBot triage note

Automated triage of commit 708a4bd333e4 produced:

• Priority: high. Prompt maintainer attention is suggested.

These are automated triage suggestions only — the final decision belongs to the maintainers.

[yenuo26]

@abinggo please fix conflicts

[Gaohan123]

LGTM. Thanks