feat: add MobiusModelBuilder Olive pass for mobius-backed ONNX export

[justinchuby]

Summary

Adds a new Olive pass (MobiusModelBuilder) that wraps mobius build() to produce ONNX models from HuggingFace model IDs.

• Single-component models (LLMs) → ONNXModelHandler
• Multi-component models (VLMs, encoder-decoders) → CompositeModelHandler
• EP auto-detected from Olive accelerator spec (cpu/cuda/dml/webgpu)
• Precision: fp32 (default), fp16, bf16
• Registered in olive_config.json as MobiusModelBuilder
• Example pipeline config: examples/gemma4/gemma4_int4_cuda.json
• 14 unit tests covering single/multi-component, EP detection, and error cases

Validated: Gemma4 INT4 Quantization Pipeline

Successfully tested MobiusModelBuilder → OnnxBlockWiseRtnQuantization on google/gemma-4-E2B-it:

Quantized ops per component

Component	Total nodes	MatMulNBits	GatherBlockQuantized	Other ops
decoder	1,277	277	39	961
audio	1,465	135	0	1,330
vision	1,488	114	66	1,308
embedding	24	0	1	23

Weight quantization coverage

Component	Quantized (UINT8/INT4)	Non-quantized (FP16)	% quantized by size
decoder	316 tensors (2.4G elements)	585 tensors (71M elements)	97%
audio	135 tensors (154M elements)	768 tensors (2.8M elements)	98%
embedding	1 tensor (201M elements)	4 tensors (3.1M elements)	98%
vision	147 tensors (90M elements)	698 tensors (1.7M elements)	98%

Output structure (2.8GB total, down from ~5GB fp16)

models/gemma4-e2b-int4-cuda/
├── decoder.onnx      (853K) + decoder.onnx.data   (2.4G)
├── audio.onnx        (1.2M) + audio.onnx.data     (152M)
├── embedding.onnx    (8.5K) + embedding.onnx.data  (199M)
├── vision.onnx       (1.2M) + vision.onnx.data     (89M)
└── model_config.json

Pipeline timing

Pass	Time
MobiusModelBuilder (fp16 build)	77s
OnnxBlockWiseRtnQuantization (int4)	129s
Total	~3.5 min

[Copilot]

Pull request overview

Adds a new ONNX pass (MobiusModelBuilder) that uses the mobius package to build ONNX models directly from HuggingFace model IDs, returning either a single ONNXModelHandler or a CompositeModelHandler for multi-component exports.

Changes:

• Introduces olive/passes/onnx/mobius_model_builder.py implementing the new pass (EP mapping, precision mapping, trust_remote_code passthrough).
• Registers the pass in olive/olive_config.json and adds two Gemma4 example run configs.
• Adds unit tests for single-component, multi-component, EP selection, and error paths.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
olive/passes/onnx/mobius_model_builder.py	New pass wrapping mobius.build() and emitting Olive model handlers.
olive/olive_config.json	Registers MobiusModelBuilder and declares extras for its dependencies.
examples/gemma4/gemma4_int4_pipeline.json	Example pipeline: mobius export (fp16 CUDA) then INT4 quantization.
examples/gemma4/gemma4_fp32_cpu.json	Example pipeline: mobius export (fp32 CPU).
test/passes/onnx/test_mobius_model_builder.py	New unit tests for config, handler types, EP mapping, and missing dependency behavior.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

[jambayk]

we could create an enum of the supported eps for automatic validation like in

Olive/olive/passes/pytorch/autoawq.py

Line 27 in 8b1957e

class ModelDtype(StrEnumBase):

.
unless you think the options might keep growing and it would be hard to keep it in sync across versions

[justinchuby]

Done.

[xiaoyu-work]

will mobius generate genai_config.json and related files for ort genai? Also, does mobius support customized naming for different component for multi components model? I can see all component models are named as "model.onnx"

[justinchuby]

@xiaoyu-work The models are <component_name>/model.onnx. Is it good enough or are there cases when we want a flat layout / renamed models?

[devang-ml]

Incorrect URL

[justinchuby]

Fixed

[devang-ml]

We should not have pass level execution provider user choices.
The Olive engine is running a series of passes and user selects the EP for a given engine run.

[devang-ml]

See another relevant comment below _run_for_config

[Copilot]

The execution_provider pass config param has been removed. The pass now uses only the Olive accelerator spec EP, and raises a ValueError if that EP is not supported by mobius. This was addressed in 8efcec5.

[titaiwangms]

Nice work! A few suggestions from our experience building the Ministral-3 VLM recipe on top of mobius:

1. Per-component VLM quantization guidance
For VLMs, downstream quantization needs differ per component: decoder → INT4, vision → INT8, embedding → none (ORT has a Gather rank-1 bug with GatherBlockQuantized that prevents embedding quantization). It would be helpful to document how recipe authors should wire per-component quantization after CompositeModelHandler. Even a brief note in the docstring would save people time.

2. context_length default may be too small
write_ort_genai_config() defaults context_length to 4096, but models like Ministral-3 need 262144 for full YaRN RoPE cache. Consider reading max_position_embeddings from the HF config automatically, or exposing it as a pass config parameter.

3. Minimum mobius version check (minor)
If a user has an older mobius without support for newer model types (e.g., Pixtral), they would get confusing errors from mobius.build(). A version check or clearer error message would help.

4. Migration example (nice-to-have)
Existing recipes manually call mobius.build() + write_ort_genai_config(). A brief before/after example showing how to replace that with MobiusModelBuilder pass would help adoption.

Overall this is clean and well-tested — excited to migrate our recipe to use this once it lands!

[justinchuby]

@xiaoyu-work how should we handle per component quantization with Olive?

[justinchuby]

@xiaoyu-work Thanks for the question!

genai_config.json generation: Yes, we've just added support for this. The pass now calls `_write_genai_config()` which generates all ORT GenAI artifacts (genai_config.json, tokenizer files, processor configs) and includes them in the model handler's `additional_files`. This happens automatically when `runtime='ort-genai'` (the default).

Multi-component naming: Correct, mobius uses the flat `<component_name>/model.onnx` layout (e.g., `decoder/model.onnx`, `vision_encoder/model.onnx`). This is what ORT GenAI expects. The pass returns a `CompositeModelHandler` with each component's directory as the model path, so the structure is preserved.

[justinchuby]

@titaiwangms Great feedback! Addressing each point:

1. Per-component VLM quantization guidance
This is important. The `CompositeModelHandler` structure makes this straightforward — each component is a standalone `ONNXModelHandler` with its own model path, so recipe authors can wire per-component quantization passes. We'll add a docstring note with a brief example (e.g., decoder → INT4, vision → INT8, embedding → skip).

2. context_length / max_position_embeddings
Good catch! We've verified that `write_ort_genai_config()` already handles this automatically — it reads `max_position_embeddings` from the HF config and takes `max(context_length, max_position_embeddings)`. So Ministral-3 and similar models with large rope should already work without manual intervention. No config parameter needed!

3. Minimum mobius version check
Valid concern. For now, users hitting old mobius versions will see mobius's own errors. We can add a version check in a follow-up if needed.

4. Migration example
Will add a docstring example showing the before/after. Quick version:

```

Before: manual mobius.build()

from mobius import build
pkg = build('model-id', load_weights=True)
pkg.save('output')
write_ort_genai_config(pkg, 'output', hf_model_id='model-id')

After: MobiusModelBuilder pass

Just put {'type': 'MobiusModelBuilder', 'precision': 'fp32'} in your Olive config!

```

Thanks for the thorough review — these notes will help adoption!

[justinchuby]

@xiaoyu-work @justinchuby Regarding per-component quantization:

With `CompositeModelHandler`, you can wire different passes per component by targeting them in the pipeline config. Here's the pattern:

```json
{
"passes": {
"mobius": {"type": "MobiusModelBuilder", "precision": "fp16"},
"quantize_decoder": {
"type": "OnnxBlockWiseRtnQuantization",
"bits": 4,
"nodes_to_exclude": [...]
}
}
}
```

Then the Olive engine will:

1. Run MobiusModelBuilder → CompositeModelHandler with components [decoder, vision, embedding, audio]
2. Run quantize_decoder on each component separately

For selective per-component quantization (e.g., skip embedding), you'd use `nodes_to_exclude` or create separate configs per component. We can document this pattern in the pass docstring to make it clearer.

The architecture here is that each pass is component-agnostic; the engine applies it to all components in the composite. For more granular control, recipes can create separate Olive config variants (one per component, or one per quantization strategy).