【合入来源】

• 需求
• 问题单
• issue/工单
• 重构优化
• 资料更新

【修改方案】

一、触发层

1. torch-npu-upstream-test-trigger.yml — 入口触发器

触发方式：schedule（每日 UTC 11:00）+ workflow_dispatch（手动）

唯一的作用是接收触发事件，将参数（python_version、分片数、test_files 等）传递给下游主编排 workflow。本身不执行任何
job，只是一个可复用的参数入口。

---

二、编排层

2. _torch-npu-upstream-test.yml — 主编排器

类型：workflow_call（被 trigger 调用）

定义了 7 个 job 的执行顺序和条件分支：

┌──────────────────┬───────────────────────────┬────────────────────┐
│ Job │ 依赖 │ 条件 │
├──────────────────┼───────────────────────────┼────────────────────┤
│ prepare │ 无 │ 总是执行 │
├──────────────────┼───────────────────────────┼────────────────────┤
│ build_torch_npu │ prepare │ 总是执行 │
├──────────────────┼───────────────────────────┼────────────────────┤
│ collect_cases │ prepare + build │ test_files 为空 │
├──────────────────┼───────────────────────────┼────────────────────┤
│ test_distributed │ prepare + build + collect │ test_files 为空 │
├──────────────────┼───────────────────────────┼────────────────────┤
│ test_regular │ prepare + build + collect │ test_files 为空 │
├──────────────────┼───────────────────────────┼────────────────────┤
│ test_custom │ prepare + build │ test_files 不为空 │
├──────────────────┼───────────────────────────┼────────────────────┤
│ report │ 所有以上 job │ always()，汇总输出 │
└──────────────────┴───────────────────────────┴────────────────────┘

两个执行路径：

• 全量模式（默认）：走 collect → distributed + regular 分片测试
• 指定文件模式（手动触发传 test_files）：跳过 collect，直接跑 custom 测试

---

三、执行层 — Workflow

3. _torch-npu-upstream-prepare.yml — 准备测试源码

• Clone 上游 PyTorch 源码（pytorch/pytorch）
• 拷贝 test_upstream/ 补丁目录
• 执行 apply_patch.sh 打 NPU 适配补丁
• 打包并上传 patched 源码为 artifact
• 输出 patch_count（补丁数量）供 report 使用

4. _torch-npu-upstream-build.yml — 构建 torch_npu Wheel

• 运行在 linux-aarch64-a3-2（ARM64 + NPU 构建机）
• 在 Docker 容器内从源码编译 torch_npu
• 使用 ccache 加速 C++ 编译
• 上传构建产物 .whl 为 artifact
• 输出 wheel_name 和 build_status

5. _torch-npu-upstream-collect.yml — 收集并分片测试用例

• 运行在 linux-aarch64-a3-8（8 卡 NPU 机器）
• 调用 collect_all_cases.py 遍历 test/ 目录
• 按 case_paths_ci.yml 配置将用例分为 distributed 和 regular 两类
• 每类按分片数（默认 distributed=2, regular=5）拆成多个 JSON 文件
• 输出 distributed_matrix / regular_matrix（JSON 数组，供 matrix strategy 使用）

6. _torch-npu-upstream-test-dist.yml — 执行分布式测试

• 运行在 linux-aarch64-a3-16（16 卡 NPU）
• 使用 strategy.matrix 并行跑多个 shard（max-parallel: 2）
• 每个 shard 调用 run_npu_test_shard.py，串行执行该分片内的用例
• timeout: 1200 分钟（20 小时）
• 失败时单独上传 error-logs

7. _torch-npu-upstream-test-regular.yml — 执行常规测试

• 运行在 linux-aarch64-a3-16（16 卡 NPU）
• 使用 strategy.matrix 并行跑多个 shard（max-parallel: 5）
• 每个 shard 调用 run_npu_test_shard.py，64 并发执行该分片内的用例
• timeout: 1200 分钟

8. _torch-npu-upstream-test-custom.yml — 执行指定文件测试

• 运行在 linux-aarch64-a3-8
• 不走 collect/shard 流程，直接对用户指定的文件执行测试
• 单 job，无 matrix 并行

9. _torch-npu-upstream-report.yml — 生成测试报告

• 运行在 ubuntu-latest（普通 x86 runner，无需 NPU）
• 下载所有 shard 的测试报告 artifact（distributed + regular + custom）
• 调用 generate_npu_full_test_report.py 生成：
  • npu-full-test-summary.md — Markdown 报告
  • npu-full-test-summary.json — 结构化数据
• 将 Markdown 追加到 GITHUB_STEP_SUMMARY

---

四、共享 Action

10. setup-npu-test-env/action.yml — NPU 测试环境初始化

类型：composite action
被调用方：collect / test_distributed / test_regular / test_custom 四个 workflow

这是一个被多个测试 job 复用的环境准备步骤组合，包含：

1. Checkout Ascend/pytorch 仓库（获取脚本和配置）
2. pip 缓存（与 build job 共享 key）
3. 下载并安装构建好的 torch_npu wheel
4. 安装上游 PyTorch + triton-ascend
5. 下载并解压 patched 测试源码
6. 验证 NPU 设备可用性
7. 安装测试依赖（requirements.txt, requirements-ci.txt）
8. 执行 torch_env_patch.sh（环境级 NPU 适配脚本）

---

五、脚本层

11. collect_all_cases.py — 用例收集与分片

• 扫描 test/ 目录，根据 case_paths_ci.yml 配置归类用例
• 将 distributed 和 regular 用例按指定分片数分配到不同 JSON 文件
• 输出 cases_collection_summary.json 记录总数等统计信息

12. run_npu_test_shard.py — 测试执行引擎

• 两种模式：
  • 分片模式：读取 *_cases_shard_N.json，执行该分片内的所有用例
  • 文件模式：直接执行 --test-files 指定的文件
• 支持串行/并发执行（--max-workers）
• 支持 --disabled-testcases 黑名单跳过
• 生成 JUnit XML 报告 + 单用例日志

13. generate_npu_full_test_report.py — 报告生成

• 聚合所有 shard 的测试结果 JSON
• 生成 Markdown 摘要（通过率、失败列表、耗时统计等）
• 生成按文件分组的 *_cases_results_by_file.jsonl

14. discover_test_files.py — 测试文件发现

• 扫描指定目录找出所有测试文件

15. parse_test_results.py — 测试结果解析

• 解析 JUnit XML 或测试输出日志，提取通过/失败/跳过统计

---

整体数据流

trigger.yml
│ schedule (每日) 或 workflow_dispatch (手动)
▼
_torch-npu-upstream-test.yml （编排层，路由到两条路径之一）
│
├─ [路径A: test_files为空] 全量测试
│ prepare → build → collect → test_distributed (matrix并行)
│ → test_regular (matrix并行)
│ │
│ ▼
│ report (汇总)
│
└─ [路径B: test_files指定] 指定文件测试
prepare → build → test_custom → report (汇总)

每个测试 job 都通过 setup-npu-test-env action 统一初始化环境（装 wheel、装依赖、打补丁），保证一致性。

【资料变更】

不涉及

【接口变更】

不涉及

【功能验证】

https://github.com/Ascend/pytorch/actions/runs/25964865787

【CheckList】

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

• 代码注释完备，正确记录错误日志
• 代码实现进行了返回值、空指针等校验
• PR标题正确使用类型标签，如：feat、fix、refactor、docs、test等
• PR持续集成流水线（CI）执行通过，代码检查无异常