[Feature Request] Support optrace profiling with QNNExecutionProvider in the published onnxruntime-qnn wheels

[martinResearch]

Describe the feature request

It appears that the latest onnxruntime-qnn package on pypi.org (version 1.23.2, released in October 2025) does not support optrace-level profiling when using the QNNExecutionProvider. Is this to be expected?

In the QNNExecutionProvider documentation optrace-level-profiling, it states, "This feature is only available with the QAIRT 2.39 SDK and later." However, it does not specify which version was used to compile the published onnxruntime-qnn Python wheels, whether optrace-level profiling is supported in the published onnxruntime-qnn package, or, if so, from which version. Explicitly providing this information in the documentation would be very helpful.

Thank you!

Describe scenario use case

I want to profile my models on NPU and get detailed logs I can visualize in perfetto.

[MarioGini]

• It seems onnxruntime-qnn 1.23.2 comes with QNN SDK 2.37: https://github.com/microsoft/onnxruntime/releases
• If you have a local install of QNN SDK with version >=2.39 you can use that one by passing the appropriate path to the backend_path session config. This produces the artifacts needed that you can parse with qnn-profile-viewer.exe tool that is also shipped with the QNN SDK. I profiled models using this setup myself.

[martinResearch]

With onnxruntime-qnn==1.24.1 the QNN SDK has been upgraded to 2.42.0 and I can do optrace profiling without having to point to an external QnnHtp.dll file. It would be great to have this information documented in https://onnxruntime.ai/docs/execution-providers/QNN-ExecutionProvider.html#qnn-ep-profiling

[martinResearch]

Here is an minimal end-to-end working exampleto get Qnn optrace profiling results and visualize them in perfetto:

"""Test QNN profiling with a dummy convolution model.

Setup
* windows ARM64 machine
* onnxruntime-qnn version 1.24.1 (compiled with QNN SDK 2.42.0, see https://github.com/microsoft/onnxruntime/releases)
* onnx version 1.19.0
* QAIRT SDK 2.40.0.251030 from the link on https://docs.qualcomm.com/doc/80-90441-15/topic/qairt-install.html
   decompressed to the user's Downloads folder. Note that there is no need to register to the Qualcomm
   developer program to download this file.
"""

import os
from pathlib import Path
import subprocess
import tempfile
import time

import numpy as np
import onnx
from onnx import helper, TensorProto
import onnxruntime as ort

DOWNLOAD_DIR = Path.home() / "Downloads"
QAIRT_ROOT = DOWNLOAD_DIR / "v2.40.0.251030" / "qairt" / "2.40.0.251030"
qnn_profile_viewer_exe = QAIRT_ROOT / "bin" / "x86_64-windows-msvc" / "qnn-profile-viewer.exe"
qnn_htp_optrace_profiling_reader_dll = QAIRT_ROOT / "lib" / "x86_64-windows-msvc" / "QnnHtpOptraceProfilingReader.dll"

assert qnn_profile_viewer_exe.is_file(), f"QNN profile viewer not found at {qnn_profile_viewer_exe}"
assert qnn_htp_optrace_profiling_reader_dll.is_file(), (
    f"QNN HTP optrace profiling reader dll not found at {qnn_htp_optrace_profiling_reader_dll}"
)

print("onnxruntime version", ort.__version__)
print("onnx version", onnx.__version__)

assert ort.__version__.startswith("1.24")


