Why PerformanceLab exists
Local LLM performance depends on the model, quantization, processor, RAM, GPU/VRAM, memory bandwidth, context length, thread count, thermal state and whatever else the workstation is doing at the time. PerformanceLab avoids pretending that hardware specifications alone can predict the answer. It benchmarks local Ollama inference directly.
The baseline methodology is:
Scan Machine
↓
Establish Controlled Configuration
↓
Run Benchmark
↓
Record Results
↓
Assess Performance
↓
Change ONE Variable
↓
Run Benchmark Again
↓
Compare
↓
Keep or Reject the ChangeIntegration with OpusAI
The PerformanceLab button opens the utility as a second suite window inside the same Qt application process. It does not start another OpusAI/Python instance. Benchmark configuration, history and reports remain accessible to the main application through the unified project structure.
System scan
The System tab creates a performance profile including operating system, kernel, architecture, Python, CPU model and threads, CPU frequency/governors, system load, RAM, swap, GPU discovery, NVIDIA statistics when available, thermal zones, block devices, Ollama availability/version, installed models, model size, parameters and reported quantization.
The scan is informational and does not modify the machine.
Benchmark configuration
| Variable | Meaning |
|---|---|
| Model | An installed Ollama model. |
| Measured runs | Inference runs included in warm-performance averages. Baseline default: 3. |
| Warmup runs | Unmeasured runs performed before measured runs. Baseline default: 1. |
| Output tokens | Maximum generated tokens, sent to Ollama as num_predict. Baseline default: 256. |
| CPU threads | Explicit num_thread, or Auto when zero. |
| Context | Requested num_ctx. Baseline default: 4096. |
| Temperature | Sampling temperature; 0.0 is recommended for controlled comparisons. |
| Cold benchmark | Unloads the selected model before the first benchmark request. |
| Prompt | User-configurable benchmark prompt; keep it unchanged for comparisons. |
Benchmark phases
Pre-benchmark scan
Records the machine state before inference as system_before.
Cold phase
When enabled, the selected model is unloaded and reloaded by the benchmark request. Cold results include generation throughput, prompt throughput, load duration, total Ollama duration and independent wall time.
Warmup phase
Warmup requests are retained in the record but excluded from measured-run averages.
Measured phase
Repeated measured runs record generation tokens/sec, prompt evaluation tokens/sec, total duration, load duration, wall time and evaluated-token count.
Post-benchmark scan
Records the system state after inference as system_after.
Session timing
PerformanceLab 1.0.3 introduced complete session timing for pre-scan, cold phase, warmup phase, measured phase, post-scan, benchmark phase and total session. Pre-1.0.3 reports do not contain equivalent total-session timing and should not be mixed into session-duration comparisons.
Metrics
- Generation tokens/sec: autoregressive output speed. Higher is better.
- Prompt evaluation tokens/sec: input processing speed. Higher is better.
- Load time: especially important for cold tests. Lower is better.
- Total duration: Ollama-reported request duration. Lower is better.
- Wall time: application-side monotonic timing. Lower is better.
- Total session: complete benchmark workflow duration. Lower is better.
Comparison and configuration tracking
PerformanceLab finds the most recent prior record using the same model, compares key performance metrics, reverses lower-is-better measures into a performance interpretation, and reports configuration changes such as cpu_threads: 12 -> 8. This matters because a benchmark number without the configuration that produced it is not reproducible evidence.
Recommendations
The recommendation engine checks conditions such as swap use, memory pressure, CPU governor, load, temperature, GPU information and unexpectedly low throughput. Recommendations are diagnostic hypotheses, not proof that a suggested change will improve performance.
CPU governor controls
The Settings tab can explicitly request the Linux performance governor and later restore the per-core governor state saved before the app-initiated change. Elevated permission is requested with pkexec only when the user deliberately changes the governor. Normal scanning and benchmarking do not require OpusAI to run permanently as root.
Persistence
config/performance_lab.json data/performance_lab/benchmarks.json reports/
Benchmark history is structured JSON and includes IDs, timestamps, application version, configuration, pre/post system state, benchmark phases, comparison data, configuration changes, previous record ID and recommendations. Text reports provide a human-readable companion to the JSON history.
Report visualizer
The OpusAI 1.2 source includes an integrated PerformanceLab report visualizer. It scans active benchmark text reports, can filter by model, plots selected metrics across reports, summarizes report/model counts and can export a graph. Its selected reports directory is stored separately from the benchmark configuration so visualization preferences do not alter benchmark settings.
Canonical baseline results
The supplied PerformanceLab documentation identifies two initial canonical baselines:
| Model | Gen tok/s | Prompt tok/s | Avg wall | Total session |
|---|---|---|---|---|
| llama3:latest | 7.51 | 311.23 | 34.610 s | 179.844 s |
| qwen3-coder:30b | 10.02 | 344.17 | 25.990 s | 143.958 s |
These are development-machine baselines, not universal model rankings. Their value is that they preserve a controlled configuration for comparison on the machine that produced them.
Best practice
Establish a baseline, keep the prompt and environment consistent, change one variable, rerun, compare both throughput and complete session behavior, and keep the change only when the measurement supports it. PerformanceLab is built to replace tuning folklore with repeatable evidence.