已合并
[feature]mooncake standalone部署模式适配 #783
[feature]mooncake standalone部署模式适配 #783
已合并
zhinengwu创建于 11 天前
zhinengwu
zhinengwu
11 天前

1. 合入背景

Mooncake 池化后端原仅有 in-process(embedded)模式:池化内存由引擎进程贡献,引擎故障则池内存失效,且大块内存与引擎权重 / KV 内存同进程竞争。本 PR 为 mooncake 池化后端适配 standalone
部署模式
:由 NodeManager 在每个引擎 Pod 内拉起独立 mooncake_store_service 进程贡献池化内存,与引擎生命周期解耦,引擎仅作为纯请求方。
Fixes #511

2. 修改内容

  1. 新增 motor/node_manager/core/services/mooncake/lifecycle.py + bootstrap/ + __init__.py):通过 service registry 注册 backend="mooncake" 的 KV store 服务,管理
    mooncake_store_service 子进程生命周期:
    • prepare 阶段只生成 store 配置(mooncake_store_config.jsonlocal_hostname 取 POD_IP、master 地址取 KVS_MASTER_SERVICE),不启动进程,避免引擎启动等待 store;
    • start 流程引擎拉起后(pull_kv_store)启动 store 进程;protocol=ascend 时经 bootstrap/ascend_800I.py / bootstrap/ascend_850.py 启动:进程内创建 ACL device context(store 自身不调用
      aclrtSetDevice),保持 comm-free 不建 HCCL comm(store 与引擎 worker 同节点同卡时,comm 会使 adxl P2P 握手合并 ranktable 出现重复 device IP,HCCL 校验报 EI0014);bootstrap
      初始化失败非致命(stderr 告警后 store 照常启动);
    • store 通信环境自动配置:HIXL comm_resource_config.listen_port=26666(merge 进 ASCEND_GLOBAL_RESOURCE_CONFIG,保留 UBOE protocol_desc 等既有项),使 store 在 ranktable 中携带独立
      device_port,与同卡 worker 区分;HCCL socket 端口段避开引擎(A2:HCCL_NPU_SOCKET_PORT_RANGE=16700-16800;A5:host socket 段 +2000),防止与引擎 16666/RA socket 冲突(EI0020);REST
      端口默认 0 由内核分配临时端口(hostNetwork 同机端口安全);
    • health_check 监视进程,死亡即原地重拉并重新注册 master(受 MOTOR_RESTART_LOCAL_SERVICE 控制,默认开启);
  2. motor/config/node_manager.pyKVCacheStoreConfig 新增 store_mode / global_segment_size / local_buffer_size / store_http_port / metadata_server / protocol / device_name
    配置项及解析、校验(store_mode 非法值回退 embedded)、配置打印;
  3. motor/common/utils/env.py:新增 MOONCAKE_CONFIG_PATH 环境变量;
  4. motor/node_manager/core/services/registry.py:注册 mooncake 服务模块;
  5. 资料变更:mooncake.md 新增 standalone 模式章节与环境变量说明、kv_cache_store README 参数表更新、nodeman.md 引用同步。

3. 资料变更

涉及:

  • docs/zh/user_guide/features/kv_cache_store/backend/mooncake.md:新增「standalone 模式(独立 store 进程)」章节(部署架构、P/D 配置示例、字段说明);环境变量章节明确所有硬件必配
    HCCL_INTRA_ROCE_ENABLE=1ASCEND_LOCAL_COMM_RES={"version":"1.3"}(v1.3 格式本地通信资源,走 client-server 单边通信,ranktable 携带 device_port,是同卡多进程建链的前提,缺失报
    EI0014);补充 store 侧通信环境由 NodeManager 自动配置、无需手工干预的说明;
  • docs/zh/user_guide/features/kv_cache_store/README.md:参数表新增 store_mode / local_buffer_size / store_http_port
  • .agent/skills/motor-dev/references/nodeman.md:同步更新。

4. 接口变更

涉及(客户面可见配置接口变更,已在资料中体现):

  • kv_cache_store_config 新增字段:store_mode""/embedded/standalone,默认 embedded)、global_segment_sizelocal_buffer_sizestore_http_port(默认
    0)、metadata_serverprotocoldevice_name
  • 新增可选环境变量 MOONCAKE_CONFIG_PATH
  • env.json 引擎角色(motor_engine_prefill_env / motor_engine_decode_env)新增必配项:HCCL_INTRA_ROCE_ENABLE=1ASCEND_LOCAL_COMM_RES={"version":"1.3"}(所有硬件,Prefill/Decode
    保持一致)。