def profile_model_qnn_optrace(
    onnx_file: Path,
    inputs: dict[str, np.ndarray],
    num_iterations: int = 1,
) -> None:
    date_string = time.strftime("%Y%m%d-%H%M%S")
    context_qnn_profiling_path = str(onnx_file.parent / f"{onnx_file.stem}_context_qnn_profiling_{date_string}.csv")
    provider = "QNNExecutionProvider"

    provider_options = {
        "backend_type": "htp",
        "htp_performance_mode": "high_performance",
        "htp_graph_finalization_optimization_mode": "3",
        "profiling_level": "optrace",  # Set profiling_level to optrace
        "profiling_file_path": context_qnn_profiling_path,
    }
    # Enable context bin generation
    context_session_options = ort.SessionOptions()  # type: ignore
    context_session_options.add_session_config_entry("ep.context_embed_mode", "0")
    context_session_options.add_session_config_entry("ep.context_enable", "1")

    # run the session to generate the files model_ctx.onnx model_qnn.bin
    # and QNNExecutionProvider_QNN_<number>_schematic.bin
    # see https://onnxruntime.ai/docs/execution-providers/QNN-ExecutionProvider.html#optrace-level-profiling
    # the schematic file is generated in current directory with a name QNNExecutionProvider_QNN_<number>_schematic.bin,
    # with number being different for each run. this is not convenient.
    # we create a temporary directory for all the generated files and move temporarily the current folder there

    with tempfile.TemporaryDirectory() as temp_dir:
        # move the current folder to the temp directory
        temp_dir_path = Path(temp_dir)
        current_dir = Path.cwd()
        try:
            os.chdir(temp_dir_path)
            ort.InferenceSession(onnx_file, context_session_options, providers=[(provider, provider_options)])
        finally:
            os.chdir(current_dir)
        # find the generated file ending with schematic.bin and move them back to the original folder
        schematic_files = list(temp_dir_path.glob("*schematic.bin"))
        assert len(schematic_files) == 1, f"Expected exactly one schematic.bin file, but found {len(schematic_files)}"
        schematic_file = schematic_files[0]

        target_path = onnx_file.parent / schematic_file.name
        schematic_file.rename(target_path)
        print(f"Moved {schematic_file} to {target_path}")
        schematic_file = target_path

    bin_file = Path(str(onnx_file)[:-5] + "_qnn.bin")
    context_file = Path(str(onnx_file)[:-5] + "_ctx.onnx")
    assert bin_file.is_file(), f"Expected bin file not found at {bin_file}"
    assert context_file.is_file(), f"Expected context onnx file not found at {context_file}"

    session_options = ort.SessionOptions()
    session_options.add_session_config_entry("ep.context_enable", "0")
    qnn_profiling_csv_path = str(onnx_file.parent / f"{onnx_file.stem}_qnn_profiling_{date_string}.csv")

    provider_options = {
        "backend_type": "htp",
        "htp_performance_mode": "high_performance",
        "htp_graph_finalization_optimization_mode": "3",
        "profiling_level": "optrace",
        "profiling_file_path": qnn_profiling_csv_path,
    }

    session = ort.InferenceSession(context_file, session_options, providers=[(provider, provider_options)])
    # Getting errors "<E> Failed to create context from binary with err 0x7fffffff"
    # and warnings "F"ailed to create context with file mapping enabled. Error: Unknown error. ""
    # but this does not prevent the profiling files from being generated.
    output_names = [output.name for output in session.get_outputs()]

    # Run a few iterations for profiling
    timings = []
    for _ in range(num_iterations):
        start = time.perf_counter_ns()
        session.run(output_names, inputs)
        end = time.perf_counter_ns()
        timings.append(end - start)
    session.end_profiling()
    # avg_duration = np.mean(timings) / 1e6
    # print(f"Average inference time with profiling over {num_iterations} runs: {avg_duration} ms")
    # print(f"Minimum inference time with profiling over {num_iterations} runs: {min(timings) / 1e6} ms")

    print(f"QNN detailed profiling saved to: {qnn_profiling_csv_path}")
    assert Path(qnn_profiling_csv_path).is_file()
    qnn_log_file = qnn_profiling_csv_path.replace(".csv", "_qnn.log")
    print(f"QNN log profiling saved to: {qnn_log_file}")
    assert Path(qnn_log_file).is_file(), f"QNN log file not found at {qnn_log_file}"
    assert Path(schematic_file).is_file(), f"Schematic file not found at {schematic_file}"

    # End profiling and get the profile file path
    output_qnn_profiling_json_path = str(onnx_file.parent / f"{onnx_file.stem}_qnn_profiling_{date_string}.json")

    cmd = (
        f'"{qnn_profile_viewer_exe}" --reader {qnn_htp_optrace_profiling_reader_dll} '
        f" --input_log {qnn_log_file} --schematic {schematic_file} --output {output_qnn_profiling_json_path}"
    )

    print(f"Running command: {cmd}")
    subprocess.run(cmd, shell=True)

    assert Path(output_qnn_profiling_json_path).is_file()
    print(
        f"QNN profiling json output saved to: {output_qnn_profiling_json_path}. "
        "can be viewed with chrome://tracing or https://ui.perfetto.dev/ "
    )


def create_model_and_inputs() -> tuple[Path, dict[str, np.ndarray]]:
    """Build a tiny convolution ONNX model and save it to a persistent path."""
    input_name = "input"
    output_name = "output"
    input_shape = (1, 1, 5, 5)
    kernel_shape = (1, 1, 3, 3)

    weight_values = np.array(
        [
            [
                [[1.0, 0.0, -1.0], [1.0, 0.0, -1.0], [1.0, 0.0, -1.0]],
            ]
        ],
        dtype=np.float32,
    )
    bias_values = np.zeros(kernel_shape[0], dtype=np.float32)

    date_string = time.strftime("%Y%m%d-%H%M%S")
    folder = Path.cwd() / f"{date_string}"
    folder.mkdir(parents=True, exist_ok=True)
    resolved_model_path = folder / "dummy_conv.onnx"
    resolved_model_path.parent.mkdir(parents=True, exist_ok=True)

    input_tensor = helper.make_tensor_value_info(input_name, TensorProto.FLOAT, list(input_shape))
    output_tensor = helper.make_tensor_value_info(
        output_name,
        TensorProto.FLOAT,
        [
            input_shape[0],
            kernel_shape[0],
            input_shape[2] - kernel_shape[2] + 1,
            input_shape[3] - kernel_shape[3] + 1,
        ],
    )

    conv_node = helper.make_node(
        "Conv",
        inputs=[input_name, "weight", "bias"],
        outputs=[output_name],
        pads=[0, 0, 0, 0],
        strides=[1, 1],
    )

    graph = helper.make_graph(
        nodes=[conv_node],
        name="dummy_conv_graph",
        inputs=[input_tensor],
        outputs=[output_tensor],
        initializer=[
            helper.make_tensor(
                name="weight",
                data_type=TensorProto.FLOAT,
                dims=list(kernel_shape),
                vals=weight_values.flatten().tolist(),
            ),
            helper.make_tensor(
                name="bias",
                data_type=TensorProto.FLOAT,
                dims=[kernel_shape[0]],
                vals=bias_values.tolist(),
            ),
        ],
    )

    # Force an IR/opset version supported by the current ORT build (max IR 11 per error message).
    model = helper.make_model(
        graph,
        producer_name="holoportation_dummy",
        opset_imports=[helper.make_opsetid("", 11)],
    )
    model.ir_version = 11
    onnx.checker.check_model(model)
    onnx.save(model, resolved_model_path)

    dummy_input = np.random.rand(*input_shape).astype(np.float32)
    inputs = {input_name: dummy_input}
    return resolved_model_path, inputs


