8652a685e6
- rewrite README with project purpose, standard workflow, corrected index - add docs/NEW_PLATFORM_GUIDE.md (new GPU onboarding SOP, GLM5.2 reuse) - fix ../../scripts/common -> ../../../scripts/common in 42 experiment scripts - refresh stale docs (EXPERIMENT_GUIDE, H200_QUICKSTART, ADAPTIVE_CONCURRENCY_USAGE, BENCHMARK_WORKFLOW) - remove dead code (dp_proxy.py) and .bak leftovers - add p800 adaptive results (tp4_dp2/tp8_dp1 metrics + summary) - gitignore envs/charts and .tmp_charts
140 lines
9.4 KiB
Markdown
140 lines
9.4 KiB
Markdown
# 新平台接入指南（New Platform Onboarding SOP）
|
||
|
||
> 目标：新显卡（GPU/NPU）到货后，用最短时间跑起与既有平台口径一致的推理性能实验。
|
||
> 读者：执行接入的人或 Agent。带 🤖 的步骤 Agent 可自动完成；带 🧑 的步骤需要人确认或提供信息。
|
||
|
||
## 0. 前置准备 🧑
|
||
|
||
接入前确认以下信息就绪，缺一项都会卡住后续步骤：
|
||
|
||
| 项目 | 说明 | 示例 |
|
||
|---|---|---|
|
||
| 机器与驱动 | 8 卡整机，驱动/固件可用，`nvidia-smi` 或厂商等价工具（`xpu-smi`）能看到全部卡 | — |
|
||
| 推理镜像 | 该平台可用的 vLLM / SGLang 镜像或 native 环境 | `vllm/vllm-openai:latest`、`iregistry.baidu-int.com/xpu/sglang-p800-...` |
|
||
| 模型权重 | 模型在本机的路径与精度格式 | `/data1/hf_models/DeepSeek-V4-Flash`（FP8）、`/data1/models/DeepSeek-V4-Flash-INT8` |
|
||
| 上下文上限 | 该平台显存能支撑的 max context | H20：1M；P800 INT8：140k |
|
||
| 数据集 | ShareGPT 种子文件（random workload 用） | `datasets/ShareGPT_V3_unfiltered_cleaned_split.json` |
|
||
| 显存约束 | 单卡显存，预判 TP/DP 可行性（见 §4.2） | P800 96 GiB/卡 → TP2 放不下 INT8 专家权重 |
|
||
|
||
## 1. 平台配置 🤖
|
||
|
||
1. 新建 `platforms/<chip>.env`（参考 `platforms/nvidia_h20.env` / `platforms/kunlun_p800.env`），至少包含 `CHIP`、`ACCELERATOR`、`HARDWARE`、`ENGINE`、`DEFAULT_PORT`、`MODEL_ROOT`；Docker 平台再加 `DOCKER_IMAGE`、`CONTAINER_NAME`；需要运行时补丁的加 `PATCH_ROOT` 并把补丁放到 `platforms/patches/<chip>/`。
|
||
2. 在 `scripts/common/platform.sh` 的自动探测分支里加上新平台（当前只识别 P800 / H20 / 其他 NVIDIA→H200，**新 NVIDIA 卡不改会被误判成 H200**）。
|
||
3. 在 `platforms/README.md` 的平台表中加一行。
|
||
|
||
## 2. 复制实验目录 🤖
|
||
|
||
**NVIDIA 平台**（有官方 vLLM/SGLang 镜像）直接复制 H20 目录——它是路径正确、维护最新的范本，且 NVIDIA 平台间 `start_*_docker.sh` 零改动可复用：
|
||
|
||
```bash
|
||
cp -r experiments/h20/dsv4_h20_vllm_tp_dp_matrix experiments/<chip>/dsv4_<chip>_vllm_tp_dp_matrix
|
||
cp -r experiments/h20/dsv4_h20_sglang_tp_dp_matrix experiments/<chip>/dsv4_<chip>_sglang_tp_dp_matrix
|
||
# 清理复制过来的结果与缓存
|
||
rm -rf experiments/<chip>/*/adaptive_results experiments/<chip>/*/results experiments/<chip>/*/__pycache__
|
||
```
|
||
|
||
**非 NVIDIA 平台**（XPU 等）同样从 H20 目录复制，但需按 §4 重写启动脚本与平台回调，以 `experiments/p800/dsv4_p800_sglang_tp_dp_matrix` 为范例。
|
||
|
||
> 不要抄 `experiments/h200/` 或 `experiments/pro6000/` 的目录结构组织方式以外的内容：那里存在 `dsl`（应为 `osl`）的批量误改名残留，新目录以 H20 版为准。
|
||
|
||
## 3. 修改三件套配置 🤖（🧑 确认关键参数）
|
||
|
||
### 3.1 `config.env`（核心参数面板）
|
||
|
||
| 必改项 | 说明 |
|
||
|---|---|
|
||
| `EXPERIMENT` | 实验名，与目录名一致 |
|
||
| `MODEL_NAME` / `MODEL_PATH` / `SERVED_MODEL_NAME` | 本机模型路径（机器相关） |
|
||
| `DOCKER_IMAGE` / `CONTAINER_NAME` | 平台镜像；容器名专用化避免冲突 |
|
||
| `VLLM_PORT` / `SGLANG_PORT` | 避开已占用端口 |
|
||
| `CUDA_VISIBLE_DEVICES` / `XPU_VISIBLE_DEVICES` | 设备选择 |
|
||
| `MAX_MODEL_LEN` / `CONTEXT_LENGTH` | 按平台显存与需求设定 |
|
||
| `GPU_MEMORY_UTILIZATION` / `MEM_FRACTION_STATIC` | 显存水位（H20 0.9 / P800 0.8） |
|
||
| `KV_CACHE_DTYPE`、`BLOCK_SIZE` / `PAGE_SIZE` | KV cache 精度与块大小 |
|
||
| `PARALLEL_CONFIGS` | 按显存裁剪（见 §4.2） |
|
||
| `DATASET_PATH` | 本机数据集路径 |
|
||
|
||
### 3.2 `adaptive_config.env`
|
||
|
||
一般保持默认即可（起步 C=16、×2 或 +16 步进、TTFT_SLO_MS=4000、TTFT_GROUP_SKIP_MS=8000、num_prompts=5×C）。显存小或单请求 prefill 慢的平台，可适当降低 `SEARCH_MAX_CONCURRENCY`。
|
||
|
||
### 3.3 `matrix.json`
|
||
|
||
按 `CONTEXT_LENGTH` 和显存砍 shape：超出上下文上限的 ISL 删掉，显存放不下的组合标 `N`。参照 H20（1M 上下文，7 个 ISL 档）与 P800（140k 上下文，5 个 ISL 档）两版的取舍。
|
||
|
||
## 4. 非 NVIDIA 平台的额外工作（以 P800 为范例）🧑🤖
|
||
|
||
### 4.1 需要重写的地方
|
||
|
||
- **`start_*_docker.sh`**：设备映射（如 `/dev/xpu*`）、厂商 env 变量、引擎 launch args（attention backend、量化、kv-cache dtype、cuda graph 等价物开关）、补丁挂载（如 P800 挂 `bench_serving.py` 补丁补 P95 指标）、容器内 bootstrap。
|
||
- **`run_adaptive_concurrency*.sh` 的 5 个 `engine_*` 回调**：`engine_start_server` / `engine_stop_server`（pid kill 还是 `docker rm -f`）、`engine_run_bench`（独立客户端容器还是 `docker exec` 进服务端容器）、`engine_detect_oom`（日志文件还是 `docker logs`）、`engine_build_server_args`。
|
||
- **GPU 监控**：公共库的 `adaptive_start_gpu_monitor` 写死 `nvidia-smi`，非 NVIDIA 平台在 run 脚本里用厂商工具重写该函数（P800 即用 `xpu-smi` 覆盖）。
|
||
- **warmup 能力差异**：部分厂商镜像的 bench_serving 不支持 `--warmup-requests`，需设 `BENCH_WARMUP_MAX_REQUESTS=0` 并在 adaptive_config.env 里注明。
|
||
|
||
### 4.2 显存可行性预判（避免白跑）
|
||
|
||
MoE 模型的专家权重在未开 EP 时按 TP 组切分、DP 副本间不共享：每卡专家权重 ≈ 专家总权重 / TP。实例：DSV4-Flash-INT8 路由专家约 264 GiB，P800 单卡 96 GiB → TP=2 每卡需 137 GiB，启动即 OOM，TP≥4 才可行。接入时先算一遍，把不可行的配置从 `PARALLEL_CONFIGS` 去掉，并把根因写进 config.env 注释（照 P800 的做法）。
|
||
|
||
## 5. 冒烟 🤖
|
||
|
||
```bash
|
||
cd experiments/<chip>/dsv4_<chip>_<engine>_tp_dp_matrix
|
||
|
||
# 1. dry-run：只打印计划，不起服务
|
||
DRY_RUN=1 bash run_adaptive_concurrency_add16.sh
|
||
|
||
# 2. 单 shape 小并发：验证起服务、发压测、出指标全链路
|
||
RUN_ID=smoke-$(date +%Y%m%d-%H%M%S) \
|
||
TP_LIST="8" ISL_LIST="1024" OSL_LIST="128" GRID_LIMIT=1 SEARCH_MAX_CONCURRENCY=8 \
|
||
bash run_adaptive_concurrency_add16.sh
|
||
|
||
# 3. 检查 smoke 产物：adaptive_results/smoke-*/adaptive_points.jsonl 应有 COMPLETED 点
|
||
```
|
||
|
||
冒烟失败的常见原因：镜像 launch args 不被支持（查服务端日志）、端口冲突、数据集路径不存在、显存不足（回 §4.2）。
|
||
|
||
## 6. 正式跑 🤖
|
||
|
||
```bash
|
||
tmux new-session -d -s <chip>-<engine>-adaptive \
|
||
"cd $(pwd) && bash run_adaptive_concurrency_add16.sh"
|
||
```
|
||
|
||
- 心跳监控：`scripts/common/adaptive_heartbeat.sh` 或 `tail -f adaptive_results/<run_id>/logs/orchestrator.log`。
|
||
- 中断了用 `RESUME_RUN_ID=<run_id>` 断点续跑（按已终态 shape 去重）。
|
||
- 完整参数说明见 `experiments/ADAPTIVE_CONCURRENCY_USAGE.md`。
|
||
|
||
## 7. 分析、报告与归档 🤖（🧑 确认发布）
|
||
|
||
1. **分析**：用 Python 从 `adaptive_points.jsonl` / `adaptive_shapes.jsonl` 实算（SLO：TTFT P95 < 3s 且 TPOT P95 < 50ms，严格小于），禁止目测估算。
|
||
2. **飞书报告**：按飞书 wiki「显卡性能报告 / 性能报告编写指南（README）」的骨架写到「显卡性能报告/<平台>」节点下；图表用 `envs/charts/bin/python` + matplotlib 生成。
|
||
3. **多维表格**：在「模型推理适配 Bench 迭代跟踪」的对应平台表（没有则按现有 schema 新建）按"每成功探测点一行"回填；`SLO达标状态` 按上述口径判定。
|
||
4. **提交**：实验代码 + `adaptive_results/<run_id>/` 的 jsonl/summary/manifest 入库；日志与 raw_outputs 不入库。
|
||
|
||
## 8. 完成检查清单
|
||
|
||
- [ ] `platforms/<chip>.env` 已建，`platform.sh` 探测分支已加，`platforms/README.md` 已更新
|
||
- [ ] `config.env` / `adaptive_config.env` / `matrix.json` 三件套已按平台调整
|
||
- [ ] smoke 通过（有 COMPLETED 探测点）
|
||
- [ ] 正式 run 的 `run_manifest.json` 参数正确
|
||
- [ ] 飞书报告已发布到对应平台节点下
|
||
- [ ] 多维表格已回填
|
||
- [ ] git 提交不含日志、raw_outputs、gpu_logs
|
||
|
||
## 9. 已知坑
|
||
|
||
1. **公共库路径层级**：`experiments/<platform>/<experiment>/` 下的脚本引用公共组件必须是 `${SCRIPT_DIR}/../../../scripts/common`；`experiments/TEMPLATE/` 下是 `../../`。写错会在 source 阶段直接失败。
|
||
2. **机器相关绝对路径**：模型、数据集、venv 路径随机器不同（`/data1/...`、`/data3/...`），换机器先改 config.env，不要在脚本里写死。
|
||
3. **TTFT SLO 停止 ≠ 饱和**：add16 流派的搜索在 P95 TTFT 超 4000ms 即停，绝大多数 shape 不会到达 TPS 平台期，报告中的"最佳 TPS"是 TTFT 边界内最高值，分析时不要当成吞吐上限。
|
||
4. **`dsl` 命名坑**：h200/pro6000 目录部分文件把 `osl` 误改名成 `dsl`（含 CSV 表头），复制时以 h20 目录为准。
|
||
5. **结果结构以 jsonl 为准**：`.gitignore` 排除 csv/logs，跨机器汇总数据时用 `adaptive_points.jsonl`、`adaptive_shapes.jsonl`、`adaptive_summary.*`、`run_manifest.json`。
|
||
|
||
## 10. 新模型接入（GLM5.2）
|
||
|
||
GLM5.2 **完全复用**本 SOP 的实验与报告流程，差异只在配置层：
|
||
|
||
1. 新目录命名 `experiments/<platform>/glm52_<platform>_<engine>_tp_dp_matrix/`；
|
||
2. `config.env` 改模型路径、`SERVED_MODEL_NAME`、量化方式（按发布精度）、`CONTEXT_LENGTH`（按模型实际上限）、引擎 launch args（attention backend / rope / 量化 flag 等按模型要求）；
|
||
3. `matrix.json` 按模型上下文上限调整 ISL 档；
|
||
4. SLO 口径、报告骨架、多维表格结构不变；多维表格的 `模型名称` 选/新增 GLM5.2 对应选项。
|