PyTorch 在 Intel GPU（XPU）上快速上手：安装、迁移与推理训练实战指南

PyTorch 在 Intel GPU（XPU）上快速上手：安装、迁移与推理训练实战指南

【免费下载链接】pytorchTensors and Dynamic neural networks in Python with strong GPU acceleration项目地址: https://gitcode.com/GitHub_Trending/py/pytorch

本指南以 PyTorch 官方文档 docs/source/notes/get_start_xpu.md 为核心主体，系统讲解如何在 Intel Data Center GPU 与 Intel 客户端 GPU 上启用 PyTorch 的 XPU 后端：从硬件/软件前置条件、二进制与源码安装，到cuda→xpu的最小代码迁移、可用性检查，以及覆盖 FP32、AMP、torch.compile三种模式的完整推理与训练示例。读完本文，你将能够独立完成 Intel GPU 环境的搭建，并把现有 CUDA 代码以最小改动迁移到 Intel GPU 上运行。

硬件前置要求

Intel Data Center GPU

PyTorch 的 XPU 后端首先面向 Intel 数据中心 GPU 验证，官方文档给出的设备与操作系统组合如下：

Intel Client GPU

在客户端 GPU 一侧，支持的 OS 与已验证硬件覆盖了 Intel 近几代 Arc 独立显卡与核显：

Intel GPU 支持（Prototype 原型阶段）自 PyTorch* 2.5 起就绪，覆盖上述 Intel 客户端 GPU 与 Intel Data Center GPU Max Series，在 Linux 和 Windows 上均可用。它把 Intel GPU 与 SYCL* 软件栈引入官方 PyTorch 技术栈，提供与 CUDA 一致的使用体验。

软件前置要求

要在 Intel GPU 上使用 PyTorch，需要先安装 Intel GPU 驱动。官方安装指南（Intel GPUs Driver Installation）会给出针对各操作系统与设备型号的驱动安装步骤，请在安装 PyTorch 前完成驱动验证。

需要注意的安装分支：

• 通过预编译二进制（wheel）安装时，可以跳过 Intel® Deep Learning Essentials（DL Essentials）的安装；
• 从源码构建时，则需要同时安装 Intel GPU Driver 与 Intel® Deep Learning Essentials（具体参见 PyTorch Installation Prerequisites for Intel GPUs）。

安装

通过二进制 wheel 安装

安装完 Intel GPU 驱动后，即可安装torch、torchvision、torchaudio三个包。PyTorch 为 Intel GPU（XPU）提供了独立的 wheel 索引。

Stable 稳定版

安装最新的稳定版 XPU wheel：

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/xpu

Nightly 每日构建版

安装最新预览/每日构建 wheel：

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

历史版本

安装带 Intel GPU（XPU）支持的旧版本时，前往 previous versions 页面找到对应版本号，同样使用xpu索引：

pip3 install torch==TORCH_VERSION torchvision==TORCHVISION_VERSION torchaudio==TORCHAUDIO_VERSION --index-url https://download.pytorch.org/whl/xpu

其中TORCH_VERSION、TORCHVISION_VERSION、TORCHAUDIO_VERSION需替换为彼此匹配的具体版本号（例如2.5.0，且三者需保持一致或按官方版本对应关系选择）。

从源码构建

在安装好 Intel GPU Driver 与 Intel® Deep Learning Essentials 后，可以按各自项目的官方源码构建指南编译：

• torch：参考 PyTorch 仓库 README 中的 "From source" 一节，构建时需启用 XPU 支持相关的构建选项（当前仓库根目录的 setup.py、CMakeLists.txt 与 cmake/ 目录包含了完整的构建配置）；
• torchvision：参考 Torchvision 仓库 CONTRIBUTING 中的 Development Installation；
• torchaudio：参考 Torchaudio 仓库 CONTRIBUTING 中的 Building torchaudio from source。

检查 Intel GPU 是否可用

安装完成后，用下面的代码确认 XPU 后端是否识别到你的 Intel GPU：

