KV 캐시 오프로딩¶

개요¶

Prefix caching은 KV 캐시가 NPU 디바이스 메모리에 남아 있는 동안에만 이를 재사용합니다. 디바이스 메모리는 계층 중 가장 작기 때문에, 한 번 evict된 프리픽스는 이후 요청에 같은 프리픽스가 포함되면 재계산해야 합니다.

KV 캐시 오프로딩은 요청을 처리하는 동안 재사용 가능한 KV 청크를 더 크고 느린 계층에 저장합니다. NPU 캐시에서 프리픽스가 evict된 뒤에도, 이후 요청은 이 계층에서 KV를 복원해 재계산을 줄일 수 있습니다. RBLN vLLM은 LMCache와 그 RBLN 확장인 lmcache-rbln을 통해 이를 지원합니다.

아키텍처¶

lmcache-rbln은 RBLN NPU를 위한 LMCache의 하드웨어 특화 확장입니다. 청크 분할, 조회, eviction 정책 같은 캐시 관리는 upstream lmcache 패키지에 의존하고, 디바이스에 닿는 부분만 대체합니다. NPU 메모리와 오프로드 계층 사이의 KV 캐시 전송, 그리고 NVMe 직접 스토리지용 저장 백엔드가 그 대상입니다.

RBLN vLLM은 이 확장의 connector인 RBLNLMCacheConnectorV1을 자신의 KV connector factory에 등록하므로, 다른 vLLM KV connector와 마찬가지로 --kv-transfer-config에서 이름으로 선택할 수 있습니다.

사전 준비 사항¶

해당 환경에서 패키지를 확인합니다.

1
2

python -m pip show vllm-rbln lmcache-rbln lmcache torch-rbln rebel-compiler
python -m pip check

Connector는 vllm model implementation에서 동작하므로 서버를 --model-impl vllm으로 기동합니다. 이 구현이 KV 캐시를 디바이스 텐서로 두며, connector가 지원하는 방식은 이것뿐입니다. Connector는 캐시를 device='rbln' 위의 torch 텐서로 전송합니다.

• 실행이 vllm model implementation으로 결정되지 않으면 RBLN vLLM이 RBLNLMCacheConnectorV1을 등록하는 모듈을 임포트하지 않으므로, 엔진 기동이 connector 이름 검증 단계에서 Unsupported connector type: RBLNLMCacheConnectorV1로 실패합니다. auto는 optimum-rbln이 지원하는 아키텍처에 transformers를 고르므로, vLLM 구현을 확실히 사용하려면 --model-impl vllm을 지정해야 합니다.
• PYTHONHASHSEED는 고정된 값으로 설정해야 합니다. 설정하지 않으면 vLLM이 블록 해시 체인의 기준값을 프로세스별 난수로 만들어, 스케줄러와 워커 사이에서 해시 체인이 갈라지고 모든 캐시 조회가 miss합니다. Connector는 조용히 실패하는 대신 생성 시점에 RuntimeError로 거부합니다. vLLM은 이 변수의 문자열을 해시해 체인의 시드로 쓰므로, 고정된 값이면 무엇이든 동작합니다.

1
2

systemctl status rebellions-rds-binding.service --no-pager
journalctl -u rebellions-rds-binding.service -b --no-pager

1

python -c 'from rebel import rds; print("RDS available:", rds.is_available()); print("RDS devices:", rds.query_available_device_count())'

설정¶

캐시는 LMCache의 LMCACHE_* 환경 변수로 설정하고, connector는 --kv-transfer-config로 선택합니다. 저장 계층을 고르고 아래 설정을 확인한 뒤, 서버 기동의 전체 블록을 복사해 실행합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

export PYTHONHASHSEED=0
export LMCACHE_LOCAL_CPU=True
export LMCACHE_MAX_LOCAL_CPU_SIZE=5.0
export LMCACHE_CHUNK_SIZE=1024
export LMCACHE_USE_LAYERWISE=False

vllm serve Qwen/Qwen3-1.7B \
  --model-impl vllm \
  --max-model-len 8192 \
  --block-size 1024 \
  --enable-prefix-caching \
  --max-num-batched-tokens 128 \
  --max-num-seqs 4 \
  --kv-transfer-config \
  '{"kv_connector":"RBLNLMCacheConnectorV1", "kv_role":"kv_both"}'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

export PYTHONHASHSEED=0
export LMCACHE_LOCAL_CPU=False
export LMCACHE_MAX_LOCAL_CPU_SIZE=0
export LMCACHE_CHUNK_SIZE=1024
export LMCACHE_USE_LAYERWISE=False
export LMCACHE_STORAGE_PLUGINS=RDSBackend
export LMCACHE_EXTRA_CONFIG='{
    "storage_plugin.RDSBackend.module_path": "lmcache_rbln.storage_plugin.rds_backend",
    "storage_plugin.RDSBackend.class_name": "RDSBackend",
    "rds_buffer_size": 2048,
    "rds_failure_policy": "ignore"
}'

vllm serve Qwen/Qwen3-1.7B \
  --model-impl vllm \
  --max-model-len 8192 \
  --block-size 1024 \
  --enable-prefix-caching \
  --max-num-batched-tokens 128 \
  --max-num-seqs 4 \
  --kv-transfer-config \
  '{"kv_connector":"RBLNLMCacheConnectorV1", "kv_role":"kv_both"}'

오프로딩 동작 확인¶

기동, 저장, 복원 로그를 먼저 확인합니다.

복원을 확인하려면 --no-enable-prefix-caching으로 서버를 시작한 뒤, 한 청크보다 긴 같은 프롬프트를 두 번 보냅니다. /metrics의 vllm:external_prefix_cache_hits_total이 첫 요청 전보다 두 번째 요청 후에 커졌으면 두 번째 요청이 오프로드 계층의 KV를 재사용한 것입니다. RDS에서는 로그에 RDS batched write failed 오류 없이 Retrieved N out of N required tokens가 출력되는지도 확인합니다. 확인이 끝나면 prefix caching을 다시 켭니다. 가져온 토큰이 없을 때의 조치는 문제 해결에서 확인할 수 있습니다.

문제 해결¶

1

RDS batched write failed for 1 keys

제약 사항¶

• Sub-block prefix caching과 KV connector는 둘 다 full-block prefix cache hit을 연장하려 하므로, 스케줄러는 요청마다 둘 중 하나만 사용합니다. 더 많은 토큰을 확보하는 쪽이 선택되고, 같으면 sub-block이 우선합니다. 자세한 내용은 Prefix Caching에서 확인할 수 있습니다.