[Bugfix] Reject non-positive values for ParallelConfig int knobs

[jwzheng96]

Summary

Adds Pydantic lower-bound constraints to the parallelism-size knobs in
ParallelConfig so that obviously invalid values (zero, negative) fail
fast at construction time instead of producing nonsensical world_size
or surfacing as opaque errors later in torch.distributed.

Problem

vllm/config/parallel.py declares the parallelism size fields as bare
int = 1 with no validation:

pipeline_parallel_size: int = 1
tensor_parallel_size: int = 1
prefill_context_parallel_size: int = 1
data_parallel_size: int = 1
data_parallel_size_local: int = 1
...
nnodes: int = 1
...
decode_context_parallel_size: int = 1

This means:

• ParallelConfig(tensor_parallel_size=0) yields world_size = 0
  (computed at vllm/config/parallel.py:774-778 as the product of
  pp × tp × prefill_cp). The downstream guard
  device_count() < self.world_size is silently bypassed.
• ParallelConfig(pipeline_parallel_size=-1) yields a negative
  world_size, which eventually flows into
  torch.distributed.init_process_group(world_size=-1) — a confusing
  failure far from the user's actual misconfiguration.
• ParallelConfig(decode_context_parallel_size=0) triggers
  ZeroDivisionError at vllm/config/parallel.py:485
  (tp % decode_context_parallel_size) rather than a clear user error.

The same file already uses Field(default=..., gt=0) and
Field(default=..., ge=0) for EPLBConfig (lines 59-77), so the
pattern is already accepted in this codebase.

Fix

• Six size knobs whose only meaningful values are >= 1 get
  Field(default=1, ge=1):
  pipeline_parallel_size, tensor_parallel_size,
  prefill_context_parallel_size, data_parallel_size, nnodes,
  decode_context_parallel_size.
• data_parallel_size_local uses Field(default=1, ge=0). The 0
  value is a sentinel used by the engine-args layer to signal that
  data parallelism was specified externally
  (vllm/config/parallel.py:__post_init__:
  if self.data_parallel_size > 1 or self.data_parallel_size_local == 0).
  Tightening to ge=1 would break this path; tightening to ge=0
  still rejects all negative values, which is the actual bug surface.
• ubatch_size, dbo_decode_token_threshold, and
  dbo_prefill_token_threshold get Field(default=..., ge=0). 0 is
  the documented disabled state for ubatch_size (the activation check
  at line 508 is self.ubatch_size > 1); negative thresholds for the
  dbo knobs would make num_tokens >= threshold in
  vllm/v1/worker/ubatch_utils.py permanently true and silently force
  microbatching on every request.
• max_parallel_loading_workers gets Field(default=None, ge=1). The
  field is currently no-op'd with a warning (vllm/config/parallel.py,
  if self.max_parallel_loading_workers is not None: logger.warning(... not supported and will be ignored)), but constraining it now avoids
  accepting nonsense values like 0 or -1 when it is re-enabled.

Related Issues

No directly matching open issue. Surface area is small enough that a tracking issue feels unnecessary.

Duplicate-work check

$ gh pr list --repo vllm-project/vllm --state open \
    --search "ParallelConfig Field validation"
$ gh pr list --repo vllm-project/vllm --state open \
    --search "tensor_parallel_size validation OR pipeline_parallel_size validation"

No competing PR found. PR #43792 touches the renderer (different
config) and #43154 plumbs shutdown-timeout into the multiproc executor
(adjacent area but unrelated).

Test plan

No new tests are added — the change is a one-line-per-field Pydantic
Field(ge=...) constraint whose behavior is exercised exhaustively by
Pydantic upstream, and the same file already uses this pattern in
EPLBConfig (lines 59-77). Verified locally with an isolated Pydantic
smoke test that mirrors the new field declarations:

• All six ge=1 fields reject 0 and a negative integer.

• data_parallel_size_local rejects negatives but still accepts the
  0 sentinel used by ParallelConfig.__post_init__.

• A positive composition (tp=2, pp=2, prefill_cp=1) still builds and
  produces world_size == 4.

• Pure-Python change, no kernel/C++ touched

• Default values unchanged → no behavior change for valid configs

• DCO sign-off included

AI assistance disclosure

This PR was prepared with AI assistance (Claude). I have reviewed every changed line. Commit trailer includes Co-authored-by: Claude.

[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. Once the PR is approved and ready to go, your PR reviewer(s) can run CI to test the changes comprehensively before merging.

To run CI, PR reviewers can either: Add ready label to the PR or enable auto-merge.

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.

🚀

[hclsys]

nice — same lane as #44042 (admission-rejection) + reuses the EPLBConfig precedent in the same file. one adjacent: data_parallel_rank: int = 0 (and data_parallel_rank_local / node_rank) are also bare int with no lower bound, and a negative rank is just as nonsensical as a zero size. intentional skip (because rank gets overwritten by init_process_group and you didn't want false-positive rejections on a -1 sentinel)? if so worth a one-line doc comment so future readers don't add ge=0 and break something subtle.

[jwzheng96]

Good catch — I had skipped the rank fields because I wasn't sure if any used a negative sentinel. After re-checking:

• data_parallel_rank and node_rank have no such sentinel, so added Field(default=0, ge=0) to both. data_parallel_rank is also runtime-checked at __post_init__ (0 <= rank < data_parallel_size); the Pydantic constraint just moves the lower-bound check earlier.
• data_parallel_rank_local does use -1 as a sentinel — vllm/envs.py has VLLM_DP_RANK_LOCAL: int = -1 and __post_init__ assigns that env value directly to the field in the offline SPMD path. Left unconstrained and added an inline doc comment so future readers don't add ge=0 and break that path.

Pushed in d1cd0162d.

[yewentao256]

Thanks for the work!

[yewentao256]

LGTM, thanks for the work!