본문으로 건너뛰기

LMCache 코드 구조 분석 — Overview & storage_backend 진입

작성일: 2026-05-19 분석 대상: /home/ny/LMCache/

1. LMCache 최상위 레이아웃 (lmcache/)​

lmcache/
├── v1/                  ← 현재 활성 런타임 (모든 신규 개발은 여기)
├── integration/         ← vLLM / SGLang / TRT-LLM 어댑터
├── storage_backend/     ← 레거시 백엔드 (v1/storage_backend 로 대체됨)
├── cli/                 ← 커맨드라인 도구
├── tools/               ← 보조 스크립트
├── *.so                 ← C++ 확장 (c_ops, lmcache_fs, lmcache_redis, native_storage_ops)
└── connections.py / logging.py / observability.py / utils.py
  • v1/ 가 본체이고, 최상위 storage_backend/ 는 deprecated.
  • 분석 타깃은 lmcache/v1/storage_backend/.

2. lmcache/v1/ 내부 — 런타임의 큰 그림​

그룹모듈역할
엔진 코어cache_engine.py, cache_interface.py, manager.py, token_database.py, metadata.pyKV 캐시 라이프사이클 오케스트레이션
스토리지 계층storage_backend/GPU→CPU→Disk→S3/Redis/NIXL 계층형 백엔드 (오늘의 타깃)
메모리/할당memory_management.py, lazy_memory_allocator.py, pin_monitor.py버퍼/핀 메모리 관리
GPU 연동gpu_connector/, compute/, ec_engine.py디바이스 측 KV 이동·연산
프로세스간multiprocess/, mp_observability/, transfer_channel/, rpc/워커 ↔ 캐시 서버 IPC
분산/공유distributed/, cache_controller/, p2p_backend노드 간 KV 공유, disagg prefill
서버/APIserver/, api_server/, internal_api_server/, offload_server/, lookup_client/컨트롤 플레인
운영health_monitor/, check/, basic_check.py, periodic_thread.py, event_manager.py헬스/모니터링
플랫폼/플러그인platform/, plugin/, system_detection.py, standalone/환경 적응
설정/공통config.py, config_base.py, exceptions/, protocol.py, utils/설정·예외·프로토콜

설계 문서(docs/design/v1/)는 distributed, gpu_connector, mp_observability, multiprocess, platform 만 존재하며, storage_backend/ 디자인 doc 디렉토리는 아직 없음. 즉 코드와 docstring 위주로 파야 함.

3. lmcache/v1/storage_backend/ 구조 (라인수 기준)​

storage_backend/
├── abstract_backend.py        460   ← 공통 인터페이스 (StorageBackendInterface)
├── storage_manager.py        1371   ← 백엔드 오케스트레이션 (계층 관리)
├── __init__.py                316   ← 백엔드 팩토리/등록
│
├── local_cpu_backend.py       886   ← L1: pinned CPU 메모리
├── local_disk_backend.py      673   ← L2: 로컬 디스크
├── remote_backend.py          625   ← L3: Redis/S3 등 원격
├── gds_backend.py            1227   ← GPUDirect Storage
├── nixl_storage_backend.py   1662   ← NIXL 백엔드
├── maru_backend.py            735
├── p2p_backend.py             788   ← 노드 간 P2P
├── pd_backend.py             1085   ← prefill/decode disaggregation
├── pd_backend_async.py       1664   ← 동상, async 버전
├── audit_backend.py           233   ← 데코레이터 (정합성 검증)
│
├── connector/                 ← 원격 백엔드용 transport (redis, s3 등)
├── naive_serde/               ← 직렬화/역직렬화
├── cache_policy/              ← eviction 정책 (LRU 등)
├── job_executor/              ← 비동기 작업 실행기
├── dax/                       ← DAX(persistent memory) 경로
├── raw_block/                 ← 블록 디바이스 직접 I/O
├── plugins/                   ← 외부 백엔드 플러그인
├── native_clients/            ← C++ 확장 클라이언트 래퍼
│
├── batched_message_sender.py  222
├── resp_client.py             227   ← RESP(Redis 프로토콜)
├── path_sharder.py            115   ← 디스크 경로 샤딩
└── storage_backend_listener.py 19

4. plugins/ vs 빌트인 백엔드 차이​

한 줄 요약: plugins/ = 동적으로 로드되는 "꽂아 쓰는" 백엔드, 나머지 = 코어에 하드코딩된 빌트인 백엔드.

4.1 인터페이스 계층 (abstract_backend.py)​

