Intel GPU 的 ComfyUI 系统优化指南

面向普通 Intel GPU 用户：让 ComfyUI 在 Intel Arc 显卡上更快、更稳的完整方案。 本指南配套同目录下的安装文件包使用，版本：20260912

📌 本版本更新说明（20260912）：

• ⚠️ 本版为 torch 2.14 栈 / B 系列（BMG）和 A770(dg2) 双线，请区分不同的文件夹。
• A770(dg2) 线内容已补齐（社区 fork，Blackwood416）：内核 omni_xpu_kernel-0.2.0b1+torch214.dg2.3-cp313-cp313-win_amd64.whl（版本号是 b1，B 系列为 b2，号小不代表装错）+ ComfyUI-OmniXPU.A770(dg2)-20260912.zip。A770 没有单独的 aimdo / kitchen 包——与 B 系列共用包根目录的同一份 provider。 相关章节：2.1 / 3.1 / 6.9。
• ⚠️ A770 跑 MiniMax H3 必须设 UR_L0_USE_IMMEDIATE_COMMANDLISTS=1——否则第一个采样步的第 3 个 attention stage 即报 UR_RESULT_ERROR_DEVICE_LOST（详见 3.1）。该变量只影响 Windows DG2。
• comfy-aimdo XPU：改用 provider 架构（本版最大变化）——不再用 deploy.bat 覆盖官方 comfy_aimdo 包，改为独立发行 comfy-aimdo-xpu-runtime（本包根目录 comfy_aimdo_xpu_runtime-0.5.3-cp39-abi3-win_amd64.whl），与官方 comfy-aimdo 精确配对、互不覆盖，安装方式改为 pip。详见第三部分第 6 节（含前置条件表与排错对照表）。
• 配套内核升级到 ComfyUI 0.35.0：kitchen 的"版本三角"随之抬到 0.2.33——ComfyUI requirements.txt 固定官方 comfy-kitchen==0.2.33，本包 provider 的版本锚同步为 ["0.2.33"]。
• omni_xpu_kernel：0.2.0b2+torch214.bmg 同版本号重建——同步上游 intel/llm-scaler#696（xiangyuT，Omni: Upgrade ComfyUI to v0.35.0）：新增原生 Sol attention CUTE 全套实现（sol_attn_{carriers,coarse,pooled,routes,token}.hpp、sol_attn_mainloop.hpp、sol_attn_prepare.cpp、sol_attn_torch.cpp，以及 cute/sol_attn_v2.py）。本版 pyd 已重编：cute_fmha_torch.pyd 由 4.6MB 增至 7.3MB。
• ComfyUI-OmniXPU：20260908 → 20260912 新版（ComfyUI-OmniXPU.bmg-20260912.zip）——新增 sparse_attention（改写上游 block-sparse 资格判定，认 kitchen 原生 XPU API）与 quantized_matmul（把 kitchen 原生 INT8 格式暴露给 ComfyUI 模型资格检查）两个 adapter；runtime_bootstrap / config / patches / h3_rms_modulation 同步更新。
• comfy-kitchen XPU provider：0.2.31 → 0.2.33（fork revision 9a46ea7）——接入内核 cute.sol_attn_v2 sidecar，sol_attn 算子纳入 kitchen 分发。
• ComfyUI-GGUF-XPU：20260905 → 20260912——loader.py 的 IMG_ARCH_LIST 补入 krea2（Krea2 GGUF 图像架构识别）。
• ComfyUI-SolAttn：沿用 20260901 版（无变化）；仅 B 系列可用，A770 不适用。
• 📄 文档新增：第六部分增加 6.2 节《provider 的「双锚」》——解释"升级 ComfyUI 后 XPU 加速还在、但变慢了"这个高频现象，附自检命令与判读规则（另：Sol-Attn 章节补充了与 ComfyUI-SolAttn_triton 抢注册的警告，见第三部分第 4 节）。
• 📄 A770 章节新增：本版补入 A770 线内容——UR_L0_USE_IMMEDIATE_COMMANDLISTS=1（H3 硬性要求，见 3.1）、ESIMD 路由判据表（3.1）、A770 专属开关表与 SeedVR2 结论（6.9）、A770 实测数据（第五部分）、以及 6.5 的两线 adapter 对照。
• 🧰 新增工具：check_provider_alignment.py（包根目录）——一条命令体检"ComfyUI pin ↔ 官方包 ↔ provider 锚 ↔ torch"是否对齐，有问题时直接给出建议动作。建议每次升级 ComfyUI / git pull 之后跑一次。

---

目录

• 第一部分：背景说明
• 第二部分：优化思路
• 第三部分：安装
• 第四部分：验证与故障排查
• 第五部分：实测数据与 FAQ
• 第六部分：内核升级后的组件检查与恢复
• 附录：文件清单对照

---

第一部分：背景说明

为什么 Intel GPU 在 ComfyUI 下又慢又"不稳"

问题	根因
慢	ComfyUI 的算子生态长期以 CUDA（NVIDIA）为中心，Intel 显卡只能走 PyTorch 通用路径（eager 逐算子执行），量化模型（GGUF/INT8/FP8）的解包、反量化大量在 CPU 或通用实现上完成
更慢	Intel GPU 没有成熟的"算子分发层"——装了量化模型也没有原生 kernel 可调，全部回退到慢速路径
不稳	消费级卡显存小（12–16GB）+ Windows WDDM 驱动调度开销大，大模型贴满显存时 OOM、卡死、花屏频发
生态	torch.xpu（PyTorch 的 Intel GPU 后端）是后起之秀，周边配套（手写 kernel 库、显存管理）远不如 CUDA 成熟

一句话：Intel GPU 的瓶颈不在硬件，而在"软件生态没跟上"——量化算子和显存管理缺两条腿。

Intel llm-scaler-omni 的价值和问题

价值：官方为 ComfyUI 打造的 XPU 优化套件

Intel 官方仓库 intel/llm-scaler 的 omni 系列，把"两条腿"补上了： 地址：https://github.com/intel/llm-scaler/tree/main/omni

组件	作用
omni_xpu_kernel	计算方：SYCL/ESIMD 手写内核库——norm（RMSNorm/LayerNorm）、rotary、INT8 FFN、FP8 GEMM、GGUF 解包、SVDQuant INT4，量化加速的唯一计算终点
comfy-kitchen XPU fork	分发壳（零计算）：QuantizedTensor 解包 + registry 选路，把量化算子（GGUF/rope/convrot…）路由到 omni_xpu_kernel 原生 kernel
ComfyUI-OmniXPU	接线方：启动自动 patch ComfyUI 的模型层，adapter 让 norm/FP8/INT8-FFN/attention 等普通张量路径直连 kernel（不经 kitchen）；无需改工作流
comfy-aimdo XPU	DynamicVRAM 显存管理：按需换页（VBAR fault）、权重驱逐，防 OOM（20260912 起为 provider 架构，独立发行 comfy-aimdo-xpu-runtime）

官方验证面：Arc Pro B70/B60 专业卡。

问题：官方套件的三个受限点

1. 专注 B 系列（BMG 架构）：官方内核只编译 bmg 目标（B580/B60/B70），A 系列（A770 等 DG2 架构）原版不支持——需社区手搓内核（见安装 2.1）。社区的 dg2 内核不只是"能跑"：它额外带了 DG2 SDP 注意力侧车（ESIMD/DPAS 路线；B 系列走的是 CUTE）与一批 A770 实测调优，所以 A770 与 B 系列在注意力引擎、adapter 集上都是两条独立路线（对照见 6.9）
2. 优选专业卡：官方文档以 B60/B70 为基准验证，消费级 B580 部分场景（显存贴满）需要额外处理
3. Windows 支持度有限：官方 Windows 便携版只验证到 torch 2.12；torch 2.13/2.14 均需本地适配编译（本包已为你编译好）；组件版本联动、升级后互相覆盖，维护门槛高

---

第二部分：优化思路

提速：量化算子加速链路（终点：omni_xpu_kernel 原生 kernel）

核心：所有量化加速的计算终结点都是 omni_xpu_kernel 原生 kernel（SYCL/ESIMD）；comfy-kitchen 不实现任何计算，只充当"分发壳"。

量化算子（INT8/GGUF/rope/convrot/SVDQuant…）有两条到达 kernel 的路径，取决于权重以什么形式参与计算：

优化前: 量化算子 → eager 通用路径（CPU/慢速实现）

路径① QuantizedTensor 承载（int8_tensorwise/convrot/GGUF/svdquant…）
量化算子 → comfy-kitchen(xpu backend) 分发壳 → omni_xpu_kernel 原生 kernel

路径② 普通张量承载（OmniXPU adapter patch：norm/FP8/INT8-FFN/attention）
模型计算 → 直连 omni_xpu_kernel 原生 kernel（不经 kitchen）

为什么路径① 必须经过分发壳（不能直接"量化算子 → kernel"）：

量化权重以 QuantizedTensor（comfy-kitchen 定义的数据结构）承载，
scale/zero_point/group 等量化元数据封装在内部；
omni_xpu_kernel 的算子只认原始 tensor（x / weight / weight_scale / bias），
不认识 QuantizedTensor 对象
→ kitchen 层负责：解包元数据 + registry 按 capability 约束（dtype/形状）选 backend
→ 约束不匹配时回落 eager（CPU 慢路径）

