SGLang 0.5.15: Spec V2와 Breakable CUDA Graph가 기본 경로가 되면서 달라진 운영 기준
왜 지금 SGLang 0.5.15를 봐야 하나
2026년 7월 10일 공개된 SGLang 0.5.15는 새 모델 몇 개를 더 지원했다는 수준의 릴리스가 아니다. 이미 RadixAttention, prefix cache, disaggregated prefill/decode 같은 큰 구조를 이해한 운영자에게는 이제 병목이 어디로 옮겨갔는지를 보여주는 릴리스다.
병목은 점점 모델 자체보다 다음으로 이동한다.
- speculative decoding에서 CPU 스케줄러와 GPU worker 사이의 동기화 오버헤드
- CUDA graph에 못 들어가는 연산 때문에 생기는 launch overhead
- MTP와 sparse attention 경로에서 반복되는 인덱서 작업
- 긴 컨텍스트에서 커지는 정적 page-table 메모리
v0.5.15는 이 네 가지를 각각 다른 레이어에서 건드린다. 릴리스 노트는 Spec V2 기본화, Breakable CUDA Graph 기본 경로, IndexShare MTP, TopK V2를 한 묶음으로 설명한다. 공통점은 하나다. 토큰 하나를 더 빨리 뽑는 것이 아니라, 토큰을 뽑기 위해 매 step마다 치르던 제어면 비용을 줄이는 것이다.
다만 이 릴리스에서 가장 중요한 점은 성능 숫자보다도 기본 경로와 플래그 표면이 바뀌었다는 사실이다. 태그된 저장소 안에서도 구형 markdown 문서, 새 docs 트리, 실제 source code가 완전히 같은 말을 하지는 않는다. 그래서 이번 글은 "몇 % 빨라졌다"보다 무엇이 실제 기본값인지, 운영자가 무엇을 명시적으로 확인해야 하는지에 초점을 맞춘다.
한눈에 보는 변화
| 변화 | 태그된 근거 | 운영자가 읽어야 할 포인트 |
|---|---|---|
| Spec V2 overlap scheduler 기본 경로화 | v0.5.15 release note, docs_new/docs/advanced_features/speculative_decoding.mdx, speculative_hook.py | 예전처럼 SGLANG_ENABLE_SPEC_V2=True를 넣는 방식이 아니라, 기본 활성 경로를 전제로 --disable-overlap-schedule로 되돌리는 사고가 필요하다. |
| Breakable CUDA Graph 기본화 | release note, PR #29458, cuda_graph_config.py | 릴리스 노트만 보면 전체 경로가 breakable처럼 읽히지만, 태그된 source는 CUDA 환경에서 prefill 기본값만 breakable, decode 기본값은 여전히 full이다. |
| IndexShare MTP | PR #29959 | GLM/DSA 계열 MTP 경로에서 레이어 간 중복 indexer 작업을 건너뛰어 draft step 비용을 줄인다. 모든 모델 공통 이득으로 읽으면 안 된다. |
| TopK V2 + compact page table | PR #30274 | 긴 컨텍스트 decode 경로에서 정적 page table 메모리와 전처리 비용을 줄인다. DeepSeek/GLM 계열 DSA 경로에서 특히 의미가 크다. |
| draft-extend CUDA graph화 | PR #29413 | overlap scheduler를 실제 기본 경로로 쓰려면 host sync가 남아 있으면 안 되는데, 그 구멍 하나를 메운 변경이다. |
릴리스 노트에는 +11% TPS, 최대 1.9x 낮은 draft-step cost, ~8% faster decode 같은 수치가 포함돼 있다. 이 수치들은 모두 upstream이 특정 모델/하드웨어에서 측정한 값이다. 이번 글에서는 그 숫자를 결과로 받아들이지 않고, 어떤 구조가 그 수치를 만들려고 하는지를 본다.
전체 경로: v0.5.15가 줄이려는 것은 어디의 비용인가
이 그림에서 봐야 할 핵심은 단순하다.
- speculative decoding의 이득은 draft model accuracy만으로 결정되지 않는다.
- CPU scheduler와 GPU worker를 얼마나 겹쳐서 돌릴 수 있는지, host sync를 얼마나 없앴는지가 실제 처리량에 크게 작용한다.
- CUDA graph는 아직 중요하지만, "전체를 하나로 잡아라"보다 "깨야 할 곳만 깨라"는 방향으로 바뀌고 있다.
- MTP/DSA 계열에서는 토큰을 예측하는 계산보다도, 그 토큰을 검증하기 위해 필요한 보조 메타데이터 작업이 새로운 병목이 된다.
1. Spec V2는 이제 옵션이 아니라 기본 가정에 가깝다
v0.5.15에서 가장 큰 사고 전환은 speculative decoding의 V2 worker와 overlap scheduler를 기본 경로로 놓고 생각해야 한다는 점이다.
태그된 docs_new/docs/advanced_features/speculative_decoding.mdx는 다음 의미를 분명히 가진다.
- speculative decoding은 V2 workers를 사용한다.
- overlap scheduler는 기본 활성화다.
- 되돌리고 싶으면
--disable-overlap-schedule을 써야 한다. - 현재 overlap scheduler는
--speculative-eagle-topk 1만 지원한다.
반면, 같은 태그 안의 구형 docs/advanced_features/speculative_decoding.md에는 여전히 SGLANG_ENABLE_SPEC_V2=True를 설정해 SpecV2를 켠다고 적혀 있다. 그런데 실제 source인 python/sglang/srt/arg_groups/speculative_hook.py는 더 강하게 말한다. 이 환경변수는 제거되었고, 넣어도 경고만 내며, 비동기 경로를 끄려면 --disable-overlap-schedule을 쓰라고 안내한다.
즉, 운영 기준은 이렇게 바뀐다.
- 예전 기준: "Spec V2를 켤까 말까"
- 지금 기준: "기본 overlap 경로를 그대로 쓸지, 일부 workload에서 동기 경로로 되돌릴지"
이 차이는 실무에서 꽤 크다. 기존 runbook에 SGLANG_ENABLE_SPEC_V2=True만 남아 있으면 다음 두 가지 문제가 생긴다.
- 운영자는 옵션을 "켰다"고 믿지만 실제로는 이미 기본 경로라서 A/B 비교가 꼬인다.
- top-k 제약을 명시하지 않으면 auto-tuning이 일부 모델에서
topk > 1을 잡아 overlap scheduler와 충돌할 수 있다.
바로 써먹을 수 있는 A/B 기준
python3 -m sglang.launch_server \
--model Qwen/Qwen2.5-7B-Instruct \
--speculative-algorithm STANDALONE \
--speculative-draft-model-path Qwen/Qwen2.5-1.5B-Instruct \
--speculative-num-steps 4 \
--speculative-eagle-topk 1 \
--speculative-num-draft-tokens 5 \
--cuda-graph-max-bs-decode 8
# 동기 경로와 비교할 때만 추가
# --disable-overlap-schedule여기서 중요한 건 --disable-overlap-schedule 자체보다 명시적으로 --speculative-eagle-topk 1을 고정하는 습관이다. 그래야 겹치는 스케줄러의 효과와 draft tree branching 효과를 섞어서 보지 않게 된다.
2. Breakable CUDA Graph는 "전체 기본값"이 아니라 phase별 기본값으로 읽어야 한다
Breakable CUDA Graph 문서는 문제를 정확히 짚는다. 일반 CUDA graph는 빠르지만, 한 번 capture되면 다음이 어렵다.
- 어느 연산이 잘못됐는지 디버깅하기 어렵다.
- dynamic control flow, host-device synchronization, JIT compile처럼 graph에 안 들어가는 연산을 만나면 전체 graph를 꺼야 한다.
Breakable CUDA Graph는 이 사이를 노린다. graphable한 구간은 잡아두고, 안 되는 부분만 eager segment로 끊는다. 이 접근은 speculative decoding처럼 경로가 복잡한 추론 엔진에 잘 맞는다.
문제는 릴리스 노트의 표현이다. PR #29458 제목은 Enable Breakable Cuda Graph as Default이고, 릴리스 노트도 "Breakable CUDA Graph on by default"로 읽힌다. 그런데 태그된 cuda_graph_config.py를 보면 기본 설정은 이렇게 잡혀 있다.
decode.backend = fullprefill.backend = breakableon CUDA
이 차이를 운영자가 놓치면 위험하다.
왜 이 차이가 중요한가
1. 디코드 경로 버그를 breakable 기본값으로 착각할 수 있다
릴리스 노트만 읽고 "이제 decode도 breakable이겠지"라고 생각하면, 실제론 full graph에서만 재현되는 문제를 잘못 추적하게 된다.
2. 성능 벤치마크 해석이 달라진다
prefill에서 breakable이 기본이어도 decode는 full이면, request mix에 따라 체감 이득이 다르다. 긴 prompt 위주 batch와 짧은 streaming decode 위주 batch는 같은 결과를 내지 않는다.
3. 명시적 pinning이 더 중요해진다
릴리스 이후에는 묵시적 환경변수에 기대기보다, phase별 graph backend를 직접 고정하는 편이 안전하다.
예를 들면 다음처럼 적어두는 편이 낫다.
--cuda-graph-config '{"decode":{"backend":"full","max_bs":256},"prefill":{"backend":"breakable"}}'이렇게 해두면 릴리스 노트 문구, 환경변수, 내부 default 변경에 덜 흔들린다.
디버깅 경로도 바뀐다
문서가 제안하는 --debug-cuda-graph는 여전히 유효하다. 이 플래그는 forward 전체를 eager처럼 돌리되, capture/replay 코드 경로 자체는 유지한다. 즉, "CUDA graph를 완전히 끈 eager baseline"이 아니라, graph 관련 버그를 재현할 수 있는 eager형 디버그 경로라는 점이 중요하다.
3. IndexShare MTP와 TopK V2는 "모델이 아니라 메타데이터 경로"를 줄인다
v0.5.15의 또 다른 흥미로운 지점은 IndexShare MTP와 TopK V2다. 이 둘은 새 attention 알고리즘이 아니다. 대신, DeepSeek sparse attention(DSA) 계열에서 토큰을 검증하기 위해 필요한 부수 작업을 줄인다.
IndexShare MTP
PR #29959는 Index Share for MHA라는 제목 그대로, 공유 indexer layer에서 indexer를 다시 돌리지 않도록 바꾼다. 릴리스 노트는 이를 IndexShare MTP라고 요약하면서 긴 컨텍스트에서 draft-step cost를 줄인다고 설명한다.
운영 관점에서 중요한 포인트는 다음이다.
- 이 이득은 모든 speculative decoding 공통 이득이 아니다.
- DSA/GLM5.2 같은 공유 indexer layer를 가진 모델 경로에서 의미가 크다.
- 따라서 Llama 계열 일반 speculative serving에서 같은 숫자를 기대하면 안 된다.
TopK V2
PR #30274는 더 실무적이다. 핵심은 두 가지다.
- Top-k transform 계획(plan)을 한 번의 forward마다 한 번만 계산해 재사용한다.
- decode CUDA graph에서
page_size=1기반의 넓은 page table을 버리고 compactreal_page_table을 직접 사용한다.
PR 설명에는 160K context 기준으로 이 정적 table이 64배 작아진다는 말이 나온다. 이 역시 upstream이 설명한 특정 경로의 효과지만, 운영자 입장에서는 숫자보다 뜻이 더 중요하다.
- 긴 컨텍스트일수록 정적 graph metadata도 메모리를 먹는다.
- sparse attention 경로에서는 실제 attention 계산보다 page table 구성 비용이 커질 수 있다.
- 따라서 long-context serving 병목은 "KV cache 메모리만"이 아니라 KV를 찾기 위한 인덱싱/페이지 메타데이터로도 확장된다.
즉, v0.5.15는 speculative decoding을 더 똑똑하게 만든다기보다, speculative decoding을 둘러싼 보조 경로를 더 싸게 만든다고 읽는 편이 맞다.
4. 이번 릴리스에서 가장 조심해야 할 것은 문서 표면의 드리프트다
보통 이런 릴리스 글은 "새 기능 목록"으로 끝나지만, SGLang 0.5.15는 그보다 어느 문서를 믿을지가 더 중요하다.
태그된 저장소 기준으로 보면:
- 구형
docs/advanced_features/speculative_decoding.md는SGLANG_ENABLE_SPEC_V2=True를 여전히 소개한다. - 새
docs_new/docs/advanced_features/speculative_decoding.mdx는 overlap scheduler 기본 활성화를 설명한다. - 실제 source
speculative_hook.py는 env var 제거 경고를 낸다. - release note는 Breakable CUDA Graph default를 강하게 말한다.
- 실제 source
cuda_graph_config.py는 decode/prefill 기본값을 phase별로 다르게 둔다.
이런 드리프트가 생기면 운영자가 해야 할 일은 단순하다.
- release note를 읽는다.
- tagged docs_new를 확인한다.
- 마지막으로 source에서 기본값을 본다.
- production 명령줄에는 추론에 민감한 값을 명시적으로 적는다.
특히 다음 둘은 묵시적 default에 맡기지 않는 편이 안전하다.
- speculative overlap 사용 여부와 관련 파라미터 (
--disable-overlap-schedule,--speculative-eagle-topk 1) - phase별 CUDA graph backend (
--cuda-graph-config ...)
운영자가 바로 확인할 체크리스트
speculative overlap 경로
- [ ] 기존 runbook에
SGLANG_ENABLE_SPEC_V2만 들어가 있지 않은지 확인한다. - [ ] overlap scheduler를 쓸 때
--speculative-eagle-topk 1을 명시한다. - [ ] baseline 비교는
--disable-overlap-schedule을 추가한 동기 경로로 잡는다. - [ ] accepted tokens, tokens/sec, TTFT, inter-token latency를 같은 prompt mix로 다시 측정한다.
CUDA graph 경로
- [ ] release note 문구만 믿지 말고 phase별 backend를 점검한다.
- [ ] 문제 재현이 필요하면
--debug-cuda-graph로 eager형 디버그 경로를 먼저 확인한다. - [ ] production에서는
--cuda-graph-config로 decode/prefill backend를 pinning한다. - [ ] prefill-heavy workload와 decode-heavy workload를 분리해서 본다.
DSA / MTP / long-context 경로
- [ ] 내 모델이 DSA/GLM/DeepSeek sparse attention 계열인지 먼저 확인한다.
- [ ] 아니면 IndexShare MTP와 TopK V2의 효과를 일반화하지 않는다.
- [ ] 긴 컨텍스트에서 GPU 메모리뿐 아니라 정적 metadata allocation도 같이 관찰한다.
- [ ] upstream이 제시한 Blackwell/특정 모델 수치를 그대로 목표치로 삼지 않는다.
검증 순서 제안
- 현재 production 플래그를 그대로 유지한 v0.5.14/이전 버전 baseline 측정
- v0.5.15로 올리되
--disable-overlap-schedule상태로 1차 측정 - overlap scheduler 활성화 +
--speculative-eagle-topk 1고정 - 필요 시
cuda_graph_config를 명시해 prefill/decode backend를 분리 측정 - DSA 모델만 따로 long-context profile 수집
이 순서를 지키면 "릴리스 업그레이드 효과"와 "새 기본값 효과"를 섞지 않고 볼 수 있다.
이 릴리스를 한 문장으로 요약하면
SGLang 0.5.15는 speculative decoding과 CUDA graph를 더 화려하게 만든 릴리스가 아니라, 그 둘을 실제 production 기본 경로로 밀어 넣기 위해 남아 있던 스케줄링·그래프 캡처·메타데이터 비용을 줄인 릴리스에 가깝다.
그래서 이번 릴리스의 핵심 질문은 "몇 % 빨라졌나"가 아니다. 내 서버가 지금 어느 기본 경로를 타고 있는가, 그리고 그 경로를 내가 명시적으로 제어하고 있는가가 더 중요하다.
References
- SGLang v0.5.15 release notes (published 2026-07-10): https://github.com/sgl-project/sglang/releases/tag/v0.5.15
- SGLang speculative decoding docs (new docs tree, tagged v0.5.15): https://github.com/sgl-project/sglang/blob/v0.5.15/docs_new/docs/advanced_features/speculative_decoding.mdx
- SGLang speculative decoding docs (legacy markdown in tagged tree, tagged v0.5.15): https://github.com/sgl-project/sglang/blob/v0.5.15/docs/advanced_features/speculative_decoding.md
- SGLang breakable CUDA graph docs (tagged v0.5.15): https://github.com/sgl-project/sglang/blob/v0.5.15/docs_new/docs/advanced_features/breakable_cuda_graph.mdx
speculative_hook.pyin tagged source (v0.5.15): https://github.com/sgl-project/sglang/blob/v0.5.15/python/sglang/srt/arg_groups/speculative_hook.pycuda_graph_config.pyin tagged source (v0.5.15): https://github.com/sgl-project/sglang/blob/v0.5.15/python/sglang/srt/model_executor/cuda_graph_config.py- PR #29458 — Enable Breakable Cuda Graph as Default (merged 2026-07-02): https://github.com/sgl-project/sglang/pull/29458
- PR #29413 — Enable draft-extend CUDA graph for DeepSeek Sparse Attention (merged 2026-06-27): https://github.com/sgl-project/sglang/pull/29413
- PR #29959 — Index Share for MHA (merged 2026-07-04): https://github.com/sgl-project/sglang/pull/29959
- PR #30274 — Fold page-table into fused top-k v2 (merged 2026-07-07): https://github.com/sgl-project/sglang/pull/30274