세션 인지 라디스 캐시

세션 인지 라디스 캐시 (Session-Aware Radix Cache)

멀티 턴으로 오래 이어지는 대화나 에이전트 워크로드에서는 프롬프트 앞부분이 매번 비슷해요. 그런데 메모리가 빠듯하면 재사용 가능한 KV가 다른 요청에 밀려 캐시에서 나가버리고, 다음 턴에서 또 다시 앞부분을 계산하게 돼요. 세션 인지 라디스 캐시는 이 경우 캐시 적중률을 높이기 위한 기능이에요.

출처: 공식문서

무엇이 다를까요

이 캐시는 재사용 가능한 KV를 세션에 등록해 두고, 활성 세션이 아직 참조 중인 KV를 먼저 보호해요. 즉 참조되지 않은 KV를 먼저, 나중에 참조 중인 KV를 내보낸다는 우선순위로 동작해요.

단, 세션 참조는 "부드러운 보호(soft protection)"이지 메모리 고정(pin)이 아니에요. 참조 중인 KV를 빼도 부족할 만큼 메모리가 빠듯하면 참조 중인 KV도 내보내질 수 있어요.

캐시 켜기

이 기능은 UnifiedRadixCache에서만 구현돼요.

SGLANG_ENABLE_UNIFIED_RADIX_TREE=1 python3 -m sglang.launch_server \
  --model-path MODEL_PATH \
  --enable-session-radix-cache

세션 전달과 종료

애플리케이션은 한 세션의 모든 요청에 **같은 최상위 session_id**를 넘겨야 해요. 이 ID는 캐시 참조를 라벨링할 뿐, 대화 맥락을 붙이거나 재구성하지 않아요. 그래서 각 요청에 의도한 프롬프트 전체를 계속 포함해야 해요.

curl http://localhost:30000/generate \
  -H "Content-Type: application/json" \
  -d '{
    "text": "FULL_PROMPT_FOR_THIS_TURN",
    "sampling_params": {"max_new_tokens": 128},
    "session_id": "agent-42"
  }'

요청이 끝나면 SGLang이 그 요청의 재사용 가능한 캐시 잎을 자동으로 session_id 아래 등록해요. 이 방식은 참조만 하므로 /open_session 호출이 필요 없어요.

애플리케이션 세션이 끝나면 /close_session을 호출하세요. 에러나 취소 경로에서도 꼭요.

curl -X POST http://localhost:30000/close_session \
  -H "Content-Type: application/json" \
  -d '{"session_id": "agent-42"}'

세션을 닫으면 그 세션의 참조가 제거될 뿐, KV가 즉시 해제되지는 않아요. KV는 여전히 재사용 가능한 상태로 남아 일반적인 내보내기 순서로 돌아가요.

내보내기 동작 (Eviction)

캐시는 각 UnifiedRadixCache 컴포넌트별로 참조를 따로 추적해요. 디바이스/호스트 내보내기 모두 같은 세션 선호를 사용해요.

UnifiedRadixCache는 여전히 컴포넌트 연쇄 규칙을 적용해요. 내부 Full 노드를 내보내면 그 SWA·Mamba 데이터도 함께 내보내지고, SWA를 내보내면 Mamba 데이터도 내보내져요. 반면 Mamba만 내보내면 Mamba만 영향을 받아요. 잎(leaf)을 내보내면 그 잎의 모든 컴포넌트 데이터가 제거돼요.

더 알아보기 (Learn more)

• 라디스 캐시 내보내기 정책
• 양자화 KV 캐시