llm-serving-auto-benchmark

LLM Serving 自动化基准测试

概览

使用此技能比较 SGLang、vLLM、TensorRT-LLM 和 TokenSpeed 等 LLM 服务框架在相同模型和工作负载下的表现。

采用配置驱动的工作流：

• 将仅用于启动的容量选项放在各框架的 base_server_flags 中
• 将搜索参数放在 search_space 中
• 为每个框架运行相同的数据集场景
• 根据 search_space 生成数量受限的候选列表，并将基线候选项排在首位
• 在结果文件中保留失败的候选项
• 规范化结果后，选出符合 SLA 的最佳候选项

对于特定模型的起始配置，优先使用随附的 configs/cookbook-llm/ 配置。这些配置定义了一组与框架无关的 LLM 服务示例模型，并将每个条目转换为框架原生的 SGLang、vLLM、TensorRT-LLM 和 TokenSpeed 服务标志。正式运行前，请验证这些配置：

python skills/llm-serving-auto-benchmark/scripts/validate_cookbook_configs.py \
  skills/llm-serving-auto-benchmark/configs/cookbook-llm/*.yaml

如果已捕获目标环境的 --help 文件，请添加 --help-dir <artifact-help-dir>。此检查只会加载配置、验证服务标志名称并渲染候选命令；不会启动模型服务。

在能提供更好覆盖范围时，优先使用原生工具：

• SGLang：当前公开示例使用 sglang serve；仍接受 python -m sglang.launch_server。优先使用 python -m sglang.benchmark.serving
• vLLM：进行服务参数扫描时使用 vllm bench sweep serve，否则使用 vllm serve 和 vllm bench serve
• TensorRT-LLM：使用 trtllm-serve 启动兼容 OpenAI 的服务，并搭配 TensorRT-LLM 服务基准测试客户端或通用的兼容 OpenAI 基准测试客户端
• TokenSpeed：使用 tokenspeed serve 启动兼容 OpenAI 的服务，并搭配 vllm bench serve --backend openai-chat，或搭配用于其他框架的同一兼容 OpenAI 基准测试客户端

此技能对 TensorRT-LLM 有一条硬性范围规则：当前服务仅支持 PyTorch；旧版镜像必须选择 pytorch。不要搜索 TensorRT-LLM 后端选项。如果请求、配置或候选项要求使用 trt、引擎后端或其他非 PyTorch TensorRT-LLM 服务后端，请将该候选项判定为此技能不支持，并记录原因。这不会改变基准测试客户端后端；TensorRT-LLM 基准测试客户端仍使用 --backend openai 或 --backend openai-chat 等兼容 OpenAI 的模式。

只有在每个请求的框架都完成主要服务参数调优后，才能选出优胜者。

框架选择由调用方控制。如果调用方明确提供框架列表，只对列表中启用的框架进行基准测试。不要仅仅因为存在示例配置或历史文档，就擅自加入 TensorRT-LLM 或 TokenSpeed；应将省略的框架记录为用户排除，而不是不支持。

此技能中的参数列表不构成兼容性承诺，而是对受版本影响的候选参数类别的说明。每次正式运行前，都要记录确切的框架版本或 git 提交，并在目标环境中使用 --help 验证具体的 CLI 标志名称。

默认搜索方式与框架无关：从基本采用纯 TP 的基线开始，扫描少量影响较大的运行时参数，并将首轮搜索的每个框架候选项数量控制在 10 个左右。默认不搜索内存占用比例。

来源与实验约定

当前的分析器 API、分支特定默认值和 KV 容量计算语义，请参阅 2026-09-18 来源约定。合并 PR 或声称内核性能／精度等效之前，请参阅 paired-validation.md。该文档区分了纯代码 A/B 测试与部署调优、真实与模拟验收，以及交互性与总体输出吞吐量。计时后进行分析，以确认候选后端确实已运行。

验证环境

此技能与目标无关。它假设以下任一环境可用，且不需要其他条件：

• 配有 Docker/Podman，且已拉取目标框架镜像的本地 GPU 主机；
• 通过 ssh <host> 连接、且框架镜像已在容器中运行的远程 GPU 主机；
• 可对每个框架的预构建镜像执行命令的 CI 运行器。

不要假设此技能自身的工作流中存在特定的运维主机名。特定机器的 SSH 配置、容器名称、工作区路径和 HF 令牌传递方式由运维侧的每主机技能负责；此技能只要求调用方能够进入一个安装了所需框架的容器 shell。

参考文件是可选的，且对版本敏感。应将历史标志说明视为来自某个镜像的证据，而非下一次运行的兼容性保证。

2026-05-01（H100）和 2026-06-27（B200）的历史冒烟验证测试了小型服务和搜索工作负载。B200 镜像仅提供 SGLang；缺少 vLLM/TRT-LLM/TokenSpeed CLI 属于环境缺失。这些运行结果不是当前的跨框架速度或准确性结果。9 月的源代码刷新运行的是离线工具，而非新的 GPU 测试矩阵。

技能范围

此技能是一套操作手册和配置及验证工具链，并非开箱即用的编排器。操作人员仍需启动服务、运行工作负载，并为每个候选项写入一行规范化 JSONL。

scripts/ 目录中恰好包含两个工具：

• validate_cookbook_configs.py：加载 cookbook YAML，渲染有限范围的候选服务命令，并根据捕获的 --help 快照检查标志名称，但不启动服务。
• compare_benchmark_results.py：将规范化的每候选项 JSONL 转换为 Output Contract 中所述的 Markdown 表格和可选 CSV 表格。

configs/cookbook-llm/ 下的 cookbook 配置必须通过验证器。较短的 references/example-plan.yaml 是一次性运行计划骨架，不要求其原样通过验证。请将 references/result-schema.md 作为 SLA 键名称的唯一事实来源。

必需输入

长时间运行前，请收集以下信息：

• 模型和分词器路径、目标框架、GPU 型号和数量、多节点许可、精度及量化限制
• 端点形态、工作负载来源、数据集场景、SLA 目标、搜索预算和产物输出目录
• 版本清单：框架软件包版本或 git 提交、容器/Python 环境、--help 快照，以及每个搜索参数是否被对应的 CLI 接受

如果目标是真实生产流量，请使用真实请求分布。合成工作负载适用于环境启动和初步比较，但不足以作为生产选择的依据。

在规范化结果行中记录每个场景的输入/输出长度分布。这是分析器交接约定的一部分：当某个框架速度较慢，后续调查调用 llm-torch-profiler-analysis 时，分析器工作负载必须重用较慢基准测试场景的长度，而不能回退到通用的预填充 4090->1 和解码 1->2048 默认值。

对版本敏感的部署检查

• 查阅上游源码契约，了解确切的检查版本。保留已安装镜像中的 --help 输出和实际生效的环境变量值；不要沿用历史版本的默认值。
• 检查的提交中，SGLang main 和 dsv4.1 对 FlashInfer 融合 finalize 的处理不同。数值默认值的变化是实验的一部分，不是噪声。 当前内核目录为 python/sglang/kernels/{aot,jit,ops}。
• SGLang 的原生 /generate 路径与 OpenAI 兼容路径属于不同的基准测试通道。比较框架时，使用相同的端点和客户端；任何原生客户端结果都应单独标注。
• 根据 GPU 架构和数据类型，匹配注意力/GEMM 后端支持情况。 “Blackwell”涵盖不同的 SM 目标；B200/GB300/RTX 5090 并不共用一套可互换的后端契约。请在已安装的代码中验证支持情况。
• vLLM DBO 依赖受支持的 all-to-all 后端。编译融合取决于平台、图分区和数据类型守卫。请参阅融合参考确认分派情况。
• 当前的 TensorRT-LLM 通道使用 trtllm-serve serve <model>；较旧的镜像可能需要 --backend pytorch。 服务端后端与 OpenAI 基准测试客户端后端不同。请根据选定的 CLI 验证模型格式、KV 内存标志的拼写以及随机数据集采样选项；不要悄悄改用其他数据集。
• TokenSpeed 使用 tokenspeed serve <model> 和通用的 OpenAI 兼容客户端。 其 TP/注意力-TP/MoE-TP/EP 和内存标志需要单独解读； SGLang/vLLM 中名称相似的选项并不保证含义相同。
• 每个最大上下文候选值都必须覆盖所有场景中的 max(input_len + output_len)，而不只是基线场景。配方验证器会检查这一点。
• 计时后再进行性能分析。对于固定的模拟接受率曲线，应明确标注；模型准确性测试则应重启并使用真实接受率模式。端到端分数恰好相同时，也绝不要因此启用未使用的替代内核。

密钥安全

• 绝不要将 HF_TOKEN、HUGGINGFACE_HUB_TOKEN 或任何上游 API 密钥写入已保存的产物。通过容器 -e VAR 传入（右侧不加引号，以继承主机上的值），并确保写入结果 JSONL 的 server_command 和 benchmark_command 字段中不包含这些密钥。
• 如果某个框架在启动时会回显完整 argv，请在上传产物前清理日志，或对看起来像令牌的子串进行脱敏。

公平性规则

在整个基准测试中遵循以下规则：

• 所有框架都使用相同的 GPU 类型、GPU 数量、模型权重、分词器、精度、量化策略、提示词分布、输出长度目标和采样设置。
• 记录框架版本、git 提交、容器镜像、CUDA/NCCL 版本、GPU 驱动、可见 GPU ID、启动命令和基准测试命令。
• 测量前预热服务。若缓存效应会使比较产生偏差，则在测试不同候选配置之间重启服务或清除状态。
• 将稳态固定 QPS 测试与突发吞吐量测试分开比较。
• 在最终结果中保留失败的候选项，并注明失败原因。
• 同时报告原始吞吐量和满足 SLA 的吞吐量。失败候选中速度最快的，并不代表它是最佳部署命令。

工作流

1. 预检

开始搜索前，验证 SGLang 及所有指定的对比框架。 仅运行指定框架集合对应的命令：

sglang serve --help
python -m sglang.launch_server --help
python -m sglang.benchmark.serving --help
vllm serve --help
vllm serve --help=all
vllm bench serve --help
vllm bench serve --help=all
vllm bench sweep serve --help=all
trtllm-serve serve --help
python -m tensorrt_llm.serve.scripts.benchmark_serving --help
tokenspeed serve --help
vllm bench serve --help

以目标环境中针对各框架的 --help 输出为准。不要仅仅因为旧笔记中有过某个启动标志，就继续使用已过时的标志。

vLLM 0.19 及更高版本使用分组帮助信息。普通的 vllm serve --help 只会显示分组，因此在判断某个搜索参数是否存在前，先捕获 --help=all 输出。

将这些 --help 输出保存到本次运行的产物目录中。如果当前 CLI 中缺少某个列出的搜索参数，请在运行基准测试前删除该参数或将其转换为可用参数。不要静默传入未知标志。

记录 trtllm-serve serve --help。当前 main 仅支持 PyTorch；省略已弃用的后端选项。对于列出多个后端的旧版镜像，请选择 --backend pytorch。

对于 TokenSpeed，确认服务和基准测试入口点，因为某些安装会将二进制文件别名为 ts。在 server_command 中记录实际使用的二进制文件。

对于每个框架，启动一个最小化服务，确认 /v1/models 或原生模型信息端点，发送一个流式请求，运行一个至少包含 5 个请求的小型基准测试，然后保存启动命令、基准测试命令、服务日志和基准测试输出。

进行任何使用 GPU 的冒烟测试前，直接使用 nvidia-smi 检查指定的 GPU ID。如果指定的 GPU 已在使用，请停止并记录这一情况。进行性能对比时，不要静默改用不同数量的 GPU。只有在结果明确标注为流程检查而非公平的吞吐量对比时，才可以使用一张 GPU 进行规模更小的冒烟测试。

如果目标环境通过容器运行，请遵循 references/container-runbook.md，并保存镜像标签、拉取命令、启动和基准测试日志，以及清理命令。

2. 规范化工作负载

所有框架都使用同一个规范工作负载。建议的 JSONL 行格式：

{"prompt": [{"role": "user", "content": "Summarize this text."}], "output_len": 256}
{"prompt": "Write a short explanation of CUDA graphs.", "output_len": 128}

可选字段：

{
  "prompt": [{"role": "user", "content": "Use low temperature."}],
  "output_len": 256,
  "extra_request_body": {"temperature": 0.0, "top_p": 0.95},
  "metadata": {"source": "prod-sample"}
}

转换用户数据时：

• 转换前至少检查 3 行
• 在 extra_request_body 中保留请求级采样选项
• 如果最终助手回答是目标补全内容，不要将该回答包含在提示词中
• 仅当所有指定框架都支持所选端点格式时，才保留多模态或工具调用负载

进行合成环境启动时，使用随附的双场景格式：

dataset:
  kind: random
  num_prompts: 80
  scenario_names: [chat, summarization]
  input_len: [1000, 8000]
  output_len: [1000, 1000]

每组对齐的 input_len / output_len 都是一个场景。除非用户要求，否则不要计算笛卡尔积。 为每个场景命名，并在产物中保留对齐后的数值对。对于自定义数据集，请计算或记录具有代表性的 input_len 和 output_len 分桶；条件允许时至少记录 p50 和 p95，以便后续分析器运行可以针对较慢的分桶，而不是分析无关的合成格式。

搜索任何序列长度上限前，先计算数据集中最大的 input_len + output_len。对于所有预期能运行全部场景的候选项，SGLang context_length、vLLM max_model_len、TensorRT-LLM max_seq_len 和 TokenSpeed max_model_len 都必须不小于该值。

3. 选择搜索层级

使用能够回答用户问题的最小层级：

• 层级 1：冒烟和基本检查。一个基线配置，加上少数几个影响较大的参数。
• 层级 2：默认。对最可能的服务端设置进行范围有限的扫描。
• 层级 3：穷举。仅当搜索空间已经很小，且用户接受长时间运行时使用。

默认预算：

• 默认跨框架比较使用 num_prompts: 80；每个场景使用 num_prompts: 20 进行冒烟／流程检查也可以，但必须在产物中标注为此类检查（而非性能结果）。
• 首轮有效测试使用 search.max_candidates_per_framework: 10
• 候选项生成：先测试基线配置，然后根据 search_space 生成范围有限的组合或有序候选项列表
• 除非用户要求更多，否则最多进行 5 轮 QPS 搜索
• 如果某个框架的所有候选项都明显会 OOM 或未通过基本健康检查，则提前停止

除非用户明确想研究容量或内存，否则请将以下设置保留在 base_server_flags 中：

• SGLang mem_fraction_static
• SGLang schedule_policy
• vLLM gpu_memory_utilization
• TensorRT-LLM kv_cache_free_gpu_memory_fraction
• TokenSpeed gpu_memory_utilization

这些都是真实的参数，但会迅速扩大搜索范围，而且往往会让服务性能比较变成内存限制研究。

4. 调优 SGLang

手动启动每个 SGLang 候选项。自动基准测试模块已在 #31941 中移除。

使用当前服务客户端进行基准测试：

python -m sglang.benchmark.serving \
  --backend sglang \
  --dataset-name random \
  --random-input-len 1024 \
  --random-output-len 256 \
  --num-prompts 80 \
  --request-rate 8 \
  --output-file /path/to/sglang/results.json \
  --output-details

需要核实的、随版本变化的 SGLang 参数族：

• tp_size、pp_size、dp_size（副本数）、attn_dp_size、ep_size
• attention_backend、prefill_attention_backend、decode_attention_backend
• sampling_backend
• max_running_requests、max_queued_requests
• chunked_prefill_size、prefill_max_requests、max_prefill_tokens
• max_total_tokens、page_size
• 阶段专用的 CUDA 图设置
• 仅在非推测基线配置完成调优后，才调整推测解码或 EAGLE 设置

在默认测试中，请将 mem_fraction_static 和 schedule_policy 固定，以匹配共享的配置指南样式。

对于快速冒烟测试，如果目标仅是验证框架流程，请使用 --cuda-graph-backend-decode disabled 和 --cuda-graph-backend-prefill disabled。在产物中记录这些参数。除非用户要求调优 eager 模式服务，否则不要在性能优胜配置中沿用这些冒烟测试设置。

5. 调优 vLLM

如果可用，请使用 vLLM 的扫描运行器：

vllm bench sweep serve \
  --serve-cmd 'vllm serve <model> --port 8000' \
  --bench-cmd 'vllm bench serve --backend vllm --model <model> --port 8000 --dataset-name random --num-prompts 80' \
  --serve-params /path/to/vllm_serve_params.json \
  --bench-params /path/to/vllm_bench_params.json \
  --output-dir /path/to/vllm_results

如果不支持扫描，请为每个候选项运行 vllm serve，并使用 vllm bench serve 进行测量。

需要核实的、随版本变化的 vLLM 参数族：

• 张量、流水线、数据、解码上下文和专家并行
• gpu_memory_utilization
• max_num_seqs
• max_num_batched_tokens
• max_model_len
• enable_chunked_prefill、long_prefill_token_threshold 和 DBO 阈值
• KV 缓存数据类型和块大小
• 数据类型和量化设置
• 相关时的 CUDA 图捕获大小或 eager 模式开关
• 仅在工作负载需要时，才调整前缀缓存和推测解码设置

vLLM 应进行常规扫描，而不是只运行一条基线命令。原生命令模板和跨框架参数族请参阅 references/framework-reference.md。运行前，请根据目标镜像的 --help 确认每个参数。

默认测试中，请将 gpu_memory_utilization 保留在基线配置中。仅当问题明确涉及模型适配或容量与吞吐量之间的权衡时，才搜索此参数。

除非目标 vLLM 环境已配置好 DBO 和 all2all 后端，否则请不要在默认测试中加入这些设置。它们都是有效的调优参数，但如果所需的 all2all 后端不可用，候选项可能会在启动时失败。添加 long_prefill_token_threshold 进行搜索之前，请先在具体的 vllm serve --help=all 输出中确认该参数。

6. 调优 TensorRT-LLM

当目标环境支持时，使用 trtllm-serve serve 作为服务入口：

trtllm-serve serve <model> \
  --tp_size <tp> \
  --pp_size <pp> \
  --kv_cache_free_gpu_memory_fraction 0.75 \
  --host 0.0.0.0 \
  --port 8000

然后使用 TensorRT-LLM 服务基准测试客户端，或用于其他框架的同一 OpenAI 兼容客户端，对 OpenAI 兼容端点进行基准测试。

在历史版本的 TensorRT-LLM 1.0.0 验证镜像中，benchmark_serving --dataset-name random 会从 ShareGPT 中抽样，除非传入 --download-path 或 --random-ids。若要快速进行合成冒烟测试，请传入 --random-ids，然后在目标 TensorRT-LLM 镜像上确认其行为。

TensorRT-LLM 的标志名称尤其容易随版本变化。历史上，在经过验证的 TensorRT-LLM 1.0.0 镜像中，trtllm-serve serve 接受的 KV 缓存内存标志是 --kv_cache_free_gpu_memory_fraction，而不是 --free_gpu_memory_fraction。已于 2026-10-05 重新检查当前主线版本 bb367fc8c1adf6e2c28c88cb1a8b46e1742a9d60。在任何 GPU 目标上运行搜索前，请务必使用 trtllm-serve serve --help 验证标志。

此技能的 TensorRT-LLM 后端策略：

• 启动当前仅支持 PyTorch 的服务时，不使用已弃用的后端选项
• 仅将 backend: pytorch 用作旧镜像的兼容性设置
• 不要将 backend 加入 search_space
• 对 trt、基于引擎的服务或任何其他非 PyTorch TensorRT-LLM 服务后端，均应判定为此技能不支持

需要验证的、随版本变化的 TensorRT-LLM 参数类别：

• tp_size、pp_size 和 ep_size
• 最大批次大小、最大序列长度、最大令牌数和 KV 缓存预算
• 连续批处理和调度器选项
• trtllm-serve 在 PyTorch 后端中使用的额外 LLM API 选项 YAML

与 SGLang 或 vLLM 相比，trtllm-serve serve CLI 直接暴露的运行时参数更少。存在直接标志时，请优先使用；对于不是顶层 CLI 标志的 PyTorch 后端设置，则使用 --extra_llm_api_options。将不受支持的后端或引擎请求保留在失败表中，不要转换它们。

默认运行时，将 kv_cache_free_gpu_memory_fraction 保留在基线配置中。首先搜索 max_batch_size、max_num_tokens、max_seq_len 和经过验证的 PyTorch 后端配置选项。服务后端固定为 pytorch。

7. 调优 TokenSpeed

将 TokenSpeed 作为一流的对比框架，尤其适用于 Agent 式或多轮工作负载；在这类场景中，它可能是最强的非 SGLang 基线：

tokenspeed serve <model> \
  --host 0.0.0.0 \
  --port 8000 \
  --tensor-parallel-size <tp> \
  --gpu-memory-utilization 0.90 \
  --max-model-len 12288 \
  --max-num-seqs 64 \
  --chunked-prefill-size 8192 \
  --kv-cache-dtype auto \
  --trust-remote-code

基准测试可使用通用的 OpenAI 兼容基准测试客户端：

vllm bench serve --backend openai-chat \
  --base-url http://127.0.0.1:8000 \
  --model <model> \
  --dataset-name random \
  --random-input-len 1024 \
  --random-output-len 256 \
  --num-prompts 80

也可使用用于其他框架的同一 OpenAI 兼容客户端。当 TokenSpeed 很可能表现领先，且需要交接给分析器时，控制服务端可针对相同请求形态启用 torch 分析（CONTROL_PORT 默认为服务端口 + 1；可使用 --control-port 覆盖）：

curl -X POST "http://127.0.0.1:${CONTROL_PORT}/start_profile" \
  -H 'Content-Type: application/json' \
  -d '{"output_dir":"/artifacts/tokenspeed_profile","num_steps":5,"activities":["CPU","GPU"],"with_stack":true,"profile_id":"ts-bench"}'
# Drive the same workload with the common client, then POST /stop_profile if needed.

如果未提供 output_dir，TokenSpeed 会将文件写入 TOKENSPEED_PROFILER_DIR 指定的位置，默认为 /tmp。

对于大型 MoE 或 Agent 式检查点，在将以下参数加入搜索前，请先验证：

• tensor_parallel_size、attn_tp_size、moe_tp_size 和 enable_expert_parallel
• attention_backend、drafter_attention_backend、moe_backend 和 draft_moe_backend
• max_num_seqs、chunked_prefill_size、max_prefill_tokens 和 max_total_tokens
• kv_cache_dtype、quantization 和前缀缓存控制项
• speculative_algorithm、speculative_num_steps 和 speculative_num_draft_tokens 等推测解码标志
• 仅在目标镜像上完成冒烟测试后，才使用 comm_fusion_max_num_tokens、enable_allreduce_fusion 和相关的通信融合标志

如果存在适用于同一模型系列的 TokenSpeed 原生 Agent 式配置，请将其作为额外的工作负载通道运行，而不是用它替换跨框架通用场景。使用相同架构规范化其结果行，并按实际情况设置 workload.kind。

默认运行时，将 gpu_memory_utilization 固定不变。仅当用户明确要求进行容量研究时，才搜索此参数。

8. 规范化结果

按照 references/result-schema.md 中的架构，为每个候选项写入一行 JSONL。然后运行：

python skills/llm-serving-auto-benchmark/scripts/compare_benchmark_results.py \
  --input /path/to/candidates.jsonl \
  --output /path/to/summary.md

按以下顺序对候选项排序：

1. 通过 SLA
2. 请求吞吐量或有效吞吐量最高
3. 输出 token 吞吐量最高
4. p50 TTFT 较低
5. p50 TPOT/ITL 较低
6. 性能接近时，GPU 数量较少或部署更简单

SLA 门槛本身保持不变。在 cookbook 配置和规范化结果架构中，TTFT SLA 仍使用 max_p50_ttft_ms，TPOT SLA 仍使用 max_p50_tpot_ms；只有跨候选项比较的默认顺序改为 p50 TTFT 和 p50 TPOT。

输出约定

返回一份精简报告，包含工作负载/SLA、硬件和框架版本、各框架/场景下最佳部署命令表、一张跨框架比较表、获胜方案的准确启动和基准测试命令，以及工作负载、原始/规范化结果、CSV 或 Markdown 摘要和服务端日志的产物路径。

当 SGLang 未获胜时，附上分析器交接说明，注明运行缓慢的 SGLang 场景名称，以及要传递给 llm-torch-profiler-analysis 的准确输入/输出长度或百分位区间。

当候选项使用推测解码、前缀缓存、卸载或 Agent 工作负载时，记录可选的规范化字段，包括接受长度、调度器前耗时、缓存命中率和内存驻留情况。如果存在这些列，摘要脚本会显示它们。

列出失败或排除的候选项及原因。说明此表记录的是尝试过但未被选中的配置：候选项可能失败、因策略而跳过，或虽已完成但未达到 SLA。对于合成工作负载、未完成的公平搜索或特定于框架的参数替换，添加注意事项。

如需命令模板、源链接或参数族映射，请使用 references/framework-reference.md。完整的跨框架运行计划请以 references/example-plan.yaml 为起点。

界面审计 — 2026-10-05

SGLang 的规范客户端是 python -m sglang.benchmark.serving；bench_serving 是已弃用的兼容封装，自动基准测试模块已被移除（#31941）。请从目标镜像中获取 sglang serve --help 和客户端帮助信息。当前镜像要求 CUDA 13 及兼容的主机驱动（#38404）；最后一个 CUDA 12 标签是 v0.5.19-cu129。MiniMax-M3 需要 lmsysorg/sglang:dev-minimax-m3； Qwen3.8-Flash-Next H200/B200 需要 lmsysorg/sglang:qwen38flashnext。

当前 SGLang 使用按阶段区分的图标志（#38375）： --cuda-graph-backend-decode / --cuda-graph-backend-prefill 接受 full、breakable、tc_piecewise、disabled；捕获大小使用 --cuda-graph-bs-decode / --cuda-graph-bs-prefill 和 --cuda-graph-max-bs-decode / --cuda-graph-max-bs-prefill。冒烟测试的 eager 模式为 --cuda-graph-backend-decode disabled --cuda-graph-backend-prefill disabled。 旧的大小别名已被移除，--disable-cuda-graph 已弃用。 在主分支上，--attn-dp-size 替代了旧的 attention-DP 参数对（#41818）； --dp-size 仍表示副本 DP。v0.5.21 早于这一参数命名：请检查镜像帮助信息。 调优时还要检查 --attn-cp-size、--dcp-size、--moe-dp-size 和 --ep 别名。

在 bb367fc8 版本中，TensorRT-LLM 在 #19028 之后仅支持 PyTorch。--backend pytorch 是已弃用的兼容选项；在当前主分支上应省略它，仅在帮助信息列出其他后端的旧镜像上选择该选项。 --free_gpu_memory_fraction（主要选项）和 --kv_cache_free_gpu_memory_fraction （别名）均可使用。1.0.0 镜像说明已属历史信息。--cluster_size 已弃用且不受支持。 --set PATH=YAML_VALUE 可在 --config 之后覆盖配置路径。

TokenSpeed #1236 移除了其基准测试子命令。对于对齐的工作负载，请使用通用客户端 vllm bench serve --backend openai-chat。ts 仍是 tokenspeed 的别名。禁用前缀缓存的选项是 --disable-prefix-caching；引擎标志 --api-key、--enable-cache-report、 --skip-server-warmup、--warmups 已被移除。--tool-call-parser 和 --chat-template 是网关标志。调优并行度时，请检查 --pipeline-parallel-size、 --prefill-context-parallel-size、--decode-context-parallel-size、 --lm-head-tp-size 和 --dense-gemm-backend。

不要强制指定 vLLM --block-size 16：这会排除首选的 MLA/DSA 后端。让后端自行选择块大小，并记录其启动时的分派行。 对比的各行数据应使用相同版本的客户端：vLLM #55508 更改了聊天 TTFT/E2E 分块统计方式，而 SGLang #39889 报告的服务器提示词令牌用量包含模板令牌。单独记录可选的客户端排队延迟。 SGLang 的默认调度器是 FCFS；历史 cookbook YAML 不再对随机提示词强制使用 LPM。对于默认开启的布尔选项，False 必须对应明确的关闭标志，且不得悄悄重复基线配置。YAML 验证器要求 Python 3.10 或更高版本。

源代码依据：SGLang 图标志， SGLang 并行标志， vLLM 后端尺寸设置， TensorRT-LLM 服务， TokenSpeed CLI。