【Bug已解决】[WebGPU EP] Meta-Llama-3.1-8B inference crash on QNN environments 解决方案

一、现象长什么样

在启用了 QNN（Qualcomm Neural Network，高通 NPU 执行提供方）的环境里，用 ONNX Runtime 的 WebGPU EP 跑 Meta-Llama-3.1-8B 推理时，进程直接崩溃（segfault / 访问空指针），而不是优雅报错或正常出结果。现象：

# 现象 A：初始化或首步推理时 segfault # SIGSEGV at webgpu_ep_kernel.cc: ptr->Dispatch() —— ptr 为 nullptr # 因为 QNN 环境下某个 WebGPU 资源（如 pipeline / shader module）没创建成功 # 现象 B：只在 WebGPU EP + QNN 环境组合触发 # 纯 WebGPU（非 QNN）正常；纯 QNN（不用 WebGPU EP）正常； # 一旦 WebGPU EP 跑在 QNN 后端之上就崩 # 现象 C：崩在“跨 EP 资源假设”处 # WebGPU EP 假设自己独占 GPU 设备、能创建 compute pipeline， # 但 QNN 环境下 GPU 设备已被 NPU 栈部分占用/抽象，pipeline 创建返回空， # WebGPU EP 没判空直接用 -> 崩

最坑的是现象 A：直接 segfault 没有可捕获的错误信息，且只在特定硬件组合（QNN 高通设备）出现，普通 CI 覆盖不到，用户只能拿 crash dump 反推。

二、背景

ONNX Runtime 支持多个 EP 组合：WebGPU EP（用浏览器/系统的 WebGPU 算力）和 QNN EP（用高通 NPU）。理论上它们可以共存——比如一部分图用 QNN 在 NPU 上跑，一部分用 WebGPU 在 GPU 上跑。但实际中，WebGPU EP 的初始化假设“我能拿到一个有效的 WebGPUGPUDevice并创建所有需要的GPUComputePipeline/GPUShaderModule”。

在 QNN 环境下，系统的图形/计算栈可能被高通驱动做了特殊抽象：WebGPU 的requestAdapter()/createShaderModule()在某些情况下返回null（而非抛异常），或者返回的 device 能力子集与 WebGPU EP 假设不符。WebGPU EP 的代码对“创建结果可能为 null”没有判空，直接用这个 null pipeline 去Dispatch，于是 segfault。

这是多 EP 共存 / 跨后端审查里典型的坑：某 EP 假设自己独占且一定能成功创建底层资源，对“创建返回 null”的异常后端环境没有防御性判空。

三、根因

1. WebGPU 资源创建未判空：createShaderModule/createComputePipeline在 QNN 环境下可能返回nullptr，WebGPU EP 直接解引用 → segfault（现象 A）。

2. 跨 EP 设备假设过强：WebGPU EP 假设自己能独占并完整初始化 GPUDevice，没考虑 QNN 已占用/抽象了部分栈，导致初始化在中间步骤“静默失败但返回非空句柄、内部资源却为 null”。

3. 缺少 QNN 环境的崩溃回归测试：CI 没有“WebGPU EP 跑在 QNN 后端”的组合测试，null 路径从未被触发和防御。

本质：是WebGPU EP 对底层资源创建结果未做防御性判空，且跨 EP 设备假设过强，在 QNN 异常后端下 segfault，且缺组合测试。

四、最小可运行复现

下面用 Python 模拟“WebGPU 资源创建返回 null，EP 未判空直接解引用崩溃”：

class MockWebGpuDevice: def create_compute_pipeline(self, desc): # QNN 环境下返回 None（创建失败但没抛异常） return None def dispatch_buggy(device, shader_desc): """buggy: 不判空直接用 pipeline。""" pipeline = device.create_compute_pipeline(shader_desc) pipeline.dispatch() # ← pipeline 是 None -> AttributeError（类比 segfault） def dispatch_fixed(device, shader_desc): """fixed: 创建失败显式报错，绝不拿 null 去 dispatch。""" pipeline = device.create_compute_pipeline(shader_desc) if pipeline is None: raise RuntimeError( "WebGPU compute pipeline creation failed (likely unsupported " "backend such as QNN); cannot dispatch") pipeline.dispatch() dev = MockWebGpuDevice() try: dispatch_buggy(dev, {}) except AttributeError: print("REPRO A -> segfault equivalent: null pipeline dereferenced") dispatch_fixed(dev, {}) # 优雅报错，不崩

buggy在pipeline.dispatch()处因None报错（类比 C++ segfault），fixed优雅抛错。

五、解决方案（第一层：最小直接修复）

最小修复：WebGPU EP 在所有底层资源创建后判空，为空则抛清晰错误而非解引用：

// 修正：创建 compute pipeline 后判空 auto pipeline = device.CreateComputePipeline(pipeline_desc); if (!pipeline) { return ORT_MAKE_STATUS(ONNXRUNTIME, FAIL, "WebGPU compute pipeline creation failed. This backend may not " "support the required WebGPU features (e.g. running on QNN env)."); } // 只有非空才 dispatch pipeline->Dispatch(workgroup_count);