5. 测试结果

  • UTbash tests/run_tests.sh):新增 tests/node_manager/core/services/mooncake/test_lifecycle.py(覆盖 prepare 配置生成、pull 幂等启动、stop、health_check 原地重拉、非 standalone
    模式不拉起、store listen_port merge 覆盖等场景)与 tests/node_manager/core/services/mooncake/test_store_bootstrap.py(覆盖两个 bootstrap 的 ACL context
    初始化与失败非致命);tests/node_manager/test_config.pytests/node_manager/core/services/test_registry.py 同步更新,模块 23 个用例全部通过,pre-commit 全绿。
  • 实机验证(800I A2,P/D 分离 standalone 部署):基础推理正常;>128 token 请求触发入池,prefill 入池 / decode 出池正常(重复请求 kvpool hit tokens: 256, need to load: 0,decode External
    prefix cache hit rate 100%);store 与 worker 同卡共存无 EI0014/EI0020;kill 掉 store 进程后 NodeManager 原地重拉成功。

6. CheckList

[x] 代码注释完备
[x] 正确记录维测日志
[x] 是否有UT用例
[x] 若涉及多线程场景,考虑了并发场景,不存在死锁问题

likedislike
Pull Request已成功合入, 合并人@wangyang
(感谢 zhinengwu 的贡献)
zhinengwuzhinengwu
11 天前 关联了issue:[Feature-Request|需求反馈]: mooncake 池化后端适配 standalone 部署模式(NodeManager 管理独立 store 进程)
atomgit-bot
atomgit-bot
11 天前 评论:

变更摘要

