# SGLang B300 原生拓扑矩阵（部署方案一）

对应调研文档（本地仓库 `sskj/docs/MINIMAX_H3_B300_PLAN1_NATIVE_TOPO.md`）：
**原生 sglang、无 lossy 优化**，只调 tp / ulysses / 实例数 / 实例内批并发 / 精度档，目标节点级最高吞吐与 GPU 利用率。

## 口径（与 6000D 报告完全对齐，结果可直接对比）

- 框架/环境：SGLang（6000D 机 conda env `sglang`，sglang 0.5.17；B300 上机后按实际环境覆盖 `PYTHON`/`SGLANG_BIN`）。
- 生成规格：20 inference steps、5 秒、16:9、`flow_shift=12.0`、`audio_flow_shift=3.0`。
- 任务：FL2VA、Ref2VA；分辨率：480、720、768、1080；每任务每档 8 条，总量 32 条。
- 样本按 prompt 分片均分到每个实例；实例间并行，实例内并发由 `--in-flight` 控制。

## 与 6000D 矩阵的差异（B300 新增轴）

| 轴 | 6000D（sglang-base） | B300（本目录） |
|---|---|---|
| 拓扑 | TP8×1 / TP4×2 / TP2×4（`--ulysses-degree 1`） | Ulysses-8×1、Ulysses-4×2、tp1×8、单卡双实例×8 |
| 批并发 | 固定 `--batching-max-size 1` | `--batching-max-size {1,2,4}`（原生吞吐主杠杆） |
| 精度 | BF16 | BF16 / FP8（`--quantization fp8`） |
| 失败处理 | 严格 die | `SKIP_ON_FAIL=1` 记录后继续（探索期） |

## 默认矩阵（TOPO_LIST，`name|replicas|tp|ulysses|batching`）

| topo | 说明 | 依据 |
|---|---|---|
| `u8x1` | Ulysses-8 × 1 实例，batch1 | 官方 8×B300 验证拓扑（19.04s@BF16） |
| `u8x1_b2` / `u8x1_b4` | 单实例批 2 / 批 4 | 官方吞吐档：`--encoder-parallel dp --batching-max-size N` |
| `u4x2` / `u4x2_b2` | 2 实例 × Ulysses-4（批 1 / 2） | 折中拓扑 |
| `tp1x8` / `tp1x8_b2` | 8 实例 × 单卡驻留（批 1 / 2） | 6000D「多实例并行」结论直译（B300 单卡 288GB 可整模型驻留） |
| `share2x8` | 单卡双实例 × 8 卡 = 16 实例（实验项） | 用户点名方向；仅 FP8 档可行 |

- `GPU_MODE=partition`（默认）：实例 i 用卡 `[i*K, (i+1)*K)`，K = tp×ulysses。
- `GPU_MODE=share`（share2x8 用）：每实例 1 卡，实例 i 用卡 `i % TOTAL_GPUS`（同卡多实例）。
- `--encoder-parallel dp` 仅在 batching>1 时追加；batch=1 用默认 `auto`。

## 用法

```bash
# dry-run：只打印矩阵计划
DRY_RUN=1 bash scripts/run_sglang_h3_b300_matrix.sh

# 冒烟：单 topo、单精度、单任务、少请求
TOPO_LIST="u8x1" QUANT_LIST="bf16" TASKS="fl2va" REQUESTS_PER_RESOLUTION=1 \
  RUN_ID=smoke bash scripts/run_sglang_h3_b300_matrix.sh

# 正式跑（放 tmux；默认全矩阵 = 8 topo × 2 精度 × 2 任务）
tmux new-session -d -s b300-matrix "bash scripts/run_sglang_h3_b300_matrix.sh"
```

常用覆盖变量：`TOTAL_GPUS NUM_INFERENCE_STEPS DURATION_SECONDS TOPO_LIST QUANT_LIST TASKS RESOLUTIONS REQUESTS_PER_RESOLUTION BASE_PORT MODEL REFERENCE_IMAGE PROMPT_FILE PYTHON SGLANG_BIN CLIENT_SCRIPT RUN_ID RESULT_ROOT SKIP_ON_FAIL GPU_MODE`。

## 结果目录

```
results/<run_id>/
├── summary.tsv            # 全矩阵一行一 phase（可贴进飞书多维表格）
├── orchestrator.log / orchestrator.pid
└── <topo>_<quant>/
    └── <task>/
        ├── server_<i>_port<p>/        # server.log / cuda_visible_devices.txt / outputs/
        ├── client_<i>_port<p>/        # client.log / results.jsonl
        └── summary.json               # 该 phase 汇总
```

summary.tsv 列：`topo prec replicas tp ulysses batching inflight task expected recorded completed failed machine_qps latency_mean_s latency_p95_s machine_wall_s`。

## 备注

- 20 步/5s 为 6000D 对比口径；B300 官方 50 步数据见调研文档（u8x1 BF16 19.04s/请求、83.6GB/卡；FP8 18.03s、51.9GB/卡）。
- 长片（10/15s）批容量按 token 数等比缩水，另跑专项。
- 方案二（Turbo LoRA / SubBlock / Cache-DiT / AdaLN 缓存等优化策略）另行编排，不动本目录口径。