补充：xpu backend 是纯薄壳——backends/xpu/rope.py 整个文件靠一句 from omni_xpu_kernel import rotary；int8_linear 非编译路径直接 return _int8.int8_linear(...)（_int8 = omni_xpu_kernel.int8）。零计算、零重写，实际算的 100% 是 omni_xpu_kernel。

三个组件边界一目了然：

omni_xpu_kernel    = 计算方 —— SYCL/ESIMD 内核（norm/rotary/int8/fp8/gguf/svdquant）
comfy-kitchen(xpu) = 分发壳 —— QuantizedTensor 解包 + registry 选路，零计算
ComfyUI-OmniXPU    = 接线方 —— 启动自动 patch 模型层；adapter 直连路径的发起者

实测效果（Arc B580，Krea2 GGUF Q4_0，8 步）：

配置	每步耗时	提升
不优化（KJNodes 加载）	4.00 s/it	—
三件套（UnetLoaderGGUF 加载）	2.50 s/it	快 37.5%

稳定：comfy-aimdo XPU（DynamicVRAM）

原理：显存贴满时，把不活跃的模型权重"换页"到系统内存（VBAR fault/驱逐），需要时再调回，避免 OOM。

⚠️ 20260912 起更换为 provider 架构：XPU 实现不再覆盖官方 comfy_aimdo 包，而是作为独立发行 comfy-aimdo-xpu-runtime 与官方包精确配对。好处是升级 ComfyUI 不再互相覆盖；代价是版本必须严格对齐（provider 内部写死了可接受的官方版本）。

→ 安装方式、前置条件与排错见第三部分第 6 节。

---

第三部分：安装

0. 不熟悉命令行？让 AI 助手帮你装

如果你不想手动执行命令、改配置文件，最简单的方式：

把本文件夹（含本指南和全部安装包）直接交给一个 AI 助手（如 WorkBuddy / 其他支持读取本地文件的 agent），对它说："请阅读《Intel GPU 的 ComfyUI 系统优化指南-20260912.md》，按我的显卡（A770 或 B 系列）帮我完成安装、配置和验证。"

AI 助手会替你完成以下全部工作：

• 读取本指南 + 检查你的环境（显卡型号、torch 版本、ComfyUI 版本）
• 安装对应的 kernel wheel（按 A/B 系列选对版本）
• 部署 OmniXPU 节点 / GGUF-XPU 节点到 custom_nodes\
• 修改启动 bat 的环境变量（按你的显卡选对一组）
• 按第四部分的清单验证是否生效
• 跑一次 check_provider_alignment.py，确认三个组件版本对齐

💡 前提：AI 助手需要能访问本机文件（WorkBuddy 等桌面助手支持）。装完如有报错，直接把错误日志贴给助手即可。

1. 环境要求

项	要求
显卡	B 系列：Arc B580 / B60 / B70（BMG 架构） A 系列：Arc A770 （DG2 架构）
操作系统	Windows 10/11 64 位
Python	3.13
PyTorch	2.14.0+xpu（ComfyUI XPU版本自带）
ComfyUI	0.35.0+
显卡驱动	Intel Arc 最新驱动
oneAPI	仅编译需要；运行时不需要（本包 wheel 已编译好）

先确认环境（命令行执行）：

python -c "import torch; print(torch.__version__, torch.xpu.is_available())"
:: 应输出: 2.14.0+xpu True

2. omni_xpu_kernel 安装

内核 wheel 按显卡系列区分，选你对应的那个，不要混装。

⚠️ 官方版本内核也支持 Panther Lake H, 新一代酷睿 Ultra 200 系列集显，但必须在集显环境下编译才可使用，不能直接用下方内容

2.1 A770 显卡安装（社区 fork，dg2）

A 系列官方原版不支持，使用社区维护者 Blackwood416 的 dg2 内核。同架构 A750 可能会报错。

🔄 后续升级：从这个项目找更新包 → https://github.com/Blackwood416/omni-xpu-kernel

安装文件（本包 A770(dg2)/ 目录）：

omni_xpu_kernel-0.2.0b1+torch214.dg2.3-cp313-cp313-win_amd64.whl
SHA256: DD3466A4175E19501741DABD914E05402062922EE8823784039701A61A0CB92A

安装方法：

python -m pip install omni_xpu_kernel-0.2.0b1+torch214.dg2.3-cp313-cp313-win_amd64.whl

⚠️ 这个 wheel 只认 Python 3.13 + PyTorch 2.14.0+xpu + DG2（Arc A770）。 PyTorch 2.13 与 2.14 的 C++ ABI 不兼容，2.13 用户必须留在 0.2.0b1+torch213.dg2.2，不能装本版。

版本号提示：A770 线是 0.2.0b1（dg2 目标），B 系列线是 0.2.0b2（bmg 目标）——两条线版本号不同步，不要看到号小以为装错了。dg2 目标另有 a770 / arc-a770 别名。

一个容易踩的坑（缺 pi_level_zero.dll）：A770 wheel 运行时导入 sycl9.dll、dnnl.dll、torch_xpu.dll、c10_xpu.dll。torch 的 XPU pip 包会自动拉齐 SYCL / Unified Runtime 全家（intel-sycl-rt、intel-cmplr-lib-ur…），但一个残缺的 oneAPI 安装如果缺 pi_level_zero.dll，_C 会加载失败。ComfyUI 便携版环境已满足这一条，不需要单独装 oneAPI。

2.2 B 系列显卡安装（官方支持，bmg）

说明：bmg wheel 覆盖整个 BMG 系列（B580/B60/B70），内核运行时自动识别显卡型号。

🔄 后续升级：B 系列官方内核来自 llm-scaler-omni 项目 → https://github.com/intel/llm-scaler/tree/main/omni/omni_xpu_kernel

• 安装文件（本包 B系列(bmg)/ 目录）：

omni_xpu_kernel-0.2.0b2+torch214.bmg-cp313-cp313-win_amd64.whl

• 安装方法：

text python -m pip install omni_xpu_kernel-0.2.0b2+torch214.bmg-cp313-cp313-win_amd64.whl

3. ComfyUI-OmniXPU 安装

3.1 A770 用户

🔄 A770 节点后续升级：从这个项目找更新包 → https://github.com/Blackwood416/ComfyUI-OmniXPU

安装

解压 A770(dg2)/ 目录内的 ComfyUI-OmniXPU.A770(dg2)-20260912.zip 到 ComfyUI\custom_nodes\（解压后即得 ComfyUI-OmniXPU 文件夹）
重启 ComfyUI 后自动加载（日志出现 [OmniXPU] 即成功）。

A770 的启动文件（bat）相关设置

在启动 bat 的 python main.py ... 之前加入环境变量：

:: OMNIXPU加速相关（A770 / dg2）

:: ① MiniMax H3 必设：不设会在第 3 个 attention stage 报 DEVICE_LOST
set UR_L0_USE_IMMEDIATE_COMMANDLISTS=1

:: ② 注意力后端：保持注释即为默认 torch（不 patch，最稳）
::    A770 的 ESIMD/DPAS 侧车需显式开启；auto 永不自动选 ESIMD
::    仅建议 D128 长序列 / H3 类负载开启（实测判据见下方表格）
:: set OMNI_ATTN_BACKEND=esimd

💡 不需要写 OMNIXPU_ENABLE=1 / OMNIXPU_ATTENTION=1——这些适配器默认就是开的，写 =1 是空操作（只有 =0 才有意义，用于关闭）。A770 的完整开关表见 6.9。

要不要开 ESIMD？先看判据（A770 实测，D=128 / FP16 / H=32，驱动 32.0.101.8860）：

形状 / 场景	谁更快	实测（ESIMD vs PyTorch SDPA）
D128，q_len == 2048 或 ≥ 4096	ESIMD	L2048 2.75 vs 3.29 ms · L4096 8.8 vs 12.6 ms · L8192 34.7 vs 41.4 ms
D128，q_len ∈ [1024,2048) 或 (2048,4096)	torch	ESIMD 慢 1.1–1.6×
D64 形状（如 FP16/D64）	torch	ESIMD 只有 0.57–0.92×
H3 大形状 (1,20683,56,128) BF16	ESIMD	405–410 vs 431–451 ms

判据已经写进 adapter：ESIMD 不赢的契约会自动回退 PyTorch SDPA，所以开了不会崩，但也拿不到收益。想省心就保持默认（不开）；主跑 H3 / D128 长序列再开。

3.2 B 系列用户

🔄 B 系列节点后续升级：官方节点来自 llm-scaler-omni 项目 → https://github.com/intel/llm-scaler/tree/main/omni/ComfyUI-OmniXPU

安装

解压 B系列(bmg)/ComfyUI-OmniXPU.bmg-20260912.zip 到 ComfyUI\custom_nodes\（解压后即得 ComfyUI-OmniXPU 文件夹）
重启 ComfyUI 后自动加载（日志出现 [OmniXPU] 即成功）。

B 系列启动文件（bat）相关设置

在启动 bat 的 python main.py ... 之前加入环境变量（按你的显卡选一组）：

