llama-cpp-python-sycl-windows

中文 | English

llama-cpp-python-sycl-windows

为 Windows 平台预编译的 llama-cpp-python 安装包，支持 Intel Arc GPU (SYCL) 加速。

基于 JamePeng 的分支编译，为 Intel Arc GPU 提供 SYCL 加速支持。

手工安装/升级whl的步骤扫盲包 https://www.yuque.com/allan-gmwqz/xq0z39/ckgeuiklqkazz75k?singleDoc#

最新版本说明（v0.4.5+sycl · 2026-10-26）

核心亮点：LiliCorr 投机解码 + Soprano TTS + MTMD 媒体缓存优化（一并覆盖上游 0.4.4）

升级至 llama-cpp-python 0.4.5（基于 JamePeng 3fc39b2，同步 llama.cpp 74bca39 = b11870，子模块跨 167 个提交，零本地补丁）。⚠️ 上游 0.4.4 有 CHANGELOG 段但未单独发版，__version__ 从 0.4.3 直跳 0.4.5，故本版一并覆盖 0.4.4 + 0.4.5 两段内容（距 0.4.3 共 26 个提交）
LiliCorr 投机解码（本版主线）：新增块解码、projected anchor 处理与 checkpoint 恢复，对齐 MTP/DFlash 的 CPU 抑制与候选概率；上游 Nemotron-3.5-Bolt-74B + LiLiCorr 实测解码 132.6 → 198.0 tok/s（1.49x）
Soprano TTS：新增音频流行数 / flush 进度查询（可选 int64 API），支持非流式 WAV/PCM 合成并做模型专属校验；Qwen3-TTS / Pocket TTS 在固定种子下输出逐字节不变
MTMD 媒体缓存优化（多轮对话收益最大）：无投机引擎占槽时改用设备侧媒体 checkpoint、跨轮保留可复用历史与媒体 checkpoint、归一化 BOS/EOS 与 Qwen vision 边界防重复 → 上游实测 Qwen3.5 第 2/3 轮首 token 延迟降约 60%、图像缓存命中 0% → 100%
LlamaModel.suppress_tokens() 新增（位于 llama_cpp._internals，非顶层导出）；采样侧改为在候选过滤前合并模型 suppression 与用户 logit bias，且不再修改调用方参数
投机解码 / hybrid 状态可靠性（0.4.4 段）：跳过无用的 final target checkpoint（上游实测每请求少导出约 50 MiB、清理 27–28 ms → 约 0.1 ms、吞吐 +8~12%）；MTP 验证钩子与 native rollback 对齐；checkpoints 关闭时仍保留有效前缀复用；hybrid checkpoint 恢复不再因 export size 变化被拒；RAM / disk / trie 前缀匹配统一
SYCL 后端收益（llama.cpp 侧 167 个提交，SYCL 16 项）：ESIMD kernel 在 FFN 路径恢复启用、XMX 矩阵引擎多列 mul_mat_vec_q 重构、get_rows 在 reorder 权重上的修复（本构建 Reorder=Y 直接命中）、graph 录制/重放（默认关闭）、反量化 fp16/fp32 开关合并、fattn-mkl 显式依赖替代 host wait、CONV_2D 非连续输入错误结果修复、memset 改有序写
XMX 的覆盖面（按合并后源码核实）：六种 K-quant / Q8_0 类型全部支持；单列自回归解码是否走 XMX 由 ggml_sycl_xmx_min_cols(type) == 1 决定，实际为 Q2_K / Q3_K / Q4_K —— 本模型的 Q4_K 权重在单 token 解码时即走 XMX int8 DPAS；Q5_K / Q6_K / Q8_0 需 ≥2 列才启用。多列路径覆盖 2–80 列（面向投机解码验证与短提示批），融合 gate/up GLU kernel 最多 16 列。前置条件是 Reorder=Y（权重已 reorder）与 BMG / LNL 架构
显存工作集与 0.4.3 完全一致：SYCL0 compute buffer 513.02 MiB、SYCL_Host 28.03 MiB，两次运行均 matches expectation，未增长、无泄漏
新增 3 个 SYCL 环境变量：GGML_SYCL_ENABLE_XMX_ESIMD(1) / GGML_SYCL_XMX_MAX_COLS(80) / GGML_SYCL_GRAPH_EVICTION_TIMEOUT(10)；另有 4 个编译期宏（GGML_SYCL_XMX_GLU_MAX_COLS=16 等）无法用环境变量设置，其中 XMX_GLU_MAX_COLS 会以宏值形式出现在启动日志里，易被误认为 env。GGML_SYCL_ENABLE_GRAPH 默认 0，graph 重放需显式开启（该开关 0.4.3 已存在但无实现，本版才实装）

