2026-09-16
新增 Tinker 网关示例启动器、SDK 客户端与网关测试套件
值得精读，但建议带着「契约而非实现」的视角读三处：examples/multi_lora/serve_qwen3_30b_a3b_tinker.py（单节点 8 卡的资源切分与参数分组，是复刻其它模型的模板）、miles/tinker/arguments.py（Tinker 能力边界被写死在这里，扩模型族必看）、tests/fast/tinker/core/test_service.py 与 harness.py（checkpoint 版本化、租户隔离、失败隔离的对外承诺都在这些断言里）。值得关注的设计决策有：把上游 tinker-cookbook 当作 wire contract 的验收标准；用 test_layering.py 以导入图约束 core/runtime/server 分层；sampler 保存走不可变目录并支持 pinned version 解析。注意三点：本 PR 无逐行人工评审（批准来自共同作者），如需信任请自行核对最终 tree；run_id 每次调用生成导致重启后旧 checkpoint 路径不可达，长跑场景务必显式固定；IO 失败终止整个网关的策略是否可接受，建议结合业务 SLA 单独评估。
新增 Tinker 网关运行时与 serve 入口
值得精读，是本轮 multi-LoRA v2 栈中最靠近「真实执行链路」的一篇。阅读顺序建议：先看 `miles/tinker/runtime.py` 的 `_pad_to_dp_multiple` / `_build_train_data` / `_execute_batch` 三件套，理解 datum 契约与 `sample_index` 重组规则；再看 `serve_tinker.py` 的 `serve()`，重点体会任务监督（`asyncio.wait(FIRST_COMPLETED)`）、dispose 顺序与 `GatewayConfig` 的推导；最后扫 `miles/utils/arguments.py` 的 entry 维度，确认对既有 train 入口没有隐性行为回归。需要重点关注的设计决策有四条：训练命令经 object store 传递并让 worker 自行按 DP 切分、用零掩码副本做 DP 补齐、显式失败透传与未知失败终止网关的失败分类边界、以及 `NaN` / `MASK_LOGPROB` 的 wire 约定。建议精读时反向确认 `TrainerCell.execute(kill_on_failure=True)` 与 Tinker 服务错误分类是否已完全对齐，并确认 `_build_train_data` 依赖首条 datum 探测可选键的假设在真实 SDK 用法下是否成立。
新增 Tinker 网关协议层与每模型调度器，纯进程内无 runtime 依赖
值得精读，尤其是三处：core/service.py 的失败分级与 _close_model 的 slot quarantine 语义、core/scheduler.py 的“arrival 选 seed + pack_key 打包 + optim barrier 合并”三件套、以及 review 线程本身——它展示了一个很典型的踩坑模式：给外部 SDK 写服务端时，request_id 必须由 SDK 的 (session/seq) 幂等键派生，自己随机生成的 id 在客户端重试下必然重复占资源。阅读时建议对照 #2845 的 runtime 接线和 #2849 的测试，确认 review 中“Non-blocking”的几条（完整 outcome map 校验、loss_fn_config_v2 优先级）在最终实现里是否真的闭环。
新增 LoRA 适配器不可变磁盘快照发布路径
值得精读。三个最值得关注的设计点：一是 joyliu-q 发现的生成器惰性求值 bug 及其修复方式（把循环变量改为函数形参绑定，而非依赖 `itertools.chain` 的求值时机），这是 Python 里极易复现的陷阱；二是 `materialize_adapter` 的集合通信契约——所有 rank 必须走同一路径、只有 writer 产出数据；三是 staged-push 被整体删除后，失败与重试语义转移到了哪里（#2845 的 runtime 与 SGLang on-demand loading），以及删除 `slot_lora_name` 后全仓引用是否已清理。如果所在团队还在用旧的多 LoRA push 行为，需要先确认配置不再显式设置 `update_weights`/`model_path`。
新增多 LoRA 单槽位检查点，含 Adam 状态与原子版本发布
值得精读，但读法有侧重：
1. **优先看 `miles/backends/training_utils/checkpoint_io.py`**：`publish_dir()` 里「rename 到 `_version_*` → 建相对符号链接 → `os.replace` 顶替公共路径」三步是整个栈崩溃安全性的基石，也解释了为什么必须保留旧版本目录；同时注意 `make_tmp_dir` 的三种拒绝路径（non-overwrite、legacy 目录、崩溃残留）。
2. **再看 `miles/backends/megatron_utils/lora/checkpoint.py`**：`_canonicalize_slot_keys` 与 `load_optimizer` 两条分支（`load_sharded_state` vs `reload_masters`）是「槽位无关 + 槽位本地」两个设计意图的落点，也是评审意见 1/2 的修复位置。
3. **值得追踪的遗留项**：IO 失败隔离 TODO、`_version_*` 回收策略、rank 局部失败的集体错误广播、docstring 与 PR body 关于拓扑约束的口径统一，以及在 TP/PP/EP/MoE 布局下的恢复验证。
4. **可借鉴的设计决策**：「先校验后赋值」的两段式加载、把跨槽不变量固化成 key 归一化、用负向对照（master 舍入到 BF16 / 纯权重重启必须失败）证明测试确实在测正确的东西——这三点在同类持久化改动中都值得复用。
新增 Tinker 每批损失选择、5 种目标函数与 per-datum 输出
建议精读。最值得关注的三处设计决策：(1) `tinker_losses.py` 的「服务端只做 raw sum、归一化交给客户端」模型，以及 `loss_normalizer` 与执行 batch size 解耦的理由；(2) `_sum_loss_and_outputs` 在“无监督 token 的 microbatch”上用 `logits.sum(dtype=torch.float32) * 0` 保持计算图连通的 NaN 防御写法，以及 per-datum 输出 detach 到 CPU 以规避 recompute 重复追加的设计；(3) `forward_only` 复用同一条 loss pass 而不是另起实现，这是消除双实现漂移的关键取舍。阅读时建议同时对照 review 中“零掩码测试无法验证目标函数”与“per_datum 命名空间污染”两条评论，它们分别解释了最终测试矩阵与 `loss.py` 守卫的由来；并把 nanjiangwill 关于 O(KN) 全池同步的评论作为独立待办跟踪。
新增多 LoRA 槽位执行器与每租户独立优化器
建议精读。这是整套 multi-LoRA v2 的地基（1/7），后续 6 个 PR 的损失选择、槽位 checkpoint、快照发布和网关 runtime 都建立在它的命令面与优化器所有权模型上，改动虽然只有 +453/-352，但触及所有 Megatron 训练路径。推荐阅读顺序：先看 megatron_utils/model.py 的抽函数是否严格等价（尤其被丢掉的 no_sync_func 断言），再看 lora/model.py 的 4 个槽位操作函数，最后细读 lora/optimizer.py 的 SlotOptimizer 与 step_slot_optimizers。需要重点确认三个设计决策：(1) 是否接受“pre-collective 失败 = cell 失败”的粗粒度恢复；(2) nonfinite 跳过时直接丢弃梯度是否符合网关的重放语义；(3) 每租户独立优化器的显存增长是否在容量预算内。同时留意 review 点名但未补齐的双槽位/两 rank 回归测试，以及 body 中“无新增测试文件”与实际 diff 的口径差异。
删除 multi-LoRA v1 实现，仅保留槽位原语
值得精读，但重点不是 5000 行删除本身，而是删除与保留的边界如何划定：建议先读 `miles/backends/megatron_utils/lora/slots.py`（保留原语的新家，含跨 rank shard 写入者选举与 expert-axis-safe 的 rank 切分）与 `miles/utils/multi_lora.py`（收缩后的公共工具面），再回看 `miles/ray/multi_lora/registry.py`、`backend.py` 被删掉的注册期校验与状态机，逐条确认 v2（#2844 的 `miles/tinker/core/scheduler.py`/`service.py`、#2840 的 slot actor）是否有等价实现。三个最值得关注的设计决策：一是槽位原语与控制面彻底解耦（docstring 里显式声明不掺控制面/数据面逻辑）；二是注册期 fail-fast 校验（data 路径、reward 配置、batch 形状整除）整体消失后由谁承担；三是 per-slot LR 调度与 adapter YAML 契约被删，v2 是否真的不再需要 per-adapter 调度。阅读时注意 head 只有一个 squash commit，MoE 专家路径的恢复要直接核对 head_sha 958e1ca 的文件内容。
