TokenSpeed性能调优实战：启动计时分析、基准测试与瓶颈定位全攻略

TokenSpeed性能调优实战：启动计时分析、基准测试与瓶颈定位全攻略

【免费下载链接】tokenspeedTokenSpeed is a speed-of-light LLM inference engine.项目地址: https://gitcode.com/gh_mirrors/to/tokenspeed

TokenSpeed 是一款面向智能体（agentic）工作负载的光速级 LLM 推理引擎，其性能调优离不开三件事：启动计时分析、基准测试与瓶颈定位。本文将带你从零开始，用 TokenSpeed 内置的启动计时、内核基准套件和端到端压测配置，快速定位服务慢在哪里、快在哪里，是新手入门性能调优的完整指南。

上图：TokenSpeed 与 TensorRT-LLM 在 Kimi K2.5（B200）agentic 负载下的 Pareto 性能对比曲线

一、启动计时分析：用启动计时定位服务启动慢在哪

大模型服务启动慢是常见问题：权重加载慢？图捕获卡住？内核自动调优太久？TokenSpeed 提供了开箱即用的启动计时分析工具。

1. 一键开启启动计时

启动服务时只需设置环境变量，让运行时日志输出结构化的startup_timing记录：

TOKENSPEED_STARTUP_TIMING=1 tokenspeed serve <模型路径> ...

该开关默认关闭，插桩不做任何设备同步或分布式通信，对启动过程几乎零侵入（实现见 startup_timing.py）。

2. 读懂 15 个启动阶段

调度器会把启动过程切成清晰的阶段（spans），每个阶段输出起止时间戳、耗时与成功/错误状态：

完整阶段定义见官方文档 startup-timing.md，相关单测在 test_startup_timing.py。

3. 找关键路径的三个诀窍 🎯

• 看最慢的 rank：多卡部署时，用最慢 rank 的墙钟时间确定关键路径；
• 区分冷/热编译缓存：对比编译缓存冷启动与热启动两次运行，注意保留各后端缓存目录；
• 验证真实请求：就绪（readiness）不等于可用，还要验证第一个真实请求与稳态行为——把编译"挪到服务期"不算真正的启动优化。

二、内核基准测试：精确测量每一个算子

服务级指标之外，TokenSpeed 提供了独立于引擎的内核基准测试套件，覆盖 GEMM、注意力、MoE 等算子族。

1. 基准框架如何工作

基准框架将"算子输入构造与正确性校验"和"共享设备计时"解耦：

• 计时只测设备时间：输入生成、编译、图捕获、正确性检查都不计入报告时间；
• 正确性先行：先与注册的参考解对比，通过后才计时，失败则不产出测量结果；
• 回归判定用中位数 + 离散度：只有中位减速同时超过相对与绝对阈值才判定为回归，噪声过大的运行标记为"不确定"而非误报。

设计细节完整收录在 benchmarks/README.md。

上图：AMD 平台上 MoE 算子的内核性能对比，来自 tokenspeed-kernel-amd 性能测试

2. 运行基准套件只需两条命令

硬件套件按<vendor>/<arch>.json组织（如 gfx950.json）。在仓库根目录运行单次基准：

python3 -m tokenspeed_kernel.benchmark.ci \ --suite tokenspeed-kernel/benchmarks/amd/gfx950.json \ --revision "$(git rev-parse HEAD)" \ --output /tmp/tokenspeed-kernel-result.json

要做两个版本之间的回归对比，用 kernel_benchmark_ci.py 自动为基线与候选各建独立环境：

python3 test/ci_system/kernel_benchmark_ci.py \ --base-ref <基线提交> --candidate-ref <候选提交> \ --output-dir /tmp/tokenspeed-kernel-benchmark

输出包含逐版本 JSON 结果、结构化对比和 Markdown 摘要。回归策略取自 merge-base 套件，候选版本无法通过改阈值放宽自己的门禁——这是基准可信的关键设计。

三、端到端压测：随机负载与智能体负载

1. 随机负载压测：最通用的性能基准

CI 中使用 EvalScope 对服务发起random数据集压测，典型参数：固定输入/输出长度（如 4k 输入、1k 输出）、并发从 1 逐步拉高、带 warmup、temperature 0保证可复现。一份完整配置可参考 kimi-k3-mxfp4-tp8ep1-evalscope-random-4k-1k-mi35x.yaml。

压测结束后，collect_outputs.py 把所有轮次的benchmark_summary.json汇总成一张表，核心指标包括：

2. 智能体负载压测：更贴近真实生产

agentic 场景是 TokenSpeed 的主场。agentic 压测配置 使用swe_smith数据集做多轮对话压测，先跑一轮 warmup 再正式测量，并开启 MTP 投机解码等生产同款参数——这样测出的 TPS 才能代表真实 agentic 工作负载表现。

上图：TokenSpeed-MLA 解码延迟对比（numHead=32），展示注意力内核调优带来的收益

3. 用 perf_reference 守住性能底线

每个压测配置都带perf_reference基线与perf_threshold（如 0.9）：任一并发点的实测值低于基线 × 阈值即门禁失败。基线约定为最近三次通过运行的中位数向下取整，避免一次毛刺拉高门槛。这套"基线 + 阈值"机制让性能回归在提交阶段就被拦截。

四、瓶颈定位实战：一张对照表

上图：AMD 平台注意力算子性能对比，注意力往往是长上下文解码的性能瓶颈

拿到启动计时与压测数据后，按这张表快速归因：

📌 调参时遵循 launching.md 的检查清单：先固定--max-model-len、--kv-cache-dtype、--gpu-memory-utilization，再调并发与并行度；基准与生产运行务必显式指定 attention/moe 后端，保证结果可复现。更多并行策略见 parallelism.md。

五、小结

TokenSpeed 的性能调优是一条清晰的流水线：启动计时（TOKENSPEED_STARTUP_TIMING=1）拆解冷启动 →内核基准套件定位算子级回归 →端到端随机/agentic 压测验证服务级指标 → 用perf_reference门禁守住底线。三层数据相互印证，瓶颈基本无处遁形。建议从官方文档 startup-timing.md 与 benchmarks/README.md 开始，结合自己的模型与硬件跑一轮完整流程，你会发现调优并没有想象中那么难。

【免费下载链接】tokenspeedTokenSpeed is a speed-of-light LLM inference engine.项目地址: https://gitcode.com/gh_mirrors/to/tokenspeed