vllm-omni/docs/contributing/profiling.md

Profiling vLLM-Omni

Performance Profiling Guidelines Profiling capabilities in vLLM-Omni are reserved for development and maintenance tasks aimed at temporal analysis of the codebase. Production use is strongly discouraged; enabling the profiler incurs a substantial overhead that negatively impacts inference latency.

Mechanism: vLLM-Omni implements cross-stage profiling via the PyTorch Profiler. To accommodate the architecture—where stages operate as distinct engine instances in separate processes—the profiling interface supports both holistic capturing (all stages) and targeted capturing (specific stages).

1. Enabling the Profiler

Before running your script, you must set the VLLM_TORCH_PROFILER_DIR environment variable.

export VLLM_TORCH_PROFILER_DIR=/path/to/save/traces

Highly Recommended: Limit Profiling to a Single Iteration
For most use cases (especially when profiling audio stages), you should limit the profiler to just one iteration to keep trace files small and readable.

export VLLM_PROFILER_MAX_ITERS=1

2. Offline Inference

For offlinie processing using OmniLLM, you can wrap your generate calls with start_profile and stop_profile().

Basic Usage(All Stages)

from vllm_omni import OmniLLM

omni_llm = OmniLLM.from_engine_args(engine_args)

# Start profiling all active stages
omni_llm.start_profile()

outputs = omni_llm.generate(prompts, sampling_params)

# Stop profiling and save traces
omni_llm.stop_profile()

Selective Stage Profiling The profiler is default to function across all stages. But It is highly recommended to profile specific stages by passing the stages list, preventing from producing too large trace files:

# Only profile Stage 1
omni_llm.start_profile(stages=[1])

# Stage 0 (Thinker) and Stage 2 (Audio Decoder) for qwen omni
omni_llm.start_profile(stages=[0, 2])

Examples:

1. Qwen-omni 2.5: https://github.com/vllm-project/vllm-omni/blob/main/examples/offline_inference/qwen2_5_omni/end2end.py

2. Qwen-omni 3.0: https://github.com/vllm-project/vllm-omni/blob/main/examples/offline_inference/qwen3_omni/end2end.py

3. Online Inference(Async)

For online serving using AsyncOmni, the methods are asynchronous. This allows you to toggle profiling dynamically without restarting the server.

from vllm_omni import AsyncOmni

# Inside an async function:
async_omni = AsyncOmni.from_engine_args(engine_args)

await async_omni.start_profile()

async for output in async_omni.generate(prompt, sampling_params, request_id):
    # Process outputs...
    pass

await async_omni.stop_profile()

4. Analyzing Omni Traces

After stop_profile() completes (and the file write wait time has passed), the directory specified in VLLM_TORCH_PROFILER_DIR will contain the trace files.

Output/
│── ...rank-0.pt.trace.json.gz   # GPU 0 trace (TP=2 Example)
│── ...rank-1.pt.trace.json.gz   # GPU 1 trace (TP=2 Example)
│       # Load these into Perfetto to visualize synchronization
│
│── profiler_out_.txt            # Summary tables (CPU/CUDA time %)

Viewing Tools: - Perfetto: (Recommended): Best for handling large audio trace files. - chrome://tracing: Good for smaller text-only traces.

Note: vLLM-Omni reuses the PyTorch Profiler infrastructure from vLLM.
For more advanced configuration options (memory profiling, custom activities, etc.), see the official vLLM profiler documentation: vLLM Profiling Guide