kvcached

GPU 공유를 유연하고 쉽게 만들기

kvcached(KV cache daemon)는 공유 GPU에서 LLM 서빙/학습을 위한 KV cache 라이브러리입니다. OS 스타일의 가상 메모리 추상화를 LLM 시스템에 도입하여 탄력적이고 수요 기반의 KV cache 할당을 가능하게 하며, 동적 워크로드에서 GPU 활용도를 향상시킵니다.

kvcached는 KV cache에 대해 GPU 가상 주소 지정을 물리 메모리 할당으로부터 분리함으로써 이를 달성합니다. 이를 통해 서빙 엔진은 처음에는 가상 메모리만 예약하고, 캐시가 실제로 사용될 때 물리 GPU 메모리로 이를 뒷받침할 수 있습니다. 이러한 분리는 온디맨드 할당과 유연한 공유를 가능하게 하여 동적이고 혼합된 워크로드에서 더 나은 GPU 메모리 활용도를 제공합니다. 자세한 내용은 블로그에서 확인하세요.

주요 기능

탄력적 KV cache: 실제 부하에 맞춰 KV 메모리를 동적으로 할당하고 회수합니다.
GPU 가상 메모리: 런타임 매핑을 통해 논리적 KV를 물리 GPU 메모리로부터 분리합니다.
메모리 제어: kvcached CLI 또는
개정된 프로덕션 제어 API를 통해 메모리 한도를 적용합니다.
프론트엔드 라우터 및 슬립 모드: 요청을 대상 모델로 라우팅하고 유휴 시 모델을 슬립 상태로 전환합니다.
주류 서빙 엔진 지원: SGLang 및 vLLM과 통합됩니다.
프리픽스 캐싱: 구성 가능한 메모리 한도와 함께 자동 프리픽스 캐싱(APC)을 지원합니다. 자세한 내용은 예제 문서를 참조하세요.

📢 업데이트

[2026-10] kvcached v0.1.6은 vLLM v0.30(Model Runner V2 포함) 및 SGLang v0.5.20, 하이브리드 선형 어텐션 모델(Qwen3.5, Qwen3.8), Gemma 4, AMD GPU(ROCm)를 지원합니다.

[2026-04] kvcached가 제한된 리소스 환경에서 프로덕션 LLM을 동적으로 실행하는 사례로 Red Hat에 소개되었습니다! Red Hat의 Sardeenz는 kvcached를 기반으로 Kubernetes 및 OpenShift 지원을 갖춘 동적 멀티 모델 서빙을 제공합니다. 자세한 내용은 블로그 게시물을 참조하세요.
[▶ 데모 보기]

[2026-04] 프리픽스 캐싱 지원이 추가되었습니다. kvcached는 이제 vLLM의 자동 프리픽스 캐싱(APC)과 SGLang의 RadixCache를 지원하여 탄력적 메모리 관리를 유지하면서 요청 간 프리픽스 재사용을 가능하게 합니다.

[2026-03] 파이프라인 병렬 처리 지원이 추가되었습니다.
MLA 모델(DeepSeek-V3, DeepSeek-V2 등)과 GPT-OSS 하이브리드 어텐션 모델(openai/gpt-oss-20b)도 이제 vLLM에서 지원됩니다.
SGLang의 GPT-OSS 지원이 v0.5.9로 업데이트되었습니다.

지원 엔진 및 모델

엔진
버전
어텐션 유형
예제 모델

SGLang
≥ v0.5.11(v0.5.20까지 테스트됨)
MHA / GQA / MLA / 슬라이딩 윈도우 / 하이브리드
DeepSeek-V3, Qwen3-8B, GPT-OSS-20B, Qwen3.5-9B, Qwen3.8-27B, Gemma-4-E2B-it

vLLM
≥ v0.17.0(v0.30.0까지 테스트됨)
MHA / GQA / MLA / 슬라이딩 윈도우 / 하이브리드
DeepSeek-V3, Qwen3-8B, GPT-OSS-20B, Qwen3.5-9B, Qwen3.8-27B, Gemma-4-E2B-it, Gemma-4-12B-it

최소 버전은 아래 PyTorch 요구 사항에서 비롯됩니다. 각 엔진 및 KV 레이아웃별 모델 결과는 #425를 참조하세요.

예제 사용 사례

