| 文件 | 最后提交记录 | 最后更新时间 |
|---|---|---|
【bugfix】coordinator add weight config Co-authored-by: ganglv<lvgang1@huawei.com> # message auto-generated for no-merge-commit merge: !677 merge master_icbc_shanghai into master 【bugfix】coordinator add weight config Created-by: ganglv Commit-by: ganglv Merged-by: tobking Description: ## **1. 合入背景** > 请描述为什么要做这个PR内的改动。\ > 如涉及，请关联前序PR或同特性/需求下的其他PR。\ > 如果是修复之前PR引入的问题，请关联引入问题的PR。\ > 请通过#ISSUE ID关联issue。\ > 注意： Fixes #ISSUE ID会自动关闭issue，如问题部分解决请不要使用Fixes，可以用Fix part of #ISSUE ID替代. KV Cache 亲和调度此前用 Conductor 返回的 matched_tokens（按介质覆盖终点）直接参与打分，存在两点不足： 1. **npu/cpu/disk_blocks 语义不清**：重叠前缀下各介质块数可能重复计入，无法表达「互斥真实命中块数」。 2. **介质价值差异无法配置**：HBM/NPU、CPU、Disk 对 TTFT 的贡献不同，但调度侧无法按介质加权；权重属于调度策略，不宜放在 Conductor（事实层）。 本 PR 将职责拆清：Conductor 只上报互斥命中事实；Coordinator 按 w_npu/w_cpu/w_disk 做亲和加权，并顺带把亲和参数收敛到嵌套配置 scheduler_config.kv_affinity。 ## **2. 修改内容** > 请<ins>**描述修改内容的具体实现**</ins>，涉及哪些组件之间进行交互，可以用1、2、3、...进行罗列。 > 如果是需求或者重构类的PR，需要<ins>**补充详细设计文档**</ins>（说明上下游组件关系、时序图、类图、DFX能力等内容）。 1. **KV Conductor（事实层）** - 匹配阶段收集每 DP 的介质绝对终点（npu_end/cpu_end/disk_end）。 - build_response 按优先级 **NPU > CPU > Disk** 做互斥划分，写入 npu_blocks/cpu_blocks/disk_blocks。 - matched_tokens = (npu+cpu+disk) × block_size（未加权真实覆盖长度）；实例级 longest_matched 仍取各 DP max。 2. **Coordinator（策略层）** - 新增/使用 KvAffinityConfig，配置迁入 scheduler_config.kv_affinity： - 原有：mode / load_weight / overlap_credit / prefill_load_scale / load_gate_topn - 新增：w_npu / w_cpu / w_disk（默认 **1.0 / 1.0 / 0.0**） - 亲和打分： text affinity_matched = min(round((npu×w_npu + cpu×w_cpu + disk×w_disk)×block_size), isl) prefill_cost = max(0, isl − overlap_credit × affinity_matched) - 兼容旧 flat key（kv_affinity_mode 等）：自动迁入嵌套结构并告警；嵌套优先。 3. **配置透传** - scheduler_connection_manager / scheduler_client 将 kv_affinity 权重传入 KvCacheAffinityPolicy。 4. **文档与示例** - 更新亲和调度用户指南、配置参考、kv-conductor README/设计文档、config_sample.json 及 skill 文档。 ## **3. 资料变更** > 请确认<ins>**是否涉及资料变更**</ins>。\ > 如涉及，需要在PR中体现，并简要说明修改内容。\ > 如不涉及，需填写“不涉及”。 涉及。已更新： - docs/zh/user_guide/features/kvcache_affinity.md - docs/zh/user_guide/configuration/config_reference.md - docs/zh/user_guide/deployment/k8s/pd_aggregation_deployment.md - docs/zh/design/kv_conductor.md - motor/kv_conductor/README.md - examples/features/config_sample.json - .agent/skills/motor-dev/references/{kv-conductor,coordinator}.md ## **4. 接口变更** > 请确认<ins>**是否涉及跨代码仓或者客户面可见的接口变更**</ins>。\ > 如涉及，需详细说明接口以及对应的变更内容，同时需要在资料中体现。\ > 如不涉及，需填写“不涉及”。 涉及（客户面配置与 Conductor 响应语义）： | 位置 | 变更 | |------|------| | Coordinator 配置 | 亲和参数由 flat kv_affinity_* 改为嵌套 scheduler_config.kv_affinity；保留 legacy 迁移 | | kv_affinity.w_npu/w_cpu/w_disk | 新增；默认 1.0/1.0/0.0 | | Conductor *_blocks | 语义改为互斥真实命中块数（NPU>CPU>Disk） | | Conductor matched_tokens | 改为互斥块数之和 × block_size（不再在 Conductor 侧乘权重） | ## **5. 测试结果** > 需体现<ins>**测试场景，测试方法以及测试结果**</ins>。\ > 测试用例设计时需考虑硬件、部署方式、功能、性能、精度、显存等维度。  ## **6. CheckList** > PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x] [ ] 代码注释完备 [ ] 正确记录维测日志 [ ] 是否有UT用例 [ ] 若涉及多线程场景，考虑了并发场景，不存在死锁问题 See merge request: Ascend/MindIE-Motor!677 | 2 个月前 | |
【bugfix】coordinator add weight config Co-authored-by: ganglv<lvgang1@huawei.com> # message auto-generated for no-merge-commit merge: !677 merge master_icbc_shanghai into master 【bugfix】coordinator add weight config Created-by: ganglv Commit-by: ganglv Merged-by: tobking Description: ## **1. 合入背景** > 请描述为什么要做这个PR内的改动。\ > 如涉及，请关联前序PR或同特性/需求下的其他PR。\ > 如果是修复之前PR引入的问题，请关联引入问题的PR。\ > 请通过#ISSUE ID关联issue。\ > 注意： Fixes #ISSUE ID会自动关闭issue，如问题部分解决请不要使用Fixes，可以用Fix part of #ISSUE ID替代. KV Cache 亲和调度此前用 Conductor 返回的 matched_tokens（按介质覆盖终点）直接参与打分，存在两点不足： 1. **npu/cpu/disk_blocks 语义不清**：重叠前缀下各介质块数可能重复计入，无法表达「互斥真实命中块数」。 2. **介质价值差异无法配置**：HBM/NPU、CPU、Disk 对 TTFT 的贡献不同，但调度侧无法按介质加权；权重属于调度策略，不宜放在 Conductor（事实层）。 本 PR 将职责拆清：Conductor 只上报互斥命中事实；Coordinator 按 w_npu/w_cpu/w_disk 做亲和加权，并顺带把亲和参数收敛到嵌套配置 scheduler_config.kv_affinity。 ## **2. 修改内容** > 请<ins>**描述修改内容的具体实现**</ins>，涉及哪些组件之间进行交互，可以用1、2、3、...进行罗列。 > 如果是需求或者重构类的PR，需要<ins>**补充详细设计文档**</ins>（说明上下游组件关系、时序图、类图、DFX能力等内容）。 1. **KV Conductor（事实层）** - 匹配阶段收集每 DP 的介质绝对终点（npu_end/cpu_end/disk_end）。 - build_response 按优先级 **NPU > CPU > Disk** 做互斥划分，写入 npu_blocks/cpu_blocks/disk_blocks。 - matched_tokens = (npu+cpu+disk) × block_size（未加权真实覆盖长度）；实例级 longest_matched 仍取各 DP max。 2. **Coordinator（策略层）** - 新增/使用 KvAffinityConfig，配置迁入 scheduler_config.kv_affinity： - 原有：mode / load_weight / overlap_credit / prefill_load_scale / load_gate_topn - 新增：w_npu / w_cpu / w_disk（默认 **1.0 / 1.0 / 0.0**） - 亲和打分： text affinity_matched = min(round((npu×w_npu + cpu×w_cpu + disk×w_disk)×block_size), isl) prefill_cost = max(0, isl − overlap_credit × affinity_matched) - 兼容旧 flat key（kv_affinity_mode 等）：自动迁入嵌套结构并告警；嵌套优先。 3. **配置透传** - scheduler_connection_manager / scheduler_client 将 kv_affinity 权重传入 KvCacheAffinityPolicy。 4. **文档与示例** - 更新亲和调度用户指南、配置参考、kv-conductor README/设计文档、config_sample.json 及 skill 文档。 ## **3. 资料变更** > 请确认<ins>**是否涉及资料变更**</ins>。\ > 如涉及，需要在PR中体现，并简要说明修改内容。\ > 如不涉及，需填写“不涉及”。 涉及。已更新： - docs/zh/user_guide/features/kvcache_affinity.md - docs/zh/user_guide/configuration/config_reference.md - docs/zh/user_guide/deployment/k8s/pd_aggregation_deployment.md - docs/zh/design/kv_conductor.md - motor/kv_conductor/README.md - examples/features/config_sample.json - .agent/skills/motor-dev/references/{kv-conductor,coordinator}.md ## **4. 接口变更** > 请确认<ins>**是否涉及跨代码仓或者客户面可见的接口变更**</ins>。\ > 如涉及，需详细说明接口以及对应的变更内容，同时需要在资料中体现。\ > 如不涉及，需填写“不涉及”。 涉及（客户面配置与 Conductor 响应语义）： | 位置 | 变更 | |------|------| | Coordinator 配置 | 亲和参数由 flat kv_affinity_* 改为嵌套 scheduler_config.kv_affinity；保留 legacy 迁移 | | kv_affinity.w_npu/w_cpu/w_disk | 新增；默认 1.0/1.0/0.0 | | Conductor *_blocks | 语义改为互斥真实命中块数（NPU>CPU>Disk） | | Conductor matched_tokens | 改为互斥块数之和 × block_size（不再在 Conductor 侧乘权重） | ## **5. 测试结果** > 需体现<ins>**测试场景，测试方法以及测试结果**</ins>。\ > 测试用例设计时需考虑硬件、部署方式、功能、性能、精度、显存等维度。  ## **6. CheckList** > PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x] [ ] 代码注释完备 [ ] 正确记录维测日志 [ ] 是否有UT用例 [ ] 若涉及多线程场景，考虑了并发场景，不存在死锁问题 See merge request: Ascend/MindIE-Motor!677 | 2 个月前 | |
[bugfix]cpu/disk命中根据parent_hash + token_hash查找 Co-authored-by: ganglv<lvgang1@huawei.com> # message auto-generated for no-merge-commit merge: !601 merge conductor into master [bugfix]cpu/disk命中根据parent_hash + token_hash查找 Created-by: ganglv Commit-by: ganglv Merged-by: towncharlie Description: ## **1. 合入背景** > 请描述为什么要做这个PR内的改动。\ > 如涉及，请关联前序PR或同特性/需求下的其他PR。\ > 如果是修复之前PR引入的问题，请关联引入问题的PR。\ > 请通过#ISSUE ID关联issue。\ > 注意： Fixes #ISSUE ID会自动关闭issue，如问题部分解决请不要使用Fixes，可以用Fix part of #ISSUE ID替代. 完善 KV Conductor 多级缓存亲和性匹配，支持 HBM、CPU、Disk 间连续前缀查询，提升匹配准确性。 [#386](https://gitcode.com/Ascend/MindIE-Motor/issues/386) [#387](https://gitcode.com/Ascend/MindIE-Motor/issues/387) ## **2. 修改内容** > 请<ins>**描述修改内容的具体实现**</ins>，涉及哪些组件之间进行交互，可以用1、2、3、...进行罗列。 > 如果是需求或者重构类的PR，需要<ins>**补充详细设计文档**</ins>（说明上下游组件关系、时序图、类图、DFX能力等内容）。 - 重构多级缓存索引及跨介质断点续查逻辑。 - bugfix for dsv4 flash - 支持disk查询 - 按实例和 DP 聚合各介质命中块数，移除加权评分。 - 完善事件兼容、测试、设计文档及第三方许可证声明。 - 修复log monitor收集日志有重复的问题 - 修改rust precommit失败问题 & rust commit执行慢问题 ## **3. 资料变更** > 请确认<ins>**是否涉及资料变更**</ins>。\ > 如涉及，需要在PR中体现，并简要说明修改内容。\ > 如不涉及，需填写“不涉及”。 不涉及 ## **4. 接口变更** > 请确认<ins>**是否涉及跨代码仓或者客户面可见的接口变更**</ins>。\ > 如涉及，需详细说明接口以及对应的变更内容，同时需要在资料中体现。\ > 如不涉及，需填写“不涉及”。 - 配置项 xpu_endpoint 更名为 gpu_endpoint。 - 注册接口介质名称由 xpu 调整为 gpu，仍兼容旧名称。 - 查询结果由 XPU/CPU/DISK/total 加权分数调整为 gpu_blocks/cpu_blocks/disk_blocks/matched_tokens。 ## **5. 测试结果** > 需体现<ins>**测试场景，测试方法以及测试结果**</ins>。\ > 测试用例设计时需考虑硬件、部署方式、功能、性能、精度、显存等维度。 dsv4_flash  qwen  disk  rename to npu  ## **6. CheckList** > PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x] [ ] 代码注释完备 [ ] 正确记录维测日志 [ ] 是否有UT用例 [ ] 若涉及多线程场景，考虑了并发场景，不存在死锁问题 See merge request: Ascend/MindIE-Motor!601 | 2 个月前 | |
[bugfix]cpu/disk命中根据parent_hash + token_hash查找 Co-authored-by: ganglv<lvgang1@huawei.com> # message auto-generated for no-merge-commit merge: !601 merge conductor into master [bugfix]cpu/disk命中根据parent_hash + token_hash查找 Created-by: ganglv Commit-by: ganglv Merged-by: towncharlie Description: ## **1. 合入背景** > 请描述为什么要做这个PR内的改动。\ > 如涉及，请关联前序PR或同特性/需求下的其他PR。\ > 如果是修复之前PR引入的问题，请关联引入问题的PR。\ > 请通过#ISSUE ID关联issue。\ > 注意： Fixes #ISSUE ID会自动关闭issue，如问题部分解决请不要使用Fixes，可以用Fix part of #ISSUE ID替代. 完善 KV Conductor 多级缓存亲和性匹配，支持 HBM、CPU、Disk 间连续前缀查询，提升匹配准确性。 [#386](https://gitcode.com/Ascend/MindIE-Motor/issues/386) [#387](https://gitcode.com/Ascend/MindIE-Motor/issues/387) ## **2. 修改内容** > 请<ins>**描述修改内容的具体实现**</ins>，涉及哪些组件之间进行交互，可以用1、2、3、...进行罗列。 > 如果是需求或者重构类的PR，需要<ins>**补充详细设计文档**</ins>（说明上下游组件关系、时序图、类图、DFX能力等内容）。 - 重构多级缓存索引及跨介质断点续查逻辑。 - bugfix for dsv4 flash - 支持disk查询 - 按实例和 DP 聚合各介质命中块数，移除加权评分。 - 完善事件兼容、测试、设计文档及第三方许可证声明。 - 修复log monitor收集日志有重复的问题 - 修改rust precommit失败问题 & rust commit执行慢问题 ## **3. 资料变更** > 请确认<ins>**是否涉及资料变更**</ins>。\ > 如涉及，需要在PR中体现，并简要说明修改内容。\ > 如不涉及，需填写“不涉及”。 不涉及 ## **4. 接口变更** > 请确认<ins>**是否涉及跨代码仓或者客户面可见的接口变更**</ins>。\ > 如涉及，需详细说明接口以及对应的变更内容，同时需要在资料中体现。\ > 如不涉及，需填写“不涉及”。 - 配置项 xpu_endpoint 更名为 gpu_endpoint。 - 注册接口介质名称由 xpu 调整为 gpu，仍兼容旧名称。 - 查询结果由 XPU/CPU/DISK/total 加权分数调整为 gpu_blocks/cpu_blocks/disk_blocks/matched_tokens。 ## **5. 测试结果** > 需体现<ins>**测试场景，测试方法以及测试结果**</ins>。\ > 测试用例设计时需考虑硬件、部署方式、功能、性能、精度、显存等维度。 dsv4_flash  qwen  disk  rename to npu  ## **6. CheckList** > PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x] [ ] 代码注释完备 [ ] 正确记录维测日志 [ ] 是否有UT用例 [ ] 若涉及多线程场景，考虑了并发场景，不存在死锁问题 See merge request: Ascend/MindIE-Motor!601 | 2 个月前 | |
【bugfix】缓存数据增加TTL，避免内存泄漏 Co-authored-by: ganglv<lvgang1@huawei.com> # message auto-generated for no-merge-commit merge: !673 merge conductor_ttl into master 【bugfix】缓存数据增加TTL，避免内存泄漏 Created-by: ganglv Commit-by: ganglv Merged-by: tobking Description: ## **1. 合入背景** > 请描述为什么要做这个PR内的改动。\ > 如涉及，请关联前序PR或同特性/需求下的其他PR。\ > 如果是修复之前PR引入的问题，请关联引入问题的PR。\ > 请通过#ISSUE ID关联issue。\ > 注意： Fixes #ISSUE ID会自动关闭issue，如问题部分解决请不要使用Fixes，可以用Fix part of #ISSUE ID替代. [#402](https://gitcode.com/Ascend/MindIE-Motor/issues/402) KV Conductor 中部分异步匹配缓存依赖事件流量触发清理，HBM 空节点也曾在事件热路径按删除次数执行全树扫描。这可能导致： - 服务空闲后过期缓存无法及时回收； - 未确认的 offload 数据长期驻留； - HBM 删除事件周期性出现延迟尖峰； - 空 WorkerLookup 或 IndexerEntry 残留； - 注销时使用请求中的 model/tenant，可能无法回收实际注册的索引； - 存在部分无调用或重复存储的代码。 ## **2. 修改内容** > 请<ins>**描述修改内容的具体实现**</ins>，涉及哪些组件之间进行交互，可以用1、2、3、...进行罗列。 > 如果是需求或者重构类的PR，需要<ins>**补充详细设计文档**</ins>（说明上下游组件关系、时序图、类图、DFX能力等内容）。 #### 1. 增加统一后台 Maintenance 服务启动时创建周期性 Tokio maintenance 任务，默认每 30 秒执行： - 清理过期的 pending_pool； - 清理过期的 content； - 清理过期的 offload； - 回收 HBM Radix Tree 空节点； - 删除没有活跃注册引用的空 (model, tenant) IndexerEntry。 Maintenance 使用 Weak<WorkerRegistry>，不会阻止服务状态释放。回收顶层 Entry 时会保护仍处于注册状态、但暂时没有缓存数据的索引。 #### 2. 为三类匹配缓存增加可配置 TTL 默认配置： 缓存 默认 TTL ━━━━━━━━━━━━━━ ━━━━━━━━━━ pending_pool 60 秒 ────────────── ────────── content 300 秒 ────────────── ────────── offload 600 秒 新增 CLI 参数： --maintenance-interval-secs --pending-ttl-secs --content-ttl-secs --offload-ttl-secs offload 仅使用 TTL，不设置容量上限。 #### 3. 删除事件路径上的惰性清扫 移除基于 ingest 次数触发的 TTL 全量扫描： - 删除 PENDING_SWEEP_THRESHOLD； - 删除 pending_ingest_count； - 删除 maybe_sweep_pending()； - 删除 ingest 路径中的清扫调用。 TTL 清理现在统一由后台 maintenance 负责，即使事件流量停止，过期数据仍能被回收。 #### 4. 删除 HBM 阈值清扫 移除 HBM 删除事件热路径上的全树扫描： - 删除 HBM_SWEEP_THRESHOLD； - 删除 hbm_removal_count； - 删除 maybe_sweep_hbm()； - 删除 Removed、Cleared 中的同步清扫调用。 现在： Removed/Cleared → 只执行精确索引删除 maintenance → 周期性回收 HBM 空节点 避免高流量场景下删除事件出现全树扫描延迟尖峰。 #### 5. 完善 Worker 和 IndexerEntry 回收 - HBM 收到 Cleared 后删除空的外层 WorkerLookup key； - 注销最后一个 DP 时，使用注册记录中的 model/tenant 调用 remove_if_empty()； - maintenance 清理完成后扫描并回收无活跃注册引用的空 IndexerEntry； - maintenance 持有注册表读锁，避免注册与空 Entry 回收之间的竞态。 #### 6. 优化匹配缓存结构 抽取公共内容结构： BlockContent { tokens_hash, parent_hash, } 调整为： OffloadCacheEntry = BlockContent + offload inserted_at ContentEntry = BlockContent + content inserted_at 消除了 ContentEntry 中重复且未使用的第二个时间戳。 #### 7. 清理冗余代码 删除： - 仅供测试使用的 sweep_stale_pending() 包装； - 未使用且实现与注释不一致的 OverlapBlocks::merge()； - 从未构造的 KvConductorError::BlockNotFound； - 只有增减、没有消费者的 replay_in_progress； - 当前重注册流程下不可达的 DuplicateRegistration 错误和 HTTP 409 分支。 重命名重复注册集成测试，以准确表达当前语义： test_same_backend_reregistration_is_accepted #### 8. 更新设计文档 刷新 docs/zh/design/kv_conductor.md 和 KV Conductor README，包括： - 三类缓存及 TTL 生命周期； - 后台 maintenance 调用链； - maintenance 与 ingest 的锁关系； - HBM 空节点回收机制； - 注册、重注册、注销及 replay 生命周期； - 空 IndexerEntry 回收规则； - CLI 参数； - 两阶段 offload/pool 匹配结构； - 删除旧的惰性清扫和容量上限描述。 ### 并发与一致性 Maintenance 和 ingest 修改匹配缓存时，共用： RwLock<OffloadPoolState> 双方获取写锁后串行修改，不会出现数据竞争或部分清扫。Maintenance 可能在扫描期间让 ingest 短暂等待，但清扫已移出事件热路径，延迟影响更加可控。 HBM maintenance 只删除： workers 为空 && children 为空 的节点，不会删除仍被 Worker 持有的有效缓存索引。 ### 兼容性影响 - HTTP API 请求和响应格式不变； - Worker 注册、查询和事件接入协议不变； - 同后端重注册仍返回 201 Created； - 新增 CLI 参数均提供默认值，现有启动方式无需修改； - offload 现在会在 TTL 到期后被回收，极晚到达的 Pool 确认可能无法再匹配，需要根据实际事件延迟调整 --offload-ttl-secs。 ## **3. 资料变更** > 请确认<ins>**是否涉及资料变更**</ins>。\ > 如涉及，需要在PR中体现，并简要说明修改内容。\ > 如不涉及，需填写“不涉及”。 不涉及 ## **4. 接口变更** > 请确认<ins>**是否涉及跨代码仓或者客户面可见的接口变更**</ins>。\ > 如涉及，需详细说明接口以及对应的变更内容，同时需要在资料中体现。\ > 如不涉及，需填写“不涉及”。 不涉及 ## **5. 测试结果** > 需体现<ins>**测试场景，测试方法以及测试结果**</ins>。\ > 测试用例设计时需考虑硬件、部署方式、功能、性能、精度、显存等维度。 ## **6. CheckList** > PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x] [ ] 代码注释完备 [ ] 正确记录维测日志 [ ] 是否有UT用例 [ ] 若涉及多线程场景，考虑了并发场景，不存在死锁问题 See merge request: Ascend/MindIE-Motor!673 | 2 个月前 | |
[bugfix]cpu/disk命中根据parent_hash + token_hash查找 Co-authored-by: ganglv<lvgang1@huawei.com> # message auto-generated for no-merge-commit merge: !601 merge conductor into master [bugfix]cpu/disk命中根据parent_hash + token_hash查找 Created-by: ganglv Commit-by: ganglv Merged-by: towncharlie Description: ## **1. 合入背景** > 请描述为什么要做这个PR内的改动。\ > 如涉及，请关联前序PR或同特性/需求下的其他PR。\ > 如果是修复之前PR引入的问题，请关联引入问题的PR。\ > 请通过#ISSUE ID关联issue。\ > 注意： Fixes #ISSUE ID会自动关闭issue，如问题部分解决请不要使用Fixes，可以用Fix part of #ISSUE ID替代. 完善 KV Conductor 多级缓存亲和性匹配，支持 HBM、CPU、Disk 间连续前缀查询，提升匹配准确性。 [#386](https://gitcode.com/Ascend/MindIE-Motor/issues/386) [#387](https://gitcode.com/Ascend/MindIE-Motor/issues/387) ## **2. 修改内容** > 请<ins>**描述修改内容的具体实现**</ins>，涉及哪些组件之间进行交互，可以用1、2、3、...进行罗列。 > 如果是需求或者重构类的PR，需要<ins>**补充详细设计文档**</ins>（说明上下游组件关系、时序图、类图、DFX能力等内容）。 - 重构多级缓存索引及跨介质断点续查逻辑。 - bugfix for dsv4 flash - 支持disk查询 - 按实例和 DP 聚合各介质命中块数，移除加权评分。 - 完善事件兼容、测试、设计文档及第三方许可证声明。 - 修复log monitor收集日志有重复的问题 - 修改rust precommit失败问题 & rust commit执行慢问题 ## **3. 资料变更** > 请确认<ins>**是否涉及资料变更**</ins>。\ > 如涉及，需要在PR中体现，并简要说明修改内容。\ > 如不涉及，需填写“不涉及”。 不涉及 ## **4. 接口变更** > 请确认<ins>**是否涉及跨代码仓或者客户面可见的接口变更**</ins>。\ > 如涉及，需详细说明接口以及对应的变更内容，同时需要在资料中体现。\ > 如不涉及，需填写“不涉及”。 - 配置项 xpu_endpoint 更名为 gpu_endpoint。 - 注册接口介质名称由 xpu 调整为 gpu，仍兼容旧名称。 - 查询结果由 XPU/CPU/DISK/total 加权分数调整为 gpu_blocks/cpu_blocks/disk_blocks/matched_tokens。 ## **5. 测试结果** > 需体现<ins>**测试场景，测试方法以及测试结果**</ins>。\ > 测试用例设计时需考虑硬件、部署方式、功能、性能、精度、显存等维度。 dsv4_flash  qwen  disk  rename to npu  ## **6. CheckList** > PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x] [ ] 代码注释完备 [ ] 正确记录维测日志 [ ] 是否有UT用例 [ ] 若涉及多线程场景，考虑了并发场景，不存在死锁问题 See merge request: Ascend/MindIE-Motor!601 | 2 个月前 | |
[bugfix]cpu/disk命中根据parent_hash + token_hash查找 Co-authored-by: ganglv<lvgang1@huawei.com> # message auto-generated for no-merge-commit merge: !601 merge conductor into master [bugfix]cpu/disk命中根据parent_hash + token_hash查找 Created-by: ganglv Commit-by: ganglv Merged-by: towncharlie Description: ## **1. 合入背景** > 请描述为什么要做这个PR内的改动。\ > 如涉及，请关联前序PR或同特性/需求下的其他PR。\ > 如果是修复之前PR引入的问题，请关联引入问题的PR。\ > 请通过#ISSUE ID关联issue。\ > 注意： Fixes #ISSUE ID会自动关闭issue，如问题部分解决请不要使用Fixes，可以用Fix part of #ISSUE ID替代. 完善 KV Conductor 多级缓存亲和性匹配，支持 HBM、CPU、Disk 间连续前缀查询，提升匹配准确性。 [#386](https://gitcode.com/Ascend/MindIE-Motor/issues/386) [#387](https://gitcode.com/Ascend/MindIE-Motor/issues/387) ## **2. 修改内容** > 请<ins>**描述修改内容的具体实现**</ins>，涉及哪些组件之间进行交互，可以用1、2、3、...进行罗列。 > 如果是需求或者重构类的PR，需要<ins>**补充详细设计文档**</ins>（说明上下游组件关系、时序图、类图、DFX能力等内容）。 - 重构多级缓存索引及跨介质断点续查逻辑。 - bugfix for dsv4 flash - 支持disk查询 - 按实例和 DP 聚合各介质命中块数，移除加权评分。 - 完善事件兼容、测试、设计文档及第三方许可证声明。 - 修复log monitor收集日志有重复的问题 - 修改rust precommit失败问题 & rust commit执行慢问题 ## **3. 资料变更** > 请确认<ins>**是否涉及资料变更**</ins>。\ > 如涉及，需要在PR中体现，并简要说明修改内容。\ > 如不涉及，需填写“不涉及”。 不涉及 ## **4. 接口变更** > 请确认<ins>**是否涉及跨代码仓或者客户面可见的接口变更**</ins>。\ > 如涉及，需详细说明接口以及对应的变更内容，同时需要在资料中体现。\ > 如不涉及，需填写“不涉及”。 - 配置项 xpu_endpoint 更名为 gpu_endpoint。 - 注册接口介质名称由 xpu 调整为 gpu，仍兼容旧名称。 - 查询结果由 XPU/CPU/DISK/total 加权分数调整为 gpu_blocks/cpu_blocks/disk_blocks/matched_tokens。 ## **5. 测试结果** > 需体现<ins>**测试场景，测试方法以及测试结果**</ins>。\ > 测试用例设计时需考虑硬件、部署方式、功能、性能、精度、显存等维度。 dsv4_flash  qwen  disk  rename to npu  ## **6. CheckList** > PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x] [ ] 代码注释完备 [ ] 正确记录维测日志 [ ] 是否有UT用例 [ ] 若涉及多线程场景，考虑了并发场景，不存在死锁问题 See merge request: Ascend/MindIE-Motor!601 | 2 个月前 | |
[bugfix]cpu/disk命中根据parent_hash + token_hash查找 Co-authored-by: ganglv<lvgang1@huawei.com> # message auto-generated for no-merge-commit merge: !601 merge conductor into master [bugfix]cpu/disk命中根据parent_hash + token_hash查找 Created-by: ganglv Commit-by: ganglv Merged-by: towncharlie Description: ## **1. 合入背景** > 请描述为什么要做这个PR内的改动。\ > 如涉及，请关联前序PR或同特性/需求下的其他PR。\ > 如果是修复之前PR引入的问题，请关联引入问题的PR。\ > 请通过#ISSUE ID关联issue。\ > 注意： Fixes #ISSUE ID会自动关闭issue，如问题部分解决请不要使用Fixes，可以用Fix part of #ISSUE ID替代. 完善 KV Conductor 多级缓存亲和性匹配，支持 HBM、CPU、Disk 间连续前缀查询，提升匹配准确性。 [#386](https://gitcode.com/Ascend/MindIE-Motor/issues/386) [#387](https://gitcode.com/Ascend/MindIE-Motor/issues/387) ## **2. 修改内容** > 请<ins>**描述修改内容的具体实现**</ins>，涉及哪些组件之间进行交互，可以用1、2、3、...进行罗列。 > 如果是需求或者重构类的PR，需要<ins>**补充详细设计文档**</ins>（说明上下游组件关系、时序图、类图、DFX能力等内容）。 - 重构多级缓存索引及跨介质断点续查逻辑。 - bugfix for dsv4 flash - 支持disk查询 - 按实例和 DP 聚合各介质命中块数，移除加权评分。 - 完善事件兼容、测试、设计文档及第三方许可证声明。 - 修复log monitor收集日志有重复的问题 - 修改rust precommit失败问题 & rust commit执行慢问题 ## **3. 资料变更** > 请确认<ins>**是否涉及资料变更**</ins>。\ > 如涉及，需要在PR中体现，并简要说明修改内容。\ > 如不涉及，需填写“不涉及”。 不涉及 ## **4. 接口变更** > 请确认<ins>**是否涉及跨代码仓或者客户面可见的接口变更**</ins>。\ > 如涉及，需详细说明接口以及对应的变更内容，同时需要在资料中体现。\ > 如不涉及，需填写“不涉及”。 - 配置项 xpu_endpoint 更名为 gpu_endpoint。 - 注册接口介质名称由 xpu 调整为 gpu，仍兼容旧名称。 - 查询结果由 XPU/CPU/DISK/total 加权分数调整为 gpu_blocks/cpu_blocks/disk_blocks/matched_tokens。 ## **5. 测试结果** > 需体现<ins>**测试场景，测试方法以及测试结果**</ins>。\ > 测试用例设计时需考虑硬件、部署方式、功能、性能、精度、显存等维度。 dsv4_flash  qwen  disk  rename to npu  ## **6. CheckList** > PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x] [ ] 代码注释完备 [ ] 正确记录维测日志 [ ] 是否有UT用例 [ ] 若涉及多线程场景，考虑了并发场景，不存在死锁问题 See merge request: Ascend/MindIE-Motor!601 | 2 个月前 | |
【bugfix】缓存数据增加TTL，避免内存泄漏 Co-authored-by: ganglv<lvgang1@huawei.com> # message auto-generated for no-merge-commit merge: !673 merge conductor_ttl into master 【bugfix】缓存数据增加TTL，避免内存泄漏 Created-by: ganglv Commit-by: ganglv Merged-by: tobking Description: ## **1. 合入背景** > 请描述为什么要做这个PR内的改动。\ > 如涉及，请关联前序PR或同特性/需求下的其他PR。\ > 如果是修复之前PR引入的问题，请关联引入问题的PR。\ > 请通过#ISSUE ID关联issue。\ > 注意： Fixes #ISSUE ID会自动关闭issue，如问题部分解决请不要使用Fixes，可以用Fix part of #ISSUE ID替代. [#402](https://gitcode.com/Ascend/MindIE-Motor/issues/402) KV Conductor 中部分异步匹配缓存依赖事件流量触发清理，HBM 空节点也曾在事件热路径按删除次数执行全树扫描。这可能导致： - 服务空闲后过期缓存无法及时回收； - 未确认的 offload 数据长期驻留； - HBM 删除事件周期性出现延迟尖峰； - 空 WorkerLookup 或 IndexerEntry 残留； - 注销时使用请求中的 model/tenant，可能无法回收实际注册的索引； - 存在部分无调用或重复存储的代码。 ## **2. 修改内容** > 请<ins>**描述修改内容的具体实现**</ins>，涉及哪些组件之间进行交互，可以用1、2、3、...进行罗列。 > 如果是需求或者重构类的PR，需要<ins>**补充详细设计文档**</ins>（说明上下游组件关系、时序图、类图、DFX能力等内容）。 #### 1. 增加统一后台 Maintenance 服务启动时创建周期性 Tokio maintenance 任务，默认每 30 秒执行： - 清理过期的 pending_pool； - 清理过期的 content； - 清理过期的 offload； - 回收 HBM Radix Tree 空节点； - 删除没有活跃注册引用的空 (model, tenant) IndexerEntry。 Maintenance 使用 Weak<WorkerRegistry>，不会阻止服务状态释放。回收顶层 Entry 时会保护仍处于注册状态、但暂时没有缓存数据的索引。 #### 2. 为三类匹配缓存增加可配置 TTL 默认配置： 缓存 默认 TTL ━━━━━━━━━━━━━━ ━━━━━━━━━━ pending_pool 60 秒 ────────────── ────────── content 300 秒 ────────────── ────────── offload 600 秒 新增 CLI 参数： --maintenance-interval-secs --pending-ttl-secs --content-ttl-secs --offload-ttl-secs offload 仅使用 TTL，不设置容量上限。 #### 3. 删除事件路径上的惰性清扫 移除基于 ingest 次数触发的 TTL 全量扫描： - 删除 PENDING_SWEEP_THRESHOLD； - 删除 pending_ingest_count； - 删除 maybe_sweep_pending()； - 删除 ingest 路径中的清扫调用。 TTL 清理现在统一由后台 maintenance 负责，即使事件流量停止，过期数据仍能被回收。 #### 4. 删除 HBM 阈值清扫 移除 HBM 删除事件热路径上的全树扫描： - 删除 HBM_SWEEP_THRESHOLD； - 删除 hbm_removal_count； - 删除 maybe_sweep_hbm()； - 删除 Removed、Cleared 中的同步清扫调用。 现在： Removed/Cleared → 只执行精确索引删除 maintenance → 周期性回收 HBM 空节点 避免高流量场景下删除事件出现全树扫描延迟尖峰。 #### 5. 完善 Worker 和 IndexerEntry 回收 - HBM 收到 Cleared 后删除空的外层 WorkerLookup key； - 注销最后一个 DP 时，使用注册记录中的 model/tenant 调用 remove_if_empty()； - maintenance 清理完成后扫描并回收无活跃注册引用的空 IndexerEntry； - maintenance 持有注册表读锁，避免注册与空 Entry 回收之间的竞态。 #### 6. 优化匹配缓存结构 抽取公共内容结构： BlockContent { tokens_hash, parent_hash, } 调整为： OffloadCacheEntry = BlockContent + offload inserted_at ContentEntry = BlockContent + content inserted_at 消除了 ContentEntry 中重复且未使用的第二个时间戳。 #### 7. 清理冗余代码 删除： - 仅供测试使用的 sweep_stale_pending() 包装； - 未使用且实现与注释不一致的 OverlapBlocks::merge()； - 从未构造的 KvConductorError::BlockNotFound； - 只有增减、没有消费者的 replay_in_progress； - 当前重注册流程下不可达的 DuplicateRegistration 错误和 HTTP 409 分支。 重命名重复注册集成测试，以准确表达当前语义： test_same_backend_reregistration_is_accepted #### 8. 更新设计文档 刷新 docs/zh/design/kv_conductor.md 和 KV Conductor README，包括： - 三类缓存及 TTL 生命周期； - 后台 maintenance 调用链； - maintenance 与 ingest 的锁关系； - HBM 空节点回收机制； - 注册、重注册、注销及 replay 生命周期； - 空 IndexerEntry 回收规则； - CLI 参数； - 两阶段 offload/pool 匹配结构； - 删除旧的惰性清扫和容量上限描述。 ### 并发与一致性 Maintenance 和 ingest 修改匹配缓存时，共用： RwLock<OffloadPoolState> 双方获取写锁后串行修改，不会出现数据竞争或部分清扫。Maintenance 可能在扫描期间让 ingest 短暂等待，但清扫已移出事件热路径，延迟影响更加可控。 HBM maintenance 只删除： workers 为空 && children 为空 的节点，不会删除仍被 Worker 持有的有效缓存索引。 ### 兼容性影响 - HTTP API 请求和响应格式不变； - Worker 注册、查询和事件接入协议不变； - 同后端重注册仍返回 201 Created； - 新增 CLI 参数均提供默认值，现有启动方式无需修改； - offload 现在会在 TTL 到期后被回收，极晚到达的 Pool 确认可能无法再匹配，需要根据实际事件延迟调整 --offload-ttl-secs。 ## **3. 资料变更** > 请确认<ins>**是否涉及资料变更**</ins>。\ > 如涉及，需要在PR中体现，并简要说明修改内容。\ > 如不涉及，需填写“不涉及”。 不涉及 ## **4. 接口变更** > 请确认<ins>**是否涉及跨代码仓或者客户面可见的接口变更**</ins>。\ > 如涉及，需详细说明接口以及对应的变更内容，同时需要在资料中体现。\ > 如不涉及，需填写“不涉及”。 不涉及 ## **5. 测试结果** > 需体现<ins>**测试场景，测试方法以及测试结果**</ins>。\ > 测试用例设计时需考虑硬件、部署方式、功能、性能、精度、显存等维度。 ## **6. CheckList** > PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x] [ ] 代码注释完备 [ ] 正确记录维测日志 [ ] 是否有UT用例 [ ] 若涉及多线程场景，考虑了并发场景，不存在死锁问题 See merge request: Ascend/MindIE-Motor!673 | 2 个月前 | |
[feature] kv-conductor /query 支持 msgpack 编码，10倍性能收益 Co-authored-by: 吕有辉<lvyouhui@huawei.com> # message auto-generated for no-merge-commit merge: !687 merge opt/kv_conductor_query_msgpack into master [feature] kv-conductor /query 支持 msgpack 编码，10倍性能收益 Created-by: codeDogPro Commit-by: 吕有辉 Merged-by: tobking Description: ## 1. 合入背景 为 kv-conductor 的 /query 与 /query_by_hash 增加 MessagePack 编解码支持，并在 Coordinator 端到端打通（ConductorApiClient.query_conductor 默认走 msgpack）。长上下文（1M/5M token）场景下，KV 亲和性查询的请求体积与编解码耗时显著下降。 借鉴 Mooncake conductor #3258 的 Content-Type 分派方案；与 KV Conductor 的前缀索引能力（#338 对应的自研 kv-conductor）配套演进。 关联 ISSUE：[#455](https://gitcode.com/Ascend/MindIE-Motor/issues/455) ## 2. 修改内容 1. **kv-conductor（Rust，motor/kv_conductor/）** - /query、/query_by_hash 按请求 Content-Type 分派：application/msgpack → rmp_serde 解码请求，响应/错误/空结果用 rmp::encode 手工编码；其他 Content-Type 走原 JSON 路径（行为不变）。 - 响应侧手工编码的原因：QueryResponse 使用 #[serde(flatten)]（tenants 展开到顶层 map），msgpack 序列化器不支持 flatten——手工编码保证 msgpack wire 形状与 JSON 逐字节等价，并有单元测试（rmpv→serde_json 结构化对比）守护。 - QueryRequest / QueryByHashRequest 增加 Serialize（原仅 Deserialize）。 2. **Coordinator（Python）** - ConductorApiClient：新增 encode_query_msgpack / decode_query_response_msgpack（msgspec），query_conductor() 按 kv_conductor_config.query_encoding（默认 "msgpack"）分派；响应按服务器 Content-Type 解析（msgpack → msgspec，否则 JSON），**旧版 JSON-only conductor 自动兼容，无需配置切换**。 - SafeHTTPSClient 新增 post_bytes()（原始 body POST）。 - KvConductorConfig 新增 query_encoding 配置项。 3. **测试** - Rust：单元测试 120（新增 msgpack 往返、wire 形状等价、Content-Type 嗅探、错误/空结果编码）+ 集成测试 20（新增 msgpack/JSON 查询结果一致、msgpack /query_by_hash、404/400 错误路径按请求编码返回）；cargo clippy -D warnings、cargo fmt 通过。 - Python：api_client 44（新增 msgpack wire 格式断言、json 配置路径、legacy JSON 响应 fallback）、coordinator 模块 1155 全过。 - 性能验证使用临时 benchmark 脚本（真实 conductor 进程 + client 真实编解码路径），bench 属验证工具未随 PR 上库。 ## 3. 资料变更 涉及： - docs/zh/user_guide/configuration/config_reference.md：新增 kv_conductor_config.query_encoding 配置说明。 - skill reference（.agent/skills/motor-dev/references/coordinator.md、kv-conductor.md）：新增 msgpack 编解码章节与端到端数据，并修正两处过时内容（服务端加权评分模型已移除、src/indexer.rs → src/indexer/ 目录）。 ## 4. 接口变更 涉及（客户面可见）： - POST /query、POST /query_by_hash 新增 Content-Type: application/msgpack 请求编码支持，响应随请求编码返回（JSON 默认行为不变，向后兼容）。 - Coordinator 配置新增 kv_conductor_config.query_encoding（默认 "msgpack"；对接旧版 conductor 可配 "json"）。 ## 5. 测试结果 **性能收益**（真实 kv-conductor release 进程 + Coordinator client 真实编解码路径，best-of-5，DeepSeek V4 风格长上下文）： === 1M tokens（block_size=128）=== step JSON msgpack 提速 请求体积 encode 29.92 ms 2.89 ms 10.4x 6.65MB -> 2.99MB (-55%) HTTP RTT 45.63 ms 12.07 ms 3.78x (客户端序列化+服务端XXH3哈希/树匹配/序列化+网络) TOTAL 45.63 ms 12.07 ms 3.78x === 5M tokens（block_size=128）=== encode 149.8 ms 14.4 ms 10.4x 33.3MB -> 14.9MB (-55%) HTTP RTT 220.5 ms 41.9 ms 5.26x TOTAL 220.5 ms 41.9 ms 5.26x - 5M 上下文单次查询省 ~178ms，1M 省 ~34ms；请求体积减半（网络传输同步受益）。 - 收益来源：客户端 msgspec 编码（10x）、服务端 rmp 解析 vs serde_json（RTT 内体现）、传输字节减半。 **短上下文覆盖**（1 ~ 16K tokens，纯编解码，msgspec vs json.dumps/loads，best-of-20000）： tokens | json enc msgpack enc | json dec msgpack dec 1 | 1.07us 0.12us | 1.19us 0.21us 64 | 2.83us 0.27us | 2.94us 0.51us 1024 | 26.44us 2.31us | 26.44us 7.96us 16384 | 437.67us 32.82us | 430.86us 148.58us - 全长度区间（1 ~ 16K token）msgpack 均更快：1 token 时亦快 ~9x（编码 0.12us vs 1.07us）； - **无临界点、无负收益**——msgspec 为纯 C 实现，固定开销（~0.1-0.2us）低于 json.dumps/loads 的固定开销（~1-1.2us），短上下文（普通对话场景）同样占优； - 默认 query_encoding: "msgpack" 在短/长上下文下均无回归。 **功能测试**： - cargo test：120 单元 + 20 集成全过； - bash tests/run_tests.sh tests/coordinator/：1155 用例全过； - pre-commit 全量通过（ruff/pylint/bandit/cargo clippy/fmt 等）。 **测试场景**：单元（编解码往返/等价性）、集成（HTTP Content-Type 协商、错误路径、JSON 兼容）、端到端（1M/5M 长上下文性能）。精度/显存不涉及（无模型运行）。 ## 6. CheckList - [x] 代码注释完备 - [x] 正确记录维测日志 - [x] 是否有UT用例（120 Rust 单元 + 20 集成 + 44 Python 单测） - [x] 若涉及多线程场景，考虑了并发场景，不存在死锁问题（查询路径只读锁语义未变，msgpack 编解码为无状态纯函数） See merge request: Ascend/MindIE-Motor!687 | 2 个月前 | |
【bugfix】缓存数据增加TTL，避免内存泄漏 Co-authored-by: ganglv<lvgang1@huawei.com> # message auto-generated for no-merge-commit merge: !673 merge conductor_ttl into master 【bugfix】缓存数据增加TTL，避免内存泄漏 Created-by: ganglv Commit-by: ganglv Merged-by: tobking Description: ## **1. 合入背景** > 请描述为什么要做这个PR内的改动。\ > 如涉及，请关联前序PR或同特性/需求下的其他PR。\ > 如果是修复之前PR引入的问题，请关联引入问题的PR。\ > 请通过#ISSUE ID关联issue。\ > 注意： Fixes #ISSUE ID会自动关闭issue，如问题部分解决请不要使用Fixes，可以用Fix part of #ISSUE ID替代. [#402](https://gitcode.com/Ascend/MindIE-Motor/issues/402) KV Conductor 中部分异步匹配缓存依赖事件流量触发清理，HBM 空节点也曾在事件热路径按删除次数执行全树扫描。这可能导致： - 服务空闲后过期缓存无法及时回收； - 未确认的 offload 数据长期驻留； - HBM 删除事件周期性出现延迟尖峰； - 空 WorkerLookup 或 IndexerEntry 残留； - 注销时使用请求中的 model/tenant，可能无法回收实际注册的索引； - 存在部分无调用或重复存储的代码。 ## **2. 修改内容** > 请<ins>**描述修改内容的具体实现**</ins>，涉及哪些组件之间进行交互，可以用1、2、3、...进行罗列。 > 如果是需求或者重构类的PR，需要<ins>**补充详细设计文档**</ins>（说明上下游组件关系、时序图、类图、DFX能力等内容）。 #### 1. 增加统一后台 Maintenance 服务启动时创建周期性 Tokio maintenance 任务，默认每 30 秒执行： - 清理过期的 pending_pool； - 清理过期的 content； - 清理过期的 offload； - 回收 HBM Radix Tree 空节点； - 删除没有活跃注册引用的空 (model, tenant) IndexerEntry。 Maintenance 使用 Weak<WorkerRegistry>，不会阻止服务状态释放。回收顶层 Entry 时会保护仍处于注册状态、但暂时没有缓存数据的索引。 #### 2. 为三类匹配缓存增加可配置 TTL 默认配置： 缓存 默认 TTL ━━━━━━━━━━━━━━ ━━━━━━━━━━ pending_pool 60 秒 ────────────── ────────── content 300 秒 ────────────── ────────── offload 600 秒 新增 CLI 参数： --maintenance-interval-secs --pending-ttl-secs --content-ttl-secs --offload-ttl-secs offload 仅使用 TTL，不设置容量上限。 #### 3. 删除事件路径上的惰性清扫 移除基于 ingest 次数触发的 TTL 全量扫描： - 删除 PENDING_SWEEP_THRESHOLD； - 删除 pending_ingest_count； - 删除 maybe_sweep_pending()； - 删除 ingest 路径中的清扫调用。 TTL 清理现在统一由后台 maintenance 负责，即使事件流量停止，过期数据仍能被回收。 #### 4. 删除 HBM 阈值清扫 移除 HBM 删除事件热路径上的全树扫描： - 删除 HBM_SWEEP_THRESHOLD； - 删除 hbm_removal_count； - 删除 maybe_sweep_hbm()； - 删除 Removed、Cleared 中的同步清扫调用。 现在： Removed/Cleared → 只执行精确索引删除 maintenance → 周期性回收 HBM 空节点 避免高流量场景下删除事件出现全树扫描延迟尖峰。 #### 5. 完善 Worker 和 IndexerEntry 回收 - HBM 收到 Cleared 后删除空的外层 WorkerLookup key； - 注销最后一个 DP 时，使用注册记录中的 model/tenant 调用 remove_if_empty()； - maintenance 清理完成后扫描并回收无活跃注册引用的空 IndexerEntry； - maintenance 持有注册表读锁，避免注册与空 Entry 回收之间的竞态。 #### 6. 优化匹配缓存结构 抽取公共内容结构： BlockContent { tokens_hash, parent_hash, } 调整为： OffloadCacheEntry = BlockContent + offload inserted_at ContentEntry = BlockContent + content inserted_at 消除了 ContentEntry 中重复且未使用的第二个时间戳。 #### 7. 清理冗余代码 删除： - 仅供测试使用的 sweep_stale_pending() 包装； - 未使用且实现与注释不一致的 OverlapBlocks::merge()； - 从未构造的 KvConductorError::BlockNotFound； - 只有增减、没有消费者的 replay_in_progress； - 当前重注册流程下不可达的 DuplicateRegistration 错误和 HTTP 409 分支。 重命名重复注册集成测试，以准确表达当前语义： test_same_backend_reregistration_is_accepted #### 8. 更新设计文档 刷新 docs/zh/design/kv_conductor.md 和 KV Conductor README，包括： - 三类缓存及 TTL 生命周期； - 后台 maintenance 调用链； - maintenance 与 ingest 的锁关系； - HBM 空节点回收机制； - 注册、重注册、注销及 replay 生命周期； - 空 IndexerEntry 回收规则； - CLI 参数； - 两阶段 offload/pool 匹配结构； - 删除旧的惰性清扫和容量上限描述。 ### 并发与一致性 Maintenance 和 ingest 修改匹配缓存时，共用： RwLock<OffloadPoolState> 双方获取写锁后串行修改，不会出现数据竞争或部分清扫。Maintenance 可能在扫描期间让 ingest 短暂等待，但清扫已移出事件热路径，延迟影响更加可控。 HBM maintenance 只删除： workers 为空 && children 为空 的节点，不会删除仍被 Worker 持有的有效缓存索引。 ### 兼容性影响 - HTTP API 请求和响应格式不变； - Worker 注册、查询和事件接入协议不变； - 同后端重注册仍返回 201 Created； - 新增 CLI 参数均提供默认值，现有启动方式无需修改； - offload 现在会在 TTL 到期后被回收，极晚到达的 Pool 确认可能无法再匹配，需要根据实际事件延迟调整 --offload-ttl-secs。 ## **3. 资料变更** > 请确认<ins>**是否涉及资料变更**</ins>。\ > 如涉及，需要在PR中体现，并简要说明修改内容。\ > 如不涉及，需填写“不涉及”。 不涉及 ## **4. 接口变更** > 请确认<ins>**是否涉及跨代码仓或者客户面可见的接口变更**</ins>。\ > 如涉及，需详细说明接口以及对应的变更内容，同时需要在资料中体现。\ > 如不涉及，需填写“不涉及”。 不涉及 ## **5. 测试结果** > 需体现<ins>**测试场景，测试方法以及测试结果**</ins>。\ > 测试用例设计时需考虑硬件、部署方式、功能、性能、精度、显存等维度。 ## **6. CheckList** > PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x] [ ] 代码注释完备 [ ] 正确记录维测日志 [ ] 是否有UT用例 [ ] 若涉及多线程场景，考虑了并发场景，不存在死锁问题 See merge request: Ascend/MindIE-Motor!673 | 2 个月前 | |
[feature] kv-conductor /query 支持 msgpack 编码，10倍性能收益 Co-authored-by: 吕有辉<lvyouhui@huawei.com> # message auto-generated for no-merge-commit merge: !687 merge opt/kv_conductor_query_msgpack into master [feature] kv-conductor /query 支持 msgpack 编码，10倍性能收益 Created-by: codeDogPro Commit-by: 吕有辉 Merged-by: tobking Description: ## 1. 合入背景 为 kv-conductor 的 /query 与 /query_by_hash 增加 MessagePack 编解码支持，并在 Coordinator 端到端打通（ConductorApiClient.query_conductor 默认走 msgpack）。长上下文（1M/5M token）场景下，KV 亲和性查询的请求体积与编解码耗时显著下降。 借鉴 Mooncake conductor #3258 的 Content-Type 分派方案；与 KV Conductor 的前缀索引能力（#338 对应的自研 kv-conductor）配套演进。 关联 ISSUE：[#455](https://gitcode.com/Ascend/MindIE-Motor/issues/455) ## 2. 修改内容 1. **kv-conductor（Rust，motor/kv_conductor/）** - /query、/query_by_hash 按请求 Content-Type 分派：application/msgpack → rmp_serde 解码请求，响应/错误/空结果用 rmp::encode 手工编码；其他 Content-Type 走原 JSON 路径（行为不变）。 - 响应侧手工编码的原因：QueryResponse 使用 #[serde(flatten)]（tenants 展开到顶层 map），msgpack 序列化器不支持 flatten——手工编码保证 msgpack wire 形状与 JSON 逐字节等价，并有单元测试（rmpv→serde_json 结构化对比）守护。 - QueryRequest / QueryByHashRequest 增加 Serialize（原仅 Deserialize）。 2. **Coordinator（Python）** - ConductorApiClient：新增 encode_query_msgpack / decode_query_response_msgpack（msgspec），query_conductor() 按 kv_conductor_config.query_encoding（默认 "msgpack"）分派；响应按服务器 Content-Type 解析（msgpack → msgspec，否则 JSON），**旧版 JSON-only conductor 自动兼容，无需配置切换**。 - SafeHTTPSClient 新增 post_bytes()（原始 body POST）。 - KvConductorConfig 新增 query_encoding 配置项。 3. **测试** - Rust：单元测试 120（新增 msgpack 往返、wire 形状等价、Content-Type 嗅探、错误/空结果编码）+ 集成测试 20（新增 msgpack/JSON 查询结果一致、msgpack /query_by_hash、404/400 错误路径按请求编码返回）；cargo clippy -D warnings、cargo fmt 通过。 - Python：api_client 44（新增 msgpack wire 格式断言、json 配置路径、legacy JSON 响应 fallback）、coordinator 模块 1155 全过。 - 性能验证使用临时 benchmark 脚本（真实 conductor 进程 + client 真实编解码路径），bench 属验证工具未随 PR 上库。 ## 3. 资料变更 涉及： - docs/zh/user_guide/configuration/config_reference.md：新增 kv_conductor_config.query_encoding 配置说明。 - skill reference（.agent/skills/motor-dev/references/coordinator.md、kv-conductor.md）：新增 msgpack 编解码章节与端到端数据，并修正两处过时内容（服务端加权评分模型已移除、src/indexer.rs → src/indexer/ 目录）。 ## 4. 接口变更 涉及（客户面可见）： - POST /query、POST /query_by_hash 新增 Content-Type: application/msgpack 请求编码支持，响应随请求编码返回（JSON 默认行为不变，向后兼容）。 - Coordinator 配置新增 kv_conductor_config.query_encoding（默认 "msgpack"；对接旧版 conductor 可配 "json"）。 ## 5. 测试结果 **性能收益**（真实 kv-conductor release 进程 + Coordinator client 真实编解码路径，best-of-5，DeepSeek V4 风格长上下文）： === 1M tokens（block_size=128）=== step JSON msgpack 提速 请求体积 encode 29.92 ms 2.89 ms 10.4x 6.65MB -> 2.99MB (-55%) HTTP RTT 45.63 ms 12.07 ms 3.78x (客户端序列化+服务端XXH3哈希/树匹配/序列化+网络) TOTAL 45.63 ms 12.07 ms 3.78x === 5M tokens（block_size=128）=== encode 149.8 ms 14.4 ms 10.4x 33.3MB -> 14.9MB (-55%) HTTP RTT 220.5 ms 41.9 ms 5.26x TOTAL 220.5 ms 41.9 ms 5.26x - 5M 上下文单次查询省 ~178ms，1M 省 ~34ms；请求体积减半（网络传输同步受益）。 - 收益来源：客户端 msgspec 编码（10x）、服务端 rmp 解析 vs serde_json（RTT 内体现）、传输字节减半。 **短上下文覆盖**（1 ~ 16K tokens，纯编解码，msgspec vs json.dumps/loads，best-of-20000）： tokens | json enc msgpack enc | json dec msgpack dec 1 | 1.07us 0.12us | 1.19us 0.21us 64 | 2.83us 0.27us | 2.94us 0.51us 1024 | 26.44us 2.31us | 26.44us 7.96us 16384 | 437.67us 32.82us | 430.86us 148.58us - 全长度区间（1 ~ 16K token）msgpack 均更快：1 token 时亦快 ~9x（编码 0.12us vs 1.07us）； - **无临界点、无负收益**——msgspec 为纯 C 实现，固定开销（~0.1-0.2us）低于 json.dumps/loads 的固定开销（~1-1.2us），短上下文（普通对话场景）同样占优； - 默认 query_encoding: "msgpack" 在短/长上下文下均无回归。 **功能测试**： - cargo test：120 单元 + 20 集成全过； - bash tests/run_tests.sh tests/coordinator/：1155 用例全过； - pre-commit 全量通过（ruff/pylint/bandit/cargo clippy/fmt 等）。 **测试场景**：单元（编解码往返/等价性）、集成（HTTP Content-Type 协商、错误路径、JSON 兼容）、端到端（1M/5M 长上下文性能）。精度/显存不涉及（无模型运行）。 ## 6. CheckList - [x] 代码注释完备 - [x] 正确记录维测日志 - [x] 是否有UT用例（120 Rust 单元 + 20 集成 + 44 Python 单测） - [x] 若涉及多线程场景，考虑了并发场景，不存在死锁问题（查询路径只读锁语义未变，msgpack 编解码为无状态纯函数） See merge request: Ascend/MindIE-Motor!687 | 2 个月前 | |
[bugfix]cpu/disk命中根据parent_hash + token_hash查找 Co-authored-by: ganglv<lvgang1@huawei.com> # message auto-generated for no-merge-commit merge: !601 merge conductor into master [bugfix]cpu/disk命中根据parent_hash + token_hash查找 Created-by: ganglv Commit-by: ganglv Merged-by: towncharlie Description: ## **1. 合入背景** > 请描述为什么要做这个PR内的改动。\ > 如涉及，请关联前序PR或同特性/需求下的其他PR。\ > 如果是修复之前PR引入的问题，请关联引入问题的PR。\ > 请通过#ISSUE ID关联issue。\ > 注意： Fixes #ISSUE ID会自动关闭issue，如问题部分解决请不要使用Fixes，可以用Fix part of #ISSUE ID替代. 完善 KV Conductor 多级缓存亲和性匹配，支持 HBM、CPU、Disk 间连续前缀查询，提升匹配准确性。 [#386](https://gitcode.com/Ascend/MindIE-Motor/issues/386) [#387](https://gitcode.com/Ascend/MindIE-Motor/issues/387) ## **2. 修改内容** > 请<ins>**描述修改内容的具体实现**</ins>，涉及哪些组件之间进行交互，可以用1、2、3、...进行罗列。 > 如果是需求或者重构类的PR，需要<ins>**补充详细设计文档**</ins>（说明上下游组件关系、时序图、类图、DFX能力等内容）。 - 重构多级缓存索引及跨介质断点续查逻辑。 - bugfix for dsv4 flash - 支持disk查询 - 按实例和 DP 聚合各介质命中块数，移除加权评分。 - 完善事件兼容、测试、设计文档及第三方许可证声明。 - 修复log monitor收集日志有重复的问题 - 修改rust precommit失败问题 & rust commit执行慢问题 ## **3. 资料变更** > 请确认<ins>**是否涉及资料变更**</ins>。\ > 如涉及，需要在PR中体现，并简要说明修改内容。\ > 如不涉及，需填写“不涉及”。 不涉及 ## **4. 接口变更** > 请确认<ins>**是否涉及跨代码仓或者客户面可见的接口变更**</ins>。\ > 如涉及，需详细说明接口以及对应的变更内容，同时需要在资料中体现。\ > 如不涉及，需填写“不涉及”。 - 配置项 xpu_endpoint 更名为 gpu_endpoint。 - 注册接口介质名称由 xpu 调整为 gpu，仍兼容旧名称。 - 查询结果由 XPU/CPU/DISK/total 加权分数调整为 gpu_blocks/cpu_blocks/disk_blocks/matched_tokens。 ## **5. 测试结果** > 需体现<ins>**测试场景，测试方法以及测试结果**</ins>。\ > 测试用例设计时需考虑硬件、部署方式、功能、性能、精度、显存等维度。 dsv4_flash  qwen  disk  rename to npu  ## **6. CheckList** > PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x] [ ] 代码注释完备 [ ] 正确记录维测日志 [ ] 是否有UT用例 [ ] 若涉及多线程场景，考虑了并发场景，不存在死锁问题 See merge request: Ascend/MindIE-Motor!601 | 2 个月前 |
| 文件 | 最后提交记录 | 最后更新时间 |
|---|---|---|
| 2 个月前 | ||
| 2 个月前 | ||
| 2 个月前 | ||
| 2 个月前 | ||
| 2 个月前 | ||
| 2 个月前 | ||
| 2 个月前 | ||
| 2 个月前 | ||
| 2 个月前 | ||
| 2 个月前 | ||
| 2 个月前 | ||
| 2 个月前 | ||
| 2 个月前 |