# Compile the model

The AI/ML models compilation step compiles a pre-trained model defined
in other formats (ONNX is preferred) into QAic program container (QPC)
format. Cloud AI devices require this format to run inference.

A pretrained model can be compiled in three ways:

- Using `qaic-compile` (binary executable shipped with the Apps SDK).
- Using high level Python APIs. See the [Python API reference](https://docs.qualcomm.com/doc/80-99100-3/topic/index_Python-API.html#reference-to-python-api) for more information.
- Using C++ APIs. See the [C++ API reference](https://docs.qualcomm.com/doc/80-99100-3/topic/index_Cpp-API.html#reference-to-cpp-api) for more information.

This section describes how to compile using `qaic-compile`.

## Prerequisite

1. Use ONNX format as input.
2. Try to squash the original model into a single file ONNX format.

## Compilation using `qaic-compile`

Use the `qaic-compile` CLI tool to compile the model. `qaic-compile` is located at `/opt/qti-aic/exec/qaic-compile`. The tool supports all the latest compiler flags and is a sophisticated tool with a number of arguments. For the complete list of arguments, descriptions, and examples, see [qaic-compile](https://docs.qualcomm.com/doc/80-99100-3/topic/index_qaic-compile.html#reference-to-qaic-compile) or run the following help and usage commands:

/opt/qti-aic/exec/qaic-compile -h
    /opt/qti-aic/exec/qaic-compile --usage
    Copy to clipboard

`qaic-compile` can also be used to dump the supported operators.

/opt/qti-aic/exec/qaic-compile -operators-supported=<onnx | tensorflow>
    Copy to clipboard

Tip

After compilation, use `qaic-qpc validate` to confirm your QPC binary is compatible with the hardware installed on your system before proceeding to execution.

## Compile-time profiling options

To collect device-level profiling data, you must recompile your model with the
appropriate stats flags before running inference. The compiler instruments the
generated code with a stats buffer and configures the network to write cycle
data into the buffer based on the flags you pass to `qaic-compile`.

Stats collection is divided into two categories:

- Inference-level stats: Cycle counts accumulated across an entire inference, such as device execution time and per-port I/O wait times.
- Opstats (operator-level stats): Cycle counts collected on a per-operator basis.

Note

System-level profiling (host and runtime stats) doesn’t require
recompilation. Device-level profiling requires recompilation with
`-stats-level` and any additional flags described below.

### Stats level

The primary control for stats instrumentation is the `-stats-level` flag.
Stats levels are additive, that is, each higher level engages all instrumentation
from lower levels.

/opt/qti-aic/exec/qaic-compile -model=<model.onnx> \
        -aic-binary-dir=<./binaries> \
        -stats-level=70
    Copy to clipboard

| Stats level | What it collects |
| --- | --- |
| &gt;= 40 | Per-core, per-thread inference duration (UCycles and PCycles).<br><br><br>Per-core, per-thread activation (pre-inference setup) duration.<br><br><br>Per-core, per-thread PMU counter values (requires `-aic-pmu-events`<br>or `-aic-pmu-recipe`).<br><br><br>Per-core DDR traffic (requires `-ddr-stats`). |
| &gt;= 50 | Per-port total wait cycles on I/O doorbells.<br><br><br>Pipelined input port doorbell ring timestamps.<br><br><br>Per-op cycle data for pipelined semaphore increment instructions. |
| &gt;= 70 | Operator-level cycle counts (opstats level 1). |
| &gt;= 100 | Extended PMU stats. |

Level 40 is the default and is sufficient for basic performance analysis.
Use level 70 or above to enable per-operator profiling, which is required
for `qaic-opstats` post-processing.

### Stats batch size

Use `-stats-batchsize=<num>` to normalizes performance statistics to be per-inference when the model processes multiple batches.

### DDR stats

Use `-ddr-stats` to enable collection of per-core DDR traffic details. Requires `-stats-level >= 40`.

### PMU configuration

Performance monitoring unit (PMU) counters can be configured with one of two
mutually exclusive flags:

- `-aic-pmu-recipe=<recipe>`: Selects a pre-determined set of PMU event codes. Available recipes: `AxiRd`, `AxiWr`, `AxiRdWr`, `KernelUtil`, `HmxMacs`.
- `-aic-pmu-events=<event,event,...>`: Tracks specific PMU events on NSP cores. Up to 8 events are supported.

    Event IDs are interpreted as hexadecimal:

-aic-pmu-events=3F,70,200
        Copy to clipboard

### Other performance flags

The following flags print additional performance information during compilation:

- `-aic-perf-warnings`: Prints performance warning messages.
- `-aic-perf-metrics`: Prints compiler performance metrics.

Note

After recompiling with your chosen stats flags, see
[Profile inference time](https://docs.qualcomm.com/doc/80-99100-3/topic/index_model-execution.html#reference-to-inference-profiling) for instructions on collecting
and post-processing the stats buffers at runtime.

## Next steps

- See [Tune performance](https://docs.qualcomm.com/doc/80-99100-3/topic/index_Tune-performance.html#reference-to-tune-performance) to learn how to achieve the best throughput and latency based on your use case.
- See [Model configurator](https://docs.qualcomm.com/doc/80-99100-3/topic/network-performance-tuning.html#reference-to-model-configurator) for more information about using the model configurator tool to find the optimal compiler and runtime configurations.
- Inspect your QPC binary with [qaic-qpc](https://docs.qualcomm.com/doc/80-99100-3/topic/index_qaic-qpc.html#ref-to-qaic-qpc).

Last Published: Aug 25, 2026

[Previous Topic
Data type support](https://docs.qualcomm.com/bundle/publicresource/80-99100-3/topics/index_Operator-and-Datatype-support.md) [Next Topic
Tune performance](https://docs.qualcomm.com/bundle/publicresource/80-99100-3/topics/index_Tune-performance.md)