:: OMNIXPU加速相关（B系列 / bmg）
set OMNIXPU_ENABLE=1
set OMNIXPU_DEBUG=0

:: 注意力后端：默认 CUTE FMHA（b2 内核起支持，长序列自注意力更快，
::   d128/H3/Wan 形状自动命中，其余自动回退 torch SDPA）
set OMNI_ATTN_BACKEND=cute

:: 手动强制回退 PyTorch SDPA（仅故障排查 / A/B 对比 / 低版本内核时用）：
:: set OMNI_ATTN_BACKEND=torch

3.3 通用启动文件思路（可选）：bat 自动判定显卡，走对应分支

上面 A770 与 B 系列是两套手动变量（B 系列 cute；A770 默认 torch、要提速再开 esimd），分享或换机时容易配错。更省心的做法是把它合并成一份通用启动 bat：启动开头先检测显卡型号，按结果自动设置对应的一组变量，一套文件通吃：

• 判定方式：bat 里调 PowerShell 读显卡型号（WMI Win32_VideoController），按名称特征分流——Arc B5xx（如 B580）→ bmg；Arc A3xx–A7xx（如 A770）→ dg2；两者都不匹配（核显 / 其他 / 未知）→ 兜底。
• 各分支动作：bmg → 设上面 B 系列那组（OMNI_ATTN_BACKEND=cute 等）；dg2 → 设 UR_L0_USE_IMMEDIATE_COMMANDLISTS=1（ESIMD 按需再开）；兜底 → 保留 UR_L0_USE_IMMEDIATE_COMMANDLISTS=1（无 Level Zero 设备时被忽略，无副作用）、不设 OMNI_ATTN_BACKEND（即保持默认 torch SDPA、不打 attention 补丁，最保守、不会出错）。
• 效果：A770 / B 系列 / 其他显卡用户拿到同一份 bat 都能直接跑，无需手工改型号；检测不到时自动走兜底而不是报错；想固定某档也可手动指定、跳过检测。
• 提示：完整实现代码段较长，需要时可按此思路自行扩展启动 bat（或参考维护者发布的示例 bat 中的 GPU 分支段）。

4. ComfyUI-SolAttn 安装（选装，仅 B 系列用户）

🔄 后续升级：从这个项目找更新包 → https://github.com/xiangyuT/ComfyUI-SolAttn_xpu

⚠️ 仅限 B 系列（BMG）：Sol-Attn 稀疏注意力依赖内核的 cute.sol_attn 算子，A770（DG2）不支持（A770 用户请跳过本小节）。

Sol-Attn 是什么：训练无关的稀疏注意力（arXiv 2607.24027，NVlabs Sana 团队）——只计算部分 token 对，加速长序列自注意力（高分辨率生图 / 长视频 / H3 等）。不匹配的注意力形状自动回退 dense（安全）。

安装
解压 B系列(bmg)/ComfyUI-SolAttn-20260901.zip 到 ComfyUI\custom_nodes\（解压后即得 ComfyUI-SolAttn 文件夹）
重启 ComfyUI 后节点列表出现 Patch Sol-Attn 即成功。

⚠️ 不要同时安装 ComfyUI-SolAttn_triton（上游 CUDA 版）：两个插件都向 ComfyUI 注册同名的 sol_attn attention 函数，而 ComfyUI 的注册表是先到先得——后注册的只打一行 already registered, skipping registration 警告就被跳过。最终生效的是哪一个取决于插件加载顺序，等于把行为交给运气；而且 triton 版在 Windows 上本来就跑不了（它的 triton 内核需要 C++ 编译器，且 kitchen 的 triton 后端在 Windows 默认禁用）。

→ 如果你以前装过 ComfyUI-SolAttn_triton，把它整个文件夹移出 custom_nodes\（或改名加 .disabled 后缀）即可，只保留本包提供的 XPU 版。

B 系列启动文件（bat）相关设置——配合内核 cute.sol_attn，需启用实验开关：

:: Sol-Attn 实验路径（装了 ComfyUI-SolAttn 插件才需要）
set SOL_ATTN_XPU_EXPERIMENTAL=1

使用：工作流里在模型加载器后添加 Patch Sol-Attn 节点（参数：start_percent / end_percent 控制稀疏区间，头尾保留 dense 保画质；tau 控制稀疏激进程度，先小值起步对比画质）。

前提（缺一不可）：内核 0.2.0b2+torch214.bmg（含 sol_attn）+ SOL_ATTN_XPU_EXPERIMENTAL=1 + OMNI_ATTN_BACKEND=cute（CUTE 路由）+ 注意力形状匹配（BF16 BTHD D128）。

5. ComfyUI Kitchen XPU 安装（选装；provider 架构）

🔄 后续升级：从这个项目找更新包 → https://github.com/xiangyuT/comfy-kitchen-xpu

⚠️ provider 架构说明：kitchen 走 xiangyuT provider 架构——官方 comfy-kitchen 由 ComfyUI requirements.txt 自动安装（官方 PyPI 版，不含 xpu 后端），XPU 实现打包为独立 provider 发行 comfy_kitchen_xpu_runtime，由 ComfyUI-OmniXPU 启动时（prestartup）按契约路由激活。不再互相覆盖，与 ComfyUI 依赖管理兼容。

⚠️ 本版（20260912）为 0.2.33，必须配 ComfyUI 0.35.0：ComfyUI 的 requirements.txt 固定官方 comfy-kitchen==0.2.33，provider 内部写死了可接受的版本（compatible_versions: ["0.2.33"]）。三方必须同时对齐：ComfyUI 的 pin ↔ 官方包版本 ↔ provider 锚。若你的 ComfyUI 低于 0.35.0（官方包还是 0.2.31），请勿使用本 provider，否则会在启动日志看到 compatible_versions 不匹配的拒绝提示（见第四部分）。

kitchen 不分显卡系列，provider wheel 一个通用（在本包根目录，A770 与 B 系列共用同一份，A770 没有单独的 kitchen 包）；官方 comfy-kitchen 由 ComfyUI 自动装好，无需手动处理。

💡 A770 说明：A770 的社区节点不装本 provider 也能跑——它的 kitchen_compat 适配器自带一层"缺后端桥"；装上本 provider 后，该桥会检测到已有 Kitchen XPU 后端并自动跳过自身注册（走正式分发层）。所以对 A770 而言，装它是推荐、但非强制。

安装方法（装 provider wheel）

python -m pip install comfy_kitchen_xpu_runtime-0.2.33-py3-none-any.whl

生效前提：ComfyUI-OmniXPU 为 20260912 版（含 runtime_bootstrap.py，本包已带）+ 官方 comfy-kitchen 0.2.33（ComfyUI 0.35.0 自动装好）；安装后 重启 ComfyUI，启动日志出现 provider active（bootstrap 路由）即生效。

💡 本版 kitchen provider 起，sol_attn（内核 CUTE sidecar）也纳入 kitchen 分发——即 Sol-Attn 的能力可以在 kitchen 这一层被调度。

ComfyUI 内核升级后还会失效吗？——不会自动跟随，但也不会崩

provider 架构下官方版与 XPU provider 各司其职，升级 ComfyUI 内核不会把 provider 冲掉；但 ComfyUI 抬高了 comfy-kitchen 的 pin 时，版本三角会被打破：provider 的版本锚不匹配 → 启动日志打印明确拒绝 → XPU 路由回落 PyTorch 慢路径（不崩，只是变慢）。此时需要安装与新官方包版本对齐的新 provider（联系包提供者）。

若升级后发现 xpu 路由未生效：确认 provider 已装（pip show comfy-kitchen-xpu-runtime）+ 官方包版本与 provider 锚一致 + OmniXPU 为 20260912+ 版 + 重启 ComfyUI。

不安装 ComfyUI Kitchen XPU 的损失

路径	没有 kitchen 时
norm（RMSNorm/LayerNorm）	✅ 不受影响（OmniXPU 直连内核）
FP8 GEMM / INT8 FFN	✅ 不受影响（直连）
GGUF 解包（Q4_0/Q8_0）	❌ 回落 eager，丢失 ~37% 的加速
rms_rope / convrot 等通用量化算子	❌ 回落 eager

结论：只跑 FP16/FP8 模型可不装；跑 GGUF 量化模型收益最大（~37%），但需接受"每次内核升级要重新合并/patch/安装"的维护成本——收益与成本请自行权衡。

6. comfy-aimdo XPU 安装（选装）

🔄 后续升级：从这个项目找更新包 → https://github.com/xiangyuT/comfy-aimdo-xpu/

⚠️ 20260912 起改用 provider 架构：不再用 deploy.bat 覆盖官方 comfy_aimdo 包——XPU 实现改为独立发行 comfy-aimdo-xpu-runtime，与官方 comfy-aimdo 精确配对、各司其职：官方包由 pip 管理，XPU provider 常驻 site-packages，互不覆盖。旧的"解压 zip + 双击 deploy.bat"装法作废。

安装文件（本包根目录）：comfy_aimdo_xpu_runtime-0.5.3-cp39-abi3-win_amd64.whl

包名含义：0.5.3 = provider 版本 · torch2.14 = 必须配 torch 2.14.0+xpu · xpu = Intel XPU（不锁机型）· 20260912 = 打包日期。

