概述#

CT-HPKV采用配置文件与环境变量配置的方案实现KV Cache卸载的行为控制，CT-HPKV将配置分为两层，推理引擎层和HPKV Server层。 CT-HPKV当前支持的推理主要是vLLM与SGLang。所谓推理引擎层环境变量，即在原始推理引擎拥有的环境变量基础上，为了适配CT-HPKV 功能做的环境变量扩展。CT-HPKV为vLLM新增的环境变量扩展仍以 VLLM_ 开头, 为SGLang新增的环境变量扩展仍以 SGLANG_ 开头。

CT-HPKV Server侧的配置项则以 HPKV_ 开头。配置的优先级为: 配置文件 > 环境变量 > 默认值 。详细来说，如果某配置项存在于配置文件中，则优先使用配置文件中的配置；如果某配置项存在于环境变量中，则优先使用环境变量中的配置；如果某配置既不存在于配置文件中，也不存在于环境变量中，则使用CT-HPKV预置的默认值(配置文件与环境变量采用完全相同的配置名)。

vLLM#

# 是否使用CT-HPKV使能KV Cache卸载, 支持传入: (1, 0, "True", "False"), 不区分大小写，默认False
export VLLM_ENABLE_HPKV = "True"

# vLLM 启动HPKV GRPC Server时服务端监听的端口, 若GRPC Server独立启动, vLLM连接该端口
# 支持传入: (50051, "50051"), 默认50051
export VLLM_HPKV_RPC_SERVER_PORT=50051

# HPKV GRPC Server启动模式: 0: vLLM主动拉起; 1: GRPC Server单独启动vLLM仅连接, 默认值: 0
export VLLM_HPKV_RPC_SERVER_MODE=0

# vLLM 单次推理中使用HPKV以存代算的阈值, 小于该值时选择重算或仅使用Prefix Cache, 默认值: 1024
export VLLM_HPKV_TOKEN_THRESHOLD=1024

# vLLM 使用启动CHUNKED PREFILL, 某些vLLM版本默认开始, 添加此设置允许用户显示控制
export VLLM_ENABLE_CHUNKED_PREFILL=Fasle

# 显式指定vLLM KV Cache Layout, 仅vLLM v<=0.9.1传入, 高版本vLLM支持此环境环境
# 支持传入: ("NHD", "HND"), 默认None("NHD")
export VLLM_KV_CACHE_LAYOUT="NHD"

vLLM-Ascend#

# vLLM-Acend暂无配置选项

SGLang#

# 是否使用CT-HPKV使能KV Cache卸载
export SGLANG_ENABLE_HPKV = "True"


# SGLang启动HPKV GRPC Server时服务端监听的端口, 若GRPC Server独立启动, SGLang连接该端口
# 支持传入: (50051, "50051"), 默认50051
export SGLANG_HPKV_RPC_SERVER_PORT=50051


# HPKV GRPC Server启动模式: 0: SGLANG主动拉起; 1: GRPC Server单独启动SGLANG仅连接, 默认值: 0
export SGLANG_HPKV_RPC_SERVER_MODE=0


# SGLang单次推理中使用HPKV以存代算的阈值, 小于该值时选择重算或仅使用Prefix Cache, 默认值: 1024
export SGLANG_HPKV_TOKEN_THRESHOLD=1024

HPKV#

# 1. HPKV日志信息配置字段
# GRPC Server日志文件路径, 默认: "~/.cache/hpkv/logs"
export HPKV_LOG_PATH="~/.cache/hpkv/logs"

# GRPC Server日志级别, 默认"INFO", 不区分大小写
export HPKV_LOG_LEVEL="INFO"

# RRPC Server日志是否落盘, 默认: true
export HPKV_ENABLE_LOG_SINK="true"

# GRP Server日志文件名， 默认: "hpkv.log"
export HPKV_LOG_FILE_NAME="hpkv.log"

# GRP Server日志文件最大数量, 默认值: 10
export HPKV_MAX_LOG_FILE_NUM=10

# GRP Server日志文件最大容量, 默认值: 10(默认单位MB)
export HPKV_LOG_FILE_MAX_SIZE=10


# 2. HPKV 配置文件
# HPKV GRPC Server配置文件路径, 默认: "~/.config/hpkv/config.ini"
# HPKV GRPC Server默认优先从配置文件读取配置信息，然后再选择从环境变量获取
export HPKV_CONFIG_FILE_PATH="~/.config/hpkv/config.ini"


# 3. HPKV KV Cache配置
# HPKV KV Cache卸载内存池大小
# 支持("1024MB", "4GB", "4G", "8g", "8"), 默认值: 16, 默认单位GB, 不区分大小写
export HPKV_KV_MEM_POOL_SIZE=8

# HPKV 共享内存文件路径, 默认: "/mnt/hugepages"
# 注意事项:
#  1. 当前用户需要对该路径有用读写权限;
#  2. 路径需要配置为ramfs类型: 可使`mount -t ramfs nodev /mnt/hugepages`配置, 后使用`mount | grep ramfs`进行查看
export HPKV_SHARE_MEM_FILE_PATH="/mnt/hpkv"


# 4. GRPC 配置
# GPRC Server服务监听端口, GPRC独立启动时使用该配置
export HPKV_RPC_SERVER_PORT=50051

# GPRC Server服务监听端口, GPRC被vLLM启动时使用该配置
export VLLM_HPKV_RPC_SERVER_PORT=50051


# 5. HPKV KV Cache持久化存储配置(SSD/HPFS)
# 启用KV Cache卸载到存储, 默认: true
export HPKV_ENABLE_STORAGE="true"

# KV Cache存储路径, 默认: "~/.cache/hpkv/storage"
export HPKV_KV_STORAGE_PATH="~/.cache/hpkv/storage"

# 多机或多实例场景下KV Cache存储系统模式: 0: "LOCAL", 1: "SHARED"
export HPKV_KV_STORAGE_MODE=0

# KV Cache存储读取线程数, 默认: 16
export HPKV_IO_THREAD_NUM_R=16

# KV Cache存储写入线程数, 默认: 4
export HPKV_IO_THREAD_NUM_W=4

# 是否启用存储自动驱逐, 默认: true
export HPKV_ENABLE_STORAGE_AUTO_EVICT="true"

# 启动时是否驱逐所有KV Cache文件, 默认: false
export HPKV_ENABLE_STORAGE_EVICT_ON_BOOT="false"

# 退出时是否驱逐所有KV Cache文件, 默认: false
export HPKV_ENABLE_STORAGE_EVICT_ON_EXIT="false"

# KV Cache存储文件自动驱逐时间间隔, 默认：60, 单位'second'
export HPKV_STORAGE_AUTO_EVICT_INTERVAL=60


# KV Cache文件驱逐占用率因子, 超过该占用率开始驱逐，默认: 0.85
export HPKV_STORAGE_FULL_FACTOR=0.85

# 存储上KV Cache文件单次驱逐最大文件数量(默认值: 10000)
export HPKV_STORAGE_MAX_EVICT_NUM=10000

# 存储上KV Cache文件单次驱逐最大文件比例默认值
export HPKV_STORAGE_MAX_EVICT_RATIO=0.01


# 6. MMAP配置
# 异步进行共享内存mmap的线程数量, 默认：4
export HPKV_ASYNC_MMAP_THREAD_NUM=4