import torch print(torch.xpu.is_available()) # torch.xpu 是 Intel GPU 支持的 API

如果输出为False，请复查 Intel GPU 驱动是否正确安装。

从源码实现看，torch.xpu.is_available()实际上是device_count() > 0的封装（见 torch/xpu/init.py）。device_count()在未初始化时优先通过 Level Zero Sysman（pyzes）枚举可见设备，并解析ZE_AFFINITY_MASK环境变量来确定可见设备序号；只有在 XPU 编译支持缺失（_is_compiled()为假）时才直接返回 0。XPU 模块采用懒初始化设计，is_available()与device_count()都不会主动触发设备初始化，因此你可以在任意环境安全地调用它们来判断平台能力。

最小代码改动：从 CUDA 迁移到 Intel GPU

如果你正从cuda迁移代码，核心操作就是把设备名从cuda替换为xpu。例如：

# CUDA 代码 tensor = torch.tensor([1.0, 2.0]).to("cuda") # Intel GPU 代码 tensor = torch.tensor([1.0, 2.0]).to("xpu")

在 torch/xpu/ 包中，你可以找到与 CUDA 后端一一对应的 API 族：

• torch/xpu/init.py：device、device_of、set_device、current_device、synchronize、stream、current_stream、get_device_name、get_device_properties、init、is_initialized等核心设备管理与流 API；
• torch/xpu/memory.py：empty_cache、reset_peak_memory_stats、memory_stats_as_nested_dict等内存统计与管理 API；
• torch/xpu/streams.py：Stream、Event；
• torch/xpu/graphs.py：XPUGraph、graph、make_graphed_callables等图捕获 API；
• torch/xpu/random.py：manual_seed、seed、get_rng_state等随机数 API。

完整 API 清单可在 docs/source/xpu.md 的 autosummary 中找到，包括get_gencode_flags、get_arch_list、is_bf16_supported、is_tf32_supported、temperature、clock_rate、utilization、can_device_access_peer等扩展接口。

支持能力与限制

以下要点概括了 PyTorch + Intel GPU 的支持范围：

1. 训练与推理工作流均受支持；
2. eager 模式与torch.compile均受支持。torch.compile在 Windows 上的 Intel GPU 支持自 PyTorch* 2.7 起可用（可参考 torch.compiler 的 Windows CPU/XPU 使用教程，见 docs/source/user_guide/torch_compiler/torch.compiler_get_started.md）；
3. FP32、BF16、FP16 以及自动混合精度（AMP）全部受支持。

在 test/test_xpu.py 中，测试套件覆盖了上述能力矩阵：包括torch.amp.autocast在 XPU 上的 FP16/BF16 行为测试（test_autocast_torch_fp16、test_autocast_torch_bf16等）、torch.amp.GradScaler(device="xpu")的梯度缩放训练测试，以及多设备（TEST_MULTIXPU）行为验证。测试还使用instantiate_device_type_tests把通用算子测试实例化到xpu设备上运行，印证了 XPU 后端与 CUDA 后端共享同一套算子测试体系。

推理示例

以下示例使用 torchvision 的 ResNet50，演示三种推理工作流。运行前请确保已完成 通过二进制 wheel 安装 中的安装步骤。

FP32 推理

import torch import torchvision.models as models model = models.resnet50(weights="ResNet50_Weights.DEFAULT") model.eval() data = torch.rand(1, 3, 224, 224) model = model.to("xpu") data = data.to("xpu") with torch.no_grad(): model(data) print("Execution finished")

AMP 推理

import torch import torchvision.models as models model = models.resnet50(weights="ResNet50_Weights.DEFAULT") model.eval() data = torch.rand(1, 3, 224, 224) model = model.to("xpu") data = data.to("xpu") with torch.no_grad(): d = torch.rand(1, 3, 224, 224) d = d.to("xpu") # 设置 dtype=torch.bfloat16 以使用 BF16 with torch.autocast(device_type="xpu", dtype=torch.float16, enabled=True): model(data) print("Execution finished")

