26S16a

QK·2026년 9월 16일

MinIO AIStor의 MemKV(LLM 인퍼런스 환경에서 KV 캐시를 GPU HBM과 NVMe 간에 고속으로 캐싱/오프로드하는 분산 컨텍스트 메모리 스토어)를 단일 Bare-metal 노드(Co-located / Single-node 형태)에 테스트 목적으로 구성하는 사전 요건 및 절차 정리입니다.

1. 사전 요건 (Prerequisites)

MemKV는 아키텍처상 단일 노드 구성 시 Co-located with drives(전용 NVMe 디스크 직접 사용) 모드와 Co-located file-mode(일반 파일시스템 디렉토리 사용) 두 가지 방식을 지원합니다.

(1) 하드웨어 및 OS 요건

OS: 최신 Linux (Ubuntu 22.04+ / RHEL 9+ 등 x86_64 또는 aarch64)
커널: io_uring 및 O_DIRECT를 지원하는 최신 Linux 커널 (Linux 5.15 이상 권장)
스토리지 (택 1):
전용 드라이브 모드 (권장 테스트): OS 디스크와 분리된 비어 있는 raw NVMe SSD 1개 이상 (예: /dev/nvme1n1)
파일 모드 (간이 테스트): 전용 NVMe가 없는 경우 일반 마운트 경로(디렉터리) 사용 가능 (TCP 전송, 드라이브 포맷 불필요)

네트워크:
단일 노드 내부 loopback 통신 시에는 일반 NIC나 로컬 루프백 인터페이스로도 구동 가능합니다.
(선택/고성능 검증 시): Mellanox/NVIDIA ConnectX (mlx5) RDMA NIC (RoCEv2 / InfiniBand)

메모리 / HugePages:
RDMA 바운스 버퍼 가속을 위해 HugePages가 권장되나, 파일 모드 테스트 시에는 비활성화 가능.

(2) 소프트웨어 및 라이선스 요건

MinIO 라이선스 키 파일: minio.license (MinIO AIStor 라이선스 또는 평가판 라이선스 파일)
MemKV 바이너리 (memkv): 공식 패키지/바이너리
인증 키 (Auth Key): 클라이언트-서버 간 통신 검증용 32바이트(64자리 Hex) HMAC 키

2. 배포 및 구성 절차

라이선스 및 디렉터리 준비:
설정 파일과 라이선스가 위치할 기본 디렉터리를 생성하고 라이선스 파일을 배치합니다.

sudo mkdir -p /etc/memkv
sudo cp /path/to/minio.license /etc/memkv/minio.license

인증 키(Auth Key) 생성:
클라이언트와 서버가 공유할 32바이트(64 hex 문자) 인증 키를 생성합니다.

# 64자 Hex Key 생성
openssl rand -hex 32 | sudo tee /etc/memkv/auth.key

서버 설정 파일(config.yaml) 작성: 주의: 드라이브 지정 시 OS 디스크 제외 필수.
MemKV는 memkv setup 명령어로 시스템의 드라이브와 NIC를 자동 감지하여 설정을 뽑아낼 수 있습니다.

# 하드웨어 자동 감지 기반 템플릿 생성
memkv setup > /etc/memkv/config.yaml

또는 단일 노드 테스트 용도에 맞게 /etc/memkv/config.yaml을 수동 작성합니다:

[방법 A: Raw NVMe 디스크 모드 (성능 검증용)]

listen: "0.0.0.0:8500"
license: "/etc/memkv/minio.license"
auth_key: "<위에서 생성한 64자리 Hex 키>"

# 테스트할 raw NVMe 블록 디바이스 지정 (OS 디스크 포함 금지)
drives:
  - /dev/nvme1n1

[방법 B: 파일 모드 (전용 NVMe 없는 간이 개발/테스트용)]

listen: "0.0.0.0:8500"
license: "/etc/memkv/minio.license"
auth_key: "<위에서 생성한 64자리 Hex 키>"

# 파일시스템 디렉토리 기반 캐시 경로 지정
file_mode: true
storage_path: "/data/memkv_cache"

드라이브 초기화 (Raw NVMe 모드인 경우만 해당):
지정한 전용 NVMe 디바이스를 MemKV 전용 포맷으로 초기화합니다. (파일 모드인 경우 생략)

sudo memkv setup --force /dev/nvme1n1

MemKV 서버 실행: 백그라운드 실행 또는 systemd 등록 권장.
설정 파일과 라이선스를 지정하여 MemKV 데몬을 시작합니다.

# 포그라운드 실행 및 로그 확인
memkv start --config /etc/memkv/config.yaml --license /etc/memkv/minio.license

단일 노드 통신 검증:
MemKV 내장 CLI 도구를 사용하여 서버와 루프백 연결이 정상인지, 데이터 블록 write/read가 동작하는지 확인합니다.

# 연결 및 I/O 동작 검증
memkv verify --address 127.0.0.1:8500 --auth-key "$(cat /etc/memkv/auth.key)"

출력 결과에 VERIFIED 메시지가 나타나면 로컬 MemKV 인스턴스가 정상 작동하는 상태입니다.

3. 테스트 클라이언트 연동 (vLLM / LMCache 예시)

동일한 Bare-metal 머신에서 vLLM 또는 SGLang 등의 서빙 엔진을 실행할 때, 환경 변수 또는 엔진 설정 파일로 방금 띄운 로컬 MemKV를 바라보게 구성합니다:

# MemKV 클라이언트 구성 환경변수 설정
export MEMKV_SERVER="127.0.0.1:8500"
export MEMKV_AUTH_KEY="$(cat /etc/memkv/auth.key)"