멀티 LLM 서빙
kvcached를 사용하면 여러 LLM이 GPU 메모리를 탄력적으로 공유할 수 있어, 현재 사용되는 경직된 메모리 분할 없이 동시 배포가 가능합니다. 이를 통해 GPU 활용도가 향상되고 서빙 비용이 절감됩니다.

서버리스 LLM
필요할 때만 KV cache를 할당함으로써 kvcached는 모델이 수요에 따라 시작되고 종료될 수 있는 서버리스 배포를 지원합니다.

복합 AI 시스템
kvcached는 파이프라인 내 특화 모델(예: 검색, 추론, 요약) 간에 메모리를 탄력적으로 할당하여 제한된 하드웨어에서 복합 AI 시스템을 실용적으로 만듭니다.

GPU 워크로드 코로케이션
kvcached를 사용하면 LLM 추론이 학습 작업, 파인튜닝, 비전 모델 등 다른 GPU 워크로드와 공존할 수 있습니다.

구체적인 예제는 여기에서 확인하세요: kvcached/examples.

실제 kvcached 활용
다음의 간단한 예제는 kvcached가 수정되지 않은 vLLM 엔진을 동적으로 할당된 메모리로 실행하는 방법을 보여줍니다.

성능: 멀티 LLM 서빙
kvcached는 LLM 간의 동적 메모리 공유를 가능하게 하여 동일한 GPU 메모리를 탄력적으로 공유할 수 있게 합니다. 이와 대조적으로, 현재의 서빙 엔진은 시작 시 GPU 메모리를 정적으로 예약해야 합니다.

이 벤치마크는 간헐적인 피크가 있는 워크로드에서 A100-80G GPU로 세 개의 Llama-3.1-8B 모델을 서빙할 때 kvcached의 성능 이점을 보여줍니다. kvcached는 현재 서빙 엔진 대비 2-28배의 TTFT 감소를 달성할 수 있습니다. 이 성능 이점은 LLM 서빙의 상당한 비용 절감으로 이어질 수 있습니다. kvcached가 없다면 시스템은 동일한 성능을 달성하기 위해 더 많은 GPU를 프로비저닝해야 합니다.
자세한 내용은 benchmarks/bench_latency_benefit에서 확인할 수 있습니다.

설치
사전 요구 사항

Python(3.10 - 3.13에서 테스트됨)
PyTorch >= 2.10(kvcached는 PyTorch stable ABI에 맞춰 빌드됨)
SGLang(v0.5.20에서 테스트됨) 또는 vLLM(v0.30.0에서 테스트됨)

kvcached는 기존 SGLang 또는 vLLM 환경에 플러그인으로 설치할 수 있습니다.

PyPI에서 설치
pip install kvcached --no-build-isolation
소스에서 설치
# 프로젝트 루트 폴더에서

pip install -e . --no-build-isolation --no-cache-dir
Docker 사용
kvcached는 원본 엔진 Docker와 함께 설치됩니다.

docker pull ghcr.io/ovg-project/kvcached-sglang:latest # kvcached-v0.1.6-sglang-v0.5.20
docker pull ghcr.io/ovg-project/kvcached-vllm:latest # kvcached-v0.1.6-vllm-v0.30.0
개발자를 위한 올인원 Docker를 준비했습니다:

docker pull ghcr.io/ovg-project/kvcached-dev:latest
더 많은 지침은 여기에서 확인할 수 있습니다.

문서
kvcached는 LLM 기반 문서화를 위해 DeepWiki에 색인되어 있습니다.

문서는 다음을 다룹니다:

핵심 아키텍처 및 메모리 관리 시스템
vLLM 및 SGLang과의 통합
멀티 모델 서빙 및 컨트롤러 시스템
배포 가이드 및 구성 참조
성능 벤치마킹 및 분석
개발 도구 및 테스트

테스트
kvcached는 다음 환경 변수를 설정하여 활성화할 수 있습니다:

export ENABLE_KVCACHED=true
export KVCACHED_AUTOPATCH=1
엔진별 Docker를 사용하는 경우, 원본 엔진의 벤치마크 스크립트를 실행하여 kvcached를 테스트할 수 있습니다. 예를 들어:

# sglang의 경우
python -m sglang.launch_server --model meta-llama/Llama-3.2-1B-Instruct --port 30000
python -m sglang.bench_serving --backend sglang-oai --model meta-llama/Llama-3.2-1B-Instruct --dataset-name sharegpt --request-rate 10 --num-prompts 1000 --port 30000

# vllm의 경우
vllm serve meta-llama/Llama-3.2-1B-Instruct --port=12346
vllm bench serve --model meta-llama/Llama-3.2-1B-Instruct --request-rate 10 --num-prompts 1000 --port 12346
참고

프리픽스 캐싱을 비활성화하려면 vLLM의 경우 --no-enable-prefix-caching을, SGLang의 경우 --disable-radix-cache를 사용하세요.

kvcached가 활성화되면 kvcached가 메모리를 자동으로 관리하므로 메모리 사용률 한도(예: --gpu-memory-utilization 사용)를 설정할 필요가 없습니다.

참고

AMD / ROCm: ROCm(HIP) 빌드에서 kvcached는 자동으로 비연속 KV-cache 레이아웃을 기본값으로 사용합니다. 연속 레이아웃(NVIDIA의 기본값)은 vLLM의 ROCm 어텐션 백엔드에 올바르게 읽을 수 없는 스트라이드된 계층별 KV 텐서를 전달하는 반면, 비연속 레이아웃은 백엔드가 기대하는 레이아웃과 일치합니다. KVCACHED_CONTIGUOUS_LAYOUT=true|false로 재정의할 수 있지만, ROCm에서는 연속 레이아웃을 권장하지 않습니다.

소스 코드로 kvcached를 설치한 경우 다음도 수행할 수 있습니다:

cd benchmarks/simple_bench
./start_server.sh [sglang | vllm] --venv-path $VENV_PATH --model meta-llama/Llama-3.2-1B-Instruct
# LLM 서버가 준비될 때까지 대기
./start_client.sh [sglang | vllm] --venv-path $VENV_PATH --model meta-llama/Llama-3.2-1B-Instruct
벤치마크 스크립트는 자동으로 ENABLE_KVCACHED=true를 설정합니다. kvcached로 추론을 실행하는 방법은 각 스크립트의 지침을 참조하세요.

참고

모든 버전의 SGLang 및 vLLM과 kvcached를 완전히 테스트하지는 않았습니다(너무 많습니다!). 특정 버전에서 문제가 발생하면 이슈를 열어주세요---몇 시간 내에 확인하고 수정하겠습니다.

기여
어떤 종류의 기여와 협력도 환영하며 감사드립니다.

일관된 코딩 스타일을 보장하기 위해 pre-commit을 사용합니다. 다음과 같이 설정할 수 있습니다:

pip install pre-commit
pre-commit install

코드를 푸시하기 전에 다음 검사를 실행하고 코드가 모든 검사를 통과하는지 확인하세요.

pre-commit run --all-files

연락처
kvcached는 커뮤니티의 많은 기여자들에 의해 개발되었습니다. 질문, 이슈, 기여에 대해 문의하는 가장 좋은 방법은 Slack 채널 또는 GitHub Issues를 이용하는 것입니다.

신뢰하고 배포하는 곳

인용
kvcached가 유용하다고 생각되면 논문을 인용해 주세요:

@article { xing2025towards ,
title = { Towards Efficient and Practical GPU Multitasking in the Era of LLM } ,
author = { Xing, Jiarong and Qiao, Yifan and Mo, Simon and Cui, Xingqi and Sela, Gur-Eyal and Zhou, Yang and Gonzalez, Joseph and Stoica, Ion } ,
journal = { arXiv preprint arXiv:2508.08448 } ,
year = { 2025 }
}

@article { yu2026prism ,
title = { Prism: Cost-Efficient Multi-LLM Serving via GPU Memory Ballooning } ,
author = { Yu, Shan and Qiao, Yifan and Ma, Mingyuan and Li, Yangmin and Yang, Shuo and Tong, Xinyuan and Wang, Yang and Xie, Zhiqiang and An, Yuwei and Cao, Shiyi and Bao, Ke and Vij, Deepak and Ding, Xiaoning and Wang, Yichen and Lu, Qingda and Wang, Zhong and Gao, Gao and Xu, Harry and Shu, Junyi and Xing, Jiarong and Sheng, Ying } ,
journal = { OSDI } ,
year = { 2026 }
}