LLaVA-OneVision-2: Skill for OpenCode

Purpose / 用途

Use this skill when diagnosing, designing, or converting Megatron/Megatron-Core checkpoints that may use TP, PP, and EP.

在排查、设计或转换使用 TP、PP、EP 的 Megatron / Megatron-Core checkpoint 时，使用这个 skill。

Core rule / 核心规则

• TP only: mp_rank_{tp}

• TP + PP: mp_rank_{tp}_{pp}

• TP + PP + EP: mp_rank_{tp}_{pp}_{ep}

• 只有 TP：mp_rank_{tp}

• TP + PP：mp_rank_{tp}_{pp}

• TP + PP + EP：mp_rank_{tp}_{pp}_{ep}

The key discriminator is whether expert parallelism participates in checkpoint sharding.

真正的分界点是：expert parallelism 是否参与了 checkpoint 切分。

• If EP is present, treat the checkpoint layout as 3D.

• If EP is absent, treat the checkpoint layout as non-EP and use 1D or 2D.

• 如果存在 EP，就按 3D 布局处理。

• 如果不存在 EP，就按非 EP 布局处理，即 1D 或 2D。

Mental model / 心智模型

Megatron does not treat pp > 1 as meaning 3D by itself.

Megatron 不会因为 pp > 1 就自动把 checkpoint 视为 3D。

• PP adds a pipeline index.

• EP adds an expert index.

• The third coordinate exists because EP exists, not because PP exists.

• PP 只是在目录里增加 pipeline 这一维。

• EP 才会增加 expert 这一维。

• 第三维存在的原因是 EP 存在，而不是因为 PP 存在。

So even if tp=1 and pp=1, once EP is enabled the checkpoint naming is still conceptually 3D because ranks are addressed by (tp, pp, ep).

所以即使 tp=1 且 pp=1，只要启用了 EP，checkpoint 在语义上仍然是 3D，因为 rank 仍然由 (tp, pp, ep) 共同定位。

Practical interpretation / 实际使用解释

When reading or converting checkpoints:

在读取或转换 checkpoint 时：

1. First decide whether EP exists in the checkpoint contract.

2. If EP exists, require mp_rank_{tp}_{pp}_{ep}.

3. If EP does not exist, read as mp_rank_{tp} or mp_rank_{tp}_{pp}.

4. Do not infer 3D solely from pipeline_model_parallel_size > 1.

5. 先判断这个 checkpoint 契约里是否存在 EP。

6. 如果存在 EP，就要求目录是 mp_rank_{tp}_{pp}_{ep}。

7. 如果不存在 EP，就按 mp_rank_{tp} 或 mp_rank_{tp}_{pp} 去读。

8. 不要仅凭 pipeline_model_parallel_size > 1 就推断它一定是 3D。

Typical failure pattern / 典型错误模式

Bad assumption:

错误假设：

• pp > 1 so loader chooses a 3D reader.

• 只要 pp > 1，loader 就应该走 3D reader。