注意torch.autocast(device_type="xpu", ...)的用法与 CUDA 一致：只需把device_type换成"xpu"，即可把 FP16（或通过dtype=torch.bfloat16切换为 BF16）的自动混合精度能力应用于 Intel GPU。

使用torch.compile的推理

import torch import torchvision.models as models import time model = models.resnet50(weights="ResNet50_Weights.DEFAULT") model.eval() data = torch.rand(1, 3, 224, 224) ITERS = 10 model = model.to("xpu") data = data.to("xpu") for i in range(ITERS): start = time.time() with torch.no_grad(): model(data) torch.xpu.synchronize() end = time.time() print(f"Inference time before torch.compile for iteration {i}: {(end-start)*1000} ms") model = torch.compile(model) for i in range(ITERS): start = time.time() with torch.no_grad(): model(data) torch.xpu.synchronize() end = time.time() print(f"Inference time after torch.compile for iteration {i}: {(end-start)*1000} ms") print("Execution finished")

在衡量耗时前调用torch.xpu.synchronize()是必要的：XPU 内核是异步入队执行的，synchronize()（底层为torch._C._xpu_synchronize，见 torch/xpu/init.py）会等待当前设备上所有流的全部内核完成，从而保证计时包含真实的设备执行时间。

训练示例

以下示例在 CIFAR-10 数据集上以 ResNet50 训练一个 epoch，演示三种训练工作流，并包含模型与优化器状态保存。

FP32 训练

import torch import torchvision LR = 0.001 DOWNLOAD = True DATA = "datasets/cifar10/" transform = torchvision.transforms.Compose( [ torchvision.transforms.Resize((224, 224)), torchvision.transforms.ToTensor(), torchvision.transforms.Normalize((0.5, 0.5, 0.5), (0.5, 0.5, 0.5)), ] ) train_dataset = torchvision.datasets.CIFAR10( root=DATA, train=True, transform=transform, download=DOWNLOAD, ) train_loader = torch.utils.data.DataLoader(dataset=train_dataset, batch_size=128) train_len = len(train_loader) model = torchvision.models.resnet50() criterion = torch.nn.CrossEntropyLoss() optimizer = torch.optim.SGD(model.parameters(), lr=LR, momentum=0.9) model.train() model = model.to("xpu") criterion = criterion.to("xpu") print(f"Initiating training") for batch_idx, (data, target) in enumerate(train_loader): data = data.to("xpu") target = target.to("xpu") optimizer.zero_grad() output = model(data) loss = criterion(output, target) loss.backward() optimizer.step() if (batch_idx + 1) % 10 == 0: iteration_loss = loss.item() print(f"Iteration [{batch_idx+1}/{train_len}], Loss: {iteration_loss:.4f}") torch.save( { "model_state_dict": model.state_dict(), "optimizer_state_dict": optimizer.state_dict(), }, "checkpoint.pth", ) print("Execution finished")

AMP 训练

使用 `GradScaler` 训练需要硬件对 `FP64` 的支持。Intel® Arc™ A-Series Graphics 不原生支持 `FP64`。如果你在 Intel® Arc™ A-Series Graphics 上运行负载，请禁用 `GradScaler`。

