# HTP Backend Extensions

Backend extensions are JSON configuration files that control the HTP backend during context binary
compilation.

This guide covers:

- The JSON structure and what each section controls
- Loading an existing JSON file into a `CompileConfig`
- Building a `CompileConfig` from Python objects
- The HTP configuration classes and their fields
- Serializing a `CompileConfig` back to JSON

## JSON Structure

The example below shows a minimal backend extension file. For the complete JSON specification and
all available fields, see the [QNN HTP Backend documentation](https://docs.qualcomm.com/doc/80-63442-10/topic/htp_backend.html).

{
        "context": [
            {
                "weight_sharing_enabled": true,
                "lora_weight_sharing": true
            }
        ],
        "graphs": [
            {
                "graph_names": ["graphA", "graphB"],
                "O": 3,
                "vtcm_mb": 8
            },
            {
                "graph_names": ["graphC"],
                "dlbc": 1
            }
        ],
        "devices": [
            {
                "device_id": 0,
                "soc_model": 43,
                "dsp_arch": "v73",
                "cores": [
                    {
                        "core_id": 0,
                        "perf_profile": "burst"
                    }
                ]
            }
        ],
        "memory": {
            "mem_type": "shared_buffer"
        },
        "groupContext": {
            "share_resources": true
        }
    }
    Copy to clipboard

Each section maps to a Python config class (see [qairt.api.common.backends.htp](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-common-backends-htp.html)):

| JSON Section | Python Config Class | Controls |
| --- | --- | --- |
| `"context"` | `HtpContextConfig` | Weight sharing, extended UDMA, LoRA weight sharing |
| `"graphs"` | `HtpGraphConfig` | Per-graph VTCM, HVX threads, optimization level, fp16 precision, DLBC |
| `"devices"` | `HtpDeviceConfig` + `HtpDeviceCoreConfig` | SoC ID, DSP architecture, PD session, performance profile, RPC latency |
| `"memory"` | `HtpMemoryConfig` | Memory type (shared buffer, etc.) |
| `"groupContext"` | `HtpGroupContextConfig` | Resource sharing across contexts |

Note

The `"graphs"` section uses JSON aliases (`"O"` for `optimization_type`, `"vtcm_mb"`
for `vtcm_size_in_mb`). The Python classes accept both the alias and the full name.

## Loading from JSON

If you have an existing backend extensions JSON file, you can load it directly into a
`CompileConfig` rather than constructing each config object by hand.

### from\_backend\_extensions (classmethod)

Creates a new `CompileConfig` from a JSON file:

from qairt.api.compiler.config import CompileConfig
    
    config = CompileConfig.from_backend_extensions("HTP", "/path/to/backend_extensions.json")
    Copy to clipboard

See [`from_backend_extensions()`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-compiler.html#qairt.api.compiler.config.CompileConfig.from_backend_extensions) for the full
signature.

### populate\_from\_backend\_extensions (instance method)

Populates an existing `CompileConfig` from a JSON file, overwriting any HTP-related fields
while preserving other settings:

config = CompileConfig(backend="HTP")
    config.populate_from_backend_extensions("/path/to/backend_extensions.json")
    Copy to clipboard

See [`populate_from_backend_extensions()`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-compiler.html#qairt.api.compiler.config.CompileConfig.populate_from_backend_extensions) for the
full signature.

### Using with the Gen AI Builder

After loading a `CompileConfig` from JSON, pass it to the builder via
`set_compilation_options(config=...)`:

from qairt.gen_ai_api.gen_ai_builder_factory import GenAIBuilderFactory
    from qairt.api.compiler.config import CompileConfig
    
    builder = GenAIBuilderFactory.create("/path/to/model", "HTP", cache_root="./cache")
    
    config = CompileConfig.from_backend_extensions("HTP", "/path/to/backend_extensions.json")
    builder.set_compilation_options(config=config)
    
    container = builder.build()
    Copy to clipboard

Note

When using the `config=` path, you provide the **entire** compilation config. This replaces
the config created by `set_targets()` rather than merging with it. Ensure the JSON file
includes the appropriate SoC and device settings.

## Building from Python

For full control, construct a `CompileConfig` directly from the HTP config classes:

from qairt.api.compiler.config import CompileConfig
    from qairt.api.common.backends.htp import (
        HtpGraphConfig,
        HtpDeviceConfig,
        HtpDeviceCoreConfig,
        HtpContextConfig,
        HtpMemoryConfig,
        HtpGroupContextConfig,
    )
    from qairt.gen_ai_api.gen_ai_builder_factory import GenAIBuilderFactory
    
    builder = GenAIBuilderFactory.create("/path/to/model", "HTP", cache_root="./cache")
    
    config = CompileConfig(
        backend="HTP",
        soc_details="chipset:SM8750",
        graph_custom_configs=[HtpGraphConfig(
            name="placeholder",
            optimization_type=3,
            vtcm_size_in_mb=8,
            fp16_relaxed_precision=0,
        )],
        device_custom_configs=[HtpDeviceConfig(
            pd_session="unsigned",
            cores=[HtpDeviceCoreConfig(
                perf_profile="burst",
                rpc_control_latency=100,
            )],
        )],
        context_custom_configs=[HtpContextConfig(
            weight_sharing_enabled=True,
            extended_udma=True,
        )],
        memory_custom_config=HtpMemoryConfig(mem_type="shared_buffer"),
        group_context_config=HtpGroupContextConfig(share_resources=True),
    )
    builder.set_compilation_options(config=config)
    Copy to clipboard

## HTP Configuration Classes

For a full list of HTP configuration classes, their fields, types, and defaults, see the
[API reference](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-common-backends-htp.html). You can also list
available options programmatically:

from qairt.api.common.backends.htp import list_options
    list_options()
    Copy to clipboard

## Serializing to JSON

To export a `CompileConfig` back to a backend extensions JSON string, use
[`to_backend_extension_json()`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-compiler.html#qairt.api.compiler.config.CompileConfig.to_backend_extension_json):

from pathlib import Path
    
    json_str = config.to_backend_extension_json()
    Path("backend_extensions.json").write_text(json_str)
    
    # Custom indentation
    json_str = config.to_backend_extension_json(indent=2)
    Copy to clipboard

This enables a round-trip workflow: load a JSON file, modify it in Python, and write it back out.

from qairt.api.compiler.config import CompileConfig
    
    # Load, modify, save
    config = CompileConfig.from_backend_extensions("HTP", "original.json")
    config.context_custom_configs[0].extended_udma = True
    Path("modified.json").write_text(config.to_backend_extension_json())
    Copy to clipboard

Last Published: Aug 26, 2026

[Previous Topic
Conversion Options](https://docs.qualcomm.com/bundle/publicresource/80-87189-2/topics/genai_builder_configuration.md)