多维并行能力组合验证

HyperParallel：`examples` 目录 — 多并行维完备性验证设计

本文档说明在 hyper-parallel 仓库的 examples/ 下，如何分层、有约束地覆盖 TP、EP、CP、FSDP2（及与之强绑定的 HSDP/DP-replicate、ETP、SP 等）的组合完备性验证，避免对「所有笛卡尔积」做无意义穷举。参考来源：

来源	作用
PyTorch `examples/distributed/tensor_parallelism`	基线：纯 TP、TP+序（SP）示例、`FSDP+TP(+SP)` 与 Mini Llama 的脚本形态与 `torchrun` 约定。
TorchTitan `ParallelDims` + 各模型 `parallelize`	权威 mesh 代数、维名、`world_size` 等式、`ep>1 ⇒ (etp==tp ∨ etp==1)`、`seq_len` 整除、稠密/稀疏双栈 FSDP（`docs/design_moe_fsdp_dual_stack.md`）。
VeOmni `init_parallel_state` + `ParallelPlan` + 约束文档	Ulysses/CP 与 FSDP 的 `dp_shard_sp` 融合、EP 的 `[ep × ep_fsdp]` 子网、FSDP2 `fully_shard` 与专家放置；测试侧 `tests/tools/training_utils.build_torchrun_cmd` 的参数注入模式。

关联文档：docs/design_moe_fsdp_dual_stack.md（MoE+FSDP 双栈）、docs/design_expert_tensor_parallel.md（ETP）、docs/design_no_parallel.md（Router/复制型 DTensor）。

1. 目标与非目标

1.1 目标

在 examples/ 中提供可单节点 torchrun 复现的脚本，证明 HyperParallel 在声明的并行维组合上 前向+反向+一步优化（可选） 可跑通，且与参考基线（单卡/已知好配置）在可接受容差内一致。
为 CI / 夜间任务提供小 world size 的分级清单（冒烟 / 全矩阵子集）。
文档化每类组合的 mesh 构造、顺序、整除/互斥 与上游一致，便于和 TorchTitan / VeOmni 对照。

1.2 非目标

不追求与 Titan 全量生产训练脚本（checkpoint、监控、多机 rdzv）字节级一致。
不在首版就覆盖 PP>1、DeepEP、异步 TP/EP 等，除非单独 RFC；可在矩阵中标为 N×（不纳入首版）。
Ulysses（VeOmni 的序列并行子维）在语义上接近 TP+SP/CP 的组合表达，若 hyper 的「CP」与 VeOmni 的 cp 命名对齐则合并验证；若实现分叉，在矩阵中单列标 「与 VeOmni 对齐时单独测」。

2. 并行维符号与有效域

2.1 本设计采用的维（与 TorchTitan 对齐主符号）

维	含义	开条件（示意）	与 FSDP2 关系
dp_replicate	HSDP 外层 DDP/复制	`>1`	常与 `fsdp` 子网格组合为 `["dp_replicate","fsdp"]`
dp_shard	数据分片度（FSDP 的「数据维」基）	`>=1`	与 `cp` 在 Titan 中叠在 `fsdp = dp_shard × cp` 上
cp	上下文并行（attention 上 ring/LB 等）	`>1`	叠在 `fsdp` 维；整除 `seq_len` 见 2.3
tp	张量并行	`>1`	稠密 `Rowwise/Colwise/SequenceParallel`
FSDP2	`fully_shard` 使用的 mesh	通常 `dp_shard>1` 或 `cp>1`（Titan 倾向仍包 FSDP）	显式作为「是否调用 FSDP2」列，而非独立整数维
ep	专家并行	`>1`	仅 MoE 模型/桩；走 all-to-all 与 `ep` mesh
etp	专家内张量并行	`>1` 且与 `ep` 同用	约束只与 `ep>1` 同时出现；Titan：`etp==tp` 或 `etp==1`
SP	序列维并行（Titan 开关 `enable_sequence_parallel`）	常随 TP	影响整除与 FFN/Loss 侧 layout

pp 若未在首版 examples 支持，不纳入完备性主表，可在附录保留占位。

2.2 World size 等式（稠密，无 EP 在「度」上挤占时）