StorageBackendInterface           ← 공통 추상 (put/get/lookup …)         # line 27
 ├─ AllocatorBackendInterface     ← 자체 메모리 할당까지 책임           # line 325
 │     ↑ 빌트인 백엔드들 (CPU/Disk/Remote/GDS/NIXL …) 이 이쪽을 상속
 └─ StoragePluginInterface        ← plug-and-play 용 베이스              # line 424
       ↑ plugins/* 가 이쪽을 상속
       추가 인자: config, metadata, local_cpu_backend, loop

StoragePluginInterface docstring 그대로:

"implement when you want to add a storage backend in a configurable or plug and play fashion."

4.2 로딩 방식 차이 (storage_backend/__init__.py)​

함수동작대상
CreateStorageBackends() (line 111~)if config.enable_pd: ..., if config.local_cpu: ... 처럼 플래그 분기로 import + 인스턴스화빌트인 백엔드
storage_plugin_launcher() (line 40~)config.storage_plugins + extra_config.storage_plugin.<name>.module_path/class_name 를 읽어 importlib.import_module(...) 로 동적 로드plugin 백엔드

즉 plugin은 import 경로가 config 에 적혀 있어 LMCache 코드를 안 건드리고도 외부 패키지 클래스를 그대로 꽂을 수 있음.

4.3 dax/, raw_block/ 와의 관계​

dax/          ← DaxCore (실제 I/O 엔진, mmap/persistent memory 접근)
plugins/
 └─ dax_backend.py            ← DaxCore + LocalCPUBackend 를 StoragePluginInterface 로 노출

raw_block/    ← RawBlockCore (io_uring 기반 블록 디바이스 I/O)
plugins/
 └─ rust_raw_block_backend.py ← RawBlockCore 를 StoragePluginInterface 로 노출

즉 dax/, raw_block/ = 로우레벨 코어, plugins/* = 그 코어를 plugin 인터페이스에 맞춰 감싼 어댑터.

4.4 연구 목표 (FDP / HC-SSD / raw block 성능 개선 / io_uring)​

이 구조라면 LMCache 본체를 fork 하지 않고도 새 백엔드 = plugin 으로 등록 가능.

  • FDP (Flexible Data Placement): StoragePluginInterface 구현으로 새 백엔드를 추가. _write_one (Python) + pwrite_from_buffer (Rust) 에 placement_id 흘리는 경로 추가. NVMe IORING_OP_URING_CMD passthru 필요 (kernel 6.8+). 메타데이터 / 핫·콜드 슬롯 / cache_salt 기반 PLID 분류 정책 설계.
  • HC-SSD (High-Capacity SSD): 대용량 시 in-memory 인덱스(_index) 압박, 체크포인트 lock hold O(n), 단일 ring 처리량 한계 등 스케일 문제 해결. 인덱스 오프로드, 멀티 ring, meta_total_bytes 자동 산정 포함.
  • raw block 성능 개선: 기존 raw_block 구현의 성능 병목 개선. 주요 후보:
    • register_fixed_buffers 미사용 상태 해소 → zero-copy (WriteFixed/ReadFixed) 실제 활성화
    • _free_slots: list[int] O(n) 멤버십 체크 → set 교체
    • io_uring setup flag 튜닝 (setup_sqpoll, setup_single_issuer 등)
    • 단일 ring / 단일 worker → 멀티 ring 또는 queue depth 최적화
  • io_uring 개선: 이미 구현되어 있는 io_uring 경로 위에 추가 기능 및 성능 개선. 신규 구현이 아니라 기존 코드 확장:
    • IORING_OP_URING_CMD 로 NVMe passthru (FDP 연동)
    • setup flag 활성화 (setup_iopoll, setup_sqpoll 등) 효과 측정
    • register_fixed_buffers 실제 호출 경로 연결
    • multishot, registered file 등 미사용 기능 검토

5. 분석 타깃 (업데이트)​

연구 방향(FDP / HC-SSD / raw block 성능 개선 / io_uring 개선)에 가장 직접적으로 닿는 영역으로 타깃 재설정:

5.1 1순위 — lmcache/v1/distributed/l2_adapters/​

L2(원격/디스크 계층) 어댑터 모듈. 디자인 문서가 같이 있는 드문 영역이라 분석 효율이 높음.

lmcache/v1/distributed/l2_adapters/
├── base.py
├── config.py
├── factory.py
├── serde_wrapper.py
│
├── dax_l2_adapter.py
├── raw_block_l2_adapter.py
├── plugin_l2_adapter.py
├── native_plugin_l2_adapter.py
├── native_connector_l2_adapter.py
├── nixl_store_l2_adapter.py
├── nixl_store_dynamic_l2_adapter.py
├── mooncake_store_l2_adapter.py
├── fs_l2_adapter.py
├── fs_native_l2_adapter.py
├── s3_l2_adapter.py
├── resp_l2_adapter.py
└── mock_l2_adapter.py

docs/design/v1/distributed/l2_adapters/
├── overall.md
├── plugin.md
├── dax.md
├── raw_block.md
├── nixl_store.md
├── l2_eviction.md
├── l2_per_user_quota.md
└── serde_wrapper.md

5.2 2순위 — lmcache/v1/storage_backend/plugins/​

StoragePluginInterface 구현 레퍼런스 (2개).

plugins/
├── dax_backend.py              (917 lines)
└── rust_raw_block_backend.py   (585 lines)

5.3 3순위 — lmcache/v1/storage_backend/raw_block/​

io_uring 기반 블록 디바이스 I/O 코어. 새 백엔드 작성 시 의존하게 될 로우레벨 엔진.

raw_block/
├── core.py
├── key_codec.py
└── __init__.py

진입 권장 순서​

  1. docs/design/v1/distributed/l2_adapters/overall.md — L2 어댑터 전체 그림
  2. distributed/l2_adapters/base.py + factory.py — 어댑터 계약과 등록 흐름
  3. docs/design/v1/distributed/l2_adapters/plugin.md + plugin_l2_adapter.py — adapter ↔ plugin 연결
  4. docs/design/v1/distributed/l2_adapters/raw_block.md + raw_block_l2_adapter.py + storage_backend/raw_block/core.py + plugins/rust_raw_block_backend.py — raw_block 라인 전체 종단
  5. (참고) dax.md + dax_l2_adapter.py + dax/core.py + plugins/dax_backend.py — 같은 패턴으로 dax 라인 확인