vLLM + LMCache 사용 시: Python 패키지(memkv_lmcache)를 설치하고, LMCache의 저장소 백엔드 플러그인(Storage plugin)으로 MemKV를 등록하여 KV Cache 오프로딩/프롬프트 캐싱을 테스트할 수 있습니다.

vLLM과 로컬 MemKV 연동은 LMCache의 스토리지 플러그인(memkv-lmcache)을 통해 이루어집니다.

구조적으로 vLLM은 KV-Transfer 커넥터(LMCacheConnectorV1)를 통해 LMCache를 바라보고, LMCache가 MemKVStorageBackend 플러그인을 통해 로컬 MemKV 서버와 통신하여 NVMe/메모리에 KV 캐시(프롬프트 캐시)를 오프로드하고 재사용합니다.

1. 패키지 설치

Python 가상환경(vLLM 구동 환경)에 vLLM, LMCache 및 MemKV 플러그인을 설치합니다.

pip install vllm lmcache memkv-lmcache

2. 설정 파일 작성

(1) LMCache 설정 파일 생성 (`/etc/lmcache.yaml`)

LMCache가 MemKV 플러그인을 스토리지 백엔드로 로드하도록 구성합니다.

주의: MemKV 플러그인은 가져온 텐서를 스테이징하기 위해 로컬 CPU 할당자를 사용하므로 max_local_cpu_size는 반드시 0보다 커야 합니다.

# /etc/lmcache.yaml
chunk_size: 64
local_cpu: true
max_local_cpu_size: 5    # CPU 메모리 스테이징용 (GB 단위)

# MemKV 스토리지 플러그인 지정
storage_plugins: memkv

extra_config:
  storage_plugin.memkv.module_path: memkv_lmcache.backend
  storage_plugin.memkv.class_name: MemKVStorageBackend

3. 환경 변수 설정 (MemKV 연결 정보)

플러그인은 표준 MEMKV_* 환경 변수를 읽어 로컬 서버에 연결합니다. 단일 노드 로컬 바인딩(127.0.0.1:8500) 기준으로 설정합니다:

# 1. 로컬 MemKV 엔드포인트
export MEMKV_SERVERS="127.0.0.1:8500"

# 2. 서버 설정 시 생성했던 64자리 Hex 인증 키
export MEMKV_AUTH_KEY="$(cat /etc/memkv/auth.key)"

# 3. 라이선스 경로
export MEMKV_LICENSE="/etc/memkv/minio.license"

# 4. LMCache 설정 파일 경로 지정
export LMCACHE_CONFIG_FILE="/etc/lmcache.yaml"

# 5. vLLM KV Transfer 설정 (송수신 겸용)
export KV_TRANSFER_CONFIG='{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'

(참고: 로컬 TCP 루프백 테스트 시 RDMA 관련 변수는 지정하지 않아도 기본 소켓/TCP 레이어로 통신합니다.)

4. vLLM 서버 실행

환경 변수가 로드된 상태에서 vllm serve를 실행합니다.

vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --tensor-parallel-size 1 \
  --kv-transfer-config "$KV_TRANSFER_CONFIG"

정상 기동 확인 로그

서버 기동 시 표준 출력에서 다음 로그들이 순차적으로 출력되는지 확인합니다:

LMCache INFO: Created dynamic backend: memkv (LMCache가 플러그인을 정상 로드)
INFO Creating memkv engine config=PluginConfig ... (MemKV 엔진 초기화 및 서버 핸드셰이크 성공)

5. 동작 검증 테스트

별도 터미널에서 동일한 롱 프롬프트(수천 토큰 이상)를 2회 연속 요청하여 첫 번째 요청(Cache Miss)과 두 번째 요청(Cache Hit)의 TTFT(Time To First Token) 차이를 비교합니다.

# 1회차 요청 (KV 캐시 생성 및 MemKV로 Write)
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-3.1-8B-Instruct",
    "messages": [
      {"role": "system", "content": "너는 문서 분석 도우미야. 아래 내용을 요약해줘."},
      {"role": "user", "content": "<매우 긴 텍스트 본문...>"}
    ],
    "max_tokens": 50
  }'

# 2회차 동일 요청 (MemKV로부터 KV 캐시 복원 -> TTFT 대폭 단축 확인)

vLLM 콘솔 로그에서 두 번째 호출 시 GPU가 프롬프트를 재연산하지 않고 LMCache/MemKV를 통해 청크 단위로 가져와 즉시 토큰 생성을 시작하는 것을 확인할 수 있습니다.

engineer

이전 포스트

26S15c

다음 포스트

26S16a

1. 사전 요건 (Prerequisites)

(1) 하드웨어 및 OS 요건

(2) 소프트웨어 및 라이선스 요건

2. 배포 및 구성 절차

3. 테스트 클라이언트 연동 (vLLM / LMCache 예시)

1. 패키지 설치

2. 설정 파일 작성

(1) LMCache 설정 파일 생성 (`/etc/lmcache.yaml`)

3. 환경 변수 설정 (MemKV 연결 정보)

4. vLLM 서버 실행

정상 기동 확인 로그

5. 동작 검증 테스트

26S15c

26S21a

0개의 댓글

26S16a

1. 사전 요건 (Prerequisites)

(1) 하드웨어 및 OS 요건

(2) 소프트웨어 및 라이선스 요건

2. 배포 및 구성 절차

3. 테스트 클라이언트 연동 (vLLM / LMCache 예시)

1. 패키지 설치

2. 설정 파일 작성

(1) LMCache 설정 파일 생성 (/etc/lmcache.yaml)

3. 환경 변수 설정 (MemKV 연결 정보)

4. vLLM 서버 실행

정상 기동 확인 로그

5. 동작 검증 테스트

26S15c

26S21a

0개의 댓글

(1) LMCache 설정 파일 생성 (`/etc/lmcache.yaml`)