安装方法

python -m pip install --force-reinstall --no-deps comfy_aimdo_xpu_runtime-0.5.3-cp39-abi3-win_amd64.whl

两个参数都不能省：

• --force-reinstall：provider 的版本号与官方包同为 0.5.3，普通 pip install -U 会以为"已是最新"而什么都不做；
• --no-deps：provider 的 METADATA 里没有依赖声明，加它避免 pip 去动别的包。

关于 wheel 名里的 cp39-abi3：abi3 是下限声明（最低 Python 3.9），不是"只能装 3.9"。它按稳定 ABI 打标，pip 允许装在任意 ≥3.9 的 CPython 上（3.13 也行）。本包用 CPython 3.13 构建并实测通过；wheel 内没有任何 .pyd，唯一二进制是运行时用 ctypes 加载的 aimdo_xpu.dll，与 CPython 版本无关。

前置条件（缺一即被拒，或被静默跳过）

#	前置	具体要求	缺了会怎样
1	ComfyUI-OmniXPU 插件	版本已认识 comfy_aimdo.xpu 这个 provider 契约（本包 20260912 版即满足）	装了等于没装，而且不报错
2	官方 comfy-aimdo	版本精确等于 0.5.3	启动打印 is incompatible，provider 被拒
3	PyTorch	官方 XPU wheel，精确 2.14.0+xpu	打印 does not match provider，被拒
4	显卡驱动 + VC++ 运行库	系统目录有 ze_loader.dll（显卡驱动带）与 MSVCP140.dll（VC++ 2015-2022 运行库）	aimdo_xpu.dll 加载失败
5	启动参数	启动 bat 的 python 那行显式加 --enable-dynamic-vram	provider 被标成 skipped，静默退回旧路径

关于第 2 条（重要）：不要用 pip install -U comfy-aimdo，也不要用别人给的任意版本。官方包和 provider 是精确配对的：provider 内部写死了 compatible_versions: ["0.5.3"]，多一个小版本号都会被拒（拒绝是"响亮"的，会打印原因并退回纯官方包，不会半残运行）。ComfyUI 0.35.0 的 requirements.txt 里就是 comfy-aimdo==0.5.3，升级内核时会自动装好。

关于第 3 条：包名里的 torch2.14 就是这一条——名字对不上就别装。核对：

python -c "import torch; print(torch.__version__)"
:: 期望输出: 2.14.0+xpu

关于 oneAPI：本包不需要完整 oneAPI（6~7GB）。aimdo_xpu.dll 需要 sycl9.dll 和 libmmd.dll 两个运行库——它们随 torch 的 XPU wheel 一起装到 python\Library\bin\，provider 会自己把这个目录加进 DLL 搜索路径。所以只要 torch 是 XPU 版，这一条就自动满足了。

关于显卡型号：本包不锁机型。aimdo_xpu.dll 编译时没有指定 SYCL AOT 目标，落成的是通用 SPIR-V（spir64），运行时按你机器上的实际设备 JIT——所以 DG2（A770 一类）与 BMG（B580 / B70 一类）用的是同一份二进制，换卡不需要换包。已实测环境：B580 + Win11。

💡 A770 用户的命名提示：社区（Blackwood）在自己的说明里把 A770 侧的 aimdo provider 写作 comfy-aimdo-xpu 0.5.3+xpu.1。其中的 +xpu.1 只是他自己的本地构建编号，与包根目录的 comfy_aimdo_xpu_runtime-0.5.3-cp39-abi3-win_amd64.whl 是同一个包——A770 没有单独的 aimdo 包，直接用本包这一份即可。

开启与关闭

操作	方法
开启	启动 bat 的 python main.py 参数中加 --enable-dynamic-vram
关闭	改成 --disable-dynamic-vram（保留其他参数）

provider 读的是"显式给了这个参数"这一件事本身，它不会去用 ComfyUI 自己那套 enables_dynamic_vram() 的推导逻辑。所以即使你的配置看起来"本来就开着 DynamicVRAM"，也必须显式加上。

验证（启动前自检，30 秒）

python -c "import importlib.metadata as m;v=m.version('comfy-aimdo');print(v,'-> OK' if v=='0.5.3' else '-> MISMATCH')"
:: 期望: 0.5.3 -> OK

再检查宿主插件是否认识这个 provider（在 ComfyUI 根目录下执行）：

python -c "import sys; sys.path.insert(0,'ComfyUI/custom_nodes/ComfyUI-OmniXPU'); import runtime_bootstrap as b; print('contract registered :', 'comfy_aimdo.xpu' in b._PROVIDER_CONTRACTS); ps, errs = b.discover_providers(); print('comfy_aimdo.xpu accepted :', 'comfy_aimdo.xpu' in ps); [print('rejected ->', e) for e in errs]"
:: 期望: contract registered : True / comfy_aimdo.xpu accepted : True

如果你另外装了 comfy-kitchen 的 XPU provider，这里可能还会多出一行 rejected -> comfy_kitchen.xpu: ... is incompatible。那是另一个包的版本问题，不影响 aimdo，可以忽略——它也正说明这套机制是"不匹配就明确拒绝"，而不是悄悄失效。

启动日志判据

日志里应该出现下面这些行（前两条是 XPU 独占的，官方 CUDA / ROCm 版不会打）：

native Torch XPU allocator retained; arbitrating Unified Runtime USM allocations
arbitrating Unified Runtime USM allocations; PyTorch caching allocator retained

再配合 ComfyUI 自己的：

DynamicVRAM support detected and enabled

⚠️ 不要用 WDDM adapter match 当判据 —— 官方 CUDA / ROCm 的 DLL 也会打这句。

出问题时的对照表

日志 / 报错	真实原因
runtime provider rejected: comfy_aimdo.xpu: official comfy-aimdo 0.5.x is incompatible; provider accepts ['0.5.3']	官方包版本不是 0.5.3（被别的 pip 操作升级/降级过）
PyTorch '2.13.0+xpu' does not match provider '2.14.0+xpu'	torch 版本和本包不配对
... is not installed	官方 comfy-aimdo 根本没装
什么都没报，但也没有 DynamicVRAM support detected	① 启动 bat 没加 --enable-dynamic-vram；② 没装 ComfyUI-OmniXPU 插件；③ site-packages 里官方包被改脏
Error loading aimdo_xpu.dll / 找不到指定的模块	缺 sycl9.dll（torch 不是 XPU 版）或 ze_loader.dll / MSVCP140.dll（驱动 / VC++ 运行库）
source repository is not the registered contract	宿主的 provider 契约和本包来源仓库不一致，说明插件版本不匹配

出现"被拒"时不用慌：这套机制是响亮失败——provider 会被跳过，ComfyUI 照常能启动，只是没有 XPU 加速。修好上面那一条再重启即可。

旧版残留不需要清理：如果你以前装过旧版 aimdo xpu（那种"把 py 和 dll 直接覆盖进 site-packages"的装法），官方包升级后，旧版多出来的 aimdo_xpu.dll、*.bak 之类会继续留在 site-packages 里。这些残留不影响本 provider 工作——它们既不参与模块加载，也被 provider 自己的 _vendor/ 目录挡在解析顺序后面。不需要手工删任何东西。

卸载

python -m pip uninstall comfy-aimdo-xpu-runtime

官方 comfy-aimdo 包不会被影响（它们是两个独立的 distribution），ComfyUI 会回到纯官方路径继续跑。

7. ComfyUI-GGUF-XPU 安装（选装，GGUF 用户强烈建议）

🔄 后续升级：从这个项目找更新包 → https://github.com/analytics-zoo/ComfyUI-GGUF-XPU

GGUF 模型（Q4_0/Q8_0 等）想走 kernel 加速，加载器必须用 ComfyUI-GGUF-XPU 的 UnetLoaderGGUF 节点（走 kitchen → omni_xpu_kernel.gguf）。实测比普通加载方式快 ~37%。

安装文件的下载与部署

• 安装文件（本包根目录）：ComfyUI-GGUF-XPU-20260912.zip
• 本版（20260912）变更：loader.py 的 IMG_ARCH_LIST 补入 krea2——Krea2 的 GGUF 图像模型不再被当成未知架构处理（沿用 20260905 版起含的 Qwen3-VL 视觉塔加载补丁，Krea2 工作流加载 GGUF 版 Qwen3-VL CLIP 必需）
• 安装方法：解压到 ComfyUI\custom_nodes\（解压后即得 ComfyUI-GGUF-XPU 文件夹），重启 ComfyUI

重要提醒：与官方原版 ComfyUI-GGUF 不冲突

两个插件都注册同名节点 UnetLoaderGGUF，同时安装时谁生效取决于加载顺序（字母序靠后的覆盖靠前的）。

---

第四部分：验证与故障排查

验证清单（按顺序）

① 内核就位：

python -c "import omni_xpu_kernel as o; print(o.__version__, o.__xpu_target__, o.is_available())"
:: B 系列期望: 0.2.0b2+torch214.bmg bmg True
:: A770 期望:   0.2.0b1+torch214.dg2.3 dg2 True

② kitchen xpu provider 生效：