⚠️ 已知集成注意（延续 0.3.48 / 0.3.49 / 0.4.0 / 0.4.1 / 0.4.2 / 0.4.3）：hybrid 视觉模型 + ctx_checkpoints=0 首 decode 崩溃

现象：Qwen3.5 等带 SWA 层的 hybrid 视觉模型，大图（约 4000+ vision tokens）下 prefill 正常，但首 decode token 崩溃（failed to prepare attention ubatches / failed to find a memory slot for batch of size 1）
根因：调用方传 ctx_checkpoints=0 会强制 hybrid 模型走 "Bypassing rollback" fast-path，大 prefill 下无槽余量给首 decode token
本版状态：未做真机复测。上游 0.4.4 含一条 fix(state): preserve valid prefix reuse with checkpoints disabled，与该校验路径高度相关，疑似即该问题的修复，但未经本机验证；同时 Llama.generate() 相关代码已大幅重写（0.4.3 的 llama.py:2174-2178 快路径已不存在）
规避：建议继续沿用 ctx_checkpoints 默认 -1
✅ 官方推荐插件已修复：comfyui-sg-llama-cpp 已在 1f0fc15 将 ctx_checkpoints 默认改为 -1 并加响应式 n_ctx hint。使用此插件无需手动处理
本 wheel 本身无此 bug：纯 llama_cpp.Llama 同模型同大图在 n_ctx=8192 下已验证正常

🚀 实测性能（Qwen3.5-4B 视觉模型 + 图像，0.4.5）：

⚠️ 测试硬件说明：本次测试机临时更换为 Intel Arc Pro B70 32GB（B580 暂不在机内），只做了两张图的跑通验证。下表只列本版绝对数字，不与任何历史版本做对比 —— B580 与 B70 在算力（160 → 256 CU）与显存带宽上的差距过大，跨硬件横比没有意义。

指标	小图 1088×1440（热跑）	大图 1792×2304（冷跑）
视觉 token 数	1530	4032
图像编码耗时	1120 ms（clip_encode）	21670 ms（clip_encode）
图像解码耗时	515 ms（batch 1/1）	3101 ms（batch 1/2）+ 2403 ms（batch 2/2）
prompt eval	1756.58 t/s（886.38 ms / 1557 tokens）	34.07 t/s（119133.96 ms / 4059 tokens）
生成速度	117.45 t/s（eval 9859.19 ms / 1158 runs）	111.58 t/s（eval 10871.25 ms / 1213 runs）
总耗时	19.00 s	165.56 s
load time	99.41 ms（热）	62993.54 ms（冷）
Hybrid checkpoint	host 1×50.25 MiB（pos 64）+ device（pos 72 / 1230）	host 1×50.25 MiB（pos 91）+ device（pos 99 / 1312）
SYCL 计算缓冲	SYCL0 513.02 MiB / SYCL_Host 28.03 MiB	同左

测试场景：Qwen3.5-4B-Uncensored + mmproj-BF16，hybrid 架构（含 SWA 层），ctx_checkpoints=-1，n_ctx=8192，n_batch=2048（大图按 2048 + 1984 两批喂入）。

大图为冷跑（load time 62993.54 ms）：其 prompt eval 34.07 t/s 含 SYCL kernel 首次 JIT 编译与 oneDNN primitive 创建的一次性成本（同图第二次运行会回到热跑量级），不可与本版小图热跑横比。小图 load time 99.41 ms 为热跑稳定态。

需要版本间性能结论时，请在 B580 上复测后单独记录，不要引用本表做跨硬件或跨版本比较。

社区反馈：

