[Feature] Add --attn-dp-size and deprecate --enable-dp-attention

[ch-wan]

Motivation

--dp-size means two different things. With --enable-dp-attention it counts attention data-parallel groups inside the TP group; without it, it counts model replicas. Every reader has to look at both flags to know which meaning it has. This PR gives each meaning its own argument, and the runtime reads the meaning it needs.

Modifications

Arguments.

• --attn-dp-size N (alias --attention-data-parallel-size, default 1) runs N attention data-parallel groups inside the TP group, one scheduler each, while the FFN stays tensor / expert parallel.
• --dp-size counts replicas only. Replicas combined with attention DP (--dp-size > 1 with --attn-dp-size > 1) were never supported and are now rejected at resolution.
• --enable-dp-attention is registered with DeprecatedStoreTrueAction: it warns and names --attn-dp-size as the replacement. Resolution turns --dp-size N --enable-dp-attention into --attn-dp-size N --dp-size 1 before any handler reads the layout. With --dp-size 1 the old spelling still means attention DP off. Passing it together with --attn-dp-size is rejected.
• Handlers that turned attention DP on declare the width directly: DWDP, the DeepSeek DSA / MLA context-parallel overrides, and DeepSeek-V4. The three DeepSeek CP handlers still run --dp-size N as attention DP N, as before, and reject replicas combined with --attn-dp-size.

Runtime. Outside argument handling nothing reads enable_dp_attention. The published parallel config gains two derived fields:

• attn_dp_enabled: attn_dp_size > 1, or an elastic EP scale joiner. A joiner's own group can be one rank wide, but it joins an attention-DP deployment and runs its DP-attention paths.
• num_dp_ranks: dp_size * attn_dp_size, the number of DP ranks (schedulers). It equals the old dp_size under either meaning.

Readers migrate by meaning:

• The old dp_size → num_dp_ranks (DP controllers, MLP sync, CUDA graph buffers, load snapshots, prefill delayer, startup weight load, and so on).
• The old enable_dp_attention → attn_dp_enabled.
• Replica-only readers read dp_size: tokenizer control, the PD bootstrap world size, compute_world_size.

Other runtime changes:

• Elastic EP scale-up stamps the grown num_dp_ranks; attn_dp_size keeps the local layout.
• Wire formats keep their dp_size keys, which still carry the DP rank count: KV-event descriptors, PD prefill server info, and load snapshots.
• The weight-cache fingerprint records attn_dp_size instead of the flag.
• /server_info reports attn_dp_size. The model gateway counts DP ranks as dp_size * attn_dp_size, and falls back to dp_size for a server that does not report it.

Docs, scripts, tests.

• Every launch command, cookbook config and playground snippet uses --attn-dp-size N.
• Commands that passed --dp 1 --enable-dp-attention ran without attention DP; they drop the flag. The DeepSeek-OCR, DeepSeek-OCR-2 and GLM-4.7-Flash generators drop the DP option that only emitted it, and the Kimi-K3 950PR/DT recipe picks DP-Attention off.
• The server-arguments table marks --enable-dp-attention deprecated.
• The DP / DPA guide explains the two arguments, that an elastic EP scale joiner runs attention DP at width one, and that wire formats keep the dp_size key for the DP rank count.
• Tests and fixtures declare attn_dp_size.

Tests. The new test_attn_dp_size.py covers:

• the deprecated spelling resolving exactly like --attn-dp-size;
• width one without attention DP;
• the rejected layouts;
• both CLI spellings, and the deprecation warning;
• the published attn_dp_size / num_dp_ranks / attn_dp_enabled, including a scale joiner and overrides.

Gateway unit tests cover the DP rank count.

Accuracy Tests

H200, this PR vs its base. GSM8K uses 300 questions; greedy text is 4 prompts × 48 tokens. The DeepSeek-V2-Lite (base model) row is the mean of 6 interleaved runs per side:

model	launch (this PR / base)	GSM8K this PR / base	server_info this PR
DeepSeek-V2-Lite	--tp 4 --attn-dp-size 4 --ep-size 4 / --tp 4 --dp 4 --enable-dp-attention --ep-size 4	0.386 / 0.386	dp_size=1, attn_dp_size=4
Qwen3-8B + EAGLE3	--tp 2 --attn-dp-size 2 / --tp 2 --dp 2 --enable-dp-attention	0.950 / 0.950	dp_size=1, attn_dp_size=2
Qwen3-8B	--tp 2 --dp 2 (replicas) on both	0.950 / 0.953	dp_size=2, attn_dp_size=1

• On this PR, --tp 4 --dp 4 --enable-dp-attention resolves to the same layout as --attn-dp-size 4, produces identical greedy text, and prints one deprecation warning. The new spelling prints none.
• Greedy text is identical to the base for Qwen3-8B, in both the EAGLE3 and the replica runs. With DeepSeek-V2-Lite, attention DP and EP, greedy text is not deterministic on the base itself (two variants across six runs), and this PR's runs produce the same variants.

Speed Tests and Profiling

DeepSeek-V2-Lite, --tp 4 --attn-dp-size 4 --ep-size 4 vs the old spelling on the base, 6 interleaved runs each, GSM8K output throughput: base 6069 tok/s (range 5626–6367), this PR 5883 tok/s (range 5676–6456). The difference is within the run-to-run spread; attn_dp_enabled and num_dp_ranks are computed once at publication, not per read.

Checklist

• Format your code according to the Format code with pre-commit.
• Add unit tests according to the Run and add unit tests.
• Update documentation according to Write documentations.
• Provide accuracy and speed benchmark results according to Test the accuracy and Benchmark the speed.
• Follow the SGLang code style guidance.

Review and Merge Process

1. Ping Merge Oncalls to start the process. See the PR Merge Process.
2. Get approvals from CODEOWNERS and other reviewers.
3. Trigger CI tests with comments or contact authorized users to do so.
   • Common commands include /tag-and-rerun-ci, /tag-run-ci-label, /rerun-failed-ci
4. After green CI and required approvals, ask Merge Oncalls or people with Write permission to merge the PR.

---

CI States

Latest PR Test (Base): 🚫 Run #36773503469
Latest PR Test (Extra): ⚠️ Not run on latest push -- push again to dispatch.
Latest PR Test (AMD ROCm 10): 🚫 Run #36773503843

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
sglang-doc	🟢 Ready	View Preview	Sep 30, 2026, 8:33 PM

💡 Tip: Enable Automations to automatically generate PRs for you.