1. 文档与开关验收 这里的文档是指什么？在哪看？
2. enable_mc2开关需要怎么配置，只在examples/torch/llama3/parallelize.py示例脚本里找到这个开关，如果不跑示例，是否需要配置enable_mc2？

缺少接口参数说明和约束
缺少了竞品分析
缺少必要的样例说明

1. 文档与开关验收 这里的文档是指什么？在哪看？
2. enable_mc2开关需要怎么配置，只在examples/torch/llama3/parallelize.py示例脚本里找到这个开关，如果不跑示例，是否需要配置enable_mc2？

@nihui11

1. 没有文档，复制的模板标题，已修改。
2. 当前这个PR，提供的是MC2的能力，用户可以选择使用或者不使用。使用的话可以在构建网络切分时，自己调用相关的style方法。enable_mc2 只是举了一个demo，表示用户可以在端到端场景自己控制是否使用。(后续可以考虑在trainer相关能力完备后，在yaml侧暴露一个开关，当前不涉及)

1. 「文档与开关验收」里的「文档」指什么？在哪看？

这里的「文档」不是指某个已存在的独立文档页，而是指本特性对外可读的说明载体，验收范围包括：

结论：Issue 8.4 的「文档验收」目前主要靠 Issue/PR + 代码内注释满足；正式 API 文档尚未落地，这是已知 gap，会在后续文档 PR 中补齐。

2. enable_mc2 怎么配？不跑示例要不要配？

enable_mc2 不是框架级全局开关或环境变量，而是 Llama3 示例封装层 的参数：

parallelize_llama3(model, tp_mesh, enable_mc2=True)  # 默认 False

内部逻辑：仅在 enable_sequence_parallel=True 时生效，将 MLP 的 ColwiseParallel/RowwiseParallel 替换为 MC2ColwiseParallel/MC2RowwiseParallel；Attention 投影仍走非 MC2 路径。

不跑 Llama3 示例时，不需要也不存在 enable_mc2 这个参数。正确用法是在自定义 parallelize_module plan 中 直接选用 MC2 Style：

from hyper_parallel import MC2ColwiseParallel, MC2RowwiseParallel, parallelize_module
from hyper_parallel.core.dtensor.placement_types import Shard

plan = {
    "fc1": MC2ColwiseParallel(input_layouts=Shard(1), use_local_output=False),
    "fc2": MC2RowwiseParallel(
        input_layouts=Shard(-1),
        output_layouts=Shard(1),
        use_local_output=False,
    ),
}
parallelize_module(model, tp_mesh, plan)

参考样例：

• examples/torch/bench_mc2_vs_tp.py — MC2 vs 非 MC2 性能对比
• tests/torch/tensor_parallel/test_mc2_distributed.py — 分布式精度 ST

默认行为不变：不选用 MC2 Style 时，仍走原有 ColwiseParallel/RowwiseParallel。

3. 接口参数说明与约束（补充完整版）

承认 Issue 正文对接口参数的说明不够系统，以下为补充。正式版将写入 docs/api/api_reference.md。

3.1 公开 API

from hyper_parallel import MC2ColwiseParallel, MC2RowwiseParallel
from hyper_parallel.core.tensor_parallel.mc2 import MC2Linear

3.2 MC2ColwiseParallel

Column 并行 + 融合 AllGather+MatMul。继承 ColwiseParallel。

行为要点：

• 不做 input AG redistribute，desired_input_layouts = input_layouts（保持序列 sharding，融合核内部 AG）
• apply() 时将 nn.Linear 原地替换为 MC2Linear（mode=all_gather）
• 仅支持 nn.Linear（Embedding 等会 NotImplementedError）

3.3 MC2RowwiseParallel

Row 并行 + 融合 MatMul+ReduceScatter。继承 RowwiseParallel。

行为要点：

• apply() 时替换为 MC2Linear（mode=reduce_scatter）
• Row 路径要求 序列维长度能被 world_size 整除，否则 RuntimeError

3.4 MC2Linear.configure_mc2

通常由 Style apply() 自动调用，高级用户可直接配置：

前置条件：须先 MC2Linear.from_linear(nn.Linear) + Style apply()；未配置就 forward 会 RuntimeError；weight 须为 DTensor。

3.5 Kernel / 运行时约束

Shape 选型公式（MLP 链设计时参考，ST 注释）：

• Column 前向收缩维 = in_features
• Row 前向收缩维 = in_features / tp
• Column 反向（融合 MRS）收缩维 = out_features / tp
• 实践中：in_features ≥ 256 × world_size，Column 层的 out_features / tp ≥ 256

fail-closed 说明：Issue 8.3 要求 dtype/k/world_size 不满足时在入口明确失败；当前 layout 约束已在 Style 入口校验，dtype/k/world_size 暂依赖 kernel 运行时失败。后续会在 Style/Linear 入口补前置校验，与 8.3 对齐。

4. 竞品 / 替代方案分析（补充）