✅ "Qwen 3.8 27B working fine with llama_multimodal.GenericMTMDChatHandler" —— 视觉模型兼容性良好详见：JamePeng/llama-cpp-python#169 (comment)

安装包：llama_cpp_python-0.4.5+sycl-cp313-cp313-win_amd64.whl（约 42 MB，精简版，需预装 oneAPI 2026.1）

0.3.39+ 重要变更说明

1. llama-cpp-python-sycl-windows 在 0.3.39 之后发生了哪些变化

从 0.3.39 版本开始，llama-cpp-python 引入了重大的 MTMD（Multi-Modal Token Decomposition）重写，对视觉模型的支持方式做了底层重构：

变更项	0.3.38 及之前	0.3.39+
视觉模型加载方式	手动创建 `clip_model_path` handler 注入 `Llama()`	`mmproj_path` 直接传给 `Lama()`，内部自动创建 handler
视觉 handler 类	模型特定 handler（如 `Qwen3VLChatHandler`）	`GenericMTMDChatHandler` 统一处理
handler 参数传递	直接传给 handler 构造函数	通过 `chat_handler_kwargs` dict 传递
混合架构模型	无特殊处理	用默认 `ctx_checkpoints=-1`（如 Qwen3.5）；勿传 `0`，0.3.48+ 会触发 hybrid fast-path 首 decode 崩溃

2. 从 0.3.38 或更早版本升级的用户需要手工清理哪些内容

重要：不要直接使用 pip install --upgrade，旧版本残留文件可能与新版冲突。请按以下步骤操作：

步骤 1：完全卸载旧版本

pip uninstall llama-cpp-python -y

步骤 2：安装新版本 whl

pip install llama_cpp_python-0.4.5+sycl-cp313-cp313-win_amd64.whl

步骤 3：更新 ComfyUI 插件

如果你在 ComfyUI 中使用此 whl，必须使用适配 0.3.39+ 的插件版本（见下方第 3 节）。

3. 对应适配的 ComfyUI 插件

原版 comfyui-sg-llama-cpp 插件不支持 0.3.39+ 的 MTMD 重写。以下 fork 已完成适配：

https://github.com/allanmeng/comfyui-sg-llama-cpp

适配内容：

clip_model_path → mmproj_path：直接传给 Llama()，不再手动创建 handler
GenericMTMDChatHandler 参数过滤：取 GenericMTMDChatHandler ∪ MTMDChatHandler 参数并集，过滤掉 force_reasoning、enable_thinking 等 0.3.39+ 不接受的参数
新增 ctx_checkpoints 选项（默认 -1）：混合架构模型（Qwen3.5 等 Transformer+Mamba）使用默认即可；勿设为 0，0.3.48+ 会触发 hybrid fast-path 首 decode 崩溃
vision_image_min_tokens 默认值从 -1 改为 1024（Qwen-VL 最低要求）
移除无效 UI 参数：vision_enable_thinking、vision_force_reasoning、vision_add_vision_id

安装方式：

cd ComfyUI/custom_nodes
git clone https://github.com/allanmeng/comfyui-sg-llama-cpp

0.3.43+ 构建与部署说明（oneAPI 2026 / Python XPU ≥ 2.13）

1. 为什么 0.3.43 起使用 oneAPI 2026 编译

从 0.3.43 开始，本项目的构建环境升级到 Intel oneAPI Base Toolkit 2026（对应 Intel Deep Learning Essentials 2026.0）。升级动机：

Intel 官方建议安装并使用最新 oneAPI / 显卡驱动，以确保 Intel Arc B580 / B70（Battlemage）的性能与兼容性。
0.3.43 的编译需要搭配 Python XPU 运行时（intel-xpu-backend-for-pytorch / PyTorch XPU）≥ 2.13（即 PyTorch 2.13 生态）。oneAPI 2026 与之在 ABI 与运行时层面匹配；若混用旧版 Python XPU 后端（如 2.12 + oneAPI 2025）可能导致运行时不匹配。

重要：若你的 ComfyUI / 推理环境使用 PyTorch XPU 方案，请确保 intel-xpu-backend-for-pytorch ≥ 2.13，与 0.3.43 的 oneAPI 2026 构建保持一致。

