# 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`。
