| 文件 | 最后提交记录 | 最后更新时间 |
|---|---|---|
[bugfix] 禁止打出缺负载 workload_shm.so 的 wheel，默认同时打包 kv-conductor+workload_shm.so Co-authored-by: LinWei100<linwei100@huawei.com> # message auto-generated for no-merge-commit merge: !902 merge bugfix/workload-shm-wheel-required into master [bugfix] 禁止打出缺负载 workload_shm.so 的 wheel，默认同时打包 kv-conductor+workload_shm.so Created-by: LinWei100 Commit-by: LinWei100 Merged-by: tobking Description: ## **1. 合入背景** PR822（#521）合入后 Coordinator 负载账本只加载 libmindie_workload_shm.so，无 Python 回退。build.sh 在无 cargo 时仍 warning 并打出缺库 wheel，装进镜像后启动报 NativeWorkloadShmUnavailable。官方 bash build.sh 在有 cargo 时应把 kv-conductor 一并打进同一 wheel；缺 SHM 库必须拒绝出包。\ Fixes #570 ## **2. 修改内容** 1. 新增 scripts/ensure_rust.sh：探测 PATH / $HOME/.cargo；**显式 CARGO_HOME 只认该前缀**（不回退 /root/.cargo，避免 CI-as-root 负向 UT 误命中宿主机工具链）。必须 cargo --version 成功才算可用。缺失且确实需要编译时 rustup（SKIP_RUST_INSTALL=1 关闭）。编 kv-conductor 前探测 libzmq / g++（SKIP_CXX_INSTALL=1 关闭自动装 g++）；conductor 自己的 cargo build 失败返回 1，不 exit 1。 2. 修改 build.sh：默认**已有** lib/libmindie_workload_shm.so / bin/kv-conductor 则跳过对应 cargo（也不 rustup）；**缺文件才编译**。显式 SKIP_WORKLOAD_SHM_BUILD=0 / SKIP_KV_CONDUCTOR_BUILD=0 强制重编。先编 workload-shm（缺库 refusing to emit），再尝试 kv-conductor；仅 conductor 特有原因 WARNING 跳过（缺 libzmq / g++ / zmq 链接失败）。pip wheel 可用 PIP_INDEX_URL 换源，隔离失败则 --no-build-isolation 重试。 3. 新增 motor/coordinator/workload_shm_rs/wheel_gate.py：校验 .so；编出 conductor 时再校验二进制。 4. 修改 setup.py：官方打包必须带 SHM 库；已有 bin/kv-conductor 时打进 wheel。 5. 修改 docker/mindie-motor-vllm/master/Dockerfile：装 gcc/g++/libzmq；默认 SKIP_WORKLOAD_SHM_BUILD=0 与 SKIP_KV_CONDUCTOR_BUILD=0（镜像内按目标 ABI 重编，避免打进宿主机 .so）；python -P 断言 site-packages 内的 .so 与 kv-conductor，再删除 rustup。 6. 更新 AGENTS.md、motor/kv_conductor/README.md、独立部署 / KV 亲和 / 镜像制作 / Coordinator / 设计文档 §8.5、docker OVERVIEW。 7. UT：tests/coordinator/scheduler/test_ensure_rust.py（含 CARGO_HOME 隔离、motor_var_is_explicit_zero）、tests/coordinator/scheduler/test_workload_shm_wheel_gate.py。 ## **3. 资料变更** 涉及。更新 AGENTS.md、独立部署、KV Cache 亲和构建说明、镜像制作、Coordinator 组件说明、调度热路径设计文档 §8.5、docker OVERVIEW。 ## **4. 接口变更** 不涉及客户面 API。构建行为变化：无 libmindie_workload_shm.so 时 build.sh 失败并删除不完整 wheel。默认有产物则跳过 cargo；强制重编必须显式 SKIP_*=0（unset 不等于 0）。缺 libzmq 时自动跳过 kv-conductor，不 apt 安装 libzmq。官方镜像默认两个 SKIP 为 0。 ## **5. 测试结果** - bash tests/run_tests.sh --serial tests/coordinator/scheduler/test_ensure_rust.py tests/coordinator/scheduler/test_workload_shm_wheel_gate.py：24 passed。 ### 5.1 自验证环境（192.168.9.195，2026-09-07） | 项 | 事实 | |---|---| | 主机 | aarch64 Linux（hostname master） | | 工作目录 | /mnt/share/l00957062/pr902-verify | | 被测源码 | fork 分支 bugfix/workload-shm-wheel-required，d6a7a53a（[bugfix] 打包同时打入 kv-conductor，缺 SHM 库禁止出包） | | 构建/运行镜像 | mindie-motor-vllm:dev-nightly-202607090701-800I-A2-py3.11-Ubuntu24.04-lts-aarch64（容器内 Ubuntu 22.04.5 / Python 3.12.13 / gcc 11.4.0；镜像原生无 rustc/cargo、无 zmq.h / pkg-config） | | 宿主机约束 | 系统 Python 3.10，setup.py 要求 >=3.11，**禁止在宿主机直接 bash build.sh**，一律进上述镜像 | 对照目录：/mnt/share/l00957062/master-tuna-verify（上游 master f009b3a9，无本 PR 的 ensure_rust.sh / wheel_gate / refusing to emit）。 ### 5.2 步骤一：准备 PR902 源码与容器 1. 在共享盘克隆 PR 分支（不要用宿主机 Python 打包）。 2. docker run --rm --network=host --entrypoint bash，挂载 /mnt/share/l00957062/pr902-verify 为 /work。 3. 容器内 export PATH=/usr/local/python3.12.13/bin:$PATH。 4. 镜像无 libzmq：试验中 apt-get install -y --no-install-recommends libzmq3-dev pkg-config（jammy libzmq 4.3.4-2）。**不**把 apt 装 zmq 写进 build.sh；官方 Motor Dockerfile 才预装这些包。 ### 5.3 步骤二：官方 bash build.sh 编两个 Rust crate（正向） 容器内执行官方脚本（未 SKIP conductor）： ``text Installing Rust toolchain via rustup (needed to compile libmindie_workload_shm.so)... RUSTUP_INIT_URL=https://rsproxy.cn/rustup-init.sh cargo ready: /root/.cargo/bin/cargo (cargo 1.98.1 (797e8a9bc 2026-08-05)) Building kv-conductor from source (cargo build --release)... Finished release profile [optimized] target(s) in 9m 18s kv-conductor binary ready (cargo-built): ./motor/kv_conductor/bin/kv-conductor === workload-shm === Building workload-shm from source (cargo build --release)... Finished release profile [optimized] target(s) in 0.11s workload-shm library ready (cargo-built): ./motor/coordinator/workload_shm_rs/lib/libmindie_workload_shm.so ` 宿主机 file 验收： text libmindie_workload_shm.so: ELF 64-bit LSB shared object, ARM aarch64, ... 414K kv-conductor: ELF 64-bit LSB pie executable, ARM aarch64, ... 6.1M 结论：无预置 rust 时，本 PR 的 ensure_rust.sh 能 rustup 装上可用 cargo，并编出两个 native 产物。 ### 5.4 步骤三：官方 tuna pip wheel 与对照（同一镜像） 官方 build.sh 写死 -i https://pypi.tuna.tsinghua.edu.cn/simple。Rust 编完后 isolation 拉 setuptools 失败： text Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple Collecting setuptools>=40.8.0 ERROR: HTTP error 403 while getting .../setuptools-84.0.0-py3-none-any.whl ERROR: Failed to build 'file:///work' when installing build dependencies **对照（无 PR902 的上游 master f009b3a9，同一镜像、同一官方 bash build.sh、不改索引、不加 --no-build-isolation）**： | 项 | PR902 d6a7a53a | master f009b3a9 | |---|---|---| | cargo / rustup | 自动安装，编出 .so + kv-conductor | 无 cargo，仅 WARNING 后继续 pip wheel（这正是本 PR 要修的空心包路径） | | tuna isolation 拉 setuptools | HTTP 403 | **同一 403，同一 setuptools-84.0.0 URL** | | dist/motor-*.whl | 官方 tuna 路径未写出 | 官方 tuna 路径未写出 | 结论：tuna 403 是该机访问清华 wheel 被拒 + build.sh 写死索引，**不是 902 引入的**。master 对照日志：/mnt/share/l00957062/master-tuna-build.log。 随后用镜像已有 setuptools 做 --no-build-isolation 打出 wheel（native 已由步骤二编好）： text /mnt/share/l00957062/dist/motor-3.1.0-py3-none-any.whl 3.7M motor/coordinator/workload_shm_rs/lib/libmindie_workload_shm.so 423848 motor/kv_conductor/bin/kv-conductor 6335184 验收命令：unzip -l dist/motor-*.whl | grep -E 'kv-conductor|libmindie_workload_shm.so'，wheel_gate 通过。 ### 5.5 步骤四：负向 — 缺 SHM 库禁止出包 新容器去掉 lib/*.so 与 bin/kv-conductor，设 SKIP_RUST_INSTALL=1 SKIP_KV_CONDUCTOR_BUILD=1 再跑 bash build.sh： text [ERROR] refusing to emit dist/motor-*.whl: cargo is required to compile libmindie_workload_shm.so. Coordinator cannot start without this library (no Python ledger fallback). exit 1，dist/ 无 wheel。master 对照不会拒绝出包（只 WARNING），这是 902 相对 master 的行为差。 ### 5.6 步骤五：安装该 wheel 后拉起 Coordinator（无 SHM 报错） 独立容器 pr902-coord-test（--network=host，不挂源码树，避免 import 走源码）： text python3 -m pip install --force-reinstall --no-deps /whl/motor-3.1.0-py3-none-any.whl # Successfully installed motor-3.1.0 # MOTOR_FILE .../site-packages/motor/__init__.py # SHM_LIB .../site-packages/motor/coordinator/workload_shm_rs/lib/libmindie_workload_shm.so True 423848 # KV_BIN .../site-packages/motor/kv_conductor/bin/kv-conductor True 6335184 python3 -m motor.coordinator.main 启动日志（默认配置，无 NativeWorkloadShmUnavailable / 无 Traceback / 无 Startup failed）： text (MainProcess pid=1) INFO ... [__main__][main.py:28] Starting Motor Coordinator Daemon... (MainProcess pid=1) INFO ... [daemon][coordinator_daemon.py:196] MgmtProcess started successfully (MainProcess pid=1) INFO ... [daemon][coordinator_daemon.py:196] InferenceWorkers started successfully (MgmtServer pid=90) INFO ... [scheduler][scheduler_server.py:816] Workload shared memory enabled: mindie_workload_90 (MgmtServer pid=90) INFO ... [scheduler][scheduler_server.py:832] Control plane started, frontend: ipc:///tmp/scheduler_frontend INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:1026 INFO: Uvicorn running on http://127.0.0.1:1027 进程保持运行（验证时 docker ps：Up 35 minutes）。grep NativeWorkloadShm / Traceback / Startup failed 均为空。 只读探活（默认配置无完整集群，mgmt/infer 的 /health 路由本身不存在，返回 404 JSON，**不是进程崩溃**）： text obs : GET http://127.0.0.1:1027/health -> 200 {"status":"ok",...} mgmt : GET http://127.0.0.1:1026/health -> 404 {"detail":"Not Found"} infer: GET http://127.0.0.1:1025/health -> 404 {"detail":"Not Found"} 与复现问题对照：PR822 后「无 .so 的 wheel」会在创建负载 SHM 时直接 NativeWorkloadShmUnavailable 退出。本 wheel 走到 Workload shared memory enabled: mindie_workload_90，证明 site-packages 里的 Rust .so 已加载。 ### 5.7 自验证结论 | 场景 | 结果 | |---|---| | 空镜像 rustup + 编 SHM / kv-conductor | 通过 | | 打进 wheel 并 wheel_gate | 通过（tuna isolation 403 后 --no-build-isolation） | | 缺 .so 拒绝出包 | 通过 | | 安装后 python3 -m motor.coordinator.main | 通过：SHM 创建成功，进程存活，无 SHM 缺失报错 | | master 官方 tuna build.sh` | 同样 403，打不出 wheel；且无 cargo 时不会拒绝空心包 | ## **6. CheckList** [x] 代码注释完备 [x] 正确记录维测日志 [x] 是否有UT用例 [x] 若涉及多线程场景，考虑了并发场景，不存在死锁问题 See merge request: Ascend/MindIE-Motor!902 | 22 天前 | |
支持引擎原生方式拉起：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 | 1 个月前 |
| 文件 | 最后提交记录 | 最后更新时间 |
|---|---|---|
| 22 天前 | ||
| 1 个月前 |