# Buildable

- *class* qairt.gen\_ai\_api.builders.buildable.Buildable

    - Bases: `ABC`

Abstract base builder defining the build contract.

- *abstract* build() → [GenAIContainerable](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-containers.html#qairt.gen_ai_api.containers.gen_ai_containerable.GenAIContainerable)

    - Build and return a GenAIContainer.

# GenAIBuilder

GenAI Builder constructed to shepherd a model from source framework to being prepared to run.
GenAI Builder builds a GenAIContainer object with all of the prepared model artifacts.

- *class* qairt.gen\_ai\_api.builders.gen\_ai\_builder.GenAIBuilder(*framework\_model\_path: os.PathLike | str*, *config: [GenAIConfig](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-configs.html#qairt.gen_ai_api.configs.gen_ai_config.GenAIConfig)*, *backend: [BackendType](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-configs.html#qairt.api.configs.common.BackendType)*)

    - Bases: [`Buildable`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-builders.html#qairt.gen_ai_api.builders.buildable.Buildable)

Abstract class for Generative AI Builder.

- *abstract* build() → [GenAIContainerable](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-containers.html#qairt.gen_ai_api.containers.gen_ai_containerable.GenAIContainerable)

    - Prepares and builds the model for execution.

- Returns

    - GenAIContainer object.

- *property* prepare\_embedding\_lut*: bool*

    - Whether the embedding layer should be extracted as a lookup table instead of compiling for HTP.

# WorkflowBuilder

`WorkflowBuilder` connects multiple `GenAIBuilder` instances into a single
multi-model workflow (for example, a vision encoder feeding a text generator for
image-to-text inference) and builds them into a [`WorkflowContainer`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-containers.html#qairt.gen_ai_api.containers.workflow_container.WorkflowContainer).

- *class* qairt.gen\_ai\_api.builders.workflow\_builder.WorkflowBuilder(*builders: Dict[str, [Buildable](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-builders.html#qairt.gen_ai_api.builders.buildable.Buildable)]*, *workflow\_graph: [WorkflowGraph](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-configs-workflow.html#qairt.gen_ai_api.configs.workflow.WorkflowGraph)*)

    - Bases: [`Buildable`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-builders.html#qairt.gen_ai_api.builders.buildable.Buildable)

Constructs a <cite>WorkflowContainer</cite> from <cite>GenAIBuilder</cite> instances and a <cite>WorkflowGraph</cite>.

Use one of the two factory methods rather than calling `__init__` directly:

- <cite>from_builders</cite>: use when you have already constructed <cite>GenAIBuilder</cite>
instances and optionally a <cite>WorkflowGraph</cite>. If no graph is supplied and
there is exactly one builder, a single-node `TEXT_GENERATOR` graph is
created automatically.
- <cite>from_workflow</cite>: use when you have a <cite>WorkflowGraph</cite> whose nodes each
carry a `path` and want the builder to construct the <cite>GenAIBuilder</cite>
instances automatically.

- build() → [WorkflowContainer](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-containers.html#qairt.gen_ai_api.containers.workflow_container.WorkflowContainer)

    - Build and return a <cite>WorkflowContainer</cite> from the configured builders.

Calls <cite>build()</cite> on each <cite>GenAIBuilder</cite> and assembles the resulting
containers into a <cite>WorkflowContainer</cite> with the configured graph.

- Returns

    - A <cite>WorkflowContainer</cite> holding all built sub-containers and the
workflow graph.

- *classmethod* from\_builders(*builders: Dict[str, [Buildable](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-builders.html#qairt.gen_ai_api.builders.buildable.Buildable)]*, *workflow\_graph: Optional[[WorkflowGraph](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-configs-workflow.html#qairt.gen_ai_api.configs.workflow.WorkflowGraph)] = None*) → [WorkflowBuilder](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-builders.html#qairt.gen_ai_api.builders.workflow_builder.WorkflowBuilder)

    - Creates a <cite>WorkflowBuilder</cite> from already-constructed builder instances.

- Parameters

    - - **builders** – Mapping of node name to builder instance (any `Buildable`
subclass, including `GenAIBuilder` and
`VisionEncoderBuilderHTP`). The builders must already be fully
configured; no path information is read here.
- **workflow\_graph** – <cite>WorkflowGraph</cite> describing the directed graph structure (node
names, roles, and connections). Node `path` fields are not
required here — the builders have already been constructed.
If omitted and `builders` contains exactly one entry, a
single-node `TEXT_GENERATOR` graph is constructed automatically
using the builder’s key as the node name. If omitted and
`builders` contains more than one entry, a `ValueError` is
raised — multi-node workflows require an explicit graph.
When `workflow_graph` is provided, `builders` may be empty.

- Returns

    - A <cite>WorkflowBuilder</cite> ready to call <cite>build()</cite> on.

- Raises

    - **ValueError** – If `workflow_graph` is omitted and `builders` has
    more than one entry, or if `workflow_graph` is omitted and
    `builders` is empty.

- *classmethod* from\_workflow(*workflow: [WorkflowGraph](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-configs-workflow.html#qairt.gen_ai_api.configs.workflow.WorkflowGraph)*, *backend\_type: [BackendType](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-configs.html#qairt.api.configs.common.BackendType) = BackendType.HTP*, *cache\_root: Optional[PathLike] = None*) → [WorkflowBuilder](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-builders.html#qairt.gen_ai_api.builders.workflow_builder.WorkflowBuilder)

    - Creates a <cite>WorkflowBuilder</cite> by constructing <cite>GenAIBuilder</cite> instances from a <cite>WorkflowGraph</cite>.

Each node in the graph must have its `path` field set, pointing to
the model artifacts for that node. Per-node `tokenizer_path` and
`config_path` can be set on each <cite>WorkflowNode</cite>; if omitted,
convention-based discovery is used.

- Parameters

    - - **workflow** – <cite>WorkflowGraph</cite> whose nodes each carry a `path`
pointing to the model artifacts. A <cite>GenAIBuilder</cite> is created
for every node using <cite>GenAIBuilderFactory</cite>. Each node may
also carry `tokenizer_path` and `config_path` to override
convention-based artifact discovery for that node.
- **backend\_type** – The backend to use when creating each <cite>GenAIBuilder</cite>.
Defaults to <cite>BackendType.HTP</cite>.
- **cache\_root** – Shared root directory for build caches. Applied to
every node. Defaults to `None` (no caching).

- Returns

    - A <cite>WorkflowBuilder</cite> ready to call <cite>build()</cite> on.

- Raises

    - **ValueError** – If any node is missing a `path`, or if a
    <cite>GenAIBuilder</cite> cannot be created for any node.

# VisionEncoderBuilderHTP

`VisionEncoderBuilderHTP` builds single-pass vision encoder models for the HTP
backend. It is used as the `IMAGE_ENCODER` node of a multimodal workflow and is
typically created through [`create_vision_encoder()`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-gen-ai-builder-factory.html#qairt.gen_ai_api.gen_ai_builder_factory.GenAIBuilderFactory.create_vision_encoder).

HTP builder for single-pass vision encoder models.

- *class* qairt.gen\_ai\_api.builders.vision\_encoder\_builder\_htp.VisionEncoderBuilderHTP(*model\_path: str | os.PathLike*, *config: VisionEncoderConfig*, *cache\_dir: Optional[Union[str, PathLike]] = None*)

    - Bases: [`Buildable`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-builders.html#qairt.gen_ai_api.builders.buildable.Buildable), [`HTPMixin`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-builders-htp.html#qairt.gen_ai_api.builders.htp_mixin.HTPMixin)

Builds a [`VisionEncoderContainer`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-containers.html#qairt.gen_ai_api.containers.vision_encoder_container.VisionEncoderContainer)
for HTP execution.

The build pipeline is intentionally simple — no model splitting, no
AR/CL transformation, no KV cache, and no tokenizer:

ONNX  →  convert()  →  compile()  →  VisionEncoderContainer
    Copy to clipboard

Configuration is loaded from the `vision_config` sub-section of the
model’s `config.json` (the same file used by
[`GenAIBuilderHTP`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-builders-htp.html#qairt.gen_ai_api.builders.gen_ai_builder_htp.GenAIBuilderHTP)),
so both builders can share a single config file for a multimodal model.

Model-specific parameters (positional encoding, special token IDs, etc.)
are populated by the `_build_config()` hook, which subclasses override.
For Qwen2-VL / Qwen2.5-VL models use
`Qwen2VLVisionEncoderBuilderHTP`.

Example:

builder = VisionEncoderBuilderHTP.from_pretrained(
        "/path/to/vision_encoder.onnx",
        cache_root="/tmp/cache",
        config_path="/path/to/model/config.json",
    )
    builder.set_targets(["chipset:SC8380XP"])
    container = builder.build()
    container.save("/path/to/output/vision_encoder")
    Copy to clipboard

Key differences from `GenAIBuilderHTP`:

- No `ARn_ContextLengthConfig`
— the vision encoder is a single-pass feed-forward network with no
autoregressive loop.
- No `SplitModelConfig`
— the model is compiled as a single graph.
- No tokenizer, no vocabulary size, no BOS/EOS tokens.
- Returns [`VisionEncoderContainer`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-containers.html#qairt.gen_ai_api.containers.vision_encoder_container.VisionEncoderContainer)
instead of [`LLMContainer`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-containers.html#qairt.gen_ai_api.containers.llm_container.LLMContainer).
- Proceeds without quantization encodings when none are found (float32
base model is a valid use case).

- build() → [VisionEncoderContainer](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-containers.html#qairt.gen_ai_api.containers.vision_encoder_container.VisionEncoderContainer)

    - Build and return a `VisionEncoderContainer`.

Steps:

1. Validate that a DSP compilation target has been set.
2. Locate quantization encodings alongside the model (optional).
3. Apply the MHA→SHA rewrite via `HTPMixin.transform()` (no AR/CL
conversion, no splitting).
4. Convert the ONNX model to a QAIRT DLC via `HTPMixin.convert()`.
5. Compile the DLC to a context binary via `HTPMixin.compile()`.
6. Wrap in a `VisionEncoderContainer` and return.

- Returns

    - A `VisionEncoderContainer` ready to be saved or embedded
in a
[`WorkflowContainer`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-containers.html#qairt.gen_ai_api.containers.workflow_container.WorkflowContainer).

- Raises

    - **ValueError** – If no compilation target has been set.

- *property* encodings\_path*: Optional[Path]*

    - Path to the quantization encodings file, or `None`.

- *classmethod* from\_pretrained(*pretrained\_model\_path: str | os.PathLike*, *cache\_root: Optional[Union[str, PathLike]] = None*, *\**, *config\_path: Optional[Union[str, PathLike]] = None*, *config\_section: str = 'vision\_config'*, *grid\_height: Optional[int] = None*, *grid\_width: Optional[int] = None*) → [VisionEncoderBuilderHTP](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-builders.html#qairt.gen_ai_api.builders.vision_encoder_builder_htp.VisionEncoderBuilderHTP)

    - Create a builder by reading `config.json` from the model directory.

The vision-specific parameters are read from the sub-object identified
by *config\_section* (default `"vision_config"`) inside the top-level
`config.json`.  This is the same file used by
`GenAIBuilderHTP.from_pretrained()`, so both builders can share a
single config for a multimodal model.

If the key identified by *config\_section* is absent (e.g. a standalone
vision-only `config.json` that has the fields at the top level), the
top-level config object is used directly.

Model-specific parameters (positional encoding, special token IDs, etc.)
are populated by `_build_config()`, which subclasses override to
add model-specific logic.

- Parameters

    - - **pretrained\_model\_path** – Path to the ONNX model file or a directory
containing exactly one `.onnx` file.
- **cache\_root** – Optional root directory for caching build artifacts.
- **config\_path** – Explicit path to `config.json` or a directory
containing it.  When omitted the directory that contains
*pretrained\_model\_path* is searched.
- **config\_section** – Key inside `config.json` that holds the vision
encoder parameters.  Defaults to `"vision_config"`.

- Returns

    - A new [`VisionEncoderBuilderHTP`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-builders.html#qairt.gen_ai_api.builders.vision_encoder_builder_htp.VisionEncoderBuilderHTP) instance.

- Raises

    - **FileNotFoundError** – If *pretrained\_model\_path* does not exist.

- [GenAIBuilderHTP](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-builders-htp.html)
- [GenAIBuilderCPU](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-builders-cpu.html)

Last Published: Aug 19, 2026

[Previous Topic
SupportedLLMs.QWEN3\_MOE](https://docs.qualcomm.com/bundle/publicresource/80-87189-2/topics/qairt-gen-ai-api-gen-ai-builder-factory.md)