# Bucket-Aware Routing Design ## 背景 当前 simulator 只有一个全局 `Cluster`： - trace replay 的所有请求共享一组 `instances` - router 直接在全局 instance 池里选目标实例 - `meta_store`、L0/L1 cache 可见性、remote RDMA 也都是全局共享 这和目标架构不一致。目标架构要求： - service 内存在多个显式定义的 input-length buckets - 每个 bucket 有独立的 instance 池，实例数由配置显式给出 - bucket 之间的 cache / meta-store / remote 可见性严格隔离 - router 不只是 bucket 内调度器，还要能以 global 视角感知 bucket 的存在 - 后续需要用 simulator 研究： - 是否应该区分 bucket - 严格按 input length 分发与非严格分发的差异 - bucket policy 与 bucket 内 instance policy 的耦合和收益 因此，这次重构不能把“先按 input length 选 bucket”硬编码到 service 层，而要把 bucket 选择纳入 global router 的决策面。 ## 目标 本次设计的目标是把 simulator 重构成“两级调度”架构： 1. global router 在所有 bucket 之间选择目标 bucket 2. local router 在选中的 bucket 内选择目标 instance 同时满足： - bucket 由配置文件显式定义 - 所有 bucket 共享同一套 local router 配置 - bucket 之间完全隔离，不共享 L0/L1/meta-store/remote 视图 - 保留足够的 metrics / routing log，支持后续研究 bucket policy 的效果 - 尽量复用现有 `src/router/*` 中的 instance 级路由实现，避免把所有 router 改写成跨 bucket 扁平打分器 非目标： - 第一阶段不支持 per-bucket 自定义 router 算法 - 第一阶段不支持跨 bucket cache 共享 - 第一阶段不自动推导 bucket 边界或 bucket 实例数 - 第一阶段不实现“全局扁平 instance 池”语义 ## 方案比较 ### 方案 A：service 层固定按 input length 选 bucket，router 只负责 bucket 内 instance 优点： - 对现有代码侵入最小 - local router 基本不用改 缺点： - 无法研究“router 不严格按照 input length 分发会怎样” - bucket policy 被固化，无法与 instance policy 解耦对比 - global 视角只能做观测，不能做真正决策 ### 方案 B：两级路由，global router 选 bucket，local router 选 bucket 内 instance 优点： - bucket policy 和 instance policy 清晰解耦 - 符合目标架构，也适合做对照实验 - 可以最大程度复用现有 router 实现作为 local router 缺点： - 需要新增 service 层摘要视图与 global router 接口 - driver / events / metrics 要显式携带 bucket 维度 ### 方案 C：全局扁平 router，对所有 instance 跨 bucket 一起打分 优点： - 表面上最自由 缺点： - bucket policy 与 instance policy 混在一起，实验解释性差 - 现有大多数 router 要重写 - 容易把“bucket 是独立实例池”的物理边界冲淡 推荐方案：方案 B。 原因：bucket 是 service-level 拓扑与隔离边界，instance selection 是 bucket 内局部调度问题。这两个层次应该分开建模，否则后续无法清晰回答“bucket 本身是否有价值”和“instance 级路由算法是否有效”。 ## 配置设计 `cluster` 从现在的单实例池配置扩展为显式 bucket 配置。 目标 YAML 形态： ```yaml cluster: meta_store: ttl_seconds: 1000.0 router: mode: cache_affinity precise_probe_latency_us: 10.0 precise_probe_topk: 4 load_alpha: 0.1 score_alpha: 1.0 score_beta: 0.1 prefix_k: 8 affinity_fan_out: 0 global_router: mode: strict_input_length length_penalty_weight: 1.0 load_weight: 1.0 cache_weight: 1.0 buckets: - name: short input_length_min: 0 input_length_max: 32768 num_instances: 3 - name: medium input_length_min: 32769 input_length_max: 81920 num_instances: 4 - name: long input_length_min: 81921 input_length_max: 131072 num_instances: 3 ``` 其中： - `cluster.router` 继续表示 bucket 内 local router 配置，全局统一 - 新增 `cluster.global_router`，表示 bucket 选择策略 - `cluster.buckets` 显式描述 service 拓扑 第一阶段建议继续兼容旧配置： - 若只提供 `cluster.num_instances`，则视为单 bucket 模式 - 若提供 `cluster.buckets`，则进入多 bucket 模式 - 两者同时出现时直接报错，避免歧义 配置校验约束： 1. `buckets` 非空 2. 每个 bucket `num_instances > 0` 3. `input_length_min <= input_length_max` 4. bucket 区间不重叠 5. bucket 排序后必须能唯一命中一个 bucket 6. 旧模式与新模式互斥 ## 运行时架构 运行时拆成三层： ### 1. BucketedService 新增一个 service 层对象，持有多个 bucket。每个 bucket 包含： - `bucket_id` - bucket 配置 - 独立的 `Cluster` `BucketedService` 职责： - 为请求构造所有 bucket 的摘要视图 - 调用 global router 选择 bucket - 将请求转发给选中的 bucket 内 `Cluster` - 提供全量 bucket / instance 遍历接口，供 driver 做采样与 tick 调度 ### 2. Cluster 现有 `Cluster` 语义收缩为“单个 bucket 内的 cluster”： - 只持有该 bucket 的 `instances` - 只持有该 bucket 的 `meta_store` - 只运行该 bucket 的 local router `Cluster::route_and_admit` 不再负责 bucket 选择，只负责： - 在 bucket 内调用 local router 选 instance - 执行该 bucket 内的 L0/L1/remote/miss 路径 - 返回 bucket 维度补充后的 admission stats ### 3. Router 分层 router 明确拆分为： - `GlobalRouter`：负责 bucket 选择 - `LocalRouter`：负责 bucket 内 instance 选择 现有 `src/router/*` 中的大部分算法迁移为 `LocalRouter` 实现。 ## Router 接口设计 ### GlobalRouter global router 只看 bucket 摘要，不直接操作实例数组。 建议接口： ```rust trait GlobalRouter { fn name(&self) -> &'static str; fn route_bucket( &mut self, req: &RequestRecord, buckets: &[BucketView], now: f64, ) -> GlobalRouteDecision; } ``` `BucketView` 是只读摘要，至少包含： - `bucket_id` - `name` - `input_length_min` - `input_length_max` - `num_instances` - `queue_len_sum` - `queue_len_max` - `kv_blocks_used_sum` - `kv_blocks_total_sum` - `active_requests` - `predicted_prefix` - 可选的 `estimated_drain_time` `predicted_prefix` 表示该 bucket 对当前请求的 bucket 级 prefix 命中预测，用于让 global router 感知 bucket 级 cache affinity。 ### LocalRouter local router 继续以 bucket 内 instance 池为输入。 建议接口保持和现有语义接近： ```rust trait LocalRouter { fn name(&self) -> &'static str; fn route_instance( &mut self, req: &RequestRecord, instances: &[Instance], meta: &MetaStore, now: f64, ) -> LocalRouteDecision; } ``` 现有 `RouteDecision` 需要拆成两层，最后再合并成对外统一的日志结构： - `GlobalRouteDecision` - `LocalRouteDecision` - `RouteDecision`：包含 `chosen_bucket + chosen_instance + 两层 candidates` ## Bucket 隔离语义 bucket 是显式物理隔离边界，不是逻辑标签。 必须满足： - 请求一旦进入 bucket，只能使用该 bucket 的实例池 - L0 / L1 只在 bucket 内可见 - `meta_store` 只描述该 bucket 内哪些实例持有块 - remote RDMA 只允许从同 bucket 其他实例拉取 - bucket 之间不共享 owner 信息 这保证了 simulator 中的 bucket 与实际服务拓扑有明确对应关系，避免 global router 虽然“知道 bucket”，但底层缓存模型仍然偷偷全局共享，从而污染实验结论。 ## 首批 Global Bucket Policies 第一阶段只实现两个 global bucket policy。 ### 1. strict_input_length 语义： - 只允许选择 `req.input_len` 所在区间的 bucket 用途： - 作为严格长度分桶的基线策略 - 对应最初目标架构图 ### 2. bucket_score 语义： - 对所有 bucket 计算分数并选择最优 bucket 第一阶段分数只使用少量强信号： - `length_penalty`：请求长度偏离 bucket 目标范围的惩罚 - `load`：bucket 总负载或最大负载 - `miss`：bucket 级预测 miss，来自当前请求在该 bucket 上的 `predicted_prefix` 目标形式： ```text score = a * length_penalty + b * load + c * miss ``` 设计意图： - 能研究“非严格按 input length 分发”的收益或损失 - 同时保留长度匹配偏好，避免第一阶段就退化为完全无约束调度 暂不实现： - 完全扁平的跨 bucket instance 全局打分 - per-bucket 特化 global scoring - 跨 bucket 回退式 cache 共享 ## 事件与 Driver 设计 当前 `Event::BatchTick { instance }` 假设 instance 是全局单层编号。多 bucket 后需要改成： ```rust Event::BatchTick { bucket: BucketId, instance: InstanceId } ``` driver 主循环改为： 1. `Arrival` 2. 读取请求 3. 调用 `BucketedService::route_and_admit` 4. 记录全局+局部路由决策 5. 为 `(bucket, instance)` 安排 `BatchTick` `Sample` 事件可以继续是全局事件，但采样时要遍历所有 buckets 的所有 instances。 `inflight` 结构保留按 `req_id` 索引，但 value 中新增： - `bucket` - `bucket_policy` - `length_bucket_match` - 可选的 `bucket_predicted_prefix` ## Metrics 与可观测性 这次重构的重点之一是让 bucket policy 可研究，因此 metrics 必须明确区分 bucket 选择和 instance 选择。 ### routing_log.jsonl 建议新增字段： - `global_mode` - `local_mode` - `chosen_bucket` - `chosen_instance` - `bucket_candidates` - `instance_candidates` - `global_reason` - `local_reason` 其中： - `bucket_candidates` 记录每个 bucket 的摘要与分数 - `instance_candidates` 记录选中 bucket 内的 instance 级候选信息 ### per_request.csv 建议新增字段： - `bucket` - `bucket_policy` - `length_bucket_match` - `bucket_predicted_prefix` `length_bucket_match` 用于直接衡量“最终 bucket 是否等于严格长度命中的 bucket”，是分析非严格分发影响的关键字段。 ### instances.csv 建议新增字段： - `bucket` ### summary.json 保留全局汇总不变，同时新增 bucket 维度 breakdown。可以采用： - 在 `summary.json` 内增加 `per_bucket` - 或新增独立 `bucket_summary.json` 第一阶段优先保证可读性与易分析，不需要过度抽象。 ## 错误处理 需要显式处理以下失败场景： - 请求命中 0 个 bucket - 请求命中多个 bucket - bucket 配置不合法 - 多 bucket 模式下事件找不到对应 `(bucket, instance)` - routing log / metrics 缺失 bucket 信息 其中配置相关错误应尽量在启动时失败，而不是等到 trace replay 中途才暴露。 ## 测试策略 测试分三层。 ### 1. 配置测试 - 旧配置 `num_instances` 模式仍能成功加载 - `buckets` 模式成功加载 - bucket 区间重叠时报错 - `num_instances` 与 `buckets` 同时配置时报错 - bucket 未覆盖请求长度时报错或在运行时明确失败 ### 2. Service / Driver 测试 - 短请求进入 short bucket - 长请求进入 long bucket - `bucket_score` 可以在长度不完全匹配时选择非默认 bucket - long bucket 请求看不到 short bucket 的 meta-store / remote owner - `(bucket, instance)` 维度的 `BatchTick` 能正确推进 ### 3. 集成 Smoke Test 构造 mixed trace，包含多个 input length 段与共享前缀模式，验证： - 严格 bucket policy 下，请求落入预期 bucket - `routing_log` 同时记录 bucket 候选和 instance 候选 - `per_request` / `instances` 带 bucket 字段 - `bucket_score` 与 `strict_input_length` 在 mixed trace 上产生可观测差异 ## 迁移策略 为了控制风险，这次重构按以下顺序推进： 1. 在配置层引入 bucket 结构与校验，但保留旧单 bucket 模式 2. 把现有 `Cluster` 收缩为单 bucket 语义 3. 新增 `BucketedService`，先接通 strict bucket policy 4. 抽出 `GlobalRouter` 接口，补上 `strict_input_length` 5. 把现有 instance 级 router 适配为 `LocalRouter` 6. 扩展 driver / events / metrics 到 `(bucket, instance)` 维度 7. 再实现 `bucket_score` 作为第一种非严格 bucket policy 这样可以先建立正确拓扑与日志，再逐步加入实验策略，避免一次性重写过多核心路径。 ## 预期结果 完成后，simulator 将具备以下能力： - 用显式 bucket 拓扑 replay 混合长度 trace - 研究严格长度分桶是否带来收益 - 研究 global router 在 bucket 维度做非严格调度会产生什么影响 - 在 bucket policy 与 local instance policy 两个层次分别做 ablation 这为后续研究“bucket 是否必要”“bucket 边界怎么设”“global router 应不应该偏离长度分发”提供了清晰、可观测、可复用的 simulator 基础。