Benchmark requirements
Write a benchmark contract that another engineer can reproduce without verbal context
Before you begin
Follow a linked prerequisite when you cannot explain it from memory. Background skills without links are stated as abilities rather than hidden terminology.
- Rate and latency units
- Basic statistics
Suppose two inference engines report 2,000 generated tokens per second on the same GPU. The numbers still cannot be compared until you know prompt lengths, output lengths, concurrency, model format, decoding policy, cache state, and latency constraints. One engine may have processed short prompts in an offline batch. The other may have served a Poisson arrival stream while meeting a p99 latency limit.
A benchmark specification makes these conditions part of the result. The written record defines the engineering decision, the sampled requests, the server and GPU software, the points where timing begins and ends, the statistics, and the allowed output differences. Writing the specification before the comparison prevents the experiment from changing its definition of success after the faster-looking number appears.
The worked investigation compares two engines for a 7-billion-parameter decoder under a replay of recorded prompt and output lengths. A load generator supplies timestamped requests, server logs record queue and completion times, and per-request result files preserve latency and error observations. The comparison is valid for capacity planning only after both engines meet the same quality and latency requirements at a stable offered load.
State the decision
A benchmark for kernel development asks whether one implementation reduces device time for a defined shape family while preserving numerical behavior. A benchmark for hardware selection asks how many systems are required to meet a workload and service objective. A benchmark for capacity planning asks where goodput stops increasing under load. The three engineering decisions require different timing boundaries and statistics.
Write the decision in the benchmark record. This determines which costs must be included. Model loading may be irrelevant to a week-long training run, important to a frequently restarted service, and the primary metric for a scale-to-zero deployment.
Describe the workload population
AI work is strongly shape-dependent. For training, record global batch, microbatch, sequence-length policy, padding or packing, parallel configuration, activation checkpointing, optimizer, and data format. For serving, record prompt and requested-output distributions, arrival process, concurrency, batching policy, decoding settings, and cache state.
Preserve relationships between variables. If long prompts usually request short answers, independently sampling prompt and output lengths creates a workload that production never sees. A replay benchmark should retain this correlation or explain the approximation.
Define the system under test
List the hardware and software that can change the mechanism. Hardware model and count are insufficient when memory capacity, topology, power caps, clocks, firmware, driver, runtime, libraries, compiler settings, graph mode, and scheduler configuration affect the result.
Record the source revision and configuration in machine-readable form when possible. The benchmark program can emit a manifest beside its raw samples. This reduces transcription errors and makes later comparisons against a changed environment possible.
Choose cold, warm, and steady states deliberately
The first invocation can include compilation, library initialization, autotuning, memory allocation, page mapping, cache population, and lower device clocks. Later invocations can reuse all of this state. Neither state is inherently more correct. The deployment determines which one matters.
Separate states when they answer separate questions. Report cold-start time for deployment readiness, warm steady-state service for capacity, and cache-hit or cache-miss cases for a prefix-caching system. Do not remove a cost from the timed interval merely because it makes the measurement less stable.
Set measurement boundaries
A GPU-kernel-sequence benchmark can begin immediately before the first kernel launch and end when the device completes the final kernel. An end-to-end inference benchmark can begin when a query enters the service and end when the complete response is delivered. State whether tokenization, network ingress, queueing, transfers, and postprocessing are inside the boundary.
A narrow timing interval helps isolate a mechanism. A wide interval measures experienced performance. Use both when you need to explain why a shorter GPU-kernel sequence does or does not change the complete system.
Report distributions and constraints
A median is often suitable for repeated steady kernel intervals because it resists occasional host interruptions. Interactive services require tail percentiles under a declared offered load. Training time to quality can require repeated runs because initialization and data order affect convergence.
Preserve raw observations and report the quality or correctness limit beside the performance result. MLPerf Inference, for example, defines scenarios with different query generation and latency requirements and requires quality compliance. The broader lesson is that a performance number is meaningful only within its workload and validity rules.
State the sample count behind every percentile. With only 100 independent observations, an empirical p99 is determined by approximately the single slowest observation and is therefore unstable. A production tail estimate usually needs many more observations, a sufficiently long steady interval, and repeated runs. Preserve the empirical distribution instead of reporting a tail percentile with unsupported decimal precision.
Worked example: Writing a contract for an inference comparison
Two serving engines will be compared for a 7-billion-parameter decoder. The engineering decision is how many GPU replicas the service needs for next month's interactive traffic, not which engine has the highest offline token rate.
- Extract a representative joint distribution of prompt length, requested output length, and relevant request class. Remove or anonymize content without destroying these workload relationships.
- Replay arrivals using the intended load model. Run each load point long enough to fill caches, reach stable queue behavior, and observe long requests. Record queue size over time so a growing queue is not mistaken for a valid high-throughput point.
- Hold model weights, numerical format, tokenizer, decoding policy, quality evaluation, and memory limit constant. If an engine cannot support one setting, report that limitation rather than silently changing the workload.
- Measure time to first token, time per output token, end-to-end latency, completed requests, errors, input tokens, output tokens, and GPU-hours. Calculate goodput as valid requests meeting the stated service limits.
- Test several offered loads and plot goodput with latency percentiles. Determine the highest stable point that meets the service objective, then calculate required replicas with explicit headroom for bursts and failures.
- Publish software versions, configuration, scheduler limits, environment manifest, quality results, and raw per-request records. Report cold-start time separately if the deployment frequently adds replicas.
Conclusion: The comparison produces a capacity result for the intended interactive workload. The capacity result does not claim that the selected engine also has the highest offline throughput or the fastest isolated kernels.
Common errors
- Selecting the metric after observing the systems. Write the decision and validity conditions before running the comparison.
- Using one convenient shape to support a production-capacity claim. The result applies only to the measured shape unless a distribution or sweep establishes broader coverage.
- Removing warm-up without defining the intended operating state. Compilation and cache filling can be irrelevant to one deployment and decisive to another.
- Reporting only aggregate throughput. Throughput without load, latency, quality, and error limits does not define an operationally valid point.
Reference summary
A benchmark is the complete controlled experiment, not only the code that reads a timer. For the recurring 7-billion-parameter service, the contract records the 2,048-token prompt distribution, maximum 256-token output, one 80 GiB GPU, request arrival pattern, software revisions, cache state, timing endpoints, quality check, and statistics. The recorded conditions determine which engineering decision the result can support.
- Workload population: record shape, sequence length, sparsity, arrival, and output-length distributions instead of presenting one convenient input as universal.
- System boundary: state whether the measurement includes tokenization, queueing, host-to-device transfers, compilation, model loading, and result processing.
- System state: distinguish cold start, warm-up, cache filling, allocator growth, autotuning, and stable operation. Include each state that matters to the intended deployment.
- Statistics: retain raw samples, report the sample count, and select statistics that match the decision. A tail percentile such as p99 needs enough observations and repeated runs to be stable.
- Reproduction data: record the source revision, configuration, dependencies, driver and runtime, hardware, topology, power policy, and relevant environment settings.
Knowledge check
Two reports both claim 2,000 output tokens per second. Which prompt-length, output-length, arrival, quality, latency, and cache-state fields must match before the rates answer the same capacity question?
Show the answer guide
- The reports must use the same joint prompt-length distribution, including cache-hit or reused prompt tokens, rather than merely reporting the same mean prompt length.
- The output-length distribution, stopping rules, sampling parameters, tokenizer, model weights, and quality gate must match so that an output token represents the same model work and accepted behavior.
- The arrival process, offered request rate, concurrency limit, and test duration must match. An offline full queue and an open-loop online arrival stream answer different capacity questions.
- Timer boundaries and reported time to first token (TTFT), time per output token (TPOT), end-to-end, rejection, and error constraints must match; a token rate measured after discarding late requests is not equivalent to unconstrained throughput.
- Prefix-cache state, key-value (KV) cache occupancy, warm-up, compilation, allocator state, and any cache-reset policy must match because reuse changes both prefill work and available memory.
- Hardware, parallel layout, engine version, quantization, and included host or network stages must also match before attributing a difference to implementation quality.
Run a matched and mismatched corpus benchmark
Choose 20 local text records and a deterministic text-processing function. Save the exact record-length list and run two timed passes with the same ordering and warm state. Run a third pass after replacing half the records with texts four times longer while keeping only the record count constant.
Evidence to keep: Keep the three workload manifests, raw timing samples, length histograms, output checksums, and a written comparison explaining why the first two rates share a contract and the third does not.
After the benchmark requirements define the timed work, select timing boundaries that account for asynchronous host and accelerator execution.
Sources and further reading
The lesson explanations synthesize primary papers and official references. Follow the originals for proofs, exact APIs, architecture details, and version-sensitive behavior.
- CUDA C++ Best Practices Guide↗
- NVIDIA Nsight Systems User Guide↗
Official reference for capturing and reading CPU, CUDA API, GPU workload, and communication timelines.
- PyTorch Profiler documentation↗
Official reference for recording operator activity, CPU and accelerator events, shapes, stacks, and exported traces.
- MLPerf Inference Rules↗
- MLPerf Training Benchmark↗