已开启
docs: add distributed environment variables documentation #45307
docs: add distributed environment variables documentation #45307
已开启
Chris创建于 8月25日
Chris
Chris成员
8月25日

【合入来源】

如有社区issue,请关联issue链接
请勿携带内部流程信息(需求链接、问题单、内部issue等)

【修改方案】

不涉及

【资料变更】

分布式环境变量配置全景

汇总 torch_npu 分布式模块全部环境变量的配置概览,作为本次文档变更的说明。

图例(「本次新增」列):

  • ✅ 本次新增(24 个:集合通信 19 + 分布式启动 4 + 内存管理 1)
  • ❌ 项目已有
  • ⚠️ 由 CANN HCCL 库提供,PTA 仅透传或记录,指向 CANN 文档
  • ℹ️ 社区通用变量,由 torchrun/elastic 注入,用户无需手动设置

1. 启动、rank 与 rendezvous

环境变量 说明 默认值 本次新增
TORCH_NPU_USE_PARALLEL_TCPSTORE 启用并行TCP Store False ✅
TORCH_NPU_ELASTIC_USE_AGENT_STORE 连接agent已启动的ParallelStore 未设置 ✅
ENABLE_TIERED_PARALLEL_TCPSTORE 启用分层并行 TCP Store false ✅
PROXY_AGENT_PID_USE_LOCAL_SOCKET_PATH 用agent PID生成本地socket路径 -1 ✅

ℹ️ torchrun/elastic 注入变量(LOCAL_RANK、RANK、WORLD_SIZE、MASTER_ADDR、MASTER_PORT、LOCAL_RANK、GROUP_RANK、LOCAL_WORLD_SIZE、TORCHELASTIC_RESTART_COUNT)由社区启动器自动注入,供 rendezvous、rank 拓扑、zero-copy、NSLB 等路径消费,用户无需手动设置。详见 PyTorch elastic run 文档。

2. ProcessGroupHCCL 等待、watchdog 与错误处理

环境变量 说明 默认值 本次新增
TORCH_HCCL_BLOCKING_WAIT 启动阻塞等待 0 ❌
TORCH_HCCL_ASYNC_ERROR_HANDLING 启动异步错误处理 1(PyTorch大于2.1.0) ❌
TORCH_HCCL_DESYNC_DEBUG 启动通信超时分析 0 ❌
TORCH_HCCL_HIGH_PRIORITY 强制高优先级stream 0 ✅
TORCH_HCCL_ENABLE_MONITORING 启动heartbeat监控 0 ✅
TORCH_HCCL_HEARTBEAT_TIMEOUT_SEC watchdog无心跳超时(秒) 600 秒 ✅
TORCH_HCCL_COORD_CHECK_MILSEC 轮询dump信号间隔(ms) 1000 ms ✅

3. Flight Recorder 与 dump

环境变量 说明 默认值 本次新增
TORCH_HCCL_TRACE_BUFFER_SIZE FR缓冲区大小 0(关闭) ✅
TORCH_HCCL_TRACE_CPP_STACK 记录C++调用栈 0 ✅
TORCH_HCCL_DUMP_ON_TIMEOUT 超时/错误自动dump 0 ✅
TORCH_HCCL_WAIT_TIMEOUT_DUMP_MILSEC 等待dump完成超时(ms) 60000 ms ✅
TORCH_HCCL_DEBUG_INFO_PIPE_FILE dump触发管道文件 空 ✅
TORCH_HCCL_DEBUG_INFO_TEMP_FILE dump文件名前缀 /tmp/hccl_trace_rank_ ✅

4. HCCL 超时、算法与 communicator 配置

环境变量 说明 默认值 本次新增
HCCL_BUFFSIZE 通信buffer大小 200 MB ⚠️
HCCL_EXEC_TIMEOUT 执行超时时间 1836 秒(内部默认) ⚠️
HCCL_CONNECT_TIMEOUT 建链超时时间 未设置返回 0 ⚠️
HCCL_DETERMINISTIC 确定性算法控制 取决于PyTorch设置 ⚠️
HCCL_ALGO 算法选择 PTA 不校验 ⚠️
HCCL_EVENT_TIMEOUT op等待超时时间 未设置/负值为 -1 ❌
P2P_HCCL_BUFFSIZE P2P通信buffer大小 20 MB ❌
RANK_TABLE_FILE 建链文件路径 空 ❌

⚠️ HCCL_BUFFSIZE、HCCL_EXEC_TIMEOUT、HCCL_CONNECT_TIMEOUT、HCCL_DETERMINISTIC、HCCL_ALGO 为 CANN HCCL集合通信库提供的环境变量,PTA 仅透传或记录,详见 CANN 环境变量参考。

