frontend.py Source File

frontend.py Source File#

Mobilint SDK qb Compiler: frontend.py Source File
Mobilint SDK qb Compiler v1.4
MCS002-EN
 
import warnings
from collections.abc import Callable
from typing import Any, List, Optional, Union
 
import torch
from qbcompiler.compiler.execution import (
    execute_mblt_compile_request,
    execute_quantize_request,
    missing_mblt_entries_message,
)
from qbcompiler.compiler.utils import validate_target_device
from qbcompiler.configs import (
    CompileConfig,
    CalibrationConfig,
    BitConfig,
    ResourceManagementConfig,
    HessianQuantConfig,
    BiasCorrectionConfig,
    ModConfig,
    LlmConfig,
    EquivalentTransformationConfig,
    SearchWeightScaleConfig,
    SaveSampleConfig,
    Uint8InputConfig,
    ExtraOutputConfig,
    PreprocessingConfig,
)
from qbcompiler.model_dict.backends import (
    MODEL_DICT_BACKENDS,
    normalize_backend,
)
from qbcompiler.compile_requests import (
    UNSET,
    MxqCompileResolveRequest,
    build_mblt_compile_request,
    build_quantize_request,
)
from qbcompiler.artifact.input import (
    is_existing_mblt_input,
    is_existing_mblt_list,
    take_parse_only_args,
    warn_parse_args_ignored_for_mblt,
)
from qbcompiler.config_resolver import ConfigManager, save_compile_config
from qbcompiler.config_resolver.deprecations import reject_removed_kwargs
from qbcompiler.reporting.logging import get_logger
from qbcompiler.reporting.progress import emit_progress, progress_context
 
