Edit

Build configuration

Use winml config to generate a WinMLBuildConfig JSON file for your model and target. The generated file is the starting point for editing settings; defaults and available fields can change between CLI versions.

winml config -m .\model.onnx --device cpu --ep cpu --precision fp32 --no-quant --no-compile -o .\build_config.json
winml build -c .\build_config.json -m .\model.onnx -o .\output --no-quant --no-compile

config -o names a JSON file, while build -o names an output directory. A configuration doesn't necessarily store the source model path, so supply -m when replaying a build.

Top-level structure

An unquantized, uncompiled ONNX workflow can use this configuration:

{
  "export": null,
  "optim": {},
  "quant": null,
  "compile": null
}
Section Purpose
loader Select the source task, model class/type, and loading behavior for a supported Hugging Face model.
export Configure ONNX export and input/output specifications. null represents an already-exported ONNX input.
optim Configure graph transformation capabilities.
quant Configure precision conversion or quantization; null skips this stage.
compile Configure EP compilation; null skips this stage.
eval Optional evaluation settings for workflows that consume them. Run winml eval explicitly when validating a build.
auto Enable automatic configuration; omitted when using the default true.
skip_optimize Skip optimization when explicitly enabled.

Preview conversion workflows can add other fields. Don't copy preview-specific settings into a standard ONNX build without meeting that workflow's prerequisites.

Loader and export

Common loader fields include task, model_class, model_type, module_path, and trust_remote_code. Only enable remote code for a model repository you trust.

Export settings include:

Field Purpose
opset_version Requested ONNX operator-set version. Inspect the exported graph if an exporter reports a different version.
batch_size Static example batch size.
input_tensors, output_tensors Named tensor specifications including dtype and shape.
dynamic_axes Map tensor dimensions to symbolic names, where supported.
dynamo Select the TorchDynamo exporter instead of the default TorchScript exporter.
enable_hierarchy_tags Preserve source module hierarchy in node metadata.
compatibility Resolved model/export compatibility settings.

An input tensor specification can include name, dtype, shape, and value_range. Use the generated model-specific inputs rather than assuming every text or vision model accepts the same names and types.

Optimization

optim contains registered capability settings. Use winml optimize --list-capabilities and --list-rewrites to discover the installed version's names and defaults. Settings are not all disabled by default.

Use the analyzer's recommended optimizer configuration or edit a generated build configuration. Don't assume an optimizer-only configuration file is interchangeable with the complete build configuration.

Quantization and precision conversion

quant.mode selects static, dynamic, rtn, or fp16. The older qdq mode name is accepted as a compatibility alias for static; prefer the current names in new configurations.

Field Applies to
weight_type, activation_type Integer types for applicable quantization modes.
task, model_id, dataset_name Task-aware calibration data and preprocessing.
samples, calibration_method Static calibration sample count and range estimation.
per_channel, symmetric Quantization granularity and symmetry.
weight_symmetric, activation_symmetric Optional per-target symmetry overrides.
nodes_to_exclude, op_types_to_quantize Graph selection for applicable quantization modes.
reduce_range Reduced weight range for dynamic quantization.
rtn_bits, rtn_block_size, rtn_symmetric RTN weight-only settings.
fp16_keep_io_types, fp16_op_block_list FP16 conversion controls.

For the normal CLI workflow, select precision with winml quantize --precision rather than manually constructing every field. See Quantize command.

Compilation

The JSON compile section stores the provider under execution_provider. The serialized keys differ from the internal Python configuration object's attributes:

{
  "compile": {
    "execution_provider": "qnn",
    "device": "npu",
    "compiler": "ort",
    "enable_ep_context": true,
    "embed_context": false,
    "provider_options": {},
    "validate": true
  }
}

This is a compile-section example, not a complete build recipe. Generate the complete configuration with winml config --compile for the intended model and target.

Available compiler backends include ort, ort_session, and qairt; requirements differ. provider_option_file_keys identifies provider options whose values are input files so path resolution and cache identity account for them. qnn_sdk_root identifies the QAIRT SDK when required.

Reuse and overrides

build reads the complete configuration. Commands such as export, analyze, quantize, and compile accept -c for their supported sections; not every command accepts the same configuration file format.

Explicit CLI options take precedence where supported. Use --overwrite to replace an existing generated config, and --rebuild to rerun a build into existing artifacts. Review the resulting configuration after changing target, precision, or model revision.

See also

  • Last updated on