import torch import torchvision LR = 0.001 DOWNLOAD = True DATA = "datasets/cifar10/" use_amp=True transform = torchvision.transforms.Compose( [ torchvision.transforms.Resize((224, 224)), torchvision.transforms.ToTensor(), torchvision.transforms.Normalize((0.5, 0.5, 0.5), (0.5, 0.5, 0.5)), ] ) train_dataset = torchvision.datasets.CIFAR10( root=DATA, train=True, transform=transform, download=DOWNLOAD, ) train_loader = torch.utils.data.DataLoader(dataset=train_dataset, batch_size=128) train_len = len(train_loader) model = torchvision.models.resnet50() criterion = torch.nn.CrossEntropyLoss() optimizer = torch.optim.SGD(model.parameters(), lr=LR, momentum=0.9) scaler = torch.amp.GradScaler(device="xpu", enabled=use_amp) model.train() model = model.to("xpu") criterion = criterion.to("xpu") print(f"Initiating training") for batch_idx, (data, target) in enumerate(train_loader): data = data.to("xpu") target = target.to("xpu") # 设置 dtype=torch.bfloat16 以使用 BF16 with torch.autocast(device_type="xpu", dtype=torch.float16, enabled=use_amp): output = model(data) loss = criterion(output, target) scaler.scale(loss).backward() scaler.step(optimizer) scaler.update() optimizer.zero_grad() if (batch_idx + 1) % 10 == 0: iteration_loss = loss.item() print(f"Iteration [{batch_idx+1}/{train_len}], Loss: {iteration_loss:.4f}") torch.save( { "model_state_dict": model.state_dict(), "optimizer_state_dict": optimizer.state_dict(), }, "checkpoint.pth", ) print("Execution finished")

AMP 训练的关键差异点：

• torch.amp.GradScaler(device="xpu", enabled=use_amp)：为 XPU 设备创建梯度缩放器，enabled=False时可直接关闭缩放；
• 前向与损失计算放入torch.autocast(device_type="xpu", dtype=torch.float16, enabled=use_amp)上下文；
• 反向传播使用scaler.scale(loss).backward()，随后scaler.step(optimizer)与scaler.update()，与 CUDA 训练完全同构。

使用torch.compile的训练

import torch import torchvision LR = 0.001 DOWNLOAD = True DATA = "datasets/cifar10/" transform = torchvision.transforms.Compose( [ torchvision.transforms.Resize((224, 224)), torchvision.transforms.ToTensor(), torchvision.transforms.Normalize((0.5, 0.5, 0.5), (0.5, 0.5, 0.5)), ] ) train_dataset = torchvision.datasets.CIFAR10( root=DATA, train=True, transform=transform, download=DOWNLOAD, ) train_loader = torch.utils.data.DataLoader(dataset=train_dataset, batch_size=128) train_len = len(train_loader) model = torchvision.models.resnet50() criterion = torch.nn.CrossEntropyLoss() optimizer = torch.optim.SGD(model.parameters(), lr=LR, momentum=0.9) model.train() model = model.to("xpu") criterion = criterion.to("xpu") model = torch.compile(model) print(f"Initiating training with torch compile") for batch_idx, (data, target) in enumerate(train_loader): data = data.to("xpu") target = target.to("xpu") optimizer.zero_grad() output = model(data) loss = criterion(output, target) loss.backward() optimizer.step() if (batch_idx + 1) % 10 == 0: iteration_loss = loss.item() print(f"Iteration [{batch_idx+1}/{train_len}], Loss: {iteration_loss:.4f}") torch.save( { "model_state_dict": model.state_dict(), "optimizer_state_dict": optimizer.state_dict(), }, "checkpoint.pth", ) print("Execution finished")

torch.compile训练与 FP32 训练的差异仅在于把模型搬到 XPU 后追加一行model = torch.compile(model)，其余训练循环保持不变。首次迭代会触发图编译，后续迭代在编译产物上执行。

深入torch.xpu：源码视角的 API 全景

前面示例反复使用的torch.xpu包（torch/xpu/init.py）是 Intel GPU 支持的统一入口，理解其设计有助于排查问题与扩展用法。

懒初始化与设备枚举

• 模块注释明确说明：XPU 包是懒初始化的，任何时候都可以 import，并用is_available()判断系统是否支持 XPU（torch/xpu/init.py 头部 docstring）；
• _lazy_init()在首次访问设备相关 API 时触发torch._C._xpu_init()，并把初始化前排队的惰性调用（如种子设置）一并执行；
• _parse_visible_devices()解析ZE_AFFINITY_MASK环境变量：未设置时默认可见全部 128 个设备序号（int8_t设备索引上限）；设置为"0,1,2"这类逗号分隔整数时只暴露对应设备；遇到 COMPOSITE 格式（如"0.0,0.1"）则视为不支持并返回空列表；
• device_count()在初始化前通过 Level Zero Sysman（pyzes）枚举可见设备，且初始化前不缓存设备数——因为ZE_AFFINITY_MASK在初始化前仍可能变化（torch/xpu/init.py）。