logger = get_logger(__name__)
 
 
 
 
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,
    **kwargs,
):
    """
    @brief Compile a model into a Mobilint eXeCUtable (MXQ) package for execution on Mobilint NPUs.
 
    @details When no explicit value is provided for a parameter marked with @c UNSET, the default
    from 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 object or JSON/YAML file) or config_preset
    5. CompileConfig field defaults
 
    @param model string or model instance. Model path. When using @c backend="onnx", this should be the path to an ONNX
    model file. When @c backend is "torchscript", pass the path of a @c torch.jit.save archive (it is exported to ONNX
    first, so @p feed_dict is required); when "torch", provide a standard PyTorch model. For @c backend="tf", pass a
    TensorFlow SavedModel directory, a Keras .keras/.h5 file or a frozen GraphDef .pb. For @c backend="tflite", pass
    the .tflite model path. The path of an existing @c .mblt skips parsing and only quantizes.
    A list or tuple is accepted for one purpose only: multi-shape compilation. Its entries must be existing @c .mblt
    files that are the sizes of one model -- written by a @p multi_shape compile, or by one @c mblt_compile() call per
    size -- and they are quantized in one call into a single multi-shape @c .mxq (then @p calib_data_path takes one
    directory per file, in the same order). A list of source models, or of unrelated @c .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 @p multi_shape instead.
    @param 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.
    @param 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.
    @param output_subgraph_path string. Destination path for the exported .mblt file when @p save_subgraph_type is 1–4.
    The resulting file can be used for visualization. Defaults to "".
    @param save_path string or list of strings. Output MXQ filename(s). When omitted, defaults to "{model_name}.mxq"
    derived from the model path basename.
    @param 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 @c ValueError. Defaults to "onnx". When @p model is a path to an already-compiled .mblt file (the
    output of @c mblt_compile()), it is compiled directly with MXQ regardless of the @p backend value,
    and the file is validated beforehand; it must be a runnable
    artifact produced by @c mblt_compile() rather than a @c save_subgraph_type preview export.
    @param target_device string. Target NPU device for parser/compiler configuration (for example "aries-rb"). Required by execution paths that parse or quantize a model.
    @param device string. Compilation and inference device: "cpu" or "gpu". When omitted, uses CompileConfig default.
    @param feed_dict dict. Example input tensors for shape inference and inference validation.
    @param multi_shape dict. Compile the model at several sizes of a dynamic dimension in one call. Keyed by input
    name like @p 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 @p 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 @p dynamic_axes. With @p 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.
    @param 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"}}).
    @param inference_scheme string. NPU inference scheme. One of "single", "multi", "global", "global4", or
    "global8". When omitted, uses CompileConfig default.
    @param yolo_decode_include bool. Determines whether YOLO decode runs on NPU. Defaults to @c False.
    @param use_random_calib bool. Generates random calibration data to validate model compilability.
    When omitted, uses CompileConfig default.
    @param cpu_offload bool. Enables CPU offloading during NPU inference. When omitted, uses CompileConfig default.
    @param optimize_option int. Compiler optimization strategy selector. When omitted, uses CompileConfig default.
    @param buffer_mode int. Buffer serialization mode: 0 uses a naive buffer, 1 uses an mmap-backed buffer.
    When omitted, uses CompileConfig default.
    @param force_npu_input_reposition bool. Force input reposition operations to run on NPU instead of CPU.
    When omitted, uses CompileConfig default.
    @param force_npu_output_reposition bool. Force output reposition operations to run on NPU instead of CPU.
    When omitted, uses CompileConfig default.
    @param image_channels int. Number of image channels (0 for auto-detect).
    When omitted, uses CompileConfig default.
    @param split_blocks list of int. Multi-MXQ split points by transformer block index.
    Only supported for LLM models. When omitted, uses CompileConfig default.
    @param split_parts int. Evenly split transformer blocks into N MXQ parts.
    Only supported for LLM models. When omitted, uses CompileConfig default.
    @param bias_correction bool. Enables in-schedule integer bias correction during weight quantization.
    When omitted, uses @p bias_correction_config or the CompileConfig value.
    @param 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 @c False.
    @param config_preset string. Name of a built-in configuration preset. When provided, loads the preset
    via 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.)
    @param compile_config CompileConfig or string. CompileConfig object or path to JSON/YAML configuration file
    containing all compilation settings (resourceManagement, calibration, bit, hessianQuant, mod, llm, etc.).
    @param config_save_path string. When provided, the fully resolved configuration - the normalized
    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 @p compile_config to reproduce the same compilation.
    Defaults to None (no config file is written).
    @param resource_management_config ResourceManagementConfig. Resource management configuration object.
    @param calibration_config CalibrationConfig. Calibration configuration object.
    @param bit_config BitConfig. Bit configuration object for quantization precision settings.
    @param llm_config LlmConfig. LLM configuration object.
    @param hessian_quant_config HessianQuantConfig. HessianQuant (Hessian-based Quantization) configuration object.
    @param bias_correction_config BiasCorrectionConfig. In-schedule integer bias correction settings.
    @param 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.
    @param model_part_options dict. Extra arguments for the named part (e.g. {"mel_frames": 100} for Qwen3-ASR audio).
    @param mod_config ModConfig. MOD (Metric-based Optimization and Distillation) configuration object.
    @param equivalent_transformation_config EquivalentTransformationConfig. Configuration for equivalent
    transformations like SmoothQuant.
    @param search_weight_scale_config SearchWeightScaleConfig. Configuration for weight scale search.
    @param save_sample_config SaveSampleConfig. Configuration for sample data generation and saving.
    @param uint8_input_config Uint8InputConfig. Configuration for uint8 input handling.
    @param preprocessing_config PreprocessingConfig. Preprocessing pipeline configuration.
    @param extra_output_config 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.
    @param kwargs dict. Additional compiler arguments. Supports partial config overrides such as
    @c quantization_method, @c quantization_mode, @c percentile, @c weight_dtype, @c ram_usage,
    @c max_sequence_length, etc. Also accepts deprecated parameters (@c quantization_config,
    @c advanced_quantization_config, @c input_process_config, @c save_sample, @c sample_dtype)
    which will emit DeprecationWarning.
    @return None.
 
    @par Using configuration
    There are three ways to configure quantization settings:
 
    1. Load all settings from a JSON/YAML config file:
    @code{.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",
    )
    @endcode
 
    2. Pass individual sub-config objects:
    @code{.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",
    )
    @endcode
 
    3. Automatically applied partial configuration overrides:
    @code{.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",
    )
    @endcode
    Please refer to the mxq_compile function and the quantization configuration section for the meaning of the quantization-related numeric values.
 
 
    @par 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.
 
    @code{.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",
    )
    @endcode
    """
    target_device = validate_target_device(target_device)
    reject_removed_kwargs(kwargs)
 
    if isinstance(model, (list, tuple)) or is_existing_mblt_input(model):
        # A list is several already-parsed .mblt files: mxq_compile_from_mblt
        # checks that every one exists, and its pipeline that they are one graph.
        if model_part is not None or model_part_options is not None:
            raise ValueError(
                "model_part / model_part_options apply to parsing a live model; "
                f"{model!r} is an already-parsed .mblt. Pass the part when "
                "producing the mblt (mblt_compile), or pass the source model here."
            )
        # The parser-only arguments below are not forwarded; say so rather than
        # letting a caller believe multi_shape or feed_dict took effect.
        warn_parse_args_ignored_for_mblt(
            "mxq_compile()",
            feed_dict=feed_dict,
            dynamic_axes=dynamic_axes,
            multi_shape=multi_shape,
            yolo_decode_include=yolo_decode_include,
            exclude_first_subgraph=exclude_first_subgraph,
            save_subgraph_type=save_subgraph_type,
            output_subgraph_path=output_subgraph_path,
        )
        mxq_compile_from_mblt(
            mblt=model,
            calib_data_path=calib_data_path,
            save_path=save_path,
            backend=backend,
            device=device,
            inference_scheme=inference_scheme,
            use_random_calib=use_random_calib,
            cpu_offload=cpu_offload,
            optimize_option=optimize_option,
            buffer_mode=buffer_mode,
            force_npu_input_reposition=force_npu_input_reposition,
            force_npu_output_reposition=force_npu_output_reposition,
            image_channels=image_channels,
            split_blocks=split_blocks,
            split_parts=split_parts,
            config_preset=config_preset,
            compile_config=compile_config,
            resource_management_config=resource_management_config,
            calibration_config=calibration_config,
            bit_config=bit_config,
            llm_config=llm_config,
            hessian_quant_config=hessian_quant_config,
            mod_config=mod_config,
            equivalent_transformation_config=equivalent_transformation_config,
            search_weight_scale_config=search_weight_scale_config,
            save_sample_config=save_sample_config,
            uint8_input_config=uint8_input_config,
            preprocessing_config=preprocessing_config,
            extra_output_config=extra_output_config,
            bias_correction=bias_correction,
            bias_correction_config=bias_correction_config,
            config_save_path=config_save_path,
            target_device=target_device,
            **kwargs,
        )
        return
 
    mxq_compile_from_source(
        model=model,
        calib_data_path=calib_data_path,
        save_subgraph_type=save_subgraph_type,
        output_subgraph_path=output_subgraph_path,
        save_path=save_path,
        backend=backend,
        feed_dict=feed_dict,
        dynamic_axes=dynamic_axes,
        multi_shape=multi_shape,
        yolo_decode_include=yolo_decode_include,
        exclude_first_subgraph=exclude_first_subgraph,
        device=device,
        inference_scheme=inference_scheme,
        use_random_calib=use_random_calib,
        cpu_offload=cpu_offload,
        optimize_option=optimize_option,
        buffer_mode=buffer_mode,
        force_npu_input_reposition=force_npu_input_reposition,
        force_npu_output_reposition=force_npu_output_reposition,
        image_channels=image_channels,
        split_blocks=split_blocks,
        split_parts=split_parts,
        config_preset=config_preset,
        compile_config=compile_config,
        resource_management_config=resource_management_config,
        calibration_config=calibration_config,
        bit_config=bit_config,
        llm_config=llm_config,
        hessian_quant_config=hessian_quant_config,
        mod_config=mod_config,
        equivalent_transformation_config=equivalent_transformation_config,
        search_weight_scale_config=search_weight_scale_config,
        save_sample_config=save_sample_config,
        uint8_input_config=uint8_input_config,
        preprocessing_config=preprocessing_config,
        extra_output_config=extra_output_config,
        bias_correction=bias_correction,
        bias_correction_config=bias_correction_config,
        model_part=model_part,
        model_part_options=model_part_options,
        config_save_path=config_save_path,
        target_device=target_device,
        **kwargs,
    )
 
 
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,
    **kwargs,
):
    """
    @brief Compile a raw framework model (ONNX / PyTorch / TensorFlow / TF-Lite) into an MXQ package.
 
    @details This is the raw-model half of @c 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 @c mxq_compile() —
    see that function for the full reference and usage examples.
 
    Passing the path of an existing @c .mblt file here raises @c ValueError; use
    @c mxq_compile_from_mblt() for that input instead. @c mxq_compile() routes between
    the two automatically.
 
    @param model string or model instance. Raw model or path to one. Must not be an
    existing @c .mblt file.
    @param target_device string. Target NPU device (for example "aries-rb").
    @return None.
    """
    if isinstance(model, (list, tuple)) or is_existing_mblt_input(model):
        raise ValueError(
            "mxq_compile_from_source() does not accept an existing .mblt file. Call "
            "mxq_compile_from_mblt() instead, or mxq_compile() to route automatically."
        )
 
    target_device = validate_target_device(target_device)
    backend = normalize_backend(backend)
    reject_removed_kwargs(kwargs)
 
    _mxq_compile_pipeline(
        model=model,
        calib_data_path=calib_data_path,
        save_subgraph_type=save_subgraph_type,
        output_subgraph_path=output_subgraph_path,
        save_path=save_path,
        backend=backend,
        target_device=target_device,
        feed_dict=feed_dict,
        dynamic_axes=dynamic_axes,
        multi_shape=multi_shape,
        yolo_decode_include=yolo_decode_include,
        exclude_first_subgraph=exclude_first_subgraph,
        device=device,
        inference_scheme=inference_scheme,
        use_random_calib=use_random_calib,
        cpu_offload=cpu_offload,
        optimize_option=optimize_option,
        buffer_mode=buffer_mode,
        force_npu_input_reposition=force_npu_input_reposition,
        force_npu_output_reposition=force_npu_output_reposition,
        image_channels=image_channels,
        split_blocks=split_blocks,
        split_parts=split_parts,
        bias_correction=bias_correction,
        config_preset=config_preset,
        compile_config=compile_config,
        config_save_path=config_save_path,
        resource_management_config=resource_management_config,
        calibration_config=calibration_config,
        bit_config=bit_config,
        llm_config=llm_config,
        hessian_quant_config=hessian_quant_config,
        bias_correction_config=bias_correction_config,
        mod_config=mod_config,
        equivalent_transformation_config=equivalent_transformation_config,
        search_weight_scale_config=search_weight_scale_config,
        save_sample_config=save_sample_config,
        uint8_input_config=uint8_input_config,
        preprocessing_config=preprocessing_config,
        extra_output_config=extra_output_config,
        model_part=model_part,
        model_part_options=model_part_options,
        **kwargs,
    )
 
 
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,
    **kwargs,
):
    """
    @brief Compile an existing Mobilint IR (@c .mblt) file into an MXQ package.
 
    @details This is the pre-parsed half of @c mxq_compile(): parsing already happened
    (via @c mblt_compile()), so this function only quantizes and compiles. Quantization
    parameters, their defaults, and the configuration precedence rules are identical to
    @c mxq_compile() — see that function for the full reference and usage examples.
 
    Parser-only arguments (@c save_subgraph_type, @c output_subgraph_path, @c feed_dict,
    @c dynamic_axes, @c multi_shape, @c yolo_decode_include,
    @c exclude_first_subgraph) are absent because the graph is already parsed.
    @c 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
    @c multi_shape or @c feed_dict that cannot apply is not mistaken for one that did.
 
    @param mblt string or list of strings. Path to a runnable @c .mblt produced by
    @c mblt_compile(); the file is validated up front and a @c 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 @c .mxq, as a @p multi_shape compile does with the files it
    writes per size, and @p 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.
    @param target_device string. Target NPU device (for example "aries-rb").
    @param backend string. Retained for backward compatibility and ignored: the graph is
    already parsed, so no parser backend is selected.
    @return None.
 
    @exception ValueError @p mblt is not an existing @c .mblt file, or a list has an entry
    that is not one; a file is not a runnable artifact for the requested @p cpu_offload
    setting; or the files of a list are not the same graph.
    """
    target_device = validate_target_device(target_device)
    reject_removed_kwargs(kwargs)
    # This entry point has no parser-only parameters, so one passed by name
    # lands in kwargs and would ride along into the pipeline. Take it out and
    # report it, the same way the mxq_compile() route does.
    warn_parse_args_ignored_for_mblt(
        "mxq_compile_from_mblt()", **take_parse_only_args(kwargs)
    )
 
    if isinstance(mblt, (list, tuple)):
        if not is_existing_mblt_list(mblt):
            raise ValueError(missing_mblt_entries_message(mblt))
    elif not is_existing_mblt_input(mblt):
        raise ValueError(
            f"mxq_compile_from_mblt() requires an existing .mblt file, got {mblt!r}. "
            "Produce one with mblt_compile() first."
        )
    # The artifact itself is validated in the pipeline planner, where
    # cpu_offload has been resolved against compile_config / config_preset.
 
    _mxq_compile_pipeline(
        model=mblt,
        calib_data_path=calib_data_path,
        save_path=save_path,
        backend=backend,
        device=device,
        inference_scheme=inference_scheme,
        use_random_calib=use_random_calib,
        cpu_offload=cpu_offload,
        optimize_option=optimize_option,
        buffer_mode=buffer_mode,
        force_npu_input_reposition=force_npu_input_reposition,
        force_npu_output_reposition=force_npu_output_reposition,
        image_channels=image_channels,
        split_blocks=split_blocks,
        split_parts=split_parts,
        config_preset=config_preset,
        compile_config=compile_config,
        resource_management_config=resource_management_config,
        calibration_config=calibration_config,
        bit_config=bit_config,
        llm_config=llm_config,
        hessian_quant_config=hessian_quant_config,
        mod_config=mod_config,
        equivalent_transformation_config=equivalent_transformation_config,
        search_weight_scale_config=search_weight_scale_config,
        save_sample_config=save_sample_config,
        uint8_input_config=uint8_input_config,
        preprocessing_config=preprocessing_config,
        extra_output_config=extra_output_config,
        bias_correction=bias_correction,
        bias_correction_config=bias_correction_config,
        config_save_path=config_save_path,
        target_device=target_device,
        **kwargs,
    )
 
 
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,
):
    """
    @brief Export a model to the Mobilint .mblt format without producing an MXQ package.
 
    @param model string or model instance. Source model or path to compile.
    @param mblt_save_path string or list of strings. Output path for the .mblt artifact; with @p multi_shape, one
    path per value.
    @param 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 @p feed_dict.
    Any other value raises @c ValueError. Defaults to "onnx".
    @param device string. Compilation device ("cpu" or "gpu"). Defaults to "cpu".
    @param feed_dict dict. Example inputs used for shape inference.
    @param multi_shape dict. Compile the model at several sizes of a dynamic dimension in one call. Keyed by input
    name like @p 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 @p 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 @p mblt_save_path per value (a list), or a single path to get <stem>_<i>.mblt.
    Cannot be combined with @p dynamic_axes. With @p 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.
    @param dynamic_axes dict. Declares dynamic axes per input name.
    @param yolo_decode_include bool. Runs YOLO decode on NPU when True.
    @param cpu_offload bool. Enables CPU offloading for unsupported groups.
    @param exclude_first_subgraph bool. Applies only when CPU offloading is enabled: exclude the first subgraph from the final graph if it is unsupported.
    @param 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.
    @param model_part_options dict. Extra arguments for the named part (e.g. {"mel_frames": 100} for Qwen3-ASR audio).
    @param kwargs dict. Additional arguments forwarded to the compiler.
    @return None.
    """
    _mblt_compile_dispatch(
        model=model,
        mblt_save_path=mblt_save_path,
        target_device=target_device,
        backend=backend,
        device=device,
        feed_dict=feed_dict,
        dynamic_axes=dynamic_axes,
        multi_shape=multi_shape,
        yolo_decode_include=yolo_decode_include,
        cpu_offload=cpu_offload,
        exclude_first_subgraph=exclude_first_subgraph,
        model_part=model_part,
        model_part_options=model_part_options,
        **kwargs,
    )
 
 
def _mblt_compile_dispatch(
    model: str | Any,
    mblt_save_path: str | list[str],
    target_device: str,
    backend="onnx",
    device=UNSET,
    feed_dict=None,
    dynamic_axes=None,
    multi_shape: Optional[dict] = None,
    yolo_decode_include=False,
    cpu_offload=UNSET,
    exclude_first_subgraph=False,
    model_part: Optional[str] = None,
    model_part_options: Optional[dict] = None,
    **kwargs,
) -> None:
    """Route a compile-to-mblt call to the compile pipeline.
 
    Shared by :func:`mblt_compile` and :func:`mblt_compile_with_callback` so
    both validate ``target_device`` and normalize ``backend`` the same way. ``device`` / ``cpu_offload`` default to ``UNSET`` here rather
    than to concrete values: that is what lets the callback wrapper forward only
    the flags its caller actually set and leave the rest to the merged
    ``CompileConfig``. :func:`mblt_compile` keeps its own historical
    ``"cpu"`` / ``False`` defaults and passes them explicitly.
    """
    target_device = validate_target_device(target_device)
    backend = normalize_backend(backend)
    reject_removed_kwargs(kwargs)
 
    _mblt_compile_pipeline(
        model=model,
        mblt_save_path=mblt_save_path,
        backend=backend,
        target_device=target_device,
        device=device,
        feed_dict=feed_dict,
        dynamic_axes=dynamic_axes,
        multi_shape=multi_shape,
        yolo_decode_include=yolo_decode_include,
        cpu_offload=cpu_offload,
        exclude_first_subgraph=exclude_first_subgraph,
        model_part=model_part,
        model_part_options=model_part_options,
        **kwargs,
    )
 
 