python -m pip show comfy-kitchen-xpu-runtime   :: 有输出 = provider 已装

• 重启 ComfyUI，启动日志出现 provider active / bootstrap 路由行 = XPU 路由已激活
• ⚠️ xpu backend 由 OmniXPU prestartup 挂载：独立 python 下 import comfy_kitchen 看到的是官方版（无 xpu），属正常，勿按旧版方式独立验证

③ 节点生效（重启 ComfyUI 后看启动日志）：

B 系列（bmg）——本版新增 quantized_matmul_adapter 与 sparse_attention_adapter 两行：

[OmniXPU] omni_xpu_kernel 0.2.0b2+torch214.bmg - available: sdp, norm, rotary, linear_fp8, int8, layout
[OmniXPU] quantized_matmul_adapter: applied
[OmniXPU] sparse_attention_adapter: applied
[OmniXPU] attention[cute]: rebound 58 by-value imports across sys.modules
[OmniXPU] norm_adapter: applied
[OmniXPU] fp8_model_adapter: applied
[OmniXPU] int8_ffn_adapter: applied
[OmniXPU] norm: patched MiniMax H3 segmented RMS modulation
[OmniXPU] h3_rms_modulation_adapter: applied
ComfyUI-GGUF: Comfy Kitchen GGUF routing available
Found comfy_kitchen backend xpu: {'available': True, 'disabled': False, ... 'capabilities': [..., 'sol_attn', ...]}

A770（dg2）——社区 fork 是另一套 adapter，不会出现上面那两个新增 adapter：

[OmniXPU] omni_xpu_kernel 0.2.0b1+torch214.dg2.3 - available: sdp, norm, rotary, linear_fp8, int8, layout
[OmniXPU] attention_adapter: applied
[OmniXPU] rotary_adapter: applied
[OmniXPU] a770_rms_rope_bridge: applied          ← A770 专属：RMS-RoPE 融合桥
[OmniXPU] norm_adapter: applied
[OmniXPU] fp8_model_adapter: applied
[OmniXPU] int8_ffn_adapter: applied
[OmniXPU] int4_gemm_adapter: applied             ← A770 专属
[OmniXPU] dynamic_vram_boundary_trim: applied
[OmniXPU] a770_kitchen_compat: applied           ← A770 缺后端桥（装了 kitchen provider 时会变成 skipped）
[OmniXPU] a770_int8_native_gate: applied         ← A770 专属
[OmniXPU] sdp_cache_lifecycle: applied
[OmniXPU] legacy_interpolate_fix: skipped (disabled by env)
[OmniXPU] legacy_median_fix: skipped (disabled by env)
ComfyUI-GGUF: Comfy Kitchen GGUF routing available
Found comfy_kitchen backend xpu: {'available': True, 'disabled': False, ...}

带 a770_ 前缀的三条（a770_rms_rope_bridge / a770_kitchen_compat / a770_int8_native_gate）是 A770 专属兼容桥，B 系列不会有。种子/大视频相关的 seedvr_*、large_video_preprocess_adapter、lora_memory_adapter 两条线都有，此处省略。

Found comfy_kitchen backend xpu 里 available: True 是路由生效的铁证（若版本三角不匹配，这里会是 available: False 且附带 unavailable_reason）。注意 A770 的 capabilities 里没有 sol_attn（DG2 不支持），这是正常的，不是故障。

④ 工作流实测：GGUF 模型请用 UnetLoaderGGUF 节点（不要用 GGUFLoaderKJ——不走内核加速），对比速度应有明显提升。

常见问题表

症状	原因	解决
pip install 报错版本不匹配	wheel 与 torch/Python 不匹配	确认 torch 2.14.0+xpu、Python 3.13
kitchen xpu 路由没生效	provider 未装 / 官方包版本与锚不一致 / 未重启	装本包 provider wheel + 确认 ComfyUI 0.35.0（官方 kitchen 0.2.33）+ 重启
启动日志 comfy_kitchen backend xpu: available False	版本三角不匹配（ComfyUI pin ↔ 官方包 ↔ provider 锚）	三者对齐到 0.2.33；旧 ComfyUI 请勿使用本版 provider
节点没加载（无 [OmniXPU] 日志）	解压目录名不对/有 __pycache__ 残留	确认目录名为 ComfyUI-OmniXPU，删除 __pycache__
GGUF 没加速	用了 GGUFLoaderKJ 节点	改用 UnetLoaderGGUF
aimdo 装了但没生效（无 XPU 独占日志行）	启动 bat 没显式加 --enable-dynamic-vram	见第三部分第 6 节前置条件表
runtime provider rejected: comfy_aimdo.xpu ... is incompatible	官方 comfy-aimdo 不是 0.5.3	对齐官方包版本（ComfyUI 0.35.0 自带 0.5.3）
开启 aimdo 后卡死/极慢	aimdo 仍在演进，个别工作流可能有回归	关闭 aimdo（把 --enable-dynamic-vram 改成 --disable-dynamic-vram）并反馈日志
运行时报 DLL 加载错误	oneAPI 运行时缺失（罕见）	确认 torch 环境自带 sycl9.dll（python\Library\bin）
启动日志出现 Attention function sol_attn already registered	同时装了 ComfyUI-SolAttn 与 ComfyUI-SolAttn_triton	移出 triton 版，只保留 XPU 版（见第三部分第 4 节）
A770 跑 H3 报 UR_RESULT_ERROR_DEVICE_LOST	没设 UR_L0_USE_IMMEDIATE_COMMANDLISTS=1	bat 里补上该变量（见 3.1）
A770 装了 dg2.3 但 _C 加载失败	残缺的 oneAPI 安装缺 pi_level_zero.dll	确认 torch 为 XPU 版（其 pip 包会拉齐 Unified Runtime）；见 2.1
A770 装了 0.2.0b2 却报 target 不符	A770 只有 0.2.0b1 的 dg2 线，b2 是 B 系列的	换装 A770(dg2) 目录里的 dg2.3 包（见 2.1）
A770 开了 ESIMD 反而更慢	形状不在 ESIMD 的胜出区间（D64 / D128 中段）	按 3.1 判据表决定；或直接保持默认不开

ComfyUI 内核升级后的标准动作（重要）

每次升级 ComfyUI 内核后，按顺序执行：

1. 检查 kitchen：启动日志里 comfy_kitchen backend xpu 是否 available: True → 没有就对齐版本三角并重装 provider wheel（第 5 节）
2. 检查 aimdo：pip show comfy-aimdo 版本是否仍与 provider 锚一致 → 不一致就装对应的新 provider
3. 检查 torch：版本变了 → 内核 wheel 需要重新编译（联系包提供者）
4. 检查节点：[OmniXPU] 日志的 adapter 是否 still applied

---

第五部分：实测数据与 FAQ

实测数据（Arc B580 / Windows；提速数据基于 torch 2.13 栈测得，torch 2.14 栈待复测）

工作流	优化前	优化后	提升
Krea2 GGUF Q4_0（8 步）	4.00 s/it	2.50 s/it	+37.5%
Lumina2 GGUF 混合量化	—	1.21 s/it	正常水平
Flux2 Klein FP8	—	3.16 s/it	fp8_gemm 生效

实测数据（Arc A770 16GB / Windows / torch 2.14.0+xpu）

环境：驱动 32.0.101.8860 · oneAPI 2026.1 · 内核 0.2.0b1+torch214.dg2.3 · 稳定的单步采样时间

工作流	规格	单步耗时
Z-Image Turbo	1024²，8 步	0.91–0.93 s
Krea2 Turbo + LoRA	1024²，8 步，strength 0.8	1.64–1.68 s
MiniMax H3 + LoRA	864×480，124 帧，8 步	26.3–26.7 s

⚠️ H3 这一行必须在设了 UR_L0_USE_IMMEDIATE_COMMANDLISTS=1 的前提下才成立（不设会在第一个采样步崩，见 3.1）。A770 的注意力算子级实测（ESIMD vs PyTorch SDPA）见 3.1 的判据表。

FAQ

Q1：A 系列（A770）和 B 系列（B580/B70）区别？ A：架构不同（DG2 vs BMG），内核 wheel 不通用，注意力引擎也不同——A770 走 ESIMD/DPAS 侧车，B 系列走 CUTE（对照见 6.9）。B系列(bmg)/ 与 A770(dg2)/ 都已随本包提供，各自用对应的 wheel 与节点 zip。kitchen / aimdo provider 两线共用同一份——A770 没有单独的 aimdo / kitchen 包。

Q2：需要安装 oneAPI 吗？ A：不需要。oneAPI 只是编译内核时的工具；运行时的 DLL 依赖（sycl9 等）由 torch 2.14 环境自带。前提是 torch 必须是 2.14.0+xpu（与内核 wheel、aimdo provider 配对）。

Q3：kitchen 和 OmniXPU 是重复的吗？ A：不是。OmniXPU 负责"接进 ComfyUI"（patch 模型层），kitchen 负责"算子分发"（路由到内核）。两者配合才完整；GGUF 加速主要靠 kitchen。

