执行摘要

• 一句话：修正 initialize_model_parallel 并行组布局 docstring
• 推荐动作：不值得精读，但可作为 API 文档纠错的快速参考。值得关注的设计决策是：作者通过补充 attn_tp_size = tp_size // attn_cp_size // attn_dp_size 推导公式，让文档结论可以被计算验证，而不仅仅是改一行描述；这种用公式支撑示例的写法可以推广到其他并行布局说明中。

功能与动机

PR body 明确指出原文档的错误：'The docstring previously mislabeled the latter as tensor model-parallel groups and omitted the real one.' 即在 attn_cp_size=2、attn_tp_size=4 的 8 卡示例中，docstring 把两个 attention tensor-parallel 组误标为 tensor model-parallel 组，同时遗漏了真正覆盖全部 8 卡的 TP 组，会误导用户对 TP 与 attention-TP 组布局的理解。

实现拆解

1. 定位文档错误：在 python/sglang/srt/distributed/parallel_state.py 的 initialize_model_parallel docstring 中，针对 attn_cp_size=2 与 attn_tp_size=4 的 8 卡示例，原文档将 [g0, g1, g2, g3] 与 [g4, g5, g6, g7] 标注为 2 个 tensor model-parallel 组，但这两个组实际是 attention tensor-parallel 组；真正由 Tensor 并行产生的组应覆盖全部 8 卡。该错误会误导用户理解 TP 与 attention-TP 的组合关系。
2. 修正组列表并补充推导：文档改为列出 1 个覆盖 [g0, g1, g2, g3, g4, g5, g6, g7] 的 tensor model-parallel 组，并新增 2 个 attention tensor-parallel 组 [g0, g1, g2, g3]、[g4, g5, g6, g7]；同时补充公式 attn_tp_size = tp_size // attn_cp_size // attn_dp_size，说明该示例隐含 tensor_model_parallel_size=8，为单 TP 组结论提供计算依据。其余 attention context-parallel、MoE expert-parallel、MoE data-parallel 组保持不变。
3. 配套与合入：无测试、配置或部署配套改动，纯 docstring 变更；分支经过两次 merge main 同步（作者 QNan0513、维护者 BBuf 各一次），最终由 BBuf APPROVED 合入。作者在 issue 评论区两次请求添加 run-ci 标签并路由 reviewer，PR 检查在 gate 阶段曾有失败记录，材料未说明失败原因，且未阻塞合入。

关键文件：

• python/sglang/srt/distributed/parallel_state.py（模块 并行状态；类别 source；类型 documentation；符号 initialize_model_parallel）: 唯一变更文件，修正 initialize_model_parallel 的 docstring 中 TP 与 attention-TP 组布局描述，无运行时逻辑变化

关键符号：initialize_model_parallel

关键源码片段

python/sglang/srt/distributed/parallel_state.py

唯一变更文件，修正 initialize_model_parallel 的 docstring 中 TP 与 attention-TP 组布局描述，无运行时逻辑变化

# initialize_model_parallel 的 docstring（摘录，已按本次修正更新）
# 原文档把 [g0..g3] 与 [g4..g7] 误标为 tensor model-parallel groups，
# 并遗漏了真正覆盖全部 8 卡的 TP 组；修正后补上了推导关系与正确组名。
​
    Let's say we use 2 GPUs for attention context parallelism (attn_cp_size=2) and 4 GPUs for
    attention tensor parallelism (attn_tp_size=4). As for MoE part, we use 2 GPUs for moe data
    parallelism (moe_dp_size=2) and 4 GPUs for moe expert parallelism (moe_ep_size=4). Note that
    this implies tensor_model_parallel_size=8 (attn_tp_size = tp_size // attn_cp_size //
    attn_dp_size), so all 8 GPUs form a single tensor model-parallel group. The present
    function will create the following groups:
        1 tensor model-parallel group: # 全部 8 卡构成唯一 TP 组（本次修正补上）
            [g0, g1, g2, g3, g4, g5, g6, g7]
        4 attention context-parallel groups: # 注意力上下文并行组，按卡号步长 4 划分
            [g0, g4], [g1, g5], [g2, g6], [g3, g7]
        2 attention tensor-parallel groups: # 注意力张量并行组（原文档误标为 TP 组）
            [g0, g1, g2, g3], [g4, g5, g6, g7]
        2 moe expert-parallel groups: # MoE Expert 并行组，与 attention-TP 范围一致
            [g0, g1, g2, g3], [g4, g5, g6, g7]
        4 moe data-parallel groups: # MoE 数据并行组，按卡号步长 4 划分
            [g0, g4], [g1, g5], [g2, g6], [g3, g7]

评论区精华

本 PR 无 review 评论，讨论集中在 issue 评论区。作者 QNan0513 两次留言请求维护者添加 run-ci 标签并路由 reviewer，强调这是 docstring-only 变更、无运行时行为变化，并说明 PR 检查在 gate 阶段失败。维护者 BBuf 最终 APPROVED 并合入，期间通过 merge main 保持分支与主干同步。结论：文档准确性修正获认可，CI gate 失败的具体原因在材料中未给出最终解释。

• docstring-only PR 的 CI 触发与评审路由 (question): 维护者 BBuf 最终 APPROVED 并合入，期间通过 merge main 同步主干；CI gate 失败的具体原因未在材料中说明，未阻塞合入。

风险与影响

• 风险：运行时回归风险：无，仅修改 docstring 文本，initialize_model_parallel 的 world_size 校验、进程组创建等逻辑完全未动。文档一致性风险：并行组布局推导（attn_tp_size = tp_size // attn_cp_size // attn_dp_size）未来若调整，该示例需同步更新，否则会再次产生文档与实现脱节。CI 不确定性：PR 检查在 gate 阶段有失败记录（Run #32125827994 与 Run #32125827718），失败原因未在材料中说明；由于是纯文档变更且已合入，大概率与代码回归无关，但若仓库对 PR 检查有强制要求，需留意该失败对合入流程可追溯性的影响。
• 影响：用户与开发者影响：改善 initialize_model_parallel 文档准确性，帮助使用 attention context/tensor 并行组合的用户正确理解进程组划分；无任何行为影响。系统影响：无运行时、性能、内存或网络改动。团队影响：作为文档纠错样例，提示维护者关注 docstring 示例与并行组实现的一致性；变更极小，review 成本低。
• 风险标记：纯文档变更无运行时风险, CI gate 阶段失败待确认, docstring 需随并行规则演进同步维护

关联脉络

• PR #35061 [Fix] Select custom all-reduce v2 by topology capability: 同样修改了 python/sglang/srt/distributed/parallel_state.py，属于同一分布式并行状态模块的近期演进，与本次并行组布局文档校准确认相互印证。
• PR #34713 [diffusion] Decouple encoder parallelism from the DiT parallel layout: 在 diffusion 子系统中重构为双并行组布局，与本次澄清 TP / attention-TP / CP 组边界的主题相关，同属并行组布局设计范畴。