5. stream、allocator 与对称内存

环境变量 说明 默认值 本次新增
MULTI_STREAM_MEMORY_REUSE 多流内存复用 1 ❌
(beta)TORCH_HCCL_ZERO_COPY 片内零拷贝 0 ❌
NPU_SHMEM_SYMMETRIC_SIZE 对称内存堆大小 1 GiB ✅

6. 诊断、采样与静默检测(PTA 特有)

环境变量 说明 默认值 本次新增
TORCH_HCCL_STATUS_SAVE_ENABLE 周期保存PG状态 false ✅
TORCH_HCCL_STATUS_SAVE_PATH 状态保存目录 /tmp ✅
TORCH_HCCL_STATUS_SAVE_INTERVAL 状态保存间隔 2 秒 ✅
NSLB_CP NSLB采样目录 未设置(关闭) ✅
NSLB_MAX_RECORD_NUM 最大采样记录数 1000 ✅
PERF_DUMP_CONFIG 性能数据记录 disabled ✅
PERF_DUMP_PATH 性能dump目录 空 ✅
NPU_ASD_ENABLE 特征值检测(静默检测) 0 ❌
NPU_ASD_UPPER_THRESH 绝对阈值 1000000,10000 ❌
NPU_ASD_SIGMA_THRESH 相对阈值 100000,5000 ❌

7. 其他:RPC、DTensor与DDP overlay

环境变量 说明 默认值 本次新增
TP_SOCKET_IFNAME 指定RPC网卡 未设置(按 hostname 解析) ✅
DDP_SET_LAST_BUCKET_CAP DDP桶重建顺序 未设置 ✅
TORCH_NPU_USE_COMPATIBLE_IMPL DTensor兼容实现 "1" 时保留社区实现 ❌

变更范围小结

  • ✅ 本次新增文档 24 个:collective_communication/ 19 个、distributed_startup/ 4 个(新目录)、memory_management/ 1 个。
  • 同步更新:env_variable_list.md(新表 11 分布式启动 + 表 3/4 增补)、三个 _menu_*.md 菜单文件。

【接口变更】

不涉及

【功能验证】

不涉及

【CheckList】

PR提交人对以下CheckList自检项进行全量自检,自检通过或不涉及,均修改 [ ] 为 [x]

likedislike
合并受阻
ChrisChris成员
8月25日 创建了 pull request,commit bde5d977
atomgit-bot
atomgit-bot
8月25日 评论:

变更摘要

这是一个纯文档类 PR(docs),为 torch_npu 分布式模块新增环境变量配置文档,共新增 24 个环境变量说明文档:集合通信(collective_communication/,19 个)、分布式启动(distributed_startup/,4 个,新目录)、内存管理(memory_management/,1 个),并同步更新环境变量总表 env_variable_list.md(新增 11 个分布式启动变量列表、增补表 3/4)及三个 _menu_*.md 菜单文件。文档按「本次新增 / 项目已有 / 由 CANN HCCL 库提供(指向 CANN 文档)/ 由 torchrun/elastic 注入(用户无需手动设置)」四类图例区分变量来源,且本 PR 不涉及接口变更。

主要改动

  • 新增分布式启动环境变量文档(4 个,新目录 distributed_startup/):补充 TORCH_NPU_USE_PARALLEL_TCPSTORE、TORCH_NPU_ELASTIC_USE_AGENT_STORE、ENABLE_TIERED_PARALLEL_TCPSTORE、PROXY_AGENT_PID_USE_LOCAL_SOCKET_PATH 的说明与默认值,覆盖并行/分层 TCP Store 及 agent PID 本地 socket 路径等启动配置。

  • 新增集合通信环境变量文档(19 个,collective_communication/):覆盖 watchdog 与错误处理(TORCH_HCCL_HIGH_PRIORITY、TORCH_HCCL_ENABLE_MONITORING、TORCH_HCCL_HEARTBEAT_TIMEOUT_SEC、TORCH_HCCL_COORD_CHECK_MILSEC)、Flight Recorder 与 dump(TORCH_HCCL_TRACE_BUFFER_SIZE、TORCH_HCCL_TRACE_CPP_STACK、TORCH_HCCL_DUMP_ON_TIMEOUT、TORCH_HCCL_WAIT_TIMEOUT_DUMP_MILSEC、TORCH_HCCL_DEBUG_INFO_PIPE_FILE、TORCH_HCCL_DEBUG_INFO_TEMP_FILE)、状态保存与 NSLB/性能采样(TORCH_HCCL_STATUS_SAVE_ENABLE/TORCH_HCCL_STATUS_SAVE_PATH/TORCH_HCCL_STATUS_SAVE_INTERVAL、NSLB_CP、NSLB_MAX_RECORD_NUM、PERF_DUMP_CONFIG、PERF_DUMP_PATH)以及 RPC/DTensor/DDP 配置(TP_SOCKET_IFNAME、DDP_SET_LAST_BUCKET_CAP)等变量说明。

  • 新增内存管理环境变量文档(1 个):补充对称内存堆大小变量 NPU_SHMEM_SYMMETRIC_SIZE(默认 1 GiB)的说明。

  • 同步更新索引与菜单文件:更新 env_variable_list.md 环境变量总表(新增 11 个分布式启动变量列表、增补表 3/4),并同步三个 _menu_*.md 菜单文件,保证文档入口与新增页面导航一致。

