帮你快速理解、总结文档立即下载
文档中心>高性能计算集群>HyperAcc 训练加速套件>常见问题

常见问题

最近更新时间：2026-08-14 18:27:00
我的收藏

本页目录：

本文汇总 HyperAcc 训练加速套件使用过程中的常见问题，涵盖安装、能力启用、训练加速、系统优化、硬件算子、自动编译、DataLoader 及日志等方面，提供排查思路与解决方案。

安装相关

安装 wheel 包失败怎么办？

请按以下顺序检查：
1. 确认 wheel 包文件完整，文件名通常为 hyperacc-*.whl。
2. 确认 Python 版本为 3.8 及以上，并与 wheel 包匹配。
  python --version
  #确认Python 版本
3. 确认当前环境已安装 PyTorch 2.0 及以上版本和训练任务所需依赖。
4. 使用绝对路径重新安装：
pip install /path/to/hyperacc-*.whl
# path是wheel包所放置的路径

如何确认 HyperAcc 已安装成功？

执行以下命令：
python -c "import hyperacc.auto; print('hyperacc auto import ok')"
如果命令正常输出，说明 Python 包可被当前环境导入。

为什么 import hyperacc.auto 后没有启用能力？

这是预期行为。未设置环境变量时，import hyperacc.auto 默认不做任何操作。如需启用能力，请先设置对应环境变量，再导入 hyperacc.auto：
import hyperacc.auto

启用相关

如何一键启用全部能力？

export HA_USE_ALL=1
python train.py
并确保训练入口中已导入：
import hyperacc.auto

如何只启用某一项能力？

设置单项环境变量即可，例如：
export HA_USE_COMPILE=1
export HA_USE_GC=1
python train.py
单项开关优先级高于总开关。

环境变量优先级是什么？

优先级从高到低依次为：HA_USE_<FEATURE> > HA_USE_ALL_HOOKS > HA_USE_ALL > 默认关闭
例如，设置 HA_USE_ALL=1 后，再设置 HA_USE_COMPILE=0，可单独关闭自动编译能力。

为什么启用了环境变量仍未生效？

请逐项排查：
环境变量是否在启动训练进程前设置。
训练入口 Python 脚本是否导入了 hyperacc.auto。
import hyperacc.auto 是否位于 torch、训练框架、模型和 DataLoader 相关导入之前（from __future__ 等必须位于文件开头的语句除外）。
当前硬件平台是否支持对应能力。
日志级别是否过低，可尝试设置 HA_LOG_LEVEL=DEBUG 获取更多信息。

训练加速相关

HyperAcc 会保证所有任务都有固定性能提升吗？

不会。优化效果受模型结构、数据加载瓶颈、硬件平台、PyTorch 版本及训练配置多重因素影响，建议结合自身业务任务开展实测验证。

是否需要改造训练框架？

不需要。推荐方式是通过环境变量启用所需能力，并在训练入口 Python 脚本开头导入 hyperacc.auto。

能否在生产任务中直接启用 HA_USE_ALL=1？

可以用于快速验证，但生产任务建议先按单项能力逐步启用，确认训练正确性和稳定性后再组合启用。

系统优化相关

CPU/NUMA 绑核依赖哪些信息？

HyperAcc 会根据 LOCAL_RANK、LOCAL_WORLD_SIZE、CUDA_VISIBLE_DEVICES 或 HIP_VISIBLE_DEVICES 等环境变量，结合 GPU 与 NUMA 拓扑进行绑定。

LOCAL_WORLD_SIZE 未设置时能否使用 NUMA 绑核？

可以。单卡直接运行时，HyperAcc 可按单卡场景处理，将进程绑定到 GPU 所在 NUMA 节点的 CPU。

透明大页为什么没有生效？

透明大页配置需要写入 Linux 系统配置，通常需要 root 或管理员预配置权限。权限不足时，对应能力可能无法完成配置。
/sys/kernel/mm/transparent_hugepage/enabled: Permission denied
# 权限不足时的展示

GC 优化应该选择什么模式？

建议默认使用：
export HA_USE_GC=1
export HA_GC_MODE=reduce_frequency
disable 模式会完全关闭 GC，建议仅在充分验证并监控内存使用后使用。

NVIDIA/ DCU 相关

NVIDIA 和 DCU 支持的能力是否相同？

不完全相同。部分算子能力仅适用于 NVIDIA GPU，部分能力仅适用于 DCU。

如何启用 NVIDIA 相关算子能力？

算子能力是通过环境变量进行启用。
示例：
export HA_USE_VOXEL=1
export HA_USE_DEFORM_AGG=1
export HA_USE_RASTERIZER=1
export HA_USE_SYNCBN=1
python train.py

如何启用 DCU 相关算子能力？

示例：
export HA_USE_DEFORM_ATTN=1
export HA_USE_DROPOUT=1
export HA_USE_FOCAL_LOSS=1
export HA_USE_RMSNORM=1
export HA_USE_ROPE=1
python train.py

torch.compile 相关

启用自动编译后首次启动变慢是否正常？

是正常现象。torch.compile 可能在首次运行时产生编译开销，后续运行性能表现需结合具体任务评估。

自动编译失败怎么办？

可先降低配置复杂度：
export HA_USE_COMPILE=1
export HA_COMPILE_MODE=default
export HA_COMPILE_FULLGRAPH=false
export HA_COMPILE_EXPLAIN=1
export HA_LOG_LEVEL=INFO
python train.py
如果仍有问题，建议先关闭自动编译，确认其他能力是否正常：
export HA_USE_COMPILE=0
python train.py

HA_COMPILE_MODE 应该如何选择？

模式
说明
default
默认模式，平衡编译速度和性能。
reduce-overhead
降低运行时开销，适合部分推理或小 batch 场景。
max-autotune
更激进的优化策略，可能带来更长编译时间。

DataLoader 相关

HA_DATALOADER_WORKERS 应该设置多少？

可从默认值 16 开始，根据 CPU 核数、数据预处理开销和内存情况调整。过大的 worker 数可能造成 CPU 或内存压力。

什么时候设置 HA_DATALOADER_NO_PIN_MEMORY=1？

当容器共享内存不足、出现锁页内存相关报错，或 pin_memory 在当前环境中表现不稳定时，可尝试关闭。

日志相关

查看日志

#查看更多的日志
export HA_LOG_LEVEL=DEBUG
export HA_HOOKS_SILENT=0
python train.py

#查看更少的日志

export HA_LOG_LEVEL=WARNING
export HA_HOOKS_SILENT=1
python train.py

问题定位建议

在问题定位时，建议提供以下信息：
HyperAcc 安装包版本。
Python 和 PyTorch 版本。
硬件平台。
已设置的 HA_* 环境变量。
训练启动命令和关键日志。
中国站