SGLang 接入 FlexKV用 CPU/SSD/远端分层 KV Cache 扩展 RadixCache 的主机端卸载实战指南【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang导读本文围绕 SGLang 仓库中 FlexKV 集成模块 展开讲解如何通过一个继承自RadixCache的FlexKVRadixCache子类把 SGLang 的宿主层host-tierKV Cache 路由到 FlexKV 的KVManagerCPU / SSD / 远端卸载从而在 GPU 显存不足时把前缀 KV 持久化到更廉价的分层存储并实现前缀命中复用。读完本文你将掌握 FlexKV 后端的完整部署流程Docker 容器、editable 安装、最小 YAML、服务器启动与缓存命中验证、MP同步与 IPlayerwise 逐层传输两种运行模式的区别、PP × CP × TP 多轴并行下的同步机制、全部环境变量与常见故障排查方法并能依据仓库源码理解lookup_kv/retrieve_kv/store_kv等核心调用链的底层原理。FlexKV 与 SGLang 的集成模式FlexKV 是一个面向大模型推理的宿主层 KV Cache 管理组件负责把 KV 数据按 CPU 内存 → SSD → 远端remote的层次进行缓存与传输。SGLang 通过一个名为FlexKVRadixCache的RadixCache子类接入 FlexKV其设计模式与已有的 LMCache 集成LMCRadixCache完全同构FlexKVRadixCache覆盖match_prefix/init_load_back/cache_finished_req/evict等调度器侧关键入口FlexKVConnector作为门面façade对外统一封装对KVManager、KVTPClient以及一个三轴PP × CP × TP同步上下文的调用。从源码结构看这一集成把调度器侧的 RadixCache 契约与FlexKV 侧的任务式 API解耦调度器仍然只认识MatchPrefixParams、MatchResult、InitLoadBackParams等标准类型而 FlexKV 的launch/wait/put_match/get_match等任务式调用全部收敛在FlexKVConnector内部见 flexkv_connector.py 的 docstring。快速开始单卡 H20 Qwen3-8B官方在 H20-GPU-11 上验证过下面这条完整路径请按实际环境调整路径、模型与 GPU 数量。1. 前置条件lmsysorg/sglang:dev镜像或任何自带 CUDA 12.x torch 2.10 的 SGLang 容器本仓库文档对应的 sglang fork分支feat/flexkv-main-connector与 FlexKV分支main需要被挂载进容器内可达的目录例如/raid/fly/sglang-connector-dir/{sglang,FlexKV}。文档验证时针对的是 FlexKV main 的aa74e39PR #184再老一些的、直到 layerwise 集成的提交同样可用。2. 启动一个同时挂载两个仓库的容器docker run -d --name flexkv-sglang \ --gpus all --ipchost --network host \ --shm-size32g --cap-add SYS_NICE --cap-add IPC_LOCK \ -v /raid/fly:/raid/fly \ --workdir /raid/fly/sglang-connector-dir \ --entrypoint \ lmsysorg/sglang:dev sleep infinity docker exec flexkv-sglang bash -c apt-get update -qq apt-get install -y numactl libnuma-dev libxxhash-dev liburing-dev cmake ninja-build 说明--ipchost与--shm-size32g服务于大页与共享内存场景--cap-add SYS_NICE --cap-add IPC_LOCK是 FlexKV 传输子进程执行cudaHostRegister等操作所依赖的权限。3. 安装 sglang forkeditable FlexKVdocker exec flexkv-sglang bash -c set -e git config --global --add safe.directory * # sglang fork: install in editable mode, replacing the prebuilt sglang cd /raid/fly/sglang-connector-dir/sglang pip install --no-deps -e python # FlexKV: pin to main, init the xxHash submodule, debug C build. cd /raid/fly/sglang-connector-dir/FlexKV git checkout main git pull --ff-only git submodule update --init third_party/xxHash pip install -q cython ninja pybind11 FLEXKV_ENABLE_METRICS0 bash build.sh --debug # Smoke check python3 -c import sglang, flexkv from flexkv.kvmanager import KVManager from sglang.srt.mem_cache.storage.flexkv import flexkv_comm from sglang.srt.mem_cache.registry import registered_radix_cache_backends import sglang.srt.mem_cache.storage.flexkv # registers print(\flexkv ok\, flexkv.__file__) print(\sglang ok\, sglang.__file__) print(\registered backends:\, registered_radix_cache_backends()) 这段脚本的最后一步很有价值import sglang.srt.mem_cache.storage.flexkv会触发包导入副作用——在__init__.py中通过register_radix_cache_backend(flexkv, _flexkv_factory)把flexkv名字注册进 mem_cache 注册表。打印registered_radix_cache_backends()即可确认注册成功。如果构建卡在pip install sglang-kernel见文末故障排查。4. 最小 FlexKV YAML 配置# /raid/fly/sglang-connector-dir/flexkv_min.yaml cpu_cache_gb: 16仅这一行就足以启用一个 16 GiB 的 CPU 卸载池。SSD / 远端 / 分布式相关的更多旋钮可参考仓库自带的 example_config_mp.yaml其中注释逐项说明了各字段# ---- CPU host-side cache ---------------------------------------------- cpu_cache_gb: 64 # 可选用透明大页钉住 CPU 池 # use_hugepage_cpu_buffer: false # use_hugepage_tmp_buffer: false # hugepage_size_bytes: 2097152 # ---- SSD tier --------------------------------------------------------- # 设置 ssd_cache_gb cpu_cache_gb 即启用 SSD 溢出层 # ssd_cache_gb: 256 # ssd_cache_dir: /mnt/nvme0/flexkv;/mnt/nvme1/flexkv # 用 ; 分隔可做条带化 # enable_gds: false # cuFile / GDS 路径 # ---- KV cache dtype override ----------------------------------------- # 当 sglang 以 --kv-cache-dtype auto 启动时 FlexKV 无法判断实际 KV 张量 dtype # kv_cache_dtype: bfloat16 # ---- Peer / distributed sharing -------------------------------------- # enable_p2p_cpu: false # enable_p2p_ssd: false # enable_3rd_remote: false # ---- Redis (分布式元数据 / KV 共享) ----------------------------------- # redis_host: 127.0.0.1 # redis_port: 6379 # redis_password: null # node_ttl_seconds: 60 # local_ip: 10.0.0.1注意cpu_cache_gb并不是直接决定 block 数量FlexKV 会结合模型 dtype、head dim、KV head 数与页大小推导出num_cpu_blocks对应注释Used to derivenum_cpu_blockstogether with the model dtype, head dim, num kv heads, and page size。5. 启动服务器MP / 同步模式docker exec -d flexkv-sglang bash -c cd /raid/fly/sglang-connector-dir CUDA_VISIBLE_DEVICES0 \ SGLANG_SKIP_SGL_KERNEL_VERSION_CHECK1 \ python3 -m sglang.launch_server \ --model-path /raid/fly/model/Qwen3-8B \ --port 30000 --tp-size 1 \ --enable-flexkv \ --flexkv-config-file /raid/fly/sglang-connector-dir/flexkv_min.yaml \ --mem-fraction-static 0.45 --max-running-requests 8 \ /tmp/sglang.log 21 SGLANG_SKIP_SGL_KERNEL_VERSION_CHECK1用于绕过预编译sglang-kernel的版本断言lmsysorg/sglang:dev镜像自带的 kernel 是 0.4.2.post2而 main 分支要求 ≥ 0.4.3。这并非 FlexKV 特有待镜像刷新后即可去掉。等待约 2 分钟模型加载 CUDA graph 捕获然后用如下命令确认docker exec flexkv-sglang bash -c grep -E fired up|Connector ready /tmp/sglang.log | tail -2 预期关键日志[FlexKV] Connector ready ...: layerwiseFalse, prefetchFalse The server is fired up and ready to roll!Connector ready这行日志来自 flexkv_connector.py其中layerwise反映是否启用逐层传输prefetch反映是否启用了 SSD / 远端 / KV 共享层三者任一开启即视为启用预取。6. 发请求并观察缓存命中# First call: priming — fresh prefill, FlexKV stores the prefix. docker exec flexkv-sglang bash -c curl -s http://127.0.0.1:30000/generate -X POST \ -H Content-Type: application/json \ -d {\text\: \The capital of France is\, \sampling_params\: {\max_new_tokens\: 5, \temperature\: 0}} # Flush the GPU radix (FlexKV CPU pool keeps the data) and re-send. docker exec flexkv-sglang bash -c curl -s http://127.0.0.1:30000/flush_cache -X POST curl -s http://127.0.0.1:30000/generate -X POST \ -H Content-Type: application/json \ -d {\text\: \The capital of France is\, \sampling_params\: {\max_new_tokens\: 5, \temperature\: 0}} 第一次请求是预热全新 prefillFlexKV 在cache_finished_req阶段把该前缀异步写回宿主层。紧接着flush_cache清空 GPU 上的 radix 树但 FlexKV 的 CPU 池仍保留数据。第二次请求的meta_info应显示cached_tokens: 4, cached_tokens_details: { device: 0, host: 4 },host: 4说明这 4 个 token 的 KV 是从 FlexKV 的 CPU 池取回的。服务端日志还应该出现对应的 D2H/H2D 带宽行[FLEXKV] ... H2D transfer request: N finished transfer data size: 0.0xx GB ... 30 GB/sLayerwise逐层传输模式在python3 -m sglang.launch_server之前加上环境变量即可切换FLEXKV_ENABLE_LAYERWISE_TRANSFER1其余配置完全不变。第二次请求时会观察到cached_tokens_details: {device: N, host: 0}——在 IP 模式下加载发生在match_prefix内部因此 SGLang 将其计为设备侧命中日志中出现LAYERWISE transfer request: N finished ...启动日志中会出现[FlexKV] Eventfd handshake complete ... counters3 layersN。counters3对应 flexkv_comm.py 中FlexKVLayerDoneCounter的三缓冲设计num_counters3生产者槽位轮转允许下一次预取在当前任务消费完成前就开始从而隐藏传输延迟。两种模式的具体语义差异见下文两种运行模式的源码级剖析。后端选择两条等价的 CLI 路径仓库提供了两种等效的后端选择方式# 自动选择链与 --enable-lmcache 风格一致 python3 -m sglang.launch_server --enable-flexkv \ --flexkv-config-file /path/to/flexkv_config.yaml ... # 显式注册表路径 python3 -m sglang.launch_server --radix-cache-backend flexkv \ --flexkv-config-file /path/to/flexkv_config.yaml ...任意一种写法都会顺带设置FLEXKV_CONFIG_PATH环境变量因此可以省略--flexkv-config-file完全通过环境变量配置 FlexKV。从 memory.py 参数定义 可以看到两者的官方语义--enable-flexkv把默认 RadixCache 路由到 FlexKV 的KVManager做宿主层卸载与--radix-cache-backendflexkv等价但同时参与--enable-lmcache同级的自动选择链--flexkv-config-fileFlexKV YAML / JSON 配置路径等价于设置FLEXKV_CONFIG_PATH。底层逻辑在 registry.py 的default_radix_cache_factory中当--enable-flexkv命中时先导入sglang.srt.mem_cache.storage.flexkv包注册显式名字flexkv再把--flexkv-config-file通过环境变量FLEXKV_CONFIG_PATH转发给 FlexKV 自己的配置加载器FlexKVConfig.from_env()见 flexkv_connector.py最后直接调用_flexkv_factory(ctx)构造缓存。而--radix-cache-backendflexkv走的是create_tree_cache中get_radix_cache_factory(name)的注册表查询路径registry.py。_flexkv_factoryflexkv/init.py从TreeCacheBuildContext中取出 TP rank/size 与 TP 组再通过sglang.srt.distributed.parallel_state的全局访问器补齐 PP 组、attention TP 组与 attention CP 组构造出FlexKVRadixCache。两种运行模式的源码级剖析FlexKVRadixCache构造时flexkv_radix_cache.py依据FLEXKV_ENABLE_LAYERWISE_TRANSFER决定模式启用则为FlexKVMode.IP否则为FlexKVMode.MP。两种模式在match_prefix处flexkv_radix_cache.py分派到不同的子路径。MP同步默认MP 模式下调用链是两阶段的match_prefix→_mp_match_prefixflexkv_radix_cache.py只调用FlexKVConnector.lookup_kv做前缀查找。查找前先把查询 key 向下对齐到page_size的整数倍aligned_len (len(key) // page_size) * page_size保证回报给调度器的命中数不超过 FlexKV 实际能按页服务的能力查找时构造token_maskdevice 上已存在的 token 为 False其余为 TrueFlexKV 据此判断哪些 token 可服务。命中后把匹配 key 的快照RadixKey存入self._load_markers[req.rid]并以host_hit_lengthhit返回MatchResult。调度器在派发阶段看到host_hit_length 0后调用init_load_back→_allocate_and_loadflexkv_radix_cache.py先从 KV pool 分配未被缓存的 slot必要时先evict腾空间再调用FlexKVConnector.retrieve_kv其内部执行 FlexKV 的launchwait同步等待超时 30 s见 flexkv_connector.py把宿主层 KV 搬回 GPU。若 FlexKV 实际返回的 token 少于预期则释放超配 slot 的尾部。cache_finished_reqflexkv_radix_cache.py先调用基类完成设备侧入树再计算 committed 前缀对非 speculative-EAGLE 模型用req.kv.kv_committed_len对 EAGLE 模型退化为origin_input_ids output_ids[:-1]然后调用FlexKVConnector.store_kv发起异步写回。写回期间源节点被加锁inc_lock_ref只有check_completed_stores由check_hicache_events/evict触发确认 FlexKV 任务完成后才dec_lock_ref解锁——_inflight_store_nodes[rid]记录了 rid → TreeNode 的映射flexkv_radix_cache.py。MP 模式是任何非平凡部署拓扑DP 1、多实例、多节点下应使用的路径。evict在把源节点交给基类驱逐前会先排水已完成的写回_drain_completed_stores并store_stream.synchronize()确保 GPU 侧写回被观察到check_hicache_events则由调度器 tick 周期性地非阻塞排水同时drain_launched_loads清理长时间存活的任务避免 FlexKV 管道积压flexkv_radix_cache.py。IP / LayerwiseFLEXKV_ENABLE_LAYERWISE_TRANSFER1IP 模式下时序被大幅压缩match_prefix→_ip_match_prefixflexkv_radix_cache.py先做一次快速lookup_kv探测命中数使用合成的稳定 rid_ip_key-id命中后立即分配 slot 并调用FlexKVConnector.start_load_kv_layerwise启动逐层异步加载。FlexKVLayerDoneCounter通过register_layer_transfer_counter注册到 SGLang 的 KV pool 上flexkv_radix_cache.py。模型 forward 的每一层都会调用wait_until(layer_id)阻塞在该层自己的 eventfd 上直到 FlexKV 传输工作线程把该层 H2D 拷贝完成并写入信号flexkv_comm.py。启动时连接器需要通过 UDS socket默认/tmp/flexkv_layerwise_eventfd.sock与 FlexKV 的传输工作线程握手。握手细节在 flexkv_connector.py通过SCM_RIGHTS辅助数据把每个 counter 的 eventfd 文件描述符发送给工作线程并等待 1 字节 ACK。socket 路径由 FlexKV 的build_layerwise_eventfd_socket_path依据相同的 dp/pp/instance 设置计算因此只要以一致的方式启动 FlexKV配置即可自动对齐。FlexKVLayerLoadingEvent.wait的实现值得一提flexkv_comm.pyeventfd 以EFD_SEMAPHORE | EFD_NONBLOCK创建使reset_for_new_transfer能无阻塞地排空上一轮残留信号而wait则通过select.select在 NONBLOCK fd 上重新获得阻塞语义保证读取恰好消费一个信号。这正是 README 中标注的layerwise 正确性修复所在若不做排空上一轮传输残留的信号会让下一轮首层wait立即返回导致 forward 读到错误的 KV 数据。多维度并行拓扑TP / PP / CP / DPFlexKV 为每个 DP 路由instance_id * dp_size dp_rank运行一个KVManager同一 fan-out 中的其他 rank 是同步跟随者——FlexKVComm通过 gloo CPU 组广播 leader 的 lookup / store 决策使非 leader rank 也能获知该用哪个任务 id 与哪些 slot 映射。FlexKVCommflexkv_comm.py是sync leaderpp_rank0 且 attn_cp_rank0 且 attn_tp_rank0 的唯一 rank与其余 rank 之间的分层同步上下文支持scatter三级扇出sync_leader → PP stage leaders → CP leaders → TP ranks、scatter_ppPP 专用 P2P、all_reduce_min用于对齐各 rank 的 block 数上限与barrier。P2P 走全局 gloo CPU 组并选择不与 SGLang 自身 P2P 冲突的 4 字节 tag如FxSc、FxPP、FxCP、FxTP为避免 glooisendWork 对象轮询不前进导致的泄漏还实现了带自适应水位的异步 work 回收器_reap_high在_REAP_HIGH_BASE1024与_REAP_HIGH_MAX32768之间动态调整见 flexkv_comm.py。支持情况TP任意大小——标准 SGLang 拓扑DPdp_size 1与多实例——FlexKV 自动把KVManager切换为 server-client 模式PPpp_size 1——含跨节点 PP。PP 接收端receiver通过 ZMQ 通道把自己的 slot 映射转发回 FlexKV 的TransferManagerOnRemote即should_send_slot_mapping_to_remote分支flexkv_connector.py该通道与 GPU 注册共用CPattn_cp_size 1——与 TP 对称处理DP attentionenable_dp_attentionTrue——注册侧路由使用的是内部attn_tp_size。另外多节点场景下 node_rank 0 的 local_rank 0 进程会在注册 GPU buffer 前先拉起TransferManagerOnRemote子进程flexkv_connector.pyGPU 注册本身带重试_register_with_retry最多约 6 分钟flexkv_connector.py以容忍远端管理进程尚未就绪。环境变量一览环境变量作用FLEXKV_CONFIG_PATH完整 FlexKV YAML / JSON 配置路径--flexkv-config-file会自动设置它FLEXKV_ENABLE_LAYERWISE_TRANSFER设为1启用逐层layerwise传输模式FLEXKV_LAYERWISE_EVENTFD_SOCKETUDS socket 路径默认/tmp/flexkv_layerwise_eventfd.sock当 PP 或 DP 维度 1 时按(pp_rank, dp_client_id)自动加后缀FLEXKV_MASTER_HOST/FLEXKV_MASTER_PORTS多节点TransferManagerOnRemote的 master 端点默认localhost:5556,5557,5558当nnodes 1时回退使用server_args.dist_init_addr的主机名FLEXKV_KV_CACHE_DTYPE当 SGLang 使用--kv-cache-dtype auto时覆盖 KV dtypeSGLANG_SKIP_SGL_KERNEL_VERSION_CHECK绕过预编译sglang-kernel版本断言非 FlexKV 特有正确性验证仓库在 verify_outputs.py 中提供了与无 FlexKV 基线的数值比对脚本greedy 解码、确定性。核心流程分两阶段# Phase 1: capture the no-FlexKV baseline. docker exec -d flexkv-sglang bash -c CUDA_VISIBLE_DEVICES0 SGLANG_SKIP_SGL_KERNEL_VERSION_CHECK1 \ python3 -m sglang.launch_server \ --model-path /raid/fly/model/Qwen3-8B --port 30000 --tp-size 1 \ --mem-fraction-static 0.45 /tmp/sglang.log 21 # ... wait until ready ... docker exec flexkv-sglang python3 /raid/fly/sglang-connector-dir/sglang/python/sglang/srt/mem_cache/storage/flexkv/verify_outputs.py --phase baseline docker exec flexkv-sglang bash -c pkill -9 -f launch_server; sleep 3 # Phase 2: relaunch with --enable-flexkv and compare. docker exec -d flexkv-sglang bash -c CUDA_VISIBLE_DEVICES0 SGLANG_SKIP_SGL_KERNEL_VERSION_CHECK1 \ python3 -m sglang.launch_server \ --model-path /raid/fly/model/Qwen3-8B --port 30000 --tp-size 1 \ --enable-flexkv --flexkv-config-file /raid/fly/sglang-connector-dir/flexkv_min.yaml \ --mem-fraction-static 0.45 /tmp/sglang.log 21 # ... wait until ready ... docker exec flexkv-sglang python3 /raid/fly/sglang-connector-dir/sglang/python/sglang/srt/mem_cache/storage/flexkv/verify_outputs.py --phase test预期最后一行输出Total mismatches: 0。脚本内部每个 prompt 跑两次R1 冷启动 / R2 在flush_cache之后并要求 R1 与 R2 的output_ids都逐字节等于基线verify_outputs.py。R2 阶段还会打印命中率cached_tokens / prompt_tokens用于确认宿主层命中确实发生。脚本内置了三个 prompt 覆盖SHORT12 token、MEDIUM24 token与 LONG横跨多个 KV 页的长文本。如需验证 layerwise 路径用FLEXKV_ENABLE_LAYERWISE_TRANSFER1重复 Phase-2 启动即可。故障排查文档与源码共同确认的典型问题与对策fatal: not a git repository ... third_party/xxHash—— FlexKV 的 build.sh 需要真实 git checkout 才能初始化子模块。若通过 rsync 同步 FlexKV 且没有.git/需补齐rsync -az /path/to/FlexKV/.git/ remote:dir/FlexKV/.git/然后git config --global --add safe.directory *。fatal: detected dubious ownership—— 同上执行git config --global --add safe.directory *。xxhash.h: No such file or directory—— 子模块未初始化cd FlexKV git submodule update --init third_party/xxHash。dist/lease_meta_mempool.h: No such file or directory—— rsync 时排除了csrc/dist/。注意FlexKV/csrc/dist/是源码而非构建产物请去掉--excludedist重新同步。No module named Cython—— 安装依赖pip install cython ninja pybind11。sglang-kernel is installed with version 0.4.2.post2, which is less than the minimum required version 0.4.3—— 二选一带SGLANG_SKIP_SGL_KERNEL_VERSION_CHECK1运行或pip install -U sglang-kernel刷新。后者下载约 600 MB慢速网络下耗时较长。cudaHostRegister failed with error code 100cudaErrorNoDevice—— FlexKV 传输子进程无法在指定设备上初始化 CUDA通常由上一个残留会话导致重启容器即可。[FlexKV] Waiting for FlexKV ready循环超过 60 s——KVManager子进程启动时崩溃检查/tmp/sglang.log中的实际堆栈多为 CUDA 初始化或 torch 多进程问题。Layerwise 模式服务器卡在Eventfd connected attempts...——LayerwiseTransferWorker尚未启动。Eventfd server created之后它可能需要 20~30 秒若长时间无进展检查 FlexKV 侧以[LayerwiseWorker]开头的日志行。状态与已知限制当前验证状态MP同步路径——已在 Qwen3-8BH20-3e上端到端验证短 / 中 / 长 prompt 输出均与无 FlexKV 基线逐字节一致观测到 D2H 存储约 30–46 GB/sH2D 加载约 37 GB/s。IPlayerwise路径——已携带flexkv_comm.py中的修复端到端验证每层约 7–12 GB/s单次调用载荷更小。PP / CP / DP / 多节点——代码路径由FlexKVComm驱动沿用自生产验证过的BaseKVConnector集成未在单卡冒烟测试中覆盖上线前需要多节点验证。已知限制混合模型不支持Mamba / SWA / DSV4 indexer 辅助池等混合模型无法通过本连接器接入——当前只挂接了主 KV 池。HiCache 的多池batch_*_v2接口理论上可以映射过来但需要先为FlexKVConnector补齐PoolTransfer与PoolHitPolicy管道。写回确认是请求级的每个cache_finished_req对应一次dec_lock_ref而不是像 HiCache 的 write-through ack 队列那样按页确认。--radix-cache-backendflexkv与--enable-flexkv目前完全等价两者同时设置时尚未发出弃用警告。基准测试暖缓存命中收益仓库 README 记录的基准设置如下Qwen3-8B 单卡 H20服务器参数--attention-backend triton --mem-fraction-static 0.32 --max-running-requests 32 --chunked-prefill-size 16384 --context-length 32000负载为从 SWE-bench_Lite_oracle 采样的 120 条 prompt输入长度 ≤ 28k tokenp50 7088最大 27961pass 1 填充宿主缓存pass 2 为实测轮qps2.0、concurrency24、max_new_tokens32、temperature0。暖缓存轮结果ConfigTTFT avg / p50 / p90 / p99E2E p50ThroughputOutput tok/sH2D / D2Hbaseline6.86 / 8.04 / 9.88 / 10.89 s8.15 s1.86 req/s37.7—--enable-hierarchical-cache0.04 / 0.04 / 0.06 / 0.06 s0.23 s2.02 req/s40.8—--enable-flexkv0.05 / 0.05 / 0.07 / 0.08 s0.24 s2.02 req/s40.886 / 155服务端侧SGLang 日志中的ReqTimeStats76 个非 EOS 立即返回的暖缓存请求中hicache与flexkv均有 76 个达到cached_input_len input_len100% 前缀恢复baseline 停留在约 59 token仅系统 prompt 头部。flexkv下 86 条H2D transfer日志行证实 CPU 层加载真实发生。输出正确性方面对 32 条 prompt、temperature0做逐字节 diffbaseline冷轮 暖轮32 / 32无缓存时完全确定hicache暖轮 vs baseline 暖轮——29 / 32 一致3 条分歧flexkv暖轮 vs baseline 暖轮——29 / 32 一致3 条分歧与hicache基本是同一批。temperature0下约 10% 的分歧是众所周知的 KV 缓存复用伪影浮点非结合性导致原位 prefill与加载预计算 KV两条路径结果略有差异。它同样影响主线--enable-hierarchical-cache并非 FlexKV 特有。模块文件清单FlexKV 集成模块位于 python/sglang/srt/mem_cache/storage/flexkv/flexkv_radix_cache.py ——FlexKVRadixCache(RadixCache)覆盖match_prefix、init_load_back、cache_finished_req、evict、check_hicache_events、resetflexkv_connector.py ——FlexKVConnector持有KVManager、KVTPClient与跨 rank 同步上下文公共方法包括lookup_kv、retrieve_kv、start_load_kv_layerwise、store_kv、check_completed_stores、prefetch_async等flexkv_comm.py ——FlexKVComm基于 torch.distributed 的 PP × CP × TP 三轴同步与 layerwise UDS 握手使用的 eventfd /SCM_RIGHTS封装FlexKVLayerLoadingEvent在此承载 layerwise 正确性修复reset 时排空残留 eventfd 信号、用select.select在 NONBLOCK fd 上保持阻塞语义init.py —— 通过sglang.srt.mem_cache.registry注册flexkv工厂example_config_mp.yaml —— SSD / 远端 / 分布式旋钮的完整示例配置verify_outputs.py —— 端到端正确性验证脚本。接入点的注册表实现在 mem_cache/registry.pyCLI 参数定义在 arg_groups/fields/memory.py供希望扩展自定义 RadixCache 后端的开发者参考。【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SGLang 接入 FlexKV：用 CPU/SSD/远端分层 KV Cache 扩展 RadixCache 的主机端卸载实战指南
SGLang 接入 FlexKV用 CPU/SSD/远端分层 KV Cache 扩展 RadixCache 的主机端卸载实战指南【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang导读本文围绕 SGLang 仓库中 FlexKV 集成模块 展开讲解如何通过一个继承自RadixCache的FlexKVRadixCache子类把 SGLang 的宿主层host-tierKV Cache 路由到 FlexKV 的KVManagerCPU / SSD / 远端卸载从而在 GPU 显存不足时把前缀 KV 持久化到更廉价的分层存储并实现前缀命中复用。读完本文你将掌握 FlexKV 后端的完整部署流程Docker 容器、editable 安装、最小 YAML、服务器启动与缓存命中验证、MP同步与 IPlayerwise 逐层传输两种运行模式的区别、PP × CP × TP 多轴并行下的同步机制、全部环境变量与常见故障排查方法并能依据仓库源码理解lookup_kv/retrieve_kv/store_kv等核心调用链的底层原理。FlexKV 与 SGLang 的集成模式FlexKV 是一个面向大模型推理的宿主层 KV Cache 管理组件负责把 KV 数据按 CPU 内存 → SSD → 远端remote的层次进行缓存与传输。SGLang 通过一个名为FlexKVRadixCache的RadixCache子类接入 FlexKV其设计模式与已有的 LMCache 集成LMCRadixCache完全同构FlexKVRadixCache覆盖match_prefix/init_load_back/cache_finished_req/evict等调度器侧关键入口FlexKVConnector作为门面façade对外统一封装对KVManager、KVTPClient以及一个三轴PP × CP × TP同步上下文的调用。从源码结构看这一集成把调度器侧的 RadixCache 契约与FlexKV 侧的任务式 API解耦调度器仍然只认识MatchPrefixParams、MatchResult、InitLoadBackParams等标准类型而 FlexKV 的launch/wait/put_match/get_match等任务式调用全部收敛在FlexKVConnector内部见 flexkv_connector.py 的 docstring。快速开始单卡 H20 Qwen3-8B官方在 H20-GPU-11 上验证过下面这条完整路径请按实际环境调整路径、模型与 GPU 数量。1. 前置条件lmsysorg/sglang:dev镜像或任何自带 CUDA 12.x torch 2.10 的 SGLang 容器本仓库文档对应的 sglang fork分支feat/flexkv-main-connector与 FlexKV分支main需要被挂载进容器内可达的目录例如/raid/fly/sglang-connector-dir/{sglang,FlexKV}。文档验证时针对的是 FlexKV main 的aa74e39PR #184再老一些的、直到 layerwise 集成的提交同样可用。2. 启动一个同时挂载两个仓库的容器docker run -d --name flexkv-sglang \ --gpus all --ipchost --network host \ --shm-size32g --cap-add SYS_NICE --cap-add IPC_LOCK \ -v /raid/fly:/raid/fly \ --workdir /raid/fly/sglang-connector-dir \ --entrypoint \ lmsysorg/sglang:dev sleep infinity docker exec flexkv-sglang bash -c apt-get update -qq apt-get install -y numactl libnuma-dev libxxhash-dev liburing-dev cmake ninja-build 说明--ipchost与--shm-size32g服务于大页与共享内存场景--cap-add SYS_NICE --cap-add IPC_LOCK是 FlexKV 传输子进程执行cudaHostRegister等操作所依赖的权限。3. 安装 sglang forkeditable FlexKVdocker exec flexkv-sglang bash -c set -e git config --global --add safe.directory * # sglang fork: install in editable mode, replacing the prebuilt sglang cd /raid/fly/sglang-connector-dir/sglang pip install --no-deps -e python # FlexKV: pin to main, init the xxHash submodule, debug C build. cd /raid/fly/sglang-connector-dir/FlexKV git checkout main git pull --ff-only git submodule update --init third_party/xxHash pip install -q cython ninja pybind11 FLEXKV_ENABLE_METRICS0 bash build.sh --debug # Smoke check python3 -c import sglang, flexkv from flexkv.kvmanager import KVManager from sglang.srt.mem_cache.storage.flexkv import flexkv_comm from sglang.srt.mem_cache.registry import registered_radix_cache_backends import sglang.srt.mem_cache.storage.flexkv # registers print(\flexkv ok\, flexkv.__file__) print(\sglang ok\, sglang.__file__) print(\registered backends:\, registered_radix_cache_backends()) 这段脚本的最后一步很有价值import sglang.srt.mem_cache.storage.flexkv会触发包导入副作用——在__init__.py中通过register_radix_cache_backend(flexkv, _flexkv_factory)把flexkv名字注册进 mem_cache 注册表。打印registered_radix_cache_backends()即可确认注册成功。如果构建卡在pip install sglang-kernel见文末故障排查。4. 最小 FlexKV YAML 配置# /raid/fly/sglang-connector-dir/flexkv_min.yaml cpu_cache_gb: 16仅这一行就足以启用一个 16 GiB 的 CPU 卸载池。SSD / 远端 / 分布式相关的更多旋钮可参考仓库自带的 example_config_mp.yaml其中注释逐项说明了各字段# ---- CPU host-side cache ---------------------------------------------- cpu_cache_gb: 64 # 可选用透明大页钉住 CPU 池 # use_hugepage_cpu_buffer: false # use_hugepage_tmp_buffer: false # hugepage_size_bytes: 2097152 # ---- SSD tier --------------------------------------------------------- # 设置 ssd_cache_gb cpu_cache_gb 即启用 SSD 溢出层 # ssd_cache_gb: 256 # ssd_cache_dir: /mnt/nvme0/flexkv;/mnt/nvme1/flexkv # 用 ; 分隔可做条带化 # enable_gds: false # cuFile / GDS 路径 # ---- KV cache dtype override ----------------------------------------- # 当 sglang 以 --kv-cache-dtype auto 启动时 FlexKV 无法判断实际 KV 张量 dtype # kv_cache_dtype: bfloat16 # ---- Peer / distributed sharing -------------------------------------- # enable_p2p_cpu: false # enable_p2p_ssd: false # enable_3rd_remote: false # ---- Redis (分布式元数据 / KV 共享) ----------------------------------- # redis_host: 127.0.0.1 # redis_port: 6379 # redis_password: null # node_ttl_seconds: 60 # local_ip: 10.0.0.1注意cpu_cache_gb并不是直接决定 block 数量FlexKV 会结合模型 dtype、head dim、KV head 数与页大小推导出num_cpu_blocks对应注释Used to derivenum_cpu_blockstogether with the model dtype, head dim, num kv heads, and page size。5. 启动服务器MP / 同步模式docker exec -d flexkv-sglang bash -c cd /raid/fly/sglang-connector-dir CUDA_VISIBLE_DEVICES0 \ SGLANG_SKIP_SGL_KERNEL_VERSION_CHECK1 \ python3 -m sglang.launch_server \ --model-path /raid/fly/model/Qwen3-8B \ --port 30000 --tp-size 1 \ --enable-flexkv \ --flexkv-config-file /raid/fly/sglang-connector-dir/flexkv_min.yaml \ --mem-fraction-static 0.45 --max-running-requests 8 \ /tmp/sglang.log 21 SGLANG_SKIP_SGL_KERNEL_VERSION_CHECK1用于绕过预编译sglang-kernel的版本断言lmsysorg/sglang:dev镜像自带的 kernel 是 0.4.2.post2而 main 分支要求 ≥ 0.4.3。这并非 FlexKV 特有待镜像刷新后即可去掉。等待约 2 分钟模型加载 CUDA graph 捕获然后用如下命令确认docker exec flexkv-sglang bash -c grep -E fired up|Connector ready /tmp/sglang.log | tail -2 预期关键日志[FlexKV] Connector ready ...: layerwiseFalse, prefetchFalse The server is fired up and ready to roll!Connector ready这行日志来自 flexkv_connector.py其中layerwise反映是否启用逐层传输prefetch反映是否启用了 SSD / 远端 / KV 共享层三者任一开启即视为启用预取。6. 发请求并观察缓存命中# First call: priming — fresh prefill, FlexKV stores the prefix. docker exec flexkv-sglang bash -c curl -s http://127.0.0.1:30000/generate -X POST \ -H Content-Type: application/json \ -d {\text\: \The capital of France is\, \sampling_params\: {\max_new_tokens\: 5, \temperature\: 0}} # Flush the GPU radix (FlexKV CPU pool keeps the data) and re-send. docker exec flexkv-sglang bash -c curl -s http://127.0.0.1:30000/flush_cache -X POST curl -s http://127.0.0.1:30000/generate -X POST \ -H Content-Type: application/json \ -d {\text\: \The capital of France is\, \sampling_params\: {\max_new_tokens\: 5, \temperature\: 0}} 第一次请求是预热全新 prefillFlexKV 在cache_finished_req阶段把该前缀异步写回宿主层。紧接着flush_cache清空 GPU 上的 radix 树但 FlexKV 的 CPU 池仍保留数据。第二次请求的meta_info应显示cached_tokens: 4, cached_tokens_details: { device: 0, host: 4 },host: 4说明这 4 个 token 的 KV 是从 FlexKV 的 CPU 池取回的。服务端日志还应该出现对应的 D2H/H2D 带宽行[FLEXKV] ... H2D transfer request: N finished transfer data size: 0.0xx GB ... 30 GB/sLayerwise逐层传输模式在python3 -m sglang.launch_server之前加上环境变量即可切换FLEXKV_ENABLE_LAYERWISE_TRANSFER1其余配置完全不变。第二次请求时会观察到cached_tokens_details: {device: N, host: 0}——在 IP 模式下加载发生在match_prefix内部因此 SGLang 将其计为设备侧命中日志中出现LAYERWISE transfer request: N finished ...启动日志中会出现[FlexKV] Eventfd handshake complete ... counters3 layersN。counters3对应 flexkv_comm.py 中FlexKVLayerDoneCounter的三缓冲设计num_counters3生产者槽位轮转允许下一次预取在当前任务消费完成前就开始从而隐藏传输延迟。两种模式的具体语义差异见下文两种运行模式的源码级剖析。后端选择两条等价的 CLI 路径仓库提供了两种等效的后端选择方式# 自动选择链与 --enable-lmcache 风格一致 python3 -m sglang.launch_server --enable-flexkv \ --flexkv-config-file /path/to/flexkv_config.yaml ... # 显式注册表路径 python3 -m sglang.launch_server --radix-cache-backend flexkv \ --flexkv-config-file /path/to/flexkv_config.yaml ...任意一种写法都会顺带设置FLEXKV_CONFIG_PATH环境变量因此可以省略--flexkv-config-file完全通过环境变量配置 FlexKV。从 memory.py 参数定义 可以看到两者的官方语义--enable-flexkv把默认 RadixCache 路由到 FlexKV 的KVManager做宿主层卸载与--radix-cache-backendflexkv等价但同时参与--enable-lmcache同级的自动选择链--flexkv-config-fileFlexKV YAML / JSON 配置路径等价于设置FLEXKV_CONFIG_PATH。底层逻辑在 registry.py 的default_radix_cache_factory中当--enable-flexkv命中时先导入sglang.srt.mem_cache.storage.flexkv包注册显式名字flexkv再把--flexkv-config-file通过环境变量FLEXKV_CONFIG_PATH转发给 FlexKV 自己的配置加载器FlexKVConfig.from_env()见 flexkv_connector.py最后直接调用_flexkv_factory(ctx)构造缓存。而--radix-cache-backendflexkv走的是create_tree_cache中get_radix_cache_factory(name)的注册表查询路径registry.py。_flexkv_factoryflexkv/init.py从TreeCacheBuildContext中取出 TP rank/size 与 TP 组再通过sglang.srt.distributed.parallel_state的全局访问器补齐 PP 组、attention TP 组与 attention CP 组构造出FlexKVRadixCache。两种运行模式的源码级剖析FlexKVRadixCache构造时flexkv_radix_cache.py依据FLEXKV_ENABLE_LAYERWISE_TRANSFER决定模式启用则为FlexKVMode.IP否则为FlexKVMode.MP。两种模式在match_prefix处flexkv_radix_cache.py分派到不同的子路径。MP同步默认MP 模式下调用链是两阶段的match_prefix→_mp_match_prefixflexkv_radix_cache.py只调用FlexKVConnector.lookup_kv做前缀查找。查找前先把查询 key 向下对齐到page_size的整数倍aligned_len (len(key) // page_size) * page_size保证回报给调度器的命中数不超过 FlexKV 实际能按页服务的能力查找时构造token_maskdevice 上已存在的 token 为 False其余为 TrueFlexKV 据此判断哪些 token 可服务。命中后把匹配 key 的快照RadixKey存入self._load_markers[req.rid]并以host_hit_lengthhit返回MatchResult。调度器在派发阶段看到host_hit_length 0后调用init_load_back→_allocate_and_loadflexkv_radix_cache.py先从 KV pool 分配未被缓存的 slot必要时先evict腾空间再调用FlexKVConnector.retrieve_kv其内部执行 FlexKV 的launchwait同步等待超时 30 s见 flexkv_connector.py把宿主层 KV 搬回 GPU。若 FlexKV 实际返回的 token 少于预期则释放超配 slot 的尾部。cache_finished_reqflexkv_radix_cache.py先调用基类完成设备侧入树再计算 committed 前缀对非 speculative-EAGLE 模型用req.kv.kv_committed_len对 EAGLE 模型退化为origin_input_ids output_ids[:-1]然后调用FlexKVConnector.store_kv发起异步写回。写回期间源节点被加锁inc_lock_ref只有check_completed_stores由check_hicache_events/evict触发确认 FlexKV 任务完成后才dec_lock_ref解锁——_inflight_store_nodes[rid]记录了 rid → TreeNode 的映射flexkv_radix_cache.py。MP 模式是任何非平凡部署拓扑DP 1、多实例、多节点下应使用的路径。evict在把源节点交给基类驱逐前会先排水已完成的写回_drain_completed_stores并store_stream.synchronize()确保 GPU 侧写回被观察到check_hicache_events则由调度器 tick 周期性地非阻塞排水同时drain_launched_loads清理长时间存活的任务避免 FlexKV 管道积压flexkv_radix_cache.py。IP / LayerwiseFLEXKV_ENABLE_LAYERWISE_TRANSFER1IP 模式下时序被大幅压缩match_prefix→_ip_match_prefixflexkv_radix_cache.py先做一次快速lookup_kv探测命中数使用合成的稳定 rid_ip_key-id命中后立即分配 slot 并调用FlexKVConnector.start_load_kv_layerwise启动逐层异步加载。FlexKVLayerDoneCounter通过register_layer_transfer_counter注册到 SGLang 的 KV pool 上flexkv_radix_cache.py。模型 forward 的每一层都会调用wait_until(layer_id)阻塞在该层自己的 eventfd 上直到 FlexKV 传输工作线程把该层 H2D 拷贝完成并写入信号flexkv_comm.py。启动时连接器需要通过 UDS socket默认/tmp/flexkv_layerwise_eventfd.sock与 FlexKV 的传输工作线程握手。握手细节在 flexkv_connector.py通过SCM_RIGHTS辅助数据把每个 counter 的 eventfd 文件描述符发送给工作线程并等待 1 字节 ACK。socket 路径由 FlexKV 的build_layerwise_eventfd_socket_path依据相同的 dp/pp/instance 设置计算因此只要以一致的方式启动 FlexKV配置即可自动对齐。FlexKVLayerLoadingEvent.wait的实现值得一提flexkv_comm.pyeventfd 以EFD_SEMAPHORE | EFD_NONBLOCK创建使reset_for_new_transfer能无阻塞地排空上一轮残留信号而wait则通过select.select在 NONBLOCK fd 上重新获得阻塞语义保证读取恰好消费一个信号。这正是 README 中标注的layerwise 正确性修复所在若不做排空上一轮传输残留的信号会让下一轮首层wait立即返回导致 forward 读到错误的 KV 数据。多维度并行拓扑TP / PP / CP / DPFlexKV 为每个 DP 路由instance_id * dp_size dp_rank运行一个KVManager同一 fan-out 中的其他 rank 是同步跟随者——FlexKVComm通过 gloo CPU 组广播 leader 的 lookup / store 决策使非 leader rank 也能获知该用哪个任务 id 与哪些 slot 映射。FlexKVCommflexkv_comm.py是sync leaderpp_rank0 且 attn_cp_rank0 且 attn_tp_rank0 的唯一 rank与其余 rank 之间的分层同步上下文支持scatter三级扇出sync_leader → PP stage leaders → CP leaders → TP ranks、scatter_ppPP 专用 P2P、all_reduce_min用于对齐各 rank 的 block 数上限与barrier。P2P 走全局 gloo CPU 组并选择不与 SGLang 自身 P2P 冲突的 4 字节 tag如FxSc、FxPP、FxCP、FxTP为避免 glooisendWork 对象轮询不前进导致的泄漏还实现了带自适应水位的异步 work 回收器_reap_high在_REAP_HIGH_BASE1024与_REAP_HIGH_MAX32768之间动态调整见 flexkv_comm.py。支持情况TP任意大小——标准 SGLang 拓扑DPdp_size 1与多实例——FlexKV 自动把KVManager切换为 server-client 模式PPpp_size 1——含跨节点 PP。PP 接收端receiver通过 ZMQ 通道把自己的 slot 映射转发回 FlexKV 的TransferManagerOnRemote即should_send_slot_mapping_to_remote分支flexkv_connector.py该通道与 GPU 注册共用CPattn_cp_size 1——与 TP 对称处理DP attentionenable_dp_attentionTrue——注册侧路由使用的是内部attn_tp_size。另外多节点场景下 node_rank 0 的 local_rank 0 进程会在注册 GPU buffer 前先拉起TransferManagerOnRemote子进程flexkv_connector.pyGPU 注册本身带重试_register_with_retry最多约 6 分钟flexkv_connector.py以容忍远端管理进程尚未就绪。环境变量一览环境变量作用FLEXKV_CONFIG_PATH完整 FlexKV YAML / JSON 配置路径--flexkv-config-file会自动设置它FLEXKV_ENABLE_LAYERWISE_TRANSFER设为1启用逐层layerwise传输模式FLEXKV_LAYERWISE_EVENTFD_SOCKETUDS socket 路径默认/tmp/flexkv_layerwise_eventfd.sock当 PP 或 DP 维度 1 时按(pp_rank, dp_client_id)自动加后缀FLEXKV_MASTER_HOST/FLEXKV_MASTER_PORTS多节点TransferManagerOnRemote的 master 端点默认localhost:5556,5557,5558当nnodes 1时回退使用server_args.dist_init_addr的主机名FLEXKV_KV_CACHE_DTYPE当 SGLang 使用--kv-cache-dtype auto时覆盖 KV dtypeSGLANG_SKIP_SGL_KERNEL_VERSION_CHECK绕过预编译sglang-kernel版本断言非 FlexKV 特有正确性验证仓库在 verify_outputs.py 中提供了与无 FlexKV 基线的数值比对脚本greedy 解码、确定性。核心流程分两阶段# Phase 1: capture the no-FlexKV baseline. docker exec -d flexkv-sglang bash -c CUDA_VISIBLE_DEVICES0 SGLANG_SKIP_SGL_KERNEL_VERSION_CHECK1 \ python3 -m sglang.launch_server \ --model-path /raid/fly/model/Qwen3-8B --port 30000 --tp-size 1 \ --mem-fraction-static 0.45 /tmp/sglang.log 21 # ... wait until ready ... docker exec flexkv-sglang python3 /raid/fly/sglang-connector-dir/sglang/python/sglang/srt/mem_cache/storage/flexkv/verify_outputs.py --phase baseline docker exec flexkv-sglang bash -c pkill -9 -f launch_server; sleep 3 # Phase 2: relaunch with --enable-flexkv and compare. docker exec -d flexkv-sglang bash -c CUDA_VISIBLE_DEVICES0 SGLANG_SKIP_SGL_KERNEL_VERSION_CHECK1 \ python3 -m sglang.launch_server \ --model-path /raid/fly/model/Qwen3-8B --port 30000 --tp-size 1 \ --enable-flexkv --flexkv-config-file /raid/fly/sglang-connector-dir/flexkv_min.yaml \ --mem-fraction-static 0.45 /tmp/sglang.log 21 # ... wait until ready ... docker exec flexkv-sglang python3 /raid/fly/sglang-connector-dir/sglang/python/sglang/srt/mem_cache/storage/flexkv/verify_outputs.py --phase test预期最后一行输出Total mismatches: 0。脚本内部每个 prompt 跑两次R1 冷启动 / R2 在flush_cache之后并要求 R1 与 R2 的output_ids都逐字节等于基线verify_outputs.py。R2 阶段还会打印命中率cached_tokens / prompt_tokens用于确认宿主层命中确实发生。脚本内置了三个 prompt 覆盖SHORT12 token、MEDIUM24 token与 LONG横跨多个 KV 页的长文本。如需验证 layerwise 路径用FLEXKV_ENABLE_LAYERWISE_TRANSFER1重复 Phase-2 启动即可。故障排查文档与源码共同确认的典型问题与对策fatal: not a git repository ... third_party/xxHash—— FlexKV 的 build.sh 需要真实 git checkout 才能初始化子模块。若通过 rsync 同步 FlexKV 且没有.git/需补齐rsync -az /path/to/FlexKV/.git/ remote:dir/FlexKV/.git/然后git config --global --add safe.directory *。fatal: detected dubious ownership—— 同上执行git config --global --add safe.directory *。xxhash.h: No such file or directory—— 子模块未初始化cd FlexKV git submodule update --init third_party/xxHash。dist/lease_meta_mempool.h: No such file or directory—— rsync 时排除了csrc/dist/。注意FlexKV/csrc/dist/是源码而非构建产物请去掉--excludedist重新同步。No module named Cython—— 安装依赖pip install cython ninja pybind11。sglang-kernel is installed with version 0.4.2.post2, which is less than the minimum required version 0.4.3—— 二选一带SGLANG_SKIP_SGL_KERNEL_VERSION_CHECK1运行或pip install -U sglang-kernel刷新。后者下载约 600 MB慢速网络下耗时较长。cudaHostRegister failed with error code 100cudaErrorNoDevice—— FlexKV 传输子进程无法在指定设备上初始化 CUDA通常由上一个残留会话导致重启容器即可。[FlexKV] Waiting for FlexKV ready循环超过 60 s——KVManager子进程启动时崩溃检查/tmp/sglang.log中的实际堆栈多为 CUDA 初始化或 torch 多进程问题。Layerwise 模式服务器卡在Eventfd connected attempts...——LayerwiseTransferWorker尚未启动。Eventfd server created之后它可能需要 20~30 秒若长时间无进展检查 FlexKV 侧以[LayerwiseWorker]开头的日志行。状态与已知限制当前验证状态MP同步路径——已在 Qwen3-8BH20-3e上端到端验证短 / 中 / 长 prompt 输出均与无 FlexKV 基线逐字节一致观测到 D2H 存储约 30–46 GB/sH2D 加载约 37 GB/s。IPlayerwise路径——已携带flexkv_comm.py中的修复端到端验证每层约 7–12 GB/s单次调用载荷更小。PP / CP / DP / 多节点——代码路径由FlexKVComm驱动沿用自生产验证过的BaseKVConnector集成未在单卡冒烟测试中覆盖上线前需要多节点验证。已知限制混合模型不支持Mamba / SWA / DSV4 indexer 辅助池等混合模型无法通过本连接器接入——当前只挂接了主 KV 池。HiCache 的多池batch_*_v2接口理论上可以映射过来但需要先为FlexKVConnector补齐PoolTransfer与PoolHitPolicy管道。写回确认是请求级的每个cache_finished_req对应一次dec_lock_ref而不是像 HiCache 的 write-through ack 队列那样按页确认。--radix-cache-backendflexkv与--enable-flexkv目前完全等价两者同时设置时尚未发出弃用警告。基准测试暖缓存命中收益仓库 README 记录的基准设置如下Qwen3-8B 单卡 H20服务器参数--attention-backend triton --mem-fraction-static 0.32 --max-running-requests 32 --chunked-prefill-size 16384 --context-length 32000负载为从 SWE-bench_Lite_oracle 采样的 120 条 prompt输入长度 ≤ 28k tokenp50 7088最大 27961pass 1 填充宿主缓存pass 2 为实测轮qps2.0、concurrency24、max_new_tokens32、temperature0。暖缓存轮结果ConfigTTFT avg / p50 / p90 / p99E2E p50ThroughputOutput tok/sH2D / D2Hbaseline6.86 / 8.04 / 9.88 / 10.89 s8.15 s1.86 req/s37.7—--enable-hierarchical-cache0.04 / 0.04 / 0.06 / 0.06 s0.23 s2.02 req/s40.8—--enable-flexkv0.05 / 0.05 / 0.07 / 0.08 s0.24 s2.02 req/s40.886 / 155服务端侧SGLang 日志中的ReqTimeStats76 个非 EOS 立即返回的暖缓存请求中hicache与flexkv均有 76 个达到cached_input_len input_len100% 前缀恢复baseline 停留在约 59 token仅系统 prompt 头部。flexkv下 86 条H2D transfer日志行证实 CPU 层加载真实发生。输出正确性方面对 32 条 prompt、temperature0做逐字节 diffbaseline冷轮 暖轮32 / 32无缓存时完全确定hicache暖轮 vs baseline 暖轮——29 / 32 一致3 条分歧flexkv暖轮 vs baseline 暖轮——29 / 32 一致3 条分歧与hicache基本是同一批。temperature0下约 10% 的分歧是众所周知的 KV 缓存复用伪影浮点非结合性导致原位 prefill与加载预计算 KV两条路径结果略有差异。它同样影响主线--enable-hierarchical-cache并非 FlexKV 特有。模块文件清单FlexKV 集成模块位于 python/sglang/srt/mem_cache/storage/flexkv/flexkv_radix_cache.py ——FlexKVRadixCache(RadixCache)覆盖match_prefix、init_load_back、cache_finished_req、evict、check_hicache_events、resetflexkv_connector.py ——FlexKVConnector持有KVManager、KVTPClient与跨 rank 同步上下文公共方法包括lookup_kv、retrieve_kv、start_load_kv_layerwise、store_kv、check_completed_stores、prefetch_async等flexkv_comm.py ——FlexKVComm基于 torch.distributed 的 PP × CP × TP 三轴同步与 layerwise UDS 握手使用的 eventfd /SCM_RIGHTS封装FlexKVLayerLoadingEvent在此承载 layerwise 正确性修复reset 时排空残留 eventfd 信号、用select.select在 NONBLOCK fd 上保持阻塞语义init.py —— 通过sglang.srt.mem_cache.registry注册flexkv工厂example_config_mp.yaml —— SSD / 远端 / 分布式旋钮的完整示例配置verify_outputs.py —— 端到端正确性验证脚本。接入点的注册表实现在 mem_cache/registry.pyCLI 参数定义在 arg_groups/fields/memory.py供希望扩展自定义 RadixCache 后端的开发者参考。【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考