这一层改动最小：每处创建后加判空 + 清晰报错，segfault 变可捕获错误。但依赖“每处创建都加判空”，下看第二层。

六、解决方案（第二层：结构性改进）

把“WebGPU EP 所有底层资源创建必须判空、失败即优雅报错”固化成单一事实来源。下面这个 dataclass 集中管理资源创建契约，用一个守卫统一处理：

from dataclasses import dataclass, field from typing import Any, Callable, Optional @dataclass class WebGpuLlamaCrashPolicy: """单一事实来源：WebGPU EP 资源创建的判空与失败契约。""" _created: list = field(default_factory=list) def create_or_fail(self, name: str, factory: Callable[[], Any]) -> Any: """统一守卫：创建失败（返回 None）即抛清晰错误，绝不返回 None 给调用方。""" resource = factory() if resource is None: raise RuntimeError( f"WebGPU resource '{name}' creation failed (backend may be " f"unsupported, e.g. QNN env). Aborting before dispatch.") self._created.append(name) return resource def assert_no_null_resource(self, name: str, resource: Any) -> None: if resource is None: raise AssertionError(f"null WebGPU resource '{name}' would crash")

用法：

policy = WebGpuLlamaCrashPolicy() pipeline = policy.create_or_fail( "llama_attention_pipeline", lambda: device.create_compute_pipeline(desc)) # 返回 None 时直接报错

这一层的关键收益：

• 统一判空：所有资源创建走create_or_fail，不可能返回 None 给 dispatch；
• 清晰错误：失败时说明“可能是 QNN 等不支持的后端”，便于定位；
• 单一事实来源：所有 WebGPU 资源创建约定收口在WebGpuLlamaCrashPolicy。

七、解决方案（第三层：断言 / CI 守护）

把第二层钉成 pytest，挂进 CI，覆盖 QNN 式 null 创建路径：

import pytest from your_package.webgpu_llama_crash import WebGpuLlamaCrashPolicy def test_null_pipeline_raises(): # 断言 1：创建返回 None 必须优雅报错，不崩 p = WebGpuLlamaCrashPolicy() with pytest.raises(RuntimeError): p.create_or_fail("pipeline", lambda: None) def test_valid_pipeline_returns(): # 断言 2：创建成功返回资源，不报错 p = WebGpuLlamaCrashPolicy() res = p.create_or_fail("pipeline", lambda: object()) assert res is not None def test_no_null_dispatched(): # 断言 3：任何 null 资源都不允许进入 dispatch（assert 守卫） p = WebGpuLlamaCrashPolicy() with pytest.raises(AssertionError): p.assert_no_null_resource("shader", None) def test_qnn_env_clean_abort(): # 断言 4：模拟 QNN 环境（多资源创建失败），首处失败即中止，不 segfault p = WebGpuLlamaCrashPolicy() calls = {"n": 0} def factory(): calls["n"] += 1 return None # 模拟 QNN 下所有创建都失败 with pytest.raises(RuntimeError): p.create_or_fail("p0", factory) # 第一个就失败，不会继续 dispatch assert calls["n"] == 1

四条断言从“null 报错”“有效返回”“不 dispatch null”“QNN 干净中止”四面把 segfault 回归钉死在 CI。

八、排查清单

WebGPU EP 在 QNN/特殊后端上 segfault 时：

1. crash 在pipeline->Dispatch()或 shader 解引用？几乎肯定是创建返回了 null 没判空（现象 A）。
2. 是否只在“WebGPU EP + 某特殊后端”组合触发？是就确认该后端下createXxx返回 null 而非抛异常。
3. 所有底层资源创建是否都判空？没判空的都会在异常后端下 segfault。
4. 用第二层WebGpuLlamaCrashPolicy：统一create_or_fail守卫，失败即优雅报错。
5. 加第三层 pytest，断言“null 报错、有效返回、不 dispatch null、QNN 干净中止”。
6. 多 EP 共存时，每个 EP 都必须防御“后端部分不可用”，不能假设独占成功。

九、小结

WebGPU EP 在 QNN 环境跑 Llama-3.1-8B 的崩溃 bug 本质是WebGPU EP 假设底层资源（compute pipeline / shader module）一定能创建成功，对异常后端（QNN）下返回null的创建结果没有防御性判空，直接解引用去Dispatch导致 segfault；且 CI 没有“WebGPU EP + QNN”组合测试，null 路径从未防御。修复分三层——第一层所有资源创建后判空、为空抛清晰错误；第二层用WebGpuLlamaCrashPolicy这个 dataclass 把“创建判空 + 失败优雅报错”收口成统一守卫；第三层用四条 pytest 把“null 报错、有效返回、不 dispatch null、QNN 干净中止”钉死在 CI。核心心法：任何 EP 对底层资源的创建结果都必须判空，异常后端下创建可能返回 null 而非抛异常，未判空即 segfault。