orbitkv

OrbitKV는 LLM 추론 엔진을 위한 외부 키-값 캐시 계층입니다. vLLM과 SGLang의 KV 캐시를 GPU 메모리 너머로 확장합니다. 재사용 가능한 프리픽스는 DRAM과 SSD에 보관되고, 일치하는 요청이 도착하면 복원됩니다. 명시된 사용 사례는 반복 문서, 공유 시스템 프롬프트, 그리고 프리픽스가 엔진의 GPU 캐시에 더 이상 들어가지 않는 긴 대화가 있는 워크로드입니다. 배포 모델 독립적인 Cache Manager가 호스트별로 실행되며, 해당 호스트의 엔진들이 그 공유 캐시에 연결됩니다. 엔진은 GPU 메모리와 스케줄링의 소유권을 유지하고, OrbitKV는 외부 복제본과 전송을 관리합니다. 단일 노드 경로는 vLLM 0.29.0과 SGLang 0.5.20에서 GPU 테스트되었다고 설명됩니다. 다중 노드 캐시 공유는 실험적이라고 표시되어 있으며, 인터페이스는 1.0 이전에 변경될 수 있습니다. 주요 기능 - DRAM 및 SSD 캐싱: Cache Manager가 살아 있는 동안 GPU 제거 또는 엔진 재시작 후에도 프리픽스를 재사용할 수 있습니다. - 선택적 재사용 정책: Rust 구성 요소가 바이트 상한 내에서 재사용된 페이지를 보호하고 SSD 쓰기를 선택적으로 허용할 수 있습니다. 문서는 콜드 재사용 트레이드오프를 언급합니다. - 직접 GPU 전송: 두 엔진 모두 CUDA IPC를 통해 GPU 버퍼를 등록합니다. 어댑터는 생성 CUDA 스트림을 펜스하고, Rust는 캐시 쿼리, 읽기 및 전송 완료를 처리합니다. - 모델 인식 복구: 캐시 아이덴티티에는 모델 아티팩트, 계산 설정 및 저장소 레이아웃이 포함됩니다. 컴파일된 복구 규칙은 어텐션 페이지, 슬라이딩 윈도우 및 순환/컨브 체크포인트를 선택하며, 세 가지를 모두 결합한 레이아웃도 포함합니다. - 제한된 리소스 사용: 바이트 예산은 대기 중인 읽기, 준비된 페이지 및 활성 GPU 전송을 포함합니다. 취소는 완료될 때까지 제출된 I/O를 유지합니다. - 관찰 가능성: Prometheus 메트릭과 선택적 요청 타임라인, 게시된 측정값에 대한 재현 명령을 제공합니다. - 실험적 공유 캐시: 임베디드 카탈로그 샤드가 피어 복제본을 찾고, Mooncake Transfer Engine이 바이트를 이동하며, etcd가 클러스터 멤버십을 추적합니다. 빠른 시작 개요 휠은 Python 및 CUDA 런타임별로 빌드 및 설치되며, vLLM과 SGLang을 위한 별도 환경이 있습니다. 휠에는 Cache Manager와 Mooncake 라이브러리가 포함되며, Manager는 호환되는 PyTorch도 필요로 합니다. 첫 번째 Python 릴리스는 준비 중이라고 설명되어 있으므로 패키지 게시 상태는 릴리스 문서에서 확인해야 합니다. Cache Manager는 `orbitkv-cache-manager --addr 127.0.0.1:50055 --http-addr 127.0.0.1:9091 --pool-size 8gb`와 같은 명령으로 시작됩니다. 그런 다음 vLLM은 프리픽스 캐싱을 활성화하고 OrbitKV 커넥터 모듈을 지정하는 KV 전송 구성을 사용하여 시작됩니다. SGLang은 OrbitKV 엔드포인트 환경 변수, 페이지 크기, 외부 링커 및 radix 캐시 백엔드 옵션으로 시작됩니다. SSD 캐싱은 Manager 명령에 `--ssd-cache-path`와 `--ssd-cache-capacity`를 추가하여 활성화됩니다. SSD 캐시는 Manager가 재시작될 때 다시 생성됩니다. 기본 SSD 백엔드는 지원되는 마운트에서 네이티브 cuFile을 시도하고 io_uring으로 폴백합니다. `--ssd-read-path uring|cufile` 재정의는 저장된 표현과 독립적으로 수요 복원 경로를 선택합니다. 스토리지 인코딩 옵션에는 nvCOMP ANS 무손실 압축, FP8, 3/4비트 TurboQuant가 있으며 `--storage-codec`으로 선택합니다. 기본값은 정확한 저장이며, 손실 모드는 모델 품질 검증이 필요합니다. `orbitkv_load_bytes_total` 메트릭의 상승이 외부 복원의 확인으로 제시됩니다. 아키텍처 및 상태 엔진 어댑터는 누락된 상태를 식별하고 GPU 대상을 제공합니다. OrbitKV는 호환되는 캐시된 범위를 선택하고, 구성된 계층에서 읽으며, GPU 복사가 완료될 때까지 페이지 소유권을 유지합니다. 새로 계산된 KV는 나중에 재사용할 수 있도록 게시됩니다. 동일한 어댑터 API가 DRAM, SSD 및 실험적 원격 페치를 제공하며, 물리적 배치는 Cache Manager 내부에 있습니다. 프로젝트는 고정된 LMCache, FlexKV 및 Mooncake 메커니즘을 배포 및 검증 작업에 매핑하는 구현 계획을 문서화합니다. 제한된 Rust 비용 관찰, 원시 복사 섀도 예측 및 독립 SSD 읽기 경로는 구현된 것으로 설명됩니다. 동적 비용 선택은 계획된 상태로 남아 있으며, 관찰은 기본적으로 꺼져 있습니다. 엔진 간 바이트 변환, 프로덕션 카탈로그 HA 및 KV 인식 요청 라우팅은 계획된 작업으로 나열됩니다. 성능 문서 성능은 프리픽스 재사용, 캐시 용량, 스토리지 및 엔진 스케줄링에 따라 달라진다고 명시되어 있습니다. 보고서는 단일 노드 비교(네이티브 HBM, 엔진 CPU 캐시, OrbitKV, LMCache, FlexKV), SSD 복구, Qwen3-8B 호스트 읽기 및 GPU 전송을 사용한 일반 복구, 요청 준비 및 공유 캐시 검증을 다룹니다. 요청 준비는 기본적으로 꺼져 있습니다. 문서화된 Qwen3-8B 컨트롤은 두 엔진 모두에서 처리량을 향상시키지만, SGLang P95 지연 시간은 회귀하며, 단일 H20 측정값은 다른 캐시에 대한 보편적 이점으로 제시되지 않습니다. 벤치마크 코드와 요약은 `benches/` 디렉터리에 있습니다. 라이선스 및 기여 OrbitKV는 Apache-2.0에 따라 라이선스가 부여됩니다. 문서는 설치, 어댑터 구성, Manager 옵션, 메트릭, 장애 검증, 배포 패턴, 기여자 가이드, Python 패키지 세부 정보, 테스트 게이트 및 릴리스를 다룹니다. 기여에는 관련 검사와 문서 변경이 포함될 것으로 예상됩니다.