Mooncake 커넥터 사용 가이드

Mooncake 커넥터 사용 가이드 (MooncakeConnector Usage Guide)

Mooncake는 대규모 언어 모델(LLM)의 추론 효율을 높이기 위한 프로젝트로, 특히 느린 객체 스토리지 환경에서 고속 상호연결 DRAM/SSD 리소스에 다중 레벨 캐싱 풀을 구성해 성능을 개선해요. 기존 캐싱 시스템과 달리 (GPUDirect) RDMA 기술을 사용해 데이터를 제로 카피(zero-copy) 방식으로 직접 전송하고, 단일 머신의 다중 NIC 리소스를 최대한 활용합니다.

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

출처: 문서

본문

사전 준비 (Prerequisites)

설치 (Installation)

pip으로 mooncake를 설치하세요:

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 노드 (192.168.0.2)

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

Decoder 노드 (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 포트를 통해 proxy 서버로 요청을 보낼 수 있어요.

환경 변수 (Environment Variables)

VLLM_MOONCAKE_BOOTSTRAP_PORT: mooncake bootstrap 서버를 위한 포트입니다.
- 기본값: 8998
- prefiller 인스턴스에만 필요합니다.
- 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: 특정 요청에 대해 prefiller의 KV 캐시를 자동으로 해제하기 위한 타임아웃(초)입니다. (선택 사항)
- 기본값: 480
- 요청이 중단되었는데 decoder가 아직 prefiller에 알리지 못한 경우, prefill 인스턴스는 이 타임아웃 이후 KV-cache 블록을 해제해 무기한 보유를 방지합니다.

KV 전송 설정 (KV Transfer Config)

KV 역할 옵션 (KV Role Options)

kv_producer: KV 캐시를 생성하는 prefiller 인스턴스용입니다.
kv_consumer: prefiller로부터 KV 캐시를 소비하는 decoder 인스턴스용입니다.
kv_both: 커넥터가 producer와 consumer 역할을 모두 수행할 수 있게 하는 대칭 기능입니다. 역할 구분이 미리 정해지지 않은 실험적 설정이나 시나리오에 유연성을 제공합니다.

kv_connector_extra_config

num_workers: 하나의 prefiller 워커가 mooncake로 KV 캐시를 전송할 때 사용하는 스레드 풀 크기입니다. (기본값 10)
mooncake_protocol: mooncake 커넥터 프로토콜입니다. (기본값 "rdma")
device_name: 토폴로지 탐색을 제한할 RDMA 디바이스의 쉼표로 구분된 화이트리스트입니다(예: "mlx5_0,mlx5_1"). 비워두면 모든 디바이스를 탐색합니다. InfiniBand와 RoCE 포트가 섞여 있는 호스트에서 유용하며, 양쪽 피어가 동일한 링크 계층을 사용해야 합니다.

예시 스크립트/코드

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

Mooncake 커넥터 사용 가이드