benchmark-tune

Runs mesh-llm benchmark tune sweeps to optimize model-serving throughput settings.

3.4k|405|Updated Feb 11, 2026
One-click install
npx skills add https://github.com/Mesh-LLM/mesh-llm --skill benchmark-tune
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: benchmark-tune
Source: https://github.com/Mesh-LLM/mesh-llm/tree/main/.agents/skills/benchmark-tune
Command: npx skills add https://github.com/Mesh-LLM/mesh-llm --skill benchmark-tune

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Tuning LLM serving performance requires testing many combinations of context size, batch size, mmap, mlock, and speculative decoding settings, which is tedious and error-prone to do manually. This Skill guides running, debugging, and interpreting mesh-llm benchmark tune trials so you get tolerance-aware, evidence-backed configuration recommendations.

Core Features & Use Cases

  • Candidate Sweeps: Sweep ctx sizes, batch/ubatch sizes, mmap/mlock values, and speculative decoding types (MTP, draft, ngram) with bounded or explicit value lists.
  • JSON Evidence Collection: Capture machine-readable results including best, raw_best, pareto frontier, per-trial decode tok/s, timings, and error logs for local or SSH remote hosts.
  • Tolerance-Aware Interpretation: Compare raw best versus recommended settings, explain tok/s versus context-size tradeoffs, and verify speculative decoding is actually active via debug telemetry.
  • Use Case: On a remote CUDA host, run a bounded sweep over ctx sizes 8192-262144 with speculative auto mode, tee the JSON output to a timestamped file, and report the recommended configuration with its throughput and context tradeoffs.

Quick Start

Ask the assistant to run mesh-llm benchmark tune on a local GGUF model with a bounded ctx and batch sweep and interpret the JSON results.

Frequently Asked Questions about benchmark-tune

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run mesh-llm benchmark tune on a local model?

Run mesh-llm benchmark tune with --model pointing to a downloaded GGUF file, plus sweep flags like --ctx-sizes, --batch-sizes, and --ubatch-sizes. Add --json and tee the output to a file for machine-readable evidence.

What is the difference between mesh-llm benchmark tune and gpu tune?

Benchmark tune is the correct command for model-serving throughput tuning. The gpus namespace is only for hardware inventory and raw fingerprinting, so gpu tune or gpus tune should not be used for serving optimization.

Can benchmark tune run on a remote SSH host?

Yes, benchmark tune can run on remote hosts over SSH, preferably in a TTY login shell with tee logging. Verify the intended CUDA runtime is selected via mesh-llm runtime list before recording performance results.

How does speculative decoding tuning work in benchmark tune?

By default, --speculative-types auto tries MTP for MTP-style models, then local draft-model candidates, then ngram fallbacks, plus a disabled baseline. Use --speculative-types mtp,draft,ngram,disabled to force an explicit sweep or --no-speculative-tune to disable it.

Why do benchmark tune trials fail or produce no results?

Trials commonly fail due to invalid ubatch greater than batch pairs, missing local model targets, or wrong runtime selection. Check benchmarks[].trials[].error and the per-trial log_path under target/gpu-tune/ for the shared failure reason.

What are the limitations of benchmark tune model targets?

Benchmark tune only accepts already-downloaded local or configured model targets and will not fetch remote-only refs. Without an explicit target, it uses configured local models from ~/.mesh-llm/config.toml.