guidellm.benchmark.schemas
Benchmark schemas for performance measurement and result analysis.
This module consolidates the complete benchmark schema ecosystem, providing both base abstractions for benchmark execution and domain-specific implementations for generative AI tasks. It exports core configuration objects, accumulator interfaces for real-time metric collection, benchmark result containers with statistical summaries, and reporting utilities. The schemas support flexible scheduling strategies, comprehensive metric tracking including latency and throughput distributions, and multi-modal generative benchmarks for text, image, video, and audio generation tasks.
BenchmarkAccumulatorT = TypeVar('BenchmarkAccumulatorT', bound='BenchmarkAccumulator[Any, Any]') module-attribute
Generic type variable for benchmark accumulator implementations
BenchmarkT = TypeVar('BenchmarkT', bound='Benchmark') module-attribute
Generic type variable for benchmark result implementations
Benchmark
Bases: StandardBaseDict, ABC, Generic[BenchmarkAccumulatorT]
Compile and expose final benchmark execution metrics.
Defines the interface for benchmark result implementations capturing comprehensive performance metrics including latency distributions, throughput measurements, and concurrency patterns. Subclasses implement compilation logic to transform accumulated metrics and scheduler state into structured results with statistical summaries.
Source code in src/guidellm/benchmark/schemas/base.py
duration abstractmethod property
Returns:
| Type | Description |
|---|---|
float | Benchmark execution duration in seconds |
end_time abstractmethod property
Returns:
| Type | Description |
|---|---|
float | Benchmark completion timestamp in seconds since epoch |
request_concurrency abstractmethod property
Returns:
| Type | Description |
|---|---|
StatusDistributionSummary | Statistical distribution of concurrent request counts |
request_latency abstractmethod property
Returns:
| Type | Description |
|---|---|
StatusDistributionSummary | Statistical distribution of request latencies |
request_throughput abstractmethod property
Returns:
| Type | Description |
|---|---|
StatusDistributionSummary | Statistical distribution of throughput measurements |
start_time abstractmethod property
Returns:
| Type | Description |
|---|---|
float | Benchmark start timestamp in seconds since epoch |
compile(accumulator, scheduler_state) abstractmethod classmethod
Transform accumulated metrics into final benchmark results.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
accumulator | BenchmarkAccumulatorT | Accumulator instance with collected metrics and state | required |
scheduler_state | SchedulerState | Scheduler's final state after execution completion | required |
Returns:
| Type | Description |
|---|---|
Any | Compiled benchmark instance with complete statistical results |
Source code in src/guidellm/benchmark/schemas/base.py
BenchmarkAccumulator
Bases: StandardBaseDict, ABC, Generic[RequestT, ResponseT]
Track and accumulate benchmark metrics during scheduler execution.
Maintains incremental metric estimates as requests are processed, enabling real-time progress monitoring and efficient metric compilation. Subclasses implement specific metric calculation strategies based on request/response characteristics and scheduler state evolution.
Source code in src/guidellm/benchmark/schemas/base.py
update_estimate(response, request, info, scheduler_state) abstractmethod
Incrementally update metrics with completed request data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
response | ResponseT | None | Backend response data if request succeeded | required |
request | RequestT | Request instance submitted to backend | required |
info | RequestInfo | Request timing, status, and execution metadata | required |
scheduler_state | SchedulerState | Current scheduler state with queue and concurrency info | required |
Source code in src/guidellm/benchmark/schemas/base.py
BenchmarkArgs
Bases: ReloadableBaseModel
Common benchmark configuration arguments.
Source code in src/guidellm/benchmark/schemas/entrypoints.py
139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 | |
BenchmarkConfig
Bases: StandardBaseDict
Encapsulate execution parameters and constraints for benchmark runs.
Defines comprehensive configuration including scheduler strategy, constraint sets, transient phase handling, metric sampling preferences, and execution metadata. Coordinates profile, request, backend, and environment configurations to enable reproducible benchmark execution with precise control over metric collection.
Source code in src/guidellm/benchmark/schemas/base.py
BenchmarkMetadata
Bases: StandardBaseModel
Metadata about the benchmark scenario.
Contains information such as name, description, and tags that describe the benchmark scenario. This metadata is used for reporting and organizational purposes but does not affect benchmark execution.
Source code in src/guidellm/benchmark/schemas/entrypoints.py
BenchmarkOutputArgs
Bases: PydanticClassRegistryMixin['BenchmarkOutputArgs'], ABC
Base class for output creation arguments.
This class serves as a base for defining argument models used in the creation of output instances. It inherits from PydanticClassRegistryMixin to enable automatic registration of subclasses, allowing for flexible and extensible output configurations.
Attributes:
| Name | Type | Description |
|---|---|---|
schema_discriminator | str | Field name for polymorphic deserialization |
Source code in src/guidellm/benchmark/schemas/output.py
__pydantic_schema_base_type__() classmethod
Return base type for polymorphic validation hierarchy.
Returns:
| Type | Description |
|---|---|
type[BenchmarkOutputArgs] | Base BenchmarkOutputArgs class for schema validation |
Source code in src/guidellm/benchmark/schemas/output.py
BenchmarkScenario
Bases: ReloadableBaseModel, BaseSettings
Configuration arguments for generative text benchmark execution.
Defines all parameters for benchmark setup including target endpoint, data sources, backend configuration, processing pipeline, output formatting, and execution constraints. Supports loading from scenario files and merging with runtime overrides for flexible benchmark construction from multiple sources.
Example::
# Load from built-in scenario with overrides
args = BenchmarkScenario.create(
scenario="chat",
spec={"backend": {"kind": "openai_http", "target": "http://localhost:8000/v1"}},
)
# Create from keyword arguments only
args = BenchmarkScenario(
spec=BenchmarkArgs(
backend={"kind": "openai_http", "target": "http://localhost:8000/v1"},
data=[{"kind": "synthetic_text"}],
),
)
Source code in src/guidellm/benchmark/schemas/entrypoints.py
255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 | |
create(scenario, **kwargs) classmethod
Create benchmark args from scenario file and keyword arguments.
Loads base configuration from scenario file (built-in or custom) and merges with provided keyword arguments. Arguments explicitly set via kwargs override scenario values, while defaulted kwargs are ignored to preserve scenario settings.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scenario | Path | str | None | Path to scenario file, built-in scenario name, or None | required |
kwargs | Any | Keyword arguments to override scenario values | {} |
Returns:
| Type | Description |
|---|---|
BenchmarkScenario | Configured benchmark args instance |
Raises:
| Type | Description |
|---|---|
ValueError | If scenario is not found or file format is unsupported |
Source code in src/guidellm/benchmark/schemas/entrypoints.py
get_benchmarks()
Get list of benchmark argument instances for each individual benchmark.
Combines global arguments with individual benchmark overrides to produce a list of fully configured benchmark argument instances for execution.
Returns:
| Type | Description |
|---|---|
list[BenchmarkArgs] | List of benchmark argument instances |
Source code in src/guidellm/benchmark/schemas/entrypoints.py
insert_first_benchmark(data) classmethod
Inserts the first benchmark into the common args.
This allows users to ommit fields from the common args if they have overrides in the first benchmark.
Source code in src/guidellm/benchmark/schemas/entrypoints.py
GenerativeAudioMetricsSummary
Bases: StandardBaseDict
Audio-specific metric summaries for generative benchmarks.
Tracks token, sample count, duration, and byte-level metrics across input, output, and total usage for audio generation workloads.
Source code in src/guidellm/benchmark/schemas/metrics.py
compile(successful, incomplete, errored) classmethod
Compile audio metrics summary from request statistics.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
successful | list[GenerativeRequestStats] | Successfully completed request statistics | required |
incomplete | list[GenerativeRequestStats] | Incomplete/cancelled request statistics | required |
errored | list[GenerativeRequestStats] | Failed request statistics | required |
Returns:
| Type | Description |
|---|---|
GenerativeAudioMetricsSummary | Compiled audio metrics summary |
Source code in src/guidellm/benchmark/schemas/metrics.py
GenerativeBenchmark
Bases: Benchmark[GenerativeBenchmarkAccumulator]
Complete generative AI benchmark results with specialized metrics.
Encapsulates comprehensive performance data from scheduler-driven generative workload executions including request-level statistics, token/latency distributions, throughput analysis, and concurrency patterns. Provides computed fields for temporal analysis and status-grouped request details for detailed post-execution reporting.
Source code in src/guidellm/benchmark/schemas/benchmark.py
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 | |
cooldown_duration property
Returns:
| Type | Description |
|---|---|
float | Cooldown phase duration in seconds |
duration property
Returns:
| Type | Description |
|---|---|
float | Total benchmark execution duration in seconds |
end_time property
Returns:
| Type | Description |
|---|---|
float | Benchmark end time in seconds since epoch |
request_concurrency property
Returns:
| Type | Description |
|---|---|
StatusDistributionSummary | Statistical distribution of concurrent requests throughout execution |
request_latency property
Returns:
| Type | Description |
|---|---|
StatusDistributionSummary | Statistical distribution of request latencies across all requests |
request_throughput property
Returns:
| Type | Description |
|---|---|
StatusDistributionSummary | Statistical distribution of throughput measured in requests per second |
start_time property
Returns:
| Type | Description |
|---|---|
float | Benchmark start time in seconds since epoch |
warmup_duration property
Returns:
| Type | Description |
|---|---|
float | Warmup phase duration in seconds |
compile(accumulator, scheduler_state) classmethod
Compile final benchmark results from accumulated execution state.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
accumulator | GenerativeBenchmarkAccumulator | Accumulated benchmark state with request statistics | required |
scheduler_state | SchedulerState | Final scheduler state after execution completion | required |
Returns:
| Type | Description |
|---|---|
GenerativeBenchmark | Compiled generative benchmark instance with complete metrics |
Source code in src/guidellm/benchmark/schemas/benchmark.py
GenerativeBenchmarkAccumulator
Bases: BenchmarkAccumulator[GenerationRequest, GenerationResponse]
Primary accumulator for generative benchmark execution metrics and statistics.
Orchestrates real-time metric collection across timing, scheduler, concurrency, and generative performance dimensions. Maintains separate accumulators for completed, errored, and incomplete requests while tracking overall metrics. Integrates with scheduler state to monitor warmup/cooldown phases and compute time-weighted statistics for throughput and latency analysis.
Source code in src/guidellm/benchmark/schemas/accumulator.py
774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 | |
model_post_init(__context)
Initialize child accumulators with config values after model construction.
Propagates sample_size from config to child request accumulators to ensure consistent sampling behavior across completed, errored, and incomplete request collections. This ensures the --metrics-sample-size option functions correctly.
Source code in src/guidellm/benchmark/schemas/accumulator.py
update_estimate(response, request, info, scheduler_state)
Update all benchmark metrics with a completed request.
Processes request completion by updating timing phases, concurrency metrics, scheduler statistics, and generative performance metrics. Routes request to appropriate status-specific accumulator (completed/errored/incomplete) and updates aggregate totals. Cancelled requests that never started are ignored.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
response | GenerationResponse | None | Generation response with output and metrics, or None | required |
request | GenerationRequest | Original generation request with input data | required |
info | RequestInfo | Request execution information and timing | required |
scheduler_state | SchedulerState | Current scheduler state for phase tracking | required |
Source code in src/guidellm/benchmark/schemas/accumulator.py
GenerativeBenchmarkMetadata
Bases: StandardBaseModel
Versioning and environment metadata for generative benchmark reports.
Source code in src/guidellm/benchmark/schemas/report.py
GenerativeBenchmarkTimings
Bases: StandardBaseModel
Tracks timing phases and transitions during benchmark execution.
Monitors timestamps throughout benchmark execution including request submission, measurement period boundaries (warmup/active/cooldown), and completion events. Provides duration calculations and phase status determination based on configured warmup and cooldown periods.
Source code in src/guidellm/benchmark/schemas/accumulator.py
44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 | |
duration property
Returns:
| Type | Description |
|---|---|
float | Elapsed time since measurement or request start in seconds |
elapsed_time_last_request property
Returns:
| Type | Description |
|---|---|
float | Time elapsed between the last two request completions in seconds |
elapsed_time_last_update property
Returns:
| Type | Description |
|---|---|
float | Time elapsed between the last two update timestamps in seconds |
finalized_measure_end property
Returns:
| Type | Description |
|---|---|
float | Finalized timestamp from the current state for when measurement ended |
finalized_measure_start property
Returns:
| Type | Description |
|---|---|
float | Finalized timestamp from the current state for when measurement started |
finalized_request_end property
Returns:
| Type | Description |
|---|---|
float | Finalized timestamp from the current state for when requests ended |
finalized_request_start property
Returns:
| Type | Description |
|---|---|
float | Finalized timestamp from the current state for when requests started |
status property
Returns:
| Type | Description |
|---|---|
Literal['pending', 'warmup', 'active', 'cooldown'] | Current execution phase based on timing thresholds |
update_estimate(info, scheduler_state, config)
Update timing estimates based on request info and scheduler state.
Advances timing markers through benchmark phases (warmup to active to cooldown) based on configured thresholds. Updates current/last timestamps for updates and request completions, determining measurement period boundaries.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
info | RequestInfo | Request information containing timing data | required |
scheduler_state | SchedulerState | Current scheduler state with progress metrics | required |
config | BenchmarkConfig | Benchmark configuration with warmup/cooldown settings | required |
Source code in src/guidellm/benchmark/schemas/accumulator.py
GenerativeBenchmarksReport
Bases: StandardBaseModel
Container for multiple benchmark results with load/save functionality.
Aggregates multiple generative benchmark executions into a single report, providing persistence through JSON and YAML file formats. Enables result collection, storage, and retrieval across different execution sessions with automatic file type detection and path resolution.
Attributes:
| Name | Type | Description |
|---|---|---|
DEFAULT_FILE | str | Default filename used when saving to or loading from a directory |
Source code in src/guidellm/benchmark/schemas/report.py
56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 | |
load_file(path, type_=None) classmethod
Load report from JSON or YAML file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path | str | Path | File path or directory containing DEFAULT_FILE to load from | required |
type_ | Literal['json', 'yaml'] | None | File format override ('json' or 'yaml'), auto-detected from extension if None | None |
Returns:
| Type | Description |
|---|---|
GenerativeBenchmarksReport | Loaded report instance with benchmarks and configuration |
Raises:
| Type | Description |
|---|---|
ValueError | If file type is unsupported or cannot be determined |
FileNotFoundError | If specified file does not exist |
Source code in src/guidellm/benchmark/schemas/report.py
save_file(path=None, type_=None)
Save report to file in JSON or YAML format.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path | str | Path | None | File path or directory for saving, defaults to current directory with DEFAULT_FILE name | None |
type_ | Literal['json', 'yaml'] | None | File format override ('json' or 'yaml'), auto-detected from extension if None | None |
Returns:
| Type | Description |
|---|---|
Path | Resolved path to the saved file |
Raises:
| Type | Description |
|---|---|
ValueError | If file type is unsupported or cannot be determined |
Source code in src/guidellm/benchmark/schemas/report.py
GenerativeImageMetricsSummary
Bases: StandardBaseDict
Image-specific metric summaries for generative benchmarks.
Tracks token, image count, pixel, and byte-level metrics across input, output, and total usage for image generation workloads.
Source code in src/guidellm/benchmark/schemas/metrics.py
compile(successful, incomplete, errored) classmethod
Compile image metrics summary from request statistics.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
successful | list[GenerativeRequestStats] | Successfully completed request statistics | required |
incomplete | list[GenerativeRequestStats] | Incomplete/cancelled request statistics | required |
errored | list[GenerativeRequestStats] | Failed request statistics | required |
Returns:
| Type | Description |
|---|---|
GenerativeImageMetricsSummary | Compiled image metrics summary |
Source code in src/guidellm/benchmark/schemas/metrics.py
GenerativeMetrics
Bases: StandardBaseDict
Comprehensive metrics for generative AI benchmarks.
Aggregates request statistics, token metrics, timing distributions, and domain-specific measurements across text, image, video, and audio modalities. Provides detailed statistical summaries including distribution analysis for throughput, latency, concurrency, and resource utilization metrics across successful, incomplete, and errored requests.
Source code in src/guidellm/benchmark/schemas/metrics.py
763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 | |
compile(accumulator) classmethod
Compile comprehensive generative metrics from benchmark accumulator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
accumulator | GenerativeBenchmarkAccumulator | Benchmark accumulator with completed request statistics | required |
Returns:
| Type | Description |
|---|---|
GenerativeMetrics | Compiled generative metrics with all distributions and summaries |
Raises:
| Type | Description |
|---|---|
ValueError | If measure_start and measure_end/request_end are not set |
Source code in src/guidellm/benchmark/schemas/metrics.py
852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 | |
GenerativeMetricsAccumulator
Bases: StandardBaseModel
Accumulates generative model performance metrics during execution.
Tracks token throughput, latency characteristics, and request timing for generative workloads. Maintains running statistics for input/output tokens, time-to-first-token, inter-token latency, and streaming patterns for comprehensive performance analysis.
Source code in src/guidellm/benchmark/schemas/accumulator.py
465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 | |
update_estimate(stats, duration)
Update generative metrics with completed request statistics.
Incorporates token counts, latency measurements, and streaming characteristics from a completed request into running metric accumulators with time-weighted calculations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
stats | GenerativeRequestStats | Request statistics containing token and latency measurements | required |
duration | float | Current benchmark duration for time-weighted metrics | required |
Source code in src/guidellm/benchmark/schemas/accumulator.py
GenerativeMetricsArgs
Bases: MetricsArgs
Metrics configuration for generative (autoregressive) benchmarks.
Source code in src/guidellm/benchmark/schemas/entrypoints.py
GenerativeMetricsSummary
Bases: StandardBaseDict
Statistical summaries for input, output, and total metrics.
Provides distribution summaries across successful, incomplete, and errored requests for absolute values, per-second rates, and concurrency levels.
Source code in src/guidellm/benchmark/schemas/metrics.py
171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 | |
compile(property_name, successful, incomplete, errored) classmethod
Compile metrics summary from request statistics for a specific property.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
property_name | str | Name of the property to extract from request metrics | required |
successful | list[GenerativeRequestStats] | Successfully completed request statistics | required |
incomplete | list[GenerativeRequestStats] | Incomplete or cancelled request statistics | required |
errored | list[GenerativeRequestStats] | Failed request statistics | required |
Returns:
| Type | Description |
|---|---|
GenerativeMetricsSummary | None | Compiled metrics summary or None if no data available |
Source code in src/guidellm/benchmark/schemas/metrics.py
compile_timed_metrics(successful, incomplete, errored) classmethod
Compile metrics summary from timed metric tuples.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
successful | list[TimedMetricTypeAlias] | Timed metrics from successful requests | required |
incomplete | list[TimedMetricTypeAlias] | Timed metrics from incomplete requests | required |
errored | list[TimedMetricTypeAlias] | Timed metrics from errored requests | required |
Returns:
| Type | Description |
|---|---|
GenerativeMetricsSummary | None | Compiled metrics summary or None if no data available |
Source code in src/guidellm/benchmark/schemas/metrics.py
242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 | |
extract_property_metrics_for_summary(stats_list, property_name) classmethod
Extract timed metrics for a specific property from request statistics.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
stats_list | list[GenerativeRequestStats] | List of request statistics to extract from | required |
property_name | str | Name of the property to extract from metrics | required |
Returns:
| Type | Description |
|---|---|
list[TimedMetricTypeAlias] | List of tuples containing (start_time, end_time, input_value, output_value) |
Source code in src/guidellm/benchmark/schemas/metrics.py
GenerativeRequestsAccumulator
Bases: StandardBaseModel
Manages request statistics collection with optional reservoir sampling.
Collects detailed request statistics while optionally sampling to limit memory usage in long-running benchmarks. Supports configurable sampling rates and selective data retention (clearing request arguments and/or outputs for non-sampled requests).
Source code in src/guidellm/benchmark/schemas/accumulator.py
571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 | |
compile_stats(response, request, info, prefer_response_metrics) classmethod
Compile statistics from request, response, and execution info.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
response | GenerationResponse | None | Generation response with output and metrics, or None | required |
request | GenerationRequest | Original generation request with input data | required |
info | RequestInfo | Request execution information and timing | required |
prefer_response_metrics | bool | Whether to prefer metrics from response | required |
Returns:
| Type | Description |
|---|---|
GenerativeRequestStats | Compiled generative request statistics |
Source code in src/guidellm/benchmark/schemas/accumulator.py
get_sampled()
Retrieve the list of sampled request statistics.
Returns:
| Type | Description |
|---|---|
list[GenerativeRequestStats] | List of sampled generative request statistics |
Source code in src/guidellm/benchmark/schemas/accumulator.py
get_within_range(start_time, end_time, start_func=lambda s: s.request_start_time, end_func=lambda s: s.request_end_time, closed=False)
Retrieve request statistics within a specified time range.
If the request has no start time we treat it as an instantaneous event at the end time.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
start_time | float | Start timestamp for filtering (events must end after this) | required |
end_time | float | End timestamp for filtering (events must start before this) | required |
start_func | Callable[[GenerativeRequestStats], float | None] | Function to extract the start timestamp from a request stat | lambda s: request_start_time |
end_func | Callable[[GenerativeRequestStats], float | None] | Function to extract the end timestamp from a request stats | lambda s: request_end_time |
closed | bool | If True, events must be strictly enclosed within the time range. If False, include events that partially overlap the time range. | False |
Returns:
| Type | Description |
|---|---|
list[GenerativeRequestStats] | List of request statistics within the time range |
Source code in src/guidellm/benchmark/schemas/accumulator.py
update_estimate(response, request, info, prefer_response_metrics)
Record request statistics and apply reservoir sampling if configured.
Compiles statistics from the completed request and adds to the collection. Uses reservoir sampling algorithm to maintain uniform sample distribution when enabled, clearing non-sampled request data to manage memory.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
response | GenerationResponse | None | Generation response containing output and metrics | required |
request | GenerationRequest | Original generation request with input data | required |
info | RequestInfo | Request execution information and timing | required |
prefer_response_metrics | bool | Whether to prefer metrics from response | required |
Returns:
| Type | Description |
|---|---|
GenerativeRequestStats | Compiled request statistics |
Source code in src/guidellm/benchmark/schemas/accumulator.py
GenerativeTextMetricsSummary
Bases: StandardBaseDict
Text-specific metric summaries for generative benchmarks.
Tracks token, word, and character-level metrics across input, output, and total usage for text generation workloads.
Source code in src/guidellm/benchmark/schemas/metrics.py
compile(successful, incomplete, errored) classmethod
Compile text metrics summary from request statistics.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
successful | list[GenerativeRequestStats] | Successfully completed request statistics | required |
incomplete | list[GenerativeRequestStats] | Incomplete/cancelled request statistics | required |
errored | list[GenerativeRequestStats] | Failed request statistics | required |
Returns:
| Type | Description |
|---|---|
GenerativeTextMetricsSummary | Compiled text metrics summary |
Source code in src/guidellm/benchmark/schemas/metrics.py
GenerativeVideoMetricsSummary
Bases: StandardBaseDict
Video-specific metric summaries for generative benchmarks.
Tracks token, frame count, duration, and byte-level metrics across input, output, and total usage for video generation workloads.
Source code in src/guidellm/benchmark/schemas/metrics.py
compile(successful, incomplete, errored) classmethod
Compile video metrics summary from request statistics.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
successful | list[GenerativeRequestStats] | Successfully completed request statistics | required |
incomplete | list[GenerativeRequestStats] | Incomplete/cancelled request statistics | required |
errored | list[GenerativeRequestStats] | Failed request statistics | required |
Returns:
| Type | Description |
|---|---|
GenerativeVideoMetricsSummary | Compiled video metrics summary |
Source code in src/guidellm/benchmark/schemas/metrics.py
MetricsArgs
Bases: PydanticClassRegistryMixin['MetricsArgs'], ABC
Base class for metrics collection arguments.
Attributes:
| Name | Type | Description |
|---|---|---|
schema_discriminator | str | Field name for polymorphic deserialization |
Source code in src/guidellm/benchmark/schemas/entrypoints.py
__pydantic_schema_base_type__() classmethod
Return base type for polymorphic validation hierarchy.
Returns:
| Type | Description |
|---|---|
type[MetricsArgs] | Base MetricsArgs class for schema validation |
Source code in src/guidellm/benchmark/schemas/entrypoints.py
ProfileArgs
Bases: PydanticClassRegistryMixin['ProfileArgs'], ABC
Base class for profile creation arguments.
This class serves as a base for defining argument models used in the creation of profile instances. It inherits from PydanticClassRegistryMixin to enable automatic registration of subclasses, allowing for flexible and extensible profile configurations.
Attributes:
| Name | Type | Description |
|---|---|---|
schema_discriminator | str | Field name for polymorphic deserialization |
Source code in src/guidellm/benchmark/schemas/profiles.py
__pydantic_schema_base_type__() classmethod
Return base type for polymorphic validation hierarchy.
Returns:
| Type | Description |
|---|---|
type[ProfileArgs] | Base ProfileArgs class for schema validation |
Source code in src/guidellm/benchmark/schemas/profiles.py
RandomArgs
Bases: PydanticClassRegistryMixin['RandomArgs'], ABC
Base class for random initialization arguments.
Attributes:
| Name | Type | Description |
|---|---|---|
schema_discriminator | str | Field name for polymorphic deserialization |
Source code in src/guidellm/benchmark/schemas/random.py
__pydantic_schema_base_type__() classmethod
Return base type for polymorphic validation hierarchy.
Returns:
| Type | Description |
|---|---|
type[RandomArgs] | Base RandomArgs class for schema validation |
Source code in src/guidellm/benchmark/schemas/random.py
RunningMetricStats
Bases: StandardBaseModel
Maintains running statistics for a metric stream without storing all samples.
Accumulates count, sum, time-weighted sum, and duration to compute mean, rate, and time-weighted statistics incrementally. Efficient for real-time metric tracking during long-running benchmarks where storing individual samples is impractical.
Source code in src/guidellm/benchmark/schemas/accumulator.py
216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 | |
mean property
Returns:
| Type | Description |
|---|---|
float | None | Arithmetic mean of accumulated values, or None if no samples |
rate_per_item property
Returns:
| Type | Description |
|---|---|
float | None | Average value per accumulated item, or None if no samples |
rate_per_second property
Returns:
| Type | Description |
|---|---|
float | None | Average value per second of duration, or None if no duration |
time_weighted_mean property
Returns:
| Type | Description |
|---|---|
float | None | Time-weighted mean considering duration between samples, or None |
update_estimate(value, count=1, duration=None, elapsed=None)
Incorporate a new metric value into running statistics.
Updates count, sum, and time-weighted statistics using the new value and timing information. Time-weighted calculations use the previous value over the elapsed interval to capture sustained metric behavior.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value | float | None | New metric value to accumulate | required |
count | int | Number of occurrences this value represents | 1 |
duration | float | None | Total duration to set, overriding incremental elapsed updates | None |
elapsed | float | None | Time elapsed since last update for time-weighted calculations | None |
Source code in src/guidellm/benchmark/schemas/accumulator.py
SchedulerMetrics
Bases: StandardBaseDict
Scheduler timing and performance statistics.
Tracks overall benchmark timing, request counts by status, and detailed internal scheduler performance metrics including queue times, processing delays, and request execution statistics. Used to analyze scheduler efficiency and identify bottlenecks in request processing pipelines.
Source code in src/guidellm/benchmark/schemas/metrics.py
58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 | |
compile(accumulator, scheduler_state) classmethod
Compile scheduler metrics from accumulator and scheduler state.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
accumulator | GenerativeBenchmarkAccumulator | Benchmark accumulator containing timing and metric data | required |
scheduler_state | SchedulerState | Scheduler state with execution timing information | required |
Returns:
| Type | Description |
|---|---|
SchedulerMetrics | Compiled scheduler metrics with performance statistics |
Source code in src/guidellm/benchmark/schemas/metrics.py
SchedulerMetricsAccumulator
Bases: StandardBaseModel
Tracks scheduler-level timing and overhead metrics during execution.
Monitors request lifecycle timing from queuing through completion, capturing delays at each stage: queue time, worker start delays, request processing time, and finalization overhead. Provides insight into scheduler efficiency and bottleneck identification in request orchestration.
Source code in src/guidellm/benchmark/schemas/accumulator.py
309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 | |
update_estimate(scheduler_state, stats)
Update scheduler metrics with completed request timing data.
Extracts timing information from request statistics to update running metrics for each scheduler lifecycle stage. Validates that required timing markers are present before processing.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scheduler_state | SchedulerState | Current scheduler state with request counts | required |
stats | GenerativeRequestStats | Completed request statistics with detailed timing information | required |
Raises:
| Type | Description |
|---|---|
ValueError | If required timing markers are missing |
Source code in src/guidellm/benchmark/schemas/accumulator.py
379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 | |
TransientPhaseConfig
Bases: StandardBaseModel
Configure warmup and cooldown phases for benchmark execution.
Supports flexible phase definition through percentage or absolute value specifications with multiple interpretation modes. Phases can be bounded by duration, request count, or both, enabling precise control over transient periods that should be excluded from final benchmark metrics.
Source code in src/guidellm/benchmark/schemas/base.py
52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 | |
compute_limits(max_requests, max_seconds, enforce_preference=True)
Calculate phase boundaries from benchmark constraints.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
max_requests | int | float | None | Total request budget for benchmark execution | required |
max_seconds | float | None | Total duration budget for benchmark execution | required |
enforce_preference | bool | Whether to enforce preferred mode when both duration and request constraints are available | True |
Returns:
| Type | Description |
|---|---|
tuple[float | None, int | None] | Tuple of (phase duration in seconds, phase request count) |
Source code in src/guidellm/benchmark/schemas/base.py
compute_transition_time(info, state, period)
Determine transition timestamp for entering or exiting phase.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
info | RequestInfo | RequestInfo for current request to calculate against | required |
state | SchedulerState | SchedulerState with current progress metrics and scheduler info | required |
period | Literal['start', 'end'] | Phase period, either "start" for warmup or "end" for cooldown | required |
Returns:
| Type | Description |
|---|---|
tuple[bool, float | None] | Tuple of (phase active flag, transition timestamp if applicable) |
Source code in src/guidellm/benchmark/schemas/base.py
160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 | |
create_from_value(value) classmethod
Create configuration from flexible input formats.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value | int | float | dict | TransientPhaseConfig | None | Configuration as int/float (percent if <1.0, absolute otherwise), dict (validated to model), TransientPhaseConfig instance, or None for defaults | required |
Returns:
| Type | Description |
|---|---|
TransientPhaseConfig | Configured TransientPhaseConfig instance |
Raises:
| Type | Description |
|---|---|
ValueError | If value type is unsupported |