def test_with_dummy_model() -> None:
    """Build a tiny convolution ONNX model, run benchmark, and profile if QNN is available."""
    model_path, inputs = create_model_and_inputs()

    profile_model_qnn_optrace(
        onnx_file=model_path,
        inputs=inputs,
    )

if __name__ == "__main__":
    test_with_dummy_model()

I can visualize the json file with perfetto. Note that it seems to display only the profiling for the last execution in the loop.

[martinResearch]

it seems the timings in the chrome json file are in cycles and not milliseconds, and as a result the timings displayed in perfetto are wrong. Not sure where this is documented.

possible fix using

def _fix_optrace_chrometrace_timestamps(
    chrometrace_json: Path,
    runtrace_json: Path,
) -> Path:
    """Convert optrace chrometrace timestamps from HTP cycles to microseconds.

    The ``QnnHtpOptraceProfilingReader.dll`` outputs ``ts`` and ``dur`` fields
    in the chrometrace JSON as raw HTP processor cycle counts, not microseconds.
    Since the chrometrace / Perfetto format assumes microseconds by default,
    Perfetto displays wildly inflated times (e.g. 26 ms for what is actually
    18 us of NPU execution).

    The chrometrace JSON format has no header field to declare an arbitrary
    clock frequency.  Its only time-unit knob (``displayTimeUnit``) accepts
    ``"ms"`` or ``"ns"`` and only changes the UI label, not the scale.
    Perfetto's native protobuf format supports ``ClockSnapshot`` packets for
    custom clock domains, but the QNN reader outputs JSON, so that mechanism
    is unavailable.  The only option is to multiply out the conversion
    ourselves.

    This function reads the HTP core clock frequency from the companion
    runtrace JSON, converts all ``ts`` and ``dur`` values from cycles to
    microseconds, and writes the result to a new file (``*_corrected.json``)
    next to the original.  The original chrometrace is left untouched.

    Args:
        chrometrace_json: Path to the original optrace chrometrace JSON
            (raw HTP cycle timestamps).
        runtrace_json: Path to the companion ``*_runtrace.json`` with clock
            frequency information.

    Returns:
        Path to the newly created corrected chrometrace JSON.
    """
    htp_frequency_ghz = _get_htp_frequency_ghz_from_runtrace(runtrace_json)
    # cycles_per_microsecond = frequency_ghz * 1000
    # (e.g. 1.4 GHz = 1400 cycles/us)
    cycles_per_microsecond = htp_frequency_ghz * 1000.0

    data: dict[str, Any] = json.loads(chrometrace_json.read_text())
    events = data.get("traceEvents", [])

    num_converted = 0
    for event in events:
        if not isinstance(event, dict):
            continue
        if "ts" in event:
            event["ts"] = round(event["ts"] / cycles_per_microsecond, 3)
        if "dur" in event:
            event["dur"] = round(event["dur"] / cycles_per_microsecond, 3)
            num_converted += 1

    corrected_path = chrometrace_json.with_stem(chrometrace_json.stem + "_corrected")
    corrected_path.write_text(json.dumps(data, indent=1))
    print(f"  Fixed {num_converted} duration events: cycles → microseconds (÷ {cycles_per_microsecond:.0f} cycles/us)")

    # Show the corrected timeline span for verification
    x_events = [e for e in events if isinstance(e, dict) and e.get("ph") == "X"]
    if x_events:
        min_ts = min(e["ts"] for e in x_events)
        max_end = max(e["ts"] + e.get("dur", 0) for e in x_events)
        print(f"  Corrected timeline span: {min_ts:.3f} – {max_end:.3f} us ({(max_end - min_ts):.3f} us total)")

    return corrected_path