# Use GenAI models with Qualcomm Generative AI (GenAI) Inference Extensions (Genie)
Genie is a high-level framework to run GenAI models, such as LLMs, vision transformers,
and multimodal models on Qualcomm platforms. It abstracts the complexity of managing
multiple binaries and orchestrates execution across heterogeneous compute units
(CPU, GPU, NPU), delivering low latency, power efficiency, and user simplicity.

The following JSON configurations, Genie tools, and C APIs are the essential components
for preparing, executing, and managing GenAI models on-device.
| Component | Purpose |
| --- | --- |
| JSON configurations | Key functions:
Specifies backend selection (CPU or NPU).
Configures model paths, tokenizer settings, and memory allocation.
Manages dialogue session parameters for multi-turn conversations.
Example fields:
For more details, see [Qualcomm AI Engine Direct](https://docs.qualcomm.com/doc/80-63442-10/topic/index_QNN.html) |
| Genie tools | Command like tools for model execution, and profiling.
Common tools:
For more details, see [Qualcomm AI Runtime (QAIRT) SDK](https://docs.qualcomm.com/doc/80-63442-10). |
| Genie API | Provides programmatic access to integrate Genie into GenAI applications.
Features:
Advantages:
Integration:
For more details, see [QAIRT](https://docs.qualcomm.com/doc/80-63442-10) |
## Run LLMs with Genie
Once your large language model (LLM) has been prepared and optimized
(using [AI Hub](https://docs.qualcomm.com/doc/80-80022-15B/topic/genai-prepare-ai-hub.html) or the
[Jupyter notebooks](https://docs.qualcomm.com/doc/80-80022-15B/topic/genai-prepare-jupyter.html)),
Genie provides a streamlined way to execute it on Qualcomm platforms.
### Prerequisites
Before running a language model with Genie, confirm that the following prerequisites are met.
- The model bundle is exported and prepared for the correct backend (CPU or NPU) and it includes
AI Engine Direct (QNN) binaries, tokenizer files, and configuration files.
- QAIRT is installed on the target device and Genie tools and libraries are available as part of
the SDK.
- The target hardware uses a Qualcomm platform with sufficient memory (RAM and storage to copy and execute model binaries).
The following image shows the required inputs to use Genie to run an LLM with `genie-t2t-run`.

The `genie-t2t-run` tool is a test application to do text-to-text inference on a provided LLM network.
It takes a user prompt in text format and outputs the result in the text format. It provides a ready-to-use
command line interface (CLI) to run LLM inference on supported Qualcomm devices using CPU, GPU, and Hexagon Tensor Processor (HTP) backends.
Genie streamlines multibinary LLM execution into a single job using pre-optimized model assets.
The following snippet shows a sample `genie-t2t-run` command.
genie-t2t-run -c genie-config.json -p "Tell me about Qualcomm"
Copy to clipboard
The following image shows the call flow of the `genie-t2t-run` command.

The following steps detail how to push the LLM artifacts to the target device and run the LLM model
with Genie. Before running `genie-t2t-run` you need to copy the genie-bundle generated from the
model preparation step to the target device.
1. From the host computer, connect to the target device using its IP address.
ssh root@
Copy to clipboard
2. From the host computer, create a directory to push model artifacts.
mkdir -p /data/local/tmp
Copy to clipboard
3. From the host computer, push the libraries and binaries needed run the model to the target device.
scp ${QNN_SDK_ROOT}/bin/aarch64-oe-linux-gcc11.2/genie-t2t-run root@:/data/local/tmp/
Copy to clipboard
scp ${QNN_SDK_ROOT}/lib/aarch64-oe-linux-gcc11.2/libGenie.so root@:/data/local/tmp/
Copy to clipboard
scp ${QNN_SDK_ROOT}/lib/aarch64-oe-linux-gcc11.2/libQnnHtp.so root@:/data/local/tmp/
Copy to clipboard
scp ${QNN_SDK_ROOT}/lib/aarch64-oe-linux-gcc11.2/libQnnSystem.so root@:/data/local/tmp/
Copy to clipboard
scp ${QNN_SDK_ROOT}/lib/aarch64-oe-linux-gcc11.2/libQnnHtpPrepare.so root@:/data/local/tmp/
Copy to clipboard
scp ${QNN_SDK_ROOT}/lib/aarch64-oe-linux-gcc11.2/libQnnHtpNetRunExtensions.so root@:/data/local/tmp/
Copy to clipboard
Note
In the following commands, replace `` with the DSP Hexagon architecture library version.
Tab IQ-8275
Tab IQ-9075/QCS9100
Tab Qualcomm Dragonwing™ RB3 Gen 2
`75`
`73`
`68`
scp ${QNN_SDK_ROOT}/lib/aarch64-oe-linux-gcc11.2/libQnnHtpVStub.so root@:/data/local/tmp/
Copy to clipboard
scp ${QNN_SDK_ROOT}/lib/hexagon-v/unsigned/libQnnHtpVSkel.so root@:/data/local/tmp/
Copy to clipboard
4. From the host computer, push model binaries and configuration files to the target device.
adb push /data/local/tmp/
Copy to clipboard
adb push /data/local/tmp/
Copy to clipboard
adb push /data/local/tmp/
Copy to clipboard
adb push /data/local/tmp/
Copy to clipboard
5. From the target device, run the model.
export LD_LIBRARY_PATH=/data/local/tmp/
Copy to clipboard
export PATH=$LD_LIBRARY_PATH:$PATH
Copy to clipboard
cd $LD_LIBRARY_PATH
Copy to clipboard
./genie-t2t-run -c -p "What's the most popular cookie in the world?"
Copy to clipboard
Note
Select the runtime using the `backend::type` parameter from the
[JSON configuration file](https://docs.qualcomm.com/doc/80-63442-10/topic/json.html#genie-dialog-json-config-string)
| `backend::type` | All backends | Engine to use.
|
| --- | --- | --- |
Note
Sample Genie configurations for different models are available through
[AI Hub](https://github.com/quic/ai-hub-apps/tree/main/tutorials/llm_on_genie/configs/genie).
## Run multimodal models with Genie
To run multimodal models with Genie, use the GenAI tutorials (available in Qualcomm Package Manager)
to generate the models and run them with Genie tools.
Note
No multimodal models are hosted in AI Hub.
Users must use the Jupyter notebooks to generate and run the models.
Multimodal execution with Genie happens with the Genie pipeline.
- Genie Node APIs: Used to create individual blocks. Each node creation requires a standalone JSON
configuration, similar to the dialog configuration.
- `text-encoder`
- `image-encoder`
- `text-generator`
- Genie Pipeline APIs: Used to connect nodes and streamline execution. The Genie pipeline manages
internal data type translations, re-quantization, and concatenation operations.

### Genie pipeline stages
1. Create the nodes.
1. Create the node configuration. Node JSON configurations vary based on the node type.
For more information, see [node JSON](https://docs.qualcomm.com/doc/80-63442-10/topic/node_json.html)
Genie_Status_t GenieNodeConfig_createFromJson(const char* str,
GenieNodeConfig_Handle_t* configHandle);
Copy to clipboard
2. Create the node.
Genie_Status_t GenieNode_create(const GenieNodeConfig_Handle_t nodeConfigHandle,
GenieNode_Handle_t* nodeHandle);
Copy to clipboard
2. Construct the pipeline.
1. Create a pipeline from the node configuration.
Genie_Status_t GeniePipelineConfig_createFromJson(const char* str,
GeniePipelineConfig_Handle_t* configHandle);
Copy to clipboard
2. Add nodes to the pipeline.
Genie_Status_t GeniePipeline_create(const GeniePipelineConfig_Handle_t configHandle,
GeniePipeline_Handle_t* pipelineHandle);
Copy to clipboard
3. Connect the nodes.
- Each node type has a set of predefined IO names. These are defined in `GenieNode.h`.
For example, the text generator node has one of the two possible inputs and one output:
- Input: `GENIE_NODE_TEXT_GENERATOR_TEXT_INPUT`
- Input: `GENIE_NODE_TEXT_GENERATOR_EMBEDDING_INPUT`
- Output: `GENIE_NODE_TEXT_GENERATOR_TEXT_OUTPUT`
>
>
> - The Genie pipeline connect API defines one connection from one producer node output to one
> consumer node input. For example:
>
>
> GeniePipeline_connect(pipelineHandle,
> lutEncoder,
> GENIE_NODE_TEXT_ENCODER_EMBEDDING_OUTPUT,
> textGenerator,
> ENIE_NODE_TEXT_GENERATOR_EMBEDDING_INPUT)
> Copy to clipboard
3. Run the pipeline.
1. Set data for the input nodes.
Genie_Status_t GenieNode_setData(const GenieNode_Handle_t nodeHandle,
const GenieNode_IOName_t nodeIOName,
const void* data,
const size_t dataSize,
const char* dataConfig);
Copy to clipboard
- Use the predefined IO name (as in connect API)
- The IO name implicitly defines the data type
2. Run the pipeline.
Genie_Status_t GeniePipeline_execute(const GeniePipeline_Handle_t pipelineHandle,
void* userData);
Copy to clipboard
- Callbacks registered to the output node(s) return the output.
## Genie API
The Genie API is a high-level interface for running LLM pipelines on Qualcomm devices.
It wraps the tokenizer, engine (QNN backend), KV-cache management, decoding, and sampling
into dialog and token-generation flows, while delegating device execution to QAIRT
with HTP/NPU and CPU backends.
The following diagram shows the high-level functions handled internally by Genie APIs.
You can use the Genie C APIs to configure each component according to your LLM application needs.

The Genie API has the following components.
For complete function definitions and header-level details, see [Genie API documentation](https://docs.qualcomm.com/doc/80-63442-10/topic/library.html)
- `GeniePipeline`: Orchestrates the entire inference workflow by chaining tokenizer, engine, sampler,
and other nodes into a runnable pipeline. It manages data flow and execution order for text generation
or embedding tasks.
- `GenieNode`: Represents an individual processing unit (tokenizer, engine) within the pipeline.
Nodes encapsulate specific functionality and can be used to build custom inference graphs.
- `GenieDialog`: A high-level abstraction for conversational tasks. It wires together tokenizer,
model, backend, and sampler using JSON configuration and provides APIs for token generation and embeddings.
- `GenieEmbedding`: Handles embedding queries for retrieval-augmented generation (RAG) or semantic search.
Converts input text into dense vector representations using the loaded model.
- `GenieProfile`: Stores configuration and runtime parameters such as backend selection, sampling strategies,
and performance settings. Profiles allow quick switching between different inference setups.
- `GenieSampler`: Implements decoding strategies (for example, greedy, top-k, or top-p sampling) to convert
model logits into output tokens. Supports advanced speedup techniques like speculative decoding (SPD),
self-speculative decoding (SSD), and look ahead decoding (LADE).
- `GenieEngine`: Executes the model forward pass on the chosen backend (HTP, GenAI transformer, or CPU).
It manages graph execution, memory allocation, and hardware acceleration.
- `GenieTokenizer`: Converts text to token IDs and back to text during inference. Works with model-specific
vocabularies and supports efficient encoding/decoding for multi-turn dialogs.
The following diagram shows a sample call flow for the Genie API in an end-to-end LLM chatbot application.

Last Published: Jun 23, 2026
[Previous Topic
Run a Generative AI (GenAI) model](https://docs.qualcomm.com/bundle/publicresource/80-80022-15B/topics/run-genai-model.md) [Next Topic
Develop a generative AI (GenAI) application](https://docs.qualcomm.com/bundle/publicresource/80-80022-15B/topics/develop-genai-app.md)