执行摘要

• 一句话：修复DP模式迭代索引不同步，增加dummy步日志
• 推荐动作：值得快速合并的小而精的修复。设计上对核心路径（step()）改动极少，将逻辑隔离在日志上下文管理器中，保持了代码整洁。建议后续考虑异常保护，确保索引递增在异常时也能执行。

功能与动机

当启用--enable-logging-iteration-details时，DP模式下未处理真实请求的引擎不输出日志，导致各DP引擎的迭代编号不一致，造成日志分析混乱。PR示例显示DP0迭代90时DP1仍停在45。

实现拆解

1. 修改log_iteration_details签名：将参数类型从SchedulerOutput扩展为SchedulerOutput | None，None表示DP dummy迭代。

2. 处理零token调度：当scheduler_output非None但total_num_scheduled_tokens为0时，直接yield返回，避免与后续dummy包装器重复记录。

3. 处理dummy迭代：在run_busy_loop中，将execute_dummy_batch()调用包装在self.log_iteration_details(None)上下文管理器中，dummy步会以全零指标输出日志并附加(dummy)标记。

4. 供给默认迭代指标：当scheduler_output=None时，使用IterationDetails(0,0,0,0)构造全零指标，同时标记is_dummy=True，在日志末尾追加(dummy)标记。

5. 保持迭代索引递增：无论dummy还是正常步，均执行self._iteration_index += 1，确保所有DP引擎的索引一致前进。

关键文件：

• vllm/v1/engine/core.py（模块 V1引擎；类别 source；类型 core-logic；符号 log_iteration_details）: 唯一的变更文件，修改了日志迭代细节的上下文管理器以支持dummy迭代，并在DP繁忙循环中包装dummy执行调用。

关键符号：log_iteration_details

关键源码片段

vllm/v1/engine/core.py

唯一的变更文件，修改了日志迭代细节的上下文管理器以支持dummy迭代，并在DP繁忙循环中包装dummy执行调用。

@contextmanager
def log_iteration_details(self, scheduler_output: SchedulerOutput | None):
    if not self.vllm_config.observability_config.enable_logging_iteration_details:
        yield
        return
    # 零 token 步骤：让 dummy_batch 包装器记录日志（避免重复记录）
    if scheduler_output and scheduler_output.total_num_scheduled_tokens == 0:
        yield
        return
    self._iteration_index = getattr(self, '_iteration_index', 0)
    # scheduler_output=None 表示 DP dummy 迭代
    if scheduler_output is None:
        iteration_details = IterationDetails(0, 0, 0, 0)
        is_dummy = True
    else:
        iteration_details = compute_iteration_details(scheduler_output)
        is_dummy = False
    before = time.monotonic()
    yield
    logger.info(
        ''.join([
            'Iteration(',
            str(self._iteration_index),
            '): ',
            str(iteration_details.num_ctx_requests),
            ' context requests, ',
            str(iteration_details.num_ctx_tokens),
            ' context tokens, ',
            str(iteration_details.num_generation_requests),
            ' generation requests, ',
            str(iteration_details.num_generation_tokens),
            ' generation tokens, iteration elapsed time: ',
            format((time.monotonic() - before) * 1000, '.2f'),
            ' ms',
            ' (dummy)' if is_dummy else '',
        ])
    )
    self._iteration_index += 1

评论区精华

审核者gemini-code-assist[bot]指出：当scheduler_output存在但调度token数为0时，也应当标记为dummy以防止索引分歧；并且注意到初始实现可能造成_iteration_index的双重递增。njhill建议将核心路径变更最小化，避免在step()流程中添加额外逻辑。作者vadiklyutiy随后重构，将所有处理集中到log_iteration_details内部，仅在run_busy_loop保留一行封装，解决了重复递增问题。另一条关于异常保护的评论（yield后递增应在try...finally中）未被采纳，但当前异常会导致索引停止递增，可能造成后续分歧。

• 零 token 调度也应标记为 dummy 以保持日志一致性 (correctness): 作者通过在 log_iteration_details 开头添加对 zero-token 的早期返回来处理，将该情况视为“已由 dummy wrapper 处理”，但实际并未输出 (dummy) 行。这可能导致调试模糊，但避免了 double-logging。
• 避免核心路径中重复日志和迭代索引双重递增 (correctness): 最终版本只保留一行 with self.log_iteration_details(None)，其余细节都在上下文管理器中处理，实现了最小化核心路径变更。
• yield 内异常导致迭代索引不递增 (correctness): 当前代码未添加异常保护，视为未解决风险。作者未采纳该建议，可能在 merge 后仍然存在。

风险与影响

• 风险：主要风险是当log_iteration_details的yield内抛出异常时，_iteration_index不会递增，可能导致异常DP引擎与正常引擎的迭代索引产生永久偏差。虽然log_iteration_details被设计为异常安全（仅在execute_dummy_batch调用处使用），但若execute_dummy_batch本身抛异常，索引将无法同步。此外，零token调度的情况被静默跳过日志，可能掩盖调度器无效循环的调试信息。
• 影响：仅影响V1引擎在DP模式下并启用--enable-logging-iteration-details的用户。这些用户将看到所有DP引擎输出同步的迭代编号，dummy行清晰标记，便于理解和调试DP分布情况。不开启该日志或非DP模式下无影响。
• 风险标记：异常导致迭代索引永久偏差, 零token调度日志被静默跳过

关联脉络

• 暂无明显关联 PR