26O05a

Об этом предложении

MinIO memkv 문서를 먼저 확인하겠습니다.Quick Start 페이지를 확인하겠습니다.vLLM 연동 페이지도 확인하겠습니다.MinIO MemKV 공식 문서(Quick Start, vLLM 연동 페이지)를 기준으로 정리했습니다. 문서에 없어서 제가 보충한 내용은 [보충] 으로 표시했습니다. 0. 먼저 알아둘 점 MemKV 서버는 두 가지 형태가 있습니다. 형태 용도 스토리지 / 전송 Distributed full server (Linux) 운영용. 문서의 97.4 GiB/s 벤치마크가 이 형태입니다. NVMe raw 디바이스 + RDMA(DC, RC fallback) Single-node co-located 개발, 엣지, GPU 개발 박스 file 모드 + TCP (127.0.0.1) 3.5단계 스토리지 용도라면 distributed full server 가 맞습니다. 이 서버는 GPU 노드와 별도의 스토리지 노드(NVMe + RDMA NIC) 에 올리고, GPU 노드의 vLLM이 클라이언트로 접속하는 구성이 일반적입니다. 라이선스 제약 은 Free 티어가 distributed 형태에서 서버 1대로 제한되고, 다중 서버 scale-out은 Enterprise가 필요합니다. 파일럿은 Free로 1대부터 시작할 수 있습니다. 라이선스(JWT)는 min.io/pricing에서 발급받습니다. 1. Baremetal 설치 1-1. 사전 요구사항 (distributed full server) Linux kernel 6.8+ RDMA NIC: DC 고속 경로는 Mellanox mlx5 필요, RC fallback은 RoCE NIC이면 가능 NVMe 드라이브: MemKV 전용 이며 memkv setup 때 재포맷됩니다. Hugepages(2MiB) : 최소 memory.maxSize 이상이어야 하며, 부족하면 memkv start 가 실행을 거부합니다. 라이선스 파일 사전 점검 명령입니다. [보충] uname -r # 6.8 이상인지 ibv_devices # RDMA 디바이스명 확인 (예: mlx5_0) lsblk -d -o NAME,SIZE,MODEL # 전용 NVMe 식별 (OS 디스크 제외!) grep -i huge /proc/meminfo 1-2. Hugepages 예약 예를 들어 memory.maxSize 를 64 GiB로 잡으면 2 MiB 페이지 32768개가 필요합니다. [보충: 계산 및 영구화] sudo sysctl -w vm.nr_hugepages=32768 echo "vm.nr_hugepages=32768" | sudo tee /etc/sysctl.d/90-memkv.conf 1-3. 바이너리 설치 바이너리 하나에 서버, admin client, 문서 사이트가 모두 들어 있습니다. curl -LO https://dl.min.io/aistor/memkv/release/linux-amd64/memkv chmod +x memkv sudo mv memkv /usr/local/bin/ memkv --version linux-arm64 빌드도 있으며 URL만 바꾸면 됩니다. .deb / .rpm 패키지로 설치했다면 NIXL 플러그인은 /usr/lib/memkv/libplugin_MEMKV.so 에 이미 있습니다. 1-4. NIXL 플러그인 (Dynamo/NIXL 경로를 쓸 때만) vLLM + LMCache 경로에서는 필요 없고, NIXL 경로(Dynamo KVBM 등)에서만 필요합니다. sudo mkdir -p /opt/nvidia/nvda_nixl/lib/plugins sudo curl -L \ https://dl.min.io/aistor/memkv/release/linux-amd64/libplugin_MEMKV.so \ -o /opt/nvidia/nvda_nixl/lib/plugins/libplugin_MEMKV.so 설치 위치는 NIXL_PLUGIN_DIR 로 바꿀 수 있습니다. 1-5. 라이선스 배치 sudo mkdir -p /etc/memkv sudo install -m 0600 /path/to/minio.license /etc/memkv/minio.license 서버가 이 경로를 자동으로 인식하며, 다른 경로를 쓰려면 MEMKV_LICENSE=/path 를 지정합니다. 1-6. 드라이브 초기화 및 서버 설정 생성 ⚠️ 지정한 드라이브의 데이터가 모두 삭제 됩니다. 이미 초기화된 드라이브를 덮어쓰려면 --force 가 필요합니다. sudo memkv setup \ --drives /dev/nvme0n1 /dev/nvme1n1 /dev/nvme2n1 \ --rdma mlx5_0 \ | sudo tee /etc/memkv/config.yaml YAML이 stdout으로 출력되므로 반드시 파일로 리다이렉트해야 합니다. 생성된 network.auth_key 는 클라이언트와 공유하는 HMAC 키이니 따로 보관하세요. 전체 플래그는 CLI Reference( /operate/cli/#setup )에서 확인할 수 있습니다. 1-7. 서버 기동 및 확인 sudo memkv start --config /etc/memkv/config.yaml curl http://localhost:9901/v1/health # {"status":"healthy","rdma_active":true,"drives_online":3,"drives_offline":0,"drives_total":3} 포트는 데이터 플레인이 9900 , admin/health가 9901 (데이터 포트 + 1)입니다. rdma_active:true 와 drives_online == drives_total 을 확인하세요. 1-8. systemd 등록 [보충: 문서에 unit 파일은 없음] # /etc/systemd/system/memkv.service [Unit] Description=MinIO MemKV server After=network-online.target Wants=network-online.target [Service] ExecStart=/usr/local/bin/memkv start --config /etc/memkv/config.yaml Restart=on-failure LimitMEMLOCK=infinity LimitNOFILE=1048576 [Install] WantedBy=multi-user.target sudo systemctl daemon-reload && sudo systemctl enable --now memkv 1-9. 클라이언트(GPU 노드) 설정 GPU 노드에 /etc/memkv/client.yaml 을 만들고 MEMKV_CONFIG 로 지정합니다. servers: - server-0.memkv.example.com:9900 rdma_devices: [mlx5_0, mlx5_1] transport: auto # rdma_devices가 있으면 RDMA, 없으면 TCP auth_key: <서버 config.yaml의 network.auth_key> license: /etc/memkv/minio.license export MEMKV_CONFIG=/etc/memkv/client.yaml yaml의 모든 값은 MEMKV_SERVERS , MEMKV_RDMA_DEVICES , MEMKV_AUTH_KEY , MEMKV_LICENSE 같은 환경변수로 덮어쓸 수 있습니다. (참고) 단일 노드 co-located / file 모드 GPU 개발 박스에서 빠르게 테스트할 때 쓰는 형태입니다. 운영용은 아닙니다. sudo mkdir -p /etc/memkv /var/lib/memkv openssl rand -hex 32 | sudo tee /etc/memkv/auth_key >/dev/null sudo chmod 600 /etc/memkv/auth_key AUTH=$(sudo cat /etc/memkv/auth_key) sudo tee /etc/memkv/config.yaml >/dev/null <<EOF network: address: 127.0.0.1:9900 auth_key: "$AUTH" memory: block_size: 2 MiB max_size: 1 GiB storage: mode: file block_size: 4 MiB drives: - media: /var/lib/memkv/drive0.dat max_size: 16 GiB EOF sudo memkv start --config /etc/memkv/config.yaml 이 경우 클라이언트는 transport: tcp , servers: [127.0.0.1:9900] 로 설정합니다. 2. Kubernetes 설치 차트는 deploy/helm/memkv , 이미지는 quay.io/minio/memkv 입니다. StatefulSet으로 서버 1개당 Pod 1개 가 뜨고, hard pod-anti-affinity로 노드마다 하나씩 배치됩니다. 차트 소스를 어디서 받는지는 문서에 명시돼 있지 않으니 MinIO 다운로드 페이지( dl.minio.io/aistor/memkv/ )나 담당 채널에서 확인이 필요합니다. 2-1. 사전 요구사항 Kubernetes 1.27+ 스토리지 노드마다 RDMA NIC 노드별 hugepages 예약 (kubelet이 hugepages-2Mi 리소스를 인식해야 합니다) [보충] 라이선스 이 조건은 values.schema.json 으로 설치 시점에 검증됩니다. NVMe를 쓸 스토리지 노드에는 라벨/테인트를 걸어두면 편합니다. [보충] kubectl label node <node> memkv.minio.io/storage=true 2-2. NVMe용 raw block PV 사전 생성 (권장 모드) MemKV는 raw block 디바이스에 직접 기록하므로, 기본 모드( drives.mode: blockDevice )는 드라이브마다 PVC를 하나씩 만들어 local PV에 바인딩합니다. PV의 nodeAffinity 덕분에 Pod가 해당 호스트로 자동 고정됩니다. deploy/helm/memkv/examples/local-pv-example.yaml 을 환경에 맞게 수정한 뒤 적용합니다. kubectl apply -f deploy/helm/memkv/examples/local-pv-example.yaml StorageClass 이름은 아래 설치 명령의 memkv-local 과 맞춰야 합니다. 2-3. 라이선스 Secret kubectl create namespace memkv kubectl -n memkv create secret generic memkv-license \ --from-file=license=/path/to/minio.license 2-4. 차트 설치 (모드 3종) (A) 운영 권장: blockDevice helm install memkv deploy/helm/memkv \ --namespace memkv \ --set replicaCount=2 \ --set drives.blockDevice.count=12 \ --set drives.blockDevice.storageClass=memkv-local \ --set license.existingSecret=memkv-license \ --set config.memory.maxSize="64 GiB" \ --set hugepages.amount=64Gi replicaCount 가 서버(노드) 수이고, drives.blockDevice.count 는 노드당 드라이브 수입니다. Free 라이선스는 서버 1대 제한이므로 replicaCount=1 로 시작하세요. [보충] (B) hostDev 모드 (단일 테넌트, 편의용) 호스트 /dev 를 Pod에 bind-mount하고 /dev/nvmeXn1 을 직접 지정합니다. 차트가 Pod를 특정 노드에 고정해 주지 못하므로 nodeSelector 나 affinity 를 반드시 함께 지정해야 합니다. helm install memkv deploy/helm/memkv \ --namespace memkv \ --set drives.mode=hostDev \ --set 'drives.hostDev.devices={/dev/nvme0n1,/dev/nvme1n1}' \ --set 'nodeSelector.memkv\.minio\.io/storage=true' \ --set license.existingSecret=memkv-license (C) file 모드 (dev/kind/CI 전용) PVC 안의 일반 파일을 mmap해서 쓰므로 NVMe나 privileged init이 필요 없고, 성능은 호스트 파일시스템에 제한됩니다. 운영용은 아닙니다. helm install memkv deploy/helm/memkv \ --namespace memkv --create-namespace \ -f deploy/helm/memkv/ci/ci-values.yaml 2-5. 검증 kubectl -n memkv get pods -o wide # Pod가 서로 다른 노드에 배치됐는지 kubectl -n memkv get pvc -l app.kubernetes.io/instance=memkv # 전부 Bound인지 kubectl -n memkv port-forward svc/memkv-admin 9901:9901 curl http://127.0.0.1:9901/v1/health # {"status":"healthy","rdma_active":true,"drives_online":12,"drives_offline":0,"drives_total":12} vLLM Pod에서 접속할 서버 주소( MEMKV_SERVERS )는 StatefulSet의 Pod별 DNS 형태( memkv-0.<headless-svc>.memkv.svc:9900 등)가 될 가능성이 높습니다. 실제 서비스명은 kubectl -n memkv get svc 로 확인하세요. [보충] Prometheus 메트릭과 K8s probe는 문서의 Monitoring 페이지( /operate/monitoring/ )를 참고하세요. 3. vLLM(GPU 노드) 연동: 3.5단계 스토리지로 사용 문서상 vLLM 연결 방식은 세 가지입니다. 방식 vLLM 버전 구조 1 LMCache 플러그인 릴리스 버전 vLLM → LMCacheConnectorV1 → memkv_lmcache → MemKV 2 Native offloading 2차 티어 vLLM main vLLM 자체 CPU offload 풀 뒤에 MemKV 3 Direct (GPUDirect) vLLM main GPU 텐서 ↔ MemKV를 RDMA로 직접 이동 (CPU 풀 없음) 릴리스 vLLM에서는 1이 기본 경로이고, 3이 3.5단계 개념(GPU HBM → 네트워크 NVMe 직결)에 가장 가깝지만 vLLM main이 필요 합니다. 2, 3은 각각 /integrate/vllm-offloading/ , /integrate/vllm-gpudirect/ 페이지를 따로 확인하세요. 아래는 1 기준입니다. 3-1. 플러그인 설치 curl -LO https://dl.min.io/aistor/memkv/release/linux-amd64/memkv_lmcache-latest-cp39-abi3-linux_x86_64.whl pip install 'lmcache>=0.5,<0.6' ./memkv_lmcache-latest-cp39-abi3-linux_x86_64.whl 3-2. LMCache 설정 ( lmcache.yaml ) chunk_size: 256 local_cpu: True max_local_cpu_size: 60 # GiB. 너무 작으면(한 자리 GiB) 모든 read가 MemKV로 감 enable_lazy_memory_allocator: True lazy_memory_initial_ratio: 0.003 storage_plugins: memkv extra_config: storage_plugin.memkv.module_path: memkv_lmcache.backend storage_plugin.memkv.class_name: MemKVStorageBackend local_cpu: True 와 max_local_cpu_size > 0 은 필수입니다. LMCache의 CPU 풀(2단계)이 가득 차면 evict된 chunk가 MemKV로 흘러가는 구조라서, 이 풀이 곧 vLLM의 G2 역할을 합니다. 3-3. 접속 환경변수 export MEMKV_SERVERS="host-a:9900,host-b:9900" export MEMKV_AUTH_KEY="<64-hex>" export MEMKV_TRANSPORT=auto # RDMA 사용 시. 컨테이너에서 RDMA 미노출이면 tcp export MEMKV_LICENSE=/path/to/minio.license export MEMKV_RDMA_DEVICES="mlx5_0,mlx5_1" export MEMKV_STAGING_SIZE_MB=1024 # TP worker별 pinned staging 풀 export MEMKV_STAGING_SLOT_MB=16 TP=8이면 호스트당 pinned 메모리가 8 × MEMKV_STAGING_SIZE_MB 만큼 필요합니다. 3-4. vLLM 기동 (Docker 예시, RDMA 포함) RDMA를 쓰려면 문서 예시에 --device=/dev/infiniband --cap-add=IPC_LOCK --ulimit memlock=-1 을 추가하고 MEMKV_TRANSPORT=auto (또는 rdma )로 설정합니다. docker run -d --name vllm-memkv \ --runtime=nvidia --net=host --shm-size=64g --ipc=host \ --device=/dev/infiniband --cap-add=IPC_LOCK --ulimit memlock=-1 \ -e MEMKV_SERVERS="host-a:9900,host-b:9900" \ -e MEMKV_AUTH_KEY="$AUTH_KEY" \ -e MEMKV_TRANSPORT=auto \ -e MEMKV_RDMA_DEVICES="mlx5_0,mlx5_1" \ -e MEMKV_LICENSE=/minio.license \ -e LMCACHE_CONFIG_FILE=/lmcache.yaml \ -v /path/to/models:/inference-models:ro \ -v /path/to/minio.license:/minio.license:ro \ -v /path/to/lmcache.yaml:/lmcache.yaml:ro \ -v /path/to/wheels:/plugins:ro \ --entrypoint bash \ vllm/vllm-openai:<tag> -lc ' pip install "lmcache>=0.5,<0.6" /plugins/memkv_lmcache-*.whl && vllm serve /inference-models/<model-dir> \ --host 0.0.0.0 --port 8810 \ --tensor-parallel-size <N> \ --max-model-len <max_seq_len> \ --gpu-memory-utilization 0.85 \ --enable-prefix-caching \ --kv-transfer-config "{\"kv_connector\":\"LMCacheConnectorV1\",\"kv_role\":\"kv_both\"}" ' 정상 기동 시 TP worker마다 Created dynamic backend: memkv , memkv-client license verified , MemKVStorageBackend ready (servers=[...], rdma=...) 로그가 순서대로 보입니다. 이후 chunk_size (256 토큰)보다 긴 프롬프트가 들어오면 Stored ... tokens 로그의 put_time 으로 MemKV 쓰기 시간을 볼 수 있습니다. 3-5. 운영 시 알아둘 점 재시작 후 cold start : 데이터는 MemKV에 남지만 key별 shape/dtype 정보는 프로세스 메모리 dict에만 있어서, 재시작 직후에는 prefill을 다시 하게 됩니다. 문서 로드맵에 개선 항목으로 올라 있습니다. TCP 세션 수 : TP=N이면 MemKV 서버당 TCP 세션이 N세트 생깁니다. HMAC은 인증만 하고 암호화는 하지 않습니다. 특히 TCP는 통제