intel/intel-optimized-pytorch

Intel® Extension for PyTorch* Docker镜像文档

镜像概述和主要用途

[Intel® Extension for PyTorch*] 扩展了 [PyTorch*]，提供针对Intel硬件的最新特性优化，以获得额外的性能提升。本镜像基于 https://hub.docker.com/_/ubuntu 构建，包含不同用例的Intel® Extension for PyTorch*以及其他附加软件，旨在为Intel架构提供优化的PyTorch运行环境。

注意： 有两个Docker Hub仓库（intel/intel-extension-for-pytorch 和 intel/intel-optimized-pytorch）会定期更新最新镜像，但部分旧版镜像可能未发布到两个仓库。

核心功能和特性

CPU优化

利用以下指令集优化Intel CPU性能：

• Intel® Advanced Matrix Extensions (Intel® AMX)
• Intel® Advanced Vector Extensions 512 (Intel® AVX-512)
• Vector Neural Network Instructions (VNNI)

GPU优化

通过PyTorch* xpu设备提供简单的GPU加速，支持以下Intel GPU：

• [Intel® Arc™ A-Series Graphics]
• [Intel® Data Center GPU Flex Series]
• [Intel® Data Center GPU Max Series]

使用场景和适用范围

本镜像适用于需要在Intel CPU和GPU上运行PyTorch工作负载的场景，包括但不限于：

• 深度学习模型训练与推理
• 大规模分布式训练
• Jupyter Notebook交互式开发
• 生产环境模型部署（通过TorchServe*）
• MLPerf优化工作负载

详细的使用方法和配置说明

镜像类型

XPU镜像

同时包含CPU和GPU优化支持的镜像：

运行XPU容器：

bash
docker run -it --rm \
    --device /dev/dri \
    -v /dev/dri/by-path:/dev/dri/by-path \
    --ipc=host \
    intel/intel-extension-for-pytorch:2.8.10-xpu

包含Jupyter Notebook的XPU镜像

运行XPU Jupyter容器：

bash
docker run -it --rm \
    -p 8888:8888 \
    --device /dev/dri \
    -v /dev/dri/by-path:/dev/dri/by-path \
    intel/intel-extension-for-pytorch:2.8.10-xpu-pip-jupyter

运行命令后，复制类似 http://127.0.0.1:$PORT/?token=*** 的URL到浏览器以访问notebook服务器。

CPU-only镜像

仅包含CPU优化（刻意排除GPU加速支持）的镜像：

运行CPU容器：

bash
docker run -it --rm intel/intel-extension-for-pytorch:latest

包含Jupyter Notebook的CPU-only镜像

运行Jupyter容器：

bash
docker run -it --rm \
    -p 8888:8888 \
    -v $PWD/workspace:/workspace \
    -w /workspace \
    intel/intel-extension-for-pytorch:2.8.0-pip-jupyter

包含Intel® oneAPI Collective Communications Library和Neural Compressor的镜像

注意： 镜像中已启用无密码SSH连接，但容器不包含任何SSH ID密钥。用户需要将这些密钥挂载到 /root/.ssh/id_rsa 和 /etc/ssh/authorized_keys。

提示： 挂载任何密钥之前，请使用 chmod 600 authorized_keys; chmod 600 id_rsa 修改文件权限，以授予默认用户账户读取权限。

配置和运行IPEX多节点容器

重要提示： Intel® Extension for PyTorch* 多节点容器对Xeon处理器的维护、错误修复和发布已停止开发。最后支持的版本是 2.4.0。对于未来版本，请使用Intel® Extension for PyTorch* XPU多节点容器。

1. 生成SSH密钥

   bash
   ssh-keygen -q -N "" -t rsa -b 4096 -f ./id_rsa
   touch authorized_keys
   cat id_rsa.pub >> authorized_keys
   

2. 配置文件权限

   bash
   chmod 600 id_rsa config authorized_keys
   chown root:root id_rsa.pub id_rsa config authorized_keys
   

3. 创建hostfile（可选）

   txt
   Host host1
       HostName <host1的主机名>
       IdentitiesOnly yes
       IdentityFile ~/.root/id_rsa
       Port <SSH端口>
   Host host2
       HostName <host2的主机名>
       IdentitiesOnly yes
       IdentityFile ~/.root/id_rsa
       Port <SSH端口>
   ...
   

4. 在Python脚本中配置Intel® oneAPI Collective Communications Library

   python
   import oneccl_bindings_for_pytorch
   import os
   
   dist.init_process_group(
       backend="ccl",
       init_method="tcp://127.0.0.1:3022",
       world_size=int(os.environ.get("WORLD_SIZE")),
       rank=int(os.environ.get("RANK")),
   )
   

5. 启动worker并在launcher上执行DDP

   Worker运行命令：

   bash
   docker run -it --rm \
       --net=host \
       -v $PWD/authorized_keys:/etc/ssh/authorized_keys \
       -v $PWD/tests:/workspace/tests \
       -w /workspace \
       intel/intel-extension-for-pytorch:2.4.0-pip-multinode \
       bash -c '/usr/sbin/sshd -D'
   

   Launcher运行命令：

   bash
   docker run -it --rm \
       --net=host \
       -v $PWD/id_rsa:/root/.ssh/id_rsa \
       -v $PWD/tests:/workspace/tests \
       -v $PWD/hostfile:/workspace/hostfile \
       -w /workspace \
       intel/intel-extension-for-pytorch:2.4.0-pip-multinode \
       bash -c 'ipexrun cpu  --nnodes 2 --nprocs-per-node 1 --master-addr 127.0.0.1 --master-port 3022 /workspace/tests/ipex-resnet50.py --ipex --device cpu --backend ccl'