执行摘要

• 一句话：修复 Harmony 解析器非终端状态静默丢弃内容
• 推荐动作：值得精读。此 PR 展示了如何优雅地处理解析后端的静默失败：保持 HTTP 协议不变，仅做内容回退和日志记录。设计决策（try/finally、异常传播）以及 reviewer 提出的改进建议（去重警告、删除冗余注释）都是良好的工程实践。建议团队在日常开发中参考这种异常处理模式。

功能与动机

修复 issue #45736，该问题指出 GPT-OSS Harmony 输出在非终端状态（例如 final 通道缺少 <|message|> 分隔符）时 vLLM 返回 HTTP 200、content=null、finish_reason="stop" 且 completion_tokens > 0，静默丢弃生成内容且无任何异常或日志。此 PR 实现 issue 讨论中达成的共识：捕获 HarmonyError，返回原始未解析内容作为 content，保持标准 finish_reason，并记录警告用于可观测性。

实现拆解

1. 修改 vllm/parser/harmony.py 的 flush() 方法：将 contextlib.suppress(HarmonyError) 替换为 try/except/finally。在 except 中输出警告日志并重新抛出异常；在 finally 中始终重置解析器状态，确保下一轮对话不受影响。
2. 修改 parse() 方法与 parse_delta() 方法：对 flush() 调用添加 try/except HarmonyError，捕获后直接返回原始 model_output（非流式）或包含 delta 文本的 DeltaMessage（流式），并在 parse_delta 中重置工具调用索引。
3. 修正测试辅助函数 get_model_output_tokens：将 render_conversation_for_completion 替换为 render_conversation，避免尾部附加的下一轮 <|start|>assistant 标记导致合成流始终非终端。
4. 新增三个测试用例：test_flush_raises_and_resets_on_non_terminal_eos 验证 flush() 抛出异常并重置状态；test_malformed_final_recovers_raw_content（parse 版）验证非终端时返回原始字符串；test_malformed_final_recovers_raw_content（parse_delta 版）验证流式结尾的 fallback。
5. 更新原有 test_flush_resets_after_eos_error 测试用例，适配新的异常抛出行为。

关键文件：

• vllm/parser/harmony.py（模块 解析器；类别 source；类型 core-logic；符号 flush, parse, parse_delta）: 核心变更文件，修改了 flush() 的异常处理逻辑，以及 parse()/parse_delta() 的 fallback 行为。
• tests/parser/test_harmony.py（模块 测试；类别 test；类型 test-coverage；符号 test_flush_raises_and_resets_on_non_terminal_eos, test_malformed_final_recovers_raw_content）: 测试文件，新增三个测试用例覆盖 malformed final 的 flush、parse 和 parse_delta 行为，同时修复了辅助函数以正确生成合成 token 序列。

关键符号：flush, parse, parse_delta

关键源码片段

vllm/parser/harmony.py

核心变更文件，修改了 flush() 的异常处理逻辑，以及 parse()/parse_delta() 的 fallback 行为。

def flush(self) -> Segment | None:
    try:
        self._harmony_parser.process_eos()
        msg = self._poll_completed_message()
    except HarmonyError:
        logger.warning(
            'Harmony parser ended in a non-terminal state; returning the '
            'raw unparsed output. This usually indicates a malformed '
            "assistant turn, e.g. a 'final' channel missing the "
            '<|message|> delimiter.'
        )
        raise # 重新抛出异常，由 parse / parse_delta 捕获并回退
    finally:
        # 重置解析器状态，为下一轮对话做准备
        self._parser = None
        self._num_processed_messages = 0
​
    if msg is None:
        return None
​
    return Segment(
        channel=msg.channel,
        recipient=msg.recipient,
        delta='',
        completed_message=msg,
    )

评论区精华

Review 主要由 yzong-rh 发起，关键讨论点包括：

• 建议用 try/finally 替代存储异常变量的方式，确保 reset 始终执行。
• 建议将 parse() 和 parse_delta() 中的重复警告合并到 flush() 中。

• 建议删除测试中多余的内联注释，因为测试名称已自解释。
  作者全部采纳并修复，最终获得 yzong-rh 的批准，并由 sfeng33 合并。

• 使用 try/finally 替换存储异常的方式 (design): 作者采纳建议，改用 try/finally 结构，将异常处理移至 except 块，parser 状态重置放在 finally 中。

• 合并重复的 logger.warning 至 flush() (style): 作者将警告移至 flush() 的 except 块中，parse() 和 parse_delta() 仅负责捕获并回退，不单独记录警告。
• 删除测试中冗余的内联注释 (style): 作者删除了所有多余的注释，仅保留必要的文档。

风险与影响

• 风险：
  1. 异常传播变更：flush() 之前静默抑制异常，现在会抛出 HarmonyError。当前仅 parse/parse_delta 调用它，但未来新调用方可能遗漏捕获，导致异常扩散到上层。建议通过类型标注和文档明确此行为。
  2. 流式内容不完整：parse_delta() 的 fallback 仅返回当前 delta 文本，之前已发出的 delta 不可挽回。这是设计上的妥协，比静默丢弃好。
  3. 状态重置依赖：finally 中重置了 _parser 和 _num_processed_messages，若其他方法也依赖重置后的状态，需要确保时序正确。
  4. 日志高频触发：如果模型频繁产生 malformed 输出，警告日志可能会大量涌现，但可考虑限频或降级。
     - 影响：直接影响 GPT-OSS 用户，不再因 malformed 输出而丢失答案。影响范围限于 Harmony 解析路径，不涉及推理引擎或其他模块。测试覆盖了新旧行为。团队需注意合并后原有依赖静默抑制的代码可能受影响，但分析表明无其他依赖。
     - 风险标记：异常传播路径变更, 流式尽力回退, 状态重置依赖

关联脉络

• PR #45657 [Bugfix][Frontend] Normalize constrained Harmony recipients: 同一文件 vllm/parser/harmony.py 的修改，涉及 Harmony 解析器约束处理，属于相关修复线。
• PR #47185 [Refactor][GPT-OSS] Harmony Responses API Refactor to use HarmonyParser: 同一模块的重构，合并 HarmonyParser 上下文类并修复流式 bug，与本 PR 的异常处理改进共同完善 Harmony 路径。