2. whl 打包方式：方案 A（精简版，不含 oneAPI 运行时）

自 0.3.45 起，发布的 whl 采用方案 A（精简版）：不包含 oneAPI 运行时 DLL（dnnl.dll、mkl_core.3.dll、mkl_sycl_blas.6.dll、mkl_tbb_thread.3.dll、tbb12.dll 均已移除），whl 体积约 36–37 MB。因此部署目标机 必须预先安装 Intel oneAPI（SYCL 核心运行时 sycl9.dll / OpenCL.dll 及上述数值库由 oneAPI 提供）。

⚠️ 注意：libomp140.x86_64.dll 保留在 whl 中（OpenMP 预加载修复依赖），不可删除。

若目标机未安装 oneAPI，SYCL 运行时无法加载，推理会失败。请先按下方「前置要求」安装 oneAPI Base Toolkit。

3. 已安装 oneAPI Toolkit 的用户（默认即精简版，无需再删）

方案 A 的 whl 本身已不含 oneAPI 冗余 DLL，目标机安装 oneAPI 后这些运行时由 oneAPI 经 setvars.bat 或系统 PATH 提供。whl 内仅保留 libomp140.x86_64.dll（必需）。

若你从旧版（0.3.43/0.3.44 自包含 whl）升级，site-packages 里可能残留旧版 oneAPI DLL，建议先 pip uninstall 清理再装新版。

4. PR #25880 补丁：修复 SYCL onednn fattn 长上下文乱码

0.3.43 版本本地应用了 PR #25880（ggml-org/llama.cpp）补丁，修复了 SYCL onednn flash-attention 路径下的 use-after-return 问题。

症状：在较长上下文（n_kv ≥ ~26k，如多轮对话第二轮）时，oneDNN fattn 的输出塌缩为重复 token（"GGGGG…" 模式）。

根因：SDPA scale 值通过 async memcpy 从 CPU 上传到 GPU device buffer，源是栈局部变量。当 K/V staging 内核在 in-order 队列中先于 memcpy 完成时，栈帧已被回收，memcpy 读到垃圾值 → 后续 SDPA 使用错误的 scale → 输出乱码。

修复方案：

将 scale 上传改为同步 memcpy（.wait()），确保拷贝完成后再返回 buffer 指针
使用 per-device device scalar 缓存（static std::unordered_map），scale 值仅首次同步上传一次，后续复用缓存，消除重复 sync 开销
新增环境变量 GGML_SYCL_FA_ONEDNN_MAX_KV（默认 0 = 不限），可在极长序列场景选择性回退到原生 FA kernel

与之前 PR #25741 的区别：原先的 #25741 使用无条件 wait_and_throw() 来掩盖问题（靠撑住栈帧让 async memcpy 完成），但每调用付出 ~6% PP 性能代价。#25880 从根因修复，且单设备无性能损失。

前置要求

安装前，请确保已完成以下步骤：

1. Intel Arc 显卡驱动

从以下地址下载并安装最新的 Intel Arc 显卡驱动： https://www.intel.com/content/www/us/en/download/785597/intel-arc-iris-xe-graphics-windows.html

2. Intel oneAPI Base Toolkit（必须安装）

SYCL 运行时依赖 Intel oneAPI，但 无需安装完整工具包，只需安装以下组件：

组件	用途
Intel oneAPI DPC++/C++ Compiler	提供 SYCL 编译器（icx）与 `OpenCL.dll`
Intel oneAPI DPC++ Library	提供 `sycl9.dll` 运行时（oneAPI 2026.1）
Intel oneAPI Math Kernel Library (oneMKL)	提供 MKL SYCL 运行时
Intel oneAPI Deep Neural Network Library (oneDNN)	提供 `dnnl.dll`
Intel oneAPI Threading Building Blocks (oneTBB)	提供 `tbb12.dll`

下载 Intel oneAPI Base Toolkit（安装时选择自定义安装）： https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html

提示： 安装时选择「自定义安装」，只勾选上表中的这几个组件，可节省大量磁盘空间。oneAPI 2025+ 中 DPC++ Library 是独立于 Compiler 的组件，需单独勾选。

环境要求

