[Feature][KVCache] Implement Cache Manager V1 with multi-GPU support and MTP KV Cache

[kevincheng2]

Motivation

实现全新的 Cache Manager V1 三级缓存管理架构（fastdeploy/cache_manager/v1/），支持 KV Cache 在 GPU 显存、CPU 内存、持久化存储之间的异步换入换出，提升 KV Cache 命中率和整体吞吐。

同时修复了多卡场景下 CuPy stream/Event 设备绑定错误，以及多模态 hash 边界判断 Bug。

Modifications

新增核心模块（fastdeploy/cache_manager/v1/）

模块	说明
base.py	KVCacheBase 抽象基类，统一初始化 model_config、cache_config、quant_config、parallel_config，消除子类重复代码
block_pool.py	BlockPool，管理 Device/Host block 的分配与释放，支持 LRU 驱逐
cache_controller.py	CacheController，三级缓存 block 状态机（DEVICE / HOST / SWAP_TO_HOST / SWAP_TO_DEVICE / LOADING_FROM_STORAGE / DELETING），协调 swap/backup/storage 操作
cache_manager.py	CacheManager，对外统一接口，封装 prefix cache 匹配、block 分配/释放、swap 调度
cache_utils.py	get_block_hash_extra_keys：计算包含多模态 token 的 block hash extra keys；LayerDoneCounter：基于 CUDA Event 追踪逐层传输完成状态，支持 Compute-Transfer Overlap
metadata.py	完整元数据定义：BlockNode、MatchResult、CacheSwapMetadata、PDTransferMetadata、StorageMetadata、TransferResult；注释全部翻译为英文
radix_tree.py	RadixTree，基于 Radix Tree 的 prefix cache 索引，支持 write_through_selective 备份策略（按 hit_count 阈值触发 host 备份）
transfer_manager.py	CacheTransferManager，管理 Host↔Device 异步 swap，基于独立 CuPy stream 实现 Compute-Transfer Overlap

CUDA 算子优化（custom_ops/gpu_ops/）

• swap_cache_optimized.cu：提供三种 swap 算子：swap_cache_per_layer（单层同步）、swap_cache_per_layer_async（单层异步，无 cudaStreamSynchronize）、swap_cache_all_layers（多层 swap）；连续 block 使用 cudaMemcpyAsync 快速路径，非连续 block 使用 warp-level PTX non-temporal 访存；删除 swap_cache_all_layers_batch（batch 上传算子，由 cupy device context 替代）
• swap_cache_batch.cu：删除 cudaSetDevice 调用，由上层 cupy context 统一保证设备正确性

MTP KV Cache 支持

支持 cache_manager_v1 下的 MTP（Multi-Token Prediction）KV Cache 初始化，以及多模态 token 的 block hash 计算。

Bug 修复

多 GPU 设备绑定修复（transfer_manager.py）

多卡场景下，CuPy stream 和 Event 创建未指定目标 GPU，导致流绑定到错误设备，swap 操作失败。修复方式：在所有 CuPy stream/Event 的创建与使用处包装 with cp.cuda.Device(device_id): context，覆盖 __init__、_swap_all_layers_async、_swap_per_layer_async、record_input_stream_event 等方法。

多模态 hash 边界修复（cache_utils.py）

get_block_hash_extra_keys 中使用严格小于 < 判断多模态 item 是否在 block 开始位置之前，导致恰好结束于 block 起始位置的 item 被错误包含。修复为 <=。

测试覆盖

新增/扩展单元测试：

• tests/cache_manager/v1/test_cache_utils.py：get_block_hash_extra_keys 全场景测试（边界、多模态重叠、跨 block 等 20+ 用例）
• tests/cache_manager/v1/test_cache_controller.py：CacheController block 状态机测试
• tests/cache_manager/v1/test_cache_manager.py：CacheManager 分配/释放/前缀匹配全链路测试
• tests/cache_manager/v1/test_radix_tree.py：RadixTree 备份候选、LRU 驱逐测试
• tests/cache_manager/v1/test_transfer_manager.py：TransferManager 多 GPU 场景测试
• tests/engine/test_request.py：Request cache 字段（block_hasher、prompt_hashes、cache_swap_metadata）测试

Usage or Command

Cache Manager V1 通过 FDConfig.cache_config 控制，相关配置参数：

参数	类型	默认值	说明
cache_config.total_block_num	int	-	GPU device block 总数
cache_config.num_cpu_blocks	int	0	CPU host block 总数；0 表示禁用 host cache
cache_config.block_size	int	64	每个 block 的 token 数
cache_config.enable_prefix_caching	bool	False	是否启用 prefix cache（RadixTree 索引）
cache_config.enable_host_cache	bool	False	是否启用 Host 二级缓存（CPU 内存换出）
cache_config.write_through_policy	str	"write_through_all"	Host 备份策略：write_through_all 全部备份；write_through_selective 按阈值备份
cache_config.backup_hit_threshold	int	2	write_through_selective 模式触发备份的最小命中次数
cache_config.enable_storage_cache	bool	False	是否启用 Storage 三级缓存（持久化存储）
cache_config.enable_compute_transfer_overlap	bool	False	是否启用 Compute-Transfer Overlap（逐层传输）

启动服务示例（开启 host cache 及 prefix caching）：

# 编译算子（如修改了 .cu 文件）
bash build.sh 1 python false [90] 1

# 启动推理服务，开启 host cache
python -m fastdeploy.entrypoints.openai.api_server \
    --model /path/to/model \
    --enable-prefix-caching \
    --num-cpu-blocks 2048 \
    --tensor-parallel-size 4

运行单元测试：

source .venv/py310/bin/activate
cd baidu/FastDeploy
python -m pytest tests/cache_manager/v1/ -vv -s

Checklist

• Add at least a tag in the PR title.
• Format your code, run pre-commit before commit.
• Add unit tests. Please write the reason in this PR if no unit tests.
• Provide accuracy results.
• If the current PR is submitting to the release branch, make sure the PR has been submitted to the develop branch, then cherry-pick it to the release branch with the [Cherry-Pick] PR tag.

[kevincheng2]

Closing: PR should target upstream PaddlePaddle/FastDeploy, not this fork.