执行摘要

该 PR 是对 LoRA 训练与托管指南的一次全面重写，修正了旧文档与实现脱节的多个问题：将 LoRA 从“仅 colocate”的描述更新为覆盖 colocated 与 disaggregated 两种拓扑，显式区分 Megatron-Bridge 与原生/raw 两条实现路径，补充多 LoRA 的部署约束、模型验证矩阵与当前限制，并标注了 agentic 配方和 Tinker 路线图的边界。文档还加入了 GLM-5.2 FP8 历史实验证据图。整体为纯文档变更，无代码风险，但对用户配置 LoRA 的指导意义显著。

功能与动机

PR body 明确指出：旧文档已将 LoRA 描述为 colocate-only，对低精度训练支持表述过宽，遗漏多节点广播与多 LoRA，且未区分 Bridge、native、agentic 和 Tinker 路线图的边界。本次更新旨在让指南与当前代码、测试、launcher 和 roadmap 提案保持一致，并显式标注各功能的就绪状态（如“general Bridge LoRA + Inkling-specific native LoRA”“multi-LoRA 为 Bridge-based dataset-driven”“Tinker 后端为未发布 roadmap”）。

实现拆解

1. 重写生命周期描述：新增 “Training and rollout lifecycle” 章节，说明 miles 在 Megatron 中训练 adapter，在每次权重更新边界导出并通过本地 tensor/IPC 或远端 NCCL 广播同步到 SGLang；默认每次 rollout/train iteration 同步一次，无需 merge 或 checkpoint 转换。
2. 区分实现路径：新增 “LoRA training implementations” 表格，对比 Megatron-Bridge PEFT（--megatron-to-hf-mode bridge）与 Native/raw 模式（--megatron-to-hf-mode raw），并列出各自模型覆盖范围与状态（Bridge 为通用生产路径，Native 目前仅 Inkling/Inkling-Small），同时说明 native-first 的后续维护方向。
3. 增补验证矩阵与证据：新增 “Validated models and recipes” 表格，按 Bridge/Native 列出 Qwen2.5、Qwen3、GPT-OSS、Kimi K2.5、GLM-5.x、Qwen3.5/3.6、Inkling 等模型的架构类型、证据链接与注意事项；补入两张 GLM-5.2 FP8 实验曲线图（logprob/reward）作为历史全规模实验证据，并明确 CI 覆盖的是缩减层数 checkpoint，避免读者误以为全规模已验证。
4. 明确多 LoRA 与限制：说明当前 multi-LoRA 仅支持 disaggregated 且启动时拒绝 --colocate；SGLang 引擎常驻 base checkpoint，miles 选择性导出并通过 NCCL 广播新加载或 optimizer 步进的 adapter；新启动或重启的引擎会收到所有已加载 adapter。同时列出已知限制（如原生多 LoRA 未发布、Tinker 后端为 roadmap）。
5. 按 review 迭代精简：根据审阅意见先后完成删除已合并 PR 引用（#2122）、将 ASCII 流程改为 Mermaid 图后又删除、精简 Native LoRA 介绍（去除 PR 分支详细矩阵和投影注意事项）、重命名章节标题等调整。

本次为纯文档 PR，无源码改动，因此不展示代码片段。文档核心的 Bridge/Native 对比与 multi-LoRA 拓扑约束均以 Markdown 表格和文字形式呈现，可直接查看 docs/advanced/lora.md。

评论区精华

• Shi-Dong 对标题提出疑问：

  Not sure whether "Mental model" is a good section title in docs lol.

作者随后将章节重命名为 Training and rollout lifecycle。

• 关于流程图形式：

  Replace with Mermaid diagram? Would be more visually appealing than text.

作者先改为 Mermaid，但 Zhichenzzz 随后建议：

maybe we could delete those ai gen chart?

最终作者删除了图表，改用简洁文字描述生命周期。

• 关于多 LoRA 与 colocate 的准确性：

  colocate? what about multi-lora

作者澄清：单 LoRA 支持 colocated tensor/IPC 与 disaggregated NCCL；multi-LoRA 仅支持 disaggregated 且拒绝 --colocate，只广播新加载或 optimizer 步进的 adapter。

• 关于已合并 PR 引用：

  This PR is merged so I think we can drop this line?

作者删除了历史 #2122 引用，改为直接描述当前行为。

• 关于 Native LoRA 的篇幅：
  作者在回复中记录要求“Just introduce native lora”，随后精简为简短介绍，仅保留 Inkling 支持、Bridge 差异及 #1792 指向。

风险与影响

• 文档与代码漂移风险：文档中模型矩阵和限制描述非常具体，后续代码演进（如原生 LoRA 泛化 #1792、multi-LoRA 原生化 #2141）若不及时更新，会重新出现本次修复的漂移问题。
• roadmap 引用过期：文档明确引用 #2273、#2346 等 open PR 作为未发布功能，这些 PR 一旦合并或关闭，需要同步修改文档中的“未来工作”表述。
• 历史实验证据的误读风险：新增的 GLM-5.2 FP8 图为特定配置下的历史结果，文档虽已声明范围，但读者仍可能将其视为通用能力，需要结合上下文阅读。

对用户而言，本文档直接决定了 LoRA 配置的可行路径选择；对团队而言，文档明确了 native-first 的维护方向，可作为后续实现的参考基准。

关联脉络

该 PR 与多个 LoRA 相关的长期工作直接关联：

• 1792：generalized native LoRA model-provider support，是原生 LoRA 从 Inkling 专属走向通用化的关键。

• 2141：native multi-LoRA，当前多 LoRA 仅 Bridge 支持，原生路径仍在开发。

• 2273 与 #2346：Tinker 操作后端与 SDK 兼容 REST 前端，是 agentic 配方的未来承载层。

从历史 PR 看，仓库近期有多项 LoRA 相关文档与代码澄清（如 #2368 session v2、#2386 FSDP 重构等），本 PR 是其中面向用户文档的一次重要整理，为后续 LoRA 功能演进提供了明确的状态基线。