项目	要求
操作系统	Windows 10/11 x64
显卡	Intel Arc（炼金师 / 战法师架构）
驱动	Intel Arc 显卡驱动（最新版）
oneAPI	必须安装 — DPC++ Compiler、oneMKL、oneDNN、oneTBB

可用安装包

版本	文件	大小
0.4.5	`llama_cpp_python-0.4.5+sycl-cp313-cp313-win_amd64.whl`	~42 MB
0.4.3	`llama_cpp_python-0.4.3+sycl-cp313-cp313-win_amd64.whl`	~39 MB
0.4.2	`llama_cpp_python-0.4.2+sycl-cp313-cp313-win_amd64.whl`	~37 MB
0.4.1	`llama_cpp_python-0.4.1+sycl-cp313-cp313-win_amd64.whl`	~37 MB
0.4.0	`llama_cpp_python-0.4.0+sycl-cp313-cp313-win_amd64.whl`	~36 MB
0.3.49	`llama_cpp_python-0.3.49+sycl-cp313-cp313-win_amd64.whl`	~36 MB
0.3.48	`llama_cpp_python-0.3.48+sycl-cp313-cp313-win_amd64.whl`	~36 MB
0.3.47	`llama_cpp_python-0.3.47+sycl-cp313-cp313-win_amd64.whl`	~36 MB
0.3.46	`llama_cpp_python-0.3.46+sycl-cp313-cp313-win_amd64.whl`	~35 MB
0.3.45	`llama_cpp_python-0.3.45+sycl-cp313-cp313-win_amd64.whl`	~36 MB
0.3.44	`llama_cpp_python-0.3.44+sycl+pr25880-cp313-cp313-win_amd64.whl`	~36 MB
0.3.43	`llama_cpp_python-0.3.43+sycl+pr25880+oneapi2610-cp313-cp313-win_amd64.whl`	~109 MB
0.3.41	`llama_cpp_python-0.3.41+sycl-cp313-cp313-win_amd64.whl`	~27 MB
0.3.38	`llama_cpp_python-0.3.38+sycl-cp313-cp313-win_amd64.whl`	~22 MB
0.3.36	`llama_cpp_python-0.3.36+sycl-cp313-cp313-win_amd64.whl`	~20 MB
0.3.35	`llama_cpp_python-0.3.35+sycl-cp313-cp313-win_amd64.whl`	~19 MB
0.3.34	`llama_cpp_python-0.3.34+sycl-cp313-cp313-win_amd64.whl`	~19 MB
0.3.33	`llama_cpp_python-0.3.33+sycl-cp313-cp313-win_amd64.whl`	~18 MB
0.3.32	`llama_cpp_python-0.3.32+sycl-cp313-cp313-win_amd64.whl`	~18 MB
0.3.31	`llama_cpp_python-0.3.31+sycl-cp313-cp313-win_amd64.whl`	~174 MB
0.3.30	`llama_cpp_python-0.3.30+sycl-cp313-cp313-win_amd64.whl`	~180 MB

从 Releases 页面下载。

安装方法

方法一：pip 安装（推荐）

pip uninstall llama-cpp-python -y
pip install llama_cpp_python-0.4.5+sycl-cp313-cp313-win_amd64.whl

先 uninstall 再 install 是最干净的安装方式。

方法二：手动安装（适用于 ComfyUI 等嵌入式 Python 环境）

将 whl 文件重命名为 .zip 后解压
将 llama_cpp 文件夹复制到 site-packages 目录：
```
your_python\Lib\site-packages\llama_cpp\
```

在 ComfyUI 中使用

在启动脚本中加载 oneAPI 环境

安装完 oneAPI 后，在 ComfyUI 的启动 .bat 文件里， Python 启动之前 加入以下一行：

call "C:\Program Files (x86)\Intel\oneAPI\setvars.bat" --force

启动脚本示例 start_comfyui.bat：

@echo off
call "C:\Program Files (x86)\Intel\oneAPI\setvars.bat" --force
......
......
"C:\python\python.exe" main.py --listen 0.0.0.0

创建专用的预加载插件

