执行摘要

• 一句话：用 ValueError 替换数据并行 assert，增加 node_rank 下界检查
• 推荐动作：值得精读，展示了如何通过统一的错误前缀和可操作的纠正建议改善用户体验。设计决策（如一致性错误格式）值得在其他验证路径中推广。

功能与动机

替换数据并行启动组合断言为普通的 ValueError，使用一致前缀、相关 CLI 标志和值以及纠正行动。同时验证 --node-rank 的下界。

实现拆解

1. 统一错误信息格式：将原本的 assert 语句改为 if ... raise ValueError(...)，所有错误消息以 "Invalid data-parallel launch options:" 开头，并直接指出冲突的 CLI 选项（如 --data-parallel-hybrid-lb 和 --data-parallel-external-lb），同时给出可操作的纠正建议。
2. 增加 node_rank 下界验证：原来只检查 node_rank < nnodes，现在增加 node_rank >= 0 的检查，确保范围在 [0, nnodes-1] 内。
3. 改进 world_size 整除性校验：将 assert world_size % nnodes == 0 替换为 ValueError，并提示用户调整哪些相关参数。
4. 完善 external_lb 相关校验：当 data_parallel_rank 为 None 时，给出详细的设置方法；当 data_parallel_size_local 不合法时，明确提示应设为 1 或忽略。
5. 移除冗余测试：根据 reviewer 建议，删除了新增的独立单元测试，因为改动极小无需单独测试。

关键文件：

• vllm/engine/arg_utils.py（模块 配置验证；类别 source；类型 core-logic；符号 create_engine_config）: 唯一变更文件，实现了所有验证改进。

关键符号：create_engine_config

关键源码片段

vllm/engine/arg_utils.py

唯一变更文件，实现了所有验证改进。

# vllm/engine/arg_utils.py - create_engine_config 中的验证改进
​
def create_engine_config(self, ...) -> EngineConfig:
    # ... 前置代码 ...
​
    # 验证混合 LB 与外部 LB 不能同时启用
    if self.data_parallel_hybrid_lb and self.data_parallel_external_lb:
        raise ValueError(
            "Invalid data-parallel launch options: "
            "`--data-parallel-hybrid-lb` and "
            "`--data-parallel-external-lb` cannot be enabled together. "
            "Enable only one load-balancing mode."
        )
​
    # 多节点时必须使用 MP 后端
    if self.nnodes > 1 and self.data_parallel_backend != "mp":
        raise ValueError(
            "Invalid data-parallel launch options: "
            f"`--nnodes {self.nnodes}` requires "
            "`--data-parallel-backend mp`; got "
            f"`--data-parallel-backend {self.data_parallel_backend}`. "
            "Use the MP backend or set `--nnodes 1`."
        )
​
    inferred_data_parallel_rank = 0
    if self.nnodes > 1:
        world_size = (
            self.data_parallel_size
            * self.pipeline_parallel_size
            * self.tensor_parallel_size
        )
        world_size_within_dp = (
            self.pipeline_parallel_size * self.tensor_parallel_size
        )
        # 验证 nnodes 必须能整除 world_size
        if world_size % self.nnodes != 0:
            raise ValueError(
                "Invalid data-parallel launch options: "
                f"`--nnodes {self.nnodes}` must evenly divide the total "
                f"world size ({world_size}). Adjust `--nnodes`, "
                "`--data-parallel-size`, `--pipeline-parallel-size`, or "
                "`--tensor-parallel-size`."
            )
        # 验证 node_rank 在有效范围内（0 到 nnodes-1）
        if not 0 <= self.node_rank < self.nnodes:
            raise ValueError(
                "Invalid data-parallel launch options: `--node-rank` must "
                f"be between 0 and {self.nnodes - 1}; got "
                f"`--node-rank {self.node_rank}`. Set it to this node's "
                "zero-based index."
            )
        # ... 其余 world_size 计算与推断 ...
​
    # 外部 LB 需要 data_parallel_rank
    if data_parallel_external_lb:
        if self.data_parallel_rank is None:
            raise ValueError(
                "Invalid data-parallel launch options: "
                "`--data-parallel-external-lb` requires a data-parallel "
                "rank. Set `--data-parallel-rank`, or set "
                "`--data-parallel-size` greater than 1 and use `--nnodes` "
                "with `--node-rank` so the rank can be inferred."
            )
        if self.data_parallel_size_local not in (1, None):
            raise ValueError(
                "Invalid data-parallel launch options: "
                "an external data-parallel rank requires "
                "`--data-parallel-size-local 1`; got "
                f"{self.data_parallel_size_local}. Set it to 1 or omit it."
            )
    # ... 后续代码 ...

评论区精华

1. 测试必要性讨论：yewentao256 建议删除新增的单元测试（test_invalid_data_parallel_launch_options），认为小改动不需要单独测试。作者采纳，测试被移除。
2. 文档改进建议：hmellor 建议改进 config 字段的 docstring，使用户更少遇到这些错误。目前未在本次 PR 中执行，但可以作为后续改进方向。

• 删除新增单元测试 (testing): 作者采纳，删除了测试。
• 改进配置字段 docstring (documentation): 认可但未在本 PR 中执行，可作为后续改进。

风险与影响

• 风险：仅修改配置验证路径，不影响运行时核心逻辑。将 assert 替换为 ValueError 在 Python 优化模式（-O）下更安全（assert 会被跳过）。风险极低。
• 影响：用户影响：获得更清晰、可操作的错误信息；系统影响：无性能或行为变化；团队影响：维护成本低，后续类似验证可遵循此模式。
• 风险标记：低风险, 仅配置路径

关联脉络

• PR #49134 [Bugfix] Reject contradictory custom-op directives: 同样将 assert 替换为 ValueError，改善用户体验，方法类似。