Compile Configuration

Compile Configuration#

First Compile showed the shortest path from a model to an MXQ. This chapter explains how to control that path with compile configuration.

qb Compiler accepts configuration in three ways:

  • Config preset — a built-in starting point for a model family

  • Config file — a JSON or YAML file with compile settings

  • Python sub-config objects — typed config objects passed to the Python API

Use presets for common model families, config files for repeatable builds, and Python sub-config objects for scripted workflows.

Config Presets#

A preset is a named, built-in partial configuration for a common model family. It sets calibration, quantization, preprocessing, and model-family defaults so you do not need to specify every field.

List the presets available in the installed package:

python -m qbcompiler presets

Using a preset#

From the CLI, pass --config-preset:

python -m qbcompiler compile \
  --model resnet50.onnx \
  --backend onnx \
  --target-device regulus-rb \
  --config-preset classification \
  --calib-data-path ./calib_resnet50 \
  --output resnet50.mxq

From Python, pass config_preset:

from qbcompiler import mxq_compile

mxq_compile(
    model="resnet50.onnx",
    backend="onnx",
    target_device="regulus-rb",
    config_preset="classification",
    calib_data_path="./calib_resnet50",
    save_path="resnet50.mxq",
)

Presets are starting points, not model identifiers. A preset does not remove the need to provide the correct model path, backend, target device, input information, and calibration data. For model-family-specific preset usage, see Vision and Transformer. For the full preset list and what each preset sets, see Reference — Preset List.

dump-config: Generate a Config Template#

dump-config writes a fully expanded CompileConfig to a JSON or YAML file. Use it to see every available field and its default value, or to inspect what a preset changes.

Generate a default template#

python -m qbcompiler dump-config --output compile_config.json

Generate a preset-based template#

python -m qbcompiler dump-config --preset yolo_640 --output yolo_640_config.yaml

The output format is chosen by file extension: .yaml or .yml produces YAML, anything else produces JSON.

Workflow: dump → edit → compile#

  1. Generate a template from a preset that matches your model family.

  2. Open the file and change only the fields you need to override.

  3. Pass the edited file to compile or quantize with --compile-config.

# 1. Generate
python -m qbcompiler dump-config --preset classification --output my_config.yaml

# 2. Edit my_config.yaml (change calibration, bit settings, etc.)

# 3. Compile with the edited config
python -m qbcompiler compile \
  --model resnet50.onnx \
  --backend onnx \
  --target-device regulus-rb \
  --compile-config my_config.yaml \
  --calib-data-path ./calib_resnet50 \
  --output resnet50.mxq

Before using a config in automation, compare the generated template against the default to confirm which values came from the preset and which came from your edits.

Custom Config File#

A compile config file is useful when a build must be repeatable. Keep it in version control next to the model export recipe.

CLI usage#

Pass the file path with --compile-config:

python -m qbcompiler compile \
  --model model.onnx \
  --backend onnx \
  --target-device regulus-rb \
  --compile-config my_config.json \
  --calib-data-path ./calib \
  --output model.mxq

Python usage#

Pass the file path as the compile_config argument:

from qbcompiler import mxq_compile

mxq_compile(
    model="resnet50.onnx",
    target_device="regulus-rb",
    calib_data_path="./calib_resnet50",
    save_path="resnet50.mxq",
    backend="onnx",
    compile_config="resnet50_compile_config.json",
)

The config file contains compile settings only. Model path, calibration data path, target device, backend, and output path remain normal CLI or Python arguments. JSON and YAML files are interchangeable when they contain the same fields. The file must contain only supported CompileConfig fields; do not include metadata keys such as $preset, $description, or $skipValidation.

A preset and a config file can be used together. The preset provides the base, and the config file overrides specific values on top.

When editing generated config files, inferenceScheme controls the runtime core mode prepared into the MXQ. single, multi, global4, and global8 map to different ARIES core-collaboration modes; see Reference — inferenceScheme for the supported values and detailed core-mode links.

For the full CompileConfig schema and field descriptions, see Reference — CompileConfig Schema.

Python Sub-Config Objects#

The Python API provides typed sub-config objects for specialized areas. Use them when writing reusable compile scripts:

from qbcompiler import mxq_compile
from qbcompiler.configs import CalibrationConfig, BitConfig

mxq_compile(
    model="resnet50.onnx",
    backend="onnx",
    target_device="regulus-rb",
    calib_data_path="./calib_resnet50",
    save_path="resnet50.mxq",
    config_preset="classification",
    calibration_config=CalibrationConfig(mode=1, output=0),
    bit_config=BitConfig(
        transformer=BitConfig.Transformer(
            weight=BitConfig.Transformer.Weight(
                query=8, key=8, value=8, output=8, ffn=8, head=8,
            ),
        ),
    ),
)

Sub-config objects override the corresponding section of the preset or config file. This makes it easy to keep model-family defaults from a preset while adjusting specific quantization or LLM settings in code.

Available sub-config objects include CalibrationConfig, BitConfig, LlmConfig, HessianQuantConfig, ModConfig, EquivalentTransformationConfig, SearchWeightScaleConfig, Uint8InputConfig, PreprocessingConfig, and SaveSampleConfig. For the role and tuning order of each quantization sub-config, see Model Quantization — Quantization Configuration.

Config Resolution Priority#

When the same setting is provided in more than one place, the effective value follows this priority (highest wins):

  1. Explicit CLI or Python API arguments

  2. Individual sub-config objects

  3. compile_config file

  4. config_preset

  5. CompileConfig defaults

Use this layering deliberately: put stable model-family choices in the preset, project-specific choices in the config file, and one-off experiment values on the command line or in the Python call.

When in doubt, use dump-config to inspect the resolved configuration before running a build.