pytorch-xpu-setup

用途

该技能提供在 Intel GPU（XPU）上安装、配置和使用 PyTorch 的完整指南，覆盖 Windows 与 Linux 平台。当用户涉及 PyTorch 配合 Intel GPU、XPU 相关话题时可使用本技能。

重要背景（截至 2026 年）

Intel Extension for PyTorch（IPEX）已于 2026 年 3 月停止维护（EOL）。所有 XPU 支持现已成为上游 PyTorch 的原生功能。
XPU 没有 conda 包，只有来自 XPU 索引 URL 的 pip wheel。
推荐流程：创建 conda 环境 → 在其中通过 pip 安装。

前置条件

Intel GPU 驱动：所有用户必需。

Windows：从 Intel Arc & Iris Xe Graphics - Windows 下载。安装时包含 LevelZeroSDK 以支持 torch.compile。
Linux：遵循 Client GPU 安装说明。
完整前置条件页面：https://www.intel.com/content/www/us/en/developer/articles/tool/pytorch-prerequisites-for-intel-gpu/2-11.html

Intel Deep Learning Essentials：仅在从源码构建时需要。若通过 pip wheel 安装，运行时包会自动打包。

受支持硬件

平台	支持的 GPU
Windows 11 / Ubuntu 24.04+	Intel Arc A-Series (Alchemist)、Arc B-Series (Battlemage)、Core Ultra with Arc Graphics (Meteor Lake-H、Arrow Lake-H、Lunar Lake)
Windows 11 / Ubuntu 25.10	Panther Lake
Linux (RHEL 9.2、SUSE 15 SP5、Ubuntu 22.04+)	Intel Data Center GPU Max Series (Ponte Vecchio)

安装步骤

# 1. Create conda environment
conda create -n pytorch-xpu python=3.11 -y
conda activate pytorch-xpu

# 2. Install PyTorch with XPU support (stable release)
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/xpu

# --- OR for nightly builds ---
pip3 install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/xpu

# --- OR for a specific version (e.g. 2.10.0) ---
pip install torch==2.10.0 torchvision==0.25.0 torchaudio==2.10.0 --index-url https://download.pytorch.org/whl/xpu

# 3. Verify
python -c "import torch; print(torch.xpu.is_available()); print(torch.xpu.get_device_name(0))"

Python 版本说明：Python 3.10–3.12 经过充分测试。Python 3.13 在某些 XPU nightly 构建中有已知问题。

安装问题排查

现象	修复方法
torch.xpu.is_available() 返回 False	将 Intel GPU 驱动更新到最新版。在 Linux 上用 sycl-ls 验证，在 Windows 上用设备管理器验证。
AssertionError: Torch not compiled with XPU enabled	安装的是非 XPU wheel。用 --index-url https://download.pytorch.org/whl/xpu 重新安装。
Windows 上缺少 DLL 的导入错误	确保驱动安装时包含了 LevelZeroSDK。
Windows 上 torch.compile 失败	需要 PyTorch ≥ 2.7 + MSVC（Desktop Development with C++）。

代码使用

torch.xpu API 与 torch.cuda 几乎 1:1 对应。从 CUDA 迁移基本就是把 "cuda" 查找替换为 "xpu"。

详细的代码模式（推理、训练、AMP、torch.compile、内存管理、多设备、性能分析）见参考文件： → references/code-patterns.md — 覆盖所有 XPU 工作流的综合代码示例。

最小示例：

import torch

device = torch.device("xpu" if torch.xpu.is_available() else "cpu")

model = MyModel().to(device)
data = torch.randn(32, 3, 224, 224).to(device)

with torch.no_grad():
    output = model(data)

关键 API

函数	用途
torch.xpu.is_available()	检查 XPU 设备是否可用
torch.xpu.device_count()	Intel GPU 设备数量
torch.xpu.current_device()	当前选中设备的索引
torch.xpu.get_device_name(i)	设备名称字符串
torch.xpu.synchronize()	等待所有 kernel 完成
torch.xpu.empty_cache()	释放未使用的缓存内存
torch.xpu.memory_allocated()	当前内存占用（字节）
torch.xpu.max_memory_allocated()	峰值内存占用
torch.xpu.memory_stats()	分配器统计信息字典
torch.xpu.Stream()	创建计算流
torch.xpu.Event()	创建计时事件
torch.autocast(device_type="xpu")	启用 AMP
torch.amp.GradScaler(device="xpu")	AMP 训练的梯度缩放

重要注意事项

GradScaler 与 FP64：GradScaler 需要 FP64 硬件支持。Intel Arc A-Series 原生不支持 FP64。在 Arc A 系列上，使用 autocast 但不使用 GradScaler。
Windows 上的 torch.compile：从 PyTorch 2.7+ 开始支持。需要 MSVC（Visual Studio 2022，Desktop Development with C++ 工作负载）。
不需要 IPEX：新项目不要安装 intel-extension-for-pytorch。它已 EOL。直接使用原生 torch.xpu。
没有 conda XPU 包：始终在 conda 环境内使用 pip 并带上 --index-url https://download.pytorch.org/whl/xpu。

官方文档链接

资源	URL
torch.xpu API 参考	https://docs.pytorch.org/docs/stable/xpu.html
Intel GPU 入门	https://docs.pytorch.org/docs/stable/notes/get_start_xpu.html
Windows XPU 上的 torch.compile	https://docs.pytorch.org/tutorials/unstable/inductor_windows.html
Intel GPU 前置条件	https://www.intel.com/content/www/us/en/developer/articles/tool/pytorch-prerequisites-for-intel-gpu/2-11.html
Intel GPU 驱动（Windows）	https://www.intel.com/content/www/us/en/download/785597/intel-arc-iris-xe-graphics-windows.html
PyTorch 历史版本	https://pytorch.org/get-started/previous-versions/