NixlConnector 호환성 매트릭스

NixlConnector 호환성 매트릭스 (NixlConnector Compatibility Matrix)

이 페이지는 NixlConnector를 사용한 분리형 프리필링(disaggregated prefilling) 의 기능 호환성을 문서화합니다. 일반 사용법은 NixlConnector 사용 가이드 를, 분리형 프리필링 개요는 Disaggregated Prefilling 을 참고하세요.

참고: 이 페이지는 코드베이스의 현재 상태를 반영하며 기능이 발전함에 따라 변경될 수 있습니다. 🟠 또는 ❌ 항목은 추적 이슈로 연결될 수 있습니다. 향후 기능 개발은 NIXL 커넥터 로드맵 을 참고하세요.

범례(Legend): ✅ = 완전 지원, 🟠 = 부분 지원(각주 참고), ❌ = 지원 안 함, ❔ = 알 수 없음 / 아직 검증 안 됨, 🚧 = 진행 중

출처: 문서

본문

보편 지원 기능 (Universally supported features)

NixlConnector PD 분리 서빙을 사용할 때 다음 기능은 모든 모델 아키텍처에서 동작합니다.

모델 아키텍처 × 기능 (Model Architecture x Capability)

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

P와 D 인스턴스는 호환 가능한 speculation 구성을 사용해야 합니다. 무엇이 일치해야 하고 무엇이 달라도 되는지는 아래 구성 참고 를 참고하세요.
크로스 레이어 연속성은 BLHNC 레이아웃(VLLM_KV_CACHE_LAYOUT=BLHNC 로 설정)을 사용해 달성됩니다.
HMA가 필요하지 않은 경우(즉 비-하이브리드 모델)에만 지원됩니다. 블록 ID가 자동으로 리매핑됩니다. P 블록 크기 < D 블록 크기만 지원됩니다.
MLA KV 캐시는 TP 워커 전체에 복제되므로 이기종 TP가 동작하지만 헤드 분할은 없습니다. P TP > D TP일 때 단일 읽기만 실행됩니다(중복 랭크는 건너뜀). D TP > P TP도 동작합니다.
Hybrid SSM (Mamba) 모델은 균일 TP(P TP == D TP)를 요구합니다. Mamba 레이어에 대한 이기종 TP는 아직 지원되지 않습니다.
HMA(하이브리드 모델에 필요)는 서로 다른 원격 블록 크기를 지원하지 않습니다.

구성 참고 (Configuration Notes)

P와 D 사이에 일치해야 하는 것

기본적으로 핸드셰이크 중 호환성 해시(compatibility hash) 가 검사됩니다. P와 D 인스턴스는 다음에 동의해야 합니다.

vLLM 버전과 NIXL 커넥터 버전
모델(아키텍처, dtype, KV 헤드 수, 헤드 크기, hidden 레이어 수)
Attention 백엔드
KV 캐시 dtype(cache_dtype)
EAGLE/MTP 스타일 스펙큘레이티브 방식과 draft 모델 구성
NIXL 전송 모드(push vs pull) — push(WRITE) 커넥터와 pull(READ) 커넥터는 호환되지 않는 전송 프로토콜을 사용하므로 절대 함께 연결해서는 안 됩니다.

경고: 해시 검사를 --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가 서로 다른 draft 깊이를 사용할 수 있음)
Draft 모델의 attention_backend (각 인스턴스가 독립적으로 자동 선택하며, 결과 KV 블록 레이아웃은 호환성 해시가 아니라 핸드셰이크 시점에 검증됩니다)

KV 캐시 레이아웃

NixlConnector는 기본적으로 최적의 전송 성능을 위해 LBHNC(head-major, 이전 HND) 레이아웃을 사용합니다(비-MLA 모델).

LBNHC(token-major, 이전 NHD) 레이아웃은 지원되지만 이기종 TP 헤드 분할을 허용하지 않습니다.

실험적 LBHNC ↔ LBNHC permute는 --kv-transfer-config '{"enable_permute_local_kv": true}' 로 활성화할 수 있어요. HMA에서는 지원되지 않습니다.

파이프라인 병렬 (Pipeline parallelism)

기본(pull) NixlConnector는 하이브리드 KV 캐시(HMA) 레이아웃과 함께 pipeline-parallel-size > 1 을 지원하지 않습니다. region 인덱스가 prefill/decode 레이어 분할을 가로질러 안정적인 아이덴티티가 아니므로 커넥터가 시작 시 오류를 일으킵니다. 하이브리드 KV 캐시와 함께 파이프라인 병렬을 사용하려면 push 커넥터(NixlPushConnector)를 사용하세요. 이 커넥터는 레이어 이름(member) 아이덴티티로 전송을 라우팅하므로 PP 분할 프리필러가 PP=1 decoder에 쓸 수 있습니다. NIXL push-mode KV 전송 을 참고하세요.

현재 push PP + HMA 제한 사항:

오직 prefiller(프로듀서)만 PP 분할될 수 있으며, decode 쪽 PP는 지원되지 않습니다.
Hybrid SSM/Mamba 레이아웃은 PP에서 지원되지 않습니다.
HMA는 P와 D에서 같은 블록 크기를 요구합니다.
Attention-HMA 멤버 라우팅은 decode TP가 prefill TP 이하이기를 요구합니다.

양자화된 KV 캐시 (Quantized KV cache)

양자화된 KV 캐시(예: FP8)는 P와 D 인스턴스 모두 같은 cache_dtype 을 사용해야 합니다. cache dtype이 일치하지 않으면 핸드셰이크 중 호환성 해시 검사가 실패합니다.

정적 양자화(스케일을 체크포인트에서 로드): ✅ 지원됨. 각 인스턴스가 모델 체크포인트에서 스케일을 독립적으로 로드합니다.
동적 양자화(스케일을 런타임에 계산): ❌ 지원 안 됨. per-block 스케일이 KV 캐시 데이터와 함께 전송되지 않습니다.
Packed-layout 스케일(가중치에 인라인으로 저장): ✅ 지원됨. 스케일이 KV 캐시 블록과 함께 전송됩니다.

NixlConnector 호환성 매트릭스