Hugging Face Transformers 加速器选择指南用环境变量控制 CUDA 与 Intel XPU 的可见性与顺序【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers本指南围绕 Hugging Face Transformers 官方文档中的加速器选择主题讲解如何在分布式训练中通过硬件特定的环境变量精确控制 PyTorch 可见的加速器CUDA、Intel XPU 等及其识别顺序——既可以把更快设备排在前面以提升效率也可以把训练限制在部分硬件上。读完本文你将掌握CUDA_VISIBLE_DEVICES、CUDA_DEVICE_ORDER、ZE_AFFINITY_MASK等关键变量的完整用法并理解它们与 TransformersTrainer底层设备初始化逻辑training_args.py之间的配合关系。为什么需要显式控制加速器在一台拥有多张 GPU或 XPU的机器上PyTorch 默认按照自己的枚举顺序暴露全部设备。这在以下场景中会造成困扰多用户共享服务器某次任务只想占用 0 号和 2 号卡避免抢占他人正在使用的资源异构硬件希望优先使用算力更强的设备或把训练限定在特定型号上调试与回归让任务看不到GPU、强制走 CPU 路径以便复现纯 CPU 行为。官方文档给出的方案不依赖任何框架级封装它同时适用于 PyTorch 的 DistributedDataParallel文档中 DeepSpeed 主文档位于 deepspeed.md。机制非常简单——PyTorch 在启动时读取环境变量据此过滤和重排设备列表后续cuda:0、cuda:1等逻辑编号都基于过滤后的结果。设置环境变量的正确姿势文档给出了两条路径在每次运行的命令行上设置或写入~/.bashrc等启动配置文件。但官方文档特别强调[!WARNING] 尽量避免使用export方式持久化环境变量。一旦忘记变量是怎么设置的你可能会在错误的加速器上悄无声息地完成整个训练。请把环境变量写在训练命令的同一行。也就是说推荐做法是把变量作为命令前缀与训练命令写在同一行如CUDA_VISIBLE_DEVICES0,2 torchrun ...而不是export到 shell 会话或配置文件里。这能保证每次运行的环境是显式、可审计、可复现的。CUDA用 CUDA_VISIBLE_DEVICES 选择与排序 GPU选择部分 GPU假设机器上有四张 GPU编号 03只想使用其中的 0 号和 2 号只需把它们的物理编号以逗号分隔写入变量CUDA_VISIBLE_DEVICES0,2 torchrun trainer-program.py ...PyTorch 启动后只能看到0 号和 2 号 GPU并把它们分别映射为逻辑编号cuda:0和cuda:1原 1 号、3 号 GPU 对程序完全不可见。反转顺序让2 号卡成为 cuda:0变量的书写顺序直接决定逻辑映射顺序。想让物理 2 号 GPU 变成cuda:0、物理 0 号 GPU 变成cuda:1把列表顺序反过来即可CUDA_VISIBLE_DEVICES2,0 torchrun trainer-program.py ...这一特性非常实用例如需要让某个更快的卡承担主进程rank 0的工作或配合nn.DataParallel期望的 device 顺序使用。完全禁用 GPU把变量设为空值PyTorch 将看不到任何 GPU程序退化为 CPU 执行CUDA_VISIBLE_DEVICES python trainer-program.py ...这个用法在 Transformers 测试基础设施中同样出现——testing_utils.py 中注释 Set env var CUDA_VISIBLE_DEVICES to force cpu-mode说明设置空字符串是官方认可的强制 CPU 模式手段可用于复现 CPU 行为或跑纯 CPU 测试。用 CUDA_DEVICE_ORDER 控制枚举顺序CUDA_VISIBLE_DEVICES负责过滤 重排可见设备而CUDA_DEVICE_ORDER负责决定原始枚举顺序二者配合可以达成更精细的控制按 PCIe 总线 ID 排序与nvidia-smi的输出顺序一致export CUDA_DEVICE_ORDERPCI_BUS_ID按计算能力compute capability排序最快的设备排在前面export CUDA_DEVICE_ORDERFASTEST_FIRST注意文档示例中CUDA_DEVICE_ORDER仍以export形式给出因为它在进程启动前就需要生效但在实际训练中仍建议把它与训练命令写在同一行如CUDA_DEVICE_ORDERPCI_BUS_ID CUDA_VISIBLE_DEVICES0,2 torchrun ...遵循文档的警告原则。底层原理Trainer 如何消费设备可见性Transformers 的Trainer并不直接解析这些环境变量而是依赖accelerate的PartialState/AcceleratorState完成设备探测。在 training_args.py 的_setup_devices方法中可以看到完整的设备选择链若use_cpu为真或设置了ACCELERATE_USE_CPU强制cpu否则按优先级依次检查 XLATPU、MPS、XPU、MLU、MUSA、NPU、HPU、Neuron、TPU最后兜底逻辑是torch.device(cuda:0 if torch.cuda.is_available() else ...)源码注释明确写着 Default to cuda:0 (respects CUDA_VISIBLE_DEVICES)——即cuda:0是经过CUDA_VISIBLE_DEVICES过滤后的 0 号设备这正是前文物理 2 号卡被映射为cuda:0在框架层面的体现。因此可以推断环境变量在 PyTorch/torchrun层面生效Trainer无需任何额外参数即可感知你选定的设备集合。此外 training_args.py 表明 XPU 会被映射为xpu:0并调用torch.xpu.set_device与下一节 Intel XPU 的内容直接对应。Intel XPU用 ZE_AFFINITY_MASK 选择与排序设备对 Intel 数据中心 GPU通过 oneAPI Level Zero 暴露对应的控制变量是ZE_AFFINITY_MASK用法与 CUDA 完全对称ZE_AFFINITY_MASK0,2 torchrun trainer-program.py ...PyTorch 只能看到 0 号和 2 号 XPU并映射为逻辑编号xpu:0与xpu:1。反转顺序同样只需调换列表ZE_AFFINITY_MASK2,0 torchrun trainer-program.py ...Intel XPU 的枚举顺序则由另一个变量控制export ZE_ENABLE_PCI_ID_DEVICE_ORDER1关于 Intel XPU 设备枚举与排序的完整细节可参考 Level Zero 的官方说明设备枚举部分。在 Transformers 仓库中XPU 已是一等公民torch.xpu的相关工具函数如is_torch_xpu_available被大量模块引用见 utils 与 cli/system.py后者在打印环境信息时会报告 XPU type分布式后端映射中也有xpu: xccl的配置见 distributed/utils.py连续批处理continuous batching等新功能同样显式支持 XPU 上的 Flash Attention 2见 generation/continuous_batching/initialization.py。这些实现事实表明XPU 环境下的设备选择与 CUDA 一样被 Transformers 完整支持。实战组合建议共享服务器上只用自己的卡CUDA_VISIBLE_DEVICES2,3 torchrun trainer-program.py ...把最快卡设为主卡先CUDA_DEVICE_ORDERFASTEST_FIRST或用PCI_BUS_ID对齐nvidia-smi排查再按需用CUDA_VISIBLE_DEVICES指定子集强制 CPU 回归CUDA_VISIBLE_DEVICES python trainer-program.py ...Intel 平台ZE_AFFINITY_MASK0,2 torchrun trainer-program.py ...必要时加ZE_ENABLE_PCI_ID_DEVICE_ORDER1一致性原则始终把环境变量与训练命令写在同一行避免export造成不知道在哪台设备上跑的隐患。小结加速器选择是分布式训练的第一步也是最容易踩坑的一步。Transformers 官方文档给出的方案足够朴素且通用不依赖 Accelerate 或 DeepSpeed仅凭硬件特定的环境变量即可完成设备的过滤、排序与禁用。理解CUDA_VISIBLE_DEVICES、CUDA_DEVICE_ORDER与ZE_AFFINITY_MASK、ZE_ENABLE_PCI_ID_DEVICE_ORDER两组变量的语义再结合Trainer._setup_devicestraining_args.py的底层设备选择链你就能在多卡、异构甚至纯 CPU 场景下精确掌控每一次训练运行的硬件环境。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hugging Face Transformers 加速器选择指南：用环境变量控制 CUDA 与 Intel XPU 的可见性与顺序
Hugging Face Transformers 加速器选择指南用环境变量控制 CUDA 与 Intel XPU 的可见性与顺序【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers本指南围绕 Hugging Face Transformers 官方文档中的加速器选择主题讲解如何在分布式训练中通过硬件特定的环境变量精确控制 PyTorch 可见的加速器CUDA、Intel XPU 等及其识别顺序——既可以把更快设备排在前面以提升效率也可以把训练限制在部分硬件上。读完本文你将掌握CUDA_VISIBLE_DEVICES、CUDA_DEVICE_ORDER、ZE_AFFINITY_MASK等关键变量的完整用法并理解它们与 TransformersTrainer底层设备初始化逻辑training_args.py之间的配合关系。为什么需要显式控制加速器在一台拥有多张 GPU或 XPU的机器上PyTorch 默认按照自己的枚举顺序暴露全部设备。这在以下场景中会造成困扰多用户共享服务器某次任务只想占用 0 号和 2 号卡避免抢占他人正在使用的资源异构硬件希望优先使用算力更强的设备或把训练限定在特定型号上调试与回归让任务看不到GPU、强制走 CPU 路径以便复现纯 CPU 行为。官方文档给出的方案不依赖任何框架级封装它同时适用于 PyTorch 的 DistributedDataParallel文档中 DeepSpeed 主文档位于 deepspeed.md。机制非常简单——PyTorch 在启动时读取环境变量据此过滤和重排设备列表后续cuda:0、cuda:1等逻辑编号都基于过滤后的结果。设置环境变量的正确姿势文档给出了两条路径在每次运行的命令行上设置或写入~/.bashrc等启动配置文件。但官方文档特别强调[!WARNING] 尽量避免使用export方式持久化环境变量。一旦忘记变量是怎么设置的你可能会在错误的加速器上悄无声息地完成整个训练。请把环境变量写在训练命令的同一行。也就是说推荐做法是把变量作为命令前缀与训练命令写在同一行如CUDA_VISIBLE_DEVICES0,2 torchrun ...而不是export到 shell 会话或配置文件里。这能保证每次运行的环境是显式、可审计、可复现的。CUDA用 CUDA_VISIBLE_DEVICES 选择与排序 GPU选择部分 GPU假设机器上有四张 GPU编号 03只想使用其中的 0 号和 2 号只需把它们的物理编号以逗号分隔写入变量CUDA_VISIBLE_DEVICES0,2 torchrun trainer-program.py ...PyTorch 启动后只能看到0 号和 2 号 GPU并把它们分别映射为逻辑编号cuda:0和cuda:1原 1 号、3 号 GPU 对程序完全不可见。反转顺序让2 号卡成为 cuda:0变量的书写顺序直接决定逻辑映射顺序。想让物理 2 号 GPU 变成cuda:0、物理 0 号 GPU 变成cuda:1把列表顺序反过来即可CUDA_VISIBLE_DEVICES2,0 torchrun trainer-program.py ...这一特性非常实用例如需要让某个更快的卡承担主进程rank 0的工作或配合nn.DataParallel期望的 device 顺序使用。完全禁用 GPU把变量设为空值PyTorch 将看不到任何 GPU程序退化为 CPU 执行CUDA_VISIBLE_DEVICES python trainer-program.py ...这个用法在 Transformers 测试基础设施中同样出现——testing_utils.py 中注释 Set env var CUDA_VISIBLE_DEVICES to force cpu-mode说明设置空字符串是官方认可的强制 CPU 模式手段可用于复现 CPU 行为或跑纯 CPU 测试。用 CUDA_DEVICE_ORDER 控制枚举顺序CUDA_VISIBLE_DEVICES负责过滤 重排可见设备而CUDA_DEVICE_ORDER负责决定原始枚举顺序二者配合可以达成更精细的控制按 PCIe 总线 ID 排序与nvidia-smi的输出顺序一致export CUDA_DEVICE_ORDERPCI_BUS_ID按计算能力compute capability排序最快的设备排在前面export CUDA_DEVICE_ORDERFASTEST_FIRST注意文档示例中CUDA_DEVICE_ORDER仍以export形式给出因为它在进程启动前就需要生效但在实际训练中仍建议把它与训练命令写在同一行如CUDA_DEVICE_ORDERPCI_BUS_ID CUDA_VISIBLE_DEVICES0,2 torchrun ...遵循文档的警告原则。底层原理Trainer 如何消费设备可见性Transformers 的Trainer并不直接解析这些环境变量而是依赖accelerate的PartialState/AcceleratorState完成设备探测。在 training_args.py 的_setup_devices方法中可以看到完整的设备选择链若use_cpu为真或设置了ACCELERATE_USE_CPU强制cpu否则按优先级依次检查 XLATPU、MPS、XPU、MLU、MUSA、NPU、HPU、Neuron、TPU最后兜底逻辑是torch.device(cuda:0 if torch.cuda.is_available() else ...)源码注释明确写着 Default to cuda:0 (respects CUDA_VISIBLE_DEVICES)——即cuda:0是经过CUDA_VISIBLE_DEVICES过滤后的 0 号设备这正是前文物理 2 号卡被映射为cuda:0在框架层面的体现。因此可以推断环境变量在 PyTorch/torchrun层面生效Trainer无需任何额外参数即可感知你选定的设备集合。此外 training_args.py 表明 XPU 会被映射为xpu:0并调用torch.xpu.set_device与下一节 Intel XPU 的内容直接对应。Intel XPU用 ZE_AFFINITY_MASK 选择与排序设备对 Intel 数据中心 GPU通过 oneAPI Level Zero 暴露对应的控制变量是ZE_AFFINITY_MASK用法与 CUDA 完全对称ZE_AFFINITY_MASK0,2 torchrun trainer-program.py ...PyTorch 只能看到 0 号和 2 号 XPU并映射为逻辑编号xpu:0与xpu:1。反转顺序同样只需调换列表ZE_AFFINITY_MASK2,0 torchrun trainer-program.py ...Intel XPU 的枚举顺序则由另一个变量控制export ZE_ENABLE_PCI_ID_DEVICE_ORDER1关于 Intel XPU 设备枚举与排序的完整细节可参考 Level Zero 的官方说明设备枚举部分。在 Transformers 仓库中XPU 已是一等公民torch.xpu的相关工具函数如is_torch_xpu_available被大量模块引用见 utils 与 cli/system.py后者在打印环境信息时会报告 XPU type分布式后端映射中也有xpu: xccl的配置见 distributed/utils.py连续批处理continuous batching等新功能同样显式支持 XPU 上的 Flash Attention 2见 generation/continuous_batching/initialization.py。这些实现事实表明XPU 环境下的设备选择与 CUDA 一样被 Transformers 完整支持。实战组合建议共享服务器上只用自己的卡CUDA_VISIBLE_DEVICES2,3 torchrun trainer-program.py ...把最快卡设为主卡先CUDA_DEVICE_ORDERFASTEST_FIRST或用PCI_BUS_ID对齐nvidia-smi排查再按需用CUDA_VISIBLE_DEVICES指定子集强制 CPU 回归CUDA_VISIBLE_DEVICES python trainer-program.py ...Intel 平台ZE_AFFINITY_MASK0,2 torchrun trainer-program.py ...必要时加ZE_ENABLE_PCI_ID_DEVICE_ORDER1一致性原则始终把环境变量与训练命令写在同一行避免export造成不知道在哪台设备上跑的隐患。小结加速器选择是分布式训练的第一步也是最容易踩坑的一步。Transformers 官方文档给出的方案足够朴素且通用不依赖 Accelerate 或 DeepSpeed仅凭硬件特定的环境变量即可完成设备的过滤、排序与禁用。理解CUDA_VISIBLE_DEVICES、CUDA_DEVICE_ORDER与ZE_AFFINITY_MASK、ZE_ENABLE_PCI_ID_DEVICE_ORDER两组变量的语义再结合Trainer._setup_devicestraining_args.py的底层设备选择链你就能在多卡、异构甚至纯 CPU 场景下精确掌控每一次训练运行的硬件环境。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考