ONNX Converter and Optimization Tools

1.16.0 · active · verified Sun Apr 12

The `onnxconverter-common` package provides common functions and utilities for use in converters from various AI frameworks to ONNX. It also enables different converters to work together, such as converting a scikit-learn pipeline embedding an XGBoost model. It is actively maintained by Microsoft with frequent releases, often tied to ONNX and ONNX Runtime updates, focusing on compatibility and optimization.

Warnings

breaking Breaking changes in ONNX or ONNX Runtime can cause compatibility issues. Specifically, `v1.16.0` fixed an `onnx.mapping` reference for `onnx 1.19`, indicating tight coupling and potential breakage with unaligned ONNX versions.
Fix: Always install `onnxconverter-common` alongside compatible `onnx` and `onnxruntime` versions. Refer to the project's GitHub releases and ONNX Runtime compatibility matrix. Upgrade `onnxconverter-common` to the latest version to ensure compatibility with recent ONNX releases.
gotcha Specific `protobuf` versions have been critical dependencies, leading to conflicts. `v1.14.0` explicitly required `protobuf==3.20.2` due to security concerns, which often clashed with other libraries (e.g., TensorFlow) requiring different `protobuf` versions. While recent versions might be more flexible, `protobuf` version clashes remain a common footgun in the ONNX ecosystem.
Fix: Carefully manage `protobuf` versions in your environment. If encountering conflicts, try pinning `protobuf` to a version compatible with both `onnxconverter-common` and other major dependencies (e.g., `tensorflow`, `onnx`). Virtual environments are highly recommended.
gotcha Float16 (FP16) conversion can be complex and may introduce accuracy issues or runtime errors. Common problems include `SubGraph` bugs, incorrect operator ordering, `Cast` node issues, and failures with specific ops (e.g., `RandomUniformLike`, `Resize`). The tool might also log warnings about FP32 truncation.
Fix: When converting to FP16, always validate the converted model's accuracy and functionality. Utilize `convert_float_to_float16` arguments like `op_block_list`, `node_block_list`, and `keep_io_types` to fine-tune the conversion. Monitor for warning messages during conversion and check relevant GitHub issues for known limitations.
gotcha Models exceeding 2GB can hit Protobuf deserialization limits, leading to `ValueError: Message onnx.ModelProto exceeds maximum protobuf size of 2GB`. This is a limitation of the Protobuf format, not `onnxconverter-common` directly, but affects its usage with large models.
Fix: For models over 2GB, consider splitting the model, using external data storage for large tensors in ONNX, or exploring specific `onnxruntime` nightly builds or older `onnxruntime`/`onnxconverter-common` combinations that might have workarounds. The `auto_mixed_precision_model_path` function might help with large models.

Install

pip install onnxconverter-common Install stable version

Imports

convert_float_to_float16
```
from onnxconverter_common import float16
model_fp16 = float16.convert_float_to_float16(model)
```
This is the primary function for converting an ONNX model to float16 precision.
onnx_ops
```
from onnxconverter_common import onnx_ops
```
Provides common ONNX operator utilities for graph manipulation.

Quickstart

This quickstart demonstrates how to use `onnxconverter-common` to convert an ONNX model from float32 to float16 precision. This is a common optimization to reduce model size and potentially improve inference performance on compatible hardware. It creates a dummy ONNX model, converts it, and saves the result.

import onnx
from onnxconverter_common import float16
import os

# Create a dummy ONNX model for demonstration
# In a real scenario, you would load your model: model = onnx.load("path/to/model.onnx")

# Example: A simple Add operation
nodes = [onnx.helper.make_node("Add", ["input1", "input2"], ["output"]) ]
graph = onnx.helper.make_graph(
    nodes,
    "simple-graph",
    [
        onnx.helper.make_tensor_value_info("input1", onnx.TensorProto.FLOAT, [None, 2]),
        onnx.helper.make_tensor_value_info("input2", onnx.TensorProto.FLOAT, [None, 2]),
    ],
    [
        onnx.helper.make_tensor_value_info("output", onnx.TensorProto.FLOAT, [None, 2]),
    ],
)
model_fp32 = onnx.helper.make_model(graph, producer_name="onnx-example")

# Convert the model to float16
model_fp16 = float16.convert_float_to_float16(model_fp32)

# Save the converted model
output_path = "dummy_model_fp16.onnx"
onnx.save(model_fp16, output_path)
print(f"FP32 model converted to FP16 and saved to {output_path}")

# Clean up the dummy file
os.remove(output_path)

view raw JSON →