MooncakeConnector 사용 가이드

프리필(prefill)과 디코드(decode)를 분리해 서빙할 때, 두 인스턴스 사이에서 KV 캐시를 어떻게 옮길지가 관건이에요. vLLM은 KV 캐시 전송 커넥터를 통해 이 문제를 풀고, 그중 하나가 MooncakeConnector예요. 이 가이드는 Mooncake 커넥터로 프리필/디코드 분산 서빙을 구성하는 방법을 설명해요.

출처: 공식문서

Mooncake 소개

Mooncake는 느린 객체 스토리지 환경에서 대규모 언어모델(LLM)의 추론 효율을 높이기 위해, 고속으로 연결된 DRAM/SSD 자원 위에 다단계 캐싱 풀을 구축하는 방식이에요. 기존 캐싱 시스템과 달리 Mooncake는 (GPUDirect) RDMA 기술로 데이터를 제로 카피(zero-copy) 방식으로 직접 전송하면서, 단일 머신의 다중 NIC 자원을 최대한 활용해요.

Mooncake에 대한 더 자세한 내용은 Mooncake 프로젝트와 Mooncake 문서를 참고하세요.

사전 준비 (Prerequisites)

설치

mooncake를 pip으로 설치해요: uv pip install mooncake-transfer-engine-cuda13.

vLLM은 기본적으로 CUDA 13을 사용해요. CUDA 12 환경에서는 mooncake-transfer-engine을 설치하세요 — 둘은 같은 릴리스를 서로 다른 CUDA 메이저 버전에 맞춰 빌드한 것이고, 잘못된 걸 설치하면 libcudart.so.<major>: cannot open shared object file 오류가 나면서 import에 실패해요.

더 자세한 설치 방법은 Mooncake 공식 저장소를 참고하세요.

사용법 (Usage)

프리필러 노드 (Prefiller Node, 192.168.0.2)

vllm serve Qwen/Qwen2.5-7B-Instruct --port 8010 --kv-transfer-config '{"kv_connector":"MooncakeConnector","kv_role":"kv_producer"}'

디코더 노드 (Decoder Node, 192.168.0.3)

vllm serve Qwen/Qwen2.5-7B-Instruct --port 8020 --kv-transfer-config '{"kv_connector":"MooncakeConnector","kv_role":"kv_consumer"}'

프록시 (Proxy)

python examples/disaggregated/mooncake_connector/mooncake_connector_proxy.py --prefill http://192.168.0.2:8010 --decode http://192.168.0.3:8020

이제 8000번 포트를 통해 프록시 서버에 요청을 보내면 돼요.

환경변수

VLLM_MOONCAKE_BOOTSTRAP_PORT: Mooncake 부트스트랩 서버 포트
- 기본값: 8998
- 프리필러 인스턴스에만 필요해요
- headless 인스턴스라면 마스터 인스턴스와 같은 값이어야 해요
- 각 인스턴스는 자기 호스트에서 고유한 포트를 써야 해요. 다른 호스트끼리 같은 포트 번호를 쓰는 건 문제없어요.
WITH_NVIDIA_PEERMEM: Mooncake가 RDMA용 GPU 메모리를 등록하는 방식을 선택해요. vLLM이 아니라 mooncake가 읽는 값이에요.
- 기본값 1은 ibv_reg_mr()을 쓰고, nvidia-peermem 커널 모듈이 로드돼 있어야 해요
- 0으로 두면 DMA-BUF 경로를 쓰는데, 그 모듈이 필요 없어요. nvidia-peermem이 로드되지 않은 호스트(예: GB200)에서 필수예요
- 컨테이너 이미지라면 실행 시점에 넘겨주세요: docker run -e WITH_NVIDIA_PEERMEM=0 ...
- 이런 호스트에서 설정을 안 두면 생기는 증상: rdma_context.cpp에서 Failed to register memory <addr>: Bad address [14]가 나오고 KV 전송이 실패해요
VLLM_MOONCAKE_ABORT_REQUEST_TIMEOUT: 특정 요청에 대해 프리필러의 KV 캐시를 자동으로 해제하는 타임아웃(초)이에요. (선택 사항)
- 기본값: 480
- 요청이 중단됐는데 디코더가 아직 프리필러에 알리지 못한 경우, 이 타임아웃이 지나면 프리필 인스턴스가 자기 KV-cache 블록을 해제해서 무한정 붙잡고 있지 않게 해요.

KV 전송 설정 (KV Transfer Config)

KV 역할 옵션 (KV Role Options)

kv_producer: KV 캐시를 생성하는 프리필러 인스턴스용
kv_consumer: 프리필러에서 KV 캐시를 소비하는 디코더 인스턴스용
kv_both: 커넥터가 producer와 consumer를 모두 수행할 수 있는 대칭 기능을 켜요. 역할 구분이 미리 정해지지 않은 실험적 구성이나 시나리오에서 유연하게 쓸 수 있어요.

kv_connector_extra_config

num_workers: 프리필러 워커 하나가 mooncake로 KV 캐시를 전송할 때 쓰는 스레드 풀 크기. (기본 10)
mooncake_protocol: Mooncake 커넥터 프로토콜. (기본 "rdma")
device_name: 토폴로지 발견을 제한할 RDMA 장치의 쉼표 구분 화이트리스트(예: "mlx5_0,mlx5_1"). 비워두면 모든 장치를 발견해요. InfiniBand와 RoCE 포트가 섞여 있는 호스트에서 유용한데, 양쪽 피어가 같은 링크 레이어로 합의해야 하거든요.

예제 스크립트/코드

vLLM 저장소의 다음 예제 스크립트를 참고하세요.

MooncakeConnector 사용 가이드