Q4：aimdo 为什么单独一个 provider 包？ A：官方 comfy-aimdo 只做 CUDA/ROCm 等后端，Intel XPU 的实现由社区 fork 维护，且必须与官方包精确配对（provider 内部写死了可接受的官方版本）。打包成独立 provider 后：官方包由 pip 正常管理、XPU provider 常驻 site-packages，升级 ComfyUI 不再互相覆盖。不匹配时是"响亮失败"（明确拒绝 + 退回纯官方路径），不会半残运行。

Q5：Sol-Attn 是什么？支持哪些工作流？ A：训练无关的稀疏注意力（arXiv 2607.24027，NVlabs Sana 团队）——只计算部分 token 对，加速长序列自注意力。不限于 H3/Wan：任何 D128 长序列生图工作流（Flux / Qwen-Image / Sana / 高分辨率 DiT）都能挂 Patch Sol-Attn 试，不匹配的注意力形状自动回退 dense（安全无副作用）。

Q6：Sol-Attn 只有 B 系列能用？A770 行吗？ A：仅限 B 系列（BMG）。内核 cute.sol_attn 是 BMG 专属（编译目标 bmg-g31），A770（DG2）不支持——CUTE 注意力全家（d128/H3 VAE/Wan cross/sol_attn）在 A 系列上都没有，A770 请用社区 A 系列内核（Blackwood416 fork，DPAS 融合算子路线）。

Q7：CUTE 不是只支持 Linux 吗？Windows 怎么也有了？ A：原本是——PR#659 之前 Windows 编译直接拒编 CUTE（setup.py raise）。PR#659（2026-09-01 合并）起 Windows 正式支持 CUTE + Sol-Attn（b2 内核），但仅验证 BMG 目标。Windows 上默认仍走 torch SDPA，须设 OMNI_ATTN_BACKEND=cute 才启用 CUTE 路由。

Q8：OMNI_ATTN_BACKEND=cute 和 =torch 什么关系？ A：cute = CUTE 优先 + 形状不匹配自动回退 torch SDPA（安全）；torch = 强制纯 SDPA（完全不 patch）。cute 用 fp32 累加（大激活如 Qwen-Image 不溢出，优于 ESIMD 的 fp16 累加）。故障排查/A-B 对比时手动切回 torch 即可。

Q9：挂了 Patch Sol-Attn 但感觉没效果？ A：先确认是否命中：用插件自带的 SolAttnBlockProbe 节点查看统计——sparse 计数 > 0 才算生效；dense_fallback 增长 = 形状不匹配自动回退（正常，无收益而已）。注意命中日志只在前几次调用打印（防刷屏），以 Probe 统计为准。也可能注意力在总耗时占比小（短序列/少步数）导致收益不明显。

Q10：启用 Sol-Attn 需要什么？ A：三层门槛缺一不可：① 内核 b2+（supports_sol_attn() 为 True）② 启动 bat 设 SOL_ATTN_XPU_EXPERIMENTAL=1 ③ OMNI_ATTN_BACKEND=cute + 工作流加 Patch Sol-Attn 节点。前提注意力形状匹配（BF16 BTHD D128）。另需确认没有装 ComfyUI-SolAttn_triton（会抢注册同名 attention 函数）。

Q11：Qwen-Image 能用 Sol-Attn 吗？ A：可以试——bf16 + D128 + 长序列（实测 seq=4224）匹配，cross-attention（图像↔文本）部分预期 dense（不稀疏）。命中与否以 SolAttnBlockProbe 统计为准；不匹配自动回退，不会崩。

---

第六部分：内核升级后的组件检查与恢复

升级 ComfyUI 内核后（如 0.34.x → 0.35.x），按本部分检查 XPU 加速组件是否受影响、如何恢复。 本部分为通用方法，不依赖具体版本号；恢复时以本包内提供的文件为准（版本以本包为准）。

6.1 总览

组件	升级会被覆盖吗	恢复方式	需要重新编译吗
omni_xpu_kernel	❌ 不会（requirements 无声明）	通常无需操作	仅当 torch 升级时
comfy-kitchen	❌ 不会（provider 架构，与官方解耦）	版本三角变化时重装本包 provider wheel	否（纯 python）
ComfyUI-OmniXPU	❌ 不会（custom_nodes 不被动）	一般无需	否
ComfyUI-SolAttn（B 系列）	❌ 不会（custom_nodes 不被动）	一般无需；插件丢失时重解压本包 zip	否（纯 python）
comfy-aimdo	❌ 不会（20260912 起为 provider 架构，与官方解耦）	版本三角变化时重装本包 aimdo provider wheel	否（wheel 含编译好的 dll）

A770 补充：两线共用 kitchen / aimdo provider，恢复方式与上表一致；但 A770 的内核走 dg2 线、由社区独立发版，不跟随官方版本号（b1/b2 与 dg2.N 是两套编号）。A770 的恢复与升级请以 A770(dg2)/ 目录或社区 release 页为准，详见 6.9。

6.2 provider 的「双锚」：ComfyUI 一抬依赖，provider 就可能失效

本小节解释一个高频现象：升级 ComfyUI 后 XPU 加速"还在、但变慢了"。结论是 provider 被"响亮地拒绝"了，不是装坏了。

provider 不是"装一次就永久有效"——每次启动都会被校验，有两个锚，任一不满足即被拒：

锚	校验内容	当前值
① 官方包版本	provider 清单里写死 compatible_versions，必须精确命中官方包的已装版本	kitchen ["0.2.33"] / aimdo ["0.5.3"]
② PyTorch 版本	必须精确等于 provider 清单里的 torch_version	2.14.0+xpu

为什么要有锚：provider 的 _vendor/ 目录里装的是"某个官方版本对应的 XPU 实现"，而官方包提供的是 API 契约。官方换版本意味着契约可能变——这时明确拒绝比"看起来能跑"更安全。

关键：官方包版本由 ComfyUI 自己决定，而且变得很勤

ComfyUI\requirements.txt 固定了官方版本：
    comfy-kitchen==0.2.33
    comfy-aimdo==0.5.3

实测 ComfyUI 仓库近 5 周（2026-08-10 ~ 09-09）的 pin 变动：

包	版本变化	抬升次数
comfy-kitchen	0.2.28 → 0.2.30 → 0.2.31 → 0.2.33	3
comfy-aimdo	0.4.13 → 0.4.15 → 0.5.1 → 0.5.2 → 0.5.3	4

⚠️ 别只看版本号：这些是独立于 ComfyUI 版本号的提交（如 Update comfy-kitchen version to 0.2.33）。也就是说，不必等到"升级到新版本号"——一次普通的 git pull 就可能撞上。

失效时的表现（响亮失败，不崩）

[WARNING] [OmniXPU] runtime provider rejected:
    comfy_kitchen.xpu: official comfy-kitchen 0.2.34 is incompatible; provider accepts ['0.2.33']

→ 该 provider 被跳过，ComfyUI 照常启动，相关加速回落 PyTorch 慢路径——不崩，但明显变慢。

升级 ComfyUI 之后，建议跑一次自检

python -c "import importlib.metadata as m; print('kitchen 官方', m.version('comfy-kitchen'), '| provider', m.version('comfy-kitchen-xpu-runtime')); print('aimdo   官方', m.version('comfy-aimdo'), '| provider', m.version('comfy-aimdo-xpu-runtime')); print('torch', m.version('torch'))"

再对照 ComfyUI 里的实际要求（Windows）：

findstr /b "comfy-kitchen comfy-aimdo" ComfyUI\requirements.txt

判读规则：

现象	含义	处理
requirements pin = 官方实装 = provider 锚	对齐	无需操作
requirements pin 变了、官方包也跟着变了	① 号锚过期	换装锚定新版本的新 provider wheel
官方包没变，但 torch 变了	② 号锚过期	换装按新 torch 重打的 provider wheel

💡 懒人版：本包提供了一个自检脚本 check_provider_alignment.py（在包根目录）。用 ComfyUI 自带的 python 跑一次，上面这些结论会自动成表输出，并直接给出建议动作：

<你的ComfyUI>\python\python.exe check_provider_alignment.py --comfy-root <你的ComfyUI>

• 退出码 0 = 全部对齐；1 = 有需处理项（会自动列出问题与建议操作）
• 加 --quiet 只输出结论行，便于配合批处理 / 自动化调用
• 也可不传参数：脚本会自动探测 ComfyUI 根目录（也认环境变量 COMFY_ROOT）
• 它还会顺带检查：vendor 文件哈希是否完整、OmniXPU 插件是否在位、是否两个 SolAttn 插件抢注册、aimdo 旧版残留

三类组件"怕的东西"各不相同

组件	绑定对象	ComfyUI 抬依赖 pin 后
omni_xpu_kernel	PyTorch（ABI）	✅ 不受影响（不在 requirements 里）
comfy-kitchen / comfy-aimdo provider	官方包版本 + PyTorch	❌ 需重打（响亮失败）
ComfyUI-OmniXPU	ComfyUI 内部 API	⚠️ 不会被覆盖，但 adapter 可能静默失效

⚠️ 最需要警惕的反而是最后一行：provider 失效会打 warning，而 OmniXPU 的 adapter 找不到 patch 目标时，只体现为日志里一行从 xxx_adapter: applied 变成 xxx_adapter: skipped——功能没了却不报错。升级后请主动核对启动日志里的 adapter 列表（见第四部分「验证③」）。

