腾讯云 HyperAcc 训练加速套件（以下简称 HyperAcc）面向 PyTorch 训练任务提供训练加速能力。您获取已编译的 wheel 安装包后，可通过安装 Python 包、配置环境变量、在训练入口导入激活模块的方式接入，在兼容场景下，无需改造训练框架。
本文介绍如何在已获取 HyperAcc wheel 安装包的情况下，完成首次安装和训练任务接入。
前提条件
开始前，请确认已具备以下条件：
条件 | 说明 |
wheel 安装包 | |
Python 环境 | Python 3.8 及以上版本，且需要与 wheel 包匹配。 |
PyTorch 环境 | PyTorch 2.0 及以上版本，且训练脚本已可在当前环境中正常运行。 |
系统权限 | 如需启用透明大页，可能需要系统写权限或管理员预配置。 |
操作步骤
步骤1：安装 HyperAcc
在训练环境中执行以下命令，安装 HyperAcc wheel 包：
pip install /path/to/hyperacc-*.whl
安装完成后，执行以下命令检查 Python 包是否可正常导入：
python -c "import hyperacc.auto; print('hyperacc auto import ok')"
步骤2：启用加速能力
如需快速体验全部能力，可设置总开关：
export HA_USE_ALL=1
如需按需启用能力，可设置单项开关：
export HA_USE_COMPILE=1export HA_USE_GC=1export HA_USE_DATALOADER=1
环境变量优先级从高到低依次为：
HA_USE_<FEATURE>：单项功能开关，优先级最高。显式设置为 0 时，可覆盖上层总开关的启用状态。HA_USE_ALL_HOOKS：Hook 类功能总开关。HA_USE_ALL：全局总开关。默认关闭：未设置任何环境变量时，所有能力默认关闭。
步骤3：在训练入口导入
在 Python 训练入口脚本开头导入
import hyperacc.auto。除 from __future__ import ... 等必须置于文件开头的语句外，建议将导入语句放置在 torch、训练框架、模型及 DataLoader 等相关模块导入之前，以确保优化能力能够正确生效。import hyperacc.auto# 保持原有训练逻辑不变# from your_project import train# train()
步骤4：启动训练任务
单卡训练场景下，在启动命令前设置环境变量即可：
export HA_USE_ALL=1python train.py
分布式训练场景下，同样在启动命令前设置环境变量：
export HA_USE_GC=1export HA_USE_NUMABIND=1export HA_USE_DATALOADER=1torchrun --nproc_per_node=8 train.py
步骤5：验证是否生效
1. 默认日志级别为 INFO，可输出关键初始化信息，用于初步确认 HyperAcc 是否正常生效。如需获取更详细的运行与调试信息，可将日志级别设置为 DEBUG：
export HA_LOG_LEVEL=DEBUG
2. 观察训练启动日志中是否出现 HyperAcc 相关初始化信息。初始化日志示例如下：
3. 检查训练任务是否正常进入训练循环。
4. 如果启用 DataLoader、GC、NUMA 等能力，可结合训练日志、CPU 亲和性或系统监控确认行为变化。
常用配置
启用全部能力
export HA_USE_ALL=1python train.py
仅启用系统优化
export HA_USE_GC=1export HA_USE_NUMABIND=1export HA_USE_THP=1python train.py
仅启用自动编译
export HA_USE_COMPILE=1export HA_COMPILE_MODE=defaultpython train.py
仅启用 DataLoader 优化
export HA_USE_DATALOADER=1export HA_DATALOADER_WORKERS=16export HA_DATALOADER_PREFETCH=2python train.py