注意（自 0.3.43 起）：llama_cpp 在导入时会自动将自身 lib/ 目录注册到 DLL 搜索路径（继承上游 0.3.42 的 Windows DLL 搜索修复）。因此 通常情况下，ComfyUI 中不再需要放置 sycl-preloader 插件。以下内容仅供需要兼容 0.3.42 及更早版本，或自定义部署环境的用户参考。

另注（自 0.3.45 起）：whl 采用方案 A（精简版），不再自带 oneAPI 运行时 DLL；但仍会自动注册自身 lib/ 目录，且目标机需预装 oneAPI（见上文「whl 打包方式」）。

为所有基于 llama-cpp-python 的 ComfyUI 节点启用 SYCL GPU 加速，需要创建一个专用的预加载插件。

第一步：创建插件目录

mkdir "your_comfyui\custom_nodes\sycl-preloader"

第二步：创建空的 `init.py`

echo. > "your_comfyui\custom_nodes\sycl-preloader\__init__.py"

第三步：创建 `prestartup_script.py`

import os
import importlib.util
from pathlib import Path

def sycl_preloader():
    if os.name != "nt":
        return
    try:
        _spec = importlib.util.find_spec('llama_cpp')
        if not _spec:
            print("[SYCL] 找不到 llama_cpp 包")
            return
        _pkg_dir = Path(_spec.origin).parent
        for _sub in ['', 'lib', 'bin']:
            _d = _pkg_dir / _sub if _sub else _pkg_dir
            if _d.exists():
                os.add_dll_directory(str(_d))
        for _p in os.environ.get("PATH", "").split(os.pathsep):
            if "Intel" in _p and os.path.exists(_p):
                os.add_dll_directory(_p)
        print("[SYCL] DLL搜索路径注册完成")
    except Exception as e:
        print(f"[SYCL] Error: {e}")

sycl_preloader()

为什么使用 prestartup_script.py？

问题背景

编译并安装 SYCL 版本的 llama-cpp-python 之后，直接用 Python 脚本调用时 GPU 可以正常工作。但是，ComfyUI 里基于 llama-cpp-python 的插件（例如提示词反推插件）却无法激活 SYCL，只能回退到 CPU 运行。

根本原因是 Python 3.8+ 在 Windows 上引入的 DLL 加载限制：

出于安全考虑，Python 3.8+ 在加载 DLL 时完全忽略 PATH 环境变量。即使 setvars.bat 已经正确地把 oneAPI 路径写入了 PATH，Python 也不会通过这个机制找到 SYCL DLL。唯一可靠的方式是在 Python 代码里显式调用 os.add_dll_directory()，在需要 DLL 之前提前注册搜索路径。

为什么 bat 启动文件和 main.py 都不行？

启动 .bat 文件：可以设置 PATH 和环境变量，但无法调用 Python 的 os.add_dll_directory()，DLL 加载限制依然存在。
ComfyUI 的 main.py：看起来是个选项，但 main.py 第一行就开始导入 ComfyUI 核心模块（ import comfy.options 等），这些 import 会间接触发插件加载链，导致 llama_cpp 可能在预加载代码执行之前就已经被导入了。时机太晚，不可靠。

解决方案：利用 ComfyUI 的 prestartup 机制

ComfyUI 内置了一个钩子函数 execute_prestartup_script()。启动时，ComfyUI 会扫描 custom_nodes\ 下每一个子文件夹，找到并执行其中名为 prestartup_script.py 的文件。这个过程发生在 所有插件节点被导入之前，是整个 ComfyUI 进程中最早能可靠运行 Python 代码的时机。

启动顺序如下：

main.py 基础初始化
    ↓
execute_prestartup_script()  ← prestartup_script.py 在这里执行
    ↓
加载各插件的 __init__.py / nodes.py
    ↓
启动服务器

通过 os.add_dll_directory() 和 ctypes.CDLL() 加载 SYCL DLL 之后，效果是 进程级别 的。后续所有基于 llama-cpp-python 的插件（ComfyUI-QwenVL、comfyui-sg-llama-cpp 等）都能自动找到已经在内存中的 DLL，无需每个插件单独配置。

为什么要建一个专用的插件文件夹？

