[Bugfix] Add explicit error when using CFGP with distilled Cosmos3 models

[MaciejBalaNV]

This PR adds explicit error when CFGP is used with distilled Cosmos3 models.

Purpose

This PR adds explicit error when CFGP is used with distilled Cosmos3 models. These models use guidance=1, so CFGP does not make sense or bring any benefit. Before this PR, CFGP was silently ignored and users would have pointlessly duplicated instances without any performance gain. After this PR an explicit error is thrown before the model is loaded so that we do not spend time on unnecessary model loading.

Test Plan

Unit tests

We add 8 new unit tests that verify whether the error is indeed thrown and whether other cases work fine.

Serving test

This command is now expected to fail with an appropriate error message: vllm serve nvidia/Cosmos3-Super-Image2Video-4Step --omni --cfg-parallel-size 2

vLLM Version:
0.29
vLLM-Omni Commit:
ToT

Test Result

Unit tests

All new unit tests pass

Serving tests

vllm serve nvidia/Cosmos3-Super-Image2Video-4Step --omni --cfg-parallel-size 2 indeed fails with ValueError: Distilled Cosmos3 checkpoints run without classifier-free guidance. Set --cfg-parallel-size 1 and use --ulysses-degree for multi-GPU inference. error message. vllm serve nvidia/Cosmos3-Super-Image2Video-4Step --omni --ulysses-degree 2 works fine and provides the expected speedup.

BEFORE SUBMITTING: read CONTRIBUTING.md and run the precheck-pr skill with the code agent for a self-check against project conventions.
(anything written below this line will be removed by GitHub Actions)

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-11T12:20:12.388331Z	7b563ae	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[vllm-omni-review-bot]

This PR appears to belong to: docs/design/module/diffusion/offloader.md, docs/design/module/diffusion/diffusion_model_integration.md, docs/design/module/diffusion/index.md.

Module owners: @fhfuih @Bounty-hunter @david6666666

Routing: @fhfuih via module of the changed files, semantic router, CODEOWNERS; @Bounty-hunter via module of the changed files; @david6666666 via module of the changed files

@MaciejBalaNV, please review your own changes and leave a short self-review comment describing what you checked. PRs without author self-review may not be assigned a reviewer.

Please take a look when you have a chance. If you would like an automated review, mention @vllm-omni-review-bot in a comment.

[MaciejBalaNV]

Overall this is a simple change that adds one ValueError after a check and moves scheduler initialization before the checkpoint loading.

[MaciejBalaNV]

The main part of the change is just moving the scheduler init here and adding the ValueError.

[hsliuustc0106]

LGTM. Verified the fail-fast path end to end: the offload component-selector guard precedes the new scheduler-config read, so the error lands before any component load; the parallel_config deref is safe on all construction paths (dataclass default_factory + post-init normalization); and the guidance warning covers every distilled-reachable request path — non-T2I/T2V modes are hard-rejected and T2I/T2V/I2V route through _resolve_guidance_scale. The new tests fail on base and exercise the real load_config, so they pin both behaviors.

One note: no CI lane has run the new unit tests on this head — the green evidence is author-run only. Consider adding a trigger label if you want lane coverage before merge.

[lishunyang12]

Can you briefly introduce what is CFGP? sorry that my context does not cover this model recently,

[MaciejBalaNV]

@lishunyang12
It's --cfg-parallel-size option in vllm serve which parallelizes the model across the classifier-free guidance calls. It's not Cosmos3 specific