Transformers documentation

Intel GPU

You are viewing v5.23.0 version. A newer version v5.24.0 is available.
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Intel GPU

Intel GPU 通过 XPU 后端运行 PyTorch,设备字符串为 xpu。PyTorch 的 XPU 构建来自独立的软件包索引,因此下方的安装命令将其作为额外的索引添加。

安装

安装 PyTorch 的 Intel GPU 驱动程序,然后运行 xpu-smi 以检查系统是否检测到 GPU。

从 XPU 索引安装 PyTorch,并同时安装 Transformers。

pip install "transformers[torch]" --extra-index-url https://download.pytorch.org/whl/xpu

检查 PyTorch 是否能够识别 GPU。

import torch

print(torch.xpu.is_available(), torch.xpu.device_count())

它会打印 True 以及 GPU 的数量,例如 True 2。

选择和排序 XPU

使用 ZE_AFFINITY_MASK 环境变量来选择 XPU。请将其与运行命令放在同一命令行中设置,因为忘记取消导出的变量可能会悄无声息地将后续运行发送到错误的 XPU 上。

例如,要从四个 XPU 中选择 0 号和 2 号:

ZE_AFFINITY_MASK=0,2 torchrun trainer-program.py ...

PyTorch 仅识别 XPU 0 和 2。ZE_AFFINITY_MASK 中值的顺序不会改变 PyTorch 枚举它们的顺序。为了在多次运行中保持一致的顺序,请同时设置 ZE_ENABLE_PCI_ID_DEVICE_ORDER=1,该设置会按 PCI 总线 ID 从低到高的顺序报告设备。

ZE_ENABLE_PCI_ID_DEVICE_ORDER=1 ZE_AFFINITY_MASK=0,2 torchrun trainer-program.py ...

有关设备枚举的更多信息,请参阅 Level Zero 规范。

选择注意力后端

在加载模型时,您通过 attn_implementation 设置注意力后端,该设置同时适用于推理和训练。模型默认使用 SDPA。在 PyTorch 2.8 或更高版本中,XPU 上的 SDPA 可以直接处理分组查询注意力,而无需先重复键和值头。

attn_implementation="flash_attention_2" 会从 Hub 加载 kernels-community/flash-attn2,该库提供了 XPU 构建版本。请安装 kernels 附加组件以使用它。FlashAttention-3 和 FlashAttention-4 仅支持在 NVIDIA GPU 上运行。

pip install "transformers[kernels]"
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    dtype="bfloat16",
    device_map="xpu",
    attn_implementation="flash_attention_2",
)

运行推理

将 device_map="auto" 传递给 from_pretrained(),可将无法装入单个 XPU 的模型拆分到可用的多个 XPU 上;或者使用 device_map="xpu" 将其加载到单个 XPU 上。如果未传递 device,pipeline() 会自动选择一个 XPU。

from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-0.6B", dtype="bfloat16", device_map="xpu")
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-0.6B")

inputs = tokenizer("Intel GPUs are", return_tensors="pt").to(model.device)
output = model.generate(**inputs, max_new_tokens=50, do_sample=False)
print(tokenizer.decode(output[0], skip_special_tokens=True))

连续批处理支持 Intel GPU 上的 XPU 图和异步批处理,并会自动决定是否使用它们。

使用 Hub 内核

在 from_pretrained() 中设置 use_kernels=True,即可用 Hub 上的优化内核替换受支持的层。Intel GPU 覆盖的层与 NVIDIA GPU 基本一致,例如激活函数、RMSNorm 和旋转位置编码。请安装 kernels 附加组件以使用这些内核。

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B", dtype="bfloat16", device_map="xpu", use_kernels=True
)

Hub 内核同样适用于训练。调用 model.train() 或 model.eval() 会切换为该模式对应的内核。若要自行选择内核,请传入 KernelConfig,并使用 "xpu" 作为设备键,以指定 XPU 专属的映射。完整的映射关系请参阅 加载内核。

量化模型

量化可以让更大的模型装入 GPU 内存。请查看量化概述中的 Intel GPU 列,以了解可在 XPU 上运行的方法。

要微调无法装入 GPU 显存的模型,请使用 bitsandbytes 以 4-bit 精度加载模型,并使用 PEFT 训练 LoRA 适配器。

使用 Trainer 进行训练

TrainingArguments 会检测 Intel GPU 并将设备设置为 xpu,因此 Trainer 无需任何设备设置即可在其上训练。TrainingArguments 通过 torch.xpu.is_bf16_supported() 检查 bf16 支持情况,如果 GPU 不支持,则会抛出 ValueError。

from transformers import TrainingArguments

training_args = TrainingArguments(
    output_dir="./outputs",
    bf16=True,
)
print(training_args.device)

当 Trainer 将在单个 XPU 上进行训练时,它会打印 xpu:0。

分布式训练

分布式训练使用 xccl 集合通信后端。使用 torchrun 或 accelerate launch 为每个 XPU 启动一个进程。

torchrun --nproc_per_node=2 train.py

请参阅 DDP、FSDP2、DeepSpeed ZeRO 和 Tensor parallelism,以选择合适的并行策略。

后续步骤

Update on GitHub