From 0cf01e63ae4f8c388d7698f77db067789962b007 Mon Sep 17 00:00:00 2001 From: Juwon Hwang <74857614+juwon8891@users.noreply.github.com> Date: Sun, 23 Aug 2026 22:36:31 +0900 Subject: [PATCH 1/2] =?UTF-8?q?docs(lmcache):=20MP=20=EB=AA=A8=EB=93=9C=20?= =?UTF-8?q?=EC=84=A4=EC=A0=95=EA=B3=BC=20K8s=20=EB=B0=B0=ED=8F=AC=20?= =?UTF-8?q?=ED=98=95=ED=83=9C=20=EB=B3=B4=EA=B0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 실제 설정 예시가 없어 형제 문서와 깊이가 불균형한 점을 보완한다. - vLLM 연동 설정 섹션 신설: 권장 실행 모드인 MP(multiprocess) 모드 기준으로 lmcache server 기동 명령, LMCacheMPConnector 접속 설정, 주요 서버 플래그 표. vLLM 0.20.0 기준 kv_connector_module_path 지정 필요 여부를 warning으로 명시 - 저장 백엔드 선택 섹션 신설: --l2-adapter 방식과 지원 어댑터 type 분류표. 공유 범위(노드 로컬 vs 클러스터)를 선택 기준으로 제시 - K8s 배포 형태 섹션 신설: 공식 가이드의 DaemonSet + Deployment 패턴과 --supported-transfer-mode 별 요구사항 차이. hostNetwork·/dev/shm 이 PSS baseline·restricted에서 금지되는 항목이라 요구 권한이 채택 가능 여부를 결정할 수 있는 점, 그리고 engine_driven + pickle 전송으로 /dev/shm 의존을 제거할 수 있는 점을 함께 명시 - LMCache MP의 L1·L2가 문서 상단 그림의 계층 표기와 다른 축임을 info로 구분 - 참고 자료에 MP 모드 개요·설정 레퍼런스·배포 가이드 추가 설정 키와 플래그는 LMCache 공식 문서(2026-08 확인) MP 모드 기준이다. 기존 in-process 모드는 공식 문서상 legacy로 분류되어 채택하지 않았다. --- .../inference-optimization/lmcache.md | 119 +++++++++++++++++- 1 file changed, 116 insertions(+), 3 deletions(-) diff --git a/docs/agentic-ai-platform/model-serving/inference-optimization/lmcache.md b/docs/agentic-ai-platform/model-serving/inference-optimization/lmcache.md index 0938d33d..7c740f91 100644 --- a/docs/agentic-ai-platform/model-serving/inference-optimization/lmcache.md +++ b/docs/agentic-ai-platform/model-serving/inference-optimization/lmcache.md @@ -3,9 +3,9 @@ title: "LMCache: KV 캐시 오프로딩과 공유" description: GPU 메모리 너머 CPU·디스크로 KV 캐시를 오프로딩하고 추론 인스턴스 간 공유하는 LMCache의 개념과, vLLM prefix cache·NIXL·kvaware 라우팅과의 관계 created: "2026-06-25" last_update: - date: "2026-07-15" - author: YoungJoon Jeong -reading_time: 6 + date: "2026-08-23" + author: Juwon Hwang +reading_time: 11 tags: - lmcache - kv-cache @@ -63,6 +63,116 @@ flowchart LR KV 캐시는 접근 속도와 용량이 다른 계층에 단계적으로 저장됩니다. 가장 빠른 GPU HBM에서 밀려난 블록은 CPU DRAM으로, 다시 디스크·원격 스토리지로 내려가며, 재사용 시 역순으로 끌어올려집니다. +## vLLM 연동 설정 + +LMCache는 두 가지 실행 모드가 있고, **현재 권장은 MP(multiprocess) 모드**입니다. LMCache를 독립 서비스로 띄우고 vLLM 엔진이 ZMQ로 접속하는 구조로, 프로세스 격리·Pod 간 캐시 공유·GPU와 무관한 캐시 메모리 증설이 가능합니다. 기존 in-process 모드는 legacy로 분류되어 있습니다. + +먼저 LMCache 서버를 기동합니다. + +```bash +lmcache server \ + --l1-size-gb 100 \ + --eviction-policy LRU \ + --port 5555 \ + --http-port 8080 +``` + +ZMQ 포트(기본 5555)로 vLLM 엔진이 접속하고, HTTP 포트(기본 8080)는 Prometheus 호환 메트릭과 관리 API를 노출합니다. + +vLLM 쪽은 커넥터와 접속 정보를 지정합니다. + +```bash +vllm serve Qwen/Qwen3-8B \ + --port 8000 \ + --kv-transfer-config '{"kv_connector":"LMCacheMPConnector","kv_role":"kv_both","kv_connector_extra_config":{"lmcache.mp.host":"localhost","lmcache.mp.port":5555}}' +``` + +`lmcache.mp.server_urls`로 `"tcp://host1:6667,tcp://host2:6667"` 형태의 다중 서버를 지정할 수도 있습니다. + +:::warning vLLM 버전에 따라 커넥터 해석이 달라집니다 + +vLLM 0.20.0 이상에서는 `kv_connector_extra_config`에 `"kv_connector_module_path":"lmcache.integration.vllm.lmcache_mp_connector"`를 함께 지정해야 LMCache가 배포하는 구현을 사용합니다. 생략하면 vLLM에 벤더링된 버전이 선택되며, LMCache 배포판이 최신 서버 프로토콜과 수정사항을 먼저 반영합니다. + +vLLM 0.20.0 미만에서는 `LMCacheMPConnector`가 항상 vLLM 내장 커넥터로 해석되어, LMCache 배포판으로 우회할 방법이 없습니다. + +::: + +주요 서버 플래그는 다음과 같습니다. + +| 플래그 | 기본값 | 역할 | +|--------|--------|------| +| `--l1-size-gb` | (필수) | L1 캐시 풀 크기 (GB) | +| `--eviction-policy` | (필수) | `LRU` / `IsolatedLRU` / `noop` | +| `--chunk-size` | 256 | KV 청크당 토큰 수 | +| `--hash-algorithm` | `blake3` | `builtin` / `sha256_cbor` / `blake3` | +| `--eviction-trigger-watermark` | 0.8 | 축출을 시작하는 메모리 사용률 | +| `--max-workers` | 1 | 워커 수 (`--max-gpu-workers`·`--max-cpu-workers`로 개별 지정) | + +:::tip 해시 재현성이 필요한 경우 + +`--hash-algorithm builtin`을 쓸 때에만 프로세스 간 해시 재현성을 위해 `PYTHONHASHSEED`를 고정값으로 통일해야 합니다. 기본값 `blake3`에는 해당하지 않습니다. + +::: + +## 저장 백엔드 선택 + +MP 모드에서 L1은 LMCache 서버가 보유한 캐시 풀이고, 그 아래 L2 계층은 `--l2-adapter`에 JSON을 넘겨 붙입니다. 어댑터는 여러 개 지정해 캐스케이드로 구성할 수 있습니다. + +```bash +lmcache server --l1-size-gb 100 --eviction-policy LRU \ + --l2-adapter '{"type": "nixl_store", "backend": "POSIX", "backend_params": {"file_path": "/data/ssd/l2"}, "pool_size": 64}' +``` + +지원하는 어댑터 `type`은 다음과 같습니다. + +| 분류 | `type` 값 | +|------|-----------| +| 로컬 파일시스템·블록 | `fs`, `fs_native`, `nixl_store`, `raw_block`, `dax` | +| 분산 KV 스토어 | `mooncake_store`, `aerospike` | +| Redis 계열 | `resp`, `valkey` | +| 객체·관리형 스토리지 | `s3`, `bigtable`, `hfbucket`, `sagemaker-hyperpod` | +| 확장·테스트 | `plugin`, `native_plugin`, `mock`, `fault_inject` | + +백엔드 선택 기준은 성능만이 아니라 **공유 범위**입니다. 노드 로컬 파일시스템은 같은 노드의 Pod까지만 캐시를 공유하고, 스케일아웃 후에도 캐시를 재사용하려면 `mooncake_store`·`resp`·`s3` 같은 클러스터 범위 백엔드가 필요합니다. 저장 정책은 `--l2-store-policy`(`default`|`skip_l1`), 프리페치는 `--l2-prefetch-policy`(`default`|`retain`)로 제어하며, 백엔드별 필수 파라미터는 [MP Configuration Reference](https://docs.lmcache.ai/mp/configuration.html)를 참조하세요. + +:::info 계층 명칭 주의 + +LMCache MP 모드의 L1·L2는 **LMCache 서버 내부의 계층 명칭**으로, 위 그림에서 표기한 L1(GPU HBM)·L2(CPU DRAM)·L3와는 다른 축입니다. 위 그림의 GPU HBM은 vLLM이 직접 관리하는 영역입니다. + +::: + +## K8s 배포 형태 + +공식 배포 가이드는 sidecar가 아니라 **DaemonSet + Deployment 패턴**을 권장합니다. 노드당 LMCache 서버 하나(DaemonSet)를 같은 노드의 여러 vLLM Pod(Deployment)가 공유하는 구조입니다. + +| 항목 | 내용 | +|------|------| +| `hostNetwork: true` | 공식 DaemonSet 패턴이 사용. vLLM Pod은 Service DNS가 아니라 `status.hostIP`로 서버를 찾음 | +| `/dev/shm` 호스트 마운트 | 공식 예시는 양쪽 컨테이너에 마운트. **전송 경로에 딸린 조건**이며 아래 조합으로 제거 가능 | +| GPU 리소스 | DaemonSet에는 GPU를 요청하지 않음. 단 IPC 전송을 위해 컨테이너 런타임이 GPU 접근을 제공하므로 GPU 노드에만 스케줄해야 하며, GPU 없는 노드에서는 CUDA 초기화 오류로 크래시 | + +### 전송 경로에 따라 요구사항이 달라집니다 + +`--supported-transfer-mode`가 서버에 어떤 전송 경로를 적재할지 결정합니다. + +| 모드 | 경로 | 용도 | +|------|------|------| +| `auto` (기본) | 양쪽 적재 | 어느 디바이스 타입 워커든 접속 가능 | +| `lmcache_driven` | 서버 주도 — CUDA 디바이스는 IPC, CPU 디바이스는 SHM | GPU 직결 전송 | +| `engine_driven` | 엔진(워커) 주도 | CPU-only·비CUDA 가속기 워커 | + +`--shm-name`은 SHM 풀 동작을 제어하며, 빈 문자열이면 pickle 기반 전송을 사용합니다. 공식 문서는 이 조합이 **`/dev/shm`을 쓸 수 없는 환경이나 Docker에서 `--ipc host` 없이 돌릴 때 동작**한다고 명시합니다. + +:::warning 배포 전 admission 정책을 확인하세요 + +`hostNetwork: true`와 `/dev/shm` hostPath 마운트는 Pod Security Standards의 baseline·restricted 프로파일에서 금지되는 항목이며, Kyverno나 Validating Admission Policy로 동등한 제약을 걸어둔 클러스터에서도 차단됩니다. 즉 **요구 권한이 성능과 무관하게 채택 가능 여부를 결정**할 수 있습니다. + +다만 위 표처럼 요구사항은 전송 경로에 따라 달라집니다. 정책이 엄격한 클러스터라면 `engine_driven` + pickle 전송으로 `/dev/shm` 의존을 먼저 제거해볼 수 있습니다. 대신 서버 주도 경로의 GPU 직결 전송 이점은 포기하게 되며, 그 성능 차이는 워크로드에 따라 직접 측정해야 합니다. + +프로파일별 제약 내용은 [보안 & 거버넌스](../../../security-governance/index.md)의 워크로드 보안 절을 참조하세요. + +::: + ## 인접 기술과의 관계 LMCache는 단독으로 동작하지 않고 다른 추론 최적화 기술과 함께 쓰입니다. @@ -87,6 +197,9 @@ AWS 관리형 환경에서는 SageMaker HyperPod Inference Operator가 LMCache ### 공식 문서 - [LMCache GitHub](https://github.com/LMCache/LMCache) — LMCache 오픈소스 프로젝트 저장소 +- [LMCache MP Mode](https://docs.lmcache.ai/mp/index.html) — 권장 실행 모드 개요 +- [MP Configuration Reference](https://docs.lmcache.ai/mp/configuration.html) — 서버 플래그·L2 어댑터 전체 레퍼런스 +- [MP Deployment Guide](https://docs.lmcache.ai/mp/deployment.html) — K8s DaemonSet 배포 패턴 - [vLLM Documentation](https://docs.vllm.ai/) — vLLM 서빙 엔진 및 KV 캐시 관리 ### 논문 / 기술 블로그 From 402d96d5db5dca663c1d18cd0437f3668a1d1708 Mon Sep 17 00:00:00 2001 From: Juwon Hwang <74857614+juwon8891@users.noreply.github.com> Date: Thu, 27 Aug 2026 13:33:35 +0900 Subject: [PATCH 2/2] =?UTF-8?q?docs(lmcache):=20=EB=A6=AC=EB=B7=B0=20?= =?UTF-8?q?=EB=B0=98=EC=98=81=20=E2=80=94=20=EB=A7=81=ED=81=AC=C2=B7?= =?UTF-8?q?=EA=B8=B0=EB=B3=B8=EA=B0=92=20=EC=A0=95=EC=A0=95,=20=EC=96=B4?= =?UTF-8?q?=EB=8C=91=ED=84=B0/=ED=97=A4=EB=94=A9=20=EB=B3=B4=EC=99=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - security-governance 삭제로 끊긴 링크를 eks-best-practices/security-authn/index.md로 교체 - --supported-transfer-mode 기본값 표기를 auto → lmcache_driven으로 정정 - 8080(--http-port, 관리·헬스체크)과 9090(--prometheus-port, /metrics)을 분리 서술 - last_update.author를 원저자 병기 형태로 변경 - 어댑터 표에 nixl_store_dynamic 추가, "지원하는" → "주요"로 완화 - 문장형 헤딩 명사구화, MP 모드 서술에 문서 확인 시점(2026-08) 명시 --- .../inference-optimization/lmcache.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/agentic-ai-platform/model-serving/inference-optimization/lmcache.md b/docs/agentic-ai-platform/model-serving/inference-optimization/lmcache.md index 7c740f91..c68d1784 100644 --- a/docs/agentic-ai-platform/model-serving/inference-optimization/lmcache.md +++ b/docs/agentic-ai-platform/model-serving/inference-optimization/lmcache.md @@ -4,7 +4,7 @@ description: GPU 메모리 너머 CPU·디스크로 KV 캐시를 오프로딩하 created: "2026-06-25" last_update: date: "2026-08-23" - author: Juwon Hwang + author: YoungJoon Jeong · Juwon Hwang reading_time: 11 tags: - lmcache @@ -65,7 +65,7 @@ KV 캐시는 접근 속도와 용량이 다른 계층에 단계적으로 저장 ## vLLM 연동 설정 -LMCache는 두 가지 실행 모드가 있고, **현재 권장은 MP(multiprocess) 모드**입니다. LMCache를 독립 서비스로 띄우고 vLLM 엔진이 ZMQ로 접속하는 구조로, 프로세스 격리·Pod 간 캐시 공유·GPU와 무관한 캐시 메모리 증설이 가능합니다. 기존 in-process 모드는 legacy로 분류되어 있습니다. +LMCache는 두 가지 실행 모드가 있고, **현재 권장은 MP(multiprocess) 모드**입니다. LMCache를 독립 서비스로 띄우고 vLLM 엔진이 ZMQ로 접속하는 구조로, 프로세스 격리·Pod 간 캐시 공유·GPU와 무관한 캐시 메모리 증설이 가능합니다. 기존 in-process 모드는 legacy로 분류되어 있습니다. 아래 플래그·설정 키는 2026-08 기준 공식 문서와 대조한 내용이며, LMCache가 MP 모드의 최소 버전을 명시하지 않고 최신 dev 브랜치를 권장하므로 도입 시점에 다시 확인하세요. 먼저 LMCache 서버를 기동합니다. @@ -77,7 +77,7 @@ lmcache server \ --http-port 8080 ``` -ZMQ 포트(기본 5555)로 vLLM 엔진이 접속하고, HTTP 포트(기본 8080)는 Prometheus 호환 메트릭과 관리 API를 노출합니다. +ZMQ 포트(기본 5555)로 vLLM 엔진이 접속합니다. HTTP 포트(`--http-port`, 기본 8080)는 관리·헬스체크용 FastAPI 프런트엔드이고, Prometheus 메트릭은 별도의 `--prometheus-port`(기본 9090)가 `/metrics`로 노출합니다. vLLM 쪽은 커넥터와 접속 정보를 지정합니다. @@ -123,11 +123,11 @@ lmcache server --l1-size-gb 100 --eviction-policy LRU \ --l2-adapter '{"type": "nixl_store", "backend": "POSIX", "backend_params": {"file_path": "/data/ssd/l2"}, "pool_size": 64}' ``` -지원하는 어댑터 `type`은 다음과 같습니다. +주요 어댑터 `type`은 다음과 같습니다. | 분류 | `type` 값 | |------|-----------| -| 로컬 파일시스템·블록 | `fs`, `fs_native`, `nixl_store`, `raw_block`, `dax` | +| 로컬 파일시스템·블록 | `fs`, `fs_native`, `nixl_store`, `nixl_store_dynamic`, `raw_block`, `dax` | | 분산 KV 스토어 | `mooncake_store`, `aerospike` | | Redis 계열 | `resp`, `valkey` | | 객체·관리형 스토리지 | `s3`, `bigtable`, `hfbucket`, `sagemaker-hyperpod` | @@ -151,14 +151,14 @@ LMCache MP 모드의 L1·L2는 **LMCache 서버 내부의 계층 명칭**으로, | `/dev/shm` 호스트 마운트 | 공식 예시는 양쪽 컨테이너에 마운트. **전송 경로에 딸린 조건**이며 아래 조합으로 제거 가능 | | GPU 리소스 | DaemonSet에는 GPU를 요청하지 않음. 단 IPC 전송을 위해 컨테이너 런타임이 GPU 접근을 제공하므로 GPU 노드에만 스케줄해야 하며, GPU 없는 노드에서는 CUDA 초기화 오류로 크래시 | -### 전송 경로에 따라 요구사항이 달라집니다 +### 전송 경로별 요구사항 `--supported-transfer-mode`가 서버에 어떤 전송 경로를 적재할지 결정합니다. | 모드 | 경로 | 용도 | |------|------|------| -| `auto` (기본) | 양쪽 적재 | 어느 디바이스 타입 워커든 접속 가능 | -| `lmcache_driven` | 서버 주도 — CUDA 디바이스는 IPC, CPU 디바이스는 SHM | GPU 직결 전송 | +| `auto` | 양쪽 적재 | 어느 디바이스 타입 워커든 접속 가능 | +| `lmcache_driven` (기본) | 서버 주도 — CUDA 디바이스는 IPC, CPU 디바이스는 SHM | GPU 직결 전송 | | `engine_driven` | 엔진(워커) 주도 | CPU-only·비CUDA 가속기 워커 | `--shm-name`은 SHM 풀 동작을 제어하며, 빈 문자열이면 pickle 기반 전송을 사용합니다. 공식 문서는 이 조합이 **`/dev/shm`을 쓸 수 없는 환경이나 Docker에서 `--ipc host` 없이 돌릴 때 동작**한다고 명시합니다. @@ -169,7 +169,7 @@ LMCache MP 모드의 L1·L2는 **LMCache 서버 내부의 계층 명칭**으로, 다만 위 표처럼 요구사항은 전송 경로에 따라 달라집니다. 정책이 엄격한 클러스터라면 `engine_driven` + pickle 전송으로 `/dev/shm` 의존을 먼저 제거해볼 수 있습니다. 대신 서버 주도 경로의 GPU 직결 전송 이점은 포기하게 되며, 그 성능 차이는 워크로드에 따라 직접 측정해야 합니다. -프로파일별 제약 내용은 [보안 & 거버넌스](../../../security-governance/index.md)의 워크로드 보안 절을 참조하세요. +프로파일별 제약 내용은 [보안 & 거버넌스](../../../eks-best-practices/security-authn/index.md)의 워크로드 보안 절을 참조하세요. :::