def _mxq_compile_pipeline(
    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",
    feed_dict=None,
    dynamic_axes=None,
    multi_shape: Optional[dict] = None,
    yolo_decode_include=False,
    exclude_first_subgraph=False,
    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 | str] = 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,
    **kwargs,
) -> None:
    """Quantize and compile through the ConfigManager-resolved pipeline.
 
    Serves the backends in ``MODEL_DICT_BACKENDS``; the callers
    (:func:`mxq_compile_from_source`, :func:`mxq_compile_from_mblt`) have
    already validated ``target_device`` and normalized ``backend``.
    """
    request = build_quantize_request(
        model=model,
        save_path=save_path,
        backend=backend,
        target_device=target_device,
        feed_dict=feed_dict,
        dynamic_axes=dynamic_axes,
        multi_shape=multi_shape,
        yolo_decode_include=yolo_decode_include,
        exclude_first_subgraph=exclude_first_subgraph,
        save_subgraph_type=save_subgraph_type,
        output_subgraph_path=output_subgraph_path,
        calib_data_path=calib_data_path,
        device=device,
        inference_scheme=inference_scheme,
        use_random_calib=use_random_calib,
        cpu_offload=cpu_offload,
        optimize_option=optimize_option,
        buffer_mode=buffer_mode,
        force_npu_input_reposition=force_npu_input_reposition,
        force_npu_output_reposition=force_npu_output_reposition,
        image_channels=image_channels,
        split_blocks=split_blocks,
        split_parts=split_parts,
        bias_correction=bias_correction,
        config_preset=config_preset,
        compile_config=compile_config,
        resource_management_config=resource_management_config,
        calibration_config=calibration_config,
        bit_config=bit_config,
        llm_config=llm_config,
        hessian_quant_config=hessian_quant_config,
        bias_correction_config=bias_correction_config,
        mod_config=mod_config,
        equivalent_transformation_config=equivalent_transformation_config,
        search_weight_scale_config=search_weight_scale_config,
        save_sample_config=save_sample_config,
        uint8_input_config=uint8_input_config,
        preprocessing_config=preprocessing_config,
        extra_output_config=extra_output_config,
        model_part=model_part,
        model_part_options=model_part_options,
        **kwargs,
    )
    resolved_request = ConfigManager.resolve_quantize_request(request)
    if config_save_path is not None:
        # Written before the (potentially hours-long) compile starts, so the
        # record survives a failure. Two fields still hold their defaults here
        # because ``MxqCompileStage`` fills them at execution time:
        # ``model_paths`` -- which for a raw-model input is a throwaway path in
        # the pipeline tempdir -- and ``runtime_options.version``.
        save_compile_config(resolved_request.compile_config, config_save_path)
    execute_quantize_request(resolved_request)
 
 
