[Bugfix][CPU][DiffusionGemma] Support narrower canvas w/ sync scheduling

[ojeda-e]

Purpose

Fixes DiffusionGemma structured reads on the CPU backend.

Structured reads were added to DiffusionGemma in #57250 and tested on GPU. On CPU they fail with the faster narrower canvases. When async scheduling is disabled, reads that ask for a canvas narrower than the served one are rejected. CPU always runs synchronous scheduling (#31525), and the error asks for --async-scheduling, but CPU ignores that flag.

The same happens on any platform started with --no-async-scheduling.

This PR adds a synchronous diffusion scheduler that trims each request's canvas to its own width. The async diffusion scheduler already does this. Other models are not affected.

Changes in this PR

• Add a DiffusionScheduler for sync scheduling. It cuts each request's canvas down to the width the request asked for, in update_draft_token_ids(). DiffusionAsyncScheduler now inherits from it.
• VllmConfig selects the matching diffusion scheduler for both sync and async scheduling.
• Remove the check that rejected narrow canvases unless --async-scheduling was set.
• Update the structured diffusion README and the tests in tests/test_sampling_params.py and tests/v1/core/test_scheduler.py to match.

No open issue or PR covers this. I searched for diffusion_canvas_length, DiffusionGemma on CPU and CPU async scheduling for diffusion. The closest is #58964, which fixed a separate DiffusionGemma crash on CPU. Structured reads still fail on CPU after that fix.

I used Codex to help with this PR. I reviewed every changed line and ran the tests below.

Test Plan

Hardware: 22 vCPU Intel Xeon Platinum 8481C, Ubuntu 22.04, PyTorch 2.13.0+cpu. vLLM built from source for CPU at 32cc3f1, with the real google/diffusiongemma-26B-A4B-it checkpoint in BF16.

Unit tests:

pytest -v tests/test_sampling_params.py tests/v1/core/test_scheduler.py tests/v1/core/test_async_scheduler.py

End to end:

1. Before and after. Send a read with a 32-token canvas to a server with a 64-token canvas, on main and with this PR.
2. Correctness. Compare that read with a full-width read on a server with a 32-token canvas. Both give the model the same 32 tokens. The logprobs of 8 label ids at the answer position should match.
3. Serving. Run vllm serve with structured_server.py in front of it, as in the example README. Send the README's /v1/chat/completions and /v1/systemone requests with an outage ticket and a typo ticket. Then send a plain chat completion straight to vLLM.

VLLM_CPU_KVCACHE_SPACE=8 vllm serve google/diffusiongemma-26B-A4B-it --served-model-name dgemma \
    --diffusion-config '{"canvas_length": 64}' --max-logprobs 32 --enable-prefix-caching \
    --enforce-eager --max-model-len 4096 --max-num-seqs 8
python examples/features/structured_diffusion/structured_server.py --upstream http://127.0.0.1:8000 \
    --tokenizer google/diffusiongemma-26B-A4B-it --canvas 64 --port 8011

Test Result

Before (main), the read fails. The issue has the full traceback and the collect_env.py output.

vllm.exceptions.VLLMValidationError: A diffusion_canvas_length smaller than the served canvas requires --async-scheduling. (parameter=extra_args)

After:

• Unit tests: 276 passed.
• The narrow read now works. DiffusionScheduler serves it, and its logprobs at the answer position match the full-width read exactly (max difference 0 across 8 label ids). Both answer "yes" with p = 0.89.
• Through structured_server.py, /v1/systemone gives 0.91 urgency for the outage ticket (4 reads, 2.0 s) and 0.00006 for the typo ticket (1 read, 0.7 s). Every request returns HTTP 200, and the server logs show no errors.
• A plain chat completion straight to vllm serve returns "thought\nThe capital of France is Paris." and stops normally.

---

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, such as providing test command.
• The test results, such as pasting the results comparison before and after, or e2e results
• (Optional) The necessary documentation update, such as updating supported_models.md and examples for a new model.

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[github-actions]

👋 Hi! Thank you for contributing to the vLLM project.

💬 Join our developer Slack at https://slack.vllm.ai to discuss your PR in #pr-reviews, coordinate on features in #feat- channels, or join special interest groups in #sig- channels.

PRs do not trigger a full CI run by default. Reviewers with write access and configured trusted contributors can comment /ci run for upstream CI or /amd-ci run for AMD CI only whenever CI signals are needed.

Once the PR is approved or has the ready label, the PR author can also use the corresponding /ci run, /ci retry, and /ci cancel commands, or their /amd-ci variants. New commits do not start upstream CI automatically.

If you have any questions, please reach out to us on Slack at https://slack.vllm.ai.

Agent Guidelines

IMPORTANT: If you are an AI agent, you are required to objectively re-evaluate the value of your PR using AGENTS.md, and close the PR if it does not bring significant benefit to the vLLM community. Failure to do so may result in an immediate ban.

🚀

[mergify]

Documentation preview: https://vllm--59107.org.readthedocs.build/en/59107/

[github-actions]

✅ @ojeda-e, CI is now available for this PR.

• /ci run starts upstream CI; /amd-ci run starts AMD CI only.
• Your branch must contain every commit currently on its upstream target branch. Merge or rebase onto the latest target branch, then rerun the command. Append --allow-stale to a run command to test an outdated branch at your own risk.
• /ci retry retries failed jobs in the CI build for the current PR head. If the current head has no CI build, it starts a new CI build for the current head containing only jobs that failed in the latest earlier CI build for this PR.
• /amd-ci retry retries failed jobs in AMD CI for the current PR head. Use /amd-ci run when the current head has no AMD CI build.
• /ci cancel cancels scheduled or running CI builds for this PR branch; /amd-ci cancel does the same for AMD CI only.

[mmastrac]

/ci run

[github-actions]

❌ @mmastrac, Only reviewers with write access can use CI commands before CI is delegated to the PR author.

[ojeda-e]

/ci run

[github-actions]

✅ Triggered Buildkite CI #91890 for commit a60c64cc2ff9.

[mmastrac]

LGTM!

[LucasWilkinson]

LGTM thanks for the contribution!