设备与流管理

• torch.xpu.device(idx)、device_of(obj)、set_device()、current_device()提供了与torch.cuda同构的设备上下文管理；
• torch.xpu.stream(stream)上下文管理器（StreamContext）让上下文内的内核统一入队到指定流；current_stream()返回当前流；get_stream_from_external(data_ptr)可以包装其他库创建的 SYCL 队列为Stream，便于多库协同；
• synchronize()等待设备上所有内核完成，是性能计时与结果确认的关键同步点。

设备属性与能力查询

get_device_properties()返回_XpuDeviceProperties，字段涵盖：设备名、SYCL 平台名、厂商、驱动版本、最大计算单元数、EU 数量、内存时钟与总线位宽、子组大小列表、FP16/FP64/原子 64 位支持、BF16 转换能力、DPAS 矩阵乘加（TF32）能力、是否集成 GPU、总显存等（完整字段清单见 torch/xpu/init.py）。基于这些字段，is_bf16_supported()与is_tf32_supported()可以动态判断当前设备的数据类型能力。

内存管理

torch/xpu/memory.py 提供了缓存分配器的管理与统计接口：empty_cache()释放空闲缓存内存以减少碎片；reset_peak_memory_stats()、reset_accumulated_memory_stats()、memory_stats_as_nested_dict()用于跟踪与重置分配/释放/峰值统计；此外还支持可插拔分配器（XPUPluggableAllocator、change_current_allocator，见 docs/source/xpu.md 的 Memory management 一节）。

测试验证

test/test_xpu.py（共 3988 行）是 XPU 后端最完整的验证样本：TestXpu测试类覆盖设备行为、多设备切换、图捕获、内存统计等基础能力；TestAutocast系列验证 FP16/BF16 autocast 行为；GradScaler相关测试（含图捕获场景下的缩放器）验证 AMP 训练路径；instantiate_device_type_tests把通用算子测试实例化到xpu设备，从算子层面保证功能一致性。如果你在本机启用 XPU，可通过python test/test_xpu.py运行这组测试来验证环境。

常见问题排查

• torch.xpu.is_available()返回False：优先复查 Intel GPU 驱动是否安装并加载成功；确认当前 PyTorch 版本为 2.5 及以上且安装的是xpu索引的 wheel（pip3 list检查torch构建来源）；在多设备机器上确认ZE_AFFINITY_MASK未把目标设备排除。
• 编译产物不包含 XPU：_is_compiled()返回torch._C._has_xpu，如果为假说明当前安装的 PyTorch 未启用 XPU 编译选项，需要改用官方xpuwheel 或按"从源码构建"一节启用 XPU 支持重新编译。
• GradScaler训练异常：检查目标硬件是否支持 FP64。Intel® Arc™ A-Series Graphics 不原生支持 FP64，按文档要求禁用GradScaler（enabled=False）后改用常规训练循环。
• 性能计时不准确：计时前调用torch.xpu.synchronize()，确保异步内核执行完成后再读取墙钟时间。

结语

从本指南可以看到，PyTorch 的 Intel GPU（XPU）支持遵循"与 CUDA 体验一致"的设计原则：安装只需切换 wheel 索引，迁移只需把cuda换成xpu，AMP 与torch.compile能力矩阵完整对齐。无论你面向 Intel Data Center GPU Max Series 还是 Arc 客户端 GPU，都可以用本文提供的四类示例（FP32/AMP/torch.compile× 推理/训练）作为起点，快速把既有工作负载跑通在 Intel GPU 之上。

【免费下载链接】pytorchTensors and Dynamic neural networks in Python with strong GPU acceleration项目地址: https://gitcode.com/GitHub_Trending/py/pytorch