guidellm

SLO-aware Benchmarking and Evaluation Platform for Optimizing Real-World LLM Inference

Overview

GuideLLM is a platform for evaluating how language models perform under real workloads and configurations. It simulates end-to-end interactions with OpenAI-compatible and vLLM-native servers, generates workload patterns that reflect production usage, and produces detailed reports that help teams understand system behavior, resource needs, and operational limits. GuideLLM supports real and synthetic datasets, multimodal inputs, and flexible execution profiles, giving engineering and ML teams a consistent framework for assessing model behavior, tuning deployments, and planning capacity as their systems evolve.

Why GuideLLM?

GuideLLM gives teams a clear picture of performance, efficiency, and reliability when deploying LLMs in production-like environments.

• Captures complete latency and token-level statistics for SLO-driven evaluation, including full distributions for TTFT, ITL, and end-to-end behavior.
• Generates realistic, configurable traffic patterns across synchronous, concurrent, and rate-based modes, including reproducible sweeps to identify safe operating ranges.
• Supports both real and synthetic multimodal datasets, enabling controlled experiments and production-style evaluations in one framework.
• Produces standardized, exportable reports for dashboards, analysis, and regression tracking, ensuring consistency across teams and workflows.
• Delivers high-throughput, extensible benchmarking with multiprocessing, threading, async execution, and a flexible CLI/API for customization or quickstarts.

Comparisons

Many tools benchmark endpoints, not models, and miss the details that matter for LLMs. GuideLLM focuses exclusively on LLM-specific workloads, measuring TTFT, ITL, output distributions, and dataset-driven variation. It fits into everyday engineering tasks by using standard Python interfaces and HuggingFace datasets instead of custom formats or research-only pipelines. It is also built for performance, supporting high-rate load generation and accurate scheduling far beyond simple scripts or example benchmarks. The table below highlights how this approach compares to other options.

What's New

This section summarizes the newest capabilities available to users and outlines the current areas of development. It helps readers understand how the platform is evolving and what to expect next.

Recent Additions

• New CLI interface with improved configuration and validation.
• New backends for in-process vLLM Python API and websocket audio transcription.
• Multi-turn conversation capabilities for benchmarking chat agents and dialogue systems.
• Full tool calling support (client and server side) in chat completions and responses APIs.
• Synthetic video and image datasets for controlled experimentation.
• Replay of Mooncake trace files for realistic load testing.
• Support for benchmarking Geospatial LLMs.

Active Development

• Replay of OTEL and WEKA trace files.
• Improved scenarios for benchmarking standard workflows.
• Ability to stack scenario files for complex benchmarking workflows.
• Ability to override constraints for individual benchmarks in a profile.
• gRPC backend for benchmarking vLLM-native servers.

Quick Start

The Quick Start shows how to install GuideLLM, launch a server, and run your first benchmark in a few minutes.

Install GuideLLM

Before installing, ensure you have the following prerequisites:

• OS: Linux or MacOS
• Python: 3.10 - 3.13

Install the latest GuideLLM release from PyPi using pip :

pip install guidellm[recommended]

Or install from source:

pip install git+https://github.com/vllm-project/guidellm.git

Or run the latest container from ghcr.io/vllm-project/guidellm:

podman run \
  --rm -it \
  -v "./results:/results:rw" \
  -e GUIDELLM__SPEC__BACKEND='{"kind": "openai_http", "target": "http://localhost:8000"}' \
  -e GUIDELLM__SPEC__PROFILE='{"kind": "sweep"}' \
  -e GUIDELLM__SPEC__CONSTRAINTS='[{"kind": "max_duration", "seconds": 30}]' \
  -e GUIDELLM__SPEC__DATA='[{"kind": "synthetic_text", "prompt_tokens": 256, "output_tokens": 128}]' \
  ghcr.io/vllm-project/guidellm:latest

Published images are multi-arch (linux/amd64 and linux/arm64) for Docker, Podman, Kubernetes, and OpenShift. Prefer pinning a release tag in production:

Architecture-specific tags such as vX.Y.Z-amd64 / vX.Y.Z-arm64 are build artifacts — do not use them as the image reference.

Launch an Inference Server

Start any OpenAI-compatible endpoint. For vLLM:

vllm serve "neuralmagic/Meta-Llama-3.1-8B-Instruct-quantized.w4a16"

Verify the server is running at http://localhost:8000.

Run Your First Benchmark

Run a sweep that identifies the maximum performance and maximum rates for the model:

guidellm run \
  --backend kind=openai_http,target=http://localhost:8000 \
  --profile kind=sweep \
  --constraint kind=max_duration,seconds=30 \
  --data kind=synthetic_text,prompt_tokens=256,output_tokens=128

You will see progress updates and per-benchmark summaries during the run, as given below:

Inspect Outputs

After the benchmark completes, GuideLLM writes benchmarks.json and benchmarks.csv by default. The files are saved in the directory configured by GUIDELLM__DEFAULT_RESULTS_DIR, or in the current directory when the variable is not set. GuideLLM also prints a summary and the generated file locations to the console.

Specifying --output replaces the default JSON and CSV outputs. See output configuration for examples of selecting formats, including generating HTML alongside JSON and CSV.

Output Files and Reports

Use JSON or YAML for detailed analysis, CSV for spreadsheet comparisons, HTML for self-contained visual reports, and PLOT for static performance graphs. See supported file formats for their contents and default filenames, and configuring file outputs to choose output paths.

The console provides a summary of each benchmark. Its tables can be copied into spreadsheet software using | as the delimiter. See console output for progress and display controls.

Common Use Cases and Configurations

GuideLLM supports a wide range of LLM benchmarking workflows. The examples below show how to run typical scenarios and highlight the parameters that matter most. For a complete list of arguments, details, and options, run guidellm run --help.

Each registry-backed option uses the form --<option> kind=<TYPE>,<CONFIG>..., where CONFIG is key=value pairs. For more complex configurations, use JSON or YAML, e.g. --data '{"kind":"huggingface","source":"abisee/cnn_dailymail","load_kwargs":{"name":"3.0.0"}}'.

Load Patterns

Simulating different applications requires different traffic shapes. This example demonstrates rate-based load testing using a constant profile at 10 requests per second, running for 20 seconds with synthetic data of 128 prompt tokens and 256 output tokens.

guidellm run \
  --backend kind=openai_http,target=http://localhost:8000 \
  --profile kind=constant,rate=10 \
  --constraint kind=max_duration,seconds=20 \
  --data kind=synthetic_text,prompt_tokens=128,output_tokens=256

Key parameters:

• --profile kind=<type>: Defines the traffic pattern — synchronous, concurrent, throughput, constant, poisson, or sweep
• --profile kind=constant,rate=10: For constant/`poisson