如果把 prestartup_script.py 放在某个现有插件的文件夹里（例如 comfyui-sg-llama-cpp），风险很高——一旦那个插件被删除或更新，这个文件就消失了。最稳妥的做法是创建一个只包含两个文件的最小专用插件目录：

custom_nodes\sycl-preloader\
    __init__.py          （空文件）
    prestartup_script.py （SYCL DLL 预加载器）

这个文件夹没有节点、没有依赖，永远不会被 ComfyUI Manager 的更新机制修改。它只有一个职责：在正确的时机为整个 ComfyUI 进程完成 SYCL DLL 的预加载。

ComfyUI 推荐参数

参数	推荐值
`n_gpu_layers`	`-1`（所有层卸载到 GPU）
`n_ctx`	`4096`
`n_threads`	`4`
`n_threads_batch`	`4`
`ctx_checkpoints`	`-1`（默认；混合架构模型如 Qwen3.5 用默认即可，勿设 `0`——0.3.48+ 会触发 hybrid fast-path 首 decode 崩溃）
`vision_image_min_tokens`	`1024`（Qwen-VL 最低要求）
`vision_image_max_tokens`	`-1`（使用默认值）

已知限制

Intel Arc（SYCL0）的 Flash Attention 通过 oneDNN 路径实现（GGML_SYCL_DNNL，默认开启）：B 系列（B580/B70 等）实测 GGML_SYCL_ENABLE_FLASH_ATTN / GGML_SYCL_FA_ONEDNN / GGML_SYCL_ENABLE_MKL_FA 均为开启；上游对 A 系列（Alchemist） 做了 oneDNN 特性 gate，A 系列上该路径不可用。无论哪种情况，显存占用都高于 CUDA 方案
部分 CLIP 图计算算子会回退到 CPU，视觉编码性能受限
Qwen3.5-2B（混合/循环架构）可能导致不稳定，建议改用 Qwen3-2B

测试环境

项目	版本
显卡	Intel Arc Pro B70 32GB（本版实测；B580 未复测）
驱动	最新版（本版实测 SYCL 20.2 / driver 1.15.39183+4）
操作系统	Windows 11 x64
Python	3.13.11
oneAPI	2026.1
ComfyUI	0.16.3

Name		Name	Last commit message	Last commit date
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
README_EN.md		README_EN.md
sycl-build-guide-cn.md		sycl-build-guide-cn.md
sycl-build-guide-en.md		sycl-build-guide-en.md

Latest commit

History

Folders and files

Repository files navigation

llama-cpp-python-sycl-windows

最新版本说明（v0.4.5+sycl · 2026-10-26）

0.3.39+ 重要变更说明

1. llama-cpp-python-sycl-windows 在 0.3.39 之后发生了哪些变化

2. 从 0.3.38 或更早版本升级的用户需要手工清理哪些内容

步骤 1：完全卸载旧版本

步骤 2：安装新版本 whl

步骤 3：更新 ComfyUI 插件

3. 对应适配的 ComfyUI 插件

0.3.43+ 构建与部署说明（oneAPI 2026 / Python XPU ≥ 2.13）

1. 为什么 0.3.43 起使用 oneAPI 2026 编译

2. whl 打包方式：方案 A（精简版，不含 oneAPI 运行时）

3. 已安装 oneAPI Toolkit 的用户（默认即精简版，无需再删）

4. PR #25880 补丁：修复 SYCL onednn fattn 长上下文乱码

前置要求

1. Intel Arc 显卡驱动

2. Intel oneAPI Base Toolkit（必须安装）

环境要求

可用安装包

安装方法

方法一：pip 安装（推荐）

方法二：手动安装（适用于 ComfyUI 等嵌入式 Python 环境）

在 ComfyUI 中使用

在启动脚本中加载 oneAPI 环境

创建专用的预加载插件

第一步：创建插件目录

第二步：创建空的 __init__.py

第三步：创建 prestartup_script.py

为什么使用 prestartup_script.py？

问题背景

为什么 bat 启动文件和 main.py 都不行？

解决方案：利用 ComfyUI 的 prestartup 机制

为什么要建一个专用的插件文件夹？

ComfyUI 推荐参数

已知限制

测试环境

致谢

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

第二步：创建空的 `init.py`

第三步：创建 `prestartup_script.py`