SGLang HiCache 모범 사례

SGLang HiCache 모범 사례 (Best Practices)

SGLang HiCache는 전통적인 RadixAttention을 3단계 계층형 KV 캐싱 시스템으로 확장한 기능입니다. 긴 컨텍스트와 다중 턴 대화 시나리오에서 성능을 크게 개선해요. 이 문서는 HiCache를 실제로 배포할 때 어떤 설정을 고르고 어떻게 구성하는지 안내합니다.

출처: 문서

본문

HiCache가 왜 중요한가 (Why HiCache Matters)

SGLang HiCache는 기존 RadixAttention을 GPU 메모리, 호스트 메모리, 외부 스토리지 백엔드로 이어지는 3단계 계층형 KV 캐싱 시스템으로 확장해, 긴 컨텍스트와 다중 턴 대화 시나리오의 성능을 크게 개선합니다. KV 캐시를 GPU 메모리·호스트 메모리·외부 스토리지 백엔드에 걸쳐 지능적으로 관리함으로써, 기존 시스템에서 캐시 적중률을 제한하는 근본적인 용량 병목을 해결합니다.

L1과 L2는 단일 추론 인스턴스에 전용됩니다. L3만 공유할 수 있어요. 호스트 메모리는 인스턴스 간이나 호스트 간에 풀(pool)할 수 없으며, 같은 노드에 있는 두 인스턴스조차 불가능합니다. `--hicache-ratio`나 `--hicache-size`를 올리면 해당 인스턴스 고유의 private L2만 커집니다. 인스턴스 간 재사용은 L3의 몫이며, `--hicache-storage-backend`와 원하는 범위에 맞게 구성된 백엔드가 필요해요. `file` 백엔드는 기본적으로 노드 로컬 `/tmp/hicache`를 쓰지만, `mooncake`, `hf3fs`, `nixl`, `aibrix`는 모든 인스턴스가 동일 네임스페이스를 공유하면 클러스터 범위에 도달합니다. [Tier Sharing Scope](/docs/advanced_features/hicache_design#tier-sharing-scope)를 참고하세요.

설정 가이드라인 (Configuration Guidelines)

핵심 HiCache 파라미터 (Core HiCache Parameters)

# Essential HiCache flags
--page-size 64                        # Page size for cache management
--enable-hierarchical-cache           # Enable HiCache
--hicache-ratio 2                     # Host memory ratio (2x GPU memory)
--hicache-size 100                    # Host memory size in GBs, will override the above ratio
--hicache-io-backend kernel           # The I/O backend of moving data between CPU and GPU
--hicache-write-policy write_through  # Cache write policy from GPU to CPU
--hicache-storage-backend             # Optional storage backend (e.g., hf3fs, mooncake, etc.)

참고:

  • 시작 시 --hicache-storage-backend를 구성하는 것 외에도, SGLang은 HTTP admin 엔드포인트를 통한 HiCache 스토리지 백엔드의 런타임 attach/detach(재시작 불필요)를 지원합니다. Runtime Attach/Detach HiCache Storage Backend를 참고하세요.

스토리지 백엔드가 켜진 핵심 설정 (Key Configurations with Storage Backends Enabled)

메모리 레이아웃 최적화 (Memory Layout Optimization)

# Page-first: Optimized for I/O efficiency with zero-copy (recommended with kernel backend)
--hicache-mem-layout page_first
# Page-first-direct: Optimized for direct I/O operations (Compatible with fa3 and same zero-copy performance as page_first)
--hicache-mem-layout page_first_direct
# Layer-first
--hicache-mem-layout layer_first

레이아웃 호환성 (Layout Compatibility):

  • page_first: kernel I/O 백엔드에서만 호환되며, direct 백엔드에서는 자동으로 layer_first로 전환됨
  • page_first_direct: direct I/O 백엔드를 위해 최적화된 메모리 구성을 갖춘 전용 모드

이기종 TP 지원 (GQA/MHA 모델) (Heterogeneous TP Support)

HiCache 스토리지는 서로 다른 배포가 서로 다른 TP 크기(예: tp=4, tp=8)를 사용하고 동일한 스토리지 백엔드 네임스페이스를 공유할 때 교차 클러스터 KV 재사용을 지원합니다.

--hicache-storage-backend-extra-config에서 tp_lcm_size를 사용하세요:

# Example: heterogeneous TP = {4, 8}, so lcm = 8
--hicache-storage-backend-extra-config '{"tp_lcm_size": 8}'

가이드라인:

  • tp_lcm_size는 동일한 HiCache 스토리지를 공유할 모든 TP 크기의 최소공배수(LCM)로 설정하세요.
  • Mooncake와 page_head 레이아웃을 쓰는 MHA 모델의 경우, HiCache는 tp_lcm_size에 따라 헤드 샤드를 분할해 이기종 TP 배포에서 키를 재사용 가능하게 합니다.
  • 모든 클러스터가 동일한 TP 크기를 쓰면 이 옵션은 필요 없습니다.

프리페치 정책 (Prefetch Policies)

# Best-effort: Terminate prefetch when needed
--hicache-storage-prefetch-policy best_effort
# Wait-complete: Ensure complete prefetch, higher cache reuse
--hicache-storage-prefetch-policy wait_complete
# Timeout: Balance between completion and best-effort
--hicache-storage-prefetch-policy timeout

PD 분리(Disaggregation)와의 통합 (Integration with PD Disaggregation)

HiCache는 PD Disaggregation과 완벽하게 연동됩니다. 두 가지 구성을 선택할 수 있어요:

  1. Prefill 전용 HiCache (Prefill-only HiCache): Prefill 노드에서만 HiCache를 켜 Prefill 인스턴스 간 KV 캐시 공유를 허용
  2. 비동기 오프로딩이 있는 전체 HiCache (Full HiCache with async offloading): Prefill 노드에 HiCache를, Decode 노드에 비동기 KV 캐시 오프로딩을 켜 다중 턴 대화 시나리오에서 Prefill 노드가 Decode 노드의 KV 캐시를 재사용할 수 있게
# Prefill node with HiCache enabled for cross-prefill sharing (ideal for SystemPrompt scenarios)
python3 -m sglang.launch_server \
  --model-path /xxx/DeepSeek-R1/ \
  --tp 8 \
  --host 0.0.0.0 \
  --port 10000 \
  --enable-metrics \
  --enable-cache-report \
  --mem-fraction-static 0.85 \
  --page-size 64 \
  --enable-hierarchical-cache \
  --hicache-ratio 2 \
  --hicache-size 0 \
  --hicache-mem-layout page_first_direct \
  --hicache-io-backend direct \
  --hicache-write-policy write_through \
  --hicache-storage-backend hf3fs \
  --hicache-storage-prefetch-policy wait_complete \
  --disaggregation-ib-device mlx5_0 \
  --disaggregation-mode prefill \
  --disaggregation-transfer-backend mooncake

# Decode node with async offloading enabled for KV cache reuse by Prefill (ideal for multi-turn conversations)
python3 -m sglang.launch_server \
  --model-path /xxx/DeepSeek-R1/ \
  --tp 8 \
  --host 0.0.0.0 \
  --port 10000 \
  --enable-metrics \
  --enable-cache-report \
  --page-size 64 \
  --hicache-ratio 2 \
  --hicache-size 0 \
  --hicache-mem-layout page_first_direct \
  --hicache-io-backend direct \
  --hicache-write-policy write_through \
  --hicache-storage-backend hf3fs \
  --hicache-storage-prefetch-policy wait_complete \
  --disaggregation-decode-enable-offload-kvcache \  # Enable async KV cache offloading in decode node
  --disaggregation-ib-device mlx5_0 \
  --disaggregation-mode decode \
  --disaggregation-transfer-backend mooncake

HF3FS로 배포 (Deployment with HF3FS)

다음은 HiCache-HF3FS로 DeepSeek-R1을 배포하는 예시입니다. 자세한 내용은 HF3FS Documentation을 참고하세요.

python3 -m sglang.launch_server \
  --model-path /xxx/DeepSeek-R1/ \
  --log-level info \
  --tp 8 \
  --host 0.0.0.0 \
  --port 10000 \
  --enable-metrics \
  --enable-cache-report \
  --page-size 64 \
  --mem-fraction-static 0.85 \
  --enable-hierarchical-cache \
  --hicache-ratio 2 \
  --hicache-size 0 \
  --hicache-mem-layout page_first_direct \
  --hicache-io-backend direct \
  --hicache-write-policy write_through \
  --hicache-storage-backend hf3fs \
  --hicache-storage-prefetch-policy wait_complete \

Mooncake로 배포 (Deployment with Mooncake)

다음은 Mooncake로 Qwen3-235B-A22B-Instruct-2507을 배포하는 예시입니다. 자세한 내용은 Mooncake Documentation을 참고하세요.

# Set Mooncake environment variables
export MOONCAKE_TE_META_DATA_SERVER="http://127.0.0.1:8080/metadata"
export MOONCAKE_GLOBAL_SEGMENT_SIZE=816043786240
export MOONCAKE_PROTOCOL="rdma"
export MOONCAKE_DEVICE="$DEVICE_LIST"
export MOONCAKE_MASTER=127.0.0.1:50051

# Launch SGLang server with Mooncake backend
python3 -m sglang.launch_server \
  --model-path $MODEL_PATH \
  --tp 8 \
  --page-size 64 \
  --enable-hierarchical-cache \
  --hicache-ratio 2 \
  --hicache-mem-layout page_first_direct \
  --hicache-io-backend direct \
  --hicache-storage-backend mooncake \
  --hicache-write-policy write_through \
  --hicache-storage-prefetch-policy timeout

커스텀 스토리지 백엔드 통합 (Custom Storage Backend Integration)

새 스토리지 백엔드를 통합하려면:

  1. 세 가지 핵심 메서드 구현:

    • get(key): 키로 값 조회
    • exists(key): 키 존재 확인
    • set(key, value): 키-값 쌍 저장

  2. 백엔드 등록: 스토리지 백엔드를 HiCache BackendFactory에 추가

HiCache 컨트롤러가 모든 스케줄링과 동기화를 자동으로 처리합니다.

동적 백엔드 로딩 (Dynamic Backend Loading)

또는 동적 로딩을 사용해 저장소에 백엔드를 하드코딩하지 않을 수 있습니다:

python3 -m sglang.launch_server \
  --model-path your-model \
  --enable-hierarchical-cache \
  --hicache-storage-backend dynamic \
  --hicache-storage-backend-extra-config '{"backend_name":"custom_backend_name", "module_path": "your_module_path", "class_name": "YourHiCacheClassName"}'

설정 파라미터 (Configuration Parameters):

  • --hicache-storage-backend: dynamic으로 설정
  • --hicache-storage-backend-extra-config: 다음을 포함한 JSON 설정
    • backend_name: 커스텀 백엔드 식별자
    • module_path: 구현체의 Python 모듈 경로
    • class_name: HiCache 구현 클래스명
    • interface_v1: batch_get_v1·batch_set_v1 메서드 사용 제어를 위한 0(비활성) 또는 1(활성)

커뮤니티와 지원 (Community and Support)

  • GitHub Issues: 버그와 기능 요청 보고
  • Slack Channel: #sgl-kv-cache-store에서 커뮤니티 토론 참여
  • Documentation: 스토리지 백엔드별 가이드 참조

이 문서는 커뮤니티 피드백과 새 기능에 따라 지속적으로 업데이트됩니다. 기여와 제안을 환영합니다!

더 알아보기 (Learn more)