6.3 omni_xpu_kernel：通常不用管

• 为什么安全：ComfyUI\requirements.txt 里没有 kernel 条目 → 升级脚本不会重装
• 检查（可选）：

F:\ComfyUI-aki-v3\python\python.exe -c "import torch; torch.xpu.init(); import omni_xpu_kernel; print(omni_xpu_kernel.__version__, omni_xpu_kernel.is_available())"

• 期望：当前版本号 + True
• ⚠️ 唯一例外：torch 版本变了（kernel 按特定 torch ABI 编译）：

F:\ComfyUI-aki-v3\python\python.exe -c "import torch; print(torch.__version__)"

• torch 未变 → 不用管；torch 变了 → kernel 加载失败，需按新 torch 重新编译（参考内核编译说明）

6.4 comfy-kitchen：provider 架构下不再被覆盖

• 旧版问题（≤20260901 的 0.2.31.post1 整包）：requirements.txt 固定官方 kitchen → 升级时被官方纯版覆盖（xpu 后端丢失）
• 新版机制（provider 架构）：官方 comfy-kitchen 由 pip 管理、XPU provider（comfy_kitchen_xpu_runtime）常驻 site-packages，二者解耦
• ⚠️ 但版本三角要跟着走：ComfyUI 抬高官方 pin（如 0.2.31 → 0.2.33）时，provider 的 compatible_versions 锚会对不上 → provider 被明确拒绝、路由回落慢路径。这是"响亮失败"，不崩
• 检查：

python -m pip show comfy-kitchen-xpu-runtime   :: 有输出 = provider 已装
python -c "import importlib.metadata as m; print(m.version('comfy-kitchen'))"   :: 官方包版本

• 验证 xpu 路由：重启 ComfyUI 看启动日志 comfy_kitchen backend xpu: {... 'available': True ...}；或先模拟 prestartup 激活 provider 再独立验证：

F:\ComfyUI-aki-v3\python\python.exe -c "import sys; sys.path.insert(0,'ComfyUI/custom_nodes/ComfyUI-OmniXPU'); import runtime_bootstrap as rb; rb.bootstrap(); import comfy_kitchen as ck; x=ck.list_backends().get('xpu',{}); print(x.get('available'), len(x.get('capabilities') or []))"

• 期望：True + capabilities 数量 > 0
• 恢复：provider 与官方包版本不再配对 → 换装锚定新版本的本包 provider wheel（pip install --force-reinstall --no-deps），再重启 ComfyUI

6.5 ComfyUI-OmniXPU：目录安全，看启动日志

• custom_nodes 目录由用户手工管理，升级脚本不碰
• 检查：custom_nodes\ComfyUI-OmniXPU\adapters 目录完整——⚠️ 两条线的 adapter 集完全不同，不要拿对方的名单去核对：

类别	B 系列（官方，bmg）	A770（社区 fork，dg2）
本版新增	sparse_attention.py、quantized_matmul.py	无（A770 没有这两个）
注意力	attention.py（CUTE 路由）、h3_rms_modulation.py	attention.py（ESIMD/DPAS 路由）、rms_rope.py、sdp_cache_lifecycle.py
量化	fp8_gemm.py、int8_ffn.py	fp8_gemm.py、int8_ffn.py、int4_gemm.py、int8_direct_cast.py、int8_native_gate.py
兼容桥	—	kitchen_compat.py（A770 专属）
内存 / 种子	seedvr_capacity.py、seedvr_cat_pad.py	dynamic_vram.py、lora_memory.py、seedvr_capacity.py、seedvr_cat_pad.py、large_video_preprocess.py
fixes/	legacy_interpolate.py、legacy_median.py、seedvr_ada.py	同上 + seedvr_vae_decode.py（A770 独家）
nodes/	—	含 sdp_cache.py

• 验证：启动日志应见 [OmniXPU] xxx_adapter: applied（A770 另有 a770_* 前缀的专属桥）；若缺失或报 patch 目标找不到 → 内核 API 变了，需等插件更新
• 恢复：插件丢失/损坏时，重新解压本包 B系列(bmg)\ComfyUI-OmniXPU.bmg-20260912.zip（A770 用户用 A770(dg2)\ComfyUI-OmniXPU.A770(dg2)-20260912.zip）到 custom_nodes\

6.6 ComfyUI-SolAttn：ComfyUI 升级后的验证与恢复（仅 B 系列）

• 仅限 B 系列（BMG）——Sol-Attn 稀疏注意力依赖内核的 cute.sol_attn 算子，A770（DG2）不支持
• ComfyUI 升级影响：插件本体在 custom_nodes 不会被覆盖（升级脚本不碰自定义节点）；但 ComfyUI 升级可能改变 attention 接口，需验证插件 patch 兼容性
• 验证（ComfyUI 升级后）：
• 节点加载：重启后节点列表有 Patch Sol-Attn（无 import 报错）
• patch 生效：跑含 Patch Sol-Attn 的工作流，用 SolAttnBlockProbe 看统计——sparse > 0 才算生效（dense_fallback 增长 = 注意力形状不匹配自动回退，属正常）
• 启动 bat 里 SOL_ATTN_XPU_EXPERIMENTAL=1 还在
• 启动日志没有 Attention function sol_attn already registered（有则说明 ComfyUI-SolAttn_triton 也装着，把后者移出 custom_nodes）
• 恢复：
• 插件丢失/损坏 → 重新解压本包 B系列(bmg)\ComfyUI-SolAttn-20260901.zip 到 custom_nodes\
• ComfyUI 接口变化导致节点报错/patch 失效 → 等插件作者更新（https://github.com/xiangyuT/ComfyUI-SolAttn_xpu）
• 实验开关丢失 → 启动 bat 补回 set SOL_ATTN_XPU_EXPERIMENTAL=1

6.7 comfy-aimdo：provider 架构下不再被覆盖（20260912 起）

• 旧版问题（deploy.bat 覆盖 site-packages\comfy_aimdo）：官方包一旦更新，覆盖内容即失效，需重新 deploy
• 新版机制：官方 comfy-aimdo 由 pip 管理（ComfyUI 0.35.0 对应 0.5.3），XPU provider（comfy-aimdo-xpu-runtime）独立常驻 → 二者解耦，升级互不影响
• 检查：

python -m pip show comfy-aimdo-xpu-runtime   :: 有输出 = provider 已装
python -c "import importlib.metadata as m; print(m.version('comfy-aimdo'))"   :: 应为 0.5.3

• 验证：启动日志出现两条 XPU 独占行 + DynamicVRAM support detected and enabled；启动 bat 里有 --enable-dynamic-vram
• 恢复：provider 与官方包版本不再配对 → 换装锚定新版本的本包 aimdo provider wheel（pip install --force-reinstall --no-deps），再重启
• 注意：内核升级后需实测工作流（aimdo 与 ComfyUI 接口联动，验证无回归）

6.8 升级后标准动作

1. 先跑一次 provider 对齐自检（见 6.2）→ 一屏看清两个 provider 的锚是否还成立，再决定要不要动别的地方
2. 查 torch 版本 → 决定 kernel 是否需要重编译
3. 检查 kitchen provider（必做）→ pip show comfy-kitchen-xpu-runtime + 官方包版本是否与锚一致 + OmniXPU provider active → 不符则换装对应 provider wheel
4. 看 OmniXPU 启动日志 → adapter applied 是否完整
5. 查 SolAttn 能力（B 系列）→ supports_sol_attn() + 实验开关 + Probe 统计 + 确认无 triton 版抢注册
6. 检查 aimdo → pip show comfy-aimdo 与 provider 锚一致 + bat 有 --enable-dynamic-vram + 实测工作流
7. A770 加查 → 内核仍是 0.2.0b1+torch214.dg2.3（社区 fork 独立发版，不会自动跟随官方 b2）+ bat 里有 UR_L0_USE_IMMEDIATE_COMMANDLISTS=1 + ESIMD 开关是否仍符合 3.1 判据

---

6.9 A770（DG2）专项说明

A770 与 B 系列在内核、注意力引擎、adapter 集上都是两条独立路线。本节集中 A770 的差异点与开关。

① 两线差异速查

维度	A770 / DG2（社区 fork）	B 系列 / BMG（官方）
内核 wheel	0.2.0b1+torch214.dg2.3	0.2.0b2+torch214.bmg
编译目标	dg2（别名 a770 / arc-a770）	bmg
注意力引擎	ESIMD / DPAS 侧车（lgrf_uni\lgrf_sdp*.pyd）	CUTE FMHA（cute_fmha_torch.pyd，7.3MB）
Sol-Attn	❌ 不支持（无 cute.sol_attn）	✅ 支持
注意力开关	OMNI_ATTN_BACKEND=esimd（opt-in，默认 torch）	OMNI_ATTN_BACKEND=cute
专属 adapter	a770_rms_rope_bridge、a770_kitchen_compat、a770_int8_native_gate、int4_gemm、sdp_cache_lifecycle、seedvr_vae_decode	sparse_attention、quantized_matmul、h3_rms_modulation
kitchen provider	共用根目录同一份（不装也能跑，有 a770_kitchen_compat 兜底桥）	共用根目录同一份
aimdo provider	共用根目录同一份（无独立 dg2 版）	共用根目录同一份

