master

文件	最后提交记录	最后更新时间
test_controller_config.py	[Feature] 引擎重启兜底策略：容器不重启重拉引擎 + 自杀裁决收敛 Daemon Co-authored-by: 吕有辉<lvyouhui@huawei.com> # message auto-generated for no-merge-commit merge: !710 merge feature/engine_relaunch into master [Feature] 引擎重启兜底策略：容器不重启重拉引擎 + 自杀裁决收敛 Daemon Created-by: codeDogPro Commit-by: 吕有辉 Merged-by: tobking Description: ### 1. 合入背景 引擎进程死亡后，当前唯一兜底是「NodeManager 心跳 abnormal ×5（约 15s）→ 自杀 → k8s 重启 pod」，代价是全容器重建。本 PR 实现「容器不重启重拉引擎」：Controller 协同实例的**所有** NodeManager 一起重拉全部引擎（rank 集合通信组一致性），重拉失败再回退到容器重启；同时把自杀裁决权收敛到 Daemon（进程生命周期管理者）。 本 PR 基于最新主线：原生引擎拉起（#698：NodeManager 直接 spawn 原生 vLLM/SGLang，删除 EngineServer 层）与 EngineServer 删除收尾（#717）均已合入，重拉链路已对接原生拉起路径。 关联 ISSUE：#472 ### 2. 修改内容 1. **Controller 引擎重启兜底策略**（motor/controller/fault_tolerance/strategy/engine_relaunch.py，两阶段）： - Phase 1 重启引擎：探活实例全部 NodeManager（任一不可达 → 直接 Phase 2，保证 rank 一致性）→ 逐个下发 POST /node-manager/engine-restart → 轮询 /node-manager/status 全部 NORMAL → 成功 - Phase 2 重启容器：仅对**未成功派发重启**的 NM 发 abort 解冻自杀（已派发 NM 保持 freeze，避免打断正在恢复的引擎）→ 心跳机制触发容器重启（k8s）；abort 发送失败补 error 日志指名 NM；实例 DELETED/消失提前结束 - stop() 被打断时 fire-and-forget 发 abort（防冻结窗口内 NM 自杀被延迟） 2. **策略失败升级机制（可复用）**：StrategyBase.mark_failed() + InstanceMetadata.prev_strategy_failed——token 重推/UCE/弹性扩缩容等「期望引擎不重启快速恢复」的策略失败后，策略中心自动降级到 EngineRelaunchStrategy（兜底链）；升级分支同样受 enable_engine_relaunch 门控 3. **level2_strategy 挂钩**：ENGINE_DEAD 软件故障直接触发 EngineRelaunchStrategy（开关关闭 → None） 4. **NodeManager 新路由** POST /node-manager/engine-restart（node_manager_api.py）：body {"action": "restart"|"abort", "instance_id"}；**薄路由**——restart 整体委托 Daemon.restart_engine（Daemon 内部解析启动参数、冻结自杀、暂停/恢复 FaultReporter、只停引擎服务重拉不动 KV store/监控线程），路由只做 HTTP 语义映射（并发 409、快照恢复中 409、未 start 400、失败 500，零锁零状态）。部分失联协同**复用既有 /node-manager/stop**（不在 restart 路由新加 shutdown action） 5. **自杀冻结**（daemon.py）：截止时间制 freeze/unfreeze（abort 丢失自动过期，容器重启兜底永存）；**freeze 仅在死亡上报成功后才执行**（上报失败 → Controller 不可达 → 不冻结，仲裁继续计数，容器重启兜底不被拖死）；**freeze 受 enable_engine_relaunch 门控**（未开开关 → 不上报后不冻结，pod 快速自终止走 k8s 容器重启，不被 180s 冻结窗口拖延） 6. **FaultReporter 重拉编排**：重拉期间由 Daemon 暂停轮询（引擎被杀期间 FT 端口不可达，poll 失败会被误报死亡），重拉成功后 Daemon 恢复轮询并清空轮询状态（新引擎自然重新起算启动宽限）；另修复首次 poll 失败即冻结自杀的时序竞态（自杀 ~15s vs DEAD 上报 15-30s） 7. **自杀裁决收敛 Daemon**：心跳模块收敛为状态源（has_abnormal_endpoints/endpoints_generation/is_within_grace_period），Daemon 独立 3s 仲裁线程统一裁决（5×3s≈15s，间隔跟随 heartbeat_interval_seconds 配置）+ 统一 freeze/should_suicide；**冷启动误判门槛**：只有「曾经 NORMAL」的 endpoint 异常才上报死亡（模型加载期不误报） 8. **引擎就绪等待下沉**：_engine_ready 握手事件 + Daemon 后台 wait_ready——heartbeat 不再感知引擎就绪、不再 import Daemon（循环依赖解除），状态线程在探测前等待握手 9. **改名**：EngineManager → RegisterManager（register_manager.py，职责=注册/元数据管理，与 Daemon 进程管理区分） 10. **结构**：StrategyBase 移至 strategy/base.py（消除循环 import） 11. **配置收敛（唯一开关）**：enable_engine_relaunch（默认开）为「容器不重启重拉引擎」唯一开关——Controller 侧 fault_tolerance_config（策略选择门控）+ NodeManager 侧 fault_tolerance_config（同名配置，freeze 门控）；**删除 MOTOR_RESTART_ENGINE 环境变量及 health_check 的 SIGTERM 自杀快路径**，恢复路径统一由 Daemon 按开关决策 12. **重拉日志分隔标记**：旧引擎 stop 后、新引擎 pull 前，print 直达容器 stdout 打印 [ENGINE RELAUNCH #N] banner（容器生命周期内重拉计数 + 时间），多次重拉日志按次分区检索 13. **原生拉起适配（rebase #698/#717）**：重拉/就绪握手/死亡上报链路对接 native_engine；心跳经 RuntimeState probe 查询（STARTING/STOPPING 保留原状态）；进程组清理（start_new_session + killpg + 退出等待 + 僵尸收割）；bootstrap_port 字段；过时 EngineServer 提法清理 ### 3. 资料变更 涉及，同步更新： - docs/zh/developer_guide/components/node_manager.md：模块表（RegisterManager）、自杀裁决章节 - docs/zh/design/fault_tolerance/overview.md / fault_manager.md：策略/模块引用同步 - examples/features/config_sample.json：两侧 fault_tolerance_config 新字段 - skill refs（nodeman.md、controller.md、code-style.md）——nodeman.md 已随 #717 文档清理合并 ### 4. 接口变更 涉及（NodeManager 管理面接口 + 配置）： - 新增 POST /node-manager/engine-restart：body {"action": "restart"|"abort", "instance_id": int?}，200/400/409/500 - /node-manager/stop 语义补全为「自杀」：停引擎后延时 SIGTERM 自身（退出 -1 → k8s 重启 pod）。部分失联时 Controller 对存活 NM 复用该接口下发自杀（不再依赖引擎重拉路由） - 新增 Controller 配置 fault_tolerance_config.enable_engine_relaunch（默认 true）/ engine_relaunch_complete_timeout_sec / engine_relaunch_poll_interval_sec / engine_relaunch_dispatch_retries / engine_relaunch_nm_unreachable_threshold - 新增 NodeManager 配置 fault_tolerance_config.enable_engine_relaunch（默认 true，与 Controller 对齐）/ engine_restart_wait_timeout_sec（180s）/ engine_restart_freeze_sec（720s） - **删除** MOTOR_RESTART_ENGINE 环境变量（配置收敛，统一由 enable_engine_relaunch 决策） ### 5. 测试结果 **单测**（bash tests/run_tests.sh 全量）：**2665 passed**（rebase #698/#717 后全量基线之上） 新增/重写测试覆盖： - EngineRelaunchStrategy：Phase 1 探活全部 NM / 探活失败直接 Phase 2 / 下发全部 NM / 轮询成功 / NM 连续不可达进 Phase 2 / 超时 abort / 实例消失提前结束 / event 打断 / Phase 2 只 abort 未派发 NM - 策略失败升级：StrategyBase 失败标记 / 策略中心 prev_strategy_failed 置位与清除 / 升级选择 EngineRelaunchStrategy - level2_strategy 挂钩：ENGINE_DEAD → EngineRelaunchStrategy、开关关闭 → None、UNHEALTHY → None - engine-restart 路由：restart/abort/400/409（并发、快照恢复中）/500（pull 失败且解冻） - /node-manager/stop 自杀语义：停引擎 + 延时 SIGTERM 自身（pod 重启） - 自杀冻结与裁决：freeze 清零复位 / 冻结期不计数 / 解冻恢复 / 冻结到期自动恢复 / generation 变化重置 / grace 期跳过 / 阈值触发 / **上报失败不冻结** / **未开 enable_engine_relaunch 不冻结** - 引擎死亡双信号源：PID 死亡事件（monitor health_check 返回死亡列表 + pid 去重）/ 心跳 ABNORMAL 上报（ep 去重 + 恢复清除 + 失败重试） - FaultReporter：回归纯 FT 状态上报 - 心跳状态源：has_abnormal_endpoints / abnormal_endpoint_ids / endpoints_generation / grace getter - daemon：restart_engine 只动引擎服务（KV/监控线程不动）/ 裁决（阈值、重置条件、冻结窗口与过期）/ PID 死亡上报去重与失败重试 / 冷启动不误报、曾 NORMAL 后异常上报 / 重拉分隔标记（计数 + banner 打印） - RegisterManager：master_dp_ip/role 持久化、get_restart_params - 配置：两侧新字段默认值与校验 **静态检查**：pylint / ruff 通过 **K8s e2e（infer195，A2 跨机 EP16 = 2 pod × 8 卡）**：已验证通过—— - 杀 vLLM 进程 → 双信号检测 → EngineRelaunchStrategy 协同两个 pod 一起重拉全部引擎 → 实例回 ACTIVE - 杀 NodeManager 进程 → 实例稳定 INACTIVE（无 ACTIVE↔INACTIVE 震荡）→ volcano podgroup 自动重启两个 pod（既有机制）→ 新实例组装恢复 - 冷启动加载期（30B 模型 > grace 120s）不再被误判死亡：新增「曾 NORMAL 门槛」——e2e 对比：修复前加载期多条误报触发重拉打断加载（恶性循环），修复后误报 0、实例平滑 ACTIVE e2e 定位并修复的问题： - engine-restart 路由快照恢复检查条件错误（非快照部署误拒 409） - EngineServer SIGKILL 后子进程孤儿残留（占旧 ZMQ 端口 → 重拉引擎握手 5 分钟超时）——进程组管理修复（start_new_session + killpg + 退出等待 + 僵尸收割） - 重拉与 FaultReporter 解耦：PID 级检测 + 心跳 ABNORMAL 双信号源，不依赖 FT 配置 - 部分节点失联防震荡：转 ACTIVE 加心跳新鲜度门槛 + 存活 NM 经既有 /node-manager/stop（自杀语义）协同退出（volcano 兜底） - daemon 职责收敛：engine 重启生命周期（stop/分隔标记/pull）下沉 EngineService.restart，daemon 回归 service 无关的编排者 ### 6. CheckList - [x] 代码注释完备 - [x] 正确记录维测日志（错误场景 error_window 防刷屏） See merge request: Ascend/MindIE-Motor!710	9 天前
test_event_pusher.py	支持引擎原生方式拉起：Coordinator 支持独立部署 Co-authored-by: tobking<wangjun292@huawei.com> # message auto-generated for no-merge-commit merge: !771 merge feat/coordinator-standalone-deploy-guide into master 支持引擎原生方式拉起：Coordinator 支持独立部署 Created-by: tobking Commit-by: tobking Merged-by: towncharlie Description: ## **1. 合入背景** 引擎改为由 NodeManager 原生拉起 vLLM/SGLang、Engine Server 下线后，Endpoint、配置及注册路径中仍残留不再使用的 mgmt_port 控制面字段。同时，已有原生 Prefill/Decode 引擎的用户需要一种不依赖 Controller、NodeManager 和 Kubernetes、仅部署 Coordinator 的 PD 调度方式。 本 PR 清理废弃字段，补齐 Coordinator 独立部署、实例管理和管理面安全能力，并根据检视意见加固实例注册一致性。 关联 ISSUE：#394。 ## **2. 修改内容** 1. **清理废弃控制面字段** - 从 Endpoint、配置、NodeManager 注册/心跳、Controller 组装及相关测试中删除 mgmt_port / mgmt_ports。 - Endpoint 不再吞掉未知参数；mgmt_port、拼写错误字段等直接校验失败。 - Controller、Coordinator、NodeManager 需同步升级，不支持混合版本。 2. **Coordinator 独立部署与注册 CLI** - 新增 python3 -m motor.coordinator.register，支持 set、add、del、list。 - 实例 ID 使用独立高位命名空间，由 role 与排序后的完整 endpoint 组派生；endpoint 输入顺序不影响 ID、job name 和 endpoint ID。 - CLI 提交前查询 GET /instances 检查已有冲突；按 endpoint 或 ID 删除时先获取真实注册身份，未知 ID 拒绝删除。 - /v1/models 返回空列表时判定为不健康；可通过 --no-health-check 显式跳过探测。 3. **实例管理一致性加固** - InstanceManager 在全部角色和状态池中保证实例 ID 全局唯一。 - SET 请求内重复 ID 返回 400；ADD 的同 ID 异身份冲突返回 409；DEL 校验角色、名称和 endpoint 身份。 - Scheduler 接受刷新后才更新管理面镜像，避免两侧状态不一致。 - endpoint 匹配改为顺序无关，并通过惰性导出消除 Coordinator models/domain 循环导入。 4. **Controller 最终一致性兜底** - ADD、DEL、PAUSE、RESUME 增量刷新失败时，合并排队一次全量 SET 对账。 - SET 失败不递归排队，也不更新已同步指纹。 5. **管理面安全与可观测性** - 新增 GET /instances，汇总 available、unavailable、paused 实例摘要。 - 管理面支持独立 API Key 文件；对外监听时可使用 X-Motor-Management-Key 保护管理接口。 - 独立部署主流程默认监听 127.0.0.1，跨主机、Docker、Kubernetes 监听和 API Key 配置移至附录。 6. **依赖约束** - 对齐 grpcio/grpcio-tools/protobuf 生成与运行时版本。 - FastAPI 最低版本提升至 0.100.0；Pydantic 限定为 >=2.0.0,<3.0.0。 ## **3. 资料变更** 涉及资料变更： - 新增 docs/zh/user_guide/deployment/standalone.md，并补充部署导航入口。 - 管理接口文档补充 GET /instances、管理 API Key 和同步升级要求。 - 配置参考、NodeManager、Controller、Coordinator 开发资料同步删除废弃字段并说明注册一致性机制。 ## **4. 接口变更** 涉及客户面可见接口变更： - Endpoint 注册协议删除 mgmt_port，未知字段严格拒绝；所有组件必须同步升级。 - Coordinator 管理面新增 GET /instances。 - Coordinator 管理面可配置独立 API Key，请求使用 X-Motor-Management-Key。 - 新增独立部署注册命令 python3 -m motor.coordinator.register。 ## **5. 测试结果** - Controller 事件兜底、注册 CLI、服务端实例冲突及删除校验联合回归：122 passed。 - Endpoint/Instance 严格字段校验：25 passed。 - 最终直接受影响测试复跑：49 passed。 - Ruff 静态检查及 git diff --check 通过。 - 本次改动集中在管理面、注册和资料路径，不涉及模型精度、显存或硬件性能变化。 ## **6. CheckList** [x] 代码注释完备 [x] 正确记录维测日志 [x] 是否有 UT 用例 [x] 若涉及多线程场景，考虑了并发场景，不存在死锁问题 See merge request: Ascend/MindIE-Motor!771	2 天前
test_instance.py	支持引擎原生方式拉起：Coordinator 支持独立部署 Co-authored-by: tobking<wangjun292@huawei.com> # message auto-generated for no-merge-commit merge: !771 merge feat/coordinator-standalone-deploy-guide into master 支持引擎原生方式拉起：Coordinator 支持独立部署 Created-by: tobking Commit-by: tobking Merged-by: towncharlie Description: ## **1. 合入背景** 引擎改为由 NodeManager 原生拉起 vLLM/SGLang、Engine Server 下线后，Endpoint、配置及注册路径中仍残留不再使用的 mgmt_port 控制面字段。同时，已有原生 Prefill/Decode 引擎的用户需要一种不依赖 Controller、NodeManager 和 Kubernetes、仅部署 Coordinator 的 PD 调度方式。 本 PR 清理废弃字段，补齐 Coordinator 独立部署、实例管理和管理面安全能力，并根据检视意见加固实例注册一致性。 关联 ISSUE：#394。 ## **2. 修改内容** 1. **清理废弃控制面字段** - 从 Endpoint、配置、NodeManager 注册/心跳、Controller 组装及相关测试中删除 mgmt_port / mgmt_ports。 - Endpoint 不再吞掉未知参数；mgmt_port、拼写错误字段等直接校验失败。 - Controller、Coordinator、NodeManager 需同步升级，不支持混合版本。 2. **Coordinator 独立部署与注册 CLI** - 新增 python3 -m motor.coordinator.register，支持 set、add、del、list。 - 实例 ID 使用独立高位命名空间，由 role 与排序后的完整 endpoint 组派生；endpoint 输入顺序不影响 ID、job name 和 endpoint ID。 - CLI 提交前查询 GET /instances 检查已有冲突；按 endpoint 或 ID 删除时先获取真实注册身份，未知 ID 拒绝删除。 - /v1/models 返回空列表时判定为不健康；可通过 --no-health-check 显式跳过探测。 3. **实例管理一致性加固** - InstanceManager 在全部角色和状态池中保证实例 ID 全局唯一。 - SET 请求内重复 ID 返回 400；ADD 的同 ID 异身份冲突返回 409；DEL 校验角色、名称和 endpoint 身份。 - Scheduler 接受刷新后才更新管理面镜像，避免两侧状态不一致。 - endpoint 匹配改为顺序无关，并通过惰性导出消除 Coordinator models/domain 循环导入。 4. **Controller 最终一致性兜底** - ADD、DEL、PAUSE、RESUME 增量刷新失败时，合并排队一次全量 SET 对账。 - SET 失败不递归排队，也不更新已同步指纹。 5. **管理面安全与可观测性** - 新增 GET /instances，汇总 available、unavailable、paused 实例摘要。 - 管理面支持独立 API Key 文件；对外监听时可使用 X-Motor-Management-Key 保护管理接口。 - 独立部署主流程默认监听 127.0.0.1，跨主机、Docker、Kubernetes 监听和 API Key 配置移至附录。 6. **依赖约束** - 对齐 grpcio/grpcio-tools/protobuf 生成与运行时版本。 - FastAPI 最低版本提升至 0.100.0；Pydantic 限定为 >=2.0.0,<3.0.0。 ## **3. 资料变更** 涉及资料变更： - 新增 docs/zh/user_guide/deployment/standalone.md，并补充部署导航入口。 - 管理接口文档补充 GET /instances、管理 API Key 和同步升级要求。 - 配置参考、NodeManager、Controller、Coordinator 开发资料同步删除废弃字段并说明注册一致性机制。 ## **4. 接口变更** 涉及客户面可见接口变更： - Endpoint 注册协议删除 mgmt_port，未知字段严格拒绝；所有组件必须同步升级。 - Coordinator 管理面新增 GET /instances。 - Coordinator 管理面可配置独立 API Key，请求使用 X-Motor-Management-Key。 - 新增独立部署注册命令 python3 -m motor.coordinator.register。 ## **5. 测试结果** - Controller 事件兜底、注册 CLI、服务端实例冲突及删除校验联合回归：122 passed。 - Endpoint/Instance 严格字段校验：25 passed。 - 最终直接受影响测试复跑：49 passed。 - Ruff 静态检查及 git diff --check 通过。 - 本次改动集中在管理面、注册和资料路径，不涉及模型精度、显存或硬件性能变化。 ## **6. CheckList** [x] 代码注释完备 [x] 正确记录维测日志 [x] 是否有 UT 用例 [x] 若涉及多线程场景，考虑了并发场景，不存在死锁问题 See merge request: Ascend/MindIE-Motor!771	2 天前
test_instance_assembler.py	支持引擎原生方式拉起：Coordinator 支持独立部署 Co-authored-by: tobking<wangjun292@huawei.com> # message auto-generated for no-merge-commit merge: !771 merge feat/coordinator-standalone-deploy-guide into master 支持引擎原生方式拉起：Coordinator 支持独立部署 Created-by: tobking Commit-by: tobking Merged-by: towncharlie Description: ## **1. 合入背景** 引擎改为由 NodeManager 原生拉起 vLLM/SGLang、Engine Server 下线后，Endpoint、配置及注册路径中仍残留不再使用的 mgmt_port 控制面字段。同时，已有原生 Prefill/Decode 引擎的用户需要一种不依赖 Controller、NodeManager 和 Kubernetes、仅部署 Coordinator 的 PD 调度方式。 本 PR 清理废弃字段，补齐 Coordinator 独立部署、实例管理和管理面安全能力，并根据检视意见加固实例注册一致性。 关联 ISSUE：#394。 ## **2. 修改内容** 1. **清理废弃控制面字段** - 从 Endpoint、配置、NodeManager 注册/心跳、Controller 组装及相关测试中删除 mgmt_port / mgmt_ports。 - Endpoint 不再吞掉未知参数；mgmt_port、拼写错误字段等直接校验失败。 - Controller、Coordinator、NodeManager 需同步升级，不支持混合版本。 2. **Coordinator 独立部署与注册 CLI** - 新增 python3 -m motor.coordinator.register，支持 set、add、del、list。 - 实例 ID 使用独立高位命名空间，由 role 与排序后的完整 endpoint 组派生；endpoint 输入顺序不影响 ID、job name 和 endpoint ID。 - CLI 提交前查询 GET /instances 检查已有冲突；按 endpoint 或 ID 删除时先获取真实注册身份，未知 ID 拒绝删除。 - /v1/models 返回空列表时判定为不健康；可通过 --no-health-check 显式跳过探测。 3. **实例管理一致性加固** - InstanceManager 在全部角色和状态池中保证实例 ID 全局唯一。 - SET 请求内重复 ID 返回 400；ADD 的同 ID 异身份冲突返回 409；DEL 校验角色、名称和 endpoint 身份。 - Scheduler 接受刷新后才更新管理面镜像，避免两侧状态不一致。 - endpoint 匹配改为顺序无关，并通过惰性导出消除 Coordinator models/domain 循环导入。 4. **Controller 最终一致性兜底** - ADD、DEL、PAUSE、RESUME 增量刷新失败时，合并排队一次全量 SET 对账。 - SET 失败不递归排队，也不更新已同步指纹。 5. **管理面安全与可观测性** - 新增 GET /instances，汇总 available、unavailable、paused 实例摘要。 - 管理面支持独立 API Key 文件；对外监听时可使用 X-Motor-Management-Key 保护管理接口。 - 独立部署主流程默认监听 127.0.0.1，跨主机、Docker、Kubernetes 监听和 API Key 配置移至附录。 6. **依赖约束** - 对齐 grpcio/grpcio-tools/protobuf 生成与运行时版本。 - FastAPI 最低版本提升至 0.100.0；Pydantic 限定为 >=2.0.0,<3.0.0。 ## **3. 资料变更** 涉及资料变更： - 新增 docs/zh/user_guide/deployment/standalone.md，并补充部署导航入口。 - 管理接口文档补充 GET /instances、管理 API Key 和同步升级要求。 - 配置参考、NodeManager、Controller、Coordinator 开发资料同步删除废弃字段并说明注册一致性机制。 ## **4. 接口变更** 涉及客户面可见接口变更： - Endpoint 注册协议删除 mgmt_port，未知字段严格拒绝；所有组件必须同步升级。 - Coordinator 管理面新增 GET /instances。 - Coordinator 管理面可配置独立 API Key，请求使用 X-Motor-Management-Key。 - 新增独立部署注册命令 python3 -m motor.coordinator.register。 ## **5. 测试结果** - Controller 事件兜底、注册 CLI、服务端实例冲突及删除校验联合回归：122 passed。 - Endpoint/Instance 严格字段校验：25 passed。 - 最终直接受影响测试复跑：49 passed。 - Ruff 静态检查及 git diff --check 通过。 - 本次改动集中在管理面、注册和资料路径，不涉及模型精度、显存或硬件性能变化。 ## **6. CheckList** [x] 代码注释完备 [x] 正确记录维测日志 [x] 是否有 UT 用例 [x] 若涉及多线程场景，考虑了并发场景，不存在死锁问题 See merge request: Ascend/MindIE-Motor!771	2 天前
test_instance_manager.py	支持引擎原生方式拉起：Coordinator 支持独立部署 Co-authored-by: tobking<wangjun292@huawei.com> # message auto-generated for no-merge-commit merge: !771 merge feat/coordinator-standalone-deploy-guide into master 支持引擎原生方式拉起：Coordinator 支持独立部署 Created-by: tobking Commit-by: tobking Merged-by: towncharlie Description: ## **1. 合入背景** 引擎改为由 NodeManager 原生拉起 vLLM/SGLang、Engine Server 下线后，Endpoint、配置及注册路径中仍残留不再使用的 mgmt_port 控制面字段。同时，已有原生 Prefill/Decode 引擎的用户需要一种不依赖 Controller、NodeManager 和 Kubernetes、仅部署 Coordinator 的 PD 调度方式。 本 PR 清理废弃字段，补齐 Coordinator 独立部署、实例管理和管理面安全能力，并根据检视意见加固实例注册一致性。 关联 ISSUE：#394。 ## **2. 修改内容** 1. **清理废弃控制面字段** - 从 Endpoint、配置、NodeManager 注册/心跳、Controller 组装及相关测试中删除 mgmt_port / mgmt_ports。 - Endpoint 不再吞掉未知参数；mgmt_port、拼写错误字段等直接校验失败。 - Controller、Coordinator、NodeManager 需同步升级，不支持混合版本。 2. **Coordinator 独立部署与注册 CLI** - 新增 python3 -m motor.coordinator.register，支持 set、add、del、list。 - 实例 ID 使用独立高位命名空间，由 role 与排序后的完整 endpoint 组派生；endpoint 输入顺序不影响 ID、job name 和 endpoint ID。 - CLI 提交前查询 GET /instances 检查已有冲突；按 endpoint 或 ID 删除时先获取真实注册身份，未知 ID 拒绝删除。 - /v1/models 返回空列表时判定为不健康；可通过 --no-health-check 显式跳过探测。 3. **实例管理一致性加固** - InstanceManager 在全部角色和状态池中保证实例 ID 全局唯一。 - SET 请求内重复 ID 返回 400；ADD 的同 ID 异身份冲突返回 409；DEL 校验角色、名称和 endpoint 身份。 - Scheduler 接受刷新后才更新管理面镜像，避免两侧状态不一致。 - endpoint 匹配改为顺序无关，并通过惰性导出消除 Coordinator models/domain 循环导入。 4. **Controller 最终一致性兜底** - ADD、DEL、PAUSE、RESUME 增量刷新失败时，合并排队一次全量 SET 对账。 - SET 失败不递归排队，也不更新已同步指纹。 5. **管理面安全与可观测性** - 新增 GET /instances，汇总 available、unavailable、paused 实例摘要。 - 管理面支持独立 API Key 文件；对外监听时可使用 X-Motor-Management-Key 保护管理接口。 - 独立部署主流程默认监听 127.0.0.1，跨主机、Docker、Kubernetes 监听和 API Key 配置移至附录。 6. **依赖约束** - 对齐 grpcio/grpcio-tools/protobuf 生成与运行时版本。 - FastAPI 最低版本提升至 0.100.0；Pydantic 限定为 >=2.0.0,<3.0.0。 ## **3. 资料变更** 涉及资料变更： - 新增 docs/zh/user_guide/deployment/standalone.md，并补充部署导航入口。 - 管理接口文档补充 GET /instances、管理 API Key 和同步升级要求。 - 配置参考、NodeManager、Controller、Coordinator 开发资料同步删除废弃字段并说明注册一致性机制。 ## **4. 接口变更** 涉及客户面可见接口变更： - Endpoint 注册协议删除 mgmt_port，未知字段严格拒绝；所有组件必须同步升级。 - Coordinator 管理面新增 GET /instances。 - Coordinator 管理面可配置独立 API Key，请求使用 X-Motor-Management-Key。 - 新增独立部署注册命令 python3 -m motor.coordinator.register。 ## **5. 测试结果** - Controller 事件兜底、注册 CLI、服务端实例冲突及删除校验联合回归：122 passed。 - Endpoint/Instance 严格字段校验：25 passed。 - 最终直接受影响测试复跑：49 passed。 - Ruff 静态检查及 git diff --check 通过。 - 本次改动集中在管理面、注册和资料路径，不涉及模型精度、显存或硬件性能变化。 ## **6. CheckList** [x] 代码注释完备 [x] 正确记录维测日志 [x] 是否有 UT 用例 [x] 若涉及多线程场景，考虑了并发场景，不存在死锁问题 See merge request: Ascend/MindIE-Motor!771	2 天前
test_recovery_service.py	[feature]增加告警清除逻辑 Co-authored-by: hxy<huxinyi9@huawei.com> # message auto-generated for no-merge-commit merge: !598 merge feat/hybrid-precision-detection into master [feature]增加告警清除逻辑 Created-by: hu-xinyi_555 Commit-by: hxy Merged-by: towncharlie Description: ## **1. 合入背景** 可见https://gitcode.com/Ascend/MindIE-Motor/issues/359 精度检测特性（前序合入 61b0475 [feature]支持混布场景的精度异常检测）已具备 **告警产生** 与 **auto-recovery 实例终止** 能力，但缺少完整的 **告警清除（CLEAR）闭环**： - auto-recovery 终止 P/D 实例后，OM 侧精度告警仍可能残留； - CCAE 手动下发 precision control 终止实例后，未同步清除对应 PD Group 告警； - 未开启 auto-recovery 时，实例恢复后无法通过连续正常检测自动清除活动告警； - Coordinator Scheduler 侧 alarm_active 状态无统一清理入口，影响后续同 PD Group 重复告警。 ## **2. 修改内容** 详细设计见：[docs/zh/design/fault_tolerance/precision_detection.md](../../pymotor/MindIE-PyMotor_8989/docs/zh/design/fault_tolerance/precision_detection.md)（告警清除章节） ### 2.1 三条清除路径 | 路径 | 触发方 | 行为 | |------|--------|------| | **auto-recovery 清除** | Controller | 精度 ALARM 触发终止 P/D 全部成功后，上报 CLEAR 至 OM，并通知 Coordinator 清理 Scheduler 活动状态 | | **CCAE 手动清除** | CCAE Reporter → Controller | 终止 P/D 时携带 precision_alarm_clear=true，复用统一恢复入口清除 OM 告警 + 通知 Coordinator | | **连续正常清除** | Coordinator | 活动告警下连续 precision_clear_threshold（默认 10）次有效正常检测后，上报 CLEAR | ### 2.2 组件交互（实现要点） 1. **Controller recovery_service.py（新增统一入口）** - complete_precision_pd_group_recovery()：可选终止 P/D → 从 AlarmStore 查找活动精度告警 → 深拷贝原 Alarm 并 clear() 上报 OM → 调用 CoordinatorApiClient.notify_precision_alarm_cleared() 清理 Scheduler 状态 - terminate_pd_group() / is_precision_raise_alarm() 等辅助函数供 API 层复用 2. **Controller alarm_store.py** - 新增 _active_precision_alarms 索引与 find_active_precision_alarm(p_id, d_id)，按 PD Group 追踪活动精度告警及其 moi 3. **Controller controller_api.py** - 精度 auto-recovery 成功后走 complete_precision_pd_group_recovery，响应携带 precision_alarm_cleared / precision_alarm_cleared_by_auto_recovery - POST /controller/terminate_instance 支持 precision_alarm_clear=true，CCAE 手动清除走同一恢复入口 4. **Coordinator Scheduler（scheduler.py + runtime）** - 新增 alarm_active、clear_probing、clear_tokens 等 per-PD-Group 状态 - record_precision_result() 在活动告警下累计连续正常样本，达 clear_threshold 触发 clear action - finish_precision_action(action_type=clear|raise) 提交 action 结果；auto-recovery 已清除时直接删除整组状态 - 新增 ZMQ 协议与 client/server 透传 finish_precision_action / record_precision_result(clear_threshold=...) 5. **Coordinator PrecisionReporter + PrecisionAlarm** - Reporter 支持 raise / clear 双 action 编排，clear_threshold_hit 时异步触发 CLEAR 上报 - PrecisionAlarm.execute(action=clear) 构造 build_precision_issue_clear_alarm() 并上报 Controller；CLEAR 必须使用与产生告警相同的 moi 6. **Coordinator Management API（新增）** - POST /precision/alarm_cleared：Controller 通知 Coordinator 删除 Scheduler 活动告警状态（Mgmt 进程 → Scheduler） 7. **CCAE Reporter + MotorBackend** - precision control 终止成功后调用带 precision_alarm_clear=true 的 group terminate - 新增 precision task 上报窗口与 controlCode 抑制逻辑 8. **公共层** - 新增 motor/common/alarm/deserialize.py：告警反序列化 - precision_issue_alarm.py：新增 build_precision_issue_clear_alarm() - coordinator.py：新增 precision_clear_threshold 配置项 ### 2.3 时序（auto-recovery 清除） mermaid sequenceDiagram participant CR as Coordinator PrecisionAlarm participant CT as Controller participant OM as OM/CCAE participant SCH as Coordinator Scheduler CR->>CT: POST report_alarms (ALARM) CT->>CT: terminate P/D instances CT->>OM: report ALARM + CLEAR (same moi) CT->>SCH: POST /precision/alarm_cleared SCH->>SCH: clear alarm_active state CT-->>CR: precision_alarm_cleared_by_auto_recovery=true --- ## **3. 资料变更** **涉及**，修改如下： | 文件 | 变更说明 | |------|----------| | docs/zh/design/fault_tolerance/precision_detection.md | 补充告警清除设计：三条清除路径、moi 一致性约束、Scheduler 状态清理、CCAE 手动清除时序 | | docs/zh/user_guide/features/precision_detection.md | 补充 precision_clear_threshold 配置说明 | | docs/zh/user_guide/api/observability_interface.md | 补充 CCAE precision control 调用 /controller/terminate_instance 时 precision_alarm_clear 字段说明 | --- ## **4. 接口变更** **涉及**，均为客户面/跨组件可见接口： | 接口 | 变更类型 | 说明 | |------|----------|------| | POST /controller/terminate_instance | **请求体扩展** | 新增可选字段 precision_alarm_clear: bool（默认 false）。为 true 时按 PD Group 终止 P/D 并清除精度告警；响应 data 新增 precision_alarm_cleared、scheduler_state_cleared、moi | | POST /controller/report_alarms（精度 ALARM 响应） | **响应扩展** | auto-recovery 成功后 data 新增 precision_alarm_cleared、precision_alarm_cleared_by_auto_recovery、scheduler_state_cleared | | POST /precision/alarm_cleared（Coordinator Mgmt） | **新增** | Controller → Coordinator，请求体 {p_instance_id, d_instance_id}，清除 Scheduler 侧活动精度告警状态 | | Coordinator 配置 | **新增字段** | precision_detection_config.precision_clear_threshold（默认 10） | | CCAE precision control → MotorBackend | **行为变更** | 终止实例时携带 precision_alarm_clear=true | --- ## **5. 测试结果**  --- ## **6. CheckList** > PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x] [x] 代码注释完备 [x] 正确记录维测日志 [x] 是否有UT用例 [x] 若涉及多线程场景，考虑了并发场景，不存在死锁问题 See merge request: Ascend/MindIE-Motor!598	30 天前