已开启

多维并行能力组合验证 #111

changzherui创建于 4月27日

4月27日创建

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 与验收