Titan 主式（ParallelDims）：

[
\text{dp_replicate} \times \text{dp_shard} \times \text{cp} \times \text{tp} \times \text{pp} = \text{world_size}.
]

含 EP/ETP 时，专家域走 另一张 sparse_mesh 的展开，不乘进上式；须保证 build_mesh 的构造与 rank 布局 在 hyper 的 mesh API 中与 Titan 文档一致（或显式记偏差）。

VeOmni：全局 mesh 在 >1 时包含 pp, dp_replicate, dp_shard, ulysses, cp, tp 等；EP 通过 extra_parallel_sizes 等构造 [ep, ep_fsdp] 子网，world_size % ep == 0。Examples 中若以 VeOmni 为对照，同一脚本 应注明 Titan 维名 ↔ VeOmni 维名 映射表（见 §6）。

2.3 序列与形状整除

Titan 风格：seq_len % (tp × cp × 2) == 0（seq_len_divisor，含 SP+默认 CP 负载平衡假设）。
任意无 CP（cp=1）时退化为与 TP+SP 对 seq_len 的约束。
EP：通常 num_experts % ep == 0；ETP 时隐藏维、专家维需可切。

2.4 互斥与负例（须在文档与测试中显式标出）

约束	来源/说明
`ep>1` ⇒ `etp ∈ {1, tp}`	TorchTitan `ParallelDims._validate`
DeepEP/HybridEP × ETP>1	Titan 部分模型未实现；负例用例可期望报错
仅 Dense 桩	不开 `ep`；避免「无专家却建 sparse_mesh」的歧义
双栈 FSDP	`docs/design_moe_fsdp_dual_stack.md`：专家/稠密不同 `fully_shard` mesh

3. 组合不是全排列：分层覆盖策略

用 3 个层级 覆盖「完备性」，避免维爆炸。

3.1 层级 A：单维冒烟（`world_size` 最小为维本身）

ID	激活维	典型 NPROC	验证点
A-TP	仅 `tp=2/4`	2/4	Col/Row/all-gather 与参考一致
A-CP	仅 `cp=2/4`	2/4	attention/CP 核与全量序列一致
A-FSDP2	仅 `dp_shard=2` 或 HSDP 最小	2	`fully_shard` 参数分片+梯度无 NaN
A-EP	仅 `ep=2/4`（MoE 桩）	2/4	dispatch 后 expert 前向+反向

不交叉，但保证 每维在 hyper API 上有一条绿灯路径。

3.2 层级 B：双维/三维「工业常见」组合

参考 Titan 编排顺序（dense，示意）：TP(±SP) → CP(注意力) → AC/compile(可选) → FSDP2；MoE 在 Titan 中多为 非 MoE 部分 TP 后再 apply_moe_ep_tp → CP → FSDP2（见 llama4/parallelize.py）。

ID	组合	参考样例/仓库
B-1	TP + FSDP2	`examples/.../fsdp_tp_example.py`、Titan Llama3
B-2	TP + SP + FSDP2	同上 + `enable_sequence_parallel` 思想；PyTorch `sequence_parallel_example`
B-3	CP + FSDP2	Titan：`fsdp` 已含 `cp`；`cp>1, dp_shard=1` 也要 FSDP 的路径
B-4	TP + CP + FSDP2	Titan 整除 `seq_len`；`apply_tp` 带 `enable_cp`
B-5	HSDP：`dp_replicate + fsdp`	Titan `get_mesh(["dp_replicate","fsdp"])`
B-6	EP + FSDP2（无 TP）	Titan `ep>0` 触发专家侧 FSDP；`design_moe_fsdp_dual_stack`
B-7	EP + TP + (ETP) + FSDP2	ETP=TP 与 ETP=1 各一；Titan `expert_tensor_parallel`

3.3 层级 C：四维+「Titan 全量小型网格」

在 单节点多卡 上选 1～2 组 满足 ParallelDims 的 小配置（例如 8 卡：(dp_replicate,dp_shard,cp,tp) = (1,2,2,2) 等），MoE 另加 ep,etp 的合法对。

