Add MaaS collaboration overview

docs/aituner-maas-collab-overview-20260703.md

@@ -0,0 +1,221 @@
+# AITuner：MaaS Serving Config 自动调优 — 合作概述
+
+> 面向：配置调优团队
+> 目的：介绍 AITuner 是什么、为什么它比纯 LLM loop 可靠、以及我们建议的 pilot 合作方式。
+> 日期：2026-07-03
+
+## 一句话总结
+
+AITuner 把 LLM serving engine 的 config tuning 从"人工试错 / LLM 黑盒瞎猜"变成
+**基于真实测量、按 bottleneck 机制分类、由 validator 把关的自动实验循环**。
+我们希望在贵团队的真实环境上跑通 1-2 个 case，验证它能否成为你们的日常工具。
+
+## 1. 问题背景
+
+MaaS 场景下 tuning 的现状：
+
+- 平台上有**数百个模型**，模型本身还在持续迭代；
+- 硬件平台在更新，同一个模型在不同硬件上的最优 config 不同；
+- 每个 (model, hardware, workload, SLO) 组合都是一个独立的 tuning case；
+- 人力远远覆盖不了所有 case，大量 case 只能用默认或粗调的 config 上线，
+  留下吞吐和成本上的浪费。
+
+AITuner 的目标：**自动化 tune 这些没人力覆盖的 case**，输出满足 SLO 的
+engine config，并附带可审计的实验证据。
+
+## 2. 为什么"纯 LLM 自动调参"不够
+
+直接让 LLM 在循环里提 config、跑一轮、再提 config，实践中有两个硬伤：
+
+**(a) 缺 domain-specific 知识和内部 context。**
+
+- LLM 会误读 engine knob 的语义，典型例子是 vLLM 的 DP：LLM 常把它当成
+  "免费加吞吐"的开关，忽略它改变的是 replica 数和 per-GPU 效率，
+  在 per-GPU 指标下盲目 scale-out 反而变差；
+- 内部平台（如 dash）有大量内部环境变量和 launch 约束，LLM 完全没有这部分
+  context，提出的 config 经常直接 launch failure 或 OOM。
+
+**(b) 缺 bottleneck breakdown，不会像专家一样理解系统。**
+
+- LLM 拿到的往往只是"pass rate 低了"这样的 scalar 结果，
+  它无法区分瓶颈在 prefill、decode、admission/queueing 还是 memory；
+- 没有瓶颈归因，proposal 就退化成 knob space 里的随机游走：
+  重复已试过的配置、在错误的 knob family 上反复消耗 GPU trial。
+
+AITuner 的设计就是补上这两块：把系统知识和瓶颈分析放进一个 **harness**，
+LLM 只负责在 harness 给出的合法候选里做排序和取舍。
+
+## 3. AITuner 是怎么工作的（概述）
+
+一句话：AITuner 是一个自动实验循环——对目标 case 做真实压测，
+从结果做瓶颈归因，按系统机制生成下一个 config 候选，
+经 validator 把关后执行下一轮测量，直到证据表明继续实验不再值得。
+
+```text
+真实压测 ──> 瓶颈归因 ──> 机制化候选 ──> Validator 把关 ──> 下一轮压测 / 停止
+```
+
+对使用方来说，需要知道的只有四点：
+
+1. **每一步决策都来自真实测量**，不是 LLM 的自然语言猜测——每轮以
+   SLO verdict、pass rate、`request_rate_per_gpu`、launch/OOM 状态为准；
+2. **像专家一样先归因再动手**：把 SLO 违约症状聚合成 prefill / decode /
+   admission / memory 瓶颈假设，候选 config 只从对应的机制
+   （拓扑切分、prefill 调度、并发准入、KV cache 余量等）中生成，
+   不在 knob 空间里盲搜；
+3. **Validator 挡住不合法和重复的实验**：engine 参数合法性、硬件/拓扑约束、
+   内部平台 launch 约束、已测配置查重、失败记忆——包括 LLM 在内的任何
+   proposal 来源都必须过这一关；
+4. **知道什么时候该停**：验证充分或触及测量上限时确定性停止，
+   不多烧 GPU，也不会静默宣称"已经最优"。
+
+架构与模块细节见 `docs/aituner-harness-design-contract.md`，
+pilot 阶段可按需深入，这里不展开。
+
+## 4. 关键性质：不被单一 LLM 绑死
+
+Harness 是 **planner-agnostic** 的：LLM、确定性 heuristic 甚至 BO/bandit
+都只是在同一个 CandidateSet 上做排序。目前已经验证：
+
+- **No-LLM 模式**：在没有任何 LLM endpoint 的情况下，harness 可以作为
+  deterministic planner 完成整轮 tuning（baseline → 假设 → 候选 → 打分 →
+  proposal/stop），已有 Qwen30B 真实轨迹；
+- 高分确定性候选存在时根本不调 LLM，LLM 只在候选需要复杂 tradeoff
+  排序时介入。
+
+这意味着**换 LLM 供应商的风险是可控的**：tuning 的正确性来自
+harness 的证据编译和 validator，而不是某个特定模型的能力。
+
+## 5. 已有证据（内部实验，3 个 case）
+
+对照组均为"纯 LLM loop"（同一 LLM、同一压测框架，只关闭 harness），
+指标为满足 SLO 的 `request_rate_per_gpu`（每 GPU 可承载请求率，越高越好）。
+
+### Case 1：qwen27b chat 0-8k，dash0 内部 vLLM，H20
+
+真实 trace 窗口回放（`chat_w20260311_1000`），SLO：95% pass rate、
+TTFT 2s/4s/6s 分档、TPOT ≤ 50ms。
+详见 `docs/qwen27b-chat-0-8k-current-config-fig18-20260506.md`。
+
+| | 纯 LLM loop | AITuner |
+| --- | --- | --- |
+| 最终最优 config | TP2/DP1，**0.2025** req/s/GPU | TP4，**0.4429** req/s/GPU（**约 2.2x**） |
+| baseline（起点相同） | TP1/DP1，0.0350 | TP1/DP1，0.0350 |
+| 搜索路径 | 第 2/3 轮先选 DP2、DP4，per-GPU 吞吐反而回落；第 4 轮才到 TP2 | 瓶颈归因判定 TTFT/prefill 主导，第 2 轮直接 TP2（0.2142），第 4 轮 TP4（0.4429） |
+| tuning 开销 | 跑满 12 轮 GPU trial，其中第 5-12 轮全部是无可行点的 runtime probe（纯浪费） | 第 8 轮确定性 stop，实际执行 4 次 GPU trial，全程约 2.5 小时 |
+
+两个值得注意的点：
+
+- 纯 LLM loop 的前几轮正是第 2 节所说的 DP 误读实例——LLM 把 DP scale-out
+  当成免费吞吐，per-GPU 效率被稀释，绕了 3 轮弯路；
+- 单轮真实 trial（engine launch + 多个二分 probe）约 1 小时，跑满 12 轮
+  意味着 10 小时以上的 GPU 占用；AITuner 在拿到约 2.2x 的 config 的同时，
+  把整个 tuning 过程压到约 2.5 小时。
+
+### Case 2：qwen235b thinking prefill（大模型，TP4 baseline）
+
+详见 `docs/qwen235b-thinking-prefill-harness-20260427.md`。
+
+| | 纯 LLM loop | AITuner |
+| --- | --- | --- |
+| 最优 config | TP8，**0.3794** req/s/GPU，第 **10** 轮才找到 | TP8，**0.3863** req/s/GPU，第 **2** 轮即超过对照组 12 轮的最优值 |
+| 搜索路径 | 中途浪费在 DP2、EP4 等失败探索上 | 从 baseline 直接跳到 TP8/DP1，跳过对照组踩过的失败方向 |
+| tuning 开销 | 12 轮预算 | 到达最优的迭代数从 10 降到 2（**5x**） |
+
+大模型 case 上单轮 trial 更贵，少跑 8 轮的绝对 GPU 成本节省也更大。
+
+### Case 3：Qwen3-30B-A3B，社区 vLLM 0.20（非内部环境同样适用）
+
+详见 `docs/qwen30b-community-vllm020/harness-early-stop-ablation-20260502.md`。
+两个子实验：
+
+- **测量上限识别**（search 上限较低时）：默认 config 已触及压测搜索上限。
+  AITuner 只执行 1 次 GPU trial 就识别出"当前压测范围测不出更优配置"，
+  停止并明确报告原因；纯 LLM loop 把 12 轮预算烧完——第 2 轮 DP2 使
+  per-GPU 吞吐减半，第 3-12 轮**连续 10 轮 launch failure**。
+  净节省 11 轮 GPU 占用。
+- **放宽上限后的真实搜索**：AITuner 第 4 轮到达最优 config family
+  （TP2 + runtime 精调）并在第 5 轮 stop；纯 LLM loop 经历 EP launch
+  failure、不可行 DP probe 等弯路后第 7 轮才到同一 family（单次测值差
+  约 1.5%，在重复压测噪声内）。
+
+### 汇总
+
+| Case | config 性能（vs 纯 LLM loop 最优） | 到达最优迭代数 | 省下的无效 GPU trial |
+| --- | --- | --- | --- |
+| qwen27b 内部 vLLM | **约 2.2x**（0.4429 vs 0.2025） | 4 vs 4，但对照组随后 8 轮全部无效 | 8 轮 infeasible probe |
+| qwen235b thinking | 持平略优（0.3863 vs 0.3794） | **2 vs 10（5x）** | 8 轮失败/弱探索 |
+| qwen30b 社区 vLLM | 同一 config family（±1.5%） | 4 vs 7；上限场景 1 vs 12 | 最多 11 轮（含 10 轮 launch failure） |
+
+诚实说明：以上是有限 case 上的证据，qwen30b 子实验使用了有界压缩回放
+（固定输出长度）做收敛性测试，不等同生产 benchmark；结论是"更快收敛到
+同等或更好的 config、大幅减少无效 GPU trial"，不是全局最优性证明。
+这正是我们想通过 pilot 在你们的真实 case 上进一步验证的。
+
+## 6. 你们会得到什么
+
+对每个 case，AITuner 的产出不只是一个 config：
+
+1. **满足 SLO 的 engine config**（以 `request_rate_per_gpu` 为主要
+   跨拓扑指标）；
+2. **完整可审计的实验轨迹**：每个 trial 的假设、预期效果、真实测量、
+   confirm/reject 结论，以及 probe 级别的明细（`probe_details.jsonl`）；
+3. **瓶颈归因报告**：这个 case 的限制因素是 prefill、decode、admission
+   还是 memory，为什么；
+4. **明确的 stop 理由**：是候选耗尽、验证充分，还是 measurement 上限
+   （比如 search 范围）不够——不会静默糊弄。
+
+这些轨迹本身对你们的人工 tuning 经验沉淀也有价值。
+
+## 7. 建议的合作方式（pilot）
+
+我们目前缺少的是贵团队每个 case 的真实环境和硬件。建议直接在你们的
+环境上做，分四步：
+
+**Phase 0 — 选 case、对齐输入（约 1 周）**
+- 双方选定 1-2 个有代表性的 case；
+- 每个 case 需要：模型 + 硬件规格、SLO 定义（TTFT/TPOT/pass rate）、
+  workload trace 或可复现的流量描述、当前人工 config（作对照基线）；
+- 我们把 dash 平台的内部环境变量 / launch 约束接入 harness 的
+  launch-feasibility 层和 validator。
+
+**Phase 1 — 在你们环境跑通（1-2 周）**
+- 部署 AITuner，先跑 baseline 建立测量基线，再跑完整 tune loop；
+- 我们负责跑通和调试，你们提供环境访问和平台侧支持。
+
+**Phase 2 — 对比评估**
+- AITuner 结果 vs 你们的人工 config：SLO 达标情况、`request_rate_per_gpu`、
+  消耗的 GPU trial 数、时间成本；
+- 全部结果附实验轨迹，可复查。
+
+**Phase 3 — 决策**
+- 若 pilot 达标，讨论扩展到更多 case 的方式（接入流程、权限、
+  运行成本、维护分工）。
+
+## 8. 当前依赖与风险（如实说明）
+
+1. **LLM 依赖**：当前 planner 使用 gpt-5.5。计划切换到百炼
+   qwen3.7-max 的 dog-fooding API，并做同 case 的效果对比。
+   风险缓冲：harness 的 no-LLM deterministic 路径已经能独立完成
+   相当一部分 tuning（见第 4 节），planner 模型的能力差距被 harness
+   部分补偿，切换成本预计可控——但对比数据出来之前这是一个待验证项。
+2. **Engine 适配**：当前 mechanism families 主要针对 vLLM 的 knob
+   语义；SGLang 等其他 engine 需要一层 adapter 把 knobs 映射到相同的
+   mechanism vocabulary（架构上已预留，工作量取决于目标 engine）。
+3. **平台适配**：dash 内部环境变量和 launch 约束需要在 Phase 0 一次性
+   接入，之后由 failure memory 持续积累。
+4. **边界**：AITuner 保证的是结构化、可审计、测量高效的搜索；
+   它不证明全局最优，瓶颈分类是 symptom-based 的启发式归因而非
+   完美因果诊断。对生产决策来说，可审计比"号称最优"更重要。
+
+## 9. 我们需要贵团队提供的
+
+- 1-2 个 case 的测试环境和硬件访问（或由你们的同学代跑，我们远程支持）；
+- 每个 case 的 SLO 定义和 workload trace；
+- dash 平台内部环境变量 / launch 约束的文档或对接人；
+- 百炼 qwen3.7-max dog-fooding API 的配额（用于 LLM 切换对比）。
+
+---
+
+附：更完整的设计语义见 `docs/aituner-harness-design-contract.md`，
+harness 各机制与实验证据见 `docs/aituner-harness-summary.md`。