Skip to content

README_zh.md

Latest commit

 

History

History
145 lines (114 loc) · 4.75 KB

README_zh.md

File metadata and controls

145 lines (114 loc) · 4.75 KB

在 vLLM 中使用 FlexKV

🎉 重要更新（2026年3月17日）

FlexKV 已于 2026 年 3 月 17 日正式合并进入 vLLM 官方主干（PR #34328）。

从 vLLM v0.17.2rc0（commit 8cb24d3）起，FlexKVConnectorV1 已内置于 vLLM，无需再手动打 patch。

推荐做法：直接安装 vLLM >= v0.17.2 正式版（或当前 main 分支），不再需要使用 examples/vllm_adaption/ 下的 patch 文件。
旧版 patch 仍保留于 examples/vllm_adaption/ 目录，供需要使用 vLLM < 0.17.2 的用户参考。

当前版本与 Legacy 版本说明

在 commit 0290841dce65ae9b036a23d733cf94e47e814934，我们更新了一个重要功能： FlexKV 从 client-server 模式，变为推理加速引擎（如 vLLM）可直接调用的库函数，以减少进程间消息传递的开销。 这一变更引发了较大的 API 调整。因此，请注意：

  • 版本 >= 1.0.0：应使用 当前版本 API。
  • 版本 == 0.1.0：仅支持 Legacy 版本 API, vLLM patch位于examples/vllm_adaption_legacy/。

当前版本（>= 1.0.0）

适用版本

  • FlexKV >= 1.0.0
  • vLLM >= 0.17.2（推荐）：内置 FlexKVConnectorV1，无需打 patch，直接使用
  • vLLM 0.10.1 ~ 0.17.1：需手动 apply patch，参见使用旧版 vLLM（需 patch）

配置

示例一：仅启用CPU卸载

使用32GB的CPU内存作为二级缓存。

unset FLEXKV_CONFIG_PATH
export FLEXKV_CPU_CACHE_GB=32

示例二：启用SSD卸载

使用32GB的CPU内存和1T的SSD存储分别作为二级和三级缓存。（假设机器有两个SSD，并分别挂载在/data0和/data1两个路径上。）

# generate config
cat <<EOF > ./flexkv_config.yml
cpu_cache_gb: 32
ssd_cache_gb: 1024
ssd_cache_dir: /data0/flexkv_ssd/;/data1/flexkv_ssd/
enable_gds: false
EOF
export FLEXKV_CONFIG_PATH="./flexkv_config.yml"

注：flexkv_config.yml配置仅为简单示例，选项请参考docs/flexkv_config_reference/README_zh.md

运行（推荐：vLLM >= 0.17.2，无需 patch）

  1. 安装 vLLM（>= 0.17.2 正式版，或从官方 main 分支源码安装）
pip install vllm>=0.17.2
# 或从源码安装最新 main 分支：
# git clone https://github.com/vllm-project/vllm.git && cd vllm && pip install -e .
  1. 安装 FlexKV
pip install flexkv  # 或从源码编译：./build.sh
  1. offline test
# 参考 VLLM_DIR/examples/offline_inference/prefix_caching_flexkv.py
python examples/offline_inference/prefix_caching_flexkv.py
  1. online serving
VLLM_USE_V1=1 python -m vllm.entrypoints.cli.main serve Qwen3/Qwen3-32B \
     --tensor-parallel-size 8 \
     --trust-remote-code \
     --port 30001 \
     --max-num-seqs 128 \
     --max-num-batched-tokens 8192 \
     --max_model_len 8192 \
     --max-seq-len-to-capture 8192 \
     --gpu-memory-utilization 0.8 \
     --enable-chunked-prefill \
     --enable-prefix-caching \
     --kv-transfer-config \
        '{"kv_connector":"FlexKVConnectorV1","kv_role":"kv_both"}'

使用旧版 vLLM（需 patch）

如需在 vLLM < 0.17.2 上使用 FlexKV，请手动 apply 对应版本的 patch：

vLLM 版本 patch 文件
0.10.1.1 examples/vllm_adaption/vllm_0_10_1_1-flexkv-connector.patch
0.14.1+ examples/vllm_adaption/vllm_up_0_14_1-flexkv-connector.patch
0.16.0 examples/vllm_adaption/vllm_0_16_0-flexkv-connector.patch 
cd vllm
git apply FLEXKV_DIR/examples/vllm_adaption/<对应patch文件>
pip install -e .

Legacy版本（<= 0.1.0），目前的版本尽量不要使用

适用版本

  • FlexKV <= 0.1.0

配置

旧版本配置方式如下

# generate config
cat <<EOF > ./flexkv_config.json
{
    "server_recv_port": "ipc:///tmp/flexkv_test",
    "cache_config": {
          "enable_cpu": true,
          "num_cpu_blocks": 10240
    },
    "num_log_interval_requests": 200
}
EOF
export FLEXKV_CONFIG_PATH="./flexkv_config.json"

运行

在 vLLM 0.8.4 版本中应用patch examples/vllm_adaption_legacy/flexkv_vllm_0_8_4.patch，分别启动 FlexKV、vLLM 和测试脚本：

# 启动 FlexKV 作为服务端
bash benchmarks/flexkv_benchmark/run_flexkv_server.sh

# 启动 vLLM 作为客户端
bash benchmarks/flexkv_benchmark/serving_vllm.sh

# 启动性能测试
bash benchmarks/flexkv_benchmark/multiturn_benchmark.sh

在 vLLM 0.10.0 版本中应用patch examples/vllm_adaption_legacy/flexkv_vllm_0_10_0.patch，测试方法同上。