How to Select a Decode Profile in MTPLX: CLI and Python API Guide

MTPLX automatically selects the optimal decode profile (Auto mode) based on the model identifier, but you can override this selection using the --profile flag in the CLI or the get_profile() function in Python to force specific runtime behaviors like turbo for fastest decode or sustained for long-context safety.

The MTPLX engine executes large language models under specific runtime profiles that govern pre-fill strategies, decode kernels, and fan control mechanisms. While the system defaults to an intelligent Auto mode that selects the appropriate profile for your model, understanding how to manually select a decode profile in MTPLX allows you to optimize for speed, context length, or compatibility. This guide covers both command-line and programmatic profile selection using the official youssofal/MTPLX source.

Understanding Auto Mode and Default Resolution

The Auto mode examines the model identifier to determine the safest and fastest decode path. According to the source code in mtplx/cli.py around line 2161, the engine applies the following resolution logic:

• For quantized 27B/9B flagship families (specifically Qwen 3.8-Turbo packs), the engine selects the turbo profile. This profile activates NAX-verify kernels and compiled-verify paths for maximum throughput.
• For all other models, the engine falls back to the sustained profile, which provides chunked pre-fill and normal fan control for safe long-context execution.

This default behavior ensures that specialized hardware optimizations apply automatically to supported models while maintaining stability for general workloads.

Selecting a Decode Profile via Command Line

You can explicitly override Auto mode using the --profile flag defined in mtplx/cli.py (line 2165). This flag accepts several profile identifiers that alter the runtime characteristics of the inference engine.

Use the following commands to select specific profiles:

# Auto mode (recommended) - let MTPLX choose per-model

mtplx start

# Turbo mode - fastest decode for quantized flagships

mtplx start --profile turbo

# Sustained mode - safe long-context processing

mtplx start --profile sustained

# Performance-cold with fan boost - short-context benchmarking

mtplx start --profile performance-cold --max

The --profile argument injects environment variables and kernel selection logic immediately upon server initialization.

Programmatic Profile Selection with Python

For custom scripts or API integrations, import the profile utilities from mtplx/profiles. The get_profile() function at line 863 returns a RuntimeProfile instance based on the name you provide:

from mtplx.profiles import get_profile

# Retrieve the 'turbo' profile (will also populate its env vars)

profile = get_profile("turbo")
print("Runtime profile:", profile.runtime_profile)
print("Env vars to export:", profile.env_dict())

The returned RuntimeProfile object can be passed directly to lower-level server components such as mtplx.server.openai.Server that expect profile configurations. When you pass None to get_profile(), it defaults to Auto resolution logic.

Available Decode Profiles Reference

MTPLX provides several runtime profiles optimized for different hardware and workload characteristics. Each profile is implemented as a RuntimeProfile dataclass instance in mtplx/profiles.py:

• turbo - The fastest decode profile for quantized flagship models. Enables native_mtp_turbo runtime with MTPLX_NAX_VERIFY=1 and MTPLX_COMPILED_VERIFY=1 environment variables set (lines 616-640).
• sustained - The default safe path for most models. Uses chunked pre-fill and standard fan control to prevent thermal throttling during long-context operations.
• performance-cold - Legacy burst path without fan boost. Suitable for short contexts where immediate throughput matters more than sustained thermal performance.
• performance-cold with --max - Burst mode with fan control allowed. Enable by setting p.fan_control_allowed = True in Python or using the --max CLI flag for short-context benchmarking.
• stable - Conservative compatibility alias that uses exact-staged execution paths for maximum compatibility.
• max-diagnostic - Fan-control diagnostics only; runs the cooling system without loading a model for hardware testing.

RuntimeProfile Implementation Details

All profiles inherit from the RuntimeProfile class defined in mtplx/profiles.py. This class encapsulates the configuration through the following attributes:

• name: The profile identifier string
• runtime_profile: The internal runtime identifier (e.g., native_mtp_turbo)
• summary: Human-readable description of the profile behavior
• env: Tuple of environment variable tuples to export

The TURBO_PROFILE definition (lines 616-640) demonstrates how profiles merge base environments with specific flags:

TURBO_PROFILE = RuntimeProfile(
    name="turbo",
    runtime_profile="native_mtp_turbo",
    summary="Fastest decode profile …",
    env=_merge_env(
        SUSTAINED_PREFILL_ENV,
        {"MTPLX_NAX_VERIFY": "1", "MTPLX_COMPILED_VERIFY": "1", …},
    ),
    # …

)

The get_profile() helper handles the lookup logic, returning the appropriate RuntimeProfile instance while resolving None to Auto mode behavior.

Summary

• MTPLX uses Auto mode by default to select turbo for quantized 27B/9B flagships and sustained for all other models.
• Override automatic selection using the --profile CLI flag or the get_profile() Python function.
• The turbo profile provides the fastest decode path with NAX-verify kernels, while sustained ensures safe long-context execution.
• All profile configurations are defined in mtplx/profiles.py and instantiated as RuntimeProfile objects.
• Use performance-cold with --max for short-context benchmarking with elevated fan speeds.

Frequently Asked Questions

What is the default decode profile in MTPLX?

The default is Auto mode, which resolves to specific profiles based on the model identifier. For quantized 27B/9B Qwen Turbo models, it selects turbo; for all others, it falls back to sustained. This logic executes automatically when starting the engine without the --profile flag.

When should I use the turbo profile versus the sustained profile?

Use turbo when running quantized flagship models (27B/9B Qwen families) where maximum decode throughput is required and you can tolerate higher thermal output. Use sustained for long-context workloads, unquantized models, or any scenario where thermal stability and chunked pre-fill safety are prioritized over raw speed.

How do I enable fan boost for short-context benchmarking?

Activate the performance-cold profile and append the --max flag in the CLI: mtplx start --profile performance-cold --max. In Python, retrieve the profile with get_profile("performance-cold") and set p.fan_control_allowed = True before passing it to the server constructor.

Can I use custom profiles in the Python API?

Yes. Import get_profile from mtplx.profiles and call it with your desired profile name (e.g., get_profile("turbo")). The function returns a RuntimeProfile object that you can pass to server initializers like mtplx.server.openai.Server or use to inspect the environment variables via profile.env_dict().

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}