[Misc][RFC] Add automated profiling sweep and heatmap visualization tools

[ConstBob]

Summary

This PR introduces a lightweight and automated profiling suite for vLLM, enabling kernel-level benchmarking across multiple batch sizes and prompt lengths, and visualizing the results as heatmaps.

It includes:

1. sweep_profiling.py: Automates profiling runs with varied batch and prompt configurations. In addition to the overall model runner time, we also generate the profiling result for operator breakdown.
2. plot_heatmap_from_traces.py: Parses JSON trace outputs and generates latency heatmaps.
3. profiling.py: A self-contained adaptation of examples/offline_inference/profiling.py, modified for sweepability and output compatibility.

For more detailed description for this RFC and PR, please see #17823 .

Usage

Example:

python sweep_profiling.py --model "deepseek-ai/DeepSeek-R1-Distill-Llama-8B" --max-tokens 80000 --tensor-parallel-size 2

This will generate multiple trace files like:

profiling_bs8_pl128.json
profiling_bs16_pl512.json
...

To visualize results:

python plot_heatmap_from_traces.py

Files Added

tools/profiler/
├── profiling.py                    # Adapted from examples/offline_inference/profiling.py
├── sweep_profiling.py              # Automates profiling.py across batch × prompt
├── plot_heatmap_from_traces.py     # Visualizes JSON traces as heatmaps

Notes

• Currently targets vLLM V0 only

Related Issue

FIX #17823

CC List

@GindaChen @JJMN22

[github-actions]

👋 Hi! Thank you for contributing to the vLLM project.

💬 Join our developer Slack at https://slack.vllm.ai to discuss your PR in #pr-reviews, coordinate on features in #feat- channels, or join special interest groups in #sig- channels.

Just a reminder: PRs would not trigger full CI run by default. Instead, it would only run fastcheck CI which starts running only a small and essential subset of CI tests to quickly catch errors. You can run other CI tests on top of those by going to your fastcheck build on Buildkite UI (linked in the PR checks section) and unblock them. If you do not have permission to unblock, ping simon-mo or khluu to add you in our Buildkite org.

Once the PR is approved and ready to go, your PR reviewer(s) can run CI to test the changes comprehensively before merging.

To run CI, PR reviewers can either: Add ready label to the PR or enable auto-merge.

🚀