CANN/torchtitan-npu指标与调试指南

调试支持特性

【免费下载链接】torchtitan-npuAscend Extension for torchtitan项目地址: https://gitcode.com/cann/torchtitan-npu

torchtitan-npu 目前提供多种调试特性支持，帮助开发者定位分布式训练中的各类问题，包括通信故障、内存问题和性能瓶颈等。以下是常见使用场景和对应功能的快速参考：

HCCL Flight Recorder

在大规模分布式训练任务因通信算子超时而异常退出时，往往因为缺少详尽的通信轨迹及对应代码位置信息，难以快速定位问题的根本原因。HCCL Flight Recorder 通过自动配置 HCCL 相关环境变量，在分布式训练过程中实时监控 HCCL 通信操作，并记录通信算子的下发调用栈、时间戳和数据量大小等关键信息。当检测到通信超时异常时，系统会自动将缓冲区中的追踪信息转储到文件。

使用场景

• 训练过程中出现 HCCL 通信超时错误
• 需要排查 HCCL 通信算子的调用顺序和参数

实现原理

由于启用 HCCL Flight Recorder 功能所需的环境变量配置与 NCCL 存在差异，因而 torchtitan_npu 在torchtitan_npu/tools/flight_recorder.py中对torchtitan.distributed.utils.init_distributed函数进行了拦截，自动配置 HCCL Flight Recorder 相关的环境变量，使能了通信超时的自动检测和轨迹转储功能。在分布式初始化阶段，系统会根据配置自动设置以下环境变量：

1. TORCH_HCCL_TRACE_BUFFER_SIZE：设置 HCCL 追踪缓冲区大小，控制记录的通信轨迹数据量。
2. HCCL_ASYNC_ERROR_HANDLING：启用 HCCL 异步错误处理机制，创建检测通信问题的 HCCL Watchdog 线程。
3. TORCH_HCCL_ENABLE_MONITORING：启用 HCCL 监控功能，实时检测通信状态。
4. TORCH_HCCL_DUMP_ON_TIMEOUT：配置在检测到超时时自动转储追踪信息。
5. TORCH_HCCL_DEBUG_INFO_TEMP_FILE：指定追踪文件的存储路径和文件名前缀。

配置选项

在训练任务的 TOML 配置文件（例如torchtitan_npu/models/deepseek_v32/train_configs/deepseek_v32_671b_debug.toml，或实际启动训练时--job.config_file所指向的路径）中，找到对应的[comm]节，并添加以下配置以启用 HCCL Flight Recorder：

需要注意的是，HCCL 通信超时的阈值目前只能通过环境变量HCCL_EXEC_TIMEOUT来配置。设置此环境变量可以确保 HCCL 本身的其他调试信息能够被正确收集。例如，在启动训练脚本中设置：

export HCCL_EXEC_TIMEOUT=120 # 设置超时阈值为 120 秒

配置示例

在配置文件的[comm]节中添加以下配置，启用 HCCL Flight Recorder 并设置相关参数：

[comm] trace_buf_size = 2000 # 设置大小为 2000 的追踪缓冲区 save_traces_folder = "hccl_traces" # 追踪文件保存到 `hccl_traces` 目录 save_traces_file_prefix = "rank_" # 文件名前缀为 `rank_`

当训练过程中出现 HCCL 通信超时或错误时，系统会自动将追踪信息转储到hccl_traces/rank_*文件中，开发者可以使用这些文件进行问题诊断和分析，相关指导可以参考Pytorch社区关于Flight Recorder功能的相关说明文档。

Memory Snapshot

内存快照功能用于捕获和记录训练过程中的内存使用情况，包括内存分配、显存占用、张量生命周期等信息。通过 torchtitan 配置项进行定时内存快照收集，本功能生成的.pickle格式内存快照文件可通过memory_viz工具进行解析和可视化查看。

使用场景

• 训练过程中出现 OOM（Out of Memory）错误，需要分析内存占用情况
• 怀疑存在内存泄漏，需要追踪内存分配和释放情况
• 需要优化显存使用，了解框架不同模块的内存占用

配置选项

torchtitan 原生提供内存快照功能，相关配置项位于[profiling]节，支持的配置选项如下：

torchtitan 原生内存快照功能会按照profile_freq指定的频率定期收集内存快照，并在发生 OOM 错误时自动转储当前内存快照。收集到的内存快照将保存到save_memory_snapshot_folder指定的目录中。

配置示例

在配置文件的[profiling]节中添加以下配置，启用内存快照功能：

[profiling] enable_memory_snapshot = true # 使能内存快照采集 save_memory_snapshot_folder = "memory_snapshot" # 指定输出快照文件目录为 memory_snapshot profile_freq = 10 # 指定每训练10步收集采集内存快照

Profiling

性能分析是优化训练性能的关键工具。torchtitan_npu 对性能分析功能进行了 NPU 适配，支持详细的性能数据收集和分析。系统使用torch_npu.profiler提供的原生性能分析器，能够追踪 CPU 和 NPU 的活动，记录内存使用情况、调用栈信息、张量形状等详细数据，并提供 AI 算力利用率指标。

使用场景

• 需要分析训练过程中的性能瓶颈
• 需要对比不同配置或优化方案的性能表现
• 需要定位训练过程中的性能异常或退化

配置选项

在训练任务的 TOML 配置文件中，找到对应的[profiling]节，并添加以下配置以启用性能分析。

torchtitan 原生配置选项

torchtitan_npu 扩展配置选项

配置示例

在配置文件中添加以下配置，启用性能分析功能。

使用 torchtitan 原生的基于频率的分析模式：

[profiling] enable_profiling = true # 启用性能分析 save_traces_folder = "profile_traces" # 性能分析结果保存目录 profile_freq = 10 # 每 10 步采集一次profiling profiler_warmup = 1 # 预热 1 步 profiler_active = 3 # 采集 3 步

使用 torchtitan_npu 扩展的基于步数的分析模式：

[profiling] enable_profiling = true # 启用性能分析 save_traces_folder = "profile_traces" # 性能分析结果保存目录 profile_step_start = 10 # 从第 10 步开始分析 profile_step_end = 15 # 到第 15 步结束分析 profile_ranks = [0] # 仅对 rank 0 进行分析 profile_record_shapes = true # 记录张量形状 profile_with_memory = false # 不记录内存使用 profile_with_stack = false # 不记录调用栈 enable_online_parse = true # 启用在线解析

【免费下载链接】torchtitan-npuAscend Extension for torchtitan项目地址: https://gitcode.com/cann/torchtitan-npu