# Tutti 接入 vLLM 设计文档 > 架构（D-005）：**外部 TuttiConnectorV1，零 vLLM 侵入**。 > 决策：`ai-orch/decisions/`（D-001 红线、D-002 存储契约、D-005 架构）。 > 操作手册：`tutti-vllm-manual.md`。编排：`ai-orch/` + `rounds/`。 --- ## 1. tutti 旧版（legacy）接入 vLLM 复盘（既有资产） ### 1.1 总体架构：三层解耦 | 层 | 位置 | 职责 | |---|---|---| | vLLM fork（薄改） | `third_pkgs/tutti-legacy/vllm-fork` | KVConnector 挂点补丁约 8 文件 | | Python adapter（厚） | `third_pkgs/tutti-legacy/engine/pkg/integration/vllm-connector/vllm_v1_adapter.py`（约 1300 行） | 全部 vLLM 侧调度：请求追踪、前缀命中、slot 映射、逐层 IO 编排 | | C++/CUDA 引擎 | `legacy-tutti/csrc/tutti 前身` | NVMe 队列、GPU P2P DMA、GPU-direct IO kernel | 核心：**调度逻辑不改 vLLM，全部实现在 KVConnectorBase_V1 回调里**。 ### 1.2 vLLM fork 侧修改清单（历史参考，新版全部原生具备） 1. `legacy-tutti_connector.py`：64KB 对齐（`_align_num_blocks_for_legacy-tutti`）、 `prefer_cross_layer_blocks`、`requires_piecewise_for_cudagraph`。 2. `factory.py` 注册；`kv_transfer_utils.py` 的 `maybe_transfer_kv_layer` 装饰器；跨层 KV buffer（`allocate_uniform_kv_caches`）。 3. 启动：`kv_transfer_config={"kv_connector": "LegacyTuttiConnector", "kv_role": "kv_both"}`，block_size=128=chunk_size，环境变量配置。 ### 1.3 存储文件组织 - 一个 KV chunk（chunk_size token × 全部 layer × K+V）= 一个 GPUFile； 每 GPUFile 最多 4 盘各建一个物理文件条带化，per 盘大小对齐 64KB。 - 文件描述符 GPUFileDesc{file_id, 单层 block_size, tensor_shape[3], CompactNVMeMapping(17B)}，GPU-resident。 ### 1.4 索引设计 - 逻辑索引（CPU/Python）：token chunk 哈希 → CacheEngineKey → GPUFileId 分配 + LRU evictor； - 跨进程查询：scheduler 经 ZMQ/Redis lookup server 查 worker 的索引 （`get_num_new_matched_tokens` 用）； - 物理索引（GPU/C++）：CompactNVMeMapping 内联，kernel 直接算盘上 offset，不回 CPU。 ### 1.5 读写接口与调度时机 **Scheduler 进程（每调度步）**： ``` get_num_new_matched_tokens() # lookup 查外部命中 → LoadSpec update_state_after_alloc() # 分配 block 后 can_load=True build_connector_meta() # ReqMeta{token_ids, slot_mapping, block_ids, save/load_spec} # slot_mapping = block_id*block_size + offset ``` `ReqMeta.from_request_tracker()` 负责 chunk 边界对齐 （discard_partial_chunks）、skip_leading_tokens 去重、slot_mapping 展开。 **Worker 进程（每次 forward）**： ``` start_load_kv() # prepare_for_load/save + 预取第 0 层 + IO 预算 每层 attention 前: wait_for_layer_load(layer) # retrieve_layer(L+1) 逐层预取 每层 attention 后: save_kv_layer(layer) # store_layer(L) 逐层落盘 forward 出口: wait_for_save() # no-op（stream 异步） ``` - overlap：StreamController（green context SM 分区）切 IO stream （load 16 SM / save 8 SM），与计算 stream 并行；逐层 prefetch 重叠 第 N+1 层读取与第 N 层计算。 - IO 任务：`IOSpec{gpu_file, block_id, layer}` 逐层递增；请求释放时 withdraw_tasks 回收。 ### 1.6 Debug 与 nsys 标记 - Python NVTX：`_tutti_legacy_nvtx_annotate` 装饰器（domain="legacy-tutti"， 函数名 hash 分色）铺满 adapter/engine；区间 `nvtx.start_range`。 - C++ 侧无 NVTX（靠 kernel 名区分）；独立 logger + observability 统计。 --- ## 2. Tutti 与 tutti 的接入面对应关系 | 概念 | tutti 前身 | Tutti | |---|---|---| | 引擎入口 | legacy-tutti_engine（get/put chunk） | `StorageRuntime`（open/register_memory/submit/wait） | | GPU 显存注册 | register_kv_caches → DMA 注册 | `register_memory(MemoryView{DEVICE})` | | 一次性下发 | 多次 per-layer engine 调用 | **`submit(IoRequest[], DEVICE_EXECUTION, stream)` 一次调用 = 一次 fused kernel launch** | | 文件/条带 | GPUFile + 4 盘自动条带 | URI：`file://`（FIEMAP 一次）、`striped://`（N 盘融合 kernel） | | partial commit | 无显式契约 | `IoSubmitOutcome.initial_states` 逐项；**被拒项必须窗口化重提交** | | 环境依赖 | 内核模块随引擎 | 内核模块 → tutti_daemon → mount 三步；daemon 仅资源 broker | 关键 gap：tutti 无 Python 绑定 → T-101 补（唯一新 C++ 面）。 --- ## 3. 新版 vLLM 现状（接入可行性依据） 1. `maybe_transfer_kv_layer` 原生存在（`kv_transfer_utils.py:15-61`）， 已挂 unified attention——逐层 hook 零改动可用。 2. 跨层 KV buffer 机制原生存在（`allocate_uniform_kv_caches` 等）。 3. **外部包零侵入注册**：`kv_connector_module_path` 直接 import 外部 connector 类（`factory.py:105-114`，LMCache 同款）——本方案核心依据。 4. 官方参考实现齐全（LMCache/Nixl/OffloadingConnector 等）。 5. HMA：connector 不支持时需 `--disable-hybrid-kv-cache-manager`。 6. 无 legacy-tutti/legacy-tutti/tutti 残留，代码干净。 --- ## 4. TuttiConnectorV1 设计（当前权威） ### 4.1 组件与仓库位置（全在 tutti 仓库） ``` integration/vllm-connector/bindings/python/ # tutti_runtime 包：pybind 封装 # make_{stub,local_nvme,striped_nvme}_runtime # open_batch / register_memory / submit / wait integration/vllm-connector/engine/ core.py # TuttiEngine 唯一引擎（计划态 + 逐层执行态 + 环形窗口） chunk_index.py # chunk hash → 文件路径 key + LRU + pin（纯 stdlib） backend.py # StorageBackend SPI（chunk_paths/bind_staging/段搬运） memory_backend.py # MemoryBackend（无盘可测） integration/vllm-connector/tests/ # 按测试需求分类（唯一测试落点，见 tests/README.md）： # contract(读写接口契约) / unit(纯逻辑) / adapter / # kernels / bindings / perf / scale / overlap integration/vllm-connector/adapter/ vllm_adapter.py # TuttiConnectorV1(KVConnectorBase_V1) 双角色壳 # + scheduler 侧：RequestTracker/ReqMeta/slot_mapping # （平移 legacy tutti）+ engine 计划态进程内前缀命中 worker.py # register_kv_caches → engine.bind；逐层 load/store 编排 nvtx_utils.py integration/vllm-connector/kernels/ # tutti_kv_kernels：gather/scatter（LMCache 平移，T-117） # LocalStoreBackend（T-115）：engine/local_store_backend.py ``` ### 4.2 配置 ```python kv_transfer_config = { "kv_connector": "TuttiConnectorV1", "kv_connector_module_path": "adapter.connector", "kv_role": "kv_both", "extra_config": {"capacity_bytes": ..., # 必需；硬件无关 "blocks_per_chunk": 0}} # 0=自动（segment≥256KiB 对齐） ``` ### 4.3 存储布局与对齐契约（D-002 摘要，以 ARCHITECTURE.md §0a 为准） - chunk 身份 = 文件路径 key（opaque，backend 自产自解释）；文件 布局 = packed（层段 offset = layer_idx × segment_bytes）。 - 池化/聚合/fd 收敛/建池校验：LocalStoreBackend 私有自决，不进接口 （若做预分配：零实写，禁 fallocate——FIEMAP fail-closed）。 - 注册：staging 环形窗口是唯一注册对象（基址 64KiB 对齐， io_granularity=segment_bytes 预建描述符）；IO 的 memory_offset/length/target_offset 4KiB 对齐；单请求 ≤ caps().max_single_io_bytes（默认 32MiB）。 - submit 前 `io_stream.wait_stream(gather stream)`；被拒请求 内部窗口重发，对上层恒 True；每层 CUDA event。 ### 4.3a staging gather/scatter 内核（D-006：复用 LMCache 资产） legacy 引擎即 LMCache fork 改名版，其 staging kernel 被砍只剩 DMA； 当前设计恰好接回这条路径，内核资产现成： | LMCache 资产 | 位置 | 复用方式 | |---|---|---| | `single_layer_kv_transfer` | `csrc/cuda/mem_kernels.cu:1012`（模板特化 :1131） | **T-117 已平移**：单层 packed ↔ paged（slot_mapping），16 种 EngineKVFormat 全覆盖 | | `multi_layer_kv_transfer` | 同文件 :904（+`_fused_ptr` :869） | 跨层 `[2,L,T,H]` ↔ 每层独立 paged tensor（`key_value_ptrs[L]`——正是 vllm register_kv_caches 形态） | | `load_and_reshape_flash`/`reshape_and_cache_back_flash` | :1160/:1209 | "load and reshape" 本体，语义参照 | | `EngineKVFormat` + `FormatFacts` | `csrc/engine_kv_format.h:36-292` | paged 布局描述（16 种，编译期谓词） | | `normalize_kv_and_discover_format` | `lmcache/v1/gpu_connector/utils.py:186` | register_kv_caches 时运行时布局探测 | | `TensorMemoryObj` 池管理 | `lmcache/v1/memory_management.py:635+` | 槽管理参照（ref_count/pin/unpin） | 平移方式：拷 `mem_kernels.cu` 相关部分 + `engine_kv_format.h` 至 `kernels/`（独立包 tutti_kv_kernels）自建最小 torch extension—— 不依赖 lmcache pip 包（Apache-2.0，保留版权头）。 staging 槽布局与 LMCache `KV_2LTD`（[2,L,T,H]）同构，kernel 参数化 适配。engine 的 gather_fn/scatter_fn 钩子即注入点（T-117 已交付 single_layer 平移内核，集成接线在后续卡完成）。 ### 4.4 调用时序 **Scheduler**： ``` get_num_new_matched_tokens → engine.lookup_prefix（进程内，无 RPC） update_state_after_alloc → RequestTracker 记录 + can_load build_connector_meta → ReqMeta（slot_mapping 手算，平移 legacy tutti） + engine.plan_load/plan_store（chunk_id 路径 opaque 透传） ``` **Worker**： ``` register_kv_caches # engine.bind（staging 是唯一注册对象，注册在 backend 内部） start_load_kv # engine.load_layer(plan, 0) wait_for_layer_load(L) # 等 L 层句柄；engine.load_layer(plan, L+1)；末层 complete_load save_kv_layer(L) # engine.store_layer(plan, L)（与计算并行） wait_for_save # no-op get_finished # complete_store/complete_load 收割 ``` **Overlap 语义**（与 legacy-tutti 对齐）：load 层间预取 + save 逐层落盘， IO stream 与计算 stream 并行——这是选择外部 connector 路线的核心收益。 ### 4.5 与官方 Offloading 体系的关系 刻意不依赖 vllm 的 OffloadingSpec/Manager/Worker 抽象：完整实现 KVConnectorBase_V1 回调，索引/驱逐自管（engine/chunk_index.py）。理由： 逐层 hook 粒度 + 不受 experimental API 演进影响（D-005 第 2 条）。 --- ## 5. 架构契合度分析（tutti 现状 vs vLLM 需求） ### 5.1 模型多样性：MoE / Mamba / 混合架构 — 满足 - tutti 是 opaque-byte 引擎（无 reshape/paged 逻辑，IO kernel 只做 PRP+doorbell），结构知识全在 vLLM 侧。 - MoE 不改变 KV 形状；Mamba/GDN state 由 connector 的 kv_caches dict 收集（按 layer 独立 tensor 注册即可，`MambaSpec` 页同样走 4KiB 对齐约束，非 4KiB 倍数由 vllm 的 page_size_padded 处理或跳过）。 - 唯一约束：各 group page_size_bytes(padded) % 4096 == 0。 ### 5.2 GPU-NVMe 拓扑与带宽 实测拓扑：2 NUMA × 4 PCIe switch，每 switch 1 GPU(x16)+1 NVMe(x4)。 即每 GPU 直连 1 盘（distance 0），NUMA 内其余 3 盘 distance 1， 跨 NUMA distance 2。 - **推荐**：每 NUMA 4 盘组 striped 池，同 NUMA 4 GPU 各起独立 TuttiRuntime open 同一批池文件——全部 IO NUMA 内闭合，零跨 NUMA P2P。chunk 路径空间按 rank 分区（无锁），或共享 canonical 去重（二期）。 - 带宽模型（分级）：单盘直连 ~7GB/s；单 GPU NUMA 4 盘突发 ~28GB/s； 全机 8 盘聚合峰值 50+GB/s（保守一半 20+GB/s）；稳态 8 GPU 均分 ~7GB/s/GPU （GPU x16 上行 ~32GB/s 封顶）；瓶颈在盘数（8×Gen4x4 ≈ 56-60GB/s）。 - NUMA0 四盘尚未 daemon bring-up（用前补三步）；跨 GPU 不互访 KV （TP 分片语义 + tutti stream 归属校验），共享池无正确性风险。 ### 5.3 条带化与持久化 - `striped://` 文件级静态条带（unit + rot），物理盘映射 `((offset/unit)+rot) % N` 隐式完成，vLLM 侧只见 opaque chunk 路径。 - 数据持久（文件应用层创建，重启可读）；**索引不持久**（R1 接受 重启冷缓存；V2 加 sidecar 索引 dump/load）。 ### 5.4 内存注册：staging 是唯一注册对象 - 契约（实证）：注册基址 64KiB 硬性（`local_nvme_data_path.cpp:985`）； IO memory_offset/length 4KiB（`submit_one.cuh:38-43`）。 - 落地：staging 环形窗口一次注册（`io_granularity=segment_bytes` 预建描述符，全部 IO 走 pre-built 路径）；vllm paged 池**不注册**—— 数据进出只经 gather/scatter kernel（HBM 域 μs 级），IO 的 GPU 端 恒为 staging 内偏移。小 block（16/32）下的粒度碎片、对齐非法、 预建描述符失效问题由此全部消解（详见 ARCHITECTURE.md §2b）。 ### 5.5 容量与 fd 收敛（LocalStoreBackend 私有自决） - 一 chunk 一文件在真实容量下是十万级 fd——fd 收敛（聚合大文件） 是真实需求，但属 backend 内部实现自决（ARCHITECTURE.md §0a）： 不进接口、不进路径语义、不进 engine/adapter。 - 硬约束（若做预分配）：禁 fallocate（FIEMAP fail-closed 拒 UNWRITTEN，须实写零）；单文件物理 extent ≤ 124 （kMaxTotalExtents），实写大文件通常几个~几十个，可控。 ### 5.6 md/dm RAID0 直通（未立项，结论存档） md-raid0 上 FIEMAP 只给 md 逻辑偏移（ext4 的 m_pblk 是所在块设备 块号；raid0 的 bio remap 在 ext4 之下的块层，OpenCloudOS 5.4.241 raid0.c `map_sector` 证实）。可行路径 = snvme 块设备（保留 gendisk） 组 md0 + tutti 新增 md_raid0 resolver 复刻映射（同构盘退化为线性 公式，参数从 /sys 运行时读）。**收益**：单一 ext4 大文件随便放 + 模型权重挂载零修改聚合加载；**代价**：一个新 resolver + 部署纪律。 D-001 红线：本轮不做，如立项另出决策。 --- ## 6. 调用路径图（外部 connector 版） ``` ┌────────────────────────── Scheduler 进程 ──────────────────────────┐ │ vllm/v1/core/sched/scheduler.py（官方） │ │ get_num_new_matched_tokens / update_state_after_alloc / │ │ build_connector_meta │ │ │ 官方 KVConnectorBase_V1 扩展点 │ │ v │ │ ★ adapter.connector.TuttiConnectorV1(SCHEDULER) │ │ → vllm_adapter.py（scheduler 侧） │ │ engine 计划态：lookup_prefix / plan_load / plan_store │ │ （进程内，无 RPC；chunk_id 路径 opaque 透传） │ │ ReqMeta{token_ids, slot_mapping, block_ids, load/save_spec} │ └──────────────────┬──────────────────────────────────────────────────┘ │ KVConnectorMetadata（官方 IPC） ┌──────────────────v─────────── Worker 进程（每 GPU）─────────────────┐ │ vllm gpu_model_runner（官方）+ maybe_transfer_kv_layer 装饰器 │ │ forward 前 start_load_kv；每层前 wait_for_layer_load； │ │ 每层后 save_kv_layer；出口 wait_for_save │ │ │ │ │ v │ │ ★ adapter.connector.TuttiConnectorV1(WORKER) │ │ → worker.py WorkerImpl（纯编排翻译 + 在途上限背压） │ │ → TuttiEngine 执行态：环形窗口 staging + gather/scatter │ │ （_kernels，LMCache 平移） │ │ → StorageBackend（LocalStoreBackend：路径自产自解释、 │ │ 固定粒度 submit、partial-commit 重发；池化/fd 收敛私有） │ │ │ pybind │ │ v │ │ ★ tutti_runtime._core → tutti/presets make_*_runtime（只读链接） │ │ StorageRuntime.submit(reqs, DEVICE_EXECUTION, io_stream) │ │ → 按 DataPath 分组 → 1×H2D 描述符 → 1 次 fused kernel launch │ │ IO kernel @ io_stream ∥ 计算 stream ← overlap │ └──────────────────┬──────────────────────────────────────────────────┘ │ PCIe P2P GPU-direct DMA（不经 host） v NUMA 内 4 盘 striped 池（文件布局=packed；聚合/fd 收敛 backend 自决） ``` ★ = 新增代码（全在 tutti 仓库）；vllm fork 零改动。 --- ## 7. 环境与操作 见 `tutti-vllm-manual.md`（tutti-env 完全隔离环境 / env-tutti.sh / snvme bring-up 三步 / 冒烟与 bench 流程 / FAQ）。