[SGLang] DeepSeek V3.2 지원 추가

PR 링크: sgl-project/sglang#11061 상태: Merged | 변경: +4542 / -141

들어가며

DeepSeek V3.2는 Native Sparse Attention(NSA)을 도입한 새로운 모델이다. 기존 MLA(Multi-head Latent Attention)에 sparse indexing을 결합하여 long context에서 attention 연산량을 줄인다. 이 PR은 SGLang 추론 엔진에 V3.2 모델 클래스, NSA attention 백엔드, 그리고 관련 설정을 추가한다.

핵심 코드 분석

모델 클래스 등록

Before:

class DeepseekV3ForCausalLM(DeepseekV2ForCausalLM):
    pass

EntryClass = [DeepseekV2ForCausalLM, DeepseekV3ForCausalLM]

After:

class DeepseekV3ForCausalLM(DeepseekV2ForCausalLM):
    pass

class DeepseekV32ForCausalLM(DeepseekV2ForCausalLM):
    pass

EntryClass = [DeepseekV2ForCausalLM, DeepseekV3ForCausalLM, DeepseekV32ForCausalLM]

V3.2는 V2의 아키텍처를 상속하되, HuggingFace config에서 DeepseekV32ForCausalLM으로 식별된다. EntryClass 리스트에 추가하여 모델 로딩 시 자동으로 인식된다.

NSA 감지 및 설정

Before:

if (
    "DeepseekV2ForCausalLM" in self.hf_config.architectures
    or "DeepseekV3ForCausalLM" in self.hf_config.architectures
    # ...
):

After:

def is_deepseek_nsa(config: PretrainedConfig) -> bool:
    return (
        config.architectures is not None
        and config.architectures[0]
        in ["DeepseekV3ForCausalLM", "DeepseekV32ForCausalLM"]
        and getattr(config, "index_topk", None) is not None
    )

index_topk 속성의 존재 여부로 NSA 지원 모델인지 판별한다. 이 값은 sparse attention에서 선택할 상위 k개 블록 수를 의미한다.

NSA Attention 백엔드 등록

@register_attention_backend("nsa")
def create_nsa_backend(runner):
    from sglang.srt.layers.attention.nsa_backend import NativeSparseAttnBackend
    return NativeSparseAttnBackend(runner)

새로운 nsa attention 백엔드가 등록되어, 서버 시작 시 --attention-backend nsa로 선택할 수 있다.

Sparse Attention forward 경로

def forward_sparse(self, q, k, v, layer, forward_batch,
                   save_kv_cache=True, q_rope=None, k_rope=None,
                   topk_indices=None):
    # ...
    attn_out = torch.ops.custom.npu_sparse_flash_attention(
        query=q_nope, key=k_nope, value=k_nope,
        query_rope=q_pe, key_rope=k_pe,
        sparse_indices=topk_indices,
        scale_value=layer.scaling,
        # ...
        sparse_mode=3,
    )
    return attn_out

topk_indices가 전달되면 sparse attention 경로로 분기한다. MLA의 nope/rope 분리 구조를 유지하면서 선택된 block만 attend하는 방식이다.

왜 이게 좋은가

NSA는 full attention 대비 연산량을 대폭 줄인다. 긴 시퀀스에서 모든 토큰에 attend하는 대신, indexer가 선택한 top-k 블록만 계산한다. V3.2 지원으로 SGLang 사용자는 최신 DeepSeek 모델을 바로 배포할 수 있으며, prefill/decode 각각에 최적화된 NSA 백엔드(flashmla_prefill, flashmla_decode 등)를 선택할 수 있다.

정리

• DeepseekV32ForCausalLM 모델 클래스가 추가되어 V3.2를 자동 인식한다
• nsa attention 백엔드가 등록되어 sparse attention을 지원한다
• index_topk, index_head_dim 등 NSA 관련 config 파라미터를 파싱한다
• Ascend NPU 백엔드에서도 sparse attention forward 경로가 구현되었다

참고 자료

• DeepSeek-V3 기술 보고서 -- MLA 아키텍처 상세 설명
• Native Sparse Attention 논문 -- NSA 알고리즘 원리

⚠️ 알림: 이 분석은 AI가 실제 코드 diff를 기반으로 작성했습니다.