sskj/docs/EXPERIMENT_GUIDE.md

实验规范指南

本仓库用于统一记录和复现不同芯片、不同 backend（SGLang / vLLM）下的推理测速实验。

1. 目录结构

实验目录为三层结构：experiments/<platform>/<experiment_name>/，其中 platform ∈ {h20, h200, p800, pro6000}；另有 experiments/TEMPLATE/ 作为新实验模板。

experiments/<platform>/<experiment_name>/
├── config.env              # 实验参数唯一来源
├── run_bench.sh            # 编排入口
├── start_sglang.sh         # SGLang server 启动脚本
├── start_vllm.sh           # vLLM server 启动脚本
└── results/<run_id>/
    ├── comparison.md
    ├── sglang/
    │   ├── results.json
    │   ├── report.md
    │   ├── raw_outputs/    # .gitignore 忽略
    │   └── logs/           # .gitignore 忽略
    └── vllm/
        ├── results.json
        ├── report.md
        ├── raw_outputs/    # .gitignore 忽略
        └── logs/           # .gitignore 忽略

上述是 TEMPLATE 式的固定场景对比实验布局（sglang vs vllm，老形态，仍可用）。当前主流实验形态是 TP/DP matrix + 自适应并发搜索：实验目录内由 matrix.json + generate_scenarios.py 生成场景，adaptive_config.env 配置搜索参数，run_adaptive_concurrency.sh 驱动，结果落盘 adaptive_results/<run_id>/（adaptive_points.jsonl、adaptive_summary.{jsonl,md,csv}、run_manifest.json、tp*_dp*/ 等），用法见 experiments/ADAPTIVE_CONCURRENCY_USAGE.md。

通用工具集中放在 scripts/common/，不要复制到每个实验。三层实验目录以 ../../../scripts/common 引用（experiments/TEMPLATE/ 为两层，用 ../../scripts/common）：

• scripts/common/lib.sh：日志、metadata、JSON 工具
• scripts/common/platform.sh：平台自动检测
• scripts/common/warmup.py：server 预热
• scripts/common/parse_backend.py：解析 raw jsonl -> results.json + report.md
• scripts/common/compare.py：生成 SGLang vs vLLM 对比表
• scripts/common/adaptive_bench_lib.sh / adaptive_concurrency.py：自适应并发搜索
• scripts/common/server_docker.sh / bench_client_docker.sh：Docker server / client 管理
• scripts/common/adaptive_heartbeat.sh：自适应测试心跳保活

2. 新增一个实验

最快方式：

cp -r experiments/TEMPLATE experiments/<platform>/<your_experiment_name>
# 修改 config.env、start_*.sh
bash experiments/<platform>/<your_experiment_name>/run_bench.sh

2.1 config.env 必备字段

EXPERIMENT="<experiment_name>"
MODEL_NAME="DeepSeek-V4-Flash"
MODEL_PATH="/data/models/DeepSeek-V4-Flash"

SGLANG_PORT="${SGLANG_PORT:-30006}"
VLLM_PORT="${VLLM_PORT:-30005}"

# venv 路径按机器实际配置调整
VENV_SGLANG="${VENV_SGLANG:-/path/to/envs/sglang}"
VENV_VLLM="${VENV_VLLM:-/path/to/envs/vllm}"

export CUDA_VISIBLE_DEVICES="${CUDA_VISIBLE_DEVICES:-0,1,2,3,4,5,6,7}"
TP="${TP:-8}"

MAX_MODEL_LEN=...
MAX_NUM_SEQS=...
MAX_RUNNING=...

# 场景："concurrency input_len output_len num_prompts"
declare -a SCENARIOS=(
  "1  512  256 32"
)

VENV_CLIENT="${VENV_CLIENT:-$VENV_SGLANG}"
SGLANG_START_SCRIPT="${SCRIPT_DIR:-.}/start_sglang.sh"
VLLM_START_SCRIPT="${SCRIPT_DIR:-.}/start_vllm.sh"

2.2 可复现性要求

每个 results.json 必须记录：

• metadata.model：模型路径
• metadata.hardware / metadata.accelerator / metadata.chip
• metadata.env：使用的虚拟环境路径
• metadata.git_commit / metadata.git_dirty
• config.server_args：完整的 server 启动命令
• config.cuda_visible_devices