本期定位为 HyperParallel Torch 路径对齐 MindFormers MC2 能力补齐，非全框架替代。

5. 样例说明（补充）

本地复现：

export HYPER_PARALLEL_PLATFORM=torch
pytest tests/ut/core/tensor_parallel/test_mc2_style.py -q

export ASCEND_RT_VISIBLE_DEVICES=4,5
pytest tests/torch/tensor_parallel/test_mc2_distributed.py -v

1.examples/torch/bench_mc2_vs_tp.py库上没找到
2.非目标里的MoE / Attention 路径的 MC2 融合。是指MoE / Attention里不能apply() 将 nn.Linear 原地替换为 MC2Linear吗？如果apply了是会报错还是没效果？
3.与其他特性的交互？

补充一组 PyTorch / Ascend 本地性能对照（MC2 vs 非融合 ColwiseParallel / RowwiseParallel），用于说明什么场景有收益、什么场景可能劣化。本期 Issue 明确未覆盖正式多机 E2E 吞吐报告，以下为单机 910B3 上的定向 A/B，供评审参考。

测试环境

对照网络与 PR 一致：

• MLP 堆叠（examples/torch/bench_mc2_vs_tp.py）：fc1 Column + fc2 Row
• Llama3 SwiGLU FFN（parallelize.py）：w1/w3 Column + w2 Row；Attention 始终非融合
• Llama3 block：Attention 非融合 + MLP 可选 MC2（即 enable_mc2=True 的真实覆盖面）

示例 Llama3DemoConfig(dim=256) 不满足 Column 反向 n_local≥256（TP=2 时 FFN=256 → n_local=128），未纳入本表。

结果（正数 = MC2 更快）

本组 前向全部正向。训练（fwd+bwd）出现回退的是：短序列大 GEMM、以及 70B 档 SwiGLU。

小/中 shape 上 2.4–2.6x 主要来自少掉 DTensor 独立 AG/RS + nn.Linear 的调度，不完全是通算流水本身。

什么场景有收益

1. 纯 MLP / FFN 占比高
   PR 推荐的大 MLP 长序列（8192 / 28672 / seq=4096）前向约 +14%，训练约 +11%。
2. 通信与框架调度相对明显
   层数多、shape 未大到纯计算墙；或 TP 更大（同 7B 档 MLP：TP=2 训练约 +4%，TP=4 前向 +41%、训练 +22%）。
3. Llama3 在 enable_mc2 真实覆盖面下
   Attention 不走 MC2，但 FFN 仍占时间。7B 档 2 层 block、seq=1024 时整 block 训练约 +13%。
4. 只跑前向 / 推理
   本组前向均加速，包括训练会回退的两个 case。

什么场景没有收益（或会劣化）

1. 大 GEMM + 短序列的训练
   seq=128、FFN=28672：前向仍 +18%，fwd+bwd −6.8%。计算已很重、通信量相对小，融合反向（Column MRS 收缩维为很大的 n_local）不如分离 GEMM+通信。
2. 大 SwiGLU 的训练
   70B 档 FFN（3 个 Linear + SiLU）：前向 +6%，fwd+bwd −10.4%。比 2-linear MLP 多一次 Column 融合反向，SiLU 也不在 MC2 内。
3. Attention / MoE 占绝对大头的端到端
   本期不融 q/k/v/o 与 MoE。seq 更长、层数更多时 SDPA 会进一步稀释 MLP 收益；正式全模型吞吐仍未覆盖。
4. 约束不满足，不应启用（不是变慢，是跑不了或 fail-closed）
   • 无 Sequence Parallel
   • 示例级 dim=256（n_local<256）
   • dtype 非 fp16/bf16、world_size 不在 {2,4,8}、收缩维不在 [256, 65535)
   • 单卡 / 非 Ascend / MindSpore 后端

选用建议

优先开 MC2：Ascend + TP+SP + 合法 shape + MLP/FFN 为主；更长序列、更大 TP、前向/推理
建议 A/B：很短 seq + 很宽 FFN 的训练；70B 级 SwiGLU 训练
不要开：dim 过小、无 SP、dtype/world_size/k 不合法

结论：MC2 在 PR 的 MLP / Llama3 FFN 路径上 有可测收益，默认关闭是合理的。收益随拓扑变化：前向更稳；训练在短序列大 GEMM 和大 SwiGLU 上可能回退。正式 E2E 吞吐报告仍按 Issue 非目标留后续。

1.examples/torch/bench_mc2_vs_tp.py库上没找到
2.非目标里的MoE / Attention 路径的 MC2 融合。是指MoE / Attention里不能apply() 将 nn.Linear 原地替换为 MC2Linear吗？如果apply了是会报错还是没效果？
3.与其他特性的交互？

@nihui11

1. 例子看这个吧：tests/torch/tensor_parallel/_test_mc2_distributed.py
2. 必须是 nn.Linear，否则 apply()会报 NotImplementedError
3. mc2是TP的一种，和其他特性正交，没有影响