# qbcompiler.frontend

## Attributes

| Name | Description |
| --- | --- |
| [`logger`](<#logger>) |  |

### logger

```python
logger = get_logger(__name__)
```

## Functions

| Name | Description |
| --- | --- |
| [`mxq_compile`](<#mxq-compile>) | Compile a model into a Mobilint eXeCUtable (MXQ) package for execution on Mobilint NPUs. |
| [`mxq_compile_from_source`](<#mxq-compile-from-source>) | Compile a raw framework model (ONNX / PyTorch / TensorFlow / TF-Lite) into an MXQ package. |
| [`mxq_compile_from_mblt`](<#mxq-compile-from-mblt>) | Compile an existing Mobilint IR (`.mblt`) file into an MXQ package. |
| [`mblt_compile`](<#mblt-compile>) | Export a model to the Mobilint .mblt format without producing an MXQ package. |
| [`mblt_compile_with_callback`](<#mblt-compile-with-callback>) | Compile-to-mblt entry point with progress callbacks. |
| [`mxq_compile_with_callback`](<#mxq-compile-with-callback>) | Compile/quantize entry point with progress callbacks. |

### mxq\_compile

```python
def mxq_compile(
    model,
    target_device: str,
    calib_data_path: Union[str, List[str]] = UNSET,
    save_subgraph_type: int = 0,
    output_subgraph_path="",
    save_path: Union[str, List[str]] = UNSET,
    backend="onnx",
    # -- ModelDict params --
    feed_dict=None,
    dynamic_axes=None,
    multi_shape: Optional[dict] = None,
    yolo_decode_include=False,
    exclude_first_subgraph=False,
    # -- CompileConfig-overridable (UNSET = defer to config) --
    device=UNSET,
    inference_scheme=UNSET,
    use_random_calib=UNSET,
    cpu_offload=UNSET,
    optimize_option=UNSET,
    buffer_mode=UNSET,
    force_npu_input_reposition=UNSET,
    force_npu_output_reposition=UNSET,
    image_channels=UNSET,
    split_blocks=UNSET,
    split_parts=UNSET,
    # -- Config objects --
    config_preset: Optional[str] = None,
    compile_config: Optional[CompileConfig] = None,
    resource_management_config: Optional[ResourceManagementConfig] = None,
    calibration_config: Optional[CalibrationConfig] = None,
    bit_config: Optional[BitConfig] = None,
    llm_config: Optional[LlmConfig] = None,
    hessian_quant_config: Optional[HessianQuantConfig] = None,
    mod_config: Optional[ModConfig] = None,
    equivalent_transformation_config: Optional[EquivalentTransformationConfig] = None,
    search_weight_scale_config: Optional[SearchWeightScaleConfig] = None,
    save_sample_config: Optional[SaveSampleConfig] = None,
    uint8_input_config: Optional[Uint8InputConfig] = None,
    preprocessing_config: Optional[PreprocessingConfig] = None,
    bias_correction=UNSET,
    bias_correction_config: Optional[BiasCorrectionConfig] = None,
    model_part: Optional[str] = None,
    model_part_options: Optional[dict] = None,
    config_save_path: Optional[str] = None,
    *,
    extra_output_config: Optional[ExtraOutputConfig] = None,
    quant_error_report_config: Optional[QuantErrorReportConfig] = None,
    **kwargs,
)
```

Compile a model into a Mobilint eXeCUtable (MXQ) package for execution on Mobilint NPUs.

When no explicit value is provided for a parameter marked with `UNSET`, the default from [CompileConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#compileconfig>) is used. This allows a compile\_config file or object to supply the value without being overridden by function-level defaults.

Configuration is resolved in priority order (highest to lowest):

1. Explicitly passed function arguments
2. Individual sub-config objects (calibration\_config, llm\_config, etc.)
3. kwargs partial overrides (quantization\_method, weight\_dtype, etc.)
4. compile\_config ([CompileConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#compileconfig>) object or JSON/YAML file) or config\_preset
5. [CompileConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#compileconfig>) field defaults

**Parameters**

- `model` — string or model instance. Model path. When using `backend="onnx"`, this should be the path to an ONNX model file. When `backend` is "torchscript", pass the path of a `torch.jit.save` archive (it is exported to ONNX first, so `feed_dict` is required); when "torch", provide a standard PyTorch model. For `backend="tf"`, pass a TensorFlow SavedModel directory, a Keras .keras/.h5 file or a frozen GraphDef .pb. For `backend="tflite"`, pass the .tflite model path. The path of an existing `.mblt` skips parsing and only quantizes. A list or tuple is accepted for one purpose only: multi-shape compilation. Its entries must be existing `.mblt` files that are the sizes of one model -- written by a `multi_shape` compile, or by one [`mblt_compile()`](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.frontend/#mblt-compile>) call per size -- and they are quantized in one call into a single multi-shape `.mxq` (then `calib_data_path` takes one directory per file, in the same order). A list of source models, or of unrelated `.mblt` files, is not a valid input: before quantization the files are checked to be one model at different sizes and the set is refused with the first difference otherwise. Two things are compared. The source model each file records in its provenance (the source file's sha256, the HuggingFace revision, ...): files made from different checkpoints are rejected even when their graphs match. Only fields that pin the weights are grounds for refusal; a backend or class name that disagrees is reported instead, since those also change with where the compile ran. And the graph itself: same NPU/CPU partition, same layer types in graph order (options and weights are not compared, since they legitimately differ per size). A file that records no such identity -- an in-memory torch model leaves only its class name -- is logged as unverified, because for it "same graph" is all that was checked. To compile a source model at several sizes in one call, pass one model with `multi_shape` instead.
- `calib_data_path` — string or list of strings. Path(s) to the calibration dataset. Accepts either a text/json file that lists NumPy files or a directory that contains the pre-processed NumPy files.
- `save_subgraph_type` — int. Controls optional MBLT subgraph exports: 0 disables exports; 1 saves only the graph structure; 2 saves graph structure plus weights; 3 saves the graph structure split into multiple subgraphs; 4 saves both structure and weights split into multiple subgraphs. Defaults to 0.
- `output_subgraph_path` — string. Destination path for the exported .mblt file when `save_subgraph_type` is 1–4. The resulting file can be used for visualization. Defaults to "".
- `save_path` — string or list of strings. Output MXQ filename(s). When omitted, defaults to "{model\_name}.mxq" derived from the model path basename.
- `backend` — string. Framework used to generate the Mobilint IR. Case-insensitive, so "ONNX" and "onnx" are the same backend. "onnx", "torch", "tf" (also spelled "tensorflow" or "keras"), "tflite" and "torchscript" are all parsed by the current parser. Any other value raises `ValueError`. Defaults to "onnx". When `model` is a path to an already-compiled .mblt file (the output of [`mblt_compile()`](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.frontend/#mblt-compile>)), it is compiled directly with MXQ regardless of the `backend` value, and the file is validated beforehand; it must be a runnable artifact produced by [`mblt_compile()`](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.frontend/#mblt-compile>) rather than a `save_subgraph_type` preview export.
- `target_device` — string. Target NPU device for parser/compiler configuration (for example "aries-rb"). Required by execution paths that parse or quantize a model.
- `device` — string. Compilation and inference device: "cpu" or "gpu". When omitted, uses [CompileConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#compileconfig>) default.
- `feed_dict` — dict. Example input tensors for shape inference and inference validation.
- `multi_shape` — dict. Compile the model at several sizes of a dynamic dimension in one call. Keyed by input name like `feed_dict`; each entry names the axis (an int, or a tuple of axes that move together) and the sizes it takes: {"x": {"axis": 3, "values": \[100, 200, 300\]}} or {"x": {"axis": (2, 3), "values": \[(224, 224), (448, 448)\]}}. Requires `feed_dict`: each value yields its own example tensor derived from it, and the model is parsed once per value into its own .mblt. Several inputs are walked together by index, so their "values" lists must be equally long. Cannot be combined with `dynamic_axes`. With `model_part` the part is built once per size from that size's example tensors, so a part that sizes itself from its feed (Qwen3-ASR audio's "mel\_chunk") compiles at every listed size.
- `dynamic_axes` — dict. Marks model axes as dynamic. Keys are input names and values map dimension indices to aliases (for example {"input": {2: "seq\_len"}}).
- `inference_scheme` — string. NPU inference scheme. One of "single", "multi", "global", "global4", or "global8". When omitted, uses [CompileConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#compileconfig>) default.
- `yolo_decode_include` — bool. Determines whether YOLO decode runs on NPU. Defaults to `False`.
- `use_random_calib` — bool. Generates random calibration data to validate model compilability. When omitted, uses [CompileConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#compileconfig>) default.
- `cpu_offload` — bool. Enables CPU offloading during NPU inference. When omitted, uses [CompileConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#compileconfig>) default.
- `optimize_option` — int. Compiler optimization strategy selector. When omitted, uses [CompileConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#compileconfig>) default.
- `buffer_mode` — int. Buffer serialization mode: 0 uses a naive buffer, 1 uses an mmap-backed buffer. When omitted, uses [CompileConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#compileconfig>) default.
- `force_npu_input_reposition` — bool. Force input reposition operations to run on NPU instead of CPU. When omitted, uses [CompileConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#compileconfig>) default.
- `force_npu_output_reposition` — bool. Force output reposition operations to run on NPU instead of CPU. When omitted, uses [CompileConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#compileconfig>) default.
- `image_channels` — int. Number of image channels (0 for auto-detect). When omitted, uses [CompileConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#compileconfig>) default.
- `split_blocks` — list of int. Multi-MXQ split points by transformer block index. Only supported for LLM models. When omitted, uses [CompileConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#compileconfig>) default.
- `split_parts` — int. Evenly split transformer blocks into N MXQ parts. Only supported for LLM models. When omitted, uses [CompileConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#compileconfig>) default.
- `bias_correction` — bool. Enables in-schedule integer bias correction during weight quantization. When omitted, uses `bias_correction_config` or the [CompileConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#compileconfig>) value.
- `exclude_first_subgraph` — bool. Applies only when CPU offloading is enabled: exclude the first subgraph from the final graph if it is unsupported. Defaults to `False`.
- `config_preset` — string. Name of a built-in configuration preset. When provided, loads the preset via [CompileConfig.from\_preset()](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#compileconfig-from-preset>). Defaults to None (no preset). Available presets: - "classification": Image classification models (ResNet, EfficientNet, ViT, etc.) - "detection": Object detection models (YOLO, SSD, DETR, etc.) - "classification\_torchvision": Torchvision classification models with standard preprocessing - "yolo\_640": YOLO detection models with 640x640 letterbox preprocessing - "yolo\_1280": YOLO detection models with 1280x1280 letterbox preprocessing - "llm": Large Language Models (LLaMA, Qwen, Gemma, etc.) - "llm\_fast": LLM with faster compilation (less accuracy optimization) - "vision\_transformer": Vision Transformer models (ViT, DeiT, Swin, etc.) - "multimodal": Multimodal models (CLIP, BLIP, LLaVA, etc.)
- `compile_config` — [CompileConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#compileconfig>) or string. [CompileConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#compileconfig>) object or path to JSON/YAML configuration file containing all compilation settings (resourceManagement, calibration, bit, hessianQuant, mod, llm, etc.).
- `config_save_path` — string. When provided, the fully resolved configuration - the normalized [CompileConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#compileconfig>) after every layer of the precedence order above has been applied, including all sub-configurations - is written to this path before compilation starts. The format follows the path suffix: ".yaml"/".yml" produce YAML, anything else produces JSON. Parent directories are created as needed. The saved file can be fed back as `compile_config` to reproduce the same compilation. Defaults to None (no config file is written).
- `resource_management_config` — [ResourceManagementConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#resourcemanagementconfig>). Resource management configuration object.
- `calibration_config` — [CalibrationConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#calibrationconfig>). Calibration configuration object.
- `bit_config` — [BitConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#bitconfig>). Bit configuration object for quantization precision settings.
- `llm_config` — [LlmConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#llmconfig>). LLM configuration object.
- `hessian_quant_config` — [HessianQuantConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#hessianquantconfig>). HessianQuant (Hessian-based Quantization) configuration object.
- `bias_correction_config` — [BiasCorrectionConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#biascorrectionconfig>). In-schedule integer bias correction settings.
- `model_part` — string. Selects a specific part of a torch model to parse ("vision", "language", "encoder", ...). Typically used to support models with complex architectures (e.g. Qwen3-VL) by compiling one part at a time. Parts a model declares: parser.patcher.parts.available\_parts(model). A model declaring exactly one part resolves it from None; one declaring several requires a name.
- `model_part_options` — dict. Extra arguments for the named part (e.g. {"mel\_frames": 100} for Qwen3-ASR audio).
- `mod_config` — [ModConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#modconfig>). MOD (Metric-based Optimization and Distillation) configuration object.
- `equivalent_transformation_config` — [EquivalentTransformationConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#equivalenttransformationconfig>). Configuration for equivalent transformations like SmoothQuant.
- `search_weight_scale_config` — [SearchWeightScaleConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#searchweightscaleconfig>). Configuration for weight scale search.
- `save_sample_config` — [SaveSampleConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#savesampleconfig>). Configuration for sample data generation and saving.
- `uint8_input_config` — [Uint8InputConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#uint8inputconfig>). Configuration for uint8 input handling.
- `preprocessing_config` — [PreprocessingConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#preprocessingconfig>). Preprocessing pipeline configuration.
- `extra_output_config` — [ExtraOutputConfig](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.configs.models/#extraoutputconfig>). Promote named intermediate layers to extra model outputs. Keyword-only. Names are matched against the post-fusion graph, after quantization, so a layer the graph optimizer folded away is rejected by name.
- `quant_error_report_config` — QuantErrorReportConfig. Keyword-only. With apply=True, draw a per-layer quantization error report after quantization as "\<MXQ name\>\_quant\_error\_report.pdf" beside the first MXQ, or one "\<MXQ name\>\_quant\_error\_report\_model\<i\>.pdf" per model of a multi-shape compile. The report compares the float and the quantized model on max\_samples calibration samples, so it is a diagnostic aid, not an accuracy guarantee. It needs matplotlib and does not support group-wise quantization yet.
- `kwargs` — dict. Additional compiler arguments. Supports partial config overrides such as `quantization_method`, `quantization_mode`, `percentile`, `weight_dtype`, `ram_usage`, `max_sequence_length`, etc. Also accepts deprecated parameters (`quantization_config`, `advanced_quantization_config`, `input_process_config`, `save_sample`, `sample_dtype`) which will emit DeprecationWarning.

**Returns**

None.

**Using configuration**

There are three ways to configure quantization settings:

1. Load all settings from a JSON/YAML config file:

   ```py
   from qbcompiler import mxq_compile

   mxq_compile(
       model="path/to/model.onnx",
       target_device="aries-rb",
       calib_data_path="path/to/calib",
       compile_config="path/to/config.json",  # or config.yaml
       device="gpu",
   )
   ```
2. Pass individual sub-config objects:

   ```py
   from qbcompiler import mxq_compile
   from qbcompiler.configs import (
       ResourceManagementConfig,
       CalibrationConfig,
       BitConfig,
       HessianQuantConfig,
       ModConfig,
       LlmConfig,
   )

   resource_mgmt = ResourceManagementConfig(weight_dtype="float32")
   calib_cfg = CalibrationConfig(method=1, mode=1)
   bit_cfg = BitConfig(...)
   hessian_quant_cfg = HessianQuantConfig(apply=True)
   mod_cfg = ModConfig(apply=False)
   llm_cfg = LlmConfig(apply=True)

   mxq_compile(
       model="path/to/model.onnx",
       target_device="aries-rb",
       calib_data_path="path/to/calib",
       resource_management_config=resource_mgmt,
       calibration_config=calib_cfg,
       bit_config=bit_cfg,
       hessian_quant_config=hessian_quant_cfg,
       mod_config=mod_cfg,
       llm_config=llm_cfg,
       device="gpu",
   )
   ```
3. Automatically applied partial configuration overrides:

   ```py
   from qbcompiler import mxq_compile

   mxq_compile(
       model="path/to/model.onnx",
       target_device="aries-rb",
       calib_data_path="path/to/calib",
       quantization_method=1, # per channel quantization
       quantization_mode=1, # max percentile quantization
       percentile=0.999, # percentile value for max percentile quantization
       quantization_output=0, # per layer quantization for the output layer
       device="gpu",
   )
   ```

Please refer to the mxq\_compile function and the quantization configuration section for the meaning of the quantization-related numeric values.

**Compiling models with custom inputs (ONNX/Torch/TensorFlow)**

Provide NumPy inputs whenever the model omits shape information so that qbcompiler can infer unknown dimensions and data formats.

```py
from qbcompiler import mxq_compile
import numpy as np

example_input = {
    "input_node_name_1": np.random.randn(1, 3, 224, 224).astype(np.float32),
    "input_node_name_2": np.random.randn(1, 8, 224, 224).astype(np.float32),
    "input_node_name_3": np.random.randn(1, 4, 56, 56).astype(np.float32),
}

onnx_model_path = "path/to/your/model.onnx"
mxq_compile(
    model=onnx_model_path,
    target_device="aries-rb",
    feed_dict=example_input,
    backend="onnx",
    compile_config="path/to/config.json",
)
```

### mxq\_compile\_from\_source

```python
def mxq_compile_from_source(
    model,
    target_device: str,
    calib_data_path: Union[str, List[str]] = UNSET,
    save_subgraph_type: int = 0,
    output_subgraph_path="",
    save_path: Union[str, List[str]] = UNSET,
    backend="onnx",
    # -- ModelDict params --
    feed_dict=None,
    dynamic_axes=None,
    multi_shape: Optional[dict] = None,
    yolo_decode_include=False,
    exclude_first_subgraph=False,
    # -- CompileConfig-overridable (UNSET = defer to config) --
    device=UNSET,
    inference_scheme=UNSET,
    use_random_calib=UNSET,
    cpu_offload=UNSET,
    optimize_option=UNSET,
    buffer_mode=UNSET,
    force_npu_input_reposition=UNSET,
    force_npu_output_reposition=UNSET,
    image_channels=UNSET,
    split_blocks=UNSET,
    split_parts=UNSET,
    # -- Config objects --
    config_preset: Optional[str] = None,
    compile_config: Optional[CompileConfig] = None,
    resource_management_config: Optional[ResourceManagementConfig] = None,
    calibration_config: Optional[CalibrationConfig] = None,
    bit_config: Optional[BitConfig] = None,
    llm_config: Optional[LlmConfig] = None,
    hessian_quant_config: Optional[HessianQuantConfig] = None,
    mod_config: Optional[ModConfig] = None,
    equivalent_transformation_config: Optional[EquivalentTransformationConfig] = None,
    search_weight_scale_config: Optional[SearchWeightScaleConfig] = None,
    save_sample_config: Optional[SaveSampleConfig] = None,
    uint8_input_config: Optional[Uint8InputConfig] = None,
    preprocessing_config: Optional[PreprocessingConfig] = None,
    bias_correction=UNSET,
    bias_correction_config: Optional[BiasCorrectionConfig] = None,
    model_part: Optional[str] = None,
    model_part_options: Optional[dict] = None,
    config_save_path: Optional[str] = None,
    *,
    extra_output_config: Optional[ExtraOutputConfig] = None,
    quant_error_report_config: Optional[QuantErrorReportConfig] = None,
    **kwargs,
)
```

Compile a raw framework model (ONNX / PyTorch / TensorFlow / TF-Lite) into an MXQ package.

This is the raw-model half of [`mxq_compile()`](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.frontend/#mxq-compile>): it parses the model into Mobilint IR and then quantizes and compiles it in one pass. The parameters, their defaults, and the configuration precedence rules are identical to [`mxq_compile()`](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.frontend/#mxq-compile>) — see that function for the full reference and usage examples.

Passing the path of an existing `.mblt` file here raises `ValueError`; use [`mxq_compile_from_mblt()`](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.frontend/#mxq-compile-from-mblt>) for that input instead. [`mxq_compile()`](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.frontend/#mxq-compile>) routes between the two automatically.

**Parameters**

- `model` — string or model instance. Raw model or path to one. Must not be an existing `.mblt` file.
- `target_device` — string. Target NPU device (for example "aries-rb").

**Returns**

None.

### mxq\_compile\_from\_mblt

```python
def mxq_compile_from_mblt(
    mblt: str | list[str],
    target_device: str,
    calib_data_path: Union[str, List[str]] = UNSET,
    save_path: Union[str, List[str]] = UNSET,
    backend="onnx",
    device=UNSET,
    inference_scheme=UNSET,
    use_random_calib=UNSET,
    cpu_offload=UNSET,
    optimize_option=UNSET,
    buffer_mode=UNSET,
    force_npu_input_reposition=UNSET,
    force_npu_output_reposition=UNSET,
    image_channels=UNSET,
    split_blocks=UNSET,
    split_parts=UNSET,
    config_preset: Optional[str] = None,
    compile_config: Optional[CompileConfig] = None,
    resource_management_config: Optional[ResourceManagementConfig] = None,
    calibration_config: Optional[CalibrationConfig] = None,
    bit_config: Optional[BitConfig] = None,
    llm_config: Optional[LlmConfig] = None,
    hessian_quant_config: Optional[HessianQuantConfig] = None,
    mod_config: Optional[ModConfig] = None,
    equivalent_transformation_config: Optional[EquivalentTransformationConfig] = None,
    search_weight_scale_config: Optional[SearchWeightScaleConfig] = None,
    save_sample_config: Optional[SaveSampleConfig] = None,
    uint8_input_config: Optional[Uint8InputConfig] = None,
    preprocessing_config: Optional[PreprocessingConfig] = None,
    bias_correction=UNSET,
    bias_correction_config: Optional[BiasCorrectionConfig] = None,
    config_save_path: Optional[str] = None,
    *,
    extra_output_config: Optional[ExtraOutputConfig] = None,
    quant_error_report_config: Optional[QuantErrorReportConfig] = None,
    **kwargs,
)
```

Compile an existing Mobilint IR (`.mblt`) file into an MXQ package.

This is the pre-parsed half of [`mxq_compile()`](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.frontend/#mxq-compile>): parsing already happened (via [`mblt_compile()`](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.frontend/#mblt-compile>)), so this function only quantizes and compiles. Quantization parameters, their defaults, and the configuration precedence rules are identical to [`mxq_compile()`](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.frontend/#mxq-compile>) — see that function for the full reference and usage examples.

Parser-only arguments (`save_subgraph_type`, `output_subgraph_path`, `feed_dict`, `dynamic_axes`, `multi_shape`, `yolo_decode_include`, `exclude_first_subgraph`) are absent because the graph is already parsed. [`mxq_compile()`](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.frontend/#mxq-compile>) accepts them for backward compatibility and drops them when routing here; either entry point logs a warning naming the ones that were given, so a `multi_shape` or `feed_dict` that cannot apply is not mistaken for one that did.

**Parameters**

- `mblt` — string or list of strings. Path to a runnable `.mblt` produced by [`mblt_compile()`](<https://docs.mobilint.com/compiler/en/v1.4/api/python/qbcompiler.frontend/#mblt-compile>); the file is validated up front and a `save_subgraph_type` preview export is rejected. Or a list of such paths: every file is quantized in one call and packed into a single `.mxq`, as a `multi_shape` compile does with the files it writes per size, and `calib_data_path` takes one calibration directory per file, in the same order. The files must be one graph at different sizes; before quantization the pipeline checks that every file has the same NPU/CPU partition and the same layer types in graph order, and refuses the set with the first difference otherwise. Options and weights are not compared -- shape-dependent options and constant folding legitimately differ per size.
- `target_device` — string. Target NPU device (for example "aries-rb").
- `backend` — string. Retained for backward compatibility and ignored: the graph is already parsed, so no parser backend is selected.

**Returns**

None.

**Throws**

- `ValueError` — `mblt` is not an existing `.mblt` file, or a list has an entry that is not one; a file is not a runnable artifact for the requested `cpu_offload` setting; or the files of a list are not the same graph.

### mblt\_compile

```python
def mblt_compile(
    model: str | Any,
    mblt_save_path: str | list[str],
    target_device: str,
    backend="onnx",
    device="cpu",
    feed_dict=None,
    dynamic_axes=None,
    multi_shape: Optional[dict] = None,
    yolo_decode_include=False,
    cpu_offload=False,
    exclude_first_subgraph=False,
    model_part: Optional[str] = None,
    model_part_options: Optional[dict] = None,
    **kwargs,
)
```

Export a model to the Mobilint .mblt format without producing an MXQ package.

**Parameters**

- `model` — string or model instance. Source model or path to compile.
- `mblt_save_path` — string or list of strings. Output path for the .mblt artifact; with `multi_shape`, one path per value.
- `backend` — string. Framework identifier, case-insensitive. "onnx", "torch", "tf" (also spelled "tensorflow" or "keras"), "tflite" and "torchscript" are all parsed by the current parser; a "torchscript" archive is exported to ONNX first and needs `feed_dict`. Any other value raises `ValueError`. Defaults to "onnx".
- `device` — string. Compilation device ("cpu" or "gpu"). Defaults to "cpu".
- `feed_dict` — dict. Example inputs used for shape inference.
- `multi_shape` — dict. Compile the model at several sizes of a dynamic dimension in one call. Keyed by input name like `feed_dict`; each entry names the axis (an int, or a tuple of axes that move together) and the sizes it takes: {"x": {"axis": 3, "values": \[100, 200, 300\]}} or {"x": {"axis": (2, 3), "values": \[(224, 224), (448, 448)\]}}. Requires `feed_dict`: each value yields its own example tensor derived from it, and the model is parsed once per value into its own .mblt. Several inputs are walked together by index, so their "values" lists must be equally long. Pass one `mblt_save_path` per value (a list), or a single path to get \<stem\>\_\<i\>.mblt. Cannot be combined with `dynamic_axes`. With `model_part` the part is built once per size from that size's example tensors, so a part that sizes itself from its feed (Qwen3-ASR audio's "mel\_chunk") compiles at every listed size.
- `dynamic_axes` — dict. Declares dynamic axes per input name.
- `yolo_decode_include` — bool. Runs YOLO decode on NPU when True.
- `cpu_offload` — bool. Enables CPU offloading for unsupported groups.
- `exclude_first_subgraph` — bool. Applies only when CPU offloading is enabled: exclude the first subgraph from the final graph if it is unsupported.
- `model_part` — string. Selects a specific part of a torch model to parse ("vision", "language", "encoder", ...). Typically used to support models with complex architectures (e.g. Qwen3-VL) by compiling one part at a time. Parts a model declares: parser.patcher.parts.available\_parts(model). A model declaring exactly one part resolves it from None; one declaring several requires a name.
- `model_part_options` — dict. Extra arguments for the named part (e.g. {"mel\_frames": 100} for Qwen3-ASR audio).
- `kwargs` — dict. Additional arguments forwarded to the compiler.

**Returns**

None.

### mblt\_compile\_with\_callback

```python
def mblt_compile_with_callback(
    model: str,
    mblt_save_path: str,
    target_device: str,
    backend: str = "onnx",
    device: Optional[str] = None,
    cpu_offload: Optional[bool] = None,
    config_preset: Optional[str] = None,
    compile_config: Optional[CompileConfig | str] = None,
    compilation_mode: Optional[str] = None,
    *,
    progress_callback: Callable[[int, str], None],
) -> None
```

Compile-to-mblt entry point with progress callbacks.

Only forwards explicitly-set values so the `UNSET` defaults (and the merged `[CompileConfig](qbcompiler.configs.models.md#compileconfig)` behind them) apply when the caller omits a flag -- which is why this goes through `_mblt_compile_dispatch` rather than :func:`mblt_compile`, whose own `device` / `cpu_offload` defaults would override the config. `target_device` is required and has no config fallback — callers (e.g. the CLI) validate it via `validate_target_device` before invoking (QC-228).

### mxq\_compile\_with\_callback

```python
def mxq_compile_with_callback(
    model: str,
    target_device: str,
    save_path: str,
    backend: str = "onnx",
    device: Optional[str] = None,
    calib_data_path: Optional[Union[str, List[str]]] = None,
    use_random_calib: Optional[bool] = None,
    config_preset: Optional[str] = None,
    compile_config: Optional[CompileConfig | str] = None,
    config_save_path: Optional[str] = None,
    *,
    progress_callback: Callable[[int, str], None],
) -> None
```

Compile/quantize entry point with progress callbacks.

`target_device` is required and has no config fallback — callers (e.g. the CLI) validate it via `validate_target_device` before invoking, and the wrapper forwards it unconditionally (QC-228).

Like :func:`mblt_compile_with_callback`, only explicitly-set values are forwarded, so :func:`mxq_compile`'s `UNSET` defaults (and the merged `[CompileConfig](qbcompiler.configs.models.md#compileconfig)` behind them) still apply to whatever the caller omits. `config_save_path` passes straight through, and the resolved config is written there before compilation starts; this is what backs the CLI's `--config-save-path` on `quantize` / `compile`.
