Star890
1409
代码
代码
Issues1692
Pull Requests1755
Actions
项目讨论
Wiki
分析
Star890
1409
已开启
docs: add distributed environment variables documentation #45307
Chris创建于 8月25日
docs: add distributed environment variables documentation #45307
已开启
Chris创建于 8月25日
从ccyyccyyccyycc/pytorchfeat/docs-distributed-env合入到Ascend/pytorchmaster
共 28 个文件变更+770-0
Adocs/zh/api/environment_variable/collective_communication/DDP_SET_LAST_BUCKET_CAP.md+27-0
@@ -0,0 +1,27 @@
1+# DDP\_SET\_LAST\_BUCKET\_CAP
2+ 
3+## 功能描述
4+ 
5+通过此环境变量可控制DDP（Distributed Data Parallel）的bucket重建顺序。当设为"1"时，较小的first bucket cap会被分配到最后一个bucket，而不是第一个bucket。
6+ 
7+- 精确等于字符串"1"：启用，将较小的first bucket cap落到最后一个bucket。
8+- 其他值：不启用，保持默认的bucket顺序。
9+ 
10+默认值：未设置。
11+ 
12+> [!NOTE]
13+>
14+> **PyTorch社区：** `torch_npu`与`torch`对应环境变量同名，行为一致。
15+ 
16+## 配置示例
17+ 
18+```bash
19+export DDP_SET_LAST_BUCKET_CAP=1
20+```
21+ 
22+## 支持的型号
23+ 
24+- <term>Atlas 训练系列产品</term>
25+- <term>Atlas A2 训练系列产品</term>
26+- <term>Atlas A3 训练系列产品</term>
27+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/collective_communication/NSLB_CP.md+33-0
@@ -0,0 +1,33 @@
1+# NSLB\_CP
2+ 
3+## 功能描述
4+ 
5+通过此环境变量可配置HCCL操作的NSLB（Non-Stop Load Balancing）采样记录目录路径。当设置为非空路径时，每个collective操作会记录操作类型、数据量和rank信息到该目录下的文件中。
6+ 
7+- 未设置：关闭NSLB采样。
8+- 设置路径：开启NSLB采样，记录文件创建在指定路径下。
9+ 
10+默认值：未设置（关闭）。
11+ 
12+> [!NOTE]
13+>
14+> - 此环境变量在`ProcessGroupHCCL.cpp`文件级全局初始化时读取，**应在加载`torch_npu`扩展前设置**。
15+> - NSLB采样依赖由`torchrun/elastic`启动器注入的`RANK`和`MASTER_ADDR`两个PyTorch的环境变量。`RANK`用于标记记录来源，`MASTER_ADDR`参与文件名构造。
16+> - 如果环境中存在`HCCL_ALGO`，新建记录文件时会写入一行`HCCL_ALGO=<value>`作为说明。
17+> - NSLB采样不读取Flight Recorder ring buffer，与FR dump是独立的采样路径。
18+> - 记录文件名格式为：`<master_addr>_<comm_name>_<rank>.log`。
19+> - 每个PG的最大采样记录数量由`NSLB_MAX_RECORD_NUM`控制。
20+> - 此功能为`torch_npu`特有，PyTorch社区无直接对应变量。
21+ 
22+## 配置示例
23+ 
24+```bash
25+export NSLB_CP=/data/nslb_records
26+```
27+ 
28+## 支持的型号
29+ 
30+- <term>Atlas 训练系列产品</term>
31+- <term>Atlas A2 训练系列产品</term>
32+- <term>Atlas A3 训练系列产品</term>
33+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/collective_communication/NSLB_MAX_RECORD_NUM.md+25-0
@@ -0,0 +1,25 @@
1+# NSLB\_MAX\_RECORD\_NUM
2+ 
3+## 功能描述
4+ 
5+通过此环境变量可控制每个PG的NSLB（Non-Stop Load Balancing）最大采样记录数量。
6+ 
7+默认值：1000。达到上限后，会写入end文件并停止采样。
8+ 
9+> [!NOTE]
10+>
11+> - 仅当`NSLB_CP`设置为非空路径时，采样记录才会写入文件。
12+> - 此功能为`torch_npu`特有，PyTorch社区无直接对应变量。
13+ 
14+## 配置示例
15+ 
16+```bash
17+export NSLB_MAX_RECORD_NUM=5000
18+```
19+ 
20+## 支持的型号
21+ 
22+- <term>Atlas 训练系列产品</term>
23+- <term>Atlas A2 训练系列产品</term>
24+- <term>Atlas A3 训练系列产品</term>
25+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/collective_communication/PERF_DUMP_CONFIG.md+29-0
@@ -0,0 +1,29 @@
1+# PERF\_DUMP\_CONFIG
2+ 
3+## 功能描述
4+ 
5+通过此环境变量可配置HCCL操作的性能数据记录功能。格式为逗号分隔的`key:value`键值对。只有`enable:true`精确匹配时才会启用性能记录。
6+ 
7+- `enable:true`：启用collective性能记录。
8+- 其他配置：不启用。
9+ 
10+默认值：未设置（不启用）。
11+ 
12+> [!CAUTION]
13+>
14+> `PERF_DUMP_CONFIG=enable:true`后若`PERF_DUMP_PATH`为空或不是可解析的real path，collective热路径会抛出错误。该路径必须能通过`realpath`解析。
15+>
16+> 此功能为`torch_npu`特有，PyTorch社区无直接对应变量。
17+ 
18+## 配置示例
19+ 
20+```bash
21+export PERF_DUMP_CONFIG=enable:true
22+```
23+ 
24+## 支持的型号
25+ 
26+- <term>Atlas 训练系列产品</term>
27+- <term>Atlas A2 训练系列产品</term>
28+- <term>Atlas A3 训练系列产品</term>
29+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/collective_communication/PERF_DUMP_PATH.md+26-0
@@ -0,0 +1,26 @@
1+# PERF\_DUMP\_PATH
2+ 
3+## 功能描述
4+ 
5+通过此环境变量可配置HCCL性能dump文件的输出目录路径。启用性能记录后，collective性能记录会输出到该目录下的`perf_pt_<pid>_<device>.log`文件中。
6+ 
7+默认值：空。
8+ 
9+> [!CAUTION]
10+>
11+> `PERF_DUMP_PATH`必须能通过`realpath`解析，否则在`PERF_DUMP_CONFIG=enable:true`时collective热路径会抛出错误。
12+>
13+> 此功能为`torch_npu`特有，PyTorch社区无直接对应变量。
14+ 
15+## 配置示例
16+ 
17+```bash
18+export PERF_DUMP_PATH=/data/perf_logs
19+```
20+ 
21+## 支持的型号
22+ 
23+- <term>Atlas 训练系列产品</term>
24+- <term>Atlas A2 训练系列产品</term>
25+- <term>Atlas A3 训练系列产品</term>
26+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/collective_communication/TORCH_HCCL_COORD_CHECK_MILSEC.md+28-0
@@ -0,0 +1,28 @@
1+# TORCH\_HCCL\_COORD\_CHECK\_MILSEC
2+ 
3+## 功能描述
4+ 
5+当使用HCCL作为通信后端时，通过此环境变量可设置WatchDog线程中轮询检查Store dump signal的时间间隔。
6+ 
7+单位为ms，默认值为1000毫秒（1秒）。
8+ 
9+WatchDog线程会以此间隔检查其他rank通过Store发出的dump信号，用于跨rank协调的dump通知。
10+ 
11+> [!NOTE]
12+>
13+> - 此环境变量仅在`TORCH_HCCL_ENABLE_MONITORING=1`时生效。
14+> - 减小此值可以更快响应dump信号，但会增加对Store的轮询频率。
15+> - **PyTorch社区：** 社区对应环境变量 `TORCH_NCCL_COORD_CHECK_MILSEC`，默认值为1000ms，`torch_npu`与`torch`行为一致。
16+ 
17+## 配置示例
18+ 
19+```bash
20+export TORCH_HCCL_COORD_CHECK_MILSEC=500
21+```
22+ 
23+## 支持的型号
24+ 
25+- <term>Atlas 训练系列产品</term>
26+- <term>Atlas A2 训练系列产品</term>
27+- <term>Atlas A3 训练系列产品</term>
28+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/collective_communication/TORCH_HCCL_DEBUG_INFO_PIPE_FILE.md+38-0
@@ -0,0 +1,38 @@
1+# TORCH\_HCCL\_DEBUG\_INFO\_PIPE\_FILE
2+ 
3+## 功能描述
4+ 
5+当使用HCCL作为通信后端时，通过此环境变量可配置命名管道文件，用于外部触发Flight Recorder dump。
6+ 
7+- 非空字符串且`TORCH_HCCL_TRACE_BUFFER_SIZE > 0`时，在指定路径创建`<stem><rank>.pipe`命名管道文件。
8+- 向该管道文件写入任意内容，即可触发HCCL debug dump。
9+- 空字符串：不创建管道文件。
10+ 
11+默认值：空（不创建管道）。
12+ 
13+> [!NOTE]
14+>
15+> - 此环境变量仅在`TORCH_HCCL_TRACE_BUFFER_SIZE > 0`时生效。
16+> - 管道文件通过`mkfifo`创建，`O_RDONLY | O_NONBLOCK`模式打开。
17+> - **PyTorch社区：** 社区对应环境变量 `TORCH_NCCL_DEBUG_INFO_PIPE_FILE`，默认值同样为空，`torch_npu`与`torch`行为一致。
18+ 
19+## 配置示例
20+ 
21+```bash
22+export TORCH_HCCL_DEBUG_INFO_PIPE_FILE=/tmp/hccl_debug_pipe
23+```
24+ 
25+## 使用约束
26+ 
27+- 管道文件在被创建后，用户可通过`echo`等命令向管道写入数据触发dump，例如：
28+ ```bash
29+ echo "dump" > /tmp/hccl_debug_pipe_0.pipe
30+ ```
31+- 管道文件是在ProcessGroupHCCL构造时创建的，需在创建PG前设置环境变量。
32+ 
33+## 支持的型号
34+ 
35+- <term>Atlas 训练系列产品</term>
36+- <term>Atlas A2 训练系列产品</term>
37+- <term>Atlas A3 训练系列产品</term>
38+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/collective_communication/TORCH_HCCL_DEBUG_INFO_TEMP_FILE.md+27-0
@@ -0,0 +1,27 @@
1+# TORCH\_HCCL\_DEBUG\_INFO\_TEMP\_FILE
2+ 
3+## 功能描述
4+ 
5+当使用HCCL作为通信后端时，通过此环境变量可配置dump文件的名称前缀，HCCL debug信息将输出到该文件。
6+ 
7+默认值为`/tmp/hccl_trace_rank_`，最终文件名为`<前缀><rank>`。
8+ 
9+例如，默认配置下rank 0的dump文件为`/tmp/hccl_trace_rank_0`。
10+ 
11+> [!NOTE]
12+>
13+> - 仅当`TORCH_HCCL_TRACE_BUFFER_SIZE > 0`且有dump触发时才会生成文件。
14+> - **PyTorch社区：** 社区对应环境变量 `TORCH_FR_DUMP_TEMP_FILE`（fallback `TORCH_NCCL_DEBUG_INFO_TEMP_FILE`），但社区默认值为`$XDG_CACHE_HOME/torch/comm_lib_trace_rank_`，未设置XDG时为`$HOME/.cache/torch/...`。PTA默认路径为`/tmp/hccl_trace_rank_`，`torch_npu`与`torch`的名称和默认目录都不同。
15+ 
16+## 配置示例
17+ 
18+```bash
19+export TORCH_HCCL_DEBUG_INFO_TEMP_FILE=/data/hccl_dumps/trace_
20+```
21+ 
22+## 支持的型号
23+ 
24+- <term>Atlas 训练系列产品</term>
25+- <term>Atlas A2 训练系列产品</term>
26+- <term>Atlas A3 训练系列产品</term>
27+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/collective_communication/TORCH_HCCL_DUMP_ON_TIMEOUT.md+34-0
@@ -0,0 +1,34 @@
1+# TORCH\_HCCL\_DUMP\_ON\_TIMEOUT
2+ 
3+## 功能描述
4+ 
5+当使用HCCL作为通信后端时，通过此环境变量可控制发生HCCL超时或错误时是否自动触发Flight Recorder调试信息dump。
6+ 
7+- 0：超时或错误时不触发dump。
8+- 1：超时或错误时触发本rank的dump，并通过Store协调其他rank同步dump。
9+ 
10+默认值：0。
11+ 
12+> [!NOTE]
13+>
14+> - 开启此功能需要`TORCH_HCCL_TRACE_BUFFER_SIZE > 0`，否则无事件可dump。
15+> - 开启此功能后，建议同时开启`TORCH_HCCL_ENABLE_MONITORING`，以确保watchDog卡死时也能触发dump。
16+> - **PyTorch社区：** 社区对应环境变量 `TORCH_FR_DUMP_ON_TIMEOUT`（fallback `TORCH_NCCL_DUMP_ON_TIMEOUT`），但社区当前PG默认true，`torch_npu`与`torch`存在差异。
17+ 
18+## 配置示例
19+ 
20+```bash
21+export TORCH_HCCL_DUMP_ON_TIMEOUT=1
22+```
23+ 
24+## 使用约束
25+ 
26+- 建议配合`TORCH_HCCL_TRACE_BUFFER_SIZE > 0`和`TORCH_HCCL_ENABLE_MONITORING=1`使用。
27+- dump文件路径由`TORCH_HCCL_DEBUG_INFO_TEMP_FILE`控制，默认输出到`/tmp/hccl_trace_rank_<rank>`。
28+ 
29+## 支持的型号
30+ 
31+- <term>Atlas 训练系列产品</term>
32+- <term>Atlas A2 训练系列产品</term>
33+- <term>Atlas A3 训练系列产品</term>
34+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/collective_communication/TORCH_HCCL_ENABLE_MONITORING.md+35-0
@@ -0,0 +1,35 @@
1+# TORCH\_HCCL\_ENABLE\_MONITORING
2+ 
3+## 功能描述
4+ 
5+当使用HCCL作为通信后端时，通过此环境变量可控制是否启动heartbeat monitor线程。该线程用于检测HCCL WatchDog线程是否卡死，并在WatchDog无心跳时自动dump调试信息并终止进程。
6+ 
7+- 0：不启动monitor线程。
8+- 1：启动monitor线程，WatchDog卡死时将触发`TORCH_HCCL_DUMP_ON_TIMEOUT`逻辑并终止进程。
9+ 
10+默认值：0。
11+ 
12+> [!NOTE]
13+>
14+> - 当前版本同时兼容旧名称`HCCL_ENABLE_MONITORING`。
15+> - WatchDog心跳超时时间由`TORCH_HCCL_HEARTBEAT_TIMEOUT_SEC`控制，默认600秒。
16+> - 建议开启此功能以预防训练任务因HCCL API卡死而长时间占用集群资源。
17+> - **PyTorch社区：** 社区对应环境变量 `TORCH_NCCL_ENABLE_MONITORING`，但社区默认值为true，`torch_npu`与`torch`存在差异。
18+ 
19+## 配置示例
20+ 
21+```bash
22+export TORCH_HCCL_ENABLE_MONITORING=1
23+```
24+ 
25+## 使用约束
26+ 
27+- 建议同时设置`TORCH_HCCL_TRACE_BUFFER_SIZE > 0`以便在卡死时dump有效的调试信息。
28+- Monitor线程在ProcessGroupHCCL构造时启动，需在创建PG前设置环境变量。
29+ 
30+## 支持的型号
31+ 
32+- <term>Atlas 训练系列产品</term>
33+- <term>Atlas A2 训练系列产品</term>
34+- <term>Atlas A3 训练系列产品</term>
35+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/collective_communication/TORCH_HCCL_HEARTBEAT_TIMEOUT_SEC.md+27-0
@@ -0,0 +1,27 @@
1+# TORCH\_HCCL\_HEARTBEAT\_TIMEOUT\_SEC
2+ 
3+## 功能描述
4+ 
5+当使用HCCL作为通信后端时，通过此环境变量可设置heartbeat monitor判定WatchDog卡死的超时时间。
6+ 
7+单位为秒，默认值为600秒（10分钟）。
8+ 
9+当WatchDog线程的心跳停止超过此时间时，monitor认为WatchDog已卡死，将触发dump并终止进程。
10+ 
11+> [!NOTE]
12+>
13+> - 此环境变量仅在`TORCH_HCCL_ENABLE_MONITORING=1`时生效。
14+> - **PyTorch社区：** 社区对应环境变量 `TORCH_NCCL_HEARTBEAT_TIMEOUT_SEC`，但社区默认值为480秒，`torch_npu`与`torch`存在差异。
15+ 
16+## 配置示例
17+ 
18+```bash
19+export TORCH_HCCL_HEARTBEAT_TIMEOUT_SEC=300
20+```
21+ 
22+## 支持的型号
23+ 
24+- <term>Atlas 训练系列产品</term>
25+- <term>Atlas A2 训练系列产品</term>
26+- <term>Atlas A3 训练系列产品</term>
27+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/collective_communication/TORCH_HCCL_HIGH_PRIORITY.md+29-0
@@ -0,0 +1,29 @@
1+# TORCH\_HCCL\_HIGH\_PRIORITY
2+ 
3+## 功能描述
4+ 
5+当使用HCCL作为通信后端时，通过此环境变量可控制是否强制从高优先级NPU stream pool中获取通信流。
6+ 
7+- 0：不强制使用高优先级stream，PG option中的优先级设置可能生效。
8+- 1：强制使用高优先级NPU stream pool中的通信流。
9+ 
10+默认值：0。
11+ 
12+> [!NOTE]
13+>
14+> - 当前版本同时兼容旧名称`HCCL_HIGH_PRIORITY`。
15+> - 高优先级stream可能减少通信延迟，但可能影响计算与通信的并发调度。
16+> - **PyTorch社区：** 社区对应环境变量 `TORCH_NCCL_HIGH_PRIORITY`，默认同样为false，`torch_npu`与`torch`行为一致。
17+ 
18+## 配置示例
19+ 
20+```bash
21+export TORCH_HCCL_HIGH_PRIORITY=1
22+```
23+ 
24+## 支持的型号
25+ 
26+- <term>Atlas 训练系列产品</term>
27+- <term>Atlas A2 训练系列产品</term>
28+- <term>Atlas A3 训练系列产品</term>
29+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/collective_communication/TORCH_HCCL_STATUS_SAVE_ENABLE.md+30-0
@@ -0,0 +1,30 @@
1+# TORCH\_HCCL\_STATUS\_SAVE\_ENABLE
2+ 
3+## 功能描述
4+ 
5+当使用HCCL作为通信后端时，通过此环境变量可控制HCCL进程组状态信息的周期性保存。状态文件包含collective操作的seq、op_type、pg_id、comm_ids和status等信息，以及异常退出时的错误信息。
6+ 
7+- 0：不保存状态信息。
8+- 1：启用状态保存。
9+ 
10+默认值：0。
11+ 
12+> [!NOTE]
13+>
14+> - 此环境变量在`ProcessGroupHCCL.cpp`文件级全局初始化时读取，**应在加载`torch_npu`扩展前设置**。
15+> - 状态文件保存在`TORCH_HCCL_STATUS_SAVE_PATH`指定目录下，保存间隔由`TORCH_HCCL_STATUS_SAVE_INTERVAL`控制。
16+> - 状态保存在WatchDog线程中进行，WatchDog异常退出时会自动追加错误状态。
17+> - 此功能为`torch_npu`特有，PyTorch社区无直接对应变量。
18+ 
19+## 配置示例
20+ 
21+```bash
22+export TORCH_HCCL_STATUS_SAVE_ENABLE=1
23+```
24+ 
25+## 支持的型号
26+ 
27+- <term>Atlas 训练系列产品</term>
28+- <term>Atlas A2 训练系列产品</term>
29+- <term>Atlas A3 训练系列产品</term>
30+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/collective_communication/TORCH_HCCL_STATUS_SAVE_INTERVAL.md+26-0
@@ -0,0 +1,26 @@
1+# TORCH\_HCCL\_STATUS\_SAVE\_INTERVAL
2+ 
3+## 功能描述
4+ 
5+当使用HCCL作为通信后端时，通过此环境变量可配置HCCL进程组状态保存的间隔时间。
6+ 
7+单位为秒，默认值为2秒。如果配置为小于等于0的值，会被重置为2秒。
8+ 
9+> [!NOTE]
10+>
11+> - 此环境变量在首次调用时读取并缓存。
12+> - 仅当`TORCH_HCCL_STATUS_SAVE_ENABLE=1`时生效。
13+> - 此功能为`torch_npu`特有，PyTorch社区无直接对应变量。
14+ 
15+## 配置示例
16+ 
17+```bash
18+export TORCH_HCCL_STATUS_SAVE_INTERVAL=5
19+```
20+ 
21+## 支持的型号
22+ 
23+- <term>Atlas 训练系列产品</term>
24+- <term>Atlas A2 训练系列产品</term>
25+- <term>Atlas A3 训练系列产品</term>
26+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/collective_communication/TORCH_HCCL_STATUS_SAVE_PATH.md+28-0
@@ -0,0 +1,28 @@
1+# TORCH\_HCCL\_STATUS\_SAVE\_PATH
2+ 
3+## 功能描述
4+ 
5+当使用HCCL作为通信后端时，通过此环境变量可配置HCCL进程组状态文件的保存目录。
6+ 
7+默认值：`/tmp`。
8+ 
9+状态文件名格式为：`torch_hccl_status-<global_rank>_<master_addr>_<deviceId>_<numRanks>_<pid>_<timestamp>.log`。
10+ 
11+> [!NOTE]
12+>
13+> - 此环境变量在`ProcessGroupHCCL.cpp`文件级全局初始化时读取，**应在加载`torch_npu`扩展前设置**。
14+> - 仅当`TORCH_HCCL_STATUS_SAVE_ENABLE=1`时，状态文件才会写入该目录。
15+> - 此功能为`torch_npu`特有，PyTorch社区无直接对应变量。
16+ 
17+## 配置示例
18+ 
19+```bash
20+export TORCH_HCCL_STATUS_SAVE_PATH=/data/hccl_status
21+```
22+ 
23+## 支持的型号
24+ 
25+- <term>Atlas 训练系列产品</term>
26+- <term>Atlas A2 训练系列产品</term>
27+- <term>Atlas A3 训练系列产品</term>
28+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/collective_communication/TORCH_HCCL_TRACE_BUFFER_SIZE.md+35-0
@@ -0,0 +1,35 @@
1+# TORCH\_HCCL\_TRACE\_BUFFER\_SIZE
2+ 
3+## 功能描述
4+ 
5+当使用HCCL作为通信后端时，通过此环境变量可配置HCCL Flight Recorder环形缓冲区中最大可记录的事件数。每个事件对应一次集合通信操作的开始或结束。
6+ 
7+- 配置为0或负数时：关闭Flight Recorder记录功能，不记录任何事件，导出dump时也不包含trace内容。
8+- 配置为正整数时：开启Flight Recorder记录功能，缓冲区最多保存该数量的事件记录。
9+ 
10+单位为个数，默认值为0。
11+ 
12+> [!NOTE]
13+>
14+> - 此环境变量在`HCCLTraceBuffer`单例首次构造时读取并缓存，运行中修改不会生效。
15+> - 仅当`TRACE_BUFFER_SIZE > 0`时，`TORCH_HCCL_DUMP_ON_TIMEOUT`等超时dump功能才会产生有效内容。
16+> - **PyTorch社区：** 社区对应环境变量 `TORCH_FR_BUFFER_SIZE`（fallback `TORCH_NCCL_TRACE_BUFFER_SIZE`），但社区默认值为2000，`torch_npu`与`torch`存在差异。
17+ 
18+## 配置示例
19+ 
20+```bash
21+export TORCH_HCCL_TRACE_BUFFER_SIZE=2000
22+```
23+ 
24+## 使用约束
25+ 
26+- 此环境变量需在加载`torch_npu`扩展前设置，运行中修改无效。
27+- 缓冲区大小直接影响内存占用，建议根据实际collective数量合理配置。
28+- 开启记录后，HCCL watchDog线程会周期性处理缓冲区中的事件。
29+ 
30+## 支持的型号
31+ 
32+- <term>Atlas 训练系列产品</term>
33+- <term>Atlas A2 训练系列产品</term>
34+- <term>Atlas A3 训练系列产品</term>
35+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/collective_communication/TORCH_HCCL_TRACE_CPP_STACK.md+35-0
@@ -0,0 +1,35 @@
1+# TORCH\_HCCL\_TRACE\_CPP\_STACK
2+ 
3+## 功能描述
4+ 
5+当使用HCCL作为通信后端时，通过此环境变量可控制Flight Recorder在记录事件时是否同时采集C++调用栈。
6+ 
7+- 0：不采集C++调用栈，仅记录Python和TorchScript调用栈。
8+- 1：采集C++调用栈，在事件记录时保存C++ instruction pointer，导出dump时可通过符号化转换为函数名和行号。
9+ 
10+默认值：0。
11+ 
12+> [!NOTE]
13+>
14+> - 此环境变量在`HCCLTraceBuffer`单例首次构造时读取并缓存，运行中修改不会生效。
15+> - 此环境变量控制的是**记录阶段**是否采集栈，不等同于dump阶段是否输出栈。如果记录时未采集，dump时无法还原C++栈。
16+> - 开启C++栈采集会略微增加记录阶段的性能开销。
17+> - **PyTorch社区：** 社区对应环境变量为`TORCH_FR_CPP_STACK`（fallback `TORCH_NCCL_TRACE_CPP_STACK`），默认值同样为false。`torch_npu`与`torch`行为一致，但社区已使用`TORCH_FR_*`主名称。
18+ 
19+## 配置示例
20+ 
21+```bash
22+export TORCH_HCCL_TRACE_CPP_STACK=1
23+```
24+ 
25+## 使用约束
26+ 
27+- 需在加载`torch_npu`扩展前设置。
28+- 需同时设置`TORCH_HCCL_TRACE_BUFFER_SIZE > 0`，否则无事件可记录。
29+ 
30+## 支持的型号
31+ 
32+- <term>Atlas 训练系列产品</term>
33+- <term>Atlas A2 训练系列产品</term>
34+- <term>Atlas A3 训练系列产品</term>
35+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/collective_communication/TORCH_HCCL_WAIT_TIMEOUT_DUMP_MILSEC.md+27-0
@@ -0,0 +1,27 @@
1+# TORCH\_HCCL\_WAIT\_TIMEOUT\_DUMP\_MILSEC
2+ 
3+## 功能描述
4+ 
5+当使用HCCL作为通信后端时，通过此环境变量可设置heartbeat monitor等待异步dump完成的最大时间。
6+ 
7+单位为ms，默认值为60000（60秒）。
8+ 
9+当发生超时触发dump时，monitor会等待其他rank的dump完成。超过此时间后，无论dump是否完成，monitor都会终止进程。
10+ 
11+> [!NOTE]
12+>
13+> - 此环境变量仅在`TORCH_HCCL_ENABLE_MONITORING=1`时生效。
14+> - **PyTorch社区：** 社区对应环境变量 `TORCH_FR_WAIT_TIMEOUT_DUMP_MILSEC`（fallback `TORCH_NCCL_WAIT_TIMEOUT_DUMP_MILSEC`），但社区默认值为15000（15秒），`torch_npu`与`torch`存在差异。
15+ 
16+## 配置示例
17+ 
18+```bash
19+export TORCH_HCCL_WAIT_TIMEOUT_DUMP_MILSEC=30000
20+```
21+ 
22+## 支持的型号
23+ 
24+- <term>Atlas 训练系列产品</term>
25+- <term>Atlas A2 训练系列产品</term>
26+- <term>Atlas A3 训练系列产品</term>
27+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/collective_communication/TP_SOCKET_IFNAME.md+28-0
@@ -0,0 +1,28 @@
1+# TP\_SOCKET\_IFNAME
2+ 
3+## 功能描述
4+ 
5+通过此环境变量可指定TensorPipe RPC传输层使用的网络接口名称。当节点有多个网络接口时，用于绑定特定的网卡。
6+ 
7+- 未设置：按hostname解析IP地址。
8+- 设置接口名：绑定指定网卡，通过`lookupAddrForIface`查找该接口的IP地址。
9+- 如果指定接口查找失败：回退到`127.0.0.1`。
10+ 
11+默认值：未设置（按hostname解析）。
12+ 
13+> [!NOTE]
14+>
15+> **PyTorch社区：** `torch_npu`与`torch`对应环境变量同名，行为一致。
16+ 
17+## 配置示例
18+ 
19+```bash
20+export TP_SOCKET_IFNAME=eth0
21+```
22+ 
23+## 支持的型号
24+ 
25+- <term>Atlas 训练系列产品</term>
26+- <term>Atlas A2 训练系列产品</term>
27+- <term>Atlas A3 训练系列产品</term>
28+- <term>Ascend 950DT</term>
Mdocs/zh/api/environment_variable/collective_communication/_menu_collective_communication.md+19-0
@@ -7,3 +7,22 @@
7- [P2P_HCCL_BUFFSIZE](P2P_HCCL_BUFFSIZE.md)7- [P2P_HCCL_BUFFSIZE](P2P_HCCL_BUFFSIZE.md)
8- [RANK_TABLE_FILE](RANK_TABLE_FILE.md)8- [RANK_TABLE_FILE](RANK_TABLE_FILE.md)
9- [（beta）TORCH_HCCL_ZERO_COPY](（beta）TORCH_HCCL_ZERO_COPY.md)9- [（beta）TORCH_HCCL_ZERO_COPY](（beta）TORCH_HCCL_ZERO_COPY.md)
10+- [TORCH_HCCL_TRACE_BUFFER_SIZE](TORCH_HCCL_TRACE_BUFFER_SIZE.md)
11+- [TORCH_HCCL_TRACE_CPP_STACK](TORCH_HCCL_TRACE_CPP_STACK.md)
12+- [TORCH_HCCL_DUMP_ON_TIMEOUT](TORCH_HCCL_DUMP_ON_TIMEOUT.md)
13+- [TORCH_HCCL_WAIT_TIMEOUT_DUMP_MILSEC](TORCH_HCCL_WAIT_TIMEOUT_DUMP_MILSEC.md)
14+- [TORCH_HCCL_DEBUG_INFO_PIPE_FILE](TORCH_HCCL_DEBUG_INFO_PIPE_FILE.md)
15+- [TORCH_HCCL_DEBUG_INFO_TEMP_FILE](TORCH_HCCL_DEBUG_INFO_TEMP_FILE.md)
16+- [TORCH_HCCL_HIGH_PRIORITY](TORCH_HCCL_HIGH_PRIORITY.md)
17+- [TORCH_HCCL_ENABLE_MONITORING](TORCH_HCCL_ENABLE_MONITORING.md)
18+- [TORCH_HCCL_HEARTBEAT_TIMEOUT_SEC](TORCH_HCCL_HEARTBEAT_TIMEOUT_SEC.md)
19+- [TORCH_HCCL_COORD_CHECK_MILSEC](TORCH_HCCL_COORD_CHECK_MILSEC.md)
20+- [TORCH_HCCL_STATUS_SAVE_ENABLE](TORCH_HCCL_STATUS_SAVE_ENABLE.md)
21+- [TORCH_HCCL_STATUS_SAVE_PATH](TORCH_HCCL_STATUS_SAVE_PATH.md)
22+- [TORCH_HCCL_STATUS_SAVE_INTERVAL](TORCH_HCCL_STATUS_SAVE_INTERVAL.md)
23+- [NSLB_CP](NSLB_CP.md)
24+- [NSLB_MAX_RECORD_NUM](NSLB_MAX_RECORD_NUM.md)
25+- [PERF_DUMP_CONFIG](PERF_DUMP_CONFIG.md)
26+- [PERF_DUMP_PATH](PERF_DUMP_PATH.md)
27+- [TP_SOCKET_IFNAME](TP_SOCKET_IFNAME.md)
28+- [DDP_SET_LAST_BUCKET_CAP](DDP_SET_LAST_BUCKET_CAP.md)
Adocs/zh/api/environment_variable/distributed_startup/ENABLE_TIERED_PARALLEL_TCPSTORE.md+28-0
@@ -0,0 +1,28 @@
1+# ENABLE\_TIERED\_PARALLEL\_TCPSTORE
2+ 
3+## 功能描述
4+ 
5+通过此环境变量可控制ParallelStore是否启用分层建链（tiered）优化模式。分层建链将建链复杂度从O(n)降低到O(sqrt(n))，在大规模集群场景下显著提升建链性能。
6+ 
7+- 字符串"true"（大小写不敏感）：开启分层建链。
8+- 其他值：关闭。
9+ 
10+默认值：`torch_npu_run`命令行参数`--enable_tiered_parallel_tcpstore`的默认值，通常为"false"。
11+ 
12+> [!NOTE]
13+>
14+> - 此环境变量在`torch_npu_run`的`_create_parallel_handler`中通过`setdefault`写入，通常由`torch_npu_run`的`--enable_tiered_parallel_tcpstore`参数控制，详细说明可参考[torch_npu_run使用指导](../../../developer_notes/distributed/torch_npu_run.md#使用指导)。
15+> - 此功能为`torch_npu`特有，PyTorch社区无直接对应变量。
16+ 
17+## 配置示例
18+ 
19+```bash
20+export ENABLE_TIERED_PARALLEL_TCPSTORE=true
21+```
22+ 
23+## 支持的型号
24+ 
25+- <term>Atlas 训练系列产品</term>
26+- <term>Atlas A2 训练系列产品</term>
27+- <term>Atlas A3 训练系列产品</term>
28+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/distributed_startup/PROXY_AGENT_PID_USE_LOCAL_SOCKET_PATH.md+28-0
@@ -0,0 +1,28 @@
1+# PROXY\_AGENT\_PID\_USE\_LOCAL\_SOCKET\_PATH
2+ 
3+## 功能描述
4+ 
5+通过此环境变量可将agent进程的PID传递给ParallelStore，用于控制本地socket路径的生成。
6+ 
7+默认值：-1（表示未设置）。
8+ 
9+在`torch_npu_run`的`_create_parallel_handler`中，通过`setdefault`将当前进程PID写入此变量。
10+ 
11+> [!NOTE]
12+>
13+> 此功能为`torch_npu`特有，PyTorch社区无直接对应变量。
14+ 
15+## 配置示例
16+ 
17+通常无需手动配置，由`torch_npu_run`自动设置。
18+ 
19+```bash
20+export PROXY_AGENT_PID_USE_LOCAL_SOCKET_PATH=12345
21+```
22+ 
23+## 支持的型号
24+ 
25+- <term>Atlas 训练系列产品</term>
26+- <term>Atlas A2 训练系列产品</term>
27+- <term>Atlas A3 训练系列产品</term>
28+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/distributed_startup/TORCH_NPU_ELASTIC_USE_AGENT_STORE.md+29-0
@@ -0,0 +1,29 @@
1+# TORCH\_NPU\_ELASTIC\_USE\_AGENT\_STORE
2+ 
3+## 功能描述
4+ 
5+通过此环境变量可控制是否使用agent已启动的ParallelStore。启用后，所有worker连接agent已启动的ParallelStore，并包裹`PrefixStore("/worker/attempt_<n>")`前缀来隔离每次重启。
6+ 
7+- 精确等于字符串"True"（大小写敏感）：启用agent store模式。
8+- 其他值：关闭。
9+ 
10+默认值：未设置。
11+ 
12+> [!NOTE]
13+>
14+> - 当启用agent store时，需要同时设置`TORCHELASTIC_RESTART_COUNT`环境变量（由torchrun/elastic启动器注入），否则会抛出`KeyError`。
15+> - 使用`torch_npu_run`启动时，`_create_parallel_handler`中会通过`setdefault`默认写入`TORCH_NPU_ELASTIC_USE_AGENT_STORE=True`，通常无需手动配置此变量。
16+> - **PyTorch社区：** 社区对应环境变量 `TORCHELASTIC_USE_AGENT_STORE`，`torch_npu`与`torch`名称不同。
17+ 
18+## 配置示例
19+ 
20+```bash
21+export TORCH_NPU_ELASTIC_USE_AGENT_STORE=True
22+```
23+ 
24+## 支持的型号
25+ 
26+- <term>Atlas 训练系列产品</term>
27+- <term>Atlas A2 训练系列产品</term>
28+- <term>Atlas A3 训练系列产品</term>
29+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/distributed_startup/TORCH_NPU_USE_PARALLEL_TCPSTORE.md+30-0
@@ -0,0 +1,30 @@
1+# TORCH\_NPU\_USE\_PARALLEL\_TCPSTORE
2+ 
3+## 功能描述
4+ 
5+通过此环境变量可控制是否将`env://` rendezvous URL改为`parallel://`，从而启用ParallelStore作为分布式存储后端，提升建链性能。
6+ 
7+- 精确等于字符串"True"（大小写敏感）：启用ParallelStore，将`env://`改写为`parallel://<MASTER_ADDR>:<MASTER_PORT>`。
8+- 其他值（包括"true"、"TRUE"）：视为关闭。
9+ 
10+默认值："False"。
11+ 
12+> [!NOTE]
13+>
14+> - 此环境变量仅在`torch_npu`分布式初始化时通过`torch_npu.distributed`的`_trigger_rendezvous_decorator`读取。
15+> - 使用`torch_npu_run`启动时，默认会设置此环境变量，通常无需手动配置。
16+> - 启用后，`MASTER_ADDR`缺省值为`127.0.0.1`，`MASTER_PORT`缺省值为`29500`。
17+> - 此功能为`torch_npu`特有，PyTorch社区无直接对应变量。
18+ 
19+## 配置示例
20+ 
21+```bash
22+export TORCH_NPU_USE_PARALLEL_TCPSTORE=True
23+```
24+ 
25+## 支持的型号
26+ 
27+- <term>Atlas 训练系列产品</term>
28+- <term>Atlas A2 训练系列产品</term>
29+- <term>Atlas A3 训练系列产品</term>
30+- <term>Ascend 950DT</term>
Adocs/zh/api/environment_variable/distributed_startup/_menu_distributed_startup.md+6-0
@@ -0,0 +1,6 @@
1+# 分布式启动
2+ 
3+- [TORCH_NPU_USE_PARALLEL_TCPSTORE](TORCH_NPU_USE_PARALLEL_TCPSTORE.md)
4+- [TORCH_NPU_ELASTIC_USE_AGENT_STORE](TORCH_NPU_ELASTIC_USE_AGENT_STORE.md)
5+- [ENABLE_TIERED_PARALLEL_TCPSTORE](ENABLE_TIERED_PARALLEL_TCPSTORE.md)
6+- [PROXY_AGENT_PID_USE_LOCAL_SOCKET_PATH](PROXY_AGENT_PID_USE_LOCAL_SOCKET_PATH.md)
Mdocs/zh/api/environment_variable/env_variable_list.md+29-0
@@ -34,6 +34,7 @@
34|[OOM_SNAPSHOT_PATH](memory_management/OOM_SNAPSHOT_PATH.md)|通过此环境变量可配置在内存不足报错时内存数据的保存路径。|34|[OOM_SNAPSHOT_PATH](memory_management/OOM_SNAPSHOT_PATH.md)|通过此环境变量可配置在内存不足报错时内存数据的保存路径。|
35|[MULTI_STREAM_MEMORY_REUSE](memory_management/MULTI_STREAM_MEMORY_REUSE.md)|通过此环境变量可配置多流内存复用是否开启。|35|[MULTI_STREAM_MEMORY_REUSE](memory_management/MULTI_STREAM_MEMORY_REUSE.md)|通过此环境变量可配置多流内存复用是否开启。|
36|[TORCH_NPUGRAPH_GC](memory_management/TORCH_NPUGRAPH_GC.md)|通过此环境变量可控制图捕获模式（NPUGraph Capture）过程中是否主动触发Python GC（Garbage Collection）。|36|[TORCH_NPUGRAPH_GC](memory_management/TORCH_NPUGRAPH_GC.md)|通过此环境变量可控制图捕获模式（NPUGraph Capture）过程中是否主动触发Python GC（Garbage Collection）。|
37+|[NPU_SHMEM_SYMMETRIC_SIZE](memory_management/NPU_SHMEM_SYMMETRIC_SIZE.md)|通过此环境变量可配置NPU对称内存的堆大小，用于设备间直接内存访问。|
37 38 
38**表 4** 集合通信环境变量列表39**表 4** 集合通信环境变量列表
39 40 
@@ -46,6 +47,25 @@
46|[P2P_HCCL_BUFFSIZE](collective_communication/P2P_HCCL_BUFFSIZE.md)|通过此环境变量可配置是否开启点对点通信（`torch.distributed.isend`、`torch.distributed.irecv`和`torch.distributed.batch_isend_irecv`），并使用独立通信域功能。|47|[P2P_HCCL_BUFFSIZE](collective_communication/P2P_HCCL_BUFFSIZE.md)|通过此环境变量可配置是否开启点对点通信（`torch.distributed.isend`、`torch.distributed.irecv`和`torch.distributed.batch_isend_irecv`），并使用独立通信域功能。|
47|[RANK_TABLE_FILE](collective_communication/RANK_TABLE_FILE.md)|通过此环境变量可配置RANK_TABLE_FILE文件的路径，用于集合通信域建链。|48|[RANK_TABLE_FILE](collective_communication/RANK_TABLE_FILE.md)|通过此环境变量可配置RANK_TABLE_FILE文件的路径，用于集合通信域建链。|
48|[(beta) TORCH_HCCL_ZERO_COPY](collective_communication/（beta）TORCH_HCCL_ZERO_COPY.md)|训练或在线推理场景下，可通过此环境变量开启集合通信片内零拷贝功能，减少通信算子在通信过程中片内拷贝次数，提升集合通信效率，降低通信耗时。同时在计算通信并行场景下，降低通信过程中对显存带宽的抢占。|49|[(beta) TORCH_HCCL_ZERO_COPY](collective_communication/（beta）TORCH_HCCL_ZERO_COPY.md)|训练或在线推理场景下，可通过此环境变量开启集合通信片内零拷贝功能，减少通信算子在通信过程中片内拷贝次数，提升集合通信效率，降低通信耗时。同时在计算通信并行场景下，降低通信过程中对显存带宽的抢占。|
50+|[TORCH_HCCL_TRACE_BUFFER_SIZE](collective_communication/TORCH_HCCL_TRACE_BUFFER_SIZE.md)|当使用HCCL作为通信后端时，通过此环境变量可配置Flight Recorder环形缓冲区最大事件数，默认关闭。|
51+|[TORCH_HCCL_TRACE_CPP_STACK](collective_communication/TORCH_HCCL_TRACE_CPP_STACK.md)|当使用HCCL作为通信后端时，通过此环境变量可控制在记录事件时是否采集C++调用栈。|
52+|[TORCH_HCCL_DUMP_ON_TIMEOUT](collective_communication/TORCH_HCCL_DUMP_ON_TIMEOUT.md)|当使用HCCL作为通信后端时，通过此环境变量可控制超时或错误时是否自动触发Flight Recorder dump。|
53+|[TORCH_HCCL_WAIT_TIMEOUT_DUMP_MILSEC](collective_communication/TORCH_HCCL_WAIT_TIMEOUT_DUMP_MILSEC.md)|当使用HCCL作为通信后端时，通过此环境变量可设置monitor等待异步dump完成的最大时间。|
54+|[TORCH_HCCL_DEBUG_INFO_PIPE_FILE](collective_communication/TORCH_HCCL_DEBUG_INFO_PIPE_FILE.md)|当使用HCCL作为通信后端时，通过此环境变量可配置命名管道文件，用于外部触发Flight Recorder dump。|
55+|[TORCH_HCCL_DEBUG_INFO_TEMP_FILE](collective_communication/TORCH_HCCL_DEBUG_INFO_TEMP_FILE.md)|通过此环境变量可配置HCCL dump文件的名称前缀。|
56+|[TORCH_HCCL_HIGH_PRIORITY](collective_communication/TORCH_HCCL_HIGH_PRIORITY.md)|当使用HCCL作为通信后端时，通过此环境变量可控制是否强制使用高优先级NPU stream。|
57+|[TORCH_HCCL_ENABLE_MONITORING](collective_communication/TORCH_HCCL_ENABLE_MONITORING.md)|当使用HCCL作为通信后端时，通过此环境变量可控制是否启动heartbeat monitor线程。|
58+|[TORCH_HCCL_HEARTBEAT_TIMEOUT_SEC](collective_communication/TORCH_HCCL_HEARTBEAT_TIMEOUT_SEC.md)|当使用HCCL作为通信后端时，通过此环境变量可设置heartbeat monitor判定WatchDog卡死的超时时间。|
59+|[TORCH_HCCL_COORD_CHECK_MILSEC](collective_communication/TORCH_HCCL_COORD_CHECK_MILSEC.md)|当使用HCCL作为通信后端时，通过此环境变量可设置WatchDog轮询检查Store dump signal的间隔时间。|
60+|[TORCH_HCCL_STATUS_SAVE_ENABLE](collective_communication/TORCH_HCCL_STATUS_SAVE_ENABLE.md)|通过此环境变量可控制HCCL进程组状态信息的周期性保存。|
61+|[TORCH_HCCL_STATUS_SAVE_PATH](collective_communication/TORCH_HCCL_STATUS_SAVE_PATH.md)|通过此环境变量可配置HCCL状态文件的保存目录。|
62+|[TORCH_HCCL_STATUS_SAVE_INTERVAL](collective_communication/TORCH_HCCL_STATUS_SAVE_INTERVAL.md)|通过此环境变量可配置HCCL状态保存的间隔时间。|
63+|[NSLB_CP](collective_communication/NSLB_CP.md)|通过此环境变量可配置HCCL NSLB采样记录的目录路径。|
64+|[NSLB_MAX_RECORD_NUM](collective_communication/NSLB_MAX_RECORD_NUM.md)|通过此环境变量可配置每个PG的最大NSLB采样记录数量。|
65+|[PERF_DUMP_CONFIG](collective_communication/PERF_DUMP_CONFIG.md)|通过此环境变量可配置HCCL操作的性能数据记录功能。|
66+|[PERF_DUMP_PATH](collective_communication/PERF_DUMP_PATH.md)|通过此环境变量可配置HCCL性能dump文件的输出目录。|
67+|[TP_SOCKET_IFNAME](collective_communication/TP_SOCKET_IFNAME.md)|通过此环境变量可指定TensorPipe RPC传输层使用的网络接口名称。|
68+|[DDP_SET_LAST_BUCKET_CAP](collective_communication/DDP_SET_LAST_BUCKET_CAP.md)|通过此环境变量可控制DDP的bucket重建顺序。|
49 69 
50**表 5** 告警信息打印环境变量列表70**表 5** 告警信息打印环境变量列表
51 71 
@@ -98,3 +118,12 @@
98|[NPU_INDUCTOR_FALLBACK_LIST](inductor/NPU_INDUCTOR_FALLBACK_LIST.md)|通过此环境变量可指定需要回退到PyTorch原生的算子列表。|118|[NPU_INDUCTOR_FALLBACK_LIST](inductor/NPU_INDUCTOR_FALLBACK_LIST.md)|通过此环境变量可指定需要回退到PyTorch原生的算子列表。|
99|[（beta）TORCHINDUCTOR_ENABLE_MFUSION](inductor/TORCHINDUCTOR_ENABLE_MFUSION.md)|通过此环境变量可控制是否启用MFusion融合优化功能，仅在torch.compile图编译后端为"Inductor"生效。|119|[（beta）TORCHINDUCTOR_ENABLE_MFUSION](inductor/TORCHINDUCTOR_ENABLE_MFUSION.md)|通过此环境变量可控制是否启用MFusion融合优化功能，仅在torch.compile图编译后端为"Inductor"生效。|
100|[TORCHINDUCTOR_USE_AKG](inductor/TORCHINDUCTOR_USE_AKG.md)|通过此环境变量可配置torch.compile图模式（Inductor）下MLIR（Multi-Level Intermediate Representation）模式启用AKG（Auto Kernel Generator）后端优化。|120|[TORCHINDUCTOR_USE_AKG](inductor/TORCHINDUCTOR_USE_AKG.md)|通过此环境变量可配置torch.compile图模式（Inductor）下MLIR（Multi-Level Intermediate Representation）模式启用AKG（Auto Kernel Generator）后端优化。|
121+ 
122+**表 11** 分布式启动环境变量列表
123+ 
124+|环境变量名称|简介|
125+|--|--|
126+|[TORCH_NPU_USE_PARALLEL_TCPSTORE](distributed_startup/TORCH_NPU_USE_PARALLEL_TCPSTORE.md)|通过此环境变量可控制是否启用ParallelStore作为分布式存储后端，提升建链性能。|
127+|[TORCH_NPU_ELASTIC_USE_AGENT_STORE](distributed_startup/TORCH_NPU_ELASTIC_USE_AGENT_STORE.md)|通过此环境变量可控制是否使用agent已启动的ParallelStore。|
128+|[ENABLE_TIERED_PARALLEL_TCPSTORE](distributed_startup/ENABLE_TIERED_PARALLEL_TCPSTORE.md)|通过此环境变量可控制ParallelStore是否启用分层建链优化模式。|
129+|[PROXY_AGENT_PID_USE_LOCAL_SOCKET_PATH](distributed_startup/PROXY_AGENT_PID_USE_LOCAL_SOCKET_PATH.md)|通过此环境变量可将agent PID传递给ParallelStore，用于本地socket路径生成。|
Adocs/zh/api/environment_variable/memory_management/NPU_SHMEM_SYMMETRIC_SIZE.md+33-0
@@ -0,0 +1,33 @@
1+# NPU\_SHMEM\_SYMMETRIC\_SIZE
2+ 
3+## 功能描述
4+ 
5+通过此环境变量可配置NPU对称内存（symmetric memory）的堆大小。对称内存用于NPU设备间的直接内存访问，是NPUSHMEM功能的基础。
6+ 
7+默认值为1 GiB。支持以下格式：
8+- 纯数字（字节）：例如`1073741824`表示1 GiB。
9+- 数字加后缀：`k/K`（KB）、`m/M`（MB）、`g/G`（GB）、`t/T`（TB）。
10+ 
11+> [!NOTE]
12+>
13+> - 此环境变量在首次调用`OptionsManager::GetShmemSymmetricSize`时读取并缓存，运行中修改不会生效。
14+> - 该值传递给`aclshmemx_init_attr`或`shmem_set_attr`用于初始化对称内存区域。
15+> - 配置值必须为正数，非法格式会抛出`NPU_SHMEM_SYMMETRIC_SIZE is invalid`错误。
16+> - 此功能为`torch_npu`特有，PyTorch社区无直接对应变量。
17+ 
18+## 配置示例
19+ 
20+```bash
21+# 配置为2 GiB
22+export NPU_SHMEM_SYMMETRIC_SIZE=2G
23+ 
24+# 配置为512 MB
25+export NPU_SHMEM_SYMMETRIC_SIZE=512M
26+```
27+ 
28+## 支持的型号
29+ 
30+- <term>Atlas 训练系列产品</term>
31+- <term>Atlas A2 训练系列产品</term>
32+- <term>Atlas A3 训练系列产品</term>
33+- <term>Ascend 950DT</term>
Mdocs/zh/api/environment_variable/memory_management/_menu_memory_management.md+1-0
@@ -6,3 +6,4 @@
6- [OOM_SNAPSHOT_PATH](OOM_SNAPSHOT_PATH.md)6- [OOM_SNAPSHOT_PATH](OOM_SNAPSHOT_PATH.md)
7- [MULTI_STREAM_MEMORY_REUSE](MULTI_STREAM_MEMORY_REUSE.md)7- [MULTI_STREAM_MEMORY_REUSE](MULTI_STREAM_MEMORY_REUSE.md)
8- [TORCH_NPUGRAPH_GC](TORCH_NPUGRAPH_GC.md)8- [TORCH_NPUGRAPH_GC](TORCH_NPUGRAPH_GC.md)
9+- [NPU_SHMEM_SYMMETRIC_SIZE](NPU_SHMEM_SYMMETRIC_SIZE.md)