benchmark-vllm-v.s-sglang

这是统一的 vLLM / SGLang benchmark 入口。目标是用新的 Matrix Runner 完成 week1-week4 的评测任务，并把新结果、日志、历史结果分开管理。

1. 核心概念

新评测入口是 scripts/matrix_runner.py。它读取 configs/tasks/*.json，展开模型、server、client 和参数矩阵，按 case 启动服务、运行 client、采集 GPU 指标，并把结果写入统一目录。

Matrix Runner
  -> configs/models/   # 模型路径、served model name、上下文长度
  -> configs/servers/  # vLLM / SGLang 服务启动模板
  -> configs/clients/  # GuideLLM、vLLM bench、自定义 evaluator
  -> configs/tasks/    # week1-week4 任务矩阵
  -> results/raw/      # 原始产物
  -> results/logs/     # stdout/stderr 日志
  -> results/summary/  # 归一化 CSV/JSONL

2. 目录结构

configs/
  models/             # 模型配置
  servers/            # vLLM / SGLang server 模板
  clients/            # benchmark client / evaluator 模板
  tasks/              # week-task 命名的任务入口
  vllm_sweep/         # vLLM sweep 参数
data/
  tool_call_eval/
  reasoning_stream_eval/
scripts/
  matrix_runner.py
  normalize_results.py
  tool_call_evaluator.py
  reasoning_stream_evaluator.py
  auto_run_ready_models.py
  vllm_startup_smoke.py
results/
  raw/                # 新体系原始产物
  logs/               # 新体系统一日志
  summary/            # 新体系统一汇总
  startup_smoke/      # 大模型启动 smoke
  archive/            # 历史结果索引
reports/              # 结论报告
docs/                 # 轻量文档索引
legacy/               # 旧体系代码和历史结果，只读追溯

3. 快速开始

cd /nfs100/xiaoyixiao/benchmark-vllm-v.s-sglang
export NO_PROXY=127.0.0.1,localhost
export no_proxy=127.0.0.1,localhost

只验证配置展开，不启动模型：

python3 scripts/matrix_runner.py configs/tasks/week1-2-task1-engine-compare.json --dry-run --limit 3
python3 scripts/matrix_runner.py configs/tasks/week4-task4a-tool-call-qwen25-7b-v2.json --dry-run

真实执行：

python3 scripts/matrix_runner.py configs/tasks/week4-task4a-tool-call-qwen25-7b-v2.json \
  --execute \
  --run-id formal_qwen25_7b_tool_v2_$(date +%Y%m%d_%H%M%S)

执行完成后归一化：

python3 scripts/normalize_results.py results/raw/<run_id>

4. Week 任务入口

5. 已导入 Benchmark 数据

已从 week5_eval_toolchain 迁入一组正式 Benchmark 数据，只迁移原始结果和归一化汇总，不迁移调研报告或报告草稿。导入数据仍按正式 run 命名，统一放在 results/raw/ 和 results/summary/。

6. Clients 和 Servers

servers 指被测推理服务的启动方式，例如普通 vLLM、tool-call vLLM、reasoning-stream vLLM、SGLang。它决定模型如何被 serve 起来、端口是什么、GPU 怎么绑、要不要带 parser 参数。

clients 指压测或评测服务的请求端，例如 GuideLLM、vllm bench serve、tool_call_evaluator.py、reasoning_stream_evaluator.py。它决定怎么向服务发请求、发多少请求、如何评分和输出 client.json。

7. 三个 vLLM Server 模板

• configs/servers/vllm.json：通用 serving 性能模板，用于 week1-3。它只关心基础启动、prefix cache、chunked prefill 等性能参数。
• configs/servers/vllm_tool_call.json：工具调用模板，用于 week4 tool calling。它会按任务注入 --enable-auto-tool-choice --tool-call-parser <parser>，也支持 structured outputs 参数。
• configs/servers/vllm_reasoning_stream.json：推理流解析模板，用于 week4 reasoning stream。它会按任务注入 --reasoning-parser <parser>，用于解析 delta.reasoning 或 <think> 类输出。

8. 结果和日志规范

results/raw/<run_id>/<case_id>/attempt_00/
  case_meta.json
  client.json
  results.jsonl
  gpu.csv

results/logs/<run_id>/<case_id>/attempt_00/
  server.stdout.log
  server.stderr.log
  client.stdout.log
  client.stderr.log

results/summary/
  <run_id>.csv
  <run_id>.jsonl

新的正式结果不要写进 legacy/benchmark_results/、reports/ 或 docs/。

9. 历史结果

历史结果只用于追溯：

legacy/benchmark_results/
results/archive/README.md

历史 legacy 结果不再追加。新跑的正式任务统一进 results/raw/、results/logs/、results/summary/。

10. auto_run_ready_models_state.json

results/auto_run_ready_models_state.json 是 scripts/auto_run_ready_models.py 的状态文件。它记录自动轮询任务哪些已经完成、哪些失败以及对应 run_id，避免自动 runner 反复跑同一个任务。

它不是 benchmark 结果本身，只是自动调度器的 checkpoint。正式结果仍以 results/raw/<run_id>/ 和 results/summary/<run_id>.csv/jsonl 为准。

11. 推荐工作流

1. 先 --dry-run 看 case 数和 case_id。
2. 确认 GPU 空闲、模型权重存在、端口没有被占用。
3. 用 --execute --run-id <name> 跑正式任务。
4. 跑 scripts/normalize_results.py results/raw/<run_id>。
5. 只引用 results/summary/<run_id>.csv/jsonl 写报告。
6. 失败排查看 results/logs/<run_id>/，不要把日志散落到 docs 或 reports。