cpu - sweep saturation detection

[maryamtahhan]

Summary

This PR adds configurable saturation detection and optimisation parameters for testing CPU-based deployments/SUTs (vllm-cpu) with the sweep profile. CPU deployments saturate at much lower concurrency rates than GPU deployments (e.g., 16 concurrent requests vs 512), causing sweep tests to continue measuring beyond saturation and producing misleading "knee bend" artifacts in performance graphs. The new parameters allow users to detect saturation early, stop tests efficiently, and exclude anomalous throughput measurements from results.

Details

• Added three new configurable parameters to SweepProfile:
  • exclude_throughput_target (default: false) - Stops constant-rate tests before reaching throughput level
  • exclude_throughput_result (default: false) - Excludes throughput benchmark from saved results
  • saturation_threshold (default: 0.98) - Efficiency threshold for detecting saturation (achieved/target rate)
• Implemented saturation detection logic in SweepProfile.next_strategy() that stops sweep when efficiency drops below threshold
• Added parameter propagation through:
  • Settings class for environment variable configuration (GUIDELLM__*)
  • CLI parameters in GenerativeBenchmarkEntrypoint
  • Profile resolution in SweepProfile.resolve_args()
• Modified rate interpolation logic to support both GPU mode (include throughput target) and CPU mode (exclude throughput target)
• Added comprehensive documentation in docs/getting-started/benchmark.md

Test Plan

Verified with vLLM-CPU deployment
Test saturation detection works correctly:

guidellm benchmark \
  --target "http://localhost:8000" \
  --profile sweep \
  --exclude-throughput-target true \
  --exclude-throughput-result true \
  --saturation-threshold 0.98 \
  --data "prompt_tokens=256,output_tokens=128" \
  --max-seconds 180

• ✅ Sweep stopped at test Standardize Logger Implementation with Loguru and Add Comprehensive Unit Tests #5 when efficiency dropped to 97% (below 98% threshold)
• ✅ TTFT increased correctly: 67.65 → 69.34 → 70.82 → 73.49 → 80.53ms
• ✅ Throughput benchmark excluded from saved results
• ✅ No anomalous data points in graphs

** Test that defaults work for GPU deployments**

guidellm benchmark \
  --target "http://localhost:8000" \
  --profile sweep \
  --data "prompt_tokens=256,output_tokens=128"

• ✅ All parameters default to false/0.98 (GPU-friendly behavior)
• ✅ Full sweep completes with throughput benchmark included

** Verify environment variable configuration **

export GUIDELLM__EXCLUDE_THROUGHPUT_TARGET=true
export GUIDELLM__EXCLUDE_THROUGHPUT_RESULT=true
export GUIDELLM__SATURATION_THRESHOLD=0.98

guidellm benchmark --target "http://localhost:8000" --profile sweep

• ✅ Parameters correctly inherited from environment variables

** Run unit tests**

pytest tests/unit/data/test_builders.py tests/unit/test_settings.py -v

• ✅ All 54 tests passed

Run pre-commit checks

pre-commit run --all-files

• ✅ All checks passed (linter, formatter, whitespace, EOF)

Related Issues

N/A

---

• "I certify that all code in this PR is my own, except as noted below."

Use of AI

• Includes AI-assisted code completion
• Includes code generated by an AI application
• Includes AI-generated tests (NOTE: AI written tests should have a docstring that includes ## WRITTEN BY AI ##)

[maryamtahhan]

changes graphs from:

[maryamtahhan]

To:

[maryamtahhan]

and sweep stops gracefully when saturation is detected: