NixlConnector 호환성 매트릭스

프리필/디코드를 분리해 서빙할 때 NixlConnector를 쓰면 어떤 기능이 되는지, 어떤 모델에서 되는지를 한눈에 보여주는 페이지예요. 일반 사용법은 NixlConnector 사용 가이드를, 분리 프리필링 개요는 Disaggregated Prefilling을 참고하세요.

출처: 공식문서

!!! note 이 페이지는 현재 코드베이스 상태를 반영하며, 기능이 발전함에 따라 바뀔 수 있어요. 🟠 또는 ❌로 표시된 항목은 추적 이슈로 연결될 수 있어요. 앞으로의 기능 개발은 NIXL 연결 로드맵을 참고하세요.

범례 (Legend):

✅ = 완전 지원
🟠 = 부분 지원 (각주 참고)
❌ = 미지원
❔ = 알 수 없음 / 아직 검증되지 않음
🚧 = 진행 중 (Work in progress)

!!! info "보편적으로 지원되는 기능" 다음 기능들은 NixlConnector PD 분리 서빙을 사용할 때 모든 모델 아키텍처에서 동작해요.

[Chunked Prefill](../configuration/optimization.md#chunked-prefill) |
[APC (Prefix Caching)](automatic_prefix_caching.md) |
[Data Parallel](../serving/data_parallel_deployment.md) |
CUDA graph |
Logprobs |
Prompt Logprobs |
[Prompt Embeds](prompt_embeds.md) |
여러 NIXL 백엔드 (UCX, GDS, LIBFABRIC 등)

모델 아키텍처 x 기능

모델 유형	기본 PD	Spec Decode	Hetero TP	크로스 레이어 블록	SWA	호스트 버퍼	Hetero 블록 크기
Dense Transformers	✅	✅¹	✅	✅²	✅	✅	🟠³
MLA (예: DeepSeek-V2/V3)	✅	✅¹	🟠⁴	✅²	✅	✅	🟠³
Sparse MLA (예: DeepSeek-V3.2)	✅	✅¹	🟠⁴	✅²	✅	✅	🟠³
Hybrid SSM / Mamba	✅	❔	🚧⁵	❌	✅	✅	❌⁶
MoE	✅	✅¹	✅	✅²	✅	✅	🟠³
Multimodal	❔	❔	❔	❔	❔	❔	❔
Encoder-Decoder	❌	❌	❌	❌	❌	❌	❌

¹ P와 D 인스턴스는 호환되는 스펙큘레이션 설정을 사용해야 해요. 무엇이 일치해야 하고 무엇이 달라도 되는지는 아래 설정 메모를 참고하세요.

² 크로스 레이어 연속성은 BLHNC 레이아웃을 사용해 얻어요(VLLM_KV_CACHE_LAYOUT=BLHNC로 설정).

³ HMA가 필요하지 않을 때만 지원돼요(즉 non-hybrid 모델). 블록 ID는 자동으로 재매핑돼요. P 블록 크기 < D 블록 크기만 지원돼요.

⁴ MLA KV 캐시는 TP 워커 간에 복제되므로, 이종 TP가 동작하지만 헤드 분할(head-splitting)은 없어요. P TP > D TP일 때는 단일 read만 실행돼요(중복 랭크는 건너뜀). D TP > P TP도 동작해요.

⁵ Hybrid SSM(Mamba) 모델은 균일 TP(P TP == D TP)가 필요해요. 이종 TP는 Mamba 레이어에서 아직 지원되지 않아요.

⁶ HMA(hybrid 모델에 필요)는 서로 다른 원격 블록 크기를 지원하지 않아요.

설정 메모 (Configuration Notes)

P와 D 사이에서 반드시 일치해야 하는 것

기본적으로 핸드셰이크 중에 호환성 해시(compatibility hash) 가 확인돼요. P와 D 인스턴스는 다음이 일치해야 해요.

vLLM 버전과 NIXL 커넥터 버전
모델(아키텍처, dtype, KV 헤드 수, 헤드 크기, 히든 레이어 수)
어텐션 백엔드
KV 캐시 dtype(cache_dtype)
EAGLE/MTP 스타일의 스펙큘레이티브 방식과 드래프트 모델 설정
NIXL 전송 모드(push vs pull) — push(WRITE) 커넥터와 pull(READ) 커넥터는 호환되지 않는 전송 프로토콜을 쓰므로 절대 짝지으면 안 돼요

!!! warning 해시 확인을 끄려면 --kv-transfer-config '{"kv_connector_extra_config": {"enforce_handshake_compat": false}}'로 끌 수 있는데, 책임은 본인이 져야 해요.

P와 D 사이에서 안전하게 달라도 되는 것

tensor-parallel-size (이종 TP, 위 모델 제약 적용)
block-size (이종 블록 크기, 위 제약 적용)
KV 캐시 블록 수 (각 인스턴스의 가용 메모리가 결정)
num_speculative_tokens (prefill과 decode가 다른 드래프트 깊이를 쓸 수 있음)
드래프트 모델 attention_backend (각 인스턴스가 독립적으로 자동 선택. 결과 KV 블록 레이아웃은 호환성 해시가 아니라 핸드셰이크 시점에 검증됨)

KV 캐시 레이아웃

NixlConnector는 기본적으로 최적 전송 성능을 위해 LBHNC(head-major, 이전 HND) 레이아웃을 써요(non-MLA 모델).
LBNHC(token-major, 이전 NHD) 레이아웃도 지원되지만 이종 TP 헤드 분할은 허용하지 않아요.
실험적인 LBHNC ↔ LBNHC permute: --kv-transfer-config '{"enable_permute_local_kv": true}'로 켜요. HMA에서는 지원되지 않아요.

양자화된 KV 캐시

양자화된 KV 캐시(예: FP8)는 P와 D 인스턴스 모두 같은 cache_dtype를 사용해야 해요. cache_dtype가 다르면 핸드셰이크 중 호환성 해시 확인에서 실패해요.

정적 양자화(체크포인트에서 로드한 스케일): ✅ 지원. 각 인스턴스가 모델 체크포인트에서 스케일을 독립적으로 로드해요.
동적 양자화(런타임에 계산한 스케일): ❌ 미지원. KV 캐시 데이터와 함께 퍼블록 스케일이 전송되지 않아요.
Packed 레이아웃 스케일(가중치와 함께 인라인 저장): ✅ 지원. KV 캐시 블록과 함께 스케일이 전송돼요.

NixlConnector 호환성 매트릭스