这些通过 scripts/common/lib.sh 中的 write_metadata_json 和 jq 注入。

3. 平台与硬件适配

3.1 芯片级默认配置

芯片相关默认值放到 platforms/<chip>.env，现有：

• platforms/nvidia_h20.env
• platforms/nvidia_h200.env
• platforms/nvidia_rtx6000d.env
• platforms/kunlun_p800.env

实验级覆盖通过 config.env 实现。

3.2 跨芯片注意事项

项	H200	P800	备注
TP 大小	8	8/16	由 TP 控制
KV cache dtype	fp8	可能不同	在 start_vllm.sh 调整
MLA backend	flashinfer_mla	可能不支持	在 start_sglang.sh/start_vllm.sh 调整
最大上下文	受显存限制	受显存限制	通过探针测试确定
设备变量	CUDA_VISIBLE_DEVICES	可能不同	在 config.env 设置

如果某芯片不支持某个 feature，在 start_*.sh 里用条件判断，不要把条件写进通用脚本。

4. SLO 标准

默认使用 S2 层级（完整分级定义见 docs/SLO_STANDARDS.md）：

• TTFT P95 < 3000 ms
• TPOT mean < 50 ms

scripts/common/parse_backend.py 和 scripts/common/compare.py 默认按这个标准打标。如果需要其他 tier，调用 compare.py 时传入 --ttft-limit 和 --tpot-limit。

5. 断点续测

run_bench.sh 必须实现 scenario_already_completed() 检查：

• 如果某 scenario 的 raw_outputs/*.jsonl 中 completed 数量已达标，直接跳过
• 重新执行脚本即可从中断处继续

6. Git 提交规范

6.1 必须提交

• 实验代码：config.env、run_bench.sh、start_*.sh
• 最终结果：comparison.md、sglang/results.json、sglang/report.md、vllm/results.json、vllm/report.md

6.2 不要提交

• raw_outputs/
• logs/
• 中间 server 日志

这些已在 .gitignore 中忽略。

6.3 提交示例

git add experiments/<platform>/<name>/config.env \
        experiments/<platform>/<name>/run_bench.sh \
        experiments/<platform>/<name>/start_*.sh \
        experiments/<platform>/<name>/results/<run_id>/comparison.md \
        experiments/<platform>/<name>/results/<run_id>/sglang/results.json \
        experiments/<platform>/<name>/results/<run_id>/sglang/report.md \
        experiments/<platform>/<name>/results/<run_id>/vllm/results.json \
        experiments/<platform>/<name>/results/<run_id>/vllm/report.md

git commit -m "results: <experiment_name> run <run_id>"
git push origin main

7. 场景设计规范

7.1 请求数 = 并发数 × 5

每个 scenario 的 num_prompts 必须是对应 concurrency 的 5 倍，即每个并发档位至少跑满 5 轮请求，保证 P95/P99 等尾延迟指标有统计意义。

# 格式：concurrency input_len output_len num_prompts
declare -a SCENARIOS=(
  "1   512  256  5"    # 1 × 5
  "32  512  256  160"  # 32 × 5
  "128 512  256  640"  # 128 × 5
)

例外：对于超长上下文（如 128k/256k）或探针类实验，若执行成本过高，可在 config.env 中显式注释说明原因，并保留不小于 concurrency × 2 的最低样本量。

8. 命名约定

• 实验目录：experiments/<platform>/{model}_{chip}_{scenario}_{backend_vs_backend}，例如 experiments/h200/dsv4_h200_sglang_vs_vllm
• scenario 名称：c{concurrency}_i{input_len}_o{output_len}
• raw 输出：{backend}_{label}_{MMDD}_{concurrency}_{input_len}_{output_len}.jsonl
• run_id：YYYYMMDD-HHMMSS

9. 常见问题

8.1 新芯片上 server 起不来

1. 检查 platforms/<chip>.env 是否已定义
2. 检查 start_*.sh 中的 backend-specific 参数是否被该芯片支持
3. 先用最小场景（input=512, output=256, concurrency=1）验证通路

8.2 长上下文 OOM

1. 降低并发
2. 降低输出长度
3. 调整 mem-fraction-static / gpu-memory-utilization
4. 记录能跑通的最大组合，更新矩阵