ImportError: No module named ‘xgrammar’

快速结论：这个报错通常出现在 s390x（IBM Z / LinuxONE）等没有 xgrammar 预编译 wheel 的平台上，vLLM 启动阶段在导入 xgrammar 相关模块时直接抛出 ImportError: No module named 'xgrammar'。优先排查 xgrammar 是否按平台要求正确安装（s390x 需要从源码构建），而不是先改代码绕过导入。

适用环境：已确认信息：s390x（IBM Z / LinuxONE），vLLM 0.28.0，Python 3.11，RHEL / UBI 9，加速器为 IBM Spyre（非 CUDA）。Issue 正文报告 xgrammar 未安装且无 s390x wheel；维护者则在评论中说明 xgrammar 在 s390x 上是硬依赖，可由 sdist 构建。其他平台、CUDA 版本、PyTorch 版本未在 Issue 中明确。

最快修复方案：暂无确认的一步修复方案。Issue 讨论表明该问题不算 vLLM 缺陷，而是 s390x 上 xgrammar 未安装导致；可行的方向是准备 C++ 工具链、从 sdist 构建并安装 xgrammar（含其构建依赖），或使用官方 s390x 镜像。若确实无法在该平台安装 xgrammar，可优先尝试让导入路径变为延迟失败（见解决步骤），但这属于 Issue 中的修复方向，最终以合并状态为准。

注意事项：导入守卫（try/except 或 PlaceholderModule）只是把报错从启动时推迟到实际使用结构化输出时，并不能让缺少 xgrammar 的平台真正支持 xgrammar 后端；且评论指出 backend_xgrammar.py 之外，vllm/parser/harmony.py 与 vllm/tool_parsers/structural_tag_registry.py 也存在无条件导入，单独修一处不充分。自行打补丁存在与后续版本冲突的风险。

问题场景

在 s390x（IBM Z / LinuxONE）上使用 vLLM 0.28.0，仅执行 from vllm import LLM 或启动 vllm serve 时，进程在模型加载之前就崩溃，即使工作负载完全不涉及结构化输出。报错源于结构化输出相关模块对 xgrammar 的导入。此外，OpenAI server 入口也会拉取这些模块，因此 vllm serve 同样受影响。

报错原文

ImportError: No module named 'xgrammar'
  File "vllm/v1/structured_output/backend_xgrammar.py", line N, in <module>
    import xgrammar as xgr

原因分析

最可能的原因是目标平台（s390x）上缺少 xgrammar，而 vLLM 的部分模块在导入阶段就会触发对 xgrammar 的引用，导致启动即失败。Issue 正文最初定位在 vllm/v1/structured_output/backend_xgrammar.py 的无条件导入；但评论中的复现给出了更完整的链路：backend_xgrammar.py 已经是延迟加载，真正首先硬导入的是 vllm/parser/harmony.py（from xgrammar import StructuralTag），它经由 vllm/v1/structured_output/__init__.py 到 vllm.parser 被拉入，vllm/tool_parsers/structural_tag_registry.py 也有同样的无条件导入。维护者则认为这不是 vLLM 缺陷：xgrammar 在 s390x 上是硬依赖，requirements/common.txt 中带有 s390x 标记，官方 s390x 镜像从 sdist 构建并安装它，平台缺少 wheel 属于常见情况（类似 torchvision、numba、llvmlite）。

环境排查

确认平台是否为 s390x（IBM Z / LinuxONE）、操作系统与镜像版本（Issue 为 RHEL / UBI 9）。
确认 vLLM 版本（Issue 为 0.28.0）与 Python 版本（3.11）。
确认 xgrammar 是否已安装，以及安装方式：是 wheel 还是 sdist 源码构建。
确认是否具备 C++ 工具链，能否构建 xgrammar 及其构建依赖 apache-tvm-ffi。
确认加速器环境：Issue 中为 IBM Spyre（非 CUDA），需注意这与 CUDA 平台排查路径不同。
若使用了 xgrammar 的 stub 包作为临时绕过手段，需确认其 __file__ 属性是否有效。

解决步骤

先确认报错链路与平台：在 s390x 环境中执行 python -c "import xgrammar"，若同样报 ImportError: No module named 'xgrammar'，说明是平台缺少该依赖，而非 vLLM 单独问题。
按维护者说明，优先在 s390x 上通过 sdist 方式安装 xgrammar（requirements/common.txt 对该平台有显式标记），并同步准备好 apache-tvm-ffi 的构建环境，即需要完整的 C++ 工具链；可参考官方 s390x 镜像 docker/Dockerfile.s390x 的构建方式。
如果无法在该平台安装 xgrammar，可优先尝试 Issue 中提出的代码级做法：对相关导入加 try/except ImportError 守卫，并在用户实际请求 xgrammar 结构化输出后端时再抛出明确错误；评论中提到用 PlaceholderModule 替代导入、让报错延迟到首次使用，并补充 tests/standalone_tests/lazy_imports.py 与子进程回归测试，同时需要覆盖 vllm/parser/harmony.py 和 vllm/tool_parsers/structural_tag_registry.py 两个模块，仅修 backend_xgrammar.py 不充分。
如需临时让进程能启动，Issue 正文给出的现有变通方法是安装一个最小的 xgrammar stub 包，并带上有效的 __file__ 属性以通过导入检查；这只是绕过，不具备实际结构化输出能力。
关注并核对相关修复的合并状态：Issue 讨论提到 #56561 修复了 backend_xgrammar.py 中的 dataclass 注解触发点，并且有分支在做两个 parser 模块的延迟失败改造，最终以实际发布/合并结果为准。

验证方法

在目标 s390x 环境中执行 python -c "from vllm import LLM" 以及 python -c "import vllm.entrypoints.openai.api_server"，若在未安装 xgrammar 的情况下不再抛出导入错误，说明导入路径已被正确解耦（若走的是延迟失败方案，实际调用 xgrammar 结构化输出后端时应收到清晰的 RuntimeError）。若走的是安装 xgrammar 的方案，则 python -c "import xgrammar" 应能成功，并且 vLLM 可正常启动与提供服务。