def _mblt_compile_pipeline(
    model: str | object,
    target_device: str,
    mblt_save_path: str | list[str],
    backend="onnx",
    device: object = UNSET,
    feed_dict=None,
    dynamic_axes=None,
    multi_shape: Optional[dict] = None,
    yolo_decode_include=False,
    cpu_offload: object = UNSET,
    exclude_first_subgraph=False,
    model_part: Optional[str] = None,
    model_part_options: Optional[dict] = None,
    config_preset: Optional[str] = None,
    compile_config: Optional[CompileConfig | str] = None,
    compilation_mode: Optional[str] = None,
    **kwargs,
) -> None:
    """Export to ``.mblt`` through the ConfigManager-resolved pipeline.
 
    ``compilation_mode`` is an internal knob: one of
    ``{"release", "dev", "debug"}`` or ``None`` (default) to defer to the
    ``MBLT_APP_ENV`` environment variable. When set it overrides the env
    and drives the parser's ``inference_validation`` / ``device_alloc``
    / ``log_level`` cascade — the same preset as ``MBLT_APP_ENV``. Not
    surfaced in the CLI on purpose; intended for in-process scripts and
    tests that want scoped dev-mode validation without mutating
    process-wide environment.
    """
    request = build_mblt_compile_request(
        model=model,
        mblt_save_path=mblt_save_path,
        backend=backend,
        target_device=target_device,
        device=device,
        feed_dict=feed_dict,
        dynamic_axes=dynamic_axes,
        multi_shape=multi_shape,
        yolo_decode_include=yolo_decode_include,
        cpu_offload=cpu_offload,
        exclude_first_subgraph=exclude_first_subgraph,
        model_part=model_part,
        model_part_options=model_part_options,
        config_preset=config_preset,
        compile_config=compile_config,
        compilation_mode=compilation_mode,
        **kwargs,
    )
    resolved_request = ConfigManager.resolve_mblt_compile_request(request)
    execute_mblt_compile_request(resolved_request)
 
 
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`` 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).
    """
    call_kwargs: dict[str, Any] = {
        "model": model,
        "mblt_save_path": mblt_save_path,
        "backend": backend,
        "target_device": target_device,
    }
    if device is not None:
        call_kwargs["device"] = device
    if cpu_offload is not None:
        call_kwargs["cpu_offload"] = cpu_offload
    if config_preset is not None:
        call_kwargs["config_preset"] = config_preset
    if compile_config is not None:
        call_kwargs["compile_config"] = compile_config
    if compilation_mode is not None:
        call_kwargs["compilation_mode"] = compilation_mode
 
    with progress_context(progress_callback):
        emit_progress(0, "Initializing compiler", log=False)
        _mblt_compile_dispatch(**call_kwargs)
        emit_progress(100, "Complete", log=False)
 
 
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`` 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``.
    """
    call_kwargs: dict[str, object] = {
        "model": model,
        "save_path": save_path,
        "backend": backend,
        "target_device": target_device,
    }
    if device is not None:
        call_kwargs["device"] = device
    if calib_data_path is not None:
        call_kwargs["calib_data_path"] = calib_data_path
    if use_random_calib is not None:
        call_kwargs["use_random_calib"] = use_random_calib
    if config_preset is not None:
        call_kwargs["config_preset"] = config_preset
    if compile_config is not None:
        call_kwargs["compile_config"] = compile_config
    if config_save_path is not None:
        call_kwargs["config_save_path"] = config_save_path
 
    with progress_context(progress_callback):
        emit_progress(0, "Initializing compiler", log=False)
        mxq_compile(**call_kwargs)
        emit_progress(100, "Complete", log=False)
 
 