目的：集成 mesh 自洽 + 与 B 类相比无新逻辑分叉则可在 CI 降权为夜间。

4. 与参考仓库的一一映射

4.1 PyTorch `examples/distributed/tensor_parallelism`

脚本	覆盖层级	Hyper `examples` 建议对应
`tensor_parallel_example.py`	A-TP、最小 MLP	`torch/mlp_tensor_parallel.py` 或等价
`sequence_parallel_example.py`	TP+SP	带 `SequenceParallel` 的块
`fsdp_tp_example.py`	B-1、B-2	Mini Transformer + `fully_shard` + `tp` mesh

构建要点：torchrun --nproc_per_node=K 的 K 等于 张量/数据等并行度的乘积；与下节矩阵一致。

4.2 TorchTitan

维与 mesh：torchtitan/distributed/parallel_dims.py 为 黄金参考；examples 的 rank 数 必须满足 build_mesh 不 assert。
编排顺序：torchtitan/torchtitan/models/*/parallelize.py 中 parallelize_* 的 call 序 应被 hyper 的「集成示例」复现（可缩小模型）。
MoE：apply_fsdp 的 edp_mesh、ep_degree；design_moe_fsdp_dual_stack.md。

4.3 VeOmni

parallel_state：veomni/distributed/parallel_state.py — init_parallel_state 的 dp_shard/ulysses/cp/tp 与 extra_parallel_*（EP）。
FSDP2：veomni/distributed/torch_parallelize.py；约束见 .agents/knowledge/constraints.md FSDP/EP 条目。
测试（可选抄结构）：VeOmni/tests/tools/training_utils.py 的 build_torchrun_cmd + ParallelConfig(fsdp_mode, ulysses_size, ep_size) 作为 CLI/固定参数 的模板。

映射提示：

VeOmni ulysses 常承担「序长度方向并行」，与 Titan 的 TP+SP 或 CP 的边界可能不同；hyper 若未实现 ulysses，在矩阵中 B 类不提供「HYPER×Ulysses」 用例，或放 veomni-only 对照 子目录，避免误导。

5. 主矩阵：并行配方与用例建法

下表为首版建议覆盖的有编号配方；列 「最小模型」 指验证目标而非生产模型。

配方ID	稠密/稀疏	TP	SP	CP	FSDP2	dp_rep	EP	ETP	约束摘要	最小模型	参考
M1	稠密	1	0	1	1	0	0	0	纯 DDP/仅本地	2-layer MLP / 1 block	基线
M2	稠密	>1	0	1	1	0	0	0	纯 TP	同	`tensor_parallel_example`
M3	稠密	>1	1	1	1	0	0	0	TP+SP，整除	Mini LM block	`sequence_parallel_example`
M4	稠密	1	0	1	>0	0	0	0	仅 FSDP2 / dp_shard	同	任意 FSDP2 教程
M5	稠密	1	0	>1	>0	0	0	0	`cp` 进 `fsdp` 维；`seq_len%`	带 CP attention 桩	`apply_cp`
M6	稠密	>1	1	>1	>0	0	0	0	整除 `tp×2×cp`	Mini LM	Titan `llama3`
M7	稠密	>1	0..1	1..>1	>0	1	0	0	HSDP	同	`dp_replicate`+`fsdp`
S1	稀疏	≥1	*	1..>1	>0	0..1	>1	1	仅 EP，etp=1；双栈 FSDP	Mini MoE 块	`ExpertParallel`
S2	稀疏	>1	*	1..>1	>0	0..1	>1	tp	ETP=TP；dispatch 在 ep	同上 + ETP	`design_expert_tensor_parallel`
S3	稀疏	任意	*	1..>1	>0	0..1	>1	1	与 S1 同维不同实现路径	对照 S1 数值	回归用

说明：

M1–M7 不需要真实 MoE 权重，可用 小 Transformer 或 MLP 即可。
S1–S3 需要 GroupedExperts 或等价 + 可跑通的 router（可 top-1 固定）。
N× 首版不强制：PP>1、DeepEP、ETP+DeepEP、Float8+TP 等，放入 扩展矩阵（附录）或单独 issue。

6. 建议的 `hyper-parallel/examples` 目录结构

examples/
├── README.md                      # 入口；指向本文档；环境与 torchrun 基线
├── design_examples_parallel_completeness.md  # 可选：软链或「见 docs/…」
├── torch/
│   ├── README.md
│   ├── 01_mlp_tensor_parallel/        # 对应 A-TP / M2
│   ├── 02_mlp_seq_parallel/           # 对应 M3（如实现）
│   ├── 03_mini_transformer_fsdp_tp/  # 对应 M4–M6、B-1/2/4
│   ├── 04_transformer_fsdp_cp/        # 对应 M5
│   ├── 05_moe_ep_fsdp/                # 对应 S1 + design_moe_fsdp_dual_stack
│   ├── 06_moe_ep_tp_etp/              # 对应 S2
│   ├── run_*.sh                       # 每目录统一 torchrun 封装
│   └── _common/                        # 共享：mesh 工厂、小模型、loss 基线
└── mindspore/                        # 已有 fully_shard 线可**增量**与 torch 同矩阵对齐（平台允许时）

_common/ 应提供：
- 与 ParallelDims 或 hyper 等价的 build_world_mesh(...)；
- make_mini_transformer(n_layer, moe=bool)；
- run_forward_backward_step + 单卡/广播参考 或 loss 对比。
每个 0x_* 目录 自洽：requirements.txt、一条默认 run.sh、表格一行 说明覆盖 配方ID。

7. 单个用例的构建步骤（模板）

定配方：在 §5 选对 M/S ID，写出 整数表 dp_replicate, dp_shard, cp, tp, ep, etp, pp(=1) 与 WORLD_SIZE=N。
证等式：N = dp_replicate * dp_shard * cp * tp * pp；若含稀疏 mesh，用 Titan 或 design_moe_fsdp_dual_stack 中的 efsdp 公式 检查 不 assert。
定 seq_len 与 batch：满足 §2.3 整除 与 dataloader 可 shard。
写模型桩：
- 稠密：偶数层 + 可开关 Moe 层；
- MoE：num_experts 可被 ep 整除；ETP 时与 etp 与 权重 layout 一致。
应用 parallelize（与 Titan 顺序一致，见 §3.2）：TP →(MoE EP/ETP) → CP → FSDP2。若 hyper API 名不同，在 README 逐步列调用序列。
主进程断言：loss 为有限值；backward 后 关键参数 grad 非空且范数在 [ref*0.5, ref*2]（示例阈值）或与单卡 all_gather 后 loss 一致（推荐后者 做强校验）。
提供 torchrun：nproc = N；MASTER_PORT 与 CI 随机端口（可抄 VeOmni find_free_port 模式）。

8. CI 分级

级别	内容	频率 / 卡数建议
L0	M1、M2、M4（最小步数、无 MoE）	每 PR；2～4 卡
L1	M3、M5、M6、B-5/7 各一	每日；4～8 卡
L2	S1、S2 及一条 C 级 8 卡 Titan 小网格	每周 / 夜间

MoE/EP 在资源不足时可 单测 mock all_to_all + 仅 L2 上真机；但 完备性声明 应以 L2 至少 S1+S2 真跑通 为门槛。

9. 验收（examples 子项目）

README 中表格 M1–M7 与 S1–S2 均有路径链接 或明确写 「未实现」 与跟踪 issue。
每个已实现 配方：存在 run.sh + 文档 中 NPROC 计算 说明。
与 ParallelDims（或替代实现）无 assert 在正确参数下触发的已知 bug。
负例（非法 etp、DeepEP×ETP 等）可在 examples/torch/negative_tests/ 中期望非零退出。

10. 附录 A：与 VeOmni 的维名快速对照

概念	TorchTitan	VeOmni（`parallel_state`）
数据分片 FSDP 维	`fsdp`（含 cp）	`dp_shard` + 与 ulysses/cp 的 flatten（`dp_shard_sp` 等）
长序列并行	`cp` + 可选 ulysses（无）	`cp`、`ulysses` 分列
专家+专家侧 FSDP	`ep` + `efsdp` + `edp`	`extra_parallel` 的 `ep` × `ep_fsdp`
HSDP 复制维	`dp_replicate`	`dp_replicate`

Hyper 文档在引用 VeOmni 时应在具体脚本顶部 4 行以内 写清对照，避免跨团队误读。

11. 附录 B：首版不纳入矩阵的扩展项（可后续加行）

PP>1、Async TP、Float8 tensorwise TP
DeepEP / HybridEP 与 FSDP/ETP 的兼容矩阵（见 Titan 报错）
Ulysses-only 与 CP 的二维 SP（VeOmni 特化）
多机 torchrun 仅作文档，不作为「完备性」必跑

12. 参考文献与路径

examples/distributed/tensor_parallelism/README.md（本仓库上游 frame/examples 若同构）
torchtitan/torchtitan/distributed/parallel_dims.py
torchtitan/torchtitan/models/llama3/parallelize.py、llama4/parallelize.py
VeOmni/veomni/distributed/parallel_state.py、.agents/knowledge/constraints.md
hyper-parallel/docs/design_moe_fsdp_dual_stack.md、docs/design_expert_tensor_parallel.md

版本	说明
0.1	初版：组合分层、M/S 矩阵、目录与用例构建模板、CI 与验收

schema_version: 1
source: gitcode
gitcode_repo: mindspore/hyper-parallel
gitcode_issue: 111
source_url: https://gitcode.com/mindspore/hyper-parallel/issues/111

Description

HyperParallel：`examples` 目录 — 多并行维完备性验证设计

1. 目标与非目标

1.1 目标

1.2 非目标

2. 并行维符号与有效域

2.1 本设计采用的维（与 TorchTitan 对齐主符号）

2.2 World size 等式（稠密，无 EP 在「度」上挤占时）

2.3 序列与形状整除

2.4 互斥与负例（须在文档与测试中显式标出）

3. 组合不是全排列：分层覆盖策略

3.1 层级 A：单维冒烟（`world_size` 最小为维本身）

3.2 层级 B：双维/三维「工业常见」组合

3.3 层级 C：四维+「Titan 全量小型网格」

4. 与参考仓库的一一映射

4.1 PyTorch `examples/distributed/tensor_parallelism`

4.2 TorchTitan

4.3 VeOmni

5. 主矩阵：并行配方与用例建法

6. 建议的 `hyper-parallel/examples` 目录结构

7. 单个用例的构建步骤（模板）

8. CI 分级

9. 验收（examples 子项目）

10. 附录 A：与 VeOmni 的维名快速对照

11. 附录 B：首版不纳入矩阵的扩展项（可后续加行）

12. 参考文献与路径

Contributor guide

First steps

Research direction

Assessment

多维并行能力组合验证

Description

HyperParallel：examples 目录 — 多并行维完备性验证设计

1. 目标与非目标

1.1 目标

1.2 非目标

2. 并行维符号与有效域

2.1 本设计采用的维（与 TorchTitan 对齐主符号）

2.2 World size 等式（稠密，无 EP 在「度」上挤占时）

2.3 序列与形状整除

2.4 互斥与负例（须在文档与测试中显式标出）

3. 组合不是全排列：分层覆盖策略

3.1 层级 A：单维冒烟（world_size 最小为维本身）

3.2 层级 B：双维/三维「工业常见」组合

3.3 层级 C：四维+「Titan 全量小型网格」

4. 与参考仓库的一一映射

4.1 PyTorch examples/distributed/tensor_parallelism

4.2 TorchTitan

4.3 VeOmni

5. 主矩阵：并行配方与用例建法

6. 建议的 hyper-parallel/examples 目录结构

7. 单个用例的构建步骤（模板）

8. CI 分级

9. 验收（examples 子项目）

10. 附录 A：与 VeOmni 的维名快速对照

11. 附录 B：首版不纳入矩阵的扩展项（可后续加行）

12. 参考文献与路径

Contributor guide

First steps

Research direction

Assessment

Get new issues in your inbox

HyperParallel：`examples` 目录 — 多并行维完备性验证设计

3.1 层级 A：单维冒烟（`world_size` 最小为维本身）

4.1 PyTorch `examples/distributed/tensor_parallelism`

6. 建议的 `hyper-parallel/examples` 目录结构