HiCache 스토리지 백엔드 런타임 attach/detach

HiCache 스토리지 백엔드 런타임 attach/detach (재시작 없음)

SGLang이 이미 실행 중이고 트래픽을 서빙하는 동안, 프로세스를 재시작하지 않고 HiCache L3 스토리지 백엔드(예: mooncake / hf3fs / nixl / file / aibrix / eic)를 동적으로 attach/detach 하는 방법을 설명합니다.

출처: 문서

본문

이 문서는 SGLang이 이미 실행 중이고 트래픽을 서빙하는 동안, 프로세스를 재시작하지 않고 HiCache L3 스토리지 백엔드(예: mooncake / hf3fs / nixl / file / aibrix / eic)를 동적으로 attach/detach 하는 방법을 설명합니다.

안전성과 일관성을 위해, 현재 구현은 엄격하게 이러한 작업이 서비스가 유휴(idle) 상태일 때만 일어나도록 요구합니다:

실행 중인 요청 없음
대기/큐에 있는 요청 없음

유휴 조건이 충족되지 않으면 API는 빠르게 실패(HTTP 400)하며 현재 서비스 상태를 수정하지 않습니다.

1. 배경과 구현 개요

1.1 아키텍처 / 제어 경로 (Architecture / control path)

제어 경로는 다음과 같습니다:

HTTP Server (python/sglang/srt/entrypoints/http_server.py)
- PUT /hicache/storage-backend, DELETE /hicache/storage-backend, GET /hicache/storage-backend 노출
TokenizerManager (python/sglang/srt/managers/tokenizer_control_mixin.py)
- FanOutCommunicator로 요청을 Scheduler에 전송
Scheduler (python/sglang/srt/managers/scheduler.py)
- 엄격한 유휴 검사 수행
- tree_cache.attach_storage_backend(...) / detach_storage_backend(...) 호출
UnifiedRadixCache (python/sglang/srt/mem_cache/unified_radix_cache.py)
- hicache_storage_backend_extra_config_json 파싱 (백엔드 설정과 프리페치 노브 모두 지원)
- cache_controller.attach_storage_backend(...) / detach_storage_backend(...) 호출
HiCacheController (python/sglang/srt/managers/cache_controller.py)
- (StorageBackendFactory로) 스토리지 백엔드 인스턴스 생성/파괴
- 런타임에 백엔드 백그라운드 스레드(프리페치/백업) 시작/중지

2. 유휴 상태 요구사항 (엄격)

Scheduler는 is_fully_idle()을 사용하며 다음을 검사합니다:

실행 중인 배치 없음 (chunked prefill, overlap, pipeline-parallel, disaggregation 경로 포함)
어떤 큐에도 대기 요청 없음 (waiting, grammar, disagg bootstrap/prealloc/transfer/inflight)
DLLM 스테이징 요청 없음

조건이 충족되지 않으면 attach/detach는 다음과 같은 오류를 반환합니다:

Reject attach: scheduler is not idle. #queue-req=... #running-req=...

전환 전에 업스트림 트래픽을 비우고 서버가 유휴 상태가 될 때까지 기다린 뒤 attach/detach를 호출하세요.

2.1 DP (데이터 병렬) 의미

dp_size > 1이면 tokenizer는 요청을 모든 DP 스케줄러 인스턴스로 디스패치하고 응답을 집계합니다:

최종 success는 모든 DP 랭크가 성공을 반환해야만 true
최종 message는 모든 DP 랭크의 메시지를 연결

이것은 "조용한 부분 성공(silent partial success)"을 방지하기 위한 것이지만, 다음과 같은 상황을 볼 수도 있음을 뜻합니다:

일부 랭크가 이미 성공했어도 전체 실패

현재 DP 랭크 전반에 걸친 자동 부분 롤백은 없습니다(코드의 TODO 참고). 운영상:

랭크 간 백엔드 설정을 동일하게 유지하는 것을 선호
attach가 실패하면 즉시 detach 호출(best-effort/idempotent), 설정 수정 후 attach 재시도

3. 사용 방법 (HTTP Admin API)

아래 예시는 SGLang HTTP 서버가 http://127.0.0.1:30000에 있다고 가정합니다.

3.1 현재 스토리지 백엔드 상태 조회

curl -s http://127.0.0.1:30000/hicache/storage-backend

예시 응답:

{
  "hicache_storage_backend": "mooncake",
  "hicache_storage_backend_extra_config": "{\"master_server_address\":\"127.0.0.1:50051\", ...}"
}

3.2 스토리지 백엔드 attach (활성화)

curl -s -X PUT http://127.0.0.1:30000/hicache/storage-backend \
  -H 'Content-Type: application/json' \
  -d '{
    "hicache_storage_backend": "mooncake"
  }'

curl -s -X PUT http://127.0.0.1:30000/hicache/storage-backend \
  -H 'Content-Type: application/json' \
  -d '{
    "hicache_storage_backend": "mooncake",
    "hicache_storage_backend_extra_config_json": "{\"master_server_address\":\"127.0.0.1:50051\",\"protocol\":\"tcp\",\"global_segment_size\":\"4gb\",\"prefetch_threshold\":256}",
    "hicache_storage_prefetch_policy": "timeout"
  }'

참고:

hicache_storage_backend_extra_config_json은 다음을 모두 포함할 수 있습니다:
- 백엔드 설정 (예: Mooncake master/metadata/protocol 등)
- 프리페치 설정 (prefetch_threshold, prefetch_timeout_base, prefetch_timeout_per_ki_token, prefetch_timeout_max, hicache_storage_pass_prefix_keys)

3.3 스토리지 백엔드 detach (비활성화)

curl -s -X DELETE http://127.0.0.1:30000/hicache/storage-backend

참고:

Detach는 SGLang이 L3 스토리지 백엔드 사용을 중단하고 프리페치/백업 스레드를 중지하게만 함
Mooncake/HF3FS(또는 다른 원격 백엔드)에 저장된 데이터를 자동으로 삭제하지는 않음

4. 동작과 주의사항

재시작 불필요: attach/detach는 런타임에 프로세스 내에서 전환됨
유휴해야 함: 그렇지 않으면 일관성 문제를 피하기 위해 요청이 거부됨
호스트 KV 레이아웃 제약이 여전히 적용됨: 예를 들어 Mooncake는 여전히 page_first/page_first_direct/page_head 같은 레이아웃을 요구합니다. 서버의 HiCache 호스트 메모리 레이아웃이 백엔드 요구사항을 충족하지 않으면 attach는 오류로 실패합니다
관측성 (Observability):
- attach 후 server_args.hicache_storage_backend*가 tokenizer와 scheduler 양쪽에서 갱신됨
- 메트릭이 활성화되어 있으면 attach가 UnifiedRadixCache에서 스토리지 메트릭 수집기를 주문형으로 생성함

HiCache 스토리지 백엔드 런타임 attach/detach