Skip to content

[distributed] Context parallelism with tensor parallelism - #50511

Draft
3outeille wants to merge 2 commits into
cp-3-cp-sizefrom
cp-6-tp-x-cp
Draft

3outeille wants to merge 2 commits into
cp-3-cp-sizefrom
cp-6-tp-x-cp

Conversation

@3outeille

@3outeille 3outeille commented Nov 9, 2026 •

Copy link
Copy Markdown
Member

🤗 Transformers CI

What does this PR do?

Stack: #50493 → #50496 → this PR → #50514 → #50515 → #50499 → #50521 → #50522

Context parallelism now composes with tensor parallelism: DistributedConfig(tp_size=T, cp_size=C), with or without fsdp_size.

  • Under TP each rank holds num_heads / tp_size heads, and Ulysses splits those across the cp ranks. So tp_size * cp_size must divide the attention and key/value heads.
  • The ranks of a tp group hold the same batch and the same cp slice. The data parallel rank is rank // (cp_size * tp_size).
  • The mesh needs no change: [distributed] DistributedConfig(cp_size=N) #50496 already builds fsdp_cp on the root mesh, which FSDP2 composes with tp.
  • pp_size and ep_size with cp_size are still refused.

Tests

tests/context_parallel, CPU (gloo). Loss, logits slice and every gradient match an unsharded run:

setup ranks
tp=2 × cp=2, unpacked and packed 4

Also: the head check with tp_size * cp_size, and gathered save_pretrained with tp × cp. The existing TP, FSDP and EP tests of llama and qwen3_moe pass, and so does tests/tensor_parallel.

@HuggingFaceDocBuilderDev

HuggingFaceDocBuilderDev commented Nov 9, 2026 •

Copy link
Copy Markdown

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

@3outeille
3outeille changed the base branch from cp-5-docs to cp-4-tester-mixin November 9, 2026 14:24
@3outeille
3outeille added this pull request to stack #50517 November 9, 2026 14:29
@3outeille
3outeille removed this pull request from stack #50517 November 9, 2026 14:30
@3outeille
3outeille added this pull request to stack #50518 November 9, 2026 14:30
@3outeille
3outeille removed this pull request from stack #50518 November 9, 2026 14:36
@3outeille
3outeille changed the base branch from cp-4-tester-mixin to cp-3-cp-size November 9, 2026 14:36
@3outeille
3outeille added this pull request to stack #50520 November 9, 2026 14:37
@3outeille
3outeille removed this pull request from stack #50520 November 10, 2026 02:50
@3outeille
3outeille added this pull request to stack #50546 November 10, 2026 02:51
`fsdp_cp` is now an axis of a dense root mesh `(pp, dp_replicate, fsdp_cp, tp)`, and the
five dense axes are an unflattened view of it: FSDP2 composes the mesh it shards over with the
mesh the parameters are already sharded on, and torch only composes meshes built from the same
root. Requires `torch>=2.10` (`DeviceMesh._unflatten`), refused in `DistributedConfig`.

Under TP this rank holds `num_heads / tp_size` heads and Ulysses splits those across the cp
group, so `cp_size * tp_size` must divide the attention and key/value heads.
`tp_size=2 x cp_size=2` on four ranks, plain and packed, against the same weights on the full
sequences, plus the gathered save, the head divisibility check under TP, and a test that the two
plans compose: the attention module whose call CP routes is the one whose projections TP sharded.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants