让 GPU 共享更灵活、更简单

kvcached（KV 缓存守护进程）是一个用于在共享 GPU 上进行 LLM 推理/训练的 KV 缓存库。它通过将操作系统级别的虚拟内存抽象引入 LLM 系统，实现了弹性且按需分配的 KV 缓存，从而在动态负载下提升 GPU 利用率。

kvcached 的实现方式是将 GPU 虚拟地址空间与 KV 缓存的物理内存分配解耦。这使得推理引擎可以先仅保留虚拟内存，等到缓存被实际使用时再将其映射到物理 GPU 内存上。这种解耦支持按需分配和灵活共享，在动态混合负载场景下显著提升了 GPU 内存利用率。更多详细信息请参阅博客。

核心特性

• 弹性 KV 缓存：根据实时负载动态分配和回收 KV 内存。
• GPU 虚拟内存：通过运行时映射将逻辑 KV 与物理 GPU 内存解耦。
• 内存控制 CLI：使用 kvcached CLI 强制执行内存限制。
• 前端路由与休眠模式：将请求路由到目标模型，并在空闲时使模型进入休眠状态。
• 前缀缓存：支持 vLLM（包括混合注意力模型）的自动前缀缓存（APC）以及 SGLang 的 RadixCache，可配置内存上限。
• 支持主流推理引擎：与 SGLang 和 vLLM 集成。

📢 最新动态

• [2026-04] kvcached 被红帽公司重点推荐，用于在资源有限的情况下以动态方式在生产环境中运行 LLM！红帽的 Sardeenz 基于 kvcached 构建，提供基于 Kubernetes 和 OpenShift 支持的动态多模型推理服务。更多信息请参阅博客文章。 [▶ 查看演示]

• [2026-04] 新增前缀缓存支持。kvcached 现在支持 vLLM 的自动前缀缓存（APC）和 SGLang 的RadixCache，能够在保持弹性内存管理的同时实现跨请求的前缀复用。缓存的 token 预算可以通过 KVCACHED_MAX_CACHED_TOKENS 进行控制（默认值为 16000）。

  • vLLM：缓存块保留在可驱逐池中，当内存压力出现时按需释放（惰性驱逐）。token 限制会在内部转换为块数（KVCACHED_MAX_CACHED_TOKENS // block_size）。
  • SGLang：每次请求结束后，RadixCache 会主动驱逐超出 token 预算的条目。适用于 page_size=1 和 page_size>1 的场景。

• [2026-03] 新增流水线并行支持。 MLA 模型（DeepSeek-V3、DeepSeek-V2 等）以及 GPT-OSS 混合注意力模型（openai/gpt-oss-20b）现在也已在 vLLM 中得到支持。 SGLang 对 GPT-OSS 的支持已更新至 v0.5.9。

• [2026-02] kvcached 现在支持 vLLM v0.16.0 和 SGLang v0.5.9。 MLA 模型（DeepSeek-V3、DeepSeek-V2 等）在 SGLang 中同时支持 page_size=1 和 page_size>1。 GPT-OSS 混合注意力模型（openai/gpt-oss-20b）已在 SGLang 中得到支持。

支持的引擎和模型

引擎	版本	注意力类型	示例模型
SGLang	≥ v0.4.9（测试最高至 v0.5.9）	MHA / GQA / MLA	Llama 3.1/3.3、Qwen 2.5、DeepSeek-V3、openai/gpt-oss-20b 等
vLLM	≥ v0.8.4（测试最高至 v0.16.0）	MHA / GQA / MLA	Llama 3.1/3.3、Qwen 2.5、DeepSeek-V3、openai/gpt-oss-20b

示例用例

更多具体示例请参见：kvcached/examples。

kvcached 实际应用

以下简单示例展示了 kvcached 如何使未经修改的 vLLM 引擎以动态分配的内存运行。

性能：多模型服务

kvcached 能够在多个大语言模型之间动态共享显存，使它们可以弹性地共用同一块 GPU 显存。相比之下，当前的推理引擎需要在启动时静态预留 GPU 显存。

本基准测试展示了在 A100-80G GPU 上，使用间歇性高峰负载为三个 Llama-3.1-8B 模型提供服务时，kvcached 带来的性能优势。与现有推理引擎相比，kvcached 可将 TTFT 降低 2 至 28 倍。这种性能提升可转化为大语言模型推理服务的 显著成本节约。如果没有 kvcached，系统必须配置更多的 GPU 才能达到相同的性能。 详细信息请参阅 benchmarks/bench_latency_benefit。

安装

先决条件

• Python（已测试版本：3.9 - 3.13）
• SGLang（已测试版本：v0.5.9）或 vLLM（已测试版本：v0.16.0）

kvcached 可作为插件安装到现有的 SGLang 或 vLLM 环境中。

从 PyPI 安装

pip install kvcached --no-build-isolation

从源码安装

# 在项目根目录下

pip install -e . --no-build-isolation --no-cache-dir
python tools/dev_copy_pth.py

使用 Docker

kvcached 可与原生引擎的 Docker 镜像一起安装。

docker pull ghcr.io/ovg-project/kvcached-sglang:latest   # kvcached-v0.1.4-sglang-v0.5.9
docker pull ghcr.io/ovg-project/kvcached-vllm:latest     # kvcached-v0.1.4-vllm-v0.16.0

我们还为开发者准备了一体化 Docker：

docker pull ghcr.io/ovg-project/kvcached-dev:latest

更多说明请参阅 此处。GB200 的 Docker 镜像正在开发中。

文档

kvcached 已被收录至 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 --disable-radix-cache --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 --no-enable-prefix-caching --port=12346
vllm bench serve --model meta-llama/Llama-3.2-1B-Instruct --request-rate 10 --num-prompts 1000 --port 12346

[!NOTE] kvcached 现在同时支持 vLLM（APC）和 SGLang（RadixCache）的 前缀缓存。您可以按常规方式启用前缀缓存（引擎会使用默认设置）。缓存的块会被保留以供跨请求复用，当需要内存时则按需逐出。通过设置 KVCACHED_MAX_CACHED_TOKENS 可以控制两个引擎的缓存令牌预算（默认值为 16000；设为 0 表示无限制）。如果您希望禁用前缀缓存，请对 vLLM 使用 --no-enable-prefix-caching，对 SGLang 使用 --disable-radix-cache。

当启用 kvcached 时，无需再设置显存利用率限制（例如使用 --gpu-memory-utilization），因为 kvcached 会自动管理显存。

如果您是通过源代码安装的 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 进行推理的说明，请参阅各个脚本。

[!TIP] 自 transformers >= 4.44 起，不再有回退的“默认”聊天模板。如果分词器未定义 chat_template，则在未显式提供的情况下无法使用 apply_chat_template。如果在启动时进行聊天预热时遇到聊天模板错误，请改用 Instruct 模型（例如 meta-llama/Llama-3.2-1B-Instruct），而不是基础模型。

[!NOTE] 我们尚未对 kvcached 与所有版本的 SGLang 和 vLLM 完全兼容（版本太多！）。如果您在特定版本中遇到问题，请提交一个问题——我们会尽快调查并修复。

路线图

最新的路线图也在 issue #125 中记录。

• 引擎集成
  • SGLang 和 vLLM
  • Ollama（进行中）
  • llama.cpp 和 LMStudio
• 功能
  • 张量并行
  • 前缀缓存
  • 将 KV 缓存卸载到主机内存
  • 更多注意力类型（滑动窗口注意力、线性注意力、视觉编码器等）
• 性能优化
  • 连续 KV 张量布局
  • 物理内存管理
• 硬件
  • NVIDIA GPU
  • AMD GPU

贡献

我们非常感谢并欢迎任何形式的贡献与合作。

我们使用 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{yu2025prism,
  title={Prism: Unleashing GPU Sharing for Cost-Efficient Multi-LLM Serving},
  author={Yu, Shan and Xing, Jiarong and Qiao, Yifan and Ma, Mingyuan and Li, Yangmin and Wang, Yang and Yang, Shuo and Xie, Zhiqiang and Cao, Shiyi and Bao, Ke and others},
  journal={OSDI},
  year={2026}
}

kvcached 快速上手指南

kvcached 是一个专为共享 GPU 场景设计的 KV Cache 库。它通过引入操作系统式的虚拟内存抽象，实现了 KV Cache 的弹性分配和按需加载，显著提升了动态负载下的 GPU 利用率。支持 SGLang 和 vLLM 主流推理引擎。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐 Ubuntu)
• Python 版本: 3.9 – 3.13
• 推理引擎 (二选一或同时安装):
  • SGLang: 测试版本 ≥ v0.4.9 (推荐 v0.5.9)
  • vLLM: 测试版本 ≥ v0.8.4 (推荐 v0.16.0)
• GPU: 支持 CUDA 的 NVIDIA GPU (如 A100, H100, RTX 系列等)

注意: kvcached 作为插件运行，需先安装好基础的 SGLang 或 vLLM 环境。

2. 安装步骤

您可以选择通过 PyPI 直接安装，或通过源码/Docker 进行部署。

方式一：通过 PyPI 安装（推荐）

在已安装 SGLang 或 vLLM 的环境中执行：

pip install kvcached --no-build-isolation

方式二：从源码安装（适合开发者）

# 克隆项目并进入目录
git clone https://github.com/ovg-project/kvcached.git
cd kvcached

# 编辑模式安装
pip install -e . --no-build-isolation --no-cache-dir

# 执行必要的补丁复制脚本
python tools/dev_copy_pth.py

方式三：使用 Docker（最简便）

直接使用预构建的镜像，包含完整的引擎和 kvcached 环境：

# SGLang 版本
docker pull ghcr.io/ovg-project/kvcached-sglang:latest

# vLLM 版本
docker pull ghcr.io/ovg-project/kvcached-vllm:latest

# 全能开发版镜像
docker pull ghcr.io/ovg-project/kvcached-dev:latest

3. 基本使用

kvcached 的核心优势在于无需修改原有推理引擎代码，仅需设置环境变量即可激活弹性内存管理功能。

第一步：启用 kvcached

在启动推理服务前，导出以下环境变量：

export ENABLE_KVCACHED=true
export KVCACHED_AUTOPATCH=1

(可选) 配置前缀缓存令牌上限（默认 16000）：

export KVCACHED_MAX_CACHED_TOKENS=16000

第二步：启动推理服务

根据您使用的引擎，运行标准的启动命令。kvcached 会自动拦截内存分配请求。

场景 A：使用 SGLang

# 启动服务
python -m sglang.launch_server \
    --model meta-llama/Llama-3.2-1B-Instruct \
    --disable-radix-cache \
    --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

场景 B：使用 vLLM

# 启动服务
vllm serve meta-llama/Llama-3.2-1B-Instruct \
    --no-enable-prefix-caching \
    --port=12346

# 后台运行压力测试验证效果
vllm bench serve \
    --model meta-llama/Llama-3.2-1B-Instruct \
    --request-rate 10 \
    --num-prompts 1000 \
    --port 12346

验证效果

成功启用后，多个 LLM 模型可以共享同一块 GPU 显存。当某个模型空闲时，其占用的物理显存会被释放供其他模型使用，从而在有限资源下实现多模型并发或服务器的“休眠/唤醒”机制。

提示: 更多高级用法（如多模型路由、流水线并行）请参考官方 examples 目录或 DeepWiki 文档。