本 PR 为 mooncake 池化后端适配 standalone 部署模式(Fixes #511):原 in-process(embedded)模式下池化内存由引擎进程贡献,引擎故障会导致池内存失效;本次改造后由 NodeManager 在引擎 Pod 内以 service registry 注册 backend="mooncake" 的 KV store 服务(MooncakeStoreService),在引擎拉起后启动独立 mooncake_store_service 子进程贡献池化内存,使 store 与引擎生命周期解耦,引擎仅作为纯请求方。同时新增 KVCacheStoreConfig 的 standalone 相关配置项、MOONCAKE_CONFIG_PATH 环境变量,并配套更新部署配置生成、文档与 UT 用例。

主要改动

  • 新增 motor/node_manager/core/services/mooncake/lifecycle.pyMooncakeStoreService: 通过 @register_service(SERVICE_KV_STORE, backend="mooncake", ...) 注册服务;prepare 阶段仅生成 mooncake_store_config.json 不启动进程(避免引擎启动等待 store),pull 在引擎拉起后幂等启动 store 子进程,health_check 在进程死亡时原地重拉并重新注册 master(受 MOTOR_RESTART_LOCAL_SERVICE 控制)。
  • ascend 协议启动增强: pullpython -c 内置 bootstrap(_STORE_BOOTSTRAP_ASCEND)为 store 进程预建 ACL 设备上下文并完成 2-rank HcclGetRootInfo/HcclCommInitRootInfo P2P 握手;同时注入 ASCEND_GLOBAL_RESOURCE_CONFIG 将 HIXL listen port 设为 16667(避开引擎 comm 默认 16666),并注入 ASCEND_SLOG_PRINT_TO_STDOUT=1 便于日志采集。
  • motor/config/node_manager.py 配置扩展: KVCacheStoreConfig 新增 store_mode / global_segment_size / local_buffer_size / store_http_port(默认 0,由内核分配临时端口)/ metadata_server / protocol / device_name 字段及其解析校验(store_mode 非法值回退 embedded),并在配置打印中新增 Store Mode、Global Segment Size 项。
  • 配套基础设施与部署配置: motor/common/utils/env.py 新增 MOONCAKE_CONFIG_PATH 环境变量读取;motor/node_manager/core/services/registry.pymooncake 注册进 _DEFAULT_MODULE_MAPexamples/deployer/.../mooncake_config.py 在 standalone 模式下将引擎侧 global_segment_size 置 0、local_buffer_size 默认 "1GB",并默认 metadata_server="P2PHANDSHAKE"
  • 测试用例更新: 新增 tests/node_manager/core/services/mooncake/test_lifecycle.py(覆盖 prepare 配置生成、pull 幂等启动、stop、health_check 原地重拉、非 standalone 模式不拉起等场景),并同步更新 tests/node_manager/test_config.py(新字段解析与非法 store_mode 回退)和 tests/node_manager/core/services/test_registry.py
likedislike
atomgit-bot
atomgit-bot
11 天前 评论:

代码审查

我已完成对全部 9 个变更文件的逐文件审查,并报告了 5 个发现。

审查结果

发现的发现(按优先级)

优先级 文件:行 问题
P2 tests/.../mooncake/test_lifecycle.py:150 test_pull_injects_hixl_listen_port 首处断言期望 "26666",而代码(lifecycle.py:256)默认值及 PR 设计均为 "16667",干净环境下该测试必然失败(仅当运行环境恰好存在 HIXL_LISTEN_PORT=26666 时才会偶然通过)
P2 motor/.../mooncake/lifecycle.py:267-269 pull() 吞掉启动异常且置 _store_process=Nonehealth_check() 只在"曾成功启动后死亡"时重拉,首次启动失败(瞬时故障)永远不会被重试,池化内存永久缺失,且绕过 API 层依赖异常清理引擎的路径
P3 motor/.../mooncake/lifecycle.py:171 master service 为空(KVS_MASTER_SERVICE 未设置)时生成畸形 master_server_address=":50088",缺少与 mooncake_config.py:104-107 一致的显式校验
P3 motor/.../mooncake/lifecycle.py:211-214 pull()is_alive() 检查与 Popen 非原子、无锁,API 线程与 monitor 线程并发可双开 store 进程(双份内存分配 / 重复注册)
P3 motor/config/node_manager.py:747-749 mooncake 字段解析仅认 kv 内的 backend 键;enable 逻辑显式支持的 env-only 路径(KV_STORE_BACKEND=mooncake)下 store_mode 等新字段被静默忽略,standalone 被静默禁用

逐文件确认

  • examples/deployer/startup/roles/kv_store_backends/mooncake/mooncake_config.py — 已审查,no issues(standalone 覆盖逻辑与 PR 设计一致,out_cfg 为浅拷贝未污染 kv_cfg
  • motor/common/utils/env.py — 已审查,no issues(纯属性新增,默认值/None 处理正确)
  • motor/config/node_manager.py — 已审查,发现 1 个 P3(见上表)
  • motor/node_manager/core/services/mooncake/__init__.py — 已审查,no issues(仅 docstring)
  • motor/node_manager/core/services/mooncake/lifecycle.py — 已审查,发现 1 个 P2 + 2 个 P3(见上表);-c bootstrap 的 argv/runpy 用法、SIGKILL 后 helper 孤儿回收逻辑均确认可行
  • motor/node_manager/core/services/registry.py — 已审查,no issues(单行 module map 注册,与 discover()/register() 契约一致)
  • tests/node_manager/core/services/mooncake/test_lifecycle.py — 已审查,发现 1 个 P2(见上表)
  • tests/node_manager/core/services/test_registry.py — 已审查,no issues(改用 memcache/future_backend 规避与新增真实 backend 键的冲突,合理)
  • tests/node_manager/test_config.py — 已审查,no issues(新字段解析/回退断言与解析器逻辑一致)

总体风险判断

共 2 个 P2、3 个 P3。核心 standalone 生命周期设计合理、配置解析与注册链路一致,但存在一处确定性测试失败(干净 CI 会红)和一处store 启动失败后永不复原的可靠性缺口(池化内存可能在生产中静默缺失),建议合入前修复这两项;其余为低概率并发竞态与配置校验缺口。无 P0/P1 级问题。

类型 数量
🔴 阻塞 0
🟡 建议 1

💬 仅评论

likedislike
ascend-robotascend-robot成员
11 天前 添加了label:ascend-cla/yes
ascend-robotascend-robot成员
11 天前 添加了label:ci-pipeline-running
此处折叠了120条消息 查看更多
zhinengwuzhinengwu
7 天前 修改标题为 “[feature]mooncake standalone部署模式适配”,原标题为“[B030需求]mooncake standalone部署模式适配”
wangyang
wangyang成员
7 天前 评论:

/lgtm
/approve

likedislike
ascend-robotascend-robot成员
7 天前 添加了label:approved
wangyangwangyang成员
7 天前 关闭了关联的issue
wangyangwangyang成员
7 天前 合入了pull request