1. 操作步骤

• 该脚本能够自动搜索最优的vLLM服务器参数组合（包括max-num-seqs和max-num-batched-tokens），在满足端到端延迟和前缀缓存命中率等要求的同时，实现吞吐量最大化。

1.1 前提条件

1. 克隆 vLLM 并切到目标分支

   git clone https://github.com/vllm-project/vllm.git
   cd vllm
   # git checkout <your-branch>
   

2. 安装运行环境
   如果使用 TPU，请激活对应 conda 环境并安装匹配版本的 torch、torch_xla。
3. 模型准备
   若使用自定义模型，确保配置文件放置正确且可访问。

1.2 配置（脚本顶部必须设置）

变量	说明	示例
BASE	vLLM 仓库所在目录的绝对路径	"$HOME"
MODEL	Hugging Face 模型名称	"meta-llama/Llama-3.1-8B-Instruct"
SYSTEM	硬件类型：TPU 或 GPU	"TPU"
TP	Tensor-parallelism 大小	1
DOWNLOAD_DIR	模型权重下载/缓存目录	""（默认路径）
INPUT_LEN	请求输入长度	4000
OUTPUT_LEN	请求输出长度	16
MAX_MODEL_LEN	模型最大长度	4096
MIN_CACHE_HIT_PCT	前缀缓存命中率要求，0–100；设为 0 禁用	60
MAX_LATENCY_ALLOWED_MS	允许的 P99 端到端延迟（ms）；设极大值可忽略	500
NUM_SEQS_LIST	待测 max-num-seqs 列表	"128 256"
NUM_BATCHED_TOKENS_LIST	待测 max-num-batched-tokens 列表	"1024 2048 4096"

短上下文场景可适当增大 max-num-seqs 值。

1.3 运行步骤

1. 配置：按上表在脚本顶部修改变量。
2. 执行：

   cd <脚本所在目录>
   bash auto_tune.sh
   

注意：执行路径中不能包含字符串 vllm，否则 pkill -f vllm 会误杀脚本自身。

---

2. 要点提炼

2.1 核心目标

• 自动遍历 max-num-seqs 与 max-num-batched-tokens 组合。
• 在满足延迟或缓存命中率约束的前提下，找到最大吞吐。

2.2 典型场景

目标	关键配置示例
仅最大化吞吐	MAX_LATENCY_ALLOWED_MS=1e11, MIN_CACHE_HIT_PCT=0
吞吐 + 延迟约束	MAX_LATENCY_ALLOWED_MS=500
吞吐 + 延迟 + 前缀缓存	MAX_LATENCY_ALLOWED_MS=500, MIN_CACHE_HIT_PCT=60

2.3 输出结果

• 位于 $BASE/auto-benchmark/YYYY_MM_DD_HH_MM/：
  • vllm_log_*.txt：各参数组合的 vLLM 日志
  • bm_log_*.txt：对应 benchmark 日志
  • result.txt：最优参数及吞吐汇总
  • profile/：最佳运行的一次 profiler trace（TPU 为 .xplane.pb，GPU 为 .json）

---

3. 如何调优 vLLM 运行参数（实战指南）

3.1 调优流程（脚本内部逻辑）

1. 确定最大 GPU 内存利用率
   从 0.98 开始递减，防止 OOM。
2. 双重循环遍历
   遍历所有 (max-num-seqs, max-num-batched-tokens) 组合。
3. 延迟感知吞吐搜索
   • 先以无限请求速率跑一轮；若 P99 延迟满足，则记录吞吐。
   • 若延迟超限，则逐步降低请求速率，找到满足延迟的最高吞吐。
4. 记录最优值
   每次更新吞吐更高的有效组合。
5. 保存性能画像
   对最佳组合保存 profiler trace，便于 TensorBoard 等工具深度分析。

3.2 手动微调建议

• 长输入 / 长输出场景
  • 适当降低 max-num-seqs，提高 max-num-batched-tokens，减少 padding 浪费。
• 短输入 / 短输出场景
  • 提高 max-num-seqs，降低 max-num-batched-tokens，充分利用并发。
• 显存紧张
  • 降低 gpu-memory-utilization 或 max-model-len。
• 延迟敏感
  • 在 MAX_LATENCY_ALLOWED_MS 范围内，优先选择吞吐最高的组合，若仍超限，则降低 max-num-seqs 或 max-num-batched-tokens。
• 前缀缓存优化
  • 若业务有大量共享前缀，可设置 MIN_CACHE_HIT_PCT>0，脚本会过滤掉命中率不达标的结果。

脚本已自动化上述过程；如想手动实验，可直接用 vllm serve 启动并配合 vllm bench serve 进行基准测试。