Deployment
Install SGLang
Install SGLang
For all methods and hardware platforms, see the official SGLang installation guide. The two paths below match the Python / Docker toggle in the command panel.Then run the Python output of the command panel below in that environment.
- Python (pip / uv)
- Docker
Command
- Low-Latency — fastest reply for a single user. Pick for chat.
- Balanced — good speed with several users at once. Use for typical multi-user serving.
- High-Throughput — most tokens per second across many users. Best for batch jobs.
For a runnable end-to-end example, see the DeepSeek-V4-Flash demo notebook.
Panel controls (top of the command box):
- Python / Docker — bare
sglang serve …for an existing SGLang env, or adocker run … sglang serve …wrap against the per-hardware image from the Install SGLang panel above. - ⧉ Copy — copies the current command (with whichever framing is active) to your clipboard.
- $ cURL — a sample request against
localhost:30000to confirm the server is up. - ⚙ Env — edits the placeholders (
HOST_IP,PORT,HF_TOKEN,NODE_RANK,NODE0_IP) the command and cURL share. Persists in localStorage across cookbooks. - Verified / Not Verified badge — green when the
(hw, variant, quant, strategy, nodes)combo has been run end-to-end on real hardware; yellow when auto-derived from a neighbor and not yet re-checked.
Playground
The Playground is where you experiment with SGLang features beyond the verified matrix. The Deploy panel above only emits combinations the SGLang team has signed off on; the Playground lets you turn on additional knobs on top of whichever cell the Deploy panel is currently showing. The base is read live from your Deploy selection — only your overrides change. The knobs come in two flavors:- Built-in SGLang features — parallelism overrides (TP / CP / DP-Attention — DP-Attention’s value is the DP degree, with
offto disable), MoE backend + EP, reasoning / tool-call parsers, speculative-decoding presets, prefill/decode disaggregation, HiCache tiers, and HiSparse hierarchical sparse attention (decode-role only — the card appears once PD-Disagg mode is set to decode). - DeepSeek-V4 specific features — MegaMoE W4A8 / W4A4 fused kernel (Blackwell only; Hopper SM90 uses a separate all-FP8 MegaMoE path — see Configuration Tips below).
Panel controls reuse Python / Docker · ⧉ Copy · $ cURL · ⚙ Env from the Deploy panel, plus one extra:
- Submit ↗ — opens a pre-filled GitHub issue so you can land your override combo as a new verified cookbook cell. Shown only while the badge says Not Verified; click it once you’ve actually run the command on your hardware and confirmed it works.
1. Model Introduction
DeepSeek-V4 is the next-generation Mixture-of-Experts model from DeepSeek, released 2026-04-24 under an MIT License. The 0731 Flash and 0813 Pro refreshes add checkpoints with a bundled DSpark draft head:| Variant | Total params | Active (MoE) | Use |
|---|---|---|---|
| DeepSeek-V4-Flash | 284B | 13B | single-node serving on B200 / B300 / GB200 / GB300 / H200 (TP=4); RTX PRO 6000 (TP=2); H100 (TP=8) |
| DeepSeek-V4-Flash-0731 | 304 | 13B | Flash Official (0731), with a bundled DSpark draft head; verified on 8×B200, 4×GB300, and 4×H200 |
| DeepSeek-V4-Pro | 1.6T | 49B | high-capacity: B200 / B300 (TP=8) · GB300 (TP=4) · H200 FP4 (TP=8) · GB200 (2-node, TP=8) · H200 FP8 (2-node, TP=16) · H100 (2-node, TP=16) |
| DeepSeek-V4-Pro-0813 | 1.65T | 49B | Pro Official (0813), with a bundled DSpark draft head; verified on 4×GB300 (TP=4) · B200 / B300 / H200 FP4 (TP=8) · GB200 (2-node, TP=8) · H100 (2-node, TP=16) · MI355X |
*-Base repos ship pure FP8 mixed and are for further pre-training only — not for chat or tool calling.
Highlights: hybrid CSA + HCA attention (~27% inference FLOPs / ~10% KV cache vs DSv3.2 at 1M context), manifold-constrained hyper-connections (mHC), Muon optimizer, 1M-token context (32T+ pre-training tokens), three reasoning modes (Non-think / Think High / Think Max — use ≥ 384K context for Think Max), and a dedicated encoding_dsv4.encode_messages Python encoder + DSML tool-call grammar.
Recommended generation: temperature=1.0, top_p=1.0.
Resources: HuggingFace · Flash Official (0731) · Flash · Pro · Pro Official (0813) · ModelScope · Flash · Pro.
2. Configuration Tips
Concurrency & DeepEP dispatch buffer Must hold:max-running-requests × MTP_draft_tokens ≤ SGLANG_DEEPEP_NUM_MAX_DISPATCH_TOKENS_PER_RANK. Violating it blows DeepEP’s dispatch buffer at steady-state load (deep_ep.cpp:1105). When tuning, move --cuda-graph-max-bs-decode, --max-running-requests, and the env together.
The generator currently picks values on the conservative side (mirroring an internal stress-test matrix). They run safely out of the box but likely leave throughput on the table — please tune them up toward your actual workload’s peak concurrency and report findings back so the defaults can be revised.
Speculative decoding
The original Flash and Pro recipes use EAGLE. Flash Official (0731) and Pro Official (0813) use the bundled DSpark draft head; see DSpark for its launch and tuning notes.
For the original Flash and Pro checkpoints:
low-latency: steps=3, draft-tokens=4 → largest win at bs=1.balanced: steps=1, draft-tokens=2 → gentler MTP, reduces throughput hit at higher batch.high-throughput: MTP disabled — at saturation the verify step costs more than it saves.- MTP runs on the v2 speculative path.
SGLANG_DSV4_COMPRESS_STATE_DTYPE controls the dtype of the C4 / C128 compressed attention state pools. Supported values are float32 / fp32 (default: float32) and bfloat16 / bf16. For BF16 on the offline compression path:
Command
c4_state and c128_state pool sizes. Keep the default float32 setting for the most conservative behavior.
EPLB + Waterfill (Experimental)
For recorded/static EPLB reproduction, first record an expert-distribution file by following
Capture expert selection distribution in MoE models.
For reproduction runs, use the generated expert_distribution_recorder_*.pt as
the initial expert location. Please checkout to latest main branch for this feature.
For non-PD reproduction, use:
Command
normal mode on the prefill server and
low_latency mode on the decode server. Add the same --init-expert-location
flag to both commands:
Command
--ep-num-redundant-experts and --eplb-algorithm to customize
EPLB placement.
Waterfill also supports MegaMOE. Use --moe-a2a-backend megamoe --enable-waterfill to keep the MegaMOE backend while applying Waterfill to the
fused shared expert slot.
FP4 Indexer (Experimental)
DeepSeek-V4 uses the default indexer path unless --enable-deepseek-v4-fp4-indexer is set. Enable this flag to use the experimental FP4 C4 indexer on SM100 GPUs with DeepGEMM FP4 indexer support. This path is intended for decode-heavy long-context workloads where reducing indexer cache bandwidth is beneficial.
Command
nvidia/DeepSeek-V4-Pro-NVFP4 and
nvidia/DeepSeek-V4-Flash-NVFP4 checkpoints
quantize MoE experts to NVFP4 while keeping attention and dense layers in
FP8. It requires --moe-runner-backend flashinfer_trtllm_routed which will be automatically selected if not provided.
Command
Command
Mxfp4FlashinferTrtllmMoEMethod path
automatically.
Hopper (H100 / H200) note
Two options are available for running DeepSeek-V4 on Hopper:
- Original FP4 checkpoints — apply the W4A16 MoE kernels (Marlin) as the command generator picks for Hopper cells. This path works on both H100 and H200 and is the only option for H100 (no FP8 path). It is TP-only; on H200 the Pro variant fits on a single 8-GPU node, while H100 Pro needs 2 nodes (TP=16).
- Converted FP8 checkpoints (H100 and H200 only) — pre-repackaged FP8 weights at
sgl-project/DeepSeek-V4-Flash-FP8andsgl-project/DeepSeek-V4-Pro-FP8unlock DP-attention + DeepEP and richer parallelism (e.g. Pro TP=16 across 2 nodes).
docker run --privileged --ulimit memlock=-1
(or --device /dev/infiniband:/dev/infiniband --cap-add IPC_LOCK) so mooncake
can discover the IB HCAs; without IB exposure mooncake silently falls back to
TCP, which can lead to garbled KV transfer on large checkpoints.
RTX PRO 6000 (SM120 / Blackwell Desktop) note
RTX PRO 6000 (96 GB) runs Flash only with the FlashInfer MXFP4 MoE runner.
V4-Pro doesn’t fit on 8× 96 GB; the Deploy panel greys out unsupported recipes.
HiCache and MegaMoE are not supported on RTX PRO 6000.
AMD (MI300X / MI355X) note
- Model checkpoints — for correct accuracy, the FP4 model uses the stock
deepseek-ai/DeepSeek-V4-{Flash,Pro}, and the FP8 model uses the repackagedsgl-project/DeepSeek-V4-{Flash,Pro}-FP8. - Supported models — MI300X supports DeepSeek-V4-Flash in FP8; MI355X supports DeepSeek-V4-Flash / Pro in both FP4 and FP8. All recipes run single-node.
- TP / DP setting — both TP=4 and TP=8 are supported. At low concurrency we recommend TP-only; at high concurrency use TP + DP, which additionally needs
--dp 8 --enable-dp-attention --enable-prefill-delayer --prefill-delayer-max-delay-ms 5000. - MTP — speculative decoding is supported; add
--speculative-algorithm EAGLE --speculative-num-steps 3 --speculative-eagle-topk 1 --speculative-num-draft-tokens 4. - Kernels — uses the Unified KV attention and the flydsl MoE.
--moe-a2a-backend deepep for
--moe-a2a-backend megamoe and add the relevant env vars automatically.
Two variants are exposed:
- W4A8 — default MegaMoE kernel (FP4 weights, FP8 activations).
- W4A4 — adds
SGLANG_OPT_DEEPGEMM_MEGA_MOE_USE_FP4_ACTS=1andSGLANG_OPT_DEEPGEMM_MEGA_MOE_USE_MXF4_KIND=1to run the custom W4A4 kernel (FP4 activations). Higher throughput with negligible accuracy drop (~89.5 GPQA on Pro).
- The W4A8 / W4A4 variants above are Blackwell-only (B200 / B300 / GB200 / GB300). On Hopper (SM90, H100 / H200) use the all-FP8 MegaMoE path described below instead.
- MegaMoE is only wired into the
high-throughputrecipe on Blackwell (per sgl-project/sglang#26451). The chip is hidden onlow-latencyandbalanced— switch tohigh-throughputto expose it. - When running MegaMoE, don’t set
--moe-runner-backendmanually. - Adjust
SGLANG_OPT_DEEPGEMM_MEGA_MOE_NUM_MAX_TOKENS_PER_RANKbased on your workload and memory usage. Setting higher number of tokens for MegaMoE requires more HBM space (recommended: 8320 for high-throughput).
mega_moe runner for higher long-context / large-decode throughput on
the FP8 checkpoints. Unlike the Blackwell W4A8 / W4A4 variants above, experts
stay in FP8 — keep SGLANG_DSV4_FP4_EXPERTS=0. It requires a sgl-deep-gemm
build with SM90 FP8 MegaMoE support. Please use the latest image for this
feature.
Enable the MegaMoE path with --moe-a2a-backend megamoe
Command
SGLANG_OPT_DEEPGEMM_MEGA_MOE_NUM_MAX_TOKENS_PER_RANK caps the number of tokens
the MegaMoE path processes per rank (i.e. per GPU); the MegaMoE path is only used
for batches at or below this cap. The right value depends on your parallelism /
token-split scheme, and larger values reserve more HBM.
GB300 PD-Disagg cross-pod MNNVL
On some GB300 clusters with cross-pod KV transfer over NVLink, mooncake may
fail with nvlink_transport.cpp:497 Requested address ... not found!. If
this happens, prepend MC_FORCE_MNNVL=1 NCCL_MNNVL_ENABLE=1 NCCL_CUMEM_ENABLE=1
to both prefill and decode sglang serve commands.
3. Advanced Usage
3.1 Reasoning
Enable thedeepseek-v4 reasoning parser (toggle Reasoning Parser in the Parsers card of the Playground above) to separate thinking from the final answer into reasoning_content vs content.
Streaming with Thinking Process (Python)
Streaming with Thinking Process (Python)
Example
Example Output
Example Output
Output
3.2 Tool Calling
Enable thedeepseekv4 tool-call parser (toggle Tool Call Parser in the Parsers card of the Playground above) to surface structured tool calls via message.tool_calls.
Python Example with Thinking Process
Python Example with Thinking Process
Example
Example Output
Example Output
Output
3.3 HiCache (Hierarchical KV Caching)
HiCache enables multi-tier KV cache offloading (GPU → CPU → Storage), significantly expanding effective context capacity for long-context and multi-turn scenarios. Combined with UnifiedRadixTree, it provides intelligent prefix caching across all tiers. To enable HiCache, open the HiCache card in the Playground above and flip Enable:- L2 (GPU + CPU) — leave Storage on
auto(default). Cold KV pages spill to CPU pinned memory only. - L3 (GPU + CPU + Storage) — pick a Storage backend (
file/mooncake/hf3fs/nixl); the Playground emits the canonicalpage_first_directmem-layout +directIO backend +wait_completeprefetch policy, matching the HiCache best-practices recipe.
- L2 (GPU + CPU) — leave Storage on
auto(default). Cold KV pages spill to CPU pinned memory only. UsedirectIO backend +page_first_directorlayer-firstmem-layout. - L3 (GPU + CPU + Storage) — pick a Storage backend (
file); the Playground emits the canonicalpage_first_directmem-layout +directIO backend +wait_completeprefetch policy, matching the HiCache best-practices recipe.
write_through (the upstream default); switch to write_back / write_through_selective to trade durability for write speed when the storage tier is slow.
For more details, see the HiCache documentation.
3.4 DSpark (Speculative Decoding)
Flash Official (0731) and Pro Official (0813) bundle a DSpark draft head indeepseek-ai/DeepSeek-V4-Flash-0731 and deepseek-ai/DeepSeek-V4-Pro-0813. The target and draft weights therefore come from the same checkpoint: enable DSpark with --speculative-algorithm DSPARK and do not set a separate --speculative-draft-model-path.
Unlike the EAGLE recipes for the original Flash and Pro checkpoints, this recipe omits --speculative-num-steps, --speculative-eagle-topk, and --speculative-num-draft-tokens. SGLang reads the DSpark shape from the checkpoint.
The Pro Official (0813) low-latency speed numbers in the Deploy panel were measured with
SGLANG_SIMULATE_ACC_LEN=4, which pins the DSpark accept length at exactly 4.00. The recipe as shipped earns 4.678 on the same engine, so those rows read slightly conservative. The GSM8K figure for that cell is from the shipped command.Command
--mem-fraction-static 0.90 on this topology to leave enough headroom for the batch-256 verify graph. The first cold start can take 10–15 minutes while FlashInfer autotunes and SGLang captures the draft and verify graphs; later starts reuse the cache. This path is verified end-to-end on 4×GB300 with SGLang v0.5.16.
Tune proposed draft tokens. --speculative-dspark-block-size N asks DSpark to propose N tokens per step; the target verifies a window of N + 1. If the flag is omitted, SGLang reads the value from the checkpoint. Both the 0731 and 0813 checkpoints resolve to five proposed tokens (the startup log reports gamma=5, verify_num_draft_tokens=6), which is the verified default. Use the DSpark Proposed Draft Tokens slider in the Playground to sweep one through five.
Larger blocks can improve decode latency when acceptance stays high, but they also increase verification work and graph memory. Start from the checkpoint default, then sweep downward under the real prompt-length and concurrency distribution. The gain is usually largest for short interactive traffic and narrows as prefill dominates. Track P50/P99 TTFT and TPOT, total throughput, accepted length, GPU memory, and stop rate rather than choosing from acceptance alone.
For every candidate, compare with the same recipe without --speculative-algorithm DSPARK. Restart the server between the DSpark and non-speculative legs, keep the request corpus, sampling, concurrency, and warmup identical, and give each bench_serving leg its own --flush-cache. Leave --speculative-draft-attention-backend unset unless a separate profiling run justifies an override.
DSpark currently requires CUDA, pp_size == 1, and DP Attention disabled. It is not compatible with PD disaggregation on current SGLang releases; selecting a prefill or decode role in the Playground automatically removes the inherited DSpark flags. The DP-Attention and MI355X Flash Official recipes therefore run target-only. If a larger draft block or concurrency causes graph-capture OOM, lower --mem-fraction-static, the draft block size, or the configured maximum running requests, then rerun both performance and accuracy gates.