执行摘要

• 一句话：修复 Harmony 解析器在 xgrammar 下中止 token 处理
• 推荐动作：值得精读，尤其是理解 Harmony 解析器与 xgrammar 的集成方式，以及测试如何模拟生产路径。

功能与动机

修复 xgrammar 结构化输出时，Harmony 解析器因 stop token 处理不当导致的 500 错误和无限生成问题。Issue #51693 中报告了此错误，bbrowning 确认此修复解决了该问题。

实现拆解

1. 更新 Harmony 解析器：在 vllm/parser/harmony.py 中，将 _END_TAG 列表从 ["<|end|>", "<|call|>", ""] 简化为 ["<|end|>", ""]，移除 <|call|>，因为 #50595 落地后不再需要，且 xgrammar 在约束下不允许 stop token。
2. 更新测试：在 tests/parser/test_harmony.py 中，引入 GenerationConfig、VllmConfig、XgrammarBackend 等依赖，新增 gpt_oss_stop_token_ids 和 xgrammar_backend fixture，并将 _assert_structured_outputs_admission 改为使用真实的 xgrammar 后端编译 grammar，通过 encode_output 和 validate_tokens 验证 token 序列，而非旧的 _is_grammar_accept_string。
3. 调整测试用例：更新 test_adjust_request 等测试，传递新 fixture，确保测试覆盖真实生产路径。

关键文件：

• vllm/parser/harmony.py（模块 解析器；类别 source；类型 core-logic；符号 _END_TAG）: 核心逻辑修改，移除 <|call|> 并简化 _END_TAG，影响 Harmony 解析器的停止 token 处理。
• tests/parser/test_harmony.py（模块 测试；类别 test；类型 test-coverage；符号 gpt_oss_stop_token_ids, xgrammar_backend, _assert_structured_outputs_admission, test_adjust_request）: 测试更新，改用真实 xgrammar 后端，覆盖生产路径。

关键符号：_normalize_recipient, adjust_request, _assert_structured_outputs_admission

关键源码片段

tests/parser/test_harmony.py

测试更新，改用真实 xgrammar 后端，覆盖生产路径。

# tests/parser/test_harmony.py
# 新增 fixture 获取真实模型的 stop token IDs，并构造 xgrammar 后端实例。
@pytest.fixture(scope="module")
def gpt_oss_stop_token_ids() -> set[int]:
    eos_token_id = GenerationConfig.from_pretrained(REASONING_MODEL_NAME).eos_token_id
    if isinstance(eos_token_id, int):
        return {eos_token_id}
    return set(eos_token_id)
​
@pytest.fixture(scope="module")
def xgrammar_backend(gpt_oss_tokenizer) -> XgrammarBackend:
    vllm_config = VllmConfig(
        structured_outputs_config=StructuredOutputsConfig(backend="xgrammar")
    )
    return XgrammarBackend(
        vllm_config,
        tokenizer=gpt_oss_tokenizer,
        vocab_size=len(gpt_oss_tokenizer),
    )
​
# 将语法编译改为使用真实 xgrammar 后端，并传入 stop_token_ids。
# 使用 encode_output 和 validate_tokens 模拟生产路径的 token 验证。
grammar = xgrammar_backend.compile_grammar(
    StructuredOutputOptions.STRUCTURAL_TAG,
    structured_outputs.structural_tag,
    stop_token_ids=stop_token_ids,
)
tokens = encode_output(getattr(cls, sample_name))
accepted = grammar.validate_tokens(tokens)
admitted = accepted == tokens

评论区精华

• 关于其他后端支持：bbrowning 询问是否其他 grammar 后端也会遇到相同问题，yzong-rh 确认只有 xgrammar 使用 stop_token_ids，其他后端（如 guidance）需要单独修复，且上游可能也需要支持。

• 确认修复：bbrowning 确认该修复解决了 #51693 的 500 错误。

  • 其他 grammar 后端是否支持 stop_token_ids (design): yzong-rh 承认其他后端（如 guidance）也需要单独修复，且部分后端不支持 per-request eos_token 覆盖，留下许多 TODO。
  • 修复是否解决具体 issue (question): 确认修复有效。

风险与影响

• 风险：主要风险在于移除 <|call|> 可能影响 Harmony 解析器对 tool call 结束符的处理，但测试覆盖了相关场景。此外，xgrammar 后端依赖 stop_token_ids，但其他后端不支持，可能导致功能不一致。测试中 encode_output 和 validate_tokens 的替换可能影响断言准确性，但已通过本地测试验证。
• 影响：影响 xgrammar 结构化输出用户，特别是使用 Harmony 模型的用户，修复了 500 错误和无限生成问题。对系统性能无显著影响，但测试逻辑调整可能影响 CI 稳定性。
• 风险标记：核心路径变更, 其他后端未覆盖, 测试逻辑调整

关联脉络

• PR #49227 [Bugfix][Structured Output] Mask request stop tokens in xgrammar: 该 PR 是 #49227 的重基并移除遗留补丁，功能上依赖其合并。
• PR #51693 Issue: 500 error with Inkling model: 该 PR 修复了此 issue 中报告的 xgrammar 相关错误。