likedislike
不准确?
atomgit-bot
atomgit-bot
8月25日 评论:

🤖 本次改动均为数据 / 生成 / 二进制文件(如测试用例、锁文件、媒体资源),没有可审查的代码逻辑,已跳过 AI 代码审查。

likedislike
不准确?
ascend-robotascend-robot成员
8月25日 添加了label:ascend-cla/yes
ascend-robot
ascend-robot成员
8月25日 评论:

Thanks for your pull-request.
The full list of commands accepted by me can be found at here.
You can get sig-info at here.
You can self-configure the PR merge rules for this repository. For more details, please refer to Here.


PR Approval Progress

⚠️ This PR does not yet meet the following requirements:lgtm (requires ≥ 2 person(s) per module)、approve (requires ≥ 1 person(s) per module)

Module Approval Details

module lgtm status approve status
**/*.md ❌ (0/2)(You can also ask: kisnwang, zyw-hw, liangsongwei, LQ1206, lyx324521) ❌ (0/1)(You can also ask: wjlflyer, li_jing_hw, 楚浩田, zyw-hw, huangjingwei)

💡 Tip:

  • Committer can comment /approve or /lgtm
  • Commenting /approve implies both code review (lgtm) and intent to merge (approve)

CLA Signature Pass

ccyyccyyccyycc, thanks for your pull request. All authors of the commits have signed the CLA. 👍

likedislike
ascend-robotascend-robot成员
8月25日 添加了label:needs-issue
ascend-robot
ascend-robot成员
8月25日 评论:

Linking Issue Notice

@ccyyccyyccyycc , the pull request must be linked to at least one issue.
If an issue has already been linked, but the needs-issue label remains, you can remove the label by commenting /check-issue .

likedislike
ascend-robot
ascend-robot成员
8月25日 评论:

当前仓库存在以下 保护分支 :

Protected Branch Version Release
master
v2.7.1
v2.9.0
v2.10.0
v2.11.0
v2.12.0
v2.11.0-26.1.0
v2.12.0-26.1.0
v2.10.0-26.1.0
v2.9.0-26.1.0
v2.7.1-26.1.0
ci-test

评论 /sync <branch1> <branch2> ... 可将当前 PR 修改同步到其它分支(创建同步 PR):
a) 如果当前 PR 是 Open 状态,同步操作将延迟到 PR 被合并时执行
b) 如果当前 PR 已经 Merged,将立即执行同步操作

注意:

  1. /sync 命令可以指定同步到多个分支,仅最后一个 /sync 命令生效
  2. 如果创建的同步 PR 不正确,可通过向同步 PR 的源分支提交轻量级 PR 完善,或使用 /close 命令关闭
likedislike
ascend-robotascend-robot成员
8月25日 添加了label:ci-pipeline-running
ChrisChris成员
8月25日 修改了pull request 的描述
ascend-robotascend-robot成员
8月25日 删除了label:ci-pipeline-running
ascend-robotascend-robot成员
8月25日 添加了label:ci-pipeline-passed
ascend-robot
ascend-robot成员
8月25日 评论:
流水线 PR-pipeline_pytorch#63752 [ commitID:7607693f ] 已完成
>>>代码风格自动修复执行成功(无修复内容)
阶段 任务名 状态 详情
编译构建 Build_X86 🛑 >>>
Build_ARM 🛑 >>>
Build_X86_torchair 🛑 >>>
Build_ARM_torchair 🛑 >>>
patch_test 🛑 >>>
Build_X86_213 🛑 >>>
Build_ARM_213 🛑 >>>
恶意代码检查 Antipoison ✅ >>>
编码安全与规范检查 codecheck_pre-commit ✅ >>>
check_error ✅ >>>
lintrunner ✅ >>>
开源片段检查 SCA ✅ >>>
开发者测试 UT_ARM_A3_Part_01 🛑 >>>
UT_ARM_A3_Part_02 🛑 >>>
UT_ARM_A2_Part_01 🛑 >>>
UT_ARM_A2_Part_02 🛑 >>>
UT_ARM_A2_Part_03 🛑 >>>
UT_inductor_Part_01 🛑 >>>
UT_inductor_Part_02 🛑 >>>
UT_inductor_Part_03 🛑 >>>
UT_inductor_Part_04 🛑 >>>
UT_DIST_ARM_Part_01 🛑 >>>
UT_DIST_ARM_Part_02 🛑 >>>
UT_DIST_ARM_Part_03 🛑 >>>
UT_DIST_ARM_Part_04 🛑 >>>
UT_ARM_A2_Select_Part_01 🛑 >>>
UT_ARM_A2_Select_Part_02 🛑 >>>
UT_ARM_A2_Part_01_213 🛑 >>>
UT_ARM_A2_Part_02_213 🛑 >>>
UT_ARM_A2_Part_03_213 🛑 >>>
UT_inductor_Part_01_213 🛑 >>>
UT_inductor_Part_02_213 🛑 >>>
UT_inductor_Part_03_213 🛑 >>>
UT_inductor_Part_04_213 🛑 >>>
UT_DIST_ARM_Part_01_213 🛑 >>>
UT_DIST_ARM_Part_02_213 🛑 >>>
UT_DIST_ARM_Part_03_213 🛑 >>>
UT_DIST_ARM_Part_04_213 🛑 >>>
UT_ARM_A2_Select_Part_01_213 🛑 >>>
UT_ARM_A2_Select_Part_02_213 🛑 >>>
流水线 PR-pipeline_pytorch ✅ >>>
此流水线已支持下列评论快捷指令,仅PR创建者和白名单成员[wujinyuan1, huangjingwei, liangsongwei, yashi999, culechan, Dring, wuyouqi1, L1919_snow, qq_52711437, WhiteNight12, nomiz, xiu_21, ffmh, wanglijun55, hss-shuai, husichao, smallsilly, lanshaozuishuai, jimmyisme1, lzy0920232, alpha-junh, Sunshine_Youngster, wei_zhuoyi, zhangyihuiben, zyw-hw, zzzkeke, rmch, yangch0324, LucciC, AACAES, renyujin, wjlflyer, senzhen-town, pengjingyou, qsc97, limuan, yule100, xiaoqi-zhou, kuhn7, chenxingying, hanye02, zichun_ye, anyrenwei, kkjocker, wangzili121, Lu_G, yvjc, puddingfjz, HandsoemLemon, bigprestigee1, huawuyi, zhenyu10, dairenjie, du-jin-hang, zou-jieyu, adelaideliu, TrHan, wanlinan, Windwindzzz, pengqihw, kisnwang, yuheng_wang, honghao_wang, jizewei, zhangguoguang, sunyu-xuan, chenrayray, hbhu_bin, liujunzhu, c_34, LiNuoh, maoyuanpeng1, zzhongmin, zhaoyu65, bellatan, jiabaolin, zhuofanshen, wencaiwen, lu_zhuge, caoshuyang, molly12, lyx324521, LQ1206, gitcode-chenjiao, cai-weiwei1989, CHDong, ogqin, yuanlipingGit, xuqinglin1, lqz2, zouwei1, chaoluoa, paradox325, jackzhang1116, yaoyao, akh, yujiacheng, dengjie0116, Hubert11111, Shine_Ws, wslhj555, longqiand, OYtao666, JiaqingQiang, luyyyy, Kingbelial, zhanghaiyu0101, wenxp1018, yanliu-luoluo, ksun_sekiro, liyong328, wgzheng, tangky, vivi_is_coding, aoiaoisola, weixin_44494597, wangmengmengwang65667, hid57809721, qq_35468730, comeonup, C547032, gcw_m5OQChA4, yao_yao_ling_xian, cnnbwcy, szqfes_12, cora_19, cann_lilin, can, shawnylee233, fanglanyue0916, hhz0, LiNuohang, taohuoquan, Jesse, WSs_321]评论有效
  • compile、compile_inductor、compile_torchair : 运行流水线
  • retry : 重试流水线所有失败子任务
  • retry <任务名> : 仅重试指定失败子任务
  • stop : 停止流水线
likedislike
ChrisChris成员
8月25日 修改了pull request 的描述
ascend-robot
ascend-robot成员
8月25日 评论:

ascend docs pipeline is running...

likedislike
ascend-robotascend-robot成员
8月25日 添加了label:docs-ci-pipeline-running
ascend-robot
ascend-robot成员
8月25日 评论:

✅ 跳过 docs ci 检查,没有需要检查的文档文件

likedislike
ascend-robotascend-robot成员
8月25日 删除了label:docs-ci-pipeline-running
ascend-robotascend-robot成员
8月25日 添加了label:docs-ci-pipeline-success