② A770 专属开关（默认值已逐条核对源码 config.py）

变量	默认	作用
UR_L0_USE_IMMEDIATE_COMMANDLISTS	—	H3 必设 =1，否则 DEVICE_LOST（见 3.1）
OMNIXPU_DG2_CONVROT_FUSED	开	把缓存的 Hadamard 矩阵乘融进 rowwise INT8 量化（SLM 与 register butterfly 两条实现，后者为生产路径）；数字见 ③
OMNIXPU_RMS_ROPE	开	RMS-RoPE 融合桥；实测 Kitchen eager 路径比融合 kernel 慢 4–11×
OMNIXPU_KITCHEN_COMPAT	开	缺后端桥（装了 kitchen provider 后自动跳过自身注册）
OMNIXPU_INT8_NATIVE	开	INT8 原生路径门控
OMNIXPU_INT4_GEMM	开	INT4 GEMM（A770 独有模块）
OMNIXPU_INT8_DIRECT_CAST	关	A770 实验：卸载的 TensorWise INT8 留在量化路径，省掉 bf16 物化
OMNIXPU_INT8_PATCH_CACHE	关	A770 实验：缓存 patched bf16 权重；显存紧张时会退化，仅 A/B 时开
OMNIXPU_SDP_CACHE_AUTOCLEAR	开	SDP 缓存生命周期；注意是"非 0/off/keep 即开"，写 keep 也可关闭
OMNIXPU_XPU_MEMORY_FRACTION	0.99（Win）	分配器占比；非法值会直接 SystemExit
OMNIXPU_INT8_FAST_FORWARD_COPY_MIN_ELEMS	—	已有负面结论：调到 16 Mi 以下不会提速，不必再试

另 OMNIXPU_VALIDATE_ATTENTION_OUTPUT=1：开启后每次 CUTE 调用都全量扫描输出（增加与形状成正比的临时分配），默认关闭，仅诊断用。A770 的 ESIMD FP16 路由不受这个开关控制——它始终保留自己的溢出扫描。

③ DG2 上的计算优化亮点

项	结果
dtype-aware ConvRot 反量化（build 3 新增）	低显存 LoRA 场景不再先物化整块 FP32 再转 BF16；group 64/256 + rowwise scale 走融合 DG2 ESIMD kernel，其他形状回退 FP32+cast；带配套 torch.compile meta function
H3 SwiGLU 精确契约（build 3 新增）	activation (16473,28672) / weight (5376,14336)；3.33ms vs 5.43ms（对比 eager SiLU + 原地乘）；输出 bit-exact
ConvRot 融合量化	int8_convrot_quant_esimd（register butterfly）为生产路径：20685×14336 4.3ms vs 7.3ms；压力测试无 DEVICE_LOST
RMS-RoPE 桥	rotary.rms_kitchen_rope_split_half_，供 MiniMax H3 的 Q/K 使用

④ SeedVR2 在 A770 上

• seedvr_ada_reshape：消除一处 >4GiB 的 repeat_interleave（A770 上会让 K 采样 OOM）
• seedvr_vae_decode：单次 XPU 分配会超过 ~4GiB 上限时，把 tiled decode 结果 CPU staging；设 UR_L0_ENABLE_RELAXED_ALLOCATION_LIMITS=1 时自动关闭
• DG2 D128 注意力路由：q_len ∈ [1024,2048) 与 (2048,4096) 走 torch SDPA（ESIMD 实测慢 1.1–1.6×）；q_len == 2048 与 q_len ≥ 4096 走 ESIMD
• 端到端实测（seedvr2_3b_int8_upscale_video.json）：681 s → 607 s
• 已知负面结论（不必再试）：spatial tile 1024 会 OOM；temporal chunk 125 无收益

⑤ A770 的升级节奏与 B 系列不同步

社区 fork 是独立发版的：它有自己的构建号（dg2.1 → dg2.2 → dg2.3），不会自动跟随官方内核的版本号（官方另外走 b1 → b2）。所以升级 ComfyUI 后，A770 用户要看的是"有没有新的 dg2.N"，而不是"官方出没出 bN"。更新从这里找：https://github.com/Blackwood416/omni-xpu-kernel/releases

---

附录：文件清单对照

IntelGPU-ComfyUI-系统优化指南-20260912/
├── 本指南.md                      ← 你现在看的（torch 2.14 栈 / B 系列(bmg) 与 A770(dg2) 双线）
├── A770(dg2)/                     ← A 系列（A770 等 DG2）专用（社区 fork，Blackwood416）
│   ├── omni_xpu_kernel-0.2.0b1+torch214.dg2.3-cp313-cp313-win_amd64.whl
│   │     └─ SHA256: DD3466A4175E19501741DABD914E05402062922EE8823784039701A61A0CB92A
│   └── ComfyUI-OmniXPU.A770(dg2)-20260912.zip               ← 社区版（A770 专属 adapter：a770_rms_rope_bridge / a770_kitchen_compat / int4_gemm / seedvr_vae_decode 等）
├── B系列(bmg)/                    ← B 系列（B580/B60/B70）专用
│   ├── omni_xpu_kernel-0.2.0b2+torch214.bmg-cp313-....whl   ← 含 Windows CUTE + Sol-Attn；本版同步 #696（新增原生 Sol attention CUTE 全套 + sol_attn_v2.py，pyd 重编）
│   ├── ComfyUI-OmniXPU.bmg-20260912.zip                     ← 官方版（新增 sparse_attention / quantized_matmul 两个 adapter）
│   └── ComfyUI-SolAttn-20260901.zip                         ← Patch Sol-Attn 稀疏注意力节点（沿用，**仅 B 系列**）
├── comfy_kitchen_xpu_runtime-0.2.33-py3-none-any.whl  ← kitchen XPU provider（0.2.31 → 0.2.33，锚定 ComfyUI 0.35.0 的官方 pin）**两线共用**
├── comfy_aimdo_xpu_runtime-0.5.3-cp39-abi3-win_amd64.whl  ← aimdo XPU provider（新版架构，取代旧 deploy.bat 覆盖式装法）**两线共用，无独立 dg2 版**
├── ComfyUI-GGUF-XPU-20260912.zip   ← GGUF 加速节点（本版补入 krea2 架构识别，选装）
└── check_provider_alignment.py     ← 对齐自检脚本（升级 ComfyUI 后跑一次，看三个组件是否还对齐）

注： - A770 不含 Sol-Attn——A770(dg2)/ 内外都没有 SolAttn 包，这是正确的（DG2 无 cute.sol_attn）。 - A770 不含独立的 aimdo / kitchen provider——与 B 系列共用上面那两份，无需另找。 - 一键安装 bat 由维护者单独发布，随包结构以实际目录为准。

---

感谢

本指南涉及的所有项目与作者，感谢你们的付出：

特别感谢

作者	项目	贡献
Blackwood	Blackwood416/omni-xpu-kernel	A770 等 A 系列（DG2）内核——官方原版不支持 A 系列，是 Blackwood 手搓的 dg2 内核让 A 系列也能享受加速
xiangyuT	intel/llm-scaler omni	官方 omni 项目负责人——omni_xpu_kernel、ComfyUI-OmniXPU 官方套件的核心作者，同时维护 XPU fork（kitchen/aimdo）

Intel GPU & ComfyUI 折腾群

QQ 群号：220819365 —— 欢迎加入交流 Intel GPU 上的 ComfyUI 折腾经验。

全部项目地址汇总

项目	地址	用途
Intel llm-scaler（官方 omni）	https://github.com/intel/llm-scaler/tree/main/omni	官方内核 + OmniXPU 节点
Blackwood416/omni-xpu-kernel	https://github.com/Blackwood416/omni-xpu-kernel	A 系列（DG2）内核
Blackwood416/ComfyUI-OmniXPU	https://github.com/Blackwood416/ComfyUI-OmniXPU	A 系列专用节点
xiangyuT/comfy-kitchen-xpu	https://github.com/xiangyuT/comfy-kitchen-xpu	kitchen XPU fork（算子分发）
xiangyuT/comfy-aimdo-xpu	https://github.com/xiangyuT/comfy-aimdo-xpu/	aimdo XPU（DynamicVRAM）
xiangyuT/ComfyUI-SolAttn_xpu	https://github.com/xiangyuT/ComfyUI-SolAttn_xpu	Sol-Attn 稀疏注意力节点（B 系列）
kijai/ComfyUI-SolAttn_triton（上游）	https://github.com/kijai/ComfyUI-SolAttn_triton	Sol-Attn 官方实现（CUDA/ROCm）——不要与 XPU 版同装
analytics-zoo/ComfyUI-GGUF-XPU	https://github.com/analytics-zoo/ComfyUI-GGUF-XPU	GGUF 加速节点
Comfy-Org/comfy-kitchen（官方上游）	https://github.com/Comfy-Org/comfy-kitchen	kitchen 官方源

感谢所有为 Intel GPU 生态贡献代码的开发者们 🙏

---

本指南由 Intel Arc 生态维护整理，随组件版本更新。如有问题，请携带上述验证输出反馈。